diff options
Diffstat (limited to 'files/fr/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.md')
| -rw-r--r-- | files/fr/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.md | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/files/fr/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.md b/files/fr/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.md new file mode 100644 index 0000000000..c731203edf --- /dev/null +++ b/files/fr/mozilla/add-ons/webextensions/anatomy_of_a_webextension/index.md @@ -0,0 +1,146 @@ +--- +title: Anatomie d'une WebExtension +slug: Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension +tags: + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension +--- +<div>{{AddonSidebar}}</div> + +<p>Une extension se compose de plusieurs fichiers, packagés pour la distribution et l'installation. Dans cet article, nous allons rapidement passer par les fichiers qui pourraient être présents dans une extension.</p> + +<h2 id="manifest.json">manifest.json</h2> + +<p>Il s'agit du seul fichier qui doit être présent dans chaque extension. Il contient des métadonnées de base sur l'extension telles que son nom, sa version et les autorisations requises. Il fournit également des pointeurs vers d'autres fichiers dans l'extension.</p> + +<p>Ce manifeste peut également contenir des pointeurs vers plusieurs autres types de fichiers :</p> + +<ul> + <li><a href="/fr/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Background_scripts">page d'arrière-plan </a>: implémentez une logique à longue durée.</li> + <li>Icônes pour l'extension et tous les boutons qu'elle peut définir.</li> + <li><a href="/fr/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Sidebars_popups_options_pages">Sidebars, popups, et options pages</a>: Documents HTML qui fournissent du contenu pour divers composants de l'interface utilisateur.</li> + <li><a href="/fr/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Content_scripts">Script de contenu</a> : interagissez avec les pages Web (Notez que ce n'est pas le même que javaScript dans un élément {{HTMLElement("script")}} au sein d'une page).</li> + <li><a href="/fr/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#Web_accessible_resources">Web-accessible resources</a> : Rendez le contenu packagé accessible aux pages Web et aux scripts de contenu.</li> +</ul> + +<p><img alt="" src="webextension-anatomy.png"></p> + +<p>Voir la page référence <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json">manifest.json</a> pour tous les détails.</p> + +<p>En plus de celles déjà listées dans le manifeste, une extension peut également inclure des pages d'extensions supplémentaires et des fichiers de support.</p> + +<h2 id="Scripts_darrière-plan">Scripts d'arrière-plan</h2> + +<p>Les extensions doivent souvent conserver un état à long terme ou effectuer des opérations à long terme indépendamment de la durée de vie d'une page Web ou d'une fenêtre de navigateur. C'est le rôle des scripts d'arrière-plan.</p> + +<p>Les scripts en arrière-plan sont chargés dès que l'extension est chargée et restent chargés jusqu'à ce que l'extension soit désactivée ou désinstallée. Vous pouvez utiliser n'importe laquelle des <a href="/fr/Add-ons/WebExtensions/API">WebExtension APIs</a> dans le script, tant que vous avez demandé les <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a> nécessaires.</p> + +<h3 id="Spécifier_les_scripts_darrière-plan">Spécifier les scripts d'arrière-plan</h3> + +<p>Vous pouvez inclure un script d'arrière-plan à l'aide de la clé <code>background</code> dans "manifest.json" :</p> + +<pre class="brush: json">// manifest.json + +"background": { + "scripts": ["background-script.js"] +}</pre> + +<p>Vous pouvez spécifier plusieurs scripts en arrière-plan : si vous le faites, ils s'exécutent dans le même contexte, tout comme plusieurs scripts chargés dans une seule page Web.</p> + +<p>Au lieu de spécifier des scripts d'arrière-plan, vous pouvez spécifier une page d'arrière-plan qui a l'avantage supplémentaire de supporter les modules ES6 :</p> + +<p><strong>manifest.json</strong></p> + +<pre class="brush: json">// manifest.json + +"background": { + "page": "background-page.html" +}</pre> + +<p><strong>background-page.html</strong></p> + +<pre class="brush: html"><!DOCTYPE html> +<html lang="en"> + <head> + <meta charset="utf-8"> + <script type="module" src="background-script.js"></script> + </head> +</html></pre> + +<h3 id="Environnement_des_scripts_darrière-plan">Environnement des scripts d'arrière-plan</h3> + +<h4 id="APIs_DOM">APIs DOM</h4> + +<p>Les scripts d'arrière-plan s'exécutent dans le contexte de pages spéciales appelées pages d'arrière-plan. Cela leur donne une <code><a href="/fr/docs/Web/API/Window">fenêtre</a></code> globale, ainsi que toutes les API DOM standard fournies par cet objet.</p> + +<div class="warning"> +<p><strong>Attention :</strong> Dans Firefox, les pages d'arrière-plan ne supportent pas l'utilisation de <code><a href="/fr/docs/Web/API/Window/alert">alert()</a></code>, <code><a href="/fr/docs/Web/API/Window/confirm">confirm()</a></code>, ou <code><a href="/fr/docs/Web/API/Window/prompt">prompt()</a></code>.</p> +</div> + +<h4 id="APIs_des_WebExtensions">APIs des WebExtensions</h4> + +<p>Les scripts d'arrière-plan peuvent utiliser l'une des <a href="/fr/Add-ons/WebExtensions/API">APIs des WebExtensions</a> dans le script, à condition que leur extension dispose des <a href="/fr-FR/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions</a> nécessaires.</p> + +<h4 id="Cross-origin_access">Cross-origin access</h4> + +<p>Les scripts d'arrière-plan peuvent faire des requêtes XHR à tous les hôtes pour lesquels ils ont des <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions">permissions d'hôte</a>.</p> + +<h4 id="Contenu_Web">Contenu Web</h4> + +<p>Les scripts d'arrière-plan n'obtiennent pas un accès direct aux pages Web. Toutefois, ils peuvent charger des <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">scripts de contenu</a> dans les pages Web et peuvent <a href="/fr/Add-ons/WebExtensions/Content_scripts#Communicating_with_background_scripts">communiquer avec ces scripts de contenu à l'aide d'une API de communication</a>.</p> + +<h4 id="Politique_de_sécurité_du_contenu">Politique de sécurité du contenu</h4> + +<p>Les scripts d'arrière-plan sont restreints à certaines opérations pour lutter contre d'autres potentiellement dangereuses, comme l'utilisation de la fonction <code><a href="/fr/docs/Web/JavaScript/Reference/Global_Objects/eval">eval()</a></code>, par le biais d'une politique de sécurité du contenu. Pour plus de détails, consultez la <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy">politique de sécurité du contenu</a>.</p> + +<h2 id="Sidebars_popups_pages_options">Sidebars, popups, pages options</h2> + +<p>Votre extension peut inclure divers composants d'interface utilisateur dont le contenu est défini à l'aide d'un document HTML :</p> + +<ul> + <li>Une <a href="/fr/Add-ons/WebExtensions/user_interface/Sidebars">barre latérale</a> est un volet qui s'affiche dans la partie gauche de la fenêtre du navigateur, à côté de la page Web.</li> + <li>Un <a href="/fr/Add-ons/WebExtensions/user_interface/Popups">popup</a> est une boîte de dialogue que vous pouvez afficher lorsque l'utilisateur clique sur un <a href="/fr/Add-ons/WebExtensions/user_interface/Browser_action">bouton de la barre d'outils</a> ou de la <a href="/fr/Add-ons/WebExtensions/user_interface/Page_actions">barre d'adresse</a></li> + <li>Une <a href="/fr/Add-ons/WebExtensions/user_interface/Options_pages">page d'options</a> est une page qui s'affiche lorsque l'utilisateur accède aux préférences de votre module complémentaire dans le gestionnaire d'add-ons natif du navigateur.</li> +</ul> + +<p>Pour chacun de ces composants, vous créez un fichier HTML et pointez vers lui en utilisant une propriété spécifique dans <a href="/fr/Add-ons/WebExtensions/manifest.json">manifest.json</a>. Le fichier HTML peut inclure des fichiers CSS et JavaScript, tout comme une page Web normale.</p> + +<p>Toutes ces pages sont un type de <a href="/fr/Add-ons/WebExtensions/user_interface/Extension_pages">pages d'extension</a>,et contrairement à une page Web normale, votre JavaScript peut utiliser les mêmes API d'extension Web privilégiées que votre script de fond. Ils peuvent même accéder directement aux variables de la page d'arrière-plan en utilisant {{WebExtAPIRef("runtime.getBackgroundPage()")}}.</p> + +<h2 id="Page_dextension">Page d'extension</h2> + +<p>Vous pouvez également inclure dans votre extension des documents HTML qui ne sont pas attachés à un composant d'interface utilisateur prédéfini. Contrairement aux documents que vous pouvez fournir pour les sidebars, les popups ou les pages d'options, ceux-ci n'ont pas d'entrée dans manifest.json. Cependant, ils ont également accès aux mêmes API WebExtension privilégiées que votre script d'arrière-plan.</p> + +<p>Vous chargerez typiquement une page comme celle-ci en utilisant {{WebExtAPIRef("windows.create()")}} ou {{WebExtAPIRef("tabs.create()")}}.</p> + +<p>Voir les <a href="/fr/Add-ons/WebExtensions/user_interface/Extension_pages">pages d'extension</a> pour en savoir plus.</p> + +<h2 id="Scripts_de_contenu">Scripts de contenu</h2> + +<p>Utilisez les scripts de contenu pour accéder et manipuler des pages Web. Les scripts de contenu sont chargés dans des pages Web et lancés dans le contexte de cette page particulière.</p> + +<p>Les scripts de contenu sont des scripts fournis par les extensions qui s'exécutent dans le contexte d'une page Web ; cela diffère des scripts qui sont chargés par la page elle-même, y compris ceux qui sont fournis dans les éléments {{HTMLElement ("script")}} dans la page.</p> + +<p>Les scripts de contenu peuvent voir et manipuler le DOM de la page, tout comme les scripts normaux chargés par la page.</p> + +<p>Contrairement aux scripts de pages normales, ils peuvent :</p> + +<ul> + <li>Effectuer des requêtes XHR entre domaines.</li> + <li>Utiliser un petit sous-ensemble de l'<a href="/fr/docs/Mozilla/Add-ons/WebExtensions/API">APIs des WebExtensions</a>.</li> + <li><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#Communication_avec_les_scripts_darrière-plan">Echanger des messages avec leurs scripts d'arrière-plan</a> et peuvent ainsi accéder indirectement à toutes les API des WebExtensions.</li> +</ul> + +<p>Les scripts de contenu ne peuvent pas directement accéder normalement aux scripts de page, mais peuvent échanger des messages avec eux à l'aide de l'API standard <code><a href="/fr-FR/docs/Web/API/Window/postMessage">window.postMessage()</a></code>.</p> + +<p>Habituellement, quand nous parlons de scripts de contenu, nous parlons de JavaScript, mais vous pouvez injecter du CSS dans des pages Web en utilisant le même mécanisme.</p> + +<p>Voir l'article de <a href="/fr-FR/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">scripts de contenu</a> pour en savoir plus.</p> + +<h2 id="Rendre_accessible_des_ressources_web">Rendre accessible des ressources web</h2> + +<p>Les ressources web sont des fichiers tels que des images, des fichiers HTML, CSS ou JavaScript qui sont inclus dans l'extension afin d'être utilisés par les scripts de contenu et les scripts d'arrière-plan. Les ressources web mises à disposition peuvent être référencées depuis les scripts grâce à un schéma d'URI spécifique.</p> + +<p>Ainsi, si un script de contenu souhaite insérer des images sur une page web, on pourra insérer ces images dans l'extension et les rendre accessible. Ensuite, le script de contenu pourra créer et ajouter une balise {{HTMLElement("img")}} faisant référence à l'image via l'attribut <code>src</code> ciblant le fichier via le schéma spécifique.</p> + +<p>Pour en savoir plus, se référer à la documentation de la clé <code><a href="/fr/docs/Mozilla/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a></code> du fichier <code>manifest.json</code>.</p> |