RTCPeerConnection: iceconnectionstatechange 事件

一个 iceconnectionstatechange 事件在 RTCPeerConnection 对象中每次 ICE 连接状态在协商过程中发生变化时都会发送。新的 ICE 连接状态在对象的 iceConnectionState 属性中可用。

iceconnectionstatechange 事件侦听器执行的一项常见任务是在状态更改为 failed 时触发 ICE 重新启动。

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

语法

在像 addEventListener() 这样的方法中使用事件名称，或设置事件处理程序属性。

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

oniceconnectionstatechange = (event) => {};

事件类型

一个通用的 Event。

使用说明

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

ICE 重新启动期间的 ICE 连接状态

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

协商结束时的状态转换

当协商过程用尽了要检查的候选者时，ICE 连接将转换为两种状态之一。如果未找到合适的候选者，则状态将转换为 failed。如果至少识别出一个合适的候选者，则状态将转换为 completed。ICE 层在收到候选者结束信号时做出此决定，候选者结束信号是通过调用 addIceCandidate()，并传递一个其 candidate 属性为空字符串 ("") 的候选者，或通过将 RTCPeerConnection 属性 canTrickleIceCandidates 设置为 false 来提供的。

示例

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

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

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

也可以写成

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

规范

规范
WebRTC：浏览器中的实时通信
# dom-rtcpeerconnection-oniceconnectionstatechange

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。

另请参阅