webSocketUtil

Install

$ npm install @dabing_bigpawn/socket-util

Usage

import { useSocket } from "@dabing_bigpawn/socket-util";

// 创建 WebSocket 连接
const socket = useSocket({
  url: "/ws/chat",
  customBase: "wss://example.com",
  query: { userId: "123", token: "abc" },
  heartCheckData: { type: "ping" },
  heartCheckTimeout: 30000, // 30秒心跳
  maxReconnectCount: 5, // 最多重连5次
});

// 订阅事件
const messageHandler = (data) => {
  console.log("收到消息:", data);
};

socket.subscribe("open", (e) => {
  console.log("WebSocket 已连接");
  socket.sendMessage({ type: "hello" });
});

socket.subscribe("message", messageHandler);

socket.subscribe("error", (e) => {
  console.error("WebSocket 错误:", e);
});

socket.subscribe("reconnect", (newSocket) => {
  console.log("WebSocket 重连成功");
});

// 取消订阅
socket.unsubscribe("message", messageHandler);

// 发送消息
try {
  socket.sendMessage({ content: "Hello Server!" });
  // 发送纯文本（不转JSON）
  socket.sendMessage("plain text", { transformJSON: false });
} catch (error) {
  console.error("发送失败:", error.message);
}

// 关闭连接
socket.closeSocket();

Development

$ pnpm install
$ npm run dev
$ npm run build

Options

配置参数

• url：要连接的 WebSocket URL（必填）
• customBase：自定义的 baseURL（可选）
• protocols：一个协议字符串或者一个包含协议字符串的数组（可选）
• query：可以通过 URL 传递给后端的查询参数（可选）
• heartCheckData：心跳检测的数据内容（可选，默认为空对象）
• heartCheckTimeout：心跳检测的间隔时间，单位毫秒（可选，默认 55000ms）
• maxReconnectCount：最大重连次数（可选，默认 3 次）
• greet：心跳检测的打招呼信息（已废弃，建议使用 heartCheckData）

事件类型

• onopen：触发 dep 内 open 对应的回调函数并且打开心跳检测
• onclose：触发 dep 内 close 对应的回调函数并且对关闭的 code 码进行判断，如果是非正常关闭连接，将会进行重连，如果重连次数达到阈值，则通知给用户
• onerror：触发 dep 内 error 对应的回调函数
• onmessage：接收到服务端返回的数据，支持二进制数据（Blob）、JSON 数据和纯文本数据的自动解析，然后触发 dep 内 message 对应的回调函数并传入处理过后的数据
• onreconnect：重连时触发，传入新的 WebSocket 实例

API 方法

• subscribe(eventType, callback)：订阅 WebSocket 事件，传入事件类型（必须是 EventTypes 内的类型之一）和回调函数。支持对同一事件多次订阅。
• unsubscribe(eventType, callback)：取消订阅指定的事件监听器
• sendMessage(data, options)：发送消息到服务端。会自动检查连接状态，默认会将数据转换为 JSON 格式发送（可通过 options.transformJSON = false 关闭）
• closeSocket(code, reason)：关闭 WebSocket 连接，会自动清理心跳定时器
• resetHeartCheck()：重置心跳检测定时器

LICENSE

MIT

webSocketUtil

WebSocket 封装