@hxa-rn/react-native-tcp

本项目基于 react-native-tcp 开发，并适配 React Native for OpenHarmony。 如果在使用过程中有任何问题，可以在 GitCode 提交 Issue，我们会及时跟进。

项目介绍

@hxa-rn/react-native-tcp 为 React Native 提供 Node.js net 风格的 TCP 客户端与服务端 API，并增加 HarmonyOS 原生实现。

主要功能包括：

• 创建 TCP 服务端并监听客户端连接。
• 创建 TCP 客户端并收发字符串或二进制数据。
• 支持连接、数据、关闭、错误和超时事件。
• 支持 IPv4、IPv6 地址检测。

集成指南

安装

在 React Native 工程根目录执行：

npm install @hxa-rn/react-native-tcp

宿主工程需使用 React Native 0.72 或更高版本，并使用 Node.js >=18。

Autolinking

本库已配置 React Native for OpenHarmony Autolinking。安装依赖后由宿主工程自动接入，无需手动注册。

导入

import tcp, {
  Server,
  Socket,
  connect,
  createConnection,
  createServer,
  isIP,
  isIPv4,
  isIPv6,
} from '@hxa-rn/react-native-tcp';

使用说明

基础用法

import tcp from '@hxa-rn/react-native-tcp';

const server = tcp.createServer((socket) => {
  socket.on('data', (data) => {
    socket.write(data);
  });
});

server.listen(0, '127.0.0.1', () => {
  const address = server.address();
  if (!address) {
    return;
  }

  const client = tcp.connect({
    host: address.address,
    port: address.port,
  });

  client.on('connect', () => {
    client.write('hello');
  });

  client.on('data', (data) => {
    console.info(data.toString());
    client.end();
    server.close();
  });
});

Socket.write 接受字符串或 Buffer。接收数据时，data 事件返回 Buffer。请为客户端和服务端监听 error 事件，以处理连接或网络异常。

IP 地址检测

import {isIP, isIPv4, isIPv6} from '@hxa-rn/react-native-tcp';

isIP('127.0.0.1'); // 4
isIPv4('127.0.0.1'); // true
isIPv6('::1'); // true

isIP 对 IPv4 返回 4，对 IPv6 返回 6，对其他输入返回 0。

接口文档

以下 API 依据 src/index.ts、src/TcpSockets.js、src/TcpServer.js、src/TcpSocket.js 和 src/specs/v1/NativeTcpSockets.ts 整理。

顶层导出

模块默认导出 TCP API 对象，同时提供以下命名导出。

属性	类型	默认值	说明
createServer	(connectionListener?) => Server	未声明	创建 TCP 服务端，可传入连接监听函数。
connect	(options, callback?) => Socket	未声明	创建 Socket 并连接到指定主机和端口。
createConnection	typeof connect	未声明	connect 的别名，也支持端口、主机和回调位置参数。
Socket	TcpSocket 构造函数	未声明	TCP 双工 Socket 类。
Server	TcpServer 构造函数	未声明	TCP 服务端类。
isIP	(input: string) => 0 | 4 | 6	未声明	判断输入是否为 IPv4 或 IPv6 地址。
isIPv4	(input: string) => boolean	未声明	判断输入是否为 IPv4 地址。
isIPv6	(input: string) => boolean	未声明	判断输入是否为 IPv6 地址。

Socket

Socket 继承自 stream.Duplex，用于建立连接、收发数据和管理连接生命周期。

属性	类型	默认值	说明
connect	(options, callback?) => Socket	host: 'localhost'、port: 0	连接 TCP 服务端；options 支持 host、port、localAddress、localPort 和 timeout。
write	(chunk, encoding?, callback?) => boolean	未声明	发送字符串或 Buffer。
end	(data?, encoding?) => Socket	未声明	可选地发送最后一段数据，然后结束连接。
destroy	() => Socket	未声明	立即销毁连接并清理超时计时器。
setTimeout	(msecs, callback?) => Socket	未声明	设置空闲超时；传入 0 可取消超时。
address	() => TcpSocketAddress | undefined	未声明	返回当前连接地址。
ref / unref	() => Socket	未声明	兼容 Node.js API，返回当前 Socket。
setNoDelay / setKeepAlive / setEncoding	(...args) => Socket	未声明	兼容 Node.js API，当前实现仅返回当前 Socket。

Socket 可监听 connect、data、timeout、error 和 close 事件。

Server

Server 用于监听端口、接收连接并管理服务端生命周期。

属性	类型	默认值	说明
listen	(port, host?, callback?) => Server	host: '0.0.0.0'	绑定指定地址和端口并开始监听。
address	() => TcpSocketAddress | undefined	未声明	返回服务端监听地址。
getConnections	(callback) => Server	未声明	通过回调返回当前连接数。
close	(callback?) => Server	未声明	停止监听并关闭服务端。
ref / unref	() => Server	未声明	兼容 Node.js API，返回当前 Server。

Server 可监听 listening、connection、error 和 close 事件。

快速验证（运行 Example）

前置条件

依赖	版本要求
Node.js	>=20
React Native for OpenHarmony	0.72.139
HarmonyOS SDK	API 21+

运行步骤

1. 获取开发分支源码：

   git clone -b react-native-tcp_dev https://gitcode.com/hxa-rn/react-native-tcp.git
   

2. 进入仓库根目录：

   cd react-native-tcp
   

3. 安装根目录依赖：

   npm i
   

4. 生成供示例工程安装的本地安装包：

   npm pack
   

5. 进入 example 目录：

   cd example
   

6. 安装示例工程依赖：

   npm i
   

7. 生成 React Native JavaScript Bundle：

   npm run dev
   

8. 使用 DevEco Studio 打开 example/harmony，同步依赖并完成签名配置后构建运行。

约束与限制

兼容性

依赖	要求
React Native for OpenHarmony	0.72.139
HarmonyOS SDK	API 21+
Example 工程 compatibleSdkVersion	6.0.1(21)
Example 工程 targetSdkVersion	6.1.1(24)
Node.js	>=18

使用限制

• 本库仅提供明文 TCP，不提供 TLS、证书校验、自动重连或网络状态订阅能力。
• ref、unref、setNoDelay、setKeepAlive 和 setEncoding 为兼容 Node.js API 保留，当前实现不提供额外平台行为。
• Socket.write 仅接受字符串或 Buffer。
• 地址对象中的 family 为 IPv4 或 IPv6；域名连接由系统 Network Kit 解析，返回地址以系统实际结果为准。

系统权限

本库需要 ohos.permission.INTERNET 权限，HAR 模块已在 harmony/tcp/src/main/module.json5 中声明该权限。

开源 License

本项目采用 MIT License，与上游项目保持一致。

问题反馈渠道

如在使用过程中遇到问题，请在 GitCode 提交Issue，我们会及时跟进。

• 提交问题时建议附上项目版本、RN 版本、OpenHarmony SDK/API 版本、DevEco Studio 版本、设备信息、复现步骤及相关日志。
• 涉及签名、账号、密钥或用户数据时，请勿在 Issue 中上传敏感信息；可按组织安全流程提交脱敏日志。