English 中文 العربية 日本語 Português

Controlled Components Componentes Controlados

Última atualização: 2026-11-03

Controlled Components Componentes Controlados

Um componente controlado é aquele cujo valor é conduzido pelo estado do React: o valor é vinculado ao estado e o onChange escreve o novo valor de volta no estado, fechando o ciclo de fluxo de dados em uma única direção com o retorno do evento. É o padrão usado nos formulários React e mantém o valor atual continuamente validável, enviável e capaz de alimentar outros campos sem precisar mexer no DOM de forma imperativa. Como o estado é a única fonte de verdade, um campo controlado pode ser redefinido, pré-preenchido ou conferido com os campos vizinhos a qualquer momento.

GrupoPadrões de Componentes
TipoPadrão

ℹ️ Informação O editor transpila JSX para JavaScript e renderiza a UI real na sandbox; os componentes são montados automaticamente — sem render manual.

📝 Sintaxe

<input
  value={name}                           // state drives the display
  onChange={e => setName(e.target.value)} // typing writes back to state
/>

Retorna：Sem valor de retorno; esta entrada descreve um padrão de codificação e não uma função.

▶ Exemplo

O exemplo roda direto: renderiza automaticamente ao expandir e edições valem na hora.

Saída：

Depois de digitar "Alice" e selecionar "Advanced", a linha abaixo mostra imediatamente "Hello, Alice (Advanced)" — cada tecla digitada atualiza o estado uma vez e a UI renderiza de novo em sincronia.
▶ Experimente

💡 Pontos-chave

💡 Dica value e onChange devem aparecer em par: vincular o value sem onChange trava o campo e impossibilita a digitação.
ℹ️ Informação Uma vez controlado, cada tecla digitada vai parar no estado; assim, validação, botões desabilitados e listas suspensas encadeadas tornam-se derivações puramente funcionais do estado.
⚠️ Aviso Depois que um valor passa a ser controlado, nunca o deixe se tornar undefined; caso contrário, o React reclama sobre a alternância entre controlado e não controlado.
usestate form-inputs form-validation event-handling
Mais casos em breve.

📚 Tutoriais Relacionados

Formulários e Componentes Controlados
Lição 7: o conjunto completo de padrões controlados, do input ao select, além das armadilhas comuns.

❓ Perguntas Frequentes

P Como escolher entre componentes controlados e não controlados?
R Use o controlado quando precisar de validação instantânea, campos encadeados, desativação condicional ou processamento antes do envio; use o não controlado (lendo o valor por meio de um ref) quando só lhe importa o valor no momento do envio. Os formulários React adotam o controlado por padrão.
P O que acontece se eu escrever value mas não onChange?
R O campo de entrada fica somente leitura: o React fixa o valor no valor do estado, as teclas não surtem efeito e o console registra um aviso.
P Cada input precisa do seu próprio useState?
R Com muitos campos, você pode reuní-los em um único estado objeto (atualizado por nome de campo) ou extrair um hook personalizado / useReducer para gerenciá-los em um só lugar.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%