對象WebSocket

WebSocket 是一種基於TCP 協定的全雙工通訊協議，在瀏覽器和伺服器之間建立起一個不斷開的連接，可以實現即時雙向資料傳輸，並且可以支援任意格式的資料傳輸。在fibjs 中，WebSocket 支援模組提供了對應的API 接口，可以實現WebSocket 伺服器端和客戶端的開發

WebSocket 支援模組只是WebSocket 協定的實現，需要在HTTP 協定之上才能運作。在伺服器端，可以透過upgrade 函數將HTTP 請求轉換為WebSocket 連接，而在客戶端，則需要透過WebSocket 協定的URL 來指定需要連接的伺服器位址。

啟動WebSocket伺服器範例：

1
2
3
4
5
6
7
8
9
10
11
var ws = require('ws');
var http = require('http');

var svr = new http.Server(80, {
    '/ws': ws.upgrade(conn => {
        conn.onmessage = e => {
            conn.send('fibjs:' + e.data);
        };
    })
});
svr.start();

在客戶端中與上述伺服器建立連線的範例：

1
2
3
4
5
6
7
8
9
10
11
12
var ws = require("ws");

var conn = new ws.Socket("ws://127.0.0.1/ws");
// emit open event
conn.onopen = () => {
    console.log("websocket connected");
    conn.send("hi");
};
// emit close event
conn.onmessage = evt => {
    console.log("websocket receive: " + evt.data);
};

繼承關係

建構函數

WebSocket

WebSocket 建構函數

1
2
3
new WebSocket(String url,
    String protocol = "",
    String origin = "");

呼叫參數:

url: String, 指定連接的伺服器
protocol: String, 指定握手協議，預設為""
origin: String, 指定握手時模擬的來源，預設為""

WebSocket 建構函數

1
2
new WebSocket(String url,
    Object opts);

呼叫參數:

url: String, 指定連接的伺服器
opts: Object, 連結選項，預設是{}

opts 包含請求的附加選項，支援的內容如下：

1
2
3
4
5
6
7
8{
    "protocol": "", // specify the sub-protocol, default is ""
    "origin": "", // specify the origin, default is ""
    "perMessageDeflate": false, // specify whether to enable permessage-deflate, default is false
    "maxPayload": 67108864, // specify the max payload size, default is 64MB
    "httpClient": hc, // specify the http client, default is null, use the global http client
    "headers": // specify the http headers, default is {}
}

靜態屬性

defaultMaxListeners

Integer, 預設全域最大監聽器數

1
static Integer WebSocket.defaultMaxListeners;

成員屬性

url

String, 查詢目前物件連接的伺服器

1
readonly String WebSocket.url;

protocol

String, 查詢目前物件連線時的協定

1
readonly String WebSocket.protocol;

origin

String, 查詢目前物件連接的來源

1
readonly String WebSocket.origin;

readyState

Integer, 查詢目前物件的連線狀態，參見ws

1readonly Integer WebSocket.readyState;

onopen

Function, 查詢與綁定連線成功事件，相當於on("open", func);

1
Function WebSocket.onopen;

onmessage

Function, 查詢和綁定接受到對方訊息的事件，相當於on("message", func);

1
Function WebSocket.onmessage;

onclose

Function, 查詢和綁定連線關閉的事件，相當於on("close", func);

1
Function WebSocket.onclose;

onerror

Function, 查詢與綁定錯誤發生的事件，相當於on("error", func);

1
Function WebSocket.onerror;

成員函數

close

關閉目前連接，此操作會向對方發送CLOSE 封包，並等待對方回應

1
2
WebSocket.close(Integer code = 1000,
    String reason = "");

呼叫參數:

code: Integer, 指定關閉的代碼，允許值為3000-4999 或1000，預設值為1000
reason: String, 指定關閉的原因，預設為""

send

向對方發送一段文字

1
WebSocket.send(String data);

呼叫參數:

data: String, 指定傳送的文本

向對方發送一段二進位數據

1WebSocket.send(Buffer data);

呼叫參數:

data:Buffer, 指定發送的二進位數據

ref

維持fibjs 程序不退出，在物件綁定期間阻止fibjs 進程退出

1WebSocket WebSocket.ref();

回傳結果:

WebSocket, 傳回當前對象

unref

允許fibjs 進程退出，在物件綁定期間允許fibjs 進程退出

1WebSocket WebSocket.unref();

回傳結果:

WebSocket, 傳回當前對象

on

綁定一個事件處理函數到對象

1
2
Object WebSocket.on(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

綁定一個事件處理函數到對象

1
Object WebSocket.on(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱將作為事件名稱，屬性的值將作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

addListener

綁定一個事件處理函數到對象

1
2
Object WebSocket.addListener(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

綁定一個事件處理函數到對象

1
Object WebSocket.addListener(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱將作為事件名稱，屬性的值將作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

prependListener

綁定一個事件處理函數到物件起始

1
2
Object WebSocket.prependListener(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

綁定一個事件處理函數到物件起始

1
Object WebSocket.prependListener(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱將作為事件名稱，屬性的值將作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

once

綁定一個一次性事件處理函數到對象，一次性處理函數只會觸發一次

1
2
Object WebSocket.once(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

綁定一個一次性事件處理函數到對象，一次性處理函數只會觸發一次

1
Object WebSocket.once(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱將作為事件名稱，屬性的值將作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

prependOnceListener

綁定一個事件處理函數到物件起始

1
2
Object WebSocket.prependOnceListener(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

綁定一個事件處理函數到物件起始

1
Object WebSocket.prependOnceListener(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱將作為事件名稱，屬性的值將作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

off

從物件處理佇列中取消指定函數

1
2
Object WebSocket.off(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

取消物件處理佇列中的全部函數

1
Object WebSocket.off(String ev);

呼叫參數:

ev: String, 指定事件的名稱

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

從物件處理佇列中取消指定函數

1
Object WebSocket.off(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱作為事件名稱，屬性的值作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

removeListener

從物件處理佇列中取消指定函數

1
2
Object WebSocket.removeListener(String ev,
    Function func);

呼叫參數:

ev: String, 指定事件的名稱
func: Function, 指定事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

取消物件處理佇列中的全部函數

1
Object WebSocket.removeListener(String ev);

呼叫參數:

ev: String, 指定事件的名稱

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

從物件處理佇列中取消指定函數

1
Object WebSocket.removeListener(Object map);

呼叫參數:

map: Object, 指定事件映射關係，物件屬性名稱作為事件名稱，屬性的值作為事件處理函數

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

removeAllListeners

從物件處理佇列中取消所有事件的所有監聽器，如果指定事件，則移除指定事件的所有監聽器。

1
Object WebSocket.removeAllListeners(String ev);

呼叫參數:

ev: String, 指定事件的名稱

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

從物件處理佇列中取消所有事件的所有監聽器，如果指定事件，則移除指定事件的所有監聽器。

1
Object WebSocket.removeAllListeners(Array evs = []);

呼叫參數:

evs: Array, 指定事件的名稱

回傳結果:

Object, 傳回事件物件本身，便於鍊式調用

setMaxListeners

監聽器的預設限制的數量，僅用於相容

1WebSocket.setMaxListeners(Integer n);

呼叫參數:

n: Integer, 指定事件的數量

getMaxListeners

取得監聽器的預設限制的數量，僅用於相容

1Integer WebSocket.getMaxListeners();

回傳結果:

Integer, 回傳預設限制數量

listeners

查詢物件指定事件的監聽器陣列

1
Array WebSocket.listeners(String ev);

呼叫參數:

ev: String, 指定事件的名稱

回傳結果:

Array, 傳回指定事件的監聽器數組

listenerCount

查詢物件指定事件的監聽器數量

1
Integer WebSocket.listenerCount(String ev);

呼叫參數:

ev: String, 指定事件的名稱

回傳結果:

Integer, 傳回指定事件的監聽器數量

查詢物件指定事件的監聽器數量

1
2Integer WebSocket.listenerCount(Value o,
    String ev);

呼叫參數:

o: Value, 指定查詢的對象
ev: String, 指定事件的名稱

回傳結果:

Integer, 傳回指定事件的監聽器數量

eventNames

查詢監聽器事件名稱

1
Array WebSocket.eventNames();

回傳結果:

Array, 傳回事件名稱數組

emit

主動觸發一個事件

1
2
Boolean WebSocket.emit(String ev,
    ...args);

呼叫參數:

ev: String, 事件名稱
args: ..., 事件參數，將會傳遞給事件處理函數

回傳結果:

Boolean, 回傳事件觸發狀態，有回應事件回傳true，否則回傳false

toString

傳回物件的字串表示，一般回傳"[Native Object]"，物件可以根據自己的特性重新實現

1
String WebSocket.toString();

回傳結果:

String, 傳回物件的字串表示

toJSON

傳回物件的JSON 格式表示，一般傳回物件定義的可讀屬性集合

1
Value WebSocket.toJSON(String key = "");

呼叫參數:

key: String, 未使用

回傳結果:

Value, 傳回包含可JSON 序列化的值

開發指南

基礎模組

內建對象

社群模組

對象WebSocket

繼承關係

建構函數

WebSocket

靜態屬性

defaultMaxListeners

成員屬性

url

protocol

origin

readyState

onopen

onmessage

onclose

onerror

成員函數

close

send

ref

unref

on

addListener

prependListener

once

prependOnceListener

off

removeListener

removeAllListeners

setMaxListeners

getMaxListeners

listeners

listenerCount

eventNames

emit

toString

toJSON