什么是故事？

故事捕获 UI 组件的渲染状态。开发者为每个组件编写多个故事，描述组件可以支持的所有“有趣”状态。

¥A story captures the rendered state of a UI component. Developers write multiple stories per component that describe all the “interesting” states a component can support.

当你安装 Storybook 时，CLI 创建了示例组件，演示了你可以使用 Storybook 构建的组件类型：按钮、标题和页面。

¥When you installed Storybook, the CLI created example components that demonstrate the types of components you can build with Storybook: Button, Header, and Page.

每个示例组件都有一组故事，显示它支持的状态。你可以在 UI 中浏览故事，并在以 .stories.js|ts 结尾的文件中查看它们背后的代码。故事以 组件故事格式 (CSF) 编写，这是一种基于 ES6 模块的编写组件示例的标准。

¥Each example component has a set of stories that show the states it supports. You can browse the stories in the UI and see the code behind them in files that end with .stories.js|ts. The stories are written in Component Story Format (CSF), an ES6 modules-based standard for writing component examples.

让我们从 Button 组件开始。故事是一个描述如何渲染相关组件的对象。以下是如何在“主要”状态下渲染 Button 并导出名为 Primary 的故事。

¥Let’s start with the Button component. A story is an object that describes how to render the component in question. Here’s how to render Button in the “primary” state and export a story called Primary.

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',
  },
};

单击 Storybook 侧栏中的 Button 即可查看渲染的 Button。请注意 args 中指定的值如何用于渲染组件并匹配 控件 选项卡中表示的值。在你的故事中使用 args 有额外的好处：

¥View the rendered Button by clicking on it in the Storybook sidebar. Note how the values specified in args are used to render the component and match those represented in the Controls tab. Using args in your stories has additional benefits:

• Button 的回调记录到 操作 选项卡中。单击尝试。

  ¥Button's callbacks are logged into the Actions tab. Click to try it.

• Button 的参数可在“控件”选项卡中动态编辑。调整控件。

  ¥Button's arguments are dynamically editable in the Controls tab. Adjust the controls.

使用故事

¥Working with stories

Storybook 使一次在一个状态（即故事）中处理一个组件变得容易。当你编辑组件的代码或其故事时，Storybook 将立即在浏览器中重新渲染。无需手动刷新。

¥Storybook makes it easy to work on one component in one state (aka a story) at a time. When you edit a component's code or its stories, Storybook will instantly re-render in the browser. No need to refresh manually.

创建新故事

¥Create a new story

如果你正在开发尚无任何故事的组件，则可以单击侧栏中的 ➕ 按钮来搜索你的组件并为你创建一个基本故事。

¥If you're working on a component that does not yet have any stories, you can click the ➕ button in the sidebar to search for your component and have a basic story created for you.

你还可以为新故事创建一个故事文件。我们建议将现有故事文件复制/粘贴到组件源文件旁边，然后根据你的组件进行调整。

¥You can also create a story file for your new story. We recommend copy/pasting an existing story file next to the component source file, then adjusting it for your component.

如果你正在开发已经有其他故事的组件，则可以使用 控件插件 调整控件的值，然后将这些更改保存为新故事。

¥If you're working on a component that already has other stories, you can use the Controls addon to adjust the value of a control and then save those changes as a new story.

或者，如果你愿意，可以编辑故事文件的代码以为你的故事添加一个新的命名导出：

¥Or, if you prefer, edit the story file's code to add a new named export for your story:

编辑故事

¥Edit a story

使用 控件插件，更新故事的控件值。然后，你可以保存对故事的更改，故事文件的代码将为你更新。

¥Using the Controls addon, update a control's value for a story. You can then save the changes to the story and the story file's code will be updated for you.

当然，你也可以随时直接更新故事的代码：

¥Of course, you can always update the story's code directly too:

故事还有助于检查 UI 在你进行更改时是否继续看起来正确。Button 组件有四个故事，展示了它在不同的用例中的表现。现在查看这些故事以确认你对 Primary 的更改没有在其他故事中引入无意的错误。

¥Stories are also helpful for checking that UI continues to look correct as you make changes. The Button component has four stories that show it in different use cases. View those stories now to confirm that your change to Primary didn’t introduce unintentional bugs in the other stories.

在开发过程中检查组件的故事有助于防止意外回归。与 Storybook 集成的工具可以自动执行此操作 为你服务。

¥Checking component’s stories as you develop helps prevent accidental regressions. Tools that integrate with Storybook can automate this for you.

现在我们已经了解了故事的基本结构，让我们看看如何使用 Storybook 的 UI 来开发故事。

¥Now that we’ve seen the basic anatomy of a story let’s see how we use Storybook’s UI to develop stories.