Vant

繁體中文

简体中文
English

繁體中文

简体中文
English

Appearance

Uploader 文件上传 - Vant 4

📤 Uploader 文件上传 ​

🎯 介绍 ​

Uploader 是一个功能强大的文件上传组件，专为移动端设计。它不仅支持图片和文件的本地选择与预览，还提供了丰富的上传状态展示、进度跟踪和自定义样式功能。无论是单文件上传还是批量上传，Uploader 都能为用户提供流畅的上传体验。

核心特性：

  • 📸 支持图片和文件上传，兼容多种格式
  • 🖼️ 实时预览功能，支持全屏图片浏览
  • 📊 上传状态管理（上传中、成功、失败）
  • 🎨 高度可定制的样式和布局
  • 🔒 完善的权限控制和文件校验
  • 📱 移动端优化，支持拍照和相册选择

注意： Uploader 组件专注于前端交互体验，不包含服务器上传接口逻辑，需要开发者自行实现后端上传功能。

📦 引入 ​

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

js
import { createApp } from 'vue';
import { Uploader } from 'vant';

const app = createApp();
app.use(Uploader);

🎨 代码演示 ​

📤 基础用法 ​

最简单的文件上传方式，用户选择文件后会触发 after-read 回调函数。在这个回调中，你可以获取到文件对象并进行后续处理，比如上传到服务器。

html
<van-uploader :after-read="afterRead" />
js
import { showToast } from 'vant';

export default {
  setup() {
    const afterRead = (file) => {
      // 此时可以自行将文件上传至服务器
      console.log('选择的文件:', file);
      showToast('文件选择成功');
      
      // 示例：模拟上传到服务器
      // uploadToServer(file);
    };

    return {
      afterRead,
    };
  },
};

🖼️ 文件预览 ​

通过 v-model 可以绑定已经上传的文件列表，组件会自动展示文件的预览图。支持图片预览和文件图标展示，让用户清楚地看到已上传的内容。

html
<van-uploader v-model="fileList" multiple />
js
import { ref } from 'vue';

export default {
  setup() {
    const fileList = ref([
      { 
        url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg',
        name: '美丽的叶子.jpg'
      },
      // Uploader 根据文件后缀来判断是否为图片文件
      // 如果图片 URL 中不包含类型信息，可以添加 isImage 标记来声明
      { 
        url: 'https://cloud-image', 
        isImage: true,
        name: '云端图片.png'
      },
    ]);

    return {
      fileList,
    };
  },
};

📊 上传状态 ​

通过 status 属性可以标识上传状态，让用户实时了解文件上传进度。支持 uploading（上传中）、failed（上传失败）、done（上传完成）三种状态。

html
<van-uploader v-model="fileList" :after-read="afterRead" />
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const fileList = ref([
      {
        url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg',
        status: 'uploading',
        message: '上传中...',
      },
      {
        url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg',
        status: 'failed',
        message: '上传失败',
      },
    ]);

    const afterRead = (file) => {
      file.status = 'uploading';
      file.message = '上传中...';
      
      // 模拟上传过程
      setTimeout(() => {
        if (Math.random() > 0.5) {
          file.status = 'done';
          file.message = '上传成功';
          showToast('上传成功');
        } else {
          file.status = 'failed';
          file.message = '上传失败';
          showToast('上传失败，请重试');
        }
      }, 2000);
    };

    return {
      fileList,
      afterRead,
    };
  },
};

🔢 限制上传数量 ​

通过 max-count 属性可以限制上传文件的数量，当达到限制后会自动隐藏上传区域，防止用户继续添加文件。这对于控制用户上传行为非常有用。

html
<van-uploader v-model="fileList" multiple :max-count="3" />
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const fileList = ref([]);

    const afterRead = (file) => {
      showToast(`已选择 ${fileList.value.length} 个文件`);
    };

    return {
      fileList,
      afterRead,
    };
  },
};

📏 限制上传大小 ​

通过 max-size 属性可以限制上传文件的大小，超过大小的文件会被自动过滤。当文件超出限制时，会触发 oversize 事件，你可以在此事件中给用户友好的提示。

html
<van-uploader 
  v-model="fileList" 
  multiple 
  :max-size="500 * 1024" 
  @oversize="onOversize" 
/>
js
import { showToast } from 'vant';

export default {
  setup() {
    const onOversize = (file) => {
      console.log('超大文件:', file);
      showToast('文件大小不能超过 500KB');
    };

    return {
      onOversize,
    };
  },
};

高级用法： 如果需要针对不同类型的文件设置不同的大小限制，可以在 max-size 属性中传入一个函数，通过 file.type 区分文件类型。

html
<van-uploader 
  v-model="fileList" 
  multiple 
  :max-size="isOverSize" 
  @oversize="onOversize" 
/>
js
import { showToast } from 'vant';

export default {
  setup() {
    const isOverSize = (file) => {
      // 图片文件限制 500KB，其他文件限制 1MB
      const maxSize = file.type.startsWith('image/') ? 500 * 1024 : 1000 * 1024;
      return file.size >= maxSize;
    };

    const onOversize = (file) => {
      const limit = file.type.startsWith('image/') ? '500KB' : '1MB';
      showToast(`${file.type.startsWith('image/') ? '图片' : '文件'}大小不能超过 ${limit}`);
    };

    return {
      isOverSize,
      onOversize,
    };
  },
};

🎨 自定义上传样式 ​

通过默认插槽可以完全自定义上传区域的样式，让上传界面更符合你的设计需求。

html
<van-uploader v-model="fileList">
  <van-button icon="plus" type="primary" plain>
    自定义上传样式
  </van-button>
</van-uploader>

🖼️ 自定义预览样式 ​

通过 preview-cover 插槽可以自定义覆盖在预览区域上方的内容，比如添加编辑按钮、删除确认等交互元素。

html
<van-uploader v-model="fileList">
  <template #preview-cover="{ file }">
    <div class="preview-cover van-ellipsis">
      {{ file.name }}
    </div>
  </template>
</van-uploader>

<style>
.preview-cover {
  position: absolute;
  bottom: 0;
  box-sizing: border-box;
  width: 100%;
  padding: 4px;
  color: #fff;
  font-size: 12px;
  text-align: center;
  background: rgba(0, 0, 0, 0.3);
}
</style>

📐 自定义预览大小 ​

通过 preview-size 属性可以灵活定义预览图和上传区域的大小，适应不同的界面布局需求。

html
<!-- 设置统一大小 -->
<van-uploader v-model="fileList" preview-size="60px" />

将 preview-size 设置为数组格式，可以分别设置宽高，实现矩形预览区域。

html
<!-- 设置不同的宽高 -->
<van-uploader v-model="fileList" :preview-size="[60, 40]" />

🔍 上传前置处理 ​

通过传入 beforeRead 函数可以在上传前进行校验和处理，支持文件格式验证、大小检查、图片压缩等操作。返回 true 表示校验通过，返回 false 表示校验失败。

html
<van-uploader 
  :before-read="beforeRead" 
  :after-read="afterRead"
/>

<!-- 异步处理示例 -->
<van-uploader 
  :before-read="asyncBeforeRead" 
  :after-read="afterRead"
/>
js
import { showToast } from 'vant';

export default {
  setup() {
    // 返回布尔值 - 同步校验
    const beforeRead = (file) => {
      if (file.type !== 'image/jpeg') {
        showToast('请上传 JPG 格式图片');
        return false;
      }
      if (file.size > 2 * 1024 * 1024) {
        showToast('图片大小不能超过 2MB');
        return false;
      }
      return true;
    };

    // 返回 Promise - 异步处理
    const asyncBeforeRead = (file) => 
      new Promise((resolve, reject) => {
        if (file.type !== 'image/jpeg') {
          showToast('请上传 JPG 格式图片');
          reject();
        } else {
          // 示例：创建处理后的文件对象
          const processedFile = new File(['processed'], 'processed.jpg', {
            type: 'image/jpeg',
          });
          resolve(processedFile);
        }
      });

    const afterRead = (file) => {
      console.log('文件处理完成:', file);
    };

    return {
      beforeRead,
      asyncBeforeRead,
      afterRead,
    };
  },
};

🚫 禁用文件上传 ​

通过 disabled 属性可以禁用文件上传功能，常用于表单提交中或权限控制场景。

html
<van-uploader v-model="fileList" disabled />

🎨 自定义单个图片预览 ​

在 v-model 数组中设置单个预览图片属性，支持 imageFit、deletable、previewSize、beforeDelete 等属性，实现更精细的控制。

html
<van-uploader v-model="fileList" />
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const fileList = ref([
      {
        url: 'https://fastly.jsdelivr.net/npm/@vant/assets/sand.jpeg',
        deletable: true,
        beforeDelete: () => {
          showToast('删除前置处理');
          return true;
        },
      },
      {
        url: 'https://fastly.jsdelivr.net/npm/@vant/assets/tree.jpeg',
        imageFit: 'contain',
      },
    ]);

    return {
      fileList,
    };
  },
};

🔄 开启覆盖上传 ​

设置 reupload 属性后，点击图片时会覆盖上传，而不是预览图片。这在需要替换已上传文件的场景中非常有用。

html
<van-uploader 
  v-model="fileList" 
  reupload 
  :after-read="afterRead"
/>
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const fileList = ref([
      { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' },
    ]);

    const afterRead = (file) => {
      showToast('文件已替换');
      console.log('新文件:', file);
    };

    return {
      fileList,
      afterRead,
    };
  },
};

📚 API ​

Props ​

参数说明类型默认值
v-model已上传的文件列表FileListItem[]-
accept允许上传的文件类型，详细说明stringimage/*

| name | 🏷️ 标识符，通常为一个唯一的字符串或数字，可以在回调函数的第二项参数中获取 | number | string | - | | preview-size | 📐 预览图和上传区域的尺寸，默认单位为 px | number | string | Array | 80px | | preview-image | 🖼️ 是否在上传完成后展示预览图 | boolean | true | | preview-full-image | 🔍 是否在点击预览图后展示全屏图片预览 | boolean | true | | preview-options | ⚙️ 全屏图片预览的配置项，可选值见 ImagePreview | object | - | | multiple | 📚 是否开启图片多选，部分安卓机型不支持 | boolean | false | | disabled | 🚫 是否禁用文件上传 | boolean | false | | readonly | 🔒 是否将上传区域设置为只读状态 | boolean | false | | deletable | 🗑️ 是否展示删除按钮 | boolean | true | | reupload v4.4.0 | 🔄 是否开启覆盖上传，开启后会关闭图片预览 | boolean | false | | show-upload | ➕ 是否展示上传区域 | boolean | true | | lazy-load | ⏳ 是否开启图片懒加载，须配合 Lazyload 组件使用 | boolean | false | | capture | 📷 图片选取模式，可选值为 camera (直接调起摄像头) | string | - | | after-read | ✅ 文件读取完成后的回调函数 | Function | - | | before-read | 🔍 文件读取前的回调函数，返回 false 可终止文件读取，支持返回 Promise | Function | - | | before-delete | ⚠️ 文件删除前的回调函数，返回 false 可终止文件删除，支持返回 Promise | Function | - | | max-size | 📏 文件大小限制，单位为 byte | number | string | (file: File) => boolean | Infinity | | max-count | 🔢 文件上传数量限制 | number | string | Infinity | | result-type | 📄 文件读取结果类型，可选值为 file、text、dataUrl | string | dataUrl | | upload-text | 💬 上传区域文字提示 | string | - | | image-fit | 🖼️ 预览图裁剪模式，可选值见 Image 组件 | string | cover | | upload-icon | 🎨 上传区域图标名称或图片链接，等同于 Icon 组件的 name 属性 | string | photograph |

注意：accept、capture 和 multiple 为浏览器 input 标签的原生属性，移动端各种机型对这些属性的支持程度有所差异，因此在不同机型和 WebView 下可能出现一些兼容性问题。

Events ​

事件名说明回调参数
oversize📏 文件大小超过限制时触发同 after-read
click-upload👆 点击上传区域时触发event: MouseEvent
click-preview🖼️ 点击预览图时触发同 after-read
click-reupload🔄 点击覆盖上传时触发同 after-read
close-preview❌ 关闭全屏图片预览时触发-
delete🗑️ 删除文件预览时触发同 after-read

Slots ​

名称说明参数
default🎨 自定义上传区域-
preview-delete🗑️ 自定义删除按钮-
preview-cover🖼️ 自定义覆盖在预览区域上方的内容item: FileListItem

📋 回调参数 ​

before-read、before-delete 执行时会传递以下回调参数：

参数名说明类型
file📁 file 对象object
detailℹ️ 额外信息，包含 name 和 index 字段object

✅ after-read 回调参数 ​

after-read 执行时会传递以下回调参数：

参数名说明类型
file📁 包含 file 对象UploaderFileListItem | UploaderFileListItem[]
detailℹ️ 额外信息，包含 name 和 index 字段object

📄 ResultType 可选值 ​

result-type 字段表示文件读取结果的类型，上传大文件时，建议使用 file 类型，避免卡顿。

值描述
file📁 结果仅包含 File 对象
text📝 结果包含 File 对象，以及文件的文本内容
dataUrl🖼️ 结果包含 File 对象，以及文件对应的 base64 编码

🔧 方法 ​

通过 ref 可以获取到 Uploader 实例并调用实例方法，详见组件实例方法。

方法名说明参数返回值
closeImagePreview❌ 关闭全屏的图片预览--
chooseFile📁 主动调起文件选择，由于浏览器安全限制，只有在用户触发操作的上下文中调用才有效--
reuploadFile 4.9.3🔄 主动调起文件选择，选择新文件后将覆盖原先上传的文件，由于浏览器安全限制，只有在用户触发操作的上下文中调用才有效index: number-

📝 类型定义 ​

组件导出以下类型定义：

ts
import type {
  UploaderProps,
  UploaderInstance,
  UploaderResultType,
  UploaderFileListItem,
  UploaderBeforeRead,
  UploaderAfterRead,
} from 'vant';

UploaderInstance 是组件实例的类型，用法如下：

ts
import { ref } from 'vue';
import type { UploaderInstance } from 'vant';

const uploaderRef = ref<UploaderInstance>();
uploaderRef.value?.chooseFile();

🎨 主题定制 ​

样式变量 ​

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称默认值描述
--van-uploader-size80px📐 上传区域大小
--van-uploader-icon-size24px🎨 上传图标大小
--van-uploader-icon-colorvar(--van-gray-4)🎨 上传图标颜色
--van-uploader-text-colorvar(--van-text-color-2)💬 上传文字颜色
--van-uploader-text-font-sizevar(--van-font-size-sm)📝 上传文字大小
--van-uploader-upload-backgroundvar(--van-gray-1)🎨 上传区域背景色
--van-uploader-upload-active-colorvar(--van-active-color)🎨 上传区域激活颜色
--van-uploader-delete-colorvar(--van-white)🗑️ 删除按钮颜色
--van-uploader-delete-icon-size14px🗑️ 删除图标大小
--van-uploader-delete-backgroundrgba(0, 0, 0, 0.7)🗑️ 删除按钮背景色
--van-uploader-file-backgroundvar(--van-background)📁 文件背景色
--van-uploader-file-icon-size20px📁 文件图标大小
--van-uploader-file-icon-colorvar(--van-gray-7)📁 文件图标颜色
--van-uploader-file-name-padding0 var(--van-padding-base)📝 文件名内边距
--van-uploader-file-name-margin-topvar(--van-padding-xs)📝 文件名上边距
--van-uploader-file-name-font-sizevar(--van-font-size-sm)📝 文件名字体大小
--van-uploader-file-name-text-colorvar(--van-gray-7)📝 文件名文字颜色
--van-uploader-mask-text-colorvar(--van-white)🎭 遮罩文字颜色
--van-uploader-mask-backgroundfade(var(--van-gray-8), 88%)🎭 遮罩背景色
--van-uploader-mask-icon-size22px🎭 遮罩图标大小
--van-uploader-mask-message-font-sizevar(--van-font-size-sm)🎭 遮罩消息字体大小
--van-uploader-mask-message-line-heightvar(--van-line-height-xs)🎭 遮罩消息行高
--van-uploader-loading-icon-size22px⏳ 加载图标大小
--van-uploader-loading-icon-colorvar(--van-white)⏳ 加载图标颜色
--van-uploader-disabled-opacityvar(--van-disabled-opacity)🚫 禁用状态透明度
--van-uploader-border-radius0px📐 边框圆角

❓ 常见问题 ​

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

Uploader 采用了 HTML 原生的 <input type="file" /> 标签进行上传，能否上传取决于当前系统和浏览器的兼容性。当遇到无法上传的问题时，一般有以下几种情况：

  1. 🔧 遇到了安卓 App WebView 的兼容性问题，需要在安卓原生代码中进行兼容，可以参考此文章。
  2. 🖼️ 图片格式不正确，在当前系统/浏览器中无法识别，比如 webp 或 heic 格式。
  3. 🌐 其他浏览器兼容性问题。

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

部分手机在拍照上传时会出现图片被旋转 90 度的问题，这个问题可以通过 compressorjs 或其他开源库进行处理。

compressorjs 是一个开源的图片处理库，提供了图片压缩、图片旋转等能力。

💡 示例 ​

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

html
<van-uploader :before-read="beforeRead" />
js
import Compressor from 'compressorjs';

export default {
  setup() {
    const beforeRead = (file) =>
      new Promise((resolve) => {
        // compressorjs 默认开启 checkOrientation 选项
        // 会将图片修正为正确方向
        new Compressor(file, {
          success: resolve,
          error(err) {
            console.log(err.message);
          },
        });
      });

    return {
      beforeRead,
    };
  },
};

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

这种现象一般是内存不足导致的，通常发生在旧机型上；上传一张较大的图片也会引起此现象。

为了减少这种情况的出现，可以在上传图片前对图片进行压缩，压缩方法请参考上文中提到的 compressorjs 库。

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

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

[HEIF] 格式的兼容性请参考 caniuse。

📷 如何判断用户授予了摄像头权限？ ​

在上传图片时，如果用户没有授予当前 App 摄像头权限，会导致 Uploader 组件无法使用。

你可以通过浏览器提供的 getUserMedia 方法来判断是否被授予了摄像头权限（请留意 getUserMedia 方法无法在 iOS 10 中使用）。

以下是一个简化的示例：

ts
navigator.mediaDevices
  .getUserMedia({ video: true })
  .then((stream) => {
    console.log('摄像头权限已授予:', stream);
  })
  .catch((err) => {
    console.log('摄像头权限被拒绝:', err);
  });

📖 相关文档 ​

📁 文件处理组件 ​

📝 表单组件 ​

💬 反馈组件 ​

🔧 工具组件 ​

基於Vant構建的企業級移動端解決方案

Copyright © 2025 siex.cn ｜ sitemap