FormUpload

This component is a wrapper for Antd Upload component. By managing fileList and onChange props, it behaves as a standard controlled component with value/onChange pattern, making it ready to use directly within Form.Item.

The design goal of FormUpload is to provide a simple, lightweight experience similar to using an Input component after basic global configuration. Successfully uploaded files are automatically collected by the form, while failed uploads are filtered out.

Basic Usage

Configure essential props like action and headers globally before use:

<SettingProvider
  formUploadSetting={{
    action: 'https://mock.apifox.cn/m1/1864670-0-default/mockUpload',
    headers: { Authorization: 'myToken' },
    responseToFileList: (res) => ({ id: res?.data.id }), // Merge API response into file object
    children: ({ loading }) => (
      <LinkButton disabled={loading}>
        {loading ? 'Uploading...' : 'Upload File'}
      </LinkButton>
    ),
  }}
>
  ...
</SettingProvider>

The component's children can use render function:

<FormUpload>
  {({loading} => <Button disabled={loading}>{loading ? 'Uploading...' : 'Upload'}</Button>)}
</FormUpload>

attachment

Upload Failures

• You can configure error notifications globally.
• Failed files won't be collected by the form.

attachment

File Initial Values

Files where beforeUpload returns false are excluded from form collection.

attachment

Data Processing and Collection

SchemaForm provides convertValue and transform for data processing:

• convertValue - Pre-processes initial values
• transform - Processes data before submission

FormUpload component expects file objects in format: { name: string; url: string } by default

This example shows how to use convertValue and transform for data conversion when backend returns non-conforming data.

attachment

Change Field Keys

FormUpload also provides nameKey and urlKey to customize file object field mapping. Global configuration is also supported.

attachments

File Import

FormUpload component can also be used for file import scenarios. File import differs from file attachment upload in that each new imported file should replace previous files, while attachment upload logic adds newly uploaded files to the existing file list.

To achieve this replacement effect, you can clear the list after import completion.

index	name	spceA	specB
No data

API

FormUpload

FormUpload type is a combination of FormUploadSelfType and UploadProps.

FormUploadSelfType

Property	Description	Type	Default
action	Uploading URL	string	--
value	File list. { name: string; url: string; status: string }	"" | UploadFile<any>[]	--
onChange	Callback after file change; This property has changed in version 0.3, and it is changed to be consistent with the onFinish property. It is only triggered when all files are uploaded.	((files: UploadFile<any>[]) => void)	--
onFinish	Callback after all files are uploaded (all files are not uploading)	((files: UploadFile<any>[]) => void)	--
nameKey	Custom field for file list name	string	name
urlKey	Custom field for file list url	string	url
responseToFileList	You can merge the data returned by the background into fileList	((res: any) => Record<string, any>)	--
errorHandle	Error handling function after upload failure	((res: any) => void)	--
children	children	({ loading: boolean }) => Element | Element	--

FAQ

What is responseToFileList?

After successful file upload, the default collected data looks like:

{
  uid: 'rc-upload-1691485494798-17',
  name: 'xx.png',
  size: 1403,
  status: 'done',
  response: {
    // Backend response after successful upload
    id: 123,
    filePath: 'xxx'
  }
}

The responseToFileList function can merge the above response into the file object.

For example: responseToFileList: (res) => ({ id: res.id }), the final submitted object will have the id:

{
  id: 123,
  uid: 'rc-upload-1691485494798-17',
  name: 'xx.png',
  size: 1403,
  status: 'done',
  response: {
    // Backend response after successful upload
    id: 123,
    filePath: 'xxx'
  }
}

Generally this property can be set globally in the SettingProvider component.