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`;
};