aboutsummaryrefslogtreecommitdiff
path: root/files/pt-br/web/api/document/execcommand/index.html
blob: cc5e3d3da8985e4089af090d1e0a0fe1e8da736a (plain)
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
---
title: Document.execCommand()
slug: Web/API/Document/execCommand
translation_of: Web/API/Document/execCommand
---
<div>{{ApiRef("DOM")}}{{Obsolete_header}}</div>

<p><span class="seoSummary">Quando um documento HTML está em <code><a href="/en-US/docs/Web/API/Document/designMode">designMode</a></code>, seu objeto <code>document</code>  expõe um metodo <strong><code>execCommand</code></strong> para editar a região editável corrente, algo como elementos <a href="/en-US/docs/Web/HTML/Element/input">form inputs</a> ou <code><a href="/en-US/docs/Web/HTML/Global_attributes/contenteditable">contentEditable</a></code>.</span></p>

<p>A maioria dos comandos afetam apaenas uma área selecionada [<a href="/en-US/docs/Web/API/Selection">seleção</a>] (negrito, itálico, etc.), enquantos outros adicionam novos elementos (adicionar um link por exemplo), ou afetam uma linha toda (identação). Quando usando <code>contentEditable</code>, o metódo <code>execCommand()</code> afeta o elemento editável ativo.</p>

<h2 id="Síntaxe">Síntaxe</h2>

<pre class="syntaxbox"><em>document</em>.execCommand(<em>aCommandName</em>, <em>aShowDefaultUI</em>, <em>aValueArgument</em>)
</pre>

<h3 id="Valor_de_Retorno">Valor de Retorno</h3>

<p>Um {{jsxref('Boolean')}} que tem valor <code>false</code> se o comando não é válido ou está desabilitado.</p>

<div class="note">
<p><strong>Nota</strong>: Retorna <code>true</code> se for parte da interação do usuário. Não tente utilizar o retorno para verificar o suporte do browser antes de chamar o comando.</p>
</div>

<h3 id="Parâmetros">Parâmetros</h3>

<dl>
 <dt><code>aCommandName</code></dt>
 <dd>Uma {{domxref("DOMString")}} especificando o nome do comando a ser executado. Veja {{anch("Comandos")}} para um lista dos possíveis comandos.</dd>
 <dt><code>aShowDefaultUI</code></dt>
 <dd>Um {{jsxref("Boolean")}} indicando se a interface padrão do usuário deve ser mostrada. Isso não é implementado no Mozilla.</dd>
 <dt><code>aValueArgument</code></dt>
 <dd>Para comandos que requerem um argumento de entrada. É uma {{domxref("DOMString")}} provendo a informação. Por exemplo, <code>insertImage</code> requer uma URL da imagem a ser inserida. Use <code>null</code> se nenhum argumento é necessário.</dd>
</dl>

<h3 id="Comandos">Comandos</h3>

<dl>
 <dt><code>backColor</code></dt>
 <dd>Muda a cor de fundo do documento. No modo <code>styleWithCss</code>, ele afeta a cor de fundo do bloco que contém. Isso requer um valor de {{cssxref("&lt;color&gt;")}} passado como argumento. Observe que o Internet Explorer usa isso para definir a cor do plano de fundo do <strong>texto</strong>.</dd>
 <dt><code>bold</code></dt>
 <dd>Ativa / desativa negrito na seleção ou no ponto de inserção. O Internet Explorer usa a tag {{HTMLElement("strong")}} no lugar de {{HTMLElement("b")}}.</dd>
 <dt><code>ClearAuthenticationCache</code></dt>
 <dd>Limpa todas as credenciais de autenticação do cache.</dd>
 <dt><code>contentReadOnly</code></dt>
 <dd>Torna o documento de conteúdo somente leitura ou editável. Isso requer um valor booleano <code>true</code> / <code>false</code> como argumento. (Não é suportado pelo Internet Explorer.)</dd>
 <dt><code>copy</code></dt>
 <dd>Copia a seleção atual para a área de transferência. As condições para ativar esse comportamento variam de um navegador para outro e evoluíram com o tempo. Verifique a Tabela de {{anch("Compatibilidade entre Browsers")}} para determinar se você pode usar no seu caso.</dd>
 <dt><code>createLink</code></dt>
 <dd>Cria um hiperlink a partir da seleção, mas apenas se houver uma seleção. Requer uma string <a href="/en-US/docs/Archive/Mozilla/URIs_and_URLs">URI</a> como argumento para o <code>href</code> do link.  O URI deve conter pelo menos um único caractere, que pode ser um espaço em branco. (O Internet Explorer criará um link com um valor nulo.)</dd>
 <dt><code>cut</code></dt>
 <dd>Remove a seleção atual e a copia para a área de transferência. Quando esse comportamento é ativado, varia entre os navegadores e suas condições evoluíram com o tempo. Verifique a Tabela de {{anch("Compatibilidade entre Browsers")}} para mais detalhes.</dd>
 <dt><code>decreaseFontSize</code></dt>
 <dd>Adiciona a tag {{HTMLElement("small")}} ao redor da seleção ou no ponto de inserção. (Não é suportado pelo Internet Explorer.)</dd>
 <dt><code>defaultParagraphSeparator</code></dt>
 <dd>Altera o separador de parágrafos usado quando novos parágrafos são criados em regiões de texto editáveis. Veja <a href="/en-US/docs/Web/Guide/HTML/Editable_content#Differences_in_markup_generation">Diferenças na geração de marcação</a> para mais detalhes.</dd>
 <dt><code>delete</code></dt>
 <dd>Exclui o conteúdo da seleção atual.</dd>
 <dt><code>enableAbsolutePositionEditor</code></dt>
 <dd>Habilita ou desabilita a garra que permite mover elementos absolutamente posicionados. Está desabilitado por padrão no Firefox 63 Beta / Dev Edition ({{bug(1449564)}})</dd>
 <dt><code>enableInlineTableEditing</code></dt>
 <dd>Ativa ou desativa os controles de inserção e exclusão de linhas / colunas da tabela. Está desabilitado por padrão no Firefox 63 Beta / Dev Edition ({{bug(1449564)}}).</dd>
 <dt><code>enableObjectResizing</code></dt>
 <dd>Ativa ou desativa as alças de redimensionamento em imagens, tabelas e elementos absolutamente posicionados e outros objetos redimensionáveis. Está desabilitado por padrão no Firefox 63 Beta / Dev Edition ({{bug(1449564)}}).</dd>
 <dt><code>fontName</code></dt>
 <dd>Altera o nome da fonte para a seleção ou no ponto de inserção. Isso requer uma string com o nome da fonte (como <code>"Arial"</code>) como argumento.</dd>
 <dt><code>fontSize</code></dt>
 <dd>Altera o tamanho da fonte para a seleção ou no ponto de inserção. Isso requer um número inteiro de <code>1</code>-<code>7</code> como argumento.</dd>
 <dt><code>foreColor</code></dt>
 <dd>Altera a cor da fonte para a seleção ou no ponto de inserção. Isso requer uma string de cor (hexadecimal) como argumento.</dd>
 <dt><code>formatBlock</code></dt>
 <dd>Adiciona um elemento de nível de bloco HTML ao redor da linha que contém a seleção atual, substituindo o elemento de bloco que contém a linha, se houver (no Firefox,  {{HTMLElement("blockquote")}} é a exceção - envolverá qualquer elemento de bloco que contenha). Requer uma sequência de nome de tag como argumento de valor. Praticamente todos os elementos em nível de bloco podem ser usados. (Internet Explorer e Edge suportam apenas tags de cabeçalho  <code>H1</code><code>H6</code>, <code>ADDRESS</code>, e <code>PRE</code>, que devem estar entre colchetes angulares, como <code>"&lt;H1&gt;"</code>.)</dd>
 <dt><code>forwardDelete</code></dt>
 <dd>Exclui o caractere depois da posição do <a href="http://en.wikipedia.org/wiki/Cursor_%28computers%29">cursor</a>, idêntico a pressionar a tecla Delete em um teclado do Windows.</dd>
 <dt><code>heading</code></dt>
 <dd>Adiciona um elemento de cabeçalho ao redor de uma linha de seleção ou ponto de inserção. Requer uma string com o nome da tag como argumento (ex. <code>"H1"</code>, <code>"H6"</code>). (Não suportado pelo Internet Explorer e Safari.)</dd>
 <dt><code>hiliteColor</code></dt>
 <dd>Altera a cor do plano de fundo para a seleção ou no ponto de inserção. Requer uma sequência de valores de cores como argumento. <code>useCSS</code> tem de ser <code>true</code> para essa função. (Não é suportado pelo Internet Explorer.)</dd>
 <dt><code>increaseFontSize</code></dt>
 <dd>Adiciona uma tag {{HTMLElement("big")}} ao redor da seleção ou no ponto de inserção. (Não é suportado pelo Internet Explorer.)</dd>
 <dt><code>indent</code></dt>
 <dd>Recua a linha que contém o ponto de seleção ou inserção. No Firefox, se a seleção abranger várias linhas em diferentes níveis de recuo, apenas as linhas menos recuadas na seleção serão recuadas.</dd>
 <dt><code>insertBrOnReturn</code></dt>
 <dd>Controla se a tecla Enter insere um elemento {{HTMLElement("br")}}, ou divide o elemento do bloco atual em dois. (Não é suportado pelo Internet Explorer.)</dd>
 <dt><code>insertHorizontalRule</code></dt>
 <dd>Insere um elemento {{HTMLElement("hr")}} no ponto de inserção ou substitui a seleção por ele.</dd>
 <dt><code>insertHTML</code></dt>
 <dd>Insere uma string HTML no ponto de inserção (exclui a seleção). Requer uma string HTML válida como argumento. (Não é suportado pelo Internet Explorer.)</dd>
 <dt><code>insertImage</code></dt>
 <dd>Insere uma imagem no ponto de inserção (exclui a seleção). Requer uma string de URL para o <code>src</code> da imagem como argumento. Os requisitos para essa string são os mesmos que <code>createLink</code>.</dd>
 <dt><code>insertOrderedList</code></dt>
 <dd>Cria uma <a href="/en-US/docs/Web/HTML/Element/ol">lista ordenada e numerada</a> para a seleção ou no ponto de inserção.</dd>
 <dt><code>insertUnorderedList</code></dt>
 <dd>Cria uma <a href="/en-US/docs/Web/HTML/Element/ul">lista não ordenada</a> para a seleção ou no ponto de inserção.</dd>
 <dt><code>insertParagraph</code></dt>
 <dd>Insere um <a href="/en-US/docs/Web/HTML/Element/p">parágrafo</a> ao redor da seleção ou da linha atual. (O Internet Explorer insere um parágrafo no ponto de inserção e exclui a seleção.)</dd>
 <dt><code>insertText</code></dt>
 <dd>Insere o texto fornecido no ponto de inserção (exclui a seleção).</dd>
 <dt><code>italic</code></dt>
 <dd>Ativa / desativa o itálico para a seleção ou no ponto de inserção. (O Internet Explorer usa o elemento {{HTMLElement("em")}} no lugar de {{HTMLElement("i")}}.)</dd>
 <dt><code>justifyCenter</code></dt>
 <dd>Centraliza o ponto de seleção ou inserção.</dd>
 <dt><code>justifyFull</code></dt>
 <dd>Justifica o ponto de seleção ou inserção.</dd>
 <dt><code>justifyLeft</code></dt>
 <dd>Justifica o ponto de seleção ou inserção à esquerda.</dd>
 <dt><code>justifyRight</code></dt>
 <dd>Justifica à direita a seleção ou o ponto de inserção.</dd>
 <dt><code>outdent</code></dt>
 <dd>Supera a linha que contém o ponto de seleção ou inserção.</dd>
 <dt><code>paste</code></dt>
 <dd>Cola o conteúdo da área de transferência no ponto de inserção (substitui a seleção atual). Desativado para conteúdo da web. Veja [1].</dd>
 <dt><code>redo</code></dt>
 <dd>Refaz o comando desfazer anterior.</dd>
 <dt><code>removeFormat</code></dt>
 <dd>Remove toda a formatação da seleção atual.</dd>
 <dt><code>selectAll</code></dt>
 <dd>Seleciona todo o conteúdo da região editável.</dd>
 <dt><code>strikeThrough</code></dt>
 <dd>Ativa / desativa o strikethrough(linha riscada) para a seleção ou no ponto de inserção.</dd>
 <dt><code>subscript</code></dt>
 <dd>Ativa / desativa o <a href="/en-US/docs/Web/HTML/Element/sub">subscrito</a> para a seleção ou no ponto de inserção.</dd>
 <dt><code>superscript</code></dt>
 <dd>Ativa / desativa o <a href="/en-US/docs/Web/HTML/Element/sup">superscript</a> para a seleção ou no ponto de inserção.</dd>
 <dt><code>underline</code></dt>
 <dd>Ativa / desativa o <a href="/en-US/docs/Web/HTML/Element/u">underline</a> para a seleção ou no ponto de inserção.</dd>
 <dt><code>undo</code></dt>
 <dd>Desfaz o último comando executado.</dd>
 <dt><code>unlink</code></dt>
 <dd>Remove o elemento <a href="/en-US/docs/Web/HTML/Element/a">âncora</a> de um hiperlink selecionado.</dd>
 <dt><code>useCSS</code> {{Deprecated_inline}}</dt>
 <dd>Alterna o uso de tags HTML ou CSS para a marcação gerada. Requer um booleano <code>true</code> / <code>false</code> como argumento.</dd>
 <dd><br>
 NOTA: Este argumento é logicamente reverso (ou seja, use <code>false</code> para usar CSS, <code>true</code> para usar HTML) e não é suportado pelo Internet Explorer. Isso foi preterido em favor do <code>styleWithCSS</code>.</dd>
 <dt><code>styleWithCSS</code></dt>
 <dd>Substitui o comando <code>useCSS</code>. <code>true</code> modifica / gera atributos de <code>style</code> na marcação, <code>false</code> gera elementos de apresentação(html).</dd>
 <dd></dd>
</dl>

<h2 id="Exemplo">Exemplo</h2>

<p>Um exemplo de <a href="https://codepen.io/chrisdavidmills/full/gzYjag/">como usar a funcionalidade</a> no CodePen.</p>

<h2 id="Especificações">Especificações</h2>

<table class="spectable standard-table">
 <tbody>
  <tr>
   <th scope="col">Especificação</th>
   <th scope="col">Estado</th>
   <th scope="col">Comentário</th>
  </tr>
  <tr>
   <td><a href="https://w3c.github.io/editing/execCommand.html#execcommand()">execCommand</a></td>
   <td></td>
   <td></td>
  </tr>
 </tbody>
</table>

<h2 id="Compatibilidade_entre_Browsers">Compatibilidade entre Browsers</h2>

<div class="hidden">A tabela de compatibilidade nesta página é gerada a partir de dados estruturados. Se você deseja contribuir com os dados, consulte <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> e envie-nos uma solicitação de recebimento.</div>

<p>{{Compat("api.Document.execCommand")}}</p>

<h2 id="Veja_também">Veja também</h2>

<ul>
 <li>{{domxref("HTMLElement.contentEditable")}}</li>
 <li>{{domxref("document.designMode")}}</li>
 <li><a href="/en-US/docs/Rich-Text_Editing_in_Mozilla">Edição de Rich-Text com Mozilla</a></li>
 <li><a href="https://github.com/guardian/scribe/blob/master/BROWSERINCONSISTENCIES.md">Scribe: documentação sobre inconsitencias entre browsers</a> com bugs relacionados a <code>document.execCommand</code>.</li>
</ul>