u

2026-04-28 17:29:53 +08:00
1 parent ae6ccad238
commit b2d113db38
@@ -0,0 +1,211 @@
+# UI 提示系统重构计划
+
+## 需求分析
+
+用户要求重新设计并实现一个轻量 UI 提示系统，包含：
+
+1. **Toast（右上角）** - 瞬时提示，无状态设计
+2. **Task Center（右下角任务中心）** - 长任务状态系统，有状态
+
+核心要求：
+- 两者完全独立，不共享逻辑
+- Task 必须通用化，不绑定具体业务类型
+- 实现 UI Lock 机制
+- 支持多语言国际化
+
+---
+
+## 架构设计
+
+### 1. 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     UI 提示系统                              │
+├───────────────────────────┬─────────────────────────────────┤
+│        Toast 系统         │         Task Center 系统         │
+│  (右上角，无状态)          │      (右下角，有状态)             │
+├───────────────────────────┼─────────────────────────────────┤
+│ • 自动消失                │ • 手动关闭                      │
+│ • 多条堆叠                │ • 单一实例                      │
+│ • 类型：success/error/   │ • 生命周期独立                  │
+│   info/warning           │ • 进度追踪                      │
+└───────────────────────────┴─────────────────────────────────┘
+```
+
+### 2. Toast API
+
+```js
+showToast({
+  title,        // 标题
+  message,      // 消息内容
+  type: "success | error | info | warning",
+  duration      // 显示时长（毫秒）
+});
+```
+
+### 3. Task API
+
+```js
+// 创建任务
+startTask({
+  id,           // 任务ID
+  title,        // 任务标题（国际化key）
+  total,        // 总数量
+  current,      // 当前进度
+  currentItem   // 当前处理项
+});
+
+// 更新任务
+updateTask({
+  id,           // 任务ID
+  current,      // 当前进度
+  currentItem   // 当前处理项
+});
+
+// 完成任务
+finishTask({
+  id,           // 任务ID
+  total,        // 总数量
+  success,      // 成功数量
+  failed        // 失败数量
+});
+
+// 手动关闭
+closeTask(id);
+```
+
+---
+
+## 修改内容
+
+### 1. 修改 CSS 文件 (`custom-file/index.css`)
+
+**新增样式：**
+- Toast 容器样式（右上角固定定位）
+- Toast 单条样式（支持不同类型）
+- Toast 动画（进入/退出）
+- Task Center 容器样式（右下角固定定位）
+- Task Center 进度条样式
+- Task Center 结果展示样式
+- UI Lock 样式
+
+**删除旧样式：**
+- 删除 `.task-dock` 相关样式（如仍存在）
+
+### 2. 修改 JS 文件 (`custom-file/index.js`)
+
+**新增方法：**
+
+| 方法名 | 功能 |
+|--------|------|
+| `showToast` | 显示 Toast 提示 |
+| `startTask` | 创建并启动任务 |
+| `updateTask` | 更新任务进度 |
+| `finishTask` | 完成任务 |
+| `closeTask` | 关闭任务 UI |
+| `lockUI` | 锁定 UI |
+| `unlockUI` | 解锁 UI |
+| `isUILocked` | 检查 UI 是否锁定 |
+
+**修改方法：**
+- `render` - 添加 Toast 和 Task Center 的 DOM 结构
+- `internalDownloadBatch` - 使用新的 Task API
+
+**删除方法：**
+- `addTask`（旧版本）
+- `updateTask`（旧版本）
+- `finishTask`（旧版本）
+- `clearTasks`（旧版本）
+- `updateTaskStats`（旧版本）
+
+### 3. 新增多语言配置
+
+```js
+languages: {
+  "zh-CN": {
+    // ... 现有配置
+    toast: {
+      success: "成功",
+      error: "错误",
+      info: "提示",
+      warning: "警告"
+    },
+    task: {
+      title: {
+        processing: "处理中"
+      },
+      total: "总计",
+      success: "成功",
+      failed: "失败",
+      currentItem: "当前项",
+      close: "关闭"
+    }
+  },
+  "en-US": {
+    // ... 现有配置
+    toast: {
+      success: "Success",
+      error: "Error",
+      info: "Info",
+      warning: "Warning"
+    },
+    task: {
+      title: {
+        processing: "Processing"
+      },
+      total: "Total",
+      success: "Success",
+      failed: "Failed",
+      currentItem: "Current",
+      close: "Close"
+    }
+  }
+}
+```
+
+---
+
+## 实施步骤
+
+| 步骤 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| 1 | 添加 Toast 和 Task Center 的 CSS 样式 | `custom-file/index.css` | 待执行 |
+| 2 | 更新多语言配置 | `custom-file/index.js` | 待执行 |
+| 3 | 添加 Toast 相关方法 | `custom-file/index.js` | 待执行 |
+| 4 | 添加 Task Center 相关方法 | `custom-file/index.js` | 待执行 |
+| 5 | 添加 UI Lock 机制 | `custom-file/index.js` | 待执行 |
+| 6 | 修改 render 方法添加 DOM 结构 | `custom-file/index.js` | 待执行 |
+| 7 | 修改 internalDownloadBatch 使用新 API | `custom-file/index.js` | 待执行 |
+| 8 | 删除旧的任务管理方法 | `custom-file/index.js` | 待执行 |
+
+---
+
+## 风险评估
+
+| 风险项 | 风险等级 | 处理方式 |
+|--------|----------|----------|
+| Task 状态与 UI 不同步 | 中 | 确保 task 对象独立于 UI 存在 |
+| Toast 堆叠过多 | 低 | 限制最大显示数量（如5条） |
+| UI Lock 状态异常 | 中 | 在任务完成时强制解锁 |
+| 多语言文案遗漏 | 低 | 统一使用 `this.language.xxx` 模式 |
+
+---
+
+## 兼容性
+
+- 原有 API 调用保持兼容
+- 新增 API 为可选参数
+- 不影响现有文件管理功能
+
+---
+
+## 最终目标
+
+实现一个 **"通用任务系统 + Toast 提示系统 + UI Lock + i18n"** 的轻量 UI 架构，支持未来扩展：
+- 批量上传
+- 批量下载
+- 批量删除
+- 任意异步任务
+
+无需修改核心结构，仅通过 task 数据驱动。