storybook

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Storybook

Storybook is a frontend workshop for building UI components and pages in isolation. It enables you to develop UI components without running your entire app (and logic/APIs).

Storybook 是一个用于独立构建UI组件和页面的前端工作台。它让你无需运行整个应用（以及相关逻辑/API）就能开发UI组件。

When to Use

适用场景

Component Libraries: Building a Design System.
Visual Testing: Visualizing all states of a component (Loading, Error, Empty).
Documentation: Auto-generating docs for your team.

组件库：构建设计系统。
视觉测试：可视化组件的所有状态（加载中、错误、空状态）。
文档：为团队自动生成文档。

Quick Start

快速开始

bash

npx storybook@latest init
npm run storybook

Snippet:

tsx

// Button.stories.tsx
import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "./Button";

const meta: Meta<typeof Button> = {
  component: Button,
};
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    primary: true,
    label: "Button",
  },
};

bash

npx storybook@latest init
npm run storybook

代码片段：

tsx

// Button.stories.tsx
import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "./Button";

const meta: Meta<typeof Button> = {
  component: Button,
};
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    primary: true,
    label: "Button",
  },
};

Core Concepts

核心概念

Stories

故事（Stories）

A capture of a component in a specific state. A file can have multiple stories (Primary, Secondary, Disabled).

捕获组件在特定状态下的表现。一个文件可以包含多个故事（主要状态、次要状态、禁用状态等）。

Controls

控件（Controls）

Auto-generated UI knobs that allow you to modify props (Change color, change text) live in the browser.

自动生成的UI旋钮，允许你在浏览器中实时修改组件属性（更改颜色、文本等）。

Addons

插件（Addons）

Plugins that extend functionality. Key ones:

```
Actions
```
: Log events (
```
onClick
```
).
```
A11y
```
: Check accessibility compliance.
```
Interactions
```
: Run small tests inside the story (
```
play
```
function).

扩展功能的插件。关键插件包括：

```
Actions
```
：记录事件（如
```
onClick
```
）。
```
A11y
```
：检查无障碍合规性。
```
Interactions
```
：在故事中运行小型测试（通过
```
play
```
函数）。

Best Practices (2025)

最佳实践（2025）

Do:

Use the
play
function: Allows interactive testing within Storybook (powered by Testing Library).
Use "Autodocs": Enable
```
tags: ['autodocs']
```
to generate automatic documentation pages.
Visual Regression: Integrate with Chromatic (by Storybook maintainers) to detect visual changes in CI.

Don't:

Don't mix business logic: Components in Storybook should be "dumb" (Presentational). If they need data, pass it via args (mocks), don't fetch from APIs inside the component if possible.

建议做法：

使用
play
函数：允许在Storybook内进行交互式测试（基于Testing Library）。
使用“自动文档（Autodocs）”：启用
```
tags: ['autodocs']
```
来生成自动文档页面。
视觉回归测试：与Chromatic（由Storybook维护者开发）集成，在CI中检测视觉变化。

不建议做法：

不要混入业务逻辑：Storybook中的组件应该是“无状态”的（纯展示型）。如果需要数据，通过参数（模拟数据）传递，尽可能不要在组件内部从API获取数据。

References

参考资料

Storybook Documentation

Storybook 官方文档