Extension Chrome - configuration de l'environnement

Je veux des fonctionnalités loufoques dans mon navigateur. Peut-être que je peux l'ajouter avec une simple extension ? Cela n'existe pas, mais l'écrire moi-même devrait être facile, non ?

C'est ce que je pensais il y a quelques jours. Même si je n'avais pas complètement erreur, certaines parties du processus de développement ont pris un peu plus de temps que prévu. Je ne dirai pas difficile, mais plutôt difficile à comprendre à l'aide de la documentation disponible. Bien que la documentation de l'API, les concepts de base, etc. soient assez bien décrits sur Developer.chrome.com, je souhaitais une expérience de développeur spécifique :

• TypeScript avec saisie appropriée de l'espace de noms Chrome
• Diviser le code en plusieurs fichiers et importer/exporter ce qui était nécessaire
• Débogage de mon code avec un simple console.log et/ou un débogueur
• Autocomplétion dans mon manifest.json
• Configuration simple, sans aucun bundler et la moitié d'Internet dans mes node_modules
• Un moyen simple de mettre à jour et de tester l'extension dans le navigateur

De manière meilleure ou pire, j'ai réussi à mettre les choses en place comme je le souhaitais. Dans cet article, je vais expliquer brièvement les concepts généraux des extensions et vous montrer comment j'ai configuré mon environnement de développement. Dans un ou deux prochains articles, je me concentrerai sur les détails de mise en œuvre de ma simple extension page-audio.

TLDR :
Si vous voulez juste le code, voici le dépôt passe-partout :

Vaudou / chrome-extension-passe-partout

Plaque passe-partout d'extension Chrome

Ce référentiel vise à être un point de départ pour développer une extension Chrome.

C'est aussi minimaliste que possible, mais est livré avec préconfiguré :

• complétion automatique pour manifest.json
• Transpilation TypeScript du dossier ts vers le répertoire dist
• types pour l'espace de noms Chrome
• l'exportation et l'importation fonctionnent correctement (avec le paramètre d'espace de travail VS Code pour un format d'importation automatique correct)
• exemple manifest.json

Bon codage !

Voir sur GitHub

ℹ️ J'utilise Windows 11, MS Edge, VS Code et npm partout ci-dessous ℹ️

---

Brève introduction aux extensions

Commençons par un cours intensif sur les concepts généraux d'extension.

Chaque extension possède un fichier manifest.json qui définit son nom, sa version, les autorisations requises et les fichiers utilisés. Les extensions peuvent fournir des fonctionnalités de plusieurs manières différentes :

• via popup - la popup d'extension est cette petite fenêtre qui s'ouvre lorsque vous cliquez sur l'icône d'extension dans la barre d'extension,
• via des scripts de contenu - des scripts injectés directement dans les sites Web et ayant un accès au DOM,
• via des scripts d'arrière-plan (service worker) - les scripts s'exécutent dans un contexte distinct, indépendant des sites Web ouverts

Il existe d'autres moyens, mais je m'en tiendrai à ces trois-là dans ce guide.

Un autre concept important est la messagerie. Habituellement, nous devons combiner les méthodes ci-dessus, car elles ont toutes des limites différentes. Par exemple, les scripts en arrière-plan ne dépendent pas des onglets ouverts et peuvent être plus utiles pour un état persistant, mais ne peuvent accéder au DOM d'aucun site Web. Par conséquent, nous devrons peut-être obtenir des données à l'échelle de l'extension à partir du script d'arrière-plan, les transmettre à l'aide d'un message à un script de contenu et modifier le site Web à partir de là.

Il peut également être utile de comprendre quelques notions de base sur les autorisations. En bref, certaines API ne fonctionneront pas comme prévu si manifest.json ne spécifie pas les autorisations correctes. Par exemple, si nous ne spécifions pas l'autorisation « onglets », les objets renvoyés par l'API des onglets n'auront pas de champ URL. D'un autre côté, nous ne devrions pas demander trop d'autorisations : si l'extension doit être publique, les utilisateurs pourraient craindre de donner accès à trop de choses.

---

Créer une extension simple

Inspiré par https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world

Commençons par comprendre les concepts fondamentaux de notre flux de travail de développement à l'aide d'une extension extrêmement simple qui affiche simplement du texte dans une fenêtre contextuelle.

Fichiers

Tout d'abord, nous avons besoin d'un fichier manifest.json :

// manifest.json
{
  "name": "Hello World",
  "description": "Shows Hello World text",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_popup": "hello.html",
    "default_icon": "icon.png"
  }
}

name, description, version et manifest_version sont probablement explicites. action.default_popup est un chemin vers un fichier HTML qui sera rendu en cliquant sur l'icône d'extension. default_icon est un chemin vers l'icône d'extension. Les deux chemins sont relatifs à l’emplacement manifest.json.

Maintenant, ajoutez les fichiers icon.png (par exemple, celui-ci) et hello.html dans le même répertoire que manifest.json.
hello.html peut ressembler à ça :

<!-- hello.html -->
<p>Hello world</p>

Et tout votre répertoire devrait ressembler à ça :

// manifest.json
{
  "name": "Hello World",
  "description": "Shows Hello World text",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_popup": "hello.html",
    "default_icon": "icon.png"
  }
}

Activation de l'extension

Pour activer votre extension :

1. Allez sur edge://extensions/
2. Dans la barre latérale gauche, activez le « Mode développeur »
   • "Autoriser les extensions d'autres magasins" peut également être nécessaire
3. Au-dessus de la liste des extensions, cliquez sur "Charger décompressé"
4. Sélectionnez le dossier contenant vos fichiers d'extension
5. Votre extension doit apparaître dans la liste et son icône dans la barre d'outils des extensions ?

Maintenant, après avoir cliqué sur l'icône, une petite fenêtre contextuelle s'affichera avec le texte "Bonjour tout le monde".

Cela couvre les bases les plus importantes. Passons à quelque chose de plus intéressant.

---

Configuration de l'environnement d'extension Page-Audio

Saisie semi-automatique dans manifest.json

On recommence avec le manifest.json et le répertoire vide.

Ce serait génial d'avoir la saisie semi-automatique lors de l'écriture du fichier manifest.json, n'est-ce pas ? Heureusement, il s'agit d'une norme bien définie et possède un schéma JSON sur https://json.schemastore.org/chrome-manifest. Nous en avons juste besoin sous la clé "$schema" au début de manifest.json :

<!-- hello.html -->
<p>Hello world</p>

et VS Code commence instantanément à nous aider en suggérant des noms de champs et en affichant des avertissements si des champs obligatoires sont manquants. Génial !?

Pour que quelque chose fonctionne pour tester notre configuration, utilisez manifest.json en regardant de cette façon :

.
├── hello.html
├── icon.png
└── manifest.json

• icônes - c'est juste une façon différente de spécifier les icônes d'extension
• section d'arrière-plan - spécifie le chemin avec le fichier JS du service worker et son type ; c'est un module car le code utilisera l'exportation et l'importation plus tard

Manuscrit

Utiliser TypeScript... eh bien, nécessite TypeScript. Si vous ne l'avez pas installé, commencez par

// manifest.json
{
    "$schema": "https://json.schemastore.org/chrome-manifest"
}

Configuration de base

Pour organiser les choses, mais pas trop compliqué, je vais conserver les fichiers sources .ts dans le répertoire ts. Ils seront extraits de là par le transpilateur et placés dans le répertoire dist sous forme de fichiers .js.

Ceci est décrit par le .tsconfig suivant :

// manifest.json
{
    "$schema": "https://json.schemastore.org/chrome-manifest",
    "name": "Page Audio",
    "version": "0.0.0.1",
    "manifest_version": 3,
    "icons": {
        "16": "icons/logo16x16.png",
        "32": "icons/logo32x32.png",
        "48": "icons/logo48x48.png",
        "128": "icons/logo128x128.png"
    },
    "background": {
        "service_worker": "dist/background.js",
        "type": "module"
    }
}

Les éléments les plus importants sont compiler.rootDir et compiler.outDir. Les autres champs peuvent avoir des valeurs différentes ou être complètement supprimés (au moins certains d'entre eux).

C'est la configuration de base - placer certains fichiers dans le répertoire ts et exécuter tsc dans le répertoire racine créera un fichier .js correspondant dans dist. Cependant, il nous manque une partie importante : les types pour l'espace de noms Chrome que nous utiliserons. La solution la plus simple est de les ajouter via npm.

Ajout de types de chrome

Créez un package.json vide, juste avec les parenthèses :

// manifest.json
{
  "name": "Hello World",
  "description": "Shows Hello World text",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_popup": "hello.html",
    "default_icon": "icon.png"
  }
}

et dans la ligne de commande, exécutez :

<!-- hello.html -->
<p>Hello world</p>

Vous pouvez également ajouter des scripts pour exécuter tsc build et en mode montre. Le package.json final devrait ressembler à ceci :

.
├── hello.html
├── icon.png
└── manifest.json

ℹ️ La version des types Chrome pourrait être plus élevée dans votre cas. ℹ️

Après avoir ajouté les types, nous devons en informer TypeScript. Pour ce faire, mettez simplement à jour .tsconfig.json :

// manifest.json
{
    "$schema": "https://json.schemastore.org/chrome-manifest"
}

Pour tester si notre configuration fonctionne correctement :

1. Dans le dossier ts, créez le fichier background.ts avec le contenu suivant
   

   // manifest.json
   {
       "$schema": "https://json.schemastore.org/chrome-manifest",
       "name": "Page Audio",
       "version": "0.0.0.1",
       "manifest_version": 3,
       "icons": {
           "16": "icons/logo16x16.png",
           "32": "icons/logo32x32.png",
           "48": "icons/logo48x48.png",
           "128": "icons/logo128x128.png"
       },
       "background": {
           "service_worker": "dist/background.js",
           "type": "module"
       }
   }
   
   

2. Dans la ligne de commande, exécutez
   

   npm install -g typescript
   

3. Vérifiez si le répertoire dist a été créé et si le fichier background.js y est apparu

4. Modifiez quelque chose dans la chaîne console.log dans le fichier ts/background.ts et enregistrez-le

5. Vérifiez s'il a automatiquement mis à jour dist/background.js.

Si ça marche, génial ! Nous avons presque tout mis en place ?

Vous pouvez également vérifier si votre structure de répertoires ressemble à celle-ci :

// .tsconfig
{
    "compilerOptions": {
        "target": "ES6",
        "module": "ES6",
        "outDir": "./dist",
        "rootDir": "./ts",
        "strict": true,
    }
}

importer et exporter

Comme je l'ai mentionné, j'aimerais diviser le code en fichiers plus petits. Pour ce faire, l'exportation et l'importation doivent fonctionner correctement.

Une étape dans cette direction consistait à spécifier notre service_worker dans manifest.json comme "type": "module". Cependant, il existe une différence entre TypeScript et JavaScript lorsque vous travaillez avec des modules : alors que TypeScript n'a pas besoin d'extensions de fichier lors de l'importation, JavaScript en a besoin. Ainsi, par exemple, cette importation :

// package.json
{
}

fonctionnera dans TS, mais JS a besoin

npm i -D chrome-types

Il est également important de comprendre que le transpilateur TS ne fait rien sur les chemins d'importation. Et c'est assez "intelligent" pour comprendre que lors de l'importation depuis file.js, il doit également rechercher file.ts.

En combinant tout cela, TS sera également satisfait de l'importation de style JS et utilisera le fichier TS correspondant lors de l'importation à partir de file.js. Ce que nous devons faire est de nous assurer que toutes les importations dans les fichiers TS ont une extension .js. Pour l'automatiser dans VS Code :

1. Appuyez sur CTRL pour ouvrir les paramètres
2. Passer à l'onglet "Espace de travail"
3. Recherchez typescript.preferences.importModuleSpecifierEnding
4. Réglez-le sur l'option ".js / .ts"

Maintenant, chaque fois que vous importez automatiquement à l'aide de VS Code, il ajoutera .js au nom de fichier ?

Pour tester si tout fonctionne correctement :

1. Créez un fichier ts/hello.ts avec le contenu suivant
   

   // package.json
   {
       "scripts": {
           "build": "tsc",
           "watch": "tsc -w"
       },
       "devDependencies": {
           "chrome-types": "^0.1.327"
       }
   }
   

2. Dans ts/background.ts, supprimez la ligne console.log actuelle et commencez à taper "hello"

3. VS Code devrait le compléter automatiquement et ajouter l'importation correcte après avoir accepté la suggestion avec Tab

4. Au final, le fichier devrait ressembler à ceci :
   

   // manifest.json
   {
     "name": "Hello World",
     "description": "Shows Hello World text",
     "version": "1.0",
     "manifest_version": 3,
     "action": {
       "default_popup": "hello.html",
       "default_icon": "icon.png"
     }
   }
   

Notez que l'importation se termine par l'extension .js. Si vous vérifiez dist/background.js, l'extension est également là et c'est ce qui fait que tout fonctionne correctement.

Pour être sûr que nous sommes au même stade, vous pouvez comparer la structure des répertoires :

<!-- hello.html -->
<p>Hello world</p>

Outils de développement pour les techniciens de service

D'accord, nous avons une expérience de développement décente. Nous avons également ajouté quelques appels console.log... mais où les trouver maintenant ?

Si vous ajoutez console.log dans un script de contenu, vous pouvez simplement ouvrir les outils de développement et ils seront là, car les scripts de contenu fonctionnent dans le même contexte que la page dans laquelle ils sont injectés. Cependant, les console.logs des scripts d'arrière-plan sont un peu plus masqués.

1. Ouvrez edge://extensions/ et chargez votre extension si vous ne l'avez pas encore fait
2. Trouvez votre extension dans la liste

3. Cliquez sur le lien « Service Worker » dans la ligne « Inspecter les vues » :

   

4. Une nouvelle fenêtre Outils de développement devrait s'ouvrir et vous y verrez les journaux du technicien de service

   • Si vous ne voyez pas les journaux, cliquez sur « Recharger » sous « Inspecter les vues »

Les trois liens en bas de la tuile sont également très importants

• "Reload" - actualise l'intégralité de l'extension, y compris les modifications apportées à manifest.json ; consultez ce tableau pour comprendre quand un rechargement pourrait être nécessaire
• "Supprimer" - supprime l'extension
• "Détails" - affiche plus d'informations sur l'extension, par exemple ses autorisations
• (facultatif) "Erreurs" - s'il y a des erreurs lors de l'installation du service worker, ce lien apparaîtra et vous amènera à la liste des erreurs

Ouf. Cela a pris un moment, mais, finalement, notre environnement est bien configuré. Désormais, il suffira de

1. Exécutez npm run watch (si vous l'avez arrêté)
2. Écrivez notre code dans le répertoire ts
3. (Facultatif) Rechargez l'extension depuis l'onglet Extensions

Et notre extension sera automatiquement mise à jour ! ⚙️

Si vous avez une idée sur la façon de "Recharger" automatiquement (sans piratage élaboré), faites-le-moi savoir dans les commentaires

Résumé

Nous avons notre environnement prêt !

• La saisie semi-automatique fonctionne dans manifest.json, nous n'avons donc pas à deviner quelles sont les valeurs correctes
• TypeScript nous aide à utiliser correctement l'API Chrome
• Le code peut être divisé en fichiers logiques plus petits
• Le code que nous écrivons dans le dossier ts est mis à jour automatiquement
• Nous savons où trouver les outils de développement pour le service worker et les scripts de contenu

Dans la partie suivante, je décrirai les détails d'implémentation de ma petite extension "Page audio".

Merci d'avoir lu !

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!