能力中的 API
Screen Capture API(getDisplayMedia)
发布于 更新于
navigator.mediaDevices.getDisplayMedia() 让用户选择要共享的屏幕、窗口或标签页,返回的 MediaStream 可交给 MediaRecorder、<video> 元素或 RTCPeerConnection。流中恰好有一条视频轨,至多有一条音频轨。
这项授权不像 getUserMedia() 那样持久保存。浏览器每次调用都会弹出选择器,页面不能枚举显示源或预选其中一个。
桌面端的 Chrome 72、Edge 79、Firefox 66 与 macOS 上的 Safari 13 实现了它(Edge 17 到 79 在 navigator 上暴露过早期版本)。Android 上的 Chrome 72 到 88 与 Firefox 66 到 79 暴露了该方法,但每次调用都以 NotAllowedError 拒绝(Chromium bug 40418135);如今 Android 上的 Chrome 与 Firefox 不再暴露它,BCD 记录 iOS 上的 Safari 从 27 起支持它(BCD api.MediaDevices.getDisplayMedia)。video 与 audio 之外的捕获选项只有 Chromium 实现。
navigator.mediaDevices.getDisplayMedia()navigator.mediaDevices.getDisplayMedia(options)返回 Promise<MediaStream>。调用需要瞬时激活、处于 fully active 且拥有焦点的文档、安全上下文,以及 display-capture Permissions Policy(默认允许列表为 'self',跨源 iframe 需要 allow="display-capture")。浏览器会消耗这次激活,第二次调用需要再点一次。
唯一的可选参数是 DisplayMediaStreamOptions 字典。video 与 audio 来自 W3C 规范;其余成员是浏览器可以忽略的提示,只有 Chromium 实现(版本号来自 BCD)。
| 成员 | 类型 | 必填 | 说明 |
|---|---|---|---|
video |
boolean 或 MediaTrackConstraints |
否,默认 true |
传 false 以 TypeError 拒绝。约束对象可带作为提示的 displaySurface("browser"、"window"、"monitor")以及 width、height、frameRate、aspectRatio、cursor;约束在用户选定之后才应用,不会过滤选择器。min、exact 与 advanced 会被拒绝。 |
audio |
boolean 或 MediaTrackConstraints |
否,默认 false |
请求音频轨;浏览器可以只返回视频。Chrome 74 在 Windows 与 ChromeOS 上捕获系统音频,其他平台只捕获标签页音频。 |
controller |
CaptureController |
否 | 用户选定标签页或窗口后,让页面通过 setFocusBehavior() 保留或转移焦点;每次调用一个控制器。Chrome 109。 |
preferCurrentTab |
boolean |
否,默认 false |
把调用方标签页排在选择器最前。Chrome 94。 |
selfBrowserSurface |
"include" 或 "exclude" |
否 | 调用方标签页是否出现在选择器中;Chrome 112 默认 "exclude"(107 到 111 默认 "include")。 |
surfaceSwitching |
"include" 或 "exclude" |
否 | 捕获期间 Chrome 是否显示「改为共享此标签页」控件。Chrome 107。 |
systemAudio |
"include" 或 "exclude" |
否 | 选择整个屏幕时选择器是否提供系统音频。Chrome 105。 |
windowAudio |
"exclude"、"window" 或 "system" |
否 | 选择窗口时提供的音频;Chrome 141 只接受 "exclude" 与 "system"。 |
monitorTypeSurfaces |
"include" 或 "exclude" |
否 | 是否提供整个屏幕作为选项。Chrome 119。 |
Promise 拒绝时会返回下列异常之一。Chrome 的错误消息引自 media_devices.cc。
| 异常 | 条件 |
|---|---|
InvalidStateError |
没有瞬时激活(Chrome:getDisplayMedia() requires transient activation (user gesture).);文档不是 fully active 或没有焦点;传入的 controller 已被用过(Chrome:A CaptureController object may only be used with a single getDisplayMedia() invocation.)。 |
TypeError |
video: false,或约束集中含 advanced、min 或 exact。 |
OverconstrainedError |
某个 max 约束低于该属性的下限,或对所选表面应用约束失败。 |
NotAllowedError |
用户关闭了选择器、权限状态为 "denied"、操作系统或企业策略禁止捕获,或 display-capture Permissions Policy 拒绝了该文档(Chrome:Access to the feature "display-capture" is disallowed by permissions policy.)。 |
NotFoundError |
不存在所请求类型的源。 |
NotReadableError |
用户已授权,但操作系统层面的锁阻止读取该表面。 |
AbortError |
设备访问因上述之外的原因失败。 |
在按钮点击处理器里开始捕获,以满足用户激活要求。调用前先检查方法是否存在,并处理无法捕获或用户拒绝的情况。
预览所选表面,不可用时给出提示
链接到“预览所选表面,不可用时给出提示”一节检测 navigator.mediaDevices 上的 getDisplayMedia;在非安全源上 mediaDevices 本身就不存在。方法缺失说明该浏览器不提供屏幕捕获,例如 Android 上的 Chrome 与 Firefox。选择器出现后的 NotAllowedError 常见原因是用户拒绝或取消了共享,通常不必上报为失败。
const button = document.querySelector("#share-screen");const preview = document.querySelector("video#preview");const notice = document.querySelector("#capture-notice");
if (!navigator.mediaDevices?.getDisplayMedia) { button.disabled = true; notice.textContent = "此浏览器不支持屏幕共享。";} else { button.addEventListener("click", async () => { try { const stream = await navigator.mediaDevices.getDisplayMedia({ video: { displaySurface: "window" }, audio: false, }); preview.srcObject = stream; stream.getVideoTracks()[0].addEventListener("ended", () => { preview.srcObject = null; // 用户点了浏览器自己的「停止共享」控件 }); } catch (err) { notice.textContent = err.name === "NotAllowedError" ? "已取消共享。" : `${err.name}: ${err.message}`; } });}ended 事件是用户从浏览器自身 UI 停止共享的唯一信号;不监听它,<video> 会一直停在最后一帧。
用 MediaRecorder 把标签页录成 WebM
链接到“用 MediaRecorder 把标签页录成 WebM”一节用 preferCurrentTab(Chrome 94 的提示,其他浏览器忽略)请求当前标签页并带音频,再把流交给 MediaRecorder。轨道结束时停止录制器,这样用户从浏览器工具栏或你的按钮结束共享时,文件都能正常收尾。
async function recordTab() { if (!navigator.mediaDevices?.getDisplayMedia || typeof MediaRecorder === "undefined") { return null; } const stream = await navigator.mediaDevices.getDisplayMedia({ video: true, audio: true, preferCurrentTab: true, }); const recorder = new MediaRecorder(stream, { mimeType: "video/webm" }); const chunks = []; recorder.addEventListener("dataavailable", (event) => chunks.push(event.data));
const done = new Promise((resolve) => { recorder.addEventListener("stop", () => resolve(new Blob(chunks, { type: "video/webm" }))); }); stream.getVideoTracks()[0].addEventListener("ended", () => recorder.stop()); recorder.start(1000); return { stop: () => recorder.stop(), done };}向用户提示音频可用前,先检查 stream.getAudioTracks().length。Firefox 与 Safari 只返回视频,macOS 与 Linux 上的 Chrome 只在共享标签页时带音频,窗口与屏幕都没有。
用 CaptureController 让焦点留在你的页面
链接到“用 CaptureController 让焦点留在你的页面”一节选择器关闭后,Chrome 默认把焦点切到正在捕获的标签页或窗口,挡住用户刚点过的控件。先创建 CaptureController,再发起捕获,就可以要求 Chrome 保留原来的焦点。必须在 Promise 兑现后的那一刻调用;其他浏览器没有这个构造函数。
async function startCaptureKeepingFocus() { const options = { video: true }; let controller = null; if ("CaptureController" in window) { controller = new CaptureController(); options.controller = controller; } const stream = await navigator.mediaDevices.getDisplayMedia(options); if (controller && stream.getVideoTracks()[0].getSettings().displaySurface !== "monitor") { controller.setFocusBehavior("no-focus-change"); } return stream;}捕获整个屏幕时没有可聚焦的对象,浏览器会忽略 setFocusBehavior();规范的「finalize focus decision」步骤在 Promise 兑现后紧接着排队的任务里执行,此后再调用会抛 InvalidStateError,所以 await 之后要同步调用。
另请参阅
链接到“另请参阅”一节- WebRTC,把捕获到的流发给另一端
- WebCodecs,不经
MediaRecorder直接编码捕获帧 - Document Picture-in-Picture,用户切到别处时让捕获控件保持可见
- Screen Capture: getDisplayMedia() method(w3.org)
- Screen Capture: DisplayMediaStreamOptions dictionary(w3.org)
- Better screen sharing with Conditional Focus and the other screen-sharing controls(developer.chrome.com)
- Chromium bug 40418135: getDisplayMedia on Android(crbug.com)
规范
| 规范 | 状态 |
|---|---|
| Screen Capture: getDisplayMedia() method | W3C |
| Screen Capture: DisplayMediaStreamOptions dictionary | W3C |