跳转到内容

能力中的 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> 会一直停在最后一帧。

用 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 之后要同步调用。

规范

规范状态
Screen Capture: getDisplayMedia() methodW3C
Screen Capture: DisplayMediaStreamOptions dictionaryW3C