-
Notifications
You must be signed in to change notification settings - Fork 8k
/
index.md
332 lines (263 loc) · 14.6 KB
/
index.md
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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
---
title: <input type="checkbox">
slug: Web/HTML/Element/input/checkbox
l10n:
sourceCommit: 2b4bf33acb346baf925fad1317f425ba2b967456
---
{{HTMLSidebar}}
Les éléments [`<input>`](/fr/docs/Web/HTML/Element/input) de type **`checkbox`** sont affichés sous la forme de boîtes à cocher qui sont cochées lorsqu'elles sont activées. Elles permettent de sélectionner une ou plusieurs valeurs dans un formulaire. Leur apparence exacte dépend du navigateur utilisé. Il s'agit généralement d'une case carrée, dont les coins peuvent parfois être arrondis.
{{EmbedInteractiveExample("pages/tabbed/input-checkbox.html", "tabbed-standard")}}
> **Note :** [Les boutons radio](/fr/docs/Web/HTML/Element/input/radio) sont semblables aux cases à cocher, mais il existe une différence importante : les boutons radio permettent de sélectionner une seule valeur parmi plusieurs d'[un même groupe (identifié par le nom)](/fr/docs/Web/HTML/Element/input/radio#defining_a_radio_group) alors que les cases à cocher permettent de cocher/décocher plusieurs valeurs d'un groupe.
## Valeur
Une chaîne de caractères qui représente la valeur de la case à cocher. Cette chaîne de caractères n'est pas affichée côté client mais est envoyée au serveur comme valeur associée à la donnée envoyée avec le nom de la case à cocher. Par exemple :
```html
<form>
<div>
<input
type="checkbox"
id="subscribeNews"
name="subscribe"
value="newsletter" />
<label for="subscribeNews">
Souhaitez-vous vous abonner à la newsletter ?
</label>
</div>
<div>
<button type="submit">Subscribe</button>
</div>
</form>
```
Dans cet exemple, on a le nom (l'attribut `name`) `subscribe` utilisé pour la case à cocher avec une valeur (l'attribut `value`) qui est `newsletter`. Lorsque le formulaire est envoyé, les données seront transmises sous la forme `subscribe=newsletter`.
Si l'attribut `value` n'était pas renseigné, la valeur par défaut serait `on` (dans l'exemple, les données envoyées au serveur auraient eu la forme `subscribe=on`).
> **Note :** Si la case à cocher n'est pas cochée lorsque le formulaire est envoyé, ni le nom ni la valeur ne sont envoyés au serveur pour indiquer cet état (autrement dit, le client n'envoie pas quelque chose comme `value=unchecked`) ; la valeur n'est pas transmise au serveur du tout. Si on veut envoyer une valeur par défaut lorsque la case à cocher est décochée, une solution pourrait être d'utiliser du JavaScript pour créer un élément [`<input type="hidden">`](/fr/docs/Web/HTML/Element/input/hidden).
## Attributs supplémentaires
En plus des attributs qui sont partagés par l'ensemble des éléments [`<input>`](/fr/docs/Web/HTML/Element/input), les champs de type `checkbox` prennent aussi en charge les attributs suivants :
- `checked`
- : Un attribut booléen qui indique si la case est cochée par défaut à l'ouverture de la page. Cet attribut n'indique _pas_ si la case est actuellement cochée : si l'état a été modifié, l'attribut dans le document ne reflètera pas cette modification (seul l'attribut IDL `checked` de l'objet [`HTMLInputElement`](/fr/docs/Web/API/HTMLInputElement) est mis à jour).
> **Note :** À la différence des autres champs, les valeurs des cases à cocher ne sont envoyées au serveur que lorsqu'elles sont cochées. Lorsque c'est le cas, c'est la valeur de l'attribut `value` qui est envoyé (ou la valeur `on` si aucun attribut `value` n'est présent).
> À la différence des autres navigateurs, Firefox [conserve l'état coché placé dynamiquement](https://stackoverflow.com/questions/5985839/bug-with-firefox-disabled-attribute-of-input-not-resetting-when-refreshing) d'un champ `<input>` après les rechargements de la page. L'attribut [`autocomplete`](/fr/docs/Web/HTML/Element/input#autocomplete) peut être utilisé afin de contrôler cette fonctionnalité.
- `value`
- : L'attribut `value` est partagé par l'ensemble des éléments [`<input>`](/fr/docs/Web/HTML/Element/input), mais il a un rôle spécifique pour les champs de type `checkbox` : lorsqu'un formulaire est envoyé, seules les cases à cocher qui sont cochées sont envoyées au serveur et c'est la valeur de l'attribut `value` qui est envoyée. Si l'attribut `value` n'est pas renseigné, ce sera la chaîne de caractères `"on"` qui sera envoyée par défaut (voir [la section précédente](#valeur))
## Utiliser les cases à cocher
### Gérer plusieurs cases à cocher
Dans l'exemple précédent, il n'y a qu'une seule case à cocher. Dans un scénario réaliste, on aura vraisemblablement plusieurs cases à cocher. Si celles-ci n'ont pas de rapport entre elles, il est possible de les gérer de façon séparée avec des cases à cocher « unitaires » comme illustré précédemment. Toutefois, si les valeurs sont liées entre elles, il est alors nécessaire d'indiquer ce lien.
Dans l'exemple qui suit, on affiche différentes cases à cocher pour représenter les intérêts d'une personne (voir l'exemple complet dans la section [Exemples](#exemples)).
```html
<fieldset>
<legend>Veuillez sélectionner vos intérêts</legend>
<div>
<input type="checkbox" id="coding" name="interest" value="coding" />
<label for="coding">Développement</label>
</div>
<div>
<input type="checkbox" id="music" name="interest" value="music" />
<label for="music">Musique</label>
</div>
</fieldset>
```
{{EmbedLiveSample('', 600, 100)}}
Dans cet exemple on voit que chaque case à cocher utilise le même attribut `name`. Si les deux cases sont cochées lorsque le formulaire est envoyé, la chaîne des paires nom/valeur qui sera envoyée au serveur sera : `interest=coding&interest=music`. Lorsque les données parviennent au serveur, on peut ainsi récupérer un tableau des valeurs sélectionnées (voir [la question StackOverflow : Gérer plusieurs cases à cocher avec une seule variable côté serveur](https://stackoverflow.com/questions/18745456/handle-multiple-checkboxes-with-a-single-serverside-variable) par exemple).
### Cocher certaines cases par défaut
Afin qu'une case à cocher soit sélectionnée par défaut, il suffit de placer l'attribut booléen `checked`. Voir l'exemple qui suit :
```html
<fieldset>
<legend>Veuillez sélectionner vos intérêts</legend>
<div>
<input type="checkbox" id="coding" name="interest" value="coding" checked />
<label for="coding">Développement</label>
</div>
<div>
<input type="checkbox" id="music" name="interest" value="music" />
<label for="music">Musique</label>
</div>
</fieldset>
```
{{EmbedLiveSample('', 600, 100)}}
### Fournir une zone cliquable plus grande
Dans les exemples précédents, vous avez peut-être remarqué qu'il était possible de cocher une case en cliquant sur l'élément [`<label>`](/fr/docs/Web/HTML/Element/label) associé. Il s'agit d'une fonctionnalité particulièrement utile des étiquettes de formulaire HTML : il y a ainsi plus d'espace qui peut être utilisé pour sélectionner les options voulues (notamment sur les petits écrans).
En plus des raisons liées à l'accessibilité, il s'agit d'une bonne raison pour indiquer correctement des éléments `<label>` dans vos formulaires.
### Gérer un état indéterminé
Il existe un état indéterminé pour les cases à cocher qui indique que la case n'est ni cochée, ni décochée mais indéterminée. Cet état peut être obtenu via la propriété `indeterminate` d'un élément [`HTMLInputElement`](/fr/docs/Web/API/HTMLInputElement) en JavaScript (il est impossible d'obtenir cet état en utilisant uniquement du HTML) :
```js
inputInstance.indeterminate = true;
```
Dans la plupart des navigateurs, une case à cocher dans un état indéterminé est représentée avec une ligne horizontale en travers de la case.
Il n'y a pas beaucoup de cas d'usage pour cette propriété. Le scénario le plus fréquent est d'avoir une case à cocher parente, contenant plusieurs options filles représentées par d'autres cases à cocher. Si l'ensemble des options filles est coché, la case à cocher parente est cochée, si toutes les options filles sont décochées, la case à cocher parente est décochée. En revanche, si au moins une des options filles est dans un état différent des autres, la case à cocher parente apparaît dans un état indéterminé.
Voici un exemple d'utilisation de cet état (tiré de [CSS Tricks](https://css-tricks.com/indeterminate-checkboxes/)) où on tient le compte des ingrédients qu'on possède pour une recette. Lorsqu'on coche ou décoche une case d'un ingrédient, une fonction JavaScript vérifie le nombre d'ingrédients possédés (c'est-à-dire cochés) :
- Si aucun n'est coché, la case associée à la recette est décochée.
- Si un ou deux éléments sont cochés, la case associée à la recette est dans un état indéterminé.
- Si les trois ingrédients sont cochés, la case associée à la recette est cochée.
Dans cet exemple, l'état `indeterminate` est utilisé afin d'indiquer qu'on possède certains ingrédients mais pas suffisamment pour une recette.
```js
const overall = document.querySelector("#enchantment");
const ingredients = document.querySelectorAll("ul input");
overall.addEventListener("click", (e) => {
e.preventDefault();
});
for (const ingredient of ingredients) {
ingredient.addEventListener("click", updateDisplay);
}
function updateDisplay() {
let checkedCount = 0;
for (const ingredient of ingredients) {
if (ingredient.checked) {
checkedCount++;
}
}
if (checkedCount === 0) {
overall.checked = false;
overall.indeterminate = false;
} else if (checkedCount === ingredients.length) {
overall.checked = true;
overall.indeterminate = false;
} else {
overall.checked = false;
overall.indeterminate = true;
}
}
```
{{EmbedGHLiveSample("learning-area/html/forms/indeterminate-example/index.html", '100%', 200)}}
> **Note :** Si vous envoyez un formulaire avec une case à cocher dans un état indéterminé, le résultat obtenu est le même que si la case avait été décochée : aucune donnée n'est envoyée au serveur.
## Validation
Les cases à cocher prennent en charge la [validation](/fr/docs/Web/HTML/Constraint_validation) (comme d'autres [`<input>`](/fr/docs/Web/HTML/Element/input)). Toutefois, la plupart des propriétés de l'instance correspondante [`ValidityState`](/fr/docs/Web/API/ValidityState) vaudront toujours `false`. Si la case à cocher utilise l'attribut [`required`](/fr/docs/Web/HTML/Element/input#required), mais n'est pas cochée, [`ValidityState.valueMissing`](/fr/docs/Web/API/ValidityState/valueMissing) vaudra `true`.
## Exemples
Dans l'exemple suivant, on développe l'exemple vu précédemment avec les groupes de cases à cocher : il y a cette fois plus d'options et un champ texte libre qui permet de saisir une autre valeur. Pour cela on utilise un bloc de code JavaScript et quelques règles CSS pour la mise en forme.
### HTML
```html
<form>
<fieldset>
<legend>Veuillez sélectionner vos intérêts</legend>
<div>
<label>
<input type="checkbox" id="coding" name="interest" value="coding" />
Développement
</label>
</div>
<div>
<label>
<input type="checkbox" id="music" name="interest" value="music" />
Musique
</label>
</div>
<div>
<label>
<input type="checkbox" id="art" name="interest" value="art" />
Art
</label>
</div>
<div>
<label>
<input type="checkbox" id="sports" name="interest" value="sports" />
Sports
</label>
</div>
<div>
<label>
<input type="checkbox" id="cooking" name="interest" value="cooking" />
Cuisine
</label>
</div>
<div>
<label>
<input type="checkbox" id="other" name="interest" value="other" />
Autre
</label>
<input
type="text"
id="otherValue"
name="other"
aria-label="Autres intérêts" />
</div>
<div>
<button type="submit">Envoyer le formulaire</button>
</div>
</fieldset>
</form>
```
### CSS
```css
html {
font-family: sans-serif;
}
form {
width: 600px;
margin: 0 auto;
}
div {
margin-bottom: 10px;
}
fieldset {
background: cyan;
border: 5px solid blue;
}
legend {
padding: 10px;
background: blue;
color: cyan;
}
```
### JavaScript
```js
const otherCheckbox = document.querySelector("#other");
const otherText = document.querySelector("#otherValue");
otherText.style.visibility = "hidden";
otherCheckbox.addEventListener("change", () => {
if (otherCheckbox.checked) {
otherText.style.visibility = "visible";
otherText.value = "";
} else {
otherText.style.visibility = "hidden";
}
});
```
### Résultat
{{EmbedLiveSample('', '100%', 300)}}
## Résumé technique
<table class="properties">
<tbody>
<tr>
<td><strong><a href="#valeur">Valeur</a></strong></td>
<td>
Une chaîne de caractères qui représente la valeur de la case à cocher.
</td>
</tr>
<tr>
<td><strong>Évènements</strong></td>
<td><a href="/fr/docs/Web/API/HTMLElement/change_event"><code>change</code></a> et <a href="/fr/docs/Web/API/HTMLElement/input_event"><code>input</code></a></td>
</tr>
<tr>
<td><strong>Attributs pris en charge</strong></td>
<td><code>checked</code></td>
</tr>
<tr>
<td><strong>Attributs IDL</strong></td>
<td>
<code><a href="#checked">checked</a></code>,
<code><a href="#indeterminate">indeterminate</a></code> et
<code><a href="#value">value</a></code>
</td>
</tr>
<tr>
<td><strong>Interface DOM</strong></td>
<td><a href="/fr/docs/Web/API/HTMLInputElement"><code>HTMLInputElement</code></a></td>
</tr>
<tr>
<td><strong>Méthodes</strong></td>
<td>
<a href="/fr/docs/Web/API/HTMLInputElement/select"><code>select()</code></a>
</td>
</tr>
<tr>
<td><strong>Rôle ARIA implicite</strong></td>
<td><a href="/fr/docs/Web/Accessibility/ARIA/Roles/checkbox_role"><code>checkbox</code></a></td>
</tr>
</tbody>
</table>
## Spécifications
{{Specifications}}
## Compatibilité des navigateurs
{{Compat}}
## Voir aussi
- Les sélecteurs CSS qui permettent de mettre en forme les cases à cocher en fonction de leur état actuel : [`:checked`](/fr/docs/Web/CSS/:checked), [`:indeterminate`](/fr/docs/Web/CSS/:indeterminate)
- L'interface du DOM qui représente cet élément : [`HTMLInputElement`](/fr/docs/Web/API/HTMLInputElement)
- [Tableau de compatibilité des propriétés CSS pour les contrôles de formulaires](/fr/docs/Learn/Forms/Property_compatibility_table_for_form_controls)