{"meta":"

Develop Guide #

\n

When to Use #

\n

When user want to upload some file to server side or cloud storage, upload component could help user deal with it.

\n","api":"

API #

\n

Upload #

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParamDescriptionTypeDefault ValueRequiredSupported Version
actionUpload addressstring--
shapeUpload button shape'card'--
acceptAccepted file types, see [input accept attribute](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/Input#attrstring--
dataUpload extra parameters| { [key: string]: string | Blob }
| ((file: UploadFile) => { [key: string]: string | Blob })		--
headersSet the request header{
'X-Requested-With'?: string | undefined;
[key: string]: unknown;
}		--
withCredentialsWhether to allow requests to carry cookiesbooleantrue-
beforeUploadOptional parameters, see beforeUpload

signature:
params:
file: All file
options: Parameters		(file: UploadFile, options: BeforeUploadOption) => boolean | object | unknownfunc.noop-
onProgressOnProgress Callback(file: ObjectFile[], e: ObjectFile) => voidfunc.noop-
onSuccessOptional parameters, upload success callback function, the parameter is the response information and file

signature:
params:
file: File
value: Value		(file: ObjectFile, value?: ObjectFile[]) => voidfunc.noop-
onErrorOptional parameters, upload failure callback function, the parameter is the upload failure information, response information and file

signature:
params:
file: Error file
value: Current value		(file: ObjectFile, value: ObjectFile[]) => voidfunc.noop-
childrenChild elementsReactNode--
timeoutUpload timeout, unit msnumber--
methodUpload method'post' | 'put' | 'POST' | 'PUT''post'-
requestCustom upload method

signature:
params:
option: Parameters
return:
Object with abort method		(option: object) => object--
nameFile name fieldstring--
onSelectSelect file callback(uploadFiles: Array<unknown>, value: Array<unknown>) => voidfunc.noop-
onDropDrop file(files: UploadFile[]) => voidfunc.noop-
valueFile listArray<ObjectFile> | ObjectFile--
defaultValueDefault file listArray<ObjectFile> | ObjectFile--
listTypeUpload list styleListType--
formatterData formatting function, used with custom action, the parameter is the response data of the server, see formatter

signature:
params:
response: Return
file: File object		(response: UploadResponse, file: UploadFile) => UploadResponse--
limitMaximum number of file uploadsnumberInfinity-
dragableOptional parameters, whether to support drag and drop upload, ie10+ supports.boolean--
useDataURLOptional parameters, whether to locally previewboolean--
disabledOptional parameters, whether to disable uploadboolean--
onChangeUpload file change status

signature:
params:
value: Value
file: File object		(value: ObjectFile[], file: ObjectFile | ObjectFile[]) => voidfunc.noop-
afterSelectOptional parameters, used to validate files, afterSelect only takes effect when autoUpload=false, autoUpload=true can be used to replace this function

signature:
params:
file: File
return:
Return false will block upload, other means normal		(file: ObjectFile) => boolean | Promise<void>func.noop-
onRemoveRemove file callback function

signature:
params:
file: File
return:
Return false、Promise.resolve(false)、Promise.reject() will block file deletion		(file: object) => voidfunc.noop-
autoUploadAutomatic uploadbooleantrue-
progressPropsPass to Progress propsProgressProps--
isPreviewIs previewboolean--
renderPreviewPreview mode

signature:
params:
value: File		(value: ObjectFile | ObjectFile[], props: UploadProps) => void--
fileKeyNameFile object key namestring-1.21
fileNameRenderCustom file name rendering

signature:
params:
file: File
return:
React node		(file: object) => ReactNode--
actionRenderCustom operation area rendering

signature:
params:
file: File
return:
React node		(file: ObjectFile) => ReactNode--
previewOnFileNameClick file nameboolean-1.24
itemRenderCustomize success and failure list rendering, only in listType is card or image(file: UploadFile, action?: { remove?: () => void }) => ReactNode--
reUploadSelect new file upload and replaceboolean--
\n

Upload.Card #

\n

继承 Upload 的 API，除非特别说明

\n

Inheritance Upload API, unless otherwise specified

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParamDescriptionTypeDefault ValueRequiredSupported Version
onPreviewClick image callback(file: ObjectFile, e?: MouseEvent<HTMLElement>) => voidfunc.noop-
onChangeChange callback(value: UploadFile[], file: UploadFile) => voidfunc.noop-
onRemoveClick remove callback(file: object) => void--
onCancelCancel upload callback() => void--
itemRenderCustomize success and failure list rendering，only in listType is card or image

signature:
params:
file: File object
action: Contains properties remove: delete callback		(file: ObjectFile, action?: { remove?: () => void }) => ReactNode-1.21
reUploadSelect new file upload and replaceboolean-1.24
showDownloadShow download buttonbooleantrue1.24
onProgressOnProgress Callback(file: UploadFile[], e: UploadFile) => voidfunc.noop-
\n

Upload.Dragger #

\n

IE10+ 支持。继承 Upload 的 API，除非特别说明

\n

IE10+ supports. Inheritance Upload API, unless otherwise specified

\n

Upload.Selecter #

\n

[底层能力] 可自定义样式的文件选择器

\n

[Underlying capabilities] Customizable file selector

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParamDescriptionTypeDefault ValueRequired
disabledWhether to disable uploadboolean-
multipleWhether to support multiple file selection, ie10+ supportsbooleanfalse
webkitdirectoryWhether to support upload folder, only in chromeboolean-
captureCall system device mediastring-
dragableWhether to support drag and drop upload, ie10+ supportsboolean-
acceptAccepted file typesstring-
onSelectFile selection callback(e: UploadFile[]) => voidfunc.noop
onDragOverDrag over callback(e: DragEvent<HTMLInputElement>) => voidfunc.noop
onDragLeaveDrag leave callback() => voidfunc.noop
onDropDrag complete callback(fiels: File[]) => voidfunc.noop
\n

Method #

\n

Upload.Uploader #

\n
\n

[Basic Ability] File Upload Core Ability\nlet uploader = new Upload.Uploader([options]);

\n
\n

options

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParamDescripitonTypeDefault Value
actionupload urlString-
dataextra upload dataObject/Function-
headersupload request headersObject-
withCredentialsAllow request with cookie or notBooleanfalse
onProgresscallback when upload progress change

signature:
Function() => void		Functionnoop
onSuccesscallback when upload success

signature:
Function() => void		Functionnoop
onErrorcallback when upload failed

signature:
Function() => void		Functionnoop
\n

Custom Request #

\n

某些场景下需要自定义Request,例如对接AWS S3 jd-sdk or aliyun oss sdk. Upload 支持 传入自定义的 request方法.\nUnder some circumstances, a developer may want to overriding default request call method， just like using AWS S3 jd-sdk or aliyun oss sdk. Upload has a prop named request.

\n
function customRequest(option) {\n    /* coding here */\n    return {abort() {/* coding here */}};\n}\n\n<Upload request={customRequest}/>\n
\n

a object named 'option' will be pass into customRequest method and it's schema:

\n
    onProgress: (event: { percent: number }): void\n    onError: (event: Error, body?: Object): void\n    onSuccess: (body: Object): void\n    data: Object // 额外的数据\n    filename: String // 文件名\n    file: File // 原生File对象\n    withCredentials: Boolean // 是否携带cookie\n    action: String // 请求地址\n    method: String // 请求类型 post/put\n    timeout: Number // 超时\n    headers: Object // 请求头\n
\n

customRequest should return a object with a abort method which can abort a request

\n
abort(file?: File) => void: abort the uploading file\n
\n

customRequest implements reference: https://github.com/alibaba-fusion/next/blob/master/src/upload/runtime/request.jsx

\n

ErrorCode #

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ErrorCodedescription
EXCEED_LIMITwhen limit is set , selected files number + uploaded files number > limit
BEFOREUPLOAD_REJECTBeforeUpload method returns false/Promise.resolve(false)/Promise.reject()
RESPONSE_FAILResponse Error
\n

All the ErrorCode in Upload.ErrorCode.

\n

onChange Return Data Schema #

\n
    {\n      uid: 'uid',       // file unique ID\n      name: 'xx.png'    // filename\n      state: 'done',    // selected uploading done error\n      response: {"success":true}  // server response\n      url: 'https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg',\n      imgURL: 'https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg', //optional\n      downloadURL: 'https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg' // optional\n    }\n
\n

API Response Data Schema #

\n
    {\n      "success": true,\n      "message": "upload success",                           // display when success=false\n      "url": "https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg"             // file url\n      "imgURL": "https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg",         // file preview url(optional)\n      "downloadURL": "https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg",    // file download url(optional)\n    }\n
\n

Server Side Response Format #

\n

Use formatter to transfer nonstandard data to standard data

\n\n

Server side code example #

\n

Next Upload components upload files by sending multipart/form-data type request.

\n

It is no doubt that every kind of server side framework can deal with multipart/form-data type request and extract files from request body. Now we give out 2 examples

\n\n

IE9 Compatibility #

\n\n

Assume that your form page url domain：shop.taobao.com, while the file server url is upload.taobao.com. Server side should return data with a extra script tag

\n
    <script>document.domain="taobao.com";</script>\n    {"status":1,"type":"ajax","name":"54.png","url":".\\/files\\/54.png"}\n
\n

iframe upload will request with a param _documentDomain. You can set your domain

\n

ARIA and KeyBoard #

\n\n\n\n\n\n\n\n\n\n\n\n\n\n
KeyBoardDescripiton
Enter1. When the component gets the focus, press Enter to select the file upload 2. Delete uploaded image
\n"}