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

---

前言

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

---

一、需求分析与设计思路

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

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

基于这些需求，我们决定对微信小程序的 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", // 文件对应的 keyformData: 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 ~ 100success: (res) => {// 将压缩后的图片路径用于上传}
});

4.2 上传进度

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

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

4.3 重试机制

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

五、总结

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