此页面由 Cloud Translation API 翻译。

利用捕获句柄改善标签页共享体验

François Beaufort

GitHub

Elad Alon

GitHub

浏览器支持

Web 平台现在附带捕获句柄，该机制可帮助捕获和捕获 Web 应用之间的协作。借助拍摄手柄，捕获的 Web 应用能够符合人体工程学、自信地识别捕获的 Web 应用。（如果捕获的 Web 应用已选择启用捕获功能。）

我们通过几个示例说明了具体好处。

示例 1：如果视频会议 Web 应用要截取演示文稿的 Web 应用，那么视频会议 Web 应用可以向用户提供用于在幻灯片之间导航的控件。由于这些控件直接嵌入到视频会议 Web 应用中，因此用户无需在视频会议标签页和当前展示的标签页之间反复切换。减轻这种负担后，用户现在可以更专注地进行演示。

示例 2：当拍摄的表面被渲染回拍摄地点时，就会出现“镜面厅”效果。值得注意的是，如果用户选择捕获进行视频会议通话的标签页，而视频会议 Web 应用呈现本地预览，就会观察到这种可怕的效果。使用拍摄句柄可以检测和减少自拍；例如，通过抑制本地预览的 Web 应用。

镜厅效果的图示

关于拍摄手柄

拍摄手柄由两个互补部分组成：

捕获的 Web 应用可以选择通过 navigator.mediaDevices.setCaptureHandleConfig() 向某些源公开某些信息。
然后，捕获 Web 应用可以使用 getCaptureHandle() 对 MediaStreamTrack 对象读取该信息。

捕获端

Web 应用可以向可能捕获的 Web 应用提供信息。为此，它会使用包含以下成员的可选对象调用 navigator.mediaDevices.setCaptureHandleConfig()：

handle：可以是任何不超过 1024 个字符的字符串。
exposeOrigin：如果设置为 true，则捕获的 Web 应用的来源可能会向捕获的 Web 应用公开。
permittedOrigins：有效值包括 (i) 空数组，(ii) 包含单项商品 "*" 的数组，或 (iii) 出发地数组。如果 permittedOrigins 包含单项 "*"，则 CaptureHandle 可被所有捕获 Web 应用观察到。否则，只能观察到来源为 permittedOrigins 的 Web 应用。

以下示例展示了如何将随机生成的 UUID 作为句柄和来源向任何捕获 Web 应用公开。

const config = {
  handle: crypto.randomUUID(),
  exposeOrigin: true,
  permittedOrigins: ['*'],
};
navigator.mediaDevices.setCaptureHandleConfig(config);

请注意，捕获的 Web 应用不知道是否正在捕获。也就是说，捕获的 Web 应用会使用 CaptureHandle 信息与捕获的 Web 应用建立通信（例如，通过工作器或共享云基础架构进行消息传递）。

正在拍摄面

捕获 Web 应用会保存视频 MediaStreamTrack，并可以通过对该 MediaStreamTrack 调用 getCaptureHandle() 来读取捕获句柄信息。如果没有捕获句柄，或者捕获的 Web 应用无权读取句柄，则此调用会返回 null。如果捕获句柄可用，并且捕获的 Web 应用已添加到 permittedOrigins，则此调用会返回包含以下成员的对象：

handle：捕获的 Web 应用通过 navigator.mediaDevices.setCaptureHandleConfig() 设置的字符串值。
origin：所捕获的 Web 应用的来源（如果 exposeOrigin 设置为 true）。否则，未定义。

以下示例展示了如何读取视频轨道中的拍摄句柄信息。

// Prompt the user to capture their display (screen, window, tab).
const stream = await navigator.mediaDevices.getDisplayMedia();

// Check if the video track is exposing information.
const [videoTrack] = stream.getVideoTracks();
const captureHandle = videoTrack.getCaptureHandle();
if (captureHandle) {
  // Use captureHandle.origin and captureHandle.handle...
}

通过监听 MediaStreamTrack 对象上的 "capturehandlechange" 事件来监控 CaptureHandle 更改。更改会在以下情况下发生：

捕获的 Web 应用调用 navigator.mediaDevices.setCaptureHandleConfig()。
在捕获的 Web 应用中发生跨文档导航。

videoTrack.addEventListener('capturehandlechange', event => {
  captureHandle = event.target.getCaptureHandle();
  // Consume new capture handle...
});

安全和隐私设置

从理论上讲，捕获的 Web 应用与捕获的 Web 应用之间的协作是可行的，例如，通过在捕获的 Web 应用中嵌入“神奇像素”或在视频流中嵌入二维码即可。拍摄手柄提供了一种更简单、更可靠且更安全的机制。它还允许捕获的 Web 应用选择受众群体（选择源站或整个网络）。

请注意，navigator.mediaDevices.setCaptureHandleConfig() 仅适用于安全浏览上下文（仅限 HTTPS）中的顶级主框架。

示例

您可以通过在 Glitch 上运行示例来体验拍摄手柄。请务必查看源代码。

样本歌曲

您可以访问以下网址查看部分演示：

功能检测

如需检查 getCaptureHandle() 是否受支持，请使用以下命令：

if ('getCaptureHandle' in MediaStreamTrack.prototype) {
  // getCaptureHandle() is supported.
}

如需检查 navigator.mediaDevices.setCaptureHandleConfig() 是否受支持，请使用以下命令：

if ('setCaptureHandleConfig' in navigator.mediaDevices) {
  // navigator.mediaDevices.setCaptureHandleConfig() is supported.
}

后续步骤

下文抢先了解近期将如何改进网络上的屏幕共享功能：

区域捕获可允许剪裁来自当前标签页的显示捕获的视频轨道。
条件焦点将允许捕获的 Web 应用指示浏览器将焦点切换到捕获的显示表面，或避免此类焦点更改。

反馈

Chrome 团队和网络标准社区希望了解您使用拍摄手柄的体验。

请告诉我们设计情况

是否存在拍摄手柄无法正常运行的问题？或者是否缺少一些您需要的方法或属性来实现您的想法？对安全模型有疑问或意见？

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

实施时遇到了问题？

您是否发现了 Chrome 实现方面的错误？或者，实现方式是否不同于规范？

请访问 https://new.crbug.com 提交 bug。请务必提供尽可能详细的信息，和简单的重现说明。Glitch 非常适合用于快速轻松地重现问题。

显示支持

您是否打算使用拍摄手柄？您公开提供的支持可帮助 Chrome 团队确定各项功能的优先级，并向其他浏览器供应商说明支持这些功能的重要性。

请向 @ChromiumDev 发送 Twitter 微博，告诉我们您在哪里以及如何使用它。

实用链接

致谢

感谢 Joe Medley 对本文进行审核。