RTCPeerConnection

Baseline 廣泛可用 *

此功能已成熟，可跨多種裝置和瀏覽器版本使用。自 2017 年 9 月以來，它已在瀏覽器中提供。

* 此特性的某些部分可能存在不同級別的支援。

RTCPeerConnection 介面表示本地計算機與遠端對等端之間的 WebRTC 連線。它提供了連線到遠端對等端、維護和監控連線以及在不再需要時關閉連線的方法。

建構函式

RTCPeerConnection(): 返回一個新的 RTCPeerConnection 物件，表示本地裝置與遠端對等端之間的連線。

例項屬性

還繼承了 EventTarget 的屬性。

canTrickleIceCandidates 只讀: 返回一個布林值，指示遠端對等端是否可以接受 trickled ICE 候選。
connectionState 只讀: 透過返回以下字串之一來指示對等連線的當前狀態：new、connecting、connected、disconnected、failed 或 closed。
currentLocalDescription 只讀: 返回一個 RTCSessionDescription 物件，描述此 RTCPeerConnection 自上次與遠端對等端完成協商和連線以來，本地連線端最近一次成功協商的狀態。其中還包括自描述所代表的要約或應答首次例項化以來，ICE 代理可能已經生成的任何 ICE 候選列表。
currentRemoteDescription 只讀: 返回一個 RTCSessionDescription 物件，描述此 RTCPeerConnection 自上次與遠端對等端完成協商和連線以來，遠端連線端最近一次成功協商的狀態。其中還包括自描述所代表的要約或應答首次例項化以來，ICE 代理可能已經生成的任何 ICE 候選列表。
iceConnectionState 只讀: 返回一個字串，表示與此 RTCPeerConnection 關聯的 ICE 代理的狀態。它可以是以下值之一：new、checking、connected、completed、failed、disconnected 或 closed。
iceGatheringState 只讀: 返回一個字串，描述連線的 ICE 收集狀態。這讓你可以檢測到，例如，ICE 候選收集何時完成。可能的值為：new、gathering 或 complete。
localDescription 只讀: 返回一個 RTCSessionDescription，描述連線本地端的會話。如果尚未設定，則返回 null。
peerIdentity 只讀: 返回一個 Promise，該 Promise 解析為一個 RTCIdentityAssertion，其中包含一個標識遠端對等端的字串。一旦此 Promise 成功解析，則生成的身份為目標對等端身份，並且在連線期間不會更改。
pendingLocalDescription 只讀: 返回一個 RTCSessionDescription 物件，描述連線本地端的待定配置更改。這不描述連線的當前狀態，而是描述連線在不久的將來可能存在的方式。
pendingRemoteDescription 只讀: 返回一個 RTCSessionDescription 物件，描述連線遠端端的待定配置更改。這不描述連線的當前狀態，而是描述連線在不久的將來可能存在的方式。
remoteDescription 只讀: 返回一個 RTCSessionDescription 物件，描述連線遠端端的會話，包括配置和媒體資訊。如果尚未設定，則返回 null。
sctp 只讀: 返回一個 RTCSctpTransport 物件，描述正在透過其傳送和接收 SCTP 資料的 SCTP 傳輸層。如果尚未協商 SCTP，則此值為 null。
signalingState 只讀: 返回一個字串，描述連線到另一個對等端時，連線本地端信令過程的狀態。它是以下值之一：stable、have-local-offer、have-remote-offer、have-local-pranswer、have-remote-pranswer 或 closed。

靜態方法

RTCPeerConnection.generateCertificate(): 建立 X.509 證書及其相應的私鑰，並返回一個 Promise，該 Promise 在生成新 RTCCertificate 後解析為它。

例項方法

還繼承了 EventTarget 的方法。

addIceCandidate(): 向 RTCPeerConnection 的遠端描述新增新的遠端候選，該描述描述了連線遠端端的狀態。
addTrack(): 向將傳輸到另一個對等端的軌道集新增新的 MediaStreamTrack。
addTransceiver(): 建立新的 RTCRtpTransceiver 並將其新增到與連線關聯的收發器集。每個收發器都表示一個雙向流，並與其關聯一個 RTCRtpSender 和一個 RTCRtpReceiver。
close(): 關閉當前對等連線。
createAnswer(): 在 WebRTC 連線的要約/應答協商期間，啟動建立對從遠端對等端收到的要約的 SDP 應答。應答包含有關已附加到會話的任何媒體、瀏覽器支援的編解碼器和選項以及已收集的任何 ICE 候選的資訊。
createDataChannel(): 啟動建立與遠端對等端連結的新通道，透過該通道可以傳輸任何型別的資料。這對於後臺內容（例如影像、檔案傳輸、文字聊天、遊戲更新包等）非常有用。
createOffer(): 啟動建立 SDP 要約，以啟動到遠端對等端的新 WebRTC 連線。SDP 要約包括有關已附加到 WebRTC 會話的任何 MediaStreamTrack 物件、編解碼器和瀏覽器支援的選項的資訊，以及 ICE 代理已收集的任何候選，目的是透過信令通道傳送給潛在的對等端，以請求連線或更新現有連線的配置。
getConfiguration(): 返回一個物件，指示連線的當前配置。
getIdentityAssertion(): 啟動身份斷言的收集並返回一個 Promise，該 Promise 解析為編碼為字串的身份斷言。這僅在 signalingState 不是 closed 時才有效。
getReceivers(): 返回一個 RTCRtpReceiver 物件陣列，每個物件表示一個 RTP 接收器。
getSenders(): 返回一個 RTCRtpSender 物件陣列，每個物件表示負責傳輸一個軌道資料的 RTP 傳送器。
getStats(): 返回一個 Promise，該 Promise 解析為提供有關整個連線或指定 MediaStreamTrack 的統計資料。
getTransceivers(): 返回一個列表，其中包含用於在連線上傳送和接收資料的所有 RTCRtpTransceiver 物件。
removeTrack(): 通知連線的本地端停止傳送指定軌道的媒體，而無需實際從 getSenders() 報告的傳送器列表中刪除相應的 RTCRtpSender。如果軌道已經停止或不在連線的傳送器列表中，則此方法無效。
restartIce(): 允許輕鬆請求在連線的兩端重新執行 ICE 候選收集。這透過允許呼叫方或接收方使用相同的方法觸發 ICE 重啟來簡化該過程。
setConfiguration(): 根據指定物件中包含的值設定連線的當前配置。這允許您更改連線使用的 ICE 伺服器和要使用的傳輸策略。
setIdentityProvider(): 將身份提供商 (IdP) 設定為引數中給出的三元組：其名稱、用於與其通訊的協議和使用者名稱。協議和使用者名稱是可選的。
setLocalDescription(): 更改與連線關聯的本地描述。此描述指定連線本地端的屬性，包括媒體格式。它返回一個 Promise，該 Promise 在描述非同步更改後實現。
setRemoteDescription(): 將指定的會話描述設定為遠端對等端的當前要約或應答。該描述指定連線遠端端的屬性，包括媒體格式。它返回一個 Promise，該 Promise 在描述非同步更改後實現。

已廢棄的方法

addStream() 已棄用非標準: 將 MediaStream 新增為本地音訊或影片源。與其使用此過時方法，不如為您希望傳送到遠端對等端的每個軌道使用 addTrack() 一次。
createDTMFSender() 已棄用非標準: 建立與特定 MediaStreamTrack 關聯的新 RTCDTMFSender，該物件將能夠透過連線傳送 DTMF 電話信令。
removeStream() 已棄用非標準: 從本地音訊或影片源中移除 MediaStream。由於此方法已過時，因此應改用 removeTrack()。

事件

使用 addEventListener() 監聽這些事件，或透過將事件監聽器分配給此介面的 oneventname 屬性。

connectionstatechange: 當 RTCPeerConnection 的整體連線狀態發生變化時傳送。
datachannel: 當遠端對等端向連線新增 RTCDataChannel 時傳送。
icecandidate: 傳送以請求將指定的候選傳輸到遠端對等端。
icecandidateerror: 如果在 ICE 候選收集期間發生錯誤，則傳送到連線。事件描述了該錯誤。
iceconnectionstatechange: 當 ICE 連線狀態發生變化時傳送，例如斷開連線時。
icegatheringstatechange: 當 ICE 層的收集狀態（由 iceGatheringState 反映）發生變化時傳送。這表示 ICE 協商是否尚未開始 (new)、已開始收集候選 (gathering) 或已完成 (complete)。
negotiationneeded: 當需要執行 ICE 連線的協商或重新協商時傳送；這既可能在首次建立連線時發生，也可能在需要適應不斷變化的網路條件時發生。接收方應透過建立要約並將其傳送給其他對等端來響應。
signalingstatechange: 當連線的 ICE 信令狀態發生變化時傳送。
track: 當新軌道已新增到構成連線的 RTCRtpReceiver 例項之一後傳送。

過時事件

addstream 已棄用非標準: 當新 MediaStream 已新增到連線時傳送。與其監聽此過時事件，不如監聽 track 事件；對於新增到連線的每個 MediaStreamTrack，都會發送一個事件。
removestream 已棄用非標準: 當 MediaStream 從連線中移除時傳送。與其監聽此過時事件，不如監聽每個流上的 removetrack 事件。

規範

規範
WebRTC：瀏覽器中的即時通訊 # 介面定義

瀏覽器相容性

另見

https://github.com/jesup/nightly-gupshup/blob/master/static/js/chat.js
WebRTC 入門
TutorRoom：Node.js HTML 影片捕獲、點對點影片和檔案共享應用程式（GitHub 上的原始碼）

幫助改進 MDN

瞭解如何貢獻

本頁面上次由 MDN 貢獻者於 2025 年 9 月 25 日修改。

在 GitHub 上檢視此頁面 • 報告此內容問題