Forem: Davi Batista

Você conhece SelectionModel do @Angular/cdk ?

Davi Batista — Tue, 13 May 2025 15:51:20 +0000

Em muitas aplicações, precisamos permitir que o usuário selecione um ou vários itens (linhas, cards, arquivos) para executar ações em lote - como excluir, editar ou exportar alguma coisa. Implementar essa lógica “na mão” pode gerar código verboso e propenso a bugs.

O SelectionModel do @angular/cdk/collections simplifica esse cenário, oferecendo métodos prontos e observáveis para:

✅ Selecionar e desselecionar itens
🔄 Alternar o estado de seleção (toggle)
✔️ Verificar se um item (ou todos) estão selecionados
🗑️ Limpar toda a seleção

💿 Instalação do CDK

Antes de usar o SelectionModel, instale o Angular CDK no seu projeto:

Em seguida, importe o módulo necessário (se for usar componentes de tabela, tree ou drag-drop, por exemplo):

npm install @angular/cdk --save

🤔 Conceitos Básicos

selection = new SelectionModel<MyItem>(true, []);

multiple (boolean): true permite seleção múltipla; false apenas uma.
initiallySelected (T[]): itens que já vêm marcados.

Principais Membros

Membro	Descrição
`select(item...)`	Marca um ou mais itens
`deselect(item...)`	Desmarca itens
`toggle(item)`	Alterna seleção de um item
`clear()`	Remove todas as seleções
`selected: T[]`	Array com itens selecionados
`hasValue(): boolean`	Retorna `true` se houver pelo menos um item selecionado
`isSelected(item)`	`true` se o item está entre os selecionados

🗂️ Exemplo Completo: Gestão de Documentos

A seguir, um fluxo integrado TypeScript + HTML para demonstrar a criação de um componente que usa SelectionModel.

📄 document-list.component.ts

import { Component, OnInit } from '@angular/core';
import { SelectionModel } from '@angular/cdk/collections';
import { DocumentService, IDocument } from './document.service';
import { DatePipe } from '@angular/common';

@Component({
  selector: 'app-document-list',
  templateUrl: './document-list.component.html',
  styleUrls: ['./document-list.component.css'],
  imports: [DatePipe],
})
export class DocumentListComponent implements OnInit {
  documents: IDocument[] = [];
  selection = new SelectionModel<IDocument>(true, []); // múltipla seleção

  constructor(private docService: DocumentService) {
    this.loadDocuments(); // carrega lista na inicialização
  }

  ngOnInit(): void {
    // Exibe no console os documentos adicionados e removidos da seleção
    this.selection.changed.subscribe(change => {
      console.log('Adicionados:', change.added);
      console.log('Removidos:', change.removed);
    });
  }

  /** Carrega dados da API (simulada) */
  loadDocuments(): void {
    this.selection.clear(); // limpa seleção ao carregar nova lista
    this.docService
      .getAllDocuments()
      .subscribe((docs) => (this.documents = docs));
  }

  /** Retorna se todos os documentos estão selecionados */
  isAllSelected(): boolean {
    return this.selection.selected.length === this.documents.length;
  }

  /** Seleciona todos ou limpa seleção */
  masterToggle(): void {
    if (this.isAllSelected()) {
      this.selection.clear(); // limpa todas as seleções
    } else {
      this.documents.forEach((doc) => this.selection.select(doc));
    }
  }

  /** Deleta documentos selecionados e limpa o modelo */
  bulkDelete(): void {
    const idsToDelete = this.selection.selected.map((d) => d.id);
    // TODO: chamar serviço real de delete
    this.documents = this.documents.filter((d) => !idsToDelete.includes(d.id));
    this.selection.clear();
  }
}

📑 document-list.component.html

<div class="container">
  <div class="toolbar">
    <button class="btn" (click)="loadDocuments()">🔄 Recarregar</button>
    <button
      class="btn"
      (click)="bulkDelete()"
      [disabled]="!selection.hasValue()"
    >
      🗑️ Excluir ({{ selection.selected.length }})
    </button>
  </div>

  <table class="document-table">
    <thead>
      <tr>
        <th>
          <input
            type="checkbox"
            [checked]="isAllSelected()"
            [indeterminate]="selection.hasValue() && !isAllSelected()"
            (change)="masterToggle()"
          />
        </th>
        <th>Nome do Documento</th>
        <th>Data de Upload</th>
        <th>Tamanho</th>
      </tr>
    </thead>
    <tbody>
      @for(doc of documents; track doc.id) {
      <tr>
        <td>
          <input
            type="checkbox"
            [checked]="selection.isSelected(doc)"
            (change)="selection.toggle(doc)"
          />
        </td>
        <td>{{ doc.name }}</td>
        <td>{{ doc.uploadDate | date : "dd/MM/yyyy" }}</td>
        <td>{{ doc.size }} bytes</td>
      </tr>
      }
      <!--  -->
      @empty {
      <tr>
        <td colspan="4" class="no-data">Nenhum documento encontrado.</td>
      </tr>
      }
    </tbody>
  </table>
</div>

Dica: Não se esqueça de usar “trackBy” em loops (como *ngFor ou @for) traz ganhos de performance e estabilidade à sua aplicação Angular. Veja por quê:
@for(doc of documents; track doc.id) {
  <tr>
      <td>{{ doc.name }}</td>
  </tr>
}

Minimiza operações no DOM
Sem trackBy, o Angular recria todos os elementos quando o array muda. Com ele, apenas atualiza os itens modificados usando uma chave única.
Evita recriações desnecessárias
Mantém referências de componentes inalterados, economizando recursos de renderização.
Melhora a experiência do usuário
Reduz "piscadas" na interface e oferece melhor performance em listas longas.
Otimiza dados imutáveis
Em arquiteturas como NgRx/Redux, atualiza apenas os itens necessários usando trackBy: item => item.id.

📣 Eventos e Observabilidade

O SelectionModel expõe um Observable (changed) que notifica sempre que itens são adicionados ou removidos da seleção. Se você ainda não está familiarizado com RxJS, veja a documentação oficial.

selection.changed.subscribe(change => {
  console.log('Adicionados:', change.added);
  console.log('Removidos:', change.removed);
});

Use essa reatividade para:

Atualizar botões de ação em tempo real
Exibir contadores de seleção
Enviar eventos de analytics

🔒 Itens Desabilitados

Você pode renderizar checkboxes desabilitados para itens que não devem ser selecionados:

<input
  type="checkbox"
  [checked]="selection.isSelected(doc)"
  [disabled]="doc.locked"
  (change)="selection.toggle(doc)"
/>

Isso comunica ao usuário quais opções estão indisponíveis.

🏁 Conclusão

O SelectionModel do Angular CDK oferece:

API enxuta para seleção de itens
Observabilidade via changed para reatividade
Flexibilidade para cenários como tabelas, tree's e formulários dinâmicos

Experimente essas práticas no seu próximo projeto e comente abaixo como o SelectionModel facilitou sua vida de desenvolvedor! 🚀

🌐 repository: https://github.com/DaviBatistaOliv/angular-SelectionModel

Angular AsyncValidator: Validação Assíncrona de Formulários

Davi Batista — Mon, 12 May 2025 12:51:05 +0000

Introdução

Validar formulários é essencial para manter a integridade dos dados enviados pelos usuários. Muitas vezes, esse processo exige consultas a serviços externos, seja para confirmar se um nome de usuário já está em uso, verificar em tempo real se um cupom de desconto ainda é válido e não ultrapassou seu limite de utilizações, ou até mesmo consultar o estoque de um produto antes de habilitar o botão “Adicionar ao carrinho”.

O AsyncValidator do Angular surge como a solução ideal para esses cenários, pois suporta retornos assíncronos via Promise ou Observable, garantindo que o formulário só seja considerado válido depois que todas as validações remotas forem concluídas com sucesso.

1. O que é um AsyncValidator? 🤔

É uma classe (ou função) que implementa a interface AsyncValidator do Angular.
Retorna um Observable<ValidationErrors | null> ou Promise<ValidationErrors | null>.
Ideal para checar duplicidade em servidor, disponibilidade de e-mail, validadores de segurança, etc.

2. Visão geral do fluxo

Usuário digita o código do cupom no campo do formulário.
Ao perder o foco (updateOn: 'blur'), o AsyncValidator é acionado.
Dispara-se uma chamada HTTP simulada ao nosso serviço de cupons.
Se o cupom for válido (true), o validador retorna null e o campo fica válido.
Se o cupom for inválido (false), retorna { invalidCoupon: true } e exibe erro.
Em caso de erro de rede, retorna null para não bloquear o avanço do usuário.

3. Serviço de integração

Não há razão para se preocupar com um backend real, vamos apenas simular uma chamada http para busca de dados:

// coupon.service.ts
import { Injectable } from '@angular/core';
import { Observable, of } from 'rxjs';
import { delay } from 'rxjs/operators';

@Injectable({ providedIn: 'root' })
export class CouponService {
  // Lista de cupons válidos simulada
  private validCoupons = ['PROMO10', 'SAVE20', 'OFF30'];

  /** Simula uma chamada HTTP verificando se o cupom é válido */
  validateCoupon(code: string): Observable<boolean> {
    const isValid = this.validCoupons.includes(code.toUpperCase());

    return of(isValid).pipe(delay(500));
  }
}

4. Criando o AsyncValidator customizado

// coupon.validator.ts
import { inject, Injectable } from '@angular/core';
import {
  AbstractControl,
  AsyncValidator,
  ValidationErrors,
} from '@angular/forms';
import { Observable, of } from 'rxjs';
import { map } from 'rxjs/operators';
import { CouponService } from './coupon.service';

@Injectable({ providedIn: 'root' })
export class CouponValidator implements AsyncValidator {
  private couponService = inject(CouponService);

  validate(control: AbstractControl): Observable<ValidationErrors | null> {
    const code = control.value;
    if (!code) {
      return of(null);
    }
    return this.couponService
      .validateCoupon(code)
      .pipe(map((isValid) => (isValid ? null : { invalidCoupon: true })));
  }
}

timer(500): aguarda 500 ms após o último caractere.
switchMap: cancela requisições anteriores se o valor mudar.
catchError: devolve null em falha de rede para não invalidar o form.

5. Integrando no FormBuilder

// checkout.component.ts
import { Component, inject, OnInit } from '@angular/core';
import {
  FormBuilder,
  FormGroup,
  FormsModule,
  ReactiveFormsModule,
  Validators,
} from '@angular/forms';
import { CouponValidator } from './coupon.validator';

@Component({
  selector: 'app-checkout',
  templateUrl: './checkout.component.html',
  styleUrls: ['./checkout.component.css'],
  imports: [FormsModule, ReactiveFormsModule],
})
export class CheckoutComponent implements OnInit {
  checkoutForm!: FormGroup;

  private fb = inject(FormBuilder);
  private couponValidator = inject(CouponValidator);

  ngOnInit(): void {
    this.checkoutForm = this.fb.group({
      couponCode: this.fb.control('', {
        validators: [Validators.required],
        asyncValidators: [
          this.couponValidator.validate.bind(this.couponValidator),
        ],
      }),
    });
  }
}

6. Exibindo erros no template

<!-- checkout.component.html -->
<form class="form-container" [formGroup]="checkoutForm">
  <div class="field-group">
    <label for="coupon" class="field-label">🎫 Cupom de Desconto</label>
    <input
      id="coupon"
      type="text"
      formControlName="couponCode"
      placeholder="Insira seu cupom"
      class="field-input"
    />

    @if(checkoutForm.get('couponCode')?.pending) {
    <div class="field-info">⏳ Verificando cupom...</div>
    }
    <!--  -->
    @if(checkoutForm.get('couponCode')?.hasError('required')) {
    <div class="field-info">
      Que tal usar o cupom de desconto <strong>OFF30</strong>?
    </div>
    }
    <!--  -->
    @if( checkoutForm.get('couponCode')?.valid &&
    !checkoutForm.get('couponCode')?.pending &&
    checkoutForm.get('couponCode')?.dirty ) {
    <div class="field-success">✅ Cupom aplicado com sucesso!</div>
    }
  </div>
</form>

form.pending: indica que a validação assíncrona está em andamento.

7. Boas práticas 🎯

Use updateOn: 'blur' ou submit para reduzir chamadas excessivas.
Aplique debounce interno (com timer ou debounceTime).
Sempre trate erros de rede com catchError, para não travar o formulário.
Separe lógica de API em serviços (CouponService) e validação em classes (AsyncValidator), seguindo o princípio de responsabilidade única.

Conclusão

Com este padrão, você garante validações assíncronas limpas, reutilizáveis e fáceis de testar. O exemplo de validação de cupons é apenas uma amostra: a mesma abordagem vale para e-mails, CPFs.

Agora é sua vez: experimente adaptar esse AsyncValidator a outros cenários 😊

🌐 repository: https://github.com/DaviBatistaOliv/Angular-AsyncValidator-cupon

Não perca tempo! Crie modais com @angular/cdk

Davi Batista — Tue, 28 Mar 2023 14:20:09 +0000

E aí, pessoal! Já pensou em criar sua própria modal para suas aplicações web sem se preocupar com bibliotecas de terceiros? Com o @angular/cdk, podemos tornar essa tarefa muito mais fácil.

O @angular/cdk contém vários componentes prontos para uso, como o Overlay e o Portal, que ajudam muito na criação de modais personalizadas.

Neste artigo, vou te mostrar como criar uma modal personalizada usando o @ViewChild e @ViewChild. Então, pegue seu café e vamos ao código 👨‍💻

Pré-requisitos:

Para acompanhar este tutorial, você precisará de um projeto Angular e ter um breve conhecimento sobres os conceitos do Angular.

Atenção! Este tutorial foi criado usando Angular 15, mas com um pouco de esforço, é possível implementá-lo em versões anteriores do Angular.

É Hora de implementar

Para iniciar, é necessário instalar o pacote @angular/cdk através do comando npm install @angular/cdk ou utilizar a opção ng add @angular/cdk fornecida pelo @angular/cli. É importante também incluir os estilos disponíveis do @angular/cdk no seu arquivo de CSS global.

@import "@angular/cdk/overlay-prebuilt.css";

Para criar o nosso componente modal utilizando o @angular/cli, execute o seguinte comando no terminal dentro do diretório do seu projeto:

ng g c modal

após gerar nosso component via @angular/cli devemos ter algo assim:

import { Component, OnInit } from "@angular/core";

@Component({
  selector: "app-modal",
  templateUrl: "./modal.component.html",
  styleUrls: ["./modal.component.css"],
  standalone: true,
})
export class ModalComponent implements OnInit {
  constructor() {}

  ngOnInit() {}
}

Ótimo! Vamos começar criando uma variável chamada MODAL_DEFAULT_OPTIONS com alguns valores padrão. Nela, definimos o positionStrategy como GlobalPositionStrategy, o que fará com que o Overlay trabalhe com o posicionamento relativo à janela do navegador. Em seguida, chamamos os métodos centerHorizontally() e centerVertically() para alinhar nossa modal ao centro da tela.

Também definimos que a modal terá um fundo hasBackdrop e adicionamos uma class personalizada chamada modal-panel para nosso painel. Por fim, definimos uma largura mínima para nossa modal de 500px.

export const MODAL_DEFAULT_OPTIONS: OverlayConfig = {
  positionStrategy: new GlobalPositionStrategy()
    .centerHorizontally()
    .centerVertically(),
  hasBackdrop: true,
  panelClass: "modal-panel",
  minWidth: "500px",
};

O próximo passo é criar um ng-template em nosso arquivo HTML e incluir algumas tags HTML para ajudar a estruturar nossa modal:

Criamos um ng-template e demos a ele um nome de referência #modalTemplate.
Criamos uma div para agrupar nossos elementos.
Adicionamos um ng-content com o select [modal--content].

<ng-template #modalTemplate>
  <div class="modal">
    <ng-content select="[modal--content]"></ng-content>
  </div>
</ng-template>

Vamos criar um ng-template para que o conteúdo seja chamado apenas quando criarmos nossa modal utilizando o TemplatePortal.

O TemplatePortal é uma classe do @angular/cdk/portal que nos permite inserir conteúdo em um componente ou elemento de destino.

Agora que já temos o nosso template definido no HTML, vamos criar uma variável e utilizar o decorator @ViewChild, passando o nome que demos ao nosso template no HTML. Além disso, vamos criar uma variável chamada overlayRef para controlar a exibição da nossa modal.

 @ViewChild("modalTemplate") modalTemplate: TemplateRef<any>;

 private overlayRef: OverlayRef;

no constructor do nosso component vamos injetar o viewContainerRef e o overlay

constructor(
    private _viewContainerRef: ViewContainerRef,
    private overlay: Overlay
  ) {}

criamores agora o metodo que ira abrir a modal, vamos chamar ele de open()

Primeiramente, o método open() cria uma overlayRef utilizando a função create() do overlay, que recebe como parâmetro um objeto contendo as opções para a modal. Essas opções foram definidas através do MODAL_DEFAULT_OPTIONS.

em seguida, é criado um containerModal utilizando o TemplatePortal, que é uma classe que permite criar um portal para o conteúdo de um ng-template. O containerModal é criado a partir do modalTemplate, que é definido em um ng-template no arquivo HTML. O TemplatePortal também recebe como parâmetro o viewContainerRef, que é uma referência para o container da view do Angular.

por fim, a overlayRef é anexada ao containerModal utilizando a função attach(), que recebe como parâmetro o containerModal. A função open() retorna a overlayRef, que pode ser utilizada para fechar a modal posteriormente.

public open() {
    this.overlayRef = this.overlay.create({
      ...MODAL_DEFAULT_OPTIONS,
    });

    const containerModal = new TemplatePortal(
      this.modalTemplate,
      this._viewContainerRef
    );

    this.overlayRef.attach(containerModal);

    return this.overlayRef;
}

Agora método close() ele é responsável por fechar a modal. Ele simplesmente chama o método dispose() no overlayRef, o que faz com que a modal seja removida da tela

public close() {
    this.overlayRef.dispose();
}

agora em nosso arquivo de scss global vamos incluir um estilo para nossa modal

.modal-panel {
  background-color: white;
  border-radius: 8px;
  padding: 24px;
}

Otimo! finalizamos a implementação da nossa modal, agora vamos utilizar.

Para utilizar o componente ModalComponent, podemos criar um botão que chama o método open() e um outro botão dentro da modal que chama o método close(). Podemos utilizar a referência do componente utilizando o decorator @ViewChild.

import "zone.js/dist/zone";
import { Component, ViewChild } from "@angular/core";
import { CommonModule } from "@angular/common";
import { bootstrapApplication } from "@angular/platform-browser";
import { ModalComponent } from "./modal/modal.component";

@Component({
  selector: "my-app",
  standalone: true,
  imports: [CommonModule, ModalComponent],
  template: `
    <button (click)="modalOpen()">Abrir modal</button>

    <app-modal #modal>
      <div modal--content>
        <p>modal</p>
        <button (click)="modalClose()">Fechar</button>
      </div>
    </app-modal>
  `,
})
export class App {
  @ViewChild("modal") modal: ModalComponent;

  name = "Angular";

  modalOpen() {
    this.modal.open();
  }

  modalClose() {
    this.modal.close();
  }
}

bootstrapApplication(App);

import "zone.js/dist/zone";
import { Component } from "@angular/core";
import { CommonModule } from "@angular/common";
import { bootstrapApplication } from "@angular/platform-browser";
import { ModalComponent } from "./modal/modal.component";

@Component({
  selector: "my-app",
  standalone: true,
  imports: [CommonModule, ModalComponent],
  template: `
    <button (click)="modal.open()">Abrir modal</button>

    <app-modal #modal>
      <div modal--content>
        <p>modal</p>
        <button (click)="modal.close()">Fechar modal</button>
      </div>
    </app-modal>
  `,
})
export class App {
  name = "Angular";
}

bootstrapApplication(App);

🥳 Parabéns! Agora você tem em mãos uma modal reutilizável que pode ser implementada em seus projetos ou até mesmo em uma biblioteca de componentes (design system).
Lembre-se de considerar as necessidades do seu projeto e manter uma documentação clara e atualizada para facilitar o uso por outros membros da equipe.

Além disso, você pode acessar o repositório no Github e o exemplo no Stackblitz para consultar o código e ter mais informações sobre a implementação da modal.

🌐 repository: https://github.com/DrewOliv/angular-cdk-component-modal-example
💻 stackblitz: https://stackblitz.com/edit/angular-qhsjku?file=README.md