Addon API

Storybook 的 API 允许开发者以编程方式与 Storybook 交互。借助 API，开发者可以构建和部署自定义插件以及其他增强 Storybook 功能的工具。

核心 Addon API

我们的 API 通过两个不同的包公开，每个包都有不同的用途

@storybook/manager-api 用于与 Storybook 管理器 UI 交互或访问 Storybook API。
@storybook/preview-api 用于控制和配置插件的行为。

my-addon/src/manager.js|ts

import { addons } from '@storybook/preview-api';
 
import { useStorybookApi } from '@storybook/manager-api';

addons.add()

add 方法允许您注册与插件关联的 UI 组件类型（例如，面板、工具栏、选项卡）。对于最低可用的 Storybook 插件，您应该提供以下参数

type：要注册的 UI 组件的类型。
title：要在插件面板中显示的标题。
render：渲染插件 UI 组件的函数。

my-addon/src/manager.js|ts

import React from 'react';
 
import { addons, types } from '@storybook/manager-api';
 
import { AddonPanel } from '@storybook/components';
 
const ADDON_ID = 'myaddon';
const PANEL_ID = `${ADDON_ID}/panel`;
 
addons.register(ADDON_ID, (api) => {
  addons.add(PANEL_ID, {
    type: types.PANEL,
    title: 'My Addon',
    render: ({ active }) => (
      <AddonPanel active={active}>
        <div> Storybook addon panel </div>
      </AddonPanel>
    ),
  });
});

渲染函数在 active 为真时调用。active 值在面板聚焦于 UI 时为 true。

addons.register()

作为所有插件的入口点。它允许您注册插件并访问 Storybook API。例如

my-addon/src/manager.js|ts

import { addons } from '@storybook/preview-api';
 
// Register the addon with a unique name.
addons.register('my-organisation/my-addon', (api) => {});

现在您将获得 StorybookAPI 的实例。有关使用方法，请参阅 Storybook API 的 api 文档。

addons.getChannel()

获取通道的实例以与管理器和预览进行通信。您可以在插件注册代码和插件的包装器组件（在 story 中使用时）中找到它。

它具有 NodeJS EventEmitter 兼容的 API。因此，您可以使用它来发出事件和监听事件。

my-addon/src/manager.js|ts

import React, { useCallback } from 'react';
 
import { FORCE_RE_RENDER } from '@storybook/core-events';
import { addons } from '@storybook/preview-api';
import { useGlobals } from '@storybook/manager-api';
import { IconButton } from '@storybook/components';
import { OutlineIcon } from '@storybook/icons';
 
const ExampleToolbar = () => {
  const [globals, updateGlobals] = useGlobals();
 
  const isActive = globals['my-param-key'] || false;
 
  // Function that will update the global value and trigger a UI refresh.
  const refreshAndUpdateGlobal = () => {
    updateGlobals({
      ['my-param-key']: !isActive,
    }),
      // Invokes Storybook's addon API method (with the FORCE_RE_RENDER) event to trigger a UI refresh
      addons.getChannel().emit(FORCE_RE_RENDER);
  };
 
  const toggleToolbarAddon = useCallback(() => refreshAndUpdateGlobal(), [isActive]);
 
  return (
    <IconButton
      key="Example"
      active={isActive}
      title="Show the toolbar addon"
      onClick={toggleToolbarAddon}
    >
      <OutlineIcon />
    </IconButton>
  );
};

makeDecorator

使用 makeDecorator API 创建官方插件风格的装饰器。像这样

my-addon/src/decorator.js|ts

import { makeDecorator } from '@storybook/preview-api';
 
export const withAddonDecorator = makeDecorator({
  name: 'withSomething',
  parameterName: 'CustomParameter',
  skipIfNoParametersOrOptions: true
  wrapper: (getStory, context, { parameters }) => {
    /*
    * Write your custom logic here based on the parameters passed in Storybook's stories.
    * Although not advised, you can also alter the story output based on the parameters.
    */
    return getStory(context);
  },
});

如果 story 的参数包含 { exampleParameter: { disable: true } }（其中 exampleParameter 是您的插件的 parameterName），则不会调用您的装饰器。

makeDecorator API 需要以下参数

name：用于标识自定义插件装饰器的唯一名称。
parameterName：设置要由插件使用的唯一参数。
skipIfNoParametersOrOptions：（可选）如果用户没有通过装饰器或参数提供选项，则不运行装饰器。
wrapper：您的装饰器函数。接受 getStory、context 以及 options 和 parameters（如上面的 skipIfNoParametersOrOptions 中定义）。

Storybook API

Storybook 的 API 允许您访问 Storybook UI 的不同功能。

api.selectStory()

selectStory API 方法允许您选择单个 story。它接受以下两个参数；story kind 名称和一个可选的 story 名称。例如

Button.stories.ts|tsx

import type { Meta, StoryObj } from '@storybook/react';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  /* 👇 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,
  //👇 Creates specific parameters for the story
  parameters: {
    myAddon: {
      data: 'This data is passed to the addon',
    },
  },
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
/*
 *👇 Render functions are a framework specific feature to allow you control on how the component renders.
 * See https://storybook.org.cn/docs/api/csf
 * to learn how to use render functions.
 */
export const Basic: Story = {
  render: () => <Button>Hello</Button>,
};

以下是如何选择上述 story

my-addon/src/manager.js|ts

addons.register('my-organisation/my-addon', (api) => {
  api.selectStory('Button', 'Default');
});

api.selectInCurrentKind()

与 selectStory API 方法类似，但它只接受 story 作为唯一参数。

my-addon/src/manager.js|ts

addons.register('my-organisation/my-addon', (api) => {
  api.selectInCurrentKind('Default');
});

api.setQueryParams()

此方法允许您设置查询字符串参数。您可以将其用作插件的临时存储。以下是如何定义查询参数

my-addon/src/manager.js|ts

addons.register('my-organisation/my-addon', (api) => {
  api.setQueryParams({
    exampleParameter: 'Sets the example parameter value',
    anotherParameter: 'Sets the another parameter value',
  });
});

此外，如果您需要删除查询参数，请将其设置为 null 而不是从插件中删除它们。例如

my-addon/src/manager.js|ts

addons.register('my-organisation/my-addon', (api) => {
  api.setQueryParams({
    exampleParameter: null,
  });
});

api.getQueryParam()

允许检索通过 setQueryParams API 方法启用的查询参数。例如

my-addon/src/manager.js|ts

addons.register('my-organisation/my-addon', (api) => {
  api.getQueryParam('exampleParameter');
});

api.getUrlState(overrideParams)

此方法允许您获取应用程序 URL 状态，包括任何覆盖或自定义的参数值。例如

my-addon/src/manager.js|ts

addons.register('my-organisation/my-addon', (api) => {
  const href = api.getUrlState({
    selectedKind: 'kind',
    selectedStory: 'story',
  }).url;
});

api.on(eventName, fn)

此方法允许您注册一个处理函数，每当用户在 stories 之间导航时调用该函数。

my-addon/src/manager.js|ts

addons.register('my-organisation/my-addon', (api) => {
  // Logs the event data to the browser console whenever the event is emitted.
  api.on('custom-addon-event', (eventData) => console.log(eventData));
});

addons.setConfig(config)

此方法允许您覆盖默认的 Storybook UI 配置（例如，设置主题或隐藏 UI 元素）

.storybook/manager.js

import { addons } from '@storybook/manager-api';
 
addons.setConfig({
  navSize: 300,
  bottomPanelHeight: 300,
  rightPanelWidth: 300,
  panelPosition: 'bottom',
  enableShortcuts: true,
  showToolbar: true,
  theme: undefined,
  selectedPanel: undefined,
  initialActive: 'sidebar',
  sidebar: {
    showRoots: false,
    collapsedRoots: ['other'],
  },
  toolbar: {
    title: { hidden: false },
    zoom: { hidden: false },
    eject: { hidden: false },
    copy: { hidden: false },
    fullscreen: { hidden: false },
  },
});

下表详细说明了如何使用 API 值

名称	类型	描述	示例值
navSize	数字 (像素)	显示故事列表的侧边栏大小	`300`
bottomPanelHeight	数字 (像素)	附加组件面板在底部位置时的大小	`200`
rightPanelWidth	数字 (像素)	附加组件面板在右侧位置时的大小	`200`
panelPosition	字符串	在哪里显示附加组件面板	`'bottom'` 或 `'right'`
enableShortcuts	布尔值	启用/禁用快捷键	`true`
showToolbar	布尔值	显示/隐藏工具栏	`true`
theme	对象	Storybook 主题，请参阅下一节	`undefined`
selectedPanel	字符串	选择附加组件面板的 ID	`storybook/actions/panel`
initialActive	字符串	选择移动设备上的默认活动标签页	`sidebar` 或 `canvas` 或 `addons`
sidebar	对象	侧边栏选项，请参阅下文	`{ showRoots: false }`
toolbar	对象	使用附加组件 ID 修改工具栏中的工具	`{ fullscreen: { hidden: false } }`

以下选项可在 sidebar 命名空间下配置

名称	类型	描述	示例值
showRoots	布尔值	在侧边栏中将顶层节点显示为“根节点”	`false`
collapsedRoots	数组	默认情况下视觉上折叠的根节点 ID 集合	`['misc', 'other']`
renderLabel	函数	为树节点创建自定义标签；必须返回 ReactNode	`(item, api) => <abbr title="...">{item.name}</abbr>`

以下选项可在 toolbar 命名空间下配置

名称	类型	描述	示例值
id	字符串	切换工具栏项的可见性	`{ hidden: false }`

Storybook Hooks

为了帮助简化附加组件开发并减少样板代码，API 公开了一组 Hooks 以访问 Storybook 的内部组件。这些 Hooks 是 @storybook/manager-api 包的扩展。

useStorybookState

它允许访问 Storybook 的内部状态。与 useglobals hook 类似，我们建议优化您的附加组件以依赖 React.memo 或以下 Hooks：useMemo、useCallback，以防止大量的重新渲染循环。

my-addon/src/manager.js|ts

import React from 'react';
 
import { AddonPanel } from '@storybook/components';
 
import { useStorybookState } from '@storybook/manager-api';
 
export const Panel = () => {
  const state = useStorybookState();
  return (
    <AddonPanel {...props}>
      {state.viewMode !== 'docs' ? (
        <h2>Do something with the documentation</h2>
      ) : (
        <h2>Show the panel when viewing the story</h2>
      )}
    </AddonPanel>
  );
};

useStorybookApi

useStorybookApi hook 是一个方便的助手，让您可以完全访问 Storybook API 方法。

my-addon/manager.js|ts

import React, { useEffect, useCallback } from 'react';
 
import { useStorybookApi } from '@storybook/manager-api';
import { IconButton } from '@storybook/components';
import { ChevronDownIcon } from '@storybook/icons';
 
export const Panel = () => {
  const api = useStorybookApi();
 
  const toggleMyTool = useCallback(() => {
    // Custom logic to toggle the addon here
  }, []);
 
  useEffect(() => {
    api.setAddonShortcut('custom-toolbar-addon', {
      label: 'Enable toolbar addon',
      defaultShortcut: ['G'],
      actionName: 'Toggle',
      showInMenu: false,
      action: toggleAddon,
    });
  }, [api]);
 
  return (
    <IconButton key="custom-toolbar" active="true" title="Show a toolbar addon">
      <ChevronDownIcon />
    </IconButton>
  );
};

useChannel

允许设置事件订阅，并获取发射器以向通道发射自定义事件。

消息可以在 iframe 和管理器上被监听。

my-addon/manager.js|ts

import React from 'react';
 
import { AddonPanel, Button } from '@storybook/components';
 
import { STORY_CHANGED } from '@storybook/core-events';
 
import { useChannel } from '@storybook/manager-api';
 
export const Panel = () => {
  // Creates a Storybook API channel and subscribes to the STORY_CHANGED event
  const emit = useChannel({
    STORY_CHANGED: (...args) => console.log(...args),
  });
 
  return (
    <AddonPanel key="custom-panel" active="true">
      <Button onClick={() => emit('my-event-type', { sampleData: 'example' })}>
        Emit a Storybook API event with custom data
      </Button>
    </AddonPanel>
  );
};

useAddonState

useAddonState 对于需要数据持久性的附加组件是一个有用的 hook，无论是由于 Storybook 的 UI 生命周期还是涉及多种类型（例如，工具栏、面板）的更复杂的附加组件。

my-addon/manager.js|ts

import React from 'react';
 
import { useAddonState } from '@storybook/manager-api';
import { AddonPanel, IconButton } from '@storybook/components';
import { LightningIcon } from '@storybook/icons';
 
export const Panel = () => {
  const [state, setState] = useAddonState('addon-unique-identifier', 'initial state');
 
  return (
    <AddonPanel key="custom-panel" active="true">
      <Button onClick={() => setState('Example')}>
        Click to update Storybook's internal state
      </Button>
    </AddonPanel>
  );
};
export const Tool = () => {
  const [state, setState] = useAddonState('addon-unique-identifier', 'initial state');
 
  return (
    <IconButton
      key="custom-toolbar"
      active="true"
      title="Enable my addon"
      onClick={() => setState('Example')}
    >
      <LightningIcon />
    </IconButton>
  );
};

useParameter

useParameter 检索当前故事的参数。如果未定义参数值，它将自动默认为第二个定义的值。

my-addon/manager.js|ts

import React from 'react';
 
import { AddonPanel } from '@storybook/components';
 
import { useParameter } from '@storybook/manager-api';
 
export const Panel = () => {
  // Connects to Storybook's API and retrieves the value of the custom parameter for the current story
  const value = useParameter('custom-parameter', 'initial value');
 
  return (
    <AddonPanel key="custom-panel" active="true">
      {value === 'initial value' ? (
        <h2>The story doesn't contain custom parameters. Defaulting to the initial value.</h2>
      ) : (
        <h2>You've set {value} as the parameter.</h2>
      )}
    </AddonPanel>
  );
};

useGlobals

对于依赖 Storybook Globals 的附加组件来说，这是一个非常有用的 hook。它允许您获取和更新全局值。我们还建议优化您的附加组件以依赖 React.memo 或以下 Hooks：useMemo、useCallback，以防止大量的重新渲染循环。

my-addon/manager.js|ts

import React from 'react';
 
import { AddonPanel, Button } from '@storybook/components';
 
import { useGlobals } from '@storybook/manager-api';
 
export const Panel = () => {
  const [globals, updateGlobals] = useGlobals();
 
  const isActive = globals['my-param-key'] || false; // 👈 Sets visibility based on the global value.
 
  return (
    <AddonPanel key="custom-panel" active={isActive}>
      <Button onClick={() => updateGlobals({ ['my-param-key']: !isActive })}>
        {isActive ? 'Hide the addon panel' : 'Show the panel'}
      </Button>
    </AddonPanel>
  );
};

useArgs

Hook，允许您检索或更新故事的 args。

my-addon/src/manager.js|ts

import { useArgs } from '@storybook/manager-api';
 
const [args, updateArgs, resetArgs] = useArgs();
 
// To update one or more args:
updateArgs({ key: 'value' });
 
// To reset one (or more) args:
resetArgs((argNames: ['key']));
 
// To reset all args
resetArgs();

了解更多关于 Storybook 附加组件生态系统的信息

其他类型的附加组件的附加组件类型
编写附加组件，了解附加组件开发的基础知识
预设，用于预设开发
集成目录，用于了解要求和可用配方
API 参考，了解可用的 API