Anchor 页内目录

页内目录，随滚动标出当前所在的小节。

简介

滚动此区域，右侧条目随之更新。

安装

滚动此区域，右侧条目随之更新。

用法

滚动此区域，右侧条目随之更新。

import { Anchor, Heading, Inline, ScrollArea, Section, Text } from '@hina-ui/react'

const sections = [
  { id: 'hero-intro', label: '简介' },
  { id: 'hero-install', label: '安装' },
  { id: 'hero-usage', label: '用法' },
]

export default function Demo() {
  return (
    <Inline gap="lg" align="start" className="w-full max-w-2xl">
      <ScrollArea className="border-line h-56 flex-1 rounded-lg border">
        {sections.map(s => (
          <Section id={s.id} key={s.id} className="min-h-40 p-4">
            <Heading level={3} size="sm">
              {s.label}
            </Heading>
            <Text size="sm" tone="muted">
              滚动此区域，右侧条目随之更新。
            </Text>
          </Section>
        ))}
      </ScrollArea>
      <Anchor items={sections} className="w-28 shrink-0" />
    </Inline>
  )
}

tsx

用法

import { Anchor } from '@hina-ui/react'

Anchor 由 items 驱动，每一项的 id 对应页面中一个元素的 id，label 是目录上显示的文字。

它只渲染目录，不渲染内容。每个 id 必须能在文档中找到对应元素，否则该项既不会被跟踪，点击也不会有反应。

作品简介

这一节的正文。

登场角色

这一节的正文。

制作人员

这一节的正文。

import { Anchor, Heading, Inline, ScrollArea, Section, Text } from '@hina-ui/react'

const items = [
  { id: 'basic-a', label: '作品简介' },
  { id: 'basic-b', label: '登场角色' },
  { id: 'basic-c', label: '制作人员' },
]

export default function Demo() {
  return (
    <Inline gap="lg" align="start" className="w-full max-w-2xl">
      <ScrollArea className="border-line h-56 flex-1 rounded-lg border">
        {items.map(item => (
          <Section id={item.id} key={item.id} className="min-h-40 p-4">
            <Heading level={3} size="sm">
              {item.label}
            </Heading>
            <Text size="sm" tone="muted">
              这一节的正文。
            </Text>
          </Section>
        ))}
      </ScrollArea>
      <Anchor items={items} className="w-28 shrink-0" />
    </Inline>
  )
}

tsx

它跟踪的是元素在视口中的可见性，因此内容位于页面主滚动区或 ScrollArea 之中，均可正常跟踪。

示例

层级

children 提供第二层条目，缩进一级显示。目录只支持两层——children 里再写 children 不会渲染。页内目录超过两层时，应当考虑拆分页面，而不是继续加深层级。

简介

这一节的正文。

路线

这一节的正文。

共通线

这一节的正文。

个人线

这一节的正文。

制作人员

这一节的正文。

import { Anchor, Heading, Inline, ScrollArea, Section, Text } from '@hina-ui/react'

const items = [
  { id: 'nest-intro', label: '简介' },
  {
    id: 'nest-route',
    label: '路线',
    children: [
      { id: 'nest-route-a', label: '共通线' },
      { id: 'nest-route-b', label: '个人线' },
    ],
  },
  { id: 'nest-staff', label: '制作人员' },
]

const flat = items.flatMap(item => [item, ...(item.children ?? [])])

export default function Demo() {
  return (
    <Inline gap="lg" align="start" className="w-full max-w-2xl">
      <ScrollArea className="border-line h-56 flex-1 rounded-lg border">
        {flat.map(item => (
          <Section id={item.id} key={item.id} className="min-h-32 p-4">
            <Heading level={3} size="sm">
              {item.label}
            </Heading>
            <Text size="sm" tone="muted">
              这一节的正文。
            </Text>
          </Section>
        ))}
      </ScrollArea>
      <Anchor items={items} className="w-32 shrink-0" />
    </Inline>
  )
}

tsx

尾部内容

renderTrailing 接收 { item, active }，可放置 Tag、文字或图标等非交互内容。item 是原始条目，包含自定义字段；顶层与第二层条目均支持。

active 表示该项带有 aria-current="location"。多个小节同时可见时，仅目录顺序中的第一个可见项为 active，原有的可见区间高亮保持不变。

尾部靠行尾排列，不压缩自身宽度，长标题可换行。空的尾部不占位；更新状态标记不会重置当前项，点击标记仍由该行执行跳转。

条目 A

这一节的正文。

条目 B

这一节的正文。

子条目

这一节的正文。

'use client'

import { useState } from 'react'
import {
  Anchor,
  Button,
  Heading,
  Inline,
  ScrollArea,
  Section,
  Stack,
  Tag,
  Text,
} from '@hina-ui/react'

export default function Demo() {
  const [modified, setModified] = useState(true)
  const items = [
    { id: 'trailing-a', label: '条目 A', modified },
    {
      id: 'trailing-b',
      label: '条目 B',
      modified: false,
      children: [{ id: 'trailing-c', label: '子条目', modified: true }],
    },
  ]
  const sections = items.flatMap(item => [item, ...(item.children ?? [])])

  return (
    <Stack gap="md" className="w-full max-w-2xl">
      <Inline>
        <Button
          variant="soft"
          tone="neutral"
          aria-pressed={modified}
          onClick={() => setModified(!modified)}
        >
          切换条目 A 的标记
        </Button>
      </Inline>
      <Inline gap="lg" align="start" wrap={false}>
        <ScrollArea className="border-line h-56 min-w-0 flex-1 rounded-lg border">
          {sections.map(item => (
            <Section id={item.id} key={item.id} className="min-h-40 p-4">
              <Heading level={3} size="sm">
                {item.label}
              </Heading>
              <Text size="sm" tone="muted">
                这一节的正文。
              </Text>
            </Section>
          ))}
        </ScrollArea>
        <Anchor
          items={items}
          label="带尾部标记的目录"
          className="w-44 shrink-0"
          renderTrailing={({ item, active }) =>
            item.modified ? <Tag tone={active ? 'accent' : 'neutral'}>已修改</Tag> : null
          }
        />
      </Inline>
    </Stack>
  )
}

tsx

长目录跟随

把长目录放入限定高度的 ScrollArea，当前高亮段超出目录可视区域时，Anchor 会自动滚动目录使整段完整可见，并保留少量边距。高亮段比可视区域更高时，退回跟随段首当前项，不在首尾之间来回滚动。它会识别最近的纵向滚动容器，也支持原生滚动容器或根元素自身滚动，无需传入 viewport。

已经完整可见的高亮段不会反复居中，手动翻看目录也不会被持续拉回。首次定位和尺寸调整直接对齐，后续高亮段首尾变化时平滑跟随；减弱动态效果下始终瞬时定位。自动跟随不会移动焦点，也不会滚动同时包含正文的外层容器。

通过 autoScroll={false} 关闭自动跟随，scroll-spy 和高亮仍然工作。onChange 接收当前条目的 id，组件 ref 上也可读取只读的 current，不需要观察 aria-current。下面的目录包含 51 项，可以独立滚动正文和目录，或关闭跟随作比较。

目录自动跟随

共 51 节