更新记录

1.0.1（2026-07-07）

发版本

1.0.0（2026-07-07）

发版

平台兼容性

uni-app(5.14)

uni-app x(5.14)

jiabo-uts-file-kit

赛博老李三端文件选择 UTS 插件，提供 Android / iOS / HarmonyOS 统一文件选择 API。

特性

安装

在 uni-app 项目中，将 jiabo-uts-file-kit 复制到 uni_modules/ 目录下，或通过插件市场安装。

导入

import {
  chooseFile,
  getFileInfo,
  normalizePath,
  setFilePickBehavior,
  getFilePickBehavior,
  buildUploadPayload,
  uploadFile
} from '@/uni_modules/jiabo-uts-file-kit'

API

chooseFile(options)

打开系统文件选择器。

chooseFile({
  multiple: true,
  count: 5,
  mimeTypes: ['application/pdf', 'image/*'],
  extensions: ['pdf', 'jpg', 'png'],
  success(res) {
    console.log('选中文件:', res.files)
  },
  fail(res) {
    console.error('选择失败:', res.message)
  },
  complete(res) {
    console.log('选择完成:', res.code)
  }
})

getFileInfo(options)

读取指定路径或 URI 的文件信息。

getFileInfo({
  path: 'content://...',
  success(res) {
    console.log(res.file)
  }
})

normalizePath(path)

归一化 file://、unifile:// 等路径。

buildUploadPayload(options)

从路径、文件名、MIME 类型生成统一上传参数。

const payload = buildUploadPayload({
  path: 'content://...',
  name: 'report.pdf',
  mimeType: 'application/pdf'
})

uploadFile(options)

上传辅助函数。当前版本负责路径归一化和参数构建，并通过 success/fail/complete 回调返回统一结构，业务侧可将结果传给 uni.uploadFile。

setFilePickBehavior / getFilePickBehavior

切换或查询文件选择行为。

setFilePickBehavior('mock')
setFilePickBehavior('system')
const mode = getFilePickBehavior()

平台说明

Android

• 使用 Intent.ACTION_OPEN_DOCUMENT
• content:// URI 可直接保留给上传链路
• getFileInfo 使用 ContentResolver.query(OpenableColumns) 获取名称、大小和 MIME 类型
• extensions 会映射为 MIME 类型传给系统选择器，选择结果会按 count 兜底截断
• 不声明 READ_EXTERNAL_STORAGE、READ_MEDIA_IMAGES、READ_MEDIA_VIDEO、READ_MEDIA_AUDIO

iOS

• 使用 UIDocumentPickerViewController
• 使用 asCopy: true，让应用获取可访问副本
• 支持 MIME 与扩展名到 UTType 的映射
• 读取文件大小时通过 NSFileManager 查询

HarmonyOS

• 使用 @ohos.file.picker.DocumentViewPicker
• 支持 maxSelectNumber 与 fileSuffixFilters
• 使用 @ohos.file.fs.statSync 读取沙箱路径文件大小
• 选择器 URI 会原样返回给业务上传链路

本地测试

node scripts/check-structure.mjs
node scripts/test-plugin.mjs

test-plugin.mjs 会校验三端 API 导出、Android 权限声明、非三端平台未声明状态，并调用 HBuilderX 自带 UTS 编译器验证 Android Kotlin、iOS Swift、Harmony ArkTS/ETS 转译。

上架说明

1. 填写 package.json 中的 repository 和 dcloudext.contact
2. 按需调整 sale 中的价格
3. 删除 .DS_Store 等系统文件
4. 准备 Android、iOS、HarmonyOS 三端运行截图和隐私说明

版本历史

• 1.0.0 - Android SAF 文件选择 + iOS UIDocumentPicker + HarmonyOS DocumentViewPicker，三端完整实现
• 0.1.0 - 首版 Android picker 入口 + iOS/HarmonyOS 初始实现 + mock 模式