Storybook 背景切换插件

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

可以在 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>
};

装饰器

全局 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