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

ASER_19892025-04-14 8:09

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

Dumi

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

Storybook

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

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

安装

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

shell 复制代码 
npx storybook@latest init

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

运行

shell 复制代码 
npm run storybook

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

配置

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

  • 集中存放： 将所有文档统一放在指定目录，例如 src/stories/，类似于示例文档的管理方式。
  1. 优点：结构清晰，文档与业务代码解耦，方便统一管理。
  2. 适用场景：适合大规模组件库开发，尤其是需要独立维护文档的项目。
  • 跟随组件： 每个组件的 Story 文档与组件代码存放在一起，例如 src/components/Button/Button.stories.tsx。
  1. 优点：文档紧贴组件，便于开发和维护，不需要在多个目录之间跳转。
  2. 适用场景：适合产品型项目，组件文档随组件代码更新，保持同步。

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

typescript 复制代码 
const config: StorybookConfig = {
    stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],

Hello World

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

typescript 复制代码 
import { Meta, StoryObj } from '@storybook/react';
import Button, { ButtonProps } from './index';
import { action } from '@storybook/addon-actions';

export default {
    title: 'Atoms/Button',   // 组件在 Storybook 中的分组与显示路径。`'Atoms/Button'` 表示组件会在 `Atoms` 分组下展示为 `Button`。
    component: Button,       // 关联的 React 组件
    tags: ['autodocs'],      // `'autodocs'` 表示启用自动文档生成功能
    argTypes: {},            // 定义组件 props 的控制类型、分类、描述等
    args: {},                // 为组件设置默认的 props 值，在所有 stories 中共享，可在 UI 面板中修改
} as Meta<ButtonProps>;

export type Story = StoryObj<ButtonProps>;
export const Primary: Story = {
  // 指定组件运行的props值，可在 UI 面板中修改
    args: {
        children: 'Button',    
        type: 'primary',
        onClick: action('Button clicked'), 
    },
};

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

秀一波原创专属文档效果（不是图片，可点击体验）:
效果预览完整Demo

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

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

typescript 复制代码 
import React, { useEffect } from 'react';
import { useArgs } from '@storybook/preview-api';
// 此处省略了组件文档定义相关代码
......
export const Primary: Story = {
    args: {
        enableTags: [
            {
                tag: 'two',
                color: '#ff0000',
            },
            {
                tag: 'four',
                color: 'orange',
            },
        ],
        options: [],
    },
    render: () => {
        const options = [
            {
                value: '1',
                label: 'Option one',
                keyword: '1',
            },
            {
                value: '2',
                label: 'Option two',
                keyword: '2',
            },
            {
                value: '3',
                label: 'Option three',
                keyword: '3',
            },
            {
                value: '4',
                label: 'Option four',
                keyword: '4',
            },
        ];
        const [args, updateArgs] = useArgs<DropdownProps<string>>();
        useEffect(() => {
            updateArgs({ options: options });
        }, []);
        const handleSearch = (keyword?: string) => {
            if (keyword) {
                const newOptions = options.filter((option) =>
                    option.label?.includes(keyword),
                );
                updateArgs({ options: newOptions });
            } else {
                updateArgs({ options: options });
            }
        };

        return <Dropdown {...args} onSearch={handleSearch} />;
    },
};

因为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。如：
多个Story示例完整Demo

Autodocs 的使用方式非常简单，如同上面的案例一样，只需在export default的内容中添加 tags: ['autodocs'],即可（ [跳转至Hello World](#跳转至Hello World)查看代码 ）。

MDX

MDX 是 Storybook 提供的一项强大功能，它允许我们在文档中同时使用 Markdown 和 JSX（Vue 用户也可以使用相应语法），从而打造更灵活、更可控的组件文档体验。借助 MDX，我们不仅可以像写博客一样撰写说明文字，还可以在任意位置嵌入组件实例、添加交互示例、引入自定义样式和布局，甚至封装文档模板来复用常见结构。

相比于 Storybook 的 Autodocs（自动生成的参数+交互页面），MDX 提供了完全的内容主导权，我们可以自由决定文档的结构、顺序与样式：比如先讲背景、再展示组件、最后讲参数，或者将多个组件组合成场景化示例页，而不受自动文档生成逻辑的限制。

这种方式特别适合需要讲解上下文、构建复杂交互示例，或者进行教学类文档的场景。它让组件文档不仅"可用"，还"可讲、可演示"，真正实现文档与设计、开发的融合。

最后

组件文档不是附加项，而是组件库的标配。Storybook 不仅能写文档，还支持组件自动化测试，真的是又能打又好用。如果你还没试过，强烈建议亲自体验一下！

我已将部分 Storybook 相关文档整理发布在个人网站（aser1989.cn）上，欢迎查阅。

感谢阅读，觉得不错的话，欢迎点赞支持～✌️

热门推荐
01我决定放弃搞 Java 了02RAG 实践- Ollama+RagFlow 部署本地知识库03DeepSeek各版本说明与优缺点分析04计算机视觉——基于 Yolov8 目标检测与 OpenCV 光流实现目标追踪05DeepSeek RAGFlow构建本地知识库系统06如何在WPS和Word/Excel中直接使用DeepSeek功能07【FPGA】——DDS信号发生器设计08汽车上的各种质量：整备质量、总质量、装载质量、簧上质量、簧下质量09本地化部署AI知识库：基于Ollama+DeepSeek+AnythingLLM保姆级教程10蓝桥杯之c++入门（四）【循环】