Angular 22: como focar campos com o focusBoundControl

Aprenda a usar o focusBoundControl do Angular 22 para focar campos do Signal Forms sem ViewChild ou ElementRef, inclusive o primeiro inválido.

Share
Angular 22: como focar campos com o focusBoundControl
Angular 22: como focar campos com o focusBoundControl

Quem já precisou focar um campo de formulário programaticamente no Angular conhece bem o roteiro: criar uma referência no template, buscar o elemento com @ViewChild (ou viewChild()), acessar o ElementRef e, finalmente, chamar o nativeElement.focus(). Funciona, mas é muito código para uma tarefa simples, além de nos obrigar a manipular o DOM diretamente.

Com o Signal Forms, que se tornou estável no Angular 22, temos uma forma bem mais elegante de resolver isso: o método focusBoundControl(). Ele foi introduzido na versão 21.1 (ainda em modo experimental) e agora faz parte da API estável do framework.

A ideia é simples: em vez de dizer ao navegador qual elemento deve receber o foco, nós pedimos ao formulário que foque o controle vinculado a um determinado campo. Afinal, o Signal Forms já conhece a estrutura do formulário, então por que percorrer o DOM manualmente?

Neste texto, vou mostrar, passo a passo, como utilizar o focusBoundControl() em alguns cenários comuns do dia a dia.


Vale mencionar que, se você ainda não conhece o Signal Forms, recomendo dar uma olhada no post anterior onde apresento os conceitos básicos dessa nova API:

Angular 21 - Formulários reativos com Signal Forms


Requisitos para replicar o exemplo

Para criar o cenário de estudo utilizei o Angular 22:

# Para conferir a versão do Node.js
# abra o terminal e digite:
node -v

# Para criar o projeto Angular 22
# utilizei o seguinte comando:
#
# Observação: optei em não instalar o CLI
# em modo global.
npx @angular/cli@22 new angular22

Com o projeto criado, basta executar o comando npm start e abrir o navegador no endereço localhost:4200.

Importante: a partir da versão 21.1 a diretiva [field], que utilizei no post anterior, passou a se chamar [formField] (classe FormField). Nos exemplos abaixo já utilizo o nome atual.

Passo 1 - Uso básico do focusBoundControl()

O focusBoundControl() é um método disponível no estado de cada campo do formulário, ou seja, no objeto retornado quando chamamos um campo como função (ex: formularioCliente.email()). Ao ser chamado, o Angular localiza o controle (input, textarea, select ou um controle customizado) vinculado àquele campo via [formField] e move o foco para ele.

Vamos partir de um formulário simples de cadastro de cliente:

import { Component, signal } from '@angular/core';
import {
  email,
  form,
  FormField,
  required,
} from '@angular/forms/signals';

interface Cliente {
  nome: string;
  email: string;
  telefone: string;
}

@Component({
  selector: 'app-root',
  imports: [FormField],
  templateUrl: './app.html'
})
export class App {
  protected readonly cliente = signal<Cliente>({
    nome: '',
    email: '',
    telefone: '',
  });

  protected readonly formularioCliente = form(
    this.cliente,
    (path) => {
      required(path.nome, { message: 'Informe um nome' });
      required(path.email, { message: 'Informe um email' });
      email(path.email, { message: 'Informe um email válido' });
      required(path.telefone, { message: 'Informe um telefone' });
    }
  );

  focarEmail() {
    // Basta chamar o focusBoundControl() no estado do campo
    this.formularioCliente.email().focusBoundControl();
  }
}

app.ts

<h2>Cadastro de Cliente</h2>
<div>
  <input
    [formField]="formularioCliente.nome"
    placeholder="nome..."
    type="text" />
</div>
<div>
  <input
    [formField]="formularioCliente.email"
    placeholder="email..."
    type="email" />
</div>
<div>
  <input
    [formField]="formularioCliente.telefone"
    placeholder="telefone..."
    type="tel" />
</div>

<button type="button" (click)="focarEmail()">
  Focar email
</button>

app.html

Perceba que não foi necessário nenhum #referencia no template, nenhum viewChild() e nenhum ElementRef. O formulário já sabe qual input está vinculado ao campo email.

Passo 2 - Focando o primeiro campo inválido

Um cenário muito comum: o usuário clica em Salvar, o formulário está inválido e queremos levá-lo direto ao primeiro campo com erro. Isso melhora bastante a acessibilidade, principalmente para quem navega pelo teclado ou utiliza leitores de tela.

Para isso podemos combinar o focusBoundControl() com o errorSummary(), que retorna a lista de erros de todo o formulário. Cada erro possui a propriedade fieldTree, que aponta para o campo onde o erro ocorreu:

salvar() {
  // Marca todos os campos como "tocados"
  // para que as mensagens de erro apareçam
  this.formularioCliente().markAsTouched();

  const primeiroErro = this.formularioCliente()
    .errorSummary()[0];

  if (primeiroErro?.fieldTree) {
    // Leva o usuário até o primeiro campo inválido
    primeiroErro.fieldTree().focusBoundControl();
    return;
  }

  console.log('Salvar', this.cliente());
}

No template, adicionamos o <form> e as mensagens de erro:

<h2>Cadastro de Cliente</h2>
<form (submit)="salvar(); $event.preventDefault()" novalidate>
  <div>
    <input
      [formField]="formularioCliente.nome"
      placeholder="nome..."
      type="text" />
  </div>
  @let campoNome = formularioCliente.nome();
  @if (campoNome.touched() && campoNome.invalid()) {
    <div style="color: red">
      {{ campoNome.errors()[0].message }}
    </div>
  }

  <div>
    <input
      [formField]="formularioCliente.email"
      placeholder="email..."
      type="email" />
  </div>
  @let campoEmail = formularioCliente.email();
  @if (campoEmail.touched() && campoEmail.invalid()) {
    <div style="color: red">
      {{ campoEmail.errors()[0].message }}
    </div>
  }

  <div>
    <input
      [formField]="formularioCliente.telefone"
      placeholder="telefone..."
      type="tel" />
  </div>
  @let campoTelefone = formularioCliente.telefone();
  @if (campoTelefone.touched() && campoTelefone.invalid()) {
    <div style="color: red">
      {{ campoTelefone.errors()[0].message }}
    </div>
  }

  <button type="submit">Salvar</button>
</form>

Veja que, conforme o usuário corrige os campos e clica novamente em Salvar, o foco vai "pulando" para o próximo campo com erro, seguindo a ordem do formulário.

0:00
/0:12

Exemplo

Passo 3 - Evitando a rolagem e trabalhando com controles customizados

Evitando a rolagem com preventScroll

Por padrão, quando o campo está fora da área visível da tela, o navegador faz a rolagem até ele ao receber o foco. Se você não quiser esse comportamento, basta passar a opção preventScroll:

this.formularioCliente.email().focusBoundControl({
  preventScroll: true,
});

Essa opção é a mesma do HTMLElement.focus() nativo do navegador.

Controles customizados

Agora um detalhe importante: se o campo estiver vinculado a um componente customizado, por padrão o focusBoundControl() não faz nada. O motivo é que um componente pode conter vários inputs (pense em um campo de data com dia, mês e ano separados) e o Angular não tem como saber qual deles deve receber o foco.

Para resolver isso, basta implementar um método focus() no componente. Quando o focusBoundControl() for chamado, o Angular vai executar esse método:

import {
  Component,
  ElementRef,
  model,
  viewChild,
} from '@angular/core';
import { FormValueControl } from '@angular/forms/signals';

@Component({
  selector: 'app-input-telefone',
  template: `
    <input
      #inputTelefone
      type="tel"
      placeholder="(11) 99999-9999"
      [value]="value()"
      (input)="value.set($any($event.target).value)" />
  `,
})
export class InputTelefone implements FormValueControl<string> {
  readonly value = model<string>('');

  private readonly inputTelefone =
    viewChild.required<ElementRef<HTMLInputElement>>(
      'inputTelefone'
    );

  // Chamado automaticamente quando o focusBoundControl()
  // é executado no campo vinculado a este componente
  focus(): void {
    this.inputTelefone().nativeElement.focus();
  }
}

input-telefone.ts

E no template do formulário, trocamos o input de telefone pelo nosso componente:

<app-input-telefone
  [formField]="formularioCliente.telefone" />

Perceba que o ElementRef não sumiu por completo, mas agora ele fica encapsulado dentro do componente, que é quem realmente sabe qual elemento deve receber o foco. Quem usa o componente continua apenas chamando o focusBoundControl().

Considerações

O focusBoundControl() é um recurso pequeno, mas que resolve um incômodo antigo de quem trabalha com formulários no Angular. Em vez de espalhar viewChild(), ElementRef e nativeElement.focus() pelos componentes, passamos a pedir ao próprio formulário que foque o campo desejado.

Combinado com o errorSummary(), ele também facilita bastante a implementação de boas práticas de acessibilidade, levando o usuário direto ao campo que precisa ser corrigido.

Vale lembrar que, com o Angular 22, o Signal Forms deixou de ser experimental e agora é estável, ou seja, já pode ser utilizado com tranquilidade em produção.

Links interessantes:

Exemplo de uso:

Aplicando foco nos componentes Angular - StackBlitz
Exemplo de uso do focusBoundControl() para efetuar foco nos elementos.