更新记录

1.0.0（2026-08-06）

支持 Android 系统文件选择器与可选持久化 URI 授权；支持 content:// 元数据查询、流式复制、流式 SHA-256 和限长文本读取；无需传统存储权限，不联网、不采集数据。

平台兼容性

uni-app(5.15)

uni-app x(5.15)

Content URI 文件桥接

leafkit-filebridge 提供 Android 系统文件选择器，并安全处理返回的 content:// URI。它可以把授权文件变成可读取、可校验、可交给上传逻辑使用的应用沙盒文件。

适用场景

• content:// 无法被普通文件 API 直接读取；
• 文件上传结果为 0KB；
• 需要获取真实文件名、MIME 类型和大小；
• 需要校验大文件在复制或上传前后是否完整；
• 需要把授权 URI 复制到应用缓存后再处理。

特点

• 不申请 MANAGE_EXTERNAL_STORAGE 或传统读写存储权限；
• 通过系统 ACTION_OPEN_DOCUMENT 选择文件，可选择持久化读取授权；
• 所有处理均在设备本地完成，不联网、不采集数据；
• 复制和文件校验都采用固定大小的缓冲区，不把整个文件载入内存；
• 文本读取默认限制为 1MB，可由调用方调整。

平台

• 当前提供 Android UTS 实现，支持 uni-app、uni-app x；
• HBuilderX 5.15+；
• 已在 Huawei P20（HarmonyOS 3.0，Android 兼容环境 / API 29）完成真机验证。

市场兼容表中的“鸿蒙 ×”表示当前没有原生 app-harmony 实现，不代表它无法在带 Android 兼容环境的鸿蒙设备上运行。当前未提供原生 app-harmony、iOS、Web 和小程序实现。

导入

import {
  pickDocument,
  inspectUri,
  copyUriToCache,
  sha256Uri,
  readUriText
} from '@/uni_modules/leafkit-filebridge'

uni-app x 类型说明

HBuilderX 5.15 的 uni-app x UTS 编译器可能无法把内联对象字面量推断成插件导出的 Options 类型，并报 error17。在 .uvue 中请显式导入并声明对应类型：

import {
  inspectUri,
  InspectUriOptions
} from '@/uni_modules/leafkit-filebridge'

const options : InspectUriOptions = {
  uri: 'content://...',
  success: (res) => { console.log(res.name) },
  fail: (err) => { console.error(err.errCode) }
}
inspectUri(options)

PickDocumentOptions、CopyUriOptions、Sha256Options 和 ReadUriTextOptions 的用法相同。传统 uni-app Vue2/Vue3 可以直接使用下方对象字面量写法。

选择文件

pickDocument({
  mimeType: '*/*',
  persistPermission: true,
  success(res) {
    console.log(res.uri)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)
  }
})

pickDocument 使用 Android 系统文件选择器，不需要传统存储权限。用户取消选择时返回 1900005。

读取元数据

inspectUri({
  uri: 'content://...',
  success(res) {
    console.log(res.name, res.mimeType, res.size)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)
  }
})

复制到应用缓存

copyUriToCache({
  uri: 'content://...',
  success(res) {
    // res.path 是应用缓存中的绝对路径，可交给后续读取或上传逻辑。
    console.log(res.path, res.size)
  }
})

缓存文件位于应用 cache/leafkit-filebridge/ 目录，由系统缓存策略管理。插件不会自动删除调用方仍在使用的文件。

文件完整性校验

sha256Uri({
  uri: 'content://...',
  success(res) {
    console.log(res.sha256, res.size)
  }
})

sha256Uri 返回文件校验值和实际读取的字节数，适合在复制或上传前后进行一致性检查。

读取小型文本

readUriText({
  uri: 'content://...',
  maxBytes: 1024 * 1024,
  charset: 'UTF-8',
  success(res) {
    console.log(res.text)
  }
})

超过 maxBytes 时返回错误码 1900004，不会继续把文件读入内存。

错误码

隐私与权限

插件不申请存储权限，不采集、不保存、不上传任何用户数据。它只能访问用户通过 Android 系统授权的 URI；授权失效时会明确返回失败。

试用建议

请至少测试以下文件来源：系统“文件”应用、下载目录、相册提供方、网盘/第三方 DocumentsProvider，以及中文文件名和大文件。