background

类型 对象
必填
清单文件版本 2 或更高
示例
json
"background": {
  "scripts": ["background.js"]
}

使用background键在扩展中包含一个或多个后台脚本、一个后台页面或一个服务工作线程。

后台脚本是放置需要维护长期状态或执行独立于任何特定网页或浏览器窗口生命周期的长期操作的代码的地方。

后台脚本在扩展加载后立即加载,并一直保持加载状态,直到扩展被禁用或卸载,除非将persistent指定为false。如果你已请求必要的权限,则可以在脚本中使用任何 WebExtension API。

请参阅后台脚本以获取更多详细信息。

background键是一个对象,必须具有以下属性之一(有关如何支持这些属性的更多信息,请参阅浏览器支持

page

如果后台页面需要特定内容,可以使用page属性定义一个页面。这是一个String,表示扩展包中包含的 HTML 文档相对于 manifest.json 文件的路径。

如果使用此属性,则不能使用scripts指定后台脚本,但可以像普通网页一样从页面中包含脚本。

scripts

一个StringsArray,每个字符串都是一个 JavaScript 源文件的路径。该路径相对于 manifest.json 文件本身。这些是在扩展的后台页面中执行的脚本。

这些脚本共享相同的window全局上下文。

脚本按照它们在数组中出现的顺序加载。

如果指定scripts,则会创建一个空页面,脚本在其中运行。

注意:如果要使用<script>标签从远程位置获取脚本(例如,<script src = "https://code.jquery.com/jquery-3.6.0.min.js">),则必须更改扩展的 manifest.json 文件中的content_security_policy键。

service_worker

指定一个 JavaScript 文件作为扩展服务工作线程。服务工作线程是一个后台脚本,充当扩展的主要事件处理程序。

background键还可以包含此可选属性

persistent

一个Boolean值。

如果省略,此属性在清单文件 V2 中默认为true,在清单文件 V3 中默认为false。在清单文件 V3 中设置为true会导致错误。

  • true表示后台页面在扩展加载或浏览器启动时一直保留在内存中,直到扩展卸载或禁用,或浏览器关闭(即,后台页面是持久性的)。
  • false表示当后台页面空闲时,它可能会从内存中卸载,并在需要时重新创建。此类后台页面通常称为事件页面,因为它们加载到内存中以允许后台页面处理它已添加侦听器的事件。当页面从内存中卸载时,侦听器的注册是持久的,但其他值不是持久的。如果要在事件页面中持久存储数据,则应使用存储 API
type

一个String值。

确定在"scripts"中指定的脚本是否作为 ES 模块加载。

  • classic表示后台脚本或服务工作线程不包含为 ES 模块。
  • module表示后台脚本或服务工作线程包含为 ES 模块。这使后台页面或服务工作线程能够import代码。

如果省略,此属性默认为classic

浏览器支持

scriptspageservice_worker属性的支持在浏览器之间有所不同,如下所示

  • Chrome
    • 支持background.service_worker
    • 仅在清单文件 V2 扩展中支持background.scripts(和background.page)。
    • 在 Chrome 121 之前,Chrome 拒绝加载带有background.scriptsbackground.page的清单文件 V3 扩展。从 Chrome 121 开始,它们在清单文件 V3 扩展中的存在将被忽略。
  • Firefox
    • 不支持background.service_worker(请参阅Firefox 错误 1573659)。
    • 如果未指定service_worker或服务工作线程功能被禁用,则支持background.scripts(或background.page)。在 Firefox 120 之前,如果存在service_worker,Firefox 不会启动后台页面(请参阅Firefox 错误 1860304)。从 Firefox 121 开始,无论是否存在service_worker,后台页面都会按预期启动。
  • Safari
    • 支持background.service_worker
    • 如果未指定service_worker,则支持background.scripts(或background.page)。

为了说明,这是一个支持scriptsservice_worker的简单跨浏览器扩展示例。该示例具有此 manifest.json 文件

json
{
  "name": "Demo of service worker + event page",
  "version": "1",
  "manifest_version": 3,
  "background": {
    "scripts": ["background.js"],
    "service_worker": "background.js"
  }
}

并且,background.js 包含

javascript
if (typeof browser == "undefined") {
  // Chrome does not support the browser namespace yet.
  globalThis.browser = chrome;
}
browser.runtime.onInstalled.addListener(() => {
  browser.tabs.create({ url: "http://example.com/firstrun.html" });
});

执行扩展时,会发生以下情况

  • 在 Chrome 中,使用service_worker属性,并启动一个服务工作线程以打开标签页,因为在清单文件 V3 扩展中,Chrome 仅支持服务工作线程作为后台脚本。
  • 在 Firefox 中,使用scripts属性,并启动一个脚本以打开标签页,因为 Firefox 仅支持脚本作为后台脚本。
  • 在 Safari 中,使用service_worker属性,并启动一个服务工作线程以打开标签页,因为 Safari 优先使用服务工作线程作为后台脚本。

示例

json
  "background": {
    "scripts": ["jquery.js", "my-background.js"]
  }

加载两个后台脚本。

json
  "background": {
    "page": "my-background.html"
  }

加载自定义后台页面。

浏览器兼容性

BCD 表格仅在浏览器中加载