MediaDevices.getDisplayMedia()

这个 MediaDevices  接口的 getDisplayMedia() 方法提示用户去选择和授权捕获展示的内容或部分内容(如一个窗口)在一个  MediaStream 里. 然后流能被用 MediaStream Recording API 记录或传输一部分去一个WebRTC 会话.

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

语法

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

参数

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

返回值

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

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

异常

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

AbortError [中止错误]
发生了与以下任何其他异常不匹配的错误或故障。
InvalidStateError [拒绝错误]
调用 getDisplayMedia() 的context中的 document 不是完全激活的; 例如,也许它不是最前面的标签。
NotAllowedError [拒绝错误]
用户拒绝授予访问屏幕区域的权限,或者不允许当前浏览实例访问屏幕共享。
NotFoundError [找不到错误]
没有可用于捕获的屏幕视频源。
NotReadableError [无法读取错误]
用户选择了屏幕,窗口,标签或其他屏幕数据源,但发生了硬件或操作系统级别错误或锁定,从而预先占用了共享所选源。
OverconstrainedError [转换错误]
创建流后,由于无法生成兼容的流导致应用指定的 constraints 失效。
TypeError [类型错误]
指定的 constraints 包括调用 getDisplayMedia() 时不允许的constraints。 这些不受支持的constraintsadvanced 的,任何约束又有一个名为 minexact 的成员。

示例

在下面的示例中,我们创建了一个 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调用来从流中添加视频轨道。

规范

规范 状态 备注
Screen Capture
MediaDevices.getDisplayMedia()
Working Draft 初始定义

浏览器兼容性

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
getDisplayMedia()Chrome Full support 72
Full support 72
No support 70 — 72
Notes Disabled
Notes Available as a member of Navigator instead of MediaDevices in Chrome 70 and 71.
Disabled From version 70 until version 72 (exclusive): this feature is behind the Experimental Web Platform features preference (needs to be set to Enabled). To change preferences in Chrome, visit chrome://flags.
Edge Full support 17
Notes
Full support 17
Notes
Notes Available as a member of Navigator instead of MediaDevices.
Firefox Full support 66
Full support 66
No support 33 — 66
Notes
Notes Since Firefox 33 you can capture screen data using getUserMedia(), with a video constraint called mediaSource. Prior to 52 it relied on a client-configurable whitelist.
IE No support NoOpera ? Safari No support NoWebView Android No support No
Notes
No support No
Notes
Notes API is available, but will always fail with NotAllowedError.
Chrome Android No support NoFirefox Android No support No
Notes
No support No
Notes
Notes API is available, but will always fail with NotAllowedError.
Opera Android Full support YesSafari iOS No support NoSamsung Internet Android ?
Audio capture supportChrome Full support 74
Notes
Full support 74
Notes
Notes On Windows the entire system audio can be captured, but on Linux and Mac only the audio of a tab can be captured.
Edge ? Firefox No support NoIE No support NoOpera ? Safari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android ? Safari iOS No support NoSamsung Internet Android No support No

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
See implementation notes.
See implementation notes.
User must explicitly enable this feature.
User must explicitly enable this feature.

参考

文档标签和贡献者

此页面的贡献者: SphinxKnight, estKey, w3cways, liumingsongning
最后编辑者: SphinxKnight,