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 配置。
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 脚本;具体安装提示以向导为准。
npm run storybook预期结果:终端打印本地 Storybook 预览地址,浏览器出现故事导航和预览区;实际端口记为 <PORT>,不要求固定数字。
先让组件的状态可观察
在 src/components/Button.tsx 建立最小组件。用 variant 决定外观,用 disabled、loading 分别表示不可操作和处理中;加载态必须实际禁用按钮,避免用户连续提交。
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 也能直接断言次数。
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 展示事件记录;启用相关测试功能后可查看交互步骤。面板标签及位置可能随版本和已启用的插件变化。

按以下顺序核对,避免只确认“页面能渲染”:
| 检查操作 | 应见结果 |
|---|---|
| 选择 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。
npm run build-storybook预期结果:构建成功后默认生成 storybook-static 静态站点目录,适合交给静态站点托管或 CI 发布;构建输出的耗时、路径详情随环境变化。若组件依赖接口响应、登录态或主题 Provider,先在 Story 中提供固定 mock 数据或装饰器,否则同一个故事在不同人的环境里可能呈现不同结果。