更新记录

1.0.0（2025-12-20）

一、首次提交

平台兼容性

uni-app(4.62)

hl-iuhfq-uts 插件说明

hl-iuhfq-uts 是基于 iData Q3000 配件 iUHFQ SDK 封装的 UHF RFID 读写器 UTS 插件，Android 端通过 UHFJNI 完成设备初始化、功率/Session/盘点模式设置、标签盘点与按键控制，并通过 UTS 回调向前端页面推送盘点结果（EPC/TID）与盘点速率。

一、安装与环境

• 支持：uni-app / uni-app x
• Android 端依赖：iUHFQ SDK（iuhfqapi_Vxxx.aar 已集成进原生工程）

二、接口概览（interface.uts）

获取客户端实例：

import { getUhfClient } from '@/uni_modules/hl-iuhfq-uts'
const uhf = getUhfClient()

主要类型：

• HlIuhfqUtsResult：所有接口的统一返回结果，字段包含：

  • code: number，0 表示成功，非 0 表示失败
  • message?: string，结果说明
  • deviceModel?: 设备型号
  • power?: 当前天线功率
  • session?: 当前 Session（0–2）
  • mode?: 当前盘点模式（0 远距离 / 1 多标签）
  • scanTime? / waitTime?: 盘点间歇参数
  • 盘点统计：totalTags?、uniqueTags?、lastRate?
  • 标签回调：type?、epc?、tid?、tagData?、isNew?、count?、currentRate?
  • 标签列表：tags?: Array<HlIuhfqUtsTagInfo>
  • 触发模式：lock?

• HlIuhfqUtsTagInfo：标签列表项

  • epc, tid, count, firstSeenTime, lastSeenTime

• 其他参数类型：

  • HlIuhfqUtsInitOptions：初始化参数（mode?: 0|1 待机模式）
  • HlIuhfqUtsPowerOptions：功率设置（power: 0–33）
  • HlIuhfqUtsSessionOptions：Session 设置（session: 0–2）
  • HlIuhfqUtsInventoryModeOptions：盘点模式（mode: 0/1）
  • HlIuhfqUtsInventoryIntervalOptions：盘点间歇（scanTime / waitTime）
  • HlIuhfqUtsTriggerModeOptions：按键锁定（lock: boolean）
  • HlIuhfqUtsPerfModeOptions：待机性能模式（mode: 0/1）
  • HlIuhfqUtsAdvancedInvOptions：高级盘点参数（readMode / filterBank / filterAddress / filterLength / filterData / isFilter 等）

主要方法（IHlIuhfqUtsClient）：

• 回调注册：

  • onTagCallback(callback: HlIuhfqUtsCallback): void
    页面 onLoad 时调用一次，用于接收盘点过程中的标签/速率回调：
  • type: 'tagReport'：标签上报（含 EPC/TID/count 等）
  • type: 'inventoryRate'：盘点速率上报

• 设备与基本配置：

  • initDevice(options: HlIuhfqUtsInitOptions, cb)：初始化设备（内部调用 UHFJNI.initUhf、startListening、setExternalListener）
  • setPerformanceMode(options: HlIuhfqUtsPerfModeOptions, cb)：设置待机模式（0 常规 / 1 低功耗）
  • setPower(options: HlIuhfqUtsPowerOptions, cb) / getPower(cb)
  • setSession(options: HlIuhfqUtsSessionOptions, cb)（范围 0–2）
  • setInventoryMode(options: HlIuhfqUtsInventoryModeOptions, cb)
  • setInventoryInterval(options: HlIuhfqUtsInventoryIntervalOptions, cb)
  • switchTriggerMode(options: HlIuhfqUtsTriggerModeOptions, cb)：锁定 / 解锁扫描键
  • disconnect(cb)：停止盘点、断开设备连接并清理状态

• 盘点相关：

  • startInventory(callback)：默认盘点（EPC+TID，高级参数使用内部默认配置）
  • startInventoryTag(callback)：简单盘点，只盘 EPC，对应 SDK 的 startInventoryTag()
  • startInventoryEx(options: HlIuhfqUtsAdvancedInvOptions, callback)：高级盘点，可配置 readMode / invMode / 过滤参数等，对应 SDK 的 startInventory(...)
  • stopInventory(callback)：停止盘点，返回本轮盘点统计（totalTags / uniqueTags / lastRate）
  • getTagList(callback)：获取当前已统计的标签列表（tags: HlIuhfqUtsTagInfo[]）
  • clearTagList(callback)：清空标签列表与统计信息

三、前端使用示例（pages/uhf/uhf-demo.vue）

1. 页面加载时注册全局标签回调

import { onLoad, onUnload } from '@dcloudio/uni-app'
import { getUhfClient } from '@/uni_modules/hl-iuhfq-uts'
const uhf = getUhfClient()

const tagList = ref([])      // { epc, tid?, count }
const uniqueTags = ref(0)
const currentRate = ref(0)

onLoad(() => {
  // 统一接收标签 & 速率回调
  uhf.onTagCallback((result) => {
    if (result.code !== 0) return
    if (result.type === 'tagReport') {
      const epc = result.epc
      const tid = result.tid || ''
      const count = result.count || 0
      const existing = tagList.value.find(i => i.epc === epc)
      if (existing) {
        existing.count = count
        if (!existing.tid && tid) existing.tid = tid
      } else {
        tagList.value.push({ epc, tid, count: count || 1 })
      }
      uniqueTags.value = result.uniqueTags || tagList.value.length || 0
      currentRate.value = result.currentRate || 0
    } else if (result.type === 'inventoryRate') {
      currentRate.value = result.rate || 0
    }
  })
})

onUnload(() => {
  // 页面卸载时安全断开
  uhf.disconnect(() => {})
})

2. 初始化设备

uhf.initDevice({ mode: 1 }, (res) => {
  if (res.code === 0) {
    // 初始化成功，可开始设置功率 / Session / 盘点模式等
  } else {
    // 处理错误
  }
})

3. 设置待机模式 / 功率 / Session / 模式 / 间歇

uhf.setPerformanceMode({ mode: 1 }, cb)     // 0 常规 / 1 低功耗
uhf.setPower({ power: 30 }, cb)            // 0–33
uhf.setSession({ session: 1 }, cb)         // 0–2
uhf.setInventoryMode({ mode: 1 }, cb)      // 0 远距离 / 1 多标签
uhf.setInventoryInterval({ scanTime: 100, waitTime: 50 }, cb)

4. 三种盘点方式

1）默认盘点（EPC+TID，高级参数使用默认值）

uhf.startInventory((res) => {
  if (res.code === 0) {
    // 仅表示“开始盘点成功”，后续标签/速率由 onTagCallback 推送
  }
})

2）简单盘点（只盘 EPC，对应 SDK startInventoryTag()）

uhf.startInventoryTag((res) => {
  if (res.code === 0) {
    // 简单盘点开始，标签回调同样走 onTagCallback
  }
})

3）高级盘点（可配置过滤等）

uhf.startInventoryEx(
  {
    readMode: 1,           // 0:EPC, 1:EPC+TID, 2:EPC+TID+USER
    invMode: 0,            // 0:远距离, 1:多标签
    enableFastId: true,
    enableTagFocus: false,
    isFilter: true,
    filterBank: 0,         // 0:EPC,1:TID,2:USER
    filterAddress: 32,     // 起始 bit
    filterLength: 16,      // 长度 bit
    filterData: '3000'     // 过滤数据（十六进制）
  },
  (res) => {
    // res.code === 0 表示“高级盘点已开始”
  }
)

停止盘点与统计：

uhf.stopInventory((res) => {
  if (res.code === 0) {
    // res.totalTags / res.uniqueTags / res.lastRate
  }
})

获取标签列表：

uhf.getTagList((res) => {
  if (res.code === 0 && res.tags) {
    // res.tags 是 HlIuhfqUtsTagInfo[]
  }
})

清空标签列表：

uhf.clearTagList(() => {})

四、注意事项

1. 调用顺序：必须先 initDevice 成功，再进行功率/Session/盘点等操作。
2. 回调保持活跃：
   • 页面 onLoad 必须调用 onTagCallback 注册全局回调，否则只能收到“开始盘点”的一次性回调，收不到后续 EPC/TID。
3. 多次盘点：
   • 可以多次 startInventory / stopInventory，回调由 onTagCallback 统一接收；stopInventory 不会清空回调，仅重置扫描状态。
4. Session 范围：
   • 按 iUHFQ 文档，仅支持 Session 0–2，对应 S0–S2。
5. 过滤参数：
   • 高级过滤功能仅在 startInventoryEx 中生效，多标签模式下按文档说明对 USER/过滤能力有限制，使用前建议在实机上验证。
6. 断开连接：
   • 建议在页面 onUnload 中调用 disconnect，确保读线程与 JNI 连接及时释放。