``` Ambos os bindings `class` e `style` usam uma sintaxe mais direta que se alinha mais proximamente aos atributos HTML padrão. Isso torna seus templates mais fáceis de ler e entender, especialmente para desenvolvedores familiarizados com HTML básico. Além disso, as directives `NgClass` e `NgStyle` incorrem em um custo de desempenho adicional em comparação com a sintaxe de binding `class` e `style` integrada. Para mais detalhes, consulte o [guia de bindings](/guide/templates/binding#css-class-and-style-property-bindings) ### Nomeie event handlers pelo que eles _fazem_, não pelo evento que os dispara Prefira nomear event handlers pela ação que executam em vez do evento que os dispara: ```html ``` Usar nomes significativos como este facilita saber o que um evento faz ao ler o template. Para eventos de teclado, você pode usar os modificadores de evento de tecla do Angular com nomes de handler específicos: ```html

```

Às vezes, a lógica de tratamento de eventos é especialmente longa ou complexa, tornando impraticável declarar um único handler bem nomeado. Nesses casos, não há problema em voltar a um nome como 'handleKeydown' e então delegar a comportamentos mais específicos com base nos detalhes do evento:

```ts
@Component({/* ... */})
class RichText {
  handleKeydown(event: KeyboardEvent) {
    if (event.ctrlKey) {
      if (event.key === 'B') {
        this.activateBold();
      } else if (event.key === 'I') {
        this.activateItalic();
      }
// ...
    }
  }
}
```

### Mantenha métodos de ciclo de vida simples

Evite colocar lógica longa ou complexa dentro de hooks de ciclo de vida como `ngOnInit`. Em vez disso, prefira criar métodos bem nomeados para conter essa lógica e então _chamar esses métodos_ nos seus hooks de ciclo de vida. Nomes de hooks de ciclo de vida descrevem _quando_ eles executam, o que significa que o código dentro não tem um nome significativo que descreva o que o código está fazendo.

```typescript
// PREFIRA
ngOnInit() {
  this.startLogging();
  this.runBackgroundTask();
}

// EVITE
ngOnInit() {
  this.logger.setMode('info');
  this.logger.monitorErrors();
  // ...e todo o resto do código que seria desdobrado desses métodos.
}
```

### Use interfaces de hook de ciclo de vida

O Angular fornece uma interface TypeScript para cada método de ciclo de vida. Ao adicionar um hook de ciclo de vida à sua classe, importe e `implement` essas interfaces para garantir que os métodos sejam nomeados corretamente.

```ts
import {Component, OnInit} from '@angular/core';

@Component({/* ... */})
export class UserProfile implements OnInit {

// A interface `OnInit` garante que este método seja nomeado corretamente.
  ngOnInit() { /* ... */ }
}
```

Components são os principais blocos de construção de aplicações Angular. Cada component representa uma parte de uma página web maior. Organizar uma aplicação em components ajuda a fornecer estrutura ao seu projeto, separando claramente o código em partes específicas que são fáceis de manter e expandir ao longo do tempo.

## Definindo um component

Todo component tem algumas partes principais:

1. Um [decorator](https://www.typescriptlang.org/docs/handbook/decorators.html) `@Component` que contém algumas configurações usadas pelo Angular.
2. Um template HTML que controla o que é renderizado no DOM.
3. Um [seletor CSS](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors) que define como o component é usado no HTML.
4. Uma classe TypeScript com comportamentos, como lidar com entrada do usuário ou fazer requisições para um servidor.

Aqui está um exemplo simplificado de um component `UserProfile`.

```typescript
// user-profile.ts
@Component({
  selector: 'user-profile',
  template: `
    <h1>User profile</h1>
    <p>This is the user profile page</p>
  `,
})
export class UserProfile { /* Your component code goes here */ }
```

O decorator `@Component` também aceita opcionalmente uma propriedade `styles` para qualquer CSS que você queira aplicar ao seu template:

```typescript
// user-profile.ts
@Component({
  selector: 'user-profile',
  template: `
    <h1>User profile</h1>
    <p>This is the user profile page</p>
  `,
  styles: `h1 { font-size: 3em; } `,
})
export class UserProfile { /* Your component code goes here */ }
```

### Separando HTML e CSS em arquivos separados

Você pode definir o HTML e CSS de um component em arquivos separados usando `templateUrl` e `styleUrl`:

```typescript
// user-profile.ts
@Component({
  selector: 'user-profile',
  templateUrl: 'user-profile.html',
  styleUrl: 'user-profile.css',
})
export class UserProfile {
  // Component behavior is defined in here
}
```

```html

<h1>User profile</h1>
<p>This is the user profile page</p>
```

```css
/* user-profile.css */
h1 {
  font-size: 3em;
}
```

## Usando components

Você constrói uma aplicação compondo múltiplos components juntos. Por exemplo, se você está construindo uma página de perfil de usuário, você pode dividir a página em vários components assim:

```mermaid
flowchart TD
    A[UserProfile]-->B
    A-->C
    B[UserBiography]-->D
    C[ProfilePhoto]
    D[UserAddress]
```

Aqui, o component `UserProfile` usa vários outros components para produzir a página final.

Para importar e usar um component, você precisa:

1. No arquivo TypeScript do seu component, adicione uma declaração `import` para o component que você quer usar.
2. No seu decorator `@Component`, adicione uma entrada no array `imports` para o component que você quer usar.
3. No template do seu component, adicione um elemento que corresponda ao seletor do component que você quer usar.

Aqui está um exemplo de um component `UserProfile` importando um component `ProfilePhoto`:

```typescript
// user-profile.ts
import {ProfilePhoto} from 'profile-photo.ts';

@Component({
  selector: 'user-profile',
  imports: [ProfilePhoto],
  template: `
    <h1>User profile</h1>
    <profile-photo />
    <p>This is the user profile page</p>
  `,
})
export class UserProfile {
  // Component behavior is defined in here
}
```

DICA: Quer saber mais sobre components do Angular? Veja o [guia detalhado de Components](guide/components) para todos os detalhes.

## Próximo Passo

Agora que você sabe como components funcionam no Angular, é hora de aprender como adicionamos e gerenciamos dados dinâmicos na nossa aplicação.

# Seletores de components

TIP: Este guia assume que você já leu o [Guia de Fundamentos](essentials). Leia-o primeiro se você é novo no Angular.

Todo component define
um [seletor CSS](https://developer.mozilla.org/docs/Web/CSS/CSS_selectors) que determina como
o component é usado:

```typescript
@Component({
  selector: 'profile-photo',
  ...
})
export class ProfilePhoto { }
```
Você usa um component criando um elemento HTML correspondente nos templates de _outros_ components:

```typescript
@Component({
  template: `
    <profile-photo />
    <button>Upload a new profile photo</button>`,
  ...,
})
export class UserProfile { }
```
**O Angular corresponde seletores estaticamente em tempo de compilação**. Alterar o DOM em tempo de execução, seja via
bindings do Angular ou com APIs do DOM, não afeta os components renderizados.

**Um elemento pode corresponder exatamente a um seletor de component.** Se múltiplos seletores de component corresponderem a um
único elemento, o Angular reporta um erro.

**Seletores de components são case-sensitive.**

## Tipos de seletores

O Angular suporta um subconjunto limitado
de [tipos básicos de seletor CSS](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) em
seletores de components:

| **Tipo de seletor**       | **Descrição**                                                                                                             | **Exemplos**                  |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| Type selector             | Corresponde elementos baseado em seu nome de tag HTML, ou nome de nó.                                                     | `profile-photo`               |
| Attribute selector        | Corresponde elementos baseado na presença de um atributo HTML e, opcionalmente, um valor exato para aquele atributo.      | `[dropzone]` `[type="reset"]` |
| Class selector            | Corresponde elementos baseado na presença de uma classe CSS.                                                              | `.menu-item`                  |

Para valores de atributo, o Angular suporta correspondência de um valor de atributo exato com o operador igual (`=`).
O Angular não suporta outros operadores de valor de atributo.

Seletores de components do Angular não suportam combinadores, incluindo
o [combinador descendente](https://developer.mozilla.org/docs/Web/CSS/Descendant_combinator)
ou [combinador filho](https://developer.mozilla.org/docs/Web/CSS/Child_combinator).

Seletores de components do Angular não suportam
especificar [namespaces](https://developer.mozilla.org/docs/Web/SVG/Namespaces_Crash_Course).

### A pseudo-classe `:not`

O Angular suporta [a pseudo-classe `:not`](https://developer.mozilla.org/docs/Web/CSS/:not).
Você pode anexar esta pseudo-classe a qualquer outro seletor para restringir quais elementos o
seletor de um component corresponde. Por exemplo, você poderia definir um seletor de atributo `[dropzone]` e prevenir
correspondência com elementos `textarea`:

```typescript
@Component({
  selector: '[dropzone]:not(textarea)',
  ...
})
export class DropZone { }
```
O Angular não suporta nenhuma outra pseudo-classe ou pseudo-elemento em seletores de components.

### Combinando seletores

Você pode combinar múltiplos seletores concatenando-os. Por exemplo, você pode corresponder elementos `<button>`
que especificam `type="reset"`:

```typescript
@Component({
  selector: 'button[type="reset"]',
  ...
})
export class ResetButton { }
```
Você também pode definir múltiplos seletores com uma lista separada por vírgulas:

```typescript
@Component({
  selector: 'drop-zone, [dropzone]',
  ...
})
export class DropZone { }
```
O Angular cria um component para cada elemento que corresponde a _qualquer_ um dos seletores na lista.

## Escolhendo um seletor

A grande maioria dos components deve usar um nome de elemento personalizado como seu seletor. Todos os nomes de
elementos personalizados devem incluir um hífen conforme descrito
pela [especificação HTML](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name).
Por padrão, o Angular reporta um erro se encontrar um nome de tag personalizado que não corresponde a nenhum
component disponível, prevenindo bugs devido a nomes de components digitados incorretamente.

Veja [Configuração avançada de components](guide/components/advanced-configuration) para detalhes sobre
usar [custom elements nativos](https://developer.mozilla.org/docs/Web/Web_Components) em
templates Angular.

### Prefixos de seletor

O time do Angular recomenda usar um prefixo curto e consistente para todos os components personalizados
definidos dentro do seu projeto. Por exemplo, se você fosse construir o YouTube com Angular, você poderia
prefixar seus components com `yt-`, com components como `yt-menu`, `yt-player`, etc. Nomear
seus seletores dessa forma deixa imediatamente claro de onde um component particular vem. Por
padrão, o Angular CLI usa `app-`.

IMPORTANT: O Angular usa o prefixo de seletor `ng` para suas próprias APIs do framework. Nunca use `ng` como prefixo de seletor para seus próprios components personalizados.

### Quando usar um attribute selector

Você deve considerar um attribute selector quando quiser criar um component em um elemento
nativo padrão. Por exemplo, se você quiser criar um component de botão personalizado, você pode aproveitar o
elemento `<button>` padrão usando um attribute selector:

```typescript
@Component({
  selector: 'button[yt-upload]',
   ...
})
export class YouTubeUploadButton { }
```
Esta abordagem permite que consumidores do component usem diretamente todas as APIs padrão do elemento
sem trabalho extra. Isso é especialmente valioso para atributos ARIA como `aria-label`.

O Angular não reporta erros quando encontra atributos personalizados que não correspondem a um
component disponível. Ao usar components com attribute selectors, consumidores podem esquecer de importar o
component ou seu NgModule, resultando em o component não renderizar.
Veja [Importando e usando components](guide/components/importing) para mais informações.

Components que definem attribute selectors devem usar atributos em minúsculas, separados por hífen (dash-case). Você pode
seguir a mesma recomendação de prefixação descrita acima.

# Estilizando components

TIP: Este guia assume que você já leu o [Guia Essencial](essentials). Leia-o primeiro se você é novo no Angular.

Components podem opcionalmente incluir estilos CSS que se aplicam ao DOM daquele component:

```typescript
@Component({
  selector: 'profile-photo',
  template: `<img src="profile-photo.jpg" alt="Your profile photo">`,
  styles: ` img { border-radius: 50%; } `,
})
export class ProfilePhoto { }
```
Você também pode optar por escrever seus estilos em arquivos separados:

```typescript
@Component({
  selector: 'profile-photo',
  templateUrl: 'profile-photo.html',
  styleUrl: 'profile-photo.css',
})
export class ProfilePhoto { }
```
Quando o Angular compila seu component, esses estilos são emitidos com a saída JavaScript do seu component. Isso significa que os estilos do component participam do sistema de módulos JavaScript. Quando você renderiza um component Angular, o framework inclui automaticamente seus estilos associados, mesmo ao fazer lazy-loading de um component.

O Angular funciona com qualquer ferramenta que gera CSS, incluindo [Sass](https://sass-lang.com), [less](https://lesscss.org) e [stylus](https://stylus-lang.com).

## Escopo de estilos

Cada component tem uma configuração de **view encapsulation** que determina como o framework define o escopo dos estilos de um component. Existem quatro modos de view encapsulation: `Emulated`, `ShadowDom`, `ExperimentalIsolatedShadowDom` e `None`. Você pode especificar o modo no decorator `@Component`:

```typescript
@Component({
  ...,
  encapsulation: ViewEncapsulation.None,
})
export class ProfilePhoto { }
```
### ViewEncapsulation.Emulated

Por padrão, o Angular usa encapsulation emulado para que os estilos de um component se apliquem apenas aos elementos definidos no template daquele component. Neste modo, o framework gera um atributo HTML único para cada instância de component, adiciona esse atributo aos elementos no template do component e insere esse atributo nos seletores CSS definidos nos estilos do seu component.

Este modo garante que os estilos de um component não vazem e afetem outros components. No entanto, estilos globais definidos fora de um component ainda podem afetar elementos dentro de um component com encapsulation emulado.

No modo emulado, o Angular suporta a pseudo-classe [`:host`](https://developer.mozilla.org/docs/Web/CSS/:host). Embora a pseudo-classe [`:host-context()`](https://developer.mozilla.org/docs/Web/CSS/:host-context) esteja depreciada em navegadores modernos, o compilador do Angular fornece suporte completo para ela. Ambas as pseudo-classes podem ser usadas sem depender do [Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM) nativo. Durante a compilação, o framework transforma essas pseudo-classes em atributos, então ele não está em conformidade com as regras dessas pseudo-classes nativas em tempo de execução (por exemplo, compatibilidade do navegador, especificidade). O modo de encapsulation emulado do Angular não suporta nenhuma outra pseudo-classe relacionada ao Shadow DOM, como `::shadow` ou `::part`.

#### `::ng-deep`

O modo de encapsulation emulado do Angular suporta uma pseudo-classe customizada, `::ng-deep`. Aplicar esta pseudo-classe a uma regra CSS desabilita o encapsulation para aquela regra, efetivamente transformando-a em um estilo global. **O time do Angular desencoraja fortemente o novo uso de `::ng-deep`**. Essas APIs permanecem exclusivamente para compatibilidade retroativa.

### ViewEncapsulation.ShadowDom

Este modo define o escopo dos estilos dentro de um component usando [a API padrão web Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM). Ao ativar este modo, o Angular anexa uma shadow root ao host element do component e renderiza o template e os estilos do component na shadow tree correspondente.

Estilos dentro da shadow tree não podem afetar elementos fora daquela shadow tree.

Habilitar o encapsulation `ShadowDom`, no entanto, impacta mais do que o escopo de estilos. Renderizar o component em uma shadow tree afeta a propagação de eventos, interação com [a API `<slot>`](https://developer.mozilla.org/docs/Web/Web_Components/Using_templates_and_slots), e como as ferramentas de desenvolvedor do navegador exibem elementos. Sempre entenda as implicações completas do uso de Shadow DOM em sua aplicação antes de ativar esta opção.

### ViewEncapsulation.ExperimentalIsolatedShadowDom

Comporta-se como acima, exceto que este modo garante estritamente que _apenas_ os estilos daquele component se aplicam aos elementos no template do component. Estilos globais não podem afetar elementos em uma shadow tree e estilos dentro da shadow tree não podem afetar elementos fora daquela shadow tree.

### ViewEncapsulation.None

Este modo desabilita todo o encapsulation de estilos para o component. Quaisquer estilos associados ao component se comportam como estilos globais.

NOTE: Nos modos `Emulated` e `ShadowDom`, o Angular não garante 100% que os estilos do seu component sempre sobrescreverão estilos vindos de fora dele. Assume-se que esses estilos têm a mesma especificidade que os estilos do seu component em caso de colisão.

## Definindo estilos em templates

Você pode usar o elemento `<style>` no template de um component para definir estilos adicionais. O modo de view encapsulation do component se aplica aos estilos definidos desta forma.

O Angular não suporta bindings dentro de elementos style.

## Referenciando arquivos de estilos externos

Templates de components podem usar [o elemento `<link>`](https://developer.mozilla.org/docs/Web/HTML/Element/link) para referenciar arquivos CSS. Além disso, seu CSS pode usar [a at-rule `@import`](https://developer.mozilla.org/docs/Web/CSS/@import) para referenciar arquivos CSS. O Angular trata essas referências como estilos _externos_. Estilos externos não são afetados pelo view encapsulation emulado.

# Aceitando dados com propriedades de input

TIP: Este guia pressupõe que você já leu o [Guia de Fundamentos](essentials). Leia-o primeiro se você é novo no Angular.

TIP: Se você está familiarizado com outros frameworks web, propriedades de input são similares a _props_.

Quando você usa um component, você comumente quer passar alguns dados para ele. Um component especifica os dados que aceita declarando **inputs**:

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

@Component({/_..._/})
export class CustomSlider {
// Declare an input named 'value' with a default value of zero.
value = input(0);
}
```
Isso permite vincular à propriedade em um template:

```html
<custom-slider [value]="50" />
```

Se um input tem um valor padrão, o TypeScript infere o tipo a partir do valor padrão:

```ts
@Component({/*...*/})
export class CustomSlider {
  // TypeScript infers that this input is a number, returning InputSignal<number>.
  value = input(0);
}
```

Você pode declarar explicitamente um tipo para o input especificando um parâmetro genérico para a função.

Se um input sem um valor padrão não for definido, seu valor é `undefined`:

```ts
@Component({/*...*/})
export class CustomSlider {
  // Produces an InputSignal<number | undefined> because `value` may not be set.
  value = input<number>();
}
```

**O Angular registra inputs estaticamente em tempo de compilação**. Inputs não podem ser adicionados ou removidos em tempo de execução.

A função `input` tem significado especial para o compilador do Angular. **Você pode chamar exclusivamente `input` em inicializadores de propriedade de component e directive.**

Ao estender uma classe de component, **inputs são herdados pela classe filha.**

**Nomes de input são sensíveis a maiúsculas e minúsculas.**

## Lendo inputs

A função `input` retorna um `InputSignal`. Você pode ler o valor chamando o signal:

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

@Component({/_..._/})
export class CustomSlider {
// Declare an input named 'value' with a default value of zero.
value = input(0);

// Create a computed expression that reads the value input
label = computed(() => `The slider's value is ${this.value()}`);
}
```
Signals criados pela função `input` são somente leitura.

## Inputs obrigatórios

Você pode declarar que um input é `required` (obrigatório) chamando `input.required` em vez de `input`:

```ts
@Component({/*...*/})
export class CustomSlider {
  // Declare a required input named value. Returns an `InputSignal<number>`.
  value = input.required<number>();
}
```
O Angular garante que inputs obrigatórios _devem_ ser definidos quando o component é usado em um template. Se você tentar usar um component sem especificar todos os seus inputs obrigatórios, o Angular reporta um erro em tempo de build.

Inputs obrigatórios não incluem automaticamente `undefined` no parâmetro genérico do `InputSignal` retornado.

## Configurando inputs

A função `input` aceita um objeto de configuração como segundo parâmetro que permite alterar a forma como o input funciona.

### Transformações de input

Você pode especificar uma função `transform` para alterar o valor de um input quando ele é definido pelo Angular.

```ts
@Component({
  selector: 'custom-slider',
  /*...*/
})
export class CustomSlider {
  label = input('', {transform: trimString});
}

function trimString(value: string | undefined): string {
return value?.trim() ?? '';
}
```
```html
<custom-slider [label]="systemVolume" />
```

No exemplo acima, sempre que o valor de `systemVolume` muda, o Angular executa `trimString` e define `label` para o resultado.

O caso de uso mais comum para transformações de input é aceitar uma gama mais ampla de tipos de valor em templates, frequentemente incluindo `null` e `undefined`.

**Funções de transformação de input devem ser estaticamente analisáveis em tempo de build.** Você não pode definir funções de transformação condicionalmente ou como resultado de uma avaliação de expressão.

**Funções de transformação de input devem sempre ser [funções puras](https://en.wikipedia.org/wiki/Pure_function).** Depender de estado fora da função de transformação pode levar a comportamento imprevisível.

#### Verificação de tipo

Quando você especifica uma transformação de input, o tipo do parâmetro da função de transformação determina os tipos de valores que podem ser definidos para o input em um template.

```ts
@Component({/*...*/})
export class CustomSlider {
  widthPx = input('', {transform: appendPx});
}

function appendPx(value: number): string {
return `${value}px`;
}
```
No exemplo acima, o input `widthPx` aceita um `number` enquanto a propriedade `InputSignal` retorna uma `string`.

#### Transformações integradas

O Angular inclui duas funções de transformação integradas para os dois cenários mais comuns: coerção de valores para booleano e números.

```ts
import {Component, input, booleanAttribute, numberAttribute} from '@angular/core';

@Component({/_..._/})
export class CustomSlider {
disabled = input(false, {transform: booleanAttribute});
value = input(0, {transform: numberAttribute});
}
```
`booleanAttribute` imita o comportamento de [atributos booleanos](https://developer.mozilla.org/docs/Glossary/Boolean/HTML) HTML padrão, onde a _presença_ do atributo indica um valor "verdadeiro". No entanto, o `booleanAttribute` do Angular trata a string literal `"false"` como o booleano `false`.

`numberAttribute` tenta analisar o valor fornecido para um número, produzindo `NaN` se a análise falhar.

### Aliases de input

Você pode especificar a opção `alias` para alterar o nome de um input em templates.

```ts
@Component({/*...*/})
export class CustomSlider {
  value = input(0, {alias: 'sliderValue'});
}
```
```html
<custom-slider [sliderValue]="50" />
```

Este alias não afeta o uso da propriedade em código TypeScript.

Embora você deva geralmente evitar criar aliases para inputs de components, este recurso pode ser útil para renomear propriedades enquanto preserva um alias para o nome original ou para evitar colisões com o nome de propriedades de elementos DOM nativos.

## Model inputs

**Model inputs** são um tipo especial de input que permite que um component propague novos valores de volta para seu component pai.

Ao criar um component, você pode definir um model input de forma semelhante a como você cria um input padrão.

Ambos os tipos de input permitem que alguém vincule um valor à propriedade. No entanto, **model inputs permitem que o autor do component escreva valores na propriedade**. Se a propriedade estiver vinculada com um binding bidirecional, o novo valor propaga para aquele binding.

```typescript
@Component({ /* ... */})
export class CustomSlider {
  // Define a model input named "value".
  value = model(0);

increment() {
    // Update the model input with a new value, propagating the value to any bindings.
    this.value.update(oldValue => oldValue + 10);
  }
}

@Component({
  /* ... */
  // Using the two-way binding syntax means that any changes to the slider's
  // value automatically propagate back to the `volume` signal.
  // Note that this binding uses the signal *instance*, not the signal value.
  template: `<custom-slider [(value)]="volume" />`,
})
export class MediaControls {
  // Create a writable signal for the `volume` local state.
  volume = signal(0);
}
```

No exemplo acima, o `CustomSlider` pode escrever valores em seu model input `value`, que então propaga esses valores de volta para o signal `volume` em `MediaControls`. Este binding mantém os valores de `value` e `volume` sincronizados. Observe que o binding passa a instância do signal `volume`, não o _valor_ do signal.

Em outros aspectos, model inputs funcionam de forma semelhante a inputs padrão. Você pode ler o valor chamando a função signal, incluindo em contextos reativos como `computed` e `effect`.

Consulte [Binding bidirecional](guide/templates/two-way-binding) para mais detalhes sobre binding bidirecional em templates.

### Binding bidirecional com propriedades simples

Você pode vincular uma propriedade JavaScript simples a um model input.

```typescript
@Component({
  /* ... */
  // `value` is a model input.
  // The parenthesis-inside-square-brackets syntax (aka "banana-in-a-box") creates a two-way binding
  template: '<custom-slider [(value)]="volume" />',
})
export class MediaControls {
  protected volume = 0;
}
```

No exemplo acima, o `CustomSlider` pode escrever valores em seu model input `value`, que então propaga esses valores de volta para a propriedade `volume` em `MediaControls`. Este binding mantém os valores de `value` e `volume` sincronizados.

### Eventos `change` implícitos

Quando você declara um model input em um component ou directive, o Angular automaticamente cria um [output](guide/components/outputs) correspondente para aquele model. O nome do output é o nome do model input sufixado com "Change".

```ts
@Directive({ /* ... */ })
export class CustomCheckbox {
  // This automatically creates an output named "checkedChange".
  // Can be subscribed to using `(checkedChange)="handler()"` in the template.
  checked = model(false);
}
```

O Angular emite este evento de mudança sempre que você escreve um novo valor no model input chamando seus métodos `set` ou `update`.

Consulte [Eventos personalizados com outputs](guide/components/outputs) para mais detalhes sobre outputs.

### Personalizando model inputs

Você pode marcar um model input como obrigatório ou fornecer um alias da mesma forma que um [input padrão](guide/signals/inputs).

Model inputs não suportam transformações de input.

### Quando usar model inputs

Use model inputs quando você quiser que um component suporte binding bidirecional. Isso é tipicamente apropriado quando um component existe para modificar um valor com base em interação do usuário. Mais comumente, controles de formulário personalizados, como um seletor de data ou combobox, devem usar model inputs para seu valor principal.

## Escolhendo nomes de input

Evite escolher nomes de input que colidam com propriedades em elementos DOM como HTMLElement. Colisões de nomes introduzem confusão sobre se a propriedade vinculada pertence ao component ou ao elemento DOM.

Evite adicionar prefixos para inputs de component como você faria com seletores de component. Como um determinado elemento pode hospedar apenas um component, quaisquer propriedades personalizadas podem ser assumidas como pertencentes ao component.

## Declarando inputs com o decorator `@Input`

TIP: Embora a equipe do Angular recomende usar a função `input` baseada em signal para novos projetos, a API `@Input` original baseada em decorator continua totalmente suportada.

Você pode alternativamente declarar inputs de component adicionando o decorator `@Input` a uma propriedade:

```ts
@Component({...})
export class CustomSlider {
  @Input() value = 0;
}
```
O binding a um input é o mesmo em inputs baseados em signal e baseados em decorator:

```html
<custom-slider [value]="50" />
```

### Personalizando inputs baseados em decorator

O decorator `@Input` aceita um objeto de configuração que permite alterar a forma como o input funciona.

#### Inputs obrigatórios

Você pode especificar a opção `required` para garantir que um determinado input sempre tenha um valor.

```ts
@Component({...})
export class CustomSlider {
  @Input({required: true}) value = 0;
}
```
Se você tentar usar um component sem especificar todos os seus inputs obrigatórios, o Angular reporta um erro em tempo de build.

#### Transformações de input

Você pode especificar uma função `transform` para alterar o valor de um input quando ele é definido pelo Angular. Esta função de transformação funciona de forma idêntica às funções de transformação para inputs baseados em signal descritas acima.

```ts
@Component({
  selector: 'custom-slider',
  ...
})
export class CustomSlider {
  @Input({transform: trimString}) label = '';
}

function trimString(value: string | undefined) { return value?.trim() ?? ''; }
```
#### Aliases de input

Você pode especificar a opção `alias` para alterar o nome de um input em templates.

```ts
@Component({...})
export class CustomSlider {
  @Input({alias: 'sliderValue'}) value = 0;
}
```
```html
<custom-slider [sliderValue]="50" />
```

O decorator `@Input` também aceita o alias como seu primeiro parâmetro no lugar do objeto de configuração.

Aliases de input funcionam da mesma forma que para inputs baseados em signal descritos acima.

### Inputs com getters e setters

Ao usar inputs baseados em decorator, uma propriedade implementada com getter e setter pode ser um input:

```ts
export class CustomSlider {
  @Input()
  get value(): number {
    return this.internalValue;
  }

set value(newValue: number) { this.internalValue = newValue; }

private internalValue = 0;
}
```

Você pode até criar um input _somente escrita_ definindo apenas um setter público:

```ts
export class CustomSlider {
  @Input()
  set value(newValue: number) {
    this.internalValue = newValue;
  }

private internalValue = 0;
}
```

**Prefira usar transformações de input em vez de getters e setters** se possível.

Evite getters e setters complexos ou custosos. O Angular pode invocar o setter de um input múltiplas vezes, o que pode impactar negativamente o desempenho da aplicação se o setter executar quaisquer comportamentos custosos, como manipulação do DOM.

## Especificar inputs no decorator `@Component`

Além do decorator `@Input`, você também pode especificar os inputs de um component com a propriedade `inputs` no decorator `@Component`. Isso pode ser útil quando um component herda uma propriedade de uma classe base:

```ts
// `CustomSlider` inherits the `disabled` property from `BaseSlider`.
@Component({
  ...,
  inputs: ['disabled'],
})
export class CustomSlider extends BaseSlider { }
```
Você pode adicionalmente especificar um alias de input na lista `inputs` colocando o alias após dois pontos na string:

```ts
// `CustomSlider` inherits the `disabled` property from `BaseSlider`.
@Component({
  ...,
  inputs: ['disabled: sliderDisabled'],
})
export class CustomSlider extends BaseSlider { }
```

# Eventos personalizados com outputs

TIP: Este guia pressupõe que você já leu o [Guia de Fundamentos](essentials). Leia-o primeiro se você é novo no Angular.

Components Angular podem definir eventos personalizados atribuindo uma propriedade à função `output`:

```ts
@Component({/*...*/})
export class ExpandablePanel {
  panelClosed = output<void>();
}
```
```html
<expandable-panel (panelClosed)="savePanelState()" />
```

A função `output` retorna um `OutputEmitterRef`. Você pode emitir um evento chamando o método `emit` no `OutputEmitterRef`:

```ts
this.panelClosed.emit();
```

O Angular se refere a propriedades inicializadas com a função `output` como **outputs**. Você pode usar outputs para disparar eventos personalizados, semelhantes a eventos nativos do navegador como `click`.

**Eventos personalizados do Angular não propagam para cima no DOM**.

**Nomes de output são sensíveis a maiúsculas e minúsculas.**

Ao estender uma classe de component, **outputs são herdados pela classe filha.**

A função `output` tem significado especial para o compilador do Angular. **Você pode chamar exclusivamente `output` em inicializadores de propriedade de component e directive.**

## Emitindo dados de evento

Você pode passar dados de evento ao chamar `emit`:

```ts
// You can emit primitive values.
this.valueChanged.emit(7);

// You can emit custom event objects
this.thumbDropped.emit({
  pointerX: 123,
  pointerY: 456,
})
```

Ao definir um event listener em um template, você pode acessar os dados do evento a partir da variável `$event`:

```html
<custom-slider (valueChanged)="logValue($event)" />
```

Receba os dados do evento no component pai:

```ts
@Component({
 /*...*/
})
export class App {
  logValue(value: number) {
    ...
  }
}

```

## Personalizando nomes de output

A função `output` aceita um parâmetro que permite especificar um nome diferente para o evento em um template:

```ts
@Component({/*...*/})
export class CustomSlider {
  changed = output({alias: 'valueChanged'});
}
```

```html
<custom-slider (valueChanged)="saveVolume()" />
```

Este alias não afeta o uso da propriedade em código TypeScript.

Embora você deva geralmente evitar criar aliases para outputs de components, este recurso pode ser útil para renomear propriedades enquanto preserva um alias para o nome original ou para evitar colisões com o nome de eventos DOM nativos.

## Assinando outputs programaticamente

Ao criar um component dinamicamente, você pode programaticamente assinar eventos de output da instância do component. O tipo `OutputRef` inclui um método `subscribe`:

```ts
const someComponentRef: ComponentRef<SomeComponent> = viewContainerRef.createComponent(/*...*/);

someComponentRef.instance.someEventProperty.subscribe(eventData => {
  console.log(eventData);
});
```

O Angular automaticamente limpa as assinaturas de eventos quando destrói components com assinantes. Alternativamente, você pode cancelar manualmente a assinatura de um evento. A função `subscribe` retorna um `OutputRefSubscription` com um método `unsubscribe`:

```ts
const eventSubscription = someComponent.someEventProperty.subscribe(eventData => {
  console.log(eventData);
});

// ...

eventSubscription.unsubscribe();
```

## Escolhendo nomes de evento

Evite escolher nomes de output que colidam com eventos em elementos DOM como HTMLElement. Colisões de nomes introduzem confusão sobre se a propriedade vinculada pertence ao component ou ao elemento DOM.

Evite adicionar prefixos para outputs de component como você faria com seletores de component. Como um determinado elemento pode hospedar apenas um component, quaisquer propriedades personalizadas podem ser assumidas como pertencentes ao component.

Sempre use nomes de output em [camelCase](https://en.wikipedia.org/wiki/Camel_case). Evite prefixar nomes de output com "on".

## Usando outputs com RxJS

Consulte [Interoperabilidade RxJS com outputs de component e directive](ecosystem/rxjs-interop/output-interop) para detalhes sobre interoperabilidade entre outputs e RxJS.

## Declarando outputs com o decorator `@Output`

TIP: Embora a equipe do Angular recomende usar a função `output` para novos projetos, a API `@Output` original baseada em decorator continua totalmente suportada.

Você pode alternativamente definir eventos personalizados atribuindo uma propriedade a um novo `EventEmitter` e adicionando o decorator `@Output`:

```ts
@Component({/*...*/})
export class ExpandablePanel {
  @Output() panelClosed = new EventEmitter<void>();
}
```

Você pode emitir um evento chamando o método `emit` no `EventEmitter`.

### Aliases com o decorator `@Output`

O decorator `@Output` aceita um parâmetro que permite especificar um nome diferente para o evento em um template:

```ts
@Component({/*...*/})
export class CustomSlider {
  @Output('valueChanged') changed = new EventEmitter<number>();
}
```

```html
<custom-slider (valueChanged)="saveVolume()" />
```

Este alias não afeta o uso da propriedade em código TypeScript.

## Especificar outputs no decorator `@Component`

Além do decorator `@Output`, você também pode especificar os outputs de um component com a propriedade `outputs` no decorator `@Component`. Isso pode ser útil quando um component herda uma propriedade de uma classe base:

```ts
// `CustomSlider` inherits the `valueChanged` property from `BaseSlider`.
@Component({
  /*...*/
  outputs: ['valueChanged'],
})
export class CustomSlider extends BaseSlider {}
```

Você pode adicionalmente especificar um alias de output na lista `outputs` colocando o alias após dois pontos na string:

```ts
// `CustomSlider` inherits the `valueChanged` property from `BaseSlider`.
@Component({
  /*...*/
  outputs: ['valueChanged: volumeChanged'],
})
export class CustomSlider extends BaseSlider {}
```

# Projeção de conteúdo com ng-content

TIP: Este guia pressupõe que você já leu o [Guia de Fundamentos](essentials). Leia-o primeiro se você é novo no Angular.

Frequentemente você precisa criar components que atuam como containers para diferentes tipos de conteúdo. Por exemplo, você pode querer criar um component de card personalizado:

```typescript
@Component({
  selector: 'custom-card',
  template: '<div class="card-shadow">  </div>',
})
export class CustomCard {/* ... */}
```

**Você pode usar o elemento `<ng-content>` como um espaço reservado para marcar onde o conteúdo deve ir**:

```typescript
@Component({
  selector: 'custom-card',
  template: '<div class="card-shadow"> <ng-content/> </div>',
})
export class CustomCard {/* ... */}
```

TIP: `<ng-content>` funciona de forma semelhante ao [elemento nativo `<slot>`](https://developer.mozilla.org/docs/Web/HTML/Element/slot), mas com algumas funcionalidades específicas do Angular.

Quando você usa um component com `<ng-content>`, quaisquer filhos do elemento host do component são renderizados, ou **projetados**, no local daquele `<ng-content>`:

```typescript
// Component source
@Component({
  selector: 'custom-card',
  template: `
    <div class="card-shadow">
      <ng-content />
    </div>
  `,
})
export class CustomCard {/* ... */}
```

```html

<custom-card>
  <p>This is the projected content</p>
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <p>This is the projected content</p>
  </div>
</custom-card>
```

O Angular se refere a quaisquer filhos de um component passados desta forma como o **conteúdo** daquele component. Isso é distinto da **view** do component, que se refere aos elementos definidos no template do component.

**O elemento `<ng-content>` não é um component nem um elemento DOM**. Em vez disso, é um espaço reservado especial que diz ao Angular onde renderizar o conteúdo. O compilador do Angular processa todos os elementos `<ng-content>` em tempo de build. Você não pode inserir, remover ou modificar `<ng-content>` em tempo de execução. Você não pode adicionar directives, estilos ou atributos arbitrários ao `<ng-content>`.

IMPORTANT: Você não deve incluir condicionalmente `<ng-content>` com `@if`, `@for` ou `@switch`. O Angular sempre instancia e cria nós DOM para conteúdo renderizado em um espaço reservado `<ng-content>`, mesmo se aquele espaço reservado `<ng-content>` estiver oculto. Para renderização condicional de conteúdo de component, consulte [Fragmentos de template](api/core/ng-template).

## Múltiplos espaços reservados de conteúdo

O Angular suporta projetar múltiplos elementos diferentes em diferentes espaços reservados `<ng-content>` com base em seletor CSS. Expandindo o exemplo do card acima, você poderia criar dois espaços reservados para um título de card e um corpo de card usando o atributo `select`:

```typescript
@Component({
  selector: 'card-title',
  template: `<ng-content>card-title</ng-content>`,
})
export class CardTitle {}

@Component({
  selector: 'card-body',
  template: `<ng-content>card-body</ng-content>`,
})
export class CardBody {}
```

```typescript

Component({
  selector: 'custom-card',
  template: `
  <div class="card-shadow">
    <ng-content select="card-title"></ng-content>
    <div class="card-divider"></div>
    <ng-content select="card-body"></ng-content>
  </div>
  `,
})
export class CustomCard {}
```

```typescript

@Component({
  selector: 'app-root',
  imports: [CustomCard, CardTitle, CardBody],
  template: `
    <custom-card>
      <card-title>Hello</card-title>
      <card-body>Welcome to the example</card-body>
    </custom-card>
`,
})
export class App {}
```

```html

<custom-card>
  <div class="card-shadow">
    <card-title>Hello</card-title>
    <div class="card-divider"></div>
    <card-body>Welcome to the example</card-body>
  </div>
</custom-card>
```

O espaço reservado `<ng-content>` suporta os mesmos seletores CSS que os [seletores de components](guide/components/selectors).

Se você incluir um ou mais espaços reservados `<ng-content>` com um atributo `select` e um espaço reservado `<ng-content>` sem um atributo `select`, o último captura todos os elementos que não corresponderam a um atributo `select`:

```html

<div class="card-shadow">
  <ng-content select="card-title"></ng-content>
  <div class="card-divider"></div>
  
  <ng-content></ng-content>
</div>
```

```html

<custom-card>
  <card-title>Hello</card-title>
  <img src="..." />
  <p>Welcome to the example</p>
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <card-title>Hello</card-title>
    <div class="card-divider"></div>
    <img src="..." />
    <p>Welcome to the example</p>
  </div>
</custom-card>
```

Se um component não incluir um espaço reservado `<ng-content>` sem um atributo `select`, quaisquer elementos que não correspondam a um dos espaços reservados do component não serão renderizados no DOM.

## Conteúdo de fallback

O Angular pode mostrar _conteúdo de fallback_ para um espaço reservado `<ng-content>` de um component se aquele component não tiver nenhum conteúdo filho correspondente. Você pode especificar o conteúdo de fallback adicionando conteúdo filho ao próprio elemento `<ng-content>`.

```html

<div class="card-shadow">
  <ng-content select="card-title">Default Title</ng-content>
  <div class="card-divider"></div>
  <ng-content select="card-body">Default Body</ng-content>
</div>
```

```html

<custom-card>
  <card-title>Hello</card-title>
  
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <card-title>Hello</card-title>
    <div class="card-divider"></div>
    Default Body
  </div>
</custom-card>
```

## Criando alias de conteúdo para projeção

O Angular suporta um atributo especial, `ngProjectAs`, que permite especificar um seletor CSS em qualquer elemento. Sempre que um elemento com `ngProjectAs` é verificado contra um espaço reservado `<ng-content>`, o Angular compara contra o valor de `ngProjectAs` em vez da identidade do elemento:

```html

<div class="card-shadow">
  <ng-content select="card-title"></ng-content>
  <div class="card-divider"></div>
  <ng-content></ng-content>
</div>
```

```html

<custom-card>
  <h3 ngProjectAs="card-title">Hello</h3>

<p>Welcome to the example</p>
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <h3>Hello</h3>
    <div class="card-divider"></div>
    <p>Welcome to the example</p>
  </div>
</custom-card>
```

`ngProjectAs` suporta apenas valores estáticos e não pode ser vinculado a expressões dinâmicas.

# Ciclo de Vida de Component

TIP: Este guia pressupõe que você já leu o [Guia de Fundamentos](essentials). Leia-o primeiro se você é novo no Angular.

O **ciclo de vida** de um component é a sequência de etapas que acontecem entre a criação do component e sua destruição. Cada etapa representa uma parte diferente do processo do Angular para renderizar components e verificá-los quanto a atualizações ao longo do tempo.

Em seus components, você pode implementar **hooks de ciclo de vida** para executar código durante essas etapas. Hooks de ciclo de vida que se relacionam a uma instância específica de component são implementados como métodos na sua classe de component. Hooks de ciclo de vida que se relacionam à aplicação Angular como um todo são implementados como funções que aceitam um callback.

O ciclo de vida de um component está intimamente conectado a como o Angular verifica seus components quanto a mudanças ao longo do tempo. Para fins de entendimento deste ciclo de vida, você só precisa saber que o Angular percorre a árvore da sua aplicação de cima para baixo, verificando bindings de template quanto a mudanças. Os hooks de ciclo de vida descritos abaixo são executados enquanto o Angular está fazendo esta travessia. Esta travessia visita cada component exatamente uma vez, então você deve sempre evitar fazer outras mudanças de estado no meio do processo.

## Resumo

<div class="docs-table docs-scroll-track-transparent">
  <table>
    <tr>
      <td><strong>Fase</strong></td>
      <td><strong>Método</strong></td>
      <td><strong>Resumo</strong></td>
    </tr>
    <tr>
      <td>Criação</td>
      <td><code>constructor</code></td>
      <td>
        <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Classes/constructor" target="_blank">
          Constructor de classe JavaScript padrão
        </a>. Executa quando o Angular instancia o component.
      </td>
    </tr>
    <tr>
      <td rowspan="7">Detecção<p>de Mudanças</td>
      <td><code>ngOnInit</code>
      </td>
      <td>Executa uma vez após o Angular ter inicializado todos os inputs do component.</td>
    </tr>
    <tr>
      <td><code>ngOnChanges</code></td>
      <td>Executa toda vez que os inputs do component mudarem.</td>
    </tr>
    <tr>
      <td><code>ngDoCheck</code></td>
      <td>Executa toda vez que este component é verificado quanto a mudanças.</td>
    </tr>
    <tr>
      <td><code>ngAfterContentInit</code></td>
      <td>Executa uma vez após o <em>conteúdo</em> do component ter sido inicializado.</td>
    </tr>
    <tr>
      <td><code>ngAfterContentChecked</code></td>
      <td>Executa toda vez que o conteúdo deste component foi verificado quanto a mudanças.</td>
    </tr>
    <tr>
      <td><code>ngAfterViewInit</code></td>
      <td>Executa uma vez após a <em>view</em> do component ter sido inicializada.</td>
    </tr>
    <tr>
      <td><code>ngAfterViewChecked</code></td>
      <td>Executa toda vez que a view do component foi verificada quanto a mudanças.</td>
    </tr>
    <tr>
      <td rowspan="2">Renderização</td>
      <td><code>afterNextRender</code></td>
      <td>Executa uma vez na próxima vez que <strong>todos</strong> os components forem renderizados no DOM.</td>
    </tr>
    <tr>
      <td><code>afterEveryRender</code></td>
      <td>Executa toda vez que <strong>todos</strong> os components forem renderizados no DOM.</td>
    </tr>
    <tr>
      <td>Destruição</td>
      <td><code>ngOnDestroy</code></td>
      <td>Executa uma vez antes do component ser destruído.</td>
    </tr>
  </table>
</div>

### ngOnInit

O método `ngOnInit` executa após o Angular ter inicializado todos os inputs do component com seus valores iniciais. O `ngOnInit` de um component executa exatamente uma vez.

Esta etapa acontece _antes_ do próprio template do component ser inicializado. Isso significa que você pode atualizar o estado do component com base em seus valores iniciais de input.

### ngOnChanges

O método `ngOnChanges` executa após qualquer input de component ter mudado.

Esta etapa acontece _antes_ do próprio template do component ser verificado. Isso significa que você pode atualizar o estado do component com base em seus valores iniciais de input.

Durante a inicialização, o primeiro `ngOnChanges` executa antes do `ngOnInit`.

#### Inspecionando mudanças

O método `ngOnChanges` aceita um argumento `SimpleChanges`. Este objeto é um [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) mapeando cada nome de input do component para um objeto `SimpleChange`. Cada `SimpleChange` contém o valor anterior do input, seu valor atual e uma flag para se esta é a primeira vez que o input mudou.

```ts
@Component({
  /* ... */
})
export class UserProfile {
  name = input('');

ngOnChanges(changes: SimpleChanges) {
    for (const inputName in changes) {
      const inputValues = changes[inputName];
      console.log(`Previous ${inputName} == ${inputValues.previousValue}`);
      console.log(`Current ${inputName} == ${inputValues.currentValue}`);
      console.log(`Is first ${inputName} change == ${inputValues.firstChange}`);
    }
  }
}
```

Se você fornecer um `alias` para quaisquer propriedades de input, o Record `SimpleChanges` ainda usa o nome da propriedade TypeScript como chave, em vez do alias.

### ngOnDestroy

O método `ngOnDestroy` executa uma vez pouco antes de um component ser destruído. O Angular destrói um component quando ele não é mais mostrado na página, como sendo ocultado por `@if` ou ao navegar para outra página.

#### DestroyRef

Como uma alternativa ao método `ngOnDestroy`, você pode injetar uma instância de `DestroyRef`. Você pode registrar um callback para ser invocado na destruição do component chamando o método `onDestroy` de `DestroyRef`.

```ts
@Component({
  /* ... */
})
export class UserProfile {
  constructor() {
    inject(DestroyRef).onDestroy(() => {
      console.log('UserProfile destruction');
    });
  }
}
```

Você pode passar a instância de `DestroyRef` para funções ou classes fora do seu component. Use este padrão se você tiver outro código que deve executar algum comportamento de limpeza quando o component for destruído.

Você também pode usar `DestroyRef` para manter o código de configuração próximo ao código de limpeza, em vez de colocar todo o código de limpeza no método `ngOnDestroy`.

##### Detectando destruição de instância

`DestroyRef` fornece uma propriedade `destroyed` que permite verificar se uma determinada instância já foi destruída. Isso é útil para evitar operações em components destruídos, especialmente ao lidar com lógica atrasada ou assíncrona.

Ao verificar `destroyRef.destroyed`, você pode prevenir a execução de código após a instância ter sido limpa, evitando erros potenciais como `NG0911: View has already been destroyed.`.

### ngDoCheck

O método `ngDoCheck` executa antes de toda vez que o Angular verifica o template de um component quanto a mudanças.

Você pode usar este hook de ciclo de vida para verificar manualmente mudanças de estado fora da detecção normal de mudanças do Angular, atualizando manualmente o estado do component.

Este método executa muito frequentemente e pode impactar significativamente o desempenho da sua página. Evite definir este hook sempre que possível, usando-o apenas quando você não tiver alternativa.

Durante a inicialização, o primeiro `ngDoCheck` executa após `ngOnInit`.

### ngAfterContentInit

O método `ngAfterContentInit` executa uma vez após todos os filhos aninhados dentro do component (seu _conteúdo_) terem sido inicializados.

Você pode usar este hook de ciclo de vida para ler os resultados de [consultas de conteúdo](guide/components/queries#content-queries). Embora você possa acessar o estado inicializado dessas consultas, tentar alterar qualquer estado neste método resulta em um [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).

### ngAfterContentChecked

O método `ngAfterContentChecked` executa toda vez que os filhos aninhados dentro do component (seu _conteúdo_) foram verificados quanto a mudanças.

Embora você possa acessar o estado atualizado de [consultas de conteúdo](guide/components/queries#content-queries) aqui, tentar alterar qualquer estado neste método resulta em um [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).

### ngAfterViewInit

O método `ngAfterViewInit` executa uma vez após todos os filhos no template do component (sua _view_) terem sido inicializados.

Você pode usar este hook de ciclo de vida para ler os resultados de [consultas de view](guide/components/queries#view-queries). Embora você possa acessar o estado inicializado dessas consultas, tentar alterar qualquer estado neste método resulta em um [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).

### ngAfterViewChecked

O método `ngAfterViewChecked` executa toda vez que os filhos no template do component (sua _view_) foram verificados quanto a mudanças.

Embora você possa acessar o estado atualizado de [consultas de view](guide/components/queries#view-queries) aqui, tentar alterar qualquer estado neste método resulta em um [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).

### afterEveryRender e afterNextRender

As funções `afterEveryRender` e `afterNextRender` permitem que você registre um **callback de renderização** para ser invocado após o Angular ter terminado de renderizar _todos os components_ na página no DOM.

Essas funções são diferentes dos outros hooks de ciclo de vida descritos neste guia. Em vez de um método de classe, são funções autônomas que aceitam um callback. A execução de callbacks de renderização não está vinculada a nenhuma instância de component específica, mas sim a um hook em toda a aplicação.

`afterEveryRender` e `afterNextRender` devem ser chamados em um [contexto de injeção](guide/di/dependency-injection-context), tipicamente no constructor de um component.

Você pode usar callbacks de renderização para realizar operações manuais do DOM. Consulte [Usando APIs DOM](guide/components/dom-apis) para orientação sobre trabalhar com o DOM no Angular.

Callbacks de renderização não são executados durante renderização no servidor ou durante pré-renderização em tempo de build.

#### Fases after\*Render

Ao usar `afterEveryRender` ou `afterNextRender`, você pode opcionalmente dividir o trabalho em fases. A fase dá a você controle sobre o sequenciamento de operações DOM, permitindo sequenciar operações de _escrita_ antes de operações de _leitura_ para minimizar [layout thrashing](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing). Para se comunicar entre fases, uma função de fase pode retornar um valor de resultado que pode ser acessado na próxima fase.

```ts
import {Component, ElementRef, afterNextRender} from '@angular/core';

@Component({...})
export class UserProfile {
  private prevPadding = 0;
  private elementHeight = 0;

constructor() {
    private elementRef = inject(ElementRef);
    const nativeElement = elementRef.nativeElement;

afterNextRender({
      // Use the `Write` phase to write to a geometric property.
      write: () => {
        const padding = computePadding();
        const changed = padding !== this.prevPadding;
        if (changed) {
          nativeElement.style.padding = padding;
        }
        return changed; // Communicate whether anything changed to the read phase.
      },

// Use the `Read` phase to read geometric properties after all writes have occurred.
      read: (didWrite) => {
        if (didWrite) {
          this.elementHeight = nativeElement.getBoundingClientRect().height;
        }
      }
    });
  }
}
```

Existem quatro fases, executadas na seguinte ordem:

| Fase             | Descrição                                                                                                                                                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `earlyRead`      | Use esta fase para ler quaisquer propriedades e estilos DOM que afetam o layout e que são estritamente necessários para cálculos subsequentes. Evite esta fase se possível, preferindo as fases `write` e `read`.         |
| `mixedReadWrite` | Fase padrão. Use para quaisquer operações que precisam ler e escrever propriedades e estilos que afetam o layout. Evite esta fase se possível, preferindo as fases explícitas `write` e `read`.                           |
| `write`          | Use esta fase para escrever propriedades e estilos DOM que afetam o layout.                                                                                                                                               |
| `read`           | Use esta fase para ler quaisquer propriedades DOM que afetam o layout.                                                                                                                                                    |

## Interfaces de ciclo de vida

O Angular fornece uma interface TypeScript para cada método de ciclo de vida. Você pode opcionalmente importar e `implementar` essas interfaces para garantir que sua implementação não tenha erros de digitação.

Cada interface tem o mesmo nome que o método correspondente sem o prefixo `ng`. Por exemplo, a interface para `ngOnInit` é `OnInit`.

```ts
@Component({
  /* ... */
})
export class UserProfile implements OnInit {
  ngOnInit() {
    /* ... */
  }
}
```

## Ordem de execução

Os diagramas a seguir mostram a ordem de execução dos hooks de ciclo de vida do Angular.

### Durante a inicialização

```mermaid
graph TD;
id[constructor]-->CHANGE;
subgraph CHANGE [Change detection]
direction TB
ngOnChanges-->ngOnInit;
ngOnInit-->ngDoCheck;
ngDoCheck-->ngAfterContentInit;
ngDoCheck-->ngAfterViewInit
ngAfterContentInit-->ngAfterContentChecked
ngAfterViewInit-->ngAfterViewChecked
end
CHANGE--Rendering-->afterNextRender-->afterEveryRender
```

### Atualizações subsequentes

```mermaid
graph TD;
subgraph CHANGE [Change detection]
direction TB
ngOnChanges-->ngDoCheck
ngDoCheck-->ngAfterContentChecked;
ngDoCheck-->ngAfterViewChecked
end
CHANGE--Rendering-->afterEveryRender
```

### Ordenação com directives

Quando você coloca uma ou mais directives no mesmo elemento que um component, seja em um template ou com a propriedade `hostDirectives`, o framework não garante qualquer ordenação de um determinado hook de ciclo de vida entre o component e as directives em um único elemento. Nunca dependa de uma ordenação observada, pois isso pode mudar em versões posteriores do Angular.

Templates de components não são apenas HTML estático— eles podem usar dados da sua classe de component e configurar manipuladores para interação do usuário.

## Mostrando texto dinâmico

No Angular, um _binding_ cria uma conexão dinâmica entre o template de um component e seus dados. Esta conexão garante que mudanças nos dados do component atualizem automaticamente o template renderizado.

Você pode criar um binding para mostrar algum texto dinâmico em um template usando chaves duplas:

```typescript
@Component({
  selector: 'user-profile',
  template: `<h1>Profile for {{userName()}}</h1>`,
})
export class UserProfile {
  userName = signal('pro_programmer_123');
}
```

Quando o Angular renderiza o component, você vê:

```html
<h1>Profile for pro_programmer_123</h1>
```

O Angular automaticamente mantém o binding atualizado quando o valor do signal muda. Construindo sobre
o exemplo acima, se atualizarmos o valor do signal `userName`:

```typescript
this.userName.set('cool_coder_789');
```

A página renderizada atualiza para refletir o novo valor:

```html
<h1>Profile for cool_coder_789</h1>
```

## Definindo propriedades e atributos dinâmicos

O Angular suporta binding de valores dinâmicos em propriedades do DOM com colchetes:

```typescript
@Component({
  /*...*/
  // Set the `disabled` property of the button based on the value of `isValidUserId`.
  template: `<button [disabled]="!isValidUserId()">Save changes</button>`,
})
export class UserProfile {
  isValidUserId = signal(false);
}
```

Você também pode fazer binding para _atributos_ HTML prefixando o nome do atributo com `attr.`:

```html

<ul [attr.role]="listRole()">
```

O Angular automaticamente atualiza propriedades e atributos do DOM quando o valor vinculado muda.

## Lidando com interação do usuário

O Angular permite que você adicione event listeners a um elemento no seu template com parênteses:

```typescript
@Component({
  /*...*/
  // Add an 'click' event handler that calls the `cancelSubscription` method.
  template: `<button (click)="cancelSubscription()">Cancel subscription</button>`,
})
export class UserProfile {
  /* ... */

cancelSubscription() { /* Your event handling code goes here. */  }
}
```

Se você precisar passar o objeto [event](https://developer.mozilla.org/docs/Web/API/Event) para seu listener, você pode usar a variável embutida `$event` do Angular dentro da chamada da função:

```typescript
@Component({
  /*...*/
  // Add an 'click' event handler that calls the `cancelSubscription` method.
  template: `<button (click)="cancelSubscription($event)">Cancel subscription</button>`,
})
export class UserProfile {
  /* ... */

cancelSubscription(event: Event) { /* Your event handling code goes here. */  }
}
```

## Controle de fluxo com `@if` e `@for`

Você pode condicionalmente ocultar e mostrar partes de um template com o bloco `@if` do Angular:

```html
<h1>User profile</h1>

@if (isAdmin()) {
  <h2>Admin settings</h2>
  
}
```

O bloco `@if` também suporta um bloco `@else` opcional:

```html
<h1>User profile</h1>

@if (isAdmin()) {
  <h2>Admin settings</h2>
  
} @else {
  <h2>User settings</h2>
  
}
```

Você pode repetir parte de um template múltiplas vezes com o bloco `@for` do Angular:

```html
<h1>User profile</h1>

<ul class="user-badge-list">
  @for (badge of badges(); track badge.id) {
    <li class="user-badge">{{badge.name}}</li>
  }
</ul>
```

O Angular usa a palavra-chave `track`, mostrada no exemplo acima, para associar dados com os elementos DOM criados por `@for`. Veja [_Por que track em blocos @for é importante?_](guide/templates/control-flow#why-is-track-in-for-blocks-important) para mais informações.

DICA: Quer saber mais sobre templates do Angular? Veja o [guia detalhado de Templates](guide/templates) para todos os detalhes.

## Próximo Passo

Agora que você tem dados dinâmicos e templates na aplicação, é hora de aprender como aprimorar templates condicionalmente ocultando ou mostrando certos elementos, percorrendo elementos em loop e muito mais.

# Adicionando event listeners

O Angular suporta definir event listeners em um elemento no seu template especificando o nome do evento dentro de parênteses junto com uma instrução que executa toda vez que o evento ocorre.

## Ouvindo eventos nativos

Quando você quer adicionar event listeners a um elemento HTML, você envolve o evento com parênteses, `()`, o que permite que você especifique uma instrução de listener.

```typescript
@Component({
  template: `
    <input type="text" (keyup)="updateField()" />
  `,
  ...
})
export class AppComponent{
  updateField(): void {
    console.log('Field is updated!');
  }
}
```

Neste exemplo, o Angular chama `updateField` toda vez que o elemento `<input>` emite um evento `keyup`.

Você pode adicionar listeners para quaisquer eventos nativos, como: `click`, `keydown`, `mouseover`, etc. Para saber mais, confira [todos os eventos disponíveis em elementos no MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element#events).

## Acessando o argumento de evento

Em todo template event listener, o Angular fornece uma variável chamada `$event` que contém uma referência ao objeto de evento.

```typescript
@Component({
  template: `
    <input type="text" (keyup)="updateField($event)" />
  `,
  ...
})
export class AppComponent {
  updateField(event: KeyboardEvent): void {
    console.log(`The user pressed: ${event.key}`);
  }
}
```

## Usando modificadores de tecla

Quando você quer capturar eventos de teclado específicos para uma tecla específica, você pode escrever algum código como o seguinte:

```typescript
@Component({
  template: `
    <input type="text" (keyup)="updateField($event)" />
  `,
  ...
})
export class AppComponent {
  updateField(event: KeyboardEvent): void {
    if (event.key === 'Enter') {
      console.log('The user pressed enter in the text field.');
    }
  }
}
```

No entanto, como este é um cenário comum, o Angular permite que você filtre os eventos especificando uma tecla específica usando o caractere de ponto (`.`). Ao fazer isso, o código pode ser simplificado para:

```typescript
@Component({
  template: `
    <input type="text" (keyup.enter)="updateField($event)" />
  `,
  ...
})
export class AppComponent{
  updateField(event: KeyboardEvent): void {
    console.log('The user pressed enter in the text field.');
  }
}
```

Você também pode adicionar modificadores de tecla adicionais:

```html

<input type="text" (keyup.shift.enter)="updateField($event)" />
```

O Angular suporta os modificadores `alt`, `control`, `meta` e `shift`.

Você pode especificar a tecla ou código que você gostaria de vincular a eventos de teclado. Os campos key e code são uma parte nativa do objeto de evento de teclado do navegador. Por padrão, o event binding assume que você quer usar os [valores de Key para eventos de teclado](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values).

O Angular também permite que você especifique [valores de Code para eventos de teclado](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_code_values) fornecendo um sufixo `code` integrado.

```html

<input type="text" (keydown.code.alt.shiftleft)="updateField($event)" />
```

Isso pode ser útil para lidar com eventos de teclado de forma consistente em diferentes sistemas operacionais. Por exemplo, ao usar a tecla Alt em dispositivos MacOS, a propriedade `key` reporta a tecla baseada no caractere já modificado pela tecla Alt. Isso significa que uma combinação como Alt + S reporta um valor `key` de `'ß'`. A propriedade `code`, no entanto, corresponde ao botão físico ou virtual pressionado ao invés do caractere produzido.

## Prevenindo comportamento padrão de evento

Se seu event handler deve substituir o comportamento nativo do navegador, você pode usar o [método `preventDefault`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) do objeto de evento:

```typescript
@Component({
  template: `
    <a href="#overlay" (click)="showOverlay($event)">
  `,
  ...
})
export class AppComponent{
  showOverlay(event: PointerEvent): void {
    event.preventDefault();
    console.log('Show overlay without updating the URL!');
  }
}
```

Se a instrução do event handler avaliar para `false`, o Angular automaticamente chama `preventDefault()`, similar aos [atributos de event handler nativos](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes). _Sempre prefira chamar explicitamente `preventDefault`_, pois esta abordagem torna a intenção do código óbvia.

## Estender manipulação de eventos

O sistema de eventos do Angular é extensível via plugins de eventos customizados registrados com o token de injeção `EVENT_MANAGER_PLUGINS`.

### Implementando Event Plugin

Para criar um plugin de evento customizado, estenda a classe `EventManagerPlugin` e implemente os métodos necessários.

```ts
import { Injectable } from '@angular/core';
import { EventManagerPlugin } from '@angular/platform-browser';

@Injectable()
export class DebounceEventPlugin extends EventManagerPlugin {
  constructor() {
    super(document);
  }

// Define which events this plugin supports
  override supports(eventName: string) {
    return /debounce/.test(eventName);
  }

// Handle the event registration
  override addEventListener(
    element: HTMLElement,
    eventName: string,
    handler: Function
  ) {
    // Parse the event: e.g., "click.debounce.500"
    // event: "click", delay: 500
    const [event, method , delay = 300 ] = eventName.split('.');

let timeoutId: number;

const listener = (event: Event) => {
      clearTimeout(timeoutId);
      timeoutId = setTimeout(() => {
          handler(event);
      }, delay);
    };

element.addEventListener(event, listener);

// Return cleanup function
    return () => {
      clearTimeout(timeoutId);
      element.removeEventListener(event, listener);
    };
  }
}
```

Registre seu plugin customizado usando o token `EVENT_MANAGER_PLUGINS` nos providers da sua aplicação:

```ts
import { bootstrapApplication } from '@angular/platform-browser';
import { EVENT_MANAGER_PLUGINS } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
import { DebounceEventPlugin } from './debounce-event-plugin';

bootstrapApplication(AppComponent, {
  providers: [
    {
      provide: EVENT_MANAGER_PLUGINS,
      useClass: DebounceEventPlugin,
      multi: true
    }
  ]
});
```

Uma vez registrado, você pode usar sua sintaxe de evento customizada em templates, bem como com a propriedade `host`:

```typescript
@Component({
  template: `
    <input
      type="text"
      (input.debounce.500)="onSearch($event.target.value)"
      placeholder="Search..."
    />
  `,
  ...
})
export class Search {
 onSearch(query: string): void {
    console.log('Searching for:', query);
  }
}
```

```ts
@Component({
  ...,
  host: {
    '(click.debounce.500)': 'handleDebouncedClick()',
  },
})
export class AwesomeCard {
  handleDebouncedClick(): void {
   console.log('Debounced click!');
  }
}
```

# Vinculando texto, propriedades e atributos dinâmicos

No Angular, um **binding** cria uma conexão dinâmica entre o template de um component e seus dados. Esta conexão garante que mudanças nos dados do component atualizem automaticamente o template renderizado.

## Renderizar texto dinâmico com text interpolation

Você pode vincular texto dinâmico em templates com chaves duplas, o que informa ao Angular que ele é responsável pela expressão dentro e garantir que ela seja atualizada corretamente. Isso é chamado de **text interpolation**.

```typescript
@Component({
  template: `
    <p>Your color preference is {{ theme }}.</p>
  `,
  ...
})
export class AppComponent {
  theme = 'dark';
}
```

Neste exemplo, quando o trecho é renderizado na página, o Angular substituirá `{{ theme }}` por `dark`.

```html

<p>Your color preference is dark.</p>
```

Bindings que mudam ao longo do tempo devem ler valores de [signals](/guide/signals). O Angular rastreia os signals lidos no template e atualiza a página renderizada quando esses valores de signal mudam.

```typescript
@Component({
  template: `
    
    <p>{{ welcomeMessage }}</p>

<p>Your color preference is {{ theme() }}.</p> 
  `
  ...
})
export class AppComponent {
  welcomeMessage = "Welcome, enjoy this app that we built for you";
  theme = signal('dark');
}
```

Para mais detalhes, veja o [guia de Signals](/guide/signals).

Continuando o exemplo do tema, se um usuário clicar em um botão que atualiza o signal `theme` para `'light'` após o carregamento da página, a página atualiza de acordo para:

```html

<p>Your color preference is light.</p>
```

Você pode usar text interpolation em qualquer lugar onde você normalmente escreveria texto em HTML.

Todos os valores de expressão são convertidos para uma string. Objetos e arrays são convertidos usando o método `toString` do valor.

## Vinculando propriedades e atributos dinâmicos

O Angular suporta vincular valores dinâmicos a propriedades de objetos e atributos HTML com colchetes.

Você pode vincular a propriedades em uma instância DOM de um elemento HTML, uma instância de [component](guide/components), ou uma instância de [directive](guide/directives).

### Propriedades de elementos nativos

Cada elemento HTML tem uma representação DOM correspondente. Por exemplo, cada elemento HTML `<button>` corresponde a uma instância de `HTMLButtonElement` no DOM. No Angular, você usa property bindings para definir valores diretamente na representação DOM do elemento.

```html

<button [disabled]="isFormValid()">Save</button>
```

Neste exemplo, toda vez que `isFormValid` muda, o Angular define automaticamente a propriedade `disabled` da instância `HTMLButtonElement`.

### Propriedades de components e directives

Quando um elemento é um component Angular, você pode usar property bindings para definir propriedades de input do component usando a mesma sintaxe de colchetes.

```html

<my-listbox [value]="mySelection()" />
```

Neste exemplo, toda vez que `mySelection` muda, o Angular define automaticamente a propriedade `value` da instância `MyListbox`.

Você também pode vincular a propriedades de directives.

```html

<img [ngSrc]="profilePhotoUrl()" alt="The current user's profile photo">
```

### Atributos

Quando você precisa definir atributos HTML que não têm propriedades DOM correspondentes, como atributos ARIA ou atributos SVG, você pode vincular atributos a elementos em seu template com o prefixo `attr.`.

```html

<ul [attr.role]="listRole()">
```

Neste exemplo, toda vez que `listRole` muda, o Angular define automaticamente o atributo `role` do elemento `<ul>` chamando `setAttribute`.

Se o valor de um attribute binding for `null`, o Angular remove o atributo chamando `removeAttribute`.

### Text interpolation em propriedades e atributos

Você também pode usar a sintaxe de text interpolation em propriedades e atributos usando a sintaxe de chaves duplas em vez de colchetes ao redor do nome da propriedade ou atributo. Ao usar esta sintaxe, o Angular trata a atribuição como um property binding.

```html

<img src="profile-photo.jpg" alt="Profile photo of {{ firstName() }}" >
```

Para vincular a um atributo com a sintaxe de text interpolation, prefixe o nome do atributo com `attr.`

```html
<button attr.aria-label="Save changes to {{ objectType() }}">
```

## Bindings de classes CSS e propriedades de estilo

O Angular suporta recursos adicionais para vincular classes CSS e propriedades de estilo CSS a elementos.

### Classes CSS

Você pode criar um CSS class binding para adicionar ou remover condicionalmente uma classe CSS em um elemento com base em se o valor vinculado é [truthy ou falsy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy).

```html

<ul [class.expanded]="isExpanded()">
```

Você também pode vincular diretamente à propriedade `class`. O Angular aceita três tipos de valor:

| Descrição do valor de `class`                                                                                                                                        | Tipo TypeScript       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Uma string contendo uma ou mais classes CSS separadas por espaços                                                                                                     | `string`              |
| Um array de strings de classes CSS                                                                                                                                    | `string[]`            |
| Um objeto onde cada nome de propriedade é um nome de classe CSS e cada valor correspondente determina se aquela classe é aplicada ao elemento, com base em truthiness. | `Record<string, any>` |

```typescript
@Component({
  template: `
    <ul [class]="listClasses"> ... </ul>
    <section [class]="sectionClasses()"> ... </section>
    <button [class]="buttonClasses()"> ... </button>
  `,
  ...
})
export class UserProfile {
  listClasses = 'full-width outlined';
  sectionClasses = signal(['expandable', 'elevated']);
  buttonClasses = signal({
    highlighted: true,
    embiggened: false,
  });
}
```

O exemplo acima renderiza o seguinte DOM:

```html
<ul class="full-width outlined"> ... </ul>
<section class="expandable elevated"> ... </section>
<button class="highlighted"> ... </button>
```

O Angular ignora quaisquer valores de string que não sejam nomes de classes CSS válidos.

Ao usar classes CSS estáticas, vincular diretamente `class` e vincular classes específicas, o Angular combina inteligentemente todas as classes no resultado renderizado.

```typescript
@Component({
  template: `<ul class="list" [class]="listType()" [class.expanded]="isExpanded()"> ...`,
  ...
})
export class Listbox {
  listType = signal('box');
  isExpanded = signal(true);
}
```

No exemplo acima, o Angular renderiza o elemento `ul` com todas as três classes CSS.

```html
<ul class="list box expanded">
```

O Angular não garante nenhuma ordem específica de classes CSS em elementos renderizados.

Ao vincular `class` a um array ou um objeto, o Angular compara o valor anterior com o valor atual usando o operador de igualdade tripla (`===`). Você deve criar uma nova instância de objeto ou array quando modificar esses valores para que o Angular aplique quaisquer atualizações.

Se um elemento tiver vários bindings para a mesma classe CSS, o Angular resolve colisões seguindo sua ordem de precedência de estilo.

NOTE: Class bindings não suportam nomes de classe separados por espaço em uma única chave. Eles também não suportam mutações em objetos, pois a referência do binding permanece a mesma. Se você precisar de um ou outro, use a directive [ngClass](/api/common/NgClass).

### Propriedades de estilo CSS

Você também pode vincular diretamente a propriedades de estilo CSS em um elemento.

```html

<section [style.display]="isExpanded() ? 'block' : 'none'">
```

Você pode especificar ainda mais unidades para propriedades CSS que aceitam unidades.

```html

<section [style.height.px]="sectionHeightInPixels()">
```

Você também pode definir vários valores de estilo em um único binding. O Angular aceita os seguintes tipos de valor:

| Descrição do valor de `style`                                                                                                 | Tipo TypeScript       |
| ----------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Uma string contendo zero ou mais declarações CSS, como `"display: flex; margin: 8px"`.                                        | `string`              |
| Um objeto onde cada nome de propriedade é um nome de propriedade CSS e cada valor correspondente é o valor daquela propriedade CSS. | `Record<string, any>` |

```typescript
@Component({
  template: `
    <ul [style]="listStyles()"> ... </ul>
    <section [style]="sectionStyles()"> ... </section>
  `,
  ...
})
export class UserProfile {
  listStyles = signal('display: flex; padding: 8px');
  sectionStyles = signal({
    border: '1px solid black',
    'font-weight': 'bold',
  });
}
```

O exemplo acima renderiza o seguinte DOM.

```html
<ul style="display: flex; padding: 8px"> ... </ul>
<section style="border: 1px solid black; font-weight: bold"> ... </section>
```

Ao vincular `style` a um objeto, o Angular compara o valor anterior com o valor atual usando o operador de igualdade tripla (`===`). Você deve criar uma nova instância de objeto quando modificar esses valores para que o Angular aplique quaisquer atualizações.

Se um elemento tiver vários bindings para a mesma propriedade de estilo, o Angular resolve colisões seguindo sua ordem de precedência de estilo.

# Control flow

Templates Angular suportam blocos de control flow que permitem mostrar, ocultar e repetir elementos condicionalmente.

## Exibir conteúdo condicionalmente com `@if`, `@else-if` e `@else`

O bloco `@if` exibe condicionalmente seu conteúdo quando sua expressão de condição é truthy:

```html
@if (a > b) {
  <p>{{a}} is greater than {{b}}</p>
}
```

Se você quiser exibir conteúdo alternativo, você pode fazê-lo fornecendo qualquer número de blocos `@else if` e um único bloco `@else`.

```html
@if (a > b) {
  {{a}} is greater than {{b}}
} @else if (b > a) {
  {{a}} is less than {{b}}
} @else {
  {{a}} is equal to {{b}}
}
```

### Referenciando o resultado da expressão condicional

O condicional `@if` suporta salvar o resultado da expressão condicional em uma variável para reutilização dentro do bloco.

```html
@if (user.profile.settings.startDate; as startDate) {
  {{ startDate }}
}
```

Isso pode ser útil para referenciar expressões mais longas que seriam mais fáceis de ler e manter dentro do template.

## Repetir conteúdo com o bloco `@for`

O bloco `@for` percorre uma coleção e renderiza repetidamente o conteúdo de um bloco. A coleção pode ser qualquer [iterable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols) JavaScript, mas o Angular tem otimizações de performance adicionais para valores `Array`.

Um loop `@for` típico se parece com:

```html
@for (item of items; track item.id) {
  {{ item.name }}
}
```

O bloco `@for` do Angular não suporta instruções que modificam o fluxo como `continue` ou `break` do JavaScript.

### Por que `track` em blocos `@for` é importante?

A expressão `track` permite que o Angular mantenha uma relação entre seus dados e os nós DOM na página. Isso permite que o Angular otimize a performance executando as operações DOM mínimas necessárias quando os dados mudam.

Usar track efetivamente pode melhorar significativamente a performance de renderização da sua aplicação ao percorrer coleções de dados.

Selecione uma propriedade que identifica exclusivamente cada item na expressão `track`. Se seu modelo de dados incluir uma propriedade de identificação única, comumente `id` ou `uuid`, use este valor. Se seus dados não incluírem um campo como este, considere fortemente adicionar um.

Para coleções estáticas que nunca mudam, você pode usar `$index` para informar ao Angular para rastrear cada item por seu índice na coleção.

Se nenhuma outra opção estiver disponível, você pode especificar `identity`. Isso informa ao Angular para rastrear o item por sua identidade de referência usando o operador de igualdade tripla (`===`). Evite esta opção sempre que possível, pois pode levar a atualizações de renderização significativamente mais lentas, já que o Angular não tem como mapear qual item de dados corresponde a quais nós DOM.

### Variáveis contextuais em blocos `@for`

Dentro de blocos `@for`, várias variáveis implícitas estão sempre disponíveis:

| Variável | Significado                                   |
| -------- | --------------------------------------------- |
| `$count` | Número de itens em uma coleção iterada        |
| `$index` | Índice da linha atual                         |
| `$first` | Se a linha atual é a primeira linha           |
| `$last`  | Se a linha atual é a última linha             |
| `$even`  | Se o índice da linha atual é par              |
| `$odd`   | Se o índice da linha atual é ímpar            |

Essas variáveis estão sempre disponíveis com esses nomes, mas podem receber aliases via um segmento `let`:

```html
@for (item of items; track item.id; let idx = $index, e = $even) {
  <p>Item #{{ idx }}: {{ item.name }}</p>
}
```

O alias é útil ao aninhar blocos `@for`, permitindo que você leia variáveis do bloco `@for` externo de um bloco `@for` interno.

### Fornecendo um fallback para blocos `@for` com o bloco `@empty`

Você pode opcionalmente incluir uma seção `@empty` imediatamente após o conteúdo do bloco `@for`. O conteúdo do bloco `@empty` é exibido quando não há itens:

```html
@for (item of items; track item.name) {
  <li> {{ item.name }}</li>
} @empty {
  <li> There are no items. </li>
}
```

## Exibir conteúdo condicionalmente com o bloco `@switch`

Embora o bloco `@if` seja ótimo para a maioria dos cenários, o bloco `@switch` fornece uma sintaxe alternativa para renderizar dados condicionalmente. Sua sintaxe se assemelha muito à instrução `switch` do JavaScript.

```html
@switch (userPermissions) {
  @case ('admin') {
    <app-admin-dashboard />
  }
  @case ('reviewer') {
    <app-reviewer-dashboard />
  }
  @case ('editor') {
    <app-editor-dashboard />
  }
  @default {
    <app-viewer-dashboard />
  }
}
```

O valor da expressão condicional é comparado com a expressão case usando o operador de igualdade tripla (`===`).

**`@switch` não tem fallthrough**, então você não precisa de um equivalente a uma instrução `break` ou `return` no bloco.

Você pode opcionalmente incluir um bloco `@default`. O conteúdo do bloco `@default` é exibido se nenhuma das expressões case anteriores corresponder ao valor do switch.

Se nenhum `@case` corresponder à expressão e não houver um bloco `@default`, nada é mostrado.

# Variáveis em templates

O Angular tem dois tipos de declarações de variáveis em templates: variáveis locais de template e template reference variables.

## Variáveis locais de template com `@let`

A sintaxe `@let` do Angular permite que você defina uma variável local e a reutilize em um template, semelhante à [sintaxe `let` do JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let).

### Usando `@let`

Use `@let` para declarar uma variável cujo valor é baseado no resultado de uma expressão de template. O Angular mantém automaticamente o valor da variável atualizado com a expressão fornecida, semelhante aos [bindings](./templates/bindings).

```html
@let name = user.name;
@let greeting = 'Hello, ' + name;
@let data = data$ | async;
@let pi = 3.14159;
@let coordinates = {x: 50, y: 100};
@let longExpression = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit ' +
                      'sed do eiusmod tempor incididunt ut labore et dolore magna ' +
                      'Ut enim ad minim veniam...';
```

Cada bloco `@let` pode declarar exatamente uma variável. Você não pode declarar múltiplas variáveis no mesmo bloco com uma vírgula.

### Referenciando o valor de `@let`

Uma vez que você tenha declarado uma variável com `@let`, pode reutilizá-la no mesmo template:

```html
@let user = user$ | async;

@if (user) {
  <h1>Hello, {{user.name}}</h1>
  <user-avatar [photo]="user.photo"/>

<ul>
    @for (snack of user.favoriteSnacks; track snack.id) {
      <li>{{snack.name}}</li>
    }
  </ul>

<button (click)="update(user)">Update profile</button>
}
```

### Atribuibilidade

Uma diferença chave entre `@let` e o `let` do JavaScript é que `@let` não pode ser reatribuído após a declaração. No entanto, o Angular mantém automaticamente o valor da variável atualizado com a expressão fornecida.

```html
@let value = 1;

<button (click)="value = value + 1">Increment the value</button>
```

### Escopo de variável

Declarações `@let` têm escopo na view atual e seus descendentes. O Angular cria uma nova view nos limites de components e onde quer que um template possa conter conteúdo dinâmico, como blocos de control flow, blocos `@defer` ou structural directives.

Como declarações `@let` não sofrem hoisting, elas **não podem** ser acessadas por views pai ou siblings:

```html
@let topLevel = value;

<div>
  @let insideDiv = value;
</div>

{{topLevel}} 
{{insideDiv}}

@if (condition) {
  {{topLevel + insideDiv}}

@let nested = value;

@if (condition) {
    {{topLevel + insideDiv + nested}} 
  }
}

{{nested}} 
```

### Sintaxe completa

A sintaxe `@let` é formalmente definida como:

- A palavra-chave `@let`.
- Seguida por um ou mais espaços em branco, não incluindo novas linhas.
- Seguida por um nome JavaScript válido e zero ou mais espaços em branco.
- Seguida pelo símbolo = e zero ou mais espaços em branco.
- Seguida por uma expressão Angular que pode ser multi-linha.
- Terminada pelo símbolo `;`.

## Template reference variables

Template reference variables fornecem uma maneira de declarar uma variável que referencia um valor de um elemento em seu template.

Uma template reference variable pode se referir ao seguinte:

- um elemento DOM dentro de um template (incluindo [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements))
- um component ou directive do Angular
- um [TemplateRef](/api/core/TemplateRef) de um [ng-template](/api/core/ng-template)

Você pode usar template reference variables para ler informações de uma parte do template em outra parte do mesmo template.

### Declarando uma template reference variable

Você pode declarar uma variável em um elemento em um template adicionando um atributo que começa com o caractere hash (`#`) seguido pelo nome da variável.

```html

<input #taskInput placeholder="Enter task name">
```

### Atribuindo valores a template reference variables

O Angular atribui um valor às template variables baseado no elemento no qual a variável é declarada.

Se você declarar a variável em um component Angular, a variável se refere à instância do component.

```html

<my-datepicker #startDate />
```

Se você declarar a variável em um elemento `<ng-template>`, a variável se refere a uma instância de TemplateRef que representa o template. Para mais informações, consulte [Como o Angular usa o asterisco, \*, na sintaxe](/guide/directives/structural-directives#structural-directive-shorthand) em [Structural directives](/guide/directives/structural-directives).

```html

<ng-template #myFragment>
  <p>This is a template fragment</p>
</ng-template>
```

Se você declarar a variável em qualquer outro elemento exibido, a variável se refere à instância `HTMLElement`.

```html

<input #taskInput placeholder="Enter task name">
```

#### Atribuindo uma referência a uma directive Angular

Directives Angular podem ter uma propriedade `exportAs` que define um nome pelo qual a directive pode ser referenciada em um template:

```typescript
@Directive({
  selector: '[dropZone]',
  exportAs: 'dropZone',
})
export class DropZone { /* ... */ }
```

Quando você declara uma template variable em um elemento, pode atribuir a essa variável uma instância de directive especificando este nome `exportAs`:

```html

<section dropZone #firstZone="dropZone"> ... </section>
```

Você não pode se referir a uma directive que não especifica um nome `exportAs`.

### Usando template reference variables com queries

Além de usar template variables para ler valores de outra parte do mesmo template, você também pode usar este estilo de declaração de variável para "marcar" um elemento para [queries de component e directive](/guide/components/queries).

Quando você quer fazer uma query por um elemento específico em um template, pode declarar uma template variable nesse elemento e então fazer uma query pelo elemento baseando-se no nome da variável.

```html
<input #description value="Original description">
```

```typescript
@Component({
  /* ... */,
  template: `<input #description value="Original description">`,
})
export class AppComponent {
  // Query for the input element based on the template variable name.
  @ViewChild('description') input: ElementRef | undefined;
}
```

Consulte [Referenciando filhos com queries](/guide/components/queries) para mais informações sobre queries.

# Carregamento diferido com `@defer`

Views diferíveis, também conhecidas como blocos `@defer`, reduzem o tamanho do bundle inicial da sua aplicação adiando o carregamento de código que não é estritamente necessário para a renderização inicial de uma página. Isso frequentemente resulta em um carregamento inicial mais rápido e melhoria nos Core Web Vitals (CWV), principalmente Largest Contentful Paint (LCP) e Time to First Byte (TTFB).

Para usar este recurso, você pode declarativamente envolver uma seção do seu template em um bloco @defer:

```html
@defer {
  <large-component />
}
```

O código para quaisquer components, directives e pipes dentro do bloco `@defer` é dividido em um arquivo JavaScript separado e carregado apenas quando necessário, após o resto do template ter sido renderizado.

Views diferíveis suportam uma variedade de triggers, opções de prefetching e sub-blocos para gerenciamento de estado de placeholder, loading e error.

## Quais dependências são diferidas?

Components, directives, pipes e quaisquer estilos CSS de components podem ser diferidos ao carregar uma aplicação.

Para que as dependências dentro de um bloco `@defer` sejam diferidas, elas precisam atender duas condições:

1. **Elas devem ser standalone.** Dependências não-standalone não podem ser diferidas e ainda são carregadas eagerly, mesmo se estiverem dentro de blocos `@defer`.
1. **Elas não podem ser referenciadas fora de blocos `@defer` dentro do mesmo arquivo.** Se elas forem referenciadas fora do bloco `@defer` ou referenciadas dentro de queries ViewChild, as dependências serão carregadas eagerly.

As dependências _transitivas_ dos components, directives e pipes usados no bloco `@defer` não precisam estritamente ser standalone; dependências transitivas ainda podem ser declaradas em um `NgModule` e participar do carregamento diferido.

O compilador do Angular produz uma instrução [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) para cada component, directive e pipe usado no bloco `@defer`. O conteúdo principal do bloco renderiza após todos os imports serem resolvidos. O Angular não garante nenhuma ordem específica para esses imports.

## Como gerenciar diferentes estágios do carregamento diferido

Blocos `@defer` têm vários sub-blocos para permitir que você gerencie graciosamente diferentes estágios no processo de carregamento diferido.

### `@defer`

Este é o bloco primário que define a seção de conteúdo que é carregada lazily. Ele não é renderizado inicialmente– o conteúdo diferido carrega e renderiza uma vez que o [trigger](/guide/templates/defer#triggers) especificado ocorre ou a condição `when` é atendida.

Por padrão, um bloco `@defer` é acionado quando o estado do navegador se torna [idle](/guide/templates/defer#idle).

```html
@defer {
  <large-component />
}
```

### Mostrar conteúdo de placeholder com `@placeholder`

Por padrão, blocos defer não renderizam nenhum conteúdo antes de serem acionados.

O `@placeholder` é um bloco opcional que declara qual conteúdo mostrar antes que o bloco `@defer` seja acionado.

```html
@defer {
  <large-component />
} @placeholder {
  <p>Placeholder content</p>
}
```

Embora opcional, certos triggers podem exigir a presença de um `@placeholder` ou uma [template reference variable](/guide/templates/variables#template-reference-variables) para funcionar. Veja a seção [Triggers](/guide/templates/defer#triggers) para mais detalhes.

O Angular substitui o conteúdo do placeholder pelo conteúdo principal uma vez que o carregamento está completo. Você pode usar qualquer conteúdo na seção de placeholder incluindo HTML simples, components, directives e pipes. Tenha em mente que as _dependências do bloco placeholder são carregadas eagerly_.

O bloco `@placeholder` aceita um parâmetro opcional para especificar a quantidade `minimum` de tempo que este placeholder deve ser mostrado após o conteúdo do placeholder renderizar inicialmente.

```html
@defer {
  <large-component />
} @placeholder (minimum 500ms) {
  <p>Placeholder content</p>
}
```

Este parâmetro `minimum` é especificado em incrementos de tempo de milissegundos (ms) ou segundos (s). Você pode usar este parâmetro para prevenir flickering rápido do conteúdo do placeholder no caso das dependências diferidas serem buscadas rapidamente.

### Mostrar conteúdo de loading com `@loading`

O bloco `@loading` é um bloco opcional que permite que você declare conteúdo que é mostrado enquanto as dependências diferidas estão carregando. Ele substitui o bloco `@placeholder` uma vez que o carregamento é acionado.

```html
@defer {
  <large-component />
} @loading {
  <img alt="loading..." src="loading.gif" />
} @placeholder {
  <p>Placeholder content</p>
}
```

Suas dependências são carregadas eagerly (similar ao `@placeholder`).

O bloco `@loading` aceita dois parâmetros opcionais para ajudar a prevenir flickering rápido de conteúdo que pode ocorrer quando dependências diferidas são buscadas rapidamente:

- `minimum` - a quantidade mínima de tempo que este placeholder deve ser mostrado
- `after` - a quantidade de tempo para esperar após o início do carregamento antes de mostrar o template de loading

```html
@defer {
  <large-component />
} @loading (after 100ms; minimum 1s) {
  <img alt="loading..." src="loading.gif" />
}
```

Ambos os parâmetros são especificados em incrementos de tempo de milissegundos (ms) ou segundos (s). Além disso, os temporizadores para ambos os parâmetros começam imediatamente após o carregamento ter sido acionado.

### Mostrar estado de erro quando o carregamento diferido falha com `@error`

O bloco `@error` é um bloco opcional que exibe se o carregamento diferido falhar. Similar ao `@placeholder` e `@loading`, as dependências do bloco @error são carregadas eagerly.

```html
@defer {
  <large-component />
} @error {
  <p>Failed to load large component.</p>
}
```

## Controlando o carregamento de conteúdo diferido com triggers

Você pode especificar **triggers** que controlam quando o Angular carrega e exibe conteúdo diferido.

Quando um bloco `@defer` é acionado, ele substitui o conteúdo do placeholder pelo conteúdo carregado lazily.

Vários event triggers podem ser definidos separando-os com ponto e vírgula, `;` e serão avaliados como condições OR.

Existem dois tipos de triggers: `on` e `when`.

### `on`

`on` especifica uma condição para quando o bloco `@defer` é acionado.

Os triggers disponíveis são os seguintes:

| Trigger                       | Descrição                                                             |
| ----------------------------- | --------------------------------------------------------------------- |
| [`idle`](#idle)               | Aciona quando o navegador está ocioso.                                |
| [`viewport`](#viewport)       | Aciona quando o conteúdo especificado entra no viewport               |
| [`interaction`](#interaction) | Aciona quando o usuário interage com o elemento especificado          |
| [`hover`](#hover)             | Aciona quando o mouse passa sobre a área especificada                 |
| [`immediate`](#immediate)     | Aciona imediatamente após o conteúdo não diferido ter terminado de renderizar |
| [`timer`](#timer)             | Aciona após uma duração específica                                    |

#### `idle`

O trigger `idle` carrega o conteúdo diferido uma vez que o navegador tenha atingido um estado ocioso, baseado em requestIdleCallback. Este é o comportamento padrão com um bloco defer.

```html

@defer {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `viewport`

O trigger `viewport` carrega o conteúdo diferido quando o conteúdo especificado entra no viewport usando a [Intersection Observer API](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API). O conteúdo observado pode ser o conteúdo `@placeholder` ou uma referência de elemento explícita.

Por padrão, o `@defer` observa o placeholder entrando no viewport. Placeholders usados desta forma devem ter um único elemento raiz.

```html
@defer (on viewport) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

Alternativamente, você pode especificar uma [template reference variable](/guide/templates/variables) no mesmo template que o bloco `@defer` como o elemento que é observado para entrar no viewport. Esta variável é passada como um parâmetro no trigger viewport.

```html
<div #greeting>Hello!</div>
@defer (on viewport(greeting)) {
  <greetings-cmp />
}
```

Se você quiser customizar as opções do `IntersectionObserver`, o trigger `viewport` suporta passar um objeto literal. O literal suporta todas as propriedades do segundo parâmetro de `IntersectionObserver`, exceto `root`. Ao usar a notação de objeto literal, você tem que passar seu trigger usando a propriedade `trigger`.

```html
<div #greeting>Hello!</div>

@defer (on viewport({trigger: greeting, rootMargin: '100px', threshold: 0.5})) {
  <greetings-cmp />
}

@defer (on viewport({rootMargin: '100px', threshold: 0.5})) {
  <greetings-cmp />
} @placeholder {
  <div>Implied trigger</div>
}
```

#### `interaction`

O trigger `interaction` carrega o conteúdo diferido quando o usuário interage com o elemento especificado através de eventos `click` ou `keydown`.

Por padrão, o placeholder atua como o elemento de interação. Placeholders usados desta forma devem ter um único elemento raiz.

```html
@defer (on interaction) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

Alternativamente, você pode especificar uma [template reference variable](/guide/templates/variables) no mesmo template que o bloco `@defer` como o elemento que é observado para interações. Esta variável é passada como um parâmetro no trigger viewport.

```html
<div #greeting>Hello!</div>
@defer (on interaction(greeting)) {
  <greetings-cmp />
}
```

#### `hover`

O trigger `hover` carrega o conteúdo diferido quando o mouse passou sobre a área acionada através dos eventos `mouseover` e `focusin`.

Por padrão, o placeholder atua como o elemento de interação. Placeholders usados desta forma devem ter um único elemento raiz.

```html
@defer (on hover) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

```html
<div #greeting>Hello!</div>
@defer (on hover(greeting)) {
  <greetings-cmp />
}
```

#### `immediate`

O trigger `immediate` carrega o conteúdo diferido imediatamente. Isso significa que o bloco diferido carrega assim que todo o outro conteúdo não diferido tiver terminado de renderizar.

```html
@defer (on immediate) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `timer`

O trigger `timer` carrega o conteúdo diferido após uma duração especificada.

```html
@defer (on timer(500ms)) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

O parâmetro de duração deve ser especificado em milissegundos (`ms`) ou segundos (`s`).

### `when`

O trigger `when` aceita uma expressão condicional customizada e carrega o conteúdo diferido quando a condição se torna truthy.

```html
@defer (when condition) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

Esta é uma operação única– o bloco `@defer` não reverte de volta para o placeholder se a condição mudar para um valor falsy após se tornar truthy.

## Pré-buscar dados com `prefetch`

Além de especificar uma condição que determina quando o conteúdo diferido é mostrado, você pode opcionalmente especificar um **prefetch trigger**. Este trigger permite que você carregue o JavaScript associado ao bloco `@defer` antes que o conteúdo diferido seja mostrado.

Prefetching habilita comportamentos mais avançados, como permitir que você comece a pré-buscar recursos antes que um usuário tenha realmente visto ou interagido com um bloco defer, mas possa interagir com ele em breve, tornando os recursos disponíveis mais rapidamente.

Você pode especificar um prefetch trigger de forma similar ao trigger principal do bloco, mas prefixado com a palavra-chave `prefetch`. O trigger principal do bloco e o prefetch trigger são separados com um caractere de ponto e vírgula (`;`).

No exemplo abaixo, o prefetching inicia quando um navegador se torna ocioso e o conteúdo do bloco é renderizado apenas uma vez que o usuário interage com o placeholder.

```html
@defer (on interaction; prefetch on idle) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

## Testando blocos `@defer`

O Angular fornece APIs do TestBed para simplificar o processo de testar blocos `@defer` e acionar diferentes estados durante o teste. Por padrão, blocos `@defer` em testes funcionam como um bloco defer se comportaria em uma aplicação real. Se você quiser percorrer manualmente os estados, pode mudar o comportamento do bloco defer para `Manual` na configuração do TestBed.

```typescript
it('should render a defer block in different states', async () => {
  // configures the defer block behavior to start in "paused" state for manual control.
  TestBed.configureTestingModule({deferBlockBehavior: DeferBlockBehavior.Manual});
  @Component({
    // ...
    template: `
      @defer {
        <large-component />
      } @placeholder {
        Placeholder
      } @loading {
        Loading...
      }
    `
  })
  class ComponentA {}
  // Create component fixture.
  const componentFixture = TestBed.createComponent(ComponentA);
  // Retrieve the list of all defer block fixtures and get the first block.
  const deferBlockFixture = (await componentFixture.getDeferBlocks())[0];
  // Renders placeholder state by default.
  expect(componentFixture.nativeElement.innerHTML).toContain('Placeholder');
  // Render loading state and verify rendered output.
  await deferBlockFixture.render(DeferBlockState.Loading);
  expect(componentFixture.nativeElement.innerHTML).toContain('Loading');
  // Render final state and verify the output.
  await deferBlockFixture.render(DeferBlockState.Complete);
  expect(componentFixture.nativeElement.innerHTML).toContain('large works!');
});
```

## `@defer` funciona com `NgModule`?

Blocos `@defer` são compatíveis tanto com components, directives e pipes standalone quanto baseados em NgModule. No entanto, **apenas components, directives e pipes standalone podem ser diferidos**. Dependências baseadas em NgModule não são diferidas e são incluídas no bundle carregado eagerly.

## Compatibilidade entre blocos `@defer` e Hot Module Reload (HMR)

Quando Hot Module Replacement (HMR) está ativo, todos os chunks de blocos `@defer` são buscados eagerly, sobrescrevendo quaisquer triggers configurados. Para restaurar o comportamento de trigger padrão, você deve desabilitar o HMR servindo sua aplicação com a flag `--no-hmr`.

## Como `@defer` funciona com server-side rendering (SSR) e static-site generation (SSG)?

Por padrão, ao renderizar uma aplicação no servidor (usando SSR ou SSG), blocos defer sempre renderizam seu `@placeholder` (ou nada se um placeholder não for especificado) e triggers não são invocados. No cliente, o conteúdo do `@placeholder` é hidratado e triggers são ativados.

Para renderizar o conteúdo principal de blocos `@defer` no servidor (tanto SSR quanto SSG), você pode habilitar [o recurso de Incremental Hydration](/guide/incremental-hydration) e configurar triggers `hydrate` para os blocos necessários.

## Boas práticas para diferir views

### Evite carregamentos em cascata com blocos `@defer` aninhados

Quando você tem blocos `@defer` aninhados, eles devem ter triggers diferentes para evitar carregamento simultâneo, o que causa requisições em cascata e pode impactar negativamente a performance de carregamento da página.

### Evite mudanças de layout

Evite diferir components que são visíveis no viewport do usuário no carregamento inicial. Fazer isso pode impactar negativamente os Core Web Vitals causando um aumento no cumulative layout shift (CLS).

No caso de isso ser necessário, evite triggers `immediate`, `timer`, `viewport` e `when` customizados que causam o carregamento do conteúdo durante a renderização inicial da página.

### Mantenha a acessibilidade em mente

Ao usar blocos `@defer`, considere o impacto em usuários com tecnologias assistivas como leitores de tela. Leitores de tela que focam em uma seção diferida inicialmente lerão o conteúdo do placeholder ou loading, mas podem não anunciar mudanças quando o conteúdo diferido carregar.

Para garantir que mudanças de conteúdo diferido sejam anunciadas para leitores de tela, você pode envolver seu bloco `@defer` em um elemento com uma região live:

```html
<div aria-live="polite" aria-atomic="true">
  @defer (on timer(2000)) {
    <user-profile [user]="currentUser" />
  } @placeholder {
    Loading user profile...
  } @loading {
    Please wait...
  } @error {
    Failed to load profile
  }
</div>
```

Isso garante que mudanças sejam anunciadas ao usuário quando transições (placeholder → loading → content/error) ocorrem.

# Sintaxe de Expressão

Expressões Angular são baseadas em JavaScript, mas diferem de algumas maneiras importantes. Este guia percorre as semelhanças e diferenças entre expressões Angular e JavaScript padrão.

## Literais de valor

O Angular suporta um subconjunto de [valores literais](https://developer.mozilla.org/en-US/docs/Glossary/Literal) do JavaScript.

### Literais de valor suportados

| Tipo de literal | Valores de exemplo                |
| --------------- | --------------------------------- |
| String          | `'Hello'`, `"World"`              |
| Boolean         | `true`, `false`                   |
| Number          | `123`, `3.14`                     |
| Object          | `{name: 'Alice'}`                 |
| Array           | `['Onion', 'Cheese', 'Garlic']`   |
| null            | `null`                            |
| Template string | `` `Hello ${name}` ``             |
| RegExp          | `/\d+/`                           |

### Literais de valor não suportados

| Tipo de literal | Valores de exemplo |
| --------------- | ------------------ |
| BigInt          | `1n`               |

## Globais

Expressões Angular suportam os seguintes [globais](https://developer.mozilla.org/en-US/docs/Glossary/Global_object):

- [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)
- [$any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any)

Nenhum outro global JavaScript é suportado. Globais JavaScript comuns incluem `Number`, `Boolean`, `NaN`, `Infinity`, `parseInt`, e mais.

## Variáveis locais

O Angular automaticamente disponibiliza variáveis locais especiais para uso em expressões em contextos específicos. Essas variáveis especiais sempre começam com o caractere de cifrão (`$`).

Por exemplo, blocos `@for` disponibilizam várias variáveis locais correspondentes a informações sobre o loop, como `$index`.

## Quais operadores são suportados?

### Operadores suportados

O Angular suporta os seguintes operadores do JavaScript padrão.

| Operador                         | Exemplo(s)                                     |
| -------------------------------- | ---------------------------------------------- |
| Adicionar / Concatenar           | `1 + 2`                                        |
| Subtrair                         | `52 - 3`                                       |
| Multiplicar                      | `41 * 6`                                       |
| Dividir                          | `20 / 4`                                       |
| Resto (Módulo)                   | `17 % 5`                                       |
| Exponenciação                    | `10 ** 3`                                      |
| Parênteses                       | `9 * (8 + 4)`                                  |
| Condicional (Ternário)           | `a > b ? true : false`                         |
| And (Lógico)                     | `&&`                                           |
| Or (Lógico)                      | `\|\|`                                         |
| Not (Lógico)                     | `!`                                            |
| Nullish Coalescing               | `possiblyNullValue ?? 'default'`               |
| Operadores de Comparação         | `<`, `<=`, `>`, `>=`, `==`, `===`, `!==`, `!=` |
| Negação Unária                   | `-x`                                           |
| Plus Unário                      | `+y`                                           |
| Property Accessor                | `person['name']`                               |
| Atribuição                       | `a = b`                                        |
| Atribuição de Adição             | `a += b`                                       |
| Atribuição de Subtração          | `a -= b`                                       |
| Atribuição de Multiplicação      | `a *= b`                                       |
| Atribuição de Divisão            | `a /= b`                                       |
| Atribuição de Resto              | `a %= b`                                       |
| Atribuição de Exponenciação      | `a **= b`                                      |
| Atribuição AND Lógico            | `a &&= b`                                      |
| Atribuição OR Lógico             | `a \|\|= b`                                    |
| Atribuição Nullish Coalescing    | `a ??= b`                                      |

Expressões Angular adicionalmente também suportam os seguintes operadores não-padrão:

| Operador                        | Exemplo(s)                     |
| ------------------------------- | ------------------------------ |
| [Pipe](/guide/templates/pipes)  | `{{ total \| currency }}`      |
| Optional chaining\*             | `someObj.someProp?.nestedProp` |
| Non-null assertion (TypeScript) | `someObj!.someProp`            |

NOTE: Optional chaining se comporta de forma diferente da versão JavaScript padrão em que se o lado esquerdo do operador optional chaining do Angular for `null` ou `undefined`, ele retorna `null` ao invés de `undefined`.

### Operadores não suportados

| Operador                      | Exemplo(s)                        |
| ----------------------------- | --------------------------------- |
| Todos operadores bitwise      | `&`, `&=`, `~`, `\|=`, `^=`, etc. |
| Desestruturação de objeto     | `const { name } = person`         |
| Desestruturação de array      | `const [firstItem] = items`       |
| Operador vírgula              | `x = (x++, x)`                    |
| instanceof                    | `car instanceof Automobile`       |
| new                           | `new Car()`                       |

## Contexto léxico para expressões

Expressões Angular são avaliadas dentro do contexto da classe do component, bem como quaisquer [variáveis de template](/guide/templates/variables), locais e globais relevantes.

Ao se referir a membros da classe do component, `this` está sempre implícito. No entanto, se um template declara uma [variável de template](guide/templates/variables) com o mesmo nome que um membro, a variável sombreia aquele membro. Você pode referenciar inequivocamente tal membro da classe usando explicitamente `this.`. Isso pode ser útil ao criar uma declaração `@let` que sombreia um membro da classe, por exemplo, para fins de narrowing de signal.

## Declarações

De modo geral, declarações não são suportadas em expressões Angular. Isso inclui, mas não está limitado a:

| Declarações    | Exemplo(s)                                  |
| -------------- | ------------------------------------------- |
| Variáveis      | `let label = 'abc'`, `const item = 'apple'` |
| Funções        | `function myCustomFunction() { }`           |
| Arrow Functions| `() => { }`                                 |
| Classes        | `class Rectangle { }`                       |

# Instruções de event listener

Event handlers são **instruções** ao invés de expressões. Embora eles suportem toda a mesma sintaxe que expressões Angular, existem duas diferenças principais:

1. Instruções **suportam** operadores de atribuição (mas não atribuições de desestruturação)
1. Instruções **não suportam** pipes

# Attribute directives

Mude a aparência ou comportamento de elementos DOM e components Angular com attribute directives.

## Construindo uma attribute directive

Esta seção orienta você na criação de uma directive de destaque que define a cor de fundo do elemento host para amarelo.

1. Para criar uma directive, use o comando CLI [`ng generate directive`](tools/cli/schematics).

```shell
ng generate directive highlight
```
   O CLI cria `src/app/highlight.directive.ts`, um arquivo de teste correspondente `src/app/highlight.directive.spec.ts`.

<docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.0.ts"/>

A propriedade de configuração do decorator `@Directive()` especifica o seletor de atributo CSS da directive, `[appHighlight]`.

1. Importe `ElementRef` de `@angular/core`.
   `ElementRef` concede acesso direto ao elemento DOM host através de sua propriedade `nativeElement`.

1. Adicione `ElementRef` no `constructor()` da directive para [injetar](guide/di) uma referência ao elemento DOM host, o elemento ao qual você aplica `appHighlight`.

1. Adicione lógica à classe `HighlightDirective` que define o fundo como amarelo.

<docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.1.ts"/>

ÚTIL: Directives _não_ suportam namespaces.

<docs-code header="src/app/app.component.avoid.html (não suportado)" path="adev/src/content/examples/attribute-directives/src/app/app.component.avoid.html" visibleRegion="unsupported"/>

## Aplicando uma attribute directive

1. Para usar a `HighlightDirective`, adicione um elemento `<p>` ao template HTML com a directive como um atributo.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/attribute-directives/src/app/app.component.1.html" visibleRegion="applied"/>

O Angular cria uma instância da classe `HighlightDirective` e injeta uma referência ao elemento `<p>` no constructor da directive, que define o estilo de fundo do elemento `<p>` como amarelo.

## Manipulando eventos do usuário

Esta seção mostra como detectar quando um usuário passa o mouse sobre o elemento ou sai dele e responder definindo ou limpando a cor de destaque.

1. Importe `HostListener` de '@angular/core'.

<docs-code header="src/app/highlight.directive.ts (imports)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.2.ts" visibleRegion="imports"/>

1. Adicione dois event handlers que respondem quando o mouse entra ou sai, cada um com o decorator `@HostListener()`.

<docs-code header="src/app/highlight.directive.ts (mouse-methods)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.2.ts" visibleRegion="mouse-methods"/>

Inscreva-se em eventos do elemento DOM que hospeda uma attribute directive, o `<p>` neste caso, com o decorator `@HostListener()`.

ÚTIL: Os handlers delegam para um método auxiliar, `highlight()`, que define a cor no elemento DOM host, `el`.

A directive completa é a seguinte:

<docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.2.ts"/>

A cor de fundo aparece quando o ponteiro passa sobre o elemento de parágrafo e desaparece quando o ponteiro se move para fora.

## Passando valores para uma attribute directive

Esta seção orienta você a definir a cor de destaque ao aplicar a `HighlightDirective`.

1. Em `highlight.directive.ts`, importe `Input` de `@angular/core`.

<docs-code header="src/app/highlight.directive.ts (imports)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" visibleRegion="imports"/>

1. Adicione uma propriedade `input` `appHighlight`.

<docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" visibleRegion="input"/>

A função `input()` adiciona metadados à classe que torna a propriedade `appHighlight` da directive disponível para binding.

1. Em `app.component.ts`, adicione uma propriedade `color` ao `AppComponent`.

<docs-code header="src/app/app.component.ts (class)" path="adev/src/content/examples/attribute-directives/src/app/app.component.1.ts" visibleRegion="class"/>

1. Para aplicar simultaneamente a directive e a cor, use property binding com o seletor da directive `appHighlight`, definindo-o igual a `color`.

<docs-code header="src/app/app.component.html (color)" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="color"/>

O attribute binding `[appHighlight]` executa duas tarefas:
   - Aplica a directive de destaque ao elemento `<p>`
   - Define a cor de destaque da directive com um property binding

### Definindo o valor com entrada do usuário

Esta seção orienta você a adicionar botões de opção para vincular sua escolha de cor à directive `appHighlight`.

1. Adicione marcação a `app.component.html` para escolher uma cor da seguinte forma:

<docs-code header="src/app/app.component.html (v2)" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="v2"/>

1. Revise o `AppComponent.color` para que ele não tenha valor inicial.

<docs-code header="src/app/app.component.ts (class)" path="adev/src/content/examples/attribute-directives/src/app/app.component.ts" visibleRegion="class"/>

1. Em `highlight.directive.ts`, revise o método `onMouseEnter` para que ele primeiro tente destacar com `appHighlight` e volte para `red` se `appHighlight` for `undefined`.

<docs-code header="src/app/highlight.directive.ts (mouse-enter)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" visibleRegion="mouse-enter"/>

1. Sirva sua aplicação para verificar que o usuário pode escolher a cor com os botões de opção.

## Binding para uma segunda propriedade

Esta seção orienta você a configurar sua aplicação para que o desenvolvedor possa definir a cor padrão.

1. Adicione uma segunda propriedade `Input()` à `HighlightDirective` chamada `defaultColor`.

<docs-code header="src/app/highlight.directive.ts (defaultColor)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.ts" visibleRegion="defaultColor"/>

1. Revise o `onMouseEnter` da directive para que ele primeiro tente destacar com o `appHighlight`, depois com o `defaultColor`, e volte para `red` se ambas as propriedades forem `undefined`.

<docs-code header="src/app/highlight.directive.ts (mouse-enter)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.ts" visibleRegion="mouse-enter"/>

1. Para fazer binding com `AppComponent.color` e voltar para "violet" como a cor padrão, adicione o seguinte HTML.
   Neste caso, o binding `defaultColor` não usa colchetes, `[]`, porque é estático.

<docs-code header="src/app/app.component.html (defaultColor)" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="defaultColor"/>

Assim como com components, você pode adicionar múltiplos property bindings de directive a um elemento host.

A cor padrão é vermelho se não houver binding de cor padrão.
Quando o usuário escolhe uma cor, a cor selecionada se torna a cor de destaque ativa.

## Desativando o processamento do Angular com `NgNonBindable`

Para prevenir a avaliação de expressões no navegador, adicione `ngNonBindable` ao elemento host.
`ngNonBindable` desativa interpolation, directives e binding em templates.

No exemplo a seguir, a expressão `{{ 1 + 1 }}` renderiza exatamente como aparece no seu editor de código, e não exibe `2`.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="ngNonBindable"/>

Aplicar `ngNonBindable` a um elemento interrompe o binding para os elementos filhos desse elemento.
No entanto, `ngNonBindable` ainda permite que directives funcionem no elemento onde você aplica `ngNonBindable`.
No exemplo a seguir, a directive `appHighlight` ainda está ativa, mas o Angular não avalia a expressão `{{ 1 + 1 }}`.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="ngNonBindable-with-directive"/>

Se você aplicar `ngNonBindable` a um elemento pai, o Angular desativa interpolation e binding de qualquer tipo, como property binding ou event binding, para os filhos do elemento.

# Structural directives {#structural-directives}

Structural directives são directives aplicadas a um elemento `<ng-template>` que renderizam condicionalmente ou repetidamente o conteúdo daquele `<ng-template>`.

## Exemplo de caso de uso

Neste guia você construirá uma structural directive que busca dados de uma fonte de dados fornecida e renderiza seu template quando esses dados estão disponíveis. Esta directive é chamada `SelectDirective`, após a palavra-chave SQL `SELECT`, e a combina com um seletor de atributo `[select]`.

`SelectDirective` terá um input nomeando a fonte de dados a ser usada, que você chamará de `selectFrom`. O prefixo `select` para este input é importante para a [sintaxe abreviada](#structural-directive-shorthand). A directive instanciará seu `<ng-template>` com um contexto de template fornecendo os dados selecionados.

O seguinte é um exemplo de uso desta directive diretamente em um `<ng-template>`:

```html
<ng-template select let-data [selectFrom]="source">
  <p>The data is: {{ data }}</p>
</ng-template>
```

A structural directive pode aguardar que os dados fiquem disponíveis e então renderizar seu `<ng-template>`.

ÚTIL: Note que o elemento `<ng-template>` do Angular define um template que não renderiza nada por padrão, se você apenas envolver elementos em um `<ng-template>` sem aplicar uma structural directive, esses elementos não serão renderizados.

Para mais informações, veja a documentação da [API ng-template](api/core/ng-template).

## Sintaxe abreviada de structural directive {#structural-directive-shorthand}

O Angular suporta uma sintaxe abreviada para structural directives que evita a necessidade de criar explicitamente um elemento `<ng-template>`.

Structural directives podem ser aplicadas diretamente em um elemento prefixando o seletor de atributo da directive com um asterisco (`*`), como `*select`. O Angular transforma o asterisco na frente de uma structural directive em um `<ng-template>` que hospeda a directive e envolve o elemento e seus descendentes.

Você pode usar isso com `SelectDirective` da seguinte forma:

```html
<p *select="let data from source">The data is: {{data}}</p>
```

Este exemplo mostra a flexibilidade da sintaxe abreviada de structural directive, que às vezes é chamada de _microsyntax_.

Quando usada desta forma, apenas a structural directive e seus bindings são aplicados ao `<ng-template>`. Quaisquer outros atributos ou bindings na tag `<p>` são deixados intactos. Por exemplo, essas duas formas são equivalentes:

```html

<p class="data-view" *select="let data from source">The data is: {{data}}</p>

<ng-template select let-data [selectFrom]="source">
  <p class="data-view">The data is: {{data}}</p>
</ng-template>
```

A sintaxe abreviada é expandida através de um conjunto de convenções. Uma [gramática](#structural-directive-syntax-reference) mais completa é definida abaixo, mas no exemplo acima, esta transformação pode ser explicada da seguinte forma:

A primeira parte da expressão `*select` é `let data`, que declara uma variável de template `data`. Como nenhuma atribuição segue, a variável de template é vinculada à propriedade do contexto de template `$implicit`.

A segunda parte da sintaxe é um par chave-expressão, `from source`. `from` é uma chave de binding e `source` é uma expressão de template regular. Chaves de binding são mapeadas para propriedades transformando-as para PascalCase e prefixando com o seletor da structural directive. A chave `from` é mapeada para `selectFrom`, que é então vinculada à expressão `source`. É por isso que muitas structural directives terão inputs que são todos prefixados com o seletor da structural directive.

## Uma structural directive por elemento

Você pode aplicar apenas uma structural directive por elemento ao usar a sintaxe abreviada. Isso ocorre porque há apenas um elemento `<ng-template>` no qual essa directive é desembrulhada. Múltiplas directives exigiriam múltiplos `<ng-template>` aninhados, e não está claro qual directive deveria ser a primeira. `<ng-container>` pode ser usado para criar camadas wrapper quando múltiplas structural directives precisam ser aplicadas ao redor do mesmo elemento DOM físico ou component, o que permite ao usuário definir a estrutura aninhada.

## Criando uma structural directive

Esta seção orienta você na criação da `SelectDirective`.

<docs-workflow>
<docs-step title="Gerar a directive">
Usando o Angular CLI, execute o seguinte comando, onde `select` é o nome da directive:

```shell
ng generate directive select
```

O Angular cria a classe da directive e especifica o seletor CSS, `[select]`, que identifica a directive em um template.
</docs-step>
<docs-step title="Tornar a directive estrutural {#typing-the-directives-context}">
Importe `TemplateRef` e `ViewContainerRef`. Injete `TemplateRef` e `ViewContainerRef` na directive como propriedades privadas.

```ts
import {Directive, TemplateRef, ViewContainerRef} from '@angular/core';

@Directive({
  selector: '[select]',
})
export class SelectDirective {
  private templateRef = inject(TemplateRef);
  private viewContainerRef = inject(ViewContainerRef);
}

```

</docs-step>
<docs-step title="Adicionar o input 'selectFrom'">
Adicione uma propriedade `input()` `selectFrom`.

```ts
export class SelectDirective {
  // ...

selectFrom = input.required<DataSource>();
}
```

</docs-step>
<docs-step title="Adicionar a lógica de negócio">
Com `SelectDirective` agora estruturada como uma structural directive com seu input, você pode agora adicionar a lógica para buscar os dados e renderizar o template com eles:

```ts
export class SelectDirective {
  // ...

async ngOnInit() {
    const data = await this.selectFrom.load();
    this.viewContainerRef.createEmbeddedView(this.templateRef, {
      // Cria a embedded view com um objeto de contexto que contém
      // os dados através da chave `$implicit`.
      $implicit: data,
    });
  }
}
```

</docs-step>
</docs-workflow>

É isso - `SelectDirective` está pronta e funcionando. Um próximo passo poderia ser [adicionar suporte à verificação de tipo de template](#tipando-o-contexto-da-directive).

## Referência de sintaxe de structural directive {#structural-directive-syntax-reference}

Quando você escreve suas próprias structural directives, use a seguinte sintaxe:

```
_:prefix="( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )_"
```
Os seguintes padrões descrevem cada parte da gramática de structural directive:

```ts
as = :export "as" :local ";"?
keyExp = :key ":"? :expression ("as" :local)? ";"?
let = "let" :local "=" :export ";"?
```

### Como o Angular traduz a sintaxe abreviada

O Angular traduz a sintaxe abreviada de structural directive para a sintaxe de binding normal da seguinte forma:

### Exemplos de sintaxe abreviada

A tabela a seguir fornece exemplos de sintaxe abreviada:

| Abreviado                                                             | Como o Angular interpreta a sintaxe                                                                           |
| :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| `*myDir="let item of [1,2,3]"`                                        | `<ng-template myDir let-item [myDirOf]="[1, 2, 3]">`                                                          |
| `*myDir="let item of [1,2,3] as items; trackBy: myTrack; index as i"` | `<ng-template myDir let-item [myDirOf]="[1,2,3]" let-items="myDirOf" [myDirTrackBy]="myTrack" let-i="index">` |
| `*ngComponentOutlet="componentClass";`                                | `<ng-template [ngComponentOutlet]="componentClass">`                                                          |
| `*ngComponentOutlet="componentClass; inputs: myInputs";`              | `<ng-template [ngComponentOutlet]="componentClass" [ngComponentOutletInputs]="myInputs">`                     |
| `*myDir="exp as value"`                                               | `<ng-template [myDir]="exp" let-value="myDir">`                                                               |

## Melhorando a verificação de tipo de template para directives personalizadas

Você pode melhorar a verificação de tipo de template para directives personalizadas adicionando guards de template à sua definição de directive.
Esses guards ajudam o verificador de tipo de template Angular a encontrar erros no template em tempo de compilação, o que pode evitar erros em runtime.
Dois tipos diferentes de guards são possíveis:

- `ngTemplateGuard_(input)` permite que você controle como uma expressão de input deve ser restringida com base no tipo de um input específico.
- `ngTemplateContextGuard` é usado para determinar o tipo do objeto de contexto para o template, com base no tipo da própria directive.

Esta seção fornece exemplos de ambos os tipos de guards.
Para mais informações, veja [Verificação de tipo de template](tools/cli/template-typecheck 'Guia de verificação de tipo de template').

### Restrição de tipo com template guards

Uma structural directive em um template controla se esse template é renderizado em runtime. Algumas structural directives querem realizar restrição de tipo com base no tipo da expressão de input.

Existem duas restrições possíveis com input guards:

- Restringir a expressão de input com base em uma função de asserção de tipo TypeScript.
- Restringir a expressão de input com base em sua veracidade.

Para restringir a expressão de input definindo uma função de asserção de tipo:

```ts
// Esta directive apenas renderiza seu template se o actor for um usuário.
// Você quer afirmar que dentro do template, o tipo da expressão `actor`
// é restringido para `User`.
@Directive(...)
class ActorIsUser {
  actor = input<User | Robot>();

static ngTemplateGuard_actor(dir: ActorIsUser, expr: User | Robot): expr is User {
    // A declaração de retorno é desnecessária na prática, mas incluída para
    // prevenir erros do TypeScript.
    return true;
  }
}
```

A verificação de tipo se comportará dentro do template como se o `ngTemplateGuard_actor` tivesse sido afirmado na expressão vinculada ao input.

Algumas directives apenas renderizam seus templates quando um input é verdadeiro. Não é possível capturar toda a semântica de veracidade em uma função de asserção de tipo, então, em vez disso, um tipo literal de `'binding'` pode ser usado para sinalizar ao verificador de tipo de template que a própria expressão de binding deve ser usada como guard:

```ts
@Directive(...)
class CustomIf {
  condition = input.required<boolean>();

static ngTemplateGuard_condition: 'binding';
}
```

O verificador de tipo de template se comportará como se a expressão vinculada a `condition` fosse afirmada como verdadeira dentro do template.

### Tipando o contexto da directive

Se sua structural directive fornece um contexto para o template instanciado, você pode tipá-lo adequadamente dentro do template fornecendo uma função de asserção de tipo estática `ngTemplateContextGuard`. Esta função pode usar o tipo da directive para derivar o tipo do contexto, o que é útil quando o tipo da directive é genérico.

Para a `SelectDirective` descrita acima, você pode implementar um `ngTemplateContextGuard` para especificar corretamente o tipo de dados, mesmo se a fonte de dados for genérica.

```ts
// Declare uma interface para o contexto do template:
export interface SelectTemplateContext<T> {
  $implicit: T;
}

@Directive(...)
export class SelectDirective<T> {
  // O tipo genérico `T` da directive será inferido do tipo `DataSource`
  // passado para o input.
  selectFrom = input.required<DataSource<T>>();

// Restringe o tipo do contexto usando o tipo genérico da directive.
  static ngTemplateContextGuard<T>(dir: SelectDirective<T>, ctx: any): ctx is SelectTemplateContext<T> {
    // Como antes, o corpo do guard não é usado em runtime, e incluído apenas para evitar
    // erros do TypeScript.
    return true;
  }
}
```

# Directive composition API

As directives do Angular oferecem uma ótima maneira de encapsular comportamentos reutilizáveis — directives podem aplicar atributos, classes CSS e event listeners a um elemento.

A _directive composition API_ permite que você aplique directives ao elemento host de um component de _dentro_ da classe TypeScript do component.

## Adicionando directives a um component

Você aplica directives a um component adicionando uma propriedade `hostDirectives` ao decorator do component. Chamamos essas directives de _host directives_.

Neste exemplo, aplicamos a directive `MenuBehavior` ao elemento host de `AdminMenu`. Isso funciona de forma similar a aplicar o `MenuBehavior` ao elemento `<admin-menu>` em um template.

```typescript
@Component({
  selector: 'admin-menu',
  template: 'admin-menu.html',
  hostDirectives: [MenuBehavior],
})
export class AdminMenu { }
```

Quando o framework renderiza um component, o Angular também cria uma instância de cada host directive. Os host bindings das directives se aplicam ao elemento host do component. Por padrão, inputs e outputs de host directive não são expostos como parte da API pública do component. Veja [Incluindo inputs e outputs](#including-inputs-and-outputs) abaixo para mais informações.

**O Angular aplica host directives estaticamente em tempo de compilação.** Você não pode adicionar directives dinamicamente em runtime.

**Directives usadas em `hostDirectives` não podem especificar `standalone: false`.**

**O Angular ignora o `selector` de directives aplicadas na propriedade `hostDirectives`.**

## Incluindo inputs e outputs {#including-inputs-and-outputs}

Quando você aplica `hostDirectives` ao seu component, os inputs e outputs das host directives não são incluídos na API do seu component por padrão. Você pode incluir explicitamente inputs e outputs na API do seu component expandindo a entrada em `hostDirectives`:

```typescript
@Component({
  selector: 'admin-menu',
  template: 'admin-menu.html',
  hostDirectives: [{
    directive: MenuBehavior,
    inputs: ['menuId'],
    outputs: ['menuClosed'],
  }],
})
export class AdminMenu { }
```

Ao especificar explicitamente os inputs e outputs, consumidores do component com `hostDirective` podem fazer binding deles em um template:

```html
<admin-menu menuId="top-menu" (menuClosed)="logMenuClosed()">
```

Além disso, você pode criar alias para inputs e outputs de `hostDirective` para personalizar a API do seu component:

```typescript
@Component({
  selector: 'admin-menu',
  template: 'admin-menu.html',
  hostDirectives: [{
    directive: MenuBehavior,
    inputs: ['menuId: id'],
    outputs: ['menuClosed: closed'],
  }],
})
export class AdminMenu { }
```

```html
<admin-menu id="top-menu" (closed)="logMenuClosed()">
```

## Adicionando directives a outra directive

Você também pode adicionar `hostDirectives` a outras directives, além de components. Isso permite a agregação transitiva de múltiplos comportamentos.

No exemplo a seguir, definimos duas directives, `Menu` e `Tooltip`. Então, compomos o comportamento dessas duas directives em `MenuWithTooltip`. Finalmente, aplicamos `MenuWithTooltip` a `SpecializedMenuWithTooltip`.

Quando `SpecializedMenuWithTooltip` é usado em um template, ele cria instâncias de todos `Menu`, `Tooltip` e `MenuWithTooltip`. Os host bindings de cada uma dessas directives se aplicam ao elemento host de `SpecializedMenuWithTooltip`.

```typescript
@Directive({...})
export class Menu { }

@Directive({...})
export class Tooltip { }

// MenuWithTooltip pode compor comportamentos de múltiplas outras directives
@Directive({
  hostDirectives: [Tooltip, Menu],
})
export class MenuWithTooltip { }

// CustomWidget pode aplicar os comportamentos já compostos de MenuWithTooltip
@Directive({
  hostDirectives: [MenuWithTooltip],
})
export class SpecializedMenuWithTooltip { }
```

## Semântica de host directive

### Ordem de execução de directive

Host directives passam pelo mesmo ciclo de vida que components e directives usadas diretamente em um template. No entanto, host directives sempre executam seu constructor, lifecycle hooks e bindings _antes_ do component ou directive no qual são aplicadas.

O exemplo a seguir mostra uso mínimo de uma host directive:

```typescript
@Component({
  selector: 'admin-menu',
  template: 'admin-menu.html',
  hostDirectives: [MenuBehavior],
})
export class AdminMenu { }
```

A ordem de execução aqui é:

1. `MenuBehavior` instanciada
2. `AdminMenu` instanciado
3. `MenuBehavior` recebe inputs (`ngOnInit`)
4. `AdminMenu` recebe inputs (`ngOnInit`)
5. `MenuBehavior` aplica host bindings
6. `AdminMenu` aplica host bindings

Esta ordem de operações significa que components com `hostDirectives` podem sobrescrever quaisquer host bindings especificados por uma host directive.

Esta ordem de operações se estende a cadeias aninhadas de host directives, como mostrado no exemplo a seguir.

```typescript
@Directive({...})
export class Tooltip { }

@Directive({
  hostDirectives: [Tooltip],
})
export class CustomTooltip { }

@Directive({
  hostDirectives: [CustomTooltip],
})
export class EvenMoreCustomTooltip { }
```

No exemplo acima, a ordem de execução é:

1. `Tooltip` instanciada
2. `CustomTooltip` instanciada
3. `EvenMoreCustomTooltip` instanciada
4. `Tooltip` recebe inputs (`ngOnInit`)
5. `CustomTooltip` recebe inputs (`ngOnInit`)
6. `EvenMoreCustomTooltip` recebe inputs (`ngOnInit`)
7. `Tooltip` aplica host bindings
8. `CustomTooltip` aplica host bindings
9. `EvenMoreCustomTooltip` aplica host bindings

### Dependency injection

Um component ou directive que especifica `hostDirectives` pode injetar as instâncias dessas host directives e vice-versa.

Ao aplicar host directives a um component, tanto o component quanto as host directives podem definir providers.

Se um component ou directive com `hostDirectives` e essas host directives ambos fornecem o mesmo injection token, os providers definidos pela classe com `hostDirectives` têm precedência sobre os providers definidos pelas host directives.

# Começando com NgOptimizedImage

A directive `NgOptimizedImage` facilita a adoção de boas práticas de performance para carregamento de imagens.

A directive garante que o carregamento da imagem [Largest Contentful Paint (LCP)](http://web.dev/lcp) seja priorizado ao:

- Configurar automaticamente o atributo `fetchpriority` na tag `<img>`
- Fazer lazy loading de outras imagens por padrão
- Gerar automaticamente uma tag de link preconnect no head do documento
- Gerar automaticamente um atributo `srcset`
- Gerar uma [dica de preload](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload) se a aplicação estiver usando SSR

Além de otimizar o carregamento da imagem LCP, `NgOptimizedImage` aplica várias boas práticas de imagem, tais como:

- Usar [URLs de CDN de imagem para aplicar otimizações de imagem](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options)
- Prevenir layout shift ao exigir `width` e `height`
- Avisar se `width` ou `height` foram configurados incorretamente
- Avisar se a imagem será visualmente distorcida quando renderizada

Se você estiver usando uma imagem de background em CSS, [comece aqui](#how-to-migrate-your-background-image).

**NOTA: Embora a directive `NgOptimizedImage` tenha se tornado uma funcionalidade estável na versão 15 do Angular, ela foi backportada e está disponível como funcionalidade estável nas versões 13.4.0 e 14.3.0 também.**

## Começando

<docs-workflow>
<docs-step title="Importar a directive `NgOptimizedImage`">
Importe a directive `NgOptimizedImage` de `@angular/common`:

```ts
import { NgOptimizedImage } from '@angular/common'

```

e inclua-a no array `imports` de um component standalone ou de um NgModule:

```ts
imports: [
  NgOptimizedImage,
  // ...
],
```

</docs-code>
</docs-step>
<docs-step title="(Opcional) Configurar um Loader">
Um image loader **não é obrigatório** para usar NgOptimizedImage, mas usar um com uma CDN de imagem habilita funcionalidades poderosas de performance, incluindo `srcset`s automáticos para suas imagens.

Um guia breve para configurar um loader pode ser encontrado na seção [Configurando um Image Loader](#configuring-an-image-loader-for-ngoptimizedimage) no final desta página.
</docs-step>
<docs-step title="Ativar a directive {#add-resource-hints}">
Para ativar a directive `NgOptimizedImage`, substitua o atributo `src` da sua imagem por `ngSrc`.

```html
<img ngSrc="cat.jpg">

```

Se você estiver usando um [loader de terceiros nativo](#built-in-loaders), certifique-se de omitir o caminho da URL base do `src`, pois isso será automaticamente adicionado pelo loader.
</docs-step>
<docs-step title="Marcar imagens como `priority`">
Sempre marque a [imagem LCP](https://web.dev/lcp/#what-elements-are-considered) na sua página como `priority` para priorizar seu carregamento.

```html
<img ngSrc="cat.jpg" width="400" height="200" priority>

```

Marcar uma imagem como `priority` aplica as seguintes otimizações:

- Define `fetchpriority=high` (leia mais sobre priority hints [aqui](https://web.dev/priority-hints))
- Define `loading=eager` (leia mais sobre lazy loading nativo [aqui](https://web.dev/browser-level-image-lazy-loading))
- Gera automaticamente um [elemento de link preload](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload) se estiver [renderizando no servidor](guide/ssr).

O Angular exibe um aviso durante o desenvolvimento se o elemento LCP é uma imagem que não tem o atributo `priority`. O elemento LCP de uma página pode variar baseado em vários fatores - como as dimensões da tela de um usuário, então uma página pode ter múltiplas imagens que devem ser marcadas como `priority`. Veja [CSS for Web Vitals](https://web.dev/css-web-vitals/#images-and-largest-contentful-paint-lcp) para mais detalhes.
</docs-step>
<docs-step title="Incluir Width e Height">
Para prevenir [layout shifts relacionados a imagens](https://web.dev/css-web-vitals/#images-and-layout-shifts), NgOptimizedImage requer que você especifique altura e largura para sua imagem, da seguinte forma:

```html
<img ngSrc="cat.jpg" width="400" height="200">

```

Para **imagens responsivas** (imagens que você estilizou para crescer e diminuir em relação ao viewport), os atributos `width` e `height` devem ser o tamanho intrínseco do arquivo de imagem. Para imagens responsivas também é importante [definir um valor para `sizes`.](#responsive-images)

Para **imagens de tamanho fixo**, os atributos `width` e `height` devem refletir o tamanho de renderização desejado da imagem. A proporção desses atributos deve sempre corresponder à proporção intrínseca da imagem.

NOTA: Se você não souber o tamanho de suas imagens, considere usar o "fill mode" para herdar o tamanho do container pai, conforme descrito abaixo.
</docs-step>
</docs-workflow>

## Usando o modo `fill` {#using-fill-mode} {#responsive-images}

Nos casos em que você deseja que uma imagem preencha um elemento container, você pode usar o atributo `fill`. Isso é frequentemente útil quando você quer obter um comportamento de "imagem de background". Também pode ser útil quando você não sabe a largura e altura exatas da sua imagem, mas você tem um container pai com um tamanho conhecido no qual você gostaria de ajustar sua imagem (veja "object-fit" abaixo).

Quando você adiciona o atributo `fill` à sua imagem, você não precisa e não deve incluir `width` e `height`, como neste exemplo:

```html
<img ngSrc="cat.jpg" fill>

```

Você pode usar a propriedade CSS [object-fit](https://developer.mozilla.org/docs/Web/CSS/object-fit) para mudar como a imagem preencherá seu container. Se você estilizar sua imagem com `object-fit: "contain"`, a imagem manterá sua proporção e será "letterboxed" para caber no elemento. Se você definir `object-fit: "cover"`, o elemento reterá sua proporção, preencherá completamente o elemento, e algum conteúdo pode ser "cortado".

Veja exemplos visuais do acima na [documentação object-fit do MDN.](https://developer.mozilla.org/docs/Web/CSS/object-fit)

Você também pode estilizar sua imagem com a [propriedade object-position](https://developer.mozilla.org/docs/Web/CSS/object-position) para ajustar sua posição dentro de seu elemento container.

IMPORTANTE: Para que a imagem "fill" renderize adequadamente, seu elemento pai **deve** ser estilizado com `position: "relative"`, `position: "fixed"`, ou `position: "absolute"`.

## Como migrar sua imagem de background {#how-to-migrate-your-background-image}

Aqui está um processo simples passo a passo para migrar de `background-image` para `NgOptimizedImage`. Para estes passos, vamos nos referir ao elemento que tem uma imagem de background como o "elemento container":

1. Remova o estilo `background-image` do elemento container.
2. Certifique-se de que o elemento container tem `position: "relative"`, `position: "fixed"`, ou `position: "absolute"`.
3. Crie um novo elemento de imagem como filho do elemento container, usando `ngSrc` para habilitar a directive `NgOptimizedImage`.
4. Dê a esse elemento o atributo `fill`. Não inclua `height` e `width`.
5. Se você acredita que esta imagem pode ser seu [elemento LCP](https://web.dev/lcp/), adicione o atributo `priority` ao elemento de imagem.

Você pode ajustar como a imagem de background preenche o container conforme descrito na seção [Usando o modo fill](#using-fill-mode).

## Usando placeholders

### Placeholders automáticos

NgOptimizedImage pode exibir um placeholder automático de baixa resolução para sua imagem se você estiver usando uma CDN ou host de imagem que fornece redimensionamento automático de imagem. Aproveite essa funcionalidade adicionando o atributo `placeholder` à sua imagem:

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder>

```

Adicionar este atributo solicita automaticamente uma segunda versão menor da imagem usando seu loader de imagem especificado. Esta imagem pequena será aplicada como um estilo `background-image` com um blur CSS enquanto sua imagem carrega. Se nenhum loader de imagem for fornecido, nenhuma imagem placeholder pode ser gerada e um erro será lançado.

O tamanho padrão para placeholders gerados é 30px de largura. Você pode mudar este tamanho especificando um valor em pixels no provider `IMAGE_CONFIG`, conforme visto abaixo:

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      placeholderResolution: 40
    }
  },
],
```

Se você quiser bordas nítidas ao redor do seu placeholder desfocado, você pode envolver sua imagem em uma `<div>` container com o estilo `overflow: hidden`. Desde que a `<div>` seja do mesmo tamanho da imagem (como usando o estilo `width: fit-content`), as "bordas difusas" do placeholder ficarão ocultas.

### Placeholders de Data URL {#optional-set-up-a-loader}

Você também pode especificar um placeholder usando uma [data URL](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) base64 sem um loader de imagem. O formato da data url é `data:image/[imagetype];[data]`, onde `[imagetype]` é o formato da imagem, como `png`, e `[data]` é uma codificação base64 da imagem. Essa codificação pode ser feita usando a linha de comando ou em JavaScript. Para comandos específicos, veja [a documentação do MDN](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs#encoding_data_into_base64_format). Um exemplo de um placeholder de data URL com dados truncados é mostrado abaixo:

```html
<img
  ngSrc="cat.jpg"
  width="400"
  height="200"
  placeholder="data:image/png;base64,iVBORw0K..."
/>

```

No entanto, grandes data URLs aumentam o tamanho de seus bundles Angular e diminuem o carregamento da página. Se você não puder usar um loader de imagem, o time do Angular recomenda manter imagens placeholder base64 menores que 4KB e usá-las exclusivamente em imagens críticas. Além de diminuir as dimensões do placeholder, considere mudar formatos de imagem ou parâmetros usados ao salvar imagens. Em resoluções muito baixas, esses parâmetros podem ter um grande efeito no tamanho do arquivo.

### Placeholders sem blur

Por padrão, NgOptimizedImage aplica um efeito de blur CSS aos placeholders de imagem. Para renderizar um placeholder sem blur, forneça um argumento `placeholderConfig` com um objeto que inclui a propriedade `blur`, definida como false. Por exemplo:

```html
<img
ngSrc="cat.jpg"
width="400"
height="200"
placeholder
[placeholderConfig]="{blur: false}"
/>
```

## Ajustando a estilização da imagem

Dependendo da estilização da imagem, adicionar atributos `width` e `height` pode fazer com que a imagem seja renderizada de forma diferente. `NgOptimizedImage` avisa você se a estilização da sua imagem renderiza a imagem com uma proporção distorcida.

Você pode tipicamente corrigir isso adicionando `height: auto` ou `width: auto` aos seus estilos de imagem. Para mais informações, veja o [artigo web.dev sobre a tag `<img>`](https://web.dev/patterns/web-vitals-patterns/images/img-tag).

Se os atributos `width` e `height` na imagem estiverem impedindo você de dimensionar a imagem da forma que deseja com CSS, considere usar o modo `fill` em vez disso, e estilizar o elemento pai da imagem.

## Funcionalidades de Performance

NgOptimizedImage inclui várias funcionalidades projetadas para melhorar a performance de carregamento na sua aplicação. Essas funcionalidades são descritas nesta seção.

### Adicionar resource hints {#advanced-sizes-values}

Uma [resource hint `preconnect`](https://web.dev/preconnect-and-dns-prefetch) para a origem da sua imagem garante que a imagem LCP carregue o mais rápido possível.

Links preconnect são gerados automaticamente para domínios fornecidos como argumento para um [loader](#optional-set-up-a-loader). Se uma origem de imagem não puder ser identificada automaticamente, e nenhum link preconnect for detectado para a imagem LCP, `NgOptimizedImage` avisará durante o desenvolvimento. Nesse caso, você deve adicionar manualmente um resource hint ao `index.html`. Dentro do `<head>` do documento, adicione uma tag `link` com `rel="preconnect"`, como mostrado abaixo:

```html
<link rel="preconnect" href="https://my.cdn.origin" />

```

Para desabilitar avisos de preconnect, injete o token `PRECONNECT_CHECK_BLOCKLIST`:

```ts
providers: [
{provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
],

```

Veja mais informações sobre geração automática de preconnect [aqui](#why-is-a-preconnect-element-not-being-generated-for-my-image-domain).

### Solicitar imagens no tamanho correto com `srcset` automático

Definir um [atributo `srcset`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/srcset) garante que o browser solicite uma imagem no tamanho certo para o viewport do seu usuário, então ele não perde tempo baixando uma imagem que é muito grande. `NgOptimizedImage` gera um `srcset` apropriado para a imagem, baseado na presença e valor do [atributo `sizes`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) na tag de imagem.

#### Imagens de tamanho fixo

Se sua imagem deve ser "fixa" em tamanho (ou seja, do mesmo tamanho em todos os dispositivos, exceto para [densidade de pixel](https://web.dev/codelab-density-descriptors/)), não há necessidade de definir um atributo `sizes`. Um `srcset` pode ser gerado automaticamente a partir dos atributos width e height da imagem sem mais nenhuma entrada necessária.

Exemplo de srcset gerado:

```html
<img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x">
```

#### Imagens responsivas {#responsive-images}

Se sua imagem deve ser responsiva (ou seja, crescer e diminuir de acordo com o tamanho do viewport), então você precisará definir um [atributo `sizes`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) para gerar o `srcset`.

Se você não usou `sizes` antes, um bom lugar para começar é defini-lo baseado na largura do viewport. Por exemplo, se seu CSS faz com que a imagem preencha 100% da largura do viewport, defina `sizes` para `100vw` e o browser selecionará a imagem no `srcset` que está mais próxima da largura do viewport (depois de considerar a densidade de pixel). Se sua imagem provavelmente ocupará apenas metade da tela (ex: em uma sidebar), defina `sizes` para `50vw` para garantir que o browser selecione uma imagem menor. E assim por diante.

Se você achar que o acima não cobre o comportamento desejado da sua imagem, veja a documentação sobre [valores avançados de sizes](#advanced-sizes-values).

Note que `NgOptimizedImage` automaticamente adiciona `"auto"` ao valor de `sizes` fornecido. Esta é uma otimização que aumenta a precisão da seleção de srcset em browsers que suportam `sizes="auto"`, e é ignorada por browsers que não suportam.

Por padrão, os breakpoints responsivos são:

`[16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840]`

Se você quiser customizar esses breakpoints, você pode fazer isso usando o provider `IMAGE_CONFIG`:

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      breakpoints: [16, 48, 96, 128, 384, 640, 750, 828, 1080, 1200, 1920]
    }
  },
],
```

Se você quiser definir manualmente um atributo `srcset`, você pode fornecer o seu próprio usando o atributo `ngSrcset`:

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w">

```

Se o atributo `ngSrcset` estiver presente, `NgOptimizedImage` gera e define o `srcset` baseado nos tamanhos incluídos. Não inclua nomes de arquivo de imagem no `ngSrcset` - a directive infere essa informação do `ngSrc`. A directive suporta tanto descritores de largura (ex: `100w`) quanto descritores de densidade (ex: `1x`).

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw">

```

### Desabilitando a geração automática de srcset

Para desabilitar a geração de srcset para uma única imagem, você pode adicionar o atributo `disableOptimizedSrcset` na imagem:

```html
<img ngSrc="about.jpg" disableOptimizedSrcset>

```

### Desabilitando lazy loading de imagem

Por padrão, `NgOptimizedImage` define `loading=lazy` para todas as imagens que não estão marcadas como `priority`. Você pode desabilitar esse comportamento para imagens não-priority definindo o atributo `loading`. Este atributo aceita valores: `eager`, `auto`, e `lazy`. [Veja a documentação para o atributo `loading` de imagem padrão para detalhes](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/loading#value).

```html
<img ngSrc="cat.jpg" width="400" height="200" loading="eager">

```

### Controlando a decodificação da imagem

Por padrão, `NgOptimizedImage` define `decoding="auto"` para todas as imagens. Isso permite que o browser decida o momento ideal para decodificar uma imagem depois que ela foi baixada. Quando uma imagem é marcada como `priority`, o Angular automaticamente define `decoding="sync"` para garantir que a imagem seja decodificada e pintada o mais cedo possível ajudando a melhorar a performance de **Largest Contentful Paint (LCP)**.

Você ainda pode sobrescrever esse comportamento definindo explicitamente o atributo `decoding`.
[Veja a documentação para o atributo `decoding` de imagem padrão para detalhes](https://developer.mozilla.org/docs/Web/HTML/Element/img#decoding).

```html

<img ngSrc="gallery/landscape.jpg" width="1200" height="800">

<img ngSrc="gallery/preview.jpg" width="600" height="400" decoding="async">

<img ngSrc="awesome.jpg" width="500" height="625" priority >

<img ngSrc="hero.jpg" width="1600" height="900" decoding="sync">
```

**Valores permitidos**

- `auto` (padrão): deixa o browser escolher a estratégia ideal.
- `async`: decodifica a imagem assincronamente, evitando bloqueio da thread principal quando possível.
- `sync`: decodifica a imagem imediatamente; pode bloquear a renderização mas garante que os pixels estejam prontos assim que a imagem estiver disponível.

### Valores avançados de 'sizes' {#the-loaderparams-property}

Você pode querer ter imagens exibidas em larguras variadas em telas de tamanhos diferentes. Um exemplo comum desse padrão é um layout baseado em grid ou colunas que renderiza uma única coluna em dispositivos móveis, e duas colunas em dispositivos maiores. Você pode capturar esse comportamento no atributo `sizes`, usando uma sintaxe de "media query", como a seguinte:

```html
<img ngSrc="cat.jpg" width="400" height="200" sizes="(max-width: 768px) 100vw, 50vw">

```

O atributo `sizes` no exemplo acima diz "Eu espero que esta imagem seja 100 por cento da largura da tela em dispositivos com menos de 768px de largura. Caso contrário, eu espero que seja 50 por cento da largura da tela.

Para informações adicionais sobre o atributo `sizes`, veja [web.dev](https://web.dev/learn/design/responsive-images/#sizes) ou [mdn](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes).

## Configurando um image loader para `NgOptimizedImage` {#configuring-an-image-loader-for-ngoptimizedimage}

Um "loader" é uma função que gera uma [URL de transformação de imagem](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options) para um determinado arquivo de imagem. Quando apropriado, `NgOptimizedImage` define o tamanho, formato e transformações de qualidade de imagem para uma imagem.

`NgOptimizedImage` fornece tanto um loader genérico que não aplica transformações, quanto loaders para vários serviços de imagem de terceiros. Ele também suporta escrever seu próprio loader customizado.

| Tipo de loader                               | Comportamento                                                                                                                                                                                                                               |
| :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Loader genérico                              | A URL retornada pelo loader genérico sempre corresponderá ao valor de `src`. Em outras palavras, este loader não aplica transformações. Sites que usam Angular para servir imagens são o caso de uso principal pretendido para este loader. |
| Loaders para serviços de imagem de terceiros | A URL retornada pelos loaders para serviços de imagem de terceiros seguirá as convenções da API usadas por aquele serviço de imagem específico.                                                                                             |
| Loaders customizados                         | O comportamento de um loader customizado é definido por seu desenvolvedor. Você deve usar um loader customizado se seu serviço de imagem não for suportado pelos loaders que vêm pré-configurados com `NgOptimizedImage`.                   |

Baseado nos serviços de imagem comumente usados com aplicações Angular, `NgOptimizedImage` fornece loaders pré-configurados para trabalhar com os seguintes serviços de imagem:

Para usar o **loader genérico** nenhuma mudança adicional de código é necessária. Este é o comportamento padrão.

### Loaders Nativos {#built-in-loaders}

Para usar um loader existente para um **serviço de imagem de terceiros**, adicione a factory do provider para seu serviço escolhido ao array `providers`. No exemplo abaixo, o loader Imgix é usado:

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

A URL base para seus assets de imagem deve ser passada para a factory do provider como um argumento. Para a maioria dos sites, esta URL base deve corresponder a um dos seguintes padrões:

- <https://yoursite.yourcdn.com>
- <https://subdomain.yoursite.com>
- <https://subdomain.yourcdn.com/yoursite>

Você pode aprender mais sobre a estrutura da URL base nos documentos de um provider CDN correspondente.

### Loaders Customizados {#custom-loaders}

Para usar um **loader customizado**, forneça sua função de loader como um valor para o token DI `IMAGE_LOADER`. No exemplo abaixo, a função de loader customizado retorna uma URL começando com `https://example.com` que inclui `src` e `width` como parâmetros de URL.

```ts
providers: [
  {
    provide: IMAGE_LOADER,
    useValue: (config: ImageLoaderConfig) => {
      return `https://example.com/images?src=${config.src}&width=${config.width}`;
    },
  },
],
```

Uma função de loader para a directive `NgOptimizedImage` recebe um objeto com o tipo `ImageLoaderConfig` (de `@angular/common`) como seu argumento e retorna a URL absoluta do asset de imagem. O objeto `ImageLoaderConfig` contém a propriedade `src`, e propriedades opcionais `width` e `loaderParams`.

NOTA: mesmo que a propriedade `width` possa nem sempre estar presente, um loader customizado deve usá-la para suportar solicitação de imagens em várias larguras para que `ngSrcset` funcione corretamente.

### A Propriedade `loaderParams`

Há um atributo adicional suportado pela directive `NgOptimizedImage`, chamado `loaderParams`, que é especificamente projetado para suportar o uso de loaders customizados. O atributo `loaderParams` recebe um objeto com quaisquer propriedades como valor, e não faz nada por conta própria. Os dados em `loaderParams` são adicionados ao objeto `ImageLoaderConfig` passado para seu loader customizado, e podem ser usados para controlar o comportamento do loader.

Um uso comum para `loaderParams` é controlar funcionalidades avançadas de CDN de imagem.

### Exemplo de loader customizado

O seguinte mostra um exemplo de uma função de loader customizado. Esta função de exemplo concatena `src` e `width`, e usa `loaderParams` para controlar uma funcionalidade customizada de CDN para cantos arredondados:

```ts
const myCustomLoader = (config: ImageLoaderConfig) => {
  let url = `https://example.com/images/${config.src}?`;
  let queryParams = [];
  if (config.width) {
    queryParams.push(`w=${config.width}`);
  }
  if (config.loaderParams?.roundedCorners) {
    queryParams.push('mask=corners&corner-radius=5');
  }
  return url + queryParams.join('&');
};
```

Note que no exemplo acima, inventamos o nome da propriedade 'roundedCorners' para controlar uma funcionalidade do nosso loader customizado. Poderíamos então usar essa funcionalidade ao criar uma imagem, da seguinte forma:

```html
<img ngSrc="profile.jpg" width="300" height="300" [loaderParams]="{roundedCorners: true}">

```

## Perguntas Frequentes

### NgOptimizedImage suporta a propriedade css `background-image`?

NgOptimizedImage não suporta diretamente a propriedade css `background-image`, mas é projetado para facilmente acomodar o caso de uso de ter uma imagem como background de outro elemento.

Para um processo passo a passo para migração de `background-image` para `NgOptimizedImage`, veja a seção [Como migrar sua imagem de background](#how-to-migrate-your-background-image) acima.

### Por que não posso usar `src` com `NgOptimizedImage`?

O atributo `ngSrc` foi escolhido como gatilho para NgOptimizedImage devido a considerações técnicas sobre como imagens são carregadas pelo browser. NgOptimizedImage faz mudanças programáticas no atributo `loading` -- se o browser vir o atributo `src` antes que essas mudanças sejam feitas, ele começará a baixar avidamente o arquivo de imagem, e as mudanças de carregamento serão ignoradas.

### Por que um elemento preconnect não está sendo gerado para meu domínio de imagem?

A geração de preconnect é realizada baseada em análise estática de sua aplicação. Isso significa que o domínio da imagem deve estar diretamente incluído no parâmetro do loader, como no seguinte exemplo:

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

Se você usar uma variável para passar a string de domínio para o loader, ou você não estiver usando um loader, a análise estática não será capaz de identificar o domínio, e nenhum link preconnect será gerado. Neste caso você deve adicionar manualmente um link preconnect ao head do documento, como [descrito acima](#advanced-sizes-values).

### Posso usar dois domínios de imagem diferentes na mesma página?

O padrão de provider de [loaders de imagem](#configuring-an-image-loader-for-ngoptimizedimage) é projetado para ser o mais simples possível para o caso de uso comum de ter apenas uma única CDN de imagem usada dentro de um component. No entanto, ainda é muito possível gerenciar múltiplas CDNs de imagem usando um único provider.

Para fazer isso, recomendamos escrever um [loader de imagem customizado](#custom-loaders) que use a [propriedade `loaderParams`](#the-loaderparams-property) para passar uma flag que especifica qual CDN de imagem deve ser usada, e então invoca o loader apropriado baseado nessa flag.

### Vocês podem adicionar um novo loader nativo para minha CDN preferida? {#why-is-a-preconnect-element-not-being-generated-for-my-image-domain}

Por razões de manutenção, atualmente não planejamos suportar loaders nativos adicionais no repositório Angular. Em vez disso, encorajamos desenvolvedores a publicar quaisquer loaders de imagem adicionais como pacotes de terceiros.

### Posso usar isso com a tag `<picture>`

Não, mas isso está no nosso roadmap, então fique ligado.

Se você estiver esperando por essa funcionalidade, por favor vote positivamente na issue do Github [aqui](https://github.com/angular/angular/issues/56594).

### Como encontro minha imagem LCP com o Chrome DevTools?

1. Usando a aba performance do Chrome DevTools, clique no botão "start profiling and reload page" no canto superior esquerdo. Ele se parece com um ícone de atualização de página.

2. Isso acionará um snapshot de profiling da sua aplicação Angular.

3. Uma vez que o resultado do profiling esteja disponível, selecione "LCP" na seção timings.

4. Uma entrada de resumo deve aparecer no painel na parte inferior. Você pode encontrar o elemento LCP na linha para "related node". Clicar nele revelará o elemento no painel Elements.

NOTA: Isso apenas identifica o elemento LCP dentro do viewport da página que você está testando. Também é recomendado usar emulação mobile para identificar o elemento LCP para telas menores.

No Angular, você usa _signals_ para criar e gerenciar estado. Um signal é um wrapper leve em torno de um valor.

Use a função `signal` para criar um signal para armazenar estado local:

```typescript
import {signal} from '@angular/core';

// Create a signal with the `signal` function.
const firstName = signal('Morgan');

// Read a signal value by calling it— signals are functions.
console.log(firstName());

// Change the value of this signal by calling its `set` method with a new value.
firstName.set('Jaime');

// You can also use the `update` method to change the value
// based on the previous value.
firstName.update(name => name.toUpperCase());
```

O Angular rastreia onde os signals são lidos e quando são atualizados. O framework usa essa informação para realizar trabalhos adicionais, como atualizar o DOM com o novo estado. Essa capacidade de responder a valores de signal que mudam ao longo do tempo é conhecida como _reatividade_.

## Expressões computed

Um `computed` é um signal que produz seu valor com base em outros signals.

```typescript
import {signal, computed} from '@angular/core';

const firstName = signal('Morgan');
const firstNameCapitalized = computed(() => firstName().toUpperCase());

console.log(firstNameCapitalized()); // MORGAN
```

Um signal `computed` é somente leitura; ele não possui um método `set` ou `update`. Em vez disso, o valor do signal `computed` muda automaticamente quando qualquer um dos signals que ele lê muda:

```typescript
import {signal, computed} from '@angular/core';

const firstName = signal('Morgan');
const firstNameCapitalized = computed(() => firstName().toUpperCase());
console.log(firstNameCapitalized()); // MORGAN

firstName.set('Jaime');
console.log(firstNameCapitalized()); // JAIME
```

## Usando signals em components

Use `signal` e `computed` dentro de seus components para criar e gerenciar estado:

```typescript
@Component({/* ... */})
export class UserProfile {
  isTrial = signal(false);
  isTrialExpired = signal(false);
  showTrialDuration = computed(() => this.isTrial() && !this.isTrialExpired());

activateTrial() {
    this.isTrial.set(true);
  }
}
```

DICA: Quer saber mais sobre Angular Signals? Consulte o [guia detalhado de Signals](guide/signals) para todos os detalhes.

## Próximo Passo

Agora que você aprendeu como declarar e gerenciar dados dinâmicos, é hora de aprender como usar esses dados dentro de templates.

# Estado dependente com `linkedSignal`

Você pode usar a função `signal` para armazenar algum estado no seu código Angular. Às vezes, este estado depende de algum _outro_ estado. Por exemplo, imagine um component que permite ao usuário selecionar um método de envio para um pedido:

```typescript
@Component({/* ... */})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// Select the first shipping option by default.
  selectedOption = signal(this.shippingOptions()[0]);

changeShipping(newOptionIndex: number) {
    this.selectedOption.set(this.shippingOptions()[newOptionIndex]);
  }
}
```

Neste exemplo, o `selectedOption` usa como padrão a primeira opção, mas muda se o usuário selecionar outra opção. Mas `shippingOptions` é um signal— seu valor pode mudar! Se `shippingOptions` muda, `selectedOption` pode conter um valor que não é mais uma opção válida.

**A função `linkedSignal` permite que você crie um signal para armazenar algum estado que está intrinsecamente _vinculado_ a algum outro estado.** Revisitando o exemplo acima, `linkedSignal` pode substituir `signal`:

```typescript
@Component({/* ... */})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// Initialize selectedOption to the first shipping option.
  selectedOption = linkedSignal(() => this.shippingOptions()[0]);

changeShipping(index: number) {
    this.selectedOption.set(this.shippingOptions()[index]);
  }
}
```

`linkedSignal` funciona de forma similar ao `signal` com uma diferença chave— em vez de passar um valor padrão, você passa uma _função de computação_, assim como `computed`. Quando o valor da computação muda, o valor do `linkedSignal` muda para o resultado da computação. Isso ajuda a garantir que o `linkedSignal` sempre tenha um valor válido.

O exemplo a seguir mostra como o valor de um `linkedSignal` pode mudar com base em seu estado vinculado:

```typescript
const shippingOptions = signal(['Ground', 'Air', 'Sea']);
const selectedOption = linkedSignal(() => shippingOptions()[0]);
console.log(selectedOption()); // 'Ground'

selectedOption.set(shippingOptions()[2]);
console.log(selectedOption()); // 'Sea'

shippingOptions.set(['Email', 'Will Call', 'Postal service']);
console.log(selectedOption()); // 'Email'
```

## Considerando o estado anterior

Em alguns casos, a computação para um `linkedSignal` precisa considerar o valor anterior do `linkedSignal`.

No exemplo acima, `selectedOption` sempre atualiza de volta para a primeira opção quando `shippingOptions` muda. Você pode, no entanto, querer preservar a seleção do usuário se sua opção selecionada ainda estiver em algum lugar da lista. Para realizar isso, você pode criar um `linkedSignal` com uma _source_ e _computation_ separadas:

```typescript
interface ShippingMethod {
  id: number;
  name: string;
}

@Component({/* ... */})
export class ShippingMethodPicker {
  constructor() {
    this.changeShipping(2);
    this.changeShippingOptions();
    console.log(this.selectedOption()); // {"id":2,"name":"Postal Service"}
  }

shippingOptions = signal<ShippingMethod[]>([
    { id: 0, name: 'Ground' },
    { id: 1, name: 'Air' },
    { id: 2, name: 'Sea' },
  ]);

selectedOption = linkedSignal<ShippingMethod[], ShippingMethod>({
    // `selectedOption` is set to the `computation` result whenever this `source` changes.
    source: this.shippingOptions,
    computation: (newOptions, previous) => {
      // If the newOptions contain the previously selected option, preserve that selection.
      // Otherwise, default to the first option.
      return (
        newOptions.find((opt) => opt.id === previous?.value.id) ?? newOptions[0]
      );
    },
  });

changeShipping(index: number) {
    this.selectedOption.set(this.shippingOptions()[index]);
  }

changeShippingOptions() {
    this.shippingOptions.set([
      { id: 0, name: 'Email' },
      { id: 1, name: 'Sea' },
      { id: 2, name: 'Postal Service' },
    ]);
  }
}
```

Quando você cria um `linkedSignal`, você pode passar um objeto com propriedades `source` e `computation` separadas em vez de fornecer apenas uma computação.

A `source` pode ser qualquer signal, como um `computed` ou `input` de component. Quando o valor de `source` muda, `linkedSignal` atualiza seu valor para o resultado da `computation` fornecida.

A `computation` é uma função que recebe o novo valor de `source` e um objeto `previous`. O objeto `previous` tem duas propriedades— `previous.source` é o valor anterior de `source`, e `previous.value` é o valor anterior do `linkedSignal`. Você pode usar esses valores anteriores para decidir o novo resultado da computação.

HELPFUL: Ao usar o parâmetro `previous`, é necessário fornecer os argumentos de tipo genérico de `linkedSignal` explicitamente. O primeiro tipo genérico corresponde ao tipo de `source` e o segundo tipo genérico determina o tipo de saída de `computation`.

## Comparação de igualdade customizada

`linkedSignal`, como qualquer outro signal, pode ser configurado com uma função de igualdade customizada. Esta função é usada por dependências downstream para determinar se o valor do `linkedSignal` (resultado de uma computação) mudou:

```typescript
const activeUser = signal({id: 123, name: 'Morgan', isAdmin: true});

const activeUserEditCopy = linkedSignal(() => activeUser(), {
  // Consider the user as the same if it's the same `id`.
  equal: (a, b) => a.id === b.id,
});

// Or, if separating `source` and `computation`
const activeUserEditCopy = linkedSignal({
  source: activeUser,
  computation: user => user,
  equal: (a, b) => a.id === b.id,
});
```

# Reatividade assíncrona com resources

IMPORTANT: `resource` é [experimental](reference/releases#experimental). Está pronto para você experimentar, mas pode mudar antes de se tornar estável.

A maioria das APIs de signal são síncronas— `signal`, `computed`, `input`, etc. No entanto, aplicações frequentemente precisam lidar com dados que estão disponíveis de forma assíncrona. Um `Resource` fornece uma maneira de incorporar dados assíncronos no código baseado em signals da sua aplicação.

Você pode usar um `Resource` para realizar qualquer tipo de operação assíncrona, mas o caso de uso mais comum para `Resource` é buscar dados de um servidor. O exemplo a seguir cria um resource para buscar alguns dados de usuário.

A maneira mais fácil de criar um `Resource` é a função `resource`.

```typescript
import {resource, Signal} from '@angular/core';

const userId: Signal<string> = getUserId();

const userResource = resource({
  // Define a reactive computation.
  // The params value recomputes whenever any read signals change.
  params: () => ({id: userId()}),

// Define an async loader that retrieves data.
  // The resource calls this function every time the `params` value changes.
  loader: ({params}) => fetchUser(params),
});

// Create a computed signal based on the result of the resource's loader function.
const firstName = computed(() => {
  if (userResource.hasValue()) {
    // `hasValue` serves 2 purposes:
    // - It acts as type guard to strip `undefined` from the type
    // - If protects against reading a throwing `value` when the resource is in error state
    return userResource.value().firstName;
  }

// fallback in case the resource value is `undefined` or if the resource is in error state
  return undefined;
});
```

A função `resource` aceita um objeto `ResourceOptions` com duas propriedades principais: `params` e `loader`.

A propriedade `params` define uma computação reativa que produz um valor de parâmetro. Sempre que signals lidos nesta computação mudam, o resource produz um novo valor de parâmetro, semelhante ao `computed`.

A propriedade `loader` define um `ResourceLoader`— uma função assíncrona que recupera algum estado. O resource chama o loader toda vez que a computação `params` produz um novo valor, passando esse valor para o loader. Veja [Resource loaders](#resource-loaders) abaixo para mais detalhes.

`Resource` tem um signal `value` que contém os resultados do loader.

## Resource loaders

Ao criar um resource, você especifica um `ResourceLoader`. Este loader é uma função assíncrona que aceita um único parâmetro— um objeto `ResourceLoaderParams`— e retorna um valor.

O objeto `ResourceLoaderParams` contém três propriedades: `params`, `previous` e `abortSignal`.

| Propriedade   | Descrição                                                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`      | O valor da computação `params` do resource.                                                                                                            |
| `previous`    | Um objeto com uma propriedade `status`, contendo o `ResourceStatus` anterior.                                                                          |
| `abortSignal` | Um [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). Veja [Abortar requisições](#aborting-requests) abaixo para detalhes. |

Se a computação `params` retorna `undefined`, a função loader não executa e o status do resource se torna `'idle'`.

### Abortar requisições {#aborting-requests}

Um resource aborta uma operação de carregamento pendente se a computação `params` mudar enquanto o resource está carregando.

Você pode usar o `abortSignal` em `ResourceLoaderParams` para responder a requisições abortadas. Por exemplo, a função nativa `fetch` aceita um `AbortSignal`:

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params, abortSignal}): Promise<User> => {
    // fetch cancels any outstanding HTTP requests when the given `AbortSignal`
    // indicates that the request has been aborted.
    return fetch(`users/${params.id}`, {signal: abortSignal});
  },
});
```

Veja [`AbortSignal` no MDN](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) para mais detalhes sobre cancelamento de requisição com `AbortSignal`.

### Recarregar

Você pode acionar programaticamente o `loader` de um resource chamando o método `reload`.

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

// ...

userResource.reload();
```

## Status do Resource

O objeto resource tem várias propriedades signal para ler o status do loader assíncrono.

| Propriedade | Descrição                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| `value`     | O valor mais recente do resource, ou `undefined` se nenhum valor foi recebido.                          |
| `hasValue`  | Se o resource tem um valor.                                                                             |
| `error`     | O erro mais recente encontrado ao executar o loader do resource, ou `undefined` se nenhum erro ocorreu. |
| `isLoading` | Se o loader do resource está em execução atualmente.                                                    |
| `status`    | O `ResourceStatus` específico do resource, conforme descrito abaixo.                                    |

O signal `status` fornece um `ResourceStatus` específico que descreve o estado do resource usando uma constante string.

| Status        | `value()`                 | Descrição                                                                           |
| ------------- | :------------------------ | ----------------------------------------------------------------------------------- |
| `'idle'`      | `undefined`               | O resource não tem requisição válida e o loader não foi executado.                  |
| `'error'`     | `undefined`               | O loader encontrou um erro.                                                         |
| `'loading'`   | `undefined`               | O loader está em execução como resultado da mudança do valor `params`.              |
| `'reloading'` | Valor anterior            | O loader está em execução como resultado da chamada do método `reload` do resource. |
| `'resolved'`  | Valor resolvido           | O loader foi concluído.                                                             |
| `'local'`     | Valor definido localmente | O valor do resource foi definido localmente via `.set()` ou `.update()`             |

Você pode usar essas informações de status para exibir condicionalmente elementos de interface do usuário, como indicadores de carregamento e mensagens de erro.

## Busca de dados reativa com `httpResource`

[`httpResource`](/guide/http/http-resource) é um wrapper em torno do `HttpClient` que fornece o status da requisição e a resposta como signals. Ele faz requisições HTTP através da pilha HTTP do Angular, incluindo interceptors.

# Criando um service injetável

Service é uma categoria ampla que abrange qualquer valor, função ou recurso que uma aplicação precisa.
Um service é tipicamente uma classe com um propósito restrito e bem definido.
Um component é um tipo de classe que pode usar DI.

O Angular distingue components de services para aumentar a modularidade e reutilização.
Ao separar os recursos relacionados à visualização de um component de outros tipos de processamento, você pode tornar suas classes de component enxutas e eficientes.

Idealmente, o trabalho de um component é habilitar a experiência do usuário e nada mais.
Um component deve apresentar propriedades e métodos para data binding, para mediar entre a view (renderizada pelo template) e a lógica da aplicação (que frequentemente inclui alguma noção de um modelo).

Um component pode delegar certas tarefas a services, como buscar dados do servidor, validar entrada do usuário ou fazer log diretamente no console.
Ao definir tais tarefas de processamento em uma classe de service injetável, você torna essas tarefas disponíveis para qualquer component.
Você também pode tornar sua aplicação mais adaptável configurando diferentes providers do mesmo tipo de service, conforme apropriado em diferentes circunstâncias.

O Angular não impõe esses princípios.
O Angular ajuda você a seguir esses princípios tornando fácil fatorar a lógica da sua aplicação em services e tornar esses services disponíveis para components através de DI.

## Exemplos de service

Aqui está um exemplo de uma classe de service que faz log no console do navegador:

```
export class Logger {
  log(msg: unknown) { console.log(msg); }
  error(msg: unknown) { console.error(msg); }
  warn(msg: unknown) { console.warn(msg); }
}
```
Services podem depender de outros services.
Por exemplo, aqui está um `HeroService` que depende do service `Logger`, e também usa `BackendService` para obter heroes.
Esse service por sua vez pode depender do service `HttpClient` para buscar heroes assincronamente de um servidor:

```
import { inject } from "@angular/core";

export class HeroService {
private heroes: Hero[] = [];

private backend = inject(BackendService);
private logger = inject(Logger);

async getHeroes() {
// Fetch
this.heroes = await this.backend.getAll(Hero);
// Log
this.logger.log(`Fetched ${this.heroes.length} heroes.`);
return this.heroes;
}
}
```
## Criando um service injetável com o CLI

O Angular CLI fornece um comando para criar um novo service. No exemplo a seguir, você adiciona um novo service a uma aplicação existente.

Para gerar uma nova classe `HeroService` na pasta `src/app/heroes`, siga estes passos:

1. Execute este comando do [Angular CLI](/tools/cli):

```sh
ng generate service heroes/hero
```
Este comando cria o seguinte `HeroService` padrão:

```
import { Injectable } from '@angular/core';

@Injectable({
providedIn: 'root',
})
export class HeroService {}
```
O decorator `@Injectable()` especifica que o Angular pode usar esta classe no sistema DI.
Os metadados, `providedIn: 'root'`, significam que o `HeroService` é fornecido por toda a aplicação.

Adicione um método `getHeroes()` que retorna os heroes de `mock.heroes.ts` para obter os dados mock de hero:

```
import { Injectable } from '@angular/core';
import { HEROES } from './mock-heroes';

@Injectable({
// declara que este service deve ser criado
// pelo injector raiz da aplicação.
providedIn: 'root',
})
export class HeroService {
getHeroes() {
return HEROES;
}
}
```
Para clareza e manutenibilidade, é recomendado que você defina components e services em arquivos separados.

## Injetando services

Para injetar um service como uma dependência em um component, você pode declarar um campo de classe representando a dependência e usar a função `inject` do Angular para inicializá-lo.

O exemplo a seguir especifica o `HeroService` no `HeroListComponent`.
O tipo de `heroService` é `HeroService`.

```
import { inject } from "@angular/core";

export class HeroListComponent {
private heroService = inject(HeroService);
}
```
Também é possível injetar um service em um component usando o constructor do component:

```
constructor(private heroService: HeroService)
```
O método `inject` pode ser usado tanto em classes quanto em funções, enquanto o método do constructor naturalmente só pode ser usado em um constructor de classe. No entanto, em qualquer caso, uma dependência só pode ser injetada em um [contexto de injeção](guide/di/dependency-injection-context) válido, geralmente na construção ou inicialização de um component.

## Injetando services em outros services

Quando um service depende de outro service, siga o mesmo padrão de injetar em um component.
No exemplo a seguir, `HeroService` depende de um service `Logger` para reportar suas atividades:

```
import { inject, Injectable } from '@angular/core';
import { HEROES } from './mock-heroes';
import { Logger } from '../logger.service';

@Injectable({
providedIn: 'root',
})
export class HeroService {
private logger = inject(Logger);

getHeroes() {
this.logger.log('Getting heroes.');
return HEROES;
}
}
```
Neste exemplo, o método `getHeroes()` usa o service `Logger` fazendo log de uma mensagem ao buscar heroes.

## Próximos passos

# Contexto de injeção

O sistema de injeção de dependência (DI) depende internamente de um contexto de tempo de execução onde o injector atual está disponível.

Isso significa que injectors podem funcionar apenas quando o código é executado em tal contexto.

O contexto de injeção está disponível nestas situações:

- Durante a construção (via `constructor`) de uma classe sendo instanciada pelo sistema de DI, como um `@Injectable` ou `@Component`.
- No inicializador para campos de tais classes.
- Na factory function especificada para `useFactory` de um `Provider` ou um `@Injectable`.
- Na factory function especificada para um `InjectionToken`.
- Dentro de um stack frame que executa em um contexto de injeção.

Saber quando você está em um contexto de injeção permitirá que você use a função [`inject`](api/core/inject) para injetar instâncias.

NOTE: Para exemplos básicos de uso de `inject()` em construtores de classe e inicializadores de campo, veja o [guia de visão geral](guide/di/overview#where-can-inject-be-used).

## Stack frame em contexto

Algumas APIs são projetadas para serem executadas em um contexto de injeção. Este é o caso, por exemplo, com router guards. Isso permite o uso de [`inject`](api/core/inject) dentro da função guard para acessar um service.

Aqui está um exemplo para `CanActivateFn`

```typescript
const canActivateTeam: CanActivateFn =
    (route: ActivatedRouteSnapshot, state: RouterStateSnapshot) => {
      return inject(PermissionsService).canActivate(inject(UserToken), route.params.id);
    };
```
## Executar dentro de um contexto de injeção

Quando você quer executar uma determinada função em um contexto de injeção sem já estar em um, você pode fazer isso com `runInInjectionContext`.
Isso requer acesso a um injector específico, como o `EnvironmentInjector`, por exemplo:

```
@Injectable({
  providedIn: 'root',
})
export class HeroService {
  private environmentInjector = inject(EnvironmentInjector);

someMethod() {
    runInInjectionContext(this.environmentInjector, () => {
      inject(SomeService); // Do what you need with the injected service
    });
  }
}
```
Note que `inject` retornará uma instância apenas se o injector puder resolver o token requerido.

## Verificando o contexto

O Angular fornece a função helper `assertInInjectionContext` para verificar que o contexto atual é um contexto de injeção e lança um erro claro se não for. Passe uma referência para a função chamadora para que a mensagem de erro aponte para o ponto de entrada correto da API. Isso produz uma mensagem mais clara e acionável do que o erro genérico de injeção padrão.

```ts
import { ElementRef, assertInInjectionContext, inject } from '@angular/core';

export function injectNativeElement<T extends Element>(): T {
    assertInInjectionContext(injectNativeElement);
    return inject(ElementRef).nativeElement;
}
```

Você pode então chamar este helper **de um contexto de injeção** (constructor, inicializador de campo, provider factory, ou código executado via `runInInjectionContext`):

```ts
import { Component, inject } from '@angular/core';
import { injectNativeElement } from './dom-helpers';

@Component({ /* … */ })
export class PreviewCard {
  readonly hostEl = injectNativeElement<HTMLElement>(); // Field initializer runs in an injection context.

onAction() {
    const anotherRef = injectNativeElement<HTMLElement>(); // Fails: runs outside an injection context.
  }
}
```

## Usando DI fora de um contexto

Chamar [`inject`](api/core/inject) ou chamar `assertInInjectionContext` fora de um contexto de injeção lançará [erro NG0203](/errors/NG0203).

# Injectors hierárquicos

Este guia fornece cobertura aprofundada do sistema de dependency injection hierárquico do Angular, incluindo regras de resolução, modificadores e padrões avançados.

NOTA: Para conceitos básicos sobre hierarquia de injector e escopo de provider, veja o [guia de definição de providers de dependência](guide/di/defining-dependency-providers#injector-hierarchy-in-angular).

## Tipos de hierarquias de injector

O Angular tem duas hierarquias de injector:

| Hierarquias de injector          | Detalhes                                                                                                                                                                         |
| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hierarquia `EnvironmentInjector` | Configure um `EnvironmentInjector` nesta hierarquia usando `@Injectable()` ou array `providers` em `ApplicationConfig`.                                                          |
| Hierarquia `ElementInjector`     | Criado implicitamente em cada elemento DOM. Um `ElementInjector` é vazio por padrão a menos que você o configure na propriedade `providers` em `@Directive()` ou `@Component()`. |
Para aplicações baseadas em `NgModule`, você pode fornecer dependências com a hierarquia `ModuleInjector` usando uma anotação `@NgModule()` ou `@Injectable()`.
### `EnvironmentInjector`

O `EnvironmentInjector` pode ser configurado de uma das duas maneiras usando:

- A propriedade `providedIn` do `@Injectable()` para se referir a `root` ou `platform`
- O array `providers` do `ApplicationConfig`
Usar a propriedade `providedIn` do `@Injectable()` é preferível a usar o array `providers` do `ApplicationConfig`. Com `@Injectable()` `providedIn`, ferramentas de otimização podem realizar tree-shaking, que remove services que sua aplicação não está usando. Isso resulta em tamanhos de bundle menores.

Tree-shaking é especialmente útil para uma biblioteca porque a aplicação que usa a biblioteca pode não ter necessidade de injetá-la.
`EnvironmentInjector` é configurado pelo `ApplicationConfig.providers`.

Forneça services usando `providedIn` do `@Injectable()` da seguinte forma:

```ts
{highlight:[4]}
import { Injectable } from '@angular/core';

@Injectable({
  providedIn: 'root' // <--provides this service in the root EnvironmentInjector
})
export class ItemService {
  name = 'telephone';
}
```

O decorator `@Injectable()` identifica uma classe de service.
A propriedade `providedIn` configura um `EnvironmentInjector` específico, aqui `root`, que torna o service disponível no `EnvironmentInjector` `root`.

### ModuleInjector

No caso de aplicações baseadas em `NgModule`, o ModuleInjector pode ser configurado de uma das duas maneiras usando:

- A propriedade `providedIn` do `@Injectable()` para se referir a `root` ou `platform`
- O array `providers` do `@NgModule()`

`ModuleInjector` é configurado pelas propriedades `@NgModule.providers` e `NgModule.imports`. `ModuleInjector` é um achatamento de todos os arrays de providers que podem ser alcançados seguindo `NgModule.imports` recursivamente.

Hierarquias filhas de `ModuleInjector` são criadas ao fazer lazy loading de outros `@NgModules`.

### Platform injector

Existem mais dois injectors acima de `root`, um `EnvironmentInjector` adicional e `NullInjector()`.

Considere como o Angular inicializa a aplicação com o seguinte em `main.ts`:

```ts
bootstrapApplication(AppComponent, appConfig);
```

O método `bootstrapApplication()` cria um injector filho do platform injector que é configurado pela instância `ApplicationConfig`.
Este é o `EnvironmentInjector` `root`.

O método `platformBrowserDynamic()` cria um injector configurado por um `PlatformModule`, que contém dependências específicas da plataforma.
Isso permite que múltiplas aplicações compartilhem uma configuração de plataforma.
Por exemplo, um browser tem apenas uma barra de URL, não importa quantas aplicações você tenha executando.
Você pode configurar providers adicionais específicos da plataforma no nível da plataforma fornecendo `extraProviders` usando a função `platformBrowser()`.

O próximo injector pai na hierarquia é o `NullInjector()`, que é o topo da árvore.
Se você subiu tanto na árvore que está procurando um service no `NullInjector()`, você receberá um erro a menos que tenha usado `@Optional()` porque, em última análise, tudo termina no `NullInjector()` e ele retorna um erro ou, no caso de `@Optional()`, `null`.
Para mais informações sobre `@Optional()`, veja a seção [`@Optional()`](#optional) deste guia.

O diagrama a seguir representa a relação entre o `ModuleInjector` `root` e seus injectors pais conforme os parágrafos anteriores descrevem.

```mermaid
stateDiagram-v2
    elementInjector: EnvironmentInjector<br>(configured by Angular)<br>has special things like DomSanitizer => providedIn 'platform'
    rootInjector: root EnvironmentInjector<br>(configured by AppConfig)<br>has things for your app => bootstrapApplication(..., AppConfig)
    nullInjector: NullInjector<br>always throws an error unless<br>you use @Optional()

direction BT
    rootInjector --> elementInjector
    elementInjector --> nullInjector
```

Embora o nome `root` seja um alias especial, outras hierarquias `EnvironmentInjector` não têm aliases.
Você tem a opção de criar hierarquias `EnvironmentInjector` sempre que um component carregado dinamicamente for criado, como com o Router, que criará hierarquias filhas de `EnvironmentInjector`.

Todas as requisições encaminham até o root injector, quer você o tenha configurado com a instância `ApplicationConfig` passada para o método `bootstrapApplication()`, ou registrado todos os providers com `root` em seus próprios services.
Se você configurar um provider em toda a aplicação no `ApplicationConfig` de `bootstrapApplication`, ele sobrescreve um configurado para `root` nos metadados `@Injectable()`.
Você pode fazer isso para configurar um provider não-padrão de um service que é compartilhado com múltiplas aplicações.

Aqui está um exemplo do caso onde a configuração do router de component inclui uma [estratégia de localização](guide/routing#location-strategy) não-padrão listando seu provider na lista `providers` do `ApplicationConfig`.

```ts
providers: [
  { provide: LocationStrategy, useClass: HashLocationStrategy }
]
```

Para aplicações baseadas em `NgModule`, configure providers em toda a aplicação no `AppModule` `providers`.
### `ElementInjector`

O Angular cria hierarquias `ElementInjector` implicitamente para cada elemento DOM.

Fornecer um service no decorator `@Component()` usando sua propriedade `providers` ou `viewProviders` configura um `ElementInjector`.
Por exemplo, o seguinte `TestComponent` configura o `ElementInjector` fornecendo o service da seguinte forma:

```ts
{highlight:[3]}
@Component({
  /* … */
  providers: [{ provide: ItemService, useValue: { name: 'lamp' } }]
})
export class TestComponent
```

ÚTIL: Veja a seção [regras de resolução](#resolution-rules) para entender a relação entre a árvore `EnvironmentInjector`, o `ModuleInjector` e a árvore `ElementInjector`.

Quando você fornece services em um component, esse service fica disponível através do `ElementInjector` naquela instância de component.
Ele também pode estar visível em components/directives filhos baseado nas regras de visibilidade descritas na seção [regras de resolução](#resolution-rules).

Quando a instância do component é destruída, a instância do service também é.

#### `@Directive()` e `@Component()`

Um component é um tipo especial de directive, o que significa que assim como `@Directive()` tem uma propriedade `providers`, `@Component()` também tem.
Isso significa que directives assim como components podem configurar providers, usando a propriedade `providers`.
Quando você configura um provider para um component ou directive usando a propriedade `providers`, esse provider pertence ao `ElementInjector` daquele component ou directive.
Components e directives no mesmo elemento compartilham um injector.

## Regras de resolução {#resolution-rules}

Ao resolver um token para um component/directive, o Angular o resolve em duas fases:

1. Contra seus pais na hierarquia `ElementInjector`.
2. Contra seus pais na hierarquia `EnvironmentInjector`.

Quando um component declara uma dependência, o Angular tenta satisfazer essa dependência com seu próprio `ElementInjector`.
Se o injector do component não tem o provider, ele passa a requisição para o `ElementInjector` do component pai.

As requisições continuam sendo encaminhadas até que o Angular encontre um injector que possa lidar com a requisição ou fique sem hierarquias ancestrais de `ElementInjector`.

Se o Angular não encontrar o provider em nenhuma hierarquia de `ElementInjector`, ele volta para o elemento onde a requisição se originou e procura na hierarquia `EnvironmentInjector`.
Se o Angular ainda não encontrar o provider, ele lança um erro.

Se você registrou um provider para o mesmo token DI em diferentes níveis, o primeiro que o Angular encontrar é o que ele usa para resolver a dependência.
Se, por exemplo, um provider for registrado localmente no component que precisa de um service,
o Angular não procura por outro provider do mesmo service.

ÚTIL: Para aplicações baseadas em `NgModule`, o Angular procurará na hierarquia `ModuleInjector` se não conseguir encontrar um provider nas hierarquias `ElementInjector`.

## Modificadores de resolução

O comportamento de resolução do Angular pode ser modificado com `optional`, `self`, `skipSelf` e `host`.
Importe cada um deles de `@angular/core` e use cada um na configuração do `inject` quando você injetar seu service.

### Tipos de modificadores

Modificadores de resolução se enquadram em três categorias:

- O que fazer se o Angular não encontrar o que você está procurando, ou seja `optional`
- Onde começar a procurar, ou seja `skipSelf`
- Onde parar de procurar, `host` e `self`

Por padrão, o Angular sempre começa no `Injector` atual e continua procurando até o topo.
Modificadores permitem que você mude a localização inicial, ou _self_, e a localização final.

Além disso, você pode combinar todos os modificadores exceto:

- `host` e `self`
- `skipSelf` e `self`.

### `optional`

`optional` permite ao Angular considerar um service que você injeta como opcional.
Dessa forma, se ele não puder ser resolvido em tempo de execução, o Angular resolve o service como `null`, ao invés de lançar um erro.
No exemplo a seguir, o service, `OptionalService`, não é fornecido no service, `ApplicationConfig`, `@NgModule()`, ou classe de component, então ele não está disponível em nenhum lugar na aplicação.

```ts
{header:"src/app/optional/optional.component.ts"}
export class OptionalComponent {
  public optional? = inject(OptionalService, {optional: true});
}
```

### `self`

Use `self` para que o Angular procure apenas no `ElementInjector` do component ou directive atual.

Um bom caso de uso para `self` é injetar um service mas apenas se ele estiver disponível no elemento host atual.
Para evitar erros nesta situação, combine `self` com `optional`.

Por exemplo, no seguinte `SelfNoDataComponent`, observe o `LeafService` injetado como uma propriedade.

```ts
{header:"src/app/self-no-data/self-no-data.component.ts", highlight=[7]}>
@Component({
  selector: 'app-self-no-data',
  templateUrl: './self-no-data.component.html',
  styleUrls: ['./self-no-data.component.css']
})
export class SelfNoDataComponent {
  public leaf = inject(LeafService, {optional: true, self: true});
}
```

Neste exemplo, há um provider pai e injetar o service retornará o valor, no entanto, injetar o service com `self` e `optional` retornará `null` porque `self` diz ao injector para parar de procurar no elemento host atual.

Outro exemplo mostra a classe de component com um provider para `FlowerService`.
Neste caso, o injector não procura além do `ElementInjector` atual porque encontra o `FlowerService` e retorna a tulipa 🌷.

```ts
{header:"src/app/self/self.component.ts"}
@Component({
  selector: 'app-self',
  templateUrl: './self.component.html',
  styleUrls: ['./self.component.css'],
  providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}],
})
export class SelfComponent {
  constructor(@Self() public flower: FlowerService) {}
}
```

### `skipSelf`

`skipSelf` é o oposto de `self`.
Com `skipSelf`, o Angular inicia sua busca por um service no `ElementInjector` pai, ao invés do atual.
Então, se o `ElementInjector` pai estivesse usando o valor samambaia <code>🌿</code> para `emoji`, mas você tivesse folha de bordo <code>🍁</code> no array `providers` do component, o Angular ignoraria a folha de bordo <code>🍁</code> e usaria samambaia <code>🌿</code>.

Para ver isso em código, assuma que o seguinte valor para `emoji` é o que o component pai estava usando, como neste service:

```ts
{header:"src/app/leaf.service.ts"}
export class LeafService {
  emoji = '🌿';
}
```

Imagine que no component filho, você tivesse um valor diferente, folha de bordo 🍁, mas quisesse usar o valor do pai. É quando você usaria `skipSelf`:

```ts
{header:"src/app/skipself/skipself.component.ts" highlight:[[6],[10]]}
@Component({
  selector: 'app-skipself',
  templateUrl: './skipself.component.html',
  styleUrls: ['./skipself.component.css'],
  // Angular would ignore this LeafService instance
  providers: [{ provide: LeafService, useValue: { emoji: '🍁' } }]
})
export class SkipselfComponent {
  // Use skipSelf as inject option
  public leaf = inject(LeafService, {skipSelf: true});
}
```

Neste caso, o valor que você obteria para `emoji` seria samambaia <code>🌿</code>, não folha de bordo <code>🍁</code>.

#### Opção `skipSelf` com `optional`

Use a opção `skipSelf` com `optional` para prevenir um erro se o valor for `null`.

No exemplo a seguir, o service `Person` é injetado durante a inicialização da propriedade.
`skipSelf` diz ao Angular para pular o injector atual e `optional` prevenirá um erro caso o service `Person` seja `null`.

```ts
class Person {
  parent = inject(Person, {optional: true, skipSelf: true})
}
```

### `host`

`host` permite que você designe um component como a última parada na árvore de injector ao procurar por providers.

Mesmo se houver uma instância de service mais acima na árvore, o Angular não continuará procurando.
Use `host` da seguinte forma:

```ts
{header:"src/app/host/host.component.ts" highlight:[[6],[10]]}
@Component({
selector: 'app-host',
templateUrl: './host.component.html',
styleUrls: ['./host.component.css'],
// provide the service
providers: [{ provide: FlowerService, useValue: { emoji: '🌷' } }]
})
export class HostComponent {
// use host when injecting the service
flower = inject(FlowerService, {host: true, optional: true});
}
```

Como `HostComponent` tem a opção `host`, não importa o que o pai de `HostComponent` possa ter como valor `flower.emoji`, o `HostComponent` usará tulipa <code>🌷</code>.

### Modificadores com injeção via constructor

Similarmente como apresentado antes, o comportamento da injeção via constructor pode ser modificado com `@Optional()`, `@Self()`, `@SkipSelf()` e `@Host()`.

Importe cada um deles de `@angular/core` e use cada um no constructor da classe de component quando você injetar seu service.

```ts
{header:"src/app/self-no-data/self-no-data.component.ts" highlight:[3]}
export class SelfNoDataComponent {
  constructor(@Self() @Optional() public leaf?: LeafService) { }
}
```

## Estrutura lógica do template

Quando você fornece services na classe de component, services ficam visíveis dentro da árvore `ElementInjector` relativo a onde e como você fornece esses services.

Entender a estrutura lógica subjacente do template Angular lhe dará uma base para configurar services e, por sua vez, controlar sua visibilidade.

Components são usados em seus templates, como no exemplo a seguir:

```html
<app-root>
  <app-child></app-child>;
</app-root>
```

ÚTIL: Normalmente, você declara os components e seus templates em arquivos separados.
Para os propósitos de entender como o sistema de injeção funciona, é útil olhá-los do ponto de vista de uma árvore lógica combinada.
O termo _lógica_ o distingue da árvore de renderização, que é a árvore DOM da sua aplicação.
Para marcar as localizações de onde os templates de component estão localizados, este guia usa o pseudo-elemento `<#VIEW>`, que não existe realmente na árvore de renderização e está presente apenas para propósitos de modelo mental.

O seguinte é um exemplo de como as árvores de view `<app-root>` e `<app-child>` são combinadas em uma única árvore lógica:

```html
<app-root>
  <#VIEW>
    <app-child>
     <#VIEW>
       …content goes here…
     </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

Entender a ideia da demarcação `<#VIEW>` é especialmente significativo quando você configura services na classe de component.

## Exemplo: Fornecendo services em `@Component()`

Como você fornece services usando um decorator `@Component()` (ou `@Directive()`) determina sua visibilidade.
As seções a seguir demonstram `providers` e `viewProviders` juntamente com maneiras de modificar a visibilidade do service com `skipSelf` e `host`.

Uma classe de component pode fornecer services de duas maneiras:

| Arrays                       | Detalhes                                       |
| :--------------------------- | :--------------------------------------------- |
| Com um array `providers`     | `@Component({ providers: [SomeService] })`     |
| Com um array `viewProviders` | `@Component({ viewProviders: [SomeService] })` |

Nos exemplos abaixo, você verá a árvore lógica de uma aplicação Angular.
Para ilustrar como o injector funciona no contexto de templates, a árvore lógica representará a estrutura HTML da aplicação.
Por exemplo, a árvore lógica mostrará que `<child-component>` é um filho direto de `<parent-component>`.

Na árvore lógica, você verá atributos especiais: `@Provide`, `@Inject`, e `@ApplicationConfig`.
Estes não são atributos reais mas estão aqui para demonstrar o que está acontecendo por baixo dos panos.

| Atributo de service Angular | Detalhes                                                                             |
| :-------------------------- | :----------------------------------------------------------------------------------- |
| `@Inject(Token)=>Value`     | Se `Token` for injetado nesta localização na árvore lógica, seu valor seria `Value`. |
| `@Provide(Token=Value)`     | Indica que `Token` é fornecido com `Value` nesta localização na árvore lógica.       |
| `@ApplicationConfig`        | Demonstra que um `EnvironmentInjector` de fallback deve ser usado nesta localização. |

### Estrutura de aplicação de exemplo

A aplicação de exemplo tem um `FlowerService` fornecido em `root` com um valor `emoji` de hibisco vermelho <code>🌺</code>.

```ts
{header:"src/app/flower.service.ts"}
@Injectable({
  providedIn: 'root'
})
export class FlowerService {
  emoji = '🌺';
}
```

Considere uma aplicação com apenas um `AppComponent` e um `ChildComponent`.
A view renderizada mais básica seria como elementos HTML aninhados como o seguinte:

```html
<app-root> 
<app-child> 
</app-child>
</app-root>
```

No entanto, nos bastidores, o Angular usa uma representação lógica de view da seguinte forma ao resolver requisições de injeção:

```html
<app-root> 
  <#VIEW>
    <app-child> 
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

O `<#VIEW>` aqui representa uma instância de um template.
Observe que cada component tem seu próprio `<#VIEW>`.

Conhecimento desta estrutura pode informar como você fornece e injeta seus services, e lhe dar controle completo da visibilidade do service.

Agora, considere que `<app-root>` injeta o `FlowerService`:

```typescript
export class AppComponent  {
  flower = inject(FlowerService);
}
```

Adicione um binding ao template `<app-root>` para visualizar o resultado:

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

A saída na view seria:

```shell
Emoji from FlowerService: 🌺
```

Na árvore lógica, isso seria representado da seguinte forma:

```html
<app-root @ApplicationConfig
        @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
    <p>Emoji from FlowerService: {{flower.emoji}} (🌺)</p>
    <app-child>
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

Quando `<app-root>` solicita o `FlowerService`, é trabalho do injector resolver o token `FlowerService`.
A resolução do token acontece em duas fases:

1. O injector determina a localização inicial na árvore lógica e uma localização final da busca.
   O injector começa com a localização inicial e procura pelo token em cada nível de view na árvore lógica.
   Se o token for encontrado, ele é retornado.

1. Se o token não for encontrado, o injector procura pelo `EnvironmentInjector` pai mais próximo para delegar a requisição.

No caso de exemplo, as restrições são:

1. Comece com `<#VIEW>` pertencente a `<app-root>` e termine com `<app-root>`.
   - Normalmente o ponto inicial para busca é no ponto de injeção.
     No entanto, neste caso `<app-root>` é um component. `@Component`s são especiais pois também incluem seus próprios `viewProviders`, que é por isso que a busca começa em `<#VIEW>` pertencente a `<app-root>`.
     Este não seria o caso para uma directive correspondida na mesma localização.
   - A localização final acontece de ser a mesma que o próprio component, porque é o component mais alto nesta aplicação.

1. O `EnvironmentInjector` fornecido pelo `ApplicationConfig` atua como o injector de fallback quando o token de injeção não pode ser encontrado nas hierarquias `ElementInjector`.

### Usando o array `providers`

Agora, na classe `ChildComponent`, adicione um provider para `FlowerService` para demonstrar regras de resolução mais complexas nas próximas seções:

```typescript
@Component({
selector: 'app-child',
templateUrl: './child.component.html',
styleUrls: ['./child.component.css'],
// use the providers array to provide a service
providers: [{ provide: FlowerService, useValue: { emoji: '🌻' } }]
})
export class ChildComponent {
// inject the service
flower = inject(FlowerService);
}
```

Agora que o `FlowerService` é fornecido no decorator `@Component()`, quando o `<app-child>` solicita o service, o injector tem apenas que procurar até o `ElementInjector` no `<app-child>`.
Ele não terá que continuar a busca através da árvore de injector.

O próximo passo é adicionar um binding ao template `ChildComponent`.

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

Para renderizar os novos valores, adicione `<app-child>` no final do template `AppComponent` para que a view também exiba o girassol:

```shell
Child Component
Emoji from FlowerService: 🌻
```

Na árvore lógica, isso é representado da seguinte forma:

```html
<app-root @ApplicationConfig
@Inject(FlowerService) flower=>"🌺">
<#VIEW>

<p>Emoji from FlowerService: {{flower.emoji}} (🌺)</p>
<app-child @Provide(FlowerService="🌻")
@Inject(FlowerService)=>"🌻"> 
<#VIEW> 
<h2>Child Component</h2>
<p>Emoji from FlowerService: {{flower.emoji}} (🌻)</p>
</#VIEW>
</app-child>
</#VIEW>
</app-root>
```

Quando `<app-child>` solicita o `FlowerService`, o injector começa sua busca no `<#VIEW>` pertencente a `<app-child>` $`<#VIEW>` é incluído porque é injetado de `@Component()`$ e termina com `<app-child>`.
Neste caso, o `FlowerService` é resolvido no array `providers` com girassol <code>🌻</code> do `<app-child>`.
O injector não tem que procurar mais adiante na árvore de injector.
Ele para assim que encontra o `FlowerService` e nunca vê o hibisco vermelho <code>🌺</code>.

### Usando o array `viewProviders`

Use o array `viewProviders` como outra maneira de fornecer services no decorator `@Component()`.
Usar `viewProviders` torna services visíveis no `<#VIEW>`.

ÚTIL: Os passos são os mesmos que usar o array `providers`, com a exceção de usar o array `viewProviders`.

Para instruções passo a passo, continue com esta seção.
Se você conseguir configurá-lo sozinho, pule para [Modificando disponibilidade de service](#visibility-of-provided-tokens).

Para demonstração, estamos construindo um `AnimalService` para demonstrar `viewProviders`.
Primeiro, crie um `AnimalService` com uma propriedade `emoji` de baleia <code>🐳</code>:

```typescript
import { Injectable } from '@angular/core';

@Injectable({
providedIn: 'root'
})
export class AnimalService {
emoji = '🐳';
}
```

Seguindo o mesmo padrão que com o `FlowerService`, injete o `AnimalService` na classe `AppComponent`:

```typescript
export class AppComponent {
    public flower = inject(FlowerService);
    public animal = inject(AnimalService);
}
```

ÚTIL: Você pode deixar todo o código relacionado ao `FlowerService` no lugar pois permitirá uma comparação com o `AnimalService`.

Adicione um array `viewProviders` e injete o `AnimalService` na classe `<app-child>` também, mas dê ao `emoji` um valor diferente.
Aqui, ele tem um valor de cachorro 🐶.

```typescript
@Component({
selector: 'app-child',
templateUrl: './child.component.html',
styleUrls: ['./child.component.css'],
// provide services
providers: [{ provide: FlowerService, useValue: { emoji: '🌻' } }],
viewProviders: [{ provide: AnimalService, useValue: { emoji: '🐶' } }]
})
export class ChildComponent {
// inject services
flower = inject(FlowerService);
animal = inject(AnimalService)
...
}
```

Adicione bindings aos templates `ChildComponent` e `AppComponent`.
No template `ChildComponent`, adicione o seguinte binding:

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

Adicionalmente, adicione o mesmo ao template `AppComponent`:

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>s
```

Agora você deve ver ambos os valores no browser:

```shell
AppComponent
Emoji from AnimalService: 🐳

Child Component
Emoji from AnimalService: 🐶
```

A árvore lógica para este exemplo de `viewProviders` é a seguinte:

```html
<app-root @ApplicationConfig
@Inject(AnimalService) animal=>"🐳">
<#VIEW>
<app-child>
<#VIEW @Provide(AnimalService="🐶")
@Inject(AnimalService=>"🐶")>

<p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>
</#VIEW>
</app-child>
</#VIEW>
</app-root>
```

Assim como com o exemplo `FlowerService`, o `AnimalService` é fornecido no decorator `@Component()` do `<app-child>`.
Isso significa que, uma vez que o injector primeiro procura no `ElementInjector` do component, ele encontra o valor `AnimalService` de cachorro <code>🐶</code>.
Ele não precisa continuar procurando na árvore `ElementInjector`, nem precisa procurar no `ModuleInjector`.

### `providers` vs. `viewProviders`

O campo `viewProviders` é conceitualmente similar a `providers`, mas há uma diferença notável.
Providers configurados em `viewProviders` não são visíveis para conteúdo projetado que acaba como filho lógico do component.

Para ver a diferença entre usar `providers` e `viewProviders`, adicione outro component ao exemplo e chame-o de `InspectorComponent`.
`InspectorComponent` será um filho do `ChildComponent`.
Em `inspector.component.ts`, injete o `FlowerService` e `AnimalService` durante a inicialização da propriedade:

```typescript
export class InspectorComponent {
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

Você não precisa de um array `providers` ou `viewProviders`.
A seguir, em `inspector.component.html`, adicione a mesma marcação dos components anteriores:

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

Lembre-se de adicionar o `InspectorComponent` ao array `imports` do `ChildComponent`.

```typescript
@Component({
...
imports: [InspectorComponent]
})
```

A seguir, adicione o seguinte a `child.component.html`:

```html
...

<div class="container">
  <h3>Content projection</h3>
  <ng-content></ng-content>
</div>
<h3>Inside the view</h3>

<app-inspector></app-inspector>
```

`<ng-content>` permite que você projete conteúdo, e `<app-inspector>` dentro do template `ChildComponent` torna o `InspectorComponent` um component filho de `ChildComponent`.

A seguir, adicione o seguinte a `app.component.html` para aproveitar a projeção de conteúdo.

```html
<app-child>
  <app-inspector></app-inspector>
</app-child>
```

O browser agora renderiza o seguinte, omitindo os exemplos anteriores para brevidade:

```shell
...
Content projection

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐳

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐶
```

Esses quatro bindings demonstram a diferença entre `providers` e `viewProviders`.
Lembre-se de que o emoji de cachorro <code>🐶</code> é declarado dentro do `<#VIEW>` de `ChildComponent` e não é visível para o conteúdo projetado.
Em vez disso, o conteúdo projetado vê a baleia <code>🐳</code>.

No entanto, na próxima seção de saída, o `InspectorComponent` é um component filho real de `ChildComponent`, `InspectorComponent` está dentro do `<#VIEW>`, então quando ele pede o `AnimalService`, ele vê o cachorro <code>🐶</code>.

O `AnimalService` na árvore lógica seria assim:

```html
<app-root @ApplicationConfig
@Inject(AnimalService) animal=>"🐳">
<#VIEW>
<app-child>
<#VIEW @Provide(AnimalService="🐶")
@Inject(AnimalService=>"🐶")>

<p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>

<div class="container">
          <h3>Content projection</h3>
          <app-inspector @Inject(AnimalService) animal=>"🐳">
            <p>Emoji from AnimalService: {{animal.emoji}} (🐳)</p>
          </app-inspector>
        </div>

<app-inspector>
          <#VIEW @Inject(AnimalService) animal=>"🐶">
            <p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>
          </#VIEW>
        </app-inspector>
      </#VIEW>
    </app-child>

</#VIEW>
</app-root>
```

O conteúdo projetado de `<app-inspector>` vê a baleia <code>🐳</code>, não o cachorro <code>🐶</code>, porque o cachorro <code>🐶</code> está dentro do `<#VIEW>` do `<app-child>`.
O `<app-inspector>` só pode ver o cachorro <code>🐶</code> se também estiver dentro do `<#VIEW>`.

### Visibilidade de tokens fornecidos {#visibility-of-provided-tokens}

Decorators de visibilidade influenciam onde a busca pelo token de injeção começa e termina na árvore lógica.
Para fazer isso, coloque a configuração de visibilidade no ponto de injeção, ou seja, ao invocar `inject()`, ao invés de em um ponto de declaração.

Para alterar onde o injector começa a procurar por `FlowerService`, adicione `skipSelf` à invocação `inject()` do `<app-child>` onde `FlowerService` é injetado.
Esta invocação é um inicializador de propriedade do `<app-child>` como mostrado em `child.component.ts`:

```typescript
flower = inject(FlowerService, { skipSelf: true })
```

Com `skipSelf`, o injector `<app-child>` não procura em si mesmo pelo `FlowerService`.
Em vez disso, o injector começa a procurar pelo `FlowerService` no `ElementInjector` do `<app-root>`, onde não encontra nada.
Então, ele volta para o `ModuleInjector` do `<app-child>` e encontra o valor hibisco vermelho <code>🌺</code>, que está disponível porque `<app-child>` e `<app-root>` compartilham o mesmo `ModuleInjector`.
A UI renderiza o seguinte:

```shell
Emoji from FlowerService: 🌺
```

Em uma árvore lógica, esta mesma ideia pode parecer assim:

```html
<app-root @ApplicationConfig
@Inject(FlowerService) flower=>"🌺">
<#VIEW>
<app-child @Provide(FlowerService="🌻")>
<#VIEW @Inject(FlowerService, SkipSelf)=>"🌺">

</#VIEW>
</app-child>
</#VIEW>
</app-root>
```

Embora `<app-child>` forneça o girassol <code>🌻</code>, a aplicação renderiza o hibisco vermelho <code>🌺</code> porque `skipSelf` faz com que o injector atual (`app-child`) se pule e procure em seu pai.

Se você agora adicionar `host` (além do `skipSelf`), o resultado será `null`.
Isso é porque `host` limita o limite superior da busca ao `<#VIEW>` do `app-child`.
Aqui está a ideia na árvore lógica:

```html
<app-root @ApplicationConfig
@Inject(FlowerService) flower=>"🌺">
<#VIEW> 
<app-child @Provide(FlowerService="🌻")> 
<#VIEW inject(FlowerService, {skipSelf: true, host: true, optional:true})=>null>
</#VIEW>
</app-parent>
</#VIEW>
</app-root>
```

Aqui, os services e seus valores são os mesmos, mas `host` impede o injector de procurar além do `<#VIEW>` por `FlowerService`, então ele não o encontra e retorna `null`.

### `skipSelf` e `viewProviders`

Lembre-se, `<app-child>` fornece o `AnimalService` no array `viewProviders` com o valor de cachorro <code>🐶</code>.
Como o injector tem apenas que procurar no `ElementInjector` do `<app-child>` pelo `AnimalService`, ele nunca vê a baleia <code>🐳</code>.

Como no exemplo `FlowerService`, se você adicionar `skipSelf` ao `inject()` de `AnimalService`, o injector não procurará no `ElementInjector` do `<app-child>` atual pelo `AnimalService`.
Em vez disso, o injector começará no `ElementInjector` do `<app-root>`.

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ],
})
```

A árvore lógica se parece com isso com `skipSelf` em `<app-child>`:

```html
<app-root @ApplicationConfig
@Inject(AnimalService=>"🐳")>
<#VIEW>
<app-child>
<#VIEW @Provide(AnimalService="🐶")
@Inject(AnimalService, SkipSelf=>"🐳")>

</#VIEW>
</app-child>
</#VIEW>
</app-root>
```

Com `skipSelf` no `<app-child>`, o injector começa sua busca pelo `AnimalService` no `ElementInjector` do `<app-root>` e encontra baleia 🐳.

### `host` e `viewProviders`

Se você apenas usar `host` para a injeção de `AnimalService`, o resultado é cachorro <code>🐶</code> porque o injector encontra o `AnimalService` no próprio `<#VIEW>` do `<app-child>`.
O `ChildComponent` configura os `viewProviders` para que o emoji de cachorro seja fornecido como valor `AnimalService`.
Você também pode ver `host` no `inject()`:

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ]
})
export class ChildComponent {
  animal = inject(AnimalService, { host: true })
}
```

`host: true` faz com que o injector procure até encontrar a borda do `<#VIEW>`.

```html
<app-root @ApplicationConfig
@Inject(AnimalService=>"🐳")>
<#VIEW>
<app-child>
<#VIEW @Provide(AnimalService="🐶")
inject(AnimalService, {host: true}=>"🐶")> 
</#VIEW>
</app-child>
</#VIEW>
</app-root>
```

Adicione um array `viewProviders` com um terceiro animal, ouriço <code>🦔</code>, aos metadados `@Component()` do `app.component.ts`:

```typescript
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: [ './app.component.css' ],
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🦔' } },
  ],
})
```

A seguir, adicione `skipSelf` junto com `host` ao `inject()` para a injeção de `AnimalService` em `child.component.ts`.
Aqui estão `host` e `skipSelf` na inicialização da propriedade `animal`:

```typescript
export class ChildComponent {
  animal = inject(AnimalService, { host: true, skipSelf: true });
}
```

Quando `host` e `skipSelf` foram aplicados ao `FlowerService`, que está no array `providers`, o resultado foi `null` porque `skipSelf` inicia sua busca no injector `<app-child>`, mas `host` para de procurar em `<#VIEW>` —onde não há `FlowerService`
Na árvore lógica, você pode ver que o `FlowerService` é visível em `<app-child>`, não em seu `<#VIEW>`.

No entanto, o `AnimalService`, que é fornecido no array `viewProviders` do `AppComponent`, é visível.

A representação da árvore lógica mostra por que isso acontece:

```html
<app-root @ApplicationConfig
@Inject(AnimalService=>"🐳")>
<#VIEW @Provide(AnimalService="🦔")
@Inject(AnimalService, @Optional)=>"🦔">

<app-child>
<#VIEW @Provide(AnimalService="🐶")
inject(AnimalService, {skipSelf:true, host: true, optional: true})=>"🦔">

</#VIEW>
</app-child>
</#VIEW>
</app-root>
```

`skipSelf`, faz com que o injector inicie sua busca pelo `AnimalService` no `<app-root>`, não no `<app-child>`, onde a requisição se origina, e `host` para a busca no `<#VIEW>` do `<app-root>`.
Como `AnimalService` é fornecido através do array `viewProviders`, o injector encontra ouriço <code>🦔</code> no `<#VIEW>`.

## Exemplo: casos de uso de `ElementInjector`

A habilidade de configurar um ou mais providers em diferentes níveis abre possibilidades úteis.

### Cenário: isolamento de service

Razões arquiteturais podem levá-lo a restringir acesso a um service ao domínio da aplicação onde ele pertence.
Por exemplo, considere que construímos um `VillainsListComponent` que exibe uma lista de vilões.
Ele obtém esses vilões de um `VillainsService`.

Se você fornecer `VillainsService` no `AppModule` raiz, ele tornará `VillainsService` visível em todos os lugares na aplicação.
Se você posteriormente modificar o `VillainsService`, você poderia quebrar algo em outros components que começaram a depender deste service por acidente.

Em vez disso, você deve fornecer o `VillainsService` nos metadados `providers` do `VillainsListComponent` assim:

```typescript
@Component({
selector: 'app-villains-list',
templateUrl: './villains-list.component.html',
providers: [VillainsService]
})
export class VillainsListComponent {}
```

Ao fornecer `VillainsService` nos metadados `VillainsListComponent` e em nenhum outro lugar, o service torna-se disponível apenas no `VillainsListComponent` e sua subárvore de components.

`VillainService` é um singleton com respeito a `VillainsListComponent` porque é onde ele é declarado.
Contanto que `VillainsListComponent` não seja destruído, será a mesma instância de `VillainService`, mas se houver múltiplas instâncias de `VillainsListComponent`, então cada instância de `VillainsListComponent` terá sua própria instância de `VillainService`.

### Cenário: múltiplas sessões de edição

Muitas aplicações permitem que usuários trabalhem em várias tarefas abertas ao mesmo tempo.
Por exemplo, em uma aplicação de preparação de impostos, o preparador poderia estar trabalhando em várias declarações fiscais, alternando de uma para outra ao longo do dia.

Para demonstrar esse cenário, imagine um `HeroListComponent` que exibe uma lista de super-heróis.

Para abrir a declaração fiscal de um herói, o preparador clica em um nome de herói, que abre um component para editar aquela declaração.
Cada declaração fiscal de herói selecionado abre em seu próprio component e múltiplas declarações podem estar abertas ao mesmo tempo.

Cada component de declaração fiscal tem as seguintes características:

- É sua própria sessão de edição de declaração fiscal
- Pode alterar uma declaração fiscal sem afetar uma declaração em outro component
- Tem a habilidade de salvar as mudanças em sua declaração fiscal ou cancelá-las

Suponha que o `HeroTaxReturnComponent` tivesse lógica para gerenciar e restaurar mudanças.
Isso seria uma tarefa direta para uma declaração fiscal de herói.
No mundo real, com um modelo de dados de declaração fiscal rico, o gerenciamento de mudanças seria complicado.
Você poderia delegar esse gerenciamento a um service auxiliar, como este exemplo faz.

O `HeroTaxReturnService` armazena em cache um único `HeroTaxReturn`, rastreia mudanças naquela declaração e pode salvá-la ou restaurá-la.
Ele também delega ao singleton `HeroService` em toda a aplicação, que ele obtém por injeção.

```typescript
import { Injectable } from '@angular/core';
import { HeroTaxReturn } from './hero';
import { HeroesService } from './heroes.service';

@Injectable()
export class HeroTaxReturnService {
private currentTaxReturn!: HeroTaxReturn;
private originalTaxReturn!: HeroTaxReturn;

private heroService = inject(HeroesService);

set taxReturn(htr: HeroTaxReturn) {
this.originalTaxReturn = htr;
this.currentTaxReturn = htr.clone();
}

get taxReturn(): HeroTaxReturn {
return this.currentTaxReturn;
}

restoreTaxReturn() {
this.taxReturn = this.originalTaxReturn;
}

saveTaxReturn() {
this.taxReturn = this.currentTaxReturn;
this.heroService.saveTaxReturn(this.currentTaxReturn).subscribe();
}
}
```

Aqui está o `HeroTaxReturnComponent` que faz uso de `HeroTaxReturnService`.

```typescript
import { Component, EventEmitter, input, output } from '@angular/core';
import { HeroTaxReturn } from './hero';
import { HeroTaxReturnService } from './hero-tax-return.service';

@Component({
selector: 'app-hero-tax-return',
templateUrl: './hero-tax-return.component.html',
styleUrls: [ './hero-tax-return.component.css' ],
providers: [ HeroTaxReturnService ]
})
export class HeroTaxReturnComponent {
message = '';

close = output<void>();

get taxReturn(): HeroTaxReturn {
return this.heroTaxReturnService.taxReturn;
}

taxReturn = input.required<HeroTaxReturn>();

constructor() {
effect(() => {
this.heroTaxReturnService.taxReturn = this.taxReturn();
})
}

private heroTaxReturnService = inject(HeroTaxReturnService);

onCanceled() {
this.flashMessage('Canceled');
this.heroTaxReturnService.restoreTaxReturn();
}

onClose() { this.close.emit(); }

onSaved() {
this.flashMessage('Saved');
this.heroTaxReturnService.saveTaxReturn();
}

flashMessage(msg: string) {
this.message = msg;
setTimeout(() => this.message = '', 500);
}
}
```

A _tax-return-to-edit_ chega através da propriedade `input`, que é implementada com getters e setters.
O setter inicializa a própria instância do component do `HeroTaxReturnService` com a declaração recebida.
O getter sempre retorna o que aquele service diz que é o estado atual do herói.
O component também pede ao service para salvar e restaurar esta declaração fiscal.

Isso não funcionará se o service for um singleton em toda a aplicação.
Cada component compartilharia a mesma instância de service, e cada component sobrescreveria a declaração fiscal que pertenceu a outro herói.

Para evitar isso, configure o injector de nível de component de `HeroTaxReturnComponent` para fornecer o service, usando a propriedade `providers` nos metadados do component.

```typescript
providers: [HeroTaxReturnService]
```

O `HeroTaxReturnComponent` tem seu próprio provider do `HeroTaxReturnService`.
Lembre-se que cada _instância_ de component tem seu próprio injector.
Fornecer o service no nível do component garante que _cada_ instância do component obtenha uma instância privada do service. Isso garante que nenhuma declaração fiscal seja sobrescrita.

ÚTIL: O resto do código do cenário depende de outros recursos e técnicas do Angular que você pode aprender em outros lugares na documentação.

### Cenário: providers especializados

Outra razão para fornecer um service novamente em outro nível é substituir uma implementação _mais especializada_ daquele service, mais profundamente na árvore de components.

Por exemplo, considere um component `Car` que inclui informações de serviço de pneus e depende de outros services para fornecer mais detalhes sobre o carro.

O injector raiz, marcado como (A), usa providers _genéricos_ para detalhes sobre `CarService` e `EngineService`.

1. Component `Car` (A). Component (A) exibe dados de serviço de pneus sobre um carro e especifica services genéricos para fornecer mais informações sobre o carro.

2. Component filho (B). Component (B) define seus próprios providers _especializados_ para `CarService` e `EngineService` que têm capacidades especiais adequadas para o que está acontecendo no component (B).

3. Component filho (C) como filho do Component (B). Component (C) define seu próprio provider ainda _mais especializado_ para `CarService`.

```mermaid
graph TD;
subgraph COMPONENT_A[Component A]
subgraph COMPONENT_B[Component B]
COMPONENT_C[Component C]
end
end

style COMPONENT_A fill:#BDD7EE
style COMPONENT_B fill:#FFE699
style COMPONENT_C fill:#A9D18E,color:#000
classDef noShadow filter:none
class COMPONENT_A,COMPONENT_B,COMPONENT_C noShadow
```

Nos bastidores, cada component configura seu próprio injector com zero, um ou mais providers definidos para aquele próprio component.

Quando você resolve uma instância de `Car` no component mais profundo (C), seu injector produz:

- Uma instância de `Car` resolvida pelo injector (C)
- Um `Engine` resolvido pelo injector (B)
- Seus `Tires` resolvidos pelo injector raiz (A).

```mermaid
graph BT;

subgraph A[" "]
direction LR
RootInjector["(A) RootInjector"]
ServicesA["CarService, EngineService, TiresService"]
end

subgraph B[" "]
direction LR
ParentInjector["(B) ParentInjector"]
ServicesB["CarService2, EngineService2"]
end

subgraph C[" "]
direction LR
ChildInjector["(C) ChildInjector"]
ServicesC["CarService3"]
end

direction LR
car["(C) Car"]
engine["(B) Engine"]
tires["(A) Tires"]

direction BT
car-->ChildInjector
ChildInjector-->ParentInjector-->RootInjector

class car,engine,tires,RootInjector,ParentInjector,ChildInjector,ServicesA,ServicesB,ServicesC,A,B,C noShadow
style car fill:#A9D18E,color:#000
style ChildInjector fill:#A9D18E,color:#000
style engine fill:#FFE699,color:#000
style ParentInjector fill:#FFE699,color:#000
style tires fill:#BDD7EE,color:#000
style RootInjector fill:#BDD7EE,color:#000
```

## Mais sobre dependency injection

# Otimizando o tamanho da aplicação cliente com lightweight injection tokens

Esta página fornece uma visão geral conceitual de uma técnica de dependency injection que é recomendada para desenvolvedores de bibliotecas.
Projetar sua biblioteca com _lightweight injection tokens_ ajuda a otimizar o tamanho do bundle de aplicações cliente que usam sua biblioteca.

Você pode gerenciar a estrutura de dependência entre seus components e injectable services para otimizar o tamanho do bundle usando tree-shakable providers.
Isso normalmente garante que se um component ou service fornecido nunca for realmente usado pela aplicação, o compilador pode remover seu código do bundle.

Devido à forma como o Angular armazena injection tokens, é possível que tal component ou service não utilizado acabe no bundle de qualquer forma.
Esta página descreve um padrão de design de dependency injection que suporta tree-shaking adequado usando lightweight injection tokens.

O padrão de design de lightweight injection token é especialmente importante para desenvolvedores de bibliotecas.
Ele garante que quando uma aplicação usa apenas algumas das capacidades da sua biblioteca, o código não usado pode ser eliminado do bundle da aplicação cliente.

Quando uma aplicação usa sua biblioteca, pode haver alguns services que sua biblioteca fornece que a aplicação cliente não usa.
Neste caso, o desenvolvedor da aplicação deve esperar que o service seja tree-shaken, e não contribua para o tamanho da aplicação compilada.
Como o desenvolvedor da aplicação não pode saber sobre ou remediar um problema de tree-shaking na biblioteca, é responsabilidade do desenvolvedor da biblioteca fazê-lo.
Para prevenir a retenção de components não usados, sua biblioteca deve usar o padrão de design de lightweight injection token.

## Quando tokens são retidos

Para explicar melhor a condição sob a qual a retenção de token ocorre, considere uma biblioteca que fornece um component library-card.
Este component contém um corpo e pode conter um header opcional:

```html
<lib-card>;
<lib-header>…</lib-header>;
</lib-card>;
```
Em uma implementação provável, o component `<lib-card>` usa `@ContentChild()` ou `@ContentChildren()` para obter `<lib-header>` e `<lib-body>`, como no seguinte:

```typescript
@Component({
  selector: 'lib-header',
  …,
})
class LibHeaderComponent {}

@Component({
selector: 'lib-card',
…,
})
class LibCardComponent {
@ContentChild(LibHeaderComponent) header: LibHeaderComponent|null = null;
}
```
Como `<lib-header>` é opcional, o elemento pode aparecer no template em sua forma mínima, `<lib-card></lib-card>`.
Neste caso, `<lib-header>` não é usado e você esperaria que fosse tree-shaken, mas isso não é o que acontece.
Isso ocorre porque `LibCardComponent` na verdade contém duas referências ao `LibHeaderComponent`:

```typescript
@ContentChild(LibHeaderComponent) header: LibHeaderComponent;
```
- Uma dessas referências está na _posição de tipo_-- ou seja, ela especifica `LibHeaderComponent` como um tipo: `header: LibHeaderComponent;`.
- A outra referência está na _posição de valor_-- ou seja, LibHeaderComponent é o valor do parâmetro decorator `@ContentChild()`: `@ContentChild(LibHeaderComponent)`.

O compilador lida com referências de token nessas posições de forma diferente:

- O compilador apaga referências de _posição de tipo_ após conversão do TypeScript, então elas não têm impacto no tree-shaking.
- O compilador deve manter referências de _posição de valor_ em tempo de execução, o que **previne** o component de ser tree-shaken.

No exemplo, o compilador retém o token `LibHeaderComponent` que ocorre na posição de valor.
Isso previne o component referenciado de ser tree-shaken, mesmo se a aplicação não usar realmente `<lib-header>` em lugar algum.
Se o código, template e estilos do `LibHeaderComponent` se combinarem para se tornar muito grandes, incluí-lo desnecessariamente pode aumentar significativamente o tamanho da aplicação cliente.

## Quando usar o padrão de lightweight injection token

O problema de tree-shaking surge quando um component é usado como um injection token.
Há dois casos quando isso pode acontecer:

- O token é usado na posição de valor de uma [content query](guide/components/queries#content-queries).
- O token é usado como um especificador de tipo para injeção de constructor.

No exemplo a seguir, ambos os usos do token `OtherComponent` causam retenção de `OtherComponent`, prevenindo-o de ser tree-shaken quando não é usado:

```typescript
class MyComponent {
  constructor(@Optional() other: OtherComponent) {}

@ContentChild(OtherComponent) other: OtherComponent|null;
}
```
Embora tokens usados apenas como especificadores de tipo sejam removidos quando convertidos para JavaScript, todos os tokens usados para dependency injection são necessários em tempo de execução.
Estes efetivamente mudam `constructor(@Optional() other: OtherComponent)` para `constructor(@Optional() @Inject(OtherComponent) other)`.
O token está agora em uma posição de valor, o que faz com que o tree-shaker mantenha a referência.

ÚTIL: Bibliotecas devem usar [tree-shakable providers](guide/di/dependency-injection#providing-dependency) para todos os services, fornecendo dependências no nível raiz ao invés de em components ou modules.

## Usando lightweight injection tokens

O padrão de design de lightweight injection token consiste em usar uma pequena classe abstrata como um injection token, e fornecer a implementação real em um estágio posterior.
A classe abstrata é retida, não tree-shaken, mas ela é pequena e não tem impacto material no tamanho da aplicação.

O exemplo a seguir mostra como isso funciona para o `LibHeaderComponent`:

```typescript
abstract class LibHeaderToken {}

@Component({
selector: 'lib-header',
providers: [
{provide: LibHeaderToken, useExisting: LibHeaderComponent}
]
…,
})
class LibHeaderComponent extends LibHeaderToken {}

@Component({
selector: 'lib-card',
…,
})
class LibCardComponent {
@ContentChild(LibHeaderToken) header: LibHeaderToken|null = null;
}
```
Neste exemplo, a implementação de `LibCardComponent` não se refere mais a `LibHeaderComponent` nem na posição de tipo nem na posição de valor.
Isso permite que o tree-shaking completo de `LibHeaderComponent` ocorra.
O `LibHeaderToken` é retido, mas é apenas uma declaração de classe, sem implementação concreta.
É pequeno e não impacta materialmente o tamanho da aplicação quando retido após compilação.

Em vez disso, `LibHeaderComponent` em si implementa a classe abstrata `LibHeaderToken`.
Você pode usar com segurança esse token como o provider na definição do component, permitindo que o Angular injete corretamente o tipo concreto.

Para resumir, o padrão de lightweight injection token consiste do seguinte:

1. Um lightweight injection token que é representado como uma classe abstrata.
1. Uma definição de component que implementa a classe abstrata.
1. Injeção do padrão lightweight, usando `@ContentChild()` ou `@ContentChildren()`.
1. Um provider na implementação do lightweight injection token que associa o lightweight injection token com a implementação.

### Use o lightweight injection token para definição de API

Um component que injeta um lightweight injection token pode precisar invocar um método na classe injetada.
O token agora é uma classe abstrata. Como o component injetável implementa aquela classe, você também deve declarar um método abstrato na classe abstrata de lightweight injection token.
A implementação do método, com toda sua sobrecarga de código, reside no component injetável que pode ser tree-shaken.
Isso permite que o pai se comunique com o filho, se estiver presente, de maneira type-safe.

Por exemplo, o `LibCardComponent` agora consulta `LibHeaderToken` ao invés de `LibHeaderComponent`.
O exemplo a seguir mostra como o padrão permite que `LibCardComponent` se comunique com o `LibHeaderComponent` sem realmente se referir a `LibHeaderComponent`:

```typescript
abstract class LibHeaderToken {
  abstract doSomething(): void;
}

@Component({
selector: 'lib-header',
providers: [
{provide: LibHeaderToken, useExisting: LibHeaderComponent}
]
…,
})
class LibHeaderComponent extends LibHeaderToken {
doSomething(): void {
// Concrete implementation of `doSomething`
}
}

@Component({
selector: 'lib-card',
…,
})
class LibCardComponent implement AfterContentInit {
@ContentChild(LibHeaderToken) header: LibHeaderToken|null = null;

ngAfterContentInit(): void {
if (this.header !== null) {
this.header?.doSomething();
}
}
}
```
Neste exemplo, o pai consulta o token para obter o component filho, e armazena a referência do component resultante se estiver presente.
Antes de chamar um método no filho, o component pai verifica se o component filho está presente.
Se o component filho foi tree-shaken, não há referência em runtime a ele, e nenhuma chamada ao seu método.

### Nomeando seu lightweight injection token

Lightweight injection tokens são úteis apenas com components.
O guia de estilo do Angular sugere que você nomeie components usando o sufixo "Component".
O exemplo "LibHeaderComponent" segue esta convenção.

Você deve manter a relação entre o component e seu token enquanto ainda os distingue.
O estilo recomendado é usar o nome base do component com o sufixo "`Token`" para nomear seus lightweight injection tokens: "`LibHeaderToken`."

# Interoperabilidade entre RxJS e signals do Angular

O pacote `@angular/core/rxjs-interop` oferece APIs que ajudam você a integrar RxJS e signals do Angular.

## Criar um signal a partir de um Observable RxJs com `toSignal`

Use a função `toSignal` para criar um signal que rastreia o valor de um Observable. Ela se comporta de forma similar ao pipe `async` em templates, mas é mais flexível e pode ser usada em qualquer lugar de uma aplicação.

```typescript
import { Component } from '@angular/core';
import { AsyncPipe } from '@angular/common';
import { interval } from 'rxjs';
import { toSignal } from '@angular/core/rxjs-interop';

@Component({
  template: `{{ counter() }}`,
})
export class Ticker {
  counterObservable = interval(1000);

// Get a `Signal` representing the `counterObservable`'s value.
  counter = toSignal(this.counterObservable, {initialValue: 0});
}
```

Assim como o pipe `async`, `toSignal` se inscreve no Observable imediatamente, o que pode disparar efeitos colaterais. A inscrição criada por `toSignal` automaticamente cancela a inscrição do Observable quando o component ou service que chama `toSignal` é destruído.

IMPORTANTE: `toSignal` cria uma inscrição. Você deve evitar chamá-lo repetidamente para o mesmo Observable, e em vez disso reutilizar o signal que ele retorna.

### Contexto de injeção

`toSignal` por padrão precisa executar em um [contexto de injeção](guide/di/dependency-injection-context), como durante a construção de um component ou service. Se um contexto de injeção não estiver disponível, você pode especificar manualmente o `Injector` a ser usado.

### Valores iniciais

Observables podem não produzir um valor de forma síncrona na inscrição, mas signals sempre requerem um valor atual. Existem várias maneiras de lidar com esse valor "inicial" dos signals `toSignal`.

#### A opção `initialValue`

Como no exemplo acima, você pode especificar uma opção `initialValue` com o valor que o signal deve retornar antes que o Observable emita pela primeira vez.

#### Valores iniciais `undefined`

Se você não fornecer um `initialValue`, o signal resultante retornará `undefined` até que o Observable emita. Isso é similar ao comportamento do pipe `async` de retornar `null`.

#### A opção `requireSync`

Alguns Observables são garantidos para emitir de forma síncrona, como `BehaviorSubject`. Nesses casos, você pode especificar a opção `requireSync: true`.

Quando `requiredSync` é `true`, `toSignal` garante que o Observable emita de forma síncrona na inscrição. Isso garante que o signal sempre tenha um valor, e nenhum tipo `undefined` ou valor inicial é necessário.

### `manualCleanup`

Por padrão, `toSignal` automaticamente cancela a inscrição do Observable quando o component ou service que o cria é destruído.

Para substituir esse comportamento, você pode passar a opção `manualCleanup`. Você pode usar essa configuração para Observables que se completam naturalmente.

#### Comparação de igualdade personalizada

Alguns observables podem emitir valores que são **iguais** mesmo que difiram por referência ou detalhe menor. A opção `equal` permite que você defina uma **função de igualdade personalizada** para determinar quando dois valores consecutivos devem ser considerados iguais.

Quando dois valores emitidos são considerados iguais, o signal resultante **não atualiza**. Isso evita computações redundantes, atualizações de DOM ou effects sendo executados desnecessariamente.

```ts
import { Component } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { interval, map } from 'rxjs';

@Component(/* ... */)
export class EqualExample {
  temperature$ = interval(1000).pipe(
    map(() => ({ temperature: Math.floor(Math.random() * 3) + 20 }) ) // 20, 21, or 22 randomly
  );

// Only update if the temperature changes
  temperature = toSignal(this.temperature$, {
    initialValue: { temperature : 20  },
    equal: (prev, curr) => prev.temperature === curr.temperature
  });
}
```

### Erro e Conclusão

Se um Observable usado em `toSignal` produz um erro, esse erro é lançado quando o signal é lido.

Se um Observable usado em `toSignal` se completa, o signal continua a retornar o valor emitido mais recente antes da conclusão.

## Criar um Observable RxJS a partir de um signal com `toObservable`

Use o utilitário `toObservable` para criar um `Observable` que rastreia o valor de um signal. O valor do signal é monitorado com um `effect` que emite o valor para o Observable quando ele muda.

```ts
import { Component, signal } from '@angular/core';
import { toObservable } from '@angular/core/rxjs-interop';

@Component(/* ... */)
export class SearchResults {
  query: Signal<string> = inject(QueryService).query;
  query$ = toObservable(this.query);

results$ = this.query$.pipe(
    switchMap(query => this.http.get('/search?q=' + query ))
  );
}
```

Conforme o signal `query` muda, o Observable `query$` emite a última query e dispara uma nova requisição HTTP.

### Contexto de injeção

`toObservable` por padrão precisa executar em um [contexto de injeção](guide/di/dependency-injection-context), como durante a construção de um component ou service. Se um contexto de injeção não estiver disponível, você pode especificar manualmente o `Injector` a ser usado.

### Timing de `toObservable`

`toObservable` usa um effect para rastrear o valor do signal em um `ReplaySubject`. Na inscrição, o primeiro valor (se disponível) pode ser emitido de forma síncrona, e todos os valores subsequentes serão assíncronos.

Diferente de Observables, signals nunca fornecem uma notificação síncrona de mudanças. Mesmo se você atualizar o valor de um signal várias vezes, `toObservable` só emitirá o valor depois que o signal estabilizar.

```ts
const obs$ = toObservable(mySignal);
obs$.subscribe(value => console.log(value));

mySignal.set(1);
mySignal.set(2);
mySignal.set(3);
```

Aqui, apenas o último valor (3) será registrado no log.

## Usando `rxResource` para dados assíncronos

IMPORTANTE: `rxResource` é [experimental](reference/releases#experimental). Está pronto para você testar, mas pode mudar antes de se tornar estável.

A [função `resource` do Angular](/guide/signals/resource) fornece uma maneira de incorporar dados assíncronos no código baseado em signals da sua aplicação. Construindo em cima desse padrão, `rxResource` permite que você defina um resource onde a fonte dos seus dados é definida em termos de um `Observable` RxJS. Em vez de aceitar uma função `loader`, `rxResource` aceita uma função `stream` que aceita um `Observable` RxJS.

```typescript
import {Component, inject} from '@angular/core';
import {rxResource} from '@angular/core/rxjs-interop';

@Component(/* ... */)
export class UserProfile {
  // This component relies on a service that exposes data through an RxJS Observable.
  private userData = inject(MyUserDataClient);

protected userId = input<string>();

private userResource = rxResource({
    params: () => ({ userId: this.userId() }),

// The `stream` property expects a factory function that returns
    // a data stream as an RxJS Observable.
    stream: ({params}) => this.userData.load(params.userId),
  });
}
```

A propriedade `stream` aceita uma função factory para um `Observable` RxJS. Essa função factory recebe o valor `params` do resource e retorna um `Observable`. O resource chama essa função factory toda vez que a computação `params` produz um novo valor. Veja [Resource loaders](/guide/signals/resource#resource-loaders) para mais detalhes sobre os parâmetros passados para a função factory.

Em todos os outros aspectos, `rxResource` se comporta como e fornece as mesmas APIs que `resource` para especificar parâmetros, ler valores, verificar estado de carregamento e examinar erros.

# Interoperabilidade entre RxJS e outputs de component e directive

DICA: Este guia assume que você está familiarizado com [outputs de component e directive](guide/components/outputs).

O pacote `@angular/rxjs-interop` oferece duas APIs relacionadas a outputs de component e directive.

## Criando um output baseado em um Observable RxJs

O `outputFromObservable` permite que você crie um output de component ou directive que emite baseado em um observable RxJS:

```ts
{highlight:[9]}
import {Directive} from '@angular/core';
import {outputFromObservable} from '@angular/core/rxjs-interop';

@Directive({/*...*/})
class Draggable {
    pointerMoves$: Observable<PointerMovements> = listenToPointerMoves();

// Whenever `pointerMoves$` emits, the `pointerMove` event fires.
    pointerMove = outputFromObservable(this.pointerMoves$);
}
```

A função `outputFromObservable` tem um significado especial para o compilador Angular. **Você só pode chamar `outputFromObservable` em inicializadores de propriedade de component e directive.**

Quando você faz `subscribe` no output, o Angular automaticamente encaminha a inscrição para o observable subjacente. O Angular para de encaminhar valores quando o component ou directive é destruído.

ÚTIL: Considere usar `output()` diretamente se você puder emitir valores de forma imperativa.

## Criando um Observable RxJS a partir de um output de component ou directive

A função `outputToObservable` permite que você crie um observable RxJS a partir de um output de component.

```ts
{highlight:[11]}
import {outputToObservable} from '@angular/core/rxjs-interop';

@Component(/*...*/)
    class CustomSlider {
    valueChange = output<number>();
}

// Instance reference to `CustomSlider`.
const slider: CustomSlider = createSlider();

outputToObservable(slider.valueChange) // Observable<number>
    .pipe(...)
    .subscribe(...);
```

ÚTIL: Considere usar o method `subscribe` em `OutputRef` diretamente se ele atender suas necessidades.

# Configurando o `HttpClient`

Antes de usar o `HttpClient` em sua aplicação, você deve configurá-lo usando [dependency injection](guide/di).

## Fornecendo o `HttpClient` através de dependency injection

O `HttpClient` é fornecido usando a função auxiliar `provideHttpClient`, que a maioria das aplicações inclui nos `providers` da aplicação no arquivo `app.config.ts`.

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(),
  ]
};
```

Se sua aplicação está usando bootstrap baseado em NgModule, você pode incluir `provideHttpClient` nos providers do NgModule da sua aplicação:

```ts
@NgModule({
  providers: [
    provideHttpClient(),
  ],
  // ... other application configuration
})
export class AppModule {}
```

Você pode então injetar o service `HttpClient` como uma dependência de seus components, services ou outras classes:

```ts
@Injectable({providedIn: 'root'})
export class ConfigService {
  private http = inject(HttpClient);
  // This service can now make HTTP requests via `this.http`.
}
```

## Configurando recursos do `HttpClient`

`provideHttpClient` aceita uma lista de configurações de recursos opcionais, para habilitar ou configurar o comportamento de diferentes aspectos do cliente. Esta seção detalha os recursos opcionais e seus usos.

### `withFetch`

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withFetch(),
    ),
  ]
};
```

Por padrão, o `HttpClient` usa a API [`XMLHttpRequest`](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest) para fazer requisições. O recurso `withFetch` altera o cliente para usar a API [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) ao invés disso.

`fetch` é uma API mais moderna e está disponível em alguns ambientes onde `XMLHttpRequest` não é suportada. No entanto, ela possui algumas limitações, como não produzir eventos de progresso de upload.

### `withInterceptors(...)`

`withInterceptors` configura o conjunto de funções interceptor que processarão as requisições feitas através do `HttpClient`. Consulte o [guia de interceptors](guide/http/interceptors) para mais informações.

### `withInterceptorsFromDi()`

`withInterceptorsFromDi` inclui o estilo antigo de interceptors baseados em classe na configuração do `HttpClient`. Consulte o [guia de interceptors](guide/http/interceptors) para mais informações.

HELPFUL: Interceptors funcionais (através de `withInterceptors`) têm ordenação mais previsível e nós os recomendamos ao invés de interceptors baseados em DI.

### `withRequestsMadeViaParent()`

Por padrão, quando você configura o `HttpClient` usando `provideHttpClient` dentro de um determinado injector, esta configuração substitui qualquer configuração para `HttpClient` que possa estar presente no injector pai.

Quando você adiciona `withRequestsMadeViaParent()`, o `HttpClient` é configurado para passar as requisições para a instância `HttpClient` no injector pai, uma vez que elas tenham passado por quaisquer interceptors configurados neste nível. Isso é útil se você deseja _adicionar_ interceptors em um injector filho, enquanto ainda envia a requisição através dos interceptors do injector pai também.

CRITICAL: Você deve configurar uma instância de `HttpClient` acima do injector atual, ou esta opção não é válida e você receberá um erro de execução quando tentar usá-la.

### `withJsonpSupport()`

Incluir `withJsonpSupport` habilita o método `.jsonp()` no `HttpClient`, que faz uma requisição GET através da [convenção JSONP](https://en.wikipedia.org/wiki/JSONP) para carregamento de dados entre domínios.

HELPFUL: Prefira usar [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) para fazer requisições entre domínios ao invés de JSONP quando possível.

### `withXsrfConfiguration(...)`

Incluir esta opção permite a customização da funcionalidade de segurança XSRF integrada do `HttpClient`. Consulte o [guia de segurança](best-practices/security) para mais informações.

### `withNoXsrfProtection()`

Incluir esta opção desabilita a funcionalidade de segurança XSRF integrada do `HttpClient`. Consulte o [guia de segurança](best-practices/security) para mais informações.

## Configuração baseada em `HttpClientModule`

Algumas aplicações podem configurar o `HttpClient` usando a API antiga baseada em NgModules.

Esta tabela lista os NgModules disponíveis em `@angular/common/http` e como eles se relacionam com as funções de configuração de provider acima.

| **NgModule**                            | Equivalente em `provideHttpClient()`          |
| --------------------------------------- | --------------------------------------------- |
| `HttpClientModule`                      | `provideHttpClient(withInterceptorsFromDi())` |
| `HttpClientJsonpModule`                 | `withJsonpSupport()`                          |
| `HttpClientXsrfModule.withOptions(...)` | `withXsrfConfiguration(...)`                  |
| `HttpClientXsrfModule.disable()`        | `withNoXsrfProtection()`                      |
Quando `HttpClientModule` está presente em múltiplos injectors, o comportamento dos interceptors é mal definido e depende das opções exatas e da ordenação de provider/import.

Prefira `provideHttpClient` para configurações com múltiplos injectors, pois ele tem comportamento mais estável. Veja o recurso `withRequestsMadeViaParent` acima.

# Fazendo requisições HTTP

`HttpClient` tem métodos correspondentes aos diferentes verbos HTTP usados para fazer requisições, tanto para carregar dados quanto para aplicar mutações no servidor. Cada método retorna um [RxJS `Observable`](https://rxjs.dev/guide/observable) que, quando inscrito, envia a requisição e então emite os resultados quando o servidor responde.

NOTE: `Observable`s criados por `HttpClient` podem ser inscritos qualquer número de vezes e farão uma nova requisição backend para cada inscrição.

Através de um objeto de opções passado para o método de requisição, várias propriedades da requisição e o tipo de resposta retornado podem ser ajustados.

## Buscando dados JSON

Buscar dados de um backend frequentemente requer fazer uma requisição GET usando o método [`HttpClient.get()`](api/common/http/HttpClient#get). Este método recebe dois argumentos: a string da URL do endpoint do qual buscar, e um _objeto de opções opcional_ para configurar a requisição.

Por exemplo, para buscar dados de configuração de uma API hipotética usando o método `HttpClient.get()`:

```ts
http.get<Config>('/api/config').subscribe(config => {
  // process the configuration.
});
```

Note o argumento de tipo genérico que especifica que os dados retornados pelo servidor serão do tipo `Config`. Este argumento é opcional, e se você omiti-lo então os dados retornados terão o tipo `Object`.

TIP: Ao lidar com dados de estrutura incerta e valores potenciais `undefined` ou `null`, considere usar o tipo `unknown` em vez de `Object` como o tipo de resposta.

CRITICAL: O tipo genérico dos métodos de requisição é uma **asserção** de tipo sobre os dados retornados pelo servidor. `HttpClient` não verifica se os dados de retorno reais correspondem a este tipo.

## Buscando outros tipos de dados

Por padrão, `HttpClient` assume que os servidores retornarão dados JSON. Ao interagir com uma API não-JSON, você pode dizer ao `HttpClient` que tipo de resposta esperar e retornar ao fazer a requisição. Isso é feito com a opção `responseType`.

| **Valor de `responseType`** | **Tipo de resposta retornado**                                                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `'json'` (padrão)       | Dados JSON do tipo genérico dado                                                                                                       |
| `'text'`                 | Dados string                                                                                                                               |
| `'arraybuffer'`          | [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) contendo os bytes brutos da resposta |
| `'blob'`                 | Instância [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob)                                                                        |

Por exemplo, você pode pedir ao `HttpClient` para baixar os bytes brutos de uma imagem `.jpeg` em um `ArrayBuffer`:

```ts
http.get('/images/dog.jpg', {responseType: 'arraybuffer'}).subscribe(buffer => {
  console.log('The image is ' + buffer.byteLength + ' bytes large');
});
```
Como o valor de `responseType` afeta o tipo retornado por `HttpClient`, ele deve ter um tipo literal e não um tipo `string`.

Isso acontece automaticamente se o objeto de opções passado para o método de requisição for um objeto literal, mas se você estiver extraindo as opções de requisição para uma variável ou método auxiliar, pode precisar especificá-lo explicitamente como um literal, como `responseType: 'text' as const`.
## Mutando o estado do servidor

APIs de servidor que realizam mutações frequentemente requerem fazer requisições POST com um corpo de requisição especificando o novo estado ou a mudança a ser feita.

O método [`HttpClient.post()`](api/common/http/HttpClient#post) se comporta de forma semelhante a `get()`, e aceita um argumento `body` adicional antes de suas opções:

```ts
http.post<Config>('/api/config', newConfig).subscribe(config => {
  console.log('Updated config:', config);
});
```

Muitos tipos diferentes de valores podem ser fornecidos como o `body` da requisição, e `HttpClient` os serializará adequadamente:

| **Tipo de `body`**                                                                                                               | **Serializado como**                                    |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| string                                                                                                                        | Texto simples                                           |
| number, boolean, array ou plain object                                                                                       | JSON                                                 |
| [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)                       | dados brutos do buffer                             |
| [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob)                                                                     | dados brutos com o content type do `Blob`              |
| [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData)                                                             | dados codificados como `multipart/form-data`                   |
| [`HttpParams`](api/common/http/HttpParams) ou [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) | string formatada como `application/x-www-form-urlencoded` |

IMPORTANT: Lembre-se de fazer `.subscribe()` nos `Observable`s de requisição de mutação para realmente disparar a requisição.

## Definindo parâmetros de URL

Especifique parâmetros de requisição que devem ser incluídos na URL da requisição usando a opção `params`.

Passar um objeto literal é a maneira mais simples de configurar parâmetros de URL:

```ts
http.get('/api/config', {
  params: {filter: 'all'},
}).subscribe(config => {
  // ...
});
```

Alternativamente, passe uma instância de `HttpParams` se você precisar de mais controle sobre a construção ou serialização dos parâmetros.

IMPORTANT: Instâncias de `HttpParams` são _imutáveis_ e não podem ser alteradas diretamente. Em vez disso, métodos de mutação como `append()` retornam uma nova instância de `HttpParams` com a mutação aplicada.

```ts
const baseParams = new HttpParams().set('filter', 'all');

http.get('/api/config', {
  params: baseParams.set('details', 'enabled'),
}).subscribe(config => {
  // ...
});
```

Você pode instanciar `HttpParams` com um `HttpParameterCodec` personalizado que determina como `HttpClient` codificará os parâmetros na URL.

### Codificação de parâmetros personalizada

Por padrão, `HttpParams` usa o [`HttpUrlEncodingCodec`](api/common/http/HttpUrlEncodingCodec) embutido para codificar e decodificar chaves e valores de parâmetros.

Você pode fornecer sua própria implementação de [`HttpParameterCodec`](api/common/http/HttpParameterCodec) para personalizar como a codificação e decodificação são aplicadas.

```ts
import { HttpClient, HttpParams, HttpParameterCodec } from '@angular/common/http';
import { inject } from '@angular/core';

export class CustomHttpParamEncoder  implements HttpParameterCodec {
  encodeKey(key: string): string   {
    return encodeURIComponent(key);
  }

encodeValue(value: string): string {
    return encodeURIComponent(value);
  }

decodeKey(key: string): string {
    return decodeURIComponent(key);
  }

decodeValue(value: string): string {
    return decodeURIComponent(value);
  }
}

export class ApiService {
  private http = inject(HttpClient);

search() {
    const params = new HttpParams({
      encoder: new CustomHttpParamEncoder(),
    })
    .set('email', 'dev+alerts@example.com')
    .set('q', 'a & b? c/d = e');

return this.http.get('/api/items', { params });
  }
}
```

## Definindo headers de requisição

Especifique headers de requisição que devem ser incluídos na requisição usando a opção `headers`.

Passar um objeto literal é a maneira mais simples de configurar headers de requisição:

```ts
http.get('/api/config', {
  headers: {
    'X-Debug-Level': 'verbose',
  }
}).subscribe(config => {
  // ...
});
```

Alternativamente, passe uma instância de `HttpHeaders` se você precisar de mais controle sobre a construção de headers

IMPORTANT: Instâncias de `HttpHeaders` são _imutáveis_ e não podem ser alteradas diretamente. Em vez disso, métodos de mutação como `append()` retornam uma nova instância de `HttpHeaders` com a mutação aplicada.

```ts
const baseHeaders = new HttpHeaders().set('X-Debug-Level', 'minimal');

http.get<Config>('/api/config', {
  headers: baseHeaders.set('X-Debug-Level', 'verbose'),
}).subscribe(config => {
  // ...
});
```

## Interagindo com os eventos de resposta do servidor

Por conveniência, `HttpClient` por padrão retorna um `Observable` dos dados retornados pelo servidor (o corpo da resposta). Ocasionalmente é desejável examinar a resposta real, por exemplo para recuperar headers de resposta específicos.

Para acessar a resposta inteira, defina a opção `observe` como `'response'`:

```ts
http.get<Config>('/api/config', {observe: 'response'}).subscribe(res => {
  console.log('Response status:', res.status);
  console.log('Body:', res.body);
});
```
Como o valor de `observe` afeta o tipo retornado por `HttpClient`, ele deve ter um tipo literal e não um tipo `string`.

Isso acontece automaticamente se o objeto de opções passado para o método de requisição for um objeto literal, mas se você estiver extraindo as opções de requisição para uma variável ou método auxiliar, pode precisar especificá-lo explicitamente como um literal, como `observe: 'response' as const`.
## Recebendo eventos de progresso brutos

Além do corpo da resposta ou objeto de resposta, `HttpClient` também pode retornar um fluxo de _eventos_ brutos correspondentes a momentos específicos no ciclo de vida da requisição. Esses eventos incluem quando a requisição é enviada, quando o header da resposta é retornado e quando o corpo está completo. Esses eventos também podem incluir _eventos de progresso_ que relatam o status de upload e download para corpos de requisição ou resposta grandes.

Eventos de progresso são desabilitados por padrão (pois têm um custo de desempenho) mas podem ser habilitados com a opção `reportProgress`.

NOTE: A implementação `fetch` opcional de `HttpClient` não relata eventos de progresso de _upload_.

Para observar o fluxo de eventos, defina a opção `observe` como `'events'`:

```ts
http.post('/api/upload', myData, {
  reportProgress: true,
  observe: 'events',
}).subscribe(event => {
  switch (event.type) {
    case HttpEventType.UploadProgress:
      console.log('Uploaded ' + event.loaded + ' out of ' + event.total + ' bytes');
      break;
    case HttpEventType.Response:
      console.log('Finished uploading!');
      break;
  }
});
```
Como o valor de `observe` afeta o tipo retornado por `HttpClient`, ele deve ter um tipo literal e não um tipo `string`.

Isso acontece automaticamente se o objeto de opções passado para o método de requisição for um objeto literal, mas se você estiver extraindo as opções de requisição para uma variável ou método auxiliar, pode precisar especificá-lo explicitamente como um literal, como `observe: 'events' as const`.
Cada `HttpEvent` relatado no fluxo de eventos tem um `type` que distingue o que o evento representa:

| **Valor de `type`**                 | **Significado do evento**                                                                  |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| `HttpEventType.Sent`             | A requisição foi despachada para o servidor                                      |
| `HttpEventType.UploadProgress`   | Um `HttpUploadProgressEvent` relatando progresso no upload do corpo da requisição      |
| `HttpEventType.ResponseHeader`   | O cabeçalho da resposta foi recebido, incluindo status e headers           |
| `HttpEventType.DownloadProgress` | Um `HttpDownloadProgressEvent` relatando progresso no download do corpo da resposta |
| `HttpEventType.Response`         | A resposta inteira foi recebida, incluindo o corpo da resposta                 |
| `HttpEventType.User`             | Um evento personalizado de um interceptor HTTP.                                           |

## Lidando com falha de requisição

Existem três maneiras de uma requisição HTTP falhar:

- Um erro de rede ou conexão pode impedir que a requisição alcance o servidor backend.
- Uma requisição não respondeu a tempo quando a opção de timeout foi definida.
- O backend pode receber a requisição mas falhar ao processá-la, e retornar uma resposta de erro.

`HttpClient` captura todos os tipos de erros acima em um `HttpErrorResponse` que ele retorna através do canal de erro do `Observable`. Erros de rede e timeout têm um código de `status` de `0` e um `error` que é uma instância de [`ProgressEvent`](https://developer.mozilla.org/docs/Web/API/ProgressEvent). Erros de backend têm o código de `status` de falha retornado pelo backend, e a resposta de erro como o `error`. Inspecione a resposta para identificar a causa do erro e a ação apropriada para lidar com o erro.

A [biblioteca RxJS](https://rxjs.dev/) oferece vários operadores que podem ser úteis para tratamento de erros.

Você pode usar o operador `catchError` para transformar uma resposta de erro em um valor para a UI. Este valor pode dizer à UI para exibir uma página ou valor de erro, e capturar a causa do erro se necessário.

Às vezes erros transitórios como interrupções de rede podem causar uma falha inesperada na requisição, e simplesmente tentar novamente a requisição permitirá que ela seja bem-sucedida. RxJS fornece vários operadores de _retry_ que automaticamente re-inscrevem em um `Observable` que falhou sob certas condições. Por exemplo, o operador `retry()` tentará automaticamente re-inscrever um número especificado de vezes.

### Timeouts

Para definir um timeout para uma requisição, você pode definir a opção `timeout` para um número de milissegundos junto com outras opções de requisição. Se a requisição backend não for concluída dentro do tempo especificado, a requisição será abortada e um erro será emitido.

NOTE: O timeout só se aplicará à requisição HTTP backend em si. Não é um timeout para toda a cadeia de processamento de requisição. Portanto, esta opção não é afetada por qualquer atraso introduzido por interceptors.

```ts
http.get('/api/config', {
  timeout: 3000,
}).subscribe({
  next: config => {
    console.log('Config fetched successfully:', config);
  },
  error: err => {
    // If the request times out, an error will have been emitted.
  }
});
```

## Opções avançadas de fetch

Ao usar o provider `withFetch()`, o `HttpClient` do Angular fornece acesso a opções avançadas da API fetch que podem melhorar o desempenho e a experiência do usuário. Essas opções estão disponíveis apenas ao usar o backend fetch.

### Opções de Fetch

As seguintes opções fornecem controle refinado sobre o comportamento da requisição ao usar o backend fetch.

#### Conexões keep-alive

A opção `keepalive` permite que uma requisição sobreviva à página que a iniciou. Isso é particularmente útil para requisições de analytics ou logging que precisam ser concluídas mesmo se o usuário navegar para longe da página.

```ts
http.post('/api/analytics', analyticsData, {
  keepalive: true
}).subscribe();
```

#### Controle de cache HTTP

A opção `cache` controla como a requisição interage com o cache HTTP do navegador, o que pode melhorar significativamente o desempenho para requisições repetidas.

```ts
//  Use cached response regardless of freshness
http.get('/api/config', {
  cache: 'force-cache'
}).subscribe(config => {
  // ...
});

// Always fetch from network, bypass cache
http.get('/api/live-data', {
  cache: 'no-cache'
}).subscribe(data => {
  // ...
});

// Use cached response only, fail if not in cache
http.get('/api/static-data', {
  cache: 'only-if-cached'
}).subscribe(data => {
  // ...
});
```

#### Prioridade de requisição para Core Web Vitals

A opção `priority` permite que você indique a importância relativa de uma requisição, ajudando os navegadores a otimizar o carregamento de recursos para melhores pontuações de Core Web Vitals.

```ts
// High priority for critical resources
http.get('/api/user-profile', {
  priority: 'high'
}).subscribe(profile => {
  // ...
});

// Low priority for non-critical resources
http.get('/api/recommendations', {
  priority: 'low'
}).subscribe(recommendations => {
  // ...
});

// Auto priority (default) lets the browser decide
http.get('/api/settings', {
  priority: 'auto'
}).subscribe(settings => {
  // ...
});
```

Valores de `priority` disponíveis:

- `'high'`: Alta prioridade, carregado cedo (ex: dados críticos do usuário, conteúdo above-the-fold)
- `'low'`: Baixa prioridade, carregado quando recursos estão disponíveis (ex: analytics, dados de prefetch)
- `'auto'`: Navegador determina prioridade com base no contexto da requisição (padrão)

TIP: Use `priority: 'high'` para requisições que afetam o Largest Contentful Paint (LCP) e `priority: 'low'` para requisições que não impactam a experiência inicial do usuário.

#### Modo de requisição

A opção `mode` controla como a requisição lida com requisições cross-origin e determina o tipo de resposta.

```ts
// Same-origin requests only
http.get('/api/local-data', {
  mode: 'same-origin'
}).subscribe(data => {
  // ...
});

// CORS-enabled cross-origin requests
http.get('https://api.external.com/data', {
  mode: 'cors'
}).subscribe(data => {
  // ...
});

// No-CORS mode for simple cross-origin requests
http.get('https://external-api.com/public-data', {
  mode: 'no-cors'
}).subscribe(data => {
  // ...
});
```

Valores de `mode` disponíveis:

- `'same-origin'`: Permitir apenas requisições same-origin, falhar para requisições cross-origin
- `'cors'`: Permitir requisições cross-origin com CORS (padrão)
- `'no-cors'`: Permitir requisições cross-origin simples sem CORS, resposta é opaca

TIP: Use `mode: 'same-origin'` para requisições sensíveis que nunca devem ir cross-origin.

#### Tratamento de redirecionamento

A opção `redirect` especifica como lidar com respostas de redirecionamento do servidor.

```ts
// Follow redirects automatically (default behavior)
http.get('/api/resource', {
  redirect: 'follow'
}).subscribe(data => {
  // ...
});

// Prevent automatic redirects
http.get('/api/resource', {
  redirect: 'manual'
}).subscribe(response => {
  // Handle redirect manually
});

// Treat redirects as errors
http.get('/api/resource', {
  redirect: 'error'
}).subscribe({
  next: data => {
    // Success response
  },
  error: err => {
    // Redirect responses will trigger this error handler
  }
});
```

Valores de `redirect` disponíveis:

- `'follow'`: Seguir redirecionamentos automaticamente (padrão)
- `'error'`: Tratar redirecionamentos como erros
- `'manual'`: Não seguir redirecionamentos automaticamente, retornar resposta de redirecionamento

TIP: Use `redirect: 'manual'` quando você precisar lidar com redirecionamentos com lógica personalizada.

#### Tratamento de credenciais

A opção `credentials` controla se cookies, headers de autorização e outras credenciais são enviados com requisições cross-origin. Isso é particularmente importante para cenários de autenticação.

```ts
// Include credentials for cross-origin requests
http.get('https://api.example.com/protected-data', {
  credentials: 'include'
}).subscribe(data => {
  // ...
});

// Never send credentials (default for cross-origin)
http.get('https://api.example.com/public-data', {
  credentials: 'omit'
}).subscribe(data => {
  // ...
});

// Send credentials only for same-origin requests
http.get('/api/user-data', {
  credentials: 'same-origin'
}).subscribe(data => {
  // ...
});

// withCredentials overrides credentials setting
http.get('https://api.example.com/data', {
  credentials: 'omit',        // This will be ignored
  withCredentials: true       // This forces credentials: 'include'
}).subscribe(data => {
  // Request will include credentials despite credentials: 'omit'
});

// Legacy approach (still supported)
http.get('https://api.example.com/data', {
  withCredentials: true
}).subscribe(data => {
  // Equivalent to credentials: 'include'
});
```

IMPORTANT: A opção `withCredentials` tem precedência sobre a opção `credentials`. Se ambas forem especificadas, `withCredentials: true` sempre resultará em `credentials: 'include'`, independentemente do valor explícito de `credentials`.

Valores de `credentials` disponíveis:

- `'omit'`: Nunca enviar credenciais
- `'same-origin'`: Enviar credenciais apenas para requisições same-origin (padrão)
- `'include'`: Sempre enviar credenciais, mesmo para requisições cross-origin

TIP: Use `credentials: 'include'` quando você precisar enviar cookies ou headers de autenticação para um domínio diferente que suporta CORS. Evite misturar opções `credentials` e `withCredentials` para evitar confusão.

#### Referrer

A opção `referrer` permite que você controle quais informações de referrer são enviadas com a requisição. Isso é importante para considerações de privacidade e segurança.

```ts
// Send a specific referrer URL
http.get('/api/data', {
  referrer: 'https://example.com/page'
}).subscribe(data => {
  // ...
});

// Use the current page as referrer (default behavior)
http.get('/api/analytics', {
  referrer: 'about:client'
}).subscribe(data => {
  // ...
});
```

A opção `referrer` aceita:

- Uma string de URL válida: Define a URL de referrer específica a enviar
- Uma string vazia `''`: Não envia informações de referrer
- `'about:client'`: Usa o referrer padrão (URL da página atual)

TIP: Use `referrer: ''` para requisições sensíveis onde você não quer vazar a URL da página referenciadora.

#### Política de referrer

A opção `referrerPolicy` controla quanta informação de referrer, a URL da página fazendo a requisição é enviada junto com uma requisição HTTP. Esta configuração afeta tanto privacidade quanto analytics, permitindo que você equilibre visibilidade de dados com considerações de segurança.

```ts
// Send no referrer information regardless of the current page
http.get('/api/data', {
  referrerPolicy: 'no-referrer'
}).subscribe();

// Send origin only (e.g. https://example.com)
http.get('/api/analytics', {
  referrerPolicy: 'origin'
}).subscribe();
```

A opção `referrerPolicy` aceita:

- `'no-referrer'` Nunca enviar o header `Referer`.
- `'no-referrer-when-downgrade'` Envia o referrer para requisições same-origin e seguras (HTTPS→HTTPS), mas omite ao navegar de uma origem segura para uma menos segura (HTTPS→HTTP).
- `'origin'` Envia apenas a origem (scheme, host, port) do referrer, omitindo informações de path e query.
- `'origin-when-cross-origin'` Envia a URL completa para requisições same-origin, mas apenas a origem para requisições cross-origin.
- `'same-origin'` Envia a URL completa para requisições same-origin e nenhum referrer para requisições cross-origin.
- `'strict-origin'` Envia apenas a origem, e apenas se o nível de segurança do protocolo não for rebaixado (ex: HTTPS→HTTPS). Omite o referrer no rebaixamento.
- `'strict-origin-when-cross-origin'` Comportamento padrão do navegador. Envia a URL completa para requisições same-origin, a origem para requisições cross-origin quando não rebaixado, e omite o referrer no rebaixamento.
- `'unsafe-url'` Sempre envia a URL completa (incluindo path e query). Isso pode expor dados sensíveis e deve ser usado com cautela.

TIP: Prefira valores conservadores como `'no-referrer'`, `'origin'` ou `'strict-origin-when-cross-origin'` para requisições sensíveis à privacidade.

#### Integridade

A opção `integrity` permite que você verifique que a resposta não foi adulterada fornecendo um hash criptográfico do conteúdo esperado. Isso é particularmente útil para carregar scripts ou outros recursos de CDNs.

```ts
// Verify response integrity with SHA-256 hash
http.get('/api/script.js', {
  integrity: 'sha256-ABC123...',
  responseType: 'text'
}).subscribe(script => {
  // Script content is verified against the hash
});
```

IMPORTANT: A opção `integrity` requer uma correspondência exata entre o conteúdo da resposta e o hash fornecido. Se o conteúdo não corresponder, a requisição falhará com um erro de rede.

TIP: Use integridade de subrecurso ao carregar recursos críticos de fontes externas para garantir que não foram modificados. Gere hashes usando ferramentas como `openssl`.

## `Observable`s HTTP

Cada método de requisição em `HttpClient` constrói e retorna um `Observable` do tipo de resposta solicitado. Entender como esses `Observable`s funcionam é importante ao usar `HttpClient`.

`HttpClient` produz o que RxJS chama de `Observable`s "frios", o que significa que nenhuma requisição real acontece até que o `Observable` seja inscrito. Somente então a requisição é realmente despachada para o servidor. Inscrever-se no mesmo `Observable` várias vezes acionará múltiplas requisições backend. Cada inscrição é independente.

TIP: Você pode pensar nos `Observable`s de `HttpClient` como _blueprints_ para requisições de servidor reais.

Uma vez inscrito, cancelar a inscrição abortará a requisição em andamento. Isso é muito útil se o `Observable` for inscrito via pipe `async`, pois automaticamente cancelará a requisição se o usuário navegar para longe da página atual. Além disso, se você usar o `Observable` com um combinador RxJS como `switchMap`, esse cancelamento limpará quaisquer requisições obsoletas.

Uma vez que a resposta retorna, `Observable`s de `HttpClient` geralmente completam (embora interceptors possam influenciar isso).

Por causa da conclusão automática, geralmente não há risco de vazamentos de memória se inscrições de `HttpClient` não forem limpas. No entanto, como com qualquer operação assíncrona, recomendamos fortemente que você limpe inscrições quando o component que as usa for destruído, pois o callback de inscrição pode de outra forma executar e encontrar erros quando tentar interagir com o component destruído.

TIP: Usar o pipe `async` ou a operação `toSignal` para se inscrever em `Observable`s garante que inscrições sejam descartadas adequadamente.

## Melhores práticas

Embora `HttpClient` possa ser injetado e usado diretamente de components, geralmente recomendamos que você crie services reutilizáveis e injetáveis que isolam e encapsulam lógica de acesso a dados. Por exemplo, este `UserService` encapsula a lógica para solicitar dados para um usuário por seu id:

```ts
@Injectable({providedIn: 'root'})
export class UserService {
  private http = inject(HttpClient);

getUser(id: string): Observable<User> {
    return this.http.get<User>(`/api/user/${id}`);
  }
}
```

Dentro de um component, você pode combinar `@if` com o pipe `async` para renderizar a UI para os dados apenas depois que terminar de carregar:

```typescript
import { AsyncPipe } from '@angular/common';

@Component({
  imports: [AsyncPipe],
  template: `
    @if (user$ | async; as user) {
      <p>Name: {{ user.name }}</p>
      <p>Biography: {{ user.biography }}</p>
    }
  `,
})
export class UserProfileComponent {
  userId = input.required<string>();
  user$!: Observable<User>;

private userService = inject(UserService);

constructor(): void {
    effect(() => {
      this.user$ = this.userService.getUser(this.userId());
    });
  }
}
```

# Interceptors

`HttpClient` suporta uma forma de middleware conhecida como _interceptors_.

TLDR: Interceptors são middleware que permitem que padrões comuns relacionados a novas tentativas, caching, logging e autenticação sejam abstraídos das requisições individuais.

`HttpClient` suporta dois tipos de interceptors: funcionais e baseados em DI. Nossa recomendação é usar interceptors funcionais porque eles têm comportamento mais previsível, especialmente em configurações complexas. Nossos exemplos neste guia usam interceptors funcionais, e cobrimos [interceptors baseados em DI](#di-based-interceptors) em sua própria seção no final.

## Interceptors

Interceptors são geralmente funções que você pode executar para cada requisição, e têm amplas capacidades para afetar o conteúdo e o fluxo geral de requisições e respostas. Você pode instalar múltiplos interceptors, que formam uma cadeia de interceptors onde cada interceptor processa a requisição ou resposta antes de encaminhá-la para o próximo interceptor na cadeia.

Você pode usar interceptors para implementar uma variedade de padrões comuns, como:

- Adicionar headers de autenticação a requisições de saída para uma API específica.
- Tentar novamente requisições que falharam com backoff exponencial.
- Fazer cache de respostas por um período de tempo, ou até que sejam invalidadas por mutações.
- Personalizar o parsing de respostas.
- Medir tempos de resposta do servidor e registrá-los.
- Controlar elementos de UI como um spinner de carregamento enquanto operações de rede estão em andamento.
- Coletar e agrupar requisições feitas dentro de um determinado período de tempo.
- Falhar automaticamente requisições após um prazo ou timeout configurável.
- Consultar regularmente o servidor e atualizar resultados.

## Definindo um interceptor

A forma básica de um interceptor é uma função que recebe a `HttpRequest` de saída e uma função `next` representando o próximo passo de processamento na cadeia de interceptors.

Por exemplo, este `loggingInterceptor` irá registrar a URL da requisição de saída no `console.log` antes de encaminhar a requisição:

```ts
export function loggingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  console.log(req.url);
  return next(req);
}
```

Para que este interceptor realmente intercepte requisições, você deve configurar o `HttpClient` para usá-lo.

## Configurando interceptors

Você declara o conjunto de interceptors a serem usados ao configurar o `HttpClient` através de dependency injection, usando a feature `withInterceptors`:

```ts
bootstrapApplication(AppComponent, {providers: [
  provideHttpClient(
    withInterceptors([loggingInterceptor, cachingInterceptor]),
  )
]});
```

Os interceptors que você configura são encadeados na ordem em que você os listou nos providers. No exemplo acima, o `loggingInterceptor` processaria a requisição e então a encaminharia para o `cachingInterceptor`.

### Interceptando eventos de resposta

Um interceptor pode transformar o stream `Observable` de `HttpEvent`s retornado por `next` para acessar ou manipular a resposta. Como este stream inclui todos os eventos de resposta, inspecionar o `.type` de cada evento pode ser necessário para identificar o objeto de resposta final.

```ts
export function loggingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  return next(req).pipe(tap(event => {
    if (event.type === HttpEventType.Response) {
      console.log(req.url, 'returned a response with status', event.status);
    }
  }));
}
```

DICA: Interceptors naturalmente associam respostas com suas requisições de saída, porque eles transformam o stream de resposta em um closure que captura o objeto da requisição.

## Modificando requisições {#di-based-interceptors}

A maioria dos aspectos das instâncias de `HttpRequest` e `HttpResponse` são _imutáveis_, e interceptors não podem modificá-los diretamente. Em vez disso, interceptors aplicam mutações clonando esses objetos usando a operação `.clone()`, e especificando quais propriedades devem ser mutadas na nova instância. Isso pode envolver realizar atualizações imutáveis no próprio valor (como `HttpHeaders` ou `HttpParams`).

Por exemplo, para adicionar um header a uma requisição:

```ts
const reqWithHeader = req.clone({
  headers: req.headers.set('X-New-Header', 'new header value'),
});
```

Esta imutabilidade permite que a maioria dos interceptors sejam idempotentes se a mesma `HttpRequest` for submetida à cadeia de interceptors múltiplas vezes. Isso pode acontecer por algumas razões, incluindo quando uma requisição é tentada novamente após falha.

CRÍTICO: O body de uma requisição ou resposta **não** está protegido contra mutações profundas. Se um interceptor deve mutar o body, tenha cuidado ao lidar com execução múltipla na mesma requisição.

## Dependency injection em interceptors

Interceptors são executados no _contexto de injeção_ do injector que os registrou, e podem usar a API `inject` do Angular para recuperar dependências.

Por exemplo, suponha que uma aplicação tenha um service chamado `AuthService`, que cria tokens de autenticação para requisições de saída. Um interceptor pode injetar e usar este service:

```ts
export function authInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn) {
  // Inject the current `AuthService` and use it to get an authentication token:
  const authToken = inject(AuthService).getAuthToken();

// Clone the request to add the authentication header.
  const newReq = req.clone({
    headers: req.headers.append('X-Authentication-Token', authToken),
  });
  return next(newReq);
}
```

## Metadados de requisição e resposta

Frequentemente é útil incluir informações em uma requisição que não são enviadas para o backend, mas são especificamente destinadas a interceptors. `HttpRequest`s têm um objeto `.context` que armazena esse tipo de metadado como uma instância de `HttpContext`. Este objeto funciona como um mapa tipado, com chaves do tipo `HttpContextToken`.

Para ilustrar como este sistema funciona, vamos usar metadados para controlar se um interceptor de caching está habilitado para uma determinada requisição.

### Definindo tokens de contexto

Para armazenar se o interceptor de caching deve fazer cache de uma requisição específica no mapa `.context` dessa requisição, defina um novo `HttpContextToken` para atuar como uma chave:

```ts
export const CACHING_ENABLED = new HttpContextToken<boolean>(() => true);
```

A função fornecida cria o valor padrão para o token para requisições que não definiram explicitamente um valor para ele. Usar uma função garante que se o valor do token for um objeto ou array, cada requisição obtenha sua própria instância.

### Lendo o token em um interceptor

Um interceptor pode então ler o token e escolher aplicar lógica de caching ou não com base em seu valor:

```ts
export function cachingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  if (req.context.get(CACHING_ENABLED)) {
    // apply caching logic
    return ...;
  } else {
    // caching has been disabled for this request
    return next(req);
  }
}
```

### Definindo tokens de contexto ao fazer uma requisição

Ao fazer uma requisição via API `HttpClient`, você pode fornecer valores para `HttpContextToken`s:

```ts
const data$ = http.get('/sensitive/data', {
  context: new HttpContext().set(CACHING_ENABLED, false),
});
```

Interceptors podem ler esses valores do `HttpContext` da requisição.

### O contexto da requisição é mutável

Diferentemente de outras propriedades de `HttpRequest`s, o `HttpContext` associado é _mutável_. Se um interceptor mudar o contexto de uma requisição que é tentada novamente mais tarde, o mesmo interceptor observará a mutação do contexto quando executar novamente. Isso é útil para passar estado através de múltiplas tentativas se necessário.

## Respostas sintéticas

A maioria dos interceptors simplesmente invocará o handler `next` enquanto transforma a requisição ou a resposta, mas isso não é estritamente um requisito. Esta seção discute várias das maneiras pelas quais um interceptor pode incorporar comportamento mais avançado.

Interceptors não são obrigados a invocar `next`. Eles podem em vez disso escolher construir respostas através de algum outro mecanismo, como de um cache ou enviando a requisição através de um mecanismo alternativo.

Construir uma resposta é possível usando o construtor `HttpResponse`:

```ts
const resp = new HttpResponse({
  body: 'response body',
});
```

## Trabalhando com informações de redirecionamento

Ao usar `HttpClient` com o provider `withFetch`, as respostas incluem uma propriedade `redirected` que indica se a resposta foi o resultado de um redirecionamento. Esta propriedade se alinha com a especificação da API Fetch nativa e pode ser útil em interceptors para lidar com cenários de redirecionamento.

Um interceptor pode acessar e agir sobre as informações de redirecionamento:

```ts
export function redirectTrackingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  return next(req).pipe(tap(event => {
    if (event.type === HttpEventType.Response && event.redirected) {
      console.log('Request to', req.url, 'was redirected to', event.url);
      // Handle redirect logic - maybe update analytics, security checks, etc.
    }
  }));
}
```

Você também pode usar as informações de redirecionamento para implementar lógica condicional em seus interceptors:

```ts
export function authRedirectInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  return next(req).pipe(tap(event => {
    if (event.type === HttpEventType.Response && event.redirected) {
      // Check if we were redirected to a login page
      if (event.url?.includes('/login')) {
        // Handle authentication redirect
        handleAuthRedirect();
      }
    }
  }));
}
```

## Trabalhando com tipos de resposta

Ao usar `HttpClient` com o provider `withFetch`, as respostas incluem uma propriedade `type` que indica como o browser lidou com a resposta com base em políticas CORS e modo de requisição. Esta propriedade se alinha com a especificação da API Fetch nativa e fornece insights valiosos para debugar problemas de CORS e entender a acessibilidade da resposta.

A propriedade `type` da resposta pode ter os seguintes valores:

- `'basic'` - Resposta de mesma origem com todos os headers acessíveis
- `'cors'` - Resposta de origem cruzada com headers CORS configurados adequadamente
- `'opaque'` - Resposta de origem cruzada sem CORS, headers e body podem ser limitados
- `'opaqueredirect'` - Resposta de uma requisição redirecionada em modo no-cors
- `'error'` - Ocorreu um erro de rede

Um interceptor pode usar informações de tipo de resposta para debugging de CORS e tratamento de erros:

```ts
export function responseTypeInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  return next(req).pipe(map(event => {
    if (event.type === HttpEventType.Response) {
      // Handle different response types appropriately
      switch (event.responseType) {
        case 'opaque':
          // Limited access to response data
          console.warn('Limited response data due to CORS policy');
          break;
        case 'cors':
        case 'basic':
          // Full access to response data
          break;
        case 'error':
          // Handle network errors
          console.error('Network error in response');
          break;
      }
    }
  }));
}
```

## Interceptors baseados em DI

`HttpClient` também suporta interceptors que são definidos como classes injetáveis e configurados através do sistema de DI. As capacidades de interceptors baseados em DI são idênticas às de interceptors funcionais, mas o mecanismo de configuração é diferente.

Um interceptor baseado em DI é uma classe injetável que implementa a interface `HttpInterceptor`:

```ts
@Injectable()
export class LoggingInterceptor implements HttpInterceptor {
  intercept(req: HttpRequest<any>, handler: HttpHandler): Observable<HttpEvent<any>> {
    console.log('Request URL: ' + req.url);
    return handler.handle(req);
  }
}
```

Interceptors baseados em DI são configurados através de um multi-provider de dependency injection:

```ts
bootstrapApplication(AppComponent, {providers: [
  provideHttpClient(
    // DI-based interceptors must be explicitly enabled.
    withInterceptorsFromDi(),
  ),

{provide: HTTP_INTERCEPTORS, useClass: LoggingInterceptor, multi: true},
]});
```

Interceptors baseados em DI executam na ordem em que seus providers são registrados. Em uma aplicação com uma configuração de DI extensa e hierárquica, esta ordem pode ser muito difícil de prever.

# Testando requisições

Como para qualquer dependência externa, você deve fazer mock do backend HTTP para que seus testes possam simular interação com um servidor remoto. A biblioteca `@angular/common/http/testing` fornece ferramentas para capturar requisições feitas pela aplicação, fazer assertions sobre elas, e fazer mock das respostas para emular o comportamento do seu backend.

A biblioteca de teste é projetada para um padrão no qual a aplicação executa código e faz requisições primeiro. O teste então espera que certas requisições tenham ou não sido feitas, executa assertions contra essas requisições, e finalmente fornece respostas "liberando" (flushing) cada requisição esperada.

No final, os testes podem verificar que a aplicação não fez requisições inesperadas.

## Configuração para teste

Para começar a testar o uso do `HttpClient`, configure o `TestBed` e inclua `provideHttpClient()` e `provideHttpClientTesting()` na configuração do seu teste. Isso configura o `HttpClient` para usar um backend de teste ao invés da rede real. Também fornece o `HttpTestingController`, que você usará para interagir com o backend de teste, definir expectativas sobre quais requisições foram feitas, e liberar respostas para essas requisições. O `HttpTestingController` pode ser injetado do `TestBed` uma vez configurado.

IMPORTANT: Lembre-se de fornecer `provideHttpClient()` **antes** de `provideHttpClientTesting()`, pois `provideHttpClientTesting()` sobrescreverá partes de `provideHttpClient()`. Fazer o contrário pode potencialmente quebrar seus testes.

```ts
TestBed.configureTestingModule({
  providers: [
    // ... other test providers
    provideHttpClient(),
    provideHttpClientTesting(),
  ],
});

const httpTesting = TestBed.inject(HttpTestingController);
```

Agora quando seus testes fazem requisições, elas atingirão o backend de teste ao invés do normal. Você pode usar `httpTesting` para fazer assertions sobre essas requisições.

## Esperando e respondendo requisições

Por exemplo, você pode escrever um teste que espera que uma requisição GET ocorra e forneça uma resposta mock:

```ts
TestBed.configureTestingModule({
  providers: [
    ConfigService,
    provideHttpClient(),
    provideHttpClientTesting(),
  ],
});

const httpTesting = TestBed.inject(HttpTestingController);

// Load `ConfigService` and request the current configuration.
const service = TestBed.inject(ConfigService);
const config$ = service.getConfig<Config>();

// `firstValueFrom` subscribes to the `Observable`, which makes the HTTP request,
// and creates a `Promise` of the response.
const configPromise = firstValueFrom(config$);

// At this point, the request is pending, and we can assert it was made
// via the `HttpTestingController`:
const req = httpTesting.expectOne('/api/config', 'Request to load the configuration');

// We can assert various properties of the request if desired.
expect(req.request.method).toBe('GET');

// Flushing the request causes it to complete, delivering the result.
req.flush(DEFAULT_CONFIG);

// We can then assert that the response was successfully delivered by the `ConfigService`:
expect(await configPromise).toEqual(DEFAULT_CONFIG);

// Finally, we can assert that no other requests were made.
httpTesting.verify();
```

NOTE: `expectOne` falhará se o teste tiver feito mais de uma requisição que corresponde aos critérios fornecidos.

Como alternativa para fazer assertion em `req.method`, você pode usar uma forma expandida de `expectOne` para também corresponder ao método da requisição:

```ts
const req = httpTesting.expectOne({
  method: 'GET',
  url: '/api/config',
}, 'Request to load the configuration');
```

HELPFUL: As APIs de expectativa correspondem à URL completa das requisições, incluindo quaisquer parâmetros de query.

O último passo, verificar que nenhuma requisição permanece pendente, é comum o suficiente para você movê-lo para um passo `afterEach()`:

```ts
afterEach(() => {
  // Verify that none of the tests make any extra HTTP requests.
  TestBed.inject(HttpTestingController).verify();
});
```

## Lidando com mais de uma requisição por vez

Se você precisa responder a requisições duplicadas em seu teste, use a API `match()` ao invés de `expectOne()`. Ela aceita os mesmos argumentos mas retorna um array de requisições correspondentes. Uma vez retornadas, essas requisições são removidas das correspondências futuras e você é responsável por liberar e verificá-las.

```ts
const allGetRequests = httpTesting.match({method: 'GET'});
for (const req of allGetRequests) {
  // Handle responding to each request.
}
```

## Correspondência avançada

Todas as funções de correspondência aceitam uma função predicado para lógica de correspondência customizada:

```ts
// Look for one request that has a request body.
const requestsWithBody = httpTesting.expectOne(req => req.body !== null);
```

A função `expectNone` faz assertion de que nenhuma requisição corresponde aos critérios fornecidos.

```ts
// Assert that no mutation requests have been issued.
httpTesting.expectNone(req => req.method !== 'GET');
```

## Testando tratamento de erros

Você deve testar as respostas da sua aplicação quando requisições HTTP falham.

### Erros de backend

Para testar o tratamento de erros de backend (quando o servidor retorna um código de status sem sucesso), libere requisições com uma resposta de erro que emula o que seu backend retornaria quando uma requisição falha.

```ts
const req = httpTesting.expectOne('/api/config');
req.flush('Failed!', {status: 500, statusText: 'Internal Server Error'});

// Assert that the application successfully handled the backend error.
```

### Erros de rede

Requisições também podem falhar devido a erros de rede, que aparecem como erros `ProgressEvent`. Estes podem ser entregues com o método `error()`:

```ts
const req = httpTesting.expectOne('/api/config');
req.error(new ProgressEvent('network error!'));

// Assert that the application successfully handled the network error.
```

## Testando um Interceptor

Você deve testar que seus interceptors funcionam nas circunstâncias desejadas.

Por exemplo, uma aplicação pode ser obrigada a adicionar um token de autenticação gerado por um service a cada requisição de saída.
Este comportamento pode ser imposto com o uso de um interceptor:

```ts
export function authInterceptor(request: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  const authService = inject(AuthService);

const clonedRequest = request.clone({
    headers: request.headers.append('X-Authentication-Token', authService.getAuthToken()),
  });
  return next(clonedRequest);
}
```

A configuração do `TestBed` para este interceptor deve depender do recurso `withInterceptors`.

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    // Testing one interceptor at a time is recommended.
    provideHttpClient(withInterceptors([authInterceptor])),
    provideHttpClientTesting(),
  ],
});
```

O `HttpTestingController` pode recuperar a instância de requisição que pode então ser inspecionada para garantir que a requisição foi modificada.

```ts
const service = TestBed.inject(AuthService);
const req = httpTesting.expectOne('/api/config');

expect(req.request.headers.get('X-Authentication-Token')).toEqual(service.getAuthToken());
```

Um interceptor similar poderia ser implementado com interceptors baseados em classe:

```ts
@Injectable()
export class AuthInterceptor implements HttpInterceptor {
  private authService = inject(AuthService);

intercept(request: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>> {
    const clonedRequest = request.clone({
      headers: request.headers.append('X-Authentication-Token', this.authService.getAuthToken()),
    });
    return next.handle(clonedRequest);
  }
}
```

Para testá-lo, a configuração do `TestBed` deve ser ao invés:

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    provideHttpClient(withInterceptorsFromDi()),
    provideHttpClientTesting(),
    // We rely on the HTTP_INTERCEPTORS token to register the AuthInterceptor as an HttpInterceptor
    { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true },
  ],
});
```

# Reactive forms

Reactive forms fornecem uma abordagem model-driven para lidar com entradas de formulário cujos valores mudam ao longo do tempo.
Este guia mostra como criar e atualizar um form control básico, progredir para o uso de vários controls em um grupo, validar valores de formulário e criar formulários dinâmicos onde você pode adicionar ou remover controls em tempo de execução.

## Visão geral de reactive forms

Reactive forms usam uma abordagem explícita e imutável para gerenciar o estado de um formulário em um determinado momento.
Cada mudança no estado do formulário retorna um novo estado, que mantém a integridade do modelo entre as mudanças.
Reactive forms são construídos em torno de observable streams, onde entradas e valores de formulário são fornecidos como streams de valores de entrada, que podem ser acessados de forma síncrona.

Reactive forms também fornecem um caminho direto para testes porque você tem a garantia de que seus dados são consistentes e previsíveis quando solicitados.
Quaisquer consumidores dos streams têm acesso para manipular esses dados com segurança.

Reactive forms diferem de [template-driven forms](guide/forms/template-driven-forms) de maneiras distintas.
Reactive forms fornecem acesso síncrono ao data model, imutabilidade com operadores observable e rastreamento de mudanças através de observable streams.

Template-driven forms permitem acesso direto para modificar dados no seu template, mas são menos explícitos do que reactive forms porque dependem de directives incorporadas no template, juntamente com dados mutáveis para rastrear mudanças de forma assíncrona.
Consulte a [Visão Geral de Forms](guide/forms) para comparações detalhadas entre os dois paradigmas.

## Adicionando um form control básico

Existem três etapas para usar form controls.

1. Gere um novo component e registre o módulo de reactive forms. Este módulo declara as directives de reactive-form que você precisa para usar reactive forms.
1. Instancie um novo `FormControl`.
1. Registre o `FormControl` no template.

Você pode então exibir o formulário adicionando o component ao template.

Os exemplos a seguir mostram como adicionar um único form control.
No exemplo, o usuário insere seu nome em um campo de entrada, captura esse valor de entrada e exibe o valor atual do elemento form control.

<docs-workflow>

<docs-step title="Gere um novo component e importe o ReactiveFormsModule">
Use o comando CLI `ng generate component` para gerar um component no seu projeto e importe `ReactiveFormsModule` do pacote `@angular/forms` e adicione-o ao array `imports` do seu Component.

```
</docs-step>

<docs-step title="Declare uma instância FormControl">
Use o construtor de `FormControl` para definir seu valor inicial, que neste caso é uma string vazia. Ao criar esses controls na classe do seu component, você obtém acesso imediato para ouvir, atualizar e validar o estado da entrada de formulário.

<docs-code header="name-editor.component.ts" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" visibleRegion="create-control"/>
</docs-step>

<docs-step title="Registre o control no template">
Depois de criar o control na classe do component, você deve associá-lo a um elemento form control no template. Atualize o template com o form control usando o binding `formControl` fornecido por `FormControlDirective`, que também está incluído no `ReactiveFormsModule`.

<docs-code header="name-editor.component.html" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" visibleRegion="control-binding" />

Usando a sintaxe de template binding, o form control agora está registrado no elemento de entrada `name` no template. O form control e o elemento DOM se comunicam entre si: a view reflete mudanças no model e o model reflete mudanças na view.
</docs-step>

<docs-step title="Exiba o component">
O `FormControl` atribuído à propriedade `name` é exibido quando o component `<app-name-editor>` é adicionado a um template.

<docs-code header="src/app/app.component.html (name editor)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" visibleRegion="app-name-editor"/>
</docs-step>
</docs-workflow>

### Exibindo o valor de um form control

Você pode exibir o valor das seguintes maneiras.

- Através do observable `valueChanges`, onde você pode ouvir mudanças no valor do formulário no template usando `AsyncPipe` ou na classe do component usando o método `subscribe()`
- Com a propriedade `value`, que fornece um snapshot do valor atual

O exemplo a seguir mostra como exibir o valor atual usando interpolação no template.

<docs-code header="name-editor.component.html (control value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" visibleRegion="display-value"/>

O valor exibido muda conforme você atualiza o elemento form control.

Reactive forms fornecem acesso a informações sobre um determinado control através de propriedades e métodos fornecidos com cada instância.
Essas propriedades e métodos da classe subjacente [AbstractControl](api/forms/AbstractControl 'API reference') são usados para controlar o estado do formulário e determinar quando exibir mensagens ao lidar com [validação de entrada](#validating-form-input).

Leia sobre outras propriedades e métodos de `FormControl` na [Referência da API](api/forms/FormControl 'Detailed syntax reference').

### Substituindo o valor de um form control

Reactive forms têm métodos para alterar o valor de um control programaticamente, o que oferece a flexibilidade de atualizar o valor sem interação do usuário.
Uma instância de form control fornece um método `setValue()` que atualiza o valor do form control e valida a estrutura do valor fornecido em relação à estrutura do control.
Por exemplo, ao recuperar dados de formulário de uma API ou serviço de backend, use o método `setValue()` para atualizar o control com seu novo valor, substituindo o valor antigo inteiramente.

O exemplo a seguir adiciona um método à classe do component para atualizar o valor do control para _Nancy_ usando o método `setValue()`.

<docs-code header="name-editor.component.ts (update value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" visibleRegion="update-value"/>

Atualize o template com um botão para simular uma atualização de nome.
Quando você clica no botão **Update Name**, o valor inserido no elemento form control é refletido como seu valor atual.

<docs-code header="name-editor.component.html (update value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" visibleRegion="update-value"/>

O form model é a fonte da verdade para o control, então quando você clica no botão, o valor da entrada é alterado dentro da classe do component, sobrescrevendo seu valor atual.

HELPFUL: Neste exemplo, você está usando um único control.
Ao usar o método `setValue()` com um form group ou form array, o valor precisa corresponder à estrutura do grupo ou array.

## Agrupando form controls

Os formulários normalmente contêm vários controls relacionados.
Reactive forms fornecem duas maneiras de agrupar vários controls relacionados em um único formulário de entrada.

| Form groups | Detalhes                                                                                                                                                                                                                                                                    |
| :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Form group  | Define um formulário com um conjunto fixo de controls que você pode gerenciar juntos. Os fundamentos do form group são discutidos nesta seção. Você também pode [aninhar form groups](#creating-nested-form-groups) para criar formulários mais complexos.                  |
| Form array  | Define um formulário dinâmico, onde você pode adicionar e remover controls em tempo de execução. Você também pode aninhar form arrays para criar formulários mais complexos. Para mais sobre esta opção, consulte [Criando formulários dinâmicos](#creating-dynamic-forms). |

Assim como uma instância de form control oferece controle sobre um único campo de entrada, uma instância de form group rastreia o estado do formulário de um grupo de instâncias de form control $por exemplo, um formulário$.
Cada control em uma instância de form group é rastreado por nome ao criar o form group.
O exemplo a seguir mostra como gerenciar várias instâncias de form control em um único grupo.

Gere um component `ProfileEditor` e importe as classes `FormGroup` e `FormControl` do pacote `@angular/forms`.

<docs-code language="shell">
ng generate component ProfileEditor
```
<docs-code header="profile-editor.component.ts (imports)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="imports"/>

Para adicionar um form group a este component, siga as seguintes etapas.

1. Crie uma instância `FormGroup`.
1. Associe o model `FormGroup` e a view.
1. Salve os dados do formulário.

<docs-workflow>

<docs-step title="Crie uma instância FormGroup">
Crie uma propriedade na classe do component chamada `profileForm` e defina a propriedade como uma nova instância de form group. Para inicializar o form group, forneça ao construtor um objeto de chaves nomeadas mapeadas para seus controls.

Para o formulário de perfil, adicione duas instâncias de form control com os nomes `firstName` e `lastName`

<docs-code header="profile-editor.component.ts (form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="formgroup"/>

Os form controls individuais agora estão coletados dentro de um grupo. Uma instância `FormGroup` fornece seu valor de modelo como um objeto reduzido dos valores de cada control no grupo. Uma instância de form group tem as mesmas propriedades (como `value` e `untouched`) e métodos (como `setValue()`) que uma instância de form control.
</docs-step>

<docs-step title="Associe o model FormGroup e a view">
Um form group rastreia o status e as mudanças de cada um de seus controls, portanto, se um dos controls mudar, o control pai também emite um novo status ou mudança de valor. O model para o grupo é mantido a partir de seus membros. Depois de definir o model, você deve atualizar o template para refletir o model na view.

<docs-code header="profile-editor.component.html (template form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" visibleRegion="formgroup"/>

Assim como um form group contém um grupo de controls, o `FormGroup` _profileForm_ é vinculado ao elemento `form` com a directive `FormGroup`, criando uma camada de comunicação entre o model e o formulário contendo as entradas. A entrada `formControlName` fornecida pela directive `FormControlName` vincula cada entrada individual ao form control definido no `FormGroup`. Os form controls se comunicam com seus respectivos elementos. Eles também comunicam mudanças à instância do form group, que fornece a fonte da verdade para o valor do modelo.
</docs-step>

<docs-step title="Salve os dados do formulário">
O component `ProfileEditor` aceita entrada do usuário, mas em um cenário real você deseja capturar o valor do formulário e disponibilizá-lo para processamento adicional fora do component. A directive `FormGroup` escuta o evento `submit` emitido pelo elemento `form` e emite um evento `ngSubmit` ao qual você pode vincular uma função de callback. Adicione um event listener `ngSubmit` à tag `form` com o método de callback `onSubmit()`.

<docs-code header="profile-editor.component.html (submit event)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="ng-submit"/>

O método `onSubmit()` no component `ProfileEditor` captura o valor atual de `profileForm`. Use `EventEmitter` para manter o formulário encapsulado e fornecer o valor do formulário fora do component. O exemplo a seguir usa `console.warn` para registrar uma mensagem no console do navegador.

<docs-code header="profile-editor.component.ts (submit method)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="on-submit"/>

O evento `submit` é emitido pela tag `form` usando o evento DOM nativo. Você aciona o evento clicando em um botão com tipo `submit`. Isso permite que o usuário pressione a tecla **Enter** para enviar o formulário concluído.

Use um elemento `button` para adicionar um botão na parte inferior do formulário para acionar o envio do formulário.

<docs-code header="profile-editor.component.html (submit button)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="submit-button"/>

O botão no trecho anterior também tem um binding `disabled` anexado a ele para desabilitar o botão quando `profileForm` for inválido. Você ainda não está executando nenhuma validação, então o botão está sempre ativado. A validação básica de formulário é abordada na seção [Validando entrada de formulário](#validating-form-input).
</docs-step>

<docs-step title="Exiba o component">
Para exibir o component `ProfileEditor` que contém o formulário, adicione-o a um template de component.

<docs-code header="app.component.html (profile editor)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" visibleRegion="app-profile-editor"/>

`ProfileEditor` permite que você gerencie as instâncias de form control para os controls `firstName` e `lastName` dentro da instância do form group.

### Criando form groups aninhados {#creating-nested-form-groups}

Form groups podem aceitar tanto instâncias individuais de form control quanto outras instâncias de form group como filhos.
Isso torna a composição de modelos de formulário complexos mais fácil de manter e agrupar logicamente.

Ao construir formulários complexos, gerenciar as diferentes áreas de informação é mais fácil em seções menores.
Usar uma instância de form group aninhado permite que você divida form groups grandes em grupos menores e mais gerenciáveis.

Para criar formulários mais complexos, use as seguintes etapas.

1. Crie um grupo aninhado.
1. Agrupe o formulário aninhado no template.

Alguns tipos de informação naturalmente se enquadram no mesmo grupo.
Um nome e endereço são exemplos típicos de tais grupos aninhados e são usados nos exemplos a seguir.

<docs-workflow>
<docs-step title="Crie um grupo aninhado {#grouping-form-controls}">
Para criar um grupo aninhado em `profileForm`, adicione um elemento `address` aninhado à instância do form group.

<docs-code header="profile-editor.component.ts (nested form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="nested-formgroup"/>

Neste exemplo, `address group` combina os controls atuais `firstName` e `lastName` com os novos controls `street`, `city`, `state` e `zip`. Embora o elemento `address` no form group seja um filho do elemento `profileForm` geral no form group, as mesmas regras se aplicam com mudanças de valor e status. As mudanças no status e valor do form group aninhado se propagam para o form group pai, mantendo a consistência com o modelo geral.
</docs-step>

<docs-step title="Agrupe o formulário aninhado no template">
Depois de atualizar o model na classe do component, atualize o template para conectar a instância do form group e seus elementos de entrada. Adicione o form group `address` contendo os campos `street`, `city`, `state` e `zip` ao template `ProfileEditor`.

<docs-code header="profile-editor.component.html (template nested form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" visibleRegion="formgroupname"/>

O formulário `ProfileEditor` é exibido como um grupo, mas o modelo é dividido ainda mais para representar as áreas de agrupamento lógico.

Exiba o valor da instância do form group no template do component usando a propriedade `value` e `JsonPipe`.
</docs-step>
</docs-workflow>

### Atualizando partes do data model

Ao atualizar o valor de uma instância de form group que contém vários controls, você pode querer atualizar apenas partes do modelo.
Esta seção cobre como atualizar partes específicas de um data model de form control.

Existem duas maneiras de atualizar o valor do modelo:

| Métodos        | Detalhes                                                                                                                                                 |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setValue()`   | Define um novo valor para um control individual. O método `setValue()` adere estritamente à estrutura do form group e substitui todo o valor do control. |
| `patchValue()` | Substitui quaisquer propriedades definidas no objeto que foram alteradas no form model.                                                                  |

As verificações estritas do método `setValue()` ajudam a capturar erros de aninhamento em formulários complexos, enquanto `patchValue()` falha silenciosamente nesses erros.

Em `ProfileEditorComponent`, use o método `updateProfile` com o exemplo a seguir para atualizar o primeiro nome e endereço de rua do usuário.

<docs-code header="profile-editor.component.ts (patch value)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="patch-value"/>

Simule uma atualização adicionando um botão ao template para atualizar o perfil do usuário sob demanda.

<docs-code header="profile-editor.component.html (update value)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" visibleRegion="patch-value"/>

Quando um usuário clica no botão, o model `profileForm` é atualizado com novos valores para `firstName` e `street`. Observe que `street` é fornecido em um objeto dentro da propriedade `address`.
Isso é necessário porque o método `patchValue()` aplica a atualização contra a estrutura do modelo.
`PatchValue()` atualiza apenas as propriedades que o form model define.

## Usando o serviço FormBuilder para gerar controls

Criar instâncias de form control manualmente pode se tornar repetitivo ao lidar com vários formulários.
O serviço `FormBuilder` fornece métodos convenientes para gerar controls.

Use as seguintes etapas para aproveitar este serviço.

1. Importe a classe `FormBuilder`.
1. Injete o serviço `FormBuilder`.
1. Gere o conteúdo do formulário.

Os exemplos a seguir mostram como refatorar o component `ProfileEditor` para usar o serviço form builder para criar instâncias de form control e form group.

<docs-workflow>
<docs-step title="Importe a classe FormBuilder">
Importe a classe `FormBuilder` do pacote `@angular/forms`.

<docs-code header="profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="form-builder-imports"/>

</docs-step>

<docs-step title="Injete o serviço FormBuilder">
O serviço `FormBuilder` é um provider injetável do módulo de reactive forms. Use a função `inject()` para injetar essa dependência no seu component.

<docs-code header="profile-editor.component.ts (property init)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="inject-form-builder"/>

</docs-step>
<docs-step title="Gere form controls">
O serviço `FormBuilder` tem três métodos: `control()`, `group()` e `array()`. Estes são métodos de fábrica para gerar instâncias nas classes de seus components, incluindo form controls, form groups e form arrays. Use o método `group` para criar os controls `profileForm`.

<docs-code header="profile-editor.component.ts (form builder)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="form-builder"/>

No exemplo anterior, você usa o método `group()` com o mesmo objeto para definir as propriedades no model. O valor para cada nome de control é um array contendo o valor inicial como o primeiro item no array.

TIP: Você pode definir o control apenas com o valor inicial, mas se seus controls precisarem de validação síncrona ou assíncrona, adicione validadores síncronos e assíncronos como segundo e terceiro itens no array. Compare o uso do form builder com a criação manual das instâncias.
</docs-step>

</docs-workflow>

## Validando entrada de formulário {#validating-form-input}

_Validação de formulário_ é usada para garantir que a entrada do usuário esteja completa e correta.
Esta seção cobre adicionar um único validador a um form control e exibir o status geral do formulário.
A validação de formulário é abordada mais extensivamente no guia [Validação de Formulário](guide/forms/form-validation).

Use as seguintes etapas para adicionar validação de formulário.

1. Importe uma função validadora no seu component de formulário.
1. Adicione o validador ao campo no formulário.
1. Adicione lógica para lidar com o status de validação.

A validação mais comum é tornar um campo obrigatório.
O exemplo a seguir mostra como adicionar uma validação obrigatória ao control `firstName` e exibir o resultado da validação.

<docs-workflow>
<docs-step title="Importe uma função validadora">
Reactive forms incluem um conjunto de funções validadoras para casos de uso comuns. Essas funções recebem um control para validar e retornam um objeto de erro ou um valor nulo com base na verificação de validação.

Importe a classe `Validators` do pacote `@angular/forms`.

<docs-code header="profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="validator-imports"/>
</docs-step>

<docs-step title="Torne um campo obrigatório">
No component `ProfileEditor`, adicione o método estático `Validators.required` como o segundo item no array para o control `firstName`.

<docs-code header="profile-editor.component.ts (required validator)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="required-validator"/>
</docs-step>

<docs-step title="Exiba o status do formulário">
Quando você adiciona um campo obrigatório ao form control, seu status inicial é inválido. Este status inválido se propaga para o elemento form group pai, tornando seu status inválido. Acesse o status atual da instância do form group através de sua propriedade `status`.

Exiba o status atual de `profileForm` usando interpolação.

<docs-code header="profile-editor.component.html (display status)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="display-status"/>

O botão **Submit** está desabilitado porque `profileForm` é inválido devido ao control de formulário `firstName` obrigatório. Depois de preencher a entrada `firstName`, o formulário se torna válido e o botão **Submit** é habilitado.

Para mais sobre validação de formulário, visite o guia [Validação de Formulário](guide/forms/form-validation).
</docs-step>
</docs-workflow>

## Criando formulários dinâmicos {#creating-dynamic-forms}

`FormArray` é uma alternativa a `FormGroup` para gerenciar qualquer número de controls sem nome.
Assim como nas instâncias de form group, você pode inserir e remover dinamicamente controls de instâncias de form array, e o valor da instância de form array e o status de validação são calculados a partir de seus controls filhos.
No entanto, você não precisa definir uma chave para cada control por nome, então esta é uma ótima opção se você não sabe o número de valores filhos antecipadamente.

Para definir um formulário dinâmico, siga as seguintes etapas.

1. Importe a classe `FormArray`.
1. Defina um control `FormArray`.
1. Acesse o control `FormArray` com um método getter.
1. Exiba o form array em um template.

O exemplo a seguir mostra como gerenciar um array de _aliases_ em `ProfileEditor`.

<docs-workflow>
<docs-step title="Importe a classe `FormArray`">
Importe a classe `FormArray` de `@angular/forms` para usar para informações de tipo. O serviço `FormBuilder` está pronto para criar uma instância `FormArray`.

<docs-code header="profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="form-array-imports"/>
</docs-step>

<docs-step title="Defina um control `FormArray`">
Você pode inicializar um form array com qualquer número de controls, de zero a muitos, definindo-os em um array. Adicione uma propriedade `aliases` à instância do form group para `profileForm` para definir o form array.

Use o método `FormBuilder.array()` para definir o array e o método `FormBuilder.control()` para preencher o array com um control inicial.

<docs-code header="profile-editor.component.ts (aliases form array)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="aliases"/>

O control aliases na instância do form group agora está preenchido com um único control até que mais controls sejam adicionados dinamicamente.
</docs-step>

<docs-step title="Acesse o control `FormArray`">
Um getter fornece acesso aos aliases na instância do form array em comparação com repetir o método `profileForm.get()` para obter cada instância. A instância do form array representa um número indefinido de controls em um array. É conveniente acessar um control através de um getter, e esta abordagem é direta de repetir para controls adicionais. <br />

Use a sintaxe getter para criar uma propriedade de classe `aliases` para recuperar o control de form array de aliases do form group pai.

<docs-code header="profile-editor.component.ts (aliases getter)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="aliases-getter"/>

Como o control retornado é do tipo `AbstractControl`, você precisa fornecer um tipo explícito para acessar a sintaxe do método para a instância do form array. Defina um método para inserir dinamicamente um control de alias no form array de aliases. O método `FormArray.push()` insere o control como um novo item no array, e você também pode passar um array de controls para FormArray.push() para registrar vários controls de uma vez.

<docs-code header="profile-editor.component.ts (add alias)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="add-alias"/>

No template, cada control é exibido como um campo de entrada separado.

</docs-step>

<docs-step title="Exiba o form array no template">

Para anexar os aliases do seu form model, você deve adicioná-lo ao template. Semelhante à entrada `formGroupName` fornecida por `FormGroupNameDirective`, `formArrayName` vincula a comunicação da instância do form array ao template com `FormArrayNameDirective`.

Adicione o seguinte HTML de template após a `<div>` que fecha o elemento `formGroupName`.

<docs-code header="profile-editor.component.html (aliases form array template)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="formarrayname"/>

O bloco `@for` itera sobre cada instância de form control fornecida pela instância do form array de aliases. Como os elementos do form array não têm nome, você atribui o índice à variável `i` e o passa para cada control para vinculá-lo à entrada `formControlName`.

Cada vez que uma nova instância de alias é adicionada, a nova instância do form array é fornecida com seu control com base no índice. Isso permite que você rastreie cada control individual ao calcular o status e o valor do control raiz.

</docs-step>

<docs-step title="Adicione um alias">

Inicialmente, o formulário contém um campo `Alias`. Para adicionar outro campo, clique no botão **Add Alias**. Você também pode validar o array de aliases relatado pelo form model exibido por `Form Value` na parte inferior do template. Em vez de uma instância de form control para cada alias, você pode compor outra instância de form group com campos adicionais. O processo de definir um control para cada item é o mesmo.
</docs-step>

</docs-workflow>

## Eventos unificados de mudança de estado de control

Todos os form controls expõem um único stream unificado de **eventos de mudança de estado de control** através do observable `events` em `AbstractControl` (`FormControl`, `FormGroup`, `FormArray` e `FormRecord`).
Este stream unificado permite que você reaja a mudanças de estado de **value**, **status**, **pristine**, **touched** e **reset** e também para **ações no nível de formulário**, como **submit**, permitindo que você lide com todas as atualizações com uma única assinatura em vez de conectar vários observables.

### Tipos de evento

Cada item emitido por `events` é uma instância de uma classe de evento específica:

- **`ValueChangeEvent`** — quando o **value** do control muda.
- **`StatusChangeEvent`** — quando o **status de validação** do control atualiza para um dos valores `FormControlStatus` (`VALID`, `INVALID`, `PENDING` ou `DISABLED`).
- **`PristineChangeEvent`** — quando o estado **pristine/dirty** do control muda.
- **`TouchedChangeEvent`** — quando o estado **touched/untouched** do control muda.
- **`FormResetEvent`** — quando um control ou formulário é resetado, seja através da API `reset()` ou de uma ação nativa.
- **`FormSubmittedEvent`** — quando o formulário é enviado.

Todas as classes de evento estendem `ControlEvent` e incluem uma referência `source` ao `AbstractControl` que originou a mudança, o que é útil em formulários grandes.

```ts
import { Component } from '@angular/core';
import {
  FormControl,
  ValueChangeEvent,
  StatusChangeEvent,
  PristineChangeEvent,
  TouchedChangeEvent,
  FormResetEvent,
  FormSubmittedEvent,
  ReactiveFormsModule,
  FormGroup,
} from '@angular/forms';

@Component({/* ... */ })
export class UnifiedEventsBasicComponent {
  form = new FormGroup({
    username: new FormControl(''),
  });

constructor() {
    this.form.events.subscribe((e) => {
      if (e instanceof ValueChangeEvent) {
        console.log('Value changed to: ', e.value);
      }

if (e instanceof StatusChangeEvent) {
        console.log('Status changed to: ', e.status);
      }

if (e instanceof PristineChangeEvent) {
        console.log('Pristine status changed to: ', e.pristine);
      }

if (e instanceof TouchedChangeEvent) {
        console.log('Touched status changed to: ', e.touched);
      }

if (e instanceof FormResetEvent) {
        console.log('Form was reset');
      }

if (e instanceof FormSubmittedEvent) {
        console.log('Form was submitted');
      }
    });
  }
}
```

### Filtrando eventos específicos

Prefira operadores RxJS quando você precisar apenas de um subconjunto de tipos de evento.

```ts
import { filter } from 'rxjs/operators';
import { StatusChangeEvent } from '@angular/forms';

control.events
  .pipe(filter((e) => e instanceof StatusChangeEvent))
  .subscribe((e) => console.log('Status:', e.status));
```

### Unificando de múltiplas assinaturas

**Antes**

```ts
import { combineLatest } from 'rxjs/operators';

combineLatest([control.valueChanges, control.statusChanges])
  .subscribe(([value, status]) => { /* ... */ });
```

**Depois**

```ts
control.events.subscribe((e) => {
  // Handle ValueChangeEvent, StatusChangeEvent, etc.
});
```

NOTE: Na mudança de valor, a emissão acontece logo após um valor deste control ser atualizado. O valor de um control pai (por exemplo, se este FormControl faz parte de um FormGroup) é atualizado mais tarde, portanto, acessar um valor de um control pai (usando a propriedade `value`) do callback deste evento pode resultar em obter um valor que ainda não foi atualizado. Assine os `events` do control pai em vez disso.

## Funções utilitárias para restringir tipos de form control {#creating-nested-form-groups 'See more about nesting groups'} {#validating-form-input 'Learn more about validating form input'}

O Angular fornece quatro funções utilitárias que ajudam a determinar o tipo concreto de um `AbstractControl`. Essas funções atuam como **type guards** e restringem o tipo de control quando retornam `true`, o que permite que você acesse com segurança propriedades específicas do subtipo dentro do mesmo bloco.

Esses helpers são particularmente úteis em **validadores personalizados**, onde a assinatura da função recebe um `AbstractControl`, mas a lógica é destinada a um tipo específico de control.

```ts
import { AbstractControl, isFormArray } from '@angular/forms';

export function positiveValues(control: AbstractControl) {
    if (!isFormArray(control)) {
        return null; // Not a FormArray: validator is not applicable.
    }

// Safe to access FormArray-specific API after narrowing.
    const hasNegative = control.controls.some(c => c.value < 0);
    return hasNegative ? { positiveValues: true } : null;
}
```

## Resumo da API de reactive forms

A tabela a seguir lista as classes base e serviços usados para criar e gerenciar reactive form controls.
Para detalhes de sintaxe completos, consulte a documentação de referência da API para o [pacote Forms](api#forms 'API reference').

### Classes

| Classe            | Detalhes                                                                                                                                                                                                    |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AbstractControl` | A classe base abstrata para as classes concretas de form control `FormControl`, `FormGroup` e `FormArray`. Ela fornece seus comportamentos e propriedades comuns.                                           |
| `FormControl`     | Gerencia o valor e o status de validação de um form control individual. Ele corresponde a um form control HTML, como `<input>` ou `<select>`.                                                               |
| `FormGroup`       | Gerencia o valor e o estado de validação de um grupo de instâncias `AbstractControl`. As propriedades do grupo incluem seus controls filhos. O formulário de nível superior no seu component é `FormGroup`. |
| `FormArray`       | Gerencia o valor e o estado de validação de um array numericamente indexado de instâncias `AbstractControl`.                                                                                                |
| `FormBuilder`     | Um serviço injetável que fornece métodos de fábrica para criar instâncias de control.                                                                                                                       |
| `FormRecord`      | Rastreia o valor e o estado de validação de uma coleção de instâncias `FormControl`, cada uma das quais tem o mesmo tipo de valor.                                                                          |

### Directives

| Directive              | Detalhes                                                                                             |
| :--------------------- | :--------------------------------------------------------------------------------------------------- |
| `FormControlDirective` | Sincroniza uma instância `FormControl` autônoma a um elemento form control.                          |
| `FormControlName`      | Sincroniza `FormControl` em uma instância `FormGroup` existente a um elemento form control por nome. |
| `FormGroupDirective`   | Sincroniza uma instância `FormGroup` existente a um elemento DOM.                                    |
| `FormGroupName`        | Sincroniza uma instância `FormGroup` aninhada a um elemento DOM.                                     |
| `FormArrayName`        | Sincroniza uma instância `FormArray` aninhada a um elemento DOM.                                     |

# Typed Forms

A partir do Angular 14, reactive forms são estritamente tipados por padrão.

Como base para este guia, você já deve estar familiarizado com [Angular Reactive Forms](guide/forms/reactive-forms).

## Visão geral de Typed Forms

<docs-video src="https://www.youtube.com/embed/L-odCf4MfJc" alt="Typed Forms in Angular" />

Com reactive forms do Angular, você especifica explicitamente um _form model_. Como um exemplo simples, considere este formulário básico de login de usuário:

```ts
const login = new FormGroup({
  email: new FormControl(''),
  password: new FormControl(''),
});
```

O Angular fornece muitas APIs para interagir com este `FormGroup`. Por exemplo, você pode chamar `login.value`, `login.controls`, `login.patchValue`, etc. (Para uma referência completa da API, veja a [documentação da API](api/forms/FormGroup).)

Em versões anteriores do Angular, a maioria dessas APIs incluía `any` em algum lugar de seus tipos, e interagir com a estrutura dos controls, ou os valores em si, não era type-safe. Por exemplo: você poderia escrever o seguinte código inválido:

```ts
const emailDomain = login.value.email.domain;
```

Com reactive forms estritamente tipados, o código acima não compila, porque não há propriedade `domain` em `email`.

Além da segurança adicionada, os tipos habilitam uma variedade de outras melhorias, como melhor autocomplete em IDEs, e uma forma explícita de especificar a estrutura do formulário.

Essas melhorias atualmente aplicam-se apenas a _reactive_ forms (não [_template-driven_ forms](guide/forms/template-driven-forms)).

## Untyped Forms

Formulários não tipados ainda são suportados, e continuarão a funcionar como antes. Para usá-los, você deve importar os símbolos `Untyped` de `@angular/forms`:

```ts
const login = new UntypedFormGroup({
  email: new UntypedFormControl(''),
  password: new UntypedFormControl(''),
});
```

Cada símbolo `Untyped` tem exatamente a mesma semântica que nas versões anteriores do Angular. Ao remover os prefixos `Untyped`, você pode habilitar os tipos incrementalmente.

## `FormControl`: Começando

O formulário mais simples possível consiste de um único control:

```ts
const email = new FormControl('angularrox@gmail.com');
```

Este control será automaticamente inferido para ter o tipo `FormControl<string|null>`. O TypeScript automaticamente aplicará este tipo em toda a [API do `FormControl`](api/forms/FormControl), como `email.value`, `email.valueChanges`, `email.setValue(...)`, etc.

### Nullability

Você pode se perguntar: por que o tipo deste control inclui `null`? Isso é porque o control pode se tornar `null` a qualquer momento, ao chamar reset:

```ts
const email = new FormControl('angularrox@gmail.com');
email.reset();
console.log(email.value); // null
```

O TypeScript aplicará que você sempre lide com a possibilidade de que o control tenha se tornado `null`. Se você quiser tornar este control não-anulável, você pode usar a opção `nonNullable`. Isso fará com que o control seja resetado para seu valor inicial, ao invés de `null`:

```ts
const email = new FormControl('angularrox@gmail.com', {nonNullable: true});
email.reset();
console.log(email.value); // angularrox@gmail.com
```

Para reiterar, esta opção afeta o comportamento em tempo de execução do seu formulário quando `.reset()` é chamado, e deve ser alterada com cuidado.

### Especificando um tipo explícito

É possível especificar o tipo, ao invés de confiar na inferência. Considere um control que é inicializado como `null`. Como o valor inicial é `null`, o TypeScript inferirá `FormControl<null>`, que é mais restrito do que queremos.

```ts
const email = new FormControl(null);
email.setValue('angularrox@gmail.com'); // Error!
```

Para prevenir isso, especificamos explicitamente o tipo como `string|null`:

```ts
const email = new FormControl<string|null>(null);
email.setValue('angularrox@gmail.com');
```

## `FormArray`: Coleções dinâmicas e homogêneas

Um `FormArray` contém uma lista aberta de controls. O parâmetro de tipo corresponde ao tipo de cada control interno:

```ts
const names = new FormArray([new FormControl('Alex')]);
names.push(new FormControl('Jess'));
```

Passe um array de controls para `aliases.push()` quando você precisar adicionar várias entradas de uma vez.

```ts
const aliases = new FormArray([new FormControl('ng')]);
aliases.push([new FormControl('ngDev'), new FormControl('ngAwesome')]);
```

Este `FormArray` terá o tipo de controls internos `FormControl<string|null>`.

Se você quiser ter múltiplos tipos de elementos diferentes dentro do array, você deve usar `UntypedFormArray`, porque o TypeScript não pode inferir qual tipo de elemento ocorrerá em qual posição.

Um `FormArray` também fornece um método `clear()` para remover todos os controls que contém:

```ts
const aliases = new FormArray([new FormControl('ngDev'), new FormControl('ngAwesome')]);
aliases.clear();
console.log(aliases.length); // 0
```

## `FormGroup` e `FormRecord`

O Angular fornece o tipo `FormGroup` para formulários com um conjunto enumerado de chaves, e um tipo chamado `FormRecord`, para grupos abertos ou dinâmicos.

### Valores parciais

Considere novamente um formulário de login:

```ts
const login = new FormGroup({
    email: new FormControl('', {nonNullable: true}),
    password: new FormControl('', {nonNullable: true}),
});
```

Em qualquer `FormGroup`, é [possível desabilitar controls](api/forms/FormGroup). Qualquer control desabilitado não aparecerá no valor do grupo.

Como consequência, o tipo de `login.value` é `Partial<{email: string, password: string}>`. O `Partial` neste tipo significa que cada membro pode estar undefined.

Mais especificamente, o tipo de `login.value.email` é `string|undefined`, e o TypeScript aplicará que você lide com o valor possivelmente `undefined` (se você tiver `strictNullChecks` habilitado).

Se você quiser acessar o valor _incluindo_ controls desabilitados, e assim contornar campos possivelmente `undefined`, você pode usar `login.getRawValue()`.

### Optional Controls e grupos dinâmicos

Alguns formulários têm controls que podem ou não estar presentes, que podem ser adicionados e removidos em tempo de execução. Você pode representar esses controls usando _optional fields_:

```ts
interface LoginForm {
  email: FormControl<string>;
  password?: FormControl<string>;
}

const login = new FormGroup<LoginForm>({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});

Neste formulário, especificamos explicitamente o tipo, o que nos permite tornar o control `password` opcional. O TypeScript aplicará que apenas controls opcionais podem ser adicionados ou removidos.

### `FormRecord`

Alguns usos de `FormGroup` não se encaixam no padrão acima porque as chaves não são conhecidas antecipadamente. A classe `FormRecord` é projetada para esse caso:

```ts
const addresses = new FormRecord<FormControl<string|null>>({});
addresses.addControl('Andrew', new FormControl('2340 Folsom St'));
```

Qualquer control do tipo `string|null` pode ser adicionado a este `FormRecord`.

Se você precisar de um `FormGroup` que seja tanto dinâmico (aberto) quanto heterogêneo (os controls são tipos diferentes), nenhuma melhoria de type safety é possível, e você deve usar `UntypedFormGroup`.

Um `FormRecord` também pode ser construído com o `FormBuilder`:

```ts
const addresses = fb.record({'Andrew': '2340 Folsom St'});
```

## `FormBuilder` e `NonNullableFormBuilder`

A classe `FormBuilder` foi atualizada para suportar os novos tipos também, da mesma maneira que os exemplos acima.

Adicionalmente, um builder adicional está disponível: `NonNullableFormBuilder`. Este tipo é uma abreviação para especificar `{nonNullable: true}` em cada control, e pode eliminar boilerplate significativo de grandes formulários não anuláveis. Você pode acessá-lo usando a propriedade `nonNullable` em um `FormBuilder`:

```ts
const fb = new FormBuilder();
const login = fb.nonNullable.group({
  email: '',
  password: '',
});
```

No exemplo acima, ambos os controls internos serão não anuláveis (ou seja, `nonNullable` será definido).

Você também pode injetá-lo usando o nome `NonNullableFormBuilder`.

# Construindo um formulário template-driven

Este tutorial mostra como criar um formulário template-driven. Os elementos de controle no formulário são vinculados a propriedades de dados que possuem validação de entrada. A validação de entrada ajuda a manter a integridade dos dados e o estilo melhora a experiência do usuário.

Formulários template-driven usam [vinculação de dados bidirecional](guide/templates/two-way-binding) para atualizar o modelo de dados no component conforme as alterações são feitas no template e vice-versa.
Angular suporta duas abordagens de design para formulários interativos. Formulários template-driven permitem que você use directives específicas de formulário em seu template Angular. Formulários reactive fornecem uma abordagem orientada a modelo para construção de formulários.

Formulários template-driven são uma ótima escolha para formulários pequenos ou simples, enquanto formulários reactive são mais escaláveis e adequados para formulários complexos. Para uma comparação das duas abordagens, veja [Escolhendo uma abordagem](guide/forms#choosing-an-approach)
Você pode construir praticamente qualquer tipo de formulário com um template Angular — formulários de login, formulários de contato e praticamente qualquer formulário de negócios.
Você pode dispor os controles de forma criativa e vinculá-los aos dados no seu modelo de objeto.
Você pode especificar regras de validação e exibir erros de validação, permitir condicionalmente entrada de controles específicos, acionar feedback visual integrado e muito mais.

## Objetivos

Este tutorial ensina como fazer o seguinte:

- Construir um formulário Angular com um component e template
- Usar `ngModel` para criar vinculações de dados bidirecionais para leitura e escrita de valores de controle de entrada
- Fornecer feedback visual usando classes CSS especiais que rastreiam o estado dos controles
- Exibir erros de validação aos usuários e permitir condicionalmente entrada de controles de formulário com base no status do formulário
- Compartilhar informações entre elementos HTML usando [variáveis de referência de template](guide/templates/variables#template-reference-variables)

## Construir um formulário template-driven

Formulários template-driven dependem de directives definidas no `FormsModule`.

| Directives     | Detalhes                                                                                                                                                                                                                                                                         |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NgModel`      | Reconcilia mudanças de valor no elemento de formulário anexado com mudanças no modelo de dados, permitindo que você responda à entrada do usuário com validação de entrada e tratamento de erros.                                                                                           |
| `NgForm`       | Cria uma instância `FormGroup` de nível superior e a vincula a um elemento `<form>` para rastrear o valor agregado do formulário e o status de validação. Assim que você importa o `FormsModule`, esta directive se torna ativa por padrão em todas as tags `<form>`. Você não precisa adicionar um seletor especial. |
| `NgModelGroup` | Cria e vincula uma instância `FormGroup` a um elemento DOM.                                                                                                                                                                                                                      |

### Visão geral das etapas

No decorrer deste tutorial, você vincula um formulário de exemplo aos dados e lida com a entrada do usuário usando as seguintes etapas.

1. Construir o formulário básico.
   - Definir um modelo de dados de exemplo
   - Incluir a infraestrutura necessária, como o `FormsModule`
1. Vincular controles de formulário a propriedades de dados usando a directive `ngModel` e a sintaxe de vinculação de dados bidirecional.
   - Examinar como `ngModel` relata estados de controle usando classes CSS
   - Nomear controles para torná-los acessíveis ao `ngModel`
1. Rastrear a validade de entrada e o status do controle usando `ngModel`.
   - Adicionar CSS personalizado para fornecer feedback visual sobre o status
   - Mostrar e ocultar mensagens de erro de validação
1. Responder a um evento de clique de botão HTML nativo adicionando aos dados do modelo.
1. Lidar com o envio do formulário usando a propriedade de output [`ngSubmit`](api/forms/NgForm#properties) do formulário.
   - Desabilitar o botão **Submit** até que o formulário seja válido
   - Após o envio, trocar o formulário concluído por conteúdo diferente na página

## Construir o formulário

1. O aplicativo de exemplo fornecido cria a classe `Actor` que define o modelo de dados refletido no formulário.

<docs-code header="actor.ts" language="typescript" path="adev/src/content/examples/forms/src/app/actor.ts"/>

1. O layout e os detalhes do formulário são definidos na classe `ActorFormComponent`.

<docs-code header="actor-form.component.ts (v1)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" visibleRegion="v1"/>

O valor do `selector` do component "app-actor-form" significa que você pode colocar este formulário em um template pai usando a tag `<app-actor-form>`.

2. O código a seguir cria uma nova instância de actor, para que o formulário inicial possa mostrar um actor de exemplo.

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" visibleRegion="Marilyn"/>

Esta demonstração usa dados fictícios para `model` e `skills`.
   Em um aplicativo real, você injetaria um service de dados para obter e salvar dados reais, ou exporia essas propriedades como inputs e outputs.

3. O component habilita o recurso de Forms importando o módulo `FormsModule`.

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" visibleRegion="imports"/>

4. O formulário é exibido no layout do aplicativo definido pelo template do component raiz.

<docs-code header="src/app/app.component.html" language="html" path="adev/src/content/examples/forms/src/app/app.component.html"/>

O template inicial define o layout para um formulário com dois grupos de formulário e um botão de envio.
   Os grupos de formulário correspondem a duas propriedades do modelo de dados Actor, name e studio.
   Cada grupo tem um rótulo e uma caixa para entrada do usuário.
   - O elemento de controle `<input>` de **Name** tem o atributo HTML5 `required`
   - O elemento de controle `<input>` de **Studio** não tem porque `studio` é opcional

O botão **Submit** tem algumas classes nele para estilização.
   Neste ponto, o layout do formulário é todo HTML5 simples, sem vinculações ou directives.

5. O formulário de exemplo usa algumas classes de estilo do [Twitter Bootstrap](https://getbootstrap.com/css): `container`, `form-group`, `form-control` e `btn`.
   Para usar esses estilos, a folha de estilo do aplicativo importa a biblioteca.

<docs-code header="src/styles.css" path="adev/src/content/examples/forms/src/styles.1.css"/>

1. O formulário requer que a habilidade de um actor seja escolhida de uma lista predefinida de `skills` mantida internamente em `ActorFormComponent`.
   O loop `@for` do Angular itera sobre os valores de dados para preencher o elemento `<select>`.

<docs-code header="actor-form.component.html (skills)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="skills"/>

Se você executar o aplicativo agora, verá a lista de habilidades no controle de seleção.
Os elementos de entrada ainda não estão vinculados a valores de dados ou eventos, portanto ainda estão em branco e não têm comportamento.

## Vincular controles de entrada a propriedades de dados

O próximo passo é vincular os controles de entrada às propriedades `Actor` correspondentes com vinculação de dados bidirecional, para que eles respondam à entrada do usuário atualizando o modelo de dados e também respondam a mudanças programáticas nos dados atualizando a exibição.

A directive `ngModel` declarada no `FormsModule` permite vincular controles em seu formulário template-driven a propriedades em seu modelo de dados.
Quando você inclui a directive usando a sintaxe para vinculação de dados bidirecional, `[(ngModel)]`, o Angular pode rastrear o valor e a interação do usuário com o controle e manter a view sincronizada com o modelo.

1. Edite o arquivo de template `actor-form.component.html`.
1. Encontre a tag `<input>` ao lado do rótulo **Name**.
1. Adicione a directive `ngModel`, usando a sintaxe de vinculação de dados bidirecional `[(ngModel)]="..."`.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="ngModelName-1"/>

HELPFUL: Este exemplo tem uma interpolação de diagnóstico temporária após cada tag de entrada, `{{model.name}}`, para mostrar o valor de dados atual da propriedade correspondente. O comentário lembra você de remover as linhas de diagnóstico quando terminar de observar a vinculação de dados bidirecional em funcionamento.

### Acessar o status geral do formulário

Quando você importou o `FormsModule` em seu component, o Angular criou e anexou automaticamente uma directive [NgForm](api/forms/NgForm) à tag `<form>` no template (porque `NgForm` tem o seletor `form` que corresponde aos elementos `<form>`).

Para obter acesso ao `NgForm` e ao status geral do formulário, declare uma [variável de referência de template](guide/templates/variables#template-reference-variables).

1. Edite o arquivo de template `actor-form.component.html`.
1. Atualize a tag `<form>` com uma variável de referência de template, `#actorForm`, e defina seu valor da seguinte forma.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="template-variable"/>

A variável de template `actorForm` agora é uma referência à instância da directive `NgForm` que governa o formulário como um todo.

1. Execute o aplicativo.
1. Comece a digitar na caixa de entrada **Name**.

Conforme você adiciona e exclui caracteres, pode vê-los aparecer e desaparecer do modelo de dados.

A linha de diagnóstico que mostra valores interpolados demonstra que os valores estão realmente fluindo da caixa de entrada para o modelo e de volta novamente.

### Nomear elementos de controle

Quando você usa `[(ngModel)]` em um elemento, deve definir um atributo `name` para esse elemento.
O Angular usa o nome atribuído para registrar o elemento com a directive `NgForm` anexada ao elemento pai `<form>`.

O exemplo adicionou um atributo `name` ao elemento `<input>` e o definiu como "name", o que faz sentido para o nome do actor.
Qualquer valor único serve, mas usar um nome descritivo é útil.

1. Adicione vinculações `[(ngModel)]` e atributos `name` similares a **Studio** e **Skill**.
1. Agora você pode remover as mensagens de diagnóstico que mostram valores interpolados.
1. Para confirmar que a vinculação de dados bidirecional funciona para todo o modelo de actor, adicione uma nova vinculação de texto com o pipe [`json`](api/common/JsonPipe) no topo do template do component, que serializa os dados para uma string.

Após essas revisões, o template do formulário deve se parecer com o seguinte:

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="ngModel-2"/>

Você notará que:

- Cada elemento `<input>` tem uma propriedade `id`.
  Isso é usado pelo atributo `for` do elemento `<label>` para corresponder o rótulo ao seu controle de entrada.
  Este é um [recurso HTML padrão](https://developer.mozilla.org/docs/Web/HTML/Element/label).

- Cada elemento `<input>` também tem a propriedade `name` necessária que o Angular usa para registrar o controle com o formulário.

Quando você tiver observado os efeitos, pode excluir a vinculação de texto `{{ model | json }}`.

## Rastrear estados do formulário

O Angular aplica a classe `ng-submitted` aos elementos `form` após o formulário ter sido enviado. Esta classe pode ser usada para alterar o estilo do formulário após ele ter sido enviado.

## Rastrear estados do controle

Adicionar a directive `NgModel` a um controle adiciona nomes de classe ao controle que descrevem seu estado.
Essas classes podem ser usadas para alterar o estilo de um controle com base em seu estado.

A tabela a seguir descreve os nomes de classe que o Angular aplica com base no estado do controle.

O Angular também aplica a classe `ng-submitted` aos elementos `form` após o envio,
mas não aos controles dentro do elemento `form`.

Você usa essas classes CSS para definir os estilos para seu controle com base em seu status.

### Observar estados do controle

Para ver como as classes são adicionadas e removidas pelo framework, abra as ferramentas de desenvolvedor do navegador e inspecione o elemento `<input>` que representa o nome do actor.

1. Usando as ferramentas de desenvolvedor do seu navegador, encontre o elemento `<input>` que corresponde à caixa de entrada **Name**.
   Você pode ver que o elemento tem várias classes CSS além de "form-control".

1. Quando você o abre pela primeira vez, as classes indicam que ele tem um valor válido, que o valor não foi alterado desde a inicialização ou redefinição, e que o controle não foi visitado desde a inicialização ou redefinição.

<docs-code language="html">

<input class="form-control ng-untouched ng-pristine ng-valid">;
```
1. Execute as seguintes ações na caixa `<input>` de **Name** e observe quais classes aparecem.
   - Olhe mas não toque.
     As classes indicam que está intocado, pristine e válido.

- Clique dentro da caixa de nome, depois clique fora dela.
     O controle foi visitado agora, e o elemento tem a classe `ng-touched` em vez da classe `ng-untouched`.

- Adicione barras ao final do nome.
     Agora está touched e dirty.

- Apague o nome.
     Isso torna o valor inválido, então a classe `ng-invalid` substitui a classe `ng-valid`.

### Criar feedback visual para estados

O par `ng-valid`/`ng-invalid` é particularmente interessante, porque você quer enviar um
sinal visual forte quando os valores são inválidos.
Você também quer marcar campos obrigatórios.

Você pode marcar campos obrigatórios e dados inválidos ao mesmo tempo com uma barra colorida
à esquerda da caixa de entrada.

Para alterar a aparência dessa forma, execute as seguintes etapas.

1. Adicione definições para as classes CSS `ng-*`.
1. Adicione essas definições de classe a um novo arquivo `forms.css`.
1. Adicione o novo arquivo ao projeto como irmão de `index.html`:

<docs-code header="src/assets/forms.css" language="css" path="adev/src/content/examples/forms/src/assets/forms.css"/>

1. No arquivo `index.html`, atualize a tag `<head>` para incluir a nova folha de estilo.

<docs-code header="src/index.html (styles)" path="adev/src/content/examples/forms/src/index.html" visibleRegion="styles"/>

### Mostrar e ocultar mensagens de erro de validação

A caixa de entrada **Name** é obrigatória e limpá-la deixa a barra vermelha.
Isso indica que algo está errado, mas o usuário não sabe o que está errado ou o que fazer a respeito.
Você pode fornecer uma mensagem útil verificando e respondendo ao estado do controle.

A caixa de seleção **Skill** também é obrigatória, mas não precisa desse tipo de tratamento de erro porque a caixa de seleção já restringe a seleção a valores válidos.

Para definir e mostrar uma mensagem de erro quando apropriado, execute as seguintes etapas.

<docs-workflow>
<docs-step title="Adicionar uma referência local à entrada">
Estenda a tag `input` com uma variável de referência de template que você pode usar para acessar o controle Angular da caixa de entrada de dentro do template. No exemplo, a variável é `#name="ngModel"`.

A variável de referência de template (`#name`) é definida como `"ngModel"` porque esse é o valor da propriedade [`NgModel.exportAs`](api/core/Directive#exportAs). Esta propriedade diz ao Angular como vincular uma variável de referência a uma directive.
</docs-step>

<docs-step title="Adicionar a mensagem de erro">
Adicione um `<div>` que contém uma mensagem de erro adequada.
</docs-step>

<docs-step title="Tornar a mensagem de erro condicional">
Mostre ou oculte a mensagem de erro vinculando propriedades do controle `name` à propriedade `hidden` do elemento `<div>` da mensagem.
</docs-step>

<docs-code header="actor-form.component.html (hidden-error-msg)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="hidden-error-msg"/>

<docs-step title="Adicionar uma mensagem de erro condicional ao name">
Adicione uma mensagem de erro condicional à caixa de entrada `name`, como no exemplo a seguir.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="name-with-error-msg"/>
</docs-step>
</docs-workflow>
Neste exemplo, você oculta a mensagem quando o controle está válido ou _pristine_.
Pristine significa que o usuário não alterou o valor desde que foi exibido neste formulário.
Se você ignorar o estado `pristine`, ocultará a mensagem apenas quando o valor for válido.
Se você chegar neste component com um novo actor em branco ou um actor inválido, verá a mensagem de erro imediatamente, antes de ter feito qualquer coisa.

Você pode querer que a mensagem seja exibida apenas quando o usuário fizer uma alteração inválida.
Ocultar a mensagem enquanto o controle está no estado `pristine` alcança esse objetivo.
Você verá a importância dessa escolha quando adicionar um novo actor ao formulário na próxima etapa.
## Adicionar um novo actor

Este exercício mostra como você pode responder a um evento de clique de botão HTML nativo adicionando aos dados do modelo.
Para permitir que os usuários do formulário adicionem um novo actor, você adicionará um botão **New Actor** que responde a um evento de clique.

1. No template, coloque um elemento `<button>` "New Actor" na parte inferior do formulário.
1. No arquivo do component, adicione o método de criação de actor ao modelo de dados de actor.

<docs-code header="actor-form.component.ts (New Actor method)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" visibleRegion="new-actor"/>

1. Vincule o evento de clique do botão a um método de criação de actor, `newActor()`.

<docs-code header="actor-form.component.html (New Actor button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="new-actor-button-no-reset"/>

1. Execute o aplicativo novamente e clique no botão **New Actor**.

O formulário é limpo e as barras _obrigatórias_ à esquerda da caixa de entrada ficam vermelhas, indicando propriedades `name` e `skill` inválidas.
   Observe que as mensagens de erro estão ocultas.
   Isso ocorre porque o formulário está pristine; você ainda não alterou nada.

1. Digite um nome e clique em **New Actor** novamente.

Agora o aplicativo exibe uma mensagem de erro `Name is required`, porque a caixa de entrada não está mais pristine.
   O formulário lembra que você digitou um nome antes de clicar em **New Actor**.

1. Para restaurar o estado pristine dos controles do formulário, limpe todos os flags imperativamente chamando o método `reset()` do formulário após chamar o método `newActor()`.

<docs-code header="actor-form.component.html (Reset the form)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="new-actor-button-form-reset"/>

Agora clicar em **New Actor** redefine tanto o formulário quanto seus flags de controle.

## Enviar o formulário com `ngSubmit`

O usuário deve ser capaz de enviar este formulário depois de preenchê-lo.
O botão **Submit** na parte inferior do formulário não faz nada por si só, mas aciona um evento de envio de formulário por causa de seu tipo (`type="submit"`).

Para responder a este evento, execute as seguintes etapas.

<docs-workflow>

<docs-step title="Escutar ngOnSubmit">
Vincule a propriedade de evento [`ngSubmit`](api/forms/NgForm#properties) do formulário ao método `onSubmit()` do component actor-form.

<docs-code header="actor-form.component.html (ngSubmit)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="ngSubmit"/>
</docs-step>

<docs-step title="Vincular a propriedade disabled">
Use a variável de referência de template, `#actorForm` para acessar o formulário que contém o botão **Submit** e criar uma vinculação de evento.

Você vinculará a propriedade do formulário que indica sua validade geral à propriedade `disabled` do botão **Submit**.

<docs-code header="actor-form.component.html (submit-button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="submit-button"/>
</docs-step>

<docs-step title="Executar o aplicativo">
Observe que o botão está habilitado — embora ainda não faça nada útil.
</docs-step>

<docs-step title="Excluir o valor Name">
Isso viola a regra "obrigatória", então exibe a mensagem de erro — e observe que também desabilita o botão **Submit**.

Você não precisou conectar explicitamente o estado habilitado do botão à validade do formulário.
O `FormsModule` fez isso automaticamente quando você definiu uma variável de referência de template no elemento de formulário aprimorado, depois referenciou essa variável no controle do botão.
</docs-step>
</docs-workflow>

### Responder ao envio do formulário

Para mostrar uma resposta ao envio do formulário, você pode ocultar a área de entrada de dados e exibir outra coisa em seu lugar.

<docs-workflow>
<docs-step title="Encapsular o formulário">
Envolva todo o formulário em um `<div>` e vincule sua propriedade `hidden` à propriedade `ActorFormComponent.submitted`.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="edit-div"/>

O formulário principal está visível desde o início porque a propriedade `submitted` é false até que você envie o formulário, como este fragmento do `ActorFormComponent` mostra:

<docs-code header="actor-form.component.ts (submitted)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" visibleRegion="submitted"/>

Quando você clica no botão **Submit**, o flag `submitted` se torna true e o formulário desaparece.
</docs-step>

<docs-step title="Adicionar o estado submitted">
Para mostrar outra coisa enquanto o formulário está no estado submitted, adicione o seguinte HTML abaixo do novo wrapper `<div>`.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="submitted"/>

Este `<div>`, que mostra um actor somente leitura com vinculações de interpolação, aparece apenas enquanto o component está no estado submitted.

A exibição alternativa inclui um botão _Edit_ cujo evento de clique está vinculado a uma expressão que limpa o flag `submitted`.
</docs-step>

<docs-step title="Testar o botão Edit">
Clique no botão *Edit* para alternar a exibição de volta para o formulário editável.
</docs-step>
</docs-workflow>

## Resumo

O formulário Angular discutido nesta página aproveita os seguintes
recursos do framework para fornecer suporte para modificação de dados, validação e muito mais.

- Um template de formulário HTML do Angular
- Uma classe component de formulário com um decorator `@Component`
- Manipulação de envio de formulário vinculando à propriedade de evento `NgForm.ngSubmit`
- Variáveis de referência de template como `#actorForm` e `#name`
- Sintaxe `[(ngModel)]` para vinculação de dados bidirecional
- O uso de atributos `name` para validação e rastreamento de alteração de elemento de formulário
- A propriedade `valid` da variável de referência em controles de entrada indica se um controle é válido ou deve mostrar mensagens de erro
- Controlar o estado habilitado do botão **Submit** vinculando à validade do `NgForm`
- Classes CSS personalizadas que fornecem feedback visual aos usuários sobre controles que não são válidos

Aqui está o código para a versão final do aplicativo:

# Validando entrada de formulário

Você pode melhorar a qualidade geral dos dados validando a entrada do usuário quanto à precisão e completude.
Esta página mostra como validar a entrada do usuário a partir da UI e exibir mensagens de validação úteis, tanto em reactive forms quanto em template-driven forms.

## Validando entrada em template-driven forms

Para adicionar validação a um template-driven form, você adiciona os mesmos atributos de validação que faria com [validação de formulário HTML nativa](https://developer.mozilla.org/docs/Web/Guide/HTML/HTML5/Constraint_validation).
O Angular usa directives para corresponder esses atributos a funções validadoras no framework.

Toda vez que o valor de um form control muda, o Angular executa a validação e gera uma lista de erros de validação que resulta em um status `INVALID`, ou null, que resulta em um status VALID.

Você pode então inspecionar o estado do control exportando `ngModel` para uma variável local de template.
O exemplo a seguir exporta `NgModel` para uma variável chamada `name`:

```
Observe os seguintes recursos ilustrados pelo exemplo.

- O elemento `<input>` carrega os atributos de validação HTML: `required` e `minlength`.
  Ele também carrega uma directive validadora personalizada, `forbiddenName`.
  Para mais informações, consulte a seção [Validadores personalizados](#defining-custom-validators).

- `#name="ngModel"` exporta `NgModel` para uma variável local chamada `name`.
  `NgModel` espelha muitas das propriedades de sua instância `FormControl` subjacente, então você pode usar isso no template para verificar estados de control como `valid` e `dirty`.
  Para uma lista completa de propriedades de control, consulte a referência da API [AbstractControl](api/forms/AbstractControl).
  - O `@if` mais externo revela um conjunto de mensagens aninhadas, mas apenas se o `name` for inválido e o control estiver `dirty` ou `touched`.

- Cada `@if` aninhado pode apresentar uma mensagem personalizada para um dos possíveis erros de validação.
    Existem mensagens para `required`, `minlength` e `forbiddenName`.

HELPFUL: Para evitar que o validador exiba erros antes que o usuário tenha a chance de editar o formulário, você deve verificar os estados `dirty` ou `touched` em um control.

- Quando o usuário altera o valor no campo observado, o control é marcado como "dirty"
- Quando o usuário desfoca o elemento form control, o control é marcado como "touched"

## Validando entrada em reactive forms

Em um reactive form, a fonte da verdade é a classe do component.
Em vez de adicionar validadores através de atributos no template, você adiciona funções validadoras diretamente ao form control model na classe do component.
O Angular então chama essas funções sempre que o valor do control muda.

### Funções validadoras

Funções validadoras podem ser síncronas ou assíncronas.

| Tipo de validador       | Detalhes                                                                                                                                                                                                                               |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Validadores síncronos   | Funções síncronas que recebem uma instância de control e retornam imediatamente um conjunto de erros de validação ou `null`. Passe-os como o segundo argumento ao instanciar um `FormControl`.                                         |
| Validadores assíncronos | Funções assíncronas que recebem uma instância de control e retornam uma Promise ou Observable que posteriormente emite um conjunto de erros de validação ou `null`. Passe-os como o terceiro argumento ao instanciar um `FormControl`. |

Por razões de desempenho, o Angular executa validadores assíncronos apenas se todos os validadores síncronos passarem.
Cada um deve ser concluído antes que os erros sejam definidos.

### Funções validadoras nativas

Você pode optar por [escrever suas próprias funções validadoras](#defining-custom-validators), ou pode usar alguns dos validadores nativos do Angular.

Os mesmos validadores nativos que estão disponíveis como atributos em template-driven forms, como `required` e `minlength`, estão todos disponíveis para uso como funções da classe `Validators`.
Para uma lista completa de validadores nativos, consulte a referência da API [Validators](api/forms/Validators).

Para atualizar o formulário de ator para ser um reactive form, use alguns dos mesmos
validadores nativos—desta vez, na forma de função, como no exemplo a seguir.

<docs-code header="reactive/actor-form-reactive.component.ts (validator functions)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" visibleRegion="form-group"/>

Neste exemplo, o control `name` configura dois validadores nativos—`Validators.required` e `Validators.minLength(4)`— e um validador personalizado, `forbiddenNameValidator`.

Todos esses validadores são síncronos, então são passados como o segundo argumento.
Observe que você pode suportar vários validadores passando as funções como um array.

Este exemplo também adiciona alguns métodos getter.
Em um reactive form, você sempre pode acessar qualquer form control através do método `get` em seu grupo pai, mas às vezes é útil definir getters como atalho para o template.

Se você olhar para o template da entrada `name` novamente, é bastante semelhante ao exemplo template-driven.

<docs-code header="reactive/actor-form-reactive.component.html (name with error msg)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" visibleRegion="name-with-error-msg"/>

Este formulário difere da versão template-driven pelo fato de não exportar mais nenhuma directive. Em vez disso, ele usa o getter `name` definido na classe do component.

Observe que o atributo `required` ainda está presente no template. Embora não seja necessário para validação, ele deve ser mantido para fins de acessibilidade.

## Definindo validadores personalizados {#defining-custom-validators}

Os validadores nativos nem sempre correspondem ao caso de uso exato da sua aplicação, então às vezes você precisa criar um validador personalizado.

Considere a função `forbiddenNameValidator` do exemplo anterior.
Aqui está a definição dessa função.

<docs-code header="shared/forbidden-name.directive.ts (forbiddenNameValidator)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" visibleRegion="custom-validator"/>

A função é uma fábrica que recebe uma expressão regular para detectar um nome proibido _específico_ e retorna uma função validadora.

Nesta amostra, o nome proibido é "bob", então o validador rejeita qualquer nome de ator contendo "bob".
Em outro lugar, poderia rejeitar "alice" ou qualquer nome que a expressão regular configurada corresponda.

A fábrica `forbiddenNameValidator` retorna a função validadora configurada.
Essa função recebe um objeto de control Angular e retorna _ou_ null se o valor do control for válido _ou_ um objeto de erro de validação.
O objeto de erro de validação normalmente tem uma propriedade cujo nome é a chave de validação, `'forbiddenName'`, e cujo valor é um dicionário arbitrário de valores que você poderia inserir em uma mensagem de erro, `{name}`.

Validadores assíncronos personalizados são semelhantes aos validadores síncronos, mas devem retornar uma Promise ou observable que posteriormente emite null ou um objeto de erro de validação.
No caso de um observable, o observable deve ser completado, momento em que o formulário usa o último valor emitido para validação.

### Adicionando validadores personalizados a reactive forms

Em reactive forms, adicione um validador personalizado passando a função diretamente para o `FormControl`.

### Adicionando validadores personalizados a template-driven forms

Em template-driven forms, adicione uma directive ao template, onde a directive encapsula a função validadora.
Por exemplo, a `ForbiddenValidatorDirective` correspondente serve como um wrapper em torno do `forbiddenNameValidator`.

O Angular reconhece o papel da directive no processo de validação porque a directive se registra com o provider `NG_VALIDATORS`, conforme mostrado no exemplo a seguir.
`NG_VALIDATORS` é um provider predefinido com uma coleção extensível de validadores.

<docs-code header="shared/forbidden-name.directive.ts (providers)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" visibleRegion="directive-providers"/>

A classe directive então implementa a interface `Validator`, para que possa se integrar facilmente com formulários Angular.
Aqui está o resto da directive para ajudá-lo a entender como tudo se encaixa.

<docs-code header="shared/forbidden-name.directive.ts (directive)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" visibleRegion="directive"/>

Uma vez que a `ForbiddenValidatorDirective` esteja pronta, você pode adicionar seu seletor, `appForbiddenName`, a qualquer elemento de entrada para ativá-la.
Por exemplo:

<docs-code header="template/actor-form-template.component.html (forbidden-name-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="name-input"/>

HELPFUL: Observe que a directive de validação personalizada é instanciada com `useExisting` em vez de `useClass`.
O validador registrado deve ser _esta instância_ da `ForbiddenValidatorDirective`—a instância no formulário com sua propriedade `forbiddenName` vinculada a "bob".

Se você substituísse `useExisting` por `useClass`, então você estaria registrando uma nova instância de classe, uma que não tem `forbiddenName`.

## Classes CSS de status de control

O Angular espelha automaticamente muitas propriedades de control no elemento form control como classes CSS.
Use essas classes para estilizar elementos form control de acordo com o estado do formulário.
As seguintes classes são atualmente suportadas.

- `.ng-valid`
- `.ng-invalid`
- `.ng-pending`
- `.ng-pristine`
- `.ng-dirty`
- `.ng-untouched`
- `.ng-touched`
- `.ng-submitted` $apenas elemento form envolvente$

No exemplo a seguir, o formulário de ator usa as classes `.ng-valid` e `.ng-invalid` para
definir a cor da borda de cada form control.

<docs-code header="forms.css (status classes)" path="adev/src/content/examples/form-validation/src/assets/forms.css"/>

## Validação de campos cruzados {#control-status-css-classes}

Um validador de campos cruzados é um [validador personalizado](#defining-custom-validators) que compara os valores de diferentes campos em um formulário e os aceita ou rejeita em combinação.
Por exemplo, você pode ter um formulário que oferece opções mutuamente incompatíveis, de modo que se o usuário puder escolher A ou B, mas não ambos.
Alguns valores de campo também podem depender de outros; um usuário pode ser permitido escolher B apenas se A também for escolhido.

Os exemplos de validação cruzada a seguir mostram como fazer o seguinte:

- Validar entrada de formulário reactive ou baseado em template com base nos valores de dois controls irmãos,
- Mostrar uma mensagem de erro descritiva depois que o usuário interagiu com o formulário e a validação falhou.

Os exemplos usam validação cruzada para garantir que os atores não reutilizem o mesmo nome em seu papel preenchendo o Formulário de Ator.
Os validadores fazem isso verificando que os nomes e papéis dos atores não correspondem.

### Adicionando validação cruzada a reactive forms

O formulário tem a seguinte estrutura:

<docs-code language="javascript">

const actorForm = new FormGroup({
'name': new FormControl(),
'role': new FormControl(),
'skill': new FormControl()
});
```
Observe que `name` e `role` são controls irmãos.
Para avaliar ambos os controls em um único validador personalizado, você deve executar a validação em um control ancestral comum: o `FormGroup`.
Você consulta o `FormGroup` por seus controls filhos para poder comparar seus valores.

Para adicionar um validador ao `FormGroup`, passe o novo validador como o segundo argumento na criação.

```javascript
const actorForm = new FormGroup({
'name': new FormControl(),
'role': new FormControl(),
'skill': new FormControl()
}, { validators: unambiguousRoleValidator });
```
O código do validador é o seguinte.

```
O validador `unambiguousRoleValidator` implementa a interface `ValidatorFn`.
Ele recebe um objeto de control Angular como argumento e retorna null se o formulário for válido, ou `ValidationErrors` caso contrário.

O validador recupera os controls filhos chamando o método [get](api/forms/AbstractControl#get) do `FormGroup`, depois compara os valores dos controls `name` e `role`.

Se os valores não corresponderem, o papel é inequívoco, ambos são válidos e o validador retorna null.
Se eles corresponderem, o papel do ator é ambíguo e o validador deve marcar o formulário como inválido retornando um objeto de erro.

Para fornecer uma melhor experiência ao usuário, o template mostra uma mensagem de erro apropriada quando o formulário é inválido.

<docs-code header="reactive/actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" visibleRegion="cross-validation-error-message"/>

Este `@if` exibe o erro se o `FormGroup` tiver o erro de validação cruzada retornado pelo validador `unambiguousRoleValidator`, mas apenas se o usuário terminou de [interagir com o formulário](#control-status-css-classes).

### Adicionando validação cruzada a template-driven forms

Para um template-driven form, você deve criar uma directive para encapsular a função validadora.
Você fornece essa directive como validador usando o token [`NG_VALIDATORS` token](/api/forms/NG_VALIDATORS), conforme mostrado no exemplo a seguir.

<docs-code header="shared/unambiguous-role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/unambiguous-role.directive.ts" visibleRegion="cross-validation-directive"/>

Você deve adicionar a nova directive ao template HTML.
Como o validador deve ser registrado no nível mais alto no formulário, o template a seguir coloca a directive na tag `form`.

<docs-code header="template/actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="cross-validation-register-validator"/>

Para fornecer uma melhor experiência ao usuário, uma mensagem de erro apropriada aparece quando o formulário é inválido.

Isso é o mesmo tanto em template-driven quanto em reactive forms.

## Criando validadores assíncronos

Validadores assíncronos implementam as interfaces `AsyncValidatorFn` e `AsyncValidator`.
Estes são muito semelhantes aos seus equivalentes síncronos, com as seguintes diferenças.

- As funções `validate()` devem retornar uma Promise ou um observable,
- O observable retornado deve ser finito, ou seja, deve ser completado em algum momento.
  Para converter um observable infinito em um finito, faça o pipe do observable através de um operador de filtragem como `first`, `last`, `take` ou `takeUntil`.

A validação assíncrona acontece após a validação síncrona e é executada apenas se a validação síncrona for bem-sucedida.
Essa verificação permite que os formulários evitem processos de validação assíncrona potencialmente caros $como uma solicitação HTTP$ se os métodos de validação mais básicos já encontraram entrada inválida.

Após o início da validação assíncrona, o form control entra em um estado `pending`.
Inspecione a propriedade `pending` do control e use-a para fornecer feedback visual sobre a operação de validação em andamento.

Um padrão de UI comum é mostrar um spinner enquanto a validação assíncrona está sendo executada.
O exemplo a seguir mostra como alcançar isso em um template-driven form.

<docs-code language="html">

<input [(ngModel)]="name" #model="ngModel" appSomeAsyncValidator>
@if(model.pending) {
<app-spinner />
}
```
### Implementando um validador assíncrono personalizado

No exemplo a seguir, um validador assíncrono garante que os atores sejam escolhidos para um papel que ainda não está ocupado.
Novos atores estão constantemente fazendo audições e atores antigos estão se aposentando, então a lista de papéis disponíveis não pode ser recuperada antecipadamente.
Para validar a potencial entrada de papel, o validador deve iniciar uma operação assíncrona para consultar um banco de dados central de todos os atores atualmente escalados.

O código a seguir cria a classe validadora, `UniqueRoleValidator`, que implementa a interface `AsyncValidator`.

```
A propriedade `actorsService` é inicializada com uma instância do token `ActorsService`, que define a seguinte interface.

<docs-code language="typescript">
interface ActorsService {
  isRoleTaken: (role: string) => Observable<boolean>;
}
```
Em uma aplicação do mundo real, o `ActorsService` seria responsável por fazer uma solicitação HTTP ao banco de dados de atores para verificar se o papel está disponível.
Do ponto de vista do validador, a implementação real do serviço não é importante, então o exemplo pode apenas codificar contra a interface `ActorsService`.

À medida que a validação começa, o `UnambiguousRoleValidator` delega ao método `isRoleTaken()` do `ActorsService` com o valor atual do control.
Neste ponto, o control é marcado como `pending` e permanece neste estado até que a cadeia observable retornada do método `validate()` seja concluída.

O método `isRoleTaken()` despacha uma solicitação HTTP que verifica se o papel está disponível e retorna `Observable<boolean>` como resultado.
O método `validate()` faz o pipe da resposta através do operador `map` e a transforma em um resultado de validação.

O método então, como qualquer validador, retorna `null` se o formulário for válido e `ValidationErrors` se não for.
Este validador lida com quaisquer erros potenciais com o operador `catchError`.
Neste caso, o validador trata o erro `isRoleTaken()` como uma validação bem-sucedida, porque a falha ao fazer uma solicitação de validação não significa necessariamente que o papel é inválido.
Você poderia lidar com o erro de forma diferente e retornar o objeto `ValidationError` em vez disso.

Depois de algum tempo, a cadeia observable é concluída e a validação assíncrona é feita.
A flag `pending` é definida como `false` e a validade do formulário é atualizada.

### Adicionando validadores assíncronos a reactive forms

Para usar um validador assíncrono em reactive forms, comece injetando o validador em uma propriedade da classe do component.

```
Em seguida, passe a função validadora diretamente para o `FormControl` para aplicá-la.

No exemplo a seguir, a função `validate` de `UnambiguousRoleValidator` é aplicada a `roleControl` passando-a para a opção `asyncValidators` do control e vinculando-a à instância de `UnambiguousRoleValidator` que foi injetada em `ActorFormReactiveComponent`.
O valor de `asyncValidators` pode ser uma única função validadora assíncrona ou um array de funções.
Para saber mais sobre opções de `FormControl`, consulte a referência da API [AbstractControlOptions](api/forms/AbstractControlOptions).

<docs-code path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" visibleRegion="async-validator-usage"/>

### Adicionando validadores assíncronos a template-driven forms {#adding-async-validators-to-template-driven-forms}

Para usar um validador assíncrono em template-driven forms, crie uma nova directive e registre o provider `NG_ASYNC_VALIDATORS` nela.

No exemplo abaixo, a directive injeta a classe `UniqueRoleValidator` que contém a lógica de validação real e a invoca na função `validate`, acionada pelo Angular quando a validação deve acontecer.

<docs-code path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" visibleRegion="async-validator-directive"/>

Em seguida, assim como com validadores síncronos, adicione o seletor da directive a uma entrada para ativá-la.

<docs-code header="template/actor-form-template.component.html (unique-unambiguous-role-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="role-input"/>

### Otimizando o desempenho de validadores assíncronos

Por padrão, todos os validadores são executados após cada mudança de valor do formulário.
Com validadores síncronos, isso normalmente não tem um impacto perceptível no desempenho da aplicação.
Validadores assíncronos, no entanto, normalmente executam algum tipo de solicitação HTTP para validar o control.
Despachar uma solicitação HTTP após cada pressionamento de tecla pode sobrecarregar a API backend e deve ser evitado, se possível.

Você pode atrasar a atualização da validade do formulário alterando a propriedade `updateOn` de `change` (padrão) para `submit` ou `blur`.

Com template-driven forms, defina a propriedade no template.

<docs-code language="html">
<input [(ngModel)]="name" [ngModelOptions]="{updateOn: 'blur'}">
```
Com reactive forms, defina a propriedade na instância `FormControl`.

```typescript
new FormControl('', {updateOn: 'blur'});
```
## Interação com validação de formulário HTML nativa

Por padrão, o Angular desabilita [validação de formulário HTML nativa](https://developer.mozilla.org/docs/Web/Guide/HTML/Constraint_validation) adicionando o atributo `novalidate` no `<form>` envolvente e usa directives para corresponder esses atributos a funções validadoras no framework.
Se você quiser usar validação nativa **em combinação** com validação baseada em Angular, pode reativá-la com a directive `ngNativeValidate`.
Consulte a [documentação da API](api/forms/NgForm#native-dom-validation-ui) para detalhes.

# Construindo formulários dinâmicos

Muitos formulários, como questionários, podem ser muito semelhantes entre si em formato e intenção.
Para tornar mais rápido e fácil gerar diferentes versões de tal formulário, você pode criar um _template de formulário dinâmico_ baseado em metadados que descrevem o modelo de objeto de negócio.
Em seguida, use o template para gerar novos formulários automaticamente, de acordo com as mudanças no modelo de dados.

A técnica é particularmente útil quando você tem um tipo de formulário cujo conteúdo deve mudar frequentemente para atender a requisitos de negócio e regulatórios em rápida mudança.
Um caso de uso típico é um questionário.
Você pode precisar obter entrada de usuários em diferentes contextos.
O formato e o estilo dos formulários que um usuário vê devem permanecer constantes, enquanto as perguntas reais que você precisa fazer variam com o contexto.

Neste tutorial você construirá um formulário dinâmico que apresenta um questionário básico.
Você constrói um aplicativo online para heróis que buscam emprego.
A agência está constantemente ajustando o processo de inscrição, mas usando o formulário dinâmico
você pode criar os novos formulários dinamicamente sem alterar o código do aplicativo.

O tutorial orienta você através das seguintes etapas.

1. Habilitar reactive forms para um projeto.
1. Estabelecer um modelo de dados para representar controles de formulário.
1. Preencher o modelo com dados de exemplo.
1. Desenvolver um component para criar controles de formulário dinamicamente.

O formulário que você cria usa validação de entrada e estilização para melhorar a experiência do usuário.
Ele tem um botão Submit que só é habilitado quando toda a entrada do usuário é válida, e sinaliza entrada inválida com codificação de cores e mensagens de erro.

A versão básica pode evoluir para suportar uma variedade mais rica de perguntas, renderização mais elegante e experiência de usuário superior.

## Habilitar reactive forms para seu projeto

Formulários dinâmicos são baseados em reactive forms.

Para dar ao aplicativo acesso às directives de reactive forms, importe `ReactiveFormsModule` da biblioteca `@angular/forms` nos components necessários.
## Criar um modelo de objeto de formulário

Um formulário dinâmico requer um modelo de objeto que possa descrever todos os cenários necessários pela funcionalidade do formulário.
O formulário de exemplo de aplicação de herói é um conjunto de perguntas — isto é, cada controle no formulário deve fazer uma pergunta e aceitar uma resposta.

O modelo de dados para este tipo de formulário deve representar uma pergunta.
O exemplo inclui o `DynamicFormQuestionComponent`, que define uma pergunta como o objeto fundamental no modelo.

A seguinte `QuestionBase` é uma classe base para um conjunto de controles que podem representar a pergunta e sua resposta no formulário.

<docs-code header="question-base.ts" path="adev/src/content/examples/dynamic-form/src/app/question-base.ts"/>

### Definir classes de controle

A partir desta base, o exemplo deriva duas novas classes, `TextboxQuestion` e `DropdownQuestion`, que representam diferentes tipos de controle.
Quando você criar o template do formulário no próximo passo, você instanciará esses tipos de pergunta específicos para renderizar os controles apropriados dinamicamente.

O tipo de controle `TextboxQuestion` é representado em um template de formulário usando um elemento `<input>`. Ele apresenta uma pergunta e permite que os usuários insiram entrada. O atributo `type` do elemento é definido com base no campo `type` especificado no argumento `options` (por exemplo `text`, `email`, `url`).

<docs-code header="question-textbox.ts" path="adev/src/content/examples/dynamic-form/src/app/question-textbox.ts"/>

O tipo de controle `DropdownQuestion` apresenta uma lista de escolhas em uma caixa de seleção.

<docs-code header="question-dropdown.ts" path="adev/src/content/examples/dynamic-form/src/app/question-dropdown.ts"/>

### Compor grupos de formulário

Um formulário dinâmico usa um service para criar conjuntos agrupados de controles de entrada, baseados no modelo de formulário.
O seguinte `QuestionControlService` coleta um conjunto de instâncias `FormGroup` que consomem os metadados do modelo de pergunta.
Você pode especificar valores padrão e regras de validação.

<docs-code header="question-control.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question-control.service.ts"/>

## Compor conteúdo de formulário dinâmico

O formulário dinâmico em si é representado por um component contêiner, que você adiciona em uma etapa posterior.
Cada pergunta é representada no template do component do formulário por uma tag `<app-question>`, que corresponde a uma instância de `DynamicFormQuestionComponent`.

O `DynamicFormQuestionComponent` é responsável por renderizar os detalhes de uma pergunta individual com base nos valores no objeto de pergunta vinculado aos dados.
O formulário depende de uma [directive `[formGroup]`](api/forms/FormGroupDirective 'API reference') para conectar o HTML do template aos objetos de controle subjacentes.
O `DynamicFormQuestionComponent` cria grupos de formulário e os preenche com controles definidos no modelo de pergunta, especificando regras de exibição e validação.
O objetivo do `DynamicFormQuestionComponent` é apresentar tipos de pergunta definidos em seu modelo.
Você tem apenas dois tipos de perguntas neste ponto, mas pode imaginar muitos mais.
O bloco `@switch` no template determina qual tipo de pergunta exibir.
O switch usa directives com os seletores [`formControlName`](api/forms/FormControlName 'FormControlName directive API reference') e [`formGroup`](api/forms/FormGroupDirective 'FormGroupDirective API reference').
Ambas as directives são definidas em `ReactiveFormsModule`.

### Fornecer dados

Outro service é necessário para fornecer um conjunto específico de perguntas a partir das quais construir um formulário individual.
Para este exercício, você cria o `QuestionService` para fornecer este array de perguntas a partir dos dados de exemplo codificados.
Em um aplicativo do mundo real, o service pode buscar dados de um sistema backend.
O ponto chave, no entanto, é que você controla as perguntas de inscrição de emprego de herói inteiramente através dos objetos retornados de `QuestionService`.
Para manter o questionário conforme os requisitos mudam, você só precisa adicionar, atualizar e remover objetos do array `questions`.

O `QuestionService` fornece um conjunto de perguntas na forma de um array vinculado ao `input()` questions.

<docs-code header="question.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question.service.ts"/>

## Criar um template de formulário dinâmico

O component `DynamicFormComponent` é o ponto de entrada e o contêiner principal para o formulário, que é representado usando `<app-dynamic-form>` em um template.

O component `DynamicFormComponent` apresenta uma lista de perguntas vinculando cada uma a um elemento `<app-question>` que corresponde ao `DynamicFormQuestionComponent`.
### Exibir o formulário

Para exibir uma instância do formulário dinâmico, o template shell do `AppComponent` passa o array `questions` retornado pelo `QuestionService` para o component contêiner do formulário, `<app-dynamic-form>`.

<docs-code header="app.component.ts" path="adev/src/content/examples/dynamic-form/src/app/app.component.ts"/>

Esta separação de modelo e dados permite reutilizar os components para qualquer tipo de pesquisa, desde que seja compatível com o modelo de objeto _question_.

### Garantir dados válidos

O template do formulário usa vinculação de dados dinâmica de metadados para renderizar o formulário sem fazer suposições codificadas sobre perguntas específicas.
Ele adiciona tanto metadados de controle quanto critérios de validação dinamicamente.

Para garantir entrada válida, o botão _Save_ é desabilitado até que o formulário esteja em um estado válido.
Quando o formulário está válido, clique em _Save_ e o aplicativo renderiza os valores atuais do formulário como JSON.

A figura a seguir mostra o formulário final.

## Próximos passos

O Angular Router (`@angular/router`) é a biblioteca oficial para gerenciar navegação em aplicações Angular e uma parte central do framework. Ele é incluído por padrão em todos os projetos criados pelo Angular CLI.

## Por que routing é necessário em uma SPA?

Quando você navega para uma URL no seu navegador web, o navegador normalmente faz uma requisição de rede para um servidor web e exibe a página HTML retornada. Quando você navega para uma URL diferente, como clicar em um link, o navegador faz outra requisição de rede e substitui a página inteira por uma nova.

Uma aplicação de página única (SPA) difere no sentido de que o navegador só faz uma requisição para um servidor web para a primeira página, o `index.html`. Depois disso, um router do lado do cliente assume o controle, controlando qual conteúdo é exibido baseado na URL. Quando um usuário navega para uma URL diferente, o router atualiza o conteúdo da página no local sem acionar um recarregamento completo da página.

## Como o Angular gerencia routing

Routing no Angular é composto de três partes principais:

1. **Routes** definem qual component é exibido quando um usuário visita uma URL específica.
2. **Outlets** são placeholders em seus templates que carregam e renderizam componentes dinamicamente baseados na rota ativa.
3. **Links** fornecem uma forma para os usuários navegarem entre diferentes rotas em sua aplicação sem acionar um recarregamento completo da página.

Além disso, a biblioteca Angular Routing oferece funcionalidade adicional como:

- Rotas aninhadas
- Navegação programática
- Parâmetros de rota, queries e wildcards
- Informação de rota ativada com `ActivatedRoute`
- Efeitos de transição de view
- Guards de navegação

## Próximos passos

Saiba mais sobre como você pode [definir rotas usando o Angular router](/guide/routing/define-routes).

# Definir routes

Routes servem como blocos de construção fundamentais para navegação dentro de uma aplicação Angular.

## O que são routes?

No Angular, uma **route** é um objeto que define qual component deve ser renderizado para um caminho ou padrão de URL específico, bem como opções de configuração adicionais sobre o que acontece quando um usuário navega para aquela URL.

Aqui está um exemplo básico de uma route:

```ts
import { AdminPage } from './app-admin/app-admin.component';

const adminPage = {
  path: 'admin',
  component: AdminPage
}
```

Para esta route, quando um usuário visita o caminho `/admin`, a aplicação exibirá o component `AdminPage`.

### Gerenciando routes em sua aplicação

A maioria dos projetos define routes em um arquivo separado que contém `routes` no nome do arquivo.

Uma coleção de routes se parece com isto:

```ts
import { Routes } from '@angular/router';
import { HomePage } from './home-page/home-page.component';
import { AdminPage } from './about-page/admin-page.component';

export const routes: Routes = [
  {
    path: '',
    component: HomePage,
  },
  {
    path: 'admin',
    component: AdminPage,
  },
];
```

Dica: Se você gerou um projeto com o Angular CLI, suas routes são definidas em `src/app/app.routes.ts`.

### Adicionando o router à sua aplicação

Ao fazer bootstrap de uma aplicação Angular sem o Angular CLI, você pode passar um objeto de configuração que inclui um array `providers`.

Dentro do array `providers`, você pode adicionar o router Angular à sua aplicação adicionando uma chamada de função `provideRouter` com suas routes.

```ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';

import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    // ...
  ]
};
```

## Caminhos de URL de Route

### Caminhos de URL Estáticos

Caminhos de URL estáticos referem-se a routes com caminhos predefinidos que não mudam com base em parâmetros dinâmicos. Estas são routes que correspondem a uma string `path` exatamente e têm um resultado fixo.

Exemplos disso incluem:

- "/admin"
- "/blog"
- "/settings/account"

### Definir Caminhos de URL com Parâmetros de Route

URLs parametrizadas permitem que você defina caminhos dinâmicos que permitem múltiplas URLs para o mesmo component, enquanto exibem dados dinamicamente com base em parâmetros na URL.

Você pode definir este tipo de padrão adicionando parâmetros à string `path` da sua route e prefixando cada parâmetro com o caractere dois-pontos (`:`).

IMPORTANTE: Parâmetros são distintos de informações na [query string](https://en.wikipedia.org/wiki/Query_string) da URL.
Saiba mais sobre [query parameters no Angular neste guia](/guide/routing/read-route-state#query-parameters).

O exemplo a seguir exibe um component de perfil de usuário com base no id do usuário passado através da URL.

```ts
import { Routes } from '@angular/router';
import { UserProfile } from './user-profile/user-profile';

const routes: Routes = [
  { path: 'user/:id', component: UserProfile }
];
```

Neste exemplo, URLs como `/user/leeroy` e `/user/jenkins` renderizam o component `UserProfile`. Este component pode então ler o parâmetro `id` e usá-lo para realizar trabalho adicional, como buscar dados. Veja o [guia de leitura de estado de route](/guide/routing/read-route-state) para detalhes sobre como ler parâmetros de route.

Nomes de parâmetros de route válidos devem começar com uma letra (a-z, A-Z) e podem conter apenas:

- Letras (a-z, A-Z)
- Números (0-9)
- Underscore (\_)
- Hífen (-)

Você também pode definir caminhos com múltiplos parâmetros:

```ts
import { Routes } from '@angular/router';
import { UserProfile } from './user-profile/user-profile.component';
import { SocialMediaFeed } from './user-profile/social–media-feed.component';

const routes: Routes = [
  { path: 'user/:id/:social-media', component: SocialMediaFeed },
  { path: 'user/:id/', component: UserProfile },
];
```

Com este novo caminho, os usuários podem visitar `/user/leeroy/youtube` e `/user/leeroy/bluesky` e ver respectivos feeds de mídia social baseados no parâmetro para o usuário leeroy.

Veja [Lendo estado de route](/guide/routing/read-route-state) para detalhes sobre como ler parâmetros de route.

### Wildcards

Quando você precisa capturar todas as routes para um caminho específico, a solução é uma route wildcard que é definida com o duplo asterisco (`**`).

Um exemplo comum é definir um component de Página Não Encontrada.

```ts
import { Home } from './home/home.component';
import { UserProfile } from './user-profile/user-profile.component';
import { NotFound } from './not-found/not-found.component';

const routes: Routes = [
  { path: 'home', component: Home },
  { path: 'user/:id', component: UserProfile },
  { path: '**', component: NotFound }
];
```

Neste array de routes, a aplicação exibe o component `NotFound` quando o usuário visita qualquer caminho fora de `home` e `user/:id`.

Dica: Routes wildcard são tipicamente colocadas no final de um array de routes.

## Como o Angular corresponde URLs

Quando você define routes, a ordem é importante porque o Angular usa uma estratégia de primeira correspondência ganha. Isso significa que uma vez que o Angular corresponde uma URL com um `path` de route, ele para de verificar quaisquer outras routes. Como resultado, sempre coloque routes mais específicas antes de routes menos específicas.

O exemplo a seguir mostra routes definidas da mais específica para a menos específica:

```ts
const routes: Routes = [
  { path: '', component: HomeComponent },              // Caminho vazio
  { path: 'users/new', component: NewUserComponent },  // Estático, mais específico
  { path: 'users/:id', component: UserDetailComponent }, // Dinâmico
  { path: 'users', component: UsersComponent },        // Estático, menos específico
  { path: '**', component: NotFoundComponent }         // Wildcard - sempre por último
];
```

Se um usuário visita `/users/new`, o router Angular passaria pelos seguintes passos:

1. Verifica `''` - não corresponde
1. Verifica `users/new` - corresponde! Para aqui
1. Nunca alcança `users/:id` mesmo que pudesse corresponder
1. Nunca alcança `users`
1. Nunca alcança `**`

## Estratégias de Carregamento de Component de Route

Entender como e quando components carregam no roteamento Angular é crucial para construir aplicações web responsivas. O Angular oferece duas estratégias principais para controlar o comportamento de carregamento de components:

1. **Carregamento eagerly (imediato)**: Components que são carregados imediatamente
2. **Carregamento lazily (preguiçoso)**: Components carregados apenas quando necessário

Cada abordagem oferece vantagens distintas para diferentes cenários.

### Components carregados eagerly

Quando você define uma route com a propriedade `component`, o component referenciado é carregado eagerly como parte do mesmo bundle JavaScript que a configuração da route.

```ts
import { Routes } from "@angular/router";
import { HomePage } from "./components/home/home-page"
import { LoginPage } from "./components/auth/login-page"

export const routes: Routes = [
  // HomePage e LoginPage são ambos diretamente referenciados nesta config,
  // então seu código é incluído eagerly no mesmo bundle JavaScript que este arquivo.
  {
    path: "",
    component: HomePage
  },
  {
    path: "login",
    component: LoginPage
  }
]
```

Carregar components de route eagerly assim significa que o browser tem que fazer download e analisar todo o JavaScript para estes components como parte do carregamento inicial da página, mas os components estão disponíveis para o Angular imediatamente.

Embora incluir mais JavaScript no carregamento inicial da página leve a tempos de carregamento inicial mais lentos, isso pode levar a transições mais suaves conforme o usuário navega pela aplicação.

### Components carregados lazily

Você pode usar a propriedade `loadComponent` para carregar lazily o JavaScript de uma route apenas no ponto em que aquela route se tornaria ativa.

```ts
import { Routes } from "@angular/router";

export const routes: Routes = [
  // Os components HomePage e LoginPage são carregados lazily no ponto em que
  // suas routes correspondentes se tornam ativas.
  {
    path: 'login',
    loadComponent: () => import('./components/auth/login-page').then(m => m.LoginPage)
  },
  {
    path: '',
    loadComponent: () => import('./components/home/home-page').then(m => m.HomePage)
  }
]
```

A propriedade `loadComponent` aceita uma função loader que retorna uma Promise que resolve para um component Angular. Na maioria dos casos, esta função usa a [API de importação dinâmica padrão do JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import). Você pode, no entanto, usar qualquer função loader assíncrona arbitrária.

Carregar routes lazily pode melhorar significativamente a velocidade de carregamento da sua aplicação Angular removendo grandes porções de JavaScript do bundle inicial. Estas porções do seu código compilam em "chunks" JavaScript separados que o router requisita apenas quando o usuário visita a route correspondente.

### Lazy loading com contexto de injeção

O Router executa `loadComponent` e `loadChildren` dentro do **contexto de injeção da route atual**, permitindo que você chame `inject` dentro destas funções loader para acessar providers declarados naquela route, herdados de routes pai através de injeção de dependência hierárquica, ou disponíveis globalmente. Isso habilita lazy loading consciente do contexto.

```ts
import { Routes } from '@angular/router';
import { inject } from '@angular/core';
import { FeatureFlags } from './feature-flags';

export const routes: Routes = [
  {
    path: 'dashboard',
    // Executa dentro do contexto de injeção da route
    loadComponent: () => {
      const flags = inject(FeatureFlags);
      return flags.isPremium
        ? import('./dashboard/premium-dashboard').then(m => m.PremiumDashboard)
        : import('./dashboard/basic-dashboard').then(m => m.BasicDashboard);
    },
  },
];
```

### Devo usar uma route eager ou lazy?

Existem muitos fatores a considerar ao decidir se uma route deve ser eager ou lazy.

Em geral, carregamento eager é recomendado para página(s) de destino primária(s) enquanto outras páginas seriam carregadas lazily.

Nota: Embora routes lazy tenham o benefício de performance inicial de reduzir a quantidade de dados iniciais requisitados pelo usuário, isso adiciona requisições futuras de dados que podem ser indesejáveis. Isso é particularmente verdadeiro ao lidar com lazy loading aninhado em múltiplos níveis, o que pode impactar significativamente a performance.

## Redirecionamentos

Você pode definir uma route que redireciona para outra route em vez de renderizar um component:

```ts
import { BlogComponent } from './home/blog.component';

const routes: Routes = [
  {
    path: 'articles',
    redirectTo: '/blog',
  },
  {
    path: 'blog',
    component: BlogComponent
  },
];
```

Se você modificar ou remover uma route, alguns usuários ainda podem clicar em links desatualizados ou favoritos para aquela route. Você pode adicionar um redirecionamento para direcionar esses usuários para uma route alternativa apropriada em vez de uma página "não encontrada".

## Títulos de página

Você pode associar um **title** com cada route. O Angular atualiza automaticamente o [título da página](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) quando uma route é ativada. Sempre defina títulos de página apropriados para sua aplicação, pois estes títulos são necessários para criar uma experiência acessível.

```ts
import { Routes } from '@angular/router';
import { HomeComponent } from './home/home.component';
import { AboutComponent } from './about/about.component';
import { ProductsComponent } from './products/products.component';

const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    title: 'Home Page'
  },
  {
    path: 'about',
    component: AboutComponent,
    title: 'About Us'
  },
];
```

A propriedade `title` da página pode ser definida dinamicamente para uma função resolver usando [`ResolveFn`](/api/router/ResolveFn).

```ts
const titleResolver: ResolveFn<string> = (route) => route.queryParams['id'];
const routes: Routes = [
   ...
  {
    path: 'products',
    component: ProductsComponent,
    title: titleResolver,
  }
];

```

Títulos de route também podem ser definidos através de um service que estende a classe abstrata [`TitleStrategy`](/api/router/TitleStrategy). Por padrão, o Angular usa a [`DefaultTitleStrategy`](/api/router/DefaultTitleStrategy).

### Usando TitleStrategy para títulos de página

Para cenários avançados onde você precisa de controle centralizado sobre como o título do documento é composto, implemente uma `TitleStrategy`.

`TitleStrategy` é um token que você pode fornecer para sobrescrever a estratégia de título padrão usada pelo Angular. Você pode fornecer uma `TitleStrategy` customizada para implementar convenções como adicionar um sufixo de aplicação, formatar títulos de breadcrumbs, ou gerar títulos dinamicamente a partir de dados de route.

```ts
import { Injectable } from '@angular/core';
import { Title } from '@angular/platform-browser';
import { TitleStrategy, RouterStateSnapshot } from '@angular/router';

@Injectable()
export class AppTitleStrategy extends TitleStrategy {
  private readonly title = inject(Title);

updateTitle(snapshot: RouterStateSnapshot): void {
    // PageTitle é igual ao "Title" de uma route se estiver definido
    // Se não estiver definido, usará o "title" fornecido em index.html
    const pageTitle = this.buildTitle(snapshot) || this.title.getTitle();
    this.title.setTitle(`MyAwesomeApp - ${pageTitle}`);
  }
}
```

Para usar a estratégia customizada, forneça-a com o token `TitleStrategy` no nível da aplicação:

```ts
import { provideRouter, TitleStrategy } from '@angular/router';
import { AppTitleStrategy } from './app-title.strategy';

export const appConfig = {
  providers: [
    provideRouter(routes),
    { provide: TitleStrategy, useClass: AppTitleStrategy },
  ],
};
```

## Providers em nível de route para injeção de dependência

Cada route tem uma propriedade `providers` que permite que você forneça dependências para o conteúdo daquela route via [injeção de dependência](/guide/di).

Cenários comuns onde isso pode ser útil incluem aplicações que têm diferentes services baseados em se o usuário é admin ou não.

```ts
export const ROUTES: Route[] = [
  {
    path: 'admin',
    providers: [
      AdminService,
      {provide: ADMIN_API_KEY, useValue: '12345'},
    ],
    children: [
      {path: 'users', component: AdminUsersComponent},
      {path: 'teams', component: AdminTeamsComponent},
    ],
  },
  // ... outras routes da aplicação que não
  //     têm acesso a ADMIN_API_KEY ou AdminService.
];
```

Neste exemplo de código, o caminho `admin` contém uma propriedade de dados protegida de `ADMIN_API_KEY` que está disponível apenas para filhos dentro de sua seção. Como resultado, nenhum outro caminho será capaz de acessar os dados fornecidos via `ADMIN_API_KEY`.

Veja o [guia de Injeção de dependência](/guide/di) para mais informações sobre providers e injeção no Angular.

## Associando dados com routes

Dados de route permitem que você anexe informações adicionais a routes. Você é capaz de configurar como components se comportam com base nestes dados.

Existem duas maneiras de trabalhar com dados de route: dados estáticos que permanecem constantes, e dados dinâmicos que podem mudar com base em condições de runtime.

### Dados estáticos

Você pode associar dados estáticos arbitrários com uma route via a propriedade `data` a fim de centralizar coisas como metadados específicos de route (ex: rastreamento de analytics, permissões, etc.):

const routes: Routes = [
  {
    path: 'about',
    component: AboutComponent,
    data: { analyticsId: '456' }
  },
  {
    path: '',
    component: HomeComponent,
    data: { analyticsId: '123' }
  }
];
```

Neste exemplo de código, as páginas home e about são configuradas com `analyticsId` específico que seria então usado em seus respectivos components para rastreamento de analytics da página.

Você pode ler estes dados estáticos injetando o `ActivatedRoute`. Veja [Lendo estado de route](/guide/routing/read-route-state) para detalhes.

### Dados dinâmicos com resolvers de dados

Quando você precisa fornecer dados dinâmicos para uma route, confira o [guia sobre resolvers de dados de route](/guide/routing/data-resolvers).

## Routes Aninhadas

Routes aninhadas, também conhecidas como routes filhas, são uma técnica comum para gerenciar routes de navegação mais complexas onde um component tem uma sub-visualização que muda com base na URL.

Você pode adicionar routes filhas a qualquer definição de route com a propriedade `children`:

```ts
const routes: Routes = [
  {
    path: 'product/:id',
    component: ProductComponent,
    children: [
      {
        path: 'info',
        component: ProductInfoComponent
      },
      {
        path: 'reviews',
        component: ProductReviewsComponent
      }
    ]
  }
]
```

O exemplo acima define uma route para uma página de produto que permite ao usuário mudar se as informações do produto ou reviews são exibidas com base na url.

A propriedade `children` aceita um array de objetos `Route`.

Para exibir routes filhas, o component pai (`ProductComponent` no exemplo acima) inclui seu próprio `<router-outlet>`.

```html

<article>
  <h1>Product {{ id }}</h1>
  <router-outlet />
</article>
```

Depois de adicionar routes filhas à configuração e adicionar um `<router-outlet>` ao component, a navegação entre URLs que correspondem às routes filhas atualiza apenas o outlet aninhado.

## Próximos passos

Saiba como [exibir o conteúdo de suas routes com Outlets](/guide/routing/show-routes-with-outlets).

# Mostrar routes com outlets

A directive `RouterOutlet` é um espaço reservado que marca o local onde o router deve renderizar o component para a URL atual.

```html
<app-header />
<router-outlet />  
<app-footer />
```

```ts
import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css'
})
export class AppComponent {}
```

Neste exemplo, se uma aplicação tem as seguintes routes definidas:

```ts
import { Routes } from '@angular/router';
import { HomeComponent } from './home/home.component';
import { ProductsComponent } from './products/products.component';

const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    title: 'Home Page'
  },
  {
    path: 'products',
    component: ProductsComponent,
    title: 'Our Products'
  }
];
```

Quando um usuário visita `/products`, o Angular renderiza o seguinte:

```html
<app-header />
<app-products />
<app-footer />
```

Se o usuário volta para a página inicial, então o Angular renderiza:

```html
<app-header />
<app-home />
<app-footer />
```

Ao exibir uma route, o elemento `<router-outlet>` permanece presente no DOM como um ponto de referência para navegações futuras. O Angular insere o conteúdo roteado logo após o elemento outlet como um irmão.

```html

<app-header />
<router-outlet />
<app-footer />
```

```html

<app-header>...</app-header>
<router-outlet></router-outlet>
<app-admin-page>...</app-admin-page>
<app-footer>...</app-footer>
```

## Aninhando routes com routes filhas

À medida que sua aplicação cresce em complexidade, você pode querer criar routes que sejam relativas a um component diferente do seu component raiz. Isso permite que você crie experiências onde apenas parte da aplicação muda quando a URL muda, em vez de os usuários sentirem que a página inteira está sendo atualizada.

Esses tipos de routes aninhadas são chamadas de routes filhas. Isso significa que você está adicionando um segundo `<router-outlet>` à sua aplicação, porque ele é adicional ao `<router-outlet>` no AppComponent.

Neste exemplo, o component `Settings` exibirá o painel desejado com base no que o usuário selecionar. Uma das coisas únicas que você notará sobre routes filhas é que o component frequentemente tem seu próprio `<nav>` e `<router-outlet>`.

```html
<h1>Settings</h1>
<nav>
  <ul>
    <li><a routerLink="profile">Profile</a></li>
    <li><a routerLink="security">Security</a></li>
  </ul>
</nav>
<router-outlet />
```

Uma route filha é como qualquer outra route, pois precisa tanto de um `path` quanto de um `component`. A única diferença é que você coloca routes filhas em um array children dentro da route pai.

```ts
const routes: Routes = [
  {
    path: 'settings-component',
    component: SettingsComponent, // this is the component with the <router-outlet> in the template
    children: [
      {
        path: 'profile', // child route path
        component: ProfileComponent, // child route component that the router renders
      },
      {
        path: 'security',
        component: SecurityComponent, // another child route component that the router renders
      },
    ],
  },
];
```

Uma vez que tanto as `routes` quanto o `<router-outlet>` estejam configurados corretamente, sua aplicação agora está usando routes aninhadas!

## Routes secundárias com outlets nomeados

Páginas podem ter múltiplos outlets— você pode atribuir um nome a cada outlet para especificar qual conteúdo pertence a qual outlet.

```html
<app-header />
<router-outlet />
<router-outlet name='read-more' />
<router-outlet name='additional-actions' />
<app-footer />
```

Cada outlet deve ter um nome único. O nome não pode ser definido ou alterado dinamicamente. Por padrão, o nome é `'primary'`.

O Angular corresponde o nome do outlet à propriedade `outlet` definida em cada route:

```ts
{
  path: 'user/:id',
  component: UserDetails,
  outlet: 'additional-actions'
}
```

## Eventos de ciclo de vida do outlet

Existem quatro eventos de ciclo de vida que um router outlet pode emitir:

| Event        | Description                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| `activate`   | Quando um novo component é instanciado                                     |
| `deactivate` | Quando um component é destruído                                            |
| `attach`     | Quando o `RouteReuseStrategy` instrui o outlet a anexar a subárvore        |
| `detach`     | Quando o `RouteReuseStrategy` instrui o outlet a desanexar a subárvore     |

Você pode adicionar event listeners com a sintaxe padrão de event binding:

```html
<router-outlet
  (activate)='onActivate($event)'
  (deactivate)='onDeactivate($event)'
  (attach)='onAttach($event)'
  (detach)='onDetach($event)'
/>
```

Confira a [documentação da API para RouterOutlet](/api/router/RouterOutlet?tab=api) se você quiser saber mais.

## Passando dados contextuais para components roteados

Passar dados contextuais para components roteados frequentemente requer estado global ou configurações de route complicadas. Para facilitar isso, cada `RouterOutlet` suporta um input `routerOutletData`. Components roteados e seus filhos podem ler esses dados como um signal usando o token de injeção `ROUTER_OUTLET_DATA`, permitindo configuração específica do outlet sem modificar definições de route.

```typescript
import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';

@Component({
  selector: 'app-dashboard',
  imports: [RouterOutlet],
  template: `
    <h2>Dashboard</h2>
    <router-outlet [routerOutletData]="{ layout: 'sidebar' }" />
  `,
})
export class DashboardComponent {}
```

O component roteado pode injetar os dados do outlet fornecidos usando `ROUTER_OUTLET_DATA`:

```typescript
import { Component, inject } from '@angular/core';
import { ROUTER_OUTLET_DATA } from '@angular/router';

@Component({
  selector: 'app-stats',
  template: `<p>Stats view (layout: {{ outletData().layout }})</p>`,
})
export class StatsComponent {
  outletData = inject(ROUTER_OUTLET_DATA) as Signal<{ layout: string }>;
}
```

Quando o Angular ativa o `StatsComponent` nesse outlet, ele recebe `{ layout: 'sidebar' }` como dados injetados.

NOTA: Quando o input `routerOutletData` não está definido, o valor injetado é null por padrão.

---

## Próximos passos

Aprenda como [navegar para routes](/guide/routing/navigate-to-routes) com o Angular Router.

# Navegar para routes

A directive RouterLink é a abordagem declarativa do Angular para navegação. Ela permite que você use elementos âncora padrão (`<a>`) que se integram perfeitamente ao sistema de routing do Angular.

## Como usar RouterLink

Em vez de usar elementos âncora regulares `<a>` com um atributo `href`, você adiciona uma directive RouterLink com o caminho apropriado para aproveitar o routing do Angular.

```typescript
import {RouterLink} from '@angular/router';
@Component({
  template: `
    <nav>
      <a routerLink="/user-profile">User profile</a>
      <a routerLink="/settings">Settings</a>
    </nav>
  `
  imports: [RouterLink],
  ...
})
export class App {}
```

### Usando links absolutos ou relativos

**URLs relativas** no routing do Angular permitem que você defina caminhos de navegação relativos à localização da route atual. Isso contrasta com **URLs absolutas**, que contêm o caminho completo com o protocolo (por exemplo, `http://`) e o **domínio raiz** (por exemplo, `google.com`).

```html

<a href="https://www.angular.dev/essentials">Angular Essentials Guide</a>

<a href="/essentials">Angular Essentials Guide</a>
```

Neste exemplo, o primeiro exemplo contém o caminho completo com o protocolo (ou seja, `https://`) e o domínio raiz (ou seja, `angular.dev`) explicitamente definidos para a página essentials. Em contraste, o segundo exemplo assume que o usuário já está no domínio raiz correto para `/essentials`.

De modo geral, URLs relativas são preferidas porque são mais fáceis de manter em aplicações, pois não precisam conhecer sua posição absoluta dentro da hierarquia de routing.

### Como funcionam as URLs relativas

O routing do Angular possui duas sintaxes para definir URLs relativas: strings e arrays.

```html

<a routerLink="dashboard">Dashboard</a>
<a [routerLink]="['dashboard']">Dashboard</a>
```

ÚTIL: Passar uma string é a maneira mais comum de definir URLs relativas.

Quando você precisa definir parâmetros dinâmicos em uma URL relativa, use a sintaxe de array:

```html
<a [routerLink]="['user', currentUserId]">Current User</a>
```

Além disso, o routing do Angular permite que você especifique se deseja que o caminho seja relativo à URL atual ou ao domínio raiz, com base em se o caminho relativo é prefixado com uma barra (`/`) ou não.

Por exemplo, se o usuário está em `example.com/settings`, veja como diferentes caminhos relativos podem ser definidos para vários cenários:

```html

<a routerLink="notifications">Notifications</a>
<a routerLink="/settings/notifications">Notifications</a>

<a routerLink="/team/123/user/456">User 456</a>
<a [routerLink]="['/team', teamId, 'user', userId]">Current User</a>"
```

## Navegação programática para routes

Enquanto o `RouterLink` lida com navegação declarativa em templates, o Angular fornece navegação programática para cenários onde você precisa navegar com base em lógica, ações do usuário ou estado da aplicação. Ao injetar o `Router`, você pode navegar dinamicamente para routes, passar parâmetros e controlar o comportamento de navegação no seu código TypeScript.

### `router.navigate()`

Você pode usar o método `router.navigate()` para navegar programaticamente entre routes especificando um array de caminhos de URL.

```typescript
import { Router } from '@angular/router';

@Component({
  selector: 'app-dashboard',
  template: `
    <button (click)="navigateToProfile()">View Profile</button>
  `
})
export class AppDashboard {
  private router = inject(Router);

navigateToProfile() {
    // Standard navigation
    this.router.navigate(['/profile']);

// With route parameters
    this.router.navigate(['/users', userId]);

// With query parameters
    this.router.navigate(['/search'], {
      queryParams: { category: 'books', sort: 'price' }
    });

// With matrix parameters
    this.router.navigate(['/products', { featured: true, onSale: true }]);
  }
}
```

O `router.navigate()` suporta cenários de routing simples e complexos, permitindo que você passe parâmetros de route, [query parameters](/guide/routing/read-route-state#query-parameters) e controle o comportamento de navegação.

Você também pode construir caminhos de navegação dinâmicos relativos à localização do seu component na árvore de routing usando a opção `relativeTo`.

```typescript
import { Router, ActivatedRoute } from '@angular/router';

@Component({
  selector: 'app-user-detail',
  template: `
    <button (click)="navigateToEdit()">Edit User</button>
    <button (click)="navigateToParent()">Back to List</button>
  `
})
export class UserDetailComponent {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

constructor() {}

// Navigate to a sibling route
  navigateToEdit() {
    // From: /users/123
    // To:   /users/123/edit
    this.router.navigate(['edit'], { relativeTo: this.route });
  }

// Navigate to parent
  navigateToParent() {
    // From: /users/123
    // To:   /users
    this.router.navigate(['..'], { relativeTo: this.route });
  }
}
```

### `router.navigateByUrl()`

O método `router.navigateByUrl()` fornece uma maneira direta de navegar programaticamente usando strings de caminho de URL em vez de segmentos de array. Este método é ideal quando você tem um caminho de URL completo e precisa realizar navegação absoluta, especialmente ao trabalhar com URLs fornecidas externamente ou cenários de deep linking.

```ts
// Standard route navigation
router.navigateByUrl('/products);

// Navigate to nested route
router.navigateByUrl('/products/featured');

// Complete URL with parameters and fragment
router.navigateByUrl('/products/123?view=details#reviews');

// Navigate with query parameters
router.navigateByUrl('/search?category=books&sortBy=price');

// With matrix parameters
router.navigateByUrl('/sales-awesome;isOffer=true;showModal=false')
```

No caso de você precisar substituir a URL atual no histórico, `navigateByUrl` também aceita um objeto de configuração que possui uma opção `replaceUrl`.

```ts
// Replace current URL in history
router.navigateByUrl('/checkout', {
  replaceUrl: true
});
```

## Próximos passos

Aprenda como [ler o estado da route](/guide/routing/read-route-state) para criar components responsivos e conscientes do contexto.

# Ler o estado da route

O Angular Router permite que você leia e use informações associadas a uma route para criar components responsivos e conscientes do contexto.

## Obter informações sobre a route atual com ActivatedRoute

`ActivatedRoute` é um service de `@angular/router` que fornece todas as informações associadas à route atual.

```typescript
import { Component } from '@angular/core';
import { ActivatedRoute } from '@angular/router';

@Component({
  selector: 'app-product',
})
export class ProductComponent {
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    console.log(this.activatedRoute);
  }
}
```

O `ActivatedRoute` pode fornecer diferentes informações sobre a route. Algumas propriedades comuns incluem:

| Property      | Details                                                                                                                                      |
| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`         | Um `Observable` dos caminhos da route, representados como um array de strings para cada parte do caminho da route.                          |
| `data`        | Um `Observable` que contém o objeto `data` fornecido para a route. Também contém quaisquer valores resolvidos do resolve guard.             |
| `params`      | Um `Observable` que contém os parâmetros obrigatórios e opcionais específicos da route.                                                     |
| `queryParams` | Um `Observable` que contém os query parameters disponíveis para todas as routes.                                                            |

Confira a [documentação da API `ActivatedRoute`](/api/router/ActivatedRoute) para uma lista completa do que você pode acessar na route.

## Entendendo snapshots de route

Navegações de página são eventos ao longo do tempo, e você pode acessar o estado do router em um determinado momento recuperando um snapshot da route.

Snapshots de route contêm informações essenciais sobre a route, incluindo seus parâmetros, dados e routes filhas. Além disso, snapshots são estáticos e não refletirão mudanças futuras.

Aqui está um exemplo de como você acessaria um snapshot de route:

```typescript
import { ActivatedRoute, ActivatedRouteSnapshot } from '@angular/router';

@Component({ ... })
export class UserProfileComponent {
  readonly userId: string;
  private route = inject(ActivatedRoute);

constructor() {
    // Example URL: https://www.angular.dev/users/123?role=admin&status=active#contact

// Access route parameters from snapshot
    this.userId = this.route.snapshot.paramMap.get('id');

// Access multiple route elements
    const snapshot = this.route.snapshot;
    console.log({
      url: snapshot.url,           // https://www.angular.dev
      // Route parameters object: {id: '123'}
      params: snapshot.params,
      // Query parameters object: {role: 'admin', status: 'active'}
      queryParams: snapshot.queryParams,  // Query parameters
    });
  }
}
```

Confira a [documentação da API `ActivatedRoute`](/api/router/ActivatedRoute) e a [documentação da API `ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) para uma lista completa de todas as propriedades que você pode acessar.

## Lendo parâmetros em uma route

Existem dois tipos de parâmetros que os desenvolvedores podem utilizar de uma route: parâmetros de route e query parameters.

### Parâmetros de Route

Parâmetros de route permitem que você passe dados para um component através da URL. Isso é útil quando você deseja exibir conteúdo específico com base em um identificador na URL, como um ID de usuário ou um ID de produto.

Você pode [definir parâmetros de route](/guide/routing/define-routes#define-url-paths-with-route-parameters) prefixando o nome do parâmetro com dois pontos (`:`).

```typescript
import { Routes } from '@angular/router';
import { ProductComponent } from './product/product.component';

const routes: Routes = [
  { path: 'product/:id', component: ProductComponent }
];
```

Você pode acessar parâmetros assinando `route.params`.

```typescript
import { Component, inject, signal } from '@angular/core';
import { ActivatedRoute } from '@angular/router';

@Component({
  selector: 'app-product-detail',
  template: `<h1>Product Details: {{ productId() }}</h1>`,
})
export class ProductDetailComponent {
  productId = signal('');
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    // Access route parameters
    this.activatedRoute.params.subscribe((params) => {
      this.productId.set(params['id']);
    });
  }
}
```

### Query Parameters

[Query parameters](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) fornecem uma maneira flexível de passar dados opcionais através de URLs sem afetar a estrutura da route. Diferentemente dos parâmetros de route, query parameters podem persistir entre eventos de navegação e são perfeitos para lidar com filtragem, ordenação, paginação e outros elementos de UI com estado.

```typescript
// Single parameter structure
// /products?category=electronics
router.navigate(['/products'], {
  queryParams: { category: 'electronics' }
});

// Multiple parameters
// /products?category=electronics&sort=price&page=1
router.navigate(['/products'], {
  queryParams: {
    category: 'electronics',
    sort: 'price',
    page: 1
  }
});
```

Você pode acessar query parameters com `route.queryParams`.

Aqui está um exemplo de um `ProductListComponent` que atualiza os query parameters que afetam como ele exibe uma lista de produtos:

```typescript
import { ActivatedRoute, Router } from '@angular/router';

@Component({
  selector: 'app-product-list',
  template: `
    <div>
      <select (change)="updateSort($event)">
        <option value="price">Price</option>
        <option value="name">Name</option>
      </select>
      
    </div>
  `
})
export class ProductListComponent implements OnInit {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

constructor() {
    // Access query parameters reactively
    this.route.queryParams.subscribe(params => {
      const sort = params['sort'] || 'price';
      const page = Number(params['page']) || 1;
      this.loadProducts(sort, page);
    });
  }

updateSort(event: Event) {
    const sort = (event.target as HTMLSelectElement).value;
    // Update URL with new query parameter
    this.router.navigate([], {
      queryParams: { sort },
      queryParamsHandling: 'merge' // Preserve other query parameters
    });
  }
}
```

Neste exemplo, os usuários podem usar um elemento select para ordenar a lista de produtos por nome ou preço. O manipulador de mudança associado atualiza os query parameters da URL, que por sua vez dispara um evento de mudança que pode ler os query parameters atualizados e atualizar a lista de produtos.

Para mais informações, confira a [documentação oficial sobre QueryParamsHandling](/api/router/QueryParamsHandling).

### Matrix Parameters

Matrix parameters são parâmetros opcionais que pertencem a um segmento de URL específico, em vez de se aplicarem a toda a route. Diferentemente dos query parameters que aparecem depois de um `?` e se aplicam globalmente, matrix parameters usam ponto e vírgula (`;`) e têm escopo para segmentos de caminho individuais.

Matrix parameters são úteis quando você precisa passar dados auxiliares para um segmento de route específico sem afetar a definição da route ou o comportamento de correspondência. Assim como os query parameters, eles não precisam ser definidos na sua configuração de route.

```ts
// URL format: /path;key=value
// Multiple parameters: /path;key1=value1;key2=value2

// Navigate with matrix parameters
this.router.navigate(['/awesome-products', { view: 'grid', filter: 'new' }]);
// Results in URL: /awesome-products;view=grid;filter=new
```

**Usando ActivatedRoute**

```ts
import { Component, inject } from '@angular/core';
import { ActivatedRoute } from '@angular/router';

@Component(/* ... */)
export class AwesomeProducts  {
  private route = inject(ActivatedRoute);

constructor() {
    // Access matrix parameters via params
    this.route.params.subscribe((params) => {
      const view = params['view']; // e.g., 'grid'
      const filter = params['filter']; // e.g., 'new'
    });
  }
}
```

NOTA: Como alternativa ao uso de `ActivatedRoute`, matrix parameters também são vinculados a inputs de component ao usar o `withComponentInputBinding`.

## Detectar a route ativa atual com RouterLinkActive

Você pode usar a directive `RouterLinkActive` para estilizar dinamicamente elementos de navegação com base na route ativa atual. Isso é comum em elementos de navegação para informar aos usuários qual é a route ativa.

```html
<nav>
  <a class="button"
     routerLink="/about"
     routerLinkActive="active-button"
     ariaCurrentWhenActive="page">
    About
  </a> |
  <a class="button"
     routerLink="/settings"
     routerLinkActive="active-button"
     ariaCurrentWhenActive="page">
    Settings
  </a>
</nav>
```

Neste exemplo, o Angular Router aplicará a classe `active-button` ao link âncora correto e `ariaCurrentWhenActive` como `page` quando a URL corresponder ao `routerLink` correspondente.

Se você precisar adicionar várias classes ao elemento, você pode usar uma string separada por espaços ou um array:

```html

<a routerLink="/user/bob" routerLinkActive="class1 class2">Bob</a>

<a routerLink="/user/bob" [routerLinkActive]="['class1', 'class2']">Bob</a>
```

Quando você especifica um valor para routerLinkActive, você também está definindo o mesmo valor para `ariaCurrentWhenActive`. Isso garante que usuários com deficiência visual (que podem não perceber a estilização diferente sendo aplicada) também possam identificar o botão ativo.

Se você quiser definir um valor diferente para aria, você precisará definir explicitamente o valor usando a directive `ariaCurrentWhenActive`.

### Estratégia de correspondência de route

Por padrão, `RouterLinkActive` considera quaisquer ancestrais na route como uma correspondência.

```html
<a [routerLink]="['/user/jane']" routerLinkActive="active-link">
  User
</a>
<a [routerLink]="['/user/jane/role/admin']" routerLinkActive="active-link">
  Role
</a>
```

Quando o usuário visita `/user/jane/role/admin`, ambos os links teriam a classe `active-link`.

### Aplicar RouterLinkActive apenas em correspondências exatas de route

Se você quiser aplicar a classe apenas em uma correspondência exata, você precisa fornecer a directive `routerLinkActiveOptions` com um objeto de configuração que contém o valor `exact: true`.

```html
<a [routerLink]="['/user/jane']"
  routerLinkActive="active-link"
  [routerLinkActiveOptions]="{exact: true}"
>
  User
</a>
<a [routerLink]="['/user/jane/role/admin']"
  routerLinkActive="active-link"
  [routerLinkActiveOptions]="{exact: true}"
>
  Role
</a>
```

Se você quiser ser mais preciso em como uma route é correspondida, vale a pena notar que `exact: true` é na verdade açúcar sintático para o conjunto completo de opções de correspondência:

```typescript
// `exact: true` is equivalent to
{
  paths: 'exact',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'exact',
}

// `exact: false` is equivalent
{
  paths: 'subset',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'subset',
}
```

Para mais informações, confira a documentação oficial para [isActiveMatchOptions](/api/router/IsActiveMatchOptions).

### Aplicar RouterLinkActive a um ancestral

A directive RouterLinkActive também pode ser aplicada a um elemento ancestral para permitir que os desenvolvedores estilizem os elementos conforme desejado.

```html
<div routerLinkActive="active-link" [routerLinkActiveOptions]="{exact: true}">
  <a routerLink="/user/jim">Jim</a>
  <a routerLink="/user/bob">Bob</a>
</div>
```

Para mais informações, confira a [documentação da API para RouterLinkActive](/api/router/RouterLinkActive).

# Outras Tarefas Comuns de Routing

Este guia cobre algumas outras tarefas comuns associadas ao uso do Angular router na sua aplicação.

## Obtendo informações de route

Frequentemente, quando um usuário navega pela sua aplicação, você quer passar informações de um component para outro.
Por exemplo, considere uma aplicação que exibe uma lista de compras de itens de mercado.
Cada item na lista tem um `id` único.
Para editar um item, os usuários clicam em um botão Edit, que abre um component `EditGroceryItem`.
Você quer que esse component recupere o `id` do item de mercado para que ele possa exibir as informações corretas para o usuário.

Use uma route para passar este tipo de informação para os components da sua aplicação.
Para fazer isso, você usa o recurso `withComponentInputBinding` com `provideRouter` ou a opção `bindToComponentInputs` de `RouterModule.forRoot`.

Para obter informações de uma route:

<docs-workflow>

<docs-step title="Adicione `withComponentInputBinding`">

Adicione o recurso `withComponentInputBinding` ao método `provideRouter`.

```ts
providers: [
  provideRouter(appRoutes, withComponentInputBinding()),
]
```

</docs-step>

<docs-step title="Adicione um `input` ao component">

Atualize o component para ter uma propriedade `input()` correspondente ao nome do parâmetro.

```ts
id = input.required<string>()
hero = computed(() => this.service.getHero(id()));
```

</docs-step>
<docs-step title="Opcional: Use um valor padrão">
O router atribui valores a todos os inputs com base na route atual quando `withComponentInputBinding` está habilitado.
O router atribui `undefined` se nenhum dado de route corresponder à chave do input, como quando um parâmetro de query opcional está ausente.
Você deve incluir `undefined` no tipo do `input` quando houver a possibilidade de que um input possa não ser correspondido pela route.

Forneça um valor padrão usando a opção `transform` no input ou gerenciando um estado local com um `linkedSignal`.

```ts
id = input.required({
  transform: (maybeUndefined: string | undefined) => maybeUndefined ?? '0',
});
// or
id = input<string|undefined>();
internalId = linkedSignal(() => this.id() ?? getDefaultId());
```

</docs-step>
</docs-workflow>

NOTA: Você pode vincular todos os dados de route com pares chave-valor aos inputs do component: dados de route estáticos ou resolvidos, parâmetros de path, parâmetros de matriz e parâmetros de query.
Se você quiser usar as informações de route dos components pais, você precisará configurar a opção `paramsInheritanceStrategy` do router:
`withRouterConfig({paramsInheritanceStrategy: 'always'})`. Veja [opções de configuração do router](guide/routing/customizing-route-behavior#router-configuration-options) para detalhes sobre outras configurações disponíveis.

## Exibindo uma página 404

Para exibir uma página 404, configure uma [route wildcard](guide/routing/common-router-tasks#setting-up-wildcard-routes) com a propriedade `component` definida para o component que você gostaria de usar para sua página 404 da seguinte forma:

```ts
const routes: Routes = [
  { path: 'first-component', component: FirstComponent },
  { path: 'second-component', component: SecondComponent },
  { path: '**', component: PageNotFoundComponent },  // Wildcard route for a 404 page
];
```

A última route com o `path` de `**` é uma route wildcard.
O router seleciona esta route se a URL solicitada não corresponder a nenhum dos paths anteriores na lista e envia o usuário para o `PageNotFoundComponent`.

## Array de parâmetros de link

Um array de parâmetros de link contém os seguintes ingredientes para navegação do router:

- O path da route para o component de destino
- Parâmetros de route obrigatórios e opcionais que vão para a URL da route

Vincule a diretiva `RouterLink` a tal array assim:

```html
<a [routerLink]="['/heroes']">Heroes</a>
```

O seguinte é um array de dois elementos ao especificar um parâmetro de route:

```html
<a [routerLink]="['/hero', hero.id]">
  <span class="badge">{{ hero.id }}</span>{{ hero.name }}
</a>
```

Forneça parâmetros de route opcionais em um object, como em `{ foo: 'foo' }`:

```html
<a [routerLink]="['/crisis-center', { foo: 'foo' }]">Crisis Center</a>
```

Esta sintaxe passa parâmetros de matriz, que são parâmetros opcionais associados a um segmento de URL específico. Saiba mais sobre [parâmetros de matriz](/guide/routing/read-route-state#matrix-parameters).

Estes três exemplos cobrem as necessidades de uma aplicação com um nível de routing.
No entanto, com um router filho, como no crisis center, você cria novas possibilidades de array de link.

O seguinte exemplo mínimo de `RouterLink` baseia-se em uma route filho padrão especificada para o crisis center.

```html
<a [routerLink]="['/crisis-center']">Crisis Center</a>
```

Revise o seguinte:

- O primeiro item no array identifica a route pai $`/crisis-center`$
- Não há parâmetros para esta route pai
- Não há padrão para a route filho, então você precisa escolher uma
- Você está navegando para o `CrisisListComponent`, cujo path de route é `/`, mas você não precisa adicionar a barra explicitamente

Considere o seguinte link de router que navega da raiz da aplicação até a Dragon Crisis:

```html
<a [routerLink]="['/crisis-center', 1]">Dragon Crisis</a>
```

- O primeiro item no array identifica a route pai $`/crisis-center`$
- Não há parâmetros para esta route pai
- O segundo item identifica os detalhes da route filho sobre uma crise específica $`/:id`$
- A route filho de detalhes requer um parâmetro de route `id`
- Você adicionou o `id` da Dragon Crisis como o segundo item no array $`1`$
- O path resultante é `/crisis-center/1`

Você também pode redefinir o template `AppComponent` com routes do Crisis Center exclusivamente:

```typescript
@Component({
  template: `
    <h1 class="title">Angular Router</h1>
    <nav>
      <a [routerLink]="['/crisis-center']">Crisis Center</a>
      <a [routerLink]="['/crisis-center/1', { foo: 'foo' }]">Dragon Crisis</a>
      <a [routerLink]="['/crisis-center/2']">Shark Crisis</a>
    </nav>
    <router-outlet />
  `
})
export class AppComponent {}
```

Em resumo, você pode escrever aplicações com um, dois ou mais níveis de routing.
O array de parâmetros de link oferece a flexibilidade para representar qualquer profundidade de routing e qualquer sequência legal de paths de route, parâmetros de router $obrigatórios$ e objects de parâmetro de route $opcionais$.

## `LocationStrategy` e estilos de URL do browser

Quando o router navega para uma nova view de component, ele atualiza a location e o histórico do browser com uma URL para essa view.

Browsers HTML5 modernos suportam [history.pushState](https://developer.mozilla.org/docs/Web/API/History_API/Working_with_the_History_API#adding_and_modifying_history_entries 'HTML5 browser history push-state'), uma técnica que altera a location e o histórico de um browser sem acionar uma requisição de página ao servidor.
O router pode compor uma URL "natural" que é indistinguível de uma que, de outra forma, exigiria um carregamento de página.

Aqui está a URL do Crisis Center neste estilo "HTML5 pushState":

```text
localhost:3002/crisis-center
```

Browsers mais antigos enviam requisições de página ao servidor quando a URL de location muda, a menos que a mudança ocorra após um "#" $chamado de "hash"$.
Routers podem aproveitar esta exceção compondo URLs de route dentro da aplicação com hashes.
Aqui está uma "hash URL" que direciona para o Crisis Center.

```text
localhost:3002/src/#/crisis-center
```

O router suporta ambos os estilos com dois providers `LocationStrategy`:

A função `RouterModule.forRoot()` define a `LocationStrategy` para a `PathLocationStrategy`, o que a torna a estratégia padrão.
Você também tem a opção de mudar para a `HashLocationStrategy` com uma substituição durante o processo de bootstrapping.

ÚTIL: Para mais informações sobre providers e o processo de bootstrap, veja [Dependency Injection](guide/di/dependency-injection-providers).

# Usando rotas Angular em uma aplicação de página única

Este tutorial descreve como construir uma aplicação de página única, SPA, que usa múltiplas rotas Angular.

Em uma Aplicação de Página Única $SPA$, todas as funções de sua aplicação existem em uma única página HTML.
Conforme os usuários acessam as funcionalidades de sua aplicação, o navegador precisa renderizar apenas as partes que importam para o usuário, em vez de carregar uma nova página.
Este padrão pode melhorar significativamente a experiência do usuário de sua aplicação.

Para definir como os usuários navegam através de sua aplicação, você usa rotas.
Adicione rotas para definir como os usuários navegam de uma parte de sua aplicação para outra.
Você também pode configurar rotas para proteger contra comportamento inesperado ou não autorizado.

## Objetivos

- Organizar as funcionalidades de uma aplicação de exemplo em módulos.
- Definir como navegar para um component.
- Passar informações para um component usando um parâmetro.
- Estruturar rotas aninhando várias rotas.
- Verificar se os usuários podem acessar uma rota.
- Controlar se a aplicação pode descartar mudanças não salvas.
- Melhorar a performance pré-buscando dados de rotas e fazendo lazy loading de módulos de funcionalidade.
- Exigir critérios específicos para carregar componentes.

## Criar uma aplicação de exemplo

Usando o Angular CLI, crie uma nova aplicação, _angular-router-sample_.
Esta aplicação terá dois componentes: _crisis-list_ e _heroes-list_.

1. Crie um novo projeto Angular, _angular-router-sample_.

```shell
ng new angular-router-sample
```
   Quando perguntado com `Would you like to add Angular routing?`, selecione `N`.

Quando perguntado com `Which stylesheet format would you like to use?`, selecione `CSS`.

Após alguns momentos, um novo projeto, `angular-router-sample`, está pronto.

1. Do seu terminal, navegue para o diretório `angular-router-sample`.
1. Crie um component, _crisis-list_.

```shell
ng generate component crisis-list
```
1. No seu editor de código, localize o arquivo, `crisis-list.component.html` e substitua o conteúdo placeholder pelo seguinte HTML.

```
1. Crie um segundo component, _heroes-list_.

<docs-code language="shell">
ng generate component heroes-list
```
1. No seu editor de código, localize o arquivo, `heroes-list.component.html` e substitua o conteúdo placeholder pelo seguinte HTML.

```
1. No seu editor de código, abra o arquivo, `app.component.html` e substitua seus conteúdos pelo seguinte HTML.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="setup"/>

1. Verifique se sua nova aplicação funciona como esperado executando o comando `ng serve`.

<docs-code language="shell">
ng serve
```
1. Abra um navegador em `http://localhost:4200`.

Você deve ver uma única página web, consistindo de um título e o HTML de seus dois componentes.

## Defina suas rotas

Nesta seção, você definirá duas rotas:

- A rota `/crisis-center` abre o component `crisis-center`.
- A rota `/heroes-list` abre o component `heroes-list`.

Uma definição de rota é um objeto JavaScript.
Cada rota tipicamente tem duas propriedades.
A primeira propriedade, `path`, é uma string que especifica o caminho da URL para a rota.
A segunda propriedade, `component`, é uma string que especifica qual component sua aplicação deve exibir para aquele caminho.

1. Do seu editor de código, crie e abra o arquivo `app.routes.ts`.
1. Crie e exporte uma lista de rotas para sua aplicação:

```ts
import {Routes} from '@angular/router';

export const routes = [];
   ```

1. Adicione duas rotas para seus dois primeiros componentes:

```ts
{path: 'crisis-list', component: CrisisListComponent},
   {path: 'heroes-list', component: HeroesListComponent},
   ```

Esta lista de rotas é um array de objetos JavaScript, com cada objeto definindo as propriedades de uma rota.

## Importar `provideRouter` de `@angular/router`

Routing permite que você exiba views específicas de sua aplicação dependendo do caminho da URL.
Para adicionar esta funcionalidade à sua aplicação de exemplo, você precisa atualizar o arquivo `app.config.ts` para usar a função de providers do router, `provideRouter`.
Você importa esta função de provider de `@angular/router`.

1. Do seu editor de código, abra o arquivo `app.config.ts`.
1. Adicione as seguintes declarações de import:

```ts
import { provideRouter } from '@angular/router';
   import { routes } from './app.routes';
   ```

1. Atualize os providers no `appConfig`:

```ts
providers: [provideRouter(routes)]
   ```

Para aplicações baseadas em `NgModule`, coloque o `provideRouter` na lista `providers` do `AppModule`, ou qualquer módulo que seja passado para `bootstrapModule` na aplicação.

## Atualize seu component com `router-outlet`

Neste ponto, você definiu duas rotas para sua aplicação.
Contudo, sua aplicação ainda tem ambos os componentes `crisis-list` e `heroes-list` codificados diretamente no seu template `app.component.html`.
Para que suas rotas funcionem, você precisa atualizar seu template para carregar dinamicamente um component baseado no caminho da URL.

Para implementar esta funcionalidade, você adiciona a directive `router-outlet` ao seu arquivo de template.

1. Do seu editor de código, abra o arquivo `app.component.html`.
1. Delete as seguintes linhas.

```
1. Adicione a directive `router-outlet`.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="router-outlet"/>

1. Adicione `RouterOutlet` aos imports do `AppComponent` em `app.component.ts`

```ts
imports: [RouterOutlet],
   ```

Visualize sua aplicação atualizada no seu navegador.
Você deve ver apenas o título da aplicação.
Para visualizar o component `crisis-list`, adicione `crisis-list` ao final do caminho na barra de endereços do seu navegador.
Por exemplo:

<docs-code language="http">
http://localhost:4200/crisis-list
```
Observe que o component `crisis-list` é exibido.
O Angular está usando a rota que você definiu para carregar dinamicamente o component.
Você pode carregar o component `heroes-list` da mesma forma:

```http
http://localhost:4200/heroes-list
```
## Controlar navegação com elementos de UI

Atualmente, sua aplicação suporta duas rotas.
Contudo, a única forma de usar essas rotas é o usuário digitar manualmente o caminho na barra de endereços do navegador.
Nesta seção, você adicionará dois links nos quais os usuários podem clicar para navegar entre os componentes `heroes-list` e `crisis-list`.
Você também adicionará alguns estilos CSS.
Embora esses estilos não sejam obrigatórios, eles facilitam identificar o link para o component atualmente exibido.
Você adicionará essa funcionalidade na próxima seção.

1. Abra o arquivo `app.component.html` e adicione o seguinte HTML abaixo do título.

```
Este HTML usa uma directive Angular, `routerLink`.
   Esta directive conecta as rotas que você definiu aos seus arquivos de template.

1. Adicione a directive `RouterLink` à lista de imports de `AppComponent` em `app.component.ts`.

1. Abra o arquivo `app.component.css` e adicione os seguintes estilos.

<docs-code header="src/app/app.component.css" path="adev/src/content/examples/router-tutorial/src/app/app.component.css"/>

Se você visualizar sua aplicação no navegador, deverá ver esses dois links.
Quando você clica em um link, o component correspondente aparece.

## Identificar a rota ativa

Embora os usuários possam navegar sua aplicação usando os links que você adicionou na seção anterior, eles não têm uma forma direta de identificar qual é a rota ativa.
Adicione esta funcionalidade usando a directive `routerLinkActive` do Angular.

1. Do seu editor de código, abra o arquivo `app.component.html`.
1. Atualize as tags âncora para incluir a directive `routerLinkActive`.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="routeractivelink"/>

1. Adicione a directive `RouterLinkActive` à lista de `imports` de `AppComponent` em `app.component.ts`.

Visualize sua aplicação novamente.
Conforme você clica em um dos botões, o estilo para aquele botão atualiza automaticamente, identificando o component ativo para o usuário.
Ao adicionar a directive `routerLinkActive`, você informa sua aplicação para aplicar uma classe CSS específica à rota ativa.
Neste tutorial, essa classe CSS é `activebutton`, mas você poderia usar qualquer classe que quiser.

Note que também estamos especificando um valor para o `ariaCurrentWhenActive` do `routerLinkActive`. Isso garante que usuários com deficiência visual (que podem não perceber o estilo diferente sendo aplicado) também possam identificar o botão ativo. Para mais informações veja as Boas Práticas de Acessibilidade [seção de identificação de links ativos](/best-practices/a11y#active-links-identification).

## Adicionando um redirect

Nesta etapa do tutorial, você adiciona uma rota que redireciona o usuário para exibir o component `/heroes-list`.

1. Do seu editor de código, abra o arquivo `app.routes.ts`.
1. Atualize a seção `routes` como a seguir.

```ts
{path: '', redirectTo: '/heroes-list', pathMatch: 'full'},
   ```

Observe que esta nova rota usa uma string vazia como seu caminho.
   Além disso, ela substitui a propriedade `component` por duas novas:

| Propriedades | Detalhes                                                                                                                                                                                                                                                                                           |
   | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
   | `redirectTo` | Esta propriedade instrui o Angular a redirecionar de um caminho vazio para o caminho `heroes-list`.                                                                                                                                                                                                         |
   | `pathMatch`  | Esta propriedade instrui o Angular sobre quanto da URL corresponder. Para este tutorial, você deve definir esta propriedade como `full`. Esta estratégia é recomendada quando você tem uma string vazia para um caminho. Para mais informações sobre esta propriedade, veja a [documentação da API Route](api/router/Route). |

Agora quando você abre sua aplicação, ela exibe o component `heroes-list` por padrão.

## Adicionando uma página 404

É possível que um usuário tente acessar uma rota que você não definiu.
Para contabilizar este comportamento, a melhor prática é exibir uma página 404.
Nesta seção, você criará uma página 404 e atualizará sua configuração de rotas para mostrar aquela página para quaisquer rotas não especificadas.

1. Do terminal, crie um novo component, `PageNotFound`.

<docs-code language="shell">
ng generate component page-not-found
```
1. Do seu editor de código, abra o arquivo `page-not-found.component.html` e substitua seus conteúdos pelo seguinte HTML.

<docs-code header="src/app/page-not-found/page-not-found.component.html" path="adev/src/content/examples/router-tutorial/src/app/page-not-found/page-not-found.component.html"/>

1. Abra o arquivo `app.routes.ts` e adicione a seguinte rota à lista de rotas:

```ts
{path: '**', component: PageNotFoundComponent}
   ```

A nova rota usa um caminho, `**`.
   Este caminho é como o Angular identifica uma rota wildcard.
   Qualquer rota que não corresponda a uma rota existente em sua configuração usará esta rota.

IMPORTANTE: Observe que a rota wildcard é colocada no final do array.
A ordem de suas rotas é importante, pois o Angular aplica rotas em ordem e usa a primeira correspondência que encontrar.

Tente navegar para uma rota não existente em sua aplicação, como `http://localhost:4200/powers`.
Esta rota não corresponde a nada definido em seu arquivo `app.routes.ts`.
Contudo, porque você definiu uma rota wildcard, a aplicação automaticamente exibe seu component `PageNotFound`.

## Próximos passos

Neste ponto, você tem uma aplicação básica que usa a funcionalidade de routing do Angular para mudar quais componentes o usuário pode ver baseado no endereço da URL.
Você estendeu essas funcionalidades para incluir um redirect, bem como uma rota wildcard para exibir uma página 404 customizada.

Para mais informações sobre routing, veja os seguintes tópicos:

# Criando correspondências de rotas customizadas

O Angular Router suporta uma estratégia de correspondência poderosa que você pode usar para ajudar usuários a navegar em sua aplicação.
Esta estratégia de correspondência suporta rotas estáticas, rotas variáveis com parâmetros, rotas wildcard e assim por diante.
Além disso, construa seu próprio padrão de correspondência customizado para situações nas quais as URLs são mais complicadas.

Neste tutorial, você construirá um custom route matcher usando o `UrlMatcher` do Angular.
Este matcher procura por um handle do Twitter na URL.

## Objetivos

Implementar o `UrlMatcher` do Angular para criar um custom route matcher.

## Criar uma aplicação de exemplo

Usando o Angular CLI, crie uma nova aplicação, _angular-custom-route-match_.
Além do framework padrão de aplicação Angular, você também criará um component _profile_.

1. Crie um novo projeto Angular, _angular-custom-route-match_.

```shell
ng new angular-custom-route-match
   ```

Quando perguntado com `Would you like to add Angular routing?`, selecione `Y`.

Quando perguntado com `Which stylesheet format would you like to use?`, selecione `CSS`.

Após alguns momentos, um novo projeto, `angular-custom-route-match`, está pronto.

1. Do seu terminal, navegue para o diretório `angular-custom-route-match`.
1. Crie um component, _profile_.

```shell
ng generate component profile
   ```

1. No seu editor de código, localize o arquivo, `profile.component.html` e substitua o conteúdo placeholder pelo seguinte HTML.

<docs-code header="src/app/profile/profile.component.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/profile/profile.component.html"/>

1. No seu editor de código, localize o arquivo, `app.component.html` e substitua o conteúdo placeholder pelo seguinte HTML.

<docs-code header="src/app/app.component.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.component.html"/>

## Configure suas rotas para sua aplicação

Com o framework de sua aplicação no lugar, você precisa adicionar capacidades de routing ao arquivo `app.config.ts`.
Como parte deste processo, você criará um URL matcher customizado que procura por um handle do Twitter na URL.
Este handle é identificado por um símbolo `@` precedente.

1. No seu editor de código, abra seu arquivo `app.config.ts`.
1. Adicione uma declaração `import` para `provideRouter` e `withComponentInputBinding` do Angular bem como as rotas da aplicação.

```ts
import {provideRouter, withComponentInputBinding} from '@angular/router';

import {routes} from './app.routes';
   ```

1. No array de providers, adicione uma declaração `provideRouter(routes, withComponentInputBinding())`.

1. Defina o custom route matcher adicionando o seguinte código às rotas da aplicação.

<docs-code header="src/app/app.routes.ts" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.routes.ts" visibleRegion="matcher"/>

Este custom matcher é uma função que executa as seguintes tarefas:

- O matcher verifica se o array contém apenas um segmento
- O matcher emprega uma expressão regular para garantir que o formato do username seja uma correspondência
- Se houver uma correspondência, a função retorna a URL inteira, definindo um parâmetro de rota `username` como uma substring do caminho
- Se não houver correspondência, a função retorna null e o router continua a procurar por outras rotas que correspondam à URL

DICA: Um custom URL matcher se comporta como qualquer outra definição de rota. Defina rotas filhas ou rotas lazy loaded como você faria com qualquer outra rota.

## Lendo os parâmetros de rota

Com o custom matcher no lugar, você agora pode vincular o parâmetro de rota no component `profile`.

No seu editor de código, abra seu arquivo `profile.component.ts` e crie um `input` correspondente ao parâmetro `username`.
Adicionamos a feature `withComponentInputBinding` anteriormente
no `provideRouter`. Isso permite ao `Router` vincular informações diretamente aos route components.

```ts
username = input.required<string>();
```

## Teste seu custom URL matcher

Com seu código no lugar, você agora pode testar seu custom URL matcher.

1. De uma janela de terminal, execute o comando `ng serve`.

```shell
ng serve
   ```

1. Abra um navegador em `http://localhost:4200`.

Você deve ver uma única página web, consistindo de uma frase que diz `Navigate to my profile`.

1. Clique no hyperlink **my profile**.

Uma nova frase, dizendo `Hello, Angular!` aparece na página.

## Próximos passos

Correspondência de padrões com o Angular Router fornece muita flexibilidade quando você tem URLs dinâmicas em sua aplicação.
Para saber mais sobre o Angular Router, veja os seguintes tópicos:
DICA: Este conteúdo é baseado em [Custom Route Matching with the Angular Router](https://medium.com/@brandontroberts/custom-route-matching-with-the-angular-router-fbdd48665483), por [Brandon Roberts](https://twitter.com/brandontroberts).

# Renderização server e hybrid

O Angular entrega todas as aplicações como client-side rendered (CSR) por padrão. Embora essa abordagem forneça um payload inicial leve, ela introduz trade-offs incluindo tempos de carregamento mais lentos, métricas de desempenho degradadas e maiores demandas de recursos, já que o dispositivo do usuário executa a maioria dos cálculos. Como resultado, muitas aplicações alcançam melhorias significativas de desempenho ao integrar server-side rendering (SSR) em uma estratégia de hybrid rendering.

## O que é hybrid rendering?

Hybrid rendering permite que desenvolvedores aproveitem os benefícios de server-side rendering (SSR), pré-renderização (também conhecida como "static site generation" ou SSG) e client-side rendering (CSR) para otimizar sua aplicação Angular. Isso dá a você controle refinado sobre como as diferentes partes da sua aplicação são renderizadas para dar aos seus usuários a melhor experiência possível.

## Configurando hybrid rendering

Você pode criar um **novo** projeto com hybrid rendering usando a flag server-side rendering (ou seja, `--ssr`) com o comando `ng new` do Angular CLI:

```shell
ng new --ssr
```

Você também pode habilitar hybrid rendering adicionando server-side rendering a um projeto existente com o comando `ng add`:

```shell
ng add @angular/ssr
```

NOTE: Por padrão, o Angular pré-renderiza toda a sua aplicação e gera um arquivo de servidor. Para desabilitar isso e criar uma aplicação totalmente estática, defina `outputMode` como `static`. Para habilitar SSR, atualize as rotas do servidor para usar `RenderMode.Server`. Para mais detalhes, consulte [`Server routing`](#server-routing) e [`Generate a fully static application`](#generate-a-fully-static-application).

## Server routing

### Configurando rotas de servidor

Você pode criar uma configuração de rota de servidor declarando um array de objetos [`ServerRoute`](api/ssr/ServerRoute 'API reference'). Esta configuração normalmente fica em um arquivo chamado `app.routes.server.ts`.

```typescript
// app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: '', // Isso renderiza a rota "/" no cliente (CSR)
    renderMode: RenderMode.Client,
  },
  {
    path: 'about', // Esta página é estática, então nós pré-renderizamos (SSG)
    renderMode: RenderMode.Prerender,
  },
  {
    path: 'profile', // Esta página requer dados específicos do usuário, então usamos SSR
    renderMode: RenderMode.Server,
  },
  {
    path: '**', // Todas as outras rotas serão renderizadas no servidor (SSR)
    renderMode: RenderMode.Server,
  },
];
```

Você pode adicionar essa configuração à sua aplicação com [`provideServerRendering`](api/ssr/provideServerRendering 'API reference') usando a função [`withRoutes`](api/ssr/withRoutes 'API reference'):

```typescript
import { provideServerRendering, withRoutes } from '@angular/ssr';
import { serverRoutes } from './app.routes.server';

// app.config.server.ts
const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes)),
    // ... outros providers ...
  ]
};
```

Ao usar o [App shell pattern](ecosystem/service-workers/app-shell), você deve especificar o component a ser usado como app shell para rotas renderizadas client-side. Para fazer isso, use a feature [`withAppShell`](api/ssr/withAppShell 'API reference'):

```typescript
import { provideServerRendering, withRoutes, withAppShell } from '@angular/ssr';
import { AppShellComponent } from './app-shell/app-shell.component';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(
      withRoutes(serverRoutes),
      withAppShell(AppShellComponent),
    ),
    // ... outros providers ...
  ]
};
```

### Modos de renderização

A configuração de server routing permite que você especifique como cada rota na sua aplicação deve renderizar definindo um [`RenderMode`](api/ssr/RenderMode 'API reference'):

| Modo de renderização | Descrição                                                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Server (SSR)**     | Renderiza a aplicação no servidor para cada requisição, enviando uma página HTML totalmente populada ao navegador. |
| **Client (CSR)**     | Renderiza a aplicação no navegador. Este é o comportamento padrão do Angular.                                      |
| **Prerender (SSG)**  | Pré-renderiza a aplicação em build time, gerando arquivos HTML estáticos para cada rota.                           |

#### Escolhendo um modo de renderização

Cada modo de renderização tem diferentes benefícios e desvantagens. Você pode escolher modos de renderização baseados nas necessidades específicas da sua aplicação.

##### Client-side rendering (CSR)

Client-side rendering tem o modelo de desenvolvimento mais simples, já que você pode escrever código que assume que sempre executa em um navegador web. Isso permite que você use uma ampla gama de bibliotecas client-side que também assumem que executam em um navegador.

Client-side rendering geralmente tem pior desempenho do que outros modos de renderização, pois deve baixar, analisar e executar o JavaScript da sua página antes que o usuário possa ver qualquer conteúdo renderizado. Se sua página busca mais dados do servidor enquanto renderiza, os usuários também têm que esperar por essas requisições adicionais antes que possam visualizar o conteúdo completo.

Se sua página é indexada por rastreadores de busca, client-side rendering pode afetar negativamente a otimização para mecanismos de busca (SEO), já que rastreadores de busca têm limites de quanto JavaScript eles executam ao indexar uma página.

Ao usar client-side rendering, o servidor não precisa fazer nenhum trabalho para renderizar uma página além de servir assets JavaScript estáticos. Você pode considerar esse fator se o custo do servidor é uma preocupação.

Aplicações que suportam experiências instaláveis e offline com [service workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) podem depender de client-side rendering sem precisar se comunicar com um servidor.

##### Server-side rendering (SSR)

Server-side rendering oferece carregamentos de página mais rápidos do que client-side rendering. Em vez de esperar que o JavaScript baixe e execute, o servidor renderiza diretamente um documento HTML ao receber uma requisição do navegador. O usuário experimenta apenas a latência necessária para o servidor buscar dados e renderizar a página solicitada. Este modo também elimina a necessidade de requisições de rede adicionais do navegador, já que seu código pode buscar dados durante a renderização no servidor.

Server-side rendering geralmente tem excelente otimização para mecanismos de busca (SEO), já que rastreadores de busca recebem um documento HTML totalmente renderizado.

Server-side rendering requer que você escreva código que não dependa estritamente de APIs do navegador e limita sua seleção de bibliotecas JavaScript que assumem que executam em um navegador.

Ao usar server-side rendering, seu servidor executa Angular para produzir uma resposta HTML para cada requisição, o que pode aumentar os custos de hospedagem do servidor.

##### Pré-renderização em build-time

Pré-renderização oferece carregamentos de página mais rápidos do que tanto client-side rendering quanto server-side rendering. Como a pré-renderização cria documentos HTML em _build-time_, o servidor pode responder diretamente a requisições com o documento HTML estático sem nenhum trabalho adicional.

Pré-renderização requer que todas as informações necessárias para renderizar uma página estejam disponíveis em _build-time_. Isso significa que páginas pré-renderizadas não podem incluir quaisquer dados específicos do usuário que está carregando a página. Pré-renderização é principalmente útil para páginas que são as mesmas para todos os usuários da sua aplicação.

Como a pré-renderização ocorre em build-time, ela pode adicionar tempo significativo aos seus builds de produção. Usar [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') para produzir um grande número de documentos HTML pode afetar o tamanho total do arquivo dos seus deployments, e assim levar a deployments mais lentos.

Pré-renderização geralmente tem excelente otimização para mecanismos de busca (SEO), já que rastreadores de busca recebem um documento HTML totalmente renderizado.

Pré-renderização requer que você escreva código que não dependa estritamente de APIs do navegador e limita sua seleção de bibliotecas JavaScript que assumem que executam em um navegador.

Pré-renderização incorre em sobrecarga extremamente pequena por requisição de servidor, já que seu servidor responde com documentos HTML estáticos. Arquivos estáticos também são facilmente armazenados em cache por Content Delivery Networks (CDNs), navegadores e camadas de cache intermediárias para carregamentos de página subsequentes ainda mais rápidos. Sites totalmente estáticos também podem ser deployados exclusivamente através de um CDN ou servidor de arquivos estáticos, eliminando a necessidade de manter um runtime de servidor customizado para sua aplicação. Isso melhora a escalabilidade ao transferir trabalho de um servidor web de aplicação, tornando-o particularmente benéfico para aplicações de alto tráfego.

NOTE: Ao usar Angular service worker, a primeira requisição é renderizada no servidor, mas todas as requisições subsequentes são manipuladas pelo service worker e renderizadas client-side.

### Definindo headers e status codes

Você pode definir headers e status codes customizados para rotas de servidor individuais usando as propriedades `headers` e `status` na configuração `ServerRoute`.

```typescript
// app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'profile',
    renderMode: RenderMode.Server,
    headers: {
      'X-My-Custom-Header': 'some-value',
    },
    status: 201,
  },
  // ... outras rotas
];
```

### Redirects

O Angular manipula redirects especificados pela propriedade [`redirectTo`](api/router/Route#redirectTo 'API reference') em configurações de rota, de forma diferente no lado do servidor.

**Server-Side Rendering (SSR)**
Redirects são executados usando redirects HTTP padrão (por exemplo, 301, 302) dentro do processo de server-side rendering.

**Pré-renderização (SSG)**
Redirects são implementados como "soft redirects" usando tags [`<meta http-equiv="refresh">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#refresh) no HTML pré-renderizado.

### Customizando pré-renderização em build-time (SSG)

Ao usar [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), você pode especificar várias opções de configuração para customizar o processo de pré-renderização e serving.

#### Rotas parametrizadas

Para cada rota com [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), você pode especificar uma função [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference'). Esta função permite que você controle quais parâmetros específicos produzem documentos pré-renderizados separados.

A função [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') retorna uma `Promise` que resolve para um array de objetos. Cada objeto é um mapa chave-valor de nome de parâmetro de rota para valor. Por exemplo, se você definir uma rota como `post/:id`, `getPrerenderParams` poderia retornar o array `[{id: 123}, {id: 456}]`, e assim renderizar documentos separados para `post/123` e `post/456`.

O corpo de [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') pode usar a função [`inject`](api/core/inject 'API reference') do Angular para injetar dependências e executar qualquer trabalho para determinar quais rotas pré-renderizar. Isso normalmente inclui fazer requisições para buscar dados para construir o array de valores de parâmetros.

Você também pode usar essa função com rotas catch-all (por exemplo, `/**`), onde o nome do parâmetro será `"**"` e o valor de retorno será os segmentos do caminho, como `foo/bar`. Estes podem ser combinados com outros parâmetros (por exemplo, `/post/:id/**`) para lidar com configurações de rota mais complexas.

```ts
// app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'post/:id',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      const dataService = inject(PostService);
      const ids = await dataService.getIds(); // Assumindo que isso retorna ['1', '2', '3']

return ids.map(id => ({ id })); // Gera caminhos como: /post/1, /post/2, /post/3
    },
  },
  {
    path: 'post/:id/**',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      return [
        { id: '1', '**': 'foo/3' },
        { id: '2', '**': 'bar/4' },
      ]; // Gera caminhos como: /post/1/foo/3, /post/2/bar/4
    },
  },
];
```

Como [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') se aplica exclusivamente a [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), essa função sempre executa em _build-time_. `getPrerenderParams` não deve depender de quaisquer APIs específicas do navegador ou do servidor para dados.

IMPORTANT: Ao usar [`inject`](api/core/inject 'API reference') dentro de `getPrerenderParams`, lembre-se de que `inject` deve ser usado de forma síncrona. Ele não pode ser invocado dentro de callbacks assíncronos ou seguindo quaisquer declarações `await`. Para mais informações, consulte [`runInInjectionContext`](api/core/runInInjectionContext).

#### Estratégias de fallback

Ao usar o modo [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), você pode especificar uma estratégia de fallback para lidar com requisições para caminhos que não foram pré-renderizados.

As estratégias de fallback disponíveis são:

- **Server:** Volta para server-side rendering. Este é o comportamento **padrão** se nenhuma propriedade `fallback` for especificada.
- **Client:** Volta para client-side rendering.
- **None:** Nenhum fallback. O Angular não manipulará requisições para caminhos que não estão pré-renderizados.

```typescript
// app.routes.server.ts
import { RenderMode, PrerenderFallback, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'post/:id',
    renderMode: RenderMode.Prerender,
    fallback: PrerenderFallback.Client, // Fallback para CSR se não pré-renderizado
    async getPrerenderParams() {
      // Esta função retorna um array de objetos representando posts pré-renderizados nos caminhos:
      // `/post/1`, `/post/2`, e `/post/3`.
      // O caminho `/post/4` utilizará o comportamento de fallback se for requisitado.
      return [{ id: 1 }, { id: 2 }, { id: 3 }];
    },
  },
];
```

## Escrevendo components compatíveis com servidor

Algumas APIs e capacidades comuns do navegador podem não estar disponíveis no servidor. Aplicações não podem usar objetos globais específicos do navegador como `window`, `document`, `navigator` ou `location`, bem como certas propriedades de `HTMLElement`.

Em geral, código que depende de símbolos específicos do navegador só deve ser executado no navegador, não no servidor. Isso pode ser forçado através dos lifecycle hooks [`afterEveryRender`](api/core/afterEveryRender) e [`afterNextRender`](api/core/afterNextRender). Estes são executados apenas no navegador e pulados no servidor.

```typescript
import { Component, ViewChild, afterNextRender } from '@angular/core';

@Component({
  selector: 'my-cmp',
  template: `<span #content>{{ ... }}</span>`,
})
export class MyComponent {
  @ViewChild('content') contentRef: ElementRef;

constructor() {
    afterNextRender(() => {
      // Seguro verificar `scrollHeight` porque isso só executará no navegador, não no servidor.
      console.log('content height: ' + this.contentRef.nativeElement.scrollHeight);
    });
  }
}
```

## Definindo providers no servidor

No lado do servidor, valores de provider de nível superior são definidos uma vez quando o código da aplicação é inicialmente analisado e avaliado.
Isso significa que providers configurados com `useValue` manterão seu valor através de múltiplas requisições, até que a aplicação do servidor seja reiniciada.

Se você quiser gerar um novo valor para cada requisição, use um factory provider com `useFactory`. A função factory será executada para cada requisição recebida, garantindo que um novo valor seja criado e atribuído ao token a cada vez.

## Acessando Request e Response via DI

O pacote `@angular/core` fornece vários tokens para interagir com o ambiente de server-side rendering. Esses tokens dão acesso a informações e objetos cruciais dentro da sua aplicação Angular durante SSR.

- **[`REQUEST`](api/core/REQUEST 'API reference'):** Fornece acesso ao objeto de requisição atual, que é do tipo [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) da Web API. Isso permite que você acesse headers, cookies e outras informações de requisição.
- **[`RESPONSE_INIT`](api/core/RESPONSE_INIT 'API reference'):** Fornece acesso às opções de inicialização de resposta, que é do tipo [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#parameters) da Web API. Isso permite que você defina headers e o status code para a resposta dinamicamente. Use este token para definir headers ou status codes que precisam ser determinados em runtime.
- **[`REQUEST_CONTEXT`](api/core/REQUEST_CONTEXT 'API reference'):** Fornece acesso a contexto adicional relacionado à requisição atual. Este contexto pode ser passado como o segundo parâmetro da função [`handle`](api/ssr/AngularAppEngine#handle 'API reference'). Tipicamente, isso é usado para fornecer informações adicionais relacionadas à requisição que não fazem parte da Web API padrão.

```typescript
import { inject, REQUEST } from '@angular/core';

@Component({
  selector: 'app-my-component',
  template: `<h1>My Component</h1>`,
})
export class MyComponent {
  constructor() {
    const request = inject(REQUEST);
    console.log(request?.url);
  }
}
```

IMPORTANT: Os tokens acima serão `null` nos seguintes cenários:

- Durante os processos de build.
- Quando a aplicação é renderizada no navegador (CSR).
- Ao executar static site generation (SSG).
- Durante a extração de rota em desenvolvimento (no momento da requisição).

## Gerar uma aplicação totalmente estática {#generate-a-fully-static-application}

Por padrão, o Angular pré-renderiza toda a sua aplicação e gera um arquivo de servidor para manipular requisições. Isso permite que sua aplicação sirva conteúdo pré-renderizado aos usuários. No entanto, se você preferir um site totalmente estático sem um servidor, pode optar por não ter esse comportamento definindo o `outputMode` como `static` no seu arquivo de configuração `angular.json`.

Quando `outputMode` está definido como `static`, o Angular gera arquivos HTML pré-renderizados para cada rota em build time, mas não gera um arquivo de servidor ou requer um servidor Node.js para servir a aplicação. Isso é útil para deploy em provedores de hospedagem estática onde um servidor backend não é necessário.

Para configurar isso, atualize seu arquivo `angular.json` da seguinte forma:

```json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "outputMode": "static"
          }
        }
      }
    }
  }
}
```

## Caching de dados ao usar HttpClient

`HttpClient` faz cache de requisições de rede de saída ao executar no servidor. Esta informação é serializada e transferida para o navegador como parte do HTML inicial enviado do servidor. No navegador, `HttpClient` verifica se tem dados no cache e, se tiver, os reutiliza em vez de fazer uma nova requisição HTTP durante a renderização inicial da aplicação. `HttpClient` para de usar o cache assim que uma aplicação se torna [stable](api/core/ApplicationRef#isStable) enquanto executa em um navegador.

### Configurando as opções de caching

Você pode customizar como o Angular faz cache de respostas HTTP durante server‑side rendering (SSR) e as reutiliza durante hydration configurando `HttpTransferCacheOptions`.
Esta configuração é fornecida globalmente usando `withHttpTransferCacheOptions` dentro de `provideClientHydration()`.

Por padrão, `HttpClient` faz cache de todas as requisições `HEAD` e `GET` que não contêm headers `Authorization` ou `Proxy-Authorization`. Você pode sobrescrever essas configurações usando `withHttpTransferCacheOptions` na configuração de hydration.

```ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideClientHydration, withHttpTransferCacheOptions } from '@angular/platform-browser';

bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        includeHeaders: ['ETag', 'Cache-Control'],
        filter: (req) => !req.url.includes('/api/profile'),
        includePostRequests: true,
        includeRequestsWithAuthHeaders: false,
      }),
    ),
  ],
});
```

---

### `includeHeaders`

Especifica quais headers da resposta do servidor devem ser incluídos em entradas em cache.
Nenhum header é incluído por padrão.

```ts
withHttpTransferCacheOptions({
  includeHeaders: ['ETag', 'Cache-Control'],
});
```

IMPORTANT: Evite incluir headers sensíveis como tokens de autenticação. Estes podem vazar dados específicos do usuário entre requisições.

---

### `includePostRequests`

Por padrão, apenas requisições `GET` e `HEAD` são armazenadas em cache.
Você pode habilitar cache para requisições `POST` quando elas são usadas como operações de leitura, como queries GraphQL.

```ts
withHttpTransferCacheOptions({
  includePostRequests: true,
});
```

Use isso apenas quando requisições `POST` são **idempotentes** e seguras para reutilizar entre renderizações de servidor e cliente.

---

### `includeRequestsWithAuthHeaders`

Determina se requisições contendo headers `Authorization` ou `Proxy‑Authorization` são elegíveis para cache.
Por padrão, estas são excluídas para prevenir cache de respostas específicas do usuário.

```ts
withHttpTransferCacheOptions({
  includeRequestsWithAuthHeaders: true,
});
```

Habilite apenas quando headers de autenticação **não** afetam o conteúdo da resposta (por exemplo, tokens públicos para APIs de analytics).

### Sobrescrições por requisição

Você pode sobrescrever o comportamento de cache para uma requisição específica usando a opção de requisição `transferCache`.

```ts
// Incluir headers específicos para esta requisição
http.get('/api/profile', { transferCache: { includeHeaders: ['CustomHeader'] } });
```

### Desabilitando caching

Você pode desabilitar o cache HTTP de requisições enviadas do servidor globalmente ou individualmente.

#### Globalmente

Para desabilitar cache para todas as requisições na sua aplicação, use a feature `withNoHttpTransferCache`:

```ts
import { bootstrapApplication, provideClientHydration, withNoHttpTransferCache } from '@angular/platform-browser';

bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(withNoHttpTransferCache())
  ]
});
```

#### `filter`

Você também pode desabilitar seletivamente o cache para certas requisições usando a opção [`filter`](api/common/http/HttpTransferCacheOptions) em `withHttpTransferCacheOptions`. Por exemplo, você pode desabilitar cache para um endpoint de API específico:

```ts
import { bootstrapApplication, provideClientHydration, withHttpTransferCacheOptions } from '@angular/platform-browser';

bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(withHttpTransferCacheOptions({
      filter: (req) => !req.url.includes('/api/sensitive-data')
    }))
  ]
});
```

Use esta opção para excluir endpoints com dados específicos do usuário ou dinâmicos (por exemplo `/api/profile`).

#### Individualmente

Para desabilitar cache para uma requisição individual, você pode especificar a opção [`transferCache`](api/common/http/HttpRequest#transferCache) em um `HttpRequest`.

```ts
httpClient.get('/api/sensitive-data', { transferCache: false });
```

## Configurando um servidor

### Node.js

O `@angular/ssr/node` estende `@angular/ssr` especificamente para ambientes Node.js. Ele fornece APIs que facilitam a implementação de server-side rendering dentro da sua aplicação Node.js. Para uma lista completa de funções e exemplos de uso, consulte a referência da API [`@angular/ssr/node` API reference](api/ssr/node/AngularNodeAppEngine).

```typescript
// server.ts
import { AngularNodeAppEngine, createNodeRequestHandler, writeResponseToNodeResponse } from '@angular/ssr/node';
import express from 'express';

const app = express();
const angularApp = new AngularNodeAppEngine();

app.use('*', (req, res, next) => {
  angularApp
    .handle(req)
    .then(response => {
      if (response) {
        writeResponseToNodeResponse(response, res);
      } else {
        next(); // Passa controle para o próximo middleware
      }
    })
    .catch(next);
});

/**
 * O request handler usado pelo Angular CLI (dev-server e durante build).
 */
export const reqHandler = createNodeRequestHandler(app);
```

### Non-Node.js

O `@angular/ssr` fornece APIs essenciais para server-side rendering da sua aplicação Angular em plataformas diferentes de Node.js. Ele aproveita os objetos padrão [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) e [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) da Web API, permitindo que você integre Angular SSR em vários ambientes de servidor. Para informações detalhadas e exemplos, consulte a referência da API [`@angular/ssr` API reference](api/ssr/AngularAppEngine).

```typescript
// server.ts
import { AngularAppEngine, createRequestHandler } from '@angular/ssr';

const angularApp = new AngularAppEngine();

/**
 * Este é um request handler usado pelo Angular CLI (dev-server e durante build).
 */
export const reqHandler = createRequestHandler(async (req: Request) => {
  const res: Response|null = await angularApp.render(req);

// ...
});
```

# Hydration

## O que é hydration

Hydration é o processo que restaura a aplicação renderizada no servidor (server-side rendered) no cliente. Isso inclui coisas como reutilizar as estruturas DOM renderizadas no servidor, persistir o estado da aplicação, transferir dados da aplicação que já foram recuperados pelo servidor e outros processos.

## Por que hydration é importante?

Hydration melhora o desempenho da aplicação evitando trabalho extra para recriar nós do DOM. Em vez disso, o Angular tenta combinar elementos DOM existentes com a estrutura da aplicação em tempo de execução e reutiliza nós do DOM quando possível. Isso resulta em uma melhoria de desempenho que pode ser medida usando estatísticas de [Core Web Vitals (CWV)](https://web.dev/learn-core-web-vitals/), como a redução do First Input Delay ([FID](https://web.dev/fid/)) e Largest Contentful Paint ([LCP](https://web.dev/lcp/)), bem como Cumulative Layout Shift ([CLS](https://web.dev/cls/)). Melhorar esses números também afeta coisas como desempenho de SEO.

Sem hydration habilitado, aplicações Angular renderizadas no servidor irão destruir e re-renderizar o DOM da aplicação, o que pode resultar em uma oscilação visível na UI. Essa re-renderização pode impactar negativamente os [Core Web Vitals](https://web.dev/learn-core-web-vitals/) como [LCP](https://web.dev/lcp/) e causar um layout shift. Habilitar hydration permite que o DOM existente seja reutilizado e previne a oscilação.

## Como você habilita hydration no Angular

Hydration pode ser habilitado apenas para aplicações renderizadas no servidor (SSR). Siga o [Guia de SSR do Angular](guide/ssr) para habilitar server-side rendering primeiro.

### Usando Angular CLI

Se você usou o Angular CLI para habilitar SSR (seja habilitando durante a criação da aplicação ou posteriormente via `ng add @angular/ssr`), o código que habilita hydration já deve estar incluído na sua aplicação.

### Configuração manual {#constraints}

Se você tem uma configuração customizada e não usou o Angular CLI para habilitar SSR, você pode habilitar hydration manualmente visitando o component ou módulo principal da sua aplicação e importando `provideClientHydration` de `@angular/platform-browser`. Você então adiciona esse provider à lista de providers de bootstrap da sua aplicação.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
} from '@angular/platform-browser';
...

bootstrapApplication(AppComponent, {
  providers: [provideClientHydration()]
});
```

Alternativamente, se você está usando NgModules, você adicionaria `provideClientHydration` à lista de providers do módulo raiz da sua aplicação.

```typescript
import {provideClientHydration} from '@angular/platform-browser';
import {NgModule} from '@angular/core';

@NgModule({
  declarations: [AppComponent],
  exports: [AppComponent],
  bootstrap: [AppComponent],
  providers: [provideClientHydration()],
})
export class AppModule {}
```

IMPORTANTE: Certifique-se de que a chamada `provideClientHydration()` também esteja incluída em um conjunto de providers que é usado para fazer o bootstrap de uma aplicação no **servidor**. Em aplicações com a estrutura de projeto padrão (gerada pelo comando `ng new`), adicionar uma chamada ao `AppModule` raiz deve ser suficiente, pois este módulo é importado pelo módulo do servidor. Se você usa uma configuração customizada, adicione a chamada `provideClientHydration()` à lista de providers na configuração de bootstrap do servidor.

### Verificar que hydration está habilitado

Depois que você configurou hydration e iniciou seu servidor, carregue sua aplicação no navegador.

ÚTIL: Você provavelmente precisará corrigir instâncias de Manipulação Direta do DOM antes que hydration funcione completamente, seja mudando para construtos do Angular ou usando `ngSkipHydration`. Veja [Restrições](#constraints), [Manipulação Direta do DOM](#direct-dom-manipulation), e [Como pular hydration para components específicos](#how-to-skip-hydration-for-particular-components) para mais detalhes.

Ao executar uma aplicação em modo de desenvolvimento, você pode confirmar que hydration está habilitado abrindo as Ferramentas do Desenvolvedor no seu navegador e visualizando o console. Você deve ver uma mensagem que inclui estatísticas relacionadas a hydration, como o número de components e nós hidratados. O Angular calcula as estatísticas baseado em todos os components renderizados em uma página, incluindo aqueles que vêm de bibliotecas de terceiros.

Você também pode usar a [extensão de navegador Angular DevTools](tools/devtools) para ver o status de hydration dos components em uma página. Angular DevTools também permite habilitar um overlay para indicar quais partes da página foram hidratadas. Se houver um erro de incompatibilidade de hydration - DevTools também destacaria um component que causou o erro.

## Capturando e reproduzindo eventos

Quando uma aplicação é renderizada no servidor, ela fica visível em um navegador assim que o HTML produzido carrega. Os usuários podem assumir que podem interagir com a página, mas os event listeners não são anexados até que hydration seja concluído. A partir do v18, você pode habilitar o recurso Event Replay que permite capturar todos os eventos que acontecem antes de hydration e reproduzir esses eventos assim que hydration for concluída. Você pode habilitá-lo usando a função `withEventReplay()`, por exemplo:

```typescript
import {provideClientHydration, withEventReplay} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [
    provideClientHydration(withEventReplay())
  ]
});
```

### Como event replay funciona

Event Replay é um recurso que melhora a experiência do usuário capturando eventos de usuário que foram acionados antes do processo de hydration estar completo. Então esses eventos são reproduzidos, garantindo que nenhuma dessas interações foi perdida.

O Event Replay é dividido em três fases principais:

- **Capturando interações do usuário**<br>
  Antes de **Hydration**, Event Replay captura e armazena todas as interações que o usuário pode realizar, como cliques e outros eventos nativos do navegador.

- **Armazenando eventos**<br>
  O **Event Contract** mantém na memória todas as interações gravadas na etapa anterior, garantindo que elas não sejam perdidas para reprodução posterior.

- **Relançamento de eventos**<br>
  Uma vez que **Hydration** é concluída, o Angular re-invoca os eventos capturados.

Event replay suporta _eventos nativos do navegador_, por exemplo `click`, `mouseover`, e `focusin`. Se você quiser aprender mais sobre JSAction, a biblioteca que alimenta event replay, você pode ler mais [no readme](https://github.com/angular/angular/tree/main/packages/core/primitives/event-dispatch#readme).

---

Este recurso garante uma experiência de usuário consistente, prevenindo que ações do usuário realizadas antes de Hydration sejam ignoradas. NOTA: se você tem [incremental hydration](guide/incremental-hydration) habilitado, event replay é automaticamente habilitado por baixo dos panos.

## Restrições

Hydration impõe algumas restrições na sua aplicação que não estão presentes sem hydration habilitado. Sua aplicação deve ter a mesma estrutura DOM gerada tanto no servidor quanto no cliente. O processo de hydration espera que a árvore DOM tenha a mesma estrutura em ambos os lugares. Isso também inclui espaços em branco e nós de comentário que o Angular produz durante a renderização no servidor. Esses espaços em branco e nós devem estar presentes no HTML gerado pelo processo de server-side rendering.

IMPORTANTE: O HTML produzido pela operação de server-side rendering **não deve** ser alterado entre o servidor e o cliente.

Se houver uma incompatibilidade entre as estruturas da árvore DOM do servidor e do cliente, o processo de hydration encontrará problemas ao tentar combinar o que era esperado com o que realmente está presente no DOM. Components que fazem manipulação direta do DOM usando APIs DOM nativas são os culpados mais comuns.

### Manipulação Direta do DOM {#direct-dom-manipulation}

Se você tem components que manipulam o DOM usando APIs DOM nativas ou usam `innerHTML` ou `outerHTML`, o processo de hydration encontrará erros. Casos específicos onde manipulação do DOM é um problema são situações como acessar o `document`, consultar elementos específicos e injetar nós adicionais usando `appendChild`. Desanexar nós do DOM e movê-los para outros locais também resultará em erros.

Isso ocorre porque o Angular desconhece essas mudanças no DOM e não pode resolvê-las durante o processo de hydration. O Angular esperará uma certa estrutura, mas encontrará uma estrutura diferente ao tentar hidratar. Essa incompatibilidade resultará em falha de hydration e lançará um erro de incompatibilidade de DOM ([veja abaixo](#errors)).

É melhor refatorar seu component para evitar esse tipo de manipulação do DOM. Tente usar APIs do Angular para fazer esse trabalho, se possível. Se você não pode refatorar esse comportamento, use o atributo `ngSkipHydration` ([descrito abaixo](#how-to-skip-hydration-for-particular-components)) até que você possa refatorar para uma solução amigável ao hydration.

### Estrutura HTML válida {#valid-html-structure}

Existem alguns casos onde se você tem um template de component que não tem estrutura HTML válida, isso pode resultar em um erro de incompatibilidade de DOM durante hydration.

Como exemplo, aqui estão alguns dos casos mais comuns deste problema.

- `<table>` sem um `<tbody>`
- `<div>` dentro de um `<p>`
- `<a>` dentro de outro `<a>`

Se você não tem certeza se seu HTML é válido, você pode usar um [validador de sintaxe](https://validator.w3.org/) para verificá-lo.

NOTA: Enquanto o padrão HTML não exige o elemento `<tbody>` dentro de tabelas, navegadores modernos criam automaticamente um elemento `<tbody>` em tabelas que não declaram um. Por causa dessa inconsistência, sempre declare explicitamente um elemento `<tbody>` em tabelas para evitar erros de hydration.

### Configuração de Preserve Whitespaces

Ao usar o recurso de hydration, recomendamos usar a configuração padrão de `false` para `preserveWhitespaces`. Se essa configuração não estiver no seu tsconfig, o valor será `false` e nenhuma mudança é necessária. Se você optar por habilitar a preservação de espaços em branco adicionando `preserveWhitespaces: true` ao seu tsconfig, é possível que você encontre problemas com hydration. Esta ainda não é uma configuração totalmente suportada.

ÚTIL: Certifique-se de que esta configuração está definida **consistentemente** em `tsconfig.server.json` para o seu servidor e `tsconfig.app.json` para suas builds do navegador. Um valor incompatível causará quebra de hydration.

Se você optar por definir esta configuração no seu tsconfig, recomendamos defini-la apenas em `tsconfig.app.json`, do qual por padrão o `tsconfig.server.json` irá herdá-la.

### Zone.js customizado ou Noop ainda não são suportados

Hydration depende de um sinal de Zone.js quando ele se torna estável dentro de uma aplicação, para que o Angular possa iniciar o processo de serialização no servidor ou limpeza pós-hydration no cliente para remover nós do DOM que permaneceram não reclamados.

Fornecer uma implementação Zone.js customizada ou "noop" pode levar a um timing diferente do evento "stable", assim acionando a serialização ou a limpeza muito cedo ou muito tarde. Esta ainda não é uma configuração totalmente suportada e você pode precisar ajustar o timing do evento `onStable` na implementação Zone.js customizada.

## Erros {#errors}

Existem vários erros relacionados a hydration que você pode encontrar, variando de incompatibilidades de nó a casos onde o `ngSkipHydration` foi usado em um nó host inválido. O caso de erro mais comum que pode ocorrer é devido à manipulação direta do DOM usando APIs nativas que resulta em hydration sendo incapaz de encontrar ou combinar a estrutura da árvore DOM esperada no cliente que foi renderizada pelo servidor. O outro caso em que você pode encontrar este tipo de erro foi mencionado na seção [Estrutura HTML válida](#valid-html-structure) anteriormente. Então, certifique-se de que o HTML nos seus templates está usando estrutura válida, e você evitará esse caso de erro.

Para uma referência completa sobre erros relacionados a hydration, visite o [Guia de Referência de Erros](/errors).

## Como pular hydration para components específicos {#how-to-skip-hydration-for-particular-components}

Alguns components podem não funcionar adequadamente com hydration habilitado devido a alguns dos problemas mencionados anteriormente, como [Manipulação Direta do DOM](#direct-dom-manipulation). Como solução alternativa, você pode adicionar o atributo `ngSkipHydration` à tag de um component para pular a hidratação de todo o component.

```html
<app-example ngSkipHydration />
```

Alternativamente, você pode definir `ngSkipHydration` como um host binding.

```typescript
@Component({
  ...
  host: {ngSkipHydration: 'true'},
})
class ExampleComponent {}
```

O atributo `ngSkipHydration` forçará o Angular a pular hydration de todo o component e seus filhos. Usar este atributo significa que o component se comportará como se hydration não estivesse habilitado, ou seja, ele irá destruir e re-renderizar a si mesmo.

ÚTIL: Isso corrigirá problemas de renderização, mas significa que para este component (e seus filhos), você não obtém os benefícios de hydration. Você precisará ajustar a implementação do seu component para evitar padrões que quebram hydration (ou seja, Manipulação Direta do DOM) para poder remover a anotação de pular hydration.

O atributo `ngSkipHydration` só pode ser usado em nós host de components. O Angular lança um erro se este atributo for adicionado a outros nós.

Tenha em mente que adicionar o atributo `ngSkipHydration` ao seu component de aplicação raiz efetivamente desabilitaria hydration para toda a sua aplicação. Seja cuidadoso e ponderado ao usar este atributo. Ele é pretendido como uma solução alternativa de último recurso. Components que quebram hydration devem ser considerados bugs que precisam ser corrigidos.

## Timing de Hydration e Estabilidade da Aplicação

Estabilidade da aplicação é uma parte importante do processo de hydration. Hydration e quaisquer processos pós-hydration só ocorrem uma vez que a aplicação tenha reportado estabilidade. Existem várias maneiras que a estabilidade pode ser atrasada. Exemplos incluem definir timeouts e intervals, promises não resolvidas e microtasks pendentes. Nesses casos, você pode encontrar o erro [Application remains unstable](errors/NG0506), que indica que sua aplicação ainda não alcançou o estado estável após 10 segundos. Se você está descobrindo que sua aplicação não está hidratando imediatamente, dê uma olhada no que está impactando a estabilidade da aplicação e refatore para evitar causar esses atrasos.

## I18N

ÚTIL: Por padrão, o Angular pulará hydration para components que usam blocos i18n, efetivamente re-renderizando esses components do zero.

Para habilitar hydration para blocos i18n, você pode adicionar [`withI18nSupport`](/api/platform-browser/withI18nSupport) à sua chamada `provideClientHydration`.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withI18nSupport,
} from '@angular/platform-browser';
...

bootstrapApplication(AppComponent, {
  providers: [provideClientHydration(withI18nSupport())]
});
```

## Renderização consistente entre server-side e client-side

Evite introduzir blocos `@if` e outros condicionais que exibem conteúdo diferente ao renderizar no servidor do que ao renderizar no cliente, como usar um bloco `@if` com a função `isPlatformBrowser` do Angular. Essas diferenças de renderização causam layout shifts, impactando negativamente a experiência do usuário final e core web vitals.

## Bibliotecas de Terceiros com Manipulação do DOM

Existem várias bibliotecas de terceiros que dependem de manipulação do DOM para serem capazes de renderizar. Gráficos D3 são um exemplo primordial. Essas bibliotecas funcionavam sem hydration, mas podem causar erros de incompatibilidade de DOM quando hydration está habilitado. Por enquanto, se você encontrar erros de incompatibilidade de DOM usando uma dessas bibliotecas, você pode adicionar o atributo `ngSkipHydration` ao component que renderiza usando essa biblioteca.

## Scripts de Terceiros com Manipulação do DOM

Muitos scripts de terceiros, como rastreadores de anúncios e análises, modificam o DOM antes que hydration possa ocorrer. Esses scripts podem causar erros de hydration porque a página não corresponde mais à estrutura esperada pelo Angular. Prefira adiar este tipo de script até após hydration sempre que possível. Considere usar [`AfterNextRender`](api/core/afterNextRender) para atrasar o script até que processos pós-hydration tenham ocorrido.

## Incremental Hydration

Incremental hydration é uma forma avançada de hydration que permite controle mais granular sobre quando hydration acontece. Veja o [guia de incremental hydration](guide/incremental-hydration) para mais informações.

# Incremental Hydration

**Incremental hydration** é um tipo avançado de [hydration](guide/hydration) que pode deixar seções da sua aplicação desidratadas e _incrementalmente_ acionar hydration dessas seções conforme elas são necessárias.

## Por que usar incremental hydration?

Incremental hydration é uma melhoria de desempenho que se baseia em cima de full application hydration. Pode produzir bundles iniciais menores enquanto ainda fornece uma experiência de usuário final que é comparável a uma experiência de full application hydration. Bundles menores melhoram os tempos de carregamento inicial, reduzindo [First Input Delay (FID)](https://web.dev/fid) e [Cumulative Layout Shift (CLS)](https://web.dev/cls).

Incremental hydration também permite que você use deferrable views (`@defer`) para conteúdo que pode não ter sido adiável antes. Especificamente, você agora pode usar deferrable views para conteúdo que está acima da dobra (above the fold). Antes do incremental hydration, colocar um bloco `@defer` acima da dobra resultaria em conteúdo placeholder sendo renderizado e então sendo substituído pelo conteúdo do template principal do bloco `@defer`. Isso resultaria em um layout shift. Incremental hydration significa que o template principal do bloco `@defer` será renderizado sem layout shift em hydration.

## Como você habilita incremental hydration no Angular?

Você pode habilitar incremental hydration para aplicações que já usam server-side rendering (SSR) com hydration. Siga o [Guia de SSR do Angular](guide/ssr) para habilitar server-side rendering e o [Guia de Hydration do Angular](guide/hydration) para habilitar hydration primeiro.

Habilite incremental hydration adicionando a função `withIncrementalHydration()` ao provider `provideClientHydration`.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withIncrementalHydration,
} from '@angular/platform-browser';
...

bootstrapApplication(AppComponent, {
  providers: [provideClientHydration(withIncrementalHydration())]
});
```

Incremental Hydration depende e habilita [event replay](guide/hydration#capturing-and-replaying-events) automaticamente. Se você já tem `withEventReplay()` na sua lista, você pode removê-lo com segurança após habilitar incremental hydration.

## Como incremental hydration funciona?

Incremental hydration se baseia em cima de full-application [hydration](guide/hydration), [deferrable views](guide/defer), e [event replay](guide/hydration#capturing-and-replaying-events). Com incremental hydration, você pode adicionar triggers adicionais a blocos `@defer` que definem limites de incremental hydration. Adicionar um trigger `hydrate` a um bloco defer diz ao Angular que ele deve carregar as dependências desse bloco defer durante server-side rendering e renderizar o template principal em vez do `@placeholder`. Ao renderizar no client-side, as dependências ainda são adiadas, e o conteúdo do bloco defer permanece desidratado até que seu trigger `hydrate` dispare. Esse trigger diz ao bloco defer para buscar suas dependências e hidratar o conteúdo. Quaisquer eventos do navegador, especificamente aqueles que correspondem a listeners registrados no seu component, que são acionados pelo usuário antes de hydration são enfileirados e reproduzidos uma vez que o processo de hydration está completo.

## Controlando hydration de conteúdo com triggers

Você pode especificar **hydrate triggers** que controlam quando o Angular carrega e hidrata conteúdo adiado. Esses são triggers adicionais que podem ser usados junto com triggers `@defer` regulares.

Cada bloco `@defer` pode ter múltiplos event triggers de hydrate, separados com ponto e vírgula (`;`). O Angular aciona hydration quando _qualquer_ dos triggers dispara.

Existem três tipos de hydrate triggers: `hydrate on`, `hydrate when`, e `hydrate never`.

### `hydrate on`

`hydrate on` especifica uma condição para quando hydration é acionada para o bloco `@defer`.

Os triggers disponíveis são os seguintes:

| Trigger                                             | Descrição                                                                   |
| --------------------------------------------------- | --------------------------------------------------------------------------- |
| [`hydrate on idle`](#hydrate-on-idle)               | Aciona quando o navegador está ocioso.                                      |
| [`hydrate on viewport`](#hydrate-on-viewport)       | Aciona quando o conteúdo especificado entra no viewport                     |
| [`hydrate on interaction`](#hydrate-on-interaction) | Aciona quando o usuário interage com o elemento especificado                |
| [`hydrate on hover`](#hydrate-on-hover)             | Aciona quando o mouse passa sobre a área especificada                       |
| [`hydrate on immediate`](#hydrate-on-immediate)     | Aciona imediatamente após o conteúdo não adiado ter terminado de renderizar |
| [`hydrate on timer`](#hydrate-on-timer)             | Aciona após uma duração específica                                          |

#### `hydrate on idle`

O trigger `hydrate on idle` carrega as dependências da deferrable view e hidrata o conteúdo uma vez que o navegador alcançou um estado ocioso, baseado em `requestIdleCallback`.

```html
@defer (hydrate on idle) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `hydrate on viewport`

O trigger `hydrate on viewport` carrega as dependências da deferrable view e hidrata a página correspondente da aplicação quando o conteúdo especificado entra no viewport usando a
[Intersection Observer API](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API).

```html
@defer (hydrate on viewport) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `hydrate on interaction`

O trigger `hydrate on interaction` carrega as dependências da deferrable view e hidrata o conteúdo quando o usuário interage com o elemento especificado através de
eventos `click` ou `keydown`.

```html
@defer (hydrate on interaction) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `hydrate on hover`

O trigger `hydrate on hover` carrega as dependências da deferrable view e hidrata o conteúdo quando o mouse passou sobre a área acionada através dos
eventos `mouseover` e `focusin`.

```html
@defer (hydrate on hover) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `hydrate on immediate`

O trigger `hydrate on immediate` carrega as dependências da deferrable view e hidrata o conteúdo imediatamente. Isso significa que o bloco adiado carrega assim que
todo outro conteúdo não adiado terminou de renderizar.

```html
@defer (hydrate on immediate) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

#### `hydrate on timer`

O trigger `hydrate on timer` carrega as dependências da deferrable view e hidrata o conteúdo após uma duração especificada.

```html
@defer (hydrate on timer(500ms)) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

O parâmetro de duração deve ser especificado em milissegundos (`ms`) ou segundos (`s`).

### `hydrate when`

O trigger `hydrate when` aceita uma expressão condicional customizada e carrega as dependências da deferrable view e hidrata o conteúdo quando a
condição se torna verdadeira.

```html
@defer (hydrate when condition) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

NOTA: condições `hydrate when` só acionam quando são o bloco `@defer` desidratado mais no topo. A condição fornecida para o trigger é
especificada no component pai, que precisa existir antes que possa ser acionado. Se o bloco pai estiver desidratado, essa expressão ainda não será
resolvível pelo Angular.

### `hydrate never`

O `hydrate never` permite que os usuários especifiquem que o conteúdo no bloco defer deve permanecer desidratado indefinidamente, efetivamente se tornando conteúdo estático. Note que isso se aplica apenas à renderização inicial. Durante uma renderização client-side subsequente, um bloco `@defer` com `hydrate never`
ainda buscaria dependências, pois hydration só se aplica ao carregamento inicial de conteúdo renderizado no servidor. No exemplo abaixo, renderizações client-side subsequentes carregariam as dependências do bloco `@defer` no viewport.

```html
@defer (on viewport; hydrate never) {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}
```

NOTA: Usar `hydrate never` previne hydration de toda a subárvore aninhada de um determinado bloco `@defer`. Nenhum outro trigger `hydrate` dispara para conteúdo aninhado abaixo desse bloco.

## Hydrate triggers junto com triggers regulares

Hydrate triggers são triggers adicionais que são usados junto com triggers regulares em um bloco `@defer`. Hydration é uma otimização de carregamento inicial, e isso significa que hydrate triggers só se aplicam a esse carregamento inicial. Qualquer renderização client-side subsequente ainda usará o trigger regular.

```html
@defer (on idle; hydrate on interaction) {
  <example-cmp />
} @placeholder{
  <div>Example Placeholder</div>
}
```

Neste exemplo, no carregamento inicial, o `hydrate on interaction` se aplica. Hydration será acionada na interação com o component `<example-cmp />`. Em qualquer carregamento de página subsequente que seja renderizado no client-side, por exemplo quando um usuário clica em um routerLink que carrega uma página com este component, o `on idle` será aplicado.

## Como incremental hydration funciona com blocos `@defer` aninhados?

O sistema de components e dependências do Angular é hierárquico, o que significa que hidratar qualquer component requer que todos os seus pais também sejam hidratados. Então, se hydration é acionada para um bloco `@defer` filho de um conjunto aninhado de blocos `@defer` desidratados, hydration é acionada do bloco `@defer` desidratado mais no topo até o filho acionado e dispara nessa ordem.

```html
@defer (hydrate on interaction) {
  <parent-block-cmp />
  @defer (hydrate on hover) {
    <child-block-cmp />
  } @placeholder {
    <div>Child placeholder</div>
  }
} @placeholder{
  <div>Parent Placeholder</div>
}
```

No exemplo acima, passar o mouse sobre o bloco `@defer` aninhado aciona hydration. O bloco `@defer` pai com o `<parent-block-cmp />` hidrata primeiro, então o bloco `@defer` filho com `<child-block-cmp />` hidrata depois.

## Restrições

Incremental hydration tem as mesmas restrições que full-application hydration, incluindo limites na manipulação direta do DOM e exigindo estrutura HTML válida. Visite a seção [restrições do guia de Hydration](guide/hydration#constraints) para mais detalhes.

## Eu ainda preciso especificar blocos `@placeholder`?

Sim. O conteúdo do bloco `@placeholder` não é usado para incremental hydration, mas um `@placeholder` ainda é necessário para casos de renderização client-side subsequentes. Se seu conteúdo não estava na rota que fazia parte do carregamento inicial, então qualquer navegação para a rota que tem o conteúdo do seu bloco `@defer` renderiza como um bloco `@defer` regular. Então o `@placeholder` é renderizado nesses casos de renderização client-side.

# Testing

Testar sua aplicação Angular ajuda você a verificar se sua aplicação está funcionando conforme esperado.

NOTA: Embora o Vitest seja o test runner padrão, o Karma ainda é totalmente suportado. Para informações sobre testes com Karma, veja o [guia de testes Karma](guide/testing/karma).

## Configurar testes

A Angular CLI baixa e instala tudo o que você precisa para testar uma aplicação Angular com o [framework de testes Vitest](https://vitest.dev).

O projeto que você cria com a CLI está imediatamente pronto para testar.
Apenas execute o comando CLI [`ng test`](cli/test):

```shell
ng test

```

O comando `ng test` constrói a aplicação em _modo watch_ e inicia o [test runner Vitest](https://vitest.dev).

A saída do console se parece com isto:

```shell
✓ src/app/app.component.spec.ts (3)
   ✓ AppComponent should create the app
   ✓ AppComponent should have as title 'my-app'
   ✓ AppComponent should render title
 Test Files  1 passed (1)
      Tests  3 passed (3)
   Start at  18:18:01
   Duration  2.46s (transform 615ms, setup 2ms, collect 2.21s, tests 5ms)

```

Enquanto isso, o comando `ng test` está observando mudanças.

Para ver isso em ação, faça uma pequena alteração em `app.ts` e salve.
Os testes executam novamente e os novos resultados dos testes aparecem no console.

## Configuração

A Angular CLI cuida da configuração do Vitest para você. Ela constrói a configuração completa em memória, com base nas opções especificadas no arquivo `angular.json`.

Se você quiser customizar o Vitest, pode criar um `vitest-base.config.ts` executando o seguinte comando:

```shell
ng generate config vitest

```

IMPORTANTE: Usar um `vitest-base.config.ts` personalizado fornece opções de customização poderosas. No entanto, a equipe Angular não fornece suporte para o conteúdo específico deste arquivo ou para quaisquer plugins de terceiros usados dentro dele.

ÚTIL: Leia mais sobre configuração do Vitest no [guia de configuração do Vitest](https://vitest.dev/config/).

### Outros frameworks de teste

Você também pode fazer unit test de uma aplicação Angular com outras bibliotecas de teste e test runners.
Cada biblioteca e runner tem seus próprios procedimentos de instalação, configuração e sintaxe distintivos.

### Nome e localização do arquivo de teste

Dentro da pasta `src/app`, a Angular CLI gerou um arquivo de teste para o component `App` chamado `app.spec.ts`.

IMPORTANTE: A extensão do arquivo de teste **deve ser `.spec.ts` ou `.test.ts`** para que as ferramentas possam identificá-lo como um arquivo com testes $também conhecido como arquivo _spec_$.

Os arquivos `app.ts` e `app.spec.ts` são irmãos na mesma pasta.
Os nomes dos arquivos raiz $`app`$ são os mesmos para ambos os arquivos.

Adote essas duas convenções em seus próprios projetos para _todo tipo_ de arquivo de teste.

#### Coloque seu arquivo spec ao lado do arquivo que ele testa

É uma boa ideia colocar arquivos spec de unit test na mesma pasta
que os arquivos de código fonte da aplicação que eles testam:

- Tais testes são indolores de encontrar
- Você vê de relance se uma parte de sua aplicação não tem testes
- Testes próximos podem revelar como uma parte funciona em contexto
- Quando você move o código fonte $inevitável$, você lembra de mover o teste
- Quando você renomeia o arquivo fonte $inevitável$, você lembra de renomear o arquivo de teste

#### Coloque seus arquivos spec em uma pasta test

Specs de integração de aplicação podem testar as interações de múltiplas partes
espalhadas por pastas e modules.
Elas não pertencem realmente a nenhuma parte em particular, então não têm um
lugar natural ao lado de nenhum arquivo.

Geralmente é melhor criar uma pasta apropriada para elas no diretório `tests`.

Claro que specs que testam os helpers de teste pertencem à pasta `test`,
ao lado de seus arquivos helper correspondentes.

## Testes em integração contínua

Uma das melhores maneiras de manter seu projeto livre de bugs é através de um conjunto de testes, mas você pode esquecer de executar os testes o tempo todo.

Servidores de integração contínua $CI$ permitem que você configure seu repositório de projeto para que seus testes sejam executados em cada commit e pull request.

Para testar sua aplicação Angular em um servidor de integração contínua (CI), você pode normalmente executar o comando de teste padrão:

```shell
ng test
```

A maioria dos servidores CI define uma variável de ambiente `CI=true`, que `ng test` detecta. Isso executa automaticamente seus testes no modo apropriado não interativo de execução única.

Se seu servidor CI não define esta variável, ou se você precisa forçar o modo de execução única manualmente, você pode usar as flags `--no-watch` e `--no-progress`:

```shell
ng test --no-watch --no-progress
```

## Mais informações sobre testes

Depois de configurar sua aplicação para testes, você pode achar os seguintes guias de testes úteis.

|                                                                    | Detalhes                                                                           |
| :----------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| [Cobertura de código](guide/testing/code-coverage)                       | Quanto da sua aplicação seus testes estão cobrindo e como especificar quantidades necessárias. |
| [Testes de services](guide/testing/services)                         | Como testar os services que sua aplicação usa.                                   |
| [Fundamentos de testes de components](guide/testing/components-basics)    | Fundamentos de testes de components Angular.                                             |
| [Cenários de testes de components](guide/testing/components-scenarios)  | Vários tipos de cenários e casos de uso de testes de components.                       |
| [Testes de attribute directives](guide/testing/attribute-directives) | Como testar suas attribute directives.                                            |
| [Testes de pipes](guide/testing/pipes)                               | Como testar pipes.                                                                |
| [Debug de testes](guide/testing/debugging)                         | Bugs comuns de testes.                                                              |
| [APIs utilitárias de testes](guide/testing/utility-apis)                 | Recursos de testes do Angular.                                                         |

# Descubra quanto código você está testando

A Angular CLI pode executar unit tests e criar relatórios de cobertura de código.
Relatórios de cobertura de código mostram quaisquer partes da sua base de código que podem não estar devidamente testadas pelos seus unit tests.

Para gerar um relatório de cobertura, execute o seguinte comando na raiz do seu projeto.

```shell
ng test --no-watch --coverage
```

Quando os testes forem concluídos, o comando cria um novo diretório `/coverage` no projeto.
Abra o arquivo `index.html` para ver um relatório com seu código fonte e valores de cobertura de código.

Se você quiser criar relatórios de cobertura de código toda vez que testar, defina a seguinte opção no arquivo de configuração da Angular CLI, `angular.json`:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "options": {
            "coverage": true
          }
        }
      }
    }
  }
}
```

## Aplicação de cobertura de código

As porcentagens de cobertura de código permitem estimar quanto do seu código está testado.
Se sua equipe decidir sobre uma quantidade mínima definida para ser testada por unit tests, você pode aplicar esse mínimo diretamente na sua configuração da Angular CLI.

Por exemplo, suponha que você queira que a base de código tenha um mínimo de 80% de cobertura de código.
Para habilitar isso, abra o arquivo `angular.json` e adicione a opção `coverageThresholds` à sua configuração de teste:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "options": {
            "coverage": true,
            "coverageThresholds": {
              "statements": 80,
              "branches": 80,
              "functions": 80,
              "lines": 80
            }
          }
        }
      }
    }
  }
}
```

Agora, quando você executar `ng test`, a ferramenta lançará um erro se a cobertura cair abaixo de 80%.

# Testes de services

Para verificar se seus services estão funcionando conforme você pretende, você pode escrever testes especificamente para eles.

Services são frequentemente os arquivos mais suaves para fazer unit test.
Aqui estão alguns unit tests síncronos e assíncronos do `ValueService` escritos sem assistência dos utilitários de teste do Angular.

```
## Testes de services com o `TestBed`

Sua aplicação depende da [injeção de dependência (DI)](guide/di) do Angular para criar services.
Quando um service tem um service dependente, DI encontra ou cria aquele service dependente.
E se aquele service dependente tem suas próprias dependências, DI as encontra ou cria também.

Como um _consumidor_ de service, você não se preocupa com nada disso.
Você não se preocupa com a ordem dos argumentos do constructor ou como eles são criados.

Como um _testador_ de service, você deve pelo menos pensar sobre o primeiro nível de dependências de service, mas você _pode_ deixar o DI do Angular fazer a criação do service e lidar com a ordem dos argumentos do constructor quando você usa o utilitário de teste `TestBed` para fornecer e criar services.

## `TestBed` do Angular

O `TestBed` é o mais importante dos utilitários de teste do Angular.
O `TestBed` cria um module _test_ do Angular construído dinamicamente que emula um [@NgModule](guide/ngmodules) do Angular.

O método `TestBed.configureTestingModule()` recebe um objeto de metadata que pode ter a maioria das propriedades de um [@NgModule](guide/ngmodules).

Para testar um service, você define a propriedade de metadata `providers` com um array dos services que você vai testar ou simular.

<docs-code header="app/demo/demo.testbed.spec.ts (provide ValueService in beforeEach)" path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="value-service-before-each"/>

Então injete-o dentro de um teste chamando `TestBed.inject()` com a classe do service como argumento.

ÚTIL: `TestBed.get()` foi depreciado a partir do Angular versão 9.
Para ajudar a minimizar mudanças breaking, o Angular introduz uma nova função chamada `TestBed.inject()`, que você deve usar em vez disso.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="value-service-inject-it"/>

Ou dentro do `beforeEach()` se você preferir injetar o service como parte de sua configuração.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="value-service-inject-before-each">
```
Ao testar um service com uma dependência, forneça o mock no array `providers`.

No exemplo seguinte, o mock é um objeto spy.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="master-service-before-each"/>

O teste consome aquele spy da mesma maneira que fez anteriormente.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="master-service-it"/>

## Testes sem `beforeEach()`

A maioria dos conjuntos de testes neste guia chama `beforeEach()` para definir as pré-condições para cada teste `it()` e depende do `TestBed` para criar classes e injetar services.

Há outra escola de testes que nunca chama `beforeEach()` e prefere criar classes explicitamente em vez de usar o `TestBed`.

Aqui está como você pode reescrever um dos testes `MasterService` nesse estilo.

Comece colocando código preparatório reutilizável em uma função _setup_ em vez de `beforeEach()`.

<docs-code header="app/demo/demo.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="no-before-each-setup"/>

A função `setup()` retorna um objeto literal com as variáveis, como `masterService`, que um teste pode referenciar.
Você não define variáveis _semi-globais_ $por exemplo, `let masterService: MasterService`$ no corpo do `describe()`.

Então cada teste invoca `setup()` em sua primeira linha, antes de continuar com passos que manipulam o subject do teste e afirmam expectations.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="no-before-each-test"/>

Observe como o teste usa [_destructuring assignment_](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) para extrair as variáveis de setup que ele precisa.

<docs-code path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="no-before-each-setup-call"/>

Muitos desenvolvedores sentem que esta abordagem é mais limpa e mais explícita do que o estilo tradicional `beforeEach()`.

Embora este guia de testes siga o estilo tradicional e os [schematics CLI](https://github.com/angular/angular-cli) padrão gerem arquivos de teste com `beforeEach()` e `TestBed`, sinta-se livre para adotar _esta abordagem alternativa_ em seus próprios projetos.

## Testes de services HTTP

Services de dados que fazem chamadas HTTP para servidores remotos normalmente injetam e delegam ao service [`HttpClient`](guide/http/testing) do Angular para chamadas XHR.

Você pode testar um service de dados com um spy `HttpClient` injetado como você testaria qualquer service com uma dependência.

<docs-code header="app/model/hero.service.spec.ts (tests with spies)" path="adev/src/content/examples/testing/src/app/model/hero.service.spec.ts" visibleRegion="test-with-spies"/>

IMPORTANTE: Os métodos `HeroService` retornam `Observables`.
Você deve _se inscrever_ em um observable para $a$ fazer com que ele execute e $b$ afirmar que o método teve sucesso ou falhou.

O método `subscribe()` recebe um callback de sucesso $`next`$ e falha $`error`$.
Certifique-se de fornecer _ambos_ os callbacks para que você capture erros.
Negligenciar isso produz um erro de observable assíncrono não capturado que o test runner provavelmente atribuirá a um teste completamente diferente.

## `HttpClientTestingModule`

Interações estendidas entre um service de dados e o `HttpClient` podem ser complexas e difíceis de simular com spies.

O `HttpClientTestingModule` pode tornar esses cenários de teste mais gerenciáveis.

Embora o _código de exemplo_ que acompanha este guia demonstre `HttpClientTestingModule`, esta página adia para o [guia Http](guide/http/testing), que cobre testes com o `HttpClientTestingModule` em detalhes.

# Fundamentos de testes de components

Um component, diferentemente de todas as outras partes de uma aplicação Angular, combina um template HTML e uma classe TypeScript.
O component é verdadeiramente o template e a classe _trabalhando juntos_.
Para testar adequadamente um component, você deve testar que eles funcionam juntos conforme pretendido.

Tais testes exigem criar o elemento host do component no DOM do browser, assim como o Angular faz, e investigar a interação da classe do component com o DOM conforme descrito pelo seu template.

O `TestBed` do Angular facilita esse tipo de teste, como você verá nas seções seguintes.
Mas em muitos casos, _testar apenas a classe do component_, sem envolvimento do DOM, pode validar muito do comportamento do component de forma direta e mais óbvia.

## Testes DOM de component

Um component é mais do que apenas sua classe.
Um component interage com o DOM e com outros components.
Classes sozinhas não podem dizer se o component vai renderizar corretamente, responder a entradas e gestos do usuário, ou integrar com seus components pai e filho.

- O `Lightswitch.clicked()` está vinculado a algo de modo que o usuário possa invocá-lo?
- A `Lightswitch.message` é exibida?
- O usuário pode realmente selecionar o hero exibido por `DashboardHeroComponent`?
- O nome do hero é exibido conforme esperado $como em maiúsculas$?
- A mensagem de boas-vindas é exibida pelo template de `WelcomeComponent`?

Estas podem não ser questões problemáticas para os components simples precedentes ilustrados.
Mas muitos components têm interações complexas com os elementos DOM descritos em seus templates, fazendo com que HTML apareça e desapareça conforme o estado do component muda.

Para responder a esses tipos de perguntas, você precisa criar os elementos DOM associados aos components, deve examinar o DOM para confirmar que o estado do component é exibido corretamente nos momentos apropriados, e deve simular a interação do usuário com a tela para determinar se essas interações fazem o component se comportar conforme esperado.

Para escrever esses tipos de teste, você usará recursos adicionais do `TestBed`, bem como outros helpers de teste.

### Testes gerados pela CLI

A CLI cria um arquivo de teste inicial para você por padrão quando você pede para gerar um novo component.

Por exemplo, o seguinte comando da CLI gera um `BannerComponent` na pasta `app/banner` $com template e estilos inline$:

```shell
ng generate component banner --inline-template --inline-style --module app
```
Ele também gera um arquivo de teste inicial para o component, `banner-external.component.spec.ts`, que se parece com isto:

<docs-code header="app/banner/banner-external.component.spec.ts (inicial)" path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v1"/>

ÚTIL: Como `compileComponents` é assíncrono, ele usa a função utilitária [`waitForAsync`](api/core/testing/waitForAsync) importada de `@angular/core/testing`.

Consulte a seção [waitForAsync](guide/testing/components-scenarios#waitForAsync) para mais detalhes.

### Reduzir a configuração

Apenas as últimas três linhas deste arquivo realmente testam o component e tudo o que fazem é afirmar que o Angular pode criar o component.

O resto do arquivo é código de configuração boilerplate antecipando testes mais avançados que _podem_ se tornar necessários se o component evoluir para algo substancial.

Você aprenderá sobre esses recursos avançados de teste nas seções seguintes.
Por enquanto, você pode reduzir radicalmente este arquivo de teste para um tamanho mais gerenciável:

<docs-code header="app/banner/banner-initial.component.spec.ts (mínimo)" path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v2"/>

Neste exemplo, o objeto de metadata passado para `TestBed.configureTestingModule` simplesmente declara `BannerComponent`, o component a ser testado.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="configureTestingModule"/>

ÚTIL: Não há necessidade de declarar ou importar mais nada.
O module de teste padrão é pré-configurado com algo como o `BrowserModule` de `@angular/platform-browser`.

Mais tarde você chamará `TestBed.configureTestingModule()` com imports, providers e mais declarações para atender às suas necessidades de teste.
Métodos `override` opcionais podem ajustar ainda mais aspectos da configuração.

### `createComponent()`

Após configurar o `TestBed`, você chama seu método `createComponent()`.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="createComponent"/>

`TestBed.createComponent()` cria uma instância do `BannerComponent`, adiciona um elemento correspondente ao DOM do test-runner e retorna um [`ComponentFixture`](#componentfixture).

IMPORTANTE: Não reconfigure o `TestBed` após chamar `createComponent`.

O método `createComponent` congela a definição atual do `TestBed`, fechando-o para configuração adicional.

Você não pode chamar mais nenhum método de configuração do `TestBed`, nem `configureTestingModule()`, nem `get()`, nem qualquer um dos métodos `override...`.
Se você tentar, o `TestBed` lança um erro.

### `ComponentFixture`

O [ComponentFixture](api/core/testing/ComponentFixture) é um test harness para interagir com o component criado e seu elemento correspondente.

Acesse a instância do component através do fixture e confirme que ela existe com uma expectation do Jasmine:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="componentInstance"/>

### `beforeEach()`

Você adicionará mais testes conforme este component evolui.
Em vez de duplicar a configuração do `TestBed` para cada teste, você refatora para colocar a configuração em um `beforeEach()` do Jasmine e algumas variáveis de suporte:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v3"/>

Agora adicione um teste que obtém o elemento do component de `fixture.nativeElement` e procura pelo texto esperado.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-2"/>

### `nativeElement`

O valor de `ComponentFixture.nativeElement` tem o tipo `any`.
Mais tarde você encontrará o `DebugElement.nativeElement` e ele também tem o tipo `any`.

O Angular não pode saber em tempo de compilação que tipo de elemento HTML o `nativeElement` é ou se é mesmo um elemento HTML.
A aplicação pode estar sendo executada em uma _plataforma não-browser_, como o servidor ou um [Web Worker](https://developer.mozilla.org/docs/Web/API/Web_Workers_API), onde o elemento pode ter uma API reduzida ou não existir de modo algum.

Os testes neste guia são projetados para executar em um browser, então um valor `nativeElement` sempre será um `HTMLElement` ou uma de suas classes derivadas.

Sabendo que é um `HTMLElement` de algum tipo, use o `querySelector` padrão HTML para mergulhar mais fundo na árvore de elementos.

Aqui está outro teste que chama `HTMLElement.querySelector` para obter o elemento de parágrafo e procurar pelo texto do banner:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-3"/>

### `DebugElement`

O _fixture_ do Angular fornece o elemento do component diretamente através de `fixture.nativeElement`.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="nativeElement"/>

Isto é na verdade um método de conveniência, implementado como `fixture.debugElement.nativeElement`.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="debugElement-nativeElement"/>

Há uma boa razão para este caminho tortuoso até o elemento.

As propriedades do `nativeElement` dependem do ambiente de runtime.
Você pode estar executando esses testes em uma plataforma _não-browser_ que não tem um DOM ou cuja emulação de DOM não suporta a API completa do `HTMLElement`.

O Angular depende da abstração `DebugElement` para funcionar com segurança em _todas as plataformas suportadas_.
Em vez de criar uma árvore de elementos HTML, o Angular cria uma árvore `DebugElement` que envolve os _elementos nativos_ para a plataforma de runtime.
A propriedade `nativeElement` desempacota o `DebugElement` e retorna o objeto de elemento específico da plataforma.

Como os testes de exemplo deste guia são projetados para executar apenas em um browser, um `nativeElement` nesses testes é sempre um `HTMLElement` cujos métodos e propriedades familiares você pode explorar dentro de um teste.

Aqui está o teste anterior, reimplementado com `fixture.debugElement.nativeElement`:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-4"/>

O `DebugElement` tem outros métodos e propriedades que são úteis em testes, como você verá em outros lugares neste guia.

Você importa o símbolo `DebugElement` da biblioteca core do Angular.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="import-debug-element"/>

### `By.css()`

Embora os testes neste guia sejam todos executados no browser, algumas aplicações podem executar em uma plataforma diferente pelo menos parte do tempo.

Por exemplo, o component pode renderizar primeiro no servidor como parte de uma estratégia para fazer a aplicação iniciar mais rápido em dispositivos com conexão ruim.
O renderer server-side pode não suportar a API completa de elementos HTML.
Se ele não suportar `querySelector`, o teste anterior poderia falhar.

O `DebugElement` oferece métodos de query que funcionam para todas as plataformas suportadas.
Esses métodos de query recebem uma função _predicate_ que retorna `true` quando um nó na árvore `DebugElement` corresponde aos critérios de seleção.

Você cria um _predicate_ com a ajuda de uma classe `By` importada de uma biblioteca para a plataforma de runtime.
Aqui está o import `By` para a plataforma browser:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="import-by"/>

O exemplo seguinte reimplementa o teste anterior com `DebugElement.query()` e o método `By.css` do browser.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-5"/>

Algumas observações notáveis:

- O método estático `By.css()` seleciona nós `DebugElement` com um [seletor CSS padrão](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors 'CSS selectors').
- A query retorna um `DebugElement` para o parágrafo.
- Você deve desempacotar esse resultado para obter o elemento de parágrafo.

Quando você está filtrando por seletor CSS e testando apenas propriedades de um _elemento nativo_ do browser, a abordagem `By.css` pode ser excessiva.

Geralmente é mais direto e claro filtrar com um método `HTMLElement` padrão como `querySelector()` ou `querySelectorAll()`.

# Cenários de testes de components

Este guia explora casos de uso comuns de testes de components.

## Binding de component

Na aplicação de exemplo, o `BannerComponent` apresenta texto de título estático no template HTML.

Após algumas mudanças, o `BannerComponent` apresenta um título dinâmico fazendo binding com a propriedade `title` do component assim.

```
Por mais mínimo que seja, você decide adicionar um teste para confirmar que o component realmente exibe o conteúdo correto onde você pensa que deveria.

### Query para o `<h1>`

Você escreverá uma sequência de testes que inspecionam o valor do elemento `<h1>` que envolve o binding de interpolação da propriedade _title_.

Você atualiza o `beforeEach` para encontrar esse elemento com um `querySelector` HTML padrão e atribuí-lo à variável `h1`.

<docs-code header="app/banner/banner.component.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="setup"/>

### `createComponent()` não faz bind de dados

Para seu primeiro teste, você gostaria de ver que a tela exibe o `title` padrão.
Seu instinto é escrever um teste que imediatamente inspeciona o `<h1>` assim:

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="expect-h1-default-v1"/>

_Esse teste falha_ com a mensagem:

<docs-code language="javascript">

expected '' to contain 'Test Tour of Heroes'.
```
Binding acontece quando o Angular executa **change detection**.

Em produção, change detection é acionado automaticamente quando o Angular cria um component ou o usuário pressiona uma tecla, por exemplo.

O `TestBed.createComponent` não aciona change detection por padrão; um fato confirmado no teste revisado:

```
### `detectChanges()`

Você pode dizer ao `TestBed` para executar data binding chamando `fixture.detectChanges()`.
Somente então o `<h1>` tem o título esperado.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="expect-h1-default"/>

Change detection atrasado é intencional e útil.
Ele dá ao testador uma oportunidade de inspecionar e alterar o estado do component _antes que o Angular inicie data binding e chame [lifecycle hooks](guide/components/lifecycle)_.

Aqui está outro teste que altera a propriedade `title` do component _antes_ de chamar `fixture.detectChanges()`.

<docs-code path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="after-change"/>

### Change detection automático

Os testes de `BannerComponent` frequentemente chamam `detectChanges`.
Muitos testadores preferem que o ambiente de teste do Angular execute change detection automaticamente como faz em produção.

Isso é possível configurando o `TestBed` com o provider `ComponentFixtureAutoDetect`.
Primeiro importe-o da biblioteca utilitária de testes:

<docs-code header="app/banner/banner.component.detect-changes.spec.ts (import)" path="adev/src/content/examples/testing/src/app/banner/banner.component.detect-changes.spec.ts" visibleRegion="import-ComponentFixtureAutoDetect"/>

Então adicione-o ao array `providers` da configuração do module de teste:

<docs-code header="app/banner/banner.component.detect-changes.spec.ts (AutoDetect)" path="adev/src/content/examples/testing/src/app/banner/banner.component.detect-changes.spec.ts" visibleRegion="auto-detect"/>

ÚTIL: Você também pode usar a função `fixture.autoDetectChanges()` se quiser apenas ativar change detection automático
após fazer atualizações no estado do component do fixture. Além disso, change detection automático é ativado por padrão
quando se usa `provideZonelessChangeDetection` e desativá-lo não é recomendado.

Aqui estão três testes que ilustram como change detection automático funciona.

<docs-code header="app/banner/banner.component.detect-changes.spec.ts (AutoDetect Tests)" path="adev/src/content/examples/testing/src/app/banner/banner.component.detect-changes.spec.ts" visibleRegion="auto-detect-tests"/>

O primeiro teste mostra o benefício de change detection automático.

O segundo e terceiro testes revelam uma limitação importante.
O ambiente de testes do Angular não executa change detection sincronamente quando atualizações acontecem dentro do caso de teste que alterou o `title` do component.
O teste deve chamar `await fixture.whenStable` para esperar por outra rodada de change detection.

ÚTIL: O Angular não sabe sobre atualizações diretas em valores que não são signals. A maneira mais fácil de garantir que
change detection seja agendado é usar signals para valores lidos no template.

### Alterar um valor de input com `dispatchEvent()`

Para simular entrada do usuário, encontre o elemento input e defina sua propriedade `value`.

Mas há um passo essencial e intermediário.

O Angular não sabe que você definiu a propriedade `value` do elemento input.
Ele não lerá essa propriedade até que você acione o evento `input` do elemento chamando `dispatchEvent()`.

O exemplo seguinte demonstra a sequência adequada.

<docs-code header="app/hero/hero-detail.component.spec.ts (pipe test)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="title-case-pipe"/>

## Component com arquivos externos

O `BannerComponent` anterior é definido com um _template inline_ e _css inline_, especificados nas propriedades `@Component.template` e `@Component.styles` respectivamente.

Muitos components especificam _templates externos_ e _css externo_ com as propriedades `@Component.templateUrl` e `@Component.styleUrls` respectivamente, como a seguinte variante de `BannerComponent` faz.

<docs-code header="app/banner/banner-external.component.ts (metadata)" path="adev/src/content/examples/testing/src/app/banner/banner-external.component.ts" visibleRegion="metadata"/>

Esta sintaxe diz ao compilador Angular para ler os arquivos externos durante a compilação do component.

Isso não é um problema quando você executa o comando `ng test` da CLI porque ele _compila a aplicação antes de executar os testes_.

No entanto, se você executar os testes em um **ambiente não-CLI**, testes deste component podem falhar.
Por exemplo, se você executar os testes de `BannerComponent` em um ambiente de codificação web como [plunker](https://plnkr.co), você verá uma mensagem como esta:

<docs-code hideCopy language="shell">

Error: This test module uses the component BannerComponent
which is using a "templateUrl" or "styleUrls", but they were never compiled.
Please call "TestBed.compileComponents" before your test.
```
Você obtém esta mensagem de falha de teste quando o ambiente de runtime compila o código fonte _durante os próprios testes_.

Para corrigir o problema, chame `compileComponents()`.

## Component com uma dependência

Components frequentemente têm dependências de services.

O `WelcomeComponent` exibe uma mensagem de boas-vindas ao usuário logado.
Ele sabe quem é o usuário com base em uma propriedade do `UserService` injetado:

```
O `WelcomeComponent` tem lógica de decisão que interage com o service, lógica que torna este component digno de teste.

### Fornecer test doubles de service

Um _component-under-test_ não precisa receber services reais.

Injetar o `UserService` real poderia ser difícil.
O service real pode pedir credenciais de login do usuário e tentar alcançar um servidor de autenticação.
Esses comportamentos podem ser difíceis de interceptar. Esteja ciente de que usar test doubles faz o teste se comportar de forma diferente da produção, então use-os com moderação.

### Obter services injetados

Os testes precisam de acesso ao `UserService` injetado no `WelcomeComponent`.

O Angular tem um sistema de injeção hierárquico.
Pode haver injectors em múltiplos níveis, do injector raiz criado pelo `TestBed` até a árvore de components.

A maneira mais segura de obter o service injetado, a maneira que **_sempre funciona_**,
é **obtê-lo do injector do _component-under-test_**.
O injector do component é uma propriedade do `DebugElement` do fixture.

<docs-code header="WelcomeComponent's injector" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="injected-service"/>

ÚTIL: Isso _geralmente_ não é necessário. Services são frequentemente fornecidos na raiz ou o TestBed os sobrescreve e podem ser recuperados mais facilmente com `TestBed.inject()` (veja abaixo).

### `TestBed.inject()`

Isso é mais fácil de lembrar e menos verboso do que recuperar um service usando o `DebugElement` do fixture.

Neste conjunto de testes, o _único_ provider de `UserService` é o module de teste raiz, então é seguro chamar `TestBed.inject()` da seguinte forma:

<docs-code header="TestBed injector" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="inject-from-testbed" />

ÚTIL: Para um caso de uso em que `TestBed.inject()` não funciona, veja a seção [_Override component providers_](#override-component-providers) que explica quando e por que você deve obter o service do injector do component.

### Configuração final e testes

Aqui está o `beforeEach()` completo, usando `TestBed.inject()`:

<docs-code header="app/welcome/welcome.component.spec.ts" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="setup"/>

E aqui estão alguns testes:

<docs-code header="app/welcome/welcome.component.spec.ts" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="tests"/>

O primeiro é um teste de sanidade; ele confirma que o `UserService` é chamado e está funcionando.

ÚTIL: A função withContext $por exemplo, `'expected name'`$ é um rótulo de falha opcional.
Se a expectation falhar, o Jasmine anexa este rótulo à mensagem de falha da expectation.
Em uma spec com múltiplas expectations, pode ajudar a esclarecer o que deu errado e qual expectation falhou.

Os testes restantes confirmam a lógica do component quando o service retorna valores diferentes.
O segundo teste valida o efeito de alterar o nome do usuário.
O terceiro teste verifica que o component exibe a mensagem adequada quando não há usuário logado.

## Component com service assíncrono

Neste exemplo, o template `AboutComponent` hospeda um `TwainComponent`.
O `TwainComponent` exibe citações de Mark Twain.

<docs-code header="app/twain/twain.component.ts (template)" path="adev/src/content/examples/testing/src/app/twain/twain.component.ts" visibleRegion="template" />

ÚTIL: O valor da propriedade `quote` do component passa por um `AsyncPipe`.
Isso significa que a propriedade retorna ou uma `Promise` ou um `Observable`.

Neste exemplo, o método `TwainComponent.getQuote()` diz que a propriedade `quote` retorna um `Observable`.

<docs-code header="app/twain/twain.component.ts (getQuote)" path="adev/src/content/examples/testing/src/app/twain/twain.component.ts" visibleRegion="get-quote"/>

O `TwainComponent` obtém citações de um `TwainService` injetado.
O component inicia o `Observable` retornado com um valor placeholder $`'...'`$, antes que o service possa retornar sua primeira citação.

O `catchError` intercepta erros do service, prepara uma mensagem de erro e retorna o valor placeholder no canal de sucesso.

Estes são todos recursos que você vai querer testar.

### Testes com um spy

Ao testar um component, apenas a API pública do service deve importar.
Em geral, os próprios testes não devem fazer chamadas a servidores remotos.
Eles devem emular tais chamadas.
A configuração neste `app/twain/twain.component.spec.ts` mostra uma maneira de fazer isso:

<docs-code header="app/twain/twain.component.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="setup"/>

Foque no spy.

<docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="spy"/>

O spy é projetado de modo que qualquer chamada a `getQuote` recebe um observable com uma citação de teste.
Diferentemente do método `getQuote()` real, este spy ignora o servidor e retorna um observable síncrono cujo valor está disponível imediatamente.

Você pode escrever muitos testes úteis com este spy, mesmo que seu `Observable` seja síncrono.

ÚTIL: É melhor limitar o uso de spies apenas ao que é necessário para o teste. Criar mocks ou spies para mais do que o necessário pode ser frágil. À medida que o component e o injectable evoluem, os testes não relacionados podem falhar porque não simulam mais comportamentos suficientes que de outra forma não afetariam o teste.

### Teste assíncrono com `fakeAsync()`

Para usar a funcionalidade `fakeAsync()`, você deve importar `zone.js/testing` no seu arquivo de configuração de teste.
Se você criou seu projeto com a Angular CLI, `zone-testing` já está importado em `src/test.ts`.

O teste seguinte confirma o comportamento esperado quando o service retorna um `ErrorObservable`.

<docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="error-test"/>

ÚTIL: A função `it()` recebe um argumento da seguinte forma.

<docs-code language="javascript">

fakeAsync(() => { /_test body_/ })
```
A função `fakeAsync()` habilita um estilo de codificação linear executando o corpo do teste em uma `fakeAsync test zone` especial.
O corpo do teste parece ser síncrono.
Não há sintaxe aninhada $como um `Promise.then()`$ para interromper o fluxo de controle.

ÚTIL: Limitação: A função `fakeAsync()` não funcionará se o corpo do teste fizer uma chamada `XMLHttpRequest` $XHR$.
Chamadas XHR dentro de um teste são raras, mas se você precisar chamar XHR, use `waitForAsync()`.

IMPORTANTE: Esteja ciente de que tarefas assíncronas que acontecem dentro da zona `fakeAsync` precisam ser executadas manualmente com `flush` ou `tick`. Se você tentar
aguardar que elas sejam concluídas (ou seja, usando `fixture.whenStable`) sem usar os
helpers de teste `fakeAsync` para avançar o tempo, seu teste provavelmente falhará. Veja abaixo para mais informações.

### A função `tick()`

Você precisa chamar [tick()](api/core/testing/tick) para avançar o relógio virtual.

Chamar [tick()](api/core/testing/tick) simula a passagem do tempo até que todas as atividades assíncronas pendentes terminem.
Neste caso, ele espera pelo `setTimeout()` do observable.

A função [tick()](api/core/testing/tick) aceita `millis` e `tickOptions` como parâmetros. O parâmetro `millis` especifica quanto o relógio virtual avança e o padrão é `0` se não fornecido.
Por exemplo, se você tiver um `setTimeout(fn, 100)` em um teste `fakeAsync()`, você precisa usar `tick(100)` para acionar o callback fn.
O parâmetro `tickOptions` opcional tem uma propriedade chamada `processNewMacroTasksSynchronously`. A propriedade `processNewMacroTasksSynchronously` representa se deve invocar novas macro tasks geradas ao fazer tick e o padrão é `true`.

```
A função [tick()](api/core/testing/tick) é um dos utilitários de teste do Angular que você importa com `TestBed`.
É uma companheira de `fakeAsync()` e você só pode chamá-la dentro de um corpo `fakeAsync()`.

### tickOptions

Neste exemplo, você tem uma nova macro task, a função `setTimeout` aninhada. Por padrão, quando o `tick` é setTimeout, `outside` e `nested` serão ambos acionados.

<docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-tick-new-macro-task-sync"/>

Em alguns casos, você não quer acionar a nova macro task ao fazer tick. Você pode usar `tick(millis, {processNewMacroTasksSynchronously: false})` para não invocar uma nova macro task.

<docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-tick-new-macro-task-async"/>

### Comparando datas dentro de fakeAsync()

`fakeAsync()` simula a passagem do tempo, o que permite calcular a diferença entre datas dentro de `fakeAsync()`.

<docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-date"/>

### jasmine.clock com fakeAsync()

O Jasmine também fornece um recurso `clock` para simular datas.
O Angular executa automaticamente testes que são executados após `jasmine.clock().install()` ser chamado dentro de um método `fakeAsync()` até que `jasmine.clock().uninstall()` seja chamado.
`fakeAsync()` não é necessário e lança um erro se aninhado.

Por padrão, este recurso está desabilitado.
Para habilitá-lo, defina uma flag global antes de importar `zone-testing`.

Se você usa a Angular CLI, configure esta flag em `src/test.ts`.

<docs-code language="typescript">

[window as any]('__zone_symbol__fakeAsyncPatchLock') = true;
import 'zone.js/testing';
```
```
### Usando o scheduler RxJS dentro de fakeAsync()

Você também pode usar o scheduler RxJS em `fakeAsync()` assim como usar `setTimeout()` ou `setInterval()`, mas você precisa importar `zone.js/plugins/zone-patch-rxjs-fake-async` para aplicar patch no scheduler RxJS.

<docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-rxjs"/>

### Suportar mais macroTasks

Por padrão, `fakeAsync()` suporta as seguintes macro tasks.

- `setTimeout`
- `setInterval`
- `requestAnimationFrame`
- `webkitRequestAnimationFrame`
- `mozRequestAnimationFrame`

Se você executar outras macro tasks como `HTMLCanvasElement.toBlob()`, um erro _"Unknown macroTask scheduled in fake async test"_ é lançado.
Se você quiser suportar tal caso, você precisa definir a macro task que quer suportar em `beforeEach()`.
Por exemplo:

<docs-code header="src/app/shared/canvas.component.spec.ts (excerpt)" path="adev/src/content/examples/testing/src/app/shared/canvas.component.spec.ts" visibleRegion="enable-toBlob-macrotask"/>

ÚTIL: Para tornar o elemento `<canvas>` ciente do Zone.js em sua aplicação, você precisa importar o patch `zone-patch-canvas` $seja em `polyfills.ts` ou no arquivo específico que usa `<canvas>`$:

<docs-code header="src/polyfills.ts or src/app/shared/canvas.component.ts" path="adev/src/content/examples/testing/src/app/shared/canvas.component.ts" visibleRegion="import-canvas-patch"/>

### Observables assíncronos

Você pode estar satisfeito com a cobertura de testes desses testes.

No entanto, você pode estar preocupado com o fato de que o service real não se comporta exatamente assim.
O service real envia requisições a um servidor remoto.
Um servidor leva tempo para responder e a resposta certamente não estará disponível imediatamente como nos dois testes anteriores.

Seus testes refletirão o mundo real com mais fidelidade se você retornar um observable _assíncrono_ do spy `getQuote()` assim.

<docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="async-setup"/>

### Helpers de observable assíncrono

O observable assíncrono foi produzido por um helper `asyncData`.
O helper `asyncData` é uma função utilitária que você terá que escrever você mesmo, ou copiar esta do código de exemplo.

<docs-code header="testing/async-observable-helpers.ts" path="adev/src/content/examples/testing/src/testing/async-observable-helpers.ts" visibleRegion="async-data"/>

Este observable do helper emite o valor `data` no próximo turno do motor JavaScript.

O [operador `defer()` do RxJS](http://reactivex.io/documentation/operators/defer.html) retorna um observable.
Ele recebe uma função factory que retorna uma promise ou um observable.
Quando algo se inscreve no observable do _defer_, ele adiciona o subscriber a um novo observable criado com aquela factory.

O operador `defer()` transforma o `Promise.resolve()` em um novo observable que, como `HttpClient`, emite uma vez e completa.
Subscribers são desincritos após receberem o valor de dados.

Há um helper similar para produzir um erro assíncrono.

<docs-code path="adev/src/content/examples/testing/src/testing/async-observable-helpers.ts" visibleRegion="async-error"/>

### Mais testes assíncronos

Agora que o spy `getQuote()` está retornando observables assíncronos, a maioria de seus testes terá que ser assíncrona também.

Aqui está um teste `fakeAsync()` que demonstra o fluxo de dados que você esperaria no mundo real.

<docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="fake-async-test"/>

Observe que o elemento de citação exibe o valor placeholder $`'...'`$ após `ngOnInit()`.
A primeira citação ainda não chegou.

Para liberar a primeira citação do observable, você chama [tick()](api/core/testing/tick).
Então chame `detectChanges()` para dizer ao Angular para atualizar a tela.

Então você pode afirmar que o elemento de citação exibe o texto esperado.

### Teste assíncrono sem `fakeAsync()`

Aqui está o teste `fakeAsync()` anterior, reescrito com `async`.

<docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="async-test"/>

### `whenStable`

O teste deve esperar que o observable `getQuote()` emita a próxima citação.
Em vez de chamar [tick()](api/core/testing/tick), ele chama `fixture.whenStable()`.

O `fixture.whenStable()` retorna uma promise que resolve quando a fila de tarefas do motor JavaScript fica vazia.
Neste exemplo, a fila de tarefas fica vazia quando o observable emite a primeira citação.

## Component com inputs e outputs

Um component com inputs e outputs normalmente aparece dentro do template de view de um component host.
O host usa um property binding para definir a propriedade input e um event binding para ouvir eventos levantados pela propriedade output.

O objetivo do teste é verificar que tais bindings funcionam conforme esperado.
Os testes devem definir valores input e ouvir eventos output.

O `DashboardHeroComponent` é um pequeno exemplo de um component neste papel.
Ele exibe um hero individual fornecido pelo `DashboardComponent`.
Clicar naquele hero diz ao `DashboardComponent` que o usuário selecionou o hero.

O `DashboardHeroComponent` é incorporado no template `DashboardComponent` assim:

<docs-code header="app/dashboard/dashboard.component.html (excerpt)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard.component.html" visibleRegion="dashboard-hero"/>

O `DashboardHeroComponent` aparece em um bloco `@for`, que define a propriedade input `hero` de cada component para o valor em loop e ouve o evento `selected` do component.

Aqui está a definição completa do component:

<docs-code header="app/dashboard/dashboard-hero.component.ts (component)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.ts" visibleRegion="component"/>

Embora testar um component tão simples tenha pouco valor intrínseco, vale a pena saber como.
Use uma dessas abordagens:

- Teste-o como usado por `DashboardComponent`
- Teste-o como um component autônomo
- Teste-o como usado por um substituto para `DashboardComponent`

O objetivo imediato é testar o `DashboardHeroComponent`, não o `DashboardComponent`, então tente a segunda e terceira opções.

### Testar `DashboardHeroComponent` autônomo {#provide-a-spy-stub-herodetailservicespy}

Aqui está a parte principal da configuração do arquivo spec.

<docs-code header="app/dashboard/dashboard-hero.component.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="setup"/>

Observe como o código de configuração atribui um hero de teste $`expectedHero`$ à propriedade `hero` do component, emulando a maneira como o `DashboardComponent` a definiria usando o property binding em seu repetidor.

O teste seguinte verifica que o nome do hero é propagado para o template usando um binding.

<docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="name-test"/>

Como o template passa o nome do hero através do `UpperCasePipe` do Angular, o teste deve corresponder o valor do elemento com o nome em maiúsculas.

### Clicar

Clicar no hero deve acionar um evento `selected` que o component host $presumivelmente `DashboardComponent`$ pode ouvir:

<docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="click-test"/>

A propriedade `selected` do component retorna um `EventEmitter`, que parece um `Observable` síncrono RxJS para consumidores.
O teste se inscreve nele _explicitamente_ assim como o component host faz _implicitamente_.

Se o component se comporta como esperado, clicar no elemento do hero deve dizer à propriedade `selected` do component para emitir o objeto `hero`.

O teste detecta aquele evento através de sua inscrição em `selected`.

### `triggerEventHandler`

O `heroDe` no teste anterior é um `DebugElement` que representa o `<div>` do hero.

Ele tem propriedades e métodos do Angular que abstraem a interação com o elemento nativo.
Este teste chama o `DebugElement.triggerEventHandler` com o nome do evento "click".
O binding do evento "click" responde chamando `DashboardHeroComponent.click()`.

O `DebugElement.triggerEventHandler` do Angular pode acionar _qualquer evento data-bound_ por seu _nome de evento_.
O segundo parâmetro é o objeto de evento passado ao handler.

O teste acionou um evento "click".

<docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="trigger-event-handler"/>

Neste caso, o teste assume corretamente que o handler de evento runtime, o método `click()` do component, não se importa com o objeto de evento.

ÚTIL: Outros handlers são menos tolerantes.
Por exemplo, a directive `RouterLink` espera um objeto com uma propriedade `button` que identifica qual botão do mouse, se houver, foi pressionado durante o clique.
A directive `RouterLink` lança um erro se o objeto de evento estiver faltando.

### Clicar no elemento

A seguinte alternativa de teste chama o método `click()` próprio do elemento nativo, o que é perfeitamente adequado para _este component_.

<docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="click-test-2"/>

### Helper `click()`

Clicar em um botão, uma âncora ou um elemento HTML arbitrário é uma tarefa de teste comum.

Torne isso consistente e direto encapsulando o processo de _acionamento de clique_ em um helper como a seguinte função `click()`:

<docs-code header="testing/index.ts (click helper)" path="adev/src/content/examples/testing/src/testing/index.ts" visibleRegion="click-event"/>

O primeiro parâmetro é o _elemento-para-clicar_.
Se quiser, passe um objeto de evento personalizado como segundo parâmetro.
O padrão é um [objeto de evento de mouse de botão esquerdo](https://developer.mozilla.org/docs/Web/API/MouseEvent/button) parcial aceito por muitos handlers incluindo a directive `RouterLink`.

IMPORTANTE: A função helper `click()` **não** é um dos utilitários de teste do Angular.
É uma função definida no _código de exemplo deste guia_.
Todos os testes de exemplo a usam.
Se você gostar, adicione-a à sua própria coleção de helpers.

Aqui está o teste anterior, reescrito usando o helper click.

<docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test with click helper)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="click-test-3"/>

## Component dentro de um test host

Os testes anteriores desempenharam o papel do `DashboardComponent` host eles mesmos.
Mas o `DashboardHeroComponent` funciona corretamente quando adequadamente vinculado por data-binding a um component host?

<docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test host)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="test-host"/>

O test host define a propriedade input `hero` do component com seu hero de teste.
Ele vincula o evento `selected` do component com seu handler `onSelected`, que registra o hero emitido em sua propriedade `selectedHero`.

Mais tarde, os testes poderão verificar `selectedHero` para verificar que o evento `DashboardHeroComponent.selected` emitiu o hero esperado.

A configuração para os testes `test-host` é similar à configuração para os testes autônomos:

<docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test host setup)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="test-host-setup"/>

Esta configuração do module de testes mostra duas diferenças importantes:

- Ele _cria_ o `TestHostComponent` em vez do `DashboardHeroComponent`
- O `TestHostComponent` define o `DashboardHeroComponent.hero` com um binding

O `createComponent` retorna um `fixture` que contém uma instância de `TestHostComponent` em vez de uma instância de `DashboardHeroComponent`.

Criar o `TestHostComponent` tem o efeito colateral de criar um `DashboardHeroComponent` porque o último aparece dentro do template do primeiro.
A query para o elemento hero $`heroEl`$ ainda o encontra no DOM de teste, embora a maior profundidade na árvore de elementos do que antes.

Os próprios testes são quase idênticos à versão autônoma:

<docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test-host)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="test-host-tests"/>

Apenas o teste do evento selected difere.
Ele confirma que o hero `DashboardHeroComponent` selecionado realmente encontra seu caminho através do event binding até o component host.

## Routing component

Um _routing component_ é um component que diz ao `Router` para navegar para outro component.
O `DashboardComponent` é um _routing component_ porque o usuário pode navegar para o `HeroDetailComponent` clicando em um dos _botões de hero_ no dashboard.

O Angular fornece helpers de teste para reduzir boilerplate e testar código de forma mais eficaz que depende de `HttpClient`. A função `provideRouter` também pode ser usada diretamente no module de teste.

<docs-code header="app/dashboard/dashboard.component.spec.ts" path="adev/src/content/examples/testing/src/app/dashboard/dashboard.component.spec.ts" visibleRegion="router-harness"/>

O teste seguinte clica no hero exibido e confirma que navegamos para a URL esperada.

<docs-code header="app/dashboard/dashboard.component.spec.ts (navigate test)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard.component.spec.ts" visibleRegion="navigate-test"/>

## Routed components

Um _routed component_ é o destino de uma navegação do `Router`.
Pode ser mais complicado de testar, especialmente quando a rota para o component _inclui parâmetros_.
O `HeroDetailComponent` é um _routed component_ que é o destino de tal rota.

Quando um usuário clica em um hero do _Dashboard_, o `DashboardComponent` diz ao `Router` para navegar para `heroes/:id`.
O `:id` é um parâmetro de rota cujo valor é o `id` do hero a ser editado.

O `Router` corresponde aquela URL a uma rota para o `HeroDetailComponent`.
Ele cria um objeto `ActivatedRoute` com as informações de roteamento e o injeta em uma nova instância do `HeroDetailComponent`.

Aqui estão os services injetados no `HeroDetailComponent`:

<docs-code header="app/hero/hero-detail.component.ts (inject)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.ts" visibleRegion="inject"/>

O `HeroDetail` component precisa do parâmetro `id` para que possa buscar o hero correspondente usando o `HeroDetailService`.
O component tem que obter o `id` da propriedade `ActivatedRoute.paramMap` que é um `Observable`.

Ele não pode simplesmente referenciar a propriedade `id` do `ActivatedRoute.paramMap`.
O component tem que _se inscrever_ no observable `ActivatedRoute.paramMap` e estar preparado para o `id` mudar durante seu tempo de vida.

<docs-code header="app/hero/hero-detail.component.ts (constructor)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.ts" visibleRegion="ctor"/>

Os testes podem explorar como o `HeroDetailComponent` responde a diferentes valores do parâmetro `id` navegando para rotas diferentes.

## Testes de components aninhados

Templates de components frequentemente têm components aninhados, cujos templates podem conter mais components.

A árvore de components pode ser muito profunda e às vezes os components aninhados não desempenham papel algum em testar o component no topo da árvore.

O `AppComponent`, por exemplo, exibe uma barra de navegação com âncoras e suas directives `RouterLink`.

<docs-code header="app/app.component.html" path="adev/src/content/examples/testing/src/app/app.component.html"/>

Para validar os links mas não a navegação, você não precisa do `Router` para navegar e não precisa do `<router-outlet>` para marcar onde o `Router` insere _routed components_.

O `BannerComponent` e `WelcomeComponent` $indicados por `<app-banner>` e `<app-welcome>`$ também são irrelevantes.

No entanto, qualquer teste que cria o `AppComponent` no DOM também cria instâncias desses três components e, se você deixar isso acontecer, terá que configurar o `TestBed` para criá-los.

Se você negligenciar declará-los, o compilador Angular não reconhecerá as tags `<app-banner>`, `<app-welcome>` e `<router-outlet>` no template `AppComponent` e lançará um erro.

Se você declarar os components reais, também terá que declarar _seus_ components aninhados e fornecer _todos_ os services injetados em _qualquer_ component na árvore.

Esta seção descreve duas técnicas para minimizar a configuração.
Use-as, sozinhas ou em combinação, para permanecer focado em testar o component primário.

### Stubbing de components desnecessários

Na primeira técnica, você cria e declara versões stub dos components e directive que desempenham pouco ou nenhum papel nos testes.

<docs-code header="app/app.component.spec.ts (stub declaration)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="component-stubs"/>

Os seletores stub correspondem aos seletores dos components reais correspondentes.
Mas seus templates e classes estão vazios.

Então declare-os sobrescrevendo os `imports` do seu component usando `TestBed.overrideComponent`.

<docs-code header="app/app.component.spec.ts (TestBed stubs)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="testbed-stubs"/>

ÚTIL: A chave `set` neste exemplo substitui todos os imports existentes no seu component, certifique-se de importar todas as dependências, não apenas os stubs. Alternativamente, você pode usar as chaves `remove`/`add` para remover e adicionar imports seletivamente.

### `NO_ERRORS_SCHEMA`

Na segunda abordagem, adicione `NO_ERRORS_SCHEMA` aos overrides de metadata do seu component.

<docs-code header="app/app.component.spec.ts (NO_ERRORS_SCHEMA)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="no-errors-schema"/>

O `NO_ERRORS_SCHEMA` diz ao compilador Angular para ignorar elementos e atributos não reconhecidos.

O compilador reconhece o elemento `<app-root>` e o atributo `routerLink` porque você declarou um `AppComponent` e `RouterLink` correspondentes na configuração do `TestBed`.

Mas o compilador não lançará um erro quando encontrar `<app-banner>`, `<app-welcome>` ou `<router-outlet>`.
Ele simplesmente os renderiza como tags vazias e o browser os ignora.

Você não precisa mais dos stub components.

### Use ambas as técnicas juntas

Estas são técnicas para _Shallow Component Testing_, assim chamadas porque reduzem a superfície visual do component apenas àqueles elementos no template do component que importam para os testes.

A abordagem `NO_ERRORS_SCHEMA` é a mais fácil das duas, mas não a use em excesso.

O `NO_ERRORS_SCHEMA` também impede que o compilador diga sobre os components e atributos faltantes que você omitiu inadvertidamente ou digitou incorretamente.
Você pode desperdiçar horas perseguindo bugs fantasmas que o compilador teria capturado em um instante.

A abordagem de _stub component_ tem outra vantagem.
Embora os stubs neste _exemplo_ estivessem vazios, você poderia dar a eles templates e classes simplificados se seus testes precisarem interagir com eles de alguma forma.

Na prática, você combinará as duas técnicas na mesma configuração, como visto neste exemplo.

<docs-code header="app/app.component.spec.ts (mixed setup)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="mixed-setup"/>

O compilador Angular cria o `BannerStubComponent` para o elemento `<app-banner>` e aplica o `RouterLink` às âncoras com o atributo `routerLink`, mas ignora as tags `<app-welcome>` e `<router-outlet>`.

### `By.directive` e directives injetadas

Um pouco mais de configuração aciona o data binding inicial e obtém referências aos links de navegação:

<docs-code header="app/app.component.spec.ts (test setup)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="test-setup"/>

Três pontos de interesse especial:

- Localize os elementos âncora com uma directive anexada usando `By.directive`
- A query retorna wrappers `DebugElement` em torno dos elementos correspondentes
- Cada `DebugElement` expõe um dependency injector com a instância específica da directive anexada àquele elemento

Os links do `AppComponent` a validar são os seguintes:

<docs-code header="app/app.component.html (navigation links)" path="adev/src/content/examples/testing/src/app/app.component.html" visibleRegion="links"/>

Aqui estão alguns testes que confirmam que esses links estão conectados às directives `routerLink` conforme esperado:

<docs-code header="app/app.component.spec.ts (selected tests)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="tests"/>

## Usar um objeto `page`

O `HeroDetailComponent` é uma view simples com um título, dois campos hero e dois botões.

Mas há bastante complexidade de template mesmo neste formulário simples.

<docs-code
  path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.html" header="app/hero/hero-detail.component.html"/>

Testes que exercitam o component precisam …

- Esperar até que um hero chegue antes que elementos apareçam no DOM
- Uma referência ao texto do título
- Uma referência à caixa de input do nome para inspecioná-la e defini-la
- Referências aos dois botões para que possam clicar neles

Mesmo um formulário pequeno como este pode produzir uma confusão de configuração condicional torturada e seleção de elementos CSS.

Domar a complexidade com uma classe `Page` que lida com acesso a propriedades do component e encapsula a lógica que as define.

Aqui está tal classe `Page` para o `hero-detail.component.spec.ts`

<docs-code header="app/hero/hero-detail.component.spec.ts (Page)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="page"/>

Agora os hooks importantes para manipulação e inspeção do component estão organizados de forma organizada e acessíveis a partir de uma instância de `Page`.

Um método `createComponent` cria um objeto `page` e preenche os espaços em branco uma vez que o `hero` chega.

<docs-code header="app/hero/hero-detail.component.spec.ts (createComponent)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="create-component"/>

Aqui estão mais alguns testes `HeroDetailComponent` para reforçar o ponto.

<docs-code header="app/hero/hero-detail.component.spec.ts (selected tests)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="selected-tests"/>

## Override de component providers {#override-component-providers}

O `HeroDetailComponent` fornece seu próprio `HeroDetailService`.

<docs-code header="app/hero/hero-detail.component.ts (prototype)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.ts" visibleRegion="prototype"/>

Não é possível fazer stub do `HeroDetailService` do component nos `providers` do `TestBed.configureTestingModule`.
Esses são providers para o _module de teste_, não o component.
Eles preparam o dependency injector no _nível do fixture_.

O Angular cria o component com seu _próprio_ injector, que é um _filho_ do injector do fixture.
Ele registra os providers do component $o `HeroDetailService` neste caso$ com o injector filho.

Um teste não pode obter services do injector filho a partir do injector do fixture.
E `TestBed.configureTestingModule` também não pode configurá-los.

O Angular criou novas instâncias do `HeroDetailService` real o tempo todo!

ÚTIL: Esses testes podem falhar ou expirar se o `HeroDetailService` fizer suas próprias chamadas XHR a um servidor remoto.
Pode não haver um servidor remoto para chamar.

Felizmente, o `HeroDetailService` delega responsabilidade por acesso a dados remotos a um `HeroService` injetado.

<docs-code header="app/hero/hero-detail.service.ts (prototype)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.service.ts" visibleRegion="prototype"/>

A configuração de teste anterior substitui o `HeroService` real por um `TestHeroService` que intercepta requisições do servidor e falsifica suas respostas.

E se você não tiver tanta sorte.
E se falsificar o `HeroService` for difícil?
E se `HeroDetailService` fizer suas próprias requisições ao servidor?

O método `TestBed.overrideComponent` pode substituir os `providers` do component por _test doubles_ fáceis de gerenciar como visto na seguinte variação de configuração:

<docs-code header="app/hero/hero-detail.component.spec.ts (Override setup)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="setup-override"/>

Observe que `TestBed.configureTestingModule` não fornece mais um `HeroService` falso porque não é [necessário](#provide-a-spy-stub-herodetailservicespy).

### O método `overrideComponent`

Foque no método `overrideComponent`.

<docs-code header="app/hero/hero-detail.component.spec.ts (overrideComponent)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="override-component-method"/>

Ele recebe dois argumentos: o tipo de component a sobrescrever $`HeroDetailComponent`$ e um objeto de metadata de override.
O [objeto de metadata de override](guide/testing/utility-apis#metadata-override-object) é um genérico definido da seguinte forma:

<docs-code language="javascript">

type MetadataOverride<T> = {
add?: Partial<T>;
remove?: Partial<T>;
set?: Partial<T>;
};
```
Um objeto de metadata de override pode adicionar e remover elementos nas propriedades de metadata ou redefinir completamente essas propriedades.
Este exemplo redefine a metadata `providers` do component.

O parâmetro de tipo, `T`, é o tipo de metadata que você passaria para o decorator `@Component`:

```javascript
selector?: string;
template?: string;
templateUrl?: string;
providers?: any[];
…
```
### Fornecer um _spy stub_ (`HeroDetailServiceSpy`)

Este exemplo substitui completamente o array `providers` do component por um novo array contendo um `HeroDetailServiceSpy`.

O `HeroDetailServiceSpy` é uma versão stubbed do `HeroDetailService` real que falsifica todos os recursos necessários daquele service.
Ele nem injeta nem delega para o `HeroService` de nível inferior, então não há necessidade de fornecer um test double para isso.

Os testes `HeroDetailComponent` relacionados afirmarão que métodos do `HeroDetailService` foram chamados espiando os métodos do service.
Consequentemente, o stub implementa seus métodos como spies:

<docs-code header="app/hero/hero-detail.component.spec.ts (HeroDetailServiceSpy)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="hds-spy"/>

### Os testes de override

Agora os testes podem controlar o hero do component diretamente manipulando o `testHero` do spy-stub e confirmar que métodos do service foram chamados.

<docs-code header="app/hero/hero-detail.component.spec.ts (override tests)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="override-tests"/>

### Mais overrides

O método `TestBed.overrideComponent` pode ser chamado várias vezes para os mesmos ou diferentes components.
O `TestBed` oferece métodos similares `overrideDirective`, `overrideModule` e `overridePipe` para cavar e substituir partes dessas outras classes.

Explore as opções e combinações por conta própria.

# Debug de testes

Se seus testes não estão funcionando como você espera, você pode inspecioná-los e fazer debug deles no browser.

NOTA: Este guia descreve debug com o test runner Karma.

Para fazer debug de uma aplicação com o test runner Karma:

1. Revele a janela do browser Karma.
   Veja [Configurar testes](guide/testing#set-up-testing) se você precisar de ajuda com este passo.

1. Clique no botão **DEBUG** para abrir uma nova aba do browser e executar novamente os testes.
1. Abra as **Ferramentas do Desenvolvedor** do browser. No Windows, pressione `Ctrl-Shift-I`. No macOS, pressione `Command-Option-I`.
1. Escolha a seção **Sources**.
1. Pressione `Control/Command-P` e então comece a digitar o nome do seu arquivo de teste para abri-lo.
1. Defina um breakpoint no teste.
1. Atualize o browser e observe como ele para no breakpoint.

# APIs Utilitárias de Teste

Esta página descreve os recursos de teste do Angular mais úteis.

As utilitários de teste do Angular incluem o `TestBed`, o `ComponentFixture` e um punhado de funções que controlam o ambiente de teste.
As classes [`TestBed`](#testbed-class-summary) e [`ComponentFixture`](#the-componentfixture) são cobertas separadamente.

Aqui está um resumo das funções autônomas, em ordem de utilidade provável:

| Função                       | Detalhes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `waitForAsync`               | Executa o corpo de uma função de teste $`it`$ ou configuração $`beforeEach`$ dentro de uma _zona de teste assíncrona_ especial. Veja [waitForAsync](guide/testing/components-scenarios#waitForAsync).                                                                                                                                                                                                                                                                                                                                                                                                 |
| `fakeAsync`                  | Executa o corpo de um teste $`it`$ dentro de uma _zona de teste fakeAsync_ especial, permitindo um estilo de codificação de fluxo de controle linear. Veja [fakeAsync](guide/testing/components-scenarios#fake-async).                                                                                                                                                                                                                                                                                                                                                                                  |
| `tick`                       | Simula a passagem do tempo e a conclusão de atividades assíncronas pendentes liberando ambas as filas de _timer_ e _micro-task_ dentro da _zona de teste fakeAsync_. O leitor curioso e dedicado pode gostar deste longo post de blog, ["_Tasks, microtasks, queues and schedules_"](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules). Aceita um argumento opcional que move o relógio virtual para frente pelo número especificado de milissegundos, limpando atividades assíncronas agendadas dentro desse período de tempo. Veja [tick](guide/testing/components-scenarios#tick). |
| `inject`                     | Injeta um ou mais services do injetor `TestBed` atual em uma função de teste. Não pode injetar um service fornecido pelo próprio component. Veja discussão do [debugElement.injector](guide/testing/components-scenarios#get-injected-services).                                                                                                                                                                                                                                                                                                                                                          |
| `discardPeriodicTasks`       | Quando um teste `fakeAsync()` termina com _tasks_ de evento de timer pendentes $callbacks `setTimeOut` e `setInterval` enfileirados$, o teste falha com uma mensagem de erro clara. <br /> Em geral, um teste deve terminar sem tasks enfileiradas. Quando tasks de timer pendentes são esperadas, chame `discardPeriodicTasks` para liberar a fila de _task_ e evitar o erro.                                                                                                                                                                                                                          |
| `flushMicrotasks`            | Quando um teste `fakeAsync()` termina com _micro-tasks_ pendentes como promises não resolvidas, o teste falha com uma mensagem de erro clara. <br /> Em geral, um teste deve esperar que micro-tasks terminem. Quando microtasks pendentes são esperados, chame `flushMicrotasks` para liberar a fila de _micro-task_ e evitar o erro.                                                                                                                                                                                                                                                                    |
| `ComponentFixtureAutoDetect` | Um token de provider para um service que ativa a [detecção automática de mudanças](guide/testing/components-scenarios#automatic-change-detection).                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `getTestBed`                 | Obtém a instância atual do `TestBed`. Geralmente desnecessário porque os métodos de classe estáticos da classe `TestBed` são tipicamente suficientes. A instância `TestBed` expõe alguns membros raramente usados que não estão disponíveis como métodos estáticos.                                                                                                                                                                                                                                                                                                                                       |

## Resumo da classe `TestBed` {#testbed-class-summary}

A classe `TestBed` é uma das principais utilitários de teste do Angular.
Sua API é bastante grande e pode ser avassaladora até que você a explore, um pouco de cada vez.
Leia a parte inicial deste guia primeiro para obter o básico antes de tentar absorver a API completa.

A definição do módulo passada para `configureTestingModule` é um subconjunto das propriedades de metadados `@NgModule`.

```javascript
type TestModuleMetadata = {
providers?: any[];
declarations?: any[];
imports?: any[];
schemas?: Array<SchemaMetadata | any[]>;
};
```
Cada método override recebe um `MetadataOverride<T>` onde `T` é o tipo de metadados apropriado para o método, ou seja, o parâmetro de um `@NgModule`, `@Component`, `@Directive` ou `@Pipe`.

```javascript
type MetadataOverride<T> = {
add?: Partial<T>;
remove?: Partial<T>;
set?: Partial<T>;
};
```
A API `TestBed` consiste de métodos de classe estáticos que atualizam ou referenciam uma instância _global_ do `TestBed`.

Internamente, todos os métodos estáticos cobrem métodos da instância `TestBed` de runtime atual, que também é retornada pela função `getTestBed()`.

Chame métodos `TestBed` _dentro_ de um `beforeEach()` para garantir um novo começo antes de cada teste individual.

Aqui estão os métodos estáticos mais importantes, em ordem de utilidade provável.

| Métodos                  | Detalhes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `configureTestingModule` | Os shims de teste estabelecem o [ambiente de teste inicial](guide/testing) e um módulo de teste padrão. O módulo de teste padrão é configurado com declarações básicas e alguns substitutos de service do Angular que todo testador precisa. <br /> Chame `configureTestingModule` para refinar a configuração do módulo de teste para um conjunto particular de testes adicionando e removendo imports, declarations $de components, directives e pipes$ e providers.                                   |
| `compileComponents`      | Compile o módulo de teste de forma assíncrona depois de ter terminado de configurá-lo. Você **deve** chamar este método se _qualquer_ um dos components do módulo de teste tiver um `templateUrl` ou `styleUrls` porque buscar arquivos de template e estilo de component é necessariamente assíncrono. Veja [compileComponents](guide/testing/components-scenarios#calling-compilecomponents). <br /> Após chamar `compileComponents`, a configuração `TestBed` é congelada para a duração da spec atual. |
| `createComponent<T>`     | Crie uma instância de um component do tipo `T` baseado na configuração `TestBed` atual. Após chamar `createComponent`, a configuração `TestBed` é congelada para a duração da spec atual.                                                                                                                                                                                                                                                                                                                  |
| `overrideModule`         | Substitua metadados para o `NgModule` fornecido. Lembre-se que módulos podem importar outros módulos. O método `overrideModule` pode alcançar profundamente no módulo de teste atual para modificar um desses módulos internos.                                                                                                                                                                                                                                                                            |
| `overrideComponent`      | Substitua metadados para a classe de component fornecida, que poderia estar aninhada profundamente dentro de um módulo interno.                                                                                                                                                                                                                                                                                                                                                                            |
| `overrideDirective`      | Substitua metadados para a classe de directive fornecida, que poderia estar aninhada profundamente dentro de um módulo interno.                                                                                                                                                                                                                                                                                                                                                                            |
| `overridePipe`           | Substitua metadados para a classe de pipe fornecida, que poderia estar aninhada profundamente dentro de um módulo interno.                                                                                                                                                                                                                                                                                                                                                                                 |

|
`inject` | Recupere um service do injetor `TestBed` atual. A função `inject` é frequentemente adequada para este propósito. Mas `inject` lança um erro se não puder fornecer o service. <br /> E se o service for opcional? <br /> O método `TestBed.inject()` recebe um segundo parâmetro opcional, o objeto a retornar se o Angular não puder encontrar o provider $`null` neste exemplo$: <docs-code header="app/demo/demo.testbed.spec.ts" path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="testbed-get-w-null"/> Após chamar `TestBed.inject`, a configuração `TestBed` é congelada para a duração da spec atual. |
|
`initTestEnvironment` | Inicialize o ambiente de teste para toda a execução de teste. <br /> Os shims de teste o chamam para você, então raramente há razão para você chamá-lo você mesmo. <br /> Chame este método _exatamente uma vez_. Para mudar este padrão no meio de uma execução de teste, chame `resetTestEnvironment` primeiro. <br /> Especifique a factory do compilador Angular, um `PlatformRef` e um módulo de teste Angular padrão. Alternativas para plataformas não-browser estão disponíveis na forma geral `@angular/platform-<platform_name>/testing/<platform_name>`. |
| `resetTestEnvironment` | Redefina o ambiente de teste inicial, incluindo o módulo de teste padrão. |

Alguns dos métodos de instância `TestBed` não são cobertos por métodos de _classe_ estáticos `TestBed`.
Estes são raramente necessários.

## O `ComponentFixture` {#the-componentfixture}

O `TestBed.createComponent<T>` cria uma instância do component `T` e retorna um `ComponentFixture` fortemente tipado para aquele component.

As propriedades e métodos `ComponentFixture` fornecem acesso ao component, sua representação DOM e aspectos de seu ambiente Angular.

### Propriedades de `ComponentFixture`

Aqui estão as propriedades mais importantes para testadores, em ordem de utilidade provável.

| Propriedades        | Detalhes                                                                                                                                                                                                                                                                            |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentInstance` | A instância da classe de component criada por `TestBed.createComponent`.                                                                                                                                                                                                            |
| `debugElement`      | O `DebugElement` associado com o elemento raiz do component. <br /> O `debugElement` fornece insight sobre o component e seu elemento DOM durante teste e debugging. É uma propriedade crítica para testadores. Os membros mais interessantes são cobertos [abaixo](#debugelement). |
| `nativeElement`     | O elemento DOM nativo na raiz do component.                                                                                                                                                                                                                                         |
| `changeDetectorRef` | O `ChangeDetectorRef` para o component. <br /> O `ChangeDetectorRef` é mais valioso ao testar um component que tem o método `ChangeDetectionStrategy.OnPush` ou a detecção de mudanças do component está sob seu controle programático.                                             |

### Métodos de `ComponentFixture`

Os métodos _fixture_ fazem o Angular realizar certas tarefas na árvore de components.
Chame esses métodos para acionar comportamento Angular em resposta à ação simulada do usuário.

Aqui estão os métodos mais úteis para testadores.

| Métodos             | Detalhes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detectChanges`     | Aciona um ciclo de detecção de mudanças para o component. <br /> Chame-o para inicializar o component $ele chama `ngOnInit`$ e depois que seu código de teste alterar os valores de propriedade vinculados a dados do component. O Angular não pode ver que você mudou `personComponent.name` e não atualizará o binding `name` até que você chame `detectChanges`. <br /> Executa `checkNoChanges` depois para confirmar que não há atualizações circulares, a menos que chamado como `detectChanges(false)`;                                                                                                       |
| `autoDetectChanges` | Defina isso como `true` quando você quiser que o fixture detecte mudanças automaticamente. <br /> Quando autodetect é `true`, o fixture de teste chama `detectChanges` imediatamente após criar o component. Então ele escuta eventos de zone pertinentes e chama `detectChanges` de acordo. Quando seu código de teste modifica valores de propriedade do component diretamente, você provavelmente ainda terá que chamar `fixture.detectChanges` para acionar atualizações de data binding. <br /> O padrão é `false`. Testadores que preferem controle fino sobre comportamento de teste tendem a mantê-lo `false`. |
| `checkNoChanges`    | Execute uma execução de detecção de mudanças para garantir que não haja mudanças pendentes. Lança exceções se houver.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `isStable`          | Se o fixture está atualmente _estável_, retorna `true`. Se há tarefas assíncronas que não foram completadas, retorna `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `whenStable`        | Retorna uma promise que resolve quando o fixture está estável. <br /> Para retomar testes após conclusão de atividade assíncrona ou detecção de mudanças assíncrona, conecte essa promise. Veja [whenStable](guide/testing/components-scenarios#whenstable).                                                                                                                                                                                                                                                                                                                                                           |
| `destroy`           | Aciona a destruição do component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

#### `DebugElement`

O `DebugElement` fornece insights cruciais sobre a representação DOM do component.

A partir do `DebugElement` do component raiz de teste retornado por `fixture.debugElement`, você pode caminhar $e consultar$ toda a árvore de elementos e components do fixture.

Aqui estão os membros `DebugElement` mais úteis para testadores, em ordem aproximada de utilidade:

| Membros               | Detalhes                                                                                                                                                                                                                                                                                                                                                                                            |
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nativeElement`       | O elemento DOM correspondente no browser                                                                                                                                                                                                                                                                                                                                                            |
| `query`               | Chamar `query(predicate: Predicate<DebugElement>)` retorna o primeiro `DebugElement` que corresponde ao predicado em qualquer profundidade na subárvore.                                                                                                                                                                                                                                            |
| `queryAll`            | Chamar `queryAll(predicate: Predicate<DebugElement>)` retorna todos os `DebugElements` que correspondem ao predicado em qualquer profundidade na subárvore.                                                                                                                                                                                                                                         |
| `injector`            | O injetor de dependência do host. Por exemplo, o injetor da instância de component do elemento raiz.                                                                                                                                                                                                                                                                                                |
| `componentInstance`   | A própria instância de component do elemento, se houver uma.                                                                                                                                                                                                                                                                                                                                        |
| `context`             | Um objeto que fornece contexto pai para este elemento. Frequentemente uma instância de component ancestral que governa este elemento. <br /> Quando um elemento é repetido dentro de um bloco `@for`, o context é um `RepeaterContext` cuja propriedade `$implicit` é o valor da instância de linha. Por exemplo, o `hero` em `@for(hero of heroes; ...)`.                                          |
| `children`            | Os filhos `DebugElement` imediatos. Caminhe pela árvore descendo através de `children`. `DebugElement` também tem `childNodes`, uma lista de objetos `DebugNode`. `DebugElement` deriva de objetos `DebugNode` e frequentemente há mais nodes do que elementos. Testadores geralmente podem ignorar nodes simples.                                                                                  |
| `parent`              | O pai `DebugElement`. Null se este for o elemento raiz.                                                                                                                                                                                                                                                                                                                                             |
| `name`                | O nome da tag do elemento, se for um elemento.                                                                                                                                                                                                                                                                                                                                                      |
| `triggerEventHandler` | Aciona o evento por seu nome se houver um listener correspondente na coleção `listeners` do elemento. O segundo parâmetro é o _objeto de evento_ esperado pelo handler. Veja [triggerEventHandler](guide/testing/components-scenarios#trigger-event-handler). <br /> Se o evento não tiver um listener ou houver algum outro problema, considere chamar `nativeElement.dispatchEvent(eventObject)`. |
| `listeners`           | Os callbacks anexados às propriedades `@Output` do component e/ou às propriedades de evento do elemento.                                                                                                                                                                                                                                                                                            |
| `providerTokens`      | Os tokens de lookup do injetor deste component. Inclui o próprio component além dos tokens que o component lista em seus metadados `providers`.                                                                                                                                                                                                                                                     |
| `source`              | Onde encontrar este elemento no template de component fonte.                                                                                                                                                                                                                                                                                                                                        |
| `references`          | Dicionário de objetos associados com variáveis locais de template $por exemplo, `#foo`$, indexado pelo nome da variável local.                                                                                                                                                                                                                                                                    |

Os métodos `DebugElement.query(predicate)` e `DebugElement.queryAll(predicate)` recebem um predicado que filtra a subárvore do elemento fonte para `DebugElement` correspondentes.

O predicado é qualquer método que recebe um `DebugElement` e retorna um valor _truthy_.
O exemplo a seguir encontra todos os `DebugElements` com uma referência a uma variável local de template chamada "content":

<docs-code header="app/demo/demo.testbed.spec.ts" path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="custom-predicate"/>

A classe `By` do Angular tem três métodos estáticos para predicados comuns:

<docs-code header="app/hero/hero-list.component.spec.ts" path="adev/src/content/examples/testing/src/app/hero/hero-list.component.spec.ts" visibleRegion="by"/>

# Visão geral de component harnesses

Um <strong>component harness</strong> é uma classe que permite que testes interajam com components da mesma forma que um usuário final faz por meio de uma API suportada. Você pode criar test harnesses para qualquer component, desde pequenos widgets reutilizáveis até páginas completas.

Harnesses oferecem vários benefícios:

- Eles tornam os testes menos frágeis ao se isolar de detalhes de implementação de um component, como sua estrutura DOM
- Eles tornam os testes mais legíveis e fáceis de manter
- Eles podem ser usados em múltiplos ambientes de teste

```typescript
// Example of test with a harness for a component called MyButtonComponent
it('should load button with exact text', async () => {
  const button = await loader.getHarness(MyButtonComponentHarness);
  expect(await button.getText()).toBe('Confirm');
});
```
Component harnesses são especialmente úteis para widgets de UI compartilhados. Desenvolvedores frequentemente escrevem testes que dependem de detalhes de implementação privados de widgets, como estrutura DOM e classes CSS. Essas dependências tornam os testes frágeis e difíceis de manter. Harnesses oferecem uma alternativa — uma API suportada que interage com o widget da mesma forma que um usuário final faz. Mudanças na implementação do widget agora se tornam menos propensas a quebrar os testes do usuário. Por exemplo, [Angular Material](https://material.angular.dev/components/categories) fornece um test harness para cada component da biblioteca.

Component harnesses suportam múltiplos ambientes de teste. Você pode usar a mesma implementação de harness em testes unitários e end-to-end. Autores de testes precisam aprender apenas uma API e autores de components não precisam manter implementações de teste unitário e end-to-end separadas.

Muitos desenvolvedores podem ser categorizados por uma das seguintes categorias de tipo de desenvolvedor: autores de testes, autores de component harnesses e autores de ambientes de harness. Use a tabela abaixo para encontrar a seção mais relevante neste guia com base nessas categorias:

| Tipo de Desenvolvedor         | Descrição                                                                                                                                                                                                                                                                                                          | Seção Relevante                                                                                              |
| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| Autores de testes             | Desenvolvedores que usam component harnesses escritos por outra pessoa para testar sua aplicação. Por exemplo, isso pode ser um desenvolvedor de app que usa um component de menu de terceiros e precisa interagir com o menu em um teste unitário.                                                               | [Usando component harnesses em testes](guide/testing/using-component-harnesses)                              |
| Autores de component harnesses | Desenvolvedores que mantêm alguns components Angular reutilizáveis e desejam criar um test harness para seus usuários usarem em seus testes. Por exemplo, um autor de uma biblioteca de components Angular de terceiros ou um desenvolvedor que mantém um conjunto de components comuns para uma aplicação Angular grande. | [Criando component harnesses para seus components](guide/testing/creating-component-harnesses)               |
| Autores de ambientes de harness | Desenvolvedores que desejam adicionar suporte para usar component harnesses em ambientes de teste adicionais. Para informações sobre ambientes de teste suportados imediatamente, veja [ambientes de test harness e loaders](guide/testing/using-component-harnesses#test-harness-environments-and-loaders).        | [Adicionando suporte para ambientes de teste adicionais](guide/testing/component-harnesses-testing-environments) |

Para a referência completa da API, por favor veja a [página de referência da API de component harness do Angular CDK](/api#angular_cdk_testing).

# Usando component harnesses em testes

## Antes de começar

TIP: Este guia assume que você já leu o [guia de visão geral de component harnesses](guide/testing/component-harnesses-overview). Leia-o primeiro se você é novo em usar component harnesses.

### Instalação do CDK

O [Component Dev Kit (CDK)](https://material.angular.dev/cdk/categories) é um conjunto de primitivas de comportamento para construir components. Para usar os component harnesses, primeiro instale `@angular/cdk` do npm. Você pode fazer isso do seu terminal usando o Angular CLI:

```shell
ng add @angular/cdk
```
## Ambientes de test harness e loaders

Você pode usar component test harnesses em diferentes ambientes de teste. O Angular CDK suporta dois ambientes integrados:

- Testes unitários com o `TestBed` do Angular
- Testes end-to-end com [WebDriver](https://developer.mozilla.org/en-US/docs/Web/WebDriver)

Cada ambiente fornece um <strong>harness loader</strong>. O loader cria as instâncias de harness que você usa ao longo de seus testes. Veja abaixo para orientação mais específica sobre ambientes de teste suportados.

Ambientes de teste adicionais requerem bindings personalizados. Veja o [guia adicionando suporte de harness para ambientes de teste adicionais](guide/testing/component-harnesses-testing-environments) para mais informações.

### Usando o loader de `TestbedHarnessEnvironment` para testes unitários

Para testes unitários você pode criar um harness loader de [TestbedHarnessEnvironment](/api/cdk/testing/TestbedHarnessEnvironment). Este ambiente usa um [component fixture](api/core/testing/ComponentFixture) criado pelo `TestBed` do Angular.

Para criar um harness loader enraizado no elemento raiz do fixture, use o método `loader()`:

```typescript
const fixture = TestBed.createComponent(MyComponent);

// Create a harness loader from the fixture
const loader = TestbedHarnessEnvironment.loader(fixture);
...

// Use the loader to get harness instances
const myComponentHarness = await loader.getHarness(MyComponent);
```
Para criar um harness loader para harnesses de elementos que ficam fora do fixture, use o método `documentRootLoader()`. Por exemplo, código que exibe um elemento flutuante ou pop-up frequentemente anexa elementos DOM diretamente ao corpo do documento, como o service `Overlay` no Angular CDK.

Você também pode criar um harness loader diretamente com `harnessForFixture()` para um harness no elemento raiz daquele fixture diretamente.

### Usando o loader de `SeleniumWebDriverHarnessEnvironment` para testes end-to-end

Para testes end-to-end baseados em WebDriver você pode criar um harness loader com `SeleniumWebDriverHarnessEnvironment`.

Use o método `loader()` para obter a instância de harness loader para o documento HTML atual, enraizado no elemento raiz do documento. Este ambiente usa um client WebDriver.

```typescript
let wd: webdriver.WebDriver = getMyWebDriverClient();
const loader = SeleniumWebDriverHarnessEnvironment.loader(wd);
...
const myComponentHarness = await loader.getHarness(MyComponent);
```
## Usando um harness loader

Instâncias de harness loader correspondem a um elemento DOM específico e são usadas para criar instâncias de component harness para elementos sob aquele elemento específico.

Para obter `ComponentHarness` para a primeira instância do elemento, use o método `getHarness()`. Para obter todas as instâncias de `ComponentHarness`, use o método `getAllHarnesses()`.

```typescript
// Get harness for first instance of the element
const myComponentHarness = await loader.getHarness(MyComponent);

// Get harnesses for all instances of the element
const myComponentHarnesses = await loader.getHarnesses(MyComponent);
```
Além de `getHarness` e `getAllHarnesses`, `HarnessLoader` tem vários outros métodos úteis para consultar harnesses:

- `getHarnessAtIndex(...)`: Obtém o harness para um component que corresponde aos critérios fornecidos em um índice específico.
- `countHarnesses(...)`: Conta o número de instâncias de component que correspondem aos critérios fornecidos.
- `hasHarness(...)`: Verifica se pelo menos uma instância de component corresponde aos critérios fornecidos.

Como exemplo, considere um component de botão de diálogo reutilizável que abre um diálogo ao clicar. Ele contém os seguintes components, cada um com um harness correspondente:

- `MyDialogButton` (compõe o `MyButton` e `MyDialog` com uma API conveniente)
- `MyButton` (um component de botão padrão)
- `MyDialog` (um diálogo anexado ao `document.body` por `MyDialogButton` ao clicar)

O seguinte teste carrega harnesses para cada um desses components:

```typescript
let fixture: ComponentFixture<MyDialogButton>;
let loader: HarnessLoader;
let rootLoader: HarnessLoader;

beforeEach(() => {
fixture = TestBed.createComponent(MyDialogButton);
loader = TestbedHarnessEnvironment.loader(fixture);
rootLoader = TestbedHarnessEnvironment.documentRootLoader(fixture);
});

it('loads harnesses', async () => {
// Load a harness for the bootstrapped component with `harnessForFixture`
dialogButtonHarness =
await TestbedHarnessEnvironment.harnessForFixture(fixture, MyDialogButtonHarness);

// The button element is inside the fixture's root element, so we use `loader`.
const buttonHarness = await loader.getHarness(MyButtonHarness);

// Click the button to open the dialog
await buttonHarness.click();

// The dialog is appended to `document.body`, outside of the fixture's root element,
// so we use `rootLoader` in this case.
const dialogHarness = await rootLoader.getHarness(MyDialogHarness);

// ... make some assertions
});
```
### Comportamento de harness em diferentes ambientes

Harnesses podem não se comportar exatamente da mesma forma em todos os ambientes. Algumas diferenças são inevitáveis entre a interação real do usuário versus os eventos simulados gerados em testes unitários. O Angular CDK faz o melhor esforço para normalizar o comportamento na medida do possível.

### Interagindo com elementos filhos

Para interagir com elementos abaixo do elemento raiz deste harness loader, use a instância `HarnessLoader` de um elemento filho. Para a primeira instância do elemento filho, use o método `getChildLoader()`. Para todas as instâncias do elemento filho, use o método `getAllChildLoaders()`.

```typescript
const myComponentHarness = await loader.getHarness(MyComponent);

// Get loader for first instance of child element with '.child' selector
const childLoader = await myComponentHarness.getLoader('.child');

// Get loaders for all instances of child elements with '.child' selector
const allChildLoaders = await myComponentHarness.getAllChildLoaders('.child');
```
### Filtrando harnesses

Quando uma página contém múltiplas instâncias de um component particular, você pode querer filtrar baseado em alguma propriedade do component para obter uma instância de component particular. Você pode usar um <strong>harness predicate</strong>, uma classe usada para associar uma classe `ComponentHarness` com funções de predicados que podem ser usadas para filtrar instâncias de component, para fazer isso.

Quando você pede a um `HarnessLoader` por um harness, você está na verdade fornecendo um HarnessQuery. Uma query pode ser uma de duas coisas:

- Um construtor de harness. Isso apenas obtém aquele harness
- Um `HarnessPredicate`, que obtém harnesses que são filtrados baseado em uma ou mais condições

`HarnessPredicate` suporta alguns filtros base (selector, ancestor) que funcionam em qualquer coisa que estende `ComponentHarness`.

```typescript
// Example of loading a MyButtonComponentHarness with a harness predicate
const disabledButtonPredicate = new HarnessPredicate(MyButtonComponentHarness, {selector: '[disabled]'});
const disabledButton = await loader.getHarness(disabledButtonPredicate);
```
No entanto, é comum para harnesses implementarem um método estático `with()` que aceita opções de filtragem específicas do component e retorna um `HarnessPredicate`.

```typescript
// Example of loading a MyButtonComponentHarness with a specific selector
const button = await loader.getHarness(MyButtonComponentHarness.with({selector: 'btn'}))
```
Para mais detalhes, consulte a documentação específica do harness, pois opções de filtragem adicionais são específicas para cada implementação de harness.

## Usando APIs de test harness

Embora cada harness defina uma API específica para seu component correspondente, todos compartilham uma classe base comum, [ComponentHarness](/api/cdk/testing/ComponentHarness). Esta classe base define uma propriedade estática, `hostSelector`, que corresponde a classe harness a instâncias do component no DOM.

Além disso, a API de qualquer harness dado é específica para seu component correspondente; consulte a documentação do component para aprender como usar um harness específico.

Como exemplo, o seguinte é um teste para um component que usa o [harness de component slider do Angular Material](https://material.angular.dev/components/slider/api#MatSliderHarness):

```typescript
it('should get value of slider thumb', async () => {
  const slider = await loader.getHarness(MatSliderHarness);
  const thumb = await slider.getEndThumb();
  expect(await thumb.getValue()).toBe(50);
});
```
## Interoperabilidade com detecção de mudanças do Angular

Por padrão, test harnesses executam a [detecção de mudanças](https://angular.dev/best-practices/runtime-performance) do Angular antes de ler o estado de um elemento DOM e depois de interagir com um elemento DOM.

Pode haver momentos em que você precisa de controle mais refinado sobre a detecção de mudanças em seus testes, como verificar o estado de um component enquanto uma operação assíncrona está pendente. Nesses casos, use a função `manualChangeDetection` para desabilitar o tratamento automático de detecção de mudanças para um bloco de código.

```typescript
it('checks state while async action is in progress', async () => {
  const buttonHarness = loader.getHarness(MyButtonHarness);
  await manualChangeDetection(async () => {
    await buttonHarness.click();
    fixture.detectChanges();
    // Check expectations while async click operation is in progress.
    expect(isProgressSpinnerVisible()).toBe(true);
    await fixture.whenStable();
    // Check expectations after async click operation complete.
    expect(isProgressSpinnerVisible()).toBe(false);
  });
});
```
Quase todos os métodos de harness são assíncronos e retornam uma `Promise` para suportar o seguinte:

- Suporte para testes unitários
- Suporte para testes end-to-end
- Isolar testes contra mudanças em comportamento assíncrono

A equipe do Angular recomenda usar [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) para melhorar a legibilidade do teste. Chamar `await` bloqueia a execução do seu teste até que a `Promise` associada resolva.

Ocasionalmente, você pode querer realizar múltiplas ações simultaneamente e esperar até que todas estejam prontas ao invés de realizar cada ação sequencialmente. Por exemplo, ler múltiplas propriedades de um único component. Nessas situações, use a função `parallel` para paralelizar as operações. A função parallel funciona de forma similar a `Promise.all`, enquanto também otimiza verificações de detecção de mudanças.

```typescript
it('reads properties in parallel', async () => {
  const checkboxHarness = loader.getHarness(MyCheckboxHarness);
  // Read the checked and intermediate properties simultaneously.
  const [checked, indeterminate] = await parallel(() => [
    checkboxHarness.isChecked(),
    checkboxHarness.isIndeterminate()
  ]);
  expect(checked).toBe(false);
  expect(indeterminate).toBe(true);
});
```

# Criando harnesses para seus components

## Antes de começar

TIP: Este guia assume que você já leu o [guia de visão geral de component harnesses](guide/testing/component-harnesses-overview). Leia-o primeiro se você é novo em usar component harnesses.

### Quando criar um test harness faz sentido?

A equipe do Angular recomenda criar component test harnesses para components compartilhados que são usados em muitos lugares e têm alguma interatividade do usuário. Isso se aplica mais comumente a bibliotecas de widgets e components reutilizáveis similares. Harnesses são valiosos para esses casos porque fornecem aos consumidores desses components compartilhados uma API bem suportada para interagir com um component. Testes que usam harnesses podem evitar depender de detalhes de implementação não confiáveis desses components compartilhados, como estrutura DOM e event listeners específicos.

Para components que aparecem em apenas um lugar, como uma página em uma aplicação, harnesses não fornecem tanto benefício. Nessas situações, os testes de um component podem razoavelmente depender dos detalhes de implementação deste component, pois os testes e components são atualizados ao mesmo tempo. No entanto, harnesses ainda fornecem algum valor se você usar o harness em testes unitários e end-to-end.

### Instalação do CDK

```shell
ng add @angular/cdk
```
## Estendendo `ComponentHarness`

A classe abstrata `ComponentHarness` é a classe base para todos os component harnesses. Para criar um component harness personalizado, estenda `ComponentHarness` e implemente a propriedade estática `hostSelector`.

A propriedade `hostSelector` identifica elementos no DOM que correspondem a esta subclasse harness. Na maioria dos casos, o `hostSelector` deve ser o mesmo que o seletor do `Component` ou `Directive` correspondente. Por exemplo, considere um component de popup simples:

```typescript
@Component({
  selector: 'my-popup',
  template: `
    <button (click)="toggle()">{{triggerText()}}</button>
    @if (isOpen()) {
      <div class="my-popup-content"><ng-content></ng-content></div>
    }
  `
})
class MyPopup {
  triggerText = input('');

isOpen = signal(false);

toggle() {
this.isOpen.update((value) => !value);
}
}
```
Neste caso, um harness mínimo para o component ficaria assim:

```typescript
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';
}
```
Embora subclasses de `ComponentHarness` exijam apenas a propriedade `hostSelector`, a maioria dos harnesses também deve implementar um método estático `with` para gerar instâncias de `HarnessPredicate`. A [seção filtrando harnesses](guide/testing/using-component-harnesses#filtering-harnesses) cobre isso em mais detalhes.

## Encontrando elementos no DOM do component

Cada instância de uma subclasse `ComponentHarness` representa uma instância particular do component correspondente. Você pode acessar o elemento host do component via o método `host()` da classe base `ComponentHarness`.

`ComponentHarness` também oferece vários métodos para localizar elementos dentro do DOM do component. Esses métodos são `locatorFor()`, `locatorForOptional()` e `locatorForAll()`. Esses métodos criam funções que encontram elementos, eles não encontram elementos diretamente. Esta abordagem protege contra o cache de referências a elementos desatualizados. Por exemplo, quando um bloco `@if` oculta e depois mostra um elemento, o resultado é um novo elemento DOM; usar funções garante que os testes sempre referenciem o estado atual do DOM.

Veja a [página de referência da API ComponentHarness](/api/cdk/testing/ComponentHarness) para a lista completa de detalhes dos diferentes métodos `locatorFor`.

Por exemplo, o exemplo `MyPopupHarness` discutido acima poderia fornecer métodos para obter os elementos trigger e content da seguinte forma:

```typescript
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

// Gets the trigger element
getTriggerElement = this.locatorFor('button');

// Gets the content element.
getContentElement = this.locatorForOptional('.my-popup-content');
}
```
## Trabalhando com instâncias de `TestElement`

`TestElement` é uma abstração projetada para funcionar em diferentes ambientes de teste (testes unitários, WebDriver, etc). Ao usar harnesses, você deve realizar toda a interação DOM por meio desta interface. Outros meios de acessar elementos DOM, como `document.querySelector()`, não funcionam em todos os ambientes de teste.

`TestElement` tem vários métodos para interagir com o DOM subjacente, como `blur()`, `click()`, `getAttribute()` e mais. Veja a [página de referência da API TestElement](/api/cdk/testing/TestElement) para a lista completa de métodos.

Não exponha instâncias de `TestElement` aos usuários de harness, a menos que seja um elemento que o consumidor do component define diretamente, como o elemento host do component. Expor instâncias de `TestElement` para elementos internos leva os usuários a depender da estrutura DOM interna de um component.

Em vez disso, forneça métodos mais focados para ações específicas que o usuário final pode realizar ou estado particular que eles podem observar. Por exemplo, `MyPopupHarness` das seções anteriores poderia fornecer métodos como `toggle` e `isOpen`:

```typescript
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

protected getTriggerElement = this.locatorFor('button');
protected getContentElement = this.locatorForOptional('.my-popup-content');

/\*_ Toggles the open state of the popup. _/
async toggle() {
const trigger = await this.getTriggerElement();
return trigger.click();
}

/\*_ Checks if the popup us open. _/
async isOpen() {
const content = await this.getContentElement();
return !!content;
}
}
```
## Carregando harnesses para subcomponents

Components maiores frequentemente compõem sub-components. Você pode refletir esta estrutura no harness de um component também. Cada um dos métodos `locatorFor` em `ComponentHarness` tem uma assinatura alternativa que pode ser usada para localizar sub-harnesses ao invés de elementos.

Veja a [página de referência da API ComponentHarness](/api/cdk/testing/ComponentHarness) para a lista completa dos diferentes métodos locatorFor.

Por exemplo, considere um menu construído usando o popup de cima:

```typescript
@Directive({
  selector: 'my-menu-item'
})
class MyMenuItem {}

@Component({
selector: 'my-menu',
template: `     <my-popup>
      <ng-content></ng-content>
    </my-popup>
  `
})
class MyMenu {
triggerText = input('');

@ContentChildren(MyMenuItem) items: QueryList<MyMenuItem>;
}
```
O harness para `MyMenu` pode então aproveitar outros harnesses para `MyPopup` e `MyMenuItem`:

```typescript
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

protected getPopupHarness = this.locatorFor(MyPopupHarness);

/\*_ Gets the currently shown menu items (empty list if menu is closed). _/
getItems = this.locatorForAll(MyMenuItemHarness);

/\*_ Toggles open state of the menu. _/
async toggle() {
const popupHarness = await this.getPopupHarness();
return popupHarness.toggle();
}
}

class MyMenuItemHarness extends ComponentHarness {
static hostSelector = 'my-menu-item';
}
```
## Filtrando instâncias de harness com `HarnessPredicate`

Quando uma página contém múltiplas instâncias de um component particular, você pode querer filtrar baseado em alguma propriedade do component para obter uma instância de component particular. Por exemplo, você pode querer um botão com algum texto específico, ou um menu com um ID específico. A classe `HarnessPredicate` pode capturar critérios como este para uma subclasse `ComponentHarness`. Embora o autor do teste seja capaz de construir instâncias de `HarnessPredicate` manualmente, é mais fácil quando a subclasse `ComponentHarness` fornece um método auxiliar para construir predicados para filtros comuns.

Você deve criar um método estático `with()` em cada subclasse `ComponentHarness` que retorna um `HarnessPredicate` para aquela classe. Isso permite que autores de teste escrevam código facilmente compreensível, por exemplo `loader.getHarness(MyMenuHarness.with({selector: '#menu1'}))`. Além das opções padrão de selector e ancestor, o método `with` deve adicionar quaisquer outras opções que façam sentido para a subclasse particular.

Harnesses que precisam adicionar opções adicionais devem estender a interface `BaseHarnessFilters` e propriedades opcionais adicionais conforme necessário. `HarnessPredicate` fornece vários métodos de conveniência para adicionar opções: `stringMatches()`, `addOption()` e `add()`. Veja a [página da API HarnessPredicate](/api/cdk/testing/HarnessPredicate) para a descrição completa.

Por exemplo, ao trabalhar com um menu, é útil filtrar baseado no texto do trigger e filtrar itens do menu baseado no seu texto:

```typescript
interface MyMenuHarnessFilters extends BaseHarnessFilters {
  /** Filters based on the trigger text for the menu. */
  triggerText?: string | RegExp;
}

interface MyMenuItemHarnessFilters extends BaseHarnessFilters {
/\*_ Filters based on the text of the menu item. _/
text?: string | RegExp;
}

class MyMenuHarness extends ComponentHarness {
static hostSelector = 'my-menu';

/\*_ Creates a `HarnessPredicate` used to locate a particular `MyMenuHarness`. _/
static with(options: MyMenuHarnessFilters): HarnessPredicate<MyMenuHarness> {
return new HarnessPredicate(MyMenuHarness, options)
.addOption('trigger text', options.triggerText,
(harness, text) => HarnessPredicate.stringMatches(harness.getTriggerText(), text));
}

protected getPopupHarness = this.locatorFor(MyPopupHarness);

/\*_ Gets the text of the menu trigger. _/
async getTriggerText(): Promise<string> {
const popupHarness = await this.getPopupHarness();
return popupHarness.getTriggerText();
}
...
}

class MyMenuItemHarness extends ComponentHarness {
static hostSelector = 'my-menu-item';

/\*_ Creates a `HarnessPredicate` used to locate a particular `MyMenuItemHarness`. _/
static with(options: MyMenuItemHarnessFilters): HarnessPredicate<MyMenuItemHarness> {
return new HarnessPredicate(MyMenuItemHarness, options)
.addOption('text', options.text,
(harness, text) => HarnessPredicate.stringMatches(harness.getText(), text));
}

/\*_ Gets the text of the menu item. _/
async getText(): Promise<string> {
const host = await this.host();
return host.text();
}
}
```
Você pode passar um `HarnessPredicate` ao invés de uma classe `ComponentHarness` para qualquer uma das APIs em `HarnessLoader`, `LocatorFactory` ou `ComponentHarness`. Isso permite que autores de teste direcionem facilmente uma instância de component particular ao criar uma instância de harness. Também permite que o autor do harness aproveite o mesmo `HarnessPredicate` para habilitar APIs mais poderosas em sua classe harness. Por exemplo, considere o método `getItems` no `MyMenuHarness` mostrado acima. Adicionar uma API de filtragem permite que usuários do harness procurem itens de menu particulares:

```typescript
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

/\*_ Gets a list of items in the menu, optionally filtered based on the given criteria. _/
async getItems(filters: MyMenuItemHarnessFilters = {}): Promise<MyMenuItemHarness[]> {
const getFilteredItems = this.locatorForAll(MyMenuItemHarness.with(filters));
return getFilteredItems();
}
...
}
```
## Criando `HarnessLoader` para elementos que usam projeção de conteúdo

Alguns components projetam conteúdo adicional no template do component. Veja o [guia de projeção de conteúdo](guide/components/content-projection) para mais informações.

Adicione uma instância `HarnessLoader` com escopo para o elemento que contém o `<ng-content>` quando você criar um harness para um component que usa projeção de conteúdo. Isso permite que o usuário do harness carregue harnesses adicionais para quaisquer components que foram passados como conteúdo. `ComponentHarness` tem vários métodos que podem ser usados para criar instâncias HarnessLoader para casos como este: `harnessLoaderFor()`, `harnessLoaderForOptional()`, `harnessLoaderForAll()`. Veja a [página de referência da API da interface HarnessLoader](/api/cdk/testing/HarnessLoader) para mais detalhes.

Por exemplo, o exemplo `MyPopupHarness` de cima pode estender `ContentContainerComponentHarness` para adicionar suporte para carregar harnesses dentro do `<ng-content>` do component.

```typescript
class MyPopupHarness extends ContentContainerComponentHarness<string> {
  static hostSelector = 'my-popup';
}
```
## Acessando elementos fora do elemento host do component

Há momentos em que um component harness pode precisar acessar elementos fora do elemento host de seu component correspondente. Por exemplo, código que exibe um elemento flutuante ou pop-up frequentemente anexa elementos DOM diretamente ao corpo do documento, como o service `Overlay` no Angular CDK.

Neste caso, `ComponentHarness` fornece um método que pode ser usado para obter um `LocatorFactory` para o elemento raiz do documento. O `LocatorFactory` suporta a maioria das mesmas APIs que a classe base `ComponentHarness`, e pode então ser usado para consultar relativo ao elemento raiz do documento.

Considere se o component `MyPopup` acima usasse o overlay CDK para o conteúdo do popup, ao invés de um elemento em seu próprio template. Neste caso, `MyPopupHarness` teria que acessar o elemento content via método `documentRootLocatorFactory()` que obtém um locator factory enraizado na raiz do documento.

```typescript
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

/\*_ Gets a `HarnessLoader` whose root element is the popup's content element. _/
async getHarnessLoaderForContent(): Promise<HarnessLoader> {
const rootLocator = this.documentRootLocatorFactory();
return rootLocator.harnessLoaderFor('my-popup-content');
}
}
```
## Esperando por tarefas assíncronas

Os métodos em `TestElement` acionam automaticamente a detecção de mudanças do Angular e esperam por tarefas dentro da `NgZone`. Na maioria dos casos, nenhum esforço especial é necessário para autores de harness esperarem por tarefas assíncronas. No entanto, há alguns casos extremos onde isso pode não ser suficiente.

Sob algumas circunstâncias, animações do Angular podem requerer um segundo ciclo de detecção de mudanças e subsequente estabilização `NgZone` antes que eventos de animação sejam completamente liberados. Em casos onde isso é necessário, o `ComponentHarness` oferece um método `forceStabilize()` que pode ser chamado para fazer a segunda rodada.

Você pode usar `NgZone.runOutsideAngular()` para agendar tarefas fora de NgZone. Chame o método `waitForTasksOutsideAngular()` no harness correspondente se você precisar esperar explicitamente por tarefas fora de `NgZone`, pois isso não acontece automaticamente.

# Animando suas aplicações com `animate.enter` e `animate.leave`

Animações bem projetadas podem tornar sua aplicação mais divertida e simples de usar, mas elas não são apenas cosméticas.
Animações podem melhorar sua aplicação e experiência do usuário de várias maneiras:

- Sem animações, transições de páginas web podem parecer abruptas e desconfortáveis
- Movimento melhora muito a experiência do usuário, então animações dão aos usuários a chance de detectar a resposta da aplicação às suas ações
- Boas animações podem direcionar suavemente a atenção do usuário ao longo de um fluxo de trabalho

Angular fornece `animate.enter` e `animate.leave` para animar os elementos de sua aplicação. Esses dois recursos aplicam classes CSS de entrada e saída nos momentos apropriados ou chamam funções para aplicar animações de bibliotecas de terceiros. `animate.enter` e `animate.leave` não são directives. Eles são APIs especiais suportadas diretamente pelo compilador Angular. Eles podem ser usados em elementos diretamente e também podem ser usados como um host binding.

## `animate.enter`

Você pode usar `animate.enter` para animar elementos à medida que eles _entram_ no DOM. Você pode definir animações de entrada usando classes CSS com transitions ou animações de keyframe.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.ts">
    <docs-code header="enter.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.ts" />
    <docs-code header="enter.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.html" />
    <docs-code header="enter.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.css"/>
</docs-code-multifile>

Quando a animação é concluída, Angular remove a classe ou classes que você especificou em `animate.enter` do DOM. Classes de animação estão presentes apenas enquanto a animação está ativa.

NOTA: Ao usar múltiplas animações de keyframe ou propriedades de transition em um elemento, Angular remove todas as classes apenas _após_ a animação mais longa ter sido concluída.

Você pode usar `animate.enter` com quaisquer outros recursos do Angular, como control flow ou expressões dinâmicas. `animate.enter` aceita tanto uma única string de classe (com múltiplas classes separadas por espaços), quanto um array de strings de classe.

Uma nota rápida sobre o uso de transitions CSS: Se você escolher usar transitions em vez de animações de keyframe, as classes adicionadas ao elemento com `animate.enter` representam o estado para o qual a transition irá animar. Seu CSS base do elemento é como o elemento ficará quando nenhuma animação estiver rodando, que é provavelmente similar ao estado final da transition CSS. Então você ainda precisaria emparelhá-lo com `@starting-style` para ter um estado _de origem_ apropriado para que sua transition funcione.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.ts">
    <docs-code header="enter-binding.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.ts" />
    <docs-code header="enter-binding.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.html" />
    <docs-code header="enter-binding.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.css"/>
</docs-code-multifile>

## `animate.leave`

Você pode usar `animate.leave` para animar elementos à medida que eles _saem_ do DOM. Você pode definir animações de saída usando classes CSS com transforms ou animações de keyframe.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.ts">
    <docs-code header="leave.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.ts" />
    <docs-code header="leave.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.html" />
    <docs-code header="leave.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.css"/>
</docs-code-multifile>

Quando a animação é concluída, Angular remove automaticamente o elemento animado do DOM.

NOTA: Ao usar múltiplas animações de keyframe ou propriedades de transition em um elemento, Angular aguarda para remover o elemento apenas _após_ a mais longa dessas animações ter sido concluída.

`animate.leave` também pode ser usado com signals e outros bindings. Você pode usar `animate.leave` com uma única classe ou múltiplas classes. Especifique como uma string simples com espaços ou um array de strings.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.ts">
    <docs-code header="leave-binding.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.ts" />
    <docs-code header="leave-binding.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.html" />
    <docs-code header="leave-binding.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.css"/>
</docs-code-multifile>

## Event Bindings, Funções e Bibliotecas de Terceiros

Tanto `animate.enter` quanto `animate.leave` suportam sintaxe de event binding que permite chamadas de função. Você pode usar essa sintaxe para chamar uma função no código do seu component ou utilizar bibliotecas de animação de terceiros, como [GSAP](https://gsap.com/), [anime.js](https://animejs.com/), ou qualquer outra biblioteca de animação JavaScript.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.ts">
    <docs-code header="leave-event.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.ts" />
    <docs-code header="leave-event.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.html" />
    <docs-code header="leave-event.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.css"/>
</docs-code-multifile>

O objeto `$event` tem o type `AnimationCallbackEvent`. Ele inclui o elemento como o `target` e fornece uma função `animationComplete()` para notificar o framework quando a animação termina.

IMPORTANTE: Você **deve** chamar a função `animationComplete()` ao usar `animate.leave` para que o Angular remova o elemento.

Se você não chamar `animationComplete()` ao usar `animate.leave`, Angular chama a função automaticamente após um delay de quatro segundos. Você pode configurar a duração do delay fornecendo o token `MAX_ANIMATION_TIMEOUT` em milissegundos.

```typescript
{ provide: MAX_ANIMATION_TIMEOUT, useValue: 6000 }
```

## Compatibilidade com Animações Angular Legadas

Você não pode usar animações legadas juntamente com `animate.enter` e `animate.leave` dentro do mesmo component. Fazer isso resultaria em classes de entrada permanecendo no elemento ou nós de saída não sendo removidos. Caso contrário, é perfeitamente adequado usar tanto animações legadas quanto as novas animações `animate.enter` e `animate.leave` dentro da mesma _aplicação_. A única ressalva é content projection. Se você está projetando conteúdo de um component com animações legadas para outro component com `animate.enter` ou `animate.leave`, ou vice-versa, isso resultará no mesmo comportamento como se fossem usados juntos no mesmo component. Isso não é suportado.

## Testing

TestBed fornece suporte integrado para habilitar ou desabilitar animações no seu ambiente de teste. Animações CSS requerem um browser para rodar, e muitas das APIs não estão disponíveis em um ambiente de teste. Por padrão, TestBed desabilita animações para você em seus ambientes de teste.

Se você quiser testar que as animações estão animando em um teste de browser, por exemplo um teste end-to-end, você pode configurar o TestBed para habilitar animações especificando `animationsEnabled: true` na sua configuração de teste.

```typescript
TestBed.configureTestingModule({animationsEnabled: true});
```

Isso configurará animações no seu ambiente de teste para se comportarem normalmente.

NOTA: Alguns ambientes de teste não emitem eventos de animação como `animationstart`, `animationend` e seus equivalentes de eventos de transition.

## Mais sobre animações Angular

Você também pode estar interessado no seguinte:

# Animando sua Aplicação com CSS

CSS oferece um conjunto robusto de ferramentas para você criar animações bonitas e envolventes dentro de sua aplicação.

## Como escrever animações em CSS nativo

Se você nunca escreveu animações CSS nativas, existem vários guias excelentes para começar. Aqui estão alguns deles:
[Guia de Animações CSS do MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)
[Guia de Animações CSS3 do W3Schools](https://www.w3schools.com/css/css3_animations.asp)
[Tutorial Completo de Animações CSS](https://www.lambdatest.com/blog/css-animations-tutorial/)
[Animação CSS para Iniciantes](https://thoughtbot.com/blog/css-animation-for-beginners)

e alguns vídeos:
[Aprenda Animação CSS em 9 Minutos](https://www.youtube.com/watch?v=z2LQYsZhsFw)
[Playlist de Tutorial de Animação CSS do Net Ninja](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)

Confira alguns destes vários guias e tutoriais, e depois volte a este guia.

## Criando Animações Reutilizáveis

Você pode criar animações reutilizáveis que podem ser compartilhadas em toda a sua aplicação usando `@keyframes`. Defina animações de keyframe em um arquivo CSS compartilhado, e você poderá reutilizar essas animações de keyframe onde quiser dentro de sua aplicação.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-shared"/>

Adicionar a classe `animated-class` a um elemento acionaria a animação nesse elemento.

## Animando uma Transição

### Animando Estado e Estilos

Você pode querer animar entre dois estados diferentes, por exemplo, quando um elemento é aberto ou fechado. Você pode fazer isso usando classes CSS, seja usando uma animação de keyframe ou estilização de transition.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-states"/>

Acionar o estado `open` ou `closed` é feito alternando classes no elemento em seu component. Você pode encontrar exemplos de como fazer isso em nosso [guia de template](guide/templates/binding#css-class-and-style-property-bindings).

Você pode ver exemplos semelhantes no guia de template para [animar estilos diretamente](guide/templates/binding#css-style-properties).

### Transitions, Timing e Easing

Animar frequentemente requer ajustar timing, delays e comportamentos de easing. Isso pode ser feito usando várias propriedades CSS ou propriedades de atalho.

Especifique `animation-duration`, `animation-delay` e `animation-timing-function` para uma animação de keyframe em CSS, ou alternativamente use a propriedade de atalho `animation`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-timing"/>

Da mesma forma, você pode usar `transition-duration`, `transition-delay` e `transition-timing-function` e o atalho `transition` para animações que não estão usando `@keyframes`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="transition-timing"/>

### Acionando uma Animação

Animações podem ser acionadas alternando estilos ou classes CSS. Uma vez que uma classe está presente em um elemento, a animação ocorrerá. Remover a classe reverterá o elemento de volta para qualquer CSS que esteja definido para esse elemento. Aqui está um exemplo:

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts">
    <docs-code header="open-close.component.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts" />
    <docs-code header="open-close.component.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.html" />
    <docs-code header="open-close.component.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.css"/>
</docs-code-multifile>

## Transition e Triggers

### Animando Auto Height

Você pode usar css-grid para animar para altura automática.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts">
    <docs-code header="auto-height.component.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts" />
    <docs-code header="auto-height.component.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.html" />
    <docs-code header="auto-height.component.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.css"  />
</docs-code-multifile>

Se você não precisa se preocupar em suportar todos os browsers, você também pode conferir `calc-size()`, que é a verdadeira solução para animar altura automática. Veja [a documentação do MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/calc-size) e [este tutorial](https://frontendmasters.com/blog/one-of-the-boss-battles-of-css-is-almost-won-transitioning-to-auto/) para mais informações.

### Animar entrada e saída de uma view

Você pode criar animações para quando um item entra em uma view ou sai de uma view. Vamos começar olhando como animar um elemento entrando em uma view. Vamos fazer isso com `animate.enter`, que aplicará classes de animação quando um elemento entrar na view.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts">
    <docs-code header="insert.component.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts" />
    <docs-code header="insert.component.html" path="adev/src/content/examples/animations/src/app/native-css/insert.component.html" />
    <docs-code header="insert.component.css" path="adev/src/content/examples/animations/src/app/native-css/insert.component.css"  />
</docs-code-multifile>

Animar um elemento quando ele sai da view é semelhante a animar quando entra em uma view. Use `animate.leave` para especificar quais classes CSS aplicar quando o elemento sair da view.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts">
    <docs-code header="remove.component.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts" />
    <docs-code header="remove.component.html" path="adev/src/content/examples/animations/src/app/native-css/remove.component.html" />
    <docs-code header="remove.component.css" path="adev/src/content/examples/animations/src/app/native-css/remove.component.css"  />
</docs-code-multifile>

Para mais informações sobre `animate.enter` e `animate.leave`, veja o [guia de animações Enter e Leave](guide/animations).

### Animando incremento e decremento

Animar no incremento e decremento é um padrão comum em aplicações. Aqui está um exemplo de como você pode realizar esse comportamento.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts">
    <docs-code header="increment-decrement.component.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts" />
    <docs-code header="increment-decrement.component.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.html" />
    <docs-code header="increment-decrement.component.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.css" />
</docs-code-multifile>

### Desabilitando uma animação ou todas as animações

Se você quiser desabilitar as animações que especificou, você tem múltiplas opções.

1. Crie uma classe personalizada que force animation e transition para `none`.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

Aplicar esta classe a um elemento impede que qualquer animação seja disparada nesse elemento. Você poderia alternativamente delimitar isso ao seu DOM inteiro ou seção do seu DOM para aplicar esse comportamento. No entanto, isso impede que eventos de animação sejam disparados. Se você está aguardando eventos de animação para remoção de elemento, essa solução não funcionará. Uma solução alternativa é definir as durações para 1 milissegundo.

2. Use a media query [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) para garantir que nenhuma animação seja reproduzida para usuários que preferem menos animação.

3. Previna adicionar classes de animação programaticamente

### Callbacks de Animação

Se você tem ações que gostaria de executar em certos pontos durante as animações, há vários eventos disponíveis que você pode ouvir. Aqui estão alguns deles.

[`OnAnimationStart`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationstart_event)
[`OnAnimationEnd`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationend_event)
[`OnAnimationIteration`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationitration_event)
[`OnAnimationCancel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationcancel_event)

[`OnTransitionStart`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionstart_event)
[`OnTransitionRun`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionrun_event)
[`OnTransitionEnd`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionend_event)
[`OnTransitionCancel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitioncancel_event)

A Web Animations API tem muita funcionalidade adicional. [Dê uma olhada na documentação](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) para ver todas as APIs de animação disponíveis.

NOTA: Esteja ciente de problemas de bubbling com esses callbacks. Se você está animando filhos e pais, os eventos sobem dos filhos para os pais. Considere parar a propagação ou olhar mais detalhes dentro do evento para determinar se você está respondendo ao evento alvo desejado em vez de um evento subindo de um nó filho. Você pode examinar a propriedade `animationname` ou as propriedades sendo transicionadas para verificar se você tem os nós certos.

## Sequências Complexas

Animações são frequentemente mais complicadas do que apenas um simples fade in ou fade out. Você pode ter muitas sequências complicadas de animações que pode querer executar. Vamos dar uma olhada em alguns desses cenários possíveis.

### Escalonando animações em uma lista

Um efeito comum é escalonar as animações de cada item em uma lista para criar um efeito cascata. Isso pode ser realizado utilizando `animation-delay` ou `transition-delay`. Aqui está um exemplo de como esse CSS pode parecer.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts">
    <docs-code header="stagger.component.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts" />
    <docs-code header="stagger.component.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.html" />
    <docs-code header="stagger.component.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.css" />
</docs-code-multifile>

### Animações Paralelas

Você pode aplicar múltiplas animações a um elemento de uma vez usando a propriedade de atalho `animation`. Cada uma pode ter suas próprias durações e delays. Isso permite que você componha animações juntas e crie efeitos complicados.

```css
.target-element {
  animation: rotate 3s, fade-in 2s;
}
```

Neste exemplo, as animações `rotate` e `fade-in` disparam ao mesmo tempo, mas têm durações diferentes.

### Animando os itens de uma lista reordenada

Itens em um loop `@for` serão removidos e readicionados, o que disparará animações usando `@starting-styles` para animações de entrada. Alternativamente, você pode usar `animate.enter` para esse mesmo comportamento. Use `animate.leave` para animar elementos à medida que eles são removidos, como visto no exemplo abaixo.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts">
    <docs-code header="reorder.component.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts" />
    <docs-code header="reorder.component.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.html" />
    <docs-code header="reorder.component.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.css" />
</docs-code-multifile>

## Controle programático de animações

Você pode recuperar animações de um elemento diretamente usando [`Element.getAnimations()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations). Isso retorna um array de cada [`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation) naquele elemento. Você pode usar a API `Animation` para fazer muito mais do que poderia com o que o `AnimationPlayer` do pacote de animations oferecia. A partir daqui você pode `cancel()`, `play()`, `pause()`, `reverse()` e muito mais. Esta API nativa deve fornecer tudo que você precisa para controlar suas animações.

## Mais sobre animações Angular

Você também pode estar interessado no seguinte:

# Animações de transição de route

Animações de transição de route melhoram a experiência do usuário fornecendo transições visuais suaves ao navegar entre diferentes visualizações na sua aplicação Angular. O [Angular Router](/guide/routing/overview) inclui suporte integrado para a API de View Transitions do navegador, permitindo animações perfeitas entre mudanças de route em navegadores suportados.

ÚTIL: A integração nativa de View Transitions do Router está atualmente em [developer preview](/reference/releases#developer-preview). View Transitions nativas são um recurso de navegador relativamente novo com suporte limitado em todos os navegadores.

## Como funcionam as View Transitions

View transitions usam a API nativa do navegador [`document.startViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) para criar animações suaves entre diferentes estados da sua aplicação. A API funciona:

1. **Capturando o estado atual** - O navegador tira uma captura de tela da página atual
2. **Executando a atualização do DOM** - Sua função de callback roda para atualizar o DOM
3. **Capturando o novo estado** - O navegador captura o estado atualizado da página
4. **Reproduzindo a transição** - O navegador anima entre os estados antigo e novo

Aqui está a estrutura básica da API `startViewTransition`:

```ts
document.startViewTransition(async () => {
  await updateTheDOMSomehow();
});
```

Para mais detalhes sobre a API do navegador, veja o [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions).

## Como o Router usa view transitions

O Angular Router integra view transitions no ciclo de vida de navegação para criar mudanças de route perfeitas. Durante a navegação, o Router:

1. **Completa a preparação da navegação** - Correspondência de route, [lazy loading](/guide/routing/define-routes#lazily-loaded-components), [guards](/guide/routing/route-guards) e [resolvers](/guide/routing/data-resolvers) são executados
2. **Inicia a view transition** - O Router chama `startViewTransition` quando as routes estão prontas para ativação
3. **Atualiza o DOM** - O Router ativa novas routes e desativa antigas dentro do callback de transição
4. **Finaliza a transição** - A Promise de transição é resolvida quando o Angular completa a renderização

A integração de view transition do Router age como um [progressive enhancement](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement). Quando os navegadores não suportam a API de View Transitions, o Router realiza atualizações normais do DOM sem animação, garantindo que sua aplicação funcione em todos os navegadores.

## Habilitando View Transitions no Router

Habilite view transitions adicionando o recurso `withViewTransitions` à sua [configuração de router](/guide/routing/define-routes#adding-the-router-to-your-application). O Angular suporta abordagens de bootstrap standalone e NgModule:

### Bootstrap standalone

```ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideRouter, withViewTransitions } from '@angular/router';
import { routes } from './app.routes';

bootstrapApplication(MyApp, {
  providers: [
    provideRouter(routes, withViewTransitions()),
  ]
});
```

### Bootstrap NgModule

```ts
import { NgModule } from '@angular/core';
import { RouterModule } from '@angular/router';

@NgModule({
  imports: [RouterModule.forRoot(routes, {enableViewTransitions: true})]
})
export class AppRouting {}
```

[Experimente o exemplo "count" no StackBlitz](https://stackblitz.com/edit/stackblitz-starters-2dnvtm?file=src%2Fmain.ts)

Este exemplo demonstra como a navegação do router pode substituir chamadas diretas de `startViewTransition` para atualizações de contador.

## Personalizando transições com CSS

Você pode personalizar view transitions usando CSS para criar efeitos de animação únicos. O navegador cria elementos de transição separados que você pode segmentar com seletores CSS.

Para criar transições personalizadas:

1. **Adicione view-transition-name** - Atribua nomes únicos aos elementos que você deseja animar
2. **Defina animações globais** - Crie animações CSS nos seus estilos globais
3. **Segmente pseudo-elementos de transição** - Use os seletores `::view-transition-old()` e `::view-transition-new()`

Aqui está um exemplo que adiciona um efeito de rotação a um elemento contador:

```css
/* Define keyframe animations */
@keyframes rotate-out {
  to {
    transform: rotate(90deg);
  }
}

@keyframes rotate-in {
  from {
    transform: rotate(-90deg);
  }
}

/* Target view transition pseudo-elements */
::view-transition-old(count),
::view-transition-new(count) {
  animation-duration: 200ms;
  animation-name: -ua-view-transition-fade-in, rotate-in;
}

::view-transition-old(count) {
  animation-name: -ua-view-transition-fade-out, rotate-out;
}
```

IMPORTANTE: Defina animações de view transition no seu arquivo de estilos globais, não nos estilos de component. O [view encapsulation](/guide/components/styling#view-encapsulation) do Angular escopa estilos de component, o que impede que eles segmentem os pseudo-elementos de transição corretamente.

[Experimente o exemplo "count" atualizado no StackBlitz](https://stackblitz.com/edit/stackblitz-starters-fwn4i7?file=src%2Fmain.ts)

## Controle avançado de transição com onViewTransitionCreated

O recurso `withViewTransitions` aceita um objeto de opções com um callback `onViewTransitionCreated` para controle avançado sobre view transitions. Este callback:

- Roda em um [injection context](/guide/di/dependency-injection-context#run-within-an-injection-context)
- Recebe um objeto [`ViewTransitionInfo`](/api/router/ViewTransitionInfo) contendo:
  - A instância `ViewTransition` de `startViewTransition`
  - O [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) para a route de onde está navegando
  - O [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) para a route para onde está navegando

Use este callback para personalizar o comportamento de transição com base no contexto de navegação. Por exemplo, você pode pular transições para tipos específicos de navegação:

```ts
import { inject } from '@angular/core';
import { Router, withViewTransitions } from '@angular/router';

withViewTransitions({
  onViewTransitionCreated: ({transition}) => {
    const router = inject(Router);
    const targetUrl = router.getCurrentNavigation()!.finalUrl!;

// Skip transition if only fragment or query params change
    const config = {
      paths: 'exact',
      matrixParams: 'exact',
      fragment: 'ignored',
      queryParams: 'ignored',
    };

if (router.isActive(targetUrl, config)) {
      transition.skipTransition();
    }
  },
})
```

Este exemplo pula a view transition quando a navegação apenas muda o [fragmento de URL ou query parameters](/guide/routing/read-route-state#query-parameters) (como links âncora dentro da mesma página). O método `skipTransition()` previne a animação enquanto ainda permite que a navegação seja completada.

## Exemplos do Chrome explainer adaptados para Angular

Os exemplos a seguir demonstram várias técnicas de view transition adaptadas da documentação da equipe do Chrome para uso com o Angular Router:

### Elementos em transição não precisam ser o mesmo elemento DOM

Elementos podem transicionar suavemente entre diferentes elementos DOM, desde que compartilhem o mesmo `view-transition-name`.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning_elements_dont_need_to_be_the_same_dom_element)
- [Exemplo Angular no StackBlitz](https://stackblitz.com/edit/stackblitz-starters-dh8npr?file=src%2Fmain.ts)

### Animações de entrada e saída personalizadas

Crie animações únicas para elementos entrando e saindo do viewport durante transições de route.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#custom_entry_and_exit_transitions)
- [Exemplo Angular no StackBlitz](https://stackblitz.com/edit/stackblitz-starters-8kly3o)

### Atualizações assíncronas do DOM e espera por conteúdo

O Angular Router prioriza transições imediatas sobre esperar por conteúdo adicional para carregar.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#async_dom_updates_and_waiting_for_content)

NOTA: O Angular Router não fornece uma maneira de atrasar view transitions. Esta escolha de design evita que as páginas se tornem não interativas enquanto aguardam conteúdo adicional. Como a documentação do Chrome observa: "Durante este tempo, a página está congelada, então os atrasos aqui devem ser mantidos ao mínimo...em alguns casos é melhor evitar o atraso completamente e usar o conteúdo que você já tem."

### Lidar com múltiplos estilos de view transition com view transition types

Use view transition types para aplicar diferentes estilos de animação com base no contexto de navegação.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#view-transition-types)
- [Exemplo Angular no StackBlitz](https://stackblitz.com/edit/stackblitz-starters-vxzcam)

### Lidar com múltiplos estilos de view transition com um nome de classe na raiz de view transition (descontinuado)

Esta abordagem usa classes CSS no elemento raiz de transição para controlar estilos de animação.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#changing-on-navigation-type)
- [Exemplo Angular no StackBlitz](https://stackblitz.com/edit/stackblitz-starters-nmnzzg?file=src%2Fmain.ts)

### Transicionando sem congelar outras animações

Mantenha outras animações de página durante view transitions para criar experiências de usuário mais dinâmicas.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning-without-freezing)
- [Exemplo Angular no StackBlitz](https://stackblitz.com/edit/stackblitz-starters-76kgww)

### Animando com JavaScript

Controle view transitions programaticamente usando APIs JavaScript para cenários de animação complexos.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#animating-with-javascript)
- [Exemplo Angular no StackBlitz](https://stackblitz.com/edit/stackblitz-starters-cklnkm)

# Migrando do pacote de Animações do Angular

O pacote `@angular/animations` está descontinuado a partir da v20.2, que também introduziu os novos recursos `animate.enter` e `animate.leave` para adicionar animações à sua aplicação. Usando esses novos recursos, você pode substituir todas as animações baseadas em `@angular/animations` por CSS puro ou bibliotecas de animação JS. Remover `@angular/animations` da sua aplicação pode reduzir significativamente o tamanho do seu bundle JavaScript. Animações CSS nativas geralmente oferecem performance superior, pois podem se beneficiar de aceleração por hardware. Este guia percorre o processo de refatoração do seu código de `@angular/animations` para animações CSS nativas.

## Como escrever animações em CSS nativo

Confira alguns destes vários guias e tutoriais, e depois volte a este guia.

## Criando Animações Reutilizáveis

Assim como com o pacote de animations, você pode criar animações reutilizáveis que podem ser compartilhadas em toda a sua aplicação. A versão do pacote de animations tinha você usando a função `animation()` em um arquivo typescript compartilhado. A versão CSS nativa disso é similar, mas fica em um arquivo CSS compartilhado.

#### Com Pacote de Animations

<docs-code header="src/app/animations.ts" path="adev/src/content/examples/animations/src/app/animations.1.ts" visibleRegion="animation-example"/>

#### Com CSS Nativo

<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-shared"/>

Adicionar a classe `animated-class` a um elemento acionaria a animação nesse elemento.

## Animando uma Transição

### Animando Estado e Estilos

O pacote de animations permitia que você definisse vários estados usando a função [`state()`](api/animations/state) dentro de um component. Exemplos podem ser um estado `open` ou `closed` contendo os estilos para cada respectivo estado dentro da definição. Por exemplo:

#### Com Pacote de Animations

<docs-code header="src/app/open-close.component.ts" path="adev/src/content/examples/animations/src/app/open-close.component.ts" visibleRegion="state1"/>

Esse mesmo comportamento pode ser realizado nativamente usando classes CSS, seja usando uma animação de keyframe ou estilização de transition.

#### Com CSS Nativo

<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-states"/>

Você pode ver exemplos semelhantes no guia de template para [animar estilos diretamente](guide/templates/binding#css-style-properties).

### Transitions, Timing e Easing

A função `animate()` do pacote de animations permite fornecer timing, como duração, delays e easing. Isso pode ser feito nativamente com CSS usando várias propriedades CSS ou propriedades de atalho.

Especifique `animation-duration`, `animation-delay` e `animation-timing-function` para uma animação de keyframe em CSS, ou alternativamente use a propriedade de atalho `animation`.

<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="animation-timing"/>

Da mesma forma, você pode usar `transition-duration`, `transition-delay` e `transition-timing-function` e o atalho `transition` para animações que não estão usando `@keyframes`.

<docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="transition-timing"/>

### Acionando uma Animação

O pacote de animations requeria especificar triggers usando a função `trigger()` e aninhar todos os seus estados dentro dela. Com CSS nativo, isso é desnecessário. Animações podem ser acionadas alternando estilos ou classes CSS. Uma vez que uma classe está presente em um elemento, a animação ocorrerá. Remover a classe reverterá o elemento de volta para qualquer CSS que esteja definido para esse elemento. Isso resulta em significativamente menos código para fazer a mesma animação. Aqui está um exemplo:

#### Com Pacote de Animations
#### Com CSS Nativo

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts">
    <docs-code header="src/app/open-close.component.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts" />
    <docs-code header="src/app/open-close.component.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.html" />
    <docs-code header="src/app/open-close.component.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.css"/>
</docs-code-multifile>

## Transition e Triggers

### Estado Predefinido e correspondência com wildcard

O pacote de animations oferece a capacidade de corresponder seus estados definidos a uma transition via strings. Por exemplo, animar de open para closed seria `open => closed`. Você pode usar wildcards para corresponder qualquer estado a um estado alvo, como `* => closed` e a palavra-chave `void` pode ser usada para estados de entrada e saída. Por exemplo: `* => void` para quando um elemento sai de uma view ou `void => *` para quando o elemento entra em uma view.

Esses padrões de correspondência de estado não são necessários de forma alguma ao animar com CSS diretamente. Você pode gerenciar quais transitions e animações `@keyframes` aplicam com base em quaisquer classes que você define e/ou estilos que você define nos elementos. Você também pode adicionar `@starting-style` para controlar como o elemento fica ao entrar imediatamente no DOM.

### Cálculo Automático de Propriedade com Wildcards

O pacote de animations oferece a capacidade de animar coisas que foram historicamente difíceis de animar, como animar uma altura definida para `height: auto`. Você agora pode fazer isso com CSS puro também.

#### Com Pacote de Animations
Você pode usar css-grid para animar para altura automática.

#### Com CSS Nativo

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts">
    <docs-code header="src/app/auto-height.component.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts" />
    <docs-code header="src/app/auto-height.component.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.html" />
    <docs-code header="src/app/auto-height.component.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.css"  />
</docs-code-multifile>

### Animar entrada e saída de uma view

O pacote de animations oferecia o padrão de correspondência mencionado anteriormente para entrada e saída, mas também incluía os aliases de atalho de `:enter` e `:leave`.

#### Com Pacote de Animations
Aqui está como a mesma coisa pode ser realizada sem o pacote de animations usando `animate.enter`.

#### Com CSS Nativo

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts">
    <docs-code header="src/app/insert.component.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts" />
    <docs-code header="src/app/insert.component.html" path="adev/src/content/examples/animations/src/app/native-css/insert.component.html" />
    <docs-code header="src/app/insert.component.css" path="adev/src/content/examples/animations/src/app/native-css/insert.component.css"  />
</docs-code-multifile>

Use `animate.leave` para animar elementos à medida que eles saem da view, o que aplicará as classes CSS especificadas ao elemento à medida que ele sai da view.

#### Com CSS Nativo

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts">
    <docs-code header="src/app/remove.component.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts" />
    <docs-code header="src/app/remove.component.html" path="adev/src/content/examples/animations/src/app/native-css/remove.component.html" />
    <docs-code header="src/app/remove.component.css" path="adev/src/content/examples/animations/src/app/native-css/remove.component.css"  />
</docs-code-multifile>

Para mais informações sobre `animate.enter` e `animate.leave`, veja o [guia de animações Enter e Leave](guide/animations).

### Animando incremento e decremento

Juntamente com os mencionados `:enter` e `:leave`, também há `:increment` e `:decrement`. Você pode animar esses também adicionando e removendo classes. Ao contrário dos aliases integrados do pacote de animation, não há aplicação automática de classes quando os valores sobem ou descem. Você pode aplicar as classes apropriadas programaticamente. Aqui está um exemplo:

#### Com Pacote de Animations
#### Com CSS Nativo

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts">
    <docs-code header="src/app/increment-decrement.component.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts" />
    <docs-code header="src/app/increment-decrement.component.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.html" />
    <docs-code header="src/app/increment-decrement.component.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.css" />
</docs-code-multifile>

### Animações Pai / Filho

Ao contrário do pacote de animations, quando múltiplas animações são especificadas dentro de um determinado component, nenhuma animação tem prioridade sobre outra e nada bloqueia qualquer animação de disparar. Qualquer sequenciamento de animações teria que ser tratado pela sua definição da sua animação CSS, usando animation / transition delay, e/ou usando `animationend` ou `transitionend` para tratar a adição do próximo CSS a ser animado.

### Desabilitando uma animação ou todas as animações

Com animações CSS nativas, se você quiser desabilitar as animações que especificou, você tem múltiplas opções.

1. Crie uma classe personalizada que force animation e transition para `none`.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

3. Previna adicionar classes de animação programaticamente

### Callbacks de Animação

O pacote de animations expunha callbacks para você usar no caso de querer fazer algo quando a animação terminou. Animações CSS nativas também têm esses callbacks.

## Sequências Complexas

O pacote de animations tem funcionalidade integrada para criar sequências complexas. Essas sequências são todas inteiramente possíveis sem o pacote de animations.

### Direcionando elementos específicos

No pacote de animations, você poderia direcionar elementos específicos usando a função `query()` para encontrar elementos específicos por um nome de classe CSS, similar a [`document.querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector). Isso é desnecessário em um mundo de animação CSS nativa. Em vez disso, você pode usar seus seletores CSS para direcionar subclasses e aplicar qualquer `transform` ou `animation` desejada.

Para alternar classes para nós filhos dentro de um template, você pode usar bindings de classe e estilo para adicionar as animações nos pontos certos.

### Stagger()

A função `stagger()` permitia que você atrasasse a animação de cada item em uma lista de itens por um tempo especificado para criar um efeito cascata. Você pode replicar esse comportamento em CSS nativo utilizando `animation-delay` ou `transition-delay`. Aqui está um exemplo de como esse CSS pode parecer.

#### Com Pacote de Animations
#### Com CSS Nativo

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts">
    <docs-code header="src/app/stagger.component.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts" />
    <docs-code header="src/app/stagger.component.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.html" />
    <docs-code header="src/app/stagger.component.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.css" />
</docs-code-multifile>

### Animações Paralelas

O pacote de animations tem uma função `group()` para reproduzir múltiplas animações ao mesmo tempo. Em CSS, você tem controle total sobre o timing da animação. Se você tem múltiplas animações definidas, você pode aplicar todas elas de uma vez.

```css
.target-element {
  animation: rotate 3s, fade-in 2s;
}
```

Neste exemplo, as animações `rotate` e `fade-in` disparam ao mesmo tempo.

### Animando os itens de uma lista reordenada

Itens reordenando em uma lista funciona imediatamente usando as técnicas descritas anteriormente. Nenhum trabalho especial adicional é necessário. Itens em um loop `@for` serão removidos e readicionados adequadamente, o que disparará animações usando `@starting-styles` para animações de entrada. Alternativamente, você pode usar `animate.enter` para esse mesmo comportamento. Use `animate.leave` para animar elementos à medida que eles são removidos, como visto no exemplo acima.

#### Com Pacote de Animations<
#### Com CSS Nativo

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts">
    <docs-code header="src/app/reorder.component.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts" />
    <docs-code header="src/app/reorder.component.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.html" />
    <docs-code header="src/app/reorder.component.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.css" />
</docs-code-multifile>

## Migrando usos de AnimationPlayer

A classe `AnimationPlayer` permite acesso a uma animação para fazer coisas mais avançadas como pausar, reproduzir, reiniciar e terminar uma animação através de código. Todas essas coisas podem ser tratadas nativamente também.

## Transições de Rota

Você pode usar view transitions para animar entre rotas. Veja o [Guia de Animações de Transição de Rota](guide/routing/route-transition-animations) para começar.

# Angular sem ZoneJS (Zoneless)

## Por que usar Zoneless?

As principais vantagens de remover ZoneJS como uma dependência são:

- **Desempenho melhorado**: ZoneJS usa eventos do DOM e tarefas assíncronas como indicadores de quando o estado da aplicação _pode_ ter atualizado e, subsequentemente, aciona a sincronização da aplicação para executar change detection nas views da aplicação. ZoneJS não tem nenhuma visão sobre se o estado da aplicação realmente mudou e, portanto, essa sincronização é acionada com mais frequência do que o necessário.
- **Core Web Vitals melhorados**: ZoneJS traz uma quantidade considerável de overhead, tanto em tamanho de payload quanto em custo de tempo de inicialização.
- **Experiência de debugging melhorada**: ZoneJS torna a depuração de código mais difícil. Stack traces são mais difíceis de entender com ZoneJS. Também é difícil entender quando o código quebra como resultado de estar fora da Angular Zone.
- **Melhor compatibilidade com o ecossistema**: ZoneJS funciona através de patching de APIs do navegador, mas não tem automaticamente patches para cada nova API do navegador. Algumas APIs não podem ser patchadas de forma eficaz, como `async`/`await`, e precisam ser rebaixadas para funcionar com ZoneJS. Às vezes, bibliotecas no ecossistema também são incompatíveis com a forma como ZoneJS patcha as APIs nativas. Remover ZoneJS como uma dependência garante melhor compatibilidade de longo prazo removendo uma fonte de complexidade, monkey patching e manutenção contínua.

## Habilitando Zoneless em uma aplicação

```typescript
// standalone bootstrap
bootstrapApplication(MyApp, {providers: [
  provideZonelessChangeDetection(),
]});

// NgModule bootstrap
platformBrowser().bootstrapModule(AppModule);
@NgModule({
  providers: [provideZonelessChangeDetection()]
})
export class AppModule {}
```

## Removendo ZoneJS

Aplicações zoneless devem remover ZoneJS inteiramente do build para reduzir o tamanho do bundle. ZoneJS é tipicamente
carregado via opção `polyfills` em `angular.json`, tanto nos targets `build` quanto `test`. Remova `zone.js`
e `zone.js/testing` de ambos para removê-lo do build. Projetos que usam um arquivo `polyfills.ts` explícito
devem remover `import 'zone.js';` e `import 'zone.js/testing';` do arquivo.

Depois de remover ZoneJS do build, não há mais necessidade de uma dependência `zone.js` e o
pacote pode ser removido inteiramente:

```shell
npm uninstall zone.js
```

## Requisitos para compatibilidade Zoneless

O Angular depende de notificações de APIs core para determinar quando executar change detection e em quais views.
Essas notificações incluem:

- `ChangeDetectorRef.markForCheck` (chamado automaticamente por `AsyncPipe`)
- `ComponentRef.setInput`
- Atualizar um signal que é lido em um template
- Callbacks de listeners de host ou template bound
- Anexar uma view que foi marcada como dirty por um dos itens acima

### Components compatíveis com `OnPush`

Uma maneira de garantir que um component está usando os mecanismos de notificação corretos acima é
usar [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush).

A estratégia de change detection `OnPush` não é obrigatória, mas é uma etapa recomendada em direção à compatibilidade zoneless para components de aplicação. Nem sempre é possível para components de biblioteca usar `ChangeDetectionStrategy.OnPush`.
Quando um component de biblioteca é um host para user-components que podem usar `ChangeDetectionStrategy.Default`, ele não pode usar `OnPush` porque isso impediria que o component filho fosse atualizado se não for compatível com `OnPush` e depende de ZoneJS para acionar change detection. Components podem usar a estratégia `Default` desde que notifiquem o Angular quando change detection precisa executar (chamando `markForCheck`, usando signals, `AsyncPipe`, etc.).
Ser um host para um user component significa usar uma API como `ViewContainerRef.createComponent` e não apenas hospedar uma parte de um template de um user component (ou seja, projeção de conteúdo ou usar um input de template ref).

### Remover `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, `NgZone.isStable`, ou `NgZone.onStable`

Aplicações e bibliotecas precisam remover usos de `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable` e `NgZone.onStable`.
Esses observables nunca emitirão quando uma Aplicação habilitar zoneless change detection.
Da mesma forma, `NgZone.isStable` sempre será `true` e não deve ser usado como uma condição para execução de código.

Os observables `NgZone.onMicrotaskEmpty` e `NgZone.onStable` são mais frequentemente usados para esperar o Angular
completar change detection antes de realizar uma tarefa. Em vez disso, eles podem ser substituídos por `afterNextRender`
se precisarem esperar por um único change detection ou `afterEveryRender` se houver alguma condição que pode abranger
várias rodadas de change detection. Em outros casos, esses observables foram usados porque eram
familiares e tinham timing similar ao que era necessário. APIs DOM mais diretas ou diretas podem ser usadas em vez disso,
como `MutationObserver` quando o código precisa esperar por certo estado do DOM (em vez de esperar por ele indiretamente
através dos hooks de renderização do Angular).
`NgZone.run` e `NgZone.runOutsideAngular` não precisam ser removidos para que o código seja compatível com
aplicações Zoneless. Na verdade, remover essas chamadas pode levar a regressões de desempenho para bibliotecas que
são usadas em aplicações que ainda dependem de ZoneJS.
### `PendingTasks` para Server Side Rendering (SSR)

Se você está usando SSR com Angular, você pode saber que ele depende de ZoneJS para ajudar a determinar quando a aplicação
está "estável" e pode ser serializada. Se houver tarefas assíncronas que devem prevenir serialização, uma aplicação
que não usa ZoneJS deve tornar o Angular ciente dessas com o serviço [PendingTasks](/api/core/PendingTasks). A serialização
aguardará o primeiro momento em que todas as tarefas pendentes foram removidas.

Os dois usos mais diretos de pending tasks são o método `run`:

```typescript
const taskService = inject(PendingTasks);
taskService.run(async () => {
  const someResult = await doSomeWorkThatNeedsToBeRendered();
  this.someState.set(someResult);
});
```

Para casos de uso mais complicados, você pode adicionar e remover manualmente uma pending task:

```typescript
const taskService = inject(PendingTasks);
const taskCleanup = taskService.add();
try {
  await doSomeWorkThatNeedsToBeRendered();
} catch {
  // handle error
} finally {
  taskCleanup();
}
```

Além disso, o helper [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent#) em `rxjs-interop` garante
que a aplicação permaneça instável até que o observable emita, complete, dê erro ou seja unsubscribed.

```typescript
readonly myObservableState = someObservable.pipe(pendingUntilEvent());
```

O framework usa este serviço internamente também para prevenir serialização até que tarefas assíncronas estejam completas. Isso inclui, mas não se limita a,
uma navegação de Router em andamento e uma requisição `HttpClient` incompleta.

## Testes e Debugging

### Usando Zoneless em `TestBed`

A função provider zoneless também pode ser usada com `TestBed` para ajudar
a garantir que os components sob teste sejam compatíveis com uma aplicação
Angular Zoneless.

```typescript
TestBed.configureTestingModule({
  providers: [provideZonelessChangeDetection()]
});

const fixture = TestBed.createComponent(MyComponent);
await fixture.whenStable();
```

Para garantir que os testes tenham o comportamento mais similar ao código de produção,
evite usar `fixture.detectChanges()` quando possível. Isso força
change detection a executar quando o Angular de outra forma pode não ter
agendado change detection. Os testes devem garantir que essas notificações
estão acontecendo e permitir que o Angular controle quando sincronizar
o estado em vez de forçá-lo manualmente a acontecer no teste.

Para suites de teste existentes, usar `fixture.detectChanges()` é um padrão comum
e provavelmente não vale o esforço de converter esses para
`await fixture.whenStable()`. `TestBed` ainda aplicará que o
component do fixture seja compatível com `OnPush` e lança `ExpressionChangedAfterItHasBeenCheckedError`
se encontrar que valores de template foram atualizados sem uma
notificação de mudança (ou seja, `fixture.componentInstance.someValue = 'newValue';`).
Se o component é usado em produção, este problema deve ser resolvido atualizando
o component para usar signals para estado ou chamar `ChangeDetectorRef.markForCheck()`.
Se o component é usado apenas como um wrapper de teste e nunca usado em uma aplicação,
é aceitável usar `fixture.changeDetectorRef.markForCheck()`.

### Verificação em modo debug para garantir que atualizações são detectadas

O Angular também fornece uma ferramenta adicional para ajudar a verificar que uma aplicação está fazendo
atualizações de estado de uma forma compatível com zoneless. `provideCheckNoChangesConfig({exhaustive: true, interval: <milliseconds>})`
pode ser usado para verificar periodicamente para garantir que nenhum binding foi atualizado
sem uma notificação. O Angular lança `ExpressionChangedAfterItHasBeenCheckedError`
se houver um binding atualizado que não teria sido atualizado pela change
detection zoneless.

Como um projeto open source, os commits diários, PRs e o progresso do Angular podem ser acompanhados no GitHub. Para aumentar a transparência sobre como esse trabalho diário se conecta ao futuro do framework, nosso roadmap reúne a visão atual e futura planejada pelo time.

Os projetos a seguir não estão associados a uma versão específica do Angular. Nós os lançaremos quando estiverem completos, e eles farão parte de uma versão específica baseada em nosso cronograma de lançamento, seguindo o versionamento semântico. Por exemplo, lançamos funcionalidades na próxima versão minor após a conclusão, ou na próxima major se incluírem mudanças que quebram compatibilidade.

Atualmente, o Angular tem dois objetivos para o framework:

1. Melhorar a [experiência do desenvolvedor Angular](#improving-the-angular-developer-experience) e
2. Melhorar a performance do framework.

Continue lendo para saber como planejamos entregar esses objetivos com trabalhos de projetos específicos.

## Explore o Angular moderno

Comece a desenvolver com as funcionalidades mais recentes do Angular do nosso roadmap. Esta lista representa o status atual de novas funcionalidades do nosso roadmap:

### Disponível para experimentação

- [Resource API](/guide/signals/resource)
- [httpResource](/api/common/http/httpResource)

### Pronto para produção

- [Detecção de mudanças sem zone](/guide/zoneless)
- [Linked Signal API](/guide/signals/linked-signal)
- [Hidratação incremental](/guide/incremental-hydration)
- [Effect API](/api/core/effect)
- [Event replay com SSR](/api/platform-browser/withEventReplay)
- [Modo de renderização por rota](/guide/ssr)

## Melhorando a experiência do desenvolvedor Angular

### Velocidade do desenvolvedor
### Melhorar Angular Material e o CDK
### Melhorar ferramentas
## Trabalho futuro, explorações e prototipagem {#improving-the-angular-developer-experience}

Esta seção representa explorações e prototipagem de potenciais projetos futuros. Um resultado razoável é decidir que nossas soluções atuais são as melhores opções. Outros projetos podem resultar em RFCs, graduando para projetos em andamento, ou sendo despriorizados conforme a web continua a inovar junto com nosso framework.
## Projetos completos

# Mantendo seus projetos Angular atualizados

Assim como a Web e todo o ecossistema web, o Angular está em constante melhoria.
O Angular equilibra melhoria contínua com um forte foco em estabilidade e em tornar as atualizações diretas.
Manter sua aplicação Angular atualizada permite que você aproveite novos recursos de ponta, bem como otimizações e correções de bugs.

Este documento contém informações e recursos para ajudá-lo a manter suas aplicações e bibliotecas Angular atualizadas.

Para informações sobre nossa política e práticas de versionamento — incluindo práticas de suporte e descontinuação, bem como o cronograma de lançamento — veja [Versionamento e lançamentos do Angular](reference/releases 'Angular versioning and releases').

DICA: Se você está usando atualmente AngularJS, veja [Atualizando do AngularJS](https://angular.io/guide/upgrade 'Upgrading from Angular JS').
_AngularJS_ é o nome para todas as versões v1.x do Angular.

## Sendo notificado sobre novos lançamentos

Para ser notificado quando novos lançamentos estiverem disponíveis, siga [@angular](https://x.com/angular '@angular on X') no X (anteriormente Twitter) ou assine o [blog do Angular](https://blog.angular.dev 'Angular blog').

## Aprendendo sobre novos recursos

O que há de novo? O que mudou? Compartilhamos as coisas mais importantes que você precisa saber no blog do Angular em [anúncios de lançamento](https://blog.angular.dev/ 'Angular blog - release announcements').

Para revisar uma lista completa de mudanças, organizadas por versão, veja o [log de mudanças do Angular](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular change log').

## Verificando sua versão do Angular

Para verificar a versão do Angular da sua aplicação, use o comando `ng version` dentro do diretório do seu projeto.

## Encontrando a versão atual do Angular

A versão estável mais recente lançada do Angular aparece [no npm](https://www.npmjs.com/package/@angular/core 'Angular on npm') em "Version." Por exemplo, `16.2.4`.

Você também pode encontrar a versão mais atual do Angular usando o comando da CLI [`ng update`](cli/update).
Por padrão, [`ng update`](cli/update) (sem argumentos adicionais) lista as atualizações que estão disponíveis para você.

## Atualizando seu ambiente e aplicações

Para tornar a atualização descomplicada, fornecemos instruções completas no [Guia de Atualização do Angular](update-guide) interativo.

O Guia de Atualização do Angular fornece instruções de atualização personalizadas, baseadas nas versões atual e de destino que você especificar.
Ele inclui caminhos de atualização básicos e avançados, para corresponder à complexidade de suas aplicações.
Também inclui informações de solução de problemas e quaisquer mudanças manuais recomendadas para ajudá-lo a aproveitar ao máximo o novo lançamento.

Para atualizações simples, o comando da CLI [`ng update`](cli/update) é tudo que você precisa.
Sem argumentos adicionais, [`ng update`](cli/update) lista as atualizações que estão disponíveis para você e fornece etapas recomendadas para atualizar sua aplicação para a versão mais atual.

[Versionamento e Lançamentos do Angular](reference/releases#versioning 'Angular Release Practices, Versioning') descreve o nível de mudança que você pode esperar com base no número de versão de um lançamento.
Também descreve caminhos de atualização suportados.

## Resumo de recursos

- Anúncios de lançamento:
  [Blog do Angular - anúncios sobre lançamentos recentes](https://blog.angular.dev/ 'Angular blog announcements about recent releases')

- Detalhes do lançamento:
  [Log de mudanças do Angular](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular change log')

- Instruções de atualização:
  [Guia de Atualização do Angular](update-guide)

- Referência do comando de atualização:
  [Referência do comando `ng update` da CLI Angular](cli/update)

- Práticas de versionamento, lançamento, suporte e descontinuação:
  [Versionamento e lançamentos do Angular](reference/releases 'Angular versioning and releases')

# Segurança do `HttpClient`

O `HttpClient` inclui suporte integrado para dois mecanismos comuns de segurança HTTP: proteção XSSI e proteção XSRF/CSRF.

TIP: Considere também adotar uma [Content Security Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) para suas APIs.

## Proteção XSSI

Cross-Site Script Inclusion (XSSI) é uma forma de ataque de [Cross-Site Scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) onde um atacante carrega dados JSON dos seus endpoints de API como `<script>`s em uma página que eles controlam. Diferentes técnicas JavaScript podem então ser usadas para acessar esses dados.

Uma técnica comum para prevenir XSSI é servir respostas JSON com um "prefixo não-executável", comumente `)]}',\n`. Este prefixo impede que a resposta JSON seja interpretada como JavaScript executável válido. Quando a API é carregada como dados, o prefixo pode ser removido antes da análise JSON.

O `HttpClient` automaticamente remove este prefixo XSSI (se presente) ao analisar JSON de uma resposta.

## Proteção XSRF/CSRF

[Cross-Site Request Forgery (XSRF ou CSRF)](https://en.wikipedia.org/wiki/Cross-site_request_forgery) é uma técnica de ataque pela qual o atacante pode enganar um usuário autenticado para executar ações sem saber em seu website.

O `HttpClient` suporta um [mecanismo comum](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Cookie-to-header_token) usado para prevenir ataques XSRF. Ao realizar requisições HTTP, um interceptor lê um token de um cookie, por padrão `XSRF-TOKEN`, e o define como um header HTTP, `X-XSRF-TOKEN`. Como apenas código que executa no seu domínio pode ler o cookie, o backend pode ter certeza de que a requisição HTTP veio da sua aplicação cliente e não de um atacante.

Por padrão, um interceptor envia este header em todas as requisições mutantes (como `POST`) para URLs relativas, mas não em requisições GET/HEAD ou em requisições com URL absoluta.
Proteção CSRF é necessária apenas para requisições que podem mudar o estado no backend. Por natureza, ataques CSRF cruzam limites de domínio, e a [same-origin policy](https://developer.mozilla.org/docs/Web/Security/Same-origin_policy) da web impedirá que uma página atacante recupere os resultados de requisições GET autenticadas.
Para aproveitar isso, seu servidor precisa definir um token em um cookie de sessão legível por JavaScript chamado `XSRF-TOKEN` ou no carregamento da página ou na primeira requisição GET. Em requisições subsequentes, o servidor pode verificar se o cookie corresponde ao header HTTP `X-XSRF-TOKEN`, e portanto ter certeza de que apenas código executando em seu domínio poderia ter enviado a requisição. O token deve ser único para cada usuário e deve ser verificável pelo servidor; isso impede que o cliente crie seus próprios tokens. Defina o token como um digest do cookie de autenticação do seu site com um salt para segurança adicional.

Para prevenir colisões em ambientes onde múltiplas aplicações Angular compartilham o mesmo domínio ou subdomínio, dê a cada aplicação um nome de cookie único.
  Seu service de backend deve ser configurado para definir o cookie para sua página, e para verificar que o header está presente em todas as requisições elegíveis. Falhar em fazer isso torna a proteção padrão do Angular ineficaz.
### Configurar nomes personalizados de cookie/header

Se seu service de backend usa nomes diferentes para o cookie ou header do token XSRF, use `withXsrfConfiguration` para sobrescrever os padrões.

Adicione-o à chamada `provideHttpClient` da seguinte forma:

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withXsrfConfiguration({
        cookieName: 'CUSTOM_XSRF_TOKEN',
        headerName: 'X-Custom-Xsrf-Header',
      }),
    ),
  ]
};
```

### Desabilitando a proteção XSRF

Se o mecanismo de proteção XSRF integrado não funciona para sua aplicação, você pode desabilitá-lo usando o recurso `withNoXsrfProtection`:

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withNoXsrfProtection(),
    ),
  ]
};
```

# Internacionalização (i18n) no Angular

_Internacionalização_, às vezes referenciada como i18n, é o processo de projetar e preparar seu projeto para uso em diferentes locales ao redor do mundo.
_Localização_ é o processo de construir versões do seu projeto para diferentes locales.
O processo de localização inclui as seguintes ações.

- Extrair texto para tradução em diferentes idiomas
- Formatar dados para um locale específico

Um _locale_ identifica uma região na qual as pessoas falam um idioma ou variante de idioma particular.
As possíveis regiões incluem países e regiões geográficas.
Um locale determina a formatação e análise dos seguintes detalhes.

- Unidades de medida incluindo data e hora, números e moedas
- Nomes traduzidos incluindo fusos horários, idiomas e países

Para uma introdução rápida à localização e internacionalização, assista a este vídeo:

<docs-video src="https://www.youtube.com/embed/KNTN-nsbV7M"/>

## Aprenda sobre internacionalização no Angular