HTMLInputElement

A interface HTMLInputElement fornece propriedades e métodos especiais para manipular as opções, layout e apresentação de elementos <input>.

EventTarget Node Element HTMLElement HTMLInputElement

Propriedades da instância

Algumas propriedades se aplicam apenas a tipos de elemento de entrada que suportam os atributos correspondentes.

align Deprecated

string: Representa o alinhamento do elemento. Em vez disso, use CSS.

autocapitalize Experimental

string: Define o comportamento de capitalização para a entrada do usuário. Os valores válidos são none, off, characters, words ou sentences.

defaultValue

string: Retorna / Define o valor padrão como originalmente especificado no HTML que criou este objeto.

dirName

string: Retorna / Define a direcionalidade do elemento.

inputmode

Fornece uma dica aos navegadores quanto ao tipo de configuração do teclado virtual a ser usado ao editar este elemento ou seu conteúdo.

labels Somente leitura

NodeList array: Retorna uma lista de elementos <label> que são rótulos para este elemento.

list Somente leitura

HTMLElement: Retorna o elemento apontado pelo atributo list. A propriedade pode ser null se nenhum elemento HTML for encontrado na mesma árvore.

multiple

boolean: Retorna / Define o atributo multiple do elemento, indicando se mais de um valor é possível (ex. , vários arquivos).

name

string: Retorna / Define o atributo name do elemento, contendo um nome que identifica o elemento ao enviar o formulário.

step

string: Retorna / Define o atributo step do elemento, que funciona com min e max para limitar os incrementos nos quais um número ou data - valor de tempo pode ser definido. Pode ser a string any ou um número de ponto flutuante positivo. Se isso não for definido como any, o controle aceitará apenas valores em múltiplos do valor da etapa maior que o mínimo.

type

string: Retorna / Define o atributo type do elemento, indicando o tipo de controle a ser exibido. Para valores possíveis, consulte a documentação do atributo type.

useMap Deprecated

string: Representa um mapa de imagem do lado do cliente.

value

string: Retorna / Define o valor atual do controle. Se o usuário inserir um valor diferente do valor esperado, isso pode retornar uma string vazia.

valueAsDate

Date: Retorna / Define o valor do elemento, interpretado como uma data, ou null se a conversão não for possível.

valueAsNumber

double: Retorna o valor do elemento, interpretado como um dos seguintes, em ordem: Um valor de tempo, um número ou NaN se a conversão for impossível

Propriedades de instância relacionadas ao formulário pai

form Somente leitura

HTMLFormElement: Retorna uma referência ao elemento pai <form>.

formAction

string: Retorna / Define o atributo formaction do elemento, contendo a URL de um programa que processa as informações enviadas pelo elemento. Isso substitui o atributo action do formulário pai.

formEnctype

string: Retorna / Define o atributo formenctype do elemento, contendo o tipo de conteúdo que é usado para enviar o formulário para o servidor. Isso substitui o atributo enctype do formulário pai.

formMethod

string: Retorna / Define o atributo formmethod do elemento, contendo o método HTTP que o navegador usa para enviar a forma. Isso substitui o atributo method do formulário pai.

formNoValidate

boolean: Retorna / Define o atributo formnovalidate do elemento, indicando que o formulário não deve ser validado quando ele é submetido. Isso substitui o atributo novalidate do formulário pai.

formTarget

string: Retorna / Define o atributo formtarget do elemento, contendo um nome ou palavra-chave indicando onde exibir o resposta recebida após o envio do formulário. Isso substitui o atributo target do formulário pai.

Propriedades de instância que se aplicam a qualquer tipo de elemento de entrada que não esteja oculto

autofocus

boolean: Retorna / Define o atributo autofocus do elemento, que especifica que um controle de formulário deve ter foco de entrada quando a página é carregada, a menos que o usuário a substitua, por exemplo, digitando um controle diferente. Apenas um elemento de formulário em um documento pode ter o atributo autofocus.

disabled

boolean: Retorna / Define o atributo disabled do elemento, indicando que o controle não está disponível para interação. Os valores de entrada não serão enviados com o formulário. Veja também readonly.

required

boolean: Retorna / Define o atributo required do elemento, indicando que o usuário deve preencher um valor antes de enviar um formulário.

validationMessage Somente leitura

string: Retorna uma mensagem localizada que descreve as restrições de validação que o controle não atende (se houver). Esta é a string vazia se o controle não for um candidato para validação de restrição (willValidate é false), ou se satisfizer suas restrições. Este valor pode ser definido pelo método setCustomValidity().

validity Somente leitura

ValidityState: Retorna o estado de validade atual do elemento.

willValidate Somente leitura

boolean: Retorna se o elemento é um candidato para validação de restrição. É false se alguma condição o impedir de validação de restrição, incluindo: seu type é um dos hidden, reset ou button, tem um ancestral <datalist> ou sua propriedade disabled é true.

Propriedades de instância que se aplicam apenas a elementos do tipo caixa de seleção ou rádio

checked

boolean: Retorna / Define o estado atual do elemento.

defaultChecked

boolean: Retorna / Define o estado padrão de um botão de rádio ou caixa de seleção conforme originalmente especificado no HTML que criou este objeto.

indeterminate

boolean: Retorna se a caixa de seleção ou o botão de opção está em estado indeterminado. Para caixas de seleção, o efeito é que a aparência da caixa de seleção é obscurecida/acinzentada de alguma forma para indicar que seu estado é indeterminado (não marcado, mas não desmarcado). Não afeta o valor do atributo checked, e clicar na caixa de seleção definirá o valor como falso.

Propriedades de instância que se aplicam apenas a elementos do tipo imagem

alt

string: Retorna / Define o atributo alt do elemento, contendo texto alternativo a ser usado.

height

string: Retorna / Define o atributo height do elemento, que define a altura da imagem exibida para o botão.

src

string: Retorna / Define o atributo src do elemento, que especifica um URI para a localização de uma imagem para exibir no botão gráfico de envio.

width

string: Retorna / Define o atributo width do elemento, que define a largura da imagem exibida para o botão.

Propriedades de instância que se aplicam apenas a elementos do tipo arquivo

accept

string: Retorna / Define o atributo accept do elemento, contendo uma lista separada por vírgulas de tipos de arquivos que podem ser selecionado.

allowdirs Non-standard

boolean: Parte da API de upload de diretório não padrão. Indica se permite ou não que diretórios e arquivos sejam selecionados na lista de arquivos. Implementado apenas no Firefox e está oculto atrás de uma preferência.

files

FileList: Retorna / Define uma lista de objetos File representando os arquivos selecionados para upload.

webkitdirectory

boolean: Retorna o atributo webkitdirectory. Se for verdadeiro, a interface do seletor do sistema de arquivos aceita apenas diretórios em vez de arquivos.

webkitEntries

FileSystemEntry array: Descreve os arquivos ou diretórios atualmente selecionados.

Propriedades de instância que se aplicam apenas a elementos visíveis contendo texto ou números

autocomplete

string: Retorna / Define o atributo autocomplete do elemento, indicando se o valor do controle pode ser automaticamente preenchido pelo navegador.

max

string: Retorna / Define o atributo max do elemento, contendo o valor (numérico ou data-hora) máximo para este item, que não deve ser menor que seu valor mínimo (atributo min).

maxLength

unsigned long: Retorna / Define o atributo maxlength do elemento, contendo o número máximo de caracteres (em pontos de código Unicode) que o valor pode ter.

min

string: Retorna / Define o atributo min do elemento, contendo o valor (numérico ou data-hora) mínimo para este item, que não deve ser maior que seu valor máximo (atributo max).

minLength

unsigned long: Retorna / Define o atributo minlength do elemento, contendo o número mínimo de caracteres (em Unicode pontos de código) que o valor pode ter.

pattern

string: Retorna / Define o atributo pattern do elemento, contendo uma expressão regular em que o valor do controle é verificado contra. Use o atributo title para descrever o padrão para ajudar o usuário. Este atributo só se aplica quando o valor do atributo type é text, search, tel, url ou e-mail.

placeholder

string: Retorna / Define o atributo placeholder do elemento, contendo uma dica para o usuário do que pode ser inserido no controle. O texto do espaço reservado não deve conter retornos de carro ou avanços de linha. Este atributo só se aplica quando o valor do atributo type é text, search, tel, url ou e-mail.

readOnly

boolean: Retorna / Define o atributo readonly do elemento, indicando que o usuário não pode modificar o valor do controle. Isso é ignorado se o type for hidden, range, color, checkbox, radio, file, ou um tipo de botão.

selectionEnd

unsigned long: Retorna / Define o índice final do texto selecionado. Quando não há seleção, isso retorna o deslocamento do caractere imediatamente após a posição atual do cursor de entrada de texto.

selectionStart

unsigned long: Retorna / Define o índice inicial do texto selecionado. Quando nada é selecionado, retorna a posição do cursor de entrada de texto (caret) dentro do elemento <input>.

selectionDirection

string: Retorna / Define a direção em que a seleção ocorreu. Os valores possíveis são: forward (a seleção foi realizada na direção de início a fim do local atual), backward (a direção oposta) ou none (a direção é desconhecida).

size

unsigned long: Retorna / Define o atributo size do elemento, contendo o tamanho visual do controle. Este valor está em pixels, a menos que o valor de type seja text ou password, caso em que é um número inteiro indicando o número de caracteres. Aplica-se somente quando type é definido como text, search, tel, url, email ou senha.

Métodos de instância

blur()

Remove o foco do elemento de entrada; as teclas digitadas subsequentemente não irão a lugar nenhum.

click()

Simula um clique no elemento de entrada.

focus()

Foca no elemento de entrada; os pressionamentos de tecla irão posteriormente para este elemento.

select()

Seleciona todo o texto no elemento de entrada e o foca para que o usuário possa substituir posteriormente todo o seu conteúdo.

setSelectionRange()

Seleciona um intervalo de texto no elemento de entrada (mas não o focaliza).

setRangeText()

Substitui um intervalo de texto no elemento de entrada por um novo texto.

setCustomValidity()

Define uma mensagem de validação personalizada para o elemento. Se esta mensagem não for a string vazia, o elemento está sofrendo de um erro de validade personalizado e não é validado.

showPicker()

Mostra um seletor de navegador para data, hora, cor e arquivos.

checkValidity()

Retorna um valor booleano que é false se o elemento for um candidato para validação de restrição e não satisfizer suas restrições. Nesse caso, ele também dispara um evento invalid no elemento. Ele retorna true se o elemento não for um candidato para validação de restrição ou se satisfizer suas restrições.

reportValidity()

Executa o método checkValidity() e, se retornar falso (para uma entrada inválida ou nenhum atributo de padrão fornecido), ele relata ao usuário que a entrada é inválida da mesma maneira como se você enviasse um formulário.

stepDown()

Decrementa o value em (step * n), em que n é padronizado como 1 se não for especificado. Lança uma exceção InvalidStateError:

  • se o método não for aplicável para o valor type atual,
  • se o elemento não tiver valor step,
  • se o value não puder ser convertido em um número,
  • se o valor resultante estiver acima de max ou abaixo de min.
stepUp()

Incrementa o value em (step * n), em que n é padronizado como 1 se não for especificado. Lança uma exceção InvalidStateError:

  • se o método não for aplicável para o valor atual de type,
  • se o elemento não tiver valor step,
  • se o value não puder ser convertido em um número,
  • se o valor resultante estiver acima de max ou abaixo de min.

Eventos

Ouça esses eventos usando addEventListener() ou atribuindo um ouvinte de evento à propriedade oneventname desta interface:

input

Dispara quando o value de um elemento <input>, <select> ou <textarea> foi alterado. Observe que na verdade isso é acionado na interface HTMLElement e também se aplica a elementos contenteditable, mas também listamos aqui porque é mais comumente usado com elementos de entrada de formulário.

invalid

Disparado quando um elemento não satisfaz suas restrições durante a validação da restrição.

Disparado quando uma pesquisa é iniciada em um <input> de type="search".

selectionchange evento Experimental

Dispara quando a seleção de texto em um elemento <input> foi alterada.

Especificações

Specification
HTML Standard
# htmlinputelement

Compatibilidade com navegadores

BCD tables only load in the browser

Veja também

  • Elemento HTML implementando esta interface: <input>