设置 Storybook

既然您已经了解了 Stories 是什么以及如何浏览它们，接下来让我们演示如何处理您的一个组件。

从您的项目中挑选一个简单的组件，比如一个 Button，然后为其编写一个配套的 .stories.js、.stories.ts 或 .stories.svelte 文件。它可能看起来像这样：

YourComponent.stories.ts|tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { YourComponent } from './YourComponent';
 
//👇 This default export determines where your story goes in the story list
const meta = {
  component: YourComponent,
} satisfies Meta<typeof YourComponent>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const FirstStory: Story = {
  args: {
    //👇 The args you need here will depend on your component
  },
};

前往您的 Storybook 查看渲染的组件。如果现在看起来有点奇怪，这是正常的。

根据您的技术栈，您可能还需要进一步配置 Storybook 环境。

渲染组件样式

Storybook 对您如何生成或加载 CSS 没有强制要求。它会渲染您提供的任何 DOM 元素。但有时，开箱即用时东西看起来可能不太“对劲”。

您可能需要为 Storybook 的渲染环境配置您的 CSS 工具。以下是社区中流行工具的一些设置指南：

没找到您正在寻找的工具？请查看样式和 CSS 页面了解更多详情。

为您的技术栈配置 Storybook

Storybook 附带一个宽松的默认配置。它会尝试根据您的设置进行自定义。但这并非万无一失。

您的项目可能在组件独立渲染之前有额外的要求。这需要进一步定制配置。您可能需要以下三类配置：

构建配置，如 Webpack 和 Babel

如果您在运行 yarn storybook 命令时在 CLI 上看到错误，您可能需要修改 Storybook 的构建配置。以下是一些可以尝试的方法：

Presets（预设）将各种技术的常见配置打包到 Storybook 中。特别是，存在用于 Create React App 和 Ant Design 的预设。
为 Storybook 指定自定义的Babel 配置。如果可能，Storybook 会自动尝试使用您的项目配置。
调整 Storybook 使用的Webpack 配置。如有需要，尝试打补丁加入您自己的配置。

运行时配置

如果 Storybook 构建成功，但在浏览器中连接时立即看到错误，在这种情况下，很可能是您的输入文件未能正确编译/转译以供浏览器解释。Storybook 支持常青浏览器（evergreen browsers），但您可能需要检查 Babel 和 Webpack 设置（参见上文），以确保您的组件代码正常工作。

组件上下文

如果某个特定的 Story 渲染有问题，通常意味着您的组件期望可获得一个特定的环境。

一个常见的前端模式是组件假定它们在渲染层级中更高层的父组件提供的特定“上下文”中渲染（例如，主题提供者）。

使用装饰器（decorators）将每个 Story“包裹”在必要的上下文提供者中。.storybook/preview.js|ts 文件允许您自定义组件在 Canvas 预览 iframe 中的渲染方式。在下面的示例中查看如何使用Styled Components 的 ThemeProvider、Vue 的 Fontawesome 或 Angular 主题提供者组件来包裹 Storybook 中渲染的每个组件。

.storybook/preview.tsx

import React from 'react';
 
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Preview } from '@storybook/your-framework';
 
import { ThemeProvider } from 'styled-components';
 
const preview: Preview = {
  decorators: [
    (Story) => (
      <ThemeProvider theme="default">
        {/* 👇 Decorators in Storybook also accept a function. Replace <Story/> with Story() to enable it  */}
        <Story />
      </ThemeProvider>
    ),
  ],
};
 
export default preview;

加载资源和资产

我们建议使用 Storybook 静态服务您的组件中请求的外部资源和资产。这能确保您的 Stories 始终可以访问这些资产。阅读我们的文档，了解如何使用 Storybook 托管静态文件。