Manifest V3 中的屏幕外文档

Ian Stanion
Ian Stanion

如需在从后台页面转换为扩展程序服务工作器的过程中替换功能,从 Chrome 109 开始,开发者可以使用 chrome.offscreen API 和清单权限。请求此权限后,您可以创建屏幕外文档以使用 DOM API,而无需打开会干扰用户体验的新窗口或标签页。chrome.offscreen API 现已在 Chrome 扩展程序中推出。

在 Chromium 中,Manifest V3 扩展程序基于服务工作线程,但服务工作线程不支持基于完整文档的页面(包括后台页面和事件页面)支持的 API 和机制。此外,使用内容脚本访问网页上的 DOM API 会导致扩展程序受网页之间不同的内容安全政策的约束。为帮助解决此问题,我们引入了屏幕外文档,以允许清单 V3 扩展程序通过专用 API 在运行时打开最小、受限且相对无权限的屏幕外文档,从而支持与 DOM 相关的功能和 API。

地图项信息

由于屏幕外文档专门用于处理服务工作器不支持的用例(例如音频播放),因此此页面的生命周期及其将被授予的权限与扩展程序服务工作器的生命周期和权限是分开的。该页面的生命周期机制与清单 V2 中的事件页面类似,即当该页面停止执行操作时,系统会将其拆解。此外,用户代理可能会针对指定用途对生命周期施加进一步限制。 屏幕外文档旨在填补仅可供 DOM API 访问的 API 的空白;因此,扩展程序 API 无需在此上下文中直接公开。为了降低扩展程序将这些 API 用作“后台页面替换项”的可能性,系统仅向屏幕外文档公开 chrome.runtime Messaging API。(开发者还可以通过其 Service Worker 将屏幕外文档声明为客户端,以使用 Web 消息传递。) 由于某些用例(尤其是网站抓取)需要访问跨源框架,因此我们允许这些文档按照与扩展程序页面相同的规则嵌入跨源框架。在屏幕外文档中,扩展程序指定的内容脚本能够在这些帧中运行,以抓取任何必要的内容,就像在任何普通网页中一样。

原因,以及要求提供用途

创建非屏幕文档需要说明原因并提供进一步的理由。这些原因列在 API 参考文档中,并以不同的方式处理文档的生命周期。例如,与用于管理剪贴板的文档相比,用于音频播放的文档目前对其生命周期应用的规则不同。您还可以在正当理由中详细说明离屏文档的用途。正当理由是开发者编写的字符串,而不是对文档有影响的参数。 随着开发者分享反馈和用例,API 中可能会逐渐添加更多原因。

展望未来

为了简化实现,此 API 的第一个版本一次只能支持每个扩展程序、每个配置文件一个页面。在未来的版本中,我们可能会放宽此限制,以支持多个页面。目前,如果扩展程序在分屏模式下运行且处于有效的无痕模式个人资料,则常规个人资料和无痕模式个人资料各可以有一个屏幕外文档。我们还计划稍后为扩展程序 worker 提供 DOM 功能。您可以将使用屏幕外 API 的函数与服务工件中的等效注释函数配对,以便日后进行切换,从而为扩展程序“做好未来规划”。

// Solution 1 - Service workers cannot directly interact with
// the system clipboard. To work around this, we'll create an offscreen
// document and pass the data we want to write to the clipboard.
async function addToClipboard(value) {
    await chrome.offscreen.createDocument({
      url: 'offscreen.html',
      reasons: [chrome.offscreen.Reason.CLIPBOARD],
      justification: 'Write text to the clipboard.',
    });
  }


// Solution 2 – Once extension service workers can use the Clipboard API,
// replace the offscreen document based implementation with something like this
async function addToClipboardV2(value) {
  navigator.clipboard.writeText(value);
}

此外,随着 DOM 功能和 API 添加到服务工件中,创建文档的原因列表也会相应增加或减少,具体取决于服务工件的当前状态以及使用屏幕外文档的原因。

总结

借助屏幕外文档,需要 DOM 或窗口互动访问权限(目前无法在服务工件中实现)的扩展程序可以正常运行。它还提供了一种灵活的方法,可以添加新的用例,并移除未来已解决的用例。 扩展程序应针对特定用例采用建议的屏幕外文档 API,并且扩展程序的主要后台上下文应保持为清单中指定的服务工件。不应将离屏文档用作存储主要扩展程序逻辑的位置,因为它具有有限的 API 访问权限。屏幕外文档的生命周期与创建它的 Service Worker 无关。我们将在单独的博文中介绍扩展程序中与服务工件生命周期相关的服务工件生命周期注意事项和使用场景。 随着服务工件本身添加功能和 API,使用屏幕外文档的原因会随时间推移而波动。我们非常期待在这一过程中听到开发者的反馈。

照片由 Unsplash 用户 Kari Shea 拍摄