Screen Capture API

螢幕捕獲 API 的概念和用法

螢幕捕獲 API 的使用相對簡單。其主要方法是 MediaDevices.getDisplayMedia()，它的作用是請求使用者選擇一個螢幕或螢幕的一部分進行捕獲，並以 MediaStream 的形式返回。

要開始從螢幕捕獲影片，請在 navigator.mediaDevices 上呼叫 getDisplayMedia()。

captureStream =
  await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);

getDisplayMedia() 返回的 Promise 會解析為一個 MediaStream，該流包含捕獲的顯示錶面。

請參閱文章 使用螢幕捕獲 API，以更深入地瞭解如何使用該 API 將螢幕內容捕獲為流。

螢幕捕獲擴充套件

螢幕捕獲 API 具有擴充套件其功能的附加特性。

限制捕獲到流中的螢幕區域

• 元素捕獲 API 將捕獲區域限制為指定的已渲染 DOM 元素及其子元素。
• 區域捕獲 API 將捕獲區域裁剪到螢幕中指定 DOM 元素所渲染的區域。

請參閱 使用元素捕獲和區域捕獲 API 以瞭解更多資訊。

控制捕獲的螢幕區域

捕獲表面控制 API 允許捕獲應用程式對捕獲的顯示錶面進行有限的控制，例如縮放和滾動其內容。

請參閱 使用捕獲表面控制 API 以瞭解更多資訊。

介面

BrowserCaptureMediaStreamTrack

表示單個影片軌道；透過擴充套件 MediaStreamTrack 類，並提供方法來限制捕獲的使用者自己的捕獲流（例如，使用者螢幕或視窗）的部分。

CaptureController

提供可用於進一步操作透過 MediaDevices.getDisplayMedia() 捕獲的顯示錶面的方法。透過將 CaptureController 物件作為 getDisplayMedia() 呼叫中 options 物件的 controller 屬性的值傳遞，可以將其與捕獲的顯示錶面關聯起來。

CropTarget

提供一個靜態方法，fromElement()，它返回一個 CropTarget 例項，可用於將捕獲的影片軌道裁剪到指定元素所渲染的區域。

RestrictionTarget

提供一個靜態方法，fromElement()，它返回一個 RestrictionTarget 例項，可用於將捕獲的影片軌道限制為指定的 DOM 元素。

對 MediaDevices 介面的補充

MediaDevices.getDisplayMedia()

getDisplayMedia() 方法已新增到 MediaDevices 介面中。與 getUserMedia() 類似，此方法建立一個 Promise，該 Promise 解析為一個 MediaStream，其中包含使用者選擇的顯示區域，格式與指定的選項匹配。

對現有字典的補充

螢幕捕獲 API 向其他規範中定義的以下字典添加了屬性。

MediaTrackConstraints

MediaTrackConstraints.displaySurface

一個 ConstrainDOMString，指示要捕獲的顯示錶面的型別。該值是 browser、monitor 或 window 之一。

MediaTrackConstraints.logicalSurface

指示流中的影片是否代表一個邏輯顯示錶面（即，可能並未完全顯示在螢幕上，或者可能完全在螢幕外）。值為 true 表示要捕獲一個邏輯顯示錶面。

MediaTrackConstraints.suppressLocalAudioPlayback

控制當捕獲某個標籤頁時，標籤頁中播放的音訊是否會繼續透過使用者的本地揚聲器播放，還是會被抑制。值為 true 表示將抑制音訊。

MediaTrackSettings

MediaTrackSettings.cursor

一個字串，指示當前捕獲的顯示錶面是否包含滑鼠游標，如果包含，則僅在滑鼠移動時可見還是始終可見。該值是 always、motion 或 never 之一。

MediaTrackSettings.displaySurface

一個字串，指示當前捕獲的顯示錶面的型別。該值是 browser、monitor 或 window 之一。

MediaTrackSettings.logicalSurface

一個布林值，如果捕獲的影片不直接對應於單個螢幕顯示區域，則為 true。

MediaTrackSettings.suppressLocalAudioPlayback

一個布林值，如果捕獲的音訊未透過使用者的本地揚聲器播放，則為 true。

MediaTrackSettings.screenPixelRatio

一個數字，表示捕獲的顯示錶面上的畫素的物理尺寸（以其物理解析度顯示）與捕獲螢幕上的 CSS 畫素的邏輯尺寸（以其邏輯解析度顯示）之比。它不能用作約束或功能。

MediaTrackSupportedConstraints

MediaTrackSupportedConstraints.displaySurface

一個布林值，如果當前環境支援 MediaTrackConstraints.displaySurface 約束，則為 true。

MediaTrackSupportedConstraints.logicalSurface

一個布林值，如果當前環境支援 MediaTrackConstraints.logicalSurface 約束，則為 true。

MediaTrackSupportedConstraints.suppressLocalAudioPlayback

一個布林值，如果當前環境支援 MediaTrackConstraints.suppressLocalAudioPlayback 約束，則為 true。

安全注意事項

支援 許可權策略的網站（透過 HTTP Permissions-Policy 標頭或 <iframe> 屬性 allow）可以使用 display-capture 指令來宣告使用螢幕捕獲 API 的意圖。

<iframe allow="display-capture" src="/some-other-document.html">…</iframe>

網站還可以透過 captured-surface-control 指令來宣告使用 捕獲表面控制 API 的意圖。具體來說，forwardWheel()、increaseZoomLevel()、decreaseZoomLevel() 和 resetZoomLevel() 方法受此指令控制。

這兩個指令的預設允許列表是 self，它允許同一來源的任何內容使用螢幕捕獲。

這些方法被視為強大功能，這意味著即使透過 Permissions-Policy 允許了許可權，使用者仍然會被提示是否允許使用它們。Permissions API 可用於查詢使用已列出功能的聚合許可權（來自網站和使用者）。

此外，規範要求使用者必須最近與頁面進行過互動才能使用這些功能，這意味著需要短暫啟用。有關更多詳細資訊，請參閱各個方法頁面。

規範

瀏覽器相容性

api.MediaDevices.getDisplayMedia

api.CropTarget

api.RestrictionTarget

另見

• 使用螢幕捕獲 API
• 使用元素捕獲和區域捕獲 API
• 使用 Captured Surface Control API
• MediaDevices.getDisplayMedia()