Créez votre première extension qui insère un nouvel élément sur la page.
Présentation
Ce tutoriel crée une extension qui ajoute le temps de lecture attendu à toute extension Chrome et à toute page de documentation du Chrome Web Store.
Dans ce guide, nous allons expliquer les concepts suivants:
- Fichier manifeste de l'extension.
- Les tailles d'icône utilisées par une extension.
- Comment injecter du code dans des pages à l'aide de scripts de contenu
- Utiliser les modèles de correspondance
- Autorisations de l'extension.
Avant de commencer
Ce guide suppose que vous disposez d'une expérience de base en développement Web. Nous vous recommandons de consulter le tutoriel Hello World pour découvrir le workflow de développement des extensions.
Créer l'extension
Pour commencer, créez un répertoire nommé reading-time 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 des informations sur l'extension
Seul le fichier manifeste JSON est obligatoire. Il contient des informations importantes sur l'extension. Créez un fichier manifest.json à la racine du projet et ajoutez le code suivant:
{
"manifest_version": 3,
"name": "Reading time",
"version": "1.0",
"description": "Add the reading time to Chrome Extension documentation articles"
}
Ces clés contiennent des métadonnées de base pour l'extension. Ils déterminent la façon dont l'extension s'affiche sur la page des extensions et, lorsqu'elle est publiée, sur le Chrome Web Store. Pour en savoir plus, consultez les clés "name", "version" et "description" sur la page de présentation du fichier manifeste.
💡 Autres informations concernant le fichier manifeste de l'extension
- Il doit se trouver à la racine du projet.
- Les seules clés obligatoires sont
"manifest_version","name"et"version". - Il accepte les commentaires (
//) pendant le développement, mais vous devez les supprimer avant d'importer votre code dans le Chrome Web Store.
Étape 2: Fournissez les icônes
Alors, pourquoi avez-vous besoin d'icônes ? Bien que les icônes soient facultatives pendant le développement, elles sont obligatoires si vous prévoyez de distribuer votre extension sur le Chrome Web Store. Elles apparaissent aussi à d'autres endroits, par exemple sur la page de gestion des extensions.
Créez un dossier images et placez-y les icônes. Vous pouvez télécharger les icônes sur GitHub. Ajoutez ensuite le code en surbrillance à votre fichier manifeste pour déclarer les icônes:
{
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
}
}
Nous vous recommandons d'utiliser des fichiers PNG, mais d'autres formats de fichiers sont autorisés, à l'exception des fichiers SVG.
💡 Où ces icônes de taille différente sont-elles affichées ?
| Taille de l'icône | Utilisation des icônes |
|---|---|
| 16x16 | Favicon sur les pages et le menu contextuel de l'extension |
| 32x32 | Les ordinateurs Windows ont souvent besoin de cette taille. |
| 48x48 | S'affiche sur la page "Extensions". |
| 128x128 | S'affiche lors de l'installation et dans le Chrome Web Store. |
Étape 3: Déclarer le script de contenu
Les extensions peuvent exécuter des scripts qui lisent et modifient le contenu d'une page. Ceux-ci sont appelés scripts de contenu. Ils résident dans un monde isolé, ce qui signifie qu'ils peuvent apporter des modifications à leur environnement JavaScript sans entrer en conflit avec les scripts de contenu de leur page hôte ou d'autres extensions.
Ajoutez le code suivant à manifest.json pour enregistrer un script de contenu appelé content.js.
{
"content_scripts": [
{
"js": ["scripts/content.js"],
"matches": [
"https://developer.chrome.com/docs/extensions/*",
"https://developer.chrome.com/docs/webstore/*"
]
}
]
}
Le champ "matches" peut contenir un ou plusieurs formats de correspondance. Ceux-ci permettent au navigateur d'identifier les sites dans lesquels injecter les scripts de contenu. Les modèles de correspondance se composent de trois parties : <scheme>://<host><path>. Ils peuvent contenir les caractères "*".
💡 Cette extension affiche-t-elle un avertissement d'autorisation ?
Lorsqu'un utilisateur installe une extension, le navigateur l'informe de ses fonctionnalités. Les scripts de contenu demandent l'autorisation de s'exécuter sur les sites répondant aux critères de format de correspondance.
Dans cet exemple, l'utilisateur verra l'avertissement d'autorisation suivant:
Pour en savoir plus sur les autorisations des extensions, consultez Déclarer des autorisations et avertir les utilisateurs.
Étape 4: Calculez et insérez le temps de lecture
Les scripts de contenu peuvent utiliser le Document Object Model (DOM) standard pour lire et modifier le contenu d'une page. L'extension vérifie d'abord si la page contient l'élément <article>.
Ensuite, il comptera tous les mots de cet élément et créera un paragraphe qui affiche le temps de lecture total.
Créez un fichier nommé content.js dans un dossier nommé scripts et ajoutez le code suivant:
const article = document.querySelector("article");
// `document.querySelector` may return null if the selector doesn't match anything.
if (article) {
const text = article.textContent;
const wordMatchRegExp = /[^\s]+/g; // Regular expression
const words = text.matchAll(wordMatchRegExp);
// matchAll returns an iterator, convert to array to get word count
const wordCount = [...words].length;
const readingTime = Math.round(wordCount / 200);
const badge = document.createElement("p");
// Use the same styling as the publish information in an article's header
badge.classList.add("color-secondary-text", "type--caption");
badge.textContent = `⏱️ ${readingTime} min read`;
// Support for API reference docs
const heading = article.querySelector("h1");
// Support for article docs with date
const date = article.querySelector("time")?.parentNode;
(date ?? heading).insertAdjacentElement("afterend", badge);
}
💡 Code JavaScript intéressant utilisé dans ce code
- Les expressions régulières, utilisées pour compter uniquement les mots dans l'élément
<article>. insertAdjacentElement()permet d'insérer le nœud du temps de lecture après l'élément.- Propriété classList utilisée pour ajouter des noms de classe CSS à l'attribut de classe d'élément.
- Un chaînage facultatif permet d'accéder à une propriété d'objet susceptible d'être non définie ou nulle.
- Le coalescing nul renvoie
<heading>si<date>est nul ou non défini.
Tester son fonctionnement
Vérifiez que la structure de fichiers de votre projet se présente comme suit:
Charger l'extension en local
Pour charger une extension non empaquetée en mode développeur, suivez la procédure décrite dans Principes de base du développement.
Ouvrir une extension ou la documentation du Chrome Web Store
Voici quelques pages que vous pouvez ouvrir pour voir le temps nécessaire à la lecture de chaque article.
Votre écran devrait ressembler à ceci :
💡 Améliorations potentielles
En vous basant sur ce que vous avez appris aujourd'hui, essayez de mettre en œuvre l'un des éléments suivants:
- Ajoutez un autre schéma de correspondance dans le fichier manifest.json pour prendre en charge les autres pages des développeurs Chrome, comme les Outils pour les développeurs Chrome ou Workbox.
- Ajoutez un script de contenu qui calcule la durée de lecture sur l'un de vos blogs ou sites de documentation préférés.
Continuer à développer
Félicitations, vous avez terminé ce tutoriel 🎉. Continuez à développer vos compétences en suivant d'autres tutoriels de cette série:
| Extension | Objectifs de l'atelier |
|---|---|
| Mode Sans distractions | Pour exécuter du code sur la page actuelle après avoir cliqué sur l'action de l'extension. |
| 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 été utile et sommes impatients de poursuivre votre formation en matière de développement Chrome. Nous vous recommandons de suivre ce parcours de formation:
- 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.