Storybook 附加组件背景切换

此附加组件的灵感来自于 @storybook/addon-backgrounds 和 storybook-addon-backgrounds，并构建了一个更流畅、功能更丰富的实现。另请参见 storybook-addon-theme-toggle.

此附加组件可用于向一个或多个目标 HTML 元素添加自定义 background。所有选项在下面解释，请参见下面的 参数 部分。

在 https://nickofthyme.github.io/storybook-addon-background-toggle/ 上试用

https://user-images.githubusercontent.com/19007109/128195841-a8ef6de0-d804-486e-93f7-13b373eb68c8.mp4

兼容性

此版本仅兼容 storybook 版本 >6.x。不适用于 >7.x，请参见 https://github.com/nickofthyme/storybook-addon-background-toggle/issues/1.

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

安装

yarn

yarn add -D storybook-addon-background-toggle

npm

npm i -D storybook-addon-background-toggle

入门

安装后，将此附加组件添加到 storybook main.js 文件中的 addons 数组中

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

有关更多信息，请参见 storybook 文档。

参数

此插件的参数位于 background 键下，并在下面定义。

interface Parameters {
  /**
   * Ignores global values in url params
   *
   * @default true
   */
  ignoreQueryParams?: false;
  /**
   * Tefault background id
   */
  default?: string;
  /**
   * Background options to be applied
   */
  options: Background[];
  /**
   * Selected background is clearable
   *
   * @default true
   */
  clearable?: boolean;
  /**
   * Disable addon at story level
   *
   * @default false
   */
  disable?: boolean;
  /**
   * Persist background selection between stories
   *
   * @default false
   */
  persist?: boolean;
  /**
   * Blur tooltip on background selection
   *
   * @default true
   */
  blurOnSelect?: boolean;
  /**
   * Override icon used in toolbar
   * See https://next--storybookjs.netlify.app/official-storybook/?path=/story/basics-icon--labels
   *
   * @default 'mirror'
   */
  icon?: IconsProps['icon'];
  /**
   * A callback that will be executed when the background changes
   */
  onChange?: (background: Background) => void;
  /**
   * Target element selector(s) to apply class(es)
   *
   * @default 'body'
   */
  selector?: string | string[];
}

Background 类型在下面定义。

interface Background {
  /**
   * id of the background
   */
  id: string;
  /**
   * Title of the background in background selector ui
   *
   * @default {@link Background#id}
   */
  title?: string;
  /**
   * Background string to be applied to targeted element(s) via selector(s)
   * See https://mdn.org.cn/en-US/docs/Web/CSS/background
   *
   * @default {@link Background#color}
   */
  background?: string;
  /**
   * Adds the `!important` flag to the background style definition
   * See https://w3schools.org.cn/css/css_important.asp
   *
   * @default false
   */
  important?: boolean;
  /**
   * Badge color in the background selector ui, also used as default background property
   * Can be any valid background string.
   * See https://mdn.org.cn/en-US/docs/Web/CSS/background
   */
  color: string;
}

配置

全局级别

您可以在 storybook preview.(ts|js) 文件中全局配置背景，如下所示。

// preview.ts

import type { BackgroundParameter } from 'storybook-addon-background-toggle';

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

export const parameters: Parameters = {
  background: {
    default: 'white',
    selector: 'body',
    onChange(background) {
      // handle new background
    },
    backgrounds: [
      {
        id: 'white',
        title: 'White',
        color: '#fff',
      },
      {
        id: 'black',
        title: 'Black',
        color: '#000',
      },
      {
        id: 'black-important',
        title: 'Black - Important',
        important: true,
        color: '#000',
      },
      {
        id: 'raindow',
        title: 'Raindow',
        background: 'linear-gradient(to right, red,orange,yellow,green,blue,indigo,violet)',
        color: 'linear-gradient(to right, red,orange,yellow,green,blue,indigo,violet)',
      },
    ],
  }
};

故事级别

BackgroundParameter 中定义的所有属性都可以在故事级别被覆盖。但是，只建议覆盖一些参数，以防止定义可能对所有故事的附加组件行为产生负面影响的参数。可接受的属性包括 default、blurOnSelect、disable、ignoreQueryParams 和 clearable。BackgroundStoryParameter 类型是一个辅助程序，应该用于限制在故事级别覆盖哪些属性；

// story1.stories.tsx

import type { BackgroundStoryParameter } from 'storybook-addon-background-toggle';

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

Example.parameters: BackgroundStoryParameter = {
  background: {
    default: 'black',
  }
};

在装饰器中使用

全局 storybook Decorators 可用于多种用途。因此，在装饰器中访问选定背景非常重要。这是选择使用 globals 来维护选定背景状态的主要原因。

下面是一个简单示例，说明如何通过 context.globals 访问背景。

// preview.tsx

import React from "react";

import type { DecoratorFunction } from "@storybook/addons";
import type { BackgroundGlobals } from 'storybook-addon-background-toggle';

const Decorator: DecoratorFunction<JSX.Element> = (Story, context) => {
  const globals = context.globals as BackgroundGlobals;
  const selectedBackground = globals.background; // background id

  return (
    <div>
      <Story {...context} />
      <br />
      <pre>
        Background: {selectedBackground}
        {JSON.stringify(globals, null, 2)}
      </pre>
    </div>
  );
};

export const decorators = [Decorator];

在 .storybook/Decorator.tsx 中查看此示例的完整示例。

全局变量目前没有被 storybook 正确初始化，这意味着它们始终返回 {} 作为初始值。为了纠正这一点，我们在 SET_STORIES 事件发出后，使用默认/初始背景 ID 更新全局变量（如果它们不同）。

框架支持

React
:white_check_mark: