Affix 固钉
Rue 的 Affix 是一个纯行为组件:它不替 child 决定外观,只负责在合适的滚动边界上把节点吸附到顶部或底部。 支持 top / bottom 偏移、自定义 target、状态回调,以及 root 与 fixed 两层样式钩子,API 尽量保持直观,视觉仍然交给 Rue 自己的内容块来完成。
适合卡片、输入条、操作栏、摘要 rail 等任意自定义内容。
既能做右侧工具条,也能做评论回复区或提交操作条。
默认跟随整页 window 滚动;需要局部容器吸附时,再显式传 target。
# 默认全局 window 吸附
不传 target 时直接跟随整页滚动,适合页面级工具条、长表单页头和跨 section 操作条。
这个示例不传 target,直接使用 Affix 的默认全局 window 语义。继续向下滚动整页,再回滚回来,可以看到它进入吸附后也会正确恢复原位。
Viewport Brief
默认不传 target 时,Affix 会直接跟随整页 window 滚动,适合长表单页头、全局过滤条和跨 section 的操作卡。
Page Cadence
这个示例故意保持普通页面流布局,不放进内部滚动容器里,便于直接观察默认 window 吸附。
Release Handoff
继续往下滚再回滚,可以直接看到 Affix 退出 fixed 后恢复原位,不会停留在漂移状态。
# 顶部吸附 rail
在自定义面板里固定右侧摘要或快捷操作,是 Affix 最常见的用法。
Signal Map
把长页面拆成几段有明确职责的内容卡片,Affix 用来把关键操作或摘要固定在读者视线附近。
Cadence Plan
随着内容区向下滚动,右侧 rail 会在自定义面板顶部吸附,保持筛选与摘要稳定可见。
Handoff Brief
Affix 本身是透明行为层,适合叠在卡片、工具条、输入区、审批面板等各种 Rue 风格块上。
在长内容里把摘要、过滤器和快速动作固定到容器顶部,比始终占据正文宽度更稳妥。
# 底部吸附操作条
适合讨论串、工单详情或移动端表单,把回复和提交动作留在视线底部。
先把本轮访谈的三个核心异议归并成一个摘要卡,底部回复区保持在阅读终点附近。
当内容接近底部时,把回复工具条固定在容器下沿,比始终占着顶部空间更适合讨论串。
视觉上还是维持 Rue 自己的圆角卡片和轻阴影,不去照搬其它库的纯线框感。
底部吸附最适合评论框、批量提交条或者移动端的确认操作区,直接支持。
我们还需要验证 fixed 释放时基础的内联 style 会不会残留,这类问题在行为组件里很常见。
如果 target 不传,就默认监听 window;但示例 里最好还是用局部面板,避免预览互相干扰。
# 状态回调与样式槽
用 onChange 感知 fixed 状态翻转,并通过 root / fixed 两层样式槽继续定制。
Scroll a bit first
先让工具条处于正常流中,滚动到它越过容器顶部之后再观察状态面板的切换。
Intake Review
先看输入质量,再决定是否进入下一阶段。这里故意把工具条放在内容中段,用于观察 onChange 的切换时机。
Prototype Review
工具条吸附后,仍然展示基础宽度和左侧坐标,适合栅格内部的过滤器和子导航。
Closeout
这一段用于拉长容器高度,确保滚动过程中可以多次观察进入和退出固定态。
对透明行为组件来说,root 和 fixed 两层语义槽足够覆盖大部分定制,不需要额外再分拆更多结构。
API
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
offsetTop | 触发顶部吸附的偏移。若 offsetTop 和 offsetBottom 都未传,则默认按 0 处理。 | number | 0 |
offsetBottom | 触发底部吸附的偏移,适合回复区、提交条和移动端底部操作。 | number | - |
target | 返回滚动监听目标;不传时默认监听 window。需要绑定局部 panel、drawer 或侧栏时再显式传入对应容器。 | () => HTMLElement | Window | null | undefined | window |
onChange | fixed 状态切换时触发,参数为当前是否处于吸附状态。 | (affixed?: boolean) => void | - |
className / style | 作用在实际固定节点上,适合调整阴影、边框、背景和过渡。 | string / CSSProperties | - |
rootClassName | 作用在占位根节点上,通常用于布局或占位容器的额外类名。 | string | - |
classNames / styles | 分别定制 root 与 fixed 两层语义槽。 | { root?: string; fixed?: string } / { root?: style; fixed?: style } | - |
children | 任意可渲染内容。Affix 自身只负责定位,不决定视觉外观。 | any | - |