Code aktualisieren

Updates, die nichts mit anderen Problemen zu tun haben

Dies ist der erste von drei Abschnitten, in denen Änderungen beschrieben werden, die für Code erforderlich sind, der nicht Teil des Extension Service Workers ist. Dieser Abschnitt bezieht sich auf erforderliche Codeänderungen, die nichts mit anderen Problemen zu tun haben. In den nächsten beiden Abschnitten geht es um das Blockieren von 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 den 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 Methode scripting.executeScript() funktioniert ähnlich wie die Methode tabs.executeScript(). Es gibt einige Unterschiede.

  • Während bei der alten Methode nur eine einzelne Datei möglich ist, kann die neue Methode ein Array von Dateien annehmen.
  • Außerdem übergeben Sie anstelle von InjectDetails ein ScriptInjection-Objekt. Es gibt mehrere Unterschiede zwischen den beiden. Beispielsweise wird tabId jetzt als Element von ScriptInjection.target statt als Methodenargument übergeben.

Das Beispiel zeigt, wie das funktioniert.

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

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

In einer Hintergrundskriptdatei

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

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

Im Extension Service Worker

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

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

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

Die Funktionen in der scripting API ähneln den Funktionen in tabs. Es gibt einige Unterschiede.

  • Beim Aufrufen dieser Methoden übergeben Sie ein CSSInjection-Objekt anstelle von InjectDetails.
  • tabId wird jetzt als Element von CSSInjection.target und nicht als Methodenargument übergeben.

Das Beispiel zeigt, wie das für insertCSS() funktioniert. Die Vorgehensweise für removeCSS() ist dieselbe.

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

In einer Hintergrundskriptdatei

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

Im Extension Service Worker

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 sind diese Konzepte in der Action API zusammengefasst. Dazu sind Änderungen an manifest.json und am Erweiterungscode erforderlich, die sich von den Änderungen im Hintergrundskript von Manifest V2 unterscheiden.

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

Ersetzen Sie "browser_action" und "page_action" durch "action".

Ersetzen Sie in manifest.json die Felder "browser_action" und "page_action" durch das Feld "action". 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"
  }

  ...
}

browserAction und pageAction APIs durch die Action API ersetzen

Wenn Manifest V2 die browserAction und die pageAction API verwendet hat, solltest du jetzt die action API nutzen.

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

Callbacks durch Promise ersetzen

In Manifest V3 geben viele Methoden der Erweiterungs-API Promise zurück. Ein Promise ist ein Proxy oder Platzhalter für einen Wert, der von einer asynchronen Methode zurückgegeben wird. Wenn du Promises noch nie verwendet hast, findest du hier entsprechende Informationen auf MDN. Auf dieser Seite wird beschrieben, was Sie zur Verwendung in einer Chrome-Erweiterung wissen müssen.

Aus Gründen der Abwärtskompatibilität unterstützen viele Methoden weiterhin Callbacks, nachdem Promise-Unterstützung hinzugefügt wurde. Beachten Sie, dass Sie nicht beide für denselben Funktionsaufruf verwenden können. Wenn du einen Callback weitergibst, gibt die Funktion kein Promise zurück, und wenn du möchtest, dass ein Promise zurückgegeben wird, gibt es keinen Callback weiter. Für einige API-Funktionen wie Ereignis-Listener sind weiterhin Rückrufe erforderlich. Um zu überprüfen, ob eine Methode Promise unterstützt, suchen Sie in der API-Referenz nach dem Label „Promise“.

Wenn du einen Callback in ein Promise umwandeln möchtest, musst du den Callback entfernen und das zurückgegebene Promise verarbeiten. Das folgende Beispiel stammt aus dem Beispiel für optionale Berechtigungen, insbesondere 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
chrome.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
Versprechen
const newPerms = { permissions: ['topSites'] };
chrome.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 Nachrichtenübergabe mit Erweiterungsdienst-Workern interagieren. Daher müssen Sie Aufrufe ersetzen, die einen Hintergrundkontext erwarten, insbesondere:

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

Ihre Erweiterungsskripts sollten die Nachrichtenweitergabe verwenden, um zwischen einem Service Worker und anderen Teilen der Erweiterung zu kommunizieren. Derzeit umfasst dies die Verwendung von sendMessage() und die Implementierung von chrome.runtime.onMessage in Ihrem Erweiterungs-Service-Worker. 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 Eigenschaften müssen in Manifest V3 geändert werden.

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