文档块

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 中使用文档块时，也可以使用其属性自定义它

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

可用块

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

ArgTypes

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

画布

画布 块是 故事 的包装器，它具有一个工具栏，允许您与内容交互，同时自动提供所需的 源代码 代码片段。

调色板

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

控件

控件 块可用于显示给定故事的动态参数表，作为记录其界面的一种方式，并允许您更改（单独）呈现的故事的参数（通过 故事 或 画布 块）。

描述

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

图标库

图标库 块允许您快速记录与您的项目相关的所有图标，并在整齐的网格中显示。

降价

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

元数据

元数据 块用于 附加 组件的故事列表旁边的自定义 MDX 文档页面。它不呈现任何内容，但在 MDX 文件中发挥两种作用

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

主要

主要 块在 故事 块中显示主要（故事文件中第一个定义）的故事。它通常在文档条目中的标题下方立即呈现。

源代码

源代码 块用于直接呈现源代码片段。

故事

故事 块呈现故事文件中所有故事的完整集合。

故事

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

在 Storybook 文档中，您可以使用 故事 块在 MDX 文件的上下文中呈现来自 CSF 文件的所有故事，并应用所有注释（参数、参数、加载程序、装饰器、播放函数）。

副标题

副标题 块可以用作文档条目的辅助标题。

标题

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

排版

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

无样式

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

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.

创建自己的文档块

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

故障排除

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

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 文档的更多信息

• 自动文档 用于为您的故事创建文档
• MDX 用于自定义您的文档
• 文档块 用于创作您的文档
• 发布文档 用于自动化发布文档的过程