Storybook Addon Badges

使用 @geometricpanda/storybook-addon-badges 您可以向您的 Storybook 应用添加徽章。

安装

NPM

npm install @geometricpanda/storybook-addon-badges --save

Yarn

yarn add @geometricpanda/storybook-addon-badges

配置

在您的 .storybook/main.ts 中，您需要将 @geometricpanda/storybook-addon-badges 加载到 Storybook 中

// .storybook/main.ts
module.exports = {
  stories: [],
  addons: ['@geometricpanda/storybook-addon-badges'],
};

或者，您可以在 .storybook/preview.ts 中定义自定义徽章样式。

// .storybook/preview.ts
import type { Preview } from "@storybook/react";
import { BADGE, BadgesConfig, BADGE_LOCATION } from "@geometricpanda/storybook-addon-badges";

const preview: Preview = {
  parameters: {
    badgesConfig: <BadgesConfig>{
      beta: {
        styles: {
          backgroundColor: '#FFF',
          borderColor: '#018786',
          color: '#018786',
        },
        location: [BADGE_LOCATION.TOOLBAR, BADGE_LOCATION.SIDEBAR],
        title: 'Beta',
      },
      deprecated: {
        styles: {
          backgroundColor: '#FFF',
          borderColor: '#6200EE',
          color: '#6200EE',
        },
        location: [BADGE_LOCATION.TOOLBAR_EXTRA],
        title: 'Deprecated',
      },
    },
  }
}

export default preview;

新功能

• 您现在可以在配置中定义每个徽章的位置

徽章位置

您可以使用以下导入来导入徽章位置列表

import { BADGE_LOCATION } from "@geometricpanda/storybook-addon-badges";

然后您可以通过 config 对象设置徽章位置

badgesConfig: <BadgesConfig>{
  beta: {
    styles: {
      backgroundColor: "#FFF",
      borderColor: "#018786",
      color: "#018786"
    },
    location: [BADGE_LOCATION.TOOLBAR, BADGE_LOCATION.SIDEBAR],
    title: "Beta"
  }
};

如果未设置位置，或位置数组为空，徽章将显示在工具栏中。

请注意，sidebar 位置有一个已知的怪癖，这意味着它仅在当前活动的 story 中渲染。

升级到 Storybook 7

由于 Storybook 7 已经移除了 addParameters 方法，我们需要迁移到导出 preview 对象。幸运的是，这与我们之前的做法并不太不同。

之前

// .storybook/preview.ts
import { addParameters } from '@storybook/react';
import { BadgesConfig } from "@geometricpanda/storybook-addon-badges";

addParameters({
  badgesConfig: <BadgesConfig>{
    ...
  }
});

之后

// .storybook/preview.ts
import type { Preview } from "@storybook/react";
import { BadgesConfig } from "@geometricpanda/storybook-addon-badges";

const preview: Preview = {
  parameters: {
    badgesConfig: <BadgesConfig>{
      ...
    },
  }
};

export default preview;

请注意，现在建议 stories 使用 CSF 格式，而外部 MDX 文件仅用于文档页面。因此，此插件不会正式支持 MDX story 格式，但可能仍然可以正常工作。

工具提示

或者，您可以为您的任何徽章定义更复杂的工具提示。

// .storybook/preview.ts
import type { Preview } from "@storybook/react";
import { BADGE, BadgesConfig } from "@geometricpanda/storybook-addon-badges";

const preview: Preview = {
  parameters: {
    badgesConfig: <BadgesConfig>{
      beta: {
        tooltip: {
          title: 'This is Beta',
          desc: 'Be ready to receive updates frequently and leave a feedback',
          links: [
            { title: 'Read more', href: 'http://path/to/your/docs' },
            {
              title: 'Leave feedback',
              onClick: () => {
                alert('thanks for the feedback');
              },
            },
          ],
        },
      },
      deprecated: {
        title: "Deprecated",
        tooltip: 'This component is deprecated, please avoid using it.',
      },
    },
  }
};

export default preview;

每个徽章的 key 将是在整个 storybook 中用来调用该徽章的标识符。

在使用 TypeScript 时，我倾向于将每个 key 定义为一个 enum，或者在纯 JavaScript 中定义为一个 Object，以避免使用 magic strings。

如果您没有定义稍后使用的徽章，也不用担心，任何未被识别的徽章都将回退到默认的预设灰色。

提示：如果您更喜欢，除了使用 addParameters 函数之外，您还可以导出包含完整 parameters 对象的 const parameters。

// .storybook/constants.ts
export enum BADGES {
  STATUS = 'status',
}

// .storybook/preview.ts
import type { Preview } from "@storybook/react";
import { BADGE, BadgesConfig } from "@geometricpanda/storybook-addon-badges";

const preview: Preview = {
  parameters: {
    badgesConfig: <BadgesConfig>{
      [BADGE.STATUS]: {
        styles: {
          backgroundColor: '#FFF',
          borderColor: '#018786',
          color: '#018786',
        },
        title: 'Status',
      },
    },
  }
};

export default preview;

预设徽章

您可以使用以下导入来导入预设徽章的集合

import { BADGE } from '@geometricpanda/storybook-addon-badges';

然后您可以通过传入以下 enum 值来使用这些徽章

• BADGE.DEFAULT
• BADGE.BETA
• BADGE.STABLE
• BADGE.DEPRECATED
• BADGE.EXPERIMENTAL
• BADGE.NEEDS_REVISION
• BADGE.OBSOLETE

如果您希望覆盖这些样式，您可以通过使用相同的 key 配置徽章来实现

// .storybook/preview.ts
import type { Preview } from "@storybook/react";
import { BADGE, BadgesConfig } from "@geometricpanda/storybook-addon-badges";

const preview: Preview = {
  parameters: {
    badgesConfig: <BadgeConfig>{
      [BADGE.STATUS]: {
        styles: {
          backgroundColor: '#FFF',
          borderColor: '#018786',
          color: '#018786',
        },
        title: 'Status',
      },
    },
  }
}

export default preview;

styles 配置的有效选项包括

• backgroundColor (背景颜色)
• borderColor (边框颜色)
• borderRadius (边框圆角)
• borderStyle (边框样式)
• borderWidth (边框宽度)
• color (颜色)
• fontSize (字体大小)
• fontFamily (字体)
• fontWeight (字体粗细)
• lineHeight (行高)
• textTransform (文本转换)
• paddingInline (内联填充)
• paddingBlock (块级填充)

重大变更

之前的 color 和 contrast 属性已被弃用并已移除。请迁移到 styles 属性。

组件 Story 格式 (CSF)

所有 Stories

以下设置将把徽章应用到您的 Story 中的所有组件

import { BADGE } from '@geometricpanda/storybook-addon-badges';

export default {
  title: 'Path/To/MyComponent',
  parameters: {
    badges: [
      BADGE.DEPRECATED,
      BADGE.OBSOLETE
    ],
  },
};

const Template = () => <h1>Hello World</h1>;

export const FirstComponent = Template.bind({});
export const SecondComponent = Template.bind({});
export const ThirdComponent = Template.bind({});

单个 Stories

您也可以选择性地为每个 Story 添加徽章

import { BADGE } from '@geometricpanda/storybook-addon-badges';

export default {
  title: 'Path/To/MyComponent',
};

const Template = () => <h1>Hello World</h1>;

export const FirstComponent = Template.bind({});
FirstComponent.parameters = {
  badges: [BADGE.DEPRECATED],
};

export const SecondComponent = Template.bind({});
SecondComponent.parameters = {
  badges: [BADGE.STABLE],
};

export const ThirdComponent = Template.bind({});
ThirdComponent.parameters = {
  badges: [BADGE.OBSOLETE],
};

从 Stories 中移除徽章

当将徽章应用到所有 Stories 时，您也可以选择性地移除它们

import { BADGE } from '@geometricpanda/storybook-addon-badges';

export default {
  title: 'Path/To/MyComponent',
  parameters: {
    badges: [BADGE.BETA],
  },
};

const Template = () => <h1>Hello World</h1>;

export const FirstComponent = Template.bind({});
export const SecondComponent = Template.bind({});

export const ThirdComponent = Template.bind({});
ThirdComponent.parameters = {
  badges: [],
};