websocket-c v1.0.0-alpha.0
websocket-client(中文文档)
Summary
A lightweight js lib for websocket.
websocket-client is a lightweight Javascript library running in a browser environment. Essentially, its instance wrapped around the native WebSocket so that it can provide some commonly used logic(e.g. hearbeat detection). Give programs similar behaviour to native WebSocket while working to make them more robust. (e.g. registration event, readyState property, etc.) The following functions is provided for websocket-client:
- automatic reconnection when an exception closed.
- you can specify the number of automatic reconnections and the interval between connections when connect to the server failed.
- cache sent failed messages and send in cached order at 100 ms intervals when the websocket reconnects.
- hearbeat detection
- EventHub mechanism
Browser Compatibility
Browser versions:
- chrome >= 43
- firefox >= 19
- ie >= 10
- safari >= 10
- edge >= 12
- opera >= 30
- android >= 4.4
- ios >= 10
Install
npm
npm i websocket-client -S
or yarn
yarn add websocket-client
Usage
Use in the browser environment like:
<script src="./websocket-client.js"></script>
<script >
var socket = new WS.WebSocketClient('ws://xxx.com/api/ws', {
immediateReconnectTimeInterval: 2000,
heartbeatPeriod: 50000,
heartbeatMessage: 'ping'
});
</script>
es module:
import WebSocketClient from 'websocket-client'
// or
// import { WebSocketClient } from 'websocket-client'
const socket = new WebSocketClient('ws://xxx.com/api/ws', {
immediateReconnectTimeInterval: 2000,
heartbeatPeriod: 50000,
heartbeatMessage: 'ping'
})
socket.onopen = function() {
console.log('open')
}
socket.onmessage = function(e) {
console.log('message', e.data)
}
socket.onclose = function() {
console.log('close')
}
socket.onerror = function(e) {
console.error(e)
}
API
new WebSocketClient(url, options)
Arguments:
{string} url
The URL to which to connect.{object} options
see also options。
Usage:
Create a
WebSocketClient
instance and connect to server.
socketClient.close(code, reason)
Arguments:
{number} code
A numeric value indicating the status code explaining why the connection is being closed. Default:1005
{string} reason
A human-readable string explaining why the connection is closing. This string must be no longer than 123 bytes of UTF-8 text (not characters).
Usage:
Closes the
WebSocket
connection or connection attempt, if any. If the connection is alreadyCLOSED
, this method does nothing.Exceptions thrown
INVALID_ACCESS_ERR
An invalidcode
was specified.SYNTAX_ERR
Thereason
string is too long or contains unpaired surrogates.
socketClient.send(data)
Arguments:
{string | Blob | ArrayBuffer | ArrayBufferView | Object} data
Usage:
Enqueues the specified data to be transmitted to the server over the WebSocket connection, increasing the value of
bufferedAmount
by the number of bytes needed to contain the data. If the data can't be sent (for example, because it needs to be buffered but the buffer is full), the socket is closed automatically.Tips: if
data
is a plain object, it will be converted toJSON
before sending.Example:
var data = { username: 'jhail', age: 18}
socketClient.send(data) // the same as socketClient.send('{"username":"jhail","age":18}')
socketClient.on( event, callback )
Arguments:
- {string | Array} event
{Function} callback
Usage:
Listen for a custom event on the current instance(
socketClient
). Events can be triggered bysocketClient.trigger
. The callback will receive all the additional arguments passed into these event-triggering methods.By default, when a message is received, the socketClient automatically triggers events corresponding to
message
property values in the received data.See also options[message].
Example:
socketClient.on('message', function(msg) {
console.log(msg)
})
socketClient.trigger('message', 'Hi')
// "Hi"
socketClient.trigger('message', 'Hi')
// "Hi"
socketClient.once( event, callback )
Arguments:
- {string} event
{Function} callback
Usage:
Listen for a custom event, but only once. The listener will be removed once it triggers for the first time.
Example:
socketClient.once('once', function(msg) {
console.log(msg)
})
socketClient.trigger('once', 'Hi')
// "Hi"
socketClient.trigger('once', 'Hi') // If triggered again, no more output "Hi".
socketClient.off( event, callback )
Arguments:
- {string | Array} event
{Function} callback
Usage:
Remove custom event listener(s).
- If no arguments are provided, remove all event listeners;
- If only the event is provided, remove all listeners for that event;
- If both event and callback are given, remove the listener for that specific callback only.
socketClient.trigger( eventName, …args )
Arguments:
- {string} eventName
Usage:
Trigger an event on the current instance. Any additional arguments will be passed into the listener’s callback function.
Example:
socketClient.on('messages', function(a, b) {
console.log(a + b)
})
socketClient.trigger('messages', 'Hello ', 'World')
// "Hello World"
options
Attribute | Type | Default | Description |
---|---|---|---|
connectImmediately | boolean | true | sometimes we don't need to start connecting to the server immediately when we create WebSocketClient instances. When set to false , you can establish connections through socketClient.createWebSocket() when needed . |
enableDefaultEventHandler | boolean | true | whether to enable the default event handler function. Default event handling functions are designed to provide heartbeat detection, automatic reconnection when an exception closed, etc. The default event handler function do not affect the onopen 、onmessage 、onclose 、onerror of these events you register. |
connectLogSilent | boolean | false | connection-related logs. |
eventLogSilent | boolean | false | logs when onopen 、onclose 、onerror event is triggered. |
maxReconnectTimes | number | 3 | the number of attempts to reconnect when the connection fails. |
reconnectTimeInterval | number | 30000 | the time interval before trying to reconnect when the connection fails. |
immediateReconnectTimeInterval | number | 2000 | the time interval for trying to reconnect when the connection is abnormally closed. |
enableMessageCache | boolean | false | whether to enable the message cache mechanism. when set to true , it will be cache all sent failed messages and send in cached order at intervals of 100 ms when the websocket reconnects. |
message | string | 'message' | specify which key of message object is used as the message type. |
heartbeatPeriod | number | 50000 | cycle of heartbeat detection. In milliseconds |
heartbeatMessage | string | object | Blob | ArrayBuffer | ArrayBufferView | "ping" | the message of heartbeat detection. |
heartbeatLogSilent | boolean | false | time log of heartbeat detection. |
EventHub
EventHub is designed to provide users with a more convenient and flexible way to handle received messages. For this purpose, an EventHub API is provided for users to import independently.
Demo
// util.js
import { EventHub } from 'websocket-client'
export const eventHub = new EventHub()
// somewhere.js
import { eventHub } from 'util.js'
eventHub.on('message', ( param ) => {
console.log(param)
})
// websocket.js
import WebSocketClient from 'websocket-client'
import { eventHub } from 'util'
const socket = new WebSocketClient('ws://xxx.com/api/ws', {
immediateReconnectTimeInterval: 2000,
heartbeatPeriod: 50000,
heartbeatMessage: 'ping'
})
socket.onmessage = function(e) {
const data = e.data
eventHub.trigger(data.message, data)
}
EventHub API
eventHub.on(event, callback)
See also socketClient.on( event, callback )
eventHub.once( event, callback )
See also socketClient.once( event, callback )
eventHub.off( event, callback )
See also socketClient.off( [event, callback] )