前言

在 uni-app 开发 App 时，官方 uni.chooseFile 在鸿蒙平台能力有限，想要选择 PDF、docx 等普通文档文件，需要调用鸿蒙原生 DocumentViewPicker 系统文件选择器。ebook-files-harmony 是完全免费的 UTS 插件，专门适配鸿蒙 App，封装系统 DocumentViewPicker；配合付费插件 ebook-select-files 可以做到 Android、iOS、鸿蒙三端一套 API，回调结构完全一致，不需要写多份差异化业务代码。

插件特点：无权限申请、不收集任何数据、MIT 协议、支持单选多选、后缀过滤、可复制文件到应用缓存目录。

插件市场地址：UTS系统文件选择器Harmony - DCloud 插件市场

一、插件平台兼容性

仅支持 APP-HARMONY（鸿蒙 App），Android / iOS 需要配套 ebook-select-files 付费插件。

平台	支持情况
鸿蒙 App	✅ 支持
Android	❌ 需要 ebook-select-files
iOS	❌ 需要 ebook-select-files
小程序 / H5	❌ 不支持

HBuilderX 版本要求 ≥3.1.0，导入 uni_modules 规范插件，鸿蒙必须制作自定义调试基座运行，普通基座无法调用 UTS 原生能力。

二、安装步骤

1. 插件市场下载插件 ebook-files-harmony，自动放到项目 uni_modules/ebook-files-harmony 目录。
2. HBuilderX 菜单：运行 → 制作自定义调试基座（勾选鸿蒙）。
3. 使用自定义基座运行鸿蒙 App。

三、核心 API 说明

selectFiles (options) 拉起文件选择器

参数	说明
count	最大选择数量，默认 1；大于 1 开启多选
extensions	后缀过滤数组，如 ['pdf','docx']，空数组不限制后缀；鸿蒙端生效
mimeTypes	MIME 类型数组，鸿蒙端会忽略该参数
copyToCache	是否复制选中文件到应用缓存目录，默认 true；true 得到稳定可访问路径；false 返回原始临时 uri，应用重启后权限失效
success	成功回调
fail	失败回调；用户取消错误码：8020001 errMsg:cancel
complete	完成回调

getSelectFilesCapabilities()

获取插件能力，鸿蒙端返回 supportsMimeTypes:false，代表不支持 MIME 过滤。

四、代码示例

示例 1：鸿蒙端直接调用（最小 demo）

import { selectFiles } from '@/uni_modules/ebook-files-harmony'

selectFiles({
  count: 2, // 最多选2个，多选
  extensions: ['pdf', 'docx'], // 只允许pdf、docx文件
  copyToCache: true, // 复制到缓存，拿到稳定访问路径
  success(res) {
    console.log('文件选择成功：', res)
    // res内返回选中文件数组：路径、文件名、大小等信息
  },
  fail(res) {
    console.log('文件选择失败：', res)
    // 判断用户取消
    if(res.errCode === 8020001){
      console.log('用户取消选择文件')
    }
  },
  complete(){
    console.log('选择操作结束')
  }
})

示例 2：三端统一封装（推荐！Android+iOS+鸿蒙一套业务代码）

新建文件 utils/select-files.js，利用条件编译区分平台：

// #ifdef APP-HARMONY
export {
  selectFiles,
  getSelectFilesCapabilities,
} from '@/uni_modules/ebook-files-harmony'
// #endif

// #ifndef APP-HARMONY
// Android / iOS端使用付费插件 ebook-select-files
export {
  selectFiles,
  getSelectFilesCapabilities,
} from '@/uni_modules/ebook-select-files'
// #endif

业务页面直接导入，不需要关心当前是什么平台：

import { selectFiles } from '@/utils/select-files'

// 业务代码完全同一套，三端表现一致
selectFiles({
  count:1,
  extensions:['pdf'],
  copyToCache:true,
  success(res){
    console.log('选中文件',res)
  },
  fail(err){
    console.error(err)
  }
})

五、重要注意事项

1. copyToCache 参数的坑
   • copyToCache:true：插件自动把系统返回临时 uri 文件复制到应用沙盒缓存目录，拿到持久可用路径，适合上传、读取；推荐业务使用 true。
   • copyToCache:false：直接返回鸿蒙原始 uri，只有临时访问权限，App 重启之后就不能访问文件，仅适合临时读取场景。
2. 用户取消判断：错误码固定为 8020001，errMsg="cancel"，业务层建议捕获处理。
3. 鸿蒙端 MIME 参数 mimeTypes 不生效，只能靠 extensions 后缀过滤文件。
4. 本插件不需要申请任何系统权限，底层调用系统 DocumentViewPicker，遵循鸿蒙文件访问安全模型，用户手动授权文件访问权限。
5. 插件不采集任何用户数据，无广告，MIT 开源协议。

六、常见问题

Q：运行没有拉起文件选择器？

A：必须使用鸿蒙自定义调试基座，普通基座不支持 UTS 插件。HBuilderX 版本≥3.1.0。

Q：拿到路径无法读取文件？

A：检查 copyToCache，如果设置 false，返回的 uri 是临时权限，App 关闭权限失效；上传业务务必设置为 true。

Q：Android、iOS 运行报错找不到模块？

A：Android 和 iOS 平台必须安装配套付费插件 ebook-select-files，否则非鸿蒙环境导入会报错。

七、总结

ebook-files-harmony 解决 uni-app 鸿蒙 App 选择文档文件痛点，免费使用，API 和 Android/iOS 付费插件对齐，通过简单条件编译，实现三端统一文件选择逻辑，不用手写 UTS 调用 DocumentViewPicker 原生代码，大幅减少跨平台适配工作量。