配置 Storybook

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

请注意，您可以通过为 storybook dev 和 storybook build CLI 命令设置 -c 标志来更改 Storybook 使用的文件夹。

配置您的 Storybook 项目

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

.storybook/main.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
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-docs'],
  staticDirs: ['../public'],
};
 
export default config;

此配置文件是一个预设，因此具有强大的接口，可以进一步自定义。请阅读我们关于编写预设的文档以了解更多信息。

配置项	描述
`stories`	一个 globs 数组，用于指示 stories 文件的位置，相对于 `main.js`
`staticDirs`	设置一个要由 Storybook 加载的静态文件目录列表 `staticDirs: ['../public']`
`addons`	设置要由 Storybook 加载的插件列表 `addons: ['@storybook/addon-docs']`
`typescript`	配置 Storybook 如何处理 TypeScript 文件 `typescript: { check: false, checkOptions: {} }`
`framework`	根据一组特定于框架的设置配置 Storybook `framework: { name: '@storybook/svelte-vite', options:{} }`
`core`	配置 Storybook 的内部功能 `core: { disableTelemetry: true, }`
`docs`	配置 Storybook 的自动生成文档 `docs: { defaultName: 'Documentation' }`
`features`	启用 Storybook 的附加功能有关可用功能的列表，请参阅下表
`refs`	配置 Storybook 组合 `refs: { example: { title: 'ExampleStorybook', url:'https://your-url.com' } }`
`logLevel`	配置 Storybook 在浏览器终端中的日志。可用于调试 `logLevel: 'debug'`
`webpackFinal`	自定义 Storybook 的 Webpack 设置 `webpackFinal: async (config:any) => { return config; }`
`viteFinal`	在使用 vite builder 时自定义 Storybook 的 Vite 设置 `viteFinal: async (config: Vite.InlineConfig, options: Options) => { return config; }`
`env`	定义自定义 Storybook 环境变量。 `env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }),`
`build`	通过排除包中的特定功能来优化 Storybook 的生产构建以提高性能。当构建时间缩短是首要任务时非常有用。 `build: { test: {} }`

配置 Story 加载

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

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

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

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

.storybook/main.ts

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

使用配置对象

此外，您还可以自定义 Storybook 的配置，以加载基于配置对象的 stories。例如，如果您想从 packages/components 目录加载 stories，您可以将 stories 配置字段调整为以下内容：

.storybook/main.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
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 扩展名的文件，并生成 stories 的标题。

使用目录

您还可以简化您的 Storybook 配置并使用目录加载 stories。例如，如果您想加载 packages/MyStories 中的所有 stories，您可以进行如下调整配置：

.storybook/main.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
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;

使用自定义实现

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

.storybook/main.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { StorybookConfig } from '@storybook/your-framework';
import type { StoriesEntry } from 'storybook/internal/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;

已知限制

由于 Storybook 目前索引 stories 的方式，按需加载 stories 有一些小的限制。

支持从版本 1 到版本 3 的 CSF 格式。
允许使用受限制 API 的自定义 storySort 函数。

配置 Story 渲染

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

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

decorators - 一个全局装饰器数组
parameters - 一个全局参数对象
globalTypes - globalTypes 的定义

如果您想更改 stories 的排序方式，请阅读关于对 stories 进行排序的内容。

配置 Storybook 的 UI

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

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