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

92 lines
5.4 KiB
Markdown
Raw Normal View History

2016-08-25 09:46:19 +08:00
---
category: Components
type: Data Entry
2016-09-21 11:28:38 +08:00
title: Upload
2016-08-25 09:46:19 +08:00
---
2016-09-18 11:08:54 +08:00
Upload file by selecting or dragging.
2016-08-25 09:46:19 +08:00
2016-09-10 13:43:30 +08:00
## When To Use
2016-08-25 09:46:19 +08:00
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.
## API
meger feature to master (#16421) * use ul in list * update snapshot * update comment * feat: TreeSelect support `showSearch` in multiple mode (#15933) * update rc-tree-select * typo * update desc & snapshot * update desc & snapshot * check default showSearch * feat: table customizing variable (#15971) * feat: added table selected row color variable * fix: @table-selected-row-color default is inherit * feat: Upload support customize previewFile (#15984) * support preview file * use promise * dealy load * use canvas of render * use domHook of test * update demo * add snapshot * update types * update testcase * feat: form customizing variables (#15954) * fix: added styling form input background-color * feat: added '@form-warning-input-bg' variable * feat: added '@form-error-input-bg' variable * use li wrap with comment * feat: Support append theme less file with less-variable (#16118) * add override * add override support * update doc * feat: dropdown support set right icon * docs: update doc of dropdown component * style: format dropdown-button.md * test: update updateSnapshot * style: format dropdown-button.md * test: update updateSnapshot * test: update updateSnapshot * style: change style of dropdown-button demo * fix: fix document table order * feat: Support SkeletonAvatarProps.size accept number (#16078) (#16128) * chore:update style of demo * feat: Notification functions accept top, bottom and getContainer as arguments * drawer: add afterVisibleChange * rm onVisibleChange * update * feat: 🇭🇷 hr_HR locale (#16258) * Added Croatian locale * fixed lint error * :white_check_mark: Add test cases for hr_HR * :memo: update i18n documentation * feat: add `htmlFor` in Form.Item (#16278) * add htmlFor in Form.Item * update doc * feat: Button support `link` type (#16289) close #15892 * feat: Add Timeline.Item.position (#16148) (#16193) * fix: Timeline.pendingDot interface documentation there is a small problem (#16177) * feat: Add Timeline.Item.position (#16148) * doc: add version infomation for Timeline.Item.position * refactor: Update Tree & TreeSelect deps (#16330) * use CSSMotion * update snapshot * feat: Collapse support `expandIconPosition` (#16365) * update doc * support expandIconPosition * update snapshot * feat: Breadcrumb support DropDown (#16315) * breadcrumbs support drop down menu * update doc * add require less * fix test * fix md doc * less code * fix style warning * update snap * add children render test * feat: TreeNode support checkable * feat: add optional to support top and left slick dots (#16186) (#16225) * add optional to support top and left slick dots * update carousel snapshot * Update doc, add placement demo * update carousel placement demo snapshots * rename dots placement to position * update vertical as deprecated * rename dotsPosition to dotPosition * refine code * add warning testcase for vertical * remove unused warning * update expression * Additional test case for dotPosition * refactor: Upgrade `rc-tree-select` to support pure React motion (#16402) * upgrade `rc-tree-select` * update snapshot * 3.17.0 changelog * fix warning * fix review warning
2019-05-06 12:04:39 +08:00
| Property | Description | Type | Default | Version |
2019-05-07 14:57:32 +08:00
| --- | --- | --- | --- | --- |
| accept | File types that can be accepted. See [input accept Attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept) | string | - | |
| action | Uploading URL | string\|(file) => `Promise` | - | |
| method | http method of upload request | string | 'post' | |
| directory | support upload whole directory ([caniuse](https://caniuse.com/#feat=input-file-directory)) | boolean | false | |
2019-05-07 14:57:32 +08:00
| beforeUpload | Hook function which will be executed before uploading. Uploading will be stopped with `false` or a rejected Promise returned. **Warningthis function is not supported in IE9**。 | (file, fileList) => `boolean | Promise` | - | |
| customRequest | override for the default xhr behavior allowing for additional customization and ability to implement your own XMLHttpRequest | Function | - | |
| data | Uploading extra params or function which can return uploading extra params. | object\|function(file) | - | |
2019-05-07 14:57:32 +08:00
| defaultFileList | Default list of files that have been uploaded. | object\[] | - | |
| disabled | disable upload button | boolean | false | |
| fileList | List of files that have been uploaded (controlled). Here is a common issue [#2423](https://github.com/ant-design/ant-design/issues/2423) when using it | object\[] | - | |
| headers | Set request headers, valid above IE10. | object | - | |
| listType | Built-in stylesheets, support for three types: `text`, `picture` or `picture-card` | string | 'text' | |
| multiple | Whether to support selected multiple file. `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' | |
| previewFile | Customize preview file logic | (file: File \| Blob) => Promise<dataURL: string> | - | |
| isImageUrl | Customize if render <img /> in thumbnail | (file: UploadFile) => boolean | [inside implementation](https://github.com/ant-design/ant-design/blob/4ad5830eecfb87471cd8ac588c5d992862b70770/components/upload/utils.tsx#L47-L68) | |
| showUploadList | Whether to show default upload list, could be an object to specify `showPreviewIcon`, `showRemoveIcon`, `showDownloadIcon`, `removeIcon` and `downloadIcon` individually | Boolean or { showPreviewIcon?: boolean, showDownloadIcon?: boolean, showRemoveIcon?: boolean, removeIcon?: React.ReactNode, downloadIcon?: React.ReactNode } | true | |
2019-05-07 14:57:32 +08:00
| supportServerRender | Need to be turned on while the server side is rendering | boolean | false | |
| withCredentials | ajax upload with cookie sent | boolean | false | |
| openFileDialogOnClick | click open file dialog | boolean | true | |
2019-05-07 14:57:32 +08:00
| onChange | A callback function, can be executed when uploading state is changing, see [onChange](#onChange) | Function | - | |
| onPreview | A callback function, will be executed when 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 return value is `false` or a Promise which resolve(false) or reject | Function(file): `boolean | Promise` | - | |
| onDownload | Click the method to download the file, pass the method to perform the method logic, do not pass the default jump to the new TAB. | Function(file): void | Jump to new TAB | |
| transformFile   | Customize transform file before request | Function(file): `string | Blob | File | Promise<string | Blob | File>` | - | |
| iconRender | custom show icon | (file: UploadFile, listType?: UploadListType) => React.ReactNode | - | |
2016-08-25 09:46:19 +08:00
### onChange
2019-01-04 11:13:55 +08:00
> The function will be called when uploading is in progress, completed or failed.
2016-08-25 09:46:19 +08:00
When uploading state change, it returns:
```js
{
file: { /* ... */ },
fileList: [ /* ... */ ],
event: { /* ... */ },
}
```
1. `file` File object for the current operation.
```js
{
2019-02-06 20:51:46 +08:00
uid: 'uid', // unique identifier, negative is recommend, to prevent interference with internal generated id
name: 'xx.png', // file name
2017-10-09 13:23:20 +08:00
status: 'done', // optionsuploading, done, error, removed
response: '{"status": "success"}', // response from server
linkProps: '{"download": "image"}', // additional html props of file link
xhr: 'XMLHttpRequest{ ... }', // XMLHttpRequest Header
2016-08-25 09:46:19 +08:00
}
```
2016-09-18 11:08:54 +08:00
2016-08-25 09:46:19 +08:00
2. `fileList` current list of files
3. `event` response from server, including uploading progress, supported by advanced browsers.
2019-01-04 11:13:55 +08:00
## FAQ
### How to implement upload server side?
- You can consult [jQuery-File-Upload](https://github.com/blueimp/jQuery-File-Upload/wiki#server-side) about how to implement server side upload interface.
- There is a mock example of [express](https://github.com/react-component/upload/blob/master/server.js) in rc-upload.
### I want to display download links.
2016-08-25 09:46:19 +08:00
2019-01-04 11:13:55 +08:00
Please set property `url` of each item in `fileList` to control content of link.
2016-08-25 09:46:19 +08:00
2019-01-04 11:13:55 +08:00
### How to use `customRequest`?
2019-01-04 11:13:55 +08:00
See <https://github.com/react-component/upload#customrequest>.