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