配置 Storybook
Storybook 通过名为 .storybook
的文件夹进行配置,该文件夹包含各种配置文件。
请注意,您可以通过将 -c
标志设置为 storybook dev
和 storybook build
CLI 命令来更改 Storybook 使用的文件夹。
配置您的 Storybook 项目
Storybook 的主要配置 (即 main.js|ts
) 定义了您的 Storybook 项目的行为,包括您的 story 文件的位置、您使用的插件、功能标志和其他项目特定的设置。此文件应位于项目根目录的 .storybook
文件夹中。您可以使用 JavaScript 或 TypeScript 编写此文件。下面列出了可用选项以及如何使用它们的示例。
// 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;
配置元素 | 描述 |
---|---|
stories | 指示 story 文件位置的 glob 数组,相对于 main.js |
staticDirs | 设置要由 Storybook 加载的静态文件目录列表staticDirs: ['../public'] |
addons | 设置 Storybook 加载的插件列表addons: ['@storybook/addon-essentials'] |
typescript | 配置 Storybook 如何处理 TypeScript 文件typescript: { check: false, checkOptions: {} } |
framework | 根据一组特定于框架的设置配置 Storybookframework: { 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 | 通过从 bundle 中排除特定功能,优化 Storybook 的生产构建以提高性能。在缩短构建时间是首要任务时很有用。build: { test: {} } |
配置 story 加载
默认情况下,Storybook 将根据 .storybook/main.js|ts
中的 glob(模式匹配字符串)从您的项目中加载 story,该 glob 匹配项目中扩展名为 .stories.*
的所有文件。目的是让您将 story 文件与它所文档化的组件放在一起。
•
└── components
├── Button.js
└── Button.stories.js
如果您想使用不同的命名约定,可以使用 picomatch 支持的语法来更改 glob。
例如,如果您想从 my-project/src/components
目录中提取 .md
和 .js
文件,您可以编写
// 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;
使用配置对象
此外,您可以自定义 Storybook 配置以基于配置对象加载您的 story。例如,如果您想从 packages/components
目录加载您的 story,您可以将您的 stories
配置字段调整为以下内容
// 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
扩展名的文件,并为您的 story 生成标题。
使用目录
您还可以简化 Storybook 配置并使用目录加载 story。例如,如果您想加载 packages/MyStories
内的所有 story,您可以按如下方式调整配置
// 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;
使用自定义实现
您还可以调整 Storybook 配置并实现自定义逻辑来加载您的 story。例如,假设您正在处理的项目包含一种特殊的模式,传统的加载 story 的方式无法解决。在这种情况下,您可以按如下方式调整您的配置
// 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;
已知限制
由于当前 Storybook 中 story 的索引方式,按需加载 story 目前有一些小的限制
- 支持版本 1 到版本 3 的CSF 格式。
- 允许基于受限 API 的自定义
storySort
函数。
配置 story 渲染
要控制 story 的渲染方式并添加全局装饰器和参数,请创建一个 .storybook/preview.js
文件。这会在 Canvas UI 中加载,即在隔离状态下渲染组件的“预览”iframe。将 preview.js
用于全局代码(例如CSS 导入或适用于所有 story 的 JavaScript 模拟)。
preview.js
文件可以是 ES 模块,并导出以下键
decorators
- 全局装饰器数组parameters
- 全局参数对象globalTypes
- globalTypes 的定义
如果您想更改 story 的排序方式,请阅读关于排序 story。
配置 Storybook 的 UI
要控制 Storybook 的 UI(“管理器”)的行为,您可以创建一个 .storybook/manager.js
文件。