董海洋
10 KiB
10 KiB
Ant Design 风格组件总览改造计划
当前状态
技术栈
- 框架: React 19 + TypeScript 6
- 文档: dumi v2 (^2.4.28)
- 构建: father v4 (组件库) + dumi build (文档站)
- 测试: Vitest + @testing-library/react
构建状态
pnpm docs:build✅ 构建成功 (Webpack compiled successfully)pnpm tsc --noEmit✅ 无类型错误 (仅 config 文件 rootDir 警告，不影响运行)pnpm lint❌ 1 个 lint 错误:Notification.tsx未使用的ReactElement导入pnpm test⚠️ 超时 (部分测试可能挂起或循环)
文档站点现状
.dumirc.ts 配置:
sidebar: {
'/components': [{ title: '组件总览', children: [] }],
},
当前 sidebar 被硬编码覆盖，dumi 无法根据 atomDirs + frontmatter 自动生成层级导航。
组件 frontmatter 格式 (已正确配置):
---
nav: 组件
group:
title: 通用 # 分类名
order: 1 # 排序
title: Button 按钮
description: 用于触发操作的按钮组件。
---
6 个分类 (order 已定义):
| 分类 | order | 组件数 |
|---|---|---|
| 通用 | 1 | 10 |
| 布局 | 2 | 8 |
| 导航 | 3 | 6 |
| 数据录入 | 4 | 19 |
| 数据展示 | 5 | 20 |
| 反馈 | 6 | 10 |
目标状态
Ant Design 风格布局
- 左侧边栏: 层级导航，分类可展开，显示该分类下所有组件
- 组件总览页: 按分类展示卡片网格，每张卡片包含图标/预览 + 组件名 + 简介
- 组件详情页: 代码演示 + API 文档
全部组件清单
通用 Common (10)
| 组件 | 路由 | 说明 | Demo 演示内容 |
|---|---|---|---|
| Button 按钮 | /components/common/button |
触发操作的按钮组件 | 6 种变体(solid/outline/dashed/filled/text/link)、6 种颜色、5 种尺寸、3 种形状、图标、加载、全宽、危险、幽灵、禁用、链接 |
| FloatButton 悬浮按钮 | /components/common/float-button |
悬浮在页面边缘的操作按钮 | - |
| Icon 图标 | /components/common/icon |
语义化的矢量图形 | - |
| Typography 排版 | /components/common/typography |
标题、段落、文本组件 | - |
| Affix 固钉 | /components/common/affix |
将元素固定在可视范围 | - |
| Anchor 锚点 | /components/common/anchor |
页面内锚点导航 | - |
| App 包裹组件 | /components/common/app |
提供全局化配置的包裹组件 | - |
| BackTop 回到顶部 | /components/common/back-top |
返回页面顶部的快捷按钮 | - |
| ConfigProvider 全局配置 | /components/common/config-provider |
全局化配置 | - |
| Watermark 水印 | /components/common/watermark |
页面水印 | - |
布局 Layout (8)
| 组件 | 路由 | 说明 | Demo 演示内容 |
|---|---|---|---|
| Divider 分割线 | /components/layout/divider |
区隔内容的分割线 | 水平/垂直分割线、带文字 |
| Flex 弹性布局 | /components/layout/flex |
弹性布局容器 | - |
| Grid 栅格 | /components/layout/grid |
24 栅格系统 | - |
| Layout 布局 | /components/layout/layout |
页面级布局 | - |
| Masonry 瀑布流 | /components/layout/masonry |
瀑布流布局 | - |
| Space 间距 | /components/layout/space |
组件间距 | - |
| Splitter 分割面板 | /components/layout/splitter |
可拖拽的面板分割 | - |
| Stack 堆栈布局 | /components/layout/stack |
堆栈式布局 | - |
导航 Navigation (6)
| 组件 | 路由 | 说明 | Demo 演示内容 |
|---|---|---|---|
| Breadcrumb 面包屑 | /components/nav/breadcrumb |
页面路径导航 | - |
| Dropdown 下拉菜单 | /components/nav/dropdown |
下拉菜单 | - |
| Menu 导航菜单 | /components/nav/menu |
侧边/顶部导航菜单 | 基本使用、垂直菜单(含子菜单) |
| Pagination 分页 | /components/nav/pagination |
数据分页 | - |
| Steps 步骤条 | /components/nav/steps |
步骤指示器 | - |
| Tabs 标签页 | /components/nav/tabs |
选项卡切换 | - |
数据录入 Data Entry (19)
| 组件 | 路由 | 说明 | Demo 演示内容 |
|---|---|---|---|
| AutoComplete 自动完成 | /components/data-entry/auto-complete |
自动补全输入 | - |
| Cascader 级联选择 | /components/data-entry/cascader |
级联选择器 | - |
| Checkbox 多选框 | /components/data-entry/choice |
多选选择框 | - |
| Radio 单选框 | /components/data-entry/choice |
单选选择框 | - |
| Switch 开关 | /components/data-entry/choice |
开关切换 | - |
| DatePicker 日期选择器 | /components/data-entry/date-picker |
日期选择 | - |
| Form 表单 | /components/data-entry/form |
表单组件 | - |
| Input 输入框 | /components/data-entry/input |
文本输入框 | 基本使用、3 种尺寸、禁用、前缀 |
| InputNumber 数字输入框 | /components/data-entry/input-number |
数字输入 | - |
| Mention 提及 | /components/data-entry/mention |
@提及 | - |
| RangePicker 范围选择器 | /components/data-entry/range-picker |
日期范围选择 | - |
| Rate 评分 | /components/data-entry/rate |
评分组件 | - |
| Select 选择器 | /components/data-entry/select |
下拉选择器 | - |
| Slider 滑动输入条 | /components/data-entry/slider |
滑动输入 | - |
| TextArea 文本域 | /components/data-entry/textarea |
多行文本输入 | - |
| TimePicker 时间选择器 | /components/data-entry/time-picker |
时间选择 | - |
| Transfer 穿梭框 | /components/data-entry/transfer |
双栏穿梭选择 | - |
| TreeSelect 树选择 | /components/data-entry/tree-select |
树形选择 | - |
| Upload 上传 | /components/data-entry/upload |
文件上传 | - |
数据展示 Data Display (20)
| 组件 | 路由 | 说明 | Demo 演示内容 |
|---|---|---|---|
| Avatar 头像 | /components/data-display/avatar |
用户头像 | 4 种尺寸、3 种类型(图标/文字/图片)、AvatarGroup |
| Badge 徽标 | /components/data-display/badge |
徽标数/小红点 | - |
| Calendar 日历 | /components/data-display/calendar |
日历 | - |
| Card 卡片 | /components/data-display/card |
内容容器 | - |
| Carousel 走马灯 | /components/data-display/carousel |
轮播 | - |
| Collapse 折叠面板 | /components/data-display/collapse |
可折叠内容 | - |
| Descriptions 描述列表 | /components/data-display/descriptions |
描述列表 | - |
| Empty 空状态 | /components/data-display/empty |
空状态占位 | - |
| Image 图片 | /components/data-display/image |
图片展示 | - |
| List 列表 | /components/data-display/list |
列表 | - |
| Popover 气泡卡片 | /components/data-display/popover |
气泡弹出 | - |
| QRCode 二维码 | /components/data-display/qrcode |
二维码生成 | - |
| Segmented 分段控制器 | /components/data-display/segmented |
分段选择 | - |
| Statistic 统计数值 | /components/data-display/statistic |
统计数值展示 | - |
| Table 表格 | /components/data-display/table |
数据表格 | - |
| Tag 标签 | /components/data-display/tag |
标签 | - |
| Timeline 时间轴 | /components/data-display/timeline |
时间轴 | - |
| Tooltip 文字提示 | /components/data-display/tooltip |
文字提示 | - |
| Tour 漫游式引导 | /components/data-display/tour |
分步引导 | - |
| Tree 树形控件 | /components/data-display/tree |
树形结构 | - |
反馈 Feedback (10)
| 组件 | 路由 | 说明 | Demo 演示内容 |
|---|---|---|---|
| Alert 警告提示 | /components/feedback/alert |
警告提示 | 4 种类型(success/info/warning/error)、可关闭 |
| Drawer 抽屉 | /components/feedback/drawer |
侧边抽屉 | - |
| Message 全局提示 | /components/feedback/message |
全局消息提示 | - |
| Modal 对话框 | /components/feedback/modal |
模态对话框 | - |
| Notification 通知提醒框 | /components/feedback/notification |
通知提醒 | - |
| Popconfirm 气泡确认框 | /components/feedback/popconfirm |
气泡确认 | - |
| Progress 进度条 | /components/feedback/progress |
进度展示 | - |
| Result 结果 | /components/feedback/result |
操作结果反馈 | - |
| Skeleton 骨架屏 | /components/feedback/skeleton |
加载占位 | - |
| Spin 加载中 | /components/feedback/spin |
加载状态 | - |
当前问题 & 修复项
1. Sidebar 未自动生成
问题: .dumirc.ts 中的 sidebar 配置覆盖了 dumi 的自动生成逻辑。
修复: 删除或调整 sidebar 配置，让 dumi 根据 frontmatter 的 group.title + group.order 自动生成层级导航。
2. Lint 错误
文件: src/components/feedback/notification/Notification.tsx:2
问题: ReactElement 导入未使用
修复: 移除未使用的 ReactElement 类型导入
3. 部分 Demo 可能报错
一些组件的 demo 代码可能引用了尚未导出的子组件或类型。需要逐一验证每个组件的 dumi demo 是否能正常渲染。
4. 测试超时
pnpm test 执行超时（>120s），可能存在问题：
- 某测试文件中有 await 未正确处理
- 测试使用了实际定时器（如 Notification 的 setTimeout）未 mock
- 组件渲染循环
改造步骤
Phase 1: Sidebar 导航修复
- 修改
.dumirc.ts，移除sidebar硬编码或让 dumi 自动生成 - 可选：手动配置完整的 sidebar 结构（如需精确控制顺序）
- 验证自动生成的 sidebar 包含 6 个分类，每个分类下列出其组件
Phase 2: 组件总览页优化
- 保留
docs/components/index.md的卡片网格布局 - 为每个组件卡片添加小预览图/示意图
- 优化卡片样式以匹配 Ant Design 设计语言
Phase 3: 错误修复
- 修复 lint 错误（未使用的导入）
- 验证每个组件 demo 的渲染
- 修复测试超时问题
Phase 4: 详情页 Demo 补全
- 为缺少 demo 的组件添加代码演示（标记为 "-" 的）
- 确保每个组件至少有一个基本用法 demo
- 确保
<API id="ComponentName" />正确引用类型定义
样式覆盖
src/theme/dumi.css 已有部分 Ant Design 风格覆盖（第 77-100 行左右），包含 sidebar 样式定义。但需要确保：
.dumi-default-sidebar的宽度 (280px) 与 Ant Design 一致- 分类标题样式与 Ant Design 一致（小号、灰色、大写字母间距）
- 组件链接样式（hover、active 状态）
- 侧边栏滚动条样式