更新记录

1.3.1（2026-09-06）

• 修复 uni-app x Android 示例的选择文件回调与可空参数类型导致的 UTS 编译错误。

1.3.0（2026-08-24）

• 修复 HarmonyOS 队列鉴权状态码转换、嵌套响应读取和网络状态监听器的 ArkTS 严格类型编译错误。
• 新增无需改造普通 multipart/form-data 服务端的可靠上传队列：文件入队、任务持久化、暂停、继续、取消、失败项重试、完成任务清理和队列快照监听。
• 新增断网等待与当前会话联网恢复、wifiOnly、全局并发、任务有效期、完成任务保留期和持久化容量上限策略。
• Android、iOS、Harmony 会先把待上传文件复制到插件专属持久目录；重启恢复后跳过已成功文件，未完成的当前文件从头重传。
• Web 恢复任务元数据但普通文件引用在页面重载后会明确标记 file-missing；微信、支付宝小程序按平台持久文件配额尽力恢复，不伪造成功。
• 上传地址、请求头和表单参数改由 resolveRequest 在每次真正上传前动态提供；队列元数据与公开快照不保存凭据、签名 URL、响应头或插件私有绝对路径。
• <lizhao-choose-file /> 新增显式 mode="queue"，uni-app 与 uni-app x 示例补齐入队、恢复、暂停、继续和失败重试入口；既有 1.2.x 选择与普通上传 API 保持原行为。

1.2.12（2026-06-24）

• 对齐 uni-app x 示例页与 uni-app 示例页的 lizhao-choose-file 业务封装测试界面，补齐上传配置、业务 API、组件式业务卡片、图片选择入口、文件选择结果和测试日志等演示能力。
• 修复 uni-app x 示例页“业务资料上传”区域只显示说明占位、业务卡片未展示的问题，补齐“组件：选择文档并上传”、文件数量、状态、进度、空态、文件列表和删除入口。
• 对齐内置业务组件的状态显示规则：未选择文件时仅展示空态提示，不提前显示上传进度和文件列表图标；选择文件并进入上传/完成状态后再展示整体进度、百分比、文件图标和文件信息。
• 本版本只调整示例页 UI、状态联动和发布日志，不修改插件公共 API、UTS 原生实现或 uni-app 已验证示例。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-choose-file

lizhao-choose-file 是面向 uni-app / uni-app x 的文件选择与上传插件，适合在表单附件、头像上传、资料提交、合同上传、批量导入等场景中快速接入“选择文件 + 上传 + 进度展示”的完整流程。

它还提供无需改造现有上传服务端的跨端可靠上传队列：断网时等待、联网后按策略恢复，应用重启后可找回任务，并跳过已经成功的文件。中断中的单个文件会从头重传，因此这里的“续传”是批次级任务恢复，不是依赖服务端分片协议的字节级断点续传。

你可以只调用 API 获取文件，也可以使用内置 <lizhao-choose-file /> 业务组件，直接获得上传按钮、文件列表、文件数量、进度条、图片缩略图、删除文件、取消上传和状态回调能力。

联系方式：信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

功能特色

适合哪些场景

• 表单附件、合同、发票、资质材料、作业文档等单文件或多文件提交。
• 头像、图片、媒体、Office、压缩包等需要按文件类型限制选择范围的业务。
• 页面已有自定义 UI，但希望复用跨端文件选择、上传、进度聚合和取消能力。
• 希望快速落地完整上传区域，减少文件列表、状态展示和删除交互开发成本。
• 需要对接业务上传接口，并读取服务端 JSON、HTTP 状态码或部分失败明细的场景。

接入方式怎么选

从简单到复杂接入

1. 引入插件

API 调用统一从插件根目录引入：

import * as LizhaoChooseFile from '@/uni_modules/lizhao-choose-file'

组件通过 easycom 使用：

<template>
  <lizhao-choose-file />
</template>

2. 选择单个文件

import * as LizhaoChooseFile from '@/uni_modules/lizhao-choose-file'

// 最小接入：只选择一个文件，不上传。
LizhaoChooseFile.pickFile({
  accept: '*/*',
  success(file) {
    console.log('选择成功', file)
  },
  fail(err) {
    console.log('选择失败', err)
  }
})

3. 选择多个文件

import * as LizhaoChooseFile from '@/uni_modules/lizhao-choose-file'

// 多选适合附件、资料包等场景；maxCount 控制最多选择数量。
LizhaoChooseFile.pickFiles({
  accept: '.pdf,.doc,.docx,.xls,.xlsx,image/*',
  multiple: true,
  maxCount: 5,
  success(files) {
    console.log('已选择文件', files)
  }
})

4. 选择后自动上传

import * as LizhaoChooseFile from '@/uni_modules/lizhao-choose-file'

// 公开测试接口只适合联调，正式业务请替换为自己的上传地址。
const task = LizhaoChooseFile.pickAndUploadFiles({
  accept: '.pdf,.doc,.docx,image/*',
  multiple: true,
  maxCount: 3,
  upload: {
    url: 'https://unidemo.dcloud.net.cn/upload',
    name: 'file',
    formData: {
      scene: 'demo'
    },
    progress(progress) {
      console.log('上传进度', progress.index + 1, progress.total, progress.progress)
    },
    success(res) {
      console.log('上传成功', res)
    },
    fail(err) {
      console.log('上传失败', err)
    }
  }
})

// 如需取消上传，保存 task 后调用 abort。
// task?.abort()

5. 使用业务场景预设

import * as LizhaoChooseFile from '@/uni_modules/lizhao-choose-file'

// document 场景会自动带上文档类 accept、默认多选和流程状态聚合。
LizhaoChooseFile.pickAndUploadBusinessFiles({
  scene: 'document',
  maxCount: 3,
  upload: {
    url: 'https://unidemo.dcloud.net.cn/upload',
    name: 'file',
    progress(progress) {
      console.log('业务上传进度', progress.overallProgress)
    }
  },
  stateChange(state) {
    console.log('业务流程状态', state.status, state.selectedCount, state.uploadTotal)
  }
})

6. 使用可靠上传队列

队列必须先配置运行期请求解析器，再恢复旧任务或加入新文件。上传地址、请求头和签名不会持久化；建议在 resolveRequest 中读取当前登录态并生成本次请求。

import {
  configureUploadQueue,
  enqueueUploadFiles,
  restoreUploadQueue,
  onUploadQueueChange
} from '@/uni_modules/lizhao-choose-file'

configureUploadQueue({
  concurrency: 2,
  retryCount: 2,
  retryDelay: 1500,
  resumeOnNetworkRestored: true,
  autoResumeOnLaunch: false,
  wifiOnly: false,
  resolveRequest(task, success, fail) {
    const url = getCurrentUploadUrl()
    if (!url) {
      fail({ errSubject: 'lizhao-choose-file', errCode: 9011017, errMsg: 'queue request unavailable' })
      return
    }
    // 每次实际上传前动态读取最新登录态，不把鉴权信息写入队列文件。
    success({ url, name: 'file', header: getCurrentUploadHeader() })
  }
})

onUploadQueueChange((snapshot) => {
  console.log('队列状态', snapshot)
})

// 应用启动时默认只恢复任务，避免未取得新凭据前自动上传。
restoreUploadQueue({ autoResume: false })

// files 来自 pickFile / pickFiles 成功回调。
enqueueUploadFiles({
  files,
  businessKey: 'order-10001',
  autoStart: true
})

已有任务可用 pauseUploadQueueTask(taskId)、resumeUploadQueueTask(taskId)、retryUploadQueueTask(taskId) 和 cancelUploadQueueTask(taskId) 控制。retryUploadQueueTask 会跳过成功文件；源文件副本丢失时状态为 file-missing，需要重新选择文件。

7. 使用内置业务 UI

<template>
  <lizhao-choose-file
    scene="document"
    mode="upload"
    ui-mode="business"
    :upload-url="uploadUrl"
    upload-name="file"
    title="业务资料上传"
    description="支持 PDF、Word、Excel、图片和压缩包"
    :show-progress="true"
    :show-file-count="true"
    :show-remove="true"
    @success="onUploadSuccess"
    @fail="onUploadFail"
    @state-change="onUploadState"
  />
</template>

<script>
export default {
  data() {
    return {
      // Web / H5 调试公开上传接口时，默认不要传自定义 header，避免 CORS 预检失败。
      uploadUrl: 'https://unidemo.dcloud.net.cn/upload'
    }
  },
  methods: {
    onUploadSuccess(res) {
      console.log('上传成功', res)
    },
    onUploadFail(err) {
      console.log('上传失败', err)
    },
    onUploadState(state) {
      console.log('上传状态', state)
    }
  }
}
</script>

7. 完全自定义 UI

<template>
  <view>
    <button @click="chooseContract">选择合同并上传</button>
    <lizhao-choose-file
      ref="contractUploader"
      scene="document"
      mode="upload"
      ui-mode="headless"
      :upload-url="uploadUrl"
      upload-name="file"
      @state-change="onUploadState"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      uploadUrl: 'https://unidemo.dcloud.net.cn/upload'
    }
  },
  methods: {
    chooseContract() {
      // headless 模式不渲染内置 UI，业务按钮通过组件方法触发流程。
      this.$refs.contractUploader.choose()
    },
    onUploadState(state) {
      console.log('自定义 UI 状态', state)
    }
  }
}
</script>

完整示例源码

完整页面源码已放在插件目录中，建议直接查看或复制：

E:\test\lizhao-plugin\uni_modules\lizhao-choose-file\example\uniapp\chooseFile.vue

该示例页覆盖 DCloud / httpbin 测试接口切换、基础 API、业务封装 API、business / simple / headless 三种组件模式、上传进度、文件数量、删除文件、图片缩略图、点击预览和取消上传。图片文件会显示缩略图，点击后通过 uni.previewImage 浏览同批图片。

支持平台

说明：所有 API 平台范围为 Android / iOS / Harmony / Web / 微信小程序 / 支付宝小程序。Harmony 端通过系统文件选择器返回 URI。file://media/Photo/...、file://docs... 等系统选择器 URI 会先通过 fs.openSync 打开授权文件，再复制到应用临时目录后上传；若 Harmony picker URI 无法复制到缓存/临时目录，会返回 9011011 明确错误，不会伪造成功。

API 总览

可靠上传队列 API

configureUploadQueue(options)

配置全局并发、重试、联网恢复和运行期请求解析器。应在恢复或入队前调用，resolveRequest 每次真正上传一个文件前触发。

enqueueUploadFiles(options) / restoreUploadQueue(options)

enqueueUploadFiles 会先保存源文件，再确认任务入队；restoreUploadQueue 会恢复元数据并检查文件副本。应用启动建议先配置队列，再以 autoResume: false 恢复，由用户确认后继续。

其他控制 API：getUploadQueueSnapshot()、pauseUploadQueueTask(taskId)、resumeUploadQueueTask(taskId)、retryUploadQueueTask(taskId)、cancelUploadQueueTask(taskId)、removeUploadQueueTask(taskId)、pauseAllUploadQueueTasks()、resumeAllUploadQueueTasks()、clearCompletedUploadQueueTasks()、onUploadQueueChange(callback)、offUploadQueueChange(callback)。

安全说明：队列只持久化任务状态、非敏感业务字段、文件显示信息和插件内部文件键；不持久化上传 URL、Authorization、Cookie、Token、签名、完整请求头、响应正文、响应头或 App 私有绝对路径。业务侧也不要把账号、密钥或生产配置放进 businessData。

业务场景预设

业务封装 API 用于减少常见页面重复写 accept / maxCount / progress / count 状态管理。底层仍复用标准选择与上传 API，不改变平台实现。

pickBusinessFiles(options)

说明 按业务场景选择文件，并通过 stateChange 返回统一流程状态。

支持平台 Android / iOS / Harmony / Web / 微信小程序 / 支付宝小程序

参数

pickAndUploadBusinessFiles(options)

说明 按业务场景选择文件并自动上传，stateChange 会聚合已选数量、当前上传序号、单文件进度、整体进度、成功数量和失败数量。

支持平台 Android / iOS / Harmony / Web / 微信小程序 / 支付宝小程序

参数

状态字段

<lizhao-choose-file />

说明 可选业务组件，适合快速放到页面中触发选择或选择并上传。核心文件能力仍由 UTS API 提供，组件按 ui-mode 提供三种接入方式：business 使用内置业务上传 UI，simple 使用轻量按钮列表 UI，headless 不渲染内置 UI，仅通过组件方法和事件交给业务页面自定义。

属性

文件类型优先级：accept 明确传入时直接使用；否则组件会把 extensions 与 mime-types 合并为过滤条件；仍未配置时再使用 file-type 或 scene 对应的业务预设。

UI 模式

事件

方法

pickFiles(options)

说明 选择多个文件。未配置 upload 时只返回文件选择结果；配置 upload 时选择成功后自动逐个上传。

支持平台 Android / iOS / Harmony / Web / 微信小程序 / 支付宝小程序

参数

pickFile(options)

说明 选择单个文件。未配置 upload 时只返回文件选择结果；配置 upload 时选择成功后自动上传。

支持平台 Android / iOS / Harmony / Web / 微信小程序 / 支付宝小程序

参数

uploadFile(options)

说明 手动上传单个已选择文件。上传方式为通用 HTTP multipart/form-data，服务器响应默认原样放入 data 字段；传 parseJson: true 时会额外尝试写入 parsedData。

支持平台 Android / iOS / Harmony / Web / 微信小程序 / 支付宝小程序

参数

uploadFiles(options)

说明 手动上传多个已选择文件。默认按顺序上传，失败后停止；传 sequential: false 时会并发上传，传 concurrency 可限制最大并发数量；传 stopOnFail: false 时会在成功结果中额外返回 failResults 便于定位部分失败文件。

支持平台 Android / iOS / Harmony / Web / 微信小程序 / 支付宝小程序

参数

pickAndUploadFile(options) / pickAndUploadFiles(options)

说明 先选择文件，再根据 options.upload 自动上传。选择成功回调仍返回原始文件对象或文件数组，上传成功回调通过 upload.success 返回。

参数

返回值说明

PickedFile

UploadSuccessItem

UploadFilesResult

错误码

示例

前面已经给出从简单到复杂的接入路径。这里保留常用扩展片段，完整页面结构、样式、错误提示、接口切换、取消上传和回调日志请看插件目录中的完整示例。

uni-app 调用示例

import * as LizhaoChooseFile from '@/uni_modules/lizhao-choose-file'

// uni-app 页面中可以直接在 methods 或组合式函数里调用。
LizhaoChooseFile.pickFile({
  accept: '*/*',
  success(file) {
    console.log('uni-app 选择成功', file)
  }
})

uni-app x 调用示例

import * as LizhaoChooseFile from '@/uni_modules/lizhao-choose-file'

// uni-app x 调用路径一致；App 端如新增业务 API 后旧基座未联编，请参考“自定义基座说明”。
LizhaoChooseFile.pickFiles({
  accept: 'image/*',
  multiple: true,
  maxCount: 3,
  success(files) {
    console.log('uni-app x 选择成功', files)
  }
})

手动上传示例

import * as LizhaoChooseFile from '@/uni_modules/lizhao-choose-file'

// 手动上传适合“先选文件、表单确认后再上传”的业务流程。
LizhaoChooseFile.pickFiles({
  accept: '.pdf,.doc,.docx,image/*',
  multiple: true,
  maxCount: 3,
  success(files) {
    const task = LizhaoChooseFile.uploadFiles({
      files,
      url: 'https://unidemo.dcloud.net.cn/upload',
      name: 'file',
      // 开启并发上传；如需严格按顺序上传，可改回 sequential: true。
      sequential: false,
      // 允许部分文件失败后继续上传，最终通过 failResults 定位失败文件。
      stopOnFail: false,
      // 测试接口返回 JSON 字符串时，插件会额外写入 parsedData，data 仍保留原文。
      parseJson: true,
      successStatusCodes: [200, 201, 204],
      progress(progress) {
        console.log('上传进度', progress.index + 1, progress.total, progress.progress)
      },
      success(res) {
        console.log('手动上传成功', res)
        console.log('失败明细', res.failResults)
      },
      fail(err) {
        console.log('手动上传失败', err)
      }
    })

    // 如需取消上传，保存 task 后调用 abort。
    // task?.abort()
  }
})

完整上传测试页面示例

完整页面源码已放在插件目录中，建议直接查看或复制：

E:\test\lizhao-plugin\uni_modules\lizhao-choose-file\example\uniapp\chooseFile.vue

该示例页覆盖以下链路：

• 上传接口切换：DCloud 测试接口、httpbin 回显接口、空 URL 错误测试。
• 基础 API：pickFile / pickFiles / uploadFiles / pickAndUploadFiles。
• 业务封装 API：pickAndUploadBusinessFiles。
• 可选业务组件：，包含 business / simple / headless 三种 UI 模式、上传进度、文件数量、删除文件、图片缩略图、点击预览、取消上传等能力。

业务场景封装 API 示例

import * as LizhaoChooseFile from '@/uni_modules/lizhao-choose-file'

// 业务附件上传：插件会按 attachment 场景生成默认 accept、数量和文件名模板。
const task = LizhaoChooseFile.pickAndUploadBusinessFiles({
  scene: 'attachment',
  maxCount: 3,
  upload: {
    url: 'https://unidemo.dcloud.net.cn/upload',
    name: 'file',
    parseJson: true,
    successStatusCodes: [200, 201, 204],
    progress(progress) {
      console.log('业务上传进度', progress.index + 1, progress.total, progress.progress)
    }
  },
  stateChange(state) {
    console.log('业务流程状态', state.status, state.selectedCount, state.uploadTotal, state.overallProgress)
  }
})

// task?.abort()

业务组件示例：business 内置业务 UI

<template>
  <lizhao-choose-file
    scene="document"
    file-type="document"
    mode="upload"
    ui-mode="business"
    :extensions="['.pdf', '.doc', '.docx', '.xls', '.xlsx', '.txt', '.ofd']"
    :upload-url="uploadUrl"
    upload-name="file"
    :parse-json="true"
    :success-status-codes="[200, 201, 204]"
    :show-progress="true"
    :show-file-count="true"
    :show-selected-list="true"
    :show-remove="true"
    :confirm-remove="true"
    title="业务资料上传"
    description="支持合同、表格、PDF 与 OFD，可删除后重新选择"
    empty-text="还没有业务资料"
    remove-text="删除"
    @state-change="onChooseFileState"
    @success="onChooseFileSuccess"
    @fail="onChooseFileFail"
    @remove="onChooseFileRemove"
  />
</template>

业务组件示例：simple 轻量 UI

<template>
  <lizhao-choose-file
    scene="image"
    mode="pick"
    ui-mode="simple"
    :max-count="6"
    button-text="选择图片"
    :show-progress="false"
    :show-file-count="true"
    :show-selected-list="true"
    :show-image-preview="true"
    :preview-on-click="true"
    @select="onImageSelect"
    @preview="onImagePreview"
  />
</template>

图片场景默认开启缩略图展示。若传入 preview-on-click="true"，点击缩略图会调用 uni.previewImage，组件也会触发 preview 事件，便于业务记录日志或埋点。

业务组件示例：headless 自定义 UI

<template>
  <view class="custom-upload">
    <button @click="chooseContract">选择合同并上传</button>
    <lizhao-choose-file
      ref="contractUploader"
      scene="document"
      mode="upload"
      ui-mode="headless"
      :upload-url="uploadUrl"
      upload-name="file"
      :parse-json="true"
      :show-progress="false"
      :show-file-count="false"
      @state-change="onContractUploadState"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      uploadUrl: 'https://unidemo.dcloud.net.cn/upload'
    }
  },
  methods: {
    chooseContract() {
      // headless 模式不渲染内置 UI，业务按钮通过 ref 调用 choose。
      this.$refs.contractUploader.choose()
    },
    onContractUploadState(state) {
      console.log('自定义上传状态', state)
    }
  }
}
</script>

权限说明

• 文件选择使用平台系统选择器，通常无需额外申请存储权限。
• Android 上传 content:// 文件时会临时复制到应用缓存目录，不会写入公共存储。
• 上传能力需要网络访问权限，业务侧需确保服务器地址、域名白名单、小程序后台配置等已正确设置。

自定义基座说明

本插件未引入三方原生 SDK。Web 和小程序不需要自定义基座；App 普通文件选择和普通上传可沿用已包含对应插件能力的基座。

可靠上传队列新增了 Android、iOS、Harmony 平台 UTS 文件系统与网络监听实现。App 端必须重新运行原生联编，或制作包含最新插件代码的自定义基座；只更新 WGT / appResource 不能让旧基座获得这部分原生能力。若业务侧再加入原生网络 SDK、权限、Manifest、依赖或资源，也需要重新制作对应平台自定义基座。

本次业务封装新增了根 utssdk/index.uts 导出和 interface.uts 类型声明，App 端如果已经安装旧自定义基座，需要重新运行原生联编或重新制作对应平台自定义基座后，才能直接调用 pickBusinessFiles / pickAndUploadBusinessFiles。可选 <lizhao-choose-file /> 组件和示例页已内置旧基座兼容兜底：当当前运行包尚未暴露业务 API 代理时，会退回已稳定暴露的 pickFiles + uploadFiles 组合，继续展示进度条、文件数量、文件列表和取消上传状态。

可测试上传接口

示例页默认使用已验证可上传的 DCloud 测试接口。公开接口仅适合插件联调，不建议用于线上业务。

测试建议：

小程序端使用公开测试接口前，需要先在小程序后台配置合法域名；正式业务请替换为自己的服务端接口。

注意事项

• 上传目标只支持通用 HTTP 服务器，不内置 uniCloud 上传。
• 可靠队列不要求分片初始化、分片查询或文件合并接口；已成功文件会跳过，中断中的单个文件从头重传，不能宣传为字节级断点续传或后台常驻上传。
• 队列恢复前先重新提供有效的 resolveRequest；HTTP 401/403 会进入 waiting-config，更新凭据并重新配置后再继续。
• method 固定为 POST，底层按平台上传 API 的 multipart/form-data 语义执行。
• name 默认值为 file，如果后端使用其他字段名，请通过 options.name 或 upload.name 指定。
• header 和 formData 都是普通对象；不要把 token、密钥、账号等敏感信息写死在示例代码或仓库中。
• 发布版运行日志会保留中文阶段、错误码、文件名与来源平台，但不会输出完整上传 URL、本地路径、临时路径或 picker URI；业务侧需要完整链路信息时，请在自己的回调里按需记录。
• accept 支持扩展名与 MIME；对于 application/zip、application/x-rar-compressed、application/vnd.rar、application/ofd、application/x-ofd 等常见归档/OFD 类型，平台未返回 MIME 时会按扩展名兜底校验，避免误报 9011005。
• Web / H5 调试公开上传接口时，默认不要传 X-Demo 等自定义请求头；部分公开接口不会在 CORS 预检响应中允许这些 header，浏览器会直接拦截上传。
• 服务器响应默认不会自动 JSON 解析；需要结构化响应时传 parseJson: true，插件会把解析成功的结果放入 UploadSuccessItem.parsedData，同时保留 data 原文。
• 上传默认以 HTTP 200-299 视为成功；后端使用 201、204 或其他固定成功码时，可通过 successStatusCodes 明确指定，传空数组则保持默认 2xx 规则。
• 多文件默认逐个上传，失败后停止；如需并发上传可传 sequential: false，如需跳过失败继续上传可传 stopOnFail: false，最终通过 UploadFilesResult.failResults 查看失败明细。
• progress 是持续回调，App 和插件根公开上传入口通过 @UTSJS.keepAlive 按 UTS 要求保活；Web / H5 与小程序平台胶水层不重复使用装饰器，避免目标编译器报 Decorators are not valid here。
• Android 选择到 content:// 文件时，插件会先复制到应用缓存目录再上传；如果复制失败会返回 9011011。
• iOS 选择到 file:// 路径时，插件会去掉前缀并做 decodeURI 后再上传。
• Harmony 选择到 file://media/Photo/...、file://docs... 等系统 URI 时，插件会先打开授权文件并复制到应用临时目录再上传；如果复制失败会返回 9011011。
• 示例中的公开测试接口只用于联调，不建议作为线上业务接口。

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。