侧边栏 & URLS

观看视频教程

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: Meta<typeof Foo> = {
  /* 👇 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,
};
 
export default meta;
type Story = StoryObj<typeof Foo>;
 
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 name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Foo } from './Foo';
 
const meta: Meta<typeof Foo> = {
  /* 👇 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
};
 
export default meta;
type Story = StoryObj<typeof Foo>;
 
export const Baz: Story = {
  name: 'Insert name here',
};

如果提供，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-webpack5, vue3-vite)
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 name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<Button> = {
  // Sets the name for the stories container
  title: 'components/Button',
  // The component name will be used if `title` is not set
  component: Button,
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
// 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 name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { MyComponent } from './MyComponent';
 
const meta: Meta<typeof MyComponent> = {
  /* 👇 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',
};
 
export default meta;
type Story = StoryObj<typeof MyComponent>;
 
export const Default: Story = {
  args: {
    something: 'Something else',
  },
};

自动标题前缀

此外，如果您自定义 Storybook 以基于配置对象（包括 configuration object）加载 stories，则 Storybook 会自动将所有标题前缀添加到匹配的 stories。例如，假设您有以下配置

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
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 索引器

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

您可以提供自己的索引器，以包含具有不同命名约定的 stories，调整超出前缀的自动标题生成，以及许多其他用例。有关更多信息，请参阅 Story 索引器 API 参考。