Storybook 标签

混乱是因为没有将东西放回原位。
— 近藤麻理惠

Storybook 成功的秘诀在于其原子单元——故事——是一种开发、测试和文档化组件的既简单又强大的方式。故事非常易于编写，许多项目包含数百甚至数千个故事。

但大型 Storybook 可能会让人不知所措：混合了来自不同团队的组件和故事，面向不同角色（例如开发者 vs 设计师），不同完成状态（不稳定、alpha、稳定、已废弃），等等。

随着 Storybook Test 的引入，团队越来越希望将面向测试的故事与面向文档的故事分开。

你可以使用层次结构级别来组织 Storybook 的侧边栏，但这在考虑许多不相关的方面时效果有限。

这就是为什么我很兴奋地推出 Storybook 标签，一种组织和查看故事的新方式。

• 🏷️ 易于创作
• 🔍 交互式侧边栏过滤
• 🙈 静态基于标签过滤
• 🟢 更新的徽章插件

给你的组件和故事打标签

打标签很简单。标签可以在你的项目预览配置中（在 .storybook/preview.js|ts 中）定义，以应用于所有故事；也可以在组件元数据中（故事文件的默认导出）定义，以应用于故事文件中的故事；或者应用于单个故事。要应用标签，只需将字符串添加到分配给 tags 属性的数组中。它们是分层组成的，因此在下面的示例中，Button 的所有故事都标记为 stable。

// Button.stories.jsx
import { Button } from './Button';

export default {
  component: Button,
  // 👇 Applies to all stories in this file
  tags: ['stable'],
}

export const Primary = {
  args: { primary: true }
}

标签也可以被否定。在前面的示例中，假设我添加了一个新的 icon prop，并希望将其标记为 experimental，我可以使用否定方式移除 stable 标签并添加 experimental 标签。

export const WithIcon = {
  args: { icon: <Icon /> },
  tags: ['!stable', 'experimental'],
}

交互式侧边栏过滤

给故事打上标签后，你可以使用新的 UI 交互式地过滤侧边栏。

你可以按应用于故事的任何标签以及一些内置标签进行过滤，例如 play-fn，它会自动应用于任何定义了 play 函数的故事。

默认情况下，所有标签都是未选中的，因此显示所有故事。在菜单中选中一个或多个标签将把侧边栏过滤到仅包含这些标签的故事，从而可以灵活地创建 Storybook 的视图。还可以在过滤视图中执行基于文本的搜索。

静态基于标签过滤

虽然交互式侧边栏过滤提供了一种灵活的方式来查看和搜索侧边栏，但标签也可以用于静态地包含/排除侧边栏、文档甚至测试运行中的故事。

假设你正在测试一个复杂组件，并且需要一堆故事来覆盖边缘情况。这些边缘情况提供了测试价值，但会使侧边栏变得混乱。你可以通过移除 dev 标签将其从侧边栏中移除，该标签默认添加到所有故事中。

export const EdgeCase = {
  args: { ... },
  tags: ['!dev'],
}

类似地，假设某个故事仅用于文档目的，并且你不希望它减慢测试运行速度（或出于任何其他原因想要跳过它）。你可以从该故事中移除 test 标签（默认也应用该标签）。

export const SkipTesting = {
  args: { ... },
  tags: ['!test'],
}

更多详细信息，请参阅 内置标签完整列表。

标签徽章插件

为了完善此功能，Storybook 社区成员 Steve Dodier-Lazaro 创建了标签徽章插件 storybook-addon-tag-badges，它将标签转化为 Storybook 侧边栏中的可视化徽章。

该插件预配置了一组标签以渲染为徽章。你还可以配置哪些标签用作徽章以及何时如何渲染它们。有关标签徽章插件的更多信息，请参阅插件 README。

立即尝试！

Storybook 8.4 完全支持标签功能。在新项目中使用它

npx storybook@latest init

或升级现有项目

npx storybook@latest upgrade

要了解有关标签的更多信息，请参阅Storybook 文档。

将社区支持的标签徽章插件添加到 8.4+ 项目中

npx storybook@latest add storybook-addon-tag-badges

更多信息请参阅标签徽章 README。

接下来是什么

标签是一种灵活的机制，我们无法预见到它们可能被使用的所有方式。

我们正在考虑的一些想法

• 为标签过滤器提供 URL 参数，以便你可以分享 Storybook 的过滤视图。
• 支持使用冒号分隔的前缀对标签进行分组，例如 type:story 和 type:docs。
• 交互式过滤目前基于标签包含故事。我们也在考虑排除故事的功能。

我们已创建了一个Github 讨论区，用于收集标签反馈和实际用例。如果你有想法，请在那里分享！