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

Toc 目录锚点

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

基础用法

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

背景

<script setup lang="ts">
import { CfToc, type TocItem } from '@chufix-design/vue';

const items: TocItem[] = [
  { id: 'intro', label: '介绍', depth: 1 },
  { id: 'install', label: '安装', depth: 1 },
  { id: 'usage', label: '基本用法', depth: 1 },
  { id: 'theme', label: '主题', depth: 1 },
];
</script>

<template>
  <div style="max-width: 220px;">
    <CfToc :items="items" :active-id="'install'" title="本页目录" />
  </div>
</template>

<script setup>
import { CfToc } from '@chufix-design/vue';

const items= [
  { id: 'intro', label: '介绍', depth: 1 },
  { id: 'install', label: '安装', depth: 1 },
  { id: 'usage', label: '基本用法', depth: 1 },
  { id: 'theme', label: '主题', depth: 1 },
];
</script>

<template>
  <div style="max-width: 220px;">
    <CfToc :items="items" :active-id="'install'" title="本页目录" />
  </div>
</template>

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

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

嵌套缩进

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

背景

<script setup lang="ts">
import { CfToc, type TocItem } from '@chufix-design/vue';

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: 'install-vanilla', label: '纯 HTML', depth: 2 },
  { id: 'usage', label: '基本用法', depth: 1 },
  { id: 'theme', label: '主题与 Tokens', depth: 1 },
  { id: 'theme-dark', label: 'dark-cool', depth: 2 },
  { id: 'theme-warm', label: 'dark-warm', depth: 2 },
  { id: 'theme-detail', label: '颜色细节', depth: 3 },
];
</script>

<template>
  <div style="max-width: 220px;">
    <CfToc :items="items" :active-id="'install-vue'" title="本页目录" />
  </div>
</template>

<script setup>
import { CfToc } from '@chufix-design/vue';

const items= [
  { 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: 'install-vanilla', label: '纯 HTML', depth: 2 },
  { id: 'usage', label: '基本用法', depth: 1 },
  { id: 'theme', label: '主题与 Tokens', depth: 1 },
  { id: 'theme-dark', label: 'dark-cool', depth: 2 },
  { id: 'theme-warm', label: 'dark-warm', depth: 2 },
  { id: 'theme-detail', label: '颜色细节', depth: 3 },
];
</script>

<template>
  <div style="max-width: 220px;">
    <CfToc :items="items" :active-id="'install-vue'" title="本页目录" />
  </div>
</template>

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

<CfToc items={items} />

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

<CfToc items={items} />

maxDepth 限制

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

背景

maxDepth = 2

maxDepth = 4（默认 6）

<script setup lang="ts">
import { CfToc, type TocItem } from '@chufix-design/vue';

const items: TocItem[] = [
  { id: 'a', label: '一级标题', depth: 1 },
  { id: 'a1', label: '二级标题', depth: 2 },
  { id: 'a1a', label: '三级 — 仅 maxDepth=3 显示', depth: 3 },
  { id: 'a1ai', label: '四级 — 仅 maxDepth>=4 显示', depth: 4 },
];
</script>

<template>
  <div style="display: flex; gap: 16px;">
    <div style="max-width: 200px;">
      <div style="font-size: 12px; color: var(--fg-3); margin-bottom: 4px;">maxDepth = 2</div>
      <CfToc :items="items" :max-depth="2" />
    </div>
    <div style="max-width: 240px;">
      <div style="font-size: 12px; color: var(--fg-3); margin-bottom: 4px;">maxDepth = 4（默认 6）</div>
      <CfToc :items="items" :max-depth="4" />
    </div>
  </div>
</template>

<script setup>
import { CfToc } from '@chufix-design/vue';

const items= [
  { id: 'a', label: '一级标题', depth: 1 },
  { id: 'a1', label: '二级标题', depth: 2 },
  { id: 'a1a', label: '三级 — 仅 maxDepth=3 显示', depth: 3 },
  { id: 'a1ai', label: '四级 — 仅 maxDepth>=4 显示', depth: 4 },
];
</script>

<template>
  <div style="display: flex; gap: 16px;">
    <div style="max-width: 200px;">
      <div style="font-size: 12px; color: var(--fg-3); margin-bottom: 4px;">maxDepth = 2</div>
      <CfToc :items="items" :max-depth="2" />
    </div>
    <div style="max-width: 240px;">
      <div style="font-size: 12px; color: var(--fg-3); margin-bottom: 4px;">maxDepth = 4（默认 6）</div>
      <CfToc :items="items" :max-depth="4" />
    </div>
  </div>
</template>

<CfToc items={items} maxDepth={2} />
<CfToc items={items} maxDepth={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）。