uni-file-picker文件上传实战：从单图到多图的灵活控制

1. 从零开始认识 uni-file-picker

如果你正在用 uni-app 开发小程序或者 H5 应用，需要让用户上传头像、发布带图的动态、提交证件照片，那你大概率绕不开文件上传这个功能。自己从头写一个文件选择器？光是处理不同平台的兼容性就够头疼的了。这时候，uni-app 官方扩展组件库里的 uni-file-picker 简直就是救星。

我刚开始用的时候，觉得它就是个简单的图片选择框，但用久了才发现，这家伙“内力深厚”，通过不同的参数配置，能玩出很多花样。简单来说，uni-file-picker 是一个集文件选择、预览、上传于一体的强大组件。你不需要关心用户是在微信小程序里从聊天记录选图，还是在 H5 里从电脑拖拽文件，它都帮你处理好了，给你一个统一、简单的接口。

它最核心的能力，也是我们今天要重点掰扯的，就是 “灵活控制”。比如，你的个人资料页只需要上传一张头像，那就要限制用户只能选一张图；而在发布商品时，可能需要上传多张细节图，那就得允许用户选最多九张甚至更多。有时候，你希望用户一点选图片就自动开始上传；有时候，你又需要等用户填写完所有表单信息后，再统一提交所有数据（包括图片）。这些看似不同的需求，其实都是通过给 uni-file-picker 传递几个简单的参数来实现的。

所以，这篇文章我就结合自己踩过的一些坑和实战经验，带你彻底搞懂这个组件。我们不谈空泛的理论，就从一个最简单的单图上传开始，一步步扩展到复杂的多图上传和手动控制上传，让你能真正在项目里用起来，而且用得顺手。

2. 单图上传：从头像设置开始

让我们从一个最常见的场景切入：用户头像上传。这个功能要求简单明确：只能选一张图，最好是正方形，选了之后最好能预览，点击上传。

2.1 基础配置与参数解析

先来看一个最精简的代码例子，这也是官方文档里常见的形式：

<template>
  <view>
    <uni-file-picker
      v-model="avatarValue"
      file-mediatype="image"
      mode="grid"
      :limit="1"
      @select="onFileSelect"
    ></uni-file-picker>
  </view>
</template>

<script>
export default {
  data() {
    return {
      avatarValue: [] // 用于绑定已选文件列表
    };
  },
  methods: {
    onFileSelect(e) {
      console.log('用户选择了文件：', e);
      // e.tempFiles 是临时文件数组
      // e.tempFilePaths 是临时文件路径数组
    }
  }
};
</script>

别看代码少，这里面的几个参数个个都是关键：

• v-model="avatarValue"： 这是 Vue 的双向绑定。组件会把用户选择的文件信息（一个对象数组）同步到这里。你既可以通过它获取已选的文件，也可以通过修改它来清空或设置已选文件（比如编辑资料时回显旧头像）。
• file-mediatype="image"： 这个参数是类型过滤器。设为 "image" 就只允许选择图片文件。它还能设为 "video"（视频）或 "all"（所有文件）。做头像上传，我们当然只关心图片。
• mode="grid"： 这是展示模式。grid 是九宫格模式，非常适合图片预览，选中的图片会以缩略图形式平铺展示。另一个常用值是 list，列表模式，更适合文件。
• :limit="1"： 这是数量限制的灵魂。这里设成 1，就意味着用户最多只能选择 1 个文件。当用户已经选了一张图，再点击选择时，组件会自动阻止，并可能提示“已达上限”。这是实现单图上传最核心的一步。
• @select="onFileSelect"： 这是选择事件。当用户从相册或文件管理器选中文件后，会触发这个事件。事件对象 e 里包含了所有选中文件的临时信息，这是我们后续进行上传操作的起点。

我刚开始用的时候，老是把 limit 和选择逻辑搞混，以为还要自己写代码判断数量。其实完全不用，limit 参数已经帮我们做了硬性限制，前端交互上用户就无法多选，省心又安全。

2.2 实战：实现头像上传并预览

光选择不行，我们得把图片传到自己的服务器。这里有个小细节：上面的例子并没有自动上传。我们需要在 select 事件里手动处理。下面是一个更贴近实战的例子，包含了上传和本地预览：

<template>
  <view class="avatar-upload">
    <text class="label">上传头像</text>
    <uni-file-picker
      v-model="formData.avatarList"
      file-mediatype="image"
      mode="grid"
      :limit="1"
      :image-styles="imageStyles"
      @select="handleAvatarSelect"
      @delete="handleAvatarDelete"
    ></uni-file-picker>
    <button @click="submitForm">提交资料</button>
  </view>
</template>

<script>
export default {
  data() {
    return {
      formData: {
        avatarList: [], // 组件绑定的文件列表
        avatarUrl: ''   // 最终上传到服务器的地址
      },
      // 可以自定义预览图的样式，比如固定为圆形
      imageStyles: {
        width: 120,
        height: 120,
        border: {
          radius: '50%' // 关键！让预览图显示为圆形，更符合头像样式
        }
      }
    };
  },
  methods: {
    async handleAvatarSelect(e) {
      // 用户选择