1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
---
title: menus.onShown
slug: Mozilla/Add-ons/WebExtensions/API/menus/onShown
tags:
- API
- Add-ons
- Event
- Extensiosn
- Reference
- WebExtensions
- menus
- onShown
translation_of: Mozilla/Add-ons/WebExtensions/API/menus/onShown
---
<div>{{AddonSidebar()}}</div>
<p>Lancé lorsque le navigateur a montré un menu.</p>
<p>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 <code>onShown</code> puis appellera {{WebExtAPIRef("menus.refresh()")}} pour mettre à jour le menu lui-même.</p>
<p>Le gestionnaire peut ajouter, supprimer ou mettre à jour des éléments de menu.</p>
<p>Par exemple, l'extension d'exemple <a href="https://github.com/mdn/webextensions-examples/tree/master/menu-labelled-open">menu-labelled-open</a> 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 <code>onShown</code> et <code>refresh()</code> 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.</p>
<p>Notez qu'une extension ne devrait pas prendre trop de temps avant d'appeler <code>refresh()</code>, sinon la mise à jour sera visible par l'utilisateur.</p>
<p>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 <a href="/fr/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">permission de l'hôte</a>.</p>
<p>Si le gestionnaire <code>onShown</code> 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 :</p>
<pre class="brush: js">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;
});</pre>
<p>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 :</p>
<pre class="brush: js">browser.menus.onShown.addListener(async function(info, tab) {
browser.menus.update(menuId, ...);
// Note: Not waiting for returned promise.
browser.menus.refresh();
});</pre>
<p>Toutefois, si vous appelez ces API de manière asynchrone, vous devez effectuer la vérification suivante :</p>
<pre class="brush: js">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();
});</pre>
<p>Firefox rend cet événement disponible via l'espace de noms <code>contextMenus</code> ainsi que l'espace de nom des <code>menus</code>.</p>
<h2 id="Syntaxe">Syntaxe</h2>
<pre class="syntaxbox brush:js">browser.menus.onShown.addListener(listener)
browser.menus.onShown.removeListener(listener)
browser.menus.onShown.hasListener(listener)
</pre>
<p>Les événements ont trois fonctions :</p>
<dl>
<dt><code>addListener(listener)</code></dt>
<dd>Ajoute un écouteur à cet événement</dd>
<dt><code>removeListener(listener)</code></dt>
<dd>Arrêtez d'écouter cet événement. L'argument <code>listener</code> est l'écouteur à supprimer.</dd>
<dt><code>hasListener(listener)</code></dt>
<dd>Vérifiez si le <code>listener</code> est enregistré pour cet événement. Renvoie <code>true</code> s'il écoute, sinon <code>false</code>.</dd>
</dl>
<h2 id="Syntaxe_addListener">Syntaxe addListener</h2>
<h3 id="Paramètres">Paramètres</h3>
<dl>
<dt><code>callback</code></dt>
<dd>
<p>Fonction qui sera appelée lorsque cet événement se produit. La fonction recevra les arguments suivants :</p>
<dl class="reference-values">
<dt><code>info</code></dt>
<dd>
<p><code>Object</code>. Ceci est juste comme l'objet {{WebExtAPIRef('menus.OnClickData')}}, sauf qu'il contient deux propriétés supplémentaires:</p>
<ul>
<li><code>contexts</code>: un tableau de tous les {{WebExtAPIRef("menus.ContextType", "contexts")}} applicables à ce menu.</li>
<li><code>menuIds</code>: un tableau d'ID de tous les éléments de menu appartenant à cette extension qui sont affichés dans ce menu.</li>
</ul>
<p>En comparaison avec <code>menus.OnClickData</code>, l'objet <code>info</code> omet également les propriétés <code>menuItemId</code> et <code>modifiers</code>, car bien sûr, celles-ci ne sont pas disponibles tant qu'un élément de menu n'a pas été sélectionné.</p>
<p>Les propriétés <code>contexts</code>, <code>menuIds</code>, <code>frameId</code>, et <code>editable</code> modifiables sont toujours fournis. Toutes les autres propriétés dans <code>info</code> sont uniquement fournies si l'extension a la <a href="/fr/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">permission d'hôte</a> pour la page.</p>
</dd>
</dl>
<dl class="reference-values">
<dt><code>tab</code></dt>
<dd>{{WebExtAPIRef('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.</dd>
</dl>
</dd>
</dl>
<h2 id="Compatibilité_du_navigateur">Compatibilité du navigateur</h2>
<p>{{Compat("webextensions.api.menus.onShown", 10)}}</p>
<h2 id="Exemples">Exemples</h2>
<p>Cet exemple permet d'afficher le menu contextuel sur un lien, puis met à jour l'élément de menu <code>openLabelledId</code> avec le nom d'hôte du lien :</p>
<pre class="brush: js">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);
});
</pre>
<p>{{WebExtExamples}}</p>
|
