更新记录

1.0.1（2025-09-09）

第一版发布，请充分试用后再购买

平台兼容性

UTS TCP多客户端通信插件

免责声明

• 源码无后门代码。
• 由第三方SDK而导致的任何损失,与作者无关。
• 使用本插件而导致的任何损失,与作者无关。
• 使用该插件即代表同意免责声明。

是否使用第三方SDK?

• 无

我有需求怎么办?

企鹅邮箱: sunic4@qq.com 感谢支持

简介

UTS TCP多客户端通信插件是一个基于uni-app x框架的TCP通信解决方案，支持多客户端连接管理，，支持Android和iOS平台。

测试TCP服务器

导入示例项目，示例项目下有一个tcp_server.py文件，该文件为测试用的TCP服务器，可直接运行。

python .\tcp_server.py

安装

1. 将插件放置于项目的uni_modules目录下
2. 在项目中引入插件：

import { createTCPClient, connectClient, sendMessage } from '@/uni_modules/ohyes-tcp'

API文档

类型定义

TCPResultType

TCP操作结果类型

export type TCPResultType = {
    code : number
    error ?: string
}

ConnectionOptionsType

连接配置选项

export type ConnectionOptionsType = {
    serverHost : string         // 服务器地址
    serverPort : number         // 服务器端口
    timeout ?: number           // 连接超时时间，单位毫秒，默认5000
    enableHeartbeat ?: boolean  // 是否启用心跳，默认false
    heartbeatInterval ?: number // 心跳间隔，单位毫秒，默认30000
    heartbeatMessage ?: string  // 心跳消息内容，默认"HEARTBEAT"
}

ConnectionStatusType

连接状态回调参数

export type ConnectionStatusType = {
    state : string
    error ?: string    // 错误信息
}

核心API

createTCPClient

创建TCP客户端实例

export const createTCPClient : CreateTCPClientType = () : string

返回值: 客户端ID（字符串）

示例:

const clientId = createTCPClient()
console.log('客户端ID:', clientId)

connectClient

通过客户端ID连接到服务器

export const connectClient : ConnectClientType = (clientId : string, options : ConnectionOptionsType) : void

参数:

• clientId: 客户端ID
• options: 连接选项

示例:

const options = {
    serverHost: '192.168.1.100',
    serverPort: 8080,
    timeout: 10000,
    enableHeartbeat: true,      // 启用心跳
    heartbeatInterval: 30000,   // 30秒心跳间隔
    heartbeatMessage: 'PING'    // 自定义心跳消息
}
connectClient(clientId, options)

disconnectClient

通过客户端ID断开连接

export const disconnectClient : DisconnectClientType = (clientId : string) : void

参数:

• clientId: 客户端ID

示例:

disconnectClient(clientId)

distoryClient

通过客户端ID销毁客户端

export const distoryClient : DistoryClientType = (clientId : string) : void

参数:

• clientId: 客户端ID

示例:

distoryClient(clientId)

sendMessage

通过客户端ID发送消息

export const sendMessage : SendMessageType = (clientId : string, message : string) : void

参数:

• clientId: 客户端ID
• message: 消息内容

示例:

sendMessage(clientId, 'Hello Server')

回调函数

onConnected

注册连接成功回调

export function onConnected(clientId : string, callback : ConnectedCallbackType) : void

参数:

• clientId: 客户端ID
• callback: 连接成功回调函数

示例:

onConnected(clientId, (clientId, res) => {
    console.log('连接成功:', clientId, res)
})

onDisconnected

注册断开连接回调

export function onDisconnected(clientId : string, callback : DisconnectedCallbackType) : void

参数:

• clientId: 客户端ID
• callback: 断开连接回调函数

示例:

onDisconnected(clientId, (clientId, res) => {
    console.log('连接断开:', clientId, res)
})

onMessage

注册消息接收回调

export function onMessage(clientId : string, callback : MessageCallbackType) : void

参数:

• clientId: 客户端ID
• callback: 消息接收回调函数

示例:

onMessage(clientId, (clientId, message) => {
    console.log('收到消息:', clientId, message)
})

onError

注册错误回调

export function onError(clientId : string, callback : ErrorCallbackType) : void

参数:

• clientId: 客户端ID
• callback: 错误回调函数

示例:

onError(clientId, (clientId, res) => {
    console.error('发生错误:', clientId, res)
})

客户端管理

getActiveClients

获取所有活跃的客户端实例

export const getActiveClients : GetActiveClientsType = () : string[]

返回值: 活跃客户端ID数组

示例:

const activeClients = getActiveClients()
console.log('活跃客户端:', activeClients)

getClientState

获取客户端连接状态

export const getClientState : GetClientStateType = (clientId : string) : string

参数:

• clientId: 客户端ID

返回值: 客户端连接状态（字符串）

示例:

const state = getClientState(clientId)
console.log('客户端状态:', state)

clientExists

检查客户端是否存在

export const clientExists : ClientExistsType = (clientId : string) : boolean

参数:

• clientId: 客户端ID

返回值: 客户端是否存在（布尔值）

示例:

const exists = clientExists(clientId)
console.log('客户端是否存在:', exists)

心跳管理

enableHeartbeat

启用心跳

export const enableHeartbeat : EnableHeartbeatType = (clientId : string, interval ?: number, message ?: string) : void

参数:

• clientId: 客户端ID
• interval: 心跳间隔，单位毫秒，默认30000
• message: 心跳消息内容，默认"HEARTBEAT"

示例:

// 使用默认配置启用心跳
enableHeartbeat(clientId)

// 自定义心跳配置
enableHeartbeat(clientId, 15000, 'PING')

disableHeartbeat

禁用心跳

export const disableHeartbeat : DisableHeartbeatType = (clientId : string) : void

参数:

• clientId: 客户端ID

示例:

disableHeartbeat(clientId)

演示页面

项目中包含了一个完整的TCP聊天演示页面 (pages/index/index.vue)，展示了插件的所有功能：

• 服务器连接配置
• 心跳功能设置和动态控制
• 消息收发界面
• 连接状态监控
• 错误处理展示

使用示例

基本使用流程

// 1. 创建客户端
const clientId = createTCPClient()

// 2. 设置回调函数
onConnected(clientId, (clientId, res) => {
    console.log('连接成功:', clientId, res)
})

onDisconnected(clientId, (clientId, res) => {
    console.log('连接断开:', clientId, res)
})

onMessage(clientId, (clientId, message) => {
    console.log('收到消息:', clientId, message)
})

onError(clientId, (clientId, res) => {
    console.error('发生错误:', clientId, res)
})

// 3. 连接服务器（带心跳配置）
const options = {
    serverHost: '192.168.1.100',
    serverPort: 8080,
    timeout: 10000,
    enableHeartbeat: true,      // 启用心跳
    heartbeatInterval: 30000,   // 30秒心跳间隔
    heartbeatMessage: 'HEARTBEAT'
}
connectClient(clientId, options)

// 4. 发送消息
sendMessage(clientId, 'Hello Server')

// 5. 断开连接（不再需要时）
// disconnectClient(clientId)

// 6. 销毁客户端（不再需要时）
// distoryClient(clientId)

多客户端管理

// 创建多个客户端
const client1 = createTCPClient()
const client2 = createTCPClient()

// 分别连接到不同的服务器
connectClient(client1, {
    serverHost: '192.168.1.100',
    serverPort: 8080
})

connectClient(client2, {
    serverHost: '192.168.1.200',
    serverPort: 8081
})

// 获取所有活跃客户端
const activeClients = getActiveClients()
console.log('活跃客户端:', activeClients)

// 检查特定客户端状态
if (clientExists(client1)) {
    const state = getClientState(client1)
    console.log('客户端1状态:', state)
}

// 动态控制心跳
enableHeartbeat(client1, 15000, 'PING')  // 启用15秒心跳
disableHeartbeat(client2)                // 禁用心跳

注意事项

1. 本插件仅支持App平台（Android/iOS），不支持H5和小程序平台
2. 使用前请确保设备网络权限已开启
3. 连接超时时间默认为5000毫秒，可根据需要调整
4. 不再使用的客户端应及时销毁，释放资源
5. 回调函数使用@UTSJS.keepAlive装饰器，确保在应用生命周期内保持有效

常见问题

Q: 如何处理连接超时？

A: 可以通过设置ConnectionOptionsType中的timeout参数来调整连接超时时间，同时通过onError回调监听超时错误。

Q: 如何同时管理多个TCP连接？

A: 每个TCP连接对应一个客户端ID，通过createTCPClient创建多个客户端，并分别管理它们的连接和消息。

Q: 如何确保消息发送成功？

A: 目前插件不提供消息发送确认机制，建议在应用层实现消息确认机制，例如通过发送特定格式的消息并等待服务器响应。

Q: 心跳功能如何工作？

A: 心跳功能会定期向服务器发送指定的心跳消息，用于保持连接活跃和检测连接状态。可以在连接时配置，也可以动态启用/禁用。

Q: 心跳消息会触发onMessage回调吗？

A: 心跳消息的发送不会触发本地回调，但如果服务器响应心跳消息，响应内容会通过onMessage回调接收。