feat:组件框架

2026-05-31 09:36:23 +08:00
parent b371a5341a
commit ba3b3ad5c8
483 changed files with 134708 additions and 1627 deletions
@@ -0,0 +1,220 @@
+# 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` 配置**:
+```typescript
+sidebar: {
+  '/components': [{ title: '组件总览', children: [] }],
+},
+```
+当前 sidebar 被硬编码覆盖，dumi 无法根据 `atomDirs` + frontmatter 自动生成层级导航。
+
+**组件 frontmatter 格式** (已正确配置):
+```markdown
+---
+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 风格布局
+1. **左侧边栏**: 层级导航，分类可展开，显示该分类下所有组件
+2. **组件总览页**: 按分类展示卡片网格，每张卡片包含图标/预览 + 组件名 + 简介
+3. **组件详情页**: 代码演示 + 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 导航修复
+1. 修改 `.dumirc.ts`，移除 `sidebar` 硬编码或让 dumi 自动生成
+2. 可选：手动配置完整的 sidebar 结构（如需精确控制顺序）
+3. 验证自动生成的 sidebar 包含 6 个分类，每个分类下列出其组件
+
+### Phase 2: 组件总览页优化
+1. 保留 `docs/components/index.md` 的卡片网格布局
+2. 为每个组件卡片添加小预览图/示意图
+3. 优化卡片样式以匹配 Ant Design 设计语言
+
+### Phase 3: 错误修复
+1. 修复 lint 错误（未使用的导入）
+2. 验证每个组件 demo 的渲染
+3. 修复测试超时问题
+
+### Phase 4: 详情页 Demo 补全
+1. 为缺少 demo 的组件添加代码演示（标记为 "-" 的）
+2. 确保每个组件至少有一个基本用法 demo
+3. 确保 `<API id="ComponentName" />` 正确引用类型定义
+
+---
+
+## 样式覆盖
+
+`src/theme/dumi.css` 已有部分 Ant Design 风格覆盖（第 77-100 行左右），包含 sidebar 样式定义。但需要确保：
+
+1. `.dumi-default-sidebar` 的宽度 (280px) 与 Ant Design 一致
+2. 分类标题样式与 Ant Design 一致（小号、灰色、大写字母间距）
+3. 组件链接样式（hover、active 状态）
+4. 侧边栏滚动条样式