menus.create()

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

 

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.

 

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

Syntaxe

browser.menus.create(
  createProperties, // object
  function() {...}  // optional function
)

Paramètres

createProperties
object. Propriétés pour le nouvel élément de menu.
checked Facultatif
boolean. L'état initial d'une case à cocher ou d'un élément radio : true pour selected et false pour non sélectionné. Un seul élément radio peut être sélectionné à la fois dans un groupe donné d'éléments radio.
command Facultatif

string. Chaîne décrivant une action à effectuer lorsque l'utilisateur clique sur l'élément. Les valeurs possibles sont:

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

Cliquer sur l'élément déclenchera toujours l'événement menus.onClicked, mais il n'y a aucune garantie de la commande ici: la commande peut être exécutée avant les incendies onClicked.

contexts Facultatif

array de menus.ContextType. Tableau des contextes dans lesquels cet élément de menu apparaîtra. Si cette option est omise :

  • Si l'élément parent a des contextes définis, alors cet élément héritera des contextes de ses parents
  • sinon, l'élément reçoit un tableau de contexte de ["page"].
documentUrlPatterns Facultatif
array de string. Vous permet de restreindre l'élément à appliquer uniquement aux documents dont l'URL correspond à l'un des motifs données. Cela s'applique également aux cadres.
enabled Facultatif
boolean. Si cet élément de menu est activé ou désactivé. Par défaut à true.
icons Facultatif

object. 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 :

 

"icons": {
      "16": "path/to/geo-16.png",
      "32": "path/to/geo-32.png"
    }

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

"icons": {
      "16": "path/to/geo.svg"
    }
id Facultatif
string. Identifiant unique à attribuer à cet élément Obligatoire pour les pages d'événement. Ne peut pas être identique à un autre ID pour cette extension.
onclick Facultatif
function. 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 menus.onClicked.
parentId Facultatif
integer ou string. 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.
targetUrlPatterns Facultatif
array de string. Similaire à documentUrlPatterns, mais vous permet de filtrer en fonction du href des balises d'ancrage et de l'attribut src des balises img/audio/video tags.
title Facultatif

string. Le texte à afficher dans l'article. Obligatoire sauf si le type est "separator".

Vous pouvez utiliser "%s" 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 titre 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".

type Facultatif
menus.ItemType. Le type d'élément de menu : "normal", "checkbox", "radio", "separator". Par défaults à "normal".
callback Facultatif
function. 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 runtime.lastError.

Valeur retournée

integer ou string. L'ID de l'article nouvellement créé.

Compatibilité du navigateur

ChromeEdgeFirefoxFirefox for AndroidOpera
Support simple Oui1 2141 2

55

482 3

Non Oui1 2
command Non Non55 Non Non
icons Non Non56 Non Non

1. Items that don't specify 'contexts' do not inherit contexts from their parents.

2. Supported as contextMenus.create.

3. Before version 53, items that don't specify 'contexts' do not inherit contexts from their parents.

Exemples

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

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);
  }
});

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 permission activeTab.

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
    });    
  }
});

Example extensions

Remerciements

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.

Étiquettes et contributeurs liés au document

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