React Academy · Aula

Entradas não controladas com useRef

Acesse valores de entrada do DOM por meio de refs em vez de estado para cenários simples de formulários.

Entradas não controladas com useRef é uma aula grátis de React Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de React Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de React Academy inclui 4 aulas no total.

Boas-vindas

Nesta lição, você usará campos não controlados com useRef para acessar valores de campos DOM sem gerenciá-los no estado do React.

Controlados e não controlados

Um **campo controlado** tem seu valor definido pelo estado do React (value + onChange). Um **campo não controlado** gerencia seu próprio valor no DOM; o React o lê por meio de uma referência somente quando necessário.

// Controlled
<input value={name} onChange={e => setName(e.target.value)} />

// Uncontrolled
const nameRef = useRef();
<input ref={nameRef} defaultValue="" />

Lendo o valor ao enviar

Com campos não controlados, leia o valor quando o usuário enviar o formulário, acessando `ref.current.value`. Nenhuma atualização de estado ocorre enquanto o usuário digita.

function Form() {
  const nameRef = useRef();
  const handleSubmit = (e) => {
    e.preventDefault();
    console.log(nameRef.current.value);
  };
  return (
    <form onSubmit={handleSubmit}>
      <input ref={nameRef} />
      <button type="submit">Submit</button>
    </form>
  );
}

defaultValue versus value

Para campos não controlados, use `defaultValue` (não `value`) para definir o valor inicial. Definir `value` sem `onChange` faz o React emitir um aviso e o campo se torna somente leitura.

<input ref={nameRef} defaultValue="Initial text" />

Quando usar campos não controlados

Campos não controlados são úteis para: formulários simples em que você só precisa dos valores ao enviar, campos de arquivo (que não podem ser controlados pelo React) e campos essenciais para o desempenho, nos quais é importante evitar novas renderizações.

Redefinindo um campo não controlado

Para redefinir um campo não controlado, defina `ref.current.value = ''` de forma imperativa. Ou altere a propriedade `key` do componente para forçar o React a montá-lo novamente com um novo nó DOM.

// Reset imperatively
nameRef.current.value = '';

// Or remount
setFormKey(k => k + 1);
<input key={formKey} ref={nameRef} />

Várias referências para vários campos

Em formulários com vários campos não controlados, crie uma referência separada para cada campo. Acesse `.current.value` de cada referência ao enviar o formulário.

const emailRef = useRef();
const passwordRef = useRef();

<input ref={emailRef} type="email" />
<input ref={passwordRef} type="password" />

Focando durante a montagem

useRef é frequentemente usado para focar automaticamente um campo quando um componente é montado. Leia a referência dentro de useEffect depois da montagem.

const inputRef = useRef();
useEffect(() => {
  inputRef.current?.focus();
}, []);
<input ref={inputRef} />

Campos não controlados e validação

Validar campos não controlados exige ler os valores de forma imperativa ao enviar o formulário. Isso é mais confuso que usar campos controlados para validação em tempo real. Prefira campos controlados quando precisar de feedback imediato.

A concessão de useRef

Campos não controlados evitam novas renderizações, mas abrem mão da reatividade do React. Não é possível renderizar condicionalmente com base no valor do campo em tempo real sem ler a referência e atualizar o estado manualmente.

Verificação rápida

Qual propriedade você deve usar para definir um valor inicial para um campo não controlado no React?

Recapitulação

Campos não controlados usam referências para ler valores quando necessário. Use defaultValue para definir valores iniciais, leia ref.current.value ao enviar o formulário e redefina limpando o valor da referência ou alterando a propriedade key.

Próxima etapa

Próxima lição: **Campo de arquivo e leitura de dados de arquivo** — você manipulará campos de arquivo e lerá metadados e dados de imagens com FileReader.

Perguntas Frequentes

A aula “Entradas não controladas com useRef” é grátis?

Sim — o texto completo de “Entradas não controladas com useRef” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de React Academy, atualize para CoddyKit PRO. O curso de React Academy inclui 4 aulas no total.

O que vou aprender em “Entradas não controladas com useRef”?

Acesse valores de entrada do DOM por meio de refs em vez de estado para cenários simples de formulários. Você pratica React Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar React Academy?

Nenhuma experiência prévia é necessária. React Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Entradas não controladas com useRef”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de React Academy?

Sim. Cada aula de React Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Entradas não controladas com useRef
Entrada de arquivo e leitura de dados de arquivos
Interface de envio de arquivos por arrastar e soltar
Carregando arquivos para uma API de back-end

← Voltar para React Academy