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.
\nRegister component globally via app.use, refer to Component Registration for more registration ways.
import { createApp } from 'vue';\nimport { Uploader } from 'vant';\n\nconst app = createApp();\napp.use(Uploader);\n<van-uploader :after-read="afterRead" />\nexport default {\n setup() {\n const afterRead = (file) => {\n console.log(file);\n };\n\n return {\n afterRead,\n };\n },\n};\n<van-uploader v-model="fileList" multiple />\nimport { ref } from 'vue';\n\nexport default {\n setup() {\n const fileList = ref([\n { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' },\n { url: 'https://cloud-image', isImage: true },\n ]);\n\n return {\n fileList,\n };\n },\n};\n<van-uploader v-model="fileList" :after-read="afterRead" />\nimport { ref } from 'vue';\n\nexport default {\n setup() {\n const fileList = ref([\n {\n url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg',\n status: 'uploading',\n message: 'Uploading...',\n },\n {\n url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg',\n status: 'failed',\n message: 'Failed',\n },\n ]);\n\n const afterRead = (file) => {\n file.status = 'uploading';\n file.message = 'Uploading...';\n\n setTimeout(() => {\n file.status = 'failed';\n file.message = 'Failed';\n }, 1000);\n };\n\n return {\n fileList,\n afterRead,\n };\n },\n};\n<van-uploader v-model="fileList" multiple :max-count="2" />\nimport { ref } from 'vue';\n\nexport default {\n setup() {\n const fileList = ref([]);\n\n return {\n fileList,\n };\n },\n};\n<van-uploader multiple :max-size="500 * 1024" @oversize="onOversize" />\nimport { showToast } from 'vant';\n\nexport default {\n setup() {\n const onOversize = (file) => {\n console.log(file);\n showToast('File size cannot exceed 500kb');\n };\n\n return {\n onOversize,\n };\n },\n};\nIf you need to make different size limits for different types of files, you can pass a function to the max-size props.
<van-uploader multiple :max-size="isOverSize" />\nexport default {\n setup() {\n const isOverSize = (file) => {\n const maxSize = file.type === 'image/jpeg' ? 500 * 1024 : 1000 * 1024;\n return file.size >= maxSize;\n };\n return {\n isOverSize,\n };\n },\n};\n<van-uploader>\n <van-button icon="plus" type="primary">Upload Image</van-button>\n</van-uploader>\n<van-uploader v-model="fileList">\n <template #preview-cover="{ file }">\n <div class="preview-cover van-ellipsis">{{ file.name }}</div>\n </template>\n</van-uploader>\n\n<style>\n .preview-cover {\n position: absolute;\n bottom: 0;\n box-sizing: border-box;\n width: 100%;\n padding: 4px;\n color: #fff;\n font-size: 12px;\n text-align: center;\n background: rgba(0, 0, 0, 0.3);\n }\n</style>\nUsing preview-size prop to custom the size of preview image.
<!-- The default unit is px -->\n<van-uploader v-model="fileList" preview-size="60" />\n<!-- Support other units, such as rem, vh, vw -->\n<van-uploader v-model="fileList" preview-size="5rem" />\nYou can set the width and height separately.
\n<van-uploader v-model="fileList" :preview-size="[60, 40]" />\n<van-uploader :before-read="beforeRead" />\nimport { showToast } from 'vant';\n\nexport default {\n setup() {\n // \u8FD4\u56DE\u5E03\u5C14\u503C\n const beforeRead = (file) => {\n if (file.type !== 'image/jpeg') {\n showToast('Please upload an image in jpg format');\n return false;\n }\n return true;\n };\n\n // \u8FD4\u56DE Promise\n const asyncBeforeRead = (file) =>\n new Promise((resolve, reject) => {\n if (file.type !== 'image/jpeg') {\n showToast('Please upload an image in jpg format');\n reject();\n } else {\n const img = new File(['foo'], 'bar.jpg', {\n type: 'image/jpeg',\n });\n resolve(img);\n }\n });\n\n return {\n beforeRead,\n asyncBeforeRead,\n };\n },\n};\nUse disabled prop to disable uploader.
<van-uploader disabled />\n<van-uploader v-model="fileList" :deletable="false" />\nimport { ref } from 'vue';\nimport { showToast } from 'vant';\n\nexport default {\n setup() {\n const fileList = ref([\n {\n url: 'https://fastly.jsdelivr.net/npm/@vant/assets/sand.jpeg',\n deletable: true,\n beforeDelete: () => {\n showToast(\n 'Customize the events and styles of a single preview image',\n );\n },\n },\n {\n url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg',\n imageFit: 'contain',\n },\n ]);\n\n return { fileList };\n },\n};\n<van-uploader v-model="fileList" reupload max-count="2" />\nimport { ref } from 'vue';\n\nexport default {\n setup() {\n const fileList = ref([\n { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' },\n ]);\n\n return { fileList };\n },\n};\n| Attribute | \nDescription | \nType | \nDefault | \n
|---|---|---|---|
| v-model | \nList of uploaded files | \nFileListItem[] | \n- | \n
| accept | \nAccepted file type | \nstring | \nimage/* | \n
| name | \nInput name, usually a unique string or number | \nnumber | string | \n- | \n
| preview-size | \nSize of preview image | \nnumber | string | Array | \n80px | \n
| preview-image | \nWhether to show image preview | \nboolean | \ntrue | \n
| preview-full-image | \nWhether to show full screen image preview when image is clicked | \nboolean | \ntrue | \n
| preview-options | \nOptions of full screen image preview, see ImagePreview | \nobject | \n- | \n
| multiple | \nWhether to enable multiple selection pictures | \nboolean | \nfalse | \n
| disabled | \nWhether to disabled the upload | \nboolean | \nfalse | \n
| readonly | \nWhether to make upload area readonly | \nboolean | \nfalse | \n
| deletable | \nWhether to show delete icon | \nboolean | \ntrue | \n
reupload v4.4.0 | \nWhether to enable reupload, if enabled, the image preview will be disabled | \nboolean | \nfalse | \n
| show-upload | \nWhether to show upload area | \nboolean | \ntrue | \n
| lazy-load | \nWhether to enable lazy load, should register Lazyload component | \nboolean | \nfalse | \n
| capture | \nCapture, can be set to camera | \nstring | \n- | \n
| after-read | \nHook after reading the file | \nFunction | \n- | \n
| before-read | \nHook before reading the file, return false to stop reading the file, can return Promise | \nFunction | \n- | \n
| before-delete | \nHook before delete the file, return false to stop reading the file, can return Promise | \nFunction | \n- | \n
| max-size | \nMax size of file | \nnumber | string | (file: File) => boolean | \nInfinity | \n
| max-count | \nMax count of image | \nnumber | string | \nInfinity | \n
| result-type | \nType of file read result, can be set to file text | \nstring | \ndataUrl | \n
| upload-text | \nUpload text | \nstring | \n- | \n
| image-fit | \nPreview image fit mode | \nstring | \ncover | \n
| upload-icon | \nUpload icon | \nstring | \nphotograph | \n
\n\nTips: accept, capture and multiple are the attributes of the native input tag, there may be some compatibility issues under different systems and WebView.
\n
| Event | \nDescription | \nArguments | \n
|---|---|---|
| oversize | \nEmitted when file size over limit | \nSame as after-read | \n
| click-upload | \nEmitted when click upload area | \nevent: MouseEvent | \n
| click-preview | \nEmitted when preview image is clicked | \nSame as after-read | \n
| click-reupload | \nEmitted when reupload image is clicked | \nSame as after-read | \n
| close-preview | \nEmitted when the full screen image preview is closed | \n- | \n
| delete | \nEmitted when preview file is deleted | \nSame as after-read | \n
| Name | \nDescription | \nSlotProps | \n
|---|---|---|
| default | \nCustom upload area | \n- | \n
| preview-delete | \nCustom delete icon | \n- | \n
| preview-cover | \nCustom content that covers the image preview | \nitem: FileListItem | \n
| Attribute | \nDescription | \nType | \n
|---|---|---|
| file | \nFile object | \nobject | \n
| detail | \nDetail info, contains name and index | \nobject | \n
| Value | \nDescription | \n
|---|---|
| file | \nResult contains File object | \n
| text | \nResult contains File object and text content | \n
| dataUrl | \nResult contains File object and base64 content | \n
Use ref to get Uploader instance and call instance methods.
\n| Name | \nDescription | \nAttribute | \nReturn value | \n
|---|---|---|---|
| closeImagePreview | \nClose full screen image preview | \n- | \n- | \n
| chooseFile | \nTrigger choosing files, works with the user action context only because of browser security | \n- | \n- | \n
The component exports the following type definitions:
\nimport type {\n UploaderProps,\n UploaderInstance,\n UploaderResultType,\n UploaderFileListItem,\n} from 'vant';\nUploaderInstance is the type of component instance:
import { ref } from 'vue';\nimport type { UploaderInstance } from 'vant';\n\nconst uploaderRef = ref<UploaderInstance>();\n\nuploaderRef.value?.chooseFile();\nThe component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.
\n| Name | \nDefault Value | \nDescription | \n
|---|---|---|
| --van-uploader-size | \n80px | \n- | \n
| --van-uploader-icon-size | \n24px | \n- | \n
| --van-uploader-icon-color | \nvar(--van-gray-4) | \n- | \n
| --van-uploader-text-color | \nvar(--van-text-color-2) | \n- | \n
| --van-uploader-text-font-size | \nvar(--van-font-size-sm) | \n- | \n
| --van-uploader-upload-background | \nvar(--van-gray-1) | \n- | \n
| --van-uploader-upload-active-color | \nvar(--van-active-color) | \n- | \n
| --van-uploader-delete-color | \nvar(--van-white) | \n- | \n
| --van-uploader-delete-icon-size | \n14px | \n- | \n
| --van-uploader-delete-background | \nrgba(0, 0, 0, 0.7) | \n- | \n
| --van-uploader-file-background | \nvar(--van-background) | \n- | \n
| --van-uploader-file-icon-size | \n20px | \n- | \n
| --van-uploader-file-icon-color | \nvar(--van-gray-7) | \n- | \n
| --van-uploader-file-name-padding | \n0 var(--van-padding-base) | \n- | \n
| --van-uploader-file-name-margin-top | \nvar(--van-padding-xs) | \n- | \n
| --van-uploader-file-name-font-size | \nvar(--van-font-size-sm) | \n- | \n
| --van-uploader-file-name-text-color | \nvar(--van-gray-7) | \n- | \n
| --van-uploader-mask-text-color | \nvar(--van-white) | \n- | \n
| --van-uploader-mask-background | \nfade(var(--van-gray-8), 88%) | \n- | \n
| --van-uploader-mask-icon-size | \n22px | \n- | \n
| --van-uploader-mask-message-font-size | \nvar(--van-font-size-sm) | \n- | \n
| --van-uploader-mask-message-line-height | \nvar(--van-line-height-xs) | \n- | \n
| --van-uploader-loading-icon-size | \n22px | \n- | \n
| --van-uploader-loading-icon-color | \nvar(--van-white) | \n- | \n
| --van-uploader-disabled-opacity | \nvar(--van-disabled-opacity) | \n- | \n
| --van-uploader-border-radius | \n0px | \n- | \n
When uploading an image, if the user has not granted camera permission to the current app, the Uploader component will not work.
\nYou 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:
\nnavigator.mediaDevices\n .getUserMedia({ video: true })\n .then((stream) => {\n console.log(stream);\n })\n .catch((err) => {\n console.log(err);\n });\n