AntdX Vue中Upload组件为何不调用onSuccess就不显示上传文件？

Question

在 AntdX（Ant Design Vue）的 `Upload` 组件中，若未正确调用 `onSuccess` 回调（或未通过 `customRequest` 显式调用 `fileList` 更新逻辑），上传文件将无法显示在列表中。这是因为 AntdX 的 `Upload` 默认采用“受控模式”行为：它不自动维护 `fileList`，而是依赖 `onSuccess`（或 `onChange` 中手动更新 `fileList`）来确认上传成功并触发 UI 同步。若仅发起请求但未调用 `onSuccess(file, response, xhr)`，组件无法识别该文件已上传完成，`file.status` 保持 `'uploading'` 或 `'error'`，导致文件条目不渲染、进度条卡住、甚至重复上传。常见于自定义 `customRequest` 时遗漏 `onSuccess` 调用，或异步处理中未正确传递响应结果。解决关键：确保每次上传成功后，**必须显式调用 `onSuccess`（或同步更新绑定的 `fileList`）**，且 `fileList` 需包含 `uid`、`name`、`status`、`url` 等必要字段。

Answer 1

```html

一、现象层：上传文件“消失”的直观表现

• 用户点击选择文件后，Upload 组件无任何条目渲染，进度条不出现；
• 已触发 customRequest 并收到 HTTP 200 响应，但 UI 仍显示“未上传”状态；
• 重复点击上传按钮，同一文件被多次发起请求（file.status === 'uploading' 持续存在）；
• 控制台无报错，网络面板可见请求成功，但 fileList 始终为空或未更新；
• 使用 onChange 监听时，file.status 停留在 'uploading' 或 'error'，从未变为 'done'。

二、机制层：AntdX Upload 的受控模式本质

Ant Design Vue 的 <Upload> 组件默认不维护内部状态，其行为完全由外部 props 驱动：

Prop	作用	是否必需
fileList	当前文件列表（含 uid/name/status/url 等字段）	✅ 受控核心
onSuccess	通知组件“某文件上传完成”，触发 status → 'done' & UI 同步	⚠️ customRequest 下必须显式调用
onChange	通用状态变更钩子，但不自动更新 fileList	❌ 仅监听，不可替代状态管理

三、根因层：为何遗漏 onSuccess 就会失效？

flowchart TD
  A[用户选择文件] --> B[Upload 触发 customRequest]
  B --> C[开发者发起 axios/fetch 请求]
  C --> D{是否调用 onSuccess?}
  D -- 否 --> E[file.status 保持 'uploading']
  D -- 是 --> F[Upload 内部标记为 done，合并至 fileList]
  E --> G[UI 不渲染条目，进度卡死，可能重复提交]
  F --> H[正确渲染 + 支持预览/删除/下载]

四、实践层：三种合规解决方案对比

1. 方案一（推荐）：在 customRequest 中调用 onSuccess
   

   customRequest: ({ file, onSuccess, onError, onProgress }) => {
     const formData = new FormData();
     formData.append('file', file);
     axios.post('/api/upload', formData, {
       onUploadProgress: e => onProgress({ percent: (e.loaded / e.total) * 100 })
     }).then(res => {
       // ✅ 关键：必须传入 file 和服务端返回的响应
       onSuccess(res.data, file, res.request);
     }).catch(onError);
   }

2. 方案二：手动维护 fileList（适用于复杂状态流）
   在 onSuccess 或 onChange 中深克隆并更新：fileList.value = [...fileList.value.filter(f => f.uid !== file.uid), { ...file, status: 'done', url: res.data.url, response: res.data }]
3. 方案三：降级为非受控模式（不推荐）
   移除 fileList 绑定 + 使用 defaultFileList + 依赖组件内部逻辑 —— 但丧失对状态的精确控制，无法支持断点续传、多阶段校验等高级场景。

五、架构层：从设计哲学理解 AntdX 的“可控性优先”原则

不同于 Element Plus 的 Upload 默认托管状态，AntdX 明确将“状态主权”交还给业务层。这源于其企业级应用治理理念：

• 规避隐式状态同步带来的竞态风险（如并发上传时 fileList 覆盖）；
• 支持与表单、工作流引擎深度集成（例如：上传后需人工审核才置为 'done'）；
• 便于统一埋点、错误归因、灰度发布（所有状态变更必经业务代码路径）；
• 符合 Vue 3 Composition API “逻辑内聚 + 状态显式” 的最佳实践范式。

六、防御层：工程化兜底策略

建议在团队基建中植入以下防护措施：

1. 封装 useUpload Hook，强制要求传入 uploadHandler 并内置 onSuccess 调用契约；
2. ESLint 自定义规则：检测 customRequest 函数体是否包含 onSuccess( 字符串或 AST 调用节点；
3. 开发环境注入调试代理：拦截所有 customRequest 执行，在未调用 onSuccess 且响应成功时抛出 warning；
4. CI 流程加入 cypress E2E 用例：模拟上传 → 断言 fileList.length > 0 且 status === 'done'。

```