RTCPeerConnection: iceconnectionstatechange 事件

Baseline 已广泛支持

此功能已成熟，可跨多种设备和浏览器版本使用。自 2017 年 9 月以来，它已在浏览器中提供。

当 RTCPeerConnection 对象在协商过程中 ICE 连接状态发生变化时，会向该对象发送一个 iceconnectionstatechange 事件。新的 ICE 连接状态可在对象的 iceConnectionState 属性中获取。

iceconnectionstatechange 事件监听器执行的一项常见任务是在状态变为 failed 时触发 ICE 重启。

此事件不可取消，也不会冒泡。

语法

在诸如 addEventListener() 之类的方法中使用事件名称，或设置事件处理程序属性。

addEventListener("iceconnectionstatechange", (event) => { })

oniceconnectionstatechange = (event) => { }

用法说明

成功的连接尝试通常涉及状态从 new 开始，然后过渡到 checking，再到 connected，最后是 completed。然而，在某些情况下，connected 状态可能会被跳过，导致连接直接从 checking 状态过渡到 completed。当只有最后检查的候选者成功，并且在成功协商完成之前就发生了候选者收集和结束信号时，就可能发生这种情况。

ICE 重启期间的 ICE 连接状态

当处理 ICE 重启时，候选者收集和连接性检查过程会从头开始，如果 ICE 重启是在 completed 状态下触发的，这将导致 iceConnectionState 过渡到 connected。如果 ICE 重启是在短暂的 disconnected 状态下启动的，状态则会过渡到 checking，这基本上表明协商忽略了连接暂时丢失的事实。

当协商过程耗尽所有待检查的候选者时，ICE 连接会过渡到两种状态之一。如果没有找到合适的候选者，状态会转为 failed。如果至少找到一个合适的候选者，状态会转为 completed。ICE 层在收到结束候选者信号后做出此决定，该信号通过调用 addIceCandidate() 并传入一个 candidate 属性为空字符串 ("") 的候选者来提供，或者通过将 RTCPeerConnection 属性 canTrickleIceCandidates 设置为 false 来实现。

示例

可以使用 oniceconnectionstatechange 属性或在 RTCPeerConnection 上使用 addEventListener() 来为该事件添加事件处理程序。

在此示例中，为 iceconnectionstatechange 设置了一个处理程序，用于更新通话状态指示器。它使用 iceConnectionState 的值创建一个字符串，该字符串对应于我们可以分配给状态指示器的 CSS 类名，以使其反映连接的当前状态。

pc.addEventListener("iceconnectionstatechange", (ev) => {
  let stateElem = document.querySelector("#call-state");
  stateElem.className = `${pc.iceConnectionState}-state`;
});

也可以这样写：

pc.oniceconnectionstatechange = (ev) => {
  let stateElem = document.querySelector("#call-state");
  stateElem.className = `${pc.iceConnectionState}-state`;
};