Code aktualisieren

Updates, die nichts mit anderen Problemen zu tun haben

Dies ist der erste von drei Abschnitten, in denen die Änderungen beschrieben werden, die für Code erforderlich sind, der nicht Teil des Service Workers der Erweiterung ist. Dieser Abschnitt ist für erforderliche Codeänderungen vorgesehen, die nicht mit anderen Problemen zusammenhängen. In den nächsten beiden Abschnitten geht es um das Ersetzen blockierender Webanfragen und die Verbesserung der Sicherheit.

Ersetzen Sie „tabs.executeScript()“ durch „scripting.executeScript()“.

In Manifest V3 wird executeScript() von der tabs API zur scripting API verschoben. Dazu sind neben den eigentlichen Codeänderungen auch Änderungen an den Berechtigungen in der Manifestdatei erforderlich.

Für die Methode executeScript() benötigen Sie Folgendes:

  • Die Berechtigung "scripting".
  • Entweder Hostberechtigungen oder die Berechtigung "activeTab".

Die Methode scripting.executeScript() ähnelt der Methode, die mit tabs.executeScript() verwendet wurde. Es gibt jedoch ein paar Unterschiede.

  • Während die alte Methode nur eine einzelne Datei akzeptieren konnte, kann die neue Methode ein Array von Dateien akzeptieren.
  • Außerdem übergeben Sie ein ScriptInjection-Objekt anstelle von InjectDetails. Es gibt mehrere Unterschiede zwischen den beiden. Beispielsweise wird tabId jetzt als Mitglied von ScriptInjection.target und nicht mehr als Methodenargument übergeben.

Im Beispiel unten wird gezeigt, wie das geht.

Manifest V2
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

browser.tabs.executeScript(
  tab.id,
  {
    file: 'content-script.js'
  }
);

In einer Hintergrundskriptdatei.

Manifest V3
async function getCurrentTab()
let tab = await getCurrentTab();

browser.scripting.executeScript({
  target: {tabId: tab.id},
  files: ['content-script.js']
});

Im Erweiterungs-Service-Worker.

Ersetzen Sie „tabs.insertCSS()“ und „tabs.removeCSS()“ durch „scripting.insertCSS()“ und „scripting.removeCSS()“.

In Manifest V3 werden insertCSS() und removeCSS() von der tabs API zur scripting API verschoben. Dazu sind neben Codeänderungen auch Änderungen an den Berechtigungen in der Manifestdatei erforderlich:

  • Die Berechtigung "scripting".
  • Entweder Hostberechtigungen oder die Berechtigung "activeTab".

Die Funktionen der scripting API ähneln denen von tabs. Es gibt jedoch ein paar Unterschiede.

  • Wenn Sie diese Methoden aufrufen, übergeben Sie ein CSSInjection-Objekt anstelle von InjectDetails.
  • tabId wird jetzt als Mitglied von CSSInjection.target und nicht mehr als Methodenargument übergeben.

Im Beispiel wird gezeigt, wie das für insertCSS() funktioniert. Das Verfahren für removeCSS() ist dasselbe.

Manifest V2
browser.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

In einer Hintergrundskriptdatei.

Manifest V3
const insertPromise = await browser.scripting.insertCSS({
  files: ["style.css"],
  target: { tabId: tab.id }
});
// Remaining code.

Im Erweiterungs-Service-Worker.

Browseraktionen und Seitenaktionen durch Aktionen ersetzen

Browseraktionen und Seitenaktionen waren in Manifest V2 separate Konzepte. Obwohl sie mit unterschiedlichen Rollen begannen, nahmen die Unterschiede zwischen ihnen im Laufe der Zeit ab. In Manifest V3 werden diese Konzepte in der Action API zusammengefasst. Dazu sind Änderungen an der Datei manifest.json und am Erweiterungscode erforderlich, die sich von den Änderungen unterscheiden, die Sie im Hintergrundskript von Manifest V2 vorgenommen hätten.

Aktionen in Manifest V3 ähneln am ehesten Browseraktionen. Die action API bietet jedoch nicht hide() und show() wie pageAction. Wenn Sie weiterhin Seitenaktionen benötigen, können Sie sie entweder mit deklarativen Inhalten emulieren oder enable() oder disable() mit einer Tab-ID aufrufen.

„browser_action“ und „page_action“ durch „action“ ersetzen

Ersetzen Sie in der manifest.json die Felder "browser_action" und "page_action" durch das Feld "action". Weitere Informationen zum Feld "action" finden Sie in der Referenz.

Manifest V2
{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}
Manifest V3
{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

Ersetzen Sie die APIs „browserAction“ und „pageAction“ durch die API „action“.

Wenn in Ihrem Manifest V2 die APIs browserAction und pageAction verwendet wurden, sollten Sie jetzt die API action verwenden.

Manifest V2
browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });
Manifest V3
browser.action.onClicked.addListener(tab => { ... });

Callbacks durch Promises ersetzen

In Manifest V3 geben viele Erweiterungs-API-Methoden Promises zurück. Ein Promise ist ein Proxy oder Platzhalter für einen Wert, der von einer asynchronen Methode zurückgegeben wird. Wenn Sie noch nie Promises verwendet haben, können Sie im MDN-Artikel mehr darüber erfahren. Auf dieser Seite wird beschrieben, was Sie wissen müssen, um sie in einer Chrome-Erweiterung zu verwenden.

Aus Gründen der Abwärtskompatibilität unterstützen viele Methoden weiterhin Callbacks, nachdem die Unterstützung für Promises hinzugefügt wurde. Beachten Sie, dass Sie nicht beide im selben Funktionsaufruf verwenden können. Wenn Sie einen Callback übergeben, gibt die Funktion kein Promise zurück. Wenn Sie ein Promise zurückgeben möchten, übergeben Sie keinen Callback. Für einige API-Funktionen wie Event-Listener sind weiterhin Callbacks erforderlich. Wenn Sie prüfen möchten, ob eine Methode Promises unterstützt, suchen Sie in der API-Referenz nach dem Label „Promise“.

Wenn Sie einen Callback in ein Promise umwandeln möchten, entfernen Sie den Callback und verarbeiten Sie das zurückgegebene Promise. Das folgende Beispiel stammt aus dem Beispiel für optionale Berechtigungen, genauer gesagt aus newtab.js. Die Callback-Version zeigt, wie der Aufruf von request() im Beispiel mit einem Callback aussehen würde. Die Promise-Version könnte mit async und await umgeschrieben werden.

Rückruf
browser.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
Promise
const newPerms = { permissions: ['topSites'] };
browser.permissions.request(newPerms)
.then((granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

Funktionen ersetzen, die einen Manifest V2-Hintergrundkontext erwarten

Andere Erweiterungskontexte können nur über die Nachrichtenweitergabe mit Erweiterungs-Service-Workern interagieren. Daher müssen Sie Aufrufe ersetzen, die einen Hintergrundkontext erwarten, insbesondere:

  • browser.runtime.getBackgroundPage()
  • browser.extension.getBackgroundPage()
  • browser.extension.getExtensionTabs()

In Ihren Erweiterungsskripts sollte die Nachrichtenweitergabe verwendet werden, um zwischen einem Service Worker und anderen Teilen Ihrer Erweiterung zu kommunizieren. Derzeit ist dies möglich, indem Sie sendMessage() verwenden und browser.runtime.onMessage in Ihrem Erweiterungs-Service-Worker implementieren. Langfristig sollten Sie diese Aufrufe durch postMessage() und den Message-Event-Handler eines Service Workers ersetzen.

Nicht unterstützte APIs ersetzen

Die unten aufgeführten Methoden und Attribute müssen in Manifest V3 geändert werden.

Manifest V2-Methode oder -Attribut Ersetzen durch
browser.extension.connect() browser.runtime.connect()
browser.extension.connectNative() browser.runtime.connectNative()
browser.extension.getExtensionTabs() browser.extension.getViews()
browser.extension.getURL() browser.runtime.getURL()
browser.extension.lastError Wenn Methoden Promise-Objekte zurückgeben, verwenden Sie promise.catch().
browser.extension.onConnect browser.runtime.onConnect
browser.extension.onConnectExternal browser.runtime.onConnectExternal
browser.extension.onMessage browser.runtime.onMessage
browser.extension.onRequest browser.runtime.onMessage
browser.extension.onRequestExternal browser.runtime.onMessageExternal
browser.extension.sendMessage() browser.runtime.sendMessage()
browser.extension.sendNativeMessage() browser.runtime.sendNativeMessage()
browser.extension.sendRequest() browser.runtime.sendMessage()
browser.runtime.onSuspend (Hintergrundskripts) Wird in Erweiterungs-Service Workern nicht unterstützt. Verwenden Sie stattdessen das Dokumentereignis beforeunload.
browser.tabs.getAllInWindow() browser.tabs.query()
browser.tabs.getSelected() browser.tabs.query()
browser.tabs.onActiveChanged browser.tabs.onActivated
browser.tabs.onHighlightChanged browser.tabs.onHighlighted
browser.tabs.onSelectionChanged browser.tabs.onActivated
browser.tabs.sendRequest() browser.runtime.sendMessage()
browser.tabs.Tab.selected browser.tabs.Tab.highlighted