Storybook 标签

杂乱源于未能将事物归还原位。
— 近藤麻理惠

Storybook 成功的秘诀在于，其原子单元——故事（story）——是开发、测试和文档化组件的一种简单而强大的方式。故事编写起来非常容易，许多项目都包含成百上千个故事。

然而，庞大的 Storybook 可能会让人不知所措：混合了来自不同团队、面向不同受众（例如开发者 vs 设计师）、不同完成状态（不稳定、Alpha 版、稳定版、已弃用）等的组件和故事。

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

您可以通过层级来组织 Storybook 的侧边栏，但这对于需要考虑的许多不相关方面来说，效果有限。

因此，我很高兴地推出 Storybook 标签（tags），这是一种组织和查看故事的新方法。

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

为您的组件和故事打上标签

标签很简单。标签可以在您项目的预览配置（在 .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 函数的故事。

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

基于标签的静态过滤

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

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

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

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

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

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

标签徽章插件

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

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

立即尝试！

Storybook 8.4 完全支持标签。在新建项目中尝试一下。

npx storybook@latest init

或升级现有项目

npx storybook@latest upgrade

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

要将社区支持的 Tag Badges 插件添加到 8.4+ 项目

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

有关更多信息，请参阅Tags Badges README。

下一步

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

我们正在考虑的一些想法

• 用于标签过滤器的 URL 参数，以便您可以共享 Storybook 的过滤视图。
• 能够通过冒号分隔的前缀对标签进行分组，例如 type:story 和 type:docs。
• 交互式过滤当前*包含*基于标签的故事。我们也在考虑*排除*故事的可能性。

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