1. Web
  2. Web API
  3. MediaDevices
  4. getDisplayMedia()

MediaDevices: getDisplayMedia() 方法

可用性有限

此特性不是基線特性，因為它在一些最廣泛使用的瀏覽器中不起作用。

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

MediaDevices 介面的 getDisplayMedia() 方法會提示使用者選擇一個顯示器或顯示器的一部分（例如一個視窗）並授予許可權，將其捕獲為一個 MediaStream。

生成的流隨後可以使用 MediaStream 錄製 API 進行錄製，或者作為 WebRTC 會話的一部分進行傳輸。

有關更多詳細資訊和示例，請參閱 使用螢幕捕獲 API。

語法

js
getDisplayMedia()
getDisplayMedia(options)

引數

options 可選

一個指定返回的 MediaStream 要求的物件。getDisplayMedia() 的選項與 MediaDevices.getUserMedia() 方法的 約束 的工作方式相同，儘管在這種情況下只能指定 audio 和 video。getDisplayMedia() 可能的選項屬性列表如下：

video 可選

一個布林值或 MediaTrackConstraints 例項；預設值為 true。如果省略此選項或將其設定為 true，則返回的 MediaStream 將包含一個影片軌道。由於 getDisplayMedia() 需要影片軌道，如果此選項設定為 false，則 Promise 將以 TypeError 拒絕。

audio 可選

一個布林值或 MediaTrackConstraints 例項；預設值為 false。值為 true 表示返回的 MediaStream 將包含一個音訊軌道，前提是音訊受支援並且可用於使用者選擇的顯示錶面。

controller 可選

一個 CaptureController 物件例項，其中包含可用於進一步操作捕獲會話的方法（如果包含）。

monitorTypeSurfaces 可選

一個列舉值，指定瀏覽器是否應在呈現給使用者的螢幕捕獲選項中，除了標籤頁和視窗選項之外，還提供整個螢幕的選項。此選項旨在防止使用者因錯誤操作而在使用視訊會議應用時洩露私人資訊。可能的值為：

  • include: 提示瀏覽器應包含螢幕選項。
  • exclude: 提示應排除螢幕選項。

注意： 您不能同時設定 monitorTypeSurfaces: "exclude" 和 displaySurface: "monitor"，因為這兩個設定是矛盾的。嘗試這樣做會導致 getDisplayMedia() 呼叫以 TypeError 失敗。

preferCurrentTab 可選

一個布林值；值為 true 會指示瀏覽器將當前標籤頁作為最突出的捕獲源提供，即作為使用者在“選擇要共享的內容”選項中“此標籤頁”的單獨選項。這很有用，因為許多應用型別通常只需要共享當前標籤頁。例如，一個幻燈片應用可能希望允許使用者將包含簡報的當前標籤頁流式傳輸到虛擬會議。

selfBrowserSurface 可選

一個列舉值，指定瀏覽器是否應允許使用者選擇當前標籤頁進行捕獲。這有助於避免視訊會議應用無意中共享自身顯示時出現的“無限鏡廳”效應。可能的值為：

  • include: 提示瀏覽器應在提供的捕獲選項中包含當前標籤頁。
  • exclude: 提示應從選項中排除當前標籤頁。
surfaceSwitching 可選

一個列舉值，指定瀏覽器是否應顯示一個控制元件，允許使用者在螢幕共享期間動態切換共享的標籤頁。這比使用者每次想要切換共享標籤頁時都必須重新經歷整個共享過程要方便得多。可能的值為：

  • include: 提示瀏覽器應包含該控制元件。
  • exclude: 提示不應顯示該控制元件。
systemAudio 可選

一個列舉值，指定瀏覽器是否應在提供給使用者的可能音訊源中包含系統音訊。可能的值為：

  • include: 提示瀏覽器應在選項列表中包含系統音訊。
  • exclude: 提示應從顯示的選項中排除系統音訊。
windowAudio 可選

一個列舉值，提示瀏覽器在提供視窗共享選項時，應向用戶呈現哪種音訊共享選項。可能的值為：

  • exclude: 提示當選擇視窗共享選項時，音訊不應可共享。
  • window: 提示當選擇視窗共享選項時，只應共享來自該視窗的音訊。
  • system: 提示當選擇視窗共享選項時，應共享所有系統音訊。

注意： 對於這些選項中的大多數，規範並未強制規定預設值。對於未提及預設值的獨立選項，請參閱 瀏覽器相容性 部分以獲取特定於瀏覽器的預設值。

注意： 有關這些選項如何工作的更多詳細資訊，請參閱文章 能力、約束和設定。

返回值

一個 Promise，它解析為一個 MediaStream，該流包含一個影片軌道（其內容來自使用者選擇的螢幕區域）以及一個可選的音訊軌道。

注意： 瀏覽器對音訊軌道的支援各不相同，包括媒體錄製器是否支援它們，以及支援的音訊源。有關每個瀏覽器的詳細資訊，請檢視 相容性表格。

異常

AbortError DOMException

如果在其他列出的異常之外發生錯誤或失敗，則丟擲此異常。

InvalidStateError DOMException

如果 getDisplayMedia() 的呼叫不是由由於 瞬時啟用（如事件處理程式）而執行的程式碼引起的。或者瀏覽器上下文未完全啟用或未獲得焦點。或者 controller 選項已用於建立另一個 MediaStream。則丟擲此異常。

NotAllowedError DOMException

如果使用者拒絕訪問螢幕區域的許可權，或者當前瀏覽例項不允許訪問螢幕共享（例如，透過 許可權策略），則丟擲此異常。

NotFoundError DOMException

如果沒有可供捕獲的螢幕影片源，則丟擲此異常。

NotReadableError DOMException

如果使用者選擇了螢幕、視窗、標籤頁或其他螢幕資料來源，但發生了硬體或作業系統級別的錯誤或鎖定，導致無法共享選定的源，則丟擲此異常。

OverconstrainedError DOMException

如果建立流後，應用任何指定的約束均因無法生成相容的流而失敗，則丟擲此異常。

TypeError

如果指定的 options 包含在呼叫 getDisplayMedia() 時不允許的值（例如，video 屬性設定為 false），或者任何指定的 MediaTrackConstraints 不允許，則丟擲此異常。在 getDisplayMedia() 呼叫中使用的約束不允許 min 和 exact 值。

安全

由於 getDisplayMedia() 可能被用於不良用途，因此它可能帶來重大的隱私和安全隱患。為此，規範詳細說明了瀏覽器必須採取的措施才能完全支援 getDisplayMedia()。

  • 指定的選項不能用於限制使用者可用的選擇。相反，它們必須在使用者選擇源後應用，才能生成與選項匹配的輸出。
  • 使用 getDisplayMedia() 的許可不能持久化以供重用。每次都必須提示使用者授予許可權。
  • 需要瞬時使用者啟用。使用者必須與頁面或 UI 元素進行互動才能使此功能正常工作。
  • 鼓勵瀏覽器向用戶發出關於共享包含瀏覽器的顯示器或視窗的警告，並密切關注可能被捕獲並展示給其他使用者的內容。

示例

下面的示例建立了一個 startCapture() 方法，該方法根據 displayMediaOptions 引數指定的選項集啟動螢幕捕獲。

js
const displayMediaOptions = {
  video: {
    displaySurface: "browser",
  },
  audio: {
    suppressLocalAudioPlayback: false,
  },
  preferCurrentTab: false,
  selfBrowserSurface: "exclude",
  systemAudio: "include",
  surfaceSwitching: "include",
  monitorTypeSurfaces: "include",
};

async function startCapture(displayMediaOptions) {
  let captureStream;

  try {
    captureStream =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
  } catch (err) {
    console.error(`Error: ${err}`);
  }
  return captureStream;
}

這使用了 await 來非同步等待 getDisplayMedia() 解析為 MediaStream，該流包含根據指定選項請求的顯示內容。然後將該流返回給呼叫者使用，或許可以使用 RTCPeerConnection.addTrack() 將流中的影片軌道新增到 WebRTC 呼叫中。

注意： 螢幕共享控制元件演示提供了一個完整的實現，允許您使用您選擇的 getDisplayMedia() 約束和選項來建立螢幕捕獲。

規範

規範
螢幕捕獲
# dom-mediadevices-getdisplaymedia

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

此頁面最後由 MDN 貢獻者於 修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題
© . Content available under a Creative Commons license.