Skip to content

2. Primeiros passos com o Angular

2.1. Exemplo 01: a estrutura de uma aplicação Angular

2.1.1. O arquivo package.json

O arquivo [package.json] da pasta de exemplos declara as bibliotecas usadas e os comandos do projeto:

{
  "name": "examples-angular",
  "version": "1.0.0",
  "description": "The small examples of the course [Step-by-step introduction to the Angular framework] - a single installation for all",
  "private": true,
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build"
  },
  "dependencies": {
    "@angular/common": "^22.2.0",
    "@angular/compiler": "^22.2.0",
    "@angular/core": "^22.2.0",
    "@angular/forms": "^22.2.0",
    "@angular/platform-browser": "^22.2.0",
    "@angular/router": "^22.2.0",
    "@ngx-translate/core": "^18.0.0",
    "bootstrap": "^5.3.8",
    "rxjs": "~7.8.0",
    "tslib": "^2.8.0"
  },
  "devDependencies": {
    "@angular/build": "^22.2.0",
    "@angular/cli": "^22.2.0",
    "@angular/compiler-cli": "^22.2.0",
    "typescript": "~6.0.2"
  }
}

Vamos analisar este arquivo:

  • Linhas 6–10: os comandos do projeto, executados por [npm run <name>] (ou [npm start] para o comando [start]):
    • [npm start 05-ngmodel] executa [ng serve 05-ngmodel]: o servidor de desenvolvimento do exemplo 05;
    • [npm run build 05-ngmodel] executa [ng build 05-ngmodel]: a versão de produção do exemplo 05, localizada na pasta [dist/05-ngmodel/];
    • [npm run ng -- <arguments>] dá acesso a todos os comandos da ferramenta [ng];
  • Linhas 11–22: as bibliotecas necessárias à aplicação no navegador: os pacotes do [Angular] ([@angular/core], o núcleo; [@angular/common], ferramentas comuns, incluindo o cliente HTTP; [@angular/forms], formulários; [@angular/router], o roteador; [@angular/platform-browser], a inicialização no navegador; [@angular/compiler], o compilador de templates; [ngx-translate] para os idiomas; [Bootstrap] para a formatação, [RxJS] para os observables e [tslib], uma pequena biblioteca auxiliar usada pelo código gerado pelo [TypeScript];
  • linhas 23–28: as ferramentas de desenvolvimento: a ferramenta de linha de comando [ng] ([@angular/cli]), o compilador do [Angular] ([@angular/compiler-cli]), a ferramenta de build ([@angular/build], que se apoia no [esbuild] e no [Vite]) e o compilador do [TypeScript]. Eles não fazem parte da aplicação entregue aos usuários.

O prefixo [^] em uma versão ([^22.2.0]) permite que o [npm] instale uma versão mais recente da mesma versão principal (22.x.y); o prefixo [~] ([~6.0.2]) permite apenas correções (6.0.x). Todos os pacotes [@angular/...] devem ter a mesma versão.

Em um projeto padrão, este arquivo é criado pelo comando [ng new project-name], que gera uma aplicação [Angular] completa e pronta para executar. Os exemplos deste curso foram escritos à mão para que vinte e cinco deles coubessem em uma única pasta.

2.1.2. O arquivo angular.json

O [angular.json] descreve o workspace: as aplicações que ele contém e como compilá-las e servi-las. Seu início, que descreve o exemplo 01:

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "cli": {
    "packageManager": "npm",
    "analytics": false
  },
  "projects": {
    "01-first-application": {
      "projectType": "application",
      "root": "01-first-application",
      "sourceRoot": "01-first-application/src",
      "prefix": "app",
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "outputPath": "dist/01-first-application",
            "index": "01-first-application/src/index.html",
            "browser": "01-first-application/src/main.ts",
            "tsConfig": "01-first-application/tsconfig.app.json",
            "styles": [
              "node_modules/bootstrap/dist/css/bootstrap.min.css"
            ]
          },
          "configurations": {
            "production": {
              "outputHashing": "all"
            },
            "development": {
              "optimization": false,
              "extractLicenses": false,
              "sourceMap": true
            }
          },
          "defaultConfiguration": "production"
        },
        "serve": {
          "builder": "@angular/build:dev-server",
          "options": {
            "proxyConfig": "proxy.conf.json"
          },
          "configurations": {
            "production": {
              "buildTarget": "01-first-application:build:production"
            },
            "development": {
              "buildTarget": "01-first-application:build:development"
            }
          },
          "defaultConfiguration": "development"
        }
      }
    },
  • linhas 4–7: as configurações da ferramenta [ng] (o gerenciador de pacotes, sem coleta de estatísticas de uso);
  • linha 9: o nome do projeto, aquele informado a [ng serve] ou a [npm start];
  • linhas 11–12: o diretório do projeto e o diretório de código-fonte;
  • linha 13: o prefixo dos seletores de componentes ([app-root], [app-doctor-card]...);
  • Linhas 15–37: o build da aplicação ([ng build]):
    • linha 16: a ferramenta de build;
    • linha 18: a pasta de saída;
    • linhas 19–20: a página HTML da aplicação e seu ponto de entrada [TypeScript];
    • linha 21: a configuração do projeto [TypeScript];
    • linhas 22–24: as folhas de estilo globais da aplicação: aqui, a do [Bootstrap];
    • linhas 26–36: duas configurações: [production] (código otimizado; [outputHashing] inclui um hash do conteúdo no nome de cada arquivo) e [development] (código legível, com “source maps” que permitem depurar o [TypeScript] no navegador). [ng build] usa a primeira por padrão (linha 36);
  • linhas 38–52: o servidor de desenvolvimento ([ng serve]):
    • linha 41: o arquivo de proxy, que só será usado a partir do exemplo 22: qualquer requisição do navegador a um endereço iniciado por [/api] é encaminhada ao servidor JSON do [RdvMedecins]. Voltaremos a isso;
    • linha 51: [ng serve] compila a aplicação usando a configuração [development].

Os outros vinte e quatro exemplos são descritos da mesma forma mais adiante no arquivo (mais de mil linhas no total). Um projeto padrão, criado por [ng new], contém apenas um.

2.1.3. Os arquivos tsconfig.json e tsconfig.app.json

A configuração do [TypeScript] comum a todos os exemplos:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "experimentalDecorators": true,
    "importHelpers": true,
    "resolveJsonModule": true,
    "target": "ES2022",
    "module": "preserve"
  },
  "angularCompilerOptions": {
    "strictInjectionParameters": true,
    "strictInputAccessModifiers": true,
    "strictTemplates": true
  },
  "include": ["*/src/**/*.ts", "common/**/*.ts"]
}
  • linha 3: o modo estrito do [TypeScript] (tipos verificados rigorosamente, inclusive [null] e [undefined]);
  • linhas 4–9: verificações adicionais; em particular, uma variável ou um parâmetro não utilizado é reportado como erro;
  • linha 12: o [Angular] usa os decoradores do [TypeScript] ([@Component], [@Injectable]...);
  • linha 14: um arquivo JSON pode ser importado como módulo (exemplo 21);
  • linhas 15–16: código [JavaScript] moderno (ES2022) e módulos processados pela ferramenta de build;
  • linhas 18–22: verificações específicas do compilador do [Angular]. A mais importante, na linha 21: os templates são verificados como [TypeScript]. Um erro de digitação em um template ([{{ titl }}] em vez de [{{ title }}]) resulta em um erro de compilação, reportado pelo [ng serve] e pelo editor;
  • linha 23: os arquivos exibidos pelo editor ([VS Code]): os de todos os exemplos.

Cada exemplo também tem seu próprio arquivo, [tsconfig.app.json], que usa essa configuração e compila apenas os arquivos DELE:

1
2
3
4
{
  "extends": "../tsconfig.json",
  "include": ["src/**/*.ts"]
}

Assim, um erro em um exemplo não impede que os outros funcionem.

2.1.4. A página index.html

Cada exemplo tem sua própria página HTML. A do exemplo 01:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example 01 - a first application</title>
  <!-- base href: o endereço inicial dos caminhos relativos (veja o roteador) -->
  <base href="/">
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
  <!-- a aplicação Angular é exibida neste elemento (veja src/main.ts) -->
  <app-root></app-root>
</body>
</html>

Esta é a única página que o navegador carregará. Ela é quase vazia:

  • linha 7: o endereço base dos caminhos relativos da página; o roteador (exemplo 17) o utiliza;
  • linha 12: o elemento no qual o [Angular] exibirá a aplicação. Essa não é uma tag HTML conhecida: é o seletor do componente raiz da aplicação.

Não há tags [<script>] nem [<link>] : a ferramenta de build as adiciona automaticamente (o programa compilado, a folha de estilo do [Bootstrap]).

2.1.5. O ponto de entrada: main.ts

// =========================================================================
// 01-first-application/src/main.ts - o ponto de entrada da aplicação
// -------------------------------------------------------------------------
// angular.json designa este arquivo como ponto de entrada ("browser"). Ele
// inicia a aplicação Angular a partir do componente RAIZ (App):
// o Angular procura em index.html o elemento <app-root> (o "selector" de
// App) e exibe nele o HTML do componente.
// =========================================================================

import { bootstrapApplication } from '@angular/platform-browser';
import { App } from './app/app';

// bootstrapApplication(App) retorna uma promise: exibimos um possível
// erro de inicialização no console do navegador
bootstrapApplication(App).catch((error) => console.error(error));
  • Linha 10: a função do [Angular] que inicia uma aplicação em um navegador;
  • linha 11: o componente raiz da aplicação, a classe [App] do arquivo [app/app.ts];
  • linha 15: a aplicação é iniciada a partir desse componente: o [Angular] procura na página o elemento [<app-root>] e exibe nele o HTML de [App].

2.1.6. O componente raiz: app.ts, app.html, app.css

Um componente [Angular] é uma classe [TypeScript] decorada por [@Component]:

// =========================================================================
// 01-first-application/src/app/app.ts - um primeiro componente
// -------------------------------------------------------------------------
// Um componente Angular é uma CLASSE TypeScript, decorada por @Component:
//   - selector    : a tag HTML que o representa (<app-root>);
//   - templateUrl : o arquivo do seu HTML (app.html);
//   - styleUrl    : o arquivo do seu CSS (app.css), que se aplica apenas
//                   a este componente.
// As propriedades e os métodos da classe podem ser usados no template.
// =========================================================================

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

@Component({
  selector: 'app-root',
  templateUrl: './app.html',
  styleUrl: './app.css',
})
export class App {
  // dados "comuns": o template pode exibi-los
  protected readonly title = 'Welcome to Angular';
  protected readonly languages = ['TypeScript', 'HTML', 'CSS'];

  // signal(...): um dado REATIVO. Seu valor é lido ao CHAMÁ-LO
  // (counter()) e alterado com set() ou update(). O Angular então
  // atualiza AUTOMATICAMENTE os pontos da página que o exibem.
  protected readonly counter = signal(0);
  protected readonly time = signal(new Date().toLocaleTimeString());

  // um método chamado pelo botão do template
  protected increment(): void {
    this.counter.update((n) => n + 1);
    this.time.set(new Date().toLocaleTimeString());
  }
}
  • Linhas 14–18: o decorador [@Component] transforma a classe em um componente:
    • linha 15: seu seletor, a tag que o representa em um template ou no [index.html];
    • linha 16: seu arquivo de template, HTML;
    • linha 17: seu arquivo de estilo, CSS;
  • linhas 21–22: dois dados comuns. [protected]: são usados apenas pelo componente e por seu template; [readonly]: não serão substituídos;
  • linha 27: [signal(0)] cria um dado reativo com valor inicial 0. Um signal é uma função: você lê seu valor chamando-o ([this.counter()]) e o altera com [set(value)] ou [update(function)]. Quando ele muda, o [Angular] atualiza todos os locais da página que o exibem;
  • linhas 31–34: um método que modifica dois signals. Ele não altera a página: o [Angular] a atualizará. [update((n) => n + 1)] calcula o novo valor a partir do antigo.

O template do componente:

<!-- 01-first-application/src/app/app.html - o template do componente App -->
<div class="container py-4">
  <!-- {{ expression }}: o valor da expressão, inserido na página -->
  <h1 class="h3">{{ title }}</h1>
  <p>This page is built in the browser, by Angular, from index.html, main.ts and the App component.</p>
  <p>It is written in {{ languages.join(', ') }} ({{ languages.length }} languages).</p>

  <!-- (click): o método a chamar ao clicar (veja o exemplo 04) -->
  <button class="btn btn-primary" (click)="increment()">Click me</button>
  <!-- um signal é lido chamando-o: counter(), não counter -->
  <p class="mt-3 counter">You clicked {{ counter() }} times (last click: {{ time() }}).</p>
</div>
  • Linha 4: a sintaxe [{{ expression }}] (interpolação) insere na página o valor de uma expressão [TypeScript], avaliada no componente ([title] refere-se a [this.title]). O valor é escapado: se [title] contivesse [<b>], [<b>] seria exibido, sem que a tag fosse interpretada;
  • linha 6: a expressão pode ser qualquer coisa: uma chamada de método, um cálculo;
  • linha 9: o clique no botão chama o método [increment] (veja o exemplo 04);
  • linha 11: um signal é exibido chamando-o como método: [{{ counter() }}]. O [Angular] registra que o template lê esse signal: quando ele mudar, esta parte da página será atualizada.

E seu estilo:

1
2
3
4
5
/* esta regra se aplica apenas aos elementos do componente App */
.counter {
  font-weight: bold;
  color: #dd0031;
}

Esta regra se aplica apenas aos elementos DESTE componente: o [Angular] adiciona um atributo único a seus elementos ([_ngcontent-xxx]) e o repassa aos seletores CSS. Isso é o encapsulamento de estilo: dois componentes podem usar a mesma classe CSS sem interferir um no outro.

Um componente também pode escrever seu template e seu estilo diretamente no decorador, usando as propriedades [template] e [styles] em vez de [templateUrl] e [styleUrl]. Os exemplos seguintes mostrarão isso para componentes pequenos.

2.1.7. Execução

No console aberto na pasta [examples-angular]:

npm start 01-first-application

O console exibe (trecho):

1
2
3
4
5
6
7
8
Initial chunk files | Names         |  Raw size
styles.css          | styles        | 276.99 kB |
main.js             | main          |   4.91 kB |

Application bundle generation complete. [2.520 seconds]

Watch mode enabled. Watching for file changes...
  ➜  Local:   http://localhost:4200/

Abra a URL http://localhost:4200/ e clique três vezes no botão:

Image

Dois experimentos para tentar:

  • Altere o texto do título em [app.ts] e salve o arquivo: a página é atualizada imediatamente, sem precisar recarregá-la. O servidor de desenvolvimento monitora os arquivos, recompila as alterações e avisa o navegador;
  • veja o código-fonte da página (Ctrl-U): você verá apenas a página [index.html], quase vazia. A página HTML exibida foi gerada pelo [Angular] dentro do navegador. Para vê-la, use o inspetor das ferramentas do desenvolvedor (F12, aba Elements) ou a extensão [Angular DevTools], que também exibe os componentes e seus dados.

2.2. Exemplo 02: signals

Os signals estão no centro da reatividade do [Angular]. Este exemplo calcula o preço de um item com IVA:

// =========================================================================
// 02-signals/src/app/app.ts - signal, computed, effect, linkedSignal
// -------------------------------------------------------------------------
// Uma pequena calculadora de preços com IVA:
//   - signal       : um valor reativo, lido ao chamá-lo e
//                    modificado com set() / update();
//   - computed     : um valor CALCULADO a partir de outros signals,
//                    recalculado automaticamente quando eles mudam;
//   - effect       : código executado a cada mudança dos signals que ele
//                    lê (um "efeito colateral");
//   - linkedSignal : um signal gravável, mas REINICIADO para um valor calculado
//                    quando outro signal muda.
// =========================================================================

import { Component, computed, effect, linkedSignal, signal, untracked } from '@angular/core';
// FormsModule fornece [(ngModel)], que vincula um campo a um signal (veja o exemplo 05)
import { FormsModule } from '@angular/forms';

@Component({
  selector: 'app-root',
  imports: [FormsModule],
  templateUrl: './app.html',
})
export class App {
  protected readonly label = signal('Pen');
  protected readonly priceExclVat = signal(2.5);
  protected readonly vatRate = signal(20); // em %

  // linkedSignal: a quantidade volta a 1 a cada vez que o item muda,
  // mas o usuário pode modificá-la nesse meio tempo
  protected readonly quantity = linkedSignal({ source: this.label, computation: () => 1 });

  // computed: nunca atribuído diretamente, sempre recalculado. O Angular sabe
  // de quais signals ele depende (os que ele LÊ): recalcula-o quando um
  // deles muda, e somente nesse caso
  protected readonly totalExclVat = computed(() => this.quantity() * this.priceExclVat());
  protected readonly vatAmount = computed(() => (this.totalExclVat() * this.vatRate()) / 100);
  protected readonly totalInclVat = computed(() => this.totalExclVat() + this.vatAmount());

  // um formatador de valores em euros, estilo inglês (€1,234.50)
  private readonly euros = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR' });

  // o histórico dos totais com IVA, preenchido pelo effect abaixo
  protected readonly history = signal<string[]>([]);
  private oldTotal: number | null = null;

  constructor() {
    // effect: executado uma primeira vez, depois a cada mudança de
    // totalInclVat (o único signal que ele lê)
    effect(() => {
      const total = this.totalInclVat();
      document.title = `Incl. VAT: ${this.format(total)}`;
      if (this.oldTotal !== null) {
        const line = `${this.format(this.oldTotal)} -> ${this.format(total)}`;
        // untracked: modifica history SEM torná-lo uma dependência do effect
        untracked(() => this.history.update((h) => [line, ...h].slice(0, 5)));
      }
      this.oldTotal = total;
    });
  }

  protected format(amount: number): string {
    return this.euros.format(amount);
  }

  protected reset(): void {
    this.label.set('Pen');
    this.priceExclVat.set(2.5);
    this.vatRate.set(20);
    this.quantity.set(1);
  }
}
  • linha 15: as funções de reatividade, todas fornecidas por [@angular/core];
  • Linhas 21 e 17: o template usa [[(ngModel)]], que vem do módulo [FormsModule]. Um componente deve importar (array [imports]) tudo o que seu template usa: outros componentes, diretivas e pipes. O compilador reporta um erro se isso for omitido;
  • linhas 25–27: três signals, [signal(initial value)]. O tipo deles é inferido a partir do valor inicial: [signal('Pen')] é um signal de string, [signal(2.5)] é um signal numérico;
  • linha 31: um [linkedSignal] é um signal modificável (pode receber escrita, como um signal comum), mas está vinculado a outro signal, sua origem: sempre que a origem muda (neste caso, a descrição do item), seu valor é redefinido para o valor calculado por [computation] (neste caso, 1). Quando o item muda, a quantidade volta a 1;
  • linhas 36–38: um [computed] é um valor calculado a partir de outros signals. Ele nunca recebe escrita; é lido como um signal ([this.totalExclVat()]). O [Angular] sabe de quais signals ele depende, porque registra os que a função lê durante o cálculo. Ele é recalculado quando um deles muda, e somente nesse caso: ler [totalInclVat()] dez vezes sem que nada mude resulta em um único cálculo. Um [computed] pode depender de outros valores [computed] (linha 38);
  • linha 41: um formatador de valores no estilo inglês (€1,234.50). O exemplo 09 mostrará como fazer isso com [Angular], os pipes;
  • linhas 50–59: um [effect] é uma função executada uma vez e, depois, a cada vez que os signals que ela lê mudam (aqui, apenas [totalInclVat]). Ele serve para efeitos colaterais: realizar ações sobre algo que não seja a página (o título da aba, linha 52; o armazenamento local do navegador; um log);
    • linha 56: o effect adiciona uma entrada ao histórico. [untracked(...)] realiza essa atualização sem fazer de [history] uma dependência do effect; caso contrário, o effect leria [history] (em [update]) e seria disparado novamente toda vez que o histórico mudasse... o que ele mesmo provoca;
    • Um [effect] é criado no construtor do componente (ou na inicialização de uma propriedade): é o que o [Angular] chama de contexto de injeção, que veremos melhor ao tratar de serviços (exemplo 14). Ele é encerrado por conta própria quando o componente é destruído;
  • Linhas 66–71: [set()] substitui o valor de um signal. A quantidade é um [linkedSignal]: pode receber escrita como os demais.

Evite escrever em um signal usando um [effect] quando um [computed] é suficiente: um [computed] descreve um valor, enquanto um [effect] descreve uma ação. Aqui, o histórico depende dos valores sucessivos do total, algo que um [computed] não consegue expressar.

O template:

<div class="container py-4">
  <h1 class="h3 mb-3">Example 02 - signals</h1>
  <div class="row g-4">
    <div class="col-md-6">
      <div class="card p-3">
        <!-- [(ngModel)]="signal": o campo lê o signal e o modifica (veja o exemplo 05) -->
        <label class="form-label" for="label">Item</label>
        <input id="label" class="form-control mb-2" [(ngModel)]="label">
        <label class="form-label" for="price">Unit price excl. VAT</label>
        <input id="price" type="number" step="0.1" min="0" class="form-control mb-2" [(ngModel)]="priceExclVat">
        <label class="form-label" for="quantity">Quantity (back to 1 if the item changes)</label>
        <input id="quantity" type="number" min="0" class="form-control mb-2" [(ngModel)]="quantity">
        <label class="form-label" for="vat">VAT rate</label>
        <select id="vat" class="form-select mb-3" [(ngModel)]="vatRate">
          <!-- [ngValue]: o valor passado é o NÚMERO 5.5, não a string "5.5" -->
          <option [ngValue]="5.5">5.5 %</option>
          <option [ngValue]="10">10 %</option>
          <option [ngValue]="20">20 %</option>
        </select>
        <button class="btn btn-outline-secondary" (click)="reset()">Reset</button>
      </div>
    </div>
    <div class="col-md-6">
      <div class="card p-3">
        <h2 class="h5">{{ quantity() }} x {{ label() }}</h2>
        <table class="table mb-0">
          <tbody>
            <tr><td>Total excl. VAT</td><td class="text-end">{{ format(totalExclVat()) }}</td></tr>
            <tr><td>VAT ({{ vatRate() }} %)</td><td class="text-end">{{ format(vatAmount()) }}</td></tr>
            <tr class="fw-bold"><td>Total incl. VAT</td><td class="text-end">{{ format(totalInclVat()) }}</td></tr>
          </tbody>
        </table>
      </div>
      <div class="card p-3 mt-3">
        <h2 class="h6">History of the total incl. VAT (effect)</h2>
        <ul class="mb-0">
          @for (line of history(); track $index) {
            <li>{{ line }}</li>
          }
        </ul>
      </div>
    </div>
  </div>
</div>
  • linhas 8–18: [[(ngModel)]="label"] vincula o campo ao signal [label] nos dois sentidos: digitar no campo altera o signal, e alterar o signal (com o botão “Reset”) altera o campo. Informamos o próprio signal, sem parênteses: [ngModel] precisa do signal para escrever nele. O exemplo 05 abordará o [ngModel] em detalhes;
  • linhas 10 e 12: com [type="number"], o signal recebe um número, não uma string;
  • linhas 16–18: [[ngValue]] fornece o valor de uma opção: neste caso, o número 5.5, não a string ["5.5"];
  • linhas 25–30: a exibição dos signals e dos [computed]. [format(...)] é um método do componente;
  • linhas 37–39: [@for] repete o bloco para cada item de uma lista (veja o exemplo 03).

Com o servidor de desenvolvimento em execução ([npm start 02-signals]), modificamos o item, o preço, a quantidade e a alíquota:

Image

A cada mudança no total com IVA, o effect adiciona uma linha ao histórico e altera o título da aba. Mudar o item redefine a quantidade para 1.

Esses signals não são específicos do [Angular]: eles também existem no [SolidJS], no [Preact], no [Vue.js] (onde [ref] tem a mesma função), e uma proposta de padrão em rascunho sugere adicioná-los ao próprio [JavaScript] . Antes dos signals (introduzidos no [Angular] 16, em 2023), o [Angular] verificava regularmente toda a árvore de componentes, usando a biblioteca [zone.js], para determinar o que havia mudado. Com os signals, ele sabe exatamente o que atualizar: é o modo “zoneless”, que é o padrão no [Angular] 22 e é usado em todos os exemplos deste curso.

2.3. Exemplo 03: sintaxe de template

Um template [Angular] é HTML enriquecido com alguns elementos de sintaxe. Este exemplo exibe uma lista de médicos que pode ser filtrada:

// =========================================================================
// 03-templates/src/app/app.ts - a sintaxe dos templates
// -------------------------------------------------------------------------
// Em um template Angular:
//   - [property]="expr"   : uma propriedade do elemento, calculada por uma
//                           expressão ([src], [disabled], [hidden]...);
//   - [class.name]="expr" : a classe CSS "name" se a expressão for verdadeira;
//     [style.prop]="expr" : uma propriedade CSS;
//   - @if / @else if / @else: um bloco que só existe se a condição
//                           for verdadeira;
//   - @for (x of list; track x.id): um bloco repetido para cada elemento;
//     track dá a IDENTIDADE de cada elemento; @empty, o bloco exibido
//     quando a lista está vazia;
//   - @switch / @case     : um bloco entre vários, conforme um valor;
//   - @let name = expr;   : uma variável local ao template.
// =========================================================================

import { Component, computed, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';

// uma interface TypeScript descreve a forma dos objetos da lista
interface Doctor {
  id: number;
  title: string;
  firstName: string;
  lastName: string;
  specialty: 'general practitioner' | 'pediatrician' | 'cardiologist';
  available: boolean;
}

@Component({
  selector: 'app-root',
  imports: [FormsModule],
  templateUrl: './app.html',
})
export class App {
  // a imagem está na pasta public/ do exemplo: servida como está
  protected readonly logoUrl = 'doctor.svg';

  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: 'cardiologist', available: true },
  ]);

  protected readonly filter = signal(''); // texto pesquisado
  protected readonly onlyAvailable = signal(false);
  protected readonly showHelp = signal(true);

  // a lista exibida: um computed, recalculado quando o filtro muda
  protected readonly displayedDoctors = computed(() => {
    const text = this.filter().trim().toLowerCase();
    return this.doctors().filter(
      (m) =>
        (!this.onlyAvailable() || m.available) &&
        `${m.firstName} ${m.lastName} ${m.specialty}`.toLowerCase().includes(text),
    );
  });

  protected toggleHelp(): void {
    this.showHelp.update((a) => !a);
  }
}
  • linhas 22–29: uma interface [TypeScript] descreve o formato dos objetos da lista. A especialidade só pode assumir três valores (linha 27);
  • linha 38: o endereço de uma imagem. Os arquivos da pasta [public/] do exemplo são servidos como estão, na raiz do site: [doctor.svg] refere-se ao arquivo [03-templates/public/doctor.svg]. Para isso, é preciso declará-la no [angular.json]:
            "assets": [
              {
                "glob": "**/*",
                "input": "03-templates/public"
              }
            ]
  • linhas 40–44: [signal<Doctor[]>(...)]: um signal cujo tipo é especificado, uma lista de médicos;
  • linhas 46–48: três signals vinculados aos campos da página;
  • linhas 51–58: a lista exibida, um [computed] que depende de três signals ([filter], [doctors], [onlyAvailable]);
  • linha 61: [update] inverte um valor booleano.

O template:

<div class="container py-4">
  <h1 class="h3 mb-3">
    <!-- [src]: o valor da propriedade src é o de logoUrl -->
    <img [src]="logoUrl" alt="logo" width="32" height="32">
    Example 03 - the template syntax
  </h1>

  <div class="d-flex flex-wrap gap-3 align-items-center mb-3">
    <input class="form-control w-auto" placeholder="search..." [(ngModel)]="filter">
    <label class="form-check-label">
      <input type="checkbox" class="form-check-input" [(ngModel)]="onlyAvailable"> available only
    </label>
    <button class="btn btn-sm btn-outline-secondary" (click)="toggleHelp()">
      {{ showHelp() ? "Hide the help" : "Show the help" }}
    </button>
  </div>

  <!-- [hidden]: o parágrafo permanece na página, apenas oculto -->
  <p class="alert alert-info" [hidden]="!showHelp()">
    Type a name or a specialty. Unavailable doctors are greyed out.
  </p>

  <!-- @let: uma variável de template, para não repetir a chamada -->
  @let displayed = displayedDoctors();

  <!-- @if / @else if / @else: apenas um dos três blocos existe por vez -->
  @if (doctors().length === 0) {
    <p class="text-muted">No doctor.</p>
  } @else if (displayed.length === 0) {
    <p class="text-warning">No doctor matches "{{ filter() }}".</p>
  } @else {
    <table class="table">
      <thead>
        <tr><th>#</th><th>Doctor</th><th>Specialty</th><th>Status</th></tr>
      </thead>
      <tbody>
        <!-- @for: uma linha por médico; $index fornece a posição.
             track m.id: a identidade de cada linha, para que o Angular saiba
             qual linha adicionar, mover ou remover quando a lista muda -->
        @for (m of displayed; track m.id; let i = $index) {
          <tr [class.opacity-50]="!m.available">
            <td>{{ i + 1 }}</td>
            <td>{{ m.title }} {{ m.firstName }} {{ m.lastName }}</td>
            <td>
              <!-- @switch: um bloco conforme o valor da especialidade -->
              @switch (m.specialty) {
                @case ('pediatrician') { <span title="children">&#x1F9F8;</span> }
                @case ('cardiologist') { <span title="heart">&#x2764;&#xFE0F;</span> }
                @default { <span title="all patients">&#x1FA7A;</span> }
              }
              {{ m.specialty }}
            </td>
            <td>
              <!-- [class] com uma string: as classes calculadas são adicionadas a "badge" -->
              <span class="badge" [class]="m.available ? 'text-bg-success' : 'text-bg-secondary'">
                {{ m.available ? 'available' : 'unavailable' }}
              </span>
            </td>
          </tr>
        }
      </tbody>
    </table>
  }

  <!-- [style.font-size.px]: uma propriedade CSS, com sua unidade -->
  <p [style.font-size.px]="12 + displayed.length * 2">
    {{ displayed.length }} doctor(s) displayed - the size of this text depends on it.
  </p>
</div>
  • Linha 4: [[src]="logoUrl"] é um binding de propriedade: a propriedade [src] do elemento recebe o valor de a expressão [logoUrl]. Sem os colchetes, [src="logoUrl"] resultaria na string ["logoUrl"]. Qualquer propriedade de um elemento pode ser vinculada dessa maneira: [[disabled]], [[value]], [[hidden]], [[title]]...;
  • linhas 9 e 11: dois campos vinculados a signals por meio de [[(ngModel)]] (veja o exemplo 05);
  • linha 14: a interpolação aceita o operador ternário [? :];
  • linha 19: [[hidden]]: o parágrafo permanece na página, mas fica simplesmente oculto (propriedade HTML [hidden]);
  • linha 24: [@let] declara uma variável de template, visível em todo o restante do template. Isso evita repetir [displayedDoctors()];
  • linhas 27–63: [@if (condition) { ... } @else if (...) { ... } @else { ... }]: apenas um dos três blocos existe na página por vez. Ao contrário de [[hidden]], os elementos de um bloco não selecionado não são criados (ou são removidos);
  • linha 40: [@for (m of displayed; track m.id)] repete o bloco para cada médico:
    • [track m.id] é obrigatório: ele identifica cada linha. Quando a lista muda, o [Angular] compara os identificadores para determinar qual linha adicionar, mover ou excluir, em vez de recriar tudo. Para uma lista de valores simples sem identificador, escreva [track $index] (exemplo 02);
    • [let i = $index]: a posição do elemento. [@for] também fornece [$first], [$last], [$even], [$odd] e [$count];
    • um bloco [@empty { ... }], posicionado após o bloco [@for], aparece quando a lista está vazia (exemplo 16);
  • linha 41: [[class.opacity-50]="condition"]: a classe [opacity-50] (do [Bootstrap]) é aplicada ao elemento se a condição for verdadeira;
  • linhas 46–50: [@switch] seleciona um bloco com base em um valor: um [@case] por valor e [@default] para os demais;
  • linha 55: [[class]="expression"]: a expressão retorna uma ou mais classes, que são adicionadas às classes escritas diretamente ([badge]);
  • linha 66: [[style.font-size.px]="expression"]: uma propriedade CSS, com sua unidade.

Uma expressão de template se parece com [TypeScript], mas é restrita: sem atribuições (exceto em manipuladores de eventos, exemplo 04), sem [new], sem acesso a variáveis globais ([window], [document]). Ela só pode acessar as propriedades e os métodos do componente.

[npm start 03-templates]:

Image

Digite “gen” e oculte a ajuda:

Image

As versões anteriores do [Angular] escreviam esses blocos com diretivas estruturais: [*ngIf], [*ngFor], [[ngSwitch]]. Elas ainda são encontradas em muitos projetos; a sintaxe [@if] / [@for] / [@switch], introduzida no [Angular] 17, é a recomendada atualmente.

2.4. Exemplo 04: eventos

Uma lista de tarefas que responde às ações do usuário. O componente:

// =========================================================================
// 04-events/src/app/app.ts - reagindo às ações do usuário
// -------------------------------------------------------------------------
// (event)="statement": a instrução é executada quando o elemento
// emite este evento:
//   - (click)="f()"            chama f;
//   - (click)="f(3, $event)"   chama f com argumentos; $event é
//                              o evento nativo do navegador;
//   - (keyup.enter), (keydown.escape): apenas para esta tecla;
//   - #name em um elemento: uma "variável de referência" do template, que
//     designa o próprio elemento HTML (name.value, name.focus()...).
// Aqui, sem FormsModule nem ngModel: lemos os campos nós mesmos.
// =========================================================================

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

interface Task {
  id: number;
  label: string;
  done: boolean;
}

@Component({
  selector: 'app-root',
  templateUrl: './app.html',
  styles: `
    .area {
      background: #e9f2ff;
      height: 80px;
      cursor: crosshair;
    }
  `,
})
export class App {
  protected readonly tasks = signal<Task[]>([
    { id: 1, label: 'Install Node.js', done: true },
    { id: 2, label: 'Read the chapter on events', done: false },
  ]);
  protected readonly log = signal<string[]>([]);
  private nextId = 3;

  private trace(message: string): void {
    this.log.update((j) => [`${new Date().toLocaleTimeString()} ${message}`, ...j]);
  }

  // chamado por (submit): $event.preventDefault() impede o navegador
  // de enviar o formulário ao servidor (e de recarregar a página)
  protected add(event: SubmitEvent, field: HTMLInputElement): void {
    event.preventDefault();
    const label = field.value.trim();
    if (label === '') {
      return;
    }
    // um signal contendo um array: nós o SUBSTITUÍMOS por um novo array
    this.tasks.update((t) => [...t, { id: this.nextId++, label, done: false }]);
    this.trace(`added "${label}"`);
    field.value = '';
    field.focus();
  }

  protected toggle(task: Task, done: boolean): void {
    this.tasks.update((t) => t.map((x) => (x.id === task.id ? { ...x, done } : x)));
    this.trace(`"${task.label}": ${done ? 'done' : 'to do'}`);
  }

  protected remove(task: Task): void {
    this.tasks.update((t) => t.filter((x) => x.id !== task.id));
    this.trace(`deleted "${task.label}"`);
  }

  // $event: o evento nativo (aqui um MouseEvent), com suas coordenadas
  protected position(event: MouseEvent): void {
    this.trace(`click at (${event.offsetX}, ${event.offsetY})`);
  }
}
  • linhas 26–32: o estilo do componente, escrito diretamente no decorador ([styles]), em vez de em um arquivo [.css];
  • linhas 35–38: um signal contendo uma lista de objetos;
  • linha 40: uma propriedade comum, que não é exibida: não precisa ser um signal;
  • linhas 48–59: adição de uma tarefa. O método recebe o evento do navegador e o próprio elemento [<input>] (veja o template):
    • linha 49: [preventDefault()] impede que o navegador envie o formulário ao servidor, o que recarregaria a página;
    • linha 55: o array contido no signal ([push]) não é modificado; em vez disso, ele é substituído por um novo array. Um signal só indica uma mudança se seu valor mudar — ou seja, se um objeto DIFERENTE for atribuído a ele. Modificar o conteúdo do array sem substituí-lo deixaria a página inalterada;
    • linhas 57–58: o campo é limpo e mantém o foco;
  • linha 62: mesmo princípio para modificar uma tarefa: [map] cria um novo array, no qual a tarefa em questão é substituída por uma cópia modificada ([{ ...x, done }]);
  • linha 67: e, para excluir uma, [filter];
  • Linhas 72–74: [MouseEvent]: o evento de clique, com a posição do ponteiro.

O template:

<div class="container py-4">
  <h1 class="h3 mb-3">Example 04 - events</h1>

  <!-- (submit): Enter no campo OU clique no botão.
       #newTask: uma referência ao elemento <input>, utilizável em qualquer lugar
       do template -->
  <form class="d-flex gap-2 mb-3" (submit)="add($event, newTask)">
    <input #newTask class="form-control" placeholder="new task (Escape to clear)"
           (keydown.escape)="newTask.value = ''">
    <button type="submit" class="btn btn-primary">Add</button>
  </form>

  <ul class="list-group mb-3">
    @for (t of tasks(); track t.id) {
      <li class="list-group-item d-flex align-items-center gap-2">
        <!-- #box: o checkbox DESTA linha; box.checked: seu estado -->
        <input #box type="checkbox" class="form-check-input" [checked]="t.done"
               (change)="toggle(t, box.checked)">
        <span class="flex-grow-1" [class.text-decoration-line-through]="t.done" [class.text-muted]="t.done">
          {{ t.label }}
        </span>
        <!-- um handler com um argumento: a tarefa DESTA linha -->
        <button class="btn btn-sm btn-outline-danger" (click)="remove(t)">Delete</button>
      </li>
    }
  </ul>

  <div class="area p-3 mb-3 rounded" (click)="position($event)">Click in this area</div>

  <h2 class="h6">Log</h2>
  <ul class="small">
    @for (line of log(); track $index) {
      <li>{{ line }}</li>
    }
  </ul>
</div>
  • linha 7: [(submit)="instruction"] é um binding de evento: a instrução é executada quando o elemento dispara o evento [submit] (entrada no campo ou clique no botão). [$event] refere-se ao evento do navegador;
  • Linha 8: [#newTask] é uma variável de referência de template: ela se refere ao próprio elemento [<input>], em todo o template. Na linha 7, ela é passada ao método [add];
  • Linha 9: [(keydown.escape)]: o evento [keydown], mas apenas para a tecla Esc. Da mesma forma, escrevemos [(keyup.enter)], [(keydown.control.s)]... Em um binding de evento, a atribuição é permitida: [newTask.value = ''] limpa o campo;
  • linhas 17–18: [#box] refere-se ao checkbox DESTA linha do [@for]; [[checked]] marca a caixa de acordo com a tarefa; [(change)] notifica o componente quando o usuário a altera;
  • Linha 23: um manipulador com um argumento: a tarefa desta linha;
  • linha 28: um clique no campo: [$event] é um [MouseEvent].

Aqui, lemos os campos nós mesmos ([field.value], [box.checked]). Os exemplos seguintes delegarão essa tarefa ao [ngModel] e, depois, aos formulários baseados em signals.

[npm start 04-events]; adicione uma tarefa (Enter), marque a segunda e clique no campo:

Image

O [Angular] atualiza a página apenas em resposta a um evento ou a uma mudança de signal. Um evento tratado pelo template ((click), (submit) etc.) basta para disparar uma verificação do componente; já os dados modificados depois — fora de um evento (como em resposta a um servidor ou quando um temporizador dispara) — só serão exibidos se forem um signal. Daí a regra seguida ao longo deste curso: todo dado exibido por um template é um signal.

2.5. Exemplo 05: campos de formulário e ngModel

O mesmo formulário do exemplo 18 do curso [NestJS] (todos os tipos de campo), mas sem servidor: tudo acontece no navegador. Os campos são vinculados a signals por meio da diretiva [ngModel]:

// =========================================================================
// 05-ngmodel/src/app/app.ts - todos os tipos de campo, vinculados por ngModel
// -------------------------------------------------------------------------
// [(ngModel)]="signal" (módulo FormsModule) vincula um campo de formulário a um
// signal, nos DOIS sentidos: digitar no campo modifica o signal, e
// modificar o signal (por código) modifica o campo. A sintaxe [( )], chamada
// "banana in a box", combina [ngModel] (signal para campo) e
// (ngModelChange) (campo para signal). O valor recebido depende do campo:
//   - text input, textarea           -> string
//   - input type="number"            -> number (null se o campo estiver vazio)
//   - checkbox único                -> boolean
//   - radio buttons                  -> o valor do botão escolhido
//   - select / select múltiplo       -> o valor / um array de valores
//   - input type="date"              -> string "yyyy-MM-dd"
// Em um <form>, cada campo vinculado por ngModel deve ter um atributo name.
// Mesmo formulário do exemplo 18 do curso de NestJS; mas aqui, sem
// servidor: tudo acontece no navegador.
// =========================================================================

import { Component, computed, signal } from '@angular/core';
import { JsonPipe } from '@angular/common';
import { FormsModule } from '@angular/forms';

@Component({
  selector: 'app-root',
  // JsonPipe: o "pipe" json, que exibe um objeto em formato JSON (veja o exemplo 09)
  imports: [FormsModule, JsonPipe],
  templateUrl: './app.html',
})
export class App {
  protected readonly titles = ['Mr', 'Mme', 'Melle'];
  protected readonly possibleHobbies = ['sport', 'music', 'reading', 'cinema'];
  protected readonly countries = [
    { code: 'fr', name: 'France' },
    { code: 'be', name: 'Belgium' },
    { code: 'ch', name: 'Switzerland' },
  ];

  // um signal por campo do formulário
  protected readonly title = signal('Mme');
  protected readonly name = signal('');
  protected readonly age = signal<number | null>(30);
  protected readonly presentation = signal('');
  protected readonly newsletter = signal(false);
  protected readonly hobbies = signal<string[]>(['reading']);
  protected readonly country = signal('fr');
  protected readonly languages = signal<string[]>([]);
  protected readonly birthDate = signal('');

  // todos os valores, reunidos em um objeto (o que seria enviado a um servidor)
  protected readonly model = computed(() => ({
    title: this.title(),
    name: this.name().trim(), // ngModel não remove os espaços: fazemos isso aqui
    age: this.age(),
    presentation: this.presentation(),
    newsletter: this.newsletter(),
    hobbies: this.hobbies(),
    country: this.country(),
    languages: this.languages(),
    birthDate: this.birthDate(),
  }));

  protected readonly sent = signal<string | null>(null);

  // vários checkboxes para UM array: o ngModel não consegue, nós cuidamos disso
  protected toggleHobby(hobby: string, checked: boolean): void {
    this.hobbies.update((l) => (checked ? [...l, hobby] : l.filter((x) => x !== hobby)));
  }

  // (ngSubmit): o envio do formulário, sem recarregar a página
  protected send(): void {
    this.sent.set(JSON.stringify(this.model()));
  }
}
  • Linha 22: [FormsModule] inclui a diretiva [ngModel] (assim como [ngSubmit], [ngModelOptions]...): são os chamados formulários “orientados a template” ([template-driven forms]);
  • linha 27: o componente também importa o pipe [json], que exibe um objeto no formato JSON (veja o exemplo 09);
  • linhas 40–48: um signal por campo, com o tipo de valor que o campo fornecerá: uma string, um número (ou [null] se o campo estiver vazio), um booleano ou uma lista de strings;
  • linhas 51–61: todos os valores, agrupados em um único objeto com [computed]: é o que seria enviado a um servidor. [ngModel] não remove os espaços ao redor de uma entrada: fazemos isso aqui (linha 53);
  • linhas 66–68: vários checkboxes para a mesma lista: [ngModel] não consegue tratar isso, então nós nos encarregamos;
  • linhas 71–73: o envio.

O template:

<div class="container py-4">
  <h1 class="h3 mb-3">Example 05 - the fields of a form and ngModel</h1>
  <div class="row g-4">
    <!-- (ngSubmit): com FormsModule, o formulário nunca é enviado ao
         servidor pelo navegador; nosso método é chamado no lugar -->
    <form class="col-md-7" (ngSubmit)="send()">
      <div class="mb-3">
        <span class="form-label d-block">Title</span>
        <!-- radio buttons: o mesmo ngModel, um valor por botão -->
        @for (t of titles; track t) {
          <div class="form-check form-check-inline">
            <input type="radio" class="form-check-input" name="title" [id]="'title-' + t" [value]="t"
                   [(ngModel)]="title">
            <label class="form-check-label" [for]="'title-' + t">{{ t }}</label>
          </div>
        }
      </div>
      <div class="row g-3 mb-3">
        <div class="col-8">
          <label class="form-label" for="name">Name</label>
          <input id="name" name="name" class="form-control" [(ngModel)]="name">
        </div>
        <div class="col-4">
          <label class="form-label" for="age">Age</label>
          <!-- type="number": o signal recebe um número, não a string "30" -->
          <input id="age" name="age" type="number" class="form-control" [(ngModel)]="age">
        </div>
      </div>
      <div class="mb-3">
        <label class="form-label" for="presentation">Presentation (updated when leaving the field)</label>
        <!-- updateOn: 'blur': o signal só é atualizado ao sair do campo -->
        <textarea id="presentation" name="presentation" rows="2" class="form-control"
                  [(ngModel)]="presentation" [ngModelOptions]="{ updateOn: 'blur' }"></textarea>
      </div>
      <div class="mb-3 form-check">
        <!-- um único checkbox: true / false -->
        <input id="newsletter" name="newsletter" type="checkbox" class="form-check-input" [(ngModel)]="newsletter">
        <label for="newsletter" class="form-check-label">Receive the newsletter</label>
      </div>
      <div class="mb-3">
        <span class="form-label d-block">Hobbies</span>
        <!-- vários checkboxes para um array: [checked] + (change) -->
        @for (h of possibleHobbies; track h) {
          <div class="form-check form-check-inline">
            <input #hobbyBox type="checkbox" class="form-check-input" [id]="'hobby-' + h"
                   [checked]="hobbies().includes(h)" (change)="toggleHobby(h, hobbyBox.checked)">
            <label class="form-check-label" [for]="'hobby-' + h">{{ h }}</label>
          </div>
        }
      </div>
      <div class="row g-3 mb-3">
        <div class="col-6">
          <label class="form-label" for="country">Country</label>
          <select id="country" name="country" class="form-select" [(ngModel)]="country">
            <!-- [value]: o valor passado (o código), sendo o texto exibido o nome -->
            @for (c of countries; track c.code) {
              <option [value]="c.code">{{ c.name }}</option>
            }
          </select>
        </div>
        <div class="col-6">
          <label class="form-label" for="languages">Spoken languages</label>
          <select id="languages" name="languages" multiple size="3" class="form-select" [(ngModel)]="languages">
            <option value="fr">French</option>
            <option value="en">English</option>
            <option value="es">Spanish</option>
          </select>
        </div>
      </div>
      <div class="mb-3">
        <label class="form-label" for="birthDate">Date of birth</label>
        <input id="birthDate" name="birthDate" type="date" class="form-control w-auto" [(ngModel)]="birthDate">
      </div>
      <button type="submit" class="btn btn-primary">Send</button>
    </form>

    <div class="col-md-5">
      <h2 class="h6">The model, live</h2>
      <pre class="bg-light p-2 rounded small">{{ model() | json }}</pre>
      @if (sent(); as text) {
        <h2 class="h6">Last submission</h2>
        <pre class="bg-success-subtle p-2 rounded small">{{ text }}</pre>
      }
    </div>
  </div>
</div>
  • linha 6: [(ngSubmit)]: com [FormsModule], o formulário nunca é enviado pelo navegador (sem recarregar a página); o método [send] é chamado em seu lugar. [preventDefault()] não é mais necessário (veja o exemplo 04);
  • linhas 12–13: botões de opção (radio): o mesmo [ngModel] em cada botão e um valor por botão ([[value]]). O signal recebe o valor do botão selecionado;
  • linha 21: [[(ngModel)]="name"] vincula o campo ao signal [name], nos dois sentidos. A sintaxe [[( )]], conhecida como “banana in a box” (banana na caixa), combina um binding de propriedade [[ngModel]] (do signal para o campo) e um binding de evento [(ngModelChange)] (do campo para o signal). Em um [<form>], cada campo vinculado por [ngModel] deve ter um atributo [name];
  • linha 26: com [type="number"], o signal recebe um número;
  • linha 33: [[ngModelOptions]="{ updateOn: 'blur' }"]: o signal só é atualizado quando o campo perde o foco, e não a cada tecla digitada;
  • linha 37: um único campo: [true] / [false];
  • linhas 45–46: os campos de lazer, gerenciados manualmente: [[checked]] e [(change)], como no exemplo 04;
  • linhas 54–59: uma lista suspensa: o signal recebe o valor ([[value]], o código do país) da opção selecionada;
  • linha 63: uma lista de múltipla escolha ([multiple]): o signal recebe a lista dos valores selecionados;
  • linha 72: uma data: o signal recebe uma string ["yyyy-MM-dd"];
  • linha 79: [{{ model() | json }}]: o modelo, em formato JSON, em tempo real;
  • linha 80: [@if (sent(); as text)]: se o valor for “verdadeiro” (neste caso, uma string não vazia), o bloco é exibido, e [as text] faz dele uma variável do bloco.

[npm start 05-ngmodel]; preencha o formulário e depois envie-o:

Image

O [ngModel] existe desde a primeira versão do [Angular] e aceita signals desde o [Angular] 17. Ele é encontrado em inúmeras aplicações. No entanto, deixa a cargo do componente tudo o que vai além do simples vaivém de um valor: mesclar campos, determinar quais foram modificados, validá-los... O exemplo a seguir mostra a forma mais recente de escrever um formulário.

2.6. Exemplo 06: formulários baseados em signals

O [Angular] 22 introduz uma nova forma de escrever formulários, inteiramente baseada em signals: os formulários baseados em signals ([Signal Forms], pacote [@angular/forms/signals]). O princípio:

  • o modelo do formulário é um signal, que contém um objeto com uma propriedade por campo;
  • a função [form(model)] constrói uma árvore de campos ([FieldTree]) que tem a mesma estrutura do modelo: [f.lastName], [f.age], [f.newsletter]...;
  • No template, [[formField]="f.lastName"] vincula um campo (HTML) a um campo da árvore.

O formulário lê e escreve no modelo; e cada campo conhece seu estado: foi acessado, foi modificado, está desabilitado, é válido?

// =========================================================================
// 06-signal-forms/src/app/app.ts - signal forms
// -------------------------------------------------------------------------
// A forma moderna (Angular 22) de escrever um formulário:
//   1. o MODELO: um signal que contém um objeto, com uma propriedade por
//      campo (o formulário lê e escreve nesse signal);
//   2. form(model, schema): constrói uma ÁRVORE DE CAMPOS (FieldTree), que
//      tem a mesma forma do modelo: f.lastName, f.age, f.newsletter... O
//      schema (opcional) descreve as regras dos campos (veja o exemplo 07);
//   3. [formField]="f.lastName" vincula um campo HTML a um campo da árvore.
// Cada campo tem um ESTADO, obtido ao chamá-lo: f.lastName() fornece seu valor
// (value()), se foi tocado (touched()), modificado (dirty()), se está
// desabilitado (disabled())...
// =========================================================================

import { Component, signal } from '@angular/core';
import { JsonPipe } from '@angular/common';
import { disabled, form, FormField } from '@angular/forms/signals';

// a forma dos dados do formulário
interface Profile {
  title: string;
  firstName: string;
  lastName: string;
  age: number;
  newsletter: boolean;
  email: string;
  country: string;
  birthDate: string;
  presentation: string;
}

const INITIAL: Profile = {
  title: 'Mme',
  firstName: 'Marie',
  lastName: 'PELISSIER',
  age: 30,
  newsletter: false,
  email: '',
  country: 'fr',
  birthDate: '',
  presentation: '',
};

@Component({
  selector: 'app-root',
  imports: [FormField, JsonPipe],
  templateUrl: './app.html',
})
export class App {
  protected readonly titles = ['Mr', 'Mme', 'Melle'];

  // 1. o modelo
  protected readonly model = signal<Profile>({ ...INITIAL });

  // 2. a árvore de campos; uma regra: o e-mail só pode ser modificado se a
  // caixa "newsletter" estiver marcada (valueOf lê o valor de OUTRO campo)
  protected readonly f = form(this.model, (p) => {
    disabled(p.email, ({ valueOf }) => !valueOf(p.newsletter));
  });

  // os campos cujo estado é exibido, na tabela à direita
  protected readonly fields = ['firstName', 'lastName', 'age', 'email'] as const;

  protected reset(): void {
    // o modelo volta ao seu valor inicial, e o estado dos campos é zerado
    this.model.set({ ...INITIAL });
    this.f().reset();
  }

  protected upperCase(): void {
    // modificando o MODELO por código: os campos acompanham
    this.model.update((m) => ({ ...m, lastName: m.lastName.toUpperCase(), firstName: m.firstName.toUpperCase() }));
  }
}
  • linha 18: as funções e a diretiva dos formulários baseados em signals;
  • linhas 21–31: o formato dos dados do formulário;
  • linha 47: o componente importa a diretiva [FormField], que é a de [[formField]];
  • linha 54: o modelo — um signal contendo um objeto [Profile];
  • linhas 58–60: a árvore de campos. O segundo argumento de [form] é o schema do formulário: uma função que recebe os caminhos dos campos ([p.email], [p.newsletter]...) e associa regras a eles. Aqui, há apenas uma: [disabled(p.email, logic)] desabilita o campo [email] quando a função [logic] retorna [true]. [valueOf(p.newsletter)] lê o valor de outro campo: o endereço de e-mail só pode ser editado se o checkbox “newsletter” estiver marcado. A regra é reativa: ela é reavaliada assim que o checkbox muda. O exemplo 07 adicionará regras de validação;
  • linha 63: os nomes dos campos cujo estado é exibido pelo template; [as const] cria uma lista de nomes exatos (['firstName' | 'lastName' | ...]), e não strings quaisquer;
  • linhas 65–69: a reinicialização. O modelo volta ao valor inicial (os campos o acompanham) e, em seguida, os estados dos campos são zerados ([touched], [dirty]): [f()] (a árvore, chamada) retorna o estado de todo o formulário, incluindo o método [reset()];
  • Linhas 71–74: modificam o modelo por código; os campos da página o acompanham.

O template:

<div class="container py-4">
  <h1 class="h3 mb-3">Example 06 - signal forms</h1>
  <div class="row g-4">
    <form class="col-md-7" (submit)="$event.preventDefault()">
      <div class="mb-3">
        <span class="form-label d-block">Title</span>
        <!-- radio buttons: o mesmo campo, um valor por botão -->
        @for (t of titles; track t) {
          <div class="form-check form-check-inline">
            <input type="radio" class="form-check-input" [id]="'title-' + t" [value]="t" [formField]="f.title">
            <label class="form-check-label" [for]="'title-' + t">{{ t }}</label>
          </div>
        }
      </div>
      <div class="row g-3 mb-3">
        <div class="col-5">
          <label class="form-label" for="firstName">First name</label>
          <!-- [formField]: este campo HTML edita o campo f.firstName do formulário -->
          <input id="firstName" class="form-control" [formField]="f.firstName">
        </div>
        <div class="col-5">
          <label class="form-label" for="lastName">Last name</label>
          <input id="lastName" class="form-control" [formField]="f.lastName">
        </div>
        <div class="col-2">
          <label class="form-label" for="age">Age</label>
          <!-- type="number" e um modelo do tipo number: um valor numérico -->
          <input id="age" type="number" class="form-control" [formField]="f.age">
        </div>
      </div>
      <div class="row g-3 mb-3 align-items-end">
        <div class="col-5">
          <div class="form-check">
            <input id="newsletter" type="checkbox" class="form-check-input" [formField]="f.newsletter">
            <label for="newsletter" class="form-check-label">Receive the newsletter</label>
          </div>
        </div>
        <div class="col-7">
          <label class="form-label" for="email">E-mail (if newsletter)</label>
          <!-- disabled é gerenciado pelo formulário: nenhum atributo a escrever aqui -->
          <input id="email" type="email" class="form-control" [formField]="f.email">
        </div>
      </div>
      <div class="row g-3 mb-3">
        <div class="col-6">
          <label class="form-label" for="country">Country</label>
          <select id="country" class="form-select" [formField]="f.country">
            <option value="fr">France</option>
            <option value="be">Belgium</option>
            <option value="ch">Switzerland</option>
          </select>
        </div>
        <div class="col-6">
          <label class="form-label" for="birthDate">Date of birth</label>
          <input id="birthDate" type="date" class="form-control" [formField]="f.birthDate">
        </div>
      </div>
      <div class="mb-3">
        <label class="form-label" for="presentation">Presentation</label>
        <textarea id="presentation" rows="2" class="form-control" [formField]="f.presentation"></textarea>
      </div>
      <div class="d-flex gap-2">
        <button type="button" class="btn btn-outline-primary" (click)="upperCase()">Name in upper case</button>
        <button type="button" class="btn btn-outline-secondary" (click)="reset()">Reset</button>
      </div>
    </form>

    <div class="col-md-5">
      <h2 class="h6">The model, live</h2>
      <!-- f().value(): o valor do formulário inteiro, ou seja, o modelo -->
      <pre class="bg-light p-2 rounded small">{{ f().value() | json }}</pre>
      <h2 class="h6">The state of the fields</h2>
      <table class="table table-sm small">
        <thead><tr><th>field</th><th>touched</th><th>dirty</th><th>disabled</th></tr></thead>
        <tbody>
          @for (c of fields; track c) {
            <tr>
              <td>{{ c }}</td>
              <td>{{ f[c]().touched() }}</td>
              <td>{{ f[c]().dirty() }}</td>
              <td>{{ f[c]().disabled() }}</td>
            </tr>
          }
        </tbody>
      </table>
      <p class="small mb-0">form modified (dirty): <strong>{{ f().dirty() }}</strong></p>
    </div>
  </div>
</div>
  • linha 4: o formulário não é enviado (não há botão de envio neste exemplo); apenas impedimos o envio pela tecla Enter;
  • linha 10: botões de opção (radio): o mesmo campo [f.title] em cada botão, um valor por botão;
  • linha 19: [[formField]="f.firstName"] vincula o campo HTML ao campo [firstName] do formulário, nos dois sentidos, como com [ngModel] no exemplo 05;
  • linha 28: um campo numérico, para uma propriedade numérica do modelo: o modelo recebe um número;
  • linha 34: um checkbox, para um valor booleano;
  • linha 41: o campo [email]. Não especifique o atributo [disabled]: a diretiva [[formField]] o define e o remove automaticamente, de acordo com a regra do schema;
  • linhas 47, 55, 60: uma lista suspensa, uma data, uma caixa de texto;
  • Linha 71: [f().value()]: o valor de todo o formulário, ou seja, o modelo;
  • Linhas 76–83: o estado de quatro campos. [f[c]] é o campo com o nome [c]; [fc] é o estado dele; [touched()] (o usuário entrou no campo e depois saiu dele), [dirty()] (o usuário alterou seu valor), [disabled()]: todos são signals;
  • Linha 86: o estado de todo o formulário — ele é atualizado se qualquer um de seus campos for modificado.

[npm start 06-signal-forms]; selecione o título, informe nome, sobrenome e idade, marque a caixa (o campo de e-mail passa a ser editável), informe o endereço de e-mail e depois clique em “Name in upper case”:

Image

Em comparação com o [ngModel]: um único signal para todo o formulário e o estado de cada campo, sem precisar escrever nada. Os formulários baseados em signals não conseguem vincular vários checkboxes à mesma lista, nem vincular uma lista de múltipla escolha: para esses campos, use a técnica do exemplo 05.

2.7. Exemplo 07: validação de formulários

O formulário “Criar uma conta” da aplicação [RdvMedecins], validado no navegador com as mesmas regras do servidor: título na lista, nome e sobrenome obrigatórios (máximo de 20 caracteres), nome de usuário em minúsculas, senha com no mínimo 6 caracteres, confirmação.

Nota: esta validação serve apenas para a conveniência do usuário (uma resposta imediata, sem troca de mensagens com o servidor). Ela não oferece nenhuma segurança: qualquer pessoa pode enviar ao servidor uma requisição montada manualmente ([curl]...). Portanto, o servidor SEMPRE validará também (veja o exemplo 25).

2.7.1. Configuração da aplicação

import { bootstrapApplication } from '@angular/platform-browser';
import { provideSignalFormsConfig } from '@angular/forms/signals';
import { App } from './app/app';

bootstrapApplication(App, {
  providers: [
    provideSignalFormsConfig({
      classes: {
        // um campo com erro só é sinalizado depois de "touched" (abandonado)
        'is-invalid': (field) => field.state().touched() && field.state().invalid(),
        'is-valid': (field) => field.state().touched() && field.state().valid(),
      },
    }),
  ],
}).catch((error) => console.error(error));
  • linha 15: o segundo argumento de [bootstrapApplication] é a configuração da aplicação: uma lista de providers ([providers]), que disponibilizam serviços e configurações para toda a aplicação (veja o exemplo 14);
  • Linhas 17–23: [provideSignalFormsConfig] configura os formulários baseados em signals. [classes] associa uma classe CSS a uma condição baseada no estado de um campo: a diretiva [[formField]] aplica a classe ao campo HTML quando a condição é verdadeira. São usadas as seguintes classes do [Bootstrap]:
    • linha 20: [is-invalid] (borda vermelha), se o usuário já passou pelo campo e ele é inválido (as duas condições). Os erros não são exibidos imediatamente: um formulário vazio coberto de vermelho não é agradável;
    • linha 21: [is-valid] (caixa verde), se o usuário já passou pelo campo e ele é válido.

2.7.2. O componente

// =========================================================================
// 07-validation/src/app/app.ts - validando um formulário no navegador
// -------------------------------------------------------------------------
// As regras dos campos são escritas no SCHEMA do formulário (segundo
// argumento de form()): required, maxLength, minLength, pattern... e
// validate() para uma regra personalizada. Cada campo então conhece seus
// erros (f.lastName().errors()), recalculados a cada tecla digitada.
// Eles não são exibidos de imediato (um formulário vazio todo vermelho é
// desagradável): somente para um campo já abandonado ("touched"). submit()
// marca todos os campos como touched e só então executa a ação se o
// formulário for válido.
//
// Mesmas regras do servidor RdvMedecins (formulário "Create an account").
// ATENÇÃO: esta validação é apenas uma COMODIDADE para o usuário (uma
// resposta imediata, sem ida e volta ao servidor). Ela não protege
// nada: qualquer pessoa pode enviar ao servidor uma requisição montada à
// mão (curl...). O servidor, portanto, SEMPRE revalida tudo (veja o exemplo 25).
// =========================================================================

import { Component, signal } from '@angular/core';
import { form, FormField, maxLength, minLength, pattern, required, submit, validate } from '@angular/forms/signals';

interface Account {
  title: string;
  firstName: string;
  lastName: string;
  login: string;
  password: string;
  confirmation: string;
}

const TITLES = ['Mr', 'Mme', 'Melle'];
const LOGIN_FORMAT = /^[a-z0-9._-]{1,30}$/;
const PASSWORD_MIN = 6;

@Component({
  selector: 'app-root',
  imports: [FormField],
  templateUrl: './app.html',
})
export class App {
  protected readonly titles = TITLES;
  protected readonly model = signal<Account>({
    title: 'Mr',
    firstName: '',
    lastName: '',
    login: '',
    password: '',
    confirmation: '',
  });

  // o schema: p designa os CAMINHOS dos campos (p.lastName, p.login...)
  protected readonly f = form(this.model, (p) => {
    validate(p.title, ({ value }) =>
      TITLES.includes(value()) ? null : { kind: 'title', message: 'Choose a title from the list.' },
    );
    required(p.firstName, { message: 'The first name is required.' });
    maxLength(p.firstName, 20, { message: 'The first name must not exceed 20 characters.' });
    required(p.lastName, { message: 'The last name is required.' });
    maxLength(p.lastName, 20, { message: 'The last name must not exceed 20 characters.' });
    required(p.login, { message: 'The login is required.' });
    pattern(p.login, LOGIN_FORMAT, { message: 'Unaccented lower-case letters, digits, dot, hyphen, underscore.' });
    required(p.password, { message: 'The password is required.' });
    minLength(p.password, PASSWORD_MIN, { message: `At least ${PASSWORD_MIN} characters.` });
    // uma regra personalizada, que compara DOIS campos (valueOf lê o outro)
    validate(p.confirmation, ({ value, valueOf }) =>
      value() === valueOf(p.password)
        ? null
        : { kind: 'confirmation', message: 'The confirmation does not match the password.' },
    );
  });

  protected readonly submitAttempted = signal(false);
  protected readonly success = signal(false);

  // (submit) do formulário
  protected async send(event: SubmitEvent): Promise<void> {
    event.preventDefault();
    this.submitAttempted.set(true);
    // submit() marca todos os campos como touched (seus erros
    // aparecem) e só então executa a ação se tudo for válido
    const valid = await submit(this.f, async () => {
      // aqui, enviaríamos o modelo ao servidor (veja o exemplo 25)
      return null; // null: sem erro
    });
    this.success.set(valid);
  }
}
  • linha 21: as funções de validação dos formulários baseados em signals;
  • linhas 53–71: o schema do formulário: cada função associa uma regra a um campo, identificado pelo seu caminho ([p.firstName]), junto com a mensagem a ser exibida em caso de falha:
    • [required]: o campo deve ser preenchido;
    • [maxLength], [minLength]: um tamanho máximo ou mínimo;
    • [pattern]: o valor deve corresponder a uma expressão regular;
    • [validate(path, function)]: uma regra “personalizada”. A função recebe o contexto do campo (seu valor [value()], o valor de outro campo [valueOf(...)]) e retorna [null] (nenhum erro) ou um erro: um objeto [{ kind, message }], em que [kind] indica o tipo de erro (linhas 54–56 e 66–70). A regra de confirmação compara dois campos: ela é reavaliada quando um OU o outro muda;
    • O [Angular] também fornece [email], [min], [max] e regras assíncronas ([validateHttp]), que consultam um servidor;
  • linhas 77–87: o envio. [submit(form, action)]:
    • marca todos os campos como visitados: seus erros aparecem, mesmo para aqueles que o usuário nunca visitou;
    • executa a ação somente se o formulário for válido;
    • retorna [true] se o envio foi bem-sucedido. A ação retorna [null] quando tudo corre bem, ou códigos de erro, que o exemplo 25 recuperará do servidor.

2.7.3. O template

<div class="container py-4" style="max-width: 640px">
  <h1 class="h3 mb-3">Example 07 - validating a form</h1>
  <!-- novalidate: desabilitamos a validação própria do navegador, para
       exibir NOSSAS mensagens, no NOSSO estilo -->
  <form class="card p-4" novalidate (submit)="send($event)">
    <div class="mb-3">
      <label class="form-label" for="title">Title</label>
      <select id="title" class="form-select" [formField]="f.title">
        @for (t of titles; track t) {
          <option [value]="t">{{ t }}</option>
        }
      </select>
      <div class="invalid-feedback">{{ f.title().errors()[0]?.message }}</div>
    </div>
    <div class="row g-3 mb-3">
      <div class="col-sm-6">
        <label class="form-label" for="firstName">First name</label>
        <!-- a classe is-invalid (definida pela configuração, veja main.ts)
             dá ao campo uma borda vermelha E revela o .invalid-feedback
             que vem logo depois: escrevemos nele o primeiro erro do campo -->
        <input id="firstName" class="form-control" [formField]="f.firstName">
        <div class="invalid-feedback">{{ f.firstName().errors()[0]?.message }}</div>
      </div>
      <div class="col-sm-6">
        <label class="form-label" for="lastName">Last name</label>
        <input id="lastName" class="form-control" [formField]="f.lastName">
        <div class="invalid-feedback">{{ f.lastName().errors()[0]?.message }}</div>
      </div>
    </div>
    <div class="mb-3">
      <label class="form-label" for="login">Login</label>
      <input id="login" class="form-control" autocomplete="username" [formField]="f.login">
      <div class="invalid-feedback">{{ f.login().errors()[0]?.message }}</div>
    </div>
    <div class="row g-3 mb-4">
      <div class="col-sm-6">
        <label class="form-label" for="password">Password</label>
        <input id="password" type="password" class="form-control" autocomplete="new-password" [formField]="f.password">
        <div class="invalid-feedback">{{ f.password().errors()[0]?.message }}</div>
      </div>
      <div class="col-sm-6">
        <label class="form-label" for="confirmation">Confirmation</label>
        <input id="confirmation" type="password" class="form-control" autocomplete="new-password"
               [formField]="f.confirmation">
        <div class="invalid-feedback">{{ f.confirmation().errors()[0]?.message }}</div>
      </div>
    </div>
    <button type="submit" class="btn btn-primary">Create the account</button>
    @if (submitAttempted() && f().invalid()) {
      <div class="alert alert-danger mt-3 mb-0">The form contains {{ f().errorSummary().length }} error(s).</div>
    }
    @if (success()) {
      <div class="alert alert-success mt-3 mb-0">Valid form: it could be sent to the server.</div>
    }
  </form>
</div>
  • linha 5: [novalidate] desabilita a validação própria do navegador (as dicas “Preencha este campo”): nossas mensagens são exibidas no NOSSO estilo;
  • Linha 13: [f.title().errors()]: a lista de erros do campo, recalculada a cada mudança. A mensagem do primeiro é exibida. [?.]: se não houver erros, [[0]] é igual a [undefined], e a expressão também;
  • Linhas 21–22: o campo e sua área de mensagem. A classe [invalid-feedback] do [Bootstrap] fica oculta, a menos que venha logo após um campo que tenha a classe [is-invalid]: portanto, não é necessário nenhum código para fazê-la aparecer no momento certo;
  • linha 49: [f().invalid()]: o formulário é inválido se qualquer um de seus campos for inválido; [f().errorSummary()] (linha 50): os erros de todos os seus campos.

[npm start 07-validation]; informe um nome, passe para o sobrenome, deixe-o em branco, informe um nome de usuário incorreto:

Image

Apenas os campos que foram preenchidos são destacados, em verde ou em vermelho. Clique em “Create the account” com o formulário vazio: todos os campos passam a ser destacados:

Image

O campo de confirmação vazio é “válido”: ele corresponde à senha, que também está vazia. Um formulário válido:

Image

2.8. Exemplo 08: formulários reativos

Antes dos formulários baseados em signals, os formulários do [Angular] eram escritos com [ngModel] (exemplo 05) ou com formulários reativos ([ReactiveFormsModule]), sendo essa API a mais usada nas aplicações existentes. Você certamente vai encontrá-la: eis o formulário do exemplo 07, reescrito com ela.

// =========================================================================
// 08-reactive-forms/src/app/app.ts - a API "histórica" de formulários
// -------------------------------------------------------------------------
// Antes dos signal forms (Angular 22), os formulários eram escritos
// com FORMULÁRIOS REATIVOS (ReactiveFormsModule). Eles são encontrados na
// maioria das aplicações existentes: aqui está o formulário do exemplo
// 07, reescrito com eles.
//   - um FormGroup reúne FormControls, um por campo;
//   - cada FormControl tem um valor inicial e VALIDADORES
//     (Validators.required, Validators.maxLength(20)...);
//   - no template, [formGroup] vincula o <form> ao grupo, e
//     formControlName="lastName" vincula um campo HTML a um control;
//   - o estado de um control (value, errors, touched, invalid...) é uma
//     propriedade comum, não um signal.
// =========================================================================

import { Component, inject, signal } from '@angular/core';
import { AbstractControl, FormBuilder, ReactiveFormsModule, ValidationErrors, Validators } from '@angular/forms';

const TITLES = ['Mr', 'Mme', 'Melle'];

// um validador personalizado se aplica ao GRUPO: ele compara dois de seus campos.
// Retorna null (sem erro) ou um objeto que descreve o erro.
function sameConfirmation(group: AbstractControl): ValidationErrors | null {
  const password = group.get('password')?.value;
  const confirmation = group.get('confirmation')?.value;
  return password === confirmation ? null : { confirmation: true };
}

@Component({
  selector: 'app-root',
  imports: [ReactiveFormsModule],
  templateUrl: './app.html',
})
export class App {
  protected readonly titles = TITLES;
  private readonly fb = inject(FormBuilder).nonNullable;

  // o grupo: { name: [valor inicial, validadores] }
  protected readonly form = this.fb.group(
    {
      title: ['Mr', [Validators.required]],
      firstName: ['', [Validators.required, Validators.maxLength(20)]],
      lastName: ['', [Validators.required, Validators.maxLength(20)]],
      login: ['', [Validators.required, Validators.pattern(/^[a-z0-9._-]{1,30}$/)]],
      password: ['', [Validators.required, Validators.minLength(6)]],
      confirmation: [''],
    },
    { validators: sameConfirmation },
  );

  protected readonly success = signal(false);
  protected readonly value = signal('');

  // um campo é sinalizado com erro se foi tocado e é inválido
  protected inError(name: string): boolean {
    const control = this.form.get(name);
    return !!control && control.touched && control.invalid;
  }

  // (ngSubmit): todos os campos passam a "touched", seus erros aparecem
  protected send(): void {
    this.form.markAllAsTouched();
    this.success.set(this.form.valid);
    // getRawValue(): o valor do grupo inteiro, tipado
    this.value.set(JSON.stringify(this.form.getRawValue()));
  }
}
  • linha 18: as classes dos formulários reativos, em [@angular/forms];
  • linhas 24–28: um validador “personalizado”. É uma função que recebe um controle (neste caso, o grupo inteiro, para comparar dois de seus campos) e retorna [null] (nenhum erro) ou um objeto que descreve o erro;
  • linha 32: o componente importa [ReactiveFormsModule], que fornece as diretivas [[formGroup]] e [formControlName];
  • linha 37: [inject(FormBuilder)]: o componente solicita um serviço ao [Angular] (injeção de dependência; veja o exemplo 14). [FormBuilder] ajuda a gerar formulários; [nonNullable]: um campo redefinido volta ao seu valor inicial, e não a [null];
  • Linhas 40–50: o formulário é um grupo ([FormGroup]) de controles ([FormControl]), um por campo. Cada um é descrito por seu valor inicial e pela lista de seus validadores: [Validators.required], [Validators.maxLength(20)], [Validators.pattern(...)]... Linha 49: o validador do grupo;
  • Linhas 56–59: um campo é sinalizado como erro se foi modificado e é inválido. O estado de um controle ([touched], [invalid], [errors], [value]) é uma propriedade comum, e não um signal;
  • Linhas 62–67: o comando. [markAllAsTouched()] exibe todos os erros; [valid] indica se o grupo inteiro é válido; [getRawValue()] retorna seu valor, tipado de acordo com a descrição do grupo.

O template:

<div class="container py-4" style="max-width: 640px">
  <h1 class="h3 mb-3">Example 08 - reactive forms</h1>
  <!-- [formGroup]: este <form> é controlado pelo grupo "form" -->
  <form class="card p-4" novalidate [formGroup]="form" (ngSubmit)="send()">
    <div class="mb-3">
      <label class="form-label" for="title">Title</label>
      <!-- formControlName: este campo é o control "title" do grupo -->
      <select id="title" class="form-select" formControlName="title">
        @for (t of titles; track t) {
          <option [value]="t">{{ t }}</option>
        }
      </select>
    </div>
    <div class="row g-3 mb-3">
      <div class="col-sm-6">
        <label class="form-label" for="firstName">First name</label>
        <input id="firstName" class="form-control" formControlName="firstName" [class.is-invalid]="inError('firstName')">
        <!-- errors: um objeto em que cada chave é o nome de um validador que falhou -->
        <div class="invalid-feedback">
          @if (form.controls.firstName.errors?.['required']) { The first name is required. }
          @if (form.controls.firstName.errors?.['maxlength']) { 20 characters at most. }
        </div>
      </div>
      <div class="col-sm-6">
        <label class="form-label" for="lastName">Last name</label>
        <input id="lastName" class="form-control" formControlName="lastName" [class.is-invalid]="inError('lastName')">
        <div class="invalid-feedback">
          @if (form.controls.lastName.errors?.['required']) { The last name is required. }
          @if (form.controls.lastName.errors?.['maxlength']) { 20 characters at most. }
        </div>
      </div>
    </div>
    <div class="mb-3">
      <label class="form-label" for="login">Login</label>
      <input id="login" class="form-control" formControlName="login" [class.is-invalid]="inError('login')">
      <div class="invalid-feedback">
        @if (form.controls.login.errors?.['required']) { The login is required. }
        @if (form.controls.login.errors?.['pattern']) { Unaccented lower-case letters, digits, dot, hyphen, underscore. }
      </div>
    </div>
    <div class="row g-3 mb-4">
      <div class="col-sm-6">
        <label class="form-label" for="password">Password</label>
        <input id="password" type="password" class="form-control" formControlName="password"
               [class.is-invalid]="inError('password')">
        <div class="invalid-feedback">
          @if (form.controls.password.errors?.['required']) { The password is required. }
          <!-- os erros também carregam informações: o tamanho exigido -->
          @if (form.controls.password.errors?.['minlength']; as e) { At least {{ e.requiredLength }} characters. }
        </div>
      </div>
      <div class="col-sm-6">
        <label class="form-label" for="confirmation">Confirmation</label>
        <!-- o erro "confirmation" é o do GRUPO (validador personalizado) -->
        <input id="confirmation" type="password" class="form-control" formControlName="confirmation"
               [class.is-invalid]="form.controls.confirmation.touched && form.hasError('confirmation')">
        <div class="invalid-feedback">The confirmation does not match the password.</div>
      </div>
    </div>
    <button type="submit" class="btn btn-primary">Create the account</button>
    @if (value()) {
      <div class="alert mt-3 mb-0" [class]="success() ? 'alert-success' : 'alert-danger'">
        {{ success() ? 'Valid form' : 'Invalid form' }}: <code>{{ value() }}</code>
      </div>
    }
  </form>
</div>
  • linha 4: [[formGroup]] vincula o formulário HTML ao grupo; [(ngSubmit)] chama o método de envio;
  • linha 8: [formControlName="title"] vincula o campo ao [title] controle do grupo;
  • linha 17: a classe [is-invalid] é definida pelo template usando o método [inError];
  • linhas 20–21: [errors] é um objeto cujas propriedades têm o nome dos validadores que falharam ([required], [maxlength]...). Uma mensagem é escrita para cada erro possível;
  • linha 49: um erro também contém informações: neste caso, o tamanho exigido;
  • linha 56: o erro de confirmação é o do grupo: [form.hasError('confirmation')].

[npm start 08-reactive-forms]; alguns erros e, em seguida, um clique em “Create the account”:

Image

As duas APIs têm a mesma função. Os formulários reativos descrevem o formulário no código (controles que guardam o valor E o estado), enquanto os formulários baseados em signals partem dos dados (um modelo ao qual regras são associadas) e se integram naturalmente aos signals do restante da aplicação. Serão esses que usaremos no restante do curso e no estudo de caso.

2.9. Exemplo 09: pipes

Um pipe formata um valor para exibição sem modificá-lo: [{{ value | pipe }}]ou, com parâmetros, [{{ value | pipe: parameter1 : parameter2 }}]. O [Angular] fornece uma dúzia deles; você pode escrever os seus.

2.9.1. O idioma dos pipes

Os pipes de data e de número formatam os valores de acordo com um idioma ([locale]). Por padrão, o [Angular] só oferece suporte ao inglês dos Estados Unidos. Para o inglês britânico:

import { LOCALE_ID } from '@angular/core';
import { registerLocaleData } from '@angular/common';
import localeEnGb from '@angular/common/locales/en-GB';
import { bootstrapApplication } from '@angular/platform-browser';
import { App } from './app/app';

registerLocaleData(localeEnGb);

bootstrapApplication(App, {
  providers: [{ provide: LOCALE_ID, useValue: 'en-GB' }],
}).catch((error) => console.error(error));
  • linha 18: [registerLocaleData(localeEnGb)] carrega as regras britânicas: nomes de dias e meses, ordem do dia e do mês, formatos de data etc.;
  • linha 21: um provider que atribui um valor ao token [LOCALE_ID]: o idioma padrão usado pelos pipes. [{ provide: token, useValue: value }] é a forma mais simples de um provider; o exemplo 14 voltará a isso.

2.9.2. Dois pipes personalizados

Um pipe é uma classe decorada por [@Pipe], cujo método [transform] recebe o valor colocado antes da barra, junto com eventuais parâmetros:

// =========================================================================
// 09-pipes/src/app/pipes/time-range.pipe.ts - um pipe personalizado
// -------------------------------------------------------------------------
// Um pipe é uma classe decorada por @Pipe, cujo método transform()
// recebe o valor colocado ANTES da barra (e, eventualmente,
// parâmetros) e retorna o que deve ser exibido:
//     {{ slot | timeRange }}           -> "8:00 - 8:20"
//     {{ slot | timeRange: 'start' }}  -> "8:00"
// Um pipe é "puro" por padrão: o Angular só chama transform() novamente se o
// valor ou os parâmetros MUDARAM (mesmo objeto = mesmo resultado).
// =========================================================================

import { Pipe, PipeTransform } from '@angular/core';

export interface Slot {
  startHour: number;
  startMinute: number;
  endHour: number;
  endMinute: number;
}

// "8:05" em vez de "8:5"
function time(h: number, m: number): string {
  return `${h}:${String(m).padStart(2, '0')}`;
}

@Pipe({ name: 'timeRange' })
export class TimeRangePipe implements PipeTransform {
  transform(c: Slot, part: 'all' | 'start' | 'end' = 'all'): string {
    switch (part) {
      case 'start':
        return time(c.startHour, c.startMinute);
      case 'end':
        return time(c.endHour, c.endMinute);
      default:
        return `${time(c.startHour, c.startMinute)} - ${time(c.endHour, c.endMinute)}`;
    }
  }
}
  • linha 27: o nome do pipe, aquele escrito nos templates;
  • linha 29: [transform(value, part)] retorna o que deve ser exibido. O parâmetro é opcional (valor padrão ['all']): [{{ slot | timeRange }}] exibe [8:00 - 8:20], [{{ slot | timeRange: 'start' }}] exibe [8:00].

Um pipe é puro por padrão: [Angular] só chama [transform] se o valor ou um dos parâmetros mudou (um objeto diferente, uma string diferente). É isso que o torna mais eficiente do que um método do componente chamado dentro do template (como [format(...)] no exemplo 02), que é executado toda vez que o componente é verificado.

Um segundo pipe, que calcula as iniciais:

// 09-pipes/src/app/pipes/initials.pipe.ts - "Marie PELISSIER" -> "MP"
import { Pipe, PipeTransform } from '@angular/core';

@Pipe({ name: 'initials' })
export class InitialsPipe implements PipeTransform {
  transform(fullName: string): string {
    return fullName
      .split(/\s+/)
      .filter((word) => word !== '')
      .map((word) => word[0].toUpperCase())
      .join('');
  }
}

2.9.3. O componente e seu template

// =========================================================================
// 09-pipes/src/app/app.ts - formatando valores em um template
// -------------------------------------------------------------------------
// {{ value | pipe }} ou {{ value | pipe: parameter1 : parameter2 }}:
// um PIPE transforma um valor para exibição, sem modificá-lo. O Angular
// fornece uma dúzia deles (módulo @angular/common); você pode escrever
// os seus (veja pipes/). Um componente importa os pipes que usa.
// =========================================================================

import { Component, signal } from '@angular/core';
import {
  CurrencyPipe,
  DatePipe,
  DecimalPipe,
  JsonPipe,
  KeyValuePipe,
  LowerCasePipe,
  PercentPipe,
  SlicePipe,
  TitleCasePipe,
  UpperCasePipe,
} from '@angular/common';
import { Slot, TimeRangePipe } from './pipes/time-range.pipe';
import { InitialsPipe } from './pipes/initials.pipe';

@Component({
  selector: 'app-root',
  imports: [
    CurrencyPipe,
    DatePipe,
    DecimalPipe,
    JsonPipe,
    KeyValuePipe,
    LowerCasePipe,
    PercentPipe,
    SlicePipe,
    TitleCasePipe,
    UpperCasePipe,
    TimeRangePipe,
    InitialsPipe,
  ],
  templateUrl: './app.html',
})
export class App {
  protected readonly now = signal(new Date());
  protected readonly day = '2026-10-05'; // uma data no formato da API do RdvMedecins
  protected readonly price = 1234.5;
  protected readonly rate = 0.055;
  protected readonly name = 'marie pelissier';
  protected readonly doctor = { title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER' };
  protected readonly slots: Slot[] = [
    { startHour: 8, startMinute: 0, endHour: 8, endMinute: 20 },
    { startHour: 8, startMinute: 20, endHour: 8, endMinute: 40 },
    { startHour: 14, startMinute: 5, endHour: 14, endMinute: 25 },
  ];
  protected readonly languages = ['TypeScript', 'HTML', 'CSS', 'JavaScript', 'SQL'];

  protected refresh(): void {
    this.now.set(new Date());
  }
}
  • Linhas 11–22 e 28–41: um componente importa os pipes que usa — os do [Angular] ([@angular/common]) — como se fossem seus;
  • linha 46: uma data no formato da API [RdvMedecins]: o pipe [date] aceita um objeto [Date], um número (milissegundos) ou uma string ISO.
<div class="container py-4" style="max-width: 820px">
  <h1 class="h3 mb-3">Example 09 - pipes</h1>
  <table class="table table-sm align-middle">
    <thead><tr><th>In the template</th><th>Displayed</th></tr></thead>
    <tbody>
      <tr><td><code>{{ '{{' }} now() | date {{ '}}' }}</code></td><td>{{ now() | date }}</td></tr>
      <tr><td><code>{{ '{{' }} now() | date: 'fullDate' {{ '}}' }}</code></td><td>{{ now() | date: 'fullDate' }}</td></tr>
      <tr><td><code>{{ '{{' }} now() | date: 'HH:mm:ss' {{ '}}' }}</code></td><td>{{ now() | date: 'HH:mm:ss' }}</td></tr>
      <tr><td><code>{{ '{{' }} day | date: 'EEEE d MMMM y' {{ '}}' }}</code></td><td>{{ day | date: 'EEEE d MMMM y' }}</td></tr>
      <tr><td><code>{{ '{{' }} day | date: 'longDate' : '' : 'en-US' {{ '}}' }}</code></td><td>{{ day | date: 'longDate' : '' : 'en-US' }}</td></tr>
      <tr><td><code>{{ '{{' }} price | currency: 'EUR' {{ '}}' }}</code></td><td>{{ price | currency: 'EUR' }}</td></tr>
      <tr><td><code>{{ '{{' }} price | number: '1.0-0' {{ '}}' }}</code></td><td>{{ price | number: '1.0-0' }}</td></tr>
      <tr><td><code>{{ '{{' }} rate | percent: '1.1-1' {{ '}}' }}</code></td><td>{{ rate | percent: '1.1-1' }}</td></tr>
      <tr><td><code>{{ '{{' }} name | uppercase {{ '}}' }}</code></td><td>{{ name | uppercase }}</td></tr>
      <tr><td><code>{{ '{{' }} name | titlecase {{ '}}' }}</code></td><td>{{ name | titlecase }}</td></tr>
      <tr><td><code>{{ '{{' }} 'APPOINTMENT' | lowercase {{ '}}' }}</code></td><td>{{ 'APPOINTMENT' | lowercase }}</td></tr>
      <tr><td><code>{{ '{{' }} languages | slice: 0 : 3 {{ '}}' }}</code></td><td>{{ languages | slice: 0 : 3 }}</td></tr>
      <tr><td><code>{{ '{{' }} doctor | json {{ '}}' }}</code></td><td><code>{{ doctor | json }}</code></td></tr>
      <!-- dois pipes em sequência: o resultado do primeiro vai para o segundo -->
      <tr><td><code>{{ '{{' }} name | titlecase | initials {{ '}}' }}</code></td><td>{{ name | titlecase | initials }}</td></tr>
    </tbody>
  </table>

  <h2 class="h6">keyvalue: iterating over the properties of an object</h2>
  <ul>
    @for (p of doctor | keyvalue; track p.key) {
      <li>{{ p.key }} = {{ p.value }}</li>
    }
  </ul>

  <h2 class="h6">A home-made pipe: timeRange</h2>
  <ul>
    @for (c of slots; track $index) {
      <li>{{ c | timeRange }} (start: {{ c | timeRange: 'start' }})</li>
    }
  </ul>
  <button class="btn btn-sm btn-outline-primary" (click)="refresh()">Refresh the time</button>
</div>
  • linhas 6–20: uma linha por pipe: a expressão, seguida de seu resultado. [{{ '{{' }}] exibe os caracteres [{{], que não podem ser escritos diretamente em um template;
    • Linhas 6–10: o pipe [date], com um formato predefinido ([fullDate], [longDate]...) ou um formato composto ([EEEE d MMMM y], [HH:mm:ss]). Linha 10: seu segundo e terceiro parâmetros são o fuso horário e o idioma: neste caso, o inglês dos Estados Unidos ([en-US]), apenas para esta data;
    • linha 11: [currency], um valor em uma moeda;
    • linha 12: [number: '1.0-0']: pelo menos 1 dígito antes da vírgula decimal, entre 0 e 0 dígitos depois: arredondado para o inteiro mais próximo;
    • linha 13: [percent], uma porcentagem;
    • linhas 14–16: letras maiúsculas, iniciais maiúsculas, letras minúsculas;
    • linha 17: [slice], parte de uma lista ou string;
    • linha 18: [json], um objeto no formato JSON (muito útil para depuração);
    • linha 20: dois pipes em sequência: o resultado do primeiro é passado ao segundo;
  • linha 26: [keyvalue] converte um objeto em uma lista de pares [{ key, value }], que o [@for] pode percorrer;
  • linha 34: nosso pipe [timeRange], primeiro sem e depois com um parâmetro.

[npm start 09-pipes]:

Image

O [Angular] também fornece o pipe [async], que exibe o último valor de um observable (veja o exemplo 19), e o [i18nPlural] para plurais. O [ngx-translate] fornece o pipe [translate], que traduz textos (exemplo 21).