@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 中上传敏感信息；可按组织安全流程提交脱敏日志。