RTCDataChannel
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
RTCDataChannel 接口代表在两者之间建立了一个双向数据通道的连接。
可以用 RTCDataChannel.createDataChannel()
或者在现有的 RTCPeerConnection
上用 RTCDataChannelEvent
类型的 datachannel
事件接收,创建出 RTCDataChannel 类型的对象。
备注:这个 API 在 Gecko 中被称作 DataChannel 而不是标准的'RTCDataChannel'。
属性
RTCDataChannel.label
只读-
返回一个包含有描述数据通道名字的
DOMString
。这个字段没有唯一性要求。 RTCDataChannel.ordered
只读-
返回一个
Boolean
对象,表示传递信息的顺序是否有保证。 RTCDataChannel.protocol
只读-
返回一个包含有正在使用的子协议的名称的
DOMString
,如果没有这样的子协议,返回"" RTCDataChannel.id
只读-
当
RTCDataChannel
对象被创建出来的时候,返回一个无符号 short 类型的数据,作为通道的标识 id。 RTCDataChannel.readyState
只读-
返回枚举类型的 RTCDataChannelState,表示数据连接的状态,有以下几种类型:
"connecting"
该状态表示底层链路还未建立和激活,该状态还是由RTCPeerConnection.createDataChannel()
生成的 datachannel 初始状态。"open"
该状态表示底层链路已经连接成功并且运行。这个状态还是由RTCDataChannelEvent
分发的 datachannel 的初始状态。"closing"
该状态表示底层链路已经在关闭的过程中。该状态下将不会接受新的发送任务,但是缓冲队列中的消息还是会被继续发送或者接收。"closed"
该状态表示底层链路已经完全被关闭(或者无法处于 established 状态)。
RTCDataChannel.bufferedAmount
只读-
返回一个
unsigned long
,表示缓冲队列中等待发送的字节数。这些数据是通过RTCDataChannel.send()
添加进缓冲队列但还未被发送的数据请求。注意:就算 channel 处于closed
状态,队列中的缓存还会保持。 RTCDataChannel.binaryType
-
是一个
DOMString
类型,表示由链路发送的二进制数据的类型。该项的值应该为"blob"
或者"arraybuffer"
,默认值为"blob"
。当值为"blob"
的时候,使用Blob
对象,当值为"arraybuffer"
时,使用ArrayBuffer
对象 RTCDataChannel.maxPacketLifeType
只读-
是一个
unsigned short
类型,表示不可靠模式下的消息发送允许时间长度,单位为毫秒。 RTCDataChannel.maxRetransmits
只读-
是一个
unsigned short
类型,表示不可靠模式下消息允许尝试重发的最大次数。 RTCDataChannel.negotiated
只读-
是一个
Boolean
类型,表示这个 channel 是否已经通过应用协商。 DataChannel.reliable
非标准 只读-
是一个
Boolean
类型,表示这个链接能不能以非可靠模式发送消息。已经废弃的 api。 DataChannel.stream
非标准 只读-
和
RTCDataChannel.id
等效,已经废弃的 api。
事件处理器
RTCDataChannel.onopen
-
当接收到
open
事件时的事件处理器,当底层链路数据传输成功,端口状态处于 established 的时候会触发该事件。 RTCDataChannel.onmessage
-
当接收到
message
事件时的事件处理器。当有数据被接收的时候会触发该事件。 RTCDataChannel.onclose
-
当接收到
close
事件时候的事件处理器。当底层链路被关闭的时候会触发该事件。 RTCDataChannel.onerror
-
当接收到
error
事件时候的事件处理器。当遇到错误的时候会触发该事件。
方法
RTCDataChannel.close()
-
关闭 channel 的方法。这个关闭动作不是直接生效的。这个方法会将 channel 的
state
属性设置为"closing"
状态,在消息队列中的消息全部发送完毕之后,channel 才会被关闭。 RTCDataChannel.send()
-
将参数中的数据通过 channel 发送。这个数据可以是
DOMString
,Blob
,ArrayBuffer
或者是ArrayBufferView
类型。
示例
var pc = new RTCPeerConnection();
var dc = pc.createDataChannel("my channel");
dc.onmessage = function (event) {
console.log("received: " + event.data);
};
dc.onopen = function () {
console.log("datachannel open");
};
dc.onclose = function () {
console.log("datachannel close");
};
规范
Specification |
---|
WebRTC: Real-Time Communication in Browsers # rtcdatachannel |
浏览器兼容性
BCD tables only load in the browser