ant-design/components/upload/index.en-US.md

11 KiB
Raw Blame History

category group title description cover coverDark demo
Components Data Entry Upload Used to select and upload files or drag and drop files. https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*93ymR4RD4S0AAAAAAAAAAAAADrJ8AQ/original https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*l1nlSryXib8AAAAAAAAAAAAADrJ8AQ/original
cols
2

When To Use

Uploading is the process of publishing information (web pages, text, pictures, video, etc.) to a remote server via a web page or upload tool.

  • When you need to upload one or more files.
  • When you need to show the process of uploading.
  • When you need to upload files by dragging and dropping.

Examples

Upload by clicking Avatar Default Files Pictures Wall Pictures with picture-circle type Complete control over file list Drag and Drop Upload directory Upload manually Upload png file only Pictures with list style Customize preview file Max Count Transform file before request Aliyun OSS custom show icon Custom action icon and extra info Drag sorting of uploadList Crop image before uploading Customize Progress Bar Component Token Debug Disabled Styles

API

Common props refCommon props

Property Description Type Default Version
accept File types that can be accepted. See input accept Attribute string -
action Uploading URL string | (file) => Promise<string> -
beforeUpload Hook function which will be executed before uploading. Uploading will be stopped with false or a rejected Promise returned. When returned value is Upload.LIST_IGNORE, the list of files that have been uploaded will ignore it. Warningthis function is not supported in IE9 (file, fileList) => boolean | Promise<File> | Upload.LIST_IGNORE -
customRequest Override for the default xhr behavior allowing for additional customization and the ability to implement your own XMLHttpRequest function -
data Uploading extra params or function which can return uploading extra params object | (file) => object | Promise<object> -
defaultFileList Default list of files that have been uploaded object[] -
directory Support upload whole directory (caniuse) boolean false
disabled Disable upload button boolean false When customizing Upload children, please pass the disabled attribute to the child node at the same time to ensure the disabled rendering effect is consistent.
fileList List of files that have been uploaded (controlled). Here is a common issue #2423 when using it UploadFile[] -
headers Set request headers, valid above IE10 object -
iconRender Custom show icon (file: UploadFile, listType?: UploadListType) => ReactNode -
isImageUrl Customize if render <img /> in thumbnail (file: UploadFile) => boolean (inside implementation)
itemRender Custom item of uploadList (originNode: ReactElement, file: UploadFile, fileList: object[], actions: { download: function, preview: function, remove: function }) => React.ReactNode - 4.16.0
listType Built-in stylesheets, support for four types: text, picture, picture-card or picture-circle string text picture-circle(5.2.0+)
maxCount Limit the number of uploaded files. Will replace current one when maxCount is 1 number - 4.10.0
method The http method of upload request string post
multiple Whether to support selected multiple files. IE10+ supported. You can select multiple files with CTRL holding down while multiple is set to be true boolean false
name The name of uploading file string file
openFileDialogOnClick Click open file dialog boolean true
previewFile Customize preview file logic (file: File | Blob) => Promise<dataURL: string> -
progress Custom progress bar ProgressProps (support type="line" only) { strokeWidth: 2, showInfo: false } 4.3.0
showUploadList Whether to show default upload list, could be an object to specify extra, showPreviewIcon, showRemoveIcon, showDownloadIcon, removeIcon and downloadIcon individually boolean | { extra?: ReactNode | (file: UploadFile) => ReactNode, showPreviewIcon?: boolean | (file: UploadFile) => boolean, showDownloadIcon?: boolean | (file: UploadFile) => boolean, showRemoveIcon?: boolean | (file: UploadFile) => boolean, previewIcon?: ReactNode | (file: UploadFile) => ReactNode, removeIcon?: ReactNode | (file: UploadFile) => ReactNode, downloadIcon?: ReactNode | (file: UploadFile) => ReactNode } true extra: 5.20.0, showPreviewIcon function: 5.21.0, showRemoveIcon function: 5.21.0, showDownloadIcon function: 5.21.0
withCredentials The ajax upload with cookie sent boolean false
onChange A callback function, can be executed when uploading state is changing. It will trigger by every uploading phase. see onChange function -
onDrop A callback function executed when files are dragged and dropped into the upload area (event: React.DragEvent) => void - 4.16.0
onDownload Click the method to download the file, pass the method to perform the method logic, and do not pass the default jump to the new TAB function(file): void (Jump to new TAB)
onPreview A callback function, will be executed when the file link or preview icon is clicked function(file) -
onRemove A callback function, will be executed when removing file button is clicked, remove event will be prevented when the return value is false or a Promise which resolve(false) or reject function(file): boolean | Promise -

UploadFile

Extends File with additional props.

Property Description Type Default Version
crossOrigin CORS settings attributes 'anonymous' | 'use-credentials' | '' - 4.20.0
name File name string - -
percent Upload progress percent number - -
status Upload status. Show different style when configured error | done | uploading | removed - -
thumbUrl Thumb image url string - -
uid unique id. Will auto-generate when not provided string - -
url Download url string - -

onChange

💡 The function will be called when uploading is in progress, completed, or failed.

When uploading state change, it returns:

{
  file: { /* ... */ },
  fileList: [ /* ... */ ],
  event: { /* ... */ },
}
  1. file File object for the current operation.

    {
       uid: 'uid',      // unique identifier, negative is recommended, to prevent interference with internally generated id
       name: 'xx.png',   // file name
       status: 'done' | 'uploading' | 'error' | 'removed', // Intercepted file by beforeUpload doesn't have a status field.
       response: '{"status": "success"}', // response from server
       linkProps: '{"download": "image"}', // additional HTML props of file link
       xhr: 'XMLHttpRequest{ ... }', // XMLHttpRequest Header
    }
    
  2. fileList current list of files

  3. event response from the server, including uploading progress, supported by advanced browsers.

Design Token

FAQ

How do I implement upload server side?

  • You can consult jQuery-File-Upload about how to implement server side upload interface.
  • There is a mock example of express in rc-upload.

Please set property url of each item in fileList to control the content of the link.

How to use customRequest?

See https://github.com/react-component/upload#customrequest.

Why will the fileList that's in control not trigger onChange status update when the file is not in the list?

onChange will only trigger when the file is in the list, it will ignore any events removed from the list. Please note that there does exist a bug which makes an event still trigger even when the file is not in the list before 4.13.0.

Why does onChange sometimes return File object and other times return { originFileObj: File }?

For compatible case, we return File object when beforeUpload return false. It will merge to { originFileObj: File } in the next major version. Current version is compatible to get origin file by info.file.originFileObj. You can change this before a major release.

Why sometimes Chrome can not upload?

Chrome update will also break native upload. Please restart Chrome to finish the upload job.

Ref:

Can still select files when uploading a folder in Safari?

Inside the upload component, we use the directory and webkitdirectory properties to control only directories can be selected. However, in Safari's implementation it doesn't seem to work. See here. Please try passing an additional accept attribute that cannot match any files. For example:

accept: `.${'n'.repeat(100)}`;