Injecter des scripts dans l'onglet actif

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

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 d'en faciliter la lecture.

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

  • Utilisez le service worker d'extension comme coordinateur d'événements.
  • Préservez la confidentialité des utilisateurs grâce à l'autorisation "activeTab".
  • Exécutez le 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.
  • Utilisez un raccourci clavier pour exécuter du code.

Avant de commencer

Ce guide suppose que vous disposez d'une expérience de base en développement Web. Nous vous recommandons de consulter Hello World pour découvrir le workflow de développement des extensions.

Créer l'extension

Pour commencer, créez un répertoire nommé focus-mode qui contiendra les fichiers de l'extension. Si vous le souhaitez, 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 sur chaque onglet" qui explique plus en détail les métadonnées et les icônes de l'extension.

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

Étape 2: Initialiser l'extension

Les extensions peuvent surveiller les événements du navigateur en arrière-plan à l'aide du service worker de l'extension. Les service workers sont des environnements JavaScript spéciaux qui gèrent les événements et s'arrêtent lorsqu'ils ne sont pas 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 écoute 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 traitons que deux états, nous utiliserons le texte du badge de l'action lui-même pour savoir 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, il exécute du code (comme dans cet exemple) ou affiche un pop-up. Ajoutez le code suivant pour déclarer l'action d'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 permet à l'extension d'exécuter du code temporairement dans l'onglet actif. Elle 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 son action.

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

  • En appuyant sur une combinaison de raccourcis clavier.
  • Sélection d'un élément de menu contextuel
  • Acceptation d'une suggestion de l'omnibox...
  • Ouverture d'un pop-up d'extension...

L'autorisation "activeTab" permet aux utilisateurs de choisir délibérément d'exécuter l'extension dans l'onglet sélectionné. Cela permet de protéger la confidentialité de l'utilisateur. Un autre avantage est qu'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: Suivez l'état de l'onglet actuel

Lorsque l'utilisateur clique sur l'action de l'extension, celle-ci vérifie si l'URL correspond à une page de documentation. Ensuite, il vérifiera 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: Ajouter ou supprimer 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:

body > .scaffold > :is(top-nav, navigation-rail, side-nav, footer),
main > :not(:last-child),
main > :last-child > navigation-tree,
main .toc-container {
  display: none;
}

main > :last-child {
  margin-top: min(10vmax, 10rem);
  margin-bottom: min(10vmax, 10rem);
}

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:

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

Pour vous amuser, 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.

Tester son fonctionnement

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

Le contenu du dossier du mode formulaire: manifest.json, background.js, focus-mode.css et le dossier images.

Charger l'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:

Ensuite, cliquez sur l'action de l'extension. Si vous avez configuré un raccourci clavier, vous pouvez le tester en appuyant sur Ctrl + B ou Cmd + B.

Voici à quoi doit ressembler le code ci-dessous:

Extension Mode Sans distractions désactivée
Extension Mode Sans distractions désactivée

par celle-ci :

Extension Mode Sans distractions activée
Extension du mode Sans distractions activée

💡 Améliorations potentielles

En vous basant sur ce que vous avez appris aujourd'hui, essayez d'accomplir l'une des actions suivantes:

  • Améliorer la feuille de style CSS
  • Attribuez un autre raccourci clavier.
  • Modifiez la mise en page de votre blog ou de votre site de documentation favori.

Continuez de vous développer.

Félicitations, vous avez terminé ce tutoriel 🎉. Continuez à améliorer vos compétences en suivant les autres tutoriels de cette série:

Extension Objectifs de l'atelier
Temps de lecture Pour insérer automatiquement un élément sur un ensemble spécifique de pages
Gestionnaire d'onglets Créer un pop-up qui gère les onglets du navigateur

Continuer à explorer

Nous espérons que cette extension Chrome vous a plu et sommes ravis de poursuivre votre formation sur le développement d'extensions. Nous vous recommandons de suivre les parcours de formation suivants:

  • Le guide du développeur contient des dizaines de liens supplémentaires vers des documents liés à la création avancée d'extensions.
  • Les extensions ont accès à des API puissantes, en plus de celles disponibles sur le Web ouvert. La documentation des API Chrome présente chaque API.