84,621
返回集成

徽章

一个 Storybook 插件，允许您在故事中添加徽章。

在 Github 上查看

npm version

Storybook 徽章插件

使用 @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";

然后，您可以通过配置对象设置徽章位置。

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

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

请注意，sidebar 位置存在一个已知的怪癖，这意味着它仅对当前活动的故事进行渲染。

升级到 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;

请注意，现在建议故事使用 CSF 格式，仅为文档页面使用外部 MDX 文件。因此，此插件将不正式支持 MDX 故事格式，但它可能也能正常工作。

工具提示

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

// .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;

每个徽章的键将在整个 Storybook 中用于调用该徽章。

在使用 TypeScript 时，我倾向于将每个键定义为一个 enum，或者在纯 JavaScript 中甚至定义为一个 Object，以避免使用魔法字符串。

如果您以后没有定义您使用的徽章，请不要担心，任何无法识别的徽章都会回退到默认的预配置灰色。

提示：如果您愿意，除了使用 addParameters 函数之外，您还可以导出包含完整参数对象的 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';

然后，您可以通过传入以下枚举值来使用这些徽章。

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

如果您希望覆盖这些样式，可以通过配置具有相同键的徽章来实现。

// .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 属性。

组件故事格式 (CSF)

所有故事

以下操作将把徽章应用到故事中的所有组件。

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({});

单个故事

您还可以选择性地为每个故事添加徽章。

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],
};

从故事中删除徽章

在将徽章应用于所有故事时，您也可以选择性地删除它们。

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
标签
如何安装插件 创建插件