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
|
---
title: document.execCommand
slug: Web/API/Document/execCommand
tags:
- API
- DOM
- Method
- Méthodes
- Reference
translation_of: Web/API/Document/execCommand
---
<div>{{ApiRef("DOM")}}{{deprecated_header}}</div>
<p>Lorsqu'un document HTML passe en <code><a href="/fr/docs/Web/API/Document/designMode">designMode</a></code>, l'objet <code>document</code> correspondant expose une méthode <strong><code>execCommand()</code></strong> permettant d'exécuter des commandes manipulant la région éditable courante tels que <a href="/fr/docs/Web/HTML/Element/input">les champs de formulaire</a> ou les éléments <code><a href="/fr/docs/Web/HTML/Global_attributes/contenteditable">contentEditable</a></code>.</p>
<p>La plupart des commandes affectent la <a
href="/fr/docs/Web/API/Selection">sélection</a> du document (mise en gras, italique, etc.), tandis que
d'autres insèrent de nouveaux éléments (un lien) ou modifient toute une ligne (indentation). Lorsqu'on
utilise <code>contentEditable</code>, <code>execCommand()</code> affecte l'élément éditable
courant.</p>
<h2 id="Syntax">Syntaxe</h2>
<pre class="brush: js"><var>document</var>.execCommand(<var>aCommandName</var>, <var>aShowDefaultUI</var>, <var>aValueArgument</var>)
</pre>
<h3 id="Return_value">Valeur de retour</h3>
<p>Un booléen ({{jsxref('Boolean')}}) qui vaut <code>false</code> si la commande n'est pas
prise en charge ou si elle est désactivée.</p>
<div class="note">
<p><strong>Note :</strong> <code><var>document</var>.execCommand()</code> ne renvoie
<code>true</code> que s'il est appelé à partir d'une interaction utilisateur. On ne
peut pas l'invoquer dans un script afin de vérifier la prise en charge navigateur avant
d'appeler une commande. À partir de Firefox 82, les appels imbriqués à
<code>document.execCommand()</code> renverront toujours <code>false</code>.</p>
</div>
<h3 id="Parameters">Paramètres</h3>
<dl>
<dt><code><var>aCommandName</var></code></dt>
<dd>Une chaîne de caractères {{domxref("DOMString")}} indiquant le nom de la commande à
exécuter. Voir {{anch("Commands")}} pour une liste de commandes possibles.</dd>
<dt><code><var>aShowDefaultUI</var></code></dt>
<dd>Un booléen ({{jsxref("Boolean")}}) indiquant si l'interface utilisateur par défaut
devrait être affichée. Ce n'est pas implémenté par Mozilla.</dd>
<dt><code><var>aValueArgument</var></code></dt>
<dd>Pour les commandes utilisant un argument en entrée, il s'agit d'une chaîne {{domxref("DOMString")}}
qui fournit cette information. On pourra, par exemple, <code>insertImage</code> utilise
l'URL de l'image à insérer. On utilisera <code>null</code> si aucun argument n'est utilisé.</dd>
</dl>
<h3 id="Commands">Commandes</h3>
<dl>
<dt><code>backColor</code></dt>
<dd><p>Modifie la couleur d'arrière-plan du document. Avec le mode <code>styleWithCss</code> cela affecte la couleur d'arrière-plan du bloc englobant. Une chaîne de caractères décrivant une valeur {{cssxref("<color>")}} doit être passée en argument. On notera qu'Internet Explorer utilise ceci pour la couleur d'arrière-plan du texte.</p></dd>
<dt><code>bold</code></dt>
<dd><p>Active ou désactive la mise en gras pour la sélection ou à partir du point d'insertion Internet Explorer utilise la balise {{HTMLElement("strong")}} plutôt que {{HTMLElement("b")}}.</p></dd>
<dt><code>ClearAuthenticationCache</code></dt>
<dd><p>Supprime toutes les informations d'authentification <i>credentials</i>) du cache.</p></dd>
<dt><code>contentReadOnly</code></dt>
<dd><p>Rend le contenu du document en lecture seule ou éditable en fonction du booléen passé en argument (n'est pas pris en charge par Internet Explorer)</p></dd>
<dt><code>copy</code></dt>
<dd><p>Copie la sélection courante vers le presse-papier. Les conditions pour obtenir ce comportement peuvent varier d'un navigateur à l'autre. Veuillez voir le tableau de compatibilité ci-après.</p></dd>
<dt><code>createLink</code></dt>
<dd><p>Crée un hyperlien à partir de la sélection (sous réserve qu'il y en ait une). Une chaîne de caractères formant un URI est nécessaire comme argument afin de fournir la valeur de l'attribut <code>href</code>. L'URI doit contenir au moins un caractère (qui peut être un blanc). (Internet Explorer créera un lien avec une valeur <code>null</code>.)</p></dd>
<dt><code>cut</code></dt>
<dd><p>Coupe le contenu de la sélection courante et le copie dans le presse-papier. Les conditions pour obtenir ce comportement peuvent varier d'un navigateur à l'autre. Veuillez voir le tableau de compatibilité ci-après.</p></dd>
<dt><code>decreaseFontSize</code></dt>
<dd><p>Ajoute une balise {{HTMLElement("small")}} autour de la sélection ou au point d'insertion. (Non pris en charge par Internet Explorer.)</p></dd>
<dt><code>defaultParagraphSeparator</code></dt>
<dd><p>Modifie le séparateur de paragraphe utilisé lorsque de nouveaux paragraphes sont créés dans les zones de texte éditables. Voir <a href="/fr/docs/Web/Guide/HTML/Editable_content#differences_in_markup_generation"> Différences dans la génération du balisage</a> pour plus de détails.</p></dd>
<dt><code>delete</code></dt>
<dd><p>Supprimer la sélection courante.</p></dd>
<dt><code>enableAbsolutePositionEditor</code></dt>
<dd><p>Active ou désactive la poignée qui permet de déplacer les éléments positionnés de façon absolue. Celle-ci est désactivée par défaut depuis Firefox 64 ({{bug(1490641)}}).</p></dd>
<dt><code>enableInlineTableEditing</code></dt>
<dd><p>Active ou désactive les contrôles pour l'insertion ou la suppression des lignes ou colonnes de tableau. Les contrôles sont désactivés par défaut depuis Firefox 64 ({{bug(1490641)}}).</p></dd>
<dt><code>enableObjectResizing</code></dt>
<dd><p>Active ou désactive les contrôles permettant de redimensionner les images, tableaux ou les éléments positionnés de façon absolue. Les poignées sont désactivées par défaut depuis Firefox 64 ({{bug(1490641)}}).</p></dd>
<dt><code>fontName</code></dt>
<dd><p>Modifie le nom de la police pour la sélection ou à partir du point d'insertion. La valeur fournie en argument doit être un nom de police (ex. <code>"Arial"</code>).</p></dd>
<dt><code>fontSize</code></dt>
<dd><p>Modifie la taille de la police pour la sélection ou à partir du point d'insertion. La valeur fournie en argument doit être un entier compris entre 1 et 7.</p></dd>
<dt><code>foreColor</code></dt>
<dd><p>Modifie la couleur de la police pour la sélection ou à partir du point d'insertion. La valeur passée en argument doit être une chaîne de caractères décrivant une couleur exprimée en notation hexadécimale.</p></dd>
<dt><code>formatBlock</code></dt>
<dd><p>Ajoute un élément HTML de bloc autour de la ligne contenant la sélection courante et remplace l'éventuel élément de bloc englobant s'il en existe un (pour Firefox, {{HTMLElement("blockquote")}} fera exception et englobera n'importe quel bloc). L'argument passé doit être un nom de balise. Tous les éléments de bloc peuvent en théorie être utilisés. (Internet Explorer et Edge ne prennent en charge que les balises <code>H1</code><code>H6</code>, <code>ADDRESS</code>, et <code>PRE</code> qui doivent être passées entre chevrons : <code>"<H1>"</code>.)</p></dd>
<dt><code>forwardDelete</code></dt>
<dd><p>Supprime un caractère à la position du curseur. Le comportement obtenu est le même que lorsqu'on appuie sur la touche <kbd>Suppr</kbd> d'un clavier Windows.</p></dd>
<dt><code>heading</code></dt>
<dd><p>Ajoute un élément de titre autour de la sélection ou au niveau du point d'insertion. L'argument doit être le nom d'une balise de titre (<code>"H1"</code> à <code>"H6"</code>). (Non pris en charge par Internet Explorer et Safari.)</p></dd>
<dt><code>hiliteColor</code></dt>
<dd><p>Modifie la couleur d'arrière-plan pour la sélection ou à partir du point d'insertion. La valeur passée en argument doit être une chaîne de caractères définissant une couleur et <code>useCSS</code> doit valoir <code>true</code>. (Non pris en charge par Internet Explorer.)</p></dd>
<dt><code>increaseFontSize</code></dt>
<dd><p>Ajoute une balise {{HTMLElement("big")}} autour de la sélection ou à partir du point d'insertion. (Non pris en charge par Internet Explorer).</p></dd>
<dt><code>indent</code></dt>
<dd><p>Augmente l'indentation de la ligne contenant la sélection ou le point d'insertion. Pour Firefox, si la sélection s'étend sur plusieurs lignes ayant différents niveaux d'indentation, seules les lignes les moins indentées seront décalées.</p></dd>
<dt><code>insertBrOnReturn</code></dt>
<dd><p>Contrôle si la touche <kbd>Entrée</kbd> insère un élément {{HTMLElement("br")}} ou si le bloc courant est scindé en deux. (Non pris en charge par Internet Explorer.)</p></dd>
<dt><code>insertHorizontalRule</code></dt>
<dd><p>Insère un élément {{HTMLElement("hr")}} au point d'insertion ou remplace la sélection courante par cet élément.</p></dd>
<dt><code>insertHTML</code></dt>
<dd><p>Insère un élément au point d'insertion en supprimant la sélection. Une chaîne de caractères HTML valide doit être fournie en argument. (Non pris en charge par Internet Explorer.)</p></dd>
<dt><code>insertImage</code></dt>
<dd><p>Insère une image au point d'insertion en supprimant la sélection. L'argument doit être une chaîne de caractères indiquant l'URL à utiliser pour l'attribut <code>src</code> de l'image. Les prérequis de cette valeur sont les mêmes que pour <code>createLink</code>.</p></dd>
<dt><code>insertOrderedList</code></dt>
<dd><p>Crée une <a href="/fr/docs/Web/HTML/Element/ol">liste numérotée ordonnée</a> pour la sélection ou à partir du point d'insertion.</p></dd>
<dt><code>insertUnorderedList</code></dt>
<dd><p>Crée une <a href="/fr/docs/Web/HTML/Element/ul">liste non-ordonnée</a> pour la sélection ou à partir du point d'insertion.</p></dd>
<dt><code>insertParagraph</code></dt>
<dd><p>Insère un <a href="/fr/docs/Web/HTML/Element/p">paragraphe</a> autour de la sélection pour la ligne courante. (Internet Explorer insère un paragraphe au point d'insertion et supprime la sélection.)</p></dd>
<dt><code>insertText</code></dt>
<dd><p>Insère le texte indiqué au point d'insertion (quitte à supprimer l'éventuelle sélection courante).</p></dd>
<dt><code>italic</code></dt>
<dd><p>Active ou désactive la mise en italique pour la sélection ou à partir du point d'insertion. (Internet Explorer utilisera l'élément {{HTMLElement("em")}} plutôt que {{HTMLElement("i")}}.)</p></dd>
<dt><code>justifyCenter</code></dt>
<dd><p>Centre la sélection ou le point d'insertion.</p></dd>
<dt><code>justifyFull</code></dt>
<dd><p>Justifie la sélection ou le point d'insertion.</p></dd>
<dt><code>justifyLeft</code></dt>
<dd><p>Justifie à gauche la sélection ou le point d'insertion.</p></dd>
<dt><code>justifyRight</code></dt>
<dd><p>Justifie à droite la sélection ou le point d'insertion.</p></dd>
<dt><code>outdent</code></dt>
<dd><p>Effectue un retrait d'indentation pour la ligne courante.</p></dd>
<dt><code>paste</code></dt>
<dd><p>Colle le contenu du presse-papier au point d'insertion (et remplace éventuellement la sélection actuelle). Fonctionnalité désactivée pour le contenu web.</p></dd>
<dt><code>redo</code></dt>
<dd><p>Rejoue l'action annulée par la précédente commande <code>undo</code>.</p></dd>
<dt><code>removeFormat</code></dt>
<dd><p>Supprime toute mise en forme pour la sélection courante.</p></dd>
<dt><code>selectAll</code></dt>
<dd><p>Sélectionne l'ensemble du contenu de la région éditable.</p></dd>
<dt><code>strikeThrough</code></dt>
<dd><p>Active ou désactive la rayure de la sélection ou à partir d'un point d'insertion.</p></dd>
<dt><code>subscript</code></dt>
<dd><p>Active ou désactive <a href="/fr/docs/Web/HTML/Element/sub">la mise en indice</a> pour la sélection ou au point d'insertion</p></dd>
<dt><code>superscript</code></dt>
<dd><p>Active ou désactive <a href="/fr/docs/Web/HTML/Element/sup">la mise en exposant</a> pour la sélection ou au point d'insertion</p></dd>
<dt><code>underline</code></dt>
<dd><p>Active ou désactive <a href="/fr/docs/Web/HTML/Element/u">le soulignement</a> pour la sélection ou au point d'insertion.</p></dd>
<dt><code>undo</code></dt>
<dd><p>Annule la dernière commande exécutée.</p></dd>
<dt><code>unlink</code></dt>
<dd><p>Retire l'<a href="/fr/docs/Web/HTML/Element/a">ancre</a> de l'hyperlien sélectionné.</p></dd>
<dt><code>useCSS</code> {{Deprecated_inline}}</dt>
<dd><p>Active/désactive l'utilisation de balises HTML ou de CSS pour le balisage généré. La valeur de l'argument doit être un booléen. Note : cet argument possède une logique inversée (<code>false</code> permet d'utiliser CSS et <code>true</code> permet d'utiliser HTML). Cette valeur n'est pas prise en charge par Internet Explorer et a été dépréciée en faveur de <code>styleWithCSS</code>.</p></dd> <dt><code>styleWithCSS</code></dt>
<dd><p>Remplace la commande <code>useCSS</code>. <code>true</code> modifie/génère des attributs <code>style</code> dans le balisage tandis que <code>false</code> génère des éléments HTML de présentation.</p></dd>
</dl>
<h2 id="Example">Exemple</h2>
<p>Un exemple d'utilisation est disponible
<a href="https://codepen.io/chrisdavidmills/full/gzYjag/">sur CodePen</a>.</p>
<h2 id="Specifications">Spécifications</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Spécification</th>
<th scope="col">État</th>
<th scope="col">Commentaires</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="https://w3c.github.io/editing/docs/execCommand/">execCommand</a></td>
<td>Brouillon non officiel</td>
<td></td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Compatibilité des navigateurs</h2>
<p>{{Compat("api.Document.execCommand")}}</p>
<h2 id="See_also">Voir aussi</h2>
<ul>
<li>{{domxref("HTMLElement.contentEditable")}}</li>
<li>{{domxref("document.designMode")}}</li>
<li><a href="/fr/docs/Web/Guide/HTML/Editable_content/Rich-Text_Editing_in_Mozilla">L'édition HTML dans Firefox</a>
</li>
<li><a
href="https://github.com/guardian/scribe/blob/master/BROWSERINCONSISTENCIES.md">Documentation des incohérences
navigateur dans Scribe</a> qui indique les bugs liés à <code>document.execCommand</code>.</li>
</ul>
|
