Anchor
在长页面章节间定位。中文惯用名：锚点。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.anchor |
| 名称 | Anchor |
| 二级分类 | 导航（navigation） |
| 用途 | 在长页面章节间定位 |
| 描述 | 中文惯用名：锚点。 |
预览
静态结构：<nav data-slot="anchor">（border-l 轨道 + 链接列）；链接 <a data-slot="anchor-link">（-ml-px border-l-2，激活项 border-primary text-primary font-medium，未激活 text-muted-foreground），子链接缩进 pl-4。交互：点击阻止默认跳转、按 offsetTop 补偿平滑滚动；监听 window 滚动做 scroll-spy（取最后一个顶部越过 offsetTop 的章节）。状态控制：非受控（未传 activeKey）内部维护激活态；受控时激活态完全由 activeKey 驱动，点击 / 滚动定位仅经 onChange 上报 href（去重：与当前激活项相同或挂载对齐计算不重复触发）。本预览无对应锚点目标，仅演示结构与激活态。
DSL 结构
{
"type": "Anchor",
"props": {
"items": [
{
"href": "#sec-basic",
"title": "基础信息"
},
{
"href": "#sec-log",
"title": "操作日志"
}
],
"offsetTop": 72
}
}何时用
何时使用
- 长页面章节间定位：文档、详情页、设置页的右侧章节目录。
- 需要 scroll-spy 同步阅读位置：滚动时自动高亮当前章节。
- 两级以内的章节树：items 支持 children 嵌套。
何时不用
- 跨页面导航：使用 Menu / NavigationMenu。
- 页面内返回顶部：使用 BackTop。
- 短页面（一屏内）不需要 Anchor。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 单层 | 平铺章节链接 | 章节无层级的文档 |
| 嵌套 | 子链接缩进 | 两级章节树（章 / 节） |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
items | AnchorItemData[] | [] | 锚点链接：{ href: "#id", title, children? } |
activeKey | string | — | 受控：当前激活链接 href；提供时激活态完全由外部驱动 |
onChange | event | — | 激活项变化（点击或滚动定位），传出 href（events.onChange 绑定动作，${event} 取 href） |
offsetTop | number | 0 | 滚动定位的顶部偏移（如有固定头部） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- href 与页面章节 id 一一对应，缺失目标时点击为空操作（onChange 仍上报）。
- 有固定头部时务必设 offsetTop，避免目标被遮挡。
- 章节数控制在 10 个以内，层级不超过两级。
- 常配合 Affix 固定在页面右侧栏。
- 需要与外部状态联动（如路由 / Tab 同步）时用 activeKey + onChange 受控；纯阅读定位用非受控即可。
正例
- ✓ 文档详情页：右侧 Affix 固定 Anchor，scroll-spy 跟随阅读进度高亮。
- ✓ 长设置页：基础设置 / 安全设置 / 通知设置三章快速定位。
反例
- ✕ 用 Anchor 做站点主导航（应使用 Menu）。
- ✕ 锚点目标 id 动态变化却不更新 items（点击落空）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。