用 MDX 与 Meta、Controls Doc Block 编写 Button 组件自定义文档Storybook 基线示例逐行解读【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook在 Storybook 中Meta与Controls是 Docs 体系里两个最基础的 Doc Block前者决定自定义 MDX 文档挂接到哪个组件、放在侧边栏何处后者则把组件的参数args渲染成一张可交互的属性表。本文以当前仓库docs/_snippets/storybook-auto-docs-baseline-example.md这份基线示例为骨架逐行拆解它为Button组件编写自定义文档的标准写法并延伸到 Meta Doc Block API 与 Controls Doc Block API让你能直接复用这套模板为自己的组件写出定义 / 用法 / 入参结构清晰、且可交互的 MDX 文档页。这份片段本身并非孤立文件它是 MDX 编写自定义文档 中 Using theMetaDoc Block 一节的完整示例由CodeSnippets pathstorybook-auto-docs-baseline-example.md /注入展示了撰写组件自定义 MDX 文档时的标配骨架。基线示例在官方文档中的位置storybook-auto-docs-baseline-example.md 提供两个几乎同构的Button.mdx版本区别只在于Meta块的使用方式custom-title标签页Meta titleButton /用title指定文档在侧边栏的标题位置of-prop标签页Meta of{ButtonStories} /用of把这份 MDX 文档挂接到具体的 CSF 故事文件。两者共用同一种正文组织方式# Definition组件是什么、## Usage怎么用、有哪些变体、## Inputs组件入参通过Controls /自动生成。这说明 Storybook 官方推荐的组件自定义文档本质上是结构化 Markdown 组件参数表格的组合。完整的两种写法如下与仓库片段逐字一致import { Meta, Controls } from storybook/addon-docs/blocks; Meta titleButton / # Definition Button is a clickable interactive element that triggers a response. You can place text and icons inside of a button. Buttons are often used for form submissions and to toggle elements into view. ## Usage The component comes in different variants such as primary, secondary, large and small which you can use to alter the look and feel of the button. ## Inputs Button has the following properties: Controls /import { Meta, Controls } from storybook/addon-docs/blocks; import * as ButtonStories from ./Button.stories; Meta of{ButtonStories} / # Definition Button is a clickable interactive element that triggers a response. You can place text and icons inside of a button. Buttons are often used for form submissions and to toggle elements into view. ## Usage The component comes in different variants such as primary, secondary, large and small which you can use to alter the look and feel of the button. ## Inputs Button has the following properties: Controls /逐行拆解一个 MDX 文档页由哪几部分组成对照仓库中更完整的解释见 MDX 编写自定义文档 的 Anatomy of MDX 一节这份示例可以被切分为四层1. 从storybook/addon-docs/blocks导入 Doc Blockimport { Meta, Controls } from storybook/addon-docs/blocks;MDX 允许在一个文件里同时写 Markdown、JSX 与 story 引用。storybook/addon-docs/blocks是 Doc Block文档专用组件库的统一导出入口Meta与Controls均来自这里。它们的真实实现位于仓库 code/addons/docs/src/blocks/blocks/Meta.tsx 与 code/addons/docs/src/blocks/blocks/Controls.tsx由 addon-docs 提供。2. 用Meta块锚定文档Meta titleButton /或import * as ButtonStories from ./Button.stories; Meta of{ButtonStories} /Meta块是两份版本差异的集中点也是理解 MDX 文档归属机制的关键详见下文专节。注意Meta不渲染任何可见内容它只负责把这篇文档挂到组件、故事与侧边栏结构中。3. 用 Markdown 标题组织叙述性内容# Definition ## Usage ## Inputs示例依次回答了三个问题组件是什么Definition、有哪些使用变体Usage、有哪些入参Inputs。MDX 默认支持 standard markdownCommonMark因此普通标题、段落、列表、表格都可直接使用正文每一段落由空行分隔切忌把不同语言块紧贴在一起否则可能触发难以定位的解析错误。4. 用Controls块插入可交互参数表Controls /Controls会把当前组件/故事的 args 渲染成一张动态表格既能当作组件的接口文档列出每个参数的名字、类型、默认值与描述也允许读者直接修改参数并即时作用于页面中已渲染的 story配合Story、Canvas块。两种Meta写法的语义差异Attached 与 UnattachedMeta块支持of、title、name、isTemplate四个属性详见 Meta Doc Block API其中决定文档归属的是前两者属性类型作用ofCSF 文件的全量导出把 MDX 文档挂接到某个故事文件attached文档会显示在该组件的故事列表旁并可使用Stories等需要在 attached 模式下的块titlestring为未挂接unattached的 MDX 文件设置标题从而把文档放到侧边栏任意路径节点下namestring修改 attached 文档条目的显示名默认取docs.defaultName即Docs可为同一组件挂多个 MDX 并分别命名isTemplateboolean声明该 MDX 文件作为自动文档autodocs模板使用不按普通条目被索引of-prop版本就是标准的attached写法。官方文档在 MDX 编写自定义文档 中特别强调了一个高频坑当为Meta提供of属性时务必引用故事文件的全量导出即import * as ButtonStories from ./Button.stories而不是组件本身或默认导出否则会引发生成文档的渲染问题。也就是说of{ButtonStories}指向的是一个模块命名空间对象而非ButtonStories.default指向的组件。attached 之后这份 MDX 在侧边栏中紧挨着 Button 的故事列表出现。custom-title版本则是unattached写法文件通过titleButton控制侧边栏位置但未与任何 CSF 文件绑定。若连title都不提供、也没有其他内容块Storybook 会把这种页面视为仅文档documentation-only页面并在侧边栏以不同形态渲染见 storybook-auto-docs-mdx-docs-docs-only-page.md。更进一步如果你完全省略Meta块Storybook 会依据文件在磁盘上的物理位置用与 CSF auto-title 相同的启发式规则推断标题并放到侧边栏对应位置用它覆盖同名组件自动生成的 autodocs 页面——这种按文件系统组织文档的方式常用于独立页面或测试指南。Controls块组件入参表格的自动来源示例第三部分的Controls /之所以没有显式传of是因为在 attached 场景下它会自动读取当前 MDX 文档所挂接 CSF 文件的上下文。Controls支持以下属性详见 Controls Doc Block API属性类型默认值作用ofStory 导出或 CSF 文件导出—指定从哪个 story 取控件传 CSF 文件导出时使用文件内第一个primarystoryincludestring[] \| RegExpparameters.docs.controls.include仅展示匹配的参数控件excludestring[] \| RegExpparameters.docs.controls.exclude排除匹配的参数控件sortnone \| alpha \| requiredFirstparameters.docs.controls.sort或none控件排序none按处理顺序、alpha按名称字母序、requiredFirst在字母序基础上把必填项置顶与多数 Doc Block 一样Controls既能用 MDX 属性配置也能用命名空间参数parameters.docs.controls配置可在项目 / 组件 / 故事三个层级覆盖。而真正决定表格中出现哪些行、显示成文本框还是下拉框的是每个参数在 CSF 里声明的argTypes含name、description、type、control、defaultValue等。如果你需要的是不带交互控件、只展示参数元数据的静态表格官方建议改用ArgTypes块见 ArgTypes Doc Block API。还有一个已知边界值得留意只有在未关闭 story 内联渲染Story/Canvas的inline配置保持开启的前提下Controls才能产生真正可用的交互控件文档页内控件与 story 的联动是否生效取决于该配置。让它真正可运行配套的 CSF 故事文件of-prop版本里被引用的./Button.stories需要按 Component Story Format 编写。作为配套示意并非仓库中的真实文件一个最小化的 CSF 3 故事文件大致如下import type { Meta, StoryObj } from storybook/react-vite; import { Button } from ./Button; const meta { title: Button, component: Button, // 通过 argTypes 描述参数Controls 表格即据此渲染 argTypes: { variant: { control: select, options: [primary, secondary], }, size: { control: radio, options: [small, large], }, }, } satisfies Metatypeof Button; export default meta; type Story StoryObjtypeof meta; export const Primary: Story { args: { variant: primary, size: large, label: Submit }, };这样 MDX 中Meta of{ButtonStories} /就能把文档挂接到上面定义好的 Button 故事节点Controls /则基于meta.argTypes与各 story 的args渲染出入参表格。MDX 内文档正文与实际 CSF 文件保持一描述、一声明的职责分离CSF 负责精确定义组件各状态与类型安全TS 下还有自动补全MDX 负责撰写可读的结构化文档并自由编排 JSX。与 Autodocs 的关系自定义 MDX 如何覆盖自动文档如果你在main.js|ts中通过tags: [autodocs]开启了自动文档autodocsStorybook 会自动为每个组件生成一份文档页而本文这套 MDX 写法属于另一条路径——为组件编写自定义MDX 文档。两条路径共享同一批 Doc Block 与侧边栏体系autodocs 生成页、自定义 MDX 页以及仅文档页面统一显示为Docs条目。当你用文件系统方式省略Meta提供的自定义 MDX 与某组件同名同位置时它会覆盖该组件的 autodocs 页面官方建议此时把tags: [autodocs]从组件故事上移除避免冲突报错见 Autodocs 编写自动文档。在项目中使用基线模板的操作步骤把这份基线示例落地到自己的 Storybook 项目只需四步确认已安装并注册storybook/addon-docsReact 框架下通常随 docs 能力默认启用。在组件旁新建Button.mdx照抄上文任一版本作为起点需要与已有故事联动、想复用Stories等块时选of版本只想把文档放到指定侧边栏位置时选title版本。用 Markdown 保持# Definition/## Usage/## Inputs这样的信息架构在末尾用Controls /或显式Controls of{ButtonStories.Primary} /嵌入参数表。确保.storybook/main.js|ts的stories配置能同时匹配*.mdx与*.stories.(js|jsx|mjs|ts|tsx)文件典型写法如../src/**/*.mdx、../src/**/*.stories.(js|jsx|mjs|ts|tsx)。更复杂的场景一页文档覆盖多个组件、引入外部 Markdown 的Markdown块、文档块进阶组合等可继续参考 MDX 编写自定义文档 与 Doc Blocks 文档写作。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考