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()