开发预览更新于 2026-05-10

Toc 目录锚点

文章侧边目录，按 depth 缩进，可手动指定或自动（IntersectionObserver scroll-spy）跟随当前阅读位置。

基础用法

items 是一个数组，每项至少有 id 和 label。activeId 控制当前高亮项；点击会平滑滚动并更新地址栏 hash。

<CfToc
:items="items"
:active-id="'install'"
title="本页目录"
/>

<CfToc items={items} activeId="install" title="本页目录" />

嵌套缩进

depth: 1..6 控制缩进层级。同一份 items 数组只要 depth 配对正确，就自然形成嵌套缩进。

const items: TocItem[] = [
{ id: 'intro', label: '介绍', depth: 1 },
{ id: 'install', label: '安装', depth: 1 },
{ id: 'install-vue', label: 'Vue 3', depth: 2 },
{ id: 'install-react', label: 'React 18', depth: 2 },
{ id: 'theme', label: '主题', depth: 1 },
{ id: 'theme-detail', label: '颜色细节', depth: 3 },
];

<CfToc :items="items" />

const items: TocItem[] = [/* ... */];

<CfToc items={items} />

maxDepth 限制

maxDepth 决定渲染的最深层级 — 比如博客侧栏只想显示 H1 / H2 时，传 maxDepth={2}，更深的标题不渲染。

maxDepth = 2

maxDepth = 4（默认 6）

<CfToc :items="items" :max-depth="2" />
<CfToc :items="items" :max-depth="4" />

<CfToc items={items} maxDepth={2} />
<CfToc items={items} maxDepth={4} />

自动滚动跟随（scroll-spy）

autoSpy: true 让组件自动监听文章里 id 与 items 对应的标题，根据可视范围自动切换 active。scrollRoot 指定监听容器；省略时监听 viewport。

<!-- Vue -->
<CfToc :items="items" auto-spy />
<CfToc :items="items" auto-spy scroll-root=".article-body" />

{/* React */}
<CfToc items={items} autoSpy />
<CfToc items={items} autoSpy scrollRoot=".article-body" />

API

属性	类型	默认值	说明
`items`	`TocItem[]`	`[]`	目录条目
`autoSpy`	`boolean`	`false`	启用 IntersectionObserver 自动跟随
`scrollRoot`	`string`	`—`	监听容器选择器；省略则使用 viewport
`activeId`	`string \| null`	`null`	受控当前 id
`defaultActiveId` (React)	`string \| null`	`null`	非受控初始值
`title`	`string \| ReactNode`	`—`	顶部小标题
`maxDepth`	`number`	`6`	渲染的最大深度

TocItem：{ id, label, depth? }。事件：update:activeId（React 端：onActiveIdChange）。