更新记录

1.0.0（2026-06-11） 下载此版本

RFID插件

平台兼容性

uni-app(3.7.9)

Html5app-UHFReader 原生插件编译说明

一、环境准备

1. 必须安装的软件

2. 下载 uni-app Android 离线 SDK

由于编译原生插件需要引用 uni-app 的 SDK，你需要先下载离线打包 SDK：

1. 打开 DCloud 官网：https://nativesupport.dcloud.net.cn/
2. 找到 "App 离线打包 SDK" → Android 离线打包 SDK
3. 下载最新版（与你的 HBuilderX 版本对应）
4. 解压后，在里面找到：

   SDK/libs/uniapp-v8-release.aar

   （文件名可能是 uniapp-release.aar 或 uniapp-v8-release.aar）

⚠️ 注意：如果找不到离线 SDK，也可以先创建一个空的 uni-app 本地打包项目，HBuilderX 会生成包含 SDK 的目录。

二、创建 Android Library 项目

步骤 1：新建项目

1. 打开 Android Studio
2. 选择 File → New → New Project
3. 选择 "Empty Activity" 模板，点击 Next
4. 填写项目信息：
   • Name: UHFReaderPlugin
   • Package name: com.html5app.uni_uhfreader
   • Language: Java
   • Minimum SDK: API 19
   • 点击 Finish

步骤 2：新建 Library Module

1. 在项目面板中，右键点击项目根目录
2. 选择 New → Module
3. 选择 "Android Library"，点击 Next
4. 填写 Module 信息：
   • Module name: uhfreader
   • Package name: com.html5app.uni_uhfreader
   • Language: Java
   • Minimum SDK: API 19
   • Target SDK: API 29 (Android 10)
   • 点击 Finish

步骤 3：删除没用的 app module（可选）

为了干净，可以把自动创建的 app module 删掉：

1. 在项目面板右键 app → Open Module Settings
2. 选中 app，点击上方 - 号删除
3. 在 settings.gradle 中删除 include ':app' 这一行

三、复制文件到 Library Module

1. 复制 jar 包

把本目录下的 jar 包复制到 module 的 libs：

# 源路径（在你的 uni-app 项目中）
nativeplugins/Html5app-UHFReader/android/libs/

# 目标路径（Android Studio 项目中）
UHFReaderPlugin/uhfreader/libs/

同时把 uni-app SDK 的 aar 也复制进去：

UHFReaderPlugin/uhfreader/libs/uniapp-v8-release.aar

2. 复制 so 库

# 源路径
nativeplugins/Html5app-UHFReader/android/jniLibs/

# 目标路径
UHFReaderPlugin/uhfreader/src/main/jniLibs/

最终 jniLibs 结构：

uhfreader/src/main/jniLibs/
├── arm64-v8a/
│   ├── libdevapi.so
│   ├── libirdaSerialPort.so
│   ├── libjni_rfid_driver.so
│   ├── libModuleAPIJni.so
│   ├── libserial_port.so
│   └── libSerialPort.so
├── armeabi-v7a/
│   └── （同上 6 个 so）
└── armeabi/
    └── （同上 6 个 so）

3. 复制封装源码

把 UHFReaderModule.java 复制到：

UHFReaderPlugin/uhfreader/src/main/java/com/html5app/uni_uhfreader/UHFReaderModule.java

四、配置 build.gradle

打开 uhfreader/build.gradle，替换为以下内容：

plugins {
    id 'com.android.library'
}

android {
    compileSdkVersion 29
    buildToolsVersion "29.0.3"

    defaultConfig {
        minSdkVersion 19
        targetSdkVersion 29
        versionCode 1
        versionName "1.0"

        ndk {
            abiFilters 'armeabi', 'armeabi-v7a', 'arm64-v8a'
        }
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    sourceSets {
        main {
            jniLibs.srcDirs = ['src/main/jniLibs']
        }
    }
}

dependencies {
    // uni-app SDK（编译时引用，不打包进去）
    compileOnly fileTree(dir: 'libs', include: ['uniapp*.aar'])

    // UHF jar 包（编译时引用，不打包进去，因为最终 uni-app 会统一处理）
    compileOnly fileTree(dir: 'libs', include: ['*.jar'])

    // fastjson（uni-app 内置，编译时引用）
    compileOnly 'com.alibaba:fastjson:1.1.46.android'
}

💡 说明：

• compileOnly 表示只在编译时使用，不会打包到最终的 aar 里
• 这样生成的 aar 体积更小，jar 和 so 仍然由 uni-app 本地插件机制统一管理

五、编译生成 aar

方法 1：通过 Android Studio 界面编译

1. 点击顶部菜单 Build → Make Project（或按 Cmd + F9）
2. 如果没有报错，继续点击 Build → Rebuild Project
3. 编译成功后，aar 文件会生成在：

   uhfreader/build/outputs/aar/uhfreader-release.aar

方法 2：通过 Gradle 命令编译

在 Android Studio 底部的 Terminal 中执行：

./gradlew :uhfreader:assembleRelease

或在 Mac 终端中：

cd /path/to/UHFReaderPlugin
./gradlew :uhfreader:assembleRelease

编译成功后，aar 路径同上。

六、把 aar 放到 uni-app 项目中

1. 整理插件目录

在 uni-app 项目中，把插件目录整理为仅包含 aar 的最终形态：

cd /path/to/CHAppPlus/nativeplugins/Html5app-UHFReader/

删除源码目录（可选，但推荐）：

rm -rf android/src
rm -rf android/jniLibs
rm android/build.gradle
rm android/AndroidManifest.xml

保留 libs 目录（因为 jar 和 so 需要被打包进 APK）：

# 保留以下结构
android/
├── libs/
│   ├── App_Demo_API.jar
│   ├── DeviceAPIver20150204.jar
│   ├── logutil-1.5.1.1.jar
│   ├── ModuleAPI_J.jar
│   ├── reader(1).jar
│   ├── UHF67_v3.6.jar
│   └── uhfreader-release.aar   ← 把你编译的 aar 放这里
├── jniLibs/
│   ├── arm64-v8a/      ← 保留 6 个 so
│   ├── armeabi-v7a/    ← 保留 6 个 so
│   └── armeabi/        ← 保留 6 个 so

⚠️ 重要：jar 和 so 文件必须保留！uni-app 打包 APK 时会自动把它们合并进去。aar 只包含你自己写的 Java 封装类。

2. 修改 package.json

把 integrateType 改为 aar（如果还没改的话）：

{
    "name": "Html5app-UHFReader",
    "id": "Html5app-UHFReader",
    "version": "1.0.0",
    "description": "UHF RFID 超高频读写器插件",
    "_dp_type": "nativeplugin",
    "_dp_nativeplugin": {
        "android": {
            "plugins": [{
                "type": "module",
                "name": "Html5app-UHFReader",
                "class": "com.html5app.uni_uhfreader.UHFReaderModule"
            }],
            "integrateType": "aar",
            "minSdkVersion": "19",
            "permissions": [
                "<uses-permission android:name=\"android.permission.CAMERA\" />"
            ]
        }
    }
}

七、在 HBuilderX 中打包测试

1. 制作自定义基座（推荐）

1. 打开 HBuilderX
2. 点击 运行 → 运行到手机或模拟器 → 制作自定义基座
3. 选择 Android(App)
4. 等待打包完成

2. 基座运行

1. 打包完成后，点击 运行 → 运行到手机或模拟器 → 运行基座选择 → 自定义基座
2. 连接你的 PDA 设备（或模拟器）
3. 点击运行，测试 UHF 扫描页面

八、常见问题排查

Q1: 编译报错 "Cannot find symbol: io.dcloud.feature.uniapp..."

原因：没有放 uniapp-v8-release.aar 解决：把 uni-app 离线 SDK 中的 aar 复制到 uhfreader/libs/ 目录

Q2: 编译报错 "Duplicate class found"

原因：jar 包和 aar 中有重复的类 解决：检查 dependencies 里是否同时用了 implementation 和 compileOnly，统一改为 compileOnly

Q3: 运行时提示 "未找到插件 Html5app-UHFReader"

原因：manifest.json 未注册，或打包时未选中本地插件 解决：

1. 确认 manifest.json 的 nativePlugins 中有 Html5app-UHFReader
2. HBuilderX 打包时选择 "使用本地插件"

Q4: 运行时崩溃 UnsatisfiedLinkError

原因：so 库架构不匹配 解决：确认 PDA 设备的 CPU 架构（通常是 arm64-v8a），对应的 so 文件必须存在

Q5: 初始化成功但读不到标签

原因：功率或区域未设置正确 解决：在页面上先点击 "获取区域" 和 "获取功率"，确认设备参数正确，再开始扫描

九、快速检查清单

• [ ] Android Studio 安装完成
• [ ] 下载了 uni-app Android 离线 SDK
• [ ] 把 uniapp-v8-release.aar 放到 module 的 libs/ 目录
• [ ] 把 6 个 jar 包放到 module 的 libs/ 目录
• [ ] 把 so 库放到 src/main/jniLibs/ 对应架构目录
• [ ] UHFReaderModule.java 已复制到正确包路径
• [ ] build.gradle 配置正确（compileOnly）
• [ ] 编译成功，生成了 uhfreader-release.aar
• [ ] aar 已放到 uni-app 插件目录
• [ ] jar 和 so 仍保留在 uni-app 插件目录
• [ ] manifest.json 已注册插件
• [ ] HBuilderX 使用自定义基座打包运行