更新记录

1.0.4（2026-06-28）

优化

1.0.3（2026-06-28）

优化

1.0.2（2026-06-27）

优化

平台兼容性

uni-app(4.63)

uni-app x(4.35)

xtf-usbserialhelper

Android USB 转串口通信插件。

用于在 uni-app / uni-app x 项目中完成以下能力：

• 获取当前已连接的 USB 设备列表
• 监听 USB 设备插入、拔出
• 检查并申请指定设备的 USB 权限
• 打开 USB 设备并选择串口端口
• 配置波特率、数据位、停止位、校验位
• 发送十六进制字符串数据
• 监听串口返回的十六进制字符串数据
• 关闭连接并释放监听资源

平台支持

• Android App：支持
• iOS：不支持
• Harmony：不支持
• Web / 小程序：不支持

说明：当前实际功能实现仅在 app-android 下完成，app-ios、app-harmony 目录中的内容不是可用实现。

使用前提

1. 这是 UTS 原生插件，真机测试时请使用自定义基座。
2. Android 设备需要支持 USB Host。
3. 需要插入实际 USB 串口设备后再测试。
4. 插件通过 deviceName 标识设备，后续权限申请、打开设备等操作都要传入 deviceName。

约束与限制

平台限制

• 仅支持 Android。
• 标准基座下原生配置和三方 SDK 不生效，必须使用自定义基座运行。

数据与调用限制

• writeData 发送的数据必须是十六进制字符串，例如 55 AA 01 02 或 55AA0102。
• onAutoReadDataTask 回调返回的数据也是十六进制字符串。
• openDevice() 只是打开 USB 设备连接，不代表串口已经打开。
• 只有执行 selectUsbInterface(index) 成功后，isOpen() 才会返回 true。
• getInterfaceCount() 只有在 openDevice() 成功后才有意义。
• stopAutoReadTask() 只停止读任务，不会关闭设备连接。
• 页面销毁时建议调用 destroy()，避免 USB 广播监听残留。

推荐调用顺序

1. getAllUsbDevice()
2. 选中目标设备的 deviceName
3. haveusbper(deviceName)
4. 如未授权，调用 reqUsbPer(deviceName, callback)
5. setSerialData(...)
6. openDevice(deviceName)
7. getInterfaceCount()
8. selectUsbInterface(0) 或其他端口索引
9. writeData(...) / onAutoReadDataTask(...)
10. stopAutoReadTask() / close()
11. 页面销毁时 destroy()

引入方式

import { UsbSerialHelper } from "@/uni_modules/xtf-usbserialhelper"

const usbHelper = new UsbSerialHelper()

数据结构

DeviceData

type DeviceData = {
  productName?: string
  productId?: number
  vendorId?: number
  deviceName?: string
}

字段说明：

• deviceName：设备唯一标识，后续权限、打开设备等接口都依赖它
• productName：设备产品名，部分设备可能为空
• productId：产品 ID
• vendorId：厂商 ID

接口说明

onListenerUsbListner

监听 USB 插入、拔出事件。

usbHelper.onListenerUsbListner(function(state, device) {
  // state 为 true 表示插入，false 表示拔出
  // device 为设备信息
})

说明：

• 注册后插件会开始监听 Android USB 插拔广播
• 如页面不再使用，请在销毁时调用 destroy() 释放监听

getAllUsbDevice

获取当前已连接的 USB 设备列表。

const devices = usbHelper.getAllUsbDevice()

返回值：DeviceData[]

说明：

• 插件内部也会在调用时刷新设备缓存
• 如果当前没有设备，返回空数组

haveusbper

检查指定设备当前是否已有 USB 权限。

const hasPermission = usbHelper.haveusbper(deviceName)

参数：

• deviceName: string，来自 DeviceData.deviceName

返回值：boolean

reqUsbPer

申请指定设备的 USB 权限。

usbHelper.reqUsbPer(deviceName, function(granted) {
  // granted 为 true 表示授权成功
})

参数：

• deviceName: string
• callback: (granted: boolean) => void

说明：

• 如果设备不存在，回调直接返回 false
• 如果当前页面没有可用 Activity，回调直接返回 false

setSerialData

设置串口参数。

usbHelper.setSerialData(9600, 8, 1, 0)

参数：

• baudRate: number，波特率
• dataBits: number，数据位，常用 5、6、7、8
• stopBits: number，停止位，常用 1、2
• parity: number，校验位

parity 取值：

• 0：无校验
• 1：奇校验
• 2：偶校验
• 3：MARK
• 4：SPACE

openDevice

打开 USB 设备连接。

const opened = usbHelper.openDevice(deviceName)

参数：

• deviceName: string

返回值：boolean

说明：

• 成功表示 USB 设备连接已打开，且找到了可用端口
• 此时串口还未真正打开，仍需继续执行 selectUsbInterface(index)

getInterfaceCount

获取当前设备可用串口端口数量。

const count = usbHelper.getInterfaceCount()

返回值：number

说明：

• 如果设备未打开，返回 0

selectUsbInterface

选择并打开指定串口端口，同时应用当前串口参数。

const ok = usbHelper.selectUsbInterface(0)

参数：

• select: number，端口索引，从 0 开始

返回值：boolean

说明：

• 成功后串口才真正处于打开状态

isOpen

判断串口当前是否已打开。

const opened = usbHelper.isOpen()

返回值：boolean

getSerial

获取当前串口序列号。

const serial = usbHelper.getSerial()

返回值：string

说明：

• 未打开串口时返回空字符串

writeData

向串口发送十六进制字符串数据。

usbHelper.writeData("55 AA 01 02", 5000, function(success) {
  // success 为 true 表示发送成功
})

参数：

• data: string，十六进制字符串
• timeout: number，写入超时时间，单位毫秒
• callback: (success: boolean) => void

说明：

• 如果串口尚未打开，回调直接返回 false

onAutoReadDataTask

启动串口读监听。

usbHelper.onAutoReadDataTask(function(state, data) {
  // state 为 true 时，data 为收到的十六进制字符串
  // state 为 false 时，表示读取异常
})

参数：

• callback: (state: boolean, data: string) => void

说明：

• 如果串口尚未打开，回调立即返回 false 和空字符串
• 同一个 UsbSerialHelper 实例重复调用时，未先停止的情况下不会重复创建读任务

stopAutoReadTask

停止串口读监听。

usbHelper.stopAutoReadTask()

说明：

• 只停止读任务，不关闭设备连接

close

关闭当前串口和 USB 连接。

usbHelper.close()

说明：

• 会停止读任务
• 会关闭串口与 USB 连接
• 不会移除插拔广播监听

destroy

销毁插件实例正在持有的资源。

usbHelper.destroy()

说明：

• 会先执行 close()
• 会移除已注册的 USB 广播监听
• 建议在页面 onUnload / 组件销毁时调用

uni-app 与 uni-app x 的写法说明

大部分调用方式完全相同，只是 uni-app x 可以补充更严格的类型声明。

相同写法

以下调用在 uni-app 和 uni-app x 中都可以直接使用：

import { UsbSerialHelper } from "@/uni_modules/xtf-usbserialhelper"

const usbHelper = new UsbSerialHelper()
const devices = usbHelper.getAllUsbDevice()

usbHelper.reqUsbPer(deviceName, function(granted) {
  console.log(granted)
})

usbHelper.writeData("55 AA 01 02", 5000, function(success) {
  console.log(success)
})

uni-app x 推荐写法

如果你在 uni-app x 中希望获得更完整的类型提示，可以给回调参数补上类型：

import { UsbSerialHelper, DeviceData } from "@/uni_modules/xtf-usbserialhelper"

const usbHelper = new UsbSerialHelper()

usbHelper.onListenerUsbListner(function(state: boolean, device: DeviceData) {
  console.log(state, device.deviceName)
})

usbHelper.onAutoReadDataTask(function(state: boolean, data: string) {
  console.log(state, data)
})

最小示例流程

import { UsbSerialHelper } from "@/uni_modules/xtf-usbserialhelper"

const usbHelper = new UsbSerialHelper()

const devices = usbHelper.getAllUsbDevice()
const deviceName = devices.length > 0 ? devices[0].deviceName : ""

if (deviceName) {
  if (usbHelper.haveusbper(deviceName)) {
    usbHelper.setSerialData(9600, 8, 1, 0)
    const opened = usbHelper.openDevice(deviceName)
    if (opened) {
      const ok = usbHelper.selectUsbInterface(0)
      if (ok) {
        usbHelper.writeData("55 AA 01 02", 5000, function(success) {
          console.log(success)
        })
      }
    }
  } else {
    usbHelper.reqUsbPer(deviceName, function(granted) {
      console.log(granted)
    })
  }
}

页面销毁时释放资源

usbHelper.destroy()

相关文档

• UTS 语法
• UTS 插件
• uni-app x UTS 标准模式组件