Storybook 擴充套件徽章

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

然後，您可以透過設定物件來設定徽章位置

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