更新记录

0.0.1（2026-08-01）

支持下载

平台兼容性

uni-app(4.24)

uni-app x(4.13)

Zhangddq Upload 插件使用说明

插件 ID：zhangddq-upload 版本：0.0.1 平台：仅 iOS App（app-ios: y，app-android: n） 类型：UTS 插件（uni_modules），支持 Vue2 / Vue3

一、插件简介

zhangddq-upload 是一个仅适用于 iOS 的 UTS 插件，用于在 uni-app 中实现后台多部分（multipart/form-data）文件上传。

底层基于 iOS 原生的 URLSessionConfiguration.background，可在应用进入后台或被系统挂起时继续上传任务，适用于大文件、长时间上传场景。

当前能力范围

• 仅支持 iOS App。
• 仅支持单文件上传。
• 仅支持 multipart/form-data 形式上传。
• 使用 URLSessionConfiguration.background 后台会话配置。
• 将 multipart 请求体写入临时文件，使用 uploadTask(with:fromFile:) 上传。
• 大文件以分块流式写入请求体，避免整文件读入内存。
• 支持进度回调、成功/失败/取消回调，以及任务查询。

二、目录结构

uni_modules/zhangddq-upload
├── package.json                 # 插件配置与平台兼容性声明
├── readme.md
└── utssdk
    ├── interface.uts            # 对外类型定义（TypeScript 风格）
    └── app-ios
        ├── index.uts            # UTS 入口，JS 侧 API 实现
        ├── ZhangddqUploadNative.swift  # iOS 原生实现
        └── config.json

三、API

通过如下方式导入：

import {
  uploadFile,
  setUploadEventListener,
  getUploadTask,
  getUploadTasks,
  removeUploadTask
} from '@/uni_modules/zhangddq-upload'

1. uploadFile(options) — 上传文件

参数 UploadFileOptions

返回值：UploadTask

进度回调 UploadFileProgressUpdateCallbackResult

成功回调 UploadFileSuccessResult

失败回调 UploadFileFailResult

2. setUploadEventListener(listener) — 全局事件监听

注册一个全局上传事件监听器，所有任务的事件（进度 / 成功 / 失败）都会通过该监听器统一派发。

setUploadEventListener((event) => {
  // event.type: "progress" | "success" | "fail"
  console.log(event.type, event.taskId)
})

事件结构 UploadEvent：

3. 任务查询

• getUploadTask(taskId)：返回指定任务的当前状态（UTSJSONObject），不存在返回 null。
• getUploadTasks()：返回所有任务的列表（按创建时间倒序）。
• removeUploadTask(taskId)：从记录中移除指定任务并清理临时文件。

任务记录字段包括：taskId、url、filePath、status、progress、totalBytesSent、totalBytesExpectedToSend、data、statusCode、header、errCode、errMsg、createdAt、updatedAt。

status 取值：uploading / success / fail / aborted。

四、错误码说明

仅 HTTP 状态码在 200–299 之间时判定为成功，其他均通过 fail 回调返回。

五、使用示例

基本用法

const task = uploadFile({
  url: 'https://example.com/upload',
  filePath: 'file:///path/to/file.mp4',
  name: 'file',
  timeout: 1200000,
  header: {
    Authorization: 'Bearer xxx'
  },
  formData: {
    userId: '123'
  },
  success: (res) => {
    console.log('上传成功', res.statusCode, res.data)
  },
  fail: (err) => {
    console.log('上传失败', err.errCode, err.errMsg)
  },
  complete: () => {
    console.log('上传结束')
  }
})

task.onProgressUpdate((res) => {
  console.log(`进度 ${res.progress}% (${res.totalBytesSent}/${res.totalBytesExpectedToSend})`)
})

// 如需取消
// task.abort()

OSS 表单上传方式（推荐对接对象存储）

const uploadTask = uploadFile({
  url: oss.serverUrl,
  filePath: file,
  name: 'file',
  timeout: '1200000',
  formData: {
    key: oss.key,
    policy: oss.policy,
    OSSAccessKeyId: oss.OSSAccessKeyId,
    signature: oss.sign,
    success_action_status: '200'
  },
  success: (res) => {
    if (res.statusCode === 200) {
      console.log(res.data)
    }
  }
})

全局事件监听

setUploadEventListener((event) => {
  switch (event.type) {
    case 'progress':
      console.log(`[${event.taskId}] 进度 ${event.progress}%`)
      break
    case 'success':
      console.log(`[${event.taskId}] 成功 statusCode=${event.statusCode}`)
      break
    case 'fail':
      console.log(`[${event.taskId}] 失败 errCode=${event.errCode} errMsg=${event.errMsg}`)
      break
  }
})

六、filePath 注意事项

iOS 上 filePath 推荐使用原生 file:// URL：

• 以 file:// 开头 → 按原生 URL 解析
• 以 / 开头 → 按绝对路径解析
• 其他情况会被视为无效，回调 fail（errCode: 10002）

上传成功或失败后，插件会自动清理生成的 multipart 临时请求体文件；调用 removeUploadTask(taskId) 也会清理对应临时文件。

七、平台与配置说明

• 插件已在 package.json 中声明：app-ios: y、app-android: n，H5/小程序均不支持。
• 后台会话标识（identifier）：cn.cnqxmi.zhangddq-upload.session，使用 URLSessionConfiguration.background。
• 启用了 sessionSendsLaunchEvents = true，便于系统在后台上传完成后唤醒应用处理事件。
• isDiscretionary = false，避免系统将上传推迟到更合适时机。
• 进度轮询间隔为 300ms（由 UTS 侧的 setInterval 实现），用于将原生侧的状态变化反馈给 JS 侧回调与事件监听器。

iOS 工程侧建议

由于使用后台 URLSession，请在 iOS 工程中确认：

1. 已开启 Background Modes（后台模式），勾选后台 fetch 或后台处理相关能力（视上传策略而定）。
2. 在 Info.plist 中配置相应权限声明（如访问相册/文件时的 NSPhotoLibraryUsageDescription 等），具体视业务场景而定。
3. 上传大文件时务必对 filePath 进行有效性校验，避免无效路径触发 10002/10003 错误。

八、注意事项

1. 仅 iOS 可用：Android / H5 / 小程序端调用无效，请在调用前判断平台或仅在该插件支持的平台上使用。
2. 单文件、multipart 上传：不支持多文件或非 multipart 形式上传。
3. Content-Type：插件会自动生成 multipart/form-data; boundary=...，传入的 content-type 会被忽略。
4. MIME 推断：插件根据文件后缀推断 MIME（jpg/jpeg、png、wav、mp3、mp4 等），其他默认 application/octet-stream。
5. 超时时间：timeout 接受数字或字符串，单位毫秒，默认 20 分钟（1200000）。
6. 后台行为：iOS 后台 URLSession 由系统调度，存在被系统挂起或延迟的可能；上传结果请以 success/fail/全局事件为准，并通过 getUploadTask 查询实际状态。
7. 临时文件：插件会在 NSTemporaryDirectory 下生成 multipart 请求体临时文件，上传结束或主动移除任务时会清理。

九、快速集成步骤

1. 将 zhangddq-upload 放入项目的 uni_modules 目录（已有）。
2. 在需要使用的页面或组件中按“三、API”的方式 import。
3. 构造 filePath（建议 file:// URL）、url 以及 formData。
4. 调用 uploadFile(options)，使用 onProgressUpdate 监听进度，使用 success/fail/complete 处理结果。
5. 如需统一管理多任务事件，使用 setUploadEventListener。
6. 需要查询或清理任务时，使用 getUploadTask / getUploadTasks / removeUploadTask。
7. 打包自定义基座或提交云端打包时，确认 iOS 平台选中此插件。