Storybook 多框架 Props 声明实战一个 interface 如何驱动整个 Controls 面板【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook 的教程从 Button 组件写起却少有人提组件里的 Props 声明——类型、默认值、JSDoc 注释——才是 Controls 和 Docs 面板的数据源头。本文拿多框架的同一 Button 拆这条 docgen 链路读完你可以直接复用组件骨架。一个组件五种方言——先看结论同一个「禁用 文案」的 Button在不同框架里各有一套最小声明单元。仓库里 button-component-with-proptypes.md 这个官方教学片段就是五个方言的合集浓缩如下框架一句话最小声明片段React (TS)interface 字段即属性注释写在字段上方isDisabled: boolean;AngularInput()装饰的类字段就是对外属性Input() isDisabled: boolean;Vue 3props选项里每项是一个类型描述对象isDisabled: { type: Boolean }Sveltescript里export let导出的变量export let disabled false;Web Components (Lit)property()装饰器或static propertiesproperty() content?: string One;拆开看五套写法高度同构属性上方的 JSDoc 注释统一成为描述文本字段的类型统一决定控件形态布尔是开关、字符串是文本框默认值统一进入表格的 Default 列。换句话说你在组件文件里敲下的每一行声明都有一份文档镜像等着它。argTypes 从哪来——把写组件和生成文档接上组件源码不会自己变成文档中间隔着一套各框架的 docgen 解析器组件源码 → 框架解析器 → 结构化的 argTypes 对象。ReactVite 侧JS 代码交给react-docgen提取 PropTypes 与 JSDocTS 代码交给react-docgen-typescript做静态分析依赖可直接在 react-vite 的 package.json 里找到Vue 3vue-docgen-api负责把props选项、script langts里的defineComponent转成__docgenInfo入口是 vue3 渲染器的 package.json 里的vue-docgen-api依赖与内部docgen-worker导出Angularstorybook/angular-compodoc执行 Compodoc把Input()字段连同 JSDoc 编译进元数据Sveltesveltedoc-parser解析export let与required标记Lit / Web Components没有额外依赖直接读取类上方的propJSDoc 块与property()装饰器。无论哪条链路产物都是同一种 JS 对象也就是 Storybook 内部消费的目标结构const argTypes { label: { name: label, type: { name: string, required: false }, defaultValue: Hello, description: demo description, table: { type: { summary: string }, defaultValue: { summary: Hello } }, control: { type: text }, }, };type决定control渲染成什么description进 Docs 面板的 ArgsTabletable.defaultValue进表格的默认值列。下面这张图就是 argTypes 落到 UI 后的样子Name、Description、Default 三列分别对应name、description、defaultValue字段。选一个框架讲透——以 React TypeScript 为例拿仓库教学片段里的 React TS 版 Button 当样本完整代码不长export interface ButtonProps { /** * Checks if the button should be disabled */ isDisabled: boolean; /** * The display content of the button */ content: string; } export const Button: React.FCButtonProps ({ isDisabled false, content }) { return ( button typebutton disabled{isDisabled} {content} /button ); };逐行看三处关键写法isDisabled: boolean;没有?意味着「必填」。react-docgen-typescript据此生成type: { name: boolean, required: true }Controls 面板里该属性名后会带一个红色星号。你在 interface 里加一个?Storybook 就会把对应属性从必填切换为可选——声明粒度完全由你掌控。解构参数上的 false与 是运行期兜底同时也是文档信息源docgen 会把它们读进defaultValue与table.defaultValue。换句话说默认值在 TS 版本里是一份代码两处生效。React.FCButtonProps这一行本身不产生文档但它把泛型钉死在ButtonProps上IDE 里解构参数能补全类型写错属性名当场报错——类型声明的防错价值早于 Storybook 存在。同一组件的 JS PropTypes 版本对比一下差异集中在这几点对比维度JS PropTypesTS interface类型来源PropTypes.bool等运行期断言编译器静态检查docgen 走 TS 静态分析必填表达isRequired后缀字段不带?默认值表达无只能靠调用方传值解构默认值且会进入defaultValue缺参后果开发环境控制台告警编译期报错运行期兜底TS 版把防错提前到了构建阶段还顺手多产出一份默认值元数据这是选 TS 的核心理由。其余四个框架不展开等价写法各记一行关键词即可Angular →Input()字段 CompodocJSDoc 写在字段上方required标记表达必填Vue 3 →props选项的type/default/required三要素 vue-docgen-apiSvelte →export let变量 sveltedoc-parserrequired标记同样生效Lit → 类级propJSDoc 块 property()装饰器或static get properties()tag指定注册名。踩坑与边界情况⚠️ 三个坑都来自真实项目里最常见的顺手写法每个都是三句话能讲清的事。必填 默认值并存会怎样现象Vue 的某个 prop 同时写了default: false和required: trueDocs 表格里必填星号和默认值同时出现读者不知道该信哪个。原因required只在属性缺失时告警而只要有default属性永远不缺失required 形同虚设。修法二选一——保留default删掉required或用 JSDoc 的required标记表达语义必填。注释缩进不一致导致 docgen 丢失描述现象注释明明写了Docs 的 Description 列却是空的。原因docgen 按注释块紧贴属性、缩进对齐来配对仓库教学片段里 React 版content属性的 JSDoc 结尾*/就没与开头/**对齐部分解析器遇到这种错位会放弃匹配。修法JSDoc 块整体对齐、紧贴属性上方中间不留空行。Svelte 脚本标签未闭合的编译报错现象教学片段里Button.svelte写了自闭合的script/拷进自己项目直接编译失败。原因Svelte 要求脚本标签显式闭合自闭合写法非法。修法改成/script再构建一行就能过。从组件到第一个 Story——收口组件声明完成后的下一步是在 stories 文件里用 CSF3 的 meta 把组件与 Story 关联起来最小写法如下import type { Meta } from storybook/react-vite; import { Button } from ./Button; const meta { component: Button, } satisfies Metatypeof Button; export default meta;component: Button这一行是触发器docgen 链路前面讲过的解析器 argTypes 推导正是从它开始工作把 interface 的每个字段翻译成 Controls 面板和 ArgsTable。若组件后续加了onClick之类的事件属性再补一行parameters: { actions: { argTypesRegex: ^on.* } }即可接入 Actions 面板。组件骨架写完后button-story.md 展示了如何导出Primary、Secondary等多个 storybutton-story-matching-argtypes.md 则给出 args 与 argTypes 逐字段对齐的跨框架完整 meta。下一次写 Button 时别把 JSDoc 当装饰interface 敲到哪注释就跟到哪Docs 面板的草稿就同时完成了。这个习惯对所有框架通用组件文件的声明质量直接决定了 Storybook 文档的下限。【免费下载链接】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 多框架 Props 声明实战：一个 interface 如何驱动整个 Controls 面板
Storybook 多框架 Props 声明实战一个 interface 如何驱动整个 Controls 面板【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook 的教程从 Button 组件写起却少有人提组件里的 Props 声明——类型、默认值、JSDoc 注释——才是 Controls 和 Docs 面板的数据源头。本文拿多框架的同一 Button 拆这条 docgen 链路读完你可以直接复用组件骨架。一个组件五种方言——先看结论同一个「禁用 文案」的 Button在不同框架里各有一套最小声明单元。仓库里 button-component-with-proptypes.md 这个官方教学片段就是五个方言的合集浓缩如下框架一句话最小声明片段React (TS)interface 字段即属性注释写在字段上方isDisabled: boolean;AngularInput()装饰的类字段就是对外属性Input() isDisabled: boolean;Vue 3props选项里每项是一个类型描述对象isDisabled: { type: Boolean }Sveltescript里export let导出的变量export let disabled false;Web Components (Lit)property()装饰器或static propertiesproperty() content?: string One;拆开看五套写法高度同构属性上方的 JSDoc 注释统一成为描述文本字段的类型统一决定控件形态布尔是开关、字符串是文本框默认值统一进入表格的 Default 列。换句话说你在组件文件里敲下的每一行声明都有一份文档镜像等着它。argTypes 从哪来——把写组件和生成文档接上组件源码不会自己变成文档中间隔着一套各框架的 docgen 解析器组件源码 → 框架解析器 → 结构化的 argTypes 对象。ReactVite 侧JS 代码交给react-docgen提取 PropTypes 与 JSDocTS 代码交给react-docgen-typescript做静态分析依赖可直接在 react-vite 的 package.json 里找到Vue 3vue-docgen-api负责把props选项、script langts里的defineComponent转成__docgenInfo入口是 vue3 渲染器的 package.json 里的vue-docgen-api依赖与内部docgen-worker导出Angularstorybook/angular-compodoc执行 Compodoc把Input()字段连同 JSDoc 编译进元数据Sveltesveltedoc-parser解析export let与required标记Lit / Web Components没有额外依赖直接读取类上方的propJSDoc 块与property()装饰器。无论哪条链路产物都是同一种 JS 对象也就是 Storybook 内部消费的目标结构const argTypes { label: { name: label, type: { name: string, required: false }, defaultValue: Hello, description: demo description, table: { type: { summary: string }, defaultValue: { summary: Hello } }, control: { type: text }, }, };type决定control渲染成什么description进 Docs 面板的 ArgsTabletable.defaultValue进表格的默认值列。下面这张图就是 argTypes 落到 UI 后的样子Name、Description、Default 三列分别对应name、description、defaultValue字段。选一个框架讲透——以 React TypeScript 为例拿仓库教学片段里的 React TS 版 Button 当样本完整代码不长export interface ButtonProps { /** * Checks if the button should be disabled */ isDisabled: boolean; /** * The display content of the button */ content: string; } export const Button: React.FCButtonProps ({ isDisabled false, content }) { return ( button typebutton disabled{isDisabled} {content} /button ); };逐行看三处关键写法isDisabled: boolean;没有?意味着「必填」。react-docgen-typescript据此生成type: { name: boolean, required: true }Controls 面板里该属性名后会带一个红色星号。你在 interface 里加一个?Storybook 就会把对应属性从必填切换为可选——声明粒度完全由你掌控。解构参数上的 false与 是运行期兜底同时也是文档信息源docgen 会把它们读进defaultValue与table.defaultValue。换句话说默认值在 TS 版本里是一份代码两处生效。React.FCButtonProps这一行本身不产生文档但它把泛型钉死在ButtonProps上IDE 里解构参数能补全类型写错属性名当场报错——类型声明的防错价值早于 Storybook 存在。同一组件的 JS PropTypes 版本对比一下差异集中在这几点对比维度JS PropTypesTS interface类型来源PropTypes.bool等运行期断言编译器静态检查docgen 走 TS 静态分析必填表达isRequired后缀字段不带?默认值表达无只能靠调用方传值解构默认值且会进入defaultValue缺参后果开发环境控制台告警编译期报错运行期兜底TS 版把防错提前到了构建阶段还顺手多产出一份默认值元数据这是选 TS 的核心理由。其余四个框架不展开等价写法各记一行关键词即可Angular →Input()字段 CompodocJSDoc 写在字段上方required标记表达必填Vue 3 →props选项的type/default/required三要素 vue-docgen-apiSvelte →export let变量 sveltedoc-parserrequired标记同样生效Lit → 类级propJSDoc 块 property()装饰器或static get properties()tag指定注册名。踩坑与边界情况⚠️ 三个坑都来自真实项目里最常见的顺手写法每个都是三句话能讲清的事。必填 默认值并存会怎样现象Vue 的某个 prop 同时写了default: false和required: trueDocs 表格里必填星号和默认值同时出现读者不知道该信哪个。原因required只在属性缺失时告警而只要有default属性永远不缺失required 形同虚设。修法二选一——保留default删掉required或用 JSDoc 的required标记表达语义必填。注释缩进不一致导致 docgen 丢失描述现象注释明明写了Docs 的 Description 列却是空的。原因docgen 按注释块紧贴属性、缩进对齐来配对仓库教学片段里 React 版content属性的 JSDoc 结尾*/就没与开头/**对齐部分解析器遇到这种错位会放弃匹配。修法JSDoc 块整体对齐、紧贴属性上方中间不留空行。Svelte 脚本标签未闭合的编译报错现象教学片段里Button.svelte写了自闭合的script/拷进自己项目直接编译失败。原因Svelte 要求脚本标签显式闭合自闭合写法非法。修法改成/script再构建一行就能过。从组件到第一个 Story——收口组件声明完成后的下一步是在 stories 文件里用 CSF3 的 meta 把组件与 Story 关联起来最小写法如下import type { Meta } from storybook/react-vite; import { Button } from ./Button; const meta { component: Button, } satisfies Metatypeof Button; export default meta;component: Button这一行是触发器docgen 链路前面讲过的解析器 argTypes 推导正是从它开始工作把 interface 的每个字段翻译成 Controls 面板和 ArgsTable。若组件后续加了onClick之类的事件属性再补一行parameters: { actions: { argTypesRegex: ^on.* } }即可接入 Actions 面板。组件骨架写完后button-story.md 展示了如何导出Primary、Secondary等多个 storybutton-story-matching-argtypes.md 则给出 args 与 argTypes 逐字段对齐的跨框架完整 meta。下一次写 Button 时别把 JSDoc 当装饰interface 敲到哪注释就跟到哪Docs 面板的草稿就同时完成了。这个习惯对所有框架通用组件文件的声明质量直接决定了 Storybook 文档的下限。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考