Document.execCommand()
Quando um documento HTML está em designMode
, seu objeto document
expõe um metodo execCommand
para editar a região editável corrente, algo como elementos form inputs ou contentEditable
.
A maioria dos comandos afetam apenas uma área selecionada [seleção] (negrito, itálico, etc.), enquantos outros adicionam novos elementos (adicionar um link por exemplo), ou afetam uma linha toda (identação). Quando usando contentEditable
, o metódo execCommand()
afeta o elemento editável ativo.
Síntaxe
document.execCommand(aCommandName, aShowDefaultUI, aValueArgument)
Valor de Retorno
Um Boolean
que tem valor false
se o comando não é válido ou está desabilitado.
Nota:
Retorna true
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.
Parâmetros
aCommandName
-
Uma
DOMString
especificando o nome do comando a ser executado. Veja Comandos para um lista dos possíveis comandos. aShowDefaultUI
-
Um
Boolean
indicando se a interface padrão do usuário deve ser mostrada. Isso não é implementado no Mozilla. aValueArgument
-
Para comandos que requerem um argumento de entrada. É uma
DOMString
provendo a informação. Por exemplo,insertImage
requer uma URL da imagem a ser inserida. Usenull
se nenhum argumento é necessário.
Comandos
backColor
-
Muda a cor de fundo do documento. No modo
styleWithCss
, ele afeta a cor de fundo do bloco que contém. Isso requer um valor de<color>
passado como argumento. Observe que o Internet Explorer usa isso para definir a cor do plano de fundo do texto. bold
-
Ativa / desativa negrito na seleção ou no ponto de inserção. O Internet Explorer usa a tag
<strong>
no lugar de<b>
. ClearAuthenticationCache
-
Limpa todas as credenciais de autenticação do cache.
contentReadOnly
-
Torna o documento de conteúdo somente leitura ou editável. Isso requer um valor booleano
true
/false
como argumento. (Não é suportado pelo Internet Explorer.) copy
-
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 Compatibilidade entre Browsers para determinar se você pode usar no seu caso.
createLink
-
Cria um hiperlink a partir da seleção, mas apenas se houver uma seleção. Requer uma string URI como argumento para o
href
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.) cut
-
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 Compatibilidade entre Browsers para mais detalhes.
decreaseFontSize
-
Adiciona a tag
<small>
ao redor da seleção ou no ponto de inserção. (Não é suportado pelo Internet Explorer.) defaultParagraphSeparator
-
Altera o separador de parágrafos usado quando novos parágrafos são criados em regiões de texto editáveis. Veja Diferenças na geração de marcação para mais detalhes.
delete
-
Exclui o conteúdo da seleção atual.
enableAbsolutePositionEditor
-
Habilita ou desabilita a garra que permite mover elementos absolutamente posicionados. Está desabilitado por padrão no Firefox 63 Beta / Dev Edition (Erro do Firefox 1449564)
enableInlineTableEditing
-
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 (Erro do Firefox 1449564).
enableObjectResizing
-
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 (Erro do Firefox 1449564).
fontName
-
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
"Arial"
) como argumento. fontSize
-
Altera o tamanho da fonte para a seleção ou no ponto de inserção. Isso requer um número inteiro de
1
-7
como argumento. foreColor
-
Altera a cor da fonte para a seleção ou no ponto de inserção. Isso requer uma string de cor (hexadecimal) como argumento.
formatBlock
-
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,
<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çalhoH1
–H6
,ADDRESS
, ePRE
, que devem estar entre colchetes angulares, como"<H1>"
.) forwardDelete
-
Exclui o caractere depois da posição do cursor, idêntico a pressionar a tecla Delete em um teclado do Windows.
heading
-
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.
"H1"
,"H6"
). (Não suportado pelo Internet Explorer e Safari.) hiliteColor
-
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.
useCSS
tem de sertrue
para essa função. (Não é suportado pelo Internet Explorer.) increaseFontSize
-
Adiciona uma tag
<big>
ao redor da seleção ou no ponto de inserção. (Não é suportado pelo Internet Explorer.) indent
-
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.
insertBrOnReturn
-
Controla se a tecla Enter insere um elemento
<br>
, ou divide o elemento do bloco atual em dois. (Não é suportado pelo Internet Explorer.) insertHorizontalRule
-
Insere um elemento
<hr>
no ponto de inserção ou substitui a seleção por ele. insertHTML
-
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.)
insertImage
-
Insere uma imagem no ponto de inserção (exclui a seleção). Requer uma string de URL para o
src
da imagem como argumento. Os requisitos para essa string são os mesmos quecreateLink
. insertOrderedList
-
Cria uma lista ordenada e numerada para a seleção ou no ponto de inserção.
insertUnorderedList
-
Cria uma lista não ordenada para a seleção ou no ponto de inserção.
insertParagraph
-
Insere um parágrafo 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.)
insertText
-
Insere o texto fornecido no ponto de inserção (exclui a seleção).
italic
-
Ativa / desativa o itálico para a seleção ou no ponto de inserção. (O Internet Explorer usa o elemento
<em>
no lugar de<i>
.) justifyCenter
-
Centraliza o ponto de seleção ou inserção.
justifyFull
-
Justifica o ponto de seleção ou inserção.
justifyLeft
-
Justifica o ponto de seleção ou inserção à esquerda.
justifyRight
-
Justifica à direita a seleção ou o ponto de inserção.
outdent
-
Supera a linha que contém o ponto de seleção ou inserção.
paste
-
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].
redo
-
Refaz o comando desfazer anterior.
removeFormat
-
Remove toda a formatação da seleção atual.
selectAll
-
Seleciona todo o conteúdo da região editável.
strikeThrough
-
Ativa / desativa o strikethrough(linha riscada) para a seleção ou no ponto de inserção.
subscript
-
Ativa / desativa o subscrito para a seleção ou no ponto de inserção.
superscript
-
Ativa / desativa o superscript para a seleção ou no ponto de inserção.
underline
-
Ativa / desativa o underline para a seleção ou no ponto de inserção.
undo
-
Desfaz o último comando executado.
unlink
-
Remove o elemento âncora de um hiperlink selecionado.
useCSS
Deprecated-
Alterna o uso de tags HTML ou CSS para a marcação gerada. Requer um booleano
true
/false
como argumento.NOTA: Este argumento é logicamente reverso (ou seja, use
false
para usar CSS,true
para usar HTML) e não é suportado pelo Internet Explorer. Isso foi preterido em favor dostyleWithCSS
. styleWithCSS
-
Substitui o comando
useCSS
.true
modifica / gera atributos destyle
na marcação,false
gera elementos de apresentação(html).
Exemplo
Um exemplo de como usar a funcionalidade no CodePen.
Especificações
Especificação | Estado | Comentário |
---|---|---|
execCommand |
Compatibilidade com navegadores
BCD tables only load in the browser
Veja também
HTMLElement.contentEditable
document.designMode
- Edição de Rich-Text com Mozilla
- Scribe: documentação sobre inconsitencias entre browsers com bugs relacionados a
document.execCommand
.