Propriedades e Métodos de Formulários em JavaScript

Introdução ao Tratamento de Formulários em JavaScript

Os formulários são a principal forma de os utilizadores enviarem dados para uma página web, por isso aceder aos seus controlos de forma confiável a partir do JavaScript é uma competência essencial. O DOM expõe os formulários e os campos neles contidos através de um conjunto de coleções dedicadas (document.forms, form.elements) e propriedades (input.value, checkbox.checked, select.value), além de alguns métodos imperativos (submit(), reset(), focus()).

Este capítulo aborda como aceder a formulários e controlos, ler e escrever os seus valores, reagir à entrada do utilizador com os eventos input e change, e acionar ações comuns de forma programática. Para uma visão mais ampla sobre onde os formulários se encontram na árvore do documento, consulte Trabalhando com formulários no DOM.

Acedendo a Formulários e aos Seus Controlos

`document.forms` e `form.elements`

Todos os formulários de uma página estão disponíveis através de document.forms. Esta é uma coleção especial que pode ser indexada por número (document.forms[0]) ou, de forma mais legível, pelo atributo name do formulário (document.forms.loginForm ou document.forms['loginForm']).

Depois de ter um formulário, form.elements fornece os seus controlos nomeados da mesma forma — por índice ou pelo name do controlo. O acesso por nome é o estilo recomendado, pois continua a funcionar mesmo quando se adicionam ou reordenam campos:

const form = document.forms.loginForm;     // a <form name="loginForm">
const userField = form.elements.username;  // an <input name="username">
// Shortcut: named controls are also exposed directly on the form
const samePassword = form.password;        // <input name="password">

Quando vários controlos partilham um name (botões de rádio), form.elements.name retorna uma RadioNodeList — uma coleção cujo .value é o valor do botão atualmente selecionado. Um <fieldset> também possui a sua própria coleção elements, por isso é possível tratar uma secção agrupada como um mini-formulário.

Aqui está um exemplo completo que acede a um formulário e aos seus campos:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <title>JavaScript Form Example</title>
</head>
<body>
    <form name="loginForm">
        <input type="text" name="username" placeholder="Username" />
        <input type="password" name="password" placeholder="Password" />
        <input type="submit" value="Login" />
    </form>
    <div style="margin-top:15px;" id="output"></div>

    <script>
        const form = document.forms['loginForm'];
        const username = form.elements['username'];
        const password = form.elements['password'];
        form.onsubmit = function(event) {
            const output = document.getElementById('output');
            output.textContent = 'Username: ' + username.value + ' Password: ' + password.value;
            event.preventDefault(); // Prevent form submission
        }
    </script>
</body>
</html>

Experimente Você Mesmo »

Este script intercepta o envio do formulário, exibe o nome de utilizador e a palavra-passe numa div da página, e impede que o formulário seja enviado para um servidor.

Lendo e Escrevendo Valores dos Controlos

Cada tipo de controlo expõe o seu estado atual através de uma propriedade ligeiramente diferente — saber qual ler é metade do trabalho:

Controlo	Ler / escrever com	Notas
`text`, `password`, `email`, `textarea`	`.value`	Sempre uma string
`checkbox`	`.checked` (boolean)	`.value` é o valor do atributo, não se está marcado
`radio` (grupo)	`form.elements.groupName.value`	Valor do botão marcado, ou `""`
`<select>`	`.value`	Valor da `<option>` selecionada; `.options[i]` e `.selectedIndex` oferecem acesso mais preciso

input.value = 'hello';            // text-like fields
checkbox.checked = true;          // tick a checkbox
select.value = 'medium';          // selects the matching <option>
const chosen = select.options[select.selectedIndex].text; // visible label

Um erro comum para iniciantes é ler checkbox.value para saber se uma caixa está marcada — isso retorna a string do atributo estático ("on" por padrão), não o estado de marcação. Em vez disso, use .checked.

Trabalhando com Valores de Input

Manipular valores de input é simples em JavaScript. Veja como definir valores de input dinamicamente e exibi-los na sua página web:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <title>Input Value Example</title>
</head>
<body>
    <form name="userForm">
        <input type="text" name="firstName" placeholder="First Name" />
        <input type="text" name="lastName" placeholder="Last Name" />
        <input type="submit" value="Submit" />
    </form>
    <div id="welcomeMessage"></div>

    <script>
        const form = document.forms['userForm'];
        const firstName = form.elements['firstName'];
        const lastName = form.elements['lastName'];
        firstName.value = 'John';
        lastName.value = 'Doe';

        form.onsubmit = function(event) {
            const welcomeMessage = document.getElementById('welcomeMessage');
            welcomeMessage.textContent = 'Hello, ' + firstName.value + ' ' + lastName.value + '!';
            event.preventDefault(); // Prevents the form from submitting to a server
        }
    </script>
</body>
</html>

Experimente Você Mesmo »

Neste exemplo, o nome e o apelido são predefinidos como 'John' e 'Doe', respetivamente. Quando o formulário é submetido, é exibida uma saudação na página, demonstrando tanto a definição como a recuperação de valores de input. Para formulários mais complexos, considere a API FormData para serializar facilmente os dados do formulário em pares chave-valor sem aceder manualmente a cada elemento.

Técnicas Avançadas de Formulários

Validação de Formulários

A validação de formulários em tempo real é fundamental para a experiência do utilizador. Aqui está um exemplo de como validar um endereço de email antes do envio do formulário. Note que a validação de email do HTML5 é básica e muitas vezes complementada por regex personalizado ou bibliotecas para produção, pois pode aceitar incorretamente endereços incompletos como 'w3docs@gmail' (Se quiser saber como corrigir isso, pode ler JavaScript Validation API):

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <title>Form Validation Example</title>
</head>
<body>
    <form name="registrationForm">
        <input type="email" name="email" placeholder="Enter your email" required />
        <input type="submit" value="Register" />
    </form>
    <div id="message"></div>

    <script>
        const form = document.forms['registrationForm'];
        const email = form.elements['email'];

        form.onsubmit = function(event) {
            // Note: HTML5 email validation is basic and often supplemented by custom regex or libraries for production.
            // It may incorrectly accept incomplete addresses like 'w3docs@gmail'.
            if (!email.checkValidity()) {
                document.getElementById('message').textContent = "Please enter a valid email address.";
                event.preventDefault();
                return;
            }
            document.getElementById('message').textContent = "Registration successful!";
            event.preventDefault(); // Prevents actual form submission
        }
    </script>
</body>
</html>

Experimente Você Mesmo »

Neste script, o formulário valida o input de email no momento do envio. Exibe uma mensagem indicando se o registo foi bem-sucedido ou se há um erro, tudo sem enviar dados para um servidor. Este exemplo também destaca uma limitação da validação de email do HTML5, que não garante totalmente os formatos corretos de domínio.

Reagindo aos Eventos `input` e `change`

Dois eventos cobrem a maioria das interações com formulários:

input dispara a cada tecla pressionada ou alteração de valor — ideal para pré-visualizações em tempo real, contadores de caracteres e validação durante a digitação.
change dispara apenas uma vez quando o utilizador confirma uma alteração: quando um campo de texto perde o foco após edição, ou imediatamente quando um checkbox, rádio ou <select> é alterado. Use-o quando reagir a cada tecla seria desnecessário.

search.addEventListener('input', () => console.log(search.value)); // every keystroke
country.addEventListener('change', () => console.log(country.value)); // on selection

O próximo exemplo usa input para mostrar uma contagem de caracteres em tempo real enquanto o utilizador escreve:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Input Event Example</title>
</head>
<body>
  <form name="bioForm">
    <textarea name="bio" maxlength="100" placeholder="Tell us about yourself"></textarea>
  </form>
  <div id="counter">0 / 100</div>

  <script>
    const bio = document.forms.bioForm.elements.bio;
    const counter = document.getElementById('counter');
    bio.addEventListener('input', function () {
      counter.textContent = bio.value.length + ' / 100';
    });
  </script>
</body>
</html>

Para os mecanismos mais aprofundados do envio — incluindo a diferença entre o evento submit e o método form.submit() — consulte Formulários: evento e método submit.

Métodos de Formulários: `submit()`, `reset()` e `focus()`

Os formulários e os controlos também oferecem métodos imperativos:

form.submit() envia o formulário de forma programática. Atenção importante: ele não dispara o evento submit, por isso qualquer validação associada a esse evento é ignorada. Prefira form.requestSubmit() quando precisar que a validação e o evento sejam executados.
form.reset() restaura todos os controlos ao seu valor inicial.
element.focus() move o cursor do teclado para um controlo — ideal para destacar o primeiro campo inválido. O seu correspondente é blur(). Consulte Foco: focus / blur para mais detalhes.

const form = document.forms.signup;
if (!form.email.value) {
  form.email.focus();   // send the user straight to the empty field
} else {
  form.requestSubmit(); // submit AND run the submit event + validation
}
form.reset();           // clear the form back to defaults

Tratando Eventos de Formulários

Aqui está como pode tratar eventos de formulários dinamicamente:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Form Events Example</title>
  </head>
  <body>
    <div style="display: flex; justify-content: center; align-items: center">
      <form
        style="display: flex; flex-direction: column; gap: 5px"
        name="contactForm"
      >
        <input type="text" name="fullName" placeholder="Full Name" required />
        <textarea name="message" placeholder="Your Message"></textarea>
        <input type="submit" value="Send" />
      </form>
    </div>
    <div
      style="display: flex; justify-content: center; align-items: center"
      id="confirmation"
    ></div>

    <script>
      const form = document.forms["contactForm"];

      form.onsubmit = function (event) {
        const name = form.elements["fullName"].value;
        const message = form.elements["message"].value;
        document.getElementById("confirmation").textContent =
          "Thank you, " + name + ", we received your message!";
        event.preventDefault(); // Prevents form from submitting to a server
      };
    </script>
  </body>
</html>

Experimente Você Mesmo »

Este exemplo fornece feedback imediato ao utilizador, exibindo uma mensagem de confirmação quando o formulário é submetido. Demonstra de forma eficaz como o JavaScript pode gerir eventos de formulários para melhorar a interação sem comunicação com o servidor.

Conclusão

Dominar as propriedades e métodos de formulários em JavaScript melhora a funcionalidade e a interação do utilizador em aplicações web. Aceda aos formulários através de document.forms, endereça os seus controlos por nome com form.elements, leia o estado com a propriedade correta (value, checked, selectedIndex), responda aos eventos input e change, e controle o formulário com submit(), reset() e focus().

Para ir mais longe, continue com estes capítulos relacionados:

Prática

Quais das seguintes afirmações são verdadeiras em relação aos formulários JavaScript e aos seus métodos?

A coleção `document.forms` permite o acesso a formulários no documento usando tanto o nome como o índice numérico.Usando `form.elements`, é possível aceder a elementos individuais num formulário usando o seu atributo name.`form.submit()` aciona o evento submit do formulário e é usado para validar os dados do formulário antes de enviá-los ao servidor.O elemento `fieldset` num formulário funciona como um subformulário e contém a sua própria propriedade `elements`.Alterar o atributo name de um elemento input via JavaScript atualiza imediatamente a coleção `form.elements` para refletir o novo nome.

Introdução ao Tratamento de Formulários em JavaScript

Acedendo a Formulários e aos Seus Controlos

document.forms e form.elements

Lendo e Escrevendo Valores dos Controlos

Trabalhando com Valores de Input

Técnicas Avançadas de Formulários

Validação de Formulários

Reagindo aos Eventos input e change

Métodos de Formulários: submit(), reset() e focus()

Tratando Eventos de Formulários

Conclusão

Prática

`document.forms` e `form.elements`

Reagindo aos Eventos `input` e `change`

Métodos de Formulários: `submit()`, `reset()` e `focus()`