通过条件聚焦功能更好地共享屏幕

François Beaufort
François Beaufort
GitHub
Elad Alon

Browser Support

  • Chrome: 109.
  • Edge: 109.
  • Firefox: not supported.
  • Safari: not supported.

Source

借助 Screen Capture API，用户可以选择要捕获为媒体流的标签页、窗口或屏幕。然后，此流可以被录制或通过网络与他人共享。本文档介绍了条件焦点，这是一种机制，可让 Web 应用控制在捕获开始时是否将焦点放在捕获的标签页或窗口上，或者捕获页面是否会保持焦点。

浏览器支持

条件焦点在 Chrome 109 及更高版本中提供。

背景

当 Web 应用开始捕获标签页或窗口时，浏览器会面临一个决定：是将捕获的表面置于最前面，还是让捕获页面保持焦点？答案取决于调用 getDisplayMedia() 的原因，以及用户最终选择的表面。

考虑一个假设的 视频会议 Web 应用。通过读取 track.getSettings().displaySurface 并可能检查 捕获句柄，视频会议 Web 应用可以了解用户选择共享的内容。然后：

  • 如果捕获的标签页或窗口可以远程控制，请将焦点放在视频会议上。
  • 否则，请将焦点放在捕获的标签页或窗口上。

在上面的示例中，如果共享幻灯片演示文稿，视频会议 Web 应用将保留焦点，允许用户远程翻阅幻灯片；但如果用户选择共享文本编辑器，视频会议 Web 应用会立即将焦点切换到捕获的标签页或窗口。

使用条件焦点 API

实例化 CaptureController 并将其传递给 getDisplayMedia()。通过在 getDiplayMedia() 返回的 promise 解析后立即调用 setFocusBehavior()，您可以控制是否将焦点放在捕获的标签页或窗口上。只有在用户共享标签页或窗口时，才能执行此操作。

const controller = new CaptureController();

// Prompt the user to share a tab, a window or a screen.
const stream =
    await navigator.mediaDevices.getDisplayMedia({ controller });

const [track] = stream.getVideoTracks();
const displaySurface = track.getSettings().displaySurface;
if (displaySurface == "browser") {
  // Focus the captured tab.
  controller.setFocusBehavior("focus-captured-surface");
} else if (displaySurface == "window") {
  // Do not move focus to the captured window.
  // Keep the capturing page focused.
  controller.setFocusBehavior("focus-capturing-application");
}

在决定是否将焦点放在捕获的标签页或窗口上时，可以考虑捕获句柄。

// Retain focus if capturing a tab dialed to example.com.
// Focus anything else.
const origin = track.getCaptureHandle().origin;
if (displaySurface == "browser" && origin == "https://example.com") {
  controller.setFocusBehavior("focus-capturing-application");
} else if (displaySurface != "monitor") {
  controller.setFocusBehavior("focus-captured-surface");
}

甚至可以在调用 getDisplayMedia() 之前决定是否将焦点放在捕获的标签页或窗口上。

// Focus the captured tab or window when capture starts.
const controller = new CaptureController();
controller.setFocusBehavior("focus-captured-surface");

// Prompt the user to share their screen.
const stream =
    await navigator.mediaDevices.getDisplayMedia({ controller });

您可以在 promise 解析之前任意多次调用 setFocusBehavior()，也可以在 promise 解析后立即调用一次。最后一次调用会替换之前的所有调用。

更准确地说：

  • getDisplayMedia() 返回的 promise 在微任务中解析。在该微任务完成后调用 setFocusBehavior() 会抛出错误。
  • 在捕获开始后超过一秒钟调用 setFocusBehavior() 是无操作。

也就是说，以下两个代码段都会失败：

// Prompt the user to share their screen.
const stream =
    await navigator.mediaDevices.getDisplayMedia({ controller });

// Too late, because it follows the completion of the task
// on which the getDisplayMedia() promise resolved.
// This will throw.
setTimeout(() => {
  controller.setFocusBehavior("focus-captured-surface");
});

// Prompt the user to share their screen.
const stream =
    await navigator.mediaDevices.getDisplayMedia({ controller });

const start = new Date();
while (new Date() - start <= 1000) {
  // Idle for ≈1s.
}

// Because too much time has elapsed, the browser will have
// already decided whether to focus.
// This fails silently.
controller.setFocusBehavior("focus-captured-surface");

在以下情况下调用 setFocusBehavior() 也会抛出错误：

  • getDisplayMedia() 返回的流的视频轨道不是 "实时" 的。
  • 在 getDisplayMedia() 返回的 promise 解析后，如果用户共享的是屏幕（而不是标签页或窗口）。

示例

您可以运行演示来体验条件焦点。

功能检测

如需检查是否支持 CaptureController.setFocusBehavior()，请使用：

if (
  "CaptureController" in window &&
  "setFocusBehavior" in CaptureController.prototype
) {
  // CaptureController.setFocusBehavior() is supported.
}

反馈

Chrome 团队和 Web 标准社区希望了解您使用条件焦点的体验。

请向我们介绍设计

条件焦点是否未按预期运行？或者，您是否需要实现自己的想法，但缺少方法或属性？您对安全模型有疑问或意见吗？

  • 在 GitHub 代码库 中提交规范问题，或将您的想法添加到现有问题中。

实现有问题？

您是否发现 Chrome 的实现存在 bug？或者，实现是否与规范不同？

  • 请访问 https://new.crbug.com 提交 bug。请务必尽可能详细地说明问题，并提供重现说明。

表达支持

您是否计划使用条件焦点？您的公开支持有助于 Chrome 团队确定功能的优先级，并向其他浏览器供应商展示支持这些功能的重要性。

向 @ChromiumDev 发送一条推文，告诉我们您在何处以及如何使用它。

致谢

感谢 Rachel Andrew 审核本文档。