配置 Storybook

Storybook 通过名为 .storybook 的文件夹进行配置，其中包含各种配置文件。

¥Storybook is configured via a folder called .storybook, which contains various configuration files.

配置你的 Storybook 项目

¥Configure your Storybook project

Storybook 的主要配置（即 main.js|ts）定义了你的 Storybook 项目的行为，包括故事的位置、你使用的插件、功能标志和其他特定于项目的设置。此文件应位于项目根目录中的 .storybook 文件夹中。你可以使用 JavaScript 或 TypeScript 编写此文件。下面列出了可用的选项及其使用方法示例。

¥Storybook's main configuration (i.e., the main.js|ts) defines your Storybook project's behavior, including the location of your stories, the addons you use, feature flags and other project-specific settings. This file should be in the .storybook folder in your project's root directory. You can author this file in either JavaScript or TypeScript. Listed below are the available options and examples of how to use them.

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  // Required
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // Optional
  addons: ['@storybook/addon-essentials'],
  docs: {
    autodocs: 'tag',
  },
  staticDirs: ['../public'],
};
 
export default config;

配置故事加载

¥Configure story loading

默认情况下，Storybook 将根据 .storybook/main.js|ts 中的 glob（模式匹配字符串）从你的项目中加载故事，该 glob 与你的项目中扩展名为 .stories.* 的所有文件相匹配。目的是让你将故事文件与其记录的组件放在一起。

¥By default, Storybook will load stories from your project based on a glob (pattern matching string) in .storybook/main.js|ts that matches all files in your project with extension .stories.*. The intention is for you to colocate a story file along with the component it documents.

•
└── components
    ├── Button.js
    └── Button.stories.js

如果你想使用不同的命名约定，你可以使用 picomatch 支持的语法更改 glob。

¥If you want to use a different naming convention, you can alter the glob using the syntax supported by picomatch.

例如，如果你想从 my-project/src/components 目录中提取 .md 和 .js 文件，你可以这样写：

¥For example, if you wanted to pull both .md and .js files from the my-project/src/components directory, you could write:

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../my-project/src/components/*.@(js|md)'],
};
 
export default config;

使用配置对象

¥With a configuration object

此外，你可以自定义 Storybook 配置以根据配置对象加载故事。例如，如果你想从 packages/components 目录加载故事，你可以将 stories 配置字段调整为以下内容：

¥Additionally, you can customize your Storybook configuration to load your stories based on a configuration object. For example, if you wanted to load your stories from a packages/components directory, you could adjust your stories configuration field into the following:

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: [
    {
      // 👇 Sets the directory containing your stories
      directory: '../packages/components',
      // 👇 Storybook will load all files that match this glob
      files: '*.stories.*',
      // 👇 Used when generating automatic titles for your stories
      titlePrefix: 'MyComponents',
    },
  ],
};
 
export default config;

Storybook 启动时，会在 packages/components 目录中查找任何包含 stories 扩展名的文件，并生成故事的标题。

¥When Storybook starts, it will look for any file containing the stories extension inside the packages/components directory and generate the titles for your stories.

使用目录

¥With a directory

你还可以简化 Storybook 配置并使用目录加载故事。例如，如果你想加载 packages/MyStories 中的所有故事，你可以按如下方式调整配置：

¥You can also simplify your Storybook configuration and load the stories using a directory. For example, if you want to load all the stories inside a packages/MyStories, you can adjust the configuration as such:

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  // 👇 Storybook will load all existing stories within the MyStories folder
  stories: ['../packages/MyStories'],
};
 
export default config;

使用自定义实现

¥With a custom implementation

你还可以调整你的 Storybook 配置并实现自定义逻辑来加载你的故事。例如，假设你正在处理一个项目，该项目包含一个特定的模式，而传统的加载故事的方式无法解决该模式。在这种情况下，你可以按如下方式调整配置：

¥You can also adjust your Storybook configuration and implement custom logic to load your stories. For example, suppose you were working on a project that includes a particular pattern that the conventional ways of loading stories could not solve. In that case, you could adjust your configuration as follows:

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
import type { StoriesEntry } from '@storybook/types';
 
async function findStories(): Promise<StoriesEntry[]> {
  // your custom logic returns a list of files
}
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: async (list: StoriesEntry[]) => [
    ...list,
    // 👇 Add your found stories to the existing list of story files
    ...(await findStories()),
  ],
};
 
export default config;

已知限制

¥Known limitations

由于 Storybook 中故事的索引方式，按需加载故事目前有几个小限制：

¥Because of the way stories are currently indexed in Storybook, loading stories on demand has a couple of minor limitations at the moment:

• 支持从版本 1 到版本 3 的 CSF 格式。

  ¥CSF formats from version 1 to version 3 are supported.

• 基于受限 API 允许自定义 storySort 函数。

  ¥Custom storySort functions are allowed based on a restricted API.

配置故事渲染

¥Configure story rendering

要控制故事的渲染方式并添加全局 decorators 和 参数，请创建一个 .storybook/preview.js 文件。这加载在 Canvas UI 中，即单独渲染组件的“预览”iframe。将 preview.js 用于适用于所有故事的全局代码（例如 CSS 导入 或 JavaScript 模拟）。

¥To control the way stories are rendered and add global decorators and parameters, create a .storybook/preview.js file. This is loaded in the Canvas UI, the “preview” iframe that renders your components in isolation. Use preview.js for global code (such as CSS imports or JavaScript mocks) that applies to all stories.

preview.js 文件可以是 ES 模块并导出以下键：

¥The preview.js file can be an ES module and export the following keys:

• decorators - 全局 decorators 数组

  ¥decorators - an array of global decorators

• parameters - 全局 参数 对象

  ¥parameters - an object of global parameters

• globalTypes - globalTypes 的定义

  ¥globalTypes - definition of globalTypes

如果你想要更改故事的排序方式，请阅读有关 故事排序 的信息。

¥If you’re looking to change how to order your stories, read about sorting stories.

配置 Storybook 的 UI

¥Configure Storybook’s UI

要控制 Storybook 的 UI（“管理器”）的行为，你可以创建一个 .storybook/manager.js 文件。

¥To control the behavior of Storybook’s UI (the “manager”), you can create a .storybook/manager.js file.

此文件没有特定的 API，但它是设置 UI 选项 和配置 Storybook 的 theme 的地方。

¥This file does not have a specific API but is the place to set UI options and to configure Storybook’s theme.