Storybook Docs for Ember：为 Ember 组件自动生成分类文档、Props 表格与 MDX 长文文档
Storybook Docs for Ember为 Ember 组件自动生成分类文档、Props 表格与 MDX 长文文档【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇技术指南基于 Storybook 官方文档 Storybook Docs for Ember系统讲解如何在 Ember 项目中接入storybook/addon-docs并覆盖文档中全部四个实战环节安装与main.js注册、DocsPage 自动生成文档、基于ember-cli-storybook的 Props 表格docgen JSON 注入链路以及 MDX 长文文档与 IFrame 高度配置。结合仓库源码可以看到Ember 的 docgen JSON 通过setJSONDoc挂载到全局变量再由 Ember 渲染层的 preview 配置消费读完本篇你将掌握一套在 Ember 项目中完整落地 Storybook Docs 的可复制方案。一、Storybook Docs 在 Ember 中的能力范围Storybook Docs 是 Storybook 的文档 Addon它能把 Storybook 中的 stories 转换成结构化的组件文档。针对 Ember官方文档明确支持两类能力DocsPage自动生成的文档页每个 story 在 Storybook UI 的Docs标签页中获得自动生成的文档MDX长文文档用 Markdown 描述组件并内嵌 stories、Props 表格等文档组件。其中 DocsPage 属于装上即得的基础能力而 Props 表格需要额外打通 docgen 数据链路后文详述。通用概念可参考 Docs 总览文档、DocsPage 参考 与 MDX 参考。说明原文档顶部注明该页描述的是 Storybook 5.3.0 引入的新版配置方式如需从旧格式迁移可参考仓库根目录的 MIGRATION.md。二、安装注册storybook/addon-docs2.1 添加依赖首先安装 Addon 包并确保项目中所有storybook/*包的版本保持一致yarn add -D storybook/addon-docs从当前仓库的 code/addons/docs/package.json 可以看到storybook/addon-docs的storybook元信息中声明了displayName: Docs且unsupportedFrameworks仅排除了react-native——Ember 属于其支持的框架范围。2.2 在.storybook/main.js中注册将 Addon 加入addons数组export default { addons: [storybook/addon-docs], };三、DocsPage自动生成的组件文档页完成上面的安装后所有 story 都会自动获得基础版 DocsPage 文档无需额外代码即可在 Storybook UI 的Docs标签页中查看。DocsPage 会自动聚合该 story 的描述、Controls、故事画布等区块是 Ember 项目落地组件文档的最低成本路径。四、Props 表格打通 docgen JSON 数据链路要为组件生成 Props 表格ArgsTable比基础 DocsPage 多几步配置。核心思路是用 ember-cli 构建过程生成一份 docgen JSON再把它注入 preview 运行时。4.1 启用ember-cli-storybook的文档集成Docs for Ember 依赖storybook/ember-cli-storybook这个 ember Addon 从组件源文件中提取文档注释。如果项目已用 Storybook 跑 Ember该 Addon 通常已安装只需在ember-cli-build.js中打开开关let app new EmberApp(defaults, { ember-cli-storybook: { enableAddonDocsIntegration: true, }, });4.2 构建产物/storybook-docgen/index.json开启后运行 ember-cli 服务会在/storybook-docgen/index.json生成分类 JSON 文档文件。由于生成逻辑挂在 ember-cli 构建流程上每次保存组件文件都会重新生成该文件因此文档与源码注释始终保持同步。组件文档注释的写法如class、参数说明等 yuidoc 风格标签可参照ember-cli-addon-docs-yuidoc提供的文档示例。4.3 用setJSONDoc把 JSON 注入 preview在.storybook/preview.js中加载生成的 JSON 文件import { setJSONDoc } from storybook/addon-docs/ember; import docJson from ../dist/storybook-docgen/index.json; setJSONDoc(docJson);从源码看这条链路非常简洁且能解释为什么叫 setcode/addons/docs/src/ember/index.ts 中setJSONDoc的实现只有一行——把传入的 JSON 挂到全局变量globalThis.__EMBER_GENERATED_DOC_JSON__ jsondoc;Ember 渲染层在 code/frameworks/ember/src/client/preview/jsondoc.ts 中通过return global.__EMBER_GENERATED_DOC_JSON__;读回该值用于在运行时按组件名查表渲染 Props 表格对应的类型声明见 code/frameworks/ember/src/types.tsvar __EMBER_GENERATED_DOC_JSON__: any;。也就是说setJSONDoc是 preview 构建期写入、渲染期读取的一个全局桥梁这也是为什么 preview.js 必须在预览构建中被执行、且 import 的是构建后产物路径../dist/storybook-docgen/index.json。4.4 在 story 元数据中填写component字段最后一步在 story 元数据中填写component字段其值必须是字符串且要与源码注释中使用的class名称一致export default { title: App Component, component: AppComponent, };这个字符串就是 docgen JSON 中的组件索引键Docs 按component名称从__EMBER_GENERATED_DOC_JSON__中查找对应条目并渲染表格名称不匹配时表格会为空。五、MDX以 Markdown 写长文文档并内嵌文档组件MDX 是用 Markdown 描述组件文档、并内嵌 story 与 Props 表格等文档组件的方式。在 Ember 中使用需注意以下三点。5.1 补充react依赖Docs Addon 存在对react的 peer 依赖MDX 文档组件在渲染层使用 React 运行时。若要写 MDX 文档可能需要额外添加yarn add -D react这一点与仓库事实相符code/addons/docs/package.json 中storybook/addon-docs声明了react/react-dom的依赖区间^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0peerDependencies 中也包含types/react可选。5.2 让main.js的 stories 匹配到 MDX 文件更新.storybook/main.js确保 stories 的 glob 能收集到 MDX 文件export default { stories: [../src/stories/**/*.stories.(js|mdx)], };5.3 一个完整的 Ember MDX 文档示例import { Meta, Story, ArgsTable } from storybook/addon-docs; import { hbs } from ember-cli-htmlbars; Meta titleApp Component componentAppComponent / # App Component Some **markdown** description, or whatever you want. Story namebasic height400px{{ template: hbsAppComponent title{{title}} /, context: { title: Title }, }}/Story ## ArgsTable ArgsTable ofAppComponent /两个来自原文档的实战注意事项component需要声明两次Meta上一次、组件名又一次。原文档指出这是已知冗余等待后续版本简化对应 Storybook 侧的 issue #8673在落地时按现状写即可不要试图省略其中一处。Props文档块依赖 docgen 配置要使用ArgsTable/Props区块必须先完成第四节的全部 docgen 链路enableAddonDocsIntegrationsetJSONDoccomponent字段否则表格无法渲染。六、IFrame 高度全局、单 story 与 MDX 三级配置Storybook Docs 在 Ember 中把 story 渲染在iframe内默认高度为60px。可在三个层面调整6.1 全局默认.storybook/preview.jsexport const parameters { docs: { story: { iframeHeight: 400px } } };6.2 DocsPage单 story 局部覆盖在 story 上直接设置parametersexport const basic () ... basic.parameters { docs: { story: { iframeHeight: 400px } } }6.3 MDX作为Story元素属性Story namebasic height400px{...}/Story6.4 源码中的取值优先级从 code/addons/docs/src/blocks/blocks/Story.tsx 的实现可以看到故事区块的高度解析存在一条明确的回退链props.height ?? storyParameters.height ?? storyParameters.iframeHeight ?? 100px即MDX 的height属性 story 参数中的height story 参数中的iframeHeight 兜底值这与上面临MDX 属性、单 story 参数、preview 全局参数三级配置的描述一一对应外层更具体的声明会覆盖全局默认。此外仓库中 Ember 渲染层的 preview 配置 code/frameworks/ember/src/client/preview/config.ts 也内置了story: { iframeHeight: 80px }的默认值作为渲染端兜底。6.5 仓库内的真实用法仓库自带的 Ember 测试 Storybook 中就有实际用例test-storybooks/ember-cli/stories/welcome-banner.stories.js 中通过docs: { story: { iframeHeight: 200px } }调整了 story 的 iframe 高度可作为参照实现。七、相关文档与延伸阅读原文档More resources部分列出的仓库内参考文档转换为本仓库的全局路径如下DocsPage 参考MDX 参考Docs FAQRecipes文档配方Theming主题定制Props 表格参考结合本仓库源码还可以进一步深入storybook/addon-docs的文档区块组件位于 code/addons/docs/src/blocks/ArgsTable、Story、Source、Controls等Ember 渲染端实现位于 code/frameworks/ember/含src/client/preview/jsondoc.ts的 docgen JSON 消费逻辑可用于验证上文中每一处配置行为。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
