background

Typ Object
Verpflichtend Nein
Manifest-Version 2 oder höher
Beispiel
json
"background": {
  "scripts": ["background.js"]
}

Verwenden Sie den background-Schlüssel, um ein oder mehrere Hintergrundskripte, eine Hintergrundseite oder einen Service Worker in Ihre Erweiterung einzubinden.

Hintergrundskripte sind der Ort, an dem Sie Code platzieren, der einen langfristigen Zustand aufrechterhalten oder langfristige Operationen unabhängig von der Lebensdauer einer bestimmten Webseite oder eines Browserfensters ausführen muss.

Hintergrundskripte werden geladen, sobald die Erweiterung geladen wird, und bleiben geladen, bis die Erweiterung deaktiviert oder deinstalliert wird, es sei denn, persistent ist auf false gesetzt. Sie können in dem Skript jede WebExtension-API verwenden, wenn Sie die notwendigen Berechtigungen angefordert haben.

Siehe Background scripts für weitere Details.

Der background-Schlüssel ist ein Objekt, das eines der folgenden Eigenschaften haben muss (für weitere Informationen zur Unterstützung dieser Eigenschaften siehe Browser-Kompatibilität):

page

Wenn Sie spezifische Inhalte in der Hintergrundseite benötigen, können Sie eine Seite mithilfe der page-Eigenschaft definieren. Dies ist ein string, der einen Pfad relativ zur Datei manifest.json zu einem HTML-Dokument darstellt, das in ihrem Erweiterungspaket enthalten ist.

Wenn Sie diese Eigenschaft verwenden, können Sie keine Hintergrundskripte mit scripts angeben, aber Sie können Skripte von der Seite einbinden, genau wie bei einer normalen Webseite.

scripts

Ein array von string, von denen jeder ein Pfad zu einem JavaScript-Quellcode ist. Der Pfad ist relativ zur Datei manifest.json selbst. Dies sind die Skripte, die im Hintergrundkontext der Erweiterung ausgeführt werden.

Die Skripte teilen sich denselben window globalen Kontext.

Die Skripte werden in der Reihenfolge geladen, in der sie im Array erscheinen.

Wenn Sie scripts angeben, wird eine leere Seite erstellt, auf der Ihre Skripte ausgeführt werden.

Hinweis: Wenn Sie ein Skript von einem entfernten Ort mit dem <script>-Tag abrufen möchten (z.B. <script src = "https://code.jquery.com/jquery-3.6.0.min.js">), müssen Sie den content_security_policy Schlüssel in der Datei manifest.json Ihrer Erweiterung ändern.

service_worker

Geben Sie eine JavaScript-Datei als Service Worker der Erweiterung an. Ein Service Worker ist ein Hintergrundskript, das als Hauptereignis-Handler der Erweiterung fungiert.

Der background-Schlüssel kann auch diese optionale Eigenschaft enthalten:

persistent

Ein boolean-Wert.

Wenn diese Eigenschaft weggelassen wird, ist der Standardwert true in Manifest V2 und false in Manifest V3. Das Setzen auf true in Manifest V3 führt zu einem Fehler.

  • true bedeutet, dass die Hintergrundseite im Speicher gehalten wird, sobald die Erweiterung geladen oder der Browser gestartet wird, bis die Erweiterung entladen, deaktiviert oder der Browser geschlossen wird (d.h. die Hintergrundseite ist persistent).
  • false bedeutet, dass die Hintergrundseite aus dem Speicher entladen werden kann, wenn sie inaktiv ist, und bei Bedarf neu erstellt wird. Solche Hintergrundseiten werden häufig als Ereignisseiten bezeichnet, da sie in den Speicher geladen werden, um die Ereignisse zu verarbeiten, für die sie Hörer hinzugefügt hat. Die Registrierung von Hörern ist persistent, wenn die Seite aus dem Speicher entladen wird, aber andere Werte sind nicht persistent. Wenn Sie Daten dauerhaft in einer Ereignisseite speichern möchten, sollten Sie die storage API verwenden.
preferred_environment

Ein array von string, das die bevorzugten Umgebungen in der Reihenfolge der Priorität auflistet.

Wenn background sowohl einen service_worker als auch page oder scripts angibt, ermöglicht diese Eigenschaft der Erweiterung, dem Browser mitzuteilen, welche Hintergrundkontexte verwendet werden sollen, wenn sie verfügbar sind. Siehe Browser-Kompatibilität für Details zu den in den wichtigsten Browsern unterstützten Umgebungen.

  • document fordert, dass der Browser die Hintergrundskripte der Erweiterung als Dokumente verwendet, falls unterstützt.
  • service_worker fordert, dass der Browser die Hintergrundskripte der Erweiterung als Service Worker ausführt, falls unterstützt.

Chrome unterstützt nur Service Worker und ignoriert daher diesen Schlüssel. Wenn weggelassen, führen Firefox und Safari Hintergrundskripte als Dokumente aus. Safari verwendet einen Service Worker-Kontext, wenn die Erweiterung scripts angibt und preferred_environment auf service_worker gesetzt ist.
type

Ein string-Wert.

Bestimmt, ob die in scripts angegebenen Skripte als ES-Module geladen werden.

  • classic bedeutet, dass die Hintergrundskripte oder Service Worker nicht als ES-Modul enthalten sind.
  • module bedeutet, dass die Hintergrundskripte oder Service Worker als ES-Modul enthalten sind. Dies ermöglicht es der Hintergrundseite oder dem Service Worker, Code zu import.

Wenn diese Eigenschaft weggelassen wird, ist der Standardwert classic.

Browser-Kompatibilität

Die Unterstützung für die Eigenschaften scripts, page und service_worker variiert zwischen Browsern wie folgt:

  • Chrome:
    • unterstützt background.service_worker.
    • unterstützt background.scripts (und background.page) nur in Manifest V2 Erweiterungen.
    • vor Chrome 121 weigert sich Chrome, eine Manifest V3 Erweiterung mit vorhandenen background.scripts oder background.page zu laden. Ab Chrome 121 wird deren Vorhandensein in einer Manifest V3 Erweiterung ignoriert.
  • Firefox:
    • background.service_worker wird nicht unterstützt (siehe Firefox-Bug 1573659).
    • unterstützt background.scripts (oder background.page), wenn service_worker nicht angegeben oder das Service-Worker-Feature deaktiviert ist. Vor Firefox 120 startete Firefox die Hintergrundseite nicht, wenn service_worker vorhanden war (siehe Firefox-Bug 1860304). Ab Firefox 121 startet die Hintergrundseite erwartungsgemäß, unabhängig von der Anwesenheit von service_worker.
  • Safari:
    • unterstützt background.service_worker.
    • unterstützt background.scripts (oder background.page), wenn service_worker nicht angegeben ist.

Zur Veranschaulichung ist hier ein Beispiel einer plattformübergreifenden Erweiterung, die scripts und service_worker unterstützt. Beispielhaft hat diese eine manifest.json Datei:

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

Und, background.js enthält:

js
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/first-run.html" });
});

Wenn die Erweiterung ausgeführt wird, geschieht Folgendes:

  • In Chrome wird die service_worker-Eigenschaft verwendet, und ein Service Worker wird gestartet, der den Tab öffnet, da Chrome in einer Manifest V3 Erweiterung nur Service Worker für Hintergrundskripte unterstützt.
  • In Firefox wird die scripts-Eigenschaft verwendet, und ein Skript wird gestartet, das den Tab öffnet, da Firefox nur Skripte für Hintergrundskripte unterstützt.
  • In Safari wird die service_worker-Eigenschaft verwendet, und ein Service Worker wird gestartet, der den Tab öffnet, da Safari Service Workern für Hintergrundskripte Priorität einräumt.

Beispiele

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

Laden Sie zwei Hintergrundskripte.

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

Laden Sie eine benutzerdefinierte Hintergrundseite.

Browser-Kompatibilität