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 功能。

bash
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;示例使用内联样式便于直接运行,正式组件应改为消费设计令牌和样式类。

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 和示例。

tsx
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

bash
npm run storybook

预期结果:浏览器打开本地 Storybook,开发服务器地址和端口以终端实际输出为准(可记为 <PORT>)。在左侧找到 组件 / Button 下的各个 Story,逐项操作:

  1. 打开 Primary 的 Canvas,在下方 Controls 改 variant 为 secondary、size 为 sm、label 为“确认提交”,预览应立即改变。
  2. 把 disabled 设为 true 后点击:按钮变淡,Actions 不新增点击记录;恢复 false,点击一次应新增一条 onClick 记录。
  3. 把 loading 设为 true:文案变为“处理中…”,按钮不可操作;再检查预设的 Disabled、Loading 与 Usage 是否符合设计稿。
  4. 打开该组件自动生成的 Docs 页面,核对组件说明、Controls/Props 表和各个 Story 示例;查看源码示例是否使用预期的 Props 名称。

Storybook 中变体检查与文档查看位置

核对覆盖范围与发布产物

设计验收至少记录以下五种状态:Primary 蓝底白字、Secondary 灰底深字、Small 小间距、Disabled 不可点击、Loading 不可重复提交。再把 label 改为 12~16 个汉字检查文案扩展;焦点样式还需要用 Tab、Enter、Space 操作实际核查,不能认为 Controls 已自动验证键盘可访问性。鼠标悬停、暗色主题等未实现的状态,不应在文档中宣称已覆盖。

bash
npm run build-storybook

预期结果:命令成功退出,并在默认配置下生成 storybook-static/ 静态站点(若配置了自定义输出目录,以项目配置为准)。若 Docs 缺失,先检查 .storybook/main.ts 是否注册 @storybook/addon-docs,以及 Story 文件是否带 autodocs 标签;若 Story 不显示,则核对文件名是否匹配配置中的 stories 匹配规则。团队评审时应把这份可交互文档与 Figma 变体名称逐项对应,而不是仅审阅图片。可参阅 Storybook 官方 Autodocs 文档。

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

目录与阅读设置

阅读设置

17

记录一个想法

在 Storybook 展示变体与文档

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

登录哪都通