Exemple : Insertion d’images à l’aide d’un script de contenu

Cet exemple utilise du code JavaScript pour insérer l’image stars.jpeg en haut de la page web actuelle, à l’intérieur de l’élément <body> . La fenêtre contextuelle de l’extension contient un titre et un bouton HTML intitulé Insérer une image. Lorsque vous cliquez sur le bouton Insérer une image , le code JavaScript de l’extension envoie un message à partir de la fenêtre contextuelle de l’icône de l’extension et insère dynamiquement le code JavaScript qui s’exécute dans l’onglet du navigateur.

Cet exemple présente les fonctionnalités d’extension suivantes :

• Injection de bibliothèques JavaScript dans une extension.
• Exposition des ressources d’extension aux onglets du navigateur.
• Inclusion des pages web de contenu dans les onglets de navigateur existants.
• Demander aux pages web de contenu d’écouter les messages des fenêtres contextuelles et de répondre.

Aperçu de l’exemple

Vous allez installer l’exemple d’extension en utilisant l’onglet Gérer les extensions du navigateur, cliquer sur le bouton Extensions () pour afficher la liste des extensions installées, puis cliquer sur cet exemple d’extension :

L’extension affiche une petite page web HTML dans une fenêtre contextuelle, contenant un titre, un bouton Insérer une image et des instructions :

Lorsque vous cliquez sur le bouton Insérer une image , le code JavaScript s’insère stars.jpeg temporairement en haut de la page web actuelle, poussant le contenu de la page web vers le bas sous l’image. Le contenu injecté définit l’élément image pour afficher l’image stars.jpeg statique en haut de la page web actuelle :

Lorsque vous cliquez sur l’image, le JavaScript injecté supprime l’image de l’arborescence DOM et de la page web.

Obtenez, installez et exécutez l’exemple comme suit.

Cloner le dépôt MicrosoftEdge-Extensions

Vous pouvez utiliser différents outils pour cloner un référentiel GitHub. Vous pouvez télécharger un répertoire sélectionné ou cloner l’intégralité du dépôt.

Clonez le référentiel MicrosoftEdge-Extensions sur votre lecteur local, puis basculez vers une branche opérationnelle, comme suit.

Installer l’exemple en local (chargement indépendant)

Au lieu d’installer l’exemple à partir du site web des modules complémentaires Microsoft Edge , vous allez l’installer localement, de sorte que vous pouvez éventuellement le modifier et tester rapidement les modifications. L’installation locale est parfois appelée chargement indépendant d’une extension.

1. Dans Microsoft Edge, cliquez sur le bouton Extensions (), en regard de la barre d’adresses, si cette icône est affichée. Ou sélectionnez Paramètres et plus (> « Paramètres et plus ») Extensions. La fenêtre contextuelle Extensions s’ouvre :

   

2. Cliquez sur Gérer les extensions. La page Gestion des extensions s’ouvre dans un nouvel onglet :

   

3. Activez le bouton bascule du mode développeur.

4. Lors de la première installation de l’exemple d’extension, cliquez sur le bouton Charger décompressé ( La boîte de dialogue Sélectionner le répertoire d’extensions s’ouvre.

5. Sélectionnez le répertoire qui contient les fichiers sources de l’extension, par manifest.jsonexemple .

   Exemple de chemin d’accès :

   C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-inserter-content-script

6. Cliquez sur le bouton Sélectionner un dossier .

   La boîte de dialogue Sélectionner le répertoire d’extensions se ferme.

   L’extension est installée dans le navigateur, comme une extension installée à partir du site web des modules complémentaires Microsoft Edge :

   

Exécution de l’exemple

1. Accédez à une page web, telle que l’application TODO, dans une nouvelle fenêtre ou un nouvel onglet. L’onglet ne doit pas être vide et ne doit pas être la page Gérer les extensions, car cet exemple insère du contenu dans la page web actuelle.

2. Actualisez la page web. Cela est parfois nécessaire après le rechargement d’une extension.

3. Dans Microsoft Edge, à droite de la barre d’adresse, si cette icône est affichée, cliquez sur le bouton Extensions (). Vous pouvez également sélectionner Paramètres et autres (> « Paramètres et plus »).

   La fenêtre contextuelle Extensions s’ouvre :

   

4. Cliquez sur l’icône ou le nom de l’extension (Inserteur d’image à l’aide d’un script de contenu).

   L’extension s’ouvre et l’icône de l’extension est ajoutée en regard de la barre d’adresse et de l’icône des extensions ().

   Une fenêtre contextuelle s’ouvre, contenant une petite page web HTML avec un titre, un bouton Insérer une image et des instructions :

   

5. Cliquez sur le bouton Insérer une image . stars.jpeg est inséré en haut de la page web actuelle dans l’onglet actif, poussant le contenu de la page web vers le bas sous l’image :

   

6. Cliquez sur l’image stars.jpeg qui remplit le haut de la page web. Cet élément d’image est supprimé de l’arborescence DOM et de la page Web, et la page Web actuelle est restaurée, déplaçant son contenu vers le haut de l’onglet.

L’extension envoie un message à partir de la fenêtre contextuelle de l’icône d’extension et insère dynamiquement un code JavaScript s’exécutant en tant que contenu dans l’onglet du navigateur. Le contenu injecté définit l’élément image à afficher stars.jpeg en haut de la page Web actuelle, puis supprime l’image lorsque vous cliquez sur l’image.

Voir aussi :

• Charger une version test d’une extension pour l’installer et la tester localement

Étudier l’échantillon

Dans les sections suivantes, vous étudiez l’échantillon. Ensuite, pour développer votre propre extension Microsoft Edge, vous pouvez copier et modifier le répertoire de l’exemple, puis installer et tester l’extension résultante.

Files et répertoires

L’exemple comprend la structure de répertoires et de fichiers suivante.

Exemple de chemin d’accès pour l’exemple :

C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-inserter-content-script

Répertoires et fichiers dans le /picture-inserter-content-script/ répertoire :

/content-scripts/
   content.js
/icons/
   extension-icon16x16.png
   extension-icon32x32.png
   extension-icon48x48.png
   extension-icon128x128.png
/images/
   stars.jpeg
/popup/
   popup.html
   popup.js
manifest.json

• Le /content-scripts/ répertoire contient content.js, qui est le script injecté dans la page web actuelle.
• Le /icons/ répertoire contient les versions d’un .png fichier utilisé pour représenter l’extension près de la barre d’adresse du navigateur, dans la fenêtre contextuelle Extensions et dans la page de gestion des extensions .
• Le /images/ répertoire contient stars.jpeg, qui est affiché dans la fenêtre contextuelle de l’extension.
• Le /popup/ répertoire contient les fichiers suivants :
  • popup.html Définit le contenu de la page web contextuelle initiale de l’extension (un titre, un bouton et des instructions).
  • popup.js for the initial pop-up webpage envoie un message au script de contenu (content.js) en cours d’exécution sur la page d’onglets, spécifiant le fichier image à afficher.
• manifest.json Contient des informations de base sur l’extension.

Stratégie de mise à jour de la page Web pour insérer l’image en haut (stars.jpeg)

Cet exemple inclut un script de contenu qui est injecté dans la page web chargée dans l’onglet actuel du navigateur.

1. Lorsque vous exécutez l’exemple d’extension, la page HTML contextuelle initiale s’affiche (popup.html ), avec un titre, des instructions et le bouton Insérer une image .

2. Lorsque vous cliquez sur le bouton Insérer une image , le code JavaScript (popup.js) de la page contextuelle initiale envoie un message au script de contenu (content.js) qui s’exécute sur la page d’onglets. Le message spécifie le fichier image à afficher.

3. Le script de contenu (content.js) exécuté sur la page d’onglet reçoit le message et affiche le fichier image spécifié (stars.jpeg).

La page web contextuelle initiale (popup.html)

/popup/popup.html est spécifié dans le fichier manifeste en tant que page web à afficher dans la fenêtre contextuelle initiale de l’extension. Le fichier manifeste contient le champ "default_popup": "popup/popup.html"clé . Le fichier de popup.html cet exemple est une petite page web qui contient un titre, un bouton Insérer une image et des instructions.

popup.html:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <style>
            body {
                width: 500px;
            }
            button {
                background-color: #336dab;
                border: none;
                color: white;
                padding: 15px 32px;
                text-align: center;
                font-size: 16px;
            }
        </style>
    </head>
    <body>
        <h1>Picture inserter using a content script</h1>
        <button id="sendmessageid">Insert picture</button>
        <script src="popup.js"></script>
        <p>Click the displayed image to remove it from the webpage.</p>
    </body>
</html>

JavaScript (popup.js) pour la page contextuelle initiale, afin d’envoyer un message au serveur JavaScript injecté

/popup/popup.js Envoie un message au script de contenu (content.js) qui est temporairement injecté dans l’onglet du navigateur. Pour ce faire, popup.js ajoutez un événement au bouton Insérer une onclickimage de la page web contextuelle, qui a l’ID sendmessageid:

popup.js (partie) :

const sendMessageId = document.getElementById("sendmessageid");
if (sendMessageId) {
    sendMessageId.onclick = function() {
        ...
    };
}

Dans popup.js, chrome.tabs.query trouve l’onglet actuel du navigateur et chrome.tabs.sendMessage envoie un message à cet onglet. L’exemple passe dans l’ID de l’onglet actif. Le message doit inclure l’URL de l’image qui s’affichera.

Vous devez envoyer un ID unique à attribuer à l’image insérée, afin de retrouver l’élément image ultérieurement et de le supprimer. Pour envoyer un ID unique à attribuer à l’image insérée, l’ID unique est généré popup.js et transmis au script de contenu.

popup.js (complet) :

const sendMessageId = document.getElementById("sendmessageid");
if (sendMessageId) {
    sendMessageId.onclick = function() {
        chrome.tabs.query({ active: true, currentWindow: true }, function(tabs) {
            chrome.tabs.sendMessage(
                tabs[0].id,
                {
                    url: chrome.runtime.getURL("images/stars.jpeg"),
                    imageDivId: crypto.randomUUID(),
                    tabId: tabs[0].id
                },
                function(response) {
                    window.close();
                }
            );
        });
    };
}

Le script de contenu message écouteur (content.js)

Voici le content-scripts\content.js fichier qui est injecté dans chaque page d’onglet du navigateur. Ce fichier est répertorié dans la content-scripts section du manifest.json

content.js (complet) :

chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
  const img = document.createElement("img");
  img.id = request.imageDivId;
  img.src = request.url;
  img.style = "height: auto; width: 90vw;";
  document.body.prepend(img);

  img.addEventListener("click", () => {
      img.remove();
  }, { once: true });

  sendResponse({ fromcontent: "This message is from content.js" });
});

content.js enregistre un écouteur à l’aide de la méthode API Extension chrome.runtime.onMessage.addListener . Cet écouteur attend le message envoyé lors popup.js des appels chrome.tabs.sendMessage.

Dans content.js, la addListener méthode prend un seul paramètre qui est une fonction. Le premier paramètre de cette fonction, request, contient les détails du message transmis.

Dans content.js, lorsqu’un événement est traité par l’écouteur, la fonction d’écouteur qui est transmise dans addListener est exécutée. Le premier paramètre de la fonction d’écoute transmise est un request objet qui a des attributs attribués par sendMessage.

Dans popup.js, pour l’appel de méthode chrome.tabs.sendMessage , les attributs du deuxième paramètre pour sendMessage sont url, imageDivId, et tabId.

Voici la fonction d’écoute isolée qui est transmise à addListener:

content.js (partie)

function(request, sender, sendResponse) {
  const img = document.createElement("img");
  img.id = request.imageDivId;
  img.src = request.url;
  img.style = "height: auto; width: 90vw;";
  document.body.prepend(img);

  img.addEventListener("click", () => {
      img.remove();
  }, { once: true });

  sendResponse({ fromcontent: "This message is from content.js" });
}

Les cinq premières lignes de la fonction d’écoute ajoutent un img élément immédiatement en dessous de l’élément dans l’onglet body du navigateur.

La deuxième ligne de la fonction d’écouteur, img.id = request.imageDivId;, définit l’ID de l’élément img sur la imageDivId demande transmise.

Dans la fonction d’écouteur, l’appel addEventListener ajoute une click fonction d’écouteur d’événements qui couvre l’ensemble de l’image, permettant à l’utilisateur de cliquer n’importe où sur l’image. Lorsque vous cliquez sur l’image insérée, l’image est supprimée de la page Web actuelle par la ligne img.remove();, et l’écouteur d’événements est également supprimé, en spécifiant { once: true }.

Mode stars.jpeg d’accès à partir de n’importe quel onglet de navigateur

Pour rendre images/stars.jpeg disponible à partir de n’importe quel onglet de navigateur :

• popup.js (ci-dessus) utilise l’API chrome.runtime.getURL .
• Le manifeste (ci-dessous) spécifie que web_accessible_resources le type .jpeg correspond à toutes les URL.

L’exemple injecte l’image à l’aide de l’attribut src de l’élément img dans la page de contenu. La page de contenu s’exécute sur un thread unique qui n’est pas le même que celui qui exécute l’extension. Le fichier image statique doit être exposé en tant que ressource web pour qu’il fonctionne correctement.

Une autre entrée est ajoutée dans le manifest.json fichier pour déclarer que l’image est disponible pour tous les onglets du navigateur :

/manifest.json (partie) :

"web_accessible_resources": [
    {
      "resources": ["images/*.jpeg"],
      "matches": ["<all_urls>"]
    }
  ]

Le code du popup.js fichier envoie un message à la page de contenu incorporée dans la page d’onglet active actuelle.

Comment les ressources sont répertoriées dans le manifeste (manifest.json)

L’exemple crée et injecte la page de contenu incorporée dans la page d’onglet active actuelle. manifest.jsoncomprend le et web_accessible_resources, content-scripts comme suit :

/manifest.json (complet) :

{
    "name": "Picture inserter using content script",
    "version": "0.0.0.1",
    "manifest_version": 3,
    "description": "A browser extension that uses JavaScript to insert an image at the top of the current webpage.",
    "icons": {
        "16": "icons/extension-icon16x16.png",
        "32": "icons/extension-icon32x32.png",
        "48": "icons/extension-icon48x48.png",
        "128": "icons/extension-icon128x128.png"
    },
    "action": {
        "default_popup": "popup/popup.html"
    },
    "content_scripts": [
        {
            "matches": [
              "<all_urls>"
            ],
            "js": ["content-scripts/content.js"]
        }
    ],
    "web_accessible_resources": [
        {
            "resources": ["images/*.jpeg"],
            "matches": ["<all_urls>"]
        }
    ]
}

La section du content_scripts manifeste injecte JavaScript dans tous les onglets du navigateur

Dans la content_scripts section clé du fichier manifeste, l’attribut matches est défini sur <all_urls>, ce qui signifie que .js (ou .css) les fichiers spécifiés dans la section clé content_scripts sont injectés dans toutes les pages d’onglets du navigateur lorsque chaque onglet est chargé. Les types de fichiers autorisés qui peuvent être injectés sont JavaScript (.js) et CSS (.css).

Le manifeste de cet exemple spécifie un script de contenu unique, content-scripts/content.js.

Chaque script de contenu s’exécute dans son propre thread, en bac à sable

Chaque page d’onglet (et extension) s’exécute dans son propre thread. Même si l’onglet du navigateur contient une page web qui exécute du code JavaScript, le content.js script injecté dans cet onglet du navigateur par l’extension n’a pas accès à ce code JavaScript. Le script de contenu injecté a uniquement accès au DOM de la page web.

Étapes suivantes

Pour développer votre propre extension Microsoft Edge, vous pouvez copier et modifier le répertoire de l’exemple, puis installer et tester l’extension résultante.

Voir aussi

• Exemple : page web contextuelle de la visionneuse d’images
• Charger une version test d’une extension pour l’installer et la tester localement
• Exemples pour les extensions Microsoft Edge

GitHub :

• référentiel MicrosoftEdge-Extensions .
  • /picture-inserter-content-script/ : code source de cet exemple.