侧边栏 & URL

观看视频教程

Storybook 的侧边栏列出了按组件分组的所有 Stories。当组件很多时，您可能也希望对这些组件进行分组。为此，您可以在 CSF 文件的 title 中添加 / 分隔符，Storybook 将根据常见前缀将 Stories 分组。

Storybook sidebar anatomy

我们建议使用一种镜像组件文件系统路径的嵌套方案。例如，如果您有一个文件 components/modals/Alert.js，将 CSF 文件命名为 components/modals/Alert.stories.js，标题为 Components/Modals/Alert。

根目录

默认情况下，Storybook 会将您的顶级节点视为“根目录”。根目录在 UI 中显示为层级结构的“部分”。较低级别的组将显示为文件夹。

Storybook sidebar story roots

如果您更喜欢将顶级节点显示为文件夹而不是根目录，可以在 ./storybook/manager.js 中将 sidebar.showRoots 选项设置为 false。

./storybook/manager.js

import { addons } from 'storybook/manager-api';
 
addons.setConfig({
  sidebar: {
    showRoots: false,
  },
});

Stories 的永久链接

默认情况下，Storybook 会根据组件标题和 Story 名称为每个 Story 生成一个 id。此 id 特别用于每个 Story 的 URL，该 URL 可以作为永久链接（主要在您发布 Storybook 时）。

考虑以下 Story

FooBar.stories.ts|tsx

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

Storybook 的 ID 生成逻辑会给它一个 id foo-bar--baz，因此链接将是 ?path=/story/foo-bar--baz。

可以手动设置 Story 的 id，这对于在重命名 Stories 时不会破坏永久链接非常有用。假设您想将层级结构中的位置更改为 OtherFoo/Bar，并将 Story 名称更改为 Moo。以下是操作方法：

FooBar.stories.ts|tsx

// 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 { Foo } from './Foo';
 
const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.org.cn/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  title: 'OtherFoo/Bar',
  component: Foo,
  id: 'Foo/Bar', // Or 'foo-bar' if you prefer
} satisfies Meta<typeof Foo>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Baz: Story = {
  name: 'Insert name here',
};

如果提供了 id，Storybook 在生成 ID 时会优先使用 id 而不是标题；在显示时会优先使用 story.name 而不是导出键。

CSF 3.0 自动标题

Storybook 6.4 引入了 CSF 3.0 作为实验性功能，让您可以更简洁地编写 Stories。假设您已经在使用此格式编写 Stories。在这种情况下，您可以从默认导出中省略 title 元素，让 Storybook 根据文件的物理位置自动推断。例如，给定以下配置和 Story：

.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'],
};
 
export default config;

Storybook 加载时，Story 可以显示在侧边栏中为 components/My Component。

自动标题适用于显式标题选项，例如组件的 title 和 Story 的 name。

src/components/Button/Button.stories.ts|tsx

// 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 = {
  // Sets the name for the stories container
  title: 'components/Button',
  // The component name will be used if `title` is not set
  component: Button,
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
// The story variable name will be used if `name` is not set
const Primary: Story = {
  // Sets the name for that particular story
  name: 'Primary',
  args: {
    label: 'Button',
  },
};

自动标题文件名大小写

从 Storybook 6.5 开始，自动生成的 Story 标题不再依赖 Lodash 的 startCase。相反，文件名的大小写会被保留，从而可以更好地控制 Story 标题。例如，components/My Component 将被定义为 components/MyComponent。

如果需要，您可以通过添加以下配置来恢复到以前的模式：

.storybook/manager.js

import { addons } from 'storybook/manager-api';
 
import startCase from 'lodash/startCase.js';
 
addons.setConfig({
  sidebar: {
    renderLabel: ({ name, type }) => (type === 'story' ? name : startCase(name)),
  },
});

除了改进 Story 文件名的大小写之外，还引入了一种新的启发式方法，用于删除文件名与目录名相同或文件名是 index.stories.js|ts 时出现的冗余名称。例如，之前 components/MyComponent/MyComponent.stories.js 在侧边栏中被定义为 Components/MyComponent/MyComponent。现在它将被定义为 Components/MyComponent。

如果您需要保留命名方案，可以将 title 元素添加到默认导出中。例如：

components/MyComponent/MyComponent.stories.ts|tsx

// 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 { MyComponent } from './MyComponent';
 
const meta = {
  /* 👇 The title prop is optional.
   * See https://storybook.org.cn/docs/configure/#configure-story-loading
   * to learn how to generate automatic titles
   */
  component: MyComponent,
  title: 'components/MyComponent/MyComponent',
} satisfies Meta<typeof MyComponent>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Default: Story = {
  args: {
    something: 'Something else',
  },
};

自动标题前缀

此外，如果您通过配置对象自定义 Storybook 来加载您的 Stories（包括 titlePrefix），Storybook 会自动为所有匹配的 Stories 的标题添加前缀。例如，假设您有以下配置：

.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: [
    {
      directory: '../src',
      titlePrefix: 'Custom', // 👈 Configure the title prefix
    },
  ],
};
 
export default config;

当 Storybook 为所有匹配的 Stories 生成标题时，它们将保留 Custom 前缀。

Story Indexers

Story Indexers 是一组由 Storybook 使用的启发式方法，用于根据给定的 glob 模式抓取文件系统，查找匹配的 Stories，然后用于生成一个 index.json（之前是 stories.json）文件，负责用必要的信息填充侧边栏。默认情况下，此启发式方法将查找包含以下方案的文件：*.stories.@(js|jsx|mjs|ts|tsx)。

您可以提供自己的 indexer，以包含使用不同命名约定的 Stories、调整除前缀之外的自动标题生成等许多用例。欲了解更多信息，请参阅 Story Indexers API 参考。