ProFormUploadButton如何配置单文件上传限制？

Question

在使用 ProFormUploadButton 组件时，如何配置仅允许用户上传单个文件并限制文件类型和大小？常见问题包括：设置 `maxCount={1}` 后仍可重复上传、未正确触发校验规则、或与表单联动失效。需结合 `beforeUpload` 自定义校验文件大小与类型，并配合 `onChange` 控制值回传，确保符合单文件约束。同时，在 Form.Item 中合理使用 valuePropName 以同步状态。

Answer 1

1. 初识 ProFormUploadButton：基础配置与单文件上传控制

在 Ant Design 的 ProComponents 生态中，ProFormUploadButton 是一个高度封装的上传组件，适用于表单场景。要实现仅允许上传单个文件，最直观的方式是设置 maxCount={1} 属性：

<ProFormUploadButton
  name="file"
  maxCount={1}
  title="点击上传"
/>

然而，实践中发现即使设置了 maxCount={1}，用户仍可多次点击上传按钮，导致文件列表不断追加。这是因为 maxCount 仅限制选择时的文件数量，并不阻止后续操作。

• maxCount 控制的是每次选择文件的最大数量
• 无法自动覆盖已有文件
• 需结合其他属性实现“单文件”语义约束

2. 深入剖析：为何 maxCount={1} 无法阻止重复上传？

Ant Design 的 Upload 组件设计逻辑决定了其行为模式：当用户点击上传按钮并选择文件后，组件会将新文件追加到 fileList 中，而不会自动替换旧文件。因此，即便设置了 maxCount={1}，若不手动干预 fileList 状态，仍可能出现多个文件条目。

属性	作用范围	是否阻止重复上传
maxCount={1}	限制每次选择的文件数	否
beforeUpload	拦截上传前校验	可间接控制
onChange	监听文件列表变化	是（关键）

由此可见，真正控制“单文件”行为的核心在于 onChange 回调对 fileList 的管理。

3. 核心机制：利用 beforeUpload 实现类型与大小校验

为了限制文件类型和大小，必须使用 beforeUpload 钩子进行前置拦截。该函数返回 false 或 Promise.reject() 可中断上传流程。

const beforeUpload = (file) => {
  const isPDF = file.type === 'application/pdf';
  const isLt2M = file.size / 1024 / 1024 < 2;

  if (!isPDF) {
    message.error('仅支持上传 PDF 文件！');
    return Upload.LIST_IGNORE;
  }
  if (!isLt2M) {
    message.error('文件大小不能超过 2MB！');
    return Upload.LIST_IGNORE;
  }
  return isPDF && isLt2M;
};

注意：返回 Upload.LIST_IGNORE 可防止非法文件出现在列表中，避免污染 UI 与数据流。

4. 状态同步：通过 onChange 控制 fileList 单文件约束

要确保只保留最后一个有效文件，必须在 onChange 中手动截取 fileList 至单个元素：

const handleChange = ({ fileList }) => {
  // 仅保留最新一个文件
  const currentFile = fileList.slice(-1)[0];
  setFileList(currentFile ? [currentFile] : []);
};

同时，在 Form.Item 中需指定 valuePropName="fileList"，以确保表单值正确绑定：

<Form.Item
  name="document"
  valuePropName="fileList"
  getValueFromEvent={handleChange}
>
  <ProFormUploadButton
    maxCount={1}
    beforeUpload={beforeUpload}
    onChange={handleChange}
  />
</Form.Item>

5. 表单联动失效问题分析与解决方案

常见问题之一是上传完成后表单值未及时更新，导致校验失败或提交数据缺失。这通常源于：

1. 未正确设置 valuePropName="fileList"
2. getValueFromEvent 未返回标准化 fileList 结构
3. 自定义 onChange 未触发 form.setFieldsValue

推荐做法是在 getValueFromEvent 中统一处理：

getValueFromEvent: (e) => {
  if (Array.isArray(e)) return e;
  return e?.fileList?.slice(-1) || [];
}

6. 完整示例：集成校验、限制与表单同步的上传组件

以下为生产环境可用的完整配置方案：

<ProForm.Item
  name="contract"
  label="合同文件"
  valuePropName="fileList"
  getValueFromEvent={(e) => (Array.isArray(e) ? e : e?.fileList?.slice(-1))}
  rules={[{ required: true, message: '请上传合同文件' }]}
>
  <ProFormUploadButton
    text="上传PDF"
    icon=<UploadOutlined />
    maxCount={1}
    accept=".pdf"
    beforeUpload={(file) => {
      const isValidType = file.type === 'application/pdf';
      const isValidSize = file.size / 1024 / 1024 < 2;
      if (!isValidType) {
        message.error('仅支持PDF格式');
        return Upload.LIST_IGNORE;
      }
      if (!isValidSize) {
        message.error('文件不得超过2MB');
        return Upload.LIST_IGNORE;
      }
      return true;
    }}
    onChange={({ fileList }) => {
      const latest = fileList.slice(-1);
      return latest;
    }}
  />
</ProForm.Item>

7. 流程图：单文件上传控制逻辑流

graph TD A[用户点击上传] --> B{选择文件} B --> C[触发 beforeUpload] C --> D{文件类型/大小合法?} D -- 否 --> E[提示错误, 返回 LIST_IGNORE] D -- 是 --> F[添加至临时 fileList] F --> G[触发 onChange] G --> H[截取最后一条记录] H --> I[更新状态 & 同步表单值] I --> J[显示最终文件项]

该流程清晰展示了从用户操作到表单同步的完整链路，强调了各钩子函数的协作关系。

8. 高级技巧：动态限制与跨字段校验

在复杂业务场景中，可能需要根据其他字段动态调整上传限制。例如，若用户选择了“高级套餐”，则允许上传更大文件。

const { getFieldValue } = form;
const maxSize = getFieldValue('plan') === 'premium' ? 10 : 2; // MB

const beforeUpload = (file) => {
  if (file.size / 1024 / 1024 > maxSize) {
    message.error(`普通用户最大上传 ${maxSize}MB`);
    return Upload.LIST_IGNORE;
  }
  return true;
};

通过监听表单变化并重新计算校验逻辑，可实现灵活的业务规则适配。