3.1. Exemplo 01: A estrutura de uma aplicação Ionic
3.1.1. O projeto
Uma aplicação [Ionic], criada com [Angular], é, inicialmente, uma aplicação [Angular] comum: ela é criada com a ferramenta de linha de comando do [Angular], [ng], e depois lhe são acrescentados os componentes do [Ionic] e do [Capacitor] ; essa ferramenta a transformará em uma aplicação [Android]:
| npm install -g @angular/cli
ng new examples_ionic --style=scss --skip-tests --ssr=false
cd examples_ionic
npm install @ionic/angular ionicons @capacitor/core @capacitor/android @capacitor/preferences
npm install -D @capacitor/cli
npx cap init "Ionic Examples" fr.stahe.examples --web-dir dist/examples_ionic/browser
|
- Linha 1: instala o [Angular CLI], o comando [ng], para todo o computador ([-g], “global”);
- linha 2: cria o projeto [examples_ionic]: uma aplicação [Angular] completa, pronta para executar. [--style=scss]: as folhas de estilo serão escritas em [SCSS], o CSS enriquecido com variáveis e aninhamento; [--skip-tests]: sem arquivos de testes unitários; [--ssr=false]: sem renderização no servidor, desnecessária em uma aplicação mobile;
- Linha 4: os pacotes do [Ionic] (seus componentes para [Angular] e sua fonte de ícones [ionicons]) e os do [Capacitor] (seu núcleo, a plataforma [Android] e o armazenamento chave-valor no dispositivo, que será usado a partir do Exemplo 20);
- linha 5: a ferramenta de linha de comando do [Capacitor], o comando [cap], usado apenas para desenvolvimento ([-D]);
- linha 6: escreve o arquivo [capacitor.config.ts]: o nome da aplicação e seu identificador (o prefixo [fr.stahe], invertido como um nome de domínio, seguido do nome da aplicação; duas aplicações instaladas no mesmo celular devem ter identificadores diferentes) e a pasta onde o [ng build] armazena a aplicação compilada.
O projeto de exemplo foi criado assim e, em seguida, sua pasta [src/app] foi preenchida manualmente para reunir vinte e cinco exemplos em uma única aplicação: uma página inicial (o menu de exemplos) e uma página por exemplo. Dessa forma, eles compartilham os mesmos pacotes, que são baixados uma única vez. Sua estrutura de diretórios:
| examples_ionic
├── angular.json the Angular project configuration
├── capacitor.config.ts the Capacitor configuration
├── package.json the packages and the scripts of the project
├── package-lock.json the exact versions of the installed packages
├── proxy.conf.json the relay to the JSON server (examples 22 to 25)
├── tsconfig.json the TypeScript configuration
├── tsconfig.app.json
├── captures/ the scripts that make the screenshots of the course
├── node_modules/ the installed packages (npm install)
├── public/ files delivered as is (icon, images, dictionaries)
├── android/ the Android Studio project (after npx cap add android)
└── src/
├── index.html the page that hosts the application
├── main.ts the entry point
├── styles.scss the styles of the whole application
└── app/
├── app.ts the root component
├── back-button.ts Android's Back button
├── app.routes.ts the routes: one address per example
├── examples.ts the list of the 25 examples
├── home/ the menu of the examples
│ ├── home.page.ts
│ └── home.page.html
├── common/ the code shared by examples 22 to 25
├── ex01-first-application/
│ ├── ex01.page.ts
│ └── ex01.page.html
├── ex02-state/
│ ├── ex02.page.ts
│ └── ex02.page.html
└── ...
|
Cada exemplo tem sua própria pasta, [src/app/exNN-short-name]. Uma página é formada por dois arquivos: uma classe [TypeScript] ([exNN.page.ts]) e seu template [HTML] ([exNN.page.html]).
3.1.2. O arquivo package.json
O arquivo [package.json] descreve o projeto para o [npm], o gerenciador de pacotes do [Node.js]: seu nome, seus scripts e os pacotes de que ele precisa.
| {
"name": "examples-ionic",
"version": "0.0.0",
"scripts": {
"ng": "ng",
"start": "ng serve",
"build": "ng build",
"watch": "ng build --watch --configuration development",
"android": "ng build && cap sync android && cap run android",
"captures": "node captures/captures.mjs"
},
"private": true,
"packageManager": "npm@10.9.4",
"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",
"@capacitor/android": "^8.5.2",
"@capacitor/app": "^8.1.2",
"@capacitor/core": "^8.5.2",
"@capacitor/preferences": "^8.0.1",
"@ionic/angular": "^9.0.6",
"ionicons": "^8.1.0",
"rxjs": "~7.8.0",
"tslib": "^2.3.0"
},
"devDependencies": {
"@angular/build": "^22.2.1",
"@angular/cli": "^22.2.1",
"@angular/compiler-cli": "^22.2.0",
"@capacitor/cli": "^8.5.2",
"playwright": "^1.56.1",
"prettier": "^3.8.1",
"typescript": "~6.0.2"
}
}
|
- linhas 2–3: o nome e a versão do projeto;
- linhas 4–11: os scripts, que são iniciados por [npm run name] (ou [npm start] para o script [start]): [npm start] inicia o [ng serve], o servidor de desenvolvimento; [npm run build] inicia o [ng build], que compila a aplicação a ser implantada; [npm run android] faz a compilação, copia a aplicação para o projeto [Android] e a inicia no celular (veja “Execução”); [npm run captures] gera as capturas de tela deste curso;
- linha 12: [private]: este projeto não é uma biblioteca; ele nunca será publicado no repositório [npm];
- linhas 14–29: os pacotes de que a aplicação precisa, que serão incluídos nela. Os pacotes [@angular/...] são componentes do framework [Angular]: [core] (componentes, signals, injeção de dependência), [common] (pipes, o cliente HTTP), [forms] (formulários), [router] (o roteador), [platform-browser] (renderização no navegador), [compiler] (o compilador de templates). Em seguida vêm o [Capacitor] e seus plugins [app] (o botão Voltar do [Android], veja abaixo) e [preferences] (a memória do dispositivo, veja o Exemplo 20), [@ionic/angular] (os componentes do [Ionic]), [ionicons] (seus ícones), [rxjs] (fluxos assíncronos de dados, veja o Exemplo 19) e [tslib] (pequenas funções usadas pelo código compilado);
- linhas 30–38: pacotes usados apenas no desenvolvimento: [@angular/build] (o compilador da aplicação, construído sobre [esbuild] e [Vite]), [@angular/cli] (o comando [ng]), [@capacitor/cli] (o comando [cap]), [typescript], [prettier] (formatação automática do código) e [playwright] (controle do navegador, para as capturas de tela).
O prefixo [^] em uma versão ([^22.2.0]) aceita qualquer versão mais recente da mesma versão principal (22.3.0, mas não 23.0.0); o prefixo [~] ([~6.0.2]) aceita apenas versões de correção (6.0.3, mas não 6.1.0). O comando [npm install] baixa os pacotes para a pasta [node_modules] e grava as versões exatas selecionadas no arquivo [package-lock.json]. Para adicionar um pacote, digite [npm install package-name]: o comando o instala e acrescenta sua linha ao [package.json].
3.1.3. O arquivo angular.json
O arquivo [angular.json] diz ao [Angular CLI] como compilar e servir a aplicação. As linhas 14–36 (não mostradas) configuram os arquivos gerados pelo comando [ng generate] (estilos em [SCSS], sem testes). O restante:
| "root": "",
"sourceRoot": "src",
"prefix": "app",
"architect": {
"build": {
"builder": "@angular/build:application",
"options": {
"browser": "src/main.ts",
"tsConfig": "tsconfig.app.json",
"inlineStyleLanguage": "scss",
"assets": [
{
"glob": "**/*",
"input": "public"
}
],
"styles": [
"src/styles.scss"
]
},
"configurations": {
"production": {
"budgets": [
{
"type": "initial",
"maximumWarning": "2MB",
"maximumError": "5MB"
},
{
"type": "anyComponentStyle",
"maximumWarning": "8kB",
"maximumError": "16kB"
}
],
"outputHashing": "all"
},
"development": {
"optimization": false,
"extractLicenses": false,
"sourceMap": true
}
},
"defaultConfiguration": "production"
},
"serve": {
"builder": "@angular/build:dev-server",
"configurations": {
"production": {
"buildTarget": "examples_ionic:build:production"
},
"development": {
"buildTarget": "examples_ionic:build:development"
}
},
"defaultConfiguration": "development",
"options": {
"proxyConfig": "proxy.conf.json",
"port": 8100
}
}
|
- linhas 38–40: o projeto está na raiz da pasta; seu código-fonte está em [src/]. [prefix]: o prefixo das tags dos componentes ([app-root], [app-ex01]...);
- linhas 42–43: a compilação ([ng build]), tratada pelo builder [@angular/build:application];
- linha 45: o ponto de entrada da aplicação, [src/main.ts];
- linha 47: os estilos escritos dentro dos próprios componentes estão em [SCSS];
- linhas 48–53: o conteúdo da pasta [public/] é copiado como está para a aplicação compilada: o ícone [favicon.ico], a imagem [ex03/doctor.svg] do Exemplo 03 e os dicionários [i18n/] dos Exemplos 21 e 25;
- linhas 54–56: a folha de estilos global, [src/styles.scss];
- linhas 59–73: a configuração [production], que é a da aplicação entregue: o código é otimizado (esse é o padrão), os “budgets” emitem avisos se a aplicação ficar grande demais, e os nomes dos arquivos compilados contêm um hash de seu conteúdo ([outputHashing]), para que o navegador não mantenha em cache uma versão antiga;
- linhas 74–78: a configuração [development]: sem otimização e com “source maps”, que permitem às ferramentas de desenvolvimento do navegador exibir o código [TypeScript] original;
- linha 80: [ng build] usa a configuração [production]; [ng build --configuration development] usa a outra;
- linhas 82–97: o servidor de desenvolvimento ([ng serve]), configurado como [development] (linha 92), na porta 8100 (linha 95), com um repasse para o servidor JSON (linha 94).
3.1.4. O arquivo proxy.conf.json
| {
"/api": {
"target": "http://localhost:8080",
"secure": false,
"changeOrigin": false,
"logLevel": "warn"
}
}
|
Este arquivo só será usado nos exemplos 22 a 25. O servidor de desenvolvimento do [Angular] encaminha para o servidor JSON de [RdvMedecins] ([http://localhost:8080]) qualquer requisição cujo endereço comece por [/api]. Para o navegador, a aplicação e a API passam a ter a mesma origem ([http://localhost:8100]): não há verificação de CORS, e o cookie de sessão é aceito sem nenhuma configuração especial. Esses exemplos retomarão este ponto.
3.1.5. O arquivo capacitor.config.ts
| // =========================================================================
// capacitor.config.ts - a configuração do Capacitor
// -------------------------------------------------------------------------
// O Capacitor transforma a aplicação web (a pasta produzida por ng build)
// em uma aplicação Android: ele a encapsula em um projeto do Android Studio
// (pasta android/), onde é exibida por uma "WebView", o motor do
// navegador Chrome do celular. Comandos (veja o exemplo 01, "Execução"):
// npx cap add android (uma única vez: cria a pasta android/)
// ng build (compila a aplicação web)
// npx cap sync android (copia-a para o projeto Android)
// npx cap run android (executa em um emulador ou em um celular)
// =========================================================================
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
// o identificador único da aplicação no celular (e na Play Store)
appId: 'fr.stahe.examples',
// o nome exibido sob o ícone
appName: 'Ionic Examples',
// a pasta da aplicação web compilada (ng build)
webDir: 'dist/examples_ionic/browser',
server: {
// permite requisições HTTP não criptografadas (http://10.0.2.2:8080) para
// o servidor JSON de desenvolvimento (exemplos 22 a 25)
cleartext: true,
},
plugins: {
// CapacitorHttp: as requisições HTTP da aplicação deixam de ser feitas
// pela WebView e passam a ser feitas pelo código nativo do Android. Consequências (veja
// os exemplos 22 e 23): sem verificação de CORS (o servidor JSON não precisa
// liberar nada), e os cookies (o do token de autenticação) são
// armazenados pelo Android e reenviados automaticamente
CapacitorHttp: {
enabled: true,
},
},
};
export default config;
|
- linha 18: o ID da aplicação no celular, [fr.stahe.examples];
- linha 20: seu nome, exibido abaixo do ícone;
- linha 22: a pasta da aplicação web compilada, que o [Capacitor] copia para o projeto [Android];
- linhas 23–27: por padrão, o [Android] rejeita requisições HTTP não criptografadas; elas são permitidas para possibilitar a conexão com o servidor JSON de desenvolvimento (exemplos 22–25);
- linhas 28–37: as requisições HTTP serão feitas pelo código nativo do [Android] em vez de pelo navegador embutido. Mais uma vez, os exemplos 22 e 23 explicam o porquê.
Esta é a principal diferença arquitetural em relação ao [Flutter]: uma aplicação [Ionic] é uma aplicação **web** (HTML, CSS, JavaScript), que o [Capacitor] empacota em uma aplicação [Android]. Essa aplicação exibe apenas a “WebView”, o motor do navegador [Chrome] do celular, em tela cheia, que carrega a aplicação web incluída nela. O [Capacitor] também dá ao código JavaScript acesso aos recursos do celular (armazenamento, câmera, notificações etc.) por meio de plugins. O [Flutter], por outro lado, renderiza cada pixel da tela com seu próprio motor.
3.1.6. O arquivo tsconfig.json
| /* Para saber mais sobre o arquivo de configuração do TypeScript: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
/* Para saber mais sobre as opções do compilador do Angular: https://angular.dev/reference/configs/angular-compiler-options. */
{
"compileOnSave": false,
"compilerOptions": {
"strict": true,
"noImplicitOverride": true,
"noPropertyAccessFromIndexSignature": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
"skipLibCheck": true,
"isolatedModules": true,
"experimentalDecorators": true,
"importHelpers": true,
"target": "ES2022",
"module": "preserve"
},
"angularCompilerOptions": {
"enableI18nLegacyMessageIdFormat": false,
"strictInjectionParameters": true,
"strictInputAccessModifiers": true,
"strictTemplates": true
},
"files": [],
"references": [
{
"path": "./tsconfig.app.json"
}
]
}
|
As configurações do compilador [TypeScript]. Observe o seguinte:
- linha 6: [strict]: a tipagem mais rigorosa. Uma variável do tipo [string] não pode conter [null]; um parâmetro deve ter um tipo etc.;
- linha 8: uma propriedade de um objeto “dicionário” (do tipo [{ [key: string]: value }]) é acessada com colchetes: [errors['required']], não [errors.required] (veja o Exemplo 08);
- linhas 9–10: uma função deve retornar um valor em todos os casos; um [case] de um [switch] não deve “cair” no seguinte;
- linha 22: [strictTemplates]: os templates [HTML] são verificados com o mesmo rigor que o código [TypeScript]: uma propriedade com erro de grafia ou um argumento do tipo errado são erros de compilação (veja o exemplo 06).
3.1.7. A página src/index.html
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Ionic Examples</title>
<base href="/">
<!-- viewport-fit=cover: a aplicação ocupa toda a tela do celular, incluindo o notch;
user-scalable=no: sem zoom com dois dedos, como em uma aplicação nativa -->
<meta name="viewport" content="viewport-fit=cover, width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no">
<meta name="color-scheme" content="light dark">
<link rel="icon" type="image/x-icon" href="favicon.ico">
</head>
<body>
<app-root></app-root>
</body>
</html>
|
A aplicação web consiste nesta única página, que o navegador (ou a WebView do celular) carrega na inicialização:
- linha 2: o idioma da página, inglês;
- linha 6: a URL base da aplicação; as URLs das páginas ([/ex01], [/ex02]...) serão relativas à raiz;
- linha 9: a página ocupa toda a largura da tela, sem zoom: esse é o comportamento de um aplicativo, não de um site;
- linha 14: a tag [app-root], vazia: o [Angular] inserirá aí o componente raiz da aplicação.
3.1.8. O ponto de entrada: src/main.ts
| // =========================================================================
// src/main.ts - o ponto de entrada da aplicação
// -------------------------------------------------------------------------
// Uma aplicação Angular começa com bootstrapApplication: o Angular cria
// o componente RAIZ (App) e o insere na tag <app-root> da
// página index.html. O segundo parâmetro fornece os "providers"
// de toda a aplicação: Ionic, o roteador, o cliente HTTP, o idioma.
// =========================================================================
import { registerLocaleData } from '@angular/common';
import { provideHttpClient } from '@angular/common/http';
import localeFr from '@angular/common/locales/fr';
import { LOCALE_ID } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { provideRouter, withComponentInputBinding } from '@angular/router';
import { provideIonicAngular } from '@ionic/angular';
import { App } from './app/app';
import { routes } from './app/app.routes';
// as regras de formatação francesas (datas, números, valores) dos
// "pipes" do Angular, para o segundo idioma dos exemplos 09 e 21 (en-US já vem embutido)
registerLocaleData(localeFr);
bootstrapApplication(App, {
providers: [
// Ionic: modo 'md' (Material Design) = o visual do Android, mesmo no
// navegador de um computador (caso contrário o Ionic adota o visual do iOS em um iPhone)
provideIonicAngular({ mode: 'md' }),
// o roteador: a lista de rotas (app.routes.ts);
// withComponentInputBinding: os parâmetros de uma rota são entregues aos
// inputs (input) do componente da página (veja o exemplo 17)
provideRouter(routes, withComponentInputBinding()),
// o cliente HTTP do Angular (exemplos 22 a 25)
provideHttpClient(),
// o idioma da aplicação: inglês (americano)
{ provide: LOCALE_ID, useValue: 'en-US' },
],
}).catch((err) => console.error(err));
|
- linha 22: as regras de formatação francesas para datas e números, para os “pipes” do [Angular], usadas como segundo idioma nos exemplos 09 e 21 ([en-US] já vem incluído);
- linha 24: [bootstrapApplication] inicia o [Angular]: ele cria o componente raiz, [App], e o insere na tag [app-root] do [index.html]. O segundo parâmetro especifica os “providers” ([providers]) de toda a aplicação: os serviços que a injeção de dependência (Exemplo 14) fornecerá aos componentes que os solicitarem;
- linha 28: o [Ionic], no modo [md] ([Material Design], a aparência do [Android]). Sem esta configuração, o [Ionic] assumiria a aparência do [iOS] em um iPhone e a do [Material Design] nos demais;
- linha 32: o roteador do [Angular] e suas rotas (o arquivo [app.routes.ts]). O roteador associa uma página a cada endereço;
- linha 34: o cliente HTTP do [Angular] (exemplos 22 a 25);
- linha 36: o idioma da aplicação, [en-US] (inglês americano), para a formatação de datas e números.
Uma observação sobre o que **não** está neste arquivo: o [zone.js]. Até a versão 20, uma aplicação [Angular] carregava essa biblioteca, que monitorava todo o código assíncrono (eventos, timers, requisições) para determinar quando atualizar a tela. A partir da versão 21, uma nova aplicação “zoneless” dispensa-a: o [Angular] atualiza a tela quando um **signal** lido por um template muda e após cada evento tratado por um template (um toque, uma tecla pressionada). É assim que funcionam todos os exemplos deste curso, e é por isso que seus dados variáveis são signals.
3.1.9. Estilos: src/styles.scss
| // =========================================================================
// src/styles.scss - os estilos de toda a aplicação
// -------------------------------------------------------------------------
// as folhas de estilo do Ionic: sem elas, seus componentes não têm
// o visual próprio. core.css é essencial; as demais são utilitários
// (margens, alinhamentos, classes ion-padding, ion-text-center...).
// =========================================================================
@use '@ionic/angular/css/core.css';
@use '@ionic/angular/css/normalize.css';
@use '@ionic/angular/css/structure.css';
@use '@ionic/angular/css/typography.css';
@use '@ionic/angular/css/padding.css';
@use '@ionic/angular/css/float-elements.css';
@use '@ionic/angular/css/text-alignment.css';
@use '@ionic/angular/css/text-transformation.css';
@use '@ionic/angular/css/flex-utils.css';
@use '@ionic/angular/css/display.css';
// o tema escuro do Ionic, ativado pela classe CSS ion-palette-dark aplicada
// à tag <html> (veja o exemplo 20)
@use '@ionic/angular/css/palettes/dark.class.css';
// a cor principal da aplicação (botões, barra superior): um índigo,
// como nos exemplos Flutter. O Ionic deriva de --ion-color-primary as
// variantes mais clara (tint) e mais escura (shade)
:root {
--ion-color-primary: #3f51b5;
--ion-color-primary-rgb: 63, 81, 181;
--ion-color-primary-contrast: #ffffff;
--ion-color-primary-contrast-rgb: 255, 255, 255;
--ion-color-primary-shade: #37479f;
--ion-color-primary-tint: #5262bc;
}
|
- linhas 9–18: as folhas de estilo do [Ionic]: [core.css] é essencial; as outras fornecem classes utilitárias ([ion-padding], [ion-text-center], [ion-margin-top]...);
- linha 22: o tema escuro, ativado pela classe CSS (exemplo 20);
- linhas 27–34: a cor primária da aplicação ([primary]), um índigo, como nos exemplos do [Flutter]. Os componentes do [Ionic] têm uma propriedade [color] ([color="primary"], [color="danger"], [color="success"]...) que se serve dessa paleta.
3.1.10. O componente raiz: src/app/app.ts
| // =========================================================================
// src/app/app.ts - o componente RAIZ da aplicação
// -------------------------------------------------------------------------
// Ele contém apenas dois componentes Ionic:
// - <ion-app>: o contêiner de toda aplicação Ionic;
// - <ion-router-outlet>: o local onde o roteador exibe a página do
// endereço atual. O do Ionic (e não o <router-outlet> do Angular)
// anima a transição de uma página para outra e mantém as páginas
// anteriores na memória: o botão Voltar do celular retorna a elas sem recriá-las.
// Seu construtor conecta o botão Voltar do Android (veja back-button.ts).
// =========================================================================
import { Component } from '@angular/core';
import { IonApp, IonRouterOutlet } from '@ionic/angular';
import { handleBackButton } from './back-button';
@Component({
selector: 'app-root',
imports: [IonApp, IonRouterOutlet],
template: `
<ion-app>
<ion-router-outlet />
</ion-app>
`,
})
export class App {
constructor() {
handleBackButton();
}
}
|
- linha 14: os componentes do [Ionic] são importados do pacote [@ionic/angular]. Cada um é uma classe [TypeScript]: [IonApp] para a tag [<ion-app>], [IonRouterOutlet] para [<ion-router-outlet>], e assim por diante;
- linhas 17–25: um componente [Angular] é uma classe decorada com [@Component]. O decorador fornece o nome de sua tag ([selector]), os componentes usados por seu template ([imports]: um componente só conhece o que importa) e o próprio template, que é escrito diretamente no decorador ([template]);
- linha 21: [<ion-app>], o contêiner de toda a aplicação [Ionic];
- linha 22: [<ion-router-outlet>], o local onde o roteador exibe a página do endereço atual. Este é o do [Ionic], e não o [<router-outlet>] do [Angular]: ele cuida da navegação entre páginas, assim como o [Android] faz, e mantém as páginas anteriores na memória;
- linhas 26–30: a própria classe não tem dados nem comportamento próprios. Seu construtor, executado uma única vez na inicialização, conecta o botão Voltar do [Android] (linha 28).
Um celular [Android] tem um botão (ou gesto) Voltar. Em um aplicativo [Flutter], ele funciona por conta própria: fecha a janela aberta, volta à tela anterior e sai do aplicativo a partir da primeira tela. Em um aplicativo [Ionic], o [Capacitor] recebe o evento Voltar; se não encontra ninguém para tratá-lo, simplesmente retrocede no histórico da WebView e fecha o aplicativo quando esse histórico está vazio. O [Ionic] não é notificado disso: uma janela aberta (exemplo 16) não se fecha, e é possível sair da aplicação a partir de uma página que não seja o menu. É preciso, portanto, conectá-lo com o plugin [@capacitor/app]:
| // =========================================================================
// src/app/back-button.ts - o botão Voltar do Android
// -------------------------------------------------------------------------
// No celular, o Capacitor recebe o toque no botão Voltar. Se não
// houver listener para esse evento, ele simplesmente volta no
// histórico da WebView e depois fecha a aplicação: o Ionic não sabe nada
// sobre isso (um diálogo aberto não fecha, nem o menu lateral).
// O plugin @capacitor/app permite assiná-lo: assim que há um
// listener, o Capacitor repassa o toque ao Ionic, que chama o handler
// de maior prioridade:
// - 100: um diálogo aberto (alert, ion-modal...) é fechado;
// - 99: o menu lateral aberto é fechado;
// - 1: (o nosso) voltamos à tela anterior; se não houver,
// saímos da aplicação.
// No navegador, não há botão Voltar: não fazemos nada.
// =========================================================================
import { inject } from '@angular/core';
import { NavController, Platform } from '@ionic/angular';
import { App as CapacitorApp } from '@capacitor/app';
import { Capacitor } from '@capacitor/core';
// a ser chamado no construtor do componente raiz (contexto de injeção)
export function handleBackButton(): void {
if (!Capacitor.isNativePlatform()) return;
const navigation = inject(NavController);
// um listener (vazio): o Capacitor passa a repassar o toque ao Ionic
void CapacitorApp.addListener('backButton', () => {});
inject(Platform).backButton.subscribeWithPriority(1, async () => {
// pop(): volta à tela anterior da pilha do Ionic; false: a
// pilha contém apenas a tela exibida, não há nada atrás
if (!(await navigation.pop())) {
await CapacitorApp.exitApp();
}
});
}
|
- linha 20: o plugin [App] do [Capacitor] (instalado por [npm install @capacitor/app]). Ele se chama [App], como o componente raiz: é renomeado na importação ([as CapacitorApp]) para evitar confusão;
- linha 24: uma função comum, chamada pelo construtor do componente raiz. Ela usa [inject]: só pode ser chamada onde o [Angular] é capaz de fornecer serviços (um construtor, a inicialização de propriedades), o “contexto de injeção”;
- linha 25: em um navegador ([ng serve]), não há botão Voltar: nenhuma ação é executada. [Capacitor.isNativePlatform()] equivale a [true] na aplicação [Android];
- linha 26: o serviço [NavController] do [Ionic]: ele conhece as pilhas de páginas do [<ion-router-outlet>];
- linha 28: um listener do evento [backButton], que não faz nada. Sua mera presença basta: assim que há um listener, o [Capacitor] deixa de retroceder automaticamente no histórico e repassa o tratamento ao [Ionic];
- linhas 29–35: o [Ionic] recebe o tratamento e chama UM ÚNICO handler: o de maior prioridade. As janelas ([AlertController], [ion-modal], a lista do [ion-select]...) recebem prioridade 100, e o menu suspenso tem prioridade 99: quando uma delas está aberta, é essa que se fecha. Caso contrário, nosso tratamento prevalece (prioridade 1): [navigation.pop()] volta à página anterior e retorna [false] se não houver nenhuma; a aplicação é então encerrada ([exitApp()]).
Neste projeto, o menu é a única página inicial: o botão Voltar leva de um exemplo de volta ao menu e, em seguida, encerra a aplicação.
3.1.12. As rotas: src/app/app.routes.ts
| // =========================================================================
// src/app/app.routes.ts - as rotas da aplicação de exemplos
// -------------------------------------------------------------------------
// Uma rota associa um ENDEREÇO (path) a uma PÁGINA (um componente). A página
// inicial ('') é o menu dos exemplos; cada exemplo tem seu endereço:
// /ex01, /ex02... O código de um exemplo só é carregado quando vamos até ele
// (loadComponent, loadChildren: carregamento tardio, "lazy", veja o exemplo 17).
// =========================================================================
import { Routes } from '@angular/router';
export const routes: Routes = [
{ path: '', loadComponent: () => import('./home/home.page').then((m) => m.HomePage) },
{ path: 'ex01', loadComponent: () => import('./ex01-first-application/ex01.page').then((m) => m.Ex01Page) },
{ path: 'ex02', loadComponent: () => import('./ex02-state/ex02.page').then((m) => m.Ex02Page) },
{ path: 'ex03', loadComponent: () => import('./ex03-templates/ex03.page').then((m) => m.Ex03Page) },
{ path: 'ex04', loadComponent: () => import('./ex04-events/ex04.page').then((m) => m.Ex04Page) },
{ path: 'ex05', loadComponent: () => import('./ex05-controlled-fields/ex05.page').then((m) => m.Ex05Page) },
{ path: 'ex06', loadComponent: () => import('./ex06-reducer/ex06.page').then((m) => m.Ex06Page) },
{ path: 'ex07', loadComponent: () => import('./ex07-validation/ex07.page').then((m) => m.Ex07Page) },
{ path: 'ex08', loadComponent: () => import('./ex08-reactive-forms/ex08.page').then((m) => m.Ex08Page) },
{ path: 'ex09', loadComponent: () => import('./ex09-formatting/ex09.page').then((m) => m.Ex09Page) },
{ path: 'ex10', loadComponent: () => import('./ex10-component-inputs/ex10.page').then((m) => m.Ex10Page) },
{ path: 'ex11', loadComponent: () => import('./ex11-lifting-state-up/ex11.page').then((m) => m.Ex11Page) },
{ path: 'ex12', loadComponent: () => import('./ex12-composition/ex12.page').then((m) => m.Ex12Page) },
{ path: 'ex13', loadComponent: () => import('./ex13-lifecycle/ex13.page').then((m) => m.Ex13Page) },
{ path: 'ex14', loadComponent: () => import('./ex14-injection/ex14.page').then((m) => m.Ex14Page) },
{ path: 'ex15', loadComponent: () => import('./ex15-behaviours/ex15.page').then((m) => m.Ex15Page) },
{ path: 'ex16', loadComponent: () => import('./ex16-confirmation/ex16.page').then((m) => m.Ex16Page) },
// os exemplos 17 e 18 têm suas próprias rotas, "filhas" de /ex17 e /ex18
{ path: 'ex17', loadChildren: () => import('./ex17-router/routes').then((m) => m.routes) },
{ path: 'ex18', loadChildren: () => import('./ex18-guards/routes').then((m) => m.routes) },
{ path: 'ex19', loadComponent: () => import('./ex19-asynchronous/ex19.page').then((m) => m.Ex19Page) },
{ path: 'ex20', loadComponent: () => import('./ex20-shared-state/ex20.page').then((m) => m.Ex20Page) },
{ path: 'ex21', loadComponent: () => import('./ex21-i18n/ex21.page').then((m) => m.Ex21Page) },
{ path: 'ex22', loadComponent: () => import('./ex22-http/ex22.page').then((m) => m.Ex22Page) },
{ path: 'ex23', loadComponent: () => import('./ex23-login/ex23.page').then((m) => m.Ex23Page) },
{ path: 'ex24', loadComponent: () => import('./ex24-api-layer/ex24.page').then((m) => m.Ex24Page) },
{ path: 'ex25', loadComponent: () => import('./ex25-server-errors/ex25.page').then((m) => m.Ex25Page) },
// qualquer outro endereço leva de volta ao menu
{ path: '**', redirectTo: '' },
];
|
- linha 12: as rotas: um array de objetos [Route];
- linha 13: a URL vazia ([http://localhost:8100/]) exibe a página inicial, [HomePage]. [loadComponent] contém uma função que importa o arquivo do componente: esse arquivo só é carregado quando você navega até esse endereço (lazy loading; veja o Exemplo 17). Na inicialização, a aplicação carrega, portanto, apenas o menu;
- linhas 14–29: uma rota, por exemplo: [/ex01], [/ex02]...;
- linhas 31–32: os Exemplos 17 e 18 têm suas próprias rotas (Exemplo 17);
- linha 41: qualquer outro endereço volta ao menu.
3.1.13. Lista de exemplos: src/app/examples.ts
| // =========================================================================
// src/app/examples.ts - a lista dos 25 exemplos
// -------------------------------------------------------------------------
// Uma fonte única para a página inicial (o menu dos exemplos). Cada
// exemplo tem um número, um título e um capítulo; seu endereço (/ex01, /ex02...)
// é declarado em app.routes.ts.
// =========================================================================
export interface Example {
number: string; // '01'...'25'
title: string;
chapter: string;
}
export const EXAMPLES: Example[] = [
{ number: '01', title: 'a first application', chapter: 'First steps' },
{ number: '02', title: 'state and computed values', chapter: 'First steps' },
{ number: '03', title: 'writing a template', chapter: 'First steps' },
{ number: '04', title: 'events', chapter: 'First steps' },
{ number: '05', title: 'all the field types', chapter: 'First steps' },
{ number: '06', title: 'a form, an object, a reducer', chapter: 'First steps' },
{ number: '07', title: 'validating a form, by hand', chapter: 'First steps' },
{ number: '08', title: 'reactive forms', chapter: 'First steps' },
{ number: '09', title: 'formatting values', chapter: 'First steps' },
{ number: '10', title: 'components and their inputs', chapter: 'Components' },
{ number: '11', title: 'the child notifies its parent', chapter: 'Components' },
{ number: '12', title: 'composition', chapter: 'Components' },
{ number: '13', title: 'the lifecycle of a component', chapter: 'Components' },
{ number: '14', title: 'dependency injection', chapter: 'Components' },
{ number: '15', title: 'reusing behaviours', chapter: 'Components' },
{ number: '16', title: 'a reusable confirmation dialog', chapter: 'Components' },
{ number: '17', title: 'the router', chapter: 'Routing' },
{ number: '18', title: 'navigation guards', chapter: 'Routing' },
{ number: '19', title: 'promises, observables and timers', chapter: 'Asynchrony and shared state' },
{ number: '20', title: 'a shared state', chapter: 'Asynchrony and shared state' },
{ number: '21', title: 'an application in two languages', chapter: 'Internationalization' },
{ number: '22', title: 'a first HTTP request', chapter: 'Talking to the server' },
{ number: '23', title: 'login, cookie and session', chapter: 'Talking to the server' },
{ number: '24', title: 'an API access layer', chapter: 'Talking to the server' },
{ number: '25', title: 'the errors returned by the server', chapter: 'Talking to the server' },
];
|
- linhas 9–13: uma interface [TypeScript] descreve a estrutura de um objeto: neste caso, um número, um título e um capítulo (três strings);
- linhas 15–41: os 25 exemplos, um array de objetos [Example]. A palavra-chave [export] torna a constante visível para outros arquivos, que a importam por meio de [import { EXAMPLES } from '../examples'].
3.1.14. A página inicial
A página inicial exibe esta tabela, agrupada por capítulo:
| // =========================================================================
// src/app/home/home.page.ts - o menu dos 25 exemplos
// -------------------------------------------------------------------------
// A primeira página da aplicação: a lista dos exemplos, agrupados por
// capítulo. Um toque em um exemplo abre sua página (/ex01, /ex02...).
// =========================================================================
import { Component } from '@angular/core';
import { RouterLink } from '@angular/router';
import {
IonContent, IonHeader, IonItem, IonItemDivider, IonItemGroup, IonLabel, IonList, IonTitle, IonToolbar,
} from '@ionic/angular';
import { EXAMPLES, Example } from '../examples';
@Component({
selector: 'app-home',
imports: [RouterLink, IonHeader, IonToolbar, IonTitle, IonContent, IonList, IonItemGroup, IonItemDivider, IonItem, IonLabel],
templateUrl: './home.page.html',
})
export class HomePage {
// os exemplos, agrupados por capítulo: [{ chapter, examples: [...] }, ...]
readonly chapters: { chapter: string; examples: Example[] }[] = [];
constructor() {
for (const example of EXAMPLES) {
let group = this.chapters.find((c) => c.chapter === example.chapter);
if (!group) {
group = { chapter: example.chapter, examples: [] };
this.chapters.push(group);
}
group.examples.push(example);
}
}
}
|
- linhas 15–19: o componente, sua tag, seus subcomponentes e seu template, que agora fica em um arquivo separado ([templateUrl]);
- linha 22: um campo da classe, lido pelo template: a lista de capítulos, cada um com seus exemplos;
- linhas 24–33: o construtor coloca cada exemplo no grupo de seu capítulo, criando o grupo quando necessário.
| <!-- o menu dos exemplos -->
<ion-header>
<ion-toolbar color="primary">
<ion-title>Ionic Examples</ion-title>
</ion-toolbar>
</ion-header>
<ion-content>
<ion-list>
@for (group of chapters; track group.chapter) {
<ion-item-group>
<ion-item-divider color="light">
<ion-label>{{ group.chapter }}</ion-label>
</ion-item-divider>
@for (example of group.examples; track example.number) {
<!-- routerLink: um toque no item abre a página do exemplo;
detail: a pequena seta à direita -->
<ion-item [routerLink]="'/ex' + example.number" detail>
<ion-label>Example {{ example.number }} - {{ example.title }}</ion-label>
</ion-item>
}
</ion-item-group>
}
</ion-list>
</ion-content>
|
- linhas 2–6: a barra superior: [<ion-header>] contém uma barra de ferramentas, [<ion-toolbar>], nas cores da aplicação ([color="primary"]), e seu título, [<ion-title>];
- linha 8: [<ion-content>]: o corpo da página, que rola quando excede a altura da tela;
- linha 9: [<ion-list>]: uma lista;
- linha 10: [@for] repete seu bloco para cada elemento de um array (veja o exemplo 03): um grupo por capítulo;
- linhas 12–14: o título do grupo, uma linha separadora ([<ion-item-divider>]);
- linha 18: uma linha da lista ([<ion-item>]), por exemplo. [[routerLink]]: tocar na linha leva à URL do exemplo; [detail]: a pequena seta à direita.

3.1.15. A página do Exemplo 01
Um exemplo é uma página, isto é, um componente, associada a um endereço pelo roteador. A do Exemplo 01:
| // =========================================================================
// src/app/ex01-first-application/ex01.page.ts - uma primeira aplicação
// -------------------------------------------------------------------------
// Uma página Ionic é um COMPONENTE Angular: uma classe TypeScript, decorada
// com @Component, associada a um TEMPLATE HTML que descreve o que
// ela exibe. O template mistura tags HTML comuns, componentes Ionic
// (<ion-button>, <ion-card>...) e expressões {{ ... }}
// que exibem os dados da classe.
// Os dados que mudam são SIGNALS: quando o valor de um signal
// muda, o Angular atualiza, na tela, o que o exibe.
// =========================================================================
import { Component, signal } from '@angular/core';
import {
IonBackButton, IonButton, IonButtons, IonContent, IonHeader, IonText, IonTitle, IonToolbar,
} from '@ionic/angular';
// dados "comuns", fora do componente: nunca mudam
const title = 'Welcome to Ionic';
const languages = ['TypeScript', 'Angular', 'Ionic'];
// "12:05:09": a hora atual, com dois dígitos
function currentTime(): string {
const d = new Date();
const twoDigits = (n: number) => n.toString().padStart(2, '0');
return `${twoDigits(d.getHours())}:${twoDigits(d.getMinutes())}:${twoDigits(d.getSeconds())}`;
}
@Component({
// o nome da tag do componente (<app-ex01>): o roteador a insere
// sozinho, nós nunca a escrevemos
selector: 'app-ex01',
// os componentes Ionic usados pelo template: um componente só
// conhece o que importa
imports: [IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonButton, IonText],
// o template, em um arquivo separado
templateUrl: './ex01.page.html',
})
export class Ex01Page {
// dados lidos pelo template: campos simples da classe
readonly title = title;
readonly languages = languages;
// o ESTADO: signals. signal(0) cria um signal com valor inicial 0;
// lemos seu valor chamando-o como uma função: counter()
readonly counter = signal(0);
readonly time = signal(currentTime());
// o método chamado pelo botão
increment(): void {
// set: o novo valor; update: o novo valor, calculado a partir
// do antigo. O Angular então atualiza a tela: nunca a
// modificamos nós mesmos
this.counter.update((n) => n + 1);
this.time.set(currentTime());
}
}
|
- linha 13: [Component] (o decorador de componente) e [signal] vêm do núcleo do [Angular];
- linhas 14–16: os componentes do [Ionic] usados pelo template;
- linhas 19–20: dois valores de dados comuns, declarados fora do componente: eles nunca mudam. [const]: uma variável à qual se atribui um valor uma única vez;
- linhas 23–27: uma função comum que retorna a hora atual no formato “12:05:09”. Ela contém uma pequena arrow function, [twoDigits]. [
...${expression}...] é um template string: o valor de cada expressão é inserido nele;
- linhas 29–38: o decorador [@Component]: a tag do componente (linha 32, que o próprio roteador insere: nós nunca a escrevemos), os componentes do [Ionic] usados por seu template (linha 35) e o arquivo que contém seu template (linha 37);
- linha 39: a classe do componente. [export]: o arquivo de rotas a importa;
- linhas 41–42: dois campos da classe, lidos pelo template. [readonly]: eles não serão reatribuídos;
- linhas 46–47: o **estado** do componente, os dados que mudam: dois **signals**. [signal(0)] cria um signal com valor inicial 0, cujo tipo ([number]) é inferido a partir desse valor. O valor de um signal é lido chamando-o como uma função: [counter()];
- linhas 50–56: o método chamado pelo botão. Ele não interage com a tela; ele altera o estado. [update] calcula o novo valor a partir do antigo (linha 54), e [set] o define diretamente (linha 55). O [Angular] então sabe que as partes da tela que leem esses signals precisam ser redesenhadas, e as redesenha.
O template:
| <!-- ======================================================================
ex01.page.html - o template da página do exemplo 01
====================================================================== -->
<!-- ion-header: a barra superior, com um botão Voltar e um título -->
<ion-header>
<ion-toolbar color="primary">
<ion-buttons slot="start">
<!-- o botão Voltar: leva de volta ao menu dos exemplos (defaultHref)
se chegamos diretamente a esta página -->
<ion-back-button defaultHref="/" />
</ion-buttons>
<ion-title>Example 01 - a first application</ion-title>
</ion-toolbar>
</ion-header>
<!-- ion-content: o corpo da página, que rola se necessário;
ion-padding: uma margem ao redor -->
<ion-content class="ion-padding">
<h2>{{ title }}</h2>
<p>This screen is built by Ionic and Angular, from the Ex01Page component and its template.</p>
<!-- {{ expression }}: o valor de uma expressão TypeScript, inserido no texto -->
<p>It is written in {{ languages.join(', ') }} ({{ languages.length }} languages).</p>
<!-- (click): o método a chamar quando o botão é pressionado (veja o exemplo 04) -->
<ion-button (click)="increment()">Click me</ion-button>
<p>
<!-- counter(): LEMOS um signal chamando-o -->
<ion-text color="primary">
<strong>You clicked {{ counter() }} times (last click: {{ time() }}).</strong>
</ion-text>
</p>
</ion-content>
|
- linhas 6–15: a barra superior. [<ion-buttons slot="start">] coloca botões no início da barra (à esquerda): um botão Voltar, [<ion-back-button>], que leva de volta à página anterior. Se não houver uma (você digitou o endereço diretamente, [/ex01]), [defaultHref] especifica a página para a qual ir: o menu;
- linha 19: o corpo da página, com uma margem ao redor (classe [ion-padding]);
- linha 20: [{{ title }}]: uma “interpolação”, isto é, o valor de uma expressão inserido no texto. A expressão é avaliada no contexto da classe: [title] é o campo da linha 41 do componente;
- linha 23: uma expressão pode chamar métodos: [languages.join(', ')], [languages.length];
- linha 26: [(click)="increment()"]: quando o botão é pressionado, o [Angular] executa a instrução escrita entre as aspas. A chamada é escrita com parênteses: a instrução só é executada quando o botão é pressionado (veja o Exemplo 04);
- linhas 30–32: texto que depende do estado. [counter()] lê o signal: quando ele muda, este texto muda. [<ion-text color="primary">] colore seu conteúdo.
A árvore de componentes da tela, como exibida pela extensão [Angular DevTools] das ferramentas de desenvolvimento do [Chrome] (aba [Angular]), complementada com os elementos HTML:
| App (app-root)
└── ion-app
└── ion-router-outlet
└── Ex01Page (app-ex01)
├── ion-header
│ └── ion-toolbar
│ ├── ion-buttons
│ │ └── ion-back-button
│ └── ion-title
└── ion-content
├── h2 (the title)
├── p
├── p
├── ion-button
└── p
└── ion-text
└── strong (the counter)
|
Assim como no [Flutter], escrevemos pouquíssimo código de “implementação” e muito código “descritivo”. Mas, enquanto o [Flutter] descreve a tela em [Dart] por meio de construtores de widgets aninhados, o [Angular] separa as duas coisas: a classe [TypeScript] contém os dados e os comportamentos, enquanto o template [HTML] descreve a tela. Os componentes do [Ionic] ([<ion-button>], [<ion-toolbar>]...) são verdadeiros elementos HTML, “web components” (“Web Components”) criados pela biblioteca [@ionic/core]: eles funcionam em qualquer navegador, e o [@ionic/angular] os encapsula para que o [Angular] possa tratá-los como seus próprios componentes. É por isso que o mesmo [Ionic] também existe para [React] e [Vue.js].
3.1.16. Execução
No console aberto na pasta [examples_ionic] (com os pacotes já instalados uma vez por [npm install]):
O console exibe:
| > examples-ionic@0.0.0 start
> ng serve
Initial chunk files | Names | Raw size
styles.css | styles | 56.90 kB |
main.js | main | 6.35 kB |
| Initial total | 63.25 kB
Lazy chunk files | Names | Raw size
chunk-QC4MGRJ7.js | home-page | 7.15 kB |
chunk-IMCNE3A4.js | ex01-page | 6.23 kB |
...
Application bundle generation complete. [6.046 seconds]
Watch mode enabled. Watching for file changes...
➜ Local: http://localhost:8100/
|
A aplicação compila em alguns segundos: um arquivo [main.js] carregado na inicialização e um pequeno arquivo por página (“lazy chunk”), carregado sob demanda. Abra a URL [http://localhost:8100] no [Chrome]. Para ver a aplicação no tamanho de um celular, abra as ferramentas de desenvolvimento (F12), depois a barra de emulação de dispositivos (Ctrl+Shift+M) e selecione um celular na lista (um [Pixel 7], por exemplo) ou especifique as dimensões (as capturas de tela deste tutorial têm 412 x 892 pixels). À esquerda, a tela inicial do Exemplo 01; à direita, depois de tocar duas vezes no botão:
Dois experimentos para fazer:
- Edite o texto da linha 21 de [ex01.page.html] e salve o arquivo: o console exibe [Component update sent to client(s)], e a tela muda imediatamente, com o contador mantendo seu valor. Isso é um hot reload: o novo template substitui o antigo na aplicação em execução. Uma alteração no código [TypeScript] ([ex01.page.ts]), por outro lado, recarrega a página inteira ([Page reload sent to client(s)]): o contador volta a 0, como no “hot restart” do [Flutter];
- Explore a aplicação com as ferramentas de desenvolvimento: a aba [Elements] exibe as tags [<ion-...>] da página, a aba [Console] mostra eventuais erros, e a aba [Sources] exibe o código [TypeScript] (graças aos “source maps”), onde é possível definir pontos de interrupção.
Passemos agora ao [Android]. Primeiro, é preciso criar o projeto [Android]:
Este comando cria a pasta [android/]: um projeto [Android Studio] completo que simplesmente exibe a WebView e carrega nela a aplicação web. Raramente se fazem alterações nele (o ícone, as permissões). Contudo, um ajuste é necessário com as versões recentes do [Android Studio]: o JDK delas é um [Java] 25, que não é suportado pela versão do [Gradle] selecionada pelo [Capacitor] 8 (versão 8.14). O build então falha com o erro [Unsupported class file major version 69]. Basta passar para o [Gradle] 9.1 modificando uma linha do arquivo [android/gradle/wrapper/gradle-wrapper.properties]:
| distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-all.zip
|
(em vez de [gradle-8.14.3-all.zip]). O primeiro build baixa esta versão do [Gradle] (cerca de 200 MB). Depois, a cada vez que a aplicação mudar:
| npx ng build
npx cap sync android
npx cap run android
|
- Linha 1: compila a aplicação web na pasta [dist/examples_ionic/browser] (configuração [production]);
- linha 2: copia-a para o projeto [Android] (usando a configuração de [capacitor.config.ts] e os plugins do [Capacitor]);
- linha 3: compila a aplicação [Android] (com a ferramenta [Gradle]), instala-a em um emulador em execução ou em um celular conectado e a inicia. O comando pede que você selecione um dispositivo se houver vários disponíveis.
No celular, o botão Voltar leva de volta uma tela, até o menu, e encerra a aplicação a partir do menu (veja [back-button.ts]).
Você também pode abrir o projeto no [Android Studio] ([npx cap open android]) e iniciar a aplicação pelo botão [Run]. O primeiro build leva um ou dois minutos; os seguintes levam apenas alguns segundos. No celular, a tela é a mesma do navegador, renderizada pelo mesmo motor, o do [Chrome]. Ela também é depurada com as mesmas ferramentas: o endereço [chrome://inspect], no [Chrome] do computador, lista as WebViews das aplicações em execução no emulador e abre suas ferramentas de desenvolvimento.
Esse ciclo (compilar, copiar, build) não oferece o hot reload do [ng serve]. Para ativá-lo no celular, é possível instruir o aplicativo a buscar seu código no servidor de desenvolvimento do computador, em vez de em sua cópia embutida:
| npx ng serve --host 0.0.0.0
npx cap run android --live-reload --host=192.168.1.20 --port=8100
|
- linha 1: o servidor de desenvolvimento aceita conexões de outras máquinas além do próprio computador (por padrão, ele só escuta em [localhost]);
- linha 2: [192.168.1.20] é o endereço do computador na rede local ([ipconfig] no [Windows] o informa). A aplicação instalada passa então a carregar [http://192.168.1.20:8100] e a recarregá-lo sempre que uma alteração é feita.
Use com cuidado: o celular deve estar conectado ao computador (mesma rede Wi-Fi, firewall do computador aberto na porta 8100), e o aplicativo instalado dessa forma não funcionará mais sem o servidor de desenvolvimento. Ao terminar o trabalho, execute novamente [npx ng build], seguido de [npx cap sync android], para que o aplicativo volte a embutir seu próprio código. Neste curso, desenvolveremos no navegador e depois executaremos no [Android] para verificar.
3.2. Exemplo 02: estado e valores calculados
O estado está no centro do [Angular], assim como do [Flutter] e do [React]. Este exemplo calcula o preço com IVA de um item:
| // =========================================================================
// src/app/ex02-state/ex02.page.ts - estado e valores calculados
// -------------------------------------------------------------------------
// Uma pequena calculadora de preços (com IVA):
// - o ESTADO: signals (signal()). Mudar seu valor (set, update)
// atualiza, na tela, o que os exibe;
// - um valor CALCULADO a partir do estado NÃO é estado: é um
// signal calculado (computed()), recalculado quando um dos signals que ele
// lê muda. Está sempre atualizado, sem nada a sincronizar;
// - um dado que depende dos valores SUCESSIVOS do estado (o histórico
// dos totais) é atualizado onde o estado muda: no método
// change(), pelo qual passam todas as mudanças;
// - o título da aplicação (aba do navegador) não está no
// template: é um EFFECT (effect()), uma função que o Angular reexecuta
// a cada vez que um dos signals que ela lê muda.
// =========================================================================
import { Component, computed, DestroyRef, effect, inject, signal } from '@angular/core';
import { Title } from '@angular/platform-browser';
import {
IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonCardHeader, IonCardSubtitle, IonCardTitle,
IonContent, IonHeader, IonIcon, IonInput, IonItem, IonLabel, IonList, IonNote, IonSegment, IonSegmentButton,
IonTitle, IonToolbar, SegmentValue,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { add, remove } from 'ionicons/icons';
// um formatador de valores em euros, no estilo inglês (€1,234.50), veja o exemplo 09
const euros = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR' });
// os valores iniciais (botão Redefinir)
const LABEL = 'Pen';
const PRICE = '2.5';
@Component({
selector: 'app-ex02',
imports: [
IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonCard, IonCardHeader, IonCardTitle,
IonCardSubtitle, IonCardContent, IonInput, IonButton, IonIcon, IonSegment, IonSegmentButton, IonList, IonItem,
IonLabel, IonNote,
],
templateUrl: './ex02.page.html',
styles: `
.quantity { display: flex; align-items: center; margin: 12px 0 8px; }
.quantity span { flex: 1; }
.quantity strong { font-size: 1.1em; min-width: 1.5em; text-align: center; }
.bold { font-weight: bold; }
ion-note { font-size: 1rem; }
`,
})
export class Ex02Page {
// o estado: quatro signals, tipados pelo valor inicial
// (o preço é mantido como TEXTO: o que digitamos, com o separador)
readonly label = signal(LABEL);
readonly priceText = signal(PRICE);
readonly quantity = signal(1);
readonly vatRate = signal(20); // em %
// o histórico das últimas 5 mudanças do total com IVA
readonly history = signal<string[]>([]);
// valores CALCULADOS: computed() memoriza o resultado e só
// o recalcula se um dos signals lidos tiver mudado
readonly priceExclVat = computed(() => Number(this.priceText().replace(',', '.')) || 0);
readonly totalExclVat = computed(() => this.quantity() * this.priceExclVat());
readonly vatAmount = computed(() => (this.totalExclVat() * this.vatRate()) / 100);
readonly totalInclVat = computed(() => this.totalExclVat() + this.vatAmount());
// as linhas do cartão de resultados: DADOS, que o template percorre
readonly lines = computed(() => [
{ label: 'Total excl. VAT', amount: euros.format(this.totalExclVat()), bold: false },
{
label: `VAT (${this.vatRate()} %)`,
amount: euros.format(this.vatAmount()),
bold: false,
},
{ label: 'Total incl. VAT', amount: euros.format(this.totalInclVat()), bold: true },
]);
constructor() {
// os ícones usados pelo template (<ion-icon name="add" />)
addIcons({ add, remove });
// o serviço Title do Angular muda o título da página (a aba do
// navegador). effect() reexecuta a função a cada vez que totalInclVat muda
const title = inject(Title);
effect(() => title.setTitle(`Incl. VAT: ${euros.format(this.totalInclVat())}`));
// quando saímos da página (o componente é destruído), restauramos o título da aplicação
inject(DestroyRef).onDestroy(() => title.setTitle('Ionic Examples'));
}
// TODAS as mudanças do estado passam por este método: ele anota o
// total com IVA antes da mudança, aplica a mudança e completa
// o histórico se o total mudou
change(apply: () => void): void {
const oldTotal = this.totalInclVat();
apply();
// ler um computed após uma mudança o recalcula imediatamente
const newTotal = this.totalInclVat();
if (newTotal !== oldTotal) {
const line = `${euros.format(oldTotal)} -> ${euros.format(newTotal)}`;
// um NOVO array (e não push): o signal percebe que seu valor mudou
this.history.update((h) => [line, ...h].slice(0, 5));
}
}
// mudar o item redefine a quantidade para 1: fazemos isso onde sabemos
// POR QUE o estado muda
changeLabel(newValue: string): void {
this.change(() => {
this.label.set(newValue);
this.quantity.set(1);
});
}
changePrice(text: string): void {
this.change(() => this.priceText.set(text));
}
// delta: -1 ou +1
addQuantity(delta: number): void {
this.change(() => this.quantity.update((q) => q + delta));
}
// o valor de um segmento é do tipo SegmentValue (string | number), ou
// undefined se nenhum botão estiver escolhido: Number() o converte em número
changeRate(value: SegmentValue | undefined): void {
this.change(() => this.vatRate.set(Number(value)));
}
reset(): void {
this.change(() => {
this.label.set(LABEL);
this.priceText.set(PRICE);
this.quantity.set(1);
this.vatRate.set(20);
});
}
}
|
- Linha 18: [Angular] funções usadas: [signal], [computed], [effect], [inject] e [DestroyRef];
- linha 19: o serviço [Title], que dá acesso ao título da página;
- linhas 25–26: os ícones. [Ionic] só fornece os ícones que a aplicação declara: eles são importados de [ionicons/icons] (aqui, [add], o “+”, e [remove], o “-”) e registrados por [addIcons] (linha 80); o template então se refere a eles pelo nome ([<ion-icon name="add" />]);
- linha 29: um formatador de valores monetários no estilo inglês (€1,234.50), criado uma única vez fora do componente, com a API JavaScript [Intl] (veja o exemplo 09);
- linhas 43–49: estilos específicos deste componente. O [Angular] os “encapsula”: a classe [.bold] deste componente se aplica apenas ao seu template e não se estende às outras páginas;
- linhas 54–57: quatro variáveis de estado, quatro signals. O tipo delas é inferido a partir dos valores iniciais: [signal('Pen')] é um signal de string, [signal(1)] é um signal numérico. [TypeScript] tem um único tipo para números, a saber, [number]. O preço é guardado exatamente como foi digitado, como texto: veremos por quê;
- linha 59: o histórico das últimas cinco alterações do total. [signal<string[]>([])]: quando o valor inicial não basta para determinar o tipo (um array vazio, mas de quê?), o tipo é indicado entre sinais de menor e maior;
- Linhas 63–66: quatro valores **calculados** a partir do estado. Eles NÃO são estados; são signals calculados ([computed(() => ...)]). O [Angular] rastreia os signals lidos pela função (aqui, [priceText], depois [quantity] e [priceExclVat]...) e chama a função novamente somente se algum deles tiver mudado; caso contrário, devolve o resultado em cache. Um signal calculado é lido como qualquer outro ([totalInclVat()]), mas não é escrito. É a mesma regra que já vimos com [Flutter] e [React]: só o que não pode ser calculado é guardado no estado; todo o resto é calculado;
- linha 63: o preço, derivado do texto digitado. [Number('3.2')] converte o texto em número e devolve [NaN] (“not a number”) se o texto não for um número: [|| 0] então substitui [NaN] (e 0) por 0. A vírgula francesa é aceita, substituindo-a por um ponto;
- linhas 68–76: as três linhas da tabela de resultados, em formato de dados: um array de objetos que o template percorrerá. O rótulo do IVA depende da alíquota: ele também é um valor calculado;
- Linhas 84–85: o título da página (a aba do navegador) acompanha o total. O título não faz parte do template da página: é um **efeito** colateral, tratado por [effect()]. Como [computed], [effect] rastreia os signals lidos por sua função e a chama sempre que um deles muda. O serviço [Title] é obtido por [inject(Title)], a injeção de dependência do [Angular] (Exemplo 14); [inject] só é chamado durante a construção do componente;
- linha 87: quando se sai da página, o componente é destruído; [DestroyRef.onDestroy] registra uma função chamada nesse momento, que restaura o título da aplicação. O próprio efeito é interrompido automaticamente;
- linhas 93–103: o histórico dos totais depende dos valores **sucessivos** do total, algo que um signal calculado não consegue expressar. Por isso, fazemos TODAS as alterações de estado passarem pelo método [change], que recebe como parâmetro a alteração a ser feita — uma função sem parâmetros nem valor de retorno (do tipo [() => void]): ele registra o total antes da alteração, aplica a alteração, lê o total depois dela (um signal calculado lido após uma alteração é recalculado imediatamente) e atualiza o histórico se o total mudou. Este é o lugar natural para esse cálculo: onde o estado muda;
- Linha 101: [update] recebe o array antigo e devolve o novo: a nova linha, seguida das antigas ([...h] as “espalha”), das quais somente as cinco primeiras são mantidas. Criamos um array NOVO, em vez de modificar o antigo com [push]: um signal compara o valor antigo com o novo para determinar se mudou, e um array modificado no próprio lugar continuaria, do ponto de vista do signal, sendo o mesmo array;
- linhas 107–112: trocar o item redefine a quantidade para 1. Isso é feito no método que trata a alteração do campo, onde sabemos por que o estado está mudando;
- linhas 125–127: a alíquota selecionada nos botões de opção. Seu valor é do tipo [SegmentValue] (uma string ou um número), ou [undefined] se nenhum botão estiver selecionado: [Number] o converte em número;
- linhas 129–136: várias alterações de estado consecutivas: o [Angular] atualizará a tela apenas uma vez, depois do método.
O template:
| <!-- ======================================================================
ex02.page.html - o template da calculadora de preços (com IVA)
====================================================================== -->
<ion-header>
<ion-toolbar color="primary">
<ion-buttons slot="start">
<ion-back-button defaultHref="/" />
</ion-buttons>
<ion-title>Example 02 - state</ion-title>
</ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
<ion-card>
<ion-card-content>
<!-- [value]: o campo EXIBE o valor do signal;
(ionInput): chamado a cada tecla digitada; $event.detail.value é o novo texto -->
<ion-input label="Item" labelPlacement="floating" [value]="label()"
(ionInput)="changeLabel($event.detail.value ?? '')" />
<!-- inputmode="decimal": o teclado numérico do celular, com o separador decimal -->
<ion-input label="Unit price excl. VAT" labelPlacement="floating" inputmode="decimal" [value]="priceText()"
(ionInput)="changePrice($event.detail.value ?? '')" />
<div class="quantity">
<span>Quantity (back to 1 if the item changes)</span>
<!-- [disabled]: o botão fica desabilitado enquanto a condição for verdadeira -->
<ion-button fill="clear" [disabled]="quantity() <= 0" (click)="addQuantity(-1)">
<ion-icon slot="icon-only" name="remove" />
</ion-button>
<strong>{{ quantity() }}</strong>
<ion-button fill="clear" (click)="addQuantity(1)">
<ion-icon slot="icon-only" name="add" />
</ion-button>
</div>
<!-- botões dos quais apenas UM é selecionado: a alíquota do IVA -->
<ion-segment [value]="vatRate()" (ionChange)="changeRate($event.detail.value)">
<ion-segment-button [value]="5.5"><ion-label>5.5 %</ion-label></ion-segment-button>
<ion-segment-button [value]="10"><ion-label>10 %</ion-label></ion-segment-button>
<ion-segment-button [value]="20"><ion-label>20 %</ion-label></ion-segment-button>
</ion-segment>
<div class="ion-text-center ion-margin-top">
<ion-button fill="outline" shape="round" (click)="reset()">Reset</ion-button>
</div>
</ion-card-content>
</ion-card>
<ion-card>
<ion-card-header>
<!-- {{ }}: lemos os signals chamando-os -->
<ion-card-title>{{ quantity() }} x {{ label() }}</ion-card-title>
</ion-card-header>
<ion-list lines="none">
<!-- uma linha por elemento do array calculado lines() (veja o exemplo 03) -->
@for (line of lines(); track line.label) {
<ion-item>
<ion-label [class.bold]="line.bold">{{ line.label }}</ion-label>
<ion-note slot="end" color="dark" [class.bold]="line.bold">{{ line.amount }}</ion-note>
</ion-item>
}
</ion-list>
</ion-card>
<ion-card>
<ion-card-header>
<ion-card-subtitle>History of the total incl. VAT</ion-card-subtitle>
</ion-card-header>
<ion-card-content>
@for (line of history(); track $index) {
<div>• {{ line }}</div>
}
</ion-card-content>
</ion-card>
</ion-content>
|
- linha 15: [<ion-card>], um cartão: um bloco com cantos arredondados, levemente elevado;
- linhas 19–20: um campo de entrada, [<ion-input>], com seu rótulo ([label]) “flutuando” acima do texto ([labelPlacement="floating"]). [[value]="label()"] é um binding de propriedade: a propriedade [value] do componente recebe o valor da expressão e o recebe novamente a cada mudança. [(ionInput)] é o evento disparado a cada tecla digitada; [$event] é o objeto do evento, cuja propriedade [detail.value] contém o novo texto (uma string, [null] ou [undefined]: [?? ''] substitui os dois últimos por uma string vazia). O campo é, assim, **controlado**: exibe o estado atual e avisa o componente a cada alteração;
- linhas 22–23: o preço. [inputmode="decimal"] seleciona o teclado do telefone: o teclado numérico, com a vírgula. Se o campo estivesse vinculado ao preço (um número), digitar “3,2” resultaria em 3.2, que o vínculo [[value]] reescreveria no campo como “3.2.” Vinculado ao texto digitado, o campo mantém o que o usuário digitou;
- linhas 25–35: a quantidade, com dois botões, “–” e “+.” [fill="clear"]: um botão sem fundo; [slot="icon-only"]: o ícone é todo o seu conteúdo. [[disabled]] desativa o botão enquanto a expressão for verdadeira: a quantidade não pode ficar abaixo de 0;
- Linhas 38–42: a alíquota do IVA, três botões “segmentados”, dos quais apenas um fica selecionado, [<ion-segment>]. Seu valor é o do botão selecionado; [(ionChange)] é disparado quando outro é selecionado. [[value]="5.5"] define o valor do botão como o NÚMERO 5.5; [value="5.5"], sem colchetes, o definiria como a string “5.5”;
- linha 45: o botão Reset, com contorno ([fill="outline"]) e arredondado ([shape="round"]);
- linha 53: [{{ quantity() }} x {{ label() }}]: dois signals, lidos a partir do texto;
- Linhas 57–62: uma linha de lista para cada elemento do array calculado [lines()] ([@for]; veja o Exemplo 03). [<ion-note slot="end">] coloca o valor no fim da linha; [[class.bold]] define a classe CSS [bold] se a expressão for verdadeira;
- Linhas 71–73: uma linha de texto para cada entrada do histórico.
Alteramos a quantidade (pressionando “+” duas vezes), a alíquota (10%) e o preço (3.2); depois, o item:
A cada mudança do total com IVA, uma linha é adicionada ao histórico. Trocar o item redefine a quantidade para 1 (à direita). Enquanto isso, a aba do navegador exibe “Incl. VAT: €10.56” e depois “Incl. VAT: €3.52”; ao voltar ao menu, ela exibe novamente “Ionic Examples”.
Os signals do [Angular] derivam tanto do [Flutter] quanto do [React]. Como no [Flutter], o estado reside em um **objeto** (o componente), criado uma única vez e mantido: são os seus campos, e não há hooks nem regras de invocação. Mas, enquanto o [Flutter] recarrega todo o [build] quando [setState] é chamado, sem saber o que mudou, um signal sabe quem o lê: o [Angular] atualiza somente as partes do template que dependem do signal modificado. Portanto, não é preciso chamar [setState]: basta escrever em um signal ([set], [update]). [computed] é o equivalente dos getters do [Flutter] (e de [useMemo] no [React]), com a funcionalidade adicional de armazenar o valor; [effect] é o equivalente de [useEffect] do [React], sem a lista de dependências a manter atualizada, pois o efeito as descobre sozinho. O título da página é um caso em que o [Flutter] é mais simples: seu título é um widget, [Title], descrito por [build] como o resto da tela; o de uma página web pertence ao documento ([document.title]), fora do template do componente, daí o efeito.
3.3. Exemplo 03: escrevendo um template
O [Flutter] não tem linguagem de template: a tela é escrita em [Dart]. O [Angular] tem uma: HTML, enriquecido com uma sintaxe específica do [Angular] para bindings, condições e laços. Este exemplo exibe uma lista de médicos que pode ser filtrada:
| // =========================================================================
// src/app/ex03-templates/ex03.page.ts - escrevendo um template
// -------------------------------------------------------------------------
// O template de um componente Angular é HTML, enriquecido com uma sintaxe
// específica do Angular (veja ex03.page.html):
// - {{ expression }} : um valor inserido no texto;
// - [property]="expression" : uma propriedade de um elemento vinculada a uma
// expressão ([class.x], [style.x] para
// uma classe CSS ou um estilo);
// - @if / @else if / @else : um bloco que só EXISTE se a
// condição for verdadeira;
// - @for (x of list; track ...) : um bloco por elemento da lista;
// - @switch / @case : um bloco entre vários, dependendo de um valor;
// - @let name = expression : uma variável local do template.
// As expressões do template só enxergam os membros (públicos ou
// protegidos) da classe: os dados, os signals, os métodos.
// =========================================================================
import { Component, computed, signal } from '@angular/core';
import {
IonAvatar, IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonChip, IonContent, IonHeader, IonIcon,
IonItem, IonLabel, IonList, IonSearchbar, IonText, IonTitle, IonToggle, IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { happy, heart, medkit } from 'ionicons/icons';
// um "union type" de strings: os únicos valores possíveis de uma especialidade
type Specialty = 'generalist' | 'pediatrician' | 'cardiologist';
// o formato de um médico: uma interface (só existe para o compilador)
interface Doctor {
readonly id: number;
readonly title: string;
readonly firstName: string;
readonly lastName: string;
readonly specialty: Specialty;
readonly available: boolean;
}
const doctors: readonly Doctor[] = [
{ id: 1, title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER', specialty: 'generalist', 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 },
];
// "um valor entre vários, dependendo de um valor": um objeto do tipo
// Record<Specialty, string>. O compilador verifica que todas as
// especialidades têm seu rótulo (esquecer uma é um erro)
const labels: Record<Specialty, string> = {
generalist: 'general practitioner',
pediatrician: 'pediatrician',
cardiologist: 'cardiologist',
};
@Component({
selector: 'app-ex03',
imports: [
IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonSearchbar, IonItem, IonToggle,
IonButton, IonCard, IonCardContent, IonText, IonList, IonAvatar, IonLabel, IonIcon, IonChip,
],
templateUrl: './ex03.page.html',
styles: `
.logo { width: 32px; height: 32px; margin-inline-start: 8px; }
.help { background: #e1f5fe; box-shadow: none; }
.unavailable { opacity: 0.5; }
.rank {
display: flex; align-items: center; justify-content: center;
height: 100%; border-radius: 50%; background: #e8eaf6;
}
.specialty { display: flex; align-items: center; gap: 6px; }
`,
})
export class Ex03Page {
// os dados, lidos pelo template
readonly doctors = doctors;
// o estado da tela
readonly filter = signal(''); // o texto pesquisado
readonly onlyAvailable = signal(false);
readonly showHelp = signal(true);
// a lista exibida: um valor CALCULADO, recalculado quando o filtro ou
// o toggle mudam. filter mantém os elementos que satisfazem uma condição
readonly displayed = computed(() => {
const text = this.filter().trim().toLowerCase();
return doctors.filter(
(m) =>
(!this.onlyAvailable() || m.available) &&
`${m.firstName} ${m.lastName} ${labels[m.specialty]}`.toLowerCase().includes(text),
);
});
constructor() {
addIcons({ happy, heart, medkit });
}
// um método chamado pelo template
label(s: Specialty): string {
return labels[s];
}
}
|
- linha 28: um tipo “união” de strings: os únicos três valores possíveis para uma especialidade. É o equivalente da enumeração em [Dart]: [let s: Specialty = 'dentist'] resulta em um erro de compilação;
- linhas 31–38: uma interface descreve a estrutura de um médico. Seus campos são [readonly]: um médico nunca muda. A interface existe apenas para o compilador, que verifica se cada médico tem todos os seus campos, com o tipo correto; ela desaparece do código compilado;
- linhas 40–44: os médicos, objetos literais. [readonly Doctor[]]: um array que não pode ser modificado (sem adições nem remoções);
- linhas 49–53: “um valor entre vários, dependendo de um valor”: um objeto cujas chaves são as especialidades. [Record<Specialty, string>] é o tipo de um objeto que tem uma propriedade do tipo [string] para CADA especialidade: omitir uma ou acrescentar uma sem completar este objeto resultaria em um erro de compilação, como com [switch] no [Dart];
- Linhas 62–71: os estilos do componente: [logo] (o tamanho da imagem na barra superior), [help] (o fundo azul-claro do cartão de ajuda), [unavailable] (um médico semitransparente), [rank] (um círculo em volta da linha);
- linha 75: os médicos, fornecidos ao template. O template só enxerga os membros da classe, não as constantes do arquivo;
- linhas 78–80: o estado da tela;
- linhas 84–91: a lista exibida: um valor calculado que é recalculado quando o filtro ou o interruptor muda. [filter] mantém os elementos do array que satisfazem uma condição; [includes] determina se uma string contém outra;
- linhas 98–100: um método que o template chamará: o rótulo de uma especialidade.
O template:
| <!-- ======================================================================
ex03.page.html - a lista de médicos, filtrada
====================================================================== -->
<ion-header>
<ion-toolbar color="primary">
<ion-buttons slot="start">
<ion-back-button defaultHref="/" />
<!-- uma imagem SVG distribuída com a aplicação (pasta public/ do projeto) -->
<img class="logo" src="ex03/doctor.svg" alt="" />
</ion-buttons>
<ion-title>Example 03 - templates</ion-title>
</ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
<!-- ion-searchbar: um campo de busca, com sua lupa -->
<ion-searchbar placeholder="search..." [value]="filter()" (ionInput)="filter.set($event.detail.value ?? '')" />
<!-- um toggle, com seu rótulo -->
<ion-item lines="none">
<ion-toggle [checked]="onlyAvailable()" (ionChange)="onlyAvailable.set($event.detail.checked)">
available only
</ion-toggle>
</ion-item>
<ion-button fill="clear" size="small" (click)="showHelp.set(!showHelp())">
{{ showHelp() ? "Hide help" : "Show help" }}
</ion-button>
<!-- @if: este cartão só EXISTE se showHelp() for true -->
@if (showHelp()) {
<ion-card class="help">
<ion-card-content>Type a name or a specialty. Unavailable doctors are greyed out.</ion-card-content>
</ion-card>
}
<!-- um bloco entre três: @if / @else if / @else -->
@if (doctors.length === 0) {
<p>No doctor.</p>
} @else if (displayed().length === 0) {
<p><ion-text color="danger">No doctor matches "{{ filter() }}".</ion-text></p>
} @else {
<ion-list>
<!-- um item por médico; track: a IDENTIDADE de cada item (veja o exemplo 04);
$index: a posição do item (0, 1, 2...) -->
@for (m of displayed(); track m.id; let i = $index) {
<!-- [class.unavailable]: a classe CSS é aplicada se a expressão for verdadeira -->
<ion-item [class.unavailable]="!m.available">
<ion-avatar slot="start">
<div class="rank">{{ i + 1 }}</div>
</ion-avatar>
<ion-label>
<h2>{{ m.title }} {{ m.firstName }} {{ m.lastName }}</h2>
<p class="specialty">
<!-- @switch: um ícone entre vários, dependendo da especialidade -->
@switch (m.specialty) {
@case ('pediatrician') { <ion-icon name="happy" style="color: orange" /> }
@case ('cardiologist') { <ion-icon name="heart" style="color: red" /> }
@default { <ion-icon name="medkit" style="color: teal" /> }
}
{{ label(m.specialty) }}
</p>
</ion-label>
<!-- [color]: uma propriedade calculada por uma expressão condicional -->
<ion-chip slot="end" [color]="m.available ? 'success' : 'medium'">
{{ m.available ? 'available' : 'unavailable' }}
</ion-chip>
</ion-item>
}
</ion-list>
}
<!-- @let: uma variável de template; [style.font-size.px]: um estilo CALCULADO,
o tamanho do texto depende do número de médicos exibidos -->
@let count = displayed().length;
<p [style.font-size.px]="12 + count * 2">{{ count }} doctor(s) displayed - the size of this text depends on it.</p>
</ion-content>
|
- linha 10: uma imagem SVG, incluída na aplicação: o arquivo [public/ex03/doctor.svg] do projeto, copiado como está para a aplicação compilada (veja o arquivo [angular.json]). O navegador sabe exibir SVG; basta uma simples tag [<img>];
- linha 18: [<ion-searchbar>], um campo de busca, com sua lupa, seu texto de sugestão ([placeholder]) e uma cruz para limpá-lo. [filter.set(...)]: uma instrução de um template pode escrever em um signal;
- Linhas 21–25: um interruptor, [<ion-toggle>], e seu rótulo (o conteúdo da tag). [(ionChange)] é emitido quando ele é alternado; [$event.detail.checked] é seu novo valor, [true] ou [false];
- linhas 27–29: um botão sem fundo, cujo texto depende do seu estado: uma expressão condicional [? :] em uma interpolação;
- linhas 32–36: [@if (condition) { ... }]: o cartão de ajuda **existe** somente se [showHelp()] for verdadeiro. Não há cartão “oculto”: quando a condição é falsa, o cartão é removido da página e recriado quando a condição volta a ser verdadeira;
- linhas 39–72: um entre três blocos, com [@if], [@else if], e [@else];
- linha 42: [<ion-text color="danger">]: texto colorido, neste caso vermelho;
- linha 47: [@for (m of displayed(); track m.id; let i = $index)] repete seu bloco para cada médico exibido. [track] fornece o identificador de cada elemento (seu [id]): quando a lista muda, o [Angular] usa esse identificador para determinar quais elementos pode manter, mover ou excluir (veja o Exemplo 04). [$index] é a posição do elemento (0, 1, 2…), que [let i = $index] renomeia para [i];
- linha 49: [[class.unavailable]="!m.available"]: a classe CSS [unavailable] é aplicada ao elemento se a expressão for verdadeira e removida caso contrário: os médicos indisponíveis aparecem em cinza;
- linhas 49–69: [<ion-item>] é a entrada de lista do [Ionic]. Seus locais ([slot]) determinam o posicionamento do conteúdo: [slot="start"] no início (aqui, um disco com a posição, dentro de um [<ion-avatar>]), [slot="end"] no fim (um chip, [<ion-chip>]). Entre os dois, [<ion-label>] contém o título ([<h2>]) e um subtítulo ([<p>]), que o [Ionic] formata;
- linhas 57–61: [@switch (value)] seleciona um bloco entre vários com base em um valor: o primeiro bloco, [@case], se for igual ao valor; caso contrário, o bloco [@default]. Aqui, o ícone da especialidade;
- linha 62: uma chamada a um método da classe;
- linha 66: [[color]]: uma propriedade cujo valor é calculado por uma expressão condicional;
- linha 76: [@let count = displayed().length;] declara uma variável de template que pode ser usada mais adiante no template; isso evita escrever a mesma expressão duas vezes;
- linha 77: [[style.font-size.px]]: um estilo calculado. O tamanho do texto, em pixels, depende do número de médicos exibidos.
Para resumir o que se escreve no template do [Angular] e seu equivalente em [Dart]:
Angular (template) | Flutter (Dart) | Função |
{{ expression }} | Text('$x') | um valor inserido no texto |
[property]="expression" | parameter: expression | uma propriedade vinculada a uma expressão |
[class.x]="c", [style.x]="v" | style: c ? ... : ... | uma classe CSS, um estilo, calculados |
@if (c) { ... } | if (c) widget | um bloco que existe somente se a condição for verdadeira |
@if (c) { A } @else { B } | if (c) A else B | um ou outro |
c? a : b | c? a : b | um dos dois, em uma expressão |
@for (x of list; track x.id) { ... } | for (final x in list) widget | um bloco para cada elemento da lista |
@switch (v) { @case (a) { ... } } | switch (v) { a => widget } | um bloco entre vários, dependendo de um valor |
@let n = expression; | final n = ...; (before the return) | uma variável local |
Na inicialização; depois de digitar “gen” e ocultar a ajuda; depois com “xyz”:
O template do [Angular] é mais próximo do HTML do que o JSX é do [React] (em que condições e laços são escritos em JavaScript, com [&&], [? :] e [map]) e da árvore de widgets do [Flutter] (escrita em [Dart]). O preço a pagar é ter de aprender mais uma sintaxe; o benefício é um template legível por qualquer pessoa familiarizada com HTML e verificado pelo compilador ([strictTemplates]): um nome de propriedade escrito errado ou uma expressão de tipo incorreto é sinalizado durante a compilação.
3.4. Exemplo 04: eventos
Em um template, [(event)="statement"] executa a instrução quando o elemento dispara o evento. Este exemplo gerencia uma lista de tarefas:
| // =========================================================================
// src/app/ex04-events/ex04.page.ts - reagindo às ações do usuário
// -------------------------------------------------------------------------
// No template, (event)="statement" executa a instrução quando
// o elemento emite o evento:
// - (click)="add()" : um toque em um botão;
// - (click)="remove(t, 'x')" : passamos nossos próprios argumentos;
// - (ionChange)="f($event)" : $event é o objeto do evento, aqui um
// CustomEvent cujo detail carrega os dados
// (a caixa marcada, o texto...);
// - (keyup.enter), (keyup.escape) : uma tecla específica do teclado;
// - (dblclick), (contextmenu) : os eventos do navegador, em
// QUALQUER elemento;
// - ion-item-sliding : deslizar uma linha para removê-la,
// o gesto típico de um celular.
// Para agir em um campo de entrada pelo código (dar-lhe o foco), nós o
// designamos com uma variável de template (#field) e o obtemos na
// classe com viewChild().
// =========================================================================
import { Component, signal, viewChild } from '@angular/core';
import {
CheckboxCustomEvent, IonBackButton, IonButton, IonButtons, IonCheckbox, IonContent, IonHeader, IonIcon, IonInput,
IonItem, IonItemOption, IonItemOptions, IonItemSliding, IonList, IonTitle, IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { trash, trashOutline } from 'ionicons/icons';
interface Task {
readonly id: number;
readonly label: string;
readonly done: boolean;
}
// "3:30 PM": a hora atual, no estilo inglês
function time(): string {
return new Date().toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' });
}
@Component({
selector: 'app-ex04',
imports: [
IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonInput, IonButton, IonList,
IonItemSliding, IonItem, IonCheckbox, IonIcon, IonItemOptions, IonItemOption,
],
templateUrl: './ex04.page.html',
styles: `
.input { display: flex; align-items: center; gap: 8px; }
.input ion-input { flex: 1; }
.done { text-decoration: line-through; color: gray; }
.area {
height: 80px; display: flex; align-items: center; justify-content: center;
margin-top: 12px; border-radius: 8px; background: #e7f5ff; user-select: none;
}
.log { font-size: 12px; }
`,
})
export class Ex04Page {
readonly tasks = signal<Task[]>([
{ id: 1, label: 'Install Ionic', done: true },
{ id: 2, label: 'Read the chapter on events', done: false },
]);
readonly log = signal<string[]>([]);
// o texto do campo de entrada
readonly input = signal('');
// o componente <ion-input #field> do template (para dar-lhe o foco)
private readonly field = viewChild.required<IonInput>('field');
// um campo da classe que NÃO é exibido: um campo simples, não um signal
private nextId = 3;
constructor() {
addIcons({ trash, trashOutline });
}
private trace(message: string): void {
this.log.update((j) => [`${time()} ${message}`, ...j]);
}
// chamado pelo botão E pela tecla Enter do teclado (keyup.enter)
add(): void {
const label = this.input().trim();
if (!label) {
return;
}
// um NOVO array: o antigo, mais a nova tarefa
this.tasks.update((ts) => [...ts, { id: this.nextId++, label, done: false }]);
this.trace(`added "${label}"`);
this.input.set('');
// o foco volta ao campo: podemos digitar a próxima tarefa
this.field().setFocus();
}
// $event é um CheckboxCustomEvent: detail.checked indica se a caixa está marcada
toggle(task: Task, event: CheckboxCustomEvent): void {
const done = event.detail.checked;
// substituímos a tarefa por uma CÓPIA modificada: { ...task, done }
this.tasks.update((ts) => ts.map((t) => (t.id === task.id ? { ...t, done } : t)));
this.trace(`"${task.label}": ${done ? 'done' : 'to do'}`);
}
remove(task: Task, how: string): void {
this.tasks.update((ts) => ts.filter((t) => t.id !== task.id));
this.trace(`removed "${task.label}" (${how})`);
}
// um toque na área: MouseEvent fornece a posição do dedo na
// página; a tornamos relativa à área tocada (currentTarget)
position(event: MouseEvent): void {
const area = (event.currentTarget as HTMLElement).getBoundingClientRect();
const x = Math.round(event.clientX - area.left);
const y = Math.round(event.clientY - area.top);
this.trace(`tap at (${x}, ${y})`);
}
// um toque longo normalmente abre o menu de contexto do navegador:
// preventDefault() o impede
longPress(event: Event): void {
event.preventDefault();
this.trace('long press');
}
// o evento de toque duplo
doubleTap(): void {
this.trace('double tap');
}
}
|
- linhas 29–33: uma tarefa. Seus campos são somente leitura: para marcar uma tarefa como concluída, substitua-a por uma cópia modificada;
- linhas 36–38: a hora atual, “3:30 PM”, formatada por [toLocaleTimeString] de acordo com as convenções do inglês (EUA);
- linhas 59–63: o estado: a lista de tarefas e um registro de eventos;
- linha 65: o texto do campo de entrada;
- linha 67: para interagir com o campo de entrada a partir do código (dar-lhe o foco), precisamos do próprio componente. O template se refere a ele por meio de uma variável de template, [#field]; [viewChild.required<IonInput>('field')] a recupera. Isso é um signal: [this.field()] é o componente [IonInput]. [required]: ele sempre existe (não está dentro de um [@if]);
- linha 69: um campo da classe que não é exibido — um campo comum, não um signal. Modificá-lo não atualiza nada na tela. É o que o [React] chama de “referência” ([useRef]);
- linhas 75–77: uma linha adicional no topo do registro;
- linhas 80–91: adição de uma tarefa, disparada pelo botão E pela tecla Enter do teclado. A tarefa é adicionada ao final de um novo array ([[...ts, { id: this.nextId++, label, done: false }]]), o campo é limpo e o foco volta a ele por meio do seu método [setFocus()]: assim, é possível digitar a próxima tarefa;
- Linhas 94–99: marcar ou desmarcar uma tarefa. O evento recebido é um [CheckboxCustomEvent]: [detail.checked] indica se a caixa de seleção está marcada. A tarefa é substituída por uma cópia modificada ([{ ...t, done }]: todos os campos de [t], mais [done] com seu novo valor) em um novo array ([map]). Diferentemente do [Flutter], em que [setState] avisa que “algo mudou”, um signal só detecta uma mudança se seu valor for um objeto NOVO: modificar a tarefa no próprio lugar ([task.done = true]) não seria detectado;
- linhas 101–104: exclusão, pelo botão ou deslizando a linha: [filter] mantém todas as tarefas, exceto aquela;
- linhas 108–113: um toque na área inferior. O evento é um [MouseEvent] (um toque com o dedo produz os mesmos eventos que um clique do mouse): [clientX] e [clientY] representam a posição do dedo na janela; essa posição é relativa à área tocada, o elemento que escuta o evento ([currentTarget]), cuja posição é dada por [getBoundingClientRect()];
- Linhas 117–120: um toque longo normalmente abre o menu de contexto do navegador (o evento [contextmenu]); [preventDefault()] impede que isso aconteça.
O template:
| <!-- ======================================================================
ex04.page.html - uma lista de tarefas e seus eventos
====================================================================== -->
<ion-header>
<ion-toolbar color="primary">
<ion-buttons slot="start">
<ion-back-button defaultHref="/" />
</ion-buttons>
<ion-title>Example 04 - events</ion-title>
</ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
<div class="input">
<!-- #field: uma variável de template, que designa este componente (veja viewChild);
(keyup.enter): a tecla Enter; (keyup.escape): a tecla Escape;
enterkeyhint="done": a tecla Enter do teclado do celular -->
<ion-input #field placeholder="new task (Escape to clear)" enterkeyhint="done"
[value]="input()" (ionInput)="input.set($event.detail.value ?? '')"
(keyup.enter)="add()" (keyup.escape)="input.set('')" />
<ion-button shape="round" (click)="add()">Add</ion-button>
</div>
<ion-list>
<!-- track t.id: a IDENTIDADE de cada linha (veja a explicação no curso) -->
@for (t of tasks(); track t.id) {
<!-- ion-item-sliding: uma linha que é deslizada com o dedo -->
<ion-item-sliding>
<ion-item>
<!-- a caixa fica à ESQUERDA (justify="start"), seu rótulo à direita -->
<ion-checkbox justify="start" labelPlacement="end" [checked]="t.done" (ionChange)="toggle(t, $event)">
<span [class.done]="t.done">{{ t.label }}</span>
</ion-checkbox>
<!-- um botão de "lixeira": a tarefa DESTA linha como argumento -->
<ion-button slot="end" fill="clear" color="danger" (click)="remove(t, 'button')">
<ion-icon slot="icon-only" name="trash-outline" />
</ion-button>
</ion-item>
<!-- o que aparece sob a linha quando ela é deslizada para a esquerda (side="end");
(ionSwipe): a linha foi deslizada até o fim (opção "expandable") -->
<ion-item-options side="end" (ionSwipe)="remove(t, 'swipe')">
<ion-item-option color="danger" expandable (click)="remove(t, 'swipe')">
<ion-icon slot="icon-only" name="trash" />
</ion-item-option>
</ion-item-options>
</ion-item-sliding>
}
</ion-list>
<!-- uma simples caixa <div>, sensível a três eventos do navegador -->
<div class="area" (click)="position($event)" (dblclick)="doubleTap()" (contextmenu)="longPress($event)">
Touch this area (tap, double tap, long press)
</div>
<h3>Log</h3>
@for (line of log(); track $index) {
<div class="log">{{ line }}</div>
}
</ion-content>
|
- linhas 19–21: o campo de entrada, chamado [#field]. Seu texto está vinculado ao signal [input]. [(keyup.enter)] é disparado somente pela tecla Enter, e [(keyup.escape)] pela tecla Esc (em um teclado físico: computador, emulador, tablet): um “pseudoevento” do [Angular], que filtra as teclas do teclado para nós. [enterkeyhint="done"] determina a aparência da tecla Enter no teclado do telefone;
- linha 22: o botão chama o mesmo método;
- linha 27: [track t.id]: o identificador de cada linha. Quando uma lista muda, o [Angular] compara a lista antiga com a nova para determinar quais itens manter: com [track $index], ele os associaria por posição (o primeiro ao primeiro, o segundo ao segundo, e assim por diante). Se a primeira tarefa desaparecesse, a linha da segunda tarefa ocuparia seu lugar… junto com o estado da linha da primeira (sua posição de rolagem, por exemplo). Com [track t.id], cada linha tem uma identidade estável: a de sua tarefa. É o papel das chaves (keys) no [Flutter];
- linhas 29–47: uma linha que se arrasta com o dedo, [<ion-item-sliding>] — o gesto típico para percorrer uma lista em um telefone. Ela contém a própria linha ([<ion-item>]) e o que aparece por baixo dela quando se desliza ([<ion-item-options>]);
- Linha 32: uma caixa de seleção, [<ion-checkbox>], à esquerda ([justify="start"]), seguida do seu rótulo ([labelPlacement="end"]). [(ionChange)="toggle(t, $event)"] passa ao método a tarefa desta linha e o objeto do evento;
- linha 33: o rótulo aparece riscado e em cinza se a tarefa estiver concluída (a [done] classe);
- linhas 36–38: um botão de “lixeira” no fim da linha: [(click)="remove(t, 'button')"] passa seus próprios argumentos ao método;
- Linhas 42–46: as opções que aparecem à direita ([side="end"]) quando se arrasta a linha para a esquerda: um botão vermelho com um ícone de lixeira. [expandable]: se você arrastar a linha até o fim, a opção se estende por toda a linha, e [<ion-item-options>] dispara o evento [(ionSwipe)];
- Linha 52: uma caixa simples, um [<div>], que responde a três eventos do navegador: [(click)] (um toque), [(dblclick)] (um toque duplo) e [(contextmenu)] (um toque longo em uma tela sensível ao toque). Qualquer elemento pode escutar qualquer evento do navegador.
Adicionamos uma tarefa (pressionando Enter), marcamos a segunda e tocamos na área inferior; depois arrastamos a primeira tarefa para a esquerda (até o meio durante o arrasto; à direita depois de arrastada até o fim):
No [Flutter], cada widget interativo declara seus eventos por meio de parâmetros tipados ([onPressed], [onChanged], [onSubmitted]...), e [GestureDetector] adiciona gestos aos que não os têm. No [Angular], encontramos o modelo do navegador: todo elemento emite os eventos do DOM ([click], [keyup], [dblclick]...), e os componentes do [Ionic] acrescentam os seus, com o prefixo [ion] ([ionInput], [ionChange], [ionSwipe]....). Graças a [strictTemplates], [$event] tem o tipo exato do evento ([CheckboxCustomEvent], [MouseEvent]...), e o editor sugere as propriedades de seu [detail] enquanto você digita. Para gestos mais complexos (arrastar, pinçar), o [Ionic] oferece [GestureController].
3.5. Exemplo 05: todos os tipos de campo
Este exemplo usa o formulário do Exemplo 05 do curso de [Flutter], com os campos de entrada do [Ionic]: caixas de texto, botões de opção, caixas de seleção, listas com marcadores, listas suspensas, controles deslizantes e calendários.
| // =========================================================================
// src/app/ex05-controlled-fields/ex05.page.ts - todos os tipos de campo
// -------------------------------------------------------------------------
// Um campo CONTROLADO exibe um valor do estado e notifica o componente
// de cada mudança, que atualiza o estado: o estado é a única fonte
// de verdade. Modificar o estado (pelo código) modifica o campo.
// Duas formas de escrever um campo vinculado a um signal:
// - [value]="name()" (ionChange)="name.set($event.detail.value)": à mão;
// - [(ngModel)]="name": o "two-way binding" do FormsModule, que
// aceita diretamente um signal gravável (WritableSignal) e faz
// as duas coisas de uma vez: lê o signal e o grava a cada mudança.
// O que o evento de um campo carrega ($event.detail) depende do campo:
// - ion-input, ion-textarea -> value: o texto (string | null);
// - ion-checkbox, ion-toggle -> checked: boolean;
// - ion-radio-group, ion-select -> value: o valor da opção escolhida;
// - ion-select multiple -> value: o ARRAY dos valores escolhidos;
// - ion-range -> value: um número;
// - ion-datetime -> value: a data, uma string ISO 8601.
// Mesma forma do exemplo 05 do curso de Flutter; tudo acontece no
// celular, sem servidor.
// =========================================================================
import { JsonPipe } from '@angular/common';
import { Component, computed, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
IonBackButton, IonButton, IonButtons, IonCheckbox, IonChip, IonCol, IonContent, IonDatetime, IonGrid, IonHeader,
IonIcon, IonInput, IonItem, IonLabel, IonModal, IonRadio, IonRadioGroup, IonRange, IonRow, IonSelect,
IonSelectOption, IonTextarea, IonTitle, IonToolbar, RangeChangeEventDetail,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { checkmark, gift } from 'ionicons/icons';
const titles = ['Mr', 'Mme', 'Melle'];
const hobbies = ['sport', 'music', 'reading', 'cinema'];
// listas de pares (código, nome): o código é o valor, o nome é exibido
const countries = [
{ code: 'fr', name: 'France' },
{ code: 'be', name: 'Belgium' },
{ code: 'ch', name: 'Switzerland' },
];
const languages = [
{ code: 'fr', name: 'French' },
{ code: 'en', name: 'English' },
{ code: 'es', name: 'Spanish' },
];
@Component({
selector: 'app-ex05',
imports: [
FormsModule, JsonPipe, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonLabel,
IonRadioGroup, IonRadio, IonGrid, IonRow, IonCol, IonInput, IonTextarea, IonItem, IonCheckbox, IonChip, IonIcon,
IonSelect, IonSelectOption, IonRange, IonButton, IonModal, IonDatetime,
],
templateUrl: './ex05.page.html',
styles: `
h3 { font-size: 0.95em; font-weight: bold; margin: 16px 0 4px; }
.titles { display: flex; gap: 24px; padding: 8px 0; }
pre { background: #f5f5f5; padding: 8px; font-size: 12px; white-space: pre-wrap; word-break: break-all; }
pre.sent { background: #e8f5e9; }
/* o diálogo do calendário: o tamanho do seu conteúdo, em vez da tela inteira */
ion-modal.calendar { --width: fit-content; --height: fit-content; --border-radius: 8px; }
`,
})
export class Ex05Page {
// as listas de opções, lidas pelo template
readonly titles = titles;
readonly hobbies = hobbies;
readonly countries = countries;
readonly languages = languages;
// a data mais recente que pode ser escolhida: hoje ("2026-10-06"), NO FUSO HORÁRIO DO DISPOSITIVO
readonly today = new Date(Date.now() - new Date().getTimezoneOffset() * 60_000).toISOString().slice(0, 10);
// um signal por campo do formulário
readonly title = signal('Mme');
readonly name = signal('');
readonly age = signal<number | null>(30);
readonly presentation = signal('');
readonly newsletter = signal(false);
readonly chosenHobbies = signal<ReadonlySet<string>>(new Set(['reading'])); // um SET: sem duplicatas
readonly chosenCountry = signal('fr');
readonly chosenLanguages = signal<string[]>([]);
readonly birthDate = signal<string | null>(null); // null: ainda não escolhido
readonly satisfaction = signal(3);
readonly sent = signal<string | null>(null);
// o texto da apresentação ENQUANTO digitamos: um campo simples, que
// não é um signal. Modificá-lo não atualiza nada
private presentationDraft = '';
// todos os valores, reunidos em um objeto (o que enviaríamos a um servidor)
readonly model = computed(() => ({
title: this.title(),
name: this.name().trim(),
age: this.age(),
presentation: this.presentation(),
newsletter: this.newsletter(),
hobbies: [...this.chosenHobbies()],
country: this.chosenCountry(),
languages: this.chosenLanguages(),
birthDate: this.birthDate(),
satisfaction: this.satisfaction(),
}));
constructor() {
addIcons({ checkmark, gift });
}
// a apresentação: anotamos o texto a cada tecla digitada, SEM tocar
// no estado; ele só é copiado para o estado ao sair do campo (ionBlur)
notePresentation(text: string | null | undefined): void {
this.presentationDraft = text ?? '';
}
commitPresentation(): void {
this.presentation.set(this.presentationDraft);
}
// um chip escolhido ou não: construímos um NOVO set, com ou sem o valor
toggleHobby(hobby: string): void {
this.chosenHobbies.update((old) => {
const newSet = new Set(old);
if (newSet.has(hobby)) {
newSet.delete(hobby);
} else {
newSet.add(hobby);
}
return newSet;
});
}
// o valor de um ion-range é um número, ou um intervalo { lower, upper }
// para um controle deslizante de dois botões (dualKnobs): aqui, é um número
changeSatisfaction(value: RangeChangeEventDetail['value']): void {
this.satisfaction.set(value as number);
}
// ion-datetime fornece uma data ISO 8601 ("2000-01-15T00:00:00"): mantemos apenas o dia,
// no formato de data da API do RdvMedecins
chooseBirthDate(value: string | string[] | null | undefined): void {
if (typeof value === 'string') {
this.birthDate.set(value.substring(0, 10));
}
}
// o estado modificado PELO CÓDIGO: os campos acompanham
example(): void {
this.title.set('Mr');
this.name.set('MARTIN');
this.age.set(42);
this.chosenHobbies.set(new Set(['sport', 'cinema']));
this.chosenCountry.set('be');
}
send(): void {
// JSON.stringify(object): o JSON em uma linha
this.sent.set(JSON.stringify(this.model()));
}
}
|
Um campo **controlado** exibe um valor do estado e notifica o componente sobre qualquer alteração, que atualiza o estado: o estado é a única fonte de verdade. Até agora, isso era escrito manualmente: [[value]="name()"] para exibir o valor, [(ionInput)="name.set($event.detail.value ?? '')"] para atualizá-lo. O módulo [FormsModule] do [Angular] faz as duas coisas de uma vez: [[(ngModel)]="name"], a conexão “bidirecional” (a “caixa de banana” [[( )]], uma combinação de [[ ]] e [( )]), que aceita diretamente um signal modificável.
- linha 25: o módulo [FormsModule], que fornece [ngModel] (linha 51: ele é importado no componente);
- linhas 34–46: as listas suspensas. Países e idiomas são arrays de pares (código, nome): o código é o valor do campo e o nome é o que se exibe;
- linha 72: a data mais recente que pode ser selecionada no calendário: hoje, no formato “2026-10-06.” [toISOString()] devolve a data em Tempo Universal Coordenado (UTC): entre meia-noite e 2 h em Paris, ainda seria o dia anterior. Portanto, primeiro deslocamos a hora atual pela diferença entre a hora local e o Tempo Universal Coordenado ([getTimezoneOffset()], em minutos); o Exemplo 24 tratará dessa armadilha;
- linhas 75–85: um signal por campo. [signal<number | null>(30)]: um número, ou [null] se o campo de idade estiver vazio; [ReadonlySet<string>]: um conjunto (sem duplicatas) de hobbies; [signal<string | null>(null)]: uma data, ou [null] até que uma seja selecionada;
- linha 89: o texto da apresentação ENQUANTO se digita, um campo comum: voltaremos a isso;
- linhas 92–103: todos os valores, reunidos em um único objeto (o que seria enviado a um servidor): um valor calculado, sempre atualizado. [[...this.chosenHobbies()]] cria um array com os elementos do conjunto;
- linhas 111–117: a apresentação: cada tecla digitada coloca o texto no campo comum; isso NÃO afeta o estado: nada é atualizado. O texto só é copiado para o signal [presentation] ao sair do campo;
- linhas 120–130: um hobby opcional em forma de chip: um conjunto NOVO é criado, uma cópia do anterior ([new Set(old)]), com ou sem o hobby;
- Linhas 134–136: o valor de um [<ion-range>] é um número, ou um intervalo [{ lower, upper }] para um controle deslizante de duas alças: aqui, é um número, o que se informa ao compilador por meio de [as number];
- linhas 140–144: o calendário fornece uma data no formato ISO 8601 (“2000-01-15T00:00:00,” ou um array de datas se várias forem selecionadas): somente o dia é mantido, no formato de data da API [RdvMedecins];
- linhas 147–153: o registro modificado pelo código; os campos vêm em seguida;
- linha 157: [JSON.stringify] gera o JSON de um objeto, em uma única linha.
Os campos no template:
| <!-- ======================================================================
ex05.page.html - um formulário, com todos os tipos de campo
====================================================================== -->
<ion-header>
<ion-toolbar color="primary">
<ion-buttons slot="start">
<ion-back-button defaultHref="/" />
</ion-buttons>
<ion-title>Example 05 - controlled fields</ion-title>
</ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
<h3>Title</h3>
<!-- radio buttons: o grupo carrega o valor escolhido ([value]) e notifica
quando outro é escolhido (ionChange) -->
<ion-radio-group [value]="title()" (ionChange)="title.set($event.detail.value)">
<div class="titles">
@for (t of titles; track t) {
<ion-radio [value]="t" labelPlacement="end">{{ t }}</ion-radio>
}
</div>
</ion-radio-group>
<!-- dois campos lado a lado: uma grade de 12 colunas, 8 para o nome, 4 para a idade -->
<ion-grid class="ion-no-padding">
<ion-row>
<ion-col size="8">
<!-- [(ngModel)]="name": o campo lê E grava o signal name -->
<ion-input label="Name" labelPlacement="floating" [(ngModel)]="name" />
</ion-col>
<ion-col size="4">
<!-- type="number": o teclado numérico; ngModel recebe um número (ou null) -->
<ion-input label="Age" labelPlacement="floating" type="number" [(ngModel)]="age" />
</ion-col>
</ion-row>
</ion-grid>
<!-- um campo NÃO vinculado ao estado a cada tecla digitada: seu texto só é copiado
para o estado ao sair do campo (ionBlur) -->
<ion-textarea label="Presentation (updated when leaving the field)" labelPlacement="floating" [rows]="2"
(ionInput)="notePresentation($event.detail.value)" (ionBlur)="commitPresentation()" />
<!-- uma única caixa: true / false -->
<ion-checkbox justify="start" labelPlacement="end" class="ion-margin-vertical" [(ngModel)]="newsletter">
Receive the newsletter
</ion-checkbox>
<h3>Hobbies</h3>
<!-- vários chips para UM set: um toque adiciona ou remove o valor -->
@for (l of hobbies; track l) {
@let chosen = chosenHobbies().has(l);
<ion-chip [outline]="!chosen" [color]="chosen ? 'primary' : 'medium'" (click)="toggleHobby(l)">
@if (chosen) {
<ion-icon name="checkmark" />
}
<ion-label>{{ l }}</ion-label>
</ion-chip>
}
<!-- uma lista suspensa; interface="popover": uma pequena lista, sob o campo -->
<ion-select label="Country" interface="popover" [(ngModel)]="chosenCountry">
@for (p of countries; track p.code) {
<ion-select-option [value]="p.code">{{ p.name }}</ion-select-option>
}
</ion-select>
<!-- uma lista de escolha MÚLTIPLA: o valor é um array -->
<ion-select label="Spoken languages" placeholder="none" [multiple]="true" cancelText="Cancel"
[(ngModel)]="chosenLanguages">
@for (l of languages; track l.code) {
<ion-select-option [value]="l.code">{{ l.name }}</ion-select-option>
}
</ion-select>
<!-- um controle deslizante: 5 passos, de 1 a 5; (ionInput): durante o movimento -->
<ion-range [label]="'Satisfaction: ' + satisfaction() + ' / 5'" [min]="1" [max]="5" [step]="1" [snaps]="true"
[ticks]="true" [value]="satisfaction()" (ionInput)="changeSatisfaction($event.detail.value)" />
<!-- a data de nascimento: o botão abre um diálogo (ion-modal) que contém um calendário -->
<ion-item lines="none" class="ion-no-padding">
<ion-icon slot="start" name="gift" />
<ion-label>
Birth date
<p>{{ birthDate() ?? 'not chosen' }}</p>
</ion-label>
<ion-button id="choose-birth-date" slot="end" fill="outline" shape="round">Choose</ion-button>
</ion-item>
<!-- trigger: o id do botão que abre o diálogo -->
<ion-modal trigger="choose-birth-date" class="calendar">
<ng-template>
<!-- showDefaultButtons: os botões Cancelar e OK; ionChange só é emitido quando OK é pressionado -->
<ion-datetime presentation="date" locale="en-US" [firstDayOfWeek]="1" [showDefaultButtons]="true"
cancelText="Cancel" doneText="OK" [max]="today" [value]="birthDate() ?? '2000-01-01'"
(ionChange)="chooseBirthDate($event.detail.value)">
<span slot="title">Select a date</span>
</ion-datetime>
</ng-template>
</ion-modal>
<div class="ion-margin-vertical">
<ion-button shape="round" (click)="send()">Send</ion-button>
<ion-button shape="round" fill="outline" (click)="example()">Fill by code</ion-button>
</div>
<h3>The model, live</h3>
<!-- o pipe json: o objeto, como JSON indentado -->
<pre>{{ model() | json }}</pre>
<!-- um bloco que só existe após um envio -->
@if (sent(); as submission) {
<h3>Last submission</h3>
<pre class="sent">{{ submission }}</pre>
}
</ion-content>
|
- linhas 18–24: botões de opção. O grupo, [<ion-radio-group>], guarda o valor selecionado ([[value]]) e dispara uma notificação quando outro é selecionado ([(ionChange)]); ele contém os botões [<ion-radio>], cada um com seu próprio valor;
- linhas 27–38: dois campos lado a lado em uma grade: [<ion-grid>] contém linhas ([<ion-row>]), divididas em doze colunas; [<ion-col size="8">] ocupa oito: o nome ocupa o dobro de espaço da idade;
- linha 31: [[(ngModel)]="name"]: o campo exibe o signal [name] e o escreve a cada tecla digitada;
- linha 35: um campo numérico ([type="number"]): o teclado do telefone é numérico, e [ngModel] recebe um número (ou [null] se o campo estiver vazio);
- linhas 42–43: um campo de texto de várias linhas, [<ion-textarea>], NÃO vinculado ao estado a cada tecla digitada: [(ionInput)] guarda o texto no campo comum, e [(ionBlur)], que é disparado quando o campo perde o foco, o copia de volta para o estado. O template exibido na parte inferior só é atualizado quando se sai do campo;
- linhas 46–48: uma única caixa de seleção, [true] ou [false], vinculada ao signal [newsletter] por meio de [ngModel];
- linhas 52–60: várias opções para UM conjunto: chips, [<ion-chip>]. Para cada hobby, [@let chosen] indica se ele está no conjunto; o chip fica então preenchido (caso contrário, apenas com contorno: [[outline]]), colorido e precedido de um sinal de verificação. Tocar adiciona ou remove o hobby;
- linhas 63–67: uma lista suspensa, [<ion-select>], cujos itens são [<ion-select-option>], cada um com seu próprio valor. [interface="popover"]: a lista se abre abaixo do campo (por padrão, em uma janela);
- linhas 70–75: uma lista de múltipla escolha ([[multiple]="true"]): seu valor é o array dos códigos selecionados. Ela se abre em uma janela, com uma caixa de seleção para cada item, e os botões [Cancel] ([cancelText]) e [OK];
- linhas 78–79: um controle deslizante, [<ion-range>], de 1 a 5 em incrementos de 1 ([step]), com marcas ([ticks]) às quais o controle se ajusta ([snaps]). [(ionInput)] é emitido durante o movimento, e [(ionChange)] quando o controle é solto;
- linhas 82–89: a data de nascimento e o botão [Choose], cujo identificador ([id]) é [choose-birth-date];
- linhas 91–100: uma janela, [<ion-modal>], aberta pelo botão cujo identificador é [trigger]. Seu conteúdo está em um [<ng-template>]: ele só é criado quando a janela é aberta;
- Linhas 94–98: o calendário, [<ion-datetime>]: seleção de uma única data ([presentation="date"]), em inglês, com semanas começando na segunda-feira ([[firstDayOfWeek]="1"]), com os botões [Cancel] e [OK] ([showDefaultButtons]); [(ionChange)] só é gerado quando [OK] é selecionado. Se nenhuma data for selecionada, ele abre em 1º de janeiro de 2000. O texto do local [title] aparece no topo;
- linha 109: o template, em tempo real: o pipe [json] (veja o exemplo 09) escreve o objeto em JSON, com indentação. A tag [<pre>] preserva as quebras de linha e os espaços;
- Linhas 112–115: um bloco que existe somente depois de um envio. [@if (sent(); as submission)] atribui o valor da condição a [submission], que é usado no bloco.
Escolhemos um nome, um hobby (esportes) e um idioma (inglês); depois abrimos o calendário; depois escolhemos uma data e enviamos:
A tabela a seguir resume o que cada campo transmite em seu evento ([$event.detail]):
Campo | Evento | Valor transmitido |
ion-input, ion-textarea, ion-searchbar | ionInput, ionChange | value: o texto (string, null ou undefined) |
ion-input type="number" (com ngModel) | ngModelChange | um número, ou null se o campo estiver vazio |
ion-checkbox, ion-toggle | ionChange | checked: true ou false |
ion-radio-group | ionChange | value: o valor do botão selecionado |
ion-select | ionChange | value: o valor da opção selecionada |
ion-select multiple | ionChange | value: o array dos valores selecionados |
ion-segment | ionChange | value: o valor do botão selecionado (string ou número) |
ion-range | ionInput, ionChange | value: um número (ou { lower, upper }) |
ion-datetime | ionChange | value: a data selecionada, uma string ISO 8601 |
Com [[(ngModel)]], você não precisa mais conhecer esses detalhes: cada campo do [Ionic] sabe ler e escrever seu próprio valor (é um “ControlValueAccessor”, a interface que conecta um campo aos formulários do [Angular]). Em comparação com o [Flutter], observe que não é preciso criar nem liberar um controlador para os campos de texto: um campo de texto é controlado como qualquer outro, por meio de seu valor. E o calendário não é uma função que devolve um [Future] ([showDatePicker]): é um componente, colocado no template, dentro de uma janela que também é definida no template.
O Exemplo 05 tinha um signal por campo de formulário. Para um formulário de verdade, preferimos **um** objeto que contenha todos os valores — o **modelo** — e descrevemos suas alterações em uma única função, o **reducer**: [reduce(currentState, action) -> newState]. É o que o hook [useReducer] faz no [React], e o que o Exemplo 06 do curso de [Flutter] escreve em [Dart]; no [Angular], não há nada a importar: [TypeScript] e um signal bastam.
| // =========================================================================
// src/app/ex06-reducer/ex06.page.ts - um formulário, um objeto, um reducer
// -------------------------------------------------------------------------
// O exemplo 05 tinha um signal por campo do formulário. Para um
// formulário real, preferimos UM objeto que contenha todos os valores, o
// MODELO (aqui um objeto Profile, não modificável), e descrevemos suas
// mudanças em uma única função, o REDUCER:
//
// reduce(currentState, action) -> newState
//
// O componente não modifica mais o estado: ele DESCREVE o que aconteceu, com
// um objeto Action ({ type: 'edit', field: 'lastName', value: 'Dupont' },
// { type: 'leave', field: 'lastName' }...), e o reducer deduz dele o
// novo estado. Toda a lógica fica em um só lugar, em uma função PURA
// (mesma entrada, mesma saída, sem efeito colateral), fácil de testar.
// O TypeScript se presta bem a isso: um tipo "discriminated union" lista todas as
// ações possíveis, e um switch em action.type é verificado pelo
// compilador (um case esquecido é um erro).
//
// O estado também guarda, para cada campo, se ele foi "tocado" (deixado pelo
// menos uma vez); deduzimos disso se ele está "modificado" (seu valor difere do
// valor inicial) e se está desabilitado.
// =========================================================================
import { JsonPipe } from '@angular/common';
import { Component, computed, signal } from '@angular/core';
import {
IonBackButton, IonButton, IonButtons, IonCol, IonContent, IonGrid, IonHeader, IonInput, IonRadio, IonRadioGroup,
IonRange, IonRow, IonSelect, IonSelectOption, IonTextarea, IonTitle, IonToggle, IonToolbar,
} from '@ionic/angular';
// o modelo
// os dados do formulário: um objeto NÃO MODIFICÁVEL (Readonly: todos os seus
// campos são somente leitura). Para "modificá-lo", construímos um
// novo: { ...old, lastName: 'Dupont' }
type Profile = Readonly<{
title: string;
firstName: string;
lastName: string;
age: number;
newsletter: boolean;
email: string;
country: string;
birthDate: string;
presentation: string;
}>;
// o nome de um campo do formulário: 'title' | 'firstName' | 'lastName' | ...
type Field = keyof Profile;
const initial: Profile = {
title: 'Mme',
firstName: 'Marie',
lastName: 'PELISSIER',
age: 30,
newsletter: false,
email: '',
country: 'fr',
birthDate: '',
presentation: '',
};
// o estado completo: os valores e o conjunto dos campos já deixados
interface State {
readonly values: Profile;
readonly touched: ReadonlySet<Field>;
}
// as ações
// uma "discriminated union": uma ação é um destes objetos, que
// distinguimos pela propriedade comum type. Para 'edit', o tipo do
// valor depende do campo: { [F in Field]: ... }[Field] constrói uma ação
// por campo ({ field: 'age', value: number } | { field: 'lastName', value: string } | ...)
type Action =
| { [F in Field]: { type: 'edit'; field: F; value: Profile[F] } }[Field]
| { type: 'leave'; field: Field }
| { type: 'uppercase' }
| { type: 'reset' };
// o reducer
// ele NUNCA modifica o estado recebido, ele retorna um novo
function reduce(state: State, action: Action): State {
switch (action.type) {
case 'edit':
// { ...object, [key]: value }: uma cópia do objeto, da qual UMA propriedade muda
return { ...state, values: { ...state.values, [action.field]: action.value } };
case 'leave':
// um novo set: os elementos do antigo, mais o campo deixado
return { ...state, touched: new Set([...state.touched, action.field]) };
case 'uppercase':
return {
...state,
values: { ...state.values, firstName: state.values.firstName.toUpperCase(), lastName: state.values.lastName.toUpperCase() },
};
case 'reset':
return { values: initial, touched: new Set() };
}
}
const titles = ['Mr', 'Mme', 'Melle'];
const trackedFields: Field[] = ['firstName', 'lastName', 'age', 'email'];
@Component({
selector: 'app-ex06',
imports: [
JsonPipe, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonRadioGroup, IonRadio,
IonGrid, IonRow, IonCol, IonInput, IonRange, IonToggle, IonSelect, IonSelectOption, IonTextarea, IonButton,
],
templateUrl: './ex06.page.html',
styles: `
h3 { font-size: 0.95em; font-weight: bold; margin: 16px 0 4px; }
.titles { display: flex; gap: 24px; padding: 8px 0; }
pre { background: #f5f5f5; padding: 8px; font-size: 12px; }
table { width: 100%; border-collapse: collapse; font-size: 14px; }
th { text-align: left; font-weight: 500; }
th, td { padding: 6px 4px; border-bottom: 1px solid #ddd; }
`,
})
export class Ex06Page {
readonly titles = titles;
// o estado da página: UM signal, que contém todo o objeto State
readonly state = signal<State>({ values: initial, touched: new Set() });
// a ÚNICA forma de mudar o estado: descrever o que aconteceu
dispatch(action: Action): void {
this.state.update((s) => reduce(s, action));
}
// valores DEDUZIDOS do estado
readonly v = computed(() => this.state().values);
modified(f: Field): boolean {
return this.v()[f] !== initial[f];
}
disabled(f: Field): boolean {
return f === 'email' && !this.v().newsletter; // o e-mail exige a newsletter
}
readonly formModified = computed(() => (Object.keys(initial) as Field[]).some((f) => this.modified(f)));
// as linhas da tabela "estado dos campos"
readonly fieldStates = computed(() =>
trackedFields.map((f) => ({
field: f,
touched: this.state().touched.has(f),
modified: this.modified(f),
disabled: this.disabled(f),
})),
);
}
|
O template:
- Linhas 36–46: os dados do formulário. [type Profile = ...] atribui um nome a um tipo; [Readonly<...>] torna todos os seus campos somente leitura; [profile.lastName = 'Dupont'] é um erro de compilação. Para “modificar” um perfil, crie uma cópia com um campo alterado: [{ ...profile, lastName: 'Dupont' }]. É o [copyWith] derivado do [Dart], sem nada escrito para isso: o operador [...] “espalha” as propriedades de um objeto em um novo objeto, e as propriedades escritas depois substituem as antigas;
- linha 49: [keyof Profile] é o tipo dos nomes dos campos do perfil: ['title' | 'firstName' | 'lastName' | ...]. Não é necessária nenhuma enumeração: o tipo dos nomes dos campos é inferido do próprio modelo;
- linhas 51–61: os valores iniciais;
- linhas 64–67: o estado completo: os valores e todos os campos dos quais já se saiu (“touched”).
As ações e o reducer:
- linhas 74–78: as ações possíveis, uma “união discriminada”: uma ação é um destes quatro tipos de objetos, distinguidos por sua propriedade comum [type] (o “discriminante”). Uma ação descreve o que aconteceu: [{ type: 'edit', field: 'lastName', value: 'Dupont' }], [{ type: 'leave', field: 'lastName' }]... É o equivalente da classe selada ([sealed]) do [Dart] e de suas subclasses;
- Linha 75: a ação [edit] é, ela própria, uma união de uma ação por campo: [{ [F in Field]: ... }] cria um objeto que tem uma propriedade por campo [F], cujo valor é o tipo da ação para esse campo (o valor tem o tipo do campo: [Profile[F]]); [[Field]] extrai a união desses tipos. Resultado: [{ type: 'edit', field: 'age', value: 30 }] é aceito, [{ type: 'edit', field: 'age', value: 'thirty' }] é rejeitado pelo compilador. O [Dart] verificava esse tipo em tempo de execução ([v as int]); o [TypeScript] o verifica em tempo de compilação;
- linhas 82–98: o reducer. É uma função pura: mesma entrada, mesma saída, sem efeitos colaterais; ele nunca modifica o estado recebido, mas devolve um novo. [switch] trata do discriminante: em cada [case], o [TypeScript] conhece o tipo da ação (em [case 'leave'], [action] tem um campo [field]; em [case 'uppercase'], não tem). O compilador também verifica se todos os casos são tratados: a função deve devolver um [State] (linha 82), e um caso ausente faria com que ela terminasse sem devolver nada, o que seria um erro de compilação;
- linha 86: [[action.field]: action.value]: uma propriedade cujo NOME é calculado (entre colchetes);
- linha 89: um novo conjunto, formado pelos elementos do conjunto antigo ([...state.touched]) e pelo campo do qual se saiu.
O componente:
- linha 123: o estado da tela: UM signal, que contém o objeto [State];
- linhas 126–128: a ÚNICA forma de alterar o estado: descrever o que aconteceu. [dispatch] (“despachar”, o nome dado a ele pelo [React]) calcula o novo estado usando o reducer. Diferentemente do exemplo do [Flutter], não há controladores de campo que precisem ser ressincronizados depois (botões “Capitalize Name” e “Reset”): cada campo exibe seu valor por meio de um binding [[value]], que acompanha o estado por conta própria;
- linhas 131–147: valores derivados do estado: os valores do formulário ([v], para abreviar o template); um campo é modificado se seu valor difere do valor inicial; o e-mail fica desativado sem a newsletter; o formulário é modificado se qualquer um de seus campos for modificado ([some]); as linhas da tabela de status dos campos.
O template:
| <!-- ======================================================================
ex06.page.html - cada campo DESCREVE suas mudanças com uma ação
====================================================================== -->
<ion-header>
<ion-toolbar color="primary">
<ion-buttons slot="start">
<ion-back-button defaultHref="/" />
</ion-buttons>
<ion-title>Example 06 - a reducer</ion-title>
</ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
<ion-radio-group [value]="v().title"
(ionChange)="dispatch({ type: 'edit', field: 'title', value: $event.detail.value })">
<div class="titles">
@for (t of titles; track t) {
<ion-radio [value]="t" labelPlacement="end">{{ t }}</ion-radio>
}
</div>
</ion-radio-group>
<ion-grid class="ion-no-padding">
<ion-row>
<ion-col>
<!-- (ionInput): uma ação 'edit' a cada tecla digitada;
(ionBlur): uma ação 'leave' quando o campo perde o foco -->
<ion-input label="First name" labelPlacement="floating" [value]="v().firstName"
(ionInput)="dispatch({ type: 'edit', field: 'firstName', value: $event.detail.value ?? '' })"
(ionBlur)="dispatch({ type: 'leave', field: 'firstName' })" />
</ion-col>
<ion-col>
<ion-input label="Last name" labelPlacement="floating" [value]="v().lastName"
(ionInput)="dispatch({ type: 'edit', field: 'lastName', value: $event.detail.value ?? '' })"
(ionBlur)="dispatch({ type: 'leave', field: 'lastName' })" />
</ion-col>
</ion-row>
</ion-grid>
<!-- (ionKnobMoveEnd): o controle deslizante foi solto, o campo foi "deixado" -->
<ion-range [label]="'Age: ' + v().age" [min]="0" [max]="120" [value]="v().age"
(ionInput)="dispatch({ type: 'edit', field: 'age', value: +$event.detail.value })"
(ionKnobMoveEnd)="dispatch({ type: 'leave', field: 'age' })" />
<ion-toggle [checked]="v().newsletter"
(ionChange)="dispatch({ type: 'edit', field: 'newsletter', value: $event.detail.checked })">
Receive the newsletter
</ion-toggle>
<!-- [disabled]: um valor deduzido do estado -->
<ion-input label="E-mail (if newsletter)" labelPlacement="floating" type="email"
[value]="v().email" [disabled]="disabled('email')"
(ionInput)="dispatch({ type: 'edit', field: 'email', value: $event.detail.value ?? '' })"
(ionBlur)="dispatch({ type: 'leave', field: 'email' })" />
<ion-select label="Country" interface="popover" [value]="v().country"
(ionChange)="dispatch({ type: 'edit', field: 'country', value: $event.detail.value })">
<ion-select-option value="fr">France</ion-select-option>
<ion-select-option value="be">Belgium</ion-select-option>
<ion-select-option value="ch">Switzerland</ion-select-option>
</ion-select>
<ion-textarea label="Presentation" labelPlacement="floating" [rows]="2" [value]="v().presentation"
(ionInput)="dispatch({ type: 'edit', field: 'presentation', value: $event.detail.value ?? '' })"
(ionBlur)="dispatch({ type: 'leave', field: 'presentation' })" />
<div class="ion-margin-vertical">
<ion-button fill="outline" shape="round" (click)="dispatch({ type: 'uppercase' })">Name in upper case</ion-button>
<ion-button fill="outline" shape="round" (click)="dispatch({ type: 'reset' })">Reset</ion-button>
</div>
<h3>The model, live</h3>
<pre>{{ v() | json }}</pre>
<h3>The state of the fields</h3>
<!-- uma tabela HTML comum, uma linha por campo acompanhado -->
<table>
<tr><th>field</th><th>touched</th><th>modified</th><th>disabled</th></tr>
@for (row of fieldStates(); track row.field) {
<tr>
<td>{{ row.field }}</td>
<td>{{ row.touched }}</td>
<td>{{ row.modified }}</td>
<td>{{ row.disabled }}</td>
</tr>
}
</table>
<p>form modified: <strong>{{ formModified() }}</strong></p>
</ion-content>
|
- Cada campo exibe um valor do modelo ([[value]="v().firstName"]...) e descreve suas alterações com uma ação: [dispatch({ type: 'edit', field: 'firstName', value: ... })] a cada tecla digitada ([(ionInput)]), [dispatch({ type: 'leave', field: 'firstName' })] quando ele perde o foco ([(ionBlur)]). Um objeto pode ser escrito diretamente em uma instrução do template e é validado pelo compilador como no código [TypeScript]: graças a [strictTemplates], um valor de tipo incorreto para um campo ([value: 'thirty'] para a idade) é um erro de compilação, reportado no arquivo [HTML];
- Linhas 42–44: a idade, um controle deslizante de 0 a 120. [+$event.detail.value]: o operador [+] converte o valor em número. [(ionKnobMoveEnd)] é gerado quando o controle é solto: saiu-se do campo;
- linhas 46–49: a newsletter, um interruptor;
- linha 53: [[disabled]]: o campo de e-mail fica desativado até que a newsletter seja solicitada — um valor derivado do estado;
- linhas 69–70: os botões descrevem suas ações, sem campos nem valores;
- linha 74: o template, em tempo real;
- linhas 78–88: uma tabela HTML padrão, [<table>], com suas linhas ([<tr>]), suas células de cabeçalho ([<th>]) e suas células ([<td>]): o status de cada campo é acompanhado;
- linha 89: texto composto de vários segmentos com estilos diferentes: em HTML, basta uma única tag [<strong>] (o [Text.rich] do [Flutter]).
Alteramos o nome, saímos do campo, assinamos a newsletter; depois capitalizamos o nome:
À direita, o primeiro nome também está “touched”: ele foi selecionado antes de clicar no botão, e o clique no botão o fez perder o foco. Toda a lógica do formulário está contida no reducer — uma função de poucas linhas, sem componentes, que pode ser testada isoladamente. O componente agora se limita a exibir o estado e a descrever o que está acontecendo.
Uma função **pura**, [validate(account)], devolve os erros dos campos; um signal calculado a chama sempre que a conta muda, de modo que os erros estão sempre atualizados. Não os exibimos imediatamente (um formulário vazio coberto de vermelho é desagradável), apenas para um campo do qual já se saiu. Enviar o formulário revela todos os erros.
| // =========================================================================
// src/app/ex07-validation/ex07.page.ts - validando um formulário, à mão
// -------------------------------------------------------------------------
// Uma função PURA, validate(account), retorna os erros dos campos; um
// signal calculado (computed) a chama a cada vez que account muda:
// os erros estão, portanto, sempre atualizados.
// Não os mostramos imediatamente (um formulário vazio coberto de vermelho é
// desagradável): apenas para um campo já deixado ("touched"). O envio
// marca todos os campos como touched e só age se o formulário
// for válido. A mensagem de erro é exibida pelo template, sob o
// campo (a propriedade errorText do ion-input é usada com os
// formulários do Angular: veja o exemplo 08).
//
// Mesmas regras do servidor RdvMedecins (formulário "Criar uma conta").
// 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, computed, input, signal } from '@angular/core';
import {
IonBackButton, IonButton, IonButtons, IonContent, IonHeader, IonIcon, IonInput, IonSelect, IonSelectOption,
IonText, IonTitle, IonToolbar,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { checkmarkCircle } from 'ionicons/icons';
// a conta sendo digitada
interface Account {
title: string;
firstName: string;
lastName: string;
login: string;
password: string;
confirmation: string;
}
type Field = keyof Account;
// para cada campo com erro, sua mensagem: um objeto cujas chaves são todas
// opcionais (Partial)
type Errors = Partial<Record<Field, string>>;
const titles = ['Mr', 'Mme', 'Melle'];
const loginFormat = /^[a-z0-9._-]{1,30}$/;
const passwordMin = 6;
// as regras: uma função pura, que só depende do seu argumento
function validate(c: Account): Errors {
const errors: Errors = {};
if (!titles.includes(c.title)) errors.title = 'Choose a title from the list.';
if (!c.firstName.trim()) {
errors.firstName = 'The first name is required.';
} else if (c.firstName.length > 20) {
errors.firstName = 'The first name must not exceed 20 characters.';
}
if (!c.lastName.trim()) {
errors.lastName = 'The last name is required.';
} else if (c.lastName.length > 20) {
errors.lastName = 'The last name must not exceed 20 characters.';
}
if (!c.login) {
errors.login = 'The login is required.';
} else if (!loginFormat.test(c.login)) {
errors.login = 'Unaccented lower-case letters, digits, dot, hyphen, underscore.';
}
if (!c.password) {
errors.password = 'The password is required.';
} else if (c.password.length < passwordMin) {
errors.password = `At least ${passwordMin} characters.`;
}
// uma regra que compara DOIS campos
if (c.confirmation !== c.password) {
errors.confirmation = 'The confirmation does not match the password.';
}
return errors;
}
// um pequeno componente: uma mensagem sobre um fundo colorido. Ele recebe seu texto e
// sua cor por meio de INPUTS, input() (veja o exemplo 10)
@Component({
selector: 'app-message',
template: `<div class="message" [style.background]="color()">{{ text() }}</div>`,
styles: `.message { padding: 12px; border-radius: 8px; margin-top: 12px; }`,
})
export class Message {
readonly text = input.required<string>();
readonly color = input.required<string>();
}
@Component({
selector: 'app-ex07',
imports: [
Message, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonSelect, IonSelectOption,
IonInput, IonIcon, IonText, IonButton,
],
templateUrl: './ex07.page.html',
styles: `
/* o rótulo de um campo com erro, em vermelho */
.wrong { color: var(--ion-color-danger); }
.error { font-size: 12px; padding: 4px 0; }
`,
})
export class Ex07Page {
readonly titles = titles;
// os campos de texto, descritos por dados: o template os percorre em um laço
readonly textFields: { field: Field; label: string; secret: boolean }[] = [
{ field: 'firstName', label: 'First name', secret: false },
{ field: 'lastName', label: 'Last name', secret: false },
{ field: 'login', label: 'Login', secret: false },
{ field: 'password', label: 'Password', secret: true },
{ field: 'confirmation', label: 'Confirmation', secret: true },
];
// o estado: a conta sendo digitada, os campos já deixados, o resultado do envio
readonly account = signal<Account>({ title: 'Mr', firstName: '', lastName: '', login: '', password: '', confirmation: '' });
readonly touched = signal<ReadonlySet<Field>>(new Set());
readonly submitAttempted = signal(false);
readonly success = signal(false);
// os erros: CALCULADOS a partir da conta, nunca armazenados no estado
readonly errors = computed(() => validate(this.account()));
readonly errorCount = computed(() => Object.keys(this.errors()).length);
constructor() {
addIcons({ checkmarkCircle });
}
update(field: Field, value: string | null | undefined): void {
this.account.update((c) => ({ ...c, [field]: value ?? '' }));
this.success.set(false);
}
leave(field: Field): void {
this.touched.update((t) => new Set([...t, field]));
}
// o erro a EXIBIR para um campo: somente se ele foi touched
error(field: Field): string | undefined {
return this.touched().has(field) ? this.errors()[field] : undefined;
}
// um campo touched e sem erro: ele ganhará seu visto verde
valid(field: Field): boolean {
return this.touched().has(field) && !this.errors()[field];
}
send(): void {
this.submitAttempted.set(true);
// todos os campos são touched: todos os erros aparecem
this.touched.set(new Set(Object.keys(this.account()) as Field[]));
// aqui, enviaríamos a conta ao servidor (veja o exemplo 25)
this.success.set(this.errorCount() === 0);
}
}
|
- linhas 30–38: a conta digitada e os nomes de seus campos;
- linha 41: os erros: um objeto cujas chaves são nomes de campos e cujos valores são mensagens de erro. [Record<Field, string>] teria uma propriedade para CADA campo; [Partial<...>] torna todas opcionais: apenas os campos com erros são listados ali;
- linhas 44–45: uma expressão regular (o formato de um login) e uma constante: as mesmas regras do servidor [RdvMedecins];
- linhas 48–76: as regras: uma função pura que depende apenas do seu argumento e devolve os eventuais erros. A última regra compara os DOIS campos: a confirmação e a senha;
- linhas 80–88: um pequeno componente, para evitar repetir duas vezes a mesma caixa colorida: uma mensagem sobre um fundo colorido. Ele recebe seu texto e sua cor do componente pai por meio de duas **entradas** (inputs): [input.required<string>()] cria uma entrada obrigatória, que se lê como um signal ([text()]). O Exemplo 10 apresentará as entradas em detalhes. O componente é declarado no mesmo arquivo que a página que o usa; ele é exportado ([export]) para poder ser reutilizado em outros lugares; isso não é necessário para usá-lo neste arquivo;
- linhas 106–112: os campos de texto, descritos por dados: o template percorrerá esses dados em um laço;
- linhas 115–118: o estado: a conta, os campos já tratados e o resultado do envio;
- linhas 121–122: os erros, CALCULADOS a partir da conta, nunca incluídos no estado; e o número deles ([Object.keys] fornece o array de chaves de um objeto);
- linhas 128–131: digitar em um campo altera o registro (uma cópia, na qual um campo muda);
- linhas 138–140: o erro a exibir para um campo: somente se ele tiver sido editado;
- linhas 143–145: um campo que foi editado e não tem erros exibirá um sinal de verificação verde;
- linhas 147–153: o envio marca todos os campos como preenchidos (os erros aparecem) e só então age, se o formulário for válido.
| <!-- ======================================================================
ex07.page.html - os campos e seus erros
====================================================================== -->
<ion-header>
<ion-toolbar color="primary">
<ion-buttons slot="start">
<ion-back-button defaultHref="/" />
</ion-buttons>
<ion-title>Example 07 - validation</ion-title>
</ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
<ion-select label="Title" interface="popover" [value]="account().title"
(ionChange)="update('title', $event.detail.value)">
@for (t of titles; track t) {
<ion-select-option [value]="t">{{ t }}</ion-select-option>
}
</ion-select>
<!-- um campo por elemento de textFields: o template é escrito uma única vez -->
@for (f of textFields; track f.field) {
<ion-input labelPlacement="floating" [type]="f.secret ? 'password' : 'text'" [value]="account()[f.field]"
(ionInput)="update(f.field, $event.detail.value)" (ionBlur)="leave(f.field)">
<!-- slot="label": um rótulo escrito por nós, em vez da propriedade label;
[class.wrong]: a classe CSS que o colore de vermelho se o campo tiver erro -->
<div slot="label" [class.wrong]="!!error(f.field)">{{ f.label }}</div>
<!-- slot="end": um ícone à direita do campo, um visto verde se ele é touched e válido -->
@if (valid(f.field)) {
<ion-icon slot="end" name="checkmark-circle" color="success" />
}
</ion-input>
<!-- a mensagem de erro, sob o campo; "as message" nomeia o valor da condição -->
@if (error(f.field); as message) {
<ion-text color="danger"><div class="error">{{ message }}</div></ion-text>
}
}
<ion-button expand="block" shape="round" class="ion-margin-top" (click)="send()">Create the account</ion-button>
<!-- as mensagens no final do formulário: o componente <app-message> e seus inputs -->
@if (submitAttempted() && errorCount() > 0) {
<app-message [text]="'The form contains ' + errorCount() + ' error(s).'" color="#ffebee" />
}
@if (success()) {
<app-message text="Valid form: it could be sent to the server." color="#e8f5e9" />
}
</ion-content>
|
- linhas 15–20: uma lista suspensa para o título;
- linhas 23–38: um campo para cada elemento de [textFields]: o template de um campo é escrito uma única vez. Seu tipo depende do campo: [password] oculta os caracteres de uma senha;
- Linha 28: o rótulo do campo. Em vez da propriedade [label], nós o especificamos por meio do local [slot="label"]: ele passa a ser um elemento do nosso template, que podemos estilizar. [[class.wrong]] o colore de vermelho quando o campo contém um erro;
- linhas 30–32: [slot="end"]: um ícone à direita do campo; um sinal de verificação verde ([color="success"]) aparece se o campo tiver sido preenchido e for válido;
- linhas 35–37: a mensagem de erro, em vermelho, abaixo do campo. [@if (error(f.field); as message)]: este bloco só existe se houver um erro a exibir, e [message] é o seu texto;
- linhas 43–48: as mensagens do fim do formulário: o componente [<app-message>] e suas duas ocorrências. [[text]="..."] fornece a ele o valor de uma expressão; [text="..."], sem colchetes, fornece uma string fixa.
Preenchemos alguns campos e enviamos; depois corrigimos tudo e enviamos novamente:
Por que não usar a propriedade [errorText] de [<ion-input>], que pode exibir um erro abaixo do campo? Porque o [Ionic] só o exibe se o campo tiver as classes CSS [ion-invalid] (o que é incorreto) e [ion-touched] (do qual se saiu), e ele próprio gerencia essas duas classes, copiando-as das definidas pelos formulários do [Angular] ([ng-invalid], [ng-touched]): como aqui elas são definidas manualmente, são apagadas pelo [Ionic] na tecla seguinte. [errorText] funciona, portanto, com os formulários do [Angular], que o exemplo seguinte usa. Aqui, sem um formulário do [Angular], exibimos a mensagem nós mesmos: três linhas de template.
ATENÇÃO: esta validação é apenas uma **comodidade** para o usuário — uma resposta imediata, sem uma ida e volta ao servidor. Ela não protege nada: qualquer pessoa pode enviar ao servidor uma requisição montada manualmente ([curl]...), e o código de um aplicativo móvel pode ser modificado. O servidor, portanto, sempre revalida tudo (veja o Exemplo 25).
O formulário do Exemplo 07, escrito com as ferramentas fornecidas pelo próprio [Angular]. Enquanto o [Flutter] tem seus próprios widgets de formulário ([Form], [TextFormField]), o [Angular] usa “formulários reativos” ([ReactiveFormsModule]): o formulário é definido na classe por meio de objetos, e o template vincula seus campos a eles.
| // =========================================================================
// src/app/ex08-reactive-forms/ex08.page.ts - formulários reativos
// -------------------------------------------------------------------------
// O formulário do exemplo 07, escrito com as ferramentas de formulário
// que o próprio Angular fornece (ReactiveFormsModule):
// - FormGroup: um grupo de campos (FormControl), descrito na classe,
// vinculado ao template por [formGroup] e formControlName;
// - Validators: regras prontas (required, maxLength, pattern,
// minLength...). Uma regra (ValidatorFn) é uma função:
// (control) -> null se o valor é bom, caso contrário um objeto de erros
// ({ blank: true }, { maxlength: {...} }...);
// - um validador de GRUPO recebe o grupo inteiro: ele compara dois campos;
// - form.valid, form.markAllAsTouched(), getRawValue()...:
// o estado do formulário, lido e modificado pelo código.
// Os campos do Ionic se conectam a isso por conta própria: ion-input recebe as classes
// ion-invalid e ion-touched quando seu control está errado e foi deixado,
// e então exibe seu errorText.
// =========================================================================
import { Component, inject, signal } from '@angular/core';
import {
AbstractControl, NonNullableFormBuilder, ReactiveFormsModule, ValidationErrors, ValidatorFn, Validators,
} from '@angular/forms';
import {
IonBackButton, IonButton, IonButtons, IonContent, IonHeader, IonInput, IonSelect, IonSelectOption, IonText,
IonTitle, IonToolbar,
} from '@ionic/angular';
const titles = ['Mr', 'Mme', 'Melle'];
// os campos de texto que têm regras, e sua mensagem "required"
type TextField = 'firstName' | 'lastName' | 'login' | 'password';
const requiredMessages: Record<TextField, string> = {
firstName: 'The first name is required.',
lastName: 'The last name is required.',
login: 'The login is required.',
password: 'The password is required.',
};
// um validador PERSONALIZADO: o valor não pode ser vazio nem composto
// só de espaços (Validators.required aceita " ")
const notBlank: ValidatorFn = (control: AbstractControl): ValidationErrors | null =>
String(control.value ?? '').trim() ? null : { blank: true };
// um validador de GRUPO: ele recebe o FormGroup e compara dois de seus campos
const sameConfirmation: ValidatorFn = (group: AbstractControl): ValidationErrors | null =>
group.get('confirmation')?.value === group.get('password')?.value ? null : { confirmation: true };
@Component({
selector: 'app-ex08',
imports: [
ReactiveFormsModule, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonSelect,
IonSelectOption, IonInput, IonText, IonButton,
],
templateUrl: './ex08.page.html',
styles: `
.error { font-size: 12px; }
.result { padding: 12px; border-radius: 8px; margin-top: 12px; word-break: break-all; }
`,
})
export class Ex08Page {
readonly titles = titles;
// o FormBuilder constrói os controls; "NonNullable": um campo
// redefinido (reset) volta ao seu valor inicial, e não a null
private readonly fb = inject(NonNullableFormBuilder);
// o formulário: para cada campo, [valor inicial, regras]
readonly form = this.fb.group(
{
title: ['Mr'],
firstName: ['', [notBlank, Validators.maxLength(20)]],
lastName: ['', [notBlank, Validators.maxLength(20)]],
login: ['', [Validators.required, Validators.pattern(/^[a-z0-9._-]{1,30}$/)]],
password: ['', [Validators.required, Validators.minLength(6)]],
confirmation: [''],
},
// as regras do próprio grupo
{ validators: sameConfirmation },
);
// null: nenhum envio ainda; '': envio recusado; caso contrário, o JSON enviado
readonly sent = signal<string | null>(null);
// a mensagem de erro de um campo, a partir dos erros do seu control
// (errors: null, ou um objeto em que cada chave é o nome de uma regra violada)
error(field: TextField): string {
const errors = this.form.controls[field].errors;
if (errors?.['blank'] || errors?.['required']) {
return requiredMessages[field];
}
if (errors?.['maxlength']) {
return `${errors['maxlength'].requiredLength} characters at most.`;
}
if (errors?.['pattern']) {
return 'Unaccented lower-case letters, digits, dot, hyphen, underscore.';
}
if (errors?.['minlength']) {
return `At least ${errors['minlength'].requiredLength} characters.`;
}
return '';
}
// o erro do GRUPO, exibido sob a confirmação assim que ela é touched
confirmationError(): boolean {
const confirmation = this.form.controls.confirmation;
return this.form.hasError('confirmation') && (confirmation.dirty || confirmation.touched);
}
create(): void {
if (this.form.invalid) {
// todos os erros aparecem
this.form.markAllAsTouched();
this.sent.set('');
return;
}
// getRawValue(): os valores de todos os campos; não guardamos a confirmação
const { confirmation, ...account } = this.form.getRawValue();
this.sent.set(JSON.stringify(account));
}
}
|
- linhas 21–23: as ferramentas dos formulários reativos, no pacote [@angular/forms];
- linhas 32–38: campos de texto com regras de validação e a mensagem de “obrigatório”;
- linhas 42–43: um validador personalizado. Um validador ([ValidatorFn]) é uma função que recebe o controle de um campo ([control.value] é o seu valor) e devolve [null] se o valor estiver correto; caso contrário, devolve um objeto que descreve o erro: aqui, [{ blank: true }]. [Angular] tem o seu próprio, [Validators.required], mas ele aceita um valor formado apenas por espaços;
- Linhas 46–47: um validador para o GRUPO: ele recebe o formulário inteiro ([group.get('password')] trata da validação da senha) e compara dois de seus campos. [Angular] o dispara novamente sempre que um dos campos do grupo muda: quando a senha muda, a confirmação é revalidada sem exigir nenhuma digitação (o exemplo do [Flutter] tinha de revalidar a confirmação por conta própria, usando a chave do campo);
- linha 52: o módulo dos formulários reativos, importado pelo componente;
- Linha 66: [FormBuilder], obtido por injeção de dependência. Ele gera os controles de forma abreviada. [NonNullable]: um campo que foi redefinido ([reset()]) volta ao seu valor inicial, e não a [null]: os valores são então [string], e não [string | null];
- linhas 69–80: o formulário, um [FormGroup]: para cada campo, seu valor inicial e suas regras. [Validators.maxLength(20)], [Validators.pattern(...)] e [Validators.minLength(6)] são fábricas de validadores: elas recebem um parâmetro e devolvem a regra. O segundo argumento de [group] especifica as regras do próprio grupo;
- linhas 87–102: a mensagem de erro de um campo. [this.form.controls[field].errors] é [null] se o campo for válido; caso contrário, é um objeto cujas chaves são os nomes das regras violadas: [{ blank: true }], [{ maxlength: { requiredLength: 20, actualLength: 23 } }], [{ pattern: ... }]... A mensagem é escolhida de acordo com a regra;
- linhas 105–108: o erro do grupo, a ser exibido abaixo da confirmação assim que ela é preenchida. Um controle fica [dirty] assim que o usuário altera seu valor, e [touched] assim que o usuário sai dele;
- linhas 110–120: o envio. [form.invalid] é verdadeiro se alguma das regras (de campos ou do grupo) não for atendida; nesse caso, todos os campos são marcados como modificados ([markAllAsTouched()]), e seus erros são exibidos. Caso contrário, [getRawValue()] devolve os valores de todos os campos — um objeto tipado ([TypeScript] conhece suas propriedades, inferidas de [group]) —, do qual a confirmação é extraída por meio de “desestruturação”: [confirmation] recebe a propriedade de mesmo nome, e [account] recebe todo o resto.
| <!-- ======================================================================
ex08.page.html - um formulário reativo
====================================================================== -->
<ion-header>
<ion-toolbar color="primary">
<ion-buttons slot="start">
<ion-back-button defaultHref="/" />
</ion-buttons>
<ion-title>Example 08 - FormGroup</ion-title>
</ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
<!-- [formGroup]: o formulário da classe; (ngSubmit): o método chamado no envio -->
<form [formGroup]="form" (ngSubmit)="create()">
<!-- formControlName: o control do grupo ao qual este campo está vinculado -->
<ion-select label="Title" labelPlacement="floating" interface="popover" formControlName="title">
@for (t of titles; track t) {
<ion-select-option [value]="t">{{ t }}</ion-select-option>
}
</ion-select>
<!-- errorText: a mensagem exibida, em vermelho, quando o control está errado E foi deixado -->
<ion-input label="First name" labelPlacement="floating" formControlName="firstName" [errorText]="error('firstName')" />
<ion-input label="Last name" labelPlacement="floating" formControlName="lastName" [errorText]="error('lastName')" />
<ion-input label="Login" labelPlacement="floating" formControlName="login" [errorText]="error('login')" />
<ion-input label="Password" labelPlacement="floating" type="password" formControlName="password"
[errorText]="error('password')" />
<ion-input label="Confirmation" labelPlacement="floating" type="password" formControlName="confirmation" />
<!-- o erro do GRUPO não pertence a nenhum campo: nós mesmos o exibimos -->
@if (confirmationError()) {
<ion-text color="danger">
<div class="error">The confirmation does not match the password.</div>
</ion-text>
}
<!-- type="submit": o botão envia o formulário (ngSubmit) -->
<ion-button type="submit" expand="block" shape="round" class="ion-margin-top">Create the account</ion-button>
</form>
@if (sent() !== null) {
<div class="result" [style.background]="sent() ? '#e8f5e9' : '#ffebee'">
{{ sent() ? 'Valid form: ' + sent() : 'Invalid form.' }}
</div>
}
</ion-content>
|
- linha 16: [[formGroup]] vincula a tag [<form>] ao formulário da classe; [(ngSubmit)] é gerado quando ele é enviado;
- Linha 18: [formControlName="title"] vincula a lista suspensa ao controle [title] do grupo: ele exibe seu valor e o atualiza;
- linhas 25–30: os campos de texto, vinculados da mesma forma. [[errorText]]: a mensagem de erro do campo. [Ionic] a exibe em vermelho e destaca o campo quando o controle é inválido e dele se saiu: as classes [ng-invalid] e [ng-touched] que o [Angular] define no campo são copiadas pelo [Ionic] para [ion-invalid] e [ion-touched]. Não há mais nada a escrever;
- linhas 32–36: o erro do grupo não está associado a nenhum campo: nós mesmos o exibimos, abaixo da confirmação;
- linha 39: [type="submit"]: o botão envia o formulário;
- linhas 42–46: o resultado do envio, sobre um fundo vermelho ou verde.
Informamos valores incorretos e enviamos; depois os corrigimos:
Uma diferença de comportamento em relação ao exemplo do [Flutter]: [AutovalidateMode.onUserInteraction] exibia o erro de um campo assim que o primeiro caractere era digitado; o [Ionic] espera até que se saia do campo ([ion-touched]), o que evita que uma mensagem de erro apareça enquanto você ainda está digitando. Os equivalentes de [form.validate()] e [form.save()] aqui são [form.invalid] e [form.getRawValue()].
Qual dos dois métodos escolher? Os formulários reativos bastam para um formulário cujas regras são escritas dentro da aplicação (o [Angular] 22 também oferece, em [@angular/forms/signals], formulários construídos sobre signals, que seguem o mesmo princípio). Mas, neste curso, são as regras do **servidor** que prevalecem: o estudo de caso não tem regras na aplicação e exibe o erro devolvido pelo servidor abaixo de cada campo (Exemplo 25). Este é o método usado no Exemplo 07, que trata dos campos e de seus erros.
Este exemplo mostra duas formas de formatar datas, números e texto: no código [TypeScript], usando a API [Intl] e funções JavaScript, além de funções personalizadas; no template, usando os “pipes” do [Angular]. Cada linha das duas tabelas mostra um trecho de código e o que ele exibe.
As funções personalizadas, junto com os formatadores da API [Intl], ficam em um arquivo separado, que pode ser testado de forma independente:
| // =========================================================================
// src/app/ex09-formatting/formatting.ts - funções de formatação
// -------------------------------------------------------------------------
// FUNÇÕES comuns, guardadas em um arquivo e testáveis isoladamente:
// timeRange(slot) -> "8:00 - 8:20"
// timeRange(slot, 'start') -> "8:00"
// capitalize('marie pelissier') -> "Marie Pelissier"
// Para datas, números e valores, a API Intl do JavaScript
// conhece as convenções de cada idioma: construímos um "formatter"
// uma vez por todas e o usamos (format) quantas vezes quisermos.
// =========================================================================
// os formatters Intl
// datas: estilos "prontos" (dateStyle, timeStyle: short, medium, long, full)...
export const shortDate = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' });
export const fullDate = new Intl.DateTimeFormat('en-US', { dateStyle: 'full' });
export const timeOnly = new Intl.DateTimeFormat('en-US', { timeStyle: 'medium' });
export const frenchDay = new Intl.DateTimeFormat('fr-FR', { dateStyle: 'long' });
// ... ou então as partes a exibir, cada uma com sua forma ("2-digit": em dois dígitos)
export const pattern = new Intl.DateTimeFormat('en-US', {
day: '2-digit',
month: '2-digit',
year: 'numeric',
hour: '2-digit',
minute: '2-digit',
});
// uma duração relativa a agora: "3 days ago", "in 2 hours"
export const relative = new Intl.RelativeTimeFormat('en-US', { numeric: 'auto' });
// números e valores
export const euros = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR' });
export const integer = new Intl.NumberFormat('en-US');
export const percent = new Intl.NumberFormat('en-US', { style: 'percent', minimumFractionDigits: 1 });
// funções caseiras
// um horário, como descrito pela API do RdvMedecins
export interface Slot {
startHour: number;
startMinute: number;
endHour: number;
endMinute: number;
}
export type Part = 'all' | 'start' | 'end';
// "8:05" em vez de "8:5": padStart preenche à esquerda com zeros
function time(h: number, m: number): string {
return `${h}:${m.toString().padStart(2, '0')}`;
}
// um parâmetro OPCIONAL, com seu valor padrão: part = 'all'
export function timeRange(c: Slot, part: Part = 'all'): string {
switch (part) {
case 'start':
return time(c.startHour, c.startMinute);
case 'end':
return time(c.endHour, c.endMinute);
case 'all':
return `${time(c.startHour, c.startMinute)} - ${time(c.endHour, c.endMinute)}`;
}
}
// "marie pelissier" -> "Marie Pelissier"; \p{L}: uma letra, com acento ou
// não (o flag u, "unicode", é necessário para \p{...})
export function capitalize(text: string): string {
return text.replace(/\p{L}+/gu, (word) => word[0].toUpperCase() + word.substring(1).toLowerCase());
}
// "Marie PELISSIER" -> "MP"
export function initials(text: string): string {
return text
.split(/\s+/)
.filter((word) => word.length > 0)
.map((word) => word[0].toUpperCase())
.join('');
}
// "2026-10-05" (o formato da API do RdvMedecins) -> uma data, à meia-noite do HORÁRIO
// LOCAL. ATENÇÃO: new Date('2026-10-05') daria meia-noite no horário
// universal (UTC), ou seja, a noite anterior em um celular configurado no
// horário de Nova York
export function toDate(day: string): Date {
const [year, month, d] = day.split('-').map(Number);
return new Date(year, month - 1, d); // os meses são numerados a partir de 0
}
|
- Linhas 15–18: formatadores de data da API [Intl], reconhecidos por todos os navegadores (e pela WebView em dispositivos móveis). O primeiro parâmetro é o idioma ([fr-FR], [en-US]); o segundo é o formato desejado: estilos “predefinidos” para a data ([dateStyle]) e para a hora ([timeStyle]), do mais curto ([short]) ao mais completo ([full]);
- linhas 20–26: também é possível especificar quais partes exibir, cada uma com seu próprio formato: o dia e o mês como números de dois dígitos, o ano completo... A ordem das partes e os separadores seguem as convenções do idioma: não existe um padrão como ['dd/MM/yyyy HH:mm'] (o pipe [date] do [Angular], porém, o aceita);
- linha 28: uma hora relativa: “3 days ago”, “tomorrow” ([numeric: 'auto'] prefere “tomorrow” a “in 1 day”);
- linhas 30–32: formatadores de números: valores monetários ([style: 'currency'], incluindo a moeda), números, porcentagens (com pelo menos um dígito após a vírgula decimal);
- linhas 36–41: um horário, como descrito pela API [RdvMedecins]: horas e minutos, em forma numérica;
- linha 47: “8:05” em vez de “8:5”: [padStart(2, '0')] preenche com zeros à esquerda;
- linhas 51–60: uma função com um parâmetro opcional e seu valor padrão: [timeRange(c)] ou [timeRange(c, 'start')]. O tipo do parâmetro — uma união de três strings — limita os valores possíveis;
- linhas 64–66: cada palavra (uma sequência de letras, com ou sem acento: [\p{L}+], com a flag [u], “Unicode”; a flag [g] especifica que todas as ocorrências devem ser substituídas, e não apenas a primeira) é substituída pelo que a função devolve: sua primeira letra em maiúscula, o restante em minúsculas. O [TypeScript] não tem as extensões do [Dart] (que adicionavam métodos ao tipo [String]): aqui são funções comuns;
- linhas 69–75: as iniciais: o texto é dividido por espaços ([split]), os segmentos vazios são removidos, a primeira letra de cada segmento é mantida ([map]) e tudo é reunido novamente;
- linhas 81–84: “2026-10-05” (o formato da API) → uma data. Dividimos a string, convertemos cada segmento em número e construímos a data à meia-noite, no horário local. ATENÇÃO: [new Date('2026-10-05')] lê a data como uma data em Tempo Universal Coordenado (UTC): em um telefone configurado no horário de Nova York, seria 4 de outubro às 20h. Os meses do objeto [Date] do JavaScript são numerados de 0 a 11.
3.9.2. Um pipe personalizado
Um “pipe” formata um valor dentro do template: [{{ value | pipe }}]. O [Angular] fornece cerca de dez deles; você pode escrever os seus:
| // =========================================================================
// src/app/ex09-formatting/initials.pipe.ts - um "pipe" caseiro
// -------------------------------------------------------------------------
// Um pipe formata um valor NO TEMPLATE: {{ name | initials }}.
// É uma classe decorada com @Pipe, cujo método transform recebe o
// valor (e, eventualmente, parâmetros: {{ x | myPipe:p1:p2 }}).
// Um pipe "puro" (o padrão) só é chamado novamente se seu valor de entrada mudar.
// =========================================================================
import { Pipe, PipeTransform } from '@angular/core';
import { initials } from './formatting';
@Pipe({ name: 'initials' })
export class InitialsPipe implements PipeTransform {
transform(text: string): string {
// o pipe simplesmente chama a função de formatting.ts
return initials(text);
}
}
|
- linha 13: um pipe é uma classe decorada por [@Pipe], que fornece o seu nome nos templates: [initials];
- linhas 15–18: seu método [transform] recebe o valor a ser formatado (e, se houver, os parâmetros do pipe: [{{ x | myPipe:p1:p2 }}]) e devolve o resultado. Aqui, ele simplesmente chama a função de [formatting.ts].
Um pipe é “puro” por padrão: o [Angular] só o chama novamente se seu valor de entrada mudar, e guarda o resultado. É isso que o distingue de uma chamada de método no template, que é reavaliada toda vez que a tela é verificada.
3.9.3. A tela
| // =========================================================================
// src/app/ex09-formatting/ex09.page.ts - formatando valores
// -------------------------------------------------------------------------
// Duas formas de formatar um valor:
// - no CÓDIGO: os formatters da API Intl e as funções caseiras
// de formatting.ts (primeira tabela: cada linha mostra um trecho de
// código e o que ele exibe);
// - no TEMPLATE: os "pipes" do Angular, {{ value | pipe:parameters }}
// (segunda tabela, escrita em ex09.page.html). Os pipes date, number,
// currency e percent seguem o idioma da aplicação (LOCALE_ID,
// en-US; as regras francesas são registradas por registerLocaleData em main.ts).
// =========================================================================
import {
CurrencyPipe, DatePipe, DecimalPipe, JsonPipe, KeyValuePipe, PercentPipe, SlicePipe, TitleCasePipe, UpperCasePipe,
} from '@angular/common';
import { Component, computed, signal } from '@angular/core';
import { IonBackButton, IonButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular';
import {
Slot, fullDate, shortDate, integer, euros, timeOnly, timeRange, initials, frenchDay, capitalize,
pattern, percent, relative, toDate,
} from './formatting';
import { InitialsPipe } from './initials.pipe';
const day = '2026-10-05'; // uma data no formato da API do RdvMedecins
const price = 1234.5;
const rate = 0.055;
const name = 'marie pelissier';
const doctor = { title: 'Mme', firstName: 'Marie', lastName: 'PELISSIER' };
const languages = ['TypeScript', 'Angular', 'Ionic', 'Kotlin', 'SQL'];
const 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 },
];
@Component({
selector: 'app-ex09',
imports: [
DatePipe, DecimalPipe, CurrencyPipe, PercentPipe, UpperCasePipe, TitleCasePipe, SlicePipe, JsonPipe, KeyValuePipe,
InitialsPipe, IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonContent, IonButton,
],
templateUrl: './ex09.page.html',
styles: `
/* table-layout: fixed: a largura das colunas é a da primeira linha (55 % para o código) */
table { width: 100%; border-collapse: collapse; font-size: 14px; table-layout: fixed; }
th { text-align: left; padding: 4px; }
th:first-child { width: 55%; }
td { padding: 4px; border-top: 1px solid #ddd; vertical-align: top; }
td.code { font-family: monospace; font-size: 11px; color: #c7254e; word-break: break-all; }
h3 { font-size: 0.95em; font-weight: bold; margin: 16px 0 4px; }
`,
})
export class Ex09Page {
// os dados, lidos pelo template (pipes)
readonly day = day;
readonly price = price;
readonly rate = rate;
readonly name = name;
readonly doctor = doctor;
readonly languages = languages;
readonly slots = slots;
readonly timeRange = timeRange;
readonly now = signal(new Date());
// (código exibido, valor): uma linha da primeira tabela
readonly rows = computed(() => {
const now = this.now();
return [
['shortDate.format(now)', shortDate.format(now)],
['fullDate.format(now)', fullDate.format(now)],
['timeOnly.format(now)', timeOnly.format(now)],
['pattern.format(now)', pattern.format(now)],
['fullDate.format(toDate(day))', fullDate.format(toDate(day))],
['frenchDay.format(toDate(day))', frenchDay.format(toDate(day))],
['now.toISOString()', now.toISOString()],
["relative.format(-3, 'day')", relative.format(-3, 'day')],
['euros.format(price)', euros.format(price)],
['integer.format(price)', integer.format(price)],
['price.toFixed(1)', price.toFixed(1)],
['percent.format(rate)', percent.format(rate)],
['name.toUpperCase()', name.toUpperCase()],
['capitalize(name)', capitalize(name)],
["'APPOINTMENT'.toLowerCase()", 'APPOINTMENT'.toLowerCase()],
["languages.slice(0, 3).join(', ')", languages.slice(0, 3).join(', ')],
['JSON.stringify(doctor)', JSON.stringify(doctor)],
// duas funções em sequência: o resultado da primeira vai para a segunda
['initials(capitalize(name))', initials(capitalize(name))],
];
});
// o pipe keyvalue ordena as entradas na ordem alfabética das chaves;
// esta função de comparação (sempre 0: "igual") mantém a ordem original delas
originalOrder(): number {
return 0;
}
refresh(): void {
this.now.set(new Date());
}
}
|
- linhas 14–16: os pipes do [Angular], no pacote [@angular/common]. Cada um é uma classe, que é importada no componente (linhas 40–41), assim como o pipe personalizado;
- linhas 25–35: os dados a formatar;
- linhas 56–63: os dados lidos pelo template. O template só enxerga os membros da classe: para chamar a função [timeRange] dentro dele, nós a declaramos como um campo (linha 63);
- linha 65: a hora atual, um signal: o botão [Refresh the time] a altera;
- linhas 68–91: o primeiro array: uma lista de pares [displayed code, value], um valor calculado que depende da hora atual;
- linhas 95–97: uma função de comparação para o pipe [keyvalue] (veja abaixo).
| <!-- ======================================================================
ex09.page.html - formatação, no código e no template
====================================================================== -->
<ion-header>
<ion-toolbar color="primary">
<ion-buttons slot="start">
<ion-back-button defaultHref="/" />
</ion-buttons>
<ion-title>Example 09 - formatting</ion-title>
</ion-toolbar>
</ion-header>
<ion-content class="ion-padding">
<!-- primeira tabela: a formatação feita no CÓDIGO (ex09.page.ts) -->
<table>
<tr><th>In the code</th><th>Displayed</th></tr>
@for (row of rows(); track row[0]) {
<tr><td class="code">{{ row[0] }}</td><td>{{ row[1] }}</td></tr>
}
</table>
<!-- segunda tabela: a formatação feita no TEMPLATE, por pipes.
A primeira coluna é o texto da expressão, a segunda seu resultado -->
<h3>In the template: the pipes</h3>
<table>
<tr><th>In the template</th><th>Displayed</th></tr>
<tr><td class="code">now() | date</td><td>{{ now() | date }}</td></tr>
<tr><td class="code">now() | date:'fullDate'</td><td>{{ now() | date:'fullDate' }}</td></tr>
<tr><td class="code">now() | date:'mediumTime'</td><td>{{ now() | date:'mediumTime' }}</td></tr>
<tr>
<td class="code">now() | date:'dd/MM/yyyy HH:mm'</td>
<td>{{ now() | date:'dd/MM/yyyy HH:mm' }}</td>
</tr>
<tr><td class="code">day | date:'fullDate'</td><td>{{ day | date:'fullDate' }}</td></tr>
<tr><td class="code">day | date:'longDate':'':'fr-FR'</td><td>{{ day | date:'longDate':'':'fr-FR' }}</td></tr>
<tr><td class="code">price | currency:'EUR'</td><td>{{ price | currency:'EUR' }}</td></tr>
<tr><td class="code">price | number</td><td>{{ price | number }}</td></tr>
<tr><td class="code">price | number:'1.2-2'</td><td>{{ price | number:'1.2-2' }}</td></tr>
<tr><td class="code">rate | percent:'1.1-1'</td><td>{{ rate | percent:'1.1-1' }}</td></tr>
<tr><td class="code">name | uppercase</td><td>{{ name | uppercase }}</td></tr>
<tr><td class="code">name | titlecase</td><td>{{ name | titlecase }}</td></tr>
<tr><td class="code">(languages | slice:0:3).join(', ')</td><td>{{ (languages | slice:0:3).join(', ') }}</td></tr>
<tr><td class="code">doctor | json</td><td>{{ doctor | json }}</td></tr>
<!-- dois pipes em sequência: o resultado do primeiro vai para o segundo (initials: um pipe caseiro) -->
<tr><td class="code">name | titlecase | initials</td><td>{{ name | titlecase | initials }}</td></tr>
</table>
<h3>Iterating over the entries of an object</h3>
<!-- o pipe keyvalue transforma um objeto em uma lista de pares { key, value } -->
@for (entry of doctor | keyvalue: originalOrder; track entry.key) {
<div>{{ entry.key }} = {{ entry.value }}</div>
}
<h3>A home-made function: timeRange</h3>
@for (c of slots; track $index) {
<div>{{ timeRange(c) }} (start: {{ timeRange(c, 'start') }})</div>
}
<ion-button fill="outline" shape="round" class="ion-margin-top" (click)="refresh()">Refresh the time</ion-button>
</ion-content>
|
- linhas 16–21: o primeiro array: uma linha por par. [row[0]] é o código, [row[1]] é o seu valor;
- linhas 26–47: a segunda tabela, escrita diretamente no template: cada linha mostra uma expressão (como texto) e seu resultado;
- linha 28: [date]: uma data, formatada de acordo com o idioma da aplicação ([LOCALE_ID], [en-US]; as regras do francês são registradas por [registerLocaleData] em [main.ts]). Sem parâmetros, o formato é [mediumDate];
- linhas 29–34: um pipe pode ter parâmetros, separados por [:]: uma forma “pronta” ([fullDate], [mediumTime]...) ou um padrão (['dd/MM/yyyy HH:mm']);
- linhas 35–36: o pipe [date] também aceita uma data no formato ISO (“2026-10-05”), que ele interpreta como uma data local. O terceiro parâmetro (depois do formato e do fuso horário, que aqui está vazio) é o idioma: [fr-FR];
- linhas 37–40: números: um valor monetário ([currency:'EUR']), um número ([number] e [number:'1.2-2']: pelo menos um dígito antes da vírgula decimal, exatamente dois depois), uma porcentagem ([percent]);
- linhas 41–42: texto: em letras maiúsculas, com a primeira letra de cada palavra em maiúscula ([titlecase], o equivalente da nossa função [capitalize]);
- linha 43: [slice] mantém uma parte de um array (ou string): os elementos de 0 a 2;
- linha 44: [json], o objeto em JSON;
- linha 46: pipes em sequência: o resultado do primeiro é passado ao segundo. [initials] é o nosso pipe personalizado;
- linhas 51–53: iterar sobre as entradas de um objeto: o pipe [keyvalue] converte um objeto em um array de tuplas [{ key, value }]. Ele as ordena alfabeticamente pela chave ([firstName], [lastName], [title]); fornecemos a ele uma função de comparação que sempre devolve “igual”, para preservar a ordem original;
- Linha 57: a função personalizada, chamada a partir do template.
A parte superior da página; depois a parte inferior, após pressionar [Refresh the time]:
Para datas, números e valores monetários, a API [Intl] e os pipes do [Angular] cumprem a mesma função que o pacote [intl] do [Flutter]: reconhecem as convenções de cada idioma (separadores, nomes dos meses, ordem dos componentes). Observe, em inglês, a vírgula que separa os milhares (€1,234.50) e a ordem “mês-dia-ano”, enquanto a linha em francês segue as convenções francesas (“5 octobre 2026”). O [Flutter] não tinha um mecanismo próprio de formatação: funções eram chamadas dentro de [build]. O [Angular] oferece os dois: funções no código e pipes no template — reutilizáveis, encadeáveis e com cache.