Code aktualisieren

Aktualisierungen, die nicht mit anderen Problemen zusammenhängen

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

tabs.executeScript() durch scripting.executeScript() ersetzen

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

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

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

Die scripting.executeScript()-Methode funktioniert ähnlich wie tabs.executeScript(). Es gibt jedoch einige Unterschiede.

• Während bei der alten Methode nur eine einzelne Datei verwendet werden konnte, kann bei der neuen Methode ein Array von Dateien verwendet werden.
• Außerdem übergeben Sie ein ScriptInjection-Objekt anstelle von InjectDetails. Es gibt mehrere Unterschiede zwischen den beiden. Beispiel: tabId wird jetzt als Mitglied von ScriptInjection.target anstelle als Methodenargument übergeben.

Das Beispiel zeigt, wie das geht.

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

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

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

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

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 den Funktionen von tabs. Es gibt jedoch einige Unterschiede.

• Wenn Sie diese Methoden aufrufen, übergeben Sie ein CSSInjection-Objekt anstelle von InjectDetails.
• tabId wird jetzt als Mitglied von CSSInjection.target anstelle eines Methodenarguments übergeben.

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

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

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

Browseraktionen und Seitenaktionen durch Aktionen ersetzen

Browser- 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 Ihrem manifest.json und Erweiterungscode erforderlich, die sich von dem unterscheiden, was Sie in Ihr Manifest V2-Hintergrundskript eingefügt 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 deklarativem Inhalt emulieren oder enable() oder disable() mit einer Tab-ID aufrufen.

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

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

{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}

{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

browserAction- und pageAction-APIs durch die action-API ersetzen

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

browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });

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, finden Sie hier weitere Informationen. Auf dieser Seite erfahren Sie, 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 von Promises hinzugefügt wurde. Beachten Sie, dass Sie beide nicht 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, z. B. Event-Listener, sind weiterhin Callbacks erforderlich. Ob eine Methode Promises unterstützt, können Sie in der API-Referenz anhand des Labels „Promise“ erkennen.

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. Hinweis: Die Promise-Version könnte mit „async“ und „await“ neu geschrieben werden.

browser.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});

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 Nachrichtenübermittlung mit Service Workern von Erweiterungen interagieren. Daher müssen Sie Aufrufe ersetzen, die einen Hintergrundkontext erwarten, insbesondere:

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

In den Skripts Ihrer Erweiterung sollte die Nachrichtenübergabe 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.