编写预设插件
Storybook 预设是预先配置的设置或配置,使开发者能够使用一组特定的特性、功能或集成快速设置和自定义他们的环境。
¥Storybook presets are pre-configured settings or configurations that enable developers quickly set up and customize their environment with a specific set of features, functionalities, or integrations.
测试构建速度提高 2-4 倍 =
¥How presets work
预设插件允许开发者通过 API 编写各种配置选项和插件,以与 Storybook 集成并自定义其行为和功能。通常,预设分为两个文件,每个文件都有其特定的角色。
¥Preset addons allow developers to compose various configuration options and plugins via APIs to integrate with Storybook and customize its behavior and functionality. Typically, presets are separated into two files, each with its specific role.
本地预设
¥Local presets
这种类型的预设允许你封装和组织特定于插件的配置,包括 builder 支持、Babel 或第三方集成。例如:
¥This type of preset allows you to encapsulate and organize configurations specific to the addon, including builder support, Babel, or third-party integrations. For example:
import { webpackFinal as webpack } from './webpack/webpackFinal';
import { viteFinal as vite } from './vite/viteFinal';
import { babelDefault as babel } from './babel/babelDefault';
export const webpackFinal = webpack as any;
export const viteFinal = vite as any;
export const babelDefault = babel as any;
根级预设
¥Root-level presets
这种类型的预设面向用户,负责通过 previewAnnotations
打包 Storybook 相关功能(例如 参数)并通过 managerEntries
API 打包 UI 相关功能(例如插件),无需用户进行任何额外配置即可注册插件。例如:
¥This type of preset is user-facing and responsible for registering the addon without any additional configuration from the user by bundling Storybook-related features (e.g., parameters) via the previewAnnotations
and UI related features (e.g., addons) via the managerEntries
API. For example:
export const previewAnnotations = [require.resolve('./dist/preview')];
export const managerEntries = [require.resolve('./dist/manager')];
export * from './dist/preset';
预设 API
¥Presets API
编写预设时,你可以访问一组选定的 API 来与 Storybook 环境交互,包括受支持的构建器(例如 Webpack、Vite)、Storybook 配置和 UI。以下是编写预设插件时可以使用的可用 API。
¥When writing a preset, you can access a select set of APIs to interact with the Storybook environment, including the supported builders (e.g., Webpack, Vite), the Storybook configuration, and UI. Below are the available APIs you can use when writing a preset addon.
Babel
要自定义 Storybook 的 Babel 配置并添加对其他功能的支持,你可以使用 babelDefault
API。它将在任何其他用户预设之前应用提供的配置,终端用户可以通过 babel
配置选项进一步自定义这些预设。例如:
¥To customize Storybook's Babel configuration and add support for additional features, you can use the babelDefault
API. It will apply the provided configuration ahead of any other user presets, which can be further customized by the end user via the babel
configuration option. For example:
import { TransformOptions } from '@babel/core';
export function babelDefault(config: TransformOptions) {
return {
...config,
plugins: [
...config.plugins,
[require.resolve('@babel/plugin-transform-react-jsx'), {}, 'preset'],
],
};
}
构建器
¥Builders
默认情况下,Storybook 为领先的行业构建器提供支持,包括 Webpack 和 Vite。如果你需要任何这些构建器的其他功能,则可以使用 API 根据你的特定需求扩展构建器配置。
¥By default, Storybook provides support for the leading industry builders, including Webpack and Vite. If you need additional features for any of these builders, you can use APIs to extend the builder configuration based on your specific needs.
Vite
如果你正在创建预设并希望包含 Vite 支持,则可以使用 viteFinal
API 来修改默认配置并启用其他功能。例如:
¥If you are creating a preset and want to include Vite support, the viteFinal
API can be used to modify the default configuration and enable additional features. For example:
export function ViteFinal(config: any, options: any = {}) {
config.plugins.push(
new MyCustomPlugin({
someOption: true,
}),
);
return config;
}
Webpack
要自定义 Storybook 中的 Webpack 配置以添加对其他文件类型的支持、应用特定的加载器、配置插件或进行任何其他必要的修改,你可以使用 webpackFinal
API。一旦调用,它将使用提供的配置扩展默认的 Webpack 配置。例如:
¥To customize the Webpack configuration in Storybook to add support for additional file types, apply specific loaders, configure plugins, or make any other necessary modifications, you can use the webpackFinal
API. Once invoked, it will extend the default Webpack configuration with the provided configuration. An example of this would be:
import type { Configuration as WebpackConfig } from 'webpack';
export function webpackFinal(config: WebpackConfig, options: any = {}) {
const rules = [
...(config.module?.rules || []),
{
test: /\.custom-file$/,
loader: require.resolve(`custom-loader`),
},
];
config.module.rules = rules;
return config;
}
ManagerEntries
如果你正在编写加载第三方插件的预设,你可能无法控制这些插件,但需要访问特定功能或其他配置,则可以使用 managerEntries
API。例如:
¥If you're writing a preset that loads third-party addons, which you may not have control over, but require access to specific features or additional configuration, you can use the managerEntries
API. For example:
//example-addon/preset.js
export const managerEntries = (entry = []) => {
return [...entry, require.resolve('path-to-third-party-addon')];
};
PreviewAnnotations
如果你需要其他设置来为预设(如 decorators 或 参数)渲染故事,则可以使用 previewAnnotations
API。例如,要将装饰器应用于所有故事,请创建包含装饰器的预览文件并将其提供给预设,如下所示:
¥If you need additional settings to render stories for a preset, like decorators or parameters, you can use the previewAnnotations
API. For example, to apply a decorator to all stories, create a preview file that includes the decorator and make it available to the preset as follows:
import type { Renderer, ProjectAnnotations } from '@storybook/types';
import { PARAM_KEY } from './constants';
import { CustomDecorator } from './decorators';
const preview: ProjectAnnotations<Renderer> = {
decorators: [CustomDecorator],
globals: {
[PARAM_KEY]: false,
},
};
export default preview;
高级配置
¥Advanced configuration
预设 API 旨在灵活,允许你根据特定需求自定义 Storybook,包括使用预设进行更高级的用例而无需发布它们。在这种情况下,你可以依赖私有预设。这些私有预设包含用于开发目的而不是终端用户的配置选项。.storybook/main.js|ts
文件是此类私有预设的示例,它使你能够修改 Storybook 的行为和功能。
¥The presets API is designed to be flexible and allow you to customize Storybook to your specific needs, including using presets for more advanced use cases without publishing them. In such cases, you can rely on a private preset. These private presets contain configuration options meant for development purposes and not for end-users. The .storybook/main.js|ts
file is an example of such a private preset that empowers you to modify the behavior and functionality of Storybook.
// 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 = {
viteFinal: async (config, options) => {
// Update config here
return config;
},
webpackFinal: async (config, options) => {
// Change webpack config
return config;
},
babel: async (config, options) => {
return config;
},
};
export default config;
插件
¥Addons
对于插件消费者,managerEntries
API 可能过于技术化,难以使用。为了更轻松地将插件添加到 Storybook,预设 API 提供了 addons
API,它接受插件名称数组并会自动为你加载它们。例如:
¥For addon consumers, the managerEntries
API can be too technical, making it difficult to use. To make it easier to add addons to Storybook, the preset API provides the addons
API, which accepts an array of addon names and will automatically load them for you. For example:
// 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 = {
addons: [
// Other Storybook addons
'@storybook/addon-a11y',
],
};
export default config;
值数组支持对应包含在管理器中的其他预设和插件的引用。Storybook 将自动检测提供的值是预设还是插件,并相应地加载它。
¥The array of values supports references to additional presets and addons that should be included in the manager. Storybook will automatically detect whether the provided value is a preset or an addon and load it accordingly.
条目
¥Entries
条目是注册预览入口点的地方。此功能可用于创建一个 configure-storybook 预设,该预设会自动将所有 *.stories.js
文件加载到 Storybook 中,无需用户重复复制粘贴相同的配置。
¥Entries are the place to register entry points for the preview. This feature can be utilized to create a configure-storybook preset that automatically loads all *.stories.js
files into Storybook, eliminating the need for users to copy-paste the same configuration repeatedly.
UI 配置
¥UI configuration
Storybook 预设 API 还提供对 UI 配置的访问,包括由 previewHead
和 previewBody
API 配置的预览的 head
和 body
HTML 元素。两者都允许你以类似于使用 preview-head.html
和 preview-body.html
文件的方式设置 Storybook。这些方法接受字符串并返回修改后的版本,将提供的内容注入 HTML 元素。
¥The Storybook preset API also provides access to the UI configuration, including the head
and body
HTML elements of the preview, configured by the previewHead
and previewBody
APIs. Both allow you to set up Storybook in a way that is similar to using the preview-head.html
and preview-body.html
files. These methods accept a string and return a modified version, injecting the provided content into the HTML element.
// 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 = {
previewBody: (body) => `
${body}
${
process.env.ANALYTICS_ID ? '<script src="https://cdn.example.com/analytics.js"></script>' : ''
}
`,
};
export default config;
此外,如果你需要自定义管理器(即 Storybook 的搜索、导航、工具栏和插件渲染的位置),你可以使用 managerHead
来修改 UI,类似于使用 manager-head.html
文件的操作。例如:
¥Additionally, if you need to customize the manager (i.e., where Storybook’s search, navigation, toolbars, and addons render), you can use the managerHead
to modify the UI, similar to how you would do it with the manager-head.html
file. For example:
// 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 = {
managerHead: (head) => `
${head}
<link rel="icon" type="image/png" href="/logo192.png" sizes="192x192" />
`,
};
export default config;
但是,如果需要,你还可以自定义 Storybook 用于渲染 UI 的模板。为此,你可以使用 previewMainTemplate
API 并为作为 ejs
文件创建的自定义模板提供参考。有关如何执行此操作的示例,请参阅 Webpack 5 构建器使用的 template。
¥However, if you need, you can also customize the template used by Storybook to render the UI. To do so, you can use the previewMainTemplate
API and provide a reference for a custom template created as a ejs
file. For an example of how to do this, see the template used by the Webpack 5 builder.
故障排除
¥Troubleshooting
Storybook 不会加载我的预设中的文件
¥Storybook doesn't load files in my preset
由于 Storybook 依赖 esbuild 而不是 Webpack 来构建 UI,因此依赖于 managerWebpack
API 来配置管理器或加载除 CSS 或图片之外的其他文件的预设将不再起作用。我们建议将其从你的预设中删除,并调整你的配置以将任何其他文件转换为 JavaScript。
¥As Storybook relies on esbuild instead of Webpack to build the UI, presets that depend on the managerWebpack
API to configure the manager or load additional files other than CSS or images will no longer work. We recommend removing it from your preset and adjusting your configuration to convert any additional files to JavaScript.
了解有关 Storybook 插件生态系统的更多信息
¥Learn more about the Storybook addon ecosystem
-
插件类型 提供有关其他类型的插件
¥Types of addons for other types of addons
-
编写插件 提供有关插件开发基础知识
¥Writing addons for the basics of addon development
-
用于预设开发的预设
¥Presets for preset development
-
集成目录 提供有关要求和可用秘诀
¥Integration catalog for requirements and available recipes
-
API 参考 用于了解可用的 API
¥API reference to learn about the available APIs