如何封装微信小程序中的图片上传功能

前言

在微信小程序开发中，图片上传功能是一个十分常见的需求，不管是社交分享、商城中的商品图片上传，还是在线报修、问诊等应用场景，上传图片都能够提升用户体验。而在实际项目中，我们常常需要对上传图片的逻辑进行封装，使得代码更加简洁、易于复用。本文将详细介绍如何封装微信小程序中的图片上传功能，帮助开发者构建一个易扩展、易维护的上传模块。

一、需求分析与设计思路

在开发一个图片上传功能时，我们需要关注以下几个方面：

•	多张图片上传：是否允许用户同时选择和上传多张图片？
•	文件校验：需要限制图片的格式和大小，避免用户上传不支持的格式或过大的图片文件。
•	错误处理：如何优雅地处理上传失败或文件选择失败的情况，提升用户体验。
•	模块化封装：为了提高代码的复用性，我们希望将上传逻辑封装成一个函数，能够灵活配置上传路径、表单数据等。

基于这些需求，我们决定对微信小程序的 wx.chooseMedia 和 wx.uploadFile API 进行封装，使得调用逻辑更加简洁，并且处理了常见的文件校验和错误处理。

二、上传图片功能封装

下面是我们对微信小程序图片上传功能的封装代码。它允许上传多张图片，包含文件格式和大小的校验，并处理了上传和文件选择过程中的错误。

import { BASE_URL, prefix } from "./config";

// 限制文件大小为 5MB
const MAX_FILE_SIZE = 5 * 1024 * 1024; 

/**
 * 校验图片格式
 * @param {string} filePath - 选择的文件路径
 * @returns {boolean} - 是否通过格式校验
 */
function validateImageType(filePath: string): boolean {
  const validFormats = ['jpg', 'jpeg', 'png'];
  const fileExtension = filePath.split('.').pop()?.toLowerCase();
  return validFormats.includes(fileExtension || '');
}

/**
 * 校验图片大小
 * @param {number} fileSize - 文件大小
 * @returns {boolean} - 是否通过大小校验
 */
function validateImageSize(fileSize: number): boolean {
  return fileSize <= MAX_FILE_SIZE;
}

/**
 * 上传图片到服务器
 * @param formData - 额外的表单数据，默认为空对象
 * @param count - 上传的图片数量，默认为 1
 * @returns 返回一个 Promise，resolve 成功结果，reject 错误信息
 */
export function uploadImages(formData: object = {}, count: number = 1): Promise<any> {
  return new Promise((resolve, reject) => {
    // 选择照片
    wx.chooseMedia({
      count: count, // 用户可选择多张图片
      mediaType: ["image"],
      sourceType: ["album", "camera"],
      success: (chooseMediaRes) => {
        const tempFiles = chooseMediaRes.tempFiles;

        // 校验文件格式和大小
        for (const file of tempFiles) {
          if (!validateImageType(file.tempFilePath)) {
            return reject(new Error("不支持的图片格式，仅支持 JPG, JPEG, PNG 格式"));
          }

          if (!validateImageSize(file.size)) {
            return reject(new Error(`图片大小不能超过 ${MAX_FILE_SIZE / 1024 / 1024}MB`));
          }
        }

        // 批量上传图片
        const uploadPromises = tempFiles.map((file) => {
          return new Promise((uploadResolve, uploadReject) => {
            wx.uploadFile({
              url: `${BASE_URL}${prefix}/upload`, // 上传接口地址
              filePath: file.tempFilePath,
              name: "file", // 文件对应的 key
              formData: formData, // 传递额外的表单数据
              success: (uploadRes) => {
                try {
                  const data = JSON.parse(uploadRes.data); // 解析服务器返回的 JSON 数据
                  uploadResolve(data); // 上传成功，返回解析的数据
                } catch (error) {
                  uploadReject(new Error("解析服务器返回的数据失败")); // 解析失败的错误处理
                }
              },
              fail: (err) => {
                uploadReject(new Error("上传照片失败")); // 上传失败的错误处理
              },
            });
          });
        });

        // 等待所有上传请求完成
        Promise.all(uploadPromises)
          .then(resolve)
          .catch(reject);
      },
      fail: (err) => {
        reject(new Error("选择照片失败"));
      },
    });
  });
}

功能解析

1.	文件格式校验：我们定义了一个 validateImageType 函数，用于确保用户上传的文件是 JPG、JPEG、PNG 格式。
2.	文件大小校验：通过 validateImageSize 函数，限制用户上传图片的大小不超过 5MB。
3.	多张图片上传：通过传递 count 参数，我们支持用户一次选择多张图片，并且批量上传到服务器。
4.	错误处理：我们捕获了图片选择、上传、以及服务器响应中的错误，并在失败时返回详细的错误信息。

三、页面调用示例

下面是如何在小程序的页面中调用这个封装好的图片上传功能：

import { uploadImages } from './upload';

Page({
  data: {},

  async onUpload() {
    try {
      const formData = { userId: '123456' }; // 附加的表单数据
      const response = await uploadImages(formData, 3); // 上传最多3张图片
      console.log('上传成功:', response);
    } catch (error) {
      console.error('上传失败:', error.message);
    }
  }
});

调用解析

•	uploadImages(formData, count)：我们通过调用 uploadImages 方法，传递表单数据（如用户 ID）以及允许用户选择上传最多3张图片。整个上传过程是异步的，调用者可以通过 try/catch 块捕获上传过程中可能发生的错误。

四、功能改进与扩展

虽然该功能已经可以满足基础的图片上传需求，但我们可以根据具体业务场景进行扩展与优化：

4.1 压缩图片

如果用户上传的图片尺寸较大，我们可以在上传之前调用微信小程序的 wx.compressImage 接口对图片进行压缩，以减少文件体积，提高上传速度。

wx.compressImage({
  src: file.tempFilePath, // 图片路径
  quality: 80, // 压缩质量，0 ~ 100
  success: (res) => {
    // 将压缩后的图片路径用于上传
  }
});

4.2 上传进度

通过 wx.uploadFile 提供的 onProgressUpdate 事件，我们可以实时获取文件上传的进度并展示给用户，提升用户体验。

wx.uploadFile({
  ...,
  onProgressUpdate: (progress) => {
    console.log('上传进度:', progress.progress);
  }
});

4.3 重试机制

如果图片上传失败，我们可以增加重试机制，例如在上传失败后自动重新上传图片，或者提示用户手动重新上传。

五、总结

通过封装微信小程序的图片上传功能，我们不仅简化了代码的编写，还增加了文件格式和大小校验、错误处理等功能，极大提升了代码的复用性与可维护性。这种封装方式适用于任何涉及图片上传的场景，方便在项目中随时调用，并且根据实际需求可以扩展到视频上传、音频上传等其他文件上传场景。