VuePress 生态系统VuePress 生态系统
  • 主题指南
  • 默认主题
  • Hope 主题
  • Plume 主题
  • Reco 主题
  • 功能插件
  • Markdown 插件
  • 搜索插件
  • 博客插件
  • 渐进式应用插件
  • 统计分析插件
  • 搜索引擎优化插件
  • 开发插件
  • 工具插件
  • AI 插件
  • @vuepress/helper
  • English
  • 简体中文
GitHub
  • 主题指南
  • 默认主题
  • Hope 主题
  • Plume 主题
  • Reco 主题
  • 功能插件
  • Markdown 插件
  • 搜索插件
  • 博客插件
  • 渐进式应用插件
  • 统计分析插件
  • 搜索引擎优化插件
  • 开发插件
  • 工具插件
  • AI 插件
  • @vuepress/helper
  • English
  • 简体中文
GitHub
  • active-header-links
  • git
  • palette
  • reading-time
  • rtl
  • Sass Palette
    • 指南
    • 配置
  • theme-data
  • toc

toc

@vuepress/plugin-toc

该插件会提供一个目录 (table-of-contents, TOC) 组件。

使用方法

npm i -D @vuepress/plugin-toc@next
.vuepress/config.ts
import { tocPlugin } from '@vuepress/plugin-toc'

export default {
  plugins: [
    tocPlugin({
      // 配置项
    }),
  ],
}

与 Markdown 目录语法的区别

与 Markdown 目录语法 类似,该插件提供的目录组件可以直接在你的 Markdown 内容中使用:

<!-- Markdown 目录语法 -->

[[toc]]

<!-- Vue 目录组件 -->
<Toc />

在 Build 模式中,它们都可以被正确地预渲染。然而,它们之间存在一些区别。

Markdown 语法 [[toc]] 仅能在 Markdown 文件中使用。它是由 markdown-it 解析的,生成的目录是静态内容。

组件 <Toc/> 既可以用在 Markdown 文件中,也可以用在 Vue 文件中。它是由 Vue 加载的,生成的目录是一个 Vue 组件。

该插件可以和 @vuepress/plugin-active-header-links 协同工作,你只需要将 headerLinkSelector 与该插件的 linkClass 匹配即可。当页面滚动至某个标题锚点后,对应的链接就会被加上 linkActiveClass 类名。

因此,该插件对于主题开发者来说更为有用。

配置项

componentName

  • 类型: string

  • 默认值: 'Toc'

  • 详情:

    指定目录组件的名称。

headerOptions

  • 类型: Partial<GetHeadersOptions>

  • 默认值: {}

  • 详情:

    覆盖组件 headerOptions Prop 的默认值。

propsOptions

  • 类型: Partial<TocPropsOptions>

  • 默认值: {}

  • 详情:

    覆盖组件 propsOptions Prop 的默认值。

组件 Props

目录组件可以通过 Props 来进行自定义。

<template>
  <Toc :headers="headers" :options="options" />
</template>

headers

  • 类型: PageHeader[]
interface PageHeader {
  level: number
  title: string
  slug: string
  children: PageHeader[]
}
  • 详情:

    指定要渲染的标题数组。

    如果该 Prop 没有被设置,默认会使用当前页面的标题。

headerOptions

  • 类型: Partial<GetHeadersOptions>

    详见 GetHeadersOptions

  • 默认值:

    详见 GetHeadersOptions,可以通过插件选项中的 headerOptions 来覆盖。

  • 详情:

    覆盖 getHeaders 函数的默认值。

propsOptions

  • 类型: Partial<TocPropsOptions>
interface TocPropsOptions {
  containerTag: string
  containerClass: string
  listClass: string
  itemClass: string
  linkTag: 'a' | 'RouteLink' | 'RouterLink'
  linkClass: string
  linkActiveClass: string
  linkChildrenActiveClass: string
}
  • 默认值:

    下列默认值可以用过插件选项中的 propsOptions 来覆盖:

const defaultOptions = {
  containerTag: 'nav',
  containerClass: 'vuepress-toc',
  listClass: 'vuepress-toc-list',
  itemClass: 'vuepress-toc-item',
  linkTag: 'RouteLink',
  linkClass: 'vuepress-toc-link',
  linkActiveClass: 'active',
  linkChildrenActiveClass: 'active',
}
  • 详情:

    自定义目录组件渲染行为。

    如果 containerTag 设置为空字符串 '' ,那么最外层的 <nav> Container 会被完全移除。

  • 示例:

    使用默认 options 的目录组件的渲染结果类似以下结构:

<template>
  <!-- container -->
  <nav class="vuepress-toc">
    <!-- list -->
    <ul class="vuepress-toc-list">
      <!-- item -->
      <li class="vuepress-toc-item">
        <!-- link -->
        <RouteLink class="vuepress-toc-link" to="#foo">Foo</RouteLink>
      </li>
      <!-- item with children -->
      <li class="vuepress-toc-item">
        <!-- link (children active) -->
        <RouteLink class="vuepress-toc-link active" to="#bar">Bar</RouteLink>
        <!-- list (children) -->
        <ul class="vuepress-toc-list">
          <!-- item -->
          <li class="vuepress-toc-item">
            <!-- link (active) -->
            <RouteLink class="vuepress-toc-link active" to="#bar-child">
              Bar Child
            </RouteLink>
          </li>
        </ul>
      </li>
    </ul>
  </nav>
</template>
在 GitHub 上编辑此页
上次更新: 2025/4/12 19:03
贡献者: Mister-Hope, meteorlxy, pengzhanbo
上一页
theme-data