更新记录

1.2.0（2026-08-25）

新增经典 uni-app（Vue3）框架支持；修复买家侧 readMap 入参编译报错。

• 修复（重要）：在自己的工程里调 client.readMap([{ name, address, type }, …]) 编译报 参数类型不匹配：实际类型为 'UTSArray<UTSJSONObject>'，预期类型为 'UTSArray<RegField>'（error17）。 原因是插件的类型声明 interface.uts 之前从同目录另一个文件 import 值类型，而市场下发的付费插件里 只有 interface.uts 保持明文、其余文件是加密的，于是买家侧拿不到 RegField 的结构、数组字面量无法 匹配。本版把值类型内联进 interface.uts，买家工程直接写数组字面量即可编过，无需任何改写。
• 新增：经典 uni-app（Vue3）支持。经典工程页面跑在 WebView，UTS 返回的带方法对象过原生桥会被 序列化、方法全丢，故经典端提供「句柄 + 自由函数」API（与 uni-app x 的对象 API 同一条原生实现）： modbusConnectTcp / modbusConnectRtuOverTcp 返回连接句柄， modbusReadHoldingRegisters / modbusReadInputRegisters / modbusReadCoils / modbusReadDiscreteInputs / modbusWriteSingleRegister / modbusWriteMultipleRegisters / modbusWriteSingleCoil / modbusWriteMultipleCoils / modbusSetSlave / modbusReadHoldingRegistersMulti / modbusReadMap / modbusReadMapJson / modbusIsConnected / modbusDisconnect 共 16 个。 uni-app x 端原有对象 API 完全不变，老代码零改动。
• 新增 ModbusClient.readMapJson(fieldsJson)：与 readMap 等价但纯字符串进出， 不依赖任何自定义类型，任何框架/编译模式下都不会有类型推断问题（逃生阀）。
• 改进：iOS 桥接按 Swift 具名参数 / UTSiOS.try / GCD 规范重写，补上此前缺失的 Dispatch 导入。

1.1.1（2026-08-13）

重新发布 1.1.0 修复内容（走 HBuilderX 正规发版管道，确保市场导入通道分发到修复包）。

• 修复：Android 云打包 / 制作自定义基座编译失败（1.0.0 的兼容性问题）。
• 若您项目里 uni_modules/nex-modbus/package.json 的 version 仍显示 1.0.0：请先删除项目里整个 uni_modules/nex-modbus 目录，再从插件市场重新点「使用 HBuilderX 导入插件」。

1.0.0（2026-07-19）

新增 RTU-over-TCP 传输 + 多从站巡检 + 断开语义更名。

• RTU-over-TCP 传输：connectModbusRtuOverTcp({ host, port?, unitId?, timeoutMs? }) —— 以 Modbus RTU 帧（含 CRC16 校验）经 TCP 传输建立连接，面向串口服务器 / 协议网关（区别于 Modbus TCP 的 MBAP 帧）。CRC16 自动编解码，坏帧 / 半包按异常返回、不崩宿主；返回与 Modbus TCP 相同的 ModbusClient 对象，建连后所有读写方法一致工作。
• 多从站切换：ModbusClient.setSlave(unitId) —— 不重连即切换后续请求的目标从站，支撑一条连接轮询多个从站。
• 多从站批量读：ModbusClient.readHoldingRegistersMulti(unitIds[], address, quantity) —— 一次调用对多个从站读同一寄存器区块，逐从站返回结果（{ unitId, ok, values, error }）；单个从站超时 / 异常不拖垮整批，失败项带错误标记、其余正常返回（SCADA 定时巡检刚需）。
• 断开语义更名：`ModbusClient.cl

平台兼容性

uni-app(5.14)

uni-app x(5.14)

nex-modbus

自研高性能 Modbus 工业协议主站核心（Modbus TCP + RTU-over-TCP 两种传输），提供 uni-app 可调的异步 JS API。面向工厂安卓平板控制屏：连 PLC / 传感器 / 串口服务器，读写寄存器 / 线圈，多从站巡检，并按寄存器表做字序 / 类型解码 → 干净 JSON。

支持 uni-app x 与经典 uni-app（Vue3）双框架：uni-app x 用对象 API（ModbusClient）， 经典 uni-app 用「句柄 + 自由函数」API（见下方「经典 uni-app 用法」）——同一条原生实现，能力完全一致。

仅 App 端（Android / iOS）：依赖原生库，H5 / 小程序加载不了（浏览器无原生 TCP，无法直连设备）。Android 需 android.permission.INTERNET。 连接是有状态对象 ModbusClient（TCP 与 RTU-over-TCP 共用同一对象）；全部读写 API 均为异步 Promise，后台执行、不卡 UI。

API

• connectModbusTcp({ host, port?, unitId?, timeoutMs? }): Promise<ModbusClient> —— 建 Modbus TCP 连接（默认 port 502 / unitId 1 / timeout 3000ms）
• connectModbusRtuOverTcp({ host, port?, unitId?, timeoutMs? }): Promise<ModbusClient> —— 建 RTU-over-TCP 连接（RTU 帧含 CRC16 经 TCP，面向串口服务器 / 协议网关；入参同上）
• ModbusClient：
  • 读：readHoldingRegisters(addr, qty) / readInputRegisters → number[]；readCoils / readDiscreteInputs → boolean[]
  • 写：writeSingleRegister(addr, value) / writeMultipleRegisters(addr, values[]) / writeSingleCoil(addr, on) / writeMultipleCoils(addr, on[])
  • 多从站：setSlave(unitId)（切从站不重连）/ readHoldingRegistersMulti(unitIds[], addr, qty)（一次巡检多从站，单从站异常不拖垮整批）
  • 转换：readMap(fields) → 按寄存器表解码的 JSON 对象；readMapJson(fieldsJson) → 同上但纯字符串进出（不依赖任何自定义类型的逃生阀）
  • 生命周期：isConnected() / disconnect()
• 经典 uni-app（Vue3）：同能力的句柄自由函数 modbusConnectTcp / modbusConnectRtuOverTcp / modbusReadHoldingRegisters / modbusReadInputRegisters / modbusReadCoils / modbusReadDiscreteInputs / modbusWriteSingleRegister / modbusWriteMultipleRegisters / modbusWriteSingleCoil / modbusWriteMultipleCoils / modbusSetSlave / modbusReadHoldingRegistersMulti / modbusReadMap / modbusReadMapJson / modbusIsConnected / modbusDisconnect

寄存器表解码（readMap 护城河）

fields 每项 { name, address, type, wordOrder?, length?, scale?, offset?, source? }：

• type：int16/uint16/int32/uint32/int64/uint64/float32/float64/string
• wordOrder：ABCD(大端,默认) / CDAB(字交换) / BADC(字节交换) / DCBA(全反序)
• scale/offset：输出 raw*scale+offset（工程量纲）；source：holding(默认) / input

最小用例

import { connectModbusTcp } from '@/uni_modules/nex-modbus';

const client = await connectModbusTcp({ host: '192.168.1.10', port: 502, unitId: 1 });
const data = await client.readMap([
  { name: 'temp', address: 0, type: 'int16', scale: 0.1 },
  { name: 'power', address: 10, type: 'uint32', wordOrder: 'CDAB' },
]);
console.log(data); // { temp: 25.0, power: 123456 }
client.disconnect();

多从站巡检（一条连接轮询多个从站，单从站离线不影响其余）：

import { connectModbusRtuOverTcp } from '@/uni_modules/nex-modbus';

// RTU-over-TCP 网关，一条连接读 1/2/3 号从站的 0..2 保持寄存器
const gw = await connectModbusRtuOverTcp({ host: '192.168.1.20', port: 502 });
const results = await gw.readHoldingRegistersMulti([1, 2, 3], 0, 2);
results.forEach(r => {
  if (r.ok) console.log(`从站 ${r.unitId}:`, r.values);
  else console.warn(`从站 ${r.unitId} 失败:`, r.error);
});
gw.disconnect();

经典 uni-app（Vue3）用法

经典工程的页面跑在 WebView，UTS 返回的带方法对象过原生桥会被序列化、方法全丢（拿到的是空对象 {}）。 所以经典端不要用 connectModbusTcp() 返回的 ModbusClient 对象，改用「句柄 + 自由函数」—— 句柄是个 number，连接对象由插件在原生侧持有，跨调用存活：

import {
  modbusConnectTcp, modbusReadHoldingRegisters, modbusReadMapJson,
  modbusWriteSingleRegister, modbusIsConnected, modbusDisconnect,
} from '@/uni_modules/nex-modbus';

// 1) 建连接，拿句柄
const h = await modbusConnectTcp({ host: '192.168.1.10', port: 502, unitId: 1, timeoutMs: 3000 });

// 2) 读寄存器
const regs = await modbusReadHoldingRegisters(h, 0, 2);   // [25, 100]

// 3) 寄存器表解码（经典端首选 Json 变体：纯字符串进出，过 WebView 桥零风险）
const json = await modbusReadMapJson(h, JSON.stringify([
  { name: 'temp',  address: 0,  type: 'int16',  scale: 0.1 },
  { name: 'power', address: 10, type: 'uint32', wordOrder: 'CDAB' },
]));
console.log(JSON.parse(json));   // { temp: 25.0, power: 123456 }

// 4) 写 + 断开
await modbusWriteSingleRegister(h, 0, 1234);
console.log(modbusIsConnected(h));  // true
modbusDisconnect(h);                // 释放句柄（幂等）

想要对象式写法？在页面里自建一个薄包装类即可（方法定义在页面 JS、不过桥）：

class Modbus {
  constructor(handle) { this.h = handle; }
  static async connect(opts) { return new Modbus(await modbusConnectTcp(opts)); }
  readHolding(addr, qty) { return modbusReadHoldingRegisters(this.h, addr, qty); }
  readMap(fields) { return modbusReadMapJson(this.h, JSON.stringify(fields)).then(JSON.parse); }
  close() { modbusDisconnect(this.h); }
}

错误（reject 的 Error）

ConnectFailed / Timeout / ConnectionLost / SlaveException(从站异常码) / InvalidParam(越界) / Decode。

当前状态：协议核心已通过模拟从站集成测试全量验证；App 真机端到端验证持续完善中。