Storybook 文档页目录Table of Contents完整配置指南docs.toc 参数详解本篇指南讲解如何在 Storybook 中为 Autodocs 自动生成的组件文档页启用与定制目录Table of Contents简称 TOC通过在.storybook/preview.js|ts中配置docs.toc参数即可让长文档页面快速获得可跳转的侧边目录并支持按组件粒度启停与深度定制。读完本文你将掌握docs.toc的全部配置项contentsSelector、disable、headingSelector、ignoreSelector、title、unsafeTocbotOptions并能结合仓库源码理解其底层基于 Tocbot 的实现原理。什么是 docs.toc文档页的侧边目录Storybook 的 Autodocs 会把组件的故事stories自动扩展成一份完整的文档页面内容包含组件元信息、示例、参数表等页面往往很长难以快速定位。TOC 功能会在文档页右侧以固定侧边栏形式渲染一份目录让读者一眼看到页面结构并一键跳转到任意章节在小屏幕宽度低于 768px下该侧边栏会被隐藏。在 Storybook 中目录不是通过向 MDX 文件里添加组件来启用的而是通过docs.tocparameter 配置的启用后由 Storybook 的 docs container 在渲染页面内容时自动附带渲染。与之对应的 Doc Block 组件是TableOfContents其 API 说明见 doc-block-tableofcontents.mdx。全局启用在 preview 配置中开启目录要全局启用目录只需在 Storybook 的 UI 配置文件即.storybook/preview.js|ts|jsx|tsx中为parameters.docs增加toc: true。以下是仓库中 storybook-preview-enable-toc.md 提供的完整示例。CSF 3 写法通用框架// .storybook/preview.js|jsx export default { parameters: { docs: { toc: true, // 启用目录 }, }, };// .storybook/preview.ts|tsx // 将 your-framework 替换为实际使用的框架如 react-vite、nextjs、vue3-vite 等 import type { Preview } from storybook/your-framework; const preview: Preview { parameters: { docs: { toc: true, // 启用目录 }, }, }; export default preview;CSF Next 写法definePreview addonDocs在 CSF Next 实验性写法中需要通过definePreview注册storybook/addon-docs插件再在parameters中配置docs.toc。以 React 为例// .storybook/preview.tsx // 将 your-framework 替换为实际使用的框架如 react-vite、nextjs、nextjs-vite import { definePreview } from storybook/your-framework; import addonDocs from storybook/addon-docs; export default definePreview({ addons: [addonDocs()], parameters: { docs: { toc: true, // 启用目录 }, }, });// .storybook/preview.jsx import { definePreview } from storybook/your-framework; import addonDocs from storybook/addon-docs; export default definePreview({ addons: [addonDocs()], parameters: { docs: { toc: true, // 启用目录 }, }, });Vue 3vue3-vite与 Angular、Web Components 的写法完全一致仅需替换框架入口// .storybook/preview.ts — vue3-vite import { definePreview } from storybook/vue3-vite; import addonDocs from storybook/addon-docs; export default definePreview({ addons: [addonDocs()], parameters: { docs: { toc: true, // 启用目录 }, }, });// .storybook/preview.ts — angular import { definePreview } from storybook/angular; import addonDocs from storybook/addon-docs; // ...addons: [addonDocs()], parameters: { docs: { toc: true } }// .storybook/preview.ts — web-components-vite import { definePreview } from storybook/web-components-vite; import addonDocs from storybook/addon-docs; // ...addons: [addonDocs()], parameters: { docs: { toc: true } }说明toc参数的取值既可以是布尔值true按默认配置启用也可以是一个配置对象见下文全部配置项不设置该参数时文档页默认不渲染目录。按组件/故事粒度启停除了全局开启docs.toc是一个标准的 parameter因此可以在单个组件的故事文件*.stories.js|ts|tsx|svelte的 metadefault export中覆盖它。典型场景是全局已开启目录但某个组件页面结构简单、不需要目录此时用toc: { disable: true }关掉示例来自 my-component-disable-toc.md// MyComponent.stories.ts — CSF 3通用框架 // 将 your-framework 替换为实际使用的框架如 react-vite、nextjs、vue3-vite 等 import type { Meta } from storybook/your-framework; import { MyComponent } from ./MyComponent; const meta { component: MyComponent, tags: [autodocs], parameters: { docs: { toc: { disable: true, // 关闭该组件的目录 }, }, }, } satisfies Metatypeof MyComponent; export default meta;// MyComponent.stories.js — CSF 3纯 JS 写法 import { MyComponent } from ./MyComponent; export default { component: MyComponent, tags: [autodocs], parameters: { docs: { toc: { disable: true, // 关闭该组件的目录 }, }, }, };Web Components 的写法类似只是component字段使用自定义元素名// MyComponent.stories.js — web-components export default { component: my-component, tags: [autodocs], parameters: { docs: { toc: { disable: true, }, }, }, };Angular、SvelteSvelte CSF 用defineMeta、Vue 等框架的 CSF 3 写法结构相同仅替换导入入口在 CSF Next 写法中则通过preview.meta({ ... })传入相同的parameters配置。所有完整变体可查阅 my-component-disable-toc.md。toc 参数全部配置项docs.toc接受true默认配置启用或一个对象。下表汇总了 doc-block-tableofcontents.mdx 与 autodocs.mdx 中定义的全部属性及默认值这些默认值与源码实现完全一致。属性类型默认值说明contentsSelectorstring.sbdocs-content用于在页面中查找标题的容器 CSS 选择器自定义文档页布局时使用disablebooleanfalse为true时隐藏该文档页的目录仍会渲染一个空的占位容器以保持页面布局不变headingSelectorstringh3决定收录哪些标题级别例如h1, h2, h3收录前三级标题ignoreSelectorstring.docs-story *, .skip-toc需要从目录中排除的标题选择器默认排除故事块story blocks内的所有标题如需额外排除某个标题可给它加上skip-tocclasstitlestring \| null \| ReactElementTable of contents视觉隐藏目录上方的标题文本或元素设为null则不渲染标题传字符串时默认渲染为视觉隐藏的h2传入非空字符串可使其可见unsafeTocbotOptionsobject—直接透传给底层 Tocbot 库的额外配置项不保证在未来版本中继续可用完整配置示例下面是在 preview 中一次性配置全部选项的示例来自 storybook-preview-custom-toc.md// .storybook/preview.js|jsx — CSF 3 export default { parameters: { docs: { toc: { contentsSelector: .sbdocs-content, headingSelector: h1, h2, h3, ignoreSelector: #primary, title: Table of Contents, disable: false, unsafeTocbotOptions: { orderedList: false, }, }, }, }, };// .storybook/preview.ts|tsx — CSF 3 import type { Preview } from storybook/your-framework; const preview: Preview { parameters: { docs: { toc: { contentsSelector: .sbdocs-content, headingSelector: h1, h2, h3, ignoreSelector: #primary, title: Table of Contents, disable: false, unsafeTocbotOptions: { orderedList: false, }, }, }, }, }; export default preview;// .storybook/preview.tsx — CSF Next react import { definePreview } from storybook/your-framework; import addonDocs from storybook/addon-docs; export default definePreview({ addons: [addonDocs()], parameters: { docs: { toc: { contentsSelector: .sbdocs-content, headingSelector: h1, h2, h3, ignoreSelector: #primary, title: Table of Contents, disable: false, unsafeTocbotOptions: { orderedList: false, }, }, }, }, });Vue、Angular、Web Components 的 CSF Next 写法与上面一致只需替换definePreview的导入来源storybook/vue3-vite、storybook/angular、storybook/web-components-vite并同样注册addonDocs()。unsafeTocbotOptions常用于控制列表形式如orderedList: true渲染有序列表、scrollSmoothOffset、headingsOffset等 Tocbot 原生行为。在单个组件上定制同样以上对象形式也可以放进组件 story 文件的 meta 中实现这一篇文档用这套目录配置的粒度控制。例如隐藏某个特定故事的目录只需在其 metadefault export中加入toc: { disable: true }。源码原理TableOfContents 组件如何工作了解了配置再来看实现能帮助你更准确地预测行为。目录由 addon-docs 中的 TableOfContents.tsx 组件渲染其核心机制如下。基于 Tocbot 的标题扫描组件在挂载后通过useEffect调用第三方库tocbot完成目录的构建与滚动联动tocbot.init(configuration)并把所有默认值与配置项合并const configuration { tocSelector: .toc-wrapper, contentSelector: contentsSelector ?? .sbdocs-content, headingSelector: headingSelector ?? h3, ignoreSelector: ignoreSelector ?? .docs-story *, .skip-toc, headingsOffset: 40, scrollSmoothOffset: -40, orderedList: false, onClick: (e) { e.preventDefault(); // 通过 Storybook 内部 Channel 发出 NAVIGATE_URL 事件实现平滑滚动跳转 channel.emit(NAVIGATE_URL, #${headerId}); }, ...unsafeTocbotOptions, };从源码可以看到tocSelector固定为.toc-wrapper这是组件内部渲染的空容器contentSelector、headingSelector、ignoreSelector三个默认值.sbdocs-content、h3、.docs-story *, .skip-toc与文档表格中的默认值一一对应且展开顺序在unsafeTocbotOptions之前——即unsafeTocbotOptions可以覆盖除onClick/scrollEndCallback之外的任何 Tocbot 配置点击目录项时不会触发浏览器默认锚点跳转而是通过channel.emit(NAVIGATE_URL, ...)走 Storybook 内部路由保证在 iframe 化的文档环境中也能正确滚动并同步 URL 状态组件在卸载时会调用tocbot.destroy()清理避免多个文档页间互相污染。disable 时仍保留占位容器特别注意disable的处理当disable: true时组件不渲染导航内容但依然渲染一个空的aside容器。源码注释解释了原因——目录占位会影响页面布局右侧留白宽度保留空容器可以在不同页面间保持一致的排版避免页面切换时内容区宽度跳动。标题渲染与响应式标题默认文案为Table of contents以视觉隐藏sb-sr-onlyclass的h2渲染兼顾无障碍aria-labelledby传入字符串时标题可见传入null则完全不渲染标题传入 React 元素则原样包裹组件会为 ARIA 关联补上 id。侧边栏宽度固定为10rem导航在垂直方向固定并支持滚动position: fixed; overflowY: auto且通过media (max-width: 768px)在小屏下display: none隐藏与文档小屏幕隐藏的说明一致。官方配套示例 stories仓库在 template/stories/toc/ 下提供了可直接参考的示例 story覆盖各种配置组合basic.stories.ts默认toc: true的基础用法custom-selector.stories.ts自定义contentsSelector/headingSelectorcustom-title.stories.ts自定义titleignore-selector.stories.ts通过ignoreSelector排除指定标题。这些 stories 同时也是 TableOfContents.stories.tsx 驱动的组件测试用例可作为验证配置行为的参照。注意事项与常见问题以下行为来自 autodocs.mdx 的 Troubleshooting 章节与源码实现配置前建议了解单标题页面不会自动隐藏目录如果文档页只有一个匹配的标题TOC 默认仍会显示。若觉得多余可以再加一个标题或直接关闭该页的目录toc: { disable: true }。小屏幕默认隐藏源码层面宽度小于 768px 时右侧目录容器会被隐藏见 TableOfContents.tsx 中的媒体查询这是为了在窄屏下优先保证正文可读性官方文档同时提示在小屏下隐藏 TOC 目前没有不影响页面样式兼容性的内置开关。MDX 独立文档无法按页定制对于使用 MDX 编写的独立unattached文档由于当前实现不支持在该场景下定义参数docs.toc的自定义配置不会生效目录会始终回退到全局默认配置。unsafeTocbotOptions属于逃生舱它直接透传给 Tocbot绕过 Storybook 的类型约束因此不保证未来版本兼容onClick与scrollEndCallback两个回调由 Storybook 内部管理不允许通过该选项覆盖。与inline渲染的已知限制如果你通过docs.story.inline关闭了故事的 iframe 内联渲染文档页中的控件将无法联动更新故事这是当前实现的已知限制与目录本身无直接关系但排查文档页交互问题时值得留意。更多阅读Autodocs 自动文档总览含 TOC 的启用与配置章节TableOfContents Doc Block APIStorybook 全局参数 parameters用 MDX 扩展文档 与 Doc Blocks 创作文档发布文档配套代码片段storybook-preview-enable-toc.md、storybook-preview-custom-toc.md、my-component-disable-toc.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Storybook 文档页目录（Table of Contents）完整配置指南：docs.toc 参数详解
Storybook 文档页目录Table of Contents完整配置指南docs.toc 参数详解本篇指南讲解如何在 Storybook 中为 Autodocs 自动生成的组件文档页启用与定制目录Table of Contents简称 TOC通过在.storybook/preview.js|ts中配置docs.toc参数即可让长文档页面快速获得可跳转的侧边目录并支持按组件粒度启停与深度定制。读完本文你将掌握docs.toc的全部配置项contentsSelector、disable、headingSelector、ignoreSelector、title、unsafeTocbotOptions并能结合仓库源码理解其底层基于 Tocbot 的实现原理。什么是 docs.toc文档页的侧边目录Storybook 的 Autodocs 会把组件的故事stories自动扩展成一份完整的文档页面内容包含组件元信息、示例、参数表等页面往往很长难以快速定位。TOC 功能会在文档页右侧以固定侧边栏形式渲染一份目录让读者一眼看到页面结构并一键跳转到任意章节在小屏幕宽度低于 768px下该侧边栏会被隐藏。在 Storybook 中目录不是通过向 MDX 文件里添加组件来启用的而是通过docs.tocparameter 配置的启用后由 Storybook 的 docs container 在渲染页面内容时自动附带渲染。与之对应的 Doc Block 组件是TableOfContents其 API 说明见 doc-block-tableofcontents.mdx。全局启用在 preview 配置中开启目录要全局启用目录只需在 Storybook 的 UI 配置文件即.storybook/preview.js|ts|jsx|tsx中为parameters.docs增加toc: true。以下是仓库中 storybook-preview-enable-toc.md 提供的完整示例。CSF 3 写法通用框架// .storybook/preview.js|jsx export default { parameters: { docs: { toc: true, // 启用目录 }, }, };// .storybook/preview.ts|tsx // 将 your-framework 替换为实际使用的框架如 react-vite、nextjs、vue3-vite 等 import type { Preview } from storybook/your-framework; const preview: Preview { parameters: { docs: { toc: true, // 启用目录 }, }, }; export default preview;CSF Next 写法definePreview addonDocs在 CSF Next 实验性写法中需要通过definePreview注册storybook/addon-docs插件再在parameters中配置docs.toc。以 React 为例// .storybook/preview.tsx // 将 your-framework 替换为实际使用的框架如 react-vite、nextjs、nextjs-vite import { definePreview } from storybook/your-framework; import addonDocs from storybook/addon-docs; export default definePreview({ addons: [addonDocs()], parameters: { docs: { toc: true, // 启用目录 }, }, });// .storybook/preview.jsx import { definePreview } from storybook/your-framework; import addonDocs from storybook/addon-docs; export default definePreview({ addons: [addonDocs()], parameters: { docs: { toc: true, // 启用目录 }, }, });Vue 3vue3-vite与 Angular、Web Components 的写法完全一致仅需替换框架入口// .storybook/preview.ts — vue3-vite import { definePreview } from storybook/vue3-vite; import addonDocs from storybook/addon-docs; export default definePreview({ addons: [addonDocs()], parameters: { docs: { toc: true, // 启用目录 }, }, });// .storybook/preview.ts — angular import { definePreview } from storybook/angular; import addonDocs from storybook/addon-docs; // ...addons: [addonDocs()], parameters: { docs: { toc: true } }// .storybook/preview.ts — web-components-vite import { definePreview } from storybook/web-components-vite; import addonDocs from storybook/addon-docs; // ...addons: [addonDocs()], parameters: { docs: { toc: true } }说明toc参数的取值既可以是布尔值true按默认配置启用也可以是一个配置对象见下文全部配置项不设置该参数时文档页默认不渲染目录。按组件/故事粒度启停除了全局开启docs.toc是一个标准的 parameter因此可以在单个组件的故事文件*.stories.js|ts|tsx|svelte的 metadefault export中覆盖它。典型场景是全局已开启目录但某个组件页面结构简单、不需要目录此时用toc: { disable: true }关掉示例来自 my-component-disable-toc.md// MyComponent.stories.ts — CSF 3通用框架 // 将 your-framework 替换为实际使用的框架如 react-vite、nextjs、vue3-vite 等 import type { Meta } from storybook/your-framework; import { MyComponent } from ./MyComponent; const meta { component: MyComponent, tags: [autodocs], parameters: { docs: { toc: { disable: true, // 关闭该组件的目录 }, }, }, } satisfies Metatypeof MyComponent; export default meta;// MyComponent.stories.js — CSF 3纯 JS 写法 import { MyComponent } from ./MyComponent; export default { component: MyComponent, tags: [autodocs], parameters: { docs: { toc: { disable: true, // 关闭该组件的目录 }, }, }, };Web Components 的写法类似只是component字段使用自定义元素名// MyComponent.stories.js — web-components export default { component: my-component, tags: [autodocs], parameters: { docs: { toc: { disable: true, }, }, }, };Angular、SvelteSvelte CSF 用defineMeta、Vue 等框架的 CSF 3 写法结构相同仅替换导入入口在 CSF Next 写法中则通过preview.meta({ ... })传入相同的parameters配置。所有完整变体可查阅 my-component-disable-toc.md。toc 参数全部配置项docs.toc接受true默认配置启用或一个对象。下表汇总了 doc-block-tableofcontents.mdx 与 autodocs.mdx 中定义的全部属性及默认值这些默认值与源码实现完全一致。属性类型默认值说明contentsSelectorstring.sbdocs-content用于在页面中查找标题的容器 CSS 选择器自定义文档页布局时使用disablebooleanfalse为true时隐藏该文档页的目录仍会渲染一个空的占位容器以保持页面布局不变headingSelectorstringh3决定收录哪些标题级别例如h1, h2, h3收录前三级标题ignoreSelectorstring.docs-story *, .skip-toc需要从目录中排除的标题选择器默认排除故事块story blocks内的所有标题如需额外排除某个标题可给它加上skip-tocclasstitlestring \| null \| ReactElementTable of contents视觉隐藏目录上方的标题文本或元素设为null则不渲染标题传字符串时默认渲染为视觉隐藏的h2传入非空字符串可使其可见unsafeTocbotOptionsobject—直接透传给底层 Tocbot 库的额外配置项不保证在未来版本中继续可用完整配置示例下面是在 preview 中一次性配置全部选项的示例来自 storybook-preview-custom-toc.md// .storybook/preview.js|jsx — CSF 3 export default { parameters: { docs: { toc: { contentsSelector: .sbdocs-content, headingSelector: h1, h2, h3, ignoreSelector: #primary, title: Table of Contents, disable: false, unsafeTocbotOptions: { orderedList: false, }, }, }, }, };// .storybook/preview.ts|tsx — CSF 3 import type { Preview } from storybook/your-framework; const preview: Preview { parameters: { docs: { toc: { contentsSelector: .sbdocs-content, headingSelector: h1, h2, h3, ignoreSelector: #primary, title: Table of Contents, disable: false, unsafeTocbotOptions: { orderedList: false, }, }, }, }, }; export default preview;// .storybook/preview.tsx — CSF Next react import { definePreview } from storybook/your-framework; import addonDocs from storybook/addon-docs; export default definePreview({ addons: [addonDocs()], parameters: { docs: { toc: { contentsSelector: .sbdocs-content, headingSelector: h1, h2, h3, ignoreSelector: #primary, title: Table of Contents, disable: false, unsafeTocbotOptions: { orderedList: false, }, }, }, }, });Vue、Angular、Web Components 的 CSF Next 写法与上面一致只需替换definePreview的导入来源storybook/vue3-vite、storybook/angular、storybook/web-components-vite并同样注册addonDocs()。unsafeTocbotOptions常用于控制列表形式如orderedList: true渲染有序列表、scrollSmoothOffset、headingsOffset等 Tocbot 原生行为。在单个组件上定制同样以上对象形式也可以放进组件 story 文件的 meta 中实现这一篇文档用这套目录配置的粒度控制。例如隐藏某个特定故事的目录只需在其 metadefault export中加入toc: { disable: true }。源码原理TableOfContents 组件如何工作了解了配置再来看实现能帮助你更准确地预测行为。目录由 addon-docs 中的 TableOfContents.tsx 组件渲染其核心机制如下。基于 Tocbot 的标题扫描组件在挂载后通过useEffect调用第三方库tocbot完成目录的构建与滚动联动tocbot.init(configuration)并把所有默认值与配置项合并const configuration { tocSelector: .toc-wrapper, contentSelector: contentsSelector ?? .sbdocs-content, headingSelector: headingSelector ?? h3, ignoreSelector: ignoreSelector ?? .docs-story *, .skip-toc, headingsOffset: 40, scrollSmoothOffset: -40, orderedList: false, onClick: (e) { e.preventDefault(); // 通过 Storybook 内部 Channel 发出 NAVIGATE_URL 事件实现平滑滚动跳转 channel.emit(NAVIGATE_URL, #${headerId}); }, ...unsafeTocbotOptions, };从源码可以看到tocSelector固定为.toc-wrapper这是组件内部渲染的空容器contentSelector、headingSelector、ignoreSelector三个默认值.sbdocs-content、h3、.docs-story *, .skip-toc与文档表格中的默认值一一对应且展开顺序在unsafeTocbotOptions之前——即unsafeTocbotOptions可以覆盖除onClick/scrollEndCallback之外的任何 Tocbot 配置点击目录项时不会触发浏览器默认锚点跳转而是通过channel.emit(NAVIGATE_URL, ...)走 Storybook 内部路由保证在 iframe 化的文档环境中也能正确滚动并同步 URL 状态组件在卸载时会调用tocbot.destroy()清理避免多个文档页间互相污染。disable 时仍保留占位容器特别注意disable的处理当disable: true时组件不渲染导航内容但依然渲染一个空的aside容器。源码注释解释了原因——目录占位会影响页面布局右侧留白宽度保留空容器可以在不同页面间保持一致的排版避免页面切换时内容区宽度跳动。标题渲染与响应式标题默认文案为Table of contents以视觉隐藏sb-sr-onlyclass的h2渲染兼顾无障碍aria-labelledby传入字符串时标题可见传入null则完全不渲染标题传入 React 元素则原样包裹组件会为 ARIA 关联补上 id。侧边栏宽度固定为10rem导航在垂直方向固定并支持滚动position: fixed; overflowY: auto且通过media (max-width: 768px)在小屏下display: none隐藏与文档小屏幕隐藏的说明一致。官方配套示例 stories仓库在 template/stories/toc/ 下提供了可直接参考的示例 story覆盖各种配置组合basic.stories.ts默认toc: true的基础用法custom-selector.stories.ts自定义contentsSelector/headingSelectorcustom-title.stories.ts自定义titleignore-selector.stories.ts通过ignoreSelector排除指定标题。这些 stories 同时也是 TableOfContents.stories.tsx 驱动的组件测试用例可作为验证配置行为的参照。注意事项与常见问题以下行为来自 autodocs.mdx 的 Troubleshooting 章节与源码实现配置前建议了解单标题页面不会自动隐藏目录如果文档页只有一个匹配的标题TOC 默认仍会显示。若觉得多余可以再加一个标题或直接关闭该页的目录toc: { disable: true }。小屏幕默认隐藏源码层面宽度小于 768px 时右侧目录容器会被隐藏见 TableOfContents.tsx 中的媒体查询这是为了在窄屏下优先保证正文可读性官方文档同时提示在小屏下隐藏 TOC 目前没有不影响页面样式兼容性的内置开关。MDX 独立文档无法按页定制对于使用 MDX 编写的独立unattached文档由于当前实现不支持在该场景下定义参数docs.toc的自定义配置不会生效目录会始终回退到全局默认配置。unsafeTocbotOptions属于逃生舱它直接透传给 Tocbot绕过 Storybook 的类型约束因此不保证未来版本兼容onClick与scrollEndCallback两个回调由 Storybook 内部管理不允许通过该选项覆盖。与inline渲染的已知限制如果你通过docs.story.inline关闭了故事的 iframe 内联渲染文档页中的控件将无法联动更新故事这是当前实现的已知限制与目录本身无直接关系但排查文档页交互问题时值得留意。更多阅读Autodocs 自动文档总览含 TOC 的启用与配置章节TableOfContents Doc Block APIStorybook 全局参数 parameters用 MDX 扩展文档 与 Doc Blocks 创作文档发布文档配套代码片段storybook-preview-enable-toc.md、storybook-preview-custom-toc.md、my-component-disable-toc.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考