• Uploader 文件上传
  • 介绍
  • 引入
• 代码演示
  • 基础用法
  • 文件预览
  • 上传状态
  • 限制上传数量
  • 限制上传大小
  • 自定义上传样式
  • 自定义预览样式
  • 自定义预览大小
  • 上传前置处理
  • 禁用文件上传
  • 自定义单个图片预览
• API
  • Props
  • Events
  • Slots
  • 回调参数
  • ResultType 可选值
  • 方法
  • 类型定义
• 主题定制
  • 样式变量
• 常见问题
  • Uploader 在部分安卓机型上无法上传图片？
  • 拍照上传的图片被旋转 90 度？
  • 示例
  • 上传图片时出现浏览器刷新或卡顿现象？
  • 上传 HEIC/HEIF 格式的图片后无法展示？

Uploader 文件上传

介绍

用于将本地的图片或文件上传至服务器，并在上传过程中展示预览图和上传进度。目前 Uploader 组件不包含将文件上传至服务器的接口逻辑，该步骤需要自行实现。

引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。
1. import { createApp } from 'vue';
2. import { Uploader } from 'vant';
3. 4. const app = createApp();
5. app.use(Uploader);

代码演示

基础用法

文件上传完毕后会触发 after-read 回调函数，获取到对应的 file 对象。
1.

  1. export default {
    2.   setup() {
    3.     const afterRead = (file) => {
    4.       // 此时可以自行将文件上传至服务器
    5.       console.log(file);
    6.     };
    7.   8.     return {
    9.       afterRead,
    10.     };
    11.   },
    12. };

文件预览

通过 v-model 可以绑定已经上传的文件列表，并展示文件列表的预览图。
1.

  1. import { ref } from 'vue';
    2.   3. export default {
    4.   setup() {
    5.     const fileList = ref([
    6.       { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' },
    7.       // Uploader 根据文件后缀来判断是否为图片文件
    8.       // 如果图片 URL 中不包含类型信息，可以添加 isImage 标记来声明
    9.       { url: 'https://cloud-image', isImage: true },
    10.     ]);
    11.   12.     return {
    13.       fileList,
    14.     };
    15.   },
    16. };

上传状态

通过 status 属性可以标识上传状态，uploading 表示上传中，failed 表示上传失败，done 表示上传完成。
1.

  1. import { ref } from 'vue';
    2.   3. export default {
    4.   setup() {
    5.     const fileList = ref([
    6.       {
    7.         url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg',
    8.         status: 'uploading',
    9.         message: '上传中...',
    10.       },
    11.       {
    12.         url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg',
    13.         status: 'failed',
    14.         message: '上传失败',
    15.       },
    16.     ]);
    17.   18.     const afterRead = (file) => {
    19.       file.status = 'uploading';
    20.       file.message = '上传中...';
    21.   22.       setTimeout(() => {
    23.         file.status = 'failed';
    24.         file.message = '上传失败';
    25.       }, 1000);
    26.     };
    27.   28.     return {
    29.       fileList,
    30.       afterRead,
    31.     };
    32.   },
    33. };

限制上传数量

通过 max-count 属性可以限制上传文件的数量，上传数量达到限制后，会自动隐藏上传区域。
1.

  1. import { ref } from 'vue';
    2.   3. export default {
    4.   setup() {
    5.     const fileList = ref([]);
    6.   7.     return {
    8.       fileList,
    9.     };
    10.   },
    11. };

限制上传大小

通过 max-size 属性可以限制上传文件的大小，超过大小的文件会被自动过滤，这些文件信息可以通过 oversize 事件获取。
1.

  1. import { showToast } from 'vant';
    2.   3. export default {
    4.   setup() {
    5.     const onOversize = (file) => {
    6.       console.log(file);
    7.       showToast('文件大小不能超过 500kb');
    8.     };
    9.   10.     return {
    11.       onOversize,
    12.     };
    13.   },
    14. };

如果需要针对不同类型的文件来作出不同的大小限制，可以在 max-size 属性中传入一个函数，在函数中通过 file.type 区分文件类型，返回 true 表示超出限制，false 表示未超出限制。
1.

  1. export default {
    2.   setup() {
    3.     const isOverSize = (file) => {
    4.       const maxSize = file.type === 'image/jpeg' ? 500 * 1024 : 1000 * 1024;
    5.       return file.size >= maxSize;
    6.     };
    7.     return {
    8.       isOverSize,
    9.     };
    10.   },
    11. };

自定义上传样式

通过默认插槽可以自定义上传区域的样式。
1.
2. 上传文件
3.

自定义预览样式

通过 preview-cover 插槽可以自定义覆盖在预览区域上方的内容。
1.
2.
5.
6. 7.

自定义预览大小

通过 preview-size 属性定义预览图和上传区域的大小。
1.
2.
3.
4.

将 preview-size 设置为数组格式，可以分别设置宽高。数组第一项对应宽度，数组第二项对应高度。
1.

上传前置处理

通过传入 beforeRead 函数可以在上传前进行校验和处理，返回 true 表示校验通过，返回 false 表示校验失败。支持返回 Promise 对 file 对象进行自定义处理，例如压缩图片。
1.

  1. import { showToast } from 'vant';
    2.   3. export default {
    4.   setup() {
    5.     // 返回布尔值
    6.     const beforeRead = (file) => {
    7.       if (file.type !== 'image/jpeg') {
    8.         showToast('请上传 jpg 格式图片');
    9.         return false;
    10.       }
    11.       return true;
    12.     };
    13.   14.     // 返回 Promise
    15.     const asyncBeforeRead = (file) =>
    16.       new Promise((resolve, reject) => {
    17.         if (file.type !== 'image/jpeg') {
    18.           showToast('请上传 jpg 格式图片');
    19.           reject();
    20.         } else {
    21.           const img = new File(['foo'], 'bar.jpg', {
    22.             type: 'image/jpeg',
    23.           });
    24.           resolve(img);
    25.         }
    26.       });
    27.   28.     return {
    29.       beforeRead,
    30.       asyncBeforeRead,
    31.     };
    32.   },
    33. };

禁用文件上传

通过 disabled 属性禁用文件上传。
1.

自定义单个图片预览

在 v-model 数组中设置单个预览图片属性，支持 imageFit deletable previewSize beforeDelete。
1.

  1. import { ref } from 'vue';
    2. import { showToast } from 'vant';
    3.   4. export default {
    5.   setup() {
    6.     const fileList = ref([
    7.       {
    8.         url: 'https://fastly.jsdelivr.net/npm/@vant/assets/sand.jpeg',
    9.         deletable: true,
    10.         beforeDelete: () => {
    11.           showToast('删除前置处理');
    12.         },
    13.       },
    14.       {
    15.         url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg',
    16.         imageFit: 'contain',
    17.       },
    18.     ]);
    19.   20.     return { fileList };
    21.   },
    22. };

API

Props

UploaderInstance 是组件实例的类型，用法如下：
1. import { ref } from 'vue';
2. import type { UploaderInstance } from 'vant';
3. 4. const uploaderRef = ref();
5. 6. uploaderRef.value?.chooseFile();

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
名称| 默认值| 描述
---|---|---
—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)| -

常见问题

Uploader 在部分安卓机型上无法上传图片？

Uploader 采用了 HTML 原生的 <input type="file /> 标签进行上传，能否上传取决于当前系统和浏览器的兼容性。当遇到无法上传的问题时，一般有以下几种情况：
1. 遇到了安卓 App WebView 的兼容性问题，需要在安卓原生代码中进行兼容，可以参考此文章。
2. 图片格式不正确，在当前系统/浏览器中无法识别，比如 webp 或 heic 格式。
3. 其他浏览器兼容性问题。

拍照上传的图片被旋转 90 度？

部分手机在拍照上传时会出现图片被旋转 90 度的问题，这个问题可以通过 compressorjs 或其他开源库进行处理。
compressorjs 是一个开源的图片处理库，提供了图片压缩、图片旋转等能力。

示例

使用 compressorjs 进行处理的示例代码如下:
1.

  1. import Compressor from 'compressorjs';
    2.   3. export default {
    4.   setup() {
    5.     const beforeRead = (file) =>
    6.       new Promise((resolve) => {
    7.         // compressorjs 默认开启 checkOrientation 选项
    8.         // 会将图片修正为正确方向
    9.         new Compressor(file, {
    10.           success: resolve,
    11.           error(err) {
    12.             console.log(err.message);
    13.           },
    14.         });
    15.       });
    16.   17.     return {
    18.       beforeRead,
    19.     };
    20.   },
    21. };

上传图片时出现浏览器刷新或卡顿现象？

这种现象一般是内存不足导致的，通常发生在旧机型上；上传一张较大的图片引起也引起此现象。
为了减少这种情况的出现，可以在上传图片前对图片进行压缩，压缩方法请参考上文中提到的 compressorjs 库。

上传 HEIC/HEIF 格式的图片后无法展示？

目前 Chrome、Safari 等浏览器不支持展示 HEIC/HEIF 格式的图片，因此上传后无法在 Uploader 组件中进行预览。
[HEIF] 格式的兼容性请参考 caniuse。