侧边栏 & URL

观看视频教程

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

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,
  },
});

故事的永久链接

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

考虑以下故事

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。

可以手动设置故事的 id，如果您希望重命名故事而不破坏永久链接，这将非常有用。假设您想将层级结构中的位置更改为 OtherFoo/Bar 并且故事名称更改为 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 作为一项实验性功能，允许您更简洁地编写故事。假设您已经使用此格式编写故事。在这种情况下，您可以从默认导出中省略 title 元素，并允许 Storybook 根据文件物理位置自动推断它。例如，给定以下配置和故事

.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 加载时，故事可以在侧边栏中显示为 components/My Component。

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

src/components/Button/Button.stories.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)),
  },
});

除了改进故事文件名的大小写外，还引入了一种新的启发式方法，在文件名与目录名相同或名为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 以基于配置对象加载您的故事，包括titlePrefix，Storybook 会自动将所有标题前缀添加到匹配的故事中。例如，假设您有以下配置

.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 为所有匹配的故事生成标题时，它们将保留Custom前缀。

故事索引器

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

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