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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
---
title: commands
slug: Mozilla/Add-ons/WebExtensions/manifest.json/commands
tags:
- Add-ons
- Extensions
- Keyboard Shortcuts
- WebExtensions
translation_of: Mozilla/Add-ons/WebExtensions/manifest.json/commands
---
<div>{{AddonSidebar}}</div>
<table class="standard-table">
<tbody>
<tr>
<th scope="row" style="width: 30%;">Type</th>
<td><code>Objet</code></td>
</tr>
<tr>
<th scope="row">Obligatoire</th>
<td>Non</td>
</tr>
<tr>
<th scope="row">Exemple</th>
<td>
<pre class="brush: json">
"commands": {
"toggle-feature": {
"suggested_key": {
"default": "Ctrl+Shift+Y",
"linux": "Ctrl+Shift+U"
},
"description": "Send a 'toggle-feature' event"
}
}</pre>
</td>
</tr>
</tbody>
</table>
<p>Utilisez la clé <strong><code>commands</code></strong> pour définir un ou plusieurs raccourcis clavier pour votre extension.</p>
<p>Chaque raccourci clavier est défini avec un <strong>nom</strong>, une <strong>combination de clé</strong>, et un <strong>description</strong>. Une fois que vous avez défini des commandes dans le fichier <code>manifest.json</code>, de votre extension, vous pouvez écouter leurs combinaisons de touches associées avec l'API JavaScript {{WebExtAPIRef("commands")}}.</p>
<h2 id="Syntaxe">Syntaxe</h2>
<p>La clé <code>commands</code> est un objet et chaque raccourci est une propriété de celui-ci. <strong>Le nom de la propriété est le nom du raccourci</strong>.</p>
<p>Chaque raccourci est lui-même un objet, qui possède jusqu'à deux propriétés :</p>
<ul>
<li><code>suggested_key</code> : définit la combinaison de touches</li>
<li><code>description</code> : une chaîne qui décrit ce raccourci</li>
</ul>
<p>La propriété <code>suggested_key</code> est elle-même un objet pouvant avoir l'une des propriétés suivantes et qui sont toutes des chaînes :</p>
<ul>
<li><code>"default"</code></li>
<li><code>"mac"</code></li>
<li><code>"linux"</code></li>
<li><code>"windows"</code></li>
<li><code>"chromeos"</code></li>
<li><code>"android"</code></li>
<li><code>"ios"</code></li>
</ul>
<p>La valeur de chaque propriété est le raccourci clavier pour la commande sur la plateforme donnée, sous la forme d'une chaîne contenant les touches séparées par "<code>+</code>". La valeur de <code>"default"</code> est utilisée sur toutes les plateformes qui ne sont pas listées explicitement.</p>
<p>Par exemple :</p>
<pre class="brush: json">"commands": {
"toggle-feature": {
"suggested_key": {
"default": "Alt+Shift+U",
"linux": "Ctrl+Shift+U"
},
"description": "Send a 'toggle-feature' event to the extension"
},
"do-another-thing": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
}
}
}</pre>
<p>Cela définit deux raccourcis :</p>
<ul>
<li>une nommée <code>"toggle-feature"</code>, accessible à l'aide de <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>U</kbd> sur Linux et <kbd>Alt</kbd>+<kbd>Shift</kbd>+<kbd>U</kbd> sur toutes les autres plateformes</li>
<li>une nommée <code>"do-another-thing"</code>, accessible à l'aide de <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Y</kbd> sur toutes les plateformes.</li>
</ul>
<p>Vous pouvez alors écouter la commande <code>"toggle-feature"</code> avec un code comme celui-ci :</p>
<pre class="brush: js">browser.commands.onCommand.addListener(function(command) {
if (command == "toggle-feature") {
console.log("toggling the feature!");
}
});</pre>
<h3 id="Raccourcis_spéciaux">Raccourcis spéciaux</h3>
<p>Il existe 3 <strong>raccourci spéciaux avec des actions par défaut</strong>, pour lesquels l'événement {{WebExtAPIRef("commands.onCommand")}} n'est pas déclenché :</p>
<ul>
<li><code>_execute_browser_action</code>: fonctionne comme un clic sur une <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/Browser_action">action de navigateur</a> de l'extension.</li>
<li><code>_execute_page_action</code>: fonctionne comme un clic sur une <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/Page_actions">action de page</a> de l'extension.</li>
<li><code>_execute_sidebar_action</code>: ouvre le <a href="/fr/docs/Mozilla/Add-ons/WebExtensions/Sidebars">panneau latéral</a> de l'extension. Uniquement pris en charge par Firefox et uniquement à partir de Firefox version 54.</li>
</ul>
<p>Par exemple, ce JSON définit une combinaison de touches qui clique sur l'action du navigateur de l'extension :</p>
<pre class="brush: js">"commands": {
"_execute_browser_action": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
}
}
}</pre>
<h2 id="Les_valeurs_de_raccourci">Les valeurs de raccourci</h2>
<p>Il existe deux formats valides pour les touches de raccourci : comme une combinaison de touches ou comme une clé multimédia.</p>
<h3 id="Combinaisons_de_touches">Combinaisons de touches</h3>
<p>Sur Mac, <code>"Ctrl"</code> est interprété comme <code>"Command"</code>, donc si vous avez réellement besoin de <code>"Ctrl"</code>, spécifiez <code>"MacCtrl"</code>.</p>
<p>Les combinaisons de touches doivent être composées de deux ou trois touches :</p>
<ol>
<li><strong>modificateur</strong> (obligatoire, à l'exception des touches de fonction). Il peut s'agir de <code>"Ctrl"</code>, <code>"Alt"</code>, <code>"Command"</code>, ou <code>"MacCtrl"</code>.</li>
<li><strong>second modificateur</strong> (facultatif). S'il est fourni, il doit être <code>"Shift"</code> ou (pour Firefox ≥ 63) l'un quelconque des <code>"Ctrl"</code>, <code>"Alt"</code>, <code>"Command"</code>, ou <code>"MacCtrl"</code>. Ne doit pas être le modificateur déjà utilisé comme modificateur principal.</li>
<li><strong>touche </strong>(obligatoire). Ce peut être l'une des touches :
<ul>
<li>lettres <code>A</code>–<code>Z</code></li>
<li>chiffres <code>0</code>–<code>9</code></li>
<li>fonctions <code>F1</code>–<code>F12</code></li>
<li><code>Comma</code>(virgule), <code>Period</code>(point), <code>Home</code> (début), <code>End</code> (Fin), <code>PageUp</code>(page précédente), <code>PageDown</code> (page suivante), <code>Space</code> (espace), <code>Insert</code>(inser), <code>Delete</code>(Suppr), <code>Up</code> (haut), <code>Down</code> (bas), <code>Left</code>(gauche), <code>Right</code> (droite)</li>
</ul>
</li>
</ol>
<p>La clé est ensuite donnée sous la forme d'une chaîne contenant l'ensemble des valeurs de clé, dans l'ordre indiqué ci-dessus, séparées "<code>+</code>". Par exemple, <code>"Ctrl+Shift+Z"</code>.</p>
<p>Si une combinaison de touches est déjà utilisée par le navigateur (comme <code>"Ctrl+P"</code>) ou par un complément existant, vous ne pouvez pas la remplacer. Vous pouvez le définir, mais votre gestionnaire d'événements ne sera pas appelé lorsque l'utilisateur appuiera sur la combinaison de touches.</p>
<h3 id="Touches_médias">Touches médias</h3>
<p>Une alternative est de spécifier le raccourci comme l'une des touches de média suivantes :</p>
<ul>
<li><code>"MediaNextTrack"</code></li>
<li><code>"MediaPlayPause"</code></li>
<li><code>"MediaPrevTrack"</code></li>
<li><code>"MediaStop"</code></li>
</ul>
<h2 id="Mise_à_jour_des_raccourcis">Mise à jour des raccourcis</h2>
<p>Les raccourcis peuvent être mis à jour via {{WebExtAPIRef("commands.update()")}}. Les utilisateurs peuvent également mettre à jour les raccourcis via l'option "Gérer les raccourcis d'extension" sur <code>about:addons</code> dans Firefox, comme montré dans <a href="https://bug1303384.bmoattachments.org/attachment.cgi?id=9051647">cette video</a>. Dans Chrome, les utilisateurs peuvent modifier les raccourcis sur <code>chrome://extensions/shortcuts</code>.</p>
<h2 id="Exemple">Exemple</h2>
<p>Définissez un seul raccourci clavier en utilisant uniquement la combinaison de touches par défaut :</p>
<pre class="brush: json">"commands": {
"toggle-feature": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
},
"description": "Send a 'toggle-feature' event"
}
}</pre>
<p>Définissez deux raccourcis clavier, l'un avec une combinaison de touches spécifique à la plate-forme :</p>
<pre class="brush: json">"commands": {
"toggle-feature": {
"suggested_key": {
"default": "Alt+Shift+U",
"linux": "Ctrl+Shift+U"
},
"description": "Send a 'toggle-feature' event"
},
"do-another-thing": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
}
}
}</pre>
<h2 id="Compatibilité_du_navigateur">Compatibilité du navigateur</h2>
<p>{{Compat("webextensions.manifest.commands")}}</p>
|
