Updates die geen verband houden met andere problemen
Dit is het eerste van 3 gedeelten waarin de wijzigingen worden beschreven die nodig zijn voor code die geen deel uitmaakt van de serviceworker van de extensie. Dit gedeelte is bedoeld voor vereiste codewijzigingen die geen verband houden met andere problemen. In de volgende 2 gedeelten wordt uitgelegd hoe je blokkerende webverzoeken vervangt en de beveiliging verbetert.
Vervang tabs.executeScript() door scripting.executeScript()
In Manifest V3 wordt executeScript() verplaatst van de tabs API naar de scripting API. Hiervoor moet je de rechten in het manifestbestand wijzigen en de daadwerkelijke code wijzigen.
Voor de methode executeScript() heeft u het volgende nodig:
- Het recht
"scripting". - Hostrechten of het recht
"activeTab".
De methode scripting.executeScript() is vergelijkbaar met hoe het werkte met tabs.executeScript(). Er zijn een paar verschillen.
- De oude methode kon maar één bestand verwerken, maar de nieuwe methode kan een array van bestanden verwerken.
- U geeft ook een
ScriptInjection-object door in plaats vanInjectDetails. Er zijn meerdere verschillen tussen de 2. DetabIdwordt nu bijvoorbeeld doorgegeven als lid vanScriptInjection.targetin plaats van als een methode-argument.
In het voorbeeld zie je hoe je dit doet.
async function getCurrentTab() {/* ... */} let tab = await getCurrentTab(); browser.tabs.executeScript( tab.id, { file: 'content-script.js' } );
In een achtergrondscriptbestand.
async function getCurrentTab() let tab = await getCurrentTab(); browser.scripting.executeScript({ target: {tabId: tab.id}, files: ['content-script.js'] });
In de service worker van de extensie.
Vervang tabs.insertCSS() en tabs.removeCSS() door scripting.insertCSS() en scripting.removeCSS()
In Manifest V3 worden insertCSS() en removeCSS() verplaatst van de tabs API naar de scripting API. Hiervoor zijn wijzigingen in de rechten in het manifestbestand vereist, naast codewijzigingen:
- Het recht
"scripting". - Hostrechten of het recht
"activeTab".
De functies van de scripting API zijn vergelijkbaar met de functies van tabs. Er zijn een paar verschillen.
- Als je deze methoden aanroept, geef je een
CSSInjection-object door in plaats vanInjectDetails. - De
tabIdwordt nu doorgegeven als lid vanCSSInjection.targetin plaats van als een methodeargument.
In het voorbeeld zie je hoe je dit doet voor insertCSS(). De procedure voor removeCSS() is hetzelfde.
browser.tabs.insertCSS(tabId, injectDetails, () => { // callback code });
In een achtergrondscriptbestand.
const insertPromise = await browser.scripting.insertCSS({ files: ["style.css"], target: { tabId: tab.id } }); // Remaining code.
In de service worker van de extensie.
Browseracties en pagina-acties vervangen door acties
Browseracties en pagina-acties waren afzonderlijke concepten in Manifest V2. Hoewel ze begonnen met verschillende rollen, werden de verschillen tussen de 2 na verloop van tijd kleiner. In Manifest V3 zijn deze concepten samengevoegd in de Action API. Hiervoor moet je wijzigingen aanbrengen in je manifest.json en extensiecode die verschillen van wat je in je Manifest V2-achtergrondscript zou hebben gezet.
Acties in Manifest V3 lijken het meest op browseracties, maar de action-API biedt geen hide() en show() zoals pageAction dat deed. Als je nog steeds pagina-acties nodig hebt, kun je ze emuleren met declaratieve content of enable() of disable() aanroepen met een tabblad-ID.
Vervang browser_action en page_action door action
Vervang in de manifest.json de velden "browser_action" en "page_action" door het veld "action". Ga naar de referentie voor informatie over het veld "action".
{ ... "page_action": { ... }, "browser_action": { "default_popup": "popup.html" } ... }
{ ... "action": { "default_popup": "popup.html" } ... }
De API's browserAction en pageAction vervangen door de API action
Waar je Manifest V2 de API's browserAction en pageAction gebruikte, moet je nu de API action gebruiken.
browser.browserAction.onClicked.addListener(tab => { ... }); browser.pageAction.onClicked.addListener(tab => { ... });
browser.action.onClicked.addListener(tab => { ... });
Callbacks vervangen door promises
In Manifest V3 retourneren veel API-methoden voor extensies promises. Een Promise is een proxy of tijdelijke aanduiding voor een waarde die wordt geretourneerd door een asynchrone methode. Als je nog nooit Promises hebt gebruikt, kun je erover lezen op MDN. Op deze pagina staat wat je moet weten om ze te gebruiken in een Chrome-extensie.
Voor compatibiliteit met eerdere versies blijven veel methoden callbacks ondersteunen nadat ondersteuning voor promises is toegevoegd. Je kunt ze niet allebei gebruiken voor dezelfde functieaanroep. Als je een callback doorgeeft, retourneert de functie geen promise. Als je een promise wilt retourneren, geef je geen callback door. Voor sommige API-functies, zoals event-listeners, zijn nog steeds callbacks vereist. Als je wilt checken of een methode promises ondersteunt, zoek je naar het label Promise in de API-referentie.
Als je een callback wilt converteren naar een promise, verwijder je de callback en verwerk je de geretourneerde promise. Het onderstaande voorbeeld is afkomstig uit het voorbeeld van optionele rechten, met name newtab.js. De callback-versie toont hoe de aanroep van het voorbeeld naar request() eruit zou zien met een callback. De promise-versie kan worden herschreven met async en await.
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'); } });
Functies vervangen die een Manifest V2-achtergrondcontext verwachten
Andere extensiecontexten kunnen alleen interactie hebben met extensie-serviceworkers via berichtdoorgifte. Daarom moet je aanroepen vervangen die een achtergrondcontext verwachten, met name:
browser.runtime.getBackgroundPage()browser.extension.getBackgroundPage()browser.extension.getExtensionTabs()
Je extensiescripts moeten berichten doorgeven om te communiceren tussen een servicemedewerker en andere delen van je extensie. Op dit moment kun je dit doen door sendMessage() te gebruiken en browser.runtime.onMessage te implementeren in je extensie-serviceworker. Op de lange termijn moet je deze aanroepen vervangen door postMessage() en de berichtgebeurtenishandler van een servicemedewerker.
Niet-ondersteunde API's vervangen
De methoden en eigenschappen hieronder moeten worden gewijzigd in Manifest V3.
| Manifest V2-methode of -property | Vervangen door |
|---|---|
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 |
Gebruik promise.catch() als methoden beloften retourneren |
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 (achtergrondscripts) |
Niet ondersteund in serviceworkers voor extensies. Gebruik in plaats daarvan de documentgebeurtenis 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 |