menus.onShown

Lancé lorsque le navigateur a montré un menu.

Une extension peut utiliser cet événement pour mettre à jour ses éléments de menu en utilisant des informations qui ne sont disponibles qu'une fois le menu affiché. Généralement, une extension trouvera la mise à jour dans son gestionnaire onShown puis appellera menus.refresh() pour mettre à jour le menu lui-même.

Le gestionnaire peut ajouter, supprimer ou mettre à jour des éléments de menu.

Par exemple, l'extension d'exemple menu-labelled-open ajoute un élément de menu qui s'affiche lorsque l'utilisateur clique sur un lien et qui, lorsqu'il est cliqué, ouvre simplement le lien. Il utilise onShown et refresh() pour annoter l'élément de menu avec le nom d'hôte du lien, afin que l'utilisateur puisse facilement voir où il ira avant de cliquer.

Notez qu'une extension ne devrait pas prendre trop de temps avant d'appeler refresh(), sinon la mise à jour sera visible par l'utilisateur.

Le gestionnaire reçoit des informations sur le menu et son contenu, ainsi que des informations sur la page (telles que le lien et / ou le texte de sélection). Pour accéder aux informations de la page, votre extension doit avoir la permission de l'hôte.

Si le gestionnaire onShown appelle des API asynchrones, il est possible que le menu ait été fermé à nouveau avant que le gestionnaire ne reprenne l'exécution. Pour cette raison, si un gestionnaire appelle des API asynchrones, il doit vérifier que le menu est toujours affiché avant la mise à jour du menu. Par exemple :

var lastMenuInstanceId = 0;
var nextMenuInstanceId = 1;

browser.menus.onShown.addListener(async function(info, tab) {
  var menuInstanceId = nextMenuInstanceId++;
  lastMenuInstanceId = menuInstanceId;

  // Call an async function
  await .... ;

  // After completing the async operation, check whether the menu is still shown.
  if (menuInstanceId !== lastMenuInstanceId) {
    return; // Menu was closed and shown again.
  }
  // Now use menus.create/update + menus.refresh.
});

browser.menus.onHidden.addListener(function() {
  lastMenuInstanceId = 0;
});

Notez qu'il est possible d'appeler les fonctions API des menus de manière synchrone, et dans ce cas vous n'avez pas à effectuer cette vérification :

browser.menus.onShown.addListener(async function(info, tab) {
  browser.menus.update(menuId, ...);
   // Note: Not waiting for returned promise.
  browser.menus.refresh();
});

Toutefois, si vous appelez ces API de manière asynchrone, vous devez effectuer la vérification suivante :

browser.menus.onShown.addListener(async function(info, tab) {
  var menuInstanceId = nextMenuInstanceId++;
  lastMenuInstanceId = menuInstanceId;

  await browser.menus.update(menuId, ...);
  // must now perform the check
  if (menuInstanceId !== lastMenuInstanceId) {
    return;
  }
  browser.menus.refresh();
});

Firefox rend cet événement disponible via l'espace de noms contextMenus ainsi que l'espace de nom des menus.

Syntaxe

browser.menus.onShown.addListener(listener);
browser.menus.onShown.removeListener(listener);
browser.menus.onShown.hasListener(listener);

Les événements ont trois fonctions :

addListener(listener): Ajoute un écouteur à cet événement
removeListener(listener): Arrêtez d'écouter cet événement. L'argument listener est l'écouteur à supprimer.
hasListener(listener): Vérifiez si le listener est enregistré pour cet événement. Renvoie true s'il écoute, sinon false.

Syntaxe addListener

Paramètres

callback

Fonction qui sera appelée lorsque cet événement se produit. La fonction recevra les arguments suivants :

info

Object. Ceci est juste comme l'objet menus.OnClickData, sauf qu'il contient deux propriétés supplémentaires:

contexts: un tableau de tous les contexts applicables à ce menu.
menuIds: un tableau d'ID de tous les éléments de menu appartenant à cette extension qui sont affichés dans ce menu.

En comparaison avec menus.OnClickData, l'objet info omet également les propriétés menuItemId et modifiers, car bien sûr, celles-ci ne sont pas disponibles tant qu'un élément de menu n'a pas été sélectionné.

Les propriétés contexts, menuIds, frameId, et editable modifiables sont toujours fournis. Toutes les autres propriétés dans info sont uniquement fournies si l'extension a la permission d'hôte pour la page.

tab: tabs.Tab. Les détails de l'onglet où le clic a eu lieu. Si le clic n'a pas eu lieu dans ou sur un onglet, ce paramètre sera manquant.

Compatibilité des navigateurs

BCD tables only load in the browser

Exemples

Cet exemple permet d'afficher le menu contextuel sur un lien, puis met à jour l'élément de menu openLabelledId avec le nom d'hôte du lien :

function updateMenuItem(linkHostname) {
  browser.menus.update(openLabelledId, {
    title: `Open (${linkHostname})`,
  });
  browser.menus.refresh();
}

browser.menus.onShown.addListener((info) => {
  if (!info.linkUrl) {
    return;
  }
  let linkElement = document.createElement("a");
  linkElement.href = info.linkUrl;
  updateMenuItem(linkElement.hostname);
});

Example extensions

menu-labelled-open