更新记录

1.0.0（2026-08-04） 下载此版本

新增

• 文件选择与附件传输插件：系统选文件、本地系统分享、上传、下载与组合 API。
• API：
  • chooseFile：单选 / 多选、maxCount、extensions / accept 过滤
  • shareFile / shareFiles：调起系统分享面板
  • uploadFile / uploadFiles：基于 uni.uploadFile，支持进度与并发
  • downloadFile：基于 uni.downloadFile，支持进度；App 落盘 _doc/lf_file_picker
  • chooseAndUpload / chooseAndShare / downloadAndShare
  • getPlatform、ErrorCode
• 统一返回：{ ok, code, message, files?, path?, statusCode? }，禁止静默失败。
• 端实现：
  • Android：ACTION_OPEN_DOCUMENT + 复制到沙盒；分享 FileProvider
  • iOS：UIDocumentPicker + UIActivityViewController
  • 鸿蒙：chooseFile / shareWithSystem / openDocument 能力内降级
  • 小程序：chooseMessageFile + openDocument / shareFileMessage
  • H5：<input type=file> + Web Share / 下载降级
• Demo：/uni_modules/lf-file-picker/pages/demo/demo

说明

• 引入路径：@/uni_modules/lf-file-picker/index.js
• uni-app x UTS 代码位于 utssdk.pending；启用时改名为 utssdk

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lf-file-picker 使用教程

从系统选择任意类型文件（多选、扩展名 / MIME 过滤），得到统一文件对象；支持上传到业务服务器、URL 下载到本地、以及把本地文件调起系统分享。

支持端：Android、iOS、鸿蒙、微信等小程序、H5。
支持技术：Vue2、Vue3、App-vue、nvue。uni-app x（UTS）见文末。

1. 安装

1. 将本目录放到项目 uni_modules/lf-file-picker
2. 在 pages.json 注册 Demo（可选）：

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

3. Android / iOS 权限声明见下文「各端配置」。默认不申请「所有文件访问」。

2. 引入

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

请使用上述路径。不要依赖 UTS 自动代理入口（避免云打包 / 编译卡死）。

3. 统一返回

所有 API 返回：

{
  ok: true,
  code: 'ok', // ok | cancel | unsupported | invalidParam | io | shareFail | uploadFail | downloadFail | unknown
  message: 'ok',
  files: [{ path, name, size, mime, ext }],
  path: '',
  statusCode: 0
}

业务侧以 ok / code 分支，不要假定「无抛错即成功」。

4. API

4.1 chooseFile

const ret = await chooseFile({
  multiple: true,
  maxCount: 5,
  extensions: ['pdf', 'xlsx', 'png'], // 可选
  accept: ['application/pdf']        // 可选，MIME；与 extensions 可同时用
})
if (ret.ok) {
  console.log(ret.files)
}

相册选图请用 uni.chooseImage；本插件主路径是「文件 / 附件」。

4.2 shareFile / shareFiles

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

4.3 uploadFile / uploadFiles

await uploadFile({
  path: file.path,
  url: 'https://api.example.com/upload',
  name: 'file',
  formData: { bizId: '1' },
  header: { Authorization: 'Bearer xxx' },
  ({ progress }) { console.log(progress) }
})

await uploadFiles({
  files: ret.files,
  url: 'https://api.example.com/upload',
  concurrency: 1, // 默认串行
  ({ progress, index }) {}
})

基于 uni.uploadFile。小程序需配置 upload 合法域名。

4.4 downloadFile

const dl = await downloadFile({
  url: 'https://example.com/a.pdf',
  filename: 'a.pdf',
  ({ progress }) {}
})
// dl.path 可接 shareFile 或 uni.openDocument

App 端尽量复制到 _doc/lf_file_picker/；其它端返回临时路径。

4.5 组合 API

await chooseAndUpload(chooseOpts, uploadOpts)
await chooseAndShare(chooseOpts, shareOpts)
await downloadAndShare(downloadOpts, shareOpts)

原子 API 仍可独立使用。

5. 各端配置

Android

• 选文件走 SAF，不要默认加 MANAGE_EXTERNAL_STORAGE（审核风险高）。
• 分享依赖 FileProvider；uni-app 默认常见 authority：{包名}.dc.fileprovider。
• 上传 / 下载需要网络权限（一般已有 INTERNET）。

iOS

• 使用系统文件选择器；若需 iCloud 文档，在 Xcode Capability 按业务开启。
• Info.plist 按实际上传 / 下载域名配置 ATS（如有 HTTP）。

小程序

• 微信：chooseMessageFile；分享侧多用 openDocument 右上角菜单。
• 配置 uploadFile / downloadFile 合法域名。

H5

• 选择依赖用户手势触发 <input type=file>。
• 跨域上传需服务端 CORS；Object URL 仅当前页有效。

6. Demo

路径：/uni_modules/lf-file-picker/pages/demo/demo

流程：选文件（类型 / 多选）→ 列表 → 上传（可改 URL）→ 下载 → 系统分享。

7. 调用建议

1. chooseFile 后立刻展示列表与 loading，避免「选完卡住」的体感。
2. 分享前确认 path 可读（App 使用插件复制后的沙盒路径）。
3. 上传失败看 code === 'uploadFail' 与 statusCode。
4. 当前端返回 unsupported 时隐藏入口或换端实现，不要静默忽略。

8. uni-app x

UTS 实现放在 utssdk.pending/。Vue / App 当前使用 index.js。
需要启用 UTS 时，将目录改名为 utssdk 并按官方插件规范编译；若 UTS 编译失败导致整模块不可用，请改回 utssdk.pending。

9. 联系

• 邮箱：lingfugroup@gmail.com

问题反馈请附：端（Android/iOS/…）、基座版本、code / message、是否自定义基座。