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

插件知识库

一旦你了解了编写插件的基础知识,还有各种常见的增强功能可以改进你的插件。本页详细介绍了有关插件创建的更多信息。在创建自己的插件时,可以将其用作快速参考指南。

禁用插件面板

可以为特定的 Story 禁用插件面板。

要实现这一点,需要在注册面板时传递 paramKey 元素

/my-addon/manager.js
addons.register(ADDON_ID, () => {
  addons.add(PANEL_ID, {
    type: types.PANEL,
    title: 'My Addon',
    render: () => <div>Addon tab content</div>,
    paramKey: 'myAddon', // this element
  });
});

然后在添加 Story 时,可以传递一个 disabled 参数。

Button.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.org.cn/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Button',
  component: Button,
  parameters: {
    myAddon: { disable: true }, // Disables the addon
  },
} satisfies Meta<typeof Button>;
 
export default meta;

样式化你的插件

Storybook 使用 Emotion 进行样式设计。还附带一个你可以自定义的主题!

我们建议使用 Emotion 为你的插件 UI 组件添加样式。这使你可以使用当前的 Storybook 主题来提供无缝的开发体验。如果你不想使用 Emotion,可以使用内联样式或其他的 css-in-js 库。你可以通过 Emotion 的 withTheme HOC 将主题作为 props 接收。阅读更多关于主题的内容

Storybook 组件

插件作者可以使用任何 React 库开发他们的 UI。但我们建议使用 storybook/internal/components 中的 Storybook UI 组件来更快地构建插件。使用 Storybook 组件,你将获得

  • 经过实战考验的现成组件
  • Storybook 原生的外观和感觉
  • 内置支持 Storybook 主题

在你的下一个插件中使用下面列出的组件。

组件源码Story
Action Bar查看组件实现查看组件 Story
插件面板查看组件实现不适用
Badge查看组件实现查看组件 Story
按钮查看组件实现查看组件 Story
表单查看组件实现查看组件 Story
加载器查看组件实现查看组件 Story
占位符查看组件实现查看组件 Story
滚动区域查看组件实现查看组件 Story
间隔查看组件实现查看组件 Story
语法高亮器查看组件实现查看组件 Story
标签页查看组件实现查看组件 Story
工具栏查看组件实现不适用
工具提示查看组件实现查看组件 Story
缩放查看组件实现查看组件 Story

作为组件的补充,还包含了一套 UI 原子组件。使用下面列出的内容作为样式化你的插件的参考。

组件源码Story
调色板(见下方说明)查看实现查看 Story
图标查看实现查看 Story
排版查看实现查看 Story

@storybook/addon-docs/blocks 实现的调色板是 storybook/theming 模块的高级抽象。

构建系统

当你在开发插件作为一个包时,不能使用 npm link 将其添加到你的项目中。将你的插件列为本地依赖项添加到你的 package.json 中

package.json
{
  "dependencies": {
    "@storybook/addon-controls": "file:///home/username/myrepo"
  }
}

运行 yarnnpm install 来安装插件。

模块热替换

在开发插件时,可以配置 HMR(模块热替换)来反映所做的更改。

独立 Storybook 插件

如果你正在开发一个独立插件,将以下新脚本添加到 package.json

package.json
{
  "scripts": {
    "start": "npm run build -- --watch"
  }
}

本地 Storybook 插件

如果你正在基于现有的 Storybook 安装开发本地 Storybook 插件,则 HMR(模块热替换)是开箱即用的。

在预设中组合插件

如果你正在处理一个加载第三方插件的预设,而你无法控制这些插件,并且你需要访问某些功能(例如 Decorators)或提供额外的配置。在这种情况下,你需要将你的预设更新为以下内容,以便加载和配置其他插件

my-preset/index.js
function managerEntries(entry = []) {
  return [...entry, require.resolve('my-other-addon/register')];
}
 
const config = (entry = [], options) => {
  return [...entry, require.resolve('my-other-addon/addDecorator')];
};
 
export default {
  managerEntries,
  config,
};

如果你可以控制想要自定义的插件。在这种情况下,你可以更新你的预设并实现一个自定义函数来加载任何额外的预设并提供必要的配置。