xxm-test-js/dist/lib/WebSocketClient.d.ts

xxm-js通用js工具(utils)库

/**
 * WebSocket 客户端封装类
 *
 * 使用场景：用于建立和管理 WebSocket 连接，提供自动重连、心跳检测、消息队列等功能。
 * 适用于需要实时双向通信的应用，如聊天应用、实时数据推送、在线协作等。
 *
 * 主要特性：
 * - 自动重连：连接断开后自动尝试重新连接
 * - 心跳检测：定时发送心跳包保持连接活跃
 * - 消息队列：连接未建立时缓存消息，连接成功后自动发送
 * - 事件监听：支持监听连接、断开、消息、错误等事件
 * - 连接状态管理：提供完整的连接状态跟踪
 *
 * @example
 * ```typescript
 * const ws = new WebSocketClient('ws://localhost:8080', {
 *   reconnectInterval: 3000,
 *   heartbeatInterval: 30000,
 *   heartbeatMessage: 'ping'
 * });
 *
 * ws.on('open', () => console.log('连接成功'));
 * ws.on('message', (data) => console.log('收到消息:', data));
 * ws.on('error', (error) => console.error('连接错误:', error));
 * ws.on('close', () => console.log('连接关闭'));
 *
 * ws.connect();
 * ws.send({ type: 'chat', message: 'Hello' });
 * ```
 */
interface WebSocketClientOptions {
    /**
     * 自动重连开关，默认 true
     */
    reconnect?: boolean;
    /**
     * 重连间隔时间（毫秒），默认 5000ms
     */
    reconnectInterval?: number;
    /**
     * 最大重连次数，默认 Infinity（无限次）
     */
    maxReconnectAttempts?: number;
    /**
     * 心跳检测开关，默认 true
     */
    heartbeat?: boolean;
    /**
     * 心跳间隔时间（毫秒），默认 30000ms
     */
    heartbeatInterval?: number;
    /**
     * 心跳消息内容，默认 'ping'
     */
    heartbeatMessage?: string | object;
    /**
     * 连接超时时间（毫秒），默认 10000ms
     */
    connectionTimeout?: number;
    /**
     * WebSocket 子协议
     */
    protocols?: string | string[];
    /**
     * 是否启用调试日志，默认 false
     */
    debug?: boolean;
}
type EventType = 'open' | 'close' | 'message' | 'error' | 'reconnect';
type WebSocketMessage = string | object | ArrayBuffer | Blob | ArrayBufferView;
type EventCallbackData = WebSocketMessage | Event | CloseEvent | MessageEvent | {
    attempt: number;
} | undefined;
type EventCallback = (data?: EventCallbackData) => void;
declare class WebSocketClient {
    private url;
    private options;
    private ws;
    private reconnectAttempts;
    private reconnectTimer;
    private heartbeatTimer;
    private connectionTimer;
    private messageQueue;
    private eventListeners;
    private isManualClose;
    private isReconnectAbandoned;
    constructor(url: string, options?: WebSocketClientOptions);
    /**
     * 建立 WebSocket 连接
     */
    connect(): void;
    /**
     * 关闭 WebSocket 连接
     * @param code 关闭状态码
     * @param reason 关闭原因
     */
    disconnect(code?: number, reason?: string): void;
    /**
     * 发送消息
     * @param data 要发送的数据（支持字符串、对象等）
     */
    send(data: string | object | ArrayBuffer | Blob): void;
    /**
     * 监听事件
     * @param event 事件类型
     * @param callback 回调函数
     */
    on(event: EventType, callback: EventCallback): void;
    /**
     * 移除事件监听
     * @param event 事件类型
     * @param callback 回调函数
     */
    off(event: EventType, callback: EventCallback): void;
    /**
     * 获取当前连接状态
     * @returns 连接状态：CONNECTING(0), OPEN(1), CLOSING(2), CLOSED(3)
     */
    getReadyState(): number;
    /**
     * 获取连接状态描述
     */
    getStatus(): string;
    /**
     * 处理连接打开事件
     */
    private handleOpen;
    /**
     * 处理连接关闭事件
     */
    private handleClose;
    /**
     * 处理消息接收事件
     */
    private handleMessage;
    /**
     * 处理错误事件
     */
    private handleError;
    /**
     * 处理重连逻辑
     */
    private handleReconnect;
    /**
     * 启动心跳检测
     */
    private startHeartbeat;
    /**
     * 停止心跳检测
     */
    private stopHeartbeat;
    /**
     * 发送消息队列中的所有消息
     */
    private flushMessageQueue;
    /**
     * 清除所有定时器
     */
    private clearTimers;
    /**
     * 触发事件
     */
    private emit;
    /**
     * 输出日志
     */
    private log;
    /**
     * 销毁实例，清理所有资源
     */
    destroy(): void;
}
export { WebSocketClient, WebSocketClientOptions };