background

Typ Object
Verpflichtend Nein
Manifest-Version 2 oder höher
Beispiel
json

"background": {
  "scripts": ["background.js"]
}

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

Hintergrundskripte sind der richtige Ort, um Code zu hinterlegen, der langfristigen Zustand pflegen oder langfristige Operationen unabhängig von der Lebensdauer bestimmter Webseiten oder Browserfenster 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 als false angegeben. Sie können in dem Skript beliebige WebExtension-APIs verwenden, wenn Sie die notwendigen Berechtigungen angefordert haben.

Siehe Hintergrundskripte für weitere Details.

Der background-Schlüssel ist ein Objekt, das eine der folgenden Eigenschaften haben muss (für weitere Informationen darüber, wie diese Eigenschaften unterstützt werden, siehe Browser-Unterstützung):

page

Wenn Sie spezifische Inhalte auf der Hintergrundseite benötigen, können Sie eine Seite mit der Eigenschaft page definieren. Dies ist ein String, der einen Pfad relativ zur manifest.json-Datei zu einem innerhalb Ihres Erweiterungspakets enthaltenen HTML-Dokument darstellt.

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

scripts

Ein Array von Strings, von denen jeder ein Pfad zu einer JavaScript-Quelle ist. Der Pfad ist relativ zur manifest.json-Datei selbst. Dies sind die Skripte, die auf der Hintergrundseite der Erweiterung ausgeführt werden.

Die Skripte teilen denselben globalen Kontext window.

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 Standort mit dem <script>-Tag (z.B., <script src = "https://code.jquery.com/jquery-3.6.0.min.js">) abrufen möchten, müssen Sie den content_security_policy-Schlüssel in der manifest.json-Datei Ihrer Erweiterung ändern.

service_worker

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

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

persistent

Ein Boolean-Wert.

Wenn weggelassen, ist diese Eigenschaft standardmäßig auf true in Manifest V2 und false in Manifest V3 gesetzt. Das Setzen auf true in Manifest V3 führt zu einem Fehler.

  • true bedeutet, dass die Hintergrundseite im Speicher gehalten werden soll, von dem Zeitpunkt an, zu dem die Erweiterung geladen oder der Browser gestartet wird, bis sie deinstalliert oder deaktiviert wird oder der Browser geschlossen wird (d.h. die Hintergrundseite ist persistent).
  • false bedeutet, dass die Hintergrundseite aus dem Speicher entladen und bei Bedarf neu erstellt werden kann, wenn sie untätig ist. Solche Hintergrundseiten werden oft als Ereignisseiten bezeichnet, weil sie in den Speicher geladen werden, um Ereignisse zu verarbeiten, zu denen sie Listener hinzugefügt haben. Die Registrierung von Listenern ist persistent, wenn die Seite aus dem Speicher entladen wird, andere Werte sind jedoch nicht persistent. Wenn Sie Daten in einer Ereignisseite persistent speichern möchten, sollten Sie die Speicher-API verwenden.
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-Module enthalten sind.
  • module bedeutet, dass die Hintergrundskripte oder Service Worker als ES-Module enthalten sind. Dies ermöglicht es der Hintergrundseite oder dem Service Worker, Code zu importieren.

Wenn weggelassen, ist diese Eigenschaft standardmäßig auf classic gesetzt.

Browser-Unterstützung

Die Unterstützung für die Eigenschaften scripts, page und service_worker variiert je nach Browser wie folgt:

  • Chrome:
    • unterstützt background.service_worker.
    • unterstützt background.scripts (und background.page) nur in Manifest V2-Erweiterungen.
    • vor Chrome 121 verweigert Chrome das Laden einer Manifest V3-Erweiterung, wenn background.scripts oder background.page vorhanden sind. Ab Chrome 121 wird ihre Anwesenheit in einer Manifest V3-Erweiterung ignoriert.
  • Firefox:
    • background.service_worker wird nicht unterstützt (siehe Firefox-Fehler 1573659).
    • unterstützt background.scripts (oder background.page), wenn service_worker nicht angegeben oder die Service Worker-Funktion deaktiviert ist. Vor Firefox 120 startete Firefox die Hintergrundseite nicht, wenn service_worker vorhanden war (siehe Firefox-Fehler 1860304). Ab Firefox 121 startet die Hintergrundseite wie erwartet, 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, dies ist ein Beispiel für eine plattformübergreifende Erweiterung, die scripts und service_worker unterstützt. Das Beispiel verfügt über diese 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:

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

Wenn die Erweiterung ausgeführt wird, passiert Folgendes:

  • in Chrome wird die service_worker-Eigenschaft verwendet, und ein Service Worker startet, der den Tab öffnet, weil in einer Manifest V3-Erweiterung Chrome nur Service Worker für Hintergrundskripte unterstützt.
  • in Firefox wird die scripts-Eigenschaft verwendet, und ein Skript startet, das den Tab öffnet, weil Firefox nur Skripte für Hintergrundskripte unterstützt.
  • in Safari wird die service_worker-Eigenschaft verwendet, und ein Service Worker startet, der den Tab öffnet, weil Safari Service Worker für Hintergrundskripte bevorzugt verwendet.

Beispiele

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

Laden von zwei Hintergrundskripten.

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

Laden einer benutzerdefinierten Hintergrundseite.

Browser-Kompatibilität

BCD tables only load in the browser