Affix
在滚动时固定关键导航或操作。中文惯用名：固钉。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.affix |
| 名称 | Affix |
| 二级分类 | 导航（navigation） |
| 用途 | 在滚动时固定关键导航或操作 |
| 描述 | 中文惯用名：固钉。 |
预览
静态结构：<div data-slot="affix">（sticky z-10）；offsetTop（默认 0）内联 top，offsetBottom 提供时优先、内联 bottom（二者同 antd 互斥语义）；子节点经 Renderer children 机制渲染 DSL 子树。吸附在其最近滚动祖先内生效，本预览为静态形态（无滚动上下文时等同普通块）。
DSL 结构
{
"type": "Affix",
"props": {
"offsetTop": 72
},
"children": [
{
"type": "Button",
"props": {
"text": "吸顶操作区"
}
}
]
}何时用
何时使用
- 滚动时固定关键导航或操作：页面头部、章节工具条、底部操作栏。
- 长表单底部提交栏常驻：offsetBottom 吸附视口底部。
- 右侧辅助栏（Anchor / 目录）跟随滚动固定。
何时不用
- 页面级固定骨架（整站头 / 侧栏）：用 Layout 的固定区域而非 Affix。
- 需要悬浮于内容之上且不占位：Affix 是 sticky（占位吸附），悬浮用 fixed 定位的自定义容器。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 顶部吸附 | sticky top = offsetTop | 章节工具条、表头、右侧目录 |
| 底部吸附 | sticky bottom = offsetBottom | 长表单提交栏 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
offsetTop | number | 0 | 距离视口顶部偏移（像素）；与 offsetBottom 互斥 |
offsetBottom | number | — | 距离视口底部偏移（像素）；提供时按底部吸附 |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式（与偏移合并） |
使用规范
- 吸附元素背景需不透明（卡片 / 页面底色），避免滚动内容透出。
- 顶部已有固定头部时 offsetTop 设为头部高度，避免叠盖。
- 同方向吸附最多一处，多处吸附互相遮挡。
正例
- ✓ 长表单页：底部操作栏 offsetBottom: 0 吸附，随时可提交。
- ✓ 文档页：右侧 Anchor 外套 Affix（offsetTop = 头部高度）。
反例
- ✕ 用 Affix 实现整站固定头部（应使用 Layout 固定区域）。
- ✕ 吸附内容高度超过一屏（sticky 失去意义且遮挡内容）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。