---
title: RTCDataChannel
slug: Web/API/RTCDataChannel
translation_of: Web/API/RTCDataChannel
---
<p>{{APIRef("WebRTC")}}{{SeeCompatTable}}</p>

<p>RTCDataChannel接口代表在两者之间建立了一个双向数据通道的连接。</p>

<p>可以用{{domxref("RTCDataChannel.createDataChannel()")}}或者在现有的 {{domxref("RTCPeerConnection")}}上用 {{domxref("RTCDataChannelEvent")}}类型的 {{event("datachannel")}} 事件接收，创建出 RTCDataChannel类型的对象。</p>

<div class="note">
<p>这个API在Gecko中被称作DataChannel而不是标准的'RTCDataChannel'。</p>
</div>

<h2 id="属性">属性</h2>

<dl>
 <dt>{{domxref("RTCDataChannel.label")}} {{readOnlyInline}}</dt>
 <dd>返回一个包含有描述数据通道名字的{{domxref("DOMString")}}。这个字段没有唯一性要求。</dd>
 <dt>{{domxref("RTCDataChannel.ordered")}} {{readOnlyInline}}</dt>
 <dd>返回一个{{domxref("Boolean")}}对象，表示传递信息的顺序是否有保证。</dd>
 <dt>{{domxref("RTCDataChannel.protocol")}} {{readOnlyInline}}</dt>
 <dd>返回一个包含有正在使用的子协议的名称的 {{Domxref("DOMString")}}，如果没有这样的子协议，返回""</dd>
 <dt>{{domxref("RTCDataChannel.id")}} {{readOnlyInline}}</dt>
 <dd>当{{domxref("RTCDataChannel")}}对象被创建出来的时候，返回一个无符号short类型的数据，作为通道的标识id。</dd>
 <dt>{{domxref("RTCDataChannel.readyState")}} {{readOnlyInline}}</dt>
 <dd>返回枚举类型的 RTCDataChannelState，表示数据连接的状态，有以下几种类型：
 <ul>
  <li><code>"connecting"</code> 该状态表示底层链路还未建立和激活，该状态还是由{{domxref("RTCPeerConnection.createDataChannel()")}}生成的datachannel初始状态。</li>
  <li><code>"open"</code> 该状态表示底层链路已经连接成功并且运行。这个状态还是由{{domxref("RTCDataChannelEvent")}}分发的datachannel的初始状态。 </li>
  <li><code>"closing"</code> 该状态表示底层链路已经在关闭的过程中。该状态下将不会接受新的发送任务，但是缓冲队列中的消息还是会被继续发送或者接收。</li>
  <li><code>"closed"</code> 该状态表示底层链路已经完全被关闭（或者无法处于established状态）。</li>
 </ul>
 </dd>
 <dt>{{domxref("RTCDataChannel.bufferedAmount")}} {{readOnlyInline}}</dt>
 <dd>
 <p>返回一个<code>unsigned long</code>，表示缓冲队列中等待发送的字节数。这些数据是通过{{domxref("RTCDataChannel.send()")}}添加进缓冲队列但还未被发送的数据请求。注意：就算channel处于<code>closed</code>状态，队列中的缓存还会保持。</p>
 </dd>
 <dt>{{domxref("RTCDataChannel.binaryType")}}</dt>
 <dd>
 <p>是一个{{domxref("DOMString")}} 类型，表示由链路发送的二进制数据的类型。该项的值应该为<code>"blob"</code>或者<code>"arraybuffer"</code>，默认值为<code>"blob"</code>。当值为<code>"blob"</code>的时候，使用{{domxref("Blob")}}对象，当值为<code>"arraybuffer"</code>时，使用{{domxref("ArrayBuffer")}}对象</p>
 </dd>
 <dt>{{domxref("RTCDataChannel.maxPacketLifeType")}} {{readOnlyInline}}</dt>
 <dd>是一个<code>unsigned short</code>类型，表示不可靠模式下的消息发送允许时间长度，单位为毫秒。</dd>
 <dt>{{domxref("RTCDataChannel.maxRetransmits")}} {{readOnlyInline}}</dt>
 <dd>是一个<code>unsigned short</code>类型，表示不可靠模式下消息允许尝试重发的最大次数。</dd>
 <dt>{{domxref("RTCDataChannel.negotiated")}} {{readOnlyInline}}</dt>
 <dd>是一个{{domxref("Boolean")}}类型，表示这个channel是否已经通过应用协商。</dd>
 <dt>{{domxref("DataChannel.reliable")}} {{non-standard_inline}} {{readOnlyInline}}</dt>
 <dd>是一个{{domxref("Boolean")}}类型，表示这个链接能不能以非可靠模式发送消息。已经废弃的api。</dd>
 <dt>{{domxref("DataChannel.stream")}} {{non-standard_inline}} {{readOnlyInline}}</dt>
 <dd>和{{domxref("RTCDataChannel.id")}}等效，已经废弃的api。</dd>
</dl>

<h3 id="事件处理器">事件处理器</h3>

<dl>
 <dt>{{domxref("RTCDataChannel.onopen")}}</dt>
 <dd>当接收到{{event("open")}} 事件时的事件处理器，当底层链路数据传输成功，端口状态处于established的时候会触发该事件。</dd>
 <dt>{{domxref("RTCDataChannel.onmessage")}}</dt>
 <dd>当接收到{{event("message")}}事件时的事件处理器。当有数据被接收的时候会触发该事件。</dd>
 <dt>{{domxref("RTCDataChannel.onclose")}}</dt>
 <dd>当接收到{{event("close")}}事件时候的事件处理器。当底层链路被关闭的时候会触发该事件。</dd>
 <dt>{{domxref("RTCDataChannel.onerror")}}</dt>
 <dd>当接收到{{event("error")}} 事件时候的事件处理器。当遇到错误的时候会触发该事件。</dd>
</dl>

<h2 id="方法">方法</h2>

<dl>
 <dt>{{domxref("RTCDataChannel.close()")}}</dt>
 <dd>
 <p>关闭channel的方法。这个关闭动作不是直接生效的。这个方法会将channel的{{domxref("RTCDataChannel.readyState", "state")}} 属性设置为<code>"closing"</code>状态，在消息队列中的消息全部发送完毕之后，channel才会被关闭。</p>
 </dd>
 <dt>{{domxref("RTCDataChannel.send()")}}</dt>
 <dd>将参数中的数据通过channel发送。这个数据可以是{{domxref("DOMString")}}, {{domxref("Blob")}}, {{domxref("ArrayBuffer")}}或者是 {{domxref("ArrayBufferView")}}类型。</dd>
</dl>

<h2 id="Example">Example</h2>

<pre class="brush: js">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");
};
</pre>

<p> </p>

<h2 id="Specifications" name="Specifications">Specifications</h2>

<table class="standard-table" style="height: 49px; width: 1000px;">
 <thead>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>{{ SpecName('WebRTC 1.0', '#idl-def-RTCDataChannel', 'RTCDataChannel') }}</td>
   <td>{{ Spec2('WebRTC 1.0') }}</td>
   <td>Initial specification.</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

{{Compat("api.RTCDataChannel")}}

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="/en-US/docs/Web/Guide/API/WebRTC">WebRTC</a></li>
</ul>