recursal/MDN huggingface dataset:
Animation.playState
===================

Baseline 2022
-------------

Newly availableSince September 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
**实验性:** **这是一项实验性技术**  
在将其用于生产之前，请仔细检查浏览器兼容性表格。

作为一个 Web Animations API 的属性，**`Animation.playState`** 能够返回并设置一个可枚举值来描述一个动画的回放状态。

**备注：** 这个属性只对 CSS Animations 和 Transitions 可读。

语法
--
```

var currentPlayState = Animation.playState;

Animation.playState = newState;
```

### 可能的值

`idle`

动画当前的时间是无法解析的，并且队列里没有处于等待执行的任务。

`pending`

动画将一直等到某些等待中的任务完成方会执行。

`running`

动画处于正在运行状态。

`paused`

动画中止，并且`Animation.currentTime`该项属性不会更新。

`finished`

动画已经达到某一临界点，并且`Animation.currentTime`该项属性不会更新。

实例
--

在Growing/Shrinking Alice Game这个例子中，玩家们可以凭Alice crying into a pool of tears结束游戏。出于性能原因，游戏里，眼泪只当可见之时才能运动。因此，这些泪滴必须在下面的情况下刚好暂停运动：


```js
// 创建泪珠动画

tears.forEach(function (el) {
  el.animate(tearsFalling, {
    delay: getRandomMsRange(-1000, 1000), // 获取每一滴随机泪珠
    duration: getRandomMsRange(2000, 6000), // 获取每一滴随机泪珠
    iterations: Infinity,
    easing: "cubic-bezier(0.6, 0.04, 0.98, 0.335)",
  });
  el.playState = "paused";
});

// 结尾需要现出时播放眼泪降落动画

tears.forEach(function (el) {
  el.playState = "playing";
});

// 暂停并重置正在哭泣时的泪滴动画

tears.forEach(function (el) {
  el.playState = "paused";
  el.currentTime = 0;
});
```

规范
--

| Specification |
| --- |
| Web Animations # dom-animation-playstate |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* Web Animations API
* `Animation` 获取更多可用来控制网页动画的方法和属性
* `Animation.play()`, `Animation.pause()` (en-US), `Animation.finish()` (en-US)，这些方法可以设置一个动画的 `playState`
HTMLTableElement.createCaption()
================================

这个 **`HTMLTableElement.createCaption()`** 方法返回这个 table 元素的 caption(HTMLTableCaptionElement). 如果这个 table 没有 caption，这个方法创建并返回 caption.

语法
--
```

HTMLTableCaptionElement = table.createCaption()
```

示例
--


```js
mycap = mytable.createCaption();
```

Specification
-------------

* createCaption
HTMLTableElement.rows
=====================

表中所有行的
**`HTMLTableElement.rows`** 只读属性返回表中所有行的一个活的 `HTMLCollection`。**`HTMLTableElement.rows`** 包括与之相关的`<thead>`, `<tfoot>` 和 `<tbody>` 元素。

Although the property is read-only, the returned object is live and allows the modification of its content.

Syntax
------
```

HTMLCollectionObject = table.rows
```

Example
-------


```js
myrows = mytable.rows;
firstRow = mytable.rows[0];
lastRow = mytable.rows[mytable.rows.length - 1];
```

Specification
-------------

* rows
* HTMLcollection
HTMLTableElement.deleteTHead()
==============================

**`HTMLTableElement.deleteTHead()`** 方法删除指定 `<table>` 的 `<thead>` 元素。

语法
--
```

HTMLTableElement.deleteTHead();
```

示例
--

本示例使用 JavaScript 删除表格的头部。

### HTML


```html
<table>
  <thead>
    <th>Name</th>
    <th>Occupation</th>
  </thead>
  <tr>
    <td>Bob</td>
    <td>Plumber</td>
  </tr>
  <tr>
    <td>Jim</td>
    <td>Roofer</td>
  </tr>
</table>
```

### JavaScript


```js
let table = document.querySelector("table");
table.deleteTHead();
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-table-deletethead-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
BroadcastChannel：message 事件
===========================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
当频道收到一条消息时，会在关联的 `BroadcastChannel` 对象上触发 `message` 事件。

语法
--

在 `addEventListener()` 等方法中使用事件名称，或设置事件处理器属性。


```js
addEventListener("message", (event) => {});
onmessage = (event) => {};
```

事件类型
----

一个 `MessageEvent`。继承自 `Event`。

Event

MessageEvent事件属性
----

*除了下面列出的属性之外，还可以使用父接口 `Event` 的属性。*

`data` (en-US) 只读 

由消息发送者发送的数据。

`origin` (en-US) 只读 

一个表示消息发送者来源的字符串。

`lastEventId` (en-US) 只读 

一个表示事件唯一 ID 的字符串。

`source` (en-US) 只读 

一个*消息事件源*，可以是一个用于表示消息发送者的 WindowProxy (en-US)、`MessagePort` 或 `ServiceWorker` 对象。

`ports` (en-US) 只读 

一个与发送消息（通过频道发送消息或向 SharedWorker 发送消息）的频道相关联的 `MessagePort` 对象的数组。

示例
--

在这个示例中，有一个 `<iframe>` 作为发送者，当用户点击按钮之后，会广播 `<textarea>` 中的内容。同时，有两个 `iframe` 作为接收者，会监听广播的消息，并将结果写入 `<div>` 元素。

### 发送者
```

<h1>发送者</h1>
<label for="message">请输入要广播的信息：</label><br />
<textarea id="message" name="message" rows="1" cols="40">Hello</textarea>
<button id="broadcast-message" type="button">广播信息</button>
```


```
body {
  border: 1px solid black;
  padding: 0.5rem;
  height: 150px;
  font-family: "Fira Sans", sans-serif;
}

h1 {
  font:
    1.6em "Fira Sans",
    sans-serif;
  margin-bottom: 1rem;
}

textarea {
  padding: 0.2rem;
}

label,
br {
  margin: 0.5rem 0;
}

button {
  vertical-align: top;
  height: 1.5rem;
}
```



```js
const channel = new BroadcastChannel("example-channel");
const messageControl = document.querySelector("#message");
const broadcastMessageButton = document.querySelector("#broadcast-message");

broadcastMessageButton.addEventListener("click", () => {
  channel.postMessage(messageControl.value);
});
```

### 接收者 1
```

<h1>接收者 1</h1>
<div id="received"></div>
```


```
body {
  border: 1px solid black;
  padding: 0.5rem;
  height: 100px;
  font-family: "Fira Sans", sans-serif;
}

h1 {
  font:
    1.6em "Fira Sans",
    sans-serif;
  margin-bottom: 1rem;
}
```



```js
const channel = new BroadcastChannel("example-channel");
channel.addEventListener("message", (event) => {
  received.textContent = event.data;
});
```

### 接收者 2
```

<h1>接收者 2</h1>
<div id="received"></div>
```


```
body {
  border: 1px solid black;
  padding: 0.5rem;
  height: 100px;
  font-family: "Fira Sans", sans-serif;
}

h1 {
  font:
    1.6em "Fira Sans",
    sans-serif;
  margin-bottom: 1rem;
}
```



```js
const channel = new BroadcastChannel("example-channel");
channel.addEventListener("message", (event) => {
  received.textContent = event.data;
});
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # event-message |
| HTML Standard # handler-broadcastchannel-onmessage |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 相关事件：`messageerror`。
BroadcastChannel.close()
========================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
通过调用 **`BroadcastChannel.close()`** 方法，可以马上断开其与对应频道的关联，并让其被垃圾回收。这是必要的步骤，因为浏览器没有其他方式知道频道不再被需要。

**备注：** 此特性在 Web Worker 中可用

语法
--
```

var str = channel.close();
```

示例
--


```js
// 连接到指定频道
var bc = new BroadcastChannel("test\_channel");

// 其他操作 (如：postMessage, …)

// 当完成后，断开与频道的连接
bc.close();
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-broadcastchannel-close-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

另见
--

* `BroadcastChannel`, the interface it belongs to.
BroadcastChannel: messageerror event
====================================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
当频道收到一条无法反序列化的消息时会在 `BroadcastChannel` 对象上触发 `messageerror` 事件。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | No |
| Interface | `MessageEvent` |
| Event handler property | `onmessageerror` |

示例
--

以下代码使用 `addEventListener` 来监听消息和错误：


```js
const channel = new BroadcastChannel("example-channel");

channel.addEventListener("message", (event) => {
  received.textContent = event.data;
});

channel.addEventListener("messageerror", (event) => {
  console.error(event);
});
```


使用 `onmessage` 和 `onmessageerror` 事件处理程序来实现相同效果：


```js
const channel = new BroadcastChannel("example-channel");

channel.onmessage = (event) => {
  received.textContent = event.data;
};

channel.onmessageerror = (event) => {
  console.log(event);
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-messageerror |
| HTML Standard # handler-broadcastchannel-onmessageerror |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

另见
--

* 相关事件：`message`
BroadcastChannel.postMessage()
==============================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
可以使用 **`BroadcastChannel.postMessage()`** 发送一条任意 `Object` 类型的消息，给所有同源下监听了该频道的所有浏览器上下文。消息以 `message` 事件的形式发送给每一个绑定到该频道的广播频道。

**备注：** 此特性在 Web Worker 中可用

语法
--
```

var str = channel.postMessage(object);
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-broadcastchannel-postmessage-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

另见
--

* 所属接口：`BroadcastChannel`
BroadcastChannel.name
=====================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
**`BroadcastChannel.name`** 是类型为 `DOMString` 的只读属性，是频道的唯一标识。属性 name 是在创建时传入 `BroadcastChannel()` 构造函数的，所以是只读的。

**备注：** 此特性在 Web Worker 中可用

语法
--
```

var str = channel.name;
```

示例
--


```js
// 连接到指定频道
var bc = new BroadcastChannel("test\_channel");

// 其他操作 (如：postMessage, …)

// 在控制台打印频道名称
console.log(bc.name); // "test\_channel"

// 当完成后，断开与频道的连接
bc.close();
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-broadcastchannel-name-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 所属接口：`BroadcastChannel`
BroadcastChannel()
==================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
**`BroadcastChannel()`** 构造函数用于创建一个 `BroadcastChannel` 对象，并与底层的通道相关联。

**备注：** 此特性在 Web Worker 中可用

语法
--


```js
new BroadcastChannel(channelName)
```

### 参数

`channelName`

表示通道名称的字符串；对于相同的来源下的所有浏览上下文，一个名称只对应一个通道。

示例
--


```js
// 创建一个监听“internal\_notification”通道的新通道。

const bc = new BroadcastChannel("internal\_notification");
bc.postMessage("New listening connected!");
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-broadcastchannel-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

另见
--

* 所属接口：`BroadcastChannel`
HTMLTableRowElement.rowIndex
============================

只读属性 **`HTMLTableRowElement.rowIndex`** 用于表示元素所在行相对于整个 `<table>` 的逻辑位置。

即使 `<thead>`、`<tbody>` 和 `<tfoot>` 元素在 HTML 中乱序排列，浏览器也会以正确的顺序渲染表格。因此，行号的标记顺序为：从 `<thead>` 到 `<tbody>`，再到 `<tfoot>`。

语法
--


```js
var index = HTMLTableRowElement.rowIndex;
```

### 返回值

返回该行的索引，如果该行不属于表的一部分，则返回 `-1`。

示例
--

本示例使用 JavaScript 标记表中的所有行号。

### HTML


```html
<table>
  <thead>
    <tr>
      <th>商品</th>
      <th>价格</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>香蕉</td>
      <td>$2</td>
    </tr>
    <tr>
      <td>橘子</td>
      <td>$8</td>
    </tr>
    <tr>
      <td>西冷牛排</td>
      <td>$20</td>
    </tr>
  </tbody>
  <tfoot>
    <tr>
      <td>总计</td>
      <td>$30</td>
    </tr>
  </tfoot>
</table>
```

### JavaScript


```js
let rows = document.querySelectorAll("tr");

rows.forEach((row) => {
  let z = document.createElement("td");
  z.textContent = `(row #${row.rowIndex})`;
  row.appendChild(z);
});
```

### 结果

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
RTCPeerConnection.ondatachannel
===============================

**实验性:** **这是一项实验性技术**  
在将其用于生产之前，请仔细检查浏览器兼容性表格。

**`RTCPeerConnection.ondatachannel`** 属性是一个事件处理器，当 `datachannel` 事件在 `RTCPeerConnection` 发生时，它指定的那个事件处理函数就会被调用。这个事件继承于 `RTCDataChannelEvent` (en-US)，当远方伙伴调用 `createDataChannel()` 时这个事件被加到这个连接（RTCPeerConnection）中。

在这个事件被收到的同时，这个 `RTCDataChannel` 实际上并没有打开，确保在 open 这个事件在`RTCDataChannel`触发以后才去使用它。

语法
--
```

RTCPeerConnection.ondatachannel = function;
```

### 值

将这个属性设置为接受一个参数的函数：这个参数是一个`RTCDataChannelEvent` (en-US)，它的 channel 属性是一个已经创建了的`RTCDataChannel`对象

示例
--


```js
pc.ondatachannel = function (ev) {
  console.log("Data channel is created!");
  ev.channel.onopen = function () {
    console.log("Data channel is open and ready to be used.");
  };
};
```

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-ondatachannel |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* WebRTC API
* 使用 WebRTC data channel (en-US)
* RTCDataChannel 简单示例
* `RTCDataChannelEvent` (en-US)
* `RTCPeerConnection.createDataChannel()`
RTCPeerConnection.iceGatheringState
===================================

只读属性 **`RTCPeerConnection.iceGatheringState`** 返回一个描述连接的 ICE 收集状态的字符串。比如当 ICE 候选收集完成的时候，你可以通过该属性的变化侦测到。

通过监听 `icegatheringstatechange` (en-US) 类型的事件，你可以侦测到该属性的变化。

值
-

可能的值是：

`new`

对等连接刚刚创建，尚未进行任何网络连接。

`gathering`

ICE 代理正在收集候选的连接。

`complete`

ICE 代理完成了候选的收集。如果发生了需要收集的新候选，例如一个新接口的增加或者一个新的 ICE 服务器的增加，状态将恢复到 `gathering`，并去收集这些候选。

示例
--


```js
const pc = new RTCPeerConnection();
const state = pc.iceGatheringState;
```

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-ice-gathering-state |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `icegatheringstatechange` (en-US)
* WebRTC
RTCPeerConnection.currentLocalDescription
=========================================

只读属性 **`RTCPeerConnection.currentLocalDescription`** 返回一个 `RTCSessionDescription` 对象，该对象描述了 自上次 `RTCPeerConnection` 完成协商与连接到远程端后，最近一次成功协商的连接的本地端。原文（describing the local end of the connection as it was most recently successfully negotiated since the last time the RTCPeerConnection finished negotiating and connecting to a remote peer）。也包括自 RTCSessionDescription 所代表的 offer 或 anwser 首次实例化以来，ICE 代理可能已经生成的任何 ICE 候选人的列表。

若想改变 `currentLocalDescription` ，则调用 `RTCPeerConnection.setLocalDescription()` (en-US) 。这将会触发引发该值被设置的一系列事件。如果希望详细了解策略与机制，查阅待定的和当前描述。

**备注：** 与 `RTCPeerConnection.localDescription` (en-US) 不同，这个值代表了当前连接的本地端的事实当前状态； `localDescription` 也许指明了一个当前正在切换中的连接的 description。

语法
--
```

sessionDescription = RTCPeerConnection.currentLocalDescription;
```

### 返回值

连接本地端的当前 description 描述，如果成功设置了一个。否则返回 null。

示例
--

本例子查看 `currentLocalDescription` 并且显示了包含 `RTCSessionDescription` 对象的 `type` 与 `sdp` 字段的 alert。


```js
var pc = new RTCPeerConnection();
…
var sd = pc.currentLocalDescription;
if (sd) {
  alert("Local session: type='" +
        sd.type + "'; sdp description='" +
        sd.sdp + "'");
}
else {
  alert("No local session yet.");
}
```

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-currentlocaldesc |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**备注：** The addition of `currentLocalDescription` and `pendingLocalDescription` (en-US) to the WebRTC spec is relatively recent. In browsers which don't support them, just use `localDescription` (en-US).

参见
--

* `RTCPeerConnection.setLocalDescription()` (en-US)、`RTCPeerConnection.pendingLocalDescription` (en-US)、`RTCPeerConnection.localDescription` (en-US)
* `RTCPeerConnection.setRemoteDescription()`、`RTCPeerConnection.remoteDescription`、`RTCPeerConnection.pendingRemoteDescription` (en-US)、`RTCPeerConnection.currentRemoteDescription` (en-US)
* WebRTC
RTCPeerConnection.remoteDescription
===================================

**实验性:** **这是一项实验性技术**  
在将其用于生产之前，请仔细检查浏览器兼容性表格。

只读属性 **`RTCPeerConnection.remoteDescription`** 返回一个 `RTCSessionDescription` ，它描述了和远程对端之间的会话 (包括配置和媒体信息) ，如果还没有被设置过的话，它会是 `null`.

这个值通常是通过信令服务器接收的对端的会话描述（作为提议或应答），调用`RTCPeerConnection.setRemoteDescription()`之后生效。

语法
--
```

 var sessionDescription = peerConnection.remoteDescription;
```


从更基础的层面上看，如果该属性不为`null`，则返回值为`RTCPeerConnection.pendingRemoteDescription` (en-US)的值，否则，返回`RTCPeerConnection.currentRemoteDescription` (en-US)的值。有关此算法的详细信息及其使用原因，请参阅待定的和当前描述。

示例
--

此示例查看`remoteDescription`并显示包含`RTCSessionDescription`对象的 type 和`sdp`字段的警告。


```js
var pc = new RTCPeerConnection();
…
var sd = pc.remoteDescription;
if (sd) {
  alert("Remote session: type='" +
        sd.type + "'; sdp description='" +
        sd.sdp + "'");
}
else {
  alert("No remote session yet.");
}
```

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-remotedescription |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `RTCPeerConnection.setRemoteDescription()`、`RTCPeerConnection.pendingRemoteDescription` (en-US)、`RTCPeerConnection.currentRemoteDescription` (en-US)
* `RTCPeerConnection.setLocalDescription()` (en-US)、`RTCPeerConnection.pendingLocalDescription` (en-US)、`RTCPeerConnection.currentLocalDescription`、`RTCPeerConnection.localDescription` (en-US)
* WebRTC
RTCPeerConnection.canTrickleIceCandidates
=========================================

只读的 **`RTCPeerConnection`** 属性 `canTrickleIceCandidates` 返回一个`Boolean`，它指示远程对等端是否可以接受 trickled ICE candidates 。

**ICE trickling**是在初始发送或回应已经发送给其他设备之后继续发送候选的过程。

仅在调用`RTCPeerConnection.setRemoteDescription()`之后才设置此属性。理想情况下，你的信令协议提供了一种检测滴流支持的方法，因此你无需依赖此属性。WebRTC 浏览器将始终支持 trickle ICE。如果不支持滴流，或者你无法辨别，则可以检查此属性的伪值，然后等待`iceGatheringState`的值更改在创建和发送之前“完成”。这样，发送信息包含所有候选。

值
-

`Boolean` 如果远程对等体可以接受滴入的 ICE candidate，则为 true；如果不能，则为 false。如果尚未建立远程对等方，则此值为 null。

**备注：** 一旦本地对等方调用`RTCPeerConnection.setRemoteDescription()`，就确定该属性的值; ICE 代理使用所提供的描述来确定远程对等体是否支持滴入的 ICE candidates。

示例
--


```js
var pc = new RTCPeerConnection();
// The following code might be used to handle an offer from a peer when
// it isn't known whether it supports trickle ICE.
pc.setRemoteDescription(remoteOffer)
  .then(\_ => pc.createAnswer())
  .then(answer => pc.setLocalDescription(answer))
  .then(\_ =>
    if (pc.canTrickleIceCandidates) {
      return pc.localDescription;
    }
    return new Promise(r => {
      pc.addEventListener('icegatheringstatechange', e => {
        if (e.target.iceGatheringState === 'complete') {
          r(pc.localDescription);
        }
      });
    });
  })
  .then(answer => sendAnswerToPeer(answer)) // signaling message
  .catch(e => handleError(e));

pc.addEventListener('icecandidate', e => {
  if (pc.canTrickleIceCandidates) {
    sendCandidateToPeer(e.candidate); // signaling message
  }
});
```

规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-cantrickleicecandidates |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* WebRTC
* `RTCPeerConnection.addIceCandidate()`
* WebRTC 会话的生命周期
RTCPeerConnection: icecandidate 事件
==================================

当 `RTCPeerConnection` 通过 `RTCPeerConnection.setLocalDescription()` (en-US) 方法更改本地描述之后，该 `RTCPeerConnection` 会抛出 **`icecandidate`** 事件。该事件的监听器需要将更改后的描述信息传送给远端 `RTCPeerConnection`，以更新远端的备选源。

使用指南
----

`icecandidate` 的类型为 `RTCPeerIceCandidateEvent`, 在以下三种情况下会触发该事件：

### 分享新的候选

触发 `icecandidate` 事件的首要原因：当获得新的源之后，需要将该源的信息发送给远端信号服务器，并分发至其他端的 `RTCPeerConnection`。其他 `RTCPeerConnection` 通过 `addIceCandidate()` 方法将新 `candidate` 中携带的信息，将新的源描述信息添加进它的备选池中；


```js
rtcPeerConnection.onicecandidate = (event) => {
  if (event.candidate) {
    sendCandidateToRemotePeer(event.candidate);
  } else {
    /\* 在此次协商中，没有更多的候选了 \*/
  }
};
```


远程的节点在接受到候选后，将通过调用 `addIceCandidate()` 的方式将候选加入候选池中，并传入通过信令服务器得到的 `candidate` (en-US) 字符串（作为参数）。

### 代表最后一轮候选结束

当一个 ICE 协商会话没有候选来提供给某个给定的 RTCIceTransport，就完成了一轮候选的收集。一个带有空字串（""）的 icecandidate 事件出现，表明了这种情况。

你应当像对待任何普通候选一般向远程节点传递这个候选，正如在上述“共享一个新的候选”里所描述的。这就确保了远程节点也能获得候选终结的通知。正如你在上一个小节的代码里所见，每个候选都被发送到别的节点，包括任何可能含有空候选字串的。只有那些事件的 candidate 属性为 null 的不通过信令连接传递。

候选终结指示在 Trickle ICE draft 规范的 9.3 章有描述（注意，章节号码会根据标准的反复修正而发生改变）

### 代表 ICE 收集完成

一旦所有的 ICE 传输完成收集候选并且 `RTCPeerConnection` 对象的 `iceGatheringState` 的值变化成 `complete`，一个 `icecandidate` 事件携带着值为 `null` 的 `complete` 属性的被发送。

这个信号的存在是为了向后兼容的目的，并且不需要向远程节点分发（这也就是为什么上面的代码片段检查了 event.candidate 是否为 null，优先于沿着候选发送）

如果你需要执行任何特别的动作，当没有更多的期待的候选，你最好通过观察 `icegatheringstatechange` (en-US) 事件来观察 ICE 收集状态。


```js
pc.addEventListener("icegatheringstatechange", (ev) => {
  switch (pc.iceGatheringState) {
    case "new":
      /\* gathering is either just starting or has been reset \*/
      break;
    case "gathering":
      /\* gathering has begun or is ongoing \*/
      break;
    case "complete":
      /\* gathering has ended \*/
      break;
  }
});
```


如你在这个例子中看到的，icegatheringstatechange 事件让你知道 RTCPeerConnection 属性 iceGatheringState 被更新的时机。如果那个值现在是 complete，你就知道 ICE 收集刚刚结束。

对表明一个 ICE 会话已经结束而言，相比观察一个单独的 ICE 消息，这是更为可靠的方法。

### 示例

这个例子建立一个简单的 icecandidate 事件处理器，通过信令服务器使用一个 sendMessenge() 来建立和发送一个回复给远程节点。

首先，一个使用 addEventListener() 的例子：


```js
pc.addEventListener(
  "icecandidate",
  (ev) => {
    if (ev.candidate) {
      sendMessage({ type: "new-ice-candidate", candidate: event.candidate });
    }
  },
  false,
);
```


你也可以直接设定 `onicecandidate` 事件处理器的属性：


```js
pc.onicecandidate = (ev) => {
  if (ev.candidate) {
    sendMessage({ type: "new-ice-candidate", candidate: event.candidate });
  }
};
```

概述
--

接口
`RTCPeerConnectionIceEvent` (en-US)
事件冒泡

否

能否取消默认

否

事件目标
`RTCPeerConnection`
默认行为

无

属性
--

*属性继承自`RTCPeerConnectionIceEvent` (en-US).*

方法
--

*方法继承自 `RTCPeerConnectionIceEvent` (en-US).*

相关事件
----

* *无*
规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-onicecandidate |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* WebRTC