Storybook Autodocs 实战指南在组件 meta 中使用 autodocs 标签启用自动生成文档【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇聚焦 Storybook 中一个高频却容易用错位置的配置如何在单个组件的故事文件CSF 文件的 meta / 默认导出里通过tags: [autodocs]标签为该组件单独启用 Autodocs 自动文档页。文章完整覆盖 Angular、React、Vue、Svelte、Web Components 等各渲染器的写法含 CSF 3 与 CSF Next 两种形态并结合核心源码说明这个标签从索引生成、侧边栏过滤到文档页渲染的完整链路读完后你能够按项目技术栈直接复制对应配置并理解 Storybook 是如何依据该标签决定是否为这个组件生成 Docs 页的。autodocs 标签是什么Storybook 的系统标签Autodocs 的启用不依赖独立的开关而是完全通过 Tags 机制 控制。核心规则是只要某个 CSF 文件中至少有一个 story 带有autodocs标签Storybook 就会为该文件对应组件生成一个文档页并放在侧边栏组件树的根层级位置。详见 Autodocs 官方文档。在源码中autodocs是 Storybook 定义的系统标签之一与attached-mdx、unattached-mdx、play-fn、test-fn、dev、test、manifest并列统一定义在 Tag 常量 中/** System tags used throughout Storybook for categorizing and filtering stories and docs entries. */ export const Tag { /** Indicates that autodocs should be generated for this component */ AUTODOCS: autodocs, /** MDX documentation attached to a components stories file */ ATTACHED_MDX: attached-mdx, // ... play-fn、test-fn、dev、test、manifest 等 };注释说明得很直接该标签的语义就是指示应为此组件生成 autodocs。文档页一旦生成会成为一个独立的 docs 条目参与索引与过滤这一点的实现细节后文结合源码展开。在 meta 中启用 autodocs各渲染器完整写法启用 Autodocs 有两个层级一是全局层在.storybook/preview.jsx|tsx的tags中统一启用对应 tags-autodocs-in-preview 片段二是组件meta层即本文档的核心——在故事文件的默认导出 meta 中添加tags: [autodocs]使该组件及其文件内的所有 story 都进入自动文档页。下面按渲染器逐一给出可复制的写法。通用写法Common / CSF 3对绝大多数 React 系框架react-vite、nextjs、vue3-vite 等TS 与 JS 两种形式如下// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. import type { Meta } from storybook/your-framework; import { Button } from ./Button; const meta { component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], } satisfies Metatypeof Button; export default meta;import { Button } from ./Button; export default { component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], };注意两点细节satisfies Metatypeof Button是 CSF 3 推荐写法既保留类型推导又提供 meta 字段校验component属性决定文档页头部展示哪个组件的元数据Args 表以此为主tags: [autodocs]则触发文档页生成并包含该文件内的所有 story。Angularimport type { Meta } from storybook/angular; import { Button } from ./Button.component; const meta: MetaButton { component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], }; export default meta;SvelteSvelte 项目常见两种风格通过storybook/addon-svelte-csf的defineMeta辅助函数或直接使用纯 JS 默认导出。script module import { defineMeta } from storybook/addon-svelte-csf; import Button from ./Button.svelte; const { Story } defineMeta({ component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], }); /script// Replace your-framework with svelte-vite or sveltekit import type { Meta } from storybook/your-framework; import Button from ./Button.svelte; const meta { component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], } satisfies Metatypeof Button; export default meta;import Button from ./Button.svelte; export default { component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], };Web ComponentsWeb Components 场景下component直接填写自定义元素标签名字符串无需导入组件类import type { Meta } from storybook/web-components-vite; const meta: Meta { title: Button, component: demo-button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], }; export default meta;export default { title: Button, component: demo-button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], };由于没有 Docgen 可直接分析的类型信息文档页的 Args/ArgTypes 会依赖你在 meta 中手动声明的args/argTypes这是使用 Web Components 时的一个重要前提。CSF Next 形态React / Vue / Web ComponentsCSF Next 将预览层配置上收到.storybook/preview并以preview.meta()工厂函数声明 meta写法更简洁但autodocs标签的语义完全一致import preview from ../.storybook/preview; import { Button } from ./Button; const meta preview.meta({ component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], });Vue 与 Web Components 同理import preview from ../.storybook/preview; import Button from ./Button.vue; const meta preview.meta({ component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], });import preview from ../.storybook/preview; const meta preview.meta({ component: demo-button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], });以上写法与 Autodocs 文档中组件级启用一节 引用的 tags-autodocs-in-meta 片段源文件 完全一致可按渲染器选择对应 Tab 复制。标签生效的底层链路从索引到渲染理解这条链路有助于排查加了标签却没有文档页这类问题。整个流程分三步。第一步索引生成时创建 docs 条目。构建 Storybook 索引时索引生成器会检查每个故事文件如果autodocs 全局启用或该文件 meta 上带有 autodocs 标签就会为这个文件追加一个指向该 CSF 文件的 docs 条目。相关逻辑见 StoryIndexGenerator文件头部注释即写明If the stories haveautodocsenabled, a docs entry is added pointing to the story file关键判断集中在该文件 L485 附近的 a/b 两个条件分支。第二步渲染侧把 docs 条目按 CSF 文件渲染。文档页的渲染入口是 CsfDocsRender 类其类注释明确把 Autodocs 列为核心用例Autodocs, where there is no story, and we fall back to the globally defined templateAutodocs 场景下没有独立的 docs story回退到全局定义的模板。在构造 DocsContext 时有一行关键代码CsfDocsRender.ts#L115-L118// Autodocs pages filter the CSF files stories down to autodocs-tagged ones when picking // the Primary / story; a custom docs.page template on an autodocs entry does not change // that (the entry is still not an MDX entry). docsContext.filterByAutodocs !isMdxEntry(this.entry);从源码结构看autodocs 文档页在挑选Primary /故事时会把 CSF 文件中的 story 过滤为带autodocs标签的那些MDX 条目则不走这条过滤路径。这也解释了为什么标签要打在 meta 上——meta 上的 tags 会被文件内所有 story 继承从而保证整组 story 都进入文档页。第三步侧边栏与 URL 过滤识别 docs 条目。管理器侧的 tags 过滤模块 中computeStaticFilterFn用如下方式区分条目种类L71-L86// Docs entry kinds are distinguished by system tags at index time: // - autodocs: type docs, no attached-mdx / unattached-mdx (importPath is the CSF file) // - attached MDX: attached-mdx // - unattached MDX: unattached-mdx const isCsfAutodocsEntry item.type docs !tags.includes(TagEnum.ATTACHED_MDX) !tags.includes(TagEnum.UNATTACHED_MDX); return ( (tags.includes(TagEnum.DEV) || isCsfAutodocsEntry) tags.filter((tag) staticExcludeTags[tag]).length 0 );即type为docs且不带 MDX 系统标签的条目就是 CSF autodocs 页它即使不带dev标签也会保留在侧边栏中同时尊重excludeFromSidebar配置。这意味着 autodocs 文档条目会继承 CSF meta 上的 tags——如果你 meta 里同时写了!devautodocs 页依然会出现在侧边栏源码注释明确说明这是有意为之的行为这是排查为什么我的排除标签没隐藏 Docs 页时的关键事实。关闭与排除用 !autodocs 反向移除标签标签体系支持!前缀排除语义因此组件级启用后也可以精细关闭移除整个组件的 autodocs在 meta 中写tags: [!autodocs]覆盖全局或更高优先级设置该组件不再生成文档页对应 tags-autodocs-remove-component 片段仅排除某个 story在单个 story 上写tags: [!autodocs]该 story 不出现在自动文档页其余 story 不受影响对应 tags-autodocs-remove-story 片段。标签的优先级、合并与排除规则完整定义在 Tags 文档 中meta 上的 tags 会覆盖 preview 全局 tagsstory 级 tags 又覆盖 meta 级 tags!前缀表达排除。验证与延伸配置完成后运行 Storybook dev 模式即可验证侧边栏对应组件节点下应出现一个与组件同级的 Docs 页默认页名由docs.defaultName控制默认 Docs页面自动聚合 Description、Story主故事、Args/ArgTypes 表、Stories 列表等区块。如果你需要进一步定制文档页自定义模板、目录 TOC、子组件文档、Monorepo 下的 import 修复等完整方案见 Autodocs 主文档标签本身的优先级与过滤语义见 Tags 文档系统标签常量定义可参考 code/core/src/shared/constants/tags.ts。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Storybook Autodocs 实战指南：在组件 meta 中使用 autodocs 标签启用自动生成文档
Storybook Autodocs 实战指南在组件 meta 中使用 autodocs 标签启用自动生成文档【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇聚焦 Storybook 中一个高频却容易用错位置的配置如何在单个组件的故事文件CSF 文件的 meta / 默认导出里通过tags: [autodocs]标签为该组件单独启用 Autodocs 自动文档页。文章完整覆盖 Angular、React、Vue、Svelte、Web Components 等各渲染器的写法含 CSF 3 与 CSF Next 两种形态并结合核心源码说明这个标签从索引生成、侧边栏过滤到文档页渲染的完整链路读完后你能够按项目技术栈直接复制对应配置并理解 Storybook 是如何依据该标签决定是否为这个组件生成 Docs 页的。autodocs 标签是什么Storybook 的系统标签Autodocs 的启用不依赖独立的开关而是完全通过 Tags 机制 控制。核心规则是只要某个 CSF 文件中至少有一个 story 带有autodocs标签Storybook 就会为该文件对应组件生成一个文档页并放在侧边栏组件树的根层级位置。详见 Autodocs 官方文档。在源码中autodocs是 Storybook 定义的系统标签之一与attached-mdx、unattached-mdx、play-fn、test-fn、dev、test、manifest并列统一定义在 Tag 常量 中/** System tags used throughout Storybook for categorizing and filtering stories and docs entries. */ export const Tag { /** Indicates that autodocs should be generated for this component */ AUTODOCS: autodocs, /** MDX documentation attached to a components stories file */ ATTACHED_MDX: attached-mdx, // ... play-fn、test-fn、dev、test、manifest 等 };注释说明得很直接该标签的语义就是指示应为此组件生成 autodocs。文档页一旦生成会成为一个独立的 docs 条目参与索引与过滤这一点的实现细节后文结合源码展开。在 meta 中启用 autodocs各渲染器完整写法启用 Autodocs 有两个层级一是全局层在.storybook/preview.jsx|tsx的tags中统一启用对应 tags-autodocs-in-preview 片段二是组件meta层即本文档的核心——在故事文件的默认导出 meta 中添加tags: [autodocs]使该组件及其文件内的所有 story 都进入自动文档页。下面按渲染器逐一给出可复制的写法。通用写法Common / CSF 3对绝大多数 React 系框架react-vite、nextjs、vue3-vite 等TS 与 JS 两种形式如下// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. import type { Meta } from storybook/your-framework; import { Button } from ./Button; const meta { component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], } satisfies Metatypeof Button; export default meta;import { Button } from ./Button; export default { component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], };注意两点细节satisfies Metatypeof Button是 CSF 3 推荐写法既保留类型推导又提供 meta 字段校验component属性决定文档页头部展示哪个组件的元数据Args 表以此为主tags: [autodocs]则触发文档页生成并包含该文件内的所有 story。Angularimport type { Meta } from storybook/angular; import { Button } from ./Button.component; const meta: MetaButton { component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], }; export default meta;SvelteSvelte 项目常见两种风格通过storybook/addon-svelte-csf的defineMeta辅助函数或直接使用纯 JS 默认导出。script module import { defineMeta } from storybook/addon-svelte-csf; import Button from ./Button.svelte; const { Story } defineMeta({ component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], }); /script// Replace your-framework with svelte-vite or sveltekit import type { Meta } from storybook/your-framework; import Button from ./Button.svelte; const meta { component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], } satisfies Metatypeof Button; export default meta;import Button from ./Button.svelte; export default { component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], };Web ComponentsWeb Components 场景下component直接填写自定义元素标签名字符串无需导入组件类import type { Meta } from storybook/web-components-vite; const meta: Meta { title: Button, component: demo-button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], }; export default meta;export default { title: Button, component: demo-button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], };由于没有 Docgen 可直接分析的类型信息文档页的 Args/ArgTypes 会依赖你在 meta 中手动声明的args/argTypes这是使用 Web Components 时的一个重要前提。CSF Next 形态React / Vue / Web ComponentsCSF Next 将预览层配置上收到.storybook/preview并以preview.meta()工厂函数声明 meta写法更简洁但autodocs标签的语义完全一致import preview from ../.storybook/preview; import { Button } from ./Button; const meta preview.meta({ component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], });Vue 与 Web Components 同理import preview from ../.storybook/preview; import Button from ./Button.vue; const meta preview.meta({ component: Button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], });import preview from ../.storybook/preview; const meta preview.meta({ component: demo-button, // Enables auto-generated documentation for this component and includes all stories in this file tags: [autodocs], });以上写法与 Autodocs 文档中组件级启用一节 引用的 tags-autodocs-in-meta 片段源文件 完全一致可按渲染器选择对应 Tab 复制。标签生效的底层链路从索引到渲染理解这条链路有助于排查加了标签却没有文档页这类问题。整个流程分三步。第一步索引生成时创建 docs 条目。构建 Storybook 索引时索引生成器会检查每个故事文件如果autodocs 全局启用或该文件 meta 上带有 autodocs 标签就会为这个文件追加一个指向该 CSF 文件的 docs 条目。相关逻辑见 StoryIndexGenerator文件头部注释即写明If the stories haveautodocsenabled, a docs entry is added pointing to the story file关键判断集中在该文件 L485 附近的 a/b 两个条件分支。第二步渲染侧把 docs 条目按 CSF 文件渲染。文档页的渲染入口是 CsfDocsRender 类其类注释明确把 Autodocs 列为核心用例Autodocs, where there is no story, and we fall back to the globally defined templateAutodocs 场景下没有独立的 docs story回退到全局定义的模板。在构造 DocsContext 时有一行关键代码CsfDocsRender.ts#L115-L118// Autodocs pages filter the CSF files stories down to autodocs-tagged ones when picking // the Primary / story; a custom docs.page template on an autodocs entry does not change // that (the entry is still not an MDX entry). docsContext.filterByAutodocs !isMdxEntry(this.entry);从源码结构看autodocs 文档页在挑选Primary /故事时会把 CSF 文件中的 story 过滤为带autodocs标签的那些MDX 条目则不走这条过滤路径。这也解释了为什么标签要打在 meta 上——meta 上的 tags 会被文件内所有 story 继承从而保证整组 story 都进入文档页。第三步侧边栏与 URL 过滤识别 docs 条目。管理器侧的 tags 过滤模块 中computeStaticFilterFn用如下方式区分条目种类L71-L86// Docs entry kinds are distinguished by system tags at index time: // - autodocs: type docs, no attached-mdx / unattached-mdx (importPath is the CSF file) // - attached MDX: attached-mdx // - unattached MDX: unattached-mdx const isCsfAutodocsEntry item.type docs !tags.includes(TagEnum.ATTACHED_MDX) !tags.includes(TagEnum.UNATTACHED_MDX); return ( (tags.includes(TagEnum.DEV) || isCsfAutodocsEntry) tags.filter((tag) staticExcludeTags[tag]).length 0 );即type为docs且不带 MDX 系统标签的条目就是 CSF autodocs 页它即使不带dev标签也会保留在侧边栏中同时尊重excludeFromSidebar配置。这意味着 autodocs 文档条目会继承 CSF meta 上的 tags——如果你 meta 里同时写了!devautodocs 页依然会出现在侧边栏源码注释明确说明这是有意为之的行为这是排查为什么我的排除标签没隐藏 Docs 页时的关键事实。关闭与排除用 !autodocs 反向移除标签标签体系支持!前缀排除语义因此组件级启用后也可以精细关闭移除整个组件的 autodocs在 meta 中写tags: [!autodocs]覆盖全局或更高优先级设置该组件不再生成文档页对应 tags-autodocs-remove-component 片段仅排除某个 story在单个 story 上写tags: [!autodocs]该 story 不出现在自动文档页其余 story 不受影响对应 tags-autodocs-remove-story 片段。标签的优先级、合并与排除规则完整定义在 Tags 文档 中meta 上的 tags 会覆盖 preview 全局 tagsstory 级 tags 又覆盖 meta 级 tags!前缀表达排除。验证与延伸配置完成后运行 Storybook dev 模式即可验证侧边栏对应组件节点下应出现一个与组件同级的 Docs 页默认页名由docs.defaultName控制默认 Docs页面自动聚合 Description、Story主故事、Args/ArgTypes 表、Stories 列表等区块。如果你需要进一步定制文档页自定义模板、目录 TOC、子组件文档、Monorepo 下的 import 修复等完整方案见 Autodocs 主文档标签本身的优先级与过滤语义见 Tags 文档系统标签常量定义可参考 code/core/src/shared/constants/tags.ts。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考