更新记录

1.0.1（2026-06-12）

jujing-filereader 是一个 UTS 插件，用于在 Android 平台上读取二进制文件并返回其字节数据。

核心功能

该插件导出 readFileBytes 函数，接收文件路径作为参数，以字节数组形式返回文件内容。主要特点：

1. 支持两种文件路径格式：

   • 普通文件路径：通过 UTSAndroid.convert2AbsFullPath 转换为绝对路径后读取
   • Content URI（以 content:// 开头）：用于访问 Android 内容提供器的文件，如相册图片、文档选择器获取的文件等

2. 返回结果结构（ReadFileResult）：

   • data: number[] | null — 字节数组，失败时为 null
   • size: number — 文件大小
   • errMsg: string — 错误信息，成功时为空字符串

使用场景

适用于需要读取二进制文件或处理用户通过文件选择器选择的文件的场景，如图片处理、配置文件读取、数据导入等。

平台兼容性

uni-app x(5.12)

其他

jujing-filereader 插件功能概要

jujing-filereader 是一个 UTS 插件，用于在 Android 平台上读取二进制文件并返回其字节数据。

核心功能

该插件导出 readFileBytes 函数，接收文件路径作为参数，以字节数组形式返回文件内容。主要特点：

1. 支持两种文件路径格式：

   • 普通文件路径：通过 UTSAndroid.convert2AbsFullPath 转换为绝对路径后读取
   • Content URI（以 content:// 开头）：用于访问 Android 内容提供器的文件，如相册图片、文档选择器获取的文件等

2. 返回结果结构（ReadFileResult）：

   • data: number[] | null — 字节数组，失败时为 null
   • size: number — 文件大小
   • errMsg: string — 错误信息，成功时为空字符串

使用场景

适用于需要读取二进制文件或处理用户通过文件选择器选择的文件的场景，如图片处理、配置文件读取、数据导入等。

文件结构

uni_modules/jujing-filereader/
├── package.json           # 插件清单文件
├── index.uts             # 入口，导出 readFileBytes 和 ReadFileResult 类型
├── interface.uts         # 类型定义
└── utssdk/
    └── app-android/
        ├── config.json   # Android 原生配置
        └── index.uts     # Android 平台具体实现

系统和版本要求

• 运行平台：仅支持 Android
• 框架要求：uni-app 或 uniappX
• UTS 版本：UTS SDK 需要支持 Java interop
• 最低 Android 版本：Android 5.0（API 21）及以上

由于该插件直接调用 Android 原生 API（java.io.FileInputStream、android.content.Context 等），不支持 iOS、Web 或其他平台。

安装配置过程

步骤一：复制插件文件

将 jujing-filereader 目录完整复制到新项目的 uni_modules/ 目录下：

your-project/
├── uni_modules/
│   └── jujing-filereader/    # 复制到此目录
│       ├── package.json
│       ├── index.uts
│       ├── interface.uts
│       └── utssdk/
│           └── app-android/
│               ├── config.json
│               └── index.uts

步骤二：配置 uni-app 项目（仅 Android）

如需使用文件选择功能，在 manifest.json 中配置权限：

{
  "app-plus": {
    "android": {
      "permissions": [
        "android.permission.READ_EXTERNAL_STORAGE",
        "android.permission.WRITE_EXTERNAL_STORAGE"
      ]
    }
  }
}

如仅使用应用内部文件路径或 Content URI（用户主动选择的文件），通常无需额外声明权限。

步骤三：在代码中引入使用

import { readFileBytes, type ReadFileResult } from '@/uni_modules/jujing-filereader'

步骤四：验证安装

可在页面中测试调用：

const result = readFileBytes('/storage/emulated/0/test.txt')
console.log('安装验证:', result.errMsg || '成功，文件大小:' + result.size)

提示：如遇编译报错 UTSAndroid.convert2AbsFullPath 或 UTSAndroid.getAppContext 未定义，请确保：

1. 已将项目运行基座切换为 Android
2. HBuilderX 版本支持 UTS Android 原生能力
3. 清除缓存重新编译（菜单：运行 → 清除缓存并重新编译）

调用示例和说明

1. 基本导入

import { readFileBytes, type ReadFileResult } from '@/uni_modules/jujing-filereader'

2. 读取普通文件

const filePath = '/data/user/files/document.pdf'
const result: ReadFileResult = readFileBytes(filePath)

if (result.errMsg) {
  console.error('读取失败:', result.errMsg)
} else {
  console.log('文件大小:', result.size, '字节')
  console.log('前10字节:', result.data?.slice(0, 10))
}

3. 读取 Content URI 文件

用户通过文件选择器获取的 URI（如相册图片、文档选择器）：

// 假设从 uni.chooseFile 或类似 API 获取的 content URI
const contentUri = 'content://com.example.provider/document/123'

const result: ReadFileResult = readFileBytes(contentUri)

if (result.errMsg) {
  console.error('读取失败:', result.errMsg)
} else {
  console.log('文件大小:', result.size)
  // 将字节数组转换为 Uint8Array 进行进一步处理
  const uint8Array = new Uint8Array(result.data!)
}

4. 完整使用示例：文件选择并读取

import { readFileBytes, type ReadFileResult } from '@/uni_modules/jujing-filereader'

async function selectAndReadFile() {
  // 使用 uniapp 文件选择 API（示例）
  const res = await new Promise((resolve) => {
    uni.chooseFile({
      success: resolve,
      fail: () => resolve(null)
    })
  })

  if (!res || !res.path) {
    console.log('未选择文件')
    return
  }

  const result: ReadFileResult = readFileBytes(res.path)

  if (result.errMsg) {
    uni.showToast({
      title: '读取失败',
      icon: 'none'
    })
    return
  }

  // 打印文件信息
  console.log(`文件大小: ${result.size} 字节`)

  // 将字节转为十六进制字符串查看
  const hex = result.data?.map(b => b.toString(16).padStart(2, '0')).join('')
  console.log('十六进制内容:', hex?.substring(0, 64) + '...')

  return result.data
}

5. 注意事项

• 错误处理：务必检查 errMsg 是否为空字符串，即使 size 为 0 也可能是正常空文件
• 大文件：对于大文件，逐字节读取可能影响性能，当前实现使用 read() 循环读取
• 路径格式：
  • Android 本地文件路径通常为 /data/user/... 或 /storage/emulated/0/...
  • Content URI 格式如 content://media/external/files/xxx
• 权限：读取外部存储文件需要相应权限（通过 uni.authorize 或配置 manifest）