MediaDevices.getDisplayMedia() - Web API 接口参考 编辑

这个 MediaDevices  接口的 getDisplayMedia() 方法提示用户去选择和授权捕获展示的内容或部分内容（如一个窗口）在一个  MediaStream 里. 然后，这个媒体流可以通过使用 MediaStream Recording API 被记录或者作为WebRTC 会话的一部分被传输。

去 Using the Screen Capture API 查找更多详情和例子.

语法

var promise = navigator.mediaDevices.getDisplayMedia(constraints);

参数

constraints 可选

一个可选的MediaStreamConstraints对象，它指定了返回的MediaStream的要求。 因为getDisplayMedia()需要视频轨道，所以即使constraints 对象没有明确请求视频轨道，返回的流也会有一个。

返回值

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

Note: 浏览器对音频的支持程度各不相同，既取决于是否支持，也取决于音频源. 点击 compatibility table 来查看各个浏览器的支持性.

异常

来自返回的promise的拒绝是通过将DOMException错误对象传递给promise的失败处理程序来进行的。可能的错误是：

AbortError ［中止错误］

发生了与以下任何其他异常不匹配的错误或故障。

InvalidStateError ［拒绝错误］

调用 getDisplayMedia() 的context中的 document 不是完全激活的; 例如，也许它不是最前面的标签。

NotAllowedError ［拒绝错误］

用户拒绝授予访问屏幕区域的权限，或者不允许当前浏览实例访问屏幕共享。

NotFoundError ［找不到错误］

没有可用于捕获的屏幕视频源。

NotReadableError ［无法读取错误］

用户选择了屏幕，窗口，标签或其他屏幕数据源，但发生了硬件或操作系统级别错误或锁定，从而预先占用了共享所选源。

OverconstrainedError ［转换错误］

创建流后，由于无法生成兼容的流导致应用指定的 constraints 失效。

TypeError ［类型错误］

指定的 constraints 包括调用 getDisplayMedia() 时不允许的constraints。 这些不受支持的constraints是 advanced 的，任何约束又有一个名为 min 或 exact 的成员。

示例

在下面的示例中，我们创建了一个 startCapture() 方法，该方法在给定由 displayMediaOptions 参数指定的一组选项的情况下启动屏幕捕获。 选项以 MediaStreamConstraints对象的形式指定，该对象指定首选流配置和从中捕获视频的显示表面

async function startCapture(displayMediaOptions) {
  let captureStream = null;

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

这里使用 await 来进行异步等待 getDisplayMedia()来进行 MediaStream解析，其中包含指定选项所请求的显示内容。 之后，流被返回给调用者以供其使用，可能是使用 RTCPeerConnection.addTrack()添加到WebRTC调用来从流中添加视频轨道。

规范

浏览器兼容性

BCD tables only load in the browser

参考

• Screen Capture API
• Using the Screen Capture API
• Media Capture and Streams API
• WebRTC API
• getUserMedia(): Capturing media from a camera and/or microphone