path: root/files/fr/mozilla/add-ons/webextensions/api/menus/create/index.html

---
title: menus.create()
slug: Mozilla/Add-ons/WebExtensions/API/menus/create
tags:
  - API
  - Add-ons
  - Create
  - Extensions
  - Method
  - Non-standard
  - Reference
  - WebExtensions
  - contextMenus
translation_of: Mozilla/Add-ons/WebExtensions/API/menus/create
---
<div>{{AddonSidebar()}}</div>

<p>Crée un nouvel élément de menu, avec un objet d'options définissant les propriétés de l'élément.</p>

<p>Contrairement aux autres fonctions asynchrones, celle-ci ne renvoie pas de promesse, mais utilise un callback optionnel pour communiquer le succès ou l'échec. C'est parce que sa valeur de retour est l'ID du nouvel élément.</p>

<p>Pour la compatibilité avec d'autres navigateurs, Firefox rend cette méthode disponible via l'espace noms <code>contextMenus</code> ainsi que l'espace de noms des <code>menus</code>. Notez cependant qu'il n'est pas possible de créer des éléments de menu d'outils (<code>contexts: ["tools_menu"]</code>) en utilisant l'espace de noms <code>contextMenus</code>.</p>

<h2 id="Syntaxe">Syntaxe</h2>

<pre class="syntaxbox brush:js">browser.menus.create(
  createProperties, // object
  function() {...}  // optional function
)
</pre>

<h3 id="Paramètres">Paramètres</h3>

<dl>
 <dt><code>createProperties</code></dt>
 <dd><code>object</code>. Propriétés pour le nouvel élément de menu.</dd>
 <dd>
 <dl class="reference-values">
  <dt><code>checked</code> {{optional_inline}}</dt>
  <dd><code>boolean</code>. L'état initial d'une case à cocher ou d'un élément radio : <code>true</code> pour selected et <code>false</code> pour non sélectionné. Un seul élément radio peut être sélectionné à la fois dans un groupe donné d'éléments radio.</dd>
  <dt><code>command</code> {{optional_inline}}</dt>
  <dd>
  <p><code>string</code>. Chaîne décrivant une action à effectuer lorsque l'utilisateur clique sur l'élément. Les valeurs possibles sont:</p>

  <ul>
   <li><code>"_execute_browser_action"</code>: simule un clic sur l'action du navigateur de l'extension, en ouvrant son popup s'il en a un</li>
   <li><code>"_execute_page_action"</code>: simule un clic sur l'action de la page de l'extension, en ouvrant son popup s'il en a un</li>
   <li><code>"_execute_sidebar_action"</code>: ouvre la barre latérale de l'extension</li>
  </ul>

  <p>Cliquer sur l'élément déclenchera toujours l'événement {{WebExtAPIRef("menus.onClicked")}}, mais il n'y a aucune garantie de la commande ici: la commande peut être exécutée avant les incendies <code>onClicked</code>.</p>
  </dd>
  <dt><code>contexts</code> {{optional_inline}}</dt>
  <dd>
  <p><code>array</code> de <code>{{WebExtAPIRef('menus.ContextType')}}</code>. Tableau des contextes dans lesquels cet élément de menu apparaîtra. Si cette option est omise :</p>

  <ul>
   <li>Si l'élément parent a des contextes définis, alors cet élément héritera des contextes de ses parents</li>
   <li>sinon, l'élément reçoit un tableau de contexte de ["page"].</li>
  </ul>
  </dd>
  <dt><code>documentUrlPatterns</code> {{optional_inline}}</dt>
  <dd><code>array</code> de <code><code>string</code></code>. Vous permet de restreindre l'élément à appliquer uniquement aux documents dont l'URL correspond à l'un des <a href="/fr/Add-ons/WebExtensions/Match_patterns">motifs</a> données. Cela s'applique également aux cadres.</dd>
  <dt><code>enabled</code> {{optional_inline}}</dt>
  <dd><code>boolean</code>. Si cet élément de menu est activé ou désactivé. Par défaut à <code>true</code>.</dd>
  <dt><code>icons</code> {{optional_inline}}</dt>
  <dd>
  <p><code>object</code>. Une ou plusieurs icônes personnalisées à afficher en regard de l'élément. Les icônes personnalisées ne peuvent être définies que pour les éléments apparaissant dans les sous-menus. Cette propriété est un objet avec une propriété pour chaque icône fournie: le nom de la propriété est la taille de l'icône en pixels et sa valeur est un chemin vers l'icône à partir du répertoire racine de l'extension. 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 densité. Donc, pour éviter toute mise à l'échelle, vous pouvez spécifier des icônes comme ceci :</p>

  <pre class="brush: json no-line-numbers  language-json"><code class="language-json"><span class="key token">"icons":</span> <span class="punctuation token">{</span>
      <span class="key token">"16":</span> <span class="string token">"path/to/geo-16.png"</span><span class="punctuation token">,</span>
      <span class="key token">"32":</span> <span class="string token">"path/to/geo-32.png"</span>
    <span class="punctuation token">}</span></code></pre>

  <p>Vous pouvez également spécifier une seule icône SVG, qui sera mise à l'échelle de manière appropriée :</p>

  <pre class="brush: json no-line-numbers  language-json"><code class="language-json"><span class="key token">"icons":</span> <span class="punctuation token">{</span>
      <span class="key token">"16":</span> <span class="string token">"path/to/geo.svg"</span>
    <span class="punctuation token">}</span></code></pre>

  <div class="blockIndicator note">
  <p><strong>Note</strong>: L'élément de menu de niveau supérieur utilise les <a href="/fr/Add-ons/WebExtensions/manifest.json/icons">icônes</a> spécifiées dans le manifest plutôt que ce qui est spécifié avec cette touche.</p>
  </div>
  </dd>
  <dt><code>id</code> {{optional_inline}}</dt>
  <dd><code>string</code>. Identifiant unique à attribuer à cet élément Obligatoire pour les pages d'événement. Ne peut pas être identique à un autre ID pour cette extension.</dd>
  <dt><code>onclick</code> {{optional_inline}}</dt>
  <dd><code>function</code>. Une fonction qui sera appelée lorsque l'élément de menu est cliqué. Les pages d'événements ne peuvent pas utiliser ceci : à la place, elles devraient enregistrer un écouteur pour {{WebExtAPIRef('menus.onClicked')}}.</dd>
  <dt><code>parentId</code> {{optional_inline}}</dt>
  <dd><code><code>integer</code></code> ou <code><code>string</code></code>. L'ID d'un élément de menu parent; Cela fait de l'élément un enfant d'un élément ajouté précédemment. Remarque : Si vous avez créé plus d'un élément de menu, les éléments seront placés dans un sous-menu. Le parent du sous-menu sera étiqueté avec le nom de l'extension.</dd>
  <dt><code>targetUrlPatterns</code> {{optional_inline}}</dt>
  <dd><code>array</code> de <code><code>string</code></code>. Similaire à <code>documentUrlPatterns</code>, mais vous permet de filtrer en fonction du <code>href</code> des balises d'ancrage et de l'attribut <code>src</code> des balises img/audio/video tags. Ce paramètre prend en charge n'importe quel schéma d'URL, même ceux qui ne sont généralement pas autorisés dans un modèle de correspondance.</dd>
  <dt><code>title</code> {{optional_inline}}</dt>
  <dd>
  <p><code>string</code>. Le texte à afficher dans l'article. Obligatoire sauf si le <code>type</code> est "separator".</p>

  <p>Vous pouvez utiliser "<code>%s</code>" dans la chaîne. Si vous le faites dans un élément de menu et que du texte est sélectionné dans la page lorsque le menu est affiché, le texte sélectionné sera interpolé dans le titre. Par exemple, si le <code>titre</code> est "traduire '%s' en Pig Latin" et que l'utilisateur sélectionne le mot "cool", alors le menu est activé, le titre de l'élément de menu sera : "Traduire 'cool' en Pig Latin".</p>

  <p>Si le titre contient une esperluette "&amp;" le caractère suivant sera utilisé comme clé d'accès pour l'élément et l'esperluette ne sera pas affichée. Les exceptions à cette règle sont les suivantes :</p>

  <ul>
   <li>Si le caractère suivant est également une esperluette : alors une esperluette simple sera affichée et aucune clé d'accès ne sera définie. En effet, "&amp;&amp;" est utilisé pour afficher une seule esperluette.</li>
   <li>Si les caractères suivants sont la directive d'interpolation "%s" :  alors l'esperluette ne sera pas affichée et aucune clé d'accès ne sera définie.</li>
   <li>Si l'esperluette est le dernier caractère du titre : alors l'esperluette ne sera pas affichée et aucune clé d'accès ne sera définie.</li>
  </ul>

  <p>Seule la première esperluette sera utilisée pour définir une clé d'accès : les esperluettes suivantes ne seront pas affichées mais ne définiront pas les clés. Ainsi "&amp;A et &amp;B" seront affichés comme "A et B" et "A" comme clé d'accès.</p>
  </dd>
  <dt><code>type</code> {{optional_inline}}</dt>
  <dd><code>{{WebExtAPIRef('menus.ItemType')}}</code>. Le type d'élément de menu : "normal", "checkbox", "radio", "separator". Par défault à "normal".</dd>
  <dt><code>viewType</code> {{optional_inline}}</dt>
  <dd><code>{{WebExtAPIRef('extension.ViewType')}}</code>. Liste des types d'affichage où l'élément de menu sera affiché. Par défaut à n'importe quelle vue, y compris celles qui n'ont pas de <code>viewType</code>.</dd>
  <dt><code>visible</code> {{optional_inline}}</dt>
  <dd><code>boolean</code>. Si l'élément est affiché dans le menu. Par défaut, la valeur est <code>true</code>.</dd>
 </dl>
 </dd>
 <dt><code>callback</code> {{optional_inline}}</dt>
 <dd><code>function</code>. Appelé lorsque l'élément a été créé. S'il y a eu des problèmes lors de la création de l'élément, les détails seront disponibles dans {{WebExtAPIRef('runtime.lastError')}}.</dd>
</dl>

<h3 id="Valeur_retournée">Valeur retournée</h3>

<p><code><code>integer</code></code> ou <code><code>string</code></code>. L'ID de l'article nouvellement créé.</p>

<h2 id="Exemples">Exemples</h2>

<p>Cet exemple crée un élément de menu contextuel qui s'affiche lorsque l'utilisateur a sélectionné du texte dans la page. Il enregistre simplement le texte sélectionné sur la console</p>

<pre class="brush: js">browser.menus.create({
  id: "log-selection",
  title: "Log '%s' to the console",
  contexts: ["selection"]
});

browser.menus.onClicked.addListener(function(info, tab) {
  if (info.menuItemId == "log-selection") {
    console.log(info.selectionText);
  }
});</pre>

<p>Cet exemple ajoute deux éléments radio, que vous pouvez utiliser pour choisir d'appliquer une bordure verte ou bleue à la page. Notez que cet exemple nécessitera la <a href="/fr/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission">permission activeTab</a>.</p>

<pre class="brush: js">function onCreated() {
  if (browser.runtime.lastError) {
    console.log("error creating item:" + browser.runtime.lastError);
  } else {
    console.log("item created successfully");
  }
}

browser.menus.create({
  id: "radio-green",
  type: "radio",
  title: "Make it green",
  contexts: ["all"],
  checked: false
}, onCreated);

browser.menus.create({
  id: "radio-blue",
  type: "radio",
  title: "Make it blue",
  contexts: ["all"],
  checked: false
}, onCreated);

var makeItBlue = 'document.body.style.border = "5px solid blue"';
var makeItGreen = 'document.body.style.border = "5px solid green"';

browser.menus.onClicked.addListener(function(info, tab) {
  if (info.menuItemId == "radio-blue") {
    browser.tabs.executeScript(tab.id, {
      code: makeItBlue
    });
  } else if (info.menuItemId == "radio-green") {
    browser.tabs.executeScript(tab.id, {
      code: makeItGreen
    });
  }
});</pre>

<p>{{WebExtExamples}}</p>

<h2 id="Compatibilité_du_navigateur">Compatibilité du navigateur</h2>

<p>{{Compat("webextensions.api.menus.create", 10)}}</p>

<div class="note"><strong>Remerciements</strong>

<p>Cette API est basée sur l'API <a href="https://developer.chrome.com/extensions/contextMenus"><code>chrome.contextMenus</code></a> de chromium. Cette documentation est dérivée de <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/context_menus.json"><code>context_menus.json</code></a> dans le code Chromium.</p>
</div>

<div class="hidden">
<pre>// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>
</div>