在此页

• 句法
• 范例
• 规范
• 浏览器兼容性
• 另请参阅
• 相关话题

createDataChannel() method on the RTCPeerConnection interface creates a new channel linked with the remote peer, over which any kind of data may be transmitted. This can be useful for back-channel content such as images, file transfer, text chat, game update packets, and so forth.

If the new data channel is the first one added to the connection, renegotiation is started by delivering a negotiationneeded 事件。

句法

dataChannel = RTCPeerConnection.createDataChannel(label[, options]);
					

参数

label

A human-readable name for the channel. This string may not be longer than 65,535 bytes .

选项 可选

RTCDataChannelInit dictionary providing configuration options for the data channel

RTCDataChannelInit dictionary

RTCDataChannelInit dictionary provides the following fields, any of which may be included in the object passed as the options parameter in order to configure the data channel to suit your needs:

ordered 可选

Indicates whether or not messages sent on the RTCDataChannel are required to arrive at their destination in the same order in which they were sent ( true ), or if they're allowed to arrive out-of-order ( false ). 默认： true .

maxPacketLifeTime 可选

The maximum number of milliseconds that attempts to transfer a message may take in unreliable mode. While this value is a 16-bit unsigned number, each user agent may clamp it to whatever maximum it deems appropriate. 默认： null .

maxRetransmits 可选

The maximum number of times the user agent should attempt to retransmit a message which fails the first time in unreliable mode. While this value is a16-bit unsigned number, each user agent may clamp it to whatever maximum it deems appropriate. 默认： null .

协议 可选

The name of the sub-protocol being used on the RTCDataChannel , if any; otherwise, the empty string (""). Default: empty string, "" . This string may not be longer than 65,535 bytes .

negotiated 可选

By default ( false ), data channels are negotiated in-band, where one side calls createDataChannel , and the other side listens to the RTCDataChannelEvent event using the ondatachannel EventHandler . Alternatively ( true ), they can be negotiated out of-band, where both sides call createDataChannel with an agreed-upon id. 默认： false .

id 可选

An 16-bit numeric ID for the channel; permitted values are 0-65534. If you don't include this option, the user agent will select an ID for you.

The options which can be configured using the RTCDataChannelInit dictionary represent the script-settable subset of the properties on the RTCDataChannel 接口。

返回值

新的 RTCDataChannel 对象采用指定 label , configured using the options specified by 选项 if that parameter is included; otherwise, the defaults listed above are established.

异常

InvalidStateError

RTCPeerConnection is closed.

TypeError

This can happen in a couple of situations:

• The label and/or protocol string is too long; these cannot be longer than 65,535 bytes (bytes, rather than characters).
• id is 65535. While this is a valid unsigned 16-bit value, it's not a permitted value for id .

SyntaxError

Values were specified for both the maxPacketLifeTime and maxRetransmits options. You may only specify a non- null value for one of these.

ResourceInUse

An id was specified, but another RTCDataChannel is already using the same value.

OperationError

Either the specified id is already in use or, if no id was specified, the WebRTC layer was unable to automatically generate an ID because all IDs are in use.

范例

This example shows how to create a data channel and set up handlers for the open and message events to send and receive messages on it (For brievity, the example assumes onnegotiationneeded is set up).

// Offerer side
var pc = new RTCPeerConnection(options);
var channel = pc.createDataChannel("chat");
channel.onopen = function(event) {
  channel.send('Hi you!');
}
channel.onmessage = function(event) {
  console.log(event.data);
}
						

// Answerer side
var pc = new RTCPeerConnection(options);
pc.ondatachannel = function(event) {
  var channel = event.channel;
  channel.onopen = function(event) {
    channel.send('Hi back!');
  }
  channel.onmessage = function(event) {
    console.log(event.data);
  }
}
						

Alternatively, more symmetrical out-of-band negotiation can be used, using an agreed-upon id (0 here):

// Both sides
var pc = new RTCPeerConnection(options);
var channel = pc.createDataChannel("chat", {negotiated: true, id: 0});
channel.onopen = function(event) {
  channel.send('Hi!');
}
channel.onmessage = function(event) {
  console.log(event.data);
}
						

For a more thorough example showing how the connection and channel are established, see A simple RTCDataChannel sample .

规范

规范	状态	注释
WebRTC 1.0: Real-time Communication Between Browsers The definition of 'createDataChannel()' in that specification.	候选推荐	初始定义。

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	桌面						移动
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
createDataChannel	Chrome 25	Edge 79	Firefox 22	IE 不支持 No	Opera 43 注意事项 43 注意事项 Promise-based version. 37 — 43	Safari 11	WebView Android Yes	Chrome Android 25	Firefox Android 44	Opera Android 43 注意事项 43 注意事项 Promise-based version. 37 — 43	Safari iOS 11	Samsung Internet Android 6.0

图例

完整支持

完整支持

不支持

不支持

见实现注意事项。

另请参阅

• RTCDataChannel
• A simple RTCDataChannel sample
• RTCPeerConnection

元数据

• 最后修改： Jan 24, 2020

相关话题

1. WebRTC API
2. RTCPeerConnection
3. 构造函数

   1. RTCPeerConnection()
4. 特性

   1. canTrickleIceCandidates
   2. connectionState
   3. currentLocalDescription
   4. currentRemoteDescription
   5. getDefaultIceServers()
   6. iceConnectionState
   7. iceGatheringState
   8. localDescription
   9. onaddstream
   10. onconnectionstatechange
   11. ondatachannel
   12. onicecandidate
   13. oniceconnectionstatechange
   14. onicegatheringstatechange
   15. onidentityresult
   16. onidpassertionerror
   17. onidpvalidationerror
   18. onnegotiationneeded
   19. onpeeridentity
   20. onremovestream
   21. onsignalingstatechange
   22. ontrack
   23. peerIdentity
   24. pendingLocalDescription
   25. pendingRemoteDescription
   26. remoteDescription
   27. sctp
   28. signalingState
5. 方法

   1. addIceCandidate()
   2. addStream()
   3. addTrack()
   4. close()
   5. createAnswer()
   6. createDataChannel()
   7. createOffer()
   8. generateCertificate()
   9. getConfiguration()
   10. getIdentityAssertion()
   11. getReceivers()
   12. getSenders()
   13. getStats()
   14. getStreamById()
   15. getTransceivers()
   16. removeStream()
   17. removeTrack()
   18. restartIce()
   19. setConfiguration()
   20. setIdentityProvider()
   21. setLocalDescription()
   22. setRemoteDescription()
6. 事件

   1. addstream
   2. identityresult
   3. negotiationneeded
   4. removestream
   5. signalingstatechange
7. 继承：

   1. EventTarget
8. Related pages for WebRTC

   1. MediaDevices.getUserMedia()
   2. Navigator.mediaDevices
   3. RTCCertificate
   4. RTCDTMFSender
   5. RTCDTMFToneChangeEvent
   6. RTCDataChannel
   7. RTCDataChannelEvent
   8. RTCDtlsTransport
   9. RTCErrorEvent
   10. RTCIceCandidate
   11. RTCIceTransport
   12. RTCPeerConnectionIceErrorEvent
   13. RTCPeerConnectionIceEvent
   14. RTCRtpReceiver
   15. RTCRtpSender
   16. RTCRtpTransceiver
   17. RTCSctpTransport
   18. RTCSessionDescription
   19. RTCStatsEvent
   20. RTCStatsReport
   21. RTCTrackEvent