workspace/code/file-preview/g3-file/.trae/documents/optimize-class-names-plan.md

上传功能实现计划

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 上传配置

uploadConfig: {
  aliyun: {
    // 阿里云配置是可选的
    // getUploadToken 是必须的，用于动态获取上传凭证
    getUploadToken: null // 动态获取上传凭证的函数，返回 Promise
  },
  customUpload: null // 自定义上传方法
}

6.2 回调函数

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：更新上传按钮的点击事件处理