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
einScriptInjection
-Objekt. Es gibt mehrere Unterschiede zwischen den beiden. Beispielsweise wirdtabId
jetzt als Element vonScriptInjection.target
statt als Methodenargument übergeben.
Das Beispiel zeigt, wie das funktioniert.
async function getCurrentTab() {/* ... */} let tab = await getCurrentTab(); chrome.tabs.executeScript( tab.id, { file: 'content-script.js' } );
async function getCurrentTab() let tab = await getCurrentTab(); chrome.scripting.executeScript({ target: {tabId: tab.id}, files: ['content-script.js'] });
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 vonInjectDetails
. tabId
wird jetzt als Element vonCSSInjection.target
und nicht als Methodenargument übergeben.
Das Beispiel zeigt, wie das für insertCSS()
funktioniert. Die Vorgehensweise für removeCSS()
ist dieselbe.
chrome.tabs.insertCSS(tabId, injectDetails, () => { // callback code });
const insertPromise = await chrome.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 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.
{ ... "page_action": { ... }, "browser_action": { "default_popup": "popup.html" } ... }
{ ... "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.
chrome.browserAction.onClicked.addListener(tab => { ... }); chrome.pageAction.onClicked.addListener(tab => { ... });
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.
chrome.permissions.request(newPerms, (granted) => { if (granted) { console.log('granted'); } else { console.log('not granted'); } });
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 |