Storybook Web Components 文档指南：基于 custom-elements.json 自动生成 Props 表格与组件文档

Storybook Web Components 文档指南基于 custom-elements.json 自动生成 Props 表格与组件文档【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook在 Storybook 中为 Web ComponentsLit、Stencil、Polymer 等框架或纯 Vanilla 自定义元素编写文档时与普通 React/Vue 组件最大的差异在于没有 PropTypes、TypeScript 装饰器这类“就地可查”的类型信息组件元数据必须依赖custom-elements.json这份外部清单文件。本文基于 Storybook 官方文档 WEB_COMPONENTS.md 完整展开讲解如何为 Web Components 接入 Storybook Docs安装与配置setCustomElementsManifest、通过清单文件自动生成 Props 表格、以及用docs.story.iframeHeight/docs.stories.inline参数控制故事的 iframe 渲染方式并结合开源仓库源码说明元数据是如何被解析、映射为 Docs 页面上 argTypes 表格的。读完本文你将能够按文档要求完成storybook/addon-docs Web Components 渲染器的接入选择或生成符合 v1.0.0 规范的custom-elements.json文件并理解其结构让 DocsPage 自动渲染出 Properties / Attributes / Events / Slots / CSS Shadow Parts 等分类表格从源码层面理解setCustomElementsManifest→getCustomElements→extractArgTypes这条数据链路的实际实现。前置条件先完成 Docs 通用安装官方文档明确要求在配置 Web Components 专属能力之前必须先在 README.md 中描述的通用流程下安装 Docs 插件。核心步骤为yarn add -D storybook/addon-docs然后在.storybook/main.js中注册插件并让 stories 可被索引export default { stories: [ ../src/**/*.mdx, ../src/**/*.stories.(js|jsx|ts|tsx), ], addons: [ storybook/addon-docs, ], };同时确认项目中已经存在一份可用的 custom-elements.json 文件后文详述如何生成与校验否则 Props 表格将无数据可渲染。安装向 preview 注入 custom-elements 清单Web Components 接入 Docs 的第一步是把custom-elements.json的内容注入到预览运行时。按 WEB_COMPONENTS.md 的 Install 一节在.storybook/preview.js中添加import { setCustomElementsManifest } from storybook/web-components; import customElements from ../custom-elements.json; setCustomElementsManifest(customElements);然后在故事文件中用标签名字符串作为component字段export default { title: Demo Card, component: your-component-name, // 该名字必须能在 custom-elements.json 中找到 };源码视角清单存到哪里、何时被读取setCustomElementsManifest的实现位于 framework-api.ts它把清单对象挂到全局变量上export function setCustomElementsManifest(customElements: any) { global.__STORYBOOK_CUSTOM_ELEMENTS_MANIFEST__ customElements; }同文件中的getCustomElementsframework-api.ts在 Docs 提取 argTypes 时读取该全局变量并带有历史兼容逻辑——旧版setCustomElements对应__STORYBOOK_CUSTOM_ELEMENTS__全局变量注入的数据同样可用export function getCustomElements() { return global.__STORYBOOK_CUSTOM_ELEMENTS__ || global.__STORYBOOK_CUSTOM_ELEMENTS_MANIFEST__; }这意味着如果你维护的是较老版本 Storybook 时代通过setCustomElements注入的清单实验性tags结构迁移到新 API 前功能仍然保持兼容。同时isValidMetaDataframework-api.ts会对清单做结构校验数据中必须包含tags数组实验性格式或modules数组v1.0.0 格式否则抛出明确指向 addon-docs 文档的错误提示帮助定位配置缺失。Props 表格custom-elements.json 的结构与生成要让 Props tables 在 Web Components 上生效必须提供custom-elements.json。官方文档给出两条路径手写或使用分析器自动生成——后者通常更可靠且“不同 Web Components 技术栈sugar下效果不一your mileage may vary”。文档中列出的已知分析器输出custom-elements.jsonv1.0.0 的分析器custom-elements-manifest/analyzerOpenWC 出品支持 Vanilla、LitElement、FAST Element、Stencil、Catalyst、Atomico输出旧版格式的分析器web-component-analyzer支持 LitElement、Polymer、Vanilla、Stencilstenciljs自带生成支持 Stencil但元数据不全用 Stencil 生成清单文件如果使用 Stencil只需在stencil.config.ts的outputTargets中追加docs-vscode输出{ type: docs-vscode, file: custom-elements.json },清单文件长什么样一份 v1.0.0 格式的最小结构如下摘自 WEB_COMPONENTS.md 原文示例完整示例可参考仓库中的 web-components-kitchen-sink 项目{ schemaVersion: 1.0.0, readme: , modules: [ { kind: javascript-module, path: src/my-element.js, declarations: [ { kind: class, description: , name: MyElement, members: [ { kind: field, name: disabled }, { kind: method, name: fire } ], events: [ { name: disabled-changed, type: { text: Event } } ], superclass: { name: HTMLElement }, tagName: my-element } ], exports: [ { kind: custom-element-definition, name: my-element, declaration: { name: MyElement, module: src/my-element.js } } ] } ] }关键字段说明字段作用schemaVersion清单版本Docs 解析器按 v1.0.0 处理modules[].path组件源文件路径用于代码链接等元信息modules[].declarations[].tagName自定义元素标签名Docs 通过它与故事中的component字段精确匹配大小写不敏感members/properties属性Properties来源映射到 Props 表格events事件Events来源映射为onXxxaction 参数superclass继承关系文档中展示exports导出声明标识元素定义与类的对应关系源码视角Docs 如何把清单变成表格数据清单到表格的转换核心在 custom-elements.ts。getMetaDatacustom-elements.ts根据清单版本分派到两条解析路径const getMetaData (tagName: string, manifest: any) { if (manifest?.version experimental) { return getMetaDataExperimental(tagName, manifest); } return getMetaDataV1(tagName, manifest); };getMetaDataExperimentalcustom-elements.ts面向旧版tags数组结构按tag.name大小写不敏感匹配getMetaDataV1custom-elements.ts遍历modules[].declarations[]以declaration.tagName tagName精确匹配 v1.0.0 格式。两条路径在找不到组件时都会输出警告日志Component not found in custom-elements.json: tagName这是排查“表格为空”时最重要的控制台线索。匹配成功后extractArgTypesFromElementscustom-elements.ts把各字段映射为 Storybook 的ArgTypesmetaData { ...mapData(metaData.members ?? [], properties), ...mapData(metaData.properties ?? [], properties), ...mapData(metaData.attributes ?? [], attributes), ...mapData(metaData.events ?? [], events), ...mapData(metaData.slots ?? [], slots), ...mapData(metaData.cssProperties ?? [], css custom properties), ...mapData(metaData.cssParts ?? [], css shadow parts), }可以推断这些table.category分类就是 DocsPage 上 Properties / Attributes / Events / Slots / CSS Custom Properties / CSS Shadow Parts 各表格的分组依据。映射细节还包括mapItemcustom-elements.ts为属性/事件/插槽生成name、description、type、table.defaultValue等字段slots 类型固定为stringmapEventcustom-elements.ts把disabled-changed这类 kebab-case 事件名转换为onDisabledChanged并附加action: { name: ... }使 Controls 面板能直接触发该事件、Actions 面板能记录调用——这是 Web Components 文档与框架文档在“事件可控性”上对齐的关键机制mapDatacustom-elements.ts中显式过滤kind method的成员即custom-elements.json中的methods不会出现在 Props 表格里方法与事件、属性在表格体系里是区分的。相关测试 custom-elements.test.ts 验证了将清单写入window.__STORYBOOK_CUSTOM_ELEMENTS_MANIFEST__后提取逻辑生效覆盖了这条全局变量数据链路。渲染方式故事默认内联可切换为 iframeWeb Components 在 DocsPage 中的故事默认以inline方式渲染——直接把自定义元素插入文档流。当组件内部使用了 Shadow DOM 隔离的复杂样式、或者内联渲染出现布局问题时可以改用 iframe 渲染。按 WEB_COMPONENTS.md 的 “Stories not inline” 一节做法是在.storybook/preview.js中设置export const parameters { docs: { story: { inline: false } } };iframe 模式下默认 iframe 高度为60px可用故事参数docs.story.iframeHeight调整高度避免内容被裁切。这一配置对全局生效如需只对部分故事生效可以在单个故事的parameters中覆盖同样的docs.story结构。进一步阅读官方文档末尾的 “More resources” 指向了 Docs 插件的核心参考资料均位于本仓库中DocsPage 参考理解零配置文档页的组成MDX 参考长文文档中嵌入故事FAQ / Recipes / ThemingProps 表格参考argTypes、表格分类与自定义的完整能力Docs 插件总览README.md其中包含安装细节与 preset options如csfPluginOptions、mdxPluginOptions说明小结为 Web Components 编写 Storybook 文档的关键在于三点一是按 README.md 完成storybook/addon-docs的通用安装二是准备并注入符合 v1.0.0 规范的custom-elements.json推荐custom-elements-manifest/analyzer或 Stencil 的docs-vscode输出目标生成再通过setCustomElementsManifest交给运行时三是善用docs.story.iframeHeight与docs.stories.inline参数处理 Shadow DOM 组件的内联渲染问题。从源码看framework-api.ts 负责清单的全局注入与校验custom-elements.ts 负责把modules[].declarations解析为带分类的 ArgTypes最终由 DocsPage 呈现为可交互的 Props 表格。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考