更新记录

1.0.5（2026-08-04）

• 修复 HarmonyOS 平台文件缺少公开 API 同名导出，导致 uni-app x 调用 getCapabilities / listPorts / getRuntimeState 等接口时报 undefined is not callable 的问题。
• 保留原有 *ByHarmony 平台分发入口，并补齐 interface.uts 声明的公开串口 API 代理，不影响 Android、iOS、Web 和既有 uni-app 调用入口。
• HarmonyOS 未接入串口适配器时继续返回明确的不支持能力、空端口列表和结构化运行态，不伪造串口通讯成功。
• Harmony 原生 UTS 已变化，升级后需要重新构建并安装匹配的 Harmony HAP 或自定义基座。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-serial-port

lizhao-serial-port 是纯 UTS 串口通信 API 插件，提供路径串口与 USB 串口双通道、多会话管理、读写超时、自动重连、事件上报与运行态观测能力。

支持平台

安装与导入

import * as SerialPort from '@/uni_modules/lizhao-serial-port'

目录结构

uni_modules/
└─ lizhao-serial-port/
   ├─ package.json
   ├─ readme.md
   ├─ changelog.md
   └─ utssdk/
      ├─ interface.uts
      ├─ unierror.uts
      ├─ index.uts
      ├─ app-android/
      ├─ app-ios/
      ├─ app-harmony/
      ├─ web/
      ├─ mp-weixin/
      └─ mp-alipay/

API 列表

• getCapabilities
• listPorts
• openPath
• openUsb
• closeSession
• closeAllSessions
• writeBytes
• writeHex
• writeText
• readOnce
• startRead
• stopRead
• flush
• sendAndWait
• getSessionState
• getRuntimeState
• on / off

兼容 API：

• openSerial
• writeData
• readData
• closeSerial
• byteArrToHexStr
• hexStrToByteArr

核心参数（openPath / openUsb）

返回值（会话状态）

错误码

权限与配置

自定义基座说明

• Android 默认系统 API 可用时无需额外三方库。
• 若项目引入特定芯片厂商串口 SDK，请使用自定义基座并同步更新插件平台配置。

uni-app 示例

import * as SerialPort from '@/uni_modules/lizhao-serial-port'

SerialPort.openPath({
  path: '/dev/ttyS3',
  sessionId: 'main-uart',
  lineConfig: {
    baudRate: 115200
  },
  success(res) {
    console.log('openPath success', res)
    SerialPort.startRead({
      sessionId: 'main-uart'
    })
  },
  fail(err) {
    console.log('openPath fail', err)
  }
})

SerialPort.on('data', (event) => {
  console.log('data event', event.payload.hex)
})

uni-app x 示例

import * as SerialPort from '@/uni_modules/lizhao-serial-port'

SerialPort.openUsb({
  vendorId: 6790,
  productId: 29987,
  sessionId: 'usb-device-1',
  success() {
    SerialPort.sendAndWait({
      sessionId: 'usb-device-1',
      hex: 'AA550001',
      matchHex: 'AA55',
      timeoutMs: 1500,
      success(res) {
        console.log('response', res.hex)
      }
    })
  }
})

注意事项

1. 路径串口需确保系统已授权访问对应设备节点。
2. USB 串口需设备已连接且权限可用；权限不足将返回 9015005。
3. 建议统一使用 sessionId 管理会话，避免并发串口互相污染。
4. 兼容 API 用于迁移旧代码，新业务建议使用规范 API。

联系方式

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。