Update uw code

Updates die geen verband houden met andere kwesties

Dit is het eerste van drie delen waarin de wijzigingen worden beschreven die nodig zijn voor code die geen deel uitmaakt van de serviceworker van de extensie. Dit deel behandelt de vereiste codewijzigingen die geen verband houden met andere problemen. De volgende twee delen gaan over het vervangen van blokkerende webverzoeken en het verbeteren van de beveiliging .

Vervang tabs.executeScript() door scripting.executeScript().

In Manifest V3 is executeScript() verplaatst van de tabs API naar de scripting API. Dit vereist, naast daadwerkelijke codeaanpassingen, ook wijzigingen in de machtigingen in het manifestbestand.

Voor de executeScript() methode heb je het volgende nodig:

• De "scripting" -toestemming.
• Ofwel de hostrechten, ofwel de "activeTab" -rechten.

De methode scripting.executeScript() werkt op een vergelijkbare manier als tabs.executeScript() . Er zijn echter een paar verschillen.

• Waar de oude methode slechts één bestand kon verwerken, kan de nieuwe methode een reeks bestanden verwerken.
• Je geeft nu ook een ScriptInjection object door in plaats van InjectDetails . Er zijn meerdere verschillen tussen de twee. Zo wordt de tabId nu bijvoorbeeld doorgegeven als een lid van ScriptInjection.target in plaats van als een argument van de methode.

Het voorbeeld laat zien hoe dit te doen.

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

Vervang tabs.insertCSS() en tabs.removeCSS() door scripting.insertCSS() en scripting.removeCSS().

In Manifest V3 insertCSS() en removeCSS() verplaatst van de tabs -API naar de scripting API . Dit vereist naast codeaanpassingen ook wijzigingen in de machtigingen in het manifestbestand.

• De "scripting" -toestemming.
• Ofwel de hostrechten, ofwel de "activeTab" -rechten.

De functies van de scripting API zijn vergelijkbaar met de functies van tabs . Er zijn echter een paar verschillen.

• Bij het aanroepen van deze methoden geeft u een CSSInjection object door in plaats van InjectDetails .
• De tabId wordt nu doorgegeven als lid van CSSInjection.target in plaats van als argument van de methode.

Het voorbeeld laat zien hoe dit werkt voor insertCSS() . De procedure voor removeCSS() is hetzelfde.

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

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

Vervang Browseracties en Pagina-acties door Acties

Browseracties en pagina-acties waren aparte concepten in Manifest V2. Hoewel ze aanvankelijk verschillende rollen hadden, namen de verschillen ertussen in de loop der tijd af. In Manifest V3 zijn deze concepten samengevoegd in de Action API. Dit vereist wijzigingen in uw manifest.json en extensiecode die afwijken van wat u in uw achtergrondscript van Manifest V2 zou hebben gebruikt.

Acties in Manifest V3 lijken het meest op browseracties; de action API biedt echter niet hide() en show() zoals pageAction dat wel deed. Als je toch pagina-acties nodig hebt, kun je deze emuleren met behulp van declaratieve content of enable() of disable() aanroepen met een tab-ID.

Vervang "browser_action" en "page_action" door "action".

Vervang in het manifest.json bestand de velden "browser_action" en "page_action" door het veld "action" . Raadpleeg de referentie voor meer informatie over het veld "action" .

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

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

  ...
}

Vervang de browserAction- en pageAction-API's door de actie-API.

Waar uw Manifest V2 de browserAction en pageAction API's gebruikte, dient u nu de action API te gebruiken.

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

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

Vervang callbacks door promises.

In Manifest V3 retourneren veel API-methoden voor extensies promises. Een Promise is een proxy of placeholder voor een waarde die wordt geretourneerd door een asynchrone methode. Als je nog nooit met Promises hebt gewerkt, kun je er meer over lezen op MDN . Deze pagina beschrijft wat je moet weten om ze in een Chrome-extensie te gebruiken.

Voor compatibiliteit met oudere versies blijven veel methoden callbacks ondersteunen, ook nadat ondersteuning voor promises is toegevoegd. Houd er rekening mee dat u ze niet allebei in dezelfde functieaanroep kunt gebruiken. Als u een callback doorgeeft, retourneert de functie geen promise. Als u een promise wilt retourneren, geef dan geen callback door. Sommige API-functies, zoals eventlisteners, blijven callbacks vereisen. Om te controleren of een methode promises ondersteunt, zoekt u naar het label "Promise" in de API-referentie.

Om een ​​callback om te zetten naar een promise, verwijder je de callback en verwerk je de geretourneerde promise. Het onderstaande voorbeeld is afkomstig uit het voorbeeld met optionele machtigingen , specifiek uit newtab.js . De callback-versie laat zien hoe de aanroep van request() in het voorbeeld eruit zou zien met een callback. Merk op dat de promise-versie herschreven zou kunnen worden 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');
  }
});

Vervang functies die een Manifest V2-achtergrondcontext verwachten.

Andere extensiecontexten kunnen alleen via berichtoverdracht communiceren met extensieserviceworkers. Daarom moet u aanroepen die een achtergrondcontext verwachten, vervangen, met name:

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

Uw extensiescripts moeten gebruikmaken van berichtuitwisseling om te communiceren tussen een service worker en andere onderdelen van uw extensie. Momenteel kan dit worden bereikt door sendMessage() te gebruiken en browser.runtime.onMessage te implementeren in uw extensieservice worker. Op de lange termijn is het raadzaam om deze aanroepen te vervangen door postMessage() en een eventhandler voor berichten in uw service worker.

Vervang niet-ondersteunde API's

De onderstaande methoden en eigenschappen moeten in Manifest V3 worden aangepast.

Updates die geen verband houden met andere kwesties

Dit is het eerste van drie delen waarin de wijzigingen worden beschreven die nodig zijn voor code die geen deel uitmaakt van de serviceworker van de extensie. Dit deel behandelt de vereiste codewijzigingen die geen verband houden met andere problemen. De volgende twee delen gaan over het vervangen van blokkerende webverzoeken en het verbeteren van de beveiliging .

Vervang tabs.executeScript() door scripting.executeScript().

In Manifest V3 is executeScript() verplaatst van de tabs API naar de scripting API. Dit vereist, naast daadwerkelijke codeaanpassingen, ook wijzigingen in de machtigingen in het manifestbestand.

Voor de executeScript() methode heb je het volgende nodig:

• De "scripting" -toestemming.
• Ofwel de hostrechten, ofwel de "activeTab" -rechten.

De methode scripting.executeScript() werkt op een vergelijkbare manier als tabs.executeScript() . Er zijn echter een paar verschillen.

• Waar de oude methode slechts één bestand kon verwerken, kan de nieuwe methode een reeks bestanden verwerken.
• Je geeft nu ook een ScriptInjection object door in plaats van InjectDetails . Er zijn meerdere verschillen tussen de twee. Zo wordt de tabId nu bijvoorbeeld doorgegeven als een lid van ScriptInjection.target in plaats van als een argument van de methode.

Het voorbeeld laat zien hoe dit te doen.

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

Vervang tabs.insertCSS() en tabs.removeCSS() door scripting.insertCSS() en scripting.removeCSS().

In Manifest V3 insertCSS() en removeCSS() verplaatst van de tabs -API naar de scripting API . Dit vereist naast codeaanpassingen ook wijzigingen in de machtigingen in het manifestbestand.

• De "scripting" -toestemming.
• Ofwel de hostrechten, ofwel de "activeTab" -rechten.

De functies van de scripting API zijn vergelijkbaar met de functies van tabs . Er zijn echter een paar verschillen.

• Bij het aanroepen van deze methoden geeft u een CSSInjection object door in plaats van InjectDetails .
• De tabId wordt nu doorgegeven als lid van CSSInjection.target in plaats van als argument van de methode.

Het voorbeeld laat zien hoe dit werkt voor insertCSS() . De procedure voor removeCSS() is hetzelfde.

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

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

Vervang Browseracties en Pagina-acties door Acties

Browseracties en pagina-acties waren aparte concepten in Manifest V2. Hoewel ze aanvankelijk verschillende rollen hadden, namen de verschillen ertussen in de loop der tijd af. In Manifest V3 zijn deze concepten samengevoegd in de Action API. Dit vereist wijzigingen in uw manifest.json en extensiecode die afwijken van wat u in uw achtergrondscript van Manifest V2 zou hebben gebruikt.

Acties in Manifest V3 lijken het meest op browseracties; de action API biedt echter niet hide() en show() zoals pageAction dat wel deed. Als je toch pagina-acties nodig hebt, kun je deze emuleren met behulp van declaratieve content of enable() of disable() aanroepen met een tab-ID.

Vervang "browser_action" en "page_action" door "action".

Vervang in het manifest.json bestand de velden "browser_action" en "page_action" door het veld "action" . Raadpleeg de referentie voor meer informatie over het veld "action" .

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

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

  ...
}

Vervang de browserAction- en pageAction-API's door de actie-API.

Waar uw Manifest V2 de browserAction en pageAction API's gebruikte, dient u nu de action API te gebruiken.

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

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

Vervang callbacks door promises.

In Manifest V3 retourneren veel API-methoden voor extensies promises. Een Promise is een proxy of placeholder voor een waarde die wordt geretourneerd door een asynchrone methode. Als je nog nooit met Promises hebt gewerkt, kun je er meer over lezen op MDN . Deze pagina beschrijft wat je moet weten om ze in een Chrome-extensie te gebruiken.

Voor compatibiliteit met oudere versies blijven veel methoden callbacks ondersteunen, ook nadat ondersteuning voor promises is toegevoegd. Houd er rekening mee dat u ze niet allebei in dezelfde functieaanroep kunt gebruiken. Als u een callback doorgeeft, retourneert de functie geen promise. Als u een promise wilt retourneren, geef dan geen callback door. Sommige API-functies, zoals eventlisteners, blijven callbacks vereisen. Om te controleren of een methode promises ondersteunt, zoekt u naar het label "Promise" in de API-referentie.

Om een ​​callback om te zetten naar een promise, verwijder je de callback en verwerk je de geretourneerde promise. Het onderstaande voorbeeld is afkomstig uit het voorbeeld met optionele machtigingen , specifiek uit newtab.js . De callback-versie laat zien hoe de aanroep van request() in het voorbeeld eruit zou zien met een callback. Merk op dat de promise-versie herschreven zou kunnen worden 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');
  }
});

Vervang functies die een Manifest V2-achtergrondcontext verwachten.

Andere extensiecontexten kunnen alleen via berichtoverdracht communiceren met extensieserviceworkers. Daarom moet u aanroepen die een achtergrondcontext verwachten, vervangen, met name:

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

Uw extensiescripts moeten gebruikmaken van berichtuitwisseling om te communiceren tussen een service worker en andere onderdelen van uw extensie. Momenteel kan dit worden bereikt door sendMessage() te gebruiken en browser.runtime.onMessage te implementeren in uw extensieservice worker. Op de lange termijn is het raadzaam om deze aanroepen te vervangen door postMessage() en een eventhandler voor berichten in uw service worker.

Vervang niet-ondersteunde API's

De onderstaande methoden en eigenschappen moeten in Manifest V3 worden aangepast.