sockjs-client API完全指南：事件、方法与配置全解析
项目地址: https://gitcode.com/gh_mirrors/so/sockjs-client SockJS-client是一个浏览器端JavaScript库，它提供了类似WebSocket的对象，旨在创建低延迟、全双工、跨域的浏览器与Web服务器通信通道。本文将详细解析SockJS-client的API，包括事件、方法与配置选项，帮助开发者更好地使用该库。
快速入门
使用SockJS-client非常简单，首先需要加载库文件。推荐使用国内CDN地址以确保访问速度和稳定性：
<script src="https://cdn.jsdelivr.net/npm/sockjs-client@1/dist/sockjs.min.js"></script>
然后创建SockJS实例并建立连接：
var sock = new SockJS('https://mydomain.com/my_prefix');
sock.onopen = function() {
console.log('连接已建立');
sock.send('Hello SockJS!');
};
sock.onmessage = function(e) {
console.log('收到消息:', e.data);
};
sock.onclose = function() {
console.log('连接已关闭');
};
SockJS类详解
SockJS类是整个库的核心，其构造函数定义如下：
var sockjs = new SockJS(url, _reserved, options);
参数说明
- url：服务器连接地址，可以包含查询字符串。
- _reserved：保留参数，目前未使用。
- options：配置选项对象，详细说明见下文。
配置选项
options是一个对象，可包含以下属性：
- server (string)：附加到URL的字符串，用于实际数据连接，默认为随机4位数字。
- transports (string | array)：指定允许使用的传输方式，默认使用所有可用传输方式。
- sessionId (number | function)：会话ID生成方式。如果是数字，则生成指定长度的随机字符串；如果是函数，则使用函数返回值作为会话ID。默认生成8位随机字符串。
- timeout (number)：传输连接的最小超时时间（毫秒），默认根据RTT动态计算。
事件系统
SockJS-client的事件系统基于lib/event/emitter.js实现，提供了丰富的事件接口。
核心事件
SockJS实例支持以下核心事件：
-
open：连接建立时触发。
sock.onopen = function() { console.log('连接已建立'); }; -
message：收到消息时触发，事件对象包含data属性。
sock.onmessage = function(e) { console.log('收到消息:', e.data); }; -
close：连接关闭时触发，可选参数code和reason。
sock.onclose = function(code, reason) { console.log('连接关闭，代码:', code, '原因:', reason); }; -
error：发生错误时触发。
sock.onerror = function(error) { console.error('发生错误:', error); };
事件方法
SockJS实例提供以下事件相关方法：
- on(event, listener)：添加事件监听器。
- once(event, listener)：添加一次性事件监听器。
- off(event, listener)：移除事件监听器。
- removeAllListeners([event])：移除所有监听器，或指定事件的所有监听器。
核心方法
SockJS实例提供以下核心方法：
send(data)
发送数据到服务器，data参数为要发送的数据。
sock.send('Hello, Server!');
close()
关闭连接。
sock.close();
传输方式
SockJS-client支持多种传输方式，会根据浏览器环境自动选择最佳方式。传输方式定义在lib/transport/目录下，主要包括：
流传输（Streaming）
- websocket：基于WebSocket协议的传输方式，定义在lib/transport/websocket.js。
- xhr-streaming：基于XHR的流传输，定义在lib/transport/xhr-streaming.js。
- xdr-streaming：基于XDomainRequest的流传输，用于IE8+。
- eventsource：基于EventSource的流传输。
轮询传输（Polling）
- xhr-polling：基于XHR的轮询传输。
- xdr-polling：基于XDomainRequest的轮询传输。
- jsonp-polling：基于JSONP的轮询传输，兼容性最好但性能较差。
传输选择逻辑
传输方式的选择逻辑在lib/transport-list.js中定义，默认顺序如下：
module.exports = [
// 流传输
require('./transport/websocket')
, require('./transport/xhr-streaming')
, require('./transport/xdr-streaming')
, require('./transport/eventsource')
, require('./transport/lib/iframe-wrap')(require('./transport/eventsource'))
// 轮询传输
, require('./transport/htmlfile')
, require('./transport/lib/iframe-wrap')(require('./transport/htmlfile'))
, require('./transport/xhr-polling')
, require('./transport/xdr-polling')
, require('./transport/lib/iframe-wrap')(require('./transport/xhr-polling'))
, require('./transport/jsonp-polling')
];
可以通过transports选项指定允许的传输方式：
var sock = new SockJS(url, null, {transports: ['websocket', 'xhr-streaming']});
浏览器兼容性
SockJS-client支持多种浏览器，不同浏览器支持的传输方式有所不同。
主要浏览器支持情况
| 浏览器 | WebSocket | 流传输 | 轮询传输 |
|---|---|---|---|
| IE 6/7 | 不支持 | 不支持 | jsonp-polling |
| IE 8/9 | 不支持 | xdr-streaming | xdr-polling |
| IE 10+ | 支持 | xhr-streaming | xhr-polling |
| Chrome | 支持 | xhr-streaming | xhr-polling |
| Firefox | 支持 | xhr-streaming | xhr-polling |
| Safari | 支持 | xhr-streaming | xhr-polling |
| Opera | 支持 | xhr-streaming | xhr-polling |
特殊环境支持
当HTML从file://协议加载时（如开发环境或PhoneGap应用），传输方式会有所调整：
| 浏览器 | WebSocket | 流传输 | 轮询传输 |
|---|---|---|---|
| IE 8/9 | 同上 | iframe-htmlfile | iframe-xhr-polling |
| 其他浏览器 | 同上 | iframe-eventsource | iframe-xhr-polling |
实际应用示例
基本聊天应用
以下是一个简单的聊天应用示例，展示了SockJS-client的基本用法：
// 创建SockJS实例
var chatSocket = new SockJS('/chat');
// 连接建立时发送用户信息
chatSocket.onopen = function() {
var userInfo = {
username: document.getElementById('username').value
};
chatSocket.send(JSON.stringify({
type: 'login',
data: userInfo
}));
};
// 处理收到的消息
chatSocket.onmessage = function(e) {
var message = JSON.parse(e.data);
var chatLog = document.getElementById('chat-log');
switch(message.type) {
case 'message':
chatLog.innerHTML += '<div class="message"><strong>' + message.from + '</strong>: ' + message.content + '</div>';
break;
case 'system':
chatLog.innerHTML += '<div class="system">' + message.content + '</div>';
break;
}
// 滚动到底部
chatLog.scrollTop = chatLog.scrollHeight;
};
// 发送聊天消息
document.getElementById('send-button').addEventListener('click', function() {
var messageInput = document.getElementById('message-input');
var content = messageInput.value.trim();
if (content) {
chatSocket.send(JSON.stringify({
type: 'message',
content: content
}));
messageInput.value = '';
}
});
// 页面关闭时关闭连接
window.addEventListener('beforeunload', function() {
chatSocket.close();
});
配置传输方式和超时
以下示例展示了如何配置传输方式和超时时间：
var options = {
// 只允许WebSocket和XHR流传输
transports: ['websocket', 'xhr-streaming'],
// 设置最小超时时间为5秒
timeout: 5000,
// 自定义会话ID生成函数
sessionId: function() {
// 生成10位随机字母数字字符串
return Math.random().toString(36).substr(2, 10);
}
};
var customSocket = new SockJS('/custom-endpoint', null, options);
customSocket.onopen = function() {
console.log('自定义配置的连接已建立');
};
调试与测试
SockJS-client提供了完善的调试和测试支持，相关代码位于tests/目录。
本地测试
可以通过以下命令运行本地测试：
git clone https://gitcode.com/gh_mirrors/so/sockjs-client
cd sockjs-client
npm install
npm run test:browser_local
这将启动Karma测试运行器和测试支持服务器，可在浏览器中查看测试结果。
调试输出
在开发环境中，可以通过设置NODE_ENV环境变量启用调试输出：
NODE_ENV=development node your-app.js
调试日志会显示各种传输方式的选择过程、连接状态变化等信息，有助于问题诊断。
部署最佳实践
CDN使用
推荐使用国内CDN加载SockJS-client，以确保访问速度和稳定性：
<script src="https://cdn.jsdelivr.net/npm/sockjs-client@1/dist/sockjs.min.js"></script>
版本选择
应根据服务器端SockJS版本选择兼容的客户端版本，以确保协议一致性。
连接管理
- 避免在同一域名下创建多个SockJS连接，因为浏览器对同一域名的并发连接数有限制。
- 如确需多个连接，可使用不同子域名。
- 在页面卸载前主动关闭连接，避免资源泄漏。
window.addEventListener('beforeunload', function() {
if (sock && sock.readyState !== 3) {
sock.close();
}
});
总结
SockJS-client提供了一个强大而灵活的API，使开发者能够轻松实现跨浏览器、低延迟的双向通信。通过本文的介绍，您应该已经了解了SockJS-client的核心API、事件系统、传输方式选择以及实际应用技巧。
无论是构建实时聊天应用、实时数据仪表盘还是在线协作工具，SockJS-client都是一个值得考虑的优秀选择。更多详细信息可以参考项目的README.md和源代码。
SockJS-client的自动化测试由BrowserStack提供支持，确保在各种浏览器环境中的兼容性。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
