Storybook Vue 3 Docs 实战指南从 addon-docs 安装到 Docgen 提取与 MDX 长文文档【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文基于 Storybook 仓库内 Vue 3 框架的官方文档页code/addons/docs/docs/frameworks/VUE3.md系统讲解如何在 Vue 3 项目中配置 Storybook Docs包括storybook/addon-docs的安装与注册、vueDocgenOptions预设选项、Props 表格的生成链路、MDX 长文文档写法以及 Inline Stories 渲染控制。读完后你不仅能完成 Vue 3 项目的 Docs 落地配置还能从源码层面理解 Storybook 是如何提取 Vue 组件元信息props / events / slots的。一、Docs 在 Vue 3 项目中的定位Storybook Docs 会将你的 Story 转换为结构化的组件文档。针对 Vue 3它提供两种文档形态DocsPage自动生成的文档页零配置聚合组件的 Story、描述、docgen 注释、Props 表格和代码示例展示在 Storybook UI 的Docs标签页中完整参考见 DocsPageMDX以 Markdown 写长文文档并内联嵌入 Story、Props 表格等文档组件完整参考见 MDX。两者关系可以理解为DocsPage 是开箱即用的默认值MDX 是完全可控的自定义。Docs Addon 的总览文档见 code/addons/docs/README.md。二、安装第一步安装 Docs Addon 包注意保持所有storybook/*包版本一致yarn add -D storybook/addon-docs第二步在.storybook/main.js的addons中注册export default { addons: [storybook/addon-docs], };安装完成后所有 Story 会自动获得 DocsPage在 Storybook UI 中点击Docs标签页即可查看无需额外配置。三、Preset 选项vueDocgenOptionsaddon-docs的 Vue 预设暴露了一个配置项用于配置vue-docgen-api——一个从 Vue 组件中提取 props / events / slots 信息的工具。当你的项目使用了路径别名如/指向srcdocgen 解析器需要知道别名映射此时就需要传入vueDocgenOptionsexport default { addons: [ { name: storybook/addon-docs, options: { vueDocgenOptions: { alias: { : path.resolve(process.cwd(), src), }, }, }, }, ], };vueDocgenOptions是一个透传给vue-docgen-api的选项对象完整可用的字段以vue-docgen-api官方文档为准。典型场景monorepo 中 Storybook 位于子包目录、组件通过/components别名导入时不配置alias会导致 docgen 解析不到组件Props 表格为空。源码视角Vue 文档提取引擎的当前实现原文档描述的是vue-docgen-api的直连配置。而从当前仓库的源码结构看Vue 3 的 docgen 提取链路已经演进code/renderers/vue3/src/preset.ts 中导出了experimental_vueDocgenEngine预设它按插件懒加载两个提取引擎/** Docgen extraction engines, keyed by plugin. Each loads lazily so a project only pays for the one it uses. */ export const experimental_vueDocgenEngine async () ({ componentMeta: () import(./docgen/component-meta.ts), vueDocgenApi: () import(./docgen/vue-docgen-api.ts), });其中code/renderers/vue3/src/docgen/component-meta.ts 是基于vue-component-metaVolar 语言服务内核的主提取路径会优先使用项目根目录的tsconfig.json创建 checkercreateVueComponentMetaChecker以支持别名解析等若tsconfig.json使用了references则回退到默认 checker。它还负责一系列去噪与补全过滤空 meta、剔除嵌套 schema 以减小storybook build产物体积、合并defineEmits/ 模板 slot 的信息缺口code/renderers/vue3/src/docgen/vue-docgen-api.ts 则是对vue-docgen-api.parse的兼容封装目前作为补充手段当 Volar 提取出 events 或发现模板slot缺口时会调用vue-docgen-api的parseMulti补齐事件描述、运行时defineEmits事件以及 Options API 组件的模板 slot见applyVueDocgenApiTempFixes。也就是说原文档中的vueDocgenOptions依然有效但其底层信息源已从vue-docgen-loader 单一依赖演化为vue-component-meta 为主、vue-docgen-api 兜底的双引擎结构——这也解释了为什么 Props 表格对 events、slots 的支持在当前版本中比文档写作时期更完善。四、DocsPage零配置的自动文档安装完 Docs 后每个 Story 都会自动获得 DocsPage它从 Story 元数据、组件 docgen 信息、源代码描述等多处收集内容拼装成一个可读的文档页出现在 Storybook UI 的Docs标签。要让 DocsPage 准确关联到你的组件关键是在 Story 的默认导出meta中填写component字段import { InfoButton } from ./InfoButton.vue; export default { title: InfoButton, component: InfoButton, };component字段是 Docs 将Story与组件类型信息关联起来的锚点没有它DocsPage 仍能渲染 Story但 Props 表格、Args 分类等依赖 docgen 的部分将无从匹配。五、Props 表格Props 表格参考文档是 Vue 3 Docs 的核心能力之一。对 Vue它依赖上文提到的 docgen 提取链路并对三种 Vue 一等公民属性提供了原生支持props组件的 props 声明defineProps/ Options APIpropsevents组件事件defineEmits/ Options APIemitsslots模板插槽slot声明及 slot props。生成 Props 表格的前提条件已安装并注册storybook/addon-docs项目路径别名等已按需通过vueDocgenOptions.alias配置见第三节Story meta 中填写了component字段见第四节示例。满足后ArgsTable或 DocsPage 的 Props 区块即会自动列出组件的 props / events / slots 及其类型。六、MDX长文文档MDX 适合撰写长篇组件文档用 Markdown 行文并在文中直接嵌入 Story、ArgsTable 等文档组件。前置依赖与配置Docs 对react存在 peer dependencyMDX 编译工具链需要。如果你要写 MDX 文档可能需要显式补装yarn add -D react然后更新.storybook/main.js让 stories glob 匹配.mdx文件export default { stories: [../src/stories/**/*.stories.(js|mdx)], };MDX 文件示例下面是一个 Vue 3 组件的完整 MDX 示例继承自官方文档原文可复制后按你的组件名修改import { Meta, Story, ArgsTable } from storybook/addon-docs; import { InfoButton } from ./InfoButton.vue; Meta titleInfoButton component{InfoButton} / # InfoButton Some **markdown** description, or whatever you want. Story namebasic height400px{{ components: { InfoButton }, template: info-button labelI\m a button!/, }}/Story ## ArgsTable ArgsTable of{InfoButton} /示例要点Meta component{InfoButton} /将 MDX 页与组件绑定使 ArgsTable 和 docgen 信息生效Story内联传入了一个 Options API 风格的渲染对象componentstemplate在 MDX 中直接渲染任意模板ArgsTable of{InfoButton} /渲染该组件的 Args 表格。原文档还特别注明component在Meta与 story 中重复声明是当时5.x 时期的冗余设计。如果你在使用老版本的示例代码遇到component 声明两次的困惑这正是原因。七、Inline Stories内联渲染与 iframe 高度Storybook Docs 默认以**内联inline**方式渲染所有 Vue Story。如果需要将 Story 渲染在 iframe 中例如隔离全局样式可以使用docs.stories.inline参数iframe 模式下的默认高度可配置原文档标注为 60px配置键为docs.story.iframeHeight。对全部 Story 生效时修改.storybook/preview.jsexport const parameters { docs: { story: { inline: false } } };该参数同样可以下沉到单个 Story 或 meta 级别。从当前源码看高度的取值优先级与回退值定义在 code/addons/docs/src/blocks/blocks/Story.tsxconst storyParameters (docs.story || {}) as StoryParameters { iframeHeight?: string }; // ... const height props.height ?? storyParameters.height ?? storyParameters.iframeHeight ?? 100px;即Story height...组件属性优先其次是docs.story.height再次是docs.story.iframeHeight都没有时回退到100px——可见当前版本对 iframe 高度的兜底值已从文档早期标注的 60px 演进为 100pxiframeHeight作为旧配置键仍被兼容读取。参数类型定义可参考 code/addons/docs/src/types.ts。八、延伸阅读围绕 Storybook Docs 的完整参考文档均位于本仓库内DocsPageDocsPage 的组成与工作机制MDXMDX 块组件全集Meta/Canvas/Story/ArgsTable等Props 表格props 表与 TypeScript 配置FAQ、Recipes、Theming。Vue 3 渲染器侧的配套实现与测试可作为深入阅读入口Vue3 渲染器源码、docgen 工作进程、以及沙箱中的示例组件 code/renderers/vue3/template/stories_vue3-vite-default-ts其中包含ReactiveArgs、ScopedSlots、GlobalSetup等典型 Vue 3 特性 Story可作为 Docs 配置的验证样本。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/7 1:45:29 · 阅读 1.2k Storybook Vue 3 Docs 实战指南：从 addon-docs 安装到 Docgen 提取与 MDX 长文文档
Storybook Vue 3 Docs 实战指南从 addon-docs 安装到 Docgen 提取与 MDX 长文文档【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文基于 Storybook 仓库内 Vue 3 框架的官方文档页code/addons/docs/docs/frameworks/VUE3.md系统讲解如何在 Vue 3 项目中配置 Storybook Docs包括storybook/addon-docs的安装与注册、vueDocgenOptions预设选项、Props 表格的生成链路、MDX 长文文档写法以及 Inline Stories 渲染控制。读完后你不仅能完成 Vue 3 项目的 Docs 落地配置还能从源码层面理解 Storybook 是如何提取 Vue 组件元信息props / events / slots的。一、Docs 在 Vue 3 项目中的定位Storybook Docs 会将你的 Story 转换为结构化的组件文档。针对 Vue 3它提供两种文档形态DocsPage自动生成的文档页零配置聚合组件的 Story、描述、docgen 注释、Props 表格和代码示例展示在 Storybook UI 的Docs标签页中完整参考见 DocsPageMDX以 Markdown 写长文文档并内联嵌入 Story、Props 表格等文档组件完整参考见 MDX。两者关系可以理解为DocsPage 是开箱即用的默认值MDX 是完全可控的自定义。Docs Addon 的总览文档见 code/addons/docs/README.md。二、安装第一步安装 Docs Addon 包注意保持所有storybook/*包版本一致yarn add -D storybook/addon-docs第二步在.storybook/main.js的addons中注册export default { addons: [storybook/addon-docs], };安装完成后所有 Story 会自动获得 DocsPage在 Storybook UI 中点击Docs标签页即可查看无需额外配置。三、Preset 选项vueDocgenOptionsaddon-docs的 Vue 预设暴露了一个配置项用于配置vue-docgen-api——一个从 Vue 组件中提取 props / events / slots 信息的工具。当你的项目使用了路径别名如/指向srcdocgen 解析器需要知道别名映射此时就需要传入vueDocgenOptionsexport default { addons: [ { name: storybook/addon-docs, options: { vueDocgenOptions: { alias: { : path.resolve(process.cwd(), src), }, }, }, }, ], };vueDocgenOptions是一个透传给vue-docgen-api的选项对象完整可用的字段以vue-docgen-api官方文档为准。典型场景monorepo 中 Storybook 位于子包目录、组件通过/components别名导入时不配置alias会导致 docgen 解析不到组件Props 表格为空。源码视角Vue 文档提取引擎的当前实现原文档描述的是vue-docgen-api的直连配置。而从当前仓库的源码结构看Vue 3 的 docgen 提取链路已经演进code/renderers/vue3/src/preset.ts 中导出了experimental_vueDocgenEngine预设它按插件懒加载两个提取引擎/** Docgen extraction engines, keyed by plugin. Each loads lazily so a project only pays for the one it uses. */ export const experimental_vueDocgenEngine async () ({ componentMeta: () import(./docgen/component-meta.ts), vueDocgenApi: () import(./docgen/vue-docgen-api.ts), });其中code/renderers/vue3/src/docgen/component-meta.ts 是基于vue-component-metaVolar 语言服务内核的主提取路径会优先使用项目根目录的tsconfig.json创建 checkercreateVueComponentMetaChecker以支持别名解析等若tsconfig.json使用了references则回退到默认 checker。它还负责一系列去噪与补全过滤空 meta、剔除嵌套 schema 以减小storybook build产物体积、合并defineEmits/ 模板 slot 的信息缺口code/renderers/vue3/src/docgen/vue-docgen-api.ts 则是对vue-docgen-api.parse的兼容封装目前作为补充手段当 Volar 提取出 events 或发现模板slot缺口时会调用vue-docgen-api的parseMulti补齐事件描述、运行时defineEmits事件以及 Options API 组件的模板 slot见applyVueDocgenApiTempFixes。也就是说原文档中的vueDocgenOptions依然有效但其底层信息源已从vue-docgen-loader 单一依赖演化为vue-component-meta 为主、vue-docgen-api 兜底的双引擎结构——这也解释了为什么 Props 表格对 events、slots 的支持在当前版本中比文档写作时期更完善。四、DocsPage零配置的自动文档安装完 Docs 后每个 Story 都会自动获得 DocsPage它从 Story 元数据、组件 docgen 信息、源代码描述等多处收集内容拼装成一个可读的文档页出现在 Storybook UI 的Docs标签。要让 DocsPage 准确关联到你的组件关键是在 Story 的默认导出meta中填写component字段import { InfoButton } from ./InfoButton.vue; export default { title: InfoButton, component: InfoButton, };component字段是 Docs 将Story与组件类型信息关联起来的锚点没有它DocsPage 仍能渲染 Story但 Props 表格、Args 分类等依赖 docgen 的部分将无从匹配。五、Props 表格Props 表格参考文档是 Vue 3 Docs 的核心能力之一。对 Vue它依赖上文提到的 docgen 提取链路并对三种 Vue 一等公民属性提供了原生支持props组件的 props 声明defineProps/ Options APIpropsevents组件事件defineEmits/ Options APIemitsslots模板插槽slot声明及 slot props。生成 Props 表格的前提条件已安装并注册storybook/addon-docs项目路径别名等已按需通过vueDocgenOptions.alias配置见第三节Story meta 中填写了component字段见第四节示例。满足后ArgsTable或 DocsPage 的 Props 区块即会自动列出组件的 props / events / slots 及其类型。六、MDX长文文档MDX 适合撰写长篇组件文档用 Markdown 行文并在文中直接嵌入 Story、ArgsTable 等文档组件。前置依赖与配置Docs 对react存在 peer dependencyMDX 编译工具链需要。如果你要写 MDX 文档可能需要显式补装yarn add -D react然后更新.storybook/main.js让 stories glob 匹配.mdx文件export default { stories: [../src/stories/**/*.stories.(js|mdx)], };MDX 文件示例下面是一个 Vue 3 组件的完整 MDX 示例继承自官方文档原文可复制后按你的组件名修改import { Meta, Story, ArgsTable } from storybook/addon-docs; import { InfoButton } from ./InfoButton.vue; Meta titleInfoButton component{InfoButton} / # InfoButton Some **markdown** description, or whatever you want. Story namebasic height400px{{ components: { InfoButton }, template: info-button labelI\m a button!/, }}/Story ## ArgsTable ArgsTable of{InfoButton} /示例要点Meta component{InfoButton} /将 MDX 页与组件绑定使 ArgsTable 和 docgen 信息生效Story内联传入了一个 Options API 风格的渲染对象componentstemplate在 MDX 中直接渲染任意模板ArgsTable of{InfoButton} /渲染该组件的 Args 表格。原文档还特别注明component在Meta与 story 中重复声明是当时5.x 时期的冗余设计。如果你在使用老版本的示例代码遇到component 声明两次的困惑这正是原因。七、Inline Stories内联渲染与 iframe 高度Storybook Docs 默认以**内联inline**方式渲染所有 Vue Story。如果需要将 Story 渲染在 iframe 中例如隔离全局样式可以使用docs.stories.inline参数iframe 模式下的默认高度可配置原文档标注为 60px配置键为docs.story.iframeHeight。对全部 Story 生效时修改.storybook/preview.jsexport const parameters { docs: { story: { inline: false } } };该参数同样可以下沉到单个 Story 或 meta 级别。从当前源码看高度的取值优先级与回退值定义在 code/addons/docs/src/blocks/blocks/Story.tsxconst storyParameters (docs.story || {}) as StoryParameters { iframeHeight?: string }; // ... const height props.height ?? storyParameters.height ?? storyParameters.iframeHeight ?? 100px;即Story height...组件属性优先其次是docs.story.height再次是docs.story.iframeHeight都没有时回退到100px——可见当前版本对 iframe 高度的兜底值已从文档早期标注的 60px 演进为 100pxiframeHeight作为旧配置键仍被兼容读取。参数类型定义可参考 code/addons/docs/src/types.ts。八、延伸阅读围绕 Storybook Docs 的完整参考文档均位于本仓库内DocsPageDocsPage 的组成与工作机制MDXMDX 块组件全集Meta/Canvas/Story/ArgsTable等Props 表格props 表与 TypeScript 配置FAQ、Recipes、Theming。Vue 3 渲染器侧的配套实现与测试可作为深入阅读入口Vue3 渲染器源码、docgen 工作进程、以及沙箱中的示例组件 code/renderers/vue3/template/stories_vue3-vite-default-ts其中包含ReactiveArgs、ScopedSlots、GlobalSetup等典型 Vue 3 特性 Story可作为 Docs 配置的验证样本。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考