编写预设插件

Storybook 预设是预先配置的设置或配置，使开发人员能够快速设置和自定义其环境，并使用一组特定的功能、功能或集成。

预设的工作原理

预设插件允许开发人员通过 API 组合各种配置选项和插件，以集成到 Storybook 并自定义其行为和功能。通常，预设分为两个文件，每个文件都有其特定的作用。

本地预设

这种类型的预设允许您封装和组织特定于插件的配置，包括构建器支持、Babel或第三方集成。例如

example-addon/src/preset.ts

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;

根级预设

这种类型的预设面向用户，负责在无需用户任何额外配置的情况下注册插件，方法是通过previewAnnotations捆绑 Storybook 相关功能（例如，参数）以及通过managerEntries API 捆绑 UI 相关功能（例如，插件）。例如

example-addon/preset.js

export const previewAnnotations = [require.resolve('./dist/preview')];
 
export const managerEntries = [require.resolve('./dist/manager')];
 
export * from './dist/preset';

预设 API

编写预设时，您可以访问一组选定的 API 来与 Storybook 环境进行交互，包括支持的构建器（例如，Webpack、Vite）、Storybook 配置和 UI。以下是编写预设插件时可以使用的一些 API。

Babel

要自定义 Storybook 的 Babel 配置并添加对其他功能的支持，您可以使用babelDefault API。它将在任何其他用户预设之前应用提供的配置，最终用户可以通过babel配置选项进一步自定义它。例如

example-addon/src/babel/babelDefault.ts

import { TransformOptions } from '@babel/core';
 
export function babelDefault(config: TransformOptions) {
  return {
    ...config,
    plugins: [
      ...config.plugins,
      [require.resolve('@babel/plugin-transform-react-jsx'), {}, 'preset'],
    ],
  };
}

Babel 配置仅应用于内部使用 Babel 的框架。如果您为使用不同编译器的框架启用它，例如SWC或esbuild，则它将被忽略。

构建器

默认情况下，Storybook 支持主要的行业构建器，包括Webpack和Vite。如果您需要这些构建器的任何其他功能，您可以使用 API 根据您的特定需求扩展构建器配置。

Vite

如果您正在创建预设并希望包含 Vite 支持，则可以使用 viteFinal API 修改默认配置并启用其他功能。例如

example-addon/src/vite/viteFinal.ts

export function ViteFinal(config: any, options: any = {}) {
  config.plugins.push(
    new MyCustomPlugin({
      someOption: true,
    }),
  );
 
  return config;
}

Webpack

为了自定义 Storybook 中的 Webpack 配置，以添加对其他文件类型的支持，应用特定的加载器，配置插件或进行任何其他必要的修改，您可以使用 webpackFinal API。一旦调用，它将使用提供的配置扩展默认的 Webpack 配置。这方面的一个例子是

example-addon/src/webpack/webpackFinal.ts

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。例如

//example-addon/preset.js
 
export const managerEntries = (entry = []) => {
  return [...entry, require.resolve('path-to-third-party-addon')];
};

PreviewAnnotations

如果您需要其他设置来为预设渲染故事，例如装饰器或参数，则可以使用 previewAnnotations API。例如，要将装饰器应用于所有故事，请创建一个包含装饰器的预览文件，并使其可供预设使用，如下所示

example-addon/src/preview.ts

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;

高级配置

预设 API 旨在灵活且允许您根据自己的特定需求自定义 Storybook，包括将预设用于更高级的用例而无需发布它们。在这种情况下，您可以依赖私有预设。这些私有预设包含用于开发目的而非最终用户的配置选项。.storybook/main.js|ts 文件是此类私有预设的一个示例，它使您能够修改 Storybook 的行为和功能。

.storybook/main.ts

// 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;

插件

对于插件使用者，managerEntries API 可能过于技术性，难以使用。为了更轻松地将插件添加到 Storybook，预设 API 提供了 addons API，它接受一个插件名称数组，并会自动为您加载它们。例如

.storybook/main.ts

// 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 将自动检测提供的值是预设还是插件，并相应地加载它。

入口

入口是注册预览入口点的地方。此功能可用于创建 configure-storybook 预设，该预设会自动将所有 *.stories.js 文件加载到 Storybook 中，从而无需用户反复复制粘贴相同的配置。

Storybook 预设 API 还提供对 UI 配置的访问，包括预览的 head 和 body HTML 元素，由 previewHead 和 previewBody API 配置。两者都允许您以类似于使用 preview-head.html 和 preview-body.html 文件的方式设置 Storybook。这些方法接受一个字符串并返回一个修改后的版本，将提供的內容注入到 HTML 元素中。

.storybook/main.ts

// 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 文件的方式。例如

.storybook/main.ts

// 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 构建器使用的模板。

故障排除

Storybook 无法加载我预设中的文件

由于 Storybook 依赖于 esbuild 而不是 Webpack 来构建 UI，因此依赖于 managerWebpack API 来配置管理器或加载除 CSS 或图像之外的其他文件的预设将不再起作用。我们建议从您的预设中将其删除，并调整您的配置以将任何其他文件转换为 JavaScript。

了解 Storybook 插件生态系统

插件类型以获取其他类型插件的信息
编写插件以了解插件开发的基础知识
预设，用于预设开发
集成目录以获取需求和可用方案
API 参考以了解可用的 API