background

Typ Object
Pflichtangabe 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 ein Service Worker in Ihre Erweiterung einzuschließen.

Hintergrundskripte sind der Ort, an dem Code platziert wird, der einen langfristigen Zustand beibehalten 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 jede WebExtension-API in dem Skript verwenden, wenn Sie die erforderlichen Berechtigungen angefordert haben.

Weitere Details finden Sie unter Hintergrundskripte.

Der background-Schlüssel ist ein Objekt, das eine dieser Eigenschaften haben muss (für weitere Informationen darüber, wie diese Eigenschaften unterstützt werden, siehe Browser-Kompatibilität):

page

Wenn Sie spezifische Inhalte in der Hintergrundseite benötigen, können Sie eine Seite mit der Eigenschaft page definieren. Dies ist ein String, der einen relativ zur manifest.json-Datei liegenden Pfad zu einem in Ihrem Erweiterungspaket 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 einbinden, 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 window-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 manifest.json-Datei Ihrer Erweiterung ändern.
service_worker

Geben Sie eine JavaScript-Datei als Erweiterungs-Service Worker 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 weggelassen, ist diese Eigenschaft standardmäßig true in Manifest V2 und false in Manifest V3. Eine Einstellung auf true in Manifest V3 führt zu einem Fehler.

  • true bedeutet, dass die Hintergrundseite im Speicher gehalten wird, vom Laden der Erweiterung oder dem Starten des Browsers, bis die Erweiterung entladen oder deaktiviert wird, oder der Browser geschlossen wird (das heißt, die Hintergrundseite ist persistent).
  • false bedeutet, dass die Hintergrundseite vom Speicher entladen werden kann, wenn sie nicht benötigt wird, und bei Bedarf neu erzeugt wird. Solche Hintergrundseiten werden oft Ereignisseiten genannt, da sie in den Speicher geladen werden, um der Hintergrundseite zu erlauben, die Ereignisse zu verarbeiten, für die sie Listener hinzugefügt hat. Die Registrierung von Listenern bleibt erhalten, wenn die Seite aus dem Speicher entladen wird, aber andere Werte sind nicht persistent. Wenn Sie Daten in einer Ereignisseite persistent speichern möchten, sollten Sie die Storage-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-Modul eingebunden sind.
  • module bedeutet, dass die Hintergrundskripte oder Service Worker als ES-Modul eingebunden sind. Dadurch kann die Hintergrundseite oder der Service Worker Code import.

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

Browser-Kompatibilität

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

  • Chrome:
    • unterstützt background.service_worker.
    • unterstützt background.scripts (und background.page) nur in Manifest V2-Erweiterungen.
    • Vor Chrome 121 lädt Chrome keine Manifest V3-Erweiterung, bei der 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-Bug 1573659).
    • unterstützt background.scripts (oder background.page), wenn service_worker nicht angegeben ist oder die Service Worker-Funktion 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 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.

Um dies zu veranschaulichen, ist hier ein einfaches Beispiel für eine plattformübergreifende Erweiterung, die sowohl scripts als auch service_worker unterstützt. Das Beispiel hat 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, da 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, da 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, da Safari es bevorzugt, Service Worker für Hintergrundskripte zu verwenden.

Beispiele

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

Zwei Hintergrundskripte laden.

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

Eine benutzerdefinierte Hintergrundseite laden.

Browser-Kompatibilität

BCD tables only load in the browser