UI 视觉设计 / 系统课时

用 Storybook 记录可操作示例

用 Storybook 记录可操作示例

设计评审看到的按钮截图无法说明禁用、加载和点击后的行为。本篇以 React、Vite、TypeScript 的 Button 为例,把常用状态写成 Storybook 故事,并通过 Controls 调整属性、用 play 验证回调,让设计、开发和测试复现同一组结果。

学习目标

  • 用 args 和 argTypes 固定状态、开放可编辑的属性控件。
  • 用 fn() 与 play 记录一次真实点击并验证回调。
  • 在 Storybook 界面检查状态、交互记录与自动文档。

创建可运行的预览环境

以下使用 Storybook 10.x 的 CSF 3 写法,配合 React、Vite 和 TypeScript。准备 Node.js 22.19 或更高兼容版本及 npm 10+;Storybook 10 为 ESM-only,旧 CommonJS 配置不应直接照搬。先建立独立示例项目,再使用初始化向导选择包含 Docs、Testing 的 Recommended 配置。

bash
npm create vite@latest storybook-demo -- --template react-ts
cd storybook-demo
npm install
npm create storybook@10

预期结果:项目新增 .storybook/main.ts 等配置,package.json 出现 storybook 与 build-storybook 脚本;具体安装提示以向导为准。

bash
npm run storybook

预期结果:终端打印本地 Storybook 预览地址,浏览器出现故事导航和预览区;实际端口记为 <PORT>,不要求固定数字。

先让组件的状态可观察

在 src/components/Button.tsx 建立最小组件。用 variant 决定外观,用 disabled、loading 分别表示不可操作和处理中;加载态必须实际禁用按钮,避免用户连续提交。

tsx
export type ButtonProps = {
  label: string;
  variant?: 'primary' | 'secondary';
  disabled?: boolean;
  loading?: boolean;
  onClick?: () => void;
};

export function Button({
  label,
  variant = 'primary',
  disabled = false,
  loading = false,
  onClick,
}: ButtonProps) {
  const inactive = disabled || loading;

  return (
    <button
      type="button"
      disabled={inactive}
      aria-busy={loading}
      onClick={onClick}
      style={{
        padding: '10px 16px',
        borderRadius: 8,
        border: '1px solid #8AA4C7',
        background: variant === 'primary' ? '#2366B1' : '#EFF4FA',
        color: variant === 'primary' ? '#FFFFFF' : '#243448',
        opacity: inactive ? 0.6 : 1,
      }}
    >
      {loading ? '保存中…' : label}
    </button>
  );
}

预期结果:默认按钮显示“保存”;传入 loading={true} 时显示“保存中…”,同时具有 disabled 属性和 aria-busy="true"。颜色只是本例的可观察差异,实际项目应替换为组件库的语义令牌。

用 Story 固定属性与交互

新建同目录的 Button.stories.tsx。meta.args 提供统一基线;每个具名导出固定一个状态;argTypes 决定 Controls 的操作方式。onClick 使用 fn(),这样 Actions 能记录调用,play 也能直接断言次数。

tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { expect, fn } from 'storybook/test';
import { Button } from './Button';

const meta = {
  title: 'Actions/Button',
  component: Button,
  tags: ['autodocs'],
  args: {
    label: '保存',
    variant: 'primary',
    disabled: false,
    loading: false,
    onClick: fn(),
  },
  argTypes: {
    label: { control: 'text' },
    variant: {
      control: 'inline-radio',
      options: ['primary', 'secondary'],
    },
    disabled: { control: 'boolean' },
    loading: { control: 'boolean' },
    onClick: { control: false },
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {};
export const Secondary: Story = {
  args: { variant: 'secondary' },
};
export const Disabled: Story = {
  args: { disabled: true },
};
export const Loading: Story = {
  args: { loading: true },
};
export const Clicked: Story = {
  play: async ({ canvas, userEvent, args }) => {
    // 操作预览画布中的按钮,而不是直接调用处理函数。
    await userEvent.click(canvas.getByRole('button', { name: '保存' }));
    await expect(args.onClick).toHaveBeenCalledTimes(1);
  },
};

预期结果:导航下出现 Primary、Secondary、Disabled、Loading、Clicked 五个故事,启用 Docs 后可见自动文档。打开 Clicked 时,play 模拟一次点击;测试断言通过,Actions 可以观察到 onClick 调用。storybook/test 适用于本例的 10.x;Storybook 8 常见的旧导入路径是 @storybook/test,不要混装跨大版本包。

在界面中复现并验收

Storybook 的左侧导航用于选择固定 Story,中间 Canvas 展示组件,Controls 用来临时改变 args,Actions 展示事件记录;启用相关测试功能后可查看交互步骤。面板标签及位置可能随版本和已启用的插件变化。

Storybook 导航、画布、属性控件和交互验证区域的对应关系

按以下顺序核对,避免只确认“页面能渲染”:

检查操作 应见结果
选择 Secondary 按钮为浅色底、深色字
在 Primary 中将 disabled 设为 true 按钮不可点击,事件不会新增
将 loading 设为 true 文案变成“保存中…”,按钮不可点击
打开 Clicked 并检查交互结果 自动点击一次,onClick 调用次数为 1
打开 Docs 能找到各 Story 和属性说明

Controls 的手动改动仅用于当前调试,不能代替提交到代码仓库的 Story args。遇到故事未出现,先检查文件后缀 .stories.tsx 和 .storybook/main.ts 的 stories 匹配范围;交互断言未执行时,检查 Testing 功能是否启用、是否使用 fn(),以及 userEvent、expect 是否都被 await。

把示例变成团队交付物

设计评审记录 Story 名称与验收状态,例如 Actions/Button/Loading 对应“禁用且显示处理中”;前端审查 label、variant、disabled、loading 是否就是生产组件的真实接口;测试人员重跑 Clicked,检查断言是否通过。不要只分享临时调整后的 Canvas 截图,应提交 Button.tsx 和 Button.stories.tsx。

bash
npm run build-storybook

预期结果:构建成功后默认生成 storybook-static 静态站点目录,适合交给静态站点托管或 CI 发布;构建输出的耗时、路径详情随环境变化。若组件依赖接口响应、登录态或主题 Provider,先在 Story 中提供固定 mock 数据或装饰器,否则同一个故事在不同人的环境里可能呈现不同结果。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Storybook 记录可操作示例

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通