dumi 详解：专为 UI 组件库研发而生的静态站点框架

前端小小栈
70 阅读3分钟

dumi 简介

dumi 是由 Umi 团队（蚂蚁集团）开发的专为 UI 组件库研发而生的静态站点框架。它与 father（构建工具）配合，提供一站式组件开发体验：开发者专注于组件代码和文档编写，dumi 负责生成交互式文档站点、Demo 预览、API 表格等。常用于 React 组件库（如 Ant Design 系列），支持 TypeScript，开箱即用，极大提升组件库文档维护效率。

官方文档：d.umijs.org/

dumi 的核心特点（Features）

dumi 的设计理念是“为组件研发而生”，以下是其主要特点：

  • 开箱即用：无需复杂配置，即可开始组件开发和文档编写。
  • 丰富的 Markdown 扩展：
    • 支持在 .md 文件中直接嵌入组件 Demo（实时预览、可交互）。
    • 外部 Demo 支持（从其他文件引入）。
    • 自动高亮代码、拷贝代码、在线运行（CodeSandbox）。
  • 自动生成组件 API 表格：基于 TypeScript 类型定义（react-docgen-typescript）自动解析 Props，生成 <API> 表格，无需手动维护。
  • 约定式路由 + 配置式路由：自动根据目录结构生成导航和路由，支持自定义分组。
  • 主题自定义：内置默认主题，支持本地主题包或第三方主题（如 dumi-theme-lobehub、dumi-theme-antd-style），轻松调整样式、布局。
  • 移动端支持：内置高清渲染方案（HD），适合移动端组件库研发。
  • 资产元数据（Assets Metadata）：组件、Hook 等资产数据化，便于下游工具集成。
  • 开发模式：
    • 文档模式（lib）：专注组件文档。
    • 站点模式（site）：适合完整官网（如添加首页、指南）。
  • 性能优化：集成 Umi 4 的 MFSU、esbuild、SWC 等，编译速度快。
  • 与 father 集成：一键打包 npm 包 + 生成静态文档站点。

如何使用 dumi 开发 UI 组件库

1. 初始化项目

推荐使用官方脚手架：

npx create-dumi

选择模板：

  • React Library：适合组件库（推荐）。
  • Static Site：纯文档站点。
  • Theme Package：主题包开发。

初始化后目录结构大致如下：

├── docs              # 普通文档（如指南、首页）
│   └── index.md
├── src               # 组件源码
│   ├── Button        # 示例组件
│   │   ├── index.tsx # 组件实现
│   │   ├── style.less
│   │   └── index.md  # 组件专属文档（Demo + API）
│   └── index.ts      # 组件库入口（export *）
├── .dumirc.ts        # dumi 配置
└── .fatherrc.ts      # father 打包配置

2. 编写组件与文档

  • 组件代码（src/Button/index.tsx）：
import React from 'react';

export interface ButtonProps {
  type?: 'primary' | 'default';
  children: React.ReactNode;
}

const Button: React.FC<ButtonProps> = ({ type = 'default', children }) => {
  return <button className={`btn-${type}`}>{children}</button>;
};

export default Button;
  • 组件文档（src/Button/index.md）：
--- 
title: Button 按钮   # 前置元数据，用于导航标题
group: 基础组件      # 分组
---

## Demo

<code src="./__tests__/basic.tsx">基础用法</code>  <!-- 外部 Demo -->

```tsx
import Button from '..';

export default () => <Button type="primary">点击我</Button>;



#### 3. 关键配置（.dumirc.ts）
使用 `defineConfig` 配置：

```ts
import { defineConfig } from 'dumi';

export default defineConfig({
  title: 'My UI Library',      // 站点标题
  favicon: '/logo.png',
  logo: '/logo.png',
  outputPath: 'dist',         // 构建输出目录
  mode: 'site',               // site: 官网模式；doc: 文档模式
  resolve: {                  // 资产解析（组件路由前缀）
    atomDirs: [{ type: 'component', dir: 'src' }],
  },
  themeConfig: {              // 主题配置
    nav: [{ title: '指南', link: '/guide' }],
    sidebar: { '/components': [{ title: '基础组件', children: [...] }] },
  },
  // 支持 Umi 配置，如 alias、extraBabelPlugins 等
});

4. 常见命令

  • npm run dev 或 npm start：启动本地开发（实时预览）。
  • npm run build：构建静态站点（部署到 GitHub Pages/Netlify）。
  • npm run build:father：打包 npm 包（通过 father）。

5. 部署与发布

  • 文档站点：构建后部署到 Vercel/Netlify/GitHub Pages。
  • npm 包：配置 .fatherrc.ts，执行发布命令。

为什么选择 dumi 开发 UI 组件库？

  • 相比 Storybook：dumi 更轻量、文档与代码紧耦合、自动 API 生成更智能。
  • 相比 Docz：性能更好、生态更丰富（Umi/father）。
  • 实际案例：Ant Design、Ant Design Pro 等蚂蚁系组件库均使用 dumi。
avatar
文章
阅读
粉丝