Mettre à jour votre code

Mises à jour sans lien 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 expliquent comment remplacer les requêtes Web bloquantes et améliorer la sécurité.

Remplacer la fonction tab.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 réelles.

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 choisir un ensemble.
  • 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.

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

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

Dans un fichier de script d'arrière-plan.

Manifest V3
async function getCurrentTab()
let tab = await getCurrentTab();

chrome.scripting.executeScript({
  target: {tabId: tab.id},
  files: ['content-script.js']
});

Dans le service worker d'extension.

Remplacement de la tab tab.insertCSS() et la tab.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".
  • Soit les autorisations d'hôte, soit l'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.

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

Dans un fichier de script d'arrière-plan.

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

Dans le service worker d'extension.

Remplacer les actions du navigateur et les actions sur 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 se sont dégradées au fil du temps. Dans Manifest V3, ces concepts sont consolidés dans l'API Action. Pour cela, votre manifest.json et votre code d'extension doivent être modifiés différemment de ceux que vous auriez indiqués dans votre script d'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 sur la page, vous pouvez les émuler à l'aide de contenu déclaratif ou appeler enable() ou disable() avec un ID d'onglet.

Remplacez "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".

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

Manifest V2
chrome.browserAction.onClicked.addListener(tab => { ... });
chrome.pageAction.onClicked.addListener(tab => { ... });
Manifest V3
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. Sachez que vous ne pouvez pas utiliser les deux sur le même appel de fonction. Si vous transmettez un rappel, la fonction ne renvoie pas de promesse, et si vous souhaitez qu'une promesse soit renvoyée, n'envoyez 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 accepte les promesses, recherchez la propriété "Promise" dans la documentation de référence de l'API.

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 de 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".

Rappel
chrome.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
Promesse
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 ce faire, vous pouvez actuellement 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.

Méthode ou propriété Manifest V2 Remplacer par
chrome.extension.connect() chrome.runtime.connect()
chrome.extension.connectNative() chrome.runtime.connectNative()
chrome.extension.getExtensionTabs() chrome.extension.getViews()
chrome.extension.getURL() chrome.runtime.getURL()
chrome.extension.lastError Lorsque les méthodes renvoient des promesses, utilisez promise.catch()
chrome.extension.onConnect chrome.runtime.onConnect
chrome.extension.onConnectExternal chrome.runtime.onConnectExternal
chrome.extension.onMessage chrome.runtime.onMessage
chrome.extension.onRequest chrome.runtime.onMessage
chrome.extension.onRequestExternal chrome.runtime.onMessageExternal
chrome.extension.sendMessage() chrome.runtime.sendMessage()
chrome.extension.sendNativeMessage() chrome.runtime.sendNativeMessage()
chrome.extension.sendRequest() chrome.runtime.sendMessage()
chrome.runtime.onSuspend (scripts en arrière-plan) Non disponible avec les service workers d'extensions. Utilisez plutôt l'événement de document beforeunload.
chrome.tabs.getAllInWindow() chrome.tabs.query()
chrome.tabs.getSelected() chrome.tabs.query()
chrome.tabs.onActiveChanged chrome.tabs.onActivated
chrome.tabs.onHighlightChanged chrome.tabs.onHighlighted
chrome.tabs.onSelectionChanged chrome.tabs.onActivated
chrome.tabs.sendRequest() chrome.runtime.sendMessage()
chrome.tabs.Tab.selected chrome.tabs.Tab.highlighted