Storybook Angular 接入 Compodoc：自动生成组件文档与 Controls 的完整配置指南

Storybook Angular 接入 Compodoc自动生成组件文档与 Controls 的完整配置指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook 的 Angular 框架通过内置的 Compodoc 集成可以从组件源码中的 JSDoc 注释自动生成documentation.json并以此驱动 Controls 面板与自动文档Autodocs的展示。本文以 angular-add-compodoc.md 与 Angular 官方接入文档 为核心结合仓库源码完整讲解在 Angular 项目中启用 Compodoc 的安装、Builder 配置、preview 接线三大步骤并深入说明其底层数据流。读完本文你将能够在自己的 Angular Storybook 项目中一键复现这套文档生成链路。一、Compodoc 集成解决什么问题在 Angular 组件开发中开发者通常会围绕组件属性维护两类信息Input/Output的类型与含义以及组件的使用文档。这些信息分散在源码注释里容易与 UI 展示脱节。Storybook 的 Angular 框架将 Compodoc 构建进工作流实现「注释即文档」当你在组件、指令、管道上方的注释中书写 JSDoc并重点为Input、Output补充说明时Compodoc 会把这些信息序列化到一份documentation.jsonStorybook 的预览端读取该 JSON在Controls 面板渲染可交互的控件并在Docs / Autodocs 页面生成组件参数表。从源码结构看这套能力分成三段独立代码Builder 侧负责“跑 Compodoc 出 JSON”run-compodoc.ts预览端入口负责“接收 JSON”addons/docs/src/angular/index.ts而解析/提取逻辑收敛在共享包storybook/angular-compodocbrowser.ts。下文按三段链路逐步配置。二、安装 compodoc/compodoc首先在 Angular 项目中将 Compodoc 安装为开发依赖。官方提供 npm / pnpm / yarn 三种包管理器命令见 compodoc-install.md# npm npm install compodoc/compodoc --save-dev # pnpm pnpm add --save-dev compodoc/compodoc # yarn yarn add --dev compodoc/compodoc安装后无需在package.json中手动串联compodoc命令Storybook 的 Angular Builder 已把执行逻辑内置你只负责开启选项见下一节。官方文档特别提醒如果你此前用docs:json: compodoc -p tsconfig.json -e json -d ./documentation之类的脚本手动生成迁移到 Builder 方案后可以安全删除相关 script避免重复运行。三、在 angular.json 中开启 Compodoc以 Angular Workspace 为标准场景在angular.json里项目级architect的storybook与build-storybook两个 target 上同时开启两个选项{ projects: { your-project: { architect: { storybook: { builder: storybook/angular:start-storybook, options: { // Add these compodoc: true, compodocArgs: [ -e, json, -d, // Where to store the generated documentation. Its usually the root of your Angular project. // Its not necessarily the root of your Angular Workspace! . ] } }, build-storybook: { builder: storybook/angular:build-storybook, options: { // Add these compodoc: true, compodocArgs: [-e, json, -d, .] } } } } } }3.1 选项语义与默认行为配置项含义compodoc是否在启动/构建 Storybook 之前执行 Compodoc。取true时每次运行都会重新生成documentation.jsoncompodocArgs透传给compodoc/compodocCLI 的参数数组例如[-e, json]关键细节藏在默认值的补全逻辑里可以对照 run-compodoc.ts 源码确认-ptsconfig 路径若你的compodocArgs中没有提供-pBuilder 会自动追加项目当前的 tsconfig 路径提供则尊重你的值。-d/--output输出目录若你的compodocArgs中没有提供Builder 会自动追加工作区根目录context.workspaceRoot上面示例显式给出-d .属于常规写法。-e导出格式json表示只输出 JSON 供 Storybook 使用文档说明也强调需要 Compodoc 的浏览器可读 HTML 站点时应另行单独调用 Compodoc 生成。相对路径为避免 Windows 上绝对路径问题源码会对 tsconfig 做一次relative(., ...)转换后再传给 Compodoc。Builder 会通过包管理器执行compodoc并附带任务状态输出Generating documentation with Compodoc/Compodoc finished successfully。同一参数的端到端调用可以在 start-storybook 的测试用例 中看到例如期望生成[compodoc, -p, ./storybook/tsconfig.ts, -d, ., -e, json]这样的命令序列。说明以上两个选项同样适用于 Vite 版框架storybook/angular-vite但在该框架默认启用experimentalDocgenServer特性的新管线中不再生效详见第六节。3.2 自动安装路径如果你是在已有 Storybook 项目之外从零开始更省事的方式是直接执行npx storybooklatest initinit会自动探测 Angular 项目并询问是否配置 Compodoc帮你完成上述angular.json写入随后的版本升级也可用npx storybooklatest automigrate自动修复/迁移相关配置。四、在 preview 中注入 documentation.jsonangular.json只负责“生成 JSON”真正让 Storybook 预览端读取 JSON 的是.storybook/preview.ts里的setCompodocJson调用——这正是 angular-add-compodoc.md 这个代码片段所演示的内容。4.1 CSF 3 写法import type { Preview } from storybook/angular; // Add these import { setCompodocJson } from storybook/addon-docs/angular; import docJson from ../documentation.json; setCompodocJson(docJson); const preview: Preview { // ... }; export default preview;4.2 CSF Next实验特性写法新版框架同时支持以definePreview声明预览配置的写法接线逻辑完全相同import { definePreview } from storybook/angular; // Add these import { setCompodocJson } from storybook/addon-docs/angular; import docJson from ../documentation.json; setCompodocJson(docJson); const preview definePreview({ // ... }); export default preview;4.3 三个容易踩坑的路径问题documentation.json的存放位置默认生成在 Angular项目根目录也就是compodocArgs中-d指向的目录它不一定是 AngularWorkspace根目录。上面的 import 路径../documentation.json以.storybook/为相对起点请根据你的实际目录结构调整。输出目录一致性请确保compodocArgs里的-d与你 import 的路径一致否则会出现“JSON 已生成但 preview 读到旧文件”的错觉。执行时机setCompodocJson只在预览启动时执行一次因此 Builder 每次运行 Storybook 前都会重新生成documentation.json保证注释改动即时生效。五、底层数据流从 JSON 到 Controls 与 Docs理解setCompodocJson做了什么有助于排查“面板没内容”的问题。逐层看源码写入全局。setCompodocJson把 JSON 挂到global.__STORYBOOK_COMPODOC_JSON__上。旧版入口见 addons/docs/src/angular/index.tsexport const setCompodocJson (compodocJson: any) { (globalThis as any).__STORYBOOK_COMPODOC_JSON__ compodocJson; };消费读取。共享适配器 browser.ts 定义配套的getCompodocJson返回global.__STORYBOOK_COMPODOC_JSON__。提取参数类型。storybook/angular客户端模块compodoc.ts再从storybook/angular-compodoc/browser导出extractArgTypes、extractComponentDescription、findComponentByName、checkValidCompodocJson等工具Controls 与 Docs 的参数表本质上由这些函数基于同一份 Compodoc JSON 计算得到。因此整条链路是JSDoc 注释 → CompodocBuilder 触发→documentation.json→setCompodocJson挂全局 →extractArgTypes等工具消费 → Controls / Docs 渲染。任一环节断裂都会表现为“文档缺失”排查时可按此顺序定位。5.1 需要写什么样的注释文档明确建议把解释性注释写在组件中 Storybook 会展示的元素上尤其是Input与Output——它们正是用户能在 UI 中通过 Controls 交互的部分。例如Component({ selector: app-button, ... }) export class ButtonComponent { /** 按钮的主文案 */ Input() label ; /** 点击后是否禁用 */ Input() disabled false; /** 点击事件 */ Output() clicked new EventEmittervoid(); }这类注释会以参数表/描述的形式出现在 Autodocs 与 Controls 中是 Compodoc 集成最直接的收益点。六、兼容性边界Vite 框架与 experimentalDocgenServer仓库当前同时维护两套 Angular 框架Compodoc 的适用前提有所不同需要区分清楚避免配置后“无效”storybook/angularWebpack 版Builder 为storybook/angular:start-storybook/build-storybook本文的完整配置链路原生生效这是 Compodoc 集成的主阵地。storybook/angular-vite该框架的默认文档生成走服务端experimentalDocgenServer新管线不再读取 Compodoc 产物。此时setCompodocJson会静默返回并打印一次会话级警告源码见 index.ts提示可以删除该调用与documentation.json的 import。若你在angular-vite项目中通过关闭experimentalDocgenServer回到 Compodoc 旧管线那么第六节之前的所有配置依然可用但该兼容路径已在路线图中标注为未来废弃计划在 Storybook 12 移除仅建议作为迁移过渡手段。因此无论你从哪篇教程拷贝代码都应先确认自己用的是storybook/angular还是storybook/angular-vite再决定是否需要setCompodocJson。七、小结在 Storybook Angular 项目中启用 Compodoc 只需记住三步安装compodoc/compodoc在angular.json的storybook与build-storybooktarget 上开启compodoc: true并给出compodocArgs在.storybook/preview.ts中调用setCompodocJson注入生成的documentation.json。三步之后组件上的 JSDoc 注释就会自动演化为 Controls 面板和 Docs 文档而它的执行细节——默认参数补全、全局 JSON 存储、以及 Webpack/Vite 两套框架的差异——都可以在仓库的 run-compodoc.ts、angular-compodoc browser 适配器 与 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），仅供参考