命名组件和层级结构

观看视频教程

Storybook 提供了一种强大的方式来组织你的 stories，为你提供必要的工具来根据你组织的需要和偏好对你的 stories 进行分类、搜索和过滤。

结构和层级结构

在组织你的 Storybook 时，有两种方法来构建你的 stories：隐式和显式。隐式方法依赖于你的 stories 的物理位置来将它们放置在侧边栏中，而显式方法涉及使用 title 参数来放置 story。

Storybook sidebar hierarchy

根据你构建 Storybook 的方式，你可以看到 story 层级结构由多个部分组成

类别：Storybook 生成的 stories 和文档页面的顶层分组
文件夹：一个中层组织单元，在侧边栏中对组件和 stories 进行分组，代表你应用程序的功能或部分
组件：一个低层组织单元，代表 story 正在测试的组件
文档：组件的自动生成的文档页面
Story：测试特定组件状态的单个 story

命名 stories

在创建你的 stories 时，你可以显式地使用 title 参数来定义 story 在侧边栏中的位置。它也可以用来分组相关的组件在一个可展开的界面中，以帮助 Storybook 组织，为你的用户提供更直观的体验。例如

Button.stories.ts

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  /* 👇 The title prop is optional.
   * See https://storybook.org.cn/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Button',
  component: Button,
};
 
export default meta;

产生这个结果

Stories hierarchy without paths

分组

也可以在一个可展开的界面中对相关组件进行分组，以帮助 Storybook 组织。为此，请使用 / 作为分隔符

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  /* 👇 The title prop is optional.
   * See https://storybook.org.cn/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Design System/Atoms/Button',
  component: Button,
};
 
export default meta;

CheckBox.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { CheckBox } from './Checkbox';
 
const meta: Meta<typeof CheckBox> = {
  /* 👇 The title prop is optional.
   * See https://storybook.org.cn/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Design System/Atoms/Checkbox',
  component: CheckBox,
};
 
export default meta;

产生这个结果

Stories hierarchy with paths

根目录

默认情况下，顶层分组将在 Storybook UI 中显示为 “root”（即，大写的、不可展开的项目）。如果你需要，你可以配置 Storybook 并禁用此行为。如果你需要为你的用户提供简化的体验，这将非常有用；然而，如果你有一个由多个组件 stories 组成的庞大 Storybook，我们建议根据文件层级结构命名你的组件。

单 story 提升

单 story 组件（即，没有同级的组件 stories），其显示名称与组件名称（title 的最后一部分）完全匹配，将自动提升以替换 UI 中的父组件。例如

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button as ButtonComponent } from './Button';
 
const meta: Meta<typeof ButtonComponent> = {
  /* 👇 The title prop is optional.
   * See https://storybook.org.cn/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'Design System/Atoms/Button',
  component: ButtonComponent,
};
 
export default meta;
type Story = StoryObj<typeof ButtonComponent>;
 
// This is the only named export in the file, and it matches the component name
export const Button: Story = {};

Stories hierarchy with single story hoisting

由于 story 导出是自动 “start cased” 的（myStory 变为 "My Story"），你的组件名称应该与之匹配。或者，你可以使用 myStory.storyName = '...' 覆盖 story 名称以匹配组件名称。

排序 stories

开箱即用，Storybook 根据 stories 的导入顺序对其进行排序。但是，你可以自定义此模式以适应你的需求，并通过将 storySort 添加到你的 preview.js 文件中的 options 参数来提供更直观的体验。

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    options: {
      // The `a` and `b` arguments in this function have a type of `import('@storybook/types').IndexEntry`. Remember that the function is executed in a JavaScript environment, so use JSDoc for IntelliSense to introspect it.
      storySort: (a, b) =>
        a.id === b.id ? 0 : a.id.localeCompare(b.id, undefined, { numeric: true }),
    },
  },
};
 
export default preview;

除了唯一的 story 标识符，你还可以使用 title、name 和导入路径，使用 storySort 函数对你的 stories 进行排序。

storySort 也可以接受一个配置对象。

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    options: {
      storySort: {
        method: '',
        order: [],
        locales: '',
      },
    },
  },
};
 
export default preview;

字段	类型	描述	必需	默认值	示例
method	String	告诉 Storybook stories 的显示顺序	否	Storybook 配置	`'alphabetical'`
order	Array	要显示的 stories，按提供的名称排序	否	空数组 `[]`	`['Intro', 'Components']`
includeNames	Boolean	在排序计算中包含 story 名称	否	`false`	`true`
locales	String	需要显示的区域设置	否	系统区域设置	`en-US`

要按字母顺序排序你的 stories，请将 method 设置为 'alphabetical'，并可选择设置 locales 字符串。要使用自定义列表排序你的 stories，请使用 order 数组；不在 order 列表中的 stories 将显示在列表项之后。

order 数组可以接受嵌套数组来排序二级 story 类型。例如

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    options: {
      storySort: {
        order: ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components'],
      },
    },
  },
};
 
export default preview;

这将导致以下 story 排序

Intro 然后是 Intro/* stories
Pages story
Pages/Home 和 Pages/Home/* stories
Pages/Login 和 Pages/Login/* stories
Pages/Admin 和 Pages/Admin/* stories
Pages/* stories
Components 和 Components/* stories
所有其他 stories

如果你希望特定类别排序到列表末尾，你可以在你的 order 数组中插入一个 * 来指示 “所有其他 stories” 应该放在哪里

.storybook/preview.ts

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    options: {
      storySort: {
        order: ['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components', '*', 'WIP'],
      },
    },
  },
};
 
export default preview;

在此示例中，WIP 类别将显示在列表的末尾。

请注意，order 选项独立于 method 选项； stories 首先按 order 数组排序，然后按 method: 'alphabetical' 或默认的 configure() 导入顺序排序。