为什么是 Storybook？

问题

¥The problem

网络的普遍性将更多的复杂性推向前端。它始于响应式网页设计，将每个用户界面从一个变成 10、100、1000 个不同的用户界面。随着时间的推移，设备、浏览器、可访问性、性能和异步状态等其他要求不断增加。

¥The web’s universality is pushing more complexity into the frontend. It began with responsive web design, which turned every user interface from one to 10, 100, 1000 different user interfaces. Over time, additional requirements piled on like devices, browsers, accessibility, performance, and async states.

组件驱动工具（如 React、Vue 3 和 Angular）有助于将复杂的 UI 分解为简单的组件，但它们并不是灵丹妙药。随着前端的增长，组件的数量也会增加。成熟的项目可以包含数百个组件，这些组件会产生数千种离散变化。

¥Component-driven tools like React, Vue 3, and Angular help break down complex UIs into simple components but they’re not silver bullets. As frontends grow, the number of components swells. Mature projects can contain hundreds of components that yield thousands of discrete variations.

更复杂的是，这些 UI 很难调试，因为它们纠缠在业务逻辑、交互状态和应用上下文中。

¥To complicate matters further, those UIs are painful to debug because they’re entangled in business logic, interactive states, and app context.

现代前端的广度压倒了现有的工作流程。开发者必须考虑无数的 UI 变化，但却没有能力开发或组织所有这些变化。你最终会遇到这样的情况：UI 更难构建、工作起来更不令人满意且更脆弱。

¥The breadth of modern frontends overwhelm existing workflows. Developers must consider countless UI variations, yet aren’t equipped to develop or organize them all. You end up in a situation where UIs are tougher to build, less satisfying to work on, and brittle.

解决方案

¥The solution

独立构建 UI

¥Build UIs in isolation

每个 UI 现在都是 component。组件的超能力在于你无需启动整个应用即可查看它们的渲染方式。你可以通过传入属性、模拟数据或伪造事件来单独渲染特定的变体。

¥Every piece of UI is now a component. The superpower of components is that you don't need to spin up the whole app just to see how they render. You can render a specific variation in isolation by passing in props, mocking data, or faking events.

Storybook 被打包为一个小型的、仅用于开发的 workshop，与你的应用共存。它提供了一个独立的 iframe 来渲染组件，而不会受到应用业务逻辑和上下文的干扰。这可以帮助你将开发重点放在组件的每个变体上，即使是难以触及的边缘情况。

¥Storybook is packaged as a small, development-only, workshop that lives alongside your app. It provides an isolated iframe to render components without interference from app business logic and context. That helps you focus development on each variation of a component, even the hard-to-reach edge cases.

将 UI 变化捕获为“故事”

¥Capture UI variations as “stories”

单独开发组件变体时，将其保存为故事。故事 是一种声明性语法，用于提供属性和模拟数据以模拟组件变化。每个组件可以有多个故事。每个故事都允许你演示该组件的特定变体以验证外观和行为。

¥When developing a component variation in isolation, save it as a story. Stories are a declarative syntax for supplying props and mock data to simulate component variations. Each component can have multiple stories. Each story allows you to demonstrate a specific variation of that component to verify appearance and behavior.

你为细粒度的 UI 组件变化编写故事，然后在开发、测试和文档中使用这些故事。

¥You write stories for granular UI component variation and then use those stories in development, testing, and documentation.

import type { Meta, StoryObj } from '@storybook/react';
 
import { Histogram } from './Histogram';
 
const meta: Meta<typeof Histogram> = {
  component: Histogram,
};
 
export default meta;
type Story = StoryObj<typeof Histogram>;
 
export const Default: Story = {
  args: {
    dataType: 'latency',
    showHistogramLabels: true,
    histogramAccentColor: '#1EA7FD',
    label: 'Latency distribution',
  },
};

Storybook 跟踪每个故事

¥Storybook keeps track of every story

Storybook 是你的 UI 组件及其故事的交互式目录。过去，你必须启动应用，导航到页面，并将 UI 扭曲到正确的状态。这非常浪费时间，并且会拖慢前端开发。使用 Storybook，你可以跳过所有这些步骤并直接跳转到处理特定状态下的 UI 组件。

¥Storybook is an interactive directory of your UI components and their stories. In the past, you'd have to spin up the app, navigate to a page, and contort the UI into the right state. This is a huge waste of time and bogs down frontend development. With Storybook, you can skip all those steps and jump straight to working on a UI component in a specific state.

好处

¥Benefits

当你为组件编写故事时，你可以免费获得许多额外的好处。

¥When you write stories for components, you get a bunch of additional benefits for free.

📝 开发更耐用的 UI

¥📝 Develop UIs that are more durable

隔离组件和页面并将其用例跟踪为 stories。验证难以触及的 UI 边缘情况。使用插件模拟组件所需的一切 - 上下文、API 请求、设备功能等。

¥Isolate components and pages and track their use cases as stories. Verify hard-to-reach edge cases of UI. Use addons to mock everything a component needs—context, API requests, device features, etc.

✅ 以更少的努力和无瑕疵的方式测试 UI

¥✅ Test UIs with less effort and no flakes

故事是一种实用、可重复的跟踪 UI 状态的方式。在开发过程中使用它们对 UI 进行抽样测试。Storybook 提供内置工作流程，用于自动 组件、可访问性 和 Visual 测试。或者使用 将它们导入到其他 JavaScript 测试工具中 将故事用作测试用例。

¥Stories are a pragmatic, reproducible way of tracking UI states. Use them to spot-test the UI during development. Storybook offers built-in workflows for automated Component, Accessibility, and Visual testing. Or use stories as test cases by importing them into other JavaScript testing tools.

📚 供你的团队重复使用的文档 UI

¥📚 Document UI for your team to reuse

Storybook 是你的 UI 的唯一真实来源。故事索引所有组件及其各种状态，使你的团队可以轻松找到和重用现有的 UI 模式。Storybook 还会从这些故事中自动生成 documentation。

¥Storybook is the single source of truth for your UI. Stories index all your components and their various states, making it easy for your team to find and reuse existing UI patterns. Storybook also auto-generates documentation from those stories.

📤 分享 UI 的实际工作原理

¥📤 Share how the UI actually works

故事展示了 UI 的实际工作方式，而不仅仅是它们应该如何工作的图片。这让每个人都了解当前生产的内容。发布 Storybook 用于获得队友的认可。或者在 wiki、Markdown 和 Figma 中 embed 它们以简化协作。

¥Stories show how UIs actually work, not just a picture of how they're supposed to work. That keeps everyone aligned on what's currently in production. Publish Storybook to get sign-off from teammates. Or embed them in wikis, Markdown, and Figma to streamline collaboration.

🚦 自动化 UI 工作流

¥🚦Automate UI workflows

Storybook 与你的持续集成工作流程兼容。将其添加为 CI 步骤以自动化用户界面测试、与队友一起审查实现情况并获得利益相关者的认可。

¥Storybook is compatible with your continuous integration workflow. Add it as a CI step to automate user interface testing, review implementation with teammates, and get signoff from stakeholders.

编写一次故事，随处重复使用

¥Write stories once, reuse everywhere

Storybook 由 组件故事格式 提供支持，组件故事格式 是基于 JavaScript ES6 模块的开放标准。这使故事能够在开发、测试和设计工具之间进行互操作。每个故事都导出为 JavaScript 函数，使你可以将其与其他工具一起重复使用。无供应商锁定。

¥Storybook is powered by Component Story Format, an open standard based on JavaScript ES6 modules. This enables stories to interoperate between development, testing, and design tools. Each story is exported as a JavaScript function enabling you to reuse it with other tools. No vendor lock-in.

使用 Jest 或 Vitest 和 测试库 重用故事来验证交互。将它们放入 Chromatic 进行可视化测试。使用 Axe 审核故事可访问性。或者使用 Playwright 和 Cypress 测试用户流程。重用可解锁更多工作流程，无需额外费用。

¥Reuse stories with Jest or Vitest and Testing Library to verify interactions. Put them in Chromatic for visual testing. Audit story accessibility with Axe. Or test user flows with Playwright and Cypress. Reuse unlocks more workflows at no extra cost.

Storybook 旨在帮助你更快地开发复杂的 UI，具有更高的耐用性和更低的维护成本。它被数百个 领先公司 和数千个 developers 使用。

¥Storybook is purpose-built to help you develop complex UIs faster with greater durability and lower maintenance. It’s used by 100s of leading companies and thousands of developers.