文档块

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

¥Storybook offers several doc blocks to help document your components and other aspects of your project.

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

¥There are two common ways to use doc blocks in Storybook, within MDX and as part of the docs page template.

在 MDX 内

¥Within MDX

这些块在 Storybook 的 MDX 文档 中最常用：

¥The blocks are most commonly used within Storybook's MDX documentation:

{/* 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} />
 
{/* ... */}

自定义自动文档页面

¥Customizing the automatic docs page

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

¥The blocks are also used to define the page template for automatics docs. For example, here's the default template:

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

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

¥If you override the default page template, you can similarly use Doc Blocks to build the perfect documentation page for your project.

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

¥Note that some doc blocks render other blocks. For example, the <Stories /> block expands to:

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

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

¥As a result, for example, customizing the Source block via parameters (see next section) will also affect the Source blocks rendered as part of Canvas blocks.

自定义文档块

¥Customizing doc blocks

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

¥In both use cases (MDX and automatic docs), many of the doc blocks can be customized via parameters.

例如，你可以通过 Storybook 从所有 Controls 表中过滤出 style 属性：

¥For example, you can filter out the style prop from all Controls tables through your 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;

以下可用块列表中标记了通过参数接受自定义的块。

¥The blocks that accept customization via parameters are marked in the list of available blocks below.

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

¥When using a doc block in MDX, it can also be customized with its props:

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

可用块

¥Available blocks

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

¥Each block has a dedicated API reference page detailing usage, available options, and technical details.

ArgTypes

ArgTypes 块可用于显示给定组件的 参数类型 静态表，作为记录其接口的一种方式。

¥The ArgTypes block can be used to show a static table of arg types for a given component as a way to document its interface.

画布

¥Canvas

Canvas 块是 Story 的封装器，具有一个工具栏，可让你与其内容进行交互，同时自动提供所需的 Source 片段。

¥The Canvas block is a wrapper around a Story, featuring a toolbar that allows you to interact with its content while automatically providing the required Source snippets.

ColorPalette

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

¥The ColorPalette block allows you to document all color-related items (e.g., swatches) used throughout your project.

控件

¥Controls

Controls 块可用于显示给定故事的动态参数表，作为记录其界面的方式，并允许你更改（单独）渲染故事的参数（通过 Story 或 Canvas 块）。

¥The Controls block can be used to show a dynamic table of args for a given story, as a way to document its interface, and to allow you to change the args for a (separately) rendered story (via the Story or Canvas blocks).

描述

¥Description

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

¥The Description block displays the description for a component, story, or meta obtained from their respective JSDoc comments.

IconGallery

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

¥The IconGallery block lets you quickly document all icons associated with your project, displayed in a neat grid.

Markdown

Markdown 块允许你导入和包含纯 markdown 到 MDX 文件。

¥The Markdown block allows you to import and include plain markdown in your MDX files.

元

¥Meta

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

¥The Meta block is used to attach a custom MDX docs page alongside a component’s list of stories. It doesn’t render any content but serves two purposes in an MDX file:

• 将 MDX 文件附加到组件及其故事，或者

  ¥Attaches the MDX file to a component and its stories, or

• 控制侧边栏中未附加文档条目的位置。

  ¥Controls the location of the unattached docs entry in the sidebar.

主要

¥Primary

Primary 块在 Story 块中显示主要（在故事文件中首先定义）故事。它通常在文档条目的标题下立即渲染。

¥The Primary block displays the primary (first defined in the stories file) story in a Story block. It is typically rendered immediately under the title in a docs entry.

来源

¥Source

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

¥The Source block is used to render a snippet of source code directly.

故事

¥Stories

Stories 块在故事文件中渲染故事的完整集合。

¥The Stories block renders the full collection of stories in a stories file.

故事

¥Story

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

¥Stories (component tests) are Storybook's fundamental building blocks.

在 Storybook Docs 中，你可以在 MDX 文件的上下文中从 CSF 文件渲染任何故事，并使用 Story 块应用所有注释（参数、args、加载器、装饰器、播放函数）。

¥In Storybook Docs, you can render any of your stories from your CSF files in the context of an MDX file with all annotations (parameters, args, loaders, decorators, play function) applied using the Story block.

副标题

¥Subtitle

Subtitle 块可作为文档条目的辅助标题。

¥The Subtitle block can serve as a secondary heading for your docs entry.

标题

¥Title

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

¥The Title block serves as the primary heading for your docs entry. It is typically used to provide the component or page name.

排版

¥Typeset

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

¥The Typeset block helps document the fonts used throughout your project.

未样式化

¥Unstyled

Unstyled 块是一个独特的块，无论在何处添加 Storybook，它都会在 MDX 文档中禁用其默认样式。

¥The Unstyled block is a unique block that disables Storybook's default styling in MDX docs wherever it is added.

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

¥By default, most elements (like h1, p, etc.) in docs have a few default styles applied to ensure the docs look good. However, sometimes you might want some of your content not to have these styles applied. In those cases, wrap the content with the Unstyled block to remove the default styles.

制作自己的 Doc Blocks

¥Make your own Doc Blocks

Storybook 还提供了 useOf 钩子，使你更容易创建像内置块一样功能的自己的块。

¥Storybook also provides a useOf hook to make it easier to create your own blocks that function like the built-in blocks.

故障排除

¥Troubleshooting

为什么我不能在我的故事中使用 Doc Blocks？

¥Why can't I use the Doc Blocks inside my stories?

Storybook 的 Doc Blocks 是高度可定制且有用的构建块，可帮助你构建自定义文档。虽然它们中的大多数都允许你使用参数自定义它们或全局创建自定义 文档模板，但它们主要设计用于 MDX 文件。例如，如果你尝试按如下方式将 ColorPalette 块添加到你的故事中，则当故事在 Storybook 中加载时，你会收到一条错误消息。

¥Storybook's Doc Blocks are highly customizable and helpful building blocks to assist you with building your custom documentation. Although most of them enable you to customize them with parameters or globally to create custom documentation templates, they are primarily designed for MDX files. For example, if you try to add the ColorPalette block to your stories as follows, you'll get an error message when the story loads in 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 文档的更多信息

¥Learn more about Storybook documentation

• 自动文档 用于为你的故事创建文档

  ¥Autodocs for creating documentation for your stories

• MDX 用于自定义你的文档

  ¥MDX for customizing your documentation

• 用于编写文档的文档块

  ¥Doc Blocks for authoring your documentation

• 发布文档 用于自动化发布文档的过程

  ¥Publishing docs to automate the process of publishing your documentation