更新记录

3.1.0（2026-06-12） 下载此版本

变更

• 分帧策略：删除 Modbus 功能码推断切帧（extractModbusFrames），改为时间间隔分帧（20ms 帧间超时），HEX/ASCII 通用
• 心跳探针：从 available() 改为 read() 探针，新增 setSoTimeout(50) 防阻塞，区分 FIN/Timeout/异常三种断线
• 缓冲区保护：新增 256 字节单帧上限，超出立即输出防止内存无限增长

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

新增

• sendHex(hexStr: string): boolean
• sendAscii(asciiStr: string): boolean

移除

• connect(host, port, options?): Promise<Result> ❌ → setHost() + open()
• disconnect(reason?): Result ❌ → close()
• send(hexStr): Promise<Result> ❌ → sendHex() / sendAscii()
• on(event, cb) / off(event, cb) ❌ → onStartAutoReadData(cb)
• setFrameMode(mode) ❌
• startHeartbeat(options?) ❌
• stopHeartbeat() ❌
• enableAutoReconnect(options?) ❌
• disableAutoReconnect() ❌
• isConnected(): boolean ❌ → 读 isOpen 属性
• destroy() ❌
• tcpInstance 全局单例 ❌ → new TCP485()

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

⚠️ BREAKING CHANGE：与 1.0.0 不兼容。请按本文"迁移指南"调整业务代码。

新增

• connect / send 改为 Promise 化，统一返回 {ok, errCode, errMsg}
• 事件订阅模型：on(event, cb) / off(event, cb)
  • connect {remoteAddress, remotePort}
  • disconnect {reason: 'USER' | 'REMOTE_CLOSED' | 'IO_ERROR'}
  • frame {hex, bytes, type: 'modbus' | 'unknown'}（默认 modbus 模式）
  • rawData {hex, bytes, available}（raw 模式）
  • reconnecting {attempt, delayMs}
  • reconnected {remoteAddress, remotePort}
  • reconnectFailed {attempt, errCode, errMsg}
  • error {errCode, errMsg}
• 错误码归一（不再 catch 吞异常）：
  • CONNECT_TIMEOUT CONNECT_REFUSED NETWORK_UNREACHABLE
  • REMOTE_CLOSED IO_ERROR INVALID_HEX
  • NOT_CONNECTED ALREADY_CONNECTING JAVA_CLASS_MISSING
• Modbus 自动切帧 内置（参考 tcp485.js）
• 30s 心跳 startHeartbeat({intervalMs}) / stopHeartbeat()
• 自动重连（指数退避） enableAutoReconnect({delayMs, maxDelayMs, maxRetries})
• 切帧模式开关 setFrameMode('modbus' | 'raw' | 'off')
• destroy() 一键释放（应用退出时调用）

变更

• 单次 read() 上限 256 字节，超出时分批
• 内部 setInterval 周期统一为 10ms
• 非 Android 端给出完整的 noop 实现（API 表面与 Android 一致）

移除

• connect(host, port, timeoutMs): boolean ❌
• send(hexStr): boolean ❌
• readAvailable(): string ❌
• 业务层需自行维护的 setInterval、Modbus 切帧、心跳、重连 ❌

迁移指南

1.0.0 写法：

const ok = tcpInstance.connect('192.168.1.200', 8899, 5000)
if (ok) {
  setInterval(() => {
    const chunk = tcpInstance.readAvailable()
    // ... 业务层切帧
  }, 30)
}

2.0.0 写法：

const r = await tcpInstance.connect('192.168.1.200', 8899, { timeoutMs: 5000 })
if (r.ok) {
  tcpInstance.on('frame', (e) => {
    console.log('收到帧:', e.hex, '类型:', e.type)
  })
  // 心跳/重连/切帧 全部由插件托管
}

平台兼容性

uni-app(4.31)

其他

android-tcpsocket

UTS 原生插件，在 Android 端为 uni-app 提供 TCP Socket 通信。 内置 时间间隔分帧（20ms）+ 10ms 主动轮询 + 30s read()心跳探针 + 覆盖 FIN/RST/硬断线，HEX/ASCII 通用，4800~115200bps 全线适配。 面向 RS485 转网口、Modbus TCP、LAN869、纯 TCP 透传设备 等场景。

⚠️ 插件层不做自动重连，检测到断线后通过 onDisconnect 回调通知应用层，由应用层自行决定重连策略。

1. 平台兼容性

2. 安装

插件位于项目内 uni_modules/android-tcpsocket/，HBuilderX 打开项目即可使用。

3. 引入与实例化

import { TCP485 } from '@/uni_modules/android-tcpsocket/utssdk/app-android/index.uts'

// 每个页面 new 自己的实例（类状态，支持多连接）
const tcp = new TCP485()

⚠️ 不是单例。TCP485 是普通类，使用时自行 new 创建实例。

4. API 文档

4.1 属性

4.2 setHost(host, port)

设置目标地址（需在 open() 前调用）。

tcp.setHost('192.168.1.200', 8899)

4.3 open(): Promise<boolean>

建立 TCP 连接。内部自动启动轮询接收 + 心跳探针。

try {
  await tcp.open()
  console.log('已连接')
} catch (e) {
  console.error('连接失败：', e.message)
}

4.4 close()

主动关闭连接，停止所有定时器（心跳、轮询），释放 socket 资源。

tcp.close()

4.5 sendHex(hexStr): boolean

发送 HEX 字符串。同步返回 true/false。

const ok = tcp.sendHex('01030000000AC5CD')   // true → 发送成功

4.6 sendAscii(asciiStr): boolean

发送 ASCII 字符串（逐字符取 charCode 写入字节流）。同步返回 true/false。

const ok = tcp.sendAscii('Hello World')

4.7 sendDataString(data, mode?): boolean

兼容接口，默认按 HEX 发送。mode 可选 'hex' 或 'ascii'。

tcp.sendDataString('01030000')       // HEX 模式
tcp.sendDataString('Hello', 'ascii') // ASCII 模式

4.8 onStartAutoReadData(callback: (hexStr: string) => void)

注册数据接收回调。收到完整帧时回调 hex 字符串（如 "01030A00010002..."）。

tcp.onStartAutoReadData((hexStr) => {
  console.log('收到:', hexStr, '长度:', hexStr.length / 2, 'B')
})

4.9 stopReadPortData()

注销接收回调（停止向业务层推送数据，底层轮询继续运行）。

tcp.stopReadPortData()

4.10 onDisconnect(callback)

注册断线回调。插件层的三种断线检测（write 异常 / read 异常或 -1 / 心跳 IO 探针）触发后，会调用此回调通知应用层。

⚠️ 插件不做自动重连。应用层在回调中自行决定重连策略（延迟、退避、最大次数、UI 提示等）。

tcp.onDisconnect(() => {
  console.log('TCP 已断开，3s 后重连...')
  setTimeout(() => {
    tcp.open().then(() => console.log('重连成功')).catch(() => {})
  }, 3000)
})

4.11 byte2HexString(bytes: Array<number>): string

工具方法，字节数组转 hex 字符串（供外部使用）。

5. 内部机制

6. 典型用法

import { TCP485 } from '@/uni_modules/android-tcpsocket/utssdk/app-android/index.uts'

export default {
  data() {
    return { tcp: null, reconnectTimer: null }
  },
  onLoad() {
    this.tcp = new TCP485()

    // 注册接收回调
    this.tcp.onStartAutoReadData((hexStr) => {
      console.log('[RX]', hexStr)
    })

    // ★ 注册断线回调：应用层控制重连策略
    this.tcp.onDisconnect(() => {
      console.log('TCP 断开，3s 后重连...')
      if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
      this.reconnectTimer = setTimeout(() => {
        this.tcp.open().catch((e) => console.error('重连失败', e.message))
      }, 3000)
    })

    // 连接
    this.tcp.setHost('192.168.31.24', 7001)
    this.tcp.open().then(() => {
      console.log('连接成功')

      // 发送 HEX
      this.tcp.sendHex('01030000000AC5CD')

      // 发送 ASCII
      this.tcp.sendAscii('Hello')
    }).catch((e) => {
      console.error('连接失败:', e.message)
    })
  },
  onUnload() {
    if (this.reconnectTimer) clearTimeout(this.reconnectTimer)
    if (this.tcp) this.tcp.close()
  }
}

7. 注意事项

1. 多连接：每个 new TCP485() 是独立实例，可同时连多个目标
2. 后台节流：uni-app 切后台后 JS 定时器会被系统节流，建议在 onHide() 调 close()，onShow() 重新 open()
3. 分帧策略：HEX/ASCII 通用，基于 20ms 帧间空闲超时切帧，无协议依赖
4. HEX 格式：sendHex() 要求偶数长度的合法 hex 字符（0-9a-fA-F）
5. 连接超时：硬编码 5000ms，如需调整请 fork 插件修改 _openSocket
6. 重连策略：插件不做自动重连，在 onDisconnect 中实现（延时、退避、最大次数等均由应用层控制）

8. 版本历史