uni-file-picker文件上传实战指南：从基础到高级应用

1. 认识 uni-file-picker：你的移动端文件上传“瑞士军刀”

如果你正在用 uni-app 开发小程序或者 App，需要让用户上传头像、提交作业图片、或者发送一个 PDF 文件，那你大概率绕不开文件上传这个功能。自己从头写一个？那得处理不同平台的 API 差异、文件选择、预览、删除、上传进度……想想就头大。这时候，uni-file-picker 就像一位贴心的助手，把这些繁琐的活儿都打包好了，你只需要简单配置，就能获得一个功能完善的文件上传组件。

我刚开始接触 uni-app 那会儿，为了一个图片上传，在微信小程序和 App 端写了不同的代码，调试得焦头烂额。后来发现了 uni-file-picker，真的有种“相见恨晚”的感觉。它本质上是一个集成了文件选择和上传管理的复合组件。你可以把它理解成一个“文件选择器 + 上传队列 + 预览图库”的小套装。无论是从相册选图、拍照，还是选择手机里的文档，它都能搞定，并且在界面上以列表或九宫格的形式优雅地展示出来。

它的核心价值在于跨平台一致性。uni-app 本身就是为了“一套代码，多端运行”而生的，uni-file-picker 完美继承了这一理念。你在 H5、微信小程序、支付宝小程序、App 等平台使用它，其调用方式、事件反馈基本是一致的，这极大地降低了开发和维护成本。你不用再担心在微信里用 wx.chooseImage，在 App 里用 plus.io，uni-file-picker 在底层帮你抹平了这些差异。

那么，它最适合谁用呢？我认为三类开发者会特别喜欢它：一是追求开发效率的实战派，希望快速实现功能，不想在基础组件上耗费太多时间；二是维护多端项目的团队，需要确保各平台上传体验一致；三是刚入门 uni-app 的新手，面对复杂的原生 API 有点发怵，需要一个开箱即用、文档清晰的组件来上手。接下来，我们就从最基础的安装配置开始，一步步把它用起来。

2. 从零开始：基础配置与第一个上传功能

万事开头难，但用 uni-file-picker 开头真的不难。首先，你需要确保你的项目是基于 Vue 3 的（如果是 Vue 2，用法类似但略有不同）。这个组件不是内置的，所以我们需要先把它请到项目里来。

2.1 安装与引入

打开你的项目，在终端里运行一条简单的命令就能完成安装：

npm install @dcloudio/uni-ui

或者，如果你习惯用 HBuilderX 开发，可以直接在项目根目录的 pages.json 里配置 easycom 规则，这样就能在模板里直接使用，连引入都省了。我个人更推荐 easycom 方式，非常省心。在 pages.json 中加入：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^uni-(.*)": "@dcloudio/uni-ui/lib/uni-$1/uni-$1.vue"
    }
  }
}

配置好后，你就可以在任意页面的 <template> 里直接写 <uni-file-picker> 了，就像使用一个内置标签一样方便。

2.2 实现单图片上传（头像场景）

让我们从一个最常见的场景开始：上传用户头像。这个场景要求只能传一张图，并且最好能圆形裁剪显示。用 uni-file-picker 实现起来非常优雅。

首先，我们在模板里放置组件：

<template>
  <view class="page">
    <text class="title">请设置您的头像</text>
    <view class="avatar-container">
      <uni-file-picker
        v-model="avatarList"
        file-mediatype="image"
        :limit="1"
        mode="grid"
        :auto-upload="false"
        :image-styles="imageStyles"
        @select="onAvatarSelected"
      ></uni-file-picker>
    </view>
  </view>
</template>

我来解释一下这几个关键属性：

• v-model="avatarList"：这是核心，用于双向绑定已选择的文件列表。即使只传一张图，它也必须是一个数组，这点很重要，后面会细说。
• file-mediatype="image"：指定只能选择图片类型。
• :limit="1"：限制最多只能选择1个文件，完美符合“单头像”需求。
• mode="grid"：以网格（单图）模式显示，而不是文件列表。
• :auto-upload="false"：我强烈建议关闭自动上传。这样我们可以先拿到文件，进行一些前置处理（比如压缩、校验），再手动控制上传时机，灵活性高得多。
• :image-styles="imageStyles"：用来控制预览图片的样式，这里是我们实现圆形头像的关键。

接着，在 <script setup> 中定义数据和事件：

<script setup>
import { ref } from 'vue'

// 绑定的文件列表，初始为空数组
const avatarList = ref([])

// 定义图片样式，使其显示为圆形
const imageStyles = {
  width: '200rpx',
  height: '200rpx',
  border: 'none'
}

// 文件选择事件
function onAvatarSelected(e) {
  // e.tempFiles 是一个数组，包含了用户刚选中的文件临时信息
  const te