@lejurobot/stomp-websocket

一个基于 Vue 3 的 STOMP WebSocket 库，提供组合式 API（Composable Hooks），让 WebSocket 通信变得更加简单。

这个包提供了什么

本包提供了两个核心的组合式函数，帮助你在 Vue 3 项目中轻松实现 STOMP WebSocket 通信：

1. useStomp - 基础连接管理

提供完整的 STOMP WebSocket 连接管理功能：

• ✅ 连接/断开管理
• ✅ 订阅/取消订阅主题
• ✅ 发送消息
• ✅ 自动重连机制
• ✅ 连接状态实时监听
• ✅ 消息接收处理

2. useStompChannel - 高级通道管理

在 useStomp 基础上提供更高级的功能：

• ✅ 自动订阅主题
• ✅ 定时轮询发送消息
• ✅ 连接状态变化时自动恢复订阅
• ✅ 组件卸载时自动清理资源
• ✅ 手动发送消息接口

主要特性

• 🎯 完美支持 Vue 3 Composition API
• 🔄 自动重连处理，无需手动干预
• 📦 简单直观的 API 设计
• 🎨 完整的 TypeScript 类型支持
• ⚡ 轻量级，性能优异
• 🛡️ 自动资源清理，避免内存泄漏

安装

npm install @lejurobot/stomp-websocket
# 或
pnpm add @lejurobot/stomp-websocket
# 或
yarn add @lejurobot/stomp-websocket

依赖要求

本包需要以下 peer dependencies：

{
  "vue": "^3.0.0",
  "@stomp/stompjs": "^7.0.0"
}

使用示例

基础用法 - useStomp

import { useStomp } from "@lejurobot/stomp-websocket";

// 创建 STOMP 实例
const { connectionStatus, connect, disconnect, subscribe, send } = useStomp(
  "ws://localhost:8080/ws",
);

// 连接到服务器
connect();

// 订阅主题
subscribe("/topic/messages", (payload) => {
  console.log("收到消息:", payload);
});

// 发送消息
send("/app/chat", { message: "Hello World" });

// 断开连接
disconnect();

高级用法 - useStompChannel

import { useStomp, useStompChannel } from "@lejurobot/stomp-websocket";

// 创建基础 STOMP 实例
const stomp = useStomp("ws://localhost:8080/ws");
stomp.connect();

// 使用通道管理器
const { isConnected, lastMessage, send } = useStompChannel(stomp, {
  // 自动订阅的主题
  subscribeTopic: "/topic/updates",

  // 定时发送的配置
  sends: [
    {
      destination: "/app/ping",
      interval: 5000, // 每5秒发送一次
      payload: () => ({ data: "ping" }),
    },
  ],

  // 收到消息的回调
  onMessage: (payload) => {
    console.log("收到消息:", payload);
  },

  // 连接成功的回调
  onConnected: (sendFn) => {
    console.log("已连接!");
    sendFn("/app/hello", { greeting: "Hi there!" });
  },
});

API 参考

useStomp

返回一个包含以下属性和方法的对象：

| 属性/方法 | 类型 | 说明 | | ------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | connectionStatus | Ref<ConnectionStatus> | 当前连接状态：'disconnected'（断开）、'connecting'（连接中）、'connected'（已连接）、'error'（错误） | | messages | Ref<any[]> | 接收到的消息数组 | | connect | () => void | 连接到 WebSocket 服务器 | | disconnect | () => void | 断开与服务器的连接 | | subscribe | (topic: string, callback: Function) => string | 订阅主题，返回主题 ID | | unsubscribe | (topic: string) => void | 取消订阅主题 | | send | (destination: string, body: object) => void | 向指定目标发送消息 | | isConnected | () => boolean | 检查当前是否已连接 |

useStompChannel

用于管理订阅和定时发送的高级组合式函数。

配置选项

interface StompChannelOptions {
  subscribeTopic?: string; // 要订阅的主题
  sends?: SendConfig[]; // 定时发送配置数组
  onMessage?: (payload: any) => void; // 消息回调函数
  onConnected?: (sendFn: Function) => void; // 连接成功回调函数
}

interface SendConfig {
  destination: string; // 发送目标
  interval?: number; // 发送间隔（毫秒，默认 3000）
  payload?: () => any; // 返回负载数据的函数
}

返回值

| 属性/方法 | 类型 | 说明 | | ----------------- | ------------------------------------------------- | ---------------- | | subscriptionId | Ref<string \| null> | 当前订阅 ID | | isConnected | Ref<boolean> | 连接状态 | | lastMessage | Ref<any> | 最后收到的消息 | | send | (destination: string, payload?: any) => boolean | 手动发送消息函数 | | startAllSending | () => void | 启动所有定时发送 | | stopAllSending | () => void | 停止所有定时发送 | | unsubscribe | () => void | 取消订阅主题 |

TypeScript 支持

本包使用 TypeScript 编写，包含完整的类型定义：

import type { PayloadType, ConnectionStatus } from "@lejurobot/stomp-websocket";
import type {
  SendConfig,
  StompChannelOptions,
} from "@lejurobot/stomp-websocket";

许可证

MIT

贡献

欢迎贡献！请随时提交 Pull Request。