跳到正文

Anchor 锚点

Anchor 是一个跟随滚动的目录,比如页面右侧的「本页目录」。每个链接通过 #id 指向页面上的一个元素;最后滚动到的目标对应的链接是当前链接,带有 aria-current="location"。点击链接会把目标滚动到视图中(平滑滚动,用户偏好减少动态效果时直接跳转),并把 hash 写进地址栏,不会触发浏览器的跳动。

演示

基础用法

用 items 树传入链接。offsetTarget 指定滚动的元素;不设置时跟随整个页面。面板滚到底以后,视图中的最后一节即使到不了顶部也会成为当前链接。

用组合的方式写同样的目录:在 Anchor 下嵌套 AnchorLink。

轨道和背景

showRail 显示轨道,并在当前链接旁做标记;showBackground 给当前链接加上底色。

块状

type="block" 不显示轨道,把当前链接整块高亮。

忽略间隙

这里的目标是标题,标题之间有空白。默认只有标题在顶部时对应的链接才是当前链接;设置 ignoreGap(左侧)后,最后经过的标题在空白处仍保持为当前链接。

受控

value 设置当前链接,onUpdateValue 回传每一次变化,无论来自滚动还是点击。

Anchor Props

名称类型默认值说明版本
itemsAnchorItem[]undefined树形的链接数据。AnchorLink 子元素渲染在它们之后。未发布
valuestring | nullundefined当前链接的 href。设置后为受控模式。未发布
defaultValuestring | nullnull非受控时的初始当前链接。未发布
onUpdateValue(value: string | null) => voidundefined当前链接变化时回传新的 href,滚动和点击都会触发。未发布
typerail | blockrail当前链接的标记方式。未发布
showRailbooleantrue显示轨道(仅 rail 类型)。未发布
showBackgroundbooleantrue给当前链接加底色(仅在显示轨道时)。未发布
boundnumber12目标距容器顶部多少 px 以内算作到达。从目标的 scroll-margin-top 算起,所以给吸顶头部留出的 margin 也会移动这条线。未发布
ignoreGapbooleanfalse在两个目标之间保持最后到达的链接为当前链接。未发布
offsetTargetstring | HTMLElement | Window | Document | RefObject | (() => HTMLElement | Window | Document | null)window目标所在的滚动容器:选择器、元素、ref 或函数。未发布
aria-labelstring语言包 Anchor.labelnav 区域的名称(「本页目录」)。未发布
名称类型默认值说明版本
hrefstring目标,写作 #id。未发布
titleReactNodeundefined链接文字。字符串标题被截断时也会作为提示显示。未发布
childrenReactNodeundefined嵌套的 AnchorLink。未发布

AnchorItem 为 { href: string; title: ReactNode; key?: Key; children?: AnchorItem[] }。

当前链接可以受控(value),点击时替换 hash 而不是跳转,目录不会每点一次就新增一条历史记录。要让锚点留在屏幕上,把它放进 position: sticky 的元素里;要跳到某个链接,设置 value 或自行滚动目标。