更新记录

1.0.0（2026-07-01） 下载此版本

初始版本

平台兼容性

uni-app(4.25)

uni-app x(4.25)

其他

xyz-socket

uni-app x 跨平台 TCP/UDP Socket 插件，支持 Android、iOS、HarmonyOS。

安装

将 xyz-socket 目录复制到项目的 uni_modules 目录下即可。

基本用法

import { createTcpSocket, createUdpSocket } from "@/uni_modules/xyz-socket"

TCP

import {
  createTcpSocket,
  CreateTcpSocketOptions,
  TcpConnectOptions,
  TcpSendOptions,
  TcpCloseOptions,
} from "@/uni_modules/xyz-socket"

// 1. 创建 TCP Socket
const tcpTask = createTcpSocket({
  host: "192.168.1.100",
  port: 8089,
  timeout: 10000,
  success: (res) => { console.log(res.errMsg) },
  fail: (err) => { console.error(err.errCode, err.errMsg) },
} as CreateTcpSocketOptions)

// 2. 注册事件回调
tcpTask.onConnect((result) => {
  console.log("Connected:", result.localAddress, result.localPort)
})

tcpTask.onMessage((result) => {
  const bytes = new Uint8Array(result.data)
  const msg = String.fromCharCode(...bytes)
  console.log("Received:", msg)
})

tcpTask.onClose((result) => {
  console.log("Closed, isLocal:", result.isLocal)
})

tcpTask.onError((result) => {
  console.error("Error:", result.errMsg)
})

// 3. 发起连接
tcpTask.connect({
  success: (res) => { console.log("connect ok") },
  fail: (err) => { console.error("connect fail:", err.errCode) },
} as TcpConnectOptions)

// 4. 发送数据（字符串或 ArrayBuffer）
tcpTask.send({
  data: "Hello Server",
  success: (res) => { console.log("send ok") },
  fail: (err) => { console.error("send fail:", err.errCode) },
} as TcpSendOptions)

// 5. 关闭连接
tcpTask.close({
  success: (res) => { console.log("close ok") },
} as TcpCloseOptions)

UDP

import {
  createUdpSocket,
  CreateUdpSocketOptions,
  UdpBindOptions,
  UdpSendOptions,
  UdpCloseOptions,
} from "@/uni_modules/xyz-socket"

// 1. 创建 UDP Socket
const udpTask = createUdpSocket({
  success: (res) => { console.log(res.errMsg) },
  fail: (err) => { console.error(err.errCode) },
} as CreateUdpSocketOptions)

// 2. 注册事件回调
udpTask.onMessage((result) => {
  const bytes = new Uint8Array(result.data)
  const msg = String.fromCharCode(...bytes)
  console.log("From:", result.remoteInfo.address, result.remoteInfo.port, "Data:", msg)
})

udpTask.onClose((result) => {
  console.log("Closed:", result.errMsg)
})

udpTask.onError((result) => {
  console.error("Error:", result.errMsg)
})

// 3. 绑定本地端口（0 为自动分配）
udpTask.bind({
  port: 0,
  success: (res) => { console.log("bind ok") },
  fail: (err) => { console.error("bind fail:", err.errCode) },
} as UdpBindOptions)

// 4. 发送数据报
udpTask.send({
  data: "Hello UDP",
  host: "192.168.1.100",
  port: 8090,
  success: (res) => { console.log("send ok") },
  fail: (err) => { console.error("send fail:", err.errCode) },
} as UdpSendOptions)

// 5. 关闭
udpTask.close({
  success: (res) => { console.log("close ok") },
} as UdpCloseOptions)

API

createTcpSocket(options)

创建 TCP Socket 实例。

参数 CreateTcpSocketOptions：

返回值： TcpSocketTask

TcpSocketTask

createUdpSocket(options)

创建 UDP Socket 实例。

参数 CreateUdpSocketOptions：

返回值： UdpSocketTask

UdpSocketTask

UdpBindOptions：

UdpSendOptions：

事件回调

TCP 事件

UDP 事件

错误码

TCP 错误码

UDP 错误码

注意事项

• 模拟器中连接本机服务时，Android/Harmony 使用 10.0.2.2，iOS 使用 127.0.0.1
• TCP 的 onMessage 回调中 data 为 ArrayBuffer 类型，需要通过 Uint8Array 转换后使用
• UDP 必须先 bind 后才能 send 和接收数据
• 页面销毁时应调用 close() 释放资源
• send 的 data 参数支持 string（自动 UTF-8 编码）或 ArrayBuffer

底层实现