Uploader - Vant 4
Uploader
Intro
Used to upload a local image or file to the server and display a preview image and upload progress during the upload process. The Uploader component does not currently contain the interface logic for uploading files to the server, this step needs to be implemented by the user.
Install
Register component globally via app.use, refer to Component Registration for more registration ways.
import { createApp } from'vue'; import { Uploader } from'vant'; const app = createApp(); app.use(Uploader);Usage
Basic Usage
exportdefault { setup() { constafterRead = (file) => { console.log(file); }; return { afterRead, }; }, };Preview File
import { ref } from'vue'; exportdefault { setup() { const fileList = ref([ { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' }, { url: 'https://cloud-image', isImage: true }, ]); return { fileList, }; }, };Upload Status
import { ref } from'vue'; exportdefault { setup() { const fileList = ref([ { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg', status: 'uploading', message: 'Uploading...', }, { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg', status: 'failed', message: 'Failed', }, ]); constafterRead = (file) => { file.status = 'uploading'; file.message = 'Uploading...'; setTimeout(() => { file.status = 'failed'; file.message = 'Failed'; }, 1000); }; return { fileList, afterRead, }; }, };Max Count
import { ref } from'vue'; exportdefault { setup() { const fileList = ref([]); return { fileList, }; }, };Max Size
import { showToast } from'vant'; exportdefault { setup() { constonOversize = (file) => { console.log(file); showToast('File size cannot exceed 500kb'); }; return { onOversize, }; }, };If you need to make different size limits for different types of files, you can pass a function to the max-size props.
exportdefault { setup() { constisOverSize = (file) => { const maxSize = file.type === 'image/jpeg' ? 500 * 1024 : 1000 * 1024; return file.size >= maxSize; }; return { isOverSize, }; }, };Custom Upload Area
Preview Cover
Preview Size
Using preview-size prop to custom the size of preview image.
You can set the width and height separately.
Before Read
import { showToast } from'vant'; exportdefault { setup() { // ���ز���ֵconstbeforeRead = (file) => { if (file.type !== 'image/jpeg') { showToast('Please upload an image in jpg format'); returnfalse; } returntrue; }; // ���� PromiseconstasyncBeforeRead = (file) => newPromise((resolve, reject) => { if (file.type !== 'image/jpeg') { showToast('Please upload an image in jpg format'); reject(); } else { const img = newFile(['foo'], 'bar.jpg', { type: 'image/jpeg', }); resolve(img); } }); return { beforeRead, asyncBeforeRead, }; }, };Disable Uploader
Use disabled prop to disable uploader.
Customize Single Preview Image Style
import { ref } from'vue'; import { showToast } from'vant'; exportdefault { setup() { const fileList = ref([ { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/sand.jpeg', deletable: true, beforeDelete: () => { showToast( 'Customize the events and styles of a single preview image', ); }, }, { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg', imageFit: 'contain', }, ]); return { fileList }; }, };Enable Reupload
import { ref } from'vue'; exportdefault { setup() { const fileList = ref([ { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' }, ]); return { fileList }; }, };API
Props
| Attribute | Description | Type | Default |
|---|---|---|---|
| v-model | List of uploaded files | FileListItem[] | - |
| accept | Accepted file type | string | image/* |
| name | Input name, usually a unique string or number | number | string | - | | preview-size | Size of preview image | number | string | Array | 80px | | preview-image | Whether to show image preview | boolean | true | | preview-full-image | Whether to show full screen image preview when image is clicked | boolean | true | | preview-options | Options of full screen image preview, see ImagePreview | object | - |
| multiple | Whether to enable multiple selection pictures | boolean | false | | disabled | Whether to disabled the upload | boolean | false | | readonly | Whether to make upload area readonly | boolean | false | | deletable | Whether to show delete icon | boolean | true | | reupload v4.4.0 | Whether to enable reupload, if enabled, the image preview will be disabled | boolean | false | | show-upload | Whether to show upload area | boolean | true | | lazy-load | Whether to enable lazy load, should register Lazyload component | boolean | false |
| capture | Capture, can be set to camera | string | - | | after-read | Hook after reading the file | Function | - | | before-read | Hook before reading the file, return false to stop reading the file, can return Promise | Function | - | | before-delete | Hook before delete the file, return false to stop deleting the file, can return Promise | Function | - | | max-size | Max size of file | number | string | (file: File) => boolean | Infinity | | max-count | Max count of image | number | string | Infinity | | result-type | Type of file read result, can be set to file``text | string | dataUrl | | upload-text | Upload text | string | - | | image-fit | Preview image fit mode | string | cover | | upload-icon | Upload icon | string | photograph |
Tips: accept, capture and multiple are the attributes of the native input tag, there may be some compatibility issues under different systems and WebView.
Events
| Event | Description | Arguments |
|---|---|---|
| oversize | Emitted when file size over limit | Same as after-read |
| click-upload | Emitted when click upload area | event: MouseEvent |
| click-preview | Emitted when preview image is clicked | Same as after-read |
| click-reupload | Emitted when reupload image is clicked | Same as after-read |
| close-preview | Emitted when the full screen image preview is closed | - |
| delete | Emitted when preview file is deleted | Same as after-read |
Slots
| Name | Description | SlotProps |
|---|---|---|
| default | Custom upload area | - |
| preview-delete | Custom delete icon | - |
| preview-cover | Custom content that covers the image preview | item: FileListItem |
Parameters of before-read��before-delete
| Attribute | Description | Type |
|---|---|---|
| file | File object | object |
| detail | Detail info, contains name and index | object |
Parameters of after-read
| Attribute | Description | Type |
|---|---|---|
| file | Contains File object | *UploaderFileListItem |
| detail | Detail info, contains name and index | object |
ResultType
| Value | Description |
|---|---|
| file | Result contains File object |
| text | Result contains File object and text content |
| dataUrl | Result contains File object and base64 content |
Methods
Use ref to get Uploader instance and call instance methods.
| Name | Description | Attribute | Return value |
|---|---|---|---|
| closeImagePreview | Close full screen image preview | - | - |
| chooseFile | Trigger choosing files, works with the user action context only because of browser security | - | - |
reuploadFile 4.9.3 | Trigger choosing files, choosing a new file will overwrite the previously uploaded file, works with the user action context only because of browser security | index: number | - |
Types
The component exports the following type definitions:
importtype { UploaderProps, UploaderInstance, UploaderResultType, UploaderFileListItem, UploaderBeforeRead, UploaderAfterRead, } from'vant';UploaderInstance is the type of component instance:
import { ref } from'vue'; importtype { UploaderInstance } from'vant'; const uploaderRef = ref<UploaderInstance>(); uploaderRef.value?.chooseFile();Theming
CSS Variables
The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.
| Name | Default Value | Description |
|---|---|---|
| --van-uploader-size | 80px | - |
| --van-uploader-icon-size | 24px | - |
| --van-uploader-icon-color | var(--van-gray-4) | - |
| --van-uploader-text-color | var(--van-text-color-2) | - |
| --van-uploader-text-font-size | var(--van-font-size-sm) | - |
| --van-uploader-upload-background | var(--van-gray-1) | - |
| --van-uploader-upload-active-color | var(--van-active-color) | - |
| --van-uploader-delete-color | var(--van-white) | - |
| --van-uploader-delete-icon-size | 14px | - |
| --van-uploader-delete-background | rgba(0, 0, 0, 0.7) | - |
| --van-uploader-file-background | var(--van-background) | - |
| --van-uploader-file-icon-size | 20px | - |
| --van-uploader-file-icon-color | var(--van-gray-7) | - |
| --van-uploader-file-name-padding | 0 var(--van-padding-base) | - |
| --van-uploader-file-name-margin-top | var(--van-padding-xs) | - |
| --van-uploader-file-name-font-size | var(--van-font-size-sm) | - |
| --van-uploader-file-name-text-color | var(--van-gray-7) | - |
| --van-uploader-mask-text-color | var(--van-white) | - |
| --van-uploader-mask-background | fade(var(--van-gray-8), 88%) | - |
| --van-uploader-mask-icon-size | 22px | - |
| --van-uploader-mask-message-font-size | var(--van-font-size-sm) | - |
| --van-uploader-mask-message-line-height | var(--van-line-height-xs) | - |
| --van-uploader-loading-icon-size | 22px | - |
| --van-uploader-loading-icon-color | var(--van-white) | - |
| --van-uploader-disabled-opacity | var(--van-disabled-opacity) | - |
| --van-uploader-border-radius | 0px | - |
FAQ
How do I know if the user has granted camera permission?
When uploading an image, if the user has not granted camera permission to the current app, the Uploader component will not work.
You can determine if camera permission has been granted by using the getUserMedia method provided by the browser (please note that the getUserMedia method cannot be used in iOS 10).
Here is a simplified example:
navigator.mediaDevices .getUserMedia({ video: true }) .then((stream) => { console.log(stream); }) .catch((err) => { console.log(err); });