# websocket

**Repository Path**: Duke_Bit/websocket

## Basic Information

- **Project Name**: websocket
- **Description**: 仓颉版的WebSocket实现，提供给ArkTS使用，解决ArkTS提供的 API12-API17下 WebSocket下 buffer和string混合传递，类型错乱的问题，解决on("Message")下payload大小为0 导致message为undefined的情况
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-07-24
- **Last Updated**: 2025-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebSocketClient Library for OpenHarmony

## 简介

[![openHarmony](https://img.shields.io/badge/openharmony-v1.0.5-brightgreen)](https://gitee.com/Duke_Bit/websocket/releases/tag/v1.0.5)

WebSocketClient是一个为OpenHarmony开发的WebSocket客户端库，提供简单易用的API来建立WebSocket连接、发送和接收消息。

- 支持WebSocket客户端连接
- 支持文本和二进制数据传输
- 支持事件监听和处理
- 仓颉版的WebSocket实现，提供给ArkTS使用，解决ArkTS提供的 API12-API17下 WebSocket下 buffer和string混合传递，类型错乱的问题，
- 解决on("Message")下payload大小为0 导致message为undefined的情况

## 下载安装

````
ohpm install @duke/websocket-client
````

OpenHarmony ohpm
环境配置等更多内容，请参考[如何安装 OpenHarmony ohpm 包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md)

## 使用说明

### 基本用法

导入WebSocket库：

```typescript
import { createWebSocket, WebSocketClient, WebSocketClientEvent } from '@duke/websocket-client';
```

创建WebSocket客户端实例：

```typescript
const wsClient = createWebSocket();
```

连接到WebSocket服务器：

```typescript
wsClient.connect("ws://your-websocket-server-url");
```

### 事件监听

可以监听以下事件：

连接打开事件：

```typescript
wsClient.on("open", (event: WebSocketClientEvent) => {
  console.log("WebSocket连接已打开");
})
```

接收到文本消息：

```typescript
wsClient.on("messageText", (data: string) => {
  console.log("收到文本消息：", data);
})
```

接收到二进制数据：

```typescript
wsClient.on("messageBuffer", (data: ArrayBuffer) => {
  console.log("收到二进制消息，长度: " + data.byteLength);
})
```

连接关闭事件：

```typescript
wsClient.on("close", (event: WebSocketClientEvent) => {
  console.log("WebSocket连接已关闭");
})
```

错误事件：

```typescript
wsClient.on("error", (event: WebSocketClientEvent) => {
  console.log("WebSocket发生错误" + event.reason);
})
```

### 发送消息

发送文本消息：

```typescript
wsClient.send("Hello, WebSocket!");
```

发送二进制数据：

```typescript
const buffer = new ArrayBuffer(10);
wsClient.send(buffer);
```

### 关闭连接

```typescript
wsClient.close();
```

### 移除事件监听

可以移除特定事件的监听器：

```typescript
// 移除特定回调函数
wsClient.off("messageText", messageHandler)
// 移除所有回调函数
wsClient.off("messageText");
```

### WebSocketClient


| 方法名     | 入参                                                             | 接口描述                    |
|:--------|:---------------------------------------------------------------|:------------------------|
| connect | url: string                                                    | 连接到指定URL的WebSocket服务器   |
| send    | data: string \| ArrayBuffer                                    | 发送文本或二进制数据，返回Promise    |
| send    | data: string \| ArrayBuffer, callback: (error: string) => void | 发送文本或二进制数据，通过回调处理结果     |
| close   | 无                                                              | 关闭WebSocket连接，返回Promise |
| close   | callback: (error: string) => void                              | 关闭WebSocket连接，通过回调处理结果  |
| on      | event: string, callback: Function                              | 注册事件监听器                 |
| off     | event: string, callback?: Function                             | 移除事件监听器                 |

### 事件类型

| 事件名           | 回调参数类型               | 描述         |
|:--------------|:---------------------|:-----------|
| open          | WebSocketClientEvent | 连接成功打开时触发  |
| messageText   | string               | 收到文本消息时触发  |
| messageBuffer | ArrayBuffer          | 收到二进制消息时触发 |
| close         | WebSocketClientEvent | 连接关闭时触发    |
| error         | WebSocketClientEvent | 发生错误时触发    |

### WebSocketClientEvent

| 属性名    | 类型               | 描述   |
|:-------|:-----------------|:-----|
| code   | string \| number | 状态码  |
| reason | string           | 原因描述 |


## 约束与限制

在下述版本验证通过：

DevEco Studio: 5.0.5.315, SDK: HarmonyOS 5.0.1 Release Ohos_sdk_public 5.0.1.115 (API Version 13 Release)

## 目录结构

````
|---- WebSocket
|     |---- AppScrope  # 示例代码文件夹
|     |---- entry  # 示例代码文件夹
|     |---- examples # 示例代码文件夹  
|     |---- library # WebSocketClient库文件夹  
|           |---- build  # WebSocketClient模块打包后的文件
|           |---- index.ets  # 对外接口     
|     |---- README.md  # 安装使用方法
|     |---- CHANGELOG.md  # 更新日志
````

## 贡献代码

使用过程中发现任何问题都可以提 [Issue](https://gitee.com/Duke_Bit/websocket/issues)
给我，当然，我也非常欢迎你给我发 [PR](https://gitee.com/Duke_Bit/websocket) 。

## 开源协议

本项目基于 [MIT license](https://gitee.com/Duke_Bit/websocket/blob/master/LICENSE) ，请自由地享受和参与开源。

## 其他库

- [eventpost](https://ohpm.openharmony.cn/#/cn/detail/eventpost) 事件分发，支持组件中的lifecycle，在组件中使用自动取消订阅: [https://gitee.com/Duke_Bit/eventpost](https://gitee.com/Duke_Bit/eventpost)
- [@duke/component-lifecycle](https://ohpm.openharmony.cn/#/cn/detail/@duke%2Fcomponent-lifecycle)
  鸿蒙版本的Lifecycle库，支持组件、Router和Navigation: [https://gitee.com/Duke_Bit/component-lifecycle](https://gitee.com/Duke_Bit/component-lifecycle)
- [@duke/elf-dialog](https://ohpm.openharmony.cn/#/cn/detail/@duke%2Felf-dialog) CustomDialog黑魔法 不依赖promptAction
  实现的函数级弹窗，省去复杂的模版代码，让你专注于你的业务，一行代码搞定弹窗: [https://gitee.com/Duke_Bit/elf-dialog](https://gitee.com/Duke_Bit/elf-dialog)
- [@duke/elf-refresh](https://ohpm.openharmony.cn/#/cn/detail/@duke%2Felf-refresh) OpenHarmony
  刷新组件，支持下拉刷新和上拉加载更多，支持各种组件，List、Grid，支持header，footer，目标打造HarmonyOS的SmartRefreshLayout: [https://gitee.com/Duke_Bit/ElfRefresh](https://gitee.com/Duke_Bit/ElfRefresh)