Поддерживаемый специальной командой в Google, Angular предоставляет широкий набор инструментов, API и библиотек, упрощающих и оптимизирующих рабочий процесс разработки. Angular даёт надёжную платформу для создания быстрых и стабильных приложений, которые масштабируются вместе с ростом вашей команды и кодовой базы. Angular.dev — официальный дом документации Angular.

Обзор того, каково работать с Angular

Пошаговые инструкции прямо в браузере

Начните работу с Angular быстро — через онлайн-стартеры или локально в терминале. ## Играйте онлайн {#play-online} Если вы просто хотите поэкспериментировать с Angular в браузере без настройки проекта, используйте нашу онлайн-песочницу: ## Настройка нового проекта локально {#set-up-a-new-project-locally} Если вы начинаете новый проект, скорее всего, захотите создать локальный проект, чтобы использовать такие инструменты, как Git. ### Требования {#prerequisites} - **Node.js** — [v20.19.0 или новее](/reference/versions) - **Текстовый редактор** — рекомендуем [Visual Studio Code](https://code.visualstudio.com/) - **Терминал** — необходим для выполнения команд [Angular CLI](/tools/cli) - **Инструмент разработки** — для улучшения рабочего процесса рекомендуем [Angular Language Service](/tools/language-service) ### Инструкции {#instructions} Следующее руководство проведёт вас через настройку локального проекта Angular. #### Установка Angular CLI {#install-angular-cli} Откройте терминал (если вы используете [Visual Studio Code](https://code.visualstudio.com/), можно открыть [встроенный терминал](https://code.visualstudio.com/docs/editor/integrated-terminal)) и выполните следующую команду: ```shell // npm npm install -g @angular/cli ``` ```shell // pnpm pnpm install -g @angular/cli ``` ```shell // yarn yarn global add @angular/cli ``` ```shell // bun bun install -g @angular/cli ``` Если у вас возникают проблемы с выполнением этой команды в Windows или Unix, ознакомьтесь с [документацией CLI](/tools/cli/setup-local#install-the-angular-cli) для получения дополнительной информации. #### Создание нового проекта {#create-a-new-project} В терминале выполните команду CLI [`ng new`](cli/new) с желаемым именем проекта. В следующих примерах мы будем использовать имя проекта `my-first-angular-app`. ```shell ng new ``` Вам будут предложены параметры конфигурации проекта. Используйте клавиши со стрелками и Enter для навигации и выбора нужных опций. Если у вас нет предпочтений, просто нажмите Enter, чтобы принять значения по умолчанию и продолжить настройку. После выбора параметров конфигурации и завершения настройки CLI вы должны увидеть следующее сообщение: ```text ✔ Packages installed successfully. Successfully initialized git. ``` На этом этапе вы готовы запустить проект локально! #### Локальный запуск нового проекта {#running-your-new-project-locally} В терминале перейдите в новый проект Angular. ```shell cd my-first-angular-app ``` Все зависимости должны быть установлены на этом этапе (это можно проверить наличием папки `node_modules` в проекте), поэтому можно запустить проект командой: ```shell npm start ``` Если всё прошло успешно, в терминале должно появиться похожее подтверждающее сообщение: ```text Watch mode enabled. Watching for file changes... NOTE: Raw file sizes do not reflect development server per-request transformations. ➜ Local: http://localhost:4200/ ➜ press h + enter to show help ``` Теперь можно открыть путь из `Local` (например, `http://localhost:4200/`) и увидеть приложение. Удачного кодинга! 🎉 ### Разработка с помощью ИИ {#using-ai-for-development} Чтобы начать разработку в предпочитаемой IDE с поддержкой ИИ, [ознакомьтесь с правилами промптов и лучшими практиками Angular](/ai/develop-with-ai). ## Следующие шаги {#next-steps} Теперь, когда вы создали проект Angular, вы можете узнать больше об Angular в нашем [руководстве «Основы»](/essentials) или выбрать тему в подробных руководствах! # Руководство по стилю кода Angular ## Введение {#introduction} Это руководство охватывает ряд стилевых соглашений для кода Angular-приложений. Эти рекомендации не обязательны для работы Angular, а задают набор практик, способствующих согласованности в экосистеме Angular. Единый набор практик упрощает обмен кодом и переход между проектами. Это руководство _не_ охватывает TypeScript или общие практики кодирования, не связанные с Angular. Для TypeScript см. [руководство по стилю TypeScript от Google](https://google.github.io/styleguide/tsguide.html). ### В сомнениях предпочитайте согласованность {#when-in-doubt-prefer-consistency} Когда эти правила противоречат стилю конкретного файла, приоритет — сохранять согласованность внутри файла. Смешение разных стилевых соглашений в одном файле создаёт больше путаницы, чем отклонение от рекомендаций этого руководства. ## Именование {#naming} ### Разделяйте слова в именах файлов дефисами {#separate-words-in-file-names-with-hyphens} Разделяйте слова в имени файла дефисами (`-`). Например, компонент с именем `UserProfile` имеет имя файла `user-profile.ts`. ### Используйте то же имя для тестов файла с `.spec` в конце {#use-the-same-name-for-a-files-tests-with-spec-at-the-end} Для unit-тестов заканчивайте имена файлов на `.spec.ts`. Например, файл unit-теста для компонента `UserProfile` имеет имя `user-profile.spec.ts`. ### Сопоставляйте имена файлов с идентификатором TypeScript внутри {#match-file-names-to-the-typescript-identifier-within} Имена файлов обычно должны описывать содержимое кода в файле. Когда файл содержит класс TypeScript, имя файла должно отражать имя этого класса. Например, файл с компонентом `UserProfile` имеет имя `user-profile.ts`. Если в файле больше одного основного именованного идентификатора, выберите имя, описывающее общую тему кода. Если код в файле не укладывается в общую тему или область функции, рассмотрите разбиение на разные файлы. Избегайте слишком общих имён файлов вроде `helpers.ts`, `utils.ts` или `common.ts`. ### Используйте одно имя файла для TypeScript, шаблона и стилей компонента {#use-the-same-file-name-for-a-components-typescript-template-and-styles} Компоненты обычно состоят из одного файла TypeScript, одного файла шаблона и одного файла стилей. Эти файлы должны иметь одно имя с разными расширениями. Например, компонент `UserProfile` может иметь файлы `user-profile.ts`, `user-profile.html` и `user-profile.css`. Если у компонента больше одного файла стилей, добавьте к имени слова, описывающие стили, специфичные для этого файла. Например, у `UserProfile` могут быть файлы стилей `user-profile-settings.css` и `user-profile-subscription.css`. ## Структура проекта {#project-structure} ### Весь код приложения — в каталоге `src` {#all-the-applications-code-goes-in-a-directory-named-src} Весь UI-код Angular (TypeScript, HTML и стили) должен жить в каталоге с именем `src`. Код, не связанный с UI, — конфигурационные файлы или скрипты — должен жить вне каталога `src`. Это сохраняет корневой каталог приложения согласованным между разными Angular-проектами и создаёт чёткое разделение между UI-кодом и остальным кодом проекта. ### Bootstrap приложения — в файле `main.ts` прямо внутри `src` {#bootstrap-your-application-in-a-file-named-maints-directly-inside-src} Код запуска, или **bootstrap**, Angular-приложения всегда должен жить в файле с именем `main.ts`. Это основная точка входа в приложение. ### Группируйте тесно связанные файлы в одном каталоге {#group-closely-related-files-together-in-the-same-directory} Компоненты Angular состоят из файла TypeScript и, опционально, шаблона и одного или нескольких файлов стилей. Их следует группировать в одном каталоге. Unit-тесты должны жить в том же каталоге, что и тестируемый код. Избегайте сбора несвязанных тестов в один каталог `tests`. ### Организуйте проект по областям функций {#organize-your-project-by-feature-areas} Организуйте проект в подкаталоги по функциям приложения или общим темам кода в этих каталогах. Например, структура проекта сайта кинотеатра MovieReel может выглядеть так: ``` src/ ├─ movie-reel/ │ ├─ show-times/ │ │ ├─ film-calendar/ │ │ ├─ film-details/ │ ├─ reserve-tickets/ │ │ ├─ payment-info/ │ │ ├─ purchase-confirmation/ ``` Избегайте создания подкаталогов по типу кода в них. Например, избегайте каталогов вроде `components`, `directives` и `services`. Избегайте помещать в один каталог столько файлов, что в нём становится трудно ориентироваться. По мере роста числа файлов в каталоге рассмотрите дальнейшее разбиение на подкаталоги. ### Одна концепция на файл {#one-concept-per-file} Предпочитайте фокусировать исходные файлы на одной _концепции_. Для классов Angular это обычно означает один компонент, директиву или сервис на файл. Однако допустимо, если файл содержит больше одного компонента или директивы, когда классы относительно малы и связаны как часть одной концепции. В сомнениях выбирайте подход, ведущий к меньшим файлам. ## Внедрение зависимостей {#dependency-injection} ### Предпочитайте функцию `inject` внедрению через параметры конструктора {#prefer-the-inject-function-over-constructor-parameter-injection} Предпочитайте функцию [`inject`](/api/core/inject) внедрению через параметры конструктора. [`inject`](/api/core/inject) работает так же, как внедрение через параметры конструктора, но даёт несколько стилевых преимуществ: - [`inject`](/api/core/inject) обычно читабельнее, особенно когда класс внедряет много зависимостей. - Синтаксически проще добавлять комментарии к внедрённым зависимостям - [`inject`](/api/core/inject) даёт лучший вывод типов. - При таргете ES2022+ с [`useDefineForClassFields`](https://www.typescriptlang.org/tsconfig/#useDefineForClassFields) можно избежать разделения объявления и инициализации полей, когда поля читают внедрённые зависимости. [Существующий код можно рефакторить на `inject` автоматическим инструментом](reference/migrations/inject-function). ## Компоненты и директивы {#components-and-directives} ### Выбор селекторов компонентов {#choosing-component-selectors} См. [руководство по компонентам о выборе селекторов компонентов](guide/components/selectors#choosing-a-selector). ### Именование членов компонентов и директив {#naming-component-and-directive-members} См. руководство по компонентам о [именовании input-свойств](guide/components/inputs#choosing-input-names) и [именовании output-свойств](guide/components/outputs#choosing-event-names). ### Выбор селекторов директив {#choosing-directive-selectors} Директивы должны использовать тот же [префикс, специфичный для приложения](guide/components/selectors#selector-prefixes), что и компоненты. При использовании attribute-селектора для директивы используйте имя атрибута в camelCase. Например, если приложение называется «MovieReel» и вы создаёте директиву, добавляющую tooltip к элементу, можно использовать селектор `[mrTooltip]`. ### Группируйте Angular-специфичные свойства перед методами {#group-angular-specific-properties-before-methods} Компоненты и директивы должны группировать Angular-специфичные свойства вместе, обычно ближе к началу объявления класса. Это включает внедрённые зависимости, input, output и queries. Определяйте их и другие свойства перед методами класса. Так проще находить template API и зависимости класса. ### Держите компоненты и директивы сфокусированными на представлении {#keep-components-and-directives-focused-on-presentation} Код внутри компонентов и директив обычно должен относиться к UI на странице. Для кода, имеющего смысл сам по себе, отдельно от UI, предпочитайте рефакторинг в другие файлы. Например, правила валидации форм или преобразования данных можно вынести в отдельные функции или классы. ### Избегайте излишне сложной логики в шаблонах {#avoid-overly-complex-logic-in-templates} Шаблоны Angular рассчитаны на [выражения, похожие на JavaScript](guide/templates/expression-syntax). Используйте эти выражения, чтобы выражать относительно простую логику прямо в выражениях шаблона. Когда код в шаблоне становится слишком сложным, рефакторьте логику в код TypeScript (обычно с [computed](guide/signals#computed-signals)). Нет жёсткого правила, что считать «сложным». Используйте здравый смысл. ### Используйте `protected` для членов класса, используемых только шаблоном компонента {#use-protected-on-class-members-that-are-only-used-by-a-components-template} Публичные члены класса компонента по сути определяют публичный API, доступный через внедрение зависимостей и [queries](guide/components/queries). Предпочитайте доступ `protected` для любых членов, предназначенных для чтения из шаблона компонента. ```ts @Component({ ..., template: `

`, }) export class UserProfile { firstName = input(); lastName = input(); // `fullName` is not part of the component's public API, but is used in the template. protected fullName = computed(() => `${this.firstName()} ${this.lastName()}`); } ``` ### Используйте `readonly` для свойств, которые не должны меняться {#use-readonly-for-properties-that-shouldnt-change} Помечайте свойства компонентов и директив, инициализируемые Angular, как `readonly`. Это включает свойства, инициализируемые через `input`, `model`, `output` и queries. Модификатор доступа readonly гарантирует, что значение, установленное Angular, не будет перезаписано. ```ts @Component(/* ... */) export class UserProfile { readonly userId = input(); readonly userSaved = output(); readonly userName = model(); } ``` Для компонентов и директив, использующих декораторные API `@Input`, `@Output` и queries, этот совет относится к output-свойствам и queries, но не к input-свойствам. ```ts @Component(/* ... */) export class UserProfile { @Output() readonly userSaved = new EventEmitter(); @ViewChildren(PaymentMethod) readonly paymentMethods?: QueryList; } ``` ### Предпочитайте `class` и `style` вместо `ngClass` и `ngStyle` {#prefer-class-and-style-over-ngclass-and-ngstyle} Предпочитайте привязки `class` и `style` использованию директив [`NgClass`](/api/common/NgClass) и [`NgStyle`](/api/common/NgStyle). ```html {prefer}

``` ```html {avoid}

``` Привязки `class` и `style` используют более прямой синтаксис, близкий к стандартным HTML-атрибутам. Это делает шаблоны проще для чтения и понимания, особенно для разработчиков, знакомых с базовым HTML. Кроме того, директивы `NgClass` и `NgStyle` несут дополнительную стоимость производительности по сравнению со встроенным синтаксисом привязок `class` и `style`. Подробнее — в [руководстве по привязкам](/guide/templates/binding#css-class-and-style-property-bindings) ### Называйте обработчики событий по тому, что они _делают_, а не по событию-триггеру {#name-event-handlers-for-what-they-do-not-for-the-triggering-event} Предпочитайте именовать обработчики событий по выполняемому действию, а не по событию-триггеру: ```html {prefer} ``` ```html {avoid} ``` Осмысленные имена упрощают понимание того, что делает событие, при чтении шаблона. Для событий клавиатуры можно использовать модификаторы клавиш Angular с конкретными именами обработчиков: ```html

```

Иногда логика обработки события особенно длинная или сложная, и объявить один
хорошо названный обработчик непрактично. В таких случаях допустимо имя вроде 'handleKeydown' с
последующей делегацией более конкретным поведениям на основе деталей события:

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

### Держите методы жизненного цикла простыми {#keep-lifecycle-methods-simple}

Избегайте длинной или сложной логики внутри хуков жизненного цикла вроде `ngOnInit`. Вместо этого создавайте
хорошо названные методы с этой логикой и _вызывайте эти методы_ в хуках жизненного цикла.
Имена хуков описывают _когда_ они выполняются, то есть код внутри не имеет
осмысленного имени, описывающего, что он делает.

```ts
{prefer}
ngOnInit() {
  this.startLogging();
  this.runBackgroundTask();
}
```

```ts
{avoid}
ngOnInit() {
  this.logger.setMode('info');
  this.logger.monitorErrors();
  // ...and all the rest of the code that would be unrolled from these methods.
}
```

### Используйте интерфейсы хуков жизненного цикла {#use-lifecycle-hook-interfaces}

Angular предоставляет интерфейс TypeScript для каждого метода жизненного цикла. При добавлении хука жизненного цикла в
класс импортируйте и `implement` эти интерфейсы, чтобы методы были названы правильно.

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

@Component(/* ... */)
export class UserProfile implements OnInit {
  // The `OnInit` interface ensures this method is named correctly.
  ngOnInit() {
    /* ... */
  }
}
```
Компоненты — основные строительные блоки приложений Angular. Каждый компонент представляет часть более крупной веб-страницы. Организация приложения в компоненты помогает структурировать проект, чётко разделяя код на конкретные части, которые легко поддерживать и развивать со временем.

## Определение компонента {#defining-a-component}

У каждого компонента есть несколько основных частей:

1. [Декоратор](https://www.typescriptlang.org/docs/handbook/decorators.html) `@Component`, содержащий конфигурацию, используемую Angular.
2. HTML-шаблон, который управляет тем, что отрисовывается в DOM.
3. [CSS-селектор](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors), определяющий, как компонент используется в HTML.
4. Класс TypeScript с поведением, например обработкой ввода пользователя или запросами к серверу.

Вот упрощённый пример компонента `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 */
}
```

Декоратор `@Component` также опционально принимает свойство `styles` для любого CSS, который вы хотите применить к шаблону:

```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 */
}
```

### Разделение HTML и CSS в отдельные файлы {#separating-html-and-css-into-separate-files}

Вы можете определить HTML и CSS компонента в отдельных файлах с помощью `templateUrl` и `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;
}
```

## Использование компонентов {#using-components}

Вы строите приложение, объединяя несколько компонентов. Например, при создании страницы профиля пользователя можно разбить страницу на несколько компонентов:

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

Здесь компонент `UserProfile` использует несколько других компонентов для формирования итоговой страницы.

Чтобы импортировать и использовать компонент, нужно:

1. В TypeScript-файле компонента добавить оператор `import` для нужного компонента.
2. В декораторе `@Component` добавить запись в массив `imports` для нужного компонента.
3. В шаблоне компонента добавить элемент, соответствующий селектору нужного компонента.

Вот пример компонента `UserProfile`, импортирующего компонент `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
}
```

TIP: Хотите узнать больше о компонентах Angular? См. [Подробное руководство по компонентам](guide/components) для полной информации.

## Следующий шаг {#next-step}

Теперь, когда вы знаете, как работают компоненты в Angular, пора узнать, как добавлять и управлять динамическими данными в приложении.
# Селекторы компонентов

TIP: Это руководство предполагает, что вы уже прочитали [Руководство по основам](essentials). Сначала ознакомьтесь с
ним, если вы новичок в Angular.

Каждый компонент задает [CSS-селектор](https://developer.mozilla.org/docs/Web/CSS/CSS_selectors), который определяет
способ использования компонента:

```typescript
{highlight: [2]}
@Component({
  selector: 'profile-photo',
  ...
})
export class ProfilePhoto { }
```

Вы используете компонент, создавая соответствующий HTML-элемент в шаблонах _других_ компонентов:

```typescript
{highlight: [3]}
@Component({
  template: `
    <profile-photo />
    <button>Upload a new profile photo</button>`,
  ...,
})
export class UserProfile { }
```

**Angular сопоставляет селекторы статически во время компиляции.** Изменение DOM во время выполнения (через привязки
Angular или DOM API) не влияет на отрисованные компоненты.

**Элемент может соответствовать ровно одному селектору компонента.** Если одному элементу соответствуют несколько
селекторов компонентов, Angular сообщает об ошибке.

**Селекторы компонентов чувствительны к регистру.**

## Типы селекторов {#types-of-selectors}

Angular поддерживает ограниченное
подмножество [базовых типов CSS-селекторов](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) в селекторах
компонентов:

| **Тип селектора**    | **Описание**                                                                                | **Примеры**                   |
| -------------------- | ------------------------------------------------------------------------------------------- | ----------------------------- |
| Селектор по типу     | Сопоставляет элементы на основе имени тега HTML или имени узла.                             | `profile-photo`               |
| Селектор по атрибуту | Сопоставляет элементы на основе наличия HTML-атрибута и, опционально, его точного значения. | `[dropzone]` `[type="reset"]` |
| Селектор по классу   | Сопоставляет элементы на основе наличия CSS-класса.                                         | `.menu-item`                  |

Для значений атрибутов Angular поддерживает сопоставление точного значения с помощью оператора равенства (`=`). Angular
не поддерживает другие операторы значений атрибутов.

Селекторы компонентов Angular не поддерживают комбинаторы,
включая [комбинатор потомков](https://developer.mozilla.org/docs/Web/CSS/Descendant_combinator)
или [дочерний комбинатор](https://developer.mozilla.org/docs/Web/CSS/Child_combinator).

Селекторы компонентов Angular не поддерживают
указание [пространств имен](https://developer.mozilla.org/docs/Web/SVG/Namespaces_Crash_Course).

### Псевдокласс `:not` {#the-not-pseudo-class}

Angular поддерживает [псевдокласс `:not`](https://developer.mozilla.org/docs/Web/CSS/:not).
Вы можете добавить этот псевдокласс к любому другому селектору, чтобы сузить круг элементов, которым соответствует
селектор компонента. Например, можно определить селектор атрибута `[dropzone]` и исключить совпадение с элементами
`textarea`:

```typescript
{highlight: [2]}
@Component({
  selector: '[dropzone]:not(textarea)',
  ...
})
export class DropZone { }
```

Angular не поддерживает никакие другие псевдоклассы или псевдоэлементы в селекторах компонентов.

### Комбинирование селекторов {#combining-selectors}

Вы можете комбинировать несколько селекторов, объединяя их. Например, можно выбрать элементы `<button>`, у которых
указан `type="reset"`:

```typescript
{highlight: [2]}
@Component({
  selector: 'button[type="reset"]',
  ...
})
export class ResetButton { }
```

Также можно определить несколько селекторов через запятую:

```typescript
{highlight: [2]}
@Component({
  selector: 'drop-zone, [dropzone]',
  ...
})
export class DropZone { }
```

Angular создает компонент для каждого элемента, который соответствует _любому_ из селекторов в списке.

## Выбор селектора {#choosing-a-selector}

Подавляющее большинство компонентов должно использовать имя пользовательского элемента в качестве селектора. Все имена
пользовательских элементов должны содержать дефис, как описано
в [спецификации HTML](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name).
По умолчанию Angular сообщает об ошибке, если встречает имя пользовательского тега, которое не соответствует ни одному
доступному компоненту, предотвращая ошибки из-за опечаток в именах компонентов.

См. [Расширенная конфигурация компонентов](guide/components/advanced-configuration) для получения подробной информации
об использовании [нативных пользовательских элементов](https://developer.mozilla.org/docs/Web/Web_Components) в шаблонах
Angular.

### Префиксы селекторов {#selector-prefixes}

Команда Angular рекомендует использовать короткий, единообразный префикс для всех пользовательских компонентов,
определенных в вашем проекте. Например, если бы вы создавали YouTube на Angular, вы могли бы использовать префикс `yt-`
для своих компонентов, получая такие имена, как `yt-menu`, `yt-player` и т.д. Использование пространств имен в
селекторах позволяет сразу понять, откуда происходит конкретный компонент. По умолчанию Angular CLI использует префикс
`app-`.

IMPORTANT: Angular использует префикс селектора `ng` для собственных API фреймворка. Никогда не используйте `ng` в качестве
префикса селектора для ваших собственных пользовательских компонентов.

### Когда использовать селектор по атрибуту {#when-to-use-an-attribute-selector}

Вам следует рассмотреть использование селектора по атрибуту, когда вы хотите создать компонент на основе стандартного
нативного элемента. Например, если вы хотите создать пользовательский компонент кнопки, вы можете воспользоваться
стандартным элементом `<button>`, используя селектор по атрибуту:

```typescript
{highlight: [2]}
@Component({
  selector: 'button[yt-upload]',
   ...
})
export class YouTubeUploadButton { }
```

Этот подход позволяет потребителям компонента напрямую использовать все стандартные API элемента без дополнительной
работы. Это особенно ценно для ARIA-атрибутов, таких как `aria-label`.

Angular не сообщает об ошибках, когда встречает пользовательские атрибуты, которые не соответствуют доступному
компоненту. При использовании компонентов с селекторами по атрибуту потребители могут забыть импортировать компонент или
его NgModule, в результате чего компонент не будет отрисован.
См. [Импорт и использование компонентов](guide/components#imports-in-the-component-decorator) для получения дополнительной информации.

Компоненты, определяющие селекторы по атрибутам, должны использовать имена атрибутов в нижнем регистре через дефис. Вы
можете следовать тем же рекомендациям по использованию префиксов, описанным выше.
# Стилизация компонентов

TIP: Это руководство предполагает, что вы уже прочитали [Essentials Guide](essentials). Если вы новичок в Angular, начните с него.

Компоненты опционально могут включать CSS-стили, применяемые к DOM этого компонента:

```typescript
{highlight:[4]}
@Component({
  selector: 'profile-photo',
  template: `<img src="profile-photo.jpg" alt="Your profile photo" />`,
  styles: `
    img {
      border-radius: 50%;
    }
  `,
})
export class ProfilePhoto {}
```

Также можно писать стили в отдельных файлах:

```typescript
{highlight:[4]}
@Component({
  selector: 'profile-photo',
  templateUrl: 'profile-photo.html',
  styleUrl: 'profile-photo.css',
})
export class ProfilePhoto {}
```

Когда Angular компилирует компонент, эти стили эмитятся вместе с JavaScript-выводом компонента.
Это значит, что стили компонента участвуют в системе модулей JavaScript. Когда вы
рендерите Angular-компонент, фреймворк автоматически включает связанные стили, даже при
ленивой загрузке компонента.

Angular работает с любым инструментом, который выводит CSS,
включая [Sass](https://sass-lang.com), [Less](https://lesscss.org)
и [Stylus](https://stylus-lang.com).

## Scope стилей {#style-scoping}

У каждого компонента есть настройка **view encapsulation**, определяющая, как фреймворк ограничивает
стили компонента. Есть четыре режима view encapsulation: `Emulated`, `ShadowDom`, `ExperimentalIsolatedShadowDom` и `None`.
Режим можно указать в декораторе `@Component`:

```typescript
{highlight:[3]}
@Component({
  ...,
  encapsulation: ViewEncapsulation.None,
})
export class ProfilePhoto { }
```

### ViewEncapsulation.Emulated {#viewencapsulationemulated}

По умолчанию Angular использует emulated encapsulation, чтобы стили компонента применялись только к элементам,
определённым в шаблоне этого компонента. В этом режиме фреймворк генерирует уникальный HTML-атрибут
для каждого экземпляра компонента, добавляет этот атрибут к элементам в шаблоне компонента и
вставляет этот атрибут в CSS-селекторы, определённые в стилях компонента.

Этот режим гарантирует, что стили компонента не «утекут» наружу и не повлияют на другие компоненты. Однако
глобальные стили, определённые вне компонента, всё ещё могут влиять на элементы внутри компонента с
emulated encapsulation.

В emulated-режиме Angular поддерживает
псевдокласс [`:host`](https://developer.mozilla.org/docs/Web/CSS/:host).
Хотя псевдокласс [`:host-context()`](https://developer.mozilla.org/docs/Web/CSS/:host-context)
устарел в современных браузерах, компилятор Angular полностью его поддерживает. Оба псевдокласса
можно использовать без опоры на нативный
[Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM).
Во время компиляции фреймворк преобразует эти псевдоклассы в атрибуты, поэтому во время выполнения он не
следует правилам этих нативных псевдоклассов (например, совместимость браузеров, specificity). Режим
emulated encapsulation Angular не поддерживает другие псевдоклассы, связанные с Shadow DOM, такие
как `::shadow` или `::part`.

#### `::ng-deep` {#ng-deep}

Режим emulated encapsulation Angular поддерживает кастомный псевдокласс `::ng-deep`.
**Команда Angular настоятельно не рекомендует новое использование `::ng-deep`**. Эти API остаются
исключительно для обратной совместимости.

Когда селектор содержит `::ng-deep`, Angular перестаёт применять границы view-encapsulation после этой точки в селекторе. Любая часть селектора после `::ng-deep` может совпадать с элементами вне шаблона компонента.

Например:

- CSS-правило с селектором вроде `p a` при emulated encapsulation совпадёт с элементами `<a>`, которые являются потомками элемента `<p>`,
  оба — внутри собственного шаблона компонента.

- Селектор вроде `::ng-deep p a` совпадёт с элементами `<a>` где угодно в приложении, потомками элемента `<p>` где угодно в приложении.

По сути это делает его похожим на глобальный стиль.

- В `p ::ng-deep a` Angular требует, чтобы элемент `<p>` происходил из собственного шаблона компонента, но элемент `<a>` может быть где угодно в приложении.

Таким образом, элемент `<a>` может быть в шаблоне компонента или в любом его projected или child content.

- С `:host ::ng-deep p a` и `<a>`, и `<p>` должны быть потомками host-элемента компонента.

Они могут происходить из шаблона компонента или views его дочерних компонентов, но не из других мест приложения.

### ViewEncapsulation.ShadowDom {#viewencapsulationshadowdom}

Этот режим ограничивает стили внутри компонента, используя
[стандартный веб API Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM).
При включении этого режима Angular присоединяет shadow root к host-элементу компонента и рендерит
шаблон и стили компонента в соответствующее shadow tree.

Стили внутри shadow tree не могут влиять на элементы вне этого shadow tree.

Включение encapsulation `ShadowDom`, однако, влияет не только на scope стилей. Рендер
компонента в shadow tree влияет на распространение событий, взаимодействие
с [API `<slot>`](https://developer.mozilla.org/docs/Web/Web_Components/Using_templates_and_slots)
и то, как browser developer tools показывают элементы. Всегда понимайте полные последствия использования
Shadow DOM в приложении, прежде чем включать эту опцию.

### ViewEncapsulation.ExperimentalIsolatedShadowDom {#viewencapsulationexperimentalisolatedshadowdom}

Ведёт себя как выше, за исключением того, что этот режим строго гарантирует: к элементам в
шаблоне компонента применяются _только_ стили этого компонента. Глобальные стили не могут влиять на элементы в shadow tree, а стили внутри
shadow tree не могут влиять на элементы вне этого shadow tree.

### ViewEncapsulation.None {#viewencapsulationnone}

Этот режим отключает всю инкапсуляцию стилей для компонента. Любые стили, связанные с
компонентом, ведут себя как глобальные стили.

NOTE: В режимах `Emulated` и `ShadowDom` Angular не гарантирует на 100%, что стили компонента всегда переопределят стили извне.
Предполагается, что эти стили имеют ту же specificity, что и стили компонента, в случае коллизии.

## Определение стилей в шаблонах {#defining-styles-in-templates}

Можно использовать элемент `<style>` в шаблоне компонента для определения дополнительных стилей. Режим
view encapsulation компонента применяется к стилям, определённым таким образом.

Angular не поддерживает привязки внутри элементов style.

## Ссылки на внешние файлы стилей {#referencing-external-style-files}

Шаблоны компонентов могут
использовать [элемент `<link>`](https://developer.mozilla.org/docs/Web/HTML/Element/link) для
ссылок на CSS-файлы. Кроме того, ваш CSS может
использовать [at-rule `@import`](https://developer.mozilla.org/docs/Web/CSS/@import) для ссылок на
CSS-файлы. Angular считает эти ссылки _внешними_ стилями. Внешние стили не затрагиваются
emulated view encapsulation.
# Принятие данных через input-свойства

TIP: Это руководство предполагает, что вы уже прочитали [Essentials Guide](essentials). Прочитайте его сначала, если вы новичок в Angular.

TIP: Если вы знакомы с другими веб-фреймворками, input-свойства похожи на _props_.

Когда вы используете компонент, обычно нужно передать ему какие-то данные. Компонент указывает данные, которые принимает, объявляя
**inputs**:

```ts
{highlight:[6]}
import {Component, input} from '@angular/core';

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

Это позволяет привязаться к свойству в шаблоне:

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

Если у input есть значение по умолчанию, TypeScript выводит тип из значения по умолчанию:

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

Можно явно объявить тип для input, указав generic-параметр функции.

Если input без значения по умолчанию не задан, его значение — `undefined`:

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

**Angular записывает inputs статически на этапе компиляции**. Inputs нельзя добавлять или удалять во время выполнения.

Функция `input` имеет особое значение для компилятора Angular. **Вызывать `input` можно исключительно в инициализаторах свойств компонентов и директив.**

При расширении класса компонента **inputs наследуются дочерним классом.**

**Имена inputs чувствительны к регистру.**

## Чтение inputs {#reading-inputs}

Функция `input` возвращает `InputSignal`. Значение можно прочитать, вызвав сигнал:

```ts
{highlight:[9]}
import {Component, input, computed} 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()}`);
}
```

Сигналы, созданные функцией `input`, — read-only.

## Обязательные inputs {#required-inputs}

Можно объявить, что input является `required`, вызвав `input.required` вместо `input`:

```ts
{highlight:[4]}
@Component(/* ... */)
export class CustomSlider {
  // Declare a required input named value. Returns an `InputSignal<number>`.
  value = input.required<number>();
}
```

Angular обеспечивает, что обязательные inputs _должны_ быть заданы при использовании компонента в шаблоне. Если попытаться использовать компонент без указания всех обязательных inputs, Angular сообщит об ошибке на этапе сборки.

Обязательные inputs не включают автоматически `undefined` в generic-параметр возвращаемого `InputSignal`.

## Настройка inputs {#configuring-inputs}

Функция `input` принимает config-объект как второй параметр, который позволяет изменить способ работы input.

### Input transforms {#input-transforms}

Можно указать функцию `transform`, чтобы изменить значение input, когда его задаёт Angular.

```ts
{highlight:[6]}
@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" />
```

В примере выше при каждом изменении значения `systemVolume` Angular выполняет `trimString` и задаёт `label` результатом.

Самый распространённый use-case для input transforms — принимать более широкий диапазон типов значений в шаблонах, часто включая `null` и `undefined`.

**Функция input transform должна быть статически анализируема на этапе сборки.** Нельзя задавать transform-функции условно или как результат вычисления выражения.

**Функции input transform всегда должны быть [pure functions](https://en.wikipedia.org/wiki/Pure_function).** Опора на состояние вне transform-функции может привести к непредсказуемому поведению.

#### Проверка типов {#type-checking}

Когда вы указываете input transform, тип параметра transform-функции определяет типы значений, которые можно задать input в шаблоне.

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

function appendPx(value: number): string {
  return `${value}px`;
}
```

В примере выше input `widthPx` принимает `number`, а свойство `InputSignal` возвращает `string`.

#### Встроенные преобразования {#built-in-transformations}

Angular включает две встроенные transform-функции для двух самых распространённых сценариев: приведение значений к boolean и numbers.

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

@Component(/* ... */)
export class CustomSlider {
  disabled = input(false, {transform: booleanAttribute});
  value = input(0, {transform: numberAttribute});
}
```

`booleanAttribute` имитирует поведение стандартных HTML [boolean attributes](https://developer.mozilla.org/docs/Glossary/Boolean/HTML), где
_присутствие_ атрибута указывает на значение «true». Однако `booleanAttribute` Angular трактует литеральную строку `"false"` как boolean `false`.

`numberAttribute` пытается разобрать данное значение как число, производя `NaN`, если разбор не удался.

### Алиасы inputs {#input-aliases}

Можно указать опцию `alias`, чтобы изменить имя input в шаблонах.

```ts
{highlight:[3]}
@Component(/* ... */)
export class CustomSlider {
  value = input(0, {alias: 'sliderValue'});
}
```

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

Этот алиас не влияет на использование свойства в коде TypeScript.

Хотя в целом следует избегать алиасинга inputs для компонентов, эта возможность может быть полезна для переименования свойств с сохранением алиаса для исходного имени или для избежания коллизий с именами свойств нативных DOM-элементов.

## Model inputs {#model-inputs}

**Model inputs** — особый тип input, который позволяет компоненту распространять новые значения обратно родительскому компоненту.

При создании компонента можно определить model input аналогично тому, как создаётся стандартный input.

Оба типа input позволяют привязать значение к свойству. Однако **model inputs позволяют автору компонента записывать значения в свойство**. Если свойство привязано two-way binding, новое значение распространяется к этой привязке.

```ts
@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);
}
```

В примере выше `CustomSlider` может записывать значения в свой model input `value`, который затем распространяет эти значения обратно к сигналу `volume` в `MediaControls`. Эта привязка синхронизирует значения `value` и `volume`. Обратите внимание, что привязка передаёт экземпляр сигнала `volume`, а не _значение_ сигнала.

В остальных отношениях model inputs работают аналогично стандартным inputs. Значение можно прочитать, вызвав функцию сигнала, в том числе в [реактивных контекстах](guide/signals#reactive-contexts) вроде `computed` и `effect`.

См. [Two-way binding](guide/templates/two-way-binding) для дополнительных деталей о two-way binding в шаблонах.

### Two-way binding с обычными свойствами {#two-way-binding-with-plain-properties}

Можно привязать обычное свойство JavaScript к 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;
}
```

В примере выше `CustomSlider` может записывать значения в свой model input `value`, который затем распространяет эти значения обратно к свойству `volume` в `MediaControls`. Эта привязка синхронизирует значения `value` и `volume`.

### Неявные события `change` {#implicit-change-events}

Когда вы объявляете model input в компоненте или директиве, Angular автоматически создаёт соответствующий [output](guide/components/outputs) для этой модели. Имя output — имя model input с суффиксом «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);
}
```

Angular испускает это событие изменения всякий раз, когда вы записываете новое значение в model input вызовом методов `set` или `update`.

См. [Custom events with outputs](guide/components/outputs) для дополнительных деталей об outputs.

### Настройка model inputs {#customizing-model-inputs}

Можно пометить model input как required или предоставить алиас так же, как для [стандартного input](guide/components/inputs).

Model inputs не поддерживают input transforms.

### Когда использовать model inputs {#when-to-use-model-inputs}

Используйте model inputs, когда хотите, чтобы компонент поддерживал two-way binding. Это обычно уместно, когда компонент существует для изменения значения на основе взаимодействия пользователя. Чаще всего пользовательские form controls — например, date picker или combobox — должны использовать model inputs для своего основного значения.

## Выбор имён inputs {#choosing-input-names}

Избегайте выбора имён inputs, которые конфликтуют со свойствами DOM-элементов вроде HTMLElement. Коллизии имён вносят путаницу относительно того, принадлежит ли привязанное свойство компоненту или DOM-элементу.

Избегайте добавления префиксов для inputs компонентов, как вы бы делали с селекторами компонентов. Поскольку данный элемент может хостить только один компонент, любые пользовательские свойства можно считать принадлежащими компоненту.

## Объявление inputs декоратором `@Input` {#declaring-inputs-with-the-input-decorator}

TIP: Хотя команда Angular рекомендует использовать signal-based функцию `input` для новых проектов, оригинальный decorator-based API `@Input` остаётся полностью поддерживаемым.

Альтернативно можно объявить inputs компонента, добавив декоратор `@Input` к свойству:

```ts
{highlight:[3]}
@Component(/* ... */)
export class CustomSlider {
  @Input() value = 0;
}
```

Привязка к input одинакова и для signal-based, и для decorator-based inputs:

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

### Настройка decorator-based inputs {#customizing-decorator-based-inputs}

Декоратор `@Input` принимает config-объект, который позволяет изменить способ работы input.

#### Обязательные inputs {#required-inputs-1}

Можно указать опцию `required`, чтобы обеспечить, что данный input всегда должен иметь значение.

```ts
{highlight:[3]}
@Component(/* ... */)
export class CustomSlider {
  @Input({required: true}) value = 0;
}
```

Если попытаться использовать компонент без указания всех обязательных inputs, Angular сообщит об ошибке на этапе сборки.

#### Input transforms {#input-transforms-1}

Можно указать функцию `transform`, чтобы изменить значение input, когда его задаёт Angular. Эта transform-функция работает идентично transform-функциям для signal-based inputs, описанным выше.

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

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

#### Алиасы inputs {#input-aliases-1}

Можно указать опцию `alias`, чтобы изменить имя input в шаблонах.

```ts
{highlight:[3]}
@Component(/* ... */)
export class CustomSlider {
  @Input({alias: 'sliderValue'}) value = 0;
}
```

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

Декоратор `@Input` также принимает алиас как первый параметр вместо config-объекта.

Алиасы inputs работают так же, как для signal-based inputs, описанных выше.

### Inputs с getters и setters {#inputs-with-getters-and-setters}

При использовании decorator-based inputs свойство, реализованное с getter и setter, может быть input:

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

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

private internalValue = 0;
}
```

Можно даже создать _write-only_ input, определив только публичный setter:

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

private internalValue = 0;
}
```

**Предпочитайте использовать input transforms вместо getters и setters**, если возможно.

Избегайте сложных или дорогих getters и setters. Angular может вызывать setter input несколько раз, что может негативно влиять на производительность приложения, если setter выполняет какие-либо дорогие действия, например манипуляции с DOM.

## Указание inputs в декораторе `@Component` {#specify-inputs-in-the-component-decorator}

В дополнение к декоратору `@Input` можно также указать inputs компонента свойством `inputs` в декораторе `@Component`. Это может быть полезно, когда компонент наследует свойство от базового класса:

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

Дополнительно можно указать алиас input в списке `inputs`, поместив алиас после двоеточия в строке:

```ts
{highlight:[4]}
// `CustomSlider` inherits the `disabled` property from `BaseSlider`.
@Component({
  ...,
  inputs: ['disabled: sliderDisabled'],
})
export class CustomSlider extends BaseSlider { }
```
# Кастомные события с outputs

TIP: Это руководство предполагает, что вы уже прочитали [Essentials Guide](essentials). Если вы новичок в Angular, начните с него.

Компоненты Angular могут определять кастомные события, назначая свойство функции `output`:

```ts
{highlight:[5]}
@Component({
  /*...*/
})
export class ExpandablePanel {
  panelClosed = output<void>();
}
```

```html
<expandable-panel (panelClosed)="savePanelState()" />
```

Функция `output` возвращает `OutputEmitterRef`. Событие можно эмитить, вызвав метод `emit` на `OutputEmitterRef`:

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

Angular называет свойства, инициализированные функцией `output`, **outputs**. Outputs можно использовать для генерации кастомных событий, аналогично нативным событиям браузера вроде `click`.

**Кастомные события Angular не всплывают по DOM**.

**Имена outputs чувствительны к регистру.**

При расширении класса компонента **outputs наследуются дочерним классом.**

Функция `output` имеет особое значение для компилятора Angular. **Вызывать `output` можно исключительно в инициализаторах свойств компонентов и директив.**

## Эмит данных события {#emitting-event-data}

При вызове `emit` можно передать данные события:

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

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

При определении слушателя события в шаблоне к данным события можно обратиться через переменную `$event`:

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

Получите данные события в родительском компоненте:

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

```

## Кастомизация имён outputs {#customizing-output-names}

Функция `output` принимает параметр, позволяющий указать другое имя события в шаблоне:

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

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

Этот alias не влияет на использование свойства в коде TypeScript.

Хотя в целом следует избегать aliasing outputs для компонентов, эта возможность полезна для переименования свойств с сохранением alias для исходного имени или для избежания коллизий с именами нативных DOM-событий.

## Программная подписка на outputs {#subscribing-to-outputs-programmatically}

При динамическом создании компонента можно программно подписаться на события output
из экземпляра компонента. Тип `OutputRef` включает метод `subscribe`:

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

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

Angular автоматически очищает подписки на события при уничтожении компонентов с подписчиками. Альтернативно можно вручную отписаться от события. Функция `subscribe` возвращает `OutputRefSubscription` с методом `unsubscribe`:

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

// ...

eventSubscription.unsubscribe();
```

## Выбор имён событий {#choosing-event-names}

Избегайте имён outputs, которые совпадают с событиями на DOM-элементах вроде HTMLElement. Коллизии имён создают путаницу: принадлежит ли привязанное свойство компоненту или DOM-элементу.

Избегайте префиксов для outputs компонентов, как для selectors компонентов. Поскольку данный элемент может хостить только один компонент, любые кастомные свойства можно считать принадлежащими компоненту.

Всегда используйте имена outputs в [camelCase](https://en.wikipedia.org/wiki/Camel_case). Избегайте префикса «on» в именах outputs.

## Использование outputs с RxJS {#using-outputs-with-rxjs}

Подробности о взаимодействии outputs и RxJS — в [RxJS interop with component and directive outputs](ecosystem/rxjs-interop/output-interop).

## Объявление outputs декоратором `@Output` {#declaring-outputs-with-the-output-decorator}

TIP: Хотя команда Angular рекомендует функцию `output` для новых проектов,
оригинальный decorator-based API `@Output` остаётся полностью поддерживаемым.

Альтернативно кастомные события можно определить, назначив свойство новому `EventEmitter` и добавив декоратор `@Output`:

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

Событие можно эмитить, вызвав метод `emit` на `EventEmitter`.

### Aliases с декоратором `@Output` {#aliases-with-the-output-decorator}

Декоратор `@Output` принимает параметр, позволяющий указать другое имя события в шаблоне:

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

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

Этот alias не влияет на использование свойства в коде TypeScript.

## Указание outputs в декораторе `@Component` {#specify-outputs-in-the-component-decorator}

Помимо декоратора `@Output`, outputs компонента можно указать через свойство `outputs` в декораторе `@Component`. Это полезно, когда компонент наследует свойство от базового класса:

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

Дополнительно можно указать alias output в списке `outputs`, поставив alias после двоеточия в строке:

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

Часто нужно создавать компоненты, которые выступают контейнерами для разного типа контента. Например, вы можете захотеть создать пользовательский card-компонент:

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

**Можно использовать элемент `<ng-content>` как placeholder, чтобы отметить, куда должен попасть контент**:

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

TIP: `<ng-content>` работает похоже
на [нативный элемент `<slot>`](https://developer.mozilla.org/docs/Web/HTML/Element/slot),
но с некоторой Angular-специфичной функциональностью.

Когда вы используете компонент с `<ng-content>`, любые дочерние элементы host-элемента компонента
отрисовываются, или **проецируются**, в месте этого `<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>
```

Angular называет любых дочерних элементов компонента, переданных таким образом, **content** этого компонента. Это
отличается от **view** компонента, который относится к элементам, определённым в шаблоне
компонента.

**Элемент `<ng-content>` — ни компонент, ни DOM-элемент**. Вместо этого это специальный
placeholder, который сообщает Angular, где отрисовывать контент. Компилятор Angular обрабатывает
все элементы `<ng-content>` на этапе сборки. Нельзя вставлять, удалять или изменять `<ng-content>` во
время выполнения. Нельзя добавлять директивы, стили или произвольные атрибуты к `<ng-content>`.

IMPORTANT: Не следует условно включать `<ng-content>` с `@if`, `@for` или `@switch`. Angular всегда
создаёт экземпляры и DOM-узлы для контента, отрисованного в placeholder `<ng-content>`, даже если
этот placeholder `<ng-content>` скрыт. Для условной отрисовки контента компонента
см. [Template fragments](api/core/ng-template).

## Несколько placeholder контента {#multiple-content-placeholders}

Angular поддерживает проецирование нескольких разных элементов в разные placeholder `<ng-content>`
на основе CSS-селектора. Расширяя пример card выше, можно создать два placeholder для
заголовка card и тела card, используя атрибут `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" />
    <div class="card-divider"></div>
    <ng-content select="card-body" />
  </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>
```

Placeholder `<ng-content>` поддерживает те же CSS-селекторы,
что и [селекторы компонентов](guide/components/selectors).

Если включить один или несколько placeholder `<ng-content>` с атрибутом `select` и
один placeholder `<ng-content>` без атрибута `select`, последний захватывает все элементы, которые
не совпали с атрибутом `select`:

```html

<div class="card-shadow">
  <ng-content select="card-title" />
  <div class="card-divider"></div>
  
  <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>
```

Если компонент не включает placeholder `<ng-content>` без атрибута `select`, любые
элементы, которые не совпадают ни с одним из placeholder компонента, не отрисовываются в DOM.

## Fallback-контент {#fallback-content}

Angular может показывать _fallback-контент_ для placeholder `<ng-content>` компонента, если у этого компонента нет подходящего дочернего контента. Fallback-контент можно указать, добавив дочерний контент в сам элемент `<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>
```

## Алиасинг контента для проекции {#aliasing-content-for-projection}

Angular поддерживает специальный атрибут `ngProjectAs`, который позволяет указать CSS-селектор на
любом элементе. Когда элемент с `ngProjectAs` проверяется против placeholder `<ng-content>`,
Angular сравнивает со значением `ngProjectAs` вместо идентичности элемента:

```html

<div class="card-shadow">
  <ng-content select="card-title" />
  <div class="card-divider"></div>
  <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` поддерживает только статические значения и не может быть привязан к динамическим выражениям.

## Ограничения {#caveats}

### Проецируемый контент живёт во view родителя {#projected-content-lives-in-the-parents-view}

Хотя проецируемый контент _отрисовывается_ внутри принимающего компонента, он по-прежнему принадлежит компоненту, который его объявил. Angular отслеживает его как часть view родителя, что имеет несколько побочных эффектов, о которых стоит знать.

**Change detection:** Проецируемый контент проверяется, когда _родитель_ запускает change detection. Если принимающий компонент использует `OnPush`, Angular может пропустить проверку собственного шаблона этого компонента — но не пропустит проецируемый контент, потому что он принадлежит родителю.

```html

<onpush-wrapper>
  
  <expensive-component />
</onpush-wrapper>
```

**Dependency injection:** Проецируемый контент получает зависимости из injector родителя, а не из `viewProviders` принимающего компонента. См. [Providers and viewProviders](guide/di/hierarchical-dependency-injection) для деталей.

### Некоторые библиотечные компоненты не поддерживают проецируемых детей {#some-library-components-dont-support-projected-children}

Определённые компоненты — menus, tabs, lists — используют `ContentChildren`, чтобы находить своих детей и настраивать поведение вроде клавиатурной навигации, управления фокусом или ARIA-атрибутов. Они написаны в предположении, что владеют детьми напрямую, поэтому проецирование внешнего контента в них обычно ломает вещи неочевидным образом.

Например, обёртка элементов `<mat-menu-item>` в дополнительный слой и проецирование их в `<mat-menu>` может незаметно сломать клавиатурную навигацию и поддержку screen reader. Query всё ещё находит элементы, но внутренняя настройка, делающая их интерактивными, может работать некорректно, когда элементы приходят из другого view-контекста.

Если библиотечный компонент управляет поведением своих детей, проверьте его документацию, прежде чем использовать content projection — это может быть не поддерживается.
# Жизненный цикл компонента

**Жизненный цикл** компонента — последовательность шагов между созданием компонента
и его уничтожением. Каждый шаг представляет разную часть процесса Angular по отрисовке
компонентов и проверке их на обновления со временем.

В компонентах можно реализовать **lifecycle hooks** для выполнения кода во время этих шагов.
Lifecycle hooks, относящиеся к конкретному экземпляру компонента, реализуются как методы на
классе компонента. Lifecycle hooks, относящиеся к приложению Angular в целом, реализуются
как функции, принимающие callback.

Жизненный цикл компонента тесно связан с тем, как Angular проверяет компоненты на изменения со
временем. Для понимания этого жизненного цикла достаточно знать, что Angular обходит
дерево приложения сверху вниз, проверяя template bindings на изменения. Lifecycle
hooks, описанные ниже, выполняются, пока Angular делает этот обход. Этот обход посещает каждый
компонент ровно один раз, поэтому всегда следует избегать дальнейших изменений состояния в середине
процесса.

## Сводка {#summary}

<div class="docs-table docs-scroll-track-transparent">
  <table>
    <tr>
      <td><strong>Фаза</strong></td>
      <td><strong>Метод</strong></td>
      <td><strong>Сводка</strong></td>
    </tr>
    <tr>
      <td>Creation</td>
      <td><code>constructor</code></td>
      <td>
        <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Classes/constructor" target="_blank">
          Стандартный конструктор класса JavaScript
        </a>. Выполняется, когда Angular создаёт экземпляр компонента.
      </td>
    </tr>
    <tr>
      <td rowspan="7">Change<p>Detection</td>
      <td><code>ngOnInit</code>
      </td>
      <td>Выполняется один раз после того, как Angular инициализировал все inputs компонента.</td>
    </tr>
    <tr>
      <td><code>ngOnChanges</code></td>
      <td>Выполняется каждый раз, когда inputs компонента изменились.</td>
    </tr>
    <tr>
      <td><code>ngDoCheck</code></td>
      <td>Выполняется каждый раз, когда этот компонент проверяется на изменения.</td>
    </tr>
    <tr>
      <td><code>ngAfterContentInit</code></td>
      <td>Выполняется один раз после инициализации <em>content</em> компонента.</td>
    </tr>
    <tr>
      <td><code>ngAfterContentChecked</code></td>
      <td>Выполняется каждый раз, когда content этого компонента проверен на изменения.</td>
    </tr>
    <tr>
      <td><code>ngAfterViewInit</code></td>
      <td>Выполняется один раз после инициализации <em>view</em> компонента.</td>
    </tr>
    <tr>
      <td><code>ngAfterViewChecked</code></td>
      <td>Выполняется каждый раз, когда view компонента проверен на изменения.</td>
    </tr>
    <tr>
      <td rowspan="2">Rendering</td>
      <td><code>afterNextRender</code></td>
      <td>Выполняется один раз в следующий раз, когда <strong>все</strong> компоненты отрисованы в DOM.</td>
    </tr>
    <tr>
      <td><code>afterEveryRender</code></td>
      <td>Выполняется каждый раз, когда <strong>все</strong> компоненты отрисованы в DOM.</td>
    </tr>
    <tr>
      <td>Destruction</td>
      <td><code>ngOnDestroy</code></td>
      <td>Выполняется один раз перед уничтожением компонента.</td>
    </tr>
  </table>
</div>

### ngOnInit {#ngoninit}

Метод `ngOnInit` выполняется после того, как Angular инициализировал все inputs компонента их
начальными значениями. `ngOnInit` компонента выполняется ровно один раз.

Этот шаг происходит _до_ инициализации собственного шаблона компонента. Это значит, что можно
обновить состояние компонента на основе его начальных значений inputs.

### ngOnChanges {#ngonchanges}

Метод `ngOnChanges` выполняется после изменения любых inputs компонента.

Этот шаг происходит _до_ проверки собственного шаблона компонента. Это значит, что можно обновить
состояние компонента на основе его начальных значений inputs.

Во время инициализации первый `ngOnChanges` выполняется до `ngOnInit`.

#### Просмотр изменений {#inspecting-changes}

Метод `ngOnChanges` принимает один аргумент `SimpleChanges`. Этот объект —
[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type),
сопоставляющий каждое имя input компонента с объектом `SimpleChange`. Каждый `SimpleChange` содержит
предыдущее значение input, его текущее значение и флаг, является ли это первым изменением input.

Можно опционально передать текущий класс или this как первый generic-аргумент для более строгой проверки типов.

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

ngOnChanges(changes: SimpleChanges<UserProfile>) {
    if (changes.name) {
      console.log(`Previous: ${changes.name.previousValue}`);
      console.log(`Current: ${changes.name.currentValue}`);
      console.log(`Is first ${changes.name.firstChange}`);
    }
  }
}
```

Если предоставить `alias` для любых input-свойств, `SimpleChanges` Record всё равно использует
имя свойства TypeScript как ключ, а не алиас.

### ngOnDestroy {#ngondestroy}

Метод `ngOnDestroy` выполняется один раз непосредственно перед уничтожением компонента. Angular уничтожает
компонент, когда он больше не показывается на странице — например, скрыт `@if` или при навигации
на другую страницу.

#### DestroyRef {#destroyref}

Как альтернативу методу `ngOnDestroy` можно внедрить экземпляр `DestroyRef`. Можно
зарегистрировать callback для вызова при уничтожении компонента, вызвав метод `onDestroy`
у `DestroyRef`.

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

Можно передать экземпляр `DestroyRef` функциям или классам вне компонента. Используйте этот
паттерн, если есть другой код, который должен выполнить cleanup-поведение при уничтожении
компонента.

Также можно использовать `DestroyRef`, чтобы держать setup-код рядом с cleanup-кодом, вместо того чтобы помещать
весь cleanup-код в метод `ngOnDestroy`.

##### Обнаружение уничтожения экземпляра {#detecting-instance-destruction}

`DestroyRef` предоставляет свойство `destroyed`, позволяющее проверить, был ли данный экземпляр уже уничтожен. Это полезно для избежания операций на уничтоженных компонентах, особенно при работе с отложенной или асинхронной логикой.

Проверяя `destroyRef.destroyed`, можно предотвратить выполнение кода после очистки экземпляра, избегая потенциальных ошибок вроде `NG0911: View has already been destroyed.`.

### ngDoCheck {#ngdocheck}

Метод `ngDoCheck` выполняется перед каждым разом, когда Angular проверяет шаблон компонента на изменения.

Можно использовать этот lifecycle hook для ручной проверки изменений состояния вне обычного
change detection Angular, вручную обновляя состояние компонента.

Этот метод выполняется очень часто и может существенно влиять на производительность страницы. Избегайте
определения этого hook, когда возможно, используя его только когда нет альтернативы.

Во время инициализации первый `ngDoCheck` выполняется после `ngOnInit`.

### ngAfterContentInit {#ngaftercontentinit}

Метод `ngAfterContentInit` выполняется один раз после инициализации всех детей, вложенных внутрь компонента (его
_content_).

Можно использовать этот lifecycle hook для чтения результатов
[content queries](guide/components/queries#content-queries). Хотя можно получить доступ к инициализированному
состоянию этих queries, попытка изменить любое состояние в этом методе приводит к
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)

### ngAfterContentChecked {#ngaftercontentchecked}

Метод `ngAfterContentChecked` выполняется каждый раз, когда дети, вложенные внутрь компонента (его
_content_), проверены на изменения.

Хотя здесь можно получить доступ к обновлённому состоянию
[content queries](guide/components/queries#content-queries), попытка
изменить любое состояние в этом методе приводит к
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).

### ngAfterViewInit {#ngafterviewinit}

Метод `ngAfterViewInit` выполняется один раз после инициализации всех детей в шаблоне компонента (его
_view_).

Можно использовать этот lifecycle hook для чтения результатов
[view queries](guide/components/queries#view-queries). Хотя можно получить доступ к инициализированному состоянию
этих queries, попытка изменить любое состояние в этом методе приводит к
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)

### ngAfterViewChecked {#ngafterviewchecked}

Метод `ngAfterViewChecked` выполняется каждый раз, когда дети в шаблоне компонента (его
_view_) проверены на изменения.

Хотя здесь можно получить доступ к обновлённому состоянию [view queries](guide/components/queries#view-queries),
попытка
изменить любое состояние в этом методе приводит к
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).

### afterEveryRender и afterNextRender {#aftereveryrender-and-afternextrender}

Функции `afterEveryRender` и `afterNextRender` позволяют зарегистрировать **render callback** для
вызова после того, как Angular закончил отрисовку _всех компонентов_ на странице в DOM.

Эти функции отличаются от других lifecycle hooks, описанных в этом руководстве. Вместо метода
класса это standalone-функции, принимающие callback. Выполнение render
callbacks не привязано к какому-либо конкретному экземпляру компонента, а является application-wide hook.

`afterEveryRender` и `afterNextRender` должны вызываться в
[injection context](guide/di/dependency-injection-context), обычно в
конструкторе компонента.

Можно использовать render callbacks для выполнения ручных DOM-операций.
См. [Using DOM APIs](guide/components/dom-apis) для указаний по работе с DOM в Angular.

Render callbacks не выполняются во время server-side rendering или во время build-time pre-rendering.

#### Фазы after\*Render {#afterrender-phases}

При использовании `afterEveryRender` или `afterNextRender` можно опционально разделить работу на фазы. Фаза
даёт контроль над последовательностью DOM-операций, позволяя упорядочить операции _write_
перед операциями _read_, чтобы минимизировать
[layout thrashing](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing). Чтобы
общаться между фазами, функция фазы может вернуть значение результата, доступное в
следующей фазе.

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

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

constructor() {
    const 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;
        }
      },
    });
  }
}
```

Есть четыре фазы, выполняемые в следующем порядке:

| Фаза             | Описание                                                                                                                                                                                              |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `earlyRead`      | Используйте эту фазу для чтения любых layout-affecting DOM-свойств и стилей, строго необходимых для последующих вычислений. Избегайте этой фазы, если возможно, предпочитая фазы `write` и `read`. |
| `write`          | Используйте эту фазу для записи layout-affecting DOM-свойств и стилей.                                                                                                                                |
| `mixedReadWrite` | Фаза по умолчанию. Используйте для любых операций, которым нужно и читать, и писать layout-affecting свойства и стили. Избегайте этой фазы, если возможно, предпочитая явные фазы `write` и `read`. |
| `read`           | Используйте эту фазу для чтения любых layout-affecting DOM-свойств.                                                                                                                                   |

## Интерфейсы жизненного цикла {#lifecycle-interfaces}

Angular предоставляет TypeScript-интерфейс для каждого метода жизненного цикла. Можно опционально импортировать
и `implement` эти интерфейсы, чтобы гарантировать, что реализация не содержит опечаток или
ошибок написания.

Каждый интерфейс имеет то же имя, что и соответствующий метод без префикса `ng`. Например,
интерфейс для `ngOnInit` — `OnInit`.

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

## Порядок выполнения {#execution-order}

Следующие диаграммы показывают порядок выполнения lifecycle hooks Angular.

### Во время инициализации {#during-initialization}

```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
```

### Последующие обновления {#subsequent-updates}

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

### Упорядочивание с директивами {#ordering-with-directives}

Когда вы помещаете одну или несколько директив на тот же элемент, что и компонент — либо в шаблоне, либо через
свойство `hostDirectives` — фреймворк не гарантирует какой-либо порядок данного lifecycle
hook между компонентом и директивами на одном элементе. Никогда не полагайтесь на наблюдаемый
порядок, так как это может измениться в более поздних версиях Angular.
Шаблоны компонентов — это не просто статический HTML: они могут использовать данные из класса компонента и настраивать обработчики взаимодействия с пользователем.

## Отображение динамического текста {#showing-dynamic-text}

В Angular _привязка_ создаёт динамическую связь между шаблоном компонента и его данными. Эта связь гарантирует, что изменения данных компонента автоматически обновляют отображаемый шаблон.

Вы можете создать привязку для отображения динамического текста в шаблоне с помощью двойных фигурных скобок:

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

Когда Angular отрисовывает компонент, вы видите:

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

Angular автоматически поддерживает привязку в актуальном состоянии при изменении значения сигнала. Развивая
пример выше, если мы обновим значение сигнала `userName`:

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

Отображаемая страница обновится с новым значением:

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

## Установка динамических свойств и атрибутов {#setting-dynamic-properties-and-attributes}

Angular поддерживает привязку динамических значений к свойствам DOM с помощью квадратных скобок:

```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);
}
```

Вы также можете привязываться к HTML _атрибутам_, добавляя префикс `attr.` к имени атрибута:

```html

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

Angular автоматически обновляет свойства и атрибуты DOM при изменении привязанного значения.

## Обработка взаимодействия с пользователем {#handling-user-interaction}

Angular позволяет добавлять обработчики событий к элементу в шаблоне с помощью круглых скобок:

```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. */
  }
}
```

Если нужно передать [объект события](https://developer.mozilla.org/docs/Web/API/Event) в обработчик, можно использовать встроенную переменную Angular `$event` внутри вызова функции:

```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. */
  }
}
```

## Управление потоком с `@if` и `@for` {#control-flow-with-if-and-for}

Вы можете условно скрывать и показывать части шаблона с помощью блока `@if` в Angular:

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

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

Блок `@if` также поддерживает необязательный блок `@else`:

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

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

Вы можете повторять часть шаблона несколько раз с помощью блока `@for` в 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>
```

Angular использует ключевое слово `track`, показанное в примере выше, для связывания данных с элементами DOM, созданными `@for`. Подробнее см. [_Why is track in @for blocks important?_](guide/templates/control-flow#why-is-track-in-for-blocks-important).

TIP: Хотите узнать больше о шаблонах Angular? См. [Подробное руководство по шаблонам](guide/templates) для полной информации.

## Следующий шаг {#next-step}

Теперь, когда в приложении есть динамические данные и шаблоны, пора узнать, как улучшать шаблоны — условно скрывая или показывая элементы, перебирая их и многое другое.
# Добавление слушателей событий

Angular поддерживает определение слушателей событий на элементе в шаблоне: укажите имя события в круглых скобках вместе со statement, который выполняется каждый раз при возникновении события.

## Прослушивание нативных событий {#listening-to-native-events}

Когда нужно добавить слушатели событий к HTML-элементу, оберните событие в круглые скобки `()` — это позволяет указать listener statement.

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

В этом примере Angular вызывает `updateField` каждый раз, когда элемент `<input>` эмитит событие `keyup`.

Можно добавлять слушатели для любых нативных событий, например: `click`, `keydown`, `mouseover` и т.д. Подробнее — [все доступные события на элементах на MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element#events).

## Доступ к аргументу события {#accessing-the-event-argument}

В каждом слушателе события шаблона Angular предоставляет переменную `$event`, содержащую ссылку на объект события.

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

## Использование key modifiers {#using-key-modifiers}

Когда нужно перехватить конкретные клавиатурные события для конкретной клавиши, можно написать код вроде следующего:

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

Однако, поскольку это распространённый сценарий, Angular позволяет фильтровать события, указав конкретную клавишу через символ точки (`.`). Тогда код упрощается до:

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

Также можно добавить дополнительные key modifiers:

```html

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

Angular поддерживает модификаторы `alt`, `control`, `meta` и `shift`.

Можно указать key или code, к которым нужно привязать клавиатурные события. Поля key и code — нативная часть объекта keyboard event браузера. По умолчанию event binding предполагает использование [Key values for keyboard events](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values).

Angular также позволяет указать [Code values for keyboard events](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_code_values), предоставив встроенный суффикс `code`.

```html

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

Это полезно для согласованной обработки клавиатурных событий на разных операционных системах. Например, при использовании клавиши Alt на устройствах macOS свойство `key` сообщает клавишу на основе символа, уже изменённого Alt. Это значит, что комбинация вроде Alt + S сообщает значение `key` `'ß'`. Свойство `code`, однако, соответствует нажатой физической или виртуальной кнопке, а не произведённому символу.

## Прослушивание на глобальных targets {#listening-on-global-targets}

Глобальные имена target можно использовать как префикс события. Поддерживаются 3 глобальных target: `window`, `document` и `body`.

```typescript
@Component({
  /* ... */
  host: {
    'window:click': 'onWindowClick()',
    'document:click': 'onDocumentClick()',
    'body:click': 'onBodyClick()',
  },
})
export class MyView {}
```

## Предотвращение поведения события по умолчанию {#preventing-event-default-behavior}

Если обработчик события должен заменить нативное поведение браузера, можно использовать метод объекта события [`preventDefault`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault):

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

Если statement обработчика события вычисляется в `false`, Angular автоматически вызывает `preventDefault()`, подобно [нативным атрибутам обработчиков событий](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes). _Всегда предпочитайте явный вызов `preventDefault`_ — так намерение кода очевидно.

## Расширение обработки событий {#extend-event-handling}

Система событий Angular расширяема через кастомные event plugins, зарегистрированные с injection token `EVENT_MANAGER_PLUGINS`.

### Реализация Event Plugin {#implementing-event-plugin}

Чтобы создать кастомный event plugin, расширьте класс `EventManagerPlugin` и реализуйте необходимые методы.

```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);
    };
  }
}
```

Зарегистрируйте кастомный plugin через токен `EVENT_MANAGER_PLUGINS` в провайдерах приложения:

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

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

После регистрации можно использовать кастомный синтаксис событий в шаблонах, а также со свойством `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!');
  }
}
```
# Привязка динамического текста, свойств и атрибутов

В Angular **binding** создаёт динамическую связь между шаблоном компонента и его данными. Эта связь гарантирует, что изменения данных компонента автоматически обновляют отрисованный шаблон.

## Отрисовка динамического текста через text interpolation {#render-dynamic-text-with-text-interpolation}

Динамический текст в шаблонах можно привязывать двойными фигурными скобками — это сообщает Angular, что он отвечает за выражение внутри и обеспечивает его корректное обновление. Это называется **text interpolation**.

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

В этом примере при отрисовке фрагмента на странице Angular заменит `{{ theme }}` на `dark`.

```html

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

Bindings, которые меняются со временем, должны читать значения из [сигналов](/guide/signals). Angular отслеживает сигналы, прочитанные в шаблоне, и обновляет отрисованную страницу при изменении этих значений.

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

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

Подробнее см. [руководство по Signals](/guide/signals).

Продолжая пример с темой: если пользователь нажмёт кнопку, обновляющую сигнал `theme` на `'light'` после загрузки страницы, страница обновится соответственно:

```html

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

Text interpolation можно использовать везде, где обычно пишут текст в HTML.

Все значения выражений преобразуются в строку. Объекты и массивы преобразуются методом `toString` значения.

## Привязка динамических свойств и атрибутов {#binding-dynamic-properties-and-attributes}

Angular поддерживает привязку динамических значений к свойствам объектов и HTML-атрибутам через квадратные скобки.

Можно привязываться к свойствам DOM-экземпляра HTML-элемента, экземпляра [компонента](/guide/components) или экземпляра [директивы](/guide/directives).

### Свойства нативных элементов {#native-element-properties}

У каждого HTML-элемента есть соответствующее DOM-представление. Например, каждый HTML-элемент `<button>` соответствует экземпляру `HTMLButtonElement` в DOM. В Angular property bindings используются для прямой установки значений в DOM-представление элемента.

```html

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

В этом примере при каждом изменении `isFormValid` Angular автоматически устанавливает свойство `disabled` экземпляра `HTMLButtonElement`.

### Свойства компонентов и директив {#component-and-directive-properties}

Когда элемент — компонент Angular, property bindings можно использовать для установки input-свойств компонента тем же синтаксисом квадратных скобок.

```html

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

В этом примере при каждом изменении `mySelection` Angular автоматически устанавливает свойство `value` экземпляра `MyListbox`.

Можно привязываться и к свойствам директив.

```html

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

### Атрибуты {#attributes}

Когда нужно задать HTML-атрибуты без соответствующих DOM-свойств — например, SVG-атрибуты — можно привязывать атрибуты к элементам в шаблоне с префиксом `attr.`.

```html

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

В этом примере при каждом изменении `listRole` Angular автоматически устанавливает атрибут `role` элемента `<ul>`, вызывая `setAttribute`.

Если значение attribute binding равно `null`, Angular удаляет атрибут вызовом `removeAttribute`.

### Text interpolation в свойствах и атрибутах {#text-interpolation-in-properties-and-attributes}

Синтаксис text interpolation также можно использовать в свойствах и атрибутах — двойные фигурные скобки вместо квадратных вокруг имени свойства или атрибута. При таком синтаксисе Angular трактует присваивание как property binding.

```html

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

## Привязки CSS class и style {#css-class-and-style-property-bindings}

Angular поддерживает дополнительные возможности для привязки CSS-классов и CSS style properties к элементам.

### CSS-классы {#css-classes}

Можно создать CSS class binding, чтобы условно добавлять или удалять CSS-класс на элементе в зависимости от того, является ли привязанное значение [truthy или falsy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy).

```html

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

Также можно привязываться напрямую к свойству `class`. Angular принимает три типа значений:

| Описание значения `class`                                                                                                                                         | Тип TypeScript        |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Строка с одним или несколькими CSS-классами через пробел                                                                                                          | `string`              |
| Массив строк CSS-классов                                                                                                                                          | `string[]`            |
| Объект, где каждое имя свойства — имя CSS-класса, а соответствующее значение определяет, применяется ли класс к элементу, на основе 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,
  });
}
```

Пример выше отрисовывает следующий DOM:

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

Angular игнорирует любые строковые значения, которые не являются валидными именами CSS-классов.

При использовании статических CSS-классов, прямой привязки `class` и привязки конкретных классов Angular интеллектуально объединяет все классы в результате отрисовки.

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

В примере выше Angular отрисовывает элемент `ul` со всеми тремя CSS-классами.

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

Angular не гарантирует какой-либо конкретный порядок CSS-классов на отрисованных элементах.

При привязке `class` к массиву или объекту Angular сравнивает предыдущее значение с текущим оператором строгого равенства (`===`). Нужно создавать новый экземпляр объекта или массива при изменении этих значений, чтобы Angular применил обновления.

Если у элемента несколько bindings для одного и того же CSS-класса, Angular разрешает коллизии по порядку приоритета стилей.

NOTE: Class bindings не поддерживают имена классов через пробел в одном ключе. Также не поддерживаются мутации объектов, поскольку ссылка binding остаётся той же. Если нужно одно или другое, используйте директиву [ngClass](/api/common/NgClass).

### CSS style properties {#css-style-properties}

Также можно привязываться к CSS style properties напрямую на элементе.

```html

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

Можно дополнительно указать единицы для CSS-свойств, которые принимают единицы.

```html

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

Также можно задать несколько значений стиля в одном binding. Angular принимает следующие типы значений:

| Описание значения `style`                                                                                                 | Тип TypeScript        |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| Строка с нулём или более CSS-объявлений, например `"display: flex; margin: 8px"`.                                         | `string`              |
| Объект, где каждое имя свойства — имя CSS-свойства, а соответствующее значение — значение этого 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',
  });
}
```

Пример выше отрисовывает следующий DOM.

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

При привязке `style` к объекту Angular сравнивает предыдущее значение с текущим оператором строгого равенства (`===`). Нужно создавать новый экземпляр объекта при изменении этих значений, чтобы Angular применил обновления.

Если у элемента несколько bindings для одного и того же style property, Angular разрешает коллизии по порядку приоритета стилей.

## ARIA-атрибуты {#aria-attributes}

Angular поддерживает привязку строковых значений к ARIA-атрибутам.

```html
<button type="button" [aria-label]="actionLabel()">
  {{ actionLabel() }}
</button>
```

Angular записывает строковое значение в атрибут `aria-label` элемента и удаляет его, когда привязанное значение равно `null`.

Некоторые возможности ARIA предоставляют DOM-свойства или input директив, принимающие структурированные значения (например, ссылки на элементы). Для таких случаев используйте стандартные property bindings. См. [руководство по accessibility](/best-practices/a11y#aria-attributes-and-properties) для примеров и дополнительных указаний.
# Control flow

Шаблоны Angular поддерживают блоки control flow, которые позволяют условно показывать, скрывать и повторять элементы.

## Условный показ контента с `@if`, `@else if` и `@else` {#conditionally-display-content-with-if-else-if-and-else}

Блок `@if` условно показывает своё содержимое, когда выражение условия truthy:

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

Если нужно показать альтернативный контент, можно предоставить любое число блоков `@else if` и один блок `@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 }}
}
```

### Ссылка на результат условного выражения {#referencing-the-conditional-expressions-result}

Условный `@if` поддерживает сохранение результата условного выражения в переменную для переиспользования внутри блока.

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

Это полезно для ссылок на более длинные выражения, которые проще читать и поддерживать внутри шаблона.

## Повтор контента блоком `@for` {#repeat-content-with-the-for-block}

Блок `@for` проходит по коллекции и многократно рендерит содержимое блока. Коллекция может быть любым JavaScript [iterable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols), но Angular имеет дополнительные оптимизации производительности для значений `Array`.

Типичный цикл `@for` выглядит так:

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

Блок `@for` Angular не поддерживает statements, изменяющие поток, вроде JavaScript `continue` или `break`.

### Почему `track` в блоках `@for` важен? {#why-is-track-in-for-blocks-important}

Выражение `track` позволяет Angular поддерживать связь между вашими данными и DOM-узлами на странице. Это позволяет Angular оптимизировать производительность, выполняя минимум необходимых DOM-операций при изменении данных.

Эффективное использование track может значительно улучшить производительность рендеринга приложения при обходе коллекций данных.

В выражении `track` выберите свойство, которое уникально идентифицирует каждый элемент. Если модель данных включает уникально идентифицирующее свойство — обычно `id` или `uuid` — используйте это значение. Если в данных нет такого поля, настоятельно рассмотрите его добавление.

Для статических коллекций, которые никогда не меняются, можно использовать `$index`, чтобы Angular отслеживал каждый элемент по его индексу в коллекции.

Если других вариантов нет, можно использовать сам элемент как tracking key. Это говорит Angular отслеживать элемент по reference identity через оператор тройного равенства (`===`). Избегайте этого варианта по возможности: он может привести к значительно более медленным обновлениям рендера, так как Angular не сможет сопоставить, какой элемент данных соответствует каким DOM-узлам.

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

NOTE: В отличие от `*ngFor`, блок `@for` приоритизирует переиспользование view. Если отслеживаемое свойство изменилось, но ссылка на объект осталась той же, Angular обновляет привязки view (включая inputs компонента), а не уничтожает и заново создаёт весь элемент.

### Контекстные переменные в блоках `@for` {#contextual-variables-in-for-blocks}

Внутри блоков `@for` всегда доступны несколько неявных переменных:

| Переменная | Значение                                          |
| ---------- | ------------------------------------------------- |
| `$count`   | Число элементов в обходимой коллекции             |
| `$index`   | Индекс текущей строки                             |
| `$first`   | Является ли текущая строка первой                 |
| `$last`    | Является ли текущая строка последней              |
| `$even`    | Является ли индекс текущей строки чётным          |
| `$odd`     | Является ли индекс текущей строки нечётным        |

Эти переменные всегда доступны с этими именами, но их можно алиасить через сегмент `let`:

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

Aliasing полезен при вложенных блоках `@for`, позволяя читать переменные внешнего блока `@for` из внутреннего блока `@for`.

### Fallback для блоков `@for` через блок `@empty` {#providing-a-fallback-for-for-blocks-with-the-empty-block}

Опционально можно включить секцию `@empty` сразу после содержимого блока `@for`. Содержимое блока `@empty` показывается, когда элементов нет:

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

## Условный показ контента блоком `@switch` {#conditionally-display-content-with-the-switch-block}

Хотя блок `@if` подходит для большинства сценариев, блок `@switch` предоставляет альтернативный синтаксис для условного рендера данных. Его синтаксис близко напоминает statement `switch` в JavaScript.

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

Значение условного выражения сравнивается с выражением case через оператор тройного равенства (`===`).

**У `@switch` нет fallthrough**, поэтому эквивалент statement `break` или `return` в блоке не нужен.

Можно указать несколько условий для одного блока, используя подряд идущие statements `@case`.

Опционально можно включить блок `@default`. Содержимое блока `@default` показывается, если ни одно из предшествующих выражений case не совпало со значением switch.

Если ни один `@case` не совпал с выражением и блока `@default` нет, ничего не показывается.

### Исчерпывающая проверка типов {#exhaustive-type-checking}

`@switch` поддерживает исчерпывающую проверку типов, позволяя Angular во время компиляции проверить, что все возможные значения union type обработаны.

Используя `@default never;`, вы явно объявляете, что оставшихся case быть не должно. Если union type позже расширят и новый case не покрыт `@case`, template type checker Angular сообщит об ошибке, помогая рано поймать пропущенные ветки.

```html
@Component({
  template: `
    @switch (state) {
      @case ('loggedOut') {
        <button>Login</button>
      }

@case ('loggedIn') {
        <p>Welcome back!</p>
      }

@default never; // throws because `@case ('loading')` is missing
    }
  `,
})
export class AppComponent {
  state: 'loggedOut' | 'loading' | 'loggedIn' = 'loggedOut';
}
```

Когда переключаемое выражение вложено в union, нужно явно указать выражение для проверки исчерпываемости.

```typescript
@Component({
  template: `
    @switch (state.mode) {
      @case ('show') {
        {{ state.menu }};
      }
      @case ('hide') {}
      @default never(state);
    }
  `,
})
export class App {
  state!: {mode: 'hide'} | {mode: 'show'; menu: number};
}
```
# Переменные в шаблонах

В шаблонах Angular есть два типа объявлений переменных: локальные переменные шаблона и template reference variables.

HELPFUL: В этом руководстве «шаблон» не означает весь HTML-файл шаблона. Имеется в виду только конкретная конструкция шаблона или выражение внутри файла.

## Локальные переменные шаблона с `@let` {#local-template-variables-with-let}

Синтаксис `@let` Angular позволяет определить локальную переменную и переиспользовать её в шаблоне — подобно [синтаксису JavaScript `let`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let).

### Использование `@let` {#using-let}

Используйте `@let`, чтобы объявить переменную, значение которой основано на результате выражения шаблона. Angular автоматически поддерживает значение переменной в актуальном состоянии с заданным выражением — подобно [привязкам](/guide/templates/binding).

```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...';
```

Каждый блок `@let` может объявить ровно одну переменную. Нельзя объявить несколько переменных в одном блоке через запятую.

### Ссылка на значение `@let` {#referencing-the-value-of-let}

После объявления переменной через `@let` её можно переиспользовать в том же шаблоне:

```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>
}
```

### Assignability {#assignability}

Ключевое отличие `@let` от JavaScript `let` — `@let` нельзя переназначить после объявления. Однако Angular автоматически поддерживает значение переменной в актуальном состоянии с заданным выражением.

```html
@let value = 1;

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

### Область видимости переменной {#variable-scope}

Объявления `@let` ограничены текущим view и его потомками. Angular создаёт новый view на границах компонентов и везде, где шаблон может содержать динамический контент — блоки control flow, блоки `@defer` или structural directives.

Поскольку объявления `@let` не поднимаются (не hoisted), к ним **нельзя** обратиться из родительских views или 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 }}
```

### Полный синтаксис {#full-syntax}

Синтаксис `@let` формально определён так:

- Ключевое слово `@let`.
- За ним один или более пробельных символов, не включая новые строки.
- За ним валидное JavaScript-имя и ноль или более пробельных символов.
- За ним символ = и ноль или более пробельных символов.
- За ним выражение Angular, которое может быть многострочным.
- Завершается символом `;`.

## Template reference variables {#template-reference-variables}

Template reference variables дают способ объявить переменную, ссылающуюся на значение из элемента в шаблоне.

Template reference variable может ссылаться на:

- DOM-элемент внутри шаблона (включая [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements))
- Angular-компонент или директиву
- [TemplateRef](/api/core/TemplateRef) из [ng-template](/api/core/ng-template)

Template reference variables можно использовать, чтобы читать информацию из одной части шаблона в другой части того же шаблона.

### Объявление template reference variable {#declaring-a-template-reference-variable}

Переменную на элементе в шаблоне можно объявить, добавив атрибут, начинающийся с символа решётки (`#`), за которым следует имя переменной.

```html

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

### Назначение значений template reference variables {#assigning-values-to-template-reference-variables}

Angular назначает значение переменным шаблона на основе элемента, на котором переменная объявлена.

Если переменная объявлена на Angular-компоненте, переменная ссылается на экземпляр компонента.

```html

<my-datepicker #startDate />
```

Если переменная объявлена на элементе `<ng-template>`, переменная ссылается на экземпляр TemplateRef, представляющий шаблон. Подробнее — в [How Angular uses the asterisk, \*, syntax](/guide/directives/structural-directives#structural-directive-shorthand) в [Structural directives](/guide/directives/structural-directives).

```html

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

Если переменная объявлена на любом другом отображаемом элементе, переменная ссылается на экземпляр `HTMLElement`.

```html

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

#### Назначение ссылки на Angular-директиву {#assigning-a-reference-to-an-angular-directive}

У директив Angular может быть свойство `exportAs`, определяющее имя, по которому на директиву можно ссылаться в шаблоне:

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

Когда вы объявляете переменную шаблона на элементе, можно назначить этой переменной экземпляр директивы, указав это имя `exportAs`:

```html

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

Нельзя ссылаться на директиву, которая не указывает имя `exportAs`.

### Использование template reference variables с queries {#using-template-reference-variables-with-queries}

Помимо использования переменных шаблона для чтения значений из другой части того же шаблона, этот стиль объявления переменных можно использовать, чтобы «пометить» элемент для [queries компонентов и директив](/guide/components/queries).

Когда нужно сделать query конкретного элемента в шаблоне, можно объявить переменную шаблона на этом элементе, а затем запросить элемент по имени переменной.

```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;
}
```

Подробнее о queries — в [Referencing children with queries](/guide/components/queries).

### Область видимости переменных шаблона {#template-variable-scope}

Как и переменные в коде JavaScript или TypeScript, переменные шаблона ограничены шаблоном, который их объявляет.

Аналогично, [Structural directives](guide/directives/structural-directives) или объявления `<ng-template>` создают новую вложенную область шаблона — подобно тому, как statements control flow JavaScript вроде `if` и `for` создают новые лексические области. К переменным шаблона внутри одной из этих structural directives нельзя обратиться извне её границ.

HELPFUL: Определяйте переменную только один раз в шаблоне, чтобы runtime-значение оставалось предсказуемым.

#### Доступ во вложенном шаблоне {#accessing-in-a-nested-template}

Внутренний шаблон может обращаться к переменным шаблона, которые определяет внешний шаблон.

В следующем примере изменение текста в `<input>` меняет значение в `<span>`, потому что Angular сразу обновляет изменения через переменную шаблона `ref1`.

```html
<input #ref1 type="text" [(ngModel)]="firstExample" />

<span *ngIf="true">Value: {{ ref1.value }}</span>
```

В этом случае `*ngIf` на `<span>` создаёт новую область шаблона, которая включает переменную `ref1` из родительской области.

Однако доступ к переменной шаблона из дочерней области в родительском шаблоне не работает:

```html
{avoid}
<input *ngIf="true" #ref2 type="text" [(ngModel)]="secondExample" />

<span>Value: {{ ref2?.value }}</span>
```

Здесь `ref2` объявлена в дочерней области, созданной `*ngIf`, и недоступна из родительского шаблона.
# Отложенная загрузка с `@defer`

Deferrable views, также известные как блоки `@defer`, уменьшают начальный размер бандла приложения, откладывая загрузку кода, который не строго необходим для начальной отрисовки страницы. Это часто приводит к более быстрой начальной загрузке и улучшению Core Web Vitals (CWV), в первую очередь Largest Contentful Paint (LCP) и Time to First Byte (TTFB).

Чтобы использовать эту возможность, можно декларативно обернуть секцию шаблона в блок @defer:

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

Код любых компонентов, директив и pipes внутри блока `@defer` разделяется в отдельный JavaScript-файл и загружается только когда необходимо — после отрисовки остальной части шаблона.

Deferrable views поддерживают различные triggers, опции prefetching и sub-блоки для управления состояниями placeholder, loading и error.

## Какие зависимости откладываются? {#which-dependencies-are-deferred}

Компоненты, директивы, pipes и любые CSS-стили компонентов могут быть отложены при загрузке приложения.

Чтобы зависимости внутри блока `@defer` были отложены, они должны соответствовать двум условиям:

1. **Они должны быть standalone.** Non-standalone зависимости не могут быть отложены и всё ещё загружаются eagerly, даже если они внутри блоков `@defer`.
1. **На них нельзя ссылаться вне блоков `@defer` в том же файле.** Если на них ссылаются вне блока `@defer` или внутри ViewChild queries, зависимости будут загружены eagerly.

_Транзитивные_ зависимости компонентов, директив и pipes, используемых в блоке `@defer`, не обязаны строго быть standalone; транзитивные зависимости всё ещё могут быть объявлены в `NgModule` и участвовать в отложенной загрузке.

Компилятор Angular производит оператор [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) для каждого компонента, директивы и pipe, используемых в блоке `@defer`. Основной контент блока отрисовывается после разрешения всех imports. Angular не гарантирует какой-либо конкретный порядок этих imports.

## Как управлять разными стадиями отложенной загрузки {#how-to-manage-different-stages-of-deferred-loading}

Блоки `@defer` имеют несколько sub-блоков, позволяющих корректно обрабатывать разные стадии процесса отложенной загрузки.

### `@defer` {#defer}

Это основной блок, определяющий секцию контента, которая загружается лениво. Изначально он не отрисовывается — отложенный контент загружается и отрисовывается, когда происходит указанный [trigger](#controlling-deferred-content-loading-with-triggers) или выполняется условие `when`.

По умолчанию блок `@defer` запускается, когда состояние браузера становится [idle](/guide/templates/defer#idle).

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

### Показ placeholder-контента с `@placeholder` {#show-placeholder-content-with-placeholder}

По умолчанию defer-блоки не отрисовывают никакой контент до запуска.

`@placeholder` — опциональный блок, объявляющий, какой контент показывать до запуска блока `@defer`.

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

Хотя он опционален, определённые triggers могут требовать присутствия либо `@placeholder`, либо [template reference variable](/guide/templates/variables#template-reference-variables) для работы. См. раздел [Triggers](#controlling-deferred-content-loading-with-triggers) для дополнительных деталей.

Angular заменяет placeholder-контент основным контентом после завершения загрузки. В секции placeholder можно использовать любой контент, включая обычный HTML, компоненты, директивы и pipes. Имейте в виду, что _зависимости блока placeholder загружаются eagerly_.

Блок `@placeholder` принимает опциональный параметр для указания `minimum` количества времени, в течение которого этот placeholder должен показываться после начальной отрисовки placeholder-контента.

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

Этот параметр `minimum` указывается в приращениях времени миллисекунд (ms) или секунд (s). Можно использовать этот параметр, чтобы предотвратить быстрое мерцание placeholder-контента в случае, когда отложенные зависимости загружаются быстро.

### Показ loading-контента с `@loading` {#show-loading-content-with-loading}

Блок `@loading` — опциональный блок, позволяющий объявить контент, который показывается, пока загружаются отложенные зависимости. Он заменяет блок `@placeholder`, как только загрузка запущена.

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

Его зависимости загружаются eagerly (аналогично `@placeholder`).

Блок `@loading` принимает два опциональных параметра, чтобы помочь предотвратить быстрое мерцание контента, которое может произойти, когда отложенные зависимости загружаются быстро:

- `minimum` — минимальное количество времени, в течение которого этот placeholder должен показываться
- `after` — количество времени ожидания после начала загрузки перед показом loading-шаблона

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

Оба параметра указываются в приращениях времени миллисекунд (ms) или секунд (s). Кроме того, таймеры для обоих параметров начинаются сразу после запуска загрузки.

### Показ состояния ошибки при сбое отложенной загрузки с `@error` {#show-error-state-when-deferred-loading-fails-with-error}

Блок `@error` — опциональный блок, который отображается, если отложенная загрузка не удалась. Аналогично `@placeholder` и `@loading`, зависимости блока @error загружаются eagerly.

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

## Управление загрузкой отложенного контента с triggers {#controlling-deferred-content-loading-with-triggers}

Можно указать **triggers**, которые контролируют, когда Angular загружает и отображает отложенный контент.

Когда блок `@defer` запускается, он заменяет placeholder-контент лениво загруженным контентом.

Несколько event triggers можно определить, разделяя их точкой с запятой `;`, и они будут оцениваться как условия OR.

Есть два типа triggers: `on` и `when`.

### `on` {#on}

`on` указывает условие, когда запускается блок `@defer`.

Доступные triggers следующие:

| Trigger                       | Описание                                                               |
| ----------------------------- | ---------------------------------------------------------------------- |
| [`idle`](#idle)               | Запускается, когда браузер idle. Поддерживает опциональный timeout.    |
| [`viewport`](#viewport)       | Запускается, когда указанный контент входит в viewport                 |
| [`interaction`](#interaction) | Запускается, когда пользователь взаимодействует с указанным элементом  |
| [`hover`](#hover)             | Запускается, когда мышь наводится на указанную область                 |
| [`immediate`](#immediate)     | Запускается сразу после завершения отрисовки non-deferred контента     |
| [`timer`](#timer)             | Запускается после конкретной длительности                              |

#### `idle` {#idle}

Trigger `idle` загружает отложенный контент, как только браузер достиг idle-состояния, на основе requestIdleCallback. Это поведение по умолчанию для defer-блока.

Можно опционально указать timeout в миллисекундах, который передаётся в [`requestIdleCallback`](https://developer.mozilla.org/docs/Web/API/Window/requestIdleCallback). Если браузер не запланирует callback достаточно скоро, работа выполнится не позже указанного timeout.

```html

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

@defer (on idle(500)) {
  <large-cmp />
}
```

##### Настройка поведения `idle` {#customizing-idle-behavior}

Можно настроить trigger `idle`, предоставив собственную реализацию `IdleService` и зарегистрировав её с `provideIdleServiceWith` в providers приложения.

```ts
@Service()
class CustomIdleService implements IdleService {
  requestOnIdle(callback: (deadline?: IdleDeadline) => void, options?: IdleRequestOptions) {
    // Custom idle scheduling logic can be implemented here.
  }

cancelOnIdle(id: number) {
    // Implement custom idle cancellation here.
  }
}

bootstrapApplication(App, {
  providers: [provideIdleServiceWith(CustomIdleService)],
});
```

#### `viewport` {#viewport}

Trigger `viewport` загружает отложенный контент, когда указанный контент входит в viewport, используя [Intersection Observer API](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API). Наблюдаемый контент может быть контентом `@placeholder` или явной ссылкой на элемент.

По умолчанию `@defer` следит за входом placeholder в viewport. Placeholders, используемые таким образом, должны иметь один корневой элемент.

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

Альтернативно можно указать [template reference variable](/guide/templates/variables) в том же шаблоне, что и блок `@defer`, как элемент, за входом которого в viewport следят. Эта переменная передаётся как параметр trigger viewport.

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

Если хотите настроить опции `IntersectionObserver`, trigger `viewport` поддерживает передачу object literal. Literal поддерживает все свойства из второго параметра `IntersectionObserver`, кроме `root`. При использовании нотации object literal нужно передать trigger через свойство `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` {#interaction}

Trigger `interaction` загружает отложенный контент, когда пользователь взаимодействует с указанным элементом через события `click` или `keydown`.

По умолчанию placeholder выступает как элемент взаимодействия. Placeholders, используемые таким образом, должны иметь один корневой элемент.

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

Альтернативно можно указать [template reference variable](/guide/templates/variables) в том же шаблоне, что и блок `@defer`, как элемент, за взаимодействиями с которым следят. Эта переменная передаётся как параметр trigger interaction.

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

#### `hover` {#hover}

Trigger `hover` загружает отложенный контент, когда мышь наведена на triggered-область через события `mouseover` и `focusin`.

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

Альтернативно можно указать [template reference variable](/guide/templates/variables) в том же шаблоне, что и блок `@defer`, как элемент, над которым наводится мышь. Эта переменная передаётся как параметр trigger hover.

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

#### `immediate` {#immediate}

Trigger `immediate` загружает отложенный контент немедленно. Это значит, что отложенный блок загружается, как только весь остальной non-deferred контент закончил отрисовку.

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

#### `timer` {#timer}

Trigger `timer` загружает отложенный контент после указанной длительности.

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

Параметр длительности должен быть указан в миллисекундах (`ms`) или секундах (`s`).

### `when` {#when}

Trigger `when` принимает пользовательское условное выражение и загружает отложенный контент, когда условие становится truthy.

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

Это одноразовая операция — блок `@defer` не возвращается к placeholder, если условие меняется на falsy-значение после того, как стало truthy.

## Prefetching данных с `prefetch` {#prefetching-data-with-prefetch}

В дополнение к указанию условия, определяющего, когда показывается отложенный контент, можно опционально указать **prefetch trigger**. Этот trigger позволяет загрузить JavaScript, ассоциированный с блоком `@defer`, до показа отложенного контента.

Prefetching включает более продвинутые поведения — например, позволяет начать prefetch ресурсов до того, как пользователь реально увидел или взаимодействовал с defer-блоком, но может взаимодействовать с ним скоро, делая ресурсы доступными быстрее.

Можно указать prefetch trigger аналогично основному trigger блока, но с префиксом ключевого слова `prefetch`. Основной trigger блока и prefetch trigger разделяются символом точки с запятой (`;`).

В примере ниже prefetching начинается, когда браузер становится idle, а содержимое блока отрисовывается только когда пользователь взаимодействует с placeholder.

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

@defer (on interaction; prefetch on idle(500)) {
  <large-cmp />
}
```

## Тестирование блоков `@defer` {#testing-defer-blocks}

Angular предоставляет TestBed API для упрощения процесса тестирования блоков `@defer` и запуска разных состояний во время тестирования. По умолчанию блоки `@defer` в тестах проигрываются так, как defer-блок вёл бы себя в реальном приложении. Если хотите вручную проходить по состояниям, можно переключить поведение defer-блока на `Manual` в конфигурации 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 ExampleA {}
  // Create component fixture.
  const componentFixture = TestBed.createComponent(ExampleA);
  // 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` с `NgModule`? {#does-defer-work-with-ngmodule}

Блоки `@defer` совместимы и со standalone, и с NgModule-based компонентами, директивами и pipes. Однако **только standalone компоненты, директивы и pipes могут быть отложены**. NgModule-based зависимости не откладываются и включаются в eagerly loaded бандл.

## Совместимость между блоками `@defer` и Hot Module Reload (HMR) {#compatibility-between-defer-blocks-and-hot-module-reload-hmr}

Когда активен Hot Module Replacement (HMR), все chunks блоков `@defer` загружаются eagerly, переопределяя любые настроенные triggers. Чтобы восстановить стандартное поведение triggers, нужно отключить HMR, обслуживая приложение с флагом `--no-hmr`.

## Как `@defer` работает с server-side rendering (SSR) и static-site generation (SSG)? {#how-does-defer-work-with-server-side-rendering-ssr-and-static-site-generation-ssg}

По умолчанию при отрисовке приложения на сервере (либо с SSR, либо с SSG) defer-блоки всегда отрисовывают свой `@placeholder` (или ничего, если placeholder не указан), и triggers не вызываются. На клиенте контент `@placeholder` гидратируется, и triggers активируются.

Чтобы отрисовать основной контент блоков `@defer` на сервере (и SSR, и SSG), можно включить [возможность Incremental Hydration](/guide/incremental-hydration) и настроить triggers `hydrate` для необходимых блоков.

## Barrel-файлы и lazy chunks {#barrel-files-and-lazy-chunks}

Если используете `@defer`, но не видите отдельный lazy chunk в выводе сборки, проверьте, как импортируете отложенный компонент. Импорт через barrel-файл (`index.ts`) — распространённая причина: бандлеры видят barrel как один модуль и держат все его exports вместе, поэтому ваш компонент оказывается в основном бандле независимо от `@defer`.

```typescript
// index.ts
export {HeavyComponent} from './heavy.component';
export {OtherComponent} from './other.component';
```

```typescript
// parent.component.ts
import {HeavyComponent} from './index'; // pulls in OtherComponent too

@Component({
  imports: [HeavyComponent],
  template: `@defer {
    <heavy-component />
  }`,
})
export class ParentComponent {}
```

Исправление прямолинейно — импортируйте напрямую из собственного файла компонента:

```typescript
import {HeavyComponent} from './heavy.component';
```

Этого достаточно, чтобы бандлер выделил его в собственный chunk и загрузил лениво, когда сработает trigger.

## Лучшие практики для отложенных views {#best-practices-for-deferring-views}

### Избегайте каскадных загрузок с вложенными блоками `@defer` {#avoid-cascading-loads-with-nested-defer-blocks}

Когда у вас вложенные блоки `@defer`, у них должны быть разные triggers, чтобы избежать одновременной загрузки, которая вызывает каскадные запросы и может негативно влиять на производительность загрузки страницы.

### Избегайте layout shifts {#avoid-layout-shifts}

Избегайте откладывания компонентов, видимых в viewport пользователя при начальной загрузке. Это может негативно влиять на Core Web Vitals, вызывая увеличение cumulative layout shift (CLS).

Если это необходимо, избегайте triggers `immediate`, `timer`, `viewport` и пользовательских `when`, которые заставляют контент загружаться во время начальной отрисовки страницы.

### Учитывайте accessibility {#keep-accessibility-in-mind}

При использовании блоков `@defer` учитывайте влияние на пользователей со вспомогательными технологиями вроде screen readers.
Screen readers, фокусирующиеся на отложенной секции, изначально прочитают placeholder или loading-контент, но могут не объявить изменения, когда загружается отложенный контент.

Чтобы гарантировать, что изменения отложенного контента объявляются screen readers, можно обернуть блок `@defer` в элемент с live region:

```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>
```

Это гарантирует, что изменения объявляются пользователю, когда происходят переходы (placeholder → loading → content/error).
# Синтаксис выражений

Выражения Angular основаны на JavaScript, но отличаются в ряде ключевых моментов. Это руководство проходит по сходствам и различиям между выражениями Angular и стандартным JavaScript.

## Литералы значений {#value-literals}

Angular поддерживает подмножество [литеральных значений](https://developer.mozilla.org/en-US/docs/Glossary/Literal) из JavaScript.

### Поддерживаемые литералы значений {#supported-value-literals}

| Тип литерала           | Примеры значений                |
| ---------------------- | ------------------------------- |
| String                 | `'Hello'`, `"World"`            |
| Boolean                | `true`, `false`                 |
| Number                 | `123`, `3.14`                   |
| Object                 | `{name: 'Alice'}`               |
| Array                  | `['Onion', 'Cheese', 'Garlic']` |
| null                   | `null`                          |
| RegExp                 | `/\d+/`                         |
| Template string        | `` `Hello ${name}` ``           |
| Tagged template string | `` tag`Hello ${name}` ``        |

### Неподдерживаемые литералы значений {#unsupported-value-literals}

| Тип литерала | Примеры значений |
| ------------ | ---------------- |
| BigInt       | `1n`             |

## Globals {#globals}

Выражения Angular поддерживают следующие [globals](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)

Другие JavaScript globals не поддерживаются. К распространённым JavaScript globals относятся `Number`, `Boolean`, `NaN`, `Infinity`, `parseInt` и другие.

## Локальные переменные {#local-variables}

Angular автоматически делает специальные локальные переменные доступными для использования в выражениях в определённых контекстах. Эти специальные переменные всегда начинаются с символа доллара (`$`).

Например, блоки `@for` предоставляют несколько локальных переменных с информацией о цикле, например `$index`.

## Какие операторы поддерживаются? {#what-operators-are-supported}

### Поддерживаемые операторы {#supported-operators}

Angular поддерживает следующие операторы из стандартного JavaScript.

| Оператор                      | Пример(ы)                                      |
| ----------------------------- | ---------------------------------------------- |
| Add / Concatenate             | `1 + 2`                                        |
| Subtract                      | `52 - 3`                                       |
| Multiply                      | `41 * 6`                                       |
| Divide                        | `20 / 4`                                       |
| Remainder (Modulo)            | `17 % 5`                                       |
| Exponentiation                | `10 ** 3`                                      |
| Parenthesis                   | `9 * (8 + 4)`                                  |
| Conditional (Ternary)         | `a > b ? true : false`                         |
| And (Logical)                 | `&&`                                           |
| Or (Logical)                  | `\|\|`                                         |
| Not (Logical)                 | `!`                                            |
| Nullish Coalescing            | `possiblyNullValue ?? 'default'`               |
| Comparison Operators          | `<`, `<=`, `>`, `>=`, `==`, `===`, `!==`, `!=` |
| Unary Negation                | `-x`                                           |
| Unary Plus                    | `+y`                                           |
| Property Accessor             | `person['name']`                               |
| typeof                        | `typeof 42`                                    |
| void                          | `void 1`                                       |
| in                            | `'model' in car`                               |
| instanceof                    | `car instanceof Automobile`                    |
| Assignment                    | `a = b`                                        |
| Addition Assignment           | `a += b`                                       |
| Subtraction Assignment        | `a -= b`                                       |
| Multiplication Assignment     | `a *= b`                                       |
| Division Assignment           | `a /= b`                                       |
| Remainder Assignment          | `a %= b`                                       |
| Exponentiation Assignment     | `a **= b`                                      |
| Logical AND Assignment        | `a &&= b`                                      |
| Logical OR Assignment         | `a \|\|= b`                                    |
| Nullish Coalescing Assignment | `a ??= b`                                      |
| Spread in object literals     | `{...obj, foo: 'bar'}`                         |
| Spread in array literals      | `[...arr, 1, 2, 3]`                            |
| Rest in function calls        | `fn(...args)`                                  |

Выражения Angular дополнительно поддерживают следующие нестандартные операторы:

| Оператор                        | Пример(ы)                      |
| ------------------------------- | ------------------------------ |
| [Pipe](/guide/templates/pipes)  | `{{ total \| currency }}`      |
| Optional chaining\*             | `someObj.someProp?.nestedProp` |
| Non-null assertion (TypeScript) | `someObj!.someProp`            |

### Миграция safe navigation {#safe-navigation-migration}

До Angular 22 оператор optional chaining (`?.`) возвращал `null`, когда левая сторона равна `null` или `undefined`, тогда как стандартный JavaScript `?.` возвращает `undefined`.
Начиная с Angular 22, поведение оператора optional chaining в выражениях Angular выровнено со стандартным поведением JavaScript.

Во время миграции на v22 schematics `ng update` добавили magic-функцию `$safeNavigationMigration` к существующим выражениям, чтобы сохранить прежнее поведение с возвратом `null`.

```html
{{ $safeNavigationMigration(foo?.bar) }}
```

`$safeNavigationMigration` — **только временная помощь при миграции**. Она указывает компилятору компилировать обёрнутое выражение safe-navigation с legacy-семантикой возврата `null`, а не со стандартной семантикой JavaScript `?.`. Это не настоящая функция и её нельзя вызвать из TypeScript.

NOTE: Предпочитайте мигрировать выражения так, чтобы они больше не опирались на различия `null` и `undefined`, и `$safeNavigationMigration` можно было удалить. Эта функция может быть удалена в будущей версии Angular.

### Неподдерживаемые операторы {#unsupported-operators}

| Оператор              | Пример(ы)                         |
| --------------------- | --------------------------------- |
| All bitwise operators | `&`, `&=`, `~`, `\|=`, `^=`, etc. |
| Object destructuring  | `const { name } = person`         |
| Array destructuring   | `const [firstItem] = items`       |
| Comma operator        | `x = (x++, x)`                    |
| new                   | `new Car()`                       |

## Лексический контекст для выражений {#lexical-context-for-expressions}

Выражения Angular вычисляются в контексте класса компонента, а также любых релевантных [переменных шаблона](/guide/templates/variables), locals и globals.

При обращении к членам класса компонента `this` всегда подразумевается. Однако если шаблон объявляет [переменную шаблона](guide/templates/variables) с тем же именем, что и член, переменная затеняет этот член. К такому члену класса можно однозначно обратиться, явно используя `this.`. Это полезно при создании объявления `@let`, которое затеняет член класса, например для сужения сигналов.

## Объявления {#declarations}

В целом объявления в выражениях Angular не поддерживаются. Это включает, но не ограничивается:

| Объявления      | Пример(ы)                                   |
| --------------- | ------------------------------------------- |
| Variables       | `let label = 'abc'`, `const item = 'apple'` |
| Functions       | `function myCustomFunction() { }`           |
| Arrow Functions | `() => { }`                                 |
| Classes         | `class Rectangle { }`                       |

## Statements слушателей событий {#event-listener-statements}

Обработчики событий — это **statements**, а не выражения. Хотя они поддерживают весь тот же синтаксис, что и выражения Angular, есть два ключевых различия:

1. Statements **поддерживают** операторы присваивания (но не destructuring assignments)
1. Statements **не поддерживают** pipes
# Attribute-директивы

Изменяйте внешний вид или поведение DOM-элементов и компонентов Angular с помощью attribute-директив.

## Создание attribute-директивы {#building-an-attribute-directive}

В этом разделе вы создадите директиву подсветки, которая задаёт жёлтый цвет фона host-элемента.

1. Чтобы создать директиву, используйте команду CLI [`ng generate directive`](tools/cli/schematics).

```shell
ng generate directive highlight
   ```

CLI создаёт `src/app/highlight.directive.ts` и соответствующий тестовый файл `src/app/highlight.directive.spec.ts`.

```typescript
import {Directive} from '@angular/core';

@Directive({
     selector: '[appHighlight]',
   })
   export class HighlightDirective {}
   ```

Свойство конфигурации декоратора `@Directive()` задаёт CSS attribute-селектор директивы `[appHighlight]`.

1. Импортируйте `ElementRef` и `inject` из `@angular/core`.
   `ElementRef` даёт прямой доступ к host DOM-элементу через свойство `nativeElement`.

1. Используйте [`inject`](guide/di), чтобы получить ссылку на host DOM-элемент — элемент, к которому применяется `appHighlight`.

1. Добавьте в класс `HighlightDirective` логику, задающую жёлтый фон.

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

IMPORTANT: Директивы _не_ поддерживают пространства имён.

```html
{avoid}
<p app:Highlight>This is invalid</p>
```

## Применение attribute-директивы {#applying-an-attribute-directive}

Чтобы использовать `HighlightDirective`, добавьте в HTML-шаблон элемент `<p>` с директивой в качестве атрибута.

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

Angular создаёт экземпляр класса `HighlightDirective`, который через `inject(ElementRef)` получает ссылку на элемент `<p>` и задаёт ему жёлтый стиль фона.

## Обработка событий пользователя {#handling-user-events}

В этом разделе показано, как отслеживать наведение и уход указателя с элемента и реагировать установкой или сбросом цвета подсветки.

1. Настройте привязки событий host через свойство `host` в декораторе `@Directive()`.

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

1. Добавьте два метода-обработчика событий и сопоставьте им события host-элемента через свойство `host`.

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

Подписывайтесь на события DOM-элемента, который является host attribute-директивы (в данном случае `<p>`), настраивая слушатели событий в свойстве [`host`](guide/components/host-elements#binding-to-the-host-element) директивы.

HELPFUL: Обработчики делегируют вспомогательному методу `highlight()`, который задаёт цвет на host DOM-элементе `el`.

Полная директива выглядит так:

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

Цвет фона появляется, когда указатель наводится на элемент абзаца, и исчезает, когда указатель уходит.

## Передача значений в attribute-директиву {#passing-values-into-an-attribute-directive}

В этом разделе вы зададите цвет подсветки при применении `HighlightDirective`.

1. В `highlight.directive.ts` импортируйте `input` из `@angular/core`.

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

1. Добавьте свойство `input` с именем `appHighlight`.

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

Функция `input()` добавляет в класс метаданные, делающие свойство `appHighlight` директивы доступным для привязки.

1. В `app.component.ts` добавьте свойство `color` в `AppComponent`.

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

1. Чтобы одновременно применить директиву и цвет, используйте привязку свойства с селектором директивы `appHighlight`, приравняв его к `color`.

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

Привязка атрибута `[appHighlight]` выполняет две задачи:
   - Применяет директиву подсветки к элементу `<p>`
   - Задаёт цвет подсветки директивы через привязку свойства

### Задание значения через ввод пользователя {#setting-the-value-with-user-input}

В этом разделе вы добавите radio-кнопки для привязки выбора цвета к директиве `appHighlight`.

1. Добавьте разметку в `app.component.html` для выбора цвета:

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

2. Измените `AppComponent.color` так, чтобы у него не было начального значения.

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

3. В `highlight.directive.ts` измените метод `onMouseEnter` так, чтобы он сначала пытался подсветить с `appHighlight` и откатывался к `red`, если `appHighlight` равен `undefined`.
   <docs-code header="highlight.directive.ts (mouse-enter)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" region="mouse-enter"/>

4. Запустите приложение и убедитесь, что пользователь может выбирать цвет radio-кнопками.

## Привязка ко второму свойству {#binding-to-a-second-property}

В этом разделе вы настроите приложение так, чтобы разработчик мог задать цвет по умолчанию.

1. Добавьте второе свойство `input()` в `HighlightDirective` с именем `defaultColor`.

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

2. Измените `onMouseEnter` директивы так, чтобы он сначала пытался подсветить с `appHighlight`, затем с `defaultColor`, и откатывался к `red`, если оба свойства `undefined`.

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

3. Чтобы привязаться к `AppComponent.color` и откатываться к «violet» как цвету по умолчанию, добавьте следующий HTML.
   В этом случае привязка `defaultColor` не использует квадратные скобки `[]`, потому что значение — статическая строка, а не динамическое выражение.

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

Как и у компонентов, к host-элементу можно добавить несколько привязок свойств директивы.

Цвет по умолчанию — красный, если нет привязки цвета по умолчанию.
Когда пользователь выбирает цвет, выбранный цвет становится активным цветом подсветки.

## Отключение обработки Angular с `NgNonBindable` {#deactivating-angular-processing-with-ngnonbindable}

Чтобы предотвратить вычисление выражений в браузере, добавьте `ngNonBindable` к host-элементу.
`ngNonBindable` отключает интерполяцию, директивы и привязки в шаблонах.

В следующем примере выражение `{{ 1 + 1 }}` отображается так же, как в редакторе кода, и не показывает `2`.

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

Применение `ngNonBindable` к элементу останавливает привязку для дочерних элементов этого элемента.
Однако `ngNonBindable` по-прежнему позволяет директивам работать на элементе, к которому применён `ngNonBindable`.
В следующем примере директива `appHighlight` всё ещё активна, но Angular не вычисляет выражение `{{ 1 + 1 }}`.

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

Если применить `ngNonBindable` к родительскому элементу, Angular отключает интерполяцию и привязки любого вида — привязку свойств или событий — для дочерних элементов.
# Структурные директивы

Структурные директивы — это директивы, применяемые к элементу `<ng-template>`, которые условно или повторно рендерят содержимое этого `<ng-template>`.

## Пример сценария использования {#example-use-case}

В этом руководстве вы создадите структурную директиву, которая загружает данные из заданного источника и рендерит свой шаблон, когда данные доступны. Директива называется `SelectDirective` по SQL-ключевому слову `SELECT` и сопоставляется с attribute-селектором `[select]`.

У `SelectDirective` будет input, именующий источник данных, — `selectFrom`. Префикс `select` для этого input важен для [сокращённого синтаксиса](#structural-directive-shorthand). Директива будет создавать экземпляр своего `<ng-template>` с контекстом шаблона, предоставляющим выбранные данные.

Пример прямого использования этой директивы на `<ng-template>`:

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

Структурная директива может дождаться доступности данных и затем отрендерить свой `<ng-template>`.

HELPFUL: Элемент Angular `<ng-template>` определяет шаблон, который по умолчанию ничего не рендерит: если просто обернуть элементы в `<ng-template>` без структурной директивы, эти элементы не будут отрендерены.

Подробнее см. документацию [ng-template API](api/core/ng-template).

## Сокращённый синтаксис структурных директив {#structural-directive-shorthand}

Angular поддерживает сокращённый синтаксис структурных директив, который избавляет от необходимости явно писать элемент `<ng-template>`.

Структурные директивы можно применять напрямую к элементу, префиксируя attribute-селектор директивы звёздочкой (`*`), например `*select`. Angular преобразует звёздочку перед структурной директивой в `<ng-template>`, который хостит директиву и окружает элемент и его потомков.

С `SelectDirective` это выглядит так:

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

Этот пример показывает гибкость сокращённого синтаксиса структурных директив, который иногда называют _microsyntax_.

При таком использовании к `<ng-template>` применяются только структурная директива и её привязки. Любые другие атрибуты или привязки на теге `<p>` остаются как есть. Например, эти две формы эквивалентны:

```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>
```

Сокращённый синтаксис раскрывается через набор соглашений. Более полная [грамматика](#structural-directive-syntax-reference) определена ниже, но в примере выше преобразование можно объяснить так:

Первая часть выражения `*select` — `let data`, которая объявляет переменную шаблона `data`. Поскольку присваивания нет, переменная шаблона привязывается к свойству контекста шаблона `$implicit`.

Вторая часть синтаксиса — пара ключ–выражение `from source`. `from` — ключ привязки, а `source` — обычное выражение шаблона. Ключи привязки отображаются на свойства преобразованием в PascalCase и добавлением префикса селектора структурной директивы. Ключ `from` отображается на `selectFrom`, который затем привязывается к выражению `source`. Поэтому у многих структурных директив inputs имеют префикс селектора структурной директивы.

## Одна структурная директива на элемент {#one-structural-directive-per-element}

При использовании сокращённого синтаксиса на элемент можно применить только одну структурную директиву. Это потому что есть только один элемент `<ng-template>`, на который разворачивается директива. Несколько директив потребовали бы нескольких вложенных `<ng-template>`, и неочевидно, какая должна быть первой. `<ng-container>` можно использовать для создания обёрточных слоёв, когда несколько структурных директив нужно применить вокруг одного физического DOM-элемента или компонента, что позволяет пользователю определить вложенную структуру.

## Создание структурной директивы {#creating-a-structural-directive}

В этом разделе вы создадите `SelectDirective`.

<docs-workflow>
<docs-step title="Generate the directive">
С помощью Angular CLI выполните следующую команду, где `select` — имя директивы:

```shell
ng generate directive select
```

Angular создаёт класс директивы и задаёт CSS-селектор `[select]`, который идентифицирует директиву в шаблоне.
</docs-step>
<docs-step title="Make the directive structural">
Импортируйте `TemplateRef`, `ViewContainerRef` и `input`. Внедрите `TemplateRef` и `ViewContainerRef` в директиве как приватные свойства.

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

export interface DataSource<T> {
  load(): Promise<T>;
}

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

</docs-step>
<docs-step title="Add the 'selectFrom' input">
Добавьте свойство `selectFrom` через `input()`.

```ts
export class SelectDirective {
  // ...
  selectFrom = input.required<DataSource<unknown>>();
}
```

</docs-step>
<docs-step title="Add the business logic">
Когда `SelectDirective` уже оформлена как структурная директива со своим input, можно добавить логику загрузки данных и рендера шаблона с ними:

```ts
export class SelectDirective {
  // ...
  async ngOnInit() {
    const data = await this.selectFrom().load();
    this.viewContainerRef.createEmbeddedView(this.templateRef, {
      // Create the embedded view with a context object that contains
      // the data via the key `$implicit`.
      $implicit: data,
    });
  }
}
```

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

Готово — `SelectDirective` работает. Следующим шагом может быть [добавление поддержки проверки типов шаблона](#typing-the-directives-context).

## Справочник синтаксиса структурных директив {#structural-directive-syntax-reference}

При написании собственных структурных директив используйте следующий синтаксис:

```ts
{hideCopy}
_: prefix = "( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )_";
```

Следующие паттерны описывают каждую часть грамматики структурных директив:

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

### Как Angular переводит сокращённый синтаксис {#how-angular-translates-shorthand}

Angular переводит сокращённый синтаксис структурных директив в обычный синтаксис привязки так:

### Примеры сокращений {#shorthand-examples}

Следующая таблица приводит примеры сокращений:

| Сокращение                                                            | Как Angular интерпретирует синтаксис                                                                              |
| :-------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| `*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">`                                                                   |

## Улучшение проверки типов шаблона для пользовательских директив {#improving-template-type-checking-for-custom-directives}

Проверку типов шаблона для пользовательских директив можно улучшить, добавив template guards в определение директивы.
Эти guards помогают проверщику типов шаблона Angular находить ошибки в шаблоне на этапе компиляции, что позволяет избежать runtime-ошибок.
Возможны два типа guards:

- `ngTemplateGuard_(input)` позволяет контролировать, как выражение input должно сужаться на основе типа конкретного input.
- `ngTemplateContextGuard` используется для определения типа объекта контекста шаблона на основе типа самой директивы.

В этом разделе приведены примеры обоих видов guards.
Подробнее см. [Проверка типов шаблона](tools/cli/template-typecheck 'Template type-checking guide').

### Сужение типов с помощью template guards {#type-narrowing-with-template-guards}

Структурная директива в шаблоне контролирует, рендерится ли этот шаблон в runtime. Некоторые структурные директивы хотят выполнять сужение типов на основе типа выражения input.

С input guards возможны два вида сужения:

- Сужение выражения input на основе функции утверждения типа TypeScript.
- Сужение выражения input на основе его truthiness.

Чтобы сузить выражение input, определив функцию утверждения типа:

```ts
// This directive only renders its template if the actor is a user.
// You want to assert that within the template, the type of the `actor`
// expression is narrowed to `User`.
@Directive(...)
class ActorIsUser {
  actor = input<User | Robot>();

static ngTemplateGuard_actor(dir: ActorIsUser, expr: User | Robot): expr is User {
    // The return statement is unnecessary in practice, but included to
    // prevent TypeScript errors.
    return true;
  }
}
```

Проверка типов внутри шаблона будет вести себя так, как будто `ngTemplateGuard_actor` был утверждён для выражения, привязанного к input.

Некоторые директивы рендерят свои шаблоны только когда input truthy. Полную семантику truthiness невозможно выразить функцией утверждения типа, поэтому вместо этого можно использовать литеральный тип `'binding'`, чтобы сигнализировать проверщику типов шаблона, что само выражение привязки следует использовать как guard:

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

static ngTemplateGuard_condition: 'binding';
}
```

Проверщик типов шаблона будет вести себя так, как будто выражение, привязанное к `condition`, было утверждено как truthy внутри шаблона.

### Типизация контекста директивы {#typing-the-directives-context}

Если структурная директива предоставляет контекст создаваемому шаблону, его можно корректно типизировать внутри шаблона, предоставив статическую функцию утверждения типа `ngTemplateContextGuard`. Эта функция может использовать тип директивы для вывода типа контекста, что полезно, когда тип директивы generic.

Для описанной выше `SelectDirective` можно реализовать `ngTemplateContextGuard`, чтобы корректно указать тип данных, даже если источник данных generic.

```ts
// Declare an interface for the template context:
export interface SelectTemplateContext<T> {
  $implicit: T;
}

@Directive(...)
export class SelectDirective<T> {
  // The directive's generic type `T` will be inferred from the `DataSource` type
  // passed to the input.
  selectFrom = input.required<DataSource<T>>();

// Narrow the type of the context using the generic type of the directive.
  static ngTemplateContextGuard<T>(dir: SelectDirective<T>, ctx: any): ctx is SelectTemplateContext<T> {
    // As before the guard body is not used at runtime, and included only to avoid
    // TypeScript errors.
    return true;
  }
}
```
# API композиции директив

Директивы Angular — удобный способ инкапсулировать переиспользуемое поведение: директивы могут применять
атрибуты, CSS-классы и слушатели событий к элементу.

_API композиции директив_ позволяет применять директивы к host-элементу компонента
_изнутри_ TypeScript-класса компонента.

## Добавление директив к компоненту {#adding-directives-to-a-component}

Директивы применяются к компоненту через свойство `hostDirectives` в декораторе
компонента. Такие директивы называют _host-директивами_.

В этом примере директива `MenuBehavior` применяется к host-элементу `AdminMenu`. Это
работает аналогично применению `MenuBehavior` к элементу `<admin-menu>` в шаблоне.

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

Когда фреймворк рендерит компонент, Angular также создаёт экземпляр каждой host-директивы.
Host-привязки директив применяются к host-элементу компонента. По умолчанию inputs и outputs
host-директив не входят в публичный API компонента. См.
[Включение inputs и outputs](#including-inputs-and-outputs) ниже.

**Angular применяет host-директивы статически на этапе компиляции.** Нельзя динамически добавлять
директивы в runtime.

**Директивы в `hostDirectives` не должны указывать `standalone: false`.**

**Angular игнорирует `selector` директив, применённых в свойстве `hostDirectives`.**

## Включение inputs и outputs {#including-inputs-and-outputs}

Когда вы применяете `hostDirectives` к компоненту, inputs и outputs host-директив
по умолчанию не включаются в API компонента. Их можно явно включить в API компонента,
расширив запись в `hostDirectives`:

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

Явно указав inputs и outputs, потребители компонента с `hostDirective` могут
привязывать их в шаблоне:

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

Кроме того, inputs и outputs из `hostDirective` можно алиасить, чтобы настроить API
компонента:

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

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

## Добавление директив к другой директиве {#adding-directives-to-another-directive}

`hostDirectives` можно добавлять и к другим директивам, не только к компонентам. Это позволяет
транзитивно агрегировать несколько поведений.

В следующем примере определены две директивы — `Menu` и `Tooltip`. Затем поведение
этих двух директив композируется в `MenuWithTooltip`. Наконец, `MenuWithTooltip`
применяется к `SpecializedMenuWithTooltip`.

Когда `SpecializedMenuWithTooltip` используется в шаблоне, создаются экземпляры всех
`Menu`, `Tooltip` и `MenuWithTooltip`. Host-привязки каждой из этих директив применяются к host-
элементу `SpecializedMenuWithTooltip`.

```ts
@Directive({
  /* ... */
})
export class Menu {}

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

// MenuWithTooltip can compose behaviors from multiple other directives
@Directive({
  hostDirectives: [Tooltip, Menu],
})
export class MenuWithTooltip {}

// CustomWidget can apply the already-composed behaviors from MenuWithTooltip
@Directive({
  hostDirectives: [MenuWithTooltip],
})
export class SpecializedMenuWithTooltip {}
```

## Семантика host-директив {#host-directive-semantics}

### Порядок выполнения директив {#directive-execution-order}

Host-директивы проходят тот же жизненный цикл, что и компоненты и директивы, используемые напрямую в
шаблоне. Однако host-директивы всегда выполняют конструктор, хуки жизненного цикла и привязки _до_ компонента или директивы, к которым они применены.

Следующий пример показывает минимальное использование host-директивы:

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

Порядок выполнения здесь:

1. Создаётся экземпляр `MenuBehavior`
2. Создаётся экземпляр `AdminMenu`
3. `MenuBehavior` получает inputs (`ngOnInit`)
4. `AdminMenu` получает inputs (`ngOnInit`)
5. `MenuBehavior` применяет host-привязки
6. `AdminMenu` применяет host-привязки

Такой порядок операций означает, что компоненты с `hostDirectives` могут переопределять любые host-привязки,
заданные host-директивой.

Этот порядок операций распространяется и на вложенные цепочки host-директив, как в следующем
примере.

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

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

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

В примере выше порядок выполнения:

1. Создаётся экземпляр `Tooltip`
2. Создаётся экземпляр `CustomTooltip`
3. Создаётся экземпляр `EvenMoreCustomTooltip`
4. `Tooltip` получает inputs (`ngOnInit`)
5. `CustomTooltip` получает inputs (`ngOnInit`)
6. `EvenMoreCustomTooltip` получает inputs (`ngOnInit`)
7. `Tooltip` применяет host-привязки
8. `CustomTooltip` применяет host-привязки
9. `EvenMoreCustomTooltip` применяет host-привязки

### Внедрение зависимостей {#dependency-injection}

Компонент или директива, указывающие `hostDirectives`, могут внедрять экземпляры этих host-
директив и наоборот.

При применении host-директив к компоненту и компонент, и host-директивы могут определять
провайдеры.

Если компонент или директива с `hostDirectives` и эти host-директивы предоставляют один и тот же
injection token, провайдеры, определённые классом с `hostDirectives`, имеют приоритет над провайдерами,
определёнными host-директивами.

### Дедупликация host-директив {#host-directive-de-duplication}

Когда одна и та же директива появляется более одного раза в разрешённом дереве host-директив, она автоматически дедуплицируется, а не вызывает ошибку. Для выбора выжившего совпадения используются два детерминированных правила.

#### Совпадение по шаблону имеет приоритет {#template-match-takes-precedence}

Если директива совпадает с элементом один раз через **селектор шаблона** и также появляется как
**host-директива**, Angular сохраняет только совпадение по шаблону и отбрасывает все совпадения host-директив.

Ментальная модель: совпадение host-директивы представляет `Partial<YourDirective>` — частичное
применение, где открыты только inputs и outputs, явно перечисленные в `hostDirectives`,
тогда как совпадение по шаблону представляет полную директиву с полным публичным API.

```ts
@Directive({selector: '[hoverable]'})
export class Hoverable {}

@Component({
  selector: 'app-button',
  hostDirectives: [Hoverable],
})
export class Button {}
```

```html


<app-button hoverable></app-button>
```

#### Несколько совпадений host-директив объединяются {#multiple-host-directive-matches-are-merged}

Если одна и та же директива появляется **более одного раза как host-директива** — например, когда две
директивы объявляют общую зависимость в своих `hostDirectives` — Angular объединяет все
экземпляры в один экземпляр директивы. Отображения inputs и outputs из всех экземпляров
комбинируются.

Это решает классическую [проблему ромба](https://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem) в композиции host-директив:

```ts
// A shared behavior that both triggers need
@Directive({
  host: {
    '[attr.data-trigger-id]': 'triggerId',
  },
})
export class TriggerRef {
  readonly triggerId = `trigger-${crypto.randomUUID()}`;
}

// Two separate triggers, each declaring TriggerRef as a host directive
@Directive({
  selector: '[popoverTrigger]',
  hostDirectives: [TriggerRef],
})
export class PopoverTrigger {
  readonly triggerRef = inject(TriggerRef);
}

@Directive({
  selector: '[dropdownTrigger]',
  hostDirectives: [TriggerRef],
})
export class DropdownTrigger {
  readonly triggerRef = inject(TriggerRef);
}
```

```html

<button popoverTrigger dropdownTrigger>Actions</button>
```

HELPFUL: Поскольку Angular создаёт только один экземпляр общей директивы, и `PopoverTrigger`,
и `DropdownTrigger` получают один и тот же экземпляр `TriggerRef` при внедрении.

#### Конфликтующие алиасы {#conflicting-aliases}

Когда Angular объединяет дублирующиеся совпадения host-директив, он также объединяет их отображения inputs и outputs.
Если два экземпляра одной host-директивы открывают **один и тот же input или output под разными
алиасами**, Angular выбрасывает ошибку на этапе компиляции ([NG8024](errors/NG8024))

```ts
@Directive({
  selector: '[popoverTrigger]',
  hostDirectives: [{directive: TriggerRef, inputs: ['triggerId: popoverTriggerId']}],
})
export class PopoverTrigger {}

@Directive({
  selector: '[dropdownTrigger]',
  hostDirectives: [
    {directive: TriggerRef, inputs: ['triggerId: dropdownTriggerId']}, // different alias!
  ],
})
export class DropdownTrigger {}
```

```html

<button popoverTrigger dropdownTrigger></button>
```

Чтобы разрешить это, убедитесь, что оба пути открывают общий input или output под одним алиасом, либо
не открывайте его вовсе.
# Начало работы с NgOptimizedImage

Директива `NgOptimizedImage` упрощает применение best practices производительности при загрузке изображений.

Директива гарантирует приоритетную загрузку изображения [Largest Contentful Paint (LCP)](http://web.dev/lcp) за счёт:

- Автоматической установки атрибута `fetchpriority` на теге `<img>`
- Ленивой загрузки остальных изображений по умолчанию
- Автоматической генерации preconnect link tag в document head
- Автоматической генерации атрибута `srcset`
- Генерации [preload hint](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload), если приложение использует SSR

Помимо оптимизации загрузки LCP-изображения, `NgOptimizedImage` обеспечивает ряд best practices для изображений, например:

- Использование [URL image CDN для применения оптимизаций](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options)
- Предотвращение layout shift за счёт требования `width` и `height`
- Предупреждение, если `width` или `height` заданы некорректно
- Предупреждение, если изображение будет визуально искажено при рендере

Если вы используете фоновое изображение в CSS, [начните здесь](#how-to-migrate-your-background-image).

**NOTE: Хотя директива `NgOptimizedImage` стала стабильной в Angular 15, она была бэкпортирована и доступна как стабильная функция также в версиях 13.4.0 и 14.3.0.**

## Начало работы {#getting-started}

<docs-workflow>
<docs-step title="Import `NgOptimizedImage` directive">
Импортируйте директиву `NgOptimizedImage` из `@angular/common`:

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

и включите её в массив `imports` standalone-компонента или NgModule:

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

</docs-step>
<docs-step title="(Optional) Set up a Loader">
Image loader **не обязателен** для использования NgOptimizedImage, но использование loader с image CDN открывает мощные возможности производительности, включая автоматические `srcset` для изображений.

Краткое руководство по настройке loader — в разделе [Configuring an Image Loader](#configuring-an-image-loader-for-ngoptimizedimage) в конце этой страницы.
</docs-step>
<docs-step title="Enable the directive">
Чтобы активировать директиву `NgOptimizedImage`, замените атрибут `src` изображения на `ngSrc`.

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

Если вы используете [встроенный сторонний loader](#built-in-loaders), не включайте base URL path в `src` — loader добавит его автоматически.
</docs-step>
<docs-step title="Mark images as `priority`">
Всегда помечайте [LCP-изображение](https://web.dev/lcp/#what-elements-are-considered) на странице как `priority`, чтобы приоритизировать его загрузку.

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

Пометка изображения как `priority` применяет следующие оптимизации:

- Устанавливает `fetchpriority=high` (подробнее о priority hints [здесь](https://web.dev/priority-hints))
- Устанавливает `loading=eager` (подробнее о native lazy loading [здесь](https://web.dev/browser-level-image-lazy-loading))
- Автоматически генерирует [preload link element](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload) при [рендере на сервере](guide/ssr).

Angular показывает предупреждение в режиме разработки, если LCP-элемент — изображение без атрибута `priority`. LCP-элемент страницы может меняться в зависимости от ряда факторов — например, размеров экрана пользователя, поэтому на странице может быть несколько изображений, которые следует пометить `priority`. Подробнее см. [CSS for Web Vitals](https://web.dev/css-web-vitals/#images-and-largest-contentful-paint-lcp).
</docs-step>
<docs-step title="Include Width and Height">
Чтобы предотвратить [image-related layout shifts](https://web.dev/css-web-vitals/#images-and-layout-shifts), NgOptimizedImage требует указать height и width для изображения:

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

Для **responsive-изображений** (изображений, стилизованных так, чтобы расти и сжиматься относительно viewport) атрибуты `width` и `height` должны быть intrinsic size файла изображения. Для responsive-изображений также важно [задать значение для `sizes`.](#responsive-images)

Для **изображений фиксированного размера** атрибуты `width` и `height` должны отражать желаемый rendered size изображения. Соотношение сторон этих атрибутов всегда должно совпадать с intrinsic aspect ratio изображения.

NOTE: Если вы не знаете размер изображений, рассмотрите «fill mode», чтобы наследовать размер родительского контейнера, как описано ниже.
</docs-step>
</docs-workflow>

## Использование режима `fill` {#using-fill-mode}

Когда нужно, чтобы изображение заполняло содержащий элемент, можно использовать атрибут `fill`. Это часто полезно для поведения «background image». Также помогает, когда точные width и height изображения неизвестны, но есть родительский контейнер известного размера, в который нужно вписать изображение (см. «object-fit» ниже).

При добавлении атрибута `fill` к изображению не нужно и не следует указывать `width` и `height`, как в этом примере:

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

Можно использовать CSS-свойство [object-fit](https://developer.mozilla.org/docs/Web/CSS/object-fit), чтобы изменить, как изображение заполняет контейнер. Если стилизовать изображение с `object-fit: "contain"`, изображение сохранит соотношение сторон и будет «letterboxed» под элемент. Если задать `object-fit: "cover"`, элемент сохранит соотношение сторон, полностью заполнит элемент, а часть контента может быть «обрезана».

Визуальные примеры выше — в [документации MDN по object-fit.](https://developer.mozilla.org/docs/Web/CSS/object-fit)

Также можно стилизовать изображение свойством [object-position](https://developer.mozilla.org/docs/Web/CSS/object-position), чтобы скорректировать его позицию внутри содержащего элемента.

IMPORTANT: Чтобы изображение «fill» корректно рендерилось, его родительский элемент **должен** быть стилизован с `position: "relative"`, `position: "fixed"` или `position: "absolute"`.

## Как мигрировать фоновое изображение {#how-to-migrate-your-background-image}

Ниже — простой пошаговый процесс миграции с `background-image` на `NgOptimizedImage`. Элемент с фоновым изображением будем называть «containing element»:

1. Удалите стиль `background-image` у containing element.
2. Убедитесь, что containing element имеет `position: "relative"`, `position: "fixed"` или `position: "absolute"`.
3. Создайте новый элемент изображения как дочерний containing element, используя `ngSrc` для включения директивы `NgOptimizedImage`.
4. Дайте этому элементу атрибут `fill`. Не указывайте `height` и `width`.
5. Если считаете, что это изображение может быть вашим [LCP-элементом](https://web.dev/lcp/), добавьте атрибут `priority` к элементу изображения.

Как фоновое изображение заполняет контейнер, можно настроить, как описано в разделе [Using fill mode](#using-fill-mode).

## Использование placeholder {#using-placeholders}

### Автоматические placeholder {#automatic-placeholders}

NgOptimizedImage может показывать автоматический low-resolution placeholder для изображения, если вы используете CDN или image host с автоматическим изменением размера. Воспользуйтесь этой возможностью, добавив атрибут `placeholder` к изображению:

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

Добавление этого атрибута автоматически запрашивает вторую, меньшую версию изображения через указанный image loader. Это маленькое изображение применяется как стиль `background-image` с CSS blur, пока загружается основное изображение. Если image loader не предоставлен, placeholder сгенерировать нельзя, и будет выброшена ошибка.

Размер сгенерированных placeholder по умолчанию — 30px в ширину. Его можно изменить, указав значение в пикселях в провайдере `IMAGE_CONFIG`:

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      placeholderResolution: 40
    }
  },
],
```

Если нужны чёткие края вокруг blurred placeholder, оберните изображение в содержащий `<div>` со стилем `overflow: hidden`. Пока `<div>` того же размера, что и изображение (например, через стиль `width: fit-content`), «размытые края» placeholder будут скрыты.

### Data URL placeholder {#data-url-placeholders}

Также можно указать placeholder через base64 [data URL](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) без image loader. Формат data url — `data:image/[imagetype];[data]`, где `[imagetype]` — формат изображения, например `png`, а `[data]` — base64-кодирование изображения. Кодирование можно сделать через командную строку или в JavaScript. Конкретные команды — в [документации MDN](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs#encoding_data_into_base64_format). Пример data URL placeholder с усечёнными данными:

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder="data:image/png;base64,iVBORw0K..." />
```

Однако большие data URL увеличивают размер Angular-бандлов и замедляют загрузку страницы. Если image loader использовать нельзя, команда Angular рекомендует держать base64 placeholder-изображения меньше 4KB и использовать их только на критических изображениях. Помимо уменьшения размеров placeholder, рассмотрите смену форматов изображений или параметров при сохранении. При очень низком разрешении эти параметры сильно влияют на размер файла.

### Placeholder без blur {#non-blurred-placeholders}

По умолчанию NgOptimizedImage применяет CSS blur к image placeholder. Чтобы отрендерить placeholder без blur, передайте аргумент `placeholderConfig` с объектом, включающим свойство `blur`, установленное в false. Например:

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder [placeholderConfig]="{blur: false}" />
```

## Настройка стилей изображения {#adjusting-image-styling}

В зависимости от стилей изображения добавление атрибутов `width` и `height` может изменить его рендер. `NgOptimizedImage` предупреждает, если стили рендерят изображение с искажённым соотношением сторон.

Обычно это исправляется добавлением `height: auto` или `width: auto` к стилям изображения. Подробнее — в [статье web.dev о теге `<img>`](https://web.dev/patterns/web-vitals-patterns/images/img-tag).

Если атрибуты `width` и `height` мешают задать размер изображения через CSS так, как нужно, рассмотрите режим `fill` и стилизацию родительского элемента изображения.

## Возможности производительности {#performance-features}

NgOptimizedImage включает ряд возможностей, улучшающих производительность загрузки в приложении. Они описаны в этом разделе.

### Добавление resource hints {#add-resource-hints}

[`preconnect` resource hint](https://web.dev/preconnect-and-dns-prefetch) для origin изображения гарантирует максимально быструю загрузку LCP-изображения.

Preconnect-ссылки автоматически генерируются для доменов, переданных как аргумент [loader](#optional-set-up-a-loader). Если origin изображения нельзя определить автоматически и для LCP-изображения не обнаружена preconnect-ссылка, `NgOptimizedImage` предупредит в режиме разработки. В этом случае следует вручную добавить resource hint в `index.html`. Внутри `<head>` документа добавьте тег `link` с `rel="preconnect"`, как показано ниже:

```html
<link rel="preconnect" href="https://my.cdn.origin" />
```

Чтобы отключить предупреждения preconnect, внедрите токен `PRECONNECT_CHECK_BLOCKLIST`:

```ts
providers: [
{provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
],

```

Подробнее об автоматической генерации preconnect — [здесь](#why-is-a-preconnect-element-not-being-generated-for-my-image-domain).

### Запрос изображений правильного размера с автоматическим `srcset` {#request-images-at-the-correct-size-with-automatic-srcset}

Определение атрибута [`srcset`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/srcset) гарантирует, что браузер запросит изображение нужного размера для viewport пользователя и не будет тратить время на скачивание слишком большого изображения. `NgOptimizedImage` генерирует подходящий `srcset` для изображения на основе наличия и значения атрибута [`sizes`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) на теге изображения.

#### Изображения фиксированного размера {#fixed-size-images}

Если изображение должно быть «фиксированного» размера (т.е. одного размера на устройствах, за исключением [pixel density](https://web.dev/codelab-density-descriptors/)), атрибут `sizes` задавать не нужно. `srcset` можно сгенерировать автоматически из атрибутов width и height изображения без дополнительного ввода.

Пример сгенерированного srcset:

```html
<img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x" />
```

#### Responsive-изображения {#responsive-images}

Если изображение должно быть responsive (т.е. расти и сжиматься в зависимости от размера viewport), нужно определить атрибут [`sizes`](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) для генерации `srcset`.

Если вы раньше не использовали `sizes`, хорошая отправная точка — задать его на основе ширины viewport. Например, если CSS заставляет изображение заполнять 100% ширины viewport, задайте `sizes` как `100vw`, и браузер выберет изображение в `srcset`, ближайшее к ширине viewport (с учётом pixel density). Если изображение, скорее всего, занимает половину экрана (например, в sidebar), задайте `sizes` как `50vw`, чтобы браузер выбрал меньшее изображение. И так далее.

Если вышеописанное не покрывает желаемое поведение изображения, см. документацию по [advanced sizes values](#advanced-sizes-values).

Обратите внимание: `NgOptimizedImage` автоматически добавляет `"auto"` в начало предоставленного значения `sizes`. Это оптимизация, повышающая точность выбора srcset в браузерах с поддержкой `sizes="auto"`, и игнорируемая браузерами без поддержки.

По умолчанию responsive breakpoints:

`[16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840]`

Если нужно кастомизировать эти breakpoints, используйте провайдер `IMAGE_CONFIG`:

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      breakpoints: [16, 48, 96, 128, 384, 640, 750, 828, 1080, 1200, 1920]
    }
  },
],
```

Если нужно вручную определить атрибут `srcset`, можно предоставить свой через атрибут `ngSrcset`:

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" />
```

Если атрибут `ngSrcset` присутствует, `NgOptimizedImage` генерирует и устанавливает `srcset` на основе включённых размеров. Не включайте имена файлов изображений в `ngSrcset` — директива выводит эту информацию из `ngSrc`. Директива поддерживает и width descriptors (например, `100w`), и density descriptors (например, `1x`).

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw" />
```

### Отключение автоматической генерации srcset {#disabling-automatic-srcset-generation}

Чтобы отключить генерацию srcset для одного изображения, добавьте атрибут `disableOptimizedSrcset`:

```html
<img ngSrc="about.jpg" disableOptimizedSrcset />
```

### Отключение ленивой загрузки изображений {#disabling-image-lazy-loading}

По умолчанию `NgOptimizedImage` устанавливает `loading=lazy` для всех изображений, не помеченных `priority`. Это поведение для non-priority изображений можно отключить, задав атрибут `loading`. Атрибут принимает значения: `eager`, `auto` и `lazy`. [Подробности — в документации стандартного атрибута `loading` изображения](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/loading#value).

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

### Управление декодированием изображений {#controlling-image-decoding}

По умолчанию `NgOptimizedImage` устанавливает `decoding="auto"` для всех изображений. Это позволяет браузеру выбрать оптимальное время декодирования изображения после его получения. Когда изображение помечено как `priority`, Angular автоматически устанавливает `decoding="sync"`, чтобы изображение декодировалось и отрисовывалось как можно раньше, помогая улучшить производительность **Largest Contentful Paint (LCP)**.

Это поведение всё равно можно переопределить, явно задав атрибут `decoding`.  
[Подробности — в документации стандартного атрибута `decoding` изображения](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" />
```

**Допустимые значения**

- `auto` (по умолчанию): браузер выбирает оптимальную стратегию.
- `async`: декодирует изображение асинхронно, по возможности избегая блокировки main‑thread.
- `sync`: декодирует изображение сразу; может блокировать рендеринг, но гарантирует готовность пикселей, как только изображение доступно.

### Продвинутые значения 'sizes' {#advanced-sizes-values}

Может понадобиться отображать изображения разной ширины на экранах разного размера. Распространённый пример — layout на основе сетки или колонок, который рендерит одну колонку на мобильных и две — на больших устройствах. Это поведение можно выразить в атрибуте `sizes` синтаксисом «media query»:

```html
<img ngSrc="cat.jpg" width="400" height="200" sizes="(max-width: 768px) 100vw, 50vw" />
```

Атрибут `sizes` в примере выше говорит: «Я ожидаю, что это изображение будет 100 процентов ширины экрана на устройствах уже 768px. Иначе — 50 процентов ширины экрана».

Дополнительно об атрибуте `sizes` — на [web.dev](https://web.dev/learn/design/responsive-images/#sizes) или [mdn](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes).

## Настройка image loader для `NgOptimizedImage` {#configuring-an-image-loader-for-ngoptimizedimage}

«Loader» — функция, генерирующая [URL трансформации изображения](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options) для данного файла изображения. Когда уместно, `NgOptimizedImage` задаёт трансформации размера, формата и качества изображения.

`NgOptimizedImage` предоставляет и generic loader без трансформаций, и loaders для различных сторонних image-сервисов. Также поддерживается написание собственного custom loader.

| Тип loader                             | Поведение                                                                                                                                                                                                                      |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Generic loader                         | URL, возвращаемый generic loader, всегда совпадает со значением `src`. Иными словами, этот loader не применяет трансформаций. Основной сценарий — сайты, которые отдают изображения через Angular.                            |
| Loaders для сторонних image-сервисов   | URL, возвращаемый loaders для сторонних image-сервисов, следует API-соглашениям конкретного сервиса.                                                                                                                           |
| Custom loaders                         | Поведение custom loader определяется его разработчиком. Используйте custom loader, если ваш image-сервис не поддерживается loaders, предустановленными с `NgOptimizedImage`.                                                   |

На основе image-сервисов, часто используемых с Angular-приложениями, `NgOptimizedImage` предоставляет loaders, предустановленные для работы со следующими сервисами:

Для использования **generic loader** дополнительные изменения кода не нужны. Это поведение по умолчанию.

### Встроенные Loaders {#built-in-loaders}

Чтобы использовать существующий loader для **стороннего image-сервиса**, добавьте provider factory выбранного сервиса в массив `providers`. В примере ниже используется Imgix loader:

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

Base URL для image assets следует передать в provider factory как аргумент. Для большинства сайтов этот base URL должен соответствовать одному из паттернов:

- <https://yoursite.yourcdn.com>
- <https://subdomain.yoursite.com>
- <https://subdomain.yourcdn.com/yoursite>

Подробнее о структуре base URL — в документации соответствующего CDN-провайдера.

### Custom Loaders {#custom-loaders}

Чтобы использовать **custom loader**, предоставьте функцию loader как значение DI-токена `IMAGE_LOADER`. В примере ниже custom loader возвращает URL, начинающийся с `https://example.com`, который включает `src`, `width` и `height` как URL-параметры.

```ts
providers: [
  {
    provide: IMAGE_LOADER,
    useValue: (config: ImageLoaderConfig) => {
      return `https://example.com/images?src=${config.src}&width=${config.width}&height=${config.height}`;
    },
  },
],
```

Функция loader для директивы `NgOptimizedImage` принимает объект типа `ImageLoaderConfig` (из `@angular/common`) как аргумент и возвращает абсолютный URL image asset. Объект `ImageLoaderConfig` содержит свойство `src` и опциональные свойства `width`, `height` и `loaderParams`.

NOTE: даже если свойство `width` не всегда присутствует, custom loader должен использовать его для поддержки запроса изображений разной ширины, чтобы `ngSrcset` работал корректно.

### Свойство `loaderParams` {#the-loaderparams-property}

Директива `NgOptimizedImage` поддерживает дополнительный атрибут `loaderParams`, специально предназначенный для поддержки custom loaders. Атрибут `loaderParams` принимает объект с любыми свойствами как значение и сам по себе ничего не делает. Данные в `loaderParams` добавляются к объекту `ImageLoaderConfig`, передаваемому custom loader, и могут использоваться для управления поведением loader.

Распространённое применение `loaderParams` — управление продвинутыми возможностями image CDN.

### Использование свойства `transform` со встроенными loaders {#using-the-transform-property-with-built-in-loaders}

Встроенные loaders для Cloudinary, Cloudflare, ImageKit и Imgix поддерживают специальное свойство `transform` внутри `loaderParams`. Оно позволяет применять кастомные трансформации изображений, предоставляемые CDN.

Свойство `transform` принимает два формата:

#### Строковый формат {#string-format}

Передайте трансформации как строку через запятую, используя синтаксис трансформаций вашего CDN:

```html
<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: 'e_grayscale,r_10'}"
/>
```

#### Объектный формат {#object-format}

Передайте трансформации как объект с парами ключ-значение.

```html
<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: {e: 'grayscale', r: 10}}"
/>
```

NOTE: Свойство `transform` не поддерживается Netlify loader, так как image CDN Netlify не предоставляет кастомные параметры трансформации.

### Пример custom loader {#example-custom-loader}

Ниже — пример функции custom loader. Эта функция конкатенирует `src`, `width` и `height` и использует `loaderParams` для управления кастомной возможностью CDN для скруглённых углов:

```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.height) {
    queryParams.push(`h=${config.height}`);
  }
  if (config.loaderParams?.roundedCorners) {
    queryParams.push('mask=corners&corner-radius=5');
  }
  return url + queryParams.join('&');
};
```

Обратите внимание: в примере выше мы придумали имя свойства 'roundedCorners' для управления возможностью custom loader. Затем эту возможность можно использовать при создании изображения:

```html
<img ngSrc="profile.jpg" width="300" height="300" [loaderParams]="{roundedCorners: true}" />
```

## Часто задаваемые вопросы {#frequently-asked-questions}

### Поддерживает ли NgOptimizedImage CSS-свойство `background-image`? {#does-ngoptimizedimage-support-the-background-image-css-property}

NgOptimizedImage напрямую не поддерживает CSS-свойство `background-image`, но спроектирован так, чтобы легко покрывать сценарий изображения как фона другого элемента.

Пошаговый процесс миграции с `background-image` на `NgOptimizedImage` — в разделе [How to migrate your background image](#how-to-migrate-your-background-image) выше.

### Почему нельзя использовать `src` с `NgOptimizedImage`? {#why-cant-i-use-src-with-ngoptimizedimage}

Атрибут `ngSrc` был выбран как trigger для NgOptimizedImage из технических соображений о том, как браузер загружает изображения. NgOptimizedImage программно меняет атрибут `loading` — если браузер увидит атрибут `src` до этих изменений, он начнёт eagerly скачивать файл изображения, и изменения loading будут проигнорированы.

### Почему для домена моего изображения не генерируется элемент preconnect? {#why-is-a-preconnect-element-not-being-generated-for-my-image-domain}

Генерация preconnect выполняется на основе статического анализа приложения. Это значит, что домен изображения должен быть напрямую включён в параметр loader, как в следующем примере:

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

Если для передачи строки домена в loader используется переменная, или loader не используется, статический анализ не сможет определить домен, и preconnect-ссылка не будет сгенерирована. В этом случае следует вручную добавить preconnect-ссылку в document head, как [описано выше](#add-resource-hints).

### Можно ли использовать два разных домена изображений на одной странице? {#can-i-use-two-different-image-domains-in-the-same-page}

Паттерн провайдера [image loaders](#configuring-an-image-loader-for-ngoptimizedimage) спроектирован максимально просто для распространённого случая одного image CDN в компоненте. Однако управлять несколькими image CDN через один провайдер всё равно вполне возможно.

Для этого рекомендуем написать [custom image loader](#custom-loaders), который использует свойство [`loaderParams`](#the-loaderparams-property) для передачи флага, указывающего, какой image CDN использовать, и затем вызывает соответствующий loader на основе этого флага.

### Можно ли добавить новый встроенный loader для моего предпочтительного CDN? {#can-you-add-a-new-built-in-loader-for-my-preferred-cdn}

По причинам поддержки мы сейчас не планируем поддерживать дополнительные встроенные loaders в репозитории Angular. Вместо этого рекомендуем разработчикам публиковать дополнительные image loaders как сторонние пакеты.

### Можно ли использовать это с тегом `<picture>` {#can-i-use-this-with-the-picture-tag}

Нет, но это в нашем roadmap — следите за обновлениями.

Если ждёте эту возможность, проголосуйте за GitHub issue [здесь](https://github.com/angular/angular/issues/56594).

### Как найти LCP-изображение с помощью Chrome DevTools? {#how-do-i-find-my-lcp-image-with-chrome-devtools}

1. На вкладке performance Chrome DevTools нажмите кнопку «start profiling and reload page» вверху слева. Она выглядит как иконка обновления страницы.

2. Это запустит profiling snapshot вашего Angular-приложения.

3. Когда результат profiling будет доступен, выберите «LCP» в секции timings.

4. В панели внизу должна появиться summary entry. LCP-элемент можно найти в строке «related node». Клик по нему покажет элемент на панели Elements.

NOTE: Это определяет LCP-элемент только в пределах viewport тестируемой страницы. Также рекомендуется использовать mobile emulation, чтобы определить LCP-элемент для меньших экранов.
В Angular вы используете _сигналы (signals)_ для создания и управления состоянием. Сигнал — это легковесная обертка
вокруг значения.

Используйте функцию `signal` для создания сигнала для хранения локального состояния:

```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());
```

Angular отслеживает, где читаются сигналы и когда они обновляются. Фреймворк использует эту информацию для выполнения
дополнительной работы, такой как обновление DOM новым состоянием. Эта способность реагировать на изменение значений
сигналов с течением времени известна как _реактивность_.

## Вычисляемые выражения (Computed expressions) {#computed-expressions}

`computed` — это сигнал, который производит свое значение на основе других сигналов.

```typescript
import {signal, computed} from '@angular/core';

const firstName = signal('Morgan');
const firstNameCapitalized = computed(() => firstName().toUpperCase());

console.log(firstNameCapitalized()); // MORGAN
```

Сигнал `computed` доступен только для чтения; у него нет методов `set` или `update`. Вместо этого значение сигнала
`computed` автоматически изменяется, когда изменяется любой из сигналов, которые он читает:

```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
```

## Использование сигналов в компонентах {#using-signals-in-components}

Используйте `signal` и `computed` внутри ваших компонентов для создания и управления состоянием:

```typescript
@Component({/* ... */})
export class UserProfile {
  isTrial = signal(false);
  isTrialExpired = signal(false);
  showTrialDuration = computed(() => this.isTrial() && !this.isTrialExpired());

activateTrial() {
    this.isTrial.set(true);
  }
}
```

TIP: Хотите узнать больше о сигналах Angular? Смотрите [Углубленное руководство по сигналам](guide/signals) для
получения полной информации.

## Следующий шаг {#next-step}

Теперь, когда вы узнали, как объявлять и управлять динамическими данными, пришло время узнать, как использовать эти
данные внутри шаблонов.
# Зависимое состояние с помощью `linkedSignal`

Вы можете использовать функцию `signal` для хранения состояния в вашем Angular-коде. Иногда это состояние зависит от
_другого_ состояния. Например, представьте компонент, который позволяет пользователю выбрать способ доставки для заказа:

```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]);
  }
}
```

В этом примере `selectedOption` по умолчанию выбирает первую опцию, но меняется, если пользователь выбирает другую. Но
`shippingOptions` — это сигнал, его значение может измениться! Если `shippingOptions` изменится, `selectedOption` может
содержать значение, которое больше не является допустимой опцией.

**Функция `linkedSignal` позволяет создать сигнал для хранения состояния, которое неразрывно _связано_ с другим
состоянием.** Возвращаясь к примеру выше, `linkedSignal` может заменить `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` работает аналогично `signal` с одним ключевым отличием: вместо передачи значения по умолчанию вы
передаете _функцию вычисления_ (computation function), точно так же, как в `computed`. Когда значение вычисления
меняется, значение `linkedSignal` меняется на результат вычисления. Это помогает гарантировать, что `linkedSignal`
всегда имеет допустимое значение.

Следующий пример показывает, как значение `linkedSignal` может изменяться в зависимости от связанного с ним состояния:

```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'
```

## Учет предыдущего состояния {#accounting-for-previous-state}

В некоторых случаях вычисление для `linkedSignal` должно учитывать предыдущее значение самого `linkedSignal`.

В примере выше `selectedOption` всегда сбрасывается на первую опцию при изменении `shippingOptions`. Однако вы можете
захотеть сохранить выбор пользователя, если выбранная им опция все еще присутствует в списке. Чтобы добиться этого,
можно создать `linkedSignal` с отдельными свойствами _source_ (источник) и _computation_ (вычисление):

```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' },
    ]);
  }
}
```

При создании `linkedSignal` вы можете передать объект с отдельными свойствами `source` и `computation` вместо
предоставления только функции вычисления.

Свойством `source` может быть любой сигнал, например `computed` или `input` компонента. Когда значение `source`
меняется, `linkedSignal` обновляет свое значение результатом предоставленного `computation`.

`computation` — это функция, которая получает новое значение `source` и объект `previous`. Объект `previous` имеет два
свойства: `previous.source` — это предыдущее значение источника, и `previous.value` — это предыдущее значение
`linkedSignal`. Вы можете использовать эти предыдущие значения для определения нового результата вычисления.

HELPFUL: При использовании параметра `previous` необходимо явно указывать аргументы обобщенного типа (generic type
arguments) для `linkedSignal`. Первый обобщенный тип соответствует типу `source`, а второй определяет тип возвращаемого
значения `computation`.

## Пользовательское сравнение на равенство {#custom-equality-comparison}

`linkedSignal`, как и любой другой сигнал, может быть настроен с пользовательской функцией равенства. Эта функция
используется зависимостями ниже по потоку для определения того, изменилось ли значение `linkedSignal` (результат
вычисления):

```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,
});
```

## Настройка операции set {#customizing-the-set-operation}

Иногда операции `set` и `update` у `linkedSignal` нужно направлять обратно в источник истины, а не обновлять значение самого `linkedSignal` напрямую. Такое поведение можно настроить, передав функцию `set` в опциях.

Пользовательская функция `set` получает два аргумента:

1. Новое устанавливаемое значение.
2. Функцию `rawSet`, которую можно вызвать, чтобы обновить внутреннее состояние `linkedSignal` напрямую (как при поведении по умолчанию).

NOTE: С помощью `rawSet` можно обновить значение `linkedSignal` напрямую. Это полезно, если нужно избежать повторного запуска вычисления — например, когда оно дорогое, а результат уже известен.

### Запись обратно в исходный сигнал {#writing-back-to-a-source-signal}

Рассмотрим компонент, который отображает и позволяет редактировать температуру в градусах Фаренгейта, но в качестве источника истины использует сигнал в градусах Цельсия:

```typescript
const tempC = signal(0);
const tempF = linkedSignal(() => (tempC() * 9) / 5 + 32, {
  set: (valF) => tempC.set(((valF - 32) * 5) / 9),
});

console.log(tempF()); // 32

// Setting Fahrenheit updates Celsius, which reactively updates Fahrenheit
tempF.set(212);
console.log(tempC()); // 100
console.log(tempF()); // 212
```

### Обновление свойства внутри родительского объекта {#updating-a-property-inside-a-parent-object}

Ещё один распространённый сценарий — обновление конкретного свойства внутри родительского объекта. Родитель хранится в сигнале, а вы связываетесь со вложенным свойством:

```typescript
interface Order {
  id: number;
  shippingMethod: string;
}

const order = signal<Order>({
  id: 42,
  shippingMethod: 'Ground',
});

const shippingMethod = linkedSignal(() => order().shippingMethod, {
  set: (newMethod) => {
    // Perform an immutable update to write the change back to the order
    order.update((currentOrder) => ({
      ...currentOrder,
      shippingMethod: newMethod,
    }));
  },
});

console.log(shippingMethod()); // 'Ground'

// Updating the shippingMethod updates the parent order object
shippingMethod.set('Air');
console.log(order()); // { id: 42, shippingMethod: 'Air' }
console.log(shippingMethod()); // 'Air'
```
# Асинхронная реактивность с resources

Все signal API синхронны — `signal`, `computed`, `input` и т.д. Однако приложениям часто нужно работать с данными, доступными асинхронно. `Resource` даёт способ включить async-данные в signal-based код приложения и при этом обращаться к ним синхронно.

`Resource` можно использовать для любой async-операции, но самый частый сценарий — получение данных с сервера. Следующий пример создаёт resource для получения данных пользователя.

Самый простой способ создать `Resource` — функция `resource`.

```typescript
import {computed, 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
    // - It 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;
});
```

Функция `resource` принимает объект `ResourceOptions` с двумя основными свойствами: `params` и `loader`.

Свойство `params` определяет реактивное вычисление, производящее значение параметра. Когда сигналы, прочитанные в этом вычислении, меняются, resource производит новое значение параметра — подобно `computed`.

Свойство `loader` определяет `ResourceLoader` — async-функцию, которая получает некоторое состояние. Resource вызывает loader каждый раз, когда вычисление `params` производит новое значение, передавая это значение в loader. Подробнее — в [Resource loaders](#resource-loaders).

У `Resource` есть сигнал `value`, содержащий результаты loader.

## Resource loaders {#resource-loaders}

При создании resource вы указываете `ResourceLoader`. Это async-функция, принимающая один параметр — объект `ResourceLoaderParams` — и возвращающая значение.

Объект `ResourceLoaderParams` содержит три свойства: `params`, `previous` и `abortSignal`.

| Свойство      | Описание                                                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`      | Значение вычисления `params` resource.                                                                                                           |
| `previous`    | Объект со свойством `status`, содержащим предыдущий `ResourceStatus`.                                                                            |
| `abortSignal` | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). Подробнее — в [Aborting requests](#aborting-requests).             |

Если вычисление `params` возвращает `undefined`, функция loader не выполняется, и статус resource становится `'idle'`.

### Streaming resources {#streaming-resources}

Некоторые асинхронные источники данных производят несколько значений со временем вместо одного результата. Примеры — WebSockets, Server-Sent Events (SSE) и слушатели Firestore `onSnapshot`.

Для таких непрерывно обновляющихся источников используйте `stream`. В отличие от `loader`, который разрешается один раз для каждого запроса, `stream` возвращает сигнал, значение которого может продолжать обновляться по мере появления новых данных.

Используйте `loader` для одноразовых асинхронных операций, например получения данных с HTTP endpoint.

```typescript
const userUpdates = signal({value: 'Alice'});

const userResource = resource({
  stream: () => userUpdates,
});

// Later, when new data arrives:
userUpdates.set({value: 'Bob'});
```

### Отмена запросов {#aborting-requests}

Resource отменяет незавершённую операцию загрузки, если вычисление `params` меняется, пока resource загружается.

Можно использовать `abortSignal` в `ResourceLoaderParams`, чтобы реагировать на отменённые запросы. Например, нативная функция `fetch` принимает `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});
  },
});
```

Подробнее об отмене запросов с `AbortSignal` — в [`AbortSignal` на MDN](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).

### Перезагрузка {#reloading}

Можно программно запустить `loader` resource, вызвав метод `reload`.

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

// ...

userResource.reload();
```

## Статус Resource {#resource-status}

Объект resource имеет несколько signal-свойств для чтения статуса асинхронного loader.

| Свойство    | Описание                                                                                                        |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| `value`     | Самое недавнее значение resource или `undefined`, если значение ещё не получено.                                |
| `hasValue`  | Есть ли у resource значение.                                                                                    |
| `error`     | Самая недавняя ошибка при выполнении loader resource или `undefined`, если ошибок не было.                      |
| `isLoading` | Выполняется ли сейчас loader resource.                                                                          |
| `status`    | Конкретный `ResourceStatus` resource, как описано ниже.                                                         |

Сигнал `status` предоставляет конкретный `ResourceStatus`, описывающий состояние resource строковой константой.

| Статус        | `value()`         | Описание                                                                         |
| ------------- | :---------------- | -------------------------------------------------------------------------------- |
| `'idle'`      | `undefined`       | У resource нет валидного запроса, и loader не выполнялся.                        |
| `'error'`     | `undefined`       | Loader столкнулся с ошибкой.                                                     |
| `'loading'`   | `undefined`       | Loader выполняется из‑за изменения значения `params`.                            |
| `'reloading'` | Previous value    | Loader выполняется из‑за вызова метода `reload` resource.                        |
| `'resolved'`  | Resolved value    | Loader завершился.                                                               |
| `'local'`     | Locally set value | Значение resource задано локально через `.set()` или `.update()`                 |

Эту информацию о статусе можно использовать для условного отображения элементов UI — индикаторов загрузки и сообщений об ошибках.

## Кэширование данных `resource` с SSR {#caching-resource-data-with-ssr}

Когда приложение рендерится на сервере, loader resource выполняется один раз для создания начального HTML. Во время гидратации браузер обычно снова запускает тот же loader.

Чтобы переиспользовать результат сервера, предоставьте `id` для resource. Angular сохраняет разрешённое значение в `TransferState` на сервере и использует его на клиенте для инициализации resource в состоянии `'resolved'`.

```ts
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
  id: 'user-unique-id',
});
```

Значение `id` должно быть уникальным в приложении и одинаковым на сервере и клиенте, чтобы Angular мог сопоставить кэшированную запись с resource, который её запросил.

IMPORTANT: Поскольку кэшированное значение сериализуется в HTML страницы, избегайте установки `id` на resources, загружающих данные, специфичные для пользователя, вызвавшего server-side render — особенно если отрендеренный HTML может кэшироваться или разделяться между пользователями.

## Цепочки resources {#chaining-resources}

Иногда один resource зависит от результата другого. Эту зависимость можно выразить через функцию `chain`, доступную в объекте контекста `params`.

```typescript
import {resource} from '@angular/core';

const userResource = resource({
  params: () => ({id: getUserId()}),
  loader: ({params}) => fetchUser(params),
});

const companyResource = resource({
  params: ({chain}) => chain(userResource)?.companyId,
  loader: ({params: companyId}) => fetchCompany(companyId),
});
```

Здесь `companyResource` зависит от `companyId` пользователя, который известен только после загрузки `userResource`. `chain(userResource)` читает значение `userResource` и автоматически распространяет его статус на `companyResource`:

- Если `userResource` **idle**, `companyResource` тоже становится `idle`.
- Если `userResource` **loading** или **reloading**, `companyResource` входит в состояние `loading`, и его loader не выполняется. Обратите внимание: во время `reloading` `chain` не возвращает ранее разрешённое значение.
- Если `userResource` в состоянии **error**, `companyResource` тоже входит в состояние `error`.
- Если `userResource` **resolved** или **local**, `chain` возвращает его текущее значение, которое `companyResource` затем использует как params.

Когда `chain` распространяет статус из `userResource` (`idle`, `loading`, `reloading` или `error`), функция params не продолжается. Когда `userResource` — `resolved` или `local`, `chain` возвращает его значение, которое само может быть `undefined`. Пример обрабатывает это через `chain(userResource)?.companyId`, так что значение `undefined` приводит к `undefined` params, и `companyResource` становится `idle`.

NOTE: Передавайте chained-значение напрямую как значение params, а не оборачивайте его в объект. Значение params вроде `{companyId: undefined}` всё ещё является определённым значением, поэтому loader выполнится с `undefined` `companyId` вместо того, чтобы resource стал `idle`.

### Chaining vs. прямое чтение значений resource {#chaining-vs-reading-resource-values-directly}

Может возникнуть желание прочитать значение resource напрямую внутри `params`:

```typescript
{avoid, header: 'reads value() directly without status propagation'}
const companyResource = resource({
  params: () => {
    const user = userResource.value(); // may be undefined
    return user ? {companyId: user.companyId} : undefined;
  },
  loader: ({params}) => fetchCompany(params.companyId),
});
```

Хотя это работает, возврат `undefined` из `params` делает resource `idle`, а не отражает фактическое состояние upstream resource. Предпочтительнее использовать `chain`, потому что он корректно зеркалирует состояния `loading` и `error`.

Обращайтесь к `chain` только когда downstream resource выполняет собственную async-работу, зависящую от upstream-значения. Если нужно только синхронно вывести значение из resource, используйте `computed`.

## Реактивное получение данных с `httpResource` {#reactive-data-fetching-with-httpresource}

[`httpResource`](/guide/http/http-resource) — обёртка над `HttpClient`, дающая статус запроса и ответ как сигналы. Она делает HTTP-запросы через Angular HTTP stack, включая interceptors.

## Композиция Resource со snapshots {#resource-composition-with-snapshots}

`ResourceSnapshot` — структурированное представление текущего состояния resource. У каждого resource есть свойство `snapshot`, предоставляющее сигнал его текущего состояния.

```ts
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

const userSnapshot = userResource.snapshot;
```

Каждый snapshot содержит `status` и либо `value`, либо `error`.

### Композиция resources со snapshots {#composing-resources-with-snapshots}

Новые resources можно создавать из snapshots через `resourceFromSnapshots`. Это позволяет композицию с signal API вроде `computed` и `linkedSignal` для трансформации поведения resource.

```ts
import {linkedSignal, resourceFromSnapshots, Resource, ResourceSnapshot} from '@angular/core';

function withPreviousValue<T>(input: Resource<T>): Resource<T> {
  const derived = linkedSignal<ResourceSnapshot<T>, ResourceSnapshot<T>>({
    source: input.snapshot,
    computation: (snap, previous) => {
      if (snap.status === 'loading' && previous && previous.value.status !== 'error') {
        // When the input resource enters loading state, we keep the value
        // from its previous state, if any.
        return {status: 'loading' as const, value: previous.value.value};
      }

// Otherwise we simply forward the state of the input resource.
      return snap;
    },
  });

return resourceFromSnapshots(derived);
}

@Component({
  /*... */
})
export class AwesomeProfile {
  userId = input.required<number>();
  user = withPreviousValue(httpResource(() => `/user/${this.userId()}`));
  // When userId changes, user.value() keeps the old user data until the new one loads
}
```
# Создание внедряемого сервиса

Сервис — широкая категория: любое значение, функция или возможность, нужная приложению.
Обычно сервис — это класс с узкой и чётко определённой целью.
Компонент — один из типов классов, которые можно использовать с внедрением зависимостей (DI).

Angular разделяет компоненты и сервисы, чтобы повысить модульность и переиспользуемость.
Отделяя связанную с представлением логику компонента от других видов обработки, вы сохраняете классы компонентов компактными и эффективными.

В идеале ответственность компонента — только пользовательский опыт.
Компонент должен предоставлять свойства и методы для привязки данных, опосредуя представление (рендер шаблона) и логику приложения (часто включая модель).

Задачи можно делегировать из компонента сервисам: загрузка данных с сервера, валидация ввода, логирование в консоль.
Определив такие задачи в внедряемом классе сервиса, вы делаете эти возможности доступными любому компоненту.
Приложение также становится гибче: для одного типа сервиса можно настроить разные провайдеры в зависимости от обстоятельств.

Angular не навязывает эти принципы жёстко.
Он помогает им следовать, упрощая организацию логики в сервисы и предоставление этих сервисов компонентам через DI.

## Примеры сервисов {#service-examples}

Пример класса сервиса, который пишет в консоль браузера:

```ts
{header: "logger.service.ts (class)"}
export class Logger {
  log(msg: unknown) {
    console.log(msg);
  }
  error(msg: unknown) {
    console.error(msg);
  }
  warn(msg: unknown) {
    console.warn(msg);
  }
}
```

Сервисы могут зависеть от других сервисов.
Например, `HeroService` зависит от `Logger` и использует `BackendService` для получения героев.
Тот, в свою очередь, может зависеть от `HttpClient`, чтобы асинхронно загружать героев с сервера:

```ts
{header: "hero.service.ts", highlight="[7,8,12,13]"}
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;
  }
}
```

## Создание внедряемого сервиса через CLI {#creating-an-injectable-service-with-the-cli}

Angular CLI предоставляет команду для создания нового сервиса. В следующем примере вы добавляете сервис в существующее приложение.

Чтобы сгенерировать класс `HeroService` в папке `src/app/heroes`, выполните шаги:

1. Запустите эту команду [Angular CLI](/tools/cli):

```sh
ng generate service heroes/hero
```

Команда создаёт следующий `HeroService` по умолчанию:

```ts
{header: 'heroes/hero.service.ts (CLI-generated)'}
import {Service} from '@angular/core';

@Service()
export class HeroService {}
```

Декоратор `@Service()` указывает, что Angular может использовать этот класс в системе DI и что `HeroService` доступен во всём приложении.

Добавьте метод `getHeroes()`, возвращающий героев из `mock.heroes.ts`:

```ts
{header: 'hero.service.ts'}
import {Service} from '@angular/core';
import {HEROES} from './mock-heroes';

@Service()
export class HeroService {
  getHeroes() {
    return HEROES;
  }
}
```

Для ясности и сопровождаемости рекомендуется определять компоненты и сервисы в отдельных файлах.

## Внедрение сервисов {#injecting-services}

Чтобы внедрить сервис в компонент, объявите поле класса для зависимости и инициализируйте его функцией Angular [`inject`](/api/core/inject).

В следующем примере `HeroService` указан в `HeroList`.
Тип `heroService` — `HeroService`.

```ts
import {inject} from '@angular/core';

export class HeroList {
  private heroService = inject(HeroService);
}
```

Сервис также можно внедрить через конструктор компонента:

```ts
{header: 'hero-list.ts (constructor signature)'}
  constructor(private heroService: HeroService)
```

Метод [`inject`](/api/core/inject) можно использовать и в классах, и в функциях, а конструктор — только в конструкторе класса. В обоих случаях зависимость можно внедрять только в допустимом [контексте внедрения](guide/di/dependency-injection-context), обычно при создании или инициализации компонента.

## Внедрение сервисов в другие сервисы {#injecting-services-in-other-services}

Когда сервис зависит от другого сервиса, используйте тот же паттерн, что и при внедрении в компонент.
В следующем примере `HeroService` зависит от `Logger`, чтобы сообщать о своих действиях:

```ts
{header: 'hero.service.ts, highlight: [[3],[9],[12]]}
import {inject, Service} from '@angular/core';
import {HEROES} from './mock-heroes';
import {Logger} from '../logger.service';

@Service()
export class HeroService {
  private logger = inject(Logger);

getHeroes() {
    this.logger.log('Getting heroes.');
    return HEROES;
  }
}
```

В этом примере метод `getHeroes()` использует сервис `Logger`, логируя сообщение при получении героев.

## Что дальше {#whats-next}
# Ленивая загрузка сервисов

IMPORTANT: Чтобы ленивая загрузка работала, сервис должен быть зарегистрирован автоматически. Используйте декоратор `@Injectable({providedIn: 'root'})` или [`@Service()`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator). Без автоматической регистрации Angular не сможет создать сервис после загрузки.

Функция Angular `injectAsync` позволяет загружать сервис по требованию — только когда он действительно нужен. Это полезно, если сервис зависит от большой библиотеки или редко используемой функции, и вы не хотите платить за неё при начальной загрузке страницы.

При использовании `injectAsync` код сервиса бандлер выносит в отдельный JavaScript-чанк и скачивает при первом запросе экземпляра. После загрузки Angular разрешает сервис через обычную систему DI, поэтому он по-прежнему может зависеть от других injectable и ведёт себя как любой другой синглтон.

## Ленивое внедрение сервиса {#lazily-injecting-a-service}

Представьте `ReportExporter`, зависящий от тяжёлой библиотеки для таблиц. Большинство пользователей открывают отчёт; экспорт нажимают лишь немногие. Загрузите экспортёр по требованию:

```typescript
import {Component, injectAsync} from '@angular/core';

@Component({
  selector: 'app-report',
  template: `<button (click)="export()">Export</button>`,
})
export class Report {
  private exporter = injectAsync(() => import('./report-exporter').then((m) => m.ReportExporter));

async export() {
    const exporter = await this.exporter();
    exporter.export();
  }
}
```

Первый вызов `this.exporter()` запускает динамический импорт и разрешает сервис из DI. Последующие вызовы переиспользуют тот же promise, поэтому чанк загружается только один раз.

Если лениво загружаемый сервис — [default export](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/export#using_the_default_export), передайте динамический импорт напрямую: Angular сам развернёт `default`:

```ts
{header: report-exporter.ts}
@Service()
export default class ReportExporter {
  /* … */
}
```

```ts
{header: report.ts}
private exporter = injectAsync(() => import('./report-exporter'));
```

## Prefetch зависимости {#prefetching-the-dependency}

По умолчанию ленивый чанк загружается только при вызове возвращённой функции. Скачивание можно начать раньше, передав в опциях триггер `prefetch`. Триггер — любая функция, возвращающая `Promise`: когда он разрешится, Angular запускает загрузчик.

Angular поставляет встроенный триггер `onIdle`, который ждёт, пока браузер станет простаивать:

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

@Component({
  /* … */
})
export class Report {
  private exporter = injectAsync(() => import('./report-exporter').then((m) => m.ReportExporter), {
    prefetch: onIdle,
  });
}
```

`onIdle` также можно настроить с максимальным временем ожидания, чтобы prefetch всегда происходил в известном окне, даже на загруженных страницах:

```ts
injectAsync(loader, {prefetch: () => onIdle({timeout: 1_000})});
```

NOTE: Prefetch — оппортунистический. Если пользователь вызовет функцию до срабатывания prefetch, Angular всё равно сразу загрузит зависимость и разрешит ваш `await`, как только она будет готова.

## Пользовательский триггер prefetch {#provide-a-custom-prefetch-trigger}

`PrefetchTrigger` — просто функция, возвращающая promise: загрузчик запускается, как только promise разрешится. Так можно согласовать prefetch с собственными сигналами — например, hover или тик планировщика:

```ts
import {PrefetchTrigger} from '@angular/core';

export function onHover(target: HTMLElement): PrefetchTrigger {
  return () =>
    new Promise<void>((resolve) => {
      target.addEventListener('pointerenter', () => resolve(), {once: true});
    });
}
```
# Контекст внедрения

Система внедрения зависимостей (DI) опирается на runtime-контекст, в котором доступен текущий инжектор.

Это значит, что инжекторы работают только при выполнении кода внутри этого контекста.

Контекст внедрения доступен в следующих ситуациях:

- При создании (через `constructor`) класса, экземпляр которого создаёт система DI, например `@Injectable` или `@Component`.
- В инициализаторах полей таких классов.
- В фабричной функции, указанной для `useFactory` у `Provider` или `@Injectable`.
- В функции `factory`, указанной для `InjectionToken`.
- Внутри стекового фрейма, выполняющегося в контексте внедрения.

Зная, что вы находитесь в контексте внедрения, можно использовать функцию [`inject`](api/core/inject) для получения зависимостей.

NOTE: Базовые примеры использования `inject()` в конструкторах и инициализаторах полей см. в [обзорном руководстве](/guide/di#where-can-inject-be-used).

## Стек-фрейм в контексте {#stack-frame-in-context}

Некоторые API рассчитаны на выполнение в контексте внедрения. Так, например, устроены guard'ы роутера. Это позволяет вызывать [`inject`](api/core/inject) внутри функции guard для доступа к сервисам.

Пример для `CanActivateFn`:

```ts
{highlight: [3]}
const canActivateTeam: CanActivateFn = (
  route: ActivatedRouteSnapshot,
  state: RouterStateSnapshot,
) => {
  return inject(PermissionsService).canActivate(inject(UserToken), route.params.id);
};
```

## Выполнение в контексте внедрения {#run-within-an-injection-context}

Если нужно выполнить функцию в контексте внедрения, не находясь в нём, используйте `runInInjectionContext`.
Для этого нужен доступ к инжектору, например `EnvironmentInjector`:

```ts
{highlight: [9], header:"hero.service.ts"}
@Injectable({
  providedIn: 'root',
})
export class HeroService {
  private environmentInjector = inject(EnvironmentInjector);

someMethod() {
    runInInjectionContext(this.environmentInjector, () => {
      inject(SomeService); // Do what you need with the injected service
    });
  }
}
```

Учтите: [`inject`](/api/core/inject) возвращает экземпляр только если инжектор может разрешить запрошенный токен.

## Проверка контекста {#asserts-the-context}

Angular предоставляет вспомогательную функцию `assertInInjectionContext`, которая проверяет, что текущий контекст — контекст внедрения, и выбрасывает понятную ошибку, если это не так. Передайте ссылку на вызывающую функцию, чтобы сообщение об ошибке указывало на правильную точку входа API. Так сообщение получается яснее и полезнее, чем стандартная общая ошибка внедрения.

```ts
import {ElementRef, assertInInjectionContext, inject} from '@angular/core';

export function injectNativeElement<T extends Element>(): T {
  assertInInjectionContext(injectNativeElement);
  return inject(ElementRef).nativeElement;
}
```

Затем этот хелпер можно вызывать **из контекста внедрения** (конструктор, инициализатор поля, фабрика провайдера или код, выполняемый через `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.
  }
}
```

## Использование DI вне контекста {#using-di-outside-of-a-context}

Если вызвать [`inject`](api/core/inject) или `assertInInjectionContext` вне контекста внедрения, Angular выбросит [ошибку NG0203](/errors/NG0203).
# Иерархические инжекторы

Это руководство подробно описывает иерархическую систему внедрения зависимостей Angular: правила разрешения, модификаторы и продвинутые паттерны.

NOTE: Базовые концепции иерархии инжекторов и области провайдеров см. в [руководстве по определению провайдеров зависимостей](guide/di/defining-dependency-providers#injector-hierarchy-in-angular).

## Типы иерархий инжекторов {#types-of-injector-hierarchies}

В Angular две иерархии инжекторов:

| Иерархия инжекторов            | Подробности                                                                                                                                                               |
| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Иерархия `EnvironmentInjector` | Настраивается через `@Service()` или массив `providers` в `ApplicationConfig`.                                                                                            |
| Иерархия `ElementInjector`     | Создаётся неявно для каждого DOM-элемента. По умолчанию пуста, пока не настроить свойство `providers` у `@Directive()` или `@Component()`.                                |
В приложениях на основе `NgModule` зависимости можно предоставлять через иерархию `ModuleInjector` с помощью аннотации `@NgModule()` или `@Injectable()`.
### `EnvironmentInjector` {#environmentinjector}

`EnvironmentInjector` можно настроить одним из двух способов:

- Через `@Service()`
- Через массив `providers` в `ApplicationConfig`
Декоратор `@Service()` предпочтительнее массива `providers` в `ApplicationConfig`. С `@Service` инструменты оптимизации могут выполнять tree-shaking и удалять неиспользуемые сервисы. Это уменьшает размер бандла.

Tree-shaking особенно полезен для библиотеки: приложение, использующее библиотеку, может не внедрять этот сервис.
`EnvironmentInjector` настраивается через `ApplicationConfig.providers`.

Предоставляйте сервисы с `@Service()` так:

```ts
{highlight:[4]}
import {Service} from '@angular/core';

@Service() // <--provides this service in the root EnvironmentInjector
export class ItemService {
  name = 'telephone';
}
```

Декораторы `@Service()` или `@Injectable()` идентифицируют класс сервиса.

### ModuleInjector {#moduleinjector}

В приложениях на основе `NgModule` ModuleInjector можно настроить одним из способов:

- Декоратор `@Service()`,
- Свойство `providedIn` у `@Injectable()` со значением `root` или `platform`
- Массив `providers` у `@NgModule()`

`ModuleInjector` настраивается свойствами `@NgModule.providers` и `NgModule.imports`. `ModuleInjector` — это объединение всех массивов providers, достижимых рекурсивным обходом `NgModule.imports`.

Дочерние иерархии `ModuleInjector` создаются при ленивой загрузке других `@NgModules`.

### Platform injector {#platform-injector}

Над `root` есть ещё два инжектора: дополнительный `EnvironmentInjector` и `NullInjector()`.

Рассмотрим, как Angular загружает приложение в `main.ts`:

```ts
bootstrapApplication(App, appConfig);
```

Метод `bootstrapApplication()` создаёт дочерний инжектор platform-инжектора, настроенный экземпляром `ApplicationConfig`.
Это `root` `EnvironmentInjector`.

Метод `platformBrowserDynamic()` создаёт инжектор, настроенный `PlatformModule` с платформо-специфичными зависимостями.
Это позволяет нескольким приложениям делить конфигурацию платформы.
Например, у браузера одна адресная строка, сколько бы приложений ни работало.
Дополнительные платформо-специфичные провайдеры можно настроить на уровне платформы, передав `extraProviders` в функцию `platformBrowser()`.

Следующий родительский инжектор в иерархии — `NullInjector()`, вершина дерева.
Если поиск дошёл до `NullInjector()`, вы получите ошибку, если не использовали `@Optional()`: всё заканчивается на `NullInjector()`, который возвращает ошибку или, в случае `@Optional()`, `null`.
Подробнее об `@Optional()` — в [разделе `@Optional()`](#optional) этого руководства.

Следующая диаграмма показывает связь между `root` `ModuleInjector` и его родительскими инжекторами.

```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
```

Имя `root` — специальный псевдоним; у других иерархий `EnvironmentInjector` псевдонимов нет.
Иерархии `EnvironmentInjector` можно создавать при создании динамически загружаемого компонента, например через Router, который создаёт дочерние иерархии `EnvironmentInjector`.

Все запросы поднимаются к root-инжектору — независимо от того, настроили ли вы его через `ApplicationConfig` в `bootstrapApplication()`, или зарегистрировали провайдеры с `root` в самих сервисах.
Если настроить app-wide провайдер в `ApplicationConfig` у `bootstrapApplication`, он переопределяет конфигурацию для `root` в метаданных `@Injectable()`.
Так можно настроить нестандартный провайдер сервиса, общего для нескольких приложений.

Пример: конфигурация роутера компонентов включает нестандартную [стратегию location](guide/routing/common-router-tasks#locationstrategy-and-browser-url-styles), перечисляя её провайдер в списке `providers` у `ApplicationConfig`.

```ts
providers: [{provide: LocationStrategy, useClass: HashLocationStrategy}];
```

В приложениях на основе `NgModule` app-wide провайдеры настраивают в `providers` у `AppModule`.
### `ElementInjector` {#elementinjector}

Angular неявно создаёт иерархии `ElementInjector` для каждого DOM-элемента.

Предоставление сервиса в декораторе `@Component()` через свойства `providers` или `viewProviders` настраивает `ElementInjector`.
Например, следующий `TestComponent` настраивает `ElementInjector`, предоставляя сервис так:

```ts
{highlight:[3]}
@Component({
  /* … */
  providers: [{ provide: ItemService, useValue: { name: 'lamp' } }]
})
export class TestComponent
```

HELPFUL: См. раздел [правила разрешения](#resolution-rules), чтобы понять связь между деревом `EnvironmentInjector`, `ModuleInjector` и деревом `ElementInjector`.

Когда вы предоставляете сервисы в компоненте, сервис доступен через `ElementInjector` этого экземпляра компонента.
Он также может быть виден дочерним компонентам/директивам согласно правилам видимости из раздела [правила разрешения](#resolution-rules).

Когда экземпляр компонента уничтожается, уничтожается и экземпляр сервиса.

#### `@Directive()` и `@Component()` {#directive-and-component}

Компонент — особый тип директивы, поэтому у `@Component()` есть свойство `providers`, как и у `@Directive()`.
Директивы и компоненты могут настраивать провайдеры через свойство `providers`.
Когда вы настраиваете провайдер для компонента или директивы через `providers`, этот провайдер принадлежит `ElementInjector` этого компонента или директивы.
Компоненты и директивы на одном элементе делят один инжектор.

## Правила разрешения {#resolution-rules}

При разрешении токена для компонента/директивы Angular делает это в две фазы:

1. Против родителей в иерархии `ElementInjector`.
2. Против родителей в иерархии `EnvironmentInjector`.

Когда компонент объявляет зависимость, Angular пытается удовлетворить её собственным `ElementInjector`.
Если у инжектора компонента нет провайдера, запрос передаётся родительскому `ElementInjector`.

Запросы продолжают подниматься, пока Angular не найдёт инжектор, способный обработать запрос, или не закончатся предки в иерархиях `ElementInjector`.

Если Angular не находит провайдер ни в одной иерархии `ElementInjector`, он возвращается к элементу, откуда исходил запрос, и ищет в иерархии `EnvironmentInjector`.
Если провайдер всё ещё не найден, Angular выбрасывает ошибку.

Если провайдер для одного DI-токена зарегистрирован на разных уровнях, Angular использует первый встреченный.
Например, если провайдер зарегистрирован локально в компоненте, которому нужен сервис, Angular не ищет другой провайдер того же сервиса.

HELPFUL: В приложениях на основе `NgModule` Angular ищет в иерархии `ModuleInjector`, если не находит провайдер в иерархиях `ElementInjector`.

## Модификаторы разрешения {#resolution-modifiers}

Поведение разрешения Angular можно изменить с помощью `optional`, `self`, `skipSelf` и `host`.
Импортируйте каждый из `@angular/core` и используйте в конфигурации [`inject`](/api/core/inject) при внедрении сервиса.

### Типы модификаторов {#types-of-modifiers}

Модификаторы разрешения делятся на три категории:

- Что делать, если Angular не находит нужное — `optional`
- Где начинать поиск — `skipSelf`
- Где останавливать поиск — `host` и `self`

По умолчанию Angular всегда начинает с текущего `Injector` и продолжает поиск вверх.
Модификаторы позволяют изменить начальную (_self_) и конечную точки поиска.

Кроме того, можно комбинировать все модификаторы, кроме:

- `host` и `self`
- `skipSelf` и `self`.

### `optional` {#optional}

`optional` позволяет считать внедряемый сервис опциональным.
Если его нельзя разрешить в runtime, Angular разрешает сервис как `null`, а не выбрасывает ошибку.
В следующем примере сервис `OptionalService` не предоставлен в сервисе, `ApplicationConfig`, `@NgModule()` или классе компонента, поэтому недоступен нигде в приложении.

```ts
{header:"src/app/optional/optional.ts"}
export class Optional {
  public optional? = inject(OptionalService, {optional: true});
}
```

### `self` {#self}

Используйте `self`, чтобы Angular смотрел только на `ElementInjector` текущего компонента или директивы.

Хороший сценарий для `self` — внедрить сервис только если он доступен на текущем host-элементе.
Чтобы избежать ошибок, комбинируйте `self` с `optional`.

Например, в следующем `SelfNoData` обратите внимание на внедрённый `LeafService` как свойство.

```ts
{header: 'self-no-data.ts', highlight: [7]}
@Component({
  selector: 'app-self-no-data',
  templateUrl: './self-no-data.html',
  styleUrls: ['./self-no-data.css'],
})
export class SelfNoData {
  public leaf = inject(LeafService, {optional: true, self: true});
}
```

В этом примере есть родительский провайдер, и обычное внедрение вернёт значение; однако внедрение с `self` и `optional` вернёт `null`, потому что `self` останавливает поиск на текущем host-элементе.

Другой пример показывает класс компонента с провайдером для `FlowerService`.
В этом случае инжектор не ищет дальше текущего `ElementInjector`, потому что находит `FlowerService` и возвращает тюльпан 🌷.

```ts
{header:"src/app/self/self.ts"}
@Component({
  selector: 'app-self',
  templateUrl: './self.html',
  styleUrls: ['./self.css'],
  providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}],
})
export class Self {
  public flower = inject(FlowerService, {self: true});
}
```

### `skipSelf` {#skipself}

`skipSelf` — противоположность `self`.
С `skipSelf` Angular начинает поиск сервиса в родительском `ElementInjector`, а не в текущем.
Поэтому если родительский `ElementInjector` использует значение папоротника <code>🌿</code> для `emoji`, а в массиве `providers` компонента — кленовый лист <code>🍁</code>, Angular проигнорирует кленовый лист <code>🍁</code> и использует папоротник <code>🌿</code>.

В коде предположим, что родительский компонент использует следующее значение `emoji`, как в этом сервисе:

```ts
{header: 'leaf.service.ts'}
export class LeafService {
  emoji = '🌿';
}
```

Представьте, что в дочернем компоненте другое значение — кленовый лист 🍁, но нужно использовать значение родителя.
Тогда применяют `skipSelf`:

```ts
{header:"skipself.ts" highlight:[[6],[10]]}
@Component({
  selector: 'app-skipself',
  templateUrl: './skipself.html',
  styleUrls: ['./skipself.css'],
  // Angular would ignore this LeafService instance
  providers: [{provide: LeafService, useValue: {emoji: '🍁'}}],
})
export class Skipself {
  // Use skipSelf as inject option
  public leaf = inject(LeafService, {skipSelf: true});
}
```

В этом случае значение `emoji` будет папоротник <code>🌿</code>, а не кленовый лист <code>🍁</code>.

#### Опция `skipSelf` с `optional` {#skipself-option-with-optional}

Используйте опцию `skipSelf` с `optional`, чтобы предотвратить ошибку, если значение `null`.

В следующем примере сервис `Person` внедряется при инициализации свойства.
`skipSelf` говорит Angular пропустить текущий инжектор, а `optional` предотвратит ошибку, если `Person` окажется `null`.

```ts
class Person {
  parent = inject(Person, {optional: true, skipSelf: true});
}
```

### `host` {#host}

`host` позволяет назначить компонент последней остановкой в дереве инжекторов при поиске провайдеров.

Даже если экземпляр сервиса есть выше по дереву, Angular не продолжит поиск.
Используйте `host` так:

```ts
{header:"host.ts" highlight:[[6],[9]]}
@Component({
  selector: 'app-host',
  templateUrl: './host.html',
  styleUrls: ['./host.css'],
  // provide the service
  providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}],
})
export class Host {
  // use host when injecting the service
  flower = inject(FlowerService, {host: true, optional: true});
}
```

Поскольку у `Host` есть опция `host`, независимо от значения `flower.emoji` у родителя `Host`, `Host` будет использовать тюльпан <code>🌷</code>.

### Модификаторы с внедрением через конструктор {#modifiers-with-constructor-injection}

Аналогично, поведение внедрения через конструктор можно изменить с помощью `@Optional()`, `@Self()`, `@SkipSelf()` и `@Host()`.

Импортируйте каждый из `@angular/core` и используйте в конструкторе класса компонента при внедрении сервиса.

```ts
{header:"self-no-data.ts" highlight:[2]}
export class SelfNoData {
  constructor(@Self() @Optional() public leaf?: LeafService) {}
}
```

## Логическая структура шаблона {#logical-structure-of-the-template}

Когда вы предоставляете сервисы в классе компонента, они видны в дереве `ElementInjector` относительно того, где и как вы их предоставляете.

Понимание логической структуры шаблона Angular даёт основу для настройки сервисов и контроля их видимости.

Компоненты используются в шаблонах, как в следующем примере:

```html
<app-root> <app-child />; </app-root>
```

HELPFUL: Обычно компоненты и их шаблоны объявляют в отдельных файлах.
Чтобы понять, как работает система внедрения, полезно смотреть на них как на объединённое логическое дерево.
Термин _логическое_ отличает его от дерева рендера — DOM-дерева приложения.
Чтобы отметить расположение шаблонов компонентов, в этом руководстве используется псевдоэлемент `<#VIEW>`, которого нет в дереве рендера и который нужен только для ментальной модели.

Пример объединения деревьев представлений `<app-root>` и `<app-child>` в одно логическое дерево:

```html
<app-root>
  <#VIEW>
    <app-child>
     <#VIEW>
       …content goes here…
     </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

Понимание разметки `<#VIEW>` особенно важно при настройке сервисов в классе компонента.

## Пример: предоставление сервисов в `@Component()` {#example-providing-services-in-component}

То, как вы предоставляете сервисы через декоратор `@Component()` (или `@Directive()`), определяет их видимость.
В следующих разделах демонстрируются `providers` и `viewProviders`, а также способы изменения видимости сервисов с `skipSelf` и `host`.

Класс компонента может предоставлять сервисы двумя способами:

| Массивы                      | Подробности                                    |
| :--------------------------- | :--------------------------------------------- |
| Массив `providers`           | `@Component({ providers: [SomeService] })`     |
| Массив `viewProviders`       | `@Component({ viewProviders: [SomeService] })` |

В примерах ниже вы увидите логическое дерево приложения Angular.
Чтобы показать, как инжектор работает в контексте шаблонов, логическое дерево представляет HTML-структуру приложения.
Например, логическое дерево покажет, что `<child-component>` — прямой потомок `<parent-component>`.

В логическом дереве вы увидите специальные атрибуты: `@Provide`, `@Inject` и `@ApplicationConfig`.
Это не настоящие атрибуты — они демонстрируют, что происходит «под капотом».

| Атрибут сервиса Angular   | Подробности                                                                                          |
| :------------------------ | :--------------------------------------------------------------------------------------------------- |
| `@Inject(Token)=>Value`   | Если `Token` внедряется в этом месте логического дерева, его значение будет `Value`.                 |
| `@Provide(Token=Value)`   | Указывает, что `Token` предоставлен со значением `Value` в этом месте логического дерева.            |
| `@ApplicationConfig`      | Показывает, что в этом месте следует использовать запасной `EnvironmentInjector`.                    |

### Структура примера приложения {#example-app-structure}

В примере приложения `FlowerService` предоставлен в `root` со значением `emoji` — красный гибискус <code>🌺</code>.

```ts
{header:"flower.service.ts"}
@Service()
export class FlowerService {
  emoji = '🌺';
}
```

Рассмотрим приложение только с `App` и `Child`.
Самое базовое отрендеренное представление выглядело бы как вложенные HTML-элементы:

```html
<app-root>
  
  <app-child>  </app-child>
</app-root>
```

Однако за кулисами Angular использует логическое представление при разрешении запросов внедрения:

```html
<app-root> 
  <#VIEW>
    <app-child> 
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

Здесь `<#VIEW>` представляет экземпляр шаблона.
У каждого компонента свой `<#VIEW>`.

Знание этой структуры помогает предоставлять и внедрять сервисы и даёт полный контроль над их видимостью.

Теперь предположим, что `<app-root>` внедряет `FlowerService`:

```typescript
export class App {
  flower = inject(FlowerService);
}
```

Добавьте привязку в шаблон `<app-root>`, чтобы визуализировать результат:

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

Вывод в представлении:

```text
{hideCopy}
Emoji from FlowerService: 🌺
```

В логическом дереве это выглядит так:

```html
<app-root @ApplicationConfig
        @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
    <p>Emoji from FlowerService: {{flower.emoji}} (🌺)</p>
    <app-child>
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

Когда `<app-root>` запрашивает `FlowerService`, задача инжектора — разрешить токен `FlowerService`.
Разрешение токена происходит в две фазы:

1. Инжектор определяет начальную и конечную точки поиска в логическом дереве.
   Он начинает с начальной точки и ищет токен на каждом уровне представления.
   Если токен найден — возвращает его.

1. Если токен не найден, инжектор ищет ближайший родительский `EnvironmentInjector`, чтобы делегировать запрос.

В примере ограничения такие:

1. Начать с `<#VIEW>`, принадлежащего `<app-root>`, и закончить на `<app-root>`.
   - Обычно поиск начинается в точке внедрения.
     Однако `<app-root>` — компонент. У `@Component` также есть собственные `viewProviders`, поэтому поиск начинается с `<#VIEW>` у `<app-root>`.
     Для директивы, сопоставленной в том же месте, это было бы иначе.
   - Конечная точка совпадает с самим компонентом, потому что это самый верхний компонент в приложении.

1. `EnvironmentInjector`, предоставленный `ApplicationConfig`, действует как запасной инжектор, когда токен не найден в иерархиях `ElementInjector`.

### Использование массива `providers` {#using-the-providers-array}

Теперь в классе `Child` добавьте провайдер для `FlowerService`, чтобы продемонстрировать более сложные правила разрешения:

```ts
@Component({
  selector: 'app-child',
  templateUrl: './child.html',
  styleUrls: ['./child.css'],
  // use the providers array to provide a service
  providers: [{provide: FlowerService, useValue: {emoji: '🌻'}}],
})
export class Child {
  // inject the service
  flower = inject(FlowerService);
}
```

Теперь, когда `FlowerService` предоставлен в декораторе `@Component()`, при запросе сервиса `<app-child>` инжектору достаточно посмотреть на `ElementInjector` в `<app-child>`.
Ему не нужно продолжать поиск дальше по дереву инжекторов.

Следующий шаг — добавить привязку в шаблон `Child`.

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

Чтобы отобразить новые значения, добавьте `<app-child>` в конец шаблона `App`, чтобы представление также показывало подсолнух:

```text
{hideCopy}
Child Component
Emoji from FlowerService: 🌻
```

В логическом дереве это представлено так:

```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>
```

Когда `<app-child>` запрашивает `FlowerService`, инжектор начинает поиск с `<#VIEW>`, принадлежащего `<app-child>` (`<#VIEW>` включён, потому что внедрение идёт из `@Component()`), и заканчивает на `<app-child>`.
В этом случае `FlowerService` разрешается в массиве `providers` с подсолнухом <code>🌻</code> у `<app-child>`.
Инжектору не нужно смотреть дальше по дереву.
Он останавливается, как только находит `FlowerService`, и никогда не видит красный гибискус <code>🌺</code>.

### Использование массива `viewProviders` {#using-the-viewproviders-array}

Массив `viewProviders` — ещё один способ предоставить сервисы в декораторе `@Component()`.
С `viewProviders` сервисы видны в `<#VIEW>`.

HELPFUL: Шаги те же, что и с массивом `providers`, за исключением использования `viewProviders`.

Для пошаговых инструкций продолжайте этот раздел.
Если можете настроить самостоятельно, переходите к [изменению доступности сервисов](#visibility-of-provided-tokens).

Для демонстрации создаём `AnimalService`, чтобы показать `viewProviders`.
Сначала создайте `AnimalService` со свойством `emoji` — кит <code>🐳</code>:

```typescript
import {Service} from '@angular/core';

@Service()
export class AnimalService {
  emoji = '🐳';
}
```

По тому же паттерну, что и с `FlowerService`, внедрите `AnimalService` в классе `App`:

```ts
export class App {
  public flower = inject(FlowerService);
  public animal = inject(AnimalService);
}
```

HELPFUL: Код, связанный с `FlowerService`, можно оставить — он позволит сравнить с `AnimalService`.

Добавьте массив `viewProviders` и внедрите `AnimalService` также в классе `<app-child>`, но дайте `emoji` другое значение.
Здесь это собака 🐶.

```typescript
@Component({
  selector: 'app-child',
  templateUrl: './child.html',
  styleUrls: ['./child.css'],
  // provide services
  providers: [{provide: FlowerService, useValue: {emoji: '🌻'}}],
  viewProviders: [{provide: AnimalService, useValue: {emoji: '🐶'}}],
})
export class Child {
  // inject services
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

Добавьте привязки в шаблоны `Child` и `App`.
В шаблоне `Child`:

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

И то же в шаблоне `App`:

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

В браузере должны быть видны оба значения:

```text
{hideCopy}
App
Emoji from AnimalService: 🐳

Child Component
Emoji from AnimalService: 🐶
```

Логическое дерево для этого примера `viewProviders`:

```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>
```

Как и в примере с `FlowerService`, `AnimalService` предоставлен в декораторе `@Component()` у `<app-child>`.
Это значит, что инжектор сначала смотрит в `ElementInjector` компонента и находит значение `AnimalService` — собака <code>🐶</code>.
Ему не нужно продолжать поиск по дереву `ElementInjector` или в `ModuleInjector`.

### `providers` и `viewProviders` {#providers-vs-viewproviders}

Поле `viewProviders` концептуально похоже на `providers`, но есть важное отличие.
Провайдеры в `viewProviders` видны только внутри собственного представления компонента — контент, спроецированный через `<ng-content>`, их не видит.

Чтобы увидеть разницу между `providers` и `viewProviders`, добавьте ещё один компонент — `Inspector`.
`Inspector` будет потомком `Child`.
В `inspector.ts` внедрите `FlowerService` и `AnimalService` при инициализации свойств:

```typescript
export class Inspector {
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

Массивы `providers` или `viewProviders` не нужны.
Далее в `inspector.html` добавьте ту же разметку, что и в предыдущих компонентах:

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

Не забудьте добавить `Inspector` в массив `imports` у `Child`.

```ts
@Component({
  ...
  imports: [Inspector]
})
```

Далее добавьте в `child.html`:

```html
...

<div class="container">
  <h3>Content projection</h3>
  <ng-content />
</div>
<h3>Inside the view</h3>

<app-inspector />
```

`<ng-content>` позволяет проецировать контент, а `<app-inspector>` внутри шаблона `Child` делает `Inspector` дочерним компонентом `Child`.

Далее добавьте в `app.html`, чтобы использовать проекцию контента:

```html
<app-child>
  <app-inspector />
</app-child>
```

Браузер теперь рендерит следующее (предыдущие примеры опущены для краткости):

```text
{hideCopy}
...
Content projection

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐳

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐶
```

Эти четыре привязки демонстрируют разницу между `providers` и `viewProviders`.
Помните: эмодзи собаки <code>🐶</code> объявлен внутри `<#VIEW>` у `Child` и не виден спроецированному контенту.
Вместо этого спроецированный контент видит кита <code>🐳</code>.

Может возникнуть вопрос, почему спроецированный `<app-inspector>` всё ещё видит <code>🐳</code> из `viewProviders` у `App`.
Причина в том, что Angular DI отслеживает **где компонент был объявлен**, а не где он в итоге отрендерен.
`<app-inspector>` живёт в шаблоне `App` — внутри `<#VIEW>` у `App` — поэтому `viewProviders` у `App` доступны.
Проекция в `Child` отрезает доступ к `viewProviders` у `Child` (<code>🐶</code>), но провайдеры `App` (<code>🐳</code>) по-прежнему достижимы вверх по дереву.

Однако в следующем блоке вывода `Inspector` — настоящий дочерний компонент `Child`, он внутри `<#VIEW>`, поэтому при запросе `AnimalService` видит собаку <code>🐶</code>.

`AnimalService` в логическом дереве выглядел бы так:

```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>
```

Спроецированный `<app-inspector>` получает <code>🐳</code>, потому что <code>🐶</code> принадлежит представлению `Child`, и спроецированный контент до него не дотягивается.
<code>🐳</code> доступен, потому что `<app-inspector>` был объявлен в шаблоне `App` и может подняться к `viewProviders` у `App`.

`<app-inspector>`, живущий напрямую внутри шаблона `Child` (не спроецированный), получает <code>🐶</code> — он внутри `<#VIEW>`, границы пересекать не нужно.

### Видимость предоставленных токенов {#visibility-of-provided-tokens}

Декораторы видимости влияют на то, где начинается и заканчивается поиск injection token в логическом дереве.
Для этого размещайте конфигурацию видимости в точке внедрения — при вызове `inject()`, а не в точке объявления.

Чтобы изменить, где инжектор начинает искать `FlowerService`, добавьте `skipSelf` к вызову `inject()` в `<app-child>`, где внедряется `FlowerService`.
Этот вызов — инициализатор свойства в `<app-child>`, как показано в `child.ts`:

```typescript
flower = inject(FlowerService, {skipSelf: true});
```

С `skipSelf` инжектор `<app-child>` не ищет `FlowerService` у себя.
Вместо этого поиск начинается с `ElementInjector` у `<app-root>`, где ничего нет.
Затем он возвращается к `ModuleInjector` у `<app-child>` и находит значение красного гибискуса <code>🌺</code>, доступное потому что `<app-child>` и `<app-root>` делят один `ModuleInjector`.
UI показывает:

```text
{hideCopy}
Emoji from FlowerService: 🌺
```

В логическом дереве та же идея может выглядеть так:

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
  <app-child @Provide(FlowerService="🌻" )>
    <#VIEW @Inject(FlowerService, SkipSelf)=>"🌺">

</
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

Хотя `<app-child>` предоставляет подсолнух <code>🌻</code>, приложение рендерит красный гибискус <code>🌺</code>, потому что `skipSelf` заставляет текущий инжектор (`app-child`) пропустить себя и смотреть на родителя.

Если теперь добавить `host` (в дополнение к `skipSelf`), результат будет `null`.
Это потому что `host` ограничивает верхнюю границу поиска `<#VIEW>` у `app-child`.
В логическом дереве:

```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>
```

Здесь сервисы и их значения те же, но `host` останавливает инжектор на `<#VIEW>` для `FlowerService`, поэтому он не находит его и возвращает `null`.

### `skipSelf` и `viewProviders` {#skipself-and-viewproviders}

Помните: `<app-child>` предоставляет `AnimalService` в массиве `viewProviders` со значением собака <code>🐶</code>.
Поскольку инжектору достаточно посмотреть на `ElementInjector` у `<app-child>` для `AnimalService`, он никогда не видит кита <code>🐳</code>.

Как в примере с `FlowerService`, если добавить `skipSelf` к `inject()` для `AnimalService`, инжектор не будет искать в `ElementInjector` текущего `<app-child>`.
Вместо этого поиск начнётся с `ElementInjector` у `<app-root>`.

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ],
})
```

Логическое дерево с `skipSelf` в `<app-child>`:

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService, SkipSelf=>"🐳")>

</
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

С `skipSelf` в `<app-child>` инжектор начинает поиск `AnimalService` в `ElementInjector` у `<app-root>` и находит кита 🐳.

### `host` и `viewProviders` {#host-and-viewproviders}

Если использовать только `host` при внедрении `AnimalService`, результат — собака <code>🐶</code>, потому что инжектор находит `AnimalService` в самом `<#VIEW>` у `<app-child>`.
`Child` настраивает `viewProviders` так, что эмодзи собаки предоставляется как значение `AnimalService`.
Также можно увидеть `host` в `inject()`:

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ]
})
export class Child {
  animal = inject(AnimalService, { host: true })
}
```

`host: true` заставляет инжектор искать, пока он не встретит границу `<#VIEW>`.

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    inject(AnimalService, {host: true}=>"🐶")> 
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

Добавьте массив `viewProviders` с третьим животным — ёж <code>🦔</code> — в метаданные `@Component()` у `app.ts`:

```typescript
@Component({
  selector: 'app-root',
  templateUrl: './app.html',
  styleUrls: [ './app.css' ],
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🦔' } },
  ],
})
```

Далее добавьте `skipSelf` вместе с `host` к `inject()` для внедрения `AnimalService` в `child.ts`.
Вот `host` и `skipSelf` в инициализации свойства `animal`:

```typescript
export class Child {
  animal = inject(AnimalService, {host: true, skipSelf: true});
}
```

Когда `host` и `skipSelf` применялись к `FlowerService` в массиве `providers`, результат был `null`, потому что `skipSelf` начинает поиск в инжекторе `<app-child>`, а `host` останавливает поиск на `<#VIEW>` — где нет `FlowerService`.
В логическом дереве видно, что `FlowerService` виден в `<app-child>`, а не в его `<#VIEW>`.

Однако `AnimalService`, предоставленный в массиве `viewProviders` у `App`, виден.

Логическое представление показывает почему:

```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` заставляет инжектор начинать поиск `AnimalService` с `<app-root>`, а не с `<app-child>`, откуда исходит запрос, а `host` останавливает поиск на `<#VIEW>` у `<app-root>`.
Поскольку `AnimalService` предоставлен через массив `viewProviders`, инжектор находит ежа <code>🦔</code> в `<#VIEW>`.

## Пример: сценарии использования `ElementInjector` {#example-elementinjector-use-cases}

Возможность настраивать один или несколько провайдеров на разных уровнях открывает полезные возможности.

### Сценарий: изоляция сервиса {#scenario-service-isolation}

Архитектурные причины могут потребовать ограничить доступ к сервису доменом приложения, которому он принадлежит.
Например, рассмотрим `VillainsList`, отображающий список злодеев.
Он получает злодеев из `VillainsService`.

Если предоставить `VillainsService` в корневом `AppModule`, сервис станет виден везде в приложении.
Если позже изменить `VillainsService`, можно сломать что-то в других компонентах, которые случайно начали от него зависеть.

Вместо этого следует предоставить `VillainsService` в метаданных `providers` у `VillainsList`:

```typescript
@Component({
  selector: 'app-villains-list',
  templateUrl: './villains-list.html',
  providers: [VillainsService],
})
export class VillainsList {}
```

Предоставляя `VillainsService` в метаданных `VillainsList` и нигде больше, сервис становится доступен только в `VillainsList` и его поддереве компонентов.

`VillainsService` — синглтон относительно `VillainsList`, потому что объявлен там.
Пока `VillainsList` не уничтожен, это будет один и тот же экземпляр `VillainsService`, но если экземпляров `VillainsList` несколько, у каждого будет свой экземпляр `VillainsService`.

### Сценарий: несколько сессий редактирования {#scenario-multiple-edit-sessions}

Многие приложения позволяют пользователям работать над несколькими открытыми задачами одновременно.
Например, в приложении для подготовки налоговых деклараций специалист может работать над несколькими декларациями, переключаясь между ними в течение дня.

Чтобы продемонстрировать этот сценарий, представьте `HeroList`, отображающий список супергероев.

Чтобы открыть налоговую декларацию героя, специалист кликает по имени героя, что открывает компонент для редактирования этой декларации.
Каждая выбранная декларация открывается в своём компоненте, и несколько деклараций могут быть открыты одновременно.

У каждого компонента налоговой декларации следующие характеристики:

- Это собственная сессия редактирования декларации
- Можно менять декларацию, не затрагивая декларацию в другом компоненте
- Можно сохранить изменения или отменить их

Предположим, у `HeroTaxReturn` есть логика управления и восстановления изменений.
Для декларации героя это была бы простая задача.
В реальном мире с богатой моделью данных налоговой декларации управление изменениями было бы сложным.
Этим можно делегировать вспомогательному сервису, как в этом примере.

`HeroTaxReturnService` кэширует один `HeroTaxReturn`, отслеживает изменения этой декларации и может сохранить или восстановить её.
Он также делегирует app-wide синглтону `HeroService`, который получает через внедрение.

```typescript
import {inject, Service} from '@angular/core';
import {HeroTaxReturn} from './hero';
import {HeroesService} from './heroes.service';

@Service({autoProvided: false})
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();
  }
}
```

Вот `HeroTaxReturn`, использующий `HeroTaxReturnService`.

```typescript
import {Component, 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.html',
  styleUrls: ['./hero-tax-return.css'],
  providers: [HeroTaxReturnService],
})
export class HeroTaxReturn {
  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);
  }
}
```

_Декларация для редактирования_ приходит через свойство `input`, реализованное геттерами и сеттерами.
Сеттер инициализирует собственный экземпляр `HeroTaxReturnService` компонента входящей декларацией.
Геттер всегда возвращает то, что сервис считает текущим состоянием героя.
Компонент также просит сервис сохранить и восстановить эту декларацию.

Это не сработает, если сервис — app-wide синглтон.
Каждый компонент делил бы один экземпляр сервиса, и каждый перезаписывал бы декларацию другого героя.

Чтобы предотвратить это, настройте инжектор уровня компонента `HeroTaxReturn` для предоставления сервиса через свойство `providers` в метаданных компонента.

```typescript
providers: [HeroTaxReturnService];
```

У `HeroTaxReturn` свой провайдер `HeroTaxReturnService`.
Помните: у каждого _экземпляра_ компонента свой инжектор.
Предоставление сервиса на уровне компонента гарантирует, что _каждый_ экземпляр компонента получает приватный экземпляр сервиса. Так ни одна декларация не будет перезаписана.

HELPFUL: Остальной код сценария опирается на другие возможности и техники Angular, о которых можно узнать в других разделах документации.

### Сценарий: специализированные провайдеры {#scenario-specialized-providers}

Ещё одна причина снова предоставить сервис на другом уровне — подставить _более специализированную_ реализацию этого сервиса глубже в дереве компонентов.

Например, рассмотрим компонент `Car`, который включает информацию об обслуживании шин и зависит от других сервисов для деталей об автомобиле.

Root-инжектор, отмеченный как (A), использует _общие_ провайдеры для деталей о `CarService` и `EngineService`.

1. Компонент `Car` (A). Компонент (A) отображает данные об обслуживании шин и указывает общие сервисы для дополнительной информации об автомобиле.

2. Дочерний компонент (B). Компонент (B) определяет собственные _специализированные_ провайдеры для `CarService` и `EngineService` с особыми возможностями, подходящими для происходящего в компоненте (B).

3. Дочерний компонент (C) как потомок компонента (B). Компонент (C) определяет собственный, ещё _более специализированный_ провайдер для `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
```

За кулисами каждый компонент настраивает свой инжектор с нулём, одним или несколькими провайдерами, определёнными для самого компонента.

Когда вы разрешаете экземпляр `Car` в самом глубоком компоненте (C), его инжектор производит:

- Экземпляр `Car`, разрешённый инжектором (C)
- `Engine`, разрешённый инжектором (B)
- Его `Tires`, разрешённые root-инжектором (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
```

## Ещё о внедрении зависимостей {#more-on-dependency-injection}
# Оптимизация размера клиентского приложения с помощью lightweight injection tokens

На этой странице — концептуальный обзор техники внедрения зависимостей, рекомендуемой разработчикам библиотек.
Проектирование библиотеки с _lightweight injection tokens_ помогает оптимизировать размер бандла клиентских приложений, использующих вашу библиотеку.

Структуру зависимостей между компонентами и injectable-сервисами можно управлять для оптимизации размера бандла с помощью tree-shakable провайдеров.
Обычно это гарантирует: если предоставленный компонент или сервис приложение фактически не использует, компилятор может удалить его код из бандла.

Из-за того, как Angular хранит injection tokens, неиспользуемый компонент или сервис всё же может попасть в бандл.
На этой странице описан паттерн проектирования DI, который обеспечивает корректный tree-shaking за счёт lightweight injection tokens.

Паттерн lightweight injection token особенно важен для авторов библиотек.
Он гарантирует: когда приложение использует лишь часть возможностей библиотеки, неиспользуемый код можно исключить из бандла клиента.

Когда приложение использует вашу библиотеку, часть поставляемых ею сервисов клиент может не применять.
В этом случае разработчик приложения ожидает, что сервис будет tree-shaken и не увеличит размер скомпилированного приложения.
Поскольку разработчик приложения не может знать о проблеме tree-shaking в библиотеке или исправить её, ответственность лежит на авторе библиотеки.
Чтобы неиспользуемые компоненты не удерживались в бандле, библиотека должна использовать паттерн lightweight injection token.

## Когда токены удерживаются {#when-tokens-are-retained}

Чтобы лучше объяснить условие удержания токена, рассмотрим библиотеку с компонентом library-card.
Компонент содержит body и может содержать опциональный header:

```html
<lib-card>
  <lib-header>…</lib-header>
</lib-card>
```

В типичной реализации `<lib-card>` использует `contentChild` или `contentChildren` для получения `<lib-header>` и `<lib-body>`, как ниже:

```ts
{highlight: [14]}
import {Component, contentChild} from '@angular/core';

@Component({
  selector: 'lib-header',
  …,
})
class LibHeader {}

@Component({
  selector: 'lib-card',
  …,
})
class LibCard {
  readonly header = contentChild(LibHeader);
}
```

Поскольку `<lib-header>` опционален, элемент может появиться в шаблоне в минимальной форме `<lib-card />`.
В этом случае `<lib-header>` не используется, и ожидается tree-shaking — но этого не происходит.
Причина в том, что `LibCard` фактически содержит две ссылки на `LibHeader`:

```ts
readonly header = contentChild(LibHeader);
```

- Одна ссылка — в _позиции типа_: она указывает `LibHeader` как тип: `readonly header: Signal<LibHeader|undefined>`.
- Другая — в _позиции значения_: `LibHeader` передаётся в функцию `contentChild`: `contentChild(LibHeader)`.

Компилятор обрабатывает ссылки на токены в этих позициях по-разному:

- Ссылки в _позиции типа_ стираются после преобразования из TypeScript и не влияют на tree-shaking.
- Ссылки в _позиции значения_ компилятор обязан сохранить в runtime, что **мешает** tree-shaking компонента.

В примере компилятор удерживает токен `LibHeader` из позиции значения.
Это мешает tree-shaking ссылаемого компонента, даже если приложение нигде не использует `<lib-header>`.
Если код, шаблон и стили `LibHeader` вместе становятся слишком большими, ненужное включение заметно увеличивает размер клиентского приложения.

## Когда использовать паттерн lightweight injection token {#when-to-use-the-lightweight-injection-token-pattern}

Проблема tree-shaking возникает, когда компонент используется как injection token.
Это возможно в двух случаях:

- Токен используется в позиции значения [content query](guide/components/queries#content-queries).
- Токен используется с функцией `inject`.

В следующем примере оба использования токена `CustomOther` удерживают `CustomOther` и мешают tree-shaking, когда он не используется:

```ts
{highlight: [[2],[4]]}
class App {
  private readonly other = inject(CustomOther, {optional: true});

readonly header = contentChild(CustomOther);
}
```

Хотя токены, используемые только как спецификаторы типов, удаляются при преобразовании в JavaScript, все токены для внедрения зависимостей нужны в runtime.
При `inject(CustomOther)` `CustomOther` передаётся как аргумент-значение.
Токен оказывается в позиции значения, и tree-shaker сохраняет ссылку.

HELPFUL: Библиотекам следует использовать [tree-shakable провайдеры](guide/di/defining-dependency-providers) для всех сервисов, предоставляя зависимости на уровне root, а не в компонентах или модулях.

## Использование lightweight injection tokens {#using-lightweight-injection-tokens}

Паттерн lightweight injection token состоит в использовании небольшого абстрактного класса как injection token и предоставлении реальной реализации позже.
Абстрактный класс удерживается (не tree-shaken), но он мал и существенно не влияет на размер приложения.

Следующий пример показывает, как это работает для `LibHeader`:

```ts
{highlight: [[1],[5], [15]]}
abstract class LibHeaderToken {}

@Component({
  selector: 'lib-header',
  providers: [{provide: LibHeaderToken, useExisting: LibHeader}],
  …,
})
class LibHeader extends LibHeaderToken {}

@Component({
  selector: 'lib-card',
  …,
})
class LibCard {
  readonly header = contentChild(LibHeaderToken);
}
```

В этом примере реализация `LibCard` больше не ссылается на `LibHeader` ни в позиции типа, ни в позиции значения.
Это позволяет полностью tree-shake'ить `LibHeader`.
`LibHeaderToken` удерживается, но это лишь объявление класса без конкретной реализации.
Он мал и после компиляции существенно не влияет на размер приложения.

Вместо этого сам `LibHeader` реализует абстрактный класс `LibHeaderToken`.
Этот токен можно безопасно использовать как провайдер в определении компонента, позволяя Angular корректно внедрять конкретный тип.

Итого, паттерн lightweight injection token включает:

1. Lightweight injection token в виде абстрактного класса.
2. Определение компонента, реализующего абстрактный класс.
3. Внедрение по lightweight-паттерну через `contentChild` или `contentChildren`.
4. Провайдер в реализации, связывающий lightweight injection token с реализацией.

### Использование lightweight injection token для определения API {#use-the-lightweight-injection-token-for-api-definition}

Компоненту, внедряющему lightweight injection token, может понадобиться вызвать метод внедрённого класса.
Токен теперь — абстрактный класс. Поскольку injectable-компонент его реализует, в абстрактном классе токена нужно объявить и абстрактный метод.
Реализация метода со всем кодом остаётся в injectable-компоненте, который можно tree-shake'ить.
Так родитель может типобезопасно общаться с дочерним элементом, если он присутствует.

Например, `LibCard` теперь запрашивает `LibHeaderToken`, а не `LibHeader`.
Следующий пример показывает, как паттерн позволяет `LibCard` общаться с `LibHeader`, не ссылаясь на `LibHeader` напрямую:

```ts
{highlight: [[2],[7],[11],[19]]}
abstract class LibHeaderToken {
  abstract doSomething(): void;
}

@Component({
  selector: 'lib-header',
  providers: [{provide: LibHeaderToken, useExisting: LibHeader}],
})
class LibHeader extends LibHeaderToken {
  doSomething(): void {
    // Concrete implementation of `doSomething`
  }
}

@Component({
  selector: 'lib-card',
})
class LibCard implements AfterContentInit {
  readonly header = contentChild(LibHeaderToken);

ngAfterContentInit(): void {
    if (this.header() !== undefined) {
      this.header()!.doSomething();
    }
  }
}
```

В этом примере родитель запрашивает токен, чтобы получить дочерний компонент, и сохраняет ссылку, если он есть.
Перед вызовом метода у дочернего элемента родитель проверяет его наличие.
Если дочерний компонент был tree-shaken, в runtime на него нет ссылки и вызова его метода нет.

### Именование lightweight injection token {#naming-your-lightweight-injection-token}

Lightweight injection tokens полезны только с компонентами.
[Руководство по стилю Angular](style-guide) рекомендует именовать компоненты без суффикса `Component`.
Пример `LibHeader` следует этому соглашению.

Нужно сохранять связь между компонентом и его токеном, при этом различая их.
Рекомендуемый стиль — базовое имя компонента с суффиксом `Token`: `LibHeaderToken`.
# RxJS interop с сигналами Angular

Пакет `@angular/core/rxjs-interop` предлагает API, помогающие интегрировать RxJS и сигналы Angular.

## Создание сигнала из RxJS Observable с `toSignal` {#create-a-signal-from-an-rxjs-observable-with-tosignal}

Используйте функцию `toSignal`, чтобы создать сигнал, отслеживающий значение Observable. Поведение похоже на pipe `async` в шаблонах, но гибче и доступно в любой части приложения.

```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});
}
```

Как и pipe `async`, `toSignal` сразу подписывается на Observable, что может вызвать побочные эффекты. Подписка, созданная `toSignal`, автоматически отписывается от Observable при уничтожении компонента или сервиса, вызвавшего `toSignal`.

IMPORTANT: `toSignal` создаёт подписку. Избегайте повторных вызовов для одного и того же Observable — переиспользуйте возвращаемый сигнал.

### Контекст внедрения {#injection-context}

По умолчанию `toSignal` нужно запускать в [контексте внедрения](guide/di/dependency-injection-context), например при создании компонента или сервиса. Если контекст недоступен, можно вручную указать `Injector`.

### Начальные значения {#initial-values}

Observable может не выдать значение синхронно при подписке, а сигналы всегда требуют текущего значения. Есть несколько способов обработать «начальное» значение сигналов `toSignal`.

#### Опция `initialValue` {#the-initialvalue-option}

Как в примере выше, можно указать опцию `initialValue` — значение, которое сигнал вернёт до первого эмита Observable.

#### Начальные значения `undefined` {#undefined-initial-values}

Если `initialValue` не задан, результирующий сигнал будет возвращать `undefined`, пока Observable не эмитит. Это похоже на поведение pipe `async`, возвращающего `null`.

#### Опция `requireSync` {#the-requiresync-option}

Некоторые Observable гарантированно эмитят синхронно, например `BehaviorSubject`. В таких случаях можно указать `requireSync: true`.

Когда `requireSync` равен `true`, `toSignal` требует, чтобы Observable эмитил синхронно при подписке. Это гарантирует, что у сигнала всегда есть значение, и тип `undefined` или начальное значение не нужны.

### `manualCleanup` {#manualcleanup}

По умолчанию `toSignal` автоматически отписывается от Observable при уничтожении создавшего его компонента или сервиса.

Чтобы переопределить это поведение, передайте опцию `manualCleanup`. Её можно использовать для Observable, которые завершаются сами.

#### Пользовательское сравнение равенства {#custom-equality-comparison}

Некоторые Observable могут эмитить значения, которые **равны**, даже если отличаются по ссылке или мелким деталям. Опция `equal` позволяет задать **пользовательскую функцию равенства**, определяющую, когда два последовательных значения считаются одинаковыми.

Когда два эмитированных значения считаются равными, результирующий сигнал **не обновляется**. Это предотвращает лишние вычисления, обновления DOM или повторный запуск эффектов.

```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,
  });
}
```

### Ошибки и завершение {#error-and-completion}

Если Observable, используемый в `toSignal`, выдаёт ошибку, она выбрасывается при чтении сигнала.

Если Observable, используемый в `toSignal`, завершается, сигнал продолжает возвращать последнее эмитированное до завершения значение.

## Создание RxJS Observable из сигнала с `toObservable` {#create-an-rxjs-observable-from-a-signal-with-toobservable}

Утилита `toObservable` создаёт `Observable`, отслеживающий значение сигнала. Значение сигнала мониторится через `effect`, который эмитит в Observable при изменении.

```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)));
}
```

При изменении сигнала `query` Observable `query$` эмитит последний запрос и запускает новый HTTP-запрос.

### Контекст внедрения {#injection-context-1}

По умолчанию `toObservable` нужно запускать в [контексте внедрения](guide/di/dependency-injection-context), например при создании компонента или сервиса. Если контекст недоступен, можно вручную указать `Injector`.

### Тайминг `toObservable` {#timing-of-toobservable}

`toObservable` использует эффект для отслеживания значения сигнала в `ReplaySubject`. При подписке первое значение (если есть) может быть эмитировано синхронно, все последующие — асинхронно.

В отличие от Observable, сигналы никогда не дают синхронного уведомления об изменениях. Даже если обновить значение сигнала несколько раз, `toObservable` эмитит значение только после стабилизации сигнала.

```ts
const obs$ = toObservable(mySignal);
obs$.subscribe((value) => console.log(value));

mySignal.set(1);
mySignal.set(2);
mySignal.set(3);
```

Здесь будет залогировано только последнее значение (3).

## Использование `rxResource` для асинхронных данных {#using-rxresource-for-async-data}

Функция Angular [`resource`](/guide/signals/resource) позволяет включать асинхронные данные в код приложения на сигналах. На базе этого паттерна `rxResource` даёт определить resource, источник данных которого задан через RxJS `Observable`. Вместо функции `loader` `rxResource` принимает функцию `stream`, возвращающую RxJS `Observable`.

```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),
  });
}
```

Свойство `stream` принимает фабричную функцию для RxJS `Observable`. Ей передаётся значение `params` resource, и она возвращает `Observable`. Resource вызывает эту фабрику каждый раз, когда вычисление `params` даёт новое значение. Подробнее о параметрах фабрики — в [Resource loaders](/guide/signals/resource#resource-loaders).

Во всём остальном `rxResource` ведёт себя как `resource` и предоставляет те же API для параметров, чтения значений, проверки состояния загрузки и ошибок.
# RxJS interop с output компонентов и директив

TIP: Это руководство предполагает знакомство с [output компонентов и директив](guide/components/outputs).

Пакет `@angular/rxjs-interop` предлагает два API, связанных с output компонентов и директив.

## Создание output на основе RxJS Observable {#creating-an-output-based-on-an-rxjs-observable}

`outputFromObservable` позволяет создать output компонента или директивы, который эмитит на основе RxJS Observable:

```ts
{highlight:[11]}
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$);
}
```

Функция `outputFromObservable` имеет особое значение для компилятора Angular. **Вызывать `outputFromObservable` можно только в инициализаторах свойств компонентов и директив.**

Когда вы `subscribe` на output, Angular автоматически пробрасывает подписку в нижележащий Observable. Angular прекращает проброс значений при уничтожении компонента или директивы.

HELPFUL: Если значения можно эмитить императивно, рассмотрите прямое использование `output()`.

## Создание RxJS Observable из output компонента или директивы {#creating-an-rxjs-observable-from-a-component-or-directive-output}

Функция `outputToObservable` позволяет создать RxJS Observable из output компонента.

```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(...);
```

HELPFUL: Если метод `subscribe` на `OutputRef` покрывает ваши нужды, рассмотрите его прямое использование.
# Настройка `HttpClient`

`HttpClient` доступен для внедрения по умолчанию в Angular v21 и новее.

## Предоставление `HttpClient` через внедрение зависимостей {#providing-httpclient-through-dependency-injection}

Вспомогательную функцию `provideHttpClient` можно использовать для настройки набора HTTP-возможностей по умолчанию или добавления возможностей в `providers` приложения в `app.config.ts`.

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(/* add features here, such as withInterceptors(...) */)],
};
```

Если приложение использует bootstrap на основе NgModule, включите `provideHttpClient` в providers NgModule приложения, чтобы настроить набор HTTP-возможностей по умолчанию или добавить возможности:

```ts
@NgModule({
  providers: [provideHttpClient(/* add features here, such as withInterceptors(...) */)],
  // ... other application configuration
})
export class AppModule {}
```

Затем можно внедрить сервис `HttpClient` как зависимость компонентов, сервисов или других классов:

```ts
@Service()
export class ConfigService {
  private http = inject(HttpClient);
  // This service can now make HTTP requests via `this.http`.
}
```

## Настройка возможностей `HttpClient` {#configuring-features-of-httpclient}

`provideHttpClient` принимает список опциональных конфигураций возможностей для включения или настройки разных аспектов клиента. В этом разделе описаны опциональные возможности и их использование.

### `withXhr` {#withxhr}

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withXhr())],
};
```

По умолчанию `HttpClient` использует API [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) для запросов. Возможность `withXhr` переключает клиент на API [`XMLHttpRequest`](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest).

`fetch` — более современный API и доступен в некоторых окружениях, где `XMLHttpRequest` не поддерживается. У него есть ограничения, например отсутствие событий прогресса загрузки (upload).
Поддержка XHR на сервере **устарела** и планируется к удалению в Angular 23. Лежащая в основе библиотека `xhr2` небезопасно обрабатывает редиректы: она может пересылать заголовки `Authorization` при cross-origin редиректах и уязвима к denial-of-service (DoS) через циклы редиректов. Для SSR-приложений используйте backend `fetch` по умолчанию.
### `withInterceptors(...)` {#withinterceptors}

`withInterceptors` настраивает набор функций-interceptor'ов, которые будут обрабатывать запросы через `HttpClient`. Подробнее см. [руководство по interceptor'ам](guide/http/interceptors).

### `withInterceptorsFromDi()` {#withinterceptorsfromdi}

`withInterceptorsFromDi` включает более старый стиль классовых interceptor'ов в конфигурацию `HttpClient`. Подробнее см. [руководство по interceptor'ам](guide/http/interceptors).

HELPFUL: Функциональные interceptor'ы (через `withInterceptors`) имеют более предсказуемый порядок, и мы рекомендуем их вместо interceptor'ов на основе DI.

### `withRequestsMadeViaParent()` {#withrequestsmadeviaparent}

По умолчанию, когда вы настраиваете `HttpClient` через `provideHttpClient` в данном инжекторе, эта конфигурация переопределяет любую конфигурацию `HttpClient`, которая может быть в родительском инжекторе.

При добавлении `withRequestsMadeViaParent()` `HttpClient` настраивается так, чтобы передавать запросы вверх экземпляру `HttpClient` в родительском инжекторе после прохождения через interceptor'ы, настроенные на этом уровне. Это полезно, если нужно _добавить_ interceptor'ы в дочернем инжекторе, продолжая отправлять запрос через interceptor'ы родительского инжектора.

CRITICAL: Над текущим инжектором должен быть настроен экземпляр `HttpClient`, иначе эта опция недопустима и при попытке использования вы получите runtime-ошибку.

### `withJsonpSupport()` {#withjsonpsupport}

Включение `withJsonpSupport` включает метод `.jsonp()` у `HttpClient`, который делает GET-запрос через [соглашение JSONP](https://en.wikipedia.org/wiki/JSONP) для кросс-доменной загрузки данных.

HELPFUL: По возможности предпочитайте [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) для кросс-доменных запросов вместо JSONP.

### `withXsrfConfiguration(...)` {#withxsrfconfiguration}

Эта опция позволяет настроить встроенную XSRF-защиту `HttpClient`. Подробнее см. [руководство по безопасности](best-practices/security).

### `withNoXsrfProtection()` {#withnoxsrfprotection}

Эта опция отключает встроенную XSRF-защиту `HttpClient`. Подробнее см. [руководство по безопасности](best-practices/security).

## Конфигурация на основе `HttpClientModule` {#httpclientmodule-based-configuration}

Некоторые приложения могут настраивать `HttpClient` через более старый API на основе NgModules.

В таблице перечислены NgModules из `@angular/common/http` и их соответствие функциям конфигурации провайдеров выше.

| **NgModule**                            | Эквивалент `provideHttpClient()`                         |
| --------------------------------------- | -------------------------------------------------------- |
| `HttpClientModule`                      | `provideHttpClient(withInterceptorsFromDi(), withXhr())` |
| `HttpClientJsonpModule`                 | `withJsonpSupport()`                                     |
| `HttpClientXsrfModule.withOptions(...)` | `withXsrfConfiguration(...)`                             |
| `HttpClientXsrfModule.disable()`        | `withNoXsrfProtection()`                                 |
Когда `HttpClientModule` присутствует в нескольких инжекторах, поведение interceptor'ов плохо определено и зависит от точных опций и порядка providers/imports.

Для конфигураций с несколькими инжекторами предпочитайте `provideHttpClient` — у него более стабильное поведение. См. возможность `withRequestsMadeViaParent` выше.

# Выполнение HTTP-запросов

У `HttpClient` есть методы, соответствующие разным HTTP-глаголам, используемым для запросов — как для загрузки данных, так и для мутаций на сервере. Каждый метод возвращает [RxJS `Observable`](https://rxjs.dev/guide/observable), который при подписке отправляет запрос, а затем испускает результаты, когда сервер отвечает.

NOTE: На `Observable`, созданные `HttpClient`, можно подписаться любое число раз, и для каждой подписки будет выполнен новый backend-запрос.

Через объект options, передаваемый методу запроса, можно настроить различные свойства запроса и тип возвращаемого ответа.

## Получение JSON-данных {#fetching-json-data}

Получение данных с backend часто требует GET-запроса методом [`HttpClient.get()`](api/common/http/HttpClient#get). Этот метод принимает два аргумента: строковый URL endpoint, с которого нужно получить данные, и _необязательный объект options_ для настройки запроса.

Например, чтобы получить конфигурационные данные из гипотетического API методом `HttpClient.get()`:

```ts
http.get<Config>('/api/config').subscribe((config) => {
  // process the configuration.
});
```

Обратите внимание на generic type argument, который указывает, что данные, возвращаемые сервером, будут типа `Config`. Этот аргумент необязателен: если его опустить, возвращаемые данные будут иметь тип `Object`.

TIP: При работе с данными неопределённой структуры и возможными значениями `undefined` или `null` рассмотрите использование типа `unknown` вместо `Object` в качестве типа ответа.

CRITICAL: Generic type методов запроса — это **утверждение** о данных, возвращаемых сервером. `HttpClient` не проверяет, что фактические возвращаемые данные соответствуют этому типу.

## Получение других типов данных {#fetching-other-types-of-data}

По умолчанию `HttpClient` предполагает, что серверы возвращают JSON-данные. При взаимодействии с не-JSON API можно указать `HttpClient`, какой тип ответа ожидать при запросе. Это делается опцией `responseType`.

| **Значение `responseType`** | **Тип возвращаемого ответа**                                                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `'json'` (по умолчанию)       | JSON-данные заданного generic type                                                                                                       |
| `'text'`                 | строковые данные                                                                                                                               |
| `'arraybuffer'`          | [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) с сырыми байтами ответа |
| `'blob'`                 | экземпляр [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob)                                                                        |

Например, можно попросить `HttpClient` загрузить сырые байты изображения `.jpeg` в `ArrayBuffer`:

```ts
http.get('/images/dog.jpg', {responseType: 'arraybuffer'}).subscribe((buffer) => {
  console.log('The image is ' + buffer.byteLength + ' bytes large');
});
```
Поскольку значение `responseType` влияет на тип, возвращаемый `HttpClient`, оно должно иметь literal type, а не тип `string`.

Это происходит автоматически, если объект options, переданный методу запроса, — литеральный объект, но если вы выносите options запроса в переменную или helper-метод, может потребоваться явно указать его как литерал, например `responseType: 'text' as const`.
## Изменение состояния сервера {#mutating-server-state}

Server API, выполняющие мутации, часто требуют POST-запросов с телом запроса, указывающим новое состояние или изменение.

Метод [`HttpClient.post()`](api/common/http/HttpClient#post) ведёт себя аналогично `get()` и принимает дополнительный аргумент `body` перед options:

```ts
http.post<Config>('/api/config', newConfig).subscribe((config) => {
  console.log('Updated config:', config);
});
```

В качестве `body` запроса можно передать много разных типов значений, и `HttpClient` сериализует их соответствующим образом:

| **Тип `body`**                                                                                                               | **Сериализуется как**                                    |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| string                                                                                                                        | Plain text                                           |
| number, boolean, array или plain object                                                                                       | JSON                                                 |
| [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)                       | сырые данные из буфера                             |
| [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob)                                                                     | сырые данные с content type `Blob`              |
| [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData)                                                             | данные в кодировке `multipart/form-data`                   |
| [`HttpParams`](api/common/http/HttpParams) или [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) | строка в формате `application/x-www-form-urlencoded` |

IMPORTANT: Не забывайте вызывать `.subscribe()` на `Observable` мутирующих запросов, чтобы запрос действительно выполнился.

## Задание URL-параметров {#setting-url-parameters}

Укажите параметры запроса, которые должны быть включены в URL запроса, с помощью опции `params`.

Передача object literal — самый простой способ настроить URL-параметры:

```ts
http
  .get('/api/config', {
    params: {filter: 'all'},
  })
  .subscribe((config) => {
    // ...
  });
```

Либо передайте экземпляр `HttpParams`, если нужен больший контроль над построением или сериализацией параметров.

IMPORTANT: Экземпляры `HttpParams` _неизменяемы_ и не могут быть изменены напрямую. Вместо этого методы мутации, такие как `append()`, возвращают новый экземпляр `HttpParams` с применённой мутацией.

```ts
const baseParams = new HttpParams().set('filter', 'all');

http
  .get('/api/config', {
    params: baseParams.set('details', 'enabled'),
  })
  .subscribe((config) => {
    // ...
  });
```

Можно создать `HttpParams` с пользовательским `HttpParameterCodec`, который определяет, как `HttpClient` будет кодировать параметры в URL.

### Пользовательское кодирование параметров {#custom-parameter-encoding}

По умолчанию `HttpParams` использует встроенный [`HttpUrlEncodingCodec`](api/common/http/HttpUrlEncodingCodec) для кодирования и декодирования ключей и значений параметров.

Можно предоставить собственную реализацию [`HttpParameterCodec`](api/common/http/HttpParameterCodec), чтобы настроить, как применяются кодирование и декодирование.

```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});
  }
}
```

## Задание заголовков запроса {#setting-request-headers}

Укажите заголовки запроса, которые должны быть включены в запрос, с помощью опции `headers`.

Передача object literal — самый простой способ настроить заголовки запроса:

```ts
http
  .get('/api/config', {
    headers: {
      'X-Debug-Level': 'verbose',
    },
  })
  .subscribe((config) => {
    // ...
  });
```

Либо передайте экземпляр `HttpHeaders`, если нужен больший контроль над построением заголовков.

IMPORTANT: Экземпляры `HttpHeaders` _неизменяемы_ и не могут быть изменены напрямую. Вместо этого методы мутации, такие как `append()`, возвращают новый экземпляр `HttpHeaders` с применённой мутацией.

```ts
const baseHeaders = new HttpHeaders().set('X-Debug-Level', 'minimal');

http
  .get<Config>('/api/config', {
    headers: baseHeaders.set('X-Debug-Level', 'verbose'),
  })
  .subscribe((config) => {
    // ...
  });
```

## Взаимодействие с событиями ответа сервера {#interacting-with-the-server-response-events}

Для удобства `HttpClient` по умолчанию возвращает `Observable` данных, возвращённых сервером (тело ответа). Иногда желательно изучить сам ответ, например чтобы получить конкретные заголовки ответа.

Чтобы получить доступ ко всему ответу, установите опцию `observe` в `'response'`:

```ts
http.get<Config>('/api/config', {observe: 'response'}).subscribe((res) => {
  console.log('Response status:', res.status);
  console.log('Body:', res.body);
});
```
Поскольку значение `observe` влияет на тип, возвращаемый `HttpClient`, оно должно иметь literal type, а не тип `string`.

Это происходит автоматически, если объект options, переданный методу запроса, — литеральный объект, но если вы выносите options запроса в переменную или helper-метод, может потребоваться явно указать его как литерал, например `observe: 'response' as const`.
## Получение сырых событий прогресса {#receiving-raw-progress-events}

Помимо тела ответа или объекта ответа, `HttpClient` также может возвращать поток сырых _событий_, соответствующих конкретным моментам жизненного цикла запроса. Эти события включают момент отправки запроса, возврата заголовка ответа и завершения тела. Эти события также могут включать _события прогресса_, сообщающие о статусе загрузки и скачивания для больших тел запроса или ответа.

События прогресса по умолчанию отключены (так как имеют стоимость производительности), но их можно включить опцией `reportProgress`.

NOTE: Backend fetch по умолчанию у `HttpClient` не сообщает о событиях прогресса _загрузки_ (upload). Если приложению нужны события прогресса загрузки, настройте `HttpClient` с `withXhr()` в `provideHttpClient(...)`.

Чтобы наблюдать поток событий, установите опцию `observe` в `'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;
    }
  });
```
Поскольку значение `observe` влияет на тип, возвращаемый `HttpClient`, оно должно иметь literal type, а не тип `string`.

Это происходит автоматически, если объект options, переданный методу запроса, — литеральный объект, но если вы выносите options запроса в переменную или helper-метод, может потребоваться явно указать его как литерал, например `observe: 'events' as const`.
Каждое `HttpEvent` в потоке событий имеет `type`, который различает, что представляет событие:

| **Значение `type`**                 | **Значение события**                                                                  |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| `HttpEventType.Sent`             | Запрос отправлен на сервер                                      |
| `HttpEventType.UploadProgress`   | `HttpUploadProgressEvent`, сообщающий о прогрессе загрузки тела запроса      |
| `HttpEventType.ResponseHeader`   | Получена голова ответа, включая статус и заголовки           |
| `HttpEventType.DownloadProgress` | `HttpDownloadProgressEvent`, сообщающий о прогрессе скачивания тела ответа |
| `HttpEventType.Response`         | Получен весь ответ, включая тело ответа                 |
| `HttpEventType.User`             | Пользовательское событие от HTTP interceptor.                                           |

## Обработка сбоев запроса {#handling-request-failure}

Есть три способа, которыми HTTP-запрос может завершиться неудачей:

- Сетевая ошибка или ошибка соединения может помешать запросу достичь backend-сервера.
- Запрос не ответил вовремя, когда была задана опция timeout.
- Backend может получить запрос, но не обработать его и вернуть ответ с ошибкой.

`HttpClient` захватывает все перечисленные виды ошибок в `HttpErrorResponse`, который возвращает через канал ошибок `Observable`. Сетевые ошибки и ошибки timeout имеют код `status` `0` и `error`, который является экземпляром [`ProgressEvent`](https://developer.mozilla.org/docs/Web/API/ProgressEvent). Ошибки backend имеют код `status` сбоя, возвращённый backend, и ответ с ошибкой в качестве `error`. Изучите ответ, чтобы определить причину ошибки и подходящее действие для её обработки.

[Библиотека RxJS](https://rxjs.dev/) предлагает несколько операторов, полезных для обработки ошибок.

Можно использовать оператор `catchError`, чтобы преобразовать ответ с ошибкой в значение для UI. Это значение может указать UI отобразить страницу или значение ошибки и при необходимости зафиксировать причину ошибки.

Иногда временные ошибки, такие как сетевые прерывания, могут неожиданно привести к сбою запроса, и простой повтор запроса позволит ему успешно выполниться. RxJS предоставляет несколько операторов _retry_, которые автоматически повторно подписываются на неудачный `Observable` при определённых условиях. Например, оператор `retry()` автоматически попытается повторно подписаться указанное число раз.

### Timeouts {#timeouts}

Чтобы задать timeout для запроса, можно установить опцию `timeout` в число миллисекунд вместе с другими options запроса. Если backend-запрос не завершится за указанное время, запрос будет прерван и будет испущена ошибка.

NOTE: Timeout применяется только к самому backend HTTP-запросу. Это не timeout для всей цепочки обработки запроса. Поэтому на эту опцию не влияют задержки, вносимые 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.
    },
  });
```

## Расширенные опции fetch {#advanced-fetch-options}

`HttpClient` Angular поддерживает расширенные опции Fetch API, которые могут улучшить производительность и пользовательский опыт. Эти опции доступны при использовании fetch backend, который используется по умолчанию.

### Опции fetch {#fetch-options}

Следующие опции дают тонкий контроль над поведением запроса при использовании fetch backend.

#### Keep-alive соединения {#keep-alive-connections}

Опция `keepalive` позволяет запросу пережить страницу, которая его инициировала. Это особенно полезно для запросов аналитики или логирования, которые должны завершиться, даже если пользователь уходит со страницы.

```ts
http
  .post('/api/analytics', analyticsData, {
    keepalive: true,
  })
  .subscribe();
```

#### Управление HTTP-кэшированием {#http-caching-control}

Опция `cache` управляет тем, как запрос взаимодействует с HTTP-кэшем браузера, что может значительно улучшить производительность повторных запросов.

```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) => {
    // ...
  });
```

#### Приоритет запроса для Core Web Vitals {#request-priority-for-core-web-vitals}

Опция `priority` позволяет указать относительную важность запроса, помогая браузерам оптимизировать загрузку ресурсов для лучших показателей 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) => {
    // ...
  });
```

Доступные значения `priority`:

- `'high'`: Высокий приоритет, загружается рано (например, критичные данные пользователя, контент above-the-fold)
- `'low'`: Низкий приоритет, загружается, когда ресурсы доступны (например, аналитика, prefetch-данные)
- `'auto'`: Браузер определяет приоритет на основе контекста запроса (по умолчанию)

TIP: Используйте `priority: 'high'` для запросов, влияющих на Largest Contentful Paint (LCP), и `priority: 'low'` для запросов, не влияющих на начальный пользовательский опыт.

#### Режим запроса {#request-mode}

Опция `mode` управляет тем, как запрос обрабатывает cross-origin запросы, и определяет тип ответа.

```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) => {
    // ...
  });
```

Доступные значения `mode`:

- `'same-origin'`: Разрешать только same-origin запросы, завершать неудачей cross-origin запросы
- `'cors'`: Разрешать cross-origin запросы с CORS (по умолчанию)
- `'no-cors'`: Разрешать простые cross-origin запросы без CORS, ответ opaque

TIP: Используйте `mode: 'same-origin'` для чувствительных запросов, которые никогда не должны уходить cross-origin.

#### Обработка редиректов {#redirect-handling}

Опция `redirect` указывает, как обрабатывать ответы с редиректом от сервера.

```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
    },
  });
```

Доступные значения `redirect`:

- `'follow'`: Автоматически следовать редиректам (по умолчанию)
- `'error'`: Считать редиректы ошибками
- `'manual'`: Не следовать редиректам автоматически, вернуть ответ редиректа

TIP: Используйте `redirect: 'manual'`, когда нужно обрабатывать редиректы с пользовательской логикой.

#### Обработка credentials {#credentials-handling}

Опция `credentials` управляет тем, отправляются ли cookies, authorization headers и другие credentials с cross-origin запросами. Это особенно важно для сценариев аутентификации.

```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: Опция `withCredentials` имеет приоритет над опцией `credentials`. Если указаны обе, `withCredentials: true` всегда приведёт к `credentials: 'include'`, независимо от явного значения `credentials`.

Доступные значения `credentials`:

- `'omit'`: Никогда не отправлять credentials
- `'same-origin'`: Отправлять credentials только для same-origin запросов (по умолчанию)
- `'include'`: Всегда отправлять credentials, даже для cross-origin запросов

TIP: Используйте `credentials: 'include'`, когда нужно отправить authentication cookies или headers на другой домен, поддерживающий CORS. Избегайте смешивания опций `credentials` и `withCredentials`, чтобы не путаться.

#### Referrer {#referrer}

Опция `referrer` позволяет управлять тем, какая информация о referrer отправляется с запросом. Это важно для соображений приватности и безопасности.

```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) => {
    // ...
  });
```

Опция `referrer` принимает:

- Валидную строку URL: задаёт конкретный URL referrer для отправки
- Пустую строку `''`: не отправляет информацию о referrer
- `'about:client'`: использует referrer по умолчанию (URL текущей страницы)

TIP: Используйте `referrer: ''` для чувствительных запросов, где не хотите раскрывать URL страницы-источника.

#### Политика referrer {#referrer-policy}

Опция `referrerPolicy` управляет тем, сколько информации о referrer — URL страницы, выполняющей запрос — отправляется вместе с HTTP-запросом. Этот параметр влияет и на приватность, и на аналитику, позволяя балансировать видимость данных с соображениями безопасности.

```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();
```

Опция `referrerPolicy` принимает:

- `'no-referrer'` Никогда не отправлять заголовок `Referer`.
- `'no-referrer-when-downgrade'` Отправляет referrer для same-origin и безопасных (HTTPS→HTTPS) запросов, но опускает его при переходе с безопасного на менее безопасный origin (HTTPS→HTTP).
- `'origin'` Отправляет только origin (scheme, host, port) referrer, опуская path и query.
- `'origin-when-cross-origin'` Отправляет полный URL для same-origin запросов, но только origin для cross-origin запросов.
- `'same-origin'` Отправляет полный URL для same-origin запросов и не отправляет referrer для cross-origin запросов.
- `'strict-origin'` Отправляет только origin, и только если уровень безопасности протокола не понижен (например, HTTPS→HTTPS). Опускает referrer при понижении.
- `'strict-origin-when-cross-origin'` Поведение браузера по умолчанию. Отправляет полный URL для same-origin запросов, origin для cross-origin запросов без понижения, и опускает referrer при понижении.
- `'unsafe-url'` Всегда отправляет полный URL (включая path и query). Это может раскрыть чувствительные данные и должно использоваться с осторожностью.

TIP: Для запросов, чувствительных к приватности, предпочитайте консервативные значения, такие как `'no-referrer'`, `'origin'` или `'strict-origin-when-cross-origin'`.

#### Integrity {#integrity}

Опция `integrity` позволяет проверить, что ответ не был изменён, предоставив криптографический хеш ожидаемого содержимого. Это особенно полезно при загрузке скриптов или других ресурсов с CDN.

```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: Опция `integrity` требует точного совпадения между содержимым ответа и предоставленным хешем. Если содержимое не совпадает, запрос завершится сетевой ошибкой.

TIP: Используйте subresource integrity при загрузке критичных ресурсов из внешних источников, чтобы убедиться, что они не были изменены. Генерируйте хеши с помощью инструментов вроде `openssl`.

## HTTP `Observable` {#http-observables}

Каждый метод запроса на `HttpClient` создаёт и возвращает `Observable` запрошенного типа ответа. Понимание того, как работают эти `Observable`, важно при использовании `HttpClient`.

`HttpClient` создаёт то, что RxJS называет «холодными» `Observable`: фактический запрос не происходит, пока на `Observable` не подписались. Только тогда запрос действительно отправляется на сервер. Подписка на один и тот же `Observable` несколько раз вызовет несколько backend-запросов. Каждая подписка независима.

TIP: Можно думать об `Observable` `HttpClient` как о _чертежах_ фактических серверных запросов.

После подписки отписка прервёт выполняющийся запрос. Это очень полезно, если на `Observable` подписались через pipe `async`, так как запрос автоматически отменится, если пользователь уйдёт с текущей страницы. Кроме того, если использовать `Observable` с RxJS-комбинатором вроде `switchMap`, эта отмена очистит устаревшие запросы.

После возврата ответа `Observable` от `HttpClient` обычно завершаются (хотя interceptors могут на это влиять).

Из-за автоматического завершения обычно нет риска утечек памяти, если подписки `HttpClient` не очищены. Однако, как и с любой асинхронной операцией, настоятельно рекомендуется очищать подписки при уничтожении использующего их компонента, иначе callback подписки может выполниться и столкнуться с ошибками при попытке взаимодействовать с уничтоженным компонентом.

TIP: Использование pipe `async` или операции `toSignal` для подписки на `Observable` гарантирует корректную утилизацию подписок.

## Лучшие практики {#best-practices}

Хотя `HttpClient` можно внедрять и использовать напрямую из компонентов, в целом рекомендуется создавать переиспользуемые внедряемые сервисы, которые изолируют и инкапсулируют логику доступа к данным. Например, этот `UserService` инкапсулирует логику запроса данных пользователя по его id:

```ts
@Service()
export class UserService {
  private http = inject(HttpClient);

getUser(id: string): Observable<User> {
    return this.http.get<User>(`/api/user/${id}`);
  }
}
```

В компоненте можно объединить `@if` с pipe `async`, чтобы отрисовать UI для данных только после завершения загрузки:

```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 UserProfile {
  userId = input.required<string>();
  user$!: Observable<User>;

private userService = inject(UserService);

constructor(): void {
    effect(() => {
      this.user$ = this.userService.getUser(this.userId());
    });
  }
}
```
# Interceptor'ы

`HttpClient` поддерживает форму middleware, известную как _interceptor'ы_.

TLDR: Interceptor'ы — это middleware, позволяющее абстрагировать общие паттерны вокруг повторных попыток, кэширования, логирования и аутентификации от отдельных запросов.

`HttpClient` поддерживает два вида interceptor'ов: функциональные и на основе DI. Рекомендация — использовать функциональные interceptor'ы, потому что у них более предсказуемое поведение, особенно в сложных настройках. Примеры в этом руководстве используют функциональные interceptor'ы, а [interceptor'ы на основе DI](#di-based-interceptors) рассматриваются в отдельном разделе в конце.

## Interceptor'ы {#interceptors}

Interceptor'ы — обычно функции, которые можно запускать для каждого запроса и которые имеют широкие возможности влиять на содержимое и общий поток запросов и ответов. Можно установить несколько interceptor'ов, которые образуют цепочку, где каждый обрабатывает запрос или ответ перед передачей следующему interceptor'у в цепочке.

Interceptor'ы можно использовать для реализации различных распространённых паттернов, например:

- Добавление заголовков аутентификации к исходящим запросам к конкретному API.
- Повтор неудачных запросов с экспоненциальной задержкой.
- Кэширование ответов на период времени или до инвалидации мутациями.
- Настройка разбора ответов.
- Измерение времени ответа сервера и логирование.
- Управление UI-элементами вроде спиннера загрузки, пока сетевые операции выполняются.
- Сбор и пакетная обработка запросов, сделанных в определённом временном окне.
- Автоматический сбой запросов после настраиваемого дедлайна или таймаута.
- Регулярный опрос сервера и обновление результатов.

## Определение interceptor {#defining-an-interceptor}

Базовая форма interceptor — функция, которая получает исходящий `HttpRequest` и функцию `next`, представляющую следующий шаг обработки в цепочке interceptor'ов.

Например, этот `loggingInterceptor` залогирует URL исходящего запроса в `console.log` перед передачей запроса дальше:

```ts
export function loggingInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  console.log(req.url);
  return next(req);
}
```

Чтобы этот interceptor действительно перехватывал запросы, нужно настроить `HttpClient` на его использование.

## Настройка interceptor'ов {#configuring-interceptors}

Набор interceptor'ов для использования объявляется при настройке `HttpClient` через внедрение зависимостей с помощью возможности `withInterceptors`:

```ts
bootstrapApplication(App, {
  providers: [provideHttpClient(withInterceptors([loggingInterceptor, cachingInterceptor]))],
});
```

Настроенные interceptor'ы связываются в цепочку в порядке, в котором вы перечислили их в providers. В примере выше `loggingInterceptor` обработал бы запрос и затем передал бы его `cachingInterceptor`.

### Перехват событий ответа {#intercepting-response-events}

Interceptor может преобразовывать поток `Observable` событий `HttpEvent`, возвращаемый `next`, чтобы получить доступ к ответу или манипулировать им. Поскольку этот поток включает все события ответа, может понадобиться проверять `.type` каждого события, чтобы идентифицировать финальный объект ответа.

```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);
      }
    }),
  );
}
```

TIP: Interceptor'ы естественно ассоциируют ответы с исходящими запросами, потому что преобразуют поток ответа в замыкании, захватывающем объект запроса.

## Изменение запросов {#modifying-requests}

Большинство аспектов экземпляров `HttpRequest` и `HttpResponse` _неизменяемы_, и interceptor'ы не могут изменять их напрямую. Вместо этого interceptor'ы применяют мутации, клонируя эти объекты операцией `.clone()` и указывая, какие свойства должны быть изменены в новом экземпляре. Это может включать выполнение неизменяемых обновлений самого значения (вроде `HttpHeaders` или `HttpParams`).

Например, чтобы добавить заголовок к запросу:

```ts
const reqWithHeader = req.clone({
  headers: req.headers.set('X-New-Header', 'new header value'),
});
```

Эта неизменяемость позволяет большинству interceptor'ов быть идемпотентными, если один и тот же `HttpRequest` отправляется в цепочку interceptor'ов несколько раз. Это может произойти по нескольким причинам, включая повтор запроса после сбоя.

CRITICAL: Тело запроса или ответа **не** защищено от глубоких мутаций. Если interceptor должен мутировать тело, будьте осторожны при обработке многократного запуска на одном запросе.

## Внедрение зависимостей в interceptor'ах {#dependency-injection-in-interceptors}

Interceptor'ы выполняются в _контексте внедрения_ инжектора, который их зарегистрировал, и могут использовать API Angular [`inject`](/api/core/inject) для получения зависимостей.

Например, предположим, у приложения есть сервис `AuthService`, который создаёт токены аутентификации для исходящих запросов. Interceptor может внедрить и использовать этот сервис:

```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);
}
```

## Метаданные запроса и ответа {#request-and-response-metadata}

Часто полезно включать в запрос информацию, которая не отправляется на backend, а специально предназначена для interceptor'ов. У `HttpRequest` есть объект `.context`, который хранит такие метаданные как экземпляр `HttpContext`. Этот объект функционирует как типизированная карта с ключами типа `HttpContextToken`.

Чтобы проиллюстрировать, как работает эта система, используем метаданные для управления тем, включён ли кэширующий interceptor для данного запроса.

### Определение токенов контекста {#defining-context-tokens}

Чтобы хранить, должен ли кэширующий interceptor кэшировать конкретный запрос в карте `.context` этого запроса, определите новый `HttpContextToken` как ключ:

```ts
export const CACHING_ENABLED = new HttpContextToken<boolean>(() => true);
```

Предоставленная функция создаёт значение по умолчанию для токена для запросов, которые явно не задали для него значение. Использование функции гарантирует, что если значение токена — объект или массив, каждый запрос получает свой экземпляр.

### Чтение токена в interceptor {#reading-the-token-in-an-interceptor}

Затем interceptor может прочитать токен и выбрать, применять ли логику кэширования, на основе его значения:

```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);
  }
}
```

### Установка токенов контекста при выполнении запроса {#setting-context-tokens-when-making-a-request}

При выполнении запроса через API `HttpClient` можно предоставить значения для `HttpContextToken`:

```ts
const data$ = http.get('/sensitive/data', {
  context: new HttpContext().set(CACHING_ENABLED, false),
});
```

Interceptor'ы могут читать эти значения из `HttpContext` запроса.

### Контекст запроса изменяем {#the-request-context-is-mutable}

В отличие от других свойств `HttpRequest`, связанный `HttpContext` _изменяем_. Если interceptor меняет контекст запроса, который позже повторяется, тот же interceptor увидит мутацию контекста при повторном запуске. Это полезно для передачи состояния через несколько повторных попыток при необходимости.

## Синтетические ответы {#synthetic-responses}

Большинство interceptor'ов просто вызывают обработчик `next`, преобразуя либо запрос, либо ответ, но это не строгое требование. В этом разделе обсуждаются несколько способов, которыми interceptor может включать более продвинутое поведение.

Interceptor'ы не обязаны вызывать `next`. Вместо этого они могут выбрать построение ответов через другой механизм, например из кэша или отправкой запроса через альтернативный механизм.

Построить ответ можно с помощью конструктора `HttpResponse`:

```ts
const resp = new HttpResponse({
  body: 'response body',
});
```

## Работа с информацией о редиректе {#working-with-redirect-information}

Когда `HttpClient` использует fetch backend, ответы включают свойство `redirected`, указывающее, был ли ответ результатом редиректа. Это свойство соответствует спецификации нативного Fetch API и может быть полезно в interceptor'ах для обработки сценариев редиректа.

Interceptor может получить доступ к информации о редиректе и действовать на её основе:

```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.
      }
    }),
  );
}
```

Также можно использовать информацию о редиректе для реализации условной логики в interceptor'ах:

```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();
        }
      }
    }),
  );
}
```

## Работа с типами ответа {#working-with-response-types}

Когда `HttpClient` использует fetch backend, ответы включают свойство `type`, указывающее, как браузер обработал ответ на основе политик CORS и режима запроса. Это свойство соответствует спецификации нативного Fetch API и даёт ценные insights для отладки проблем CORS и понимания доступности ответа.

Свойство `type` ответа может иметь следующие значения:

- `'basic'` — ответ same-origin со всеми доступными заголовками
- `'cors'` — кросс-origin ответ с корректно настроенными CORS-заголовками
- `'opaque'` — кросс-origin ответ без CORS; заголовки и тело могут быть ограничены
- `'opaqueredirect'` — ответ от перенаправленного запроса в режиме no-cors
- `'error'` — произошла сетевая ошибка

Interceptor может использовать информацию о типе ответа для отладки CORS и обработки ошибок:

```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;
        }
      }
    }),
  );
}
```

## Interceptor'ы на основе DI {#di-based-interceptors}

`HttpClient` также поддерживает interceptor'ы, определённые как injectable-классы и настроенные через систему DI. Возможности interceptor'ов на основе DI идентичны функциональным, но механизм конфигурации другой.

Interceptor на основе DI — injectable-класс, реализующий интерфейс `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);
  }
}
```

Interceptor'ы на основе DI настраиваются через multi-provider внедрения зависимостей:

```ts
bootstrapApplication(App, {
  providers: [
    provideHttpClient(
      // DI-based interceptors must be explicitly enabled.
      withInterceptorsFromDi(),
    ),

{provide: HTTP_INTERCEPTORS, useClass: LoggingInterceptor, multi: true},
  ],
});
```

Interceptor'ы на основе DI выполняются в порядке регистрации их providers. В приложении с обширной и иерархической конфигурацией DI этот порядок может быть очень сложно предсказать.
# Тестирование запросов

Как и для любой внешней зависимости, нужно мокировать HTTP-backend, чтобы тесты могли симулировать взаимодействие с удалённым сервером. Библиотека `@angular/common/http/testing` предоставляет инструменты для захвата запросов, сделанных приложением, утверждений о них и мокирования ответов для эмуляции поведения вашего backend.

Библиотека тестирования рассчитана на паттерн, где приложение сначала выполняет код и делает запросы. Затем тест ожидает, что определённые запросы были или не были сделаны, выполняет утверждения против этих запросов и наконец предоставляет ответы, «сбрасывая» (flushing) каждый ожидаемый запрос.

Наконец, тесты могут проверить, что приложение не сделало неожиданных запросов.

## Настройка для тестирования {#setup-for-testing}

Чтобы начать тестировать использование `HttpClient`, настройте `TestBed` и включите `provideHttpClientTesting()` в настройку теста. `HttpClient` предоставляется тестовым окружением Angular, а `provideHttpClientTesting()` настраивает его на использование тестового backend вместо реальной сети. Он также предоставляет `HttpTestingController`, который вы будете использовать для взаимодействия с тестовым backend, установки ожиданий о том, какие запросы были сделаны, и сброса ответов на эти запросы. `HttpTestingController` можно внедрить из `TestBed` после настройки.

```ts
TestBed.configureTestingModule({
  providers: [
    // ... other test providers
    provideHttpClientTesting(),
  ],
});

const httpTesting = TestBed.inject(HttpTestingController);
```

Теперь когда ваши тесты делают запросы, они попадут в тестовый backend вместо обычного. Можно использовать `httpTesting` для утверждений об этих запросах.

### Настройка `HttpClient` в тестах {#configuring-httpclient-in-tests}

Если тесту нужно настроить возможности `HttpClient`, например interceptor'ы, включите `provideHttpClient(...)` перед `provideHttpClientTesting()`.
IMPORTANT: Помните, что нужно предоставлять `provideHttpClient()` **перед** `provideHttpClientTesting()`, потому что `provideHttpClientTesting()` перезапишет части `provideHttpClient()`. Обратный порядок может потенциально сломать тесты.

```ts
TestBed.configureTestingModule({
  providers: [provideHttpClient(withInterceptors([authInterceptor])), provideHttpClientTesting()],
});
```

## Ожидание и ответы на запросы {#expecting-and-answering-requests}

Например, можно написать тест, который ожидает GET-запрос и предоставляет mock-ответ:

```ts
TestBed.configureTestingModule({
  providers: [ConfigService, 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` завершится неудачей, если тест сделал более одного запроса, соответствующего заданным критериям.

Как альтернативу утверждению на `req.method` можно использовать расширенную форму `expectOne`, чтобы также сопоставить метод запроса:

```ts
const req = httpTesting.expectOne(
  {
    method: 'GET',
    url: '/api/config',
  },
  'Request to load the configuration',
);
```

HELPFUL: API ожиданий сопоставляются с полным URL запросов, включая любые query-параметры.

Последний шаг — проверка, что не осталось незавершённых запросов — достаточно распространён, чтобы перенести его в шаг `afterEach()`:

```ts
afterEach(() => {
  // Verify that none of the tests make any extra HTTP requests.
  TestBed.inject(HttpTestingController).verify();
});
```

## Обработка более одного запроса одновременно {#handling-more-than-one-request-at-once}

Если нужно ответить на дублирующиеся запросы в тесте, используйте API `match()` вместо `expectOne()`. Он принимает те же аргументы, но возвращает массив совпадающих запросов. После возврата эти запросы удаляются из будущего сопоставления, и вы отвечаете за их flush и проверку.

```ts
const allGetRequests = httpTesting.match({method: 'GET'});
for (const req of allGetRequests) {
  // Handle responding to each request.
}
```

## Продвинутое сопоставление {#advanced-matching}

Все функции сопоставления принимают функцию-предикат для пользовательской логики сопоставления:

```ts
// Look for one request that has a request body.
const requestsWithBody = httpTesting.expectOne((req) => req.body !== null);
```

Функция `expectNone` утверждает, что ни один запрос не соответствует заданным критериям.

```ts
// Assert that no mutation requests have been issued.
httpTesting.expectNone((req) => req.method !== 'GET');
```

## Тестирование обработки ошибок {#testing-error-handling}

Следует тестировать ответы приложения, когда HTTP-запросы завершаются неудачей.

### Ошибки backend {#backend-errors}

Чтобы тестировать обработку ошибок backend (когда сервер возвращает неуспешный код статуса), сбрасывайте запросы с ответом об ошибке, эмулирующим то, что вернул бы ваш backend при сбое запроса.

```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.
```

### Сетевые ошибки {#network-errors}

Запросы также могут завершаться неудачей из-за сетевых ошибок, которые проявляются как ошибки `ProgressEvent`. Их можно доставить методом `error()`:

```ts
const req = httpTesting.expectOne('/api/config');
req.error(new ProgressEvent('network error!'));

// Assert that the application successfully handled the network error.
```

## Тестирование Interceptor {#testing-an-interceptor}

Следует тестировать, что ваши interceptor'ы работают в желаемых обстоятельствах.

Например, приложению может требоваться добавлять токен аутентификации, сгенерированный сервисом, к каждому исходящему запросу.
Это поведение можно обеспечить с помощью 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);
}
```

Конфигурация `TestBed` для этого interceptor должна опираться на возможность `withInterceptors`.

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    // Testing one interceptor at a time is recommended.
    provideHttpClient(withInterceptors([authInterceptor])),
    provideHttpClientTesting(),
  ],
});
```

`HttpTestingController` может получить экземпляр запроса, который затем можно проверить, чтобы убедиться, что запрос был изменён.

```ts
const service = TestBed.inject(AuthService);
const req = httpTesting.expectOne('/api/config');

expect(req.request.headers.get('X-Authentication-Token')).toEqual(service.getAuthToken());
```

Похожий interceptor можно реализовать с классовыми interceptor'ами:

```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);
  }
}
```

Чтобы протестировать его, конфигурация `TestBed` вместо этого должна быть:

```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 дают model-driven подход к обработке полей формы, значения которых меняются со временем.
В этом руководстве показано, как создать и обновить базовый form control, использовать несколько controls в группе, валидировать значения формы и создавать динамические формы, в которых можно добавлять и удалять controls во время выполнения.

## Обзор reactive forms {#overview-of-reactive-forms}

Reactive forms используют явный и неизменяемый подход к управлению состоянием формы в конкретный момент времени.
Каждое изменение состояния формы возвращает новое состояние, что сохраняет целостность модели между изменениями.
Reactive forms построены вокруг observable-потоков: ввод и значения формы предоставляются как потоки, к которым можно обращаться синхронно.

Reactive forms также упрощают тестирование, потому что данные при запросе согласованы и предсказуемы.
Любые потребители этих потоков могут безопасно манипулировать данными.

Reactive forms отличаются от [template-driven forms](guide/forms/template-driven-forms) по ряду существенных пунктов.
Reactive forms дают синхронный доступ к модели данных, неизменяемость через операторы Observable и отслеживание изменений через observable-потоки.

Template-driven forms позволяют напрямую изменять данные в шаблоне, но менее явны, чем reactive forms: они опираются на директивы в шаблоне и на изменяемые данные для асинхронного отслеживания изменений.
Подробное сравнение двух подходов см. в [обзоре форм](guide/forms).

## Добавление базового form control {#adding-a-basic-form-control}

Чтобы использовать form controls, выполните три шага.

1. Создайте новый компонент и подключите модуль reactive forms. Этот модуль объявляет директивы, необходимые для работы с reactive forms.
1. Создайте экземпляр `FormControl`.
1. Зарегистрируйте `FormControl` в шаблоне.

Затем можно отобразить форму, добавив компонент в шаблон.

Следующие примеры показывают, как добавить один form control.
В примере пользователь вводит имя в поле ввода, значение сохраняется, и отображается текущее значение элемента form control.

<docs-workflow>

<docs-step title="Generate a new component and import the ReactiveFormsModule">
С помощью CLI-команды `ng generate component` создайте компонент в проекте, импортируйте `ReactiveFormsModule` из пакета `@angular/forms` и добавьте его в массив `imports` компонента.

<docs-code header="name-editor.component.ts (excerpt)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" region="imports" />
</docs-step>

<docs-step title="Declare a FormControl instance">
С помощью конструктора `FormControl` задайте начальное значение — в этом случае пустую строку. Создавая эти controls в классе компонента, вы сразу получаете доступ к прослушиванию, обновлению и валидации состояния поля формы.

<docs-code header="name-editor.component.ts" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" region="create-control"/>
</docs-step>

<docs-step title="Register the control in the template">
После создания control в классе компонента его нужно связать с элементом form control в шаблоне. Обновите шаблон, используя привязку `formControl`, которую предоставляет `FormControlDirective` (также входит в `ReactiveFormsModule`).

<docs-code header="name-editor.component.html" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="control-binding" />

Благодаря синтаксису привязки в шаблоне form control теперь зарегистрирован на элементе ввода `name`. Form control и DOM-элемент обмениваются данными: представление отражает изменения модели, а модель — изменения представления.
</docs-step>

<docs-step title="Display the component">
`FormControl`, назначенный свойству `name`, отображается, когда компонент `<app-name-editor>` добавляется в шаблон.

<docs-code header="app.component.html (name editor)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" region="app-name-editor"/>
</docs-step>
</docs-workflow>

### Отображение значения form control {#displaying-a-form-control-value}

Значение можно отобразить следующими способами:

- Через Observable `valueChanges`, где можно слушать изменения значения формы в шаблоне с помощью `AsyncPipe` или в классе компонента методом `subscribe()`
- Через свойство `value`, которое даёт снимок текущего значения

Следующий пример показывает, как отобразить текущее значение с помощью интерполяции в шаблоне.

<docs-code header="name-editor.component.html (control value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="display-value"/>

Отображаемое значение меняется при обновлении элемента form control.

Reactive forms дают доступ к информации о control через свойства и методы каждого экземпляра.
Эти свойства и методы базового класса [AbstractControl](api/forms/AbstractControl 'API reference') используются для управления состоянием формы и определения, когда показывать сообщения при [валидации ввода](#validating-form-input 'Learn more about validating form input').

О других свойствах и методах `FormControl` читайте в [справочнике API](api/forms/FormControl 'Detailed syntax reference').

### Замена значения form control {#replacing-a-form-control-value}

В reactive forms есть методы для программного изменения значения control, что позволяет обновлять значение без взаимодействия пользователя.
Экземпляр form control предоставляет метод `setValue()`, который обновляет значение form control и проверяет структуру переданного значения относительно структуры control.
Например, при получении данных формы из backend API или сервиса используйте `setValue()`, чтобы полностью заменить старое значение control новым.

Следующий пример добавляет в класс компонента метод, который обновляет значение control на _Nancy_ с помощью `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" region="update-value"/>

Обновите шаблон кнопкой, имитирующей обновление имени.
При нажатии кнопки **Update Name** значение, введённое в элемент form control, отражается как текущее значение.

<docs-code header="name-editor.component.html (update value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="update-value"/>

Модель формы — источник истины для control, поэтому при нажатии кнопки значение input меняется в классе компонента, перезаписывая текущее значение.

HELPFUL: В этом примере используется один control.
При использовании `setValue()` с экземпляром [form group](#grouping-form-controls) или [form array](#creating-dynamic-forms) значение должно соответствовать структуре группы или массива.

## Группировка form controls {#grouping-form-controls}

Формы обычно содержат несколько связанных controls.
Reactive forms дают два способа сгруппировать несколько связанных controls в одну форму ввода.

| Form groups | Подробности                                                                                                                                                                                                                                                |
| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Form group  | Определяет форму с фиксированным набором controls, которыми можно управлять вместе. Основы form group рассматриваются в этом разделе. Также можно [вкладывать form groups](#creating-nested-form-groups 'See more about nesting groups'), чтобы создавать более сложные формы. |
| Form array  | Определяет динамическую форму, в которой можно добавлять и удалять controls во время выполнения. Form arrays также можно вкладывать для более сложных форм. Подробнее об этом варианте см. в разделе [Создание динамических форм](#creating-dynamic-forms).                              |

Как экземпляр form control даёт управление одним полем ввода, так экземпляр form group отслеживает состояние формы для группы экземпляров form control $например, формы$.
Каждый control в экземпляре form group отслеживается по имени при создании form group.
Следующий пример показывает, как управлять несколькими экземплярами form control в одной группе.

Создайте компонент `ProfileEditor` и импортируйте классы `FormGroup` и `FormControl` из пакета `@angular/forms`.

```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" region="imports"/>

Чтобы добавить form group в этот компонент, выполните следующие шаги.

1. Создайте экземпляр `FormGroup`.
1. Свяжите модель `FormGroup` и представление.
1. Сохраните данные формы.

<docs-workflow>

<docs-step title="Create a FormGroup instance">
Создайте в классе компонента свойство с именем `profileForm` и присвойте ему новый экземпляр form group. Чтобы инициализировать form group, передайте в конструктор объект с именованными ключами, сопоставленными с их controls.

Для формы профиля добавьте два экземпляра form control с именами `firstName` и `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" region="formgroup"/>

Отдельные form controls теперь собраны в группу. Экземпляр `FormGroup` предоставляет значение модели как объект, собранный из значений каждого control в группе. У экземпляра form group те же свойства (например, `value` и `untouched`) и методы (например, `setValue()`), что и у экземпляра form control.
</docs-step>

<docs-step title="Associate the FormGroup model and view">
Form group отслеживает статус и изменения каждого своего control, поэтому если один из controls меняется, родительский control также испускает новый статус или изменение значения. Модель группы поддерживается её участниками. После определения модели нужно обновить шаблон, чтобы отразить модель в представлении.

<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" region="formgroup"/>

Как form group содержит группу controls, так _profileForm_ `FormGroup` привязывается к элементу `form` директивой `FormGroup`, создавая слой связи между моделью и формой с полями ввода. Input `formControlName`, предоставляемый директивой `FormControlName`, привязывает каждый отдельный input к form control, определённому в `FormGroup`. Form controls обмениваются данными со своими элементами. Они также сообщают об изменениях экземпляру form group, который является источником истины для значения модели.
</docs-step>

<docs-step title="Save form data">
Компонент `ProfileEditor` принимает ввод пользователя, но в реальном сценарии нужно захватить значение формы и сделать его доступным для дальнейшей обработки вне компонента. Директива `FormGroup` слушает событие `submit`, испускаемое элементом `form`, и испускает событие `ngSubmit`, которое можно привязать к callback-функции. Добавьте слушатель события `ngSubmit` к тегу `form` с 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" region="ng-submit"/>

Метод `onSubmit()` в компоненте `ProfileEditor` захватывает текущее значение `profileForm`. Используйте `output()`, чтобы сохранить инкапсуляцию формы и предоставить значение формы вне компонента. В следующем примере `console.warn` записывает сообщение в консоль браузера.

<docs-code header="profile-editor.component.ts (submit method)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="on-submit"/>

Событие `submit` испускается тегом `form` через встроенное DOM-событие. Событие запускается нажатием кнопки с типом `submit`. Это позволяет пользователю нажать клавишу **Enter**, чтобы отправить заполненную форму.

Используйте элемент `button`, чтобы добавить кнопку внизу формы для отправки формы.

<docs-code header="profile-editor.component.html (submit button)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="submit-button"/>

У кнопки в предыдущем фрагменте также есть привязка `disabled`, которая отключает кнопку, когда `profileForm` невалидна. Пока валидация не выполняется, кнопка всегда включена. Базовая валидация формы рассматривается в разделе [Валидация ввода формы](#validating-form-input).
</docs-step>

<docs-step title="Display the component">
Чтобы отобразить компонент `ProfileEditor` с формой, добавьте его в шаблон компонента.

<docs-code header="app.component.html (profile editor)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" region="app-profile-editor"/>

`ProfileEditor` позволяет управлять экземплярами form control для controls `firstName` и `lastName` внутри экземпляра form group.

### Создание вложенных form groups {#creating-nested-form-groups}

Form groups могут принимать в качестве дочерних элементов как отдельные экземпляры form control, так и другие экземпляры form group.
Это упрощает поддержку сложных моделей форм и логическую группировку.

При создании сложных форм удобнее управлять разными областями информации в меньших секциях.
Вложенный экземпляр form group позволяет разбить большие form groups на более мелкие и управляемые.

Чтобы создать более сложные формы, выполните следующие шаги.

1. Создайте вложенную группу.
1. Сгруппируйте вложенную форму в шаблоне.

Некоторые типы информации естественно относятся к одной группе.
Имя и адрес — типичные примеры таких вложенных групп; они используются в следующих примерах.

<docs-workflow>
<docs-step title="Create a nested group">
Чтобы создать вложенную группу в `profileForm`, добавьте вложенный элемент `address` в экземпляр 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" region="nested-formgroup"/>

В этом примере `address group` объединяет текущие controls `firstName` и `lastName` с новыми controls `street`, `city`, `state` и `zip`. Хотя элемент `address` в form group является дочерним по отношению к общему элементу `profileForm` в form group, те же правила применяются к изменениям значения и статуса. Изменения статуса и значения из вложенной form group распространяются на родительскую form group, сохраняя согласованность с общей моделью.
</docs-step>

<docs-step title="Group the nested form in the template">
После обновления модели в классе компонента обновите шаблон, чтобы связать экземпляр form group и его элементы ввода. Добавьте form group `address` с полями `street`, `city`, `state` и `zip` в шаблон `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" region="formgroupname"/>

Форма `ProfileEditor` отображается как одна группа, но модель дополнительно разбита, чтобы отражать логические области группировки.

Отобразите значение экземпляра form group в шаблоне компонента с помощью свойства `value` и `JsonPipe`.
</docs-step>
</docs-workflow>

### Обновление частей модели данных {#updating-parts-of-the-data-model}

При обновлении значения экземпляра form group, содержащего несколько controls, может потребоваться обновить только части модели.
В этом разделе рассматривается, как обновлять конкретные части модели данных form control.

Есть два способа обновить значение модели:

| Методы        | Подробности                                                                                                                                                               |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setValue()`   | Задаёт новое значение для отдельного control. Метод `setValue()` строго следует структуре form group и полностью заменяет значение control. |
| `patchValue()` | Заменяет любые свойства, определённые в объекте, которые изменились в модели формы.                                                                                     |

Строгие проверки метода `setValue()` помогают выявлять ошибки вложенности в сложных формах, тогда как `patchValue()` при таких ошибках молча завершается неудачей.

В `ProfileEditorComponent` используйте метод `updateProfile` со следующим примером, чтобы обновить имя и улицу пользователя.

<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" region="patch-value"/>

Смоделируйте обновление, добавив в шаблон кнопку для обновления профиля пользователя по запросу.

<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" region="patch-value"/>

Когда пользователь нажимает кнопку, модель `profileForm` обновляется новыми значениями для `firstName` и `street`. Обратите внимание, что `street` передаётся в объекте внутри свойства `address`.
Это необходимо, потому что метод `patchValue()` применяет обновление относительно структуры модели.
`patchValue()` обновляет только те свойства, которые определены в модели формы.

## Использование сервиса FormBuilder для генерации controls {#using-the-formbuilder-service-to-generate-controls}

Ручное создание экземпляров form control может стать повторяющимся при работе с несколькими формами.
Сервис `FormBuilder` предоставляет удобные методы для генерации controls.

Чтобы воспользоваться этим сервисом, выполните следующие шаги.

1. Импортируйте класс `FormBuilder`.
1. Внедрите сервис `FormBuilder`.
1. Сгенерируйте содержимое формы.

Следующие примеры показывают, как рефакторить компонент `ProfileEditor`, чтобы использовать сервис form builder для создания экземпляров form control и form group.

<docs-workflow>
<docs-step title="Import the FormBuilder class">
Импортируйте класс `FormBuilder` из пакета `@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" region="form-builder-imports"/>

</docs-step>

<docs-step title="Inject the FormBuilder service">
Сервис `FormBuilder` — внедряемый провайдер из модуля reactive forms. Используйте функцию `inject()`, чтобы внедрить эту зависимость в компонент.

<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" region="inject-form-builder"/>

</docs-step>
<docs-step title="Generate form controls">
У сервиса `FormBuilder` три метода: `control()`, `group()` и `array()`. Это фабричные методы для генерации экземпляров в классах компонентов, включая form controls, form groups и form arrays. Используйте метод `group`, чтобы создать 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" region="form-builder"/>

В предыдущем примере метод `group()` используется с тем же объектом для определения свойств в модели. Значение для каждого имени control — массив, в котором первый элемент — начальное значение.

TIP: Можно определить control только с начальным значением, но если controls нуждаются в синхронной или асинхронной валидации, добавьте sync- и async-валидаторы как второй и третий элементы массива. Сравните использование form builder с ручным созданием экземпляров.
</docs-step>

</docs-workflow>

## Валидация ввода формы {#validating-form-input}

_Валидация формы_ используется, чтобы убедиться, что ввод пользователя полный и корректный.
В этом разделе рассматривается добавление одного валидатора к form control и отображение общего статуса формы.
Валидация формы подробнее описана в руководстве [Валидация форм](guide/forms/form-validation).

Чтобы добавить валидацию формы, выполните следующие шаги.

1. Импортируйте функцию-валидатор в компонент формы.
1. Добавьте валидатор к полю в форме.
1. Добавьте логику обработки статуса валидации.

Самая распространённая валидация — сделать поле обязательным.
Следующий пример показывает, как добавить required-валидацию к control `firstName` и отобразить результат валидации.

<docs-workflow>
<docs-step title="Import a validator function">
Reactive forms включают набор функций-валидаторов для типичных сценариев. Эти функции принимают control для проверки и возвращают объект ошибки или значение null в зависимости от результата проверки.

Импортируйте класс `Validators` из пакета `@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" region="validator-imports"/>
</docs-step>

<docs-step title="Make a field required">
В компоненте `ProfileEditor` добавьте статический метод `Validators.required` как второй элемент массива для 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" region="required-validator"/>
</docs-step>

<docs-step title="Display form status">
Когда к form control добавляется обязательное поле, его начальный статус — invalid. Этот невалидный статус распространяется на родительский элемент form group, делая его статус invalid. Текущий статус экземпляра form group доступен через свойство `status`.

Отобразите текущий статус `profileForm` с помощью интерполяции.

<docs-code header="profile-editor.component.html (display status)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="display-status"/>

Кнопка **Submit** отключена, потому что `profileForm` невалидна из-за обязательного form control `firstName`. После заполнения поля `firstName` форма становится валидной, и кнопка **Submit** включается.

Подробнее о валидации форм см. в руководстве [Валидация форм](guide/forms/form-validation).
</docs-step>
</docs-workflow>

## Создание динамических форм {#creating-dynamic-forms}

`FormArray` — альтернатива `FormGroup` для управления любым числом безымянных controls.
Как и с экземплярами form group, в экземпляры form array можно динамически вставлять и удалять controls, а значение и статус валидации экземпляра form array вычисляются из дочерних controls.
Однако не нужно определять ключ для каждого control по имени, поэтому это отличный вариант, если заранее неизвестно число дочерних значений.

Чтобы определить динамическую форму, выполните следующие шаги.

1. Импортируйте класс `FormArray`.
1. Определите control `FormArray`.
1. Получите доступ к control `FormArray` через getter-метод.
1. Отобразите form array в шаблоне.

Следующий пример показывает, как управлять массивом _aliases_ в `ProfileEditor`.

<docs-workflow>
<docs-step title="Import the `FormArray` class">
Импортируйте класс `FormArray` из `@angular/forms` для информации о типах. Сервис `FormBuilder` готов создать экземпляр `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" region="form-array-imports"/>
</docs-step>

<docs-step title="Define a `FormArray` control">
Form array можно инициализировать любым числом controls — от нуля до многих — определив их в массиве. Добавьте свойство `aliases` в экземпляр form group для `profileForm`, чтобы определить form array.

Используйте метод `FormBuilder.array()`, чтобы определить массив, и метод `FormBuilder.control()`, чтобы заполнить массив начальным control.

<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" region="aliases"/>

Control aliases в экземпляре form group теперь заполнен одним control, пока динамически не будут добавлены дополнительные controls.
</docs-step>

<docs-step title="Access the `FormArray` control">
Getter даёт доступ к aliases в экземпляре form array по сравнению с повторным вызовом метода `profileForm.get()` для получения каждого экземпляра. Экземпляр form array представляет неопределённое число controls в массиве. Удобно обращаться к control через getter, и этот подход легко повторить для дополнительных controls. <br />

Используйте синтаксис getter, чтобы создать свойство класса `aliases` для получения form array control alias из родительской form group.

<docs-code header="profile-editor.component.ts (aliases getter)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="aliases-getter"/>

Поскольку возвращаемый control имеет тип `AbstractControl`, нужно явно указать тип, чтобы получить доступ к синтаксису методов экземпляра form array. Определите метод для динамической вставки alias control в form array aliases. Метод `FormArray.push()` вставляет control как новый элемент массива; также можно передать массив controls в FormArray.push(), чтобы зарегистрировать несколько controls сразу.

<docs-code header="profile-editor.component.ts (add alias)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="add-alias"/>

В шаблоне каждый control отображается как отдельное поле ввода.

</docs-step>

<docs-step title="Display the form array in the template">

Чтобы привязать aliases из модели формы, их нужно добавить в шаблон. Аналогично input `formGroupName`, предоставляемому `FormGroupNameDirective`, `formArrayName` связывает обмен данными от экземпляра form array с шаблоном через `FormArrayNameDirective`.

Добавьте следующий HTML шаблона после закрывающего `</div>` элемента `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" region="formarrayname"/>

Блок `@for` перебирает каждый экземпляр form control, предоставляемый экземпляром form array aliases. Поскольку элементы form array безымянны, индекс присваивается переменной `i` и передаётся каждому control для привязки к input `formControlName`.

Каждый раз, когда добавляется новый экземпляр alias, новому экземпляру form array предоставляется его control на основе индекса. Это позволяет отслеживать каждый отдельный control при вычислении статуса и значения корневого control.

NOTE: В zoneless-приложениях мутация модели reactive forms (например, вызов `FormArray.push()`) не планирует автоматически обнаружение изменений компонента. Если шаблон зависит от структурных изменений модели, таких как `aliases.controls`, убедитесь, что компонент уведомляет Angular о необходимости запустить обнаружение изменений, например связав Observable формы с `ChangeDetectorRef.markForCheck()`:

```ts
import {ChangeDetectorRef, Component, inject} from '@angular/core';
import {takeUntilDestroyed} from '@angular/core/rxjs-interop';

@Component({
  /* ... */
})
export class ProfileEditor {
  private readonly cdr = inject(ChangeDetectorRef);

constructor() {
    this.profileForm.valueChanges
      .pipe(takeUntilDestroyed())
      .subscribe(() => this.cdr.markForCheck());
  }
}
```

</docs-step>

### Использование `FormArrayDirective` для form arrays верхнего уровня {#using-formarraydirective-for-top-level-form-arrays}

Можно привязать `FormArray` напрямую к элементу `<form>` с помощью `FormArrayDirective`.  
Это полезно, когда форма не использует `FormGroup` верхнего уровня, а сам массив представляет полную модель формы.

```typescript
import {Component} from '@angular/core';
import {FormArray, FormControl} from '@angular/forms';

@Component({
  selector: 'form-array-example',
  template: `
    <form [formArray]="form">
      @for (control of form.controls; track $index) {
        <input [formControlName]="$index" />
      }
    </form>
  `,
})
export class FormArrayExampleComponent {
  controls = [new FormControl('fish'), new FormControl('cat'), new FormControl('dog')];

form = new FormArray(this.controls);
}
```

<docs-step title="Add an alias">

Изначально форма содержит одно поле `Alias`. Чтобы добавить ещё одно поле, нажмите кнопку **Add Alias**. Также можно проверить массив aliases, сообщаемый моделью формы и отображаемый как `Form Value` внизу шаблона. Вместо экземпляра form control для каждого alias можно составить другой экземпляр form group с дополнительными полями. Процесс определения control для каждого элемента тот же.
</docs-step>

</docs-workflow>

## Единые события изменения состояния control {#unified-control-state-change-events}

Все form controls предоставляют единый поток **событий изменения состояния control** через Observable `events` на `AbstractControl` (`FormControl`, `FormGroup`, `FormArray` и `FormRecord`).
Этот единый поток позволяет реагировать на изменения состояния **value**, **status**, **pristine**, **touched** и **reset**, а также на **действия уровня формы**, такие как **submit**, обрабатывая все обновления одной подпиской вместо подключения нескольких Observable.

### Типы событий {#event-types}

Каждый элемент, испускаемый `events`, — экземпляр конкретного класса события:

- **`ValueChangeEvent`** — когда меняется **value** control.
- **`StatusChangeEvent`** — когда **статус валидации** control обновляется до одного из значений `FormControlStatus` (`VALID`, `INVALID`, `PENDING` или `DISABLED`).
- **`PristineChangeEvent`** — когда меняется состояние **pristine/dirty** control.
- **`TouchedChangeEvent`** — когда меняется состояние **touched/untouched** control.
- **`FormResetEvent`** — когда control или форма сбрасывается через API `reset()` или нативное действие.
- **`FormSubmittedEvent`** — когда форма отправляется.

Все классы событий расширяют `ControlEvent` и включают ссылку `source` на `AbstractControl`, инициировавший изменение, что полезно в больших формах.

```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');
      }
    });
  }
}
```

### Фильтрация конкретных событий {#filtering-specific-events}

Предпочитайте операторы RxJS, когда нужны только определённые типы событий.

```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));
```

### Объединение вместо нескольких подписок {#unifying-from-multiple-subscriptions}

**До**

```ts
import {combineLatest} from 'rxjs/operators';

combineLatest([control.valueChanges, control.statusChanges]).subscribe(([value, status]) => {
  /* ... */
});
```

**После**

```ts
control.events.subscribe((e) => {
  // Handle ValueChangeEvent, StatusChangeEvent, etc.
});
```

NOTE: При изменении значения emit происходит сразу после обновления значения этого control. Значение родительского control (например, если этот FormControl является частью FormGroup) обновляется позже, поэтому обращение к значению родительского control (через свойство `value`) из callback этого события может вернуть ещё не обновлённое значение. Вместо этого подписывайтесь на `events` родительского control.

## Управление состоянием form control {#managing-form-control-state}

Reactive forms отслеживают состояние control через **touched/untouched** и **pristine/dirty**. Angular обновляет их автоматически при взаимодействии с DOM, но ими также можно управлять программно.

**[`markAsTouched`](api/forms/FormControl#markAsTouched)** — Помечает control или форму как touched при событиях focus и blur, которые не меняют значение. По умолчанию распространяется на родительские controls.

```ts
// Show validation errors after user leaves a field
onEmailBlur() {
  const email = this.form.get('email');
  email.markAsTouched();
}
```

**[`markAsUntouched`](api/forms/FormControl#markAsUntouched)** — Помечает control или форму как untouched. Каскадно применяется ко всем дочерним controls и пересчитывает статус touched всех родительских controls.

```ts
// Reset form state after successful submission
onSubmitSuccess() {
  this.form.markAsUntouched();
  this.form.markAsPristine();
}
```

**[`markAsDirty`](api/forms/FormControl#markAsDirty)** — Помечает control или форму как dirty, то есть значение было изменено. По умолчанию распространяется на родительские controls.

```ts
// Mark programmatically changed values as modified
autofillAddress() {
  const previousAddress = getAddress();
  this.form.patchValue(previousAddress, { emitEvent: false });
  this.form.markAsDirty();
}
```

**[`markAsPristine`](api/forms/FormControl#markAsPristine)** — Помечает control или форму как pristine. Помечает все дочерние controls как pristine и пересчитывает статус pristine всех родительских controls.

```ts
// Reset pristine state after saving to track new changes
saveForm() {
  this.api.save(this.form.value).subscribe(() => {
    this.form.markAsPristine();
  });
}
```

**[`markAllAsDirty`](api/forms/FormControl#markAllAsDirty)** — Помечает control или форму и все их потомки как dirty.

```ts
// Mark imported data as dirty
loadData(data: FormData) {
  this.form.patchValue(data);
  this.form.markAllAsDirty();
}
```

**[`markAllAsTouched`](api/forms/FormControl#markAllAsTouched)** — Помечает control или форму и все их потомки как touched. Полезно для показа ошибок валидации по всей форме.

```ts
// Show all validation errors before submission
onSubmit() {
  if (this.form.invalid) {
    this.form.markAllAsTouched();
    return;
  }
  this.saveForm();
}
```

## Управление испусканием событий и распространением {#controlling-event-emission-and-propagation}

При программном обновлении form controls есть точный контроль над тем, как изменения распространяются по иерархии формы и испускаются ли события.

### Понимание испускания событий {#understanding-event-emission}

По умолчанию `emitEvent: true` — любое изменение control испускает события через Observable `valueChanges` и `statusChanges`. Установка `emitEvent: false` подавляет эти испускания, что полезно при программной установке значений без запуска реактивного поведения вроде автосохранения, избежания циклических обновлений между controls или пакетных обновлений, когда события должны испуститься только один раз в конце.

```ts
@Component({
  /* ... */
})
export class BlogPostEditor {
  postForm = new FormGroup({
    title: new FormControl(''),
    content: new FormControl(''),
  });

constructor() {
    // Auto-save draft every time user types
    this.postForm.valueChanges.subscribe((formValue) => {
      this.autosaveDraft(formValue);
    });
  }

loadExistingDraft(savedDraft: {title: string; content: string}) {
    // Restore draft without triggering auto-save
    this.postForm.setValue(savedDraft, {emitEvent: false});
  }
}
```

### Понимание управления распространением {#understanding-propagation-control}

По умолчанию `onlySelf: false` — обновления каскадно применяются к родительским controls, пересчитывая их значения и статус валидации. Установка `onlySelf: true` изолирует обновление текущим control, предотвращая уведомление родителя. Это полезно для пакетных операций, когда родительское обновление нужно запустить вручную один раз.

```ts
updatePostalCodeValidator(country: string) {
  const postal = this.addressForm.get('postalCode');

const validators = country === 'US'
    ? [Validators.maxLength(5)]
    : [Validators.maxLength(7)];

postal.setValidators(validators);
  postal.updateValueAndValidity({ onlySelf: true, emitEvent: false });
}
```

HELPFUL: О динамическом управлении валидаторами во время выполнения см. раздел [Управление валидаторами динамически в reactive forms](guide/forms/form-validation#managing-validators-dynamically-in-reactive-forms) в руководстве по валидации форм.

## Утилитарные функции для сужения типов form control {#utility-functions-for-narrowing-form-control-types}

Angular предоставляет четыре утилитарные функции, которые помогают определить конкретный тип `AbstractControl`. Эти функции работают как **type guards** и сужают тип control, когда возвращают `true`, что позволяет безопасно обращаться к свойствам подтипа внутри того же блока.

Эти помощники особенно полезны в **пользовательских валидаторах**, где сигнатура функции принимает `AbstractControl`, но логика предназначена для конкретного вида 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;
}
```

## Сводка API reactive forms {#reactive-forms-api-summary}

В следующей таблице перечислены базовые классы и сервисы, используемые для создания и управления reactive form controls.
Полные детали синтаксиса см. в справочной документации API пакета [Forms](api#forms 'API reference').

### Классы {#classes}

| Класс             | Подробности                                                                                                                                                                                 |
| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AbstractControl` | Абстрактный базовый класс для конкретных классов form control `FormControl`, `FormGroup` и `FormArray`. Предоставляет их общее поведение и свойства.                           |
| `FormControl`     | Управляет значением и статусом валидности отдельного form control. Соответствует HTML form control, такому как `<input>` или `<select>`.                                            |
| `FormGroup`       | Управляет значением и состоянием валидности группы экземпляров `AbstractControl`. Свойства группы включают её дочерние controls. Форма верхнего уровня в компоненте — это `FormGroup`. |
| `FormArray`       | Управляет значением и состоянием валидности численно индексированного массива экземпляров `AbstractControl`.                                                                                     |
| `FormBuilder`     | Внедряемый сервис, предоставляющий фабричные методы для создания экземпляров control.                                                                                                     |
| `FormRecord`      | Отслеживает значение и состояние валидности коллекции экземпляров `FormControl`, каждый из которых имеет одинаковый тип значения.                                                                  |

### Директивы {#directives}

Начиная с Angular 14, reactive forms по умолчанию строго типизированы.

В качестве фона для этого руководства вы уже должны быть знакомы с [Angular Reactive Forms](guide/forms/reactive-forms).

## Обзор типизированных форм {#overview-of-typed-forms}

<docs-video src="https://www.youtube.com/embed/L-odCf4MfJc" alt="Typed Forms in Angular" />

В Angular reactive forms вы явно задаёте _модель формы_. Как простой пример рассмотрим базовую форму входа пользователя:

```ts
const login = new FormGroup({
  email: new FormControl(''),
  password: new FormControl(''),
});
```

Angular предоставляет множество API для взаимодействия с этим `FormGroup`. Например, можно вызвать `login.value`, `login.controls`, `login.patchValue` и т.д. (Полный справочник API см. в [документации API](api/forms/FormGroup).)

В предыдущих версиях Angular большинство этих API где-то в типах включали `any`, и взаимодействие со структурой controls или самими значениями не было типобезопасным. Например, можно было написать следующий некорректный код:

```ts
const emailDomain = login.value.email.domain;
```

Со строго типизированными reactive forms код выше не компилируется, потому что у `email` нет свойства `domain`.

Помимо дополнительной безопасности, типы дают и другие улучшения: лучшее автодополнение в IDE и явный способ задать структуру формы.

Эти улучшения сейчас применяются только к _reactive_ forms (не к [_template-driven_ forms](guide/forms/template-driven-forms)).

## Нетипизированные формы {#untyped-forms}

Нетипизированные формы по-прежнему поддерживаются и продолжают работать как раньше. Чтобы использовать их, нужно импортировать символы `Untyped` из `@angular/forms`:

```ts
const login = new UntypedFormGroup({
  email: new UntypedFormControl(''),
  password: new UntypedFormControl(''),
});
```

Каждый символ `Untyped` имеет ту же семантику, что и в предыдущих версиях Angular. Убрав префиксы `Untyped`, можно постепенно включать типы.

## `FormControl`: начало работы {#formcontrol-getting-started}

Самая простая возможная форма состоит из одного control:

```ts
const email = new FormControl('angularrox@gmail.com');
```

Для этого control автоматически выведется тип `FormControl<string|null>`. TypeScript будет автоматически обеспечивать этот тип во всём [`FormControl` API](api/forms/FormControl), например `email.value`, `email.valueChanges` и `email.setValue(...)`.

### Nullable {#nullability}

Может возникнуть вопрос: почему тип этого control включает `null`? Потому что control может стать `null` в любой момент при вызове reset:

```ts
const email = new FormControl('angularrox@gmail.com');
email.reset();
console.log(email.value); // null
```

TypeScript потребует всегда обрабатывать возможность того, что control стал `null`. Если нужно сделать control non-nullable, используйте опцию `nonNullable`. Тогда control будет сбрасываться к начальному значению, а не к `null`:

```ts
const email = new FormControl('angularrox@gmail.com', {nonNullable: true});
email.reset();
console.log(email.value); // angularrox@gmail.com
```

Повторим: эта опция влияет на runtime-поведение формы при вызове `.reset()` и должна включаться осознанно.

### Явное указание типа {#specifying-an-explicit-type}

Тип можно указать явно, вместо того чтобы полагаться на вывод. Рассмотрим control, инициализированный как `null`. Поскольку начальное значение — `null`, TypeScript выведет `FormControl<null>`, что уже, чем нужно.

```ts
const email = new FormControl(null);
email.setValue('angularrox@gmail.com'); // Error!
```

Чтобы предотвратить это, явно укажите тип как `string|null`:

```ts
const email = new FormControl<string | null>(null);
email.setValue('angularrox@gmail.com');
```

## `FormArray`: динамические однородные коллекции {#formarray-dynamic-homogenous-collections}

`FormArray` содержит открытый список controls. Параметр типа соответствует типу каждого внутреннего control:

```ts
const names = new FormArray([new FormControl('Alex')]);
names.push(new FormControl('Jess'));
```

Передавайте массив controls в `aliases.push()`, когда нужно добавить несколько записей сразу.

```ts
const aliases = new FormArray([new FormControl('ng')]);
aliases.push([new FormControl('ngDev'), new FormControl('ngAwesome')]);
```

У этого `FormArray` тип внутренних controls будет `FormControl<string|null>`.

Если нужны разные типы элементов внутри массива, используйте `UntypedFormArray`, потому что TypeScript не может вывести, какой тип элемента окажется в какой позиции.

У `FormArray` также есть метод `clear()` для удаления всех содержащихся controls:

```ts
const aliases = new FormArray([new FormControl('ngDev'), new FormControl('ngAwesome')]);
aliases.clear();
console.log(aliases.length); // 0
```

## `FormGroup` и `FormRecord` {#formgroup-and-formrecord}

Angular предоставляет тип `FormGroup` для форм с перечислимым набором ключей и тип `FormRecord` для открытых или динамических групп.

### Частичные значения {#partial-values}

Снова рассмотрим форму входа:

```ts
const login = new FormGroup({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});
```

На любом `FormGroup` [можно отключать controls](api/forms/FormGroup). Любой отключённый control не появится в значении группы.

Как следствие, тип `login.value` — `Partial<{email: string, password: string}>`. `Partial` в этом типе означает, что каждый член может быть undefined.

Точнее, тип `login.value.email` — `string|undefined`, и TypeScript потребует обрабатывать возможно `undefined` значение (если включён `strictNullChecks`).

Если нужно получить значение _включая_ отключённые controls и тем самым обойти возможные поля `undefined`, используйте `login.getRawValue()`.

### Опциональные controls и динамические группы {#optional-controls-and-dynamic-groups}

В некоторых формах controls могут присутствовать или отсутствовать и добавляться/удаляться в runtime. Такие controls можно представить через _опциональные поля_:

```ts
interface LoginForm {
  email: FormControl<string>;
  password?: FormControl<string>;
}

const login = new FormGroup<LoginForm>({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});

В этой форме мы явно указываем тип, что позволяет сделать control `password` опциональным. TypeScript потребует, чтобы добавлять или удалять можно было только опциональные controls.

### `FormRecord` {#formrecord}

Некоторые использования `FormGroup` не подходят под паттерн выше, потому что ключи заранее неизвестны. Класс `FormRecord` предназначен для этого случая:

```ts
const addresses = new FormRecord<FormControl<string | null>>({});
addresses.addControl('Andrew', new FormControl('2340 Folsom St'));
```

В этот `FormRecord` можно добавить любой control типа `string|null`.

Если нужен `FormGroup`, который одновременно динамический (открытый) и гетерогенный (controls разных типов), улучшенная типобезопасность невозможна — используйте `UntypedFormGroup`.

`FormRecord` также можно построить с помощью `FormBuilder`:

```ts
const addresses = fb.record({'Andrew': '2340 Folsom St'});
```

## `FormBuilder` и `NonNullableFormBuilder` {#formbuilder-and-nonnullableformbuilder}

Класс `FormBuilder` также обновлён для поддержки новых типов, аналогично примерам выше.

Кроме того, доступен дополнительный builder: `NonNullableFormBuilder`. Этот тип — сокращение для указания `{nonNullable: true}` на каждом control и может устранить значительный шаблонный код в крупных non-nullable формах. Доступ к нему — через свойство `nonNullable` у `FormBuilder`:

```ts
const fb = new FormBuilder();
const login = fb.nonNullable.group({
  email: '',
  password: '',
});
```

В примере выше оба внутренних control будут non-nullable (то есть будет установлен `nonNullable`).

Его также можно внедрить по имени `NonNullableFormBuilder`.
# Создание template-driven формы

В этом руководстве показано, как создать template-driven форму. Элементы управления формы привязаны к свойствам данных с валидацией ввода. Валидация помогает сохранять целостность данных, а стилизация — улучшать пользовательский опыт.

Template-driven формы используют [двустороннюю привязку данных](guide/templates/two-way-binding), чтобы обновлять модель данных в компоненте при изменениях в шаблоне и наоборот.
Angular поддерживает два подхода к интерактивным формам. Template-driven формы позволяют использовать специфичные для форм директивы в шаблоне Angular. Reactive forms дают model-driven подход к построению форм.

Template-driven формы хорошо подходят для небольших или простых форм, а reactive forms более масштабируемы и удобны для сложных форм. Сравнение двух подходов см. в [Выбор подхода](guide/forms#choosing-an-approach)
С помощью шаблона Angular можно построить почти любую форму — формы входа, контактные формы и практически любую бизнес-форму.
Элементы управления можно размещать творчески и привязывать к данным объектной модели.
Можно задавать правила валидации и показывать ошибки, условно разрешать ввод из конкретных контролов, включать встроенную визуальную обратную связь и многое другое.

## Цели {#objectives}

Это руководство учит, как:

- Создать форму Angular с компонентом и шаблоном
- Использовать `ngModel` для двусторонней привязки данных для чтения и записи значений input-контролов
- Давать визуальную обратную связь с помощью специальных CSS-классов, отслеживающих состояние контролов
- Показывать пользователям ошибки валидации и условно разрешать ввод из контролов формы на основе статуса формы
- Делиться информацией между HTML-элементами через [template reference variables](guide/templates/variables#template-reference-variables)

## Создание template-driven формы {#build-a-template-driven-form}

Template-driven формы опираются на директивы, определённые в `FormsModule`.

| Директивы      | Описание                                                                                                                                                                                                                                                                         |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NgModel`      | Согласует изменения значения привязанного элемента формы с изменениями модели данных, позволяя реагировать на ввод пользователя валидацией и обработкой ошибок.                                                                                                           |
| `NgForm`       | Создаёт экземпляр `FormGroup` верхнего уровня и привязывает его к элементу `<form>`, чтобы отслеживать агрегированное значение формы и статус валидации. Как только вы импортируете `FormsModule`, эта директива по умолчанию активна на всех тегах `<form>`. Специальный селектор добавлять не нужно. |
| `NgModelGroup` | Создаёт и привязывает экземпляр `FormGroup` к DOM-элементу.                                                                                                                                                                                                                      |

### Обзор шагов {#step-overview}

В ходе этого руководства вы привяжете пример формы к данным и обработаете ввод пользователя по следующим шагам.

1. Создайте базовую форму.
   - Определите пример модели данных
   - Подключите необходимую инфраструктуру, например `FormsModule`
1. Привяжите контролы формы к свойствам данных через директиву `ngModel` и синтаксис двусторонней привязки.
   - Изучите, как `ngModel` сообщает о состояниях контрола через CSS-классы
   - Задайте имена контролам, чтобы они были доступны `ngModel`
1. Отслеживайте валидность ввода и статус контрола через `ngModel`.
   - Добавьте пользовательский CSS для визуальной обратной связи о статусе
   - Показывайте и скрывайте сообщения об ошибках валидации
1. Реагируйте на нативное событие клика HTML-кнопки, добавляя данные в модель.
1. Обработайте отправку формы через output-свойство [`ngSubmit`](api/forms/NgForm#properties) формы.
   - Отключайте кнопку **Submit**, пока форма невалидна
   - После отправки замените заполненную форму другим содержимым на странице

## Создание формы {#build-the-form}

1. В предоставленном примере приложения создаётся класс `Actor`, который определяет модель данных, отражённую в форме.

<docs-code header="actor.ts" language="typescript" path="adev/src/content/examples/forms/src/app/actor.ts"/>

1. Разметка и детали формы определены в классе `ActorFormComponent`.

<docs-code header="actor-form.component.ts (v1)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="v1"/>

Значение `selector` компонента `"app-actor-form"` означает, что форму можно вставить в родительский шаблон тегом `<app-actor-form>`.

1. Следующий код создаёт новый экземпляр актёра, чтобы начальная форма могла показать пример актёра.

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" region="Marilyn"/>

В этой демонстрации для `model` и `skills` используются фиктивные данные.
   В реальном приложении вы бы внедрили сервис данных для получения и сохранения реальных данных или открыли эти свойства как inputs и outputs.

1. Компонент включает возможность Forms, импортируя модуль `FormsModule`.

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" region="imports"/>

1. Форма отображается в макете приложения, определённом шаблоном корневого компонента.

<docs-code header="app.component.html" language="html" path="adev/src/content/examples/forms/src/app/app.component.html"/>

Начальный шаблон задаёт макет формы с двумя группами полей и кнопкой отправки.
   Группы полей соответствуют двум свойствам модели данных Actor: name и studio.
   У каждой группы есть метка и поле для ввода пользователя.
   - У `<input>` **Name** есть HTML5-атрибут `required`
   - У `<input>` **Studio** его нет, потому что `studio` необязателен

У кнопки **Submit** есть классы для стилизации.
   На этом этапе макет формы — обычный HTML5 без привязок и директив.

1. Пример формы использует несколько классов стилей из [Twitter Bootstrap](https://getbootstrap.com/css): `container`, `form-group`, `form-control` и `btn`.
   Чтобы использовать эти стили, таблица стилей приложения импортирует библиотеку.

<docs-code header="styles.css" path="adev/src/content/examples/forms/src/styles.1.css"/>

1. Форма требует, чтобы навык актёра выбирался из предопределённого списка `skills`, хранящегося внутри `ActorFormComponent`.
   Цикл Angular `@for` перебирает значения данных, чтобы заполнить элемент `<select>`.

<docs-code header="actor-form.component.html (skills)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="skills"/>

Если запустить приложение прямо сейчас, в элементе выбора виден список навыков.
Элементы ввода ещё не привязаны к значениям данных или событиям, поэтому они пусты и не имеют поведения.

## Привязка input-контролов к свойствам данных {#bind-input-controls-to-data-properties}

Следующий шаг — привязать input-контролы к соответствующим свойствам `Actor` двусторонней привязкой данных, чтобы они реагировали на ввод пользователя обновлением модели данных и на программные изменения данных — обновлением отображения.

Директива `ngModel`, объявленная в `FormsModule`, позволяет привязывать контролы в template-driven форме к свойствам модели данных.
Когда директива включается синтаксисом двусторонней привязки `[(ngModel)]`, Angular может отслеживать значение и взаимодействие пользователя с контролом и синхронизировать представление с моделью.

1. Отредактируйте файл шаблона `actor-form.component.html`.
1. Найдите тег `<input>` рядом с меткой **Name**.
1. Добавьте директиву `ngModel` с синтаксисом двусторонней привязки `[(ngModel)]="..."`.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngModelName-1"/>

HELPFUL: В этом примере после каждого тега input временно стоит диагностическая интерполяция `{{model.name}}`, чтобы показать текущее значение соответствующего свойства. Комментарий напоминает удалить диагностические строки, когда вы закончите наблюдать работу двусторонней привязки.

### Доступ к общему статусу формы {#access-the-overall-form-status}

Когда вы импортировали `FormsModule` в компонент, Angular автоматически создал и прикрепил директиву [NgForm](api/forms/NgForm) к тегу `<form>` в шаблоне (потому что у `NgForm` селектор `form`, совпадающий с элементами `<form>`).

Чтобы получить доступ к `NgForm` и общему статусу формы, объявите [template reference variable](guide/templates/variables#template-reference-variables).

1. Отредактируйте файл шаблона `actor-form.component.html`.
1. Обновите тег `<form>` template reference variable `#actorForm` и задайте её значение следующим образом.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="template-variable"/>

Template variable `actorForm` теперь ссылается на экземпляр директивы `NgForm`, управляющий формой в целом.

1. Запустите приложение.
1. Начните вводить текст в поле **Name**.

По мере добавления и удаления символов вы видите, как они появляются и исчезают в модели данных.

Диагностическая строка с интерполированными значениями показывает, что значения действительно текут из поля ввода в модель и обратно.

### Именование элементов управления {#naming-control-elements}

Когда на элементе используется `[(ngModel)]`, для этого элемента нужно определить атрибут `name`.
Angular использует назначенное имя, чтобы зарегистрировать элемент у директивы `NgForm`, прикреплённой к родительскому элементу `<form>`.

В примере к элементу `<input>` добавлен атрибут `name` со значением "name", что логично для имени актёра.
Подойдёт любое уникальное значение, но описательное имя удобнее.

1. Добавьте аналогичные привязки `[(ngModel)]` и атрибуты `name` к **Studio** и **Skill**.
1. Теперь можно удалить диагностические сообщения с интерполированными значениями.
1. Чтобы подтвердить, что двусторонняя привязка работает для всей модели актёра, добавьте в начало шаблона компонента новую текстовую привязку с pipe [`json`](api/common/JsonPipe), которая сериализует данные в строку.

После этих правок шаблон формы должен выглядеть так:

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngModel-2"/>

Обратите внимание:

- У каждого элемента `<input>` есть свойство `id`.
  Его использует атрибут `for` элемента `<label>`, чтобы связать метку с input-контролом.
  Это [стандартная возможность HTML](https://developer.mozilla.org/docs/Web/HTML/Element/label).

- У каждого элемента `<input>` также есть обязательное свойство `name`, которое Angular использует для регистрации контрола в форме.

Когда вы наблюдали эффекты, текстовую привязку `{{ model | json }}` можно удалить.

## Отслеживание состояний формы {#track-form-states}

Angular применяет класс `ng-submitted` к элементам `form` после отправки формы. Этот класс можно использовать, чтобы изменить стиль формы после отправки.

## Отслеживание состояний контрола {#track-control-states}

Добавление директивы `NgModel` к контролу добавляет к нему имена классов, описывающие его состояние.
Эти классы можно использовать, чтобы менять стиль контрола в зависимости от состояния.

В следующей таблице описаны имена классов, которые Angular применяет в зависимости от состояния контрола.

Angular также применяет класс `ng-submitted` к элементам `form` при отправке, но не к контролам внутри элемента `form`.

Эти CSS-классы используют, чтобы задать стили контрола в зависимости от его статуса.

### Наблюдение за состояниями контрола {#observe-control-states}

Чтобы увидеть, как фреймворк добавляет и удаляет классы, откройте инструменты разработчика браузера и осмотрите элемент `<input>`, представляющий имя актёра.

1. С помощью инструментов разработчика браузера найдите элемент `<input>`, соответствующий полю **Name**.
   Видно, что у элемента несколько CSS-классов в дополнение к "form-control".

1. При первом открытии классы указывают, что значение валидно, не менялось с инициализации или сброса и контрол не посещался с инициализации или сброса.

```html
<input class="form-control ng-untouched ng-pristine ng-valid" />
   ```

1. Выполните следующие действия с полем **Name** `<input>` и наблюдайте, какие классы появляются.
   - Посмотрите, но не трогайте.
     Классы указывают, что контрол untouched, pristine и valid.

- Кликните внутри поля имени, затем кликните снаружи.
     Контрол теперь посещён, и у элемента класс `ng-touched` вместо `ng-untouched`.

- Добавьте слэши в конец имени.
     Теперь контрол touched и dirty.

- Сотрите имя.
     Значение становится невалидным, поэтому класс `ng-invalid` заменяет `ng-valid`.

### Визуальная обратная связь для состояний {#create-visual-feedback-for-states}

Пара `ng-valid`/`ng-invalid` особенно интересна, потому что при невалидных значениях нужен
сильный визуальный сигнал.
Также нужно отмечать обязательные поля.

Обязательные поля и невалидные данные можно отметить одновременно цветной полосой
слева от поля ввода.

Чтобы изменить внешний вид таким образом, выполните следующие шаги.

1. Добавьте определения для CSS-классов `ng-*`.
1. Добавьте эти определения классов в новый файл `forms.css`.
1. Добавьте новый файл в проект рядом с `index.html`:

<docs-code header="forms.css" language="css" path="adev/src/content/examples/forms/src/assets/forms.css"/>

1. В файле `index.html` обновите тег `<head>`, чтобы подключить новую таблицу стилей.

<docs-code header="index.html (styles)" path="adev/src/content/examples/forms/src/index.html" region="styles"/>

### Показ и скрытие сообщений об ошибках валидации {#show-and-hide-validation-error-messages}

Поле **Name** обязательно, и его очистка делает полосу красной.
Это указывает, что что-то не так, но пользователь не знает, что именно и что делать.
Можно дать полезное сообщение, проверяя состояние контрола и реагируя на него.

Выпадающий список **Skill** тоже обязателен, но ему не нужна такая обработка ошибок, потому что список уже ограничивает выбор валидными значениями.

Чтобы определить и показать сообщение об ошибке в нужный момент, выполните следующие шаги.

<docs-workflow>
<docs-step title="Add a local reference to the input">
Расширьте тег `input` template reference variable, чтобы из шаблона обращаться к Angular-контролу поля ввода. В примере переменная — `#name="ngModel"`.

Template reference variable (`#name`) задаётся как `"ngModel"`, потому что это значение свойства [`NgModel.exportAs`](api/core/Directive#exportAs). Это свойство говорит Angular, как связать reference variable с директивой.
</docs-step>

<docs-step title="Add the error message">
Добавьте `<div>` с подходящим сообщением об ошибке.
</docs-step>

<docs-step title="Make the error message conditional">
Показывайте или скрывайте сообщение об ошибке, привязав свойства контрола `name` к свойству `hidden` элемента `<div>` сообщения.
</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" region="hidden-error-msg"/>

<docs-step title="Add a conditional error message to name">
Добавьте условное сообщение об ошибке к полю `name`, как в следующем примере.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="name-with-error-msg"/>
</docs-step>
</docs-workflow>
В этом примере сообщение скрывается, когда контрол либо валиден, либо _pristine_.
Pristine означает, что пользователь не менял значение с момента отображения в этой форме.
Если игнорировать состояние `pristine`, сообщение скрывалось бы только при валидном значении.
Если попасть в этот компонент с новым пустым актёром или невалидным актёром, сообщение об ошибке появится сразу, до любых действий.

Возможно, сообщение нужно показывать только когда пользователь делает невалидное изменение.
Скрытие сообщения, пока контрол в состоянии `pristine`, достигает этой цели.
Значимость этого выбора станет ясна, когда в следующем шаге вы добавите нового актёра в форму.
## Добавление нового актёра {#add-a-new-actor}

Это упражнение показывает, как реагировать на нативное событие клика HTML-кнопки, добавляя данные в модель.
Чтобы пользователи формы могли добавить нового актёра, добавьте кнопку **New Actor**, реагирующую на событие click.

1. В шаблоне разместите элемент `<button>` "New Actor" внизу формы.
1. В файле компонента добавьте метод создания актёра в модель данных актёра.

<docs-code header="actor-form.component.ts (New Actor method)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="new-actor"/>

1. Привяжите событие click кнопки к методу создания актёра `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" region="new-actor-button-no-reset"/>

1. Снова запустите приложение и нажмите кнопку **New Actor**.

Форма очищается, и _обязательные_ полосы слева от полей ввода красные, указывая на невалидные свойства `name` и `skill`.
   Обратите внимание, что сообщения об ошибках скрыты.
   Это потому, что форма pristine: вы ещё ничего не меняли.

1. Введите имя и снова нажмите **New Actor**.

Теперь приложение показывает сообщение об ошибке `Name is required`, потому что поле ввода больше не pristine.
   Форма помнит, что вы вводили имя до нажатия **New Actor**.

1. Чтобы восстановить pristine-состояние контролов формы, сбросьте все флаги императивно, вызвав метод формы `reset()` после вызова `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" region="new-actor-button-form-reset"/>

Теперь нажатие **New Actor** сбрасывает и форму, и флаги её контролов.

## Отправка формы с `ngSubmit` {#submit-the-form-with-ngsubmit}

Пользователь должен иметь возможность отправить эту форму после заполнения.
Кнопка **Submit** внизу формы сама по себе ничего не делает, но запускает событие отправки формы из-за своего типа (`type="submit"`).

Чтобы отреагировать на это событие, выполните следующие шаги.

<docs-workflow>

<docs-step title="Listen to ngOnSubmit">
Привяжите событие [`ngSubmit`](api/forms/NgForm#properties) формы к методу `onSubmit()` компонента actor-form.

<docs-code header="actor-form.component.html (ngSubmit)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngSubmit"/>
</docs-step>

<docs-step title="Bind the disabled property">
Используйте template reference variable `#actorForm`, чтобы получить доступ к форме, содержащей кнопку **Submit**, и создайте привязку события.

Привяжите свойство формы, указывающее на её общую валидность, к свойству `disabled` кнопки **Submit**.

<docs-code header="actor-form.component.html (submit-button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="submit-button"/>
</docs-step>

<docs-step title="Run the application">
Обратите внимание, что кнопка включена — хотя пока ничего полезного не делает.
</docs-step>

<docs-step title="Delete the Name value">
Это нарушает правило "required", поэтому показывается сообщение об ошибке — и обратите внимание, что кнопка **Submit** также отключается.

Не пришлось явно связывать состояние включения кнопки с валидностью формы.
`FormsModule` сделал это автоматически, когда вы определили template reference variable на расширенном элементе формы, а затем сослались на эту переменную в контроле кнопки.
</docs-step>
</docs-workflow>

### Реакция на отправку формы {#respond-to-form-submission}

Чтобы показать реакцию на отправку формы, можно скрыть область ввода данных и отобразить что-то другое на её месте.

<docs-workflow>
<docs-step title="Wrap the form">
Оберните всю форму в `<div>` и привяжите его свойство `hidden` к свойству `ActorFormComponent.submitted`.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="edit-div"/>

Основная форма видна с самого начала, потому что свойство `submitted` равно false, пока вы не отправите форму, как показывает этот фрагмент из `ActorFormComponent`:

<docs-code header="actor-form.component.ts (submitted)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="submitted"/>

Когда вы нажимаете кнопку **Submit**, флаг `submitted` становится true, и форма исчезает.
</docs-step>

<docs-step title="Add the submitted state">
Чтобы показать что-то другое, пока форма в состоянии submitted, добавьте следующий HTML ниже новой обёртки `<div>`.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="submitted"/>

Этот `<div>`, показывающий актёра только для чтения с интерполяционными привязками, появляется только пока компонент в состоянии submitted.

Альтернативное отображение включает кнопку _Edit_, событие click которой привязано к выражению, сбрасывающему флаг `submitted`.
</docs-step>

<docs-step title="Test the Edit button">
Нажмите кнопку *Edit*, чтобы вернуть отображение к редактируемой форме.
</docs-step>
</docs-workflow>

## Итог {#summary}

Форма Angular, рассмотренная на этой странице, использует следующие
возможности фреймворка для поддержки изменения данных, валидации и многого другого.

- HTML-шаблон формы Angular
- Класс компонента формы с декоратором `@Component`
- Обработка отправки формы привязкой к событию `NgForm.ngSubmit`
- Template-reference variables, такие как `#actorForm` и `#name`
- Синтаксис `[(ngModel)]` для двусторонней привязки данных
- Использование атрибутов `name` для валидации и отслеживания изменений элементов формы
- Свойство `valid` reference variable на input-контролах указывает, валиден ли контрол или нужно показать сообщения об ошибках
- Управление состоянием включения кнопки **Submit** привязкой к валидности `NgForm`
- Пользовательские CSS-классы, дающие пользователям визуальную обратную связь о невалидных контролах

Вот код финальной версии приложения:
# Валидация ввода формы

Валидация пользовательского ввода на точность и полноту повышает общее качество данных.
На этой странице показано, как валидировать ввод из UI и отображать полезные сообщения об ошибках — и в reactive, и в template-driven формах.

## Валидация ввода в template-driven формах {#validating-input-in-template-driven-forms}

Чтобы добавить валидацию в template-driven форму, используйте те же атрибуты валидации, что и при [нативной HTML-валидации форм](https://developer.mozilla.org/docs/Web/Guide/HTML/HTML5/Constraint_validation).
Angular сопоставляет эти атрибуты с функциями-валидаторами фреймворка через директивы.

При каждом изменении значения контрола формы Angular запускает валидацию и формирует либо список ошибок валидации со статусом `INVALID`, либо `null` со статусом `VALID`.

Состояние контрола можно проверить, экспортировав `ngModel` в локальную переменную шаблона.
В следующем примере `NgModel` экспортируется в переменную `name`:

<docs-code header="actor-form-template.component.html (name)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="name-with-error-msg"/>

Обратите внимание на особенности, которые иллюстрирует пример.

- Элемент `<input>` несёт HTML-атрибуты валидации: `required` и `minlength`.
  Также на нём есть пользовательская директива-валидатор `forbiddenName`.
  Подробнее см. в разделе [Пользовательские валидаторы](#defining-custom-validators).

- `#name="ngModel"` экспортирует `NgModel` в локальную переменную `name`.
  `NgModel` отражает многие свойства лежащего в основе экземпляра `FormControl`, поэтому в шаблоне можно проверять состояния контрола, например `valid` и `dirty`.
  Полный список свойств контрола см. в справочнике API [AbstractControl](api/forms/AbstractControl).
  - Внешний `@if` показывает набор вложенных сообщений только если `name` невалиден и контрол либо `dirty`, либо `touched`.

- Каждый вложенный `@if` может показать своё сообщение для одной из возможных ошибок валидации.
    Есть сообщения для `required`, `minlength` и `forbiddenName`.

HELPFUL: Чтобы валидатор не показывал ошибки до того, как пользователь успел отредактировать форму, проверяйте состояния `dirty` или `touched` у контрола.

- Когда пользователь меняет значение в отслеживаемом поле, контрол помечается как "dirty"
- Когда пользователь уводит фокус с элемента контрола формы, контрол помечается как "touched"

## Валидация ввода в reactive формах {#validating-input-in-reactive-forms}

В reactive форме источником истины является класс компонента.
Вместо атрибутов в шаблоне функции-валидаторы добавляются напрямую к модели контрола формы в классе компонента.
Angular вызывает эти функции при каждом изменении значения контрола.

### Функции-валидаторы {#validator-functions}

Функции-валидаторы могут быть синхронными или асинхронными.

| Тип валидатора   | Описание                                                                                                                                                                                                                 |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sync validators  | Синхронные функции, которые принимают экземпляр контрола и сразу возвращают набор ошибок валидации или `null`. Передаются вторым аргументом при создании `FormControl`.                       |
| Async validators | Асинхронные функции, которые принимают экземпляр контрола и возвращают Promise или Observable, который позже эмитит набор ошибок валидации или `null`. Передаются третьим аргументом при создании `FormControl`. |

Из соображений производительности Angular запускает async-валидаторы только если все sync-валидаторы прошли успешно.
Каждый из них должен завершиться, прежде чем будут установлены ошибки.

### Встроенные функции-валидаторы {#built-in-validator-functions}

Можно [написать собственные функции-валидаторы](#defining-custom-validators) или использовать встроенные валидаторы Angular.

Те же встроенные валидаторы, что доступны как атрибуты в template-driven формах (`required`, `minlength` и другие), доступны и как функции класса `Validators`.
Полный список встроенных валидаторов см. в справочнике API [Validators](api/forms/Validators).

Чтобы сделать форму актёра reactive, используйте те же
встроенные валидаторы — на этот раз в виде функций, как в следующем примере.

<docs-code header="actor-form-reactive.component.ts (validator functions)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" region="form-group"/>

В этом примере контрол `name` настраивает два встроенных валидатора —`Validators.required` и `Validators.minLength(4)`— и один пользовательский, `forbiddenNameValidator`.

Все эти валидаторы синхронные, поэтому передаются вторым аргументом.
Несколько валидаторов можно передать массивом функций.

В примере также добавлены несколько getter-методов.
В reactive форме к любому контролу всегда можно обратиться через метод `get` родительской группы, но иногда удобно определить getters как сокращения для шаблона.

Если снова посмотреть на шаблон для input `name`, он довольно похож на template-driven пример.

<docs-code header="actor-form-reactive.component.html (name with error msg)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" region="name-with-error-msg"/>

Эта форма отличается от template-driven версии тем, что больше не экспортирует директивы. Вместо этого используется getter `name`, определённый в классе компонента.

Обратите внимание, что атрибут `required` по-прежнему присутствует в шаблоне. Для валидации он не обязателен, но его стоит оставить ради доступности.

## Определение пользовательских валидаторов {#defining-custom-validators}

Встроенные валидаторы не всегда покрывают точный сценарий приложения, поэтому иногда нужно создать пользовательский валидатор.

Рассмотрим функцию `forbiddenNameValidator` из предыдущего примера.
Вот как выглядит её определение.

<docs-code header="forbidden-name.directive.ts (forbiddenNameValidator)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="custom-validator"/>

Функция — фабрика: она принимает регулярное выражение для обнаружения _конкретного_ запрещённого имени и возвращает функцию-валидатор.

В этом примере запрещённое имя — "bob", поэтому валидатор отклоняет любое имя актёра, содержащее "bob".
В другом месте он мог бы отклонять "alice" или любое имя, которое совпадает с настроенным регулярным выражением.

Фабрика `forbiddenNameValidator` возвращает настроенную функцию-валидатор.
Эта функция принимает объект контрола Angular и возвращает _либо_ null, если значение контрола валидно, _либо_ объект ошибки валидации.
У объекта ошибки валидации обычно есть свойство с именем ключа валидации `'forbiddenName'` и значением — произвольным словарём данных, которые можно подставить в сообщение об ошибке, `{name}`.

Пользовательские async-валидаторы похожи на sync-валидаторы, но вместо этого должны возвращать Promise или observable, который позже эмитит null или объект ошибки валидации.
В случае observable поток должен завершиться; форма использует последнее эмитированное значение для валидации.

### Добавление пользовательских валидаторов в reactive формы {#adding-custom-validators-to-reactive-forms}

В reactive формах пользовательский валидатор добавляется передачей функции напрямую в `FormControl`.

<docs-code header="actor-form-reactive.component.ts (validator functions)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" region="custom-validator"/>

### Добавление пользовательских валидаторов в template-driven формы {#adding-custom-validators-to-template-driven-forms}

В template-driven формах в шаблон добавляется директива, которая оборачивает функцию-валидатор.
Например, соответствующая `ForbiddenValidatorDirective` служит обёрткой вокруг `forbiddenNameValidator`.

Angular распознаёт роль директивы в процессе валидации, потому что директива регистрирует себя через провайдер `NG_VALIDATORS`, как показано в следующем примере.
`NG_VALIDATORS` — предопределённый провайдер с расширяемой коллекцией валидаторов.

<docs-code header="forbidden-name.directive.ts (providers)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="directive-providers"/>

Класс директивы затем реализует интерфейс `Validator`, чтобы легко интегрироваться с формами Angular.
Ниже — остальная часть директивы, чтобы было понятно, как всё складывается вместе.

<docs-code header="forbidden-name.directive.ts (directive)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="directive"/>

Когда `ForbiddenValidatorDirective` готова, её селектор `appForbiddenName` можно добавить к любому input-элементу, чтобы активировать её.
Например:

<docs-code header="actor-form-template.component.html (forbidden-name-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="name-input"/>

HELPFUL: Обратите внимание, что пользовательская директива валидации создаётся с `useExisting`, а не с `useClass`.
Зарегистрированный валидатор должен быть _именно этим экземпляром_ `ForbiddenValidatorDirective` — экземпляром в форме со свойством `forbiddenName`, привязанным к "bob".

Если заменить `useExisting` на `useClass`, будет зарегистрирован новый экземпляр класса без `forbiddenName`.

## CSS-классы статуса контрола {#control-status-css-classes}

Angular автоматически отражает многие свойства контрола на элемент контрола формы в виде CSS-классов.
Используйте эти классы, чтобы стилизовать элементы контролов в соответствии с состоянием формы.
Сейчас поддерживаются следующие классы.

- `.ng-valid`
- `.ng-invalid`
- `.ng-pending`
- `.ng-pristine`
- `.ng-dirty`
- `.ng-untouched`
- `.ng-touched`
- `.ng-submitted` $только на охватывающем элементе формы$

В следующем примере форма актёра использует классы `.ng-valid` и `.ng-invalid`, чтобы
задать цвет границы каждого контрола формы.

<docs-code header="forms.css (status classes)" path="adev/src/content/examples/form-validation/src/assets/forms.css"/>

## Кросс-полевая валидация {#cross-field-validation}

Кросс-полевой валидатор — это [пользовательский валидатор](#defining-custom-validators 'Читать о пользовательских валидаторах'), который сравнивает значения разных полей формы и принимает или отклоняет их в совокупности.
Например, в форме могут быть взаимоисключающие варианты: пользователь может выбрать A или B, но не оба.
Некоторые значения полей могут зависеть от других: выбрать B разрешено только если также выбрано A.

Следующие примеры кросс-валидации показывают, как:

- Валидировать ввод reactive или template-based формы на основе значений двух соседних контролов,
- Показать понятное сообщение об ошибке после того, как пользователь взаимодействовал с формой и валидация не прошла.

В примерах кросс-валидация гарантирует, что актёры не используют одно и то же имя в роли при заполнении Actor Form.
Валидаторы проверяют, что имена актёров и роли не совпадают.

### Добавление кросс-валидации в reactive формы {#adding-cross-validation-to-reactive-forms}

Форма имеет следующую структуру:

```ts
const actorForm = new FormGroup({
  'name': new FormControl(),
  'role': new FormControl(),
  'skill': new FormControl(),
});
```

Обратите внимание, что `name` и `role` — соседние контролы.
Чтобы оценить оба контрола в одном пользовательском валидаторе, валидацию нужно выполнять в общем предке: `FormGroup`.
У `FormGroup` запрашиваются дочерние контролы, чтобы сравнить их значения.

Чтобы добавить валидатор к `FormGroup`, передайте новый валидатор вторым аргументом при создании.

```ts
const actorForm = new FormGroup(
  {
    'name': new FormControl(),
    'role': new FormControl(),
    'skill': new FormControl(),
  },
  {validators: unambiguousRoleValidator},
);
```

Код валидатора выглядит так.

<docs-code header="unambiguous-role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/unambiguous-role.directive.ts" region="cross-validation-validator"/>

Валидатор `unambiguousRoleValidator` реализует интерфейс `ValidatorFn`.
Он принимает объект контрола Angular и возвращает либо null, если форма валидна, либо `ValidationErrors` в противном случае.

Валидатор получает дочерние контролы через метод [get](api/forms/AbstractControl#get) у `FormGroup`, затем сравнивает значения контролов `name` и `role`.

Если значения не совпадают, роль однозначна, оба валидны, и валидатор возвращает null.
Если совпадают, роль актёра неоднозначна, и валидатор должен пометить форму как невалидную, вернув объект ошибки.

Для лучшего UX шаблон показывает подходящее сообщение об ошибке, когда форма невалидна.

<docs-code header="actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" region="cross-validation-error-message"/>

Этот `@if` показывает ошибку, если у `FormGroup` есть ошибка кросс-валидации от `unambiguousRoleValidator`, но только если пользователь завершил [взаимодействие с формой](#control-status-css-classes).

### Добавление кросс-валидации в template-driven формы {#adding-cross-validation-to-template-driven-forms}

Для template-driven формы нужно создать директиву, оборачивающую функцию-валидатор.
Эту директиву предоставляют как валидатор через [`NG_VALIDATORS` token](/api/forms/NG_VALIDATORS), как показано в следующем примере.

<docs-code header="unambiguous-role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/unambiguous-role.directive.ts" region="cross-validation-directive"/>

Новую директиву нужно добавить в HTML-шаблон.
Поскольку валидатор должен быть зарегистрирован на самом верхнем уровне формы, в следующем шаблоне директива ставится на тег `form`.

<docs-code header="actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="cross-validation-register-validator"/>

Для лучшего UX при невалидной форме появляется подходящее сообщение об ошибке.

<docs-code header="actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="cross-validation-error-message"/>

Это одинаково и для template-driven, и для reactive форм.

## Создание асинхронных валидаторов {#creating-asynchronous-validators}

Асинхронные валидаторы реализуют интерфейсы `AsyncValidatorFn` и `AsyncValidator`.
Они очень похожи на синхронные аналоги, со следующими отличиями.

- Функции `validate()` должны возвращать Promise или observable,
- Возвращаемый observable должен быть конечным, то есть в какой-то момент завершиться.
  Чтобы превратить бесконечный observable в конечный, пропустите его через фильтрующий оператор, например `first`, `last`, `take` или `takeUntil`.

Асинхронная валидация выполняется после синхронной и только если синхронная валидация успешна.
Эта проверка позволяет формам избегать потенциально дорогих async-процессов валидации $например, HTTP-запроса$, если более базовые методы валидации уже нашли невалидный ввод.

После начала асинхронной валидации контрол формы переходит в состояние `pending`.
Проверяйте свойство `pending` контрола и используйте его для визуальной обратной связи о текущей операции валидации.

Распространённый UI-паттерн — показывать спиннер, пока выполняется async-валидация.
Следующий пример показывает, как сделать это в template-driven форме.

```html
<input [(ngModel)]="name" #model="ngModel" appSomeAsyncValidator />

@if (model.pending) {
  <app-spinner />
}
```

### Реализация пользовательского async-валидатора {#implementing-a-custom-async-validator}

В следующем примере async-валидатор гарантирует, что актёры назначаются на роль, которая ещё не занята.
Новые актёры постоянно проходят пробы, старые уходят на пенсию, поэтому список доступных ролей нельзя получить заранее.
Чтобы валидировать потенциальный ввод роли, валидатор должен инициировать асинхронную операцию — обратиться к центральной базе всех текущих актёров.

Следующий код создаёт класс валидатора `UniqueRoleValidator`, реализующий интерфейс `AsyncValidator`.

<docs-code header="role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" region="async-validator"/>

Свойство `actorsService` инициализируется экземпляром токена `ActorsService`, который определяет следующий интерфейс.

```ts
interface ActorsService {
  isRoleTaken: (role: string) => Observable<boolean>;
}
```

В реальном приложении `ActorsService` отвечал бы за HTTP-запрос к базе актёров, чтобы проверить доступность роли.
С точки зрения валидатора конкретная реализация сервиса не важна, поэтому пример может опираться только на интерфейс `ActorsService`.

Когда валидация начинается, `UniqueRoleValidator` делегирует методу `ActorsService` `isRoleTaken()` текущее значение контрола.
В этот момент контрол помечается как `pending` и остаётся в этом состоянии, пока цепочка observable, возвращённая из `validate()`, не завершится.

Метод `isRoleTaken()` отправляет HTTP-запрос, проверяющий доступность роли, и возвращает `Observable<boolean>` как результат.
Метод `validate()` пропускает ответ через оператор `map` и преобразует его в результат валидации.

Затем метод, как любой валидатор, возвращает `null`, если форма валидна, и `ValidationErrors`, если нет.
Этот валидатор обрабатывает возможные ошибки оператором `catchError`.
В данном случае ошибка `isRoleTaken()` трактуется как успешная валидация, потому что сбой запроса валидации не обязательно означает, что роль невалидна.
Ошибку можно обработать иначе и вместо этого вернуть объект `ValidationError`.

Через некоторое время цепочка observable завершается, и асинхронная валидация закончена.
Флаг `pending` становится `false`, и валидность формы обновляется.

### Добавление async-валидаторов в reactive формы {#adding-async-validators-to-reactive-forms}

Чтобы использовать async-валидатор в reactive формах, сначала внедрите валидатор в свойство класса компонента.

<docs-code header="actor-form-reactive.component.2.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-inject"/>

Затем передайте функцию-валидатор напрямую в `FormControl`, чтобы применить её.

В следующем примере функция `validate` у `UniqueRoleValidator` применяется к `roleControl` через опцию `asyncValidators` контрола с привязкой к экземпляру `UniqueRoleValidator`, внедрённому в `ActorFormReactiveComponent`.
Значение `asyncValidators` может быть одной async-функцией-валидатором или массивом функций.
Подробнее об опциях `FormControl` см. в справочнике API [AbstractControlOptions](api/forms/AbstractControlOptions).

<docs-code header="actor-form-reactive.component.2.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-usage"/>

### Добавление async-валидаторов в template-driven формы {#adding-async-validators-to-template-driven-forms}

Чтобы использовать async-валидатор в template-driven формах, создайте новую директиву и зарегистрируйте на ней провайдер `NG_ASYNC_VALIDATORS`.

В примере ниже директива внедряет класс `UniqueRoleValidator` с фактической логикой валидации и вызывает его в функции `validate`, которую Angular запускает, когда нужна валидация.

<docs-code header="role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" region="async-validator-directive"/>

Затем, как и с синхронными валидаторами, добавьте селектор директивы к input, чтобы активировать её.

<docs-code header="actor-form-template.component.html (unique-unambiguous-role-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="role-input"/>

### Оптимизация производительности async-валидаторов {#optimizing-performance-of-async-validators}

По умолчанию все валидаторы запускаются после каждого изменения значения формы.
У синхронных валидаторов это обычно не заметно влияет на производительность приложения.
Async-валидаторы же часто выполняют HTTP-запрос для валидации контрола.
Отправлять HTTP-запрос после каждого нажатия клавиши может нагружать backend API, и этого по возможности стоит избегать.

Обновление валидности формы можно отложить, изменив свойство `updateOn` с `change` (по умолчанию) на `submit` или `blur`.

В template-driven формах свойство задаётся в шаблоне.

```html
<input [(ngModel)]="name" [ngModelOptions]="{updateOn: 'blur'}" />
```

В reactive формах свойство задаётся в экземпляре `FormControl`.

```ts
new FormControl('', {updateOn: 'blur'});
```

## Динамическое управление валидаторами в reactive формах {#managing-validators-dynamically-in-reactive-forms}

В сложных reactive формах может понадобиться добавлять, удалять или изменять валидаторы на основе ввода пользователя или состояния приложения.
Angular предоставляет несколько методов на `AbstractControl` для управления валидаторами во время выполнения без пересоздания контролов формы.

### Добавление и удаление валидаторов {#adding-and-removing-validators}

Методы [`addValidators`](api/forms/AbstractControl#addValidators) и [`removeValidators`](api/forms/AbstractControl#removeValidators) позволяют изменять валидаторы контрола после инициализации.

```ts
onCountryChange(country: string) {
    const postalCodeControl = this.profileForm.get('postalCode');

if (country === 'US') {
      // Add validators for US postal codes
      postalCodeControl.addValidators([Validators.required, Validators.pattern(/^\d{5}$/)]);
    } else {
      // Remove validators when not US
      postalCodeControl.removeValidators([Validators.required]);
    }

postalCodeControl.updateValueAndValidity();
}
```

### Замена всех валидаторов {#replacing-all-validators}

Используйте [`setValidators`](api/forms/AbstractControl#setValidators), чтобы заменить все существующие синхронные валидаторы контрола, или [`clearValidators`](api/forms/AbstractControl#clearValidators), чтобы удалить все валидаторы.

```ts
toggleStrictNameValidation(isStrict: boolean) {
  const nameControl = this.profileForm.get('name');

if (enable) {
    // Set strict validation rules
    nameControl.setValidators([
      Validators.required,
      Validators.minLength(3),
      Validators.pattern(/^[a-zA-Z]+$/),
    ]);
  } else {
    // Clear all validators
    nameControl.clearValidators();
  }

nameControl.updateValueAndValidity();
}
```

Тот же паттерн применяется к async-валидаторам через [`addAsyncValidators`](api/forms/AbstractControl#addAsyncValidators), [`removeAsyncValidators`](api/forms/AbstractControl#removeAsyncValidators), [`setAsyncValidators`](api/forms/AbstractControl#setAsyncValidators) и [`clearAsyncValidators`](api/forms/AbstractControl#clearAsyncValidators).

### Запуск обновления валидации {#triggering-validation-updates}

После изменения валидаторов вызовите [`updateValueAndValidity`](api/forms/AbstractControl#updateValueAndValidity), чтобы пересчитать статус валидации контрола.
Метод принимает опции для управления поведением обновления.

```ts
// Update control and notify parent
control.updateValueAndValidity();

// Update control only, don't notify parent or emit events
control.updateValueAndValidity({onlySelf: true, emitEvent: false});
```

## Взаимодействие с нативной HTML-валидацией форм {#interaction-with-native-html-form-validation}

По умолчанию Angular отключает [нативную HTML-валидацию форм](https://developer.mozilla.org/docs/Web/Guide/HTML/Constraint_validation), добавляя атрибут `novalidate` на охватывающий `<form>`, и использует директивы для сопоставления этих атрибутов с функциями-валидаторами фреймворка.
Если нужно использовать нативную валидацию **вместе** с валидацией на основе Angular, её можно снова включить директивой `ngNativeValidate`.
Подробности см. в [документации API](api/forms/NgForm#native-dom-validation-ui).
# Создание динамических форм

Многие формы, например анкеты, могут быть очень похожи друг на друга по формату и назначению.
Чтобы быстрее и проще генерировать разные версии такой формы, можно создать _шаблон динамической формы_ на основе метаданных, описывающих модель бизнес-объекта.
Затем используйте шаблон для автоматической генерации новых форм в соответствии с изменениями модели данных.

Техника особенно полезна, когда есть тип формы, содержимое которой должно часто меняться, чтобы соответствовать быстро меняющимся бизнес- и регуляторным требованиям.
Типичный сценарий — анкета.
Может понадобиться получать ввод от пользователей в разных контекстах.
Формат и стиль форм, которые видит пользователь, должны оставаться постоянными, а фактические вопросы, которые нужно задать, меняются с контекстом.

В этом туториале вы создадите динамическую форму, представляющую базовую анкету.
Вы создаёте онлайн-заявку для героев, ищущих работу.
Агентство постоянно меняет процесс подачи заявки, но используя динамическую форму,
можно создавать новые формы на лету без изменения кода приложения.

Туториал проводит вас через следующие шаги:

1. Включить reactive forms для проекта.
1. Создать модель данных для представления form controls.
1. Заполнить модель примерными данными.
1. Разработать компонент для динамического создания form controls.

Создаваемая форма использует валидацию ввода и стилизацию для улучшения пользовательского опыта.
У неё есть кнопка Submit, которая включается только когда весь пользовательский ввод валиден, и помечает невалидный ввод цветовой кодировкой и сообщениями об ошибках.

Базовая версия может развиваться для поддержки более богатого разнообразия вопросов, более изящного рендера и лучшего пользовательского опыта.

## Включение reactive forms для проекта {#enable-reactive-forms-for-your-project}

Динамические формы основаны на reactive forms.

Чтобы дать приложению доступ к директивам reactive forms, импортируйте `ReactiveFormsModule` из пакета `@angular/forms` в необходимые компоненты.
## Создание объектной модели формы {#create-a-form-object-model}

Динамической форме нужна объектная модель, которая может описать все сценарии, требуемые функциональностью формы.
Пример формы заявки героя — набор вопросов: каждый control в форме должен задать вопрос и принять ответ.

Модель данных для такого типа формы должна представлять вопрос.
Пример включает `DynamicFormQuestionComponent`, который определяет вопрос как фундаментальный объект в модели.

Следующий `QuestionBase` — базовый класс для набора controls, которые могут представлять вопрос и его ответ в форме.

<docs-code header="question-base.ts" path="adev/src/content/examples/dynamic-form/src/app/question-base.ts"/>

### Определение классов controls {#define-control-classes}

От этой базы пример выводит два новых класса — `TextboxQuestion` и `DropdownQuestion` — представляющих разные типы controls.
Когда вы создадите шаблон формы на следующем шаге, вы создадите экземпляры этих конкретных типов вопросов, чтобы динамически рендерить соответствующие controls.

Тип control `TextboxQuestion` представляется в шаблоне формы элементом `<input>`. Он представляет вопрос и позволяет пользователям вводить данные. Атрибут `type` элемента определяется на основе поля `type`, указанного в аргументе `options` (например, `text`, `email`, `url`).

<docs-code header="question-textbox.ts" path="adev/src/content/examples/dynamic-form/src/app/question-textbox.ts"/>

Тип control `DropdownQuestion` представляет список вариантов в select box.

<docs-code header="question-dropdown.ts" path="adev/src/content/examples/dynamic-form/src/app/question-dropdown.ts"/>

### Композиция групп форм {#compose-form-groups}

Динамическая форма использует сервис для создания сгруппированных наборов input controls на основе модели формы.
Следующий `QuestionControlService` собирает набор экземпляров `FormGroup`, которые потребляют метаданные из модели вопроса.
Можно указать значения по умолчанию и правила валидации.

<docs-code header="question-control.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question-control.service.ts"/>

## Композиция содержимого динамической формы {#compose-dynamic-form-contents}

Сама динамическая форма представлена компонентом-контейнером, который вы добавите на более позднем шаге.
Каждый вопрос представляется в шаблоне компонента формы тегом `<app-question>`, который соответствует экземпляру `DynamicFormQuestionComponent`.

`DynamicFormQuestionComponent` отвечает за рендер деталей отдельного вопроса на основе значений в data-bound объекте вопроса.
Форма опирается на [директиву `[formGroup]`](api/forms/FormGroupDirective 'API reference') для связи HTML шаблона с underlying объектами controls.
`DynamicFormQuestionComponent` создаёт группы форм и заполняет их controls, определёнными в модели вопроса, указывая правила отображения и валидации.
Цель `DynamicFormQuestionComponent` — представлять типы вопросов, определённые в вашей модели.
Сейчас у вас только два типа вопросов, но можно представить гораздо больше.
Блок `@switch` в шаблоне определяет, какой тип вопроса отображать.
Switch использует директивы с селекторами [`formControlName`](api/forms/FormControlName 'FormControlName directive API reference') и [`formGroup`](api/forms/FormGroupDirective 'FormGroupDirective API reference').
Обе директивы определены в `ReactiveFormsModule`.

### Поставка данных {#supply-data}

Нужен ещё один сервис, чтобы поставлять конкретный набор вопросов, из которых строится отдельная форма.
Для этого упражнения вы создаёте `QuestionService` для поставки этого массива вопросов из захардкоженных примерных данных.
В реальном приложении сервис мог бы загружать данные из backend-системы.
Ключевой момент, однако, в том, что вы полностью контролируете вопросы заявки героя через объекты, возвращаемые из `QuestionService`.
Чтобы поддерживать анкету при изменении требований, нужно только добавлять, обновлять и удалять объекты из массива `questions`.

`QuestionService` поставляет набор вопросов в виде массива, привязанного к `input()` questions.

<docs-code header="question.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question.service.ts"/>

## Создание шаблона динамической формы {#create-a-dynamic-form-template}

Компонент `DynamicFormComponent` — точка входа и основной контейнер формы, представленный как `<app-dynamic-form>` в шаблоне.

Компонент `DynamicFormComponent` представляет список вопросов, привязывая каждый к элементу `<app-question>`, который соответствует `DynamicFormQuestionComponent`.
### Отображение формы {#display-the-form}

Чтобы отобразить экземпляр динамической формы, shell-шаблон `AppComponent` передаёт массив `questions`, возвращённый `QuestionService`, компоненту-контейнеру формы `<app-dynamic-form>`.

<docs-code header="app.component.ts" path="adev/src/content/examples/dynamic-form/src/app/app.component.ts"/>

Это разделение модели и данных позволяет переиспользовать компоненты для любого типа опроса, пока он совместим с объектной моделью _вопроса_.

### Обеспечение валидных данных {#ensuring-valid-data}

Шаблон формы использует динамическую привязку данных метаданных для рендера формы без каких-либо захардкоженных предположений о конкретных вопросах.
Он динамически добавляет и метаданные controls, и критерии валидации.

Чтобы обеспечить валидный ввод, кнопка _Save_ отключена, пока форма не в валидном состоянии.
Когда форма валидна, нажмите _Save_, и приложение отрендерит текущие значения формы как JSON.

Следующий рисунок показывает финальную форму.

## Следующие шаги {#next-steps}
Angular Router (`@angular/router`) — это официальная библиотека для управления навигацией в приложениях Angular и основная часть фреймворка. Она включена по умолчанию во все проекты, созданные с помощью Angular CLI.

## Зачем нужна маршрутизация в SPA? {#why-is-routing-necessary-in-a-spa}

Когда вы переходите по URL-адресу в веб-браузере, браузер обычно делает сетевой запрос к веб-серверу и отображает возвращенную HTML-страницу. Когда вы переходите по другому URL-адресу, например, нажимая на ссылку, браузер делает еще один сетевой запрос и заменяет всю страницу новой.

Одностраничное приложение (SPA) отличается тем, что браузер делает запрос к веб-серверу только для первой страницы, `index.html`. После этого клиентский роутер берет управление на себя, контролируя, какой контент отображается на основе URL-адреса. Когда пользователь переходит по другому URL-адресу, роутер обновляет контент страницы на месте, не вызывая полной перезагрузки страницы.

## Как Angular управляет маршрутизацией {#how-angular-manages-routing}

Маршрутизация в Angular состоит из трех основных частей:

1.  **Routes (Маршруты)** определяют, какой компонент отображается, когда пользователь посещает определенный URL.
2.  **Outlets (Аутлеты)** — это заполнители в ваших шаблонах, которые динамически загружают и рендерят компоненты на основе активного маршрута.
3.  **Links (Ссылки)** предоставляют пользователям возможность перемещаться между различными маршрутами в вашем приложении без вызова полной перезагрузки страницы.

Кроме того, библиотека маршрутизации Angular предлагает дополнительные функции, такие как:

*   Вложенные маршруты
*   Программная навигация
*   Параметры маршрута, параметры запроса и подстановочные знаки (wildcards)
*   Информация об активированном маршруте с помощью `ActivatedRoute`
*   Эффекты перехода представления (View transition effects)
*   Навигационные защитники (Navigation guards)

## Следующие шаги {#next-steps}

Узнайте, как вы можете [определить маршруты с помощью роутера Angular](/guide/routing/define-routes).
# Определение маршрутов

Маршруты служат фундаментальными строительными блоками навигации в приложении Angular.

## Что такое маршруты? {#what-are-routes}

В Angular **маршрут** — это объект, который определяет, какой компонент должен рендериться для конкретного URL-пути или паттерна, а также дополнительные опции конфигурации о том, что происходит, когда пользователь переходит по этому URL.

Вот базовый пример маршрута:

```ts
import {AdminPage} from './app-admin';

const adminPage = {
  path: 'admin',
  component: AdminPage,
};
```

Для этого маршрута, когда пользователь посещает путь `/admin`, приложение отобразит компонент `AdminPage`.

### Управление маршрутами в приложении {#managing-routes-in-your-application}

Большинство проектов определяют маршруты в отдельном файле, в имени которого есть `routes`.

Коллекция маршрутов выглядит так:

```ts
import {Routes} from '@angular/router';
import {HomePage} from './home-page';
import {AdminPage} from './admin-page';

export const routes: Routes = [
  {
    path: '',
    component: HomePage,
  },
  {
    path: 'admin',
    component: AdminPage,
  },
];
```

TIP: Если вы сгенерировали проект с Angular CLI, ваши маршруты определены в `src/app/app.routes.ts`.

### Добавление router в приложение {#adding-the-router-to-your-application}

При bootstrap приложения Angular без Angular CLI можно передать объект конфигурации, включающий массив `providers`.

Внутри массива `providers` можно добавить Angular router в приложение, добавив вызов функции `provideRouter` с вашими маршрутами.

```ts
import {ApplicationConfig} from '@angular/core';
import {provideRouter} from '@angular/router';

import {routes} from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    // ...
  ],
};
```

## URL-пути маршрутов {#route-url-paths}

### Статические URL-пути {#static-url-paths}

Статические URL-пути относятся к маршрутам с предопределёнными путями, которые не меняются на основе динамических параметров. Это маршруты, которые точно соответствуют строке `path` и имеют фиксированный исход.

Примеры включают:

- "/admin"
- "/blog"
- "/settings/account"

### Определение URL-путей с параметрами маршрута {#define-url-paths-with-route-parameters}

Параметризованные URL позволяют определять динамические пути, которые допускают несколько URL к одному и тому же компоненту, динамически отображая данные на основе параметров в URL.

Можно определить такой паттерн, добавив параметры в строку `path` маршрута и предварив каждый параметр символом двоеточия (`:`).

IMPORTANT: Параметры отличаются от информации в [query string](https://en.wikipedia.org/wiki/Query_string) URL.
Узнайте больше о [query parameters в Angular в этом руководстве](/guide/routing/read-route-state#query-parameters).

Следующий пример отображает компонент профиля пользователя на основе user id, переданного через URL.

```ts
import {Routes} from '@angular/router';
import {UserProfile} from './user-profile/user-profile';

const routes: Routes = [{path: 'user/:id', component: UserProfile}];
```

В этом примере URL вроде `/user/leeroy` и `/user/jenkins` рендерят компонент `UserProfile`. Этот компонент затем может прочитать параметр `id` и использовать его для дополнительной работы, например получения данных. Подробности о чтении параметров маршрута см. в [руководстве по чтению состояния маршрута](/guide/routing/read-route-state).

Валидные имена параметров маршрута должны начинаться с буквы (a-z, A-Z) и могут содержать только:

- Буквы (a-z, A-Z)
- Цифры (0-9)
- Подчёркивание (\_)
- Дефис (-)

Также можно определять пути с несколькими параметрами:

```ts
import {Routes} from '@angular/router';
import {UserProfile} from './user-profile';
import {SocialMediaFeed} from './social-media-feed';

const routes: Routes = [
  {path: 'user/:id/:social-media', component: SocialMediaFeed},
  {path: 'user/:id/', component: UserProfile},
];
```

С этим новым путём пользователи могут посещать `/user/leeroy/youtube` и `/user/leeroy/bluesky` и видеть соответствующие ленты социальных сетей на основе параметра для пользователя leeroy.

Подробности о чтении параметров маршрута см. в [Чтение состояния маршрута](/guide/routing/read-route-state).

### Wildcards {#wildcards}

Когда нужно перехватить все маршруты для определённого пути, решением является wildcard-маршрут, который определяется двойной звёздочкой (`**`).

Распространённый пример — определение компонента Page Not Found.

```ts
import {Home} from './home/home';
import {UserProfile} from './user-profile';
import {NotFound} from './not-found';

const routes: Routes = [
  {path: 'home', component: Home},
  {path: 'user/:id', component: UserProfile},
  {path: '**', component: NotFound},
];
```

В этом массиве маршрутов приложение отображает компонент `NotFound`, когда пользователь посещает любой путь вне `home` и `user/:id`.

TIP: Wildcard-маршруты обычно размещают в конце массива маршрутов.

## Как Angular сопоставляет URL {#how-angular-matches-urls}

При определении маршрутов порядок важен, потому что Angular использует стратегию first-match wins. Это означает, что как только Angular сопоставляет URL с `path` маршрута, он прекращает проверять дальнейшие маршруты. В результате всегда помещайте более специфичные маршруты перед менее специфичными.

Следующий пример показывает маршруты, определённые от наиболее специфичных к наименее специфичным:

```ts
const routes: Routes = [
  {path: '', component: Home}, // Empty path
  {path: 'users/new', component: NewUser}, // Static, most specific
  {path: 'users/:id', component: UserDetail}, // Dynamic
  {path: 'users', component: Users}, // Static, less specific
  {path: '**', component: NotFound}, // Wildcard - always last
];
```

Если пользователь посещает `/users/new`, Angular router пройдёт следующие шаги:

1. Проверяет `''` — не совпадает
1. Проверяет `users/new` — совпадает! Останавливается здесь
1. Никогда не достигает `users/:id`, хотя он мог бы совпасть
1. Никогда не достигает `users`
1. Никогда не достигает `**`

## Redirects {#redirects}

Можно определить маршрут, который перенаправляет на другой маршрут вместо рендеринга компонента:

```ts
import {Blog} from './home/blog';

const routes: Routes = [
  {
    path: 'articles',
    redirectTo: '/blog',
  },
  {
    path: 'blog',
    component: Blog,
  },
];
```

Если вы изменяете или удаляете маршрут, некоторые пользователи всё ещё могут кликать по устаревшим ссылкам или закладкам на этот маршрут. Можно добавить redirect, чтобы направить этих пользователей на подходящий альтернативный маршрут вместо страницы «not found».

## Заголовки страниц {#page-titles}

Можно связать **title** с каждым маршрутом. Angular автоматически обновляет [заголовок страницы](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title), когда маршрут активируется. Всегда определяйте подходящие заголовки страниц для приложения, так как эти заголовки необходимы для создания доступного опыта.

```ts
import {Routes} from '@angular/router';
import {Home} from './home';
import {About} from './about';
import {Products} from './products';

const routes: Routes = [
  {
    path: '',
    component: Home,
    title: 'Home Page',
  },
  {
    path: 'about',
    component: About,
    title: 'About Us',
  },
];
```

Свойство `title` страницы можно задать динамически функцией resolver с использованием [`ResolveFn`](/api/router/ResolveFn).

```ts
const titleResolver: ResolveFn<string> = (route) => route.queryParams['id'];
const routes: Routes = [
  ...{
    path: 'products',
    component: Products,
    title: titleResolver,
  },
];
```

Заголовки маршрутов также можно задать через сервис, расширяющий абстрактный класс [`TitleStrategy`](/api/router/TitleStrategy). По умолчанию Angular использует [`DefaultTitleStrategy`](/api/router/DefaultTitleStrategy).

### Использование TitleStrategy для заголовков страниц {#using-titlestrategy-for-page-titles}

Для продвинутых сценариев, где нужен централизованный контроль над тем, как составляется document title, реализуйте `TitleStrategy`.

`TitleStrategy` — это токен, который можно предоставить, чтобы переопределить стратегию заголовков по умолчанию, используемую Angular. Можно предоставить пользовательский `TitleStrategy` для реализации соглашений вроде добавления суффикса приложения, форматирования заголовков из breadcrumbs или динамической генерации заголовков из данных маршрута.

```ts
import {inject, 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 is equal to the "Title" of a route if it's set
    // If its not set it will use the "title" given in index.html
    const pageTitle = this.buildTitle(snapshot) || this.title.getTitle();
    this.title.setTitle(`MyAwesomeApp - ${pageTitle}`);
  }
}
```

Чтобы использовать пользовательскую стратегию, предоставьте её с токеном `TitleStrategy` на уровне приложения:

```ts
import {provideRouter, TitleStrategy} from '@angular/router';
import {AppTitleStrategy} from './app-title.strategy';

export const appConfig = {
  providers: [provideRouter(routes), {provide: TitleStrategy, useClass: AppTitleStrategy}],
};
```

## Providers уровня маршрута для внедрения зависимостей {#route-level-providers-for-dependency-injection}

У каждого маршрута есть свойство `providers`, которое позволяет предоставлять зависимости содержимому этого маршрута через [внедрение зависимостей](/guide/di).

Распространённые сценарии, где это может быть полезно, включают приложения с разными сервисами в зависимости от того, является ли пользователь администратором или нет.

```ts
export const ROUTES: Route[] = [
  {
    path: 'admin',
    providers: [AdminService, {provide: ADMIN_API_KEY, useValue: '12345'}],
    children: [
      {path: 'users', component: AdminUsers},
      {path: 'teams', component: AdminTeams},
    ],
  },
  // ... other application routes that don't
  //     have access to ADMIN_API_KEY or AdminService.
];
```

В этом примере кода путь `admin` содержит защищённое свойство данных `ADMIN_API_KEY`, которое доступно только дочерним элементам внутри его секции. В результате никакие другие пути не смогут получить доступ к данным, предоставленным через `ADMIN_API_KEY`.

См. [руководство по внедрению зависимостей](/guide/di) для дополнительной информации о providers и injection в Angular.

## Связывание данных с маршрутами {#associating-data-with-routes}

Данные маршрута позволяют прикреплять дополнительную информацию к маршрутам. Можно настраивать поведение компонентов на основе этих данных.

Есть два способа работы с данными маршрута: статические данные, которые остаются постоянными, и динамические данные, которые могут меняться на основе условий runtime.

### Статические данные {#static-data}

Можно связать произвольные статические данные с маршрутом через свойство `data`, чтобы централизовать такие вещи, как метаданные, специфичные для маршрута (например, отслеживание аналитики, permissions и т.д.):

```ts
import {Routes} from '@angular/router';
import {Home} from './home';
import {About} from './about';
import {Products} from './products';

const routes: Routes = [
  {
    path: 'about',
    component: About,
    data: {analyticsId: '456'},
  },
  {
    path: '',
    component: Home,
    data: {analyticsId: '123'},
  },
];
```

В этом примере кода страницы home и about настроены с конкретным `analyticsId`, который затем использовался бы в соответствующих компонентах для аналитики отслеживания страниц.

Можно прочитать эти статические данные, внедрив `ActivatedRoute`. Подробности см. в [Чтение состояния маршрута](/guide/routing/read-route-state).

### Динамические данные с data resolvers {#dynamic-data-with-data-resolvers}

Когда нужно предоставить динамические данные маршруту, см. [руководство по route data resolvers](/guide/routing/data-resolvers).

## Вложенные маршруты {#nested-routes}

Вложенные маршруты, также известные как дочерние маршруты, — распространённая техника для управления более сложными маршрутами навигации, где у компонента есть sub-view, которая меняется на основе URL.

Можно добавить дочерние маршруты к любому определению маршрута со свойством `children`:

```ts
const routes: Routes = [
  {
    path: 'product/:id',
    component: Product,
    children: [
      {
        path: 'info',
        component: ProductInfo,
      },
      {
        path: 'reviews',
        component: ProductReviews,
      },
    ],
  },
];
```

Пример выше определяет маршрут для страницы продукта, который позволяет пользователю менять, отображается ли информация о продукте или отзывы, на основе URL.

Свойство `children` принимает массив объектов `Route`.

Чтобы отображать дочерние маршруты, родительский компонент (`Product` в примере выше) включает свой собственный `<router-outlet>`.

```html

<article>
  <h1>Product {{ id }}</h1>
  <router-outlet />
</article>
```

После добавления дочерних маршрутов в конфигурацию и добавления `<router-outlet>` в компонент навигация между URL, соответствующими дочерним маршрутам, обновляет только вложенный outlet.

## Следующие шаги {#next-steps}
# Отображение маршрутов с помощью outlet

Директива `RouterOutlet` служит заполнителем, указывающим место, где маршрутизатор должен отобразить компонент для
текущего URL.

```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 {}
```

В этом примере, если в приложении определены следующие маршруты:

```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'
  }
];
```

Когда пользователь переходит по адресу `/products`, Angular рендерит следующее:

```html
<app-header />
<app-products />
<app-footer />
```

Если пользователь возвращается на главную страницу, Angular рендерит:

```html
<app-header />
<app-home />
<app-footer />
```

При отображении маршрута элемент `<router-outlet>` остается в DOM в качестве опорной точки для будущих навигаций.
Angular вставляет контент маршрута сразу после элемента outlet в качестве соседнего узла.

```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>
```

## Вложенные маршруты и дочерние маршруты {#nesting-routes-with-child-routes}

По мере усложнения приложения может потребоваться создание маршрутов, относительных не к корневому, а к другому
компоненту. Это позволяет создавать интерфейсы, где при изменении URL меняется только часть приложения, и у пользователя
не возникает ощущения полной перезагрузки страницы.

Такие типы вложенных маршрутов называются дочерними маршрутами. Это означает, что вы добавляете второй `<router-outlet>`
в приложение в дополнение к `<router-outlet>` в `AppComponent`.

В этом примере компонент `Settings` будет отображать нужную панель в зависимости от выбора пользователя. Одной из
особенностей дочерних маршрутов является то, что компонент часто имеет свои собственные `<nav>` и `<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 />
```

Дочерний маршрут похож на любой другой маршрут тем, что ему требуются `path` и `component`. Единственное отличие
заключается в том, что дочерние маршруты помещаются в массив `children` внутри родительского маршрута.

```ts
const routes: Routes = [
  {
    path: 'settings-component',
    component: SettingsComponent, // это компонент с <router-outlet> в шаблоне
    children: [
      {
        path: 'profile', // путь дочернего маршрута
        component: ProfileComponent, // компонент дочернего маршрута, который рендерит роутер
      },
      {
        path: 'security',
        component: SecurityComponent, // еще один компонент дочернего маршрута, который рендерит роутер
      },
    ],
  },
];
```

Как только `routes` и `<router-outlet>` настроены правильно, ваше приложение начинает использовать вложенные маршруты!

## Вторичные маршруты с именованными outlet {#secondary-routes-with-named-outlets}

Страницы могут иметь несколько outlet — вы можете назначить имя каждому из них, чтобы указать, какой контент к какому
outlet относится.

```html
<app-header />
<router-outlet />
<router-outlet name='read-more' />
<router-outlet name='additional-actions' />
<app-footer />
```

Каждый outlet должен иметь уникальное имя. Имя нельзя задать или изменить динамически. По умолчанию используется имя
`'primary'`.

Angular сопоставляет имя outlet со свойством `outlet`, определенным в каждом маршруте:

```ts
{
  path: 'user/:id',
  component: UserDetails,
  outlet: 'additional-actions'
}
```

## События жизненного цикла outlet {#outlet-lifecycle-events}

Существует четыре события жизненного цикла, которые может генерировать router outlet:

| Событие      | Описание                                                               |
| ------------ | ---------------------------------------------------------------------- |
| `activate`   | Когда создается экземпляр нового компонента                            |
| `deactivate` | Когда компонент уничтожается                                           |
| `attach`     | Когда `RouteReuseStrategy` дает указание outlet присоединить поддерево |
| `detach`     | Когда `RouteReuseStrategy` дает указание outlet отсоединить поддерево  |

Вы можете добавить слушатели событий, используя стандартный синтаксис привязки событий:

```html
<router-outlet
  (activate)='onActivate($event)'
  (deactivate)='onDeactivate($event)'
  (attach)='onAttach($event)'
  (detach)='onDetach($event)'
/>
```

Ознакомьтесь с [API-документацией для RouterOutlet](/api/router/RouterOutlet?tab=api), если хотите узнать больше.

## Передача контекстных данных в маршрутизируемые компоненты {#passing-contextual-data-to-routed-components}

Передача контекстных данных в маршрутизируемые компоненты часто требует глобального состояния или сложных конфигураций
маршрутов. Чтобы упростить эту задачу, каждый `RouterOutlet` поддерживает входное свойство `routerOutletData`.
Маршрутизируемые компоненты и их потомки могут считывать эти данные как сигнал, используя токен внедрения
`ROUTER_OUTLET_DATA`, что позволяет настраивать конкретный outlet без изменения определений маршрутов.

```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 {}
```

Маршрутизируемый компонент может внедрить предоставленные данные outlet с помощью `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 }>;
}
```

Когда Angular активирует `StatsComponent` в этом outlet, он получает `{ layout: 'sidebar' }` в качестве внедренных
данных.

NOTE: Если входное свойство `routerOutletData` не задано, внедряемое значение по умолчанию равно null.

---

## Следующие шаги {#next-steps}

Узнайте, как [выполнять навигацию по маршрутам](/guide/routing/navigate-to-routes) с помощью Angular Router.
# Навигация по маршрутам

Директива RouterLink — это декларативный подход Angular к навигации. Она позволяет использовать стандартные элементы
ссылок (`<a>`), которые бесшовно интегрируются с системой маршрутизации Angular.

## Как использовать RouterLink {#how-to-use-routerlink}

Вместо использования обычных элементов `<a>` с атрибутом `href`, вы добавляете директиву RouterLink с соответствующим
путем, чтобы задействовать маршрутизацию 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 {}
```

### Использование абсолютных или относительных ссылок {#using-absolute-or-relative-links}

**Относительные URL** в маршрутизации Angular позволяют определять пути навигации относительно текущего местоположения
маршрута. Это отличается от **абсолютных URL**, которые содержат полный путь с протоколом (например, `http://`) и \*
\*корневым доменом\*\* (например, `google.com`).

```html

<a href="https://www.angular.dev/essentials">Angular Essentials Guide</a>

<a href="/essentials">Angular Essentials Guide</a>
```

В этом примере первый вариант содержит полный путь с протоколом (т.е. `https://`) и корневым доменом (т.е.
`angular.dev`), явно определенным для страницы essentials. Напротив, второй пример предполагает, что пользователь уже
находится на правильном корневом домене для `/essentials`.

Как правило, предпочтительнее использовать относительные URL, так как их легче поддерживать в разных приложениях,
поскольку им не нужно знать свое абсолютное положение в иерархии маршрутизации.

### Как работают относительные URL {#how-relative-urls-work}

Маршрутизация Angular имеет два синтаксиса для определения относительных URL: строки и массивы.

```html

<a routerLink="dashboard">Dashboard</a>
<a [routerLink]="['dashboard']">Dashboard</a>
```

HELPFUL: Передача строки — самый распространенный способ определения относительных URL.

Когда нужно определить динамические параметры в относительном URL, используйте синтаксис массива:

```html
<a [routerLink]="['user', currentUserId]">Current User</a>
```

Кроме того, маршрутизация Angular позволяет указать, должен ли путь быть относительным к текущему URL или к корневому
домену, в зависимости от того, начинается ли относительный путь с косой черты (`/`) или нет.

Например, если пользователь находится на `example.com/settings`, вот как можно определить различные относительные пути
для разных сценариев:

```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>”
```

## Программная навигация по маршрутам {#programmatic-navigation-to-routes}

В то время как `RouterLink` обрабатывает декларативную навигацию в шаблонах, Angular предоставляет программную навигацию
для сценариев, где необходимо переходить по маршрутам на основе логики, действий пользователя или состояния приложения.
Внедряя `Router`, вы можете динамически переходить к маршрутам, передавать параметры и управлять поведением навигации в
вашем TypeScript-коде.

### `router.navigate()`

Вы можете использовать метод `router.navigate()` для программной навигации между маршрутами, указав массив путей 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 }]);
  }
}
```

`router.navigate()` поддерживает как простые, так и сложные сценарии маршрутизации, позволяя передавать параметры
маршрута, [параметры запроса (query parameters)](/guide/routing/read-route-state#query-parameters) и управлять
поведением навигации.

Вы также можете создавать динамические пути навигации относительно местоположения вашего компонента в дереве
маршрутизации, используя опцию `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 });
  }
}
```

При навигации на несколько уровней вверх все сегменты `..` должны находиться в **первом элементе** массива команд. Роутер разбирает `..` только из первой строки команды — последующие элементы массива обрабатываются как литеральные сегменты пути.

```typescript
{prefer}
// From: /team/123/users/456
// Result: /team/123/settings
this.router.navigate(['../../settings'], {relativeTo: this.route});
```

При использовании `relativeTo` никогда не добавляйте `/` в начало первой команды. Ведущий `/` делает навигацию абсолютной и полностью игнорирует `relativeTo`.

```typescript
{prefer}
// From: /team/123/users/456
// Result: /team/123/users/456/edit
this.router.navigate(['edit'], {relativeTo: this.route});
```

```typescript
{avoid}
// From: /team/123/users/456
// Leading '/' causes absolute navigation — relativeTo is ignored
// Result: /edit
this.router.navigate(['/edit'], {relativeTo: this.route});
```

### `router.navigateByUrl()`

Метод `router.navigateByUrl()` предоставляет прямой способ программной навигации с использованием строковых путей URL, а
не сегментов массива. Этот метод идеально подходит, когда у вас есть полный путь URL и нужно выполнить абсолютную
навигацию, особенно при работе с внешними URL или сценариями глубоких ссылок (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')
```

В случае, если вам нужно заменить текущий URL в истории, `navigateByUrl` также принимает объект конфигурации с опцией
`replaceUrl`.

```ts
// Replace current URL in history
router.navigateByUrl('/checkout', {
  replaceUrl: true
});
```

## Следующие шаги {#next-steps}

Узнайте, как [читать состояние маршрута](/guide/routing/read-route-state), чтобы создавать отзывчивые и
контекстно-зависимые компоненты.
# Чтение состояния маршрута

Angular Router позволяет читать и использовать информацию, связанную с маршрутом, для создания отзывчивых и context-aware компонентов.

## Получение информации о текущем маршруте с ActivatedRoute {#get-information-about-the-current-route-with-activatedroute}

`ActivatedRoute` — это сервис из `@angular/router`, который предоставляет всю информацию, связанную с текущим маршрутом.

```typescript
import {Component} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component({
  selector: 'app-product',
})
export class Product {
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    console.log(this.activatedRoute);
  }
}
```

`ActivatedRoute` может предоставить разную информацию о маршруте. Некоторые распространённые свойства включают:

| Свойство      | Подробности                                                                                                                       |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------- |
| `url`         | `Observable` путей маршрута, представленных как массив строк для каждой части пути маршрута.                                      |
| `data`        | `Observable`, содержащий объект `data`, предоставленный для маршрута. Также содержит любые resolved-значения из resolve guard.    |
| `params`      | `Observable`, содержащий обязательные и опциональные параметры, специфичные для маршрута.                                         |
| `queryParams` | `Observable`, содержащий query parameters, доступные всем маршрутам.                                                              |

См. [документацию API `ActivatedRoute`](/api/router/ActivatedRoute) для полного списка того, к чему можно получить доступ в маршруте.

## Понимание снимков маршрута {#understanding-route-snapshots}

Навигации по страницам — это события во времени, и можно получить доступ к состоянию router в заданный момент, получив снимок маршрута.

Снимки маршрута содержат существенную информацию о маршруте, включая его параметры, данные и дочерние маршруты. Кроме того, снимки статичны и не будут отражать будущие изменения.

Вот пример того, как получить доступ к снимку маршрута:

```typescript
import {ActivatedRoute, ActivatedRouteSnapshot} from '@angular/router';

@Component(/* ... */)
export class UserProfile {
  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
    });
  }
}
```

См. [документацию API `ActivatedRoute`](/api/router/ActivatedRoute) и [документацию API `ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) для полного списка всех свойств, к которым можно получить доступ.

## Чтение параметров маршрута {#reading-parameters-on-a-route}

Есть два типа параметров, которые разработчики могут использовать из маршрута: параметры маршрута и query parameters.

### Параметры маршрута {#route-parameters}

Параметры маршрута позволяют передавать данные компоненту через URL. Это полезно, когда нужно отобразить конкретное содержимое на основе идентификатора в URL, например ID пользователя или ID продукта.

Можно [определить параметры маршрута](/guide/routing/define-routes#define-url-paths-with-route-parameters), предварив имя параметра двоеточием (`:`).

```typescript
import {Routes} from '@angular/router';
import {Product} from './product';

const routes: Routes = [{path: 'product/:id', component: Product}];
```

Можно получить доступ к параметрам, подписавшись на `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 ProductDetail {
  productId = signal('');
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    // Access route parameters
    this.activatedRoute.params.subscribe((params) => {
      this.productId.set(params['id']);
    });
  }
}
```

### Query Parameters {#query-parameters}

[Query parameters](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) предоставляют гибкий способ передачи опциональных данных через URL без влияния на структуру маршрута. В отличие от параметров маршрута, query parameters могут сохраняться между событиями навигации и идеально подходят для фильтрации, сортировки, пагинации и других stateful UI-элементов.

```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,
  },
});
```

Можно получить доступ к query parameters через `route.queryParams`.

Вот пример `ProductList`, который обновляет query parameters, влияющие на то, как он отображает список продуктов:

```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 ProductList {
  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
    });
  }
}
```

В этом примере пользователи могут использовать элемент select для сортировки списка продуктов по имени или цене. Связанный обработчик изменения обновляет query parameters URL, что в свою очередь запускает событие изменения, которое может прочитать обновлённые query parameters и обновить список продуктов.

Для дополнительной информации см. [официальную документацию по QueryParamsHandling](/api/router/QueryParamsHandling).

### Matrix Parameters {#matrix-parameters}

Matrix parameters — это опциональные параметры, которые принадлежат конкретному сегменту URL, а не применяются ко всему маршруту. В отличие от query parameters, которые появляются после `?` и применяются глобально, matrix parameters используют точки с запятой (`;`) и ограничены отдельными сегментами пути.

Matrix parameters полезны, когда нужно передать вспомогательные данные конкретному сегменту маршрута без влияния на определение маршрута или поведение сопоставления. Как и query parameters, их не нужно определять в конфигурации маршрутов.

```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
```

**Использование 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'
    });
  }
}
```

NOTE: Как альтернатива использованию `ActivatedRoute`, matrix parameters также привязываются к input'ам компонента при использовании `withComponentInputBinding`.

## Определение активного текущего маршрута с RouterLinkActive {#detect-active-current-route-with-routerlinkactive}

Можно использовать директиву `RouterLinkActive` для динамической стилизации элементов навигации на основе текущего активного маршрута. Это распространено в элементах навигации, чтобы информировать пользователей о том, какой маршрут активен.

```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>
```

В этом примере Angular Router применит класс `active-button` к правильной якорной ссылке и `ariaCurrentWhenActive` к `page`, когда URL соответствует соответствующему `routerLink`.

Если нужно добавить несколько классов на элемент, можно использовать либо строку, разделённую пробелами, либо массив:

```html

<a routerLink="/user/bob" routerLinkActive="class1 class2">Bob</a>

<a routerLink="/user/bob" [routerLinkActive]="['class1', 'class2']">Bob</a>
```

Когда вы указываете значение для routerLinkActive, вы также определяете то же значение для `ariaCurrentWhenActive`. Это гарантирует, что пользователи с нарушениями зрения (которые могут не воспринимать применяемую разную стилизацию) также могут идентифицировать активную кнопку.

Если нужно определить другое значение для aria, потребуется явно задать значение с помощью директивы `ariaCurrentWhenActive`.

### Стратегия сопоставления маршрутов {#route-matching-strategy}

По умолчанию `RouterLinkActive` считает совпадением любых предков в маршруте.

```html
<a [routerLink]="['/user/jane']" routerLinkActive="active-link"> User </a>
<a [routerLink]="['/user/jane/role/admin']" routerLinkActive="active-link"> Role </a>
```

Когда пользователь посещает `/user/jane/role/admin`, оба ссылки будут иметь класс `active-link`.

### Применение RouterLinkActive только при точных совпадениях маршрута {#only-apply-routerlinkactive-on-exact-route-matches}

Если нужно применять класс только при точном совпадении, нужно предоставить директиве `routerLinkActiveOptions` объект конфигурации, содержащий значение `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>
```

Если нужно быть более точным в том, как сопоставляется маршрут, стоит отметить, что `exact: true` на самом деле является синтаксическим сахаром для полного набора опций сопоставления:

```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',
}
```

Для дополнительной информации см. официальную документацию по [isActiveMatchOptions](/api/router/IsActiveMatchOptions).

### Применение RouterLinkActive к предку {#apply-routerlinkactive-to-an-ancestor}

Директиву RouterLinkActive также можно применить к элементу-предку, чтобы разработчики могли стилизовать элементы как угодно.

```html
<div routerLinkActive="active-link" [routerLinkActiveOptions]="{exact: true}">
  <a routerLink="/user/jim">Jim</a>
  <a routerLink="/user/bob">Bob</a>
</div>
```

Для дополнительной информации см. [документацию API для RouterLinkActive](/api/router/RouterLinkActive).

## Проверка, активен ли URL {#check-if-a-url-is-active}

Функция `isActive` возвращает computed signal, который отслеживает, активен ли данный URL в данный момент в router. Signal автоматически обновляется при изменении состояния router.

```typescript
import {Component, inject} from '@angular/core';
import {isActive, Router} from '@angular/router';

@Component({
  template: `
    <div [class.active]="isSettingsActive()">
      <h2>Settings</h2>
    </div>
  `,
})
export class Panel {
  private router = inject(Router);

isSettingsActive = isActive('/settings', this.router, {
    paths: 'subset',
    queryParams: 'ignored',
    fragment: 'ignored',
    matrixParams: 'ignored',
  });
}
```
# Другие распространённые задачи маршрутизации

Это руководство охватывает некоторые другие распространённые задачи, связанные с использованием Angular router в приложении.

## Получение информации о маршруте {#getting-route-information}

Часто, когда пользователь перемещается по приложению, нужно передать информацию от одного компонента другому.
Например, рассмотрим приложение, отображающее список покупок продуктов.
У каждого элемента списка есть уникальный `id`.
Чтобы отредактировать элемент, пользователи нажимают кнопку Edit, которая открывает компонент `EditGroceryItem`.
Вы хотите, чтобы этот компонент получил `id` продукта, чтобы показать пользователю правильную информацию.

Используйте маршрут, чтобы передать такой тип информации компонентам приложения.
Для этого используйте возможность `withComponentInputBinding` с `provideRouter` или опцию `bindToComponentInputs` у `RouterModule.forRoot`.

Чтобы получить информацию из маршрута:

<docs-workflow>

<docs-step title="Add `withComponentInputBinding`">

Добавьте возможность `withComponentInputBinding` в метод `provideRouter`.

```ts
providers: [provideRouter(appRoutes, withComponentInputBinding())];
```

</docs-step>

<docs-step title="Add an `input` to the component">

Обновите компонент, чтобы у него было свойство `input()`, совпадающее с именем параметра.

```ts
id = input.required<string>();
hero = computed(() => this.service.getHero(id()));
```

</docs-step>
<docs-step title="Optional: Use a default value">
Роутер назначает значения всем inputs на основе текущего маршрута, когда включён `withComponentInputBinding`.
Роутер назначает `undefined`, если данные маршрута не совпадают с ключом input, например когда отсутствует опциональный query-параметр.
Следует включать `undefined` в тип `input`, когда есть возможность, что input может не совпасть с маршрутом.

Предоставьте значение по умолчанию, используя опцию `transform` на input или управляя локальным состоянием через `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>

NOTE: Можно привязать все данные маршрута с парами ключ–значение к inputs компонента: статические или resolved данные маршрута, path-параметры, matrix-параметры и query-параметры.

### Отключение привязки query-параметров {#disable-query-parameter-binding}

Используйте `ComponentInputBindingOptions`, чтобы отключить привязку query-параметров, если вы управляете query-параметрами отдельно:

```ts
provideRouter(appRoutes, withComponentInputBinding({queryParams: false}));
```

### Настройка поведения для inputs, недоступных в данных роутера {#configure-behavior-for-inputs-not-available-in-router-data}

По умолчанию роутер устанавливает input в `undefined`, если он не был доступен в данных роутера во время навигации. Это гарантирует, что устаревшие данные не сохраняются.

Если хотите избежать установки `undefined` для inputs, которые _никогда_ не были доступны в данных роутера для активного экземпляра компонента, можно установить опцию `unmatchedInputBehavior` в `'undefinedIfStale'`:

```ts
provideRouter(appRoutes, withComponentInputBinding({unmatchedInputBehavior: 'undefinedIfStale'}));
```

Когда вы комбинируете `unmatchedInputBehavior: 'undefinedIfStale'` с `queryParams: false`, inputs сохраняют начальные значения, если они явно не предоставлены роутером. Исключение — matrix-параметры: если matrix-параметр предоставлен в одной навигации и удалён в последующей, роутер установит input в `undefined`, чтобы избежать сохранения устаревших данных.

```ts
provideRouter(
  appRoutes,
  withComponentInputBinding({
    queryParams: false,
    unmatchedInputBehavior: 'undefinedIfStale',
  }),
);
```

### Наследование данных родительского маршрута {#inherit-parent-route-data}

По умолчанию дочерние маршруты наследуют параметры и данные от родительских маршрутов (эквивалент `paramsInheritanceStrategy: 'always'`). Это значит, что можно обращаться к информации родительского маршрута напрямую в дочерних компонентах.

Если нужно восстановить legacy-поведение, где параметры наследовались только от маршрутов с пустым путём, можно установить `paramsInheritanceStrategy` в `'emptyOnly'`:

```ts
provideRouter(routes, withRouterConfig({paramsInheritanceStrategy: 'emptyOnly'}));
```

См. [опции конфигурации роутера](guide/routing/customizing-route-behavior#router-configuration-options) для подробностей о других доступных настройках.

## Отображение страницы 404 {#displaying-a-404-page}

Чтобы отобразить страницу 404, настройте [wildcard-маршрут](guide/routing/define-routes#wildcards) со свойством `component`, установленным в компонент, который хотите использовать для страницы 404:

```ts
const routes: Routes = [
  {path: 'first-component', component: First},
  {path: 'second-component', component: Second},
  {path: '**', component: PageNotFound}, // Wildcard route for a 404 page
];
```

Последний маршрут с `path` `**` — wildcard-маршрут.
Роутер выбирает этот маршрут, если запрошенный URL не совпадает ни с одним из путей ранее в списке, и отправляет пользователя на `PageNotFound`.

## Массив параметров ссылки {#link-parameters-array}

Массив параметров ссылки содержит следующие ингредиенты для навигации роутера:

- Путь маршрута к компоненту назначения
- Обязательные и опциональные параметры маршрута, попадающие в URL маршрута

Привяжите директиву `RouterLink` к такому массиву так:

```html
<a [routerLink]="['/heroes']">Heroes</a>
```

Следующее — двухэлементный массив при указании параметра маршрута:

```html
<a [routerLink]="['/hero', hero.id]">
  <span class="badge">{{ hero.id }}</span
  >{{ hero.name }}
</a>
```

Предоставляйте опциональные параметры маршрута в объекте, как в `{ foo: 'foo' }`:

```html
<a [routerLink]="['/crisis-center', {foo: 'foo'}]">Crisis Center</a>
```

Этот синтаксис передаёт matrix-параметры — опциональные параметры, связанные с конкретным сегментом URL. Подробнее о [matrix-параметрах](/guide/routing/read-route-state#matrix-parameters).

Эти три примера покрывают потребности приложения с одним уровнем маршрутизации.
Однако с дочерним роутером, как в crisis center, появляются новые возможности массива ссылок.

Следующий минимальный пример `RouterLink` строится на указанном дочернем маршруте по умолчанию для crisis center.

```html
<a [routerLink]="['/crisis-center']">Crisis Center</a>
```

Обратите внимание:

- Первый элемент массива идентифицирует родительский маршрут $`/crisis-center`$
- Для этого родительского маршрута нет параметров
- Нет значения по умолчанию для дочернего маршрута, поэтому нужно выбрать одно
- Вы переходите к `CrisisList`, чей путь маршрута — `/`, но явно добавлять слэш не нужно

Рассмотрим следующую ссылку роутера, которая навигирует от корня приложения вниз к Dragon Crisis:

```html
<a [routerLink]="['/crisis-center', 1]">Dragon Crisis</a>
```

- Первый элемент массива идентифицирует родительский маршрут $`/crisis-center`$
- Для этого родительского маршрута нет параметров
- Второй элемент идентифицирует дочерний маршрут деталей о конкретном кризисе $`/:id`$
- Дочерний маршрут деталей требует параметр маршрута `id`
- Вы добавили `id` Dragon Crisis как второй элемент массива $`1`$
- Результирующий путь — `/crisis-center/1`

Также можно переопределить шаблон `App` исключительно с маршрутами Crisis Center:

```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 App {}
```

Итого, можно писать приложения с одним, двумя или более уровнями маршрутизации.
Массив параметров ссылки даёт гибкость представлять любую глубину маршрутизации и любую допустимую последовательность путей маршрутов, $обязательных$ параметров роутера и $опциональных$ объектов параметров маршрута.

## `LocationStrategy` и стили URL браузера {#locationstrategy-and-browser-url-styles}

Когда роутер переходит к новому представлению компонента, он обновляет location и историю браузера URL для этого представления.

Современные браузеры HTML5 поддерживают [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') — технику, которая меняет location и историю браузера без запуска запроса страницы к серверу.
Роутер может составить «естественный» URL, неотличимый от того, который иначе потребовал бы загрузки страницы.

Вот URL Crisis Center в этом стиле «HTML5 pushState»:

```text
localhost:3002/crisis-center
```

Старые браузеры отправляют запросы страниц на сервер при изменении URL location, если изменение не происходит после «#» $называемого «hash»$.
Роутеры могут воспользоваться этим исключением, составляя URL маршрутов в приложении с хешами.
Вот «hash URL», который маршрутизирует к Crisis Center.

```text
localhost:3002/src/#/crisis-center
```

Роутер поддерживает оба стиля двумя провайдерами `LocationStrategy`:

Функция `RouterModule.forRoot()` устанавливает `LocationStrategy` в `PathLocationStrategy`, делая её стратегией по умолчанию.
Также есть опция переключиться на `HashLocationStrategy` с переопределением во время процесса bootstrap.

HELPFUL: Подробнее о провайдерах и процессе bootstrap см. [Внедрение зависимостей](guide/di/defining-dependency-providers).
# Создание пользовательских сопоставлений маршрутов

Angular Router поддерживает мощную стратегию сопоставления, которую можно использовать для помощи пользователям в
навигации по приложению.
Эта стратегия поддерживает статические маршруты, переменные маршруты с параметрами, wildcard-маршруты и так далее.
Кроме того, вы можете создавать собственные шаблоны сопоставления для ситуаций, когда URL-адреса имеют более сложную
структуру.

В этом руководстве вы создадите пользовательский сопоставитель маршрутов (route matcher), используя `UrlMatcher` из
Angular.
Этот сопоставитель ищет в URL хендл (имя пользователя).

## Цели {#objectives}

Реализовать `UrlMatcher` из Angular для создания пользовательского сопоставителя маршрутов.

## Создание примера приложения {#create-a-sample-application}

Используя Angular CLI, создайте новое приложение _angular-custom-route-match_.
Помимо стандартного каркаса приложения Angular, вы также создадите компонент _profile_.

1. Создайте новый проект Angular с именем _angular-custom-route-match_.

```shell
ng new angular-custom-route-match
   ```

Когда появится запрос `Would you like to add Angular routing?`, выберите `Y`.

Когда появится запрос `Which stylesheet format would you like to use?`, выберите `CSS`.

Через несколько минут новый проект `angular-custom-route-match` будет готов.

1. В терминале перейдите в директорию `angular-custom-route-match`.
1. Создайте компонент _profile_.

```shell
ng generate component profile
   ```

1. В редакторе кода найдите файл `profile.component.html` и замените его содержимое следующим HTML-кодом.

<docs-code header="profile.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/profile/profile.html"/>

1. В редакторе кода найдите файл `app.component.html` и замените его содержимое следующим HTML-кодом.

<docs-code header="app.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.html"/>

## Настройка маршрутов приложения {#configure-your-routes-for-your-application}

Теперь, когда каркас приложения готов, нужно добавить возможности маршрутизации в файл `app.config.ts`.
В рамках этого процесса вы создадите пользовательский сопоставитель URL, который ищет хендл в URL.
Этот хендл определяется по предшествующему символу `@`.

1. В редакторе кода откройте файл `app.config.ts`.
1. Добавьте `import` для `provideRouter` и `withComponentInputBinding` из Angular, а также маршруты приложения.

```ts
import {provideRouter, withComponentInputBinding} from '@angular/router';

import {routes} from './app.routes';
   ```

1. В массив `providers` добавьте выражение `provideRouter(routes, withComponentInputBinding())`.

1. Определите пользовательский сопоставитель маршрутов, добавив следующий код в маршруты приложения.

<docs-code header="app.routes.ts" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.routes.ts" region="matcher"/>

Этот пользовательский сопоставитель представляет собой функцию, которая выполняет следующие задачи:

- Сопоставитель проверяет, что массив содержит только один сегмент.
- Сопоставитель использует регулярное выражение, чтобы убедиться, что формат имени пользователя совпадает.
- Если совпадение найдено, функция возвращает весь URL, определяя параметр маршрута `username` как подстроку пути.
- Если совпадение не найдено, функция возвращает `null`, и роутер продолжает искать другие маршруты, соответствующие
  URL.

HELPFUL: Пользовательский сопоставитель URL ведет себя так же, как и любое другое определение маршрута. Вы можете
определять дочерние маршруты или маршруты с ленивой загрузкой так же, как и для любого другого маршрута.

## Чтение параметров маршрута {#reading-the-route-parameters}

Когда пользовательский сопоставитель готов, можно привязать параметр маршрута в компоненте `profile`.

В редакторе кода откройте файл `profile.component.ts` и создайте `input`, соответствующий параметру `username`.
Ранее мы добавили функцию `withComponentInputBinding` в `provideRouter`. Это позволяет `Router` привязывать информацию
непосредственно к компонентам маршрута.

```ts
username = input.required<string>();
```

## Проверка пользовательского сопоставителя URL {#test-your-custom-url-matcher}

Теперь, когда код написан, можно протестировать пользовательский сопоставитель URL.

1. В окне терминала выполните команду `ng serve`.

```shell
ng serve
   ```

1. Откройте браузер по адресу `http://localhost:4200`.

Вы должны увидеть одну веб-страницу с предложением `Navigate to my profile`.

1. Нажмите на гиперссылку **my profile**.

На странице появится новое предложение `Hello, Angular!`.

## Следующие шаги {#next-steps}

Сопоставление шаблонов с помощью Angular Router дает большую гибкость при работе с динамическими URL-адресами в
приложении.
Чтобы узнать больше об Angular Router, ознакомьтесь со следующими темами:
HELPFUL: Этот контент основан на
статье [Custom Route Matching with the Angular Router](https://medium.com/@brandontroberts/custom-route-matching-with-the-angular-router-fbdd48665483),
автор Brandon Roberts.
# Серверный и гибридный рендеринг

По умолчанию Angular поставляет все приложения как client-side rendered (CSR). Такой подход даёт лёгкий начальный payload, но вводит компромиссы: более медленную загрузку, худшие метрики производительности и более высокие требования к ресурсам, так как большую часть вычислений выполняет устройство пользователя. Поэтому многие приложения существенно выигрывают в производительности, интегрируя server-side rendering (SSR) в гибридную стратегию рендеринга.

## Что такое гибридный рендеринг? {#what-is-hybrid-rendering}

Гибридный рендеринг позволяет использовать преимущества server-side rendering (SSR), pre-rendering (также известного как «static site generation» или SSG) и client-side rendering (CSR) для оптимизации Angular-приложения. Он даёт гранулярный контроль над тем, как рендерятся разные части приложения, чтобы обеспечить пользователям лучший опыт.

## Настройка гибридного рендеринга {#setting-up-hybrid-rendering}

Можно создать **новый** проект с гибридным рендерингом, используя флаг server-side rendering (т.е. `--ssr`) с командой Angular CLI `ng new`:

```shell
ng new --ssr
```

Также можно включить гибридный рендеринг, добавив server-side rendering в существующий проект командой `ng add`:

```shell
ng add @angular/ssr
```

NOTE: По умолчанию Angular prerender'ит всё приложение и генерирует server-файл. Чтобы отключить это и создать полностью статическое приложение, задайте `outputMode` в `static`. Чтобы включить SSR, обновите server routes, используя `RenderMode.Server`. Подробнее см. [`Server routing`](#server-routing) и [`Generate a fully static application`](#generate-a-fully-static-application).

## Server routing {#server-routing}

### Настройка server routes {#configuring-server-routes}

Конфиг server routes создаётся объявлением массива объектов [`ServerRoute`](api/ssr/ServerRoute 'API reference'). Обычно эта конфигурация живёт в файле `app.routes.server.ts`.

```typescript
// app.routes.server.ts
import {RenderMode, ServerRoute} from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: '', // This renders the "/" route on the client (CSR)
    renderMode: RenderMode.Client,
  },
  {
    path: 'about', // This page is static, so we prerender it (SSG)
    renderMode: RenderMode.Prerender,
  },
  {
    path: 'profile', // This page requires user-specific data, so we use SSR
    renderMode: RenderMode.Server,
  },
  {
    path: '**', // All other routes will be rendered on the server (SSR)
    renderMode: RenderMode.Server,
  },
];
```

Этот конфиг можно добавить в приложение через [`provideServerRendering`](api/ssr/provideServerRendering 'API reference') с функцией [`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)),
    // ... other providers ...
  ],
};
```

При использовании [паттерна App shell](ecosystem/service-workers/app-shell) нужно указать компонент, который будет использоваться как app shell для маршрутов с клиентским рендерингом. Для этого используйте feature [`withAppShell`](api/ssr/withAppShell 'API reference'):

```typescript
import {provideServerRendering, withRoutes, withAppShell} from '@angular/ssr';
import {AppShell} from './app-shell';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes), withAppShell(AppShell)),
    // ... other providers ...
  ],
};
```

### Режимы рендеринга {#rendering-modes}

Конфигурация server routing позволяет указать, как должен рендериться каждый маршрут приложения, задав [`RenderMode`](api/ssr/RenderMode 'API reference'):

| Режим рендеринга    | Описание                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Server (SSR)**    | Рендерит приложение на сервере для каждого запроса, отправляя в браузер полностью заполненную HTML-страницу. |
| **Client (CSR)**    | Рендерит приложение в браузере. Это поведение Angular по умолчанию.                                           |
| **Prerender (SSG)** | Prerender'ит приложение на этапе сборки, генерируя статические HTML-файлы для каждого маршрута.               |

#### Выбор режима рендеринга {#choosing-a-rendering-mode}

У каждого режима рендеринга свои плюсы и минусы. Режим можно выбирать исходя из конкретных потребностей приложения.

##### Client-side rendering (CSR) {#client-side-rendering-csr}

У клиентского рендеринга самая простая модель разработки: можно писать код, предполагая, что он всегда выполняется в веб-браузере. Это позволяет использовать широкий спектр клиентских библиотек, которые также предполагают работу в браузере.

Клиентский рендеринг обычно хуже по производительности, чем другие режимы: нужно скачать, разобрать и выполнить JavaScript страницы, прежде чем пользователь увидит какой-либо отрендеренный контент. Если страница при рендере запрашивает дополнительные данные с сервера, пользователям также приходится ждать эти запросы, прежде чем увидеть полный контент.

Если страница индексируется поисковыми краулерами, клиентский рендеринг может негативно влиять на search engine optimization (SEO), так как у краулеров есть ограничения на объём JavaScript, который они выполняют при индексации.

При клиентском рендеринге серверу не нужно делать работу по рендеру страницы сверх отдачи статических JavaScript-ассетов. Этот фактор можно учитывать, если важна стоимость сервера.

Приложения, поддерживающие устанавливаемый offline-опыт с [service workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API), могут опираться на клиентский рендеринг без необходимости общаться с сервером.

##### Server-side rendering (SSR) {#server-side-rendering-ssr}

Серверный рендеринг даёт более быструю загрузку страниц, чем клиентский. Вместо ожидания скачивания и выполнения JavaScript сервер напрямую рендерит HTML-документ при получении запроса от браузера. Пользователь испытывает только задержку, необходимую серверу для получения данных и рендера запрошенной страницы. Этот режим также устраняет необходимость в дополнительных сетевых запросах из браузера, так как код может получать данные во время рендера на сервере.

Серверный рендеринг обычно отлично подходит для SEO: поисковые краулеры получают полностью отрендеренный HTML-документ.

Серверный рендеринг требует писать код, который не строго зависит от browser API, и ограничивает выбор JavaScript-библиотек, предполагающих работу в браузере.

При серверном рендеринге сервер запускает Angular для создания HTML-ответа на каждый запрос, что может увеличить стоимость хостинга.

##### Build-time prerendering {#build-time-prerendering}

Prerendering даёт более быструю загрузку страниц, чем и клиентский, и серверный рендеринг. Поскольку prerendering создаёт HTML-документы на этапе _сборки_, сервер может напрямую отвечать на запросы статическим HTML-документом без дополнительной работы.

Prerendering требует, чтобы вся информация, необходимая для рендера страницы, была доступна на этапе _сборки_. Это значит, что prerender'енные страницы не могут включать данные, специфичные для пользователя, загружающего страницу. Prerendering в первую очередь полезен для страниц, одинаковых для всех пользователей приложения.

Поскольку prerendering происходит на этапе сборки, он может существенно увеличить время production-сборок. Использование [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') для создания большого числа HTML-документов может повлиять на общий размер файлов развёртывания и замедлить deployments.

Prerendering обычно отлично подходит для SEO: поисковые краулеры получают полностью отрендеренный HTML-документ.

Prerendering требует писать код, который не строго зависит от browser API, и ограничивает выбор JavaScript-библиотек, предполагающих работу в браузере.

Prerendering почти не добавляет overhead на запрос сервера: сервер отвечает статическими HTML-документами. Статические файлы также легко кэшируются Content Delivery Networks (CDN), браузерами и промежуточными слоями кэширования для ещё более быстрых последующих загрузок. Полностью статические сайты можно разворачивать только через CDN или static file server, без поддержки кастомного server runtime. Это повышает масштабируемость, снимая нагрузку с application web server, и особенно полезно для приложений с высоким трафиком.

NOTE: При использовании Angular service worker первый запрос рендерится на сервере, а все последующие обрабатываются service worker и рендерятся на клиенте.

### Установка заголовков и status codes {#setting-headers-and-status-codes}

Для отдельных server routes можно задать кастомные заголовки и status codes через свойства `headers` и `status` в конфигурации `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,
  },
  // ... other routes
];
```

### Редиректы {#redirects}

Angular обрабатывает редиректы, заданные свойством [`redirectTo`](api/router/Route#redirectTo 'API reference') в конфигурациях маршрутов, на сервере иначе.

**Server-Side Rendering (SSR)**
Редиректы выполняются стандартными HTTP-редиректами (например, 301, 302) в процессе серверного рендеринга.

**Prerendering (SSG)**
Редиректы реализуются как «soft redirects» с помощью тегов [`<meta http-equiv="refresh">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#refresh) в prerender'енном HTML.

### Кастомизация build-time prerendering (SSG) {#customizing-build-time-prerendering-ssg}

При использовании [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') можно указать несколько опций конфигурации для кастомизации prerendering и serving.

#### Параметризованные маршруты {#parameterized-routes}

Для каждого маршрута с [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') можно указать функцию [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference'). Она позволяет контролировать, какие конкретные параметры создают отдельные prerender'енные документы.

Функция [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') возвращает `Promise`, который разрешается в массив объектов. Каждый объект — key-value map имени параметра маршрута к значению. Например, если определён маршрут `post/:id`, `getPrerenderParams` может вернуть массив `[{id: 123}, {id: 456}]` и таким образом отрендерить отдельные документы для `post/123` и `post/456`.

Тело [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') может использовать функцию Angular [`inject`](api/core/inject 'API reference') для внедрения зависимостей и выполнения любой работы по определению маршрутов для prerender. Обычно это включает запросы для получения данных и построения массива значений параметров.

Эту функцию также можно использовать с catch-all маршрутами (например, `/**`), где имя параметра будет `"**"`, а возвращаемое значение — сегменты пути, например `foo/bar`. Их можно комбинировать с другими параметрами (например, `/post/:id/**`) для более сложных конфигураций маршрутов.

```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(); // Assuming this returns ['1', '2', '3']

return ids.map((id) => ({id})); // Generates paths like: /post/1, /post/2, /post/3
    },
  },
  {
    path: 'post/:id/**',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      return [
        {id: '1', '**': 'foo/3'},
        {id: '2', '**': 'bar/4'},
      ]; // Generates paths like: /post/1/foo/3, /post/2/bar/4
    },
  },
];
```

Поскольку [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') применяется исключительно к [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), эта функция всегда выполняется на этапе _сборки_. `getPrerenderParams` не должна опираться на browser-specific или server-specific API для данных.

IMPORTANT: При использовании [`inject`](api/core/inject 'API reference') внутри `getPrerenderParams` помните, что `inject` нужно использовать синхронно. Его нельзя вызывать внутри асинхронных callback'ов или после любых `await`. Подробнее см. `runInInjectionContext`.

#### Стратегии fallback {#fallback-strategies}

В режиме [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') можно указать стратегию fallback для обработки запросов к путям, которые не были prerender'ены.

Доступные стратегии fallback:

- **Server:** Fallback на серверный рендеринг. Это поведение **по умолчанию**, если свойство `fallback` не указано.
- **Client:** Fallback на клиентский рендеринг.
- **None:** Без fallback. Angular не будет обрабатывать запросы к путям, которые не prerender'ены.

```ts
// 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 to CSR if not prerendered
    async getPrerenderParams() {
      // This function returns an array of objects representing prerendered posts at the paths:
      // `/post/1`, `/post/2`, and `/post/3`.
      // The path `/post/4` will utilize the fallback behavior if it's requested.
      return [{id: 1}, {id: 2}, {id: 3}];
    },
  },
];
```

## Написание server-compatible компонентов {#authoring-server-compatible-components}

Некоторые распространённые browser API и возможности могут быть недоступны на сервере. Приложения не могут использовать browser-specific глобальные объекты вроде `window`, `document`, `navigator` или `location`, а также некоторые свойства `HTMLElement`.

В целом код, опирающийся на browser-specific символы, должен выполняться только в браузере, а не на сервере. Это можно обеспечить через хуки жизненного цикла `afterEveryRender` и `afterNextRender`. Они выполняются только в браузере и пропускаются на сервере.

```typescript
import {Component, viewChild, afterNextRender} from '@angular/core';

@Component({
  selector: 'my-cmp',
  template: `<span #content>{{ ... }}</span>`,
})
export class MyComponent {
  contentRef = viewChild.required<ElementRef>('content');

constructor() {
    afterNextRender(() => {
      // Safe to check `scrollHeight` because this will only run in the browser, not the server.
      console.log('content height: ' + this.contentRef().nativeElement.scrollHeight);
    });
  }
}
```

NOTE: Предпочитайте [platform-specific провайдеры](guide/ssr#providing-platform-specific-implementations) runtime-проверкам с `isPlatformBrowser` или `isPlatformServer`.

IMPORTANT: Избегайте использования `isPlatformBrowser` в шаблонах с `@if` или другими условными конструкциями для рендера разного контента на сервере и клиенте. Это вызывает несоответствия гидратации и сдвиги макета, негативно влияя на UX и [Core Web Vitals](https://web.dev/learn-core-web-vitals/). Вместо этого используйте `afterNextRender` для browser-specific инициализации и сохраняйте отрендеренный контент согласованным между платформами.

## Установка провайдеров на сервере {#setting-providers-on-the-server}

На стороне сервера значения top-level провайдеров задаются один раз, когда код приложения изначально разбирается и вычисляется.
Это значит, что провайдеры, настроенные с `useValue`, сохранят своё значение между несколькими запросами, пока серверное приложение не будет перезапущено.

Если нужно генерировать новое значение для каждого запроса, используйте factory-провайдер с `useFactory`. Factory-функция будет выполняться для каждого входящего запроса, гарантируя создание и назначение нового значения токену каждый раз.

## Предоставление platform-specific реализаций {#providing-platform-specific-implementations}

Когда приложению нужно разное поведение в браузере и на сервере, предоставьте отдельные реализации сервисов для каждой платформы. Этот подход централизует platform-логику в выделенных сервисах.

```ts
export abstract class AnalyticsService {
  abstract trackEvent(name: string): void;
}
```

Создайте реализацию для браузера:

```ts
@Injectable()
export class BrowserAnalyticsService implements AnalyticsService {
  trackEvent(name: string): void {
    // Sends the event to the browser-based third-party analytics provider
  }
}
```

Создайте реализацию для сервера:

```ts
@Injectable()
export class ServerAnalyticsService implements AnalyticsService {
  trackEvent(name: string): void {
    // Records the event on the server
  }
}
```

Зарегистрируйте браузерную реализацию в основной конфигурации приложения:

```ts
// app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: BrowserAnalyticsService}],
};
```

Переопределите серверной реализацией в серверной конфигурации:

```ts
// app.config.server.ts
const serverConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: ServerAnalyticsService}],
};
```

Внедряйте и используйте сервис в компонентах:

```ts
@Component(/* ... */)
export class Checkout {
  private analytics = inject(AnalyticsService);

onAction() {
    this.analytics.trackEvent('action');
  }
}
```

## Доступ к Document через DI {#accessing-document-via-di}

При работе с server-side rendering следует избегать прямых ссылок на browser-specific глобалы вроде `document`. Вместо этого используйте токен [`DOCUMENT`](api/core/DOCUMENT) для доступа к объекту document платформенно-независимым способом.

```ts
import {inject, DOCUMENT, Service} from '@angular/core';

@Service()
export class CanonicalLinkService {
  private readonly document = inject(DOCUMENT);

// During server rendering, inject a <link rel="canonical"> tag
  // so the generated HTML includes the correct canonical URL
  setCanonical(href: string): void {
    const link = this.document.createElement('link');
    link.rel = 'canonical';
    link.href = href;
    this.document.head.appendChild(link);
  }
}
```

HELPFUL: Для управления meta-тегами Angular предоставляет сервис `Meta`.

## Доступ к Request и Response через DI {#accessing-request-and-response-via-di}

Пакет `@angular/core` предоставляет несколько токенов для взаимодействия с окружением server-side rendering. Эти токены дают доступ к важной информации и объектам внутри Angular-приложения во время SSR.

- **[`REQUEST`](api/core/REQUEST 'API reference'):** Доступ к текущему объекту запроса типа [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) из Web API. Позволяет получать заголовки, cookies и другую информацию о запросе.
- **[`RESPONSE_INIT`](api/core/RESPONSE_INIT 'API reference'):** Доступ к опциям инициализации ответа типа [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#parameters) из Web API. Позволяет динамически задавать заголовки и status code ответа. Используйте этот токен для заголовков или status codes, которые нужно определить во время выполнения.
- **[`REQUEST_CONTEXT`](api/core/REQUEST_CONTEXT 'API reference'):** Доступ к дополнительному контексту, связанному с текущим запросом. Этот контекст можно передать как второй параметр функции [`handle`](api/ssr/AngularAppEngine#handle 'API reference'). Обычно используется для предоставления дополнительной request-related информации, не входящей в стандартный Web API.

```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: Указанные выше токены будут `null` в следующих сценариях:<ul class="docs-list">
  <li>Во время процессов сборки.</li>
  <li>Когда приложение рендерится в браузере (CSR).</li>
  <li>При выполнении static site generation (SSG).</li>
  <li>Во время извлечения маршрутов в разработке (на момент запроса).</li>
</ul>

## Генерация полностью статического приложения {#generate-a-fully-static-application}

По умолчанию Angular prerender'ит всё приложение и генерирует server-файл для обработки запросов. Это позволяет отдавать пользователям pre-rendered контент. Однако если предпочтителен полностью статический сайт без сервера, можно отказаться от этого поведения, задав `outputMode` в `static` в файле конфигурации `angular.json`.

Когда `outputMode` задан как `static`, Angular генерирует pre-rendered HTML-файлы для каждого маршрута на этапе сборки, но не генерирует server-файл и не требует Node.js-сервер для отдачи приложения. Это полезно для развёртывания на static hosting, где backend-сервер не нужен.

Чтобы настроить это, обновите файл `angular.json` следующим образом:

```json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "outputMode": "static"
          }
        }
      }
    }
  }
}
```

## Кэширование данных при использовании HttpClient {#caching-data-when-using-httpclient}

`HttpClient` кэширует исходящие сетевые запросы при работе на сервере. Эта информация сериализуется и передаётся в браузер как часть начального HTML, отправленного с сервера. В браузере `HttpClient` проверяет, есть ли данные в кэше, и если да — переиспользует их вместо нового HTTP-запроса во время начального рендера приложения. `HttpClient` перестаёт использовать кэш, как только приложение становится [stable](api/core/ApplicationRef#isStable) при работе в браузере.

### Настройка лимита размера тела ответа {#configuring-the-response-body-size-limit}

Когда `HttpClient` использует fetch backend по умолчанию во время server-side rendering, Angular ограничивает каждое тело ответа 1 MB. Этот лимит не даёт серверу буферизовать неожиданно большие ответы во время рендера. Если ответ превышает настроенный лимит, запрос завершается ошибкой [NG02825](errors/NG02825).

Если приложению нужно получать более крупные ответы во время серверного рендера, задайте `maxResponseBodySize` в опциях `provideServerRendering`:

```ts
import {provideServerRendering, withRoutes} from '@angular/ssr';
import {serverRoutes} from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(
      {
        maxResponseBodySize: 5 * 1024 * 1024, // 5MB
      },
      withRoutes(serverRoutes),
    ),
  ],
};
```

`maxResponseBodySize` задаётся в байтах и применяется глобально к server-side запросам `HttpClient`, использующим fetch backend.

IMPORTANT: Держите этот лимит настолько маленьким, насколько позволяет приложение. Увеличение позволяет server-side запросам буферизовать более крупные тела ответов, что может увеличить использование памяти и риск denial-of-service. Предпочитайте выносить крупные загрузки за пределы серверного рендера.

### Настройка опций кэширования {#configuring-the-caching-options}

Можно кастомизировать, как Angular кэширует HTTP-ответы во время server‑side rendering (SSR) и переиспользует их при гидратации, настроив `HttpTransferCacheOptions`.  
Эта конфигурация предоставляется глобально через `withHttpTransferCacheOptions` внутри `provideClientHydration()`.

По умолчанию `HttpClient` кэширует все запросы `HEAD` и `GET`, которые не содержат заголовков `Authorization`, `Proxy-Authorization` или `Cookie` и не отправлены с `withCredentials` или режимами Fetch API `credentials`, которые могут отправлять credentials. Angular также пропускает transfer cache, когда запрос или ответ включает директивы `Cache-Control`, запрещающие кэширование (`no-store`, `no-cache` или `private`), или когда опция Fetch API `cache` задана как `no-store` или `no-cache`. Ответы с заголовком `Set-Cookie` также пропускаются. Настройки фильтрации запросов можно переопределить через `withHttpTransferCacheOptions` в конфигурации гидратации.

```ts
import {bootstrapApplication} from '@angular/platform-browser';
import {provideClientHydration, withHttpTransferCacheOptions} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        includeHeaders: ['ETag', 'Cache-Control'],
        filter: (req) => !req.url.includes('/api/profile'),
        includePostRequests: true,
        includeRequestsWithAuthHeaders: false,
      }),
    ),
  ],
});
```

### `includeHeaders` {#includeheaders}

Указывает, какие заголовки из серверного ответа должны включаться в кэшированные записи.  
По умолчанию заголовки не включаются.

```ts
withHttpTransferCacheOptions({
  includeHeaders: ['ETag', 'Cache-Control'],
});
```

IMPORTANT: Избегайте включения чувствительных заголовков вроде токенов аутентификации. Они могут утечь user‑specific данные между запросами.

Включение `Cache-Control` в `includeHeaders` только делает этот заголовок доступным на гидратированном ответе. Angular уже автоматически оценивает заголовки `Cache-Control` при решении, подходит ли запрос или ответ для transfer cache.

### `includePostRequests` {#includepostrequests}

По умолчанию кэшируются только запросы `GET` и `HEAD`.  
Можно включить кэширование для запросов `POST`, когда они используются как операции чтения, например GraphQL-запросы.

```ts
withHttpTransferCacheOptions({
  includePostRequests: true,
});
```

Используйте это только когда запросы `POST` **идемпотентны** и безопасны для переиспользования между серверным и клиентским рендером.

### `includeRequestsWithAuthHeaders` {#includerequestswithauthheaders}

Определяет, подходят ли для кэширования запросы, содержащие заголовки `Authorization`, `Proxy‑Authorization` или `Cookie`.  
По умолчанию они исключены, чтобы не кэшировать user‑specific ответы.

```ts
withHttpTransferCacheOptions({
  includeRequestsWithAuthHeaders: true,
});
```

Включайте только когда заголовки аутентификации **не** влияют на содержимое ответа (например, публичные токены для analytics API).

### `includeRequestsWithCredentials` {#includerequestswithcredentials}

Определяет, подходят ли для кэширования запросы, отправленные с `withCredentials` или режимами Fetch API `credentials` (`include` или `same-origin`).  
По умолчанию они исключены, чтобы не кэшировать user‑specific ответы.

```ts
withHttpTransferCacheOptions({
  includeRequestsWithCredentials: true,
});
```

Включайте только когда credentialed-запросы возвращают ответы, безопасные для кэширования.

### `includeNonCacheableRequests` {#includenoncacheablerequests}

Определяет, подходят ли для кэширования запросы и ответы, содержащие директивы `Cache-Control`, запрещающие кэширование (`no-store`, `no-cache` или `private`), ответы с заголовком `Set-Cookie`, или запросы с опциями Fetch API `cache` (`no-store` или `no-cache`).  
По умолчанию они исключены, чтобы уважать HTTP-контроли кэширования.

```ts
withHttpTransferCacheOptions({
  includeNonCacheableRequests: true,
});
```

Включайте только когда нужно обойти ограничения cache-control для transfer caching.

### Per‑request переопределения {#perrequest-overrides}

Поведение кэширования для конкретного запроса можно переопределить через опцию запроса `transferCache`.

```ts
// Include specific headers for this request
http.get('/api/profile', {transferCache: {includeHeaders: ['CustomHeader']}});
```

### Отключение кэширования {#disabling-caching}

HTTP-кэширование запросов, отправленных с сервера, можно отключить глобально или индивидуально.

#### Глобально {#globally}

Чтобы отключить кэширование для всех запросов в приложении, используйте feature `withNoHttpTransferCache`:

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoHttpTransferCache,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoHttpTransferCache())],
});
```

#### Фильтрация {#filtering}

Также можно выборочно отключить кэширование для определённых запросов через опцию [`filter`](api/common/http/HttpTransferCacheOptions) в `withHttpTransferCacheOptions`. Например, отключить кэширование для конкретного API endpoint:

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        filter: (req) => !req.url.includes('/api/sensitive-data'),
      }),
    ),
  ],
});
```

Используйте эту опцию, чтобы исключить endpoints с user‑specific или динамическими данными (например, `/api/profile`).

#### Per-request {#per-request}

Чтобы отключить кэширование для отдельного запроса, укажите опцию [`transferCache`](api/common/http/HttpRequest#transferCache) в `HttpRequest`.

```ts
httpClient.get('/api/sensitive-data', {transferCache: false});
```

`HttpTransferCache` не кэширует запросы или ответы, которые явно отказываются от кэширования. Angular пропускает записи transfer cache, когда запрос включает заголовок `Cache-Control` с `no-store`, `no-cache` или `private`, или когда запрос использует опцию Fetch API `cache`, заданную как `no-store` или `no-cache`. Ответы с `Cache-Control: no-store`, `Cache-Control: no-cache` или `Cache-Control: private` также не сохраняются в transfer cache. Ответы с заголовком `Set-Cookie` тоже не сохраняются, так как обычно несут user-specific состояние.

NOTE: Если приложение использует разные HTTP origins для API-вызовов на сервере и на клиенте, токен `HTTP_TRANSFER_CACHE_ORIGIN_MAP` позволяет установить соответствие между этими origins, чтобы feature `HttpTransferCache` мог распознать эти запросы как одни и те же и переиспользовать данные, закэшированные на сервере, при гидратации на клиенте.

## Настройка сервера {#configuring-a-server}

### Node.js {#nodejs}

`@angular/ssr/node` расширяет `@angular/ssr` специально для окружений Node.js. Он предоставляет API, упрощающие реализацию server-side rendering в Node.js-приложении. Полный список функций и примеры использования — в [API reference `@angular/ssr/node`](api/ssr/node/AngularNodeAppEngine).

```ts
// 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(); // Pass control to the next middleware
      }
    })
    .catch(next);
});

/**
 * The request handler used by the Angular CLI (dev-server and during build).
 */
export const reqHandler = createNodeRequestHandler(app);
```

### Non-Node.js {#non-nodejs}

`@angular/ssr` предоставляет необходимые API для server-side rendering Angular-приложения на платформах, отличных от Node.js. Он опирается на стандартные объекты [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) и [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) из Web API, позволяя интегрировать Angular SSR в различные серверные окружения. Подробности и примеры — в [API reference `@angular/ssr`](api/ssr/AngularAppEngine).

```ts
// server.ts
import {AngularAppEngine, createRequestHandler} from '@angular/ssr';

const angularApp = new AngularAppEngine();

/**
 * This is a request handler used by the Angular CLI (dev-server and during build).
 */
export const reqHandler = createRequestHandler(async (req: Request) => {
  const res: Response | null = await angularApp.render(req);

// ...
});
```

## Безопасность {#security}

Подробнее о предотвращении Server-Side Request Forgery (SSRF) и настройке разрешённых hosts см. в руководстве [Server-side security](best-practices/security#preventing-server-side-request-forgery-ssrf).
# Гидратация

## Что такое гидратация {#what-is-hydration}

Гидратация — это процесс восстановления на клиенте приложения, отрендеренного на сервере. Он включает повторное использование DOM-структур, созданных на сервере, сохранение состояния приложения, передачу данных, уже полученных сервером, и другие связанные шаги.

## Почему гидратация важна? {#why-is-hydration-important}

Гидратация повышает производительность приложения, избегая лишней работы по повторному созданию DOM-узлов. Вместо этого Angular сопоставляет существующие DOM-элементы со структурой приложения во время выполнения и по возможности переиспользует узлы. Это даёт измеримый прирост по метрикам [Core Web Vitals (CWV)](https://web.dev/learn-core-web-vitals/), например снижение First Input Delay ([FID](https://web.dev/fid/)) и Largest Contentful Paint ([LCP](https://web.dev/lcp/)), а также Cumulative Layout Shift ([CLS](https://web.dev/cls/)). Улучшение этих показателей также влияет на SEO.

Без включённой гидратации Angular-приложения с SSR уничтожают и заново рендерят DOM, что может привести к заметному мерцанию UI. Такой повторный рендеринг негативно влияет на [Core Web Vitals](https://web.dev/learn-core-web-vitals/), например [LCP](https://web.dev/lcp/), и вызывает сдвиг макета. Включение гидратации позволяет переиспользовать существующий DOM и предотвращает мерцание.

## Как включить гидратацию в Angular {#how-do-you-enable-hydration-in-angular}

Гидратацию можно включить только для приложений с рендерингом на стороне сервера (SSR). Сначала следуйте [руководству по Angular SSR](guide/ssr), чтобы включить серверный рендеринг.

### Использование Angular CLI {#using-angular-cli}

Если вы включили SSR через Angular CLI (при создании приложения или позже через `ng add @angular/ssr`), код, включающий гидратацию, уже должен быть добавлен в приложение.

### Ручная настройка {#manual-setup}

Если у вас кастомная настройка и вы не использовали Angular CLI для включения SSR, гидратацию можно включить вручную: в главном компоненте или модуле приложения импортируйте `provideClientHydration` из `@angular/platform-browser` и добавьте этот провайдер в список провайдеров при bootstrap.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
} from '@angular/platform-browser';
...

bootstrapApplication(App, {
  providers: [provideClientHydration()]
});
```

Если вы используете NgModules, добавьте `provideClientHydration` в список провайдеров корневого модуля приложения.

```typescript
import {provideClientHydration} from '@angular/platform-browser';
import {NgModule} from '@angular/core';

@NgModule({
  declarations: [App],
  exports: [App],
  bootstrap: [App],
  providers: [provideClientHydration()],
})
export class AppModule {}
```

IMPORTANT: Убедитесь, что вызов `provideClientHydration()` также включён в набор провайдеров, используемый для bootstrap приложения на **сервере**. В приложениях со стандартной структурой проекта (созданной командой `ng new`) добавления вызова в корневой `AppModule` обычно достаточно, так как этот модуль импортируется серверным модулем. При кастомной настройке добавьте `provideClientHydration()` в список провайдеров конфигурации bootstrap на сервере.

### Проверка, что гидратация включена {#verify-that-hydration-is-enabled}

После настройки гидратации и запуска сервера загрузите приложение в браузере.

HELPFUL: Перед полной работой гидратации, скорее всего, потребуется исправить случаи прямой манипуляции DOM — перейти на конструкции Angular или использовать `ngSkipHydration`. Подробнее см. [Ограничения](#constraints), [Прямая манипуляция DOM](#direct-dom-manipulation) и [Как пропустить гидратацию для отдельных компонентов](#how-to-skip-hydration-for-particular-components).

В режиме разработки можно подтвердить, что гидратация включена, открыв Developer Tools в браузере и посмотрев консоль. Должно появиться сообщение со статистикой гидратации, например числом гидратированных компонентов и узлов. Angular считает статистику по всем компонентам на странице, включая сторонние библиотеки.

Также можно использовать [расширение Angular DevTools](tools/devtools), чтобы увидеть статус гидратации компонентов на странице. Angular DevTools позволяет включить оверлей, показывающий, какие части страницы были гидратированы. При ошибке несоответствия гидратации DevTools также подсветит компонент, вызвавший ошибку.

## Захват и повтор событий {#capturing-and-replaying-events}

Когда приложение отрендерено на сервере, оно видно в браузере сразу после загрузки HTML. Пользователи могут предполагать, что со страницей уже можно взаимодействовать, но обработчики событий не привязаны, пока гидратация не завершится. Начиная с v18, можно включить функцию Event Replay, которая захватывает все события до гидратации и воспроизводит их после её завершения. Включите её с помощью функции `withEventReplay()`, например:

```typescript
import {provideClientHydration, withEventReplay} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withEventReplay())],
});
```

### Как работает повтор событий {#how-event-replay-works}

Event Replay улучшает пользовательский опыт, захватывая события пользователя, произошедшие до завершения гидратации. Затем эти события воспроизводятся, чтобы ни одно взаимодействие не было потеряно.

Повтор событий делится на три основные фазы:

- **Захват взаимодействий пользователя**<br>
  До **гидратации** Event Replay захватывает и сохраняет все взаимодействия пользователя, например клики и другие нативные события браузера.

- **Хранение событий**<br>
  **Event Contract** держит в памяти все взаимодействия, записанные на предыдущем шаге, чтобы они не были потеряны для последующего воспроизведения.

- **Повторный запуск событий**<br>
  После завершения **гидратации** Angular повторно вызывает захваченные события.

Повтор событий поддерживает _нативные события браузера_, например `click`, `mouseover` и `focusin`. Подробнее о JSAction — библиотеке, на которой основан повтор событий, — можно прочитать [в readme](https://github.com/angular/angular/tree/main/packages/core/primitives/event-dispatch#readme).

Эта функция обеспечивает согласованный пользовательский опыт и не даёт игнорировать действия пользователя, выполненные до гидратации.

NOTE: Если включена [инкрементальная гидратация](guide/incremental-hydration), повтор событий автоматически включается «под капотом».

## Ограничения {#constraints}

Гидратация накладывает на приложение ряд ограничений, которых нет без неё. На сервере и на клиенте должна генерироваться одна и та же структура DOM. Процесс гидратации ожидает одинаковое дерево DOM в обоих местах. Это также включает пробелы и comment-узлы, которые Angular создаёт при рендеринге на сервере. Эти пробелы и узлы должны присутствовать в HTML, сгенерированном SSR.

IMPORTANT: HTML, полученный при серверном рендеринге, **не должен** изменяться между сервером и клиентом.

Если структуры DOM на сервере и клиенте не совпадают, гидратация столкнётся с проблемами при сопоставлении ожидаемого и фактического DOM. Чаще всего виноваты компоненты, которые напрямую манипулируют DOM через нативные DOM API.

### Прямая манипуляция DOM {#direct-dom-manipulation}

Если компоненты манипулируют DOM через нативные DOM API или используют `innerHTML` / `outerHTML`, процесс гидратации столкнётся с ошибками. Типичные проблемные случаи — доступ к `document`, поиск конкретных элементов и добавление узлов через `appendChild`. Отсоединение DOM-узлов и перемещение их в другие места также приводит к ошибкам.

Angular не знает об этих изменениях DOM и не может разрешить их во время гидратации. Он ожидает определённую структуру, но встречает другую. Такое несоответствие приводит к сбою гидратации и ошибке DOM mismatch ([см. ниже](#errors)).

Лучше отрефакторить компонент, чтобы избежать такой манипуляции DOM. По возможности используйте Angular API. Если поведение нельзя отрефакторить сразу, используйте атрибут `ngSkipHydration` ([описан ниже](#how-to-skip-hydration-for-particular-components)), пока не найдёте решение, совместимое с гидратацией.

### Корректная HTML-структура {#valid-html-structure}

В ряде случаев шаблон компонента с некорректной HTML-структурой может привести к ошибке DOM mismatch при гидратации.

Ниже — самые частые примеры такой проблемы.

- `<table>` без `<tbody>`
- `<div>` внутри `<p>`
- `<a>` внутри другого `<a>`

Если вы не уверены в валидности HTML, проверьте его [синтаксическим валидатором](https://validator.w3.org/).

NOTE: Стандарт HTML не требует элемент `<tbody>` внутри таблиц, но современные браузеры автоматически создают `<tbody>` в таблицах без него. Из-за этого несоответствия всегда явно объявляйте `<tbody>` в таблицах, чтобы избежать ошибок гидратации.

### Конфигурация Preserve Whitespaces {#preserve-whitespaces-configuration}

При использовании гидратации рекомендуется оставлять значение по умолчанию `false` для `preserveWhitespaces`. Если этой настройки нет в tsconfig, значение будет `false`, и менять ничего не нужно. Если включить сохранение пробелов через `preserveWhitespaces: true` в tsconfig, возможны проблемы с гидратацией. Эта конфигурация пока не полностью поддерживается.

HELPFUL: Убедитесь, что эта настройка задана **одинаково** в `tsconfig.server.json` для сервера и в `tsconfig.app.json` для браузерных сборок. Разные значения сломают гидратацию.

Если вы задаёте эту настройку в tsconfig, рекомендуется указать её только в `tsconfig.app.json` — по умолчанию `tsconfig.server.json` унаследует её оттуда.

### Кастомный или Noop Zone.js пока не поддерживаются {#custom-or-noop-zonejs-are-not-yet-supported}

Гидратация опирается на сигнал от Zone.js о стабильности приложения, чтобы Angular мог начать сериализацию на сервере или post-hydration cleanup на клиенте — удаление DOM-узлов, которые остались «невостребованными».

Предоставление кастомной или «noop» реализации Zone.js может изменить момент события «stable» и запустить сериализацию или cleanup слишком рано или слишком поздно. Эта конфигурация пока не полностью поддерживается; возможно, потребуется скорректировать тайминг события `onStable` в кастомной реализации Zone.js.

## Ошибки {#errors}

Существует несколько ошибок, связанных с гидратацией: от несоответствия узлов до случаев, когда `ngSkipHydration` использован на недопустимом host-узле. Самый частый случай — прямая манипуляция DOM через нативные API, из-за которой гидратация не может найти или сопоставить ожидаемую структуру DOM на клиенте с той, что была отрендерена на сервере. Другой случай описан ранее в разделе [Корректная HTML-структура](#valid-html-structure). Используйте валидную HTML-структуру в шаблонах — и этой ошибки удастся избежать.

Полный справочник ошибок гидратации — в [руководстве по ошибкам](/errors).

## Как пропустить гидратацию для отдельных компонентов {#how-to-skip-hydration-for-particular-components}

Некоторые компоненты могут работать некорректно при включённой гидратации из-за описанных выше проблем, например [прямой манипуляции DOM](#direct-dom-manipulation). Как временное решение можно добавить атрибут `ngSkipHydration` к тегу компонента, чтобы пропустить гидратацию всего компонента.

```html
<app-example ngSkipHydration />
```

Либо задайте `ngSkipHydration` как host binding.

```typescript
@Component({
  ...
  host: {ngSkipHydration: 'true'},
})
class ExampleComponent {}
```

Атрибут `ngSkipHydration` заставляет Angular пропустить гидратацию всего компонента и его потомков. С этим атрибутом компонент ведёт себя так, будто гидратация не включена: уничтожает себя и рендерит заново.

HELPFUL: Это исправит проблемы рендеринга, но для этого компонента (и его потомков) вы не получите преимуществ гидратации. Чтобы убрать аннотацию пропуска гидратации, нужно изменить реализацию компонента и избежать паттернов, ломающих гидратацию (например, прямой манипуляции DOM).

Атрибут `ngSkipHydration` можно использовать только на host-узлах компонентов. Если добавить его к другим узлам, Angular выбросит ошибку.

Помните: добавление `ngSkipHydration` к корневому компоненту приложения фактически отключит гидратацию для всего приложения. Используйте этот атрибут осторожно — это крайняя мера. Компоненты, ломающие гидратацию, следует считать багами, которые нужно исправить.

## Тайминг гидратации и стабильность приложения {#hydration-timing-and-application-stability}

Стабильность приложения — важная часть процесса гидратации. Гидратация и любые post-hydration процессы происходят только после того, как приложение сообщило о стабильности. Стабильность может задерживаться по разным причинам: таймауты и интервалы, неразрешённые промисы, незавершённые microtasks. В таких случаях может появиться ошибка [Application remains unstable](errors/NG0506), означающая, что приложение не достигло стабильного состояния за 10 секунд. Если приложение не гидратируется сразу, посмотрите, что влияет на стабильность, и отрефакторьте код, чтобы избежать этих задержек.

### Отладка стабильности приложения {#debugging-application-stability}

Утилита `provideStabilityDebugging` помогает понять, почему приложение не стабилизируется. В режиме разработки она предоставляется по умолчанию при использовании `provideClientHydration`. Её также можно добавить вручную в провайдеры приложения для production-сборок или при SSR без гидратации. Функция пишет в консоль информацию, если приложение стабилизируется дольше ожидаемого.

```typescript
import {provideStabilityDebugging} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';
import 'zone.js/plugins/task-tracking'; // Use if you have Zone.js with `provideZoneChangeDetection`

bootstrapApplication(App, {
  providers: [provideStabilityDebugging()],
});
```

При включении утилита логирует ожидающие задачи (`PendingTasks`) в консоль. Если приложение использует Zone.js, можно также импортировать `zone.js/plugins/task-tracking`, чтобы увидеть, какие macrotasks мешают Angular Zone стабилизироваться. Плагин даёт stack trace создания macrotask и помогает найти источник задержки.

IMPORTANT: Angular не удаляет плагин отслеживания задач zone.js и эту утилиту из production-сборок. Используйте их только для временной отладки проблем стабильности в разработке, в том числе для оптимизированных production-сборок.

## I18N {#i18n}

HELPFUL: По умолчанию Angular пропускает гидратацию для компонентов, использующих блоки i18n, фактически заново рендеря эти компоненты с нуля.

Чтобы включить гидратацию для блоков i18n, добавьте [`withI18nSupport`](/api/platform-browser/withI18nSupport) в вызов `provideClientHydration`.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withI18nSupport,
} from '@angular/platform-browser';
...

bootstrapApplication(App, {
  providers: [provideClientHydration(withI18nSupport())]
});
```

## Согласованный рендеринг на сервере и клиенте {#consistent-rendering-across-server-side-and-client-side}

Избегайте блоков `@if` и других условных конструкций, которые показывают разный контент при серверном и клиентском рендеринге — например, `@if` с функцией Angular `isPlatformBrowser`. Такие различия вызывают сдвиги макета, ухудшают UX и Core Web Vitals.

## Сторонние библиотеки с манипуляцией DOM {#third-party-libraries-with-dom-manipulation}

Ряд сторонних библиотек зависит от манипуляции DOM для рендеринга. Классический пример — графики D3. Без гидратации они работали, но при включённой гидратации могут вызывать ошибки DOM mismatch. Пока при таких ошибках можно добавить атрибут `ngSkipHydration` к компоненту, который рендерится с помощью этой библиотеки.

## Сторонние скрипты с манипуляцией DOM {#third-party-scripts-with-dom-manipulation}

Многие сторонние скрипты — трекеры рекламы, аналитика и т.п. — изменяют DOM до гидратации. Они могут вызывать ошибки гидратации, потому что страница больше не соответствует структуре, ожидаемой Angular. По возможности откладывайте такие скрипты до завершения гидратации. Рассмотрите [`AfterNextRender`](api/core/afterNextRender), чтобы отложить скрипт до post-hydration процессов.

## Инкрементальная гидратация {#incremental-hydration}

Инкрементальная гидратация — продвинутая форма гидратации с более гранулярным контролем над тем, когда происходит гидратация. Подробнее см. в [руководстве по инкрементальной гидратации](guide/incremental-hydration).
# Инкрементальная гидратация

**Инкрементальная гидратация** — продвинутый тип [гидратации](guide/hydration), при котором части приложения могут оставаться дегидратированными и _постепенно_ гидратироваться по мере необходимости.

## Зачем использовать инкрементальную гидратацию? {#why-use-incremental-hydration}

Инкрементальная гидратация — улучшение производительности поверх полной гидратации приложения. Она может давать меньшие начальные бандлы при UX, сопоставимом с полной гидратацией. Меньшие бандлы ускоряют начальную загрузку, снижая [First Input Delay (FID)](https://web.dev/fid) и [Cumulative Layout Shift (CLS)](https://web.dev/cls).

Инкрементальная гидратация также позволяет использовать откладываемые views (`@defer`) для контента, который раньше нельзя было откладывать. В частности, теперь можно использовать `@defer` для контента above the fold. До инкрементальной гидратации размещение `@defer` above the fold приводило к рендеру placeholder и последующей замене основным шаблоном блока `@defer` — это вызывало сдвиг макета. С инкрементальной гидратацией основной шаблон блока `@defer` рендерится без сдвига макета при гидратации.

## Как включить инкрементальную гидратацию в Angular? {#how-do-you-enable-incremental-hydration-in-angular}

Инкрементальную гидратацию можно включить для приложений, которые уже используют SSR с гидратацией. Сначала следуйте [руководству по Angular SSR](guide/ssr) для включения серверного рендеринга и [руководству по гидратации](guide/hydration) для включения гидратации.

Инкрементальная гидратация включена по умолчанию при использовании `provideClientHydration()`.

```ts
import {bootstrapApplication, provideClientHydration} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration()],
});
```

NOTE: Инкрементальная гидратация зависит от [повтора событий](guide/hydration#capturing-and-replaying-events) и включает его автоматически. Если у вас уже есть `withEventReplay()` в списке, его можно безопасно удалить.

Чтобы отказаться от инкрементальной гидратации, используйте `withNoIncrementalHydration()`:

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoIncrementalHydration,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoIncrementalHydration())],
});
```

## Как работает инкрементальная гидратация? {#how-does-incremental-hydration-work}

Инкрементальная гидратация строится поверх полной [гидратации](guide/hydration) приложения, [откладываемых views](/guide/templates/defer) и [повтора событий](guide/hydration#capturing-and-replaying-events). С инкрементальной гидратацией к блокам `@defer` можно добавлять дополнительные триггеры, задающие границы инкрементальной гидратации. Добавление триггера `hydrate` к defer-блоку говорит Angular загрузить зависимости этого блока при SSR и отрендерить основной шаблон вместо `@placeholder`. При клиентском рендеринге зависимости по-прежнему откладываются, а контент defer-блока остаётся дегидратированным, пока не сработает триггер `hydrate`. Этот триггер заставляет defer-блок загрузить зависимости и гидратировать контент. Любые события браузера — в частности те, что соответствуют слушателям, зарегистрированным в компоненте, — вызванные пользователем до гидратации, ставятся в очередь и воспроизводятся после завершения гидратации.

## Управление гидратацией контента с помощью триггеров {#controlling-hydration-of-content-with-triggers}

Можно задать **hydrate-триггеры**, которые контролируют, когда Angular загружает и гидратирует отложенный контент. Это дополнительные триггеры наряду с обычными триггерами `@defer`.

У каждого блока `@defer` может быть несколько hydrate-триггеров, разделённых точкой с запятой (`;`). Angular запускает гидратацию, когда срабатывает _любой_ из триггеров.

Есть три типа hydrate-триггеров: `hydrate on`, `hydrate when` и `hydrate never`.

### `hydrate on` {#hydrate-on}

`hydrate on` задаёт условие, при котором запускается гидратация блока `@defer`.

Доступные триггеры:

| Триггер                                             | Описание                                                                 |
| --------------------------------------------------- | ------------------------------------------------------------------------ |
| [`hydrate on idle`](#hydrate-on-idle)               | Срабатывает, когда браузер простаивает. Поддерживает опциональный timeout. |
| [`hydrate on viewport`](#hydrate-on-viewport)       | Срабатывает, когда указанный контент попадает во viewport                |
| [`hydrate on interaction`](#hydrate-on-interaction) | Срабатывает при взаимодействии пользователя с указанным элементом        |
| [`hydrate on hover`](#hydrate-on-hover)             | Срабатывает при наведении мыши на указанную область                      |
| [`hydrate on immediate`](#hydrate-on-immediate)     | Срабатывает сразу после рендера не-отложенного контента                  |
| [`hydrate on timer`](#hydrate-on-timer)             | Срабатывает через заданный интервал                                      |

#### `hydrate on idle` {#hydrate-on-idle}

Триггер `hydrate on idle` загружает зависимости откладываемого view и гидратирует контент, когда браузер переходит в idle-состояние на основе `requestIdleCallback`.

Опционально можно указать timeout в миллисекундах, который передаётся в [`requestIdleCallback`](https://developer.mozilla.org/docs/Web/API/Window/requestIdleCallback). Если браузер не запланирует callback достаточно быстро, работа выполнится не позже указанного timeout.

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

@defer (hydrate on idle(500)) {
  <large-cmp />
}
```

#### `hydrate on viewport` {#hydrate-on-viewport}

Триггер `hydrate on viewport` загружает зависимости откладываемого view и гидратирует соответствующую часть приложения, когда указанный контент попадает во viewport, используя
[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` {#hydrate-on-interaction}

Триггер `hydrate on interaction` загружает зависимости откладываемого view и гидратирует контент, когда пользователь взаимодействует с указанным элементом через события `click` или `keydown`.

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

#### `hydrate on hover` {#hydrate-on-hover}

Триггер `hydrate on hover` загружает зависимости откладываемого view и гидратирует контент, когда мышь наведена на область триггера через события `mouseover` и `focusin`.

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

#### `hydrate on immediate` {#hydrate-on-immediate}

Триггер `hydrate on immediate` загружает зависимости откладываемого view и гидратирует контент немедленно. То есть отложенный блок загружается сразу после того, как весь остальной не-отложенный контент закончил рендериться.

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

#### `hydrate on timer` {#hydrate-on-timer}

Триггер `hydrate on timer` загружает зависимости откладываемого view и гидратирует контент через заданный интервал.

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

Параметр длительности должен быть указан в миллисекундах (`ms`) или секундах (`s`).

### `hydrate when` {#hydrate-when}

Триггер `hydrate when` принимает пользовательское условное выражение и загружает зависимости откладываемого view и гидратирует контент, когда условие становится truthy.

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

NOTE: Условия `hydrate when` срабатывают только для самого верхнего дегидратированного блока `@defer`. Условие триггера задаётся в родительском компоненте, который должен существовать до срабатывания. Если родительский блок дегидратирован, Angular ещё не сможет разрешить это выражение.

### `hydrate never` {#hydrate-never}

`hydrate never` позволяет указать, что контент в defer-блоке должен оставаться дегидратированным бесконечно, фактически становясь статическим контентом. Это относится только к начальному рендеру. При последующем клиентском рендере блок `@defer` с `hydrate never` всё равно загрузит зависимости, так как гидратация применяется только к начальной загрузке SSR-контента. В примере ниже при последующих клиентских рендерах зависимости блока `@defer` загрузятся по viewport.

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

NOTE: Использование `hydrate never` предотвращает гидратацию всего вложенного поддерева данного блока `@defer`. Другие `hydrate`-триггеры для контента внутри этого блока не сработают.

## Hydrate-триггеры вместе с обычными триггерами {#hydrate-triggers-alongside-regular-triggers}

Hydrate-триггеры — дополнительные триггеры наряду с обычными триггерами блока `@defer`. Гидратация — оптимизация начальной загрузки, поэтому hydrate-триггеры применяются только к ней. Любой последующий клиентский рендер по-прежнему использует обычный триггер.

```html
@defer (on idle; hydrate on interaction) {
  <example-cmp />
} @placeholder {
  <div>Example Placeholder</div>
}
```

В этом примере при начальной загрузке применяется `hydrate on interaction`. Гидратация запустится при взаимодействии с компонентом `<example-cmp />`. При любой последующей загрузке страницы с клиентским рендерингом — например, когда пользователь кликает по routerLink, загружающему страницу с этим компонентом, — применится `on idle`.

## Как инкрементальная гидратация работает со вложенными блоками `@defer`? {#how-does-incremental-hydration-work-with-nested-defer-blocks}

Система компонентов и зависимостей Angular иерархична: для гидратации любого компонента нужно гидратировать и всех его родителей. Поэтому если гидратация запускается для дочернего блока `@defer` во вложенном наборе дегидратированных блоков `@defer`, гидратация идёт сверху вниз — от самого верхнего дегидратированного блока `@defer` к сработавшему дочернему — в этом порядке.

```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>
}
```

В примере выше наведение на вложенный блок `@defer` запускает гидратацию. Сначала гидратируется родительский блок `@defer` с `<parent-block-cmp />`, затем — дочерний блок `@defer` с `<child-block-cmp />`.

## Ограничения {#constraints}

У инкрементальной гидратации те же ограничения, что и у полной гидратации приложения, включая ограничения на прямую манипуляцию DOM и требование валидной HTML-структуры. Подробнее — в разделе [Ограничения руководства по гидратации](guide/hydration#constraints).

## Нужно ли по-прежнему указывать блоки `@placeholder`? {#do-i-still-need-to-specify-placeholder-blocks}

Да. Контент блока `@placeholder` не используется для инкрементальной гидратации, но `@placeholder` всё равно нужен для последующих случаев клиентского рендеринга. Если контент не был на маршруте начальной загрузки, любая навигация к маршруту с вашим блоком `@defer` отрендерит его как обычный блок `@defer`. Поэтому в таких случаях клиентского рендеринга рендерится `@placeholder`.
# Unit-тестирование

Тестирование приложения Angular помогает проверить, что оно работает так, как вы ожидаете. Unit-тесты критичны для раннего обнаружения багов, обеспечения качества кода и безопасного рефакторинга.

NOTE: Это руководство охватывает настройку тестирования по умолчанию для новых проектов Angular CLI, которая использует Vitest. Если вы мигрируете существующий проект с Karma, см. [руководство по миграции с Karma на Vitest](guide/testing/migrating-to-vitest). Karma по-прежнему поддерживается; подробнее см. [руководство по тестированию с Karma](guide/testing/karma).

## Настройка для тестирования {#set-up-for-testing}

Angular CLI загружает и устанавливает всё необходимое для тестирования приложения Angular с [фреймворком тестирования Vitest](https://vitest.dev). Новые проекты включают `vitest` и `jsdom` по умолчанию.

Vitest запускает unit-тесты в окружении Node.js. Чтобы симулировать DOM браузера, Vitest использует библиотеку `jsdom`. Это позволяет быстрее выполнять тесты, избегая накладных расходов на запуск браузера. Можно заменить `jsdom` на альтернативу вроде `happy-dom`, установив её и удалив `jsdom`. Сейчас поддерживаемые библиотеки эмуляции DOM — `jsdom` и `happy-dom`.

Проект, созданный с CLI, сразу готов к тестированию. Запустите команду [`ng test`](cli/test):

```shell
ng test
```

Команда `ng test` собирает приложение в режиме _watch_ и запускает [test runner Vitest](https://vitest.dev).

Вывод консоли выглядит так:

```shell
✓ src/app/app.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)
```

Команда `ng test` также следит за изменениями файлов. Если изменить файл и сохранить его, тесты запустятся снова.

## Конфигурация {#configuration}

Angular CLI обрабатывает большую часть конфигурации Vitest за вас. Поведение тестов можно настроить, изменив опции цели `test` в файле `angular.json`.

### Опции Angular.json {#angularjson-options}

- `include`: Glob-паттерны файлов для включения в тестирование. По умолчанию `['**/*.spec.ts', '**/*.test.ts']`.
- `exclude`: Glob-паттерны файлов для исключения из тестирования.
- `setupFiles`: Список путей к глобальным setup-файлам (например, polyfills или глобальные моки), выполняемым перед тестами.
- `providersFile`: Путь к файлу, экспортирующему массив Angular providers по умолчанию для тестового окружения. Полезно для настройки глобальных тестовых providers, внедряемых в тесты.
- `coverage`: Boolean для включения или отключения отчёта о покрытии кода. По умолчанию `false`.
- `browsers`: Массив имён браузеров для запуска тестов в реальном браузере (например, `["chromium"]`). Требует установки browser provider. См. раздел [Запуск тестов в браузере](#running-tests-in-a-browser).

### Глобальная настройка тестов и providers {#global-test-setup-and-providers}

Опции `setupFiles` и `providersFile` особенно полезны для управления глобальной конфигурацией тестов.

Например, можно создать файл `src/test-providers.ts` для предоставления `provideHttpClientTesting` всем тестам:

```typescript
{header: "src/test-providers.ts"}
import {EnvironmentProviders, Provider} from '@angular/core';
import {provideHttpClientTesting} from '@angular/common/http/testing';

const testProviders: (Provider | EnvironmentProviders)[] = [provideHttpClientTesting()];

export default testProviders;
```

Затем сошлитесь на этот файл в `angular.json`:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "providersFile": "src/test-providers.ts"
          }
        }
      }
    }
  }
}
```

HELPFUL: При создании новых TypeScript-файлов для setup тестов или providers, вроде `src/test-providers.ts`, убедитесь, что они включены в файл конфигурации TypeScript для тестов проекта (обычно `tsconfig.spec.json`). Это позволяет компилятору TypeScript корректно обрабатывать эти файлы во время тестирования.

### Продвинутая конфигурация Vitest {#advanced-vitest-configuration}

Для продвинутых сценариев можно предоставить пользовательский файл конфигурации Vitest через опцию `runnerConfig` в `angular.json`.

IMPORTANT: Хотя пользовательская конфигурация включает продвинутые опции, команда Angular не предоставляет поддержку содержимого файла конфигурации или сторонних плагинов. CLI также переопределит определённые свойства (`test.projects`, `test.include`) для обеспечения корректной интеграции.

Можно создать файл конфигурации Vitest (например, `vitest-base.config.ts`) и сослаться на него в `angular.json`:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "runnerConfig": "vitest-base.config.ts"
          }
        }
      }
    }
  }
}
```

Также можно сгенерировать базовый файл конфигурации через CLI:

```shell
ng generate config vitest
```

Это создаёт файл `vitest-base.config.ts`, который можно настроить.

HELPFUL: Подробнее о конфигурации Vitest — в [официальной документации Vitest](https://vitest.dev/config/).

## Покрытие кода {#code-coverage}

Отчёт о покрытии кода можно сгенерировать, добавив флаг `--coverage` к команде `ng test`. Отчёт генерируется в каталоге `coverage/`.

Подробнее см. в [руководстве по покрытию кода](guide/testing/code-coverage).

## Запуск тестов в браузере {#running-tests-in-a-browser}

Хотя окружение Node.js по умолчанию быстрее для большинства unit-тестов, тесты также можно запускать в реальном браузере. Это полезно для тестов, опирающихся на browser-specific API (например, рендер), или для отладки.

Чтобы запускать тесты в браузере, сначала нужно установить browser provider. Подробнее о browser mode Vitest — в [официальной документации](https://vitest.dev/guide/browser).

После установки provider можно запускать тесты в браузере, настроив опцию `browsers` в `angular.json` или используя флаг CLI `--browsers`. По умолчанию тесты запускаются в headed-браузере. Если установлена переменная окружения `CI`, вместо этого используется headless-режим. Чтобы явно управлять headless-режимом, можно добавить суффикс `Headless` к имени браузера (например, `chromiumHeadless`).

```bash
# Example for Playwright (headed)
ng test --browsers=chromium

# Example for Playwright (headless)
ng test --browsers=chromiumHeadless

# Example for WebdriverIO (headed)
ng test --browsers=chrome

# Example for WebdriverIO (headless)
ng test --browsers=chromeHeadless
```

Выберите один из следующих browser providers в зависимости от потребностей:

### Playwright {#playwright}

[Playwright](https://playwright.dev/) — библиотека автоматизации браузера, поддерживающая Chromium, Firefox и WebKit.

```shell
// npm
npm install --save-dev @vitest/browser-playwright playwright
```
```shell
// yarn
yarn add --dev @vitest/browser-playwright playwright
```
```shell
// pnpm
pnpm add -D @vitest/browser-playwright playwright
```
```shell
// bun
bun add --dev @vitest/browser-playwright playwright
```
### WebdriverIO {#webdriverio}

[WebdriverIO](https://webdriver.io/) — фреймворк автоматизации браузера и мобильных устройств, поддерживающий Chrome, Firefox, Safari и Edge.

```shell
// npm
npm install --save-dev @vitest/browser-webdriverio webdriverio
```
```shell
// yarn
yarn add --dev @vitest/browser-webdriverio webdriverio
```
```shell
// pnpm
pnpm add -D @vitest/browser-webdriverio webdriverio
```
```shell
// bun
bun add --dev @vitest/browser-webdriverio webdriverio
```
### Preview {#preview}

Provider `@vitest/browser-preview` предназначен для окружений WebContainer вроде StackBlitz и не предназначен для использования в CI/CD.

```shell
// npm
npm install --save-dev @vitest/browser-preview
```
```shell
// yarn
yarn add --dev @vitest/browser-preview
```
```shell
// pnpm
pnpm add -D @vitest/browser-preview
```
```shell
// bun
bun add --dev @vitest/browser-preview
```
HELPFUL: Для более продвинутой browser-specific конфигурации см. раздел [Продвинутая конфигурация Vitest](#advanced-vitest-configuration).

## Другие фреймворки тестирования {#other-test-frameworks}

Приложение Angular также можно unit-тестировать с другими библиотеками тестирования и test runners. У каждой библиотеки и runner свои процедуры установки, конфигурация и синтаксис.

## Тестирование в непрерывной интеграции {#testing-in-continuous-integration}

Надёжный набор тестов — ключевая часть пайплайна непрерывной интеграции (CI). CI-серверы позволяют автоматизировать тесты для запуска на каждом коммите и pull request.

Чтобы тестировать приложение Angular на CI-сервере, запустите стандартную команду тестирования:

```shell
ng test
```

Большинство CI-серверов устанавливают переменную окружения `CI=true`, которую обнаруживает `ng test`. Это автоматически настраивает тесты на запуск в неинтерактивном режиме single-run.

Если CI-сервер не устанавливает эту переменную или нужно принудительно включить режим single-run вручную, можно использовать флаги `--no-watch` и `--no-progress`:

```shell
ng test --no-watch --no-progress
```

## Дополнительная информация о тестировании {#more-information-on-testing}

После настройки приложения для тестирования могут быть полезны следующие руководства.

|                                                                    | Подробности                                                                       |
| :----------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| [Покрытие кода](guide/testing/code-coverage)                       | Сколько приложения покрывают тесты и как задать требуемые объёмы.                 |
| [Тестирование сервисов](guide/testing/services)                    | Как тестировать сервисы, которые использует приложение.                           |
| [Основы тестирования компонентов](guide/testing/components-basics) | Основы тестирования компонентов Angular.                                          |
| [Сценарии тестирования компонентов](guide/testing/components-scenarios) | Разные виды сценариев и use cases тестирования компонентов.                  |
| [Тестирование attribute-директив](guide/testing/attribute-directives) | Как тестировать attribute-директивы.                                          |
| [Тестирование pipes](guide/testing/pipes)                          | Как тестировать pipes.                                                            |
| [Отладка тестов](guide/testing/debugging)                          | Типичные баги тестирования.                                                       |
| [Утилитарные API тестирования](guide/testing/utility-apis)         | Возможности тестирования Angular.                                                 |
# Покрытие кода

Отчеты о покрытии кода показывают те части вашей кодовой базы, которые могут быть недостаточно протестированы вашими
юнит-тестами.

## Предварительные требования {#prerequisites}

Чтобы генерировать отчеты о покрытии кода с помощью Vitest, необходимо установить пакет `@vitest/coverage-v8`:

```shell
// npm
npm install --save-dev @vitest/coverage-v8
```
```shell
// yarn
yarn add --dev @vitest/coverage-v8
```
```shell
// pnpm
pnpm add -D @vitest/coverage-v8
```
```shell
// bun
bun add --dev @vitest/coverage-v8
```
## Генерация отчета {#generating-a-report}

Чтобы сгенерировать отчет о покрытии, добавьте флаг `--coverage` к команде `ng test`:

```shell
ng test --coverage
```

После выполнения тестов команда создаст новую директорию `coverage/` в проекте. Откройте файл `index.html`, чтобы
увидеть отчет с вашим исходным кодом и показателями покрытия.

Если вы хотите создавать отчеты о покрытии кода при каждом запуске тестов, вы можете установить опцию `coverage` в
значение `true` в вашем файле `angular.json`:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true
          }
        }
      }
    }
  }
}
```

## Контроль пороговых значений покрытия кода {#enforcing-code-coverage-thresholds}

Проценты покрытия кода позволяют оценить, какая часть вашего кода протестирована. Если ваша команда определила
минимальный объем, который должен быть покрыт юнит-тестами, вы можете закрепить этот минимум в конфигурации.

Например, предположим, что вы хотите, чтобы кодовая база имела покрытие кода не менее 80%. Чтобы включить это, добавьте
опцию `coverageThresholds` в ваш файл `angular.json`:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true,
            "coverageThresholds": {
              "statements": 80,
              "branches": 80,
              "functions": 80,
              "lines": 80
            }
          }
        }
      }
    }
  }
}
```

Теперь, если при запуске тестов покрытие упадет ниже 80%, выполнение команды завершится с ошибкой.

## Расширенная конфигурация {#advanced-configuration}

Вы можете настроить несколько других опций покрытия в вашем файле `angular.json`:

- `coverageInclude`: Glob-шаблоны файлов для включения в отчет о покрытии.
- `coverageReporters`: Массив используемых репортеров (например, `html`, `lcov`, `json`).
- `coverageWatermarks`: Объект, определяющий `[low, high]` (низкий, высокий) уровни для HTML-репортера, которые влияют
  на цветовую кодировку отчета.

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true,
            "coverageReporters": ["html", "lcov"],
            "coverageWatermarks": {
              "statements": [50, 80],
              "branches": [50, 80],
              "functions": [50, 80],
              "lines": [50, 80]
            }
          }
        }
      }
    }
  }
}
```
# Тестирование сервисов

Сервисы обычно содержат бизнес-логику приложения, на которую опираются компоненты. Тестирование сервисов проверяет, что логика работает корректно изолированно, независимо от любого компонента или шаблона.

Это руководство использует [Vitest](https://vitest.dev/), который проекты Angular CLI включают по умолчанию. Подробнее о настройке тестирования см. в [обзорном руководстве по тестированию](guide/testing#set-up-for-testing).

## Тестирование сервиса {#testing-a-service}

Рассмотрим сервис `Calculator`, выполняющий базовую арифметику:

```ts
{ header: 'calculator.ts' }
import {Service} from '@angular/core';

@Service()
export class Calculator {
  add(a: number, b: number): number {
    return a + b;
  }

subtract(a: number, b: number): number {
    return a - b;
  }
}
```

Чтобы протестировать этот сервис, настройте `TestBed` — утилиту тестирования Angular для создания изолированного окружения тестирования для каждого теста. Она настраивает внедрение зависимостей и позволяет получать экземпляры сервисов — имитируя, как Angular связывает вещи в реальном приложении.

```ts
{ header: 'calculator.spec.ts' }
import {TestBed} from '@angular/core/testing';
import {beforeEach, describe, expect, it} from 'vitest';
import {Calculator} from './calculator';

describe('Calculator', () => {
  let service: Calculator;

beforeEach(() => {
    // Injects the Calculator service which is available to Angular
    // because the service uses `providedIn: 'root'`
    service = TestBed.inject(Calculator);
  });

it('adds two numbers', () => {
    expect(service.add(1, 2)).toBe(3);
  });

it('subtracts two numbers', () => {
    expect(service.subtract(5, 3)).toBe(2);
  });
});
```

В примере выше блок `beforeEach` внедряет свежий экземпляр сервиса перед каждым тестом. Это гарантирует, что каждый тест выполняется изолированно без утечки состояния из предыдущих тестов.

## Тестирование сервисов с зависимостями {#testing-services-with-dependencies}

Большинство сервисов зависят от других сервисов для корректной работы. По умолчанию `TestBed` предоставляет реальные реализации этих зависимостей, то есть тесты упражняют фактические пути кода, которые использует приложение. Иногда, однако, зависимость может быть сложной, медленной или непредсказуемой. В таких случаях её можно заменить контролируемой подменой.

Рассмотрим сервис `OrderTotal`, который опирается на `TaxCalculator` для вычисления итоговой цены заказа:

```ts
{ header: 'tax-calculator.ts' }
import {Service} from '@angular/core';

@Service()
export class TaxCalculator {
  calculate(subtotal: number): number {
    return subtotal * 0.05;
  }
}
```

```ts
{ header: 'order-total.ts' }
import {inject, Service} from '@angular/core';
import {TaxCalculator} from './tax-calculator';

@Service()
export class OrderTotal {
  private taxCalculator = inject(TaxCalculator);

total(subtotal: number): number {
    return subtotal + this.taxCalculator.calculate(subtotal);
  }
}
```

В этом примере `OrderTotal` использует `inject()`, чтобы запросить `TaxCalculator` у системы внедрения зависимостей Angular. По умолчанию `TestBed` предоставляет реальный `TaxCalculator` — это идеально для простых вычислений вроде этого. Однако если `TaxCalculator` включал бы сложную логику, сетевые запросы или непредсказуемые результаты, его можно было бы заменить контролируемой подменой.

### Замена зависимости stub'ом {#replacing-a-dependency-with-a-stub}

Stub — способ заменить зависимость или метод таким, который возвращает предсказуемые значения, что упрощает проверку результатов теста.

Чтобы протестировать `OrderTotal` без опоры на реальный `TaxCalculator`, можно предоставить stub в конфигурации `TestBed`.

```ts
{ header: 'order-total.spec.ts' }
import {TestBed} from '@angular/core/testing';
import {beforeEach, describe, expect, it, vi, type Mocked} from 'vitest';
import {OrderTotal} from './order-total';
import {TaxCalculator} from './tax-calculator';

// Vitest's `Mocked` utility type ensures the stub is type-safe,
// while `vi.fn()` creates a mock function for each method
const taxCalculatorStub: Mocked<TaxCalculator> = {
  calculate: vi.fn(),
};

describe('OrderTotal', () => {
  let service: OrderTotal;

beforeEach(() => {
    // `mockReturnValue` sets a controlled return value for the stub
    taxCalculatorStub.calculate.mockReturnValue(5);

TestBed.configureTestingModule({
      // The `providers` array accepts a provider object where `provide`
      // specifies the dependency to replace and `useValue` defines the stub
      providers: [{provide: TaxCalculator, useValue: taxCalculatorStub}],
    });
    service = TestBed.inject(OrderTotal);
  });

it('adds tax to the subtotal', () => {
    expect(service.total(100)).toBe(105);
  });
});
```

С этим stub, когда `OrderTotal` запрашивает `TaxCalculator`, `TestBed` знает, что нужно использовать `taxCalculatorStub`. Поскольку stub всегда возвращает 5, тест проверяет, что `OrderTotal` корректно добавляет значение налога к подытогу независимо от того, меняется ли налоговая ставка в `TaxCalculator`.

### Проверка взаимодействий со spies {#verifying-interactions-with-spies}

Stub контролирует, что возвращает зависимость, но иногда также нужно проверить, что сервис вызвал свою зависимость с корректными аргументами. Это можно сделать со spies, которые отслеживают, как вызывается функция. В Vitest эта функциональность встроена в `vi.fn()` и позволяет утверждать взаимодействия между сервисами.

const taxCalculatorStub: Mocked<TaxCalculator> = {
  calculate: vi.fn(),
};

describe('OrderTotal', () => {
  let service: OrderTotal;

beforeEach(() => {
    taxCalculatorStub.calculate.mockReturnValue(5);

TestBed.configureTestingModule({
      providers: [{provide: TaxCalculator, useValue: taxCalculatorStub}],
    });
    service = TestBed.inject(OrderTotal);
  });

afterEach(() => {
    taxCalculatorStub.calculate.mockClear();
  });

it('adds tax to the subtotal', () => {
    expect(service.total(100)).toBe(105);
  });

// Verify the interaction with a spy
  it('calls the tax calculator', () => {
    service.total(100);
    expect(taxCalculatorStub.calculate).toHaveBeenCalledExactlyOnceWith(100);
  });
});
```

Новый тест проверяет, что `OrderTotal` вызвал `TaxCalculator.calculate` при вычислении итога. Это полезно при проверке корректности взаимодействия между сервисами.

## Тестирование HTTP-сервисов {#testing-http-services}

Многие сервисы используют `HttpClient` Angular для загрузки данных с сервера. Angular предоставляет специальные утилиты тестирования для `HttpClient`, позволяющие контролировать HTTP-ответы без реальных сетевых запросов.

Подробнее о тестировании сервисов, использующих `HttpClient`, см. в [руководстве по HTTP-тестированию](guide/http/testing).
# Основы тестирования компонентов

Компонент, в отличие от всех остальных частей приложения Angular, объединяет HTML-шаблон и класс TypeScript.
Компонент — это действительно шаблон и класс, _работающие вместе_.
Чтобы адекватно протестировать компонент, нужно проверить, что они работают вместе как задумано.

Такие тесты требуют создания host-элемента компонента в DOM браузера, как это делает Angular, и исследования взаимодействия класса компонента с DOM, описанного его шаблоном.

Angular `TestBed` упрощает такого рода тестирование, как вы увидите в следующих разделах.
Но во многих случаях _тестирование только класса компонента_, без участия DOM, может подтвердить большую часть поведения компонента более прямолинейным и очевидным способом.

## Тестирование DOM компонента {#component-dom-testing}

Компонент — это больше, чем просто его класс.
Компонент взаимодействует с DOM и с другими компонентами.
Одни только классы не скажут вам, будет ли компонент корректно рендериться, реагировать на пользовательский ввод и жесты или интегрироваться с родительскими и дочерними компонентами.

- Привязан ли `Lightswitch.clicked()` к чему-либо так, что пользователь может его вызвать?
- Отображается ли `Lightswitch.message`?
- Может ли пользователь действительно выбрать героя, отображаемого компонентом `DashboardHero`?
- Отображается ли имя героя как ожидается $например, в верхнем регистре$?
- Отображается ли приветственное сообщение шаблоном компонента `Welcome`?

Для простых компонентов из предыдущих примеров эти вопросы могут не вызывать беспокойства.
Но многие компоненты имеют сложные взаимодействия с DOM-элементами, описанными в их шаблонах, из-за чего HTML появляется и исчезает при изменении состояния компонента.

Чтобы ответить на такие вопросы, нужно создать DOM-элементы, связанные с компонентами, исследовать DOM, чтобы подтвердить, что состояние компонента отображается корректно в нужные моменты, и симулировать взаимодействие пользователя с экраном, чтобы определить, вызывают ли эти взаимодействия ожидаемое поведение компонента.

Чтобы писать такие тесты, вы будете использовать дополнительные возможности `TestBed`, а также другие вспомогательные средства тестирования.

### Тесты, сгенерированные CLI {#cli-generated-tests}

CLI по умолчанию создаёт начальный тестовый файл, когда вы просите сгенерировать новый компонент.

Например, следующая команда CLI генерирует компонент `Banner` в папке `app/banner` $с inline-шаблоном и стилями$:

```shell
ng generate component banner --inline-template --inline-style
```

Она также генерирует начальный тестовый файл для компонента, `banner.spec.ts`, который выглядит так:

```ts
import {ComponentFixture, TestBed} from '@angular/core/testing';
import {Banner} from './banner';

describe('Banner', () => {
  let component: Banner;
  let fixture: ComponentFixture<Banner>;

beforeEach(async () => {
    TestBed.configureTestingModule({});

fixture = TestBed.createComponent(Banner);
    component = fixture.componentInstance;
    await fixture.whenStable();
  });

it('should create', () => {
    expect(component).toBeTruthy();
  });
});
```

### Уменьшение setup {#reduce-the-setup}

Только последние три строки этого файла действительно тестируют компонент, и всё, что они делают — утверждают, что Angular может создать компонент.

Остальная часть файла — шаблонный код setup в ожидании более продвинутых тестов, которые _могут_ понадобиться, если компонент разовьётся во что-то существенное.

Вы узнаете об этих продвинутых возможностях тестирования в следующих разделах.
Пока можно радикально сократить этот тестовый файл до более управляемого размера:

```ts
describe('Banner (minimal)', () => {
  it('should create', () => {
    const fixture = TestBed.createComponent(Banner);
    const component = fixture.componentInstance;
    expect(component).toBeDefined();
  });
});
```

Позже вы вызовете `TestBed.configureTestingModule()` с imports, providers и другими declarations под ваши нужды тестирования.
Опциональные методы `override` могут дополнительно тонко настроить аспекты конфигурации.

NOTE: `TestBed.compileComponents` требуется только когда в тестируемых компонентах используются блоки `@defer`.

### `createComponent()` {#createcomponent}

После настройки `TestBed` вы вызываете его метод `createComponent()`.

```ts
const fixture = TestBed.createComponent(Banner);
```

`TestBed.createComponent()` создаёт экземпляр компонента `Banner`, добавляет соответствующий элемент в DOM test-runner и возвращает [`ComponentFixture`](#componentfixture).

IMPORTANT: Не перенастраивайте `TestBed` после вызова `createComponent`.

Метод `createComponent` фиксирует текущее определение `TestBed`, закрывая его для дальнейшей конфигурации.

Вы не можете вызывать больше методов конфигурации `TestBed` — ни `configureTestingModule()`, ни `get()`, ни какие-либо из методов `override...`.
Если попробуете, `TestBed` выбросит ошибку.

### `ComponentFixture` {#componentfixture}

[`ComponentFixture`](api/core/testing/ComponentFixture) — это test harness для взаимодействия с созданным компонентом и его соответствующим элементом.

Получите доступ к экземпляру компонента через fixture и подтвердите, что он существует, с помощью expectation:

```ts
const component = fixture.componentInstance;
expect(component).toBeDefined();
```

### `beforeEach()` {#beforeeach}

Вы будете добавлять больше тестов по мере развития этого компонента.
Вместо дублирования конфигурации `TestBed` для каждого теста сделайте рефакторинг: вынесите setup в `beforeEach()` и несколько вспомогательных переменных:

```ts
describe('Banner (with beforeEach)', () => {
  let component: Banner;
  let fixture: ComponentFixture<Banner>;

beforeEach(async () => {
    fixture = TestBed.createComponent(Banner);
    component = fixture.componentInstance;

await fixture.whenStable(); // necessary to wait for the initial rendering
  });

it('should create', () => {
    expect(component).toBeDefined();
  });
});
```

HELPFUL: Ожидая начальный рендеринг в `beforeEach` с `await fixture.whenStable`, отдельные тесты становятся синхронными.

Теперь добавьте тест, который получает элемент компонента из `fixture.nativeElement` и ищет ожидаемый текст.

```ts
it('should contain "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  expect(bannerElement.textContent).toContain('banner works!');
});
```

### создание функции `setup` {#create-a-setup-function}

Как альтернативу `beforeEach` можно также создать функцию setup, которую вы будете вызывать в каждом тесте.
Функция setup имеет преимущество настраиваемости через параметры.

Вот пример того, как может выглядеть функция setup:

```ts
function setup(providers?: StaticProviders[]): ComponentFixture<Banner> {
  TestBed.configureTestingModule({providers});
  return TestBed.createComponent(Banner);
}
```

### `nativeElement` {#nativeelement}

Значение `ComponentFixture.nativeElement` имеет тип `any`.
Позже вы встретите `DebugElement.nativeElement`, и у него тоже тип `any`.

Angular не может знать на этапе компиляции, какого рода HTML-элемент представляет `nativeElement` и является ли он вообще HTML-элементом.
Приложение может работать на _не-браузерной платформе_, например на сервере или в node-окружении, где у элемента может быть урезанный API или он может вовсе не существовать.

Тесты в этом руководстве рассчитаны на запуск в браузере, поэтому значение `nativeElement` всегда будет `HTMLElement` или одним из его производных классов.

Зная, что это `HTMLElement` какого-то рода, используйте стандартный HTML `querySelector`, чтобы углубиться в дерево элементов.

Вот ещё один тест, который вызывает `HTMLElement.querySelector`, чтобы получить элемент paragraph и найти текст баннера:

```ts
it('should have <p> with "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  const p = bannerElement.querySelector('p')!;
  expect(p.textContent).toEqual('banner works!');
});
```

### `DebugElement` {#debugelement}

Angular _fixture_ предоставляет элемент компонента напрямую через `fixture.nativeElement`.

```ts
const bannerElement: HTMLElement = fixture.nativeElement;
```

На самом деле это удобный метод, реализованный как `fixture.debugElement.nativeElement`.

```ts
const bannerDe: DebugElement = fixture.debugElement;
const bannerEl: HTMLElement = bannerDe.nativeElement;
```

Есть веская причина для такого окольного пути к элементу.

Свойства `nativeElement` зависят от runtime-окружения.
Вы можете запускать эти тесты на _не-браузерной_ платформе, у которой нет DOM или чья эмуляция DOM не поддерживает полный API `HTMLElement`.

Angular опирается на абстракцию `DebugElement`, чтобы безопасно работать на _всех поддерживаемых платформах_.
Вместо создания дерева HTML-элементов Angular создаёт дерево `DebugElement`, которое оборачивает _native elements_ для runtime-платформы.
Свойство `nativeElement` разворачивает `DebugElement` и возвращает объект элемента, специфичный для платформы.

Поскольку примеры тестов для этого руководства рассчитаны на запуск только в браузере, `nativeElement` в этих тестах всегда является `HTMLElement`, чьи знакомые методы и свойства вы можете исследовать в тесте.

Вот предыдущий тест, переписанный с `fixture.debugElement.nativeElement`:

```ts
it('should find the <p> with fixture.debugElement.nativeElement', () => {
  const bannerDe: DebugElement = fixture.debugElement;
  const bannerEl: HTMLElement = bannerDe.nativeElement;
  const p = bannerEl.querySelector('p')!;
  expect(p.textContent).toEqual('banner works!');
});
```

У `DebugElement` есть и другие методы и свойства, полезные в тестах, как вы увидите в других местах этого руководства.

Вы импортируете символ `DebugElement` из основной библиотеки Angular.

```ts
import {DebugElement} from '@angular/core';
```

### `By.css()` {#bycss}

Хотя тесты в этом руководстве все запускаются в браузере, некоторые приложения могут хотя бы иногда работать на другой платформе.

Например, компонент может сначала рендериться на сервере как часть стратегии, чтобы приложение быстрее запускалось на устройствах с плохим соединением.
Server-side renderer может не поддерживать полный API HTML-элементов.
Если он не поддерживает `querySelector`, предыдущий тест может упасть.

`DebugElement` предлагает методы запросов, которые работают на всех поддерживаемых платформах.
Эти методы запросов принимают функцию-_предикат_, которая возвращает `true`, когда узел в дереве `DebugElement` соответствует критериям выбора.

Вы создаёте _предикат_ с помощью класса `By`, импортированного из библиотеки для runtime-платформы.
Вот импорт `By` для браузерной платформы:

```ts
import {By} from '@angular/platform-browser';
```

Следующий пример переписывает предыдущий тест с `DebugElement.query()` и методом браузера `By.css`.

```ts
it('should find the <p> with fixture.debugElement.query(By.css)', () => {
  const bannerDe: DebugElement = fixture.debugElement;
  const paragraphDe = bannerDe.query(By.css('p'));
  const p: HTMLElement = paragraphDe.nativeElement;
  expect(p.textContent).toEqual('banner works!');
});
```

Несколько важных наблюдений:

- Статический метод `By.css()` выбирает узлы `DebugElement` со [стандартным CSS-селектором](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors 'CSS selectors').
- Запрос возвращает `DebugElement` для paragraph.
- Нужно развернуть этот результат, чтобы получить элемент paragraph.

Когда вы фильтруете по CSS-селектору и тестируете только свойства _native element_ браузера, подход `By.css` может быть избыточным.

Часто проще и понятнее фильтровать стандартным методом `HTMLElement`, таким как `querySelector()` или `querySelectorAll()`.
# Сценарии тестирования компонентов

Это руководство рассматривает типичные сценарии тестирования компонентов.

## Привязка компонента {#component-binding}

В примере приложения компонент `Banner` показывает статический текст заголовка в HTML-шаблоне.

После нескольких изменений компонент `Banner` показывает динамический заголовок, привязываясь к свойству `title` компонента следующим образом.

```typescript
{header="banner.ts"}
import {Component, signal} from '@angular/core';

@Component({
  selector: 'app-banner',
  template: '<h1>{{ title() }}</h1>',
  styles: ['h1 { color: green; font-size: 350%}'],
})
export class Banner {
  title = signal('Test Tour of Heroes');
}
```

Как бы минимально это ни было, вы решаете добавить тест, подтверждающий, что компонент действительно отображает нужный контент там, где вы ожидаете.

### Запрос `<h1>` {#query-for-the-h1}

Вы напишете последовательность тестов, которые проверяют значение элемента `<h1>`, оборачивающего интерполяционную привязку свойства _title_.

Обновите `beforeEach`, чтобы найти этот элемент стандартным HTML `querySelector` и присвоить его переменной `h1`.

```ts
{header: "banner.component.spec.ts"}
let component: Banner;
let fixture: ComponentFixture<Banner>;
let h1: HTMLElement;

beforeEach(() => {
  fixture = TestBed.createComponent(Banner);
  component = fixture.componentInstance; // Banner test instance
  h1 = fixture.nativeElement.querySelector('h1');
});
```

### `createComponent()` не привязывает данные {#createcomponent-does-not-bind-data}

В первом тесте хочется увидеть, что на экране отображается `title` по умолчанию.
Инстинктивно пишется тест, который сразу проверяет `<h1>` так:

```ts
it('should display original title', () => {
  expect(h1.textContent).toContain(component.title());
});
```

_Этот тест падает_ с сообщением:

```shell
{hideCopy}
expected '' to contain 'Test Tour of Heroes'.
```

Привязка происходит, когда Angular выполняет **обнаружение изменений**.

В production обнаружение изменений запускается автоматически, когда Angular создаёт компонент или, например, пользователь нажимает клавишу.

`TestBed.createComponent` не запускает обнаружение изменений синхронно; это подтверждается в пересмотренном тесте:

```ts
it('no title in the DOM after createComponent()', () => {
  expect(h1.textContent).toEqual('');
});
```

### `whenStable()` {#whenstable}

Можно указать `TestBed` дождаться выполнения обнаружения изменений через `await fixture.whenStable()`.
Только тогда у `<h1>` появляется ожидаемый заголовок.

```ts
it('should display original title', async () => {
  await fixture.whenStable();
  expect(h1.textContent).toContain(component.title());
});
```

Отложенное обнаружение изменений намеренно и полезно.
Оно даёт тестировщику возможность проверить и изменить состояние компонента _до того, как Angular инициирует привязку данных и вызовет [хуки жизненного цикла](guide/components/lifecycle)_.

Вот ещё один тест, который меняет свойство `title` компонента _перед_ вызовом `fixture.whenStable()`.

```ts
it('should display a different test title', async () => {
  component.title.set('Test Title');
  await fixture.whenStable();
  expect(h1.textContent).toContain('Test Title');
});
```

### Привязка сигналов к inputs {#binding-signals-to-inputs}

Чтобы отражать изменения inputs и слушать outputs, можно динамически привязывать сигналы к inputs и функции к outputs.

```ts
import {inputBinding, outputBinding} from '@angular/core';

const fixture = TestBed.createComponent(ValueDisplay, {
  bindings: [
    inputBinding('value', value),
    outputBinding('valueChange', () =>  (/* ... */) ),
  ],
});
```

### Изменение значения input через `dispatchEvent()` {#change-an-input-value-with-dispatchevent}

Чтобы симулировать ввод пользователя, найдите элемент input и установите его свойство `value`.

Но есть важный промежуточный шаг.

Angular не знает, что вы установили свойство `value` элемента input.
Он не прочитает это свойство, пока вы не поднимете событие `input` элемента вызовом `dispatchEvent()`.

Следующий пример компонента с `TitleCasePipe` демонстрирует правильную последовательность.

```ts
it('should convert hero name to Title Case', async () => {
  const hostElement = fixture.nativeElement;
  const nameInput: HTMLInputElement = hostElement.querySelector('input')!;
  const nameDisplay: HTMLElement = hostElement.querySelector('span')!;

// simulate user entering a new name into the input box
  nameInput.value = 'quick BROWN  fOx';

// Dispatch a DOM event so that Angular learns of input value change.
  nameInput.dispatchEvent(new Event('input'));

// Wait for Angular to update the display binding through the title pipe
  await fixture.whenStable();

expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
```

## Компонент с зависимостью {#component-with-a-dependency}

У компонентов часто есть зависимости от сервисов.

Компонент `Welcome` показывает приветственное сообщение вошедшему пользователю.
Он знает, кто пользователь, на основе свойства внедрённого `UserAuthentication`:

```typescript
import {Component, inject, OnInit, signal} from '@angular/core';
import {UserAuthentication} from '../model/user.authentication';

@Component({
  selector: 'app-welcome',
  template: '<h3 class="welcome"><i>{{ welcome() }}</i></h3>',
})
export class Welcome {
  private userAuth = inject(UserAuthentication);
  welcome = signal(
    this.userAuth.isLoggedIn() ? `Welcome, ${this.userAuth.user().name}` : 'Please log in.',
  );
}
```

У компонента `Welcome` есть логика принятия решений, взаимодействующая с сервисом — логика, из-за которой этот компонент стоит тестировать.

### Предоставление тестовых двойников сервисов {#provide-service-test-doubles}

_Тестируемый компонент_ не обязан получать реальные сервисы.

Внедрение реального `UserAuthentication` может быть затруднительным.
Реальный сервис может запрашивать учётные данные и пытаться достучаться до сервера аутентификации.
Такое поведение сложно перехватить. Имейте в виду, что тестовые двойники заставляют тест вести себя иначе, чем в production, поэтому используйте их умеренно.

### Получение внедрённых сервисов {#get-injected-services}

Тестам нужен доступ к `UserAuthentication`, внедрённому в компонент `Welcome`.

У Angular иерархическая система внедрения.
Инжекторы могут быть на нескольких уровнях — от корневого инжектора, созданного `TestBed`, вниз по дереву компонентов.

Самый безопасный способ получить внедрённый сервис — способ, который **_всегда работает_**, —
это **получить его из инжектора _тестируемого компонента_**.
Инжектор компонента — свойство `DebugElement` фикстуры.

```ts
// UserAuthentication actually injected into the component
userAuth = fixture.debugElement.injector.get(UserAuthentication);
```

HELPFUL: Обычно это _не обязательно_. Сервисы часто предоставляются в корне или через переопределения TestBed и их проще получить через `TestBed.inject()` (см. ниже).

### `TestBed.inject()` {#testbedinject}

Это проще запомнить и менее многословно, чем получение сервиса через `DebugElement` фикстуры.

В этом наборе тестов _единственный_ провайдер `UserAuthentication` — корневой тестовый модуль, поэтому безопасно вызывать `TestBed.inject()` так:

```ts
userAuth = TestBed.inject(UserAuthentication);
```

HELPFUL: Сценарий, в котором `TestBed.inject()` не работает, см. в разделе [_Переопределение провайдеров компонента_](#override-component-providers), где объясняется, когда и почему сервис нужно брать из инжектора компонента.

### Финальная настройка и тесты {#final-setup-and-tests}

Вот полный `beforeEach()`, использующий `TestBed.inject()`:

```ts
let fixture: ComponentFixture<Welcome>;
let comp: Welcome;
let userAuth: UserAuthentication; // the TestBed injected service
let el: HTMLElement; // the DOM element with the welcome message

beforeEach(() => {
  fixture = TestBed.createComponent(Welcome);
  comp = fixture.componentInstance;

// UserAuthentication from the root injector
  userAuth = TestBed.inject(UserAuthentication);

//  get the "welcome" element by CSS selector (e.g., by class name)
  el = fixture.nativeElement.querySelector('.welcome');
});
```

И вот несколько тестов:

```ts
it('should welcome the user', async () => {
  await fixture.whenStable();
  const content = el.textContent;

expect(content, '"Welcome ..."').toContain('Welcome');
  expect(content, 'expected name').toContain('Test User');
});

it('should welcome "Bubba"', async () => {
  userAuth.user.set({name: 'Bubba'}); // welcome message hasn't been shown yet
  await fixture.whenStable();

expect(el.textContent).toContain('Bubba');
});

it('should request login if not logged in', async () => {
  userAuth.isLoggedIn.set(false); // welcome message hasn't been shown yet
  await fixture.whenStable();
  const content = el.textContent;

expect(content, 'not welcomed').not.toContain('Welcome');
  expect(content, '"log in"').toMatch(/log in/i);
});
```

Первый — sanity-тест; он подтверждает, что `UserAuthentication` вызывается и работает.

HELPFUL: Второй аргумент `expect` $например, `'expected name'`$ — необязательная метка при падении.
Если ожидание не выполняется, Vitest добавляет эту метку к сообщению о падении.
В спецификации с несколькими ожиданиями это помогает понять, что пошло не так и какое ожидание упало.

Остальные тесты подтверждают логику компонента, когда сервис возвращает разные значения.
Второй тест проверяет эффект смены имени пользователя.
Третий проверяет, что компонент показывает правильное сообщение, когда нет вошедшего пользователя.

## Компонент с асинхронным сервисом {#component-with-async-service}

В этом примере шаблон компонента `About` содержит компонент `Twain`.
Компонент `Twain` показывает цитаты Марка Твена.

```html
<p class="twain">
  <i>{{ quote | async }}</i>
</p>
<button type="button" (click)="getQuote()">Next quote</button>
@if (errorMessage()) {
  <p class="error">{{ errorMessage() }}</p>
}
```

HELPFUL: Значение свойства `quote` компонента проходит через `AsyncPipe`.
Это значит, что свойство возвращает либо `Promise`, либо `Observable`.

В этом примере метод `TwainQuotes.getQuote()` показывает, что свойство `quote` возвращает `Observable`.

```ts
getQuote() {
  this.errorMessage.set('');
  this.quote = this.twainQuotes.getQuote().pipe(
    startWith('...'),
    catchError((err: any) => {
      this.errorMessage.set(err.message || err.toString());
      return of('...'); // reset message to placeholder
    }),
  );
}
```

Компонент `Twain` получает цитаты из внедрённого `TwainQuotes`.
Компонент начинает возвращённый `Observable` с placeholder-значения $`'...'`$ до того, как сервис вернёт первую цитату.

`catchError` перехватывает ошибки сервиса, готовит сообщение об ошибке и возвращает placeholder в канале успеха.

Всё это — функции, которые стоит протестировать.

### Тестирование через мокирование HTTP-запросов с `HttpTestingController` {#testing-by-mocking-http-requests-with-the-httptestingcontroller}

При тестировании компонента важны только публичные API сервиса.
В общем случае сами тесты не должны обращаться к удалённым серверам.
Они должны эмулировать такие вызовы.

Если асинхронный сервис опирается на `HttpClient` для загрузки удалённых данных, рекомендуется возвращать mock-ответы на уровне HTTP через `HttpTestingController`.

Подробнее о мокировании `HttpBackend` см. в [отдельном руководстве](guide/http/testing).

### Тестирование через stub-реализацию сервиса {#testing-by-providing-a-stubbed-implementation-of-a-service}

Когда мокирование асинхронного запроса на уровне HTTP невозможно, альтернатива — использовать spies.

Настройка в `app/twain/twain-quotes.spec.ts` показывает один из способов:

```ts
{header: "twain.spec.ts"}
class TwainQuotesStub implements TwainQuotes {
  private testQuote = 'Test Quote';

getQuote() {
    return of(this.testQuote);
  }

// ... Implement everything to conform to the API
}

beforeEach(async () => {
  TestBed.configureTestingModule({
    providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
  });

fixture = TestBed.createComponent(Twain);
  component = fixture.componentInstance;
  await fixture.whenStable();
  quoteEl = fixture.nativeElement.querySelector('.twain');
});
```

Обратите внимание, как stub-реализация заменяет оригинальную.

```ts
TestBed.configureTestingModule({
  providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
});
```

Stub спроектирован так, что любой компонент или сервис, который его внедряет, получит stub-реализацию.
Это значит, что любой вызов `getQuote` получает observable с тестовой цитатой.

В отличие от реального метода `getQuote()`, этот spy обходит сервер и возвращает синхронный observable, значение которого доступно сразу.

### Асинхронный тест с fake timers Vitest {#async-test-with-a-vitest-fake-timers}

Чтобы мокировать асинхронные функции вроде `setTimeout` или `Promise`, можно использовать fake timers Vitest и контролировать, когда они срабатывают.

```ts
it('should display error when TwainQuotes service fails', async () => {
  class TwainQuotesStub implements TwainQuotes {
    getQuote() {
      return defer(() => {
        return new Promise<string>((_, reject) => {
          setTimeout(() => reject('TwainService test failure'));
        });
      });
    }

// ... Implement everything to conform to the API
  }

TestBed.configureTestingModule({
    providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
  });

vi.useFakeTimers(); // setting up the fake timers
  const fixture = TestBed.createComponent(TwainComponent);

// rendering isn't async, we need to flush
  await vi.runAllTimersAsync();

await expect(fixture.nativeElement.querySelector('.error')!.textContent).toMatch(/test failure/);
  expect(fixture.nativeElement.querySelector('.twain')!.textContent).toBe('...');

vi.useRealTimers(); // resets to regular async execution
});
```

### Дополнительные асинхронные тесты {#more-async-tests}

Когда stub-сервис возвращает асинхронные observables, большинство тестов тоже должны быть асинхронными.

Вот тест, демонстрирующий поток данных, который ожидается в реальном мире.

```ts
it('should show quote after getQuote', async () => {
  class MockTwainQuotes implements TwainQuotes {
    private subject = new Subject<string>();

getQuote() {
      return this.subject.asObservable();
    }

emit(val: string) {
      this.subject.next(val);
    }
  }

it('should show quote after getQuote (success)', async () => {
    vi.useFakeTimers();

TestBed.configureTestingModule({
      providers: [{provide: TwainQuotes, useClass: MockTwainQuotes}],
    });

const fixture = TestBed.createComponent(TwainComponent);
    const twainQuotes = TestBed.inject(TwainQuotes) as MockTwainQuotes;
    await vi.runAllTimersAsync(); // render before the quote is received

const quoteEl = fixture.nativeElement.querySelector('.twain');
    expect(quoteEl.textContent).toBe('...');

twainQuotes.emit('Twain Quote'); // emits the quote
    await vi.runAllTimersAsync(); // render with the quote received

expect(quoteEl.textContent).toBe('Twain Quote');
    expect(fixture.nativeElement.querySelector('.error')).toBeNull();

vi.useRealTimers();
  });
});
```

Обратите внимание: элемент цитаты при первом рендере показывает placeholder $`'...'`$.
Первая цитата ещё не пришла.

Затем можно утверждать, что элемент цитаты показывает ожидаемый текст.

### Асинхронные тесты с `zone.js` и `fakeAsync` {#async-tests-with-zonejs-and-fakeasync}

Вспомогательная функция `fakeAsync` — ещё одни mock-часы, опирающиеся на патчинг асинхронных API через `zone.js`. Она часто использовалась в приложениях на `zone.js` для тестирования. Использование `fakeAsync` больше не рекомендуется.

TIP: Предпочитайте нативные стратегии асинхронного тестирования или другие fake timers (также называемые mock clocks), например из Vitest или Jasmine.

IMPORTANT: `fakeAsync` нельзя использовать с test runner Vitest, так как для этого runner патч `zone.js` не применяется.

## Компонент с inputs и outputs {#component-with-inputs-and-outputs}

Компонент с inputs и outputs обычно появляется внутри шаблона представления host-компонента.
Host использует property binding для установки input-свойства и event binding для прослушивания событий, поднимаемых output-свойством.

Цель тестирования — убедиться, что такие привязки работают как ожидается.
Тесты должны устанавливать значения inputs и слушать события outputs.

Компонент `DashboardHero` — крошечный пример компонента в этой роли.
Он отображает отдельного героя, предоставленного компонентом `Dashboard`.
Клик по этому герою сообщает компоненту `Dashboard`, что пользователь выбрал героя.

Компонент `DashboardHero` встроен в шаблон компонента `Dashboard` так:

```html
@for (hero of heroes; track hero) {
  <dashboard-hero class="col-1-4" [hero]="hero" (selected)="gotoDetail($event)" />
}
```

Компонент `DashboardHero` появляется в блоке `@for`, который устанавливает input-свойство `hero` каждого компонента в значение цикла и слушает событие `selected` компонента.

Вот полное определение компонента:

```typescript
@Component({
  selector: 'dashboard-hero',
  imports: [UpperCasePipe],
  template: `
    <button type="button" (click)="click()" class="hero">
      {{ hero().name | uppercase }}
    </button>
  `,
})
export class DashboardHero {
  readonly hero = input.required<Hero>();
  readonly selected = output<Hero>();

click() {
    this.selected.emit(this.hero());
  }
}
```

Хотя тестирование такого простого компонента имеет мало внутренней ценности, полезно знать, как это делать.
Используйте один из подходов:

- Тестировать его так, как использует компонент `Dashboard`
- Тестировать его как standalone-компонент
- Тестировать его так, как использует заменитель компонента `Dashboard`

Непосредственная цель — протестировать компонент `DashboardHero`, а не `Dashboard`, поэтому попробуйте второй и третий варианты.

### Тестирование компонента `DashboardHero` отдельно {#test-the-dashboardhero-component-standalone}

Вот суть настройки файла спецификации.

```ts
let fixture: ComponentFixture<DashboardHero>;
let comp: DashboardHero;
let heroDe: DebugElement;
let heroEl: HTMLElement;
let expectedHero: Hero;

beforeEach(async () => {
  fixture = TestBed.createComponent(DashboardHero);
  comp = fixture.componentInstance;

// find the hero's DebugElement and element
  heroDe = fixture.debugElement.query(By.css('.hero'));
  heroEl = heroDe.nativeElement;

// mock the hero supplied by the parent component
  expectedHero = {id: 42, name: 'Test Name'};

// simulate the parent setting the input property with that hero
  fixture.componentRef.setInput('hero', expectedHero);

// wait for initial data binding
  await fixture.whenStable();
});
```

Обратите внимание, как код настройки присваивает тестового героя $`expectedHero`$ свойству `hero` компонента, эмулируя то, как `Dashboard` установил бы его через property binding в своём repeater.

Следующий тест проверяет, что имя героя попадает в шаблон через привязку.

```ts
it('should display hero name in uppercase', () => {
  const expectedPipedName = expectedHero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});
```

Поскольку шаблон пропускает имя героя через Angular `UpperCasePipe`, тест должен сопоставить значение элемента с именем в верхнем регистре.

### Клики {#clicking}

Клик по герою должен поднять событие `selected`, которое host-компонент $предположительно `Dashboard`$ может услышать:

```ts
it('should raise selected event when clicked (triggerEventHandler)', () => {
  let selectedHero: Hero | undefined;
  comp.selected.subscribe((hero: Hero) => (selectedHero = hero));

heroDe.triggerEventHandler('click');
  expect(selectedHero).toBe(expectedHero);
});
```

Свойство `selected` компонента возвращает `EventEmitter`, который для потребителей выглядит как синхронный RxJS `Observable`.
Тест подписывается на него _явно_, так же как host-компонент делает это _неявно_.

Если компонент ведёт себя как ожидается, клик по элементу героя должен сказать свойству `selected` компонента эмитировать объект `hero`.

Тест обнаруживает это событие через подписку на `selected`.

### `triggerEventHandler` {#triggereventhandler}

`heroDe` в предыдущем тесте — это `DebugElement`, представляющий `<div>` героя.

У него есть свойства и методы Angular, абстрагирующие взаимодействие с нативным элементом.
Этот тест вызывает `DebugElement.triggerEventHandler` с именем события "click".
Привязка события "click" отвечает вызовом `DashboardHero.click()`.

Angular `DebugElement.triggerEventHandler` может поднять _любое data-bound событие_ по его _имени события_.
Второй параметр — объект события, передаваемый обработчику.

Тест вызвал событие "click".

```ts
heroDe.triggerEventHandler('click');
```

В этом случае тест корректно предполагает, что runtime-обработчик события — метод `click()` компонента — не заботится об объекте события.

HELPFUL: Другие обработчики менее снисходительны.
Например, директива `RouterLink` ожидает объект со свойством `button`, идентифицирующим, какая кнопка мыши, если какая-либо, была нажата во время клика.
Директива `RouterLink` выбрасывает ошибку, если объект события отсутствует.

### Клик по элементу {#click-the-element}

Следующая альтернатива теста вызывает собственный метод `click()` нативного элемента, что для _этого компонента_ вполне нормально.

```ts
it('should raise selected event when clicked (element.click)', () => {
  let selectedHero: Hero | undefined;
  comp.selected.subscribe((hero: Hero) => (selectedHero = hero));

heroEl.click();
  expect(selectedHero).toBe(expectedHero);
});
```

### Хелпер `click()` {#click-helper}

Клик по кнопке, якорю или произвольному HTML-элементу — типичная задача теста.

Сделайте это единообразным и простым, инкапсулировав процесс _вызова клика_ в хелпер вроде следующей функции `click()`:

```ts
/** Button events to pass to `DebugElement.triggerEventHandler` for RouterLink event handler */
export const ButtonClickEvents = {
  left: {button: 0},
  right: {button: 2},
};

/** Simulate element click. Defaults to mouse left-button click event. */
export function click(
  el: DebugElement | HTMLElement,
  eventObj: any = ButtonClickEvents.left,
): void {
  if (el instanceof HTMLElement) {
    el.click();
  } else {
    el.triggerEventHandler('click', eventObj);
  }
}
```

Первый параметр — _элемент для клика_.
При желании передайте пользовательский объект события вторым параметром.
По умолчанию — частичный [объект события левой кнопки мыши](https://developer.mozilla.org/docs/Web/API/MouseEvent/button), принимаемый многими обработчиками, включая директиву `RouterLink`.

IMPORTANT: Вспомогательная функция `click()` **не** входит в утилиты тестирования Angular.
Это функция, определённая в _примерах кода этого руководства_.
Все примеры тестов её используют.
Если она вам нравится, добавьте её в свою коллекцию хелперов.

Вот предыдущий тест, переписанный с хелпером click.

```ts
it('should raise selected event when clicked (click helper with DebugElement)', () => {
  let selectedHero: Hero | undefined;
  comp.selected.subscribe((hero: Hero) => (selectedHero = hero));

click(heroDe); // click helper with DebugElement

expect(selectedHero).toBe(expectedHero);
});
```

## Компонент внутри тестового host {#component-inside-a-test-host}

Предыдущие тесты сами играли роль host-компонента `Dashboard`.
Но корректно ли работает компонент `DashboardHero`, когда правильно data-bound к host-компоненту?

```typescript
@Component({
  imports: [DashboardHero],
  template: ` <dashboard-hero [hero]="hero" (selected)="onSelected($event)" />`,
})
class TestHost {
  hero: Hero = {id: 42, name: 'Test Name'};
  selectedHero: Hero | undefined;

onSelected(hero: Hero) {
    this.selectedHero = hero;
  }
}
```

Тестовый host устанавливает input-свойство `hero` компонента своим тестовым героем.
Он привязывает событие `selected` компонента к своему обработчику `onSelected`, который записывает эмитированного героя в свойство `selectedHero`.

Позже тесты смогут проверить `selectedHero`, чтобы убедиться, что событие `DashboardHero.selected` эмитировало ожидаемого героя.

Настройка тестов `test-host` похожа на настройку standalone-тестов:

```ts
beforeEach(async () => {
  // create TestHost instead of DashboardHero
  fixture = TestBed.createComponent(TestHost);
  testHost = fixture.componentInstance;
  heroEl = fixture.nativeElement.querySelector('.hero');

await fixture.whenStable();
});
```

Эта конфигурация тестового модуля показывает два важных отличия:

- Она _создаёт_ компонент `TestHost` вместо `DashboardHero`
- Компонент `TestHost` устанавливает `DashboardHero.hero` через привязку

`createComponent` возвращает `fixture`, которая держит экземпляр `TestHost` вместо экземпляра `DashboardHero`.

Создание `TestHost` имеет побочный эффект создания `DashboardHero`, потому что последний появляется в шаблоне первого.
Запрос элемента героя $`heroEl`$ по-прежнему находит его в тестовом DOM, хотя и на большей глубине в дереве элементов, чем раньше.

Сами тесты почти идентичны standalone-версии:

```ts
it('should display hero name', () => {
  const expectedPipedName = testHost.hero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});

it('should raise selected event when clicked', () => {
  click(heroEl);
  // selected hero should be the same data bound hero
  expect(testHost.selectedHero).toBe(testHost.hero);
});
```

Отличается только тест события selected.
Он подтверждает, что выбранный герой `DashboardHero` действительно проходит вверх через event binding к host-компоненту.

## Routing-компонент {#routing-component}

_Routing-компонент_ — это компонент, который говорит `Router` перейти к другому компоненту.
Компонент `Dashboard` — _routing-компонент_, потому что пользователь может перейти к компоненту `HeroDetail`, кликнув по одной из _кнопок героев_ на dashboard.

Angular предоставляет тестовые хелперы, чтобы уменьшить boilerplate и эффективнее тестировать код, зависящий от `HttpClient`. Функцию `provideRouter` также можно использовать напрямую в тестовом модуле.

```ts
beforeEach(async () => {
  TestBed.configureTestingModule({
    providers: [
      provideRouter([{path: '**', component: Dashboard}]),
      provideHttpClientTesting(),
      HeroService,
    ],
  });
  harness = await RouterTestingHarness.create();
  comp = await harness.navigateByUrl('/', Dashboard);
  TestBed.inject(HttpTestingController).expectOne('api/heroes').flush(getTestHeroes());
});
```

Следующий тест кликает по отображённому герою и подтверждает навигацию к ожидаемому URL.

```ts
it('should tell navigate when hero clicked', async () => {
  // get first <dashboard-hero> DebugElement
  const heroDe = harness.routeDebugElement!.query(By.css('dashboard-hero'));
  heroDe.triggerEventHandler('selected', comp.heroes[0]);

// expecting to navigate to id of the component's first hero
  const id = comp.heroes[0].id;
  expect(TestBed.inject(Router).url, 'should nav to HeroDetail for first hero').toEqual(
    `/heroes/${id}`,
  );
});
```

## Routed-компоненты {#routed-components}

_Routed-компонент_ — это назначение навигации `Router`.
Его может быть сложнее тестировать, особенно когда маршрут к компоненту _включает параметры_.
`HeroDetail` — _routed-компонент_, являющийся назначением такого маршрута.

Когда пользователь кликает по герою на _Dashboard_, `Dashboard` говорит `Router` перейти к `heroes/:id`.
`:id` — параметр маршрута, значение которого — `id` героя для редактирования.

`Router` сопоставляет этот URL с маршрутом к `HeroDetail`.
Он создаёт объект `ActivatedRoute` с информацией о маршрутизации и внедряет его в новый экземпляр `HeroDetail`.

Вот сервисы, внедрённые в `HeroDetail`:

```ts
private heroDetailService = inject(HeroDetailService);
private route = inject(ActivatedRoute);
private router = inject(Router);
```

Компоненту `HeroDetail` нужен параметр `id`, чтобы получить соответствующего героя через `HeroDetailService`.
Компонент должен получить `id` из свойства `ActivatedRoute.paramMap`, которое является `Observable`.

Нельзя просто сослаться на свойство `id` у `ActivatedRoute.paramMap`.
Компонент должен _подписаться_ на observable `ActivatedRoute.paramMap` и быть готовым к тому, что `id` изменится в течение его жизни.

```ts
constructor() {
  // get hero when `id` param changes
  this.route.paramMap
    .pipe(takeUntilDestroyed())
    .subscribe((pmap) => this.getHero(pmap.get('id')));
}
```

Тесты могут исследовать, как `HeroDetail` реагирует на разные значения параметра `id`, навигируя к разным маршрутам.

## Тесты вложенных компонентов {#nested-component-tests}

Шаблоны компонентов часто содержат вложенные компоненты, чьи шаблоны могут содержать ещё компоненты.

Дерево компонентов может быть очень глубоким, и иногда вложенные компоненты не играют роли в тестировании компонента на вершине дерева.

Компонент `App`, например, показывает панель навигации с якорями и их директивами `RouterLink`.

```html
<app-banner />
<app-welcome />

<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>

<router-outlet />
```

Чтобы проверить ссылки, но не навигацию, вам не нужен `Router` для навигации и не нужен `<router-outlet>`, чтобы отмечать, куда `Router` вставляет _routed-компоненты_.

Компоненты `Banner` и `Welcome` $обозначенные `<app-banner>` и `<app-welcome>`$ тоже нерелевантны.

И всё же любой тест, создающий компонент `App` в DOM, также создаёт экземпляры этих трёх компонентов, и если вы это допустите, придётся настроить `TestBed` для их создания.

Если забыть объявить их, компилятор Angular не распознает теги `<app-banner>`, `<app-welcome>` и `<router-outlet>` в шаблоне `App` и выбросит ошибку.

Если объявить реальные компоненты, придётся также объявить _их_ вложенные компоненты и предоставить _все_ сервисы, внедрённые в _любой_ компонент дерева.

Этот раздел описывает две техники минимизации настройки.
Используйте их по отдельности или вместе, чтобы оставаться сосредоточенными на тестировании основного компонента.

### Stubbing ненужных компонентов {#stubbing-unneeded-components}

В первой технике вы создаёте и объявляете stub-версии компонентов и директив, которые играют малую роль или не играют роли в тестах.

```ts
@Component({selector: 'app-banner', template: ''})
class BannerStub {}

@Component({selector: 'router-outlet', template: ''})
class RouterOutletStub {}

@Component({selector: 'app-welcome', template: ''})
class WelcomeStub {}
```

Селекторы stub совпадают с селекторами соответствующих реальных компонентов.
Но их шаблоны и классы пусты.

Затем объявите их, переопределив `imports` вашего компонента через `TestBed.overrideComponent`.

```ts
let comp: App;
let fixture: ComponentFixture<App>;

beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    set: {
      imports: [RouterLink, BannerStub, RouterOutletStub, WelcomeStub],
    },
  });

fixture = TestBed.createComponent(App);
  comp = fixture.componentInstance;
});
```

HELPFUL: Ключ `set` в этом примере заменяет все существующие imports вашего компонента — убедитесь, что импортируете все зависимости, а не только stubs. Альтернативно можно использовать ключи `remove`/`add` для выборочного удаления и добавления imports.

### `NO_ERRORS_SCHEMA` {#noerrorsschema}

Во втором подходе добавьте `NO_ERRORS_SCHEMA` в переопределения метаданных вашего компонента.

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    set: {
      imports: [], // resets all imports
      schemas: [NO_ERRORS_SCHEMA],
    },
  });
});
```

`NO_ERRORS_SCHEMA` говорит компилятору Angular игнорировать нераспознанные элементы и атрибуты.

Компилятор распознаёт элемент `<app-root>` и атрибут `routerLink`, потому что вы объявили соответствующий компонент `App` и `RouterLink` в конфигурации `TestBed`.

Но компилятор не выбросит ошибку, когда встретит `<app-banner>`, `<app-welcome>` или `<router-outlet>`.
Он просто отрендерит их как пустые теги, и браузер их проигнорирует.

Stub-компоненты больше не нужны.

### Использование обеих техник вместе {#use-both-techniques-together}

Это техники _Shallow Component Testing_ — так названные, потому что они уменьшают визуальную поверхность компонента до тех элементов в шаблоне, которые важны для тестов.

Подход с `NO_ERRORS_SCHEMA` проще из двух, но не злоупотребляйте им.

`NO_ERRORS_SCHEMA` также мешает компилятору сообщать о пропущенных компонентах и атрибутах, которые вы случайно опустили или опечатали.
Можно потратить часы на поиск фантомных багов, которые компилятор поймал бы мгновенно.

Подход со _stub-компонентами_ имеет ещё одно преимущество.
Хотя stubs в _этом_ примере были пустыми, им можно дать урезанные шаблоны и классы, если тестам нужно как-то с ними взаимодействовать.

На практике вы комбинируете обе техники в одной настройке, как в этом примере.

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    remove: {imports: [RouterOutlet, Welcome]},
    set: {schemas: [NO_ERRORS_SCHEMA]},
  });
});
```

Компилятор Angular создаёт `BannerStub` для элемента `<app-banner>` и применяет `RouterLink` к якорям с атрибутом `routerLink`, но игнорирует теги `<app-welcome>` и `<router-outlet>`.

### `By.directive` и внедрённые директивы {#bydirective-and-injected-directives}

Немного дополнительной настройки запускает начальную привязку данных и получает ссылки на навигационные ссылки:

```ts
beforeEach(async () => {
  await fixture.whenStable();

// find DebugElements with an attached RouterLinkStubDirective
  linkDes = fixture.debugElement.queryAll(By.directive(RouterLink));

// get attached link directive instances
  // using each DebugElement's injector
  routerLinks = linkDes.map((de) => de.injector.get(RouterLink));
});
```

Три момента особого интереса:

- Найдите элементы-якоря с прикреплённой директивой через `By.directive`
- Запрос возвращает обёртки `DebugElement` вокруг совпадающих элементов
- Каждый `DebugElement` открывает dependency injector с конкретным экземпляром директивы, прикреплённой к этому элементу

Ссылки компонента `App` для проверки выглядят так:

```html
<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>
```

Вот несколько тестов, подтверждающих, что эти ссылки подключены к директивам `routerLink` как ожидается:

```ts
it('can get RouterLinks from template', () => {
  expect(routerLinks.length, 'should have 3 routerLinks').toBe(3);
  expect(routerLinks[0].href).toBe('/dashboard');
  expect(routerLinks[1].href).toBe('/heroes');
  expect(routerLinks[2].href).toBe('/about');
});

it('can click Heroes link in template', async () => {
  const heroesLinkDe = linkDes[1]; // heroes link DebugElement

TestBed.inject(Router).resetConfig([{path: '**', children: []}]);
  heroesLinkDe.triggerEventHandler('click', {button: 0});

await fixture.whenStable();

expect(TestBed.inject(Router).url).toBe('/heroes');
});
```

## Использование объекта `page` {#use-a-page-object}

Компонент `HeroDetail` — простое представление с заголовком, двумя полями героя и двумя кнопками.

Но даже в этой простой форме достаточно сложности шаблона.

```html
@if (hero) {
  <div>
    <h2>
      <span>{{ hero.name | titlecase }}</span> Details
    </h2>
    <div><span>id: </span>{{ hero.id }}</div>
    <div>
      <label for="name">name: </label>
      <input id="name" [(ngModel)]="hero.name" placeholder="name" />
    </div>
    <button type="button" (click)="save()">Save</button>
    <button type="button" (click)="cancel()">Cancel</button>
  </div>
}
```

Тестам, упражняющим компонент, нужно …

- Дождаться появления героя, прежде чем элементы появятся в DOM
- Ссылка на текст заголовка
- Ссылка на поле ввода имени для проверки и установки
- Ссылки на две кнопки, чтобы кликать по ним

Даже такая небольшая форма может породить хаос мучительной условной настройки и CSS-выбора элементов.

Укротите сложность классом `Page`, который обрабатывает доступ к свойствам компонента и инкапсулирует логику их установки.

Вот такой класс `Page` для `hero-detail.component.spec.ts`

```ts
class Page {
  // getter properties wait to query the DOM until called.
  get buttons() {
    return this.queryAll<HTMLButtonElement>('button');
  }
  get saveBtn() {
    return this.buttons[0];
  }
  get cancelBtn() {
    return this.buttons[1];
  }
  get nameDisplay() {
    return this.query<HTMLElement>('span');
  }
  get nameInput() {
    return this.query<HTMLInputElement>('input');
  }

//// query helpers ////
  private query<T>(selector: string): T {
    return harness.routeNativeElement!.querySelector(selector)! as T;
  }

private queryAll<T>(selector: string): T[] {
    return harness.routeNativeElement!.querySelectorAll(selector) as any as T[];
  }
}
```

Теперь важные точки для манипуляции и проверки компонента аккуратно организованы и доступны из экземпляра `Page`.

Метод `createComponent` создаёт объект `page` и заполняет пробелы, как только прибывает `hero`.

```ts
async function createComponent(id: number) {
  harness = await RouterTestingHarness.create();
  component = await harness.navigateByUrl(`/heroes/${id}`, HeroDetail);
  page = new Page();

const request = TestBed.inject(HttpTestingController).expectOne(`api/heroes/?id=${id}`);
  const hero = getTestHeroes().find((h) => h.id === Number(id));
  request.flush(hero ? [hero] : []);
  await harness.fixture.whenStable();
}
```

Вот ещё несколько тестов компонента `HeroDetail`, чтобы закрепить мысль.

```ts
it("should display that hero's name", () => {
  expect(page.nameDisplay.textContent).toBe(expectedHero.name);
});

it('should navigate when click cancel', () => {
  click(page.cancelBtn);
  expect(TestBed.inject(Router).url).toEqual(`/heroes/${expectedHero.id}`);
});

it('should save when click save but not navigate immediately', () => {
  click(page.saveBtn);
  expect(TestBed.inject(HttpTestingController).expectOne({method: 'PUT', url: 'api/heroes'}));
  expect(TestBed.inject(Router).url).toEqual('/heroes/41');
});

it('should navigate when click save and save resolves', async () => {
  click(page.saveBtn);
  await harness.fixture.whenStable();
  expect(TestBed.inject(Router).url).toEqual('/heroes/41');
});

it('should convert hero name to Title Case', async () => {
  // get the name's input and display elements from the DOM
  const hostElement: HTMLElement = harness.routeNativeElement!;
  const nameInput: HTMLInputElement = hostElement.querySelector('input')!;
  const nameDisplay: HTMLElement = hostElement.querySelector('span')!;

// simulate user entering a new name into the input box
  nameInput.value = 'quick BROWN  fOx';

// Dispatch a DOM event so that Angular learns of input value change.
  nameInput.dispatchEvent(new Event('input'));

// Wait for Angular to update the display binding through the title pipe
  await harness.fixture.whenStable();

expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
```

## Переопределение провайдеров компонента {#override-component-providers}

`HeroDetail` предоставляет свой собственный `HeroDetailService`.

```ts
@Component({
  /* ... */
  providers: [HeroDetailService],
})
export class HeroDetail {
  private heroDetailService = inject(HeroDetailService);
  private route = inject(ActivatedRoute);
  private router = inject(Router);
}
```

Невозможно stub'ить `HeroDetailService` компонента в `providers` у `TestBed.configureTestingModule`.
Это провайдеры для _тестового модуля_, а не компонента.
Они готовят dependency injector на _уровне фикстуры_.

Angular создаёт компонент с _собственным_ инжектором, который является _дочерним_ по отношению к инжектору фикстуры.
Он регистрирует провайдеры компонента $в данном случае `HeroDetailService`$ в дочернем инжекторе.

Тест не может получить сервисы дочернего инжектора из инжектора фикстуры.
И `TestBed.configureTestingModule` тоже не может их настроить.

Angular всё это время создавал новые экземпляры реального `HeroDetailService`!

HELPFUL: Эти тесты могут упасть или уйти в timeout, если `HeroDetailService` сам делал XHR-вызовы к удалённому серверу.
Удалённого сервера для вызова может не быть.

К счастью, `HeroDetailService` делегирует ответственность за удалённый доступ к данным внедрённому `HeroService`.

```ts
@Service()
export class HeroDetailService {
  private heroService = inject(HeroService);
}
```

Предыдущая конфигурация тестов заменяет реальный `HeroService` на `TestHeroService`, который перехватывает серверные запросы и подделывает их ответы.

А что, если вам не так повезло.
Что, если подделать `HeroService` сложно?
Что, если `HeroDetailService` сам делает серверные запросы?

Метод `TestBed.overrideComponent` может заменить `providers` компонента на удобные в управлении _тестовые двойники_, как в следующем варианте настройки:

```ts
beforeEach(async () => {
  await TestBed.configureTestingModule({
    providers: [
      provideRouter([
        {path: 'heroes', component: HeroList},
        {path: 'heroes/:id', component: HeroDetail},
      ]),
      // HeroDetailService at this level is IRRELEVANT!
      {provide: HeroDetailService, useValue: {}},
    ],
  }).overrideComponent(HeroDetail, {
    set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
  });
});
```

Обратите внимание: `TestBed.configureTestingModule` больше не предоставляет fake `HeroService`, потому что он [не нужен](#provide-a-spy-stub-herodetailservicespy).

### Метод `overrideComponent` {#the-overridecomponent-method}

Сосредоточьтесь на методе `overrideComponent`.

```ts
.overrideComponent(HeroDetail, {
  set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
});
```

Он принимает два аргумента: тип компонента для переопределения $`HeroDetail`$ и объект переопределения метаданных.
[Объект переопределения метаданных](/guide/testing/utility-apis#testbed-class-summary) — generic, определённый так:

```ts
type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```

Объект переопределения метаданных может либо добавлять-и-удалять элементы в свойствах метаданных, либо полностью сбрасывать эти свойства.
Этот пример сбрасывает метаданные `providers` компонента.

Параметр типа `T` — это вид метаданных, который вы передали бы декоратору `@Component`:

```ts
selector?: string;
template?: string;
templateUrl?: string;
providers?: any[];
…
```

### Предоставление _spy stub_ (`HeroDetailServiceSpy`) {#provide-a-spy-stub-herodetailservicespy}

Этот пример полностью заменяет массив `providers` компонента новым массивом, содержащим `HeroDetailServiceSpy`.

`HeroDetailServiceSpy` — stub-версия реального `HeroDetailService`, которая подделывает все необходимые возможности этого сервиса.
Она не внедряет и не делегирует нижнеуровневому `HeroService`, поэтому тестовый двойник для него не нужен.

Связанные тесты компонента `HeroDetail` будут утверждать, что методы `HeroDetailService` вызывались, шпионя за методами сервиса.
Соответственно, stub реализует свои методы как spies:

```ts
import {vi} from 'vitest';

class HeroDetailServiceSpy {
  testHero: Hero = {...testHero};

/* emit cloned test hero */
  getHero = vi.fn(() => asyncData({...this.testHero}));

/* emit clone of test hero, with changes merged in */
  saveHero = vi.fn((hero: Hero) => asyncData(Object.assign(this.testHero, hero)));
}
```

### Тесты переопределения {#the-override-tests}

Теперь тесты могут напрямую управлять героем компонента, манипулируя `testHero` spy-stub, и подтверждать, что методы сервиса вызывались.

```ts
let hdsSpy: HeroDetailServiceSpy;

beforeEach(async () => {
  harness = await RouterTestingHarness.create();
  component = await harness.navigateByUrl(`/heroes/${testHero.id}`, HeroDetail);
  page = new Page();
  // get the component's injected HeroDetailServiceSpy
  hdsSpy = harness.routeDebugElement!.injector.get(HeroDetailService) as any;

harness.detectChanges();
});

it('should have called `getHero`', () => {
  expect(hdsSpy.getHero, 'getHero called once').toHaveBeenCalledTimes(1);
});

it("should display stub hero's name", () => {
  expect(page.nameDisplay.textContent).toBe(hdsSpy.testHero.name);
});

it('should save stub hero change', async () => {
  const origName = hdsSpy.testHero.name;
  const newName = 'New Name';

page.nameInput.value = newName;

page.nameInput.dispatchEvent(new Event('input')); // tell Angular

expect(component.hero.name, 'component hero has new name').toBe(newName);
  expect(hdsSpy.testHero.name, 'service hero unchanged before save').toBe(origName);

click(page.saveBtn);
  expect(hdsSpy.saveHero, 'saveHero called once').toHaveBeenCalledTimes(1);

await harness.fixture.whenStable();
  expect(hdsSpy.testHero.name, 'service hero has new name after save').toBe(newName);
  expect(TestBed.inject(Router).url).toEqual('/heroes');
});
```

### Дополнительные переопределения {#more-overrides}

Метод `TestBed.overrideComponent` можно вызывать несколько раз для одного или разных компонентов.
`TestBed` предлагает похожие методы `overrideDirective`, `overrideModule` и `overridePipe` для углубления и замены частей этих других классов.

Исследуйте варианты и комбинации самостоятельно.
# Отладка тестов

Если ваши тесты работают не так, как ожидается, вы можете отладить их как в среде Node.js по умолчанию, так и в реальном
браузере.

## Отладка в Node.js {#debugging-in-node-js}

Отладка в среде Node.js по умолчанию часто является самым быстрым способом диагностики проблем, не связанных со
специфичными для браузера API или рендерингом.

1. Запустите команду `ng test` с флагом `--debug`:
   ```shell
ng test --debug
   ```
2. Средство запуска тестов перейдет в режим отладки и будет ожидать подключения отладчика.
3. Теперь вы можете подключить выбранный отладчик. Например, можно использовать встроенный отладчик Node.js в VS Code
   или Chrome DevTools для Node.js.

## Отладка в браузере {#debugging-in-a-browser}

Отладка в браузере рекомендуется для тестов, которые зависят от DOM или других специфичных для браузера API. Этот подход
позволяет использовать собственные инструменты разработчика браузера.

1. Убедитесь, что у вас установлен провайдер браузера. См. инструкции по настройке в
   разделе [Запуск тестов в браузере](guide/testing/migrating-to-vitest#5-configure-browser-mode-optional).
2. Запустите команду `ng test` с флагами `--browsers` и `--debug`:
   ```shell
ng test --browsers=chromium --debug
   ```
3. Эта команда запускает тесты в браузере с графическим интерфейсом и оставляет его открытым после завершения тестов,
   позволяя вам изучить результат.
4. Откройте **Инструменты разработчика** (Developer Tools) браузера. В Windows нажмите `Ctrl-Shift-I`. В macOS нажмите
   `Command-Option-I`.
5. Перейдите на вкладку **Sources**.
6. Используйте `Control/Command-P`, чтобы найти и открыть файл теста.
7. Установите точку останова (breakpoint) в вашем тесте.
8. Перезагрузите интерфейс запуска тестов в браузере. Теперь выполнение остановится на вашей точке останова.
# Утилитарные API тестирования

NOTE: Хотя это руководство обновляется для Vitest, некоторые описания и примеры утилитарных API сейчас представлены в контексте Karma/Jasmine. Мы активно работаем над предоставлением эквивалентов Vitest и обновлённых указаний там, где это применимо.

На этой странице описаны самые полезные возможности тестирования Angular.

Утилиты тестирования Angular включают `TestBed`, `ComponentFixture` и несколько функций, управляющих тестовым окружением.
Классы [`TestBed`](#testbed-class-summary) и [`ComponentFixture`](#the-componentfixture) рассматриваются отдельно.

Вот сводка автономных функций в порядке вероятной полезности:

| Функция      | Подробности                                                                                                                                                                                                                                                      |
| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`inject`]   | Внедряет один или несколько сервисов из текущего инжектора `TestBed` в тестовую функцию. Не может внедрить сервис, предоставленный самим компонентом. См. обсуждение [debugElement.injector](guide/testing/components-scenarios#get-injected-services). |
| `getTestBed` | Получает текущий экземпляр `TestBed`. Обычно не нужно, потому что статических методов класса `TestBed` обычно достаточно. Экземпляр `TestBed` открывает несколько редко используемых членов, недоступных как статические методы.         |

Для обработки сложных асинхронных сценариев или тестирования legacy-приложений на Zone.js см. руководство [Утилиты тестирования Zone.js](guide/testing/zone-js-testing-utilities).

## Сводка класса `TestBed` {#testbed-class-summary}

Класс `TestBed` — одна из главных утилит тестирования Angular.
Его API довольно большой и может быть overwhelming, пока вы не изучите его понемногу.
Сначала прочитайте раннюю часть этого руководства, чтобы освоить основы, прежде чем пытаться поглотить полный API.

Определение модуля, передаваемое в `configureTestingModule`, — подмножество свойств метаданных `@NgModule`.

```ts
type TestModuleMetadata = {
  providers?: any[];
  declarations?: any[];
  imports?: any[];
  schemas?: Array<SchemaMetadata | any[]>;
};
```

Каждый метод override принимает `MetadataOverride<T>`, где `T` — вид метаданных, подходящий методу, то есть параметр `@NgModule`, `@Component`, `@Directive` или `@Pipe`.

```ts
type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```

API `TestBed` состоит из статических методов класса, которые либо обновляют, либо ссылаются на _глобальный_ экземпляр `TestBed`.

Внутренне все статические методы покрывают методы текущего runtime-экземпляра `TestBed`, который также возвращает функция `getTestBed()`.

Вызывайте методы `TestBed` _внутри_ `beforeEach()`, чтобы обеспечить свежий старт перед каждым отдельным тестом.

Вот самые важные статические методы в порядке вероятной полезности.

| Методы                   | Подробности                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `configureTestingModule` | Testing shims устанавливают [начальное тестовое окружение](guide/testing) и модуль тестирования по умолчанию. Модуль тестирования по умолчанию настроен с базовыми declaratives и некоторыми заменителями сервисов Angular, нужными каждому тестировщику. <br /> Вызовите `configureTestingModule`, чтобы уточнить конфигурацию модуля тестирования для конкретного набора тестов, добавляя и удаляя imports, declarations $компонентов, директив и pipes$ и providers.                                                                                               |
| `compileComponents`      | Асинхронно скомпилируйте модуль тестирования после завершения настройки. Вы **должны** вызвать этот метод, если _любой_ из компонентов модуля тестирования имеет асинхронно загружаемые ресурсы (например, блоки @defer). <br /> После вызова `compileComponents` конфигурация `TestBed` замораживается на время текущего spec.                                                                                                                                                                                                                 |
| `createComponent<T>`     | Создайте экземпляр компонента типа `T` на основе текущей конфигурации `TestBed`. После вызова `createComponent` конфигурация `TestBed` замораживается на время текущего spec.                                                                                                                                                                                                                                                                                                                                                 |
| `overrideComponent`      | Замените метаданные для данного класса компонента, который может быть глубоко вложен во внутреннем модуле.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `overrideDirective`      | Замените метаданные для данного класса директивы, который может быть глубоко вложен во внутреннем модуле.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `overridePipe`           | Замените метаданные для данного класса pipe, который может быть глубоко вложен во внутреннем модуле.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `overrideModule`         | Замените метаданные для данного `NgModule`. Помните, что модули могут импортировать другие модули. Метод `overrideModule` может глубоко проникнуть в текущий модуль тестирования, чтобы изменить один из этих внутренних модулей.                                                                                                                                                                                                                                                                                                                                              |
| `inject`                 | Получите сервис из текущего инжектора `TestBed`. Функция `inject` часто достаточна для этой цели. Но `inject` выбрасывает ошибку, если не может предоставить сервис. <br /> Что если сервис опционален? <br /> Метод `TestBed.inject()` принимает опциональный второй параметр — объект для возврата, если Angular не может найти провайдер $`null` в этом примере$: `expect(TestBed.inject(NotProvided, null)).toBeNull();` После вызова `TestBed.inject` конфигурация `TestBed` замораживается на время текущего spec. |
| `initTestEnvironment`    | Инициализируйте тестовое окружение для всего прогона тестов. <br /> Testing shims вызывают его за вас, поэтому редко есть причина вызывать его самостоятельно. <br /> Вызовите этот метод _ровно один раз_. Чтобы изменить это значение по умолчанию в середине прогона тестов, сначала вызовите `resetTestEnvironment`. <br /> Укажите фабрику компилятора Angular, `PlatformRef` и модуль тестирования Angular по умолчанию. Альтернативы для не-браузерных платформ доступны в общем виде `@angular/platform-<platform_name>/testing/<platform_name>`.                   |
| `resetTestEnvironment`   | Сбросьте начальное тестовое окружение, включая модуль тестирования по умолчанию.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

Несколько методов экземпляра `TestBed` не покрыты статическими методами _класса_ `TestBed`.
Они редко нужны.

## `ComponentFixture` {#the-componentfixture}

`TestBed.createComponent<T>` создаёт экземпляр компонента `T` и возвращает строго типизированный `ComponentFixture` для этого компонента.

Свойства и методы `ComponentFixture` предоставляют доступ к компоненту, его DOM-представлению и аспектам его окружения Angular.

### Свойства `ComponentFixture` {#componentfixture-properties}

Вот самые важные свойства для тестировщиков в порядке вероятной полезности.

| Свойства            | Подробности                                                                                                                                                                                                                                                                                   |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentInstance` | Экземпляр класса компонента, созданный `TestBed.createComponent`.                                                                                                                                                                                                                 |
| `debugElement`      | `DebugElement`, связанный с корневым элементом компонента. <br /> `debugElement` даёт понимание компонента и его DOM-элемента во время теста и отладки. Это критическое свойство для тестировщиков. Самые интересные члены рассмотрены [ниже](#debugelement). |
| `nativeElement`     | Нативный DOM-элемент в корне компонента.                                                                                                                                                                                                                                      |
| `changeDetectorRef` | `ChangeDetectorRef` для компонента. <br /> `ChangeDetectorRef` наиболее ценен при тестировании компонента с методом `ChangeDetectionStrategy.OnPush` или когда обнаружение изменений компонента под вашим программным контролем.                                          |

### Методы `ComponentFixture` {#componentfixture-methods}

Методы _fixture_ заставляют Angular выполнять определённые задачи на дереве компонентов.
Вызывайте эти методы, чтобы запустить поведение Angular в ответ на симулированное действие пользователя.

Вот самые полезные методы для тестировщиков.

| Методы              | Подробности                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detectChanges`     | Запустить цикл обнаружения изменений для компонента. <br /> Вызовите его для инициализации компонента $он вызывает `ngOnInit`$ и после того, как тестовый код изменит значения data-bound свойств компонента. Angular не видит, что вы изменили `personComponent.name`, и не обновит привязку `name`, пока вы не вызовете `detectChanges`. <br /> Затем запускает `checkNoChanges`, чтобы подтвердить отсутствие циклических обновлений, если не вызван как `detectChanges(false)`;                                                                                    |
| `autoDetectChanges` | Установите в `true`, когда хотите, чтобы fixture автоматически обнаруживал изменения. <br /> Когда autodetect — `true`, тестовый fixture вызывает `detectChanges` сразу после создания компонента. Затем он слушает соответствующие события zone и вызывает `detectChanges` соответственно. Когда тестовый код напрямую модифицирует значения свойств компонента, вам, вероятно, всё равно нужно вызвать `fixture.detectChanges` для запуска обновлений привязки данных. <br /> По умолчанию `false`. Тестировщики, предпочитающие тонкий контроль над поведением теста, склонны оставлять его `false`. |
| `checkNoChanges`    | Выполнить прогон обнаружения изменений, чтобы убедиться, что нет ожидающих изменений. Выбрасывает исключение, если они есть.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `isStable`          | Если fixture сейчас _stable_, возвращает `true`. Если есть незавершённые async-задачи, возвращает `false`.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `whenStable`        | Возвращает promise, который разрешается, когда fixture stable. <br /> Чтобы возобновить тестирование после завершения асинхронной активности или асинхронного обнаружения изменений, подцепите этот promise. См. [whenStable](guide/testing/components-scenarios#whenstable).                                                                                                                                                                                                                                                                                                   |
| `destroy`           | Запустить уничтожение компонента.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

#### `DebugElement` {#debugelement}

`DebugElement` даёт критически важные insights в DOM-представление компонента.

От `DebugElement` корневого тестового компонента, возвращённого `fixture.debugElement`, можно обходить $и запрашивать$ всё дерево элементов и компонентов fixture.

Вот самые полезные члены `DebugElement` для тестировщиков в приблизительном порядке полезности:

| Члены                 | Подробности                                                                                                                                                                                                                                                                                                                                         |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nativeElement`       | Соответствующий DOM-элемент в браузере                                                                                                                                                                                                                                                                                                    |
| `query`               | Вызов `query(predicate: Predicate<DebugElement>)` возвращает первый `DebugElement`, соответствующий предикату на любой глубине в поддереве.                                                                                                                                                                                                    |
| `queryAll`            | Вызов `queryAll(predicate: Predicate<DebugElement>)` возвращает все `DebugElements`, соответствующие предикату на любой глубине в поддереве.                                                                                                                                                                                                          |
| `injector`            | Host dependency injector. Например, инжектор экземпляра компонента корневого элемента.                                                                                                                                                                                                                                                      |
| `componentInstance`   | Собственный экземпляр компонента элемента, если он есть.                                                                                                                                                                                                                                                                                            |
| `context`             | Объект, предоставляющий родительский контекст для этого элемента. Часто экземпляр компонента-предка, управляющий этим элементом. <br /> Когда элемент повторяется внутри блока `@for`, контекст — `RepeaterContext`, чьё свойство `$implicit` — значение экземпляра строки. Например, `hero` в `@for(hero of heroes; ...)`. |
| `children`            | Непосредственные дочерние `DebugElement`. Обходите дерево, спускаясь через `children`. У `DebugElement` также есть `childNodes` — список объектов `DebugNode`. `DebugElement` происходит от объектов `DebugNode`, и часто узлов больше, чем элементов. Тестировщики обычно могут игнорировать обычные узлы.                                               |
| `parent`              | Родительский `DebugElement`. Null, если это корневой элемент.                                                                                                                                                                                                                                                                                    |
| `name`                | Имя тега элемента, если это элемент.                                                                                                                                                                                                                                                                                                      |
| `triggerEventHandler` | Запускает событие по его имени, если в коллекции `listeners` элемента есть соответствующий слушатель. Второй параметр — _объект события_, ожидаемый обработчиком. <br /> Если у события нет слушателя или есть другая проблема, рассмотрите вызов `nativeElement.dispatchEvent(eventObject)`.                               |
| `listeners`           | Колбэки, прикреплённые к свойствам `@Output` компонента и/или свойствам событий элемента.                                                                                                                                                                                                                                           |
| `providerTokens`      | Токены поиска инжектора этого компонента. Включает сам компонент плюс токены, которые компонент перечисляет в метаданных `providers`.                                                                                                                                                                                                    |
| `source`              | Где найти этот элемент в исходном шаблоне компонента.                                                                                                                                                                                                                                                                                    |
| `references`          | Словарь объектов, связанных с локальными переменными шаблона $например, `#foo`$, с ключами по имени локальной переменной.                                                                                                                                                                                                                       |

Методы `DebugElement.query(predicate)` и `DebugElement.queryAll(predicate)` принимают предикат, который фильтрует поддерево исходного элемента на совпадающие `DebugElement`.

Предикат — любой метод, принимающий `DebugElement` и возвращающий _truthy_ значение.
Следующий пример находит все `DebugElements` со ссылкой на локальную переменную шаблона с именем "content":

```ts
// Filter for DebugElements with a #content reference
const contentRefs = el.queryAll((de) => de.references['content']);
```

Класс Angular `By` имеет три статических метода для распространённых предикатов:

```ts
// Can find DebugElement either by css selector or by directive
const h2 = fixture.debugElement.query(By.css('h2'));
const directive = fixture.debugElement.query(By.directive(Highlight));
```
# Обзор тестовых обвязок компонентов

<strong>Тестовая обвязка компонента</strong> (component harness) — это класс, который позволяет тестам взаимодействовать
с компонентами так же, как это делает конечный пользователь, через поддерживаемый API. Вы можете создавать тестовые
обвязки для любого компонента, от небольших переиспользуемых виджетов до целых страниц.

Обвязки предлагают несколько преимуществ:

- Они делают тесты менее хрупкими, изолируя их от деталей реализации компонента, таких как структура DOM.
- Они делают тесты более читаемыми и простыми в поддержке.
- Их можно использовать в различных средах тестирования.

```typescript
// Пример теста с использованием обвязки для компонента MyButtonComponent
it('should load button with exact text', async () => {
  const button = await loader.getHarness(MyButtonComponentHarness);
  expect(await button.getText()).toBe('Confirm');
});
```
Тестовые обвязки компонентов особенно полезны для общих виджетов пользовательского интерфейса (UI). Разработчики часто
пишут тесты, зависящие от внутренних деталей реализации виджетов, таких как структура DOM и CSS-классы. Эти зависимости
делают тесты хрупкими и сложными в поддержке. Обвязки предлагают альтернативу — поддерживаемый API, который
взаимодействует с виджетом так же, как конечный пользователь. Теперь изменения в реализации виджета с меньшей
вероятностью сломают пользовательские тесты.
Например, [Angular Material](https://material.angular.dev/components/categories) предоставляет тестовую обвязку для
каждого компонента в библиотеке.

Тестовые обвязки компонентов поддерживают несколько сред тестирования. Вы можете использовать одну и ту же реализацию
обвязки как в модульных (unit), так и в сквозных (end-to-end) тестах. Авторам тестов нужно изучить только один API, а
авторам компонентов не нужно поддерживать отдельные реализации для модульных и сквозных тестов.

Многих разработчиков можно отнести к одной из следующих категорий: авторы тестов, авторы тестовых обвязок компонентов и
авторы сред для обвязок. Используйте таблицу ниже, чтобы найти наиболее подходящий раздел в этом руководстве в
зависимости от категории:

| Тип разработчика                    | Описание                                                                                                                                                                                                                                                                                                                      | Соответствующий раздел                                                                                          |
| :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| Авторы тестов                       | Разработчики, которые используют тестовые обвязки компонентов, написанные кем-то другим, для тестирования своего приложения. Например, это может быть разработчик приложения, использующий сторонний компонент меню и которому необходимо взаимодействовать с меню в модульном тесте.                                         | [Использование тестовых обвязок компонентов в тестах](guide/testing/using-component-harnesses)                  |
| Авторы тестовых обвязок компонентов | Разработчики, которые поддерживают переиспользуемые компоненты Angular и хотят создать тестовую обвязку, чтобы пользователи могли использовать её в своих тестах. Например, автор сторонней библиотеки компонентов Angular или разработчик, поддерживающий набор общих компонентов для крупного приложения Angular.           | [Создание тестовых обвязок для ваших компонентов](guide/testing/creating-component-harnesses)                   |
| Авторы сред для обвязок             | Разработчики, желающие добавить поддержку использования тестовых обвязок компонентов в дополнительных средах тестирования. Информацию о средах тестирования, поддерживаемых «из коробки», см. в разделе [среды и загрузчики тестовых обвязок](guide/testing/using-component-harnesses#test-harness-environments-and-loaders). | [Добавление поддержки дополнительных сред тестирования](guide/testing/component-harnesses-testing-environments) |

Полный справочник API см. на странице [API тестовых обвязок компонентов Angular CDK](/api#angular_cdk_testing).
# Использование component harnesses в тестах

## Перед началом {#before-you-start}

TIP: Это руководство предполагает, что вы уже прочитали [обзорное руководство по component harnesses](guide/testing/component-harnesses-overview). Прочитайте его сначала, если вы новичок в использовании component harnesses.

### Установка CDK {#cdk-installation}

[Component Dev Kit (CDK)](https://material.angular.dev/cdk/categories) — набор примитивов поведения для создания компонентов. Чтобы использовать component harnesses, сначала установите `@angular/cdk` из npm. Это можно сделать из терминала с помощью Angular CLI:

```shell
ng add @angular/cdk
```

## Окружения тестовых harnesses и loaders {#test-harness-environments-and-loaders}

Component test harnesses можно использовать в разных тестовых окружениях. Angular CDK поддерживает два встроенных окружения:

- Unit-тесты с Angular `TestBed`
- End-to-end тесты с [WebDriver](https://developer.mozilla.org/en-US/docs/Web/WebDriver)

Каждое окружение предоставляет <strong>harness loader</strong>. Loader создаёт экземпляры harnesses, которые вы используете в тестах. См. ниже более конкретные указания по поддерживаемым тестовым окружениям.

Дополнительные тестовые окружения требуют пользовательских привязок. См. [руководство по добавлению поддержки harnesses для дополнительных тестовых окружений](guide/testing/component-harnesses-testing-environments).

### Использование loader из `TestbedHarnessEnvironment` для unit-тестов {#using-the-loader-from-testbedharnessenvironment-for-unit-tests}

Для unit-тестов можно создать harness loader из [TestbedHarnessEnvironment](/api/cdk/testing/testbed/TestbedHarnessEnvironment). Это окружение использует [component fixture](api/core/testing/ComponentFixture), созданный Angular `TestBed`.

Чтобы создать harness loader, укоренённый в корневом элементе fixture, используйте метод `loader()`:

```ts
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);
```

Чтобы создать harness loader для harnesses элементов, выходящих за пределы fixture, используйте метод `documentRootLoader()`. Например, код, отображающий плавающий элемент или pop-up, часто прикрепляет DOM-элементы напрямую к document body, как сервис `Overlay` в Angular CDK.

Также можно создать harness loader напрямую с `harnessForFixture()` для harness в корневом элементе этого fixture.

### Использование loader из `SeleniumWebDriverHarnessEnvironment` для end-to-end тестов {#using-the-loader-from-seleniumwebdriverharnessenvironment-for-end-to-end-tests}

Для end-to-end тестов на основе WebDriver можно создать harness loader с `SeleniumWebDriverHarnessEnvironment`.

Используйте метод `loader()`, чтобы получить экземпляр harness loader для текущего HTML-документа, укоренённый в корневом элементе документа. Это окружение использует клиент WebDriver.

```ts
let wd: webdriver.WebDriver = getMyWebDriverClient();
const loader = SeleniumWebDriverHarnessEnvironment.loader(wd);
...
const myComponentHarness = await loader.getHarness(MyComponent);
```

## Использование harness loader {#using-a-harness-loader}

Экземпляры harness loader соответствуют конкретному DOM-элементу и используются для создания экземпляров component harness для элементов под этим конкретным элементом.

Чтобы получить `ComponentHarness` для первого экземпляра элемента, используйте метод `getHarness()`. Чтобы получить все экземпляры `ComponentHarness`, используйте метод `getAllHarnesses()`.

```ts
// 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.getAllHarnesses(MyComponent);
```

Помимо `getHarness` и `getAllHarnesses`, у `HarnessLoader` есть несколько других полезных методов для запроса harnesses:

- `getHarnessAtIndex(...)`: получает harness для компонента, соответствующего заданным критериям, по конкретному индексу.
- `countHarnesses(...)`: считает количество экземпляров компонента, соответствующих заданным критериям.
- `hasHarness(...)`: проверяет, есть ли хотя бы один экземпляр компонента, соответствующий заданным критериям.

Как пример, рассмотрим переиспользуемый компонент dialog-button, который открывает диалог по клику. Он содержит следующие компоненты, у каждого со своим harness:

- `MyDialogButton` (компонует `MyButton` и `MyDialog` с удобным API)
- `MyButton` (стандартный компонент кнопки)
- `MyDialog` (диалог, добавляемый к `document.body` через `MyDialogButton` по клику)

Следующий тест загружает harnesses для каждого из этих компонентов:

```ts
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
});
```

### Поведение harnesses в разных окружениях {#harness-behavior-in-different-environments}

Harnesses могут вести себя не совсем одинаково во всех окружениях. Некоторые различия неизбежны между реальным взаимодействием пользователя и симулированными событиями, генерируемыми в unit-тестах. Angular CDK прилагает максимальные усилия для нормализации поведения в возможной степени.

### Взаимодействие с дочерними элементами {#interacting-with-child-elements}

Чтобы взаимодействовать с элементами ниже корневого элемента этого harness loader, используйте экземпляр `HarnessLoader` дочернего элемента. Для первого экземпляра дочернего элемента используйте метод `getChildLoader()`. Для всех экземпляров дочернего элемента используйте метод `getAllChildLoaders()`.

```ts
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');
```

### Фильтрация harnesses {#filtering-harnesses}

Когда страница содержит несколько экземпляров конкретного компонента, может понадобиться фильтровать по некоторому свойству компонента, чтобы получить конкретный экземпляр. Можно использовать <strong>harness predicate</strong> — класс, используемый для ассоциации класса `ComponentHarness` с функциями-предикатами, которые можно использовать для фильтрации экземпляров компонента.

Когда вы запрашиваете harness у `HarnessLoader`, вы фактически предоставляете HarnessQuery. Запрос может быть одним из двух:

- Конструктор harness. Это просто получает этот harness
- `HarnessPredicate`, который получает harnesses, отфильтрованные на основе одного или нескольких условий

`HarnessPredicate` поддерживает некоторые базовые фильтры (selector, ancestor), которые работают на всём, что расширяет `ComponentHarness`.

```ts
// Example of loading a MyButtonComponentHarness with a harness predicate
const disabledButtonPredicate = new HarnessPredicate(MyButtonComponentHarness, {
  selector: '[disabled]',
});
const disabledButton = await loader.getHarness(disabledButtonPredicate);
```

Однако обычно harnesses реализуют статический метод `with()`, который принимает опции фильтрации, специфичные для компонента, и возвращает `HarnessPredicate`.

```ts
// Example of loading a MyButtonComponentHarness with a specific selector
const button = await loader.getHarness(MyButtonComponentHarness.with({selector: 'btn'}));
```

Подробнее см. документацию конкретного harness, поскольку дополнительные опции фильтрации специфичны для каждой реализации harness.

## Использование API тестовых harnesses {#using-test-harness-apis}

Хотя каждый harness определяет API, специфичный для соответствующего компонента, все они разделяют общий базовый класс [ComponentHarness](/api/cdk/testing/ComponentHarness). Этот базовый класс определяет статическое свойство `hostSelector`, которое сопоставляет класс harness с экземплярами компонента в DOM.

Помимо этого, API любого данного harness специфичен для соответствующего компонента; обратитесь к документации компонента, чтобы узнать, как использовать конкретный harness.

Как пример, следующий тест для компонента, использующего [harness компонента slider Angular Material](https://material.angular.dev/components/slider/api#MatSliderHarness):

```ts
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);
});
```

## Совместимость с обнаружением изменений Angular {#interop-with-angular-change-detection}

По умолчанию тестовые harnesses запускают [обнаружение изменений](/best-practices/runtime-performance) Angular перед чтением состояния DOM-элемента и после взаимодействия с DOM-элементом.

Могут быть случаи, когда нужен более тонкий контроль над обнаружением изменений в тестах — например, проверка состояния компонента, пока async-операция ожидается. В этих случаях используйте функцию `manualChangeDetection`, чтобы отключить автоматическую обработку обнаружения изменений для блока кода.

```ts
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);
  });
});
```

Почти все методы harness асинхронны и возвращают `Promise` для поддержки следующего:

- Поддержка unit-тестов
- Поддержка end-to-end тестов
- Изоляция тестов от изменений в асинхронном поведении

Команда Angular рекомендует использовать [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) для улучшения читаемости теста. Вызов `await` блокирует выполнение теста, пока связанный `Promise` не разрешится.

Иногда может понадобиться выполнить несколько действий одновременно и дождаться их завершения, а не выполнять каждое действие последовательно. Например, прочитать несколько свойств одного компонента. В этих ситуациях используйте функцию `parallel` для параллелизации операций. Функция parallel работает аналогично `Promise.all`, одновременно оптимизируя проверки обнаружения изменений.

```ts
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);
});
```
# Создание harnesses для ваших компонентов

## Перед началом {#before-you-start}

### Когда имеет смысл создавать test harness? {#when-does-creating-a-test-harness-make-sense}

Команда Angular рекомендует создавать component test harnesses для shared-компонентов, которые используются во многих местах и имеют некоторую пользовательскую интерактивность. Чаще всего это относится к библиотекам виджетов и похожим переиспользуемым компонентам. Harnesses ценны в этих случаях, потому что они предоставляют потребителям этих shared-компонентов хорошо поддерживаемый API для взаимодействия с компонентом. Тесты, использующие harnesses, могут избежать зависимости от ненадёжных деталей реализации этих shared-компонентов, таких как структура DOM и конкретные event listeners.

Для компонентов, которые появляются только в одном месте, например страницы в приложении, harnesses не дают столько пользы. В этих ситуациях тесты компонента могут разумно зависеть от деталей реализации этого компонента, поскольку тесты и компоненты обновляются одновременно. Однако harnesses всё ещё дают некоторую ценность, если вы будете использовать harness и в unit-, и в end-to-end тестах.

### Установка CDK {#cdk-installation}

[Component Dev Kit (CDK)](https://material.angular.dev/cdk/categories) — это набор примитивов поведения для построения компонентов. Чтобы использовать component harnesses, сначала установите `@angular/cdk` из npm. Это можно сделать из терминала с помощью Angular CLI:

```shell
ng add @angular/cdk
```

## Расширение `ComponentHarness` {#extending-componentharness}

Абстрактный класс `ComponentHarness` — базовый класс для всех component harnesses. Чтобы создать пользовательский component harness, расширьте `ComponentHarness` и реализуйте статическое свойство `hostSelector`.

Свойство `hostSelector` идентифицирует элементы в DOM, которые соответствуют этому подклассу harness. В большинстве случаев `hostSelector` должен совпадать с селектором соответствующего `Component` или `Directive`. Например, рассмотрим простой popup-компонент:

```ts
@Component({
  selector: 'my-popup',
  template: `
    <button (click)="toggle()">{{ triggerText() }}</button>
    @if (isOpen()) {
      <div class="my-popup-content"><ng-content /></div>
    }
  `,
})
class MyPopup {
  triggerText = input('');

isOpen = signal(false);

toggle() {
    this.isOpen.update((value) => !value);
  }
}
```

В этом случае минимальный harness для компонента выглядел бы так:

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';
}
```

Хотя подклассам `ComponentHarness` требуется только свойство `hostSelector`, большинство harnesses также должны реализовывать статический метод `with` для генерации экземпляров `HarnessPredicate`. Раздел [фильтрация harnesses](guide/testing/using-component-harnesses#filtering-harnesses) охватывает это подробнее.

## Поиск элементов в DOM компонента {#finding-elements-in-the-components-dom}

Каждый экземпляр подкласса `ComponentHarness` представляет конкретный экземпляр соответствующего компонента. Вы можете получить доступ к host-элементу компонента через метод `host()` базового класса `ComponentHarness`.

`ComponentHarness` также предлагает несколько методов для поиска элементов внутри DOM компонента. Эти методы — `locatorFor()`, `locatorForOptional()` и `locatorForAll()`. Эти методы создают функции, которые находят элементы; они не находят элементы напрямую. Такой подход защищает от кэширования ссылок на устаревшие элементы. Например, когда блок `@if` скрывает, а затем показывает элемент, результатом является новый DOM-элемент; использование функций гарантирует, что тесты всегда ссылаются на текущее состояние DOM.

См. [страницу API reference ComponentHarness](/api/cdk/testing/ComponentHarness) для полного списка деталей различных методов `locatorFor`.

Например, `MyPopupHarness` из примера выше мог бы предоставить методы для получения элементов trigger и content следующим образом:

```ts
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');
}
```

## Работа с экземплярами `TestElement` {#working-with-testelement-instances}

`TestElement` — это абстракция, разработанная для работы в разных тестовых окружениях (unit-тесты, WebDriver и т.д.). При использовании harnesses все взаимодействие с DOM следует выполнять через этот интерфейс. Другие способы доступа к DOM-элементам, такие как `document.querySelector()`, работают не во всех тестовых окружениях.

У `TestElement` есть ряд методов для взаимодействия с нижележащим DOM, таких как `blur()`, `click()`, `getAttribute()` и другие. См. [страницу API reference TestElement](/api/cdk/testing/TestElement) для полного списка методов.

Не раскрывайте экземпляры `TestElement` пользователям harness, если это не элемент, который потребитель компонента определяет напрямую, например host-элемент компонента. Раскрытие экземпляров `TestElement` для внутренних элементов приводит к тому, что пользователи зависят от внутренней структуры DOM компонента.

Вместо этого предоставляйте более узкоспециализированные методы для конкретных действий, которые может выполнить конечный пользователь, или конкретного состояния, которое он может наблюдать. Например, `MyPopupHarness` из предыдущих разделов мог бы предоставить методы вроде `toggle` и `isOpen`:

```ts
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;
  }
}
```

## Загрузка harnesses для подкомпонентов {#loading-harnesses-for-subcomponents}

Крупные компоненты часто композируют подкомпоненты. Эту структуру можно отразить и в harness компонента. У каждого из методов `locatorFor` на `ComponentHarness` есть альтернативная сигнатура, которую можно использовать для поиска sub-harnesses вместо элементов.

См. [страницу API reference ComponentHarness](/api/cdk/testing/ComponentHarness) для полного списка различных методов locatorFor.

Например, рассмотрим меню, построенное с использованием popup из выше:

```ts
@Directive({
  selector: 'my-menu-item',
})
class MyMenuItem {}

@Component({
  selector: 'my-menu',
  template: `
    <my-popup>
      <ng-content />
    </my-popup>
  `,
})
class MyMenu {
  triggerText = input('');

items = contentChildren(MyMenuItem);
}
```

Harness для `MyMenu` затем может использовать другие harnesses для `MyPopup` и `MyMenuItem`:

```ts
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';
}
```

## Фильтрация экземпляров harness с `HarnessPredicate` {#filtering-harness-instances-with-harnesspredicate}

Когда на странице несколько экземпляров конкретного компонента, может понадобиться фильтровать по некоторому свойству компонента, чтобы получить конкретный экземпляр. Например, может понадобиться кнопка с определённым текстом или меню с определённым ID. Класс `HarnessPredicate` может зафиксировать такие критерии для подкласса `ComponentHarness`. Хотя автор теста может конструировать экземпляры `HarnessPredicate` вручную, проще, когда подкласс `ComponentHarness` предоставляет вспомогательный метод для построения предикатов для распространённых фильтров.

Следует создать статический метод `with()` на каждом подклассе `ComponentHarness`, который возвращает `HarnessPredicate` для этого класса. Это позволяет авторам тестов писать легко понятный код, например `loader.getHarness(MyMenuHarness.with({selector: '#menu1'}))`. В дополнение к стандартным опциям selector и ancestor метод `with` должен добавлять любые другие опции, имеющие смысл для конкретного подкласса.

Harnesses, которым нужно добавить дополнительные опции, должны расширять интерфейс `BaseHarnessFilters` и дополнительные опциональные свойства по необходимости. `HarnessPredicate` предоставляет несколько удобных методов для добавления опций: `stringMatches()`, `addOption()` и `add()`. См. [страницу API HarnessPredicate](/api/cdk/testing/HarnessPredicate) для полного описания.

Например, при работе с меню полезно фильтровать по тексту trigger и фильтровать пункты меню по их тексту:

```ts
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();
  }
}
```

Можно передать `HarnessPredicate` вместо класса `ComponentHarness` в любой из API на `HarnessLoader`, `LocatorFactory` или `ComponentHarness`. Это позволяет авторам тестов легко нацеливаться на конкретный экземпляр компонента при создании экземпляра harness. Это также позволяет автору harness использовать тот же `HarnessPredicate` для включения более мощных API в своём классе harness. Например, рассмотрим метод `getItems` на `MyMenuHarness`, показанный выше. Добавление API фильтрации позволяет пользователям harness искать конкретные пункты меню:

```ts
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();
  }
  ...
}
```

## Создание `HarnessLoader` для элементов, использующих content projection {#creating-harnessloader-for-elements-that-use-content-projection}

Некоторые компоненты проецируют дополнительное содержимое в шаблон компонента. См. [руководство по content projection](guide/components/content-projection) для дополнительной информации.

Добавьте экземпляр `HarnessLoader`, ограниченный элементом, содержащим `<ng-content>`, когда создаёте harness для компонента, использующего content projection. Это позволяет пользователю harness загружать дополнительные harnesses для любых компонентов, переданных как содержимое. У `ComponentHarness` есть несколько методов, которые можно использовать для создания экземпляров HarnessLoader в таких случаях: `harnessLoaderFor()`, `harnessLoaderForOptional()`, `harnessLoaderForAll()`. См. [страницу API reference интерфейса HarnessLoader](/api/cdk/testing/HarnessLoader) для дополнительных деталей.

Например, `MyPopupHarness` из примера выше может расширить `ContentContainerComponentHarness`, чтобы добавить поддержку загрузки harnesses внутри `<ng-content>` компонента.

```ts
class MyPopupHarness extends ContentContainerComponentHarness<string> {
  static hostSelector = 'my-popup';
}
```

## Доступ к элементам вне host-элемента компонента {#accessing-elements-outside-of-the-components-host-element}

Бывают случаи, когда component harness может потребовать доступ к элементам вне host-элемента соответствующего компонента. Например, код, отображающий плавающий элемент или pop-up, часто прикрепляет DOM-элементы напрямую к document body, как сервис `Overlay` в Angular CDK.

В этом случае `ComponentHarness` предоставляет метод, который можно использовать для получения `LocatorFactory` для корневого элемента документа. `LocatorFactory` поддерживает большинство тех же API, что и базовый класс `ComponentHarness`, и затем может использоваться для запросов относительно корневого элемента документа.

Представьте, что компонент `MyPopup` выше использовал CDK overlay для содержимого popup, а не элемент в своём собственном шаблоне. В этом случае `MyPopupHarness` должен был бы получить доступ к элементу content через метод `documentRootLocatorFactory()`, который получает locator factory с корнем в корне документа.

```ts
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');
  }
}
```

## Ожидание асинхронных задач {#waiting-for-asynchronous-tasks}

Методы на `TestElement` автоматически запускают change detection Angular и ждут задач внутри `NgZone`. В большинстве случаев авторам harness не требуется специальных усилий для ожидания асинхронных задач. Однако есть некоторые крайние случаи, когда этого может быть недостаточно.

При некоторых обстоятельствах анимации Angular могут потребовать второго цикла change detection и последующей стабилизации `NgZone`, прежде чем события анимации будут полностью сброшены. В случаях, когда это нужно, `ComponentHarness` предлагает метод `forceStabilize()`, который можно вызвать для второго раунда.

Можно использовать `NgZone.runOutsideAngular()` для планирования задач вне NgZone. Вызовите метод `waitForTasksOutsideAngular()` на соответствующем harness, если нужно явно дождаться задач вне `NgZone`, поскольку это не происходит автоматически.
# Анимация приложений с `animate.enter` и `animate.leave`

Хорошо продуманные анимации делают приложение понятнее и привлекательнее — и это не только косметика.
Анимации улучшают приложение и пользовательский опыт несколькими способами:

- Без анимаций переходы на веб-странице могут казаться резкими и неприятными
- Движение сильно улучшает UX, поэтому анимации дают пользователям шанс заметить реакцию приложения на их действия
- Хорошие анимации плавно направляют внимание пользователя по всему workflow

Angular предоставляет `animate.enter` и `animate.leave` для анимации элементов приложения. Эти две возможности в нужный момент применяют enter- и leave-CSS-классы или вызывают функции для анимаций из сторонних библиотек. `animate.enter` и `animate.leave` — не директивы. Это специальный API, поддерживаемый напрямую компилятором Angular. Их можно использовать прямо на элементах, а также как host binding.

## `animate.enter` {#animateenter}

`animate.enter` позволяет анимировать элементы при их _появлении_ в DOM. Enter-анимации можно задавать CSS-классами с transitions или 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>

Когда анимация завершается, Angular удаляет из DOM класс или классы, указанные в `animate.enter`. Классы анимации присутствуют только пока анимация активна.

NOTE: При нескольких keyframe-анимациях или transition-свойствах на элементе Angular удаляет все классы только _после_ завершения самой длинной анимации.

`animate.enter` можно использовать с любыми другими возможностями Angular — control flow, динамическими выражениями и т.д. `animate.enter` принимает как одну строку классов (несколько классов через пробел), так и массив строк классов.

Кратко о CSS transitions: если вы выбираете transitions вместо keyframe-анимаций, классы, добавленные к элементу через `animate.enter`, представляют состояние, _к которому_ будет анимироваться transition. Базовый CSS элемента — это то, как элемент выглядит без анимаций, что обычно похоже на конечное состояние CSS transition. Поэтому его всё равно нужно сочетать с `@starting-style`, чтобы у transition было корректное состояние _from_.

<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` {#animateleave}

`animate.leave` позволяет анимировать элементы при их _удалении_ из DOM. Leave-анимации можно задавать CSS-классами с transforms или 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>

Когда анимация завершается, Angular автоматически удаляет анимированный элемент из DOM.

NOTE: При нескольких keyframe-анимациях или transition-свойствах на элементе Angular ждёт удаления элемента только _после_ завершения самой длинной из этих анимаций.

`animate.leave` также можно использовать с сигналами и другими привязками. Можно указать один класс или несколько — простой строкой с пробелами или массивом строк.

<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>

### Порядок удаления элементов {#element-removal-order}

В том, как запускаются анимации `animate.leave` и когда анимация произойдёт, есть нюансы. `animate.leave` работает, если размещён на удаляемом элементе; если `animate.leave` размещён на элементе, который является _потомком_ удаляемого, дочерние анимации произойдут _до_ удаления родительского узла из DOM. Так можно уверенно анимировать уход дочерних элементов, не давая родителю исчезнуть раньше времени.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.ts">
    <docs-code header="leave.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.ts" />
    <docs-code header="leave.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.html" />
    <docs-code header="leave.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.css"/>
</docs-code-multifile>

## Привязки событий, функции и сторонние библиотеки {#event-bindings-functions-and-third-party-libraries}

И `animate.enter`, и `animate.leave` поддерживают синтаксис привязки событий с вызовами функций. Так можно вызвать функцию в коде компонента или использовать сторонние библиотеки анимаций — [GSAP](https://gsap.com/), [anime.js](https://animejs.com/) или любую другую 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>

Объект `$event` имеет тип `AnimationCallbackEvent`. Он включает элемент как `target` и предоставляет функцию `animationComplete()`, чтобы уведомить фреймворк о завершении анимации.

IMPORTANT: При использовании `animate.leave` вы **должны** вызвать `animationComplete()`, чтобы Angular удалил элемент.

Если при `animate.leave` не вызвать `animationComplete()`, Angular вызовет функцию автоматически через четыре секунды. Длительность задержки можно настроить, предоставив токен `MAX_ANIMATION_TIMEOUT` в миллисекундах.

```typescript
{ provide: MAX_ANIMATION_TIMEOUT, useValue: 6000 }
```

## Совместимость с устаревшими Angular Animations {#compatibility-with-legacy-angular-animations}

Нельзя использовать legacy-анимации вместе с `animate.enter` и `animate.leave` в одном компоненте. Это приведёт к тому, что enter-классы останутся на элементе или уходящие узлы не будут удалены. В остальном можно использовать и legacy-анимации, и новые `animate.enter` / `animate.leave` в одном _приложении_. Единственная оговорка — проекция контента. Если проецировать контент из компонента с legacy-анимациями в компонент с `animate.enter` или `animate.leave` (или наоборот), поведение будет таким же, как при совместном использовании в одном компоненте. Это не поддерживается.

## Тестирование {#testing}

TestBed предоставляет встроенную поддержку включения и отключения анимаций в тестовом окружении. CSS-анимации требуют браузера, и многие API в тестовом окружении недоступны. По умолчанию TestBed отключает анимации в тестах.

Если нужно проверить, что анимации работают в браузерном тесте (например, end-to-end), можно настроить TestBed на включение анимаций, указав `animationsEnabled: true` в конфигурации теста.

```typescript
TestBed.configureTestingModule({animationsEnabled: true});
```

Это настроит анимации в тестовом окружении на обычное поведение.

NOTE: Некоторые тестовые окружения не эмитят события анимации вроде `animationstart`, `animationend` и их transition-эквиваленты.

## Дополнительно об анимациях Angular {#more-on-angular-animations}

Вас также могут заинтересовать:
# Анимация приложения с CSS

CSS предлагает мощный набор инструментов для создания красивых и вовлекающих анимаций в приложении.

## Как писать анимации на нативном CSS {#how-to-write-animations-in-native-css}

Если вы никогда не писали нативные CSS-анимации, есть ряд отличных руководств для старта. Вот некоторые из них:
[MDN's CSS Animations guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)
[W3Schools CSS3 Animations guide](https://www.w3schools.com/css/css3_animations.asp)
[The Complete CSS Animations Tutorial](https://www.lambdatest.com/blog/css-animations-tutorial/)
[CSS Animation for Beginners](https://thoughtbot.com/blog/css-animation-for-beginners)

и несколько видео:
[Learn CSS Animation in 9 Minutes](https://www.youtube.com/watch?v=z2LQYsZhsFw)
[Net Ninja CSS Animation Tutorial Playlist](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)

Изучите эти руководства и туториалы, затем вернитесь к этому гайду.

## Создание переиспользуемых анимаций {#creating-reusable-animations}

Можно создавать переиспользуемые анимации, которыми можно делиться по всему приложению, используя `@keyframes`. Определите keyframe-анимации в общем CSS-файле — и сможете переиспользовать их где угодно в приложении.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>

Добавление класса `animated-class` к элементу запустит анимацию на этом элементе.

## Анимация перехода {#animating-a-transition}

### Анимация состояния и стилей {#animating-state-and-styles}

Может понадобиться анимировать переход между двумя состояниями — например, когда элемент открыт или закрыт. Это можно сделать через CSS-классы — с keyframe-анимацией или transition-стилями.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-states"/>

Состояние `open` или `closed` включается переключением классов на элементе в компоненте. Примеры — в нашем [руководстве по шаблонам](guide/templates/binding#css-class-and-style-property-bindings).

Похожие примеры — в руководстве по шаблонам для [прямой анимации стилей](guide/templates/binding#css-style-properties).

### Transitions, Timing и Easing {#transitions-timing-and-easing}

Анимация часто требует настройки тайминга, задержек и easing. Это делается через несколько CSS-свойств или shorthand-свойства.

Задайте `animation-duration`, `animation-delay` и `animation-timing-function` для keyframe-анимации в CSS либо используйте shorthand-свойство `animation`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>

Аналогично можно использовать `transition-duration`, `transition-delay` и `transition-timing-function` и shorthand `transition` для анимаций без `@keyframes`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>

### Запуск анимации {#triggering-an-animation}

Анимации запускаются переключением CSS-стилей или классов. Как только класс присутствует на элементе, анимация произойдёт. Удаление класса вернёт элемент к CSS, определённому для него. Пример:

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/open-close.ts">
    <docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.ts" />
    <docs-code header="open-close.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.html" />
    <docs-code header="open-close.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.css"/>
</docs-code-multifile>

## Transition и Triggers {#transition-and-triggers}

### Анимация Auto Height {#animating-auto-height}

Можно использовать CSS Grid для анимации к auto height.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/auto-height.ts">
    <docs-code header="auto-height.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.ts" />
    <docs-code header="auto-height.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.html" />
    <docs-code header="auto-height.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.css"  />
</docs-code-multifile>

Если не нужно поддерживать все браузеры, также посмотрите `calc-size()` — настоящее решение для анимации auto height. Подробнее — в [документации MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/calc-size) и [этом туториале](https://frontendmasters.com/blog/one-of-the-boss-battles-of-css-is-almost-won-transitioning-to-auto/).

### Анимация появления и ухода из view {#animate-entering-and-leaving-a-view}

Можно создавать анимации для появления элемента во view или ухода из view. Начнём с анимации появления. Используем `animate.enter`, который применяет классы анимации, когда элемент входит во view.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/insert.ts">
    <docs-code header="insert.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.ts" />
    <docs-code header="insert.html" path="adev/src/content/examples/animations/src/app/native-css/insert.html" />
    <docs-code header="insert.css" path="adev/src/content/examples/animations/src/app/native-css/insert.css"  />
</docs-code-multifile>

Анимация элемента при уходе из view похожа на анимацию появления. Используйте `animate.leave`, чтобы указать, какие CSS-классы применить, когда элемент покидает view.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/remove.ts">
    <docs-code header="remove.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.ts" />
    <docs-code header="remove.html" path="adev/src/content/examples/animations/src/app/native-css/remove.html" />
    <docs-code header="remove.css" path="adev/src/content/examples/animations/src/app/native-css/remove.css"  />
</docs-code-multifile>

Подробнее о `animate.enter` и `animate.leave` — в [руководстве по Enter и Leave анимациям](guide/animations).

### Анимация increment и decrement {#animating-increment-and-decrement}

Анимация при increment и decrement — распространённый паттерн в приложениях. Вот пример, как этого добиться.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.ts">
    <docs-code header="increment-decrement.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.ts" />
    <docs-code header="increment-decrement.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.html" />
    <docs-code header="increment-decrement.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.css" />
</docs-code-multifile>

### Отключение анимации или всех анимаций {#disabling-an-animation-or-all-animations}

Если нужно отключить указанные анимации, есть несколько вариантов.

1. Создайте кастомный класс, который принудительно задаёт animation и transition в `none`.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

Применение этого класса к элементу предотвращает запуск любой анимации на нём. Можно также ограничить область действия всем DOM или секцией DOM. Однако это предотвращает срабатывание событий анимации. Если вы ждёте события анимации для удаления элемента, это решение не подойдёт. Обходной путь — задать длительности в 1 миллисекунду.

2. Используйте media query [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion), чтобы анимации не воспроизводились для пользователей, предпочитающих меньше анимации.

3. Не добавляйте классы анимации программно

### Callback'и анимации {#animation-callbacks}

Если есть действия, которые нужно выполнить в определённые моменты анимаций, есть ряд доступных событий, на которые можно подписаться. Вот некоторые из них.

[`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)

У Web Animations API много дополнительных возможностей. [Смотрите документацию](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API), чтобы увидеть все доступные animation API.

NOTE: Учитывайте проблемы bubbling с этими callback'ами. Если анимируете детей и родителей, события всплывают от детей к родителям. Рассмотрите остановку propagation или просмотр деталей события, чтобы реагировать на нужный target, а не на событие, всплывшее от дочернего узла. Можно проверить свойство `animationname` или свойства, участвующие в transition, чтобы убедиться, что у вас правильные узлы.

## Сложные последовательности {#complex-sequences}

Анимации часто сложнее простого fade in или fade out. Может быть много сложных последовательностей анимаций. Рассмотрим некоторые из таких сценариев.

### Stagger-анимации в списке {#staggering-animations-in-a-list}

Распространённый эффект — stagger-анимации каждого элемента списка для cascade-эффекта. Это достигается через `animation-delay` или `transition-delay`. Пример того, как может выглядеть такой CSS.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/stagger.ts">
    <docs-code header="stagger.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.ts" />
    <docs-code header="stagger.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.html" />
    <docs-code header="stagger.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.css" />
</docs-code-multifile>

### Параллельные анимации {#parallel-animations}

К элементу можно применить несколько анимаций сразу через shorthand-свойство `animation`. У каждой могут быть свои длительности и задержки. Это позволяет компоновать анимации и создавать сложные эффекты.

```css
.target-element {
  animation:
    rotate 3s,
    fade-in 2s;
}
```

В этом примере анимации `rotate` и `fade-in` запускаются одновременно, но имеют разные длительности.

### Анимация элементов переупорядочиваемого списка {#animating-the-items-of-a-reordering-list}

Элементы в цикле `@for` будут удаляться и добавляться заново, что запустит анимации с `@starting-styles` для entry-анимаций. Альтернативно можно использовать `animate.enter` для того же поведения. Используйте `animate.leave` для анимации элементов при удалении, как в примере ниже.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.ts">
    <docs-code header="reorder.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.ts" />
    <docs-code header="reorder.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.html" />
    <docs-code header="reorder.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.css" />
</docs-code-multifile>

## Программное управление анимациями {#programmatic-control-of-animations}

Анимации с элемента можно получить напрямую через [`Element.getAnimations()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations). Это возвращает массив каждого [`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation) на этом элементе. API `Animation` позволяет делать гораздо больше, чем предлагал `AnimationPlayer` из пакета animations. Отсюда можно `cancel()`, `play()`, `pause()`, `reverse()` и многое другое. Этот нативный API должен предоставить всё необходимое для управления анимациями.

## Дополнительно об анимациях Angular {#more-on-angular-animations}

Вас также могут заинтересовать:
# Анимации переходов между маршрутами

Анимации переходов между маршрутами улучшают пользовательский опыт, обеспечивая плавные визуальные переходы при
навигации между различными представлениями в вашем Angular-приложении. [Angular Router](/guide/routing)
включает встроенную поддержку браузерного API View Transitions, что позволяет создавать бесшовные анимации при смене
маршрутов в поддерживаемых браузерах.

HELPFUL: Нативная интеграция View Transitions в Роутер в настоящее время находится
в [developer preview](/reference/releases#developer-preview). Нативные View Transitions — это относительно новая
возможность браузеров с ограниченной поддержкой.

## Как работают View Transitions {#how-view-transitions-work}

View Transitions используют нативный браузерный [
`document.startViewTransition` API](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) для
создания плавных анимаций между различными состояниями вашего приложения. API работает следующим образом:

1. **Захват текущего состояния** — Браузер делает снимок текущей страницы.
2. **Выполнение обновления DOM** — Запускается ваша функция обратного вызова для обновления DOM.
3. **Захват нового состояния** — Браузер захватывает обновленное состояние страницы.
4. **Воспроизведение перехода** — Браузер анимирует переход между старым и новым состояниями.

Вот базовая структура API `startViewTransition`:

```ts
document.startViewTransition(async () => {
  await updateTheDOMSomehow();
});
```

Для получения более подробной информации о браузерном API
см. [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions).

## Как Роутер использует View Transitions {#how-the-router-uses-view-transitions}

Angular Router интегрирует View Transitions в жизненный цикл навигации для создания бесшовных изменений маршрутов. Во
время навигации Роутер:

1. **Завершает подготовку навигации** — Выполняются сопоставление
   маршрутов, [ленивая загрузка](/guide/routing/loading-strategies#lazily-loaded-components-and-routes), [Guards](/guide/routing/route-guards)
   и [Resolvers](/guide/routing/data-resolvers).
2. **Инициализирует View Transition** — Роутер вызывает `startViewTransition`, когда маршруты готовы к активации.
3. **Обновляет DOM** — Роутер активирует новые маршруты и деактивирует старые внутри колбэка перехода.
4. **Завершает переход** — Promise перехода разрешается, когда Angular завершает рендеринг.

Интеграция View Transitions в Роутер действует
как [прогрессивное улучшение](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement). Если браузеры
не поддерживают API View Transitions, Роутер выполняет обычные обновления DOM без анимации, гарантируя работу вашего
приложения во всех браузерах.

## Включение View Transitions в Роутере {#enabling-view-transitions-in-the-router}

Включите View Transitions, добавив функцию `withViewTransitions` в
вашу [конфигурацию роутера](/guide/routing/define-routes#adding-the-router-to-your-application). Angular поддерживает
как Standalone, так и NgModule подходы к загрузке приложения:

### Загрузка Standalone-приложения {#standalone-bootstrap}

```ts
import {bootstrapApplication} from '@angular/platform-browser';
import {provideRouter, withViewTransitions} from '@angular/router';
import {routes} from './app.routes';

bootstrapApplication(MyApp, {
  providers: [provideRouter(routes, withViewTransitions())],
});
```

### Загрузка с NgModule {#ngmodule-bootstrap}

```ts
import {NgModule} from '@angular/core';
import {RouterModule} from '@angular/router';

@NgModule({
  imports: [RouterModule.forRoot(routes, {enableViewTransitions: true})],
})
export class AppRouting {}
```

[Попробуйте пример "count" на StackBlitz](https://stackblitz.com/edit/stackblitz-starters-2dnvtm?file=src%2Fmain.ts)

Этот пример демонстрирует, как навигация роутера может заменить прямые вызовы `startViewTransition` для обновления
счетчика.

## Настройка переходов с помощью CSS {#customizing-transitions-with-css}

Вы можете настроить View Transitions с помощью CSS для создания уникальных эффектов анимации. Браузер создает отдельные
элементы перехода, к которым можно обращаться с помощью CSS-селекторов.

Чтобы создать пользовательские переходы:

1. **Добавьте view-transition-name** — Назначьте уникальные имена элементам, которые вы хотите анимировать.
2. **Определите глобальные анимации** — Создайте CSS-анимации в ваших глобальных стилях.
3. **Используйте псевдоэлементы перехода** — Используйте селекторы `::view-transition-old()` и
   `::view-transition-new()`.

Вот пример, добавляющий эффект вращения к элементу счетчика:

```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;
}
```

IMPORTANT: Определяйте анимации View Transitions в файле глобальных стилей, а не в стилях
компонента. [Инкапсуляция представления](/guide/components/styling#style-scoping) в Angular изолирует стили
компонента, что не позволяет им корректно воздействовать на псевдоэлементы перехода.

[Попробуйте обновленный пример "count" на StackBlitz](https://stackblitz.com/edit/stackblitz-starters-fwn4i7?file=src%2Fmain.ts)

## Расширенное управление переходами с помощью onViewTransitionCreated {#advanced-transition-control-with-onviewtransitioncreated}

Функция `withViewTransitions` принимает объект опций с колбэком `onViewTransitionCreated` для расширенного управления
переходами. Этот колбэк:

- Выполняется
  в [контексте внедрения зависимостей](/guide/di/dependency-injection-context#run-within-an-injection-context).
- Получает объект [`ViewTransitionInfo`](/api/router/ViewTransitionInfo), содержащий:
  - Экземпляр `ViewTransition` из `startViewTransition`.
  - [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) для маршрута, с которого осуществляется переход.
  - [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) для маршрута, на который осуществляется переход.

Используйте этот колбэк для настройки поведения перехода в зависимости от контекста навигации. Например, вы можете
пропустить переходы для определенных типов навигации:

```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();
    }
  },
});
```

Этот пример пропускает View Transition, когда навигация изменяет
только [фрагмент URL или параметры запроса](/guide/routing/read-route-state#query-parameters) (например, якорные ссылки
на той же странице). Метод `skipTransition()` предотвращает анимацию, но позволяет навигации завершиться.

## Примеры из Chrome Explainer, адаптированные для Angular {#examples-from-the-chrome-explainer-adapted-to-angular}

Следующие примеры демонстрируют различные техники View Transitions, адаптированные из документации команды Chrome для
использования с Angular Router:

### Элементы перехода не обязательно должны быть одним и тем же DOM-элементом {#transitioning-elements-don-t-need-to-be-the-same-dom-element}

Элементы могут плавно переходить между разными DOM-элементами, если у них одинаковое имя `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)
- [Пример Angular на StackBlitz](https://stackblitz.com/edit/stackblitz-starters-dh8npr?file=src%2Fmain.ts)

### Пользовательские анимации входа и выхода {#custom-entry-and-exit-animations}

Создавайте уникальные анимации для элементов, входящих и выходящих из области просмотра во время переходов между
маршрутами.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#custom_entry_and_exit_transitions)
- [Пример Angular на StackBlitz](https://stackblitz.com/edit/stackblitz-starters-8kly3o)

### Асинхронные обновления DOM и ожидание контента {#async-dom-updates-and-waiting-for-content}

Angular Router отдает приоритет немедленным переходам, а не ожиданию загрузки дополнительного контента.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#async_dom_updates_and_waiting_for_content)

NOTE: Angular Router не предоставляет способа задержать View Transitions. Это проектное решение предотвращает потерю
интерактивности страниц во время ожидания дополнительного контента. Как отмечается в документации Chrome: "В это время
страница заморожена, поэтому задержки здесь должны быть сведены к минимуму... в некоторых случаях лучше вообще избегать
задержки и использовать тот контент, который у вас уже есть".

### Обработка нескольких стилей View Transition с помощью типов переходов {#handle-multiple-view-transition-styles-with-view-transition-types}

Используйте типы переходов (view transition types) для применения различных стилей анимации в зависимости от контекста
навигации.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#view-transition-types)
- [Пример Angular на StackBlitz](https://stackblitz.com/edit/stackblitz-starters-vxzcam)

### Обработка нескольких стилей View Transition с помощью имени класса на корне перехода (устарело) {#handle-multiple-view-transition-styles-with-a-class-name-on-the-view-transition-root-deprecated}

Этот подход использует CSS-классы на корневом элементе перехода для управления стилями анимации.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#changing-on-navigation-type)
- [Пример Angular на StackBlitz](https://stackblitz.com/edit/stackblitz-starters-nmnzzg?file=src%2Fmain.ts)

### Переход без заморозки других анимаций {#transitioning-without-freezing-other-animations}

Поддерживайте другие анимации на странице во время View Transitions для создания более динамичного пользовательского
опыта.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning-without-freezing)
- [Пример Angular на StackBlitz](https://stackblitz.com/edit/stackblitz-starters-76kgww)

### Анимация с помощью JavaScript {#animating-with-javascript}

Управляйте View Transitions программно, используя JavaScript API для сложных сценариев анимации.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#animating-with-javascript)
- [Пример Angular на StackBlitz](https://stackblitz.com/edit/stackblitz-starters-cklnkm)
# Миграция с пакета Angular Animations

Пакет `@angular/animations` устарел начиная с v20.2, которая также представила новые возможности `animate.enter` и `animate.leave` для добавления анимаций в приложение. Используя эти новые возможности, можно заменить все анимации на основе `@angular/animations` обычным CSS или JS-библиотеками анимаций. Удаление `@angular/animations` из приложения может значительно уменьшить размер JavaScript-бандла. Нативные CSS-анимации обычно дают лучшую производительность, так как могут использовать аппаратное ускорение. Это руководство проводит через процесс рефакторинга кода с `@angular/animations` на нативные CSS-анимации.

## Как писать анимации на нативном CSS {#how-to-write-animations-in-native-css}

Если вы никогда не писали нативные CSS-анимации, есть ряд отличных руководств для старта. Вот некоторые из них:  
[MDN's CSS Animations guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)  
[W3Schools CSS3 Animations guide](https://www.w3schools.com/css/css3_animations.asp)  
[The Complete CSS Animations Tutorial](https://www.lambdatest.com/blog/css-animations-tutorial/)  
[CSS Animation for Beginners](https://thoughtbot.com/blog/css-animation-for-beginners)

и пара видео:  
[Learn CSS Animation in 9 Minutes](https://www.youtube.com/watch?v=z2LQYsZhsFw)  
[Net Ninja CSS Animation Tutorial Playlist](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)

Ознакомьтесь с этими руководствами и туториалами, затем вернитесь к этому гайду.

## Создание переиспользуемых анимаций {#creating-reusable-animations}

Как и с пакетом animations, можно создавать переиспользуемые анимации, которыми можно делиться по всему приложению. Версия пакета animations требовала использования функции `animation()` в общем typescript-файле. Нативная CSS-версия похожа, но живёт в общем CSS-файле.

#### С пакетом Animations {#with-animations-package}

<docs-code header="animations.ts" path="adev/src/content/examples/animations/src/app/animations.1.ts" region="animation-example"/>

#### С нативным CSS {#with-native-css}

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>

Добавление класса `animated-class` к элементу запускает анимацию на этом элементе.

## Анимация перехода {#animating-a-transition}

### Анимация состояний и стилей {#animating-state-and-styles}

Пакет animations позволял определять различные состояния с помощью функции [`state()`](api/animations/state) внутри компонента. Примеры — состояния `open` или `closed`, содержащие стили для каждого соответствующего состояния в определении. Например:

#### С пакетом Animations {#with-animations-package-1}

<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="state1"/>

То же поведение можно реализовать нативно с помощью CSS-классов — либо с keyframe-анимацией, либо с transition-стилями.

#### С нативным CSS {#with-native-css-1}

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-states"/>

Запуск состояния `open` или `closed` выполняется переключением классов на элементе в компоненте. Примеры того, как это сделать, есть в нашем [руководстве по шаблонам](guide/templates/binding#css-class-and-style-property-bindings).

Похожие примеры есть в руководстве по шаблонам для [прямой анимации стилей](guide/templates/binding#css-style-properties).

### Transitions, timing и easing {#transitions-timing-and-easing}

Функция `animate()` пакета animations позволяет задавать timing — duration, delays и easing. Это можно сделать нативно в CSS с помощью нескольких CSS-свойств или shorthand-свойств.

Укажите `animation-duration`, `animation-delay` и `animation-timing-function` для keyframe-анимации в CSS, либо используйте shorthand-свойство `animation`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>

Аналогично можно использовать `transition-duration`, `transition-delay` и `transition-timing-function` и shorthand `transition` для анимаций, не использующих `@keyframes`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>

### Запуск анимации {#triggering-an-animation}

Пакет animations требовал указывать triggers с помощью функции `trigger()` и вкладывать все состояния внутрь. С нативным CSS это не нужно. Анимации можно запускать переключением CSS-стилей или классов. Как только класс присутствует на элементе, анимация произойдёт. Удаление класса вернёт элемент к тому CSS, который определён для этого элемента. В результате значительно меньше кода для той же анимации. Вот пример:

#### С пакетом Animations {#with-animations-package-2}
#### С нативным CSS {#with-native-css-2}

## Transition и triggers {#transition-and-triggers}

### Предопределённые состояния и wildcard matching {#predefined-state-and-wildcard-matching}

Пакет animations предлагает возможность сопоставлять определённые состояния с transition через строки. Например, анимация из open в closed была бы `open => closed`. Можно использовать wildcards для сопоставления любого состояния с целевым, например `* => closed`, а ключевое слово `void` можно использовать для состояний входа и выхода. Например: `* => void` когда элемент покидает view, или `void => *` когда элемент входит в view.

Эти паттерны сопоставления состояний вообще не нужны при анимации напрямую через CSS. Можно управлять тем, какие transitions и `@keyframes`-анимации применяются, на основе классов и/или стилей, которые вы задаёте на элементах. Также можно добавить `@starting-style`, чтобы контролировать, как элемент выглядит сразу при входе в DOM.

### Автоматический расчёт свойств с wildcards {#automatic-property-calculation-with-wildcards}

Пакет animations предлагает возможность анимировать то, что исторически было сложно анимировать — например, анимацию заданной высоты до `height: auto`. Теперь это можно сделать и на чистом CSS.

#### С пакетом Animations {#with-animations-package-3}
Можно использовать CSS Grid для анимации до auto height.

#### С нативным CSS {#with-native-css-3}

Если не нужно поддерживать все браузеры, также можно посмотреть `calc-size()` — настоящее решение для анимации auto height. См. [документацию MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/calc-size) и [этот туториал](https://frontendmasters.com/blog/one-of-the-boss-battles-of-css-is-almost-won-transitioning-to-auto/) для дополнительной информации.

### Анимация входа и выхода из view {#animate-entering-and-leaving-a-view}

Пакет animations предлагал упомянутое выше сопоставление паттернов для входа и выхода, а также включал shorthand-алиасы `:enter` и `:leave`.

#### С пакетом Animations {#with-animations-package-4}
#### С нативным CSS {#with-native-css-4}

#### С нативным CSS {#with-native-css-5}

Подробнее о `animate.enter` и `animate.leave` см. в [руководстве Enter and Leave animations](guide/animations).

### Анимация increment и decrement {#animating-increment-and-decrement}

Наряду с упомянутыми `:enter` и `:leave` есть также `:increment` и `:decrement`. Их тоже можно анимировать добавлением и удалением классов. В отличие от встроенных алиасов пакета animations, нет автоматического применения классов при увеличении или уменьшении значений. Можно применять соответствующие классы программно. Вот пример:

#### С пакетом Animations {#with-animations-package-5}
#### С нативным CSS {#with-native-css-6}

### Parent / Child анимации {#parent-child-animations}

В отличие от пакета animations, когда в компоненте указано несколько анимаций, ни одна анимация не имеет приоритета над другой и ничто не блокирует запуск любой анимации. Любая последовательность анимаций должна обрабатываться определением вашей CSS-анимации — через animation / transition delay и/или используя `animationend` или `transitionend` для добавления следующего CSS для анимации.

### Отключение анимации или всех анимаций {#disabling-an-animation-or-all-animations}

С нативными CSS-анимациями, если нужно отключить указанные анимации, есть несколько вариантов.

1. Создайте пользовательский класс, который принудительно задаёт animation и transition в `none`.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

Применение этого класса к элементу предотвращает запуск любой анимации на этом элементе. Можно также ограничить область действия всем DOM или секцией DOM, чтобы обеспечить это поведение. Однако это предотвращает срабатывание animation events. Если вы ждёте animation events для удаления элемента, это решение не сработает. Обходной путь — задать duration в 1 миллисекунду.

2. Используйте media query [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion), чтобы гарантировать, что анимации не воспроизводятся для пользователей, предпочитающих меньше анимации.

3. Не добавляйте animation-классы программно

### Callbacks анимаций {#animation-callbacks}

Пакет animations предоставлял callbacks на случай, если нужно что-то сделать, когда анимация завершилась. У нативных CSS-анимаций тоже есть эти callbacks.

Web Animations API имеет много дополнительной функциональности. [Посмотрите документацию](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API), чтобы увидеть все доступные animation API.

NOTE: Учитывайте проблемы bubbling с этими callbacks. Если анимируете детей и родителей, события всплывают от детей к родителям. Рассмотрите остановку propagation или просмотр деталей события, чтобы определить, что вы реагируете на желаемый event target, а не на событие, всплывающее от дочернего узла. Можно проверить свойство `animationname` или свойства, которые transition'ятся, чтобы убедиться, что у вас правильные узлы.

## Сложные последовательности {#complex-sequences}

Пакет animations имеет встроенную функциональность для создания сложных последовательностей. Все эти последовательности полностью возможны и без пакета animations.

### Таргетинг конкретных элементов {#targeting-specific-elements}

В пакете animations можно было таргетировать конкретные элементы с помощью функции `query()`, чтобы находить элементы по имени CSS-класса, аналогично [`document.querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector). В мире нативных CSS-анимаций это не нужно. Вместо этого можно использовать CSS-селекторы для таргетинга подклассов и применять любой желаемый `transform` или `animation`.

Чтобы переключать классы для дочерних узлов в шаблоне, можно использовать class и style bindings для добавления анимаций в нужных точках.

### Stagger() {#stagger}

Функция `stagger()` позволяла задерживать анимацию каждого элемента в списке на указанное время, чтобы создать cascade-эффект. Это поведение можно воспроизвести в нативном CSS, используя `animation-delay` или `transition-delay`. Вот пример того, как может выглядеть такой CSS.

#### С пакетом Animations {#with-animations-package-6}
#### С нативным CSS {#with-native-css-7}

### Параллельные анимации {#parallel-animations}

Пакет animations имеет функцию `group()` для одновременного воспроизведения нескольких анимаций. В CSS у вас полный контроль над timing анимации. Если определено несколько анимаций, можно применить их все сразу.

```css
.target-element {
  animation:
    rotate 3s,
    fade-in 2s;
}
```

В этом примере анимации `rotate` и `fade-in` запускаются одновременно.

### Анимация элементов переупорядочиваемого списка {#animating-the-items-of-a-reordering-list}

Переупорядочивание элементов в списке работает из коробки с помощью ранее описанных техник. Дополнительная специальная работа не требуется. Элементы в цикле `@for` будут корректно удаляться и добавляться заново, что запустит анимации с использованием `@starting-styles` для entry-анимаций. Альтернативно можно использовать `animate.enter` для того же поведения. Используйте `animate.leave` для анимации элементов при удалении, как видно в примере выше.

#### С пакетом Animations {#with-animations-package-7}
#### С нативным CSS {#with-native-css-8}

## Миграция использований AnimationPlayer {#migrating-usages-of-animationplayer}

Класс `AnimationPlayer` позволяет получать доступ к анимации для более продвинутых вещей — pause, play, restart и finish анимации через код. Всё это также можно обработать нативно.

Можно получить анимации с элемента напрямую через [`Element.getAnimations()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations). Это возвращает массив каждого [`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation) на этом элементе. API `Animation` позволяет делать гораздо больше, чем предлагал `AnimationPlayer` из пакета animations. Отсюда можно `cancel()`, `play()`, `pause()`, `reverse()` и многое другое. Этот нативный API должен предоставить всё необходимое для управления анимациями.

## Route Transitions {#route-transitions}

Можно использовать view transitions для анимации между маршрутами. См. [Route Transition Animations Guide](guide/routing/route-transition-animations), чтобы начать.
# Angular без ZoneJS (Zoneless)

## Зачем использовать Zoneless? {#why-use-zoneless}

Основные преимущества отказа от ZoneJS как зависимости:

- **Лучшая производительность**: ZoneJS использует DOM-события и асинхронные задачи как индикаторы того, что состояние приложения _могло_ обновиться, и затем запускает синхронизацию приложения — обнаружение изменений во views. ZoneJS не знает, изменилось ли состояние на самом деле, поэтому синхронизация срабатывает чаще, чем нужно.
- **Улучшение Core Web Vitals**: ZoneJS добавляет заметный overhead — и по размеру payload, и по времени старта.
- **Удобнее отладка**: ZoneJS усложняет отладку. Stack traces с ZoneJS труднее читать. Также сложно понять, когда код ломается из‑за выполнения вне Angular Zone.
- **Лучшая совместимость с экосистемой**: ZoneJS патчит browser API, но не имеет патчей для каждого нового API. Некоторые API, например `async`/`await`, нельзя эффективно пропатчить и приходится downlevel'ить для работы с ZoneJS. Иногда библиотеки несовместимы с тем, как ZoneJS патчит нативные API. Отказ от ZoneJS улучшает долгосрочную совместимость, убирая источник сложности, monkey patching и постоянной поддержки.

## Включение Zoneless в приложении {#enabling-zoneless-in-an-application}

В Angular v21+ zoneless — режим по умолчанию, ничего дополнительно включать не нужно. Убедитесь, что нигде не используется `provideZoneChangeDetection`, переопределяющий конфигурацию по умолчанию.

В Angular v20 включите zoneless change detection, добавив `provideZonelessChangeDetection()` при bootstrap:

```ts
{header: 'standalone bootstrap'}
bootstrapApplication(MyApp, {providers: [provideZonelessChangeDetection()]});
```

```ts
{header: 'NgModule bootstrap'}
platformBrowser().bootstrapModule(AppModule);

@NgModule({
  providers: [provideZonelessChangeDetection()],
})
export class AppModule {}
```

## Удаление ZoneJS {#removing-zonejs}

В zoneless-приложениях ZoneJS следует полностью убрать из сборки, чтобы уменьшить размер бандла. Обычно ZoneJS подключается через опцию `polyfills` в `angular.json` — и в `build`, и в `test`. Удалите `zone.js` и `zone.js/testing` из обоих, чтобы убрать его из сборки. В проектах с явным файлом `polyfills.ts` удалите `import 'zone.js';` и `import 'zone.js/testing';`.

После удаления ZoneJS из сборки зависимость `zone.js` больше не нужна — пакет можно удалить полностью:

```shell
npm uninstall zone.js
```

## Требования совместимости с Zoneless {#requirements-for-zoneless-compatibility}

Angular опирается на уведомления от core API, чтобы понять, когда запускать обнаружение изменений и для каких views.
Эти уведомления включают:

- `ChangeDetectorRef.markForCheck` (вызывается автоматически `AsyncPipe`)
- `ComponentRef.setInput`
- Обновление сигнала, который читается в шаблоне
- Callback'и привязанных host- или template-слушателей
- Присоединение view, помеченного dirty одним из способов выше

### Компоненты, совместимые с `OnPush` {#onpush-compatible-components}

Один из способов убедиться, что компонент использует правильные механизмы уведомлений — использовать [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush).

Стратегия `OnPush` не обязательна, но это рекомендуемый шаг к совместимости с zoneless для компонентов приложения. Для библиотечных компонентов не всегда возможно использовать `ChangeDetectionStrategy.OnPush`.
Если библиотечный компонент — host для пользовательских компонентов, которые могут использовать `ChangeDetectionStrategy.Eager`/`Default`, он не может использовать `OnPush`: это помешало бы обновлению дочернего компонента, если тот не совместим с `OnPush` и полагается на ZoneJS для запуска change detection. Компоненты могут использовать стратегию `Default`, пока уведомляют Angular о необходимости запуска change detection (вызов `markForCheck`, сигналы, `AsyncPipe` и т.д.).
Быть host'ом пользовательского компонента означает использовать API вроде `ViewContainerRef.createComponent`, а не просто размещать часть шаблона пользовательского компонента (то есть проекцию контента или input с template ref).

### Удалите `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, `NgZone.isStable` или `NgZone.onStable` {#remove-ngzoneonmicrotaskempty-ngzoneonunstable-ngzoneisstable-or-ngzoneonstable}

Приложениям и библиотекам нужно убрать использование `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable` и `NgZone.onStable`.
Эти Observable никогда не эмитят, когда в приложении включён zoneless change detection.
Аналогично, `NgZone.isStable` всегда будет `true` и не должен использоваться как условие выполнения кода.

`NgZone.onMicrotaskEmpty` и `NgZone.onStable` чаще всего используют, чтобы дождаться завершения change detection перед задачей. Вместо этого их можно заменить на `afterNextRender`, если нужно дождаться одного цикла change detection, или на `afterEveryRender`, если условие может охватывать несколько раундов. В других случаях эти Observable использовали просто потому, что они знакомы и по таймингу похожи на нужное. Вместо них можно использовать более прямые DOM API, например `MutationObserver`, когда нужно дождаться определённого состояния DOM (а не ждать его косвенно через render hooks Angular).
`NgZone.run` и `NgZone.runOutsideAngular` не нужно удалять для совместимости с Zoneless.
Напротив, удаление этих вызовов может привести к регрессии производительности в библиотеках, которые используются в приложениях, всё ещё зависящих от ZoneJS.
### `PendingTasks` для Server Side Rendering (SSR) {#pendingtasks-for-server-side-rendering-ssr}

Если вы используете SSR с Angular, вы можете знать, что он опирается на ZoneJS, чтобы определить, когда приложение «стабильно» и его можно сериализовать. Если есть асинхронные задачи, которые должны отложить сериализацию, приложение без ZoneJS должно сообщить о них Angular через сервис [PendingTasks](/api/core/PendingTasks). Сериализация дождётся первого момента, когда все pending tasks будут сняты.

Два самых простых способа использовать pending tasks — метод `run`:

```typescript
const taskService = inject(PendingTasks);
taskService.run(async () => {
  const someResult = await doSomeWorkThatNeedsToBeRendered();
  this.someState.set(someResult);
});
```

Для более сложных сценариев можно вручную добавить и снять pending task:

```typescript
const taskService = inject(PendingTasks);
const taskCleanup = taskService.add();
try {
  await doSomeWorkThatNeedsToBeRendered();
} catch {
  // handle error
} finally {
  taskCleanup();
}
```

Кроме того, хелпер [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent#) в `rxjs-interop` гарантирует, что приложение остаётся нестабильным, пока Observable не эмитит, не завершится, не ошибётся или не будет отписан.

```typescript
readonly myObservableState = someObservable.pipe(pendingUntilEvent());
```

Фреймворк также использует этот сервис внутри, чтобы отложить сериализацию до завершения асинхронных задач. В том числе — незавершённая навигация Router и незавершённый запрос `HttpClient`.

### Reactive forms в zoneless-приложениях {#reactive-forms-in-zoneless-applications}

Обновления модели reactive forms (`setValue`, `patchValue`, `FormArray.push` и похожие API) обновляют состояние формы и эмитят form Observables, но автоматически не планируют change detection компонента.

Если шаблон зависит от состояния reactive forms, свяжите Observables форм с уведомлением change detection (например, `ChangeDetectorRef.markForCheck()`) или отразите данные через сигналы, которые потребляет шаблон.

## Тестирование и отладка {#testing-and-debugging}

### Использование Zoneless в `TestBed` {#using-zoneless-in-testbed}

`TestBed` по умолчанию использует Zone-based change detection, когда `zone.js` загружен через `polyfills`.

Если `zone.js` отсутствует, `TestBed` по умолчанию работает в zoneless. Чтобы принудительно включить zoneless при загруженном `zone.js`, добавьте `provideZonelessChangeDetection()`:

```typescript
TestBed.configureTestingModule({
  // Optional: include the provider to force the testing environment
  // uses the same zoneless behavior as a zoneless application.
  providers: [provideZonelessChangeDetection()],
});

const fixture = TestBed.createComponent(MyComponent);
await fixture.whenStable();
```

Чтобы поведение тестов было максимально близко к production, по возможности избегайте `fixture.detectChanges()`. Этот вызов принудительно запускает change detection, когда Angular мог бы его не планировать. Тесты должны убедиться, что уведомления происходят, и позволить Angular самому решать, когда синхронизировать состояние, а не форсировать это вручную.

В существующих наборах тестов `fixture.detectChanges()` — распространённый паттерн, и, скорее всего, не стоит тратить усилия на перевод всех таких мест на `await fixture.whenStable()`. `TestBed` по-прежнему будет требовать совместимость компонента fixture с `OnPush` и выбрасывать `ExpressionChangedAfterItHasBeenCheckedError`, если значения шаблона обновились без уведомления об изменении (например, `fixture.componentInstance.someValue = 'newValue';`).
Если компонент используется в production, проблему нужно решать: перевести состояние на сигналы или вызывать `ChangeDetectorRef.markForCheck()`.
Если компонент — только тестовая обёртка и никогда не используется в приложении, допустимо вызвать `fixture.changeDetectorRef.markForCheck()`.

### Проверка в debug-режиме, что обновления обнаруживаются {#debug-mode-check-to-ensure-updates-are-detected}

Angular также предоставляет дополнительный инструмент, чтобы проверить, что приложение обновляет состояние способом, совместимым с zoneless. `provideCheckNoChangesConfig({exhaustive: true, interval: <milliseconds>})` можно использовать для периодической проверки: нет ли обновлённых привязок без уведомления. Angular выбросит `ExpressionChangedAfterItHasBeenCheckedError`, если есть обновлённая привязка, которую zoneless change detection не обновил бы.
Как open source проект, ежедневные коммиты, PR и динамика Angular полностью отслеживаются на GitHub. Чтобы повысить прозрачность того, как эта ежедневная работа связана с будущим фреймворка, наша дорожная карта объединяет текущее и планируемое видение команды.

Следующие проекты не привязаны к конкретной версии Angular. Мы выпустим их по завершении, и они войдут в конкретную версию на основе нашего расписания релизов, следуя семантическому версионированию. Например, мы выпускаем возможности в следующем minor после завершения или в следующем major, если они включают breaking changes.

Сейчас у Angular три цели для фреймворка:

1. Улучшить [AI-опыт для разработчиков](/ai)
1. Улучшить [опыт разработчика Angular](#improving-the-angular-developer-experience)
1. Улучшить производительность фреймворка

Продолжайте читать, чтобы узнать, как мы планируем достичь этих целей конкретной проектной работой.

## Изучайте современный Angular {#explore-modern-angular}

Начните разработку с новейшими возможностями Angular из нашей дорожной карты. Этот список отражает текущий статус новых возможностей из нашей дорожной карты:

### Доступно для экспериментов {#available-to-experiment-with}

- [Web MCP](/ai/webmcp)

### Готово к production {#production-ready}

- [Signal Forms](/guide/forms/signals/overview)
- [Resource API](/guide/signals/resource)
- [httpResource](/api/common/http/httpResource)
- [Zoneless change detection](/guide/zoneless)
- [Linked Signal API](/guide/signals/linked-signal)
- [Incremental hydration](/guide/incremental-hydration)
- [Effect API](/api/core/effect)
- [Event replay with SSR](/api/platform-browser/withEventReplay)
- [Route-level render mode](/guide/ssr)

## Улучшение AI-опыта для разработчиков Angular {#improving-the-ai-experience-for-angular-developers}

### Лучшее из AI для Angular {#bringing-the-best-of-ai-to-angular}
## Улучшение опыта разработчика Angular {#improving-the-angular-developer-experience}

### Скорость разработчика {#developer-velocity}
### Улучшение инструментов {#improve-tooling}
## Завершённые проекты {#completed-projects}
# Поддержание Angular-проектов в актуальном состоянии

Как и веб в целом и вся экосистема, Angular постоянно развивается.
Angular сочетает непрерывные улучшения с сильным акцентом на стабильность и простоту обновлений.
Актуальная версия Angular-приложения даёт доступ к новейшим возможностям, а также к оптимизациям и исправлениям ошибок.

В этом документе собраны материалы и ресурсы, которые помогут поддерживать Angular-приложения и библиотеки в актуальном состоянии.

О политике версионирования и практиках выпуска — включая поддержку, устаревание и график релизов — см. [Версионирование и релизы Angular](reference/releases 'Angular versioning and releases').

HELPFUL: Если вы используете AngularJS, см. [Переход с AngularJS](https://angular.io/guide/upgrade 'Upgrading from AngularJS').
_AngularJS_ — название всех версий Angular v1.x.

## Уведомления о новых релизах {#getting-notified-of-new-releases}

Чтобы получать уведомления о новых релизах, подпишитесь на [@angular](https://x.com/angular '@angular on X') в X (ранее Twitter) или на [блог Angular](https://blog.angular.dev 'Angular blog').

## Новые возможности {#learning-about-new-features}

Что нового? Что изменилось? Самое важное публикуется в [анонсах релизов](https://blog.angular.dev/ 'Angular blog - release announcements') в блоге Angular.

Полный список изменений по версиям см. в [журнале изменений Angular](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular change log').

## Проверка версии Angular {#checking-your-version-of-angular}

Чтобы узнать версию Angular в приложении, выполните команду `ng version` из каталога проекта.

## Текущая версия Angular {#finding-the-current-version-of-angular}

Последняя стабильная версия Angular указана [на npm](https://www.npmjs.com/package/@angular/core 'Angular on npm') в поле «Version». Например, `16.2.4`.

Текущую версию Angular можно также узнать командой CLI [`ng update`](cli/update).
По умолчанию [`ng update`](cli/update) (без аргументов) показывает доступные обновления.

## Обновление окружения и приложений {#updating-your-environment-and-apps}

Чтобы упростить обновление, мы подготовили пошаговые инструкции в интерактивном [руководстве по обновлению Angular](update-guide).

Руководство по обновлению Angular формирует инструкции с учётом текущей и целевой версий.
В нём есть базовые и продвинутые пути обновления в зависимости от сложности приложения.
Также включены сведения по устранению неполадок и рекомендуемые ручные изменения для максимальной пользы от нового релиза.

Для простых обновлений достаточно команды CLI [`ng update`](cli/update).
Без дополнительных аргументов [`ng update`](cli/update) перечисляет доступные обновления и рекомендуемые шаги для перехода на самую новую версию.

В [Версионировании и релизах Angular](reference/releases#angular-versioning 'Angular Release Practices, Versioning') описано, какого уровня изменений ожидать по номеру версии релиза.
Там же указаны поддерживаемые пути обновления.

## Сводка ресурсов {#resource-summary}

- Анонсы релизов:
  [Блог Angular — анонсы релизов](https://blog.angular.dev/ 'Angular blog announcements about recent releases')

- Подробности релизов:
  [Журнал изменений Angular](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular change log')

- Инструкции по обновлению:
  [Руководство по обновлению Angular](update-guide)

- Справочник команды обновления:
  [Справочник команды Angular CLI `ng update`](cli/update)

- Версионирование, релизы, поддержка и устаревание:
  [Версионирование и релизы Angular](reference/releases 'Angular versioning and releases')
# Безопасность `HttpClient`

`HttpClient` включает встроенную поддержку двух распространенных механизмов безопасности HTTP: защиты от XSSI и защиты
от XSRF/CSRF.

TIP: Также рассмотрите возможность
внедрения [Content Security Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) для
ваших API.

## Защита от XSSI {#xssi-protection}

Cross-Site Script Inclusion (XSSI) — это разновидность
атаки [межсайтового скриптинга (Cross-Site Scripting)](https://en.wikipedia.org/wiki/Cross-site_scripting), при которой
злоумышленник загружает JSON-данные из ваших API-эндпоинтов как `<script>` на подконтрольной ему странице. Затем могут
использоваться различные методы JavaScript для доступа к этим данным.

Распространенным методом предотвращения XSSI является добавление к JSON-ответам "неисполняемого префикса", обычно
`)]}',\n`. Этот префикс предотвращает интерпретацию JSON-ответа как валидного исполняемого JavaScript. Когда API
загружается как данные, префикс может быть удален перед парсингом JSON.

`HttpClient` автоматически удаляет этот префикс XSSI (если он присутствует) при парсинге JSON из ответа.

## Защита от XSRF/CSRF {#xsrf-csrf-protection}

[Межсайтовая подделка запроса (XSRF или CSRF)](https://en.wikipedia.org/wiki/Cross-site_request_forgery) — это техника
атаки, с помощью которой злоумышленник может обманом заставить аутентифицированного пользователя неосознанно выполнить
действия на вашем веб-сайте.

`HttpClient`
поддерживает [распространенный механизм](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Cookie-to-header_token),
используемый для предотвращения XSRF-атак. При выполнении HTTP-запросов Interceptor считывает токен из cookie (по
умолчанию `XSRF-TOKEN`) и устанавливает его в качестве HTTP-заголовка `X-XSRF-TOKEN`. Поскольку только код, запущенный
на вашем домене, может прочитать cookie, бэкенд может быть уверен, что HTTP-запрос пришел из вашего клиентского
приложения, а не от злоумышленника.

По умолчанию Interceptor отправляет этот заголовок во всех изменяющих запросах (таких как `POST`) к относительным URL,
но не в запросах GET/HEAD или запросах с абсолютным URL.
Защита от CSRF необходима только для запросов, которые могут изменить состояние на бэкенде. По своей природе CSRF-атаки пересекают границы доменов, и веб-[политика одинакового источника (same-origin policy)](https://developer.mozilla.org/docs/Web/Security/Same-origin_policy) предотвратит получение атакующей страницей результатов аутентифицированных GET-запросов.
Чтобы воспользоваться этим преимуществом, ваш сервер должен установить токен в сессионную cookie, доступную для
JavaScript, с именем `XSRF-TOKEN` при загрузке страницы или при первом GET-запросе. При последующих запросах сервер
может проверить, совпадает ли cookie с HTTP-заголовком `X-XSRF-TOKEN`, и, следовательно, быть уверенным, что запрос мог
отправить только код, запущенный на вашем домене. Токен должен быть уникальным для каждого пользователя и поддаваться
проверке сервером; это не позволяет клиенту создавать свои собственные токены. Для дополнительной безопасности
установите токен как дайджест аутентификационной cookie вашего сайта с "солью".

Чтобы предотвратить коллизии в средах, где несколько приложений Angular используют один и тот же домен или поддомен,
задайте каждому приложению уникальное имя cookie.
  Ваш бэкенд-сервис должен быть настроен на установку cookie для вашей страницы и проверку наличия заголовка во всех соответствующих запросах. Невыполнение этого требования делает защиту Angular по умолчанию неэффективной.
### Настройка пользовательских имен cookie/заголовков {#configure-custom-cookie-header-names}

Если ваш бэкенд-сервис использует другие имена для cookie или заголовка токена XSRF, используйте `withXsrfConfiguration`
для переопределения значений по умолчанию.

Добавьте его в вызов `provideHttpClient` следующим образом:

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withXsrfConfiguration({
        cookieName: 'CUSTOM_XSRF_TOKEN',
        headerName: 'X-Custom-Xsrf-Header',
      }),
    ),
  ]
};
```

### Отключение защиты XSRF {#disabling-xsrf-protection}

Если встроенный механизм защиты XSRF не подходит для вашего приложения, вы можете отключить его, используя функцию
`withNoXsrfProtection`:

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withNoXsrfProtection(),
    ),
  ]
};
```
# Интернационализация в Angular (i18n)

_Интернационализация_, иногда называемая i18n, — это процесс проектирования и подготовки вашего проекта к использованию
в различных локалях по всему миру.
_Локализация_ — это процесс сборки версий вашего проекта для различных локалей.
Процесс локализации включает следующие действия:

- Извлечение текста для перевода на разные языки
- Форматирование данных для конкретной локали

_Локаль_ определяет регион, в котором люди говорят на определенном языке или варианте языка.
Возможные регионы включают страны и географические области.
Локаль определяет форматирование и парсинг следующих деталей:

- Единицы измерения, включая дату и время, числа и валюты
- Переведенные названия, включая часовые пояса, языки и страны

Для быстрого знакомства с локализацией и интернационализацией посмотрите это видео:

<docs-video src="https://www.youtube.com/embed/KNTN-nsbV7M"/>

## Подробнее об интернационализации в Angular {#learn-about-angular-internationalization}