logo
简体中文

导航菜单

文档

简介

TableOfContents 组件是一个智能的目录导航组件，它会自动检测页面中的标题元素，生成目录列表，并在用户滚动页面时高亮当前可见的标题。当页面只有一个标题或没有足够的标题结构时，组件会自动隐藏。

主要特性

  • 自动检测：自动检测页面中的标题结构
  • 智能显示：根据标题数量自动显示或隐藏
  • 滚动高亮：滚动时自动高亮当前标题
  • 平滑滚动：点击目录项时平滑滚动到目标位置
  • 响应式设计：在小屏幕设备上自动隐藏
  • 多语言支持：支持多种语言显示
  • 自定义配置：支持自定义容器、选择器、深度等

基础用法

最简单的用法，组件会自动检测页面中的标题并生成目录。

目录导航示例

这是一个基础的目录导航示例，右侧会显示自动生成的目录。

第一章：介绍

这是第一章的内容，介绍基本概念和使用方法。

1.1 基本概念

介绍组件的基本概念和设计理念。

1.2 使用方法

详细说明如何使用这个组件。

第二章：高级功能

介绍组件的高级功能和自定义选项。

2.1 自定义配置

如何自定义目录的显示和行为。

2.2 响应式设计

组件在不同屏幕尺寸下的表现。

第三章：最佳实践

使用组件时的最佳实践和注意事项。

3.1 性能优化

如何优化目录导航的性能。

3.2 无障碍访问

确保目录导航的无障碍访问性。

---
import { TableOfContents, Heading, Container } from '@coffic/cosy-ui';
---

<Container style="display: flex; gap: 2rem;">
  <div style="flex: 1;">
    <Heading level={1} margin="none">目录导航示例</Heading>
    <p style="margin-bottom: 1rem;">
      这是一个基础的目录导航示例，右侧会显示自动生成的目录。
    </p>

    <Heading level={2} margin="sm">第一章：介绍</Heading>
    <p style="margin-bottom: 1rem;">
      这是第一章的内容，介绍基本概念和使用方法。
    </p>

    <Heading level={3} margin="sm">1.1 基本概念</Heading>
    <p style="margin-bottom: 1rem;">介绍组件的基本概念和设计理念。</p>

    <Heading level={3} margin="sm">1.2 使用方法</Heading>
    <p style="margin-bottom: 1rem;">详细说明如何使用这个组件。</p>

    <Heading level={2} margin="sm">第二章：高级功能</Heading>
    <p style="margin-bottom: 1rem;">介绍组件的高级功能和自定义选项。</p>

    <Heading level={3} margin="sm">2.1 自定义配置</Heading>
    <p style="margin-bottom: 1rem;">如何自定义目录的显示和行为。</p>

    <Heading level={3} margin="sm">2.2 响应式设计</Heading>
    <p style="margin-bottom: 1rem;">组件在不同屏幕尺寸下的表现。</p>

    <Heading level={2} margin="sm">第三章：最佳实践</Heading>
    <p style="margin-bottom: 1rem;">使用组件时的最佳实践和注意事项。</p>

    <Heading level={3} margin="sm">3.1 性能优化</Heading>
    <p style="margin-bottom: 1rem;">如何优化目录导航的性能。</p>

    <Heading level={3} margin="sm">3.2 无障碍访问</Heading>
    <p style="margin-bottom: 1rem;">确保目录导航的无障碍访问性。</p>
  </div>

  <div style="width: 16rem;">
    <TableOfContents />
  </div>
</Container>

class

自定义 CSS 类名，用于覆盖默认样式。

目录导航示例

这是一个基础的目录导航示例，右侧会显示自动生成的目录。

第一章：介绍

这是第一章的内容，介绍基本概念和使用方法。

1.1 基本概念

介绍组件的基本概念和设计理念。

1.2 使用方法

详细说明如何使用这个组件。

第二章：高级功能

介绍组件的高级功能和自定义选项。

2.1 自定义配置

如何自定义目录的显示和行为。

2.2 响应式设计

组件在不同屏幕尺寸下的表现。

第三章：最佳实践

使用组件时的最佳实践和注意事项。

3.1 性能优化

如何优化目录导航的性能。

3.2 无障碍访问

确保目录导航的无障碍访问性。

---
import { TableOfContents, Heading, Container } from '@coffic/cosy-ui';
---

<Container style="display: flex; gap: 2rem;">
  <div style="flex: 1;">
    <Heading level={1} margin="none">目录导航示例</Heading>
    <p style="margin-bottom: 1rem;">
      这是一个基础的目录导航示例，右侧会显示自动生成的目录。
    </p>

    <Heading level={2} margin="sm">第一章：介绍</Heading>
    <p style="margin-bottom: 1rem;">
      这是第一章的内容，介绍基本概念和使用方法。
    </p>

    <Heading level={3} margin="sm">1.1 基本概念</Heading>
    <p style="margin-bottom: 1rem;">介绍组件的基本概念和设计理念。</p>

    <Heading level={3} margin="sm">1.2 使用方法</Heading>
    <p style="margin-bottom: 1rem;">详细说明如何使用这个组件。</p>

    <Heading level={2} margin="sm">第二章：高级功能</Heading>
    <p style="margin-bottom: 1rem;">介绍组件的高级功能和自定义选项。</p>

    <Heading level={3} margin="sm">2.1 自定义配置</Heading>
    <p style="margin-bottom: 1rem;">如何自定义目录的显示和行为。</p>

    <Heading level={3} margin="sm">2.2 响应式设计</Heading>
    <p style="margin-bottom: 1rem;">组件在不同屏幕尺寸下的表现。</p>

    <Heading level={2} margin="sm">第三章：最佳实践</Heading>
    <p style="margin-bottom: 1rem;">使用组件时的最佳实践和注意事项。</p>

    <Heading level={3} margin="sm">3.1 性能优化</Heading>
    <p style="margin-bottom: 1rem;">如何优化目录导航的性能。</p>

    <Heading level={3} margin="sm">3.2 无障碍访问</Heading>
    <p style="margin-bottom: 1rem;">确保目录导航的无障碍访问性。</p>
  </div>

  <div style="width: 16rem;">
    <TableOfContents />
  </div>
</Container>

containerSelector

内容容器选择器，用于限制标题搜索范围。默认值为 "main"。

容器选择器示例

这个示例展示了如何使用 containerSelector 属性来指定目录搜索的内容容器。

这个标题不会被包含在目录中

这是侧边栏或其他区域的内容，不会被目录组件检测到。

文章标题 1

这是文章内容，会被目录组件检测到。

子标题 1.1

这是子标题的内容。

子标题 1.2

这是另一个子标题的内容。

文章标题 2

这是第二个文章标题。

子标题 2.1

第二个标题的子内容。

这个标题也不会被包含

这是页脚或其他区域的内容，同样不会被目录组件检测到。

---
import { TableOfContents, Heading, Container, Alert } from '@coffic/cosy-ui';
---

<Container style="display: flex; gap: 2rem;">
  <div style="flex: 1;">
    <Heading level={1} margin="none">容器选择器示例</Heading>
    <p style="margin-bottom: 1rem;">
      这个示例展示了如何使用 containerSelector 属性来指定目录搜索的内容容器。
    </p>

    <Alert type="info" title="说明" marginY="md">
      左侧的目录只会显示 article 容器内的标题，而不会包含其他区域的标题。
    </Alert>

    <div
      style="background-color: #f8fafc; padding: 1rem; border-radius: 0.5rem; margin-bottom: 1rem;">
      <Heading level={2} margin="none">这个标题不会被包含在目录中</Heading>
      <p>这是侧边栏或其他区域的内容，不会被目录组件检测到。</p>
    </div>

    <article
      style="border: 2px solid #3b82f6; padding: 1rem; border-radius: 0.5rem;">
      <Heading level={2} margin="sm">文章标题 1</Heading>
      <p style="margin-bottom: 1rem;">这是文章内容，会被目录组件检测到。</p>

      <Heading level={3} margin="sm">子标题 1.1</Heading>
      <p style="margin-bottom: 1rem;">这是子标题的内容。</p>

      <Heading level={3} margin="sm">子标题 1.2</Heading>
      <p style="margin-bottom: 1rem;">这是另一个子标题的内容。</p>

      <Heading level={2} margin="sm">文章标题 2</Heading>
      <p style="margin-bottom: 1rem;">这是第二个文章标题。</p>

      <Heading level={3} margin="sm">子标题 2.1</Heading>
      <p style="margin-bottom: 1rem;">第二个标题的子内容。</p>
    </article>

    <div
      style="background-color: #fef3c7; padding: 1rem; border-radius: 0.5rem; margin-top: 1rem;">
      <Heading level={2} margin="none">这个标题也不会被包含</Heading>
      <p>这是页脚或其他区域的内容，同样不会被目录组件检测到。</p>
    </div>
  </div>

  <div style="width: 16rem;">
    <TableOfContents containerSelector="article" />
  </div>
</Container>

fixed

是否固定在右侧，设置为 false 时目录会跟随内容流。默认值为 true。

固定位置示例

这个示例展示了 fixed 属性的不同设置效果。

内容区域

这是主要内容区域，包含多个标题用于演示目录功能。

子标题 1

这是第一个子标题的内容。

子标题 2

这是第二个子标题的内容。

另一个主标题

这是另一个主标题的内容。

更多子标题

这是更多的子标题内容。

固定目录

非固定目录示例

下面的目录设置为非固定模式，会跟随内容流：

这是目录下方的其他内容，展示了非固定目录如何跟随内容流。

---
import { TableOfContents, Heading, Container, Alert } from '@coffic/cosy-ui';
---

<Container>
  <Heading level={1} margin="none">固定位置示例</Heading>
  <p style="margin-bottom: 1rem;">这个示例展示了 fixed 属性的不同设置效果。</p>

  <Alert type="info" title="说明" marginY="md">
    当 fixed=false 时，目录会跟随内容流，而不是固定在右侧。
  </Alert>

  <div style="display: flex; gap: 2rem; margin-top: 2rem;">
    <div style="flex: 1;">
      <Heading level={2} margin="sm">内容区域</Heading>
      <p style="margin-bottom: 1rem;">
        这是主要内容区域，包含多个标题用于演示目录功能。
      </p>

      <Heading level={3} margin="sm">子标题 1</Heading>
      <p style="margin-bottom: 1rem;">这是第一个子标题的内容。</p>

      <Heading level={3} margin="sm">子标题 2</Heading>
      <p style="margin-bottom: 1rem;">这是第二个子标题的内容。</p>

      <Heading level={2} margin="sm">另一个主标题</Heading>
      <p style="margin-bottom: 1rem;">这是另一个主标题的内容。</p>

      <Heading level={3} margin="sm">更多子标题</Heading>
      <p style="margin-bottom: 1rem;">这是更多的子标题内容。</p>
    </div>

    <div style="width: 16rem;">
      <Heading level={3} margin="sm">固定目录</Heading>
      <TableOfContents fixed={true} />
    </div>
  </div>

  <div style="margin-top: 3rem;">
    <Heading level={2} margin="sm">非固定目录示例</Heading>
    <p style="margin-bottom: 1rem;">
      下面的目录设置为非固定模式，会跟随内容流：
    </p>

    <div
      style="border: 2px dashed #3b82f6; padding: 1rem; border-radius: 0.5rem; margin-bottom: 2rem;">
      <TableOfContents fixed={false} />
    </div>

    <p>这是目录下方的其他内容，展示了非固定目录如何跟随内容流。</p>
  </div>
</Container>

maxDepth

最大深度，控制目录显示的标题级别。默认值为 3。

最大深度示例

这个示例展示了如何使用 maxDepth 属性控制目录显示的标题级别。

一级标题

这是一级标题的内容。

二级标题

这是二级标题的内容。

三级标题（不会显示在目录中）

这是三级标题的内容，由于 maxDepth=2，这个标题不会出现在目录中。

四级标题（不会显示在目录中）

这是四级标题的内容，同样不会出现在目录中。

另一个一级标题

这是另一个一级标题的内容。

另一个二级标题

这是另一个二级标题的内容。

另一个三级标题（不会显示）

这是另一个三级标题的内容。

---
import { TableOfContents, Heading, Container, Alert } from '@coffic/cosy-ui';
---

<Container style="display: flex; gap: 2rem;">
  <div style="flex: 1;">
    <Heading level={1} margin="none">最大深度示例</Heading>
    <p style="margin-bottom: 1rem;">
      这个示例展示了如何使用 maxDepth 属性控制目录显示的标题级别。
    </p>

    <Alert type="info" title="说明" marginY="md">
      左侧的目录设置了 maxDepth={2}，所以只会显示 h2 和 h3 级别的标题，不会显示
      h4 及以下级别。
    </Alert>

    <Heading level={2} margin="sm">一级标题</Heading>
    <p style="margin-bottom: 1rem;">这是一级标题的内容。</p>

    <Heading level={3} margin="sm">二级标题</Heading>
    <p style="margin-bottom: 1rem;">这是二级标题的内容。</p>

    <Heading level={4} margin="sm">三级标题（不会显示在目录中）</Heading>
    <p style="margin-bottom: 1rem;">
      这是三级标题的内容，由于 maxDepth=2，这个标题不会出现在目录中。
    </p>

    <Heading level={5} margin="sm">四级标题（不会显示在目录中）</Heading>
    <p style="margin-bottom: 1rem;">
      这是四级标题的内容，同样不会出现在目录中。
    </p>

    <Heading level={2} margin="sm">另一个一级标题</Heading>
    <p style="margin-bottom: 1rem;">这是另一个一级标题的内容。</p>

    <Heading level={3} margin="sm">另一个二级标题</Heading>
    <p style="margin-bottom: 1rem;">这是另一个二级标题的内容。</p>

    <Heading level={4} margin="sm">另一个三级标题（不会显示）</Heading>
    <p style="margin-bottom: 1rem;">这是另一个三级标题的内容。</p>
  </div>

  <div style="width: 16rem;">
    <TableOfContents maxDepth={2} />
  </div>
</Container>

minHeadings

显示目录所需的最少标题数量，少于此时目录会自动隐藏。默认值为 2。

最少标题数量示例

这个示例展示了如何使用 minHeadings 属性控制目录显示的条件。

第一个标题

这是第一个标题的内容。

第二个标题

这是第二个标题的内容。

第三个标题

这是第三个标题的内容。

目录（minHeadings=2）

隐藏目录示例

下面的内容只有一个标题，所以目录会隐藏：

唯一的标题

这个区域只有一个标题，所以目录会隐藏。

目录状态

由于标题数量少于 minHeadings=2，目录已隐藏 

---
import { TableOfContents, Heading, Container, Alert } from '@coffic/cosy-ui';
---

<Container>
  <Heading level={1} margin="none">最少标题数量示例</Heading>
  <p style="margin-bottom: 1rem;">
    这个示例展示了如何使用 minHeadings 属性控制目录显示的条件。
  </p>

  <Alert type="info" title="说明" marginY="md">
    当页面中的标题数量少于 minHeadings 设置的值时，目录会自动隐藏。
  </Alert>

  <div style="display: flex; gap: 2rem; margin-top: 2rem;">
    <div style="flex: 1;">
      <Heading level={2} margin="sm">第一个标题</Heading>
      <p style="margin-bottom: 1rem;">这是第一个标题的内容。</p>

      <Heading level={2} margin="sm">第二个标题</Heading>
      <p style="margin-bottom: 1rem;">这是第二个标题的内容。</p>

      <Heading level={2} margin="sm">第三个标题</Heading>
      <p style="margin-bottom: 1rem;">这是第三个标题的内容。</p>
    </div>

    <div style="width: 16rem;">
      <Heading level={3} margin="sm">目录（minHeadings=2）</Heading>
      <TableOfContents minHeadings={2} />
    </div>
  </div>

  <div style="margin-top: 3rem;">
    <Heading level={2} margin="sm">隐藏目录示例</Heading>
    <p style="margin-bottom: 1rem;">下面的内容只有一个标题，所以目录会隐藏：</p>

    <div
      style="border: 2px dashed #ef4444; padding: 1rem; border-radius: 0.5rem; margin-bottom: 2rem;">
      <Heading level={2} margin="sm">唯一的标题</Heading>
      <p style="margin-bottom: 1rem;">这个区域只有一个标题，所以目录会隐藏。</p>

      <div
        style="background-color: #fef2f2; padding: 1rem; border-radius: 0.5rem;">
        <Heading level={3} margin="sm">目录状态</Heading>
        <p style="margin: 0; color: #dc2626;">
          由于标题数量少于 minHeadings=2，目录已隐藏
        </p>
      </div>
    </div>
  </div>
</Container>

selector

标题选择器，用于指定要包含在目录中的标题元素。默认值为 "h2, h3"。

选择器示例

这个示例展示了如何使用 selector 属性自定义要包含在目录中的标题元素。

H2 标题（会显示在目录中）

这是 H2 标题的内容。

H3 标题（不会显示在目录中）

这是 H3 标题的内容，由于 selector 设置，这个标题不会出现在目录中。

H4 标题（会显示在目录中）

这是 H4 标题的内容。

另一个 H2 标题

这是另一个 H2 标题的内容。

另一个 H3 标题（不会显示）

这是另一个 H3 标题的内容。

另一个 H4 标题

这是另一个 H4 标题的内容。

H5 标题（不会显示）

这是 H5 标题的内容，同样不会出现在目录中。 

---
import { TableOfContents, Heading, Container, Alert } from '@coffic/cosy-ui';
---

<Container style="display: flex; gap: 2rem;">
  <div style="flex: 1;">
    <Heading level={1} margin="none">选择器示例</Heading>
    <p style="margin-bottom: 1rem;">
      这个示例展示了如何使用 selector 属性自定义要包含在目录中的标题元素。
    </p>

    <Alert type="info" title="说明" marginY="md">
      左侧的目录设置了 selector="h2, h4"，所以只会显示 h2 和 h4 级别的标题，跳过
      h3 级别。
    </Alert>

    <Heading level={2} margin="sm">H2 标题（会显示在目录中）</Heading>
    <p style="margin-bottom: 1rem;">这是 H2 标题的内容。</p>

    <Heading level={3} margin="sm">H3 标题（不会显示在目录中）</Heading>
    <p style="margin-bottom: 1rem;">
      这是 H3 标题的内容，由于 selector 设置，这个标题不会出现在目录中。
    </p>

    <Heading level={4} margin="sm">H4 标题（会显示在目录中）</Heading>
    <p style="margin-bottom: 1rem;">这是 H4 标题的内容。</p>

    <Heading level={2} margin="sm">另一个 H2 标题</Heading>
    <p style="margin-bottom: 1rem;">这是另一个 H2 标题的内容。</p>

    <Heading level={3} margin="sm">另一个 H3 标题（不会显示）</Heading>
    <p style="margin-bottom: 1rem;">这是另一个 H3 标题的内容。</p>

    <Heading level={4} margin="sm">另一个 H4 标题</Heading>
    <p style="margin-bottom: 1rem;">这是另一个 H4 标题的内容。</p>

    <Heading level={5} margin="sm">H5 标题（不会显示）</Heading>
    <p style="margin-bottom: 1rem;">
      这是 H5 标题的内容，同样不会出现在目录中。
    </p>
  </div>

  <div style="width: 16rem;">
    <TableOfContents selector="h2, h4" />
  </div>
</Container>

title

目录标题文本，默认根据语言自动选择。

自定义标题示例

这个示例展示了如何使用 title 属性自定义目录的标题文本。

第一章：介绍

这是第一章的内容。

1.1 基本概念

介绍基本概念。

1.2 使用方法

介绍使用方法。

第二章：高级功能

这是第二章的内容。

2.1 自定义配置

介绍自定义配置。

2.2 最佳实践

介绍最佳实践。

第三章：总结

这是第三章的内容。

3.1 回顾要点

回顾重要要点。

---
import { TableOfContents, Heading, Container, Alert } from '@coffic/cosy-ui';
---

<Container style="display: flex; gap: 2rem;">
  <div style="flex: 1;">
    <Heading level={1} margin="none">自定义标题示例</Heading>
    <p style="margin-bottom: 1rem;">
      这个示例展示了如何使用 title 属性自定义目录的标题文本。
    </p>

    <Alert type="info" title="说明" marginY="md">
      左侧的目录使用了自定义标题 "章节导航"，而不是默认的标题。
    </Alert>

    <Heading level={2} margin="sm">第一章：介绍</Heading>
    <p style="margin-bottom: 1rem;">这是第一章的内容。</p>

    <Heading level={3} margin="sm">1.1 基本概念</Heading>
    <p style="margin-bottom: 1rem;">介绍基本概念。</p>

    <Heading level={3} margin="sm">1.2 使用方法</Heading>
    <p style="margin-bottom: 1rem;">介绍使用方法。</p>

    <Heading level={2} margin="sm">第二章：高级功能</Heading>
    <p style="margin-bottom: 1rem;">这是第二章的内容。</p>

    <Heading level={3} margin="sm">2.1 自定义配置</Heading>
    <p style="margin-bottom: 1rem;">介绍自定义配置。</p>

    <Heading level={3} margin="sm">2.2 最佳实践</Heading>
    <p style="margin-bottom: 1rem;">介绍最佳实践。</p>

    <Heading level={2} margin="sm">第三章：总结</Heading>
    <p style="margin-bottom: 1rem;">这是第三章的内容。</p>

    <Heading level={3} margin="sm">3.1 回顾要点</Heading>
    <p style="margin-bottom: 1rem;">回顾重要要点。</p>
  </div>

  <div style="width: 16rem;">
    <TableOfContents title="章节导航" />
  </div>
</Container>

搜索