更新记录

1.2.10（2026-06-17）

• 复修 iOS 云打包 unable to type-check this expression in reasonable time：launchIosPicker 主线程闭包拆为 runLaunchIosPicker()，减少 Swift 对大闭包表达式的类型推断压力。
• 新增 picker mode、mode 文案、布尔字符串和日志拼接 helper，避免三元表达式与 UIDocumentPickerViewController 构造器组合在同一推断链路中。
• 保留 1.2.9 的上传响应文本、成功状态码数组和多文件统计字段 SwiftCompile 兼容修复。
• 本版本仅修改 utssdk/app-ios 平台实现和发布资料，不修改公共接口、Android、Harmony、Web、小程序或 uni-app 示例。

1.2.9（2026-06-16）

• 修复 iOS 云打包 SwiftCompile：UploadSuccessItem.data 等上传响应文本统一通过 helper 收敛为非空字符串，避免 String? 直接赋值。
• 修复成功状态码数组处理：appendSuccessStatusCode 返回新数组，避免 Swift 生成物对不可变数组执行追加。
• 修复多文件上传批量统计：成功数量、失败数量和 failResults 长度统一转为 NSNumber 兼容值，避免 Int -> NSNumber 参数不匹配。
• 保留 parsedData / successStatusCodes / failResults / sequential: false 等 1.2.8 上传增强能力，本轮只做 iOS 云打包兼容收口。
• 增强 iOS 云打包回归守卫；本版本需重新提交 iOS 云打包验证。

1.2.8（2026-06-15）

• 新增上传结果增强：UploadSuccessItem 增加 parsedData，可通过 parseJson 将服务器响应 JSON 解析到结构化字段，同时保留 data 原始字符串。
• 新增上传成功状态码配置：successStatusCodes 支持业务自定义 HTTP 成功状态码；不传或传空数组时默认仍按 200-299 判断成功。
• 新增多文件失败明细：UploadFilesResult 增加 failResults，在 stopOnFail: false 或部分失败场景下返回失败文件、下标和错误对象。
• 优化多文件上传模式：sequential: false 现在会真实并发上传多个文件，进度回调中的 index 仍对应原始文件下标。
• 同步内置 <lizhao-choose-file /> 组件：新增 parse-json 和 success-status-codes 属性，可在组件上传模式中直接使用响应解析与成功码配置。
• 补充示例与文档：插件示例和项目演示页新增串行/并发、响应 JSON 解析、成功码和部分失败测试入口，README 顶部新增 1.2.8 上传增强说明。
• 发布前验证：Android / Harmony / iOS appResource 均已编译并导出成功，相关 LSP 与 choose-file 回归守卫通过。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-choose-file

lizhao-choose-file 是面向 uni-app / uni-app x 的文件选择与上传插件。你可以只用 API 做文件选择，也可以直接使用内置 <lizhao-choose-file /> 业务 UI，快速获得上传按钮、进度条、文件数量、文件图标、文件名称、文件大小、删除文件和取消上传能力。

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

1.2.10 iOS 云打包复修

本版本继续收口 iOS 文件选择器云打包兼容问题：launchIosPicker 主线程闭包拆分为小 helper，picker mode、日志文案和布尔字符串拼接均独立计算，降低 Swift 对大闭包表达式的类型推断压力。

升级提示：iOS 端请重新云打包或重新进行 iOS 原生联编；Android / Harmony / Web / 小程序运行逻辑不变。

1.2.9 iOS 云打包修复

本版本在保留 1.2.8 上传增强能力的基础上，收口 iOS 云打包 SwiftCompile 兼容问题，适合准备提交 iOS 云打包或插件市场发布前升级。

升级提示：本版本修复公共上传核心。iOS 端必须重新云打包或重新进行 iOS 原生联编；Android / Harmony 如需使用最新上传核心，也建议重新运行对应平台原生联编或重新制作自定义基座。

1.2.8 上传增强

本版本重点增强通用 HTTP 上传结果和多文件上传体验，适合需要对接业务上传接口、解析服务端 JSON、展示部分失败结果或提升多文件上传速度的场景。

升级提示：本版本修改了 UTS 上传接口类型和 App/Harmony 上传实现。App 端如已使用旧自定义基座，需要重新运行原生联编或重新制作对应平台自定义基座后，才能使用 parsedData / failResults / sequential=false 等最新上传能力。

接入方式怎么选

从简单到复杂接入

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. 使用内置业务 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\index.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 用于减少常见页面重复写 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 时会并发上传，传 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\index.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，默认不需要自定义基座。若业务侧后续自行加入原生网络 SDK 或额外权限配置，需要重新制作自定义基座。

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

可测试上传接口

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

测试建议：

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

注意事项

• 上传目标只支持通用 HTTP 服务器，不内置 uniCloud 上传。
• 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 与小程序上传入口已按 UTS 要求使用 @UTSJS.keepAlive 保活；Web / H5 端不能使用该装饰器，否则 Vite/esbuild 会报 Decorators are not valid here。
• Android 选择到 content:// 文件时，插件会先复制到应用缓存目录再上传；如果复制失败会返回 9011011。
• iOS 选择到 file:// 路径时，插件会去掉前缀并做 decodeURI 后再上传。
• Harmony 选择到 file://media/Photo/...、file://docs... 等系统 URI 时，插件会先打开授权文件并复制到应用临时目录再上传；如果复制失败会返回 9011011。
• 示例中的公开测试接口只用于联调，不建议作为线上业务接口。

作者系列UTS插件

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