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 }
平台差异
| 环境 | 选择 | 分享 | 上传 / 下载 |
|---|---|---|---|
| Android | ACTION_OPEN_DOCUMENT(SAF),复制到 _doc/lf_file_picker | ACTION_SEND + FileProvider | uni.uploadFile / downloadFile |
| iOS | UIDocumentPicker(Import),复制到沙盒 | UIActivityViewController | 同上 |
| 鸿蒙 | uni.chooseFile(有则用) | shareWithSystem 或 openDocument | 同上 |
| 微信小程序 | chooseMessageFile | openDocument / shareFileMessage | 同上(需合法域名) |
| H5 | <input type="file">,path 为 Object URL | Web Share 或触发下载 | 同上(受 CORS 约束) |
| nvue | 与 App-vue 同一套 JS API;plus 就绪内部轮询 | 同左 | 同左 |
| uni-app x | UTS 在 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)→ 下载 → 系统分享。
实现要点
为何先复制到沙盒
| 端 | 选择器返回 | 直接上传 / 分享的问题 |
|---|---|---|
| Android | content:// | 其它组件或进程未必持久可读;分享需要可授权 URI |
| iOS | security-scoped URL | 不 startAccessing 会读失败;离开作用域后失效 |
插件在选择成功后写入 _doc/lf_file_picker/,再返回该路径。业务侧拿到的是应用沙盒内路径,便于 uni.uploadFile 与 FileProvider / UIActivityViewController。
Android:SAF + 二次扩展名过滤
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)
结果处理:
ClipData或多选条目取出 URIContentResolver.openInputStream写入沙盒文件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 + 安全作用域
// 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。
-
选完界面长时间无反馈
现象:系统选择器关闭后页面无列表。
原因:正在把 URI 复制进沙盒。
处理:选择前后showLoading/hideLoading(Demo 已加)。 -
iOS 只能进相册、选不到微信里的文件
原因:走了相册 API。
处理:使用本插件chooseFile(Document Picker);在「浏览」中选文件 App / 微信目录。 -
Android 分享闪退或无分享面板
原因:FileProvider authority 与工程不一致,或分享了不可读路径。
处理:确认文件已是_doc/lf_file_picker/...;核对{包名}.dc.fileprovider。 -
extensions 过滤后
files为空,code 为invalidParam
原因:系统返回 MIME 与扩展名不一致,二次过滤剔除。
处理:放宽extensions,或同时配置更准的accept;核对真实后缀。 -
多选只返回 1 个文件
原因:multiple: false,或未传EXTRA_ALLOW_MULTIPLE/ iOS 未开allowsMultipleSelection。
处理:显式multiple: true,并设置合理maxCount。 -
小程序 chooseFile 返回 unsupported
原因:当前端无chooseMessageFile/chooseFile。
处理:看getPlatform();微信端确认基础库版本。 -
uploadFail 且 statusCode 为 0
原因:网络失败、域名未配、证书问题。
处理:抓message;小程序查合法域名;App 查 ATS / 清网关。 -
uploadFail 且 statusCode 为 401 / 403 / 500
原因:业务鉴权或服务端错误。
处理:检查header/formData;用同一 URL 在 Postman 对照。 -
H5 选文件后上传跨域失败
原因:服务端未允许当前 Origin。
处理:配置 CORS;开发期可用代理。 -
云打包 / 运行提示 UTS 编译失败、整模块不可用
原因:误启用有问题的utssdk。
处理:使用@/uni_modules/lf-file-picker/index.js;UTS 保持在utssdk.pending。 -
下载成功但分享失败
原因:仍指向已失效临时路径,或 H5 Object URL 不可被系统分享。
处理:App 使用插件返回的沙盒path;H5 走 Web Share / 下载降级。 -
鸿蒙返回 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)
检查项:
getPlatform()是否为预期端(android/ios/mp-weixin/web…)- 引入路径是否为
index.js ret.code是cancel、unsupported还是iofiles[0].path在 App 是否以_doc/lf_file_picker开头- 上传前用同一
path调uni.openDocument验证可读 - 小程序 upload / download 域名是否已配
- 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
接入要求:
- 目录为
uni_modules/lf-file-picker - 从
@/uni_modules/lf-file-picker/index.js引入 - 业务以
ok/code分支,不假定无抛错即成功 - 选择与大文件复制期间展示 loading
- Android 不默认依赖「所有文件访问」
- 小程序配置合法域名;H5 处理 CORS
- 相册场景继续用
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 插件的整体架构设计:
架构说明:
- 业务层:提供简洁的API接口,包括基础功能和组合功能
- 核心层:统一错误处理、文件过滤、进度管理等核心逻辑
- 平台适配层:针对不同平台调用原生API,实现跨平台一致性
- 存储层:统一文件存储路径,确保文件可读性和安全性
- 网络层:基于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、是否自定义调试基座、问题文件类型与大约体积。