Y-Z Site WebSocket Client

一个支持自动重连的WebSocket客户端，提供连接控制和重连管理功能。

功能特性

• 自动重连机制
• 可控制的连接关闭
• 心跳检测
• 错误处理
• 类型安全

安装

npm install y-z.site

使用方法

基本连接

import connect from 'y-z.site'

const connection = connect({
  onMessage: (message) => console.log('收到消息:', message),
  onOpen: () => console.log('连接已打开'),
  onClose: () => console.log('连接已关闭'),
  onError: (error) => console.error('连接错误:', error),
  onInfo: (info) => console.log('基础信息:', info)
})

连接控制

// 主动关闭连接，不进行重连（默认行为）
connection.close()

// 主动关闭连接，但允许重连
connection.close(true)

// 直接关闭WebSocket连接
connection.ws.close()

配置选项

const connection = connect({
  baseUrl: 'wss://your-server.com', // WebSocket服务器地址
  roomId: 'your-room-id',           // 房间ID
  reconnectDelay: 3000,             // 重连延迟时间（毫秒）
  maxRetries: 5,                    // 最大重试次数
  onMessage: (message) => { /* 处理消息 */ },
  onOpen: () => { /* 连接打开回调 */ },
  onClose: () => { /* 连接关闭回调 */ },
  onError: (error) => { /* 错误处理回调 */ },
  onInfo: (info) => { /* 基础信息回调 */ }
})

API 参考

ConnectOptions

| 参数 | 类型 | 默认值 | 描述 | |------|------|--------|------| | baseUrl | string | 'wss://y-z.site' | WebSocket服务器地址 | | roomId | string | 自动生成 | 房间ID | | reconnectDelay | number | 3000 | 重连延迟时间（毫秒） | | maxRetries | number | 5 | 最大重试次数 | | onMessage | function | () => {} | 消息处理回调 | | onOpen | function | () => {} | 连接打开回调 | | onClose | function | () => {} | 连接关闭回调 | | onError | function | () => {} | 错误处理回调 | | onInfo | function | () => {} | 基础信息回调 |

ConnectResult

| 属性 | 类型 | 描述 | |------|------|------| | ws | WebSocket | WebSocket实例 | | id | string | 设备ID | | roomId | string | 房间ID | | baseUrl | string | 服务器地址 | | close | function | 关闭连接方法 |

close 方法

close(allowReconnect?: boolean): void

• allowReconnect (可选): 是否允许重连
  • false (默认): 关闭连接，不进行重连
  • true: 关闭连接，但允许重连

重连机制

当WebSocket连接意外断开时，客户端会自动尝试重连：

1. 初始延迟为 reconnectDelay 毫秒
2. 每次重连失败后，延迟时间会递增（延迟 × 重试次数）
3. 最多重试 maxRetries 次
4. 可以通过 connection.close() 主动关闭连接，阻止重连

心跳检测

客户端每30秒发送一次ping消息来保持连接活跃。

类型支持

完整的TypeScript类型定义，包括：

• ServerMessage: 服务器消息类型
• UsersMessage: 用户列表消息
• ChatTextMessage: 聊天文本消息
• YZBaseInfo: 基础信息结构
• ConnectOptions: 连接配置选项
• ConnectResult: 连接结果对象

示例

完整的聊天应用示例

import connect from 'y-z.site'

const chatConnection = connect({
  onMessage: (message) => {
    if (message.type === 'message') {
      console.log(`收到聊天消息: ${message.data}`)
    } else if (message.type === 'users') {
      console.log(`在线用户: ${message.data.length}`)
    }
  },
  onOpen: () => {
    console.log('聊天连接已建立')
  },
  onClose: () => {
    console.log('聊天连接已断开')
  },
  onError: (error) => {
    console.error('聊天连接错误:', error)
  }
})

// 用户主动离开聊天室
function leaveChat() {
  chatConnection.close() // 不进行重连（默认行为）
}

// 用户暂时离开，但希望保持连接
function pauseChat() {
  chatConnection.close(true) // 允许重连
}