更新记录

1.0.0（2025-03-16） 下载此版本

1.0.0（2025-03-16）第一版

平台兼容性

uvos-websocket

uvos-websocket 是一个基于 uni-app 的 WebSocket 封装库，集成了消息收发、心跳检测、自动重连等功能，简单易用，支持 Promise 风格调用。

功能特性

• 消息收发：支持发送和接收消息，消息格式为 event + data。
• 心跳检测：自动发送心跳消息，保持连接活跃。
• 自动重连：连接断开后自动重连，支持配置重连次数和间隔。
• 消息队列：在连接未建立时缓存消息，连接成功后自动发送。
• 日志打印：支持控制是否打印日志信息。
• 多平台支持：兼容 Vue2、Vue3、App、H5、小程序等平台。

快速开始

1. 引入组件

import { UvosWebSocket, Message } from '@/js_sdk/uvos-websocket/js/websocket.js';

2. 创建 WebSocket 实例

const ws = new UvosWebSocket('wss://your-websocket-url', {
  reconnectLimit: 5, // 最大重连次数
  heartBeatInterval: 10000, // 心跳间隔（毫秒）
  logInfo: true, // 是否打印日志
});

3. 初始化连接

ws.init().then(() => {
  console.log('WebSocket 连接成功');
}).catch((err) => {
  console.error('WebSocket 连接失败', err);
});

4. 设置回调

ws.onOpen(() => {
  console.log('WebSocket 已连接');
})
ws.onMessage((message) => {
  console.log('收到消息:', message);
})
ws.onError((err) => {
  console.error('WebSocket 错误:', err);
})
ws.onClose(() => {
  console.log('WebSocket 已关闭');
});

5. 发送消息

ws.send(new Message('event-name', { key: 'value' }));

6. 关闭连接

ws.close();

API 说明

UvosWebSocket 类

构造函数

new UvosWebSocket(url, options)

• url：WebSocket 服务器地址。
• options：配置项（可选），包括：
  • reconnectLimit：最大重连次数，默认 3。
  • reconnectInterval：重连间隔（毫秒），默认 3000。
  • heartBeatInterval：心跳间隔（毫秒），默认 5000。
  • heartBeatMessage：心跳消息，默认 "ping"。
  • logInfo：是否打印日志，默认 true。

方法

• init()：初始化连接，返回 Promise。
• send(message)：发送消息，message 必须是 Message 实例。
• close()：关闭连接。
• onOpen(callback)：设置连接成功回调。
• onMessage(callback)：设置消息接收回调。
• onError(callback)：设置错误回调。
• onClose(callback)：设置连接关闭回调。

Message 类

构造函数

new Message(event, data)

• event：消息事件名称。
• data：消息数据。

示例代码

1. 基本使用

import { UvosWebSocket, Message } from '@/js_sdk/uvos-websocket/js/websocket.js';

const ws = new UvosWebSocket('wss://your-websocket-url', {
  reconnectLimit: 5,
  heartBeatInterval: 10000,
  logInfo: true,
});

ws.init()
  .then(() => {
    console.log('WebSocket 连接成功');
  })
ws.catch((err) => {
    console.error('WebSocket 连接失败', err);
  });

ws.onOpen(() => {
  console.log('WebSocket 已连接');
})
ws.onMessage((message) => {
  console.log('收到消息:', message);
})
ws.onError((err) => {
  console.error('WebSocket 错误:', err);
})
ws.onClose(() => {
  console.log('WebSocket 已关闭');
});

// 发送消息
ws.send(new Message('event-name', { key: 'value' }));

// 关闭连接
ws.close();

2. 自动重连

如果连接断开，uvos-websocket 会自动尝试重连，直到达到最大重连次数。

const ws = new UvosWebSocket('wss://your-websocket-url', {
  reconnectLimit: 5, // 最大重连次数
  reconnectInterval: 3000, // 重连间隔
});

ws.init();

3. 心跳检测

uvos-websocket 会自动发送心跳消息，保持连接活跃。

const ws = new UvosWebSocket('wss://your-websocket-url', {
  heartBeatInterval: 10000, // 心跳间隔
  heartBeatMessage: 'ping', // 心跳消息
});

ws.init();

注意事项

跨平台兼容性

• 在 H5 和小程序平台，WebSocket 的实现可能有所不同，请确保服务器支持跨平台连接。
• 在 App 平台，需要使用 uni.connectSocket。

心跳消息

• 默认心跳消息为 "ping"，如果需要自定义，可以在配置中修改 heartBeatMessage。

日志打印

• 默认会打印日志信息，如果需要关闭日志，可以在配置中设置 logInfo: false。

技术支持

如有问题或建议，请联系 QQ：76853442。

通过这份 README.md，用户可以快速了解 uvos-websocket 的功能和使用方法，并集成到自己的项目中。