跳到主要内容

FormUpload - 表单上传

该组件是对 Antd Upload 组件的封装, 通过对 fileList 和 onChange 属性的接管, 让它表现为一个标准的 value - onChange 受控组件, 使其能够被直接用在 Form.Item 里.

FormUpload 组件的设计目标是希望在简单的全局配置过后, 使用 FormUpload 组件就像使用 Input 组件一样简单轻量. 上传成功的文件会被表单自动收集, 上传失败的文件会被自动过滤.

基本的使用​

在使用之前先在全局配置好 action, headers 等必要属性.

<SettingProvider
  formUploadSetting={{
    action: 'https://mock.apifox.cn/m1/1864670-0-default/mockUpload',
    headers: { Authorization: 'myToken' },
    responseToFileList: (res) => ({ id: res?.data.id }), // 将后台返回值合并进file对象
    children: ({ loading }) => (
      <LinkButton disabled={loading}>
        {loading ? '上传中...' : '上传附件'}
      </LinkButton>
    ),
  }}
>
  ...
</SettingProvider>

组件的 children 可以使用 renderFunction。

<FormUpload>
  {({loading} => <Button disabled={loading}>{loading ? '上传中...' : '上传'}</Button>)}
</FormUpload>

文件上传失败​

  • 可在全局设置上传失败后的提醒。
  • 上传失败的文件不会被表单收集。

文件初始值​

beforeUpload 返回 false 的文件表单不收集.

数据处理和收集​

SchemaForm 组件提供了 ConverValue 和 Transform 用于数据处理。

  • convertValue - 用于前置转化
  • transform - 用于提交时的转化

FormUpload 组件默认接受的 file 对象格式是 { name: string; url: string }

该例子展示了当后端返回的数据不符合该要求时, 如何用 ConverValue 和 Transform 进行数值转换。

更改取值字段​

FormUpload 还提供了 nameKey 和 urlKey 来更改 file 对象的取值字段. 同样也支持在全局更改.

文件导入​

FormUpload 组件还能用于文件导入的场景。文件导入场景和附件上传不一样的地方在于, 每次新导入的文件要覆盖前面的文件, 而附件上传的逻辑是后上传的附件会加入到原来的文件列表中.

要实现这种覆盖的效果可以在导入完成后清空列表.

序号名称规格A规格B
暂无数据
暂无数据

API​

FormUpload​

FormUpload 类型是 FormUploadSelfType 和 UploadProps 的结合。

FormUploadSelfType​

属性名描述类型默认值
action文件上传接口string--
value文件列表. { name: string; url: string; status: string }"" | UploadFile<any>[]--
onChange文件变动后的回调; 该属性在 v0.3 版本后发生了变更, 改成与 onFinish 属性一致, 只有当文件全部上传完毕后才触发.((files: UploadFile<any>[]) => void)--
onFinish文件全部上传完成后的回调(所有文件的状态都是非uploading)((files: UploadFile<any>[]) => void)--
nameKey自定义文件列表中name的取值字段stringname
urlKey自定义文件列表中url的取值字段stringurl
responseToFileList可以将后台返回的数据合并进 fileList((res: any) => Record<string, any>)--
errorHandle上传失败后的处理函数((res: any) => void)--
childrenchildren({ loading: boolean }) => Element | Element--

FAQ​

responseToFileList 是什么意思?​

当文件上传成功后, 表单默认收集到的数据是这样的:

{
  uid: 'rc-upload-1691485494798-17',
  name: 'xx.png',
  size: 1403,
  status: 'done',
  response: {
    // 上传成功后的后端返回值
    id: 123,
    filePath: 'xxx'
  }
}

responseToFileList 函数可以把上面的 response 合并进文件对象.

比如 responseToFileList: (res) => ({ id: res.id }), 最后提交时的对象就会有 id.

{
  id: 123,
  uid: 'rc-upload-1691485494798-17',
  name: 'xx.png',
  size: 1403,
  status: 'done',
  response: {
    // 上传成功后的后端返回
    id: 123,
    filePath: 'xxx'
  }
}

一般这个属性可以在 SettingProvider 组件中全局设定