u

2026-04-27 22:11:59 +08:00
1 parent 3a951f764c
commit ae6ccad238
@@ -0,0 +1,135 @@
+# 上传功能实现计划
+
+## 1. 需求分析
+
+### 1.1 现有功能
+- 当前 `G3File` 组件的上传功能通过 `onUpload` 回调函数处理
+- 上传按钮点击时，会获取所有状态为 `pending` 的文件并调用 `onUpload` 回调
+- 没有内置的上传实现，完全依赖外部回调
+
+### 1.2 需求目标
+- 实现阿里云内部上传方法
+- 保留外部方法，允许用户动态获取阿里云key等信息
+- 支持外部自定义上传方法
+- 只上传未上传（状态为 `pending`）的文件
+- 上传成功后，将上传成功的 fileitem 传给外部调用，上传成功一个就触发一次
+
+## 2. 技术方案
+
+### 2.1 核心功能设计
+1. **上传配置**：添加上传相关的配置选项，包括阿里云上传配置和自定义上传方法
+2. **上传方法**：实现阿里云内部上传方法和外部自定义上传方法的支持
+3. **上传流程**：优化上传流程，只上传未上传的文件，上传成功后触发回调
+4. **状态管理**：管理文件的上传状态，包括 `pending`、`uploading`、`uploaded`、`failed` 等
+
+### 2.2 配置选项
+- `uploadConfig`：上传配置对象，包含阿里云上传配置和自定义上传方法
+- `onUploadSuccess`：上传成功回调，上传成功一个文件就触发一次
+- `onUploadError`：上传失败回调
+- `onUploadComplete`：所有文件上传完成回调
+
+### 2.3 上传流程
+1. 用户点击上传按钮
+2. 组件获取所有状态为 `pending` 的文件
+3. 检查是否配置了自定义上传方法，如果有则使用自定义方法
+4. 如果没有自定义上传方法，则使用阿里云内部上传方法
+5. 逐个上传文件，更新文件状态为 `uploading`
+6. 上传成功后，更新文件状态为 `uploaded`，并触发 `onUploadSuccess` 回调
+7. 上传失败后，更新文件状态为 `failed`，并触发 `onUploadError` 回调
+8. 所有文件上传完成后，触发 `onUploadComplete` 回调
+
+## 3. 实现步骤
+
+### 3.1 修改 HTML 结构
+- 无需修改 HTML 结构，使用现有的上传按钮
+
+### 3.2 扩展 JavaScript 功能
+1. **添加上传配置选项**：在 `defaults` 中添加上传相关的配置选项
+2. **实现上传方法**：
+   - `internalUpload`：内部上传方法，支持阿里云上传
+   - `handleUpload`：处理上传逻辑，支持自定义上传方法
+3. **更新上传流程**：修改 `$btnUpload` 的点击事件处理，使用新的上传逻辑
+4. **添加回调方法**：实现 `onUploadSuccess`、`onUploadError`、`onUploadComplete` 回调
+
+### 3.3 优化 CSS 样式
+- 为上传状态添加相应的样式，如上传中、上传失败等
+
+### 3.4 测试和验证
+1. 测试阿里云内部上传功能
+2. 测试外部自定义上传方法
+3. 测试上传状态管理
+4. 测试回调函数触发
+
+## 4. 预期效果
+
+### 4.1 上传功能
+- 支持阿里云内部上传
+- 支持外部自定义上传方法
+- 只上传未上传的文件
+- 上传成功后触发回调
+
+### 4.2 状态管理
+- 清晰的上传状态管理
+- 上传中、上传成功、上传失败等状态的视觉反馈
+
+### 4.3 回调机制
+- 上传成功一个文件就触发一次 `onUploadSuccess` 回调
+- 上传失败触发 `onUploadError` 回调
+- 所有文件上传完成触发 `onUploadComplete` 回调
+
+## 5. 风险评估
+
+### 5.1 潜在风险
+- 阿里云上传配置复杂，可能出现配置错误
+- 自定义上传方法可能与内部上传逻辑冲突
+- 上传过程中可能出现网络错误
+
+### 5.2 风险缓解措施
+- 提供详细的配置文档
+- 确保自定义上传方法与内部上传逻辑的兼容性
+- 添加错误处理和重试机制
+
+## 6. 实现细节
+
+### 6.1 上传配置
+```javascript
+uploadConfig: {
+  aliyun: {
+    // 阿里云配置是可选的
+    // getUploadToken 是必须的，用于动态获取上传凭证
+    getUploadToken: null // 动态获取上传凭证的函数，返回 Promise
+  },
+  customUpload: null // 自定义上传方法
+}
+```
+
+### 6.2 回调函数
+```javascript
+onUploadSuccess: function(file) {
+  // 上传成功回调
+},
+onUploadError: function(file, error) {
+  // 上传失败回调
+},
+onUploadComplete: function(successCount, failCount) {
+  // 所有文件上传完成回调
+}
+```
+
+### 6.3 上传方法
+- `internalUpload(file, callback)`：内部上传方法
+- `handleUpload(files)`：处理上传逻辑
+
+## 7. 代码结构
+
+### 7.1 主要修改文件
+- `custom-file/index.js`：扩展上传功能
+
+### 7.2 新增方法
+- `internalUpload`：内部上传方法
+- `handleUpload`：处理上传逻辑
+- `updateFileStatus`：更新文件状态
+
+### 7.3 修改方法
+- `init`：初始化上传配置
+- `bindEvents`：更新上传按钮的点击事件处理