Mettre à jour votre code

Mises à jour sans rapport avec d'autres problèmes

Ceci est la première des trois sections qui décrivent les modifications à apporter au code qui ne fait pas partie du service worker d'extension. Cette section concerne les modifications de code requises qui ne sont pas liées à d'autres problèmes. Les deux sections suivantes traitent du remplacement des requêtes Web bloquantes et de l'amélioration de la sécurité.

Remplacez tabs.executeScript() par scripting.executeScript()

Dans Manifest V3, executeScript() passe de l'API tabs à l'API scripting. Pour ce faire, vous devez modifier les autorisations dans le fichier manifeste en plus des modifications de code.

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

• L'autorisation "scripting".
• Soit les autorisations d'hôte, soit l'autorisation "activeTab".

La méthode scripting.executeScript() est semblable à son fonctionnement 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 en sélectionner un seul.
• Vous transmettez également un objet ScriptInjection au lieu de InjectDetails. Il existe de nombreuses différences entre les deux. Par exemple, tabId est maintenant transmis en tant que membre de ScriptInjection.target plutôt qu'en tant qu'argument de méthode.

L'exemple montre comment procéder.

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

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. Pour ce faire, vous devez modifier les autorisations dans le fichier manifeste en plus du 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 plutôt qu'en tant qu'argument de méthode.

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

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

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

Remplacer les actions du navigateur et les actions de la page par des actions

Les actions du navigateur et les actions sur la page étaient des concepts distincts dans Manifest 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. Pour ce faire, vous devez modifier votre code manifest.json et d'extension, qui est différent de celui que vous auriez mis dans votre script en arrière-plan Manifest V2.

Les actions dans Manifest V3 ressemblent le plus aux actions du navigateur. Toutefois, l'API action ne fournit pas hide() et show(), contrairement à pageAction. Si vous avez toujours besoin d'actions de page, vous pouvez les émuler à l'aide de contenu déclaratif ou 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

Si votre Manifest V2 utilisait les API browserAction et pageAction, vous devez maintenant utiliser l'API action.

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

chrome.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 tout ce que vous devez savoir pour les utiliser dans une extension Chrome.

Pour assurer la rétrocompatibilité, de nombreuses méthodes continuent à accepter les rappels après l'ajout de la prise en charge des promesses. Notez que vous ne pouvez pas utiliser les deux 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, telles que 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" (Promesse) dans sa documentation de référence.

Pour convertir un rappel en promesse, supprimez le rappel et gérez la promesse renvoyée. L'exemple ci-dessous est tiré de l'exemple d'autorisations facultatives, spécifiquement pour newtab.js. 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 la commande "async" et "await".

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

Remplacer les fonctions nécessitant un contexte d'arrière-plan Manifest V2

D'autres contextes d'extension ne peuvent interagir avec les service workers d'extensions qu'à l'aide de la transmission de messages. Par conséquent, vous devez remplacer les appels qui attendent un contexte d'arrière-plan, notamment:

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

Vos scripts d'extension doivent utiliser la transmission de messages pour communiquer entre un service worker et d'autres parties de votre extension. Pour le moment, vous pouvez utiliser sendMessage() et implémenter chrome.runtime.onMessage dans votre service worker d'extension. À long terme, pensez à 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.