MediaDevices.getDisplayMedia()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

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

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

语法

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

参数

constraints 可选

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

返回值

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

备注: 浏览器对音频的支持程度各不相同,既取决于是否支持,也取决于音频源。点击 浏览器兼容性 来查看各个浏览器的支持性。

异常

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

AbortError [中止错误]

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

InvalidStateError [拒绝错误]

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

NotAllowedError [拒绝错误]

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

NotFoundError [找不到错误]

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

NotReadableError [无法读取错误]

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

OverconstrainedError [转换错误]

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

TypeError [类型错误]

指定的 constraints 包括调用 getDisplayMedia() 时不允许的constraints。这些不受支持的constraintsadvanced 的,任何约束又有一个名为 minexact 的成员。

示例

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

js
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 调用来从流中添加视频轨道。

规范

Specification
Screen Capture
# dom-mediadevices-getdisplaymedia

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
getDisplayMedia()
Audio capture support
controller option
Experimental
monitorTypeSurfaces option
Experimental
preferCurrentTab option
ExperimentalNon-standard
selfBrowserSurface option
Experimental
surfaceSwitching option
Experimental
systemAudio option
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
See implementation notes.
Has more compatibility info.

参考