Affix 固钉

将页面元素钉在可视区域。常用于侧边目录、操作栏、工具条等需要常驻视野的场景。

基本使用

相对顶部 0px 固定，滚动到阈值后元素贴住顶部。下面在一个可滚动容器内演示效果（页面本身带固定导航，直接相对窗口顶部 0px 固定会被导航遮住，故用容器演示）。

偏移量 offsetTop

通过 offset-top 设置距顶部固定的距离。多个固定元素错开摆放。

固定到底部 offsetBottom

offset-bottom 把元素固定在视口底部，常用于「返回顶部」、底部操作栏。

监听固定状态变化

通过 change 事件感知是否进入/退出固定状态，可联动展示阴影、收起等。

在滚动容器中

通过 target 指定一个可滚动的父容器（CSS 选择器或 DOM 元素返回函数），固钉相对容器边界进行计算。

自定义层级 zIndex

默认 z-index: 10；当页面里有 Drawer / Modal（更高 z-index）时按需调高，确保固钉不被遮罩盖住。

多个 Affix 错开

工具栏吸顶 + 二级筛选条吸顶，靠 offsetTop 错开高度，构成「双层 sticky」效果。

表格工具栏吸顶

后台管理页常见：表格行很长，工具栏（搜索 / 新建 / 批量操作）始终可达。

章节锚点目录

侧边目录 sticky，配合右侧主内容滚动，是长文档 / 商品详情页常用排版。

容器内 vs 全局对比

并列展示「以 window 为参照」和「以容器为参照」两种模式，便于业务侧理解 target 的影响范围。

API

Props

参数	类型	默认值	说明
offsetTop	number	0	距离窗口（或目标容器）顶部多少像素后开始固定。offsetBottom 未传时启用顶部模式
offsetBottom	number	undefined	距离窗口（或目标容器）底部多少像素后开始固定。设置该值则忽略 offsetTop
target	string | HTMLElement | () => HTMLElement | Window | null	window	滚动容器。可传 CSS 选择器、DOM 节点或返回 DOM 节点的函数
zIndex	number	10	固定时元素的 z-index

Events

事件名	回调签名	触发时机
change	(fixed: boolean)	固定状态变化（进入/退出固定）

注意事项

• c-affix 内部用一个占位元素保持原始位置和尺寸，固定时把内容切换为 position: fixed。所以父容器不要给固钉外层加 transform，会让 position: fixed 失效。
• 如果固定后宽度异常，请检查父级是否使用 display: flex 等会改变子元素宽度计算的布局。