MediaDevices: getDisplayMedia() 方法

安全上下文：此功能仅在安全上下文（HTTPS）中可用，在支持的浏览器中部分或全部可用。

getDisplayMedia() 是 MediaDevices 接口的方法，它会提示用户选择并授予捕获显示屏内容或其部分内容（如窗口）作为 MediaStream 的权限。

然后可以使用 MediaStream 录制 API 录制生成的流，或将其作为 WebRTC 会话的一部分进行传输。

有关详细信息和示例，请参阅使用屏幕捕捉 API。

语法

getDisplayMedia()
getDisplayMedia(options)

参数

options 可选

一个可选对象，指定返回的 MediaStream 的要求。getDisplayMedia() 的选项与约束的选项相同 MediaDevices.getUserMedia() 方法，尽管在这种情况下只能指定 audio 和 video。getDisplayMedia() 的可能的选项属性列表如下

video 可选: 一个布尔值或一个 MediaTrackConstraints 实例；默认值为 true。如果省略此选项或将其设置为 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，提示应该将它排除在外。规范中没有强制指定默认值；请参阅浏览器兼容性部分，了解特定浏览器的默认值。
monitorTypeSurfaces 实验性可选: 一个枚举值，指定应用程序是否希望用户代理向用户提供选择类型为显示器的显示界面的选项。可能的值为 include，提示浏览器应该包含类型为显示器的显示界面，以及 exclude，提示应该将它排除在外。规范中没有强制指定默认值；请参阅浏览器兼容性部分，了解特定浏览器的默认值。

注意：有关这些选项如何工作的更多详细信息，请参阅文章功能、约束和设置。

返回值

一个 Promise，它解析为一个 MediaStream，其中包含一个视频轨道，其内容来自用户选择的屏幕区域，以及一个可选的音频轨道。

注意：浏览器对音频轨道的支持存在差异，包括媒体记录器是否支持，以及支持的音频源。请查看兼容性表，了解每个浏览器的详细信息。

异常

AbortError DOMException: 如果错误或故障与这里列出的任何其他异常不匹配，则抛出此异常。
InvalidStateError DOMException: 如果调用 getDisplayMedia() 不是从由于瞬时激活而运行的代码（例如事件处理程序）中进行的，则抛出此异常。或者，如果浏览器上下文未完全激活或未处于焦点状态。或者，如果 controller 选项已用于创建另一个 MediaStream。
NotAllowedError DOMException: 如果用户拒绝了访问屏幕区域的权限，或者当前浏览实例不允许访问屏幕共享（例如，通过权限策略），则抛出此异常。
NotFoundError DOMException: 如果没有任何可用于捕获的屏幕视频源，则抛出此异常。
NotReadableError DOMException: 如果用户选择了屏幕、窗口、选项卡或其他屏幕数据源，但硬件或操作系统级别发生错误或锁定，从而阻止了所选源的共享，则抛出此异常。
OverconstrainedError DOMException: 如果在创建流后，由于无法生成兼容的流，而导致应用任何指定的约束失败，则抛出此异常。
TypeError: 如果指定的 options 包含调用 getDisplayMedia() 时不允许的值，例如将 video 属性设置为 false，或者任何指定的 MediaTrackConstraints 不允许，则抛出此异常。min 和 exact 值在 getDisplayMedia() 调用中使用的约束中是不允许的。

安全性

由于 getDisplayMedia() 可能被用于恶意目的，因此它可能是重大隐私和安全问题的一个来源。出于这个原因，该规范详细说明了浏览器为了完全支持 getDisplayMedia() 而必须采取的措施。

指定的选项不能用于限制用户可用的选择。相反，它们必须在用户选择源后应用，以便生成与选项匹配的输出。
使用 getDisplayMedia() 的许可不能持久化以供重复使用。每次都必须提示用户进行许可。
瞬时用户激活是必需的。用户必须与页面或 UI 元素进行交互，才能使用此功能。
鼓励浏览器向用户提供有关共享包含浏览器的显示器或窗口的警告，并密切关注可能被捕获并显示给其他用户的内容。

示例

在下面的示例中，创建了一个 startCapture() 方法，该方法在 displayMediaOptions 参数指定的选项集中启动屏幕捕获。

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

浏览器兼容性

BCD 表格仅在浏览器中加载