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

插件：`lf-file-picker` 1.0.0  
地址：[https://ext.dcloud.net.cn/plugin?id=29102](https://ext.dcloud.net.cn/plugin?id=29102)  
官方文档：[uni.uploadFile](https://uniapp.dcloud.net.cn/api/request/network-file.html#uploadfile) · [Android 文档选择](https://developer.android.com/guide/topics/providers/document-provider) · [UIDocumentPicker](https://developer.apple.com/documentation/uikit/uidocumentpickerviewcontroller)

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

---

## 需求

四类能力：

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

统一文件对象：

```js
{ path, name, size, mime, ext }
```

---

## 平台差异


![mermaid diagram](https://developer.qcloudimg.com/http-save/yehe-7556547/dac0e7032e7b3f3e6f8f9d153b950634.png)


| 环境 | 选择 | 分享 | 上传 / 下载 |
| --- | --- | --- | --- |
| 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` | 同左 | 同左 |

处理流程：

```text
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` / 分享使用。

---

## 引入

```js
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（可选）：

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

---

## 统一返回与错误码

所有 API 返回同一形状，禁止静默失败：

```js
{
  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` |

```js
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

```js
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 时表现为「选完界面卡住」。

### 系统分享

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

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

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

### 上传（含进度）

```js
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 合法域名。

### 下载后打开或分享

```js
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

```js
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 + 二次扩展名过滤


![mermaid diagram](https://developer.qcloudimg.com/http-save/yehe-7556547/23a410363a542603399f19d2498904b2.png)


```js
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']` 语义稳定。

分享：

```js
// 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](https://developer.qcloudimg.com/http-save/yehe-7556547/20b843f1c5a98070f853622d96bf4e37.png)


```js
// 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 配置域名。  
- 相册用途文案与本插件主路径无关；勿把「选附件」写成仅相册能力。

### 小程序

```json
{
  "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 为主验收端。

---

## 排查

```js
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，便于对接真实接口联调。

---

## 源码目录

```txt
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`，本插件专注文件 / 附件  

完整调用链示例：

```js
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](https://developer.qcloudimg.com/http-save/yehe-7556547/bef6feecc8e7c5dc1f4f493483f2d5a4.png)

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

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

## 适用边界

适合：

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

不适合：

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

---

## 问题反馈

插件：[https://ext.dcloud.net.cn/plugin?id=29102](https://ext.dcloud.net.cn/plugin?id=29102)  
关联：[lf-file-share](https://ext.dcloud.net.cn/plugin?id=26490)  
邮箱：[lingfugroup@gmail.com](mailto:lingfugroup@gmail.com)  


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

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

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

前端

客户端

开发工具

uni-app选文件与附件传输方案，实现chooseFile、系统分享及上传下载。支持Android SAF、iOS DocumentPicker、小程序及H5，兼容PDF/Excel等非相册文件，提供统一API、进度回调与组合方法。适配Vue2/3、nvue及App平台，简化表单附件、工单材料传输流程。

文件存储

代码解释

服务器

Android

JSON

热销域名限时优惠，新客首年免费！


domain

让每一个 Agent，都跑在云上

CDN免费试用


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

uni-app 系统选文件与附件传输：chooseFile、系统分享、上传下载-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐