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

Présentation

Ce tutoriel crée une extension qui simplifie le style de l'extension Chrome et 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 d'extension en tant que coordinateur d'événements.
  • Préservez la confidentialité des utilisateurs grâce à l'autorisation "activeTab".
  • Exécuter 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

Dans ce guide, nous partons du principe que vous avez des connaissances de base en développement Web. Nous vous recommandons de vérifier Hello World pour obtenir une présentation du 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 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 la section "Exécuter des scripts sur tous les onglets" qui explique 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 de l'extension ou un nœud de calcul. Les service workers sont des environnements JavaScript spéciaux qui gèrent des événements et s'arrêtent quand 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 écouter est runtime.onInstalled() Cette méthode permet à l'extension de définir une adresse ou d'effectuer des 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 précis, puisque 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é".

É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. Dès que l'utilisateur clique sur le bouton elle exécute du code (comme dans cet exemple) ou affiche un pop-up. Ajoutez le 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 permet à l'extension d'exécuter du code temporairement dans l'onglet actif. Elle permet également d'accéder aux propriétés sensibles l'onglet actuel.

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

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

  • Appuyer sur une combinaison de raccourcis clavier
  • Sélection d'un élément de menu contextuel
  • Acceptation d'une suggestion de l'omnibox.
  • Ouverture d'une fenêtre pop-up d'extension en cours.

L'autorisation "activeTab" permet aux utilisateurs de choisir délibérément d'exécuter l'extension sur le sélectionné ; de cette façon, elle protège la vie privée de l'utilisateur. Un autre avantage est qu'il n'a pas déclencher un 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 à de documentation. Ensuite, il va vérifier l'état de l'onglet actuel et définir l'état suivant. Ajoutez le le code suivant en 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. 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éclarez 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 de script pour injecter du code au lieu d'une feuille de style ?

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

Facultatif: Attribuez un raccourci clavier

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

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

La clé "_execute_action" exécute le même code que l'événement action.onClicked(). Par conséquent, aucune est nécessaire.

Tester son fonctionnement

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

Contenu du dossier du mode formulaire: 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 les étapes décrites dans Hello World.

Tester l'extension sur une page de documentation

Tout d'abord, ouvrez l'une des pages suivantes:

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

Il doit partir de ceci:

<ph type="x-smartling-placeholder">
</ph> Extension du mode Sans distractions désactivée <ph type="x-smartling-placeholder">
</ph> Extension Mode Sans distractions désactivée
.

par celle-ci :

<ph type="x-smartling-placeholder">
</ph> Extension du mode Sans distractions activée <ph type="x-smartling-placeholder">
</ph> Extension Mode Sans distractions activée
.

💡 Améliorations potentielles

En vous basant sur ce que vous avez appris aujourd'hui, essayez de réaliser l'une des tâches suivantes:

  • Améliorez la feuille de style CSS.
  • Attribuez un raccourci clavier différent.
  • Modifiez la mise en page de votre blog préféré 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 terminant d'autres 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 Pour 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 impatients de la poursuivre. d'apprentissage du développement d'applications. Nous vous recommandons les parcours de formation suivants:

  • Le guide du développeur contient des dizaines de liens supplémentaires vers de la documentation. pertinentes pour créer des extensions avancées.
  • Les extensions ont accès à des API puissantes, en plus de celles disponibles sur le Web ouvert. La documentation des API Chrome décrit chacune de ces API.