Anatomie d'une WebExtension

Cette traduction est incomplète. Aidez à traduire cet article depuis l'anglais.

Une WebExtension 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 WebExtension.

Chaque WebExtension doit contenir un fichier appelé "manifest.json". Ce manifeste peut contenir des pointeurs vers plusieurs autres types de fichiers :

  • Background pages: Implémentez une logique longue durée.
  • Content scripts: Intéragissez avec les pages Web (Notez que ce n'est pas le même que javaScript dans un élément <script> au sein d'une page).
  • Browser action files: Ajoutez des boutons dans la barre d'outils.
  • Page action files: Ajoutez des boutons à la barre d'adresse
  • Options pages: Définissez une interface utilisateur pour qu'ils puissent afficher et modifier les paramètres de votre extension.
  • Web-accessible resources: Rendez le contenu packagé accessible aux pages Web et aux scripts de contenu.

manifest.json

Il s'agit du seul fichier qui doit être présent dans chaque WebExtension. 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.

Voir la page référence manifest.json pour tous les détails.

Background scripts

Les WebExtensions 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 ce que les scripts d'arrière-plan font.

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 WebExtension APIs dans le script, tant que vous avez demandé les permissions nécessaires.

Specifying background scripts

Vous pouvez inclure un script d'arrière-plan à l'aide de la clé de fond dans "manifest.json":

// manifest.json

"background": {
  "scripts": ["background-script.js"]
}

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.

Background script environment

DOM APIs

Les scripts d'arrière-plan se lancent dans le contexte de pages spéciales appelées pages d'arrière-plan. Cela leur donne une window globale, avec toutes les API DOM standard qui fournit.

Vous n'avez pas à fournir votre page d'arrière-plan. Si vous incluez un script en arrière-plan, une page d'arrière-plan vide sera créée pour vous.

Toutefois, vous pouvez choisir de fournir votre page d'arrière-plan en tant que fichier HTML distinct:

// manifest.json

"background": {
  "page": "background-page.html"
}

WebExtension APIs

Les scripts d'arrière-plan peuvent utiliser l'une des APIs des WebExtensions dans le script, à condition que leur extension dispose des permissions nécessaires.

Cross-origin access

Les scripts d'arrière-plan peuvent faire des requêtes XHR à tous les hôtes pour lesquels ils ont des permissions d'hôte.

Actions du navigateur

Si votre extension définit une action du navigateur et que l'action du navigateur n'a pas de fenêtre contextuelle, vous pouvez écouter les événements de clic sur le bouton de l'action du navigateur en utilisant l'objet onClicked :

browser.browserAction.onClicked.addListener(handleClick);

Contenu Web

Les scripts d'arrière-plan n'obtiennent pas un accès direct aux pages Web. Toutefois,  ils peuvent charger des scripts de contenu dans les pages Web et peuvent communiquer avec ces scripts de contenu à l'aide d'une API de communication.

Politique de sécurité du contenu

Les scripts d'arrière-plan sont limités à certaines opérations potentiellement dangereuses, comme l'utilisation de eval(), par le biais d'une politique de sécurité du contenu. Pour plus de détails, consultez la politique de sécurité du contenu.

Scripts de contenu

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.

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 <script> dans la page.

Les scripts de contenu peuvent voir et manipuler le DOM de la page, tout comme les scripts normaux chargés par la page.

Contrairement aux scripts de pages normales, ils peuvent :

  • Effectuez des requêtes XHR entre domaines.
  • Utilisez un petit sous-ensemble de l'APIs des WebExtensions.
  • Échangez des messages avec leurs scripts d'arrière-plan et peuvent ainsi accéder indirectement à toutes les API des WebExtensions.

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 window.postMessage().

Usually, when we talk about content scripts, we are referring to JavaScript, but you can inject CSS into web pages using the same mechanism.

See the content scripts article to learn more.

Browser actions

A browser action is a button you can add to the browser toolbar. Users can click the button to interact with your extension.

You can optionally define a popup for the button using HTML, CSS, and JavaScript.

If you do not define a popup, then when the user clicks the button, an event is dispatched to the extension, which you can listen for using browserAction.onClicked:

browser.browserAction.onClicked.addListener(handleClick);

If you do define a popup, the click event is not dispatched: instead, the popup will be shown when the user clicks the button. The user will be able to interact with the popup and it will close automatically when the user clicks outside it.

Learn more about browser actions.

Page actions

Page actions are like browser actions in most respects, except that:

  • Browser actions are displayed all the time and are for actions that are applicable more or less all the time.
  • Page actions are for actions which only make sense on certain pages and are only displayed when those tabs are active.

To emphasise that page actions are closely tied to particular pages, they are shown in the address bar, rather than the main toolbar:

Learn more about page actions.

Options pages

Options pages enable you to define preferences for your WebExtension that your users can change. Users can access the options page for an add-on from the browser's add-ons manager:

The way users access the page, and the way it is integrated into the browser's user interface, will vary from one browser to another.

Learn more about options pages.

Web accessible resources

Web accessible resources are resources such as images, HTML, CSS, and JavaScript that you include in the extension and want to make accessible to content scripts and page scripts. Resources which are made web-accessible can be referenced by page scripts and content scripts using a special URI scheme.

For example, if a content script wants to insert some images into web pages, you could include them in the extension and make them web accessible. Then the content script could create and append img tags which reference the images via the src attribute.

 

 

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : faridmes, hellosct1
 Dernière mise à jour par : faridmes,