menus
=====

Ajoutez des éléments au système de menus du navigateur.

Cette API est modélisée dans l'API "contextMenus" de Chrome, qui permet aux extensions Chrome d'ajouter des éléments au menu contextuel du navigateur. L'API `browser.menus` ajoute quelques fonctionnalités à l'API de Chrome.

Avant Firefox 55, cette API s'appelait à l'origine `contextMenus`, et ce nom a été retenu comme alias. Vous pouvez donc utiliser `contextMenus` pour écrire du code qui fonctionne dans Firefox et dans d'autres navigateurs.

Pour utiliser cette API, vous devez avoir la permission des `menus.` vous pouvez également utiliser l'alias `contextMenus` à la place des `menus`, mais si vous le faites, vous devez accéder aux API sous le nom `browser.contextMenus` à la place.

Excepté que `menus.getTargetElement()`, cette API ne peut pas être utilisée à partir de scripts de contenu.

Créer des éléments de menu
--------------------------

Pour créer un élément de menu, appelez la méthode `menus.create()`. Vous transmettez à cette méthode un objet contenant des options pour l'élément, y compris l'ID d'élément, le type d'élément et les contextes dans lesquels il doit être affiché.

Écoutez les clics sur votre élément de menu en ajoutant un écouteur à l'événement `menus.onClicked`. Cet écouteur recevra un objet `menus.OnClickData` contenant les détails de l'événement.

Vous pouvez créer quatre types différents d'élément de menu, en fonction de la valeur de la propriété `type` que vous fournissez dans les options de `create()`:

* "normal": un élément de menu qui affiche simplement une étiquette
* "checkbox": un élément de menu qui représente un état binaire. Il affiche une coche à côté de l'étiquette. Cliquez sur l'élément pour activer la case. L'écouteur de clic recevra deux propriétés supplémentaires : "checked",indiquant si l'élément est vérifié maintenant, et "wasChecked", indiquant si l'élément a été vérifié avant l'événement click.
* "radio": un élément de menu qui représente l'un des groupes de choix. Tout comme une case à cocher, cela affiche également une coche à côté de l'étiquette, et son écouteur de clic est passé "checked" et "wasChecked". Cependant, si vous créez plus d'un élément radio, les éléments fonctionnent comme un groupe d'éléments radio: un seul élément du groupe peut être vérifié, et cliquer sur un élément en fait l'élément sélectionné.
* "separateur": une ligne séparant un groupe d'éléments.

Si vous avez créé plus d'un élément de menu contextuel ou plus d'un élément de menu d'outils, les éléments seront placés dans un sous-menu. Le parent du sous-menu sera étiqueté avec le nom de l'extension. Par exemple, voici une extension appelée "Menu démo" qui ajoute deux éléments de menu contextuel:

![](/fr/docs/Mozilla/Add-ons/WebExtensions/API/menus/menus-1.png)

Icônes
------

Si vous avez spécifié des icônes pour votre extension à l'aide de la clé de manifest "icons", votre élément de menu affichera l'icône spécifiée à côté de son libellé. Le navigateur va essayer de choisir une icône de 16x16 pixels pour un affichage normal ou une icône de 32x32 pixels pour un affichage haute définition :

![](/fr/docs/Mozilla/Add-ons/WebExtensions/API/menus/menus-2.png)

Uniquement pour les éléments d'un sous-menu, vous pouvez spécifier des icônes personnalisées en passant l'option `icons` à `menus.create()` :

![](/fr/docs/Mozilla/Add-ons/WebExtensions/API/menus/menus-3.png)

Exemple
-------

Voici un menu contextuel contenant 4 éléments: un élément normal, deux éléments radio avec des séparateurs de chaque côté et une case à cocher. Les éléments radio sont dotés d'icônes personnalisées.

![](/fr/docs/Mozilla/Add-ons/WebExtensions/API/menus/menus-4.png)Vous pouvez créer un sous-menu comme celui-ci en utilisant du code comme :


```js
browser.menus.create(
  {
    id: "remove-me",
    title: browser.i18n.getMessage("menuItemRemoveMe"),
    contexts: ["all"],
  },
  onCreated,
);

browser.menus.create(
  {
    id: "separator-1",
    type: "separator",
    contexts: ["all"],
  },
  onCreated,
);

browser.menus.create(
  {
    id: "greenify",
    type: "radio",
    title: browser.i18n.getMessage("menuItemGreenify"),
    contexts: ["all"],
    checked: true,
    icons: {
      16: "icons/paint-green-16.png",
      32: "icons/paint-green-32.png",
    },
  },
  onCreated,
);

browser.menus.create(
  {
    id: "bluify",
    type: "radio",
    title: browser.i18n.getMessage("menuItemBluify"),
    contexts: ["all"],
    checked: false,
    icons: {
      16: "icons/paint-blue-16.png",
      32: "icons/paint-blue-32.png",
    },
  },
  onCreated,
);

browser.menus.create(
  {
    id: "separator-2",
    type: "separator",
    contexts: ["all"],
  },
  onCreated,
);

var checkedState = true;

browser.menus.create(
  {
    id: "check-uncheck",
    type: "checkbox",
    title: browser.i18n.getMessage("menuItemUncheckMe"),
    contexts: ["all"],
    checked: checkedState,
  },
  onCreated,
);
```

Types
-----

`menus.ContextType`

Les différents contextes dans lesquels un menu peut apparaître.

`menus.ItemType`

Le type d'élément de menu : "normal", "checkbox", "radio", "separator".

`menus.OnClickData`

Informations envoyées lorsqu'un élément de menu est cliqué.

Propriétés
----------

`menus.ACTION_MENU_TOP_LEVEL_LIMIT`

Le nombre maximal d'éléments d'extension de niveau supérieur pouvant être ajoutés à un élément de menu dont le type de contexte est "browser\_action" ou "page\_action".

Functions
---------

`menus.create()`

Crée un nouvel élément de menu.

`menus.getTargetElement()`

Retourne l'élément pour un `info.targetElementId` donné

`menus.overrideContext()`

Masquer tous les éléments de menu par défaut de Firefox en faveur d'une interface utilisateur de menu contextuel personnalisé.

`menus.refresh()`

Mettre à jour un menu actuellement affiché.

`menus.remove()`

Supprime un élément de menu.

`menus.removeAll()`

Supprime tous les éléments de menu ajoutés par cette extension.

`menus.update()`

Met à jour un élément de menu précédemment créé.

Evénements
----------

`menus.onClicked`

Lancé lorsqu'un élément de menu est cliqué.

`menus.onHidden`

Lancé lorsque le navigateur cache un menu.

`menus.onShown`

Lancé lorsque le navigateur affiche un menu.

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Example extensions
------------------

* menu-accesskey-visible
* menu-demo
* menu-labelled-open
* menu-remove-element
* menu-search
* session-state

**Note :**

Cette API est basée sur l'API `chrome.contextMenus` de chromium. Cette documentation est dérivée de `context_menus.json` dans le code Chromium.