标签	默认应用？	描述
`dev`	是	带有 `dev` 标签的故事会显示在 Storybook 的侧边栏中。
`test`	是	带有 `test` 标签的故事包含在测试运行器或 Vitest 插件运行中。
`autodocs`	否	带有 `autodocs` 标签的故事包含在文档页面运行中。如果 CSF 文件不包含至少一个标有 `autodocs` 的故事，则该组件将不会生成文档页面。
`play-fn`	否	自动应用于已定义播放函数的故事。
`test-fn`	否	自动应用于使用 CSF 工厂上的实验性 `.test` 方法定义的测试。

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

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

自定义标签

¥Custom tags

你不仅限于使用内置标签。自定义标签在 Storybook 的侧边栏层次结构之上提供了一个灵活的分类层。示例用途可能包括：

¥You're not limited to the built-in tags. Custom tags enable a flexible layer of categorization on top of Storybook's sidebar hierarchy. 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

创建自定义标签有两种方法：

¥There are two ways to create a custom tag:

如下所述，将其应用于故事、组件（元数据）或项目（preview.js|ts）。

¥Apply it to a story, component (meta), or project (preview.js|ts) as described below.
在 Storybook 配置文件 (.storybook/main.js|ts) 中定义它，以提供更多配置选项，例如默认的筛选选择。

¥Define it in your Storybook configuration file (.storybook/main.js|ts) to provide more configuration options, like default filter selection.

例如，要定义一个默认情况下在侧边栏中排除的 "experimental" 标签，你可以将以下内容添加到 Storybook 配置中：

¥For example, to define an "experimental" tag that is excluded by default in the sidebar, you can add this to your Storybook config:

.storybook/main.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  tags: {
    // 👇 Define a custom tag named "experimental"
    experimental: {
      defaultFilterSelection: 'exclude', // Or 'include'
    },
  },
};
 
export default config;

如果 defaultFilterSelection 设置为 include，则带有此标签的故事将被选中并包含在筛选菜单中。如果设置为 exclude，则带有此标签的故事将被排除，必须通过在侧边栏筛选菜单中选择该标签才能显式包含。如果未设置，则该标签没有默认选项。

¥If defaultFilterSelection is set to include, stories with this tag are selected as included in the filter menu. If set to exclude, stories with this tag are selected as excluded, and must be explicitly included by selecting the tag in the sidebar filter menu. If not set, the tag has no default selection.

你还可以使用 tags 配置来修改内置标签的配置。

¥You can also use the tags configuration to alter the configuration of built-in tags.

应用标签

¥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:

.storybook/preview.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Preview } from '@storybook/your-framework';
 
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:

Button.stories.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta = {
  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'],
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
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:

Button.stories.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta = {
  component: Button,
  // 👇 Applies to all stories in this file
  tags: ['stable'],
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
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 the sidebar by tags

内置标签和自定义标签都可以在 Storybook 的侧边栏中作为过滤器使用。在过滤器中选择一个标签将使侧边栏仅显示带有该标签的故事。选择多个标签将显示包含任意这些标签的故事。

¥Both built-in and custom tags are available 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.

在筛选菜单中，点击标签的“排除”按钮，即可从侧边栏中排除带有该标签的故事。你可以排除多个标签，包含这些标签的故事将被排除。你还可以混合使用包含和排除功能。

¥Pressing the Exclude button for a tag in the filter menu excludes stories with that tag from the sidebar. You can exclude multiple tags, and stories with any of those tags will be excluded. You can also mix inclusion and exclusion.

如果未选择任何标签，则会显示所有故事。

¥When no tags are selected, all stories are shown.

在本例中，已排除 experimental 标签，并包含文档标签 (autodocs)，因此仅显示带有 autodocs 标签但不带有 experimental 标签的故事。

¥In this example, the experimental tag has been excluded and the Documentation tag (autodocs) has been included, so only stories tagged with autodocs but not experimental are shown.

Filtering by tags

按标签过滤是专注于部分故事的有效方法，尤其是在大型 Storybook 项目中。搜索时，会首先应用筛选器，因此搜索结果仅限于当前筛选的标签。

¥Filtering by tags is a powerful way to focus on a subset of stories, especially in large Storybook projects. When searching, the filter is applied first, so search results are limited to the currently filtered tags.

秘诀

¥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.

Button.stories.ts

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

Button.stories.tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta = {
  component: Button,
} satisfies Meta<typeof Button>;
export default meta;
 
type Story = StoryObj<typeof meta>;
 
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} />
    </>
  ),
};

不占用侧边栏空间的测试用例

¥Test cases that don't clutter the sidebar

（⚠️ 实验性功能：虽然此 API 适用于所有标签，但内置的 _test 标签仍处于实验阶段）

¥(⚠️ Experimental: While this API is available for all tags, the built-in _test tag is experimental)

如果你使用的是 CSF 工厂上的实验性 .test 方法，你可以更改 _test 标签的默认行为，使其默认情况下从侧边栏中排除测试。此功能可减少侧边栏的杂乱，同时仍允许你对所有故事运行测试，或调整筛选器以在需要时显示测试。

¥If you're using the experimental .test method on CSF Factories, you can alter the default behavior of the _test tag to exclude tests from the sidebar by default. This reduces clutter in the sidebar while still allowing you to run tests for all stories, or adjust the filter to show tests when needed.

.storybook/main.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  tags: {
    // 👇 Adjust the default configuration of this tag
    _test: {
      defaultFilterSelection: 'exclude',
    },
  },
};
 
export default config;