Upload
Radio Upload Image
Multi-Select Upload Images
Component Status
Style Custom
Upload Props
| name | type | default | description | required |
|---|---|---|---|---|
| accept | String | - | File types that can be accepted. W3C，MDN | N |
| action | String | - | Uploading URL | N |
| addContent | String / Slot / Function | - | Typescript：string \| TNode。see more ts definition | N |
| allowUploadDuplicateFile | Boolean | false | allow to upload duplicate name files | N |
| autoUpload | Boolean | true | post upload request automatically after files being selected | N |
| beforeUpload | Function | - | stop one of files to upload。Typescript：(file: UploadFile) => boolean \| Promise<boolean> | N |
| capture | String | - | - | N |
| data | Object | - | extra request data of uploading. formatRequest can redefine all request data。Typescript：Record<string, any> \| ((files: UploadFile[]) => Record<string, any>) | N |
| disabled | Boolean | undefined | make upload to be disabled | N |
| files | Array | [] | v-model:files is supported。Typescript：Array<T> | N |
| defaultFiles | Array | [] | uncontrolled property。Typescript：Array<T> | N |
| format | Function | - | to redefine UploadFile data structure。Typescript：(file: File) => UploadFile | N |
| formatRequest | Function | - | redefine request data。Typescript：(requestData: { [key: string]: any }) => { [key: string]: any } | N |
| formatResponse | Function | - | redefine response data structure。Typescript：(response: any, context: FormatResponseContext) => ResponseType type ResponseType = { error?: string; url?: string } & Record<string, any> interface FormatResponseContext { file: UploadFile; currentFiles?: UploadFile[] }。see more ts definition | N |
| headers | Object | - | HTTP Request Header。Typescript：{[key: string]: string} | N |
| imageProps | Object | - | Typescript：ImageProps，Image API Documents。see more ts definition | N |
| max | Number | 0 | max count of files limit | N |
| method | String | POST | HTTP request method。options: POST/GET/PUT/OPTIONS/PATCH/post/get/put/options/patch | N |
| multiple | Boolean | false | multiple files uploading | N |
| preview | Boolean | true | - | N |
| requestMethod | Function | - | custom upload request method。Typescript：(files: UploadFile \| UploadFile[]) => Promise<RequestMethodResponse> interface RequestMethodResponse { status: 'success' \| 'fail'; error?: string; response: { url?: string; files?: UploadFile[]; [key: string]: any } }。see more ts definition | N |
| sizeLimit | Number / Object | - | files size limit。Typescript：number \| SizeLimitObj interface SizeLimitObj { size: number; unit: SizeUnit ; message?: string } type SizeUnitArray = ['B', 'KB', 'MB', 'GB'] type SizeUnit = SizeUnitArray[number]。see more ts definition | N |
| useMockProgress | Boolean | true | use mock progress, instead of real progress | N |
| value | Array | [] | file list。v-model and v-model:value is supported。Typescript：Array<T> | N |
| defaultValue | Array | [] | file list。uncontrolled property。Typescript：Array<T> | N |
| withCredentials | Boolean | false | uploading request with cookie | N |
| onChange | Function | Typescript：(value: Array<T>, context: UploadChangeContext) => voidtrigger on uploaded files change。see more ts definition。 interface UploadChangeContext { e?: MouseEvent \| ProgressEvent; response?: any; trigger: UploadChangeTrigger; index?: number; file?: UploadFile; files?: UploadFile[] }type UploadChangeTrigger = 'add' \| 'remove' \| 'abort' \| 'progress-success' \| 'progress' \| 'progress-fail' | N | |
| onClickUpload | Function | Typescript：(context: { e: MouseEvent }) => void | N | |
| onFail | Function | Typescript：(options: UploadFailContext) => voidresponse.error used for error tips, formatResponse can format response。see more ts definition。interface UploadFailContext { e?: ProgressEvent; failedFiles: UploadFile[]; currentFiles: UploadFile[]; response?: any; file: UploadFile; XMLHttpRequest?: XMLHttpRequest} | N | |
| onPreview | Function | Typescript：(options: { file: UploadFile; index: number; e: MouseEvent }) => voidtrigger on preview elements click | N | |
| onProgress | Function | Typescript：(options: ProgressContext) => voiduploading request progress event。see more ts definition。 interface ProgressContext { e?: ProgressEvent; file?: UploadFile; currentFiles: UploadFile[]; percent: number; type: UploadProgressType; XMLHttpRequest?: XMLHttpRequest }type UploadProgressType = 'real' \| 'mock' | N | |
| onRemove | Function | Typescript：(context: UploadRemoveContext) => voidtrigger on file removed。see more ts definition。 interface UploadRemoveContext { index?: number; file?: UploadFile; e: MouseEvent } | N | |
| onSelectChange | Function | Typescript：(files: File[], context: UploadSelectChangeContext) => voidtrigger after file choose and before upload。see more ts definition。 interface UploadSelectChangeContext { currentSelectedFiles: UploadFile[] } | N | |
| onSuccess | Function | Typescript：(context: SuccessContext) => voidtrigger on all files uploaded successfully。see more ts definition。 interface SuccessContext { e?: ProgressEvent; file?: UploadFile; fileList?: UploadFile[]; currentFiles?: UploadFile[]; response?: any; results?: SuccessContext[]; XMLHttpRequest?: XMLHttpRequest } | N | |
| onValidate | Function | Typescript：(context: { type: UploadValidateType, files: UploadFile[] }) => voidtrigger on length over limit, or trigger on file size over limit。see more ts definition。 type UploadValidateType = 'FILE_OVER_SIZE_LIMIT' \| 'FILES_OVER_LENGTH_LIMIT' \| 'FILTER_FILE_SAME_NAME' \| 'BEFORE_ALL_FILES_UPLOAD' \| 'CUSTOM_BEFORE_UPLOAD' | N |
Upload Events
| name | params | description |
|---|---|---|
| change | (value: Array<T>, context: UploadChangeContext) | trigger on uploaded files change。see more ts definition。interface UploadChangeContext { e?: MouseEvent \| ProgressEvent; response?: any; trigger: UploadChangeTrigger; index?: number; file?: UploadFile; files?: UploadFile[] }type UploadChangeTrigger = 'add' \| 'remove' \| 'abort' \| 'progress-success' \| 'progress' \| 'progress-fail' |
| click-upload | (context: { e: MouseEvent }) | - |
| fail | (options: UploadFailContext) | response.error used for error tips, formatResponse can format response。see more ts definition。interface UploadFailContext { e?: ProgressEvent; failedFiles: UploadFile[]; currentFiles: UploadFile[]; response?: any; file: UploadFile; XMLHttpRequest?: XMLHttpRequest} |
| preview | (options: { file: UploadFile; index: number; e: MouseEvent }) | trigger on preview elements click |
| progress | (options: ProgressContext) | uploading request progress event。see more ts definition。interface ProgressContext { e?: ProgressEvent; file?: UploadFile; currentFiles: UploadFile[]; percent: number; type: UploadProgressType; XMLHttpRequest?: XMLHttpRequest }type UploadProgressType = 'real' \| 'mock' |
| remove | (context: UploadRemoveContext) | trigger on file removed。see more ts definition。interface UploadRemoveContext { index?: number; file?: UploadFile; e: MouseEvent } |
| select-change | (files: File[], context: UploadSelectChangeContext) | trigger after file choose and before upload。see more ts definition。interface UploadSelectChangeContext { currentSelectedFiles: UploadFile[] } |
| success | (context: SuccessContext) | trigger on all files uploaded successfully。see more ts definition。interface SuccessContext { e?: ProgressEvent; file?: UploadFile; fileList?: UploadFile[]; currentFiles?: UploadFile[]; response?: any; results?: SuccessContext[]; XMLHttpRequest?: XMLHttpRequest } |
| validate | (context: { type: UploadValidateType, files: UploadFile[] }) | trigger on length over limit, or trigger on file size over limit。see more ts definition。type UploadValidateType = 'FILE_OVER_SIZE_LIMIT' \| 'FILES_OVER_LENGTH_LIMIT' \| 'FILTER_FILE_SAME_NAME' \| 'BEFORE_ALL_FILES_UPLOAD' \| 'CUSTOM_BEFORE_UPLOAD' |
UploadFile
| name | type | default | description | required |
|---|---|---|---|---|
| lastModified | Number | - | - | N |
| name | String | - | - | N |
| percent | Number | - | - | N |
| raw | Object | - | Typescript：File | N |
| response | Object | - | Typescript：{ [key: string]: any } | N |
| size | Number | - | - | N |
| status | String | - | Typescript： 'success' \| 'fail' \| 'progress' \| 'waiting' | N |
| type | String | - | - | N |
| uploadTime | String | - | upload time | N |
| url | String | - | - | N |
PlainObject | - | - | PlainObject is not an attribute of UploadFile，it means you can add and attributes to UploadFile, type PlainObject = {[key: string]: any}' | N |
CSS Variables
The component provides the following CSS variables, which can be used to customize styles.
| Name | Default Value | Description |
|---|---|---|
| --td-upload-add-color | @font-gray-3 | - |
| --td-upload-add-icon-font-size | 28px | - |
| --td-upload-background | @upload-add-bg-color | - |
| --td-upload-delete-icon-color | @font-white-1 | - |
| --td-upload-grid-columns | 4 | - |
| --td-upload-height | 80px | - |
| --td-upload-radius | @radius-default | - |
| --td-upload-width | 80px | - |
何时使用
当需要进行图片上传时使用。
组件搭配使用
通常用于图片上传，点击上传按钮可唤起动作面板，供用户选择不同渠道进行新的上传。
点击已经上传的图片可跳转图片预览，让用户对已上传的图片进行快速查看。
推荐/慎用示例
若上传的文件有尺寸、格式、数量限制，推荐在文案中进行明确标识。
上传特定证件图片，特别是涉及到证件正反面时，推荐结合图示进行上传指引，更加直观。
