Anchor 锚点
Anchor 是一个跟随滚动的目录,比如页面右侧的「本页目录」。每个链接通过 #id 指向页面上的一个元素;最后滚动到的目标对应的链接是当前链接,带有 aria-current="location"。点击链接会把目标滚动到视图中(平滑滚动,用户偏好减少动态效果时直接跳转),并把 hash 写进地址栏,不会触发浏览器的跳动。
演示
基础用法
用 items 树传入链接。offsetTarget 指定滚动的元素;不设置时跟随整个页面。面板滚到底以后,视图中的最后一节即使到不了顶部也会成为当前链接。
AnchorLink
用组合的方式写同样的目录:在 Anchor 下嵌套 AnchorLink。
轨道和背景
showRail 显示轨道,并在当前链接旁做标记;showBackground 给当前链接加上底色。
块状
type="block" 不显示轨道,把当前链接整块高亮。
忽略间隙
这里的目标是标题,标题之间有空白。默认只有标题在顶部时对应的链接才是当前链接;设置 ignoreGap(左侧)后,最后经过的标题在空白处仍保持为当前链接。
受控
value 设置当前链接,onUpdateValue 回传每一次变化,无论来自滚动还是点击。
Anchor Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
items | AnchorItem[] | undefined | 树形的链接数据。AnchorLink 子元素渲染在它们之后。 | 未发布 |
value | string | null | undefined | 当前链接的 href。设置后为受控模式。 | 未发布 |
defaultValue | string | null | null | 非受控时的初始当前链接。 | 未发布 |
onUpdateValue | (value: string | null) => void | undefined | 当前链接变化时回传新的 href,滚动和点击都会触发。 | 未发布 |
type | rail | block | rail | 当前链接的标记方式。 | 未发布 |
showRail | boolean | true | 显示轨道(仅 rail 类型)。 | 未发布 |
showBackground | boolean | true | 给当前链接加底色(仅在显示轨道时)。 | 未发布 |
bound | number | 12 | 目标距容器顶部多少 px 以内算作到达。从目标的 scroll-margin-top 算起,所以给吸顶头部留出的 margin 也会移动这条线。 | 未发布 |
ignoreGap | boolean | false | 在两个目标之间保持最后到达的链接为当前链接。 | 未发布 |
offsetTarget | string | HTMLElement | Window | Document | RefObject | (() => HTMLElement | Window | Document | null) | window | 目标所在的滚动容器:选择器、元素、ref 或函数。 | 未发布 |
aria-label | string | 语言包 Anchor.label | nav 区域的名称(「本页目录」)。 | 未发布 |
AnchorLink Props
| 名称 | 类型 | 默认值 | 说明 | 版本 |
|---|---|---|---|---|
href | string | 目标,写作 #id。 | 未发布 | |
title | ReactNode | undefined | 链接文字。字符串标题被截断时也会作为提示显示。 | 未发布 |
children | ReactNode | undefined | 嵌套的 AnchorLink。 | 未发布 |
AnchorItem 为 { href: string; title: ReactNode; key?: Key; children?: AnchorItem[] }。
当前链接可以受控(value),点击时替换 hash 而不是跳转,目录不会每点一次就新增一条历史记录。要让锚点留在屏幕上,把它放进 position: sticky 的元素里;要跳到某个链接,设置 value 或自行滚动目标。