Je code updaten

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 van InjectDetails. Er zijn meerdere verschillen tussen de 2. De tabId wordt nu bijvoorbeeld doorgegeven als lid van ScriptInjection.target in plaats van als een methode-argument.

In het voorbeeld zie je hoe je dit doet.

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

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

In een achtergrondscriptbestand.

Manifest V3
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 van InjectDetails.
  • De tabId wordt nu doorgegeven als lid van CSSInjection.target in plaats van als een methodeargument.

In het voorbeeld zie je hoe je dit doet voor insertCSS(). De procedure voor removeCSS() is hetzelfde.

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

In een achtergrondscriptbestand.

Manifest V3
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".

Manifest V2
{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}
Manifest V3
{
  ...
  "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.

Manifest V2
browser.browserAction.onClicked.addListener(tab => { ... });
browser.pageAction.onClicked.addListener(tab => { ... });
Manifest V3
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.

Terugbellen
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');
  }
});

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