文档块

Storybook 提供了几个文档块，以帮助记录您的组件和项目的其他方面。

在 Storybook 中，有两种常用的方法来使用文档块：在 MDX 中以及作为文档页面模板的一部分。

在 MDX 中

这些块最常用于 Storybook 的 MDX 文档

{/* ButtonDocs.mdx */}
 
import { Meta, Primary, Controls, Story } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
 
<Meta of={ButtonStories} />
 
# Button
 
A button is ...
 
<Primary />
 
## Props
 
<Controls />
 
## Stories
 
### Primary
 
A button can be of primary importance.
 
<Story of={ButtonStories.Primary} />
 
A button can be of secondary importance.
 
<Story of={ButtonStories.Secondary} />
 
{/* ... */}

自定义自动文档页面

这些块也用于为 自动文档定义页面模板。例如，这是默认模板

import { Title, Subtitle, Description, Primary, Controls, Stories } from '@storybook/blocks';
 
export const autoDocsTemplate = () => (
  <>
    <Title />
    <Subtitle />
    <Description />
    <Primary />
    <Controls />
    <Stories />
  </>
);

如果您覆盖默认页面模板，您可以类似地使用文档块为您的项目构建完美的文档页面。

请注意，一些文档块会渲染其他块。例如，<Stories /> 块展开为

## Stories
 
<Canvas>
  ### Story name
  <Description />
  <Story />
  <Source />
</Canvas>
 
{/* ... repeat <Canvas> for each story */}

因此，例如，通过参数（见下一节）自定义 Source 块也将影响作为 Canvas 块一部分渲染的 Source 块。

自定义文档块

在这两种用例（MDX 和自动文档）中，许多文档块可以通过 参数进行自定义。

例如，您可以从所有 Controls 表格中过滤掉 style 属性，通过您的 Storybook

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

接受通过参数自定义的块在下面提供的可用块列表中标记。

在 MDX 中使用文档块时，也可以使用其 props 进行自定义

<Controls exclude={['style']}>

可用块

每个块都有一个专门的 API 参考页面，详细说明了用法、可用选项和技术细节。

ArgTypes

ArgTypes 块可用于显示给定组件的 arg types 的静态表格，以此来记录其接口。

Canvas

Canvas 块是 Story 的包装器，具有一个工具栏，允许您与其内容进行交互，同时自动提供所需的 Source 代码片段。

ColorPalette

ColorPalette 块允许您记录项目中使用的所有与颜色相关的项（例如，色板）。

Controls

Controls 块可用于显示给定 story 的 args 的动态表格，以此来记录其接口，并允许您更改（单独）渲染的 story 的 args（通过 Story 或 Canvas 块）。

Description

Description 块显示从组件、story 或元数据的 JSDoc 注释中获得的描述。

IconGallery

IconGallery 块让您可以快速记录与项目关联的所有图标，并以整洁的网格显示。

Markdown

Markdown 块允许您在 MDX 文件中导入和包含纯 markdown。

Meta

Meta 块用于附加自定义 MDX 文档页面以及组件的 story 列表。它不渲染任何内容，但在 MDX 文件中具有两个用途

• 将 MDX 文件附加到组件及其 stories，或
• 控制边栏中未附加文档条目的位置。

Primary

Primary 块在 Story 块中显示主要的（在 stories 文件中定义的第一个）story。它通常在文档条目的标题下立即渲染。

Source

Source 块用于直接渲染源代码片段。

Stories

Stories 块渲染 stories 文件中的完整 stories 集合。

Story

Stories（组件测试）是 Storybook 的基本构建块。

在 Storybook 文档中，您可以使用 Story 块，在 MDX 文件的上下文中渲染来自 CSF 文件的任何 story，并应用所有注解（参数、args、加载器、装饰器、Play 函数）。

Subtitle

Subtitle 块可以用作文档条目的二级标题。

Title

Title 块用作文档条目的主要标题。它通常用于提供组件或页面名称。

Typeset

Typeset 块有助于记录项目中使用的字体。

Unstyled

Unstyled 块是一个独特的块，它在添加到的任何 MDX 文档中禁用 Storybook 的默认样式。

默认情况下，文档中的大多数元素（如 h1、p 等）都应用了一些默认样式，以确保文档看起来不错。但是，有时您可能希望某些内容不应用这些样式。在这些情况下，请使用 Unstyled 块包装内容以删除默认样式。

制作您自己的文档块

Storybook 还提供了一个 useOf hook，使您可以更轻松地创建自己的块，使其功能类似于内置块。

故障排除

为什么我不能在我的 stories 中使用文档块？

Storybook 的文档块是高度可定制且有用的构建块，可帮助您构建自定义文档。尽管它们中的大多数都允许您使用参数或全局方式自定义它们以创建自定义文档模板，但它们主要为 MDX 文件设计。例如，如果您尝试将 ColorPalette 块添加到您的 stories 中，如下所示，当 story 在 Storybook 中加载时，您将收到错误消息。

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { ColorItem, ColorPalette } from '@storybook/blocks';
 
import { MyComponent } from './MyComponent';
 
const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
};
 
export default meta;
type Story = StoryObj<typeof MyComponent>;
 
const theme = {
  colors: {
    primaryDark: {
      value: '#1C1C1C',
    },
    primaryRegular: {
      value: '#363636',
    },
    primaryLight1: {
      value: '#4D4D4D',
    },
    primaryLight2: {
      value: '#878787',
    },
    primaryLight3: {
      value: '#D1D1D1',
    },
    primaryLight4: {
      value: '#EDEDED',
    },
  },
};
 
// ❌ Don't use the Doc Blocks inside your stories. It will break Storybook with a cryptic error.
export const Colors: Story = {
  render: () => (
    <ColorPalette>
      {Object.entries(theme.colors).map(([key, { value }]) => (
        <ColorItem
          colors={{
            [key]: value,
          }}
          key={key}
          subtitle={`theme.colors.${key}`}
          title={key}
        />
      ))}
    </ColorPalette>
  ),
};

了解更多关于 Storybook 文档的信息

• 自动文档，用于为您的 stories 创建文档
• MDX，用于自定义您的文档
• 文档块，用于编写您的文档
• 发布文档，以自动化发布文档的过程