大网数据广告活动
Web 标准与前端开发

RTCPeerConnection: iceconnectionstatechange event

· 52CE 我爱测

An **`iceconnectionstatechange`** event is sent to an RTCPeerConnection object each time the ICE connection state changes during the negotiation process. The new ICE connection state is available in the object's RTCPeerConnection.iceConnectionState property.

WebRTC

An iceconnectionstatechange event is sent to an RTCPeerConnection object each time the ICE connection state changes during the negotiation process. The new ICE connection state is available in the object's RTCPeerConnection.iceConnectionState property.

One common task performed by the iceconnectionstatechange event listener is to trigger ICE restart when the state changes to failed.

This event is not cancelable and does not bubble.

Syntax

Use the event name in EventTarget/addEventListener:

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

Alternatively, assign to the event handler property of the interface:

oniceconnectionstatechange = (event) => { }

Event type

A generic Event.

Usage notes

A successful connection attempt will typically involve the state starting at new, then transitioning through checking, then connected, and finally completed. However, under certain circumstances, the connected state can be skipped, causing a connection to transition directly from the checking state to completed. This can happen when only the last checked candidate is successful, and the gathering and end-of-candidates signals both occur before the successful negotiation is completed.

ICE connection state during ICE restarts

When an ICE restart is processed, the gathering and connectivity checking process is started over from the beginning, which will cause the iceConnectionState to transition to connected if the ICE restart was triggered while in the completed state. If ICE restart is initiated while in the transient disconnected state, the state transitions instead to checking, essentially indicating that the negotiation is ignoring the fact that the connection had been temporarily lost.

State transitions as negotiation ends

When the negotiation process runs out of candidates to check, the ICE connection transitions to one of two states. If no suitable candidates were found, the state transitions to failed. If at least one suitable candidate was successfully identified, the state transitions to completed. The ICE layer makes this determination upon receiving the end-of-candidates signal, which is provided by calling RTCPeerConnection.addIceCandidate with a candidate whose RTCIceCandidate.candidate property is an empty string (""), or by setting the RTCPeerConnection property RTCPeerConnection.canTrickleIceCandidates to false.

Examples

An event handler for this event can be added using the oniceconnectionstatechange property (but note that this replaces other event listeners added using oniceconnectionstatechange, if any) or by using EventTarget.addEventListener on the RTCPeerConnection.

In this example, a handler for iceconnectionstatechange is set up to update a call state indicator by using the value of RTCPeerConnection.iceConnectionState to create a string which corresponds to the name of a CSS class that we can assign to the status indicator to cause it to reflect the current state of the connection.

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

This can also be written using the oniceconnectionstatechange event handler property (but note that this replaces other event listeners added using oniceconnectionstatechange, if any):

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

Specifications

Browser compatibility

See also

  • WebRTC API
  • RTCPeerConnection
  • RTCPeerConnection.iceConnectionState

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。