Storybook 文档块(Doc Blocks)完全指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00550/article/details/148323282

Storybook 文档块(Doc Blocks)完全指南

storybook 项目地址: https://gitcode.com/gh_mirrors/sto/storybook

前言

在现代前端开发中，组件文档化已成为不可或缺的一环。Storybook 作为业界领先的 UI 组件开发环境，提供了一套强大的文档系统，其中"文档块"(Doc Blocks)是其核心功能之一。本文将深入解析 Storybook 文档块的使用方法、定制技巧以及最佳实践。

什么是文档块？

文档块是 Storybook 提供的一系列预构建的 React 组件，专门用于创建和组织组件文档。它们可以：

自动生成组件 API 文档
展示交互式示例
呈现源代码片段
组织多故事展示
提供样式指南元素

文档块的两种使用方式

1. 在 MDX 文件中使用

MDX 是 Markdown 和 JSX 的结合体，允许你在 Markdown 中直接嵌入 React 组件。这是使用文档块最常见的方式：

import { Meta, Primary, Controls, Story } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';

<Meta of={ButtonStories} />

# 按钮组件

按钮是用户界面的基本交互元素...

<Primary />

## 属性说明

<Controls />

## 示例故事

### 主要按钮

用于表示最重要的操作。

<Story of={ButtonStories.Primary} />

### 次要按钮

用于表示次要操作。

<Story of={ButtonStories.Secondary} />

2. 自定义自动文档页面模板

Storybook 可以自动为组件生成文档页面，你可以通过自定义模板来改变这些页面的结构：

import { Title, Subtitle, Description, Primary, Controls, Stories } from '@storybook/blocks';

export const autoDocsTemplate = () => (
  <>
    <Title />
    <Subtitle />
    <Description />
    <Primary />
    <Controls />
    <Stories />
  </>
);

核心文档块详解

基础信息块

Meta: 将 MDX 文件与组件及其故事关联
Title: 文档主标题（通常显示组件名）
Subtitle: 文档副标题
Description: 显示从 JSDoc 注释中提取的描述

组件展示块

Primary: 显示主要（第一个定义的）故事
Story: 渲染特定故事
Stories: 渲染所有故事集合
Canvas: 故事容器，包含工具栏和源代码

API 文档块

Controls: 动态参数控制表
ArgTypes: 静态参数类型表
Source: 显示源代码片段

设计系统块

ColorPalette: 颜色调色板展示
IconGallery: 图标集合展示
Typeset: 字体排版展示

高级定制技巧

通过参数定制文档块

大多数文档块支持通过 Storybook 参数进行全局定制：

// .storybook/preview.js
export const parameters = {
  docs: {
    controls: {
      exclude: ['style', 'className'] // 排除特定属性
    }
  }
};

块级属性定制

在 MDX 中可以直接为文档块指定属性：

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

嵌套文档块

某些文档块会渲染其他块，例如 <Stories /> 实际上会渲染：

## Stories

<Canvas>
  ### Story name
  <Description />
  <Story />
  <Source />
</Canvas>

创建自定义文档块

Storybook 提供了 useOf hook，让你能够创建自己的文档块：

import { useOf } from '@storybook/blocks';

function CustomBlock() {
  const { story } = useOf('story', ['story']);
  return <div>自定义故事块: {story.name}</div>;
}