70 lines
3.8 KiB
JSON
70 lines
3.8 KiB
JSON
{
|
||
"slug": "anchornav",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "锚点目录：items 的 key 对应页面元素 id，滚动时自动高亮当前章节，点击平滑滚动。",
|
||
"usage": [
|
||
"React 端把导航与页面元素绑定在 id 上：items=[{key,label,children}] 的 key 必须是页面上已存在的元素 id（AnchorNav.jsx:10,19）。",
|
||
"点击滚动用 scrollTo 加 offset 修正，避免被吸顶栏遮挡（AnchorNav.jsx:18-21）。",
|
||
"高亮是滚动驱动的：监听 window scroll 后按 window.scrollY + 80 找出当前章节，卸载时移除监听（AnchorNav.jsx:22-34）。",
|
||
"支持两级嵌套：children 渲染在 kole-anchor-sub 里，父项与子项都能被高亮（AnchorNav.jsx:41-47）。",
|
||
"fixed 只加一个 fixed 类，定位方式由 CSS 决定（AnchorNav.jsx:13,37）。",
|
||
"激活项的初始值是 items 第一项的 key（AnchorNav.jsx:16）。"
|
||
],
|
||
"bestPractices": [
|
||
"key 与页面 id 必须严格一致，findElementById 找不到就静默不滚动，排查时先确认 DOM 里有没有这个 id。",
|
||
"offset 默认 24，页面上有吸顶导航时应传入吸顶高度，否则标题会被压在栏下（AnchorNav.jsx:13,20）。",
|
||
"滚动监听里的高亮判定用了 +80 的固定偏移，长页面若章节很多需注意与 offset 的取值配合。",
|
||
"items 为空时 allKeys 为空数组，active 初始为 undefined，不会报错但也没有任何高亮。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端的 API 载体是 props 与回调：属性驱动外观（type/size/disabled 等布尔与枚举），交互经 onXxx 回传（如 onChange/onClick/onSelectionChange）；没有 v-model，受控组件固定写成 value + onChange，非受控则用 defaultValue。",
|
||
"table": [
|
||
{
|
||
"name": "items",
|
||
"type": "Array<{ key, label, children? }>",
|
||
"desc": "目录数据，key 需对应页面元素 id"
|
||
},
|
||
{
|
||
"name": "fixed",
|
||
"type": "boolean",
|
||
"desc": "是否附加 fixed 类"
|
||
},
|
||
{
|
||
"name": "offset",
|
||
"type": "number",
|
||
"desc": "滚动偏移量，用于避开吸顶高度，默认 24"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"外层是 <nav className=\"kole-anchor\">，有导航语义但无 aria-label（AnchorNav.jsx:37）。",
|
||
"每一项都是原生 button（AnchorNav.jsx:40,44），键盘可达、可 Enter 激活，是本组件无障碍做得较好的一面。",
|
||
"当前章节只有 is-active 类，缺少 aria-current=\"location\" 之类的语义标注。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/AnchorNav.jsx",
|
||
"kind": "React（React）",
|
||
"desc": "React 端组件实现源码，props 与回调的唯一定义处"
|
||
},
|
||
{
|
||
"file": "frameworks/AnchorNav.css",
|
||
"kind": "样式",
|
||
"desc": "该 React 实现依赖的样式文件"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"anchornav-ex-1"
|
||
],
|
||
"notes": [
|
||
"frameworks/AnchorNav.jsx:9 中可指到 items（Array<{ key, label, children? }>）——目录数据，key 需对应页面元素 id",
|
||
"frameworks/AnchorNav.jsx:10 中可指到 fixed（boolean）——是否附加 fixed 类",
|
||
"frameworks/AnchorNav.jsx:11 中可指到 offset（number）——滚动偏移量，用于避开吸顶高度，默认 24",
|
||
"props 解构清单见 frameworks/AnchorNav.jsx:13-13；本文件 table 只列该端真正消费的属性与回调。",
|
||
"过滤口径：事实包 consumedApi 里还包含绑在组件内部节点上的同名处理器（如 onClick/onChange 绑在内部 button、input、checkbox 上，见 frameworks/AnchorNav.jsx 全文），它们不是对外 props，因此未进 table。",
|
||
"table 构成核验：3 行中 3 行是 frameworks/AnchorNav.jsx 解构出的顶层 props（解构块 frameworks/AnchorNav.jsx:13-13）；本组件 table 全部为顶层 props。"
|
||
]
|
||
}
|