Skip to content

3. Os componentes

3.1. Exemplo 10: componentes e seus inputs

Um componente é uma peça reutilizável da interface. Este exemplo exibe perfis de médicos: um componente chamado [DoctorCard] (o filho), usado várias vezes pelo componente [App] (o pai).

Os arquivos de um componente geralmente ficam em uma pasta com o nome do componente:

1
2
3
4
5
6
7
8
10-components/src/app/
├── doctor-card/
│   ├── doctor-card.ts     the class of the component
│   ├── doctor-card.html   its template
│   └── doctor-card.css    its style
├── doctor.ts             the Doctor type
├── app.ts
└── app.html

O tipo de dado compartilhado entre o pai e o filho:

1
2
3
4
5
6
7
8
9
// o tipo de dados compartilhado pelo pai (App) e pelo filho (DoctorCard)
export interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
  specialty: string;
  available: boolean;
}

3.1.1. O filho

// =========================================================================
// 10-components/src/app/doctor-card/doctor-card.ts - um componente FILHO
// -------------------------------------------------------------------------
// Ele recebe seus dados do pai por meio de INPUTS, declarados
// com input(): cada input é um SIGNAL somente leitura, que acompanha o
// valor passado pelo pai. O tipo deles é verificado em tempo de compilação:
// <app-doctor-card [doctor]="42"> seria rejeitado.
//
// Regra de ouro: um componente NUNCA MODIFICA seus inputs. Os dados
// descem do pai para o filho; para solicitar uma mudança,
// o filho emite um evento (veja o exemplo 11).
// =========================================================================

import { booleanAttribute, Component, computed, input } from '@angular/core';
import { Doctor } from '../doctor';

@Component({
  // o selector: a tag que representa este componente no seu pai
  selector: 'app-doctor-card',
  templateUrl: './doctor-card.html',
  styleUrl: './doctor-card.css',
})
export class DoctorCard {
  // input.required: o pai DEVE fornecer este input
  readonly doctor = input.required<Doctor>();
  readonly rank = input.required<number>();
  // input(valor padrão): um input opcional. booleanAttribute
  // permite escrever simplesmente <app-doctor-card compact> para true
  readonly compact = input(false, { transform: booleanAttribute });

  // um computed baseado em um input: recalculado se o pai o alterar
  protected readonly initials = computed(() => `${this.doctor().firstName[0]}${this.doctor().lastName[0]}`);
}
  • Linha 19: o seletor: o pai escreverá [<app-doctor-card>];
  • linhas 25–29: os inputs do componente ([inputs]) — os dados que o pai passa a ele. [input()] cria um signal somente leitura que acompanha o valor passado pelo pai:
    • linhas 25–26: [input.required<T>()]: um input obrigatório. Omitir [[doctor]] no template do pai resulta em um erro de compilação;
    • Linha 29: [input(default value)]: um input opcional. A opção [transform] converte o valor recebido: [booleanAttribute] transforma a presença do atributo ([<app-doctor-card compact>], sem valor) em [true], como no atributo HTML [disabled];
  • linha 32: um [computed] baseado em um input: recalculado se o pai alterar o input.

Os inputs não são [protected]: eles fazem parte da interface pública do componente, aquela que o pai utiliza.

Regra de ouro: um componente nunca modifica seus inputs (que, aliás, são somente leitura). Os dados fluem do pai para o filho; para pedir uma alteração, o filho emite um evento (exemplo 11).

<div class="card h-100" [class.border-success]="doctor().available">
  <div class="card-body d-flex gap-3 align-items-center">
    <div class="initials">{{ initials() }}</div>
    <div>
      <!-- os inputs são signals: são lidos chamando-os -->
      <h2 class="h6 mb-1">{{ rank() }}. {{ doctor().title }} {{ doctor().firstName }} {{ doctor().lastName }}</h2>
      @if (!compact()) {
        <p class="mb-0 text-muted small">{{ doctor().specialty }}</p>
      }
    </div>
  </div>
</div>
  • linhas 1, 6, 8: os inputs são signals: são lidos ao serem chamados;
  • linhas 7–9: a especialidade é exibida apenas na versão normal do cartão.
/* o estilo do componente: aplica-se apenas aos SEUS elementos */
.initials {
  width: 2.5rem;
  height: 2.5rem;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #dd0031;
  color: white;
  font-weight: bold;
}

A classe [initials] se aplica apenas a este componente: outro componente poderia ter sua própria classe [initials], sem nenhum conflito.

3.1.2. O pai

// =========================================================================
// 10-components/src/app/app.ts - o componente PAI
// -------------------------------------------------------------------------
// Ele importa o componente DoctorCard (array imports) e o usa como
// uma nova tag HTML, <app-doctor-card>, quantas vezes
// for necessário: um componente é uma peça REUTILIZÁVEL de interface, com
// seus próprios dados, seu template e seu estilo.
// =========================================================================

import { Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { DoctorCard } from './doctor-card/doctor-card';
import { Doctor } from './doctor';

@Component({
  selector: 'app-root',
  imports: [FormsModule, DoctorCard],
  templateUrl: './app.html',
})
export class App {
  protected readonly doctors = signal<Doctor[]>([
    { id: 1, title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER', specialty: 'general practitioner', available: true },
    { id: 2, title: 'Mr', firstName: 'Paul', lastName: 'TATOU', specialty: 'pediatrician', available: false },
    { id: 3, title: 'Melle', firstName: 'Sophie', lastName: 'DUPONT', specialty: 'general practitioner', available: true },
  ]);
  protected readonly compact = signal(false);

  // o pai modifica SEUS dados: os filhos envolvidos são atualizados
  protected toggleAvailability(): void {
    this.doctors.update((list) => list.map((m) => ({ ...m, available: !m.available })));
  }
}
  • linha 17: o pai importa o componente filho; sem isso, [<app-doctor-card>] seria uma tag desconhecida, e a compilação falharia;
  • linhas 29–31: o pai modifica SEUS dados. Ele substitui cada médico por uma cópia modificada: o objeto [m] passado a cada cartão muda, e os cartões se atualizam.
<div class="container py-4">
  <h1 class="h3 mb-3">Example 10 - components and their inputs</h1>
  <div class="d-flex gap-3 mb-3">
    <label class="form-check-label">
      <input type="checkbox" class="form-check-input" [(ngModel)]="compact"> compact display
    </label>
    <button class="btn btn-sm btn-outline-primary" (click)="toggleAvailability()">Toggle availability</button>
  </div>
  <div class="row g-3">
    @for (m of doctors(); track m.id; let i = $index) {
      <div class="col-md-4">
        <!-- [doctor]="m" passa o OBJETO m (uma expressão);
             doctor="m", sem colchetes, passaria a STRING "m" -->
        <app-doctor-card [doctor]="m" [rank]="i + 1" [compact]="compact()" />
      </div>
    }
  </div>
  <p class="mt-3 mb-1 small text-muted">The same card, in compact version, through an attribute without a value:</p>
  <div class="w-50">
    <app-doctor-card [doctor]="doctors()[0]" [rank]="1" compact />
  </div>
</div>
  • linha 14: o filho é usado como uma tag HTML. [[doctor]="m"] é um binding de propriedade ao input [doctor]: ele transmite o OBJETO [m]. Sem colchetes, [doctor="m"] passaria a STRING ["m"], que o compilador rejeitaria. Um componente sem conteúdo pode ser escrito com uma tag autofechada ([/>]);
  • linha 20: [compact], sem valor: graças a [booleanAttribute], o input recebe [true].

[npm start 10-components]; clique em “Toggle availability”:

Image

3.2. Exemplo 11: os outputs de um componente e model()

Um filho tem duas maneiras de enviar informações de volta ao pai:

  1. emitir um evento (um output, [output]), que o pai escuta como um evento HTML; 2. uma conexão bidirecional, [[( )]], em um [model()].

3.2.1. Emissão de um evento

Um contador que notifica o pai a cada clique e quando atinge seu limite:

// =========================================================================
// 11-outputs-model/src/app/counter/counter.ts
// -------------------------------------------------------------------------
// Um filho que NOTIFICA seu pai: output() declara um evento que o
// componente pode emitir, com o tipo de seus dados. O pai o escuta
// como um evento HTML: <app-counter (incremented)="..." (limit)="...">.
// =========================================================================

import { Component, input, output, signal } from '@angular/core';

@Component({
  selector: 'app-counter',
  template: `
    <div class="d-flex align-items-center gap-2 mb-2">
      <span class="w-25">{{ label() }}</span>
      <button class="btn btn-sm btn-outline-primary" (click)="plus()">+1</button>
      <span class="badge text-bg-secondary">{{ value() }} / {{ max() }}</span>
    </div>
  `,
})
export class Counter {
  readonly label = input.required<string>();
  readonly max = input.required<number>();

  // dois eventos: incremented (com o novo valor) e limit (sem dados)
  readonly incremented = output<number>();
  readonly limit = output<void>();

  protected readonly value = signal(0);

  protected plus(): void {
    if (this.value() >= this.max()) {
      this.limit.emit();
      return;
    }
    this.value.update((v) => v + 1);
    this.incremented.emit(this.value());
  }
}
  • linhas 13–19: o template do componente, escrito no decorador (propriedade [template], entre crases);
  • linhas 26–27: [output<T>()] declara um output: um evento que o componente pode emitir, junto com o tipo de seus dados. [limit] não tem dados ([void]);
  • linhas 33 e 37: [emit(data)] emite o evento; o pai recebe os dados.

Evite dar a um output o nome de um evento do navegador ([change], [click]...): os eventos do navegador emitidos pelos elementos do componente se propagam até o elemento hospedeiro dele, e o pai também os receberia.

3.2.2. Um binding bidirecional

Um campo de formulário “personalizado” (rótulo, campo, dica, contador de caracteres) que se vincula a dados do pai como o [ngModel]:

// =========================================================================
// 11-outputs-model/src/app/text-field/text-field.ts
// -------------------------------------------------------------------------
// Um campo de formulário personalizado (rótulo + campo + ajuda + contador
// de caracteres) que aceita um binding BIDIRECIONAL, como o ngModel:
//     <app-text-field [(value)]="lastName" label="Last name" [max]="20" />
//
// model() cria um signal GRAVÁVEL vinculado ao pai: LÊ-LO fornece o valor
// do pai, ESCREVER nele (set) emite o evento valueChange, que a
// sintaxe [( )] transforma em uma atualização do signal do pai. Os dados
// assim continuam realmente pertencendo ao pai.
// =========================================================================

import { Component, input, model } from '@angular/core';

// um contador compartilhado por todas as instâncias: um identificador único por
// campo, para vincular <label for> e <input id>
let nextNumber = 0;

@Component({
  selector: 'app-text-field',
  template: `
    <div class="mb-3">
      <label class="form-label" [for]="id">{{ label() }}</label>
      <!-- [value]: o valor do pai; (input): cada tecla digitada o substitui -->
      <input class="form-control" [id]="id" [value]="value()" [attr.maxlength]="max()"
             [class.is-invalid]="value().length === max()" (input)="onInput($event)">
      <div class="form-text">{{ help() }} ({{ value().length }} / {{ max() }})</div>
    </div>
  `,
})
export class TextField {
  readonly value = model.required<string>();
  readonly label = input.required<string>();
  readonly max = input.required<number>();
  readonly help = input('');

  protected readonly id = `text-field-${++nextNumber}`;

  protected onInput(event: Event): void {
    this.value.set((event.target as HTMLInputElement).value);
  }
}
  • Linha 33: [model()] cria um signal gravável vinculado ao pai. LER o signal retorna o valor do pai; ESCREVER nele ([set], linha 41) altera o valor E emite o evento [valueChange] (o nome do model seguido de [Change]). O pai que escreve [[(value)]="signal"] tem, assim, seu signal atualizado;
  • linha 18: uma variável de módulo (fora da classe) é compartilhada por todas as instâncias do componente: um contador que atribui um identificador único a cada campo (linha 38), para vincular [<label for>] e [<input id>];
  • linhas 26–27: [[value]] exibe o valor do pai; [(input)] o substitui a cada tecla digitada (linha 41). [[attr.maxlength]] é um binding de atributo HTML (o atributo [maxlength]), e não um binding de propriedade.

3.2.3. O pai

// =========================================================================
// 11-outputs-model/src/app/app.ts - o pai escuta seus filhos
// -------------------------------------------------------------------------
// Duas maneiras de um filho passar informações para cima:
//   1. emitir um evento (output), que o pai escuta com ( );
//   2. um binding bidirecional [( )] em um model(): um atalho
//      para o input [value] + o evento (valueChange).
// =========================================================================

import { Component, computed, signal } from '@angular/core';
import { Counter } from './counter/counter';
import { TextField } from './text-field/text-field';

@Component({
  selector: 'app-root',
  imports: [Counter, TextField],
  templateUrl: './app.html',
})
export class App {
  protected readonly total = signal(0);
  protected readonly message = signal('');
  protected readonly firstName = signal('Marie');
  protected readonly lastName = signal('PELISSIER');
  protected readonly fullName = computed(() => `${this.firstName()} ${this.lastName().toUpperCase()}`);

  // o handler do evento incremented: ele recebe os dados emitidos ($event)
  protected onChange(label: string, value: number): void {
    this.total.update((t) => t + 1);
    this.message.set(`${label} is now ${value}`);
  }

  protected clear(): void {
    this.firstName.set('');
    this.lastName.set('');
  }
}
<div class="container py-4" style="max-width: 640px">
  <h1 class="h3 mb-3">Example 11 - the outputs of a component and model()</h1>

  <div class="card p-3 mb-4">
    <h2 class="h6">1. Events emitted by the children</h2>
    <!-- $event: os dados emitidos pelo filho (aqui, o novo valor) -->
    <app-counter label="Coffees" [max]="3" (incremented)="onChange('Coffees', $event)"
                  (limit)="message.set('No more than 3 coffees!')" />
    <app-counter label="Glasses of water" [max]="8" (incremented)="onChange('Glasses of water', $event)"
                  (limit)="message.set('Enough drinking.')" />
    <p class="mb-0">Total clicks: {{ total() }} - <em>{{ message() }}</em></p>
  </div>

  <div class="card p-3">
    <h2 class="h6">2. A two-way binding with model()</h2>
    <!-- [(value)]="firstName": o signal firstName do pai, lido E modificado pelo filho -->
    <app-text-field [(value)]="firstName" label="First name" [max]="20" help="Required" />
    <app-text-field [(value)]="lastName" label="Last name" [max]="20" help="Displayed in upper case" />
    <p class="mb-0">Data of the parent: <strong>{{ fullName() }}</strong></p>
    <button class="btn btn-sm btn-outline-secondary mt-2 align-self-start" (click)="clear()">Clear (from the parent)</button>
  </div>
</div>
  • Linha 7: [(incremented)="..."] escuta o output [incremented] do contador; [$event] são os dados emitidos (o novo valor). [label="Coffees"], sem colchetes: um input do tipo string pode receber um valor constante;
  • linha 8: [(limit)]: um método de um signal ([set]) pode ser chamado diretamente dentro do template;
  • linha 9: um segundo contador, com seu próprio rótulo, limite e mensagens;
  • linha 17: [[(value)]="firstName"]: o signal [firstName] do pai (sem parênteses: informa-se o próprio signal), lido E modificado pelo filho. Esta é a forma abreviada de [[value]="firstName()" (valueChange)="firstName.set($event)"];
  • linha 20: o pai modifica seus dados: os dois campos acompanham.

[npm start 11-outputs-model]; quatro cliques nos cafés, um na água e, em seguida, digite um nome:

Image

3.3. Exemplo 12: projeção de conteúdo

Os inputs transmitem dados; a projeção de conteúdo transmite conteúdo (de HTML e de outros componentes), escrito pelo pai ENTRE as tags do componente. É o equivalente, no lado do cliente, do template [layout.hbs] do curso [NestJS] e de seu [{{{body}}}].

3.3.1. Um cartão

Uma moldura reutilizável (borda, cabeçalho, rodapé), cujo conteúdo é fornecido pelo pai:

// =========================================================================
// 12-projection/src/app/card/card.ts - um TEMPLATE reutilizável
// -------------------------------------------------------------------------
// Os inputs passam DADOS; a PROJEÇÃO de conteúdo passa
// CONTEÚDO (HTML, outros componentes), escrito pelo pai ENTRE as tags
// <app-card> e </app-card>. O card define a moldura (borda,
// cabeçalho, rodapé), o pai fornece o que vai dentro:
//   - <ng-content />                   : o conteúdo "principal";
//   - <ng-content select="[header]" /> : somente os elementos que têm
//                                        o atributo header;
//   - o conteúdo colocado ENTRE <ng-content> e </ng-content> é exibido se
//     o pai não fornecer nada (conteúdo padrão).
// É o equivalente, no lado do cliente, do template layout.hbs e de seu {{{body}}}
// no curso de NestJS.
// =========================================================================

import { Component, input } from '@angular/core';

@Component({
  selector: 'app-card',
  template: `
    <div class="card mb-3" [class]="color() ? 'border-' + color() : ''">
      <div class="card-header" [class]="color() ? 'text-bg-' + color() : ''">
        <ng-content select="[header]">Untitled</ng-content>
      </div>
      <div class="card-body">
        <ng-content />
      </div>
      <!-- um rodapé vazio (o pai não forneceu nada) é ocultado pelo CSS :empty -->
      <div class="card-footer text-muted small"><ng-content select="[footer]" /></div>
    </div>
  `,
  styles: `
    .card-footer:empty {
      display: none;
    }
  `,
})
export class Card {
  readonly color = input<'primary' | 'success' | 'danger'>();
}
  • linha 27: [<ng-content />]: o local onde o [Angular] coloca o conteúdo escrito pelo pai entre [<app-card>] e [</app-card>];
  • linha 24: [<ng-content select="[header]">]: apenas os elementos de conteúdo que têm o atributo [header]. [select] aceita um seletor CSS (uma tag, uma classe ou um atributo). O texto entre [<ng-content>] e [</ng-content>] é exibido se o elemento pai não fornecer nenhum conteúdo: é o conteúdo padrão;
  • linha 30: o rodapé: elementos que têm o atributo [footer];
  • linhas 33–37: um rodapé vazio (o elemento pai não forneceu nada) fica oculto: a pseudoclasse CSS [:empty] designa um elemento sem conteúdo;
  • Linha 40: um input opcional que só pode assumir três valores; se nenhum valor padrão for especificado, ele assume [undefined] por padrão.

3.3.2. Uma tabela genérica

Uma tabela que sabe percorrer as linhas, mas não sabe exibir UMA linha: o pai lhe diz como fazer isso passando-lhe um template de linha.

// =========================================================================
// 12-projection/src/app/data-table/data-table.ts - uma tabela GENÉRICA
// -------------------------------------------------------------------------
// DataTable<T> é uma classe genérica: ela exibe linhas de qualquer
// tipo T. Sabe percorrer as linhas, mas não como exibir UMA
// linha: o pai informa, passando-lhe um TEMPLATE de linha
// (um <ng-template #row>, um trecho de HTML que não é exibido como
// está, mas que pode ser exibido sob demanda, quantas vezes for necessário).
//
// contentChild('row'): o <ng-template #row> colocado pelo pai entre
// <app-data-table> e </app-data-table>. A tabela o exibe para cada linha
// com ngTemplateOutlet, passando-lhe um CONTEXTO: a linha ($implicit)
// e seu índice (index). O conteúdo fornecido pelo pai usa assim
// dados que pertencem ao filho.
// =========================================================================

import { Component, contentChild, input, TemplateRef } from '@angular/core';
import { NgTemplateOutlet } from '@angular/common';

// o que a tabela passa ao template de cada linha
export interface RowContext<T> {
  $implicit: T; // o valor recuperado por let-row
  index: number; // recuperado por let-i="index"
}

@Component({
  selector: 'app-data-table',
  imports: [NgTemplateOutlet],
  template: `
    <table class="table table-sm align-middle mb-0">
      <thead>
        <tr>
          @for (c of columns(); track c) {
            <th>{{ c }}</th>
          }
        </tr>
      </thead>
      <tbody>
        @for (l of rows(); track l.id; let i = $index) {
          <tr>
            <ng-container [ngTemplateOutlet]="rowTemplate() ?? null" [ngTemplateOutletContext]="{ $implicit: l, index: i }" />
          </tr>
        } @empty {
          <tr>
            <td class="text-muted" [attr.colspan]="columns().length">
              <ng-content select="[empty]">No data.</ng-content>
            </td>
          </tr>
        }
      </tbody>
    </table>
  `,
})
export class DataTable<T extends { id: number }> {
  readonly rows = input.required<T[]>();
  readonly columns = input.required<string[]>();
  protected readonly rowTemplate = contentChild<TemplateRef<RowContext<T>>>('row');
}
  • linha 54: [DataTable<T>] é uma classe genérica: ela exibe linhas de qualquer tipo [T], desde que tenham um [id] (para o [track], linha 39);
  • Linha 57: [contentChild('row')]: um signal que se refere ao elemento do conteúdo projetado marcado com [#row]. Será um [<ng-template>]: uma porção de HTML que não é exibida como está, mas pode ser exibida sob demanda, quantas vezes forem necessárias (um [TemplateRef]);
  • linha 41: a diretiva [ngTemplateOutlet] exibe um template passando-lhe um contexto — um objeto cujas propriedades se tornam variáveis no template. [$implicit] é o valor padrão (linhas 21–24);
  • linhas 43–49: se a lista estiver vazia, o bloco [@empty], com conteúdo projetado ([[empty]]) e conteúdo padrão;
  • linha 45: [[attr.colspan]]: um binding de atributo, já que [colspan] não é uma propriedade do elemento [<td>].

3.3.3. O pai

// =========================================================================
// 12-projection/src/app/app.ts - usando os templates Card e DataTable
// =========================================================================

import { Component, computed, signal } from '@angular/core';
import { Card } from './card/card';
import { DataTable } from './data-table/data-table';

interface Slot {
  id: number;
  time: string;
  patient: string | null;
}

@Component({
  selector: 'app-root',
  imports: [Card, DataTable],
  templateUrl: './app.html',
})
export class App {
  protected readonly slots = signal<Slot[]>([
    { id: 1, time: '8:00 - 8:20', patient: null },
    { id: 2, time: '8:20 - 8:40', patient: 'Mme Alice DURAND' },
    { id: 3, time: '8:40 - 9:00', patient: null },
  ]);
  protected readonly free = computed(() => this.slots().filter((c) => c.patient === null).length);
  protected readonly nobody: { id: number; name: string }[] = [];
}
<div class="container py-4" style="max-width: 720px">
  <h1 class="h3 mb-3">Example 12 - content projection</h1>

  <app-card color="primary">
    <!-- o atributo header: este <span> irá para o <ng-content select="[header]"> -->
    <span header>Schedule of Mme PELISSIER</span>
    <!-- tudo o que não tem header nem footer vai para o <ng-content /> principal -->
    <app-data-table [rows]="slots()" [columns]="['#', 'Slot', 'Status']">
      <!-- o template de uma linha: let-c recebe a linha, let-i seu índice -->
      <ng-template #row let-c let-i="index">
        <td>{{ i + 1 }}</td>
        <td>{{ c.time }}</td>
        <td>
          @if (c.patient) {
            <span class="badge text-bg-secondary">{{ c.patient }}</span>
          } @else {
            <span class="badge text-bg-success">Free</span>
          }
        </td>
      </ng-template>
    </app-data-table>
    <span footer>{{ free() }} free slot(s)</span>
  </app-card>

  <app-card color="success">
    <span header>A card without a footer</span>
    <p class="mb-0">The footer is not provided: the card does not display it.</p>
  </app-card>

  <app-card>
    <!-- nenhum header fornecido: o conteúdo padrão, "Untitled" -->
    <app-data-table [rows]="nobody" [columns]="['Name']">
      <span empty>Nobody for now.</span>
    </app-data-table>
  </app-card>
</div>
  • linhas 4–23: um cartão azul. Seu conteúdo é distribuído pelo cartão: [<span header>] (linha 6) vai para o cabeçalho, [<span footer>] (linha 22) para o rodapé, e o restante (a tabela) para o corpo;
  • linhas 10–20: o template de uma linha. [let-c] recupera o valor [$implicit] do contexto (a linha), e [let-i="index"] recupera a propriedade [index] dele. O conteúdo fornecido pelo pai usa, assim, dados que pertencem ao filho;
  • linhas 25–28: um card sem rodapé;
  • linhas 30–35: um card sem cabeçalho (o conteúdo padrão, “Untitled”) e uma tabela vazia.

[npm start 12-projection]:

Image

O compilador não reconhece o tipo de [c] no template (linhas 10–20): ele o trata como [any]. É possível remediar isso (com uma diretiva que declare o tipo do contexto), ao custo de um pouco mais de código; essa é a limitação desta técnica.

3.4. Exemplo 13: o ciclo de vida de um componente

Um componente é criado, exibido, existe e depois desaparece. [Angular] permite agir em cada etapa: este é o ciclo de vida do componente.

3.4.1. Um relógio

Um relógio inicia um temporizador ao ser criado... e deve interrompê-lo ao desaparecer: caso contrário, o temporizador continuaria rodando sem motivo (vazamento de memória).

// =========================================================================
// 13-lifecycle/src/app/clock/clock.ts
// -------------------------------------------------------------------------
// O ciclo de vida de um componente:
//   1. constructor      : a classe é criada; os inputs ainda não
//                         estão disponíveis;
//   2. ngOnInit         : os inputs receberam seu primeiro valor;
//   3. afterNextRender  : o componente é EXIBIDO, seus elementos HTML
//                         existem na página;
//   4. ngOnDestroy      : o componente está prestes a ser REMOVIDO da página.
// Um relógio inicia um timer (setInterval) na partida... e deve
// obrigatoriamente pará-lo quando desaparece: caso contrário o timer
// continuaria rodando à toa (vazamento de memória).
// =========================================================================

import { afterNextRender, Component, OnDestroy, OnInit, output, signal } from '@angular/core';

@Component({
  selector: 'app-clock',
  template: `<div class="display-6 font-monospace">{{ time() }}</div>`,
})
// implements OnInit, OnDestroy: o TypeScript verifica se os métodos existem
export class Clock implements OnInit, OnDestroy {
  readonly log = output<string>();
  protected readonly time = signal(new Date().toLocaleTimeString());
  private timer: number | undefined;

  constructor() {
    console.log('Clock: constructor'); // o pai ainda não escuta log
    // afterNextRender é registrado no constructor; a função é
    // chamada uma vez, logo após a primeira exibição do componente
    afterNextRender(() => this.log.emit('Clock: afterNextRender - displayed'));
  }

  ngOnInit(): void {
    this.log.emit('Clock: ngOnInit - starting the timer');
    this.timer = window.setInterval(() => this.time.set(new Date().toLocaleTimeString()), 1000);
  }

  ngOnDestroy(): void {
    window.clearInterval(this.timer);
    this.log.emit('Clock: ngOnDestroy - timer stopped');
  }
}

As etapas:

  • linhas 28–33: o constructor: a classe é criada. As entradas ainda não receberam valores, e o pai ainda não está escutando as saídas (daí o [console.log] na linha 29, em vez de um [emit]);
  • linhas 35–38: [ngOnInit()]: as entradas receberam seus primeiros valores. É o lugar habitual para disparar ações que dependem delas: um carregamento, um temporizador;
  • linha 32: [afterNextRender(function)], chamado no constructor, registra uma função executada uma única vez, logo depois que o componente é exibido pela primeira vez: seus elementos HTML passam então a existir na página;
  • linhas 40–43: [ngOnDestroy()]: o componente está prestes a ser removido da página. O temporizador é interrompido.

[implements OnInit, OnDestroy] (linha 23) não é obrigatório: [Angular] chama [ngOnInit] se ele existir. Mas [TypeScript] então verifica se os métodos estão escritos corretamente.

[Angular] oferece etapas adicionais, menos úteis desde a introdução dos signals: [ngOnChanges] (uma entrada mudou; para isso, preferimos um [computed] ou um [effect] sobre essa entrada), [ngAfterViewInit]... E uma alternativa a [ngOnDestroy]: [inject(DestroyRef).onDestroy(function)], que o Exemplo 14 usará.

3.4.2. O pai

// =========================================================================
// 13-lifecycle/src/app/app.ts
// -------------------------------------------------------------------------
//   - @if em volta de <app-clock>: marcar / desmarcar a caixa cria / destrói
//     o componente (ngOnInit / ngOnDestroy, veja clock.ts);
//   - viewChild('field'): um signal que fornece o elemento HTML marcado com #field
//     no template (undefined enquanto não for exibido);
//   - effect: executado uma primeira vez, depois a cada mudança dos
//     signals que ele lê. Aqui, para dar o foco ao campo assim que ele
//     aparece, e para que o título da aba acompanhe o que é digitado.
// =========================================================================

import { Component, effect, ElementRef, OnInit, signal, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { Clock } from './clock/clock';

@Component({
  selector: 'app-root',
  imports: [FormsModule, Clock],
  templateUrl: './app.html',
})
export class App implements OnInit {
  protected readonly withClock = signal(true);
  protected readonly log = signal<string[]>([]);
  protected readonly search = signal('');
  protected readonly showSearch = signal(false);

  // o elemento <input #field> do template; ElementRef.nativeElement: o elemento HTML
  private readonly field = viewChild<ElementRef<HTMLInputElement>>('field');

  constructor() {
    // o campo aparece (viewChild muda): damos o foco a ele
    effect(() => this.field()?.nativeElement.focus());
    // o título da aba acompanha o que é digitado, desde o início
    effect(() => {
      const text = this.search();
      document.title = text ? `Search: ${text}` : 'Example 13';
    });
  }

  ngOnInit(): void {
    this.trace('App: ngOnInit');
  }

  protected trace(message: string): void {
    this.log.update((j) => [...j, `${new Date().toLocaleTimeString()} ${message}`]);
  }
}
  • linha 29: [viewChild('field')]: um signal que se refere ao elemento do template marcado com [#field]. Ele vale [undefined] enquanto o elemento não existir (o campo só aparece após um clique). [ElementRef] encapsula o elemento HTML, acessível por meio de sua propriedade [nativeElement];
  • linha 33: um [effect] que lê esse signal: quando o campo aparece, o effect é disparado novamente e dá foco a ele. Não é preciso “esperar” a atualização da página: o signal só muda depois que o elemento foi criado;
  • linhas 35–38: um segundo effect: o título da aba é atualizado à medida que o texto é digitado, desde o início (um effect sempre é executado uma vez no começo);
  • linhas 41–43: o elemento pai também tem o seu próprio [ngOnInit].
<div class="container py-4" style="max-width: 720px">
  <h1 class="h3 mb-3">Example 13 - the lifecycle of a component</h1>

  <div class="card p-3 mb-3">
    <label class="form-check-label mb-2">
      <input type="checkbox" class="form-check-input" [(ngModel)]="withClock"> show the clock
    </label>
    @if (withClock()) {
      <app-clock (log)="trace($event)" />
    }
  </div>

  <div class="card p-3 mb-3">
    @if (!showSearch()) {
      <button class="btn btn-outline-primary align-self-start" (click)="showSearch.set(true)">Search...</button>
    } @else {
      <!-- #field: o elemento designado por viewChild('field') -->
      <input #field class="form-control" placeholder="the tab title follows what you type" [(ngModel)]="search">
    }
  </div>

  <h2 class="h6">Log</h2>
  <ol class="small">
    @for (line of log(); track $index) {
      <li>{{ line }}</li>
    }
  </ol>
</div>
  • linhas 8–10: marcar ou desmarcar a caixa cria ou destrói o relógio: [@if] realmente adiciona ou remove o componente da página;
  • linha 18: [#field], o elemento referenciado por [viewChild('field')].

[npm start 13-lifecycle]; desmarque e marque novamente a caixa e clique em “Search...”:

Image

O log mostra a ordem das etapas: primeiro o pai ([App: ngOnInit]), depois o relógio ([ngOnInit], [afterNextRender]), sua destruição ([ngOnDestroy]) e um novo relógio. O campo de busca está com o foco.

3.5. Exemplo 14: serviços e injeção de dependência

Um serviço é uma classe que reúne dados e código compartilhados por vários componentes: acesso ao servidor, o usuário conectado, um carrinho de compras etc. Os componentes não criam serviços (nunca [new CartService()]): eles os solicitam ao [Angular], por meio da função [inject()]. Esta é a injeção de dependência, o mecanismo que o curso de [NestJS] apresentou no lado do servidor.

Quando um componente solicita um serviço, o [Angular] procura quem o fornece: o próprio componente, depois o pai, o pai do pai... até chegar à aplicação. Dependendo de onde é fornecido, um serviço é, portanto, mais ou menos compartilhado. Este exemplo mostra três níveis.

3.5.1. Um serviço root

import { Injectable, signal } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class LogService {
  private readonly _lines = signal<string[]>([]);
  // asReadonly(): os componentes LEEM as linhas; somente o serviço as modifica
  readonly lines = this._lines.asReadonly();

  trace(message: string): void {
    this._lines.update((l) => [`${new Date().toLocaleTimeString()} ${message}`, ...l].slice(0, 6));
  }
}
  • linha 14: [@Injectable({ providedIn: 'root' })]: o serviço é fornecido na raiz da aplicação. O [Angular] cria uma única instância na primeira vez que ele é solicitado, e todos que o solicitam recebem essa instância;
  • linhas 16–18: os dados das linhas são privados; [asReadonly()] fornece uma versão pública e somente leitura deles. Os componentes leem as linhas; apenas o serviço as modifica (linha 21). Esta é a organização padrão para um serviço que mantém estado.

3.5.2. Um serviço fornecido por um componente

import { computed, inject, Injectable, signal } from '@angular/core';
import { LogService } from './log.service';

export interface Item {
  label: string;
  price: number;
}

@Injectable()
export class CartService {
  // um serviço pode ele mesmo solicitar outros serviços
  private readonly log = inject(LogService);

  private readonly _items = signal<Item[]>([]);
  readonly items = this._items.asReadonly();
  readonly total = computed(() => this._items().reduce((sum, a) => sum + a.price, 0));

  add(item: Item): void {
    this._items.update((a) => [...a, item]);
    this.log.trace(`cart: + ${item.label}`);
  }

  remove(index: number): void {
    this.log.trace(`cart: - ${this._items()[index].label}`);
    this._items.update((a) => a.filter((_, i) => i !== index));
  }
}
  • linha 19: [@Injectable()] SEM [providedIn]: o serviço não é fornecido por padrão em lugar nenhum. Um componente o fornecerá em seu array [providers];
  • linha 22: um serviço pode, ele próprio, solicitar outros serviços: o carrinho de compras é registrado no log;
  • linhas 24–26: o estado do carrinho de compras (privado), sua versão somente leitura e o total;
  • linhas 28–36: as duas ações que alteram o estado.

3.5.3. Um serviço configurado

import { DestroyRef, inject, Injectable, InjectionToken, signal } from '@angular/core';

// factory: o valor usado se ninguém fornecer este token
export const CLOCK_PERIOD = new InjectionToken<number>('period of the clock', { factory: () => 1000 });

@Injectable()
export class ClockService {
  private readonly period = inject(CLOCK_PERIOD);
  readonly now = signal(new Date());

  constructor() {
    const timer = window.setInterval(() => this.now.set(new Date()), this.period);
    inject(DestroyRef).onDestroy(() => window.clearInterval(timer));
  }
}
  • linha 15: um token de injeção ([InjectionToken]) refere-se a um valor que não é uma classe: neste caso, um número — o período do relógio. [factory] fornece o valor usado caso ninguém forneça esse token;
  • linha 19: o valor do token é solicitado da mesma forma que um serviço;
  • linha 24: [DestroyRef] representa o “tempo de vida” do componente que forneceu o serviço; [onDestroy] registra uma função a ser executada quando ele for destruído: o temporizador para junto com o componente que forneceu o relógio.

[inject()] só é chamado em um contexto de injeção: na inicialização das propriedades de uma classe criada pelo [Angular] (componente, serviço, diretiva, pipe) ou em seu constructor. Ele não pode ser chamado depois, dentro de um método comum.

3.5.4. Componentes

Um catálogo que adiciona itens ao carrinho de compras:

// 14-services/src/app/catalog/catalog.ts - um descendente que INJETA o carrinho
import { Component, inject } from '@angular/core';
import { Item, CartService } from '../services/cart.service';

@Component({
  selector: 'app-catalog',
  template: `
    <ul class="list-group">
      @for (a of catalog; track a.label) {
        <li class="list-group-item d-flex justify-content-between align-items-center">
          {{ a.label }} (€{{ a.price }})
          <button class="btn btn-sm btn-outline-primary" (click)="cart.add(a)">Add</button>
        </li>
      }
    </ul>
  `,
})
export class Catalog {
  // o carrinho fornecido por App (erro em tempo de execução se ninguém o fornecer)
  protected readonly cart = inject(CartService);

  protected readonly catalog: Item[] = [
    { label: 'Consultation', price: 30 },
    { label: 'Vaccine', price: 12.5 },
    { label: 'Certificate', price: 5 },
  ];
}
  • linha 20: [inject(CartService)]: o carrinho de compras fornecido por um pai ([App]). Se ninguém o tivesse fornecido, o [Angular] relataria um erro em tempo de execução;
  • Linha 12: o template chama diretamente um método do serviço.

Um resumo do carrinho de compras:

import { Component, inject } from '@angular/core';
import { DatePipe } from '@angular/common';
import { CartService } from '../services/cart.service';
import { ClockService, CLOCK_PERIOD } from '../services/clock.service';

@Component({
  selector: 'app-cart-summary',
  imports: [DatePipe],
  // uma nova instância de ClockService para ESTE componente, com outro
  // período: { provide: token, useValue: value }
  providers: [ClockService, { provide: CLOCK_PERIOD, useValue: 5000 }],
  template: `
    <div class="card p-3">
      <h2 class="h6">Cart ({{ cart.items().length }} item(s)) - {{ clock.now() | date: 'HH:mm:ss' }}</h2>
      <ul class="mb-2">
        @for (a of cart.items(); track $index) {
          <li>{{ a.label }} <a href="#" (click)="$event.preventDefault(); cart.remove($index)">remove</a></li>
        }
      </ul>
      <strong>Total: €{{ cart.total() }}</strong>
    </div>
  `,
})
export class CartSummary {
  protected readonly cart = inject(CartService);
  protected readonly clock = inject(ClockService);
}
  • linha 18: o componente fornece seu próprio relógio (uma nova instância de [ClockService]) e outro período: [{ provide: token, useValue: value }];
  • Linhas 32–33: o carrinho de compras é o de [App] (o mesmo do catálogo); o relógio é o próprio componente.

E o componente raiz:

import { Component, inject } from '@angular/core';
import { DatePipe } from '@angular/common';
import { Catalog } from './catalog/catalog';
import { CartSummary } from './cart-summary/cart-summary';
import { ClockService } from './services/clock.service';
import { LogService } from './services/log.service';
import { CartService } from './services/cart.service';

@Component({
  selector: 'app-root',
  imports: [DatePipe, Catalog, CartSummary],
  providers: [CartService, ClockService],
  templateUrl: './app.html',
})
export class App {
  protected readonly clock = inject(ClockService);
  protected readonly log = inject(LogService);
}
  • linha 23: [App] fornece um carrinho (compartilhado por ele e por todos os seus descendentes) e um relógio (período padrão: um segundo);
  • linha 28: o log, serviço root.
<div class="container py-4" style="max-width: 720px">
  <h1 class="h3 mb-3">Example 14 - services and dependency injection</h1>
  <p class="text-muted">Clock of App: {{ clock.now() | date: 'HH:mm:ss' }}</p>
  <div class="row g-3">
    <div class="col-md-6"><app-catalog /></div>
    <div class="col-md-6"><app-cart-summary /></div>
  </div>
  <h2 class="h6 mt-3">Log (LogService)</h2>
  <ul class="small">
    @for (line of log.lines(); track $index) {
      <li>{{ line }}</li>
    }
  </ul>
</div>

[npm start 14-services]; três itens são adicionados e um é removido:

Image

Os dois temporizadores não avançam no mesmo ritmo: cada componente recebeu a instância mais próxima dele. O carrinho de compras, por sua vez, é compartilhado pelo catálogo e pelo resumo.

Os serviços são o meio, no [Angular], de compartilhar lógica e dados entre componentes (o papel desempenhado pelos “composables” e por [provide] / [inject] no [Vue.js]). O Exemplo 20 transformará isso em um estado compartilhado por toda a aplicação.

3.6. Exemplo 15: escrevendo suas próprias diretivas

Um componente é uma diretiva que possui um template. Uma diretiva “sozinha” não possui um: ela se anexa a um elemento existente (seu host) para modificar sua aparência ou seu comportamento. [Angular] fornece algumas ([ngModel], [routerLink], [ngTemplateOutlet]...); você pode escrever as suas. Eis três exemplos.

3.6.1. Destacar um elemento ao passar o mouse

// =========================================================================
// 15-directives/src/app/directives/highlight.directive.ts
// -------------------------------------------------------------------------
// Uma DIRETIVA DE ATRIBUTO adiciona um comportamento a um elemento existente,
// sem template próprio: <li appHighlight="gold">. Seu selector é um
// seletor de atributo CSS ([appHighlight]).
// host: os bindings que a diretiva define no elemento que a carrega
// (seu "host"):
//   - '[style.background-color]' : uma propriedade do elemento;
//   - '(mouseenter)'             : um evento do elemento.
// =========================================================================

import { Directive, input, signal } from '@angular/core';

@Directive({
  selector: '[appHighlight]',
  host: {
    '[style.background-color]': 'hovered() ? color() : null',
    '[style.transition]': '"background-color 0.2s"',
    '(mouseenter)': 'hovered.set(true)',
    '(mouseleave)': 'hovered.set(false)',
  },
})
export class HighlightDirective {
  // o input tem o nome do selector: <li appHighlight="gold"> o define
  readonly color = input('#fff3cd', { alias: 'appHighlight', transform: (c: string) => c || '#fff3cd' });
  protected readonly hovered = signal(false);
}
  • linha 15: [@Directive] em vez de [@Component]: sem template;
  • linha 16: o seletor é um seletor CSS de atributo: a diretiva se aplica a qualquer elemento que tenha o atributo [appHighlight];
  • linhas 17–22: [host]: os bindings que a diretiva aplica ao seu host, escritos como em um template:
    • linha 18: um binding de propriedade: a cor de fundo do host quando o mouse passa sobre ele ([null]: sem cor);
    • linhas 20–21: bindings de evento: entrada e saída do mouse;
  • Linha 26: uma entrada com o nome do seletor (opção [alias]): [<li appHighlight="gold">] preenche ao mesmo tempo o seletor e a entrada. A função [transform] substitui uma string vazia pela cor padrão.

3.6.2. Dar foco

// =========================================================================
// 15-directives/src/app/directives/autofocus.directive.ts
// -------------------------------------------------------------------------
// <input appAutofocus>: o campo recebe o foco assim que é exibido.
// inject(ElementRef) fornece o elemento HTML host (nativeElement).
// (O atributo HTML autofocus só funciona quando a página carrega;
// em uma aplicação de página única, os campos aparecem depois.)
// =========================================================================

import { afterNextRender, Directive, ElementRef, inject } from '@angular/core';

@Directive({ selector: '[appAutofocus]' })
export class AutofocusDirective {
  constructor() {
    const element = inject<ElementRef<HTMLElement>>(ElementRef).nativeElement;
    afterNextRender(() => element.focus());
  }
}
  • linha 15: [inject(ElementRef)] especifica o elemento host;
  • linha 16: o foco é dado a ele assim que é exibido. O atributo HTML [autofocus] só funciona quando a página é carregada; em uma aplicação de página única, os campos aparecem depois.

3.6.3. Um clique longo

Uma diretiva também pode disparar eventos. Esta dispara seu evento somente se o host for mantido pressionado por um segundo: uma proteção contra cliques acidentais.

// =========================================================================
// 15-directives/src/app/directives/long-press.directive.ts
// -------------------------------------------------------------------------
// Uma diretiva também pode EMITIR eventos (output):
//     <button (appLongPress)="remove()">
// O evento só é emitido se o botão for mantido pressionado por um segundo:
// uma proteção contra cliques acidentais. Durante o pressionamento, a classe
// CSS "pressed" é definida no botão.
// =========================================================================

import { DestroyRef, Directive, inject, input, output, signal } from '@angular/core';

@Directive({
  selector: '[appLongPress]',
  host: {
    '[class.pressed]': 'pressing()',
    '(pointerdown)': 'start()',
    '(pointerup)': 'stop()',
    '(pointerleave)': 'stop()',
  },
})
export class LongPressDirective {
  readonly duration = input(1000); // em milissegundos
  readonly appLongPress = output<void>();
  protected readonly pressing = signal(false);
  private timer: number | undefined;

  constructor() {
    inject(DestroyRef).onDestroy(() => window.clearTimeout(this.timer));
  }

  protected start(): void {
    this.pressing.set(true);
    this.timer = window.setTimeout(() => {
      this.pressing.set(false);
      this.appLongPress.emit();
    }, this.duration());
  }

  protected stop(): void {
    window.clearTimeout(this.timer);
    this.pressing.set(false);
  }
}
  • linha 16: enquanto o host está pressionado, a classe [pressed] é aplicada ao host;
  • linhas 17–19: eventos de ponteiro (mouse, dedo, caneta): pressionar, soltar, sair do elemento;
  • linha 24: uma saída com o nome do seletor: escrevemos [(appLongPress)="..."], e aplicamos a diretiva ao mesmo tempo que escutamos seu evento;
  • linha 29: o temporizador é interrompido se o host desaparecer.

3.6.4. Uso

// =========================================================================
// 15-directives/src/app/app.ts - escrevendo suas próprias diretivas
// -------------------------------------------------------------------------
// Um componente é uma diretiva COM um template. Uma diretiva "simples"
// não tem template: ela se anexa a um elemento existente para
// modificar sua aparência ou seu comportamento. Como um componente, ela deve
// ser importada pelo componente que a usa.
// =========================================================================

import { Component, signal } from '@angular/core';
import { AutofocusDirective } from './directives/autofocus.directive';
import { LongPressDirective } from './directives/long-press.directive';
import { HighlightDirective } from './directives/highlight.directive';

@Component({
  selector: 'app-root',
  imports: [AutofocusDirective, LongPressDirective, HighlightDirective],
  templateUrl: './app.html',
  styles: `
    .pressed {
      outline: 4px solid #dc3545;
    }
  `,
})
export class App {
  protected readonly doctors = signal(['Mme Marie PELISSIER', 'Mr Paul TATOU', 'Melle Sophie DUPONT']);
  protected readonly message = signal('');

  protected remove(name: string): void {
    this.doctors.update((m) => m.filter((x) => x !== name));
    this.message.set(`${name} has been deleted.`);
  }
}
  • linha 17: como um componente, uma diretiva deve ser importada pelo componente que a utiliza;
  • linhas 19–23: o estilo da classe [pressed], definida pela diretiva de clique longo.
<div class="container py-4" style="max-width: 640px">
  <h1 class="h3 mb-3">Example 15 - writing your own directives</h1>
  <!-- appAutofocus: o campo recebe o foco assim que a página é exibida -->
  <input appAutofocus class="form-control mb-3" placeholder="this field received the focus by itself">

  <p class="small text-muted">Hover over the rows; hold a button down for one second to delete.</p>
  <ul class="list-group mb-3">
    @for (m of doctors(); track m; let even = $even) {
      <!-- appHighlight: sem valor, a cor padrão; com um valor, a cor informada -->
      <li class="list-group-item d-flex justify-content-between align-items-center"
          [appHighlight]="even ? '' : '#d1e7dd'">
        {{ m }}
        <button class="btn btn-sm btn-outline-danger" (appLongPress)="remove(m)">Delete (long press)</button>
      </li>
    }
  </ul>
  @if (message()) {
    <p class="alert alert-info">{{ message() }}</p>
  }
</div>
  • Linha 4: o campo terá o foco assim que for exibido;
  • linha 8: [let even = $even]: o número da linha é par?
  • linha 11: uma linha sim, outra não, é destacada com a cor padrão, e a outra, em verde;
  • Linha 13: um clique longo remove o médico.

[npm start 15-directives]; mantenha pressionado o segundo botão e depois passe o mouse sobre a primeira linha:

Image

3.7. Exemplo 16: uma janela de confirmação reutilizável

Antes de excluir um item, pede-se ao usuário que confirme. O navegador fornece [window.confirm()], mas sua janela não pode ser formatada nem traduzida. Este exemplo a substitui por uma janela [Bootstrap], combinando o que os exemplos anteriores demonstraram: um serviço (Exemplo 14) que carrega o estado da janela em um signal e um componente que a exibe. O estudo de caso usará exatamente esse mecanismo.

1
2
3
4
5
6
16-confirmation/src/app/
├── confirmation/
│   ├── confirmation.service.ts   the service: the question asked, the answer
│   └── confirm-dialog.ts         the modal dialog
├── app.ts
└── app.html

3.7.1. O serviço

// =========================================================================
// 16-confirmation/src/app/confirmation/confirmation.service.ts
// -------------------------------------------------------------------------
// "Are you sure?": window.confirm() existe, mas não pode ser
// estilizado, nem seus botões podem ser traduzidos. Nós o substituímos por um
// diálogo Bootstrap (confirm-dialog.ts), controlado por este serviço.
//
// O truque: confirm(message) retorna uma PROMISE, resolvida com true (Sim)
// ou false (Não) quando o usuário responde. O código chamador é
// então escrito tão simplesmente quanto com window.confirm:
//
//     if (await this.confirmation.confirm('Delete this doctor?')) { ... }
//
// providedIn: 'root': um único serviço para a aplicação inteira, portanto um único
// diálogo, colocado uma só vez no componente raiz.
// =========================================================================

import { Injectable, signal } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class ConfirmationService {
  private readonly _message = signal<string | null>(null); // null: diálogo fechado
  readonly message = this._message.asReadonly();
  private answer: ((yes: boolean) => void) | null = null;

  confirm(text: string): Promise<boolean> {
    this.answer?.(false); // uma pergunta ainda aberta? conta como "não"
    this._message.set(text);
    return new Promise<boolean>((resolve) => {
      this.answer = resolve;
    });
  }

  respond(yes: boolean): void {
    this._message.set(null);
    const r = this.answer;
    this.answer = null;
    r?.(yes);
  }
}
  • linha 20: um único serviço para toda a aplicação; portanto, haverá apenas uma janela, colocada uma vez por todas no componente raiz;
  • linha 22: a mensagem exibida; [null] significa que a janela está fechada;
  • linha 23: [asReadonly()]: os componentes podem ler a mensagem, mas somente o serviço pode modificá-la;
  • linha 24: a função que resolverá a promise atual, que aguarda uma resposta;
  • linhas 26–32: [confirm] abre a janela (linha 28) e retorna uma promise. Sua função [resolve] é guardada à parte (linha 30): a promise só será resolvida mais tarde, quando o usuário clicar em um botão;
  • linha 27: se uma pergunta ainda estivesse aberta, ela seria respondida com “não”: sua promise não ficará pendente para sempre;
  • linhas 34–39: [respond] é chamado pela janela: ele fecha a janela (linha 35) e depois resolve a promise com a resposta do usuário (linha 38).

Esta é a vantagem da promise: o código que faz a pergunta a escreve como uma chamada a [window.confirm()], aguardando a resposta com [await], sem função de callback.

3.7.2. A janela

// =========================================================================
// 16-confirmation/src/app/confirmation/confirm-dialog.ts
// -------------------------------------------------------------------------
// O diálogo modal, colocado UMA ÚNICA VEZ no componente raiz:
//   - mesmas classes Bootstrap de um modal de verdade (.modal, .modal-backdrop),
//     exibido "estaticamente" (show d-block): sem necessidade do JavaScript do
//     Bootstrap;
//   - teclado: Escape = Não; o foco é colocado no botão "No" (a escolha
//     menos perigosa) ao abrir.
// '(document:keydown.escape)' em host: um evento escutado no DOCUMENT
// inteiro, e não no elemento do componente.
// =========================================================================

import { Component, effect, ElementRef, inject, viewChild } from '@angular/core';
import { ConfirmationService } from './confirmation.service';

@Component({
  selector: 'app-confirm-dialog',
  host: { '(document:keydown.escape)': 'confirmation.message() !== null && confirmation.respond(false)' },
  template: `
    @if (confirmation.message(); as message) {
      <div class="modal-backdrop fade show"></div>
      <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
           (click)="$event.target === $event.currentTarget && confirmation.respond(false)">
        <div class="modal-dialog modal-dialog-centered">
          <div class="modal-content">
            <div class="modal-header">
              <h5 class="modal-title">Confirmation</h5>
              <button type="button" class="btn-close" aria-label="Close" (click)="confirmation.respond(false)"></button>
            </div>
            <div class="modal-body">
              <p class="mb-0">{{ message }}</p>
            </div>
            <div class="modal-footer">
              <button #noButton type="button" class="btn btn-secondary" (click)="confirmation.respond(false)">No, go back</button>
              <button type="button" class="btn btn-danger" (click)="confirmation.respond(true)">Yes, confirm</button>
            </div>
          </div>
        </div>
      </div>
    }
  `,
})
export class ConfirmDialog {
  protected readonly confirmation = inject(ConfirmationService);
  private readonly noButton = viewChild<ElementRef<HTMLButtonElement>>('noButton');

  constructor() {
    // ao abrir, o botão "No" aparece: ele recebe o foco
    effect(() => this.noButton()?.nativeElement.focus());
  }
}
  • linha 19: [document:keydown.escape]: o evento é escutado em todo o document, e não no elemento do componente. A tecla Esc responde “não” se houver uma pergunta em aberto;
  • linha 21: a janela só aparece se houver uma mensagem a exibir; [as message] atribui um nome ao valor do signal;
  • Linhas 22–23: as classes de um verdadeiro modal [Bootstrap], exibido diretamente ([show d-block]): o [JavaScript] derivado do [Bootstrap] é desnecessário, já que o [Angular] determina a exibição;
  • linha 24: um clique ao lado da caixa de diálogo (no fundo cinza) responde “não”. [$event.target === $event.currentTarget]: o clique ocorreu no próprio elemento [.modal], e não em um de seus filhos;
  • linhas 35–36: as duas respostas. O botão “No” carrega a variável de template [#noButton];
  • linha 46: [viewChild] (exemplo 13) retorna o elemento marcado com [#noButton] na forma de um signal: ele é igual a [undefined] enquanto a janela estiver fechada;
  • linha 50: um effect que depende desse signal: a cada abertura da janela, o botão “No” aparece, o signal muda e o botão recebe o foco. Escolhemos “No”, a resposta menos perigosa: pressionar a tecla Enter por engano não exclui nada.

3.7.3. Uso

// =========================================================================
// 16-confirmation/src/app/app.ts - usando o diálogo de confirmação
// -------------------------------------------------------------------------
// Mesma página do exemplo 21 do curso de NestJS (links, botões, confirmação),
// mas sem nenhuma ida e volta a um servidor.
// =========================================================================

import { Component, inject, signal } from '@angular/core';
import { ConfirmationService } from './confirmation/confirmation.service';
import { ConfirmDialog } from './confirmation/confirm-dialog';

interface Contact {
  id: number;
  name: string;
}

@Component({
  selector: 'app-root',
  imports: [ConfirmDialog],
  templateUrl: './app.html',
})
export class App {
  private readonly confirmation = inject(ConfirmationService);
  protected readonly contacts = signal<Contact[]>([
    { id: 1, name: 'Jean MARTIN' },
    { id: 2, name: 'Alice DURAND' },
    { id: 3, name: 'Luc GERMAN' },
  ]);
  protected readonly message = signal('');

  // um método async: ele "espera" a resposta do usuário
  protected async remove(c: Contact): Promise<void> {
    if (!(await this.confirmation.confirm(`Delete the contact ${c.name}?`))) {
      this.message.set('Deletion cancelled.');
      return;
    }
    this.contacts.update((list) => list.filter((x) => x.id !== c.id));
    this.message.set(`${c.name} has been deleted.`);
  }

  protected async removeAll(): Promise<void> {
    if (await this.confirmation.confirm(`Delete the ${this.contacts().length} contacts?`)) {
      this.contacts.set([]);
      this.message.set('All the contacts have been deleted.');
    }
  }
}
  • linha 19: o componente raiz importa a janela, que ele colocará em seu template;
  • linha 23: ele solicita o serviço;
  • linhas 32–39: um método [async]. Na linha 33, [await] suspende a execução até que o usuário responda; durante esse tempo, a aplicação continua ativa. O restante do método só é executado se a resposta for “Yes”;
  • linhas 41–46: o mesmo princípio se aplica à exclusão de todos os contatos.
<div class="container py-4" style="max-width: 640px">
  <h1 class="h3 mb-3">Example 16 - a confirmation dialog</h1>
  <ul class="list-group mb-3">
    @for (c of contacts(); track c.id) {
      <li class="list-group-item d-flex justify-content-between align-items-center">
        {{ c.name }}
        <button class="btn btn-sm btn-outline-danger" (click)="remove(c)">Delete</button>
      </li>
    } @empty {
      <li class="list-group-item text-muted">No contact.</li>
    }
  </ul>
  <button class="btn btn-danger" [disabled]="contacts().length === 0" (click)="removeAll()">Delete all</button>
  @if (message()) {
    <p class="alert alert-info mt-3">{{ message() }}</p>
  }
</div>
<!-- o diálogo, UMA ÚNICA VEZ para a aplicação inteira -->
<app-confirm-dialog />
  • linhas 4–11: [@for] pode ser seguido por um bloco [@empty], exibido quando a lista está vazia;
  • linha 13: o botão fica desabilitado quando não resta nada para excluir;
  • linha 19: a janela, posicionada uma vez para toda a aplicação. Qualquer componente pode então abri-la simplesmente chamando o serviço.

[npm start 16-confirmation]; clique no botão [Delete] de Alice DURAND:

Image

No [Vue.js], a janela e seu estado eram fornecidos por um “composable”; no [Angular], é um serviço. O princípio é o mesmo: um estado compartilhado, em um signal, que vários componentes leem e modificam.