大网数据广告活动
Web 标准与前端开发

RTCPeerConnection:createDataChannel() 方法

· 52CE 我爱测

RTCPeerConnection 接口的 **`createDataChannel()`** 方法创建一个与远程对等方关联的新通道,可通过该通道传输任意类型的数据。这适用于辅助通道内容,例如图像、文件传输、文字聊天、游戏更新数据包等。

WebRTC

RTCPeerConnection 接口的 createDataChannel() 方法创建一个与远程对等方关联的新通道,可通过该通道传输任意类型的数据。这适用于辅助通道内容,例如图像、文件传输、文字聊天、游戏更新数据包等。

如果新的数据通道是添加到该连接的第一个数据通道,则会通过派发 RTCPeerConnection/negotiationneeded_event 事件启动重新协商。

语法

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,另一方通过 RTCPeerConnection.datachannel_event 事件处理器监听 RTCDataChannelEvent 事件。或者(true),也可以在带外协商:双方使用事先约定的 ID 调用 createDataChannel。默认值:false。
      • id
        • : 通道的 16 位数字 ID;允许的值为 0 到 65534。如果不包含此选项,用户代理将为你选择一个 ID。

[!NOTE] 这些选项表示 RTCDataChannel 接口上可由脚本设置的属性子集。

返回值

一个新的 RTCDataChannel 对象,具有指定的 label;若包含了 options 参数,则按其中指定的选项进行配置,否则使用上文列出的默认值。

异常

  • InvalidStateError DOMException
    • : 如果 RTCPeerConnection 已关闭则抛出。
  • TypeError
    • : 在以下情况抛出:
      • label 和/或 protocol 字符串过长;它们不得超过 65,535 字节(是字节,而不是字符)。
      • id 为 65535。虽然这是有效的无符号 16 位值,但不是 id 的允许值。
  • SyntaxError DOMException
    • : 如果同时为 maxPacketLifeTime 和 maxRetransmits 选项指定了值则抛出。这两个选项中你只能为其中一个指定非 null 值。
  • ResourceInUse DOMException
    • : 如果指定了 id,但另一个 RTCDataChannel 已在使用相同的值则抛出。
  • OperationError DOMException
    • : 如果指定的 id 已在使用,或者未指定 id 但 WebRTC 层因所有 ID 均已被占用而无法自动生成 ID,则抛出。

示例

本示例展示如何创建数据通道,并为 RTCDataChannel/open_event 和 RTCDataChannel/message_event 事件设置处理器,以便在其上发送和接收消息(为简洁起见,示例假定已设置 onnegotiationneeded)。

// 提议方

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

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)进行更对称的带外协商:

// 双方

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 简单示例。

规范

浏览器兼容性

参见

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。