h5-ws

H5 Websocket

特性

1. 同时支持 node 和 h5
2. 自动重连
3. 离线消息缓存

安装

npm install @asteres/websocket --save

使用

import Ws from "@asteres/websocket";

const options = {
  /** 是否开启断线重连, 默认: true */
  reconnection: true,
  /** 最大重连次数, -1 则一直重连, 默认: 5 */
  maxRetries: 5,
  /** 断线时，缓存的发送的消息列表大小, -1 - 无限大小, 默认: 0 */
  maxCacheSize: 0,
  /** {@link https://developer.mozilla.org/zh-CN/docs/Web/API/WebSocket/WebSocket#protocols 协议数组} */
  protocols?: string | string[];
  /** 自定义日志记录器, 默认为: console */
  logger?: {
    info: (msg: string) => void;
    warn?: (msg: string) => void;
    error?: (msg: string) => void;
  },
  /**
   * WebSocket 客户端, 如果不想用原生, 可以指定库, 例如: 在 node 环境可以替换为 ws
   *
   * 示例:
   * import WebSocket from 'ws'
   * import Ws from '@asteres/websocket'
   *
   * const ws = new Ws("", {
   *  target: WebSocket
   * });
   */
  target?: globalThis.Websocket;
};

const ws = new Ws("ws://localhost:8080", options);

// 服务端使用 Pino 日志
import Pino from 'pino'

const logger = Pino()

const ws = new Ws("ws://localhost:8080", { logger })

options 参数为选填

方法

1. constructor(url: string, options?: WsOption)

2. on(type: 'open' | 'close' | 'error' | 'message', handler: WsEvent)

3. off(type: 'open' | 'close' | 'error' | 'message', handler: WsEvent)

注意: 为了 off 能正常工作，务必 on 的函数不要直接写回调函数

4. send(data: string | object | ArrayBuffer | Blob | ArrayBufferView, isCache?: boolean): boolean

发送消息, 跟原生方法相比, 支持普通的 JSON 对象，如果是普通的 JSON 对象，会自动转换为 JSON 字符串; 如果断线会返回发送失败

参数说明:

• data: 消息体
• isCache: 如果断线时，是否缓存消息, 默认: true

注意: 消息是否缓存，除了跟 isCache 参数有关，还跟配置连接时 maxCacheSize 配置项有关，如果这个配置项设置为 0 也不会缓存；这个配置项默认为 0

5. close(code?: number, reason?: string, destroy?: boolean)

断开连接

参数说明:

• code: 关闭连接的状态码, 默认: 1000
• reason: 关闭连接的原因, 默认: ""
• destroy: 是否销毁连接, 默认: true；如果为 true 则销毁后无法通过 connect 重连

6. connect()

连接到 WebSocket 服务器

注意: 如果创建连接时, reconnection 配置项为 false, 则需要手动调用该函数进行连接