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