> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 使用 Storybook

[Storybook](https://storybook.js.org/) 是一个为 React、Vue 等框架独立开发 UI 组件的强大的工具，它能够独立构建和测试组件，从而提升开发和测试效率。

[storybook-rsbuild](https://github.com/rstackjs/storybook-rsbuild) 是 Rsbuild 支持的 Storybook 构建器，并集成了 React、Vue 3 框架和原生 JavaScript。统一使用 Rsbuild 构建系统可以使 Storybook 与 Rslib 使用统一的构建配置。

:::info Storybook Rsbuild 版本对应表

下表展示了 Storybook Rsbuild 与 Storybook 版本的对应关系。如果你正在使用 Storybook v9 或更早版本，请参考 [官方迁移指南](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-9x-to-1000) 迁移到最新版。

| Storybook                              | Storybook Rsbuild                                                                  |
| -------------------------------------- | ---------------------------------------------------------------------------------- |
| [v10](https://storybook.js.org/docs/)  | [^3.0.0](https://storybook.rsbuild.rs)                                             |
| [v9](https://storybook.js.org/docs/9/) | [^2.0.0](https://storybook-v2.rsbuild.rs)                                          |
| [v8](https://storybook.js.org/docs/8/) | [^1.0.0](https://github.com/rstackjs/storybook-rsbuild/tree/v1/website/docs/guide) |

:::

## 快速开始

### 创建一个 Rslib 项目

这是设置 Storybook 的前提条件。你需要有一个包含组件的 Rslib 项目，并希望在 Storybook 中展示这些组件，请查看 [解决方案](/zh/guide/solution/index.md) 以设置 Rslib 项目。

:::tip
你可以直接通过 [create-rslib](/zh/guide/start/quick-start.md#创建-rslib-项目) 创建一个已集成 Storybook 的新项目，无需手动配置。
:::

### 将 Storybook 添加到项目中

使用现有的 Rslib 项目设置 Storybook。为了使用 React、Vue 3、原生 JavaScript 或其他框架，必须首先安装适当的 Storybook 框架包。有关安装说明，可以查阅 [Storybook Rsbuild 文档](https://storybook.rsbuild.rs/guide/framework.html)。

以 React 为例，在这一步你需要：

1. 安装 Storybook Rsbuild React 框架的依赖。必要的依赖包括

   - [storybook](https://www.npmjs.com/package/storybook)：Storybook core 包。
   - [@storybook/react](https://www.npmjs.com/package/@storybook/react)：React 渲染器。
   - [@storybook/addon-docs](https://www.npmjs.com/package/@storybook/addon-docs)：用于生成文档。
   - [@storybook/addon-onboarding](https://www.npmjs.com/package/@storybook/addon-onboarding)：Storybook 的交互式上手体验。
   - [@rsbuild/core](https://www.npmjs.com/package/@rsbuild/core)：Storybook 构建器。
   - [storybook-addon-rslib](https://www.npmjs.com/package/storybook-addon-rslib)：此插件将使 Storybook Rsbuild 能够从 Rslib 配置文件中继承 Rsbuild 配置。
     该插件将自动读取 Rslib 配置并将其应用于 Storybook Rsbuild，确保配置统一。你可以查看 [storybook-addon-rslib](https://storybook.rsbuild.rs/guide/integrations/rslib.html) 文档以了解可用选项。

   <PackageManagerTabs
     command={{
     npm: 'npm add storybook @storybook/react @storybook/addon-docs @storybook/addon-onboarding storybook-addon-rslib @rsbuild/core -D',
     yarn: 'yarn add storybook @storybook/react @storybook/addon-docs @storybook/addon-onboarding storybook-addon-rslib @rsbuild/core -D',
     pnpm: 'pnpm add storybook @storybook/react @storybook/addon-docs @storybook/addon-onboarding storybook-addon-rslib @rsbuild/core -D',
     bun: 'bun add storybook @storybook/react @storybook/addon-docs @storybook/addon-onboarding storybook-addon-rslib @rsbuild/core -D',
   }}
   />

   每个框架的依赖各不相同，可查阅 [Storybook Rsbuild 文档](https://storybook.rsbuild.rs/guide/framework.html) 了解详细信息。在这个 React 示例中，我们将安装 [storybook-react-rsbuild](https://www.npmjs.com/package/storybook-react-rsbuild) 作为框架集成。

   <Tabs>
     <Tab label="React">
       <PackageManagerTabs command="add storybook-react-rsbuild -D" />
     </Tab>

     <Tab label="Vue">
       <PackageManagerTabs command="add storybook-vue3-rsbuild -D" />
     </Tab>
   </Tabs>

2. 配置 Storybook 配置文件 `.storybook/main.js`，指定 stories 和 addons，并使用相应的框架集成设置框架。

   ```js title=".storybook/main.js"
   export default {
     stories: [
       '../stories/**/*.mdx',
       '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)',
     ],
     addons: [
       '@storybook/addon-docs',
       '@storybook/addon-onboarding',
       'storybook-addon-rslib',
     ],
     framework: 'storybook-react-rsbuild', // 例如 storybook-react-rsbuild
   };
   ```

3. 向 `stories` 目录添加一个简单的 story。例如，创建一个 `Button.stories.js` 文件，内容如下：

   ```js title="stories/Button.stories.js"
   import { Button } from '../src/Button';

   const meta = {
     title: 'Example/Button',
     component: Button,
   };

   export default meta;

   export const Primary = {
     args: {
       primary: true,
       label: 'Button',
     },
   };
   ```

:::tip
如果你使用的是 [Yarn Plug-n-Play](https://yarnpkg.com/features/pnp) 或者你的项目是在 monorepo 环境中设置的，你可能会遇到模块解析问题。在这种情况下，你可以添加一个 `getAbsolutePath('storybook-addon-rslib')` 函数来解析插件。有关更多信息，请查看 [Storybook 的 FAQ](https://storybook.js.org/docs/faq#how-do-i-fix-module-resolution-in-special-environments)。
:::

大功告成，你可以使用以下命令启动和构建 Storybook 服务器：

```bash
npx storybook dev   // 开发模式
npx storybook build // 构建静态文件
```

查看 [Storybook Rsbuild 文档](https://storybook.rsbuild.rs/) 和 [Storybook 文档](https://storybook.js.org/docs/react/get-started/introduction) 以了解更多信息。

## 示例

- [React 组件库 + Rslib + Storybook](https://github.com/rstackjs/rstack-examples/tree/main/rslib/react-storybook)
- [Vue 组件库 + Rslib + Storybook](https://github.com/rstackjs/rstack-examples/tree/main/rslib/vue-storybook)