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. Beispiel: browser.tabs.create({}) und chrome.tabs.create({}) sind äquivalent.

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

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

Erweiterungen mit einer Entwicklertools-Seite können den Namespace browser nicht verwenden. Wenn in Ihrer Erweiterung eine devtools_page deklariert ist, wird der Namespace browser für die gesamte Erweiterung deaktiviert – nicht nur für die DevTools-Seite, sondern auch für Ihren Service Worker, Ihre Content-Scripts, Ihr Pop-up, Ihre Optionsseite und jeden anderen Kontext, in dem Erweiterungs-APIs ausgeführt werden. Verwenden Sie chrome.* weiterhin in diesen Erweiterungen. Weitere Informationen finden Sie unter Der Browser-Namespace und Entwicklertools-Erweiterungen

.

Entscheiden, ob der Browser-Namespace übernommen werden soll

Wenn Sie webextension-polyfill verwenden, überspringen Sie den Abschnitt Hinweis für Polyfill-Nutzer, bevor Sie etwas anderes ä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 bestehende Erweiterungen, die sich für die Einführung entscheiden.

Prüfen, welche Chrome-Versionen Ihre Nutzer verwenden

Wenn Sie bereits eine 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. Mit eigenen Analysedaten bestätigen Wenn Sie noch keine Analysen eingerichtet haben, finden Sie hier Informationen zum Einrichten von Google Analytics 4.

Wählen Sie dann einen der folgenden Wege aus:

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

Bedingungslos übernehmen

Legen Sie minimum_chrome_version in Ihrem Manifest fest und verwenden Sie browser bedingungslos – es ist keine Laufzeitüberprüfung erforderlich:

{
  "minimum_chrome_version": "148"
}

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

Verwenden Sie ein gestaffeltes Rollout, wenn Sie minimum_chrome_version erhöhen. Wenn etwas schiefgeht, können Sie für Ihre Erweiterung im Chrome Web Store ein Rollback durchführen.

Laufzeitschutz verwenden

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

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-polyfill verwendet, 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 einzuführen, wurde aus diesem Grund zurückgezogen: Mit der Neudefinition von browser wurde das Wrapping durch den Polyfill beendet, aber die browser.runtime.onMessage-Implementierung von Chrome unterstützte noch keine Listener, die Promises zurückgeben, was der Polyfill bereitgestellt hatte. Erweiterungen, die auf diesem Muster basieren, funktionieren nicht mehr. In Chrome 148 werden der Namespace und die nativen Promise-zurückgebenden onMessage-Listener zusammen ausgeliefert, um diese Lücke zu vermeiden.

Sie können die Polyfill-Abhängigkeit entfernen, sobald Ihre Nutzerbasis auf Chrome 148 umgestellt hat.

Weitere Funktionen

Asynchrone Antworten in runtime.sendMessage

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

Bisher war die einzige Möglichkeit, asynchron zu antworten, die Rückgabe eines Literals 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 einen 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 return true-Muster funktioniert weiterhin, sodass vorhandener Code nicht geändert werden muss.

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