Storybook Addon Background Toggle

此插件受到 @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',
  }
};

在 Decorators 中的使用

全局 Storybook Decorators 可用于多种用途。因此，在 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 目前未正确初始化 Globals，这意味着它们总是返回 {} 作为初始值。为了解决此问题，如果在 SET_STORIES 事件触发后，Globals 与默认/初始背景 ID 不同，我们将更新 Globals。

框架支持

React
:white_check_mark: