Storybook Addon Toggle

此插件用于添加用户定义的全局开关列表，这些开关可在故事级别访问和自定义。所有选项均在下方解释，请参阅下方的参数部分。

请访问 https://nickofthyme.github.io/storybook-addon-toggles/ 进行试用

兼容性

此版本与 Storybook 版本 >6.x 兼容。

从 Storybook 6.3.0 开始，全局参数会与 URL 同步为查询搜索参数 (storybookjs/storybook#15056)。因此，这将锁定默认全局值并使其在故事之间持久化。如果您想避免此行为，应使用 storybook@~6.2.0。

安装

yarn

yarn add -D storybook-addon-toggles

npm

npm i -D storybook-addon-toggles

入门

安装完成后，将此插件添加到 Storybook 的 main.js 文件中的 addons 数组中

// main.js
module.exports = {
  addons: [
    'storybook-addon-toggles'
  ],
};

更多信息请参阅 Storybook 文档。

参数

此插件的参数位于 toggles 键下，定义如下。

export interface Parameters<ToggleId extends string = string> {
  /**
   * Ignores global values in url params
   *
   * @default true
   */
  ignoreQueryParams?: false;
  /**
   * Toggle options
   */
  options: ToggleOptions<ToggleId>[];
  /**
   * Toggle default overrides from story level
   */
  overrides: Record<ToggleId, boolean>;
  /**
   * Enabled clearing all toggles to default values
   *
   * @default true
   */
  clearable?: boolean;
  /**
   * Addon is disabled at story level
   *
   * @default false
   */
  disabled?: boolean;
  /**
   * Override icon used in toolbar
   * See https://github.com/storybookjs/storybook/blob/release/6.2/lib/components/src/icon/icons.tsx
   *
   * @default 'form'
   */
  icon?: IconsProps['icon'];
  /**
   * A callback that will be executed when the toggles change
   */
  onChange?: (Toggles?: Toggles) => void;
}

ToggleOptions 类型定义如下。

export type ToggleKey = string;
export type ToggleValue = boolean
export type Toggles = Record<string, ToggleValue>;

export interface ToggleOptions<T extends string = string> {
  /**
   * id of the toggle
   */
  id: T;
  /**
   * Title of the toggle in Selector UI
   */
  title?: string;
  /**
   * Description of the toggle, shows in title on hover
   */
  description?: string;
  /**
   * Default value
   */
  defaultValue: ToggleValue;
  /**
   * Disable toggle by boolean or list of dependent toggles
   */
  disabled?: boolean | Toggles;
}

配置

全局级别

您可以在 Storybook 的 preview.(ts|js) 文件中配置全局级别的开关，如下所示范。

// preview.ts

import type { TogglesParameter } from 'storybook-addon-toggles';

type Parameters = TogglesParameter & {
  // other global types
};

export const parameters: Parameters = {
  toggles: {
    ignoreQueryParams: false,
    icon: 'form',
    options: [
      {
        id: 'option-1',
        title: 'Option 1',
        description: 'Some description of option 1',
        defaultValue: false,
      },
      {
        id: 'option-2',
        title: 'Option 2',
        defaultValue: true,
      },
      {
        id: 'option-3',
        title: 'Option 3',
        defaultValue: true,
        disabled: {
          "option-2": false
        }
      },
    ],
  }
};

故事级别

TogglesParameter 中定义的所有属性都可以在故事级别被覆盖。但是，建议只覆盖部分参数，以防止定义可能对所有故事中的插件行为产生负面影响的参数。可接受的属性包括 overrides, options, disabled, ignoreQueryParams 和 clearable。BackgroundStoryParameter 类型是一个辅助工具，应用于限制在故事级别覆盖的属性。

// story.stories.tsx

import type { StoryTogglesParameter } from 'storybook-addon-toggles';

const Example = () => <span>Hello!</span>;

Example.parameters = {
  toggles: {
    overrides: {
      'option-1': false,
    }
  }
} as StoryTogglesParameter;

全局上下文的使用

故事

每个故事都使用两个参数进行渲染，第一个是 Story.bind(myArgs) 中的 args，第二个是 StoryContext。StoryContext 使我们可以直接访问全局变量。

// story.stories.tsx

const Example = (args, context) => {
  return <span>Value of Option 1: ${context.globals.toggles['option-1']}</span>
};

装饰器 (Decorators)

全局 Storybook Decorators 可用于多种用途。因此，在装饰器内部访问开关非常重要。这是选择使用 globals 来维护开关状态的主要原因。

下面是一个简单的示例，展示如何通过 context.globals 访问开关。

// preview.tsx

import React from "react";

import type { DecoratorFunction } from "@storybook/addons";
import type { TogglesGlobals } from 'storybook-addon-toggles';

const Decorator: DecoratorFunction<JSX.Element> = (Story, context) => {
  const globals = context.globals as TogglesGlobals;
  const toggles = globals.toggles; // object of all toggle values

  return (
    <div>
      <Story {...context} />
      <br />
      <pre>
        // Toggle values
        {JSON.stringify(toggles, null, 2)}
      </pre>
    </div>
  );
};

export const decorators = [Decorator];

有关完整示例，请参阅 .storybook/Decorator.tsx。

全局变量目前未被 Storybook 正确初始化，这意味着它们总是返回 {} 作为初始值。为了纠正这个问题，我们在触发 SET_STORIES 事件后，如果全局变量与默认/初始开关不同，就会更新全局变量。

框架支持

React
:white_check_mark