加入直播会话:周四,美国东部时间上午 11 点,Storybook 9 发布会及 AMA
文档
Storybook Docs

配置 Storybook

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

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

配置您的 Storybook 项目

Storybook 的主配置(即 main.js|ts)定义了您的 Storybook 项目的行为,包括故事文件的位置、您使用的插件、功能标志和其他项目特定设置。此文件应位于项目根目录的 .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'],
  docs: {
    autodocs: 'tag',
  },
  staticDirs: ['../public'],
};
 
export default config;

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

配置元素描述
stories一个 glob(模式匹配字符串)数组,指示您的故事文件的位置,相对于 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: { autodocs: 'tag' }
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 构建器时自定义 Storybook 的 Vite 设置
viteFinal: async (config: Vite.InlineConfig, options: Options) => { return config; }
env定义自定义 Storybook 环境变量
env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }),
build通过从捆绑包中排除特定功能,优化 Storybook 的生产构建以提高性能。当缩短构建时间是首要任务时非常有用。
build: { test: {} }

配置故事加载

默认情况下,Storybook 会根据 .storybook/main.js|ts 中的 glob(模式匹配字符串)从您的项目中加载故事,该 glob 匹配项目中所有扩展名为 .stories.* 的文件。目的是让故事文件与其文档化的组件位于同一位置。

•
└── 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 配置,使其根据配置对象加载故事。例如,如果您想从 packages/components 目录加载故事,可以将 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 扩展名的文件,并为您的故事生成标题。

使用目录

您还可以简化 Storybook 配置,并使用目录加载故事。例如,如果您想加载 packages/MyStories 内的所有故事,可以如下调整配置

.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 配置,实现自定义逻辑来加载故事。例如,假设您正在处理一个项目,其中包含现有故事加载方式无法解决的特定模式。在这种情况下,您可以如下调整配置

.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 当前索引故事的方式,按需加载故事目前存在一些小限制

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

配置故事渲染

要控制故事的渲染方式并添加全局装饰器参数,请创建 .storybook/preview.js 文件。此文件在 Canvas UI 中加载,Canvas UI 是一个“预览”iframe,用于隔离渲染您的组件。对于适用于所有故事的全局代码(如CSS 导入或 JavaScript 模拟),请使用 preview.js

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

如果您想更改故事的排序方式,请阅读关于故事排序的内容。

配置 Storybook 的 UI

要控制 Storybook UI(“管理器”)的行为,可以创建 .storybook/manager.js 文件。

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