uni-app 系统选文件与附件传输:chooseFile、系统分享、上传下载

49 阅读9分钟

uni-app 系统选文件与附件传输:chooseFile、系统分享、上传下载

插件:lf-file-picker 1.0.0
地址:ext.dcloud.net.cn/plugin?id=2…
官方文档:uni.uploadFile · Android 文档选择 · UIDocumentPicker

业务场景:表单附件、工单材料、合同 PDF / Excel 等非相册文件,需要从系统「文件」中选择,再上传业务服务器,或调起系统分享面板交给微信、邮件。本文说明方案选型、统一 API、各端实现、配置与真机问题。运行环境:uni-app Vue2/3、App-vue / nvue


需求

四类能力:

能力API说明
选择chooseFile单选 / 多选、extensions / accept 过滤,返回统一文件对象
分享shareFile / shareFiles本地路径调起系统分享
传输uploadFile / uploadFiles / downloadFile基于官方网络 API,带进度
组合chooseAndUpload / chooseAndShare / downloadAndShare薄封装,原子 API 仍可独立用

统一文件对象:

{ path, name, size, mime, ext }

平台差异

mermaid diagram

环境选择分享上传 / 下载
AndroidACTION_OPEN_DOCUMENT(SAF),复制到 _doc/lf_file_pickerACTION_SEND + FileProvideruni.uploadFile / downloadFile
iOSUIDocumentPicker(Import),复制到沙盒UIActivityViewController同上
鸿蒙uni.chooseFile(有则用)shareWithSystem 或 openDocument同上
微信小程序chooseMessageFileopenDocument / shareFileMessage同上(需合法域名)
H5<input type="file">,path 为 Object URLWeb Share 或触发下载同上(受 CORS 约束)
nvue与 App-vue 同一套 JS API;plus 就绪内部轮询同左同左
uni-app xUTS 在 utssdk.pending;当前用 index.js同左同左

处理流程:

chooseFile
   │
   ├─ Android ── OPEN_DOCUMENT → content:// → 复制 _doc/lf_file_picker
   ├─ iOS ────── UIDocumentPicker → 安全作用域 URL → 复制沙盒
   ├─ harmony ── chooseFile / unsupported
   ├─ mp-* ───── chooseMessageFile
   └─ web ────── input[type=file] → blob: URL
          │
          ├─ uploadFiles ── uni.uploadFile(串行或 concurrency)
          ├─ shareFiles ─── 系统 Share Sheet / openDocument
          └─ downloadFile ─ 临时路径 →(App)再拷贝到沙盒

选型结论:系统文档选择器权限面小于扫盘;云打包不强制绑定自定义原生选文件插件,降低「缺原生插件卡死」概率。代价是必须把 content:// / security-scoped URL 复制进应用可读路径,再给 uploadFile / 分享使用。


引入

import {
  chooseFile,
  shareFile,
  shareFiles,
  uploadFile,
  uploadFiles,
  downloadFile,
  chooseAndUpload,
  chooseAndShare,
  downloadAndShare,
  getPlatform,
  ErrorCode
} from '@/uni_modules/lf-file-picker/index.js'

使用 index.js 入口。不要依赖 UTS 自动代理路径。

pages.json 注册 Demo(可选):

{
  "path": "uni_modules/lf-file-picker/pages/demo/demo",
  "style": {
    "navigationBarTitleText": "文件选择与附件"
  }
}

统一返回与错误码

所有 API 返回同一形状,禁止静默失败:

{
  ok: false,
  code: 'cancel',
  message: '用户取消选择',
  files: [],
  path: '',
  statusCode: 0
}
code含义业务处理
ok成功读 files / path
cancel用户取消不提示或轻提示
unsupported当前端无能力隐藏入口或换端
invalidParam参数错误或类型过滤后为空检查 extensions / url
io读写、复制失败查路径与存储空间
shareFail分享失败查 FileProvider / 路径可读性
uploadFail / downloadFail网络环节失败查域名、HTTP statusCode、CORS
unknown未归类异常看 message
const ret = await chooseFile({ multiple: true, extensions: ['pdf'] })
if (!ret.ok) {
  if (ret.code === ErrorCode.CANCEL) return
  uni.showToast({ title: ret.message, icon: 'none' })
  return
}
console.log(ret.files)

用法

选择 PDF / Excel

const ret = await chooseFile({
  multiple: true,
  maxCount: 5,
  extensions: ['pdf', 'xlsx'],
  // accept: ['application/pdf'] // 可选,与 extensions 可同时用
})
if (!ret.ok) return

ret.files.forEach((f) => {
  console.log(f.name, f.size, f.path, f.mime, f.ext)
})

选择过程加 loading。Android / iOS 复制大文件到沙盒需要时间;无 loading 时表现为「选完界面卡住」。

系统分享

await shareFile(ret.files[0].path, {
  mime: ret.files[0].mime,
  title: '分享附件'
})

await shareFiles(
  ret.files.map((f) => f.path),
  { title: '分享附件' }
)

微信、邮件等目标由系统面板承接,插件不内置微信 SDK。

上传(含进度)

const up = await uploadFiles({
  files: ret.files,
  url: 'https://api.example.com/upload',
  name: 'file',
  header: { Authorization: 'Bearer <token>' },
  formData: { bizId: '1001' },
  concurrency: 1,
  onProgress({ progress, index }) {
    console.log('#' + (index + 1), progress)
  }
})
if (!up.ok) {
  console.log(up.code, up.message, up.results)
}

uploadFile 传单个 path。小程序须配置 upload 合法域名。

下载后打开或分享

const dl = await downloadFile({
  url: 'https://example.com/report.pdf',
  filename: 'report.pdf',
  onProgress({ progress }) {
    console.log(progress)
  }
})
if (!dl.ok) return

// 预览
uni.openDocument({ filePath: dl.path, showMenu: true })

// 或系统分享
await shareFile(dl.path, { title: '分享报告' })

组合 API

await chooseAndUpload(
  { multiple: true, extensions: ['pdf'] },
  { url: 'https://api.example.com/upload', name: 'file' }
)

await chooseAndShare(
  { multiple: false, extensions: ['pdf'] },
  { title: '分享附件' }
)

await downloadAndShare(
  { url: 'https://example.com/a.pdf', filename: 'a.pdf' },
  { title: '分享' }
)

Demo:/uni_modules/lf-file-picker/pages/demo/demo
流程:选文件(类型 / 多选)→ 列表 → 上传(默认可改 URL)→ 下载 → 系统分享。


实现要点

为何先复制到沙盒

端选择器返回直接上传 / 分享的问题
Androidcontent://其它组件或进程未必持久可读;分享需要可授权 URI
iOSsecurity-scoped URL不 startAccessing 会读失败;离开作用域后失效

插件在选择成功后写入 _doc/lf_file_picker/,再返回该路径。业务侧拿到的是应用沙盒内路径,便于 uni.uploadFile 与 FileProvider / UIActivityViewController。

Android:SAF + 二次扩展名过滤

mermaid diagram

const Intent = plus.android.importClass('android.content.Intent')
const intent = new Intent(Intent.ACTION_OPEN_DOCUMENT)
intent.addCategory(Intent.CATEGORY_OPENABLE)
intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
// 单 MIME:setType;多 MIME:setType('*/*') + EXTRA_MIME_TYPES
// 多选:EXTRA_ALLOW_MULTIPLE
main.startActivityForResult(intent, REQ_CODE)

结果处理:

  1. ClipData 或多选条目取出 URI
  2. ContentResolver.openInputStream 写入沙盒文件
  3. filterFilesByType 按 extensions / accept 再滤一层

系统 MIME 与真实扩展名不一致时,只靠 Intent MIME 会误放行或误杀。二次过滤保证 extensions: ['pdf'] 语义稳定。

分享:

// Android 7+ FileProvider
// authority 依次尝试:{包名}.dc.fileprovider、{包名}.fileprovider
intent.setAction(Intent.ACTION_SEND)
intent.putExtra(Intent.EXTRA_STREAM, uri)
intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)

不默认申请 MANAGE_EXTERNAL_STORAGE。

iOS:Document Picker + 安全作用域

mermaid diagram

// UIDocumentPickerModeImport = 0
const picker = new UIDocumentPickerViewController(typeArr, 0)
picker.setAllowsMultipleSelection(multiple)
// delegate:
//   documentPicker:didPickDocumentsAtURLs:
//   documentPickerWasCancelled:

复制前调用 startAccessingSecurityScopedResource,NSFileManager.copyItem 到沙盒后 stopAccessing。分享使用 UIActivityViewController;iPad 须设置 popoverPresentationController.sourceView,否则面板不出现或异常。

上传并发

uploadFiles 默认 concurrency: 1(串行)。提高到 2 / 3 可缩短总耗时,同时增加带宽与服务端压力。stopOnFail: true 时遇失败中断后续任务。

H5 / 小程序降级

端能力边界
H5必须由用户手势触发选择;取消时部分浏览器不触发 change,Promise 保持等待
H5 分享navigator.canShare({ files }) 可用则 Web Share,否则 <a download>
微信小程序会话文件为主(chooseMessageFile);无通用系统 Share Sheet
鸿蒙基座无对应 API 时返回 code: 'unsupported' 与明确 message

各端配置

Android

  • 选文件走 SAF,勿把 MANAGE_EXTERNAL_STORAGE 作为默认依赖(上架敏感)。
  • 分享依赖 FileProvider;uni-app 默认常见 authority:{应用包名}.dc.fileprovider。
  • 网络:INTERNET(工程通常已有)。

iOS

  • Document Picker 访问「文件」App;需要 iCloud 文档时按业务开启 Capability。
  • HTTP 下载 / 上传时按 ATS 配置域名。
  • 相册用途文案与本插件主路径无关;勿把「选附件」写成仅相册能力。

小程序

{
  "uploadFile": ["https://api.example.com"],
  "downloadFile": ["https://cdn.example.com"]
}

合法域名未配置时,uploadFail / downloadFail 的 message 含域名相关错误。

H5

  • 跨域上传由服务端配置 CORS。
  • path 为 blob: Object URL,仅当前页有效;刷新后失效。

插件 package.json → dcloudext.declaration 已写明:按宿主传入 URL 上传,不内置固定采集服务器。业务隐私政策按实际上传域名披露。


真机问题

验证环境:HBuilderX 正式版、自定义调试基座、Android 10+ 与 iOS 14+ 真机。下列条目来自实现约束与同类场景复现路径;发版前在目标机再跑一遍 Demo。

  1. 选完界面长时间无反馈
    现象:系统选择器关闭后页面无列表。
    原因:正在把 URI 复制进沙盒。
    处理:选择前后 showLoading / hideLoading(Demo 已加)。

  2. iOS 只能进相册、选不到微信里的文件
    原因:走了相册 API。
    处理:使用本插件 chooseFile(Document Picker);在「浏览」中选文件 App / 微信目录。

  3. Android 分享闪退或无分享面板
    原因:FileProvider authority 与工程不一致,或分享了不可读路径。
    处理:确认文件已是 _doc/lf_file_picker/...;核对 {包名}.dc.fileprovider。

  4. extensions 过滤后 files 为空,code 为 invalidParam
    原因:系统返回 MIME 与扩展名不一致,二次过滤剔除。
    处理:放宽 extensions,或同时配置更准的 accept;核对真实后缀。

  5. 多选只返回 1 个文件
    原因:multiple: false,或未传 EXTRA_ALLOW_MULTIPLE / iOS 未开 allowsMultipleSelection。
    处理:显式 multiple: true,并设置合理 maxCount。

  6. 小程序 chooseFile 返回 unsupported
    原因:当前端无 chooseMessageFile / chooseFile。
    处理:看 getPlatform();微信端确认基础库版本。

  7. uploadFail 且 statusCode 为 0
    原因:网络失败、域名未配、证书问题。
    处理:抓 message;小程序查合法域名;App 查 ATS / 清网关。

  8. uploadFail 且 statusCode 为 401 / 403 / 500
    原因:业务鉴权或服务端错误。
    处理:检查 header / formData;用同一 URL 在 Postman 对照。

  9. H5 选文件后上传跨域失败
    原因:服务端未允许当前 Origin。
    处理:配置 CORS;开发期可用代理。

  10. 云打包 / 运行提示 UTS 编译失败、整模块不可用
    原因:误启用有问题的 utssdk。
    处理:使用 @/uni_modules/lf-file-picker/index.js;UTS 保持在 utssdk.pending。

  11. 下载成功但分享失败
    原因:仍指向已失效临时路径,或 H5 Object URL 不可被系统分享。
    处理:App 使用插件返回的沙盒 path;H5 走 Web Share / 下载降级。

  12. 鸿蒙返回 unsupported
    原因:当前基座无 uni.chooseFile 等 API。
    处理:升级基座,或该端隐藏入口;Android / iOS 为主验收端。


排查

import {
  getPlatform,
  chooseFile,
  ErrorCode
} from '@/uni_modules/lf-file-picker/index.js'

console.log('platform =', getPlatform())

const ret = await chooseFile({
  multiple: true,
  maxCount: 3,
  extensions: ['pdf', 'png', 'txt']
})
console.log(ret.ok, ret.code, ret.message, ret.files)

检查项:

  1. getPlatform() 是否为预期端(android / ios / mp-weixin / web …)
  2. 引入路径是否为 index.js
  3. ret.code 是 cancel、unsupported 还是 io
  4. files[0].path 在 App 是否以 _doc/lf_file_picker 开头
  5. 上传前用同一 path 调 uni.openDocument 验证可读
  6. 小程序 upload / download 域名是否已配
  7. Android 分享失败时包名与 FileProvider 是否一致

Demo 页可改上传 / 下载 URL,便于对接真实接口联调。


源码目录

uni_modules/lf-file-picker/
├── index.js                 # 对外 API 与平台分流
├── constants.js             # ErrorCode、文件信息、类型过滤
├── transfer.js              # upload / download
├── platforms/
│   ├── android.js           # SAF 选择 + FileProvider 分享
│   ├── ios.js               # DocumentPicker + ActivityView
│   ├── harmony.js
│   ├── mp.js
│   └── web.js
├── pages/demo/demo.vue
├── utssdk.pending/          # uni-app x 占位(启用时改名为 utssdk)
├── package.json
├── readme.md
├── changelog.md
└── article.md

接入要求:

  1. 目录为 uni_modules/lf-file-picker
  2. 从 @/uni_modules/lf-file-picker/index.js 引入
  3. 业务以 ok / code 分支,不假定无抛错即成功
  4. 选择与大文件复制期间展示 loading
  5. Android 不默认依赖「所有文件访问」
  6. 小程序配置合法域名;H5 处理 CORS
  7. 相册场景继续用 uni.chooseImage,本插件专注文件 / 附件

完整调用链示例:

const picked = await chooseFile({
  multiple: true,
  maxCount: 5,
  extensions: ['pdf', 'xlsx']
})
if (!picked.ok) return

const up = await uploadFiles({
  files: picked.files,
  url: 'https://api.example.com/upload',
  name: 'file',
  onProgress({ progress, index }) {
    // 更新 UI
  }
})
if (!up.ok) return

// 需要再分享本地副本时:
await shareFiles(picked.files.map((f) => f.path))

整体架构图

以下是 lf-file-picker 插件的整体架构设计:

mermaid diagram

架构说明:

  1. 业务层:提供简洁的API接口,包括基础功能和组合功能
  2. 核心层:统一错误处理、文件过滤、进度管理等核心逻辑
  3. 平台适配层:针对不同平台调用原生API,实现跨平台一致性
  4. 存储层:统一文件存储路径,确保文件可读性和安全性
  5. 网络层:基于uni-app官方网络API,提供上传下载能力

这种分层设计确保了:

  • API 简洁易用,业务层无需关心平台差异
  • 错误处理统一,避免静默失败
  • 平台特性充分利用,同时保持行为一致
  • 文件路径统一管理,避免权限问题

适用边界

适合:

  • App 表单 / 工单附件选择与上传
  • 选本地文件后系统分享
  • URL 下载到本地再分享或 openDocument

不适合:

  • 完整磁盘文件管理器产品
  • 必须以「所有文件访问」扫全盘
  • 仅相册图片(用官方选图 API)
  • 断点续传、网盘同步

问题反馈

插件:ext.dcloud.net.cn/plugin?id=2…
关联:lf-file-share
邮箱:lingfugroup@gmail.com

反馈请附:端(Android / iOS / 鸿蒙 / 小程序 / H5)、基座或基础库版本、返回的 code / message、是否自定义调试基座、问题文件类型与大约体积。