WebSocket

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨2015年7月⁩.

* Some parts of this feature may have varying levels of support.

實驗性質: 這是一個實驗中的功能
此功能在某些瀏覽器尚在開發中，請參考兼容表格以得到不同瀏覽器用的前輟。

WebSocket 物件提供了建立、管理 WebSocket 伺服器連線的 API，它也有在連線中傳送、接收資料的能力。

方法一覽

`void close(in optional unsigned long code, in optional DOMString reason);`
`void send(in DOMString data);`

屬性	形態	描述
`binaryType`	`DOMString`	表示連線傳輸的二進制資料形態的字串，若使用 `Blob` 物件則為 "blob"，使用 `ArrayBuffer` 物件則為 "arraybuffer"。
`bufferedAmount`	`unsigned long`	呼叫 `send()` 隊列但尚未傳輸至網路上資料的位元數。連線關閉時此值不會重設為零。連續呼叫 `send()` 會讓此值不斷上升。唯讀
`extensions`	`DOMString`	伺服器選擇的擴展。目前僅有空字串或表示資料經過壓縮的 "deflate-stream"。唯讀
`onclose`	`EventListener`	當 WebSocket 連線的 `readyState` 切換至 `CLOSED` 時呼叫的事件監聽器。監聽器接收命名為 "close" 的 `CloseEvent`。
`onerror`	`EventListener`	當錯誤發生時呼叫的事件監聽器。事件為命名 "error" 的簡單事件。
`onmessage`	`EventListener`	當瀏覽器接收伺服器的訊息時呼叫的事件監聽器。監聽器接收命名為 "message" 的 `MessageEvent`。
`onopen`	`EventListener`	當 WebSocket 連線的 `readyState` 切換至 `OPEN` 時呼叫的事件監聽器，表示連線已準備傳送、接收資料。事件為命名 "open" 的簡單事件。
`protocol`	`DOMString`	伺服器選擇的子協定，這是建立 WebSocket 物件時 `protocols` 參數裡的其中一個字串。
`readyState`	`unsigned short`	連線的目前狀態，是就緒狀態常數的其中一個。唯讀
`url`	`DOMString`	建構方法解析出來的 URL，總是絕對 URL。唯讀

readyState 屬性使用以下常數描述 WebSocket 的連線狀態。

關閉 WebSocket 連線／連線嘗試，若連線已為 CLOSED，此方法沒有作用。

void close(
  in optional unsigned short code,
  in optional DOMString reason
);

code 選擇性: 表示狀態代碼，狀態代碼用以解釋連線關閉的原因。若未指定參數，預設值為 1000（表示正常的「事務完結（transaction complete）」關閉）。請參考 CloseEvent 頁面的狀態代碼列表，有所有的合法值。
reason 選擇性: 解釋連線關閉原因的人類可讀字串，字串必不可大於 123 個 UTF-8 字符。

透過 WebSocket 連線傳輸資料至伺服器。

void send(
  in DOMString data
);

void send(
  in ArrayBuffer data
);

void send(
  in Blob data
);

備註： Gecko send() 方法的實作與 Gecko 6.0 的規範有差別。Gecko 回傳一個 boolean 以表示連線是否仍處於開啟狀態（且資料成功隊列／傳輸）。另外，此時此刻，Gecko 不支援 ArrayBuffer 或 Blob 作為資料形態。

This page was last modified on ⁨2024年12月20日⁩ by MDN contributors.