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

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 等）并进行相应的安装：

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

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

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

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

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

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

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 面板上实时展示事件调用及参数，对于组件自测非常友好，能够帮助开发者快速验证组件的交互行为。