标签

标签允许你控制哪些故事包含在你的 Storybook 中，从而可以对同一组故事进行多种不同的使用。例如，你可以使用标签来包含/排除 测试运行器 中的测试。有关更复杂的用例，请参阅下面的 recipes 部分。

¥Tags allow you to control which stories are included in your Storybook, enabling many different uses of the same total set of stories. For example, you can use tags to include/exclude tests from the test runner. For more complex use cases, see the recipes section, below.

内置标签

¥Built-in tags

每个 Storybook 项目中都提供以下标签：

¥The following tags are available in every Storybook project:

dev 和 test 标签会自动、隐式地应用于 Storybook 项目中的每个故事。

¥The dev and test tags are automatically, implicitly applied to every story in your Storybook project.

应用标签

¥Applying tags

标签可以是任何静态（即非动态创建）字符串，可以是 内置标签 标签，也可以是你自己设计的自定义标签。要将标签应用于故事，请将字符串数组分配给 tags 属性。标签可以应用于项目、组件（元数据）或故事级别。

¥A tag can be any static (i.e. not created dynamically) string, either the built-in tags or custom tags of your own design. To apply tags to a story, assign an array of strings to the tags property. Tags may be applied at the project, component (meta), or story levels.

例如，要将 autodocs 标签应用于项目中的所有故事，你可以使用 .storybook/preview.js|ts：

¥For example, to apply the autodocs tag to all stories in your project, you can use .storybook/preview.js|ts:

// Replace your-renderer with the renderer you are using (e.g., react, vue3)
import type { Preview } from '@storybook/your-renderer';
 
const preview: Preview = {
  // ...rest of preview
  /*
   * All stories in your project will have these tags applied:
   * - autodocs
   * - dev (implicit default)
   * - test (implicit default)
   */
  tags: ['autodocs'],
};
 
export default preview;

在组件故事文件中，你可以像这样应用标签：

¥Within a component stories file, you apply tags like so:

// Replace your-framework with the framework you are using (e.g., nextjs, vue3-vite)
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  /*
   * All stories in this file will have these tags applied:
   * - autodocs
   * - dev (implicit default, inherited from preview)
   * - test (implicit default, inherited from preview)
   */
  tags: ['autodocs'],
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const ExperimentalFeatureStory: Story = {
  /*
   * This particular story will have these tags applied:
   * - experimental
   * - autodocs (inherited from meta)
   * - dev (inherited from meta)
   * - test (inherited from meta)
   */
  tags: ['experimental'],
};

删除标签

¥Removing tags

要从故事中删除标签，请在其前面加上 !。例如：

¥To remove a tag from a story, prefix it with !. For example:

// Replace your-framework with the framework you are using (e.g., nextjs, vue3-vite)
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  // 👇 Applies to all stories in this file
  tags: ['stable'],
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const ExperimentalFeatureStory: Story = {
  //👇 For this particular story, remove the inherited `stable` tag and apply the `experimental` tag
  tags: ['!stable', 'experimental'],
};

可以删除项目中的所有故事（在 .storybook/preview.js|ts 中）、组件的所有故事（在 CSF 文件元数据中）或单个故事（如上所述）的标签。

¥Tags can be removed for all stories in your project (in .storybook/preview.js|ts), all stories for a component (in the CSF file meta), or a single story (as above).

按自定义标签筛选

¥Filtering by custom tags

自定义标签在 Storybook 的侧边栏层次结构之上提供了一个灵活的分类层。在上面的示例中，我们创建了一个 experimental 标签来指示故事尚未稳定。

¥Custom tags enable a flexible layer of categorization on top of Storybook's sidebar hierarchy. In the example above, we created an experimental tag to indicate that a story is not yet stable.

你可以创建自定义标签用于任何用途。示例用途可能包括：

¥You can create custom tags for any purpose. Sample uses might include:

• 状态，例如 experimental、new、stable 或 deprecated

  ¥Status, such as experimental, new, stable, or deprecated

• 用户角色，例如 admin、user 或 developer

  ¥User persona, such as admin, user, or developer

• 组件/代码所有权

  ¥Component/code ownership

自定义标签非常有用，因为它们会显示在 Storybook 的侧边栏中作为筛选器。在过滤器中选择一个标签将使侧边栏仅显示带有该标签的故事。选择多个标签将显示包含任意这些标签的故事。

¥Custom tags are useful because they show up as filters in Storybook's sidebar. Selecting a tag in the filter causes the sidebar to only show stories with that tag. Selecting multiple tags shows stories that contain any of those tags.

按标签过滤是专注于部分故事的有效方法，尤其是在大型 Storybook 项目中。你还可以按标签缩小故事范围，然后在该子集中进行搜索。

¥Filtering by tags is a powerful way to focus on a subset of stories, especially in large Storybook projects. You can also narrow your stories by tag and then search within that subset.

秘诀

¥Recipes

仅限文档的故事

¥Docs-only stories

有时提供示例故事以用于文档目的会有所帮助，但你希望让侧边栏导航更专注于对开发有用的故事。通过启用 autodocs 标签并删除 dev 标签，故事将变为仅限文档：仅出现在 文档页面 中，而不出现在 Storybook 的侧边栏中。

¥It can sometimes be helpful to provide example stories for documentation purposes, but you want to keep the sidebar navigation more focused on stories useful for development. By enabling the autodocs tag and removing the dev tag, a story becomes docs-only: appearing only in the docs page and not in Storybook's sidebar.

// Replace your-framework with the framework you are using (e.g., nextjs, vue3-vite)
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  /*
   * All stories in this file will:
   * - Be included in the docs page
   * - Not appear in Storybook's sidebar
   */
  tags: ['autodocs', '!dev'],
};
export default meta;

组合故事，仍单独测试

¥Combo stories, still tested individually

对于具有许多变体的组件（例如按钮），将这些变体放在一起的网格可以成为一种可视化它的有用方法。但是你可能希望单独测试变体。你可以使用如下标签来实现这一点：

¥For a component with many variants, like a Button, a grid of those variants all together can be a helpful way to visualize it. But you may wish to test the variants individually. You can accomplish this with tags like so:

import type { Meta, StoryObj } from '@storybook/react';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
};
export default meta;
 
type Story = StoryObj<typeof Button>;
 
export const Variant1: Story = {
  // 👇 This story will not appear in Storybook's sidebar or docs page
  tags: ['!dev', '!autodocs'],
  args: { variant: 1 },
};
 
export const Variant2: Story = {
  // 👇 This story will not appear in Storybook's sidebar or docs page
  tags: ['!dev', '!autodocs'],
  args: { variant: 2 },
};
 
export const Combo: Story = {
  // 👇 This story should not be tested, but will appear in the sidebar and docs page
  tags: ['!test'],
  render: () => (
    <>
      <Button variant={1} />
      <Button variant={2} />
    </>
  ),
};