MediaDevices: getUserMedia() 方法

Baseline 已廣泛支援

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

安全上下文： 此功能僅在安全上下文（HTTPS）中可用，且支援此功能的瀏覽器數量有限。

getUserMedia() 方法是 MediaDevices 介面的一個方法，它會提示使用者授予許可權以使用媒體輸入裝置，從而生成一個包含所需媒體型別軌道的 MediaStream。

該媒體流可以包含，例如，一個影片軌道（由硬體或虛擬影片源生成，如攝像頭、影片錄製裝置、螢幕共享服務等），一個音訊軌道（同樣，由物理或虛擬音訊源生成，如麥克風、A/D 轉換器等），以及可能其他型別的軌道。

它返回一個 Promise，該 Promise 在成功時解析為一個 MediaStream 物件。如果使用者拒絕許可權，或者沒有可用的匹配媒體，則 Promise 會分別以 NotAllowedError 或 NotFoundError DOMException 拒絕。

注意： 返回的 Promise 既可能不解析也不拒絕，因為使用者不一定需要做出選擇，並且可能會忽略請求。

語法

getUserMedia(constraints)

引數

約束

一個物件，用於指定請求的媒體型別，以及每種型別的任何要求。

constraints 引數是一個包含 video 和 audio 兩個成員的物件，用於描述請求的媒體型別。必須指定其中一個或兩個。如果瀏覽器找不到所有符合給定約束條件的指定型別的媒體軌道，則返回的 Promise 會以 NotFoundError DOMException 拒絕。

對於 video 和 audio，其值可以是布林值或物件。預設值為 false。

如果為媒體型別指定 true，則生成的媒體流必須包含該型別的軌道。如果由於任何原因無法包含，返回的 Promise 將被拒絕。
如果為媒體型別指定 false，則生成的媒體流不得包含該型別的軌道，否則返回的 Promise 將被拒絕。因為 video 和 audio 都預設為 false，所以如果 constraints 物件不包含任何屬性或根本不存在，返回的 Promise 將始終被拒絕。
如果為媒體型別指定了一個物件，該物件將被讀取為 MediaTrackConstraints 字典。

返回值

一個 Promise，當成功獲取到請求的媒體時，其完成處理程式會接收一個 MediaStream 物件。

異常

AbortError DOMException: 儘管使用者和作業系統都已授予對硬體裝置的訪問許可權，並且沒有發生導致 NotReadableError DOMException 的硬體問題，但如果發生阻止裝置使用的問題，則丟擲此異常。
InvalidStateError DOMException: 如果當前文件未完全啟用，則丟擲此異常。
NotAllowedError DOMException: 如果一個或多個請求的源裝置當前無法使用，則丟擲此異常。這會在瀏覽上下文不安全（即頁面使用 HTTP 而非 HTTPS 載入）時發生。如果使用者指定當前瀏覽例項不允許訪問裝置、使用者已拒絕當前會話的訪問許可權，或者使用者已全域性拒絕所有使用者媒體裝置的訪問許可權，也會發生這種情況。在支援使用 Permissions Policy 管理媒體許可權的瀏覽器上，如果 Permissions Policy 未配置為允許訪問輸入源，則返回此錯誤。

注意： 規範的舊版本使用 SecurityError 代替此錯誤；SecurityError 已具有新含義。
NotFoundError DOMException: 如果未找到滿足給定約束條件的指定型別的媒體軌道，則丟擲此異常。
NotReadableError DOMException: 如果使用者已授予使用匹配裝置的許可權，但作業系統、瀏覽器或網頁級別發生硬體錯誤，阻止了對裝置的訪問，則丟擲此異常。
OverconstrainedError DOMException: 如果指定的約束條件導致沒有符合請求標準的候選裝置，則丟擲此異常。該錯誤是一個 OverconstrainedError 型別的物件，並具有一個 constraint 屬性，其字串值是無法滿足的約束條件的名稱，以及一個 message 屬性，其中包含解釋問題的可讀字串。

注意： 由於此錯誤甚至可能在使用者尚未授予使用底層裝置的許可權時發生，因此它可能被用作指紋識別表面。
SecurityError DOMException: 如果呼叫 getUserMedia() 的 Document 上停用了使用者媒體支援，則丟擲此異常。啟用和停用使用者媒體支援的機制由各個使用者代理自行決定。
TypeError: 如果指定的約束列表為空，或所有約束都設定為 false，則丟擲此異常。如果在不安全的環境中嘗試呼叫 getUserMedia() 也可能發生這種情況，因為在不安全的環境中 navigator.mediaDevices 是 undefined。

隱私和安全

作為一項可能涉及重大隱私問題的 API，getUserMedia() 的規範規定了瀏覽器必須滿足的廣泛隱私和安全要求。

getUserMedia() 是一項強大的功能，只能在安全上下文中使用；在不安全上下文中，navigator.mediaDevices 是 undefined，從而阻止訪問 getUserMedia()。簡而言之，安全上下文是使用 HTTPS 或 file:/// URL 方案載入的頁面，或從 localhost 載入的頁面。