Cette page a été traduite par l'API Cloud Translation.

Injecter des scripts dans l'onglet actif

Simplifiez le style de la page actuelle en cliquant sur l'icône de la barre d'outils de l'extension.

Présentation

Ce tutoriel crée une extension qui simplifie le style de l'extension Chrome et des pages de documentation du Chrome Web Store afin qu'elles soient plus faciles à lire.

Dans ce guide, nous allons vous expliquer comment effectuer les opérations suivantes:

Utilisez le service worker du service d'extension comme coordinateur d'événements.
Protégez la confidentialité des utilisateurs grâce à l'autorisation "activeTab".
Exécuter du code lorsque l'utilisateur clique sur l'icône de la barre d'outils de l'extension.
Insérez et supprimez une feuille de style à l'aide de l'API Scripting.
Exécutez du code à l'aide d'un raccourci clavier.

Avant de commencer

Ce guide part du principe que vous avez une expérience de base en développement Web. Nous vous recommandons de consulter Hello World pour découvrir le workflow de développement d'extensions.

Créer l'extension

Pour commencer, créez un répertoire appelé focus-mode qui contiendra les fichiers de l'extension. Si vous préférez, vous pouvez télécharger le code source complet sur GitHub.

Étape 1: Ajoutez les données et les icônes de l'extension

Créez un fichier nommé manifest.json et incluez le code suivant.

{
  "manifest_version": 3,
  "name": "Focus Mode",
  "description": "Enable focus mode on Chrome's official Extensions and Chrome Web Store documentation.",
  "version": "1.0",
  "icons": {
    "16": "images/icon-16.png",
    "32": "images/icon-32.png",
    "48": "images/icon-48.png",
    "128": "images/icon-128.png"
  }
}

Pour en savoir plus sur ces clés de fichier manifeste, consultez le tutoriel "Exécuter des scripts dans chaque onglet", qui explique plus en détail les metadata et les icônes de l'extension.

Créez un dossier images, puis téléchargez-y les icônes.

Étape 2: Initialiser l'extension

Les extensions peuvent surveiller les événements du navigateur en arrière-plan à l'aide du nœud de calcul de service de l'extension. Les services workers sont des environnements JavaScript spéciaux qui gèrent les événements et s'arrêtent lorsqu'ils ne sont plus nécessaires.

Commencez par enregistrer le service worker dans le fichier manifest.json:

{
  ...
  "background": {
    "service_worker": "background.js"
  },
  ...
}

Créez un fichier nommé background.js et ajoutez le code suivant:

chrome.runtime.onInstalled.addListener(() => {
  chrome.action.setBadgeText({
    text: "OFF",
  });
});

Le premier événement que notre service worker écoutera est runtime.onInstalled(). Cette méthode permet à l'extension de définir un état initial ou d'effectuer certaines tâches lors de l'installation. Les extensions peuvent utiliser l'API Storage et IndexedDB pour stocker l'état de l'application. Toutefois, dans ce cas, comme nous ne gérons que deux états, nous utiliserons le texte du badge de l'action lui-même pour déterminer si l'extension est activée ou désactivée.

Étape 3: Activez l'action de l'extension

L'action de l'extension contrôle l'icône de la barre d'outils de l'extension. Ainsi, chaque fois que l'utilisateur clique sur l'icône de l'extension, du code s'exécute (comme dans cet exemple) ou une fenêtre pop-up s'affiche. Ajoutez le code suivant pour déclarer l'action de l'extension dans le fichier manifest.json:

{
  ...
  "action": {
    "default_icon": {
      "16": "images/icon-16.png",
      "32": "images/icon-32.png",
      "48": "images/icon-48.png",
      "128": "images/icon-128.png"
    }
  },
  ...
}

Utiliser l'autorisation activeTab pour protéger la confidentialité des utilisateurs

L'autorisation activeTab accorde à l'extension la possibilité temporaire d'exécuter du code dans l'onglet actif. Il permet également d'accéder aux propriétés sensibles de l'onglet actuel.

Cette autorisation est activée lorsque l'utilisateur appelle l'extension. Dans ce cas, l'utilisateur appelle l'extension en cliquant sur l'action de l'extension.

💡 Quelles autres interactions utilisateur activent l'autorisation activeTab dans mon extension ?

Appuyer sur une combinaison de touches
Sélection d'un élément de menu contextuel.
Accepter une suggestion de l'omnibox
Ouverture d'un pop-up d'extension.

L'autorisation "activeTab" permet aux utilisateurs de choisir intentionnellement d'exécuter l'extension dans l'onglet actif. Elle protège ainsi la confidentialité de l'utilisateur. Autre avantage : elle ne déclenche pas d'avertissement d'autorisation.

Pour utiliser l'autorisation "activeTab", ajoutez-la au tableau d'autorisations du fichier manifeste:

{
  ...
  "permissions": ["activeTab"],
  ...
}

Étape 4: Suivre l'état de l'onglet actuel

Une fois que l'utilisateur a cliqué sur l'action de l'extension, celle-ci vérifie si l'URL correspond à une page de documentation. Ensuite, il vérifie l'état de l'onglet actuel et définit l'état suivant. Ajoutez le code suivant à background.js:

const extensions = 'https://developer.chrome.com/docs/extensions';
const webstore = 'https://developer.chrome.com/docs/webstore';

chrome.action.onClicked.addListener(async (tab) => {
  if (tab.url.startsWith(extensions) || tab.url.startsWith(webstore)) {
    // Retrieve the action badge to check if the extension is 'ON' or 'OFF'
    const prevState = await chrome.action.getBadgeText({ tabId: tab.id });
    // Next state will always be the opposite
    const nextState = prevState === 'ON' ? 'OFF' : 'ON';

    // Set the action badge to the next state
    await chrome.action.setBadgeText({
      tabId: tab.id,
      text: nextState,
    });
  }
});

Étape 5: Ajoutez ou supprimez la feuille de style

Il est maintenant temps de modifier la mise en page de la page. Créez un fichier nommé focus-mode.css et incluez le code suivant:

* {
  display: none !important;
}

html,
body,
*:has(article),
article,
article * {
  display: revert !important;
}

[role='navigation'] {
  display: none !important;
}

article {
  margin: auto;
  max-width: 700px;
}

Insérez ou supprimez la feuille de style à l'aide de l'API Scripting. Commencez par déclarer l'autorisation "scripting" dans le fichier manifeste:

{
  ...
  "permissions": ["activeTab", "scripting"],
  ...
}

Enfin, dans background.js, ajoutez le code suivant pour modifier la mise en page de la page:

  ...
    if (nextState === "ON") {
      // Insert the CSS file when the user turns the extension on
      await chrome.scripting.insertCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    } else if (nextState === "OFF") {
      // Remove the CSS file when the user turns the extension off
      await chrome.scripting.removeCSS({
        files: ["focus-mode.css"],
        target: { tabId: tab.id },
      });
    }
  }
});

💡 Puis-je utiliser l'API Scripting pour injecter du code au lieu d'une feuille de style ?

Oui. Vous pouvez utiliser scripting.executeScript() pour injecter du code JavaScript.

Facultatif: Attribuer un raccourci clavier

Juste pour le plaisir, ajoutez un raccourci pour activer ou désactiver plus facilement le mode Sans distractions. Ajoutez la clé "commands" au fichier manifeste.

{
  ...
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+B",
        "mac": "Command+B"
      }
    }
  }
}

La touche "_execute_action" exécute le même code que l'événement action.onClicked(). Aucun code supplémentaire n'est donc nécessaire.

Vérifier que le code fonctionne

Vérifiez que la structure de fichiers de votre projet se présente comme suit:

Contenu du dossier du mode de concentration: manifest.json, background.js, focus-mode.css et le dossier images.

Charger votre extension en local

Pour charger une extension non empaquetée en mode développeur, suivez la procédure décrite dans Hello World.

Tester l'extension sur une page de documentation

Commencez par ouvrir l'une des pages suivantes:

Cliquez ensuite sur l'action de l'extension. Si vous configurez un raccourci clavier, vous pouvez le tester en appuyant sur Ctrl + B ou Cmd + B.

Il doit se présenter comme suit:

Extension du mode Sans distractions DÉSACTIVÉE — Extension du mode Sans distractions désactivée

par celle-ci :

Extension du mode Sans distractions activée

🎯 Améliorations potentielles

Sur la base de ce que vous avez appris aujourd'hui, essayez d'accomplir l'une des tâches suivantes:

Améliorez la feuille de style CSS.
Attribuez un autre raccourci clavier.
modifier la mise en page de votre blog ou site de documentation préféré ;

Continuez de vous développer.

Félicitations ! Vous avez terminé ce tutoriel 🎉. Poursuivez votre apprentissage en suivant les autres tutoriels de cette série:

Extension	Objectifs de l'atelier
Temps de lecture	Insérer automatiquement un élément dans un ensemble de pages spécifique
Gestionnaire d'onglets	Créer une fenêtre pop-up qui gère les onglets du navigateur

Continuer à explorer

Nous espérons que vous avez apprécié créer cette extension Chrome et que vous avez hâte de poursuivre votre parcours d'apprentissage du développement d'extensions. Nous vous recommandons les parcours d'apprentissage suivants:

Le guide du développeur contient des dizaines de liens supplémentaires vers des documents pertinents pour la création d'extensions avancées.
Les extensions ont accès à des API puissantes qui vont au-delà de ce qui est disponible sur le Web ouvert. La documentation des API Chrome présente chacune d'elles.