更新记录

1.2.7（2026-09-20）

• 修复app-vue模式下，dcloud打包服务升级kotlin2导致的打包错误
• README文档说明补充

1.2.6（2025-02-11）

修复iOS端发送字符串消息，服务端接收乱码的问题

1.2.5（2025-01-24）

修复Android平台执行close方法时，onClose回调被执行了两次

平台兼容性

uni-app(3.8.4)

uni-app x(3.8.4)

wtto-TCPSocket

使用时，请务必在所有的回调函数中用try-catch完全包裹自己的代码；

如果在回调中你自己的代码有抛出异常，本插件会捕获这个异常，从而在控制台显示本插件异常的提示。

app-vue/js/ts 项目用法

引入插件

import { connect, bindWifiConnect } from '@/uni_modules/wtto-TCPSocket/api.js';

连接 TCP Socket

const TCP_ADDRESS = '192.168.31.254';
const TCP_PORT = 6668;
connect(
  {
    address: TCP_ADDRESS,
    port: TCP_PORT,
  },
  (instance) => {
    try {
      // 连接成功后的回调，这里的instance实例可以直接调用改实例的方法
      console.log('连接成功', instance);
      // do your actions
      // 调用instance的onClose和onMessage方法，监听回调
      // 之后可以调用instance.write方法，发送消息
    } catch (err) {
      console.error('connect error: ', err);
    }
  },
  (err) => {
    // 发生错误的回调，全生命周期有效，即其他接口的错误信息也是使用此回调
    console.error(`出错了: ${err.errMsg}`);
  },
);

绑定 WIFI 连接 TCP Socket

仅支持Android >= 5.0 版本

bindWifiConnect(
  {
    address: TCP_ADDRESS,
    port: TCP_PORT,
  },
  (instance) => {
    try {
      // 连接成功后的回调，这里的instance实例可以直接调用改实例的方法
      console.log('连接成功', instance);
      // do your actions
      // 调用instance的onClose和onMessage方法，监听回调
      // 之后可以调用instance.write方法，发送消息
    } catch (err) {
      console.error('bindWifiConnect error: ', err);
    }
  },
  (err) => {
    // 发生错误的回调，全生命周期有效，即其他接口的错误信息也是使用此回调
    console.error(`出错了: ${err.errMsg}`);
  },
);

主动断开连接

instance.close();

监听连接断开事件

instance.onClose(() => {
  try {
    console.log('已断开连接');
  } catch (err) {
    console.error('onClose error: ', err);
  }
});

监听接收消息

instance.onMessage((data) => {
  try {
    console.log(`接收到消息: ${JSON.stringify(data)}`);
    const buffer = new Uint8Array(data);
    // buffer => string
    const message = buffer.reduce((msg, item) => msg + String.fromCharCode(item), '');
    console.log(`接收到消息转为字符串: ${message}`);
  } catch (err) {
    console.error('onMessage error: ', err);
  }
});

发送字符串消息

instance.writeString('Hi');

发送 Buffer 消息

// 72=0x48='H' 105=0x69='i'
const buffer = new Uint8Array([72, 105]);
instance.write([...buffer]);
// 即相当于: instance.write([72, 105]);

uniapp-x/uts 项目用法

准备

插件下载到项目后，请把文件uni_modules/wtto-TCPSocket/api.ts重命名为api.uts。

引入插件

import { ConnectOptions, Err, TcpSocket, bindWifiConnect, connect } from '@/uni_modules/wtto-TCPSocket/api.uts';

连接 TCP Socket

const TCP_ADDRESS = '192.168.31.254';
const TCP_PORT = 6668;
connect(
  {
    address: TCP_ADDRESS,
    port: TCP_PORT,
  } as ConnectOptions,
  (instance: TcpSocket) => {
    try {
      // 连接成功后的回调
      console.log('连接成功', instance.id);
      // do your actions
      // 调用onClose和onMessage方法，监听回调
      // 之后可以调用write方法，发送消息
    } catch (err) {
      console.error('connect error: ', err);
    }
  },
  (err: Err) => {
    // 发生错误的回调，全生命周期有效，即其他接口的错误信息也是使用此回调
    console.error(`出错了: ${err.errMsg}`);
  },
);

绑定 WIFI 连接 TCP Socket

仅支持Android >= 5.0 版本

bindWifiConnect(
  {
    address: TCP_ADDRESS,
    port: TCP_PORT,
  } as ConnectOptions,
  (instance: TcpSocket) => {
    try {
      // 连接成功后的回调
      console.log('连接成功', instance.id);
      // do your actions
      // 调用onClose和onMessage方法，监听回调
      // 之后可以调用write方法，发送消息
    } catch (err) {
      console.error('bindWifiConnect error: ', err);
    }
  },
  (err: Err) => {
    // 发生错误的回调，全生命周期有效，即其他接口的错误信息也是使用此回调
    console.error(`出错了: ${err.errMsg}`);
  },
);

主动断开连接

instance.close();

监听连接断开事件

instance.onClose(() => {
  try {
    console.log('已断开连接');
  } catch (err) {
    console.error('onClose error: ', err);
  }
});

监听接收消息

instance.onMessage((data: number[]) => {
  try {
    console.log(`接收到消息: ${JSON.stringify(data)}`);
    const buffer = new Uint8Array(data);
    // buffer => string
    const message = buffer.reduce((msg: string, item: number): string => msg + String.fromCharCode(item), '');
    console.log(`接收到消息转为字符串: ${message}`);
  } catch (err) {
    console.error('onMessage error: ', err);
  }
});

发送字符串消息

instance.writeString('Hi');

发送 Buffer 消息

// 72=0x48='H' 105=0x69='i'
instance.write([72, 105]);

bindWifiConnect和connect的区别

此插件一般用于IoT设备自建WiFi热点，然后手机APP应用连接局域网WiFi热点来传输数据。

然而有些手机有个功能叫网络加速,意思就是“允许在WiFi网络不佳时，同时使用移动数据上网”。

手机APP连接上IoT设备自建WiFi热点后，开始传输数据，触发手机系统的网络加速功能，就导致用户在使用tcp数据时，突然连不上，手机系统自动切换到了移动数据网络来连接。

使用bindWifiConnect方法，可以在网络加速的情况下，手机系统中其他app应用正常使用网络加速的移动数据网络上网。用户开发的tcp这个进程，会保持使用连接的WiFi来传输数据，不受网络加速功能影响。

鸿蒙打包出错

如果鸿蒙系统打包，报错提示'app-harmony/uni_modules/wtto-TCPSocket/utssdk/app-harmony/index.ets' is not a module.

可以复制文件uni_modules/wtto-TCPSocket/hvigorfile.ts到harmony-configs/hvigorfile.ts中解决。