Storybook 标签

杂乱是因为未能将物品放回原位。
— Marie Kondo

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

但是大型 Storybook 可能会让人感到难以承受：混合来自不同团队的组件和故事，针对不同的角色（例如，开发人员与设计师），不同的完成状态（不稳定、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 属性，我想将其标记为 experimental，我可以使用否定删除 stable 标签并添加 experimental 标签

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

交互式侧边栏过滤器

一旦你标记了你的故事，你就可以使用新的 UI 交互式地过滤侧边栏

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

默认情况下，所有标签都未选中，因此显示所有故事。在菜单中选中一个或多个标签将过滤侧边栏，仅显示带有这些标签的故事，从而可以灵活地创建 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 讨论，用于收集标签反馈和收集真实世界的用例。如果你有想法，请在那里分享！