logo
English

导航菜单

Documents

Introduction

The TableOfContents component is an intelligent table of contents navigation component that automatically detects heading elements on the page, generates a navigation list, and highlights the currently visible heading as users scroll through the page. When there’s only one heading or insufficient heading structure on the page, the component automatically hides itself.

Key Features

  • Auto Detection: Automatically detects heading structure on the page
  • Smart Display: Automatically shows or hides based on heading count
  • Scroll Highlighting: Automatically highlights current heading during scrolling
  • Smooth Scrolling: Smoothly scrolls to target position when clicking navigation items
  • Responsive Design: Automatically hides on small screen devices
  • Multi-language Support: Supports multiple language displays
  • Custom Configuration: Supports custom containers, selectors, depth, etc.

Basic Usage

The simplest usage, the component automatically detects headings on the page and generates a table of contents.

目录导航示例

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

第一章：介绍

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

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

Custom CSS class name for overriding default styles.

目录导航示例

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

第一章：介绍

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

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

Content container selector for limiting heading search scope. Default value is "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

Whether to fix on the right side. When set to false, the table of contents follows the content flow. Default value is 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

Maximum depth controlling the heading levels displayed in the table of contents. Default value is 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

Minimum number of headings required to display the table of contents. When fewer than this number, the table of contents automatically hides. Default value is 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

Heading selector for specifying which heading elements to include in the table of contents. Default value is "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

Table of contents title text, automatically selected based on language by default.

自定义标题示例

这个示例展示了如何使用 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>

搜索