前端艺术实践：用Storybook构建交互式组件文档

对于前端来说，组件话已经从热门话题变成了基础能力，自定义组件或自建组件库已是再常见不过的事了。在实际工作中组件库的文档直接决定开发体验和效率，文档建设的重要性不言而喻。今天要推荐的工具叫Storybook，为此我特地通过用99元买的服务器搭了一套CI/CD系统部署了一套Demo，欢迎点击体验：Demo (首次加载速度尤为感人，请耐心等待。仅用于效果演示，希望大家别被这潦草的Demo迷惑)。组件库的文档不只是“写说明”，更要做到可视化、可交互、可复用——既能看、又能点、还能直接抄代码。能够满足这些需求的文档工具中，重点推荐以下两款：Dumi 和 Storybook。


Dumi

Dumi是一款为组件开发场景而生的静态站点框架，它有个代表作：Ant Design。不知是否有人跟我一样，第一眼看上的不是Ant Design的组件，而是它的组件库文档。真心嫉妒他们的这份文档，有案例、有代码、能交互，还有详细的参数说明。如果对它感兴趣可以点击Dumi传送门。


Storybook

Storybook 是一个开源项目，在 GitHub 上已有 83K+ star。它不仅用于构建组件库文档，还能用于组件测试。推荐 Storybook 的主要原因如下：

• 可直接嵌入项目，在编写组件文档的同时进行组件编码和测试；
  
• 基于 TypeScript 组件类型定义自动生成组件参数文档；
  
• 允许在文档中动态修改组件参数值，实时预览不同效果。
  
• 基础文档建设难度低（大多数 Demo  文档的编写时间不超过1分钟，主要得益于我的项目 Nebula Note，可实现快速内容替换）。
  
• 文档中可以使用第三方库来丰富文档效果，如：Swiper、Mermaid、MathJax 等等。
  
• 支持多种框架（React、Vue、Angular 等等），并且支持多种语言（TypeScript、JavaScript、HTML、CSS 等等）。
  

安装

1、在项目根目录下运行以下命令，Storybook 会自动检测你的框架（React、Vue、Angular 等）并进行相应的安装：

1. npx storybook@latest init

复制代码

安装过程可能需要几分钟，完成后它会添加必要的Storybook依赖并生成 .storybook 配置目录然后在 src/stories/ 目录中创建示例组件。

运行

1. npm run storybook

复制代码

默认情况下，Storybook 会在 http://localhost:6006/ 运行。虽然我们一行代码都没写，但已经可以看到Storybook提供的示例组件文档。

配置

在编写文档前，首先应该决定文档的存放方式：

• 集中存放： 将所有文档统一放在指定目录，例如 src/stories/，类似于示例文档的管理方式。
  

• 优点：结构清晰，文档与业务代码解耦，方便统一管理。
  
• 适用场景：适合大规模组件库开发，尤其是需要独立维护文档的项目。
  

• 跟随组件： 每个组件的 Story 文档与组件代码存放在一起，例如 src/components/Button/Button.stories.tsx。
  

• 优点：文档紧贴组件，便于开发和维护，不需要在多个目录之间跳转。
  
• 适用场景：适合产品型项目，组件文档随组件代码更新，保持同步。
  

如果选择跟随组件，则需要调整.storybook/main.js（或 main.ts），并指定文档路径，示例代码如下：

1. const config: StorybookConfig = {
2.     stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],

复制代码

Hello World

先分享一个React版的示例。新建一个文档button.stories.ts, 内容如下：

1. import { Meta, StoryObj } from '@storybook/react';
2. import Button, { ButtonProps } from './index';
3. import { action } from '@storybook/addon-actions';
5. export default {
6.     title: 'Atoms/Button',   // 组件在 Storybook 中的分组与显示路径。`'Atoms/Button'` 表示组件会在 `Atoms` 分组下展示为 `Button`。
7.     component: Button,       // 关联的 React 组件
8.     tags: ['autodocs'],      // `'autodocs'` 表示启用自动文档生成功能
9.     argTypes: {},            // 定义组件 props 的控制类型、分类、描述等
10.     args: {},                // 为组件设置默认的 props 值，在所有 stories 中共享，可在 UI 面板中修改
11. } as Meta<ButtonProps>;
13. export type Story = StoryObj<ButtonProps>;
14. export const Primary: Story = {
15.   // 指定组件运行的props值，可在 UI 面板中修改
16.     args: {
17.         children: 'Button',   
18.         type: 'primary',
19.         onClick: action('Button clicked'),
20.     },
21. };

复制代码

以上是一个完整的button文档代码。在 Storybook 的 stories 中，可以使用 actions 来监听按钮点击事件,action('Button clicked') 可以在 Action 面板上实时展示事件调用及参数，对于组件自测非常友好，能够帮助开发者快速验证组件的交互行为。


秀一波文档效果:
效果预览完整Demo

添加交互逻辑：让组件动起来

为了让文档更生动直观，我们会添加一些带交互或状态的组件示例。由于在 Storybook 中的写法几乎和正常开发一样，我们需要将文件后缀改为 .tsx，以支持 JSX 和类型。先上示例代码，这是Demo中 Dropdown 组件搜索功能的文档代码片段：

1. import React, { useEffect } from 'react';
2. import { useArgs } from '@storybook/preview-api';
3. // 此处省略了组件文档定义相关代码
4. ......
5. export const Primary: Story = {
6.     args: {
7.         enableTags: [
8.             {
9.                 tag: 'two',
10.                 color: '#ff0000',
11.             },
12.             {
13.                 tag: 'four',
14.                 color: 'orange',
15.             },
16.         ],
17.         options: [],
18.     },
19.     render: () => {
20.         const options = [
21.             {
22.                 value: '1',
23.                 label: 'Option one',
24.                 keyword: '1',
25.             },
26.             {
27.                 value: '2',
28.                 label: 'Option two',
29.                 keyword: '2',
30.             },
31.             {
32.                 value: '3',
33.                 label: 'Option three',
34.                 keyword: '3',
35.             },
36.             {
37.                 value: '4',
38.                 label: 'Option four',
39.                 keyword: '4',
40.             },
41.         ];
42.         const [args, updateArgs] = useArgs<DropdownProps<string>>();
43.         useEffect(() => {
44.             updateArgs({ options: options });
45.         }, []);
46.         const handleSearch = (keyword?: string) => {
47.             if (keyword) {
48.                 const newOptions = options.filter((option) =>
49.                     option.label?.includes(keyword),
50.                 );
51.                 updateArgs({ options: newOptions });
52.             } else {
53.                 updateArgs({ options: options });
54.             }
55.         };
57.         return <Dropdown {...args} onSearch={handleSearch} />;
58.     },
59. };

复制代码

因为Dropdown是一个受控组件，所以这里使用了Storybook的useArgs 这个hooks，目的是为了把结果更新到参数面板上。从代码片段上可以看出，Storybook支持我们添加一个render函数来实现自定义的文档逻辑和效果，在render函数中我们可以正常使用React的功能。
效果预览完整Demo

丰富文档内容：自动生成 vs 手动编辑

在Storybook中， 有两种方式可以为文档添加丰富的图文介绍：

• 使用Autodocs自动生成的基础模板,通过Meta配置的parameters.docs属性，为组件添加介绍内容；
  
• 使用MDX为每个组件创建自定义的文档页面。
  

Autodocs

Autodocs 是 Storybook 的一个功能，它通过读取Meta中parameters.docs属性内容自动生成组件文档。Autodocs 生成的文档会优先展示第一个示例（Primary）的内容以及组件的Props列表，然后再依次展示所有的Story。
Autodocs 的使用方式非常简单，如同上面的案例一样，只需在export default的内容中添加 tags: ['autodocs'],即可（ 跳转至Hello World查看代码 ）。

MDX

MDX 是 Storybook 提供的一项强大功能，它允许我们在文档中同时使用 Markdown 和 JSX（Vue 用户也可以使用相应语法），从而打造更灵活、更可控的组件文档体验。借助 MDX，我们不仅可以像写博客一样撰写说明文字，还可以在任意位置嵌入组件实例、添加交互示例、引入自定义样式和布局，甚至封装文档模板来复用常见结构。
相比于 Storybook 的 Autodocs（自动生成的参数+交互页面），MDX 提供了完全的内容主导权，我们可以自由决定文档的结构、顺序与样式：比如先讲背景、再展示组件、最后讲参数，或者将多个组件组合成场景化示例页，而不受自动文档生成逻辑的限制。
这种方式特别适合需要讲解上下文、构建复杂交互示例，或者进行教学类文档的场景。它让组件文档不仅“可用”，还“可讲、可演示”，真正实现文档与设计、开发的融合。

最后

组件文档不是附加项，而是组件库的标配。Storybook 不仅能写文档，还支持组件自动化测试，真的是又能打又好用。如果你还没试过，强烈建议亲自体验一下！
我已将部分 Storybook 相关文档整理发布在个人网站（aser1989.cn）上，欢迎查阅。
感谢阅读，觉得不错的话，欢迎点赞支持～✌️

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！