Umstellung auf den Browser-Namespace

Ab Chrome 148 sind alle Chrome-Erweiterungs-APIs zusätzlich zum vorhandenen chrome-Namespace auch unter dem browser-Namespace verfügbar. browser.tabs.create({}) und chrome.tabs.create({}) sind beispielsweise gleichwertig.

Der Namespace ist überall verfügbar, wo Sie Erweiterungs-APIs aufrufen können, einschließlich Inhaltsskripts, Service Workern und Offscreen-Dokumenten. Er verweist auf die selben API-Objekte wie chrome, also chrome.tabs === browser.tabs.

Der browser Namespace ist das Ergebnis der Arbeit in der WebExtensions Community Group (WECG), einer W3C-Community-Gruppe, in der Browseranbieter an gemeinsamen Erweiterungs standards zusammenarbeiten. Der chrome-Namespace wird nicht entfernt. Beide Namespaces funktionieren weiterhin.

Ab Chrome 152 können Erweiterungen mit einer Entwicklertools-Seite auch den browser-Namespace verwenden. In früheren Versionen von Chrome wurde der browser Namespace für Erweiterungen, die eine devtools_page deklarieren, für die gesamte Erweiterung deaktiviert, nicht nur für die DevTools-Seite. Weitere Informationen finden Sie unter Der Browser-Namespace und Entwicklertools-Erweiterungen.

Entscheiden, ob der Browser-Namespace übernommen werden soll

Wenn Sie webextension-polyfill verwenden, lesen Sie den Hinweis für Polyfill-Nutzer, bevor Sie etwas ändern. Die Antwort ist für Sie anders.

Wenn Sie eine neue Erweiterung erstellen, legen Sie minimum_chrome_version auf "148" fest und verwenden Sie browser bedingungslos. Sie können hier aufhören zu lesen. Der Rest dieses Abschnitts richtet sich an vorhandene Erweiterungen, bei denen entschieden werden muss, wie sie übernommen werden sollen.

Prüfen, welche Chrome-Versionen Ihre Nutzer verwenden

Wenn Sie eine vorhandene Erweiterung haben, prüfen Sie, welche Chrome-Versionen Ihre Nutzer verwenden, bevor Sie wechseln. Chrome wird automatisch aktualisiert, aber einige Nutzer deaktivieren Updates und andere verwenden ältere Geräte, auf denen die neueste Version nicht ausgeführt werden kann. Bestätigen Sie dies mit Ihren eigenen Analysedaten. Wenn Sie noch keine Analysen eingerichtet haben lesen Sie den Hilfeartikel Leistung Ihrer Erweiterung mit Google Analytics 4 im Blick behalten um zu beginnen.

Wählen Sie dann einen Pfad aus:

• Wenn Ihre Nutzer Chrome 148 oder höher verwenden, übernehmen Sie die Änderung bedingungslos.
• Wenn ein erheblicher Teil Ihrer Nutzer Chrome 147 oder früher verwendet, verwenden Sie den Laufzeitschutz.

Bedingungslos übernehmen

Legen Sie minimum_chrome_version im Manifest fest und verwenden Sie browser bedingungslos. Es ist kein Laufzeitschutz erforderlich:

{
  "minimum_chrome_version": "148"
}

Wenn Sie minimum_chrome_version festlegen, werden alle Updates für Nutzer mit älteren Chrome-Versionen beendet. Der Chrome Web Store stellt Nutzern mit einer niedrigeren Version als der von Ihnen angegebenen Version keine zukünftigen Versionen Ihrer Erweiterung zur Verfügung. Sie bleiben bei der installierten Version und erhalten keine Fehlerkorrekturen, Sicherheitspatches oder neuen Funktionen, es sei denn, sie aktualisieren Chrome. Das ist oft die richtige Entscheidung, sollte aber als bewusste Entscheidung und nicht als routinemäßige Kompatibilitätseinstellung betrachtet werden.

Verwenden Sie einen gestaffelten Roll-out, wenn Sie minimum_chrome_version erhöhen. Wenn etwas schiefgeht, können Sie Ihre Erweiterung zurücksetzen im Chrome Web Store.

Laufzeitschutz verwenden

Fügen Sie das folgende Snippet früh im Startcode Ihrer Erweiterung hinzu, bevor Sie an anderer Stelle auf browser verweisen:

if (!globalThis.browser) {
  globalThis.browser = chrome;
  // Consider firing an analytics event here to measure how often
  // your users hit this fallback path.
}

Dadurch wird browser in früheren Versionen zu einem Alias für chrome, sodass der Rest Ihres Codes browser bedingungslos verwenden kann.

Hinweis für Polyfill-Nutzer

Wenn Ihre Erweiterung webextension-polyfillverwendet, wird sie in Chrome 148 und höher zu einem No-Op. Das Polyfill hat das Wrapping übersprungen, wenn browser bereits definiert war, da davon ausgegangen wurde, dass der Hostbrowser die API bereits bereitgestellt hatte.

Ein früherer Versuch, den Namespace in Chrome 136 zu veröffentlichen, wurde aus diesem Grund zurückgesetzt: Da browser neu definiert wurde, hat das Polyfill das Wrapping beendet, aber Chrome's browser.runtime.onMessage unterstützte noch keine Listener, die Promises zurückgeben, was das Polyfill bereitgestellt hatte. Erweiterungen, die auf diesem Muster basieren, funktionierten nicht mehr. In Chrome 148 werden der Namespace und native onMessage-Listener, die Promises zurückgeben, zusammen ausgeliefert, um diese Lücke zu vermeiden.

Sie können die Polyfill-Abhängigkeit entfernen, sobald Ihre Nutzer zu Chrome 148 gewechselt sind.

Weitere Funktionen

Asynchrone Antworten in runtime.sendMessage

In Chrome 148 können runtime.onMessage-Listener direkt ein Promise zurückgeben, um eine asynchrone Antwort zu senden. Das funktioniert unabhängig davon, ob Sie es mit chrome.* oder browser.* aufrufen.

Bisher war die einzige Möglichkeit, asynchron zu antworten, die Rückgabe eines literalen true vom Listener und der spätere Aufruf von sendResponse:

// Old pattern - requires returning true to keep the channel open
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  fetch('https://example.com')
    .then(response => sendResponse({ statusCode: response.status }));

  return true; // keeps the message channel open for the async response
});

Sie können jetzt direkt ein Promise zurückgeben oder eine async-Funktion verwenden:

// New pattern - return a promise or use async/await
browser.runtime.onMessage.addListener(async (message, sender) => {
  const response = await fetch('https://example.com');
  return { statusCode: response.status };
});

Das Muster return true funktioniert weiterhin, sodass vorhandener Code nicht geändert werden muss.

Wie beim browser Namespace selbst, runtime.onMessage Promise-Antworten sind in Erweiterungen, die eine devtools_page deklarieren, nicht verfügbar.