第10章—快速掌握Storybook

3662字约12分钟

2024-09-19

我们每天都在写各种组件，一般的组件不需要文档，但当你写组件库里的组件，或者项目里的一些公共组件的时候，是需要提供文档的。

这时候我们一般都会用 Storybook。

Storybook 是非常流行的用来构建组件文档的工具。

现在有 80k 的 star 了：

那 Storybook 都提供了啥功能呢？

我们试一下就知道了：

npx create-react-app --template typescript sb-test

用 cra 创建个 react 项目。

然后进入项目，执行 storybook 的初始化：

npx storybook@latest init

打印的日志告诉你 storybook init 是在你的项目里添加 storybook 的最简单方式。

它会在你的 package.json 添加一个 storybook 命令：

执行 npm run storybook，就可以看到这样文档：

npm run storybook

这就是 storybook 生成的组件文档。

这三个组件不是我们自己写的，是 storybook 初始化的时候自带了三个 demo 组件。

我们可以用它来了解下 storybook 的功能。

storybook init 在项目里加了 2 个目录： .storybook 和 src/stories

.storybook 下的是配置文件， src/stories 下的是展示文档用的组件。

Button.tsx 就是传入几个参数，渲染出一个 button：

然后 Button.stories.tsx 里导出了几种 Button 的 props：

导出的这几个 Story 类型的对象是啥呢？

是用来渲染不同 story 的：

也就是 Button 组件传入不同参数的时候渲染的结果。

我们加一个 Story 试试：

export const Guang: Story = {
  args: {
    label: '光光光',
    size: 'large',
    backgroundColor: 'green'
  }
}

页面多了一个 Button 的类型：

也就是说，Storybook 把同一个组件传入不同 props 的情况，叫做一个 Story。

别的地方可能叫做用例或变体，而在 Storybook 里叫做 story。

一个组件包含多个 Story，一个文档里又包含多个组件，和一本书的目录差不多。

所以把这个工具叫做 Storybook。

除了 story 外，上面还有生成的组件文档：

可以看到，列出了每个 props 和描述。

是从注释里拿到的：

我们改了一下注释，刷新下，可以看到文档变了：

这样就可以方便的生成组件文档了。

而且，这些参数都是可以调的：

可以直接修改 props 看组件渲染结果，就很方便。

而且你还可以直接复制它的 jsx 代码：

之前我们是 args 传入参数渲染，你还可以用 render 函数的方式自己渲染：

export const Guang: Story = {
  args: {
    label: '光光光',
    size: 'large',
    backgroundColor: 'green'
  },
  render(args) {
    return <div>
      <button>aaaa</button>
      <Button {...args}/>
      <button>bbb</button>
    </div>
  }
}

render 函数的参数就是 args，你可以自己返回 jsx（这时要把文件后缀名改为 tsx）。

这样，渲染内容就是自己控制的：

而且有的组件不只是传入 props 就可以了，还需要一些点击、输入等事件。

storybook 支持写这类脚本：

export const Guang: Story = {
  args: {
    label: '光光光',
    size: 'large',
    backgroundColor: 'green'
  },
  render(args) {
    return <div>
      <button>aaaa</button>
      <Button {...args}/>
      <button>bbb</button>
    </div>
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const btn = await canvas.getByRole('button', {
      name: /光光光/i,
    });
    await userEvent.click(btn);

    btn.textContext = '东';
  },
}

比如我写了找到内容为光光光的 button，点击，然后把它的内容改为东。

组件渲染完就会自动执行 play 函数：

当然，这个案例不大好，用表单来测试 play 功能会更好点：

此外，你还可以在渲染组件之前请求数据，然后把数据传入 render 函数再渲染：


export const Guang: Story = {
  args: {
    label: '光光光',
    size: 'large',
    backgroundColor: 'green'
  },
  render(args, meta) {
    const list = meta.loaded.list;

    return <div>
      <div>{list.join(',')}</div>
      <Button {...args}/>
    </div>
  },
  loaders: [
    async () => {
      await '假装 fetch'
      return {
        list: [
          111,
          222,
          333
        ]
      }
    },
  ]
}

渲染出来是这样的：

感受到 Storybook 的强大了么？

不只是自动生成组件文档这么简单，你可以定义不同的 Story，这些 Story 可以传入不同 props、可以请求数据、可以自定义渲染内容、还可以定义自动执行的脚本。

有同学会觉得，这个自动执行的 play 函数其实和测试脚本差不多。

确实，play 函数是可以当作测试脚本来用的。

安装用到的包：

npm install @storybook/jest

使用 expect 来断言：

await expect(btn.textContent).toEqual('光光光');

await expect(btn.style.backgroundColor).toEqual('green');

这样一打开组件会自动跑 play 函数，也就会自动执行断言：

改下 expect，断言失败就是这样：

这样，组件有没有通过测试用例，打开一看就知道了。

就很方便。

但是，组件多了的话，这样一个个点开看也挺麻烦的，这时候就可以用 cli 跑了：

安装用到的包：

npm install @storybook/testing-library

然后：

npx test-storybook

xx.stories.tsx 文件里除了 Story 外，还会导出 meta 信息：

这些都很简单，改一下就知道了：

title 是这个：

paremeters 的 layout 是这个：

这里还可以配置背景色：

然后 argTypes 是这个：

具体什么类型的参数用什么控件，可以用到的时候查一下文档。

这些都是与 Story 无关的一些东西，所以放在 Meta 里。

此外，你还可以用 Storybook 写 MDX 文档。

mdx 是 markdown + jsx 的混合语法，用来写文档很不错。

在这个目录下的文档：

都会被放到这里：

我们加一个试试：

这样，当你想在组件文档里加一些别的说明文档，就可以这样加。

而且，组件文档的格式也是可以自定义的。

可以在 .storybook 下的 preview.tsx 里配置这个：

大概过了一遍 Storybook 的功能之后，我们把上节的 Calendar 组件拿过来试一下。

把那个项目的 Calendar 目录复制过来：

然后在 stories 目录下添加一个 Calendar.stories.tsx

import type { Meta, StoryObj } from '@storybook/react';
import Calendar from '../Calendar/index';
import dayjs from 'dayjs';

const meta = {
    title: '日历组件',
    component: Calendar,
    parameters: {
        layout: 'centered'
    },
    tags: ['autodocs']
} satisfies Meta<typeof Calendar>;

export default meta;

type Story = StoryObj<typeof meta>;

export const Value: Story = {
    args: {
        value: dayjs('2023-11-08')
    },
};

export const DateRender: Story = {
    args: {
        value: dayjs('2023-11-08'),
        dateRender(currentDate) {
            return <div>
                日期{currentDate.date()}
            </div>
        }
    },
};

export const DateInnerContent: Story = {
    args: {
        value: dayjs('2023-11-08'),
        dateInnerContent(currentDate) {
            return <div>
                日期{currentDate.date()}
            </div>
        }
    },
};

export const Locale: Story = {
    args: {
        value: dayjs('2023-11-08'),
        locale: 'en-US'
    },
};

我们添加了 4 个 story。

安装用到的 dayjs、classnames 和 node-sass

npm install --save classnames

npm install --save dayjs

npm install --save-dev node-sass

然后把 storybook 文档服务跑起来：

npm run storybook

都没啥问题。

不过 value 的控件类型不对：

但是现在我们要传入的是 dayjs 对象，就算是用了 date 的控件也不行。

先改成 date 类型试试：

控件确实对了，但是修改日期点击刷新后，会报错：

因为控件传入的是一个 date 的毫秒值。

那怎么办呢？

这时候就要把 story 改成 render 的方式了：


const renderCalendar = (args: CalendarProps) => {
    if(typeof args.value === 'number') {
        return <Calendar {...args} value={dayjs(new Date(args.value))}/>
    }

    return <Calendar {...args}/>
}

export const Value: Story = {
    args: {
        value: dayjs('2023-11-08')
    },
    render: renderCalendar
};