参加在线会议:美国东部时间周四上午 11 点,Storybook 9 发布及 AMA

徽章

一个 Storybook 插件,允许您向您的 stories 添加徽章

在 Github 上查看

npm version

Storybook Addon Badges

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

Screenshot of 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 (块级填充)

重大变更

之前的 colorcontrast 属性已被弃用并已移除。请迁移到 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: [],
};
由...制作
  • geometricpandadev
    geometricpandadev
支持
    Angular
    Ember
    HTML
    Preact
    React
    React native
    Svelte
    Vue
    Web Components
标签