qingcheng-uni-signalr

qingcheng-uni-signalr 是基于官方 @microsoft/signalr 10.x JavaScript 客户端做的 uni-app 适配版本。

这个包尽量保持官方 JS API 的使用方式不变，只替换底层平台能力：

• HTTP 请求使用 uni.request
• WebSocket 连接使用 uni.connectSocket
• Hub 协议、HubConnectionBuilder、invoke、send、on、自动重连等能力继续复用官方客户端

支持范围

当前版本只实现了 WebSocket 传输：

• 支持 HttpTransportType.WebSockets
• 支持 negotiate，默认行为和官方客户端一致
• 支持 skipNegotiation: true
• 支持 accessTokenFactory
• 支持 headers
• 支持 JSON Hub Protocol
• 支持 connection.on
• 支持 connection.send
• 支持 connection.invoke
• 支持 withAutomaticReconnect

暂不支持：

• LongPolling 轮询
• ServerSentEvents / SSE
• MessagePack Hub Protocol
• SignalR streaming 相关 API
• 非 WebSocket 传输降级

如果服务端或运行环境不能使用 WebSocket，这个包不会自动降级到轮询或 SSE。

安装

适配包版本号和官方 SignalR JS 客户端版本号保持一致。

npm install [email protected] @microsoft/[email protected]

如果你是把 dist/index.js 复制到 uni-app 项目的 libs 目录中使用，也需要在 uni-app 项目里安装官方依赖：

npm install @microsoft/[email protected]

使用

import * as signalR from "qingcheng-uni-signalr";

const connection = new signalR.HubConnectionBuilder()
  .withUrl("https://example.com/chatHub", {
    accessTokenFactory: () => token,
  })
  .withAutomaticReconnect()
  .build();

connection.on("ReceiveMessage", (message) => {
  console.log(message);
});

await connection.start();

const result = await connection.invoke("SendMessage", "alice");
console.log(result);

如果是从本地 libs 引入：

import * as signalR from "../../libs/index.js";

和官方 API 的关系

官方 SignalR 客户端本身提供了平台注入点，例如：

• httpClient
• transport
• accessTokenFactory
• headers
• skipNegotiation

本包没有重写 Hub 协议层，而是在 HubConnectionBuilder.withUrl() 中自动注入 uni-app 适配：

new signalR.HubConnectionBuilder()
  .withUrl("https://example.com/chatHub")
  .build();

等价于手动指定 WebSocket 传输和 uni-app HTTP 客户端：

new signalR.HubConnectionBuilder()
  .withUrl("https://example.com/chatHub", {
    transport: signalR.HttpTransportType.WebSockets,
    httpClient: new signalR.UniHttpClient(),
  })
  .build();

注意事项

真机、小程序或模拟器调试时，不要使用 127.0.0.1 连接电脑上的服务端。127.0.0.1 指的是当前设备自身。请改用电脑的局域网 IP，例如：

.withUrl("http://192.168.1.20:7007/chat")

如果后端 Hub 方法没有返回值，invoke() 的返回值会是 undefined，这是官方 SignalR 的正常行为。