RTCPeerConnection: createDataChannel() 方法

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。

一个新的 RTCDataChannel 对象，其 label 为指定值，并使用 options 指定的选项配置（如果包含该参数）；否则，将使用上述默认值。

InvalidStateError DOMException

如果 RTCPeerConnection 已关闭，则抛出此异常。

TypeError

在以下情况下抛出此异常

• 标签和/或协议字符串太长；它们不能超过 65,535 字节（字节，而不是字符）。
• id 为 65535。虽然这是一个有效的 16 位无符号值，但它不是 id 的允许值。

SyntaxError DOMException

如果为 maxPacketLifeTime 和 maxRetransmits 选项都指定了值，则抛出此异常。您只能为其中一个指定非 null 值。

ResourceInUse DOMException

如果指定了 id，但另一个 RTCDataChannel 已经在使用相同的值，则抛出此异常。

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