RTCPeerConnection：createDataChannel() 方法

語法

createDataChannel(label)
createDataChannel(label, options)

引數

label

通道的人類可讀名稱。此字串的長度不得超過 65,535 位元組。

options 可選

一個提供資料通道配置選項的物件。它可以包含以下欄位：

ordered 可選

指示在 RTCDataChannel 上傳送的訊息是否必須以傳送時的相同順序到達目的地（true），或者是否允許它們亂序到達（false）。預設值：true。

maxPacketLifeTime 可選

在不可靠模式下，嘗試傳輸訊息可能需要的最長毫秒數。雖然此值是一個 16 位無符號數字，但每個使用者代理都可以將其限制為它認為合適的任何最大值。預設值：null。

maxRetransmits 可選

在不可靠模式下，使用者代理應嘗試重新傳輸第一次失敗的訊息的最大次數。雖然此值是一個 16 位無符號數字，但每個使用者代理都可以將其限制為它認為合適的任何最大值。預設值：null。

protocol 可選

在 RTCDataChannel 上使用的子協議的名稱，如果有的話；否則，為空字串（""）。預設值：空字串（""）。此字串的長度不得超過 65,535 位元組。

negotiated 可選

預設情況下（false），資料通道是在帶內協商的，即一方呼叫 createDataChannel，而另一方使用 ondatachannel 事件處理程式偵聽 RTCDataChannelEvent 事件。或者（true），它們也可以在帶外協商，即雙方都使用約定的 ID 呼叫 createDataChannel。預設值：false。

id 可選

通道的 16 位數字 ID；允許的值為 0 到 65534。如果未包含此選項，使用者代理將為您選擇一個 ID。

返回值

一個具有指定 label 的新 RTCDataChannel 物件，如果提供了 options 引數，則使用指定的選項進行配置；否則，將建立上面列出的預設值。

異常

InvalidStateError DOMException

如果 RTCPeerConnection 已關閉，則丟擲此異常。

TypeError

在以下情況下會丟擲異常：

• 標籤和/或協議字串太長；它們的長度不能超過 65,535 位元組（位元組，而不是字元）。
• id 為 65535。雖然這是一個有效的 16 位無符號值，但它不是 id 的允許值。

SyntaxError DOMException

如果同時為 maxPacketLifeTime 和 maxRetransmits 選項指定了值，則會丟擲此異常。您只能為其中一個指定非 null 值。

ResourceInUse DOMException

如果指定了 id，但另一個 RTCDataChannel 已經在使用相同的 ID，則會丟擲此異常。

OperationError DOMException

如果指定的 id 已在使用中，或者未指定 id 但 WebRTC 層因所有 ID 都已被使用而無法自動生成 ID，則會丟擲此異常。

示例

此示例演示瞭如何建立資料通道並設定 open 和 message 事件的處理程式，以便在其上傳送和接收訊息（為簡潔起見，示例假定已設定 onnegotiationneeded）。

// Offerer side

const pc = new RTCPeerConnection(options);
const channel = pc.createDataChannel("chat");
channel.onopen = (event) => {
  channel.send("Hi you!");
};
channel.onmessage = (event) => {
  console.log(event.data);
};

// Answerer side

const pc = new RTCPeerConnection(options);
pc.ondatachannel = (event) => {
  const channel = event.channel;
  channel.onopen = (event) => {
    channel.send("Hi back!");
  };
  channel.onmessage = (event) => {
    console.log(event.data);
  };
};

或者，可以使用更對稱的帶外協商，使用約定的 ID（此處為 0）

// Both sides

const pc = new RTCPeerConnection(options);
const channel = pc.createDataChannel("chat", { negotiated: true, id: 0 });
channel.onopen = (event) => {
  channel.send("Hi!");
};
channel.onmessage = (event) => {
  console.log(event.data);
};

有關展示連線和通道如何建立的更全面的示例，請參閱 簡單的 RTCDataChannel 示例。

規範

瀏覽器相容性

另見

• RTCDataChannel
• 一個簡單的 RTCDataChannel 示例
• RTCPeerConnection