UI 视觉设计 / 系统课时
在 Storybook 展示变体与文档
在 Storybook 展示变体与文档
这篇将一个 React Button 变成可交互的组件说明:设计师能切换尺寸、层级、禁用和加载状态,现场检查外观与点击反馈;开发者则能从同一组 Stories 查看 Props、示例和构建产物,不再只靠静态截图对齐。
学习目标
- 使用 CSF3 的
Meta、StoryObj和args建立可复用的按钮状态。 - 配置 Controls、Actions 与 Autodocs,呈现可操作的组件文档。
- 按明确的验收项核查故事覆盖、交互反馈和静态构建。
准备 Storybook 环境
下面以 Storybook 10.6 + React + Vite + TypeScript 为例。先确认项目已能启动,使用 Node.js 20+、npm 10+、Vite 5+;在已有 React 项目根目录安装,并在向导中启用 Docs 功能。
npm create storybook@10.6 --features docs预期结果:安装器生成 .storybook/main.ts 等配置和 package.json 中的 storybook、build-storybook 脚本。检查 .storybook/main.ts 的 framework 为 @storybook/react-vite,且 addons 包含 @storybook/addon-docs;不同项目的生成文件可能略有差异。
编写可观察状态的 Button
先让组件真正响应 Props,否则 Controls 只是改动面板数值。创建 src/components/Button.tsx;示例使用内联样式便于直接运行,正式组件应改为消费设计令牌和样式类。
import type { ButtonHTMLAttributes } from 'react';
type ButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> & {
label: string;
variant?: 'primary' | 'secondary';
size?: 'sm' | 'md';
loading?: boolean;
};
export function Button({
label,
variant = 'primary',
size = 'md',
loading = false,
disabled = false,
type = 'button',
style,
...rest
}: ButtonProps) {
// 加载中必须阻止再次点击,不能只换文案。
const unavailable = loading || disabled;
const primary = variant === 'primary';
return (
<button
{...rest}
type={type}
disabled={unavailable}
aria-busy={loading || undefined}
style={{
backgroundColor: primary ? '#2563eb' : '#e5e7eb',
color: primary ? '#ffffff' : '#111827',
border: '1px solid transparent',
borderRadius: 6,
padding: size === 'sm' ? '6px 12px' : '10px 16px',
opacity: unavailable ? 0.5 : 1,
cursor: unavailable ? 'not-allowed' : 'pointer',
...style,
}}
>
{loading ? '处理中…' : label}
</button>
);
}预期页面效果:primary 是蓝底白字,secondary 是浅灰底深色字;sm 内边距为 6px 12px,md 为 10px 16px。loading=true 显示“处理中…”且原生按钮被禁用。
为变体配置 Stories、Controls 和文档
在同目录创建 Button.stories.tsx。args 给所有故事统一默认值;单个 Story 只覆盖与该状态有关的 Props。argTypes 决定面板控件,tags: ['autodocs'] 使 Docs 页面自动汇总文档、Props 和示例。
import type { Meta, StoryObj } from '@storybook/react-vite';
import { fn } from 'storybook/test';
import { Button } from './Button';
const meta = {
title: '组件/Button',
component: Button,
tags: ['autodocs'],
parameters: {
docs: {
description: {
component: '操作按钮:主操作优先使用 Primary;加载时不可重复提交。',
},
},
},
args: {
label: '保存更改',
variant: 'primary',
size: 'md',
disabled: false,
loading: false,
onClick: fn(),
},
argTypes: {
label: { control: 'text', description: '按钮可见文案' },
variant: {
control: 'inline-radio',
options: ['primary', 'secondary'],
},
size: { control: 'radio', options: ['sm', 'md'] },
disabled: { control: 'boolean' },
loading: { control: 'boolean' },
// 回调在 Actions 中检查,不作为可编辑字符串。
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 Small: Story = { args: { size: 'sm' } };
export const Disabled: Story = { args: { disabled: true } };
export const Loading: Story = { args: { loading: true } };
// 组合用例同时展示主次按钮,而非再复制一个静态截图。
export const Usage: Story = {
render: (args) => (
<div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
<Button {...args} />
<Button {...args} variant="secondary" label="取消" />
</div>
),
};预期结果:故事导航中出现六个可独立预览的示例,Usage 同时显示“保存更改”和“取消”两个按钮。这里两按钮为演示共用一个 onClick 监视函数,业务页面应各自绑定保存和取消处理函数。fn() 产生可记录的事件处理器,正常点击会进入 Actions;禁用时浏览器不会触发该点击事件。
让设计师检查 Canvas 和 Docs
npm run storybook预期结果:浏览器打开本地 Storybook,开发服务器地址和端口以终端实际输出为准(可记为 <PORT>)。在左侧找到 组件 / Button 下的各个 Story,逐项操作:
- 打开
Primary的 Canvas,在下方 Controls 改variant为secondary、size为sm、label为“确认提交”,预览应立即改变。 - 把
disabled设为true后点击:按钮变淡,Actions 不新增点击记录;恢复false,点击一次应新增一条onClick记录。 - 把
loading设为true:文案变为“处理中…”,按钮不可操作;再检查预设的Disabled、Loading与Usage是否符合设计稿。 - 打开该组件自动生成的 Docs 页面,核对组件说明、Controls/Props 表和各个 Story 示例;查看源码示例是否使用预期的 Props 名称。

核对覆盖范围与发布产物
设计验收至少记录以下五种状态:Primary 蓝底白字、Secondary 灰底深字、Small 小间距、Disabled 不可点击、Loading 不可重复提交。再把 label 改为 12~16 个汉字检查文案扩展;焦点样式还需要用 Tab、Enter、Space 操作实际核查,不能认为 Controls 已自动验证键盘可访问性。鼠标悬停、暗色主题等未实现的状态,不应在文档中宣称已覆盖。
npm run build-storybook预期结果:命令成功退出,并在默认配置下生成 storybook-static/ 静态站点(若配置了自定义输出目录,以项目配置为准)。若 Docs 缺失,先检查 .storybook/main.ts 是否注册 @storybook/addon-docs,以及 Story 文件是否带 autodocs 标签;若 Story 不显示,则核对文件名是否匹配配置中的 stories 匹配规则。团队评审时应把这份可交互文档与 Figma 变体名称逐项对应,而不是仅审阅图片。可参阅 Storybook 官方 Autodocs 文档。