Mettre à jour votre code

Mises à jour non liées à d'autres problèmes

Il s'agit de la première des trois sections décrivant les modifications nécessaires pour le code qui ne fait pas partie du service worker de l'extension. Cette section est réservée aux modifications de code obligatoires qui ne sont pas liées à d'autres problèmes. Les deux sections suivantes expliquent comment remplacer les requêtes Web bloquantes et améliorer la sécurité.

Remplacer tabs.executeScript() par scripting.executeScript()

Dans Manifest V3, executeScript() passe de l'API tabs à l'API scripting. Cela nécessite de modifier les autorisations dans le fichier manifeste, en plus des modifications de code proprement dites.

Pour la méthode executeScript(), vous avez besoin des éléments suivants :

• L'autorisation "scripting".
• Autorisations d'hôte ou autorisation "activeTab".

La méthode scripting.executeScript() est semblable à celle utilisée avec tabs.executeScript(). Il existe quelques différences.

• Alors que l'ancienne méthode ne pouvait accepter qu'un seul fichier, la nouvelle méthode peut accepter un tableau de fichiers.
• Vous transmettez également un objet ScriptInjection au lieu de InjectDetails. Il existe de nombreuses différences entre les deux. Par exemple, tabId est désormais transmis en tant que membre de ScriptInjection.target au lieu d'être transmis en tant qu'argument de méthode.

L'exemple montre comment procéder.

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

Remplacez tabs.insertCSS() et tabs.removeCSS() par scripting.insertCSS() et scripting.removeCSS().

Dans Manifest V3, insertCSS() et removeCSS() passent de l'API tabs à l'API scripting. Cela nécessite des modifications des autorisations dans le fichier manifeste, en plus des modifications de code :

• L'autorisation "scripting".
• Autorisations d'hôte ou autorisation "activeTab".

Les fonctions de l'API scripting sont semblables à celles de tabs. Il existe quelques différences.

• Lorsque vous appelez ces méthodes, vous transmettez un objet CSSInjection au lieu de InjectDetails.
• tabId est désormais transmis en tant que membre de CSSInjection.target au lieu d'être transmis en tant qu'argument de méthode.

L'exemple montre comment procéder pour insertCSS(). La procédure pour removeCSS() est la même.

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

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

Remplacer les actions de navigateur et de page par des actions

Les actions de navigateur et les actions de page étaient des concepts distincts dans le fichier manifeste V2. Bien qu'ils aient commencé avec des rôles distincts, les différences entre eux ont diminué au fil du temps. Dans Manifest V3, ces concepts sont regroupés dans l'API Action. Cela nécessite des modifications dans votre manifest.json et le code d'extension, qui sont différents de ce que vous auriez mis dans votre script d'arrière-plan Manifest V2.

Les actions dans Manifest V3 ressemblent beaucoup aux actions du navigateur. Toutefois, l'API action ne fournit pas hide() et show() comme le faisait pageAction. Si vous avez encore besoin d'actions de page, vous pouvez soit les émuler à l'aide de contenu déclaratif, soit appeler enable() ou disable() avec un ID d'onglet.

Remplacer "browser_action" et "page_action" par "action"

Dans manifest.json, remplacez les champs "browser_action" et "page_action" par le champ "action". Consultez la documentation de référence pour en savoir plus sur le champ "action".

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

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

  ...
}

Remplacer les API browserAction et pageAction par l'API action

Là où votre fichier manifeste V2 utilisait les API browserAction et pageAction, vous devez désormais utiliser l'API action.

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

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

Remplacer les rappels par des promesses

Dans Manifest V3, de nombreuses méthodes d'API d'extension renvoient des promesses. Une promesse est un proxy ou un espace réservé pour une valeur renvoyée par une méthode asynchrone. Si vous n'avez jamais utilisé de promesses, vous pouvez en savoir plus sur MDN. Cette page décrit ce que vous devez savoir pour les utiliser dans une extension Chrome.

Pour assurer la rétrocompatibilité, de nombreuses méthodes continuent de prendre en charge les rappels après l'ajout de la prise en charge des promesses. Notez que vous ne pouvez pas utiliser les deux en même temps dans le même appel de fonction. Si vous transmettez un rappel, la fonction ne renverra pas de promesse. Si vous souhaitez qu'une promesse soit renvoyée, ne transmettez pas de rappel. Certaines fonctionnalités de l'API, comme les écouteurs d'événements, continueront de nécessiter des rappels. Pour vérifier si une méthode est compatible avec les promesses, recherchez le libellé "Promise" dans sa documentation de référence de l'API.

Pour passer d'un rappel à une promesse, supprimez le rappel et gérez la promesse renvoyée. L'exemple ci-dessous est tiré de l'exemple d'autorisations facultatives, newtab.js plus précisément. La version avec rappel montre à quoi ressemblerait l'appel de l'exemple à request() avec un rappel. Notez que la version de la promesse peut être réécrite avec async et 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');
  }
});

Remplacer les fonctions qui attendent un contexte d'arrière-plan Manifest V2

Les autres contextes d'extension ne peuvent interagir avec les workers de service d'extension qu'à l'aide du transfert de messages. Par conséquent, vous devrez remplacer les appels qui attendent un contexte d'arrière-plan, en particulier :

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

Les scripts de votre extension doivent utiliser le transfert de messages pour communiquer entre un service worker et d'autres parties de votre extension. Pour le moment, vous pouvez y parvenir en utilisant sendMessage() et en implémentant browser.runtime.onMessage dans le service worker de votre extension. À long terme, vous devez prévoir de remplacer ces appels par postMessage() et le gestionnaire d'événements de message d'un service worker.

Remplacer les API non compatibles

Les méthodes et propriétés listées ci-dessous doivent être modifiées dans Manifest V3.