Google의 전담팀이 관리하는 Angular는 개발 작업을 단순화하고 효율화하는 데 필요한 다양한 도구와 API, 라이브러리를 제공합니다. Angular는 팀 규모와 코드 규모에 따라 확장 가능하고 빠르면서 안정적인 애플리케이션을 구축할 수 있는 견고한 플랫폼입니다. Angular.dev는 Angular 문서의 공식 홈입니다.

Angular 사용방법을 안내합니다.

브라우저에서 단계별로 학습해 보세요.

온라인 환경에서 Angular를 빠르게 시작하거나, 터미널로 로컬 환경을 구성해 보세요. ## 온라인으로 작업하기 프로젝트 세팅 없이 브라우저에서 바로 Angular를 사용해 보려면, 온라인 샌드박스에 접속하면 됩니다: ## 로컬 환경에 프로젝트 환경 설정하기 프로젝트를 새로 만든다면 Git과 같은 도구를 함께 사용하기 위해 로컬 환경에 프로젝트 환경을 설정하는 것을 대부분 선호합니다. ### 환경설정 조건 - **Node.js** - [v22.22.3 이거나 이후 버전](/reference/versions) - **텍스트 에디터** - [Visual Studio Code](https://code.visualstudio.com/)를 추천합니다. - **터미널** - [Angular CLI](/tools/cli) 명령을 실행하기 위해 필요합니다. - **개발 툴** - 개발 워크플로를 향상시키기 위해 [Angular Language Service](/tools/language-service) 사용을 권장합니다. ### 설정방법 로컬 환경에 Angular 프로젝트를 설정하려면 이런 과정을 거치면 됩니다. #### Angular CLI 설치하기 터미널을 열고 다음 명령을 실행합니다. [Visual Studio Code](https://code.visualstudio.com/)를 사용한다면 [integrated terminal](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 docs](/tools/cli/setup-local#install-the-angular-cli)를 참고하세요. #### 프로젝트 생성하기 터미널에서 Angular CLI [`ng new`](cli/new) 명령을 실행하면서 프로젝트 이름을 지정하세요. 이 문서에서는 `my-first-angular-app`라는 프로젝트 이름을 사용하겠습니다. ```shell ng new <프로젝트-이름> ``` 프로젝트를 생성하면서 몇 가지 옵션을 선택하게 됩니다. 화살표 키와 엔터 키를 사용해서 원하는 옵션을 고르면 됩니다. 특별히 선호하는 옵션이 없다면 모든 질문에 엔터 키를 누르고 기본 설정으로 시작해도 됩니다. 모든 옵션을 다 골랐으면 Angular CLI가 환경설정을 시작하고 이런 메시지를 출력합니다: ```shell ✔ Packages installed successfully. Successfully initialized git. ``` 이제 로컬 환경에 프로젝트를 실행할 준비가 끝났습니다! #### 로컬 프로젝트 실행하기 터미널에서 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` 에 접속하면 애플리케이션이 실행되는 것을 확인할 수 있습니다. 코딩 즐겁게 해봅시다! 🎉 ### AI 활용하기 AI 기능이 지원되는 IDE를 활용하려면 [Angular 프롬프트 규칙, 모범사례](/ai/develop-with-ai) 문서를 참고하세요. ## 다음 단계 Angular 프로젝트를 생성했다면 이제 [핵심 가이드](/essentials)로 이동하거나 원하는 주제를 골라서 학습해 보세요! # Angular 코딩 스타일 가이드 ## 소개 이 가이드는 Angular 애플리케이션 코드에 적용할 여러 스타일 규칙을 설명합니다. 이 권장 사항은 Angular가 동작하기 위한 필수 조건이 아니라, Angular 생태계 전반의 일관성을 높이기 위한 코딩 관례입니다. 일관된 관례가 있으면 코드를 공유하고 프로젝트 사이를 이동하기 쉬워집니다. 이 가이드는 Angular와 관련 없는 TypeScript나 일반적인 코딩 관례는 다루지 _않습니다_. TypeScript에 관해서는 [Google TypeScript 스타일 가이드](https://google.github.io/styleguide/tsguide.html)를 확인하세요. ### 판단하기 어렵다면 일관성을 우선하세요 이 규칙이 특정 파일의 스타일과 충돌한다면 해당 파일 내의 일관성을 유지하는 데 우선순위를 두세요. 한 파일 안에 여러 스타일 규칙을 섞는 것은 이 가이드의 권장 사항에서 벗어나는 것보다 혼란을 더 크게 만듭니다. ## 이름 짓기 ### 파일 이름의 단어는 하이픈으로 구분하세요 파일 이름의 단어는 하이픈(`-`)으로 구분하세요. 예를 들어 `UserProfile`이라는 컴포넌트의 파일 이름은 `user-profile.ts`입니다. ### 테스트 파일에는 같은 이름을 사용하고 끝에 `.spec`을 붙이세요 단위 테스트의 파일 이름은 `.spec.ts`로 끝나게 하세요. 예를 들어 `UserProfile` 컴포넌트의 단위 테스트 파일 이름은 `user-profile.spec.ts`입니다. ### 파일 이름은 내부 TypeScript 식별자와 맞추세요 파일 이름은 일반적으로 그 안에 있는 코드의 내용을 설명해야 합니다. 파일에 TypeScript 클래스가 있다면 파일 이름에 클래스 이름을 반영하세요. 예를 들어 `UserProfile` 컴포넌트가 있는 파일의 이름은 `user-profile.ts`입니다. 파일에 이름을 붙일 수 있는 주요 식별자가 여러 개 있다면 코드의 공통 주제를 설명하는 이름을 선택하세요. 파일의 코드가 하나의 공통 주제나 기능 영역에 속하지 않는다면 여러 파일로 나누는 것을 고려하세요. `helpers.ts`, `utils.ts`, `common.ts`처럼 지나치게 포괄적인 파일 이름은 피하세요. ### 컴포넌트의 TypeScript, 템플릿, 스타일 파일은 같은 이름을 사용하세요 컴포넌트는 보통 TypeScript 파일 하나, 템플릿 파일 하나, 스타일 파일 하나로 구성됩니다. 이 파일들은 이름을 같게 하고 확장자만 다르게 해야 합니다. 예를 들어 `UserProfile` 컴포넌트는 `user-profile.ts`, `user-profile.html`, `user-profile.css` 파일로 구성할 수 있습니다. 컴포넌트에 스타일 파일이 여러 개라면 각 파일에 고유한 스타일을 설명하는 단어를 이름에 덧붙이세요. 예를 들어 `UserProfile`에는 `user-profile-settings.css`와 `user-profile-subscription.css` 스타일 파일이 있을 수 있습니다. ## 프로젝트 구조 ### 애플리케이션 코드는 모두 `src` 디렉터리에 두세요 Angular UI 코드(TypeScript, HTML, 스타일)는 모두 `src`라는 디렉터리 안에 두어야 합니다. 설정 파일이나 스크립트처럼 UI와 관련 없는 코드는 `src` 디렉터리 바깥에 두세요. 이렇게 하면 Angular 프로젝트마다 루트 디렉터리의 구성이 일관되고, 프로젝트의 UI 코드와 다른 코드를 명확하게 구분할 수 있습니다. ### `src` 바로 아래의 `main.ts` 파일에서 애플리케이션을 부트스트랩하세요 Angular 애플리케이션을 시작하는, 즉 **부트스트랩**하는 코드는 항상 `main.ts`라는 파일에 두어야 합니다. 이 파일이 애플리케이션의 주요 진입점입니다. ### 밀접하게 관련된 파일은 같은 디렉터리에 모으세요 Angular 컴포넌트는 TypeScript 파일로 구성되며, 템플릿 파일과 하나 이상의 스타일 파일을 선택적으로 포함할 수 있습니다. 이 파일들은 같은 디렉터리에 모아야 합니다. 단위 테스트는 테스트 대상 코드와 같은 디렉터리에 두세요. 서로 관련 없는 테스트를 하나의 `tests` 디렉터리에 모으는 것은 피하세요. ### 프로젝트는 기능 영역별로 구성하세요 애플리케이션의 기능이나 코드의 공통 주제를 기준으로 프로젝트를 하위 디렉터리로 나누세요. 예를 들어 영화관 사이트 MovieReel의 프로젝트 구조는 다음과 같을 수 있습니다: ``` src/ ├─ movie-reel/ │ ├─ show-times/ │ │ ├─ film-calendar/ │ │ ├─ film-details/ │ ├─ reserve-tickets/ │ │ ├─ payment-info/ │ │ ├─ purchase-confirmation/ ``` 디렉터리에 들어가는 코드의 종류를 기준으로 하위 디렉터리를 만들지 마세요. 예를 들어 `components`, `directives`, `services` 같은 디렉터리는 피하세요. 한 디렉터리에 파일을 너무 많이 넣어 읽거나 탐색하기 어려워지지 않도록 하세요. 파일 수가 늘어나면 하위 디렉터리로 더 나누는 것을 고려하세요. ### 파일 하나에는 개념 하나를 담으세요 소스 파일은 하나의 _개념_ 에 집중하는 것이 좋습니다. Angular 클래스에서는 보통 파일마다 컴포넌트, 디렉티브, 서비스 중 하나를 두는 것을 뜻합니다. 다만 클래스가 비교적 작고 하나의 개념으로 긴밀히 연결된다면 한 파일에 여러 컴포넌트나 디렉티브를 두어도 괜찮습니다. 판단하기 어렵다면 파일이 더 작아지는 방식을 선택하세요. ## 의존성 주입 ### 생성자 매개변수 주입보다 `inject` 함수를 사용하세요 생성자 매개변수로 주입하는 것보다 [`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). ## 컴포넌트와 디렉티브 ### 컴포넌트 셀렉터 선택하기 [컴포넌트 가이드의 셀렉터 선택하기](guide/components/selectors#choosing-a-selector)를 참고하세요. ### 컴포넌트와 디렉티브 멤버의 이름 짓기 컴포넌트 가이드의 [입력 프로퍼티 이름 짓기](guide/components/inputs#choosing-input-names)와 [출력 프로퍼티 이름 짓기](guide/components/outputs#choosing-event-names)를 참고하세요. ### 디렉티브 셀렉터 선택하기 디렉티브는 컴포넌트와 같은 [애플리케이션 고유의 접두사](guide/components/selectors#selector-prefixes)를 사용해야 합니다. 디렉티브에 어트리뷰트 셀렉터를 사용한다면 어트리뷰트 이름에 카멜 표기법을 사용하세요. 예를 들어 애플리케이션 이름이 "MovieReel"이고 요소에 툴팁을 추가하는 디렉티브를 만든다면 `[mrTooltip]` 셀렉터를 사용할 수 있습니다. ### Angular 고유의 프로퍼티는 메서드 앞에 모으세요 컴포넌트와 디렉티브의 Angular 고유 프로퍼티는 보통 클래스 선언의 윗부분에 모아두어야 합니다. 주입한 의존성, 입력, 출력, 쿼리가 여기에 해당합니다. 이러한 프로퍼티와 다른 프로퍼티는 클래스 메서드보다 앞에 정의하세요. 이렇게 하면 클래스의 템플릿 API와 의존성을 쉽게 찾을 수 있습니다. ### 컴포넌트와 디렉티브는 화면 표현에 집중하도록 하세요 컴포넌트와 디렉티브 내부의 코드는 대체로 페이지에 표시되는 UI와 관련되어야 합니다. UI와 분리해도 독립적으로 의미가 있는 코드는 다른 파일로 옮기는 것이 좋습니다. 예를 들어 폼 유효성 검사 규칙이나 데이터 변환을 별도의 함수나 클래스로 분리할 수 있습니다. ### 템플릿에 지나치게 복잡한 로직을 넣지 마세요 Angular 템플릿은 [JavaScript와 유사한 표현식](guide/templates/expression-syntax)을 사용할 수 있도록 설계되었습니다. 비교적 간단한 로직은 이러한 템플릿 표현식에 직접 작성하면 됩니다. 하지만 템플릿 코드가 너무 복잡해지면 로직을 TypeScript 코드로 옮기세요(보통 [computed](guide/signals#computed-signals)를 사용합니다). 어느 정도가 "복잡한지"를 정하는 절대적인 기준은 없습니다. 상황에 맞게 판단하세요. ### 컴포넌트 템플릿에서만 사용하는 클래스 멤버에는 `protected`를 사용하세요 컴포넌트 클래스의 공개 멤버는 의존성 주입과 [쿼리](guide/components/queries)로 접근할 수 있는 공개 API를 구성합니다. 컴포넌트 템플릿에서 읽는 용도의 멤버에는 `protected` 접근 제한자를 사용하는 것이 좋습니다. ```ts @Component({ ..., template: `

`, }) export class UserProfile { firstName = input(); lastName = input(); // `fullName`은 컴포넌트의 공개 API가 아니며 템플릿에서 사용합니다. protected fullName = computed(() => `${this.firstName()} ${this.lastName()}`); } ``` ### 변경하면 안 되는 프로퍼티에는 `readonly`를 사용하세요 Angular가 초기화하는 컴포넌트와 디렉티브 프로퍼티는 `readonly`로 표시하세요. `input`, `model`, `output`, 쿼리로 초기화하는 프로퍼티가 여기에 해당합니다. readonly 접근 제한자는 Angular가 설정한 값을 덮어쓰지 못하도록 합니다. ```ts @Component(/* ... */) export class UserProfile { readonly userId = input(); readonly userSaved = output(); readonly userName = model(); } ``` 데코레이터 기반의 `@Input`, `@Output`, 쿼리 API를 사용하는 컴포넌트와 디렉티브에서는 이 지침이 출력 프로퍼티와 쿼리에 적용되지만 입력 프로퍼티에는 적용되지 않습니다. ```ts @Component(/* ... */) export class UserProfile { @Output() readonly userSaved = new EventEmitter(); @ViewChildren(PaymentMethod) readonly paymentMethods?: QueryList; } ``` ### `ngClass`와 `ngStyle`보다 `class`와 `style`을 사용하세요 [`NgClass`](/api/common/NgClass)와 [`NgStyle`](/api/common/NgStyle) 디렉티브보다 `class`와 `style` 바인딩을 사용하는 것이 좋습니다. ```html {prefer}

``` ```html {avoid}

``` `class`와 `style` 바인딩은 모두 표준 HTML 어트리뷰트에 가까운 간단한 문법을 사용합니다. 특히 기본 HTML에 익숙한 개발자가 템플릿을 읽고 이해하기 쉽습니다. 또한 `NgClass`와 `NgStyle` 디렉티브는 내장된 `class`, `style` 바인딩 문법보다 추가 성능 비용이 발생합니다. 자세한 내용은 [바인딩 가이드](/guide/templates/binding#css-class-and-style-property-bindings)를 참고하세요. ### 이벤트 핸들러의 이름은 이벤트가 아니라 _수행하는 동작_ 을 나타내도록 지으세요 이벤트 핸들러의 이름은 실행을 유발한 이벤트보다 수행하는 동작을 나타내도록 짓는 것이 좋습니다: ```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();
      }
      // ...
    }
  }
}
```

### 라이프사이클 메서드는 간단하게 유지하세요

<!--
Avoid putting long or complex logic inside lifecycle hooks like `ngOnInit`. Instead, prefer creating
well-named methods to contain that logic and then _call those methods_ in your lifecycle hooks.
Lifecycle hook names describe _when_ they run, meaning that the code inside doesn't have a
meaningful name that describes what the code inside is doing.

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

`ngOnInit` 같은 라이프사이클 후킹 메서드에 길고 복잡한 로직을 넣지 마세요.
대신 로직을 설명하는 이름의 메서드를 만들고 라이프사이클 후킹 메서드에서 _그 메서드를 호출_ 하는 것이 좋습니다.
라이프사이클 후킹 메서드의 이름은 _언제_ 실행되는지를 나타내므로, 내부 코드가 어떤 일을 하는지 설명하는 의미 있는 이름이 되지는 못합니다.

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

```ts
{avoid}
ngOnInit() {
  this.logger.setMode('info');
  this.logger.monitorErrors();
  // ...그리고 이 메서드들에서 펼쳐 쓴 나머지 코드가 이어집니다.
}
```

### 라이프사이클 후킹 인터페이스를 사용하세요

<!--
Angular provides a TypeScript interface for each lifecycle method. When adding a lifecycle hook to
your class, import and `implement` these interfaces to ensure that the methods are named correctly.

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

@Component(/* ... */)
export class UserProfile implements OnInit {
  // The `OnInit` interface ensures this method is named correctly.
  ngOnInit() {
    /* ... */
  }
}
```
-->

Angular는 각 라이프사이클 메서드에 해당하는 TypeScript 인터페이스를 제공합니다.
클래스에 라이프사이클 후킹 메서드를 추가할 때는 해당 인터페이스를 가져와 `implement`하여 메서드 이름이 올바른지 확인하세요.

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

@Component(/* ... */)
export class UserProfile implements OnInit {
  // `OnInit` 인터페이스는 이 메서드의 이름이 올바른지 확인합니다.
  ngOnInit() {
    /* ... */
  }
}
```
<!--

-->

컴포넌트(Component)는 Angular 애플리케이션을 구성하는 기본 단위이며, 거대한 웹 페이지의 일부분을 구성합니다.
컴포넌트는 특정 기능을 담당하도록 구분되어 있기 때문에, 컴포넌트를 모아서 만든 애플리케이션은 시간이 지나 규모가 커져도 관리하기 쉽습니다.

## 컴포넌트 정의하기

<!--
Every component has a few main parts:

1. A `@Component` [decorator](https://www.typescriptlang.org/docs/handbook/decorators.html) that contains some configuration used by Angular.
2. An HTML template that controls what renders into the DOM.
3. A [CSS selector](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors) that defines how the component is used in HTML.
4. A TypeScript class with behaviors, such as handling user input or making requests to a server.

Here is a simplified example of a `UserProfile` component.

```typescript
{header: "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 */
}
```

The `@Component` decorator also optionally accepts a `styles` property for any CSS you want to apply to your template:

```typescript
{header: "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 */
}
```

-->

컴포넌트를 구성하는 요소들은 이렇습니다:

1. `@Component`[데코레이터](https://www.typescriptlang.org/docs/handbook/decorators.html) - Angular가 인식할 수 있는 설정값을 지정합니다.
2. HTML 템플릿 - 렌더러가 DOM으로 렌더링하는 HTML입니다.
3. [CSS 셀렉터](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors) - 컴포넌트를 HTML 문서에 사용하기 위해 지정하는 구분자입니다.
4. TypeScript 클래스 - 사용자의 입력값을 처리하거나 서버로 요청을 보내는 등 컴포넌트의 동작을 정의합니다.

간단하게 만든 `UserProfile` 컴포넌트를 확인해 봅시다.

`@Component` 데코레이터에는 템플릿에 CSS 스타일을 지정하기 위해 `styles` 프로퍼티를 추가할 수 있습니다:

### HTML과 CSS를 개별 파일로 분리하기

<!--
You can define a component's HTML and CSS in separate files using `templateUrl` and `styleUrl`:

```typescript
{header: "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
{header: "user-profile.html"}
<h1>User profile</h1>
<p>This is the user profile page</p>
```

```css
{header: "user-profile.css"}
h1 {
  font-size: 3em;
}
```
-->

컴포넌트의 HTML과 CSS를 개별 파일로 정의하고 `templateUrl`과 `styleUrl`로 연결할 수도 있습니다:

```html
{header: "user-profile.html"}
<h1>User profile</h1>
<p>This is the user profile page</p>
```

```css
{header: "user-profile.css"}
h1 {
  font-size: 3em;
}
```

## 컴포넌트 사용하기

Angular 애플리케이션은 여러 컴포넌트를 조합해서 만듭니다.
사용자 프로필 화면을 예로 들면, 이렇게 구현하는 식입니다:

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

<!--
Here, the `UserProfile` component uses several other components to produce the final page.

To import and use a component, you need to:

1. In your component's TypeScript file, add an `import` statement for the component you want to use.
2. In your `@Component` decorator, add an entry to the `imports` array for the component you want to use.
3. In your component's template, add an element that matches the selector of the component you want to use.

Here's an example of a `UserProfile` component importing a `ProfilePhoto` component:

```typescript
{header: "user-profile.ts"}
import {Component} from '@angular/core';
import {ProfilePhoto} from './profile-photo';

@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: Want to know more about Angular components? See the [In-depth Components guide](guide/components) for the full details.
-->

여기에서 `UserProfile` 컴포넌트는 화면을 구성하기 위해 다른 컴포넌트들을 활용합니다.

컴포넌트를 불러와서 사용하려면:

1. 컴포넌트 TypeScript 파일에 `import` 구문을 추가하고 사용하려는 컴포넌트를 불러옵니다.
2. `@Component` 데코레이터에 `imports` 배열을 추가하고 사용하려는 컴포넌트를 이 배열에 추가합니다.
3. 컴포넌트 템플릿에 사용하려는 컴포넌트 셀렉터를 엘리먼트로 추가합니다.

그래서 `UserProfile` 컴포넌트 안에 `ProfilePhoto` 컴포넌트를 사용하려면 이렇게 구현하면 됩니다:

```typescript
{header: "user-profile.ts"}
import {Component} from '@angular/core';
import {ProfilePhoto} from './profile-photo';

팁: Angular 컴포넌트를 자세하게 알아보고 싶은가요? 그러면 [컴포넌트 심화 가이드](guide/components) 문서를 참고하세요.

## 다음 단계

Angular에서 컴포넌트가 어떤 역할을 하는지 알아봤습니다.
이제 동적 데이터를 다루는 방법을 알아봅시다.

# 컴포넌트 셀렉터

<!--
TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular.

Every component defines
a [CSS selector](https://developer.mozilla.org/docs/Web/CSS/CSS_selectors) that determines how
the component is used:

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

You use a component by creating a matching HTML element in the templates of _other_ components:

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

**Angular matches selectors statically at compile-time**. Changing the DOM at run-time, either via
Angular bindings or with DOM APIs, does not affect the components rendered.

**An element can match exactly one component selector.** If multiple component selectors match a
single element, Angular reports an error.

**Component selectors are case-sensitive.**
-->

팁: 이 가이드 문서는 [핵심 가이드](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는 컴파일 타임에 셀렉터를 정적으로 매칭합니다.**
그래서 실행 시점에 Angular 바인딩 문법이나 DOM API로 DOM이 변경되는 것은 컴포넌트 렌더링에 영향을 미치지 않습니다.

**엘리먼트는 하나의 컴포넌트 셀렉터에만 매칭됩니다.**
한 엘리먼트에 컴포넌트 셀렉터가 여러 개 매칭되면 오류가 발생합니다.

**컴포넌트 셀렉터는 대소문자를 구분합니다.**

## 셀렉터의 종류

<!--
Angular supports a limited subset
of [basic CSS selector types](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) in
component selectors:

| **Selector type**  | **Description**                                                                                                 | **Examples**                  |
| ------------------ | --------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| Type selector      | Matches elements based on their HTML tag name, or node name.                                                    | `profile-photo`               |
| Attribute selector | Matches elements based on the presence of an HTML attribute and, optionally, an exact value for that attribute. | `[dropzone]` `[type="reset"]` |
| Class selector     | Matches elements based on the presence of a CSS class.                                                          | `.menu-item`                  |

For attribute values, Angular supports matching an exact attribute value with the equals (`=`)
operator. Angular does not support other attribute value operators.

Angular component selectors do not support combinators, including
the [descendant combinator](https://developer.mozilla.org/docs/Web/CSS/Descendant_combinator)
or [child combinator](https://developer.mozilla.org/docs/Web/CSS/Child_combinator).

Angular component selectors do not support
specifying [namespaces](https://developer.mozilla.org/docs/Web/SVG/Namespaces_Crash_Course).
-->

Angular는 [기본 CSS 셀렉터 타입](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors)의 하위 집합으로만 컴포넌트 셀렉터를 지원합니다:

| **셀렉터 종류**   | **설명**                                                        | **예**                        |
| ----------------- | --------------------------------------------------------------- | ----------------------------- |
| 타입 셀렉터       | HTML 태그 이름이나 노드 이름과 매칭됩니다.                      | `profile-photo`               |
| 어트리뷰트 셀렉터 | 엘리먼트에 지정된 어트리뷰트나 특정 어트리뷰트 값과 매칭됩니다. | `[dropzone]` `[type="reset"]` |
| 클래스 셀렉터     | CSS 클래스와 매칭됩니다.                                        | `.menu-item`                  |

어트리뷰트 값이 지정되면 Angular는 등호(`=`) 연산자를 사용해서 어트리뷰트 값을 비교합니다.
다른 연산자는 지원하지 않습니다.

Angular 컴포넌트 셀렉터는 [자손 결합자(descendant combinator)](https://developer.mozilla.org/docs/Web/CSS/Descendant_combinator)나 [자식 결합자(child combinator)](https://developer.mozilla.org/docs/Web/CSS/Child_combinator) 등 결합 선택자를 지원하지 않습니다.

Angular 컴포넌트 셀렉터는 [네임스페이스](https://developer.mozilla.org/docs/Web/SVG/Namespaces_Crash_Course)를 지원하지 않습니다.

### `:not` 가상 클래스

<!--
Angular supports [the `:not` pseudo-class](https://developer.mozilla.org/docs/Web/CSS/:not).
You can append this pseudo-class to any other selector to narrow which elements a component's
selector matches. For example, you could define a `[dropzone]` attribute selector and prevent
matching `textarea` elements:

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

Angular does not support any other pseudo-classes or pseudo-elements in component selectors.
-->

Angular는 [`:not` 가상 클래스](https://developer.mozilla.org/docs/Web/CSS/:not)를 지원합니다.

이 가상 클래스를 사용하면 컴포넌트 셀렉터가 매칭되는 엘리먼트 범위를 좁힐 수 있습니다.
`[dropzone]` 어트리뷰트 셀렉터를 사용하지만 `textarea` 엘리먼트에는 매칭하지 않는다고 합시다:

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

`:not` 외 가상 클래스는 지원하지 않습니다.

### 셀렉터 조합하기

<!--
You can combine multiple selectors by concatenating them. For example, you can match `<button>`
elements that specify `type="reset"`:

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

You can also define multiple selectors with a comma-separated list:

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

Angular creates a component for each element that matches _any_ of the selectors in the list.
-->

셀렉터는 여러 개를 조합해서 지정할 수도 있습니다.
`type="reset"` 어트리뷰트가 지정된 `<button>` 엘리먼트를 매칭하려면 이렇게 지정하면 됩니다:

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

쉼표(`,`)로 구분하면 셀렉터를 여러 개 지정할 수도 있습니다:

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

셀렉터를 여러 개 지정하면 셀렉터 중 _어느 하나에_ 매칭되는 엘리먼트마다 컴포넌트를 생성합니다.

## 셀렉터 정하기

<!--
The vast majority of components should use a custom element name as their selector. All custom
element names should include a hyphen as described
by [the HTML specification](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name).
By default, Angular reports an error if it encounters a custom tag name that does not match any
available components, preventing bugs due to mistyped component names.

See [Advanced component configuration](guide/components/advanced-configuration) for details on
using [native custom elements](https://developer.mozilla.org/docs/Web/Web_Components) in
Angular templates.
-->

컴포넌트는 대부분 커스텀 엘리먼트 이름으로 셀렉터를 지정합니다.
따라서 [HTML 스펙](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name)에서 정하는 커스텀 엘리먼트 규칙에 따라 하이픈(`-`)을 최소한 하나 포함해야 합니다.
Angular는 어떠한 컴포넌트와도 매칭되지 않는 커스텀 태그를 확인하면 버그와 오타를 방지하기 위해 오류를 발생시킵니다.

Angular 템플릿에서 [네이티브 커스텀 엘리먼트](https://developer.mozilla.org/docs/Web/Web_Components) 활용방법을 자세하게 알아보려면 [심화 컴포넌트 설정](guide/components/advanced-configuration) 문서를 참고하세요.

### 셀렉터 접두사

<!--
The Angular team recommends using a short, consistent prefix for all the custom components
defined inside your project. For example, if you were to build YouTube with Angular, you might
prefix your components with `yt-`, with components like `yt-menu`, `yt-player`, etc. Namespacing
your selectors like this makes it immediately clear where a particular component comes from. By
default, the Angular CLI uses `app-`.

IMPORTANT: Angular uses the `ng` selector prefix for its own framework APIs. Never use `ng` as a selector prefix for your own custom components.
-->

Angular 팀은 프로젝트에 정의된 모든 커스텀 컴포넌트에 짧고 일관된 접두사 사용을 권장합니다.
예를 들어 Angular로 YouTube를 만든다면 `yt-` 접두사를 사용해서 컴포넌트를 `yt-menu`, `yt-player` 와 같이 만드는 식입니다.
셀렉터의 접두사를 네임스페이스처럼 사용하면 컴포넌트가 어떤 라이브러리에서 왔는지 쉽게 구분할 수 있습니다.
Angular CLI로 생성한 프로젝트의 기본 접두사는 `app-` 입니다.

중요: Angular 프레임워크 자체 API의 셀렉터 접두사는 `ng` 입니다.
그래서 커스텀 컴포넌트에 `ng` 접두사를 사용하면 안 됩니다.

### 어트리뷰트 셀렉터는 언제 사용해야 할까요?

<!--
You should consider an attribute selector when you want to create a component on a standard native
element. For example, if you want to create a custom button component, you can take advantage of the
standard `<button>` element by using an attribute selector:

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

This approach allows consumers of the component to directly use all the element's standard APIs
without extra work. This is especially valuable for ARIA attributes such as `aria-label`.

Angular does not report errors when it encounters custom attributes that don't match an available
component. When using components with attribute selectors, consumers may forget to import the
component or its NgModule, resulting in the component not rendering.
See [Importing and using components](guide/components#imports-in-the-component-decorator) for more information.

Components that define attribute selectors should use lowercase, dash-case attributes. You can
follow the same prefixing recommendation described above.
-->

표준 네이티브 엘리먼트에 컴포넌트를 적용하려면 어트리뷰트 셀렉터 사용을 고려해야 합니다.
표준 `<button>` 엘리먼트에 추가 기능을 구현하려는 경우는 다음과 같이 어트리뷰트 셀렉터를 사용하면 됩니다:

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

이렇게 구현하면 추가 작업 없이 기존에 존재하는 엘리먼트에 커스텀 컴포넌트를 적용할 수 있습니다.
이 방식은 `aria-label`과 같이 ARIA 어트리뷰트를 지정하는 경우에 특히 유용합니다.

그런데 커스텀 어트리뷰트 셀렉터는 매칭되는 컴포넌트가 없더라도 Angular가 오류를 발생시키지 않습니다.
그래서 어트리뷰트 셀렉터를 사용할 때는 컴포넌트나 컴포넌트가 등록된 NgModule을 로드하는 것을 깜빡해서 컴포넌트가 렌더링되지 않을 수 있습니다.
자세한 내용은 [컴포넌트 사용하기](guide/components#imports-in-the-component-decorator) 문서를 참고하세요.

컴포넌트 셀렉터를 어트리뷰트 셀렉터로 사용한다면, 소문자(lowercase)나 대시-케이스(dash-case)로 지정해야 합니다.
접두사를 사용하는 방식은 위에서 설명한 방식을 따르면 됩니다.

# 컴포넌트 스타일

<!--
TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular.

Components can optionally include CSS styles that apply to that component's 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 {}
```

You can also choose to write your styles in separate files:

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

When Angular compiles your component, these styles are emitted with your component's JavaScript
output. This means that component styles participate in the JavaScript module system. When you
render an Angular component, the framework automatically includes its associated styles, even when
lazy-loading a component.

Angular works with any tool that outputs CSS,
including [Sass](https://sass-lang.com), [Less](https://lesscss.org),
and [Stylus](https://stylus-lang.com).
-->

팁: 이 가이드 문서는 [핵심 가이드](essentials) 이후 내용을 다룹니다. 아직 Angular에 익숙하지 않다면 해당 문서를 먼저 읽어보세요.

컴포넌트는 CSS 스타일을 지정할 수 있습니다:

그리고 스타일 파일이 별도 파일로 존재한다면 이렇게 지정합니다:

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

Angular가 컴포넌트를 컴파일하면 컴포넌트에 지정된 스타일은 컴포넌트 JavaScript 결과물에 포함됩니다.
이 말은, 컴포넌트 스타일이 JavaScript 모듈 시스템 안에 포함된다는 것을 의미합니다.
이후에 Angular가 컴포넌트를 렌더링하면, 지연 로딩되는 컴포넌트라고 해도 컴포넌트가 로딩될 때 스타일도 함께 로딩됩니다.

CSS 스타일을 지정할 때는 [Sass](https://sass-lang.com)나 [less](https://lesscss.org), [stylus](https://stylus-lang.com) 문법을 사용할 수도 있습니다.

## 스타일 지정 범위

<!--
Every component has a **view encapsulation** setting that determines how the framework scopes a
component's styles. There are four view encapsulation modes: `Emulated`, `ShadowDom`, `ExperimentalIsolatedShadowDom`, and `None`.
You can specify the mode in the `@Component` decorator:

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

컴포넌트에는 컴포넌트 스타일의 범위를 지정하는 **뷰 캡슐화(view encapsulation)** 설정을 지정할 수 있습니다.
뷰 캡슐화 모드는 `Emulated`, `ShadowDom`, `ExperimentalIsolatedShadowDom`, `None` 네 가지입니다.
`@Component` 데코레이터에 이렇게 지정하면 됩니다:

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

### ViewEncapsulation.Emulated

<!--
By default, Angular uses emulated encapsulation so that a component's styles only apply to elements
defined in that component's template. In this mode, the framework generates a unique HTML attribute
for each component instance, adds that attribute to elements in the component's template, and
inserts that attribute into the CSS selectors defined in your component's styles.

This mode ensures that a component's styles do not leak out and affect other components. However,
global styles defined outside of a component may still affect elements inside a component with
emulated encapsulation.

In emulated mode, Angular supports
the [`:host`](https://developer.mozilla.org/docs/Web/CSS/:host) pseudo-class.
While the [`:host-context()`](https://developer.mozilla.org/docs/Web/CSS/:host-context) pseudo-class
is deprecated in modern browsers, Angular's compiler provides full support for it. Both pseudo-classes
can be used without relying on native
[Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM).
During compilation, the framework transforms these pseudo classes into attributes so it doesn't
comply with these native pseudo classes' rules at runtime (e.g. browser compatibility, specificity). Angular's
emulated encapsulation mode does not support any other pseudo classes related to Shadow DOM, such
as `::shadow` or `::part`.
-->

기본적으로 Angular는 에뮬레이션된 뷰 캡슐화 정책을 사용하기 때문에 컴포넌트의 스타일은 컴포넌트 템플릿에 있는 엘리먼트에만 적용됩니다.
Angular는 이 모드에서 컴포넌트 인스턴스마다 고유한 HTML 어트리뷰트를 생성해서 컴포넌트 템플릿의 엘리먼트에 추가하고, 컴포넌트 스타일에도 해당 어트리뷰트를 추가합니다.

이 모드를 사용하면 한 컴포넌트의 스타일이 다른 컴포넌트에 영향을 주지 않습니다.
하지만 컴포넌트 밖에 지정된 전역 스타일은 컴포넌트에도 적용됩니다.

에뮬레이션 모드에서 Angular는 [Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM)을 사용하지 않고 [`:host`](https://developer.mozilla.org/docs/Web/CSS/:host)와 [`:host-context()`](https://developer.mozilla.org/docs/Web/CSS/:host-context) 가상 클래스를 지원합니다.
이런 가상 클래스들은 컴파일 과정에서 어트리뷰트로 변경되어 실행 시점에 네이티브 가상 클래스와 충돌하지 않도록 변환됩니다.
Angular의 에뮬레이션 모드는 `::shadow`나 `::part`와 같은 Shadow DOM 가상 클래스는 지원하지 않습니다.

#### `::ng-deep`

<!--
Angular's emulated encapsulation mode supports a custom pseudo class, `::ng-deep`.
**The Angular team strongly discourages new use of `::ng-deep`**. These APIs remain
exclusively for backwards compatibility.

When a selector contains `::ng-deep`, Angular stops applying view-encapsulation boundaries after that point in the selector. Any part of the selector that follows `::ng-deep` can match elements outside the component’s template.

For example:

- a CSS rule selector like `p a`, using the emulated encapsulation, will match `<a>` elements that are descendants of a `<p>` element,
  both being within the component's own template.

- A selector like `::ng-deep p a` will match `<a>` elements anywhere in the application, descendants of a `<p>` element anywhere in the application.

That effectively makes it behave like a global style.

- In `p ::ng-deep a`, Angular requires the `<p>` element to come from the component's own template, but the `<a>` element may be anywhere in the application.

So, in effect, the `<a>` element may be in the component's template, or in any of its projected or child content.

- With `:host ::ng-deep p a`, both the `<a>` and `<p>` elements must be descendants of the component's host element.

They can come from the component's template or the views of its child components, but not elsewhere in the app.
-->

Angular는 캡슐화를 에뮬레이션하는 가상 클래스, `::ng-deep`을 지원합니다.
**하지만 Angular 팀은 `::ng-deep` 사용을 강하게 비권장합니다.**
이 API는 하위 호환성을 위해 남아있는 것입니다.

`::ng-deep` 셀렉터를 사용하면 이 셀렉터 뒷부분은 Angular의 뷰 캡슐화가 적용되지 않습니다.
그래서 `::ng-deep` 이후에 오는 선택자의 모든 부분은 컴포넌트 템플릿 밖의 범위에도 매칭될 수 있습니다.

예를 들면:

- `p a`라는 CSS 셀렉터를 사용하면, 컴포넌트 템플릿에 존재하는 `<p>` 엘리먼트의 자식 `<a>` 엘리먼트와 매칭됩니다.

- `::ng-deep p a`를 사용하면 애플리케이션 전체 범위에 있는 `<p>` 엘리먼트의 자식 `<a>` 엘리먼트와 매칭됩니다. 사실상 전역 스타일을 지정한 것과 같습니다.

- `p ::ng-deep a`를 사용하면 컴포넌트 템플릿의 `<p>` 엘리먼트 안에 있는 `<a>` 엘리먼트를 매칭해야 하지만, 사실상 애플리케이션 전체 범위의 `<a>` 엘리먼트와 매칭됩니다.

즉, 컴포넌트 템플릿에 있는 `<a>` 엘리먼트와 컴포넌트에 프로젝션된 자식 컨텐츠에도 적용될 수 있습니다.

- `:host ::ng-deep p a`를 사용하면 컴포넌트 호스트 엘리먼트의 자식 `<a>`와 `<p>` 엘리먼트와 매칭됩니다.

이 엘리먼트 매칭은 컴포넌트 템플릿에 존재하거나, 자식 컴포넌트에는 적용되지만 컴포넌트 밖 범위에는 적용되지 않습니다.

### ViewEncapsulation.ShadowDom

<!--
This mode scopes styles within a component by
using [the web standard Shadow DOM API](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM).
When enabling this mode, Angular attaches a shadow root to the component's host element and renders
the component's template and styles into the corresponding shadow tree.

Styles inside the shadow tree cannot affect elements outside of that shadow tree.

Enabling `ShadowDom` encapsulation, however, impacts more than style scoping. Rendering the
component in a shadow tree affects event propagation, interaction
with [the `<slot>` API](https://developer.mozilla.org/docs/Web/Web_Components/Using_templates_and_slots),
and how browser developer tools show elements. Always understand the full implications of using
Shadow DOM in your application before enabling this option.
-->

이 모드를 사용하면 [웹 표준 Shadow DOM API](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM)를 사용해서 컴포넌트 스타일을 컴포넌트에만 적용합니다.
이 모드에서는 Angular가 컴포넌트의 호스트 엘리먼트에 Shadow DOM을 붙이고 컴포넌트 템플릿을 해당 Shadow DOM에 렌더링하면서 스타일을 적용합니다.

Shadow DOM 트리 안의 스타일은 트리 밖에 있는 엘리먼트에 영향을 주지 않습니다.

하지만 `ShadowDom` 뷰 캡슐화를 사용하면 스타일 적용 범위 외에 다른 영향을 줍니다.
Shadow DOM 트리에 렌더링된 컴포넌트는 이벤트 전파 방식에 영향을 미치며, [`<slot>` API](https://developer.mozilla.org/docs/Web/Web_Components/Using_templates_and_slots)를 사용해야 하고, 브라우저 개발자 도구가 엘리먼트를 표시하는 방식도 변경됩니다.
Shadow DOM을 사용할 때는 이 옵션이 어떤 영향을 주는지 정확하게 이해한 후에 사용해야 합니다.

### ViewEncapsulation.ExperimentalIsolatedShadowDom

위와 동일하게 동작하지만, 이 모드는 해당 컴포넌트 템플릿에만 적용되도록 엄격하게 보장됩니다.
전역 스타일은 섀도우 DOM 트리에 영향을 미치지 않으며, 섀도우 DOM 안에 적용된 스타일은 섀도우 DOM 밖에 영향을 미치지 않습니다.

### ViewEncapsulation.None

<!--
This mode disables all style encapsulation for the component. Any styles associated with the
component behave as global styles.

NOTE: In `Emulated` and `ShadowDom` modes, Angular doesn't 100% guarantee that your component's styles will always override styles coming from outside it.
It is assumed that these styles have the same specificity as your component's styles in case of collision.
-->

이 모드를 사용하면 컴포넌트의 뷰 캡슐화를 적용하지 않습니다.
컴포넌트 스타일은 모두 전역 스타일이 됩니다.

참고: `Emulated`나 `ShadowDom` 모드를 사용할 때 컴포넌트 외부에서 지정한 스타일을 컴포넌트 내부에서 오버라이드할 수 있다고 보장하지는 않습니다.
CSS 지정의 구체도가 같다면 컴포넌트 스타일 지정이 충돌할 수 있습니다.

## 템플릿에서 스타일 지정하기 {#defining-styles-in-templates}

<!--
You can use the `<style>` element in a component's template to define additional styles. The
component's view encapsulation mode applies to styles defined this way.

Angular does not support bindings inside of style elements.
-->

컴포넌트 템플릿에서 직접 스타일을 지정하려면 `<style>` 엘리먼트를 사용하면 됩니다.
이 경우에도 컴포넌트의 뷰 캡슐화 정책이 적용됩니다.

Angular는 스타일 엘리먼트 내부에는 바인딩 문법을 지원하지 않습니다.

## 외부 스타일 파일 참조하기 {#referencing-external-style-files}

컴포넌트 템플릿에서 외부 CSS 파일을 참조하기 위해 [`<link>` 엘리먼트](https://developer.mozilla.org/docs/Web/HTML/Element/link)를 사용할 수 있습니다.
그리고 CSS 스타일 안에서 [`@import`](https://developer.mozilla.org/docs/Web/CSS/@import)를 사용해서 외부 CSS 파일을 참조할 수도 있습니다.
Angular는 이런 참조 방식을 컴포넌트 _외부_ 스타일로 간주합니다.
컴포넌트 외부 스타일은 에뮬레이션 뷰 캡슐화의 영향을 받지 않습니다.

<!--
## Namespacing CSS custom properties

Angular can add a prefix to the CSS custom properties (also called CSS variables) that your
component styles declare and read. Custom properties inherit down the DOM tree, so when something
outside your application defines a custom property such as `--primary-color` on an ancestor
element, your components read that value. This matters when your application shares a page with another
application or with markup you do not control. Angular does not namespace custom properties until
you ask it to, and an application that owns its page does not need namespacing.

To scope the custom properties in your component styles to your application, add
[`provideCssVarNamespacing`](api/platform-browser/provideCssVarNamespacing) to your application's
providers. It uses the application's [`APP_ID`](api/core/APP_ID) as the namespace:

```ts
{header: "app.config.ts"}
import {APP_ID, ApplicationConfig} from '@angular/core';
import {provideCssVarNamespacing} from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [{provide: APP_ID, useValue: 'my-app'}, provideCssVarNamespacing()],
};
```

Angular prefixes the custom properties in your component styles with that namespace followed by an
underscore, so `--primary-color` becomes `--my-app_primary-color`. The prefix applies to
declarations, `var()` references, `@property` rules, and style bindings such as
`[style.--primary-color]`, including the style bindings a component declares in its `host` object.

`APP_ID` is `ng` unless you set it, so give each application on the page its own `APP_ID`.
Otherwise, the applications share a prefix and collide again. To use a namespace that differs from
the application id, pass it to `provideCssVarNamespacing`. Angular appends the underscore itself:
`provideCssVarNamespacing('my-app_')` produces `--my-app__primary-color`.

Angular namespaces the styles it compiles into a component: the `styles` and `styleUrl` of the
component, the styles you [write in a `<style>` element](#defining-styles-in-templates) in its
template, stylesheets its template references with a relative `<link rel="stylesheet">`, and
the styles of a component that uses `ViewEncapsulation.None`. Angular does not namespace a stylesheet the browser
loads at runtime, such as a global stylesheet your build configuration lists or an
[external style](#referencing-external-style-files) that your build does not inline.

Namespacing applies to every component Angular compiles, including the components of the libraries
you install. When a library's styles read a custom property that a global stylesheet defines, such
as the properties of a theme, the reference no longer matches, the browser uses the `var()`
fallback if there is one or otherwise
[the property's inherited or initial value](https://www.w3.org/TR/css-variables-1/#invalid-variables),
and nothing reports an error. Before you enable namespacing in an
existing application, review the custom properties that cross between your global stylesheets and
your components.

IMPORTANT: Angular rewrites custom property names only in the styles and bindings it compiles.
Everywhere else keeps the name you write, and nothing reports the mismatch.

Angular does not rewrite the name in:

- Static style attributes, such as `style="--primary-color: red"`, including the `style` entry of a
  component's `host` object.
- Object and string style bindings, such as `[style]="{'--primary-color': color}"`,
  `[style]="'--primary-color: red'"` and `ngStyle`, including the `[style]` entry of a component's
  `host` object.
- Custom property names inside a binding's value, such as
  `[style.border-color]="'var(--primary-color)'"`.
- Calls to `Renderer2.setStyle`.

Each of these produces a property that your namespaced styles no longer read. Namespace those
names yourself, as described in
[Using namespaced properties in TypeScript](#using-namespaced-properties-in-typescript).
-->

## CSS 커스텀 프로퍼티에 네임스페이스 적용하기 {#namespacing-css-custom-properties}

Angular는 컴포넌트 스타일에서 선언하고 읽는 CSS 커스텀 프로퍼티(CSS 변수)에 접두사를 추가할 수 있습니다.
커스텀 프로퍼티는 DOM 트리를 따라 아래로 상속됩니다. 따라서 애플리케이션 외부에서 상위 엘리먼트에 `--primary-color` 같은 커스텀 프로퍼티를 정의하면 컴포넌트가 그 값을 읽게 됩니다.
다른 애플리케이션이나 직접 제어하지 않는 마크업과 페이지를 공유할 때는 이 점이 중요합니다.
Angular는 명시적으로 설정하기 전까지 커스텀 프로퍼티에 네임스페이스를 적용하지 않으며, 페이지 전체를 사용하는 애플리케이션에는 네임스페이스가 필요하지 않습니다.

컴포넌트 스타일의 커스텀 프로퍼티 범위를 애플리케이션으로 한정하려면 애플리케이션의 프로바이더에 [`provideCssVarNamespacing`](api/platform-browser/provideCssVarNamespacing)을 추가하세요.
애플리케이션의 [`APP_ID`](api/core/APP_ID)를 네임스페이스로 사용합니다.

```ts
{header: "app.config.ts"}
import {APP_ID, ApplicationConfig} from '@angular/core';
import {provideCssVarNamespacing} from '@angular/platform-browser';

export const appConfig: ApplicationConfig = {
  providers: [{provide: APP_ID, useValue: 'my-app'}, provideCssVarNamespacing()],
};
```

Angular는 컴포넌트 스타일의 커스텀 프로퍼티 앞에 네임스페이스와 밑줄을 붙입니다. 따라서 `--primary-color`는 `--my-app_primary-color`가 됩니다.
이 접두사는 선언, `var()` 참조, `@property` 규칙, `[style.--primary-color]` 같은 스타일 바인딩에 적용되며, 컴포넌트의 `host` 객체에 선언한 스타일 바인딩도 포함합니다.

`APP_ID`를 설정하지 않으면 기본값은 `ng`입니다. 페이지의 각 애플리케이션에 서로 다른 `APP_ID`를 지정하세요.
그렇지 않으면 애플리케이션들이 같은 접두사를 사용해서 다시 충돌합니다.
애플리케이션 ID와 다른 네임스페이스를 사용하려면 `provideCssVarNamespacing`에 원하는 값을 전달하세요.
Angular가 밑줄을 직접 추가하므로 `provideCssVarNamespacing('my-app_')`는 `--my-app__primary-color`를 만듭니다.

Angular는 컴포넌트로 컴파일하는 스타일에 네임스페이스를 적용합니다.
컴포넌트의 `styles`와 `styleUrl`, 템플릿의 [`<style>` 엘리먼트에 작성한 스타일](#defining-styles-in-templates), 템플릿에서 상대 경로의 `<link rel="stylesheet">`로 참조하는 스타일시트, `ViewEncapsulation.None`을 사용하는 컴포넌트의 스타일이 여기에 해당합니다.
빌드 설정에 나열한 전역 스타일시트나 빌드할 때 인라인으로 포함하지 않는 [외부 스타일](#referencing-external-style-files)처럼 브라우저가 런타임에 로드하는 스타일시트에는 네임스페이스를 적용하지 않습니다.

네임스페이스는 설치한 라이브러리의 컴포넌트를 포함해서 Angular가 컴파일하는 모든 컴포넌트에 적용됩니다.
라이브러리 스타일이 테마 프로퍼티처럼 전역 스타일시트에 정의한 커스텀 프로퍼티를 읽는다면 참조하는 이름이 더 이상 일치하지 않게 됩니다.
이때 브라우저는 `var()`에 대체값이 있으면 그 값을 사용하고, 없으면 [프로퍼티의 상속값이나 초기값](https://www.w3.org/TR/css-variables-1/#invalid-variables)을 사용하며 오류를 보고하지 않습니다.
기존 애플리케이션에서 네임스페이스를 활성화하기 전에 전역 스타일시트와 컴포넌트 사이에서 공유하는 커스텀 프로퍼티를 확인하세요.

중요: Angular는 직접 컴파일하는 스타일과 바인딩에서만 커스텀 프로퍼티의 이름을 변경합니다.
그 밖의 위치에서는 작성한 이름을 그대로 유지하며, 이름이 일치하지 않아도 오류를 보고하지 않습니다.

다음 위치에서는 이름을 변경하지 않습니다.

- `style="--primary-color: red"` 같은 정적 스타일 어트리뷰트. 컴포넌트의 `host` 객체에 있는 `style` 항목도 포함합니다.
- `[style]="{'--primary-color': color}"`, `[style]="'--primary-color: red'"`, `ngStyle` 같은 객체 및 문자열 스타일 바인딩. 컴포넌트의 `host` 객체에 있는 `[style]` 항목도 포함합니다.
- `[style.border-color]="'var(--primary-color)'"`처럼 바인딩 값 안에 있는 커스텀 프로퍼티 이름
- `Renderer2.setStyle` 호출

이렇게 생성한 프로퍼티는 네임스페이스가 적용된 스타일에서 더 이상 읽을 수 없습니다.
[TypeScript에서 네임스페이스가 적용된 프로퍼티 사용하기](#using-namespaced-properties-in-typescript)에서 설명하는 방식으로 직접 네임스페이스를 적용하세요.

<!--
### Opting out of namespacing

To declare or read a custom property that Angular does not namespace, such as one defined in a
global stylesheet, prefix its name with `--global--`. Angular removes `--global` and leaves the
remaining `--` and the rest of the name unchanged:

```css
:host {
  /* Declares --accent-color and reads --brand-color, not --my-app_brand-color. */
  --global--accent-color: navy;
  color: var(--global--brand-color);
}
```

Write two hyphens after `global`. A single hyphen, as in `--global-brand-color`, does not opt out,
and Angular namespaces that name like any other. Avoid names that start with `--global-` followed
by anything but a second hyphen; a future major version is planned to reject them at build time.
Angular removes `--global` in every application, including applications that never configure a
namespace.
-->

### 네임스페이스 적용 제외하기 {#opting-out-of-namespacing}

전역 스타일시트에 정의한 프로퍼티처럼 Angular가 네임스페이스를 적용하지 않아야 하는 커스텀 프로퍼티를 선언하거나 읽으려면 이름 앞에 `--global--`을 붙이세요.
Angular는 `--global`을 제거하고 나머지 `--`와 이름은 그대로 유지합니다.

```css
:host {
  /* --accent-color를 선언하고 --my-app_brand-color 대신 --brand-color를 읽습니다. */
  --global--accent-color: navy;
  color: var(--global--brand-color);
}
```

`global` 뒤에는 하이픈을 두 개 작성하세요.
`--global-brand-color`처럼 하이픈을 하나만 사용하면 적용 제외 대상이 되지 않으며, 다른 이름과 마찬가지로 네임스페이스가 적용됩니다.
`--global-` 다음에 두 번째 하이픈 이외의 문자가 오는 이름은 사용하지 마세요. 향후 메이저 버전에서는 빌드 시점에 이러한 이름을 허용하지 않을 예정입니다.
네임스페이스를 설정하지 않은 애플리케이션을 포함해서 모든 애플리케이션에서 Angular는 `--global`을 제거합니다.

<!--
### Using namespaced properties in TypeScript

Prefer a style binding such as `[style.--primary-color]`, which Angular namespaces for you. When
you go through a DOM API instead, pass the name you wrote in your styles to
[`CssVarNamespacer`](api/platform-browser/CssVarNamespacer), including the leading `--`:

```typescript
{header: "profile-photo.ts"}
import {Component, ElementRef, inject} from '@angular/core';
import {CssVarNamespacer} from '@angular/platform-browser';

@Component({
  selector: 'profile-photo',
  template: `<img src="profile-photo.jpg" alt="Your profile photo" />`,
  styles: `
    img {
      border: 2px solid var(--primary-color);
    }
  `,
})
export class ProfilePhoto {
  private readonly host: HTMLElement = inject(ElementRef).nativeElement;
  private readonly cssVarNamespacer = inject(CssVarNamespacer);

setPrimaryColor(color: string): void {
    this.host.style.setProperty(this.cssVarNamespacer.namespace('--primary-color'), color);
  }
}
```

Use the plain name for a property you declared with `--global--`, since Angular never namespaces
those. For everything else, `namespace` returns the name unchanged when an application configures
no namespace, so a library can call it for the custom properties its own styles declare.
-->

### TypeScript에서 네임스페이스가 적용된 프로퍼티 사용하기 {#using-namespaced-properties-in-typescript}

Angular가 자동으로 네임스페이스를 적용하는 `[style.--primary-color]` 같은 스타일 바인딩을 우선 사용하세요.
대신 DOM API를 사용한다면 스타일에 작성한 이름을 앞쪽의 `--`까지 포함해서 [`CssVarNamespacer`](api/platform-browser/CssVarNamespacer)에 전달하세요.

```typescript
{header: "profile-photo.ts"}
import {Component, ElementRef, inject} from '@angular/core';
import {CssVarNamespacer} from '@angular/platform-browser';

@Component({
  selector: 'profile-photo',
  template: `<img src="profile-photo.jpg" alt="프로필 사진" />`,
  styles: `
    img {
      border: 2px solid var(--primary-color);
    }
  `,
})
export class ProfilePhoto {
  private readonly host: HTMLElement = inject(ElementRef).nativeElement;
  private readonly cssVarNamespacer = inject(CssVarNamespacer);

setPrimaryColor(color: string): void {
    this.host.style.setProperty(this.cssVarNamespacer.namespace('--primary-color'), color);
  }
}
```

`--global--`로 선언한 프로퍼티에는 Angular가 네임스페이스를 적용하지 않으므로 원래 이름을 사용하세요.
다른 프로퍼티의 경우 애플리케이션에 네임스페이스가 설정되어 있지 않으면 `namespace`가 이름을 그대로 반환합니다.
따라서 라이브러리에서도 자체 스타일에 선언한 커스텀 프로퍼티에 이 메서드를 사용할 수 있습니다.

# 입력 프로퍼티로 데이터 받기

<!--
TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular. If you're familiar with other web frameworks, input properties are similar to _props_.

When you use a component, you commonly want to pass some data to it. A component specifies the data that it accepts by declaring
**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);
}
```

This lets you bind to the property in a template:

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

If an input has a default value, TypeScript infers the type from the default value:

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

You can explicitly declare a type for the input by specifying a generic parameter to the function.

If an input without a default value is not set, its value is `undefined`:

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

**Angular records inputs statically at compile-time**. Inputs cannot be added or removed at run-time.

The `input` function has special meaning to the Angular compiler. **You can exclusively call `input` in component and directive property initializers.**

When extending a component class, **inputs are inherited by the child class.**

**Input names are case-sensitive.**
-->

팁: 이 가이드 문서는 [핵심 가이드](essentials) 이후 내용을 다룹니다. 아직 Angular에 익숙하지 않다면 해당 문서를 먼저 읽어보세요.

팁: 만약 웹 프레임워크에 익숙하다면, 입력 프로퍼티는 _프롭스(props)_ 와 비슷하다고 이해해도 됩니다.

컴포넌트를 사용하다 보면 컴포넌트에 데이터를 전달하는 경우가 자주 있습니다.
이 경우 컴포넌트의 **입력 프로퍼티** 를 활용하면 됩니다:

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

@Component(/* ... */)
export class CustomSlider {
  // `value` 라는 이름으로 입력 프로퍼티를 선언하고 기본값 0을 할당합니다.
  value = input(0);
}
```

그러면 템플릿에서 이렇게 프로퍼티 바인딩할 수 있습니다:

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

입력 프로퍼티에 기본값이 있으면 TypeScript는 기본값을 기준으로 타입을 추론합니다:

```ts
@Component(/* ... */)
export class CustomSlider {
  // TypeScript는 숫자를 입력받는 것을 기준으로 InputSignal<number> 타입으로 추론합니다.
  value = input(0);
}
```

입력 프로퍼티에 제네릭 함수를 사용하는 경우에는 타입을 명확하게 지정할 수도 있습니다.

기본값이 없는 입력 프로퍼티에 값을 설정하지 않으면 그 값은 `undefined`입니다.

```ts
@Component(/* ... */)
export class CustomSlider {
  // 입력 프로퍼티 `value`의 기본값이 할당되지 않았기 때문에 타입은 InputSignal<number | undefined> 으로 추론됩니다.
  value = input<number>();
}
```

**Angular는 입력 프로퍼티를 컴파일 시점에 정적으로 분석합니다**.
그래서 실행 시점에 입력 프로퍼티를 추가하거나 제거할 수 없습니다.

그리고 `input` 함수는 Angular 컴파일러 관점에서 특별한 의미를 갖습니다.
**`input` 함수는 컴포넌트 프로퍼티나 디렉티브 프로퍼티를 초기화할 때만 사용할 수 있습니다.**

컴포넌트 클래스를 상속받는 경우, **자식 클래스는 부모 클래스의 입력 프로퍼티를 상속받습니다.**

**입력 프로퍼티는 대소문자를 구분합니다.**

## 입력 프로퍼티 값 읽기

<!--
The `input` function returns an `InputSignal`. You can read the value by calling the signal:

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

Signals created by the `input` function are read-only.
-->

`input` 함수는 `InputSignal`을 반환합니다.
이 시그널의 값을 읽으려면 시그널을 실행하면 됩니다:

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

@Component(/* ... */)
export class CustomSlider {
  // `value` 라는 이름으로 입력 프로퍼티를 선언하고 기본값 0을 할당합니다.
  value = input(0);

// `value` 입력 프로퍼티를 기반으로 연산 시그널을 생성합니다.
  label = computed(() => `The slider's value is ${this.value()}`);
}
```

`input` 함수로 만든 시그널은 읽기 전용 시그널입니다.

## 필수 입력값 {#required-inputs}

<!--
You can declare that an input is `required` by calling `input.required` instead of `input`:

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

Angular enforces that required inputs _must_ be set when the component is used in a template. If you try to use a component without specifying all of its required inputs, Angular reports an error at build-time.

Required inputs do not automatically include `undefined` in the generic parameter of the returned `InputSignal`.
-->

입력 프로퍼티 값을 필수 항목으로 지정하려면 `input` 함수 대신 `input.required` 함수를 사용하면 됩니다:

```ts
{highlight:[4]}
@Component(/* ... */)
export class CustomSlider {
  // `value` 라는 이름으로 입력 프로퍼티를 선언하고 `InputSignal<number>`를 할당합니다.
  value = input.required<number>();
}
```

이렇게 구현하면 템플릿에 컴포넌트가 사용될 때 입력값을 _반드시_ 지정해야 합니다.
입력값 없이 컴포넌트를 사용하면 빌드 시점에 오류가 발생합니다.

입력 프로퍼티가 필수인 경우에는 `InputSignal`의 제네릭에 `undefined`를 추가하지 않는 한 `undefined`를 포함하지 않습니다.

## 입력 프로퍼티 설정하기

`input` 함수에 두번째 인자로 옵션 객체를 전달할 수 있습니다.

### 입력값 변환

<!--
You can specify a `transform` function to change the value of an input when it's set by 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" />
```

In the example above, whenever the value of `systemVolume` changes, Angular runs `trimString` and sets `label` to the result.

The most common use-case for input transforms is to accept a wider range of value types in templates, often including `null` and `undefined`.

**Input transform function must be statically analyzable at build-time.** You cannot set transform functions conditionally or as the result of an expression evaluation.

**Input transform functions should always be [pure functions](https://en.wikipedia.org/wiki/Pure_function).** Relying on state outside the transform function can lead to unpredictable behavior.
-->

입력 프로퍼티로 받은 값을 변환해서 할당하려면 `transform` 함수를 사용하면 됩니다.

```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` 값이 변경될 때 `trimString` 함수가 실행되고 그 결과값이 `label`에 할당됩니다.

입력값을 변환하는 경우는 `null` 값과 `undefined` 값을 포함해서 템플릿에 사용되는 값의 타입을 완화하는 경우에 자주 사용됩니다.

**입력 프로퍼티 변환 함수는 빌드 시점에 정적으로 분석됩니다.**
그래서 변환 함수는 조건에 따라 결정하거나 표현식의 결과로 할당할 수는 없습니다.

**입력 프로퍼티 변환 함수는 반드시 [순수 함수(pure functions)](https://en.wikipedia.org/wiki/Pure_function)여야 합니다.**
변환 함수 외부 상태에 영향을 받으면, 변환 함수의 결과값을 예측할 수 없습니다.

#### 타입 검사

<!--
When you specify an input transform, the type of the transform function's parameter determines the types of values that can be set to the input in a template.

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

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

In the example above, the `widthPx` input accepts a `number` while the `InputSignal` property returns a `string`.
-->

입력 프로퍼티 변환 함수를 지정할 때, 변환 함수의 인자 타입에 따라 템플릿에서 입력 프로퍼티에 할당할 수 있는 타입이 결정됩니다.

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

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

위 코드처럼 구현하면 입력 프로퍼티 `widthPx`가 `InputSignal`로 문자열을 반환받더라도 `number` 타입을 인자로 받습니다.

#### 기본 변환 함수

<!--
Angular includes two built-in transform functions for the two most common scenarios: coercing values to boolean and 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` imitates the behavior of standard HTML [boolean attributes](https://developer.mozilla.org/docs/Glossary/Boolean/HTML), where the
_presence_ of the attribute indicates a "true" value. However, Angular's `booleanAttribute` treats the literal string `"false"` as the boolean `false`.

`numberAttribute` attempts to parse the given value to a number, producing `NaN` if parsing fails.
-->

불리언 타입과 숫자 타입을 변환하는 작업은 자주 사용되기 때문에 Angular가 기본 변환 함수를 제공합니다.

```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 [불리언 어트리뷰트](https://developer.mozilla.org/docs/Glossary/Boolean/HTML)처럼 어트리뷰트 자체가 _존재하면_ `true`로 취급합니다.
그리고 `booleanAttribute`가 `"false"` 문자열을 받으면 불리언 `false` 값으로 변환합니다.

`numberAttribute`는 값이 주어지면 숫자로 변환합니다.
숫자 파싱이 실패하면 `NaN`로 변환됩니다.

### 별칭 {#input-aliases}

<!--
You can specify the `alias` option to change the name of an input in templates.

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

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

This alias does not affect usage of the property in TypeScript code.

While you should generally avoid aliasing inputs for components, this feature can be useful for renaming properties while preserving an alias for the original name or for avoiding collisions with the name of native DOM element properties.
-->

템플릿에 사용하는 입력 프로퍼티 이름을 다르게 사용하려면 `alias` 옵션을 사용하면 됩니다.

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

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

이 별칭은 TypeScript 코드에서 사용하는 프로퍼티 이름에 영향을 주지 않습니다.

보통은 컴포넌트 입력 프로퍼티에 별칭을 부여하는 것은 권장하지 않지만, 이 기능은 기존 프로퍼티 이름을 유지하면서 다른 네이티브 DOM 엘리먼트 이름과 충돌하는 것을 방지하는 용도로 사용할 때는 유용합니다.

## 모델 입력 프로퍼티

<!--
**Model inputs** are a special type of input that enable a component to propagate new values back to its parent component.

When creating a component, you can define a model input similarly to how you create a standard input.

Both types of input allow someone to bind a value into the property. However, **model inputs allow the component author to write values into the property**. If the property is bound with a two-way binding, the new value propagates to that 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);
}
```

In the above example, the `CustomSlider` can write values into its `value` model input, which then propagates those values back to the `volume` signal in `MediaControls`. This binding keeps the values of `value` and `volume` in sync. Notice that the binding passes the `volume` signal instance, not the _value_ of the signal.

In other respects, model inputs work similarly to standard inputs. You can read the value by calling the signal function, including in [reactive contexts](guide/signals#reactive-contexts) like `computed` and `effect`.

See [Two-way binding](guide/templates/two-way-binding) for more details on two-way binding in templates.
-->

**모델 입력 프로퍼티(Model input)** 는 컴포넌트가 부모 컴포넌트로 값을 전달하는 형태의 특별한 입력 프로퍼티입니다.

모델 입력 프로퍼티는 컴포넌트를 정의할 때 일반적인 입력 프로퍼티를 선언하는 것과 비슷하게 선언합니다.

모델 입력 프로퍼티와 일반 입력 프로퍼티는 컴포넌트 안쪽으로 값을 전달할 수 있습니다.
그런데 **모델 입력 프로퍼티는 컴포넌트 밖으로도 값을 전달할 수 있습니다.**
그래서 이 프로퍼티는 양방향으로 바인딩할 수 있습니다.

```ts
@Component(/* ... */)
export class CustomSlider {
  // `value`라는 이름으로 모델 입력 프로퍼티를 선언합니다.
  value = model(0);

increment() {
    // 모델 입력 프로퍼티 값을 변경하고, 바인딩된 곳으로 새 값을 전달합니다.
    this.value.update((oldValue) => oldValue + 10);
  }
}

@Component({
  /* ... */
  // 양방향 바인딩을 사용한다는 것은, 슬라이더의 값이 변경되면 자동으로 `volume` 시그널로 전달된다는 것을 의미합니다.
  // 이 바인딩은 시그널의 값이 아닌 시그널의 *인스턴스*를 활용합니다.
  template: `<custom-slider [(value)]="volume" />`,
})
export class MediaControls {
  // 로컬 상태를 저장하기 위해 값을 지정할 수 있는 시그널로 `volume` 프로퍼티를 선언합니다.
  volume = signal(0);
}
```

위 예제에서 `CustomSlider`는 `value` 모델 입력 프로퍼티를 통해 값을 지정할 수 있고, 이렇게 쓴 값을 `MediaControls`의 `volume` 시그널로 전달할 수 있습니다.
이 경우 `value`와 `volume` 값은 동기화되어 유지됩니다.
바인딩 문법에서 `volume` 시그널의 _값_ 이 아니라 시그널 인스턴스라는 것에 주의하세요.

다른 측면에서는, 모델 입력 프로퍼티는 일반적인 입력 프로퍼티와 비슷하기도 합니다.
`computed`나 `effect`와 연동하는 방식을 지원하며, 시그널 함수를 실행하면 값을 읽을 수 있습니다.

양방향 바인딩을 자세하게 알아보려면 [양방향 바인딩](guide/templates/two-way-binding) 문서를 참고하세요.

### 일반 프로퍼티의 양방향 바인딩

<!--
You can bind a plain JavaScript property to a 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;
}
```

In the example above, the `CustomSlider` can write values into its `value` model input, which then propagates those values back to the `volume` property in `MediaControls`. This binding keeps the values of `value` and `volume` in sync.
-->

일반적인 JavaScript 프로퍼티를 모델 입력 프로퍼티와 바인딩할 수 있습니다.

```typescript
@Component({
  /* ... */
  // `value` 는 모델 입력 프로퍼티입니다.
  // `[()]` 문법은 양방향 바인딩을 의미합니다.
  template: '<custom-slider [(value)]="volume" />',
})
export class MediaControls {
  protected volume = 0;
}
```

위 예제 코드에서 `CustomSlider`는 `value` 모델 입력 프로퍼티를 통해 값을 지정할 수 있습니다.
그러면 이 값은 `MediaControls`의 `volume` 프로퍼티로 다시 전달됩니다.
결국 `value` 프로퍼티와 `volume` 프로퍼티는 동기화되어 유지됩니다.

### `change` 이벤트

<!--
When you declare a model input in a component or directive, Angular automatically creates a corresponding [output](guide/components/outputs) for that model. The output's name is the model input's name suffixed with "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 emits this change event whenever you write a new value into the model input by calling its `set` or `update` methods.

See [Custom events with outputs](guide/components/outputs) for more details on outputs.
-->

컴포넌트나 디렉티브에 모델 입력 프로퍼티를 선언하면 Angular는 해당 모델에 해당하는 [출력 프로퍼티](guide/components/outputs)를 Angular가 자동으로 생성합니다.
이 출력 프로퍼티의 이름은 입력 프로퍼티 이름에 "Change" 접미사를 붙인 것으로 결정됩니다.

```ts
@Directive(/* ... */)
export class CustomCheckbox {
  // "checkedChange" 출력 프로퍼티가 자동으로 생성됩니다.
  // 템플릿에서 `(checkedChange)="handler()"` 라고 지정하면 출력 프로퍼티를 구독할 수 있습니다.
  checked = model(false);
}
```

이제 모델 입력 프로퍼티에 `set` 메서드나 `update` 메서드를 사용해서 값이 변경되면, Angular가 값이 변경되었다는 이벤트를 보냅니다.

출력 프로퍼티를 자세하게 알아보려면 [출력 프로퍼티로 커스텀 이벤트 보내기](guide/components/outputs) 문서를 참고하세요.

### 모델 입력 프로퍼티 커스터마이징하기

<!--
You can mark a model input as [required](#required-inputs) or provide an [alias](#input-aliases) in the same way as a standard input.

Model inputs do not support input transforms.
-->

모델 입력 프로퍼티는 일반 입력 프로퍼티와 같은 방식으로 [필수 여부](#required-inputs)를 지정하거나 [별칭](#input-aliases)을 지정할 수 있습니다.

모델 입력 프로퍼티는 변환 함수를 지원하지 않습니다.

### 모델 입력 프로퍼티는 언제 사용할까요

모델 입력 프로퍼티는 양방향 바인딩을 사용할 때 활용합니다.
이 방식은 일반적으로 사용자와 상호작용하면서 값을 수정해야 하는 경우에 적합합니다.
커스텀 폼 컨트롤이나 날짜 선택기, 콤보박스 같은 컨트롤에서 사용하는 것이 일반적입니다.

## 입력 프로퍼티 이름 정하기

<!--
Avoid choosing input names that collide with properties on DOM elements like HTMLElement. Name collisions introduce confusion about whether the bound property belongs to the component or the DOM element.

Avoid adding prefixes for component inputs like you would with component selectors. Since a given element can only host one component, any custom properties can be assumed to belong to the component.
-->

HTMLElement와 같은 DOM 엘리먼트의 프로퍼티와 겹치는 이름은 사용하지 마세요.
이름이 겹치면 프로퍼티를 바인딩하는 것이 컴포넌트와 바인딩하는 것인지 DOM 엘리먼트와 바인딩하는 것인지 알 수 없습니다.

컴포넌트 셀렉터에 하듯 컴포넌트 입력 프로퍼티에 접두사를 추가하지 마세요.
엘리먼트는 컴포넌트 하나의 호스트 엘리먼트가 될 수 있기 때문에, 모든 사용자 프로퍼티는 컴포넌트에 속한 것으로 간주됩니다.

## `@Input` 데코레이터로 입력 프로퍼티 선언하기

<!--
TIP: While the Angular team recommends using the signal-based `input` function for new projects, the original decorator-based `@Input` API remains fully supported.

You can alternatively declare component inputs by adding the `@Input` decorator to a property:

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

Binding to an input is the same in both signal-based and decorator-based inputs:

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

팁: Angular 팀은 새 프로젝트에서 시그널 기반 `input` 함수를 사용하는 것을 권장하지만, 기존 데코레이터 기반 `@Input` API도 계속 완전히 지원합니다.

입력 프로퍼티는 `@Input` 데코레이터를 사용해서 선언할 수도 있습니다:

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

템플릿에서 바인딩하는 방법은 시그널을 기반으로 할 때와 같습니다:

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

### 데코레이터 기반 입력 프로퍼티를 커스터마이징하기

`@Input` 데코레이터는 동작방식을 지정하는 설정 객체를 인자로 받을 수 있습니다.

#### 필수 입력 프로퍼티 {#required-inputs-decorator}

<!--
You can specify the `required` option to enforce that a given input must always have a value.

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

If you try to use a component without specifying all of its required inputs, Angular reports an error at build-time.
-->

`required` 옵션을 지정하면 입력 프로퍼티 값을 필수 항목으로 지정할 수 있습니다.

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

이제 템플릿에서 필수값을 지정하지 않고 컴포넌트를 사용하면 빌드 시점에 오류가 발생합니다.

#### 입력값 변환 {#input-transforms-decorator}

<!--
You can specify a `transform` function to change the value of an input when it's set by Angular. This transform function works identically to transform functions for signal-based inputs described above.

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

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

입력 프로퍼티로 들어오는 값을 변환해서 사용하고 싶다면 `transform` 함수를 지정하면 됩니다.
이 변환 함수는 시그널 기반에서 다뤘던 것과 동일합니다.

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

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

#### 별칭 {#input-aliases-decorator}

<!--
You can specify the `alias` option to change the name of an input in templates.

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

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

The `@Input` decorator also accepts the alias as its first parameter in place of the config object.

Input aliases work the same way as for signal-based inputs described above.
-->

입력 프로퍼티에 별칭을 지정하려면 `alias` 옵션을 지정하면 됩니다.

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

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

`@Input` 데코레이터를 사용할 때 첫번째 인자를 지정하면 설정 객체 없이 별칭을 지정할 수 있습니다.

별칭은 시그널 기반에서 다뤘던 것과 동일합니다.

### 입력 프로퍼티의 게터(getter)와 세터(setter)

<!--
When using decorator-based inputs, a property implemented with a getter and setter can be an input:

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

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

private internalValue = 0;
}
```

You can even create a _write-only_ input by only defining a public setter:

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

private internalValue = 0;
}
```

**Prefer using input transforms instead of getters and setters** if possible.

Avoid complex or costly getters and setters. Angular may invoke an input's setter multiple times, which may negatively impact application performance if the setter performs any costly behaviors, such as DOM manipulation.
-->

데코레이터 기반으로 입력 프로퍼티를 선언하면서 입력 프로퍼티의 게터와 세터를 추가로 구현할 수 있습니다:

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

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

private internalValue = 0;
}
```

그리고 public 세터를 정의하면 _쓰기 전용_ 입력 프로퍼티를 만들 수도 있습니다:

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

private internalValue = 0;
}
```

가능하다면 **게터, 세터 대신 입력 프로퍼티 변환 함수를 사용하세요**.
Angular는 입력 프로퍼티의 세터를 여러 번 실행할 수 있으며, 이 세터가 DOM을 조작하는 것처럼 성능에 영향을 많이 주는 경우에는 전체 애플리케이션 성능에 부정적인 영향을 미칠 수 있습니다.

## `@Component` 데코레이터에서 입력 프로퍼티 정의하기

<!--
In addition to the `@Input` decorator, you can also specify a component's inputs with the `inputs` property in the `@Component` decorator. This can be useful when a component inherits a property from a base class:

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

You can additionally specify an input alias in the `inputs` list by putting the alias after a colon in the string:

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

`@Input` 데코레이터 외에도 `@Component` 데코레이터의 `inputs` 프로퍼티로 컴포넌트의 입력 프로퍼티를 지정할 수 있습니다.
이 방식은 컴포넌트를 기본 클래스에서 상속받을 때 유용합니다:

```ts
{highlight:[4]}
// `CustomSlider`는 `BaseSlider`에서 `disabled` 프로퍼티를 상속받습니다.
@Component({
  ...,
  inputs: ['disabled'],
})
export class CustomSlider extends BaseSlider { }
```

그리고 입력 프로퍼티를 선언할 때 콜론(`:`)을 사용하면 별칭을 함께 지정할 수도 있습니다:

```ts
{highlight:[4]}
// `CustomSlider`는 `BaseSlider`에서 `disabled` 프로퍼티를 상속받습니다.
@Component({
  ...,
  inputs: ['disabled: sliderDisabled'],
})
export class CustomSlider extends BaseSlider { }
```

# 커스텀 이벤트 보내기

<!--
TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular.

Angular components can define custom events by assigning a property to the `output` function:

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

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

The `output` function returns an `OutputEmitterRef`. You can emit an event by calling the `emit` method on the `OutputEmitterRef`:

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

Angular refers to properties initialized with the `output` function as **outputs**. You can use outputs to raise custom events, similar to native browser events like `click`.

**Angular custom events do not bubble up the DOM**.

**Output names are case-sensitive.**

When extending a component class, **outputs are inherited by the child class.**

The `output` function has special meaning to the Angular compiler. **You can exclusively call `output` in component and directive property initializers.**
-->

팁: 이 가이드 문서는 [핵심 가이드](essentials) 이후 내용을 다룹니다. 아직 Angular에 익숙하지 않다면 해당 문서를 먼저 읽어보세요.

컴포넌트는 `output` 함수로 출력 프로퍼티를 선언해서 커스텀 이벤트를 정의할 수 있습니다:

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

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

`output` 함수를 실행하면 `OutputEmitterRef` 객체를 반환합니다.
그리고 `OutputEmitterRef` 객체의 `emit` 메서드를 실행하면 이벤트를 보낼 수 있습니다:

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

Angular에서 `output` 함수로 초기화한 프로퍼티를 **출력 프로퍼티(outputs)** 라고 합니다.
출력 프로퍼티는 `click`과 같은 네이티브 브라우저 이벤트와 비슷하게 동작하는 커스텀 이벤트를 발생시키는 용도로 사용합니다.

**Angular 커스텀 이벤트는 DOM을 따라 버블 업(bubble up) 되지 않습니다.**

**출력 프로퍼티 이름은 대소문자를 구분합니다.**

컴포넌트 클래스를 상속하면, **자식 클래스에도 출력 프로퍼티가 상속됩니다.**

`output` 함수는 Angular 컴파일러가 특별하게 감지하는 함수입니다.
**`output` 함수는 컴포넌트와 디렉티브의 프로퍼티 초기화 코드에서만 호출할 수 있습니다.**

## 이벤트 데이터 보내기

<!--
You can pass event data when calling `emit`:

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

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

When defining an event listener in a template, you can access the event data from the `$event` variable:

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

Receive the event data in the parent component:

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

```
-->

`emit` 메서드를 실행하면서 이벤트 데이터를 보낼 수 있습니다:

```ts
// 기본 자료형을 보낼 수 있습니다.
this.valueChanged.emit(7);

// 커스텀 이벤트 객체를 보낼 수도 있습니다.
this.thumbDropped.emit({
  pointerX: 123,
  pointerY: 456,
});
```

이벤트 데이터를 활용하려면 템플릿에서 이벤트 리스너를 연결할 때 `$event` 변수를 인자로 전달하면 됩니다:

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

부모 컴포넌트에서는 이렇게 이벤트 데이터를 받습니다:

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

```

## 별칭으로 사용하기

<!--
The `output` function accepts a parameter that lets you specify a different name for the event in a template:

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

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

This alias does not affect usage of the property in TypeScript code.

While you should generally avoid aliasing outputs for components, this feature can be useful for renaming properties while preserving an alias for the original name or for avoiding collisions with the name of native DOM events.
-->

템플릿에서 이벤트 이름을 프로퍼티 이름과 다르게 사용하려면 `output` 함수를 실행하면서 설정하면 됩니다:

```ts
@Component(/* ... */)
export class CustomSlider {
  changed = output({alias: 'valueChanged'});
}
```
```html
<custom-slider (valueChanged)="saveVolume()" />
```

이렇게 별칭을 지정해도 TypeScript 코드에는 영향을 주지 않습니다.

일반적으로는 컴포넌트 출력 프로퍼티의 별칭을 지정하지 않는 것이 좋지만, 기존 프로퍼티 이름이 네이티브 DOM 이벤트 이름과 충돌하는 경우 유용할 수 있습니다.

## 코드로 출력 프로퍼티 구독하기

<!--
When creating a component dynamically, you can programmatically subscribe to output events
from the component instance. The `OutputRef` type includes a `subscribe` method:

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

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

Angular automatically cleans up event subscriptions when it destroys components with subscribers. Alternatively, you can manually unsubscribe from an event. The `subscribe` function returns an `OutputRefSubscription` with an `unsubscribe` method:

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

// ...

eventSubscription.unsubscribe();
```
-->

컴포넌트를 동적으로 생성했다면, 컴포넌트 인스턴스의 출력 프로퍼티 이벤트를 코드로 구독할 수 있습니다.
`OutputRef` 타입의 `subscribe` 메서드를 실행하면 됩니다:

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

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

이렇게 구독하는 이벤트는 컴포넌트 인스턴스가 종료되면 자동으로 종료됩니다.
필요하다면 이벤트를 직접 구독 중지할 수도 있습니다.
`subscribe` 함수가 반환하는 `OutputRefSubscription` 객체의 `unsubscribe` 메서드를 실행하면 됩니다:

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

// ...

eventSubscription.unsubscribe();
```

## 이벤트 이름 결정하기

<!--
Avoid choosing output names that collide with events on DOM elements like HTMLElement. Name collisions introduce confusion about whether the bound property belongs to the component or the DOM element.

Avoid adding prefixes for component outputs like you would with component selectors. Since a given element can only host one component, any custom properties can be assumed to belong to the component.

Always use [camelCase](https://en.wikipedia.org/wiki/Camel_case) output names. Avoid prefixing output names with "on".
-->

출력 프로퍼티의 이름을 결정할 때 HTMLElement와 같은 DOM 엘리먼트의 이벤트와 같은 이름은 피하세요.
이벤트 이름이 충돌되면 이벤트가 발생했을 때 이 이벤트가 컴포넌트에서 왔는지 DOM 엘리먼트에서 왔는지 혼동될 수 있습니다.

컴포넌트 셀렉터를 지정하던 것처럼 출력 프로퍼티에 접두사를 추가하지 마세요.
엘리먼트 하나는 컴포넌트 하나만 호스팅할 수 있기 때문에, 접두사가 없어도 커스텀 프로퍼티는 해당 컴포넌트에서 존재하는 것으로 간주할 수 있습니다.

출력 프로퍼티 이름은 [캐멀 케이스(camelCase)](https://en.wikipedia.org/wiki/Camel_case)로 지정하세요.
"on" 접두사는 사용하지 마세요.

## RxJS와 함께 사용하기

출력 프로퍼티와 RxJS를 함께 사용하는 방법은 [컴포넌트, 디렉티브 출력 프로퍼티와 RxJS 상호작용](ecosystem/rxjs-interop/output-interop) 문서를 참고하세요.

## `@Output` 데코레이터로 출력 프로퍼티 선언하기

<!--
TIP: While the Angular team recommends using the `output` function for new projects, the
original decorator-based `@Output` API remains fully supported.

You can alternatively define custom events by assigning a property to a new `EventEmitter` and adding the `@Output` decorator:

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

You can emit an event by calling the `emit` method on the `EventEmitter`.
-->

팁: Angular 팀은 새 프로젝트부터 `output` 함수 사용을 권장하지만, `Output` 데코레이터를 사용하는 방식도 여전히 완벽하게 지원합니다.

커스텀 이벤트는 프로퍼티에 `@Output` 데코레이터를 붙이고 `EventEmitter` 인스턴스를 생성하는 방식으로 선언할 수도 있습니다:

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

이 경우는 `EventEmitter` 객체의 `emit` 메서드를 실행해서 이벤트를 보낼 수 있습니다.

### `@Output` 데코레이터로 별칭 지정하기

<!--
The `@Output` decorator accepts a parameter that lets you specify a different name for the event in a template:

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

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

This alias does not affect usage of the property in TypeScript code.
-->

템플릿에서 이벤트 이름을 출력 프로퍼티와 다르게 사용하려면 `@Output` 데코레이터에 별칭을 지정하면 됩니다:

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

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

이렇게 별칭을 지정하더라도 TypeScript 코드에서 출력 프로퍼티를 활용하는 코드에는 영향을 주지 않습니다.

## `@Component` 데코레이터로 출력 프로퍼티 선언하기

<!--
In addition to the `@Output` decorator, you can also specify a component's outputs with the `outputs` property in the `@Component` decorator. This can be useful when a component inherits a property from a base class:

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

You can additionally specify an output alias in the `outputs` list by putting the alias after a colon in the string:

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

`@Output` 데코레이터를 사용하는 방법 외에도, `@Component` 데코레이터의 `outputs` 프로퍼티를 사용하면 컴포넌트 출력 프로퍼티를 선언할 수 있습니다.
이 방식은 컴포넌트를 상속받는 경우에 유용합니다:

```ts
// `CustomSlider` 는 `BaseSlider` 에 있는 `valueChanged` 프로퍼티를 상속받습니다.
@Component({
  /*...*/
  outputs: ['valueChanged'],
})
export class CustomSlider extends BaseSlider {}
```

그리고 `outputs`를 선언하면서 콜론을 붙이고 문자열을 붙이면 출력 프로퍼티의 별칭을 지정할 수 있습니다:

```ts
// `CustomSlider` 는 `BaseSlider` 에 있는 `valueChanged` 프로퍼티를 상속받습니다.
@Component({
  /*...*/
  outputs: ['valueChanged: volumeChanged'],
})
export class CustomSlider extends BaseSlider {}
```

# 컨텐츠 프로젝션: ng-content

<!--
TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular.

You often need to create components that act as containers for different types of content. For
example, you may want to create a custom card component:

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

**You can use the `<ng-content>` element as a placeholder to mark where content should go**:

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

TIP: `<ng-content>` works similarly
to [the native `<slot>` element](https://developer.mozilla.org/docs/Web/HTML/Element/slot),
but with some Angular-specific functionality.

When you use a component with `<ng-content>`, any children of the component host element are
rendered, or **projected**, at the location of that `<ng-content>`:

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

```html
<!- Using the component ->
<custom-card>
  <p>This is the projected content</p>
</custom-card>
```

```html
<!- The rendered DOM ->
<custom-card>
  <div class="card-shadow">
    <p>This is the projected content</p>
  </div>
</custom-card>
```

Angular refers to any children of a component passed this way as that component's **content**. This
is distinct from the component's **view**, which refers to the elements defined in the component's
template.

**The `<ng-content>` element is neither a component nor DOM element**. Instead, it is a special
placeholder that tells Angular where to render content. Angular's compiler processes
all `<ng-content>` elements at build-time. You cannot insert, remove, or modify `<ng-content>` at
run time. You cannot add directives, styles, or arbitrary attributes to `<ng-content>`.

IMPORTANT: You should not conditionally include `<ng-content>` with `@if`, `@for`, or `@switch`. Angular always
instantiates and creates DOM nodes for content rendered to a `<ng-content>` placeholder, even if
that `<ng-content>` placeholder is hidden. For conditional rendering of component content,
see [Template fragments](api/core/ng-template).
-->

팁: 이 가이드 문서는 [핵심 가이드](essentials) 이후 내용을 다룹니다. 아직 Angular에 익숙하지 않다면 해당 문서를 먼저 읽어보세요.

때로는 내용물을 다양하게 다루는 컨테이너 용도로 컴포넌트를 생성하는 경우가 있습니다.
커스텀 카드 컴포넌트 같은 경우가 그렇습니다:

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

**이때 내용물이 들어갈 위치는 `<ng-content>` 엘리먼트로 지정합니다**:

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

팁: `<ng-content>`는 [네이티브 `<slot>` 엘리먼트](https://developer.mozilla.org/docs/Web/HTML/Element/slot)와 비슷하게 동작하지만, Angular용 기능이 일부 추가되었습니다.

컴포넌트에 `<ng-content>`를 사용하면, 이 컴포넌트의 자식 컴포넌트나 **프로젝션(projected)** 되는 내용물은 모두 `<ng-content>` 엘리먼트 위치에 렌더링됩니다:

```typescript
// 컴포넌트 소스
@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>
```

컴포넌트 밖에서 컴포넌트 안으로 전달되는 모든 내용을 컴포넌트의 **내용물(content)** 라고 합니다.
컴포넌트 템플릿에 존재하는 엘리먼트를 의미하는 **뷰(view)** 와는 다릅니다.

중요: **`<ng-content>` 엘리먼트는 컴포넌트도 아니고 DOM 엘리먼트도 아닙니다.**
이 엘리먼트는 Angular에게 프로젝션되는 내용물의 위치를 지정하는 용도로만 사용되는 특별한 플레이스홀더(placeholder)입니다.
Angular 컴파일러는 `<ng-content>` 엘리먼트를 빌드 시점에 처리합니다.
`<ng-content>`는 실행 시점에 추가하거나, 제거하거나, 수정할 수 없습니다.
그리고 `<ng-content>`에 디렉티브를 적용하거나, 스타일, 어트리뷰트를 추가할 수도 없습니다.

`<ng-content>`는 `@if`나 `@for`, `@switch`로 제어할 수 없습니다.
Angular는 언제나 `<ng-content>` 플레이스홀더가 위치한 곳에 내용물을 렌더링하거나 DOM 노드를 생성하는데, `<ng-content>` 플레이스홀더가 화면에 표시되지 않는 경우도 그렇습니다.
컴포넌트 내용물을 조건부로 렌더링하려면 [템플릿 조각(Template fragments)](api/core/ng-template)을 참고하세요.

## 플레이스홀더 여러 개 사용하기

<!--
Angular supports projecting multiple different elements into different `<ng-content>` placeholders
based on CSS selector. Expanding the card example from above, you could create two placeholders for
a card title and a card body by using the `select` attribute:

```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 template ->
@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
<!- Using the component ->
@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
<!- Rendered DOM ->
<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>
```

The `<ng-content>` placeholder supports the same CSS selectors
as [component selectors](guide/components/selectors).

IMPORTANT: if using an attribute or class selector, it must be set statically, i.e `class="within"`.
Dynamic bindings such as `[class.within]="isWithin()"` will not be seen by the `select` selector.

If you include one or more `<ng-content>` placeholders with a `select` attribute and
one `<ng-content>` placeholder without a `select` attribute, the latter captures all elements that
did not match a `select` attribute:

```html
<!- Component template ->
<div class="card-shadow">
  <ng-content select="card-title" />
  <div class="card-divider"></div>
  <!- capture anything except "card-title" ->
  <ng-content />
</div>
```

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

```html
<!- Rendered DOM ->
<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>
```

If a component does not include an `<ng-content>` placeholder without a `select` attribute, any
elements that don't match one of the component's placeholders do not render into the DOM.
-->

`<ng-content>` 플레이스홀더에 CSS 셀렉터를 지정하면 내용물을 여러 개 전달할 수 있습니다.
위에서 다룬 카드 예제를 다시 보자면, `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>
```

`<ng-content>` 플레이스홀더에 사용하는 CSS 셀렉터는 [컴포넌트 셀렉터](guide/components/selectors)로 지정하는 방식과 같습니다.

중요: 어트리뷰트 셀렉터나 클래스 셀렉터를 사용하려면 `class="within"`처럼 어트리뷰트나 클래스를 정적으로 설정해야 합니다.
`[class.within]="isWithin()"`처럼 동적으로 바인딩한 값은 `select` 셀렉터가 인식하지 못합니다.

`<ng-content>` 를 하나 이상 사용할 때 `select` 어트리뷰트를 지정한 `<ng-content>` 외에 `select` 어트리뷰트를 사용하지 않는 `<ng-content>`를 사용할 수 있는데, 이 경우는 `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>
```

컴포넌트에 `select` 어트리뷰트가 지정되지 않은 `<ng-content>` 플레이스홀더가 없다면, 플레이스홀더가 매칭되지 않는 엘리먼트는 DOM에 렌더링되지 않습니다.

## 폴백 컨텐츠

<!--
Angular can show _fallback content_ for a component's `<ng-content>` placeholder if that component doesn't have any matching child content. You can specify fallback content by adding child content to the `<ng-content>` element itself.

```html
<!- Component template ->
<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
<!- Using the component ->
<custom-card>
  <card-title>Hello</card-title>
  <!- No card-body provided ->
</custom-card>
```

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

컴포넌트에 매칭되는 자식 컨텐츠가 없다면, 컴포넌트 `<ng-content>`에 표시되는 _폴백 컨텐츠(fallback content)_ 를 표시할 수 있습니다.
`<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>
```

## 별칭으로 프로젝션하기

<!--
Angular supports a special attribute, `ngProjectAs`, that allows you to specify a CSS selector on
any element. Whenever an element with `ngProjectAs` is checked against an `<ng-content>`
placeholder, Angular compares against the `ngProjectAs` value instead of the element's identity:

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

```html
<!- Using the component ->
<custom-card>
  <h3 ngProjectAs="card-title">Hello</h3>

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

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

`ngProjectAs` supports only static values and cannot be bound to dynamic expressions.
-->

Angular는 모든 엘리먼트에 CSS 셀렉터를 지정할 수 있도록 `ngProjectAs` 라는 특별한 어트리뷰트를 지원합니다.
`ngProjectAs`가 지정된 엘리먼트를 `<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` 는 정적 값만 지원하며, 동적 표현식에 바인딩할 수는 없습니다.

## 주의사항

### 프로젝션된 컨텐츠는 부모 뷰에 존재합니다.

<!--
Even though projected content is _rendered_ inside the receiving component, it is still owned by the component that declared it. Angular tracks it as part of the parent's view, which has a couple of side effects worth knowing about.

**Change detection:** Projected content is checked when the _parent_ runs change detection. If the receiving component uses `OnPush`, Angular can skip checking that component's own template — but it won't skip the projected content, because that belongs to the parent.

```html
<!- Parent template (default change detection) ->
<onpush-wrapper>
  <!- Still checked on every parent cycle, OnPush doesn't help here ->
  <expensive-component />
</onpush-wrapper>
```

**Dependency injection:** Projected content gets its dependencies from the parent's injector, not from the receiving component's `viewProviders`. See [Providers and viewProviders](guide/di/hierarchical-dependency-injection) for details.
-->

어떤 컴포넌트가 컨텐츠를 받아서 프로젝션 안에 _렌더링하더라도_, 프로젝션된 컨텐츠는 여전히 이 컨텐츠를 정의한 컴포넌트가 주인입니다.
Angular는 부모 뷰를 계속 추적하는데, 이때 알아야 할 부수 효과가 몇 가지 있습니다.

**변경 감지:** 프로젝션된 컨텐츠는 _부모_ 컴포넌트의 변경 감지가 동작할 때 함께 검사됩니다.
그래서 컨텐츠를 받는 컴포넌트가 `OnPush`를 사용하면 Angular는 이 컴포넌트의 템플릿은 변경 감지를 건너뛰지만, 프로젝션된 컨텐츠는 부모 컴포넌트에 속하기 때문에 검사가 진행됩니다.

```html

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

**의존성 주입:** 프로젝션된 컨텐츠는 부모 인젝터로 의존성 객체를 받습니다.
컨텐츠를 받는 컴포넌트의 `viewProviders`를 참조하지 않습니다.
자세한 내용은 [프로바이더와 viewProviders](guide/di/hierarchical-dependency-injection)를 참고하세요.

### 일부 라이브러리 컴포넌트는 프로젝션된 자식 엘리먼트를 지원하지 않습니다.

<!--
Certain components — menus, tabs, lists — use `ContentChildren` to find their children and wire up behavior like keyboard navigation, focus management, or ARIA attributes. They're written assuming they own their children directly, so projecting external content into them tends to break things in subtle ways.

For example, wrapping `<mat-menu-item>` elements in an extra layer and projecting them into `<mat-menu>` can silently break keyboard navigation and screen reader support. The query still finds the items, but the internal setup that makes them interactive may not work correctly when the items come from a different view context.

If a library component manages its children's behavior, check its docs before reaching for content projection — it may not be supported.
-->

메뉴, 탭, 리스트와 같은 컴포넌트는 `ContentChildren`을 활용해서 자식 컴포넌트를 찾고 키보드 네비게이션이나 포커스 관리, ARIA 어트리뷰트를 연결합니다.
그런데 이런 컴포넌트는 자식 요소를 직접 소유한다고 가정하고 구현되기 때문에, 외부에서 컨텐츠를 프로젝션하면 문제가 생길 수 있습니다.

예를 들면, `<mat-menu-item>` 엘리먼트를 추가 레이어로 감싸고 `<mat-menu>`에 프로젝션하면, 키보드 네비게이션이나 스크린 리더 지원이 동작하지 않습니다.
쿼리는 여전히 자식 항목을 찾겠지만, 프로젝션되는 항목이 다른 뷰 컨텍스트에서 오면 상호작용이 제대로 동작하지 않을 수 있습니다.

라이브러리 컴포넌트가 자식 컴포넌트의 동작을 관리한다면, 컨텐츠 프로젝션을 지원하는지 문서를 먼저 확인해 보세요.

# 컴포넌트 라이프사이클

<!--
TIP: This guide assumes you've already read the [Essentials Guide](essentials). Read that first if you're new to Angular.

A component's **lifecycle** is the sequence of steps that happen between the component's creation
and its destruction. Each step represents a different part of Angular's process for rendering
components and checking them for updates over time.

In your components, you can implement **lifecycle hooks** to run code during these steps.
Lifecycle hooks that relate to a specific component instance are implemented as methods on your
component class. Lifecycle hooks that relate the Angular application as a whole are implemented
as functions that accept a callback.

A component's lifecycle is tightly connected to how Angular checks your components for changes over
time. For the purposes of understanding this lifecycle, you only need to know that Angular walks
your application tree from top to bottom, checking template bindings for changes. The lifecycle
hooks described below run while Angular is doing this traversal. This traversal visits each
component exactly once, so you should always avoid making further state changes in the middle of the
process.
-->

팁: 이 가이드 문서는 [핵심 가이드](essentials) 이후 내용을 다룹니다. 아직 Angular에 익숙하지 않다면 해당 문서를 먼저 읽어보세요.

컴포넌트의 **라이프사이클** 은 컴포넌트가 생성되면서 종료될 때까지 진행되는 각 단계를 의미합니다.
각 단계마다 Angular는 컴포넌트를 렌더링하거나 갱신 내용을 화면에 반영하는 등 필요한 동작을 수행합니다.

이런 단계마다 어떤 코드를 실행하려면 **라이프사이클 훅(lifecycle hooks)** 를 구현하면 됩니다.
컴포넌트 인스턴스와 관련된 라이프사이클 훅은 컴포넌트 클래스 메서드로 구현합니다.
그리고 Angular 애플리케이션 전체와 관련된 라이프사이클 훅은 콜백 함수로 구현합니다.

컴포넌트 라이프사이클은 시간 흐름에 따라 Angular가 컴포넌트의 변경 사항을 확인하는 동작과 밀접하게 관련되어 있습니다.
라이프사이클 각 단계의 목적을 제대로 이해하려면 Angular가 애플리케이션 트리를 맨 윗단계부터 아래 방향으로 탐색하며 템플릿에 바인딩된 내용을 확인한다는 것을 명심하면 됩니다.
이렇게 변경 사항을 확인하는 동안 Angular는 전체 컴포넌트 트리를 순회하고, 필요한 단계마다 라이프사이클 함수가 실행됩니다.
이 작업이 진행되는 동안 Angular는 컴포넌트를 한 번만 확인하기 때문에, 변경사항이 반영되는 중에 상태를 다시 바꾸는 작업은 피해야 합니다.

## 요약

<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>생성</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">변화<br>감지</td>
      <td><code>ngOnInit</code>
      </td>
      <td>Angular가 컴포넌트의 입력 프로퍼티를 초기화한 이후 한 번 실행됩니다.</td>
    </tr>
    <tr>
      <td><code>ngOnChanges</code></td>
      <td>컴포넌트 입력 프로퍼티가 변경될 때마다 실행됩니다.</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>컴포넌트 컨텐츠의 변경 여부를 검사한 후 매번 실행됩니다.</td>
    </tr>
    <tr>
      <td><code>ngAfterViewInit</code></td>
      <td>컴포넌트의 <em>뷰(view)</em>가 초기화된 후 한 번 실행됩니다.</td>
    </tr>
    <tr>
      <td><code>ngAfterViewChecked</code></td>
      <td>컴포넌트 뷰의 변경 여부를 검사한 후 매번 실행됩니다.</td>
    </tr>
    <tr>
      <td rowspan="2">렌더링</td>
      <td><code>afterNextRender</code></td>
      <td>다음번에 모든 컴포넌트가 DOM에 렌더링된 후 한 번 실행됩니다.</td>
    </tr>
    <tr>
      <td><code>afterEveryRender</code></td>
      <td>모든 컴포넌트가 DOM에 렌더링될 때마다 실행됩니다.</td>
    </tr>
    <tr>
      <td>종료</td>
      <td><code>ngOnDestroy</code></td>
      <td>컴포넌트가 종료되기 전에 한 번 실행됩니다.</td>
    </tr>
  </table>
</div>

### ngOnInit

<!--
The `ngOnInit` method runs after Angular has initialized all the components inputs with their
initial values. A component's `ngOnInit` runs exactly once.

This step happens _before_ the component's own template is initialized. This means that you can
update the component's state based on its initial input values.
-->

`ngOnInit` 메서드는 Angular가 컴포넌트의 입력 프로퍼티를 초기값과 함께 초기화한 후에 실행됩니다.
이 함수는 한 번만 실행됩니다

이 메서드는 컴포넌트의 템플릿이 초기화되기 _전에_ 실행됩니다.
그래서 컴포넌트의 입력 프로퍼티 초기값이 템플릿에 반영되기 전에 값을 수정할 수 있습니다.

### ngOnChanges

<!--
The `ngOnChanges` method runs after any component inputs have changed.

This step happens _before_ the component's own template is checked. This means that you can update
the component's state based on its initial input values.

During initialization, the first `ngOnChanges` runs before `ngOnInit`.
-->

`ngOnChanges` 메서드는 컴포넌트의 입력 프로퍼티 값이 변경된 이후에 실행됩니다.

이 메서드는 컴포넌트 템플릿을 검사하기 _전에_ 실행됩니다.
그래서 컴포넌트의 입력 프로퍼티 값이 템플릿에 반영되기 전에 값을 수정할 수 있습니다.

컴포넌트 초기화 시점에는 `ngOnInit`이 실행되기 전에 첫번째 `ngOnChanges` 메서드가 실행됩니다.

#### 변경사항 확인하기

<!--
The `ngOnChanges` method accepts one `SimpleChanges` argument. This object is
a [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)
mapping each component input name to a `SimpleChange` object. Each `SimpleChange` contains the
input's previous value, its current value, and a flag for whether this is the first time the input
has changed.

You can optionally pass the current class or this as the first generic argument for stronger type checking.

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

If you provide an `alias` for any input properties, the `SimpleChanges` Record still uses the
TypeScript property name as a key, rather than the alias.
-->

`ngOnChanges` 메서드는 `SimpleChanges` 인자를 받습니다.
이 객체는 컴포넌트 입력 프로퍼티 이름마다 `SimpleChange` 객체로 값을 표현하는 [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) 객체입니다.
개별 `SimpleChange` 객체는 입력 프로퍼티의 이전 값과 현재값, 이 값이 처음 변경된 것인지 표시하는 플래그 값을 갖습니다.

타입 검사를 강화하려면 첫번째 제네릭 인자로 클래스를 전달할 수도 있습니다.

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

입력 프로퍼티에 `alias`를 지정했어도 `SimpleChange` 레코드는 TypeScript 프로퍼티 이름으로 키 값을 갖습니다.

### ngOnDestroy

`ngOnDestroy` 메서드는 컴포넌트가 종료되기 전에 한 번 실행됩니다.
Angular는 `@if` 등으로 컴포넌트가 화면에 표시되지 않을 때 인스턴스를 종료합니다.

#### DestroyRef

<!--
As an alternative to the `ngOnDestroy` method, you can inject an instance of `DestroyRef`. You can
register a callback to be invoked upon the component's destruction by calling the `onDestroy` method
of `DestroyRef`.

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

You can pass the `DestroyRef` instance to functions or classes outside your component. Use this
pattern if you have other code that should run some cleanup behavior when the component is
destroyed.

You can also use `DestroyRef` to keep setup code close to cleanup code, rather than putting
all cleanup code in the `ngOnDestroy` method.
-->

`ngOnDestroy` 메서드 대신 `DestroyRef` 인스턴스를 의존성 객체로 주입받아 활용할 수도 있습니다.
컴포넌트가 종료될 때 실행해야 하는 코드가 있다면 `DestroyRef`의 `onDestroy` 메서드로 등록하면 됩니다.

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

`DestroyRef` 인스턴스는 컴포넌트 밖에 있는 함수나 다른 클래스로 전달할 수 있습니다.
이 방식은 어떤 컴포넌트가 종료될 때 해당 컴포넌트 외부에서 무언가 실행해야 할 때 사용합니다.

그리고 컴포넌트를 종료하는 코드를 `ngOnDestroy` 메서드 밖에 두고 사용할 때도 활용할 수 있습니다.

##### 인스턴스 분해 감지하기

<!--
`DestroyRef` provides a `destroyed` property that allows checking whether a given instance has already been destroyed. This is useful for avoiding operations on destroyed components, especially when dealing with delayed or asynchronous logic.

By checking `destroyRef.destroyed`, you can prevent executing code after the instance has been cleaned up, avoiding potential errors such as `NG0911: View has already been destroyed.`.
-->

`DestroyRef` 객체의 `destroyed` 프로퍼티를 활용하면 인스턴스가 종료되었는지 확인할 수 있습니다.
이 프로퍼티는 특히 비동기 로직이 동작할 때 컴포넌트가 종료되었는지 확인해야 할 때 유용합니다.

`destroyRef.destroyed` 프로퍼티를 확인하면 인스턴스가 종료되었는지 확인할 수 있기 때문에, `NG0911: View has already been destroyed.` 오류를 사전에 방지할 수 있습니다.

### ngDoCheck

<!--
The `ngDoCheck` method runs before every time Angular checks a component's template for changes.

You can use this lifecycle hook to manually check for state changes outside of Angular's normal
change detection, manually updating the component's state.

This method runs very frequently and can significantly impact your page's performance. Avoid
defining this hook whenever possible, only using it when you have no alternative.

During initialization, the first `ngDoCheck` runs after `ngOnInit`.
-->

`ngDoCheck` 메서드는 Angular가 컴포넌트 템플릿의 변경 여부를 검사하기 전에 매번 실행됩니다.

이 메서드는 Angular의 일반적인 변경 감지 외에 컴포넌트 밖에서 상태가 변하는 것을 수동으로 감지하거나, 컴포넌트 상태를 수동으로 갱신해야 할 때 사용할 수 있습니다.

이 메서드는 아주 자주 실행되기 때문에 애플리케이션의 화면 렌더링 성능에 큰 영향을 줄 수 있습니다.
꼭 필요한 경우가 아니라면 이 메서드는 되도록 사용하지 않는 것이 좋습니다.

컴포넌트가 초기화될 때는 `ngOnInit`이 실행된 후에 첫번째 `ngDoCheck` 메서드가 실행됩니다.

### ngAfterContentInit

<!--
The `ngAfterContentInit` method runs once after all the children nested inside the component (its
_content_) have been initialized.

You can use this lifecycle hook to read the results of
[content queries](guide/components/queries#content-queries). While you can access the initialized
state of these queries, avoid changing non-signal state that an ancestor's template has already
rendered. Doing so can result in an
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).
-->

`ngAfterContentInit` 메서드는 컴포넌트 안에 있는 모든 자식 컴포넌트(컨텐츠)가 초기화된 후에 한 번 실행됩니다.

이 메서드는 [컨텐츠 쿼리](guide/components/queries#content-queries) 결과를 참조해야 할 때 활용합니다.
이 메서드에서는 초기화된 컨텐츠 쿼리의 상태를 참조할 수 있지만, 상위 컴포넌트의 템플릿이 이미 렌더링한 시그널이 아닌 상태를 변경하지 않도록 주의하세요.
이러한 상태를 변경하면 [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)가 발생할 수 있습니다.

### ngAfterContentChecked

<!--
The `ngAfterContentChecked` method runs every time the children nested inside the component (its
_content_) have been checked for changes.

This method runs very frequently and can significantly impact your page's performance. Avoid
defining this hook whenever possible, only using it when you have no alternative.

While you can access the updated state
of [content queries](guide/components/queries#content-queries) here, avoid changing non-signal
state that an ancestor's template has already rendered. Doing so can result in
an [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).
-->

`ngAfterContentChecked` 메서드는 컴포넌트 안에 중첩된 모든 자식 엘리먼트(컨텐츠)의 변경 여부를 검사한 후 매번 실행됩니다.

이 메서드에서는 [컨텐츠 쿼리](guide/components/queries#content-queries)의 갱신된 상태를 참조할 수 있지만, 상위 컴포넌트의 템플릿이 이미 렌더링한 시그널이 아닌 상태를 변경하지 않도록 주의하세요.
이러한 상태를 변경하면 [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)가 발생할 수 있습니다.

### ngAfterViewInit

<!--
The `ngAfterViewInit` method runs once after all the children in the component's template (its
_view_) have been initialized.

You can use this lifecycle hook to read the results of
[view queries](guide/components/queries#view-queries). While you can access the initialized state of
these queries, avoid changing non-signal state that a template has already rendered. Doing so can
result in an [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).
-->

`ngAfterViewInit` 메서드는 컴포넌트 템플릿 안에 있는 모든 자식 컴포넌트(뷰)가 초기화된 후에 한 번 실행됩니다.

이 메서드는 [뷰 쿼리](guide/components/queries#view-queries) 결과를 참조해야 할 때 활용합니다.
이 메서드에서는 초기화된 뷰 쿼리의 상태를 참조할 수 있지만, 템플릿이 이미 렌더링한 시그널이 아닌 상태를 변경하지 않도록 주의하세요.
이러한 상태를 변경하면 [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)가 발생할 수 있습니다.

### ngAfterViewChecked

<!--
The `ngAfterViewChecked` method runs every time the children in the component's template (its
_view_) have been checked for changes.

This method runs very frequently and can significantly impact your page's performance. Avoid
defining this hook whenever possible, only using it when you have no alternative.

While you can access the updated state of [view queries](guide/components/queries#view-queries)
here, avoid changing non-signal state that a template has already rendered. Doing so can result
in an [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100).
-->

`ngAfterViewChecked` 메서드는 컴포넌트 템플릿 안에 있는 모든 자식 엘리먼트(뷰)의 변경 여부를 검사한 후 매번 실행됩니다.

이 메서드에서는 [뷰 쿼리](guide/components/queries#view-queries)의 갱신된 상태를 참조할 수 있지만, 템플릿이 이미 렌더링한 시그널이 아닌 상태를 변경하지 않도록 주의하세요.
이러한 상태를 변경하면 [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)가 발생할 수 있습니다.

### afterEveryRender와 afterNextRender

<!--
The `afterEveryRender` and `afterNextRender` functions let you register a **render callback** to be
invoked after Angular has finished rendering _all components_ on the page into the DOM.

These functions are different from the other lifecycle hooks described in this guide. Rather than a
class method, they are standalone functions that accept a callback. The execution of render
callbacks are not tied to any specific component instance, but instead an application-wide hook.

`afterEveryRender` and `afterNextRender` must be called in
an [injection context](guide/di/dependency-injection-context), typically a
component's constructor.

You can use render callbacks to perform manual DOM operations.
See [Using DOM APIs](guide/components/dom-apis) for guidance on working with the DOM in Angular.

Render callbacks do not run during server-side rendering or during build-time pre-rendering.
-->

`afterEveryRender` 함수와 `afterNextRender` 함수는 Angular가 화면에 표시되는 _모든 컴포넌트_ 를 DOM에 렌더링한 후에 **렌더링 콜백** 으로 실행됩니다.

이 메서드는 다른 라이프사이클 훅과는 조금 다릅니다.
이 문서에서 다루는 라이프사이클 훅은 모두 클래스 메서드로 사용하지만, `afterEveryRender` 함수와 `afterNextRender` 함수는 단독 함수로 등록합니다.
그래서 이때 등록되는 콜백 함수는 특정 컴포넌트 인스턴스와 연관되지 않으며, 애플리케이션 전역 후킹 함수가 됩니다.

`afterEveryRender` 함수와 `afterNextRender` 함수는 반드시 [의존성 주입 컨텍스트](guide/di/dependency-injection-context) 안에서 실행해야 하기 때문에, 일반적으로 컴포넌트의 생성자에서 실행합니다.

렌더링 콜백 함수는 DOM을 수동으로 조작해야 할 때도 활용할 수 있습니다.
Angular에서 DOM을 조작하는 방법은 [DOM API 활용하기](guide/components/dom-apis) 문서를 참고하세요.

렌더링 콜백 함수는 서버 사이드 렌더링이나 빌드 시점의 사전 렌더링 시점에는 실행되지 않습니다.

#### after\*Render 단계

<!--
When using `afterEveryRender` or `afterNextRender`, you can optionally split the work into phases. The
phase gives you control over the sequencing of DOM operations, letting you sequence _write_
operations before _read_ operations in order to minimize
[layout thrashing](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing). In order to
communicate across phases, a phase function may return a result value that can be accessed in the
next phase.

```ts
import {Component, ElementRef, afterNextRender, inject} 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;
        }
      },
    });
  }
}
```

There are four phases, run in the following order:

| Phase            | Description                                                                                                                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `earlyRead`      | Use this phase to read any layout-affecting DOM properties and styles that are strictly necessary for subsequent calculation. Avoid this phase if possible, preferring the `write` and `read` phases. |
| `write`          | Use this phase to write layout-affecting DOM properties and styles.                                                                                                                                   |
| `mixedReadWrite` | Default phase. Use for any operations need to both read and write layout-affecting properties and styles. Avoid this phase if possible, preferring the explicit `write` and `read` phases.            |
| `read`           | Use this phase to read any layout-affecting DOM properties.                                                                                                                                           |
-->

`afterEveryRender` 함수와 `afterNextRender` 함수를 사용할 때 실행되는 과정은 단계별로 나눠볼 수 있습니다.
각 단계에 해당하는 DOM 작업을 실행할 수 있으며, _쓰기_ 작업을 _읽기_ 작업 전에 실행해서 [레이아웃 스래싱(layout thrashing)](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing)을 최소화할 수 있습니다.
각 단계마다 실행되는 함수는 해당 단계에서 실행된 결과값을 반환하며, 다음 단계에 실행되는 함수는 이전 단계에서 실행된 결과값을 받아 참조할 수 있습니다.

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

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

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

afterNextRender({
      // 엘리먼트의 위치정보를 참조하기 위해 `write` 단계를 활용합니다.
      write: () => {
        const padding = computePadding();
        const changed = padding !== this.prevPadding;
        if (changed) {
          nativeElement.style.padding = padding;
        }
        return changed; // 다음 단계로 정보를 전달합니다.
      },

// 쓰기 작업이 전부 완료된 후에 엘리먼트의 위치정보를 참조하기 위해 `read` 단계를 활용합니다.
      read: (didWrite) => {
        if (didWrite) {
          this.elementHeight = nativeElement.getBoundingClientRect().height;
        }
      },
    });
  }
}
```

전체 과정은 4단계로 진행됩니다:

| 단계             | 설명                                                                                                                                                                                            |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `earlyRead`      | 다음 단계에서 필요한 DOM 속성과 스타일 값을 읽을 때 사용합니다. 가능하다면, 이 단계를 생략하고 `write` 단계와 `read` 단계를 활용하는 것이 좋습니다.                                             |
| `write`          | 레이아웃 DOM 프로퍼티나 스타일 값을 설정할 때 사용합니다.                                                                                                                                       |
| `mixedReadWrite` | 기본 단계입니다. 레이아웃에 영향을 주는 프로퍼티와 스타일을 읽고 쓰는 작업을 모두 수행해야 할 때 사용합니다. 가능하다면 이 단계를 생략하고 `write` 단계와 `read` 단계를 활용하는 것이 좋습니다. |
| `read`           | 레이아웃 DOM 프로퍼티를 읽을 때 사용합니다.                                                                                                                                                     |

## 라이프사이클 인터페이스

<!--
Angular provides a TypeScript interface for each lifecycle method. You can optionally import
and `implement` these interfaces to ensure that your implementation does not have any typos or
misspellings.

Each interface has the same name as the corresponding method without the `ng` prefix. For example,
the interface for `ngOnInit` is `OnInit`.

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

Angular는 각 라이프사이클 훅에 해당하는 TypeScript 인터페이스를 제공합니다.
필요하면 이 인터페이스를 가져와 클래스에서 구현할 수 있습니다.
인터페이스를 구현하면 메서드 이름의 오타를 타입 검사로 확인할 수 있습니다.

인터페이스 이름에 `ng` 접두사를 붙여서 메서드를 구현하면 됩니다.
`OnInit` 인터페이스에 해당하는 메서드는 `ngOnInit` 메서드가 되는 식입니다.

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

## 실행 순서

Angular 라이프사이클 훅은 다음 순서대로 실행됩니다.

### 컴포넌트 생성 시점

```mermaid
graph TD;
id[constructor]-->CHANGE;
subgraph CHANGE [변화 감지]
direction TB
ngOnChanges-->ngOnInit;
ngOnInit-->ngDoCheck;
ngDoCheck-->ngAfterContentInit;
ngDoCheck-->ngAfterViewInit
ngAfterContentInit-->ngAfterContentChecked
ngAfterViewInit-->ngAfterViewChecked
end
CHANGE--렌더링-->afterNextRender-->afterEveryRender
```

### 값이 변경될 때

```mermaid
graph TD;
subgraph CHANGE [변화 감지]
direction TB
ngOnChanges-->ngDoCheck
ngDoCheck-->ngAfterContentChecked;
ngDoCheck-->ngAfterViewChecked
end
CHANGE--렌더링-->afterEveryRender
```

### 디렉티브가 함께 사용된 경우

컴포넌트의 호스트 엘리먼트에 디렉티브가 있거나, `hostDirectives` 프로퍼티를 활용하는 경우는 컴포넌트와 디렉티브의 라이프사이클 훅의 실행 순서를 보장하지 않습니다.
또한, 이 순서는 이후 Angular 버전에서 변경될 수 있기 때문에, 실행 순서에 영향을 받는 로직을 작성하지 마세요.

컴포넌트 템플릿은 단순한 정적 HTML이 아닙니다.
컴포넌트 템플릿은 컴포넌트 클래스에 있는 데이터를 불러오거나 사용자의 동작을 감지하는 핸들러에 반응합니다.

## 동적 텍스트 표시하기

<!--
In Angular, a _binding_ creates a dynamic connection between a component's template and its data. This connection ensures that changes to the component's data automatically update the rendered template.

You can create a binding to show some dynamic text in a template by using double curly-braces:

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

When Angular renders the component, you see:

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

Angular automatically keeps the binding up-to-date when the value of the signal changes. Building on
the example above, if we update the value of the `userName` signal:

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

The rendered page updates to reflect the new value:

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

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

## 동적 프로퍼티, 동적 어트리뷰트 연결하기

<!--
Angular supports binding dynamic values into DOM properties with square brackets:

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

You can also bind to HTML _attributes_ by prefixing the attribute name with `attr.`:

```html
<!- Bind the `role` attribute on the `<ul>` element to value of `listRole`. ->
<ul [attr.role]="listRole()"></ul>
```

Angular automatically updates DOM properties and attributes when the bound value changes.
-->

대괄호(`[`, `]`)를 사용하면 DOM 프로퍼티를 동적으로 바인딩할 수 있습니다:

```typescript
@Component({
  /*...*/
  // `isValidUserId` 시그널 값에 따라 `disabled` 프로퍼티 값을 설정합니다.
  template: `<button [disabled]="!isValidUserId()">Save changes</button>`,
})
export class UserProfile {
  isValidUserId = signal(false);
}
```

그리고 `attr.` 접두사를 붙이면 HTML _어트리뷰트_ 를 바인딩할 수 있습니다:

```html

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

바인딩된 값이 변경되면 Angular가 DOM 프로퍼티와 어트리뷰트를 자동으로 갱신합니다.

## 사용자 입력 처리하기

<!--
Angular lets you add event listeners to an element in your template with parentheses:

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

If you need to pass the [event](https://developer.mozilla.org/docs/Web/API/Event) object to your listener, you can use Angular's built-in `$event` variable inside the function call:

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

템플릿 엘리먼트에 소괄호(`(`, `)`)를 사용하면 이벤트 리스너를 추가할 수 있습니다:

```typescript
@Component({
  /*...*/
  // `cancelSubscription` 메서드를 실행하는 `click` 이벤트 핸들러를 추가합니다.
  template: `<button (click)="cancelSubscription()">Cancel subscription</button>`,
})
export class UserProfile {
  /* ... */

cancelSubscription() {
    /* 이벤트를 처리하는 코드는 여기에 작성합니다. */
  }
}
```

[이벤트](https://developer.mozilla.org/docs/Web/API/Event) 객체를 이벤트 핸들러로 보내려면, 이벤트 핸들러 메서드를 실행하면서 Angular가 기본으로 제공하는 `$event` 변수를 전달하면 됩니다:

```typescript
@Component({
  /*...*/
  // `cancelSubscription` 메서드를 실행하는 `click` 이벤트 핸들러를 추가합니다.
  template: `<button (click)="cancelSubscription($event)">Cancel subscription</button>`,
})
export class UserProfile {
  /* ... */

cancelSubscription(event: Event) {
    /* 이벤트를 처리하는 코드는 여기에 작성합니다. */
  }
}
```

## `@if`와 `@for`로 흐름 제어하기

`@if` 블록을 사용하면 템플릿의 특정 영역을 표시하거나 감출 수 있습니다:

```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` 블록을 사용하면 됩니다:

```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 uses the `track` keyword, shown in the example above, to associate data with the DOM elements created by `@for`. See [_Why is track in @for blocks important?_](guide/templates/control-flow#why-is-track-in-for-blocks-important) for more info.

TIP: Want to know more about Angular templates? See the [In-depth Templates guide](guide/templates) for the full details.
-->

위 예제에서 `@for` 문으로 DOM에서 반복되는 개별 객체를 구분하기 위해 `track` 키워드를 사용합니다.
자세한 내용은 [_왜 @for 블록에 track이 중요한가요?_](guide/templates/control-flow#why-is-track-in-for-blocks-important) 문서를 참고하세요.

팁: 템플릿을 더 자세하게 알아보고 싶은가요? 그렇다면 [템플릿 심화 가이드](guide/templates) 문서를 참고하세요.

## 다음 단계

이제 동적 데이터와 템플릿을 연결하는 방법을 알아봤습니다.
그리고 조건에 따라 템플릿의 특정 부분을 표시하거나, 표시하지 않는 방법을 알아봤고 어떤 템플릿 부분을 반복하는 방법을 알아봤습니다.

# 이벤트 리스너 추가하기

Angular를 활용하면 템플릿에 있는 엘리먼트에서 발생하는 이벤트를 감지하고 이벤트가 발생할 때마다 실행되는 이벤트 리스너를 정의해서 연결할 수 있습니다.

## 기본 이벤트 감지하기

<!--
When you want to add event listeners to an HTML element, you wrap the event with parentheses, `()`, which allows you to specify a listener statement.

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

In this example, Angular calls `updateField` every time the `<input>` element emits a `keyup` event.

You can add listeners for any native events, such as: `click`, `keydown`, `mouseover`, etc. To learn more, check out the [all available events on elements on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element#events).
-->

HTML 엘리먼트에서 발생하는 이벤트를 감지하려면, 이벤트 이름을 괄호(`(`, `)`)로 감싸고 리스너 실행문을 연결하면 됩니다.

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

위 코드처럼 구현하면 `<input>` 엘리먼트에서 `keyup` 이벤트가 발생할 때마다 Angular는 `updateField()` 함수를 실행합니다.

`click`, `keydown`, `mouseover` 등 HTML이 기본으로 지원하는 이벤트는 이렇게 간단하게 이벤트 리스너와 연결할 수 있습니다.
더 자세한 내용은 [엘리먼트에서 발생하는 이벤트 목록](https://developer.mozilla.org/en-US/docs/Web/API/Element#events) 문서를 참고하세요.

## 이벤트 객체 접근하기

<!--
In every template event listener, Angular provides a variable named `$event` that contains a reference to the event object.

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

템플릿에서 이벤트 리스너를 연결할 때 Angular가 제공하는 `$event` 변수를 사용하면 이벤트 객체를 참조할 수 있습니다.

## 특정 키에만 반응하기 {#using-key-modifiers}

<!--
When you want to capture specific keyboard events for a specific key, you might write some code like the following:

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

However, since this is a common scenario, Angular lets you filter the events by specifying a specific key using the period (`.`) character. By doing so, code can be simplified to:

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

You can also add additional key modifiers:

```html
<!- Matches shift and enter ->
<input type="text" (keyup.shift.enter)="updateField($event)" />
```

Angular supports the modifiers `alt`, `control`, `meta`, and `shift`.

You can specify the key or code that you would like to bind to keyboard events. The key and code fields are a native part of the browser keyboard event object. By default, event binding assumes you want to use the [Key values for keyboard events](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values).

Angular also allows you to specify [Code values for keyboard events](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_code_values) by providing a built-in `code` suffix.

```html
<!- Matches alt and left shift ->
<input type="text" (keydown.code.alt.shift.shiftleft)="updateField($event)" />
```

This can be useful for handling keyboard events consistently across different operating systems. For example, when using the Alt key on macOS devices, the `key` property reports the key based on the character already modified by the Alt key. This means that a combination like Alt + S reports a `key` value of `'ß'`. The `code` property, however, corresponds to the physical or virtual button pressed rather than the character produced.
-->

키보드 이벤트 중 특정 키를 감지해야 할 때는 다음과 같이 구현하면 됩니다:

이 방식도 좋지만, Angular는 키보드 이벤트 이름에 마침표(`.`)를 붙인 후 원하는 키만 감지할 수도 있습니다.
그러면 코드가 더 간단해집니다:

여러 키를 조합하는 경우는 이렇게 구현합니다:

```html

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

Angular는 `alt`, `control`, `meta`, `shift` 키조합도 지원합니다.

키보드 이벤트는 키 이름이나 코드를 사용해서 바인딩할 수 있습니다.
키 값이나 코드 값은 브라우저 키보드 이벤트 객체를 기반으로 하며, [키보드 이벤트의 키 값](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values)을 따른다고 가정합니다.

Angular에서는 `code` 접미사를 사용해서 [키보드 이벤트의 코드 값](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_code_values)을 활용할 수도 있습니다.

```html

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

이 방식은 운영체제와 관계없이 키보드 이벤트를 다뤄야 할 때 유용합니다.
예를 들면, MacOS 장치에서 Alt 키는 기능키가 아니라 다른 문자셋을 입력하는 것으로 동작합니다.
그래서 Alt + S 라고 지정하면 `'ß'` 문자를 감지합니다.
하지만 `code` 프로퍼티를 사용하는 경우에는 문자셋과 관계없이 실제로 눌린 키조합에 반응합니다.

## 전역 이벤트 감지하기

<!--
Global target names can be used to prefix an event. The 3 supported global targets are `window`, `document` and `body`.

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

전역 이벤트는 이벤트 이름 앞에 접두사를 붙여서 감지할 수 있습니다.
지원하는 전역 대상은 `window`, `document`, `body` 입니다.

## 이벤트의 기본 동작 막기

<!--
If your event handler should replace the native browser behavior, you can use the event object's [`preventDefault` method](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!');
  }
}
```

If the event handler statement evaluates to `false`, Angular automatically calls `preventDefault()`, similar to [native event handler attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes). _Always prefer explicitly calling `preventDefault`_, as this approach makes the code's intent obvious.
-->

이벤트 핸들러를 실행하면서 브라우저의 기본 동작을 중단해야 한다면 이벤트 객체의 [`preventDefault` 메서드](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault)를 실행하면 됩니다:

Angular에서는 [기본 이벤트 핸들러 어트리뷰트](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes)와 비슷하게, 이벤트 핸들러 실행문이 `false`로 평가되면 `preventDefault()`를 자동으로 실행합니다.
_`preventDefault()` 실행이 필요한 경우라면 반드시 명시적으로 이 메서드를 실행하세요._
그래야 코드의 의도가 명확해집니다.

## 이벤트 핸들링 확장하기

Angular 이벤트 처리 시스템은 커스텀 이벤트 플러그인을 `EVENT_MANAGER_PLUGINS` 의존성 토큰으로 등록해서 확장할 수 있습니다.

### 이벤트 플러그인 구현하기

<!--
To create a custom event plugin, extend the `EventManagerPlugin` class and implement the required methods.

```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, , delay = '300'] = eventName.split('.');

let timeoutId: ReturnType<typeof setTimeout>;

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

element.addEventListener(event, listener);

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

```ts
import {bootstrapApplication, 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,
    },
  ],
});
```

Once registered, you can use your custom event syntax in templates, as well as with the `host` property:

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

커스텀 이벤트 플러그인을 만들려면 `EventManagerPlugin` 클래스를 상속받아 필수 메서드를 구현하면 됩니다.

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

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

// 플러그인이 처리할 이벤트를 지정합니다.
  override supports(eventName: string) {
    return /debounce/.test(eventName);
  }

// 이벤트 리스너를 등록합니다.
  override addEventListener(element: HTMLElement, eventName: string, handler: Function) {
    // 이벤트를 파싱합니다:
    // "click.debounce.500" -> event: "click", delay: 500
    const [event, , delay = '300'] = eventName.split('.');

let timeoutId: ReturnType<typeof setTimeout>;

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

element.addEventListener(event, listener);

// 정리 함수를 반환합니다.
    return () => {
      clearTimeout(timeoutId);
      element.removeEventListener(event, listener);
    };
  }
}
```

이후에는 애플리케이션의 프로바이더 목록에 `EVENT_MANAGER_PLUGINS` 토큰과 커스텀 플러그인을 등록하면 됩니다.

```ts
import {bootstrapApplication, 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` 프로퍼티를 활용해도 됩니다:

# 문자열, 프로퍼티, 어트리뷰트를 동적으로 바인딩하기

**바인딩(binding)** 은 컴포넌트의 템플릿과 데이터를 연결하는 것을 의미합니다.
템플릿과 데이터를 바인딩하고 나면, 컴포넌트 데이터가 변경되더라도 템플릿에 언제나 최신 정보가 갱신됩니다.

## 문자열 바인딩

<!--
You can bind dynamic text in templates with double curly braces, which tells Angular that it is responsible for the expression inside and ensuring it is updated correctly. This is called **text interpolation**.

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

In this example, when the snippet is rendered to the page, Angular will replace `{{ theme }}` with `dark`.

```html
<!- Rendered Output ->
<p>Your color preference is dark.</p>
```

Bindings that change over time should read values from [signals](/guide/signals). Angular tracks the signals read in the template, and updates the rendered page when those signal values change.

```typescript
@Component({
  template: `
    <!- Does not necessarily update when `welcomeMessage` changes. ->
    <p>{{ welcomeMessage }}</p>

<p>Your color preference is {{ theme() }}.</p> <!- Always updates when the value of the `theme` signal changes. ->
`
...
})
export class App {
welcomeMessage = "Welcome, enjoy this app that we built for you";
theme = signal('dark');
}
```

For more details, see the [Signals guide](/guide/signals).

Continuing the theme example, if a user clicks on a button that updates the `theme` signal to `'light'` after the page loads, the page updates accordingly to:

```html
<!- Rendered Output ->
<p>Your color preference is light.</p>
```

You can use text interpolation anywhere you would normally write text in HTML.

Expression values are converted to a string. `null` and `undefined` render as an empty string. Objects and arrays are converted using the value’s `toString` method.
-->

문자열을 바인딩하려면 이중 중괄호(`{{`, `}}`)를 사용하고 괄호 안에 표현식을 작성하면 됩니다.

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

시간이 경과하며 값이 변경된다면 [시그널](/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');
}
```

자세한 내용은 [시그널 문서](/guide/signals)를 참고하세요.

예시를 좀 더 보면, 화면이 표시된 후에 사용자가 버튼을 클릭하면 `theme` 시그널이 `'light'` 값으로 변경됩니다:

```html

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

HTML에 문자열을 표시하고 싶은 곳이라면 어느 곳에든 문자열 바인딩을 활용할 수 있습니다.

문자열 바인딩 표현식의 값은 문자열 타입으로 변환됩니다.
`null`과 `undefined`는 빈 문자열로 렌더링됩니다.
표현식의 결과가 객체나 배열이라면 `toString()` 메서드 실행 결과가 사용됩니다.

## 동적 프로퍼티, 어트리뷰트 바인딩

<!--
Angular supports binding dynamic values into object properties and HTML attributes with square brackets.

You can bind to properties on an HTML element's DOM instance, a [component](/guide/components) instance, or a [directive](/guide/directives) instance.
-->

대괄호(`[`, `]`)를 사용하면 객체 프로퍼티와 HTML 어트리뷰트를 바인딩할 수 있습니다.

이때 프로퍼티는 HTML 엘리먼트의 DOM 인스턴스이거나, [컴포넌트](guide/components) 인스턴스이거나, [디렉티브](guide/directives) 인스턴스일 수 있습니다.

### 기본 엘리먼트 프로퍼티

<!--
Every HTML element has a corresponding DOM representation. For example, each `<button>` HTML element corresponds to an instance of `HTMLButtonElement` in the DOM. In Angular, you use property bindings to set values directly to the DOM representation of the element.

```html
<!- Bind the `disabled` property on the button element's DOM object ->
<button [disabled]="isFormValid()">Save</button>
```

In this example, every time `isFormValid` changes, Angular automatically sets the `disabled` property of the `HTMLButtonElement` instance.
-->

HTML 엘리먼트는 DOM 표현과 연결됩니다.
예를 들어 `<button>` HTML 엘리먼트는 DOM에서 `HTMLButtonElement` 인스턴스와 대응됩니다.
Angular 측면에서 보면, 프로퍼티와 바인딩된 값은 엘리먼트의 DOM 인스턴스와 직접 연결됩니다.

```html

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

이렇게 구현하면 `isFormValid` 값이 변경될 때마다 Angular가 자동으로 `HTMLButtonElement` 인스턴스에 있는 `disabled` 프로퍼티 값을 변경합니다.

### 컴포넌트와 디렉티브 프로퍼티

<!--
When an element is an Angular component, you can use property bindings to set component input properties using the same square bracket syntax.

```html
<!- Bind the `value` property on the `MyListbox` component instance. ->
<my-listbox [value]="mySelection()" />
```

In this example, every time `mySelection` changes, Angular automatically sets the `value` property of the `MyListbox` instance.

You can bind to directive properties as well.

```html
<!- Bind to the `ngSrc` property of the `NgOptimizedImage` directive  ->
<img [ngSrc]="profilePhotoUrl()" alt="The current user's profile photo" />
```
-->

바인딩하려는 프로퍼티가 Angular 컴포넌트라면, 대괄호를 사용하는 프로퍼티 바인딩은 컴포넌트의 입력 프로퍼티와 바인딩됩니다.

```html

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

이렇게 구현하면 `mySelection` 값이 변경될 때마다 Angular가 자동으로 `MyListbox` 인스턴스의 `value` 프로퍼티 값을 변경합니다.

디렉티브도 같은 방식으로 바인딩됩니다.

```html

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

### 어트리뷰트

<!--
When you need to set HTML attributes that do not have corresponding DOM properties, such as SVG attributes, you can bind attributes to elements in your template with the `attr.` prefix.

<!- prettier-ignore ->
```html
<!- Bind the `role` attribute on the `<ul>` element to the component's `listRole` property. ->
<ul [attr.role]="listRole()">
```

In this example, every time `listRole` changes, Angular automatically sets the `role` attribute of the `<ul>` element by calling `setAttribute`.

If the value of an attribute binding is `null` or `undefined`, Angular removes the attribute by calling `removeAttribute`.
-->

SVG 어트리뷰트와 같이 연관된 DOM 프로퍼티가 존재하지 않는 경우에는 템플릿 엘리먼트에 `attr.` 접두사를 붙여서 어트리뷰트와 바인딩할 수 있습니다.

```html

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

이렇게 구현하면 `listRole` 값이 변경될 때마다 Angular가 자동으로 `<ul>` 엘리먼트의 `setAttribute`를 실행해서 `role` 어트리뷰트 값을 변경합니다.

이때 어트리뷰트에 바인딩되는 값이 `null`이나 `undefined`이면, Angular가 `removeAttribute`를 실행해서 어트리뷰트를 제거합니다.

### 프로퍼티와 어트리뷰트를 바인딩할 때 문자열 바인딩

<!--
You can also use text interpolation syntax in properties and attributes by using the double curly brace syntax instead of square braces around the property or attribute name. When using this syntax, Angular treats the assignment as a property binding.

```html
<!- Binds a value to the `alt` property of the image element's DOM object. ->
<img src="profile-photo.jpg" alt="Profile photo of {{ firstName() }}" />
```
-->

프로퍼티나 어트리뷰트 이름에 대괄호를 사용하는 대신 이중 중괄호를 사용하면 프로퍼티나 어트리뷰트에 문자열 바인딩을 연결할 수 있습니다.

```html

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

## CSS 클래스 바인딩, 스타일 프로퍼티 바인딩

Angular는 CSS 클래스 바인딩과 CSS 스타일 프로퍼티 바인딩도 지원합니다.

### CSS 클래스

<!--
You can create a CSS class binding to conditionally add or remove a CSS class on an element based on whether the bound value is [truthy or falsy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy).

<!- prettier-ignore ->
```html
<!- When `isExpanded` is truthy, add the `expanded` CSS class. ->
<ul [class.expanded]="isExpanded()">
```

You can also bind directly to the `class` property. Angular accepts three types of value:

| Description of `class` value                                                                                                                                      | TypeScript type       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| A string containing one or more CSS classes separated by spaces                                                                                                   | `string`              |
| An array of CSS class strings                                                                                                                                     | `string[]`            |
| An object where each property name is a CSS class name and each corresponding value determines whether that class is applied to the element, based on 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,
  });
}
```

The above example renders the following DOM:

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

Angular splits a string value on whitespace and ignores empty strings.

When using static CSS classes, directly binding `class`, and binding specific classes, Angular intelligently combines all of the classes in the rendered result.

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

In the example above, Angular renders the `ul` element with all three CSS classes.

<!- prettier-ignore ->
```html
<ul class="list box expanded">
```

Angular does not guarantee any specific order of CSS classes on rendered elements.

When binding `class` to an array or an object, Angular compares the previous value to the current value with the triple-equals operator (`===`). You must create a new object or array instance when you modify these values in order for Angular to apply any updates.

If an element has multiple bindings for the same CSS class, Angular resolves collisions by following its style precedence order.

NOTE: Class bindings do not support space-separated class names in a single key. They also don't support mutations on objects as the reference of the binding remains the same. If you need one or the other, use the [ngClass](/api/common/NgClass) directive.
-->

바인딩되는 값이 [참인지, 거짓인지](https://developer.mozilla.org/en-US/docs/Glossary/Truthy)에 따라 CSS 클래스를 조건부로 적용할 수 있습니다.

```html

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

`class` 프로퍼티를 직접 바인딩하는 방법도 있습니다.
이 경우 세 가지 타입을 사용할 수 있습니다:

| `class` 값 설명                                                                     | TypeScript 타입       |
| ----------------------------------------------------------------------------------- | --------------------- |
| 띄어쓰기로 구분하는 1개 이상의 CSS 클래스 문자열                                    | `string`              |
| CSS 클래스 문자열의 배열                                                            | `string[]`            |
| 프로퍼티 이름을 CSS 클래스 이름으로 하고, 개별 값이 참으로 평가되는지 표현하는 객체 | `Record<string, any>` |

위 코드처럼 구현하면 DOM은 다음과 같이 렌더링됩니다:

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

Angular는 문자열 값을 공백으로 나누고 빈 문자열은 무시합니다.

정적 CSS 클래스를 사용하거나 `class`를 직접 바인딩하거나, 특정 클래스를 바인딩하는 경우가 겹치면 Angular는 지능적으로 결과를 조합합니다.

위 코드처럼 구현하면 Angular는 `ul` 엘리먼트에 3개의 CSS 클래스를 모두 적용합니다.

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

엘리먼트에 CSS 클래스가 적용되는 순서는 보장하지 않습니다.

`class`를 바인딩하면서 배열이나 객체를 사용한 경우에는, Angular가 이전 값과 현재 값을 동등 연산자(`===`)로 비교합니다.
그래서 객체나 배열 내부의 값이 변경되었다면 새 객체와 새 배열을 사용해야 변경사항이 제대로 반영됩니다.

엘리먼트에 같은 CSS가 여러 번 바인딩되면, 우선순위에 따라 충돌을 해결합니다.

참고: 클래스 바인딩은 키 하나에 공백으로 구분되는 여러 개 클래스 이름을 지정할 수 없습니다.
그리고 바인딩 객체의 참조가 동일하게 유지되기 때문에 객체 변경도 지원하지 않습니다.
둘 중 하나가 필요한 경우에는 [ngClass](/api/common/NgClass) 디렉티브를 사용하세요.

### CSS 스타일 프로퍼티

<!--
You can also bind to CSS style properties directly on an element.

<!- prettier-ignore ->
```html
<!- Set the CSS `display` property based on the `isExpanded` property. ->
<section [style.display]="isExpanded() ? 'block' : 'none'">
```

You can further specify units for CSS properties that accept units.

<!- prettier-ignore ->
```html
<!- Set the CSS `height` property to a pixel value based on the `sectionHeightInPixels` property. ->
<section [style.height.px]="sectionHeightInPixels()">
```

You can also set multiple style values in one binding. Angular accepts the following types of value:

| Description of `style` value                                                                                              | TypeScript type       |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| A string containing zero or more CSS declarations, such as `"display: flex; margin: 8px"`.                                | `string`              |
| An object where each property name is a CSS property name and each corresponding value is the value of that CSS property. | `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',
  });
}
```

The above example renders the following DOM.

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

When binding `style` to an object, Angular compares the previous value to the current value with the triple-equals operator (`===`). You must create a new object instance when you modify these values in order for Angular to apply any updates.

If an element has multiple bindings for the same style property, Angular resolves collisions by following its style precedence order.
-->

엘리먼트에 CSS 스타일 프로퍼티를 직접 바인딩할 수도 있습니다.

```html

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

이때 단위를 함께 지정할 수 있습니다.

```html

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

바인딩 구문 하나에 여러 스타일을 바인딩할 수도 있습니다.
이 경우 세 가지 타입을 사용할 수 있습니다:

| `style` 값 설명                                                                   | TypeScript 타입       |
| --------------------------------------------------------------------------------- | --------------------- |
| `"display: flex; margin: 8px"`와 같은 CSS 선언 문자열                             | `string`              |
| 프로퍼티 이름을 CSS 프로퍼티 이름으로 하고, 개별 값이 해당 CSS 프로퍼티 값인 객체 | `Record<string, any>` |

위 코드처럼 구현하면 DOM은 다음과 같이 렌더링됩니다:

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

`style`에 객체를 바인딩하면 Angular는 이전값과 현재값을 동등 연산자(`===`)로 비교합니다.
그래서 객체 내부의 값이 변경되었다면 새 객체를 사용해야 변경사항이 제대로 반영됩니다.

엘리먼트에 같은 스타일 프로퍼티가 여러 번 바인딩되면, 우선순위에 따라 충돌을 해결합니다.

## ARIA 어트리뷰트

<!--
Angular supports binding string values to ARIA attributes.

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

Angular writes the string value to the element’s `aria-label` attribute and removes it when the bound value is `null` or `undefined`.

Some ARIA features expose DOM properties or directive inputs that accept structured values (such as element references). Use standard property bindings for those cases. See the [accessibility guide](/best-practices/a11y#aria-attributes-and-properties) for examples and additional guidance.
-->

ARIA 어트리뷰트에 문자열을 바인딩할 수 있습니다.

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

Angular는 바인딩된 값에 따라 해당 문자열을 엘리먼트의 `aria-label` 어트리뷰트에 지정하고, 바인딩된 값이 `null`이나 `undefined`이면 어트리뷰트를 제거합니다.

일부 ARIA 기능은 엘리먼트 참조와 같이 어떤 형식을 요구하는 경우가 있습니다.
이런 경우는 일반적인 프로퍼티 바인딩을 사용하세요.
자세한 내용은 [접근성 가이드](best-practices/a11y#aria-attributes-and-properties)에서 예제와 함께 확인할 수 있습니다.

# 흐름 제어

Angular 템플릿은 조건에 따라 엘리먼트를 표시하거나, 감추거나, 반복하는 흐름 제어 블록 기능을 제공합니다.

## 조건에 따라 표시하기: `@if`, `@else-if`, `@else`

<!--
The `@if` block conditionally displays its content when its condition expression is truthy:

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

If you want to display alternative content, you can do so by providing any number of `@else if` blocks and a singular `@else` block.

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

`@if` 블록은 표현식 결과가 참으로 평가될 때 내용물을 표시합니다:

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

### 표현식 계산 결과를 변수로 저장하기

<!--
The `@if` conditional supports saving the result of the conditional expression into a variable for reuse inside of the block.

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

This can be useful for referencing longer expressions that would be easier to read and maintain within the template.
-->

`@if` 블록에서 조건문 판단에 사용한 데이터는 블록 안쪽에서 재사용할 수 있도록 변수로 할당해 둘 수 있습니다.

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

조건문에 사용하는 표현식이 길다면 이 방식이 유용합니다.

## 내용 반복하기: `@for`

<!--
The `@for` block loops through a collection and repeatedly renders the content of a block. The collection can be any JavaScript [iterable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols), but Angular has additional performance optimizations for `Array` values.

A typical `@for` loop looks like:

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

Angular's `@for` block does not support flow-modifying statements like JavaScript's `continue` or `break`.
-->

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

Angular `@for` 블록은 JavaScript의 `continue`나 `break` 같이 흐름을 제어하는 구문은 지원하지 않습니다.

### `@for` 블록을 사용할 때 왜 `track`을 지정해야 하나요?

<!--
The `track` expression allows Angular to maintain a relationship between your data and the DOM nodes on the page. This allows Angular to optimize performance by executing the minimum necessary DOM operations when the data changes.

Using track effectively can significantly improve your application's rendering performance when looping over data collections.

Select a property that uniquely identifies each item in the `track` expression. If your data model includes a uniquely identifying property, commonly `id` or `uuid`, use this value. If your data does not include a field like this, strongly consider adding one.

For static collections that never change, you can use `$index` to tell Angular to track each item by its index in the collection.

If no other option is available, you can use the item itself as a tracking key. This tells Angular to track the item by its reference identity using the triple-equals operator (`===`). Avoid this option whenever possible as it can lead to significantly slower rendering updates, as Angular has no way to map which data item corresponds to which DOM nodes.

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

NOTE: Unlike `*ngFor`, the `@for` block prioritizes view reuse. If a tracked property changes but the object reference remains the same, Angular updates the view's bindings (including component inputs) rather than destroying and recreating the entire element.
-->

`track` 표현식은 Angular가 데이터와 DOM 노드의 관계를 파악하는 용도로 사용합니다.
Angular가 이 관계를 파악할 수 있으면 데이터가 변경되었을 때 DOM 연산을 최소화하면서 성능을 최적화할 수 있습니다.

그래서 데이터 콜렉션을 반복할 때 애플리케이션의 렌더링 성능을 최적화하려면 `track` 구문을 효율적으로 작성해야 합니다.

`track` 표현식에는 개별 항목을 고유하게 구분할 수 있는 필드를 지정하세요.
보통은 `id`나 `uuid`와 같은 값을 사용할 것입니다.
고유하게 식별할 수 있는 필드가 없다면, 추가로 마련하는 것을 강력하게 권장합니다.

값이 변경되지 않는 정적 콜렉션이라면 인덱스 값을 표현하는 `$index`를 사용하는 것도 좋습니다.

값이 변경되는 것을 필드로 식별할 수 없다면 객체 자체를 활용할 수도 있습니다.
이 방식은 삼중 등호 연산자(`===`)를 기준으로 참조값이 같은지 판단합니다.
이 방식은 가능한 한 사용하지 않는 것이 좋습니다.
Angular가 데이터와 DOM 노드를 제대로 매칭할 수 없으면 렌더링 성능이 크게 저하될 수 있습니다.

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

참고: `*ngFor`와 달리 `@for` 블록은 뷰 재사용을 우선합니다. 추적하는 프로퍼티가 바뀌어도 객체 참조가 같으면 엘리먼트 전체를 제거하고 다시 생성하는 대신 컴포넌트 입력값을 포함한 뷰 바인딩을 갱신합니다.

### `@for` 블록 내부에서 사용할 수 있는 변수

<!--
Inside `@for` blocks, several implicit variables are always available:

| Variable | Meaning                                       |
| -------- | --------------------------------------------- |
| `$count` | Number of items in a collection iterated over |
| `$index` | Index of the current row                      |
| `$first` | Whether the current row is the first row      |
| `$last`  | Whether the current row is the last row       |
| `$even`  | Whether the current row index is even         |
| `$odd`   | Whether the current row index is odd          |

These variables are always available with these names, but can be aliased via a `let` segment:

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

The aliasing is useful when nesting `@for` blocks, letting you read variables from the outer `@for` block from an inner `@for` block.
-->

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

이렇게 내부 변수를 다른 이름으로 지정하는 방식은 `@for` 블록이 중첩되어 있을 때 특히 유용합니다.

### 콜렉션이 비어있을 때 - `@empty` 블록 사용하기

<!--
You can optionally include an `@empty` section immediately after the `@for` block content. The content of the `@empty` block displays when there are no items:

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

`@for` 블록 뒤에는 `@empty` 블록을 사용할 수 있습니다.
그러면 `@for` 블록에서 순회하는 콜렉션에 항목이 하나도 없을 때 `@empty` 블록이 화면에 표시됩니다:

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

## 여러 조건 중 하나 표시하기: `@switch` 블록

<!--
While the `@if` block is great for most scenarios, the `@switch` block provides an alternate syntax to conditionally render data. Its syntax closely resembles JavaScript's `switch` statement.

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

The value of the conditional expression is compared to the case expression using the triple-equals (`===`) operator.

**`@switch` does not have a fallthrough**, so you do not need an equivalent to a `break` or `return` statement in the block.

You can specify multiple conditions for a single block by having consecutive `@case` statements.

You can optionally include a `@default` block. The content of the `@default` block displays if none of the preceding case expressions match the switch value.

If no `@case` matches the expression and there is no `@default` block, nothing is shown.
-->

`@if` 블록은 대부분의 경우에 사용할 수 있지만, 조건이 여러 개라면 `@switch` 블록을 사용하는 것도 고려할 만합니다.
`@switch` 블록은 JavaScript `switch` 구문과 아주 비슷합니다.

이때 조건문은 삼중 등호 연산자(`===`)로 비교합니다.

**`@switch` 블록은 다음 블록으로 연결되지 않습니다. `break`나 `return` 같이 흐름을 제어하는 구문은 존재하지 않습니다.**

그리고 `@case` 구문은 블록 하나에 여러 조건을 함께 걸 수 있습니다.

`@default` 블록을 사용할 수 있습니다.
이 블록은 매칭되는 `@case` 블록이 없을 때 표시됩니다.

`@default` 블록이 없으면서 `@case` 블록 중 어느 것도 매칭되지 않으면, 아무것도 렌더링되지 않습니다.

<!--
### Exhaustive type checking

`@switch` supports exhaustive type checking, allowing Angular to verify at compile time that all possible values of a union type are handled.

By using `@default never;`, you explicitly declare that no remaining cases should exist. If the union type is later extended and a new case is not covered by an @case, Angular’s template type checker will report an error, helping you catch missing branches early.

NOTE: Exhaustiveness checking relies on TypeScript's type narrowing, which only works on variables. It will not work if the switch condition is a function call or a signal (for example, `@switch (state())`). To work around this, assign the signal to a `@let` variable, e.g.: `@let mySignal = this.mySignal()`.

```typescript
@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';
}
```

When the switched expression is nested within a union, you must explicitly specify the expression to check for exhaustiveness.

<!- prettier-ignore ->
```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};
}
```
-->

### 모든 경우의 타입 검사하기 {#exhaustive-type-checking}

`@switch`는 모든 경우에 대한 타입 검사를 지원하므로, Angular는 컴파일 시점에 유니언 타입의 가능한 값을 모두 처리하는지 확인할 수 있습니다.

`@default never;`를 사용하면 처리하지 않은 경우가 남아 있지 않아야 한다고 명시적으로 선언합니다.
이후 유니언 타입이 확장되어 새로운 경우가 추가되었는데 `@case`로 처리하지 않으면 Angular 템플릿 타입 검사기가 오류를 보고하므로 누락한 분기를 조기에 발견할 수 있습니다.

참고: 모든 경우에 대한 검사는 TypeScript의 타입 좁히기를 사용하며, 이 기능은 변수에만 동작합니다.
switch 조건이 함수 호출이나 시그널(예: `@switch (state())`)이면 동작하지 않습니다.
이때는 `@let mySignal = this.mySignal()`처럼 시그널 값을 `@let` 변수에 할당해서 사용하세요.

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

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

@default never;
      
    }
  `,
})
export class AppComponent {
  state: 'loggedOut' | 'loading' | 'loggedIn' = 'loggedOut';
}
```

switch 표현식이 유니언 타입 안에 중첩되면, 모든 경우를 확인할 표현식을 명시적으로 지정해야 합니다.

```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 has two types of variable declarations in templates: local template variables and template reference variables.

HELPFUL: In this guide, “template” does not mean the entire HTML template file. It refers only to a specific template construct or expression within the file.
-->

Angular 템플릿에서는 템플릿 지역 변수와 템플릿 참조 변수를 선언해서 활용할 수 있습니다.

참고: 이 문서에서 "템플릿" 이라고 하는 것은 HTML 템플릿 파일을 의미하지 않습니다.
템플릿 구조나 파일 안에 있는 템플릿 조각도 언급하는 것입니다.

## 템플릿 지역 변수(Local template variables): `@let`

Angular가 제공하는 `@let` 문법을 사용하면 템플릿에서 지역 변수를 선언해서 재사용할 수 있습니다.
이 방식은 [JavaScript `let` 문법](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let)과 비슷합니다.

### `@let` 활용하기

<!--
Use `@let` to declare a variable whose value is based on the result of a template expression. Angular automatically keeps the variable's value up-to-date with the given expression, similar to [bindings](/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...';
```

Each `@let` block can declare exactly one variable. You cannot declare multiple variables in the same block with a comma.
-->

템플릿 지역 변수를 선언하려면 `@let`을 사용하면 되고, 템플릿 지역 변수의 값은 표현식의 실행 결과로 할당됩니다.
이 값은 [바인딩](/guide/templates/binding)과 비슷하게 Angular가 값이 변경되는 것을 추적합니다.

`@let` 블록은 각각 변수 하나를 선언합니다.
쉼표(`,`)를 사용하는 것처럼 블록 하나에서 변수 여러 개를 한 번에 선언할 수는 없습니다.

### `@let`으로 값 참조하기

<!--
Once you've declared a variable with `@let`, you can reuse it in the same template:

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

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

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

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

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

### 재할당 불가

<!--
A key difference between `@let` and JavaScript's `let` is that `@let` cannot be reassigned after declaration. However, Angular automatically keeps the variable's value up-to-date with the given expression.

```html
@let value = 1;

<!- Invalid - This does not work! ->
<button (click)="value = value + 1">Increment the value</button>
```
-->

Angular 템플릿이 제공하는 `@let`은 JavaScript `let`과 다르게 한 번 선언한 뒤에 값을 재할당할 수 없습니다.
Angular에서는 값을 재할당하지 않아도 표현식의 결과에 따라 가장 최근에 계산된 값이 자동으로 갱신됩니다.

```html
@let value = 1;

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

### 접근 범위

<!--
`@let` declarations are scoped to the current view and its descendants. Angular creates a new view at component boundaries and wherever a template might contain dynamic content, such as control flow blocks, `@defer` blocks, or structural directives.

Since `@let` declarations are not hoisted, they **cannot** be accessed by parent views or siblings:

```html
@let topLevel = value;

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

<!- Valid ->
{{ topLevel }}
<!- Valid ->
{{ insideDiv }}

@if (condition) {
  <!- Valid ->
  {{ topLevel + insideDiv }}

@let nested = value;

@if (condition) {
    <!- Valid ->
    {{ topLevel + insideDiv + nested }}
  }
}

<!- Error, not hoisted from @if ->
{{ nested }}
```
-->

`@let` 으로 선언한 변수는 해당 뷰와 해당 뷰의 자식 뷰에서 접근할 수 있습니다.
Angular는 컴포넌트 경계와 흐름 제어 블록, `@defer` 블록, 구조 디렉티브 등 템플릿에 동적 컨텐츠가 위치할 수 있는 곳에 새 뷰를 생성합니다.

하지만 `@let`으로 선언한 변수는 호이스팅(hoisting)되지 않기 때문에 부모 뷰나 이웃 뷰에서는 참조할 수 없습니다:

```html
@let topLevel = value;

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

{{ topLevel }}

{{ insideDiv }}

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

@let nested = value;

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

{{ nested }}
```

### 전체 문법

<!--
The `@let` syntax is formally defined as:

- The `@let` keyword.
- Followed by one or more whitespaces, not including new lines.
- Followed by a valid JavaScript name and zero or more whitespaces.
- Followed by the = symbol and zero or more whitespaces.
- Followed by an Angular expression which can be multi-line.
- Terminated by the `;` symbol.
-->

`@let` 문법을 자세하게 살펴보면 이렇습니다:

- `@let` 키워드
- 뒤에 줄바꿈을 제외하고 하나 이상 공백 문자가 옵니다.
- 뒤에 JavaScript 문법으로 유효한 이름이 오고 공백 문자가 올 수 있습니다.
- 뒤에 `=` 심볼이 오고, 공백 문자가 올 수 있습니다.
- 뒤에 Angular 표현식이 오며, 이 표현식은 여러 줄일 수 있습니다.
- `;` 심볼로 종료됩니다.

## 템플릿 참조 변수(Template reference variables)

<!--
Template reference variables give you a way to declare a variable that references a value from an element in your template.

A template reference variable can refer to the following:

- a DOM element within a template (including [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements))
- an Angular component or directive
- a [TemplateRef](/api/core/TemplateRef) from an [ng-template](/api/core/ng-template)

You can use template reference variables to read information from one part of the template in another part of the same template.
-->

템플릿 참조 변수를 활용하면 템플릿에 있는 엘리먼트를 참조할 수 있습니다.

템플릿 참조 변수는 이런 것들을 가리킬 수 있습니다:

- 템플릿에 존재하는 DOM 엘리먼트 ([커스텀 엘리먼트](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)를 포함)
- Angular 컴포넌트나 디렉티브
- [ng-template](/api/core/ng-template)을 의미하는 [TemplateRef](/api/core/TemplateRef) 객체

그래서 템플릿 참조 변수를 활용하면 템플릿 안에 존재하는 어떤 부분을 다른 쪽에서 참조할 수 있습니다.

### 템플릿 참조 변수 선언하기

<!--
You can declare a variable on an element in a template by adding an attribute that starts with the hash character (`#`) followed by the variable name.

```html
<!- Create a template reference variable named "taskInput", referring to the HTMLInputElement. ->
<input #taskInput placeholder="Enter task name" />
```
-->

템플릿에 있는 엘리먼트에 변수를 선언하려면 변수 이름 앞에 해시 문자(`#`)를 붙이면 됩니다.

```html

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

### 템플릿 참조 변수에 값 할당하기

<!--
Angular assigns a value to template variables based on the element on which the variable is declared.

If you declare the variable on a Angular component, the variable refers to the component instance.

```html
<!- The `startDate` variable is assigned the instance of `MyDatepicker`. ->
<my-datepicker #startDate />
```

If you declare the variable on an `<ng-template>` element, the variable refers to a TemplateRef instance which represents the template. For more information, see [How Angular uses the asterisk, \*, syntax](/guide/directives/structural-directives#structural-directive-shorthand) in [Structural directives](/guide/directives/structural-directives).

```html
<!- The `myFragment` variable is assigned the `TemplateRef` instance corresponding to this template fragment. ->
<ng-template #myFragment>
  <p>This is a template fragment</p>
</ng-template>
```

If you declare the variable on any other displayed element, the variable refers to the `HTMLElement` instance.

```html
<!- The "taskInput" variable refers to the HTMLInputElement instance. ->
<input #taskInput placeholder="Enter task name" />
```
-->

Angular는 변수가 선언된 엘리먼트를 기준으로 템플릿 변수의 값을 할당합니다.

Angular 컴포넌트에 변수를 선언하면 이 변수는 컴포넌트 인스턴스를 가리킵니다.

```html

<my-datepicker #startDate />
```

그리고 `<ng-template>` 엘리먼트에 템플릿 참조 변수를 선언하면, 이 변수는 템플릿을 의미하는 TemplateRef 인스턴스를 가리킵니다.
자세한 내용은 [구조 디렉티브](/guide/directives/structural-directives) 문서의 [Angular가 별표(asterisk, \*)를 활용하는 방법](/guide/directives/structural-directives#structural-directive-shorthand) 섹션을 참고하세요.

```html

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

마지막으로 일반 엘리먼트에 템플릿 참조 변수를 선언하면, 이 변수는 `HTMLElement` 인스턴스를 가리킵니다.

```html

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

#### Angular 디렉티브 참조하기

<!--
Angular directives may have an `exportAs` property that defines a name by which the directive can be referenced in a template:

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

When you declare a template variable on an element, you can assign that variable a directive instance by specifying this `exportAs` name:

```html
<!- The `firstZone` variable refers to the `DropZone` directive instance. ->
<section dropZone #firstZone="dropZone">...</section>
```

You cannot refer to a directive that does not specify an `exportAs` name.
-->

Angular 디렉티브는 템플릿에서 참조할 수 있는 이름을 `exportAs` 프로퍼티로 지정할 수 있습니다:

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

그러면 엘리먼트에 템플릿 참조 변수를 선언하면서 `exportAs`를 사용하면 디렉티브 인스턴스를 할당할 수 있습니다:

```html

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

`exportAs`를 지정하지 않은 디렉티브는 참조할 수 없습니다.

### 템플릿 참조 변수로 탐색하기

<!--
In addition to using template variables to read values from another part of the same template, you can also use this style of variable declaration to "mark" an element for [component and directive queries](/guide/components/queries).

When you want to query for a specific element in a template, you can declare a template variable on that element and then query for the element based on the variable name.

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

See [Referencing children with queries](/guide/components/queries) for more information on queries.
-->

템플릿 변수는 해당 템플릿 안에서 어떤 값을 참조하는 용도 외에도, [컴포넌트나 디렉티브를 탐색](/guide/components/queries) 하기 위해 "마킹" 하는 용도로도 사용됩니다.

템플릿에 있는 엘리먼트를 탐색하려면 해당 엘리먼트에 템플릿 변수를 선언하고, 컴포넌트 클래스 코드에서 템플릿 변수 이름으로 탐색하면 됩니다.

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

```typescript
@Component({
  /* ... */,
  template: `<input #description value="Original description">`,
})
export class AppComponent {
  // 템플릿 변수 이름으로 input 엘리먼트를 탐색합니다.
  @ViewChild('description') input: ElementRef | undefined;
}
```

탐색에 대해 자세하게 알아보려면 [쿼리 함수로 자식 컴포넌트 참조하기](/guide/components/queries) 문서를 참고하세요.

### 템플릿 변수의 범위

<!--
Just like variables in JavaScript or TypeScript code, template variables are scoped to the template that declares them.

Similarly, [control flow blocks](guide/templates/control-flow) like `@if` and `@for`, [structural directives](guide/directives/structural-directives), and `<ng-template>` declarations create a new nested template scope, much like JavaScript's control flow statements like `if` and `for` create new lexical scopes. You cannot access template variables within one of these nested templates from outside of its boundaries.

HELPFUL: Define a variable only once in the template so the runtime value remains predictable.
-->

템플릿 변수의 범위는 JavaScript나 TypeScript 코드와 마찬가지로 선언된 범위 안에서만 유효합니다.

이와 비슷하게, `@if`와 `@for` 같은 [제어 흐름 블록](guide/templates/control-flow), [구조 디렉티브](guide/directives/structural-directives), `<ng-template>` 선언은 새로운 중첩 템플릿 범위를 만듭니다. JavaScript의 `if`와 `for`가 새로운 렉시컬 범위를 만드는 것과 같습니다.
이렇게 중첩된 템플릿 안에 선언된 변수는 해당 범위 밖에서 참조할 수 없습니다.

참고: 실행 오류를 방지하기 위해 템플릿 변수는 한 번만 선언하세요.

#### 중첩 템플릿 안에 접근하기

<!--
An inner template can access template variables that the outer template defines.

In the following example, changing the text in the `<input>` changes the value in the `<span>` because Angular immediately updates changes through the template variable, `ref1`.

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

@if (true) {
  <span>Value: {{ ref1.value }}</span>
}
```

In this case, the `@if` block creates a new template scope, which includes the `ref1` variable from its parent scope.

However, accessing a template variable from a child scope in the parent template doesn't work:

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

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

Here, `ref2` is declared in the child scope created by `@if`, and is not accessible from the parent template.
-->

내부 템플릿은 이 템플릿의 외부 템플릿 변수에 접근할 수 있습니다.

아래 코드에서 `<input>` 입력값을 변경하면 Angular가 템플릿 변수 `ref1`을 즉시 갱신하기 때문에 `<span>`에 표시되는 값이 변경됩니다.

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

@if (true) {
  <span>Value: {{ ref1.value }}</span>
}
```

이 경우 `@if` 블록은 새로운 템플릿 범위를 만들기 때문에, 이 범위에서 보면 `ref1` 변수는 부모 범위에 존재합니다.

하지만 부모 템플릿 범위에서 자식 템플릿 범위에 있는 변수에는 접근할 수 없습니다:

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

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

위 코드에서 `ref2`는 `@if`에 의해 자식 템플릿 범위에 선언되었기 때문에, 부모 템플릿에서는 접근할 수 없습니다.

# 뷰 지연 로딩: `@defer`

<!--
Deferrable views, also known as `@defer` blocks, reduce the initial bundle size of your application by deferring the loading of code that is not strictly necessary for the initial rendering of a page. This often results in a faster initial load and improvement in Core Web Vitals (CWV), primarily Largest Contentful Paint (LCP) and Time to First Byte (TTFB).

To use this feature, you can declaratively wrap a section of your template in a @defer block:

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

The code for any components, directives, and pipes inside the `@defer` block is split into a separate JavaScript file and loaded only when necessary, after the rest of the template has been rendered.

Deferrable views support a variety of triggers, prefetching options, and sub-blocks for placeholder, loading, and error state management.
-->

`@defer` 블록은 지연 로딩 뷰를 선언하는 블록입니다.
애플리케이션 초기 렌더링에 꼭 필요하지 않은 코드를 나중에 불러오는 방식으로 애플리케이션 첫 실행에 필요한 파일의 크기를 줄일 수 있습니다.
뷰를 지연 로딩하면 Core Web Vitals(CWV)나 Largest Contentful Paint(LCP), Time to First Byte(TTFB)가 향상되는 경우가 많습니다.

뷰를 지연 로딩하려면 템플릿을 `@defer` 블록으로 감싸면 됩니다:

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

`@defer` 블록 안에 있는 컴포넌트나 디렉티브, 파이프는 별도 JavaScript 파일로 분리되며, 나머지 템플릿이 렌더링된 후 이 구성요소가 필요한 경우에 로드됩니다.

지연 로딩 뷰를 지정하면서 다양한 트리거, 사전 로딩 옵션, 플레이스 홀더, 로딩, 오류 상태 관리 등의 기능을 활용할 수 있습니다.

## 어떤 항목을 지연 로딩할 수 있나요?

<!--
Components, directives, pipes, and any component CSS styles can be deferred when loading an application.

In order for the dependencies within a `@defer` block to be deferred, they need to meet two conditions:

1. **They must be standalone.** Non-standalone dependencies cannot be deferred and are still eagerly loaded, even if they are inside of `@defer` blocks.
1. **They cannot be referenced outside of `@defer` blocks within the same file.** If they are referenced outside the `@defer` block or referenced within ViewChild queries, the dependencies will be eagerly loaded.

The _transitive_ dependencies of the components, directives and pipes used in the `@defer` block do not strictly need to be standalone; transitive dependencies can still be declared in an `NgModule` and participate in deferred loading.

Angular's compiler produces a [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) statement for each component, directive, and pipe used in the `@defer` block. The main content of the block renders after all the imports resolve. Angular does not guarantee any particular order for these imports.
-->

컴포넌트, 디렉티브, 파이프, 컴포넌트 CSS 스타일은 애플리케이션 최초 실행에서 제외하여 지연 로딩할 수 있습니다.

`@defer` 블록 안에 있는 구성요소를 정말 지연 로딩하려면, 다음 조건을 만족해야 합니다:

1. **독립(standalone) 구성요소여야 합니다.** 그렇지 않으면 `@defer` 블록 안에 있더라도 로딩이 지연되지 않고 즉시 로드됩니다.
1. **같은 파일의 `@defer` 블록 밖에서 사용되지 않아야 합니다.** `@defer` 블록 밖에서도 사용되거나 ViewChild 쿼리 등으로 참조되면 해당 항목은 즉시 로드됩니다.

`@defer` 블록 안에 사용된 컴포넌트, 디렉티브, 파이프의 내부 의존성 구성요소는 독립 구성요소가 아니어도 됩니다;
이 항목들은 `NgModule`에 등록해서 모듈 단위로 지연 로딩할 수 있습니다.

Angular 컴파일러는 `@defer` 블록에 사용된 개별 컴포넌트, 디렉티브, 파이프마다 [동적 불러오기(dynamic import)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)를 적용합니다.
그래서 이 블록의 내용은 모든 로딩이 끝난 후에 렌더링됩니다.
로딩 순서는 보장하지 않습니다.

## 지연 로딩 단계 관리하기

`@defer` 블록은 지연 로딩 과정을 세분화하는 하위 블록으로 구성할 수 있습니다.

### `@defer`

<!--
This is the primary block that defines the section of content that is lazily loaded. It is not rendered initially– deferred content loads and renders once the specified [trigger](#controlling-deferred-content-loading-with-triggers) occurs or the `when` condition is met.

By default, a `@defer` block is triggered when the browser state becomes [idle](/guide/templates/defer#idle).

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

지연 로딩 뷰를 정의하는 기본 블록입니다.
지연 로딩되는 뷰는 화면의 첫 렌더링에 포함되지 않고, [트리거(trigger)](#controlling-deferred-content-loading-with-triggers)가 동작하거나 `when` 조건이 맞을 때만 로딩되어 렌더링됩니다.

기본적으로 `@defer` 블록은 브라우저가 [대기(idle)](/guide/templates/defer#idle) 상태가 되었을 때 트리거됩니다.

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

### 렌더링 위치 지정하기: `@placeholder`

<!--
By default, defer blocks do not render any content before they are triggered.

The `@placeholder` is an optional block that declares what content to show before the `@defer` block is triggered.

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

While optional, certain triggers may require the presence of either a `@placeholder` or a [template reference variable](/guide/templates/variables#template-reference-variables) to function. See the [Triggers](#controlling-deferred-content-loading-with-triggers) section for more details.

Angular replaces placeholder content with the main content once loading is complete. You can use any content in the placeholder section including plain HTML, components, directives, and pipes. Keep in mind the _dependencies of the placeholder block are eagerly loaded_.

The `@placeholder` block accepts an optional parameter to specify the `minimum` amount of time that this placeholder should be shown after the placeholder content initially renders.

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

This `minimum` parameter is specified in time increments of milliseconds (ms) or seconds (s). You can use this parameter to prevent fast flickering of placeholder content in the case that the deferred dependencies are fetched quickly.
-->

기본적으로 `@defer` 블록은 트리거가 동작하기 전까지 아무것도 렌더링되지 않습니다.

이때 `@defer` 블록이 표시되기 전에 화면에 표시할 내용이 있다면, `@placeholder` 블록을 지정하면 됩니다.

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

`@placeholder` 블록이 필수인 것은 아니지만, 어떤 트리거는 `@placeholder`나 [템플릿 참조 변수](/guide/templates/variables#template-reference-variables)가 필요합니다.
자세한 내용은 [트리거](#controlling-deferred-content-loading-with-triggers) 섹션을 참고하세요.

`@defer` 블록은 로딩된 후에 `@placeholder` 블록을 대체하며 렌더링됩니다.
그리고 `@placeholder` 블록에는 일반 HTML, 컴포넌트, 디렉티브, 파이프를 자유롭게 사용할 수 있습니다.
`@placeholder` 블록에 사용되는 컴포넌트, 디렉티브, 파이프는 지연 로딩되지 않고 _즉시 로딩된다는 것을_ 기억하세요.

`@placeholder` 블록을 사용할 때 `minimum` 옵션을 사용할 수 있습니다.
이 옵션은 `@placeholder` 블록이 처음 렌더링된 후, 표시되는 최소 시간을 지정하는 옵션입니다.

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

`minimum` 변수에는 밀리초(ms) 단위나 초(s) 단위 시간을 지정합니다.
이 옵션은 지연 로딩되는 뷰가 너무 빨리 로딩되는 경우에 화면이 깜빡이는 것을 방지하는 용도로 사용합니다.

### 로딩 표시하기: `@loading`

<!--
The `@loading` block is an optional block that allows you to declare content that is shown while deferred dependencies are loading. It replaces the `@placeholder` block once loading is triggered.

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

Its dependencies are eagerly loaded (similar to `@placeholder`).

The `@loading` block accepts two optional parameters to help prevent fast flickering of content that may occur when deferred dependencies are fetched quickly,:

- `minimum` - the minimum amount of time that this placeholder should be shown
- `after` - the amount of time to wait after loading begins before showing the loading template

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

Both parameters are specified in time increments of milliseconds (ms) or seconds (s). In addition, the timers for both parameters begin immediately after the loading has been triggered.
-->

지연 로딩되는 뷰가 로딩 중일 때 표시할 내용이 있다면 `@loading` 블록을 사용합니다.
`@loading` 블록은 트리거가 동작하고 나면 `@placeholder` 블록 대신 화면에 표시됩니다.

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

`@loading` 블록에 사용되는 컴포넌트, 디렉티브, 파이프도 `@Placeholder` 블록과 비슷하게 즉시 로딩됩니다.

`@loading` 블록은 지연 로딩하는 뷰가 너무 빨리 로딩되어 화면이 깜빡이는 것을 방지하기 위해 옵션을 2개 받을 수 있습니다:

- `minimum` - `@loading` 블록이 표시될 최소 시간
- `after` - `@loading` 블록이 로딩되고 표시되기 전까지 대기할 시간

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

두 옵션 모두 밀리초(ms)나 초(s) 단위를 지정합니다.
이 타이머는 로딩 트리거가 동작한 직후부터 시작됩니다.

### 지연 로딩 오류 표시하기: `@error`

<!--
The `@error` block is an optional block that displays if deferred loading fails. Similar to `@placeholder` and `@loading`, the dependencies of the @error block are eagerly loaded.

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

뷰 지연 로딩에서 발생하는 오류를 표시하려면 `@error` 블록을 사용합니다.
`@error` 블록 안에 사용되는 구성요소는 `@placeholder`, `@loading` 블록과 비슷하게 즉시 로딩됩니다.

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

## 트리거로 지연 로딩 제어하기 {#controlling-deferred-content-loading-with-triggers}

<!--
You can specify **triggers** that control when Angular loads and displays deferred content.

When a `@defer` block is triggered, it replaces placeholder content with lazily loaded content.

Multiple event triggers can be defined by separating them with a semicolon, `;` and will be evaluated as OR conditions.

There are two types of triggers: `on` and `when`.
-->

뷰 지연 로딩을 제어하려면 **트리거(triggers)** 를 사용하면 됩니다.

`@defer` 블록은 트리거가 동작하고 난 후 지연 로딩되면서 `@placeholder` 블록을 대체하면서 렌더링됩니다.

이때 세미콜론(`;`)을 사용해서 이벤트 트리거를 여러 개 지정할 수 있으며, 이렇게 지정된 트리거는 OR 조건으로 동작합니다.

트리거는 크게 `on`과 `when` 으로 구분할 수 있습니다.

### `on`

<!--
`on` specifies a condition for when the `@defer` block is triggered.

The available triggers are as follows:

| Trigger                       | Description                                                            |
| ----------------------------- | ---------------------------------------------------------------------- |
| [`idle`](#idle)               | Triggers when the browser is idle. Supports an optional timeout.       |
| [`viewport`](#viewport)       | Triggers when specified content enters the viewport                    |
| [`interaction`](#interaction) | Triggers when the user interacts with specified element                |
| [`hover`](#hover)             | Triggers when the mouse hovers over specified area                     |
| [`immediate`](#immediate)     | Triggers immediately after non-deferred content has finished rendering |
| [`timer`](#timer)             | Triggers after a specific duration                                     |
-->

`on` 은 `@defer` 블록 트리거가 동작하는 조건을 지정합니다.

이런 트리거를 사용할 수 있습니다:

| 트리거                        | 설명                                                              |
| ----------------------------- | ----------------------------------------------------------------- |
| [`idle`](#idle)               | 브라우저가 대기 상태일 때 동작합니다. 타임아웃 옵션을 지원합니다. |
| [`viewport`](#viewport)       | 특정 항목이 뷰포트에 진입할 때 동작합니다.                        |
| [`interaction`](#interaction) | 사용자가 특정 엘리먼트와 상호작용할 때 동작합니다.                |
| [`hover`](#hover)             | 마우스가 특정 영역 위에 올라갈 때 동작합니다.                     |
| [`immediate`](#immediate)     | 지연 로딩이 아닌 뷰 렌더링이 끝난 직후 동작합니다.                |
| [`timer`](#timer)             | 특정 시간 뒤에 동작합니다.                                        |

#### `idle`

<!--
The `idle` trigger loads the deferred content once the browser has reached an idle state, based on requestIdleCallback. This is the default behavior with a defer block.

You can optionally specify a timeout in milliseconds that is passed to [`requestIdleCallback`](https://developer.mozilla.org/docs/Web/API/Window/requestIdleCallback). If the browser doesn't schedule the callback soon enough, the work will run no later than the specified timeout.
```html
<!- @defer (on idle) ->
@defer {
  <large-cmp />
} @placeholder {
  <div>Large component placeholder</div>
}

<!- With a 500ms timeout ->
@defer (on idle(500)) {
  <large-cmp />
}
```
-->

`idle` 트리거는 브라우저가 대기 상태로 진입할 때 동작해서 지연 로딩 뷰를 로드합니다.
이 트리거가 기본값입니다.

[`requestIdleCallback`](https://developer.mozilla.org/docs/Web/API/Window/requestIdleCallback)에 전달할 타임아웃을 밀리초 단위로 지정할 수 있습니다.
브라우저가 콜백을 충분히 빨리 예약하지 못하더라도 지정한 제한 시간 안에는 작업이 실행됩니다.

```html

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

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

##### `idle` 동작 커스터마이징하기

<!--
You can customize the `idle` trigger by providing your own `IdleService` implementation and registering it with `provideIdleServiceWith` in your application's providers.

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

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

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

`IdleService`를 구현하고 이 객체를 `provideIdleServiceWith` 함수로 프로바이더에 등록하면 `idle` 트리거를 커스터마이징할 수 있습니다.

```ts
@Service()
class CustomIdleService implements IdleService {
  requestOnIdle(callback: (deadline?: IdleDeadline) => void, options?: IdleRequestOptions): number {
    // idle 스케줄 로직을 여기에 작성합니다.
    return requestIdleCallback(callback, options);
  }

cancelOnIdle(id: number) {
    // 커스텀 idle 취소 로직을 여기에 작성합니다.
  }
}

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

#### `viewport`

<!--
The `viewport` trigger loads the deferred content when the specified content enters the viewport using the [Intersection Observer API](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API). Observed content may be `@placeholder` content or an explicit element reference.

By default, the `@defer` watches for the placeholder entering the viewport. Placeholders used this way must have a single root element.

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

Alternatively, you can specify a [template reference variable](/guide/templates/variables) in the same template as the `@defer` block as the element that is watched to enter the viewport. This variable is passed in as a parameter on the viewport trigger.

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

If you want to customize the options of the `IntersectionObserver`, the `viewport` trigger supports passing in an object literal. The literal supports all properties from the second parameter of `IntersectionObserver`, except for `root`. When using the object literal notation, you have to pass your trigger using the `trigger` property.

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

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

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

`viewport` 트리거는 [Intersection Observer API](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API)를 활용해서 특정 항목이 뷰포트에 진입할 때 동작합니다.
이때 특정 항목은 `@placeholder` 항목이거나 명시적으로 지정한 엘리먼트가 됩니다.

기본적으로 `@defer` 블록은 `@placeholder` 가 뷰포트에 진입하는 것을 감지합니다.
이 경우 `@placeholder` 는 반드시 엘리먼트 하나여야 합니다.

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

아니면 대상 엘리먼트에 [템플릿 참조 변수](/guide/templates/variables)를 지정한 후에 뷰포트 트리거로 전달하면 됩니다.

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

`IntersectionObserver` 옵션을 커스터마이징하려면 `viewport` 트리거로 객체 리터럴을 전달하면 됩니다.
이 리터럴은 `root`를 제외하고 `IntersectionObserver`의 두 번째 인자의 모든 프로퍼티를 지원합니다.
객체 리터럴 표기법을 사용할 때는 `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`

<!--
The `interaction` trigger loads the deferred content when the user interacts with the specified element through `click` or `keydown` events.

By default, the placeholder acts as the interaction element. Placeholders used this way must have a single root element.

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

Alternatively, you can specify a [template reference variable](/guide/templates/variables) in the same template as the `@defer` block as the element that is watched for interactions. This variable is passed in as a parameter on the interaction trigger.

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

`interaction` 트리거는 사용자가 특정 엘리먼트와 `click` 이벤트나 `keydown` 이벤트로 상호작용할 때 동작합니다.

기본적으로 `@placeholder`는 상호작용하는 엘리먼트로 간주됩니다.
이 경우 `@placeholder`는 엘리먼트 하나여야 합니다.

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

아니면 대상 엘리먼트에 [템플릿 참조 변수](/guide/templates/variables)를 지정한 후에 상호작용 트리거로 전달하면 됩니다.

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

#### `hover`

<!--
The `hover` trigger loads the deferred content when the mouse has hovered over the triggered area through the `mouseover` and `focusin` events.

By default, the placeholder acts as the interaction element. Placeholders used this way must have a single root element.

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

Alternatively, you can specify a [template reference variable](/guide/templates/variables) in the same template as the `@defer` block as the element that is hovered over. This variable is passed in as a parameter on the hover trigger.

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

`hover` 트리거는 마우스가 어떤 영역으로 이동해서 `mouseover` 이벤트나 `focusin` 이벤트가 발생했을 때 동작합니다.

기본적으로 `@placeholder`는 상호작용하는 엘리먼트로 간주됩니다.
이 경우 `@placeholder`는 엘리먼트 하나여야 합니다.

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

아니면 같은 템플릿 안에서 마우스가 올라오는 것을 감지할 엘리먼트에 [템플릿 참조 변수](/guide/templates/variables)를 지정한 후 `hover` 트리거의 인자로 전달하면 됩니다.

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

#### `immediate`

<!--
The `immediate` trigger loads the deferred content immediately. This means that the deferred block loads as soon as all other non-deferred content has finished rendering.

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

`immediate` 트리거는 지연 로딩 뷰를 즉시 로드합니다.
다르게 표현하면, 지연 로딩이 아닌 부분의 렌더링이 끝난 직후, 지연 로딩하도록 지정된 나머지 뷰를 로드합니다.

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

#### `timer`

<!--
The `timer` trigger loads the deferred content after a specified duration.

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

The duration parameter must be specified in milliseconds (`ms`) or seconds (`s`).
-->

`timer` 트리거는 특정 시간이 지난 후에 동작합니다.

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

이때 지연시간은 밀리초(`ms`) 단위나 초(`s`) 단위를 사용합니다.

### `when`

<!--
The `when` trigger accepts a custom conditional expression and loads the deferred content when the condition becomes truthy.

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

This is a one-time operation– the `@defer` block does not revert back to the placeholder if the condition changes to a falsy value after becoming truthy.
-->

`when` 트리거는 조건 표현식을 인자로 받으며 이 조건이 참으로 평가될 때 뷰를 로딩합니다.

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

이 로딩 동작은 한 번만 실행됩니다.
조건이 참이었다가 거짓으로 평가되더라도 `@placeholder` 블록이 다시 표시되거나 하지는 않습니다.

## 사전 로딩하기: `prefetch`

<!--
In addition to specifying a condition that determines when deferred content is shown, you can optionally specify a **prefetch trigger**. This trigger lets you load the JavaScript associated with the `@defer` block before the deferred content is shown.

Prefetching enables more advanced behaviors, such as letting you start to prefetch resources before a user has actually seen or interacted with a defer block, but might interact with it soon, making the resources available faster.

You can specify a prefetch trigger similarly to the block's main trigger, but prefixed with the `prefetch` keyword. The block's main trigger and prefetch trigger are separated with a semi-colon character (`;`).

In the example below, the prefetching starts when a browser becomes idle and the contents of the block is rendered only once the user interacts with the placeholder.

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

<!- Prefetching with a 500ms idle timeout ->
@defer (on interaction; prefetch on idle(500)) {
  <large-cmp />
}
```
-->

내용을 로딩하는 조건문을 지정하면서 **사전 로딩 트리거(prefetch trigger)** 를 옵션으로 지정할 수 있습니다.
이 트리거를 사용하면 지연 로딩하는 내용을 표시하기 전에 `@defer` 블록과 연결된 JavaScript를 로드할 수 있습니다.

사전 로딩을 활용하면 사용자가 지연 로딩 뷰를 실제로 보기 전이나 특정 블록과 상호작용하기 전에 리소스를 빠르게 로딩해 둘 수 있습니다.

사전 로딩 트리거는 블록 트리거와 비슷하지만, `prefetch` 키워드가 접두사로 붙습니다.
블록 트리거와 사전 로딩 트리거를 함께 사용하는 경우에는 세미콜론(`;`)으로 구분합니다.

아래 예제처럼 구현하면, 브라우저가 대기 상태로 진입하는 시점에 사전 로딩이 시작되며, `@defer` 블록의 내용은 사용자가 `@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` 블록 테스트하기

<!--
Angular provides TestBed APIs to simplify the process of testing `@defer` blocks and triggering different states during testing. By default, `@defer` blocks in tests play through like a defer block would behave in a real application. If you want to manually step through states, you can switch the defer block behavior to `Manual` in the TestBed configuration.

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

Angular는 다양한 트리거와 함께 `@defer` 블록을 테스트할 수 있는 TestBed API를 제공합니다.
기본적으로 `@defer` 블록은 실제 애플리케이션이 동작하는 것과 동일하게 테스트 환경에서 동작합니다.
하지만 TestBed를 수동으로 설정하면 각 단계를 직접 조작할 수 있습니다.

```typescript
it('should render a defer block in different states', async () => {
  // defer 블록의 동작 방식을 수동으로 조작합니다. 시작 상태는 "paused" 입니다.
  TestBed.configureTestingModule({deferBlockBehavior: DeferBlockBehavior.Manual});
  @Component({
    // ...
    template: `
      @defer {
        <large-component />
      } @placeholder {
        Placeholder
      } @loading {
        Loading...
      }
    `,
  })
  class ExampleA {}
  // 컴포넌트 픽스처를 생성합니다.
  const componentFixture = TestBed.createComponent(ExampleA);
  // defer 블록을 모두 참조하고 그중 첫번째 블록을 가져옵니다.
  const deferBlockFixture = (await componentFixture.getDeferBlocks())[0];
  // placeholder 블록이 렌더링된 것을 확인합니다.
  expect(componentFixture.nativeElement.innerHTML).toContain('Placeholder');
  // 로딩 상태로 바꾸고 loading 블록이 렌더링된 것을 확인합니다.
  await deferBlockFixture.render(DeferBlockState.Loading);
  expect(componentFixture.nativeElement.innerHTML).toContain('Loading');
  // 최종 상태로 바꾸고 최종 렌더링을 확인합니다.
  await deferBlockFixture.render(DeferBlockState.Complete);
  expect(componentFixture.nativeElement.innerHTML).toContain('large works!');
});
```

## `@defer`를 `NgModule`과 함께 사용할 수 있나요?

`@defer` 블록은 독립 구성요소는 물론이고 NgModule 기반 컴포넌트, 디렉티브, 파이프와도 함께 사용할 수 있습니다.
하지만 **실제로 지연 로딩되는 것은 독립 컴포넌트, 독립 디렉티브, 독립 파이프뿐입니다**.
NgModule 기반으로 등록된 컴포넌트, 디렉티브, 파이프는 지연 로딩되지 않으며 즉시 로드됩니다.

## `@defer` 블록과 핫 모듈 갱신(HMR) 호환성

핫 모듈 대체(Hot Module Replacement, HMR)이 활성화되면 `@defer` 블록 청크는 설정에 관계없이 모두 즉시 로딩됩니다.
표준 트리거 동작을 복원하려면 애플리케이션을 실행할 때 `--no-hmr` 플래그를 지정해서 HMR 기능을 비활성화해야 합니다.

## 서버 사이드 렌더링(SSR), 정적 사이트 생성(SSG)인 경우는 `@defer`가 어떻게 동작하나요?

<!--
By default, when rendering an application on the server (either using SSR or SSG), defer blocks always render their `@placeholder` (or nothing if a placeholder is not specified) and triggers are not invoked. On the client, the content of the `@placeholder` is hydrated and triggers are activated.

To render the main content of `@defer` blocks on the server (both SSR and SSG), you can enable [the Incremental Hydration feature](/guide/incremental-hydration) and configure `hydrate` triggers for the necessary blocks.
-->

SSR이나 SSG와 같이 애플리케이션이 서버에서 렌더링되는 경우는 기본적으로 `@placeholder` 블록이 있는 경우는 `@placeholder` 블록을 렌더링하고, `@placeholder` 블록이 없으면 아무것도 렌더링하지 않습니다.
그리고 클라이언트에서 애플리케이션이 실행될 때 `@placeholder`가 하이드레이션되면서 트리거가 동작합니다.

서버에서 `@defer` 블록의 본문을 렌더링하려면 [점진적 하이드레이션](/guide/incremental-hydration)을 활성화하고 필요한 블록에 `hydrate` 트리거를 설정해야 합니다.

## 배럴 파일과 지연 로딩 청크

<!--
If you're using `@defer` but not seeing a separate lazy chunk in your build output, check how you're importing the deferred component. Importing through a barrel file (`index.ts`) is a common culprit — bundlers see the barrel as a single module and keep all its exports together, so your component ends up in the main bundle regardless of `@defer`.

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

```typescript
{header: "parent.component.ts"}
import {Component} from '@angular/core';
import {HeavyComponent} from './index'; // pulls in OtherComponent too

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

The fix is straightforward — import directly from the component's own file:

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

That's enough for the bundler to split it into its own chunk and load it lazily when the trigger fires.
-->

`@defer`를 사용하는데 별도로 지연 로딩 청크가 생성되지 않는다면, 지연 로딩 컴포넌트를 어떻게 불러오는지 확인해 보세요.
배럴 파일(`index.ts`)로 로딩하는 것이 흔한 원인입니다.
이런 경우는 번들러가 배럴 파일을 단일 모듈로 인식하고 모든 항목을 함께 유지하기 때문에, `@defer` 사용 여부와 관계없이 컴포넌트가 메인 번들 파일에 포함됩니다.

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

```typescript
{header: "parent.component.ts"}
import {Component} from '@angular/core';
import {HeavyComponent} from './index'; // 다른 컴포넌트도 함께 로드합니다.

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

해결방법은 간단합니다.
컴포넌트가 정의된 파일 자체를 직접 로드하세요:

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

이렇게 작성하면 별도 청크 파일을 정상적으로 생성하며, 지연 로딩도 제대로 동작합니다.

## 모범사례

### `@defer` 블록 중첩 사용을 피하세요

`@defer` 블록을 중첩할 때는 동시에 로딩되어 연속적인 요청이 발생하지 않도록 서로 다른 트리거를 사용하세요.
연속적인 요청은 페이지 로딩 성능에 나쁜 영향을 줄 수 있습니다.

### 레이아웃 변경을 피하세요

<!--
Avoid deferring components that are visible in the user’s viewport on initial load. Doing this may negatively affect Core Web Vitals by causing an increase in cumulative layout shift (CLS).

In the event this is necessary, avoid `immediate`, `timer`, `viewport`, and custom `when` triggers that cause the content to load during the initial page render.
-->

첫 로딩에서 사용자의 뷰포트에 있는 컴포넌트를 지연 로딩하지 마세요.
이 경우는 누적 레이아웃 이동(cumulative layout shift, CLS)이 발생하면서 Core Web Vital에 부정적인 영향을 줍니다.

꼭 필요한 경우라면, 첫 화면 로딩을 방해할 수 있는 `immediate`, `timer`, `viewport`, 커스텀 `when` 트리거 사용을 피하세요.

### 접근성을 항상 고려하세요

<!--
When using `@defer` blocks, consider the impact on users with assistive technologies like screen readers.
Screen readers that focus on a deferred section will initially read the placeholder or loading content, but may not announce changes when the deferred content loads.

To ensure deferred content changes are announced to screen readers, you can wrap your `@defer` block in an element with a 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>
```

This ensures that changes are announced to the user when transitions (placeholder → loading → content/error) occur.
-->

`@defer` 블록을 사용하면 스크린 리더와 같은 보조 기술을 사용하는 사용자에게 큰 영향을 줄 수 있습니다.
스크린 리더는 지연 로딩되는 섹션의 플레이스홀더나 로딩 중이라는 것은 읽을 수 있지만, 이후에 내용물이 갱신되고 나면 변경사항을 알리지 않을 수도 있습니다.

화면이 변경된 것을 스크린 리더에게 명확하게 알리려면, `@defer` 블록을 `aria-live` 어트리뷰트로 랩핑하면 됩니다:

이렇게 구현하면 화면이 변경될 때 변경사항을 사용자에게 제대로 알릴 수 있습니다.

# 표현식 문법

Angular 표현식 문법은 JavaScript를 기반으로 하지만 몇 가지는 다릅니다.
이 문서에서는 Angular 표현식 문법이 표준 JavaScript와 어떻게 비슷하고 다른지 알아봅시다.

## 리터럴 값

Angular는 JavaScript의 [리터럴 값](https://developer.mozilla.org/en-US/docs/Glossary/Literal) 중 일부를 지원합니다.

### 지원하는 리터럴 값

| 리터럴 타입                 | 예시                            |
| --------------------------- | ------------------------------- |
| 문자열                      | `'Hello'`, `"World"`            |
| 불리언                      | `true`, `false`                 |
| 숫자                        | `123`, `3.14`                   |
| 객체                        | `{name: 'Alice'}`               |
| 배열                        | `['Onion', 'Cheese', 'Garlic']` |
| null                        | `null`                          |
| 정규표현식                  | `/\d+/`                         |
| 템플릿 문자열               | `` `Hello ${name}` ``           |
| 태그가 지정된 템플릿 문자열 | `` tag`Hello ${name}` ``        |

### 지원하지 않는 리터럴 값

| 리터럴 타입 | 예시 |
| ----------- | ---- |
| BigInt      | `1n` |

## 전역 변수

<!--
Angular expressions support the following [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)

No other JavaScript globals are supported. Common JavaScript globals include `Number`, `Boolean`, `NaN`, `Infinity`, `parseInt`, and more.
-->

Angular 표현식에서는 다음과 같은 [전역](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)

이 외에 `Number`, `Boolean`, `NaN`, `Infinity`, `parseInt` 등 표준 JavaScript에서 지원하는 전역 객체는 지원하지 않습니다.

## 지역 변수

<!--
Angular automatically makes special local variables available for use in expressions in specific contexts. These special variables always start with the dollar sign character (`$`).

For example, `@for` blocks make several local variables corresponding to information about the loop, such as `$index`.
-->

표현식의 특정 컨텍스트에서 사용할 수 있는 특별한 지역 변수들이 있습니다.
이 변수들은 Angular가 자동으로 선언한 것이며, 달러 기호(`$`)로 시작합니다.

`@for` 블록에서 실행 블록을 한 번씩 돌 때마다 변경되는 `$index`와 같은 변수가 이런 경우에 해당합니다.

## 어떤 연산자를 사용할 수 있나요?

### 지원하는 연산자

<!--
Angular supports the following operators from standard JavaScript.

| Operator                      | Example(s)                                     |
| ----------------------------- | ---------------------------------------------- |
| 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)`                                  |

| Arrow function                | `items.filter((i) => i.active)`                |

NOTE: Assignment and increment/decrement operators are only valid in [event listener statements](#event-listener-statements). Using them in a binding or interpolation is a compile error, unless they are inside an arrow function.

Arrow functions must have an expression body. Pipes cannot be used inside an arrow function, but you can pass an arrow function as an argument to a pipe.

Angular expressions additionally also support the following non-standard operators:

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

### Safe navigation migration

Prior to Angular 22, the optional chaining operator (`?.`) returned `null` when the left-hand side is `null` or `undefined`, whereas standard JavaScript's `?.` returns `undefined`.
Since Angular 22, the optional chaining operator behavior in angular expressions is alligned with the standard Javascript's behavior.

During the migration to v22, the `ng update` schematics added a `$safeNavigationMigration` magic function to existing expressions to preserve the previous `null`-returning behavior.

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

`$safeNavigationMigration` is a **temporary migration aid only**. It instructs the compiler to compile the wrapped safe-navigation expression using the legacy null-returning semantics rather than the standard JavaScript `?.` semantics. It is not a real function and cannot be called from TypeScript.

NOTE: Prefer migrating expressions to no longer rely on `null` vs `undefined` distinctions so that `$safeNavigationMigration` can be removed. This function may be removed in a future version of Angular.
-->

Angular 표현식에는 표준 JavaScript 연산자 중 다음과 같은 연산자를 사용할 수 있습니다.

| 연산자                        | 예시                                           |
| ----------------------------- | ---------------------------------------------- |
| 더하기 / 문자열 연결하기      | `1 + 2`                                        |
| 빼기                          | `52 - 3`                                       |
| 곱하기                        | `41 * 6`                                       |
| 나누기                        | `20 / 4`                                       |
| 나머지 구하기                 | `17 % 5`                                       |
| 지수 연산                     | `10 ** 3`                                      |
| 소괄호                        | `9 * (8 + 4)`                                  |
| 삼항 연산자                   | `a > b ? true : false`                         |
| AND 논리 연산                 | `&&`                                           |
| Or 논리 연산                  | `\|\|`                                         |
| Not 논리 연산                 | `!`                                            |
| Null 병합(Nullish Coalescing) | `possiblyNullValue ?? 'default'`               |
| 비교 연산자                   | `<`, `<=`, `>`, `>=`, `==`, `===`, `!==`, `!=` |
| 단항 마이너스                 | `-x`                                           |
| 단항 플러스                   | `+y`                                           |
| 프로퍼티 접근                 | `person['name']`                               |
| typeof                        | `typeof 42`                                    |
| void                          | `void 1`                                       |
| in                            | `'model' in car`                               |
| instanceof                    | `car instanceof Automobile`                    |
| 할당                          | `a = b`                                        |
| 더하기 할당                   | `a += b`                                       |
| 빼기 할당                     | `a -= b`                                       |
| 곱하기 할당                   | `a *= b`                                       |
| 나누기 할당                   | `a /= b`                                       |
| 나머지 구하기 할당            | `a %= b`                                       |
| 지수 할당                     | `a **= b`                                      |
| AND 논리 연산 할당            | `a &&= b`                                      |
| OR 논리 연산 할당             | `a \|\|= b`                                    |
| Null 병합 할당                | `a ??= b`                                      |
| 객체 리터럴의 객체 전개              | `{...obj, foo: 'bar'}`                         |
| 배열 리터럴의 배열 전개              | `[...arr, 1, 2, 3]`                            |
| 함수의 나머지 인자 연산자     | `fn(...args)`                                  |

| 화살표 함수 | `items.filter((i) => i.active)` |

참고: 할당 연산자와 증가/감소 연산자는 [이벤트 리스너 구문](#event-listener-statements)에서만 사용할 수 있습니다. 화살표 함수 내부가 아니라면 바인딩이나 문자열 바인딩에서 사용했을 때 컴파일 오류가 발생합니다.

화살표 함수의 본문은 표현식이어야 합니다. 화살표 함수 안에서 파이프를 사용할 수는 없지만, 화살표 함수를 파이프의 인자로 전달할 수는 있습니다.

그리고 표준 JavaScript 연산자 외에 다음과 같은 연산자도 지원합니다:

| 연산자                         | 예시                           |
| ------------------------------ | ------------------------------ |
| [Pipe](/guide/templates/pipes) | `{{ total \| currency }}`      |
| 옵셔널 체이닝\*                | `someObj.someProp?.nestedProp` |
| null 보정 연산자 (TypeScript)  | `someObj!.someProp`            |

### 안전 탐색 마이그레이션 {#safe-navigation-migration}

Angular 22 이전에는 옵셔널 체이닝 연산자(`?.`)의 왼쪽 값이 `null`이나 `undefined`이면 `null`을 반환했지만, 표준 JavaScript의 `?.`는 `undefined`를 반환합니다.
Angular 22부터 Angular 표현식의 옵셔널 체이닝 연산자도 표준 JavaScript와 동일하게 동작합니다.

v22로 마이그레이션할 때 `ng update` 스키매틱은 기존의 `null` 반환 동작을 유지하기 위해 기존 표현식에 `$safeNavigationMigration` 특수 함수를 추가했습니다.

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

`$safeNavigationMigration`은 **임시 마이그레이션 도구**입니다.
감싼 안전 탐색 표현식을 표준 JavaScript `?.` 의미 대신 기존의 `null` 반환 의미로 컴파일하도록 컴파일러에 지시합니다.
실제 함수가 아니므로 TypeScript에서 호출할 수 없습니다.

참고: `$safeNavigationMigration`을 제거할 수 있도록 `null`과 `undefined`의 차이에 의존하지 않는 표현식으로 마이그레이션하는 것이 좋습니다.
이 함수는 향후 Angular 버전에서 제거될 수 있습니다.

### 지원하지 않는 연산자

| 연산자         | 예시                           |
| -------------- | ------------------------------ |
| 비트 연산자    | `&`, `&=`, `~`, `\|=`, `^=` 등 |
| 객체 구조 분해 할당 | `const { name } = person`      |
| 배열 구조 분해 할당 | `const [firstItem] = items`    |
| 쉼표 연산자    | `x = (x++, x)`                 |
| new            | `new Car()`                    |

## 표현식의 컨텍스트

<!--
Angular expressions are evaluated within the context of the component class as well as any relevant [template variables](/guide/templates/variables), locals, and globals.

When referring to component class members, `this` is always implied. However, if a template declares a [template variables](guide/templates/variables) with the same name as a member, the variable shadows that member. You can unambiguously reference such a class member by explicitly using `this.`. This can be useful when creating an `@let` declaration that shadows a class member, e.g. for signal narrowing purposes.
-->

Angular 표현식에서는 컴포넌트 클래스의 컨텍스트 외에도 [템플릿 변수](/guide/templates/variables), 지역 변수, 전역 변수를 활용할 수 있습니다.

컴포넌트 클래스 멤버를 참조할 때는 `this`가 사용된 것으로 간주합니다.
하지만 템플릿에 클래스 멤버와 같은 이름으로 [템플릿 변수](guide/templates/variables)가 선언되어 있다면 템플릿 변수의 우선순위가 높습니다.
이 경우는 `this.`를 명시적으로 사용해서 클래스 멤버를 참조할 수 있습니다.
`@let`을 사용하면 더 유용합니다.

## 변수 선언

<!--
Generally speaking, declarations are not supported in Angular expressions. This includes, but is not limited to:

| Declarations                      | Example(s)                                  |
| --------------------------------- | ------------------------------------------- |
| Variables                         | `let label = 'abc'`, `const item = 'apple'` |
| Functions                         | `function myCustomFunction() { }`           |
| Arrow functions with block bodies | `() => { }`                                 |
| Classes                           | `class Rectangle { }`                       |
-->

일반적으로 Angular 표현식에서는 선언문을 지원하지 않습니다.
이런 경우가 모두 해당됩니다:

| 선언                         | 예시                                        |
| ---------------------------- | ------------------------------------------- |
| 변수                         | `let label = 'abc'`, `const item = 'apple'` |
| 함수                         | `function myCustomFunction() { }`           |
| 블록 본문을 가진 화살표 함수 | `() => { }`                                 |
| 클래스                       | `class Rectangle { }`                       |

## 이벤트 리스너 실행문 {#event-listener-statements}

<!--
Event handlers are **statements** rather than expressions. While they support all of the same syntax as Angular expressions, there are two key differences:

1. Statements **do support** assignment operators (but not destructuring assignments)
1. Statements **do not support** pipes
-->

이벤트 핸들러는 표현식(expressions)이 아니고 **실행문(statements)** 입니다.
실행문은 Angular 표현식과 거의 비슷하지만, 두 가지가 다릅니다:

1. 할당 연산자를 지원합니다. (분해 할당은 지원하지 않습니다.)
1. 파이프를 허용하지 않습니다.
<!--
# Attribute directives

Attribute directives change the appearance or behavior of DOM elements and Angular components.
-->

# 어트리뷰트 디렉티브

어트리뷰트 디렉티브는 DOM 엘리먼트와 Angular 컴포넌트의 모습이나 동작을 변경합니다.

<!--
## Use template bindings for one-off behavior

Angular's template syntax already covers changing a single element's classes, styles, properties, and events:

- [Class and style bindings](guide/templates/binding#css-class-and-style-property-bindings) add and remove CSS classes and inline styles.
- [Property and attribute bindings](guide/templates/binding) set DOM properties and HTML attributes.
- [Event listeners](guide/templates/event-listeners) respond to user interaction.

Attribute directives are useful when you want to package this kind of behavior into a reusable unit that you can apply to any element or component.
-->

## 한 곳에서만 사용하는 동작은 템플릿 바인딩 활용하기 {#use-template-bindings-for-one-off-behavior}

Angular 템플릿 문법만으로도 개별 엘리먼트의 클래스, 스타일, 프로퍼티, 이벤트를 변경할 수 있습니다.

- [클래스 및 스타일 바인딩](guide/templates/binding#css-class-and-style-property-bindings)은 CSS 클래스와 인라인 스타일을 추가하거나 제거합니다.
- [프로퍼티 및 어트리뷰트 바인딩](guide/templates/binding)은 DOM 프로퍼티와 HTML 어트리뷰트를 설정합니다.
- [이벤트 리스너](guide/templates/event-listeners)는 사용자 상호작용에 반응합니다.

이러한 동작을 재사용 가능한 단위로 묶어서 어떤 엘리먼트나 컴포넌트에도 적용하고 싶다면 어트리뷰트 디렉티브가 유용합니다.

<!--
## Building an attribute directive

A custom attribute directive is a JavaScript class with the `@Directive()` decorator. The decorator's `selector` defines the attribute that applies the directive. The square brackets make this an attribute selector, so the directive matches elements that carry the attribute. By convention, use a prefix such as `app` to avoid naming collisions:

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

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

HELPFUL: The CLI command [`ng generate directive`](tools/cli/schematics) scaffolds a directive along with its test file.

A directive can change its host declaratively through host bindings or imperatively through a reference to the host element. This example [injects](guide/di) [`ElementRef`](api/core/ElementRef) and accesses the element through its `nativeElement` property to set the background to yellow:

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

IMPORTANT: Directives _do not_ support namespaces.

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

## 어트리뷰트 디렉티브 만들기 {#building-an-attribute-directive}

커스텀 어트리뷰트 디렉티브는 `@Directive()` 데코레이터가 있는 JavaScript 클래스입니다.
데코레이터의 `selector`는 디렉티브를 적용할 어트리뷰트를 정의합니다.
대괄호를 사용하면 어트리뷰트 셀렉터가 되므로 해당 어트리뷰트가 있는 엘리먼트에 디렉티브가 적용됩니다.
이름 충돌을 방지하려면 관례에 따라 `app` 같은 접두사를 사용하세요.

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

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

참고: CLI 명령어 [`ng generate directive`](tools/cli/schematics)를 사용하면 디렉티브와 테스트 파일의 기본 구조를 생성할 수 있습니다.

디렉티브는 호스트 바인딩으로 호스트를 선언적으로 변경하거나, 호스트 엘리먼트의 참조를 통해 명령형으로 변경할 수 있습니다.
다음 예제는 [`ElementRef`](api/core/ElementRef)를 [주입](guide/di)받고 `nativeElement` 프로퍼티로 엘리먼트에 접근해서 배경을 노란색으로 설정합니다.

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

중요: 디렉티브는 네임스페이스를 지원하지 _않습니다_.

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

<!--
## Applying an attribute directive

To apply the directive, add its selector as an attribute on an element:

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

Angular creates an instance of `HighlightDirective` for that `<p>` element, injects a reference to the element, and sets its background to yellow.
-->

## 어트리뷰트 디렉티브 적용하기 {#applying-an-attribute-directive}

엘리먼트에 디렉티브 셀렉터를 어트리뷰트로 추가하면 디렉티브를 적용할 수 있습니다.

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

Angular는 해당 `<p>` 엘리먼트에 `HighlightDirective` 인스턴스를 생성하고, 엘리먼트의 참조를 주입한 뒤 배경을 노란색으로 설정합니다.

<!--
## Handling user events

To respond to user interaction, bind host element events to handler methods through the `host` property of the `@Directive()` decorator. The following directive highlights the host element while the pointer is over it and clears the highlight when the pointer leaves:

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

The `host` property maps the `mouseenter` and `mouseleave` events to the `onMouseEnter()` and `onMouseLeave()` methods, which delegate to a `highlight()` helper that sets the background color on the host element. For more on host event bindings, see [binding to the host element](guide/components/host-elements#binding-to-the-host-element).
-->

## 사용자 이벤트 처리하기 {#handling-user-events}

사용자 상호작용에 반응하려면 `@Directive()` 데코레이터의 `host` 프로퍼티에서 호스트 엘리먼트의 이벤트를 핸들러 메서드에 바인딩하세요.
다음 디렉티브는 포인터가 호스트 엘리먼트 위에 있는 동안 엘리먼트를 강조하고, 포인터가 벗어나면 강조를 해제합니다.

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

`host` 프로퍼티는 `mouseenter`와 `mouseleave` 이벤트를 `onMouseEnter()`와 `onMouseLeave()` 메서드에 연결합니다.
이 메서드들은 호스트 엘리먼트의 배경색을 설정하는 `highlight()` 헬퍼를 호출합니다.
호스트 이벤트 바인딩은 [호스트 엘리먼트에 바인딩하기](guide/components/host-elements#binding-to-the-host-element)를 참고하세요.

<!--
## Accepting input values

Like components, directives accept inputs through the [`input()`](guide/components/inputs) function. Give an input the same name as the selector so that a single binding both applies the directive and passes a value to it:

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

Read the input by calling it as a signal, and fall back to a default when no color is set:

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

In the template, bind the value to the selector. Because the input shares the selector's name, `[appHighlight]` both applies the directive and sets its value. Here the bound `color` is a property on the component:

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

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

A directive can declare more than one input. The following directive adds a `defaultColor` input, then falls back through `appHighlight`, `defaultColor`, and finally `red`:

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

Bind both inputs on the same element. Because `defaultColor` takes a static string rather than a dynamic expression, it doesn't need square brackets:

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

## 입력값 받기 {#accepting-input-values}

컴포넌트와 마찬가지로 디렉티브도 [`input()`](guide/components/inputs) 함수로 입력값을 받습니다.
입력 프로퍼티의 이름을 셀렉터와 같게 지정하면 하나의 바인딩으로 디렉티브를 적용하면서 값을 전달할 수 있습니다.

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

입력 프로퍼티를 시그널처럼 호출해서 값을 읽고, 색상을 지정하지 않으면 기본값을 사용하세요.

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

템플릿에서는 셀렉터에 값을 바인딩합니다.
입력 프로퍼티와 셀렉터의 이름이 같으므로 `[appHighlight]`는 디렉티브를 적용하고 값도 설정합니다.
여기서 바인딩한 `color`는 컴포넌트의 프로퍼티입니다.

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

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

디렉티브에는 여러 입력 프로퍼티를 선언할 수 있습니다.
다음 디렉티브는 `defaultColor` 입력 프로퍼티를 추가하고, `appHighlight`, `defaultColor`, 마지막으로 `red` 순서로 사용할 색상을 결정합니다.

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

같은 엘리먼트에 두 입력 프로퍼티를 바인딩하세요.
`defaultColor`에는 동적인 표현식 대신 정적인 문자열을 전달하므로 대괄호가 필요하지 않습니다.

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

## Angular 처리 중단하기: `NgNonBindable`

<!--
To prevent expression evaluation in the browser, add `ngNonBindable` to the host element.
`ngNonBindable` deactivates interpolation, directives, and binding in templates.

In the following example, the expression `{{ 1 + 1 }}` renders just as it does in your code editor, and does not display `2`.

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

Applying `ngNonBindable` to an element stops binding for that element's child elements.
However, `ngNonBindable` still lets directives work on the element where you apply `ngNonBindable`.
In the following example, the `appHighlight` directive is still active but Angular does not evaluate the expression `{{ 1 + 1 }}`.

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

If you apply `ngNonBindable` to a parent element, Angular disables interpolation and binding of any sort, such as property binding or event binding, for the element's children.
-->

브라우저에서 Angular 표현식을 평가하지 않으려면 호스트 엘리먼트에 `ngNonBindable`을 추가하면 됩니다.
`ngNonBindable`은 문자열 바인딩, 디렉티브 동작, 템플릿의 바인딩을 비활성화합니다.

아래 예제 코드에서 `{{ 1 + 1 }}` 라는 표현식은 평가되지 않고 그대로 화면에 표시됩니다.

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

엘리먼트에 `ngNonBindable`을 지정하면 이 엘리먼트의 자식 엘리먼트의 바인딩이 중단됩니다.
하지만 `ngNonBindable`이 적용된 엘리먼트 자체에는 디렉티브 동작이 중단되지 않습니다.
아래 예제 코드처럼 구현하면, `appHighlight` 디렉티브는 여전히 동작하지만 표현식 `{{ 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`을 적용하면 됩니다.

## 다음 단계 {#whats-next}

# 구조 디렉티브(Structural Directives)

구조 디렉티브는 `<ng-template>` 엘리먼트에 적용되어 조건에 따라 내용물을 렌더링하거나, `<ng-template>` 내용물을 반복해서 렌더링하는 디렉티브입니다.

일반적인 조건부 렌더링이나 반복 렌더링에는 Angular의 내장 [제어 흐름 블록](guide/templates/control-flow)(`@if`, `@for`, `@switch`)을 사용하세요.
권한 검사에 따라 콘텐츠를 표시하거나 외부 소스의 데이터를 템플릿에 제공하는 등, 제어 흐름 블록만으로 처리할 수 없는 재사용 가능한 렌더링 동작이 필요할 때 구조 디렉티브를 작성하세요.

## 활용 예제

<!--
This guide uses a directive called `SelectDirective` as its running example. The directive fetches data from a given data source and renders its template when that data is available. It is named after the SQL keyword `SELECT` and matched with an attribute selector, `[select]`.

`SelectDirective` has an input naming the data source to use, called `selectFrom`. The `select` prefix for this input is important for the [shorthand syntax](#structural-directive-shorthand). The directive instantiates its `<ng-template>` with a template context providing the selected data.

Using this directive directly on an `<ng-template>` looks like this:

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

The structural directive can wait for the data to become available and then render its `<ng-template>`.

HELPFUL: Angular's `<ng-template>` element defines a template that doesn't render anything by default. If you wrap elements in an `<ng-template>` without applying a structural directive, those elements are not rendered.

For more information, see the [ng-template API](api/core/ng-template) documentation.
-->

이 문서에서는 데이터 소스에서 데이터를 받아와서 해당 데이터가 준비되었을 때 템플릿에 렌더링하는 구조 디렉티브를 만들어 봅시다.
이 디렉티브는 SQL 키워드 `SELECT`를 따와서 `SelectDirective`라고 하며, 어트리뷰트 셀렉터는 `[select]`로 지정합니다.

`SelectDirective`는 데이터 소스 이름을 `selectFrom` 입력으로 받습니다.
이때 사용한 `select` 접두사는 [단축 문법](#구조-디렉티브-단축-문법)입니다.
디렉티브는 데이터가 준비되면 이 데이터를 제공하는 템플릿 컨텍스트를 구성하며 `<ng-template>` 인스턴스를 생성합니다.

디렉티브를 `<ng-template>`에 직접 사용하면 이렇게 작성할 수 있습니다:

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

그러면 구조 디렉티브는 데이터를 사용할 수 있을 때까지 기다린 후에, `<ng-template>`을 화면에 렌더링합니다.

참고: Angular가 제공하는 `<ng-template>` 엘리먼트는 템플릿을 정의하며, 그 자체로는 화면에 아무것도 렌더링하지 않습니다. `<ng-template>` 엘리먼트는 구조 디렉티브와 함께 사용합니다.

더 자세한 내용을 확인하려면 [ng-template API](api/core/ng-template) 문서를 참고하세요.

## 구조 디렉티브 단축 문법

<!--
Angular supports a shorthand syntax for structural directives which avoids the need to explicitly author an `<ng-template>` element.

Structural directives can be applied directly on an element by prefixing the directive attribute selector with an asterisk (`*`), such as `*select`. Angular transforms the asterisk in front of a structural directive into an `<ng-template>` that hosts the directive and surrounds the element and its descendants.

You can use this with `SelectDirective` as follows:

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

This example shows the flexibility of structural directive shorthand syntax, which is sometimes called _microsyntax_.

When used in this way, only the structural directive and its bindings are applied to the `<ng-template>`. Any other attributes or bindings on the `<p>` tag are left alone. For example, these two forms are equivalent:

```html
<!- Shorthand syntax: ->
<p class="data-view" *select="let data; from: source">The data is: {{ data }}</p>

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

Shorthand syntax is expanded through a set of conventions. A more thorough [grammar](#structural-directive-syntax-reference) is defined below, but in the above example, this transformation can be explained as follows:

The first part of the `*select` expression is `let data`, which declares a template variable `data`. Since no assignment follows, the template variable is bound to the template context property `$implicit`.

The second piece of syntax is a key-expression pair, `from source`. `from` is a binding key and `source` is a regular template expression. Binding keys are mapped to properties by transforming them to PascalCase and prepending the structural directive selector. The `from` key is mapped to `selectFrom`, which is then bound to the expression `source`. This is why many structural directives will have inputs that are all prefixed with the structural directive's selector.
-->

Angular는 `<ng-template>` 엘리먼트 사용을 생략할 수 있도록 구조 디렉티브에 사용할 수 있는 단축 문법을 제공합니다.

구조 디렉티브는 엘리먼트에 사용하는 디렉티브 어트리뷰트 셀렉터 앞에 아스테리스크(`*`)를 붙여서 `*select`와 같이 지정할 수 있습니다.
그러면 Angular는 구조 디렉티브 앞에 붙은 아스테리스크를 `<ng-template>`으로 변환해서 엘리먼트를 감쌉니다.

그래서 `SelectDirective` 는 이렇게도 사용할 수 있습니다:

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

이 방식은 구조 디렉티브를 유연하게 사용하는 단축 문법이며, _마이크로 문법(microsyntax)_ 라고도 합니다.

이렇게 사용하면 구조 디렉티브 자체와 구조 디렉티브 바인딩은 `<ng-template>`으로 옮겨갑니다.
그리고 다른 어트리뷰트와 바인딩은 원래 엘리먼트에 그대로 남습니다.
그래서 아래 두 코드가 실행되는 결과는 같습니다:

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

단축 문법은 사용자 편의를 위해 제공되는 것입니다.
더 자세한 [문법](#구조-디렉티브-문법)은 아래에서 설명하며, 위 코드에 대해 간단하게 설명하면 이렇습니다:

`*select` 표현식은 `let data`와 같습니다.
템플릿 변수 `data`를 선언합니다.
그런데 이 선언문 뒤에 할당 표현이 없기 때문에 템플릿 변수 `data` 값은 템플릿 컨텍스트에 존재하는 `$implicit` 값이 됩니다.

두번째 부분 `from source`는 키-표현식 쌍입니다.
`from`은 바인딩 키이며, `source`는 일반적인 템플릿 표현식입니다.
바인딩 키는 파스칼 케이스(PascalCase)로 변환되어 구조 디렉티브 셀렉터 뒤에 오는 구문의 프로퍼티와 맵핑됩니다.
그래서 `from` 키는 `selectFrom`과 매핑되어 `source` 표현식과 바인딩됩니다.
구조 디렉티브는 보통 구조 디렉티브의 셀렉터와 같은 접두사를 사용하는 것이 일반적입니다.

## 구조 디렉티브는 엘리먼트에 하나씩

단축 문법을 사용하는 경우에 구조 디렉티브는 엘리먼트에 하나만 사용할 수 있습니다.
왜냐하면 구조 디렉티브마다 `<ng-template>` 엘리먼트가 연결되어야 하기 때문입니다.
디렉티브를 여러 개 사용한다면 `<ng-template>`을 여러 개 중첩해야 하는데, 이 경우에는 어떤 디렉티브를 먼저 적용해야 하는지 결정할 수 없습니다.
구조 디렉티브 여러 개를 DOM 엘리먼트나 컴포넌트 하나에 적용해야 한다면, `<ng-container>`를 사용해서 가상으로 중첩된 DOM 구조를 만들면 됩니다.

<!--
## Creating a structural directive

A structural directive is a directive class that injects two dependencies:

- [`TemplateRef`](api/core/TemplateRef) gives the directive access to the content of the `<ng-template>` it is applied to.
- [`ViewContainerRef`](api/core/ViewContainerRef) represents the location in the DOM where the directive can render that template.

The directive controls rendering by creating, or not creating, embedded views from the template in the view container. The complete `SelectDirective` looks like this:

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

selectFrom = input.required<DataSource<unknown>>();

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

The `selectFrom` input names the data source the directive reads from. It uses [`input.required()`](guide/components/inputs#required-inputs) because the directive can't do anything useful without a data source.

When Angular initializes the directive, it loads the data and then renders the template by calling `createEmbeddedView()`. The second argument is the template's _context object_: values the template can bind to with `let` declarations. Assigning the data to the `$implicit` key makes it the default value that `let-data` (or `let data` in shorthand) receives.

NOTE: This example renders its template once, when the directive initializes. It does not re-render when the bound data source changes.

Once the directive works, consider [adding template type-checking support](#typing-the-directives-context).

HELPFUL: The CLI command [`ng generate directive`](tools/cli/schematics) scaffolds a directive along with its test file.
-->

## 구조 디렉티브 만들기 {#creating-a-structural-directive}

구조 디렉티브는 다음 두 의존성을 주입받는 디렉티브 클래스입니다.

- [`TemplateRef`](api/core/TemplateRef): 디렉티브가 적용된 `<ng-template>`의 콘텐츠에 접근할 수 있습니다.
- [`ViewContainerRef`](api/core/ViewContainerRef): 디렉티브가 템플릿을 렌더링할 DOM 위치를 나타냅니다.

디렉티브는 뷰 컨테이너에 템플릿의 내장 뷰를 생성할지 결정해서 렌더링을 제어합니다.
완성된 `SelectDirective`는 다음과 같습니다.

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

selectFrom = input.required<DataSource<unknown>>();

`selectFrom` 입력 프로퍼티는 디렉티브가 읽을 데이터 소스를 지정합니다.
데이터 소스가 없으면 디렉티브가 의미 있는 작업을 할 수 없으므로 [`input.required()`](guide/components/inputs#required-inputs)를 사용합니다.

Angular가 디렉티브를 초기화하면 데이터를 로드한 뒤 `createEmbeddedView()`를 호출해서 템플릿을 렌더링합니다.
두 번째 인자는 `let` 선언으로 템플릿에서 바인딩할 수 있는 값들을 담은 _컨텍스트 객체_ 입니다.
데이터를 `$implicit` 키에 할당하면 `let-data`(단축 문법에서는 `let data`)가 받는 기본값이 됩니다.

참고: 이 예제는 디렉티브를 초기화할 때 템플릿을 한 번 렌더링합니다. 바인딩한 데이터 소스가 변경되어도 다시 렌더링하지 않습니다.

디렉티브가 동작하면 [템플릿 타입 검사 지원 추가하기](#typing-the-directives-context)를 고려하세요.

참고: CLI 명령어 [`ng generate directive`](tools/cli/schematics)를 사용하면 디렉티브와 테스트 파일의 기본 구조를 생성할 수 있습니다.

## 구조 디렉티브 문법

<!--
When you write your own structural directives, use the following syntax:

```ts
{hideCopy}
_: prefix = "( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )_";
```

The following patterns describe each portion of the structural directive grammar:

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

구조 디렉티브에는 이런 문법을 사용합니다:

```ts
{hideCopy}
_: prefix = "( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )_";
```

구조 디렉티브 문법 각각의 역할은 이렇습니다:

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

### Angular가 단축 문법을 처리하는 방식

<!--
Angular translates structural directive shorthand into the normal binding syntax as follows:

Angular는 구조 디렉티브 단축 문법을 다음과 같이 일반 바인딩 문법으로 변환해서 처리합니다:

### 단축 문법 예제

<!--
The following table provides shorthand examples:

| Shorthand                                                             | How Angular interprets the syntax                                                                             |
| :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| `*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">`                                                               |
-->

단축 문법이 어떻게 사용되는지 몇 가지 예제를 살펴봅시다:

| 단축 문법                                                             | 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">`                                                               |

## 템플릿 타입 검사 강화하기

<!--
You can improve template type checking for custom directives by adding template guards to your directive definition.
These guards help the Angular template type checker find mistakes in the template at compile time, which can avoid runtime errors.
Two different types of guards are possible:

- `ngTemplateGuard_(input)` lets you control how an input expression should be narrowed based on the type of a specific input.
- `ngTemplateContextGuard` is used to determine the type of the context object for the template, based on the type of the directive itself.

This section provides examples of both kinds of guards.
For more information, see [Template type checking](tools/cli/template-typecheck 'Template type-checking guide').
-->

디렉티브를 정의할 때 템플릿 가드를 추가하면 템플릿 타입 검사를 강화할 수 있습니다.
이 가드를 추가하면 컴파일 시점에 Angular 템플릿 타입 검사기가 동작하면서 실수를 찾아낼 수 있기 때문에, 실행 시점에 오류가 발생하는 것을 방지합니다.
가드는 두 가지 종류가 있습니다:

- `ngTemplateGuard_(input)` - 입력값의 타입에 따라 입력 표현식 타입을 좁힐 수 있습니다. -`ngTemplateContextGuard` - 디렉티브 자체 타입에 따라 템플릿 컨텍스트 객체의 타입을 결정합니다.

이번 섹션에서는 두 가드의 예제만 다룹니다.
더 자세한 내용은 [템플릿 타입 검사](tools/cli/template-typecheck 'Template type-checking guide') 문서를 참고하세요.

### 템플릿 가드로 타입 좁히기

<!--
A structural directive in a template controls whether that template is rendered at run time. Some structural directives want to perform type narrowing based on the type of input expression.

There are two narrowings which are possible with input guards:

- Narrowing the input expression based on a TypeScript type assertion function.
- Narrowing the input expression based on its truthiness.

To narrow the input expression by defining a type assertion function:

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

Type-checking will behave within the template as if the `ngTemplateGuard_actor` has been asserted on the expression bound to the input.

Some directives only render their templates when an input is truthy. It's not possible to capture the full semantics of truthiness in a type assertion function, so instead a literal type of `'binding'` can be used to signal to the template type-checker that the binding expression itself should be used as the guard:

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

static ngTemplateGuard_condition: 'binding';
}
```

The template type-checker will behave as if the expression bound to `condition` was asserted to be truthy within the template.
-->

템플릿에 사용되는 구조 디렉티브는 템플릿을 렌더링할지 결정합니다.
그래서 때로는 입력 표현식의 타입을 기반으로 타입을 좁혀야 하는 경우가 있습니다.

입력 가드로 타입을 좁히는 방법은 두 가지입니다:

- TypeScript 타입 단언(assertion) 함수를 사용해서 입력 표현식 타입을 좁히는 방법
- 입력 표현식의 참/거짓 여부로 입력 표현식 타입을 좁히는 방법

타입 단언 함수를 사용하는 방식은 이렇습니다:

```ts
// 이 디렉티브는 사용자가 사람일 때만 템플릿을 렌더링합니다.
// 이 경우 `actor` 표현식의 타입을 `User`로 좁힐 수 있습니다.
@Directive(...)
class ActorIsUser {
  actor = input<User | Robot>();

static ngTemplateGuard_actor(dir: ActorIsUser, expr: User | Robot): expr is User {
    // 반환 구문은 필요 없지만, TypeScript 에러를 방지하기 위해 선언합니다.
    return true;
  }
}
```

템플릿 안에서는 타입 검사가 마치 바인딩된 표현식에 `ngTemplateGuard_actor`가 타입 단언 함수로 사용되는 것처럼 동작합니다.

디렉티브 중에는 입력값이 참인 경우에 템플릿을 렌더링하는 경우가 있습니다.
이 경우에는 타입 검사 함수가 "참" 의 의미를 완벽하게 이해할 수는 없기 때문에, 바인딩 표현식에 가드를 사용해야 하는 것을 알리기 위해 `'binding'` 값을 사용합니다.

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

static ngTemplateGuard_condition: 'binding';
}
```

템플릿 타입 검사기는 이제 `condition`에 바인딩된 표현식이 참으로 평가되는 것을 확인한 것처럼 동작합니다.

### 디렉티브 컨텍스트에 타입 지정하기 {#typing-the-directives-context}

<!--
If your structural directive provides a context to the instantiated template, you can properly type it inside the template by providing a static `ngTemplateContextGuard` type assertion function. This function can use the type of the directive to derive the type of the context, which is useful when the type of the directive is generic.

For the `SelectDirective` described above, you can implement an `ngTemplateContextGuard` to correctly specify the data type, even if the data source is 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;
  }
}
```
-->

템플릿 안에서 구조 디렉티브의 인스턴스가 생성되면, 정적 `ngTemplateContextGuard` 타입 단언 함수를 사용해서 템플릿 안에 있는 타입을 지정할 수 있습니다.
이 함수는 디렉티브 타입을 활용할 수 있기 때문에 디렉티브가 제네릭 타입인 경우 특히 유용합니다.

위에서 살펴봤던 `SelectDirective`의 경우에는 데이터 소스가 제네릭인 경우라도 `ngTemplateContextGuard`를 정의해서 데이터 타입을 정확하게 지정할 수 있습니다.

```ts
// 템플릿 컨텍스트를 표현하는 인터페이스를 선언합니다:
export interface SelectTemplateContext<T> {
  $implicit: T;
}

@Directive(...)
export class SelectDirective<T> {
  // 입력으로 받은 `DataSource`를 제네릭 `T` 타입으로 선언합니다.
  selectFrom = input.required<DataSource<T>>();

// 디렉티브의 제네릭 타입을 활용해서 컨텍스트의 타입을 좁힙니다.
  static ngTemplateContextGuard<T>(dir: SelectDirective<T>, ctx: any): ctx is SelectTemplateContext<T> {
    // 이전에 봤던 예제처럼, 가드 함수는 실행 시점에 실제로 실행되지 않지만, TypeScript 에러를 방지하기 위해 선언합니다.
    return true;
  }
}
```

## 다음 단계 {#whats-next}

# 디렉티브 조합 API

<!--
Angular directives offer a great way to encapsulate reusable behaviors. Directives can apply attributes, CSS classes, and event listeners to an element.

The _directive composition API_ lets you apply directives to a component's host element from _within_ the component TypeScript class.
-->

Angular 디렉티브는 재사용을 염두에 두고 캡슐화되어 설계되었습니다.
디렉티브는 엘리먼트에 어트리뷰트, CSS 클래스, 이벤트 리스너를 적용할 수 있습니다.

_디렉티브 조합 API_ 를 활용하면 컴포넌트 TypeScript 클래스 _안에서_ 컴포넌트 호스트 엘리먼트에 디렉티브를 적용할 수 있습니다.

## 컴포넌트에 디렉티브 추가하기

<!--
You apply directives to a component by adding a `hostDirectives` property to a component's decorator. Such directives are called _host directives_.

In this example, the `MenuBehavior` directive is applied to the host element of `AdminMenu`. This works similarly to applying the `MenuBehavior` to the `<admin-menu>` element in a template.

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

When the framework renders a component, Angular also creates an instance of each host directive. The directives' host bindings apply to the component's host element. By default, host directive inputs and outputs are not exposed as part of the component's public API. See [Including inputs and outputs](#including-inputs-and-outputs) below for more information.

Host directives come with the following constraints:

- **Angular applies host directives statically at compile time.** You cannot dynamically add
  directives at runtime.
- **Directives used in `hostDirectives` may not specify `standalone: false`.**
- **Angular ignores the `selector` of directives applied in the `hostDirectives` property.**
-->

컴포넌트 데코레이터에 `hostDirectives` 프로퍼티를 추가하면 적용할 수 있습니다.
이렇게 사용하는 디렉티브를 _호스트 디렉티브(host directive)_ 라고 합니다.

위 예제에서는 `MenuBehavior` 디렉티브를 `AdminMenu`의 호스트 엘리먼트에 적용했습니다.
이 방식은 템플릿에서 `<admin-menu>` 엘리먼트에 `MenuBehavior` 디렉티브를 적용한 것과 같은 효과입니다.

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

프레임워크가 컴포넌트를 렌더링할 때 Angular는 호스트 디렉티브마다 각각 인스턴스를 생성합니다.
그리고 이 디렉티브는 컴포넌트의 호스트 엘리먼트에 호스트 바인딩됩니다.
기본적으로 호스트 디렉티브의 입출력 프로퍼티는 컴포넌트 public API처럼 컴포넌트 밖으로 노출되지 않습니다.
자세한 내용은 아래 [입출력 프로퍼티 지정하기](#입출력-프로퍼티-지정하기) 섹션을 참고하세요.

**호스트 디렉티브는 컴파일 시점에 정적으로 적용됩니다.**
실행 시점에는 디렉티브를 동적으로 적용할 수 없습니다.

**`hostDirectives`에 사용된 디렉티브는 `standalone: false`를 지정해서는 안 됩니다.**

**`hostDirectives` 프로퍼티에 적용된 디렉티브의 `selector`는 무시합니다.**

## 입출력 프로퍼티 지정하기

<!--
When you apply `hostDirectives` to your component, the inputs and outputs from the host directives are not included in your component's API by default. You can explicitly include inputs and outputs in your component's API by expanding the entry in `hostDirectives`:

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

By explicitly specifying the inputs and outputs, consumers of the component with `hostDirectives` can bind them in a template:

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

Furthermore, you can alias inputs and outputs from a host directive to customize the API of your component:

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

컴포넌트에 `hostDirectives`를 적용하더라도 호스트 디렉티브의 입출력 프로퍼티는 컴포넌트 API에 기본으로 포함되지 않습니다.
그렇다면 `hostDirectives` 설정을 변경해서 디렉티브의 입출력 프로퍼티를 컴포넌트 API에 등록해야 합니다:

입출력 프로퍼티를 등록하고 나면 템플릿에서 이렇게 사용할 수 있습니다:

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

그리고 `hostDirectives`에 입출력 프로퍼티를 등록할 때 별칭을 지정할 수도 있습니다:

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

## 디렉티브를 다른 디렉티브에 적용하기

<!--
You can also add `hostDirectives` to other directives, in addition to components. This enables the transitive aggregation of multiple behaviors.

The following example defines two directives, `Menu` and `Tooltip`, then composes their behavior in `MenuWithTooltip`. Finally, it applies `MenuWithTooltip` to `SpecializedMenuWithTooltip`.

When `SpecializedMenuWithTooltip` is used in a template, it creates instances of all of `Menu`, `Tooltip`, and `MenuWithTooltip`. Each of these directives' host bindings apply to the host element of `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 {}
```

-->

컴포넌트뿐 아니라 다른 디렉티브에서 `hostDirectives`를 활용할 수도 있습니다.
이 방식을 활용하면 디렉티브 여러 개를 한 번에 적용할 수 있습니다.

아래 예제에는 `Menu` 디렉티브와 `Tooltip` 디렉티브가 있습니다.
두 디렉티브를 `MenuWithTooltip` 디렉티브로 합쳐봅시다.
그리고 최종적으로는 `MenuWithTooltip`을 `SpecializedMenuWithTooltip`에 적용해 봅시다.

템플릿에 `SpecializedMenuWithTooltip`이 사용되면 Angular는 `Menu`, `Tooltip`, `MenuWithTooltip` 인스턴스를 각각 생성합니다.
그러고 나면 이 디렉티브들이 각각 `SpecializedMenuWithTooltip` 호스트 엘리먼트에 적용됩니다.

```ts
@Directive({/* ... */})
export class Menu {}

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

// MenuWithTooltip은 디렉티브 여러 개를 결합하는 디렉티브입니다.
@Directive({
  hostDirectives: [Tooltip, Menu],
})
export class MenuWithTooltip {}

// 디렉티브가 결합된 MenuWithToolTip을 최종 목적지에 적용합니다.
@Directive({
  hostDirectives: [MenuWithTooltip],
})
export class SpecializedMenuWithTooltip {}
```

## 호스트 디렉티브 활용

### 디렉티브 실행 순서

<!--
Host directives go through the same lifecycle as components and directives used directly in a template. However, host directives always execute their constructor, lifecycle hooks, and bindings _before_ the component or directive on which they are applied.

The following example shows minimal use of a host directive:

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

The order of execution here is:

1. `MenuBehavior` instantiated
2. `AdminMenu` instantiated
3. `MenuBehavior` receives inputs (`ngOnInit`)
4. `AdminMenu` receives inputs (`ngOnInit`)
5. `MenuBehavior` applies host bindings
6. `AdminMenu` applies host bindings

This order of operations means that components with `hostDirectives` can override any host bindings specified by a host directive.

This order of operations extends to nested chains of host directives, as shown in the following example.

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

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

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

In the example above, the order of execution is:

1. `Tooltip` instantiated
2. `CustomTooltip` instantiated
3. `EvenMoreCustomTooltip` instantiated
4. `Tooltip` receives inputs (`ngOnInit`)
5. `CustomTooltip` receives inputs (`ngOnInit`)
6. `EvenMoreCustomTooltip` receives inputs (`ngOnInit`)
7. `Tooltip` applies host bindings
8. `CustomTooltip` applies host bindings
9. `EvenMoreCustomTooltip` applies host bindings
-->

템플릿에 직접 사용된 호스트 디렉티브는 컴포넌트나 디렉티브와 동일한 라이프사이클을 갖습니다.
하지만 호스트 디렉티브도 클래스 생성자와 라이프사이클 훅이 실행되는데, 이 동작은 컴포넌트나 디렉티브에 바인딩되기 _전에_ 실행됩니다.

예제를 보며 확인해 봅시다:

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

위 코드는 아래 순서대로 실행됩니다:

1. `MenuBehavior` 인스턴스가 생성됩니다.
2. `AdminMenu` 인스턴스가 생성됩니다.
3. `MenuBehavior` 가 입력 프로퍼티로 입력을 받습니다. (`ngOnInit`)
4. `AdminMenu` 가 입력 프로퍼티로 입력을 받습니다. (`ngOnInit`)
5. `MenuBehavior` 호스트 바인딩이 적용됩니다.
6. `AdminMenu` 호스트 바인딩이 적용됩니다.

실행 순서가 이렇기 때문에, `hostDirectives`를 사용하는 컴포넌트는 호스트 디렉티브에 지정된 호스트 바인딩을 오버라이드할 수 있습니다.

디렉티브 적용이 중첩된 경우도 방식은 같습니다.

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

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

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

위 코드는 아래 순서대로 실행됩니다:

1. `Tooltip` 인스턴스가 생성됩니다.
2. `CustomTooltip` 인스턴스가 생성됩니다.
3. `EvenMoreCustomTooltip` 인스턴스가 생성됩니다.
4. `Tooltip`이 입력 프로퍼티로 입력을 받습니다. (`ngOnInit`)
5. `CustomTooltip`이 입력 프로퍼티로 입력을 받습니다. (`ngOnInit`)
6. `EvenMoreCustomTooltip`이 입력 프로퍼티로 입력을 받습니다. (`ngOnInit`)
7. `Tooltip` 호스트 바인딩이 적용됩니다.
8. `CustomTooltip` 호스트 바인딩이 적용됩니다.
9. `EvenMoreCustomTooltip` 호스트 바인딩이 적용됩니다.

### 의존성 주입

<!--
A component or directive that specifies `hostDirectives` can inject the instances of those host directives and vice versa.

When applying host directives to a component, both the component and host directives can define providers.

If a component or directive with `hostDirectives` and those host directives both provide the same injection token, the providers defined by class with `hostDirectives` take precedence over providers defined by the host directives.
-->

`hostDirectives`를 지정하는 컴포넌트나 디렉티브는 호스트 디렉티브를 의존성으로 주입받아 참조할 수 있으며, 반대 경우도 마찬가지입니다.

호스트 디렉티브를 컴포넌트에 적용할 때 컴포넌트나 호스트 디렉티브 양쪽에서 프로바이더를 등록할 수 있습니다.

`hostDirectives`를 지정한 컴포넌트나 디렉티브, 그리고 호스트 디렉티브가 같은 의존성 토큰을 등록하는 경우에는, 호스트 디렉티브 프로바이더보다 `hostDirectives`를 지정한 클래스의 프로바이더 우선순위가 더 높습니다.

### 호스트 디렉티브 중복 제거

호스트 디렉티브 트리에 같은 디렉티브가 두 번 이상 사용되면, 오류를 발생시키는 대신 자동으로 중복이 제거됩니다.
어떤 항목이 유지될지는 다음 규칙을 따릅니다.

#### 템플릿 매칭을 우선합니다.

<!--
If a directive matches an element once through a **template selector** and also appears as a **host directive**, Angular keeps only the template match and discards all host directive matches.

The mental model is that a host directive match represents `Partial<YourDirective>`, a partial application where only the inputs and outputs explicitly listed in `hostDirectives` are exposed, while a template match represents the full directive with its complete public API.

```ts
@Directive({selector: '[hoverable]'})
export class Hoverable {}

@Component({
  selector: 'app-button',
  hostDirectives: [Hoverable],
})
export class Button {}
```

```html
<!- Hoverable is matched by selector AND as a host directive of Button. ->
<!- Angular keeps only the selector match, which has the full public API. ->
<app-button hoverable></app-button>
```
-->

디렉티브가 **템플릿 셀렉터** 와 **호스트 디렉티브** 에 동시에 사용되면, 템플릿 매칭이 적용되고 호스트 디렉티브 매칭은 모두 폐기합니다.

호스트 디렉티브 매칭이 `Partial<YourDirective>`와 같다고 생각하면 이해하기 쉽습니다.
입출력 프로퍼티는 `hostDirectives`에서 외부로 공개된 일부(`Partial`)를 의미합니다.
반면에, 템플릿 매칭은 디렉티브의 전체 public API와 매칭된다는 것을 의미합니다.

```ts
@Directive({selector: '[hoverable]'})
export class Hoverable {}

@Component({
  selector: 'app-button',
  hostDirectives: [Hoverable],
})
export class Button {}
```

```html


<app-button hoverable></app-button>
```

#### 호스트 디렉티브가 여러 개 매칭되면 합쳐집니다.

<!--
If the same directive appears **more than once as a host directive**, for example, when two directives both declare a common dependency in their `hostDirectives`, Angular merges all instances into a single directive instance. The input and output mappings from all instances are combined.

This resolves the classic [diamond problem](https://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem) in host directive composition:

```ts
// A shared behavior that both triggers need
@Directive({
  host: {
    '[attr.data-trigger-id]': 'triggerId()',
  },
})
export class TriggerRef {
  readonly triggerId = input(`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
<!- Angular keeps one TriggerRef instance, shared by both triggers. ->
<button popoverTrigger dropdownTrigger>Actions</button>
```

HELPFUL: Because Angular produces only one instance of the shared directive, both `PopoverTrigger` and `DropdownTrigger` receive the same `TriggerRef` instance when they inject it.
-->

동일한 디렉티브가 **호스트 디렉티브로 여러 번 나타나면** Angular는 인스턴스 하나로 합칩니다. 예를 들어 서로 다른 두 디렉티브의 `hostDirectives`가 같은 디렉티브를 참조하는 경우입니다.
모든 인스턴스의 입출력 프로퍼티 매핑도 함께 합쳐집니다.

이 정책은 흔히 발생하는 [다이아몬드 문제](https://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem)를 해결하기 위한 것입니다:

```ts
// 트리거 2개의 참조
@Directive({
  host: {
    '[attr.data-trigger-id]': 'triggerId()',
  },
})
export class TriggerRef {
  readonly triggerId = input(`trigger-${crypto.randomUUID()}`);
}

// 트리거는 2개지만, TriggerRef를 사용해서 호스트 디렉티브에 적용됩니다.
@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>
```

참고: 디렉티브가 중복되는 경우에는 인스턴스가 하나만 유지되기 때문에, `PopoverTrigger`와 `DropdownTrigger`는 동일한 `TriggerRef` 인스턴스를 의존성으로 주입받습니다.

#### 별칭이 겹치는 경우

<!--
When Angular merges duplicate host directive matches it also merges their input and output mappings.

If two instances of the same host directive expose the **same input or output under different aliases**, Angular throws an error at compile time ([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
<!- Error: triggerId is exposed as both "popoverTriggerId" and "dropdownTriggerId". ->
<button popoverTrigger dropdownTrigger></button>
```

To resolve this, ensure that both paths expose the shared input or output under the same alias, or do not expose it at all.

-->

호스트 디렉티브에 적용되는 입출력 프로퍼티는 모두 하나로 합쳐집니다.
그런데 같은 호스트 디렉티브에 **같은 입출력 프로퍼티가 다른 별칭으로 사용되면**, 컴파일 시점에 [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']}, // 다른 별칭을 지정!
  ],
})
export class DropdownTrigger {}
```

```html

<button popoverTrigger dropdownTrigger></button>
```

이 문제를 해결하려면 양쪽 경로에서 공유 입출력 프로퍼티를 동일한 별칭으로 공개하거나, 해당 프로퍼티를 아예 공개하지 마세요.

## 다음 단계 {#whats-next}

# NgOptimizedImage 활용하기

<!--
The `NgOptimizedImage` directive makes it easy to adopt performance best practices for loading images.

The directive ensures that the loading of the [Largest Contentful Paint (LCP)](https://web.dev/lcp) image is prioritized by:

- Automatically setting the `fetchpriority` attribute on the `<img>` tag
- Lazy loading other images by default
- Automatically generating a preconnect link tag in the document head
- Automatically generating a `srcset` attribute
- Generating a [preload hint](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload) if app is using SSR

In addition to optimizing the loading of the LCP image, `NgOptimizedImage` enforces a number of image best practices, such as:

- Using [image CDN URLs to apply image optimizations](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options)
- Preventing layout shift by requiring `width` and `height`
- Warning if `width` or `height` have been set incorrectly
- Warning if the image will be visually distorted when rendered

If you're using a background image in CSS, [start here](#how-to-migrate-your-background-image).

NOTE: Although the `NgOptimizedImage` directive was made a stable feature in Angular version 15, it has been backported and is available as a stable feature in versions 13.4.0 and 14.3.0 as well.
-->

`NgOptimizedImage` 디렉티브를 활용하면 이미지를 다루는 모범 사례를 간단하게 도입할 수 있습니다.

이 디렉티브는 아래 작업을 통해 [가장 큰 컨텐츠 페인트(Largest Contentful Paint, LCP)](https://web.dev/lcp) 성능을 끌어올립니다:

- `<img>` 태그에 `fetchpriority` 어트리뷰트를 자동으로 설정합니다.
- 기본적으로 이미지는 지연 로딩합니다.
- document 헤더에 사전 연결 링크 태그를 자동으로 생성합니다.
- `srcset` 어트리뷰트를 자동으로 생성합니다.
- SSR이 적용된 앱이라면 [사전 로딩 힌트](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload)를 생성합니다.

`NgOptimizedImage`는 LCP 이미지 로딩을 최적화하는 것 외에도, 이미지를 다루는 모범 사례를 제공합니다:

- [이미지 최적화를 위해 이미지 CDN URL](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options)을 사용합니다.
- `width`와 `height`를 강제해서 레이아웃 변경을 방지합니다.
- `width` 값이나 `height` 값이 잘못되면 경고를 표시합니다.
- 이미지를 렌더링할 때 왜곡이 발생할 것 같으면 경고를 표시합니다.

CSS 파일로 배경 이미지를 지정하고 있다면 [여기](#배경-이미지-마이그레이션하기)부터 참고하세요.

**참고: `NgOptimizedImage` 디렉티브는 Angular 15 버전부터 정식으로 도입되었지만, 하위 버전에도 백포팅되어 Angular 13.4.0이나 14.3.0에서도 사용할 수 있습니다.**

## 시작하기

<!--
<docs-workflow>
<docs-step title="Import `NgOptimizedImage` directive">
Import `NgOptimizedImage` directive from `@angular/common`:

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

and include it into the `imports` array of a standalone component or an NgModule:

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

</docs-step>
<docs-step title="(Optional) Set up a Loader">
An image loader is not **required** in order to use NgOptimizedImage, but using one with an image CDN enables powerful performance features, including automatic `srcset`s for your images.

A brief guide for setting up a loader can be found in the [Configuring an Image Loader](#configuring-an-image-loader-for-ngoptimizedimage) section at the end of this page.
</docs-step>
<docs-step title="Enable the directive">
To activate the `NgOptimizedImage` directive, replace your image's `src` attribute with `ngSrc`.

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

If you're using a [built-in third-party loader](#built-in-loaders), make sure to omit the base URL path from `src`, as that will be prepended automatically by the loader.
</docs-step>
<docs-step title="Mark images as `priority`">
Always mark the [LCP image](https://web.dev/lcp/#what-elements-are-considered) on your page as `priority` to prioritize its loading.

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

Marking an image as `priority` applies the following optimizations:

- Sets `fetchpriority=high` (read more about priority hints [here](https://web.dev/priority-hints))
- Sets `loading=eager` (read more about native lazy loading [here](https://web.dev/browser-level-image-lazy-loading))
- Automatically generates a [preload link element](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload) if [rendering on the server](guide/ssr).

Angular displays a warning during development if the LCP element is an image that does not have the `priority` attribute. A page’s LCP element can vary based on a number of factors - such as the dimensions of a user's screen, so a page may have multiple images that should be marked `priority`. See [CSS for Web Vitals](https://web.dev/css-web-vitals/#images-and-largest-contentful-paint-lcp) for more details.
</docs-step>
<docs-step title="Include Width and Height">
In order to prevent [image-related layout shifts](https://web.dev/css-web-vitals/#images-and-layout-shifts), NgOptimizedImage requires that you specify a height and width for your image, as follows:

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

For **responsive images** (images which you've styled to grow and shrink relative to the viewport), the `width` and `height` attributes should be the intrinsic size of the image file. For responsive images it's also important to [set a value for `sizes`.](#responsive-images)

For **fixed size images**, the `width` and `height` attributes should reflect the desired rendered size of the image. The aspect ratio of these attributes should always match the intrinsic aspect ratio of the image.

NOTE: If you don't know the size of your images, consider using "fill mode" to inherit the size of the parent container, as described below.
</docs-step>
</docs-workflow>
-->
<docs-workflow>
<a id="import-ngoptimizedimage-directive"></a>

<docs-step title="`NgOptimizedImage` 디렉티브 불러오기">
`@angular/common` 패키지에서 `NgOptimizedImage` 디렉티브를 불러옵니다:

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

그리고 독립 컴포넌트나 NgModule의 `imports` 배열에 추가합니다:

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

</docs-code>
</docs-step>
<a id="optional-set-up-a-loader"></a>

<docs-step title="(선택) 로더 설정하기">
NgOptimizedImage를 활용할 때 이미지 로더를 정하는 것이 **필수** 는 아니지만, 성능 향상을 위해서라면 이미지 엘리먼트에 `srcset`을 설정하고 이미지 CDN을 활용하는 것이 좋습니다.

이미지 로더를 어떻게 설정하는지 간단하게 알아보려면 [이미지 로더 설정하기](#ngoptimizedimage용-이미지-로더-설정하기) 섹션을 참고하세요.
</docs-step>
<a id="enable-the-directive"></a>

<docs-step title="디렉티브 활성화하기">
`NgOptimizedImage` 디렉티브를 활성화하기 위해, 이미지 엘리먼트의 `src` 어트리뷰트를 `ngSrc`로 변경합니다.

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

[내장 서드 파티 로더](#built-in-loaders)를 사용하고 있다면, `src`를 지정할 때 베이스 URL 경로는 제외하세요.
베이스 주소는 이미지 로더가 직접 적용합니다.
</docs-step>
<a id="mark-images-as-priority"></a>

<docs-step title="이미지에 `priority` 설정하기">
화면에서 [LCP 이미지](https://web.dev/lcp/#what-elements-are-considered)는 `priority`를 설정해서 로딩 우선순위를 높이세요.

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

이미지 엘리먼트에 `priority`를 적용하면 이런 최적화가 수행됩니다:

- `fetchpriority=high`가 설정됩니다. 사용할 수 있는 옵션은 [여기](https://web.dev/priority-hints)를 참고하세요.
- `loading=eager`가 설정됩니다. 기본 지연 로딩은 [여기](https://web.dev/browser-level-image-lazy-loading)를 참고하세요.
- [서버에서 렌더링하는 경우](guide/ssr)라면 [사전로드 링크 엘리먼트](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload)를 자동으로 생성합니다.

LCP 엘리먼트에 `priority` 어트리뷰트가 설정되어 있지 않으면 Angular는 경고를 표시합니다.
화면에 표시되는 LCP 엘리먼트는 사용자 화면 해상도 등 여러 가지 요인에 따라 다르게 표시될 수 있기 때문에, `priority`를 이미지 여러 개에 지정해야 할 수도 있습니다.
자세한 내용은 [웹 바이탈을 위한 CSS](https://web.dev/css-web-vitals/#images-and-largest-contentful-paint-lcp)를 참고하세요.
</docs-step>
<a id="include-width-and-height"></a>

<docs-step title="너비, 높이 지정하기">
[이미지 때문에 레이아웃이 변경되는 것](https://web.dev/css-web-vitals/#images-and-layout-shifts)을 방지하기 위해, NgOptimizedImage는 이미지의 너비와 높이 입력을 강제합니다:

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

뷰포트 크기에 따라 크기가 변경되거나 화면에서 없어지는 **반응형 이미지(responsive images)** 를 사용한다면, `width` 값과 `height` 값은 이미지 파일의 원래 크기로 지정하세요.
반응형 이미지는 [`sizes` 값을 설정하는 것](#반응형-이미지)도 중요합니다.

**고정 크기 이미지(fixed size images)** 는 화면에 표시하려는 `width` 값과 `height` 값을 지정하면 됩니다.
화면에 표시되는 가로-세로 비율은 이미지 자체의 가로-세로 비율과 같아야 합니다.

참고: 이미지의 크기를 정확하게 알지 못한다면, 부모 컨테이너를 채우는 "fill 모드" 사용을 고려해 보세요.
</docs-step>
</docs-workflow>

## `fill` 모드 사용하기

<!--
In cases where you want to have an image fill a containing element, you can use the `fill` attribute. This is often useful when you want to achieve a "background image" behavior. It can also be helpful when you don't know the exact width and height of your image, but you do have a parent container with a known size that you'd like to fit your image into (see "object-fit" below).

When you add the `fill` attribute to your image, you do not need and should not include a `width` and `height`, as in this example:

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

You can use the [object-fit](https://developer.mozilla.org/docs/Web/CSS/object-fit) CSS property to change how the image will fill its container. If you style your image with `object-fit: "contain"`, the image will maintain its aspect ratio and be "letterboxed" to fit the element. If you set `object-fit: "cover"`, the element will retain its aspect ratio, fully fill the element, and some content may be "cropped" off.

See visual examples of the above at the [MDN object-fit documentation.](https://developer.mozilla.org/docs/Web/CSS/object-fit)

You can also style your image with the [object-position property](https://developer.mozilla.org/docs/Web/CSS/object-position) to adjust its position within its containing element.

IMPORTANT: For the "fill" image to render properly, its parent element **must** be styled with `position: "relative"`, `position: "fixed"`, or `position: "absolute"`.
-->

이미지를 엘리먼트에 가득 채우고 싶다면 `fill` 어트리뷰트를 사용하면 됩니다.
이 방식은 이미지를 배경 이미지처럼 지정하려고 할 때 유용합니다.
그리고 이미지 자체의 너비와 높이는 모르지만, 부모 컨테이너의 크기를 알고 있을 때에도 활용할 수 있습니다.

이미지에 `fill` 어트리뷰트를 지정하면 `width`나 `height`를 지정할 수 없습니다.
예제 코드를 봅시다:

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

이미지를 컨테이너 가득 채울 때는 [object-fit](https://developer.mozilla.org/docs/Web/CSS/object-fit) CSS 프로퍼티를 사용할 수도 있습니다.
`object-fit: "contain"` 라고 지정하면 이미지는 비율을 유지한 채로 엘리먼트 범위를 넘지 않는 정도로 엘리먼트를 채웁니다.
그리고 `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)를 지정해서 이미지가 표시되는 위치를 지정할 수 있습니다.

중요: 이미지에 `fill` 어트리뷰트를 적용할 때는, 부모 엘리먼트에 `position: "relative"`, `position: "fixed"`, `position: "absolute"` 중에 하나가 **반드시** 설정되어야 합니다.

## 배경 이미지 마이그레이션하기

<!--
Here's a simple step-by-step process for migrating from `background-image` to `NgOptimizedImage`. For these steps, we'll refer to the element that has an image background as the "containing element":

1. Remove the `background-image` style from the containing element.
2. Ensure that the containing element has `position: "relative"`, `position: "fixed"`, or `position: "absolute"`.
3. Create a new image element as a child of the containing element, using `ngSrc` to enable the `NgOptimizedImage` directive.
4. Give that element the `fill` attribute. Do not include a `height` and `width`.
5. If you believe this image might be your [LCP element](https://web.dev/lcp/), add the `priority` attribute to the image element.

You can adjust how the background image fills the container as described in the [Using fill mode](#using-fill-mode) section.
-->

`background-image`를 `NgOptimizedImage`로 마이그레이션하는 과정을 간단하게 살펴봅시다.
다음 단계에서 이미지 배경이 들어가는 엘리먼트를 "컨테이너 엘리먼트"라고 하겠습니다:

1. 컨테이너 엘리먼트에서 `background-image` 스타일을 제거합니다.
2. 컨테이너 엘리먼트에 `position: "relative"`, `position: "fixed"`,  `position: "absolute"` 중에 하나가 지정되어 있는지 확인하세요.
3. 컨테이너 엘리먼트의 자식으로 이미지 엘리먼트를 선언하고 `ngSrc` 어트리뷰트를 붙여서 `NgOptimizedImage` 디렉티브를 연결합니다.
4. 이미지 엘리먼트에 `fill` 어트리뷰트를 지정합니다. `height`나 `width`는 지정하지 마세요.
5. 이 이미지가 [LCP 엘리먼트](https://web.dev/lcp/)라면, 이미지 엘리먼트에 `priority` 어트리뷰트를 지정합니다.

배경 이미지가 컨테이너를 어떻게 채울지 지정하려면 [fill 모드 사용하기](#fill-모드-사용하기) 섹션을 참고하세요.

## 플레이스홀더(placeholder) 사용하기

### 자동 플레이스홀더

<!--
NgOptimizedImage can display an automatic low-resolution placeholder for your image if you're using a CDN or image host that provides automatic image resizing. Take advantage of this feature by adding the `placeholder` attribute to your image:

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

Adding this attribute automatically requests a second, smaller version of the image using your specified image loader. This small image will be applied as a `background-image` style with a CSS blur while your image loads. If no image loader is provided, no placeholder image can be generated and an error will be thrown.

The default size for generated placeholders is 30px wide. You can change this size by specifying a pixel value in the `IMAGE_CONFIG` provider, as seen below:

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      placeholderResolution: 40
    }
  },
],
```

If you want sharp edges around your blurred placeholder, you can wrap your image in a containing `<div>` with the `overflow: hidden` style. As long as the `<div>` is the same size as the image (such as by using the `width: fit-content` style), the "fuzzy edges" of the placeholder will be hidden.
-->

이미지 크기를 자동으로 제공하는 CDN이나 이미지 호스팅 서비스를 사용한다면 NgOptimizedImage로 저해상도 플레이스 홀더를 자동으로 표시할 수 있습니다.
이미지 엘리먼트에 `placeholder` 어트리뷰트만 추가하면 됩니다:

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

이 어트리뷰트를 추가하면 NgOptimizedImage 디렉티브는 지정된 이미지 로더를 사용해서 저해상도 플레이스홀더를 자동으로 요청합니다.
이렇게 불러오는 이미지는 CSS 블러(blur) 효과가 적용된 `background-image` 스타일로 실제 이미지가 로드될 때까지 사용됩니다.
이미지 로더가 지정되지 않으면, 플레이스홀더를 불러올 수 없기 때문에 오류가 발생합니다.

플레이스홀더의 기본 너비는 30px 입니다.
이 기본 크기는 `IMAGE_CONFIG` 프로바이더를 사용해서 변경할 수 있습니다:

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      placeholderResolution: 40
    }
  },
],
```

플레이스홀더 주변이 흐릿하게 표시되는 것을 방지하려면, 컨테이너 엘리먼트 `<div>`에 `overflow: hidden` 스타일을 지정하면 됩니다.
`width: fit-content` 스타일을 지정해서 이미지와 `<div>` 엘리먼트의 크기가 동일한 경우에는, 플레이스홀더의 흐릿한 가장자리가 표시되지 않습니다.

### 데이터 URL 플레이스홀더

<!--
You can also specify a placeholder using a base64 [data URL](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) without an image loader. The data url format is `data:image/[imagetype];[data]`, where `[imagetype]` is the image format, just as `png`, and `[data]` is a base64 encoding of the image. That encoding can be done using the command line or in JavaScript. For specific commands, see [the MDN documentation](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs#encoding_data_into_base64_format). An example of a data URL placeholder with truncated data is shown below:

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder="data:image/png;base64,iVBORw0K..." />
```

However, large data URLs increase the size of your Angular bundles and slow down page load. If you cannot use an image loader, the Angular team recommends keeping base64 placeholder images smaller than 4KB and using them exclusively on critical images. In addition to decreasing placeholder dimensions, consider changing image formats or parameters used when saving images. At very low resolutions, these parameters can have a large effect on file size.
-->

플레이스홀더에는 이미지 로더 대신 base64 [데이터 URL](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs)을 사용할 수도 있습니다.
이 데이터 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)를 참고하세요.
데이터 URL은 아래와 같이 사용하면 됩니다:

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder="data:image/png;base64,iVBORw0K..." />
```

그런데, 데이터 URL의 크기가 커지면 Angular 빌드 결과물의 크기가 함께 커지기 때문에 페이지 로딩이 느려질 수 있습니다.
이미지 로더를 사용하지 못하는 경우에는 base64 플레이스홀더 이미지를 권장하지만, 이 크기는 최대 4KB를 넘지 않을 것을 권장합니다.
플레이스홀더의 크기를 줄일 수 없다면 이미지의 형식이나 변수를 조정해서 이미지의 크기를 줄이는 것도 고려할 만합니다.
해상도가 낮은 이미지라면 이런 변수 조정이 파일 크기에 큰 영향을 미칠 수 있습니다.

### 흐리게 처리되지 않는 플레이스홀더

<!--
By default, NgOptimizedImage applies a CSS blur effect to image placeholders. To render a placeholder without blur, provide a `placeholderConfig` argument with an object that includes the `blur` property, set to false. For example:

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder [placeholderConfig]="{blur: false}" />
```
-->

기본적으로 NgOptimizedImage는 이미지 플레이스 홀더에 CSS 블러 효과를 적용합니다.
플레이스홀더에 흐림 효과를 적용하지 않으려면 `placeholderConfig` 인자를 사용해서 `blur` 프로퍼티 값을 `false`로 지정하면 됩니다:

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder [placeholderConfig]="{blur: false}" />
```

## 이미지 스타일 조정하기

<!--
Depending on the image's styling, adding `width` and `height` attributes may cause the image to render differently. `NgOptimizedImage` warns you if your image styling renders the image at a distorted aspect ratio.

You can typically fix this by adding `height: auto` or `width: auto` to your image styles. For more information, see the [web.dev article on the `<img>` tag](https://web.dev/patterns/web-vitals-patterns/images/img-tag).

If the `width` and `height` attribute on the image are preventing you from sizing the image the way you want with CSS, consider using `fill` mode instead, and styling the image's parent element.
-->

이미지 엘리먼트에 `width`, `height` 어트리뷰트를 추가하면 이미지가 다르게 렌더링될 수 있습니다.
이런 경우 이미지 비율이 왜곡되면 `NgOptimizedImage`가 경고를 표시합니다.

일반적으로는 `height: auto`, `width: auto`를 사용하면 이 문제를 방지할 수 있습니다.
자세한 내용은 [web.dev의 `<img>` 태그](https://web.dev/patterns/web-vitals-patterns/images/img-tag) 문서를 참고하세요.

`width`, `height` 어트리뷰트 때문에 이미지를 원하는 대로 조정할 수 없다면, 이미지 엘리먼트에 `fill` 모드를 적용하고 부모 엘리먼트 스타일 조정을 고려해 보세요.

## 성능 향상

NgOptimizedImage는 앱 성능 향상을 위한 기능도 다양하게 제공합니다.
어떤 기능을 제공하는지 알아봅시다.

### 리소스 힌트 추가

<!--
A [`preconnect` resource hint](https://web.dev/preconnect-and-dns-prefetch) for your image origin ensures that the LCP image loads as quickly as possible.

Preconnect links are automatically generated for domains provided as an argument to a [loader](#optional-set-up-a-loader). If an image origin cannot be automatically identified, and no preconnect link is detected for the LCP image, `NgOptimizedImage` will warn during development. In that case, you should manually add a resource hint to `index.html`. Within the `<head>` of the document, add a `link` tag with `rel="preconnect"`, as shown below:

```html
<link rel="preconnect" href="https://my.cdn.origin" />
```

To disable preconnect warnings, inject the `PRECONNECT_CHECK_BLOCKLIST` token:

```ts
providers: [
{provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
],

```

See more information on automatic preconnect generation [here](#why-is-a-preconnect-element-not-being-generated-for-my-image-domain).
-->

LCP 이미지를 최대한 빠르게 로드하려면 [`preconnect` 리소스 힌트](https://web.dev/preconnect-and-dns-prefetch)를 사용하면 됩니다.

사전 연결 링크는 [로더](#선택-로더-설정하기)에 인자로 전달되는 도메인에 대해 자동으로 생성됩니다.
이미지의 출처를 자동으로 감지할 수 없는 경우에는, LCP 이미지라고 해도 사전 연결 링크가 생성되지 않으며, 개발 서버에서는 `NgOptimizedImage`가 경고를 표시합니다.
이런 경우는 `index.html`에 리소스 힌트를 직접 추가하면 됩니다.
아래 예제 코드와 같이 도큐먼트의 `<head>`에 `link` 태그를 추가하고 `rel="preconnect"`를 지정하면 됩니다:

```html
<link rel="preconnect" href="https://my.cdn.origin" />
```

사전 연결 경고를 무시하려면 `PRECONNECT_CHECK_BLOCKLIST` 토큰을 의존성으로 주입하면 됩니다:

```ts
providers: [
  {provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
],

```

자동으로 생성되는 사전 연결 힌트에 대해 알아보려면 [이 섹션](#이미지-도메인에-사전-연결-엘리먼트가-연결되지-않는-이유는-무엇일까요)을 참고하세요.

### 이미지를 원하는 사이즈로 요청하기: `srcset`

[`srcset` 어트리뷰트](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/srcset)를 지정하면 사용자의 뷰포트에 맞는 이미지를 적절하게 로드할 수 있기 때문에, 불필요하게 큰 이미지를 다운로드하지 않아도 됩니다.
`NgOptimizedImage`는 [`sizes` 어트리뷰트](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) 값에 따라 `srcset`을 자동으로 생성합니다.

#### 크기가 고정된 이미지

<!--
If your image should be "fixed" in size (i.e. the same size across devices, except for [pixel density](https://web.dev/codelab-density-descriptors/)), there is no need to set a `sizes` attribute. A `srcset` can be generated automatically from the image's width and height attributes with no further input required.

Example srcset generated:

```html
<img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x" />
```
-->

이미지의 크기가 사용자 기기에 관계없이 동일하고 [픽셀 해상도](https://web.dev/codelab-density-descriptors/)만 다르다면, `sizes` 어트리뷰트를 설정할 필요가 없습니다.
이 경우에는 이미지의 너비와 높이에 따라 `srcset`이 자동으로 생성됩니다:

```html
<img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x" />
```

#### 반응형 이미지

<!--
If your image should be responsive (i.e. grow and shrink according to viewport size), then you will need to define a [`sizes` attribute](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) to generate the `srcset`.

If you haven't used `sizes` before, a good place to start is to set it based on viewport width. For example, if your CSS causes the image to fill 100% of viewport width, set `sizes` to `100vw` and the browser will select the image in the `srcset` that is closest to the viewport width (after accounting for pixel density). If your image is only likely to take up half the screen (ex: in a sidebar), set `sizes` to `50vw` to ensure the browser selects a smaller image. And so on.

If you find that the above does not cover your desired image behavior, see the documentation on [advanced sizes values](#advanced-sizes-values).

Note that for lazy-loaded images, `NgOptimizedImage` automatically prepends `"auto"` to the provided `sizes` value. This is an optimization that increases the accuracy of srcset selection on browsers which support `sizes="auto"`, and is ignored by browsers which do not. Images that are not lazy-loaded, such as `priority` images, keep the `sizes` value as provided.

By default, the responsive breakpoints are:

`[16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840]`

If you would like to customize these breakpoints, you can do so using the `IMAGE_CONFIG` provider:

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      breakpoints: [16, 48, 96, 128, 384, 640, 750, 828, 1080, 1200, 1920]
    }
  },
],
```

If you would like to manually define a `srcset` attribute, you can provide your own using the `ngSrcset` attribute:

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" />
```

If the `ngSrcset` attribute is present, `NgOptimizedImage` generates and sets the `srcset` based on the sizes included. Do not include image file names in `ngSrcset` - the directive infers this information from `ngSrc`. The directive supports both width descriptors (e.g. `100w`) and density descriptors (e.g. `1x`).

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw" />
```
-->

뷰포트 크기에 따라 이미지가 작아지거나 커지는 경우라면, [`sizes` 어트리뷰트](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes)를 지정해서 `srcset`을 생성해야 합니다.

`sizes`를 사용해본 적이 없다면, 뷰포트를 기준으로 설정하는 것이 좋습니다.
CSS에서 이미지가 뷰포트 100%를 채우는 경우에는, `sizes`를 `100vw`로 설정하면 브라우저가 픽셀 해상도를 고려하여 적절한 크기의 `srcset` 이미지를 선택합니다.
그리고 사이드바와 같이 화면의 최대 반 정도를 채우는 이미지라면 `sizes`를 `50vw`로 설정하면 브라우저가 더 작은 이미지를 선택해서 로드합니다.

여기까지 읽고 더 원하는 내용이 있다면, [`sizes` 고급 활용](#sizes-고급-활용) 섹션을 참고하세요.

`NgOptimizedImage`는 지연 로딩되는 이미지의 `sizes` 값 앞에 `"auto"`를 자동으로 추가합니다.
이 경우 브라우저가 `sizes="auto"`를 지원한다면 srcset에 맞게 적절한 이미지를 로드할 수 있으며, `sizes="auto"`를 지원하지 않는 브라우저에서는 무시됩니다.
`priority` 이미지처럼 지연 로딩되지 않는 이미지는 지정한 `sizes` 값을 그대로 유지합니다.

기본적으로 반응형 레이아웃의 기준점은 다음과 같이 나눕니다:

`[16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840]`

이 기준점을 변경하려면 `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`를 활용해서 추론합니다.
`NgOptimizedImage` 디렉티브는 `100w`와 같은 너비 설명자와, `1x`와 같은 밀도 설명자를 모두 지원합니다.

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw" />
```

### `srcset` 자동 생성 비활성화

<!--
To disable srcset generation for a single image, you can add the `disableOptimizedSrcset` attribute on the image:

```html
<img ngSrc="about.jpg" disableOptimizedSrcset />
```
-->

`srcset` 자동 생성을 비활성화하려면 이미지 엘리먼트에 `disableOptimizedSrcset` 어트리뷰트를 추가하면 됩니다:

```html
<img ngSrc="about.jpg" disableOptimizedSrcset />
```

### 이미지 지연로딩 비활성화

<!--
By default, `NgOptimizedImage` sets `loading=lazy` for all images that are not marked `priority`. You can disable this behavior for non-priority images by setting the `loading` attribute. This attribute accepts values: `eager`, `auto`, and `lazy`. [See the documentation for the standard image `loading` attribute for details](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/loading#value).

```html
<img ngSrc="cat.jpg" width="400" height="200" loading="eager" />
```
-->

`NgOptimizedImage`는 `priority`가 지정되지 않은 모든 이미지 파일에 `loading=lazy`를 지정합니다.
그런데 이미지들의 우선순위가 따로 없다면 이 기능을 비활성화할 수 있습니다.
`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" />
```

### 이미지 디코딩 지정

<!--
By default, `NgOptimizedImage` sets `decoding="auto"` for all images. This allows the browser to decide the optimal time to decode an image after it has been fetched. When an image is marked as `priority`, Angular automatically sets `decoding="sync"` to ensure the image is decoded and painted as early as possible helping improve **Largest Contentful Paint (LCP)** performance.

You can override the default `auto` for non-priority images by explicitly setting the `decoding` attribute. Priority images always use `decoding="sync"`.
[See the documentation for the standard image `decoding` attribute for details](https://developer.mozilla.org/docs/Web/HTML/Element/img#decoding).

```html
<!- Default: decoding is 'auto' ->
<img ngSrc="gallery/landscape.jpg" width="1200" height="800" />

<!- Decode the image asynchronously to avoid blocking the main thread.->
<img ngSrc="gallery/preview.jpg" width="600" height="400" decoding="async" />

<!- Priority images automatically use decoding="sync" ->
<img ngSrc="awesome.jpg" width="500" height="625" priority />

<!- Decode immediately (can block) when you need the pixels right away ->
<img ngSrc="hero.jpg" width="1600" height="900" decoding="sync" />
```

**Allowed values**

- `auto` (default): lets the browser choose the optimal strategy.
- `async`: decodes the image asynchronously, avoiding main‑thread blocking where possible.
- `sync`: decodes the image immediately; can block rendering but ensures pixels are ready as soon as the image is available.
-->

`NgOptimizedImage`는 모든 이미지에 `decoding="auto"`를 지정합니다.
이 동작은 브라우저가 이미지 파일을 로드한 후에 디코딩하는 방식을 지정하기 위한 것입니다.
만약 이미지 파일에 `priority`가 지정되어 있다면, Angular는 해당 이미지 엘리먼트에 `decoding="sync"`를 지정해서 최대 컨텐츠 페인트(Largest Contentful Paint, LCP)가 최대한 빨리 표시될 수 있도록 합니다.

`priority`가 지정되지 않은 이미지는 `decoding` 어트리뷰트를 직접 지정해서 기본값인 `auto`를 변경할 수 있습니다.
`priority` 이미지는 항상 `decoding="sync"`를 사용합니다.
자세한 내용은 [표준 이미지 `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`: 이미지를 비동기로 디코딩합니다. 메인 스레드 중단을 피할 수 있습니다.
- `sync`: 이미지를 즉시 디코딩합니다. 렌더링이 잠시 멈출 수 있지만 이미지는 즉시 표시됩니다.

### `sizes` 고급 활용

<!--
You may want to have images displayed at varying widths on differently-sized screens. A common example of this pattern is a grid- or column-based layout that renders a single column on mobile devices, and two columns on larger devices. You can capture this behavior in the `sizes` attribute, using a "media query" syntax, such as the following:

```html
<img ngSrc="cat.jpg" width="400" height="200" sizes="(max-width: 768px) 100vw, 50vw" />
```

The `sizes` attribute in the above example says "I expect this image to be 100 percent of the screen width on devices under 768px wide. Otherwise, I expect it to be 50 percent of the screen width.

For additional information about the `sizes` attribute, see [web.dev](https://web.dev/learn/design/responsive-images/#sizes) or [mdn](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes).
-->

다양한 화면 크기에 따라 이미지를 다양한 크기로 표시해야 하는 경우가 있습니다.
모바일 장치에서는 그리드나 칼럼 기반 레이아웃에서 한 칸으로 표시하던 것을, 화면이 더 큰 장치에서는 두 칸으로 표시하는 경우가 일반적인 경우일 것입니다.
이런 경우는 다음과 같이 "미디어 쿼리" 문법을 사용해서 `sizes` 어트리뷰트를 지정하면 됩니다:

```html
<img ngSrc="cat.jpg" width="400" height="200" sizes="(max-width: 768px) 100vw, 50vw" />
```

이렇게 작성하면, "화면 크기가 768px보다 작으면 이미지는 100% 너비로 표시하고, 화면 크기가 768px보다 크다면 화면 전체 너비의 50%로 표시한다"는 것을 의미합니다.

`sizes` 어트리뷰트에 대해 자세하게 알아보려면 [web.dev](https://web.dev/learn/design/responsive-images/#sizes)나 [mdn](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes) 문서를 참고하세요.

## `NgOptimizedImage`용 이미지 로더 설정하기

<!--
A "loader" is a function that generates an [image transformation URL](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options) for a given image file. When appropriate, `NgOptimizedImage` sets the size, format, and image quality transformations for an image.

`NgOptimizedImage` provides both a generic loader that applies no transformations, as well as loaders for various third-party image services. It also supports writing your own custom loader.

| Loader type                            | Behavior                                                                                                                                                                                                                       |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Generic loader                         | The URL returned by the generic loader will always match the value of `src`. In other words, this loader applies no transformations. Sites that use Angular to serve images are the primary intended use case for this loader. |
| Loaders for third-party image services | The URL returned by the loaders for third-party image services will follow API conventions used by that particular image service.                                                                                              |
| Custom loaders                         | A custom loader's behavior is defined by its developer. You should use a custom loader if your image service isn't supported by the loaders that come preconfigured with `NgOptimizedImage`.                                   |

Based on the image services commonly used with Angular applications, `NgOptimizedImage` provides loaders preconfigured to work with the following image services:

To use the **generic loader** no additional code changes are necessary. This is the default behavior.
-->

로더(loader)는 이미지 파일을 [이미지 URL로 변환](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options)하는 함수를 의미합니다.
`NgOptimizedImage`는 이미지의 크기, 형식, 이미지 품질을 지정합니다.

`NgOptimizedImage`는 변환을 수행하지 않는 제네릭 로더를 제공하며, 서드 파티 이미지 로더도 제공하고, 사용자 지정 로더를 직접 지정할 수도 있습니다.

| 로더 타입             | 동작                                                                                                                                                                                               |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 제네릭 로더           | 제네릭 로더를 통해 변환되는 URL은 언제나 `src`에 지정된 것과 같습니다. 다르게 표현하면, 이 로더는 URL 변환을 수행하지 않습니다. Angular를 사용해서 이미지를 제공하는 웹사이트에서 주로 사용합니다. |
| 서드 파티 이미지 로더 | 서드 파티 이미지 서비스에서 지정하는 대로 URL을 변환합니다.                                                                                                                                        |
| 커스텀 로더           | 개발자가 원하는 대로 URL을 변환합니다. `NgOptimizedImage`에서 제공하는 기능 외에 다른 기능이 필요한 경우에 사용합니다.                                                                             |

Angular 애플리케이션과 함께 사용되는 이미지 서비스들은 `NgOptimizedImage`가 사전에 로더를 준비해서 제공합니다:

**제네릭 로더** 를 사용한다면 코드를 변경할 필요가 없습니다.
기본 설정은 제네릭 로더입니다.

### 내장 로더

<!--
To use an existing loader for a **third-party image service**, add the provider factory for your chosen service to the `providers` array. In the example below, the Imgix loader is used:

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

The base URL for your image assets should be passed to the provider factory as an argument. For most sites, this base URL should match one of the following patterns:

- <https://yoursite.yourcdn.com>
- <https://subdomain.yoursite.com>
- <https://subdomain.yourcdn.com/yoursite>

You can learn more about the base URL structure in the docs of a corresponding CDN provider.
-->

**서드 파티 이미지 서비스** 용 로더를 사용하려면 프로바이더 팩토리를 `providers` 배열에 추가하면 됩니다.
예를 들어 Imgix 로더를 사용하는 경우는 이렇습니다:

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

이때 이미지 파일들이 존재하는 기본 URL이 프로바이더 팩토리에 인자로 전달되어야 합니다.
보통은 다음과 같은 패턴입니다:

- <https://yoursite.yourcdn.com>
- <https://subdomain.yoursite.com>
- <https://subdomain.yourcdn.com/yoursite>

정확한 기본 URL 구조는 CDN 프로바이더 안내를 참고하세요.

### 커스텀 로더

<!--
To use a **custom loader**, provide your loader function as a value for the `IMAGE_LOADER` DI token. In the example below, the custom loader function returns a URL starting with `https://example.com` that includes `src`, `width`, and `height` as URL parameters.

```ts
providers: [
  {
    provide: IMAGE_LOADER,
    useValue: (config: ImageLoaderConfig) => {
      return `https://example.com/images?src=${config.src}&width=${config.width}&height=${config.height}`;
    },
  },
],
```

A loader function for the `NgOptimizedImage` directive takes an object with the `ImageLoaderConfig` type (from `@angular/common`) as its argument and returns the absolute URL of the image asset. The `ImageLoaderConfig` object contains the `src` property, and optional `width`, `height`, and `loaderParams` properties.

NOTE: even though the `width` property may not always be present, a custom loader must use it to support requesting images at various widths in order for `ngSrcset` to work properly.
-->

**커스텀 로더** 를 사용하려면 `IMAGE_LOADER` DI 토큰에 로더 함수를 등록하면 됩니다.
아래 예제 코드는 URL 인자로 전달되는 `src`, `width`, `height`에 `https://example.com`을 붙이는 커스텀 로더 함수입니다.

`NgOptimizedImage` 디렉티브용 로더 함수는 `@angular/common` 패키지로 제공되는 `ImageLoaderConfig` 타입을 인자로 받고 이미지 리소스의 절대 주소를 반환합니다.
그리고 `ImageLoaderConfig` 객체에는 `src` 프로퍼티가 존재하며, `width`, `height`, `loaderParams` 프로퍼티는 옵션 인자입니다.

참고: `width` 프로퍼티가 항상 존재하는 것은 아니지만, 커스텀 로더는 `ngSrcset`이 제대로 작동할 수 있도록 다양한 너비용 이미지를 로드하기 위해 해당 기능을 지원해야 합니다.

### `loaderParams` 프로퍼티

<!--
There is an additional attribute supported by the `NgOptimizedImage` directive, called `loaderParams`, which is specifically designed to support the use of custom loaders. The `loaderParams` attribute takes an object with any properties as a value, and does not do anything on its own. The data in `loaderParams` is added to the `ImageLoaderConfig` object passed to your custom loader, and can be used to control the behavior of the loader.

A common use for `loaderParams` is controlling advanced image CDN features.
-->

`NgOptimizedImage` 디렉티브가 지원하는 `loaderParams` 추가 어트리뷰트가 있는데, 이 어트리뷰트는 커스텀 로더에서 주로 사용됩니다.
`loaderParams` 어트리뷰트는 객체를 인자로 받는데, 객체의 형식은 제한되지 않습니다.
`loaderParams` 안에 있는 데이터는 `ImageLoaderConfig` 객체에 추가되어 커스텀 로더로 전달되어, 커스텀 로더 로직으로 활용됩니다.

보통은 CDN 기능을 활용할 때 사용합니다.

### 내장 로더로 `transform` 프로퍼티 활용하기

<!--
The built-in loaders for Cloudinary, Cloudflare, ImageKit, and Imgix support a special `transform` property within `loaderParams`. This property allows you to apply custom image transformations provided by your CDN.

The `transform` property accepts two formats:
-->

내장 로더는 Cloudinary, Cloudflare, ImageKit, Imgix를 지원하며, `loaderParams`로 `transform` 프로퍼티를 지정할 수 있습니다.
이 프로퍼티를 사용하면 CDN을 통해 이미지를 변환할 수 있습니다.

`transform` 프로퍼티에는 두 가지 형식을 사용할 수 있습니다:

#### 문자열 형식

<!--
Provide transformations as a comma-separated string using your CDN's transformation syntax:

```html
<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: 'e_grayscale,r_10'}"
/>
```
-->

쉼표로 구분하는 문자열 형식을 사용할 수 있습니다:

```html
<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: 'e_grayscale,r_10'}"
/>
```

#### 객체 형식

<!--
Provide transformations as an object with key-value pairs.

```html
<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: {e: 'grayscale', r: 10}}"
/>
```

NOTE: The `transform` property is not supported by the Netlify loader, as Netlify's image CDN does not provide custom transformation parameters.
-->

키-값 쌍으로 객체 형식을 사용할 수 있습니다:

```html
<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: {e: 'grayscale', r: 10}}"
/>
```

참고: `transform` 프로퍼티는 Netlify 로더를 지원하지 않기 때문에, Netlify CDN에는 변환 인자를 전달할 수 없습니다.

### 커스텀 로더 예제

<!--
The following shows an example of a custom loader function. This example function concatenates `src`, `width`, and `height`, and uses `loaderParams` to control a custom CDN feature for rounded corners:

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

Note that in the above example, we've invented the 'roundedCorners' property name to control a feature of our custom loader. We could then use this feature when creating an image, as follows:

```html
<img ngSrc="profile.jpg" width="300" height="300" [loaderParams]="{roundedCorners: true}" />
```
-->

아래 코드는 커스텀 로더 함수입니다.
이 함수는 `src`와 `width`, `height` 를 조합하면서 가장자리 곡선 처리를 위해 `loaderParams` 인자를 활용합니다:

위에서 다룬 코드처럼 `roundedCorners` 프로퍼티는 커스텀 로더의 기능을 확장하는 용도로 활용됩니다.
다음과 같이 사용하면 됩니다:

```html
<img ngSrc="profile.jpg" width="300" height="300" [loaderParams]="{roundedCorners: true}" />
```

## 자주 묻는 질문

### `NgOptimizedImage`는 `background-image` CSS 프로퍼티를 지원하나요?

<!--
The NgOptimizedImage does not directly support the `background-image` css property, but it is designed to easily accommodate the use case of having an image as the background of another element.

For a step-by-step process for migration from `background-image` to `NgOptimizedImage`, see the [How to migrate your background image](#how-to-migrate-your-background-image) section above.
-->

NgOptimizedImage는 `background-image` CSS 프로퍼티를 직접 지원하지 않지만, 다른 엘리먼트의 배경으로 이미지를 지정하는 경우는 쉽게 처리할 수 있습니다.

`background-image`를 `NgOptimizedImage`로 단계별 마이그레이션하려면 [배경 이미지 마이그레이션하기](#배경-이미지-마이그레이션하기) 섹션을 참고하세요.

### 왜 `NgOptimizedImage`에 `src`를 사용할 수 없나요?

`ngSrc` 어트리뷰트는 브라우저에서 이미지가 효율적으로 로드되는 기능을 제공하기 위해 NgOptimizedImage의 트리거로 선택되었습니다.
NgOptimizedImage는 `loading` 어트리뷰트를 프로그램으로 변경하는데, 브라우저가 이런 변경사항을 반영하기 전에 `src` 속성을 발견하면 이미지 파일을 즉시 다운로드하기 시작하고 `loading` 어트리뷰트 변경은 무시됩니다.

### 이미지 도메인에 사전 연결 엘리먼트가 연결되지 않는 이유는 무엇일까요?

<!--
Preconnect generation is performed based on static analysis of your application. That means that the image domain must be directly included in the loader parameter, as in the following example:

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

If you use a variable to pass the domain string to the loader, or you're not using a loader, the static analysis will not be able to identify the domain, and no preconnect link will be generated. In this case you should manually add a preconnect link to the document head, as [described above](#add-resource-hints).
-->

사전 연결 생성은 애플리케이션의 정적 분석을 기반으로 수행됩니다.
이 말은, 이미지 도메인이 로더의 인자에 다음과 같이 지정되어야 한다는 것을 의미합니다:

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

도메인 문자열을 변수로 로더에 전달하거나 이미지 로더를 사용하지 않으면, 정적 분석기가 이미지의 도메인을 판단할 수 없게 되고 사전 연결 링크는 생성되지 않습니다.
이런 경우는 도큐먼트 헤드에 [리소스 힌트를 직접 추가](#리소스-힌트-추가)하면 됩니다.

### 한 화면에서 이미지 도메인을 2개 사용할 수 있나요?

<!--
The [image loaders](#configuring-an-image-loader-for-ngoptimizedimage) provider pattern is designed to be as simple as possible for the common use case of having only a single image CDN used within a component. However, it's still very possible to manage multiple image CDNs using a single provider.

To do this, we recommend writing a [custom image loader](#custom-loaders) which uses the [`loaderParams` property](#the-loaderparams-property) to pass a flag that specifies which image CDN should be used, and then invokes the appropriate loader based on that flag.
-->

[이미지 로더](#ngoptimizedimage용-이미지-로더-설정하기) 프로바이더 패턴은 컴포넌트에서 단일 이미지 CDN 활용을 최적화하기 위해 도입되었습니다.
하지만 프로바이더가 하나라도 이미지 CDN을 여러 개 활용하는 것도 가능합니다.

이런 경우라면, [커스텀 이미지 로더](#커스텀-로더)를 정의하고 [`loaderParams` 프로퍼티](#loaderparams-프로퍼티)를 전달받아 원하는 이미지 CDN을 선택하는 방식으로 구현하면 됩니다.

### 제가 자주 사용하는 CDN용 로더를 추가해 줄 수 있나요?

유지보수상의 이유로 Angular 저장소에 내장 로더를 추가할 계획은 현재 없습니다. 대신 추가 이미지 로더를 서드파티 패키지로 배포하는 것을 권장합니다.

### `<picture>` 태그를 사용할 수 있나요?

<!--
No, but this is on our roadmap, so stay tuned.

If you're waiting on this feature, please upvote the GitHub issue [here](https://github.com/angular/angular/issues/56594).
-->

아니요, 하지만 로드맵에 포함되어 있으니 조금만 기다려 주세요.

이 기능을 기다리고 있다면 [Github 이슈](https://github.com/angular/angular/issues/56594)에 투표해 주세요.

### Chrome 개발자도구에서 LCP 이미지를 어떻게 찾을 수 있나요?

<!--
1. Using the performance tab of the Chrome DevTools, click on the "start profiling and reload page" button on the top left. It looks like a page refresh icon.

2. This will trigger a profiling snapshot of your Angular application.

3. Once the profiling result is available, select "LCP" in the timings section.

4. A summary entry should appear in the panel at the bottom. You can find the LCP element in the row for "related node". Clicking on it will reveal the element in the Elements panel.

NOTE: This only identifies the LCP element within the viewport of the page you are testing. It is also recommended to use mobile emulation to identify the LCP element for smaller screens.
-->

1. Chrome 개발자도구에서 Performance 탭으로 이동한 후에 왼쪽 위에 있는 "start profiling and reload page" 버튼을 클릭하세요. 새로고침 아이콘과 비슷하게 생겼습니다.

2. 버튼을 클릭하면 Angular 애플리케이션의 프로파일링 스냅샷을 분석합니다.

3. 프로파일링 결과가 나오면 타이밍 섹션에서 "LCP"를 선택합니다.

4. 아래쪽 패널에서 요약 정보를 확인할 수 있습니다. "related node"라고 표시된 엘리먼트가 LCP 엘리먼트입니다. 이 엘리먼트를 클릭하면 실제 어떤 엘리먼트인지 Elements 패널로 이동하면서 확인할 수 있습니다.

참고: 이 방식은 테스트 중인 뷰포트에서 LCP 엘리먼트를 찾는 방법일 뿐입니다. 작은 화면의 장치에서 LCP를 확인하려면 모바일 장비 에뮬레이션 사용을 권장합니다.
<!--
In Angular, you use _signals_ to create and manage state. A signal is a lightweight wrapper around a value.

Use the `signal` function to create a signal for holding local state:

```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 tracks where signals are read and when they're updated. The framework uses this information to do additional work, such as updating the DOM with new state. This ability to respond to changing signal values over time is known as _reactivity_.
-->

Angular는 _시그널(signal)_ 을 사용해서 상태를 만들고 관리합니다.
시그널은 어떤 값을 간단하게 감싸는 객체라고 생각하면 됩니다.

`signal` 함수를 사용하면 시그널을 생성하고 상태를 저장할 수 있습니다:

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

// `signal` 함수로 시그널을 생성합니다.
const firstName = signal('Morgan');

// `signal`은 그 자체로 함수입니다. 함수를 실행해서 값을 읽을 수 있습니다.
console.log(firstName());

// `set` 메서드를 사용하면 시그널의 값을 변경할 수 있습니다.
firstName.set('Jaime');

// `update` 메서드를 사용하면 기존 값을 참조해서 시그널의 값을 변경할 수 있습니다.
firstName.update((name) => name.toUpperCase());
```

Angular는 시그널이 어디에 사용되고 언제 갱신되는지 계속 추적합니다.
그래서 상태가 변경되면 DOM을 갱신하는 등 필요한 작업을 수행합니다.
이렇게 시그널 값이 변하는 것에 맞춰 반응하는 능력을 _반응성(reactivity)_ 이라고 합니다.

## 연산 표현식

<!--
A `computed` is a signal that produces its value based on other signals.

```typescript
import {signal, computed} from '@angular/core';

const firstName = signal('Morgan');
const firstNameCapitalized = computed(() => firstName().toUpperCase());

console.log(firstNameCapitalized()); // MORGAN
```

A `computed` signal is read-only; it does not have a `set` or an `update` method. Instead, the value of the `computed` signal automatically changes when any of the signals it reads change:

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

`computed` 함수는 기존에 있던 시그널을 참조해서 새로운 시그널을 생성하는 함수입니다.

```typescript
import {signal, computed} from '@angular/core';

const firstName = signal('Morgan');
const firstNameCapitalized = computed(() => firstName().toUpperCase());

console.log(firstNameCapitalized()); // MORGAN
```

`computed()` 시그널은 읽을 수만 있습니다.
그래서 `computed()` 시그널에는 `set` 메서드와 `update` 메서드가 존재하지 않습니다.
그럼에도 `computed()` 시그널을 생성할 때 참조했던 시그널이 변경되면, `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
```

## 컴포넌트에서 시그널 활용하기

<!--
Use `signal` and `computed` inside your components to create and manage state:

```ts
@Component({
  /* ... */
})
export class UserProfile {
  isTrial = signal(false);
  isTrialExpired = signal(false);
  showTrialDuration = computed(() => this.isTrial() && !this.isTrialExpired());

activateTrial() {
    this.isTrial.set(true);
  }
}
```

TIP: Want to know more about Angular Signals? See the [In-depth Signals guide](guide/signals) for the full details.
-->

컴포넌트 상태를 관리하려면 `signal` 함수와 `computed` 함수를 사용하면 됩니다:

activateTrial() {
    this.isTrial.set(true);
  }
}
```

팁: 시그널을 자세하게 알아보고 싶은가요? 그렇다면 [시그널 심화 가이드](guide/signals) 문서를 참고하세요.

## 다음 단계

이 문서에서는 동적 데이터를 선언하고 관리하는 방법을 알아봤습니다.
이제 이 데이터를 템플릿에 어떻게 사용하는지 알아봅시다.

# `linkedSignal`을 활용한 의존 상태 관리

<!--
You can use the `signal` function to hold some state in your Angular code. Sometimes, this state depends on some _other_ state. For example, imagine a component that lets the user select a shipping method for an order:

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

In this example, the `selectedOption` defaults to the first option, but changes if the user selects another option. But `shippingOptions` is a signal— its value may change! If `shippingOptions` changes, `selectedOption` may contain a value that is no longer a valid option.

**The `linkedSignal` function lets you create a signal to hold some state that is intrinsically _linked_ to some other state.** Revisiting the example above, `linkedSignal` can replace `signal`:

```ts
@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` works similarly to `signal` with one key difference— instead of passing a default value, you pass a _computation function_, just like `computed`. When the value of the computation changes, the value of the `linkedSignal` changes to the computation result. This helps ensure that the `linkedSignal` always has a valid value.

The following example shows how the value of a `linkedSignal` can change based on its linked state:

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

Angular 코드에서 어떤 상태를 저장하려면 `signal` 함수를 사용하면 됩니다.
때로는 _다른_ 상태에 종속된 상태를 관리해야 할 수도 있습니다.
사용자가 배송 방식을 선택하는 컴포넌트를 예로 들어 봅시다:

```typescript
@Component({/* ... */})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// 기본 배송 방법을 지정합니다.
  selectedOption = signal(this.shippingOptions()[0]);

changeShipping(newOptionIndex: number) {
    this.selectedOption.set(this.shippingOptions()[newOptionIndex]);
  }
}
```

이 예제에서 `selectedOption`은 기본값이 설정되어 있으며, 사용자의 선택에 따라 값이 변경됩니다.
그런데 `shippingOptions`는 시그널이기 때문에 값이 변경될 수 있습니다!
`shippingOptions` 값이 변경되면 `selectedOption` 값은 더 이상 유효하지 않습니다.

**이때 `linkedSignal` 함수를 사용하면, 다른 상태와 직접 _연결되는_ 시그널을 생성할 수 있습니다.**
위 예제 코드에서 `signal`을 `linkedSignal`로 바꿔 보세요:

```ts
@Component({/* ... */})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// 기본 배송방법을 지정합니다.
  selectedOption = linkedSignal(() => this.shippingOptions()[0]);

changeShipping(index: number) {
    this.selectedOption.set(this.shippingOptions()[index]);
  }
}
```

`linkedSignal`은 `signal`과 비슷하지만 다른 점이 하나 있습니다.
`linkedSignal`은 기본값을 직접 받지 않고 `computed()` 함수처럼 _계산 함수_ 를 통해 전달받습니다.
그리고 계산 값이 변경되면 `linkedSignal`의 값도 새로 계산된 값으로 변경됩니다.
이제 `linkedSignal`의 값은 언제나 유효한 값을 유지합니다.

아래 예제를 보며 `linkedSignal` 값이 연결 상태에 따라 어떻게 변경되는지 확인해 보세요:

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

## 이전 상태 참조하기

<!--
In some cases, the computation for a `linkedSignal` needs to account for the previous value of the `linkedSignal`.

In the example above, `selectedOption` always updates back to the first option when `shippingOptions` changes. You may, however, want to preserve the user's selection if their selected option is still somewhere in the list. To accomplish this, you can create a `linkedSignal` with a separate _source_ and _computation_:

```ts
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'},
    ]);
  }
}
```

When you create a `linkedSignal`, you can pass an object with separate `source` and `computation` properties instead of providing just a computation.

The `source` can be any signal, such as a `computed` or component `input`. The `linkedSignal` updates its value when the `source` changes or when any signal referenced in the `computation` changes, updating its value with the result of the provided `computation`.

The `computation` is a function that receives the new value of `source` and a `previous` object. The `previous` object has two properties— `previous.source` is the previous value of `source`, and `previous.value` is the previous value of the `linkedSignal`. You can use these previous values to decide the new result of the computation.

HELPFUL: When using the `previous` parameter, it is necessary to provide the generic type arguments of `linkedSignal` explicitly. The first generic type corresponds with the type of `source` and the second generic type determines the output type of `computation`.
-->

경우에 따라 `linkedSignal`이 이전 값을 참조해야 하는 경우가 있습니다.

위 예제에서 `shippingOptions` 목록이 변경되면 `selectedOption`의 값은 언제나 첫번째 항목으로 변경됩니다.
하지만 사용자가 선택한 옵션이 새 목록에 남아 있다면 선택을 유지하고 싶을 수 있습니다.
그러면 `linkedSignal`을 생성할 때 _소스(source)_ 와 _연산(computation)_ 을 구분하는 방식을 사용하면 됩니다:

```ts
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`의 값은 `source`가 바뀌었을 때 `computation` 결과 값으로 할당됩니다.
    source: this.shippingOptions,
    computation: (newOptions, previous) => {
      // newOptions에 이전 값이 전달되면 이전 값을 유지합니다.
      // 아니면 첫번째 옵션 값을 선택합니다.
      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`가 변경되거나 `computation`에서 참조한 시그널이 변경되면, `linkedSignal`은 제공된 `computation`의 실행 결과로 값을 갱신합니다.

그리고 `computation`은 `source`에서 새 값을 받으면서 `previous` 객체를 받는 함수입니다.
이때 `previous` 객체에는 `source` 프로퍼티와 `value` 프로퍼티가 있습니다.
`previous.source` 프로퍼티에는 이전 `source` 값이 전달되며, `previous.value`에는 `linkedSignal`의 이전 값이 전달됩니다.
연산 함수는 이 값들을 활용해서 새 값을 만들어 내면 됩니다.

도움말: `previous` 인자를 사용할 때는 `linkedSignal`의 제네릭 타입을 명시적으로 지정해야 합니다.
제네릭의 첫 번째 타입은 `source`로 전달되는 타입이며, 두 번째 타입은 `computation` 연산 결과의 타입입니다.

## 동일성 평가 함수 커스터마이징

<!--
`linkedSignal`, as any other signal, can be configured with a custom equality function. This function is used by downstream dependencies to determine if that value of the `linkedSignal` (result of a computation) changed:

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

`linkedSignal`은 다른 시그널과 마찬가지로 커스텀 동일성 평가 함수를 지정할 수 있습니다.
이 함수는 `linkedSignal` 값이 변경되었는지 판단하는 용도로 사용됩니다:

```typescript
const activeUser = signal({id: 123, name: 'Morgan', isAdmin: true});

const activeUserEditCopy = linkedSignal(() => activeUser(), {
  // 사용자의 id가 같으면 같은 사용자로 판단합니다.
  equal: (a, b) => a.id === b.id,
});

// `source`와 `computation`을 각각 지정합니다.
const activeUserEditCopy = linkedSignal({
  source: activeUser,
  computation: (user) => user,
  equal: (a, b) => a.id === b.id,
});
```

## `set()` 커스터마이징하기

<!--
Sometimes you may want the `set` and `update` operations of a `linkedSignal` to write back to the source of truth instead of updating the `linkedSignal`'s value directly. You can customize this behavior by passing a `set` function in the options.

The custom `set` function receives two arguments:

1. The new value being set.
2. A `rawSet` function, which you can invoke to update the `linkedSignal`'s internal state directly (matching the default behavior).

NOTE: Using `rawSet` allows you to update the `linkedSignal`'s value directly. This can be useful to prevent the computation from running, for example if it is an expensive derivation and you already know the result.
-->

`linkedSignal`의 `set` 메서드나 `update` 메서드의 동작이 `linkedSignal` 자체의 값을 변경하지 않고 원본 데이터를 변경하는 경우가 있다고 합시다.
이런 경우에는 `linkedSignal`을 생성할 때 옵션 객체의 `set` 프로퍼티로 커스텀 함수를 전달해서 동작을 커스터마이징할 수 있습니다.

커스텀 `set` 함수는 인자를 2개 받습니다:

1. 변경할 새 값
2. `rawSet` 함수 - `linkedSignal` 내부 상태를 직접 갱신하는 함수

참고: `rawSet` 함수를 사용하면 `linkedSignal` 내부값을 직접 갱신할 수 있습니다.
이 방식은 계산이 복잡하거나 이미 결과를 알고 있는 경우를 건너뛰는 방식으로 유용합니다.

### 원본 시그널의 값을 변경하기

<!--
Consider a component that displays and allows editing temperature in Fahrenheit, but uses a Celsius signal as its source of truth:

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

화면에 사용하는 시그널은 화씨 시그널이지만, 원본 데이터는 섭씨 시그널인 경우를 생각해 봅시다:

```typescript
const tempC = signal(0);
const tempF = linkedSignal(() => (tempC() * 9) / 5 + 32, {
  set: (valF) => tempC.set(((valF - 32) * 5) / 9),
});

console.log(tempF()); // 32

// 화씨 값을 변경하면 원래 시그널인 섭씨 시그널 값을 변경합니다.
tempF.set(212);
console.log(tempC()); // 100
console.log(tempF()); // 212
```

### 부모 객체의 프로퍼티 값 변경하기

<!--
Another common scenario is updating a specific property inside a parent object. The parent is held in a signal, and you link to a nested property:

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

부모 객체의 프로퍼티 값을 변경하는 경우도 고려해봅시다.
대상 객체는 원본 시그널에 있습니다:

```typescript
interface Order {
  id: number;
  shippingMethod: string;
}

const order = signal<Order>({
  id: 42,
  shippingMethod: 'Ground',
});

const shippingMethod = linkedSignal(() => order().shippingMethod, {
  set: (newMethod) => {
    // 객체 참조를 유지하면서 내부 값을 변경합니다.
    order.update((currentOrder) => ({
      ...currentOrder,
      shippingMethod: newMethod,
    }));
  },
});

console.log(shippingMethod()); // 'Ground'

// shippingMethod 값을 변경하면서 부모 객체의 프로퍼티 값을 갱신합니다.
shippingMethod.set('Air');
console.log(order()); // { id: 42, shippingMethod: 'Air' }
console.log(shippingMethod()); // 'Air'
```

# `Resource` 를 활용한 비동기 반응성

<!--
All signal APIs are synchronous— `signal`, `computed`, `input`, etc. However, applications often need to deal with data that is available asynchronously. A `Resource` gives you a way to incorporate async data into your application's signal-based code and still allow you to access its data synchronously.

You can use a `Resource` to perform any kind of async operation, but the most common use-case for `Resource` is fetching data from a server. The following example creates a resource to fetch some user data.

The easiest way to create a `Resource` is the `resource` function.

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

The `resource` function accepts a `ResourceOptions` object with two main properties: `params` and `loader`.

The `params` property defines a reactive computation that produces a parameter value. Whenever signals read in this computation change, the resource produces a new parameter value, similar to `computed`.

The `loader` property defines a `ResourceLoader`— an async function that retrieves some state. The resource calls the loader every time the `params` computation produces a new value, passing that value to the loader. See [Resource loaders](#resource-loaders) below for more details.

`Resource` has a `value` signal that contains the results of the loader.
-->

`signal`, `computed`, `input` 등의 시그널 API는 대부분 동기 방식으로 동작합니다.
그런데 애플리케이션은 데이터를 비동기로 다뤄야 하는 경우가 종종 있습니다.
이때 `Resource`를 활용하면 애플리케이션이 시그널 기반으로 동작하면서 비동기 데이터를 처리할 수 있습니다.

`Resource`를 활용하면 모든 종류의 비동기 작업을 다룰 수 있지만, 가장 많이 사용하는 경우는 역시 서버에서 데이터를 받아오는 것입니다.
아래 코드는 사용자 데이터를 받아오는 예제 코드입니다.

`Resource`는 `resource` 함수로 생성하는 것이 가장 간단합니다.

```typescript
import {computed, resource, Signal} from '@angular/core';

const userId: Signal<string> = getUserId();

const userResource = resource({
  // 반응형 연산 함수를 정의합니다.
  // 이 계산에서 읽은 시그널의 값이 변경될 때마다 params 값을 다시 계산합니다.
  params: () => ({id: userId()}),

// 데이터를 받아오는 비동기 로더 함수를 정의합니다.
  // Resource는  `params` 값이 변경될 때마다 이 함수를 실행합니다.
  loader: ({params}) => fetchUser(params),
});

// 리소스의 로더 함수의 실행 결과로 computed() 시그널을 생성합니다.
const firstName = computed(() => {
  if (userResource.hasValue()) {
    // `hasValue`는 두 가지 용도로 사용합니다:
    // - `undefined` 타입을 걸러내는 타입 가드 역할을 합니다.
    // - 자원이 에러 상태일 때 값을 읽는 것을 방지합니다.
    return userResource.value().firstName;
  }

// 자원이 `undefined`이거나 에러 상태일 때는 아래줄을 실행합니다.
  return undefined;
});
```

`resource` 함수는 `ResourceOptions` 객체를 인자로 받는데, 이 객체에는 `params`와 `loader` 프로퍼티가 있습니다.

`params` 프로퍼티에는 인자값을 생성할 반응형 연산 함수를 지정합니다.
이 계산 함수에서 읽는 시그널이 변경될 때마다 Resource는 새로운 값을 생성합니다.
`computed()` 시그널과 비슷합니다.

`loader` 프로퍼티에는 어떤 값을 받아오는 비동기 함수인 `ResourceLoader`를 지정합니다.
리소스는 `params` 연산 함수가 새 값을 계산할 때마다 로더 함수를 실행하면서 그 값을 인자로 전달합니다.
자세한 내용은 [Resource 로더](#리소스-로더) 문서를 참고하세요.

`Resource` 객체에는 로더의 결과를 담는 `value` 시그널도 있습니다.

## 리소스 로더

<!--
When creating a resource, you specify a `ResourceLoader`. This loader is an async function that accepts a single parameter— a `ResourceLoaderParams` object— and returns a value.

The `ResourceLoaderParams` object contains three properties: `params`, `previous`, and `abortSignal`.

| Property      | Description                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`      | The value of the resource's `params` computation.                                                                                                |
| `previous`    | An object with a `status` property, containing the previous `ResourceStatus`.                                                                    |
| `abortSignal` | An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal). See [Aborting requests](#aborting-requests) below for details. |

If the `params` computation returns `undefined`, the loader function does not run and the resource status becomes `'idle'`.
-->

리소스를 생성할 때 `ResourceLoader`를 지정합니다.
이 로더는 `ResourceLoaderParams` 객체를 인자로 받는 비동기 함수이며, 값을 하나 반환합니다.

`ResourceLoaderParams` 객체에는 `params`, `previous`, `abortSignal` 프로퍼티가 있습니다.

| 프로퍼티      | 설명                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `params`      | 리소스의 `params` 연산 함수가 반환한 값                                                                                                                                 |
| `previous`    | `status` 프로퍼티와 이전 `ResourceStatus` 값이 담겨 전달되는 객체입니다.                                                                                    |
| `abortSignal` | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)에 대해 자세하게 알아보려면 [요청 취소하기](#요청-취소하기) 섹션을 참고하세요. |

`params` 연산 함수가 `undefined`를 반환하면, 로더 함수가 실행되지 않으며 리소스의 상태는 `'idle'`로 유지됩니다.

<!--
### Streaming resources

Some asynchronous data sources produce multiple values over time instead of returning a single result. Examples include WebSockets, Server-Sent Events (SSE), and Firestore `onSnapshot` listeners.

Use `stream` for these continuously updating data sources. Unlike `loader`, which resolves once for each request, `stream` returns a signal whose value can continue to update as new data becomes available.

Use `loader` for one-time asynchronous operations, such as fetching data from an HTTP endpoint.

In this example, `userUpdates` simulates an external source such as a WebSocket or SSE connection.

```typescript
const userUpdates = signal({value: 'Alice'});

const userResource = resource({
  stream: () => userUpdates,
});

// Simulate a new value arriving from the external data source:
userUpdates.set({value: 'Bob'});
```
-->

### 스트리밍 리소스

일부 비동기 데이터 소스는 결과 하나를 반환하는 대신 시간에 따라 여러 값을 생성합니다. WebSocket, Server-Sent Events(SSE), Firestore의 `onSnapshot` 리스너가 여기에 해당합니다.

계속 갱신되는 데이터 소스에는 `stream`을 사용하세요. 요청마다 한 번 결과를 반환하는 `loader`와 달리, `stream`은 새 데이터가 도착할 때마다 값을 갱신할 수 있는 시그널을 반환합니다.

HTTP 엔드포인트에서 데이터를 가져오는 것처럼 한 번만 실행하는 비동기 작업에는 `loader`를 사용하세요.

다음 예제의 `userUpdates`는 WebSocket이나 SSE 연결 같은 외부 데이터 소스를 흉내 냅니다:

```typescript
const userUpdates = signal({value: 'Alice'});

const userResource = resource({
  stream: () => userUpdates,
});

// 외부 데이터 소스에서 새 값이 도착하는 상황을 흉내 냅니다:
userUpdates.set({value: 'Bob'});
```

### 요청 취소하기

<!--
A resource aborts an outstanding loading operation if the `params` computation changes while the resource is loading.

You can use the `abortSignal` in `ResourceLoaderParams` to respond to aborted requests. For example, the native `fetch` function accepts an `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}).then((res) => res.json());
  },
});
```

See [`AbortSignal` on MDN](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for more details on request cancellation with `AbortSignal`.
-->

리소스가 로드되는 동안 `params` 연산 함수가 변경되면 리소스는 완료되지 않은 로딩을 취소합니다.

그리고 `ResourceLoaderParams`의 `abortSignal`을 지정하면 중단된 요청에 응답할 수 있습니다.
네이티브 `fetch` 함수를 `AbortSignal`로 적용해 봅시다:

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params, abortSignal}): Promise<User> => {
    // fetch는 `AbortSignal`을 통해 중단 요청이 들어올 때 미처리된 모든 `HTTP 요청을 취소합니다.
    return fetch(`users/${params.id}`, {signal: abortSignal}).then((res) => res.json());
  },
});
```

`AbortSignal`을 사용해서 요청을 취소하는 방법을 자세하게 알아보려면 [MDN의 `AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) 문서를 참고하세요.

### 재시도

<!--
You can programmatically trigger a resource's `loader` by calling the `reload` method.

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

// ...

userResource.reload();
```
-->

리소스 객체의 `reload` 메서드를 실행하면 `loader` 함수를 다시 실행할 수 있습니다.

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

// ...

userResource.reload();
```

## 리소스 상태

<!--
The resource object has several signal properties for reading the status of the asynchronous loader.

| Property    | Description                                                                                                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`     | The most recent value of the resource, or the default value (`undefined` unless `defaultValue` is set) if no value has been received. Reading `value()` throws when the status is `'error'`. |
| `hasValue`  | Whether the resource has a value.                                                                                                                                                            |
| `error`     | The most recent error encountered while running the resource's loader, or `undefined` if no error has occurred.                                                                              |
| `isLoading` | Whether the resource loader is currently running.                                                                                                                                            |
| `status`    | The resource's specific `ResourceStatus`, as described below.                                                                                                                                |

The `status` signal provides a specific `ResourceStatus` that describes the state of the resource using a string constant.

| Status        | `value()`         | Description                                                                  |
| ------------- | :---------------- | ---------------------------------------------------------------------------- |
| `'idle'`      | `undefined`       | The resource has no valid request and the loader has not run.                |
| `'error'`     | Throws an error   | The loader has encountered an error.                                         |
| `'loading'`   | `undefined`       | The loader is running as a result of the `params` value changing.            |
| `'reloading'` | Previous value    | The loader is running as a result of calling the resource's `reload` method. |
| `'resolved'`  | Resolved value    | The loader has completed.                                                    |
| `'local'`     | Locally set value | The resource's value has been set locally via `.set()` or `.update()`        |

You can use this status information to conditionally display user interface elements, such as loading indicators and error messages.
-->

리소스 객체에는 비동기 로더의 상태를 읽을 수 있는 시그널 프로퍼티가 여러 개 있습니다.

| 프로퍼티    | 설명                                                                                 |
| ----------- | ------------------------------------------------------------------------------------ |
| `value`     | 리소스의 가장 최근 값이며, 값을 받지 못했으면 기본값(`defaultValue`를 설정하지 않았다면 `undefined`)입니다. 상태가 `'error'`일 때 `value()`를 읽으면 예외가 발생합니다.                                |
| `hasValue`  | 리소스가 값을 갖고 있는지 여부                                                       |
| `error`     | 리소스 로더를 실행하다가 발생한 가장 최근 오류, 오류가 발생하지 않았다면 `undefined` |
| `isLoading` | 리소스 로더가 실행 중인지 여부                                                       |
| `status`    | 리소스의 세부 `ResourceStatus`, 아래에서 설명                                        |

`status` 시그널은 리소스의 상태를 문자열 상수로 표현하는 `ResourceStatus` 값을 제공합니다.

| 상태          | `value()`      | 설명                                                     |
| ------------- | :------------- | -------------------------------------------------------- |
| `'idle'`      | `undefined`    | 리소스에 유효한 요청이 없으며, 로더가 실행되지 않았음    |
| `'error'`     | 오류 발생      | 로더 실행 중 오류가 발생했음                             |
| `'loading'`   | `undefined`    | `params` 값이 변경되어 로더가 실행 중                    |
| `'reloading'` | 이전 값        | 리소스의 `reload` 메서드가 실행되어 로더가 실행 중       |
| `'resolved'`  | 로더가 반환한 값 | 로더 실행 종료                                           |
| `'local'`     | 직접 설정된 값 | 리소스의 `.set()`, `.update()` 메서드로 값이 설정된 상태 |

이 상태 정보를 활용하면 로딩 인디케이터나 오류 메시지 같은 UI 엘리먼트를 조건에 따라 표시할 수 있습니다.

<!--
## Caching `resource` data with SSR

When an application renders on the server, a resource loader runs once to produce the initial HTML. During hydration, the browser normally runs the same loader again.

To reuse the server result, provide an `id` for the resource. Angular stores the resolved value in `TransferState` on the server and uses it on the client to initialize the resource in a `'resolved'` state.

```ts
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
  id: 'user-unique-id',
});
```

The `id` value must be unique within your application and identical on the server and the client so that Angular can match the cached entry to the resource that requested it.

IMPORTANT: Because the cached value is serialized into the page's HTML, avoid setting `id` on resources that load data specific to the user who triggered the server-side render, especially if the rendered HTML can be cached or shared between users.
-->

## SSR에서 `resource` 데이터 캐싱하기

애플리케이션을 서버에서 렌더링하면 리소스 로더가 초기 HTML을 만들기 위해 한 번 실행됩니다. 하이드레이션 시에는 일반적으로 브라우저가 같은 로더를 다시 실행합니다.

서버의 결과를 재사용하려면 리소스에 `id`를 지정하세요. Angular는 서버에서 확정된 값을 `TransferState`에 저장하고, 클라이언트에서 이 값으로 리소스를 `'resolved'` 상태로 초기화합니다:

```ts
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
  id: 'user-unique-id',
});
```

`id`는 애플리케이션 안에서 고유해야 하고 서버와 클라이언트에서 같아야 합니다. 그래야 Angular가 캐시 항목을 해당 리소스와 연결할 수 있습니다.

중요: 캐시된 값은 페이지 HTML에 직렬화됩니다. 서버 사이드 렌더링을 요청한 사용자에게만 해당하는 데이터를 불러오는 리소스에는 `id`를 설정하지 마세요. 특히 렌더링된 HTML을 캐시하거나 여러 사용자가 공유할 수 있을 때 주의하세요.

<!--
## Chaining resources

Sometimes one resource depends on the result of another. You can express this dependency using the `chain` function available in the `params` context object.

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

Here `companyResource` depends on the user's `companyId`, which is only known once `userResource` has loaded. `chain(userResource)` reads the value of `userResource` and automatically propagates its status to `companyResource`:

- If `userResource` is **idle**, `companyResource` also becomes `idle`.
- If `userResource` is **loading** or **reloading**, `companyResource` enters the `loading` state and its loader does not run. Note that during `reloading`, `chain` does not return the previously resolved value.
- If `userResource` is in an **error** state, `companyResource` also enters the `error` state.
- If `userResource` is **resolved** or **local**, `chain` returns its current value, which `companyResource` then uses as its params.

When `chain` propagates a status from `userResource` (`idle`, `loading`, `reloading`, or `error`), the params function does not continue. When `userResource` is `resolved` or `local`, `chain` returns its value, which can itself be `undefined`. The example handles this with `chain(userResource)?.companyId`, so an `undefined` value results in `undefined` params and `companyResource` becomes `idle`.

NOTE: Pass the chained value directly as the params value rather than wrapping it in an object. A params value like `{companyId: undefined}` is still a defined value, so the loader would run with an `undefined` `companyId` instead of the resource becoming `idle`.
-->

## 리소스 연결하기

리소스가 다른 리소스의 결과에 의존하는 경우, `params` 컨텍스트 객체의 `chain` 함수로 의존 관계를 표현할 수 있습니다:

```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`는 `userResource` 로드가 끝난 뒤에야 알 수 있는 사용자의 `companyId`에 의존합니다. `chain(userResource)`는 `userResource`의 값을 읽고 상태를 `companyResource`로 자동 전파합니다:

- `userResource`가 **idle**이면 `companyResource`도 `idle`이 됩니다.
- `userResource`가 **loading** 또는 **reloading**이면 `companyResource`는 `loading` 상태가 되고 로더를 실행하지 않습니다. `reloading` 동안에는 `chain`이 이전에 확정된 값을 반환하지 않습니다.
- `userResource`가 **error** 상태이면 `companyResource`도 `error` 상태가 됩니다.
- `userResource`가 **resolved** 또는 **local**이면 `chain`은 현재 값을 반환하고, `companyResource`는 이 값을 매개변수로 사용합니다.

`chain`이 `userResource`의 `idle`, `loading`, `reloading`, `error` 상태를 전파하면 `params` 함수의 실행은 더 이상 진행되지 않습니다. `userResource`가 `resolved`나 `local`이면 `chain`은 값을 반환하며, 값 자체가 `undefined`일 수도 있습니다. 예제에서는 `chain(userResource)?.companyId`로 처리하므로 값이 `undefined`이면 매개변수도 `undefined`가 되고 `companyResource`는 `idle` 상태가 됩니다.

참고: 연결된 값을 객체로 감싸지 말고 매개변수 값으로 직접 전달하세요. `{companyId: undefined}`도 정의된 값이므로 리소스가 `idle`이 되는 대신 `companyId`가 `undefined`인 상태로 로더를 실행합니다.

<!--
### Chaining vs. reading resource values directly

You might be tempted to read a resource's value directly inside `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),
});
```

While this works, returning `undefined` from `params` makes the resource go `idle` rather than reflecting the actual state of the upstream resource. Using `chain` is preferred because it correctly mirrors `loading` and `error` states.

Reach for `chain` only when the downstream resource performs its own async work that depends on the upstream value. If you only need to derive a value synchronously from a resource, use `computed` instead.
-->

### 연결하기와 리소스 값을 직접 읽기의 차이

`params` 안에서 리소스 값을 직접 읽고 싶을 수도 있습니다:

```typescript
{avoid, header: 'reads value() directly without status propagation'}
const companyResource = resource({
  params: () => {
    const user = userResource.value(); // undefined일 수 있습니다.
    return user ? {companyId: user.companyId} : undefined;
  },
  loader: ({params}) => fetchCompany(params.companyId),
});
```

이 방식도 동작하지만 `params`가 `undefined`를 반환하면 선행 리소스의 실제 상태를 반영하는 대신 리소스가 `idle`이 됩니다. `loading`과 `error` 상태를 정확히 반영하는 `chain`을 사용하는 것이 좋습니다.

후행 리소스가 선행 리소스의 값에 의존하는 비동기 작업을 직접 수행할 때만 `chain`을 사용하세요. 리소스에서 값을 동기적으로 파생하기만 하면 되는 경우에는 `computed()` 함수를 사용하세요.

## 반응형으로 데이터 불러오기: `httpResource`

[`httpResource`](/guide/http/http-resource)는 요청 결과를 시그널로 보내는 `HttpClient` 래퍼(wrapper)입니다.
이 래퍼는 인터셉터를 포함하여 Angular HTTP 스택을 그대로 활용합니다.

<!--
## Resource composition with snapshots

A `ResourceSnapshot` is a structured representation of a resource's current state. Every resource has a `snapshot` property that provides a signal of its current state.

```ts
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

const userSnapshot = userResource.snapshot;
```

Each snapshot contains a `status` and either a `value` or an `error`.
-->

## resource 상태 확인하기

`ResourceSnapshot`을 확인하면 `resource` 시그널의 현재 상태를 참조할 수 있습니다.
`resource` 시그널은 모두 현재 상태를 확인할 수 있는 `snapshot` 프로퍼티를 제공합니다.

```ts
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

const userSnapshot = userResource.snapshot;
```

개별 스냅샷에는 `status` 프로퍼티가 존재하고, `value`나 `error` 프로퍼티 중 하나도 존재합니다.

### 스냅샷으로 resource 조합하기

<!--
IMPORTANT: `resourceFromSnapshots` is [experimental](reference/releases#experimental). It's ready for you to try, but it might change before it is stable.

You can create new resources from snapshots using `resourceFromSnapshots`. This enables composition with signal APIs like `computed` and `linkedSignal` to transform resource behavior.

```ts
import {
  Component,
  input,
  linkedSignal,
  resourceFromSnapshots,
  Resource,
  ResourceSnapshot,
} from '@angular/core';
import {httpResource} from '@angular/common/http';

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

IMPORTANT: `resourceFromSnapshots`는 [실험적 기능](reference/releases#experimental)입니다. 지금 사용해 볼 수 있지만, 안정화되기 전까지 변경될 수 있습니다.

`resourceFromSnapshots`를 사용하면 스냅샷으로 새로운 `resource` 시그널을 만들 수 있습니다.
`computed()` 함수나 `linkedSignal`도 사용할 수 있습니다.

```ts
import {
  Component,
  input,
  linkedSignal,
  resourceFromSnapshots,
  Resource,
  ResourceSnapshot,
} from '@angular/core';
import {httpResource} from '@angular/common/http';

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') {
        // 입력 시그널이 로딩 상태에 들어가면, 일단 이전 값을 유지합니다.
        return {status: 'loading' as const, value: previous.value.value};
      }

// 아니면 입력 리소스 시그널의 상태를 반환합니다.
      return snap;
    },
  });

return resourceFromSnapshots(derived);
}

@Component({/*... */})
export class AwesomeProfile {
  userId = input.required<number>();
  user = withPreviousValue(httpResource(() => `/user/${this.userId()}`));
  // userId 값이 변경되면 새 값이 로딩될 때까지 user.value()가 이전 값을 유지합니다.
}
```
<!--
TIP: Check out Angular's [Essentials](essentials/dependency-injection) before diving into this comprehensive guide.

As an application grows, developers often need to reuse and share functionality across different parts of the codebase. [Dependency Injection (DI)](https://en.wikipedia.org/wiki/Dependency_injection) helps you achieve this by allowing you to provide dependencies to a class instead of creating them directly inside it. This makes different parts of the application more reusable and easier to manage.

Dependency injection is a popular pattern because it allows developers to address common challenges such as:

- **Improved code maintainability**: Dependency injection promotes a clear separation of concerns, making code easier to refactor and reducing duplication.
- **Scalability**: You can reuse modular functionality across different parts of an application, making it easier to scale.
- **Better testing**: DI allows unit tests to use [test doubles](https://en.wikipedia.org/wiki/Test_double) in place of real implementations when needed.
-->

팁: 이 문서에서 다루는 내용을 읽기 전에 Angular [핵심](essentials/dependency-injection)을 먼저 보는 것이 좋습니다.

애플리케이션이 커지면서 개발자가 코드를 재사용하거나 서로 다른 부분에서 공유해야 하는 경우가 있습니다.
[의존성 주입(DI)](https://en.wikipedia.org/wiki/Dependency_injection)을 활용하면 클래스 안에서 의존성을 직접 생성하지 않고 외부에서 제공받을 수 있기 때문에 이런 요구사항을 해결할 수 있습니다.
그래서 애플리케이션의 각 부분을 재사용하기 쉬워지고 관리하기도 편해집니다.

의존성 주입은 다음과 같은 일반적인 문제를 해결할 수 있기 때문에 널리 사용됩니다:

- **코드의 유지보수성 향상**: 의존성 주입 패턴을 활용하면 관심사의 분리 원칙에 따라 코드를 분리하기 때문에 코드 중복을 방지하고 리팩토링하기 편합니다.
- **확장성**: 기능을 모듈화하면 여러 곳에서 재사용할 수 있기 때문에 확장하기 편합니다.
- **테스트 편의성**: 의존성 주입 패턴을 활용하면 실제 동작하는 구현 로직 대신 [테스트 더블](https://en.wikipedia.org/wiki/Test_double)을 활용할 수 있기 때문에 유닛 테스트하기 편합니다.

## Angular에서 의존성 주입이 어떻게 동작하나요?

<!--
A dependency is any object, value, function, or service that a class requires to work but does not create itself. Instead, you provide it from the outside, creating a clear relationship between different parts of the application.

You interact with a dependency injection system in two main ways:

- You can _provide_, or make available, values.
- You can _inject_, or ask for, those values as dependencies.

In this context, "values" can refer to any JavaScript value, including objects, functions, or class instances. Common types of injected dependencies include:

- **Configuration values**: Environment-specific constants, API URLs, feature flags, etc.
- **Factories**: Functions that create objects or values based on runtime conditions
- **Services**: Classes that provide common functionality, business logic, or state

Angular components and directives automatically participate in DI, meaning that you can inject dependencies into them and make them available for injection.
-->

의존성이란 클래스가 동작하는 데 필요하지만 클래스 안에서 직접 생성하지 않는 객체, 값, 함수, 서비스를 의미합니다.
의존성은 클래스 외부에서 제공하며, 이를 통해 애플리케이션의 각 부분 사이에 명확한 관계가 만들어집니다.

코드가 의존성 주입 시스템과 상호작용하는 방법은 두 가지입니다:

- 값을 _제공(provide)_ 해서 사용할 수 있게 만들 수 있습니다.
- 그렇게 제공된 값을 의존성으로 요청해서 _주입(inject)_ 받을 수 있습니다.

이때 "값"은 객체, 함수, 클래스 인스턴스를 포함한 모든 JavaScript 값을 의미합니다.
보통은 이런 것들이 의존성이 됩니다:

- **설정값**: 환경변수, API URL, 기능 스위치 플래그 등
- **팩토리**: 실행환경 상태에 따라 객체나 값을 생성하는 함수
- **서비스**: 어떤 로직을 구현하거나 비즈니스 로직, 상태를 관리하는 클래스

Angular 컴포넌트와 디렉티브는 기본적으로 의존성 주입 시스템의 일부이기 때문에, 의존성 객체를 주입받을 수 있고, 의존성으로 주입될 수도 있습니다.

## 서비스가 무엇인가요?

<!--
An Angular _service_ is a TypeScript class decorated with `@Service`, which allows you to inject an instance of the class as a dependency. Services are the most common way of sharing data and functionality across an application.

Common types of services include:

- **Data clients:** Abstracts the details of making requests to a server for data retrieval and mutation
- **State management:** Defines state shared across multiple components or pages
- **Authentication and authorization:** Manages user authentication, token storage, and access control
- **Logging and error handling:** Establishes a common API for logging or communicating error states to the user
- **Event handling and dispatch:** Handles events or notifications that are not associated with a specific component, or for dispatching events and notifications to components, following the [observer pattern](https://en.wikipedia.org/wiki/Observer_pattern)
- **Utility functions:** Offers reusable utility functions like data formatting, validation, or calculations

The following example declares a service named `AnalyticsLogger`:

```ts
import {Service} from '@angular/core';

@Service()
export class AnalyticsLogger {
  trackEvent(category: string, value: string) {
    console.log('Analytics event logged:', {
      category,
      value,
      timestamp: new Date().toISOString(),
    });
  }
}
```

NOTE: The `@Service` makes this service available throughout your entire application as a singleton. This is the recommended approach for most services.
-->

Angular에서 이야기하는 _서비스(service)_ 란 `@Service` 데코레이터가 붙은 TypeScript 클래스이며, 이 클래스를 인스턴스로 생성하면 의존성으로 주입할 수 있습니다.
서비스는 애플리케이션 전역에서 데이터와 기능을 공유하는 용도로 가장 많이 사용됩니다.

일반적으로 서비스는 이런 역할을 합니다:

- **데이터 요청:** 서버에 데이터를 요청하거나 변형하는 과정을 추상화합니다.
- **상태 관리:** 컴포넌트나 화면에서 공유하는 상태값을 선언하고 관리합니다.
- **인증, 권한 부여:** 사용자 인증을 처리하고 토큰을 보관하며 접근 권한을 관리합니다.
- **로그, 오류 처리:** 오류 상태를 로그로 출력하거나 사용자에게 알리기 위한 API를 마련합니다.
- **이벤트 처리, 전달:** 컴포넌트가 처리하지 않는 이벤트를 공통으로 처리하거나, [옵저버 패턴(observer pattern)](https://en.wikipedia.org/wiki/Observer_pattern)에 따라 컴포넌트에 이벤트를 전달합니다.
- **유틸리티 함수:** 데이터 형식 변환, 유효성 검사, 계산과 같은 재사용 유틸리티 함수를 제공합니다.

아래 코드는 `AnalyticsLogger`라는 서비스의 예제 코드입니다:

```ts
import {Service} from '@angular/core';

참고: `@Service` 데코레이터를 지정하면 서비스를 전역 범위에서 사용할 수 있도록 인스턴스를 싱글턴으로 생성합니다. 대부분의 경우 이런 사용 방식을 권장합니다.

참고: [`@Service`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator) 데코레이터는 `@Injectable({providedIn: 'root'})`를 간편하게 작성하는 단축 문법입니다.

## `inject()`로 의존성 주입하기

<!--
You can inject dependencies using Angular's `inject()` function.

Here is an example of a navigation bar that injects `AnalyticsLogger` and Angular `Router` service to allow users to navigate to a different page while tracking the event.

```typescript
import {Component, inject} from '@angular/core';
import {Router} from '@angular/router';
import {AnalyticsLogger} from './analytics-logger';

@Component({
  selector: 'app-navbar',
  template: `<a href="#" (click)="navigateToDetail($event)">Detail Page</a>`,
})
export class Navbar {
  private router = inject(Router);
  private analytics = inject(AnalyticsLogger);

navigateToDetail(event: Event) {
    event.preventDefault();
    this.analytics.trackEvent('navigation', '/details');
    this.router.navigate(['/details']);
  }
}
```
-->

의존성 객체는 Angular가 제공하는 `inject()` 함수로 주입할 수 있습니다.

아래 코드는 `AnalyticsLogger`와 Angular `Router`를 의존성 객체로 주입받아서 이벤트에 따라 화면을 전환하는 네비게이션 바 컴포넌트의 예제 코드입니다.

```typescript
import {Component, inject} from '@angular/core';
import {Router} from '@angular/router';
import {AnalyticsLogger} from './analytics-logger';

navigateToDetail(event: Event) {
    event.preventDefault();
    this.analytics.trackEvent('navigation', '/details');
    this.router.navigate(['/details']);
  }
}
```

### `inject()`는 어디에 사용할 수 있나요?

<!--
You can inject dependencies during construction of a component, directive, or service. The call to [`inject`](/api/core/inject) can appear in either the `constructor` or in a field initializer. Here are some common examples:

```ts
@Component(/* ... */)
export class MyComponent {
  // ✅ In class field initializer
  private service = inject(MyService);

// ✅ In constructor body
  private anotherService: MyService;

constructor() {
    this.anotherService = inject(MyService);
  }
}
```

```ts
@Directive({...})
export class MyDirective {
  // ✅ In class field initializer
  private element = inject(ElementRef);
}
```

```ts
import {Service, inject} from '@angular/core';
import {HttpClient} from '@angular/common/http';

@Service()
export class MyService {
  // ✅ In a service
  private http = inject(HttpClient);
}
```

```ts
export const authGuard = () => {
  // ✅ In a route guard
  const auth = inject(AuthService);
  return auth.isAuthenticated();
};
```

Angular uses the term "injection context" to describe any place in your code where you can call [`inject`](/api/core/inject). While component, directive, and service construction is the most common, see [injection contexts](/guide/di/dependency-injection-context) for more details.

For more information, see the [inject API docs](api/core/inject#usage-notes).
-->

의존성 객체는 컴포넌트, 디렉티브, 서비스를 생성할 때 주입할 수 있습니다.
`inject` 함수를 직접 사용하거나 `constructor()` 함수에서 프로퍼티로 선언하면 됩니다:

```ts
@Component(/* ... */)
export class MyComponent {
  // ✅ 클래스 필드 초기화로 주입
  private service = inject(MyService);

// ✅ 생성자에서 주입
  private anotherService: MyService;

constructor() {
    this.anotherService = inject(MyService);
  }
}
```

```ts
@Directive({...})
export class MyDirective {
  // ✅ 클래스 필드 초기화로 주입
  private element = inject(ElementRef);
}
```

```ts
import {Service, inject} from '@angular/core';
import {HttpClient} from '@angular/common/http';

@Service()
export class MyService {
  // ✅ 서비스에서 주입
  private http = inject(HttpClient);
}
```

```ts
export const authGuard = () => {
  // ✅ 라우팅 규칙 가드에서 주입
  const auth = inject(AuthService);
  return auth.isAuthenticated();
};
```

[`inject`](/api/core/inject)를 사용할 수 있는 코드 범위를 "의존성 주입 컨텍스트(injection context)"라고 합니다.
일반적으로는 컴포넌트, 디렉티브, 서비스의 생성자가 [의존성 주입 컨텍스트](/guide/di/dependency-injection-context) 입니다.

자세한 내용은 [inject API 문서](api/core/inject#usage-notes)를 참고하세요.

## 다음 단계

<!--
Now that you understand the fundamentals of dependency injection in Angular, you're ready to learn how to create your own services.

The next guide, [Creating and using services](guide/di/creating-and-using-services), will show you:

- How to create a service with the Angular CLI or manually
- How the `providedIn: 'root'` pattern works
- How to inject services into components and other services

This covers the most common use case for services in Angular applications.
-->

이제 Angular의 의존성 주입의 기본을 학습했습니다.
서비스를 직접 만들어 보세요.

다음 가이드 문서에서는 [서비스를 생성](guide/di/creating-and-using-services)하고 이런 내용을 다룹니다:

- Angular CLI나 수동으로 서비스를 생성하는 방법
- `providedIn: 'root'` 패턴이 동작하는 방식
- 서비스를 컴포넌트나 다른 서비스로 의존성 주입하는 방법

Angular 애플리케이션에서 서비스를 사용하는 방법 중 가장 기본을 알아봅시다.

# 서비스 생성하기, 활용하기

서비스는 애플리케이션 전역에서 코드를 공유하고 재사용할 수 있는 코드 묶음입니다.
서비스에는 일반적으로 데이터를 서버에서 받아오거나, 비즈니스 로직을 제공하는 등 다양한 컴포넌트에 필요한 기능을 구현합니다.

## 서비스 생성하기

<!--
You can create a service using the [Angular CLI](tools/cli) with the following command:

```bash
ng generate service CUSTOM_NAME
```

This command creates a dedicated `CUSTOM_NAME.ts` file in your `src` directory.

You can also manually create a service by adding the `@Service()` decorator to a TypeScript class. This tells Angular that you can use the class as an injectable dependency.

The following example defines a service that allows users to add and retrieve data:

```ts
{header: "src/app/basic-data-store.ts"}
import {Service} from '@angular/core';

@Service()
export class BasicDataStore {
  private data: string[] = [];

addData(item: string): void {
    this.data.push(item);
  }

getData(): string[] {
    return [...this.data];
  }
}
```
-->

서비스는 [Angular CLI](tools/cli) 명령을 실행하면 생성할 수 있습니다:

```bash
ng generate service CUSTOM_NAME
```

이 명령을 실행하면 `src` 디렉토리에 `CUSTOM_NAME.ts` 라는 파일이 생성됩니다.

서비스는 일반 TypeScript 클래스에 `@Service()` 데코레이터를 붙여서 직접 선언할 수도 있습니다.
이 데코레이터는 데코레이터가 붙은 클래스는 Angular가 의존성 객체로 취급할 수 있다는 것을 알리는 역할을 합니다.

사용자가 데이터를 추가하고 조회하는 예제 서비스라면 이렇게 구현합니다:

```ts
{header: "src/app/basic-data-store.ts"}
import {Service} from '@angular/core';

@Service()
export class BasicDataStore {
  private data: string[] = [];

addData(item: string): void {
    this.data.push(item);
  }

getData(): string[] {
    return [...this.data];
  }
}
```

<!--
## How services become available

Services are provisioned at the root level by default. When a service is provided globally, Angular guarantees three main benefits:

- **Singleton Instance:** Creates a single, shared instance for the entire application.
- **Global Availability:** Automatically accessible anywhere without manual provider registration.
- **Tree-shakability:** Ensures the service is excluded from the final production bundle if your code never explicitly uses it.
-->

## 서비스는 어떻게 사용할 수 있나요 {#how-services-become-available}

서비스는 기본적으로 최상위 계층에 제공됩니다. 서비스를 전역으로 제공하면 Angular가 다음 세 가지 이점을 보장합니다.

- **싱글턴 인스턴스:** 애플리케이션 전체에서 공유하는 인스턴스를 하나만 생성합니다.
- **전역 사용:** 프로바이더를 수동으로 등록하지 않아도 어디서든 사용할 수 있습니다.
- **트리 셰이킹:** 코드에서 서비스를 명시적으로 사용하지 않으면 최종 프로덕션 빌드 결과물에서 제외합니다.

<!--
### Using the `@Service` vs `@Injectable` decorator

The `@Service` decorator serves as a modern, ergonomic shorthand for the traditional `@Injectable({ providedIn: 'root' })` syntax.

Use this quick reference to decide which decorator fits your scenario:

| Feature / Requirement                         | `@Service` | `@Injectable`                           |
| --------------------------------------------- | ---------- | --------------------------------------- |
| **`inject()` function support**               | Yes        | Yes                                     |
| **Constructor-based DI**                      | ❌ No      | Yes                                     |
| **Implicit root singleton provider**          | Yes        | ❌ No (requires `{providedIn: 'root'}`) |
| **Advanced provider keys (`useClass`, etc.)** | ❌ No      | Yes                                     |
| **Custom initialization factories**           | Yes        | Yes                                     |
| **Non-root scopes (`platform`, etc.)**        | ❌ No      | Yes                                     |
-->

### `@Service`와 `@Injectable` 데코레이터 선택하기 {#using-the-service-vs-injectable-decorator}

`@Service` 데코레이터는 기존의 `@Injectable({ providedIn: 'root' })` 문법을 더 간편하게 작성하는 현대적인 단축 문법입니다.

다음 표를 참고해서 상황에 맞는 데코레이터를 선택하세요.

| 기능 / 요구사항                       | `@Service`       | `@Injectable`                                  |
| ------------------------------------- | ---------------- | ---------------------------------------------- |
| **`inject()` 함수 지원**              | 지원             | 지원                                           |
| **생성자 기반 DI**                    | ❌ 지원하지 않음 | 지원                                           |
| **암묵적인 최상위 싱글턴 프로바이더** | 지원             | ❌ 지원하지 않음 (`{providedIn: 'root'}` 필요) |
| **고급 프로바이더 키(`useClass` 등)** | ❌ 지원하지 않음 | 지원                                           |
| **커스텀 초기화 팩토리**              | 지원             | 지원                                           |
| **최상위 이외의 범위(`platform` 등)** | ❌ 지원하지 않음 | 지원                                           |

## 구현부를 팩토리로 사용하기

<!--
If you need to control how the singleton is created, for example, to swap in a different implementation depending on the environment, pass a `factory` function.

The factory runs in an [injection context](guide/di/dependency-injection-context), so you can use [`inject()`](api/core/inject) inside it to read other dependencies.

The following `Analytics` service is a no-op locally so events don't pollute the console during development. In production, the factory reads an `ANALYTICS_ENABLED` token and returns a `GoogleAnalytics` subclass that forwards events to the real tracker:

```ts
{header: "src/app/analytics.ts"}
import {inject, InjectionToken, Service} from '@angular/core';
import {ANALYTICS_ENABLED} from './token';

@Service({
  factory: () => (inject(ANALYTICS_ENABLED) ? new GoogleAnalytics() : new Analytics()),
})
export class Analytics {
  track(event: string, payload?: Record<string, unknown>) {
    // No-op by default.
  }
}

class GoogleAnalytics extends Analytics {
  override track(event: string, payload?: Record<string, unknown>) {
    // Dispatches an analytics event to Google Analytics
  }
}
```

NOTE: The `factory` option replaces the `useClass`, `useValue`, `useExisting`, and `useFactory` options of `@Injectable`. If you need any of those, keep using `@Injectable`.
-->

환경변수에 따라 구현을 다르게 하는 등 싱글턴 인스턴스의 생성방식을 제어해야 하는 경우에는 `factory` 함수를 사용합니다.

`factory` 함수는 [의존성 주입 컨텍스트](guide/di/dependency-injection-context) 안에서 실행되기 때문에, [`inject()`](api/core/inject)를 사용해서 다른 의존성 객체를 받을 수도 있습니다.

아래 `Analytics` 서비스 코드는 로컬 환경에서는 아무 동작도 하지 않습니다.
그리고 운영환경에서는 팩토리 함수가 `ANALYTICS_ENABLED` 토큰 값을 읽어서 `GoogleAnalytics` 클래스를 활용해서 실제 동작을 수행합니다:

```ts
{header: "src/app/analytics.ts"}
import {inject, InjectionToken, Service} from '@angular/core';
import {ANALYTICS_ENABLED} from './token';

class GoogleAnalytics extends Analytics {
  override track(event: string, payload?: Record<string, unknown>) {
    // Google Analytics에 이벤트를 보냅니다.
  }
}
```

참고: `factory` 함수는 `@Injectable`에 사용했던 `useClass`, `useValue`, `useExisting`, `useFactory`를 대체하는 옵션입니다. 이전 방식을 사용하려면 `@Injectable` 데코레이터를 사용하세요.

### 자동 프로비저닝 비활성화하기

<!--
By default, `@Service` provides the class at the root injector. If you want to provide it manually, for example, to scope it to a specific route or component, set `autoProvided: false`:

```ts
{header: "src/app/analytics-logger.ts"}
import {Service} from '@angular/core';

@Service({autoProvided: false})
export class AnalyticsLogger {
  trackEvent(name: string) {
    console.log('event:', name);
  }
}
```

You are then responsible for adding the service to a `providers` array, just like with a plain `@Injectable()`:
-->

`@Service` 데코레이터를 지정한 클래스는 최상위 인젝터에 등록됩니다.
그런데 이 클래스를 특정 라우팅 규칙이나 특정 컴포넌트 안에서만 사용하도록 수동으로 등록하고 싶다면 `autoProvided: false`를 사용하면 됩니다:

```ts
{header: "src/app/analytics-logger.ts"}
import {Service} from '@angular/core';

@Service({autoProvided: false})
export class AnalyticsLogger {
  trackEvent(name: string) {
    console.log('event:', name);
  }
}
```

이렇게 구현하면 `@Injectable()`에 했던 것처럼 `providers` 배열에 서비스를 직접 등록해야 합니다.

### `@Service` vs. `@Injectable`

<!--
Reach for `@Service` when you are creating a new singleton class that uses `inject()` for its dependencies. Keep using `@Injectable` when you need any of the following:

- **Constructor-based dependency injection.** `@Service` only supports the [`inject()`](api/core/inject) function.
- **Advanced provider configuration** such as `useClass`, `useValue`, `useExisting`, or `useFactory`. `@Service` exposes a single `factory` option instead.
- **Non-root scopes** such as `providedIn: 'platform'`.
-->

일반적으로 싱글턴으로 사용하는 클래스에는 `@Service`를 사용하세요.
`inject()`를 사용해서 추가 의존성 객체를 주입할 수도 있습니다.
그리고 다음 경우라면 `@Injectable` 사용을 유지하는 것을 권장합니다:

- **생성자로 의존성을 주입하는 경우** - `@Service` 데코레이터는 [`inject()`](api/core/inject) 함수만 지원합니다.
- **프로바이더를 복잡하게 구성하는 경우** - `useClass`, `useValue`, `useExisting`, `useFactory` 를 사용하는 경우에는 `@Injectable`을 사용하세요. `@Service` 데코레이터와 `factory` 함수로 대체할 수 있습니다.
- **최상위 스코프가 아닌 경우** - `providedIn: 'platform'`에 등록하는 경우

## 서비스를 의존성으로 주입하기

서비스에 `providedIn: 'root'`를 지정해서 선언하고 나면, 이 서비스는 `inject()` 함수를 사용해서 애플리케이션 전역에 주입할 수 있습니다.

### 컴포넌트에 주입하기

```typescript
import {Component, inject} from '@angular/core';
import {BasicDataStore} from './basic-data-store';

@Component({
  selector: 'app-example',
  template: `
    <div>
      <p>{{ dataStore.getData() }}</p>
      <button (click)="dataStore.addData('More data')">Add more data</button>
    </div>
  `,
})
export class Example {
  dataStore = inject(BasicDataStore);
}
```

### 다른 서비스에 주입하기

```ts
import {inject, Service} from '@angular/core';
import {AdvancedDataStore} from './advanced-data-store';

@Service()
export class BasicDataStore {
  private advancedDataStore = inject(AdvancedDataStore);
  private data: string[] = [];

addData(item: string): void {
    this.data.push(item);
  }

getData(): string[] {
    return [...this.data, ...this.advancedDataStore.getData()];
  }
}
```

## 다음 단계

<!--
While `providedIn: 'root'` covers most use cases, Angular also provides additional ways you can configure services for more specialized scenarios:

- **Component-specific instances** - When components need their own isolated service instances
- **Manual configuration** - For services that require runtime configuration
- **Factory providers** - For dynamic service creation based on runtime conditions
- **Value providers** - For providing configuration objects or constants

You can learn more about these advanced patterns in the next guide: [defining dependency providers](/guide/di/defining-dependency-providers).
-->

`providedIn: 'root'`는 대부분의 경우에 유효하지만, 다음과 같은 경우에는 설정을 다르게 하기도 합니다:

- **컴포넌트별 인스턴스** - 컴포넌트마다 서비스의 개별 인스턴스를 사용하는 경우
- **수동으로 설정하는 경우** - 실행환경 구성이 필요한 경우
- **팩토리 프로바이더** - 실행환경에 따라 서비스를 동적으로 생성하는 경우
- **값 프로바이더** - 환경설정 객체나 상수를 제공하는 경우

이런 경우 어떻게 활용하는지 알아보려면 다음 문서인 [의존성 주입 프로바이더 정의하기](/guide/di/defining-dependency-providers) 문서를 참고하세요.

# 의존성 프로바이더 정의하기

<!--
Angular provides two ways to make services available for injection:

1. **Automatic provision** - Using `providedIn` in the `@Injectable` decorator, the [`@Service`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator) decorator, or by providing a factory in the `InjectionToken` configuration
2. **Manual provision** - Using the `providers` array in components, directives, routes, or application config

In the [previous guide](/guide/di/creating-and-using-services), you learned how to create services using `providedIn: 'root'`, which handles most common use cases. This guide explores additional patterns for both automatic and manual provider configuration.
-->

Angular가 서비스를 의존성 주입 가능하게 만드는 방식은 두 가지입니다:

1. **자동 프로비전(provision)** - `@Injectable` 데코레이터에 `providedIn`을 지정하거나, [`@Service`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator) 데코레이터를 사용하는 경우, `InjectionToken` 설정에서 팩토리를 사용하는 경우
2. **수동 프로비전** - 컴포넌트, 디렉티브, 라우팅 규칙, 애플리케이션 환경설정에서 `providers` 배열을 사용하는 경우

[이전 가이드 문서](/guide/di/creating-and-using-services)에서는 `providedIn: 'root'`를 사용해서 서비스를 생성했고, 이것이 일반적인 사용방법입니다.
이 문서에서는 프로바이더 설정방법을 조금 더 알아봅시다.

## 자동 프로비전: 클래스가 아닌 경우

`@Injectable` 데코레이터에 `providedIn: 'root'`를 사용해도 서비스(클래스)는 잘 동작하지만, 객체나 함수, 기본 자료형을 의존성으로 주입하는 경우가 있을 수 있습니다.
이런 경우에는 `InjectionToken`을 사용합니다.

### 인젝션 토큰이 무엇인가요?

<!--
An `InjectionToken` is an object that Angular's dependency injection system uses to uniquely identify values for injection. Think of it as a special key that lets you store and retrieve any type of value in Angular's DI system:

```ts
import {InjectionToken} from '@angular/core';

// Create a token for a string value
export const API_URL = new InjectionToken<string>('api.url');

// Create a token for a function
export const LOGGER = new InjectionToken<(msg: string) => void>('logger.function');

// Create a token for a complex type
export interface Config {
  apiUrl: string;
  timeout: number;
}
export const CONFIG_TOKEN = new InjectionToken<Config>('app.config');
```

NOTE: The string parameter (e.g., `'api.url'`) is a description purely for debugging — Angular identifies tokens by their object reference, not this string.
-->

`InjectionToken`은 Angular 의존성 주입 시스템이 의존성 객체가 어떤 것인지 구분하는 객체입니다.
의존성 객체에 매겨진 특별한 키 값이며, 의존성 객체를 요청할 때 사용하는 값이라고 이해하면 됩니다:

```ts
import {InjectionToken} from '@angular/core';

// 문자열 값으로 토큰을 생성합니다.
export const API_URL = new InjectionToken<string>('api.url');

// 함수로 토큰을 생성합니다.
export const LOGGER = new InjectionToken<(msg: string) => void>('logger.function');

// 복잡한 타입으로 토큰을 생성합니다.
export interface Config {
  apiUrl: string;
  timeout: number;
}
export const CONFIG_TOKEN = new InjectionToken<Config>('app.config');
```

참고: `'api.url'`과 같은 문자열 값은 디버깅을 위한 설명일 뿐입니다. Angular는 이 문자열이 아닌 객체 참조로 토큰을 식별합니다.

### `providedIn: 'root'`를 사용하는 인젝션 토큰

<!--
An `InjectionToken` that has a `factory` results in `providedIn: 'root'` by default (but can be overridden via the `providedIn` prop).

```ts
{header: "/app/config.token.ts"}
import {InjectionToken, Component, inject} from '@angular/core';

export interface AppConfig {
  apiUrl: string;
  version: string;
  features: Record<string, boolean>;
}

// Globally available configuration using providedIn
export const APP_CONFIG = new InjectionToken<AppConfig>('app.config', {
  providedIn: 'root',
  factory: () => ({
    apiUrl: 'https://api.example.com',
    version: '1.0.0',
    features: {
      darkMode: true,
      analytics: false,
    },
  }),
});

// No need to add to providers array - available everywhere!
@Component({
  selector: 'app-header',
  template: `<h1>Version: {{ config.version }}</h1>`,
})
export class Header {
  config = inject(APP_CONFIG); // Automatically available
}
```
-->

`factory` 프로퍼티를 사용하는 `InjectionToken`은 기본적으로 `providedIn: 'root'` 값을 갖습니다.
하지만 `providedIn` 프로퍼티가 다시 지정되면 오버라이드할 수 있습니다.

```ts
{header: "/app/config.token.ts"}
import {InjectionToken, Component, inject} from '@angular/core';

export interface AppConfig {
  apiUrl: string;
  version: string;
  features: Record<string, boolean>;
}

// providedIn을 사용했기 때문에 애플리케이션 전역에서 사용할 수 있습니다.
export const APP_CONFIG = new InjectionToken<AppConfig>('app.config', {
  providedIn: 'root',
  factory: () => ({
    apiUrl: 'https://api.example.com',
    version: '1.0.0',
    features: {
      darkMode: true,
      analytics: false,
    },
  }),
});

// providers 배열에 등록할 필요가 없습니다 - 이미 사용 가능합니다!
@Component({
  selector: 'app-header',
  template: `<h1>Version: {{ config.version }}</h1>`,
})
export class Header {
  config = inject(APP_CONFIG); // 컴포넌트에 등록하지 않아도 사용할 수 있습니다.
}
```

### 팩토리 함수를 사용하는 인젝션 토큰

<!--
InjectionToken with factory functions is ideal when you can't use a class but need to provide dependencies globally:

```ts
{header: "/app/logger.token.ts"}
import {InjectionToken, inject} from '@angular/core';
import {APP_CONFIG} from './config.token';

// Logger function type
export type LoggerFn = (level: string, message: string) => void;

// Global logger function with dependencies
export const LOGGER_FN = new InjectionToken<LoggerFn>('logger.function', {
  providedIn: 'root',
  factory: () => {
    const config = inject(APP_CONFIG);

return (level: string, message: string) => {
      if (config.features.logging !== false) {
        console[level](`[${new Date().toISOString()}] ${message}`);
      }
    };
  },
});

```

```ts
{header: "/app/storage.token.ts"}
// Providing browser APIs as tokens
export const LOCAL_STORAGE = new InjectionToken<Storage>('localStorage', {
  // providedIn: 'root' is configured as the default
  factory: () => window.localStorage,
});

export const SESSION_STORAGE = new InjectionToken<Storage>('sessionStorage', {
  providedIn: 'root',
  factory: () => window.sessionStorage,
});

```

```ts
{header: "/app/feature-flags.token.ts"}
// Complex configuration with runtime logic
export const FEATURE_FLAGS = new InjectionToken<Map<string, boolean>>('feature.flags', {
  providedIn: 'root',
  factory: () => {
    const flags = new Map<string, boolean>();

// Parse from environment or URL params
    const urlParams = new URLSearchParams(window.location.search);
    const enableBeta = urlParams.get('beta') === 'true';

flags.set('betaFeatures', enableBeta);
    flags.set('darkMode', true);
    flags.set('newDashboard', false);

return flags;
  },
});
```

This approach offers several advantages:

- **No manual provider configuration needed** - Works just like `providedIn: 'root'` for services
- **Tree-shakeable** - Only included if actually used
- **Type-safe** - Full TypeScript support for non-class values
- **Can inject other dependencies** - Factory functions can use `inject()` to access other services
-->

팩토리 함수를 사용하는 `InjectionToken`은 클래스를 사용할 수 없지만 의존성을 전역으로 제공해야 할 때 유용합니다:

```ts
{header: "/app/logger.token.ts"}
import {InjectionToken, inject} from '@angular/core';
import {APP_CONFIG} from './config.token';

// 로그 함수 타입
export type LoggerFn = (level: string, message: string) => void;

// 전역 로그 함수
export const LOGGER_FN = new InjectionToken<LoggerFn>('logger.function', {
  providedIn: 'root',
  factory: () => {
    const config = inject(APP_CONFIG);

return (level: string, message: string) => {
      if (config.features.logging !== false) {
        console[level](`[${new Date().toISOString()}] ${message}`);
      }
    };
  },
});
```

```ts
{header: "/app/storage.token.ts"}
// 브라우저 API를 토컨으로 등록합니다.
export const LOCAL_STORAGE = new InjectionToken<Storage>('localStorage', {
  // providedIn: 'root' is configured as the default
  factory: () => window.localStorage,
});

export const SESSION_STORAGE = new InjectionToken<Storage>('sessionStorage', {
  providedIn: 'root',
  factory: () => window.sessionStorage,
});
```

```ts
{header: "/app/feature-flags.token.ts"}
// 실행환경에 따라 복잡한 환경설정을 등록합니다.
export const FEATURE_FLAGS = new InjectionToken<Map<string, boolean>>('feature.flags', {
  providedIn: 'root',
  factory: () => {
    const flags = new Map<string, boolean>();

// 환경변수나 URL 인자를 파싱합니다.
    const urlParams = new URLSearchParams(window.location.search);
    const enableBeta = urlParams.get('beta') === 'true';

flags.set('betaFeatures', enableBeta);
    flags.set('darkMode', true);
    flags.set('newDashboard', false);

return flags;
  },
});
```

이 방식은 이런 장점이 있습니다:

- **수동으로 프로바이더를 등록할 필요가 없습니다.** - `providedIn: 'root'` 설정을 하기만 하면 됩니다.
- **트리 셰이킹이 가능합니다.** - 실제로 사용될 때만 빌드 결과물에 포함됩니다.
- **타입 검사가 가능합니다.** - 클래스가 아니더라도 TypeScript 타입 검사를 완벽하게 지원합니다.
- **다른 의존성을 활용할 수 있습니다.** - 팩토리 함수는 `inject()` 함수를 사용해서 다른 서비스를 참조할 수 있습니다.

## 수동 프로바이더 등록 이해하기

<!--
When you need more control than `providedIn: 'root'` offers, you can manually configure providers. Manual configuration through the `providers` array is useful when:

1. **The service doesn't have `providedIn`** - Services without automatic provision must be manually provided
2. **You want a new instance** - To create a separate instance at the component/directive level instead of using the shared one
3. **You need runtime configuration** - When service behavior depends on runtime values
4. **You're providing non-class values** - Configuration objects, functions, or primitive values
-->

의존성 객체를 `providedIn: 'root'` 와는 다르게 조작해야 하는 경우라면 프로바이더를 수동으로 등록하면 됩니다.
`providers` 배열을 활용하는 수동 등록은 이런 경우에 유용합니다:

1. **서비스에 `providedIn`이 설정되지 않았을 때** - 전역 범위에 등록되지 않은 서비스는 수동으로 등록해야 합니다.
2. **인스턴스를 새로 만드는 경우** - 기존에 있던 인스턴스를 사용하지 않고 컴포넌트/디렉티브 계층에서 인스턴스를 새로 만들려고 할 때
3. **실행환경에 맞는 설정을 해야 할 때** - 실행환경에 맞는 설정으로 서비스가 동작해야 할 때
4. **클래스가 아닌 의존성 객체** - 객체나 함수, 기본 타입 의존성 토큰을 사용하는 경우

### 예제: `providedIn`이 설정되지 않은 서비스

<!--
```ts
import {Injectable, Component, inject} from '@angular/core';

// Service without providedIn
@Injectable()
export class LocalDataStore {
  private data: string[] = [];

addData(item: string) {
    this.data.push(item);
  }
}

// Component must provide it
@Component({
  selector: 'app-example',
  // A provider is required here because the `LocalDataStore` service has no providedIn.
  providers: [LocalDataStore],
  template: `...`,
})
export class Example {
  dataStore = inject(LocalDataStore);
}
```
-->

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

// providedIn이 설정되지 않은 서비스
@Injectable()
export class LocalDataStore {
  private data: string[] = [];

addData(item: string) {
    this.data.push(item);
  }
}

// 컴포넌트에서 프로바이더를 등록해야 합니다.
@Component({
  selector: 'app-example',
  // `LocalDataStore` 서비스에 providedIn이 지정되지 않았기 때문에 프로바이더 배열에 등록해야 합니다.
  providers: [LocalDataStore],
  template: `...`,
})
export class Example {
  dataStore = inject(LocalDataStore);
}
```

### 예제: 컴포넌트별 인스턴스를 생성할 때

<!--
Services with `providedIn: 'root'` can be overridden at the component level. This ties the instance of the service to the life of a component. As a result, when the component gets destroyed, the provided service is also destroyed as well.

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

@Injectable({providedIn: 'root'})
export class DataStore {
  private data: ListItem[] = [];
}

// This component gets its own instance
@Component({
  selector: 'app-isolated',
  // Creates new instance of `DataStore` rather than using the root-provided instance.
  providers: [DataStore],
  template: `...`,
})
export class Isolated {
  dataStore = inject(DataStore); // Component-specific instance
}
```
-->

서비스에 `providedIn: 'root'`가 지정되어 있어도 컴포넌트 계층에서 이 값을 오버라이드할 수 있습니다.
이 경우에는 서비스의 인스턴스가 컴포넌트의 라이프사이클와 동일하게 동작합니다.
그래서 컴포넌트가 종료되면 의존성으로 주입된 서비스의 인스턴스도 함께 종료됩니다.

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

@Injectable({providedIn: 'root'})
export class DataStore {
  private data: ListItem[] = [];
}

// 컴포넌트는 의존성 객체의 개별적인 인스턴스를 갖습니다.
@Component({
  selector: 'app-isolated',
  // 전역 범위에 존재하는 인스턴스를 사용하지 않고 `DataStore` 인스턴스를 새로 생성합니다.
  providers: [DataStore],
  template: `...`,
})
export class Isolated {
  dataStore = inject(DataStore); // 컴포넌트와 연동되는 의존성 객체의 인스턴스가 생성됩니다.
}
```

## Angular의 의존성 계층

<!--
Angular's dependency injection system is hierarchical. When a component requests a dependency, Angular starts with that component's injector and walks up the tree until it finds a provider for that dependency. Each component in your application tree can have its own injector, and these injectors form a hierarchy that mirrors your component tree.

This hierarchy enables:

- **Scoped instances**: Different parts of your app can have different instances of the same service
- **Override behavior**: Child components can override providers from parent components
- **Memory efficiency**: Services are only instantiated where needed

In Angular, any element with a component or directive can provide values to all of its descendants.

```mermaid
graph TD
    subgraph platform
        subgraph root
            direction TB
            A[SocialApp] -> B[UserProfile]
            A -> C[FriendList]
            C -> D[FriendEntry]
        end
    end
```

In the example above:

1. `SocialApp` can provide values for `UserProfile` and `FriendList`
2. `FriendList` can provide values for injection to `FriendEntry`, but cannot provide values for injection in `UserProfile` because it's not part of the tree
-->

Angular의 의존성 주입 시스템은 계층으로 구성됩니다.
컴포넌트가 의존성 객체를 요청하면 Angular는 해당 컴포넌트의 인젝터부터 의존성 객체를 찾기 시작해서, 해당 의존성 객체의 프로바이더를 찾을 때까지 트리를 거슬러 올라갑니다.
애플리케이션의 개별 컴포넌트 트리는 개별 인젝터를 구성하기 때문에, 의존성 계층은 컴포넌트 트리의 구조와 동일하다고 볼 수 있습니다.

이 계층 구조는 다음과 같은 점에서 유용합니다:

- **인스턴스의 사용 범위를 지정할 수 있습니다.**: 앱의 일부분마다 같은 서비스라도 다른 인스턴스를 사용할 수 있습니다.
- **프로바이더 오버라이드**: 자식 컴포넌트가 부모 컴포넌트 프로바이더를 오버라이드할 수 있습니다.
- **효율적인 메모리 사용**: 서비스의 인스턴스는 필요한 경우에만 생성됩니다.

Angular에서 컴포넌트나 디렉티브가 적용된 엘리먼트는 모든 하위 요소에 의존성 객체를 제공할 수 있습니다.

```mermaid
graph TD
    subgraph 플랫폼
        subgraph 최상위
            direction TB
            A[SocialApp] --> B[UserProfile]
            A --> C[FriendList]
            C --> D[FriendEntry]
        end
    end
```

위 예제를 보면:

1. `SocialApp`은 `UserProfile`과 `FriendList`에 의존성 값을 제공할 수 있습니다.
2. `FriendList`에 존재하는 의존성 객체의 인스턴스는 `FriendEntry`에서 사용할 수 있지만, `UserProfile`은 다른 트리에 있기 때문에 사용할 수 없습니다.

## 프로바이더 정의하기

<!--
Think of Angular's dependency injection system as a hash map or dictionary. Each provider configuration object defines a key-value pair:

- **Key (Provider identifier)**: The unique identifier you use to request a dependency
- **Value**: What Angular should return when that token is requested

When manually providing dependencies, you typically see this shorthand syntax:

```typescript
import {Component} from '@angular/core';
import {LocalService} from './local-service';

@Component({
  selector: 'app-example',
  providers: [LocalService], // Service without providedIn
})
export class Example {}
```

This is actually a shorthand for a more detailed provider configuration:

```ts
{
  // This is the shorthand version
  providers: [LocalService],

// This is the full version
  providers: [
    { provide: LocalService, useClass: LocalService }
  ]
}
```
-->

Angular의 의존성 주입 시스템은 맵이나 사전처럼 생각할 수 있습니다.
개별 프로바이더 설정은 다음과 같은 키-값 쌍으로 구성됩니다:

- **키 (프로바이더 구분자)**: 의존성 객체를 요청할 때 사용하는 고유 구분자
- **값**: 의존성 토큰을 요청했을 때 Angular가 반환할 값

의존성 프로바이더를 수동으로 등록할 때는 일반적으로 단축 문법을 사용합니다:

```typescript
import {Component} from '@angular/core';
import {LocalService} from './local-service';

@Component({
  selector: 'app-example',
  providers: [LocalService], // providedIn이 지정되지 않은 서비스
})
export class Example {}
```

단축 문법을 풀어서 쓰면 이렇습니다:

```ts
{
  // 단축 문법
  providers: [LocalService],

// 전체 문법
  providers: [
    { provide: LocalService, useClass: LocalService }
  ]
}
```

### 프로바이더 설정 객체

<!--
Every provider configuration object has two primary parts:

1. **Provider identifier**: The unique key that Angular uses to get the dependency (set via the `provide` property)
2. **Value**: The actual dependency that you want Angular to fetch, configured with different keys based on the desired type:
   - `useClass` - Provides a JavaScript class
   - `useValue` - Provides a static value
   - `useFactory` - Provides a factory function that returns the value
   - `useExisting` - Provides an alias to an existing provider
-->

프로바이더 설정 객체는 두 부분으로 구성됩니다:

1. **프로바이더 구분자**: Angular에 의존성 객체를 요청할 때 사용하는 유일한 키 (`provide` 프로퍼티에 설정하는 값)
2. **값**: 받아와서 사용할 의존성 객체이며, 요청하는 타입에 따라 각각 다음 프로퍼티로 연결합니다:
   - `useClass` - JavaScript 클래스인 경우
   - `useValue` - 정적인 값인 경우
   - `useFactory` - 팩토리 함수가 반환하는 값을 사용하는 경우
   - `useExisting` - 기존에 등록된 프로바이더에 별칭을 연결하는 경우

### 프로바이더 구분자

<!--
Provider identifiers allow Angular's dependency injection (DI) system to retrieve a dependency through a unique ID. You can generate provider identifiers in two ways:

1. [Class names](#class-names)
2. [Injection tokens](#injection-tokens)
-->

프로바이더 구분자는 의존성 객체를 가리키는 유일한 ID입니다.
두 가지 방식을 사용할 수 있습니다:

1. [클래스 이름](#클래스-이름)
2. [인젝션 토큰](#인젝션-토큰)

#### 클래스 이름

<!--
Class names use the imported class directly as the identifier:

```typescript
import {Component} from '@angular/core';
import {LocalService} from './local-service';

@Component({
  selector: 'app-example',
  providers: [{provide: LocalService, useClass: LocalService}],
})
export class Example {
  /* ... */
}
```

The class serves as both the identifier and the implementation, which is why Angular provides the shorthand `providers: [LocalService]`.
-->

클래스 이름을 구분자로 직접 사용할 수 있습니다:

```typescript
import {Component} from '@angular/core';
import {LocalService} from './local-service';

@Component({
  selector: 'app-example',
  providers: [{provide: LocalService, useClass: LocalService}],
})
export class Example {
  /* ... */
}
```

클래스 이름은 구분자이면서 구현체를 가리키는 용도로 사용됩니다.
단축 문법으로 사용하면 `providers: [LocalService]` 와 같습니다.

#### 인젝션 토큰

<!--
Angular provides a built-in [`InjectionToken`](api/core/InjectionToken) class that creates a unique object reference for injectable values or when you want to provide multiple implementations of the same interface.

```ts
{header: "/app/tokens.ts"}
import {InjectionToken} from '@angular/core';
import {DataService} from './data-service.interface';

export const DATA_SERVICE_TOKEN = new InjectionToken<DataService>('DataService');
```

NOTE: The string `'DataService'` is a description used purely for debugging purposes. Angular identifies the token by its object reference, not this string.

Use the token in your provider configuration:

```typescript
import {Component, inject} from '@angular/core';
import {LocalDataService} from './local-data-service';
import {DATA_SERVICE_TOKEN} from './tokens';

@Component({
  selector: 'app-example',
  providers: [{provide: DATA_SERVICE_TOKEN, useClass: LocalDataService}],
})
export class Example {
  private dataService = inject(DATA_SERVICE_TOKEN);
}
```
-->

Angular는 의존성으로 주입할 수 있는 객체를 생성하거나 같은 인터페이스 구현체를 여러 개 사용할 때 활용할 수 있는 [`InjectionToken`](api/core/InjectionToken) 클래스를 제공합니다.

```ts
{header: "/app/tokens.ts"}
import {InjectionToken} from '@angular/core';
import {DataService} from './data-service.interface';

export const DATA_SERVICE_TOKEN = new InjectionToken<DataService>('DataService');
```

참고: `'DataService'` 문자열은 설명을 위해 사용한 것입니다. 실제로는 문자열이 아니라 객체 참조를 직접 토큰으로 사용합니다.

토큰을 사용한 프로바이더 등록 방법은 이렇습니다:

```typescript
import {Component, inject} from '@angular/core';
import {LocalDataService} from './local-data-service';
import {DATA_SERVICE_TOKEN} from './tokens';

@Component({
  selector: 'app-example',
  providers: [{provide: DATA_SERVICE_TOKEN, useClass: LocalDataService}],
})
export class Example {
  private dataService = inject(DATA_SERVICE_TOKEN);
}
```

#### TypeScript 인터페이스를 구분자로 사용할 수 있나요?

<!--
TypeScript interfaces cannot be used for injection because they don't exist at runtime:

```ts
// ❌ This won't work!
interface DataService {
  getData(): string[];
}

// Interfaces disappear after TypeScript compilation
@Component({
  providers: [
    {provide: DataService, useClass: LocalDataService}, // Error!
  ],
})
export class Example {
  private dataService = inject(DataService); // Error!
}

// ✅ Use InjectionToken instead
export const DATA_SERVICE_TOKEN = new InjectionToken<DataService>('DataService');

@Component({
  providers: [{provide: DATA_SERVICE_TOKEN, useClass: LocalDataService}],
})
export class Example {
  private dataService = inject(DATA_SERVICE_TOKEN); // Works!
}
```

The InjectionToken provides a runtime value that Angular's DI system can use, while still maintaining type safety through TypeScript's generic type parameter.
-->

TypeScript 인터페이스는 실행시점에 존재하지 않기 때문에 인젝션 토큰으로 사용할 수 없습니다:

```ts
// ❌ 동작하지 않는 방식
interface DataService {
  getData(): string[];
}

// 인터페이스는 TypeScript 컴파일 이후에 존재하지 않습니다.
@Component({
  providers: [
    {provide: DataService, useClass: LocalDataService}, // 에러!
  ],
})
export class Example {
  private dataService = inject(DataService); // 에러!
}

// ✅ 대신 InjectionToken을 사용하세요
export const DATA_SERVICE_TOKEN = new InjectionToken<DataService>('DataService');

@Component({
  providers: [{provide: DATA_SERVICE_TOKEN, useClass: LocalDataService}],
})
export class Example {
  private dataService = inject(DATA_SERVICE_TOKEN); // 동작합니다!
}
```

InjectionToken은 실행 시점에 Angular 의존성 주입 시스템에서 사용할 수 있는 값을 가리키는 동시에, TypeScript의 제네릭 타입을 통해 타입 안정성을 유지합니다.

### 프로바이더 값 타입

#### useClass

<!--
`useClass` provides a JavaScript class as a dependency. This is the default when using the shorthand syntax:

```ts
// Shorthand
providers: [DataService];

// Full syntax
providers: [{provide: DataService, useClass: DataService}];

// Different implementation
providers: [{provide: DataService, useClass: MockDataService}];

// Conditional implementation
providers: [
  {
    provide: StorageService,
    useClass: environment.production ? CloudStorageService : LocalStorageService,
  },
];
```
-->

`useClass`를 사용하면 JavaScript 클래스를 의존성 객체로 등록할 수 있습니다.
단축 문법은 이렇습니다:

```ts
// 단축 문법
providers: [DataService];

// 전체 문법
providers: [{provide: DataService, useClass: DataService}];

// 구현체를 더미로 대체하기
providers: [{provide: DataService, useClass: MockDataService}];

// 조건에 따라 분기하기
providers: [
  {
    provide: StorageService,
    useClass: environment.production ? CloudStorageService : LocalStorageService,
  },
];
```

#### 실전 예제: 로그

<!--
You can substitute implementations to extend functionality:

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

// Base logger
@Injectable()
export class Logger {
  log(message: string) {
    console.log(message);
  }
}

// Enhanced logger with timestamp
@Injectable()
export class BetterLogger extends Logger {
  override log(message: string) {
    super.log(`[${new Date().toISOString()}] ${message}`);
  }
}

// Logger that includes user context
@Injectable()
export class EvenBetterLogger extends Logger {
  private userService = inject(UserService);

override log(message: string) {
    const name = this.userService.user.name;
    super.log(`Message to ${name}: ${message}`);
  }
}

// In your component
@Component({
  selector: 'app-example',
  providers: [
    UserService, // EvenBetterLogger needs this
    {provide: Logger, useClass: EvenBetterLogger},
  ],
})
export class Example {
  private logger = inject(Logger); // Gets EvenBetterLogger instance
}
```
-->

의존성 주입 시스템을 활용하면 구현체를 바꿔서 기능을 확장할 수 있습니다:

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

// 기본 로그 함수
@Injectable()
export class Logger {
  log(message: string) {
    console.log(message);
  }
}

// 타임스탬프 추가하기
@Injectable()
export class BetterLogger extends Logger {
  override log(message: string) {
    super.log(`[${new Date().toISOString()}] ${message}`);
  }
}

// 사용자 컨텍스트 추가하기
@Injectable()
export class EvenBetterLogger extends Logger {
  private userService = inject(UserService);

override log(message: string) {
    const name = this.userService.user.name;
    super.log(`Message to ${name}: ${message}`);
  }
}

// 컴포넌트에서 사용하기
@Component({
  selector: 'app-example',
  providers: [
    UserService, // EvenBetterLogger가 필요합니다.
    {provide: Logger, useClass: EvenBetterLogger},
  ],
})
export class Example {
  private logger = inject(Logger); // EvenBetterLogger 인스턴스를 받아옵니다.
}
```

#### useValue

<!--
`useValue` provides any JavaScript data type as a static value:

```ts
providers: [
  {provide: API_URL_TOKEN, useValue: 'https://api.example.com'},
  {provide: MAX_RETRIES_TOKEN, useValue: 3},
  {provide: FEATURE_FLAGS_TOKEN, useValue: {darkMode: true, beta: false}},
];
```

IMPORTANT: TypeScript types and interfaces cannot serve as dependency values. They exist only at compile-time.
-->

`useValue`를 사용하면 JavaScript 데이터 타입을 정적인 값으로 등록할 수 있습니다:

중요: TypeScript 타입이나 인터페이스는 의존성 토큰으로 사용할 수 없습니다. 이 타입들은 컴파일 시점까지만 존재합니다.

#### 실전 예제: 애플리케이션 환경설정

<!--
A common use case for `useValue` is providing application configuration:

```ts
// Define configuration interface
export interface AppConfig {
  apiUrl: string;
  appTitle: string;
  features: {
    darkMode: boolean;
    analytics: boolean;
  };
}

// Create injection token
export const APP_CONFIG = new InjectionToken<AppConfig>('app.config');

// Define configuration
const appConfig: AppConfig = {
  apiUrl: 'https://api.example.com',
  appTitle: 'My Application',
  features: {
    darkMode: true,
    analytics: false,
  },
};

// Provide in bootstrap
bootstrapApplication(AppComponent, {
  providers: [{provide: APP_CONFIG, useValue: appConfig}],
});

// Use in component
@Component({
  selector: 'app-header',
  template: `<h1>{{ title }}</h1>`,
})
export class Header {
  private config = inject(APP_CONFIG);
  title = this.config.appTitle;
}
```
-->

애플리케이션 환경설정을 할 때 보통 `useValue`를 사용합니다:

```ts
// 환경설정 인터페이스를 정의합니다.
export interface AppConfig {
  apiUrl: string;
  appTitle: string;
  features: {
    darkMode: boolean;
    analytics: boolean;
  };
}

// 인젝션 토큰을 생성합니다.
export const APP_CONFIG = new InjectionToken<AppConfig>('app.config');

// 환경설정 값을 지정합니다.
const appConfig: AppConfig = {
  apiUrl: 'https://api.example.com',
  appTitle: 'My Application',
  features: {
    darkMode: true,
    analytics: false,
  },
};

// 앱을 시작할 때 프로바이더로 등록합니다.
bootstrapApplication(AppComponent, {
  providers: [{provide: APP_CONFIG, useValue: appConfig}],
});

// 컴포넌트에서 사용하기
@Component({
  selector: 'app-header',
  template: `<h1>{{ title }}</h1>`,
})
export class Header {
  private config = inject(APP_CONFIG);
  title = this.config.appTitle;
}
```

#### useFactory

<!--
`useFactory` provides a function that generates a new value for injection:

```ts
export const loggerFactory = (config: AppConfig) => {
  return new LoggerService(config.logLevel, config.endpoint);
};

providers: [
  {
    provide: LoggerService,
    useFactory: loggerFactory,
    deps: [APP_CONFIG], // Dependencies for the factory function
  },
];
```

You can mark factory dependencies as optional:

```ts
import {Optional} from '@angular/core';

providers: [
  {
    provide: MyService,
    useFactory: (required: RequiredService, optional?: OptionalService) => {
      return new MyService(required, optional || new DefaultService());
    },
    deps: [RequiredService, [new Optional(), OptionalService]],
  },
];
```
-->

`useFactory`를 활용하면 값을 반환하는 팩토리 함수를 프로바이더로 등록할 수 있습니다:

```ts
export const loggerFactory = (config: AppConfig) => {
  return new LoggerService(config.logLevel, config.endpoint);
};

providers: [
  {
    provide: LoggerService,
    useFactory: loggerFactory,
    deps: [APP_CONFIG], // 팩토리 함수에 필요한 의존성
  },
];
```

팩토리 함수의 의존성을 생략 가능한 항목으로 지정할 수 있습니다:

```ts
import {Optional} from '@angular/core';

#### 실전 예제: 환경설정에 따른 API 클라이언트

<!--
Here's a complete example showing how to use a factory to create a service with runtime configuration:

```ts
// Service that needs runtime configuration
class ApiClient {
  constructor(
    private http: HttpClient,
    private baseUrl: string,
    private rateLimitMs: number,
  ) {}

async fetchData(endpoint: string) {
    // Apply rate limiting based on user tier
    await this.applyRateLimit();
    return this.http.get(`${this.baseUrl}/${endpoint}`);
  }

private async applyRateLimit() {
    // Simplified example - real implementation would track request timing
    return new Promise((resolve) => setTimeout(resolve, this.rateLimitMs));
  }
}

// Factory function that configures based on user tier
import {inject, Component} from '@angular/core';
import {HttpClient} from '@angular/common/http';
const apiClientFactory = () => {
  const http = inject(HttpClient);
  const userService = inject(UserService);

// Assuming userService provides these values
  const baseUrl = userService.getApiBaseUrl();
  const rateLimitMs = userService.getRateLimit();

return new ApiClient(http, baseUrl, rateLimitMs);
};

// Provider configuration
export const apiClientProvider = {
  provide: ApiClient,
  useFactory: apiClientFactory,
};

// Usage in component
@Component({
  selector: 'app-dashboard',
  providers: [apiClientProvider],
})
export class Dashboard {
  private apiClient = inject(ApiClient);
}
```
-->

실행시점의 환경설정에 따라 서비스를 생성하는 팩토리를 프로바이더로 등록한다면 다음과 같이 구현할 수 있습니다:

```ts
// 실행 시점의 환경설정이 필요한 서비스
class ApiClient {
  constructor(
    private http: HttpClient,
    private baseUrl: string,
    private rateLimitMs: number,
  ) {}

async fetchData(endpoint: string) {
    // 사용자 등급에 따라 속도 제한을 적용합니다.
    await this.applyRateLimit();
    return this.http.get(`${this.baseUrl}/${endpoint}`);
  }

private async applyRateLimit() {
    // 간단한 예제 - 실제 구현은 요청 시점을 조절해야 합니다.
    return new Promise((resolve) => setTimeout(resolve, this.rateLimitMs));
  }
}

// 사용자 등급에 따라 구성되는 팩토리 함수
import {inject, Component} from '@angular/core';
import {HttpClient} from '@angular/common/http';
const apiClientFactory = () => {
  const http = inject(HttpClient);
  const userService = inject(UserService);

// 필요한 값은 userService에서 받아온다고 가정합니다.
  const baseUrl = userService.getApiBaseUrl();
  const rateLimitMs = userService.getRateLimit();

return new ApiClient(http, baseUrl, rateLimitMs);
};

// 프로바이더 등록
export const apiClientProvider = {
  provide: ApiClient,
  useFactory: apiClientFactory,
};

// 컴포넌트에서 사용하기
@Component({
  selector: 'app-dashboard',
  providers: [apiClientProvider],
})
export class Dashboard {
  private apiClient = inject(ApiClient);
}
```

#### useExisting

<!--
`useExisting` creates an alias for a provider that was already defined. Both tokens return the same instance:

```ts
providers: [
  NewLogger, // The actual service
  {provide: OldLogger, useExisting: NewLogger}, // The alias
];
```

IMPORTANT: Don't confuse `useExisting` with `useClass`. `useClass` creates separate instances, while `useExisting` ensures you get the same singleton instance.
-->

`useExisting`을 활용하면 이미 존재하는 프로바이더에 별칭을 추가할 수 있습니다.
기존 토큰과 별칭으로 만드는 토큰은 같은 인스턴스를 반환합니다:

```ts
providers: [
  NewLogger, // 실제 서비스
  {provide: OldLogger, useExisting: NewLogger}, // 별칭 추가
];
```

중요: `useExisting`과 `useClass`를 혼동하지 마세요. `useClass`는 별도 인스턴스를 만들고, `useExisting`은 기존 프로바이더와 동일한 인스턴스를 반환합니다.

### 프로바이더 여러 개 등록하기

<!--
Use the `multi: true` flag when multiple providers contribute values to the same token:

```ts
export const INTERCEPTOR_TOKEN = new InjectionToken<Interceptor[]>('interceptors');

providers: [
  {provide: INTERCEPTOR_TOKEN, useClass: AuthInterceptor, multi: true},
  {provide: INTERCEPTOR_TOKEN, useClass: LoggingInterceptor, multi: true},
  {provide: INTERCEPTOR_TOKEN, useClass: RetryInterceptor, multi: true},
];
```

When you inject `INTERCEPTOR_TOKEN`, you'll receive an array containing instances of all three interceptors.
-->

`multi: true` 플래그를 사용하면 한 토큰에 프로바이더 여러 개를 인젝션 토큰 하나에 등록할 수 있습니다:

```ts
export const INTERCEPTOR_TOKEN = new InjectionToken<Interceptor[]>('interceptors');

이후에 `INTERCEPTOR_TOKEN`을 의존성으로 주입받으면 인터셉터 3개의 인스턴스가 들어있는 배열을 반환받습니다.

## 프로바이더는 어디에 등록하나요?

<!--
Angular offers several levels where you can register providers, each with different implications for scope, lifecycle, and performance:

- [**Application bootstrap**](#application-bootstrap) - Global singletons available everywhere
- [**On an element (component or directive)**](#component-or-directive-providers) - Isolated instances for specific component trees
- [**Route**](#route-providers) - Feature-specific services for lazy-loaded modules
-->

프로바이더를 등록하는 계층은 접근 범위, 라이프사이클, 성능에 따라 선택할 수 있습니다:

- [**애플리케이션을 부트스트랩할 때**](#애플리케이션을-부트스트랩할-때) - 전역 범위에 싱글턴 인스턴스로 등록됩니다.
- [**컴포넌트나 디렉티브 계층**](#컴포넌트나-디렉티브-프로바이더-배열) - 컴포넌트 트리별로 인스턴스를 구분할 때
- [**라우팅 규칙(Route)**](#라우팅-규칙-프로바이더) - 지연 로딩되는 모듈인 경우

### 애플리케이션을 부트스트랩할 때

<!--
Use application-level providers in `bootstrapApplication` when:

- **The service is used across multiple feature areas** - Services like HTTP clients, logging, or authentication that many parts of your app need
- **You want a true singleton** - One instance shared by the entire application
- **The service has no component-specific configuration** - General-purpose utilities that work the same everywhere
- **You're providing global configuration** - API endpoints, feature flags, or environment settings

```ts
{header: "main.ts"}
bootstrapApplication(App, {
  providers: [
    {provide: API_BASE_URL, useValue: 'https://api.example.com'},
    {provide: INTERCEPTOR_TOKEN, useClass: AuthInterceptor, multi: true},
    LoggingService, // Used throughout the app
    {provide: ErrorHandler, useClass: GlobalErrorHandler},
  ],
});
```

**Benefits:**

- Single instance reduces memory usage
- Available everywhere without additional setup
- Easier to manage global state

**Drawbacks:**

- Always included in your JavaScript bundle, even if the value is never injected
- Cannot be easily customized per feature
- Harder to test individual components in isolation
-->

이런 경우는 `bootstrapApplication` 함수를 사용할 때 애플리케이션 계층 프로바이더에 등록합니다:

- **서비스가 애플리케이션 여러 부분에 사용될 때** - HTTP 클라이언트나 로그 서비스, 인증과 같이 앱 여러 부분에 필요한 서비스
- **인스턴스를 하나만 유지할 때** - 앱 전역 범위에서 인스턴스 하나를 공유할 때
- **서비스가 컴포넌트와 관계없이 동작할 때** - 유틸리티 역할을 하는 서비스
- **전역 환경설정 값을 등록하는 경우** - API 엔드포인트, 기능 on/off 플래그, 환경설정 값을 등록할 때

```ts
{header: "main.ts"}
bootstrapApplication(App, {
  providers: [
    {provide: API_BASE_URL, useValue: 'https://api.example.com'},
    {provide: INTERCEPTOR_TOKEN, useClass: AuthInterceptor, multi: true},
    LoggingService, // 앱 전역 범위에 사용합니다.
    {provide: ErrorHandler, useClass: GlobalErrorHandler},
  ],
});
```

**장점:**

- 싱글턴 인스턴스를 활용하면 메모리 사용량을 줄일 수 있습니다.
- 별도 설정 없이도 앱 전역에서 사용할 수 있습니다.
- 전역 상태를 관리하기 편합니다.

**단점:**

- 실제 의존성 객체로 사용하지 않더라도 JavaScript 빌드 결과물에 항상 포함됩니다.
- 앱 부분별로 커스터마이징하기 어렵습니다.
- 컴포넌트를 테스트하기에 비교적 어렵습니다.

#### `providedIn: 'root'`를 사용하지 않고 부트스트랩 단계에 등록하는 이유는 무엇인가요?

<!--
You might want a provider during bootstrap when:

- The provider has side-effects (e.g., installing the client-side router)
- The provider requires configuration (e.g., routes)
- You're using Angular's `provideSomething` pattern (e.g., `provideRouter`, `provideHttpClient`)
-->

프로바이더를 부트스트랩 단계에 등록하는 것은 이런 경우에 유용합니다:

- 부수효과를 유발하는 프로바이더 (예: 클라이언트 측 라우터를 설치하기)
- 환경설정이 필요한 프로바이더 (예: 라우팅 규칙)
- Angular가 제공하는 `provideSomething` 패턴을 사용할 때 (예: `provideRouter`, `provideHttpClient`)

### 컴포넌트나 디렉티브 프로바이더 배열

<!--
Use component or directive providers when:

- **The service has component-specific state** - Form validators, component-specific caches, or UI state managers
- **You need isolated instances** - Each component needs its own copy of the service
- **The service is only used by one component tree** - Specialized services that don't need global access
- **You're creating reusable components** - Components that should work independently with their own services

```typescript
// Specialized form component with its own validation service
@Component({
  selector: 'app-advanced-form',
  providers: [
    FormValidationService, // Each form gets its own validator
    {provide: FORM_CONFIG, useValue: {strictMode: true}},
  ],
})
export class AdvancedForm {}

// Modal component with isolated state management
@Component({
  selector: 'app-modal',
  providers: [
    ModalStateService, // Each modal manages its own state
  ],
})
export class Modal {}
```

**Benefits:**

- Better encapsulation and isolation
- Easier to test components individually
- Multiple instances can coexist with different configurations

**Drawbacks:**

- New instance created for each component (higher memory usage)
- No shared state between components
- Must be provided wherever needed
- Always included in the same JavaScript bundle as the component or directive, even if the value is never injected

NOTE: If multiple directives on the same element provide the same token, one will win, but which one is undefined.
-->

컴포넌트나 디렉티브 계층 프로바이더는 이런 경우에 사용합니다:

- **서비스가 컴포넌트별 상태와 관련될 때** - 폼 유효성 검사 함수, 컴포넌트별 캐시, UI 상태 매니저 등
- **인스턴스를 구분해야 할 때** - 개별 컴포넌트마다 서비스 인스턴스를 각각 가져야 할 때
- **컴포넌트 트리 한 곳에서만 사용되는 서비스** - 서비스를 전역 범위에서는 사용할 필요가 없을 때
- **재사용하는 컴포넌트를 사용할 때** - 서비스와 독립적으로 작동해야 하는 컴포넌트

```typescript
// 유효성 검사 서비스를 갖는 폼 컴포넌트
@Component({
  selector: 'app-advanced-form',
  providers: [
    FormValidationService, // 개별 폼은 각각 유효성 검사 함수를 갖습니다.
    {provide: FORM_CONFIG, useValue: {strictMode: true}},
  ],
})
export class AdvancedForm {}

// 상태를 독립적으로 관리하는 모달 컴포넌트
@Component({
  selector: 'app-modal',
  providers: [
    ModalStateService, // 개별 모달의 상태는 각각 관리합니다.
  ],
})
export class Modal {}
```

**장점:**

- 캡슐화와 코드 분리에 유리합니다.
- 컴포넌트만 테스트하기 비교적 쉽습니다.
- 여러 인스턴스가 서로 다른 환경설정으로 존재할 수 있습니다.

**단점:**

- 개별 컴포넌트마다 인스턴스가 생성되기 때문에 메모리 사용량이 많습니다.
- 컴포넌트끼리 상태를 공유할 수 없습니다.
- 사용하는 곳마다 프로바이더를 등록해야 합니다.
- 의존성 객체를 실제로 사용하지 않더라도, 컴포넌트/디렉티브 빌드 결과물에 항상 포함됩니다.

참고: 한 엘리먼트에 같은 토큰으로 디렉티브 여러 개가 존재하면, 하나만 유효하지만, 어떤 것이 유효할지는 알 수 없습니다.

### 라우팅 규칙 프로바이더

<!--
Use route-level providers for:

- **Feature-specific services** - Services only needed for particular routes or feature modules
- **Lazy-loaded module dependencies** - Services that should only load with specific features
- **Route-specific configuration** - Settings that vary by application area

```ts
{header: "routes.ts"}
export const routes: Routes = [
  {
    path: 'admin',
    providers: [
      AdminService, // Only loaded with admin routes
      {provide: FEATURE_FLAGS, useValue: {adminMode: true}},
    ],
    loadChildren: () => import('./admin/admin.routes'),
  },
  {
    path: 'shop',
    providers: [
      ShoppingCartService, // Isolated shopping state
      PaymentService,
    ],
    loadChildren: () => import('./shop/shop.routes'),
  },
];
```

Services provided at the route level are available to all components and directives within that route, as well as to its guards and resolvers.

Since these services are instantiated independently of the route’s components, they do not have direct access to route-specific information.
-->

라우팅 규칙 계층에 프로바이더를 등록하는 경우가 있습니다:

- **기능별 서비스** - 특정 라우팅 규칙이나 특정 모듈에서만 동작하는 서비스인 경우
- **지연 로딩되는 모듈 의존성** - 특정 기능에만 필요한 서비스인 경우
- **라우팅 규칙별 환경설정** - 애플리케이션 부분마다 환경설정이 달라지는 경우

```ts
{header: "routes.ts"}
export const routes: Routes = [
  {
    path: 'admin',
    providers: [
      AdminService, // admin 라우팅 규칙에 접근할 때만 로드됩니다.
      {provide: FEATURE_FLAGS, useValue: {adminMode: true}},
    ],
    loadChildren: () => import('./admin/admin.routes'),
  },
  {
    path: 'shop',
    providers: [
      ShoppingCartService, // 독립적인 상태 관리를 생성합니다.
      PaymentService,
    ],
    loadChildren: () => import('./shop/shop.routes'),
  },
];
```

라우팅 규칙에 서비스 프로바이더를 등록하면 이 라우팅 규칙의 안쪽에 있는 컴포넌트나 디렉티브는 이 서비스에 접근할 수 있습니다.
물론 가드와 리졸버에서도 사용할 수 있습니다.

다만, 라우팅 규칙과 연결되는 컴포넌트와는 별개로 생성되기 때문에 특정 라우팅 규칙에만 해당되는 정보에 접근할 수는 없습니다.

## 라이브러리 개발자 패턴

Angular 라이브러리를 개발한다면, 깔끔한 API를 유지하면서도 사용자에게 맞는 환경설정을 제공해야 하는 경우가 있습니다.
Angular 자체 라이브러리가 활용하는 강력한 패턴을 활용해 보세요.

### `provide` 패턴

<!--
Instead of requiring users to manually configure complex providers, library authors can export functions that return provider configurations:

```ts
{header: "/libs/analytics/src/providers.ts"}
import {InjectionToken, Provider, inject} from '@angular/core';

// Configuration interface
export interface AnalyticsConfig {
  trackingId: string;
  enableDebugMode?: boolean;
  anonymizeIp?: boolean;
}

// Internal token for configuration
const ANALYTICS_CONFIG = new InjectionToken<AnalyticsConfig>('analytics.config');

// Main service that uses the configuration
export class AnalyticsService {
  private config = inject(ANALYTICS_CONFIG);

track(event: string, properties?: any) {
    // Implementation using config
  }
}

// Provider function for consumers
export function provideAnalytics(config: AnalyticsConfig): Provider[] {
  return [{provide: ANALYTICS_CONFIG, useValue: config}, AnalyticsService];
}

```

```ts
{header: "main.ts"}
// Usage in consumer app
bootstrapApplication(App, {
  providers: [
    provideAnalytics({
      trackingId: 'GA-12345',
      enableDebugMode: !environment.production,
    }),
  ],
});
```
-->

라이브러리 사용자가 복잡하게 프로바이더 설정을 하게 하는 것보다, 프로바이더 환경설정을 반환하는 함수를 사용하는 것이 더 좋습니다:

```ts
{header: "/libs/analytics/src/providers.ts"}
import {InjectionToken, Provider, inject} from '@angular/core';

// 환경설정 인터페이스
export interface AnalyticsConfig {
  trackingId: string;
  enableDebugMode?: boolean;
  anonymizeIp?: boolean;
}

// 환경설정을 위한 내부 토큰
const ANALYTICS_CONFIG = new InjectionToken<AnalyticsConfig>('analytics.config');

// 환경설정을 활용하는 메인 서비스
export class AnalyticsService {
  private config = inject(ANALYTICS_CONFIG);

track(event: string, properties?: any) {
    // 환경설정에 따라 실제로 구현되는 코드
  }
}

// 라이브러리 사용자를 위한 프로바이더 함수
export function provideAnalytics(config: AnalyticsConfig): Provider[] {
  return [{provide: ANALYTICS_CONFIG, useValue: config}, AnalyticsService];
}
```

```ts
{header: "main.ts"}
// 라이브러리 사용자가 앱에서 사용할 때
bootstrapApplication(App, {
  providers: [
    provideAnalytics({
      trackingId: 'GA-12345',
      enableDebugMode: !environment.production,
    }),
  ],
});
```

### 옵션을 사용하는 고급 프로바이더 패턴

<!--
For more complex scenarios, you can combine multiple configuration approaches:

```ts
{header: "/libs/http-client/src/provider.ts"}
import {Provider, InjectionToken, inject} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';

// Feature flags for optional functionality
export enum HttpFeatures {
  Interceptors = 'interceptors',
  Caching = 'caching',
  Retry = 'retry',
}

// Configuration interfaces
export interface HttpConfig {
  baseUrl?: string;
  timeout?: number;
  headers?: Record<string, string>;
}

export interface RetryConfig {
  maxAttempts: number;
  delayMs: number;
}

// Internal tokens
const HTTP_CONFIG = new InjectionToken<HttpConfig>('http.config');
const RETRY_CONFIG = new InjectionToken<RetryConfig>('retry.config');
const HTTP_FEATURES = new InjectionToken<Set<HttpFeatures>>('http.features');

// Core service
class HttpClientService {
  private config = inject(HTTP_CONFIG, {optional: true});
  private features = inject(HTTP_FEATURES);

get(url: string) {
    // Use config and check features
  }
}

// Feature services
class RetryInterceptor {
  private config = inject(RETRY_CONFIG);
  // Retry logic
}

class CacheInterceptor {
  // Caching logic
}

// Main provider function
export function provideHttpClient(config?: HttpConfig, ...features: HttpFeature[]): Provider[] {
  const providers: Provider[] = [
    {provide: HTTP_CONFIG, useValue: config || {}},
    {provide: HTTP_FEATURES, useValue: new Set(features.map((f) => f.kind))},
    HttpClientService,
  ];

// Add feature-specific providers
  features.forEach((feature) => {
    providers.push(...feature.providers);
  });

return providers;
}

// Feature configuration functions
export interface HttpFeature {
  kind: HttpFeatures;
  providers: Provider[];
}

export function withInterceptors(...interceptors: any[]): HttpFeature {
  return {
    kind: HttpFeatures.Interceptors,
    providers: interceptors.map((interceptor) => ({
      provide: INTERCEPTOR_TOKEN,
      useClass: interceptor,
      multi: true,
    })),
  };
}

export function withCaching(): HttpFeature {
  return {
    kind: HttpFeatures.Caching,
    providers: [CacheInterceptor],
  };
}

export function withRetry(config: RetryConfig): HttpFeature {
  return {
    kind: HttpFeatures.Retry,
    providers: [{provide: RETRY_CONFIG, useValue: config}, RetryInterceptor],
  };
}

// Consumer usage with multiple features
bootstrapApplication(App, {
  providers: [
    provideHttpClient(
      {baseUrl: 'https://api.example.com'},
      withInterceptors(AuthInterceptor, LoggingInterceptor),
      withCaching(),
      withRetry({maxAttempts: 3, delayMs: 1000}),
    ),
  ],
});
```
-->

더 복잡한 경우라면 여러 가지 구현 방식을 섞어서 사용할 수 있습니다:

```ts
{header: "/libs/http-client/src/provider.ts"}
import {Provider, InjectionToken, inject} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';

// 기능 활성화 플래그
export enum HttpFeatures {
  Interceptors = 'interceptors',
  Caching = 'caching',
  Retry = 'retry',
}

// 환경설정 인터페이스
export interface HttpConfig {
  baseUrl?: string;
  timeout?: number;
  headers?: Record<string, string>;
}

export interface RetryConfig {
  maxAttempts: number;
  delayMs: number;
}

// 내부용 토큰
const HTTP_CONFIG = new InjectionToken<HttpConfig>('http.config');
const RETRY_CONFIG = new InjectionToken<RetryConfig>('retry.config');
const HTTP_FEATURES = new InjectionToken<Set<HttpFeatures>>('http.features');

// 핵심 서비스
class HttpClientService {
  private config = inject(HTTP_CONFIG, {optional: true});
  private features = inject(HTTP_FEATURES);

get(url: string) {
    // 환경설정 값과 기능 활성화 플래그를 활용하는 로직
  }
}

// 서비스 기능
class RetryInterceptor {
  private config = inject(RETRY_CONFIG);
  // 재시도 로직
}

class CacheInterceptor {
  // 캐싱 로직
}

// 메인 프로바이더 함수
export function provideHttpClient(config?: HttpConfig, ...features: HttpFeature[]): Provider[] {
  const providers: Provider[] = [
    {provide: HTTP_CONFIG, useValue: config || {}},
    {provide: HTTP_FEATURES, useValue: new Set(features.map((f) => f.kind))},
    HttpClientService,
  ];

// 기능별 프로바이더를 추가합니다.
  features.forEach((feature) => {
    providers.push(...feature.providers);
  });

return providers;
}

// 기능 활성화 함수
export interface HttpFeature {
  kind: HttpFeatures;
  providers: Provider[];
}

export function withCaching(): HttpFeature {
  return {
    kind: HttpFeatures.Caching,
    providers: [CacheInterceptor],
  };
}

export function withRetry(config: RetryConfig): HttpFeature {
  return {
    kind: HttpFeatures.Retry,
    providers: [{provide: RETRY_CONFIG, useValue: config}, RetryInterceptor],
  };
}

// 라이브러리 사용자가 필요한 기능을 구성해서 활용하는 코드
bootstrapApplication(App, {
  providers: [
    provideHttpClient(
      {baseUrl: 'https://api.example.com'},
      withInterceptors(AuthInterceptor, LoggingInterceptor),
      withCaching(),
      withRetry({maxAttempts: 3, delayMs: 1000}),
    ),
  ],
});
```

### 왜 프로바이더를 직접 설정하지 않고 프로바이더 생성 함수를 사용하나요?

<!--
Provider functions offer several advantages for library authors:

1. **Encapsulation** - Internal tokens and implementation details remain private
2. **Type safety** - TypeScript ensures correct configuration at compile time
3. **Flexibility** - Easily compose features with `with*` pattern
4. **Future-proofing** - Internal implementation can change without breaking consumers
5. **Consistency** - Aligns with Angular's own patterns (`provideRouter`, `provideHttpClient`, etc.)

This pattern is extensively used in Angular's own libraries and is considered a best practice for library authors who need to provide configurable services.
-->

라이브러리 개발자인 경우 프로바이더 함수를 사용하면 이런 점이 좋습니다:

1. **캡슐화** - 내부용 토큰과 구현 세부 정보를 공개하지 않아도 됩니다.
2. **타입 안전성** - 컴파일 시점에 TypeScript를 활용해서 정확한 타입을 보장합니다.
3. **유연성** - `with*` 패턴으로 원하는 기능을 간단하게 조합할 수 있습니다.
4. **미래 대비** - 내부 로직을 변경하더라도 라이브러리 사용자는 코드를 변경하지 않아도 됩니다.
5. **일관성** - Angular가 제공하는 `provideRouter`, `provideHttpClient` 등과 같은 방식입니다.

이 패턴은 Angular가 제공하는 라이브러리에서도 적극적으로 사용되며, 설정값을 변경하는 방식으로 프로바이더를 등록하는 라이브러리 개발자를 위한 모범 사례입니다.

# 서비스 지연 로딩

<!--
IMPORTANT: For lazy loading to work, the service you load must be auto-provided. Decorate it with either `@Injectable({providedIn: 'root'})` or [`@Service()`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator). Without auto-provisioning, Angular has no way to construct the service after it loads.

Angular's `injectAsync` function lets you load a service on demand, only when it's actually needed. This is useful when a service depends on a large library or rarely used feature, and you don't want to pay for it on the initial page load.

When you use `injectAsync`, the service's code is split out by your bundler into a separate JavaScript chunk and downloaded the first time you ask for the instance. Once loaded, Angular resolves the service through the regular DI system, so it can still depend on other injectables and behaves like any other singleton.
-->

중요: 서비스가 지연 로딩되려면 이 서비스의 프로바이더가 앱 최상위 계층에 등록되어야 합니다.
그래서 `@Injectable({providedIn: 'root'})`나 [`@Service()`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator) 데코레이터를 사용해야 합니다.

`injectAsync` 함수를 사용하면 서비스가 실제로 사용되어 꼭 필요한 시점에 서비스를 로드할 수 있습니다.
이 방식은 용량이 큰 라이브러리를 활용하거나, 거의 사용하지 않는 기능을 사용할 때, 최초 화면 로딩 속도를 향상시키려고 할 때 유용합니다.

`injectAsync`를 사용하면 서비스의 코드가 최초 로딩에 필요한 빌드 결과물과 분리되어 별도 JavaScript 청크로 구성되며, 이 서비스 인스턴스를 실제로 요청한 경우에 다운로드 받아 실행합니다.
그리고 한 번 로드된 후에는 일반적인 의존성 주입 시스템 항목과 마찬가지로, 싱글턴 인스턴스로 필요한 곳에 주입하여 사용할 수 있습니다.

## 지연 의존성 주입

<!--
Imagine a `ReportExporter` that depends on a heavy spreadsheet library. Most users open the report; only a few click **Export**. Load the exporter on demand:

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

The first call to `this.exporter()` triggers the dynamic import and resolves the service from DI. Subsequent calls reuse the same promise, so the chunk is only fetched once.

If the lazy-loaded service is the [default export](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/export#using_the_default_export), pass the dynamic import directly, Angular unwraps the `default` for you:

```ts
{header: "report-exporter.ts"}
@Service()
export default class ReportExporter {
  /* … */
}
```

```ts
{header: "report.ts"}
private exporter = injectAsync(() => import('./report-exporter'));
```
-->

`ReportExporter`가 무거운 스프레드시트 라이브러리를 활용한다고 합시다.
사용자들은 대부분 보고서를 열어보겠지만 **내보내기** 를 클릭하는 사용자는 소수입니다.
그렇다면 다음과 같이 필요할 때만 서비스를 로드하면 됩니다:

```typescript
import {Component, injectAsync} from '@angular/core';

async export() {
    const exporter = await this.exporter();
    exporter.export();
  }
}
```

첫번째 실행하는 `this.exporter()` 시점에 동적 로드가 시작되며 서비스 클래스의 인스턴스를 생성해서 의존성 주입 시스템에 연결합니다.
그다음 실행하는 `this.exporter()`는 지연 로딩이 완료되었기 때문에 같은 객체를 다시 사용합니다.

지연 로딩되는 서비스가 [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'));
```

## 의존성을 사전에 로딩하기

<!--
By default, the lazy chunk is only fetched when you invoke the returned function. You can start the download earlier by passing a `prefetch` trigger in the options. A trigger is any function that returns a `Promise`, when it resolves, Angular kicks off the loader.

Angular ships with `onIdle`, a built-in trigger that waits until the browser becomes idle:

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

@Component({/* … */})
export class Report {
  private exporter = injectAsync(() => import('./report-exporter').then((m) => m.ReportExporter), {
    prefetch: onIdle,
  });
}
```

You can also configure `onIdle` with a maximum wait time so the prefetch always happens within a known window, even on busy pages:

```ts
injectAsync(loader, {prefetch: () => onIdle({timeout: 1_000})});
```

NOTE: Prefetching is opportunistic. If the user invokes the feature before the prefetch fires, Angular still loads the dependency immediately and resolves your `await` as soon as it's ready.
-->

기본적으로 지연 로딩 청크는 `injectAsync`가 반환한 함수를 호출할 때만 가져옵니다. 옵션에 `prefetch` 트리거를 전달하면 다운로드를 더 일찍 시작할 수 있습니다. 트리거는 `Promise`를 반환하는 함수이며, 이 Promise가 이행(resolve)되면 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`을 사용하면서 최대 대기시간을 지정하면, 브라우저가 대기 상태가 아니더라도 해당 파일을 로드합니다:

```ts
injectAsync(loader, {prefetch: () => onIdle({timeout: 1_000})});
```

참고: 사전 로딩은 상황에 따라 자동으로 동작합니다.
사용자가 사전 로딩되지 않은 함수를 실행하면, Angular는 해당 의존성 객체를 즉시 로드한 후에 `await`로 처리합니다.

## 커스텀 사전 로딩 트리거 등록하기

<!--
A `PrefetchTrigger` is just a function that returns a promise, the loader runs as soon as the promise resolves. Use this to align prefetching with your own signals, such as a hover or a scheduler tick:

```ts
import {PrefetchTrigger} from '@angular/core';

export function onHover(target: HTMLElement): PrefetchTrigger {
  return () =>
    new Promise<void>((resolve) => {
      target.addEventListener('pointerenter', () => resolve(), {once: true});
    });
}
```
-->

`PrefetchTrigger`는 `Promise`를 반환하는 함수인데, 이 Promise가 종료되면 로더가 즉시 실행됩니다.
마우스 포인터를 올리거나 타이머가 동작하는 것과 같이 개발자가 원하는 시점에 서비스를 사전 로딩하는 경우라면 다음과 같이 구성하면 됩니다:

```ts
import {PrefetchTrigger} from '@angular/core';

# 의존성 주입 컨텍스트

<!--
The dependency injection (DI) system relies on a runtime context where the current injector is available.

This means that injectors only work when you execute code within this context.

You have an injection context available in the following situations:

- During construction (via the `constructor`) of a class instantiated by the DI system, such as an `@Injectable` or `@Component`.
- In field initializers of such classes.
- In the factory function specified for `useFactory` of a `Provider` or an `@Injectable`.
- In the `factory` function specified for an `InjectionToken`.
- Within a stack frame that runs in an injection context.

Knowing when you are in an injection context allows you to use the [`inject`](api/core/inject) function to retrieve dependencies.

NOTE: For basic examples of using `inject()` in class constructors and field initializers, see the [overview guide](/guide/di#where-can-inject-be-used).
-->

의존성 주입 시스템은 현재 인젝터(injector)가 접근 가능한 범위의 실행 컨텍스트를 구성합니다.

이 말은, 이 컨텍스트 안에서만 인젝터를 사용할 수 있다는 것을 의미합니다.

의존성 주입 컨텍스트는 이런 상황에 사용할 수 있습니다:

- `@Injectable`이나 `@Component` 등 DI 시스템이 인스턴스를 생성하는 클래스의 `constructor` 안에서
- 그러한 클래스의 필드를 초기화하는 코드 안에서
- `Provider`나 `@Injectable`을 `useFactory`로 등록하는 경우 팩토리 함수 안에서
- `InjectionToken`에 연결하는 `factory` 함수 안에서
- 의존성 주입 컨텍스트가 실행되는 스택 프레임 안에서

현재 작업하는 컨텍스트가 의존성 주입이 가능한 컨텍스트라면, [`inject`](api/core/inject) 함수를 사용해서 의존성 객체의 인스턴스를 요청할 수 있습니다.

참고: 클래스 생성자나 필드를 초기화할 때 `inject()`를 사용하는 기본 방법을 알아보려면 [개요](/guide/di#where-can-inject-be-used) 문서를 참고하세요.

## 컨텍스트 안의 스택 프레임

<!--
Some APIs are designed to run within an injection context. This is the case, for example, with router guards. This allows you to use [`inject`](api/core/inject) within the guard function to access services.

Here is an example for `CanActivateFn`

```ts
{highlight: [3]}
const canActivateTeam: CanActivateFn = (
  route: ActivatedRouteSnapshot,
  state: RouterStateSnapshot,
) => {
  return inject(PermissionsService).canActivate(inject(UserToken), route.params.id);
};
```
-->

일부 API는 인젝션 컨텍스트 안에서 실행되도록 설계된 것들이 있습니다.
예를 들면 라우터 가드가 그렇습니다.
가드 함수 안에서는 [`inject`](api/core/inject) 함수를 사용해서 원하는 서비스에 접근할 수 있습니다.

`CanActivateFn` 예시를 들어보면 이렇습니다.

## 인젝션 컨텍스트 안에서 실행하기

<!--
If you need to run a function within an injection context without already being in one, you can use `runInInjectionContext`.
This requires access to an injector, such as the `EnvironmentInjector`:

```ts
{highlight: [7], header:"hero.service.ts"}
@Service()
export class HeroService {
  private environmentInjector = inject(EnvironmentInjector);

someMethod() {
    runInInjectionContext(this.environmentInjector, () => {
      inject(SomeService); // Do what you need with the injected service
    });
  }
}
```

Note that [`inject`](/api/core/inject) returns an instance only if the injector can resolve the requested token.
-->

의존성 주입 컨텍스트가 아닌 함수 안에서 의존성과 관련된 함수를 실행하려면 `runInInjectionContext`를 사용하면 됩니다.
이 방식을 사용하려면 `EnvironmentInjector`와 같은 인젝터에 접근할 수 있어야 합니다:

```ts
{highlight: [7], header:"hero.service.ts"}
@Service()
export class HeroService {
  private environmentInjector = inject(EnvironmentInjector);

someMethod() {
    runInInjectionContext(this.environmentInjector, () => {
      inject(SomeService); // 주입받은 서비스로 원하는 로직을 작성합니다.
    });
  }
}
```

참고로 [`inject`](/api/core/inject) 함수는 요청한 토큰을 찾을 수 있을 때만 해당 토큰의 인스턴스를 반환합니다.

## 컨텍스트 보장하기

<!--
Angular provides the `assertInInjectionContext` helper function to verify that the current context is an injection context and throw a clear error if it is not. Pass a reference to the calling function so the error message points to the correct API entry point. This produces a clearer, more actionable message than the default generic injection error.

```ts
import {ElementRef, assertInInjectionContext, inject} from '@angular/core';

export function injectNativeElement<T extends Element>(): T {
  assertInInjectionContext(injectNativeElement);
  return inject(ElementRef).nativeElement;
}
```

You can then call this helper **from an injection context** (constructor, field initializer, provider factory, or code executed via `runInInjectionContext`):

```ts
import {Component, inject} from '@angular/core';
import {injectNativeElement} from './dom-helpers';

@Component({/* … */})
export class PreviewCard {
  readonly hostEl = injectNativeElement<HTMLElement>(); // Field initializer runs in an injection context.

onAction() {
    const anotherRef = injectNativeElement<HTMLElement>(); // Fails: runs outside an injection context.
  }
}
```
-->

Angular는 `assertInInjectionContext` 라는 헬퍼 함수를 제공하는데, 이 함수는 현재 컨텍스트가 의존성 주입 컨텍스트라면 아무 문제가 없지만, 의존성 주입 컨텍스트가 아니라면 오류를 발생시킵니다.
그리고 이 함수를 실행하면서 올바른 API 진입점을 인자로 전달할 수 있습니다.
이 방식을 사용하면 일반적인 인젝션 오류가 아니라 좀 더 명확하고 개선할 수 있는 메시지가 표시됩니다.

```ts
import {ElementRef, assertInInjectionContext, inject} from '@angular/core';

export function injectNativeElement<T extends Element>(): T {
  assertInInjectionContext(injectNativeElement);
  return inject(ElementRef).nativeElement;
}
```

클래스의 생성자, 필드 초기화, 프로바이더 팩토리 등 **의존성 주입 컨텍스트 안에서** 이 헬퍼 함수를 호출하면 이렇습니다:

```ts
import {Component, inject} from '@angular/core';
import {injectNativeElement} from './dom-helpers';

@Component({/* … */})
export class PreviewCard {
  readonly hostEl = injectNativeElement<HTMLElement>(); // 필드를 초기화할 때 의존성 주입 컨텍스트를 실행합니다.

onAction() {
    const anotherRef = injectNativeElement<HTMLElement>(); // 에러: 인젝션 컨텍스트가 아닙니다.
  }
}
```

## 의존성 주입 컨텍스트 밖에서 의존성 주입 사용하기

의존성 주입 컨텍스트가 아닌 곳에서 [`inject`](api/core/inject) 함수를 실행하거나 `assertInInjectionContext`를 실행하면 [NG0203 오류](/errors/NG0203)가 발생합니다.

# 인젝터의 계층 구조

<!--
This guide provides in-depth coverage of Angular's hierarchical dependency injection system, including resolution rules, modifiers, and advanced patterns.

NOTE: For basic concepts about injector hierarchy and provider scoping, see the [defining dependency providers guide](guide/di/defining-dependency-providers#injector-hierarchy-in-angular).
-->

이 문서는 Angular 의존성 주입 시스템을 의존성 객체 판단 규칙, 수정자, 고급 패턴을 포함하여 깊이 있게 다룹니다.

참고: 인젝터 계층의 기본 개념이나 프로바이더 범위를 확인하려면 [의존성 주입 프로바이더 문서](guide/di/defining-dependency-providers#injector-hierarchy-in-angular)를 참고하세요.

## 인젝터 계층의 종류

<!--
Angular has two injector hierarchies:

| Injector hierarchies            | Details                                                                                                                                                                   |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `EnvironmentInjector` hierarchy | Configure an `EnvironmentInjector` in this hierarchy using `@Service()` or `providers` array in `ApplicationConfig`.                                                      |
| `ElementInjector` hierarchy     | Created implicitly at each DOM element. An `ElementInjector` is empty by default unless you configure it in the `providers` property on `@Directive()` or `@Component()`. |
For `NgModule` based applications, you can provide dependencies with the `ModuleInjector` hierarchy using an `@NgModule()` or `@Injectable()` annotation.

-->

Angular의 인젝터 계층은 두 종류입니다:

| 인젝터 계층                | 설명                                                                                                                                                                   |
| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EnvironmentInjector` 계층 | `@Service()` 이나 `ApplicationConfig`의 `providers` 배열을 사용하면 `EnvironmentInjector`를 구성할 수 있습니다.                                                        |
| `ElementInjector` 계층     | 개별 DOM 엘리먼트마다 암묵적으로 구성됩니다. `@Directive()`나 `@Component()`의 `providers` 프로퍼티에서 구성하지 않는 한 `ElementInjector`는 기본적으로 비어 있습니다. |
`NgModule` 방식으로 개발한 애플리케이션이라면 `@NgModule()` 이나 `@Injectable()`에서 `ModuleInjector` 계층을 구성할 수 있습니다.
### `EnvironmentInjector`

<!--
The `EnvironmentInjector` can be configured in one of two ways by using:

- The `@Service()`
- The `ApplicationConfig` `providers` array
Using the `@Service()` decorator is preferable to using the `ApplicationConfig` `providers` array. With `@Service`, optimization tools can perform tree-shaking, which removes services that your application isn't using. This results in smaller bundle sizes.

Tree-shaking is especially useful for a library because the application which uses the library may not have a need to inject it.
`EnvironmentInjector` is configured by the `ApplicationConfig.providers`.

Provide services using `@Service()` as follows:

```ts
{highlight:[4]}
import {Service} from '@angular/core';

@Service() // <--provides this service in the root EnvironmentInjector
export class ItemService {
  name = 'telephone';
}
```

The `@Service()` or `@Injectable()` decorators identify a service class.
-->

`EnvironmentInjector`는 다음 두 가지 방법 중 하나로 구성할 수 있습니다:

- `@Service()`
- `ApplicationConfig` `providers` 배열로
`ApplicationConfig` `providers` 배열보다는 `@Service()` 데코레이터 사용을 더 권장합니다.
`@Service()`를 사용하면 최적화 툴이 트리 셰이킹을 수행할 수 있으며, 이 서비스가 실제로 애플리케이션에 사용되지 않으면 빌드 결과물에 포함하지 않습니다.
결과적으로 빌드 결과물의 크기가 꼭 필요한 수준으로 줄어들 수 있습니다.

트리 셰이킹은 라이브러리인 경우 특히 유용합니다.
애플리케이션이 라이브러리를 사용하지 않으면 빌드 결과물에도 포함되지 않기 때문입니다.
`EnvironmentInjector`는 `ApplicationConfig.providers`에서 구성할 수 있습니다.

`@Service()`를 사용해서 다음과 같이 서비스를 등록할 수 있습니다:

```ts
{highlight:[4]}
import {Service} from '@angular/core';

@Service() // <-- 이 서비스를 최상위 EnvironmentInjector에 등록합니다.
export class ItemService {
  name = 'telephone';
}
```

`@Service()`나 `@Injectable()` 데코레이터가 붙은 클래스는 Angular 서비스 클래스입니다.

### ModuleInjector

<!--
In the case of `NgModule` based applications, the ModuleInjector can be configured in one of two ways by using:

- The `@Service()` decorator,
- The `@Injectable()` `providedIn` property to refer to `root` or `platform`
- The `@NgModule()` `providers` array

`ModuleInjector` is configured by the `@NgModule.providers` and `NgModule.imports` property. `ModuleInjector` is a flattening of all the providers arrays that can be reached by following the `NgModule.imports` recursively.

Child `ModuleInjector` hierarchies are created when lazy loading other `@NgModules`.
-->

`NgModule` 기반 애플리케이션은 다음 두 가지 방법으로 `ModuleInjector`를 구성할 수 있습니다:

- `@Service()` 데코레이터를 사용할 때
- `@Injectable()` `providedIn` 프로퍼티 값으로 `root` 이나 `platform`을 사용할 때
- `@NgModule()` `providers` 배열을 사용할 때

`ModuleInjector`는 `@NgModule.providers`와 `@NgModule.imports` 프로퍼티를 사용해서 구성됩니다.
`ModuleInjector`는 `@NgModule.imports`를 재귀적으로 순회하면서 프로바이더 배열에 있는 모든 프로바이더를 평탄화(flattening)합니다.

`@NgModule`이 지연 로딩되는 경우에는 자식 `ModuleInjector` 계층이 구성됩니다.

### 플랫폼 인젝터

<!--
There are two more injectors above `root`, an additional `EnvironmentInjector` and `NullInjector()`.

Consider how Angular bootstraps the application with the following in `main.ts`:

```ts
bootstrapApplication(App, appConfig);
```

The `bootstrapApplication()` method creates a child injector of the platform injector which is configured by the `ApplicationConfig` instance.
This is the `root` `EnvironmentInjector`.

The `bootstrapApplication()` method also creates (or reuses) the platform injector, which contains platform-specific dependencies.
This allows multiple applications to share a platform configuration.
For example, a browser has only one URL bar, no matter how many applications you have running.
You can configure additional platform-specific providers at the platform level by supplying `extraProviders` using the `platformBrowser()` function.

The next parent injector in the hierarchy is the `NullInjector()`, which is the top of the tree.
If you've gone so far up the tree that you are looking for a service in the `NullInjector()`, you'll get an error unless you've used `@Optional()` because ultimately, everything ends at the `NullInjector()` and it returns an error or, in the case of `@Optional()`, `null`.
For more information on `@Optional()`, see the [`@Optional()` section](#optional) of this guide.

The following diagram represents the relationship between the `root` `ModuleInjector` and its parent injectors as the previous paragraphs describe.

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

While the name `root` is a special alias, other `EnvironmentInjector` hierarchies don't have aliases.
You have the option to create `EnvironmentInjector` hierarchies whenever a dynamically loaded component is created, such as with the Router, which will create child `EnvironmentInjector` hierarchies.

All requests forward up to the root injector, whether you configured it with the `ApplicationConfig` instance passed to the `bootstrapApplication()` method, or registered all providers with `root` in their own services.
If you configure an app-wide provider in the `ApplicationConfig` of `bootstrapApplication`, it overrides one configured for `root` in the `@Injectable()` metadata.
You can do this to configure a non-default provider of a service that is shared with multiple applications.

Here is an example of the case where the component router configuration includes a non-default [location strategy](guide/routing/common-router-tasks#locationstrategy-and-browser-url-styles) by listing its provider in the `providers` list of the `ApplicationConfig`.

```ts
providers: [{provide: LocationStrategy, useClass: HashLocationStrategy}];
```

For `NgModule` based applications, configure app-wide providers in the `AppModule` `providers`.
-->

`root` 인젝터 상위 계층에는 `EnvironmentInjector`와 `NullInjector()`가 존재합니다.

`main.ts` 파일에서 Angular가 애플리케이션을 부트스트랩하는 과정을 살펴봅시다:

```ts
bootstrapApplication(App, appConfig);
```

`bootstrapApplication` 메서드는 `ApplicationConfig` 인스턴스 값에 따라 플랫폼 인젝터의 자식 인젝터를 생성합니다.
이것이 최상위 인젝터인 `EnvironmentInjector`입니다.

`bootstrapApplication()` 메서드는 플랫폼별 의존성이 있는 플랫폼 인젝터를 생성하거나 기존 인젝터를 재사용합니다.
이 방식에 따라 플랫폼 환경설정을 공유하는 애플리케이션은 여러 개가 될 수도 있습니다.
예를 들면, 브라우저에서 실행되는 애플리케이션 숫자에 관계없이 브라우저에는 주소표시줄이 하나만 존재합니다.
그리고 `platformBrowser()` 함수를 실행할 때 `extraProviders` 옵션을 사용해서 플랫폼 계층에 플랫폼별 프로바이더를 추가로 구성할 수 있습니다.

그다음으로 트리 최상단에 존재하는 부모 인젝터는 `NullInjector()` 입니다.
`@Optional()`을 사용하지 않은 채로 의존성 객체를 찾다가 `NullInjector()`를 만나면 오류가 발생합니다.
왜냐하면 `NullInjector()`는 의존성 객체를 찾는 마지막 지점이기 때문에 `@Optional()`을 사용한 경우 `null`을 반환하거나, 아니면 오류를 반환하기 때문입니다.
`@Optional()`에 대해 자세하게 알아보려면 이 문서의 [`@Optional()` 섹션](#optional)을 참고하세요.

아래 다이어그램은 최상위 `ModuleInjector`와 그 부모 인젝터들의 관계를 표현합니다.

```mermaid
stateDiagram-v2
    elementInjector: EnvironmentInjector<br>(Angular가 구성)<br>'platform'으로 providedIn 설정하면 등록됩니다.
    rootInjector: 최상위 EnvironmentInjector<br>(AppConfig에 따라 구성)<br>bootstrapApplication(..., AppConfig)을 실행할 때 구성
    nullInjector: NullInjector<br>@Optional()을 사용하지 않으면 에러가 발생합니다.

direction BT
    rootInjector --> elementInjector
    elementInjector --> nullInjector
```

`root`라는 이름은 특별한 별칭이지만, `EnvironmentInjector`와 같은 계층에는 별칭이 없습니다.
Router와 같이 컴포넌트를 동적으로 로딩할 때마다 `EnvironmentInjector` 계층 구조를 생성할 수 있습니다.

`bootstrapApplication()` 메서드에 `ApplicationConfig` 인스턴스가 전달되거나, 각 서비스에서 `root` 계층으로 등록하면 인스턴스 주입 요청은 최상위 인젝터까지 전달됩니다.
`bootstrapApplication()` 메서드와 `ApplicationConfig`를 사용해서 앱 전역 프로바이더를 설정하면 `@Injectable()` 메타데이터에서 `root`로 설정한 것을 오버라이드합니다.
이 방식을 활용하면 애플리케이션 여러 곳에 사용되는 서비스 프로바이더 구성을 변경할 수 있습니다.

아래 예제처럼 `ApplicationConfig`에서 `providers` 배열에 프로바이더를 등록하면 컴포넌트 라우터 설정 중 [location 정책](guide/routing/common-router-tasks#locationstrategy-and-browser-url-styles)을 변경할 수 있습니다.

```ts
providers: [{provide: LocationStrategy, useClass: HashLocationStrategy}];
```

`NgModule` 기반으로 개발한 애플리케이션이라면, `AppModule` `providers`에 프로바이더를 설정하면 동일한 효과가 됩니다.
### `ElementInjector`

<!--
Angular creates `ElementInjector` hierarchies implicitly for each DOM element.

Providing a service in the `@Component()` decorator using its `providers` or `viewProviders` property configures an `ElementInjector`.
For example, the following `TestComponent` configures the `ElementInjector` by providing the service as follows:

```ts
{highlight:[3]}
@Component({
  /* … */
  providers: [{ provide: ItemService, useValue: { name: 'lamp' } }]
})
export class TestComponent
```

HELPFUL: See the [resolution rules](#resolution-rules) section to understand the relationship between the `EnvironmentInjector` tree, the `ModuleInjector` and the `ElementInjector` tree.

When you provide services in a component, that service is available by way of the `ElementInjector` at that component instance.
It may also be visible at child component/directives based on visibility rules described in the [resolution rules](#resolution-rules) section.

When the component instance is destroyed, so is that service instance.
-->

Angular는 개별 DOM 엘리먼트마다 `ElementInjector` 계층을 구성합니다.

그래서 `@Component()` 데코레이터의 `providers` 프로퍼티나 `viewProviders` 프로퍼티를 사용하면 `ElementInjector` 계층이 구성됩니다.
예를 들어 다음과 같이 `TestComponent` 코드를 작성하면 해당 서비스가 `ElementInjector` 계층에 등록됩니다:

```ts
{highlight:[3]}
@Component({
  /* … */
  providers: [{ provide: ItemService, useValue: { name: 'lamp' } }]
})
export class TestComponent
```

참고: `EnvironmentInjector` 트리와 `ModuleInjector`, `ELementInjector` 트리 관계를 이해하려면 [의존성 객체 결정 규칙](#의존성-객체-결정-규칙) 섹션을 참고하세요.

서비스를 컴포넌트 계층에 등록하면, 해당 서비스는 컴포넌트 인스턴스의 `ElementInjector`를 통해 사용할 수 있습니다.
그래서 이 컴포넌트의 자식 컴포넌트나 디렉티브라면 [의존성 객체 결정 규칙](#의존성-객체-결정-규칙)에 따라 해당 서비스의 인스턴스에 접근할 수 있습니다.

이렇게 등록된 서비스의 인스턴스는 컴포넌트 인스턴스가 종료되면 함께 종료됩니다.

#### `@Directive()`, `@Component()`

컴포넌트는 디렉티브의 특수한 형태라고 볼 수 있습니다.
그렇다는 것은 `@Directive()`에 `providers` 프로바이더가 있는 것처럼 `@Component()` 에서도 `providers` 배열을 활용해서 프로바이더를 등록할 수 있습니다.
컴포넌트나 디렉티브에서 `providers` 프로퍼티로 프로바이더를 등록하면, 이 프로바이더는 해당 컴포넌트/디렉티브의 `ElementInjector`에 등록됩니다.
엘리먼트에 컴포넌트와 디렉티브가 동시에 존재하면 이 컴포넌트와 디렉티브는 인젝터를 공유합니다.

## 의존성 객체 결정 규칙

<!--
When resolving a token for a component/directive, Angular resolves it in two phases:

1. Against its parents in the `ElementInjector` hierarchy.
2. Against its parents in the `EnvironmentInjector` hierarchy.

When a component declares a dependency, Angular tries to satisfy that dependency with its own `ElementInjector`.
If the component's injector lacks the provider, it passes the request up to its parent component's `ElementInjector`.

The requests keep forwarding up until Angular finds an injector that can handle the request or runs out of ancestor `ElementInjector` hierarchies.

If Angular doesn't find the provider in any `ElementInjector` hierarchies, it goes back to the element where the request originated and looks in the `EnvironmentInjector` hierarchy.
If Angular still doesn't find the provider, it throws an error.

If you have registered a provider for the same DI token at different levels, the first one Angular encounters is the one it uses to resolve the dependency.
If, for example, a provider is registered locally in the component that needs a service,
Angular doesn't look for another provider of the same service.

HELPFUL: For `NgModule` based applications, Angular will search the `ModuleInjector` hierarchy if it cannot find a provider in the `ElementInjector` hierarchies.
-->

컴포넌트/디렉티브에서 의존성 객체 토큰을 결정할 때는 두 단계로 진행됩니다:

1. `ElementInjector` 계층을 따라 부모 방향으로 탐색합니다.
2. `EnvironmentInjector` 계층을 따라 부모 방향으로 탐색합니다.

어떤 컴포넌트에 의존성 객체가 등록되면 Angular는 해당 `ElementInjector`에서 의존성 객체를 찾습니다.
그리고 컴포넌트 인젝터에서 프로바이더를 찾지 못하면, 부모 컴포넌트의 `ElementInjector`를 따라 의존성 객체를 찾습니다.

이런 요청은 부모 `ElementInjector` 계층을 따라 거슬러 올라가며 원하는 의존성 객체를 찾을 때까지 계속됩니다.

Angular가 `ElementInjector` 계층을 따라 탐색했지만 의존성 객체를 찾지 못하면, 다시 시작 엘리먼트로 돌아가서 `EnvironmentInjector` 계층을 따라 다시 한 번 탐색합니다.
그리고 마지막까지 의존성 객체를 찾지 못하면 오류가 발생합니다.

같은 의존성 객체 토큰을 다른 계층에 등록하면, 먼저 만나는 의존성 객체를 사용합니다.
그래서 어떤 서비스가 컴포넌트 계층에 등록되어 있다면, Angular는 해당 컴포넌트에 등록된 프로바이더를 사용하며 다른 곳을 탐색하지 않습니다.

참고: `NgModule` 기반 애플리케이션은 `ElementInjector` 계층에서 의존성 객체를 찾지 못했을 때 `ModuleInjector` 계층을 탐색합니다.

## 의존성 객체 결정에 영향을 주는 심볼

`optional`, `self`, `skipSelf`, `host`를 사용하면 의존성 객체 결정 방식을 변경할 수 있습니다.
이 심볼들은 `@angular/core` 패키지로 제공되며, [`inject`](/api/core/inject) 함수를 사용할 때 사용할 수 있습니다.

### 종류

<!--
Resolution modifiers fall into three categories:

- What to do if Angular doesn't find what you're looking for, that is `optional`
- Where to start looking, that is `skipSelf`
- Where to stop looking, `host` and `self`

By default, Angular always starts at the current `Injector` and keeps searching all the way up.
Modifiers allow you to change the starting, or _self_, location and the ending location.

Additionally, you can combine all of the modifiers except:

- `host` and `self`
- `skipSelf` and `self`.
-->

의존성 객체에 영향을 주는 심볼은 세 종류로 구분할 수 있습니다:

- Angular가 의존성 객체를 찾지 못할 때: `optional`
- 의존성 객체 탐색 시작 위치를 변경할 때: `skipSelf`
- 의존성 객체 탐색을 멈출 위치를 변경할 때: `host`, `self`

기본적으로 Angular는 현재 위치의 `Injector`부터 의존성 객체를 찾기 시작하지만, 이런 심볼들을 사용하면 의존성 탐색의 시작 위치와 종료 위치를 변경할 수 있습니다.

그리고 다음 조합을 제외한 심볼은 동시에 사용할 수 있습니다:

- `host`와 `self`
- `skipSelf`와 `self`

### `optional`

<!--
`optional` allows Angular to consider a service you inject to be optional.
This way, if it can't be resolved at runtime, Angular resolves the service as `null`, rather than throwing an error.
In the following example, the service, `OptionalService`, isn't provided in the service, `ApplicationConfig`, `@NgModule()`, or component class, so it isn't available anywhere in the app.

```ts
{header:"src/app/optional/optional.ts"}
export class Optional {
  public optional? = inject(OptionalService, {optional: true});
}
```
-->

의존성 객체를 찾지 못해도 오류가 발생하지 않으며, 의존성으로 요청한 객체의 인스턴스는 `null`이 반환됩니다.
아래 예제 코드에서 `OptionalService`는 `ApplicationConfig`, `@NgModule()`, 컴포넌트 클래스 어디에도 등록되지 않았기 때문에 의존성 객체의 인스턴스를 찾을 수 없습니다.

```ts
{header:"src/app/optional/optional.ts"}
export class Optional {
  public optional? = inject(OptionalService, {optional: true});
}
```

### `self`

<!--
Use `self` so that Angular will only look at the `ElementInjector` for the current component or directive.

A good use case for `self` is to inject a service but only if it is available on the current host element.
To avoid errors in this situation, combine `self` with `optional`.

For example, in the following `SelfNoData`, notice the injected `LeafService` as a property.

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

In this example, there is a parent provider and injecting the service will return the value, however, injecting the service with `self` and `optional` will return `null` because `self` tells the injector to stop searching in the current host element.

Another example shows the component class with a provider for `FlowerService`.
In this case, the injector looks no further than the current `ElementInjector` because it finds the `FlowerService` and returns the tulip 🌷.

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

`self`를 사용하면 Angular는 해당 컴포넌트/디렉티브의 `ElementInjector`에서만 의존성 객체를 찾습니다.

`self`는 현재 호스트 엘리먼트에서 사용할 수 있는 서비스 인스턴스를 참조할 때 사용하면 좋습니다.
이때 오류가 발생하는 것을 방지하려면 `self`와 `optional`을 함께 사용하세요.

예를 들어 아래 코드에서 `SelfNoDataComponent`는 `LeafService`를 의존성 객체로 요청합니다.

이 예제에서 부모 프로바이더가 있고 서비스 객체도 존재한다면 의존성 객체의 인스턴스가 주입되겠지만, `self`와 `optional`을 사용하면 현재 호스트 엘리먼트까지 탐색하고 의존성 객체를 찾지 않기 때문에 의존성 객체 인스턴스로 `null`을 사용합니다.

`FlowerService`를 사용하는 예제를 살펴봅시다.
아래 예제 코드에서 인젝터는 현재 계층의 `ElementInjector`에서만 의존성 객체를 찾기 때문에, `FlowerService`는 튤립(<code>🌷</code>)을 반환합니다.

### `skipSelf`

<!--
`skipSelf` is the opposite of `self`.
With `skipSelf`, Angular starts its search for a service in the parent `ElementInjector`, rather than in the current one.
So if the parent `ElementInjector` were using the fern <code>🌿</code> value for `emoji`, but you had maple leaf <code>🍁</code> in the component's `providers` array, Angular would ignore maple leaf <code>🍁</code> and use fern <code>🌿</code>.

To see this in code, assume that the following value for `emoji` is what the parent component were using, as in this service:

```ts
{header: 'leaf.service.ts'}
export class LeafService {
  emoji = '🌿';
}
```

Imagine that in the child component, you had a different value, maple leaf 🍁 but you wanted to use the parent's value instead.
This is when you'd use `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});
}
```

In this case, the value you'd get for `emoji` would be fern <code>🌿</code>, not maple leaf <code>🍁</code>.
-->

`skipSelf`는 `self`와 반대입니다.
`skipSelf`를 사용하면 Angular는 현재 컴포넌트/디렉티브의 부모 `ElementInjector`부터 의존성 객체를 찾기 시작합니다.
그래서 현재 컴포넌트의 `providers` 배열에 단풍잎 <code>🍁</code>이 의존성 객체로 등록되어 있고, 부모 `ElementInjector`에 양치식물 <code>🌿</code>이 등록되어 있으면, Angular는 단풍잎 <code>🍁</code>을 건너뛰고 양치식물 <code>🌿</code>을 의존성 객체로 사용합니다.

코드로 보면, 부모 컴포넌트에 다음과 같이 등록되었다고 합시다.

```ts
{header: 'leaf.service.ts'}
export class LeafService {
  emoji = '🌿';
}
```

자식 컴포넌트에는 `LeafService`에 대해 단풍잎 <code>🍁</code>이 등록되어 있지만, `skipSelf`를 사용하면 이 값 대신 부모 계층의 값이 대신 사용됩니다:

```ts
{header:"skipself.ts" highlight:[[6],[10]]}
@Component({
  selector: 'app-skipself',
  templateUrl: './skipself.html',
  styleUrls: ['./skipself.css'],
  // 이 계층의 LeafService 인스턴스는 무시합니다.
  providers: [{provide: LeafService, useValue: {emoji: '🍁'}}],
})
export class Skipself {
  // skipSelf 옵션을 사용했습니다.
  public leaf = inject(LeafService, {skipSelf: true});
}
```

이 경우 `SkipselfComponent`에 주입되는 의존성 객체의 값은 단풍잎 <code>🍁</code>이 아니라 양치식물 <code>🌿</code>입니다.

#### `skipSelf`와 `optional`을 함께 사용하는 경우

<!--
Use the `skipSelf` option with `optional` to prevent an error if the value is `null`.

In the following example, the `Person` service is injected during property initialization.
`skipSelf` tells Angular to skip the current injector and `optional` will prevent an error should the `Person` service be `null`.

```ts
class Person {
  parent = inject(Person, {optional: true, skipSelf: true});
}
```
-->

`skipSelf` 옵션을 사용할 때 `optional`을 함께 사용하면 의존성 객체를 찾지 못해 `null`을 반환하더라도 오류가 발생하지 않습니다.

아래 코드는 프로퍼티 초기화 시점에 `Person` 서비스를 의존성으로 주입받는 예제 코드입니다.
이때 `skipSelf`를 사용했기 때문에 현재 계층의 인젝터는 건너뛰지만, `optional`을 함께 사용했기 때문에 `Person` 서비스를 찾지 못해 `null`을 반환하더라도 오류가 발생하지는 않습니다.

```ts
class Person {
  parent = inject(Person, {optional: true, skipSelf: true});
}
```

### `host`

<!--
`host` lets you designate a component as the last stop in the injector tree when searching for providers.

Even if there is a service instance further up the tree, Angular won't continue looking.
Use `host` as follows:

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

Since `Host` has the `host` option, no matter what the parent of `Host` might have as a `flower.emoji` value, the `Host` will use tulip <code>🌷</code>.
-->

`host`를 사용하면 의존성 객체 탐색 지점의 마지막 위치를 지정할 수 있습니다.

그래서 `host`를 사용하면 해당 계층 위쪽으로 의존성 객체의 인스턴스가 존재하더라도 위 계층을 탐색하지 않습니다.
`host`는 이런 경우에 사용합니다:

```ts
{header:"host.component.ts" highlight:[[6],[9]]}
@Component({
  selector: 'app-host',
  templateUrl: './host.html',
  styleUrls: ['./host.css'],
  // 서비스 프로바이더를 등록합니다.
  providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}],
})
export class Host {
  // 의존성 객체를 참조하면서 host 옵션을 사용합니다.
  flower = inject(FlowerService, {host: true, optional: true});
}
```

`HostComponent`에는 `host` 옵션을 사용했기 때문에, `HostComponent` 부모 컴포넌트에서 `flower.emoji` 값을 무엇으로 정해도 아무 영향을 주지 않습니다.
`HostComponent`가 받는 의존성 객체의 값은 튤립 <code>🌷</code>이 됩니다.

### 생성자 주입 시점에 사용하기

<!--
Similarly as presented before, the behavior of constructor injection can be modified with `@Optional()`, `@Self()`, `@SkipSelf()` and `@Host()`.

Import each of them from `@angular/core` and use each in the component class constructor when you inject your service.

```ts
{header:"self-no-data.ts" highlight:[2]}
export class SelfNoData {
  constructor(@Self() @Optional() public leaf?: LeafService) {}
}
```
-->

위에서 다룬 것처럼, `@Optional()`, `@Self()`, `@SkipSelf()`, `@Host()`는 생성자에서 의존성 객체를 주입할 때도 사용할 수 있습니다.

개별 심볼은 `@angular/core` 패키지로 제공되며, 컴포넌트 클래스 생성자에 주입하는 서비스마다 다음과 같이 지정하면 됩니다.

```ts
{header:"self-no-data.ts" highlight:[2]}
export class SelfNoData {
  constructor(@Self() @Optional() public leaf?: LeafService) {}
}
```

## 템플릿의 논리 구조

<!--
When you provide services in the component class, services are visible within the `ElementInjector` tree relative to where and how you provide those services.

Understanding the underlying logical structure of the Angular template will give you a foundation for configuring services and in turn control their visibility.

Components are used in your templates, as in the following example:

```html
<app-root> <app-child />; </app-root>
```

HELPFUL: Usually, you declare the components and their templates in separate files.
For the purposes of understanding how the injection system works, it is useful to look at them from the point of view of a combined logical tree.
The term _logical_ distinguishes it from the render tree, which is your application's DOM tree.
To mark the locations of where the component templates are located, this guide uses the `<#VIEW>` pseudo-element, which doesn't actually exist in the render tree and is present for mental model purposes only.

The following is an example of how the `<app-root>` and `<app-child>` view trees are combined into a single logical tree:

```html
<app-root>
  <#VIEW>
    <app-child>
     <#VIEW>
       …content goes here…
     </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

Understanding the idea of the `<#VIEW>` demarcation is especially significant when you configure services in the component class.
-->

컴포넌트 클래스에 서비스 프로바이더를 등록했다면, 이 서비스는 `ElementInjector` 트리 안에서 접근할 수 있습니다.

Angular 템플릿의 논리 구조를 이해하면 서비스를 어떻게 구성하는지, 어느 범위에서 접근할 수 있는지 더 명확하게 이해할 수 있습니다.

컴포넌트는 템플릿에 이렇게 사용됩니다:

```html
<app-root> <app-child />; </app-root>
```

참고: 일반적으로 컴포넌트 클래스 코드와 템플릿은 별도 파일로 작성합니다.
의존성 주입 시스템이 어떻게 동작하는지 이해하려면 이 둘을 논리적 트리로 합쳐서 바라보는 것이 좋습니다.
이때 _논리적(logical)_ 이라는 것은 애플리케이션 DOM 트리인 렌더링 트리와 구분하기 위한 용어입니다.
그리고 컴포넌트 템플릿이 위치한 곳을 표시하기 위해 예제 코드에서는 `<#VIEW>` 라는 임시 엘리먼트를 사용하겠습니다.
이 엘리먼트는 렌더링 트리에 실제로 존재하는 것은 아니며, 이해를 돕기 위한 목적입니다.

트리 하나로 구성되는 `<app-root>`와 `<app-child>` 뷰 트리를 표현해보면 이렇습니다:

```html
<app-root>
  <#VIEW>
    <app-child>
     <#VIEW>
       …내용물은 여기에 들어갑니다…
     </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

컴포넌트 클래스에 서비스를 등록한다면 `<#VIEW>`라는 개념을 구분해서 이해하는 것이 중요합니다.

## 예제: 서비스를 `@Component()`에 등록하기

<!--
How you provide services using a `@Component()` (or `@Directive()`) decorator determines their visibility.
The following sections demonstrate `providers` and `viewProviders` along with ways to modify service visibility with `skipSelf` and `host`.

A component class can provide services in two ways:

| Arrays                       | Details                                        |
| :--------------------------- | :--------------------------------------------- |
| With a `providers` array     | `@Component({ providers: [SomeService] })`     |
| With a `viewProviders` array | `@Component({ viewProviders: [SomeService] })` |

In the examples below, you will see the logical tree of an Angular application.
To illustrate how the injector works in the context of templates, the logical tree will represent the HTML structure of the application.
For example, the logical tree will show that `<child-component>` is a direct child of `<parent-component>`.

In the logical tree, you will see special attributes: `@Provide`, `@Inject`, and `@ApplicationConfig`.
These aren't real attributes but are here to demonstrate what is going on under the hood.

| Angular service attribute | Details                                                                                  |
| :------------------------ | :--------------------------------------------------------------------------------------- |
| `@Inject(Token)=>Value`   | If `Token` is injected at this location in the logical tree, its value would be `Value`. |
| `@Provide(Token=Value)`   | Indicates that `Token` is provided with `Value` at this location in the logical tree.    |
| `@ApplicationConfig`      | Demonstrates that a fallback `EnvironmentInjector` should be used at this location.      |
-->

`@Component()`나 `@Directive()` 데코레이터에 서비스 프로바이더를 등록하면 이 서비스의 접근 범위가 결정됩니다.
다음 섹션에서는 `providers`나 `viewProviders`, `skipSelf`와 `host`를 사용해서 서비스의 접근 범위를 변경하는 방법을 알아봅시다.

서비스 프로바이더를 컴포넌트 클래스에 등록하는 방법은 두 가지입니다:

| 배열            | 설명                                           |
| :-------------- | :--------------------------------------------- |
| `providers`     | `@Component({ providers: [SomeService] })`     |
| `viewProviders` | `@Component({ viewProviders: [SomeService] })` |

아래 예제 코드에서는 Angular 애플리케이션의 논리 트리를 확인할 수 있습니다.
템플릿 컨텍스트에서 인젝터가 어떻게 동작하는지 설명하기 위해, 논리 트리는 HTML 구조로 표현하겠습니다.
예를 들어 논리 트리에 있는 `<child-component>`는 `<parent-component>`의 직접 자식 엘리먼트인 것을 의미합니다.

논리 트리에서 `@Provide`, `@Inject`, `@ApplicationConfig` 와 같은 특수 어트리뷰트를 확인할 수 있습니다.
이 어트리뷰트들이 실제 어트리뷰트는 아니지만, 개념을 설명하기 위한 것입니다.

### 예제 앱의 구조

<!--
The example application has a `FlowerService` provided in `root` with an `emoji` value of red hibiscus <code>🌺</code>.

```ts
{header:"flower.service.ts"}
@Service()
export class FlowerService {
  emoji = '🌺';
}
```

Consider an application with only an `App` and a `Child`.
The most basic rendered view would look like nested HTML elements such as the following:

```html
<app-root>
  <!- App selector ->
  <app-child> <!- Child selector -> </app-child>
</app-root>
```

However, behind the scenes, Angular uses a logical view representation as follows when resolving injection requests:

```html
<app-root> <!- App selector ->
  <#VIEW>
    <app-child> <!- Child selector ->
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

The `<#VIEW>` here represents an instance of a template.
Notice that each component has its own `<#VIEW>`.

Knowledge of this structure can inform how you provide and inject your services, and give you complete control of service visibility.

Now, consider that `<app-root>` injects the `FlowerService`:

```typescript
export class App {
  flower = inject(FlowerService);
}
```

Add a binding to the `<app-root>` template to visualize the result:

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

The output in the view would be:

```text
{hideCopy}
Emoji from FlowerService: 🌺
```

In the logical tree, this would be represented as follows:

```html
<app-root @ApplicationConfig
        @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
    <p>Emoji from FlowerService: {{flower.emoji}} (🌺)</p>
    <app-child>
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

When `<app-root>` requests the `FlowerService`, it is the injector's job to resolve the `FlowerService` token.
The resolution of the token happens in two phases:

1. The injector determines the starting location in the logical tree and an ending location of the search.
   The injector begins with the starting location and looks for the token at each view level in the logical tree.
   If the token is found it is returned.

1. If the token is not found, the injector looks for the closest parent `EnvironmentInjector` to delegate the request to.

In the example case, the constraints are:

1. Start with `<#VIEW>` belonging to `<app-root>` and end with `<app-root>`.
   - Normally the starting point for search is at the point of injection.
     However, in this case `<app-root>` is a component. `@Component`s are special in that they also include their own `viewProviders`, which is why the search starts at `<#VIEW>` belonging to `<app-root>`.
     This would not be the case for a directive matched at the same location.
   - The ending location happens to be the same as the component itself, because it is the topmost component in this application.

1. The `EnvironmentInjector` provided by the `ApplicationConfig` acts as the fallback injector when the injection token can't be found in the `ElementInjector` hierarchies.
-->

예제 애플리케이션은 `FlowerService`를 `root` 계층에 등록하며, 이 서비스에 있는 `emoji` 프로퍼티 값은 히비스커스 <code>🌺</code> 입니다.

```ts
{header:"flower.service.ts"}
@Service()
export class FlowerService {
  emoji = '🌺';
}
```

예시 애플리케이션에는 `App`과 `Child`만 있다고 합시다.
일반적으로 구성하는 방법을 따르면 다음과 같이 구성할 수 있을 것입니다:

```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>`를 갖습니다.

이 구조를 이해하면 서비스를 어떻게 등록해야 하는지, 어떻게 주입할 수 있는지, 어느 범위에서 접근할 수 있는지 이해하는 데에 큰 도움이 됩니다.

이제 `FlowerService`를 주입받는 `<app-root>`를 봅시다:

```typescript
export class App {
  flower = inject(FlowerService);
}
```

`<app-root>` 컴포넌트의 `flower` 프로퍼티는 템플릿에 이렇게 바인딩됩니다:

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

그리고 최종 결과물은 이렇습니다:

```text
{hideCopy}
Emoji from FlowerService: 🌺
```

논리 트리 관점에서 보면 이렇게 표현할 수 있습니다:

`<app-root>`에서 `FlowerService`를 의존성 객체로 요청하면, 인젝터가 `FlowerService` 토큰을 찾기 시작합니다.
이 토큰은 두 단계로 결정됩니다:

1. 인젝터가 논리 트리에서 검색할 시작 위치와 종료 위치를 결정합니다.
   그리고 인젝터는 검색 시작 위치에서 토큰을 찾는데, 토큰을 발견하면 토큰에 연결된 값을 반환합니다.

1. 토큰을 찾지 못하면 인젝터는 가장 가까운 부모 `EnvironmentInjector`에서 다시 토큰을 찾습니다.

예제 코드로 설명하면 이렇습니다:

1. `<app-root>`의 `<#VIEW>` 범위에서만 토큰을 찾습니다.
   - 일반적으로는 의존성 객체를 요청한 계층부터 의존성 객체의 토큰을 찾기 시작합니다.
     하지만, `<app-root>` 는 컴포넌트이며, `viewProviders`가 설정되어 있습니다. 따라서 의존성 객체는 `<app-root>` 컴포넌트의 `<#VIEW>` 부터 찾기 시작합니다.
     같은 계층에 존재하는 디렉티브는 해당되지 않습니다.
   - 의존성 객체를 검색하는 마지막 지점이 같은 컴포넌트인 이유는, 이 컴포넌트가 애플리케이션의 최상위 컴포넌트이기 때문입니다.

1. `ElementInjector` 계층에서 의존성 토큰을 찾지 못하면, `ApplicationConfig`로 구성된 `EnvironmentInjector`가 대체 인젝터로서 요청을 처리합니다.

### `providers` 배열을 활용하는 방법

<!--
Now, in the `Child` class, add a provider for `FlowerService` to demonstrate more complex resolution rules in the upcoming sections:

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

Now that the `FlowerService` is provided in the `@Component()` decorator, when the `<app-child>` requests the service, the injector has only to look as far as the `ElementInjector` in the `<app-child>`.
It won't have to continue the search any further through the injector tree.

The next step is to add a binding to the `Child` template.

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

To render the new values, add `<app-child>` to the bottom of the `App` template so the view also displays the sunflower:

```text
{hideCopy}
Child Component
Emoji from FlowerService: 🌻
```

In the logical tree, this is represented as follows:

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW>

<p>Emoji from FlowerService: {{flower.emoji}} (🌺)</p>
  <app-child @Provide(FlowerService="🌻" )
             @Inject(FlowerService)=>"🌻"> <!- search ends here ->
    <#VIEW> <!- search starts here ->
    <h2>Child Component</h2>
    <p>Emoji from FlowerService: {{flower.emoji}} (🌻)</p>
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

When `<app-child>` requests the `FlowerService`, the injector begins its search at the `<#VIEW>` belonging to `<app-child>` $`<#VIEW>` is included because it is injected from `@Component()`$ and ends with `<app-child>`.
In this case, the `FlowerService` is resolved in the `providers` array with sunflower <code>🌻</code> of the `<app-child>`.
The injector doesn't have to look any further in the injector tree.
It stops as soon as it finds the `FlowerService` and never sees the red hibiscus <code>🌺</code>.
-->

이제 좀 더 복잡한 경우를 살펴보기 위해 `Child` 클래스에 `FlowerService`의 프로바이더를 추가해 봅시다:

```ts
@Component({
  selector: 'app-child',
  templateUrl: './child.html',
  styleUrls: ['./child.css'],
  // providers 배열을 사용해서 서비스 프로바이더를 등록합니다.
  providers: [{provide: FlowerService, useValue: {emoji: '🌻'}}],
})
export class Child {
  // 서비스를 의존성으로 주입합니다.
  flower = inject(FlowerService);
}
```

이제 `FlowerService`가 `@Component()` 데코레이터에 등록되었기 때문에, `<app-child>`에서 의존성 객체를 요청하면 인젝터는 `<app-child>`에 있는 `ElementInjector` 에서만 의존성 객체를 찾습니다.
인젝터 트리를 따라 위로 향하지 않습니다.

그다음 단계는 `Child` 템플릿에 바인딩을 추가해 봅시다:

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

이제 새 값을 렌더링하기 위해 `App` 템플릿 제일 아래에 `<app-child>`를 추가합니다.
그러면 해바라기가 화면에 표시될 것입니다:

```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`를 의존성 객체로 요청하면, 인젝터는 `<app-child>`의 `<#VIEW>`부터 의존성 객체를 찾기 시작합니다.
`<#VIEW>`는 `@Component()`에서 주입되기 때문에 검색 범위에 포함되며, `<app-child>`에서 검색이 종료됩니다.
이 예제의 경우는 `FlowerService`가 `<app-child>` 단계에서 `providers` 배열에 등록되었기 때문에 해바라기 <code>🌻</code> 가 의존성 객체로 결정됩니다.
그래서 인젝터는 이보다 상위 인젝터 트리는 탐색하지 않습니다.
히비스커스 <code>🌺</code>가 등록된 `FlowerService`는 전혀 참조하지 않습니다.

### `viewProviders` 배열을 활용하는 방법

<!--
Use the `viewProviders` array as another way to provide services in the `@Component()` decorator.
Using `viewProviders` makes services visible in the `<#VIEW>`.

HELPFUL: The steps are the same as using the `providers` array, with the exception of using the `viewProviders` array instead.

For step-by-step instructions, continue with this section.
If you can set it up on your own, skip ahead to [Modifying service availability](#visibility-of-provided-tokens).

For demonstration, we are building an `AnimalService` to demonstrate `viewProviders`.
First, create an `AnimalService` with an `emoji` property of whale <code>🐳</code>:

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

@Service()
export class AnimalService {
  emoji = '🐳';
}
```

Following the same pattern as with the `FlowerService`, inject the `AnimalService` in the `App` class:

```ts
export class App {
  public flower = inject(FlowerService);
  public animal = inject(AnimalService);
}
```

HELPFUL: You can leave all the `FlowerService` related code in place as it will allow a comparison with the `AnimalService`.

Add a `viewProviders` array and inject the `AnimalService` in the `<app-child>` class, too, but give `emoji` a different value.
Here, it has a value of dog 🐶.

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

Add bindings to the `Child` and the `App` templates.
In the `Child` template, add the following binding:

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

Additionally, add the same to the `App` template:

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

Now you should see both values in the browser:

```text
{hideCopy}
App
Emoji from AnimalService: 🐳

Child Component
Emoji from AnimalService: 🐶
```

The logic tree for this example of `viewProviders` is as follows:

```html
<app-root @ApplicationConfig
          @Inject(AnimalService) animal=>"🐳">
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService=>"🐶")>

<!- ^^using viewProviders means AnimalService is available in <#VIEW>->
    <p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

Just as with the `FlowerService` example, the `AnimalService` is provided in the `<app-child>` `@Component()` decorator.
This means that since the injector first looks in the `ElementInjector` of the component, it finds the `AnimalService` value of dog <code>🐶</code>.
It doesn't need to continue searching the `ElementInjector` tree, nor does it need to search the `ModuleInjector`.
-->

`@Component()` 데코레이터에서 `viewProviders` 배열을 활용해도 서비스를 의존성 객체로 등록할 수 있습니다.
`viewProviders`를 활용하면 `<#VIEW>`에서도 서비스에 접근할 수 있습니다.

참고: 방법은 `providers` 배열 대신 `viewProviders` 배열을 활용한다는 것 외에는 `providers` 배열을 활용할 때와 동일합니다.

단계별 설정방법은 이 섹션을 계속 진행하면 되며, 직접 설정하는 단계로 진행하려면 [서비스 접근범위 변경하기](#의존성-토큰의-접근-범위) 섹션을 참고하세요.

`viewProviders`를 설명하기 위해 `AnimalService`를 만들어 봅시다.
먼저, `AnimalService`에 `emoji` 프로퍼티 값으로 고래 <code>🐳</code>를 할당합니다:

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

@Service()
export class AnimalService {
  emoji = '🐳';
}
```

그리고 `FlowerService` 때와 마찬가지로, `App` 클래스에 `AnimalService` 를 의존성으로 주입합니다:

```ts
export class App {
  public flower = inject(FlowerService);
  public animal = inject(AnimalService);
}
```

참고: `FlowerService` 코드는 그대로 두고 `AnimalService`와 비교해봐도 좋습니다.

이번에는 `<app-child>` 클래스에 `viewProviders` 배열을 추가하고 `AnimalService`를 등록하는데, `emoji` 값을 강아지 <code>🐶</code>로 설정해 봅시다.

```typescript
@Component({
  selector: 'app-child',
  templateUrl: './child.html',
  styleUrls: ['./child.css'],
  // 서비스 프로바이더를 등록합니다.
  providers: [{provide: FlowerService, useValue: {emoji: '🌻'}}],
  viewProviders: [{provide: AnimalService, useValue: {emoji: '🐶'}}],
})
export class Child {
  // inject services
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

그리고 `App` 템플릿에 `Child`를 바인딩합니다.
`Child` 템플릿에는 이런 바인딩 문구가 있습니다:

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

그리고 `App` 템플릿에도 같은 내용을 추가합니다:

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

이제 브라우저에서 두 값이 어떻게 표시되는지 확인해 보세요:

```shell
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`는 `<app-child>`의 `@Component()` 데코레이터에 등록되어 있습니다.
이 말은, 인젝터가 컴포넌트의 `ElementInjector`에서 의존성 객체를 제일 먼저 찾기 때문에, 값이 강아지 <code>🐶</code>인 `AnimalService`를 찾게 된다는 것을 의미합니다.
상위 `ElementInjector` 트리나 `ModuleInjector` 트리를 탐색할 필요는 없습니다.

### `providers` vs. `viewProviders`

<!--
The `viewProviders` field is conceptually similar to `providers`, but there is one notable difference.
Providers in `viewProviders` are only visible inside the component's own view — content projected into the component via `<ng-content>` cannot see them.

To see the difference between using `providers` and `viewProviders`, add another component to the example and call it `Inspector`.
`Inspector` will be a child of the `Child`.
In `inspector.ts`, inject the `FlowerService` and `AnimalService` during property initialization:

```typescript
export class Inspector {
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

You do not need a `providers` or `viewProviders` array.
Next, in `inspector.html`, add the same markup from previous components:

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

Remember to add the `Inspector` to the `Child` `imports` array.

```ts
@Component({
  ...
  imports: [Inspector]
})
```

Next, add the following to `child.html`:

```html
...

<div class="container">
  <h3>Content projection</h3>
  <ng-content />
</div>
<h3>Inside the view</h3>

<app-inspector />
```

`<ng-content>` allows you to project content, and `<app-inspector>` inside the `Child` template makes the `Inspector` a child component of `Child`.

Next, add the following to `app.html` to take advantage of content projection.

```html
<app-child>
  <app-inspector />
</app-child>
```

The browser now renders the following, omitting the previous examples for brevity:

```text
{hideCopy}
...
Content projection

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐳

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐶
```

These four bindings demonstrate the difference between `providers` and `viewProviders`.
Remember that the dog emoji <code>🐶</code> is declared inside the `<#VIEW>` of `Child` and isn't visible to the projected content.
Instead, the projected content sees the whale <code>🐳</code>.

You might wonder why the projected `<app-inspector>` can still see <code>🐳</code>, which is the root-provided `AnimalService`.
The reason is that Angular DI tracks **where a component was declared**, not where it ends up being rendered.
`<app-inspector>` lives in `App`'s template, inside `App`'s `<#VIEW>`, so its lookup never goes through `Child`'s `<#VIEW>`.
Projecting it into `Child` cuts off access to `Child`'s `viewProviders` (<code>🐶</code>), but the root `AnimalService` (<code>🐳</code>) is still reachable up the tree.

However, in the next output section though, the `Inspector` is an actual child component of `Child`, `Inspector` is inside the `<#VIEW>`, so when it asks for the `AnimalService`, it sees the dog <code>🐶</code>.

The `AnimalService` in the logical tree would look like this:

```html
<app-root @ApplicationConfig
          @Inject(AnimalService) animal=>"🐳">
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService=>"🐶")>

<!- ^^using viewProviders means AnimalService is available in <#VIEW>->
    <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>
```

The projected `<app-inspector>` gets <code>🐳</code> because <code>🐶</code> belongs to `Child`'s view and projected content can't reach it.
<code>🐳</code> is accessible because `<app-inspector>` was declared in `App`'s template, so it can still walk up to the root `AnimalService`.

The `<app-inspector>` that lives directly inside `Child`'s template (not projected) gets <code>🐶</code> — it's inside the `<#VIEW>`, so no boundary to cross.
-->

`viewProviders`는 `providers`와 개념적으로 유사하지만, 중요한 차이가 있습니다.
`viewProviders`에 프로바이더를 등록하면 컴포넌트의 논리적 자식으로 추가되어 프로젝션되는 컨텐츠에서는 접근할 수 없습니다.

`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`를 `Child` `imports` 배열에 추가해야 하는 것을 잊지 마세요.

```ts
@Component({
  ...
  imports: [Inspector]
})
```

그리고 `child.html` 파일의 내용을 다음과 같이 구성합니다:

```html
...

<div class="container">
  <h3>Content projection</h3>
  <ng-content></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>
```

이제 브라우저는 간결하게 다음과 같이 표시됩니다:

```shell
...
Content projection

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐳

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐶
```

이렇게 네 가지로 바인딩한 결과를 보면 `providers`와 `viewProviders`의 차이점을 확인할 수 있습니다.
강아지 이모지 <code>🐶</code>는 `Child`의 `<#VIEW>` 안에 선언되어 있기 때문에 프로젝션된 컨텐츠 안에서는 접근할 수 없습니다.
프로젝션된 컨텐츠 안에서는 고래 <code>🐳</code>를 의존성 객체로 참조할 수 있습니다.

프로젝션된 `<app-inspector>`에서 왜 루트에 등록된 `AnimalService`인 <code>🐳</code>를 참조할 수 있는지 의문이 들 수 있습니다.
Angular의 의존성 주입 시스템은 **컴포넌트가 렌더링되는 곳** 이 아니라 **컴포넌트가 선언된 곳** 을 추적하기 때문입니다.
`<app-inspector>`는 `App`의 템플릿 안, 즉 `App`의 `<#VIEW>` 안에 선언되어 있으므로 의존성을 탐색할 때 `Child`의 `<#VIEW>`를 거치지 않습니다.
`Child` 안으로 프로젝션된 컨텐츠는 `Child`의 `viewProviders`에 등록된 <code>🐶</code>에는 접근할 수 없지만, 트리 상위의 루트 `AnimalService`인 <code>🐳</code>에는 접근할 수 있습니다.

그런데 다음 섹션을 보면, `Inspector`는 `Child`의 자식 컴포넌트이며, `Inspector`는 `<#VIEW>` 안에 존재하기 때문에, 이때 참조하는 `AnimalService`는 강아지 <code>🐶</code> 값이 됩니다.

로직 트리로 표현해보면 이렇습니다:

```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`의 뷰에 속하므로 프로젝션된 컨텐츠에서는 접근할 수 없습니다.
`<app-inspector>`가 `App`의 템플릿에 선언되어 있기 때문에 트리 상위의 루트 `AnimalService`인 <code>🐳</code>에는 접근할 수 있습니다.

프로젝션되지 않고 `Child`의 템플릿 안에 직접 선언된 `<app-inspector>`는 <code>🐶</code>를 참조합니다.
이 컴포넌트는 `<#VIEW>` 안에 있으므로 뷰 경계를 넘을 필요가 없습니다.

<!--
### Giving projected content access to a view injector

Content projected with `<ng-content>` can't see a component's `viewProviders`, because Angular resolves injection against the injector where the content is declared, not where it renders.

When you specifically want projected content to reach a view-level service — or the projecting component instance itself — accept the content as a template instead of `<ng-content>` and render it with an explicit injector.

Update `Child` to provide `AnimalService` in `viewProviders`, query the projected template, and render it through [`NgTemplateOutlet`](/api/common/NgTemplateOutlet) with `ngTemplateOutletInjector` set to an injector that can see that service:

```ts
@Component({
  selector: 'app-child',
  viewProviders: [AnimalService],
  imports: [NgTemplateOutlet],
  template: `
    <ng-container [ngTemplateOutlet]="content()" [ngTemplateOutletInjector]="injector" />
  `,
})
export class Child {
  readonly content = contentChild.required(TemplateRef);
  readonly injector = inject(Injector);
}
```

The consumer wraps the projected markup in an `<ng-template>`:

```html
<app-child>
  <ng-template>
    <app-inspector />
  </ng-template>
</app-child>
```

`Child` now creates `<app-inspector>` at the outlet using its own injector, so `AnimalService` resolves to the dog <code>🐶</code> even though the markup is written in `App`'s template. The cost is a little extra markup on both sides compared with `<ng-content>`.
-->

### 프로젝션된 콘텐츠에서 뷰 인젝터에 접근하기 {#giving-projected-content-access-to-a-view-injector}

`<ng-content>`로 프로젝션한 콘텐츠에서는 컴포넌트의 `viewProviders`에 접근할 수 없습니다.
Angular는 콘텐츠가 렌더링되는 위치가 아니라 선언된 위치의 인젝터를 기준으로 의존성을 찾기 때문입니다.

프로젝션한 콘텐츠에서 뷰 계층의 서비스나 콘텐츠를 프로젝션하는 컴포넌트 인스턴스 자체에 접근해야 한다면, `<ng-content>` 대신 템플릿으로 콘텐츠를 받아서 인젝터를 명시적으로 지정해 렌더링하세요.

`Child`의 `viewProviders`에 `AnimalService`를 제공하고, 프로젝션한 템플릿을 쿼리로 조회하세요.
그런 다음 [`NgTemplateOutlet`](/api/common/NgTemplateOutlet)으로 렌더링하면서 `ngTemplateOutletInjector`에 해당 서비스에 접근할 수 있는 인젝터를 지정하세요.

사용하는 쪽에서는 프로젝션할 마크업을 `<ng-template>`으로 감쌉니다.

```html
<app-child>
  <ng-template>
    <app-inspector />
  </ng-template>
</app-child>
```

이제 `Child`가 자체 인젝터를 사용해서 아웃렛에 `<app-inspector>`를 생성합니다. 따라서 마크업을 `App`의 템플릿에 작성했더라도 `AnimalService`는 강아지 <code>🐶</code>로 결정됩니다.
다만 `<ng-content>`를 사용할 때보다 양쪽에 마크업을 조금 더 작성해야 합니다.

### 의존성 토큰의 접근 범위

<!--
Visibility decorators influence where the search for the injection token begins and ends in the logic tree.
To do this, place visibility configuration at the point of injection, that is, when invoking `inject()`, rather than at a point of declaration.

To alter where the injector starts looking for `FlowerService`, add `skipSelf` to the `<app-child>` `inject()` invocation where `FlowerService` is injected.
This invocation is a property initializer in `<app-child>` as shown in `child.ts`:

```typescript
flower = inject(FlowerService, {skipSelf: true});
```

With `skipSelf`, the `<app-child>` injector doesn't look to itself for the `FlowerService`.
Instead, the injector starts looking for the `FlowerService` at the `ElementInjector` of the `<app-root>`, where it finds nothing.
Then, it goes back to the `<app-child>` `ModuleInjector` and finds the red hibiscus <code>🌺</code> value, which is available because `<app-child>` and `<app-root>` share the same `ModuleInjector`.
The UI renders the following:

```text
{hideCopy}
Emoji from FlowerService: 🌺
```

In a logical tree, this same idea might look like this:

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
  <app-child @Provide(FlowerService="🌻" )>
    <#VIEW @Inject(FlowerService, SkipSelf)=>"🌺">

<!- With SkipSelf, the injector looks to the next injector up the tree (app-root) ->

</
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

Though `<app-child>` provides the sunflower <code>🌻</code>, the application renders the red hibiscus <code>🌺</code> because `skipSelf` causes the current injector (`app-child`) to skip itself and look to its parent.

If you now add `host` (in addition to the `skipSelf`), the result will be `null`.
This is because `host` limits the upper bound of the search to the `app-child` `<#VIEW>`.
Here's the idea in the logical tree:

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW> <!- end search here with null->
  <app-child @Provide(FlowerService="🌻" )> <!- start search here ->
    <#VIEW inject(FlowerService, {skipSelf: true, host: true, optional:true})=>null>
  </
  #VIEW>
  </app-parent>
</#VIEW>
</app-root>
```

Here, the services and their values are the same, but `host` stops the injector from looking any further than the `<#VIEW>` for `FlowerService`, so it doesn't find it and returns `null`.
-->

접근 범위를 조절하는 데코레이터는 의존성 토큰을 로직 트리에서 찾는 시작 지점과 종료 지점을 변경합니다.
이렇게 접근 범위를 조절하려면, 선언 시점이 아니라 `inject()`를 실행해서 의존성 객체를 주입하는 시점에 데코레이터를 사용해야 합니다.

인젝터가 `FlowerService`를 찾는 시작 지점을 변경하려면 `<app-child>`에서 `inject()`를 실행해서 `FlowerService`를 주입하는 코드에 `skipSelf`를 추가하면 됩니다.
아래 예제 코드에서 보면 `child.ts` 파일의 `<app-child>` 컴포넌트에서 프로퍼티를 선언하는 시점에 해당됩니다:

```typescript
flower = inject(FlowerService, {skipSelf: true});
```

`skipSelf`를 사용하면 `<app-child>`의 인젝터가 자신의 계층에서 `FlowerService`를 탐색하지 않습니다.
대신에, 인젝터는 `<app-root>` 계층의 `ElementInjector`에서 `FlowerService`를 찾기 시작하며, 여기에서는 의존성 토큰을 찾지 못합니다.
그러면 이제 `<app-child>`와 `<app-root>`가 공유하고 있는 `ModuleInjector`로 돌아가서 빨간 히비스커스 <code>🌺</code> 값을 찾게 됩니다.
결과적으로 화면이 다음과 같이 표시됩니다:

```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>가 등록되어 있지만, `skipSelf`가 현재 인젝터(`app-child`)를 건너뛰고 부모 계층에서 의존성을 찾게 하므로 애플리케이션에는 빨간 히비스커스 <code>🌺</code>가 표시됩니다.

이 예제에서 `skipSelf`와 `host`를 함께 사용하면 `null`을 반환합니다.
왜냐하면 `host`는 `app-child`의 `<#VIEW>` 상위 계층의 탐색을 제한하기 때문입니다.
논리 트리로 표현하면 이렇습니다:

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW> 
    <app-child @Provide(FlowerService="🌻")> 
      <#VIEW inject(FlowerService, {skipSelf: true, host: true, optional:true})=>null>
    </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

이 예제를 보면, 서비스와 서비스에 연결된 값은 동일하지만, `host`가 지정되었기 때문에 인젝터가 현재 계층의 `<#VIEW>` 위쪽을 탐색하지 않기 때문에, `FlowerService`를 찾지 못하고 `null`을 반환합니다.

### `skipSelf`, `viewProviders`

<!--
Remember, `<app-child>` provides the `AnimalService` in the `viewProviders` array with the value of dog <code>🐶</code>.
Because the injector has only to look at the `ElementInjector` of the `<app-child>` for the `AnimalService`, it never sees the whale <code>🐳</code>.

As in the `FlowerService` example, if you add `skipSelf` to the `inject()` of `AnimalService`, the injector won't look in the `ElementInjector` of the current `<app-child>` for the `AnimalService`.
Instead, the injector will begin at the `<app-root>` `ElementInjector`.

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ],
})
```

The logical tree looks like this with `skipSelf` in `<app-child>`:

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW><!- search begins here ->
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService, SkipSelf=>"🐳")>

<!-Add skipSelf ->

</
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

With `skipSelf` in the `<app-child>`, the injector begins its search for the `AnimalService` in the `<app-root>` `ElementInjector` and finds whale 🐳.
-->

`<app-child>`의 `viewProviders` 배열에는 `AnimalService`가 강아지 <code>🐶</code> 값으로 등록되어 있습니다.
인젝터는 `<app-child>`의 `ElementInjector`에서만 `AnimalService`를 탐색하기 때문에, 고래 <code>🐳</code> 값은 절대 발견할 수 없습니다.

그래서 `FlowerService` 예제와 마찬가지로, `inject()`를 실행해서 `AnimalService`를 주입하는 코드에 `skipSelf`를 추가하면, 인젝터는 현재 `<app-child>` 계층의 `ElementInjector`에서 `AnimalService`를 찾지 못합니다.
대신, 인젝터는 `<app-root>`의 `ElementInjector` 부터 탐색을 시작합니다.

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ],
})
```

논리 트리로 표현하면 이렇습니다:

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW>
    <app-child>
      <#VIEW @Provide(AnimalService="🐶")
             @Inject(AnimalService, SkipSelf=>"🐳")>

</#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

`<app-child>`에 `skipSelf`를 사용하면, 인젝터는 `<app-root>`의 `ElementInjector` 부터 `AnimalService`를 탐색하기 때문에, 고래 <code>🐳</code> 값을 찾을 수 있습니다.

### `host`, `viewProviders`

<!--
If you just use `host` for the injection of `AnimalService`, the result is dog <code>🐶</code> because the injector finds the `AnimalService` in the `<app-child>` `<#VIEW>` itself.
The `Child` configures the `viewProviders` so that the dog emoji is provided as `AnimalService` value.
You can also see `host` the `inject()`:

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ]
})
export class Child {
  animal = inject(AnimalService, { host: true })
}
```

`host: true` causes the injector to look until it encounters the edge of the `<#VIEW>`.

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    inject(AnimalService, {host: true}=>"🐶")> <!- host stops search here ->
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

Add a `viewProviders` array with a third animal, hedgehog <code>🦔</code>, to the `app.ts` `@Component()` metadata:

```typescript
@Component({
  selector: 'app-root',
  templateUrl: './app.html',
  styleUrls: [ './app.css' ],
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🦔' } },
  ],
})
```

Next, add `skipSelf` along with `host` to the `inject()` for the `AnimalService` injection in `child.ts`.
Here are `host` and `skipSelf` in the `animal` property initialization:

```typescript
export class Child {
  animal = inject(AnimalService, {host: true, skipSelf: true});
}
```

<!- TODO: This requires a rework. It seems not well explained what `viewProviders`/`injectors` is here
  and how `host` works.
 ->

When `host` and `skipSelf` were applied to the `FlowerService`, which is in the `providers` array, the result was `null` because `skipSelf` starts its search in the `<app-child>` injector, but `host` stops searching at `<#VIEW>` —where there is no `FlowerService`
In the logical tree, you can see that the `FlowerService` is visible in `<app-child>`, not its `<#VIEW>`.

However, the `AnimalService`, which is provided in the `App` `viewProviders` array, is visible.

The logical tree representation shows why this is:

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW @Provide(AnimalService="🦔")
  @Inject(AnimalService, @Optional)=>"🦔">

<!- ^^skipSelf starts here,  host stops here^^ ->
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    inject(AnimalService, {skipSelf:true, host: true, optional: true})=>"🦔">
    <!- Add skipSelf ^^->
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

`skipSelf`, causes the injector to start its search for the `AnimalService` at the `<app-root>`, not the `<app-child>`, where the request originates, and `host` stops the search at the `<app-root>` `<#VIEW>`.
Since `AnimalService` is provided by way of the `viewProviders` array, the injector finds hedgehog <code>🦔</code> in the `<#VIEW>`.
-->

`AnimalService`를 주입할 때 `host`를 사용하면 인젝터가 `<app-child>`의 `<#VIEW>`부터 의존성 객체를 찾기 때문에 강아지 <code>🐶</code> 값을 찾습니다.
이 값은 `Child`의 `viewProviders`에 등록되어 있으며, `host`는 `inject()`를 실행할 때 사용합니다:

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

`app.ts` 파일 `@Component()` 메타데이터의 `viewProviders` 배열에 세번째 동물로 고슴도치 <code>🦔</code>를 추가해 봅시다:

다음에는 `child.ts` 파일에서 `inject()`를 실행해서 `AnimalService`를 주입할 때 `host`와 함께 `skipSelf`를 추가해 봅시다.
`animal` 프로퍼티를 초기화할 때 `host`와 `skipSelf`를 사용하면 이렇습니다:

```typescript
export class Child {
  animal = inject(AnimalService, {host: true, skipSelf: true});
}
```

`providers` 배열에 `FlowerService`를 등록했지만 `host`와 `skipSelf`를 사용하면 `null`이 반환되는 이유는, `skipSelf`를 사용했기 때문에 `<app-child>` 인젝터를 건너뛰지만, `host`를 사용했기 때문에 해당 계층의 `<#VIEW>`에서 탐색을 멈추기 때문입니다.
논리 트리로 보면 `<app-child>`에서는 `FlowerService`에 접근할 수 있지만 `<app-child>`의 `<#VIEW>`는 그렇지 않습니다.

하지만, `AnimalService`는 `App`의 `viewProviders` 배열에 등록되었기 때문에 접근할 수 있습니다.

논리 트리로 표현하면 이렇습니다:

```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`를 사용하면 인젝터는 `<app-child>`가 아니라 `<app-root>`에서부터 `AnimalService`를 탐색하고, `host`를 사용하면 `<app-root>`의 `<#VIEW>`에서 탐색을 종료합니다.
결국 `AnimalService`는 `viewProviders` 배열에 등록되어 있기 때문에 `<#VIEW>`에서 접근할 수 있는 의존성 객체의 값은 고슴도치 <code>🦔</code>가 됩니다.

## 예제: `ElementInject` 사용 사례

여러 상황을 고려하면서 프로바이더를 다양하게 구성해 봅시다.

### 시나리오: 서비스 분리

<!--
Architectural reasons may lead you to restrict access to a service to the application domain where it belongs.
For example, consider we build a `VillainsList` that displays a list of villains.
It gets those villains from a `VillainsService`.

If you provide `VillainsService` in the root `AppModule`, it will make `VillainsService` visible everywhere in the application.
If you later modify the `VillainsService`, you could break something in other components that started depending on this service by accident.

Instead, you should provide the `VillainsService` in the `providers` metadata of the `VillainsList` like this:

```typescript
@Component({
  selector: 'app-villains-list',
  templateUrl: './villains-list.html',
  providers: [VillainsService],
})
export class VillainsList {}
```

By providing `VillainsService` in the `VillainsList` metadata and nowhere else, the service becomes available only in the `VillainsList` and its subcomponent tree.

`VillainsService` is a singleton with respect to `VillainsList` because that is where it is declared.
As long as `VillainsList` does not get destroyed it will be the same instance of `VillainsService` but if there are multiple instances of `VillainsList`, then each instance of `VillainsList` will have its own instance of `VillainsService`.
-->

설계 측면에서 특정 서비스를 애플리케이션의 영역에서 분리해야 하는 경우가 있습니다.
빌런의 목록을 표시하는 `VillainsList`를 예로 들어 봅시다.
빌런 목록은 `VillainsService`에서 가져옵니다.

이때 `VillainsService`를 `AppModule`에 등록하면, `VillainsService`는 애플리케이션 전체 범위에서 자유롭게 접근할 수 있습니다.
그래서 이후에 `VillainsService`를 수정하면 다른 컴포넌트에서 문제가 발생할 수 있습니다.

대신, `VillainService`를 `VillainsList`의 `providers`에 등록하는 방법을 사용할 수도 있습니다:

```typescript
@Component({
  selector: 'app-villains-list',
  templateUrl: './villains-list.html',
  providers: [VillainsService],
})
export class VillainsList {}
```

`VillainsService`를 `VillainsList`에 등록하면 이제 이 컴포넌트와 자식 컴포넌트가 아닌 곳에서는 `VillainsService`에 접근할 수 없습니다.

`VillainService`는 이 서비스가 등록된 `VillainsList`의 기준에서 싱글턴으로 동작합니다.
그래서 `VillainsList`가 종료되지 않는 한 `VillainService`는 동일한 인스턴스가 유지되지만, `VillainsList`의 인스턴스가 여러 개가 되면 개별 컴포넌트 인스턴스마다 `VilalinService`의 인스턴스가 생성됩니다.

### 시나리오: 세션 여러 개 유지하기

<!--
Many applications allow users to work on several open tasks at the same time.
For example, in a tax preparation application, the preparer could be working on several tax returns, switching from one to the other throughout the day.

To demonstrate that scenario, imagine a `HeroList` that displays a list of super heroes.

To open a hero's tax return, the preparer clicks on a hero name, which opens a component for editing that return.
Each selected hero tax return opens in its own component and multiple returns can be open at the same time.

Each tax return component has the following characteristics:

- Is its own tax return editing session
- Can change a tax return without affecting a return in another component
- Has the ability to save the changes to its tax return or cancel them

Suppose that the `HeroTaxReturnEditor` had logic to manage and restore changes.
That would be a straightforward task for a hero tax return.
In the real world, with a rich tax return data model, the change management would be tricky.
You could delegate that management to a helper service, as this example does.

The `HeroTaxReturnService` caches a single `HeroTaxReturn`, tracks changes to that return, and can save or restore it.
It also delegates to the application-wide singleton `HeroService`, which it gets by injection.

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

Here is the `HeroTaxReturnEditor` that makes use of `HeroTaxReturnService`.

```typescript
import {Component, effect, inject, 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 HeroTaxReturnEditor {
  message = '';

close = output<void>();

taxReturn = input.required<HeroTaxReturn>();

private heroTaxReturnService = inject(HeroTaxReturnService);

constructor() {
    effect(() => {
      this.heroTaxReturnService.taxReturn = this.taxReturn();
    });
  }

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

The _tax-return-to-edit_ arrives by way of the `taxReturn` signal input.
An `effect` initializes the component's own instance of the `HeroTaxReturnService` with the incoming return whenever the input changes.
The service's getter always returns what the service says is the current state of the hero.
The component also asks the service to save and restore this tax return.

This won't work if the service is an application-wide singleton.
Every component would share the same service instance, and each component would overwrite the tax return that belonged to another hero.

To prevent this, configure the component-level injector of `HeroTaxReturnEditor` to provide the service, using the `providers` property in the component metadata.

```typescript
providers: [HeroTaxReturnService];
```

The `HeroTaxReturnEditor` has its own provider of the `HeroTaxReturnService`.
Recall that every component _instance_ has its own injector.
Providing the service at the component level ensures that _every_ instance of the component gets a private instance of the service. This makes sure that no tax return gets overwritten.

HELPFUL: The rest of the scenario code relies on other Angular features and techniques that you can learn about elsewhere in the documentation.
-->

대부분의 애플리케이션은 보통 동시에 여러 작업을 처리합니다.
세금 신고 애플리케이션이라면, 신고 담당자는 하루 종일 여러 작업을 전환하면서 세금 신고서를 동시에 작업할 수도 있습니다.

이와 비슷하게, 슈퍼 히어로 목록을 표시하는 `HeroList`를 생각해 봅시다.

목록에서 히어로의 이름을 클릭하면 히어로의 세금 신고서가 표시되고 편집할 수 있는 컴포넌트가 열립니다.
그러면 각 히어로의 세금 신고서는 동시에 각각의 컴포넌트로 열립니다.

이때 개별 컴포넌트는 이런 특징이 있습니다:

- 독립적인 편집 세션을 유지합니다.
- 다른 컴포넌트에 영향을 주지 않고 세금 신고서를 수정할 수 있습니다.
- 변경사항을 저장하거나 취소합니다.

`HeroTaxReturnEditor`에 변경사항을 관리하고 복원하는 로직이 있다고 합시다.
히어로의 세금 신고서를 편집하는 화면이라면 간단한 작업입니다.
하지만 실제 운영되는 애플리케이션이라면 복잡한 데이터 모델을 사용하기 때문에 변경사항을 관리하는 것이 까다로워질 수 있습니다.
이런 경우 관리 로직은 헬퍼 서비스로 분리하는 것이 좋습니다.

`HeroTaxReturnService`는 개별 `HeroTaxReturn`을 캐싱하고 변경사항을 추적하며, 변경한 내용을 저장하거나 복원할 수 있습니다.
이 작업은 애플리케이션 전역에 싱글턴으로 존재하는 `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();
  }
}
```

`HeroTaxReturnService`를 활용하는 `HeroTaxReturnEditor` 코드는 이렇습니다.

```typescript
import {Component, effect, inject, input, output} from '@angular/core';
import {HeroTaxReturn} from './hero';
import {HeroTaxReturnService} from './hero-tax-return.service';

close = output<void>();

taxReturn = input.required<HeroTaxReturn>();

private heroTaxReturnService = inject(HeroTaxReturnService);

constructor() {
    effect(() => {
      this.heroTaxReturnService.taxReturn = this.taxReturn();
    });
  }

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

수정하려는 세금 신고서는 `taxReturn` 시그널 입력 프로퍼티로 전달됩니다.
입력값이 변경될 때마다 `effect`가 전달받은 신고서로 컴포넌트 자체의 `HeroTaxReturnService` 인스턴스를 초기화합니다.
서비스의 게터는 서비스가 관리하는 현재 상태를 반환합니다.
이 컴포넌트는 세금 신고서를 저장하거나 복원할 때도 서비스를 활용합니다.

서비스가 애플리케이션 전역 범위에 싱글턴으로 존재하면 이런 방식은 동작하지 않습니다.
모든 컴포넌트가 서비스 인스턴스 하나를 공유하게 되면, 개별 컴포넌트에서 수정하는 세금 신고서가 다른 히어로의 세금 신고서를 덮어쓰게 될 것입니다.

그래서 이런 경우는 `HeroTaxReturnEditor` 계층에서 `providers` 배열로 서비스 프로바이더를 등록해야 합니다.

```typescript
providers: [HeroTaxReturnService];
```

`HeroTaxReturnEditor`는 `HeroTaxReturnService`를 자체 프로바이더로 등록했습니다.
컴포넌트 인스턴스마다 인젝터가 존재한다는 것을 떠올려 보세요.
컴포넌트 계층에 서비스 프로바이더를 등록하면 _개별_ 컴포넌트 인스턴스마다 독자적인 서비스 인스턴스를 갖게 됩니다.
결국 다른 컴포넌트의 작업을 덮어쓰지 않습니다.

참고: 예제 코드에서 다루지 않은 부분은 다른 문서에서 설명합니다.

### 시나리오: 프로바이더 오버라이드

<!--
Another reason to provide a service again at another level is to substitute a _more specialized_ implementation of that service, deeper in the component tree.

For example, consider a `Car` component that includes tire service information and depends on other services to provide more details about the car.

The root injector, marked as (A), uses _generic_ providers for details about `CarService` and `EngineService`.

1. `Car` component (A). Component (A) displays tire service data about a car and specifies generic services to provide more information about the car.

2. Child component (B). Component (B) defines its own, _specialized_ providers for `CarService` and `EngineService` that have special capabilities suitable for what's going on in component (B).

3. Child component (C) as a child of Component (B). Component (C) defines its own, even _more specialized_ provider for `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
```

Behind the scenes, each component sets up its own injector with zero, one, or more providers defined for that component itself.

When you resolve an instance of `Car` at the deepest component (C), its injector produces:

- An instance of `Car` resolved by injector (C)
- An `Engine` resolved by injector (B)
- Its `Tires` resolved by the root injector (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
```
-->

서비스 프로바이더를 다른 계층에 다시 등록하는 경우가 있는데, 컴포넌트 트리 안쪽에서 서비스의 구현체를 _더 특화된_ 로직으로 대체하는 경우가 있습니다.

예를 들어, 타이어 서비스를 포함해서 여러 서비스를 활용하는 `Car` 컴포넌트가 있다고 합시다.

그리고 최상위 인젝터를 (A)라고 하고 `CarService`, `EngineService`와 같은 서비스가 있다고 합시다.

1. `Car` 컴포넌트 (A). 컴포넌트 (A)는 타이어 서비스의 데이터를 표시하고, 다른 서비스를 활용해서 자동차의 정보를 표시합니다.

2. 자식 컴포넌트 (B). 컴포넌트 (B)에는 컴포넌트 (B)에 특화된 `CarService`와 `EngineService`를 프로바이더로 등록했습니다.

3. 자식 컴포넌트 (C)는 자식 컴포넌트 (B)와 비슷하게 조금 더 특화된 `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
```

내부적으로 컴포넌트는 각각 독립적인 인젝터를 구성하며, 이 컴포넌트 계층에 프로바이더를 자유롭게 구성할 수 있습니다.

그리고 가장 안쪽에 있는 컴포넌트 (C)에서 `Car` 인스턴스를 찾게 되면 인젝터가 이렇게 동작합니다:

- 인젝터 (C)가 `Car` 인스턴스를 생성합니다.
- 인젝터 (B)가 `Engine` 인스턴스를 생성합니다.
- 최상위 인젝터 (A)가 `Tires` 인스턴스를 생성합니다.

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

## 더 알아보기

<!--

-->

# 경량 의존성 주입 토큰을 사용해서 클라이언트 애플리케이션 크기 최적화하기

<!--
This page provides a conceptual overview of a dependency injection technique that is recommended for library developers.
Designing your library with _lightweight injection tokens_ helps optimize the bundle size of client applications that use your library.

You can manage the dependency structure among your components and injectable services to optimize bundle size by using tree-shakable providers.
This normally ensures that if a provided component or service is never actually used by the application, the compiler can remove its code from the bundle.

Due to the way Angular stores injection tokens, it is possible that such an unused component or service can end up in the bundle anyway.
This page describes a dependency injection design pattern that supports proper tree-shaking by using lightweight injection tokens.

The lightweight injection token design pattern is especially important for library developers.
It ensures that when an application uses only some of your library's capabilities, the unused code can be eliminated from the client's application bundle.

When an application uses your library, there might be some services that your library supplies which the client application doesn't use.
In this case, the application developer should expect that service to be tree-shaken, and not contribute to the size of the compiled application.
Because the application developer cannot know about or remedy a tree-shaking problem in the library, it is the responsibility of the library developer to do so.
To prevent the retention of unused components, your library should use the lightweight injection token design pattern.
-->

이 문서에서는 라이브러리에게 권장하는 의존성 주입 기법을 설명합니다.
_경량 주입 토큰(lightweight injection tokens)_ 을 사용하여 라이브러리를 설계하면, 이 라이브러리를 사용하는 클라이언트 애플리케이션의 빌드 결과물 크기를 최적화하는 데에도 도움이 됩니다.

트리 셰이킹 프로바이더를 사용하면 컴포넌트와 주입 가능한 서비스 사이의 의존성 구조를 관리하여 빌드 결과물의 크기를 최적화할 수 있습니다.
이렇게 하면 애플리케이션에서 실제로 사용되지 않는 컴포넌트나 서비스는 컴파일러가 코드를 빌드할 때 빌드 결과물에 포함되지 않습니다.

의존성 토큰을 관리하는 방식에 따라 사용하지 않는 컴포넌트나 서비스가 빌드 결과물에 포함되는지가 달라집니다.
이 문서에서는 경량 의존성 주입 토큰을 활용해서 트리 셰이킹을 지원하는 의존성 주입 설계 패턴을 다룹니다.

경량 의존성 주입 토큰 디자인 패턴은 라이브러리 개발자에게 특히 유용합니다.
이 패턴을 활용하면 애플리케이션이 라이브러리 기능 중 일부만 사용하는 경우, 사용하지 않는 코드는 클라이언트 애플리케이션의 빌드 결과물에서 제거할 수 있습니다.

애플리케이션이 라이브러리를 활용할 때, 라이브러리가 제공하는 서비스 중에서 클라이언트 애플리케이션이 사용하지 않는 서비스가 있을 수 있습니다.
이 경우, 애플리케이션 개발자는 해당 서비스가 트리 셰이킹되어 최종 컴파일된 애플리케이션에 영향을 미치지 않을 것을 기대합니다.
애플리케이션 개발자는 라이브러리의 트리 셰이킹 문제를 알거나 직접 해결할 수 없기 때문에, 이를 처리하는 것은 라이브러리 개발자의 몫입니다.
사용하지 않는 구성요소가 빌드 결과물에 포함되지 않도록 하려면, 라이브러리에서 경량 의존성 주입 토큰 디자인 패턴을 활용하면 됩니다.

## 토큰이 유지되는 경우

<!--
To better explain the condition under which token retention occurs, consider a library that provides a library-card component.
This component contains a body and can contain an optional header:

```html
<lib-card>
  <lib-header>…</lib-header>
</lib-card>
```

In a likely implementation, the `<lib-card>` component uses `contentChild` or `contentChildren` to get `<lib-header>` and `<lib-body>`, as in the following:

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

Because `<lib-header>` is optional, the element can appear in the template in its minimal form, `<lib-card />`.
In this case, `<lib-header>` is not used and you would expect it to be tree-shaken, but that is not what happens.
This is because `LibCard` actually contains two references to the `LibHeader`:

```ts
readonly header = contentChild(LibHeader);
```

- One of these references is in the _type position_-- that is, it specifies `LibHeader` as a type: `readonly header: Signal<LibHeader|undefined>`.
- The other reference is in the _value position_-- that is, `LibHeader` is the value passed into the `contentChild` function: `contentChild(LibHeader)`.

The compiler handles token references in these positions differently:

- The compiler erases _type position_ references after conversion from TypeScript, so they have no impact on tree-shaking.
- The compiler must keep _value position_ references at runtime, which **prevents** the component from being tree-shaken.

In the example, the compiler retains the `LibHeader` token that occurs in the value position.
This prevents the referenced component from being tree-shaken, even if the application does not actually use `<lib-header>` anywhere.
If `LibHeader` 's code, template, and styles combine to become too large, including it unnecessarily can significantly increase the size of the client application.
-->

토큰이 유지되는 경우를 설명하기 위해, 카드 컴포넌트(library-card)를 제공하는 라이브러리를 생각해 봅시다.
이 컴포넌트는 바디를 가지며 헤더는 선택적으로 가질 수 있습니다:

```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>`는 사용되지 않으며, 트리 셰이킹이 될 것으로 예상하겠지만, 실제로는 그렇지 않습니다.
`LibCard`가 실제로는 `LibHeader`를 두 번 참조하기 때문입니다:

```ts
readonly header = contentChild(LibHeader);
```

- 하나는 _타입 역할(type position)_ 로 참조합니다. `readonly header: Signal<LibHeader|undefined>`처럼 `LibHeader`를 타입으로 지정하는 경우입니다.
- 다른 하나는 _값 역할(value position)_ 로 참조합니다. `contentChild(LibHeader)`처럼 `LibHeader`를 `contentChild` 함수에 값으로 전달하는 경우입니다.

컴파일러는 이런 토큰을 역할에 따라 다르게 처리합니다.

- _타입 역할_ 참조는 컴파일러가 TypeScript 코드를 변환하면서 제거됩니다. 트리 셰이킹에 영향을 미치지 않습니다.
- _값 역할_ 참조는 실행 시점에 필요합니다. 그래서 트리 셰이킹이 동작해도 코드에 **남습니다.**

예제 코드에서 `LibHeader` 토큰은 값 역할로 사용되었기 때문에 컴파일 이후에도 코드에 남습니다.
그러면 애플리케이션 어디에서도 `<lib-header>`를 사용하지 않더라도 이 컴포넌트는 트리 셰이킹되지 않습니다.
`LibHeader`의 코드, 템플릿, 스타일 파일의 크기가 크다면, 클라이언트 애플리케이션의 빌드 결과물 크기에도 영향을 주게 됩니다.

## 경량 의존성 주입 토큰은 언제 사용해야 할까요?

<!--
The tree-shaking problem arises when a component is used as an injection token.
There are two cases when that can happen:

- The token is used in the value position of a [content query](guide/components/queries#content-queries).
- The token is used with the `inject` function.

In the following example, both uses of the `CustomOther` token cause retention of `CustomOther`, preventing it from being tree-shaken when it is not used:

```ts
{highlight: [[2],[4]]}
class App {
  private readonly other = inject(CustomOther, {optional: true});

readonly header = contentChild(CustomOther);
}
```

Although tokens used only as type specifiers are removed when converted to JavaScript, all tokens used for dependency injection are needed at runtime.
When using `inject(CustomOther)`, `CustomOther` is passed as a value argument.
The token is now in a value position, which causes the tree-shaker to keep the reference.

HELPFUL: Libraries should use [tree-shakable providers](guide/di/defining-dependency-providers) for all services, providing dependencies at the root level rather than in components or modules.
-->

컴포넌트 자체가 의존성 주입 토큰으로 사용되면 트리 셰이킹 문제가 발생할 수 있습니다.
문제가 발생하는 경우는 두 가지입니다:

- 토큰이 [컨텐츠 쿼리](guide/components/queries#content-queries) 자리에 값 역할로 사용된 경우
- 토큰이 `inject` 함수와 사용된 경우

아래 예제처럼 `OtherComponent`를 사용하면 트리 셰이킹되지 않고 빌드 결과물에 남습니다:

```ts
{highlight: [[2],[4]]}
class App {
  private readonly other = inject(CustomOther, {optional: true});

readonly header = contentChild(CustomOther);
}
```

타입 지정으로만 사용되는 토큰은 TypeScript 코드를 JavaScript로 변환할 때 제거되지만, 의존성 주입에 사용되는 모든 토큰은 실행 시점에도 필요합니다.
`inject(CustomOther)`라는 코드에서 `CustomOther`는 변수 인자로 사용되었습니다.
그래서 이 토큰은 값 역할로 사용되었기 때문에 트리 셰이킹이 동작해도 코드에 남습니다.

참고: 라이브러리가 서비스를 제공할 때는 반드시 [트리 셰이킹이 가능한 프로바이더](guide/di/defining-dependency-providers)를 사용해야 하며, 의존성 객체도 컴포넌트나 모듈 계층이 아니라 최상위 계층에 등록해야 합니다.

## 경량 의존성 토큰 사용하기

<!--
The lightweight injection token design pattern consists of using a small abstract class as an injection token, and providing the actual implementation at a later stage.
The abstract class is retained, not tree-shaken, but it is small and has no material impact on the application size.

The following example shows how this works for the `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);
}
```

In this example, the `LibCard` implementation no longer refers to `LibHeader` in either the type position or the value position.
This lets full tree-shaking of `LibHeader` take place.
The `LibHeaderToken` is retained, but it is only a class declaration, with no concrete implementation.
It is small and does not materially impact the application size when retained after compilation.

Instead, `LibHeader` itself implements the abstract `LibHeaderToken` class.
You can safely use that token as the provider in the component definition, allowing Angular to correctly inject the concrete type.

To summarize, the lightweight injection token pattern consists of the following:

1. A lightweight injection token that is represented as an abstract class.
2. A component definition that implements the abstract class.
3. Injection of the lightweight pattern, using `contentChild` or `contentChildren`.
4. A provider in the implementation of the lightweight injection token which associates the lightweight injection token with the implementation.
-->

경량 의존성 토큰 디자인 패턴은 작은 추상 클래스를 의존성 토큰으로 사용하고, 실제 구현체는 나중에 제공하는 방식입니다.
그러면 추상 클래스는 트리 셰이킹되지 않고 남더라도, 작기 때문에 애플리케이션 빌드 결과물 크기에는 거의 영향을 주지 않습니다.

아래 예제에서 `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`를 타입으로도, 값으로도 사용하지 않습니다.
따라서 `LibHeader`는 완전하게 트리 셰이킹이 가능합니다.
그 대신 `LibHeaderToken`이 클래스 선언부에 사용되어 코드에 남지만, 구현체가 없이 단순한 클래스 선언일 뿐입니다.
이 토큰의 크기는 아주 작기 때문에 컴파일 후에도 애플리케이션 크기에 거의 영향을 주지 않습니다.

대신, `LibHeaderToken` 추상 클래스의 구현체는 `LibHeader` 가 됩니다.
컴포넌트를 정의할 때 프로바이더에 `LibHeaderToken`을 등록하면 Angular가 구현체를 올바르게 의존성으로 주입합니다.

요약하자면, 경량 의존성 토큰 패턴은 다음과 같이 구성됩니다:

1. 경량 의존성 토큰 - 추상 클래스로 표현합니다
2. 컴포넌트 정의 - 추상 클래스를 구현합니다.
3. 경량 토큰 주입 - `contentChild`나 `contentChildren`을 사용해 의존성으로 주입합니다.
4. 프로바이더 - 경량 의존성 토큰과 구현체를 연결합니다.

### 경량 의존성 토큰은 API를 정의할 때 사용하세요.

<!--
A component that injects a lightweight injection token might need to invoke a method in the injected class.
The token is now an abstract class. Since the injectable component implements that class, you must also declare an abstract method in the abstract lightweight injection token class.
The implementation of the method, with all its code overhead, resides in the injectable component that can be tree-shaken.
This lets the parent communicate with the child, if it is present, in a type-safe manner.

For example, the `LibCard` now queries `LibHeaderToken` rather than `LibHeader`.
The following example shows how the pattern lets `LibCard` communicate with the `LibHeader` without actually referring to `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();
    }
  }
}
```

In this example, the parent queries the token to get the child component, and stores the resulting component reference if it is present.
Before calling a method in the child, the parent component checks to see if the child component is present.
If the child component has been tree-shaken, there is no runtime reference to it, and no call to its method.
-->

경량 의존성 토큰을 주입하는 컴포넌트는 주입된 클래스의 메서드를 호출해야 할 수 있습니다.
이 경우 토큰은 추상 클래스입니다.
그리고 의존성으로 주입할 수 있는 컴포넌트가 추상 클래스를 구현하기 때문에, 경량 의존성 토큰의 추상 클래스에도 추상 메서드를 선언해야 합니다.
메서드의 실제 구현 코드와 그 외에 코드는 모두 트리 셰이킹 대상이 되는 컴포넌트에 존재합니다.
이를 통해 부모 컴포넌트는 자식 컴포넌트가 존재하는 경우 타입으로 보호되는 방식으로 호출할 수 있습니다.

이제 `LibCard`에서 `LibHeader` 대신 `LibHeaderToken`을 쿼리해 봅시다.
아래 예제는 `LibCard`가 실제 `LibHeader`를 직접 호출하지 않아도 `LibHeader`를 활용할 수 있습니다:

```ts
{highlight: [[2],[7],[11],[19]]}
abstract class LibHeaderToken {
  abstract doSomething(): void;
}

@Component({
  selector: 'lib-card',
})
class LibCard implements AfterContentInit {
  readonly header = contentChild(LibHeaderToken);

ngAfterContentInit(): void {
    if (this.header() !== undefined) {
      this.header()!.doSomething();
    }
  }
}
```

이 예제에서 부모 컴포넌트는 토큰을 통해 자식 컴포넌트를 참조하고, 자식 컴포넌트가 존재하면 해당 컴포넌트의 참조를 저장해 둡니다.
그리고 부모 컴포넌트가 자식 컴포넌트의 메서드를 호출하기 전에 자식 컴포넌트가 존재하는지 확인하며, 자식 컴포넌트가 트리 셰이킹되어 사라지면, 실행 시점에 존재하지 않기 때문에 자식 컴포넌트의 메서드를 실행하지 않습니다.

### 경량 의존성 토큰의 이름 지정하기

<!--
Lightweight injection tokens are only useful with components.
The [Angular Style Guide](style-guide) suggests that you name components without the suffix `Component`.
The example `LibHeader` follows this convention.

You should maintain the relationship between the component and its token while still distinguishing between them.
The recommended style is to use the component base name with the suffix `Token` to name your lightweight injection tokens: `LibHeaderToken`.
-->

경량 의존성 토큰은 컴포넌트에서만 유용합니다.
[Angular 스타일 가이드](style-guide)에 따르면, 컴포넌트는 "Component"라는 접미사를 사용하지 않는 것을 권장합니다.
"LibHeader"와 같은 식입니다.

컴포넌트는 토큰과 관련되어 있지만 둘을 명확하게 구분해야 합니다.
따라서, `LibHeaderToken`과 같이 `Token` 접미사를 붙이는 것을 권장합니다.

# Angular 시그널과 RxJS 연동

`@angular/core/rxjs-interop` 패키지는 RxJS와 Angular 시그널을 연동하는 API를 제공합니다.

## `toSignal`로 RxJS 옵저버블에서 시그널 생성하기

<!--
Use the `toSignal` function to create a signal which tracks the value of an Observable. It behaves similarly to the `async` pipe in templates, but is more flexible and can be used anywhere in an application.

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

Like the `async` pipe, `toSignal` subscribes to the Observable immediately, which may trigger side effects. The subscription created by `toSignal` automatically unsubscribes from the given Observable when the component or service which calls `toSignal` is destroyed.

IMPORTANT: `toSignal` creates a subscription. You should avoid calling it repeatedly for the same Observable, and instead reuse the signal it returns.
-->

`toSignal` 함수를 사용하면 옵저버블의 값을 추적하는 시그널을 생성할 수 있습니다.
템플릿의 `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);

// `counterObservable`의 값을 나타내는 `Signal`을 가져옵니다.
  counter = toSignal(this.counterObservable, {initialValue: 0});
}
```

`async` 파이프와 마찬가지로 `toSignal`은 옵저버블을 즉시 구독하므로 사이드 이펙트가 발생할 수 있습니다.
`toSignal`이 생성한 구독은 `toSignal`을 호출한 컴포넌트나 서비스가 종료될 때 해당 옵저버블에서 자동으로 해제됩니다.

중요: `toSignal`은 구독을 생성합니다.
같은 옵저버블에 대해 반복해서 호출하지 말고, 반환된 시그널을 재사용하세요.

### 의존성 주입 컨텍스트

`toSignal`은 기본적으로 컴포넌트나 서비스가 생성되는 시점과 같은 [의존성 주입 컨텍스트](guide/di/dependency-injection-context)에서 실행해야 합니다.
의존성 주입 컨텍스트를 사용할 수 없다면 사용할 `Injector`를 직접 지정할 수 있습니다.

### 초기값

옵저버블은 구독할 때 동기적으로 값을 생성하지 않을 수 있지만, 시그널은 항상 현재 값이 필요합니다.
`toSignal` 시그널의 "초기값"은 몇 가지 방법으로 처리할 수 있습니다.

#### `initialValue` 옵션

위 예제처럼 `initialValue` 옵션에 옵저버블이 첫 번째 값을 방출하기 전까지 시그널이 반환할 값을 지정할 수 있습니다.

#### `undefined` 초기값

`initialValue`를 지정하지 않으면 생성된 시그널은 옵저버블이 값을 방출할 때까지 `undefined`를 반환합니다.
이는 `null`을 반환하는 `async` 파이프의 동작과 비슷합니다.

#### `requireSync` 옵션

<!--
Some Observables are guaranteed to emit synchronously, such as `BehaviorSubject`. In those cases, you can specify the `requireSync: true` option.

When `requireSync` is `true`, `toSignal` enforces that the Observable emits synchronously on subscription. This guarantees that the signal always has a value, and no `undefined` type or initial value is required.
-->

`BehaviorSubject`처럼 동기적으로 값을 방출하는 것이 보장되는 옵저버블도 있습니다.
이 경우에는 `requireSync: true` 옵션을 지정할 수 있습니다.

`requireSync`가 `true`이면 `toSignal`은 옵저버블이 구독 시점에 동기적으로 값을 방출하도록 강제합니다.
따라서 시그널에 항상 값이 있다는 것이 보장되며, `undefined` 타입이나 초기값이 필요하지 않습니다.

### `manualCleanup`

<!--
By default, `toSignal` automatically unsubscribes from the Observable when the component or service that creates it is destroyed.

To override this behavior, you can pass the `manualCleanup` option. You can use this setting for Observables that complete themselves naturally.
-->

기본적으로 `toSignal`은 자신을 생성한 컴포넌트나 서비스가 종료될 때 옵저버블 구독을 자동으로 해제합니다.

이 동작을 변경하려면 `manualCleanup` 옵션을 전달하면 됩니다.
스스로 완료되는 옵저버블에 이 설정을 사용할 수 있습니다.

#### 커스텀 동등성 비교

<!--
Some observables may emit values that are **equals** even though they differ by reference or minor detail. The `equal` option lets you define a **custom equal function** to determine when two consecutive values should be considered the same.

When two emitted values are considered equal, the resulting signal **does not update**. This prevents redundant computations, DOM updates, or effects from re-running unnecessarily.

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

일부 옵저버블은 참조나 세부 내용이 달라도 **동등한** 값을 방출할 수 있습니다.
`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, 22 중 무작위 값
  );

// 온도가 변경될 때만 갱신합니다.
  temperature = toSignal(this.temperature$, {
    initialValue: {temperature: 20},
    equal: (prev, curr) => prev.temperature === curr.temperature,
  });
}
```

### 오류와 완료

<!--
If an Observable used in `toSignal` produces an error, that error is thrown when the signal is read.

If an Observable used in `toSignal` completes, the signal continues to return the most recently emitted value before completion.
-->

`toSignal`에 사용한 옵저버블에서 오류가 발생하면 시그널을 읽을 때 해당 오류가 발생합니다.

`toSignal`에 사용한 옵저버블이 완료되면 시그널은 완료 직전에 마지막으로 방출한 값을 계속 반환합니다.

## `toObservable`로 시그널에서 RxJS 옵저버블 생성하기

<!--
Use the `toObservable` utility to create an `Observable` which tracks the value of a signal. The signal's value is monitored with an `effect` which emits the value to the Observable when it changes.

```ts
import {Component, signal, Signal, inject} from '@angular/core';
import {toObservable} from '@angular/core/rxjs-interop';
import {switchMap} from 'rxjs';

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

As the `query` signal changes, the `query$` Observable emits the latest query and triggers a new HTTP request.
-->

`toObservable` 유틸리티를 사용하면 시그널의 값을 추적하는 `Observable`을 생성할 수 있습니다.
시그널의 값은 `effect`로 감시하며, 값이 변경되면 옵저버블로 방출합니다.

```ts
import {Component, signal, Signal, inject} from '@angular/core';
import {toObservable} from '@angular/core/rxjs-interop';
import {switchMap} from 'rxjs';

@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` 시그널이 변경되면 `query$` 옵저버블은 최신 쿼리를 방출하고 새로운 HTTP 요청을 실행합니다.

### 의존성 주입 컨텍스트 {#ko-injection-context-to-observable}

`toObservable`은 기본적으로 컴포넌트나 서비스가 생성되는 시점과 같은 [의존성 주입 컨텍스트](guide/di/dependency-injection-context)에서 실행해야 합니다.
의존성 주입 컨텍스트를 사용할 수 없다면 사용할 `Injector`를 직접 지정할 수 있습니다.

### `toObservable`의 실행 시점

<!--
`toObservable` uses an effect to track the value of the signal in a `ReplaySubject`. On subscription, the first value (if available) may be emitted synchronously, and all subsequent values will be asynchronous.

Unlike Observables, signals never provide a synchronous notification of changes. Even if you update a signal's value multiple times, `toObservable` will only emit the value after the signal stabilizes.

```ts
const obs$ = toObservable(mySignal);
obs$.subscribe((value) => console.log(value));

mySignal.set(1);
mySignal.set(2);
mySignal.set(3);
```

Here, only the last value (3) will be logged.
-->

`toObservable`은 이펙트 함수를 사용해서 시그널의 값을 `ReplaySubject`에 반영합니다.
구독할 때 첫 번째 값이 있다면 동기적으로 방출될 수 있지만, 그 이후의 값은 모두 비동기적으로 방출됩니다.

옵저버블과 달리 시그널은 값의 변경을 동기적으로 알리지 않습니다.
시그널의 값을 여러 번 갱신하더라도 `toObservable`은 시그널이 안정화된 후에만 값을 방출합니다.

```ts
const obs$ = toObservable(mySignal);
obs$.subscribe((value) => console.log(value));

mySignal.set(1);
mySignal.set(2);
mySignal.set(3);
```

이 예제에서는 마지막 값인 3만 로그에 출력됩니다.

## 비동기 데이터에 `rxResource` 사용하기

<!--
Angular's [`resource` function](/guide/signals/resource) gives you a way to incorporate async data into your application's signal-based code. Building on top of this pattern, `rxResource` lets you define a resource where the source of your data is defined in terms of an RxJS `Observable`. Instead of accepting a `loader` function, `rxResource` accepts a `stream` function that returns an RxJS `Observable`.

```typescript
import {Component, inject, input} 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),
  });
}
```

The `stream` property accepts a factory function for an RxJS `Observable`. This factory function is passed the resource's `params` value and returns an `Observable`. The resource calls this factory function every time the `params` computation produces a new value. See [Resource loaders](/guide/signals/resource#resource-loaders) for more details on the parameters passed to the factory function.

In all other ways, `rxResource` behaves like and provides the same APIs as `resource` for specifying parameters, reading values, checking loading state, and examining errors.
-->

Angular의 [`resource` 함수](/guide/signals/resource)를 사용하면 애플리케이션의 시그널 기반 코드에 비동기 데이터를 통합할 수 있습니다.
이 패턴을 바탕으로 하는 `rxResource`는 데이터 소스를 RxJS `Observable`로 정의하는 리소스를 만들 수 있습니다.
`rxResource`는 `loader` 함수 대신 RxJS `Observable`을 반환하는 `stream` 함수를 사용합니다.

```typescript
import {Component, inject, input} from '@angular/core';
import {rxResource} from '@angular/core/rxjs-interop';

@Component(/* ... */)
export class UserProfile {
  // 이 컴포넌트는 RxJS Observable을 통해 데이터를 제공하는 서비스를 사용합니다.
  private userData = inject(MyUserDataClient);

protected userId = input<string>();

private userResource = rxResource({
    params: () => ({userId: this.userId()}),

// `stream` 프로퍼티는 데이터 스트림을 RxJS Observable로
    // 반환하는 팩토리 함수를 받습니다.
    stream: ({params}) => this.userData.load(params.userId),
  });
}
```

`stream` 프로퍼티는 RxJS `Observable`을 생성하는 팩토리 함수를 받습니다.
이 팩토리 함수는 리소스의 `params` 값을 전달받고 `Observable`을 반환합니다.
리소스는 `params` 계산에서 새 값이 나올 때마다 이 팩토리 함수를 호출합니다.
팩토리 함수에 전달되는 인자에 대한 자세한 내용은 [리소스 로더](/guide/signals/resource#resource-loaders)를 참고하세요.

그 밖의 동작과 API는 `resource`와 같습니다.
`rxResource`는 인자 지정, 값 읽기, 로딩 상태 확인, 오류 확인을 같은 방식으로 지원합니다.

`stream`이 반환하는 `Observable`은 완료되기 전에 반드시 값이나 오류를 전달해야 합니다. 그렇지 않으면 발생하는 문제와 해결 방법은 [`NG0991`](/errors/NG0991)을 참고하세요.

# 컴포넌트와 디렉티브 출력의 RxJS 연동

<!--
TIP: This guide assumes you're familiar with [component and directive outputs](guide/components/outputs).

The `@angular/core/rxjs-interop` package offers two APIs related to component and directive outputs.
-->

팁: 이 문서는 [컴포넌트와 디렉티브 출력](guide/components/outputs)을 알고 있다고 가정합니다.

`@angular/core/rxjs-interop` 패키지는 컴포넌트와 디렉티브 출력에 관련된 API를 두 가지 제공합니다.

## RxJS 옵저버블을 기반으로 출력 생성하기

<!--
The `outputFromObservable` lets you create a component or directive output that emits based on an RxJS observable:

```ts
{highlight:[9]}
import {Directive} from '@angular/core';
import {outputFromObservable} from '@angular/core/rxjs-interop';
import {Observable} from 'rxjs';

@Directive(/* ... */)
class Draggable {
  pointerMoves$: Observable<PointerMovements> = listenToPointerMoves();

// Whenever `pointerMoves$` emits, the `pointerMove` event fires.
  pointerMove = outputFromObservable(this.pointerMoves$);
}
```

The `outputFromObservable` function has special meaning to the Angular compiler. **You may only call `outputFromObservable` in component and directive property initializers.**

When you `subscribe` to the output, Angular automatically forwards the subscription to the underlying observable. Angular stops forwarding values when the component or directive is destroyed.

HELPFUL: Consider using `output()` directly if you can emit values imperatively.
-->

`outputFromObservable`을 사용하면 RxJS 옵저버블을 기반으로 값을 방출하는 컴포넌트 또는 디렉티브 출력을 생성할 수 있습니다:

```ts
{highlight:[9]}
import {Directive} from '@angular/core';
import {outputFromObservable} from '@angular/core/rxjs-interop';
import {Observable} from 'rxjs';

@Directive(/* ... */)
class Draggable {
  pointerMoves$: Observable<PointerMovements> = listenToPointerMoves();

// `pointerMoves$`가 값을 방출할 때마다 `pointerMove` 이벤트가 발생합니다.
  pointerMove = outputFromObservable(this.pointerMoves$);
}
```

Angular 컴파일러는 `outputFromObservable` 함수를 특별하게 처리합니다.
**`outputFromObservable`은 컴포넌트와 디렉티브의 프로퍼티를 초기화하는 곳에서만 호출할 수 있습니다.**

출력을 `subscribe`하면 Angular는 해당 구독을 내부 옵저버블에 자동으로 전달합니다.
컴포넌트나 디렉티브가 종료되면 Angular는 값 전달을 중단합니다.

도움말: 명령형 코드로 값을 방출할 수 있다면 `output()`을 직접 사용하는 방법을 고려하세요.

## 컴포넌트나 디렉티브 출력으로 RxJS 옵저버블 생성하기

<!--
The `outputToObservable` function lets you create an RxJS observable from a component output.

```ts
{highlight:[11]}
import {outputToObservable} from '@angular/core/rxjs-interop';
import {Component, output} from '@angular/core';

@Component(/*...*/)
class CustomSlider {
    valueChange = output<number>();
}

// Instance reference to `CustomSlider`.
const slider: CustomSlider = createSlider();

outputToObservable(slider.valueChange) // Observable<number>
    .pipe(...)
    .subscribe(...);
```

HELPFUL: Consider using the `subscribe` method on `OutputRef` directly if it meets your needs.
-->

`outputToObservable` 함수를 사용하면 컴포넌트 출력으로 RxJS 옵저버블을 생성할 수 있습니다.

```ts
{highlight:[11]}
import {outputToObservable} from '@angular/core/rxjs-interop';
import {Component, output} from '@angular/core';

@Component(/*...*/)
class CustomSlider {
    valueChange = output<number>();
}

// `CustomSlider` 인스턴스 참조입니다.
const slider: CustomSlider = createSlider();

outputToObservable(slider.valueChange) // Observable<number>
    .pipe(...)
    .subscribe(...);
```

도움말: 요구사항을 충족한다면 `OutputRef`의 `subscribe` 메서드를 직접 사용하는 방법을 고려하세요.

# `HttpClient` 설정하기

Angular v21 이상에서는 별도 설정 없이 `HttpClient`를 주입할 수 있습니다.

## 의존성 주입으로 `HttpClient` 제공하기

<!--
You can use the `provideHttpClient` helper function to configure the default HTTP feature set or add features in the application `providers` in `app.config.ts`.

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(/* add features here, such as withInterceptors(...) */)],
};
```

If your app is using NgModule-based bootstrap instead, you can include `provideHttpClient` in the providers of your app's NgModule to configure the default HTTP feature set or add features:

```ts
@NgModule({
  providers: [provideHttpClient(/* add features here, such as withInterceptors(...) */)],
  // ... other application configuration
})
export class AppModule {}
```

You can then inject the `HttpClient` service as a dependency of your components, services, or other classes:

```ts
@Service()
export class ConfigService {
  private http = inject(HttpClient);
  // This service can now make HTTP requests via `this.http`.
}
```
-->

`app.config.ts`의 애플리케이션 `providers`에서 `provideHttpClient` 헬퍼 함수를 사용하면 기본 HTTP 기능을 설정하거나 추가 기능을 활성화할 수 있습니다.

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(/* withInterceptors(...) 등의 기능을 여기에 추가합니다. */)],
};
```

NgModule 기반으로 부트스트랩하는 애플리케이션이라면 애플리케이션 NgModule의 프로바이더에 `provideHttpClient`를 포함하여 기본 HTTP 기능을 설정하거나 추가 기능을 활성화할 수 있습니다:

```ts
@NgModule({
  providers: [provideHttpClient(/* withInterceptors(...) 등의 기능을 여기에 추가합니다. */)],
  // ... 애플리케이션의 다른 설정
})
export class AppModule {}
```

이제 컴포넌트, 서비스, 다른 클래스에 `HttpClient` 서비스를 의존성으로 주입할 수 있습니다:

```ts
@Service()
export class ConfigService {
  private http = inject(HttpClient);
  // 이제 이 서비스에서 `this.http`로 HTTP 요청을 보낼 수 있습니다.
}
```

## `HttpClient` 기능 설정하기

`provideHttpClient`에는 클라이언트의 여러 기능을 활성화하거나 설정하는 선택적 기능 설정 목록을 전달할 수 있습니다.
이 섹션에서는 선택적으로 사용할 수 있는 기능과 사용 방법을 알아봅니다.

### `withXhr`

<!--
```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withXhr())],
};
```

By default, `HttpClient` uses the [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) API to make requests. The `withXhr` feature switches the client to use the [`XMLHttpRequest`](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest) API instead.

`fetch` is a more modern API and is available in a few environments where `XMLHttpRequest` is not supported. It does have a few limitations, such as not producing upload progress events.
-->

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withXhr())],
};
```

`HttpClient`는 기본적으로 [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) API로 요청을 보냅니다.
`withXhr` 기능을 사용하면 대신 [`XMLHttpRequest`](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest) API를 사용하도록 바꿀 수 있습니다.

`fetch`는 더 현대적인 API이며, `XMLHttpRequest`를 지원하지 않는 일부 환경에서도 사용할 수 있습니다.
다만 업로드 진행 상황 이벤트를 제공하지 않는 등의 제약이 있습니다.

서버에서의 XHR 사용은 **사용 중단 권고** 상태이며 Angular 23에서 제거할 예정입니다. 기반 라이브러리인 `xhr2`는 리다이렉트를 안전하게 처리하지 못합니다. 교차 출처 리다이렉트에 `Authorization` 헤더를 전달할 수 있으며, 리다이렉트 루프로 서비스 거부(DoS) 공격을 받을 수 있습니다. SSR 애플리케이션에서는 기본 `fetch` 백엔드를 사용하세요.

### `withInterceptors(...)`

`withInterceptors`는 `HttpClient`가 보내는 요청을 처리할 인터셉터 함수 목록을 설정합니다.
자세한 내용은 [인터셉터 가이드](guide/http/interceptors)를 참고하세요.

### `withInterceptorsFromDi()`

<!--
`withInterceptorsFromDi` includes the older style of class-based interceptors in the `HttpClient` configuration. See the [interceptor guide](guide/http/interceptors) for more information.

HELPFUL: Functional interceptors (through `withInterceptors`) have more predictable ordering and we recommend them over DI-based interceptors.
-->

`withInterceptorsFromDi`는 이전 방식인 클래스 기반 인터셉터를 `HttpClient` 설정에 포함합니다.
자세한 내용은 [인터셉터 가이드](guide/http/interceptors)를 참고하세요.

참고: `withInterceptors`를 사용하는 함수형 인터셉터는 실행 순서를 더 쉽게 예측할 수 있으므로, DI 기반 인터셉터보다 함수형 인터셉터를 사용하는 것을 권장합니다.

### `withRequestsMadeViaParent()`

<!--
By default, when you configure `HttpClient` using `provideHttpClient` within a given injector, this configuration overrides any configuration for `HttpClient` which may be present in the parent injector.

When you add `withRequestsMadeViaParent()`, `HttpClient` is configured to instead pass requests up to the `HttpClient` instance in the parent injector, once they've passed through any configured interceptors at this level. This is useful if you want to _add_ interceptors in a child injector while still sending the request through the parent injector's interceptors.

CRITICAL: You must configure an instance of `HttpClient` above the current injector, or this option is not valid and you'll get a runtime error when you try to use it.
-->

특정 인젝터에서 `provideHttpClient`로 `HttpClient`를 설정하면, 기본적으로 상위 인젝터에 있는 `HttpClient` 설정보다 이 설정이 우선합니다.

`withRequestsMadeViaParent()`를 추가하면 현재 수준에 설정한 인터셉터를 모두 거친 뒤 요청을 상위 인젝터의 `HttpClient` 인스턴스로 전달하도록 바뀝니다.
상위 인젝터의 인터셉터를 거쳐 요청을 보내면서 하위 인젝터에 인터셉터를 _추가_ 하고 싶은 경우에 유용합니다.

중요: 현재 인젝터보다 상위에 `HttpClient` 인스턴스를 반드시 설정해야 합니다.
그렇지 않으면 이 옵션은 유효하지 않으며, 사용하려고 할 때 런타임 오류가 발생합니다.

### `withJsonpSupport()`

JSONP는 크로스 사이트 스크립팅(XSS) 취약점을 유발할 수 있으므로 `withJsonpSupport`, `HttpClientJsonpModule`, `HttpClient`의 `.jsonp()` 메서드는 사용 중단을 권고합니다. 대신 [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS)를 사용하는 표준 HTTP 요청을 사용하세요.
<!--
Including `withJsonpSupport` enables the `.jsonp()` method on `HttpClient`, which makes a GET request via the [JSONP convention](https://en.wikipedia.org/wiki/JSONP) for cross-domain loading of data.

HELPFUL: Prefer using [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) to make cross-domain requests instead of JSONP when possible.
-->

`withJsonpSupport`를 포함하면 `HttpClient`의 `.jsonp()` 메서드를 사용할 수 있습니다.
이 메서드는 다른 도메인의 데이터를 불러오기 위해 [JSONP 규약](https://en.wikipedia.org/wiki/JSONP)에 따라 GET 요청을 보냅니다.

참고: 다른 도메인으로 요청을 보낼 때는 가능하면 JSONP 대신 [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS)를 사용하는 것이 좋습니다.

### `withXsrfConfiguration(...)`

이 옵션을 포함하면 `HttpClient`에 내장된 XSRF 보안 기능을 커스터마이징할 수 있습니다.
자세한 내용은 [보안 가이드](best-practices/security)를 참고하세요.

### `withNoXsrfProtection()`

이 옵션을 포함하면 `HttpClient`에 내장된 XSRF 보안 기능을 비활성화합니다.
자세한 내용은 [보안 가이드](best-practices/security)를 참고하세요.

## `HttpClientModule` 기반 설정

<!--
Some applications may configure `HttpClient` using the older API based on NgModules.

This table lists the NgModules available from `@angular/common/http` and how they relate to the provider configuration functions above.

| **NgModule**                            | `provideHttpClient()` equivalent                         |
| --------------------------------------- | -------------------------------------------------------- |
| `HttpClientModule`                      | `provideHttpClient(withInterceptorsFromDi(), withXhr())` |
| `HttpClientJsonpModule` (deprecated)    | `withJsonpSupport()` (deprecated)                        |
| `HttpClientXsrfModule.withOptions(...)` | `withXsrfConfiguration(...)`                             |
| `HttpClientXsrfModule.disable()`        | `withNoXsrfProtection()`                                 |

NOTE: `HttpClientModule` and `HttpClientXsrfModule` are also deprecated. Use `provideHttpClient` with the corresponding features instead.
When `HttpClientModule` is present in multiple injectors, the behavior of interceptors is poorly defined and depends on the exact options and provider/import ordering.

Prefer `provideHttpClient` for multi-injector configurations, as it has more stable behavior. See the `withRequestsMadeViaParent` feature above.

-->

일부 애플리케이션은 NgModule 기반의 이전 API로 `HttpClient`를 설정할 수 있습니다.

다음 표는 `@angular/common/http`에서 제공하는 NgModule과 앞에서 살펴본 프로바이더 설정 함수의 대응 관계입니다.

| **NgModule**                             | 대응하는 `provideHttpClient()` 설정                      |
| ---------------------------------------- | -------------------------------------------------------- |
| `HttpClientModule`                       | `provideHttpClient(withInterceptorsFromDi(), withXhr())` |
| `HttpClientJsonpModule` (사용 중단 권고) | `withJsonpSupport()` (사용 중단 권고)                    |
| `HttpClientXsrfModule.withOptions(...)`  | `withXsrfConfiguration(...)`                             |
| `HttpClientXsrfModule.disable()`         | `withNoXsrfProtection()`                                 |

참고: `HttpClientModule`과 `HttpClientXsrfModule`도 사용 중단을 권고합니다. 대신 `provideHttpClient`에 대응하는 기능을 함께 설정하세요.
여러 인젝터에 `HttpClientModule`이 있으면 인터셉터의 동작이 명확하게 정해지지 않으며, 구체적인 옵션과 프로바이더 및 모듈 로드 순서에 따라 달라집니다.

인젝터를 여러 개 사용하는 구성에서는 동작이 더 안정적인 `provideHttpClient`를 사용하는 것이 좋습니다.
앞에서 설명한 `withRequestsMadeViaParent` 기능을 참고하세요.

# HTTP 요청 보내기

<!--
`HttpClient` has methods corresponding to the different HTTP verbs used to make requests, both to load data and to apply mutations on the server. Each method returns an [RxJS `Observable`](https://rxjs.dev/guide/observable) which, when subscribed, sends the request and then emits the results when the server responds.

NOTE: `Observable`s created by `HttpClient` may be subscribed any number of times and will make a new backend request for each subscription.

Through an options object passed to the request method, various properties of the request and the returned response type can be adjusted.
-->

`HttpClient`는 데이터를 불러오거나 서버 상태를 변경하는 데 사용하는 각 HTTP 메서드에 대응하는 메서드를 제공합니다.
각 메서드는 [RxJS `Observable`](https://rxjs.dev/guide/observable)을 반환합니다.
이 옵저버블을 구독하면 요청을 보내고, 서버가 응답하면 결과를 전달합니다.

참고: `HttpClient`가 생성한 `Observable`은 여러 번 구독할 수 있으며, 구독할 때마다 백엔드로 새 요청을 보냅니다.

요청 메서드에 전달하는 옵션 객체로 요청의 여러 프로퍼티와 반환할 응답 타입을 조정할 수 있습니다.

## JSON 데이터 가져오기

<!--
Fetching data from a backend often requires making a GET request using the [`HttpClient.get()`](api/common/http/HttpClient#get) method. This method takes two arguments: the string endpoint URL from which to fetch, and an _optional options_ object to configure the request.

For example, to fetch configuration data from a hypothetical API using the `HttpClient.get()` method:

```ts
http.get<Config>('/api/config').subscribe((config) => {
  // process the configuration.
});
```

Note the generic type argument which specifies that the data returned by the server will be of type `Config`. This argument is optional, and if you omit it, the returned data will have type `Object`.

TIP: When dealing with data of uncertain structure and potential `undefined` or `null` values, consider using the `unknown` type instead of `Object` as the response type.

CRITICAL: The generic type of request methods is a type **assertion** about the data returned by the server. `HttpClient` does not verify that the actual return data matches this type.
-->

백엔드에서 데이터를 가져올 때는 [`HttpClient.get()`](api/common/http/HttpClient#get) 메서드로 GET 요청을 보내는 경우가 많습니다.
이 메서드는 데이터를 가져올 엔드포인트 URL 문자열과 요청을 설정하는 _선택적 옵션_ 객체를 인자로 받습니다.

예를 들어 `HttpClient.get()`으로 가상의 API에서 설정 데이터를 가져오려면 다음과 같이 작성합니다:

```ts
http.get<Config>('/api/config').subscribe((config) => {
  // 설정을 처리합니다.
});
```

서버가 반환할 데이터의 타입을 `Config`로 지정하는 제네릭 타입 인자를 확인해 보세요.
이 인자는 선택 사항이며, 생략하면 반환 데이터의 타입은 `Object`가 됩니다.

팁: 데이터 구조가 확실하지 않고 값이 `undefined` 또는 `null`일 가능성이 있다면, 응답 타입으로 `Object` 대신 `unknown`을 사용하는 것도 고려해 보세요.

중요: 요청 메서드의 제네릭 타입은 서버가 반환하는 데이터에 대한 타입 **단언**입니다.
`HttpClient`는 실제 반환 데이터가 지정한 타입과 일치하는지 검증하지 않습니다.

## 다른 형식의 데이터 가져오기

<!--
By default, `HttpClient` assumes that servers will return JSON data. When interacting with a non-JSON API, you can tell `HttpClient` what response type to expect when making the request. This is done with the `responseType` option.

| **`responseType` value** | **Returned response type**                                                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `'json'` (default)       | JSON data of the given generic type                                                                                                       |
| `'text'`                 | string data                                                                                                                               |
| `'arraybuffer'`          | [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) containing the raw response bytes |
| `'blob'`                 | [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob) instance                                                                        |

For example, you can ask `HttpClient` to download the raw bytes of a `.jpeg` image into an `ArrayBuffer`:

```ts
http.get('/images/dog.jpg', {responseType: 'arraybuffer'}).subscribe((buffer) => {
  console.log('The image is ' + buffer.byteLength + ' bytes large');
});
```
Because the value of `responseType` affects the type returned by `HttpClient`, it must have a literal type and not a `string` type.

This happens automatically if the options object passed to the request method is a literal object, but if you're extracting the request options out into a variable or helper method you might need to explicitly specify it as a literal, such as `responseType: 'text' as const`.

-->

`HttpClient`는 기본적으로 서버가 JSON 데이터를 반환한다고 가정합니다.
JSON이 아닌 API와 통신할 때는 요청을 보내면서 `responseType` 옵션으로 예상 응답 형식을 지정할 수 있습니다.

| **`responseType` 값** | **반환하는 응답 타입**                                                                                                            |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `'json'`(기본값)      | 지정한 제네릭 타입의 JSON 데이터                                                                                                  |
| `'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`의 반환 타입에 영향을 미치므로, `string` 타입이 아니라 리터럴 타입이어야 합니다.

요청 메서드에 객체 리터럴로 옵션을 전달하면 자동으로 처리됩니다.
하지만 요청 옵션을 별도 변수나 헬퍼 메서드로 분리한다면 `responseType: 'text' as const`처럼 리터럴 타입을 명시해야 할 수 있습니다.

## 서버 상태 변경하기

<!--
Server APIs that perform mutations often require making POST requests with a request body specifying the new state or the change to be made.

The [`HttpClient.post()`](api/common/http/HttpClient#post) method behaves similarly to `get()`, and accepts an additional `body` argument before its options:

```ts
http.post<Config>('/api/config', newConfig).subscribe((config) => {
  console.log('Updated config:', config);
});
```

Many different types of values can be provided as the request's `body`, and `HttpClient` will serialize them accordingly:

| **`body` type**                                                                                                               | **Serialized as**                                    |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| string                                                                                                                        | Plain text                                           |
| number, boolean, array, or plain object                                                                                       | JSON                                                 |
| [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)                       | raw data from the buffer                             |
| [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob)                                                                     | raw data with the `Blob`'s content type              |
| [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData)                                                             | `multipart/form-data` encoded data                   |
| [`HttpParams`](api/common/http/HttpParams) or [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) | `application/x-www-form-urlencoded` formatted string |

IMPORTANT: Remember to `.subscribe()` to mutation request `Observable`s in order to actually fire the request.
-->

서버 상태를 변경하는 API는 새로운 상태나 적용할 변경 사항을 요청 본문에 담아 POST 요청으로 보내야 하는 경우가 많습니다.

[`HttpClient.post()`](api/common/http/HttpClient#post) 메서드는 `get()`과 비슷하게 동작하며, 옵션 앞에 추가로 `body` 인자를 받습니다:

```ts
http.post<Config>('/api/config', newConfig).subscribe((config) => {
  console.log('Updated config:', config);
});
```

요청의 `body`에는 여러 타입의 값을 전달할 수 있으며, `HttpClient`가 타입에 맞춰 직렬화합니다:

| **`body` 타입**                                                                                                                 | **직렬화 형식**                                   |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| 문자열                                                                                                                          | 일반 텍스트                                       |
| 숫자, 불리언, 배열, 일반 객체                                                                                                   | JSON                                              |
| [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)                         | 버퍼의 원시 데이터                                |
| [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob)                                                                       | `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` 형식의 문자열 |

중요: 변경 요청을 실제로 보내려면 요청 `Observable`에서 `.subscribe()`를 실행해야 한다는 점을 기억하세요.

## URL 파라미터 설정하기

<!--
Specify request parameters that should be included in the request URL using the `params` option.

Passing an object literal is the simplest way of configuring URL parameters:

```ts
http
  .get('/api/config', {
    params: {filter: 'all'},
  })
  .subscribe((config) => {
    // ...
  });
```

Alternatively, pass an instance of `HttpParams` if you need more control over the construction or serialization of the parameters.

IMPORTANT: Instances of `HttpParams` are _immutable_ and cannot be directly changed. Instead, mutation methods such as `append()` return a new instance of `HttpParams` with the mutation applied.

```ts
const baseParams = new HttpParams().set('filter', 'all');

http
  .get('/api/config', {
    params: baseParams.set('details', 'enabled'),
  })
  .subscribe((config) => {
    // ...
  });
```

You can instantiate `HttpParams` with a custom `HttpParameterCodec` that determines how `HttpClient` will encode the parameters into the URL.
-->

요청 URL에 포함할 파라미터는 `params` 옵션으로 지정합니다.

객체 리터럴을 전달하는 것이 가장 간단한 방법입니다:

```ts
http
  .get('/api/config', {
    params: {filter: 'all'},
  })
  .subscribe((config) => {
    // ...
  });
```

파라미터를 구성하거나 직렬화하는 방식을 더 세밀하게 제어해야 한다면 `HttpParams` 인스턴스를 전달할 수도 있습니다.

중요: `HttpParams` 인스턴스는 _불변_ 이므로 직접 변경할 수 없습니다.
대신 `append()` 같은 변경 메서드가 변경 사항을 적용한 새 `HttpParams` 인스턴스를 반환합니다.

```ts
const baseParams = new HttpParams().set('filter', 'all');

http
  .get('/api/config', {
    params: baseParams.set('details', 'enabled'),
  })
  .subscribe((config) => {
    // ...
  });
```

커스텀 `HttpParameterCodec`을 지정해서 `HttpParams` 인스턴스를 생성하면 `HttpClient`가 URL 파라미터를 인코딩하는 방식을 정할 수 있습니다.

### 파라미터 인코딩 커스터마이징하기

<!--
By default, `HttpParams` uses the built-in [`HttpUrlEncodingCodec`](api/common/http/HttpUrlEncodingCodec) to encode and decode parameter keys and values.

You can provide your own implementation of [`HttpParameterCodec`](api/common/http/HttpParameterCodec) to customize how encoding and decoding are applied.

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

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

## 요청 헤더 설정하기

<!--
Specify request headers that should be included in the request using the `headers` option.

Passing an object literal is the simplest way of configuring request headers:

```ts
http
  .get('/api/config', {
    headers: {
      'X-Debug-Level': 'verbose',
    },
  })
  .subscribe((config) => {
    // ...
  });
```

Alternatively, pass an instance of `HttpHeaders` if you need more control over the construction of headers.

IMPORTANT: Instances of `HttpHeaders` are _immutable_ and cannot be directly changed. Instead, mutation methods such as `append()` return a new instance of `HttpHeaders` with the mutation applied.

```ts
const baseHeaders = new HttpHeaders().set('X-Debug-Level', 'minimal');

http
  .get<Config>('/api/config', {
    headers: baseHeaders.set('X-Debug-Level', 'verbose'),
  })
  .subscribe((config) => {
    // ...
  });
```
-->

요청에 포함할 헤더는 `headers` 옵션으로 지정합니다.

객체 리터럴을 전달하는 것이 가장 간단한 방법입니다:

```ts
http
  .get('/api/config', {
    headers: {
      'X-Debug-Level': 'verbose',
    },
  })
  .subscribe((config) => {
    // ...
  });
```

헤더를 구성하는 방식을 더 세밀하게 제어해야 한다면 `HttpHeaders` 인스턴스를 전달할 수도 있습니다.

중요: `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) => {
    // ...
  });
```

## 서버 응답 이벤트 다루기

<!--
For convenience, `HttpClient` by default returns an `Observable` of the data returned by the server (the response body). Occasionally it's desirable to examine the actual response, for example to retrieve specific response headers.

To access the entire response, set the `observe` option to `'response'`:

```ts
http.get<Config>('/api/config', {observe: 'response'}).subscribe((res) => {
  console.log('Response status:', res.status);
  console.log('Body:', res.body);
});
```
Because the value of `observe` affects the type returned by `HttpClient`, it must have a literal type and not a `string` type.

-->

`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`의 반환 타입에 영향을 미치므로, `string` 타입이 아니라 리터럴 타입이어야 합니다.

요청 메서드에 객체 리터럴로 옵션을 전달하면 자동으로 처리됩니다.
하지만 요청 옵션을 별도 변수나 헬퍼 메서드로 분리한다면 `observe: 'response' as const`처럼 리터럴 타입을 명시해야 할 수 있습니다.

## 진행 상황 이벤트 직접 받기

<!--
In addition to the response body or response object, `HttpClient` can also return a stream of raw _events_ corresponding to specific moments in the request lifecycle. These events include when the request is sent, when the response header is returned, and when the body is complete. These events can also include _progress events_ that report upload and download status for large request or response bodies.

Progress events are disabled by default (as they have a performance cost) but can be enabled with the `reportUploadProgress` and `reportDownloadProgress` options.

NOTE: The default fetch backend of `HttpClient` does not support _upload_ progress events and throws an error if you set `reportUploadProgress`. If your app needs upload progress events, configure `HttpClient` with `withXhr()` in `provideHttpClient(...)`.

To observe the event stream, set the `observe` option to `'events'`:

```ts
http
  .get('/api/download', {
    reportDownloadProgress: true,
    observe: 'events',
  })
  .subscribe((event) => {
    switch (event.type) {
      case HttpEventType.DownloadProgress:
        console.log('Downloaded ' + event.loaded + ' out of ' + event.total + ' bytes');
        break;
      case HttpEventType.Response:
        console.log('Finished downloading!');
        break;
    }
  });
```
Because the value of `observe` affects the type returned by `HttpClient`, it must have a literal type and not a `string` type.

| **`type` value**                 | **Event meaning**                                                                  |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| `HttpEventType.Sent`             | The request has been dispatched to the server                                      |
| `HttpEventType.UploadProgress`   | An `HttpUploadProgressEvent` reporting progress on uploading the request body      |
| `HttpEventType.ResponseHeader`   | The head of the response has been received, including status and headers           |
| `HttpEventType.DownloadProgress` | An `HttpDownloadProgressEvent` reporting progress on downloading the response body |
| `HttpEventType.Response`         | The entire response has been received, including the response body                 |
| `HttpEventType.User`             | A custom event from an HTTP interceptor.                                           |
-->

`HttpClient`는 응답 본문이나 응답 객체뿐 아니라 요청 라이프사이클의 특정 시점에 해당하는 원시 _이벤트_ 스트림도 반환할 수 있습니다.
요청을 보낸 시점, 응답 헤더를 받은 시점, 본문을 모두 받은 시점 등이 여기에 포함됩니다.
큰 요청 본문이나 응답 본문의 업로드 및 다운로드 상태를 알려주는 _진행 상황 이벤트_ 도 포함할 수 있습니다.

진행 상황 이벤트는 성능 비용이 있어 기본적으로 비활성화되어 있지만, `reportUploadProgress`와 `reportDownloadProgress` 옵션으로 활성화할 수 있습니다.

참고: `HttpClient`의 기본 fetch 백엔드는 _업로드_ 진행 상황 이벤트를 지원하지 않으며, `reportUploadProgress`를 설정하면 오류가 발생합니다.
업로드 진행 상황 이벤트가 필요하다면 `provideHttpClient(...)`에 `withXhr()`를 지정해서 `HttpClient`를 설정하세요.

이벤트 스트림을 관찰하려면 `observe` 옵션을 `'events'`로 설정합니다:

```ts
http
  .get('/api/download', {
    reportDownloadProgress: true,
    observe: 'events',
  })
  .subscribe((event) => {
    switch (event.type) {
      case HttpEventType.DownloadProgress:
        console.log('Downloaded ' + event.loaded + ' out of ' + event.total + ' bytes');
        break;
      case HttpEventType.Response:
        console.log('Finished downloading!');
        break;
    }
  });
```
`observe` 값은 `HttpClient`의 반환 타입에 영향을 미치므로, `string` 타입이 아니라 리터럴 타입이어야 합니다.

요청 메서드에 객체 리터럴로 옵션을 전달하면 자동으로 처리됩니다.
하지만 요청 옵션을 별도 변수나 헬퍼 메서드로 분리한다면 `observe: 'events' as const`처럼 리터럴 타입을 명시해야 할 수 있습니다.
이벤트 스트림에서 전달하는 각 `HttpEvent`에는 이벤트의 의미를 구분하는 `type`이 있습니다:

| **`type` 값**                    | **이벤트 의미**                                                   |
| -------------------------------- | ----------------------------------------------------------------- |
| `HttpEventType.Sent`             | 서버로 요청을 보냈음                                              |
| `HttpEventType.UploadProgress`   | 요청 본문 업로드 진행 상황을 알리는 `HttpUploadProgressEvent`     |
| `HttpEventType.ResponseHeader`   | 상태와 헤더를 포함한 응답의 헤더 부분을 받았음                    |
| `HttpEventType.DownloadProgress` | 응답 본문 다운로드 진행 상황을 알리는 `HttpDownloadProgressEvent` |
| `HttpEventType.Response`         | 본문을 포함한 전체 응답을 받았음                                  |
| `HttpEventType.User`             | HTTP 인터셉터의 커스텀 이벤트                                     |

## 요청 실패 처리하기

<!--
There are three ways an HTTP request can fail:

- A network or connection error can prevent the request from reaching the backend server.
- A request didn't respond in time when the timeout option was set.
- The backend can receive the request but fail to process it, and return an error response.

`HttpClient` captures all of the above kinds of errors in an `HttpErrorResponse` which it returns through the `Observable`'s error channel. Network and timeout errors have a `status` code of `0`. For timeouts, the `error` is a `DOMException` named `TimeoutError`; for network errors, it is the error thrown by `fetch` (or a [`ProgressEvent`](https://developer.mozilla.org/docs/Web/API/ProgressEvent) when using `withXhr()`). Backend errors have the failing `status` code returned by the backend, and the error response as the `error`. Inspect the response to identify the error's cause and the appropriate action to handle the error.

The [RxJS library](https://rxjs.dev/) offers several operators which can be useful for error handling.

You can use the `catchError` operator to transform an error response into a value for the UI. This value can tell the UI to display an error page or value, and capture the error's cause if necessary.

Sometimes transient errors such as network interruptions can cause a request to fail unexpectedly, and simply retrying the request will allow it to succeed. RxJS provides several _retry_ operators which automatically re-subscribe to a failed `Observable` under certain conditions. For example, the `retry()` operator will automatically attempt to re-subscribe a specified number of times.
-->

HTTP 요청은 다음 세 가지 방식으로 실패할 수 있습니다:

- 네트워크 또는 연결 오류로 요청이 백엔드 서버에 도달하지 못합니다.
- 타임아웃 옵션을 설정했는데 제한 시간 안에 응답하지 않습니다.
- 백엔드가 요청을 받았지만 처리에 실패해서 오류 응답을 반환합니다.

`HttpClient`는 이런 모든 오류를 `HttpErrorResponse`에 담아 `Observable`의 오류 채널로 전달합니다.
네트워크 및 타임아웃 오류의 `status` 코드는 `0`입니다. 타임아웃이면 `error`는 이름이 `TimeoutError`인 `DOMException`입니다. 네트워크 오류이면 `fetch`가 발생시킨 오류이며, `withXhr()`를 사용하는 경우에는 [`ProgressEvent`](https://developer.mozilla.org/docs/Web/API/ProgressEvent)입니다.
백엔드 오류는 백엔드가 반환한 실패 상태 코드를 `status`로, 오류 응답을 `error`로 제공합니다.
응답을 확인해서 오류 원인과 적절한 처리 방법을 판단하세요.

[RxJS 라이브러리](https://rxjs.dev/)에는 오류 처리에 유용한 연산자가 여러 개 있습니다.

`catchError` 연산자를 사용하면 오류 응답을 UI에서 사용할 값으로 변환할 수 있습니다.
이 값으로 UI에 오류 페이지나 값을 표시하도록 알리고, 필요하면 오류 원인도 기록할 수 있습니다.

때로는 네트워크 중단 같은 일시적 오류로 요청이 예상치 못하게 실패하며, 요청을 다시 보내기만 해도 성공할 수 있습니다.
RxJS는 특정 조건에서 실패한 `Observable`을 자동으로 다시 구독하는 여러 _재시도_ 연산자를 제공합니다.
예를 들어 `retry()` 연산자는 지정한 횟수만큼 자동으로 재구독을 시도합니다.

### 타임아웃

<!--
To set a timeout for a request, you can set the `timeout` option to a number of milliseconds along with other request options. If the backend request does not complete within the specified time, the request will be aborted and an error will be emitted.

NOTE: The timeout will only apply to the backend HTTP request itself. It is not a timeout for the entire request handling chain. Therefore, this option is not affected by any delay introduced by 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.
    },
  });
```
-->

요청에 타임아웃을 설정하려면 다른 요청 옵션과 함께 `timeout` 옵션에 밀리초 단위의 숫자를 지정합니다.
백엔드 요청이 지정한 시간 안에 완료되지 않으면 요청을 취소하고 오류를 전달합니다.

참고: 타임아웃은 백엔드 HTTP 요청 자체에만 적용되며, 전체 요청 처리 체인에 적용되는 것은 아닙니다.
따라서 인터셉터에서 발생한 지연은 이 옵션에 영향을 미치지 않습니다.

```ts
http
  .get('/api/config', {
    timeout: 3000,
  })
  .subscribe({
    next: (config) => {
      console.log('Config fetched successfully:', config);
    },
    error: (err) => {
      // 요청 시간이 초과되면 에러가 전달됩니다.
    },
  });
```

## 고급 fetch 옵션

Angular의 `HttpClient`는 성능과 사용자 경험을 개선할 수 있는 고급 fetch API 옵션을 지원합니다.
이 옵션은 기본 백엔드인 fetch 백엔드를 사용할 때 적용할 수 있습니다.

### fetch 옵션

다음 옵션을 사용하면 fetch 백엔드의 요청 동작을 세밀하게 제어할 수 있습니다.

#### 연결 유지

<!--
The `keepalive` option allows a request to outlive the page that initiated it. This is particularly useful for analytics or logging requests that need to complete even if the user navigates away from the page.

```ts
http
  .post('/api/analytics', analyticsData, {
    keepalive: true,
  })
  .subscribe();
```
-->

`keepalive` 옵션을 사용하면 요청을 시작한 페이지가 종료된 뒤에도 요청을 유지할 수 있습니다.
사용자가 페이지를 떠나더라도 완료해야 하는 분석 정보나 로그 전송 요청에 특히 유용합니다.

```ts
http
  .post('/api/analytics', analyticsData, {
    keepalive: true,
  })
  .subscribe();
```

#### HTTP 캐싱 제어

<!--
The `cache` option controls how the request interacts with the browser's HTTP cache, which can significantly improve performance for repeated requests.

```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) => {
    // ...
  });
```
-->

`cache` 옵션은 요청이 브라우저의 HTTP 캐시를 사용하는 방식을 제어하며, 반복 요청의 성능을 크게 개선할 수 있습니다.

```ts
// 최신 여부와 관계없이 캐시된 응답을 사용합니다.
http
  .get('/api/config', {
    cache: 'force-cache',
  })
  .subscribe((config) => {
    // ...
  });

// 캐시를 건너뛰고 항상 네트워크에서 가져옵니다.
http
  .get('/api/live-data', {
    cache: 'no-cache',
  })
  .subscribe((data) => {
    // ...
  });

// 캐시된 응답만 사용하며, 캐시에 없으면 실패합니다.
http
  .get('/api/static-data', {
    cache: 'only-if-cached',
  })
  .subscribe((data) => {
    // ...
  });
```

#### Core Web Vitals를 위한 요청 우선순위

<!--
The `priority` option allows you to indicate the relative importance of a request, helping browsers optimize resource loading for better Core Web Vitals scores.

```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) => {
    // ...
  });
```

Available `priority` values:

- `'high'`: High priority, loaded early (e.g., critical user data, above-the-fold content)
- `'low'`: Low priority, loaded when resources are available (e.g., analytics, prefetch data)
- `'auto'`: Browser determines priority based on request context (default)

TIP: Use `priority: 'high'` for requests that affect Largest Contentful Paint (LCP) and `priority: 'low'` for requests that don't impact initial user experience.
-->

`priority` 옵션은 요청의 상대적 중요도를 나타냅니다.
브라우저가 리소스 로드를 최적화해서 Core Web Vitals 점수를 개선하는 데 도움이 됩니다.

```ts
// 중요한 리소스에는 높은 우선순위를 지정합니다.
http
  .get('/api/user-profile', {
    priority: 'high',
  })
  .subscribe((profile) => {
    // ...
  });

// 덜 중요한 리소스에는 낮은 우선순위를 지정합니다.
http
  .get('/api/recommendations', {
    priority: 'low',
  })
  .subscribe((recommendations) => {
    // ...
  });

// 자동 우선순위(기본값)에서는 브라우저가 결정합니다.
http
  .get('/api/settings', {
    priority: 'auto',
  })
  .subscribe((settings) => {
    // ...
  });
```

사용할 수 있는 `priority` 값은 다음과 같습니다:

- `'high'`: 우선순위가 높으며 먼저 로드합니다.
  예를 들어 중요한 사용자 데이터나 스크롤하지 않아도 보이는 콘텐츠에 사용합니다.
- `'low'`: 우선순위가 낮으며 리소스에 여유가 있을 때 로드합니다.
  예를 들어 분석 정보나 미리 가져올 데이터에 사용합니다.
- `'auto'`: 요청 상황에 따라 브라우저가 우선순위를 정합니다.
  기본값입니다.

팁: Largest Contentful Paint(LCP)에 영향을 미치는 요청에는 `priority: 'high'`를, 초기 사용자 경험에 영향을 주지 않는 요청에는 `priority: 'low'`를 사용하세요.

#### 요청 모드

<!--
The `mode` option controls how the request handles cross-origin requests and determines the response type.

```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) => {
    // ...
  });
```

Available `mode` values:

- `'same-origin'`: Only allow same-origin requests, fail for cross-origin requests
- `'cors'`: Allow cross-origin requests with CORS (default)
- `'no-cors'`: Allow simple cross-origin requests without CORS, response is opaque

TIP: In the browser, use `mode: 'same-origin'` for sensitive requests that should never go cross-origin.

IMPORTANT: During SSR on Node.js, `HttpClient` uses Node.js's [Undici-based Fetch implementation](https://nodejs.org/api/globals.html#fetch). [Undici does not enforce browser CORS checks](https://undici.nodejs.org/#cors), so `mode: 'same-origin'` does not restrict server-side requests. Validate user-influenced URLs against an allowlist.
-->

`mode` 옵션은 교차 출처 요청을 처리하는 방식을 제어하고 응답 타입을 결정합니다.

```ts
// 동일 출처 요청만 허용합니다.
http
  .get('/api/local-data', {
    mode: 'same-origin',
  })
  .subscribe((data) => {
    // ...
  });

// CORS를 사용하는 교차 출처 요청입니다.
http
  .get('https://api.external.com/data', {
    mode: 'cors',
  })
  .subscribe((data) => {
    // ...
  });

// 단순 교차 출처 요청에 No-CORS 모드를 사용합니다.
http
  .get('https://external-api.com/public-data', {
    mode: 'no-cors',
  })
  .subscribe((data) => {
    // ...
  });
```

사용할 수 있는 `mode` 값은 다음과 같습니다:

- `'same-origin'`: 동일 출처 요청만 허용하고, 교차 출처 요청은 실패 처리합니다.
- `'cors'`: CORS를 사용하는 교차 출처 요청을 허용합니다.
  기본값입니다.
- `'no-cors'`: CORS 없이 단순 교차 출처 요청을 허용하며, 응답은 불투명한(opaque) 응답이 됩니다.

팁: 브라우저에서 다른 출처로 보내면 안 되는 민감한 요청에는 `mode: 'same-origin'`을 사용하세요.

중요: Node.js의 SSR에서 `HttpClient`는 Node.js의 [Undici 기반 Fetch 구현](https://nodejs.org/api/globals.html#fetch)을 사용합니다. [Undici는 브라우저의 CORS 검사를 강제하지 않으므로](https://undici.nodejs.org/#cors) `mode: 'same-origin'`이 서버 측 요청을 제한하지 않습니다. 사용자 입력의 영향을 받는 URL은 허용 목록과 대조하여 검사하세요.

#### 리다이렉트 처리

<!--
The `redirect` option specifies how to handle redirect responses from the server.

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

Available `redirect` values:

- `'follow'`: Automatically follow redirects (default)
- `'error'`: Treat redirects as errors
- `'manual'`: Don't follow redirects automatically, return redirect response

TIP: Use `redirect: 'manual'` when you need to handle redirects with custom logic.
-->

`redirect` 옵션은 서버의 리다이렉트 응답을 처리하는 방식을 지정합니다.

```ts
// 리다이렉트를 자동으로 따릅니다(기본 동작).
http
  .get('/api/resource', {
    redirect: 'follow',
  })
  .subscribe((data) => {
    // ...
  });

// 자동 리다이렉트를 방지합니다.
http
  .get('/api/resource', {
    redirect: 'manual',
  })
  .subscribe((response) => {
    // 리다이렉트를 직접 처리합니다.
  });

// 리다이렉트를 에러로 처리합니다.
http
  .get('/api/resource', {
    redirect: 'error',
  })
  .subscribe({
    next: (data) => {
      // 성공 응답입니다.
    },
    error: (err) => {
      // 리다이렉트 응답은 이 에러 핸들러를 실행합니다.
    },
  });
```

사용할 수 있는 `redirect` 값은 다음과 같습니다:

- `'follow'`: 리다이렉트를 자동으로 따릅니다.
  기본값입니다.
- `'error'`: 리다이렉트를 오류로 처리합니다.
- `'manual'`: 리다이렉트를 자동으로 따르지 않고 리다이렉트 응답을 반환합니다.

팁: 리다이렉트를 직접 작성한 로직으로 처리해야 한다면 `redirect: 'manual'`을 사용하세요.

#### 인증 정보 처리

<!--
The `credentials` option controls whether cookies, authorization headers, and other credentials are sent with cross-origin requests. This is particularly important for authentication scenarios.

```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: The `withCredentials` option takes precedence over the `credentials` option. If both are specified, `withCredentials: true` will always result in `credentials: 'include'`, regardless of the explicit `credentials` value.

Available `credentials` values:

- `'omit'`: Never send credentials
- `'same-origin'`: Send credentials only for same-origin requests (default)
- `'include'`: Always send credentials, even for cross-origin requests

TIP: Use `credentials: 'include'` when you need to send authentication cookies or headers to a different domain that supports CORS. Avoid mixing `credentials` and `withCredentials` options to prevent confusion.
-->

`credentials` 옵션은 교차 출처 요청에 쿠키, 인증 헤더 등의 인증 정보를 포함할지 제어합니다.
인증을 사용하는 경우에 특히 중요합니다.

```ts
// 교차 출처 요청에 인증 정보를 포함합니다.
http
  .get('https://api.example.com/protected-data', {
    credentials: 'include',
  })
  .subscribe((data) => {
    // ...
  });

// 인증 정보를 보내지 않습니다(교차 출처 요청의 기본 동작).
http
  .get('https://api.example.com/public-data', {
    credentials: 'omit',
  })
  .subscribe((data) => {
    // ...
  });

// 동일 출처 요청에만 인증 정보를 보냅니다.
http
  .get('/api/user-data', {
    credentials: 'same-origin',
  })
  .subscribe((data) => {
    // ...
  });

// withCredentials가 credentials 설정보다 우선합니다.
http
  .get('https://api.example.com/data', {
    credentials: 'omit', // 이 값은 무시됩니다.
    withCredentials: true, // credentials: 'include'로 동작하도록 강제합니다.
  })
  .subscribe((data) => {
    // credentials: 'omit'을 지정했지만 요청에 인증 정보가 포함됩니다.
  });

// 이전 방식도 계속 지원합니다.
http
  .get('https://api.example.com/data', {
    withCredentials: true,
  })
  .subscribe((data) => {
    // credentials: 'include'와 같습니다.
  });
```

중요: `withCredentials` 옵션은 `credentials` 옵션보다 우선합니다.
둘 다 지정하면 명시한 `credentials` 값과 관계없이 `withCredentials: true`가 항상 `credentials: 'include'`로 동작합니다.

사용할 수 있는 `credentials` 값은 다음과 같습니다:

- `'omit'`: 인증 정보를 보내지 않습니다.
- `'same-origin'`: 동일 출처 요청에만 인증 정보를 보냅니다.
  기본값입니다.
- `'include'`: 교차 출처 요청을 포함해서 항상 인증 정보를 보냅니다.

팁: CORS를 지원하는 다른 도메인에 인증 쿠키나 헤더를 보내야 한다면 `credentials: 'include'`를 사용하세요.
혼동을 피하려면 `credentials`와 `withCredentials` 옵션을 함께 사용하지 않는 것이 좋습니다.

중요: Node.js의 SSR에서 `credentials: 'include'`는 들어온 브라우저 요청의 쿠키를 자동으로 전달하지 않습니다. `credentials` 옵션은 직접 추가한 `Cookie`나 `Authorization` 헤더도 제거하지 않습니다. [Undici는 브라우저가 금지하는 일부 헤더를 허용하므로](https://undici.nodejs.org/#forbidden-and-safelisted-header-names), 인증 정보가 담긴 헤더는 신뢰할 수 있는 출처에만 전달하세요.

#### 리퍼러

<!--
The `referrer` option allows you to control what referrer information is sent with the request. This is important for privacy and security considerations.

```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) => {
    // ...
  });
```

The `referrer` option accepts:

- A valid URL string: Sets the specific referrer URL to send
- An empty string `''`: Sends no referrer information
- `'about:client'`: Uses the default referrer (current page URL)

TIP: Use `referrer: ''` for sensitive requests where you don't want to leak the referring page URL.
-->

`referrer` 옵션은 요청에 어떤 리퍼러 정보를 보낼지 제어합니다.
개인정보 보호와 보안 측면에서 중요한 설정입니다.

```ts
// 지정한 리퍼러 URL을 보냅니다.
http
  .get('/api/data', {
    referrer: 'https://example.com/page',
  })
  .subscribe((data) => {
    // ...
  });

// 현재 페이지를 리퍼러로 사용합니다(기본 동작).
http
  .get('/api/analytics', {
    referrer: 'about:client',
  })
  .subscribe((data) => {
    // ...
  });
```

`referrer` 옵션에는 다음 값을 지정할 수 있습니다:

- 유효한 URL 문자열: 전송할 리퍼러 URL을 직접 지정합니다.
- 빈 문자열 `''`: 리퍼러 정보를 보내지 않습니다.
- `'about:client'`: 기본 리퍼러인 현재 페이지 URL을 사용합니다.

팁: 요청을 보낸 페이지의 URL을 노출하고 싶지 않은 민감한 요청에는 `referrer: ''`를 사용하세요.

#### 리퍼러 정책

<!--
The `referrerPolicy` option controls how much referrer information—the URL of the page making the request—is sent along with an HTTP request. This setting affects both privacy and analytics, allowing you to balance data visibility with security considerations.

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

The `referrerPolicy` option accepts:

- `'no-referrer'` Never send the `Referer` header.
- `'no-referrer-when-downgrade'` Sends the referrer for same-origin and secure (HTTPS→HTTPS) requests, but omits it when navigating from a secure to a less secure origin (HTTPS→HTTP).
- `'origin'` Sends only the origin (scheme, host, port) of the referrer, omitting path and query information.
- `'origin-when-cross-origin'` Sends the full URL for same-origin requests, but only the origin for cross-origin requests.
- `'same-origin'` Sends the full URL for same-origin requests and no referrer for cross-origin requests.
- `'strict-origin'` Sends only the origin, and only if the protocol security level is not downgraded (e.g., HTTPS→HTTPS). Omits the referrer on downgrade.
- `'strict-origin-when-cross-origin'` Default browser behavior. Sends the full URL for same-origin requests, the origin for cross-origin requests when not downgraded, and omits the referrer on downgrade.
- `'unsafe-url'` Always sends the full URL (including path and query). This can expose sensitive data and should be used with caution.

TIP: Prefer conservative values such as `'no-referrer'`, `'origin'`, or `'strict-origin-when-cross-origin'` for privacy-sensitive requests.
-->

`referrerPolicy` 옵션은 HTTP 요청과 함께 요청을 보낸 페이지의 URL, 즉 리퍼러 정보를 어느 범위까지 전달할지 제어합니다.
이 설정은 개인정보 보호와 분석에 모두 영향을 미치므로, 데이터 확인 범위와 보안을 고려해서 조정할 수 있습니다.

```ts
// 현재 페이지와 관계없이 리퍼러 정보를 보내지 않습니다.
http
  .get('/api/data', {
    referrerPolicy: 'no-referrer',
  })
  .subscribe();

// 출처만 보냅니다(예: https://example.com).
http
  .get('/api/analytics', {
    referrerPolicy: 'origin',
  })
  .subscribe();
```

`referrerPolicy` 옵션에는 다음 값을 지정할 수 있습니다:

- `'no-referrer'`: `Referer` 헤더를 보내지 않습니다.
- `'no-referrer-when-downgrade'`: 동일 출처 요청과 보안 수준이 유지되는 요청(HTTPS→HTTPS)에는 리퍼러를 보내지만, 보안 수준이 낮아지는 출처로 이동할 때(HTTPS→HTTP)는 보내지 않습니다.
- `'origin'`: 리퍼러의 출처인 스킴, 호스트, 포트만 보내고 경로와 쿼리 정보는 제외합니다.
- `'origin-when-cross-origin'`: 동일 출처 요청에는 전체 URL을 보내고, 교차 출처 요청에는 출처만 보냅니다.
- `'same-origin'`: 동일 출처 요청에는 전체 URL을 보내고, 교차 출처 요청에는 리퍼러를 보내지 않습니다.
- `'strict-origin'`: 프로토콜의 보안 수준이 낮아지지 않을 때만(예: HTTPS→HTTPS) 출처를 보냅니다.
  보안 수준이 낮아지면 리퍼러를 보내지 않습니다.
- `'strict-origin-when-cross-origin'`: 브라우저의 기본 동작입니다.
  동일 출처 요청에는 전체 URL을 보내고, 보안 수준이 낮아지지 않는 교차 출처 요청에는 출처를 보내며, 보안 수준이 낮아지면 리퍼러를 보내지 않습니다.
- `'unsafe-url'`: 경로와 쿼리를 포함한 전체 URL을 항상 보냅니다.
  민감한 데이터가 노출될 수 있으므로 주의해서 사용해야 합니다.

팁: 개인정보 보호가 중요한 요청에는 `'no-referrer'`, `'origin'`, `'strict-origin-when-cross-origin'`처럼 보수적인 값을 사용하는 것이 좋습니다.

#### 무결성

<!--
The `integrity` option allows you to verify that the response hasn't been tampered with by providing a cryptographic hash of the expected content. This is particularly useful for loading scripts or other resources from CDNs.

```ts
// Verify response integrity with SHA-256 hash
http
  .get('/api/script.js', {
    integrity: 'sha256-ABC123...',
    responseType: 'text',
  })
  .subscribe((script) => {
    // Script content is verified against the hash
  });
```

IMPORTANT: The `integrity` option requires an exact match between the response content and the provided hash. If the content doesn't match, the request will fail with a network error.

CRITICAL: During SSR, the Fetch implementation reads the entire response body to verify `integrity` before returning a response, as required by the [Fetch Standard](https://fetch.spec.whatwg.org/#concept-main-fetch). Angular enforces [`maxResponseBodySize`](/guide/ssr#configuring-the-response-body-size-limit) only after Fetch returns a response, so this limit does not constrain the data buffered during integrity verification.

TIP: Use subresource integrity when loading critical resources from external sources to ensure they haven't been modified. Generate hashes using tools like `openssl`.
-->

`integrity` 옵션에 예상 콘텐츠의 암호학적 해시를 지정하면 응답이 변조되지 않았는지 검증할 수 있습니다.
CDN에서 스크립트나 다른 리소스를 불러올 때 특히 유용합니다.

```ts
// SHA-256 해시로 응답 무결성을 검증합니다.
http
  .get('/api/script.js', {
    integrity: 'sha256-ABC123...',
    responseType: 'text',
  })
  .subscribe((script) => {
    // 스크립트 콘텐츠가 해시와 일치하는지 검증합니다.
  });
```

중요: `integrity` 옵션을 사용하면 응답 콘텐츠와 지정한 해시가 정확히 일치해야 합니다.
일치하지 않으면 요청이 네트워크 오류로 실패합니다.

매우 중요: SSR에서 Fetch 구현은 [Fetch 표준](https://fetch.spec.whatwg.org/#concept-main-fetch)에 따라 응답을 반환하기 전에 전체 응답 본문을 읽어 `integrity`를 검증합니다. Angular의 [`maxResponseBodySize`](/guide/ssr#configuring-the-response-body-size-limit)는 Fetch가 응답을 반환한 뒤에만 적용되므로, 무결성 검증 중에 버퍼링하는 데이터 양을 제한하지 못합니다.

팁: 외부에서 중요한 리소스를 불러올 때는 하위 리소스 무결성 검사(subresource integrity)로 변조 여부를 확인하세요.
해시는 `openssl` 같은 도구로 생성할 수 있습니다.

## HTTP `Observable`

<!--
Each request method on `HttpClient` constructs and returns an `Observable` of the requested response type. Understanding how these `Observable`s work is important when using `HttpClient`.

`HttpClient` produces what RxJS calls "cold" `Observable`s, meaning that no actual request happens until the `Observable` is subscribed. Only then is the request actually dispatched to the server. Subscribing to the same `Observable` multiple times will trigger multiple backend requests. Each subscription is independent.

TIP: You can think of `HttpClient` `Observable`s as _blueprints_ for actual server requests.

Once subscribed, unsubscribing will abort the in-progress request. This is very useful if the `Observable` is subscribed via the `async` pipe, as it will automatically cancel the request if the user navigates away from the current page. Additionally, if you use the `Observable` with an RxJS combinator like `switchMap`, this cancellation will clean up any stale requests.

Once the response returns, `Observable`s from `HttpClient` usually complete (although interceptors can influence this).

Because of the automatic completion, there is usually no risk of memory leaks if `HttpClient` subscriptions are not cleaned up. However, as with any async operation, we strongly recommend that you clean up subscriptions when the component using them is destroyed, as the subscription callback may otherwise run and encounter errors when it attempts to interact with the destroyed component.

TIP: Using the `async` pipe or the `toSignal` operation to subscribe to `Observable`s ensures that subscriptions are disposed properly.
-->

`HttpClient`의 각 요청 메서드는 요청한 응답 타입의 `Observable`을 생성해서 반환합니다.
`HttpClient`를 사용할 때는 이 `Observable`의 동작을 이해하는 것이 중요합니다.

`HttpClient`가 생성하는 것은 RxJS에서 "콜드(cold)" `Observable`이라고 부르는 옵저버블입니다.
즉, `Observable`을 구독하기 전에는 실제 요청이 발생하지 않으며, 구독해야 서버로 요청을 보냅니다.
같은 `Observable`을 여러 번 구독하면 백엔드 요청도 여러 번 발생합니다.
각 구독은 독립적입니다.

팁: `HttpClient`의 `Observable`은 실제 서버 요청을 위한 _설계도_ 라고 생각할 수 있습니다.

구독한 뒤 구독을 해제하면 진행 중인 요청을 취소합니다.
`async` 파이프로 `Observable`을 구독하면 사용자가 현재 페이지를 떠날 때 요청을 자동으로 취소하므로 매우 유용합니다.
또한 `switchMap` 같은 RxJS 조합 연산자와 함께 사용하면 이런 취소 동작으로 더 이상 필요하지 않은 요청을 정리할 수 있습니다.

응답을 받으면 `HttpClient`의 `Observable`은 일반적으로 완료됩니다.
다만 인터셉터가 이 동작에 영향을 줄 수 있습니다.

자동으로 완료되므로 `HttpClient` 구독을 정리하지 않아도 보통 메모리 누수가 발생하지 않습니다.
하지만 다른 비동기 작업과 마찬가지로, 구독을 사용하는 컴포넌트가 종료되면 구독도 정리하는 것을 강하게 권장합니다.
그렇지 않으면 구독 콜백이 실행되면서 이미 종료된 컴포넌트와 상호작용하려다가 오류가 발생할 수 있습니다.

팁: `async` 파이프나 `toSignal`로 `Observable`을 구독하면 구독을 적절하게 정리할 수 있습니다.

## 권장하는 사용 방식

<!--
While `HttpClient` can be injected and used directly from components, generally we recommend you create reusable, injectable services which isolate and encapsulate data access logic. For example, this `UserService` encapsulates the logic to request data for a user by their id:

```ts
@Service()
export class UserService {
  private http = inject(HttpClient);

getUser(id: string): Observable<User> {
    return this.http.get<User>(`/api/user/${id}`);
  }
}
```

Within a component, you can combine `@if` with the `async` pipe to render the UI for the data only after it's finished loading:

```typescript
import {AsyncPipe} from '@angular/common';
import {Component, input, inject, effect} from '@angular/core';
import {Observable} from 'rxjs';

@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() {
    effect(() => {
      this.user$ = this.userService.getUser(this.userId());
    });
  }
}
```
-->

`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`와 `async` 파이프를 함께 사용해서 데이터 로드가 완료된 후에만 해당 데이터를 사용하는 UI를 렌더링할 수 있습니다:

```typescript
import {AsyncPipe} from '@angular/common';
import {Component, input, inject, effect} from '@angular/core';
import {Observable} from 'rxjs';

private userService = inject(UserService);

constructor() {
    effect(() => {
      this.user$ = this.userService.getUser(this.userId());
    });
  }
}
```

# 인터셉터

<!--
`HttpClient` supports a form of middleware known as _interceptors_.

TLDR: Interceptors are middleware that allows common patterns around retrying, caching, logging, and authentication to be abstracted away from individual requests.

`HttpClient` supports two kinds of interceptors: functional and DI-based. Our recommendation is to use functional interceptors because they have more predictable behavior, especially in complex setups. Our examples in this guide use functional interceptors, and we cover [DI-based interceptors](#di-based-interceptors) in their own section at the end.
-->

`HttpClient`는 _인터셉터(interceptor)_ 라는 형태의 미들웨어를 지원합니다.

요약: 인터셉터는 재시도, 캐싱, 로그 기록, 인증 같은 공통 패턴을 개별 요청에서 분리해서 구현할 수 있도록 하는 미들웨어입니다.

`HttpClient`는 함수형 인터셉터와 DI 기반 인터셉터를 지원합니다.
특히 복잡한 설정에서 동작을 더 쉽게 예측할 수 있는 함수형 인터셉터를 사용하는 것을 권장합니다.
이 가이드의 예제는 함수형 인터셉터를 사용하며, [DI 기반 인터셉터](#di-based-interceptors)는 마지막에 별도로 설명합니다.

## 인터셉터

<!--
Interceptors are generally functions that you can run for each request and have broad capabilities to affect the contents and overall flow of requests and responses. You can install multiple interceptors, which form an interceptor chain where each interceptor processes the request or response before forwarding it to the next interceptor in the chain.

You can use interceptors to implement a variety of common patterns, such as:

- Adding authentication headers to outgoing requests to a particular API.
- Retrying failed requests with exponential backoff.
- Caching responses for a period of time, or until invalidated by mutations.
- Customizing the parsing of responses.
- Measuring server response times and logging them.
- Driving UI elements such as a loading spinner while network operations are in progress.
- Collecting and batching requests made within a certain timeframe.
- Automatically failing requests after a configurable deadline or timeout.
- Regularly polling the server and refreshing results.
-->

인터셉터는 일반적으로 각 요청에 대해 실행할 수 있는 함수이며, 요청과 응답의 내용 및 전체 흐름을 폭넓게 제어할 수 있습니다.
여러 인터셉터를 등록하면 인터셉터 체인을 구성합니다.
각 인터셉터는 요청이나 응답을 처리한 뒤 체인의 다음 인터셉터로 전달합니다.

인터셉터로 다음과 같은 공통 패턴을 구현할 수 있습니다:

- 특정 API로 보내는 요청에 인증 헤더 추가하기
- 지수 백오프를 적용해서 실패한 요청 재시도하기
- 일정 시간 동안 또는 변경 작업으로 무효화될 때까지 응답 캐싱하기
- 응답 파싱 방식 커스터마이징하기
- 서버 응답 시간을 측정하고 기록하기
- 네트워크 작업 중 로딩 표시 같은 UI 엘리먼트 제어하기
- 일정 시간 동안 발생한 요청을 모아서 일괄 처리하기
- 설정한 기한이나 타임아웃이 지나면 요청을 자동으로 실패 처리하기
- 서버를 주기적으로 폴링해서 결과 갱신하기

## 인터셉터 정의하기

<!--
The basic form of an interceptor is a function which receives the outgoing `HttpRequest` and a `next` function representing the next processing step in the interceptor chain.

For example, this `loggingInterceptor` will log the outgoing request URL to `console.log` before forwarding the request:

```ts
export function loggingInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  console.log(req.url);
  return next(req);
}
```

In order for this interceptor to actually intercept requests, you must configure `HttpClient` to use it.
-->

인터셉터의 기본 형태는 전송할 `HttpRequest`와 인터셉터 체인의 다음 처리 단계를 나타내는 `next` 함수를 받는 함수입니다.

예를 들어 다음 `loggingInterceptor`는 요청을 전달하기 전에 요청 URL을 `console.log`로 출력합니다:

```ts
export function loggingInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  console.log(req.url);
  return next(req);
}
```

이 인터셉터가 실제 요청을 가로채도록 하려면 `HttpClient`에서 사용하도록 설정해야 합니다.

## 인터셉터 설정하기

<!--
You declare the set of interceptors to use when configuring `HttpClient` through dependency injection, by using the `withInterceptors` feature:

```ts
bootstrapApplication(App, {
  providers: [provideHttpClient(withInterceptors([loggingInterceptor, cachingInterceptor]))],
});
```

The interceptors you configure are chained together in the order that you've listed them in the providers. In the above example, the `loggingInterceptor` would process the request and then forward it to the `cachingInterceptor`.
-->

의존성 주입으로 `HttpClient`를 설정할 때 `withInterceptors` 기능으로 사용할 인터셉터 목록을 선언합니다:

```ts
bootstrapApplication(App, {
  providers: [provideHttpClient(withInterceptors([loggingInterceptor, cachingInterceptor]))],
});
```

인터셉터는 프로바이더에 나열한 순서대로 연결됩니다.
위 예제에서는 `loggingInterceptor`가 요청을 처리한 뒤 `cachingInterceptor`로 전달합니다.

### 응답 이벤트 가로채기

<!--
An interceptor may transform the `Observable` stream of `HttpEvent`s returned by `next` in order to access or manipulate the response. Because this stream includes all response events, inspecting the `.type` of each event may be necessary in order to identify the final response object.

```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: Interceptors naturally associate responses with their outgoing requests, because they transform the response stream in a closure that captures the request object.
-->

인터셉터는 응답에 접근하거나 응답을 조작하기 위해 `next`가 반환하는 `HttpEvent`의 `Observable` 스트림을 변환할 수 있습니다.
이 스트림에는 모든 응답 이벤트가 포함되므로, 최종 응답 객체를 구분하려면 각 이벤트의 `.type`을 확인해야 할 수 있습니다.

팁: 인터셉터는 요청 객체를 참조하는 클로저 안에서 응답 스트림을 변환하므로, 응답을 해당 요청과 자연스럽게 연결할 수 있습니다.

## 요청 수정하기

<!--
Most aspects of `HttpRequest` and `HttpResponse` instances are _immutable_, and interceptors cannot directly modify them. Instead, interceptors apply mutations by cloning these objects using the `.clone()` operation, and specifying which properties should be mutated in the new instance. This might involve performing immutable updates on the value itself (like `HttpHeaders` or `HttpParams`).

For example, to add a header to a request:

```ts
const reqWithHeader = req.clone({
  headers: req.headers.set('X-New-Header', 'new header value'),
});
```

This immutability allows most interceptors to be idempotent if the same `HttpRequest` is submitted to the interceptor chain multiple times. This can happen for a few reasons, including when a request is retried after failure.

CRITICAL: The body of a request or response is **not** protected from deep mutations. If an interceptor must mutate the body, take care to handle running multiple times on the same request.
-->

`HttpRequest`와 `HttpResponse` 인스턴스의 대부분은 _불변_ 이므로 인터셉터에서 직접 수정할 수 없습니다.
대신 `.clone()`으로 객체를 복제하면서 새 인스턴스에서 변경할 프로퍼티를 지정합니다.
이때 `HttpHeaders`나 `HttpParams`처럼 값 자체도 불변 방식으로 갱신해야 할 수 있습니다.

예를 들어 요청에 헤더를 추가하려면 다음과 같이 작성합니다:

```ts
const reqWithHeader = req.clone({
  headers: req.headers.set('X-New-Header', 'new header value'),
});
```

이런 불변성 덕분에 같은 `HttpRequest`를 인터셉터 체인에 여러 번 전달하더라도 대부분의 인터셉터는 멱등성을 유지할 수 있습니다.
요청 실패 후 재시도하는 경우를 비롯해 여러 상황에서 같은 요청이 반복해서 전달될 수 있습니다.

중요: 요청이나 응답 본문은 내부 값까지 변경되지 않도록 보호되는 것은 **아닙니다**.
인터셉터에서 본문을 변경해야 한다면 같은 요청에 여러 번 실행되는 상황을 주의해서 처리하세요.

## 인터셉터에서 의존성 주입하기

<!--
Interceptors are run in the _injection context_ of the injector which registered them, and can use Angular's [`inject`](/api/core/inject) API to retrieve dependencies.

For example, suppose an application has a service called `AuthService`, which creates authentication tokens for outgoing requests. An interceptor can inject and use this service:

```ts
export function authInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn) {
  // Inject the current `AuthService` and use it to get an authentication token:
  const authToken = inject(AuthService).getAuthToken();

// Clone the request to add the authentication header.
  const newReq = req.clone({
    headers: req.headers.append('X-Authentication-Token', authToken),
  });
  return next(newReq);
}
```
-->

인터셉터는 자신을 등록한 인젝터의 _의존성 주입 컨텍스트_ 에서 실행되며, Angular의 [`inject`](/api/core/inject) API로 의존성을 가져올 수 있습니다.

예를 들어 애플리케이션에 전송할 요청의 인증 토큰을 만드는 `AuthService` 서비스가 있다고 해봅시다.
인터셉터에서 이 서비스를 주입해서 사용할 수 있습니다:

```ts
export function authInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn) {
  // 현재 `AuthService`를 주입하고 인증 토큰을 가져옵니다:
  const authToken = inject(AuthService).getAuthToken();

// 요청을 복제하면서 인증 헤더를 추가합니다.
  const newReq = req.clone({
    headers: req.headers.append('X-Authentication-Token', authToken),
  });
  return next(newReq);
}
```

## 요청과 응답 메타데이터

<!--
Often it's useful to include information in a request that's not sent to the backend, but is specifically meant for interceptors. `HttpRequest`s have a `.context` object which stores this kind of metadata as an instance of `HttpContext`. This object functions as a typed map, with keys of type `HttpContextToken`.

To illustrate how this system works, let's use metadata to control whether a caching interceptor is enabled for a given request.
-->

백엔드로 보내지는 않지만 인터셉터에서 사용할 정보를 요청에 포함하면 유용할 때가 많습니다.
`HttpRequest`의 `.context` 객체는 이런 메타데이터를 `HttpContext` 인스턴스에 저장합니다.
이 객체는 `HttpContextToken` 타입의 키를 사용하는, 타입이 지정된 맵으로 동작합니다.

이 기능이 어떻게 동작하는지 알아보기 위해 메타데이터로 특정 요청의 캐싱 인터셉터를 활성화할지 제어해 봅시다.

### 컨텍스트 토큰 정의하기

<!--
To store whether the caching interceptor should cache a particular request in that request's `.context` map, define a new `HttpContextToken` to act as a key:

```ts
export const CACHING_ENABLED = new HttpContextToken<boolean>(() => true);
```

The provided function creates the default value for the token for requests that haven't explicitly set a value for it. Using a function ensures that if the token's value is an object or array, each request gets its own instance.
-->

캐싱 인터셉터가 특정 요청을 캐싱할지 여부를 요청의 `.context` 맵에 저장하려면, 키로 사용할 `HttpContextToken`을 새로 정의합니다:

```ts
export const CACHING_ENABLED = new HttpContextToken<boolean>(() => true);
```

전달한 함수는 토큰 값을 명시적으로 설정하지 않은 요청에서 사용할 기본값을 생성합니다.
함수를 사용하면 토큰 값이 객체나 배열일 때 각 요청이 별도의 인스턴스를 갖도록 할 수 있습니다.

### 인터셉터에서 토큰 읽기

<!--
An interceptor can then read the token and choose to apply caching logic or not based on its value:

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

인터셉터에서 토큰을 읽고 값에 따라 캐싱 로직을 적용할지 결정할 수 있습니다:

```ts
export function cachingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  if (req.context.get(CACHING_ENABLED)) {
    // 캐싱 로직을 적용합니다.
    return ...;
  } else {
    // 이 요청에서는 캐싱을 사용하지 않습니다.
    return next(req);
  }
}
```

### 요청을 보낼 때 컨텍스트 토큰 설정하기

<!--
When making a request via the `HttpClient` API, you can provide values for `HttpContextToken`s:

```ts
const data$ = http.get('/sensitive/data', {
  context: new HttpContext().set(CACHING_ENABLED, false),
});
```

Interceptors can read these values from the `HttpContext` of the request.
-->

`HttpClient` API로 요청을 보낼 때 `HttpContextToken` 값을 지정할 수 있습니다:

```ts
const data$ = http.get('/sensitive/data', {
  context: new HttpContext().set(CACHING_ENABLED, false),
});
```

인터셉터는 요청의 `HttpContext`에서 이 값을 읽을 수 있습니다.

### 요청 컨텍스트는 변경할 수 있습니다

`HttpRequest`의 다른 프로퍼티와 달리 `HttpContext`는 _변경할 수 있습니다_.
인터셉터가 요청의 컨텍스트를 변경하고 이후 요청이 재시도되면, 같은 인터셉터가 다시 실행될 때 변경된 컨텍스트를 확인할 수 있습니다.
여러 번의 재시도 사이에서 상태를 전달해야 할 때 유용합니다.

## 응답 직접 만들기

<!--
Most interceptors will simply invoke the `next` handler while transforming either the request or the response, but this is not strictly a requirement. This section discusses several of the ways in which an interceptor may incorporate more advanced behavior.

Interceptors are not required to invoke `next`. They may instead choose to construct responses through some other mechanism, such as from a cache or by sending the request through an alternate mechanism.

Constructing a response is possible using the `HttpResponse` constructor:

```ts
const resp = new HttpResponse({
  body: 'response body',
});
```
-->

대부분의 인터셉터는 요청이나 응답을 변환하면서 `next` 핸들러를 실행하지만, 반드시 그래야 하는 것은 아닙니다.
이 섹션에서는 인터셉터에 더 복잡한 동작을 구현하는 몇 가지 방법을 알아봅니다.

인터셉터는 `next`를 반드시 실행할 필요가 없습니다.
대신 캐시에서 응답을 만들거나 다른 방식으로 요청을 보내는 등 별도의 방법으로 응답을 구성할 수 있습니다.

`HttpResponse` 생성자를 사용하면 응답을 직접 만들 수 있습니다:

```ts
const resp = new HttpResponse({
  body: 'response body',
});
```

## 리다이렉트 정보 활용하기

<!--
When `HttpClient` uses the fetch backend, responses include a `redirected` property that indicates whether the response was the result of a redirect. This property aligns with the native Fetch API specification and can be useful in interceptors for handling redirect scenarios.

An interceptor can access and act upon the redirect information:

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

You can also use the redirect information to implement conditional logic in your interceptors:

```ts
export function authRedirectInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  return next(req).pipe(
    tap((event) => {
      if (event.type === HttpEventType.Response && event.redirected) {
        // Check if we were redirected to a login page
        if (event.url?.includes('/login')) {
          // Handle authentication redirect
          handleAuthRedirect();
        }
      }
    }),
  );
}
```
-->

`HttpClient`가 fetch 백엔드를 사용하면 응답에 `redirected` 프로퍼티가 포함됩니다.
이 프로퍼티는 응답이 리다이렉트의 결과인지 나타내며, 네이티브 Fetch API 명세와 같습니다.
인터셉터에서 리다이렉트 상황을 처리할 때 유용합니다.

인터셉터는 리다이렉트 정보를 확인하고 그에 따라 동작할 수 있습니다:

```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);
        // 분석 정보 갱신, 보안 검사 등 리다이렉트 로직을 처리합니다.
      }
    }),
  );
}
```

리다이렉트 정보를 사용해서 인터셉터에 조건부 로직을 구현할 수도 있습니다:

```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) {
        // 로그인 페이지로 리다이렉트되었는지 확인합니다.
        if (event.url?.includes('/login')) {
          // 인증 리다이렉트를 처리합니다.
          handleAuthRedirect();
        }
      }
    }),
  );
}
```

## 응답 타입 활용하기

<!--
When `HttpClient` uses the fetch backend, responses include a `responseType` property that indicates how the browser handled the response based on CORS policies and request mode. This property aligns with the native Fetch API specification and provides valuable insights for debugging CORS issues and understanding response accessibility.

The response `responseType` property can have the following values:

- `'basic'` - Same-origin response with all headers accessible
- `'cors'` - Cross-origin response with CORS headers properly configured
- `'opaque'` - Cross-origin response without CORS, headers and body may be limited
- `'opaqueredirect'` - Response from a redirected request in no-cors mode
- `'error'` - Network error occurred

An interceptor can use response type information for CORS debugging and error handling:

```ts
export function responseTypeInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  return next(req).pipe(
    tap((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;
        }
      }
    }),
  );
}
```
-->

`HttpClient`가 fetch 백엔드를 사용하면 응답에 `responseType` 프로퍼티가 포함됩니다.
이 프로퍼티는 브라우저가 CORS 정책과 요청 모드에 따라 응답을 어떻게 처리했는지 나타냅니다.
네이티브 Fetch API 명세와 같으며, CORS 문제를 디버깅하고 응답에 접근할 수 있는 범위를 이해하는 데 유용합니다.

응답의 `responseType` 프로퍼티에는 다음 값이 올 수 있습니다:

- `'basic'` - 모든 헤더에 접근할 수 있는 동일 출처 응답
- `'cors'` - CORS 헤더가 올바르게 설정된 교차 출처 응답
- `'opaque'` - CORS를 사용하지 않는 교차 출처 응답으로, 헤더와 본문 접근이 제한될 수 있음
- `'opaqueredirect'` - no-cors 모드에서 리다이렉트된 요청의 응답
- `'error'` - 네트워크 오류가 발생함

인터셉터에서 응답 타입 정보를 사용해서 CORS를 디버깅하고 오류를 처리할 수 있습니다:

```ts
export function responseTypeInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  return next(req).pipe(
    tap((event) => {
      if (event.type === HttpEventType.Response) {
        // 응답 타입에 맞게 처리합니다.
        switch (event.responseType) {
          case 'opaque':
            // 응답 데이터 접근이 제한됩니다.
            console.warn('Limited response data due to CORS policy');
            break;
          case 'cors':
          case 'basic':
            // 응답 데이터 전체에 접근할 수 있습니다.
            break;
          case 'error':
            // 네트워크 에러를 처리합니다.
            console.error('Network error in response');
            break;
        }
      }
    }),
  );
}
```

## DI 기반 인터셉터

<!--
`HttpClient` also supports interceptors which are defined as injectable classes and configured through the DI system. The capabilities of DI-based interceptors are identical to those of functional interceptors, but the configuration mechanism is different.

A DI-based interceptor is an injectable class which implements the `HttpInterceptor` interface:

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

DI-based interceptors are configured through a dependency injection multi-provider:

```ts
bootstrapApplication(App, {
  providers: [
    provideHttpClient(
      // DI-based interceptors must be explicitly enabled.
      withInterceptorsFromDi(),
    ),

{provide: HTTP_INTERCEPTORS, useClass: LoggingInterceptor, multi: true},
  ],
});
```

DI-based interceptors run in the order that their providers are registered. In an app with an extensive and hierarchical DI configuration, this order can be very hard to predict.
-->

`HttpClient`는 주입 가능한 클래스로 정의하고 DI 시스템을 통해 설정하는 인터셉터도 지원합니다.
DI 기반 인터셉터의 기능은 함수형 인터셉터와 같지만 설정 방식이 다릅니다.

DI 기반 인터셉터는 `HttpInterceptor` 인터페이스를 구현하는 주입 가능한 클래스입니다:

DI 기반 인터셉터는 의존성 주입의 다중 프로바이더로 설정합니다:

```ts
bootstrapApplication(App, {
  providers: [
    provideHttpClient(
      // DI 기반 인터셉터는 명시적으로 활성화해야 합니다.
      withInterceptorsFromDi(),
    ),

{provide: HTTP_INTERCEPTORS, useClass: LoggingInterceptor, multi: true},
  ],
});
```

DI 기반 인터셉터는 프로바이더가 등록된 순서로 실행됩니다.
DI 설정이 많고 여러 계층으로 구성된 애플리케이션에서는 이 순서를 예측하기가 매우 어려울 수 있습니다.

# 요청 테스트하기

<!--
As for any external dependency, you must mock the HTTP backend so your tests can simulate interaction with a remote server. The `@angular/common/http/testing` library provides tools to capture requests made by the application, make assertions about them, and mock the responses to emulate your backend's behavior.

The testing library is designed for a pattern where the app executes code and makes requests first. The test then expects that certain requests have or have not been made, performs assertions against those requests, and finally provides responses by "flushing" each expected request.

Finally, tests can verify that the app made no unexpected requests.
-->

다른 외부 의존성과 마찬가지로 HTTP 백엔드도 모의 구현해서 테스트에서 원격 서버와의 상호작용을 재현해야 합니다.
`@angular/common/http/testing` 라이브러리는 애플리케이션이 보낸 요청을 가져와 검증하고, 응답을 모의 구현해서 백엔드 동작을 재현하는 도구를 제공합니다.

테스트 라이브러리는 애플리케이션이 먼저 코드를 실행해서 요청을 보내는 패턴을 기준으로 설계되었습니다.
그런 다음 테스트에서 특정 요청이 발생했는지 또는 발생하지 않았는지 확인하고 요청 내용을 검증한 뒤, 예상한 각 요청에 응답을 전달하는 "플러시(flush)"를 수행합니다.

마지막으로 애플리케이션이 예상하지 않은 요청을 보내지 않았는지 확인할 수 있습니다.

## 테스트 설정하기

<!--
To begin testing usage of `HttpClient`, configure `TestBed` and include `provideHttpClientTesting()` in your test's setup. `HttpClient` is provided by Angular's test environment, and `provideHttpClientTesting()` configures it to use a test backend instead of the real network. It also provides `HttpTestingController`, which you'll use to interact with the test backend, set expectations about which requests have been made, and flush responses to those requests. `HttpTestingController` can be injected from `TestBed` once configured.

```ts
TestBed.configureTestingModule({
  providers: [
    // ... other test providers
    provideHttpClientTesting(),
  ],
});

const httpTesting = TestBed.inject(HttpTestingController);
```

Now when your tests make requests, they will hit the testing backend instead of the normal one. You can use `httpTesting` to make assertions about those requests.
-->

`HttpClient`를 사용하는 코드를 테스트하려면 `TestBed`를 구성하고 테스트 설정에 `provideHttpClientTesting()`을 포함합니다.
Angular 테스트 환경은 `HttpClient`를 제공하며, `provideHttpClientTesting()`은 실제 네트워크 대신 테스트 백엔드를 사용하도록 설정합니다.
이 함수는 `HttpTestingController`도 제공합니다.
이 컨트롤러로 테스트 백엔드와 상호작용하고, 어떤 요청이 발생했는지 검사하며, 요청에 응답을 전달할 수 있습니다.
설정을 마치면 `TestBed`에서 `HttpTestingController`를 주입받을 수 있습니다.

```ts
TestBed.configureTestingModule({
  providers: [
    // ... 다른 테스트 프로바이더
    provideHttpClientTesting(),
  ],
});

const httpTesting = TestBed.inject(HttpTestingController);
```

이제 테스트에서 요청을 보내면 일반 백엔드 대신 테스트 백엔드로 전달됩니다.
`httpTesting`을 사용해서 이 요청들을 검증할 수 있습니다.

### 테스트에서 `HttpClient` 설정하기

<!--
If a test needs to configure `HttpClient` features, such as interceptors, include `provideHttpClient(...)` before `provideHttpClientTesting()`.
IMPORTANT: Keep in mind to provide `provideHttpClient()` **before** `provideHttpClientTesting()`, as `provideHttpClientTesting()` will overwrite parts of `provideHttpClient()`. Doing it the other way around can potentially break your tests.

```ts
TestBed.configureTestingModule({
  providers: [provideHttpClient(withInterceptors([authInterceptor])), provideHttpClientTesting()],
});
```
-->

테스트에서 인터셉터 같은 `HttpClient` 기능을 설정해야 한다면 `provideHttpClientTesting()` 앞에 `provideHttpClient(...)`를 포함합니다.
중요: `provideHttpClientTesting()`은 `provideHttpClient()` 설정의 일부를 덮어쓰므로, 반드시 `provideHttpClient()`를 `provideHttpClientTesting()` **앞에** 제공해야 합니다.
반대 순서로 제공하면 테스트가 제대로 동작하지 않을 수 있습니다.

```ts
TestBed.configureTestingModule({
  providers: [provideHttpClient(withInterceptors([authInterceptor])), provideHttpClientTesting()],
});
```

## 요청을 확인하고 응답하기

<!--
For example, you can write a test that expects a GET request to occur and provides a mock response:

```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` will fail if the test has made more than one request which matches the given criteria.

As an alternative to asserting on `req.method`, you could instead use an expanded form of `expectOne` to also match the request method:

```ts
const req = httpTesting.expectOne(
  {
    method: 'GET',
    url: '/api/config',
  },
  'Request to load the configuration',
);
```

HELPFUL: The expectation APIs match against the full URL of requests, including any query parameters.

The last step, verifying that no requests remain outstanding, is common enough for you to move it into an `afterEach()` step:

```ts
afterEach(() => {
  // Verify that none of the tests make any extra HTTP requests.
  TestBed.inject(HttpTestingController).verify();
});
```
-->

예를 들어 GET 요청이 발생하는지 확인하고 모의 응답을 제공하는 테스트를 작성할 수 있습니다:

```ts
TestBed.configureTestingModule({
  providers: [ConfigService, provideHttpClientTesting()],
});

const httpTesting = TestBed.inject(HttpTestingController);

// `ConfigService`를 가져와 현재 설정을 요청합니다.
const service = TestBed.inject(ConfigService);
const config$ = service.getConfig<Config>();

// `firstValueFrom`은 `Observable`을 구독해서 HTTP 요청을 보내고
// 응답에 대한 `Promise`를 생성합니다.
const configPromise = firstValueFrom(config$);

// 이 시점에는 요청이 대기 중이며, `HttpTestingController`를 통해
// 요청이 발생했는지 확인할 수 있습니다:
const req = httpTesting.expectOne('/api/config', 'Request to load the configuration');

// 필요하면 요청의 여러 프로퍼티를 검사할 수 있습니다.
expect(req.request.method).toBe('GET');

// 요청에 응답을 전달하면 결과가 전달되고 요청이 완료됩니다.
req.flush(DEFAULT_CONFIG);

// 이제 `ConfigService`가 응답을 제대로 전달했는지 검사할 수 있습니다:
expect(await configPromise).toEqual(DEFAULT_CONFIG);

// 마지막으로 다른 요청이 발생하지 않았는지 검사합니다.
httpTesting.verify();
```

참고: 지정한 조건에 맞는 요청이 두 개 이상 발생하면 `expectOne`은 실패합니다.

`req.method`를 별도로 검사하는 대신, `expectOne`의 확장된 형태로 요청 메서드까지 함께 확인할 수 있습니다:

```ts
const req = httpTesting.expectOne(
  {
    method: 'GET',
    url: '/api/config',
  },
  'Request to load the configuration',
);
```

참고: 요청 확인 API는 쿼리 파라미터를 포함한 전체 URL을 비교합니다.

마지막 단계인 미처리 요청 확인은 여러 테스트에서 공통으로 필요하므로 `afterEach()`로 옮길 수 있습니다:

```ts
afterEach(() => {
  // 모든 테스트에서 추가 HTTP 요청이 발생하지 않았는지 확인합니다.
  TestBed.inject(HttpTestingController).verify();
});
```

## 여러 요청을 한 번에 처리하기

<!--
If you need to respond to duplicate requests in your test, use the `match()` API instead of `expectOne()`. It takes the same arguments but returns an array of matching requests. Once returned, these requests are removed from future matching and you are responsible for flushing and verifying them.

```ts
const allGetRequests = httpTesting.match({method: 'GET'});
for (const req of allGetRequests) {
  // Handle responding to each request.
}
```
-->

테스트에서 중복 요청에 응답해야 한다면 `expectOne()` 대신 `match()` API를 사용합니다.
받는 인자는 같지만 조건에 맞는 요청의 배열을 반환합니다.
반환한 요청은 이후 매칭 대상에서 제외되므로, 직접 응답을 전달하고 검증해야 합니다.

```ts
const allGetRequests = httpTesting.match({method: 'GET'});
for (const req of allGetRequests) {
  // 각 요청에 응답합니다.
}
```

## 복잡한 조건으로 요청 찾기

<!--
All matching functions accept a predicate function for custom matching logic:

```ts
// Look for one request that has a request body.
const requestsWithBody = httpTesting.expectOne((req) => req.body !== null);
```

The `expectNone` function asserts that no requests match the given criteria.

```ts
// Assert that no mutation requests have been issued.
httpTesting.expectNone((req) => req.method !== 'GET');
```
-->

모든 매칭 함수에는 직접 작성한 조건 함수를 전달할 수 있습니다:

```ts
// 본문이 있는 요청 하나를 찾습니다.
const requestsWithBody = httpTesting.expectOne((req) => req.body !== null);
```

`expectNone` 함수는 지정한 조건에 맞는 요청이 없는지 검사합니다.

```ts
// 변경 요청이 발생하지 않았는지 검사합니다.
httpTesting.expectNone((req) => req.method !== 'GET');
```

## 오류 처리 테스트하기

HTTP 요청이 실패했을 때 애플리케이션이 어떻게 대응하는지 테스트해야 합니다.

### 백엔드 오류

<!--
To test handling of backend errors (when the server returns a non-successful status code), flush requests with an error response that emulates what your backend would return when a request fails.

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

서버가 성공이 아닌 상태 코드를 반환하는 백엔드 오류를 테스트하려면, 요청 실패 시 백엔드가 반환할 오류 응답을 만들어 요청에 전달합니다.

```ts
const req = httpTesting.expectOne('/api/config');
req.flush('Failed!', {status: 500, statusText: 'Internal Server Error'});

// 애플리케이션이 백엔드 에러를 제대로 처리했는지 검사합니다.
```

### 네트워크 오류

<!--
Requests can also fail due to network errors, which surface as `ProgressEvent` errors. These can be delivered with the `error()` method:

```ts
const req = httpTesting.expectOne('/api/config');
req.error(new ProgressEvent('network error!'));

// Assert that the application successfully handled the network error.
```
-->

요청은 네트워크 오류로 실패할 수도 있으며, 이런 오류는 `ProgressEvent`로 전달됩니다.
`error()` 메서드로 전달할 수 있습니다:

```ts
const req = httpTesting.expectOne('/api/config');
req.error(new ProgressEvent('network error!'));

// 애플리케이션이 네트워크 에러를 제대로 처리했는지 검사합니다.
```

## 인터셉터 테스트하기

<!--
You should test that your interceptors work under the desired circumstances.

For example, an application may be required to add an authentication token generated by a service to each outgoing request.
This behavior can be enforced with the use of an 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);
}
```

The `TestBed` configuration for this interceptor should rely on the `withInterceptors` feature.

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    // Testing one interceptor at a time is recommended.
    provideHttpClient(withInterceptors([authInterceptor])),
    provideHttpClientTesting(),
  ],
});
```

The `HttpTestingController` can retrieve the request instance that can then be inspected to ensure that the request was modified.

```ts
const service = TestBed.inject(AuthService);
const http = TestBed.inject(HttpClient);

// Make an HTTP request.
const response = firstValueFrom(http.get('/api/config'));

const req = httpTesting.expectOne('/api/config');

expect(req.request.headers.get('X-Authentication-Token')).toEqual(service.getAuthToken());
```

A similar interceptor could be implemented with class-based interceptors:

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

In order to test it, the `TestBed` configuration should instead be:

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

인터셉터가 의도한 상황에서 제대로 동작하는지 테스트해야 합니다.

예를 들어 전송하는 모든 요청에 서비스가 생성한 인증 토큰을 추가해야 하는 애플리케이션이 있을 수 있습니다.
인터셉터를 사용하면 이 동작을 보장할 수 있습니다:

```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` 설정에서는 `withInterceptors` 기능을 사용합니다.

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    // 인터셉터를 한 번에 하나씩 테스트하는 것을 권장합니다.
    provideHttpClient(withInterceptors([authInterceptor])),
    provideHttpClientTesting(),
  ],
});
```

`HttpTestingController`로 요청 인스턴스를 가져와 검사하면 요청이 수정되었는지 확인할 수 있습니다.

```ts
const service = TestBed.inject(AuthService);
const http = TestBed.inject(HttpClient);

// HTTP 요청을 보냅니다.
const response = firstValueFrom(http.get('/api/config'));

const req = httpTesting.expectOne('/api/config');

expect(req.request.headers.get('X-Authentication-Token')).toEqual(service.getAuthToken());
```

같은 기능을 클래스 기반 인터셉터로 구현할 수도 있습니다:

```ts
@Injectable()
export class AuthInterceptor implements HttpInterceptor {
  private authService = inject(AuthService);

이 인터셉터를 테스트하려면 `TestBed`를 다음과 같이 설정합니다:

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    provideHttpClient(withInterceptorsFromDi()),
    provideHttpClientTesting(),
    // HTTP_INTERCEPTORS 토큰으로 AuthInterceptor를 HttpInterceptor로 등록합니다.
    {provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true},
  ],
});
```

# 반응형 폼

반응형 폼은 시간이 지나면서 값이 바뀌는 폼 입력을 모델 중심으로 처리하는 방식입니다.
이 문서에서는 기본 폼 컨트롤을 생성하고 갱신하는 방법, 여러 컨트롤을 그룹으로 묶는 방법, 폼 값의 유효성을 검사하는 방법, 실행 중에 컨트롤을 추가하거나 제거할 수 있는 동적 폼을 만드는 방법을 설명합니다.

## 반응형 폼 개요

<!--
Reactive forms use an explicit and immutable approach to managing the state of a form at a given point in time.
Each change to the form state returns a new state, which maintains the integrity of the model between changes.
Reactive forms are built around observable streams, where form inputs and values are provided as streams that can be accessed synchronously.

Reactive forms also provide a straightforward path to testing because you are assured that your data is consistent and predictable when requested.
Any consumers of these streams can safely manipulate the data.

Reactive forms differ from [template-driven forms](guide/forms/template-driven-forms) in distinct ways.
Reactive forms provide synchronous access to the data model, immutability with observable operators, and change tracking through observable streams.

Template-driven forms allow direct access to modify data in your template, but are less explicit than reactive forms because they rely on directives embedded in the template, along with mutable data to track changes asynchronously.
See the [Forms Overview](guide/forms) for detailed comparisons between the two paradigms.
-->

반응형 폼은 특정 시점의 폼 상태를 명시적이고 불변인 방식으로 관리합니다.
폼 상태가 바뀔 때마다 새로운 상태가 반환되기 때문에 상태가 바뀌는 동안에도 모델의 무결성이 유지됩니다.
반응형 폼은 옵저버블 스트림을 기반으로 구성되며, 폼 입력과 값은 동기적으로 접근할 수 있는 스트림으로 제공됩니다.

반응형 폼은 데이터를 요청할 때 일관되고 예측 가능한 데이터를 보장하기 때문에 테스트하기도 간편합니다.
이 스트림의 소비자는 데이터를 안전하게 다룰 수 있습니다.

반응형 폼은 [템플릿 기반 폼](guide/forms/template-driven-forms)과 몇 가지 차이가 있습니다.
반응형 폼에서는 데이터 모델에 동기적으로 접근하며, 옵저버블 연산자로 불변성을 유지하고, 옵저버블 스트림으로 변화를 추적합니다.

템플릿 기반 폼에서는 템플릿에서 데이터에 직접 접근해서 수정할 수 있습니다.
하지만 템플릿에 포함된 디렉티브와 변경 가능한 데이터를 활용해서 변화를 비동기적으로 추적하기 때문에 반응형 폼만큼 명시적이지 않습니다.
두 방식을 자세하게 비교한 내용은 [폼 개요](guide/forms) 문서를 참고하세요.

## 기본 폼 컨트롤 추가하기

<!--
There are three steps to using form controls.

1. Generate a new component and register the reactive forms module. This module declares the reactive-form directives required to use reactive forms.
1. Instantiate a new `FormControl`.
1. Register the `FormControl` in the template.

You can then display the form by adding the component to the template.

The following examples show how to add a single form control.
In the example, the user enters their name into an input field, captures that input value, and displays the current value of the form control element.

<docs-workflow>

<docs-step title="Generate a new component and import the ReactiveFormsModule">
Use the CLI command `ng generate component` to generate a component in your project and import `ReactiveFormsModule` from the `@angular/forms` package and add it to your Component's `imports` array.

<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">
Use the constructor of `FormControl` to set its initial value, which in this case is an empty string. By creating these controls in your component class, you get immediate access to listen for, update, and validate the state of the form input.

<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">
After you create the control in the component class, you must associate it with a form control element in the template. Update the template with the form control using the `formControl` binding provided by `FormControlDirective`, which is also included in the `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" />

Using the template binding syntax, the form control is now registered to the `name` input element in the template. The form control and DOM element communicate with each other: the view reflects changes in the model, and the model reflects changes in the view.
</docs-step>

<docs-step title="Display the component">
The `FormControl` assigned to the `name` property is displayed when the `<app-name-editor>` component is added to a template.

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

폼 컨트롤을 사용하려면 다음 세 단계를 진행합니다.

1. 새 컴포넌트를 생성하고 반응형 폼 모듈을 등록합니다.
   이 모듈에는 반응형 폼을 사용하는 데 필요한 디렉티브가 선언되어 있습니다.
1. 새 `FormControl` 인스턴스를 생성합니다.
1. 템플릿에 `FormControl`을 등록합니다.

그런 다음 템플릿에 컴포넌트를 추가하면 폼을 표시할 수 있습니다.

다음 예제에서는 폼 컨트롤 하나를 추가하는 방법을 알아봅니다.
사용자가 입력 필드에 이름을 입력하면 이 입력값을 받아서 폼 컨트롤 엘리먼트의 현재 값을 표시하는 예제입니다.

<docs-workflow>

<docs-step title="새 컴포넌트를 생성하고 ReactiveFormsModule 불러오기">
CLI 명령 `ng generate component`로 프로젝트에 컴포넌트를 생성하세요.
그리고 `@angular/forms` 패키지에서 `ReactiveFormsModule`을 불러와 컴포넌트의 `imports` 배열에 추가하세요.

<docs-code header="name-editor.component.ts (일부)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" region="imports" />
</docs-step>

<docs-step title="FormControl 인스턴스 선언하기">
`FormControl` 생성자로 초기값을 지정하세요.
이 예제에서는 빈 문자열로 지정합니다.
컴포넌트 클래스에 컨트롤을 생성하면 폼 입력 상태에 바로 접근해서 변화를 감지하고, 상태를 갱신하고, 유효성을 검사할 수 있습니다.

<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="템플릿에 컨트롤 등록하기">
컴포넌트 클래스에 컨트롤을 생성했으면 템플릿의 폼 컨트롤 엘리먼트와 연결해야 합니다.
`FormControlDirective`가 제공하는 `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" />

템플릿 바인딩 문법을 사용하면 템플릿의 `name` 입력 엘리먼트에 폼 컨트롤이 등록됩니다.
폼 컨트롤과 DOM 엘리먼트는 서로 정보를 주고받기 때문에 모델의 변화는 뷰에 반영되고, 뷰의 변화는 모델에 반영됩니다.
</docs-step>

<docs-step title="컴포넌트 표시하기">
템플릿에 `<app-name-editor>` 컴포넌트를 추가하면 `name` 프로퍼티에 할당한 `FormControl`이 표시됩니다.

<docs-code header="app.component.html (이름 편집기)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" region="app-name-editor"/>
</docs-step>
</docs-workflow>

### 폼 컨트롤 값 표시하기

<!--
You can display the value in the following ways:

- Through the `valueChanges` observable where you can listen for changes in the form's value in the template using `AsyncPipe` or in the component class using the `subscribe()` method
- With the `value` property, which gives you a snapshot of the current value

The following example shows you how to display the current value using interpolation in the template.

<docs-code header="name-editor.component.html (control value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="display-value"/>

The displayed value changes as you update the form control element.

Reactive forms provide access to information about a given control through properties and methods provided with each instance.
These properties and methods of the underlying [AbstractControl](api/forms/AbstractControl 'API reference') class are used to control form state and determine when to display messages when handling [input validation](#validating-form-input 'Learn more about validating form input').

Read about other `FormControl` properties and methods in the [API Reference](api/forms/FormControl 'Detailed syntax reference').
-->

값은 다음과 같은 방법으로 표시할 수 있습니다.

- `valueChanges` 옵저버블을 사용하면 템플릿에서는 `AsyncPipe`로, 컴포넌트 클래스에서는 `subscribe()` 메서드로 폼 값의 변화를 감지할 수 있습니다.
- `value` 프로퍼티를 사용하면 현재 값의 스냅샷을 가져올 수 있습니다.

다음 예제는 템플릿에서 문자열 바인딩으로 현재 값을 표시하는 방법입니다.

<docs-code header="name-editor.component.html (컨트롤 값)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="display-value"/>

폼 컨트롤 엘리먼트를 갱신하면 표시되는 값도 바뀝니다.

반응형 폼은 각 인스턴스의 프로퍼티와 메서드로 해당 컨트롤에 관한 정보를 제공합니다.
기반 클래스인 [AbstractControl](api/forms/AbstractControl 'API 레퍼런스')의 프로퍼티와 메서드를 사용하면 폼 상태를 제어하고, [입력 유효성 검사](#validating-form-input '폼 입력 유효성 검사 자세히 알아보기')를 처리하면서 메시지를 표시할 시점을 결정할 수 있습니다.

`FormControl`의 다른 프로퍼티와 메서드는 [API 레퍼런스](api/forms/FormControl '자세한 문법 레퍼런스')를 참고하세요.

### 폼 컨트롤 값 교체하기

<!--
Reactive forms have methods to change a control's value programmatically, which gives you the flexibility to update the value without user interaction.
A form control instance provides a `setValue()` method that updates the value of the form control and validates the structure of the value provided against the control's structure.
For example, when retrieving form data from a backend API or service, use the `setValue()` method to update the control to its new value, replacing the old value entirely.

The following example adds a method to the component class to update the value of the control to _Nancy_ using the `setValue()` method.

<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 the template with a button to simulate a name update.
When you click the **Update Name** button, the value entered in the form control element is reflected as its current value.

<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"/>

The form model is the source of truth for the control, so when you click the button, the value of the input is changed within the component class, overriding its current value.

HELPFUL: In this example, you're using a single control.
When using the `setValue()` method with a [form group](#grouping-form-controls) or [form array](#creating-dynamic-forms) instance, the value needs to match the structure of the group or array.
-->

반응형 폼에는 컨트롤 값을 코드로 변경하는 메서드가 있기 때문에 사용자 입력 없이도 유연하게 값을 갱신할 수 있습니다.
폼 컨트롤 인스턴스가 제공하는 `setValue()` 메서드는 폼 컨트롤의 값을 갱신하고, 전달한 값의 구조가 컨트롤 구조와 일치하는지 검사합니다.
예를 들어 백엔드 API나 서비스에서 폼 데이터를 가져왔다면, `setValue()` 메서드로 기존 값을 완전히 교체해서 컨트롤을 새 값으로 갱신할 수 있습니다.

다음 예제는 `setValue()` 메서드로 컨트롤 값을 *Nancy*로 갱신하는 메서드를 컴포넌트 클래스에 추가합니다.

<docs-code header="name-editor.component.ts (값 갱신)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" region="update-value"/>

이름을 갱신해 볼 수 있도록 템플릿에 버튼을 추가하세요.
**Update Name** 버튼을 클릭하면 폼 컨트롤 엘리먼트에 입력되는 값이 현재 값으로 반영됩니다.

<docs-code header="name-editor.component.html (값 갱신)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="update-value"/>

폼 모델은 컨트롤 값의 원본 데이터를 관리합니다.
따라서 버튼을 클릭하면 컴포넌트 클래스에서 입력값을 변경하면서 현재 값을 덮어씁니다.

참고: 이 예제에서는 컨트롤 하나를 사용합니다.
[폼 그룹](#grouping-form-controls)이나 [폼 배열](#creating-dynamic-forms) 인스턴스에서 `setValue()` 메서드를 사용할 때는 전달하는 값이 그룹이나 배열의 구조와 일치해야 합니다.

## 폼 컨트롤 그룹으로 묶기

<!--
Forms typically contain several related controls.
Reactive forms provide two ways of grouping multiple related controls into a single input form.

| Form groups | Details                                                                                                                                                                                                                                                |
| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Form group  | Defines a form with a fixed set of controls that you can manage together. Form group basics are discussed in this section. You can also [nest form groups](#creating-nested-form-groups 'See more about nesting groups') to create more complex forms. |
| Form array  | Defines a dynamic form, where you can add and remove controls at run time. You can also nest form arrays to create more complex forms. For more about this option, see [Creating dynamic forms](#creating-dynamic-forms).                              |

Just as a form control instance gives you control over a single input field, a form group instance tracks the form state of a group of form control instances $for example, a form$.
Each control in a form group instance is tracked by name when creating the form group.
The following example shows how to manage multiple form control instances in a single group.

Generate a `ProfileEditor` component and import the `FormGroup` and `FormControl` classes from the `@angular/forms` package.

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

To add a form group to this component, take the following steps.

1. Create a `FormGroup` instance.
1. Associate the `FormGroup` model and view.
1. Save the form data.

<docs-workflow>

<docs-step title="Create a FormGroup instance">
Create a property in the component class named `profileForm` and set the property to a new form group instance. To initialize the form group, provide the constructor with an object of named keys mapped to their control.

For the profile form, add two form control instances with the names `firstName` and `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"/>

The individual form controls are now collected within a group. A `FormGroup` instance provides its model value as an object reduced from the values of each control in the group. A form group instance has the same properties (such as `value` and `untouched`) and methods (such as `setValue()`) as a form control instance.
</docs-step>

<docs-step title="Associate the FormGroup model and view">
A form group tracks the status and changes for each of its controls, so if one of the controls changes, the parent control also emits a new status or value change. The model for the group is maintained from its members. After you define the model, you must update the template to reflect the model in the view.

<docs-code header="profile-editor.component.html (template form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="formgroup"/>

Just as a form group contains a group of controls, the _profileForm_ `FormGroup` is bound to the `form` element with the `FormGroup` directive, creating a communication layer between the model and the form containing the inputs. The `formControlName` input provided by the `FormControlName` directive binds each individual input to the form control defined in `FormGroup`. The form controls communicate with their respective elements. They also communicate changes to the form group instance, which provides the source of truth for the model value.
</docs-step>

<docs-step title="Save form data">
The `ProfileEditor` component accepts input from the user, but in a real scenario you want to capture the form value and make it available for further processing outside the component. The `FormGroup` directive listens for the `submit` event emitted by the `form` element and emits an `ngSubmit` event that you can bind to a callback function. Add an `ngSubmit` event listener to the `form` tag with the `onSubmit()` callback method.

<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"/>

The `onSubmit()` method in the `ProfileEditor` component captures the current value of `profileForm`. Use `output()` to keep the form encapsulated and to provide the form value outside the component. The following example uses `console.warn` to log a message to the browser console.

<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"/>

The `submit` event is emitted by the `form` tag using the built-in DOM event. You trigger the event by clicking a button with `submit` type. This lets the user press the **Enter** key to submit the completed form.

Use a `button` element to add a button to the bottom of the form to trigger the form submission.

<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"/>

The button in the preceding snippet also has a `disabled` binding attached to it to disable the button when `profileForm` is invalid. You aren't performing any validation yet, so the button is always enabled. Basic form validation is covered in the [Validating form input](#validating-form-input) section.
</docs-step>

<docs-step title="Display the component {#display-the-component-form-group}">
To display the `ProfileEditor` component that contains the form, add it to a component template.

<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` lets you manage the form control instances for the `firstName` and `lastName` controls within the form group instance.
</docs-step>
</docs-workflow>
-->

폼에는 일반적으로 서로 관련된 여러 컨트롤이 있습니다.
반응형 폼은 관련된 컨트롤 여러 개를 하나의 입력 폼으로 묶는 두 가지 방식을 제공합니다.

| 폼 그룹 | 설명                                                                                                                                                                                                                  |
| :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 폼 그룹 | 함께 관리할 고정된 컨트롤 묶음으로 폼을 구성합니다. 폼 그룹의 기본 사용법은 이 섹션에서 설명합니다. [폼 그룹을 중첩](#creating-nested-form-groups '그룹 중첩 자세히 알아보기')하면 더 복잡한 폼을 만들 수도 있습니다. |
| 폼 배열 | 실행 중에 컨트롤을 추가하거나 제거할 수 있는 동적 폼을 구성합니다. 폼 배열을 중첩하면 더 복잡한 폼을 만들 수도 있습니다. 이 방식은 [동적 폼 만들기](#creating-dynamic-forms)를 참고하세요.                            |

폼 컨트롤 인스턴스로 입력 필드 하나를 제어하는 것처럼, 폼 그룹 인스턴스는 폼 컨트롤 인스턴스를 묶은 그룹$예: 폼$의 상태를 추적합니다.
폼 그룹 인스턴스에 속한 각 컨트롤은 폼 그룹을 생성할 때 지정한 이름으로 추적합니다.
다음 예제는 폼 컨트롤 인스턴스 여러 개를 하나의 그룹으로 관리하는 방법입니다.

`ProfileEditor` 컴포넌트를 생성하고 `@angular/forms` 패키지에서 `FormGroup`과 `FormControl` 클래스를 불러오세요.

```shell
ng generate component ProfileEditor
```

<docs-code header="profile-editor.component.ts (불러오기)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="imports"/>

다음 단계를 따라 컴포넌트에 폼 그룹을 추가하세요.

1. `FormGroup` 인스턴스를 생성합니다.
1. `FormGroup` 모델과 뷰를 연결합니다.
1. 폼 데이터를 저장합니다.

<docs-workflow>

<docs-step title="FormGroup 인스턴스 생성하기">
컴포넌트 클래스에 `profileForm` 프로퍼티를 생성하고 새 폼 그룹 인스턴스를 할당하세요.
폼 그룹을 초기화하려면 각 컨트롤의 이름을 키로, 해당 컨트롤을 값으로 지정한 객체를 생성자에 전달합니다.

프로필 폼에는 `firstName`과 `lastName`이라는 이름의 폼 컨트롤 인스턴스 두 개를 추가하세요.

<docs-code header="profile-editor.component.ts (폼 그룹)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="formgroup"/>

이제 개별 폼 컨트롤이 하나의 그룹으로 묶였습니다.
`FormGroup` 인스턴스는 그룹에 속한 각 컨트롤의 값을 하나의 객체로 모아서 모델 값으로 제공합니다.
폼 그룹 인스턴스는 폼 컨트롤 인스턴스와 마찬가지로 `value`, `untouched` 같은 프로퍼티와 `setValue()` 같은 메서드를 제공합니다.
</docs-step>

<docs-step title="FormGroup 모델과 뷰 연결하기">
폼 그룹은 각 컨트롤의 상태와 변화를 추적합니다.
따라서 컨트롤 하나가 바뀌면 부모 컨트롤도 새로운 상태나 값의 변화를 방출합니다.
그룹의 모델은 그룹에 속한 컨트롤을 기반으로 유지됩니다.
모델을 정의했으면 템플릿을 수정해서 모델이 뷰에 반영되도록 해야 합니다.

<docs-code header="profile-editor.component.html (템플릿 폼 그룹)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="formgroup"/>

폼 그룹이 여러 컨트롤을 묶는 것처럼, _profileForm_ `FormGroup`은 `FormGroup` 디렉티브로 `form` 엘리먼트에 바인딩됩니다.
이렇게 하면 모델과 입력 엘리먼트가 있는 폼 사이에서 정보를 주고받는 연결 계층이 만들어집니다.
`FormControlName` 디렉티브가 제공하는 `formControlName` 입력 프로퍼티는 각 입력 엘리먼트를 `FormGroup`에 정의된 폼 컨트롤과 연결합니다.
폼 컨트롤은 각자의 엘리먼트와 정보를 주고받습니다.
그리고 모델 값의 원본 데이터를 관리하는 폼 그룹 인스턴스에도 변화를 전달합니다.
</docs-step>

<docs-step title="폼 데이터 저장하기">
`ProfileEditor` 컴포넌트는 사용자 입력을 받지만, 실제 애플리케이션에서는 폼 값을 가져와 컴포넌트 밖에서 추가로 처리할 수 있어야 합니다.
`FormGroup` 디렉티브는 `form` 엘리먼트가 발생시키는 `submit` 이벤트를 감지하고, 콜백 함수를 바인딩할 수 있는 `ngSubmit` 이벤트를 발생시킵니다.
`form` 태그에 `ngSubmit` 이벤트 리스너를 추가하고 `onSubmit()` 메서드를 콜백으로 연결하세요.

<docs-code header="profile-editor.component.html (제출 이벤트)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="ng-submit"/>

`ProfileEditor` 컴포넌트의 `onSubmit()` 메서드는 `profileForm`의 현재 값을 가져옵니다.
`output()`을 사용하면 폼을 캡슐화하면서 컴포넌트 밖으로 폼 값을 전달할 수 있습니다.
다음 예제에서는 `console.warn`으로 브라우저 콘솔에 메시지를 출력합니다.

<docs-code header="profile-editor.component.ts (제출 메서드)" 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 (제출 버튼)" 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-form-group}">
폼이 있는 `ProfileEditor` 컴포넌트를 표시하려면 컴포넌트 템플릿에 추가하세요.

<docs-code header="app.component.html (프로필 편집기)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" region="app-profile-editor"/>

`ProfileEditor`에서는 폼 그룹 인스턴스 안에서 `firstName`과 `lastName` 컨트롤의 폼 컨트롤 인스턴스를 관리할 수 있습니다.
</docs-step>
</docs-workflow>

### 폼 그룹 중첩하기

<!--
Form groups can accept both individual form control instances and other form group instances as children.
This makes composing complex form models easier to maintain and logically group together.

When building complex forms, managing the different areas of information is easier in smaller sections.
Using a nested form group instance lets you break large forms groups into smaller, more manageable ones.

To make more complex forms, use the following steps.

1. Create a nested group.
1. Group the nested form in the template.

Some types of information naturally fall into the same group.
A name and address are typical examples of such nested groups, and are used in the following examples.

<docs-workflow>
<docs-step title="Create a nested group">
To create a nested group in `profileForm`, add a nested `address` element to the form group instance.

<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"/>

In this example, `address group` combines the current `firstName` and `lastName` controls with the new `street`, `city`, `state`, and `zip` controls. Even though the `address` element in the form group is a child of the overall `profileForm` element in the form group, the same rules apply with value and status changes. Changes in status and value from the nested form group propagate to the parent form group, maintaining consistency with the overall model.
</docs-step>

<docs-step title="Group the nested form in the template">
After you update the model in the component class, update the template to connect the form group instance and its input elements. Add the `address` form group containing the `street`, `city`, `state`, and `zip` fields to the `ProfileEditor` template.

<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"/>

The `ProfileEditor` form is displayed as one group, but the model is broken down further to represent the logical grouping areas.

Display the value for the form group instance in the component template using the `value` property and `JsonPipe`.
</docs-step>
</docs-workflow>
-->

폼 그룹은 개별 폼 컨트롤 인스턴스뿐 아니라 다른 폼 그룹 인스턴스도 자식으로 가질 수 있습니다.
따라서 복잡한 폼 모델도 논리적으로 묶어서 구성하고 유지보수하기 쉽습니다.

복잡한 폼을 구성할 때는 정보를 작은 영역으로 나누면 관리하기 쉽습니다.
폼 그룹 인스턴스를 중첩하면 큰 폼 그룹을 관리하기 쉬운 작은 그룹으로 나눌 수 있습니다.

더 복잡한 폼을 구성하려면 다음 단계를 진행하세요.

1. 중첩 그룹을 생성합니다.
1. 템플릿에서 중첩 폼을 그룹으로 묶습니다.

일부 정보는 자연스럽게 같은 그룹으로 묶입니다.
이름과 주소는 중첩 그룹으로 묶기 좋은 대표적인 예이며, 다음 예제에서도 사용합니다.

<docs-workflow>
<a id="create-a-nested-group"></a>

<docs-step title="중첩 그룹 생성하기">
`profileForm`에 중첩 그룹을 생성하려면 폼 그룹 인스턴스에 `address` 엘리먼트를 중첩해서 추가하세요.

<docs-code header="profile-editor.component.ts (중첩 폼 그룹)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="nested-formgroup"/>

이 예제에서는 `address group`을 추가해서 기존 `firstName`, `lastName` 컨트롤과 새로운 `street`, `city`, `state`, `zip` 컨트롤을 함께 구성합니다.
폼 그룹의 `address` 엘리먼트는 전체 `profileForm` 엘리먼트의 자식이지만, 값과 상태가 바뀔 때 적용되는 규칙은 같습니다.
중첩 폼 그룹에서 상태와 값이 바뀌면 부모 폼 그룹으로 전파되기 때문에 전체 모델의 일관성이 유지됩니다.
</docs-step>

<docs-step title="템플릿에서 중첩 폼을 그룹으로 묶기">
컴포넌트 클래스의 모델을 갱신했으면 폼 그룹 인스턴스와 입력 엘리먼트가 연결되도록 템플릿을 수정하세요.
`ProfileEditor` 템플릿에 `street`, `city`, `state`, `zip` 필드가 있는 `address` 폼 그룹을 추가하세요.

<docs-code header="profile-editor.component.html (템플릿 중첩 폼 그룹)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="formgroupname"/>

`ProfileEditor` 폼은 하나의 그룹으로 표시되지만, 모델은 논리적으로 묶인 영역을 표현하도록 더 작게 나뉩니다.

컴포넌트 템플릿에서 `value` 프로퍼티와 `JsonPipe`로 폼 그룹 인스턴스의 값을 표시하세요.
</docs-step>
</docs-workflow>

### 데이터 모델 일부 갱신하기

<!--
When updating the value for a form group instance that contains multiple controls, you might only want to update parts of the model.
This section covers how to update specific parts of a form control data model.

There are two ways to update the model value:

| Methods        | Details                                                                                                                                                               |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setValue()`   | Set a new value for an individual control. The `setValue()` method strictly adheres to the structure of the form group and replaces the entire value for the control. |
| `patchValue()` | Replace any properties defined in the object that have changed in the form model.                                                                                     |

The strict checks of the `setValue()` method help catch nesting errors in complex forms, while `patchValue()` fails silently on those errors.

In `ProfileEditorComponent`, use the `updateProfile` method with the following example to update the first name and street address for the user.

<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"/>

Simulate an update by adding a button to the template to update the user profile on demand.

<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"/>

When a user clicks the button, the `profileForm` model is updated with new values for `firstName` and `street`. Notice that `street` is provided in an object inside the `address` property.
This is necessary because the `patchValue()` method applies the update against the model structure.
`patchValue()` only updates properties that the form model defines.
-->

컨트롤이 여러 개 있는 폼 그룹 인스턴스의 값을 갱신할 때는 모델의 일부만 갱신하고 싶을 수 있습니다.
이 섹션에서는 폼 컨트롤 데이터 모델의 특정 부분만 갱신하는 방법을 알아봅니다.

모델 값을 갱신하는 방법은 두 가지입니다.

| 메서드         | 설명                                                                                                                    |
| :------------- | :---------------------------------------------------------------------------------------------------------------------- |
| `setValue()`   | 개별 컨트롤에 새 값을 지정합니다. `setValue()` 메서드는 폼 그룹의 구조를 엄격하게 따르며 컨트롤의 값 전체를 교체합니다. |
| `patchValue()` | 전달한 객체에 정의된 프로퍼티에 해당하는 폼 모델 값을 교체합니다.                                                       |

`setValue()` 메서드는 엄격하게 검사하기 때문에 복잡한 폼의 중첩 구조에서 발생한 오류를 발견하는 데 도움이 됩니다.
반면 `patchValue()`는 이런 오류가 발생해도 알리지 않고 실패합니다.

`ProfileEditorComponent`에서 다음 예제처럼 `updateProfile` 메서드를 사용하면 사용자의 이름과 도로명 주소를 갱신할 수 있습니다.

<docs-code header="profile-editor.component.ts (값 일부 갱신)" 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 (값 갱신)" 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 서비스로 컨트롤 생성하기

<!--
Creating form control instances manually can become repetitive when dealing with multiple forms.
The `FormBuilder` service provides convenient methods for generating controls.

Use the following steps to take advantage of this service.

1. Import the `FormBuilder` class.
1. Inject the `FormBuilder` service.
1. Generate the form contents.

The following examples show how to refactor the `ProfileEditor` component to use the form builder service to create form control and form group instances.

<docs-workflow>
<docs-step title="Import the FormBuilder class">
Import the `FormBuilder` class from the `@angular/forms` package.

<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">
The `FormBuilder` service is an injectable provider from the reactive forms module. Use the `inject()` function to inject this dependency in your component.

<docs-code header="profile-editor.component.ts (property init)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="inject-form-builder"/>

</docs-step>
<docs-step title="Generate form controls">
The `FormBuilder` service has four methods: `control()`, `group()`, `record()`, and `array()`. These are factory methods for generating instances in your component classes including form controls, form groups, form records, and form arrays. Use the `group` method to create the `profileForm` controls.

<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"/>

In the preceding example, you use the `group()` method with the same object to define the properties in the model. The value for each control name is an array containing the initial value as the first item in the array.

TIP: You can define the control with just the initial value, but if your controls need sync or async validation, add sync and async validators as the second and third items in the array. Compare using the form builder to creating the instances manually.
</docs-step>

</docs-workflow>
-->

여러 폼을 다루다 보면 폼 컨트롤 인스턴스를 직접 생성하는 작업이 반복될 수 있습니다.
`FormBuilder` 서비스는 컨트롤을 간편하게 생성하는 메서드를 제공합니다.

다음 단계를 따라 이 서비스를 사용해 보세요.

1. `FormBuilder` 클래스를 불러옵니다.
1. `FormBuilder` 서비스를 의존성으로 주입합니다.
1. 폼 내용을 생성합니다.

다음 예제에서는 폼 빌더 서비스로 폼 컨트롤과 폼 그룹 인스턴스를 생성하도록 `ProfileEditor` 컴포넌트를 리팩토링합니다.

<docs-workflow>
<a id="import-the-formbuilder-class"></a>

<docs-step title="FormBuilder 클래스 불러오기">
`@angular/forms` 패키지에서 `FormBuilder` 클래스를 불러오세요.

<docs-code header="profile-editor.component.ts (불러오기)" 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="FormBuilder 서비스 주입하기">
`FormBuilder` 서비스는 반응형 폼 모듈에서 제공하는 주입 가능한 프로바이더입니다.
`inject()` 함수로 이 의존성을 컴포넌트에 주입하세요.

<docs-code header="profile-editor.component.ts (프로퍼티 초기화)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="inject-form-builder"/>

</docs-step>
<a id="generate-form-controls"></a>

<docs-step title="폼 컨트롤 생성하기">
`FormBuilder` 서비스에는 `control()`, `group()`, `record()`, `array()`라는 네 가지 메서드가 있습니다.
이 메서드는 컴포넌트 클래스에서 폼 컨트롤, 폼 그룹, 폼 레코드, 폼 배열 인스턴스를 생성하는 팩토리 메서드입니다.
`group` 메서드로 `profileForm`의 컨트롤을 생성하세요.

<docs-code header="profile-editor.component.ts (폼 빌더)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-builder"/>

위 예제에서는 같은 객체를 `group()` 메서드에 전달해서 모델의 프로퍼티를 정의합니다.
각 컨트롤 이름에 대응하는 값은 배열이며, 배열의 첫 번째 항목이 초기값입니다.

팁: 초기값만으로 컨트롤을 정의할 수도 있습니다.
하지만 컨트롤에 동기 또는 비동기 유효성 검사가 필요하다면 배열의 두 번째와 세 번째 항목에 각각 동기 유효성 검사기와 비동기 유효성 검사기를 추가하세요.
폼 빌더를 사용하는 방식과 인스턴스를 직접 생성하는 방식을 비교해 보세요.
</docs-step>

</docs-workflow>

## 폼 입력 유효성 검사하기

<!--
_Form validation_ is used to ensure that user input is complete and correct.
This section covers adding a single validator to a form control and displaying the overall form status.
Form validation is covered more extensively in the [Form Validation](guide/forms/form-validation) guide.

Use the following steps to add form validation.

1. Import a validator function in your form component.
1. Add the validator to the field in the form.
1. Add logic to handle the validation status.

The most common validation is making a field required.
The following example shows how to add a required validation to the `firstName` control and display the result of validation.

<docs-workflow>
<docs-step title="Import a validator function">
Reactive forms include a set of validator functions for common use cases. These functions receive a control to validate against and return an error object or a null value based on the validation check.

Import the `Validators` class from the `@angular/forms` package.

<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">
In the `ProfileEditor` component, add the `Validators.required` static method as the second item in the array for the `firstName` control.

<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">
When you add a required field to the form control, its initial status is invalid. This invalid status propagates to the parent form group element, making its status invalid. Access the current status of the form group instance through its `status` property.

Display the current status of `profileForm` using interpolation.

<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"/>

The **Submit** button is disabled because `profileForm` is invalid due to the required `firstName` form control. After you fill out the `firstName` input, the form becomes valid and the **Submit** button is enabled.

For more on form validation, visit the [Form Validation](guide/forms/form-validation) guide.
</docs-step>
</docs-workflow>
-->

*폼 유효성 검사*는 사용자 입력이 빠짐없이 올바르게 작성되었는지 확인할 때 사용합니다.
이 섹션에서는 폼 컨트롤에 유효성 검사기 하나를 추가하고 전체 폼 상태를 표시하는 방법을 알아봅니다.
폼 유효성 검사에 관한 더 자세한 내용은 [폼 유효성 검사](guide/forms/form-validation) 문서를 참고하세요.

폼 유효성 검사를 추가하려면 다음 단계를 진행하세요.

1. 폼 컴포넌트에 유효성 검사 함수를 불러옵니다.
1. 폼의 필드에 유효성 검사기를 추가합니다.
1. 유효성 검사 상태를 처리하는 로직을 추가합니다.

가장 흔한 유효성 검사는 필드를 필수로 지정하는 것입니다.
다음 예제에서는 `firstName` 컨트롤에 필수 입력 검사를 추가하고 유효성 검사 결과를 표시합니다.

<docs-workflow>
<a id="import-a-validator-function"></a>

<docs-step title="유효성 검사 함수 불러오기">
반응형 폼에는 자주 사용하는 유효성 검사 함수가 포함되어 있습니다.
이 함수는 검사할 컨트롤을 인자로 받아 유효성 검사 결과에 따라 오류 객체나 null 값을 반환합니다.

`@angular/forms` 패키지에서 `Validators` 클래스를 불러오세요.

<docs-code header="profile-editor.component.ts (불러오기)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="validator-imports"/>
</docs-step>

<docs-step title="필수 필드 지정하기">
`ProfileEditor` 컴포넌트에서 `firstName` 컨트롤 배열의 두 번째 항목에 `Validators.required` 정적 메서드를 추가하세요.

<docs-code header="profile-editor.component.ts (필수 입력 검사기)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="required-validator"/>
</docs-step>

<docs-step title="폼 상태 표시하기">
폼 컨트롤에 필수 필드를 추가하면 초기 상태는 유효하지 않은 상태입니다.
이 상태는 부모 폼 그룹 엘리먼트로 전파되기 때문에 부모도 유효하지 않은 상태가 됩니다.
폼 그룹 인스턴스의 현재 상태는 `status` 프로퍼티로 확인할 수 있습니다.

문자열 바인딩으로 `profileForm`의 현재 상태를 표시하세요.

<docs-code header="profile-editor.component.html (상태 표시)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="display-status"/>

필수 폼 컨트롤인 `firstName` 때문에 `profileForm`이 유효하지 않으므로 **Submit** 버튼은 비활성화됩니다.
`firstName` 입력란을 채우면 폼이 유효한 상태가 되고 **Submit** 버튼이 활성화됩니다.

폼 유효성 검사가 더 궁금하면 [폼 유효성 검사](guide/forms/form-validation) 문서를 참고하세요.
</docs-step>
</docs-workflow>

## 동적 폼 만들기

<!--
`FormArray` is an alternative to `FormGroup` for managing any number of unnamed controls.
As with form group instances, you can dynamically insert and remove controls from form array instances, and the form array instance value and validation status is calculated from its child controls.
However, you don't need to define a key for each control by name, so this is a great option if you don't know the number of child values in advance.

To define a dynamic form, take the following steps.

1. Import the `FormArray` class.
1. Define a `FormArray` control.
1. Access the `FormArray` control with a getter method.
1. Display the form array in a template.

The following example shows you how to manage an array of _aliases_ in `ProfileEditor`.

<docs-workflow>
<docs-step title="Import the `FormArray` class">
Import the `FormArray` class from `@angular/forms` to use for type information. The `FormBuilder` service is ready to create a `FormArray` instance.

<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">
You can initialize a form array with any number of controls, from zero to many, by defining them in an array. Add an `aliases` property to the form group instance for `profileForm` to define the form array.

Use the `FormBuilder.array()` method to define the array, and the `FormBuilder.control()` method to populate the array with an initial 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"/>

The aliases control in the form group instance is now populated with a single control until more controls are added dynamically.
</docs-step>

<docs-step title="Access the `FormArray` control">
A getter provides access to the aliases in the form array instance compared to repeating the `profileForm.get()` method to get each instance. The form array instance represents an undefined number of controls in an array. It's convenient to access a control through a getter, and this approach is straightforward to repeat for additional controls. <br />

Use the getter syntax to create an `aliases` class property to retrieve the alias's form array control from the parent 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"/>

Because the returned control is of the type `AbstractControl`, you need to provide an explicit type to access the method syntax for the form array instance. Define a method to dynamically insert an alias control into the alias's form array. The `FormArray.push()` method inserts the control as a new item in the array, and you can also pass an array of controls to FormArray.push() to register multiple controls at once.

<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"/>

In the template, each control is displayed as a separate input field.

</docs-step>

<docs-step title="Display the form array in the template">

To attach the aliases from your form model, you must add it to the template. Similar to the `formGroupName` input provided by `FormGroupName`, `formArrayName` binds communication from the form array instance to the template with `FormArrayName`.

Add the following template HTML after the `<div>` closing the `formGroupName` element.

<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"/>

The `@for` block iterates over each form control instance provided by the aliases form array instance. Because form array elements are unnamed, you assign the index to the `i` variable and pass it to each control to bind it to the `formControlName` input.

Each time a new alias instance is added, the new form array instance is provided its control based on the index. This lets you track each individual control when calculating the status and value of the root control.

NOTE: In zoneless applications, mutating a reactive forms model (for example calling `FormArray.push()`) does not automatically schedule component change detection. If your template depends on structural model changes such as `aliases.controls`, make sure the component notifies Angular to run change detection, for example by bridging a forms observable to `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>
-->

`FormArray`는 이름이 없는 컨트롤을 개수 제한 없이 관리할 때 `FormGroup` 대신 사용할 수 있습니다.
폼 그룹 인스턴스와 마찬가지로 폼 배열 인스턴스에도 컨트롤을 동적으로 추가하거나 제거할 수 있습니다.
폼 배열 인스턴스의 값과 유효성 검사 상태는 자식 컨트롤을 기준으로 계산됩니다.
하지만 각 컨트롤에 이름으로 된 키를 정의하지 않아도 되기 때문에 자식 값의 개수를 미리 알 수 없을 때 유용합니다.

동적 폼을 정의하려면 다음 단계를 진행하세요.

1. `FormArray` 클래스를 불러옵니다.
1. `FormArray` 컨트롤을 정의합니다.
1. getter 메서드로 `FormArray` 컨트롤에 접근합니다.
1. 템플릿에 폼 배열을 표시합니다.

다음 예제는 `ProfileEditor`에서 _별칭(aliases)_ 배열을 관리하는 방법입니다.

<docs-workflow>
<a id="import-the-formarray-class"></a>

<docs-step title="`FormArray` 클래스 불러오기">
타입 정보로 사용할 `FormArray` 클래스를 `@angular/forms`에서 불러오세요.
`FormBuilder` 서비스는 `FormArray` 인스턴스를 생성할 준비가 되어 있습니다.

<docs-code header="profile-editor.component.ts (불러오기)" 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="`FormArray` 컨트롤 정의하기">
배열에 컨트롤을 정의하면 컨트롤이 없는 폼 배열부터 여러 컨트롤이 있는 폼 배열까지 원하는 개수로 초기화할 수 있습니다.
`profileForm`의 폼 그룹 인스턴스에 `aliases` 프로퍼티를 추가해서 폼 배열을 정의하세요.

`FormBuilder.array()` 메서드로 배열을 정의하고, `FormBuilder.control()` 메서드로 배열에 초기 컨트롤을 추가하세요.

<docs-code header="profile-editor.component.ts (별칭 폼 배열)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="aliases"/>

이제 폼 그룹 인스턴스의 aliases 컨트롤에는 컨트롤이 하나 들어 있습니다.
이후에 컨트롤을 동적으로 더 추가할 수 있습니다.
</docs-step>

<docs-step title="`FormArray` 컨트롤에 접근하기">
각 인스턴스를 가져올 때마다 `profileForm.get()` 메서드를 호출하는 대신 getter로 폼 배열 인스턴스의 별칭에 접근할 수 있습니다.
폼 배열 인스턴스는 개수가 정해지지 않은 컨트롤을 배열로 표현합니다.
getter를 사용하면 컨트롤에 편리하게 접근할 수 있고, 다른 컨트롤에도 같은 방식을 간단하게 적용할 수 있습니다. <br />

getter 문법으로 `aliases` 클래스 프로퍼티를 생성해서 부모 폼 그룹에서 별칭의 폼 배열 컨트롤을 가져오세요.

<docs-code header="profile-editor.component.ts (별칭 getter)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="aliases-getter"/>

반환되는 컨트롤의 타입은 `AbstractControl`이기 때문에 폼 배열 인스턴스의 메서드를 사용하려면 타입을 명시해야 합니다.
별칭의 폼 배열에 별칭 컨트롤을 동적으로 추가하는 메서드를 정의하세요.
`FormArray.push()` 메서드는 컨트롤을 배열의 새 항목으로 추가합니다.
FormArray.push()에 컨트롤 배열을 전달하면 여러 컨트롤을 한 번에 등록할 수도 있습니다.

<docs-code header="profile-editor.component.ts (별칭 추가)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="add-alias"/>

템플릿에서는 각 컨트롤이 개별 입력 필드로 표시됩니다.

</docs-step>

<docs-step title="템플릿에 폼 배열 표시하기">

폼 모델의 별칭을 연결하려면 템플릿에 추가해야 합니다.
`FormGroupName`이 제공하는 `formGroupName` 입력 프로퍼티와 비슷하게, `formArrayName`은 `FormArrayName`을 통해 폼 배열 인스턴스와 템플릿을 연결합니다.

`formGroupName` 엘리먼트를 닫는 `<div>` 뒤에 다음 템플릿 HTML을 추가하세요.

<docs-code header="profile-editor.component.html (별칭 폼 배열 템플릿)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="formarrayname"/>

`@for` 블록은 aliases 폼 배열 인스턴스에 있는 폼 컨트롤 인스턴스를 하나씩 순회합니다.
폼 배열의 항목에는 이름이 없기 때문에 인덱스를 `i` 변수에 할당한 다음 각 컨트롤에 전달해서 `formControlName` 입력 프로퍼티에 바인딩합니다.

새 별칭 인스턴스가 추가될 때마다 새 폼 배열 인스턴스에는 인덱스를 기준으로 컨트롤이 연결됩니다.
따라서 최상위 컨트롤의 상태와 값을 계산할 때 각 컨트롤을 추적할 수 있습니다.

참고: 존리스 애플리케이션에서 반응형 폼 모델을 변경해도(예: `FormArray.push()` 호출) 컴포넌트 변경 감지가 자동으로 예약되지는 않습니다.
템플릿이 `aliases.controls`처럼 모델 구조의 변화에 의존한다면, 컴포넌트가 Angular에 변경 감지 실행을 알리도록 해야 합니다.
예를 들어 폼 옵저버블을 `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` 사용하기

<!--
You can bind a `FormArray` directly to a `<form>` element by using the `FormArrayDirective`.
This is useful when the form does not use a top-level `FormGroup`, and the array itself represents the full form model.

```typescript
import {Component} from '@angular/core';
import {FormArray, FormControl, ReactiveFormsModule} from '@angular/forms';

@Component({
  selector: 'form-array-example',
  imports: [ReactiveFormsModule],
  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">

Initially, the form contains one `Alias` field. To add another field, click the **Add Alias** button. You can also validate the array of aliases reported by the form model displayed by `Form Value` at the bottom of the template. Instead of a form control instance for each alias, you can compose another form group instance with additional fields. The process of defining a control for each item is the same.
</docs-step>

</docs-workflow>
-->

`FormArrayDirective`를 사용하면 `FormArray`를 `<form>` 엘리먼트에 직접 바인딩할 수 있습니다.  
최상위 `FormGroup` 없이 배열 자체가 전체 폼 모델을 나타내는 경우에 유용합니다.

```typescript
import {Component} from '@angular/core';
import {FormArray, FormControl, ReactiveFormsModule} from '@angular/forms';

form = new FormArray(this.controls);
}
```

<docs-step title="별칭 추가하기">

처음에는 폼에 `Alias` 필드가 하나 있습니다.
필드를 추가하려면 **Add Alias** 버튼을 클릭하세요.
템플릿 아래쪽의 `Form Value`에 표시된 폼 모델을 통해 별칭 배열을 확인할 수도 있습니다.
별칭마다 폼 컨트롤 인스턴스를 사용하는 대신, 추가 필드가 있는 다른 폼 그룹 인스턴스를 구성할 수도 있습니다.
각 항목의 컨트롤을 정의하는 과정은 같습니다.
</docs-step>

</docs-workflow>

## 통합 컨트롤 상태 변경 이벤트

모든 폼 컨트롤은 `AbstractControl`(`FormControl`, `FormGroup`, `FormArray`, `FormRecord`)의 `events` 옵저버블을 통해 **컨트롤 상태 변경 이벤트**를 하나의 통합 스트림으로 제공합니다.
이 통합 스트림을 사용하면 **값**, **상태**, **pristine**, **touched**, **초기화** 상태의 변화뿐 아니라 **제출** 같은 **폼 수준의 동작**에도 대응할 수 있습니다.
여러 옵저버블을 연결하는 대신 한 번의 구독으로 모든 갱신을 처리할 수 있습니다.

### 이벤트 타입

<!--
Each item emitted by `events` is an instance of a specific event class:

- **`ValueChangeEvent`** — when the control’s **value** changes.
- **`StatusChangeEvent`** — when the control’s **validation status** updates to one of the `FormControlStatus` values (`VALID`, `INVALID`, `PENDING`, or `DISABLED`).
- **`PristineChangeEvent`** — when the control’s **pristine/dirty** state changes.
- **`TouchedChangeEvent`** — when the control’s **touched/untouched** state changes.
- **`FormResetEvent`** — when a control or form is reset, either via the `reset()` API or a native action.
- **`FormSubmittedEvent`** — when the form is submitted.

All event classes extend `ControlEvent` and include a `source` reference to the `AbstractControl` that originated the change, which is useful in large forms.

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

`events`가 방출하는 각 항목은 특정 이벤트 클래스의 인스턴스입니다.

- **`ValueChangeEvent`** — 컨트롤의 **값**이 바뀔 때 발생합니다.
- **`StatusChangeEvent`** — 컨트롤의 **유효성 검사 상태**가 `FormControlStatus` 값(`VALID`, `INVALID`, `PENDING`, `DISABLED`) 중 하나로 갱신될 때 발생합니다.
- **`PristineChangeEvent`** — 컨트롤의 **pristine/dirty** 상태가 바뀔 때 발생합니다.
- **`TouchedChangeEvent`** — 컨트롤의 **touched/untouched** 상태가 바뀔 때 발생합니다.
- **`FormResetEvent`** — `reset()` API나 기본 동작으로 컨트롤 또는 폼이 초기화될 때 발생합니다.
- **`FormSubmittedEvent`** — 폼이 제출될 때 발생합니다.

모든 이벤트 클래스는 `ControlEvent`를 상속하며, 변화가 시작된 `AbstractControl`을 가리키는 `source` 참조를 포함합니다.
이 참조는 큰 폼을 다룰 때 유용합니다.

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

### 특정 이벤트 필터링하기

<!--
Prefer RxJS operators when you only need a subset of event types.

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

일부 이벤트 타입만 필요하다면 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));
```

### 여러 구독을 하나로 통합하기

<!--
**Before**

```ts
import {combineLatest} from 'rxjs';

combineLatest([control.valueChanges, control.statusChanges]).subscribe(([value, status]) => {
  /* ... */
});
```

**After**

```ts
control.events.subscribe((e) => {
  // Handle ValueChangeEvent, StatusChangeEvent, etc.
});
```

NOTE: On value change, the emit happens right after a value of this control is updated. The value of a parent control (for example if this FormControl is a part of a FormGroup) is updated later, so accessing a value of a parent control (using the `value` property) from the callback of this event might result in getting a value that has not been updated yet. Subscribe to the `events` of the parent control instead.
-->

**변경 전**

```ts
import {combineLatest} from 'rxjs';

combineLatest([control.valueChanges, control.statusChanges]).subscribe(([value, status]) => {
  /* ... */
});
```

**변경 후**

```ts
control.events.subscribe((e) => {
  // ValueChangeEvent, StatusChangeEvent 등의 이벤트를 처리합니다.
});
```

참고: 값 변경 이벤트는 해당 컨트롤의 값이 갱신된 직후에 방출됩니다.
부모 컨트롤의 값(예: 이 FormControl이 FormGroup에 속한 경우)은 나중에 갱신됩니다.
따라서 이 이벤트의 콜백에서 부모 컨트롤의 `value` 프로퍼티에 접근하면 아직 갱신되지 않은 값을 가져올 수 있습니다.
이런 경우에는 부모 컨트롤의 `events`를 구독하세요.

## 폼 컨트롤 상태 관리하기

<!--
Reactive forms track control state through **touched/untouched** and **pristine/dirty**. Angular updates these automatically during DOM interactions, but you can also manage them programmatically.

**[`markAsTouched`](api/forms/FormControl#markAsTouched)** — Marks a control or form as touched by focus and blur events that do not change the value. Propagates to parent controls by default.

```ts
// Show validation errors after user leaves a field
onEmailBlur() {
  const email = this.form.get('email');
  email.markAsTouched();
}
```

**[`markAsUntouched`](api/forms/FormControl#markAsUntouched)** — Marks a control or form as untouched. Cascades to all child controls and recalculates the touched status of all parent controls.

```ts
// Reset form state after successful submission
onSubmitSuccess() {
  this.form.markAsUntouched();
  this.form.markAsPristine();
}
```

**[`markAsDirty`](api/forms/FormControl#markAsDirty)** — Marks a control or form as dirty, meaning the value has been changed. Propagates to parent controls by default.

```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)** — Marks a control or form as pristine. Marks all child controls as pristine and recalculates the pristine status of all parent 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)** — Marks the control or form and all its descendant controls as dirty.

```ts
// Mark imported data as dirty
loadData(data: FormData) {
  this.form.patchValue(data);
  this.form.markAllAsDirty();
}
```

**[`markAllAsTouched`](api/forms/FormControl#markAllAsTouched)** — Marks the control or form and all its descendant controls as touched. Useful for showing validation errors across the entire form.

```ts
// Show all validation errors before submission
onSubmit() {
  if (this.form.invalid) {
    this.form.markAllAsTouched();
    return;
  }
  this.saveForm();
}
```
-->

반응형 폼은 **touched/untouched**와 **pristine/dirty**로 컨트롤 상태를 추적합니다.
Angular는 DOM 상호작용이 발생하면 이 상태를 자동으로 갱신하지만, 코드로 직접 관리할 수도 있습니다.

**[`markAsTouched`](api/forms/FormControl#markAsTouched)** — 값을 바꾸지 않는 focus와 blur 이벤트로 상호작용한 상태를 나타내도록 컨트롤이나 폼을 touched로 표시합니다.
기본적으로 부모 컨트롤로 전파됩니다.

```ts
// 사용자가 필드에서 벗어나면 유효성 검사 에러를 표시합니다.
onEmailBlur() {
  const email = this.form.get('email');
  email.markAsTouched();
}
```

**[`markAsUntouched`](api/forms/FormControl#markAsUntouched)** — 컨트롤이나 폼을 untouched로 표시합니다.
모든 자식 컨트롤에 적용되고, 모든 부모 컨트롤의 touched 상태를 다시 계산합니다.

```ts
// 제출에 성공하면 폼 상태를 초기화합니다.
onSubmitSuccess() {
  this.form.markAsUntouched();
  this.form.markAsPristine();
}
```

**[`markAsDirty`](api/forms/FormControl#markAsDirty)** — 값이 변경되었다는 의미로 컨트롤이나 폼을 dirty로 표시합니다.
기본적으로 부모 컨트롤로 전파됩니다.

```ts
// 코드로 바꾼 값을 변경된 상태로 표시합니다.
autofillAddress() {
  const previousAddress = getAddress();
  this.form.patchValue(previousAddress, { emitEvent: false });
  this.form.markAsDirty();
}
```

**[`markAsPristine`](api/forms/FormControl#markAsPristine)** — 컨트롤이나 폼을 pristine으로 표시합니다.
모든 자식 컨트롤을 pristine으로 표시하고, 모든 부모 컨트롤의 pristine 상태를 다시 계산합니다.

```ts
// 저장 후 pristine 상태를 초기화해서 새로운 변경사항을 추적합니다.
saveForm() {
  this.api.save(this.form.value).subscribe(() => {
    this.form.markAsPristine();
  });
}
```

**[`markAllAsDirty`](api/forms/FormControl#markAllAsDirty)** — 컨트롤이나 폼과 그 아래에 있는 모든 하위 컨트롤을 dirty로 표시합니다.

```ts
// 가져온 데이터를 dirty 상태로 표시합니다.
loadData(data: FormData) {
  this.form.patchValue(data);
  this.form.markAllAsDirty();
}
```

**[`markAllAsTouched`](api/forms/FormControl#markAllAsTouched)** — 컨트롤이나 폼과 그 아래에 있는 모든 하위 컨트롤을 touched로 표시합니다.
전체 폼의 유효성 검사 오류를 표시할 때 유용합니다.

```ts
// 제출하기 전에 모든 유효성 검사 에러를 표시합니다.
onSubmit() {
  if (this.form.invalid) {
    this.form.markAllAsTouched();
    return;
  }
  this.saveForm();
}
```

## 이벤트 방출과 전파 제어하기

폼 컨트롤을 코드로 갱신할 때는 변화가 폼 계층에 전파되는 방식과 이벤트 방출 여부를 세밀하게 제어할 수 있습니다.

### 이벤트 방출 이해하기

<!--
By default `emitEvent: true`, any change to a control emits events through the `valueChanges` and `statusChanges` observables. Setting `emitEvent: false` suppresses these emissions, which is useful when setting values programmatically without triggering reactive behavior like auto-save, avoiding circular updates between controls, or performing bulk updates where events should emit only once at the end.

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

기본값은 `emitEvent: true`이므로 컨트롤이 바뀔 때마다 `valueChanges`와 `statusChanges` 옵저버블에서 이벤트가 방출됩니다.
`emitEvent: false`로 설정하면 이 이벤트가 방출되지 않습니다.
자동 저장 같은 반응형 동작을 실행하지 않고 코드로 값을 설정하거나, 컨트롤 사이의 순환 갱신을 방지하거나, 일괄 갱신이 끝날 때 이벤트를 한 번만 방출하려는 경우에 유용합니다.

```ts
@Component({/* ... */})
export class BlogPostEditor {
  postForm = new FormGroup({
    title: new FormControl(''),
    content: new FormControl(''),
  });

constructor() {
    // 사용자가 입력할 때마다 초안을 자동으로 저장합니다.
    this.postForm.valueChanges.subscribe((formValue) => {
      this.autosaveDraft(formValue);
    });
  }

loadExistingDraft(savedDraft: {title: string; content: string}) {
    // 자동 저장을 실행하지 않고 초안을 복원합니다.
    this.postForm.setValue(savedDraft, {emitEvent: false});
  }
}
```

### 전파 제어 이해하기

<!--
By default `onlySelf: false`, updates cascade to parent controls, recalculating their values and validation status. Setting `onlySelf: true` isolates the update to the current control, preventing parent notification. This is useful for batch operations where you want to manually trigger the parent update once.

```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: For dynamically managing validators at runtime, see the [Managing validators dynamically in reactive forms](guide/forms/form-validation#managing-validators-dynamically-in-reactive-forms) section in the Form Validation guide.
-->

기본값은 `onlySelf: false`이므로 갱신이 부모 컨트롤로 전파되어 부모의 값과 유효성 검사 상태도 다시 계산됩니다.
`onlySelf: true`로 설정하면 현재 컨트롤만 갱신하고 부모에게 알리지 않습니다.
일괄 작업이 끝난 뒤 부모의 갱신을 직접 한 번만 실행하고 싶을 때 유용합니다.

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

참고: 실행 중에 유효성 검사기를 동적으로 관리하는 방법은 폼 유효성 검사 문서의 [반응형 폼에서 유효성 검사기 동적으로 관리하기](guide/forms/form-validation#managing-validators-dynamically-in-reactive-forms) 섹션을 참고하세요.

## 폼 컨트롤 타입을 좁히는 유틸리티 함수

<!--
Angular provides four utility functions that help determine the concrete type of an `AbstractControl`. These functions act as **type guards** and narrow the control type when they return `true`, which lets you safely access subtype-specific properties inside the same block.

These helpers are particularly useful in **custom validators**, where the function signature receives an `AbstractControl`, but the logic is intended for a specific control kind.

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

Angular는 `AbstractControl`의 구체적인 타입을 확인하는 유틸리티 함수 네 개를 제공합니다.
이 함수는 **타입 가드**로 동작하며, `true`를 반환하면 컨트롤의 타입이 좁혀집니다.
따라서 같은 블록 안에서 하위 타입에만 있는 프로퍼티에도 안전하게 접근할 수 있습니다.

이 함수는 **커스텀 유효성 검사기**에서 특히 유용합니다.
함수 시그니처는 `AbstractControl`을 받지만, 실제 로직은 특정 종류의 컨트롤을 처리하도록 작성하는 경우가 있기 때문입니다.

```ts
import {AbstractControl, isFormArray} from '@angular/forms';

export function positiveValues(control: AbstractControl) {
  if (!isFormArray(control)) {
    return null; // FormArray가 아니므로 이 유효성 검사기를 적용하지 않습니다.
  }

// 타입을 좁힌 뒤에는 FormArray 전용 API에 안전하게 접근할 수 있습니다.
  const hasNegative = control.controls.some((c) => c.value < 0);
  return hasNegative ? {positiveValues: true} : null;
}
```

## 반응형 폼 API 요약

다음 표는 반응형 폼 컨트롤을 생성하고 관리하는 데 사용하는 기반 클래스와 서비스를 정리한 것입니다.
자세한 문법은 [Forms 패키지](api#angular_forms 'API 레퍼런스')의 API 레퍼런스를 참고하세요.

### 클래스

| 클래스            | 설명                                                                                                                                                     |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AbstractControl` | 구체적인 폼 컨트롤 클래스인 `FormControl`, `FormGroup`, `FormArray`의 추상 기반 클래스입니다. 공통 동작과 프로퍼티를 제공합니다.                         |
| `FormControl`     | 개별 폼 컨트롤의 값과 유효성 상태를 관리합니다. `<input>`, `<select>` 같은 HTML 폼 컨트롤에 대응합니다.                                                  |
| `FormGroup`       | `AbstractControl` 인스턴스 그룹의 값과 유효성 상태를 관리합니다. 그룹의 프로퍼티에는 자식 컨트롤이 포함됩니다. 컴포넌트의 최상위 폼은 `FormGroup`입니다. |
| `FormArray`       | 숫자 인덱스로 접근하는 `AbstractControl` 인스턴스 배열의 값과 유효성 상태를 관리합니다.                                                                  |
| `FormBuilder`     | 컨트롤 인스턴스를 생성하는 팩토리 메서드를 제공하는 주입 가능한 서비스입니다.                                                                            |
| `FormRecord`      | 값의 타입이 같은 `FormControl` 인스턴스 모음의 값과 유효성 상태를 추적합니다.                                                                            |

### 디렉티브

# 타입이 지정된 폼

<!--
As of Angular 14, reactive forms are strictly typed by default.

As background for this guide, you should already be familiar with [Angular Reactive Forms](guide/forms/reactive-forms).
-->

Angular 14부터 반응형 폼에는 기본적으로 엄격한 타입이 적용됩니다.

이 가이드를 읽기 전에 [Angular 반응형 폼](guide/forms/reactive-forms)에 익숙해야 합니다.

## 타입이 지정된 폼 개요

<!--
<docs-video src="https://www.youtube.com/embed/L-odCf4MfJc" title="Typed Forms in Angular" />

With Angular reactive forms, you explicitly specify a _form model_. As a simple example, consider this basic user login form:

```ts
const login = new FormGroup({
  email: new FormControl(''),
  password: new FormControl(''),
});
```

Angular provides many APIs for interacting with this `FormGroup`. For example, you may call `login.value`, `login.controls`, `login.patchValue`, etc. (For a full API reference, see the [API documentation](api/forms/FormGroup).)

In previous Angular versions, most of these APIs included `any` somewhere in their types, and interacting with the structure of the controls, or the values themselves, was not type-safe. For example: you could write the following invalid code:

```ts
const emailDomain = login.value.email.domain;
```

With strictly typed reactive forms, the above code does not compile, because there is no `domain` property on `email`.

In addition to the added safety, the types enable a variety of other improvements, such as better autocomplete in IDEs and an explicit way to specify form structure.

These improvements currently apply only to _reactive_ forms (not [_template-driven_ forms](guide/forms/template-driven-forms)).
-->

<docs-video src="https://www.youtube.com/embed/L-odCf4MfJc" title="Angular에서 타입이 지정된 폼 사용하기" />

Angular 반응형 폼을 사용하면 _폼 모델_ 을 명시적으로 지정합니다.
간단한 예로 다음과 같은 기본 로그인 폼을 살펴봅시다:

```ts
const login = new FormGroup({
  email: new FormControl(''),
  password: new FormControl(''),
});
```

Angular는 이 `FormGroup`을 다룰 수 있는 다양한 API를 제공합니다.
예를 들어 `login.value`, `login.controls`, `login.patchValue` 등을 사용할 수 있습니다.
전체 API 레퍼런스는 [API 문서](api/forms/FormGroup)를 참고하세요.

이전 Angular 버전에서는 이런 API 대부분의 타입에 `any`가 포함되어 있어서, 컨트롤 구조나 값을 다룰 때 타입 안전성을 보장하지 못했습니다.
예를 들어 다음과 같이 잘못된 코드를 작성할 수 있었습니다:

```ts
const emailDomain = login.value.email.domain;
```

엄격한 타입이 적용된 반응형 폼에서는 `email`에 `domain` 프로퍼티가 없기 때문에 위 코드를 컴파일할 수 없습니다.

타입을 사용하면 안전성이 높아질 뿐 아니라 IDE의 자동완성이 개선되고 폼 구조를 명시적으로 지정할 수 있는 등 여러 이점이 있습니다.

이런 개선 사항은 현재 _반응형_ 폼에만 적용되며, [_템플릿 기반_ 폼](guide/forms/template-driven-forms)에는 적용되지 않습니다.

## 타입이 지정되지 않은 폼

<!--
Non-typed forms are still supported, and will continue to work as before. To use them, you must import the `Untyped` symbols from `@angular/forms`:

```ts
const login = new UntypedFormGroup({
  email: new UntypedFormControl(''),
  password: new UntypedFormControl(''),
});
```

Each `Untyped` symbol has exactly the same semantics as in previous Angular versions. By removing the `Untyped` prefixes, you can incrementally enable the types.
-->

타입이 지정되지 않은 폼도 계속 지원하며 이전과 같은 방식으로 동작합니다.
이 방식을 사용하려면 `@angular/forms`에서 `Untyped`로 시작하는 심볼을 로드해야 합니다:

```ts
const login = new UntypedFormGroup({
  email: new UntypedFormControl(''),
  password: new UntypedFormControl(''),
});
```

각 `Untyped` 심볼은 이전 Angular 버전과 정확히 같은 방식으로 동작합니다.
`Untyped` 접두사를 제거하면서 점진적으로 타입을 적용할 수 있습니다.

## `FormControl` 시작하기

<!--
The simplest possible form consists of a single control:

```ts
const email = new FormControl('angularrox@gmail.com');
```

This control will be automatically inferred to have the type `FormControl<string|null>`. TypeScript will automatically enforce this type throughout the [`FormControl` API](api/forms/FormControl), such as `email.value`, `email.valueChanges`, and `email.setValue(...)`.
-->

가장 간단한 폼은 컨트롤 하나로 구성합니다:

```ts
const email = new FormControl('angularrox@gmail.com');
```

이 컨트롤의 타입은 자동으로 `FormControl<string|null>`로 추론됩니다.
TypeScript는 `email.value`, `email.valueChanges`, `email.setValue(...)` 등 [`FormControl` API](api/forms/FormControl) 전체에서 이 타입을 적용합니다.

### null 허용 여부

<!--
You might wonder: why does the type of this control include `null`? This is because the control can become `null` at any time, by calling reset:

```ts
const email = new FormControl('angularrox@gmail.com');
email.reset();
console.log(email.value); // null
```

TypeScript will enforce that you always handle the possibility that the control has become `null`. If you want to make this control non-nullable, you may use the `nonNullable` option. This will cause the control to reset to its initial value, instead of `null`:

```ts
const email = new FormControl('angularrox@gmail.com', {nonNullable: true});
email.reset();
console.log(email.value); // angularrox@gmail.com
```

To reiterate, this option affects the runtime behavior of your form when `.reset()` is called, and should be flipped with care.
-->

컨트롤 타입에 `null`이 포함된 이유가 궁금할 수 있습니다.
`reset`을 실행하면 언제든 컨트롤 값이 `null`이 될 수 있기 때문입니다:

```ts
const email = new FormControl('angularrox@gmail.com');
email.reset();
console.log(email.value); // null
```

TypeScript는 컨트롤 값이 `null`일 가능성을 항상 처리하도록 요구합니다.
컨트롤이 `null` 값을 갖지 않도록 하려면 `nonNullable` 옵션을 사용하면 됩니다.
이 옵션을 지정하면 컨트롤을 초기화할 때 `null` 대신 초기값으로 되돌립니다:

```ts
const email = new FormControl('angularrox@gmail.com', {nonNullable: true});
email.reset();
console.log(email.value); // angularrox@gmail.com
```

다시 말해 이 옵션은 `.reset()`을 실행할 때 폼의 런타임 동작에도 영향을 미치므로, 주의해서 변경해야 합니다.

### 타입을 명시적으로 지정하기

<!--
It is possible to specify the type, instead of relying on inference. Consider a control that is initialized to `null`. Because the initial value is `null`, TypeScript will infer `FormControl<null>`, which is narrower than we want.

```ts
const email = new FormControl(null);
email.setValue('angularrox@gmail.com'); // Error!
```

To prevent this, we explicitly specify the type as `string|null`:

```ts
const email = new FormControl<string | null>(null);
email.setValue('angularrox@gmail.com');
```
-->

타입 추론에 의존하지 않고 타입을 직접 지정할 수도 있습니다.
초기값이 `null`인 컨트롤을 생각해 봅시다.
초기값이 `null`이면 TypeScript는 원하는 범위보다 좁은 `FormControl<null>`로 타입을 추론합니다.

```ts
const email = new FormControl(null);
email.setValue('angularrox@gmail.com'); // 에러가 발생합니다!
```

이 문제를 방지하려면 타입을 `string|null`로 명시합니다:

```ts
const email = new FormControl<string | null>(null);
email.setValue('angularrox@gmail.com');
```

## `FormArray`: 같은 타입의 컨트롤을 동적으로 관리하기

<!--
A `FormArray` contains an open-ended list of controls. The type parameter corresponds to the type of each inner control:

```ts
const names = new FormArray([new FormControl('Alex')]);
names.push(new FormControl('Jess'));
```

Pass an array of controls to `aliases.push()` when you need to add several entries at once.

```ts
const aliases = new FormArray([new FormControl('ng')]);
aliases.push([new FormControl('ngDev'), new FormControl('ngAwesome')]);
```

This `FormArray` will have the inner controls type `FormControl<string|null>`.

If you want to have multiple different element types inside the array, you must use `UntypedFormArray`, because TypeScript cannot infer which element type will occur at which position.

A `FormArray` also provides a `clear()` method to remove all controls it contains:

```ts
const aliases = new FormArray([new FormControl('ngDev'), new FormControl('ngAwesome')]);
aliases.clear();
console.log(aliases.length); // 0
```
-->

`FormArray`에는 개수가 정해지지 않은 컨트롤 목록을 담습니다.
타입 인자는 내부의 각 컨트롤 타입에 해당합니다:

```ts
const names = new FormArray([new FormControl('Alex')]);
names.push(new FormControl('Jess'));
```

여러 항목을 한 번에 추가하려면 `aliases.push()`에 컨트롤 배열을 전달합니다.

```ts
const aliases = new FormArray([new FormControl('ng')]);
aliases.push([new FormControl('ngDev'), new FormControl('ngAwesome')]);
```

이 `FormArray` 내부 컨트롤의 타입은 `FormControl<string|null>`입니다.

배열에 서로 다른 여러 타입의 항목을 담으려면 `UntypedFormArray`를 사용해야 합니다.
TypeScript가 각 위치에 어떤 타입의 항목이 올지 추론할 수 없기 때문입니다.

`FormArray`는 내부의 모든 컨트롤을 제거하는 `clear()` 메서드도 제공합니다:

```ts
const aliases = new FormArray([new FormControl('ngDev'), new FormControl('ngAwesome')]);
aliases.clear();
console.log(aliases.length); // 0
```

## `FormGroup`과 `FormRecord`

Angular는 키 목록이 정해진 폼에 사용할 `FormGroup` 타입과, 키가 정해지지 않았거나 동적으로 구성하는 그룹에 사용할 `FormRecord` 타입을 제공합니다.

### 일부 값만 포함하는 경우

<!--
Consider again a login form:

```ts
const login = new FormGroup({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});
```

On any `FormGroup`, it is [possible to disable controls](api/forms/FormGroup). Any disabled control will not appear in the group's value.

As a consequence, the type of `login.value` is `Partial<{email: string, password: string}>`. The `Partial` in this type means that each member might be undefined.

More specifically, the type of `login.value.email` is `string|undefined`, and TypeScript will enforce that you handle the possibly `undefined` value (if you have `strictNullChecks` enabled).

If you want to access the value _including_ disabled controls, and thus bypass possible `undefined` fields, you can use `login.getRawValue()`.
-->

로그인 폼을 다시 살펴봅시다:

```ts
const login = new FormGroup({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});
```

모든 `FormGroup`에서는 [컨트롤을 비활성화할 수 있습니다](api/forms/FormGroup).
비활성화된 컨트롤은 그룹의 값에 포함되지 않습니다.

따라서 `login.value`의 타입은 `Partial<{email: string, password: string}>`입니다.
이 타입의 `Partial`은 각 프로퍼티의 값이 undefined일 수 있다는 의미입니다.

구체적으로 `login.value.email`의 타입은 `string|undefined`이며, TypeScript는 `strictNullChecks`가 활성화되어 있다면 값이 `undefined`일 가능성을 처리하도록 요구합니다.

비활성화된 컨트롤의 값까지 _포함해서_ 가져오고, 이로 인해 필드가 `undefined`가 되는 것을 피하려면 `login.getRawValue()`를 사용하면 됩니다.

### 선택적 컨트롤과 동적 그룹

<!--
Some forms have controls that may or may not be present, which can be added and removed at runtime. You can represent these controls using _optional fields_:

```ts
interface LoginForm {
  email: FormControl<string>;
  password?: FormControl<string>;
}

const login = new FormGroup<LoginForm>({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});

In this form, we explicitly specify the type, which allows us to make the `password` control optional. TypeScript will enforce that only optional controls can be added or removed.
-->

어떤 폼에는 존재할 수도 있고 존재하지 않을 수도 있는 컨트롤이 있으며, 런타임에 이를 추가하거나 제거할 수 있습니다.
이런 컨트롤은 _선택적 필드_ 로 표현합니다:

```ts
interface LoginForm {
  email: FormControl<string>;
  password?: FormControl<string>;
}

const login = new FormGroup<LoginForm>({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});

이 폼에서는 타입을 명시적으로 지정해서 `password` 컨트롤을 선택적으로 사용하도록 설정합니다.
TypeScript는 선택적 컨트롤만 추가하거나 제거할 수 있도록 제한합니다.

### `FormRecord`

<!--
Some `FormGroup` usages do not fit the above pattern because the keys are not known ahead of time. The `FormRecord` class is designed for that case:

```ts
const addresses = new FormRecord<FormControl<string | null>>({});
addresses.addControl('Andrew', new FormControl('2340 Folsom St'));
```

Any control of type `string|null` can be added to this `FormRecord`.

If you need a `FormGroup` that is both dynamic (open-ended) and heterogeneous (the controls are different types), no improved type safety is possible, and you should use `UntypedFormGroup`.

A `FormRecord` can also be built with the `FormBuilder`:

```ts
const addresses = fb.record({'Andrew': '2340 Folsom St'});
```
-->

키를 미리 알 수 없는 경우에는 앞에서 살펴본 `FormGroup` 사용 방식이 맞지 않을 수 있습니다.
`FormRecord` 클래스는 이런 경우에 사용하도록 설계되었습니다:

```ts
const addresses = new FormRecord<FormControl<string | null>>({});
addresses.addControl('Andrew', new FormControl('2340 Folsom St'));
```

이 `FormRecord`에는 값의 타입이 `string|null`인 컨트롤을 추가할 수 있습니다.

동적이면서 키가 정해지지 않고, 컨트롤마다 타입도 다른 `FormGroup`이 필요하다면 타입 안전성을 더 높일 수 없으므로 `UntypedFormGroup`을 사용해야 합니다.

`FormBuilder`로 `FormRecord`를 생성할 수도 있습니다:

```ts
const addresses = fb.record({'Andrew': '2340 Folsom St'});
```

## `FormBuilder`와 `NonNullableFormBuilder`

<!--
The `FormBuilder` class has been upgraded to support the new types as well, in the same manner as the above examples.

Additionally, an additional builder is available: `NonNullableFormBuilder`. This type is shorthand for specifying `{nonNullable: true}` on every control, and can eliminate significant boilerplate from large non-nullable forms. You can access it using the `nonNullable` property on a `FormBuilder`:

```ts
const fb = new FormBuilder();
const login = fb.nonNullable.group({
  email: '',
  password: '',
});
```

On the above example, both inner controls will be non-nullable (i.e. `nonNullable` will be set).

You can also inject it using the name `NonNullableFormBuilder`.
-->

`FormBuilder` 클래스도 앞의 예제와 같은 방식으로 새로운 타입을 지원하도록 개선되었습니다.

추가로 `NonNullableFormBuilder`도 사용할 수 있습니다.
이 타입은 모든 컨트롤에 `{nonNullable: true}`를 지정하는 것을 간단하게 표현하며, null을 허용하지 않는 대규모 폼에서 반복 코드를 크게 줄일 수 있습니다.
`FormBuilder`의 `nonNullable` 프로퍼티로 접근할 수 있습니다:

```ts
const fb = new FormBuilder();
const login = fb.nonNullable.group({
  email: '',
  password: '',
});
```

위 예제의 내부 컨트롤 두 개는 모두 null을 허용하지 않습니다.
즉, `nonNullable`이 설정됩니다.

`NonNullableFormBuilder`라는 이름으로 직접 주입할 수도 있습니다.

# 템플릿 기반 폼 만들기

<!--
This tutorial shows you how to create a template-driven form. The control elements in the form are bound to data properties that have input validation. The input validation helps maintain data integrity and styling to improve the user experience.

Template-driven forms use [two-way data binding](guide/templates/two-way-binding) to update the data model in the component as changes are made in the template and vice versa.
Angular supports two design approaches for interactive forms. Template-driven forms allow you to use form-specific directives in your Angular template. Reactive forms provide a model-driven approach to building forms.

Template-driven forms are a great choice for small or simple forms, while reactive forms are more scalable and suitable for complex forms. For a comparison of the two approaches, see [Choosing an approach](guide/forms#choosing-an-approach)
You can build almost any kind of form with an Angular template — login forms, contact forms, and pretty much any business form.
You can lay out the controls creatively and bind them to the data in your object model.
You can specify validation rules and display validation errors, conditionally allow input from specific controls, trigger built-in visual feedback, and much more.
-->

이 튜토리얼에서는 템플릿 기반 폼을 만드는 방법을 알아봅니다.
폼에 있는 컨트롤 엘리먼트는 입력값의 유효성을 검사하는 데이터 프로퍼티와 바인딩됩니다.
입력값의 유효성을 검사하면 데이터 무결성을 유지할 수 있으며, 검사 결과에 따라 스타일을 적용해서 사용자 경험을 개선할 수 있습니다.

템플릿 기반 폼은 [양방향 데이터 바인딩](guide/templates/two-way-binding)을 사용합니다.
템플릿에서 값이 변경되면 컴포넌트의 데이터 모델에 반영되고, 데이터 모델에서 값이 변경되면 템플릿에 반영됩니다.
Angular는 사용자 입력을 처리하는 폼을 두 가지 방식으로 지원합니다.
템플릿 기반 폼은 Angular 템플릿에 폼 전용 디렉티브를 사용합니다.
반응형 폼은 모델을 중심으로 폼을 구성합니다.

템플릿 기반 폼은 작거나 간단한 폼을 만들 때 좋습니다.
반응형 폼은 확장하기 쉬워서 복잡한 폼에 적합합니다.
두 방식을 비교하려면 [폼 종류 선택하기](guide/forms#choosing-an-approach) 문서를 참고하세요.
Angular 템플릿으로 로그인 폼, 연락처 입력 폼, 업무용 폼 등 거의 모든 종류의 폼을 만들 수 있습니다.
컨트롤을 원하는 대로 배치하고 객체 모델의 데이터와 바인딩하면 됩니다.
유효성 검사 규칙을 지정하고 오류를 표시할 수 있으며, 특정 컨트롤의 입력을 조건에 따라 허용하거나 기본으로 제공되는 시각적 피드백을 표시하는 등 다양한 기능을 사용할 수 있습니다.

## 목표

<!--
This tutorial teaches you how to do the following:

- Build an Angular form with a component and template
- Use `ngModel` to create two-way data bindings for reading and writing input-control values
- Provide visual feedback using special CSS classes that track the state of the controls
- Display validation errors to users and conditionally allow input from form controls based on the form status
- Share information across HTML elements using [template reference variables](guide/templates/variables#template-reference-variables)
-->

이 튜토리얼에서는 다음 내용을 알아봅니다.

- 컴포넌트와 템플릿으로 Angular 폼 만들기
- `ngModel`을 사용해서 입력 컨트롤의 값을 읽고 쓰는 양방향 데이터 바인딩 구성하기
- 컨트롤 상태를 추적하는 CSS 클래스로 시각적 피드백 제공하기
- 사용자에게 유효성 검사 오류를 표시하고, 폼 상태에 따라 컨트롤 입력을 허용하기
- [템플릿 참조 변수](guide/templates/variables#template-reference-variables)로 HTML 엘리먼트 사이에서 정보 공유하기

## 템플릿 기반 폼 구성하기

<!--
Template-driven forms rely on directives defined in the `FormsModule`.

| Directives     | Details                                                                                                                                                                                                                                                                         |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NgModel`      | Reconciles value changes in the attached form element with changes in the data model, allowing you to respond to user input with input validation and error handling.                                                                                                           |
| `NgForm`       | Creates a top-level `FormGroup` instance and binds it to a `<form>` element to track aggregated form value and validation status. As soon as you import `FormsModule`, this directive becomes active by default on all `<form>` tags. You don't need to add a special selector. |
| `NgModelGroup` | Creates and binds a `FormGroup` instance to a DOM element.                                                                                                                                                                                                                      |
-->

템플릿 기반 폼은 `FormsModule`에 정의된 디렉티브를 사용합니다.

| 디렉티브       | 설명                                                                                                                                                                                                                                    |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NgModel`      | 폼 엘리먼트에서 변경된 값과 데이터 모델에서 변경된 값을 동기화합니다. 이를 활용해서 사용자 입력의 유효성을 검사하고 오류를 처리할 수 있습니다.                                                                                          |
| `NgForm`       | 최상위 `FormGroup` 인스턴스를 생성하고 `<form>` 엘리먼트에 바인딩해서 폼 전체의 값과 유효성 상태를 추적합니다. `FormsModule`을 로드하면 모든 `<form>` 태그에 이 디렉티브가 기본으로 적용되므로, 별도의 셀렉터를 추가할 필요가 없습니다. |
| `NgModelGroup` | `FormGroup` 인스턴스를 생성하고 DOM 엘리먼트에 바인딩합니다.                                                                                                                                                                            |

### 진행 순서

<!--
In the course of this tutorial, you bind a sample form to data and handle user input using the following steps.

1. Build the basic form.
   - Define a sample data model
   - Include required infrastructure such as the `FormsModule`
1. Bind form controls to data properties using the `ngModel` directive and two-way data-binding syntax.
   - Examine how `ngModel` reports control states using CSS classes
   - Name controls to make them accessible to `ngModel`
1. Track input validity and control status using `ngModel`.
   - Add custom CSS to provide visual feedback on the status
   - Show and hide validation-error messages
1. Respond to a native HTML button-click event by adding to the model data.
1. Handle form submission using the [`ngSubmit`](api/forms/NgForm#ngSubmit) output property of the form.
   - Disable the **Submit** button until the form is valid
   - After submit, swap out the finished form for different content on the page
-->

이 튜토리얼에서는 다음 순서로 예제 폼을 데이터와 바인딩하고 사용자 입력을 처리합니다.

1. 기본 폼을 만듭니다.
   - 예제 데이터 모델을 정의합니다.
   - `FormsModule` 등 필요한 구성 요소를 추가합니다.
1. `ngModel` 디렉티브와 양방향 데이터 바인딩 문법으로 폼 컨트롤을 데이터 프로퍼티에 바인딩합니다.
   - `ngModel`이 CSS 클래스로 컨트롤 상태를 표시하는 방식을 확인합니다.
   - `ngModel`이 컨트롤에 접근할 수 있도록 이름을 지정합니다.
1. `ngModel`로 입력값의 유효성과 컨트롤 상태를 추적합니다.
   - 커스텀 CSS를 추가해서 상태에 따른 시각적 피드백을 제공합니다.
   - 유효성 검사 오류 메시지를 표시하거나 숨깁니다.
1. 표준 HTML 버튼의 클릭 이벤트에 반응해서 모델 데이터를 추가합니다.
1. 폼의 [`ngSubmit`](api/forms/NgForm#ngSubmit) 출력 프로퍼티로 폼 제출을 처리합니다.
   - 폼이 유효해질 때까지 **Submit** 버튼을 비활성화합니다.
   - 폼을 제출하면 입력이 끝난 폼 대신 다른 내용을 페이지에 표시합니다.

## 폼 만들기

<!--
<!- TODO: link to preview ->
<!- <docs-code live/> ->

1. The provided sample application creates the `Actor` class which defines the data model reflected in the form.

<docs-code header="actor.ts" language="typescript" path="adev/src/content/examples/forms/src/app/actor.ts"/>

1. The form layout and details are defined in the `ActorFormComponent` class.

<docs-code header="actor-form.component.ts (v1)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="v1"/>

The component's `selector` value of "app-actor-form" means you can drop this form in a parent template using the `<app-actor-form>` tag.

1. The following code creates a new actor instance, so that the initial form can show an example actor.

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" region="Marilyn"/>

This demo uses dummy data for `model` and `skills`.
   In a real app, you would inject a data service to get and save real data, or expose these properties as inputs and outputs.

1. The component enables the Forms feature by importing the `FormsModule` module.

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" region="imports"/>

1. The form is displayed in the application layout defined by the root component's template.

<docs-code header="app.component.html" language="html" path="adev/src/content/examples/forms/src/app/app.component.html"/>

The initial template defines the layout for a form with two form groups and a submit button.
   The form groups correspond to two properties of the Actor data model, name and studio.
   Each group has a label and a box for user input.
   - The **Name** `<input>` control element has the HTML5 `required` attribute
   - The **Studio** `<input>` control element does not because `studio` is optional

The **Submit** button has some classes on it for styling.
   At this point, the form layout is all plain HTML5, with no bindings or directives.

1. The sample form uses some style classes from [Twitter Bootstrap](https://getbootstrap.com/css): `container`, `form-group`, `form-control`, and `btn`.
   To use these styles, the application's style sheet imports the library.

<docs-code header="styles.css" path="adev/src/content/examples/forms/src/styles.1.css"/>

1. The form requires that an actor's skill is chosen from a predefined list of `skills` maintained internally in `ActorFormComponent`.
   The Angular `@for` loop iterates over the data values to populate the `<select>` element.

<docs-code header="actor-form.component.html (skills)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="skills"/>

If you run the application right now, you see the list of skills in the selection control.
The input elements are not yet bound to data values or events, so they are still blank and have no behavior.
-->

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`에 가상 데이터를 사용합니다.
   실제 애플리케이션에서는 데이터 서비스를 주입해서 실제 데이터를 가져오고 저장하거나, 이 프로퍼티를 입력과 출력으로 공개하면 됩니다.

1. 컴포넌트에서 `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 프로퍼티에 각각 대응합니다.
   각 그룹에는 레이블과 사용자 입력 필드가 있습니다.
   - **Name** `<input>` 컨트롤 엘리먼트에는 HTML5 `required` 어트리뷰트가 있습니다.
   - **Studio** `<input>` 컨트롤 엘리먼트에는 없습니다.
     `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. 폼에서는 `ActorFormComponent` 내부의 `skills` 목록에 미리 정의된 항목 중에서 배우의 특기를 선택해야 합니다.
   Angular `@for` 반복문으로 데이터 값을 순회해서 `<select>` 엘리먼트를 구성합니다.

<docs-code header="actor-form.component.html (특기)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="skills"/>

지금 애플리케이션을 실행하면 선택 컨트롤에 특기 목록이 표시됩니다.
입력 엘리먼트는 아직 데이터 값이나 이벤트와 바인딩되지 않았기 때문에 비어 있으며, 아무 동작도 하지 않습니다.

## 입력 컨트롤을 데이터 프로퍼티에 바인딩하기

<!--
The next step is to bind the input controls to the corresponding `Actor` properties with two-way data binding, so that they respond to user input by updating the data model, and also respond to programmatic changes in the data by updating the display.

The `ngModel` directive declared in the `FormsModule` lets you bind controls in your template-driven form to properties in your data model.
When you include the directive using the syntax for two-way data binding, `[(ngModel)]`, Angular can track the value and user interaction of the control and keep the view synced with the model.

1. Edit the template file `actor-form.component.html`.
1. Find the `<input>` tag next to the **Name** label.
1. Add the `ngModel` directive, using two-way data binding syntax `[(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: This example has a temporary diagnostic interpolation after each input tag, `{{model.name}}`, to show the current data value of the corresponding property. The comment reminds you to remove the diagnostic lines when you have finished observing the two-way data binding at work.
-->

다음으로 입력 컨트롤을 해당하는 `Actor` 프로퍼티와 양방향 데이터 바인딩합니다.
그러면 사용자 입력이 데이터 모델에 반영되고, 프로그램에서 데이터를 변경하면 화면에도 반영됩니다.

`FormsModule`에 선언된 `ngModel` 디렉티브로 템플릿 기반 폼의 컨트롤을 데이터 모델의 프로퍼티에 바인딩할 수 있습니다.
양방향 데이터 바인딩 문법인 `[(ngModel)]`로 디렉티브를 적용하면, Angular가 컨트롤의 값과 사용자 상호작용을 추적하고 뷰와 모델을 동기화합니다.

1. 템플릿 파일 `actor-form.component.html`을 엽니다.
1. **Name** 레이블 옆의 `<input>` 태그를 찾습니다.
1. 양방향 데이터 바인딩 문법 `[(ngModel)]="..."`으로 `ngModel` 디렉티브를 추가합니다.

<docs-code header="actor-form.component.html (일부)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngModelName-1"/>

참고: 이 예제에서는 각 입력 태그 뒤에 확인용 문자열 바인딩 `{{model.name}}`을 임시로 추가해서 해당 프로퍼티의 현재 값을 표시합니다.
주석에 적힌 대로 양방향 데이터 바인딩의 동작을 확인한 후에는 이 확인용 코드를 삭제하세요.

### 폼 전체 상태에 접근하기

<!--
When you imported the `FormsModule` in your component, Angular automatically created and attached an [NgForm](api/forms/NgForm) directive to the `<form>` tag in the template (because `NgForm` has the selector `form` that matches `<form>` elements).

To get access to the `NgForm` and the overall form status, declare a [template reference variable](guide/templates/variables#template-reference-variables).

1. Edit the template file `actor-form.component.html`.
1. Update the `<form>` tag with a template reference variable, `#actorForm`, and set its value as follows.

<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"/>

The `actorForm` template variable is now a reference to the `NgForm` directive instance that governs the form as a whole.

1. Run the app.
1. Start typing in the **Name** input box.

As you add and delete characters, you can see them appear and disappear from the data model.

The diagnostic line that shows interpolated values demonstrates that values are really flowing from the input box to the model and back again.
-->

컴포넌트에서 `FormsModule`을 로드하면 Angular가 템플릿의 `<form>` 태그에 [NgForm](api/forms/NgForm) 디렉티브를 자동으로 생성해서 적용합니다.
`NgForm`의 셀렉터가 `<form>` 엘리먼트와 일치하는 `form`이기 때문입니다.

`NgForm`과 폼 전체 상태에 접근하려면 [템플릿 참조 변수](guide/templates/variables#template-reference-variables)를 선언하세요.

1. 템플릿 파일 `actor-form.component.html`을 엽니다.
1. `<form>` 태그에 템플릿 참조 변수 `#actorForm`을 추가하고, 아래와 같이 값을 지정합니다.

<docs-code header="actor-form.component.html (일부)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="template-variable"/>

이제 `actorForm` 템플릿 변수는 폼 전체를 관리하는 `NgForm` 디렉티브 인스턴스를 참조합니다.

1. 애플리케이션을 실행합니다.
1. **Name** 입력 필드에 값을 입력합니다.

글자를 입력하거나 삭제하면 데이터 모델에도 글자가 추가되거나 삭제되는 것을 확인할 수 있습니다.

문자열 바인딩으로 값을 표시하는 확인용 코드를 통해 입력 필드의 값이 모델로 전달되고, 다시 화면에 표시되는 것을 확인할 수 있습니다.

### 컨트롤 엘리먼트에 이름 지정하기

<!--
When you use `[(ngModel)]` on an element, you must define a `name` attribute for that element.
Angular uses the assigned name to register the element with the `NgForm` directive attached to the parent `<form>` element.

The example added a `name` attribute to the `<input>` element and set it to "name", which makes sense for the actor's name.
Any unique value will do, but using a descriptive name is helpful.

1. Add similar `[(ngModel)]` bindings and `name` attributes to **Studio** and **Skill**.
1. You can now remove the diagnostic messages that show interpolated values.
1. To confirm that two-way data binding works for the entire actor model, add a new text binding with the [`json`](api/common/JsonPipe) pipe at the top to the component's template, which serializes the data to a string.

After these revisions, the form template should look like the following:

<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"/>

You'll notice that:

- Each `<input>` element has an `id` property.
  This is used by the `<label>` element's `for` attribute to match the label to its input control.
  This is a [standard HTML feature](https://developer.mozilla.org/docs/Web/HTML/Element/label).

- Each `<input>` element also has the required `name` property that Angular uses to register the control with the form.

When you have observed the effects, you can delete the `{{ model | json }}` text binding.
-->

엘리먼트에 `[(ngModel)]`을 사용하려면 해당 엘리먼트에 `name` 어트리뷰트를 정의해야 합니다.
Angular는 이 이름으로 부모 `<form>` 엘리먼트에 적용된 `NgForm` 디렉티브에 엘리먼트를 등록합니다.

예제에서는 `<input>` 엘리먼트에 `name` 어트리뷰트를 추가하고 배우의 이름을 의미하는 "name"으로 지정했습니다.
고유한 값이면 무엇이든 사용할 수 있지만, 의미를 알기 쉬운 이름이 좋습니다.

1. **Studio**와 **Skill**에도 같은 방식으로 `[(ngModel)]` 바인딩과 `name` 어트리뷰트를 추가합니다.
1. 문자열 바인딩으로 값을 표시하던 확인용 메시지는 이제 삭제해도 됩니다.
1. 배우 모델 전체에 양방향 데이터 바인딩이 동작하는지 확인하기 위해 컴포넌트 템플릿 맨 위에 [`json`](api/common/JsonPipe) 파이프를 사용하는 문자열 바인딩을 추가합니다.
   이 파이프는 데이터를 문자열로 직렬화합니다.

수정한 폼 템플릿은 다음과 같습니다.

<docs-code header="actor-form.component.html (일부)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngModel-2"/>

다음 내용을 확인해 보세요.

- 각 `<input>` 엘리먼트에는 `id` 프로퍼티가 있습니다.
  `<label>` 엘리먼트의 `for` 어트리뷰트는 이 값을 사용해서 레이블과 입력 컨트롤을 연결합니다.
  이는 [표준 HTML 기능](https://developer.mozilla.org/docs/Web/HTML/Element/label)입니다.

- 각 `<input>` 엘리먼트에는 필수인 `name` 프로퍼티도 있습니다.
  Angular는 이 값을 사용해서 컨트롤을 폼에 등록합니다.

동작을 확인한 후에는 `{{ model | json }}` 문자열 바인딩을 삭제해도 됩니다.

## 폼 상태 추적하기

Angular는 폼이 제출되면 `form` 엘리먼트에 `ng-submitted` 클래스를 적용합니다.
이 클래스를 사용해서 제출한 폼의 스타일을 변경할 수 있습니다.

## 컨트롤 상태 추적하기

<!--
Adding the `NgModel` directive to a control adds class names to the control that describe its state.
These classes can be used to change a control's style based on its state.

The following table describes the class names that Angular applies based on the control's state.

Angular also applies the `ng-submitted` class to `form` elements upon submission, but not to the controls inside the `form` element.

You use these CSS classes to define the styles for your control based on its status.
-->

컨트롤에 `NgModel` 디렉티브를 추가하면 컨트롤 상태를 나타내는 클래스 이름이 추가됩니다.
이 클래스로 상태에 따라 컨트롤의 스타일을 변경할 수 있습니다.

Angular가 컨트롤 상태에 따라 적용하는 클래스 이름은 다음과 같습니다.

Angular는 폼이 제출되면 `form` 엘리먼트에 `ng-submitted` 클래스도 적용합니다.
다만 `form` 엘리먼트 안에 있는 컨트롤에는 이 클래스를 적용하지 않습니다.

이 CSS 클래스로 컨트롤 상태에 맞는 스타일을 정의하면 됩니다.

### 컨트롤 상태 확인하기

<!--
To see how the classes are added and removed by the framework, open the browser's developer tools and inspect the `<input>` element that represents the actor name.

1. Using your browser's developer tools, find the `<input>` element that corresponds to the **Name** input box.
   You can see that the element has multiple CSS classes in addition to "form-control".

1. When you first bring it up, the classes indicate that it has a valid value, that the value has not been changed since initialization or reset, and that the control has not been visited since initialization or reset.

```html
<input class="form-control ng-untouched ng-pristine ng-valid" />
   ```

1. Take the following actions on the **Name** `<input>` box, and observe which classes appear.
   - Look but don't touch.
     The classes indicate that it is untouched, pristine, and valid.

- Click inside the name box, then click outside it.
     The control has now been visited, and the element has the `ng-touched` class instead of the `ng-untouched` class.

- Add slashes to the end of the name.
     It is now touched and dirty.

- Erase the name.
     This makes the value invalid, so the `ng-invalid` class replaces the `ng-valid` class.
-->

Angular가 클래스를 추가하고 삭제하는 모습을 확인하려면 브라우저 개발자 도구를 열고 배우 이름을 입력하는 `<input>` 엘리먼트를 검사하세요.

1. 브라우저 개발자 도구에서 **Name** 입력 필드에 해당하는 `<input>` 엘리먼트를 찾습니다.
   엘리먼트에 "form-control" 외에도 여러 CSS 클래스가 있는 것을 확인할 수 있습니다.

1. 처음 표시될 때는 값이 유효하고, 초기화하거나 리셋한 후 값이 변경되지 않았으며, 컨트롤에도 접근한 적이 없다는 것을 클래스가 나타냅니다.

```html
<input class="form-control ng-untouched ng-pristine ng-valid" />
   ```

1. **Name** `<input>` 필드에서 다음 동작을 하면서 어떤 클래스가 적용되는지 확인해 보세요.
   - 아무 동작도 하지 않고 상태만 확인합니다.
     클래스는 컨트롤에 접근한 적이 없고(untouched), 값이 변경되지 않았으며(pristine), 유효한 상태(valid)를 나타냅니다.

- 이름 입력 필드 안쪽을 클릭한 다음 바깥쪽을 클릭합니다.
     이제 컨트롤에 접근했으므로 엘리먼트의 `ng-untouched` 클래스가 `ng-touched` 클래스로 바뀝니다.

- 이름 끝에 슬래시를 추가합니다.
     이제 컨트롤은 접근한 상태(touched)이면서 값이 변경된 상태(dirty)입니다.

- 이름을 모두 지웁니다.
     값이 유효하지 않게 되므로 `ng-valid` 클래스가 `ng-invalid` 클래스로 바뀝니다.

### 상태에 따른 시각적 피드백 제공하기

<!--
The `ng-valid`/`ng-invalid` pair is particularly interesting, because you want to send a
strong visual signal when the values are invalid.
You also want to mark required fields.

You can mark required fields and invalid data at the same time with a colored bar
on the left of the input box.

To change the appearance in this way, take the following steps.

1. Add definitions for the `ng-*` CSS classes.
1. Add these class definitions to a new `forms.css` file.
1. Add the new file to the project as a sibling to `index.html`:

<docs-code header="forms.css" language="css" path="adev/src/content/examples/forms/src/assets/forms.css"/>

1. In the `index.html` file, update the `<head>` tag to include the new style sheet.

<docs-code header="index.html (styles)" path="adev/src/content/examples/forms/src/index.html" region="styles"/>
-->

`ng-valid`와 `ng-invalid` 클래스는 특히 유용합니다.
값이 유효하지 않을 때 이를 시각적으로 명확히 알릴 수 있기 때문입니다.
필수 입력 필드도 표시하는 것이 좋습니다.

입력 필드 왼쪽에 색상 막대를 표시하면 필수 입력 필드와 유효하지 않은 데이터를 함께 나타낼 수 있습니다.

다음 순서로 스타일을 변경해 봅시다.

1. `ng-*` CSS 클래스의 스타일을 정의합니다.
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 (스타일)" path="adev/src/content/examples/forms/src/index.html" region="styles"/>

### 유효성 검사 오류 메시지 표시하고 숨기기

<!--
The **Name** input box is required and clearing it turns the bar red.
That indicates that something is wrong, but the user doesn't know what is wrong or what to do about it.
You can provide a helpful message by checking for and responding to the control's state.

The **Skill** select box is also required, but it doesn't need this kind of error handling because the selection box already constrains the selection to valid values.

To define and show an error message when appropriate, take the following steps.

<docs-workflow>
<docs-step title="Add a local reference to the input">
Extend the `input` tag with a template reference variable that you can use to access the input box's Angular control from within the template. In the example, the variable is `#name="ngModel"`.

The template reference variable (`#name`) is set to `"ngModel"` because that is the value of the [`NgModel.exportAs`](api/core/Directive#exportAs) property. This property tells Angular how to link a reference variable to a directive.
</docs-step>

<docs-step title="Add the error message">
Add a `<div>` that contains a suitable error message.
</docs-step>

<docs-step title="Make the error message conditional">
Show or hide the error message by binding properties of the `name` control to the message `<div>` element's `hidden` property.
</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">
Add a conditional error message to the `name` input box, as in the following example.

<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>
In this example, you hide the message when the control is either valid or _pristine_.
Pristine means the user hasn't changed the value since it was displayed in this form.
If you ignore the `pristine` state, you would hide the message only when the value is valid.
If you arrive in this component with a new, blank actor or an invalid actor, you'll see the error message immediately, before you've done anything.

You might want the message to display only when the user makes an invalid change.
Hiding the message while the control is in the `pristine` state achieves that goal.
You'll see the significance of this choice when you add a new actor to the form in the next step.
-->

**Name** 입력 필드는 필수이므로 값을 지우면 막대가 빨간색으로 바뀝니다.
문제가 있다는 것은 알 수 있지만, 사용자는 무엇이 잘못되었고 어떻게 해결해야 하는지 알 수 없습니다.
컨트롤 상태를 확인하고 상태에 맞는 안내 메시지를 제공해 봅시다.

**Skill** 선택 필드도 필수이지만, 선택할 수 있는 항목이 유효한 값으로 제한되어 있기 때문에 이런 오류 처리가 필요하지 않습니다.

적절한 시점에 오류 메시지가 표시되도록 다음 순서로 구성합니다.

<docs-workflow>
<a id="add-a-local-reference-to-the-input"></a>

<docs-step title="입력 필드에 지역 참조 추가하기">
`input` 태그에 템플릿 참조 변수를 추가하면 템플릿 안에서 입력 필드의 Angular 컨트롤에 접근할 수 있습니다.
예제에서는 `#name="ngModel"` 변수를 사용합니다.

템플릿 참조 변수(`#name`)를 `"ngModel"`로 지정한 이유는 이 값이 [`NgModel.exportAs`](api/core/Directive#exportAs) 프로퍼티 값이기 때문입니다.
이 프로퍼티는 참조 변수를 디렉티브에 연결하는 방법을 Angular에 알려줍니다.
</docs-step>

<docs-step title="오류 메시지 추가하기">
적절한 오류 메시지가 담긴 `<div>`를 추가합니다.
</docs-step>

<docs-step title="조건에 따라 오류 메시지 표시하기">
`name` 컨트롤의 프로퍼티를 메시지가 담긴 `<div>` 엘리먼트의 `hidden` 프로퍼티에 바인딩해서 오류 메시지를 표시하거나 숨깁니다.
</docs-step>

<docs-code header="actor-form.component.html (오류 메시지 숨기기)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="hidden-error-msg"/>

<docs-step title="name에 조건부 오류 메시지 추가하기">
아래 예제와 같이 `name` 입력 필드에 조건부 오류 메시지를 추가합니다.

<docs-code header="actor-form.component.html (일부)" 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` 상태일 때 메시지를 숨기면 이렇게 동작합니다.
다음 단계에서 폼에 새 배우를 추가해 보면 이 방식의 의미를 확인할 수 있습니다.

## 새 배우 추가하기

<!--
This exercise shows how you can respond to a native HTML button-click event by adding to the model data.
To let form users add a new actor, you will add a **New Actor** button that responds to a click event.

1. In the template, place a "New Actor" `<button>` element at the bottom of the form.
1. In the component file, add the actor-creation method to the actor data model.

<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. Bind the button's click event to an actor-creation method, `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. Run the application again and click the **New Actor** button.

The form clears, and the _required_ bars to the left of the input box are red, indicating invalid `name` and `skill` properties.
   Notice that the error messages are hidden.
   This is because the form is pristine; you haven't changed anything yet.

1. Enter a name and click **New Actor** again.

Now the application displays a `Name is required` error message, because the input box is no longer pristine.
   The form remembers that you entered a name before clicking **New Actor**.

1. To restore the pristine state of the form controls, clear all of the flags imperatively by calling the form's `reset()` method after calling the `newActor()` method.

<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"/>

Now clicking **New Actor** resets both the form and its control flags.
-->

이번에는 표준 HTML 버튼의 클릭 이벤트에 반응해서 모델 데이터를 추가하는 방법을 알아봅니다.
폼에서 새 배우를 추가할 수 있도록 클릭 이벤트에 반응하는 **New Actor** 버튼을 추가하겠습니다.

1. 템플릿의 폼 맨 아래에 "New Actor" `<button>` 엘리먼트를 추가합니다.
1. 컴포넌트 파일에서 배우 데이터 모델에 새 배우를 생성하는 메서드를 추가합니다.

<docs-code header="actor-form.component.ts (새 배우 생성 메서드)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="new-actor"/>

1. 버튼의 클릭 이벤트를 새 배우를 생성하는 `newActor()` 메서드에 바인딩합니다.

<docs-code header="actor-form.component.html (새 배우 버튼)" 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** 버튼을 다시 클릭합니다.

이제 입력 필드가 pristine 상태가 아니므로 `Name is required` 오류 메시지가 표시됩니다.
   폼은 **New Actor** 버튼을 클릭하기 전에 이름을 입력했다는 것을 기억합니다.

1. 폼 컨트롤을 pristine 상태로 되돌리려면 `newActor()` 메서드를 실행한 뒤 폼의 `reset()` 메서드를 실행해서 모든 상태 플래그를 명시적으로 초기화합니다.

<docs-code header="actor-form.component.html (폼 초기화)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="new-actor-button-form-reset"/>

이제 **New Actor** 버튼을 클릭하면 폼과 컨트롤의 상태 플래그가 모두 초기화됩니다.

## `ngSubmit`으로 폼 제출하기

<!--
The user should be able to submit this form after filling it in.
The **Submit** button at the bottom of the form does nothing on its own, but it does trigger a form-submit event because of its type (`type="submit"`).

To respond to this event, take the following steps.

<docs-workflow>

<docs-step title="Listen to ngOnSubmit">
Bind the form's [`ngSubmit`](api/forms/NgForm#ngSubmit) event property to the actor-form component's `onSubmit()` method.

<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">
Use the template reference variable, `#actorForm` to access the form that contains the **Submit** button and create an event binding.

You will bind the form property that indicates its overall validity to the **Submit** button's `disabled` property.

<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">
Notice that the button is enabled — although it doesn't do anything useful yet.
</docs-step>

<docs-step title="Delete the Name value">
This violates the "required" rule, so it displays the error message —and notice that it also disables the **Submit** button.

You didn't have to explicitly wire the button's enabled state to the form's validity.
The `FormsModule` did this automatically when you defined a template reference variable on the enhanced form element, then referred to that variable in the button control.
</docs-step>
</docs-workflow>
-->

사용자는 폼을 모두 입력한 후에 제출할 수 있어야 합니다.
폼 맨 아래의 **Submit** 버튼은 그 자체로는 아무 동작도 하지 않지만, 타입이 `type="submit"`이기 때문에 폼 제출 이벤트를 발생시킵니다.

이 이벤트를 처리하려면 다음 순서로 진행합니다.

<docs-workflow>

<docs-step title="ngOnSubmit 감지하기">
폼의 [`ngSubmit`](api/forms/NgForm#ngSubmit) 이벤트 프로퍼티를 배우 폼 컴포넌트의 `onSubmit()` 메서드에 바인딩합니다.

<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="disabled 프로퍼티 바인딩하기">
템플릿 참조 변수 `#actorForm`으로 **Submit** 버튼이 포함된 폼에 접근하고 이벤트 바인딩을 구성합니다.

폼 전체의 유효성을 나타내는 프로퍼티를 **Submit** 버튼의 `disabled` 프로퍼티에 바인딩하겠습니다.

<docs-code header="actor-form.component.html (제출 버튼)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="submit-button"/>
</docs-step>

<docs-step title="애플리케이션 실행하기">
아직 별다른 기능은 없지만 버튼이 활성화된 것을 확인할 수 있습니다.
</docs-step>

<docs-step title="Name 값 지우기">
"required" 규칙을 위반했기 때문에 오류 메시지가 표시됩니다.
**Submit** 버튼도 비활성화된 것을 확인해 보세요.

버튼의 활성화 상태와 폼의 유효성을 연결하는 별도 코드를 작성할 필요는 없습니다.
폼 기능이 적용된 엘리먼트에 템플릿 참조 변수를 정의하고 버튼 컨트롤에서 이 변수를 참조하면, `FormsModule`이 자동으로 처리합니다.
</docs-step>
</docs-workflow>

### 폼 제출 처리하기

<!--
To show a response to form submission, you can hide the data entry area and display something else in its place.

<docs-workflow>
<docs-step title="Wrap the form">
Wrap the entire form in a `<div>` and bind its `hidden` property to the `ActorFormComponent.submitted` property.

<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"/>

The main form is visible from the start because the `submitted` property is false until you submit the form, as this fragment from the `ActorFormComponent` shows:

<docs-code header="actor-form.component.ts (submitted)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="submitted"/>

When you click the **Submit** button, the `submitted` flag becomes true and the form disappears.
</docs-step>

<docs-step title="Add the submitted state">
To show something else while the form is in the submitted state, add the following HTML below the new `<div>` wrapper.

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="submitted"/>

This `<div>`, which shows a read-only actor with interpolation bindings, appears only while the component is in the submitted state.

The alternative display includes an _Edit_ button whose click event is bound to an expression that clears the `submitted` flag.
</docs-step>

<docs-step title="Test the Edit button">
Click the *Edit* button to switch the display back to the editable form.
</docs-step>
</docs-workflow>
-->

폼을 제출했다는 것을 보여주려면 데이터 입력 영역을 숨기고 그 자리에 다른 내용을 표시하면 됩니다.

<docs-workflow>
<a id="wrap-the-form"></a>

<docs-step title="폼 감싸기">
폼 전체를 `<div>`로 감싸고 `hidden` 프로퍼티를 `ActorFormComponent.submitted` 프로퍼티에 바인딩합니다.

<docs-code header="actor-form.component.html (일부)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="edit-div"/>

아래 `ActorFormComponent` 코드에서 확인할 수 있듯이 폼을 제출하기 전까지는 `submitted` 프로퍼티가 false이므로, 처음에는 폼이 표시됩니다.

<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="제출 상태 추가하기">
폼을 제출한 상태에서 다른 내용을 표시하려면 폼을 감싼 새 `<div>` 아래에 다음 HTML을 추가합니다.

<docs-code header="actor-form.component.html (일부)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="submitted"/>

이 `<div>`는 문자열 바인딩으로 배우 데이터를 읽기 전용으로 표시하며, 컴포넌트가 제출 상태일 때만 나타납니다.

새로 표시되는 영역에는 _Edit_ 버튼도 있습니다.
이 버튼의 클릭 이벤트는 `submitted` 플래그를 해제하는 표현식에 바인딩됩니다.
</docs-step>

<docs-step title="Edit 버튼 테스트하기">
*Edit* 버튼을 클릭하면 화면이 다시 수정할 수 있는 폼으로 바뀝니다.
</docs-step>
</docs-workflow>

## 정리

<!--
The Angular form discussed in this page takes advantage of the following
framework features to provide support for data modification, validation, and more.

- An Angular HTML form template
- A form component class with a `@Component` decorator
- Handling form submission by binding to the `NgForm.ngSubmit` event property
- Template-reference variables such as `#actorForm` and `#name`
- `[(ngModel)]` syntax for two-way data binding
- The use of `name` attributes for validation and form-element change tracking
- The reference variable's `valid` property on input controls indicates whether a control is valid or should show error messages
- Controlling the **Submit** button's enabled state by binding to `NgForm` validity
- Custom CSS classes that provide visual feedback to users about controls that are not valid

Here's the code for the final version of the application:
-->

이 문서에서 살펴본 Angular 폼은 다음 프레임워크 기능을 활용해서 데이터를 수정하고 유효성을 검사합니다.

- Angular HTML 폼 템플릿
- `@Component` 데코레이터가 적용된 폼 컴포넌트 클래스
- `NgForm.ngSubmit` 이벤트 프로퍼티에 바인딩해서 폼 제출 처리하기
- `#actorForm`, `#name`과 같은 템플릿 참조 변수
- 양방향 데이터 바인딩을 위한 `[(ngModel)]` 문법
- 유효성 검사와 폼 엘리먼트의 변경사항 추적에 사용하는 `name` 어트리뷰트
- 컨트롤이 유효한지, 오류 메시지를 표시해야 하는지 확인하는 입력 컨트롤 참조 변수의 `valid` 프로퍼티
- `NgForm`의 유효성 상태에 바인딩해서 **Submit** 버튼의 활성화 상태 제어하기
- 유효하지 않은 컨트롤을 사용자에게 시각적으로 알리는 커스텀 CSS 클래스

완성된 애플리케이션 코드는 다음과 같습니다.

# 폼 입력 유효성 검사하기

사용자 입력이 정확하고 완전한지 검사하면 전반적인 데이터 품질을 높일 수 있습니다.
이 문서에서는 반응형 폼과 템플릿 기반 폼에서 UI를 통해 받은 사용자 입력을 검증하고, 유용한 검사 메시지를 표시하는 방법을 알아봅니다.

## 템플릿 기반 폼에서 입력 검증하기

<!--
To add validation to a template-driven form, you add the same validation attributes as you would with [native HTML form validation](https://developer.mozilla.org/docs/Web/Guide/HTML/HTML5/Constraint_validation).
Angular uses directives to match these attributes with validator functions in the framework.

Every time the value of a form control changes, Angular runs validation and generates either a list of validation errors that results in an `INVALID` status, or `null`, which results in a `VALID` status.

You can then inspect the control's state by exporting `ngModel` to a local template variable.
The following example exports `NgModel` into a variable called `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"/>

Notice the following features illustrated by the example.

- The `<input>` element carries the HTML validation attributes: `required` and `minlength`.
  It also carries a custom validator directive, `forbiddenName`.
  For more information, see the [Custom validators](#defining-custom-validators) section.

- `#name="ngModel"` exports `NgModel` into a local variable called `name`.
  `NgModel` mirrors many of the properties of its underlying `FormControl` instance, so you can use this in the template to check for control states such as `valid` and `dirty`.
  For a full list of control properties, see the [AbstractControl](api/forms/AbstractControl) API reference.
  - The outermost `@if` reveals a set of nested messages but only if the `name` is invalid and the control is either `dirty` or `touched`.

- Each nested `@if` can present a custom message for one of the possible validation errors.
    There are messages for `required`, `minlength`, and `forbiddenName`.

HELPFUL: To prevent the validator from displaying errors before the user has a chance to edit the form, you should check for either the `dirty` or `touched` states in a control.

- When the user changes the value in the watched field, the control is marked as "dirty"
- When the user blurs the form control element, the control is marked as "touched"
-->

템플릿 기반 폼에 유효성 검사를 추가하려면 [네이티브 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` 등의 컨트롤 상태를 확인할 수 있습니다.
  컨트롤 프로퍼티의 전체 목록은 [AbstractControl](api/forms/AbstractControl) API 레퍼런스를 참고하세요.
  - 가장 바깥쪽 `@if`는 `name`이 유효하지 않으면서 컨트롤이 `dirty` 또는 `touched` 상태일 때만 내부 메시지를 표시합니다.

- 내부의 각 `@if`는 발생할 수 있는 유효성 검사 오류별로 메시지를 표시합니다.
    `required`, `minlength`, `forbiddenName` 오류에 대한 메시지가 있습니다.

참고: 사용자가 폼을 수정하기도 전에 오류가 표시되지 않도록 컨트롤이 `dirty` 또는 `touched` 상태인지 확인하는 것이 좋습니다.

- 사용자가 감시 중인 필드의 값을 변경하면 컨트롤은 "dirty" 상태가 됩니다.
- 폼 컨트롤 엘리먼트에서 포커스가 벗어나면 컨트롤은 "touched" 상태가 됩니다.

## 반응형 폼에서 입력 검증하기

반응형 폼에서는 컴포넌트 클래스가 원본 데이터를 관리합니다.
템플릿의 어트리뷰트로 검증 함수를 추가하는 대신, 컴포넌트 클래스의 폼 컨트롤 모델에 검증 함수를 직접 추가합니다.
그러면 Angular는 컨트롤 값이 변경될 때마다 이 함수를 실행합니다.

### 검증 함수

<!--
Validator functions can be either synchronous or asynchronous.

| Validator type   | Details                                                                                                                                                                                                                 |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sync validators  | Synchronous functions that take a control instance and immediately return either a set of validation errors or `null`. Pass these in as the second argument when you instantiate a `FormControl`.                       |
| Async validators | Asynchronous functions that take a control instance and return a Promise or Observable that later emits a set of validation errors or `null`. Pass these in as the third argument when you instantiate a `FormControl`. |

For performance reasons, Angular only runs async validators if all sync validators pass.
Each must complete before errors are set.
-->

검증 함수는 동기 또는 비동기 방식으로 동작할 수 있습니다.

| 검증 함수 종류   | 설명                                                                                                                                                                                              |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 동기 검증 함수   | 컨트롤 인스턴스를 인자로 받고, 유효성 검사 오류 모음 또는 `null`을 즉시 반환하는 동기 함수입니다. `FormControl` 인스턴스를 생성할 때 두 번째 인자로 전달합니다.                                   |
| 비동기 검증 함수 | 컨트롤 인스턴스를 인자로 받고, 이후 유효성 검사 오류 모음 또는 `null`을 전달하는 Promise나 옵저버블을 반환하는 비동기 함수입니다. `FormControl` 인스턴스를 생성할 때 세 번째 인자로 전달합니다. |

성능을 고려해서 Angular는 모든 동기 검증 함수를 통과한 경우에만 비동기 검증 함수를 실행합니다.
각 비동기 검증이 완료된 후에 오류가 설정됩니다.

### 내장 검증 함수

<!--
You can choose to [write your own validator functions](#defining-custom-validators), or you can use some of Angular's built-in validators.

The same built-in validators that are available as attributes in template-driven forms, such as `required` and `minlength`, are all available to use as functions from the `Validators` class.
For a full list of built-in validators, see the [Validators](api/forms/Validators) API reference.

To update the actor form to be a reactive form, use some of the same
built-in validators —this time, in function form, as in the following example.

<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"/>

In this example, the `name` control sets up two built-in validators —`Validators.required` and `Validators.minLength(4)`— and one custom validator, `forbiddenNameValidator`.

All of these validators are synchronous, so they are passed as the second argument.
Notice that you can support multiple validators by passing the functions in as an array.

This example also adds a few getter methods.
In a reactive form, you can always access any form control through the `get` method on its parent group, but sometimes it's useful to define getters as shorthand for the template.

If you look at the template for the `name` input again, it is fairly similar to the template-driven example.

<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"/>

This form differs from the template-driven version in that it no longer exports any directives. Instead, it uses the `name` getter defined in the component class.

Notice that the `required` attribute is still present in the template. Although it's not necessary for validation, it should be retained for accessibility purposes.
-->

[검증 함수를 직접 작성](#defining-custom-validators)하거나 Angular에 내장된 검증 함수를 사용할 수 있습니다.

템플릿 기반 폼에서 어트리뷰트로 사용하는 `required`, `minlength` 등의 내장 검증 기능은 모두 `Validators` 클래스의 함수로도 사용할 수 있습니다.
전체 내장 검증 함수 목록은 [Validators](api/forms/Validators) API 레퍼런스를 참고하세요.

배우 입력 폼을 반응형 폼으로 바꾸려면, 같은 내장 검증 기능을 다음 예제처럼 함수 형태로 사용하면 됩니다.

<docs-code header="actor-form-reactive.component.ts (검증 함수)" 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 메서드도 몇 개 추가했습니다.
반응형 폼에서는 상위 그룹의 `get` 메서드로 모든 폼 컨트롤에 접근할 수 있지만, 템플릿에서 간편하게 사용하도록 getter를 정의하면 편리할 때가 있습니다.

`name` 입력의 템플릿을 다시 보면 템플릿 기반 예제와 상당히 비슷합니다.

<docs-code header="actor-form-reactive.component.html (name과 오류 메시지)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" region="name-with-error-msg"/>

템플릿 기반 버전과 달리 이 폼에서는 디렉티브를 내보내지 않습니다.
대신 컴포넌트 클래스에 정의한 `name` getter를 사용합니다.

템플릿에 `required` 어트리뷰트가 여전히 남아 있다는 점도 확인해 보세요.
유효성 검사에는 필요하지 않지만, 접근성을 위해 유지해야 합니다.

## 커스텀 검증 함수 정의하기

<!--
The built-in validators don't always match the exact use case of your application, so you sometimes need to create a custom validator.

Consider the `forbiddenNameValidator` function from the previous example.
Here's what the definition of that function looks like.

<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"/>

The function is a factory that takes a regular expression to detect a _specific_ forbidden name and returns a validator function.

In this sample, the forbidden name is "bob", so the validator rejects any actor name containing "bob".
Elsewhere it could reject "alice" or any name that the configuring regular expression matches.

The `forbiddenNameValidator` factory returns the configured validator function.
That function takes an Angular control object and returns _either_ null if the control value is valid _or_ a validation error object.
The validation error object typically has a property whose name is the validation key, `'forbiddenName'`, and whose value is an arbitrary dictionary of values that you could insert into an error message, `{name}`.

Custom async validators are similar to sync validators, but they must instead return a Promise or observable that later emits null or a validation error object.
In the case of an observable, the observable must complete, at which point the form uses the last value emitted for validation.
-->

내장 검증 함수가 애플리케이션의 요구사항에 정확히 맞지 않을 수 있으므로, 때로는 커스텀 검증 함수를 만들어야 합니다.

앞의 예제에 사용한 `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}` 같은 임의의 값 모음입니다.

커스텀 비동기 검증 함수도 동기 검증 함수와 비슷하지만, null이나 유효성 검사 오류 객체를 나중에 전달하는 Promise 또는 옵저버블을 반환해야 합니다.
옵저버블을 반환하는 경우에는 반드시 완료되어야 하며, 폼은 완료 시점에 마지막으로 전달된 값을 유효성 검사 결과로 사용합니다.

### 반응형 폼에 커스텀 검증 함수 추가하기

<!--
In reactive forms, add a custom validator by passing the function directly to the `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"/>
-->

반응형 폼에서는 `FormControl`에 함수를 직접 전달해서 커스텀 검증 함수를 추가합니다.

<docs-code header="actor-form-reactive.component.ts (검증 함수)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" region="custom-validator"/>

### 템플릿 기반 폼에 커스텀 검증 함수 추가하기

<!--
In template-driven forms, add a directive to the template, where the directive wraps the validator function.
For example, the corresponding `ForbiddenValidatorDirective` serves as a wrapper around the `forbiddenNameValidator`.

Angular recognizes the directive's role in the validation process because the directive registers itself with the `NG_VALIDATORS` provider, as shown in the following example.
`NG_VALIDATORS` is a predefined provider with an extensible collection of 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"/>

The directive class then implements the `Validator` interface, so that it can easily integrate with Angular forms.
Here is the rest of the directive to help you get an idea of how it all comes together.

<docs-code header="forbidden-name.directive.ts (directive)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="directive"/>

Once the `ForbiddenValidatorDirective` is ready, you can add its selector, `appForbiddenName`, to any input element to activate it.
For example:

<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: Notice that the custom validation directive is instantiated with `useExisting` rather than `useClass`.
The registered validator must be _this instance_ of the `ForbiddenValidatorDirective` —the instance in the form with its `forbiddenName` property bound to "bob".

If you were to replace `useExisting` with `useClass`, then you'd be registering a new class instance, one that doesn't have a `forbiddenName`.
-->

템플릿 기반 폼에서는 검증 함수를 감싼 디렉티브를 템플릿에 추가합니다.
예를 들어 `ForbiddenValidatorDirective`는 `forbiddenNameValidator`를 감싸는 역할을 합니다.

다음 예제처럼 디렉티브가 자신을 `NG_VALIDATORS` 프로바이더에 등록하면 Angular가 해당 디렉티브를 유효성 검사 과정에 사용하는 것으로 인식합니다.
`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 (디렉티브)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="directive"/>

`ForbiddenValidatorDirective`를 만들었다면 입력 엘리먼트에 셀렉터인 `appForbiddenName`을 추가해서 활성화할 수 있습니다.
예를 들면 다음과 같습니다:

참고: 커스텀 유효성 검사 디렉티브는 `useClass`가 아니라 `useExisting`으로 등록합니다.
등록하는 검증 함수는 `forbiddenName` 프로퍼티가 "bob"에 바인딩된, 폼 안의 _해당_ `ForbiddenValidatorDirective` 인스턴스여야 합니다.

`useExisting`을 `useClass`로 바꾸면 `forbiddenName` 값이 없는 새 클래스 인스턴스가 등록됩니다.

## 컨트롤 상태 CSS 클래스

<!--
Angular automatically mirrors many control properties onto the form control element as CSS classes.
Use these classes to style form control elements according to the state of the form.
The following classes are currently supported.

- `.ng-valid`
- `.ng-invalid`
- `.ng-pending`
- `.ng-pristine`
- `.ng-dirty`
- `.ng-untouched`
- `.ng-touched`
- `.ng-submitted` $enclosing form element only$

In the following example, the actor form uses the `.ng-valid` and `.ng-invalid` classes to
set the color of each form control's border.

<docs-code header="forms.css (status classes)" path="adev/src/content/examples/form-validation/src/assets/forms.css"/>
-->

Angular는 여러 컨트롤 프로퍼티를 폼 컨트롤 엘리먼트의 CSS 클래스에 자동으로 반영합니다.
이 클래스를 사용하면 폼 상태에 따라 폼 컨트롤 엘리먼트에 스타일을 적용할 수 있습니다.
현재 다음 클래스를 지원합니다.

- `.ng-valid`
- `.ng-invalid`
- `.ng-pending`
- `.ng-pristine`
- `.ng-dirty`
- `.ng-untouched`
- `.ng-touched`
- `.ng-submitted` $컨트롤을 감싸는 form 엘리먼트에만 적용$

다음 배우 입력 폼 예제에서는 `.ng-valid`와 `.ng-invalid` 클래스로 각 폼 컨트롤의 테두리 색상을 지정합니다.

<docs-code header="forms.css (상태 클래스)" path="adev/src/content/examples/form-validation/src/assets/forms.css"/>

## 여러 필드를 함께 검증하기

<!--
A cross-field validator is a [custom validator](#defining-custom-validators 'Read about custom validators') that compares the values of different fields in a form and accepts or rejects them in combination.
For example, you might have a form that offers mutually incompatible options, so that if the user can choose A or B, but not both.
Some field values might also depend on others; a user might be allowed to choose B only if A is also chosen.

The following cross validation examples show how to do the following:

- Validate reactive or template-based form input based on the values of two sibling controls,
- Show a descriptive error message after the user interacted with the form and the validation failed.

The examples use cross-validation to ensure that actors do not reuse the same name in their role by filling out the Actor Form.
The validators do this by checking that the actor names and roles do not match.
-->

교차 필드 검증 함수는 폼의 서로 다른 필드 값을 비교해서, 값의 조합이 유효한지 판단하는 [커스텀 검증 함수](#defining-custom-validators '커스텀 검증 함수 알아보기')입니다.
예를 들어 서로 양립할 수 없는 선택지를 제공해서 사용자가 A나 B 중 하나만 선택하고 둘을 함께 선택할 수 없도록 하는 폼이 있을 수 있습니다.
어떤 필드 값이 다른 필드에 의존할 수도 있습니다.
예를 들어 A를 선택한 경우에만 B를 선택할 수 있도록 할 수 있습니다.

다음 교차 검증 예제에서는 아래 내용을 알아봅니다:

- 같은 수준에 있는 두 컨트롤의 값을 기준으로 반응형 폼이나 템플릿 기반 폼 입력을 검증합니다.
- 사용자가 폼과 상호작용한 뒤 유효성 검사를 통과하지 못하면 설명 메시지를 표시합니다.

이 예제에서는 배우 입력 폼을 작성할 때 배우 이름과 배역 이름을 동일하게 사용하지 않도록 교차 검증합니다.
검증 함수는 배우 이름과 배역이 서로 다른지 확인합니다.

### 반응형 폼에 교차 검증 추가하기

<!--
The form has the following structure:

```ts
const actorForm = new FormGroup({
  'name': new FormControl(),
  'role': new FormControl(),
  'skill': new FormControl(),
});
```

Notice that the `name` and `role` are sibling controls.
To evaluate both controls in a single custom validator, you must perform the validation in a common ancestor control: the `FormGroup`.
You query the `FormGroup` for its child controls so that you can compare their values.

To add a validator to the `FormGroup`, pass the new validator in as the second argument on creation.

```ts
const actorForm = new FormGroup(
  {
    'name': new FormControl(),
    'role': new FormControl(),
    'skill': new FormControl(),
  },
  {validators: unambiguousRoleValidator},
);
```

The validator code is as follows.

<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"/>

The `unambiguousRoleValidator` validator implements the `ValidatorFn` interface.
It takes an Angular control object as an argument and returns either null if the form is valid, or `ValidationErrors` otherwise.

The validator retrieves the child controls by calling the `FormGroup`'s [get](api/forms/AbstractControl#get) method, then compares the values of the `name` and `role` controls.

If the values do not match, the role is unambiguous, both are valid, and the validator returns null.
If they do match, the actor's role is ambiguous and the validator must mark the form as invalid by returning an error object.

To provide better user experience, the template shows an appropriate error message when the form is invalid.

<docs-code header="actor-form-reactive.component.html" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" region="cross-validation-error-message"/>

This `@if` displays the error if the `FormGroup` has the cross validation error returned by the `unambiguousRoleValidator` validator, but only if the user finished [interacting with the form](#control-status-css-classes).
-->

폼 구조는 다음과 같습니다:

```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`를 반환합니다.

이 검증 함수는 `FormGroup`의 [get](api/forms/AbstractControl#get) 메서드로 하위 컨트롤을 가져온 뒤 `name`과 `role` 컨트롤의 값을 비교합니다.

값이 다르면 배역을 명확히 구분할 수 있고 두 값이 모두 유효하므로 null을 반환합니다.
값이 같으면 배우와 배역을 혼동할 수 있으므로, 오류 객체를 반환해서 폼이 유효하지 않다고 표시해야 합니다.

사용자 경험을 개선하기 위해 폼이 유효하지 않을 때 템플릿에 적절한 오류 메시지를 표시합니다.

<docs-code header="actor-form-reactive.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) 표시합니다.

### 템플릿 기반 폼에 교차 검증 추가하기

<!--
For a template-driven form, you must create a directive to wrap the validator function.
You provide that directive as the validator using the [`NG_VALIDATORS` token](/api/forms/NG_VALIDATORS), as shown in the following example.

<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"/>

You must add the new directive to the HTML template.
Because the validator must be registered at the highest level in the form, the following template puts the directive on the `form` tag.

<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"/>

To provide better user experience, an appropriate error message appears when the form is invalid.

<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"/>

This is the same in both template-driven and reactive forms.
-->

템플릿 기반 폼에서는 검증 함수를 감싼 디렉티브를 만들어야 합니다.
다음 예제처럼 [`NG_VALIDATORS` 토큰](/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-error-message"/>

이 부분은 템플릿 기반 폼과 반응형 폼에서 동일합니다.

## 비동기 검증 함수 만들기

<!--
Asynchronous validators implement the `AsyncValidatorFn` and `AsyncValidator` interfaces.
These are very similar to their synchronous counterparts, with the following differences.

- The `validate()` functions must return a Promise or an observable,
- The observable returned must be finite, meaning that it must complete at some point.
  To convert an infinite observable into a finite one, pipe the observable through a filtering operator such as `first`, `last`, `take`, or `takeUntil`.

Asynchronous validation happens after the synchronous validation, and is performed only if the synchronous validation is successful.
This check lets forms avoid potentially expensive async validation processes $such as an HTTP request$ if the more basic validation methods have already found invalid input.

After asynchronous validation begins, the form control enters a `pending` state.
Inspect the control's `pending` property and use it to give visual feedback about the ongoing validation operation.

A common UI pattern is to show a spinner while the async validation is being performed.
The following example shows how to achieve this in a template-driven form.

```html
<input [(ngModel)]="name" #model="ngModel" appSomeAsyncValidator />

@if (model.pending) {
  <app-spinner />
}
```
-->

비동기 검증 함수는 `AsyncValidatorFn` 또는 `AsyncValidator` 인터페이스를 구현합니다.
동기 검증 함수와 매우 비슷하지만 다음과 같은 차이가 있습니다.

- `validate()` 함수는 Promise 또는 옵저버블을 반환해야 합니다.
- 반환하는 옵저버블은 유한해야 합니다.
  즉, 언젠가는 완료되어야 합니다.
  무한한 옵저버블을 유한한 옵저버블로 바꾸려면 `first`, `last`, `take`, `takeUntil` 같은 필터링 연산자를 파이프로 연결하면 됩니다.

비동기 유효성 검사는 동기 유효성 검사 이후에, 동기 검사를 통과한 경우에만 실행합니다.
따라서 기본적인 검사에서 이미 유효하지 않은 입력을 발견했다면 HTTP 요청처럼 비용이 많이 들 수 있는 비동기 검사 과정을 생략할 수 있습니다.

비동기 유효성 검사가 시작되면 폼 컨트롤은 `pending` 상태가 됩니다.
컨트롤의 `pending` 프로퍼티를 확인해서 검사가 진행 중임을 화면에 표시할 수 있습니다.

비동기 검사가 진행되는 동안 로딩 표시를 보여주는 것이 일반적인 UI 패턴입니다.
다음 예제는 템플릿 기반 폼에서 이를 구현하는 방법입니다.

```html
<input [(ngModel)]="name" #model="ngModel" appSomeAsyncValidator />

@if (model.pending) {
  <app-spinner />
}
```

### 커스텀 비동기 검증 함수 구현하기

<!--
In the following example, an async validator ensures that actors are cast for a role that is not already taken.
New actors are constantly auditioning and old actors are retiring, so the list of available roles cannot be retrieved ahead of time.
To validate the potential role entry, the validator must initiate an asynchronous operation to consult a central database of all currently cast actors.

The following code creates the validator class, `UniqueRoleValidator`, which implements the `AsyncValidator` interface.

<docs-code header="role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" region="async-validator"/>

The `actorsService` property is initialized with an instance of the `ActorsService` token, which defines the following interface.

```ts
interface ActorsService {
  isRoleTaken: (role: string) => Observable<boolean>;
}
```

In a real world application, the `ActorsService` would be responsible for making an HTTP request to the actor database to check if the role is available.
From the validator's point of view, the actual implementation of the service is not important, so the example can just code against the `ActorsService` interface.

As the validation begins, the `UniqueRoleValidator` delegates to the `ActorsService` `isRoleTaken()` method with the current control value.
At this point the control is marked as `pending` and remains in this state until the observable chain returned from the `validate()` method completes.

The `isRoleTaken()` method dispatches an HTTP request that checks if the role is available, and returns `Observable<boolean>` as the result.
The `validate()` method pipes the response through the `map` operator and transforms it into a validation result.

The method then, like any validator, returns `null` if the form is valid, and `ValidationErrors` if it is not.
This validator handles any potential errors with the `catchError` operator.
In this case, the validator treats the `isRoleTaken()` error as a successful validation, because failure to make a validation request does not necessarily mean that the role is invalid.
You could handle the error differently and return the `ValidationError` object instead.

After some time passes, the observable chain completes and the asynchronous validation is done.
The `pending` flag is set to `false`, and the form validity is updated.
-->

다음 예제의 비동기 검증 함수는 배우가 아직 다른 배우에게 배정되지 않은 배역을 맡도록 합니다.
새 배우가 계속 오디션을 보고 기존 배우가 은퇴하므로, 선택할 수 있는 배역 목록을 미리 가져올 수는 없습니다.
입력한 배역을 검증하려면 현재 배역을 맡은 배우들의 중앙 데이터베이스를 조회하는 비동기 작업을 시작해야 합니다.

다음 코드는 `AsyncValidator` 인터페이스를 구현한 `UniqueRoleValidator` 검증 클래스를 만듭니다.

<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` 상태가 되며, `validate()` 메서드가 반환한 옵저버블 체인이 완료될 때까지 이 상태를 유지합니다.

`isRoleTaken()` 메서드는 배역을 선택할 수 있는지 확인하는 HTTP 요청을 보내고 결과로 `Observable<boolean>`을 반환합니다.
`validate()` 메서드는 응답을 `map` 연산자로 전달해서 유효성 검사 결과로 변환합니다.

그런 다음 다른 검증 함수와 마찬가지로 폼이 유효하면 `null`을, 그렇지 않으면 `ValidationErrors`를 반환합니다.
이 검증 함수는 발생할 수 있는 오류를 `catchError` 연산자로 처리합니다.
이 예제에서는 `isRoleTaken()`의 오류를 유효성 검사 통과로 처리합니다.
검사 요청에 실패했다고 해서 반드시 배역이 유효하지 않은 것은 아니기 때문입니다.
오류를 다르게 처리해서 `ValidationError` 객체를 반환하도록 할 수도 있습니다.

시간이 지나 옵저버블 체인이 완료되면 비동기 유효성 검사도 끝납니다.
`pending` 값은 `false`가 되고 폼의 유효성 상태가 갱신됩니다.

### 반응형 폼에 비동기 검증 함수 추가하기

<!--
To use an async validator in reactive forms, begin by injecting the validator into a property of the component class.

<docs-code header="actor-form-reactive.component.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-inject"/>

Then, pass the validator function directly to the `FormControl` to apply it.

In the following example, the `validate` function of `UniqueRoleValidator` is applied to `roleControl` by passing it to the control's `asyncValidators` option and binding it to the instance of `UniqueRoleValidator` that was injected into `ActorFormReactiveComponent`.
The value of `asyncValidators` can be either a single async validator function, or an array of functions.
To learn more about `FormControl` options, see the [AbstractControlOptions](api/forms/AbstractControlOptions) API reference.

<docs-code header="actor-form-reactive.component.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-usage"/>
-->

반응형 폼에서 비동기 검증 함수를 사용하려면 먼저 컴포넌트 클래스의 프로퍼티에 검증 객체를 주입합니다.

<docs-code header="actor-form-reactive.component.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-inject"/>

그런 다음 검증 함수를 `FormControl`에 직접 전달해서 적용합니다.

다음 예제에서는 `UniqueRoleValidator`의 `validate` 함수를 컨트롤의 `asyncValidators` 옵션에 전달하고, `ActorFormReactiveComponent`에 주입한 `UniqueRoleValidator` 인스턴스에 바인딩해서 `roleControl`에 적용합니다.
`asyncValidators`에는 비동기 검증 함수 하나 또는 함수 배열을 지정할 수 있습니다.
`FormControl` 옵션에 대해 자세히 알아보려면 [AbstractControlOptions](api/forms/AbstractControlOptions) API 레퍼런스를 참고하세요.

<docs-code header="actor-form-reactive.component.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-usage"/>

### 템플릿 기반 폼에 비동기 검증 함수 추가하기

<!--
To use an async validator in template-driven forms, create a new directive and register the `NG_ASYNC_VALIDATORS` provider on it.

In the example below, the directive injects the `UniqueRoleValidator` class that contains the actual validation logic and invokes it in the `validate` function, triggered by Angular when validation should happen.

<docs-code header="role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" region="async-validator-directive"/>

Then, as with synchronous validators, add the directive's selector to an input to activate it.

<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"/>
-->

템플릿 기반 폼에서 비동기 검증 함수를 사용하려면 새 디렉티브를 만들고 `NG_ASYNC_VALIDATORS` 프로바이더에 등록합니다.

다음 예제에서 디렉티브는 실제 검증 로직을 가진 `UniqueRoleValidator` 클래스를 주입받습니다.
Angular가 유효성 검사를 실행할 때 호출하는 `validate` 함수에서 이 객체를 사용합니다.

<docs-code header="role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" region="async-validator-directive"/>

그런 다음 동기 검증 함수와 마찬가지로 입력 엘리먼트에 디렉티브 셀렉터를 추가해서 활성화합니다.

### 비동기 검증 함수 성능 최적화하기

<!--
By default, all validators run after every form value change.
With synchronous validators, this does not normally have a noticeable impact on application performance.
Async validators, however, commonly perform some kind of HTTP request to validate the control.
Dispatching an HTTP request after every keystroke could put a strain on the backend API, and should be avoided if possible.

You can delay updating the form validity by changing the `updateOn` property from `change` (default) to `submit` or `blur`.

With template-driven forms, set the property in the template.

```html
<input [(ngModel)]="name" [ngModelOptions]="{updateOn: 'blur'}" />
```

With reactive forms, set the property in the `FormControl` instance.

```ts
new FormControl('', {updateOn: 'blur'});
```
-->

기본적으로 모든 검증 함수는 폼 값이 변경될 때마다 실행됩니다.
동기 검증 함수는 보통 애플리케이션 성능에 눈에 띄는 영향을 미치지 않습니다.
하지만 비동기 검증 함수는 컨트롤을 검증하기 위해 HTTP 요청을 보내는 경우가 많습니다.
키를 누를 때마다 HTTP 요청을 보내면 백엔드 API에 부담을 줄 수 있으므로 가능하면 피하는 것이 좋습니다.

`updateOn` 프로퍼티를 기본값인 `change`에서 `submit` 또는 `blur`로 바꾸면 폼 유효성 상태를 갱신하는 시점을 늦출 수 있습니다.

템플릿 기반 폼에서는 템플릿에 프로퍼티를 설정합니다.

```html
<input [(ngModel)]="name" [ngModelOptions]="{updateOn: 'blur'}" />
```

반응형 폼에서는 `FormControl` 인스턴스에 프로퍼티를 설정합니다.

```ts
new FormControl('', {updateOn: 'blur'});
```

## 반응형 폼에서 검증 함수를 동적으로 관리하기

복잡한 반응형 폼에서는 사용자 입력이나 애플리케이션 상태에 따라 검증 함수를 추가하거나 제거하거나 변경해야 할 수 있습니다.
Angular는 폼 컨트롤을 다시 생성하지 않고도 런타임에 검증 함수를 관리할 수 있도록 `AbstractControl`에 여러 메서드를 제공합니다.

### 검증 함수 추가하고 제거하기

<!--
The [`addValidators`](api/forms/AbstractControl#addValidators) and [`removeValidators`](api/forms/AbstractControl#removeValidators) methods allow you to modify a control's validators after initialization.
Angular matches validators by reference, so you must pass the same function to `removeValidators` that you passed to `addValidators`.

```ts
private readonly usPostalCode = Validators.pattern(/^\d{5}$/);

onCountryChange(country: string) {
    const postalCodeControl = this.profileForm.get('postalCode');

if (country === 'US') {
      // Add validators for US postal codes
      postalCodeControl.addValidators([Validators.required, this.usPostalCode]);
    } else {
      // Remove validators when not US
      postalCodeControl.removeValidators([Validators.required, this.usPostalCode]);
    }

postalCodeControl.updateValueAndValidity();
}
```
-->

[`addValidators`](api/forms/AbstractControl#addValidators)와 [`removeValidators`](api/forms/AbstractControl#removeValidators) 메서드를 사용하면 초기화 이후에도 컨트롤의 검증 함수를 변경할 수 있습니다.
Angular는 검증 함수를 참조로 비교하므로 `removeValidators`에는 `addValidators`에 전달했던 것과 동일한 함수를 전달해야 합니다.

```ts
private readonly usPostalCode = Validators.pattern(/^\d{5}$/);

onCountryChange(country: string) {
    const postalCodeControl = this.profileForm.get('postalCode');

if (country === 'US') {
      // 미국 우편번호 검증 함수를 추가합니다.
      postalCodeControl.addValidators([Validators.required, this.usPostalCode]);
    } else {
      // 미국이 아니면 검증 함수를 제거합니다.
      postalCodeControl.removeValidators([Validators.required, this.usPostalCode]);
    }

postalCodeControl.updateValueAndValidity();
}
```

### 모든 검증 함수 교체하기

<!--
Use [`setValidators`](api/forms/AbstractControl#setValidators) to replace all existing synchronous validators on a control, or [`clearValidators`](api/forms/AbstractControl#clearValidators) to remove all validators.

```ts
toggleStrictNameValidation(isStrict: boolean) {
  const nameControl = this.profileForm.get('name');

if (isStrict) {
    // Set strict validation rules
    nameControl.setValidators([
      Validators.required,
      Validators.minLength(3),
      Validators.pattern(/^[a-zA-Z]+$/),
    ]);
  } else {
    // Clear all validators
    nameControl.clearValidators();
  }

nameControl.updateValueAndValidity();
}
```

The same pattern applies to async validators using [`addAsyncValidators`](api/forms/AbstractControl#addAsyncValidators), [`removeAsyncValidators`](api/forms/AbstractControl#removeAsyncValidators), [`setAsyncValidators`](api/forms/AbstractControl#setAsyncValidators), and [`clearAsyncValidators`](api/forms/AbstractControl#clearAsyncValidators).
-->

컨트롤의 기존 동기 검증 함수를 모두 교체하려면 [`setValidators`](api/forms/AbstractControl#setValidators)를 사용하고, 모두 제거하려면 [`clearValidators`](api/forms/AbstractControl#clearValidators)를 사용합니다.

```ts
toggleStrictNameValidation(isStrict: boolean) {
  const nameControl = this.profileForm.get('name');

if (isStrict) {
    // 엄격한 유효성 검사 규칙을 설정합니다.
    nameControl.setValidators([
      Validators.required,
      Validators.minLength(3),
      Validators.pattern(/^[a-zA-Z]+$/),
    ]);
  } else {
    // 모든 검증 함수를 제거합니다.
    nameControl.clearValidators();
  }

nameControl.updateValueAndValidity();
}
```

비동기 검증 함수에도 [`addAsyncValidators`](api/forms/AbstractControl#addAsyncValidators), [`removeAsyncValidators`](api/forms/AbstractControl#removeAsyncValidators), [`setAsyncValidators`](api/forms/AbstractControl#setAsyncValidators), [`clearAsyncValidators`](api/forms/AbstractControl#clearAsyncValidators)를 사용해서 같은 패턴을 적용할 수 있습니다.

### 유효성 검사 상태 갱신하기

<!--
After modifying validators, call [`updateValueAndValidity`](api/forms/AbstractControl#updateValueAndValidity) to recalculate the control's validation status.
This method accepts options to control update behavior.

```ts
// Update control and notify parent
control.updateValueAndValidity();

// Update control only, don't notify parent or emit events
control.updateValueAndValidity({onlySelf: true, emitEvent: false});
```
-->

검증 함수를 변경한 뒤에는 [`updateValueAndValidity`](api/forms/AbstractControl#updateValueAndValidity)를 실행해서 컨트롤의 유효성 검사 상태를 다시 계산합니다.
이 메서드는 갱신 동작을 제어하는 옵션을 받습니다.

```ts
// 컨트롤을 갱신하고 상위 컨트롤에 알립니다.
control.updateValueAndValidity();

// 상위 컨트롤에 알리거나 이벤트를 보내지 않고 이 컨트롤만 갱신합니다.
control.updateValueAndValidity({onlySelf: true, emitEvent: false});
```

## 네이티브 HTML 폼 유효성 검사와 함께 사용하기

Angular는 기본적으로 바깥쪽 `<form>`에 `novalidate` 어트리뷰트를 추가해서 [네이티브 HTML 폼 유효성 검사](https://developer.mozilla.org/docs/Web/Guide/HTML/Constraint_validation)를 비활성화하고, 디렉티브로 유효성 검사 어트리뷰트를 프레임워크의 검증 함수와 연결합니다.
Angular 유효성 검사와 네이티브 유효성 검사를 **함께** 사용하려면 `ngNativeValidate` 디렉티브로 네이티브 검사를 다시 활성화할 수 있습니다.
자세한 내용은 [API 문서](api/forms/NgForm#native-dom-validation-ui)를 참고하세요.

# 동적 폼 만들기

<!--
Many forms, such as questionnaires, can be very similar to one another in format and intent.
To make it faster and easier to generate different versions of such a form, you can create a _dynamic form template_ based on metadata that describes the business object model.
Then, use the template to generate new forms automatically, according to changes in the data model.

The technique is particularly useful when you have a type of form whose content must change frequently to meet rapidly changing business and regulatory requirements.
A typical use-case is a questionnaire.
You might need to get input from users in different contexts.
The format and style of the forms a user sees should remain constant, while the actual questions you need to ask vary with the context.

In this tutorial, you will build a dynamic form that presents a basic questionnaire.
You build an online application for heroes seeking employment.
The agency is constantly tinkering with the application process, but by using the dynamic form
you can create the new forms on the fly without changing the application code.

The tutorial walks you through the following steps:

1. Enable reactive forms for a project.
1. Establish a data model to represent form controls.
1. Populate the model with sample data.
1. Develop a component to create form controls dynamically.

The form you create uses input validation and styling to improve the user experience.
It has a Save button that is only enabled when all user input is valid, and flags invalid input with color coding and error messages.

The basic version can evolve to support a richer variety of questions, more graceful rendering, and superior user experience.
-->

설문지처럼 형식과 목적이 서로 비슷한 폼이 많습니다.
이런 폼의 여러 버전을 더 빠르고 쉽게 만들려면 비즈니스 객체 모델을 설명하는 메타데이터를 바탕으로 _동적 폼 템플릿_ 을 만들면 됩니다.
그런 다음 데이터 모델이 변경될 때마다 이 템플릿으로 새 폼을 자동으로 생성할 수 있습니다.

이 방법은 빠르게 바뀌는 업무 요구사항이나 규제에 맞춰 폼 내용을 자주 변경해야 하는 경우에 특히 유용합니다.
대표적인 사례는 설문지입니다.
상황에 따라 사용자에게 서로 다른 내용을 입력받아야 할 수 있습니다.
이때 사용자에게 보이는 폼의 형식과 스타일은 일정하게 유지하면서, 실제 질문은 상황에 맞춰 바꿀 수 있어야 합니다.

이 튜토리얼에서는 간단한 설문지를 표시하는 동적 폼을 만들어 봅니다.
일자리를 찾는 히어로를 위한 온라인 지원서를 만드는 예제입니다.
채용 기관에서는 지원 절차를 계속 수정하지만, 동적 폼을 사용하면 애플리케이션 코드를 변경하지 않고도 새 폼을 바로 만들 수 있습니다.

다음 순서로 진행합니다:

1. 프로젝트에서 반응형 폼을 사용할 수 있도록 설정합니다.
1. 폼 컨트롤을 표현하는 데이터 모델을 정의합니다.
1. 모델에 예제 데이터를 채웁니다.
1. 폼 컨트롤을 동적으로 생성하는 컴포넌트를 만듭니다.

만들 폼에는 사용자 경험을 개선하기 위해 입력 유효성 검사와 스타일을 적용합니다.
모든 입력 값이 유효할 때만 저장 버튼이 활성화되며, 유효하지 않은 입력은 색상과 오류 메시지로 표시합니다.

이 기본 구현을 확장하면 더 다양한 질문을 지원하고, 화면 표시를 다듬으며, 사용자 경험을 개선할 수 있습니다.

## 프로젝트에서 반응형 폼 사용하기

<!--
Dynamic forms are based on reactive forms.

To give the application access to reactive form directives, import `ReactiveFormsModule` from the `@angular/forms` package into the necessary components.
-->

동적 폼은 반응형 폼을 기반으로 합니다.

애플리케이션에서 반응형 폼 디렉티브를 사용하려면 필요한 컴포넌트에서 `@angular/forms` 패키지의 `ReactiveFormsModule`을 로드하면 됩니다.

## 폼 객체 모델 만들기

<!--
A dynamic form requires an object model that can describe all scenarios needed by the form functionality.
The example hero-application form is a set of questions — that is, each control in the form must ask a question and accept an answer.

The data model for this type of form must represent a question.
The example includes the `DynamicFormQuestionComponent`, which defines a question as the fundamental object in the model.

The following `QuestionBase` is a base class for a set of controls that can represent the question and its answer in the form.

<docs-code header="question-base.ts" path="adev/src/content/examples/dynamic-form/src/app/question-base.ts"/>
-->

동적 폼에는 폼 기능에 필요한 모든 상황을 표현할 수 있는 객체 모델이 필요합니다.
히어로 지원서 예제는 질문의 모음입니다.
즉, 폼의 각 컨트롤은 질문을 하나 표시하고 답변을 받아야 합니다.

이런 폼의 데이터 모델은 질문을 표현할 수 있어야 합니다.
이 예제에는 질문을 모델의 기본 객체로 사용하는 `DynamicFormQuestionComponent`가 있습니다.

다음 `QuestionBase`는 폼에서 질문과 답변을 표현하는 컨트롤의 기본 클래스입니다.

<docs-code header="question-base.ts" path="adev/src/content/examples/dynamic-form/src/app/question-base.ts"/>

### 컨트롤 클래스 정의하기

<!--
From this base, the example derives two new classes, `TextboxQuestion` and `DropdownQuestion`, that represent different control types.
When you create the form template in the next step, you instantiate these specific question types in order to render the appropriate controls dynamically.

The `TextboxQuestion` control type is represented in a form template using an `<input>` element. It presents a question and lets users enter input. The `type` attribute of the element is defined based on the `type` field specified in the `options` argument (for example `text`, `email`, `url`).

<docs-code header="question-textbox.ts" path="adev/src/content/examples/dynamic-form/src/app/question-textbox.ts"/>

The `DropdownQuestion` control type presents a list of choices in a select box.

<docs-code header="question-dropdown.ts" path="adev/src/content/examples/dynamic-form/src/app/question-dropdown.ts"/>
-->

이 예제에서는 기본 클래스를 상속해서 서로 다른 컨트롤 타입을 표현하는 `TextboxQuestion`과 `DropdownQuestion` 클래스를 만듭니다.
다음 단계에서 폼 템플릿을 만들 때 각 질문 타입의 인스턴스를 생성해서 알맞은 컨트롤을 동적으로 렌더링합니다.

`TextboxQuestion` 컨트롤은 폼 템플릿에서 `<input>` 엘리먼트로 표현합니다.
질문을 표시하고 사용자가 값을 입력할 수 있도록 합니다.
엘리먼트의 `type` 어트리뷰트는 `options` 인자에 지정한 `type` 필드에 따라 정해집니다.
예를 들어 `text`, `email`, `url`을 지정할 수 있습니다.

<docs-code header="question-textbox.ts" path="adev/src/content/examples/dynamic-form/src/app/question-textbox.ts"/>

`DropdownQuestion` 컨트롤은 선택 상자에 선택지 목록을 표시합니다.

<docs-code header="question-dropdown.ts" path="adev/src/content/examples/dynamic-form/src/app/question-dropdown.ts"/>

### 폼 그룹 구성하기

<!--
A dynamic form uses a service to create grouped sets of input controls, based on the form model.
The following `QuestionControlService` builds a `FormGroup` of `FormControl` instances from the metadata in the question model.
You can specify default values and validation rules.

<docs-code header="question-control.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question-control.service.ts"/>
-->

동적 폼은 서비스를 사용해서 폼 모델에 따라 입력 컨트롤을 그룹으로 묶어 생성합니다.
다음 `QuestionControlService`는 질문 모델의 메타데이터를 바탕으로 `FormControl` 인스턴스들로 구성된 `FormGroup`을 생성합니다.
기본값과 유효성 검사 규칙도 지정할 수 있습니다.

<docs-code header="question-control.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question-control.service.ts"/>

## 동적 폼 내용 구성하기

<!--
The dynamic form itself is represented by a container component, which you add in a later step.
Each question is represented in the form component's template by an `<app-question>` tag, which matches an instance of `DynamicFormQuestionComponent`.

The `DynamicFormQuestionComponent` is responsible for rendering the details of an individual question based on values in the data-bound question object.
The form relies on a [`[formGroup]` directive](api/forms/FormGroupDirective 'API reference') to connect the template HTML to the underlying control objects.
The `DynamicFormQuestionComponent` receives the form group built by `QuestionControlService` and renders the control for its question, displaying validation state based on the rules set there.
The goal of the `DynamicFormQuestionComponent` is to present question types defined in your model.
You only have two types of questions at this point but you can imagine many more.
The `@switch` block in the template determines which type of question to display.
The switch uses directives with the [`formControlName`](api/forms/FormControlName 'FormControlName directive API reference') and [`formGroup`](api/forms/FormGroupDirective 'FormGroupDirective API reference') selectors.
Both directives are defined in `ReactiveFormsModule`.
-->

동적 폼 자체는 이후 단계에서 추가할 컨테이너 컴포넌트로 표현합니다.
폼 컴포넌트의 템플릿에서 각 질문은 `<app-question>` 태그로 표현하며, 이 태그는 `DynamicFormQuestionComponent` 인스턴스에 대응합니다.

`DynamicFormQuestionComponent`는 데이터 바인딩으로 전달된 질문 객체의 값에 따라 개별 질문의 세부 내용을 렌더링합니다.
폼은 [`[formGroup]` 디렉티브](api/forms/FormGroupDirective 'API 레퍼런스')를 사용해서 템플릿 HTML과 실제 컨트롤 객체를 연결합니다.
`DynamicFormQuestionComponent`는 `QuestionControlService`가 생성한 폼 그룹을 전달받아 해당 질문의 컨트롤을 렌더링하고, 서비스에서 설정한 규칙에 따라 유효성 검사 상태를 표시합니다.
`DynamicFormQuestionComponent`의 목적은 모델에 정의된 질문 타입을 화면에 표시하는 것입니다.
지금은 질문 타입이 두 가지뿐이지만, 더 다양한 타입을 추가할 수도 있습니다.
템플릿의 `@switch` 블록은 어떤 질문 타입을 표시할지 결정합니다.
이 블록에서는 [`formControlName`](api/forms/FormControlName 'FormControlName 디렉티브 API 레퍼런스')과 [`formGroup`](api/forms/FormGroupDirective 'FormGroupDirective API 레퍼런스') 셀렉터를 사용하는 디렉티브를 활용합니다.
두 디렉티브는 모두 `ReactiveFormsModule`에 정의되어 있습니다.

### 데이터 제공하기

<!--
Another service is needed to supply a specific set of questions from which to build an individual form.
For this exercise you create the `QuestionService` to supply this array of questions from the hard-coded sample data.
In a real-world app, the service might fetch data from a backend system.
The key point, however, is that you control the hero job-application questions entirely through the objects returned from `QuestionService`.
To maintain the questionnaire as requirements change, you only need to add, update, and remove objects from the `questions` array.

The `QuestionService` supplies a set of questions in the form of an array bound to `input()` questions.

<docs-code header="question.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question.service.ts"/>
-->

각 폼을 구성할 구체적인 질문 목록을 제공하는 서비스도 필요합니다.
이 예제에서는 코드에 직접 작성한 예제 데이터로 질문 배열을 제공하는 `QuestionService`를 만듭니다.
실제 애플리케이션에서는 이 서비스가 백엔드 시스템에서 데이터를 받아올 수도 있습니다.
중요한 점은 히어로 지원서의 질문 전체를 `QuestionService`가 반환하는 객체로 제어한다는 것입니다.
요구사항이 변경되어 설문지를 수정하려면 `questions` 배열의 객체를 추가하거나 수정하거나 제거하기만 하면 됩니다.

`QuestionService`는 `input()`으로 선언한 questions에 바인딩할 질문 배열을 제공합니다.

<docs-code header="question.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question.service.ts"/>

## 동적 폼 템플릿 만들기

<!--
The `DynamicFormComponent` component is the entry point and the main container for the form, which is represented using the `<app-dynamic-form>` in a template.

The `DynamicFormComponent` component presents a list of questions by binding each one to an `<app-question>` element that matches the `DynamicFormQuestionComponent`.
-->

`DynamicFormComponent`는 폼의 진입점이자 최상위 컨테이너이며, 템플릿에서는 `<app-dynamic-form>`으로 표현합니다.

`DynamicFormComponent`는 각 질문을 `DynamicFormQuestionComponent`에 대응하는 `<app-question>` 엘리먼트에 바인딩해서 질문 목록을 표시합니다.

### 폼 표시하기

<!--
To display an instance of the dynamic form, the `AppComponent` shell template passes the `questions` array returned by the `QuestionService` to the form container component, `<app-dynamic-form>`.

<docs-code header="app.component.ts" path="adev/src/content/examples/dynamic-form/src/app/app.component.ts"/>

This separation of model and data lets you repurpose the components for any type of survey, as long as it's compatible with the _question_ object model.
-->

동적 폼 인스턴스를 화면에 표시하기 위해 `AppComponent`의 최상위 템플릿에서 `QuestionService`가 반환한 `questions` 배열을 폼 컨테이너 컴포넌트인 `<app-dynamic-form>`에 전달합니다.

<docs-code header="app.component.ts" path="adev/src/content/examples/dynamic-form/src/app/app.component.ts"/>

이렇게 모델과 데이터를 분리하면 _질문_ 객체 모델과 호환되는 모든 종류의 설문에 컴포넌트를 재사용할 수 있습니다.

### 데이터 유효성 보장하기

<!--
The form template uses dynamic data binding of metadata to render the form without making any hardcoded assumptions about specific questions.
It adds both control metadata and validation criteria dynamically.

To ensure valid input, the _Save_ button is disabled until the form is in a valid state.
When the form is valid, click _Save_ and the application renders the current form values as JSON.

The following figure shows the final form.

폼 템플릿은 메타데이터를 동적으로 바인딩해서 폼을 렌더링합니다.
따라서 특정 질문에 대한 가정을 코드에 고정해 둘 필요가 없습니다.
컨트롤 메타데이터와 유효성 검사 기준은 모두 동적으로 추가합니다.

유효한 값만 입력받기 위해 폼이 유효한 상태가 될 때까지 _Save_ 버튼을 비활성화합니다.
폼이 유효한 상태에서 _Save_ 버튼을 클릭하면 애플리케이션이 현재 폼 값을 JSON 형식으로 표시합니다.

완성된 폼은 다음과 같습니다.

## 다음 단계

<!--

-->

Angular 라우터(`@angular/router`)는 Angular 애플리케이션의 내비게이션을 관리하는 공식 라이브러리이며, 프레임워크의 핵심 구성 요소입니다.
Angular CLI로 생성한 모든 프로젝트에 기본으로 포함됩니다.

## SPA에 라우팅이 필요한 이유

<!--
When you navigate to a URL in your web browser, the browser normally makes a network request to a web server and displays the returned HTML page. When you navigate to a different URL, such as clicking a link, the browser makes another network request and replaces the entire page with a new one.

A single-page application (SPA) differs in that the browser only makes a request to a web server for the first page, the `index.html`. After that, a client-side router takes over, controlling which content displays based on the URL. When a user navigates to a different URL, the router updates the page's content in place without triggering a full-page reload.
-->

웹 브라우저에서 URL로 이동하면 일반적으로 브라우저가 웹 서버에 네트워크 요청을 보내고, 반환된 HTML 페이지를 표시합니다.
링크를 클릭하는 등 다른 URL로 이동하면 브라우저가 다시 네트워크 요청을 보내고 전체 페이지를 새 페이지로 교체합니다.

싱글 페이지 애플리케이션(SPA)은 첫 페이지인 `index.html`을 가져올 때만 브라우저가 웹 서버에 페이지를 요청한다는 점이 다릅니다.
그 이후에는 클라이언트 라우터가 URL을 기준으로 표시할 내용을 제어합니다.
사용자가 다른 URL로 이동하면 라우터가 전체 페이지를 다시 로드하지 않고 현재 페이지의 내용을 갱신합니다.

## Angular의 라우팅 관리 방식

<!--
Routing in Angular is comprised of three primary parts:

1. **Routes** define which component displays when a user visits a specific URL.
2. **Outlets** are placeholders in your templates that dynamically load and render components based on the active route.
3. **Links** provide a way for users to navigate between different routes in your application without triggering a full page reload.

In addition, the Angular Routing library offers additional functionality such as:

- Nested routes
- Programmatic navigation
- Route params, queries and wildcards
- Activated route information with `ActivatedRoute`
- Data fetching with route resources and resolvers
- View transition effects
- Navigation guards
-->

Angular 라우팅은 크게 세 가지로 구성됩니다.

1. **라우팅 규칙**은 사용자가 특정 URL에 방문했을 때 표시할 컴포넌트를 정의합니다.
2. **아웃렛**은 활성 라우팅 규칙을 기준으로 컴포넌트를 동적으로 로드하고 렌더링할 위치를 템플릿에 지정합니다.
3. **링크**는 전체 페이지를 다시 로드하지 않고 애플리케이션의 여러 라우팅 규칙 사이를 이동하는 수단입니다.

Angular 라우팅 라이브러리는 다음 기능도 제공합니다.

- 중첩 라우팅 규칙
- 코드로 실행하는 내비게이션
- 라우팅 규칙 파라미터, 쿼리, 와일드카드
- `ActivatedRoute`로 확인하는 활성 라우팅 규칙 정보
- 라우팅 규칙 리소스와 리졸버로 데이터 가져오기
- 뷰 전환 효과
- 내비게이션 가드

## 다음 단계

[Angular 라우터로 라우팅 규칙을 정의하는 방법](/guide/routing/define-routes)을 알아보세요.

# 라우팅 규칙 정의하기

라우팅 규칙은 Angular 애플리케이션 내비게이션의 기본 구성 요소입니다.

## 라우팅 규칙이란?

<!--
In Angular, a **route** is an object that defines which component should render for a specific URL path or pattern, as well as additional configuration options about what happens when a user navigates to that URL.

Here is a basic example of a route:

```ts
import {AdminPage} from './app-admin';

const adminPage = {
  path: 'admin',
  component: AdminPage,
};
```

For this route, when a user visits the `/admin` path, the app will display the `AdminPage` component.
-->

Angular에서 **라우팅 규칙**은 특정 URL 경로나 패턴에 어떤 컴포넌트를 렌더링할지 정의하는 객체입니다.
사용자가 해당 URL로 이동했을 때 동작을 정하는 추가 설정도 포함합니다.

다음은 기본적인 라우팅 규칙 예제입니다.

```ts
import {AdminPage} from './app-admin';

const adminPage = {
  path: 'admin',
  component: AdminPage,
};
```

이 라우팅 규칙에서는 사용자가 `/admin` 경로에 방문하면 애플리케이션이 `AdminPage` 컴포넌트를 표시합니다.

### 애플리케이션의 라우팅 규칙 관리하기

<!--
Most projects define routes in a separate file that contains `routes` in the filename.

A collection of routes looks like this:

```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: If you generated a project with Angular CLI, your routes are defined in `src/app/app.routes.ts`.
-->

대부분의 프로젝트에서는 파일 이름에 `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,
  },
];
```

팁: Angular CLI로 생성한 프로젝트의 라우팅 규칙은 `src/app/app.routes.ts`에 정의되어 있습니다.

### 애플리케이션에 라우터 추가하기

<!--
When bootstrapping an Angular application without the Angular CLI, you can pass a configuration object that includes a `providers` array.

Inside of the `providers` array, you can add the Angular router to your application by adding a `provideRouter` function call with your routes.

```ts
import {ApplicationConfig} from '@angular/core';
import {provideRouter} from '@angular/router';

import {routes} from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    // ...
  ],
};
```
-->

Angular CLI를 사용하지 않고 Angular 애플리케이션을 부트스트랩할 때는 `providers` 배열이 있는 설정 객체를 전달할 수 있습니다.

이 `providers` 배열에 라우팅 규칙을 인자로 전달한 `provideRouter` 함수 호출을 추가하면 애플리케이션에 Angular 라우터가 추가됩니다.

```ts
import {ApplicationConfig} from '@angular/core';
import {provideRouter} from '@angular/router';

import {routes} from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    // ...
  ],
};
```

## 라우팅 규칙 URL 경로

### 정적 URL 경로

<!--
Static URL Paths refer to routes with predefined paths that don't change based on dynamic parameters. These are routes that match a `path` string exactly and have a fixed outcome.

Examples of this include:

- "/admin"
- "/blog"
- "/settings/account"
-->

정적 URL 경로는 동적 파라미터에 따라 바뀌지 않고 미리 정의된 경로를 사용하는 라우팅 규칙입니다.
`path` 문자열과 정확히 매칭되며 결과가 정해져 있습니다.

예를 들면 다음과 같습니다.

- "/admin"
- "/blog"
- "/settings/account"

### 라우팅 규칙 파라미터로 URL 경로 정의하기

<!--
Parameterized URLs allow you to define dynamic paths that allow multiple URLs to the same component while dynamically displaying data based on parameters in the URL.

You can define this type of pattern by adding parameters to your route’s `path` string and prefixing each parameter with the colon (`:`) character.

IMPORTANT: Parameters are distinct from information in the URL's [query string](https://en.wikipedia.org/wiki/Query_string).
Learn more about [query parameters in Angular in this guide](/guide/routing/read-route-state#query-parameters).

The following example displays a user profile component based on the user id passed in through the URL.

```ts
import {Routes} from '@angular/router';
import {UserProfile} from './user-profile/user-profile';

const routes: Routes = [{path: 'user/:id', component: UserProfile}];
```

In this example, URLs such as `/user/leeroy` and `/user/jenkins` render the `UserProfile` component. This component can then read the `id` parameter and use it to perform additional work, such as fetching data. See [reading route state guide](/guide/routing/read-route-state) for details on reading route parameters.

Valid route parameter names must start with a letter (a-z, A-Z) and can only contain:

- Letters (a-z, A-Z)
- Numbers (0-9)
- Underscore (\_)
- Hyphen (-)

You can also define paths with multiple parameters:

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

With this new path, users can visit `/user/leeroy/youtube` and `/user/leeroy/bluesky` and see respective social media feeds based on the parameter for the user leeroy.

See [Reading route state](/guide/routing/read-route-state) for details on reading route parameters.
-->

파라미터가 있는 URL을 사용하면 여러 URL에서 같은 컴포넌트를 사용하면서 URL 파라미터에 따라 데이터를 동적으로 표시하는 경로를 정의할 수 있습니다.

라우팅 규칙의 `path` 문자열에 파라미터를 추가하고 각 파라미터 앞에 콜론(`:`)을 붙이면 이런 패턴을 정의할 수 있습니다.

중요: 이 파라미터는 URL의 [쿼리 문자열](https://en.wikipedia.org/wiki/Query_string)에 있는 정보와 다릅니다.
자세한 내용은 [Angular 쿼리 파라미터](/guide/routing/read-route-state#query-parameters)를 참고하세요.

다음 예제는 URL로 전달한 사용자 ID를 기준으로 사용자 프로필 컴포넌트를 표시합니다.

```ts
import {Routes} from '@angular/router';
import {UserProfile} from './user-profile/user-profile';

const routes: Routes = [{path: 'user/:id', component: UserProfile}];
```

이 예제에서 `/user/leeroy`, `/user/jenkins` 같은 URL은 `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)를 참고하세요.

### 와일드카드

<!--
When you need to catch all routes for a specific path, the solution is a wildcard route which is defined with the double asterisk (`**`).

A common example is defining a Page Not Found component.

```ts
import {Routes} from '@angular/router';
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},
];
```

In this routes array, the app displays the `NotFound` component when the user visits any path outside of `home` and `user/:id`.

TIP: Wildcard routes are typically placed at the end of a routes array.
-->

특정 경로의 모든 라우팅 규칙을 처리해야 한다면 별표 두 개(`**`)로 정의하는 와일드카드 라우팅 규칙을 사용하세요.

페이지를 찾을 수 없을 때 표시할 컴포넌트를 정의하는 경우에 자주 사용합니다.

```ts
import {Routes} from '@angular/router';
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},
];
```

이 라우팅 규칙 배열에서는 사용자가 `home`, `user/:id` 외의 경로에 방문하면 `NotFound` 컴포넌트를 표시합니다.

팁: 와일드카드 라우팅 규칙은 일반적으로 라우팅 규칙 배열의 마지막에 배치합니다.

## Angular의 URL 매칭 방식

<!--
When you define routes, the order is important because Angular uses a first-match wins strategy. This means that once Angular matches a URL with a route `path`, it stops checking any further routes. As a result, always put more specific routes before less specific routes.

The following example shows routes defined from most-specific to least specific:

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

If a user visits `/users/new`, Angular router would go through the following steps:

1. Checks `''` - doesn't match
1. Checks `users/new` - matches! Stops here
1. Never reaches `users/:id` even though it could match
1. Never reaches `users`
1. Never reaches `**`
-->

Angular는 처음 매칭되는 라우팅 규칙을 선택하기 때문에 라우팅 규칙을 정의하는 순서가 중요합니다.
URL과 라우팅 규칙의 `path`가 매칭되면 그 뒤의 라우팅 규칙은 더 이상 확인하지 않습니다.
따라서 항상 구체적인 라우팅 규칙을 덜 구체적인 라우팅 규칙보다 먼저 배치하세요.

다음 예제는 가장 구체적인 라우팅 규칙부터 덜 구체적인 라우팅 규칙 순서로 정의합니다.

```ts
const routes: Routes = [
  {path: '', component: Home}, // 빈 경로
  {path: 'users/new', component: NewUser}, // 정적 경로이며 가장 구체적입니다.
  {path: 'users/:id', component: UserDetail}, // 동적 경로
  {path: 'users', component: Users}, // 정적 경로이며 덜 구체적입니다.
  {path: '**', component: NotFound}, // 와일드카드는 항상 마지막에 배치합니다.
];
```

사용자가 `/users/new`에 방문하면 Angular 라우터는 다음과 같이 처리합니다.

1. `''`를 확인합니다.
   일치하지 않습니다.
1. `users/new`를 확인합니다.
   일치하므로 여기서 멈춥니다.
1. `users/:id`도 일치할 수 있지만 확인하지 않습니다.
1. `users`는 확인하지 않습니다.
1. `**`는 확인하지 않습니다.

## 리다이렉트

<!--
You can define a route that redirects to another route instead of rendering a component:

```ts
import {Routes} from '@angular/router';
import {Blog} from './home/blog';

const routes: Routes = [
  {
    path: 'articles',
    redirectTo: '/blog',
  },
  {
    path: 'blog',
    component: Blog,
  },
];
```

If you modify or remove a route, some users may still click on out-of-date links or bookmarks to that route. You can add a redirect to direct those users to an appropriate alternative route instead of a "not found" page.
-->

컴포넌트를 렌더링하는 대신 다른 라우팅 규칙으로 리다이렉트하는 라우팅 규칙을 정의할 수 있습니다.

```ts
import {Routes} from '@angular/router';
import {Blog} from './home/blog';

const routes: Routes = [
  {
    path: 'articles',
    redirectTo: '/blog',
  },
  {
    path: 'blog',
    component: Blog,
  },
];
```

라우팅 규칙을 수정하거나 제거해도 사용자는 해당 라우팅 규칙의 이전 링크나 북마크를 클릭할 수 있습니다.
리다이렉트를 추가하면 "페이지를 찾을 수 없음" 화면 대신 적절한 대체 라우팅 규칙으로 안내할 수 있습니다.

## 페이지 제목

<!--
You can associate a **title** with each route. Angular automatically updates the [page title](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) when a route activates. Always define appropriate page titles for your application, as these titles are necessary to create an accessible experience.

```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',
  },
];
```

The page `title` property can be set dynamically to a resolver function using [`ResolveFn`](/api/router/ResolveFn).

```ts
const titleResolver: ResolveFn<string> = (route) => route.queryParams['id'];
const routes: Routes = [
  // ...
  {
    path: 'products',
    component: Products,
    title: titleResolver,
  },
];
```

Route titles can also be set via a service extending the [`TitleStrategy`](/api/router/TitleStrategy) abstract class. By default, Angular uses the [`DefaultTitleStrategy`](/api/router/DefaultTitleStrategy).
-->

각 라우팅 규칙에 **제목**을 지정할 수 있습니다.
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` 프로퍼티에는 [`ResolveFn`](/api/router/ResolveFn)을 사용하는 리졸버 함수를 지정해서 제목을 동적으로 설정할 수도 있습니다.

[`TitleStrategy`](/api/router/TitleStrategy) 추상 클래스를 상속하는 서비스로 라우팅 규칙 제목을 설정할 수도 있습니다.
Angular는 기본적으로 [`DefaultTitleStrategy`](/api/router/DefaultTitleStrategy)를 사용합니다.

### TitleStrategy로 페이지 제목 설정하기

<!--
For advanced scenarios where you need centralized control over how the document title is composed, implement a `TitleStrategy`.

`TitleStrategy` is a token you can provide to override the default title strategy used by Angular. You can supply a custom `TitleStrategy` to implement conventions such as adding an application suffix, formatting titles from breadcrumbs, or generating titles dynamically from route data.

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

To use the custom strategy, provide it with the `TitleStrategy` token at the application level:

```ts
import {provideRouter, TitleStrategy} from '@angular/router';
import {AppTitleStrategy} from './app-title.strategy';

export const appConfig = {
  providers: [provideRouter(routes), {provide: TitleStrategy, useClass: AppTitleStrategy}],
};
```
-->

문서 제목을 구성하는 방식을 한곳에서 제어해야 하는 복잡한 경우에는 `TitleStrategy`를 구현하세요.

`TitleStrategy`는 Angular의 기본 제목 전략을 교체할 때 제공하는 토큰입니다.
커스텀 `TitleStrategy`를 제공하면 제목 끝에 애플리케이션 이름을 붙이거나, 탐색 경로로 제목을 구성하거나, 라우팅 규칙 데이터를 사용해서 제목을 동적으로 생성하는 등의 규칙을 구현할 수 있습니다.

```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 {
    // 라우팅 규칙에 "Title"이 설정되어 있으면 PageTitle은 그 값과 같습니다.
    // 설정되어 있지 않으면 index.html의 "title"을 사용합니다.
    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}],
};
```

## 의존성 주입을 위한 라우팅 규칙 수준 프로바이더

<!--
Each route has a `providers` property that lets you provide dependencies to that route's content via [dependency injection](/guide/di).

Common scenarios where this can be helpful include applications that have different services based on whether the user is an admin or not.

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

In this code sample, the `admin` path contains a protected data property of `ADMIN_API_KEY` that is only available to children within its section. As a result, no other paths will be able to access the data provided via `ADMIN_API_KEY`.

See the [Dependency injection guide](/guide/di) for more information about providers and injection in Angular.
-->

각 라우팅 규칙의 `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},
    ],
  },
  // ... 다른 애플리케이션 라우팅 규칙에서는
  //     ADMIN_API_KEY나 AdminService에 접근할 수 없습니다.
];
```

이 코드에서 `admin` 경로에는 해당 영역의 자식에서만 사용할 수 있는 `ADMIN_API_KEY` 데이터 프로퍼티가 있습니다.
따라서 다른 경로에서는 `ADMIN_API_KEY`로 제공하는 데이터에 접근할 수 없습니다.

Angular의 프로바이더와 의존성 주입에 관한 자세한 내용은 [의존성 주입 가이드](/guide/di)를 참고하세요.

## 라우팅 규칙에 데이터 연결하기

<!--
Route data enables you to attach additional information to routes. You are able to configure how components behave based on this data.

There are two ways to work with route data: static data that remains constant, and dynamic data that can change based on runtime conditions.
-->

라우팅 규칙 데이터를 사용하면 라우팅 규칙에 추가 정보를 연결할 수 있습니다.
이 데이터에 따라 컴포넌트 동작을 설정할 수 있습니다.

라우팅 규칙 데이터에는 값이 바뀌지 않는 정적 데이터와 실행 중 조건에 따라 바뀔 수 있는 동적 데이터가 있습니다.

### 정적 데이터

<!--
You can associate arbitrary static data with a route via the `data` property in order to centralize things like route-specific metadata (e.g., analytics tracking, permissions, etc.):

```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'},
  },
];
```

In this code sample, the home and about page are configured with specific `analyticsId` which would then be used in their respective components for page tracking analytics.

You can read this static data by injecting the `ActivatedRoute`. See [Reading route state](/guide/routing/read-route-state) for details.
-->

`data` 프로퍼티로 라우팅 규칙에 원하는 정적 데이터를 연결할 수 있습니다.
라우팅 규칙별 메타데이터(예: 분석 추적, 권한 등)를 한곳에서 관리할 때 유용합니다.

```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)를 참고하세요.

### 리소스와 리졸버로 동적 데이터 제공하기

<!--
When you need to fetch data for a route, Angular Router supports reactive route resources as well as data resolvers:

- [Data fetching with resources](/guide/routing/data-fetching-with-resources): Fetch data reactively using Angular Signals `Resource` APIs.
- [Route data resolvers](/guide/routing/data-resolvers): Fetch data before route activation using resolver functions.
-->

라우팅 규칙에서 데이터를 가져와야 한다면 Angular 라우터가 제공하는 반응형 리소스나 데이터 리졸버를 사용할 수 있습니다.

- [리소스로 데이터 가져오기](/guide/routing/data-fetching-with-resources): Angular 시그널의 `Resource` API로 데이터를 반응형으로 가져옵니다.
- [라우팅 규칙 데이터 리졸버](/guide/routing/data-resolvers): 리졸버 함수로 라우팅 규칙을 활성화하기 전에 데이터를 가져옵니다.

## 중첩 라우팅 규칙

<!--
Nested routes, also known as child routes, are a common technique for managing more complex navigation routes where a component has a sub-view that changes based on the URL.

You can add child routes to any route definition with the `children` property:

```ts
const routes: Routes = [
  {
    path: 'product/:id',
    component: Product,
    children: [
      {
        path: 'info',
        component: ProductInfo,
      },
      {
        path: 'reviews',
        component: ProductReviews,
      },
    ],
  },
];
```

The above example defines a route for a product page that allows a user to change whether the product info or reviews are displayed based on the url.

The `children` property accepts an array of `Route` objects.

To display child routes, the parent component (`Product` in the example above) includes its own `<router-outlet>`.

```html
<!- Product ->
<article>
  <h1>Product {{ id }}</h1>
  <router-outlet />
</article>
```

After adding child routes to the configuration and adding a `<router-outlet>` to the component, navigation between URLs that match the child routes updates only the nested outlet.
-->

중첩 라우팅 규칙은 자식 라우팅 규칙이라고도 하며, 복잡한 내비게이션 경로를 관리할 때 자주 사용하는 방식입니다.
컴포넌트 안의 하위 뷰를 URL에 따라 변경할 수 있습니다.

라우팅 규칙 정의의 `children` 프로퍼티에 자식 라우팅 규칙을 추가할 수 있습니다.

위 예제는 URL에 따라 상품 정보와 리뷰 중 어느 것을 표시할지 변경할 수 있는 상품 페이지 라우팅 규칙을 정의합니다.

`children` 프로퍼티는 `Route` 객체 배열을 받습니다.

자식 라우팅 규칙을 표시하려면 부모 컴포넌트(위 예제의 `Product`)에 별도의 `<router-outlet>`을 포함해야 합니다.

```html

<article>
  <h1>Product {{ id }}</h1>
  <router-outlet />
</article>
```

설정에 자식 라우팅 규칙을 추가하고 컴포넌트에 `<router-outlet>`을 추가하면, 자식 라우팅 규칙과 매칭되는 URL 사이를 이동할 때 중첩된 아웃렛만 갱신됩니다.

## 다음 단계

<!--

-->

# 아웃렛으로 라우팅 규칙 표시하기

<!--
The `RouterOutlet` directive is a placeholder that marks the location where the router should render the component for the current URL.

```html
<app-header />
<!- Angular inserts your route content here ->
<router-outlet />
<app-footer />
```

```ts
import {Component} from '@angular/core';
import {RouterOutlet} from '@angular/router';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet],
  templateUrl: './app.html',
  styleUrl: './app.css',
})
export class App {}
```

In this example, if an application has the following routes defined:

```ts
import {Routes} from '@angular/router';
import {Home} from './home';
import {Products} from './products';

const routes: Routes = [
  {
    path: '',
    component: Home,
    title: 'Home Page',
  },
  {
    path: 'products',
    component: Products,
    title: 'Our Products',
  },
];
```

When a user visits `/products`, Angular renders the following:

```html
<app-header />
<app-products />
<app-footer />
```

If the user goes back to the home page, then Angular renders:

```html
<app-header />
<app-home />
<app-footer />
```

When displaying a route, the `<router-outlet>` element remains present in the DOM as a reference point for future navigations. Angular inserts routed content just after the outlet element as a sibling.

```html
<!- Contents of the component's template ->
<app-header />
<router-outlet />
<app-footer />
```

```html
<!- Content rendered on the page when the user visits /admin ->
<app-header />
<router-outlet />
<app-admin-page />
<app-footer />
```
-->

`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.html',
  styleUrl: './app.css',
})
export class App {}
```

이 예제의 애플리케이션에 다음 라우팅 규칙이 정의되어 있다고 가정해 보겠습니다.

```ts
import {Routes} from '@angular/router';
import {Home} from './home';
import {Products} from './products';

const routes: Routes = [
  {
    path: '',
    component: Home,
    title: 'Home Page',
  },
  {
    path: 'products',
    component: Products,
    title: 'Our Products',
  },
];
```

사용자가 `/products`에 방문하면 Angular는 다음과 같이 렌더링합니다.

```html
<app-header />
<app-products />
<app-footer />
```

사용자가 홈페이지로 돌아가면 다음과 같이 렌더링합니다.

```html
<app-header />
<app-home />
<app-footer />
```

라우팅 규칙을 표시할 때 `<router-outlet>` 엘리먼트는 이후 내비게이션의 기준점으로 DOM에 남아 있습니다.
Angular는 라우팅된 내용을 아웃렛 엘리먼트 바로 뒤에 형제 엘리먼트로 삽입합니다.

```html

<app-header />
<router-outlet />
<app-footer />
```

```html

<app-header />
<router-outlet />
<app-admin-page />
<app-footer />
```

## 자식 라우팅 규칙으로 라우팅 규칙 중첩하기

<!--
As your application grows more complex, you might want to create routes that are relative to a component other than your root component. This enables you to create experiences where only part of the application changes when the URL changes, as opposed to the users feeling like the entire page is refreshed.

These types of nested routes are called child routes. This means you're adding a second `<router-outlet>` to your app, because it is in addition to the `<router-outlet>` in AppComponent.

In this example, the `Settings` component will display the desired panel based on what the user selects. One of the unique things you’ll notice about child routes is that the component often has its own `<nav>` and `<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 />
```

A child route is like any other route, in that it needs both a `path` and a `component`. The one difference is that you place child routes in a children array within the parent route.

```ts
const routes: Routes = [
  {
    path: 'settings',
    component: Settings, // this is the component with the <router-outlet> in the template
    children: [
      {
        path: 'profile', // child route path
        component: Profile, // child route component that the router renders
      },
      {
        path: 'security',
        component: Security, // another child route component that the router renders
      },
    ],
  },
];
```

Once both the `routes` and `<router-outlet>` are configured correctly, your application is now using nested routes!
-->

애플리케이션이 복잡해지면 루트 컴포넌트가 아닌 다른 컴포넌트를 기준으로 라우팅 규칙을 구성하고 싶을 수 있습니다.
이렇게 하면 URL이 바뀔 때 전체 페이지가 새로 고쳐지는 느낌 대신 애플리케이션의 일부만 바뀌는 화면을 구성할 수 있습니다.

이런 중첩 라우팅 규칙을 자식 라우팅 규칙이라고 합니다.
AppComponent의 `<router-outlet>`에 더해 애플리케이션에 두 번째 `<router-outlet>`을 추가하는 방식입니다.

이 예제의 `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: Settings, // 템플릿에 <router-outlet>이 있는 컴포넌트입니다.
    children: [
      {
        path: 'profile', // 자식 라우팅 규칙 경로
        component: Profile, // 라우터가 렌더링하는 자식 라우팅 규칙 컴포넌트
      },
      {
        path: 'security',
        component: Security, // 라우터가 렌더링하는 다른 자식 라우팅 규칙 컴포넌트
      },
    ],
  },
];
```

`routes`와 `<router-outlet>`을 모두 올바르게 설정하면 애플리케이션에서 중첩 라우팅 규칙을 사용할 수 있습니다!

## 이름이 있는 아웃렛으로 보조 라우팅 규칙 구성하기

<!--
Pages may have multiple outlets— you can assign a name to each outlet to specify which content belongs to which outlet.

```html
<app-header />
<router-outlet />
<router-outlet name="read-more" />
<router-outlet name="additional-actions" />
<app-footer />
```

Each outlet must have a unique name. You can bind the name to a value. When the value changes, the outlet destroys its current component and renders the route for the new name, if one matches. By default, the name is `'primary'`.

Angular matches the outlet's name to the `outlet` property defined on each route:

```ts
{
  path: 'user/:id',
  component: UserDetails,
  outlet: 'additional-actions'
}
```
-->

페이지에는 여러 아웃렛을 둘 수 있습니다.
각 아웃렛에 이름을 지정하면 어떤 내용을 어느 아웃렛에 표시할지 결정할 수 있습니다.

```html
<app-header />
<router-outlet />
<router-outlet name="read-more" />
<router-outlet name="additional-actions" />
<app-footer />
```

각 아웃렛의 이름은 고유해야 합니다.
이름을 값에 바인딩할 수 있습니다.
값이 변경되면 아웃렛은 현재 컴포넌트를 제거하고, 새 이름과 일치하는 라우팅 규칙이 있으면 해당 화면을 렌더링합니다.
기본 이름은 `'primary'`입니다.

Angular는 아웃렛 이름을 각 라우팅 규칙에 정의한 `outlet` 프로퍼티와 매칭합니다.

```ts
{
  path: 'user/:id',
  component: UserDetails,
  outlet: 'additional-actions'
}
```

## 아웃렛 라이프사이클 이벤트

<!--
There are four lifecycle events that a router outlet can emit:

| Event        | Description                                                              |
| ------------ | ------------------------------------------------------------------------ |
| `activate`   | When a new component is instantiated                                     |
| `deactivate` | When a component is destroyed                                            |
| `attach`     | When the `RouteReuseStrategy` instructs the outlet to attach the subtree |
| `detach`     | When the `RouteReuseStrategy` instructs the outlet to detach the subtree |

You can add event listeners with the standard event binding syntax:

```html
<router-outlet
  (activate)="onActivate($event)"
  (deactivate)="onDeactivate($event)"
  (attach)="onAttach($event)"
  (detach)="onDetach($event)"
/>
```

Check out the [API docs for RouterOutlet](/api/router/RouterOutlet?tab=api) if you’d like to learn more.
-->

라우터 아웃렛은 네 가지 라이프사이클 이벤트를 발생시킬 수 있습니다.

| 이벤트       | 설명                                                                         |
| ------------ | ---------------------------------------------------------------------------- |
| `activate`   | 새 컴포넌트 인스턴스가 생성될 때 발생합니다.                                 |
| `deactivate` | 컴포넌트가 종료될 때 발생합니다.                                             |
| `attach`     | `RouteReuseStrategy`가 아웃렛에 하위 트리를 연결하도록 지시할 때 발생합니다. |
| `detach`     | `RouteReuseStrategy`가 아웃렛에 하위 트리를 분리하도록 지시할 때 발생합니다. |

일반적인 이벤트 바인딩 문법으로 이벤트 리스너를 추가할 수 있습니다.

```html
<router-outlet
  (activate)="onActivate($event)"
  (deactivate)="onDeactivate($event)"
  (attach)="onAttach($event)"
  (detach)="onDetach($event)"
/>
```

자세한 내용은 [RouterOutlet API 문서](/api/router/RouterOutlet?tab=api)를 참고하세요.

## 라우팅된 컴포넌트에 컨텍스트 데이터 전달하기

<!--
Passing contextual data to routed components often requires global state or complicated route configurations. To make this easier, each `RouterOutlet` supports a `routerOutletData` input. Routed components and their children can read this data as a signal using the `ROUTER_OUTLET_DATA` injection token, allowing outlet-specific configuration without modifying route definitions.

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

The routed component can inject the provided outlet data using `ROUTER_OUTLET_DATA`:

```typescript
import {Component, inject, Signal} from '@angular/core';
import {ROUTER_OUTLET_DATA} from '@angular/router';

@Component({
  selector: 'app-stats',
  template: `<p>Stats view (layout: {{ outletData().layout }})</p>`,
})
export class Stats {
  outletData = inject(ROUTER_OUTLET_DATA) as Signal<{layout: string}>;
}
```

When Angular activates the `Stats` in that outlet, it receives `{ layout: 'sidebar' }` as injected data.

NOTE: When the `routerOutletData` input is unset, the injected signal's value is `undefined` by default.

---
-->

라우팅된 컴포넌트에 컨텍스트 데이터를 전달하려면 전역 상태나 복잡한 라우팅 규칙 설정이 필요한 경우가 많습니다.
이를 간단하게 처리할 수 있도록 각 `RouterOutlet`은 `routerOutletData` 입력 프로퍼티를 지원합니다.
라우팅된 컴포넌트와 그 자식 컴포넌트에서는 `ROUTER_OUTLET_DATA` 의존성 주입 토큰으로 이 데이터를 시그널 형태로 읽을 수 있습니다.
따라서 라우팅 규칙 정의를 수정하지 않고 아웃렛별로 설정을 전달할 수 있습니다.

```typescript
import {Component} from '@angular/core';
import {RouterOutlet} from '@angular/router';

라우팅된 컴포넌트에서는 `ROUTER_OUTLET_DATA`로 아웃렛이 제공한 데이터를 주입받을 수 있습니다.

```typescript
import {Component, inject, Signal} from '@angular/core';
import {ROUTER_OUTLET_DATA} from '@angular/router';

Angular가 해당 아웃렛에서 `Stats`를 활성화하면 `{ layout: 'sidebar' }`가 데이터로 주입됩니다.

참고: `routerOutletData` 입력 프로퍼티를 지정하지 않으면 주입된 시그널의 기본값은 `undefined`입니다.

---

## 다음 단계

Angular 라우터로 [라우팅 규칙 사이를 이동하는 방법](/guide/routing/navigate-to-routes)을 알아보세요.

# 라우팅 규칙 사이 이동하기

RouterLink 디렉티브는 Angular에서 선언적으로 내비게이션을 구성하는 방식입니다.
표준 앵커 엘리먼트(`<a>`)를 Angular 라우팅 시스템과 자연스럽게 연결해서 사용할 수 있습니다.

## RouterLink 사용하기

<!--
Instead of using regular anchor elements `<a>` with an `href` attribute, you add a RouterLink directive with the appropriate path in order to leverage Angular routing.

```typescript
import {RouterLink} from '@angular/router';
import {Component} from '@angular/core';

@Component({
  template: `
    <nav>
      <a routerLink="/user-profile">User profile</a>
      <a routerLink="/settings">Settings</a>
    </nav>
  `,
  imports: [RouterLink],
  ...
})
export class App {}
```
-->

`href` 어트리뷰트가 있는 일반적인 앵커 엘리먼트 `<a>` 대신 RouterLink 디렉티브에 경로를 지정하면 Angular 라우팅을 사용할 수 있습니다.

```typescript
import {RouterLink} from '@angular/router';
import {Component} from '@angular/core';

### 절대 링크와 상대 링크 사용하기

<!--
**Relative URLs** in Angular routing allow you to define navigation paths relative to the current route's location. This is in contrast to **absolute URLs** which contain the full path with the protocol (e.g., `http://`) and the **root domain** (e.g., `google.com`).

```html
<!- Absolute URL ->
<a href="https://www.angular.dev/essentials">Angular Essentials Guide</a>

<!- Relative URL ->
<a href="/essentials">Angular Essentials Guide</a>
```

In this example, the first example contains the full path with the protocol (i.e., `https://`) and the root domain (i.e., `angular.dev`) explicitly defined for the essentials page. In contrast, the second example assumes the user is already on the correct root domain for `/essentials`.

Generally speaking, relative URLs are preferred as they are more maintainable across applications since they don’t need to know their absolute position within the routing hierarchy.
-->

Angular 라우팅의 **상대 URL**을 사용하면 현재 라우팅 규칙 위치를 기준으로 이동할 경로를 정의할 수 있습니다.
프로토콜(예: `http://`)과 **루트 도메인**(예: `google.com`)을 포함한 전체 경로를 지정하는 **절대 URL**과는 다릅니다.

```html

<a href="https://www.angular.dev/essentials">Angular Essentials Guide</a>

<a href="/essentials">Angular Essentials Guide</a>
```

첫 번째 예제는 핵심 가이드 페이지의 전체 경로에 프로토콜(`https://`)과 루트 도메인(`angular.dev`)을 명시합니다.
반면 두 번째 예제는 사용자가 이미 `/essentials`에 해당하는 올바른 루트 도메인에 있다고 가정합니다.

일반적으로 상대 URL을 권장합니다.
라우팅 계층에서 절대 위치를 알 필요가 없기 때문에 여러 애플리케이션에서 유지보수하기 쉽습니다.

### 상대 URL의 동작 방식

<!--
Angular routing has two syntaxes for defining relative URLs: strings and arrays.

```html
<!- Navigates user to /dashboard ->
<a routerLink="dashboard">Dashboard</a>
<a [routerLink]="['dashboard']">Dashboard</a>
```

HELPFUL: Passing a string is the most common way to define relative URLs.

When you need to define dynamic parameters in a relative URL, use the array syntax:

```html
<a [routerLink]="['user', currentUserId]">Current User</a>
```

In addition, Angular routing allows you to specify whether you want the path to be relative to the current URL or to the root domain based on whether the relative path is prefixed with a forward slash (`/`) or not.

For example, if the user is on `example.com/settings`, here is how different relative paths can be defined for various scenarios:

```html
<!- Navigates to /settings/notifications ->
<a routerLink="notifications">Notifications</a>
<a routerLink="/settings/notifications">Notifications</a>

<!- Navigates to /team/:teamId/user/:userId ->
<a routerLink="/team/123/user/456">User 456</a>
<a [routerLink]="['/team', teamId, 'user', userId]">Current User</a>
```
-->

Angular 라우팅에서는 문자열과 배열, 두 가지 문법으로 상대 URL을 정의할 수 있습니다.

```html

<a routerLink="dashboard">Dashboard</a>
<a [routerLink]="['dashboard']">Dashboard</a>
```

참고: 상대 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>
```

## 코드로 라우팅 규칙 사이 이동하기

`RouterLink`는 템플릿에서 선언적으로 내비게이션을 처리합니다.
로직, 사용자 동작, 애플리케이션 상태에 따라 이동해야 하는 경우에는 Angular가 제공하는 코드 기반 내비게이션을 사용할 수 있습니다.
`Router`를 주입하면 TypeScript 코드에서 동적으로 라우팅 규칙 사이를 이동하고, 파라미터를 전달하고, 내비게이션 동작을 제어할 수 있습니다.

### `router.navigate()`

<!--
You can use the `router.navigate()` method to programmatically navigate between routes by specifying a URL path array.

```typescript
import {Router} from '@angular/router';
import {Component, inject} from '@angular/core';

@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()` supports both simple and complex routing scenarios, allowing you to pass route parameters, [query parameters](/guide/routing/read-route-state#query-parameters), and control navigation behavior.

You can also build dynamic navigation paths relative to your component’s location in the routing tree using the `relativeTo` option.

```typescript
import {Router, ActivatedRoute} from '@angular/router';
import {Component, inject} from '@angular/core';

@Component({
  selector: 'app-user-detail',
  template: `
    <button (click)="navigateToEdit()">Edit User</button>
    <button (click)="navigateToParent()">Back to List</button>
  `,
})
export class UserDetail {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

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

navigateToList() {
    // Angular resolves the commands array as a single navigation path relative to the current route.
    // From: /users/123
    // Result: /users/list
    this.router.navigate(['..', 'list'], {relativeTo: this.route});
  }
}
```

When navigating multiple levels up, all `..` segments must be in the **first element** of the commands array. The router only parses `..` from the first command string — subsequent array elements are treated as literal path segments.

```typescript
{prefer}
// From: /team/123/users/456
// Result: /team/123/settings
this.router.navigate(['../../settings'], {relativeTo: this.route});
```

When using `relativeTo`, never prefix the first command with `/`. A leading `/` makes the navigation absolute and ignores `relativeTo` entirely.

```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.navigate()` 메서드에 URL 경로 배열을 지정하면 코드로 라우팅 규칙 사이를 이동할 수 있습니다.

```typescript
import {Router} from '@angular/router';
import {Component, inject} from '@angular/core';

@Component({
  selector: 'app-dashboard',
  template: ` <button (click)="navigateToProfile()">View Profile</button> `,
})
export class AppDashboard {
  private router = inject(Router);

navigateToProfile() {
    // 기본 내비게이션
    this.router.navigate(['/profile']);

// 라우팅 규칙 파라미터 사용
    this.router.navigate(['/users', userId]);

// 쿼리 파라미터 사용
    this.router.navigate(['/search'], {
      queryParams: {category: 'books', sort: 'price'},
    });

// 매트릭스 파라미터 사용
    this.router.navigate(['/products', {featured: true, onSale: true}]);
  }
}
```

`router.navigate()`는 간단한 라우팅부터 복잡한 라우팅까지 지원합니다.
라우팅 규칙 파라미터와 [쿼리 파라미터](/guide/routing/read-route-state#query-parameters)를 전달하고 내비게이션 동작을 제어할 수 있습니다.

`relativeTo` 옵션을 사용하면 라우팅 트리에서 컴포넌트가 있는 위치를 기준으로 동적 이동 경로를 구성할 수도 있습니다.

```typescript
import {Router, ActivatedRoute} from '@angular/router';
import {Component, inject} from '@angular/core';

// 형제 라우팅 규칙으로 이동합니다.
  navigateToEdit() {
    // 출발: /users/123
    // 도착:   /users/123/edit
    this.router.navigate(['edit'], {relativeTo: this.route});
  }

// 부모로 이동합니다.
  navigateToParent() {
    // 출발: /users/123
    // 도착:   /users
    this.router.navigate(['..'], {relativeTo: this.route});
  }

navigateToList() {
    // Angular는 명령 배열을 현재 라우팅 규칙 기준의 단일 이동 경로로 해석합니다.
    // 출발: /users/123
    // 결과: /users/list
    this.router.navigate(['..', 'list'], {relativeTo: this.route});
  }
}
```

여러 단계 위로 이동할 때는 모든 `..` 세그먼트를 명령 배열의 **첫 번째 항목**에 넣어야 합니다.
라우터는 첫 번째 명령 문자열에서만 `..`를 해석하며, 그 뒤의 배열 항목은 일반 경로 세그먼트로 처리합니다.

```typescript
{prefer}
// 출발: /team/123/users/456
// 결과: /team/123/settings
this.router.navigate(['../../settings'], {relativeTo: this.route});
```

`relativeTo`를 사용할 때는 첫 번째 명령 앞에 `/`를 붙이지 마세요.
맨 앞에 `/`가 있으면 절대 경로 내비게이션이 되며 `relativeTo`는 완전히 무시됩니다.

```typescript
{prefer}
// 출발: /team/123/users/456
// 결과: /team/123/users/456/edit
this.router.navigate(['edit'], {relativeTo: this.route});
```

```typescript
{avoid}
// 출발: /team/123/users/456
// 맨 앞에 '/'가 있으면 절대 경로로 이동하며 relativeTo는 무시됩니다.
// 결과: /edit
this.router.navigate(['/edit'], {relativeTo: this.route});
```

### `router.navigateByUrl()`

<!--
The `router.navigateByUrl()` method provides a direct way to programmatically navigate using URL path strings rather than array segments. This method is ideal when you have a full URL path and need to perform absolute navigation, especially when working with externally provided URLs or deep linking scenarios.

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

In the event you need to replace the current URL in history, `navigateByUrl` also accepts a configuration object that has a `replaceUrl` option.

```ts
// Replace current URL in history
router.navigateByUrl('/checkout', {
  replaceUrl: true,
});
```
-->

`router.navigateByUrl()` 메서드는 세그먼트 배열 대신 URL 경로 문자열로 직접 내비게이션을 실행합니다.
전체 URL 경로가 있고 절대 경로로 이동해야 할 때 적합하며, 특히 외부에서 받은 URL이나 딥 링크를 처리할 때 유용합니다.

```ts
// 기본 라우팅 규칙 내비게이션
router.navigateByUrl('/products');

// 중첩 라우팅 규칙으로 이동합니다.
router.navigateByUrl('/products/featured');

// 파라미터와 프래그먼트가 있는 전체 URL
router.navigateByUrl('/products/123?view=details#reviews');

// 쿼리 파라미터와 함께 이동합니다.
router.navigateByUrl('/search?category=books&sortBy=price');

// 매트릭스 파라미터 사용
router.navigateByUrl('/sales-awesome;isOffer=true;showModal=false');
```

히스토리의 현재 URL을 교체해야 한다면 `navigateByUrl`에 `replaceUrl` 옵션이 있는 설정 객체를 전달할 수도 있습니다.

```ts
// 히스토리의 현재 URL을 교체합니다.
router.navigateByUrl('/checkout', {
  replaceUrl: true,
});
```

### 주소 표시줄에 다른 URL 표시하기

<!--
You can pass a browserUrl option to navigateByUrl to display a different URL in the browser's address bar than the one used for route matching.

This is useful when you want to redirect a user to a different route—such as an error page—without changing the URL that the user originally tried to visit.

```ts
router.navigateByUrl('/not-found', {browserUrl: '/products/missing-item'});
```

Angular navigates to and renders the `/not-found` route, but the browser address bar shows `/products/missing-item`.

NOTE: `browserUrl` only affects what appears in the browser's address bar.
-->

navigateByUrl에 browserUrl 옵션을 전달하면 라우팅 규칙 매칭에 사용하는 URL과 다른 URL을 브라우저 주소 표시줄에 표시할 수 있습니다.

사용자가 처음 방문하려던 URL을 유지하면서 다른 라우팅 규칙(예: 오류 페이지)으로 리다이렉트하고 싶을 때 유용합니다.

```ts
router.navigateByUrl('/not-found', {browserUrl: '/products/missing-item'});
```

Angular는 `/not-found` 라우팅 규칙으로 이동해서 렌더링하지만, 브라우저 주소 표시줄에는 `/products/missing-item`이 표시됩니다.

참고: `browserUrl`은 브라우저 주소 표시줄에 표시되는 내용에만 영향을 줍니다.

## RouterLink로 브라우저 URL 조정하기

<!--
The `RouterLink` directive also supports a `browserUrl` input, which lets you control the URL displayed in the browser's address bar when a link is clicked, independently of the route Angular navigates to.

```html
<!- Navigates to /dashboard, but the address bar shows /home ->
<a [routerLink]="['/dashboard']" [browserUrl]="'/home'">Go to Dashboard</a>
```

You can also bind a `UrlTree` for more dynamic use cases:

```typescript
import {Component, inject} from '@angular/core';
import {Router, RouterLink, UrlTree} from '@angular/router';

@Component({
  template: `
    <a [routerLink]="['/products', product.id]" [browserUrl]="displayUrl">
      {{ product.name }}
    </a>
  `,
  imports: [RouterLink],
})
export class ProductList {
  private router = inject(Router);

product = {id: 42, name: 'Widget'};

// Create a UrlTree to display in the address bar
  displayUrl: UrlTree = this.router.createUrlTree(['/products', 'widget']);
}
```
-->

`RouterLink` 디렉티브도 `browserUrl` 입력 프로퍼티를 지원합니다.
따라서 링크를 클릭했을 때 Angular가 이동하는 라우팅 규칙과 별개로 브라우저 주소 표시줄에 표시할 URL을 제어할 수 있습니다.

```html

<a [routerLink]="['/dashboard']" [browserUrl]="'/home'">Go to Dashboard</a>
```

더 동적인 처리가 필요하면 `UrlTree`를 바인딩할 수도 있습니다.

```typescript
import {Component, inject} from '@angular/core';
import {Router, RouterLink, UrlTree} from '@angular/router';

product = {id: 42, name: 'Widget'};

// 주소 표시줄에 표시할 UrlTree를 생성합니다.
  displayUrl: UrlTree = this.router.createUrlTree(['/products', 'widget']);
}
```

## 다음 단계

[라우팅 규칙 상태를 읽는 방법](/guide/routing/read-route-state)을 알아보고, 변화와 컨텍스트에 반응하는 컴포넌트를 만들어 보세요.

# 라우팅 규칙 상태 읽기

Angular 라우터를 사용하면 라우팅 규칙에 연결된 정보를 읽고 활용해서 변화와 컨텍스트에 반응하는 컴포넌트를 만들 수 있습니다.

## ActivatedRoute로 현재 라우팅 규칙 정보 가져오기

<!--
`ActivatedRoute` is a service from `@angular/router` that provides all the information associated with the current route.

```typescript
import {Component, inject} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component({
  selector: 'app-product',
})
export class Product {
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    console.log(this.activatedRoute);
  }
}
```

The `ActivatedRoute` can provide different information about the route. Some common properties include:

| Property      | Details                                                                                                                           |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------- |
| `url`         | An `Observable` of the route paths, represented as an array of `UrlSegment` objects for each part of the route path.              |
| `data`        | An `Observable` that contains the `data` object provided for the route. Also contains any resolved values from the resolve guard. |
| `params`      | An `Observable` that contains the required and optional parameters specific to the route.                                         |
| `queryParams` | An `Observable` that contains the query parameters available to all routes.                                                       |
| `resources` | An optional record of `Resource` instances defined on the route (when `withRouterResources` is enabled). |

Check out the [`ActivatedRoute` API docs](/api/router/ActivatedRoute) for a complete list of what you can access with in the route.
-->

`ActivatedRoute`는 현재 라우팅 규칙에 연결된 모든 정보를 제공하는 `@angular/router`의 서비스입니다.

```typescript
import {Component, inject} 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`는 라우팅 규칙의 다양한 정보를 제공합니다.
자주 사용하는 프로퍼티는 다음과 같습니다.

라우팅 규칙에서 접근할 수 있는 전체 정보는 [`ActivatedRoute` API 문서](/api/router/ActivatedRoute)를 참고하세요.

## 라우팅 규칙 스냅샷 이해하기

<!--
Page navigations are events over time, and you can access the router state at a given time by retrieving a route snapshot.

Route snapshots contain essential information about the route, including its parameters, data, and child routes. In addition, snapshots are static and will not reflect future changes.

Here’s an example of how you’d access a route snapshot:

```typescript
import {Component, inject} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component(/* ... */)
export class UserProfile {
  readonly userId: string | null;
  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, // Array of UrlSegments matched by this route
      // Route parameters object: {id: '123'}
      params: snapshot.params,
      // Query parameters object: {role: 'admin', status: 'active'}
      queryParams: snapshot.queryParams, // Query parameters
    });
  }
}
```

Check out the [`ActivatedRoute` API docs](/api/router/ActivatedRoute) and [`ActivatedRouteSnapshot` API docs](/api/router/ActivatedRouteSnapshot) for a complete list of all properties you can access.
-->

페이지 내비게이션은 시간에 따라 발생하는 이벤트입니다.
라우팅 규칙 스냅샷을 가져오면 특정 시점의 라우터 상태에 접근할 수 있습니다.

라우팅 규칙 스냅샷에는 파라미터, 데이터, 자식 라우팅 규칙 등 라우팅 규칙의 핵심 정보가 포함됩니다.
스냅샷은 정적이므로 이후에 발생하는 변화는 반영하지 않습니다.

라우팅 규칙 스냅샷에는 다음과 같이 접근할 수 있습니다.

```typescript
import {Component, inject} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component(/* ... */)
export class UserProfile {
  readonly userId: string | null;
  private route = inject(ActivatedRoute);

constructor() {
    // 예제 URL: https://www.angular.dev/users/123?role=admin&status=active#contact

// 스냅샷에서 라우팅 규칙 파라미터에 접근합니다.
    this.userId = this.route.snapshot.paramMap.get('id');

// 여러 라우팅 규칙 정보에 접근합니다.
    const snapshot = this.route.snapshot;
    console.log({
      url: snapshot.url, // Array of UrlSegments matched by this route
      // 라우팅 규칙 파라미터 객체: {id: '123'}
      params: snapshot.params,
      // 쿼리 파라미터 객체: {role: 'admin', status: 'active'}
      queryParams: snapshot.queryParams, // 쿼리 파라미터
    });
  }
}
```

접근할 수 있는 전체 프로퍼티는 [`ActivatedRoute` API 문서](/api/router/ActivatedRoute)와 [`ActivatedRouteSnapshot` API 문서](/api/router/ActivatedRouteSnapshot)를 참고하세요.

## 라우팅 규칙 파라미터 읽기

라우팅 규칙에서는 라우팅 규칙 파라미터와 쿼리 파라미터를 사용할 수 있습니다.

### 라우팅 규칙 파라미터

<!--
Route parameters allow you to pass data to a component through the URL. This is useful when you want to display specific content based on an identifier in the URL, like a user ID or a product ID.

You can [define route parameters](/guide/routing/define-routes#define-url-paths-with-route-parameters) by prefixing the parameter name with a colon (`:`).

```typescript
import {Routes} from '@angular/router';
import {Product} from './product';

const routes: Routes = [{path: 'product/:id', component: Product}];
```

You can access parameters by subscribing to `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']);
    });
  }
}
```
-->

라우팅 규칙 파라미터는 URL을 통해 컴포넌트에 데이터를 전달하는 방식입니다.
사용자 ID나 상품 ID처럼 URL의 식별자를 기준으로 특정 내용을 표시할 때 유용합니다.

파라미터 이름 앞에 콜론(`:`)을 붙이면 [라우팅 규칙 파라미터를 정의](/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';

constructor() {
    // 라우팅 규칙 파라미터에 접근합니다.
    this.activatedRoute.params.subscribe((params) => {
      this.productId.set(params['id']);
    });
  }
}
```

### 쿼리 파라미터

<!--
[Query parameters](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) provide a flexible way to pass optional data through URLs without affecting the route structure. Unlike route parameters, query parameters can persist across navigation events and are perfect for handling filtering, sorting, pagination, and other stateful UI elements.

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

You can access query parameters with `route.queryParams`.

Here is an example of a `ProductList` that updates the query parameters that affect how it displays a list of products:

```typescript
import {Component, inject} from '@angular/core';
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>
      <!- Products list ->
    </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
    });
  }
}
```

In this example, users can use a select element to sort the product list by name or price. The associated change handler updates the URL’s query parameters, which in turn triggers a change event that can read the updated query parameters and update the product list.

For more information, check out the [official docs on QueryParamsHandling](/api/router/QueryParamsHandling).
-->

[쿼리 파라미터](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)는 라우팅 규칙 구조에 영향을 주지 않고 URL로 선택적인 데이터를 유연하게 전달하는 방식입니다.
라우팅 규칙 파라미터와 달리 내비게이션이 발생해도 유지할 수 있기 때문에 필터, 정렬, 페이지 나누기 등 상태가 있는 UI를 처리할 때 적합합니다.

```typescript
// 파라미터가 하나인 구조
// /products?category=electronics
router.navigate(['/products'], {
  queryParams: {category: 'electronics'},
});

// 여러 파라미터
// /products?category=electronics&sort=price&page=1
router.navigate(['/products'], {
  queryParams: {
    category: 'electronics',
    sort: 'price',
    page: 1,
  },
});
```

`route.queryParams`로 쿼리 파라미터에 접근할 수 있습니다.

다음 `ProductList` 예제는 상품 목록을 표시하는 방식에 영향을 주는 쿼리 파라미터를 갱신합니다.

```typescript
import {Component, inject} from '@angular/core';
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() {
    // 반응형으로 쿼리 파라미터에 접근합니다.
    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;
    // 새 쿼리 파라미터로 URL을 갱신합니다.
    this.router.navigate([], {
      queryParams: {sort},
      queryParamsHandling: 'merge', // 다른 쿼리 파라미터를 유지합니다.
    });
  }
}
```

이 예제에서 사용자는 select 엘리먼트로 상품 목록을 이름이나 가격순으로 정렬할 수 있습니다.
연결된 변경 핸들러가 URL의 쿼리 파라미터를 갱신하면 변경 이벤트가 발생합니다.
이 이벤트에서 갱신된 쿼리 파라미터를 읽어 상품 목록을 갱신할 수 있습니다.

자세한 내용은 [QueryParamsHandling 공식 문서](/api/router/QueryParamsHandling)를 참고하세요.

### 매트릭스 파라미터

<!--
Matrix parameters are optional parameters that belong to a specific URL segment, rather than applying to the entire route. Unlike query parameters which appear after a `?` and apply globally, matrix parameters use semicolons (`;`) and are scoped to individual path segments.

Matrix parameters are useful when you need to pass auxiliary data to a specific route segment without affecting the route definition or matching behavior. Like query parameters, they don't need to be defined in your route configuration.

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

**Using 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: As an alternative to using `ActivatedRoute`, matrix parameters are also bound to component inputs when using the `withComponentInputBinding`.
-->

매트릭스 파라미터는 전체 라우팅 규칙이 아닌 특정 URL 세그먼트에 속하는 선택적 파라미터입니다.
`?` 뒤에 위치하고 전체에 적용되는 쿼리 파라미터와 달리, 매트릭스 파라미터는 세미콜론(`;`)을 사용하며 개별 경로 세그먼트에만 적용됩니다.

라우팅 규칙 정의나 매칭 방식에 영향을 주지 않고 특정 라우팅 규칙 세그먼트에 보조 데이터를 전달할 때 유용합니다.
쿼리 파라미터처럼 라우팅 규칙 설정에 정의할 필요가 없습니다.

```ts
// URL 형식: /path;key=value
// 여러 파라미터: /path;key1=value1;key2=value2

// 매트릭스 파라미터와 함께 이동합니다.
this.router.navigate(['/awesome-products', {view: 'grid', filter: 'new'}]);
// 결과 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() {
    // params로 매트릭스 파라미터에 접근합니다.
    this.route.params.subscribe((params) => {
      const view = params['view']; // 예: 'grid'
      const filter = params['filter']; // 예: 'new'
    });
  }
}
```

참고: `ActivatedRoute` 대신 `withComponentInputBinding`을 사용하는 경우에는 매트릭스 파라미터도 컴포넌트 입력 프로퍼티에 바인딩됩니다.

## RouterLinkActive로 현재 활성 라우팅 규칙 감지하기

<!--
You can use the `RouterLinkActive` directive to dynamically style navigation elements based on the current active route. This is common in navigation elements to inform users what the active route is.

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

In this example, Angular Router will apply the `active-button` class to the correct anchor link and `ariaCurrentWhenActive` to `page` when the URL matches the corresponding `routerLink`.

If you need to add multiple classes onto the element, you can use either a space-separated string or an array:

```html
<!- Space-separated string syntax ->
<a routerLink="/user/bob" routerLinkActive="class1 class2">Bob</a>

<!- Array syntax ->
<a routerLink="/user/bob" [routerLinkActive]="['class1', 'class2']">Bob</a>
```

Setting `routerLinkActive` alone does not set `aria-current`. Set the `ariaCurrentWhenActive` input, as in the example above, so that visually impaired users (which may not perceive the different styling being applied) can also identify the active link.
-->

`RouterLinkActive` 디렉티브를 사용하면 현재 활성 라우팅 규칙에 따라 내비게이션 엘리먼트의 스타일을 동적으로 적용할 수 있습니다.
사용자에게 현재 활성 라우팅 규칙을 알리는 내비게이션 엘리먼트에서 자주 사용합니다.

이 예제에서 URL이 `routerLink`와 일치하면 Angular 라우터는 해당 앵커 링크에 `active-button` 클래스를 적용하고 `ariaCurrentWhenActive`를 `page`로 설정합니다.

엘리먼트에 여러 클래스를 추가하려면 공백으로 구분한 문자열이나 배열을 사용할 수 있습니다.

```html

<a routerLink="/user/bob" routerLinkActive="class1 class2">Bob</a>

<a routerLink="/user/bob" [routerLinkActive]="['class1', 'class2']">Bob</a>
```

`routerLinkActive`만 설정해도 `aria-current`가 설정되는 것은 아닙니다.
적용된 스타일 차이를 인지하기 어려운 시각 장애인 사용자도 활성 링크를 구별할 수 있도록, 앞의 예제처럼 `ariaCurrentWhenActive` 입력 프로퍼티를 설정하세요.

### 라우팅 규칙 매칭 전략

<!--
By default, `RouterLinkActive` considers any ancestors in the route a match.

```html
<a [routerLink]="['/user/jane']" routerLinkActive="active-link"> User </a>
<a [routerLink]="['/user/jane/role/admin']" routerLinkActive="active-link"> Role </a>
```

When the user visits `/user/jane/role/admin`, both links would have the `active-link` class.
-->

기본적으로 `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 적용하기

<!--
If you only want to apply the class on an exact match, you need to provide the `routerLinkActiveOptions` directive with a configuration object that contains the value `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>
```

If you want to be more precise in how a route is matched, it’s worth noting that `exact: true` is actually syntactic sugar for the full set of matching options:

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

For more information, check out the official docs for [isActiveMatchOptions](/api/router/IsActiveMatchOptions).
-->

정확하게 일치할 때만 클래스를 적용하려면 `routerLinkActiveOptions` 디렉티브에 `exact: true`를 포함한 설정 객체를 전달하세요.

라우팅 규칙 매칭 방식을 더 세밀하게 지정할 수도 있습니다.
`exact: true`는 실제로 다음 매칭 옵션 전체를 간단하게 표현한 문법입니다.

```typescript
// `exact: true`는 다음 설정과 같습니다.
{
  paths: 'exact',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'exact',
}

// `exact: false`는 다음 설정과 같습니다.
{
  paths: 'subset',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'subset',
}
```

자세한 내용은 [isActiveMatchOptions 공식 문서](/api/router/IsActiveMatchOptions)를 참고하세요.

### 상위 엘리먼트에 RouterLinkActive 적용하기

<!--
The RouterLinkActive directive can also be applied to an ancestor element in order to allow developers to style the elements as desired.

```html
<div routerLinkActive="active-link" [routerLinkActiveOptions]="{exact: true}">
  <a routerLink="/user/jim">Jim</a>
  <a routerLink="/user/bob">Bob</a>
</div>
```

For more information, check out the [API docs for RouterLinkActive](/api/router/RouterLinkActive).
-->

RouterLinkActive 디렉티브는 상위 엘리먼트에도 적용할 수 있습니다.
이 방식으로 원하는 엘리먼트에 스타일을 지정할 수 있습니다.

```html
<div routerLinkActive="active-link" [routerLinkActiveOptions]="{exact: true}">
  <a routerLink="/user/jim">Jim</a>
  <a routerLink="/user/bob">Bob</a>
</div>
```

자세한 내용은 [RouterLinkActive API 문서](/api/router/RouterLinkActive)를 참고하세요.

## URL 활성 여부 확인하기

<!--
The `isActive` function returns a computed signal that tracks whether a given URL is currently active in the router. The signal automatically updates as the router state changes.

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

`isActive` 함수는 특정 URL이 현재 라우터에서 활성 상태인지 추적하는 `computed()` 시그널을 반환합니다.
이 시그널은 라우터 상태가 바뀌면 자동으로 갱신됩니다.

```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 라우터를 사용할 때 자주 수행하는 다른 작업을 알아봅니다.

## 라우팅 규칙 정보 가져오기

<!--
Often, as a user navigates your application, you want to pass information from one component to another.
For example, consider an application that displays a shopping list of grocery items.
Each item in the list has a unique `id`.
To edit an item, users click an Edit button, which opens an `EditGroceryItem` component.
You want that component to retrieve the `id` for the grocery item so it can display the right information to the user.

Use a route to pass this type of information to your application components.
To do so, you use the `withComponentInputBinding` feature with `provideRouter` or the `bindToComponentInputs` option of `RouterModule.forRoot`.

To get information from a route:

<docs-workflow>

<docs-step title="Add `withComponentInputBinding`">

Add the `withComponentInputBinding` feature to the `provideRouter` method.

```ts
providers: [provideRouter(appRoutes, withComponentInputBinding())];
```

</docs-step>

<docs-step title="Add an `input` to the component">

Update the component to have an `input()` property matching the name of the parameter.

```ts
id = input.required<string>();
hero = computed(() => this.service.getHero(this.id()));
```

</docs-step>
<docs-step title="Optional: Use a default value">
The router assigns values to all inputs based on the current route when `withComponentInputBinding` is enabled.
The router assigns `undefined` if no route data matches the input key, such as when an optional query parameter is missing.
You should include `undefined` in the `input`'s type when there's a possibility that an input might not be matched by the route.

Provide a default value by either using the `transform` option on the input or managing a local state with a `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: You can bind all route data with key-value pairs to component inputs: route resources, static or resolved route data, path parameters, matrix parameters, and query parameters.

### Input binding priority

When multiple route sources define identical keys, the router resolves collisions in the following priority order (from highest to lowest):

1. **Route resources**: Values defined in the route's `resources` map. Blocking resources bind their unwrapped value (`resource.value()`), while non-blocking resources bind the `Resource` instance.
2. **Route data and resolvers**: Static data defined in `data` or values resolved via `resolve`.
3. **Path parameters and matrix parameters**: Parameters from the URL path (such as `:id`) and matrix parameters.
4. **Query parameters**: Parameters from the query string (such as `?id=123`).

For example, if a route has both a path parameter `:id` and a query parameter `?id=...`, the path parameter value is bound to the component's `id` input. If the route also defines a resource named `id`, the resource value takes precedence over both.
-->

사용자가 애플리케이션을 탐색하는 동안 한 컴포넌트에서 다른 컴포넌트로 정보를 전달해야 하는 경우가 많습니다.
예를 들어 식료품 쇼핑 목록을 표시하는 애플리케이션을 생각해 보겠습니다.
목록의 각 항목에는 고유한 `id`가 있습니다.
사용자가 항목의 Edit 버튼을 클릭하면 `EditGroceryItem` 컴포넌트가 열립니다.
이 컴포넌트는 사용자에게 올바른 정보를 표시할 수 있도록 해당 식료품의 `id`를 가져와야 합니다.

이런 정보는 라우팅 규칙으로 애플리케이션 컴포넌트에 전달할 수 있습니다.
`provideRouter`의 `withComponentInputBinding` 기능이나 `RouterModule.forRoot`의 `bindToComponentInputs` 옵션을 사용하세요.

라우팅 규칙 정보를 가져오는 방법은 다음과 같습니다.

<docs-workflow>

<docs-step title="`withComponentInputBinding` 추가하기">

`provideRouter` 메서드에 `withComponentInputBinding` 기능을 추가하세요.

```ts
providers: [provideRouter(appRoutes, withComponentInputBinding())];
```

</docs-step>

<docs-step title="컴포넌트에 `input` 추가하기">

파라미터 이름과 일치하는 `input()` 프로퍼티를 컴포넌트에 추가하세요.

```ts
id = input.required<string>();
hero = computed(() => this.service.getHero(this.id()));
```

</docs-step>
<a id="optional-use-a-default-value"></a>

<docs-step title="선택 사항: 기본값 사용하기">
`withComponentInputBinding`을 활성화하면 라우터가 현재 라우팅 규칙을 기준으로 모든 입력 프로퍼티에 값을 할당합니다.
선택적 쿼리 파라미터가 없는 경우처럼 입력 프로퍼티의 키와 매칭되는 라우팅 규칙 데이터가 없으면 `undefined`를 할당합니다.
입력 프로퍼티가 라우팅 규칙과 매칭되지 않을 가능성이 있다면 `input`의 타입에 `undefined`를 포함해야 합니다.

입력 프로퍼티의 `transform` 옵션을 사용하거나 `linkedSignal`로 로컬 상태를 관리하면 기본값을 제공할 수 있습니다.

```ts
id = input.required({
  transform: (maybeUndefined: string | undefined) => maybeUndefined ?? '0',
});
// 또는
id = input<string | undefined>();
internalId = linkedSignal(() => this.id() ?? getDefaultId());
```

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

참고: 키와 값 쌍으로 된 모든 라우팅 규칙 데이터를 컴포넌트 입력 프로퍼티에 바인딩할 수 있습니다.
라우팅 규칙 리소스, 정적 라우팅 규칙 데이터, 리졸버가 가져온 데이터, 경로 파라미터, 매트릭스 파라미터, 쿼리 파라미터가 모두 포함됩니다.

### 입력 프로퍼티 바인딩 우선순위

여러 라우팅 데이터 소스에서 같은 키를 정의하면 라우터는 다음 우선순위에 따라 충돌을 해결합니다. 위쪽 항목의 우선순위가 더 높습니다.

1. **라우팅 규칙 리소스**: 라우팅 규칙의 `resources` 맵에 정의된 값입니다. 블로킹 리소스는 내부 값(`resource.value()`)을 바인딩하고, 논블로킹 리소스는 `Resource` 인스턴스를 바인딩합니다.
2. **라우팅 규칙 데이터와 리졸버**: `data`에 정의한 정적 데이터 또는 `resolve`로 가져온 값입니다.
3. **경로 파라미터와 매트릭스 파라미터**: URL 경로의 파라미터(`:id` 등)와 매트릭스 파라미터입니다.
4. **쿼리 파라미터**: 쿼리 문자열의 파라미터(`?id=123` 등)입니다.

예를 들어 경로 파라미터 `:id`와 쿼리 파라미터 `?id=...`가 모두 있으면 경로 파라미터 값이 컴포넌트의 `id` 입력 프로퍼티에 바인딩됩니다. 라우팅 규칙에 `id`라는 리소스도 정의되어 있다면 리소스 값이 두 파라미터보다 우선합니다.

### 쿼리 파라미터 바인딩 비활성화하기

<!--
Use `ComponentInputBindingOptions` to disable query parameter binding if you manage query parameters separately:

```ts
provideRouter(appRoutes, withComponentInputBinding({queryParams: false}));
```
-->

쿼리 파라미터를 별도로 관리한다면 `ComponentInputBindingOptions`로 쿼리 파라미터 바인딩을 비활성화하세요.

```ts
provideRouter(appRoutes, withComponentInputBinding({queryParams: false}));
```

### 라우터 데이터에 없는 입력 프로퍼티의 동작 설정하기

<!--
By default, the router sets an input to `undefined` if it was not available in the router data during a navigation. This ensures that stale data is not retained.

If you want to avoid setting `undefined` for inputs that have _never_ been available in the router data for the active component instance, you can set the `unmatchedInputBehavior` option to `'undefinedIfStale'`:

```ts
provideRouter(appRoutes, withComponentInputBinding({unmatchedInputBehavior: 'undefinedIfStale'}));
```

When you combine `unmatchedInputBehavior: 'undefinedIfStale'` with `queryParams: false`, inputs retain their initial values unless they are explicitly provided by the router. The exception is matrix parameters: if a matrix parameter is provided in one navigation and removed in a subsequent one, the router will set the input to `undefined` to avoid retaining stale data.

```ts
provideRouter(
  appRoutes,
  withComponentInputBinding({
    queryParams: false,
    unmatchedInputBehavior: 'undefinedIfStale',
  }),
);
```
-->

기본적으로 내비게이션 중에 라우터 데이터에 없는 입력 프로퍼티는 `undefined`로 설정됩니다.
이전 데이터가 남아 있지 않도록 하는 동작입니다.

활성 컴포넌트 인스턴스의 라우터 데이터에 _한 번도_ 없었던 입력 프로퍼티에는 `undefined`를 설정하지 않으려면 `unmatchedInputBehavior` 옵션을 `'undefinedIfStale'`로 지정하세요.

```ts
provideRouter(appRoutes, withComponentInputBinding({unmatchedInputBehavior: 'undefinedIfStale'}));
```

`unmatchedInputBehavior: 'undefinedIfStale'`과 `queryParams: false`를 함께 사용하면 라우터가 명시적으로 제공하지 않은 입력 프로퍼티는 초기값을 유지합니다.
다만 매트릭스 파라미터는 예외입니다.
한 내비게이션에서 제공한 매트릭스 파라미터가 다음 내비게이션에서 제거되면, 이전 데이터를 유지하지 않도록 라우터가 입력 프로퍼티를 `undefined`로 설정합니다.

```ts
provideRouter(
  appRoutes,
  withComponentInputBinding({
    queryParams: false,
    unmatchedInputBehavior: 'undefinedIfStale',
  }),
);
```

### 부모 라우팅 규칙 데이터 상속하기

<!--
By default, child routes inherit parameters and data from parent routes (equivalent to `paramsInheritanceStrategy: 'always'`). This means you can access parent route info directly in child components.

If you need to restore the legacy behavior where parameters were only inherited from empty path routes, you can set `paramsInheritanceStrategy` to `'emptyOnly'`:

```ts
provideRouter(routes, withRouterConfig({paramsInheritanceStrategy: 'emptyOnly'}));
```

See [router configuration options](guide/routing/customizing-route-behavior#router-configuration-options) for details on other available settings.
-->

기본적으로 자식 라우팅 규칙은 부모 라우팅 규칙의 파라미터와 데이터를 상속합니다(`paramsInheritanceStrategy: 'always'`와 같습니다).
따라서 자식 컴포넌트에서 부모 라우팅 규칙 정보에 직접 접근할 수 있습니다.

빈 경로 라우팅 규칙에서만 파라미터를 상속하던 이전 동작이 필요하다면 `paramsInheritanceStrategy`를 `'emptyOnly'`로 지정하세요.

```ts
provideRouter(routes, withRouterConfig({paramsInheritanceStrategy: 'emptyOnly'}));
```

다른 설정의 자세한 내용은 [라우터 설정 옵션](guide/routing/customizing-route-behavior#router-configuration-options)을 참고하세요.

## 404 페이지 표시하기

<!--
To display a 404 page, set up a [wildcard route](guide/routing/define-routes#wildcards) with the `component` property set to the component you'd like to use for your 404 page as follows:

```ts
const routes: Routes = [
  {path: 'first-component', component: First},
  {path: 'second-component', component: Second},
  {path: '**', component: PageNotFound}, // Wildcard route for a 404 page
];
```

The last route with the `path` of `**` is a wildcard route.
The router selects this route if the requested URL doesn't match any of the paths earlier in the list and sends the user to the `PageNotFound`.
-->

404 페이지를 표시하려면 [와일드카드 라우팅 규칙](guide/routing/define-routes#wildcards)을 설정하고 `component` 프로퍼티에 404 페이지용 컴포넌트를 지정하세요.

```ts
const routes: Routes = [
  {path: 'first-component', component: First},
  {path: 'second-component', component: Second},
  {path: '**', component: PageNotFound}, // 404 페이지를 위한 와일드카드 라우팅 규칙
];
```

마지막의 `path`가 `**`인 라우팅 규칙이 와일드카드 라우팅 규칙입니다.
요청한 URL이 목록의 앞쪽 경로들과 매칭되지 않으면 라우터는 이 라우팅 규칙을 선택해서 사용자를 `PageNotFound`로 보냅니다.

## 링크 파라미터 배열

<!--
A link parameters array holds the following ingredients for router navigation:

- The path of the route to the destination component
- Required and optional route parameters that go into the route URL

Bind the `RouterLink` directive to such an array like this:

```html
<a [routerLink]="['/heroes']">Heroes</a>
```

The following is a two-element array when specifying a route parameter:

```html
<a [routerLink]="['/hero', hero.id]">
  <span class="badge">{{ hero.id }}</span
  >{{ hero.name }}
</a>
```

Provide optional route parameters in an object, as in `{ foo: 'foo' }`:

```html
<a [routerLink]="['/crisis-center', {foo: 'foo'}]">Crisis Center</a>
```

This syntax passes matrix parameters, which are optional parameters associated with a specific URL segment. Learn more about [matrix parameters](/guide/routing/read-route-state#matrix-parameters).

These three examples cover the needs of an application with one level of routing.
However, with a child router, such as in the crisis center, you create new link array possibilities.

The following minimal `RouterLink` example builds upon a specified default child route for the crisis center.

```html
<a [routerLink]="['/crisis-center']">Crisis Center</a>
```

Review the following:

- The first item in the array identifies the parent route $`/crisis-center`$
- There are no parameters for this parent route
- There is no default for the child route so you need to pick one
- You're navigating to the `CrisisList`, whose route path is `/`, but you don't need to explicitly add the slash

Consider the following router link that navigates from the root of the application down to the Dragon Crisis:

```html
<a [routerLink]="['/crisis-center', 1]">Dragon Crisis</a>
```

- The first item in the array identifies the parent route $`/crisis-center`$
- There are no parameters for this parent route
- The second item identifies the child route details about a particular crisis $`/:id`$
- The details child route requires an `id` route parameter
- You added the `id` of the Dragon Crisis as the second item in the array $`1`$
- The resulting path is `/crisis-center/1`

You could also redefine the `App` template with Crisis Center routes exclusively:

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

In summary, you can write applications with one, two or more levels of routing.
The link parameters array affords the flexibility to represent any routing depth and any legal sequence of route paths, $required$ router parameters, and $optional$ route parameter objects.
-->

링크 파라미터 배열에는 라우터 내비게이션을 위한 다음 정보가 들어 있습니다.

- 목적지 컴포넌트의 라우팅 규칙 경로
- 라우팅 규칙 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>
```

이 문법은 특정 URL 세그먼트에 연결된 선택적 파라미터인 매트릭스 파라미터를 전달합니다.
[매트릭스 파라미터](/guide/routing/read-route-state#matrix-parameters)를 더 알아보세요.

이 세 가지 예제로 라우팅 계층이 하나인 애플리케이션을 구성할 수 있습니다.
하지만 위기 센터 예제처럼 자식 라우터가 있다면 링크 배열을 더 다양하게 구성할 수 있습니다.

다음의 간단한 `RouterLink` 예제는 위기 센터에 지정된 기본 자식 라우팅 규칙을 기반으로 합니다.

```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` 라우팅 규칙 파라미터가 필요합니다.
- Dragon Crisis의 `id`를 배열의 두 번째 항목$`1`$으로 추가했습니다.
- 결과 경로는 `/crisis-center/1`입니다.

위기 센터 라우팅 규칙만 사용하도록 `App` 템플릿을 다시 정의할 수도 있습니다.

라우팅 계층이 하나, 둘 또는 그 이상인 애플리케이션을 작성할 수 있습니다.
링크 파라미터 배열을 사용하면 어떤 깊이의 라우팅이든 표현할 수 있습니다.
라우팅 규칙 경로, $필수$ 라우터 파라미터, $선택적$ 라우팅 규칙 파라미터 객체를 유효한 순서로 유연하게 조합할 수 있습니다.

## `LocationStrategy`와 브라우저 URL 형식

<!--
When the router navigates to a new component view, it updates the browser's location and history with a URL for that view.

Modern HTML5 browsers support [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'), a technique that changes a browser's location and history without triggering a server page request.
The router can compose a "natural" URL that is indistinguishable from one that would otherwise require a page load.

Here's the Crisis Center URL in this "HTML5 pushState" style:

```text
localhost:3002/crisis-center
```

Older browsers send page requests to the server when the location URL changes unless the change occurs after a "#" $called the "hash"$.
Routers can take advantage of this exception by composing in-application route URLs with hashes.
Here's a "hash URL" that routes to the Crisis Center.

```text
localhost:3002/src/#/crisis-center
```

The router supports both styles with two `LocationStrategy` providers:

The `RouterModule.forRoot()` function sets the `LocationStrategy` to the `PathLocationStrategy`, which makes it the default strategy.
You also have the option of switching to the `HashLocationStrategy` with an override during the bootstrapping process.

HELPFUL: For more information on providers and the bootstrap process, see [Dependency Injection](guide/di/defining-dependency-providers).
-->

라우터가 새 컴포넌트 뷰로 이동하면 해당 뷰의 URL로 브라우저 위치와 히스토리를 갱신합니다.

최신 HTML5 브라우저는 서버에 페이지를 요청하지 않고 브라우저 위치와 히스토리를 변경하는 [history.pushState](https://developer.mozilla.org/docs/Web/API/History_API/Working_with_the_History_API#adding_and_modifying_history_entries 'HTML5 브라우저 히스토리 push-state')를 지원합니다.
라우터는 일반적으로 페이지를 로드할 때 사용하는 URL과 구별되지 않는 "자연스러운" URL을 구성할 수 있습니다.

"HTML5 pushState" 형식의 위기 센터 URL은 다음과 같습니다.

```text
localhost:3002/crisis-center
```

이전 브라우저는 위치 URL이 바뀌면 서버에 페이지를 요청합니다.
다만 "해시"라고 부르는 "#" 뒤의 내용만 바뀌면 요청하지 않습니다.
라우터는 이 특성을 활용해서 애플리케이션 내부 라우팅 규칙 URL을 해시로 구성할 수 있습니다.
다음은 위기 센터로 이동하는 "해시 URL"입니다.

```text
localhost:3002/src/#/crisis-center
```

라우터는 두 가지 `LocationStrategy` 프로바이더로 두 형식을 모두 지원합니다.

`RouterModule.forRoot()` 함수는 `LocationStrategy`를 `PathLocationStrategy`로 설정하므로 이 방식이 기본 전략입니다.
부트스트랩 과정에서 이 설정을 재정의해서 `HashLocationStrategy`로 변경할 수도 있습니다.

참고: 프로바이더와 부트스트랩 과정의 자세한 내용은 [의존성 주입](guide/di/defining-dependency-providers)을 참고하세요.

# 커스텀 라우팅 규칙 매칭 만들기

<!--
The Angular Router supports a powerful matching strategy that you can use to help users navigate your application.
This matching strategy supports static routes, variable routes with parameters, wildcard routes, and so on.
Also, build your own custom pattern matching for situations in which the URLs are more complicated.

In this tutorial, you'll build a custom route matcher using Angular's `UrlMatcher`.
This matcher looks for an X (formerly Twitter) handle in the URL.
-->

Angular 라우터는 사용자가 애플리케이션을 탐색할 수 있도록 강력한 매칭 전략을 지원합니다.
이 전략은 정적 라우팅 규칙, 파라미터가 있는 가변 라우팅 규칙, 와일드카드 라우팅 규칙 등을 지원합니다.
URL이 더 복잡한 경우에는 커스텀 패턴 매칭을 직접 만들 수도 있습니다.

이 튜토리얼에서는 Angular의 `UrlMatcher`로 커스텀 라우팅 규칙 매처를 만듭니다.
이 매처는 URL에서 X(이전 이름 Twitter) 사용자 이름을 찾습니다.

## 목표

Angular의 `UrlMatcher`를 구현해서 커스텀 라우팅 규칙 매처를 만듭니다.

## 예제 애플리케이션 생성하기

<!--
Using the Angular CLI, create a new application, _angular-custom-route-match_.
In addition to the default Angular application framework, you will also create a _profile_ component.

1. Create a new Angular project, _angular-custom-route-match_.

```shell
ng new angular-custom-route-match
   ```

When prompted with `Would you like to add Angular routing?`, select `Y`.

When prompted with `Which stylesheet format would you like to use?`, select `CSS`.

After a few moments, a new project, `angular-custom-route-match`, is ready.

1. From your terminal, navigate to the `angular-custom-route-match` directory.
1. Create a component, _profile_.

```shell
ng generate component profile
   ```

1. In your code editor, locate the file, `profile.html` and replace the placeholder content with the following HTML.

<docs-code header="profile.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/profile/profile.html"/>

1. In your code editor, locate the file, `app.html` and replace the placeholder content with the following HTML.

<docs-code header="app.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.html"/>
-->

Angular CLI로 *angular-custom-route-match*라는 새 애플리케이션을 생성하세요.
기본 Angular 애플리케이션 구조와 함께 _profile_ 컴포넌트도 생성합니다.

1. *angular-custom-route-match*라는 새 Angular 프로젝트를 생성하세요.

```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.html` 파일을 열고 기본 내용을 다음 HTML로 교체하세요.

<docs-code header="profile.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/profile/profile.html"/>

1. 코드 편집기에서 `app.html` 파일을 열고 기본 내용을 다음 HTML로 교체하세요.

<docs-code header="app.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.html"/>

## 애플리케이션의 라우팅 규칙 설정하기

<!--
With your application framework in place, you next need to add routing capabilities to the `app.config.ts` file.
As a part of this process, you will create a custom URL matcher that looks for an X handle in the URL.
This handle is identified by a preceding `@` symbol.

1. In your code editor, open your `app.config.ts` file.
1. Add an `import` statement for Angular's `provideRouter` and `withComponentInputBinding` as well as the application routes.

```ts
import {provideRouter, withComponentInputBinding} from '@angular/router';

import {routes} from './app.routes';
   ```

1. In the providers array, add a `provideRouter(routes, withComponentInputBinding())` statement.

1. Define the custom route matcher by adding the following code to the application routes.

<docs-code header="app.routes.ts" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.routes.ts" region="matcher"/>

This custom matcher is a function that performs the following tasks:

- The matcher verifies that the array contains only one segment
- The matcher employs a regular expression to ensure that the format of the username is a match
- If there is a match, the function returns the entire URL, defining a `username` route parameter as a substring of the path
- If there isn't a match, the function returns null and the router continues to look for other routes that match the URL

HELPFUL: A custom URL matcher behaves like any other route definition. Define child routes or lazy loaded routes as you would with any other route.
-->

애플리케이션의 기본 구조를 준비했으면 `app.config.ts` 파일에 라우팅 기능을 추가하세요.
이 과정에서 URL의 X 사용자 이름을 찾는 커스텀 URL 매처를 만듭니다.
사용자 이름은 앞에 붙은 `@` 기호로 구별합니다.

1. 코드 편집기에서 `app.config.ts` 파일을 여세요.
1. Angular의 `provideRouter`, `withComponentInputBinding`, 애플리케이션 라우팅 규칙을 불러오는 `import` 구문을 추가하세요.

```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과 매칭되는 다른 라우팅 규칙을 계속 찾습니다.

참고: 커스텀 URL 매처도 다른 라우팅 규칙 정의와 마찬가지로 동작합니다.
일반 라우팅 규칙처럼 자식 라우팅 규칙이나 지연 로딩 라우팅 규칙을 정의할 수 있습니다.

## 라우팅 규칙 파라미터 읽기

<!--
With the custom matcher in place, you can now bind the route parameter in the `profile` component.

In your code editor, open your `profile.ts` file and create an `input` matching the `username` parameter.
We added the `withComponentInputBinding` feature earlier
in `provideRouter`. This allows the `Router` to bind information directly to the route components.

```ts
username = input.required<string>();
```
-->

커스텀 매처를 준비했으면 `profile` 컴포넌트에 라우팅 규칙 파라미터를 바인딩할 수 있습니다.

코드 편집기에서 `profile.ts` 파일을 열고 `username` 파라미터와 일치하는 `input`을 생성하세요.
앞에서 `provideRouter`에 `withComponentInputBinding` 기능을 추가했습니다.
이 기능을 사용하면 `Router`가 라우팅 규칙 컴포넌트에 정보를 직접 바인딩할 수 있습니다.

```ts
username = input.required<string>();
```

## 커스텀 URL 매처 테스트하기

<!--
With your code in place, you can now test your custom URL matcher.

1. From a terminal window, run the `ng serve` command.

```shell
ng serve
   ```

1. Open a browser to `http://localhost:4200`.

You should see a single web page, consisting of a sentence that reads `Navigate to my profile`.

1. Click the **my profile** hyperlink.

A new sentence, reading `Hello, Angular!` appears on the page.
-->

코드가 준비되었으면 커스텀 URL 매처를 테스트할 수 있습니다.

1. 터미널에서 `ng serve` 명령을 실행하세요.

```shell
ng serve
   ```

1. 브라우저에서 `http://localhost:4200`을 여세요.

`Navigate to my profile`이라는 문장이 있는 웹 페이지가 표시됩니다.

1. **my profile** 링크를 클릭하세요.

페이지에 `Hello, Angular!`라는 새 문장이 표시됩니다.

## 다음 단계

Angular 라우터의 패턴 매칭을 사용하면 애플리케이션의 동적 URL을 유연하게 처리할 수 있습니다.
Angular 라우터가 더 궁금하면 다음 내용을 참고하세요.
참고: 이 문서는 [Brandon Roberts](https://x.com/brandontroberts)의 [Custom Route Matching with the Angular Router](https://medium.com/@brandontroberts/custom-route-matching-with-the-angular-router-fbdd48665483)를 기반으로 작성했습니다.

# 서버 렌더링과 하이브리드 렌더링

Angular 애플리케이션은 기본적으로 클라이언트 사이드 렌더링(CSR) 방식으로 제공됩니다.
이 방식은 초기 전송 데이터를 가볍게 만들지만, 사용자 기기에서 대부분의 연산을 수행하므로 로드 시간이 길어지고 성능 지표가 나빠지며 더 많은 리소스를 요구할 수 있습니다.
따라서 많은 애플리케이션은 서버 사이드 렌더링(SSR)을 하이브리드 렌더링 전략에 통합해서 성능을 크게 개선합니다.

## 하이브리드 렌더링이 무엇인가요?

하이브리드 렌더링을 사용하면 서버 사이드 렌더링(SSR), 사전 렌더링("정적 사이트 생성" 또는 SSG), 클라이언트 사이드 렌더링(CSR)의 장점을 활용해서 Angular 애플리케이션을 최적화할 수 있습니다.
애플리케이션의 각 부분을 어떻게 렌더링할지 세밀하게 제어해서 사용자에게 최상의 경험을 제공할 수 있습니다.

## 하이브리드 렌더링 설정하기

<!--
You can create a **new** project with hybrid rendering by using the server-side rendering flag (i.e., `--ssr`) with the Angular CLI `ng new` command:

```shell
ng new --ssr
```

You can also enable hybrid rendering by adding server-side rendering to an existing project with the `ng add` command:

```shell
ng add @angular/ssr
```

NOTE: By default, Angular prerenders your entire application and generates a server file. To disable this and create a fully static app, set `outputMode` to `static`. To enable SSR, update the server routes to use `RenderMode.Server`. For more details, see [`Server routing`](#server-routing) and [`Generate a fully static application`](#generate-a-fully-static-application).
-->

Angular CLI의 `ng new` 명령에 서버 사이드 렌더링 플래그인 `--ssr`을 지정하면 하이브리드 렌더링을 사용하는 **새** 프로젝트를 만들 수 있습니다:

```shell
ng new --ssr
```

`ng add` 명령으로 기존 프로젝트에 서버 사이드 렌더링을 추가해서 하이브리드 렌더링을 활성화할 수도 있습니다:

```shell
ng add @angular/ssr
```

참고: 기본적으로 Angular는 애플리케이션 전체를 사전 렌더링하고 서버 파일을 생성합니다.
이 동작을 끄고 완전한 정적 애플리케이션을 만들려면 `outputMode`를 `static`으로 설정하세요.
SSR을 활성화하려면 서버 라우팅 규칙이 `RenderMode.Server`를 사용하도록 수정하세요.
자세한 내용은 [`서버 라우팅`](#server-routing)과 [`완전한 정적 애플리케이션 생성하기`](#generate-a-fully-static-application)를 참고하세요.

## 서버 라우팅

### 서버 라우팅 규칙 설정하기

<!--
You can create a server route config by declaring an array of [`ServerRoute`](api/ssr/ServerRoute 'API reference') objects. This configuration typically lives in a file named `app.routes.server.ts`.

```typescript
{header: "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,
  },
];
```

You can add this config to your application with [`provideServerRendering`](api/ssr/provideServerRendering 'API reference') using the [`withRoutes`](api/ssr/withRoutes 'API reference') function:

```typescript
{header: "app.config.server.ts"}
import {provideServerRendering, withRoutes} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {serverRoutes} from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes)),
    // ... other providers ...
  ],
};
```

When using the [App shell pattern](ecosystem/service-workers/app-shell), you must specify the component to be used as the app shell for client-side rendered routes. To do this, use the [`withAppShell`](api/ssr/withAppShell 'API reference') feature:

```typescript
import {provideServerRendering, withRoutes, withAppShell} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {AppShell} from './app-shell';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes), withAppShell(AppShell)),
    // ... other providers ...
  ],
};
```
-->

[`ServerRoute`](api/ssr/ServerRoute 'API 레퍼런스') 객체의 배열을 선언해서 서버 라우팅 규칙을 설정할 수 있습니다.
이 설정은 일반적으로 `app.routes.server.ts` 파일에 작성합니다.

```typescript
{header: "app.routes.server.ts"}
import {RenderMode, ServerRoute} from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: '', // "/" 라우트는 클라이언트에서 렌더링합니다(CSR).
    renderMode: RenderMode.Client,
  },
  {
    path: 'about', // 정적 페이지이므로 사전 렌더링합니다(SSG).
    renderMode: RenderMode.Prerender,
  },
  {
    path: 'profile', // 사용자별 데이터가 필요한 페이지이므로 SSR을 사용합니다.
    renderMode: RenderMode.Server,
  },
  {
    path: '**', // 다른 모든 라우트는 서버에서 렌더링합니다(SSR).
    renderMode: RenderMode.Server,
  },
];
```

[`withRoutes`](api/ssr/withRoutes 'API 레퍼런스') 함수를 [`provideServerRendering`](api/ssr/provideServerRendering 'API 레퍼런스')과 함께 사용해서 애플리케이션에 이 설정을 추가할 수 있습니다:

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes)),
    // ... 다른 프로바이더 ...
  ],
};
```

[앱 기본 구조 패턴](ecosystem/service-workers/app-shell)을 사용한다면 클라이언트에서 렌더링하는 라우팅 규칙의 앱 기본 구조로 사용할 컴포넌트를 지정해야 합니다.
[`withAppShell`](api/ssr/withAppShell 'API 레퍼런스') 기능으로 지정하세요:

```typescript
import {provideServerRendering, withRoutes, withAppShell} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {AppShell} from './app-shell';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes), withAppShell(AppShell)),
    // ... 다른 프로바이더 ...
  ],
};
```

### 렌더링 모드

<!--
The server routing configuration lets you specify how each route in your application should render by setting a [`RenderMode`](api/ssr/RenderMode 'API reference'):

| Rendering mode      | Description                                                                                                 |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Server (SSR)**    | Renders the application on the server for each request, sending a fully populated HTML page to the browser. |
| **Client (CSR)**    | Renders the application in the browser. This is the default Angular behavior.                               |
| **Prerender (SSG)** | Prerenders the application at build time, generating static HTML files for each route.                      |
-->

서버 라우팅 설정에서 [`RenderMode`](api/ssr/RenderMode 'API 레퍼런스')를 지정하면 애플리케이션의 각 라우팅 규칙을 어떻게 렌더링할지 정할 수 있습니다:

| 렌더링 모드         | 설명                                                                                            |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| **Server (SSR)**    | 요청마다 서버에서 애플리케이션을 렌더링하고, 콘텐츠가 완성된 HTML 페이지를 브라우저로 보냅니다. |
| **Client (CSR)**    | 브라우저에서 애플리케이션을 렌더링합니다. Angular의 기본 동작입니다.                            |
| **Prerender (SSG)** | 빌드 시점에 애플리케이션을 사전 렌더링해서 각 라우팅 규칙의 정적 HTML 파일을 생성합니다.             |

#### 렌더링 모드 선택하기

렌더링 모드마다 장단점이 다릅니다.
애플리케이션의 구체적인 요구 사항에 맞춰 렌더링 모드를 선택할 수 있습니다.

##### 클라이언트 사이드 렌더링(CSR)

<!--
Client-side rendering has the simplest development model, as you can write code that assumes it always runs in a web browser. This lets you use a wide range of client-side libraries that also assume they run in a browser.

Client-side rendering generally has worse performance than other rendering modes, as it must download, parse, and execute your page's JavaScript before the user can see any rendered content. If your page fetches more data from the server as it renders, users also have to wait for those additional requests before they can view the complete content.

If your page is indexed by search crawlers, client-side rendering may negatively affect search engine optimization (SEO), as search crawlers have limits to how much JavaScript they execute when indexing a page.

When client-side rendering, the server does not need to do any work to render a page beyond serving static JavaScript assets. You may consider this factor if server cost is a concern.

Applications that support installable, offline experiences with [service workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) can rely on client-side rendering without needing to communicate with a server.
-->

클라이언트 사이드 렌더링은 코드가 항상 웹 브라우저에서 실행된다고 가정할 수 있으므로 개발 모델이 가장 단순합니다.
브라우저 실행을 전제로 하는 다양한 클라이언트 라이브러리도 사용할 수 있습니다.

클라이언트 사이드 렌더링은 사용자가 렌더링된 콘텐츠를 보려면 먼저 페이지의 JavaScript를 다운로드하고 파싱한 뒤 실행해야 하므로, 일반적으로 다른 렌더링 모드보다 성능이 떨어집니다.
렌더링 중 서버에서 추가 데이터를 가져오는 페이지라면 사용자는 전체 콘텐츠를 보기 위해 추가 요청이 완료될 때까지 기다려야 합니다.

검색 크롤러가 페이지를 색인한다면 클라이언트 사이드 렌더링이 검색 엔진 최적화(SEO)에 악영향을 줄 수 있습니다.
검색 크롤러가 색인 과정에서 실행하는 JavaScript의 양에는 제한이 있기 때문입니다.

클라이언트 사이드 렌더링에서는 서버가 정적 JavaScript 파일을 제공하는 것 외에 페이지 렌더링 작업을 수행할 필요가 없습니다.
서버 비용이 중요하다면 이 점을 고려할 수 있습니다.

[서비스 워커](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API)로 설치와 오프라인 사용을 지원하는 애플리케이션은 서버와 통신할 필요 없이 클라이언트 사이드 렌더링을 사용할 수 있습니다.

##### 서버 사이드 렌더링(SSR)

<!--
Server-side rendering offers faster page loads than client-side rendering. Instead of waiting for JavaScript to download and run, the server directly renders an HTML document upon receiving a request from the browser. The user experiences only the latency necessary for the server to fetch data and render the requested page. This mode also eliminates the need for additional network requests from the browser, as your code can fetch data during rendering on the server.

Server-side rendering generally has excellent search engine optimization (SEO), as search crawlers receive a fully rendered HTML document.

Server-side rendering requires you to author code that does not strictly depend on browser APIs and limits your selection of JavaScript libraries that assume they run in a browser.

When server-side rendering, your server runs Angular to produce an HTML response for every request which may increase server hosting costs.
-->

서버 사이드 렌더링은 클라이언트 사이드 렌더링보다 페이지를 빠르게 로드합니다.
JavaScript 다운로드와 실행을 기다리는 대신, 서버가 브라우저의 요청을 받으면 HTML 문서를 직접 렌더링합니다.
사용자는 서버가 데이터를 가져오고 요청한 페이지를 렌더링하는 시간만 기다리면 됩니다.
서버에서 렌더링하는 동안 코드가 데이터를 가져올 수 있으므로, 브라우저에서 추가 네트워크 요청을 보낼 필요도 없습니다.

서버 사이드 렌더링은 검색 크롤러에 완전히 렌더링된 HTML 문서를 전달하므로 일반적으로 검색 엔진 최적화(SEO)에 매우 유리합니다.

서버 사이드 렌더링에서는 브라우저 API에 전적으로 의존하지 않는 코드를 작성해야 하며, 브라우저 실행을 전제로 하는 JavaScript 라이브러리 선택에도 제한이 생깁니다.

서버 사이드 렌더링에서는 서버가 요청마다 Angular를 실행해서 HTML 응답을 생성하므로 서버 호스팅 비용이 증가할 수 있습니다.

##### 빌드 시점 사전 렌더링

<!--
Prerendering offers faster page loads than both client-side rendering and server-side rendering. Because prerendering creates HTML documents at _build-time_, the server can directly respond to requests with the static HTML document without any additional work.

Prerendering requires that all information necessary to render a page is available at _build-time_. This means that prerendered pages cannot include any data to the specific user loading the page. Prerendering is primarily useful for pages that are the same for all users of your application.

Because prerendering occurs at build-time, it may add significant time to your production builds. Using [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') to produce a large number of HTML documents may affect the total file size of your deployments, and thus lead to slower deployments.

Prerendering generally has excellent search engine optimization (SEO), as search crawlers receive a fully rendered HTML document.

Prerendering requires you to author code that does not strictly depend on browser APIs and limits your selection of JavaScript libraries that assume they run in a browser.

Prerendering incurs extremely little overhead per server request, as your server responds with static HTML documents. Static files are also easily cached by Content Delivery Networks (CDNs), browsers, and intermediate caching layers for even faster subsequent page loads. Fully static sites can also be deployed solely through a CDN or static file server, eliminating the need to maintain a custom server runtime for your application. This enhances scalability by offloading work from an application web server, making it particularly beneficial for high-traffic applications.

NOTE: When using Angular service worker, the first request is server-rendered, but all subsequent requests are handled by the service worker and rendered client-side.
-->

사전 렌더링은 클라이언트 사이드 렌더링과 서버 사이드 렌더링보다 페이지를 빠르게 로드합니다.
_빌드 시점_ 에 HTML 문서를 생성하므로 서버는 추가 작업 없이 정적 HTML 문서로 요청에 바로 응답할 수 있습니다.

사전 렌더링을 사용하려면 페이지를 렌더링하는 데 필요한 모든 정보를 _빌드 시점_ 에 알 수 있어야 합니다.
따라서 사전 렌더링한 페이지에는 페이지를 여는 특정 사용자에 종속된 데이터를 포함할 수 없습니다.
사전 렌더링은 주로 모든 사용자에게 같은 내용을 보여주는 페이지에 유용합니다.

사전 렌더링은 빌드 시점에 수행되므로 프로덕션 빌드 시간이 크게 늘어날 수 있습니다.
[`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API 레퍼런스')로 HTML 문서를 많이 생성하면 배포 파일의 총크기가 늘어나 배포 속도가 느려질 수도 있습니다.

사전 렌더링은 검색 크롤러에 완전히 렌더링된 HTML 문서를 전달하므로 일반적으로 검색 엔진 최적화(SEO)에 매우 유리합니다.

사전 렌더링에서는 브라우저 API에 전적으로 의존하지 않는 코드를 작성해야 하며, 브라우저 실행을 전제로 하는 JavaScript 라이브러리 선택에도 제한이 생깁니다.

사전 렌더링에서는 서버가 정적 HTML 문서로 응답하므로 요청별 부하가 매우 적습니다.
정적 파일은 콘텐츠 전송 네트워크(CDN), 브라우저, 중간 캐시 계층에서도 쉽게 캐시할 수 있어 이후 페이지 로드가 더욱 빨라집니다.
완전한 정적 사이트는 CDN이나 정적 파일 서버만으로도 배포할 수 있으므로 애플리케이션의 별도 서버 런타임을 유지할 필요가 없습니다.
애플리케이션 웹 서버의 작업을 덜어 확장성을 높이므로, 특히 트래픽이 많은 애플리케이션에 유리합니다.

참고: Angular 서비스 워커를 사용하면 첫 요청은 서버에서 렌더링하지만, 이후 모든 요청은 서비스 워커가 처리하고 클라이언트에서 렌더링합니다.

### 헤더와 상태 코드 설정하기

<!--
You can set custom headers and status codes for individual server routes using the `headers` and `status` properties in the `ServerRoute` configuration.

```typescript
{header: "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
];
```
-->

`ServerRoute` 설정의 `headers`, `status` 프로퍼티를 사용하면 개별 서버 라우팅 규칙에 커스텀 헤더와 상태 코드를 지정할 수 있습니다.

```typescript
{header: "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,
  },
  // ... 다른 라우트
];
```

### 리다이렉트

<!--
Angular handles redirects specified by the [`redirectTo`](api/router/Route#redirectTo 'API reference') property in route configurations, differently on the server-side.

**Server-Side Rendering (SSR)**
Redirects are performed using standard HTTP redirects (e.g., 301, 302) within the server-side rendering process.

**Prerendering (SSG)**
Redirects are implemented as "soft redirects" using [`<meta http-equiv="refresh">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#refresh) tags in the prerendered HTML.
-->

Angular는 라우팅 규칙 설정의 [`redirectTo`](api/router/Route#redirectTo 'API 레퍼런스') 프로퍼티로 지정한 리다이렉트를 서버에서 다르게 처리합니다.

**서버 사이드 렌더링(SSR)**
서버 사이드 렌더링 과정에서 표준 HTTP 리다이렉트(예: 301, 302)를 사용합니다.

**사전 렌더링(SSG)**
사전 렌더링한 HTML에 [`<meta http-equiv="refresh">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#refresh) 태그를 넣는 "소프트 리다이렉트" 방식으로 구현합니다.

### 빌드 시점 사전 렌더링(SSG) 커스터마이징하기

[`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API 레퍼런스')를 사용할 때는 여러 설정 옵션으로 사전 렌더링 과정과 콘텐츠 제공 방식을 조정할 수 있습니다.

#### 파라미터가 있는 라우팅 규칙

<!--
For each route with [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), you can specify a [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') function. This function lets you control which specific parameters produce separate prerendered documents.

The [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') function returns a `Promise` that resolves to an array of objects. Each object is a key-value map of route parameter name to value. For example, if you define a route like `post/:id`, `getPrerenderParams ` could return the array `[{id: '123'}, {id: '456'}]`, and thus render separate documents for `post/123` and `post/456`.

The body of [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') can use Angular's [`inject`](api/core/inject 'API reference') function to inject dependencies and perform any work to determine which routes to prerender. This typically includes making requests to fetch data to construct the array of parameter values.

You can also use this function with catch-all routes (e.g., `/**`), where the parameter name will be `"**"` and the return value will be the segments of the path, such as `foo/bar`. These can be combined with other parameters (e.g., `/post/:id/**`) to handle more complex route configuration.

```ts
{header: "app.routes.server.ts"}
import {RenderMode, ServerRoute} from '@angular/ssr';
import {inject} from '@angular/core';

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

Because [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') exclusively applies to [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference'), this function always runs at _build-time_. `getPrerenderParams` must not rely on any browser-specific or server-specific APIs for data.

IMPORTANT: When using [`inject`](api/core/inject 'API reference') inside `getPrerenderParams`, please remember that `inject` must be used synchronously. It cannot be invoked within asynchronous callbacks or following any `await` statements. For more information, refer to `runInInjectionContext`.
-->

[`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API 레퍼런스')를 사용하는 각 라우팅 규칙에 [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API 레퍼런스') 함수를 지정할 수 있습니다.
이 함수로 어떤 파라미터 값에 대해 별도의 사전 렌더링 문서를 생성할지 제어합니다.

[`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API 레퍼런스') 함수는 객체 배열로 이행되는 `Promise`를 반환합니다.
각 객체는 라우팅 규칙 파라미터 이름과 값을 연결하는 키·값 맵입니다.
예를 들어 `post/:id` 라우팅 규칙을 정의하고 `getPrerenderParams`가 `[{id: '123'}, {id: '456'}]`를 반환하면 `post/123`과 `post/456`의 문서를 각각 렌더링합니다.

[`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API 레퍼런스') 안에서는 Angular의 [`inject`](api/core/inject 'API 레퍼런스') 함수로 의존성을 주입하고, 어떤 라우팅 규칙을 사전 렌더링할지 결정하는 작업을 수행할 수 있습니다.
일반적으로 데이터를 요청해서 파라미터 값 배열을 만드는 작업이 여기에 포함됩니다.

이 함수를 모든 경로를 처리하는 catch-all 라우팅 규칙(예: `/**`)에도 사용할 수 있습니다.
이때 파라미터 이름은 `"**"`이며 반환 값은 `foo/bar` 같은 경로 세그먼트입니다.
`/post/:id/**`처럼 다른 파라미터와 조합해서 더 복잡한 라우팅 규칙 설정을 처리할 수도 있습니다.

```ts
{header: "app.routes.server.ts"}
import {RenderMode, ServerRoute} from '@angular/ssr';
import {inject} from '@angular/core';

return ids.map((id) => ({id})); // /post/1, /post/2, /post/3 같은 경로를 생성합니다.
    },
  },
  {
    path: 'post/:id/**',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      return [
        {id: '1', '**': 'foo/3'},
        {id: '2', '**': 'bar/4'},
      ]; // /post/1/foo/3, /post/2/bar/4 같은 경로를 생성합니다.
    },
  },
];
```

[`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API 레퍼런스')는 [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API 레퍼런스')에만 적용되므로 항상 _빌드 시점_ 에 실행됩니다.
`getPrerenderParams`는 데이터를 얻기 위해 브라우저 전용 또는 서버 전용 API에 의존하면 안 됩니다.

중요: `getPrerenderParams` 안에서 [`inject`](api/core/inject 'API 레퍼런스')를 사용할 때는 `inject`를 반드시 동기적으로 호출해야 합니다.
비동기 콜백 안이나 `await` 문 뒤에서는 호출할 수 없습니다.
자세한 내용은 `runInInjectionContext`를 참고하세요.

#### 대체 처리 전략

<!--
When using [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') mode, you can specify a fallback strategy to handle requests for paths that haven't been prerendered.

The available fallback strategies are:

- **Server:** Falls back to server-side rendering. This is the **default** behavior if no `fallback` property is specified.
- **Client:** Falls back to client-side rendering.
- **None:** No fallback. Angular will not handle requests for paths that are not prerendered.

```ts
{header: "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'}];
    },
  },
];
```
-->

[`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API 레퍼런스') 모드에서는 사전 렌더링되지 않은 경로의 요청을 처리할 대체 전략을 지정할 수 있습니다.

사용할 수 있는 대체 처리 전략은 다음과 같습니다:

- **Server:** 서버 사이드 렌더링으로 대체합니다.
  `fallback` 프로퍼티를 지정하지 않았을 때의 **기본** 동작입니다.
- **Client:** 클라이언트 사이드 렌더링으로 대체합니다.
- **None:** 대체 처리를 하지 않습니다.
  Angular는 사전 렌더링되지 않은 경로의 요청을 처리하지 않습니다.

```ts
{header: "app.routes.server.ts"}
import {RenderMode, PrerenderFallback, ServerRoute} from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'post/:id',
    renderMode: RenderMode.Prerender,
    fallback: PrerenderFallback.Client, // 사전 렌더링되지 않았다면 CSR로 대체합니다.
    async getPrerenderParams() {
      // 이 함수는 다음 경로에서 사전 렌더링할 게시물을 나타내는 객체 배열을 반환합니다:
      // `/post/1`, `/post/2`, `/post/3`.
      // `/post/4` 경로가 요청되면 대체 처리 동작을 사용합니다.
      return [{id: '1'}, {id: '2'}, {id: '3'}];
    },
  },
];
```

## 서버와 호환되는 컴포넌트 작성하기

<!--
Some common browser APIs and capabilities might not be available on the server. Applications cannot make use of browser-specific global objects like `window`, `document`, `navigator`, or `location` as well as certain properties of `HTMLElement`.

In general, code which relies on browser-specific symbols should only be executed in the browser, not on the server. This can be enforced through the `afterEveryRender` and `afterNextRender` lifecycle hooks. These are only executed on the browser and skipped on the server.

```typescript
import {Component, ElementRef, 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: Prefer [platform-specific providers](guide/ssr#providing-platform-specific-implementations) over runtime checks with `isPlatformBrowser` or `isPlatformServer`.

IMPORTANT: Avoid using `isPlatformBrowser` in templates with `@if` or other conditionals to render different content on server and client. This causes hydration mismatches and layout shifts, negatively impacting user experience and [Core Web Vitals](https://web.dev/learn-core-web-vitals/). Instead, use `afterNextRender` for browser-specific initialization and keep rendered content consistent across platforms.
-->

일부 일반적인 브라우저 API와 기능은 서버에서 사용할 수 없습니다.
애플리케이션은 `window`, `document`, `navigator`, `location` 같은 브라우저 전용 전역 객체나 `HTMLElement`의 특정 프로퍼티를 사용할 수 없습니다.

일반적으로 브라우저 전용 식별자에 의존하는 코드는 서버가 아닌 브라우저에서만 실행해야 합니다.
`afterEveryRender`, `afterNextRender` 라이프사이클 훅을 사용하면 이렇게 동작하도록 할 수 있습니다.
이 훅은 브라우저에서만 실행되고 서버에서는 건너뜁니다.

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

@Component({
  selector: 'my-cmp',
  template: `<span #content>{{ ... }}</span>`,
})
export class MyComponent {
  contentRef = viewChild.required<ElementRef>('content');

constructor() {
    afterNextRender(() => {
      // 서버가 아닌 브라우저에서만 실행되므로 `scrollHeight`를 안전하게 확인할 수 있습니다.
      console.log('content height: ' + this.contentRef().nativeElement.scrollHeight);
    });
  }
}
```

참고: `isPlatformBrowser`나 `isPlatformServer`로 런타임에 확인하는 대신 [플랫폼별 프로바이더](guide/ssr#providing-platform-specific-implementations)를 사용하는 것이 좋습니다.

중요: 템플릿에서 `isPlatformBrowser`를 `@if`나 다른 조건문과 함께 사용해서 서버와 클라이언트에 서로 다른 콘텐츠를 렌더링하지 마세요.
하이드레이션 불일치와 레이아웃 이동이 발생해서 사용자 경험과 [코어 웹 바이탈](https://web.dev/learn-core-web-vitals/)에 악영향을 줍니다.
대신 브라우저 전용 초기화에는 `afterNextRender`를 사용하고, 렌더링되는 콘텐츠는 플랫폼 간에 일관되게 유지하세요.

## 서버에서 프로바이더 설정하기

<!--
On the server side, top level provider values are set once when the application code is initially parsed and evaluated.
This means that providers configured with `useValue` will keep their value across multiple requests, until the server application is restarted.

If you want to generate a new value for each request, use a factory provider with `useFactory`. The factory function will run for every incoming request, ensuring that a new value is created and assigned to the token each time.
-->

서버의 최상위 프로바이더 값은 애플리케이션 코드가 처음 파싱되고 평가될 때 한 번 설정됩니다.
따라서 `useValue`로 설정한 프로바이더는 서버 애플리케이션이 다시 시작될 때까지 여러 요청에 걸쳐 같은 값을 유지합니다.

요청마다 새로운 값을 생성하려면 `useFactory`를 사용하는 팩토리 프로바이더를 사용하세요.
요청이 들어올 때마다 팩토리 함수가 실행되어 새로운 값을 생성하고 토큰에 할당합니다.

## 플랫폼별 구현 제공하기

<!--
When your application needs different behavior on the browser and server, provide separate service implementations for each platform. This approach centralizes platform logic in dedicated services.

```ts
export abstract class AnalyticsService {
  abstract trackEvent(name: string): void;
}
```

Create the browser implementation:

```ts
@Injectable()
export class BrowserAnalyticsService implements AnalyticsService {
  trackEvent(name: string): void {
    // Sends the event to the browser-based third-party analytics provider
  }
}
```

Create the server implementation:

```ts
@Injectable()
export class ServerAnalyticsService implements AnalyticsService {
  trackEvent(name: string): void {
    // Records the event on the server
  }
}
```

```ts
{header: "app.config.ts"}
export const appConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: BrowserAnalyticsService}],
};
```

Override with the server implementation in your server configuration:

```ts
{header: "app.config.server.ts"}
const serverConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: ServerAnalyticsService}],
};
```

Inject and use the service in your components:

```ts
@Component(/* ... */)
export class Checkout {
  private analytics = inject(AnalyticsService);

onAction() {
    this.analytics.trackEvent('action');
  }
}
```
-->

애플리케이션이 브라우저와 서버에서 다르게 동작해야 한다면 플랫폼별로 별도의 서비스 구현을 제공하세요.
이렇게 하면 플랫폼별 로직을 전용 서비스에 모을 수 있습니다.

```ts
export abstract class AnalyticsService {
  abstract trackEvent(name: string): void;
}
```

브라우저용 구현을 만듭니다:

```ts
@Injectable()
export class BrowserAnalyticsService implements AnalyticsService {
  trackEvent(name: string): void {
    // 브라우저 기반 서드 파티 분석 서비스에 이벤트를 보냅니다.
  }
}
```

서버용 구현을 만듭니다:

```ts
@Injectable()
export class ServerAnalyticsService implements AnalyticsService {
  trackEvent(name: string): void {
    // 서버에 이벤트를 기록합니다.
  }
}
```

메인 애플리케이션 설정에 브라우저용 구현을 등록합니다:

```ts
{header: "app.config.ts"}
export const appConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: BrowserAnalyticsService}],
};
```

서버 설정에서 서버용 구현으로 재정의합니다:

```ts
{header: "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');
  }
}
```

## DI로 Document에 접근하기

<!--
When working with server-side rendering, you should avoid directly referencing browser-specific globals like `document`. Instead, use the [`DOCUMENT`](api/core/DOCUMENT) token to access the document object in a platform-agnostic way.

```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: For managing meta tags, Angular provides the `Meta` service.
-->

서버 사이드 렌더링을 사용할 때는 `document` 같은 브라우저 전용 전역 객체를 직접 참조하지 마세요.
대신 [`DOCUMENT`](api/core/DOCUMENT) 토큰을 사용해서 플랫폼에 종속되지 않는 방식으로 document 객체에 접근하세요.

```ts
import {inject, DOCUMENT, Service} from '@angular/core';

@Service()
export class CanonicalLinkService {
  private readonly document = inject(DOCUMENT);

// 서버에서 렌더링할 때 <link rel="canonical"> 태그를 삽입해서
  // 생성된 HTML에 올바른 표준 URL을 포함합니다.
  setCanonical(href: string): void {
    const link = this.document.createElement('link');
    link.rel = 'canonical';
    link.href = href;
    this.document.head.appendChild(link);
  }
}
```

도움말: 메타 태그를 관리할 때는 Angular가 제공하는 `Meta` 서비스를 사용할 수 있습니다.

## DI로 Request와 Response에 접근하기

<!--
The `@angular/core` package provides several tokens for interacting with the server-side rendering environment. These tokens give you access to crucial information and objects within your Angular application during SSR.

- **[`REQUEST`](api/core/REQUEST 'API reference'):** Provides access to the current request object, which is of type [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) from the Web API. This allows you to access headers, cookies, and other request information.
- **[`RESPONSE_INIT`](api/core/RESPONSE_INIT 'API reference'):** Provides access to the response initialization options, which is of type [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#parameters) from the Web API. This allows you to set headers and the status code for the response dynamically. Use this token to set headers or status codes that need to be determined at runtime.
- **[`REQUEST_CONTEXT`](api/core/REQUEST_CONTEXT 'API reference'):** Provides access to additional context related to the current request. This context can be passed as the second parameter of the [`handle`](api/ssr/AngularAppEngine#handle 'API reference') function. Typically, this is used to provide additional request-related information that is not part of the standard Web API.

```typescript
import {inject, REQUEST, Component} 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);
  }
}
```

<!- UL is used below as otherwise the list will not be include as part of the note. ->
<!- prettier-ignore-start ->

IMPORTANT: The above tokens will be `null` in the following scenarios:<ul class="docs-list">
  <li>During the build processes.</li>
  <li>When the application is rendered in the browser (CSR).</li>
  <li>When performing static site generation (SSG).</li>
  <li>During route extraction in development (at the time of the request).</li>
</ul>

<!- prettier-ignore-end ->
-->

`@angular/core` 패키지는 서버 사이드 렌더링 환경과 상호작용하는 여러 토큰을 제공합니다.
이 토큰으로 SSR 중 Angular 애플리케이션에서 필요한 주요 정보와 객체에 접근할 수 있습니다.

- **[`REQUEST`](api/core/REQUEST 'API 레퍼런스'):** Web API의 [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) 타입인 현재 요청 객체에 접근합니다.
  헤더, 쿠키, 그 밖의 요청 정보를 확인할 수 있습니다.
- **[`RESPONSE_INIT`](api/core/RESPONSE_INIT 'API 레퍼런스'):** Web API의 [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#parameters) 타입인 응답 초기화 옵션에 접근합니다.
  응답의 헤더와 상태 코드를 동적으로 설정할 수 있습니다.
  런타임에 결정해야 하는 헤더나 상태 코드는 이 토큰을 사용해서 설정하세요.
- **[`REQUEST_CONTEXT`](api/core/REQUEST_CONTEXT 'API 레퍼런스'):** 현재 요청과 관련된 추가 컨텍스트에 접근합니다.
  이 컨텍스트는 [`handle`](api/ssr/AngularAppEngine#handle 'API 레퍼런스') 함수의 두 번째 파라미터로 전달할 수 있습니다.
  일반적으로 표준 Web API에 포함되지 않는 추가 요청 정보를 제공할 때 사용합니다.

```typescript
import {inject, REQUEST, Component} from '@angular/core';

중요: 위 토큰은 다음 상황에서 `null`입니다:<ul class="docs-list">
  <li>빌드 과정 중.</li>
  <li>애플리케이션이 브라우저에서 렌더링되는 경우(CSR).</li>
  <li>정적 사이트 생성(SSG)을 수행하는 경우.</li>
  <li>개발 중 라우팅 규칙을 추출하는 경우(요청 시점).</li>
</ul>

## 완전한 정적 애플리케이션 생성하기

<!--
By default, Angular prerenders your entire application and generates a server file for handling requests. This allows your app to serve pre-rendered content to users. However, if you prefer a fully static site without a server, you can opt out of this behavior by setting the `outputMode` to `static` in your `angular.json` configuration file.

When `outputMode` is set to `static`, Angular generates pre-rendered HTML files for each route at build time, but it does not generate a server file or require a Node.js server to serve the app. This is useful for deploying to static hosting providers where a backend server is not needed.

To configure this, update your `angular.json` file as follows:

```json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "outputMode": "static"
          }
        }
      }
    }
  }
}
```
-->

기본적으로 Angular는 애플리케이션 전체를 사전 렌더링하고 요청을 처리하는 서버 파일을 생성합니다.
이 방식으로 사전 렌더링한 콘텐츠를 사용자에게 제공할 수 있습니다.
하지만 서버 없는 완전한 정적 사이트를 원한다면 `angular.json` 설정 파일에서 `outputMode`를 `static`으로 설정해서 이 동작을 변경할 수 있습니다.

`outputMode`가 `static`이면 Angular는 빌드 시점에 각 라우팅 규칙의 사전 렌더링 HTML 파일을 생성하지만 서버 파일은 생성하지 않으며, 애플리케이션을 제공할 Node.js 서버도 필요하지 않습니다.
백엔드 서버가 필요 없는 정적 호스팅 서비스에 배포할 때 유용합니다.

다음과 같이 `angular.json` 파일을 수정하세요:

```json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "outputMode": "static"
          }
        }
      }
    }
  }
}
```

## HttpClient를 사용할 때 데이터 캐시하기

`HttpClient`는 서버에서 실행할 때 외부로 보내는 네트워크 요청을 캐시합니다.
이 정보는 직렬화되어 서버가 보내는 초기 HTML의 일부로 브라우저에 전달됩니다.
브라우저의 `HttpClient`는 캐시에 데이터가 있는지 확인하고, 있다면 애플리케이션의 초기 렌더링 중 새 HTTP 요청을 보내는 대신 캐시를 재사용합니다.
브라우저에서 애플리케이션이 [안정 상태](api/core/ApplicationRef#isStable)에 도달하면 `HttpClient`는 캐시 사용을 중단합니다.

<!--
### Configuring the response body size limit

When `HttpClient` uses the default fetch backend during server-side rendering, Angular limits each response body to 1 MB. This limit prevents the server from buffering unexpectedly large responses during rendering. If a response exceeds the configured limit, the request fails with the [NG02825](errors/NG02825) error.

If your application needs to fetch larger responses during server rendering, set `maxResponseBodySize` in the `provideServerRendering` options:

```ts
import {provideServerRendering, withRoutes} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {serverRoutes} from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(
      {
        maxResponseBodySize: 5 * 1024 * 1024, // 5MB
      },
      withRoutes(serverRoutes),
    ),
  ],
};
```

`maxResponseBodySize` is configured in bytes and applies globally to server-side `HttpClient` requests that use the fetch backend.

IMPORTANT: Keep this limit as small as your application allows. Increasing it lets server-side requests buffer larger response bodies, which can increase memory use and denial-of-service risk. Prefer moving large downloads outside server rendering.

### 응답 본문 크기 제한 설정하기

서버 사이드 렌더링 중 `HttpClient`가 기본 fetch 백엔드를 사용하면 Angular는 각 응답 본문을 1MB로 제한합니다.
렌더링 중 서버가 예상보다 큰 응답을 버퍼에 저장하는 것을 막기 위한 제한입니다.
응답이 설정한 제한을 초과하면 요청은 [NG02825](errors/NG02825) 오류로 실패합니다.

서버 렌더링 중 더 큰 응답을 가져와야 한다면 `provideServerRendering` 옵션에서 `maxResponseBodySize`를 설정하세요:

```ts
import {provideServerRendering, withRoutes} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {serverRoutes} from './app.routes.server';

`maxResponseBodySize`는 바이트 단위이며, fetch 백엔드를 사용하는 서버 측 `HttpClient` 요청에 전역으로 적용됩니다.

IMPORTANT: 애플리케이션에서 허용하는 범위 안에서 제한을 최대한 작게 유지하세요. 제한을 높이면 서버 측 요청이 더 큰 응답 본문을 버퍼에 저장할 수 있어 메모리 사용량과 서비스 거부 공격 위험이 커질 수 있습니다. 큰 파일 다운로드는 서버 렌더링 밖에서 처리하는 편이 좋습니다.

CRITICAL: SSR 중 Fetch 구현은 [Fetch 표준](https://fetch.spec.whatwg.org/#concept-main-fetch)에 따라 응답을 반환하기 전에 응답 본문 전체를 읽어 `integrity`를 검증합니다. Angular는 Fetch가 응답을 반환한 뒤에만 [`maxResponseBodySize`](/guide/ssr#configuring-the-response-body-size-limit)를 적용하므로, 이 제한으로 무결성 검증 중 버퍼에 저장되는 데이터까지 제한할 수는 없습니다.

### 캐시 옵션 설정하기

<!--
You can customize how Angular caches HTTP responses during server‑side rendering (SSR) and reuses them during hydration by configuring `HttpTransferCacheOptions`.
This configuration is provided globally using `withHttpTransferCacheOptions` inside `provideClientHydration()`.

By default, `HttpClient` caches all `HEAD` and `GET` requests which don't contain `Authorization`, `Proxy-Authorization`, or `Cookie` headers and are not sent with `withCredentials` or Fetch API `credentials` modes that can send credentials. Angular also skips transfer cache when a request or response includes `Cache-Control` directives that forbid caching (`no-store`, `no-cache`, or `private`), or when the Fetch API `cache` option is set to `no-store` or `no-cache`. Responses that carry a `Set-Cookie` header are also skipped. You can override the request filtering settings by using `withHttpTransferCacheOptions` in the hydration configuration.

```ts
import {
  bootstrapApplication,
  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,
      }),
    ),
  ],
});
```

---
-->

`HttpTransferCacheOptions`를 설정하면 Angular가 서버 사이드 렌더링(SSR) 중 HTTP 응답을 캐시하고 하이드레이션 중 재사용하는 방식을 조정할 수 있습니다.  
이 설정은 `provideClientHydration()` 안의 `withHttpTransferCacheOptions`로 전역에 제공합니다.

기본적으로 `HttpClient`는 `Authorization`, `Proxy-Authorization`, `Cookie` 헤더가 없고, `withCredentials`나 자격 증명을 전송할 수 있는 Fetch API의 `credentials` 모드로 보내지 않은 모든 `HEAD`, `GET` 요청을 캐시합니다.
요청이나 응답의 `Cache-Control`에 캐시를 금지하는 지시자(`no-store`, `no-cache`, `private`)가 있거나 Fetch API의 `cache` 옵션이 `no-store` 또는 `no-cache`이면 Angular는 전송 캐시를 건너뜁니다.
`Set-Cookie` 헤더가 포함된 응답도 건너뜁니다.
하이드레이션 설정의 `withHttpTransferCacheOptions`로 요청 필터링 설정을 재정의할 수 있습니다.

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

---

### `includeHeaders`

<!--
Specifies which headers from the server response should be included in cached entries.
No headers are included by default.

```ts
withHttpTransferCacheOptions({
  includeHeaders: ['ETag', 'Cache-Control'],
});
```

IMPORTANT: Avoid including sensitive headers like authentication tokens. These can leak user‑specific data between requests.

Including `Cache-Control` in `includeHeaders` only makes that header available on the hydrated response. Angular already evaluates `Cache-Control` headers automatically when deciding whether a request or response is eligible for transfer cache.

---
-->

서버 응답의 어떤 헤더를 캐시 항목에 포함할지 지정합니다.  
기본적으로 헤더는 포함하지 않습니다.

```ts
withHttpTransferCacheOptions({
  includeHeaders: ['ETag', 'Cache-Control'],
});
```

중요: 인증 토큰 같은 민감한 헤더를 포함하지 마세요.
요청 사이에서 사용자별 데이터가 유출될 수 있습니다.

`includeHeaders`에 `Cache-Control`을 포함하는 것은 하이드레이션된 응답에서 해당 헤더를 읽을 수 있게 할 뿐입니다.
Angular는 요청이나 응답을 전송 캐시에 저장할 수 있는지 판단할 때 이미 `Cache-Control` 헤더를 자동으로 평가합니다.

---

### `includePostRequests`

<!--
By default, only `GET` and `HEAD` requests are cached.
You can enable caching for `POST` requests when they are used as read operations such as GraphQL queries.

```ts
withHttpTransferCacheOptions({
  includePostRequests: true,
});
```

Use this only when `POST` requests are **idempotent** and safe to reuse between server and client renders.

---
-->

기본적으로 `GET`과 `HEAD` 요청만 캐시합니다.  
GraphQL 쿼리처럼 읽기 작업에 사용하는 `POST` 요청은 캐시를 활성화할 수 있습니다.

```ts
withHttpTransferCacheOptions({
  includePostRequests: true,
});
```

`POST` 요청이 **멱등적**이며 서버와 클라이언트 렌더링 사이에서 안전하게 재사용할 수 있을 때만 사용하세요.

---

### `includeRequestsWithAuthHeaders`

<!--
Determines whether requests containing `Authorization`, `Proxy‑Authorization`, or `Cookie` headers are eligible for caching.
By default, these are excluded to prevent caching user‑specific responses.

```ts
withHttpTransferCacheOptions({
  includeRequestsWithAuthHeaders: true,
});
```

Enable only when authentication headers do **not** affect the response content (for example, public tokens for analytics APIs).
-->

`Authorization`, `Proxy‑Authorization`, `Cookie` 헤더가 포함된 요청을 캐시할 수 있는지 결정합니다.  
사용자별 응답이 캐시되지 않도록 기본적으로 제외합니다.

```ts
withHttpTransferCacheOptions({
  includeRequestsWithAuthHeaders: true,
});
```

인증 헤더가 응답 내용에 영향을 **주지 않는** 경우에만 활성화하세요.
예를 들어 분석 API의 공개 토큰이 여기에 해당합니다.

<!--
### `includeRequestsWithCredentials`

Determines whether requests sent using `withCredentials` or Fetch API `credentials` modes (`include` or `same-origin`) are eligible for caching.
By default, these are excluded to prevent caching user‑specific responses.

```ts
withHttpTransferCacheOptions({
  includeRequestsWithCredentials: true,
});
```

Enable only when credentialed requests return responses that are safe to cache.
-->

### `includeRequestsWithCredentials`

`withCredentials` 또는 Fetch API의 `credentials` 모드(`include`, `same-origin`)로 보내는 요청을 캐시할 수 있는지 결정합니다.
사용자별 응답이 캐시되지 않도록 기본적으로 제외합니다.

```ts
withHttpTransferCacheOptions({
  includeRequestsWithCredentials: true,
});
```

자격 증명을 포함하는 요청이 캐시해도 안전한 응답을 반환할 때만 활성화하세요.

<!--
### `includeNonCacheableRequests`

Determines whether requests and responses containing `Cache-Control` directives that forbid caching (`no-store`, `no-cache`, or `private`), responses with a `Set-Cookie` header, or requests using Fetch API `cache` options (`no-store` or `no-cache`), are eligible for caching.
By default, these are excluded to respect HTTP caching controls.

```ts
withHttpTransferCacheOptions({
  includeNonCacheableRequests: true,
});
```

Enable only when you need to bypass cache-control restrictions for transfer caching.
-->

### `includeNonCacheableRequests`

캐시를 금지하는 `Cache-Control` 지시자(`no-store`, `no-cache`, `private`)가 포함된 요청과 응답, `Set-Cookie` 헤더가 포함된 응답, Fetch API의 `cache` 옵션(`no-store`, `no-cache`)을 사용하는 요청을 캐시할 수 있는지 결정합니다.
HTTP 캐시 제어를 따르도록 기본적으로 제외합니다.

```ts
withHttpTransferCacheOptions({
  includeNonCacheableRequests: true,
});
```

전송 캐시에 대해 캐시 제어 제한을 우회해야 할 때만 활성화하세요.

### 요청별 재정의

<!--
You can override caching behavior for a specific request using the `transferCache` request option.

```ts
// Include specific headers for this request
http.get('/api/profile', {transferCache: {includeHeaders: ['CustomHeader']}});
```
-->

`transferCache` 요청 옵션으로 특정 요청의 캐시 동작을 재정의할 수 있습니다.

```ts
// 이 요청에 특정 헤더를 포함합니다.
http.get('/api/profile', {transferCache: {includeHeaders: ['CustomHeader']}});
```

### 캐시 비활성화하기

서버에서 보내는 요청의 HTTP 캐시를 전역으로 비활성화하거나 개별적으로 비활성화할 수 있습니다.

#### 전역 비활성화

<!--
To disable caching for all requests in your application, use the `withNoHttpTransferCache` feature:

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoHttpTransferCache,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoHttpTransferCache())],
});
```
-->

애플리케이션의 모든 요청에 대해 캐시를 비활성화하려면 `withNoHttpTransferCache` 기능을 사용하세요:

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoHttpTransferCache,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoHttpTransferCache())],
});
```

#### 필터링

<!--
You can also selectively disable caching for certain requests using the [`filter`](api/common/http/HttpTransferCacheOptions) option in `withHttpTransferCacheOptions`. For example, you can disable caching for a specific API endpoint:

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        filter: (req) => !req.url.includes('/api/sensitive-data'),
      }),
    ),
  ],
});
```

Use this option to exclude endpoints with user‑specific or dynamic data (for example `/api/profile`).
-->

`withHttpTransferCacheOptions`의 [`filter`](api/common/http/HttpTransferCacheOptions) 옵션으로 특정 요청의 캐시만 선택적으로 비활성화할 수도 있습니다.
예를 들어 특정 API 엔드포인트의 캐시를 비활성화할 수 있습니다:

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

`/api/profile`처럼 사용자별 데이터나 동적 데이터를 제공하는 엔드포인트를 제외할 때 이 옵션을 사용하세요.

#### 요청별 비활성화

<!--
To disable caching for an individual request, you can specify the [`transferCache`](api/common/http/HttpRequest#transferCache) option in an `HttpRequest`.

```ts
httpClient.get('/api/sensitive-data', {transferCache: false});
```

`HttpTransferCache` does not cache requests or responses that explicitly opt out of caching. Angular skips transfer cache entries when a request includes a `Cache-Control` header with `no-store`, `no-cache`, or `private`, or when the request uses the Fetch API `cache` option set to `no-store` or `no-cache`. Responses with `Cache-Control: no-store`, `Cache-Control: no-cache`, or `Cache-Control: private` are also not stored in the transfer cache. Responses that include a `Set-Cookie` header are likewise not stored, as they typically carry user-specific state.

NOTE: If your application uses different HTTP origins to make API calls on the server and on the client, the `HTTP_TRANSFER_CACHE_ORIGIN_MAP` token allows you to establish a mapping between those origins, so that `HttpTransferCache` feature can recognize those requests as the same ones and reuse the data cached on the server during hydration on the client.
-->

개별 요청의 캐시를 비활성화하려면 `HttpRequest`에 [`transferCache`](api/common/http/HttpRequest#transferCache) 옵션을 지정하세요.

```ts
httpClient.get('/api/sensitive-data', {transferCache: false});
```

`HttpTransferCache`는 명시적으로 캐시를 거부하는 요청이나 응답을 캐시하지 않습니다.
요청의 `Cache-Control` 헤더에 `no-store`, `no-cache`, `private`가 있거나 Fetch API의 `cache` 옵션이 `no-store` 또는 `no-cache`이면 Angular는 전송 캐시를 건너뜁니다.
`Cache-Control: no-store`, `Cache-Control: no-cache`, `Cache-Control: private` 응답도 전송 캐시에 저장하지 않습니다.
`Set-Cookie` 헤더가 포함된 응답도 일반적으로 사용자별 상태를 담고 있으므로 저장하지 않습니다.

참고: 서버와 클라이언트에서 서로 다른 HTTP 출처(origin)로 API를 호출한다면, `HTTP_TRANSFER_CACHE_ORIGIN_MAP` 토큰으로 출처 사이의 매핑을 지정할 수 있습니다.
그러면 `HttpTransferCache`는 이 요청을 같은 요청으로 인식하고, 클라이언트 하이드레이션 중 서버에서 캐시한 데이터를 재사용할 수 있습니다.

## 서버 설정하기

### Node.js

<!--
The `@angular/ssr/node` extends `@angular/ssr` specifically for Node.js environments. It provides APIs that make it easier to implement server-side rendering within your Node.js application. For a complete list of functions and usage examples, refer to the [`@angular/ssr/node` API reference](api/ssr/node/AngularNodeAppEngine) API reference.

```ts
{header: "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);
```
-->

`@angular/ssr/node`는 Node.js 환경에 맞춰 `@angular/ssr`를 확장한 패키지입니다.
Node.js 애플리케이션에서 서버 사이드 렌더링을 쉽게 구현할 수 있는 API를 제공합니다.
전체 함수 목록과 사용 예제는 [`@angular/ssr/node` API 레퍼런스](api/ssr/node/AngularNodeAppEngine)를 참고하세요.

```ts
{header: "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(); // 다음 미들웨어로 제어를 넘깁니다.
      }
    })
    .catch(next);
});

/**
 * Angular CLI가 개발 서버와 빌드 중에 사용하는 요청 핸들러입니다.
 */
export const reqHandler = createNodeRequestHandler(app);
```

### Node.js 외의 환경

<!--
The `@angular/ssr` provides essential APIs for server-side rendering your Angular application on platforms other than Node.js. It leverages the standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects from the Web API, enabling you to integrate Angular SSR into various server environments. For detailed information and examples, refer to the [`@angular/ssr` API reference](api/ssr/AngularAppEngine).

```ts
{header: "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.handle(req);

// ...
});
```
-->

`@angular/ssr`는 Node.js가 아닌 플랫폼에서 Angular 애플리케이션을 서버 사이드 렌더링하는 데 필요한 핵심 API를 제공합니다.
Web API의 표준 [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)와 [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) 객체를 사용하므로 다양한 서버 환경에 Angular SSR을 통합할 수 있습니다.
자세한 내용과 예제는 [`@angular/ssr` API 레퍼런스](api/ssr/AngularAppEngine)를 참고하세요.

```ts
{header: "server.ts"}
import {AngularAppEngine, createRequestHandler} from '@angular/ssr';

const angularApp = new AngularAppEngine();

/**
 * Angular CLI가 개발 서버와 빌드 중에 사용하는 요청 핸들러입니다.
 */
export const reqHandler = createRequestHandler(async (req: Request) => {
  const res: Response | null = await angularApp.handle(req);

// ...
});
```

## 보안

서버 측 요청 위조(SSRF) 방지와 허용 호스트 설정에 대한 자세한 내용은 [서버 측 보안](best-practices/security#preventing-server-side-request-forgery-ssrf) 가이드를 참고하세요.

# 하이드레이션

## 하이드레이션이 무엇인가요?

하이드레이션은 서버에서 렌더링한 애플리케이션을 클라이언트에서 복원하는 과정입니다.
서버에서 렌더링한 DOM 구조 재사용, 애플리케이션 상태 유지, 서버가 이미 조회한 애플리케이션 데이터 전송 등의 작업이 이 과정에 포함됩니다.

## 하이드레이션은 왜 중요한가요?

<!--
Hydration improves application performance by avoiding extra work to re-create DOM nodes. Instead, Angular tries to match existing DOM elements to the application's structure at runtime and reuses DOM nodes when possible. This results in a performance improvement that can be measured using [Core Web Vitals (CWV)](https://web.dev/learn-core-web-vitals/) statistics, such as reducing the First Input Delay ([FID](https://web.dev/fid/)) and Largest Contentful Paint ([LCP](https://web.dev/lcp/)), as well as Cumulative Layout Shift ([CLS](https://web.dev/cls/)). Improving these numbers also affects things like SEO performance.

Without hydration enabled, server-side rendered Angular applications will destroy and re-render the application's DOM, which may result in a visible UI flicker. This re-rendering can negatively impact [Core Web Vitals](https://web.dev/learn-core-web-vitals/) like [LCP](https://web.dev/lcp/) and cause a layout shift. Enabling hydration allows the existing DOM to be re-used and prevents a flicker.
-->

하이드레이션은 DOM 노드를 다시 만드는 추가 작업을 피해서 애플리케이션 성능을 개선합니다.
대신 Angular는 런타임에 기존 DOM 엘리먼트를 애플리케이션 구조와 맞춰 보고, 가능한 경우 DOM 노드를 재사용합니다.
이 성능 개선은 최초 입력 지연([FID](https://web.dev/fid/)), 최대 콘텐츠풀 페인트([LCP](https://web.dev/lcp/)), 누적 레이아웃 이동([CLS](https://web.dev/cls/)) 감소처럼 [코어 웹 바이탈(CWV)](https://web.dev/learn-core-web-vitals/) 지표로 측정할 수 있습니다.
이런 수치의 개선은 SEO 성과 등에도 영향을 줍니다.

하이드레이션을 활성화하지 않으면 서버에서 렌더링한 Angular 애플리케이션은 애플리케이션의 DOM을 파괴하고 다시 렌더링하므로, UI가 깜박이는 현상이 나타날 수 있습니다.
이 재렌더링은 [LCP](https://web.dev/lcp/) 같은 [코어 웹 바이탈](https://web.dev/learn-core-web-vitals/)에 악영향을 주고 레이아웃 이동을 일으킬 수 있습니다.
하이드레이션을 활성화하면 기존 DOM을 재사용해서 깜박임을 방지합니다.

## Angular에서 하이드레이션 활성화하기

하이드레이션은 서버 사이드 렌더링(SSR)을 사용하는 애플리케이션에서만 활성화할 수 있습니다.
먼저 [Angular SSR 가이드](guide/ssr)에 따라 서버 사이드 렌더링을 활성화하세요.

### Angular CLI 사용하기

애플리케이션을 생성할 때 SSR을 활성화했거나, 나중에 `ng add @angular/ssr`를 실행하는 등 Angular CLI로 SSR을 활성화했다면 하이드레이션을 활성화하는 코드가 애플리케이션에 이미 포함되어 있습니다.

### 직접 설정하기

<!--
If you have a custom setup and didn't use Angular CLI to enable SSR, you can enable hydration manually by visiting your main application component or module and importing `provideClientHydration` from `@angular/platform-browser`. You'll then add that provider to your app's bootstrapping providers list.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
} from '@angular/platform-browser';
...

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

Alternatively if you are using NgModules, you would add `provideClientHydration` to your root app module's provider list.

```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: Make sure that the `provideClientHydration()` call is also included into a set of providers that is used to bootstrap an application on the **server**. In applications with the default project structure (generated by the `ng new` command), adding a call to the root `AppModule` should be sufficient, since this module is imported by the server module. If you use a custom setup, add the `provideClientHydration()` call to the providers list in the server bootstrap configuration.
-->

Angular CLI로 SSR을 활성화하지 않고 직접 구성했다면, 메인 애플리케이션 컴포넌트나 모듈에서 `@angular/platform-browser`의 `provideClientHydration`을 가져와 하이드레이션을 수동으로 활성화할 수 있습니다.
그런 다음 애플리케이션을 부트스트랩하는 프로바이더 목록에 이 프로바이더를 추가하세요.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
} from '@angular/platform-browser';
...

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

NgModule을 사용한다면 루트 애플리케이션 모듈의 프로바이더 목록에 `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 {}
```

중요: **서버**에서 애플리케이션을 부트스트랩하는 데 사용하는 프로바이더에도 `provideClientHydration()` 호출이 포함되어 있는지 확인하세요.
`ng new` 명령으로 생성한 기본 프로젝트 구조에서는 서버 모듈이 루트 `AppModule`을 가져오므로, 이 루트 모듈에 호출을 추가하는 것으로 충분합니다.
직접 구성한 환경이라면 서버 부트스트랩 설정의 프로바이더 목록에도 `provideClientHydration()` 호출을 추가하세요.

### 하이드레이션 활성화 여부 확인하기

<!--
After you've configured hydration and have started up your server, load your application in the browser.

HELPFUL: You will likely need to fix instances of Direct DOM Manipulation before hydration will fully work either by switching to Angular constructs or by using `ngSkipHydration`. See [Constraints](#constraints), [Direct DOM Manipulation](#direct-dom-manipulation), and [How to skip hydration for particular components](#how-to-skip-hydration-for-particular-components) for more details.

While running an application in dev mode, you can confirm hydration is enabled by opening the Developer Tools in your browser and viewing the console. You should see a message that includes hydration-related stats, such as the number of components and nodes hydrated. Angular calculates the stats based on all components rendered on a page, including those that come from third-party libraries.

You can also use [Angular DevTools browser extension](tools/devtools) to see hydration status of components on a page. Angular DevTools also allows to enable an overlay to indicate which parts of the page were hydrated. If there is a hydration mismatch error - DevTools would also highlight a component that caused the error.
-->

하이드레이션을 설정하고 서버를 시작했다면 브라우저에서 애플리케이션을 여세요.

도움말: 하이드레이션이 완전히 동작하려면 DOM을 직접 조작하는 부분을 Angular 기능으로 바꾸거나 `ngSkipHydration`을 사용해야 할 수 있습니다.
자세한 내용은 [제약 사항](#constraints), [DOM 직접 조작](#direct-dom-manipulation), [특정 컴포넌트에서 하이드레이션 건너뛰기](#how-to-skip-hydration-for-particular-components)를 참고하세요.

개발 모드로 애플리케이션을 실행할 때는 브라우저의 개발자 도구에서 콘솔을 열어 하이드레이션 활성화 여부를 확인할 수 있습니다.
하이드레이션한 컴포넌트와 노드 수 등 관련 통계를 담은 메시지가 표시됩니다.
Angular는 서드 파티 라이브러리의 컴포넌트를 포함해서, 페이지에 렌더링된 모든 컴포넌트를 기준으로 통계를 계산합니다.

[Angular DevTools 브라우저 확장 프로그램](tools/devtools)으로 페이지의 컴포넌트별 하이드레이션 상태를 확인할 수도 있습니다.
Angular DevTools에서는 페이지의 어느 부분이 하이드레이션되었는지 보여주는 오버레이를 활성화할 수 있습니다.
하이드레이션 불일치 오류가 발생하면 오류를 일으킨 컴포넌트도 강조 표시합니다.

## 이벤트 캡처와 재실행

<!--
When an application is rendered on the server, it is visible in a browser as soon as produced HTML loads. Users may assume that they can interact with the page, but event listeners are not attached until hydration completes. The Event Replay feature captures all events that happen before hydration and replays those events once hydration has completed.

Event replay is enabled alongside [incremental hydration](guide/incremental-hydration). If you opt out of incremental hydration with `withNoIncrementalHydration()`, you can still enable event replay using the `withEventReplay()` function:

```typescript
import {
  provideClientHydration,
  withEventReplay,
  withNoIncrementalHydration,
  bootstrapApplication,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoIncrementalHydration(), withEventReplay())],
});
```
-->

서버에서 렌더링한 애플리케이션은 생성된 HTML이 로드되면 바로 브라우저에 표시됩니다.
사용자는 페이지와 상호작용할 수 있다고 생각할 수 있지만, 이벤트 리스너는 하이드레이션이 완료될 때까지 연결되지 않습니다.
이벤트 재실행(Event Replay) 기능은 하이드레이션 전에 발생한 모든 이벤트를 캡처하고 하이드레이션이 완료되면 다시 실행합니다.

이벤트 재실행은 [점진적 하이드레이션](guide/incremental-hydration)과 함께 활성화됩니다.
`withNoIncrementalHydration()`으로 점진적 하이드레이션을 비활성화해도 `withEventReplay()`으로 이벤트 재실행을 활성화할 수 있습니다.
다음 예제를 참고하세요:

```typescript
import {
  provideClientHydration,
  withEventReplay,
  withNoIncrementalHydration,
  bootstrapApplication,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoIncrementalHydration(), withEventReplay())],
});
```

### 이벤트 재실행 동작 방식

<!--
Event Replay is a feature that improves user experience by capturing user events that were triggered before the hydration process is complete. Then those events are replayed, ensuring none of that interaction was lost.

The Event Replay is divided into three main phases:

- **Capturing user interactions**<br>
  Prior to **Hydration**, Event Replay captures and stores all interactions that the user may perform, such as clicks and other browser native events.

- **Storing events**<br>
  The **Event Contract** keeps in memory all the interactions recorded in the previous step, ensuring that they are not lost for later replay.

- **Relaunch of events**<br>
  Once **Hydration** is complete, Angular re-invokes the captured events.

Event replay supports _native browser events_, for example `click`, `mouseover`, and `focusin`. If you'd like to learn more about JSAction, the library that powers event replay, you can read more [on the readme](https://github.com/angular/angular/tree/main/packages/core/primitives/event-dispatch#readme).

This feature ensures a consistent user experience, preventing user actions performed before hydration from being ignored.

-->

이벤트 재실행은 하이드레이션 과정이 끝나기 전에 발생한 사용자 이벤트를 캡처해서 사용자 경험을 개선하는 기능입니다.
캡처한 이벤트를 나중에 재실행하므로 사용자 상호작용이 사라지지 않습니다.

이벤트 재실행은 크게 세 단계로 나뉩니다:

- **사용자 상호작용 캡처**<br>
  **하이드레이션** 전에 클릭과 그 밖의 브라우저 네이티브 이벤트 등 사용자가 수행하는 모든 상호작용을 캡처하고 저장합니다.

- **이벤트 저장**<br>
  **Event Contract**는 앞 단계에서 기록한 모든 상호작용을 메모리에 보관해서, 나중에 재실행할 때까지 잃어버리지 않도록 합니다.

- **이벤트 재실행**<br>
  **하이드레이션**이 완료되면 Angular가 캡처한 이벤트를 다시 실행합니다.

이벤트 재실행은 `click`, `mouseover`, `focusin` 같은 _브라우저 네이티브 이벤트_ 를 지원합니다.
이벤트 재실행을 구현하는 라이브러리인 JSAction에 대해 더 알고 싶다면 [README](https://github.com/angular/angular/tree/main/packages/core/primitives/event-dispatch#readme)를 참고하세요.

이 기능은 하이드레이션 전에 수행한 사용자 행동이 무시되지 않도록 해서 일관된 사용자 경험을 제공합니다.

## 제약 사항

<!--
Hydration imposes a few constraints on your application that are not present without hydration enabled. Your application must have the same generated DOM structure on both the server and the client. The process of hydration expects the DOM tree to have the same structure in both places. This also includes whitespaces and comment nodes that Angular produces during the rendering on the server. Those whitespaces and nodes must be present in the HTML generated by the server-side rendering process.

IMPORTANT: The HTML produced by the server side rendering operation **must not** be altered between the server and the client.

If there is a mismatch between server and client DOM tree structures, the hydration process will encounter problems attempting to match up what was expected to what is actually present in the DOM. Components that do direct DOM manipulation using native DOM APIs are the most common culprit.
-->

하이드레이션을 활성화하면 그렇지 않을 때는 없던 몇 가지 제약이 생깁니다.
애플리케이션은 서버와 클라이언트 양쪽에서 같은 DOM 구조를 생성해야 합니다.
하이드레이션 과정은 두 환경의 DOM 트리 구조가 같다고 가정합니다.
여기에는 서버에서 렌더링할 때 Angular가 생성하는 공백과 주석 노드도 포함됩니다.
서버 사이드 렌더링으로 생성한 HTML에는 이 공백과 노드가 그대로 있어야 합니다.

중요: 서버 사이드 렌더링으로 생성한 HTML은 서버에서 클라이언트로 전달되는 동안 **변경되면 안 됩니다**.

서버와 클라이언트의 DOM 트리 구조가 다르면 하이드레이션 과정에서 예상 구조와 실제 DOM 구조를 맞추는 데 문제가 생깁니다.
네이티브 DOM API로 DOM을 직접 조작하는 컴포넌트가 가장 흔한 원인입니다.

### DOM 직접 조작

<!--
If you have components that manipulate the DOM using native DOM APIs or use `innerHTML` or `outerHTML`, the hydration process will encounter errors. Specific cases where DOM manipulation is a problem are situations like accessing the `document`, querying for specific elements, and injecting additional nodes using `appendChild`. Detaching DOM nodes and moving them to other locations will also result in errors.

This is because Angular is unaware of these DOM changes and cannot resolve them during the hydration process. Angular will expect a certain structure, but it will encounter a different structure when attempting to hydrate. This mismatch will result in hydration failure and throw a DOM mismatch error ([see below](#errors)).

It is best to refactor your component to avoid this sort of DOM manipulation. Try to use Angular APIs to do this work, if you can. If you cannot refactor this behavior, use the `ngSkipHydration` attribute ([described below](#how-to-skip-hydration-for-particular-components)) until you can refactor into a hydration friendly solution.
-->

네이티브 DOM API나 `innerHTML`, `outerHTML`로 DOM을 조작하는 컴포넌트가 있으면 하이드레이션 과정에서 오류가 발생합니다.
`document`에 접근하거나, 특정 엘리먼트를 조회하거나, `appendChild`로 노드를 추가하는 경우 등이 문제가 될 수 있습니다.
DOM 노드를 분리해서 다른 위치로 옮기는 경우에도 오류가 발생합니다.

Angular가 이런 DOM 변경을 알지 못하며 하이드레이션 과정에서 처리할 수 없기 때문입니다.
Angular는 특정 구조를 예상하지만 하이드레이션하려고 할 때 다른 구조를 만나게 됩니다.
이 불일치로 인해 하이드레이션이 실패하고 DOM 불일치 오류가 발생합니다([아래 참고](#errors)).

이런 DOM 조작을 피하도록 컴포넌트를 리팩토링하는 것이 가장 좋습니다.
가능하다면 Angular API로 작업을 처리하세요.
당장 리팩토링할 수 없다면 하이드레이션과 호환되는 방식으로 고칠 때까지 `ngSkipHydration` 어트리뷰트를 사용하세요([아래 설명](#how-to-skip-hydration-for-particular-components)).

### 유효한 HTML 구조

<!--
There are a few cases where if you have a component template that does not have valid HTML structure, this could result in a DOM mismatch error during hydration.

As an example, here are some of the most common cases of this issue.

- `<table>` without a `<tbody>`
- `<div>` inside a `<p>`
- `<a>` inside another `<a>`

If you are uncertain about whether your HTML is valid, you can use a [syntax validator](https://validator.w3.org/) to check it.

NOTE: While the HTML standard does not require the `<tbody>` element inside tables, modern browsers automatically create a `<tbody>` element in tables that do not declare one. Because of this inconsistency, always explicitly declare a `<tbody>` element in tables to avoid hydration errors.
-->

컴포넌트 템플릿의 HTML 구조가 유효하지 않으면 하이드레이션 중 DOM 불일치 오류가 발생할 수 있습니다.

흔히 발생하는 예는 다음과 같습니다.

- `<tbody>`가 없는 `<table>`
- `<p>` 안의 `<div>`
- 다른 `<a>` 안의 `<a>`

HTML이 유효한지 확실하지 않다면 [문법 검사기](https://validator.w3.org/)로 확인할 수 있습니다.

참고: HTML 표준에서는 테이블 안의 `<tbody>` 엘리먼트를 필수로 요구하지 않지만, 최신 브라우저는 선언되지 않은 `<tbody>`를 자동으로 만듭니다.
이 차이로 인한 하이드레이션 오류를 피하려면 테이블에 항상 `<tbody>` 엘리먼트를 명시적으로 선언하세요.

### 공백 보존 설정

<!--
When using the hydration feature, we recommend using the default setting of `false` for `preserveWhitespaces`. If this setting is not in your tsconfig, the value will be `false` and no changes are required. If you choose to enable preserving whitespaces by adding `preserveWhitespaces: true` to your tsconfig, it is possible you may encounter issues with hydration. This is not yet a fully supported configuration.

HELPFUL: Make sure that this setting is set **consistently** in `tsconfig.server.json` for your server and `tsconfig.app.json` for your browser builds. A mismatched value will cause hydration to break.

If you choose to set this setting in your tsconfig, we recommend to set it only in `tsconfig.app.json` which by default the `tsconfig.server.json` will inherit it from.
-->

하이드레이션 기능을 사용할 때는 `preserveWhitespaces`를 기본값인 `false`로 사용하는 것을 권장합니다.
tsconfig에 이 설정이 없다면 값은 `false`이므로 변경할 필요가 없습니다.
tsconfig에 `preserveWhitespaces: true`를 추가해서 공백 보존을 활성화하면 하이드레이션 문제가 발생할 수 있습니다.
이 설정은 아직 완전히 지원되지 않습니다.

도움말: 서버 빌드의 `tsconfig.server.json`과 브라우저 빌드의 `tsconfig.app.json`에서 이 설정이 **일치하는지** 확인하세요.
값이 다르면 하이드레이션이 제대로 동작하지 않습니다.

tsconfig에 이 설정을 지정하려면 `tsconfig.app.json`에만 지정하는 것을 권장합니다.
기본적으로 `tsconfig.server.json`은 이 파일의 설정을 상속합니다.

### 커스텀 또는 Noop Zone.js는 아직 지원되지 않습니다

<!--
Hydration relies on a signal from Zone.js when it becomes stable inside an application, so that Angular can start the serialization process on the server or post-hydration cleanup on the client to remove DOM nodes that remained unclaimed.

Providing a custom or a "noop" Zone.js implementation may lead to a different timing of the "stable" event, thus triggering the serialization or the cleanup too early or too late. This is not yet a fully supported configuration and you may need to adjust the timing of the `onStable` event in the custom Zone.js implementation.
-->

하이드레이션은 애플리케이션이 안정 상태에 도달했을 때 Zone.js가 보내는 신호에 의존합니다.
이 신호를 받으면 Angular는 서버에서 직렬화를 시작하거나, 클라이언트에서 하이드레이션 후 정리 작업을 수행해서 연결되지 않은 DOM 노드를 제거합니다.

커스텀 또는 "noop" Zone.js 구현을 제공하면 "stable" 이벤트의 시점이 달라져 직렬화나 정리 작업이 너무 이르거나 늦게 실행될 수 있습니다.
이 구성은 아직 완전히 지원되지 않으며, 커스텀 Zone.js 구현에서 `onStable` 이벤트의 시점을 조정해야 할 수 있습니다.

## 오류

<!--
There are several hydration related errors you may encounter ranging from node mismatches to cases when the `ngSkipHydration` was used on an invalid host node. The most common error case that may occur is due to direct DOM manipulation using native APIs that results in hydration being unable to find or match the expected DOM tree structure on the client that was rendered by the server. The other case where you may encounter this type of error was mentioned in the [Valid HTML structure](#valid-html-structure) section earlier. So, make sure the HTML in your templates is using valid structure, and you'll avoid that error case.

For a full reference on hydration related errors, visit the [Errors Reference Guide](/errors).
-->

노드 불일치부터 잘못된 호스트 노드에 `ngSkipHydration`을 사용한 경우까지 여러 하이드레이션 오류가 발생할 수 있습니다.
가장 흔한 오류는 네이티브 API로 DOM을 직접 조작한 결과, 서버에서 렌더링한 예상 DOM 트리 구조를 클라이언트에서 찾거나 일치시키지 못하는 경우입니다.
이와 같은 오류가 발생할 수 있는 또 다른 경우는 앞서 [유효한 HTML 구조](#valid-html-structure) 절에서 설명했습니다.
템플릿의 HTML 구조가 유효한지 확인하면 이 오류를 피할 수 있습니다.

하이드레이션 관련 오류의 전체 설명은 [오류 레퍼런스 가이드](/errors)를 참고하세요.

## 특정 컴포넌트에서 하이드레이션 건너뛰기

<!--
Some components may not work properly with hydration enabled due to some of the aforementioned issues, like [Direct DOM Manipulation](#direct-dom-manipulation). As a workaround, you can add the `ngSkipHydration` attribute to a component's tag in order to skip hydrating the entire component.

```html
<app-example ngSkipHydration />
```

Alternatively you can set `ngSkipHydration` as a host binding.

```typescript
@Component({
  ...
  host: {ngSkipHydration: 'true'},
})
class ExampleComponent {}
```

The `ngSkipHydration` attribute will force Angular to skip hydrating the entire component and its children. Using this attribute means that the component will behave as if hydration is not enabled, meaning it will destroy and re-render itself.

HELPFUL: This will fix rendering issues, but it means that for this component (and its children), you don't get the benefits of hydration. You will need to adjust your component's implementation to avoid hydration-breaking patterns (i.e. Direct DOM Manipulation) to be able to remove the skip hydration annotation.

The `ngSkipHydration` attribute can only be used on component host nodes. Angular throws an error if this attribute is added to other nodes.

Keep in mind that adding the `ngSkipHydration` attribute to your root application component would effectively disable hydration for your entire application. Be careful and thoughtful about using this attribute. It is intended as a last resort workaround. Components that break hydration should be considered bugs that need to be fixed.
-->

일부 컴포넌트는 [DOM 직접 조작](#direct-dom-manipulation)처럼 앞서 설명한 문제 때문에 하이드레이션을 활성화하면 제대로 동작하지 않을 수 있습니다.
임시 해결책으로 컴포넌트 태그에 `ngSkipHydration` 어트리뷰트를 추가해서 컴포넌트 전체의 하이드레이션을 건너뛸 수 있습니다.

```html
<app-example ngSkipHydration />
```

또는 `ngSkipHydration`을 호스트 바인딩으로 설정할 수 있습니다.

```typescript
@Component({
  ...
  host: {ngSkipHydration: 'true'},
})
class ExampleComponent {}
```

`ngSkipHydration` 어트리뷰트는 Angular가 해당 컴포넌트 전체와 자식의 하이드레이션을 건너뛰도록 합니다.
이 어트리뷰트를 사용하면 컴포넌트는 하이드레이션이 활성화되지 않은 것처럼 동작하므로, 기존 내용을 파괴하고 다시 렌더링합니다.

도움말: 렌더링 문제는 해결되지만 해당 컴포넌트와 자식은 하이드레이션의 이점을 얻을 수 없습니다.
하이드레이션을 건너뛰는 표시를 제거하려면 DOM 직접 조작처럼 하이드레이션을 방해하는 패턴을 피하도록 컴포넌트 구현을 수정해야 합니다.

`ngSkipHydration` 어트리뷰트는 컴포넌트 호스트 노드에만 사용할 수 있습니다.
다른 노드에 추가하면 Angular가 오류를 발생시킵니다.

루트 애플리케이션 컴포넌트에 `ngSkipHydration` 어트리뷰트를 추가하면 사실상 애플리케이션 전체의 하이드레이션이 비활성화됩니다.
이 어트리뷰트는 신중하게 사용하세요.
다른 방법이 없을 때 사용하는 임시 해결책이며, 하이드레이션을 방해하는 컴포넌트는 수정해야 할 버그로 봐야 합니다.

## 하이드레이션 시점과 애플리케이션 안정 상태

애플리케이션의 안정 상태는 하이드레이션 과정에서 중요한 역할을 합니다.
하이드레이션과 그 이후의 처리는 애플리케이션이 안정 상태를 알린 뒤에만 실행됩니다.
타임아웃과 인터벌, 완료되지 않은 Promise, 대기 중인 마이크로태스크 등 여러 요인으로 안정 상태에 도달하는 시점이 늦어질 수 있습니다.
이런 경우 10초가 지나도 애플리케이션이 안정 상태에 도달하지 않았음을 나타내는 [Application remains unstable](errors/NG0506) 오류가 발생할 수 있습니다.
애플리케이션이 바로 하이드레이션되지 않는다면 안정 상태에 영향을 주는 요인을 확인하고, 이런 지연을 피하도록 리팩토링하세요.

### 애플리케이션 안정 상태 디버깅하기

<!--
The `provideStabilityDebugging` utility helps identify why your application fails to stabilize. This utility is provided by default in dev mode when using `provideClientHydration`. You can also add it manually to the application providers for use in production bundles or when using SSR without hydration, for example. The feature logs information to the console if the application takes longer than expected to stabilize.

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

When enabled, the utility logs pending tasks (`PendingTasks`) to the console. If your application uses Zone.js, you can also import `zone.js/plugins/task-tracking` to see which macrotasks are keeping the Angular Zone from stabilizing. This plugin provides the stack trace of the macrotask creation, effectively helping you identify the source of the delay.

IMPORTANT: Angular does not remove the zone.js task tracking plugin or this utility from production bundles. Use them only for temporary debugging of stability issues during development, including for optimized production builds.
-->

`provideStabilityDebugging` 유틸리티는 애플리케이션이 안정 상태에 도달하지 못하는 이유를 찾는 데 도움이 됩니다.
`provideClientHydration`을 사용하면 개발 모드에서 이 유틸리티가 기본으로 제공됩니다.
프로덕션 번들에서 사용하거나 하이드레이션 없이 SSR을 사용하는 경우 등에는 애플리케이션 프로바이더에 직접 추가할 수도 있습니다.
애플리케이션이 예상보다 오래 걸려 안정 상태에 도달하면 콘솔에 정보를 기록합니다.

```typescript
import {provideStabilityDebugging} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';
import 'zone.js/plugins/task-tracking'; // `provideZoneChangeDetection`과 함께 Zone.js를 사용하는 경우 추가합니다.

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

이 유틸리티를 활성화하면 대기 중인 작업(`PendingTasks`)이 콘솔에 기록됩니다.
애플리케이션이 Zone.js를 사용한다면 `zone.js/plugins/task-tracking`을 가져와 Angular Zone이 안정 상태에 도달하지 못하게 하는 매크로태스크도 확인할 수 있습니다.
이 플러그인은 매크로태스크가 생성된 시점의 스택 트레이스를 제공하므로 지연 원인을 찾는 데 도움이 됩니다.

중요: Angular는 프로덕션 번들에서 zone.js 작업 추적 플러그인이나 이 유틸리티를 제거하지 않습니다.
최적화된 프로덕션 빌드를 점검하는 경우를 포함해, 개발 중 안정 상태 문제를 일시적으로 디버깅하는 용도로만 사용하세요.

## 국제화(I18N)

<!--
HELPFUL: By default, Angular will skip hydration for components that use i18n blocks, effectively re-rendering those components from scratch.

To enable hydration for i18n blocks, you can add [`withI18nSupport`](/api/platform-browser/withI18nSupport) to your `provideClientHydration` call.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withI18nSupport,
} from '@angular/platform-browser';
...

bootstrapApplication(App, {
  providers: [provideClientHydration(withI18nSupport())]
});
```
-->

도움말: 기본적으로 Angular는 i18n 블록을 사용하는 컴포넌트의 하이드레이션을 건너뛰고 처음부터 다시 렌더링합니다.

i18n 블록의 하이드레이션을 활성화하려면 `provideClientHydration` 호출에 [`withI18nSupport`](/api/platform-browser/withI18nSupport)를 추가하세요.

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withI18nSupport,
} from '@angular/platform-browser';
...

bootstrapApplication(App, {
  providers: [provideClientHydration(withI18nSupport())]
});
```

## 서버와 클라이언트에서 일관되게 렌더링하기

Angular의 `isPlatformBrowser` 함수와 `@if` 블록을 함께 사용하는 방식처럼, 서버 사이드 렌더링과 클라이언트 사이드 렌더링에서 서로 다른 콘텐츠를 표시하는 `@if` 블록이나 조건문은 피하세요.
이런 렌더링 차이는 레이아웃 이동을 일으켜 최종 사용자 경험과 코어 웹 바이탈에 악영향을 줍니다.

## DOM을 조작하는 서드 파티 라이브러리

렌더링을 위해 DOM 조작에 의존하는 서드 파티 라이브러리가 여럿 있습니다.
D3 차트가 대표적인 예입니다.
이런 라이브러리는 하이드레이션이 없을 때는 동작하지만, 하이드레이션을 활성화하면 DOM 불일치 오류를 일으킬 수 있습니다.
현재로서는 이런 라이브러리를 사용하다 DOM 불일치 오류가 발생하면 해당 라이브러리로 렌더링하는 컴포넌트에 `ngSkipHydration` 어트리뷰트를 추가할 수 있습니다.

## DOM을 조작하는 서드 파티 스크립트

광고 추적기나 분석 도구 같은 많은 서드 파티 스크립트는 하이드레이션이 실행되기 전에 DOM을 수정합니다.
그러면 페이지가 Angular에서 예상하는 구조와 달라지므로 하이드레이션 오류가 발생할 수 있습니다.
가능하다면 이런 스크립트는 하이드레이션 이후로 실행을 미루세요.
[`AfterNextRender`](api/core/afterNextRender)를 사용해서 하이드레이션 후 처리가 끝날 때까지 스크립트 실행을 미루는 방법도 고려할 수 있습니다.

### CDN과 브라우저 확장 프로그램

애플리케이션 외부의 코드가 하이드레이션을 시작하기 전에 서버에서 받은 HTML을 변경할 수 있습니다.
이런 오류는 로컬 서버에서 발생하지 않기 때문에 개발자의 컴퓨터에서는 확인하기 어려운 경우가 많습니다.

**HTML을 변경하는 CDN.** 일부 CDN 기능은 HTML이 브라우저에 전달되는 도중에 내용을 변경합니다.
예를 들어, 하이드레이션에 필요한 주석 노드와 공백을 제거하는 기능이 있습니다.
Cloudflare에서 기본으로 활성화되는 이메일 주소 난독화(Email Address Obfuscation)도 그 예입니다.
이 기능은 이메일 주소를 `<span class="__cf_email__" data-cfemail="...">` 같은 엘리먼트로 바꿉니다.
또한 `mailto:` 링크를 변경하고 내용을 원래대로 되돌리는 스크립트를 추가합니다.
하이드레이션이 시작되기 전에 이 스크립트가 실행되지 않으면 Angular는 텍스트가 있어야 할 위치에서 엘리먼트를 발견합니다.
로컬 서버는 CDN을 사용하지 않으므로 애플리케이션은 개발자의 컴퓨터에서는 동작하고 프로덕션에서만 실패합니다.

**브라우저 확장 프로그램.** 일부 브라우저 확장 프로그램은 하이드레이션이 시작되기 전에 페이지를 변경합니다.
클릭하여 전화 걸기 도구, 번역기, 비밀번호 관리자 등이 그 예입니다.
이런 확장 프로그램은 애플리케이션에서 제어할 수 없습니다.
설치한 사용자에게만 문제가 발생하므로 일부 사용자에게서만 오류가 보고될 수 있습니다.

이런 오류를 해결하려면 다음과 같이 하세요:

- 변경되는 콘텐츠를 감싸는 컴포넌트 호스트에 `ngSkipHydration`을 추가하세요.
  해당 콘텐츠를 작성하는 템플릿에 `<app-contact ngSkipHydration><a href="tel:...">...</a></app-contact>`처럼 추가하세요.
  그러면 Angular가 브라우저에서 이 콘텐츠를 다시 렌더링하여 외부에서 변경한 내용을 제거합니다.
  이 어트리뷰트는 컴포넌트 호스트 엘리먼트에만 사용할 수 있으므로 `<a>` 엘리먼트에는 추가할 수 없습니다.
  자세한 내용은 [하이드레이션 건너뛰기](#how-to-skip-hydration-for-particular-components)를 참고하세요.
- 애플리케이션에서 해당 CDN 기능을 끄세요.
  Cloudflare에서는 보안 설정에서 [이메일 주소 난독화](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/)를 끄거나, [구성 규칙](https://developers.cloudflare.com/rules/configuration-rules/settings/)을 사용하여 애플리케이션의 호스트 이름에 대해 이 기능을 끄세요.

` comments from Cloudflare don't help in Angular templates, because the compiler removes comments from templates.
-->

참고: Angular 컴파일러는 템플릿에서 주석을 제거하므로 Cloudflare의 `` 주석은 Angular 템플릿에서 도움이 되지 않습니다.

## 점진적 하이드레이션

점진적 하이드레이션은 하이드레이션 시점을 더 세밀하게 제어하는 고급 하이드레이션 방식입니다.
자세한 내용은 [점진적 하이드레이션 가이드](guide/incremental-hydration)를 참고하세요.

# 점진적 하이드레이션

**점진적 하이드레이션**은 애플리케이션의 일부 영역을 하이드레이션되지 않은 상태로 두었다가, 필요할 때 _점진적으로_ 하이드레이션하는 고급 [하이드레이션](guide/hydration) 방식입니다.

## 점진적 하이드레이션은 왜 사용하나요?

<!--
Incremental hydration is a performance improvement that builds on top of full application hydration. It can produce smaller initial bundles while still providing an end-user experience that is comparable to a full application hydration experience. Smaller bundles improve initial load times, reducing [First Input Delay (FID)](https://web.dev/fid) and [Cumulative Layout Shift (CLS)](https://web.dev/cls).

Incremental hydration also lets you use deferrable views (`@defer`) for content that may not have been deferrable before. Specifically, you can now use deferrable views for content that is above the fold. Prior to incremental hydration, putting a `@defer` block above the fold would result in placeholder content rendering and then being replaced by the `@defer` block's main template content. This would result in a layout shift. Incremental hydration means the main template of the `@defer` block will render with no layout shift on hydration.
-->

점진적 하이드레이션은 애플리케이션 전체 하이드레이션을 기반으로 성능을 개선하는 기능입니다.
애플리케이션 전체를 하이드레이션할 때와 비슷한 사용자 경험을 제공하면서 초기 번들 크기를 줄일 수 있습니다.
번들이 작아지면 초기 로드 시간이 개선되어 [최초 입력 지연(FID)](https://web.dev/fid)과 [누적 레이아웃 이동(CLS)](https://web.dev/cls)이 줄어듭니다.

점진적 하이드레이션을 사용하면 이전에는 지연하기 어려웠던 콘텐츠에도 지연 가능한 뷰(`@defer`)를 사용할 수 있습니다.
특히 스크롤하지 않아도 보이는 첫 화면의 콘텐츠에도 사용할 수 있습니다.
점진적 하이드레이션이 없을 때는 첫 화면에 `@defer` 블록을 두면 플레이스홀더가 먼저 렌더링된 뒤 `@defer` 블록의 메인 템플릿 콘텐츠로 바뀌면서 레이아웃 이동이 발생했습니다.
점진적 하이드레이션을 사용하면 `@defer` 블록의 메인 템플릿을 렌더링하고 하이드레이션할 때 레이아웃이 이동하지 않습니다.

## Angular에서 점진적 하이드레이션 활성화하기

<!--
You can enable incremental hydration for applications that already use server-side rendering (SSR) with hydration. Follow the [Angular SSR Guide](guide/ssr) to enable server-side rendering and the [Angular Hydration Guide](guide/hydration) to enable hydration first.

Incremental hydration is enabled by default when you use `provideClientHydration()`.

```ts
import {bootstrapApplication, provideClientHydration} from '@angular/platform-browser';

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

NOTE: Incremental Hydration depends on and enables [event replay](guide/hydration#capturing-and-replaying-events) automatically. If you already have `withEventReplay()` in your list, you can safely remove it.

To opt out of incremental hydration, use `withNoIncrementalHydration()`:

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoIncrementalHydration,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoIncrementalHydration())],
});
```
-->

하이드레이션을 사용하는 서버 사이드 렌더링(SSR) 애플리케이션에서 점진적 하이드레이션을 활성화할 수 있습니다.
먼저 [Angular SSR 가이드](guide/ssr)에 따라 서버 사이드 렌더링을 활성화하고, [Angular 하이드레이션 가이드](guide/hydration)에 따라 하이드레이션을 활성화하세요.

`provideClientHydration()`을 사용하면 점진적 하이드레이션은 기본적으로 활성화됩니다.

```ts
import {bootstrapApplication, provideClientHydration} from '@angular/platform-browser';

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

참고: 점진적 하이드레이션은 [이벤트 재실행](guide/hydration#capturing-and-replaying-events)에 의존하며 이 기능을 자동으로 활성화합니다.
목록에 `withEventReplay()`가 이미 있다면 제거해도 됩니다.

점진적 하이드레이션을 비활성화하려면 `withNoIncrementalHydration()`을 사용하세요:

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoIncrementalHydration,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoIncrementalHydration())],
});
```

## 점진적 하이드레이션은 어떻게 동작하나요?

점진적 하이드레이션은 애플리케이션 전체 [하이드레이션](guide/hydration), [지연 가능한 뷰](/guide/templates/defer), [이벤트 재실행](guide/hydration#capturing-and-replaying-events)을 기반으로 동작합니다.
점진적 하이드레이션을 사용하면 `@defer` 블록에 추가 트리거를 지정해서 점진적 하이드레이션의 경계를 정의할 수 있습니다.
지연 블록에 `hydrate` 트리거를 추가하면 Angular는 서버 사이드 렌더링 중 해당 블록의 의존성을 로드하고 `@placeholder` 대신 메인 템플릿을 렌더링합니다.
클라이언트 사이드 렌더링에서는 의존성 로드를 계속 미루며, 블록의 콘텐츠는 `hydrate` 트리거가 실행될 때까지 하이드레이션되지 않은 상태로 남습니다.
트리거가 실행되면 지연 블록은 의존성을 가져오고 콘텐츠를 하이드레이션합니다.
하이드레이션 전에 사용자가 발생시킨 브라우저 이벤트 중 컴포넌트에 등록된 리스너와 일치하는 이벤트는 대기열에 저장되었다가 하이드레이션이 완료되면 재실행됩니다.

## 트리거로 콘텐츠 하이드레이션 제어하기

<!--
You can specify **hydrate triggers** that control when Angular loads and hydrates deferred content. These are additional triggers that can be used alongside regular `@defer` triggers.

Each `@defer` block may have multiple hydrate event triggers, separated with a semicolon (`;`). Angular triggers hydration when _any_ of the triggers fire.

There are three types of hydrate triggers: `hydrate on`, `hydrate when`, and `hydrate never`.
-->

**하이드레이션 트리거**를 지정하면 Angular가 지연된 콘텐츠를 로드하고 하이드레이션하는 시점을 제어할 수 있습니다.
일반 `@defer` 트리거와 함께 사용할 수 있는 추가 트리거입니다.

각 `@defer` 블록에는 세미콜론(`;`)으로 구분해서 하이드레이션 이벤트 트리거를 여러 개 지정할 수 있습니다.
이 중 _하나라도_ 실행되면 Angular가 하이드레이션을 시작합니다.

하이드레이션 트리거에는 `hydrate on`, `hydrate when`, `hydrate never` 세 가지 종류가 있습니다.

### `hydrate on`

<!--
`hydrate on` specifies a condition for when hydration is triggered for the `@defer` block.

The available triggers are as follows:

| Trigger                                             | Description                                                            |
| --------------------------------------------------- | ---------------------------------------------------------------------- |
| [`hydrate on idle`](#hydrate-on-idle)               | Triggers when the browser is idle. Supports an optional timeout.       |
| [`hydrate on viewport`](#hydrate-on-viewport)       | Triggers when specified content enters the viewport                    |
| [`hydrate on interaction`](#hydrate-on-interaction) | Triggers when the user interacts with specified element                |
| [`hydrate on hover`](#hydrate-on-hover)             | Triggers when the mouse hovers over specified area                     |
| [`hydrate on immediate`](#hydrate-on-immediate)     | Triggers immediately after non-deferred content has finished rendering |
| [`hydrate on timer`](#hydrate-on-timer)             | Triggers after a specific duration                                     |
-->

`hydrate on`은 `@defer` 블록의 하이드레이션이 실행될 조건을 지정합니다.

사용할 수 있는 트리거는 다음과 같습니다:

| 트리거                                              | 설명                                                                              |
| --------------------------------------------------- | --------------------------------------------------------------------------------- |
| [`hydrate on idle`](#hydrate-on-idle)               | 브라우저가 유휴 상태가 되면 실행합니다. 선택적으로 타임아웃을 지정할 수 있습니다. |
| [`hydrate on viewport`](#hydrate-on-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`

<!--
The `hydrate on idle` trigger loads the deferrable view's dependencies and hydrates the content once the browser has reached an idle state, based on `requestIdleCallback`.

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

<!- With a 500ms timeout ->
@defer (hydrate on idle(500)) {
  <large-cmp />
}
```
-->

`hydrate on idle` 트리거는 `requestIdleCallback`을 기준으로 브라우저가 유휴 상태에 도달하면 지연 가능한 뷰의 의존성을 로드하고 콘텐츠를 하이드레이션합니다.

[`requestIdleCallback`](https://developer.mozilla.org/docs/Web/API/Window/requestIdleCallback)에 전달할 타임아웃을 밀리초 단위로 지정할 수도 있습니다.
브라우저가 콜백을 충분히 빨리 실행하도록 예약하지 않더라도, 작업은 지정한 타임아웃 안에 실행됩니다.

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

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

#### `hydrate on viewport`

<!--
The `hydrate on viewport` trigger loads the deferrable view's dependencies and hydrates the corresponding page of the app when the specified content enters the viewport using the
[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 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`

<!--
The `hydrate on interaction` trigger loads the deferrable view's dependencies and hydrates the content when the user interacts with the specified element through
`click` or `keydown` events.

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

`hydrate on interaction` 트리거는 사용자가 지정한 엘리먼트에서 `click`이나 `keydown` 이벤트로 상호작용할 때 지연 가능한 뷰의 의존성을 로드하고 콘텐츠를 하이드레이션합니다.

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

#### `hydrate on hover`

<!--
The `hydrate on hover` trigger loads the deferrable view's dependencies and hydrates the content when the mouse has hovered over the triggered area through the
`mouseover` and `focusin` events.

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

`hydrate on hover` 트리거는 `mouseover`와 `focusin` 이벤트를 통해 지정한 영역에 마우스가 올라온 것을 감지하면 지연 가능한 뷰의 의존성을 로드하고 콘텐츠를 하이드레이션합니다.

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

#### `hydrate on immediate`

<!--
The `hydrate on immediate` trigger loads the deferrable view's dependencies and hydrates the content immediately. This means that the deferred block loads as soon
as all other non-deferred content has finished rendering.

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

`hydrate on immediate` 트리거는 지연 가능한 뷰의 의존성을 즉시 로드하고 콘텐츠를 하이드레이션합니다.
즉, 지연하지 않은 다른 모든 콘텐츠의 렌더링이 끝나는 즉시 지연 블록을 로드합니다.

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

#### `hydrate on timer`

<!--
The `hydrate on timer` trigger loads the deferrable view's dependencies and hydrates the content after a specified duration.

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

The duration parameter must be specified in milliseconds (`ms`) or seconds (`s`).
-->

`hydrate on timer` 트리거는 지정한 시간이 지나면 지연 가능한 뷰의 의존성을 로드하고 콘텐츠를 하이드레이션합니다.

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

시간 파라미터는 밀리초(`ms`) 또는 초(`s`) 단위로 지정해야 합니다.

### `hydrate when`

<!--
The `hydrate when` trigger accepts a custom conditional expression and loads the deferrable view's dependencies and hydrates the content when the
condition becomes truthy.

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

NOTE: `hydrate when` conditions only trigger when they are the top-most dehydrated `@defer` block. The condition provided for the trigger is
specified in the parent component, which needs to exist before it can be triggered. If the parent block is dehydrated, that expression will not yet
be resolvable by Angular.
-->

`hydrate when` 트리거는 커스텀 조건 표현식을 받아, 조건이 참으로 평가되는 값(truthy)이 되면 지연 가능한 뷰의 의존성을 로드하고 콘텐츠를 하이드레이션합니다.

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

참고: `hydrate when` 조건은 해당 블록이 하이드레이션되지 않은 최상위 `@defer` 블록일 때만 실행됩니다.
트리거의 조건은 부모 컴포넌트에 지정되므로, 실행하려면 부모 컴포넌트가 먼저 존재해야 합니다.
부모 블록이 하이드레이션되지 않았다면 Angular는 아직 해당 표현식을 평가할 수 없습니다.

### `hydrate never`

<!--
The `hydrate never` allows users to specify that the content in the defer block should remain dehydrated indefinitely, effectively becoming static
content. Note that this applies to the initial render only. During a subsequent client-side render, a `@defer` block with `hydrate never` would
still fetch dependencies, as hydration only applies to initial load of server-side rendered content. In the example below, subsequent client-side
renders would load the `@defer` block dependencies on viewport.

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

NOTE: Using `hydrate never` prevents hydration of the entire nested subtree of a given `@defer` block. No other `hydrate` triggers fire for content nested underneath that block.
-->

`hydrate never`를 사용하면 지연 블록의 콘텐츠를 계속 하이드레이션되지 않은 상태로 두어 사실상 정적 콘텐츠로 만들 수 있습니다.
다만 초기 렌더링에만 적용됩니다.
하이드레이션은 서버에서 렌더링한 콘텐츠를 처음 로드할 때만 적용되므로, 이후 클라이언트 사이드 렌더링에서는 `hydrate never`가 지정된 `@defer` 블록도 의존성을 가져옵니다.
아래 예제에서 이후 클라이언트 사이드 렌더링은 블록이 뷰포트에 들어올 때 `@defer` 블록의 의존성을 로드합니다.

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

참고: `hydrate never`를 사용하면 해당 `@defer` 블록에 중첩된 하위 트리 전체가 하이드레이션되지 않습니다.
이 블록 아래에 중첩된 콘텐츠의 다른 `hydrate` 트리거도 실행되지 않습니다.

## 일반 트리거와 하이드레이션 트리거 함께 사용하기

<!--
Hydrate triggers are additional triggers that are used alongside regular triggers on a `@defer` block. Hydration is an initial load optimization, and that means hydrate triggers only apply to that initial load. Any subsequent client side render will still use the regular trigger.

```html
@defer (on idle; hydrate on interaction) {
  <example-cmp />
} @placeholder {
  <div>Example Placeholder</div>
}
```

In this example, on the initial load, the `hydrate on interaction` applies. Hydration will be triggered on interaction with the `<example-cmp />` component. On any subsequent page load that is client-side rendered, for example when a user clicks a routerLink that loads a page with this component, the `on idle` will apply.
-->

하이드레이션 트리거는 `@defer` 블록의 일반 트리거와 함께 사용하는 추가 트리거입니다.
하이드레이션은 초기 로드를 최적화하는 기능이므로 하이드레이션 트리거도 초기 로드에만 적용됩니다.
이후의 클라이언트 사이드 렌더링은 일반 트리거를 사용합니다.

```html
@defer (on idle; hydrate on interaction) {
  <example-cmp />
} @placeholder {
  <div>Example Placeholder</div>
}
```

이 예제에서는 처음 로드할 때 `hydrate on interaction`이 적용됩니다.
`<example-cmp />` 컴포넌트와 상호작용하면 하이드레이션이 실행됩니다.
이후 사용자가 이 컴포넌트가 있는 페이지로 이동하는 routerLink를 클릭하는 등 클라이언트에서 렌더링하는 페이지 로드에는 `on idle`이 적용됩니다.

## 중첩된 `@defer` 블록에서 점진적 하이드레이션은 어떻게 동작하나요?

<!--
Angular's component and dependency system is hierarchical, which means hydrating any component requires all of its parents also be hydrated. So if hydration is triggered for a child `@defer` block of a nested set of dehydrated `@defer` blocks, hydration is triggered from the top-most dehydrated `@defer` block down to the triggered child and fire in that order.

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

In the above example, hovering over the nested `@defer` block triggers hydration. The parent `@defer` block with the `<parent-block-cmp />` hydrates first, then the child `@defer` block with `<child-block-cmp />` hydrates after.
-->

Angular의 컴포넌트와 의존성 시스템은 계층 구조이므로, 어떤 컴포넌트를 하이드레이션하려면 모든 부모도 하이드레이션되어야 합니다.
따라서 하이드레이션되지 않은 `@defer` 블록이 중첩된 상태에서 자식 `@defer` 블록의 하이드레이션이 실행되면, 하이드레이션되지 않은 최상위 `@defer` 블록부터 해당 자식까지 순서대로 하이드레이션됩니다.

위 예제에서는 중첩된 `@defer` 블록 위에 마우스를 올리면 하이드레이션이 실행됩니다.
`<parent-block-cmp />`가 있는 부모 `@defer` 블록이 먼저 하이드레이션되고, 그다음 `<child-block-cmp />`가 있는 자식 `@defer` 블록이 하이드레이션됩니다.

## 제약 사항

점진적 하이드레이션에는 DOM 직접 조작 제한과 유효한 HTML 구조 요구 사항 등 애플리케이션 전체 하이드레이션과 같은 제약이 있습니다.
자세한 내용은 [하이드레이션 가이드의 제약 사항](guide/hydration#constraints)을 참고하세요.

## `@placeholder` 블록도 여전히 필요한가요?

네.
`@placeholder` 블록의 콘텐츠는 점진적 하이드레이션에 사용되지 않지만, 이후의 클라이언트 사이드 렌더링에는 `@placeholder`가 여전히 필요합니다.
콘텐츠가 초기 로드에 포함된 라우팅 규칙에 없었다면, 나중에 해당 `@defer` 블록 콘텐츠가 있는 라우팅 규칙으로 이동할 때는 일반 `@defer` 블록처럼 렌더링됩니다.
따라서 이런 클라이언트 사이드 렌더링에서는 `@placeholder`가 렌더링됩니다.

# 단위 테스트

<!--
Testing your Angular application helps you check that it is working as you expect. Unit tests are crucial for catching bugs early, ensuring code quality, and facilitating safe refactoring.

NOTE: This guide covers the default testing setup for new Angular CLI projects, which uses Vitest. If you are migrating an existing project from Karma, see the [Migrating from Karma to Vitest guide](guide/testing/migrating-to-vitest). Karma is still supported; for more information, see the [Karma testing guide](guide/testing/karma).
-->

Angular 애플리케이션을 테스트하면 예상대로 동작하는지 확인할 수 있습니다.
단위 테스트는 버그를 일찍 발견하고 코드 품질을 유지하며 안전하게 리팩토링하는 데 중요합니다.

참고: 이 문서는 새 Angular CLI 프로젝트의 기본 테스트 환경인 Vitest를 설명합니다.
기존 프로젝트를 Karma에서 이전하려면 [Karma에서 Vitest로 이전하기](guide/testing/migrating-to-vitest)를 참고하세요.
Karma도 계속 지원합니다.
자세한 내용은 [Karma 테스트](guide/testing/karma) 문서를 참고하세요.

## 테스트 환경 설정하기

<!--
The Angular CLI downloads and installs everything you need to test an Angular application with the [Vitest testing framework](https://vitest.dev). New projects include `vitest` and `jsdom` by default.

Vitest runs your unit tests in a Node.js environment. To simulate the browser's DOM, Vitest uses a library called `jsdom`. This allows for faster test execution by avoiding the overhead of launching a browser. You can swap `jsdom` for an alternative like `happy-dom` by installing it and uninstalling `jsdom`. Currently, `jsdom` and `happy-dom` are the supported DOM emulation libraries.

The project you create with the CLI is immediately ready to test. Run the [`ng test`](cli/test) command:

```shell
ng test
```

The `ng test` command builds the application in _watch mode_ and launches the [Vitest test runner](https://vitest.dev).

The console output looks like this:

```shell
✓ src/app/app.spec.ts (2)
   ✓ App should create the app
   ✓ App should render title
 Test Files  1 passed (1)
      Tests  2 passed (2)
   Start at  18:18:01
   Duration  2.46s (transform 615ms, setup 2ms, collect 2.21s, tests 5ms)
```

The `ng test` command also watches your files for changes. If you modify a file and save it, the tests will run again.
-->

Angular CLI는 [Vitest 테스트 프레임워크](https://vitest.dev)로 Angular 애플리케이션을 테스트하는 데 필요한 모든 항목을 내려받아 설치합니다.
새 프로젝트에는 기본으로 `vitest`와 `jsdom`이 포함됩니다.

Vitest는 Node.js 환경에서 단위 테스트를 실행합니다.
브라우저 DOM은 `jsdom` 라이브러리로 재현합니다.
브라우저를 실행하는 데 드는 부담을 줄여 테스트를 더 빠르게 실행할 수 있습니다.
`happy-dom`과 같은 대안을 설치하고 `jsdom`을 제거하면 라이브러리를 교체할 수 있습니다.
현재 지원하는 DOM 에뮬레이션 라이브러리는 `jsdom`과 `happy-dom`입니다.

CLI로 생성한 프로젝트는 바로 테스트할 수 있습니다.
[`ng test`](cli/test) 명령을 실행하세요.

```shell
ng test
```

`ng test` 명령은 애플리케이션을 _파일 감시 모드_ 로 빌드하고 [Vitest 테스트 러너](https://vitest.dev)를 실행합니다.

콘솔에는 다음과 같이 출력됩니다.

`ng test` 명령은 파일 변경도 감시합니다.
파일을 수정하고 저장하면 테스트가 다시 실행됩니다.

## 환경 설정

Angular CLI가 Vitest 설정 대부분을 처리합니다.
`angular.json` 파일의 `test` 대상 옵션을 수정하면 테스트 동작을 변경할 수 있습니다.

### Angular.json 옵션

- `include`: 테스트에 포함할 파일의 glob 패턴입니다.
  기본값은 `['**/*.spec.ts', '**/*.test.ts']`입니다.
- `exclude`: 테스트에서 제외할 파일의 glob 패턴입니다.
- `setupFiles`: 테스트 전에 실행할 전역 설정 파일의 경로 목록입니다.
  폴리필이나 전역 목 등을 설정할 수 있습니다.
- `providersFile`: 테스트 환경에서 사용할 Angular 프로바이더 배열을 기본으로 내보내는 파일의 경로입니다.
  테스트에 주입할 전역 테스트 프로바이더를 설정할 때 유용합니다.
- `coverage`: 코드 커버리지 보고서를 활성화하거나 비활성화하는 불리언 값입니다.
  기본값은 `false`입니다.
- `browsers`: 실제 브라우저에서 테스트를 실행할 때 사용할 브라우저 이름 배열입니다.
  예를 들어 `["chromium"]`을 지정합니다.
  브라우저 프로바이더가 설치되어 있어야 합니다.
  자세한 내용은 [브라우저에서 테스트 실행하기](#running-tests-in-a-browser)를 참고하세요.

### 전역 테스트 설정과 프로바이더

<!--
The `setupFiles` and `providersFile` options are particularly useful for managing global test configuration.

For example, you could create a `src/test-providers.ts` file to provide `provideHttpClientTesting` to all your tests:

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

You would then reference this file in your `angular.json`:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "providersFile": "src/test-providers.ts"
          }
        }
      }
    }
  }
}
```

HELPFUL: When creating new TypeScript files for test setup or providers, like `src/test-providers.ts`, ensure they are included in your project's test TypeScript configuration file (typically `tsconfig.spec.json`). This allows the TypeScript compiler to properly process these files during testing.
-->

`setupFiles`와 `providersFile` 옵션은 전역 테스트 설정을 관리할 때 특히 유용합니다.

예를 들어 모든 테스트에 `provideHttpClientTesting`을 제공하려면 `src/test-providers.ts` 파일을 만들 수 있습니다.

```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`에서 이 파일을 참조합니다.

참고: `src/test-providers.ts`처럼 테스트 설정이나 프로바이더용 TypeScript 파일을 새로 만들 때는 프로젝트의 테스트용 TypeScript 설정 파일(일반적으로 `tsconfig.spec.json`)에 포함해야 합니다.
그래야 테스트할 때 TypeScript 컴파일러가 이 파일을 올바르게 처리할 수 있습니다.

### Vitest 고급 설정

<!--
For advanced use cases, you can provide a custom Vitest configuration file using the `runnerConfig` option in `angular.json`.

IMPORTANT: While using a custom configuration enables advanced options, the Angular team does not provide support for the contents of the configuration file or for any third-party plugins. The CLI will also override certain properties (`test.projects`, `test.include`) to ensure proper integration.

You can create a Vitest configuration file (e.g., `vitest-base.config.ts`) and reference it in your `angular.json`:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "runnerConfig": "vitest-base.config.ts"
          }
        }
      }
    }
  }
}
```

You can also generate a base configuration file using the CLI:

```shell
ng generate config vitest
```

This creates a `vitest-base.config.ts` file that you can customize.

HELPFUL: Read more about Vitest configuration in the [official Vitest documentation](https://vitest.dev/config/).
-->

고급 설정이 필요하면 `angular.json`의 `runnerConfig` 옵션으로 커스텀 Vitest 설정 파일을 제공할 수 있습니다.

중요: 커스텀 설정으로 고급 옵션을 사용할 수 있지만, Angular 팀은 설정 파일의 내용이나 서드 파티 플러그인을 지원하지 않습니다.
또한 CLI는 올바르게 통합하기 위해 일부 프로퍼티(`test.projects`, `test.include`)를 덮어씁니다.

Vitest 설정 파일(예: `vitest-base.config.ts`)을 만들고 `angular.json`에서 참조하세요.

CLI로 기본 설정 파일을 생성할 수도 있습니다.

```shell
ng generate config vitest
```

수정해서 사용할 수 있는 `vitest-base.config.ts` 파일이 생성됩니다.

참고: Vitest 설정에 대한 자세한 내용은 [공식 Vitest 문서](https://vitest.dev/config/)를 참고하세요.

## 코드 커버리지

<!--
You can generate a code coverage report by adding the `--coverage` flag to the `ng test` command. The report is generated in the `coverage/` directory.

For more detailed information, see the [Code coverage guide](guide/testing/code-coverage).
-->

`ng test` 명령에 `--coverage` 플래그를 추가하면 코드 커버리지 보고서를 생성할 수 있습니다.
보고서는 `coverage/` 디렉터리에 생성됩니다.

자세한 내용은 [코드 커버리지](guide/testing/code-coverage) 문서를 참고하세요.

## 브라우저에서 테스트 실행하기

<!--
While the default Node.js environment is faster for most unit tests, you can also run your tests in a real browser. This is useful for tests that rely on browser-specific APIs (like rendering) or for debugging.

To run tests in a browser, you must first install a browser provider. Read more about Vitest's browser mode in the [official documentation](https://vitest.dev/guide/browser).

Once the provider is installed, you can run your tests in the browser by configuring the `browsers` option in `angular.json` or by using the `--browsers` CLI flag. Tests run in a headed browser by default. If the `CI` environment variable is set, headless mode is used instead. To explicitly control headless mode, you can suffix the browser name with `Headless` (e.g., `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
```

Choose one of the following browser providers based on your needs:
-->

대부분의 단위 테스트는 기본 Node.js 환경에서 더 빠르게 실행되지만, 실제 브라우저에서 실행할 수도 있습니다.
렌더링처럼 브라우저 전용 API에 의존하는 테스트나 디버깅에 유용합니다.

브라우저에서 테스트를 실행하려면 먼저 브라우저 프로바이더를 설치해야 합니다.
Vitest의 브라우저 모드는 [공식 문서](https://vitest.dev/guide/browser)를 참고하세요.

프로바이더를 설치한 후 `angular.json`에 `browsers` 옵션을 설정하거나 CLI의 `--browsers` 플래그를 사용하면 브라우저에서 테스트를 실행할 수 있습니다.
기본으로 브라우저 창이 표시됩니다.
`CI` 환경 변수가 설정되어 있으면 헤드리스 모드를 사용합니다.
헤드리스 모드를 명시하려면 브라우저 이름 뒤에 `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
```

필요에 맞게 다음 브라우저 프로바이더 중 하나를 선택하세요.

### Playwright

<!--
[Playwright](https://playwright.dev/) is a browser automation library that supports Chromium, Firefox, and 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
```

-->

[Playwright](https://playwright.dev/)는 Chromium, Firefox, WebKit을 지원하는 브라우저 자동화 라이브러리입니다.

<!--
[WebdriverIO](https://webdriver.io/) is a browser and mobile automation test framework that supports Chrome, Firefox, Safari, and 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
```

-->

[WebdriverIO](https://webdriver.io/)는 Chrome, Firefox, Safari, Edge를 지원하는 브라우저 및 모바일 자동화 테스트 프레임워크입니다.

<!--
The `@vitest/browser-preview` provider is designed for WebContainer environments like StackBlitz and is not intended for use in 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: For more advanced browser-specific configuration, see the [Advanced Vitest configuration](#advanced-vitest-configuration) section.
-->

`@vitest/browser-preview` 프로바이더는 StackBlitz와 같은 WebContainer 환경용이며, 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
```
참고: 브라우저별 고급 설정은 [Vitest 고급 설정](#advanced-vitest-configuration)을 참고하세요.

## 다른 테스트 프레임워크

다른 테스트 라이브러리와 테스트 러너로도 Angular 애플리케이션의 단위 테스트를 실행할 수 있습니다.
각 라이브러리와 러너마다 설치 방법, 설정, 문법이 다릅니다.

## 지속적 통합 환경에서 테스트하기

<!--
A robust test suite is a key part of a continuous integration (CI) pipeline. CI servers let you automate your tests to run on every commit and pull request.

To test your Angular application in a CI server, run the standard test command:

```shell
ng test
```

Most CI servers set a `CI=true` environment variable, which `ng test` detects. This automatically configures your tests to run in a non-interactive, single-run mode.

If your CI server does not set this variable, or if you need to force single-run mode manually, you can use the `--no-watch` and `--no-progress` flags:

```shell
ng test --no-watch --no-progress
```
-->

견고한 테스트 모음은 지속적 통합(CI) 파이프라인의 핵심 요소입니다.
CI 서버를 사용하면 커밋과 풀 리퀘스트마다 테스트를 자동으로 실행할 수 있습니다.

CI 서버에서 Angular 애플리케이션을 테스트하려면 일반적인 테스트 명령을 실행하세요.

```shell
ng test
```

대부분의 CI 서버는 `CI=true` 환경 변수를 설정하며, `ng test`는 이를 감지합니다.
그러면 사용자 입력 없이 테스트를 한 번만 실행하도록 자동으로 설정됩니다.

CI 서버가 이 변수를 설정하지 않거나 한 번만 실행하도록 직접 지정해야 한다면 `--no-watch`와 `--no-progress` 플래그를 사용하세요.

```shell
ng test --no-watch --no-progress
```

## 테스트 더 알아보기

<!--
After you've set up your application for testing, you might find the following testing guides useful.

|                                                                    | Details                                                                           |
| :----------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| [Code coverage](guide/testing/code-coverage)                       | How much of your app your tests are covering and how to specify required amounts. |
| [Testing services](guide/testing/services)                         | How to test the services your application uses.                                   |
| [Basics of testing components](guide/testing/components-basics)    | Basics of testing Angular components.                                             |
| [Component testing scenarios](guide/testing/components-scenarios)  | Various kinds of component testing scenarios and use cases.                       |
| [Testing attribute directives](guide/testing/attribute-directives) | How to test your attribute directives.                                            |
| [Testing pipes](guide/testing/pipes)                               | How to test pipes.                                                                |
| [Debugging tests](guide/testing/debugging)                         | Common testing bugs.                                                              |
| [Testing utility APIs](guide/testing/utility-apis)                 | Angular testing features.                                                         |
-->

애플리케이션의 테스트 환경을 설정했다면 다음 문서도 확인해 보세요.

# 코드 커버리지

코드 커버리지 보고서로 코드 중에서 단위 테스트가 충분히 이루어지지 않은 부분을 확인할 수 있습니다.

## 사전 준비

<!--
To generate code coverage reports with Vitest, you must install the `@vitest/coverage-v8` package:

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

-->

Vitest로 코드 커버리지 보고서를 생성하려면 `@vitest/coverage-v8` 패키지를 설치해야 합니다.

## 보고서 생성하기

<!--
To generate a coverage report, add the `--coverage` flag to the `ng test` command:

```shell
ng test --coverage
```

After the tests run, the command creates a new `coverage/` directory in the project. Open the `index.html` file to see a report with your source code and code coverage values.

If you want to create code-coverage reports every time you test, you can set the `coverage` option to `true` in your `angular.json` file:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true
          }
        }
      }
    }
  }
}
```
-->

커버리지 보고서를 생성하려면 `ng test` 명령에 `--coverage` 플래그를 추가하세요.

```shell
ng test --coverage
```

테스트가 실행되면 프로젝트에 `coverage/` 디렉터리가 새로 생성됩니다.
`index.html` 파일을 열면 소스 코드와 코드 커버리지 수치가 담긴 보고서를 확인할 수 있습니다.

테스트를 실행할 때마다 코드 커버리지 보고서를 생성하려면 `angular.json` 파일에서 `coverage` 옵션을 `true`로 설정하세요.

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true
          }
        }
      }
    }
  }
}
```

## 코드 커버리지 최솟값 적용하기

<!--
The code coverage percentages let you estimate how much of your code is tested. If your team decides on a minimum amount to be unit tested, you can enforce this minimum in your configuration.

For example, suppose you want the code base to have a minimum of 80% code coverage. To enable this, add the `coverageThresholds` option to your `angular.json` file:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true,
            "coverageThresholds": {
              "statements": 80,
              "branches": 80,
              "functions": 80,
              "lines": 80
            }
          }
        }
      }
    }
  }
}
```

Now, if your coverage drops below 80% when you run your tests, the command will fail.
-->

코드 커버리지 비율로 코드가 얼마나 테스트되었는지 가늠할 수 있습니다.
팀에서 단위 테스트로 검증할 최소 비율을 정했다면 설정을 통해 이 기준을 적용할 수 있습니다.

예를 들어 코드 커버리지를 최소 80%로 유지하려면 `angular.json` 파일에 `coverageThresholds` 옵션을 추가하세요.

이제 테스트를 실행했을 때 커버리지가 80%보다 낮으면 명령이 실패합니다.

## 고급 설정

<!--
You can configure several other coverage options in your `angular.json` file:

- `coverageInclude`: Glob patterns of files to include in the coverage report.
- `coverageExclude`: Glob patterns of files to exclude in the coverage report.
- `coverageReporters`: An array of reporters to use (e.g., `html`, `lcov`, `json`).
- `coverageWatermarks`: An object specifying `[low, high]` watermarks for the HTML reporter, which can affect the color-coding of the report.

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

`angular.json` 파일에서 다음 커버리지 옵션도 설정할 수 있습니다.

- `coverageInclude`: 커버리지 보고서에 포함할 파일의 glob 패턴입니다.
- `coverageExclude`: 커버리지 보고서에서 제외할 파일의 glob 패턴입니다.
- `coverageReporters`: 사용할 리포터의 배열입니다.
  예를 들어 `html`, `lcov`, `json`을 사용할 수 있습니다.
- `coverageWatermarks`: HTML 리포터에 사용할 `[low, high]` 기준값을 지정하는 객체입니다.
  보고서의 색상 구분에 영향을 줄 수 있습니다.

# 서비스 테스트하기

<!--
Services typically contain your application's business logic that components rely on. Testing services verifies that the logic works correctly in isolation, independent of any component or template.

This guide uses [Vitest](https://vitest.dev/), which Angular CLI projects include by default. For more on testing setup, see the [testing overview guide](guide/testing#set-up-for-testing).
-->

서비스에는 보통 컴포넌트가 사용하는 애플리케이션의 비즈니스 로직이 담겨 있습니다.
서비스를 테스트하면 컴포넌트나 템플릿에 의존하지 않고 로직 자체가 제대로 동작하는지 확인할 수 있습니다.

이 문서에서는 Angular CLI 프로젝트에 기본으로 포함된 [Vitest](https://vitest.dev/)를 사용합니다.
테스트 환경 설정은 [테스트 개요](guide/testing#set-up-for-testing)를 참고하세요.

## 서비스 테스트하기

<!--
Consider a `Calculator` service that performs basic arithmetic:

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

To test this service, configure a `TestBed`, which is Angular's testing utility for creating an isolated testing environment for each test. It sets up dependency injection and lets you retrieve service instances — simulating how Angular wires things together in a real application.

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

In the example above, the `beforeEach` block injects a fresh instance of the service before every test. This ensures each test runs in isolation with no leaked state from previous tests.
-->

기본 산술 연산을 수행하는 `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;
  }
}
```

이 서비스를 테스트하려면 각 테스트에 독립적인 테스트 환경을 만드는 Angular 테스트 유틸리티 `TestBed`를 설정합니다.
`TestBed`는 의존성 주입을 구성하고 서비스 인스턴스를 가져올 수 있게 해서, 실제 애플리케이션에서 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(() => {
    // Calculator 서비스를 주입합니다.
    // 서비스가 `@Service`를 사용하므로 Angular에서 사용할 수 있습니다
    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` 블록은 각 테스트 전에 새로운 서비스 인스턴스를 주입합니다.
그래서 이전 테스트의 상태가 남지 않고 각 테스트가 독립적으로 실행됩니다.

## 의존성이 있는 서비스 테스트하기

<!--
Most services depend on other services to run properly. By default, `TestBed` provides the real implementations of these dependencies, which means your tests exercise the actual code paths your application uses. Sometimes, however, a dependency may be complex, slow, or unpredictable. In those cases, you can substitute it with a controlled replacement.

Consider an `OrderTotal` service that relies on a `TaxCalculator` to compute the final price of an order:

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

In this example, `OrderTotal` uses `inject()` to request `TaxCalculator` from Angular's dependency injection system. By default, `TestBed` provides the real `TaxCalculator` which is perfect for simple calculations like this. However, if `TaxCalculator` involved complex logic, network requests, or unpredictable results, you might want to substitute it with a controlled replacement.
-->

대부분의 서비스는 정상 동작하기 위해 다른 서비스에 의존합니다.
`TestBed`는 기본으로 의존성의 실제 구현을 제공하므로, 테스트에서도 애플리케이션이 사용하는 실제 코드 경로를 실행합니다.
하지만 의존성이 복잡하거나 느리거나 결과를 예측하기 어려운 경우도 있습니다.
이럴 때는 직접 제어할 수 있는 구현으로 교체할 수 있습니다.

`TaxCalculator`로 주문의 최종 금액을 계산하는 `OrderTotal` 서비스를 살펴봅시다.

```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()`로 Angular 의존성 주입 시스템에 `TaxCalculator`를 요청합니다.
`TestBed`는 기본으로 실제 `TaxCalculator`를 제공하며, 이처럼 간단한 계산에는 적합합니다.
하지만 `TaxCalculator`에 복잡한 로직이나 네트워크 요청이 있거나 결과를 예측하기 어렵다면, 직접 제어할 수 있는 구현으로 교체하는 것이 좋을 수 있습니다.

### 의존성을 스텁으로 교체하기

<!--
A stub is a way to replace a dependency or method with one that returns predictable values, which can make test results easier to verify.

To test `OrderTotal` without relying on the real `TaxCalculator`, you can provide a stub in the `TestBed` configuration.

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

With this stub, whenever `OrderTotal` requests `TaxCalculator`, the `TestBed` knows to use the `taxCalculatorStub` instead. Because the stub always returns 5, the test verifies that `OrderTotal` correctly adds the tax value to the subtotal regardless of whether the tax rate changes in `TaxCalculator`.
-->

스텁(stub)은 의존성이나 메서드를 예측할 수 있는 값을 반환하는 구현으로 교체하는 방법입니다.
이를 활용하면 테스트 결과를 검증하기 쉽습니다.

실제 `TaxCalculator`에 의존하지 않고 `OrderTotal`을 테스트하려면 `TestBed` 설정에 스텁을 제공하세요.

// Vitest의 `Mocked` 유틸리티 타입으로 스텁의 타입 안전성을 보장하고,
// `vi.fn()`으로 각 메서드의 목 함수를 생성합니다
const taxCalculatorStub: Mocked<TaxCalculator> = {
  calculate: vi.fn(),
};

describe('OrderTotal', () => {
  let service: OrderTotal;

beforeEach(() => {
    // `mockReturnValue`로 스텁의 반환값을 지정합니다
    taxCalculatorStub.calculate.mockReturnValue(5);

TestBed.configureTestingModule({
      // `providers` 배열에는 프로바이더 객체를 넣습니다. `provide`에는
      // 교체할 의존성을 지정하고 `useValue`에는 스텁을 정의합니다
      providers: [{provide: TaxCalculator, useValue: taxCalculatorStub}],
    });
    service = TestBed.inject(OrderTotal);
  });

it('adds tax to the subtotal', () => {
    expect(service.total(100)).toBe(105);
  });
});
```

이렇게 설정하면 `OrderTotal`이 `TaxCalculator`를 요청할 때마다 `TestBed`는 `taxCalculatorStub`을 대신 사용합니다.
스텁은 항상 5를 반환하므로, `TaxCalculator`의 세율이 바뀌더라도 `OrderTotal`이 소계에 세금을 올바르게 더하는지 확인할 수 있습니다.

### 스파이로 상호작용 검증하기

<!--
A stub controls what a dependency returns, but sometimes you also need to verify that a service called its dependency with the correct arguments. This can be accomplished with spies, which track how a function is called. With Vitest, this functionality is built into `vi.fn()` and lets you assert on interactions between services.

```ts
{ header: 'order-total.spec.ts' }
import {TestBed} from '@angular/core/testing';
import {afterEach, beforeEach, describe, expect, it, vi, type Mocked} from 'vitest';
import {OrderTotal} from './order-total';
import {TaxCalculator} from './tax-calculator';

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

The new test verifies that `OrderTotal` called `TaxCalculator.calculate` when computing the total. This is useful when verifying that the interaction between services happened correctly.
-->

스텁으로 의존성의 반환값을 제어할 수 있지만, 서비스가 의존성을 올바른 인자로 호출했는지도 확인해야 할 수 있습니다.
이때 함수의 호출 방식을 추적하는 스파이(spy)를 사용합니다.
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);
  });

// 스파이로 상호작용을 검증합니다
  it('calls the tax calculator', () => {
    service.total(100);
    expect(taxCalculatorStub.calculate).toHaveBeenCalledExactlyOnceWith(100);
  });
});
```

새 테스트는 `OrderTotal`이 합계를 계산할 때 `TaxCalculator.calculate`를 호출했는지 확인합니다.
서비스가 서로 올바르게 상호작용했는지 검증할 때 유용합니다.

## HTTP 서비스 테스트하기

<!--
Many services use Angular's `HttpClient` to fetch data from a server. Angular provides dedicated testing utilities for `HttpClient` that let you control HTTP responses without making real network requests.

For details on testing services that use `HttpClient`, see the [HTTP testing guide](guide/http/testing).
-->

많은 서비스가 Angular `HttpClient`로 서버에서 데이터를 가져옵니다.
Angular는 실제 네트워크 요청을 보내지 않고도 HTTP 응답을 제어할 수 있는 `HttpClient` 전용 테스트 유틸리티를 제공합니다.

`HttpClient`를 사용하는 서비스의 테스트 방법은 [HTTP 테스트](guide/http/testing) 문서를 참고하세요.

# 컴포넌트 테스트 기초

<!--
A component, unlike all other parts of an Angular application, combines an HTML template and a TypeScript class.
The component truly is the template and the class _working together_.
To adequately test a component, you should test that they work together as intended.

Such tests require creating the component's host element in the browser DOM, as Angular does, and investigating the component class's interaction with the DOM as described by its template.

The Angular `TestBed` facilitates this kind of testing as you'll see in the following sections.
But in many cases, _testing the component class alone_, without DOM involvement, can validate much of the component's behavior in a straightforward, more obvious way.
-->

컴포넌트는 Angular 애플리케이션의 다른 구성 요소와 달리 HTML 템플릿과 TypeScript 클래스를 결합합니다.
템플릿과 클래스가 _함께 동작_ 해야 비로소 컴포넌트라고 할 수 있습니다.
컴포넌트를 충분히 테스트하려면 둘이 의도한 대로 함께 동작하는지 확인해야 합니다.

이런 테스트에서는 Angular가 하는 것처럼 브라우저 DOM에 컴포넌트의 호스트 엘리먼트를 생성하고, 컴포넌트 클래스가 템플릿에 정의된 대로 DOM과 상호작용하는지 확인해야 합니다.

다음 내용에서 살펴보듯이 Angular `TestBed`를 사용하면 이런 테스트를 쉽게 작성할 수 있습니다.
하지만 많은 경우 DOM 없이 _컴포넌트 클래스만 테스트_ 해도 컴포넌트 동작의 상당 부분을 더 간단하고 명확하게 검증할 수 있습니다.

## 컴포넌트 DOM 테스트

<!--
A component is more than just its class.
A component interacts with the DOM and with other components.
Classes alone cannot tell you if the component is going to render properly, respond to user input and gestures, or integrate with its parent and child components.

- Is `Lightswitch.clicked()` bound to anything such that the user can invoke it?
- Is the `Lightswitch.message` displayed?
- Can the user actually select the hero displayed by the `DashboardHero` component?
- Is the hero name displayed as expected $such as uppercase$?
- Is the welcome message displayed by the template of the `Welcome` component?

These might not be troubling questions for the preceding simple components illustrated.
But many components have complex interactions with the DOM elements described in their templates, causing HTML to appear and disappear as the component state changes.

To answer these kinds of questions, you have to create the DOM elements associated with the components, you must examine the DOM to confirm that component state displays properly at the appropriate times, and you must simulate user interaction with the screen to determine whether those interactions cause the component to behave as expected.

To write these kinds of test, you'll use additional features of the `TestBed` as well as other testing helpers.
-->

컴포넌트는 단순한 클래스 이상입니다.
컴포넌트는 DOM 및 다른 컴포넌트와 상호작용합니다.
클래스만으로는 컴포넌트가 올바르게 렌더링되는지, 사용자 입력과 제스처에 반응하는지, 부모 및 자식 컴포넌트와 연동되는지 알 수 없습니다.

- 사용자가 `Lightswitch.clicked()`를 실행할 수 있도록 무언가에 바인딩되어 있나요?
- `Lightswitch.message`가 표시되나요?
- 사용자가 `DashboardHero` 컴포넌트에 표시된 히어로를 실제로 선택할 수 있나요?
- 히어로 이름이 예상한 대로$예: 대문자로$ 표시되나요?
- `Welcome` 컴포넌트 템플릿에 환영 메시지가 표시되나요?

앞에서 예로 든 간단한 컴포넌트라면 이런 질문이 큰 문제가 아닐 수도 있습니다.
하지만 많은 컴포넌트는 템플릿의 DOM 엘리먼트와 복잡하게 상호작용하며, 컴포넌트 상태가 바뀔 때 HTML이 나타나거나 사라집니다.

이런 내용을 확인하려면 컴포넌트에 대응하는 DOM 엘리먼트를 만들고, 적절한 시점에 컴포넌트 상태가 제대로 표시되는지 DOM을 검사해야 합니다.
또 사용자가 화면과 상호작용하는 상황을 재현해서 컴포넌트가 예상대로 동작하는지 확인해야 합니다.

이런 테스트를 작성할 때는 `TestBed`의 추가 기능과 다른 테스트 헬퍼를 사용합니다.

### CLI로 생성한 테스트

<!--
The CLI creates an initial test file for you by default when you ask it to generate a new component.

For example, the following CLI command generates a `Banner` component in the `app/banner` folder $with inline template and styles$:

```shell
ng generate component banner --inline-template --inline-style
```

It also generates an initial test file for the component, `banner.spec.ts`, that looks like this:

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

CLI로 새 컴포넌트를 생성하면 기본으로 초기 테스트 파일도 만들어집니다.

예를 들어 다음 CLI 명령은 `app/banner` 폴더에 인라인 템플릿과 스타일을 사용하는 `Banner` 컴포넌트를 생성합니다.

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

### 설정 간소화하기

<!--
Only the last three lines of this file actually test the component and all they do is assert that Angular can create the component.

The rest of the file is boilerplate setup code anticipating more advanced tests that _might_ become necessary if the component evolves into something substantial.

You'll learn about these advanced test features in the following sections.
For now, you can radically reduce this test file to a more manageable size:

```ts
describe('Banner (minimal)', () => {
  it('should create', () => {
    const fixture = TestBed.createComponent(Banner);
    const component = fixture.componentInstance;
    expect(component).toBeDefined();
  });
});
```

Later you'll call `TestBed.configureTestingModule()` with imports, providers, and more declarations to suit your testing needs.
Optional `override` methods can further fine-tune aspects of the configuration.

NOTE: `TestBed.compileComponents` is only required when `@defer` blocks are used in the tested components.
-->

이 파일에서 실제로 컴포넌트를 테스트하는 코드는 마지막 세 줄뿐입니다.
Angular가 컴포넌트를 생성할 수 있는지만 확인합니다.

나머지는 컴포넌트가 복잡해졌을 때 _필요할 수도 있는_ 고급 테스트를 대비한 기본 설정 코드입니다.

이런 고급 테스트 기능은 다음 내용에서 알아봅니다.
지금은 테스트 파일을 관리하기 쉬운 크기로 크게 줄여봅시다.

나중에 테스트 요구사항에 맞게 imports, providers, 추가 declarations를 지정해서 `TestBed.configureTestingModule()`을 실행하게 됩니다.
필요하다면 `override` 메서드로 설정을 더 세밀하게 조정할 수 있습니다.

참고: `TestBed.compileComponents`는 테스트할 컴포넌트에 `@defer` 블록이 있을 때만 필요합니다.

### `createComponent()`

<!--
After configuring `TestBed`, you call its `createComponent()` method.

```ts
const fixture = TestBed.createComponent(Banner);
```

`TestBed.createComponent()` creates an instance of the `Banner` component, adds a corresponding element to the test-runner DOM, and returns a [`ComponentFixture`](#componentfixture).

IMPORTANT: Do not re-configure `TestBed` after calling `createComponent`.

The `createComponent` method freezes the current `TestBed` definition, closing it to further configuration.

You cannot call any more `TestBed` configuration methods, not `configureTestingModule()`, nor any of the `override...` methods.
If you try, `TestBed` throws an error.
-->

`TestBed`를 설정한 후에는 `createComponent()` 메서드를 실행합니다.

```ts
const fixture = TestBed.createComponent(Banner);
```

`TestBed.createComponent()`는 `Banner` 컴포넌트 인스턴스를 생성하고 테스트 러너의 DOM에 대응하는 엘리먼트를 추가한 후 [`ComponentFixture`](#componentfixture)를 반환합니다.

중요: `createComponent`를 실행한 후에는 `TestBed`를 다시 설정하지 마세요.

`createComponent` 메서드를 실행하면 현재 `TestBed` 정의가 고정되어 더 이상 설정할 수 없습니다.

`configureTestingModule()`, `override...` 등 `TestBed` 설정 메서드를 추가로 실행할 수 없습니다.
실행하면 `TestBed`가 오류를 발생시킵니다.

### `ComponentFixture`

<!--
The [`ComponentFixture`](api/core/testing/ComponentFixture) is a test harness for interacting with the created component and its corresponding element.

Access the component instance through the fixture and confirm it exists with an expectation:

```ts
const component = fixture.componentInstance;
expect(component).toBeDefined();
```
-->

[`ComponentFixture`](api/core/testing/ComponentFixture)는 생성한 컴포넌트와 이에 대응하는 엘리먼트와 상호작용하는 테스트 하네스입니다.

픽스처를 통해 컴포넌트 인스턴스에 접근하고, 검증문으로 인스턴스가 존재하는지 확인합니다.

```ts
const component = fixture.componentInstance;
expect(component).toBeDefined();
```

### `beforeEach()`

<!--
You will add more tests as this component evolves.
Rather than duplicate the `TestBed` configuration for each test, you refactor to pull the setup into a `beforeEach()` and some supporting variables:

```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: By awaiting the initial rendering in the `beforeEach` with `await fixture.whenStable` the single tests synchronous.

Now add a test that gets the component's element from `fixture.nativeElement` and looks for the expected text.

```ts
it('should contain "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  expect(bannerElement.textContent).toContain('banner works!');
});
```
-->

컴포넌트가 발전하면 테스트도 추가하게 됩니다.
각 테스트마다 `TestBed` 설정을 반복하지 않도록 설정을 `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(); // 초기 렌더링이 끝날 때까지 기다려야 합니다
  });

it('should create', () => {
    expect(component).toBeDefined();
  });
});
```

참고: `beforeEach`에서 `await fixture.whenStable`로 초기 렌더링이 끝날 때까지 기다리면 개별 테스트를 동기적으로 작성할 수 있습니다.

이제 `fixture.nativeElement`에서 컴포넌트 엘리먼트를 가져오고 예상한 텍스트를 확인하는 테스트를 추가합니다.

```ts
it('should contain "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  expect(bannerElement.textContent).toContain('banner works!');
});
```

### `setup` 함수 만들기

<!--
As an alternative to `beforeEach`, you can also create a setup function that you will call in every test.
A setup function has the advantage of being customizable via parameters.

Here is an example of what a setup function could look like:

```ts
function setup(providers?: Provider[]): ComponentFixture<Banner> {
  TestBed.configureTestingModule({providers});
  return TestBed.createComponent(Banner);
}
```
-->

`beforeEach` 대신 각 테스트에서 호출하는 설정 함수를 만들 수도 있습니다.
설정 함수는 파라미터로 동작을 조정할 수 있다는 장점이 있습니다.

설정 함수는 다음과 같이 작성할 수 있습니다.

```ts
function setup(providers?: Provider[]): ComponentFixture<Banner> {
  TestBed.configureTestingModule({providers});
  return TestBed.createComponent(Banner);
}
```

### `nativeElement`

<!--
The value of `ComponentFixture.nativeElement` has the `any` type.
Later you'll encounter the `DebugElement.nativeElement` and it too has the `any` type.

Angular can't know at compile time what kind of HTML element the `nativeElement` is or if it even is an HTML element.
The application might be running on a _non-browser platform_, such as the server or a node environment, where the element might have a diminished API or not exist at all.

The tests in this guide are designed to run in a browser so a `nativeElement` value will always be an `HTMLElement` or one of its derived classes.

Knowing that it is an `HTMLElement` of some sort, use the standard HTML `querySelector` to dive deeper into the element tree.

Here's another test that calls `HTMLElement.querySelector` to get the paragraph element and look for the banner text:

```ts
it('should have <p> with "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  const p = bannerElement.querySelector('p')!;
  expect(p.textContent).toEqual('banner works!');
});
```
-->

`ComponentFixture.nativeElement` 값은 `any` 타입입니다.
뒤에서 살펴볼 `DebugElement.nativeElement`도 `any` 타입입니다.

Angular는 컴파일 시점에 `nativeElement`가 어떤 HTML 엘리먼트인지, HTML 엘리먼트이기는 한지 알 수 없습니다.
애플리케이션이 서버나 node 환경처럼 _브라우저가 아닌 플랫폼_ 에서 실행될 수 있기 때문입니다.
이런 환경에서는 엘리먼트 API가 제한되거나 엘리먼트 자체가 없을 수도 있습니다.

이 문서의 테스트는 브라우저에서 실행하도록 작성했으므로, `nativeElement` 값은 항상 `HTMLElement`이거나 이를 상속하는 클래스입니다.

`HTMLElement`라는 것을 알 수 있으므로 표준 HTML `querySelector`를 사용해서 엘리먼트 트리 안쪽에 접근할 수 있습니다.

다음 테스트는 `HTMLElement.querySelector`로 문단 엘리먼트를 가져오고 배너 텍스트를 확인합니다.

### `DebugElement`

<!--
The Angular _fixture_ provides the component's element directly through the `fixture.nativeElement`.

```ts
const bannerElement: HTMLElement = fixture.nativeElement;
```

This is actually a convenience method, implemented as `fixture.debugElement.nativeElement`.

```ts
const bannerDe: DebugElement = fixture.debugElement;
const bannerEl: HTMLElement = bannerDe.nativeElement;
```

There's a good reason for this circuitous path to the element.

The properties of the `nativeElement` depend upon the runtime environment.
You could be running these tests on a _non-browser_ platform that doesn't have a DOM or whose DOM-emulation doesn't support the full `HTMLElement` API.

Angular relies on the `DebugElement` abstraction to work safely across _all supported platforms_.
Instead of creating an HTML element tree, Angular creates a `DebugElement` tree that wraps the _native elements_ for the runtime platform.
The `nativeElement` property unwraps the `DebugElement` and returns the platform-specific element object.

Because the sample tests for this guide are designed to run only in a browser, a `nativeElement` in these tests is always an `HTMLElement` whose familiar methods and properties you can explore within a test.

Here's the previous test, re-implemented with `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!');
});
```

The `DebugElement` has other methods and properties that are useful in tests, as you'll see elsewhere in this guide.

You import the `DebugElement` symbol from the Angular core library.

```ts
import {DebugElement} from '@angular/core';
```
-->

Angular _픽스처_ 는 `fixture.nativeElement`로 컴포넌트 엘리먼트를 바로 제공합니다.

```ts
const bannerElement: HTMLElement = fixture.nativeElement;
```

실제로는 편의를 위해 제공하는 접근 방식이며, 내부적으로는 `fixture.debugElement.nativeElement`로 구현되어 있습니다.

```ts
const bannerDe: DebugElement = fixture.debugElement;
const bannerEl: HTMLElement = bannerDe.nativeElement;
```

엘리먼트에 이렇게 간접적으로 접근하는 데에는 이유가 있습니다.

`nativeElement`의 프로퍼티는 실행 환경에 따라 달라집니다.
DOM이 없거나 DOM 에뮬레이션이 전체 `HTMLElement` API를 지원하지 않는 _브라우저 이외의_ 플랫폼에서 테스트를 실행할 수도 있습니다.

Angular는 _지원하는 모든 플랫폼_ 에서 안전하게 동작하기 위해 `DebugElement` 추상화를 사용합니다.
HTML 엘리먼트 트리를 만드는 대신 실행 플랫폼의 _네이티브 엘리먼트_ 를 감싸는 `DebugElement` 트리를 생성합니다.
`nativeElement` 프로퍼티는 `DebugElement` 안의 플랫폼별 엘리먼트 객체를 반환합니다.

이 문서의 예제 테스트는 브라우저에서만 실행하도록 작성했으므로 `nativeElement`는 항상 `HTMLElement`입니다.
따라서 익숙한 메서드와 프로퍼티를 테스트에서 사용할 수 있습니다.

앞의 테스트를 `fixture.debugElement.nativeElement`로 다시 구현하면 다음과 같습니다.

`DebugElement`에는 테스트에 유용한 다른 메서드와 프로퍼티도 있습니다.
이 문서의 다른 부분에서 알아봅니다.

`DebugElement` 심볼은 Angular core 라이브러리에서 로드합니다.

```ts
import {DebugElement} from '@angular/core';
```

### `By.css()`

<!--
Although the tests in this guide all run in the browser, some applications might run on a different platform at least some of the time.

For example, the component might render first on the server as part of a strategy to make the application launch faster on poorly connected devices.
The server-side renderer might not support the full HTML element API.
If it doesn't support `querySelector`, the previous test could fail.

The `DebugElement` offers query methods that work for all supported platforms.
These query methods take a _predicate_ function that returns `true` when a node in the `DebugElement` tree matches the selection criteria.

You create a _predicate_ with the help of a `By` class imported from a library for the runtime platform.
Here's the `By` import for the browser platform:

```ts
import {By} from '@angular/platform-browser';
```

The following example re-implements the previous test with `DebugElement.query()` and the browser's `By.css` method.

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

Some noteworthy observations:

- The `By.css()` static method selects `DebugElement` nodes with a [standard CSS selector](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors 'CSS selectors').
- The query returns a `DebugElement` for the paragraph.
- You must unwrap that result to get the paragraph element.

When you're filtering by CSS selector and only testing properties of a browser's _native element_, the `By.css` approach might be overkill.

It's often more straightforward and clear to filter with a standard `HTMLElement` method such as `querySelector()` or `querySelectorAll()`.
-->

이 문서의 테스트는 모두 브라우저에서 실행되지만, 어떤 애플리케이션은 적어도 일부 시점에는 다른 플랫폼에서 실행될 수 있습니다.

예를 들어 연결 상태가 좋지 않은 기기에서도 애플리케이션을 빠르게 시작하도록 컴포넌트를 서버에서 먼저 렌더링할 수 있습니다.
서버 측 렌더러는 전체 HTML 엘리먼트 API를 지원하지 않을 수도 있습니다.
`querySelector`를 지원하지 않는다면 앞의 테스트는 실패할 수 있습니다.

`DebugElement`는 지원하는 모든 플랫폼에서 동작하는 쿼리 메서드를 제공합니다.
이 메서드는 `DebugElement` 트리의 노드가 선택 조건에 맞으면 `true`를 반환하는 _조건식_ 함수를 받습니다.

실행 플랫폼의 라이브러리에서 로드한 `By` 클래스로 _조건식_ 을 만들 수 있습니다.
브라우저 플랫폼에서는 다음과 같이 `By`를 로드합니다.

```ts
import {By} from '@angular/platform-browser';
```

다음 예제는 앞의 테스트를 `DebugElement.query()`와 브라우저의 `By.css` 메서드로 다시 구현한 것입니다.

다음 내용을 확인해 보세요.

- `By.css()` 정적 메서드는 [표준 CSS 셀렉터](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors 'CSS 셀렉터')로 `DebugElement` 노드를 선택합니다.
- 쿼리는 문단을 나타내는 `DebugElement`를 반환합니다.
- 문단 엘리먼트를 가져오려면 이 결과에서 실제 엘리먼트를 꺼내야 합니다.

CSS 셀렉터로 필터링하고 브라우저의 _네이티브 엘리먼트_ 프로퍼티만 테스트한다면 `By.css`는 과할 수도 있습니다.

`querySelector()`나 `querySelectorAll()` 같은 표준 `HTMLElement` 메서드로 필터링하는 것이 더 간단하고 명확한 경우가 많습니다.

# 컴포넌트 테스트 시나리오

이 문서에서는 자주 사용하는 컴포넌트 테스트 사례를 알아봅니다.

## 컴포넌트 바인딩

<!--
In the example application, the `Banner` component presents static title text in the HTML template.

After a few changes, the `Banner` component presents a dynamic title by binding to the component's `title` property like this.

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

As minimal as this is, you decide to add a test to confirm that component actually displays the right content where you think it should.
-->

예제 애플리케이션의 `Banner` 컴포넌트는 HTML 템플릿에 정적인 제목 텍스트를 표시합니다.

코드를 조금 변경해서 컴포넌트의 `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>` 조회하기

<!--
You'll write a sequence of tests that inspect the value of the `<h1>` element that wraps the _title_ property interpolation binding.

You update the `beforeEach` to find that element with a standard HTML `querySelector` and assign it to the `h1` variable.

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

_title_ 프로퍼티의 문자열 바인딩을 감싸는 `<h1>` 엘리먼트의 값을 확인하는 테스트를 작성하겠습니다.

표준 HTML `querySelector`로 이 엘리먼트를 찾아 `h1` 변수에 할당하도록 `beforeEach`를 수정합니다.

```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 인스턴스
  h1 = fixture.nativeElement.querySelector('h1');
});
```

### `createComponent()`는 데이터를 바인딩하지 않습니다

<!--
For your first test you'd like to see that the screen displays the default `title`.
Your instinct is to write a test that immediately inspects the `<h1>` like this:

```ts
it('should display original title', () => {
  expect(h1.textContent).toContain(component.title());
});
```

_That test fails_ with the message:

```shell
{hideCopy}
expected '' to contain 'Test Tour of Heroes'.
```

Binding happens when Angular performs **change detection**.

In production, change detection kicks in automatically when Angular creates a component or the user enters a keystroke, for example.

The `TestBed.createComponent` does not trigger change detection synchronously; a fact confirmed in the revised test:

```ts
it('no title in the DOM after createComponent()', () => {
  expect(h1.textContent).toEqual('');
});
```
-->

첫 번째 테스트에서는 화면에 기본 `title`이 표시되는지 확인하려고 합니다.
다음과 같이 `<h1>`을 바로 검사하는 테스트를 작성하기 쉽습니다.

```ts
it('should display original title', () => {
  expect(h1.textContent).toContain(component.title());
});
```

하지만 다음 메시지와 함께 _테스트가 실패합니다_.

```shell
{hideCopy}
expected '' to contain 'Test Tour of Heroes'.
```

바인딩은 Angular가 **변경 감지**를 실행할 때 이루어집니다.

실제 애플리케이션에서는 Angular가 컴포넌트를 생성하거나 사용자가 키를 입력할 때 변경 감지가 자동으로 실행됩니다.

`TestBed.createComponent`는 변경 감지를 동기적으로 실행하지 않습니다.
수정한 테스트에서 이를 확인할 수 있습니다.

```ts
it('no title in the DOM after createComponent()', () => {
  expect(h1.textContent).toEqual('');
});
```

### `whenStable()`

<!--
You can tell the `TestBed` to wait for change detection to run with `await fixture.whenStable()`.
Only then does the `<h1>` have the expected title.

```ts
it('should display original title', async () => {
  await fixture.whenStable();
  expect(h1.textContent).toContain(component.title());
});
```

Delayed change detection is intentional and useful.
It gives the tester an opportunity to inspect and change the state of the component _before Angular initiates data binding and calls [lifecycle hooks](guide/components/lifecycle)_.

Here's another test that changes the component's `title` property _before_ calling `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');
});
```
-->

`await fixture.whenStable()`로 `TestBed`가 변경 감지 실행을 기다리게 할 수 있습니다.
그런 다음에야 `<h1>`에 예상한 제목이 표시됩니다.

```ts
it('should display original title', async () => {
  await fixture.whenStable();
  expect(h1.textContent).toContain(component.title());
});
```

변경 감지를 지연하는 것은 의도된 동작이며 유용합니다.
_Angular가 데이터 바인딩을 시작하고 [라이프사이클 훅](guide/components/lifecycle)을 실행하기 전에_ 테스트에서 컴포넌트 상태를 확인하고 변경할 기회를 제공하기 때문입니다.

다음 테스트는 `fixture.whenStable()`을 실행하기 _전에_ 컴포넌트의 `title` 프로퍼티를 변경합니다.

```ts
it('should display a different test title', async () => {
  component.title.set('Test Title');
  await fixture.whenStable();
  expect(h1.textContent).toContain('Test Title');
});
```

### 입력 프로퍼티에 시그널 바인딩하기

<!--
To reflect changes to inputs and listen to outputs you can dynamically bind signals to inputs and functions to outputs.

```ts
import {inputBinding, outputBinding} from '@angular/core';
import {TestBed} from '@angular/core/testing';

const fixture = TestBed.createComponent(ValueDisplay, {
  bindings: [
    inputBinding('value', value),
    outputBinding('valueChange', () =>  (/* ... */) ),
  ],
});
```
-->

입력값의 변경을 반영하고 출력 이벤트를 감지하려면 입력 프로퍼티에는 시그널을, 출력 프로퍼티에는 함수를 동적으로 바인딩할 수 있습니다.

```ts
import {inputBinding, outputBinding} from '@angular/core';
import {TestBed} from '@angular/core/testing';

const fixture = TestBed.createComponent(ValueDisplay, {
  bindings: [
    inputBinding('value', value),
    outputBinding('valueChange', () =>  (/* ... */) ),
  ],
});
```

### `dispatchEvent()`로 입력값 변경하기

<!--
To simulate user input, find the input element and set its `value` property.

But there is an essential, intermediate step.

Angular doesn't know that you set the input element's `value` property.
It won't read that property until you raise the element's `input` event by calling `dispatchEvent()`.

The following example of a component using the `TitleCasePipe` demonstrates the proper sequence.

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

사용자 입력을 재현하려면 입력 엘리먼트를 찾아 `value` 프로퍼티를 설정합니다.

하지만 그 사이에 꼭 필요한 단계가 있습니다.

Angular는 입력 엘리먼트의 `value` 프로퍼티를 직접 설정했다는 것을 알지 못합니다.
`dispatchEvent()`로 엘리먼트의 `input` 이벤트를 발생시켜야 이 프로퍼티를 읽습니다.

`TitleCasePipe`를 사용하는 다음 컴포넌트 예제에서 올바른 순서를 확인할 수 있습니다.

// 사용자가 입력 필드에 새 이름을 입력하는 상황을 재현합니다
  nameInput.value = 'quick BROWN  fOx';

// Angular가 입력값 변경을 알 수 있도록 DOM 이벤트를 발생시킵니다.
  nameInput.dispatchEvent(new Event('input'));

// Angular가 title 파이프로 화면의 바인딩을 갱신할 때까지 기다립니다
  await fixture.whenStable();

expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
```

## 의존성이 있는 컴포넌트

<!--
Components often have service dependencies.

The `Welcome` component displays a welcome message to the logged-in user.
It knows who the user is based on a property of the injected `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.',
  );
}
```

The `Welcome` component has decision logic that interacts with the service, logic that makes this component worth testing.
-->

컴포넌트는 서비스에 의존하는 경우가 많습니다.

`Welcome` 컴포넌트는 로그인한 사용자에게 환영 메시지를 표시합니다.
주입된 `UserAuthentication`의 프로퍼티로 사용자가 누구인지 확인합니다.

```typescript
import {Component, inject, OnInit, signal} from '@angular/core';
import {UserAuthentication} from '../model/user.authentication';

`Welcome` 컴포넌트에는 서비스와 상호작용하는 판단 로직이 있으므로 테스트할 가치가 있습니다.

### 서비스 테스트 대역 제공하기

<!--
A _component-under-test_ doesn't have to be provided with real services.

Injecting the real `UserAuthentication` could be difficult.
The real service might ask the user for login credentials and attempt to reach an authentication server.
These behaviors can be hard to intercept. Be aware that using test doubles makes the test behave differently from production so use them sparingly.
-->

_테스트할 컴포넌트_ 에 반드시 실제 서비스를 제공할 필요는 없습니다.

실제 `UserAuthentication`을 주입하기 어려울 수 있습니다.
실제 서비스는 사용자에게 로그인 정보를 요구하거나 인증 서버에 접근할 수 있습니다.
이런 동작을 가로채기는 어려울 수 있습니다.
다만 테스트 대역을 사용하면 실제 애플리케이션과 테스트의 동작이 달라진다는 점을 고려해서 필요한 경우에만 사용하세요.

### 주입된 서비스 가져오기

<!--
The tests need access to the `UserAuthentication` injected into the `Welcome` component.

Angular has a hierarchical injection system.
There can be injectors at multiple levels, from the root injector created by the `TestBed` down through the component tree.

The safest way to get the injected service, the way that **_always works_**,
is to **get it from the injector of the _component-under-test_**.
The component injector is a property of the fixture's `DebugElement`.

```ts
// UserAuthentication actually injected into the component
userAuth = fixture.debugElement.injector.get(UserAuthentication);
```

HELPFUL: This is _usually_ not necessary. Services are often provided in the root or the TestBed overrides and can be retrieved more easily with `TestBed.inject()` (see below).
-->

테스트에서는 `Welcome` 컴포넌트에 주입된 `UserAuthentication`에 접근해야 합니다.

Angular는 계층적인 의존성 주입 시스템을 사용합니다.
`TestBed`가 생성한 최상위 인젝터부터 컴포넌트 트리 아래까지 여러 수준에 인젝터가 있을 수 있습니다.

주입된 서비스를 가져오는 가장 안전하고 **_항상 동작하는_** 방법은 ***테스트할 컴포넌트* 의 인젝터에서 가져오는 것**입니다.
컴포넌트 인젝터는 픽스처의 `DebugElement` 프로퍼티로 제공됩니다.

```ts
// 컴포넌트에 실제로 주입된 UserAuthentication
userAuth = fixture.debugElement.injector.get(UserAuthentication);
```

참고: _대부분_ 은 이렇게 할 필요가 없습니다.
서비스는 최상위에서 제공하거나 TestBed에서 재정의하는 경우가 많으므로, 아래에서 설명하는 `TestBed.inject()`로 더 간단하게 가져올 수 있습니다.

### `TestBed.inject()`

<!--
This is easier to remember and less verbose than retrieving a service using the fixture's `DebugElement`.

In this test suite, the _only_ provider of `UserAuthentication` is the root testing module, so it is safe to call `TestBed.inject()` as follows:

```ts
userAuth = TestBed.inject(UserAuthentication);
```

HELPFUL: For a use case in which `TestBed.inject()` does not work, see the [_Override component providers_](#override-component-providers) section that explains when and why you must get the service from the component's injector instead.
-->

픽스처의 `DebugElement`로 서비스를 가져오는 것보다 기억하기 쉽고 코드도 간결합니다.

이 테스트 모음에서 `UserAuthentication`의 _유일한_ 프로바이더는 최상위 테스트 모듈에 있으므로, 다음과 같이 `TestBed.inject()`를 안전하게 사용할 수 있습니다.

```ts
userAuth = TestBed.inject(UserAuthentication);
```

참고: `TestBed.inject()`로 가져올 수 없는 경우는 [_컴포넌트 프로바이더 재정의하기_](#override-component-providers)를 참고하세요.
언제, 왜 컴포넌트 인젝터에서 서비스를 가져와야 하는지 설명합니다.

### 최종 설정과 테스트

<!--
Here's the complete `beforeEach()`, using `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');
});
```

And here are some tests:

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

The first is a sanity test; it confirms that the `UserAuthentication` is called and working.

HELPFUL: The 2nd argument of `expect` $for example, `'expected name'`$ is an optional failure label.
If the expectation fails, Vitest appends this label to the expectation failure message.
In a spec with multiple expectations, it can help clarify what went wrong and which expectation failed.

The remaining tests confirm the logic of the component when the service returns different values.
The second test validates the effect of changing the user name.
The third test checks that the component displays the proper message when there is no logged-in user.
-->

`TestBed.inject()`를 사용하는 전체 `beforeEach()`는 다음과 같습니다.

```ts
let fixture: ComponentFixture<Welcome>;
let comp: Welcome;
let userAuth: UserAuthentication; // TestBed가 주입한 서비스
let el: HTMLElement; // 환영 메시지가 있는 DOM 엘리먼트

beforeEach(() => {
  fixture = TestBed.createComponent(Welcome);
  comp = fixture.componentInstance;

// 최상위 인젝터의 UserAuthentication
  userAuth = TestBed.inject(UserAuthentication);

// CSS 셀렉터(예: 클래스 이름)로 "welcome" 엘리먼트를 가져옵니다
  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'}); // 환영 메시지가 아직 표시되지 않았습니다
  await fixture.whenStable();

expect(el.textContent).toContain('Bubba');
});

it('should request login if not logged in', async () => {
  userAuth.isLoggedIn.set(false); // 환영 메시지가 아직 표시되지 않았습니다
  await fixture.whenStable();
  const content = el.textContent;

expect(content, 'not welcomed').not.toContain('Welcome');
  expect(content, '"log in"').toMatch(/log in/i);
});
```

첫 번째는 기본 동작을 확인하는 테스트입니다.
`UserAuthentication`이 호출되고 동작하는지 확인합니다.

참고: `expect`의 두 번째 인자$예: `'expected name'`$는 선택적으로 지정하는 실패 설명입니다.
검증에 실패하면 Vitest가 실패 메시지에 이 설명을 추가합니다.
검증문이 여러 개 있는 테스트에서는 어떤 문제가 발생했고 어느 검증문이 실패했는지 파악하는 데 도움이 됩니다.

나머지 테스트는 서비스가 서로 다른 값을 반환할 때 컴포넌트 로직을 확인합니다.
두 번째 테스트는 사용자 이름을 변경했을 때의 동작을 검증합니다.
세 번째 테스트는 로그인한 사용자가 없을 때 적절한 메시지를 표시하는지 확인합니다.

## 비동기 서비스를 사용하는 컴포넌트

<!--
In this sample, the `About` component template hosts a `Twain` component.
The `Twain` component displays Mark Twain quotes.

```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: The value of the component's `quote` property passes through an `AsyncPipe`.
That means the property returns either a `Promise` or an `Observable`.

In this example, the `TwainQuotes.getQuote()` method tells you that the `quote` property returns an `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
    }),
  );
}
```

The `Twain` component gets quotes from an injected `TwainQuotes`.
The component starts the returned `Observable` with a placeholder value $`'...'`$, before the service can return its first quote.

The `catchError` intercepts service errors, prepares an error message, and returns the placeholder value on the success channel.

These are all features you'll want to test.
-->

이 예제에서 `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>
}
```

참고: 컴포넌트의 `quote` 프로퍼티 값은 `AsyncPipe`를 통과합니다.
따라서 이 프로퍼티는 `Promise`나 `Observable`을 반환합니다.

이 예제에서는 `TwainQuotes.getQuote()` 메서드를 보면 `quote` 프로퍼티가 `Observable`을 반환한다는 것을 알 수 있습니다.

`Twain` 컴포넌트는 주입된 `TwainQuotes`에서 명언을 가져옵니다.
서비스가 첫 번째 명언을 반환하기 전에 표시할 수 있도록 반환된 `Observable`을 임시 값$`'...'`$으로 시작합니다.

`catchError`는 서비스 오류를 가로채고 오류 메시지를 준비한 뒤, 정상 값 전달 경로로 임시 값을 반환합니다.

이 기능들은 모두 테스트해 보는 것이 좋습니다.

### `HttpTestingController`로 HTTP 요청을 모킹해서 테스트하기

<!--
When testing a component, only the service's public API should matter.
In general, tests themselves should not make calls to remote servers.
They should emulate such calls.

In the case your async service relies on the `HttpClient` to load remote data, it is recommended to return mock responses at the HTTP level with the `HttpTestingController`.

For more details on mocking the `HttpBackend`, refer to the [dedicated guide](guide/http/testing).
-->

컴포넌트를 테스트할 때는 서비스의 공개 API에만 관심을 두어야 합니다.
일반적으로 테스트 자체가 원격 서버에 요청을 보내서는 안 됩니다.
그런 요청을 재현해야 합니다.

비동기 서비스가 `HttpClient`로 원격 데이터를 로드한다면 `HttpTestingController`로 HTTP 수준에서 목 응답을 반환하는 방식을 권장합니다.

`HttpBackend` 모킹에 대한 자세한 내용은 [HTTP 테스트](guide/http/testing) 문서를 참고하세요.

### 서비스의 스텁 구현으로 테스트하기

<!--
When mocking async request at the http level isn't possible, an alternative is to leverage spies.

The setup in this `app/twain/twain-quotes.spec.ts` shows one way to do that:

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

Focus on the how the stub implementation replaces the original one.

```ts
TestBed.configureTestingModule({
  providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
});
```

The stub is designed in such a way that any component or service that injects it will receive the stubbed implementation.
It means that any call to `getQuote` receives an observable with a test quote.

Unlike the real `getQuote()` method, this spy bypasses the server and returns a synchronous observable whose value is available immediately.
-->

HTTP 수준에서 비동기 요청을 모킹할 수 없다면 스파이를 활용할 수 있습니다.

`app/twain/twain-quotes.spec.ts`의 다음 설정은 그 방법 중 하나입니다.

```ts
{header: "twain.spec.ts"}
class TwainQuotesStub implements TwainQuotes {
  private testQuote = 'Test Quote';

getQuote() {
    return of(this.testQuote);
  }

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

스텁 구현이 원래 구현을 어떻게 대체하는지 확인해 보세요.

```ts
TestBed.configureTestingModule({
  providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
});
```

이 스텁은 이를 주입하는 모든 컴포넌트나 서비스가 스텁 구현을 받도록 구성되어 있습니다.
따라서 `getQuote`를 호출하면 항상 테스트용 명언이 담긴 옵저버블을 받습니다.

실제 `getQuote()` 메서드와 달리 이 스파이는 서버를 거치지 않고 값을 즉시 사용할 수 있는 동기 옵저버블을 반환합니다.

### Vitest 가상 타이머로 비동기 테스트하기

<!--
To mock async functions like `setTimeout` or `Promise`s, you can leverage Vitest fake timers to control whenever they fire.

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

`setTimeout`이나 `Promise` 같은 비동기 동작을 모킹할 때는 Vitest 가상 타이머로 실행 시점을 제어할 수 있습니다.

// ... API에 맞게 모든 기능을 구현합니다
  }

TestBed.configureTestingModule({
    providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
  });

vi.useFakeTimers(); // 가상 타이머를 설정합니다
  const fixture = TestBed.createComponent(TwainComponent);

// 렌더링이 비동기가 아니므로 대기 작업을 처리해야 합니다
  await vi.runAllTimersAsync();

await expect(fixture.nativeElement.querySelector('.error')!.textContent).toMatch(/test failure/);
  expect(fixture.nativeElement.querySelector('.twain')!.textContent).toBe('...');

vi.useRealTimers(); // 일반적인 비동기 실행으로 되돌립니다
});
```

### 비동기 테스트 더 알아보기

<!--
With the stubbed service returning async observables, most of your tests will have to be async as well.

Here's a test that demonstrates the data flow you'd expect in the real world.

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

Notice that the quote element displays the placeholder value $`'...'`$ on first rendering.
The first quote hasn't arrived yet.

Then you can assert that the quote element displays the expected text.
-->

스텁 서비스가 비동기 옵저버블을 반환한다면 대부분의 테스트도 비동기로 작성해야 합니다.

다음 테스트는 실제 환경에서 예상하는 데이터 흐름을 보여줍니다.

```ts
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(); // 명언을 받기 전에 렌더링합니다

const quoteEl = fixture.nativeElement.querySelector('.twain');
  expect(quoteEl.textContent).toBe('...');

twainQuotes.emit('Twain Quote'); // 명언을 발행합니다
  await vi.runAllTimersAsync(); // 명언을 받은 상태로 렌더링합니다

expect(quoteEl.textContent).toBe('Twain Quote');
  expect(fixture.nativeElement.querySelector('.error')).toBeNull();

vi.useRealTimers();
});
```

처음 렌더링할 때 명언 엘리먼트에 임시 값$`'...'`$이 표시되는 것을 확인해 보세요.
아직 첫 번째 명언이 도착하지 않았기 때문입니다.

그런 다음 명언 엘리먼트에 예상한 텍스트가 표시되는지 검증할 수 있습니다.

### `zone.js`와 `fakeAsync`로 비동기 테스트하기

<!--
The `fakeAsync` helper function is another mock clock that relies on patching asynchronous APIs with `zone.js`. It was commonly used in `zone.js` based applications for testing. The use of `fakeAsync` is no longer recommended.

TIP: Prefer using native async testing strategies or other fake timers (also called mock clocks) like those from Vitest or Jasmine.

IMPORTANT: `fakeAsync` requires `zone.js`. To use it with the Vitest test runner, add the `zone.js/plugins/vitest-patch` polyfill as described in [the Vitest migration guide](guide/testing/migrating-to-vitest#zonejs-vitest-patch).
-->

`fakeAsync` 헬퍼 함수도 가상 시계를 제공합니다.
`zone.js`로 비동기 API를 패치하는 방식이며, `zone.js` 기반 애플리케이션의 테스트에서 자주 사용했습니다.
이제는 `fakeAsync` 사용을 권장하지 않습니다.

팁: 네이티브 비동기 테스트 방식이나 Vitest, Jasmine이 제공하는 가상 타이머(목 시계라고도 합니다)를 우선 사용하세요.

중요: `fakeAsync`에는 `zone.js`가 필요합니다. Vitest 테스트 러너에서 사용하려면 [Vitest 마이그레이션 가이드](guide/testing/migrating-to-vitest#zonejs-vitest-patch)에 설명된 대로 `zone.js/plugins/vitest-patch` 폴리필을 추가하세요.

## 입력과 출력이 있는 컴포넌트

<!--
A component with inputs and outputs typically appears inside the view template of a host component.
The host uses a property binding to set the input property and an event binding to listen to events raised by the output property.

The testing goal is to verify that such bindings work as expected.
The tests should set input values and listen for output events.

The `DashboardHero` component is a tiny example of a component in this role.
It displays an individual hero provided by the `Dashboard` component.
Clicking that hero tells the `Dashboard` component that the user has selected the hero.

The `DashboardHero` component is embedded in the `Dashboard` component template like this:

```html
@for (hero of heroes; track hero) {
  <dashboard-hero class="col-1-4" [hero]="hero" (selected)="gotoDetail($event)" />
}
```

The `DashboardHero` component appears in an `@for` block, which sets each component's `hero` input property to the looping value and listens for the component's `selected` event.

Here's the component's full definition:

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

While testing a component this simple has little intrinsic value, it's worth knowing how.
Use one of these approaches:

- Test it as used by the `Dashboard` component
- Test it as a standalone component
- Test it as used by a substitute for the `Dashboard` component

The immediate goal is to test the `DashboardHero` component, not the `Dashboard` component, so, try the second and third options.
-->

입력과 출력이 있는 컴포넌트는 보통 호스트 컴포넌트의 뷰 템플릿 안에 있습니다.
호스트는 프로퍼티 바인딩으로 입력 프로퍼티를 지정하고, 이벤트 바인딩으로 출력 프로퍼티가 발생시키는 이벤트를 감지합니다.

이런 바인딩이 예상대로 동작하는지 검증하는 것이 테스트의 목표입니다.
테스트에서는 입력값을 설정하고 출력 이벤트를 감지해야 합니다.

`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` 블록 안에 있습니다.
각 컴포넌트의 `hero` 입력 프로퍼티를 반복 중인 값으로 지정하고 컴포넌트의 `selected` 이벤트를 감지합니다.

컴포넌트 전체 정의는 다음과 같습니다.

click() {
    this.selected.emit(this.hero());
  }
}
```

이렇게 간단한 컴포넌트는 테스트 자체의 이점이 크지 않지만, 테스트 방법은 알아둘 만합니다.
다음 방법 중 하나를 사용할 수 있습니다.

- `Dashboard` 컴포넌트에서 사용하는 상태로 테스트합니다.
- 독립적인 컴포넌트로 테스트합니다.
- `Dashboard`를 대신하는 컴포넌트에서 사용하는 상태로 테스트합니다.

지금은 `Dashboard`가 아니라 `DashboardHero`를 테스트하는 것이 목표이므로 두 번째와 세 번째 방법을 살펴봅시다.

### `DashboardHero` 컴포넌트를 독립적으로 테스트하기

<!--
Here's the meat of the spec file setup.

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

Notice how the setup code assigns a test hero $`expectedHero`$ to the component's `hero` property, emulating the way the `Dashboard` would set it using the property binding in its repeater.

The following test verifies that the hero name is propagated to the template using a binding.

```ts
it('should display hero name in uppercase', () => {
  const expectedPipedName = expectedHero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});
```

Because the template passes the hero name through the Angular `UpperCasePipe`, the test must match the element value with the upper-cased name.
-->

테스트 파일 설정의 핵심 부분은 다음과 같습니다.

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

// 히어로의 DebugElement와 엘리먼트를 찾습니다
  heroDe = fixture.debugElement.query(By.css('.hero'));
  heroEl = heroDe.nativeElement;

// 부모 컴포넌트가 제공하는 히어로를 모킹합니다
  expectedHero = {id: 42, name: 'Test Name'};

// 부모가 해당 히어로를 입력 프로퍼티에 지정하는 상황을 재현합니다
  fixture.componentRef.setInput('hero', expectedHero);

// 초기 데이터 바인딩을 기다립니다
  await fixture.whenStable();
});
```

설정 코드가 테스트용 히어로$`expectedHero`$를 컴포넌트의 `hero` 프로퍼티에 할당하는 방식을 확인해 보세요.
`Dashboard`가 반복문 안의 프로퍼티 바인딩으로 값을 지정하는 방식을 재현합니다.

다음 테스트는 히어로 이름이 바인딩을 통해 템플릿에 전달되는지 검증합니다.

```ts
it('should display hero name in uppercase', () => {
  const expectedPipedName = expectedHero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});
```

템플릿에서 히어로 이름에 Angular `UpperCasePipe`를 적용하므로, 테스트에서도 대문자로 변환한 이름과 엘리먼트 값을 비교해야 합니다.

### 클릭하기

<!--
Clicking the hero should raise a `selected` event that the host component $`Dashboard` presumably$ can hear:

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

The component's `selected` property is an `OutputEmitterRef`, whose `subscribe` method notifies subscribers synchronously.
The test subscribes to it _explicitly_ just as the host component does _implicitly_.

If the component behaves as expected, clicking the hero's element should tell the component's `selected` property to emit the `hero` object.

The test detects that event through its subscription to `selected`.
-->

히어로를 클릭하면 호스트 컴포넌트$이 경우에는 `Dashboard`$가 감지할 수 있는 `selected` 이벤트가 발생해야 합니다.

```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` 프로퍼티는 `OutputEmitterRef`입니다. 이 객체의 `subscribe` 메서드는 구독자에게 동기적으로 알립니다.
호스트 컴포넌트가 _묵시적으로_ 구독하는 것을 테스트에서는 _명시적으로_ 구독합니다.

컴포넌트가 예상대로 동작한다면 히어로 엘리먼트를 클릭했을 때 `selected` 프로퍼티가 `hero` 객체를 발행해야 합니다.

테스트는 `selected` 구독을 통해 이 이벤트를 감지합니다.

### `triggerEventHandler`

<!--
The `heroDe` in the previous test is a `DebugElement` that represents the hero `<button>`.

It has Angular properties and methods that abstract interaction with the native element.
This test calls the `DebugElement.triggerEventHandler` with the "click" event name.
The "click" event binding responds by calling `DashboardHero.click()`.

The Angular `DebugElement.triggerEventHandler` can raise _any data-bound event_ by its _event name_.
The second parameter is the event object passed to the handler.

The test triggered a "click" event.

```ts
heroDe.triggerEventHandler('click');
```

In this case, the test correctly assumes that the runtime event handler, the component's `click()` method, doesn't care about the event object.

HELPFUL: Other handlers are less forgiving.
For example, the `RouterLink` directive expects an object with a `button` property that identifies which mouse button, if any, was pressed during the click.
The `RouterLink` directive throws an error if the event object is missing.
-->

앞의 테스트에서 `heroDe`는 히어로 `<button>`를 나타내는 `DebugElement`입니다.

네이티브 엘리먼트와의 상호작용을 추상화하는 Angular 프로퍼티와 메서드를 제공합니다.
이 테스트는 이벤트 이름 "click"을 전달해서 `DebugElement.triggerEventHandler`를 실행합니다.
"click" 이벤트 바인딩은 이에 반응해서 `DashboardHero.click()`을 실행합니다.

Angular `DebugElement.triggerEventHandler`는 _이벤트 이름_ 으로 _데이터 바인딩된 모든 이벤트_ 를 발생시킬 수 있습니다.
두 번째 인자는 핸들러에 전달할 이벤트 객체입니다.

테스트에서는 "click" 이벤트를 발생시켰습니다.

```ts
heroDe.triggerEventHandler('click');
```

이 경우에는 실제 이벤트 핸들러인 컴포넌트의 `click()` 메서드가 이벤트 객체를 사용하지 않는다는 가정이 맞습니다.

참고: 다른 핸들러에서는 그렇지 않을 수 있습니다.
예를 들어 `RouterLink` 디렉티브는 클릭할 때 어떤 마우스 버튼을 눌렀는지 나타내는 `button` 프로퍼티가 있는 객체를 기대합니다.
이벤트 객체를 전달하지 않으면 `RouterLink` 디렉티브에서 오류가 발생합니다.

### 엘리먼트 클릭하기

<!--
The following test alternative calls the native element's own `click()` method, which is perfectly fine for _this component_.

```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()` 메서드를 실행하는 방법도 있습니다.
_이 컴포넌트_ 에는 적절한 방법입니다.

```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()` 헬퍼

<!--
Clicking a button, an anchor, or an arbitrary HTML element is a common test task.

Make that consistent and straightforward by encapsulating the _click-triggering_ process in a helper such as the following `click()` function:

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

The first parameter is the _element-to-click_.
If you want, pass a custom event object as the second parameter.
The default is a partial [left-button mouse event object](https://developer.mozilla.org/docs/Web/API/MouseEvent/button) accepted by many handlers including the `RouterLink` directive.

IMPORTANT: The `click()` helper function is **not** one of the Angular testing utilities.
It's a function defined in _this guide's sample code_.
All of the sample tests use it.
If you like it, add it to your own collection of helpers.

Here's the previous test, rewritten using the click helper.

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

버튼, 링크, 임의의 HTML 엘리먼트를 클릭하는 것은 테스트에서 자주 하는 작업입니다.

다음 `click()` 함수처럼 _클릭을 발생시키는_ 과정을 헬퍼로 감싸면 일관되고 간단하게 사용할 수 있습니다.

```ts
/** RouterLink 이벤트 핸들러를 위해 `DebugElement.triggerEventHandler`에 전달할 버튼 이벤트 */
export const ButtonClickEvents = {
  left: {button: 0},
  right: {button: 2},
};

/** 엘리먼트 클릭을 재현합니다. 기본값은 마우스 왼쪽 버튼 클릭 이벤트입니다. */
export function click(
  el: DebugElement | HTMLElement,
  eventObj: any = ButtonClickEvents.left,
): void {
  if (el instanceof HTMLElement) {
    el.click();
  } else {
    el.triggerEventHandler('click', eventObj);
  }
}
```

첫 번째 인자는 _클릭할 엘리먼트_ 입니다.
필요하면 두 번째 인자로 커스텀 이벤트 객체를 전달하세요.
기본값은 `RouterLink` 디렉티브를 비롯한 여러 핸들러가 처리할 수 있는 [마우스 왼쪽 버튼 이벤트 객체](https://developer.mozilla.org/docs/Web/API/MouseEvent/button)의 일부입니다.

중요: `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); // DebugElement에 click 헬퍼를 사용합니다

expect(selectedHero).toBe(expectedHero);
});
```

## 테스트 호스트 안의 컴포넌트

<!--
The previous tests played the role of the host `Dashboard` component themselves.
But does the `DashboardHero` component work correctly when properly data-bound to a host component?

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

The test host sets the component's `hero` input property with its test hero.
It binds the component's `selected` event with its `onSelected` handler, which records the emitted hero in its `selectedHero` property.

Later, the tests will be able to check `selectedHero` to verify that the `DashboardHero.selected` event emitted the expected hero.

The setup for the `test-host` tests is similar to the setup for the stand-alone tests:

```ts
beforeEach(async () => {
  // create TestHost instead of DashboardHero
  fixture = TestBed.createComponent(TestHost);
  testHost = fixture.componentInstance;
  heroEl = fixture.nativeElement.querySelector('.hero');

await fixture.whenStable();
});
```

This testing module configuration shows two important differences:

- It _creates_ the `TestHost` component instead of the `DashboardHero`
- The `TestHost` component sets the `DashboardHero.hero` with a binding

The `createComponent` returns a `fixture` that holds an instance of `TestHost` instead of an instance of `DashboardHero`.

Creating the `TestHost` has the side effect of creating a `DashboardHero` because the latter appears within the template of the former.
The query for the hero element $`heroEl`$ still finds it in the test DOM, albeit at greater depth in the element tree than before.

The tests themselves are almost identical to the stand-alone version:

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

Only the selected event test differs.
It confirms that the selected `DashboardHero` hero really does find its way up through the event binding to the host component.
-->

앞의 테스트는 호스트인 `Dashboard` 컴포넌트의 역할을 직접 수행했습니다.
그렇다면 `DashboardHero`를 호스트 컴포넌트에 실제로 데이터 바인딩했을 때도 제대로 동작할까요?

onSelected(hero: Hero) {
    this.selectedHero = hero;
  }
}
```

테스트 호스트는 테스트용 히어로를 컴포넌트의 `hero` 입력 프로퍼티로 지정합니다.
또한 컴포넌트의 `selected` 이벤트를 `onSelected` 핸들러에 바인딩하고, 이 핸들러는 전달받은 히어로를 `selectedHero` 프로퍼티에 저장합니다.

이후 테스트에서는 `selectedHero`를 확인해서 `DashboardHero.selected` 이벤트가 예상한 히어로를 전달했는지 검증할 수 있습니다.

`test-host` 테스트의 설정은 독립적인 테스트 설정과 비슷합니다.

```ts
beforeEach(async () => {
  // DashboardHero 대신 TestHost를 생성합니다
  fixture = TestBed.createComponent(TestHost);
  testHost = fixture.componentInstance;
  heroEl = fixture.nativeElement.querySelector('.hero');

await fixture.whenStable();
});
```

이 테스트 모듈 설정에는 두 가지 중요한 차이가 있습니다.

- `DashboardHero` 대신 `TestHost` 컴포넌트를 _생성_ 합니다.
- `TestHost` 컴포넌트가 바인딩으로 `DashboardHero.hero`를 지정합니다.

`createComponent`는 `DashboardHero`가 아닌 `TestHost` 인스턴스를 담은 `fixture`를 반환합니다.

`TestHost` 템플릿에 `DashboardHero`가 있으므로 `TestHost`를 생성하면 `DashboardHero`도 함께 생성됩니다.
히어로 엘리먼트$`heroEl`$는 이전보다 엘리먼트 트리의 더 깊은 곳에 있지만, 쿼리로 여전히 테스트 DOM에서 찾을 수 있습니다.

테스트 자체는 독립적인 테스트와 거의 같습니다.

```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);
  // 선택한 히어로는 데이터 바인딩한 히어로와 같아야 합니다
  expect(testHost.selectedHero).toBe(testHost.hero);
});
```

선택 이벤트 테스트만 다릅니다.
선택한 `DashboardHero`의 히어로가 이벤트 바인딩을 거쳐 호스트 컴포넌트까지 실제로 전달되는지 확인합니다.

## 라우팅을 실행하는 컴포넌트

<!--
A _routing component_ is a component that tells the `Router` to navigate to another component.
The `Dashboard` component is a _routing component_ because the user can navigate to the `HeroDetail` component by clicking on one of the _hero buttons_ on the dashboard.

Angular provides test helpers to reduce boilerplate and more effectively test code which depends on `HttpClient`. The `provideRouter` function can be used directly in the test module as well.

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

The following test clicks the displayed hero and confirms that we navigate to the expected 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}`,
  );
});
```
-->

_라우팅을 실행하는 컴포넌트_ 는 `Router`에 다른 컴포넌트로 이동하도록 요청하는 컴포넌트입니다.
사용자가 대시보드의 _히어로 버튼_ 을 클릭하면 `HeroDetail`로 이동할 수 있으므로 `Dashboard`는 _라우팅을 실행하는 컴포넌트_ 입니다.

Angular는 기본 설정 코드를 줄이고 `HttpClient`에 의존하는 코드를 더 효과적으로 테스트하는 헬퍼를 제공합니다.
테스트 모듈에서 `provideRouter` 함수도 직접 사용할 수 있습니다.

다음 테스트는 화면의 히어로를 클릭하고 예상한 URL로 이동하는지 확인합니다.

```ts
it('should tell navigate when hero clicked', async () => {
  // 첫 번째 <dashboard-hero>의 DebugElement를 가져옵니다
  const heroDe = harness.routeDebugElement!.query(By.css('dashboard-hero'));
  heroDe.triggerEventHandler('selected', comp.heroes[0]);

// 컴포넌트의 첫 번째 히어로 ID로 이동해야 합니다
  const id = comp.heroes[0].id;
  expect(TestBed.inject(Router).url, 'should nav to HeroDetail for first hero').toEqual(
    `/heroes/${id}`,
  );
});
```

## 라우팅 대상 컴포넌트

<!--
A _routed component_ is the destination of a `Router` navigation.
It can be trickier to test, especially when the route to the component _includes parameters_.
The `HeroDetail` is a _routed component_ that is the destination of such a route.

When a user clicks a _Dashboard_ hero, the `Dashboard` tells the `Router` to navigate to `heroes/:id`.
The `:id` is a route parameter whose value is the `id` of the hero to edit.

The `Router` matches that URL to a route to the `HeroDetail`.
It creates an `ActivatedRoute` object with the routing information and injects it into a new instance of the `HeroDetail`.

Here are the services injected into `HeroDetail`:

```ts
private heroDetailService = inject(HeroDetailService);
private route = inject(ActivatedRoute);
private router = inject(Router);
```

The `HeroDetail` component needs the `id` parameter so it can fetch the corresponding hero using the `HeroDetailService`.
The component has to get the `id` from the `ActivatedRoute.paramMap` property which is an `Observable`.

It can't just reference the `id` property of the `ActivatedRoute.paramMap`.
The component has to _subscribe_ to the `ActivatedRoute.paramMap` observable and be prepared for the `id` to change during its lifetime.

```ts
constructor() {
  // get hero when `id` param changes
  this.route.paramMap.subscribe((pmap) => this.getHero(pmap.get('id')));
}
```

Tests can explore how the `HeroDetail` responds to different `id` parameter values by navigating to different routes.
-->

_라우팅 대상 컴포넌트_ 는 `Router`가 이동하는 목적지입니다.
특히 컴포넌트의 라우팅 규칙에 _파라미터가 포함되어 있으면_ 테스트가 더 까다로울 수 있습니다.
`HeroDetail`은 이런 라우팅 규칙의 목적지인 _라우팅 대상 컴포넌트_ 입니다.

사용자가 _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` 컴포넌트는 `HeroDetailService`로 해당 히어로를 가져오기 위해 `id` 파라미터가 필요합니다.
컴포넌트는 `Observable`인 `ActivatedRoute.paramMap` 프로퍼티에서 `id`를 가져와야 합니다.

`ActivatedRoute.paramMap`의 `id` 프로퍼티를 단순히 참조할 수는 없습니다.
`ActivatedRoute.paramMap` 옵저버블을 _구독_ 하고 컴포넌트가 동작하는 동안 `id`가 변경될 수 있다는 점에 대비해야 합니다.

```ts
constructor() {
  // `id` 파라미터가 바뀌면 히어로를 가져옵니다
  this.route.paramMap.subscribe((pmap) => this.getHero(pmap.get('id')));
}
```

서로 다른 라우팅 규칙으로 이동하면 여러 `id` 파라미터 값에 `HeroDetail`이 어떻게 반응하는지 테스트할 수 있습니다.

## 중첩 컴포넌트 테스트

<!--
Component templates often have nested components, whose templates might contain more components.

The component tree can be very deep and sometimes the nested components play no role in testing the component at the top of the tree.

The `App` component, for example, displays a navigation bar with anchors and their `RouterLink` directives.

```html
<app-banner />
<app-welcome />

<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>

<router-outlet />
```

To validate the links but not the navigation, you don't need the `Router` to navigate and you don't need the `<router-outlet>` to mark where the `Router` inserts _routed components_.

The `Banner` and `Welcome` components $indicated by `<app-banner>` and `<app-welcome>`$ are also irrelevant.

Yet any test that creates the `App` component in the DOM also creates instances of these three components and, if you let that happen, you'll have to configure the `TestBed` to create them.

If you neglect to declare them, the Angular compiler won't recognize the `<app-banner>`, `<app-welcome>`, and `<router-outlet>` tags in the `App` template and will throw an error.

If you declare the real components, you'll also have to declare _their_ nested components and provide for _all_ services injected in _any_ component in the tree.

This section describes two techniques for minimizing the setup.
Use them, alone or in combination, to stay focused on testing the primary component.
-->

컴포넌트 템플릿에는 다른 컴포넌트가 들어가는 경우가 많으며, 그 컴포넌트의 템플릿에도 또 다른 컴포넌트가 있을 수 있습니다.

컴포넌트 트리는 아주 깊어질 수 있고, 중첩된 컴포넌트가 최상위 컴포넌트 테스트에는 필요하지 않은 경우도 있습니다.

예를 들어 `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`가 _라우팅 대상 컴포넌트_ 를 삽입할 위치를 표시하는 `<router-outlet>`도 필요하지 않습니다.

`<app-banner>`, `<app-welcome>`으로 표시된 `Banner`, `Welcome` 컴포넌트도 관련이 없습니다.

하지만 DOM에 `App` 컴포넌트를 생성하는 테스트는 이 세 컴포넌트의 인스턴스도 생성합니다.
그대로 생성하려면 `TestBed`에서도 이를 생성할 수 있도록 설정해야 합니다.

선언하지 않으면 Angular 컴파일러는 `App` 템플릿의 `<app-banner>`, `<app-welcome>`, `<router-outlet>` 태그를 인식하지 못하고 오류를 발생시킵니다.

실제 컴포넌트를 선언하면 _그 안의_ 중첩 컴포넌트도 선언해야 하고, 트리에 있는 _모든_ 컴포넌트에 주입되는 _모든_ 서비스도 제공해야 합니다.

여기서는 설정을 줄이는 두 가지 방법을 알아봅니다.
한 가지를 사용하거나 둘을 조합해서 주요 컴포넌트 테스트에 집중할 수 있습니다.

### 불필요한 컴포넌트를 스텁으로 대체하기

<!--
In the first technique, you create and declare stub versions of the components and directive that play little or no role in the tests.

```ts
@Component({selector: 'app-banner', template: ''})
class BannerStub {}

@Component({selector: 'router-outlet', template: ''})
class RouterOutletStub {}

@Component({selector: 'app-welcome', template: ''})
class WelcomeStub {}
```

The stub selectors match the selectors for the corresponding real components.
But their templates and classes are empty.

Then declare them by overriding the `imports` of your component using `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: The `set` key in this example replaces all the existing imports on your component, make sure to import all dependencies, not only the stubs. Alternatively you can use the `remove`/`add` keys to selectively remove and add imports.
-->

첫 번째 방법은 테스트에 거의 필요하지 않거나 전혀 필요하지 않은 컴포넌트와 디렉티브의 스텁을 만들어 선언하는 것입니다.

```ts
@Component({selector: 'app-banner', template: ''})
class BannerStub {}

@Component({selector: 'router-outlet', template: ''})
class RouterOutletStub {}

@Component({selector: 'app-welcome', template: ''})
class WelcomeStub {}
```

스텁의 셀렉터는 실제 컴포넌트와 같습니다.
하지만 템플릿과 클래스는 비어 있습니다.

그런 다음 `TestBed.overrideComponent`로 컴포넌트의 `imports`를 재정의해서 스텁을 선언합니다.

```ts
let comp: App;
let fixture: ComponentFixture<App>;

fixture = TestBed.createComponent(App);
  comp = fixture.componentInstance;
});
```

참고: 이 예제의 `set` 키는 컴포넌트의 기존 imports 전체를 교체합니다.
스텁뿐 아니라 필요한 모든 의존성을 로드해야 합니다.
대신 `remove`와 `add` 키로 imports를 선택적으로 제거하고 추가할 수도 있습니다.

### `NO_ERRORS_SCHEMA`

<!--
In the second approach, add `NO_ERRORS_SCHEMA` to the metadata overrides of your component.

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    set: {
      imports: [], // resets all imports
      schemas: [NO_ERRORS_SCHEMA],
    },
  });
});
```

The `NO_ERRORS_SCHEMA` tells the Angular compiler to ignore unrecognized elements and attributes.

The compiler recognizes the `<app-root>` element and the `routerLink` attribute because you declared a corresponding `App` component and `RouterLink` in the `TestBed` configuration.

But the compiler won't throw an error when it encounters `<app-banner>`, `<app-welcome>`, or `<router-outlet>`.
It simply renders them as empty tags and the browser ignores them.

You no longer need the stub components.
-->

두 번째 방법은 컴포넌트 메타데이터를 재정의하면서 `NO_ERRORS_SCHEMA`를 추가하는 것입니다.

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    set: {
      imports: [], // 모든 imports를 초기화합니다
      schemas: [NO_ERRORS_SCHEMA],
    },
  });
});
```

`NO_ERRORS_SCHEMA`는 Angular 컴파일러가 인식하지 못하는 엘리먼트와 어트리뷰트를 무시하도록 합니다.

`TestBed` 설정에 대응하는 `App` 컴포넌트와 `RouterLink`를 선언했으므로 컴파일러는 `<app-root>` 엘리먼트와 `routerLink` 어트리뷰트를 인식합니다.

하지만 `<app-banner>`, `<app-welcome>`, `<router-outlet>`을 만나도 오류를 발생시키지 않습니다.
빈 태그로 렌더링하고, 브라우저는 이를 무시합니다.

이제 스텁 컴포넌트가 필요하지 않습니다.

### 두 방법 함께 사용하기

<!--
These are techniques for _Shallow Component Testing_, so-named because they reduce the visual surface of the component to just those elements in the component's template that matter for tests.

The `NO_ERRORS_SCHEMA` approach is the easier of the two but don't overuse it.

The `NO_ERRORS_SCHEMA` also prevents the compiler from telling you about the missing components and attributes that you omitted inadvertently or misspelled.
You could waste hours chasing phantom bugs that the compiler would have caught in an instant.

The _stub component_ approach has another advantage.
While the stubs in _this_ example were empty, you could give them stripped-down templates and classes if your tests need to interact with them in some way.

In practice you will combine the two techniques in the same setup, as seen in this example.

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    remove: {imports: [RouterOutlet, Welcome]},
    set: {schemas: [NO_ERRORS_SCHEMA]},
  });
});
```

The Angular compiler creates the `BannerStub` for the `<app-banner>` element and applies the `RouterLink` to the anchors with the `routerLink` attribute, but it ignores the `<app-welcome>` and `<router-outlet>` tags.
-->

이런 방식을 _얕은 컴포넌트 테스트(Shallow Component Testing)_ 라고 합니다.
컴포넌트 템플릿에서 테스트에 필요한 엘리먼트만 남겨 화면 구성을 줄이기 때문입니다.

두 방법 중에서는 `NO_ERRORS_SCHEMA`가 간단하지만 남용하지 마세요.

`NO_ERRORS_SCHEMA`를 사용하면 실수로 빠뜨리거나 이름을 잘못 적은 컴포넌트와 어트리뷰트도 컴파일러가 알려주지 못합니다.
컴파일러가 즉시 발견할 수 있는 오류를 찾느라 몇 시간을 허비할 수 있습니다.

_스텁 컴포넌트_ 방식에는 또 다른 장점이 있습니다.
_이_ 예제에서는 스텁이 비어 있지만, 테스트에서 스텁과 상호작용해야 한다면 단순화한 템플릿과 클래스를 제공할 수 있습니다.

실제로는 다음 예제처럼 두 방식을 하나의 설정에서 함께 사용하기도 합니다.

Angular 컴파일러는 `<app-banner>` 엘리먼트에 `BannerStub`을 생성하고 `routerLink` 어트리뷰트가 있는 링크에는 `RouterLink`를 적용합니다.
하지만 `<app-welcome>`과 `<router-outlet>` 태그는 무시합니다.

### `By.directive`와 주입된 디렉티브

<!--
A little more setup triggers the initial data binding and gets references to the navigation links:

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

Three points of special interest:

- Locate the anchor elements with an attached directive using `By.directive`
- The query returns `DebugElement` wrappers around the matching elements
- Each `DebugElement` exposes a dependency injector with the specific instance of the directive attached to that element

The `App` component links to validate are as follows:

```html
<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>
```

Here are some tests that confirm those links are wired to the `routerLink` directives as expected:

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

설정을 조금 더 추가해서 초기 데이터 바인딩을 실행하고 내비게이션 링크의 참조를 가져옵니다.

```ts
beforeEach(async () => {
  await fixture.whenStable();

// RouterLinkStubDirective가 적용된 DebugElement를 찾습니다
  linkDes = fixture.debugElement.queryAll(By.directive(RouterLink));

// 적용된 링크 디렉티브 인스턴스를 가져옵니다
  // 각 DebugElement의 인젝터를 사용합니다
  routerLinks = linkDes.map((de) => de.injector.get(RouterLink));
});
```

세 가지 내용을 눈여겨보세요.

- `By.directive`로 디렉티브가 적용된 링크 엘리먼트를 찾습니다.
- 쿼리는 일치하는 엘리먼트를 감싼 `DebugElement`를 반환합니다.
- 각 `DebugElement`는 해당 엘리먼트에 적용된 디렉티브 인스턴스가 들어 있는 의존성 인젝터를 제공합니다.

검증할 `App` 컴포넌트의 링크는 다음과 같습니다.

```html
<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>
```

다음 테스트는 링크가 예상대로 `routerLink` 디렉티브에 연결되는지 확인합니다.

it('can click Heroes link in template', async () => {
  const heroesLinkDe = linkDes[1]; // heroes 링크의 DebugElement

TestBed.inject(Router).resetConfig([{path: '**', children: []}]);
  heroesLinkDe.triggerEventHandler('click', {button: 0});

await fixture.whenStable();

expect(TestBed.inject(Router).url).toBe('/heroes');
});
```

## `page` 객체 사용하기

<!--
The `HeroDetail` component is a simple view with a title, two hero fields, and two buttons.

But there's plenty of template complexity even in this simple form.

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

Tests that exercise the component need …

- To wait until a hero arrives before elements appear in the DOM
- A reference to the title text
- A reference to the name input box to inspect and set it
- References to the two buttons so they can click them

Even a small form such as this one can produce a mess of tortured conditional setup and CSS element selection.

Tame the complexity with a `Page` class that handles access to component properties and encapsulates the logic that sets them.

Here is such a `Page` class for the `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[];
  }
}
```

Now the important hooks for component manipulation and inspection are neatly organized and accessible from an instance of `Page`.

A `createComponent` method creates a `page` object and fills in the blanks once the `hero` arrives.

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

Here are a few more `HeroDetail` component tests to reinforce the point.

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

`HeroDetail` 컴포넌트는 제목, 히어로 필드 두 개, 버튼 두 개로 이루어진 간단한 뷰입니다.

하지만 이렇게 간단한 폼도 템플릿은 상당히 복잡할 수 있습니다.

컴포넌트를 테스트하려면 다음 내용이 필요합니다.

- DOM에 엘리먼트가 나타나도록 히어로를 가져올 때까지 기다리기
- 제목 텍스트 참조
- 값을 확인하고 설정할 이름 입력 필드 참조
- 클릭할 버튼 두 개의 참조

작은 폼이라도 조건에 따른 설정과 CSS 엘리먼트 선택 코드가 복잡하게 얽힐 수 있습니다.

컴포넌트 프로퍼티에 접근하고 값을 설정하는 로직을 `Page` 클래스로 감싸면 복잡성을 줄일 수 있습니다.

`hero-detail.component.spec.ts`에서 사용할 `Page` 클래스는 다음과 같습니다.

```ts
class Page {
  // getter 프로퍼티는 호출될 때 DOM을 조회합니다.
  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');
  }

//// 쿼리 헬퍼 ////
  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();

다음 `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 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 () => {
  // DOM에서 이름 입력 엘리먼트와 표시 엘리먼트를 가져옵니다
  const hostElement: HTMLElement = harness.routeNativeElement!;
  const nameInput: HTMLInputElement = hostElement.querySelector('input')!;
  const nameDisplay: HTMLElement = hostElement.querySelector('span')!;

// 사용자가 입력 필드에 새 이름을 입력하는 상황을 재현합니다
  nameInput.value = 'quick BROWN  fOx';

// Angular가 입력값 변경을 알 수 있도록 DOM 이벤트를 발생시킵니다.
  nameInput.dispatchEvent(new Event('input'));

// Angular가 title 파이프로 화면의 바인딩을 갱신할 때까지 기다립니다
  await harness.fixture.whenStable();

expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
```

## 컴포넌트 프로바이더 재정의하기

<!--
The `HeroDetail` provides its own `HeroDetailService`.

```ts
@Component({
  /* ... */
  providers: [HeroDetailService],
})
export class HeroDetail {
  private heroDetailService = inject(HeroDetailService);
  private route = inject(ActivatedRoute);
  private router = inject(Router);
}
```

It's not possible to stub the component's `HeroDetailService` in the `providers` of the `TestBed.configureTestingModule`.
Those are providers for the _testing module_, not the component.
They prepare the dependency injector at the _fixture level_.

Angular creates the component with its _own_ injector, which is a _child_ of the fixture injector.
It registers the component's providers $the `HeroDetailService` in this case$ with the child injector.

A test cannot get to child injector services from the fixture injector.
And `TestBed.configureTestingModule` can't configure them either.

Angular has created new instances of the real `HeroDetailService` all along!

HELPFUL: These tests could fail or timeout if the `HeroDetailService` made its own XHR calls to a remote server.
There might not be a remote server to call.

Fortunately, the `HeroDetailService` delegates responsibility for remote data access to an injected `HeroService`.

```ts
@Service()
export class HeroDetailService {
  private heroService = inject(HeroService);
}
```

The previous test configuration replaces the real `HeroService` with a `TestHeroService` that intercepts server requests and fakes their responses.

What if you aren't so lucky.
What if faking the `HeroService` is hard?
What if `HeroDetailService` makes its own server requests?

The `TestBed.overrideComponent` method can replace the component's `providers` with easy-to-manage _test doubles_ as seen in the following setup variation:

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

Notice that `TestBed.configureTestingModule` no longer provides a fake `HeroService` because it's [not needed](#provide-a-spy-stub-herodetailservicespy).
-->

`HeroDetail`은 자체 `HeroDetailService`를 제공합니다.

`TestBed.configureTestingModule`의 `providers`에서는 컴포넌트의 `HeroDetailService`를 스텁으로 대체할 수 없습니다.
이 프로바이더들은 컴포넌트가 아닌 _테스트 모듈_ 에 적용됩니다.
_픽스처 수준_ 의 의존성 인젝터를 구성하기 때문입니다.

Angular는 컴포넌트를 생성하면서 _자체_ 인젝터도 생성합니다.
이 인젝터는 픽스처 인젝터의 _자식_ 입니다.
컴포넌트의 프로바이더$이 경우에는 `HeroDetailService`$는 이 자식 인젝터에 등록합니다.

테스트에서는 픽스처 인젝터를 통해 자식 인젝터의 서비스에 접근할 수 없습니다.
`TestBed.configureTestingModule`로 설정할 수도 없습니다.

지금까지 Angular는 실제 `HeroDetailService`의 새 인스턴스를 생성하고 있었던 것입니다!

참고: `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는 관련이 없습니다!
      {provide: HeroDetailService, useValue: {}},
    ],
  }).overrideComponent(HeroDetail, {
    set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
  });
});
```

이제는 [필요하지 않기 때문에](#provide-a-spy-stub-herodetailservicespy) `TestBed.configureTestingModule`에서 가짜 `HeroService`를 제공하지 않는다는 점을 확인해 보세요.

### `overrideComponent` 메서드

<!--
Focus on the `overrideComponent` method.

```ts
.overrideComponent(HeroDetail, {
  set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
});
```

It takes two arguments: the component type to override $`HeroDetail`$ and an override metadata object.
The [override metadata object](/guide/testing/utility-apis#testbed-class-summary) is a generic defined as follows:

```ts
type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```

A metadata override object can either add-and-remove elements in metadata properties or completely reset those properties.
This example resets the component's `providers` metadata.

The type parameter, `T`, is the kind of metadata you'd pass to the `@Component` decorator:

```ts
selector?: string;
template?: string;
templateUrl?: string;
providers?: any[];
…
```
-->

`overrideComponent` 메서드를 자세히 살펴봅시다.

```ts
.overrideComponent(HeroDetail, {
  set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
});
```

재정의할 컴포넌트 타입$`HeroDetail`$과 재정의 메타데이터 객체, 이렇게 두 인자를 받습니다.
[재정의 메타데이터 객체](/guide/testing/utility-apis#testbed-class-summary)는 다음과 같은 제네릭으로 정의됩니다.

```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[];
…
```

### _스파이 스텁_ (`HeroDetailServiceSpy`) 제공하기

<!--
This example completely replaces the component's `providers` array with a new array containing a `HeroDetailServiceSpy`.

The `HeroDetailServiceSpy` is a stubbed version of the real `HeroDetailService` that fakes all necessary features of that service.
It neither injects nor delegates to the lower level `HeroService` so there's no need to provide a test double for that.

The related `HeroDetail` component tests will assert that methods of the `HeroDetailService` were called by spying on the service methods.
Accordingly, the stub implements its methods as 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)));
}
```
-->

이 예제는 컴포넌트의 `providers` 배열 전체를 `HeroDetailServiceSpy`가 들어 있는 새 배열로 교체합니다.

`HeroDetailServiceSpy`는 실제 `HeroDetailService`의 스텁으로, 테스트에 필요한 서비스 기능을 모두 대신 구현합니다.
하위 `HeroService`를 주입하거나 호출하지 않으므로 이를 위한 테스트 대역도 필요하지 않습니다.

관련 `HeroDetail` 컴포넌트 테스트는 서비스 메서드에 스파이를 적용해서 `HeroDetailService`의 메서드가 호출되는지 검증합니다.
따라서 스텁의 메서드를 스파이로 구현합니다.

```ts
import {vi} from 'vitest';

class HeroDetailServiceSpy {
  testHero: Hero = {...testHero};

/* 복제한 테스트용 히어로를 발행합니다 */
  getHero = vi.fn(() => asyncData({...this.testHero}));

/* 변경사항을 병합한 테스트용 히어로의 복제본을 발행합니다 */
  saveHero = vi.fn((hero: Hero) => asyncData(Object.assign(this.testHero, hero)));
}
```

### 재정의한 서비스로 테스트하기

<!--
Now the tests can control the component's hero directly by manipulating the spy-stub's `testHero` and confirm that service methods were called.

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

이제 테스트에서는 스파이 스텁의 `testHero`를 조작해서 컴포넌트의 히어로를 직접 제어하고 서비스 메서드가 호출되는지 확인할 수 있습니다.

```ts
let hdsSpy: HeroDetailServiceSpy;

beforeEach(async () => {
  harness = await RouterTestingHarness.create();
  component = await harness.navigateByUrl(`/heroes/${testHero.id}`, HeroDetail);
  page = new Page();
  // 컴포넌트에 주입된 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')); // 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');
});
```

### 다른 재정의 방법

<!--
The `TestBed.overrideComponent` method can be called multiple times for the same or different components.
The `TestBed` offers similar `overrideDirective`, `overrideModule`, and `overridePipe` methods for digging into and replacing parts of these other classes.

Explore the options and combinations on your own.
-->

`TestBed.overrideComponent`는 같은 컴포넌트나 서로 다른 컴포넌트에 여러 번 실행할 수 있습니다.
`TestBed`는 다른 클래스의 내부 설정을 찾아 교체하는 `overrideDirective`, `overrideModule`, `overridePipe` 메서드도 제공합니다.

여러 옵션과 조합을 직접 살펴보세요.

# 테스트 디버깅하기

테스트가 예상대로 동작하지 않으면 기본 Node.js 환경이나 실제 브라우저에서 디버깅할 수 있습니다.

## Node.js에서 디버깅하기

<!--
Debugging in the default Node.js environment is often the quickest way to diagnose issues that are not related to browser-specific APIs or rendering.

1.  Run the `ng test` command with the `--debug` flag:
    ```shell
ng test --debug
    ```
2.  The test runner will start in debug mode and wait for a debugger to attach.
3.  You can now attach your preferred debugger. For example, you can use the built-in Node.js debugger in VS Code or the Chrome DevTools for Node.js.
-->

브라우저 전용 API나 렌더링과 관련 없는 문제는 기본 Node.js 환경에서 디버깅하는 것이 대체로 가장 빠릅니다.

1. `ng test` 명령에 `--debug` 플래그를 추가해서 실행합니다.
   ```shell
ng test --debug
   ```
2. 테스트 러너가 디버그 모드로 시작되고 디버거가 연결될 때까지 기다립니다.
3. 원하는 디버거를 연결합니다.
   예를 들어 VS Code에 내장된 Node.js 디버거나 Node.js용 Chrome 개발자 도구를 사용할 수 있습니다.

## 브라우저에서 디버깅하기

<!--
The same way you start a debugging session with in Node, you can use `ng test` with the `--debug` flag with Vitest and [browser mode](/guide/testing/migrating-to-vitest#5-configure-browser-mode-optional).

The test runner will start in debug mode and wait for you to open the browser devtools to debug the tests.
-->

Node에서 디버깅을 시작하는 것과 같은 방식으로, Vitest와 [브라우저 모드](/guide/testing/migrating-to-vitest#5-configure-browser-mode-optional)에서도 `ng test` 명령에 `--debug` 플래그를 사용할 수 있습니다.

테스트 러너가 디버그 모드로 시작되고, 테스트를 디버깅할 수 있도록 브라우저 개발자 도구를 열 때까지 기다립니다.

# 테스트 유틸리티 API

<!--
NOTE: While this guide is being updated for Vitest, some descriptions and examples of utility APIs are currently presented within the context of Karma/Jasmine. We are actively working to provide Vitest equivalents and updated guidance where applicable.

This page describes the most useful Angular testing features.

The Angular testing utilities include the `TestBed`, the `ComponentFixture`, and a handful of functions that control the test environment.
The [`TestBed`](#testbed-class-summary) and [`ComponentFixture`](#the-componentfixture) classes are covered separately.

Here's a summary of the stand-alone functions, in order of likely utility:

| Function     | Details                                                                                                                                                                                                                                                      |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`inject`]   | Injects one or more services from the current `TestBed` injector into a test function. It cannot inject a service provided by the component itself. See discussion of the [debugElement.injector](guide/testing/components-scenarios#get-injected-services). |
| `getTestBed` | Gets the current instance of the `TestBed`. Usually unnecessary because the static class methods of the `TestBed` class are typically sufficient. The `TestBed` instance exposes a few rarely used members that are not available as static methods.         |

For handling complex asynchronous scenarios or testing legacy Zone.js-based applications, see the [Zone.js Testing Utilities](guide/testing/zone-js-testing-utilities) guide.
-->

참고: 이 문서는 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` 인스턴스에는 정적 메서드로 제공하지 않는 몇 가지 멤버가 있지만 드물게 사용합니다.                         |

복잡한 비동기 시나리오를 처리하거나 기존 Zone.js 기반 애플리케이션을 테스트하려면 [Zone.js 테스트 유틸리티](guide/testing/zone-js-testing-utilities) 문서를 참고하세요.

## `TestBed` 클래스 요약

<!--
The `TestBed` class is one of the principal Angular testing utilities.
Its API is quite large and can be overwhelming until you've explored it, a little at a time.
Read the early part of this guide first to get the basics before trying to absorb the full API.

The module definition passed to `configureTestingModule` is a subset of the `@NgModule` metadata properties.

```ts
type TestModuleMetadata = {
  providers?: any[];
  declarations?: any[];
  imports?: any[];
  schemas?: Array<SchemaMetadata | any[]>;
};
```

Each override method takes a `MetadataOverride<T>` where `T` is the kind of metadata appropriate to the method, that is, the parameter of an `@NgModule`, `@Component`, `@Directive`, or `@Pipe`.

```ts
type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```

The `TestBed` API consists of static class methods that either update or reference a _global_ instance of the `TestBed`.

Internally, all static methods cover methods of the current runtime `TestBed` instance, which is also returned by the `getTestBed()` function.

Call `TestBed` methods _within_ a `beforeEach()` to ensure a fresh start before each individual test.

Here are the most important static methods, in order of likely utility.

| Methods                  | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `configureTestingModule` | The testing shims establish the [initial test environment](guide/testing) and a default testing module. The default testing module is configured with basic declaratives and some Angular service substitutes that every tester needs. <br /> Call `configureTestingModule` to refine the testing module configuration for a particular set of tests by adding and removing imports, declarations $of components, directives, and pipes$, and providers.                                                                                               |
| `compileComponents`      | Compile the testing module asynchronously after you've finished configuring it. You **must** call this method if _any_ of the testing module components have asynchronously loaded resources (like @defer blocks).                                                                                                                                                                                                                                                                                                                                       |
| `createComponent<T>`     | Create an instance of a component of type `T` based on the current `TestBed` configuration. After calling `createComponent`, the `TestBed` configuration is frozen for the duration of the current spec.                                                                                                                                                                                                                                                                                                                                                 |
| `overrideComponent`      | Replace metadata for the given component class, which could be nested deeply within an inner module.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `overrideDirective`      | Replace metadata for the given directive class, which could be nested deeply within an inner module.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `overridePipe`           | Replace metadata for the given pipe class, which could be nested deeply within an inner module.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `overrideModule`         | Replace metadata for the given `NgModule`. Recall that modules can import other modules. The `overrideModule` method can reach deeply into the current testing module to modify one of these inner modules.                                                                                                                                                                                                                                                                                                                                              |
| `inject`                 | Retrieve a service from the current `TestBed` injector. The `inject` function is often adequate for this purpose. But `inject` throws an error if it can't provide the service. <br /> What if the service is optional? <br /> The `TestBed.inject()` method takes an optional second parameter, the object to return if Angular can't find the provider $`null` in this example$: `expect(TestBed.inject(NotProvided, null)).toBeNull();` After calling `TestBed.inject`, the `TestBed` configuration is frozen for the duration of the current spec. |
| `initTestEnvironment`    | Initialize the testing environment for the entire test run. <br /> The testing shims call it for you so there is rarely a reason for you to call it yourself. <br /> Call this method _exactly once_. To change this default in the middle of a test run, call `resetTestEnvironment` first. <br /> Specify a default Angular testing module and a `PlatformRef`. Alternatives for non-browser platforms are available in the general form `@angular/platform-<platform_name>/testing`.                                                                  |
| `resetTestEnvironment`   | Reset the initial test environment, including the default testing module.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

A few of the `TestBed` instance methods are not covered by static `TestBed` _class_ methods.
These are rarely needed.
-->

`TestBed`는 Angular의 주요 테스트 유틸리티 중 하나입니다.
API가 다양해서 조금씩 살펴보기 전에는 어렵게 느껴질 수 있습니다.
전체 API를 익히기 전에 이 가이드 앞부분에서 기초부터 알아보세요.

`configureTestingModule`에 전달하는 모듈 정의는 `@NgModule` 메타데이터 프로퍼티의 일부로 구성됩니다.

```ts
type TestModuleMetadata = {
  providers?: any[];
  declarations?: any[];
  imports?: any[];
  schemas?: Array<SchemaMetadata | any[]>;
};
```

각 재정의 메서드는 `MetadataOverride<T>`를 받습니다.
여기서 `T`는 해당 메서드에 맞는 메타데이터 타입으로, `@NgModule`, `@Component`, `@Directive`, `@Pipe`의 인자 타입입니다.

```ts
type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```

`TestBed` API는 _전역_ `TestBed` 인스턴스를 수정하거나 참조하는 정적 클래스 메서드로 구성됩니다.

내부적으로 모든 정적 메서드는 현재 실행 중인 `TestBed` 인스턴스의 메서드를 호출합니다.
이 인스턴스는 `getTestBed()` 함수로도 가져올 수 있습니다.

각 테스트가 새로운 상태에서 시작하도록 `beforeEach()` _안에서_ `TestBed` 메서드를 실행하세요.

중요한 정적 메서드를 활용도가 높은 순서로 정리하면 다음과 같습니다.

| 메서드                   | 설명                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `configureTestingModule` | 테스트 지원 코드가 [초기 테스트 환경](guide/testing)과 기본 테스트 모듈을 구성합니다. 기본 테스트 모듈에는 테스트에 필요한 기본 선언과 일부 Angular 서비스의 대체 구현이 설정됩니다. <br /> 특정 테스트 모음에 맞게 imports, 컴포넌트·디렉티브·파이프의 declarations, providers를 추가하거나 제거하려면 `configureTestingModule`을 실행하세요.                                                                                                                                         |
| `compileComponents`      | 설정을 마친 테스트 모듈을 비동기로 컴파일합니다. 테스트 모듈의 컴포넌트 중 _하나라도_ 비동기로 로드하는 리소스(예: @defer 블록)가 있으면 **반드시** 실행해야 합니다.                                                                                                                                                                                                                                                                                                                   |
| `createComponent<T>`     | 현재 `TestBed` 설정으로 `T` 타입의 컴포넌트 인스턴스를 생성합니다. `createComponent`를 실행하면 현재 테스트가 끝날 때까지 `TestBed` 설정이 고정됩니다.                                                                                                                                                                                                                                                                                                                                 |
| `overrideComponent`      | 지정한 컴포넌트 클래스의 메타데이터를 교체합니다. 내부 모듈에 깊게 중첩된 컴포넌트도 교체할 수 있습니다.                                                                                                                                                                                                                                                                                                                                                                               |
| `overrideDirective`      | 지정한 디렉티브 클래스의 메타데이터를 교체합니다. 내부 모듈에 깊게 중첩된 디렉티브도 교체할 수 있습니다.                                                                                                                                                                                                                                                                                                                                                                               |
| `overridePipe`           | 지정한 파이프 클래스의 메타데이터를 교체합니다. 내부 모듈에 깊게 중첩된 파이프도 교체할 수 있습니다.                                                                                                                                                                                                                                                                                                                                                                                   |
| `overrideModule`         | 지정한 `NgModule`의 메타데이터를 교체합니다. 모듈은 다른 모듈을 로드할 수 있으므로, `overrideModule`로 현재 테스트 모듈 안에 깊게 중첩된 내부 모듈도 수정할 수 있습니다.                                                                                                                                                                                                                                                                                                               |
| `inject`                 | 현재 `TestBed` 인젝터에서 서비스를 가져옵니다. 보통은 `inject` 함수로 충분하지만, 서비스를 제공할 수 없으면 오류가 발생합니다. <br /> 선택적인 서비스라면 어떻게 할까요? <br /> `TestBed.inject()`의 두 번째 인자에 Angular가 프로바이더를 찾지 못했을 때 반환할 객체를 선택적으로 지정할 수 있습니다. 다음 예제에서는 `null`을 반환합니다. `expect(TestBed.inject(NotProvided, null)).toBeNull();` `TestBed.inject`를 실행하면 현재 테스트가 끝날 때까지 `TestBed` 설정이 고정됩니다. |
| `initTestEnvironment`    | 전체 테스트 실행에 사용할 테스트 환경을 초기화합니다. <br /> 테스트 지원 코드가 대신 실행하므로 직접 실행할 일은 거의 없습니다. <br /> 이 메서드는 _정확히 한 번만_ 실행하세요. 테스트 실행 도중 이 기본 설정을 변경하려면 먼저 `resetTestEnvironment`를 실행하세요. <br /> 기본 Angular 테스트 모듈과 `PlatformRef`를 지정합니다. 브라우저가 아닌 플랫폼용 구현은 일반적으로 `@angular/platform-<platform_name>/testing` 형태로 제공됩니다.                                           |
| `resetTestEnvironment`   | 기본 테스트 모듈을 포함해서 초기 테스트 환경을 재설정합니다.                                                                                                                                                                                                                                                                                                                                                                                                                           |

일부 `TestBed` 인스턴스 메서드는 `TestBed` _클래스_ 의 정적 메서드로 제공하지 않습니다.
이런 메서드는 거의 사용할 일이 없습니다.

## `ComponentFixture`

<!--
The `TestBed.createComponent<T>` creates an instance of the component `T` and returns a strongly typed `ComponentFixture` for that component.

The `ComponentFixture` properties and methods provide access to the component, its DOM representation, and aspects of its Angular environment.
-->

`TestBed.createComponent<T>`는 `T` 컴포넌트의 인스턴스를 생성하고 해당 컴포넌트에 맞는 타입이 지정된 `ComponentFixture`를 반환합니다.

`ComponentFixture`의 프로퍼티와 메서드로 컴포넌트, 컴포넌트를 나타내는 DOM, 관련 Angular 환경에 접근할 수 있습니다.

### `ComponentFixture` 프로퍼티

<!--
Here are the most important properties for testers, in order of likely utility.

| Properties          | Details                                                                                                                                                                                                                                                                                   |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentInstance` | The instance of the component class created by `TestBed.createComponent`.                                                                                                                                                                                                                 |
| `debugElement`      | The `DebugElement` associated with the root element of the component. <br /> The `debugElement` provides insight into the component and its DOM element during test and debugging. It's a critical property for testers. The most interesting members are covered [below](#debugelement). |
| `nativeElement`     | The native DOM element at the root of the component.                                                                                                                                                                                                                                      |
| `changeDetectorRef` | The `ChangeDetectorRef` of the component's host view, not of the component itself. See [Using Zoneless in `TestBed`](guide/zoneless#using-zoneless-in-testbed).                                                                                                                           |
-->

테스트에 중요한 프로퍼티를 활용도가 높은 순서로 정리하면 다음과 같습니다.

| 프로퍼티            | 설명                                                                                                                                                                                                                                                |
| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentInstance` | `TestBed.createComponent`가 생성한 컴포넌트 클래스의 인스턴스입니다.                                                                                                                                                                                |
| `debugElement`      | 컴포넌트의 최상위 엘리먼트에 대응하는 `DebugElement`입니다. <br /> `debugElement`로 테스트와 디버깅 중에 컴포넌트와 DOM 엘리먼트를 자세히 확인할 수 있습니다. 테스트에서 핵심적인 프로퍼티입니다. 주요 멤버는 [아래](#debugelement)에서 알아봅니다. |
| `nativeElement`     | 컴포넌트의 최상위 네이티브 DOM 엘리먼트입니다.                                                                                                                                                                                                      |
| `changeDetectorRef` | 컴포넌트 자체가 아니라 컴포넌트 호스트 뷰의 `ChangeDetectorRef`입니다. [`TestBed`에서 Zoneless 사용하기](guide/zoneless#using-zoneless-in-testbed) 문서를 참고하세요.                                                                               |

### `ComponentFixture` 메서드

<!--
The _fixture_ methods cause Angular to perform certain tasks on the component tree.
Call these methods to trigger Angular behavior in response to simulated user action.

Here are the most useful methods for testers.

| Methods             | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detectChanges`     | Trigger a change detection cycle for the component. <br /> Call it to initialize the component $it calls `ngOnInit`$ and after your test code, change the component's data bound property values. Angular can't see that you've changed `personComponent.name` and won't update the `name` binding until you call `detectChanges`. <br /> Runs `checkNoChanges` afterwards to confirm that there are no circular updates unless called as `detectChanges(false)`;                                                                                                           |
| `autoDetectChanges` | Set this to `true` when you want the fixture to detect changes automatically. <br /> When autodetect is `true`, the test fixture calls `detectChanges` immediately after creating the component. Then it listens for pertinent zone events and calls `detectChanges` accordingly. When your test code modifies component property values directly, you probably still have to call `fixture.detectChanges` to trigger data binding updates. <br /> The default is `true` with zoneless change detection (the `TestBed` default) and `false` with Zone-based change detection. |
| `checkNoChanges`    | Do a change detection run to make sure there are no pending changes. Throws an exceptions if there are.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `isStable`          | If the fixture is currently _stable_, returns `true`. If there are async tasks that have not completed, returns `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `whenStable`        | Returns a promise that resolves when the fixture is stable. <br /> To resume testing after completion of asynchronous activity or asynchronous change detection, hook that promise. See [whenStable](guide/testing/components-scenarios#whenstable).                                                                                                                                                                                                                                                                                                                          |
| `destroy`           | Trigger component destruction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-->

_픽스처_ 메서드는 Angular가 컴포넌트 트리에 특정 작업을 실행하게 합니다.
사용자 동작을 재현한 뒤 이에 반응하는 Angular 동작을 실행하려면 이 메서드들을 사용하세요.

테스트에 유용한 메서드는 다음과 같습니다.

| 메서드              | 설명                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detectChanges`     | 컴포넌트의 변경 감지 사이클을 실행합니다. <br /> 컴포넌트를 초기화할 때 실행하면 `ngOnInit`도 실행됩니다. 테스트 코드에서 컴포넌트의 데이터 바인딩된 프로퍼티 값을 변경한 후에도 실행하세요. Angular는 `personComponent.name`을 직접 변경한 것을 알 수 없으므로, `detectChanges`를 실행하기 전에는 `name` 바인딩을 갱신하지 않습니다. <br /> `detectChanges(false)`로 실행하지 않았다면 이후 `checkNoChanges`를 실행해서 순환적인 갱신이 없는지 확인합니다.                             |
| `autoDetectChanges` | 픽스처가 자동으로 변화를 감지하게 하려면 `true`로 설정하세요. <br /> 자동 감지가 `true`이면 테스트 픽스처는 컴포넌트를 생성한 직후 `detectChanges`를 실행합니다. 이후 관련 존 이벤트를 감지해서 `detectChanges`를 실행합니다. 테스트 코드에서 컴포넌트 프로퍼티를 직접 수정했다면 데이터 바인딩을 갱신하기 위해 여전히 `fixture.detectChanges`를 실행해야 할 수 있습니다. <br /> 기본값은 Zoneless 변경 감지(`TestBed`의 기본값)에서는 `true`, Zone 기반 변경 감지에서는 `false`입니다. |
| `checkNoChanges`    | 변경 감지를 실행해서 처리할 변경사항이 남아 있지 않은지 확인합니다. 남아 있다면 예외를 발생시킵니다.                                                                                                                                                                                                                                                                                                                                                                                    |
| `isStable`          | 픽스처가 현재 _안정화_ 되어 있으면 `true`, 완료되지 않은 비동기 작업이 있으면 `false`를 반환합니다.                                                                                                                                                                                                                                                                                                                                                                                     |
| `whenStable`        | 픽스처가 안정화되면 이행되는 Promise를 반환합니다. <br /> 비동기 작업이나 비동기 변경 감지가 끝난 뒤 테스트를 이어가려면 이 Promise를 사용하세요. [whenStable](guide/testing/components-scenarios#whenstable)을 참고하세요.                                                                                                                                                                                                                                                             |
| `destroy`           | 컴포넌트를 종료합니다.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

#### `DebugElement`

<!--
The `DebugElement` provides crucial insights into the component's DOM representation.

From the test root component's `DebugElement` returned by `fixture.debugElement`, you can walk $and query$ the fixture's entire element and component subtrees.

Here are the most useful `DebugElement` members for testers, in approximate order of utility:

| Members               | Details                                                                                                                                                                                                                                                                                                                                         |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nativeElement`       | The corresponding DOM element in the browser                                                                                                                                                                                                                                                                                                    |
| `query`               | Calling `query(predicate: Predicate<DebugElement>)` returns the first `DebugElement` that matches the predicate at any depth in the subtree.                                                                                                                                                                                                    |
| `queryAll`            | Calling `queryAll(predicate: Predicate<DebugElement>)` returns all `DebugElements` that matches the predicate at any depth in subtree.                                                                                                                                                                                                          |
| `injector`            | The host dependency injector. For example, the root element's component instance injector.                                                                                                                                                                                                                                                      |
| `componentInstance`   | The element's own component instance, if it has one.                                                                                                                                                                                                                                                                                            |
| `context`             | An object that provides parent context for this element. Often an ancestor component instance that governs this element. <br /> When an element is repeated within `@for` block, the context is an `RepeaterContext` whose `$implicit` property is the value of the row instance value. For example, the `hero` in `@for(hero of heroes; ...)`. |
| `children`            | The immediate `DebugElement` children. Walk the tree by descending through `children`. `DebugElement` also has `childNodes`, a list of `DebugNode` objects. `DebugElement` derives from `DebugNode` objects and there are often more nodes than elements. Testers can usually ignore plain nodes.                                               |
| `parent`              | The `DebugElement` parent. Null if this is the root element.                                                                                                                                                                                                                                                                                    |
| `name`                | The element tag name, if it is an element.                                                                                                                                                                                                                                                                                                      |
| `triggerEventHandler` | Triggers the event by its name if there is a corresponding listener in the element's `listeners` collection. The second parameter is the _event object_ expected by the handler. <br /> If the event lacks a listener or there's some other problem, consider calling `nativeElement.dispatchEvent(eventObject)`.                               |
| `listeners`           | The callbacks attached to the component's `@Output` properties and/or the element's event properties.                                                                                                                                                                                                                                           |
| `providerTokens`      | This component's injector lookup tokens. Includes the component itself plus the tokens that the component lists in its `providers` metadata.                                                                                                                                                                                                    |
| `references`          | Dictionary of objects associated with template local variables $for example, `#foo`$, keyed by the local variable name.                                                                                                                                                                                                                       |

The `DebugElement.query(predicate)` and `DebugElement.queryAll(predicate)` methods take a predicate that filters the source element's subtree for matching `DebugElement`.

The predicate is any method that takes a `DebugElement` and returns a _truthy_ value.
The following example finds all `DebugElements` with a reference to a template local variable named "content":

```ts
// Filter for DebugElements with a #content reference
const contentRefs = el.queryAll((de) => de.references['content']);
```

The Angular `By` class has three static methods for common predicates:

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

`DebugElement`로 컴포넌트를 나타내는 DOM의 주요 정보를 확인할 수 있습니다.

`fixture.debugElement`가 반환하는 테스트 최상위 컴포넌트의 `DebugElement`에서 픽스처의 전체 엘리먼트 및 컴포넌트 하위 트리를 순회하거나 조회할 수 있습니다.

테스트에 유용한 `DebugElement` 멤버를 활용도가 높은 순서로 정리하면 다음과 같습니다.

| 멤버                  | 설명                                                                                                                                                                                                                                                                                                         |
| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nativeElement`       | 브라우저에서 대응하는 DOM 엘리먼트입니다.                                                                                                                                                                                                                                                                    |
| `query`               | `query(predicate: Predicate<DebugElement>)`를 실행하면 하위 트리의 깊이에 관계없이 조건식과 일치하는 첫 번째 `DebugElement`를 반환합니다.                                                                                                                                                                    |
| `queryAll`            | `queryAll(predicate: Predicate<DebugElement>)`를 실행하면 하위 트리의 깊이에 관계없이 조건식과 일치하는 모든 `DebugElement`를 반환합니다.                                                                                                                                                                    |
| `injector`            | 호스트 의존성 인젝터입니다. 예를 들어 최상위 엘리먼트에 있는 컴포넌트 인스턴스의 인젝터입니다.                                                                                                                                                                                                               |
| `componentInstance`   | 엘리먼트 자체의 컴포넌트 인스턴스가 있다면 해당 인스턴스입니다.                                                                                                                                                                                                                                              |
| `context`             | 엘리먼트의 부모 컨텍스트를 제공하는 객체입니다. 보통 이 엘리먼트를 관리하는 상위 컴포넌트 인스턴스입니다. <br /> `@for` 블록에서 엘리먼트를 반복하면 컨텍스트는 `RepeaterContext`가 됩니다. `$implicit` 프로퍼티는 해당 행의 인스턴스 값을 나타내며, `@for(hero of heroes; ...)`의 `hero`가 이에 해당합니다. |
| `children`            | 바로 아래에 있는 `DebugElement` 자식입니다. `children`을 따라 내려가며 트리를 순회할 수 있습니다. `DebugElement`에는 `DebugNode` 객체 목록인 `childNodes`도 있습니다. `DebugElement`는 `DebugNode`를 상속하며, 대체로 노드 수가 엘리먼트 수보다 많습니다. 테스트에서는 보통 일반 노드를 무시해도 됩니다.     |
| `parent`              | 부모 `DebugElement`입니다. 최상위 엘리먼트이면 null입니다.                                                                                                                                                                                                                                                   |
| `name`                | 엘리먼트라면 해당 엘리먼트의 태그 이름입니다.                                                                                                                                                                                                                                                                |
| `triggerEventHandler` | 엘리먼트의 `listeners` 모음에 대응하는 리스너가 있으면 이름으로 이벤트를 발생시킵니다. 두 번째 인자는 핸들러가 기대하는 _이벤트 객체_ 입니다. <br /> 이벤트에 리스너가 없거나 다른 문제가 있다면 `nativeElement.dispatchEvent(eventObject)` 실행을 고려하세요.                                               |
| `listeners`           | 컴포넌트의 `@Output` 프로퍼티나 엘리먼트의 이벤트 프로퍼티에 연결된 콜백입니다.                                                                                                                                                                                                                              |
| `providerTokens`      | 컴포넌트 인젝터의 조회 토큰입니다. 컴포넌트 자체와 컴포넌트의 `providers` 메타데이터에 나열한 토큰을 포함합니다.                                                                                                                                                                                             |
| `references`          | 템플릿 지역 변수(예: `#foo`)에 연결된 객체를 지역 변수 이름을 키로 저장한 사전입니다.                                                                                                                                                                                                                        |

`DebugElement.query(predicate)`와 `DebugElement.queryAll(predicate)` 메서드는 시작 엘리먼트의 하위 트리에서 일치하는 `DebugElement`를 필터링하는 조건식을 받습니다.

조건식은 `DebugElement`를 받고 _참으로 평가되는_ 값을 반환하는 메서드이면 됩니다.
다음 예제는 "content"라는 템플릿 지역 변수 참조가 있는 모든 `DebugElement`를 찾습니다.

```ts
// #content 참조가 있는 DebugElement를 필터링합니다
const contentRefs = el.queryAll((de) => de.references['content']);
```

Angular `By` 클래스는 자주 사용하는 조건식을 위한 정적 메서드 세 개를 제공합니다.

```ts
// CSS 셀렉터나 디렉티브로 DebugElement를 찾을 수 있습니다
const h2 = fixture.debugElement.query(By.css('h2'));
const directive = fixture.debugElement.query(By.directive(Highlight));
```

# 컴포넌트 하네스 개요

<!--
A <strong>component harness</strong> is a class that allows tests to interact with components the way an end user does via a supported API. You can create test harnesses for any component, ranging from small reusable widgets to full pages.

Harnesses offer several benefits:

- They make tests less brittle by insulating themselves against implementation details of a component, such as its DOM structure
- They make tests become more readable and easier to maintain
- They can be used across multiple testing environments

```ts
// Example of test with a harness for a component called MyButtonComponent
it('should load button with exact text', async () => {
  const button = await loader.getHarness(MyButtonComponentHarness);
  expect(await button.getText()).toBe('Confirm');
});
```

Component harnesses are especially useful for shared UI widgets. Developers often write tests that depend on private implementation details of widgets, such as DOM structure and CSS classes. Those dependencies make tests brittle and hard to maintain. Harnesses offer an alternative— a supported API that interacts with the widget the same way an end-user does. Widget implementation changes now become less likely to break user tests. For example, [Angular Material](https://material.angular.dev/components/categories) provides a test harness for each component in the library.

Component harnesses support multiple testing environments. You can use the same harness implementation in both unit and end-to-end tests. Test authors only need to learn one API and component authors don't have to maintain separate unit and end-to-end test implementations.

Many developers can be categorized by one of the following developer type categories: test authors, component harness authors, and harness environment authors. Use the table below to find the most relevant section in this guide based on these categories:

| Developer Type              | Description                                                                                                                                                                                                                                                                                            | Relevant Section                                                                                             |
| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| Test Authors                | Developers that use component harnesses written by someone else to test their application. For example, this could be an app developer who uses a third-party menu component and needs to interact with the menu in a unit test.                                                                       | [Using component harnesses in tests](guide/testing/using-component-harnesses)                                |
| Component harness authors   | Developers who maintain some reusable Angular components and want to create a test harness for its users to use in their tests. For example, an author of a third party Angular component library or a developer who maintains a set of common components for a large Angular application.             | [Creating component harnesses for your components](guide/testing/creating-component-harnesses)               |
| Harness environment authors | Developers who want to add support for using component harnesses in additional testing environments. For information on supported testing environments out-of-the-box, see the [test harness environments and loaders](guide/testing/using-component-harnesses#test-harness-environments-and-loaders). | [Adding support for additional testing environments](guide/testing/component-harnesses-testing-environments) |

For the full API reference, please see the [Angular CDK's component harness API reference page](/api#angular_cdk_testing).
-->

<strong>컴포넌트 하네스</strong>는 공식적으로 지원되는 API로 실제 사용자와 같은 방식으로 컴포넌트와 상호작용할 수 있게 하는 클래스입니다.
재사용하는 작은 위젯부터 페이지 전체까지 어떤 컴포넌트에도 테스트 하네스를 만들 수 있습니다.

하네스를 사용하면 다음과 같은 장점이 있습니다.

- 컴포넌트의 DOM 구조와 같은 내부 구현에 의존하지 않으므로 변경에 쉽게 깨지지 않는 테스트를 작성할 수 있습니다.
- 테스트를 읽기 쉽고 유지보수하기 편합니다.
- 여러 테스트 환경에서 사용할 수 있습니다.

```ts
// 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)은 라이브러리의 각 컴포넌트에 테스트 하네스를 제공합니다.

컴포넌트 하네스는 여러 테스트 환경을 지원합니다.
단위 테스트와 E2E 테스트에서 같은 하네스 구현을 사용할 수 있습니다.
테스트를 작성하는 개발자는 API 하나만 익히면 되고, 컴포넌트 개발자는 단위 테스트와 E2E 테스트용 구현을 따로 관리할 필요가 없습니다.

개발자는 테스트 작성자, 컴포넌트 하네스 작성자, 하네스 환경 작성자로 구분할 수 있습니다.
아래 표에서 해당하는 역할에 맞는 문서를 확인하세요.

| 개발자 역할            | 설명                                                                                                                                                                                                                                      | 관련 문서                                                                           |
| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- |
| 테스트 작성자          | 다른 사람이 만든 컴포넌트 하네스로 애플리케이션을 테스트하는 개발자입니다. 예를 들어 서드 파티 메뉴 컴포넌트를 사용하고 단위 테스트에서 메뉴와 상호작용해야 하는 애플리케이션 개발자가 해당합니다.                                        | [테스트에서 컴포넌트 하네스 사용하기](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는 [Angular CDK 컴포넌트 하네스 API 문서](/api#angular_cdk_testing)를 참고하세요.

# 테스트에서 컴포넌트 하네스 사용하기

## 시작하기 전에

팁: 이 문서는 [컴포넌트 하네스 개요](guide/testing/component-harnesses-overview)를 읽었다고 가정합니다.
컴포넌트 하네스를 처음 사용한다면 먼저 해당 문서를 읽어보세요.

### CDK 설치하기

<!--
The [Component Dev Kit (CDK)](https://material.angular.dev/cdk/categories) is a set of behavior primitives for building components. To use the component harnesses, first install `@angular/cdk` from npm. You can do this from your terminal using the Angular CLI:

```shell
ng add @angular/cdk
```
-->

[Component Dev Kit(CDK)](https://material.angular.dev/cdk/categories)는 컴포넌트의 동작을 구현하는 기본 요소 모음입니다.
컴포넌트 하네스를 사용하려면 먼저 npm에서 `@angular/cdk`를 설치해야 합니다.
터미널에서 Angular CLI로 설치할 수 있습니다.

```shell
ng add @angular/cdk
```

## 테스트 하네스 환경과 로더

<!--
You can use component test harnesses in different test environments. Angular CDK supports two built-in environments:

- Unit tests with Angular's `TestBed`
- End-to-end tests with [WebDriver](https://developer.mozilla.org/en-US/docs/Web/WebDriver)

Each environment provides a <strong>harness loader</strong>. The loader creates the harness instances you use throughout your tests. See below for more specific guidance on supported testing environments.

Additional testing environments require custom bindings. See the [adding harness support for additional testing environments guide](guide/testing/component-harnesses-testing-environments) for more information.
-->

컴포넌트 테스트 하네스는 여러 테스트 환경에서 사용할 수 있습니다.
Angular CDK는 두 가지 환경을 기본으로 지원합니다.

- Angular `TestBed`를 사용하는 단위 테스트
- [WebDriver](https://developer.mozilla.org/en-US/docs/Web/WebDriver)를 사용하는 E2E 테스트

각 환경은 <strong>하네스 로더</strong>를 제공합니다.
로더는 테스트에서 사용할 하네스 인스턴스를 생성합니다.
지원하는 테스트 환경별 사용 방법은 아래 내용을 참고하세요.

다른 테스트 환경을 사용하려면 별도의 연결 구현이 필요합니다.
자세한 내용은 [추가 테스트 환경에서 하네스 지원하기](guide/testing/component-harnesses-testing-environments)를 참고하세요.

### 단위 테스트에서 `TestbedHarnessEnvironment` 로더 사용하기

<!--
For unit tests you can create a harness loader from [TestbedHarnessEnvironment](/api/cdk/testing/testbed/TestbedHarnessEnvironment). This environment uses a [component fixture](api/core/testing/ComponentFixture) created by Angular's `TestBed`.

To create a harness loader rooted at the fixture's root element, use the `loader()` method:

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

To create a harness loader for harnesses for elements that fall outside the fixture, use the `documentRootLoader()` method. For example, code that displays a floating element or pop-up often attaches DOM elements directly to the document body, such as the `Overlay` service in Angular CDK.

You can also create a harness loader directly with `harnessForFixture()` for a harness at that fixture's root element directly.
-->

단위 테스트에서는 [TestbedHarnessEnvironment](/api/cdk/testing/testbed/TestbedHarnessEnvironment)로 하네스 로더를 만들 수 있습니다.
이 환경은 Angular `TestBed`로 생성한 [컴포넌트 픽스처](api/core/testing/ComponentFixture)를 사용합니다.

픽스처의 최상위 엘리먼트를 기준으로 하네스 로더를 만들려면 `loader()` 메서드를 사용하세요.

```ts
const fixture = TestBed.createComponent(MyComponent);

// 픽스처에서 하네스 로더를 생성합니다
const loader = TestbedHarnessEnvironment.loader(fixture);
...

// 로더로 하네스 인스턴스를 가져옵니다
const myComponentHarness = await loader.getHarness(MyComponent);
```

픽스처 바깥에 있는 엘리먼트의 하네스를 가져올 로더를 만들려면 `documentRootLoader()` 메서드를 사용하세요.
예를 들어 떠 있는 엘리먼트나 팝업을 표시하는 코드는 DOM 엘리먼트를 문서의 body에 직접 추가하는 경우가 많습니다.
Angular CDK의 `Overlay` 서비스가 이에 해당합니다.

픽스처의 최상위 엘리먼트에 있는 하네스는 `harnessForFixture()`로 직접 생성할 수도 있습니다.

### E2E 테스트에서 `SeleniumWebDriverHarnessEnvironment` 로더 사용하기

<!--
For WebDriver-based end-to-end tests you can create a harness loader with `SeleniumWebDriverHarnessEnvironment`.

Use the `loader()` method to get the harness loader instance for the current HTML document, rooted at the document's root element. This environment uses a WebDriver client.

```ts
let wd: webdriver.WebDriver = getMyWebDriverClient();
const loader = SeleniumWebDriverHarnessEnvironment.loader(wd);
...
const myComponentHarness = await loader.getHarness(MyComponent);
```
-->

WebDriver 기반 E2E 테스트에서는 `SeleniumWebDriverHarnessEnvironment`로 하네스 로더를 만들 수 있습니다.

`loader()` 메서드로 현재 HTML 문서의 최상위 엘리먼트를 기준으로 하는 하네스 로더 인스턴스를 가져오세요.
이 환경은 WebDriver 클라이언트를 사용합니다.

```ts
let wd: webdriver.WebDriver = getMyWebDriverClient();
const loader = SeleniumWebDriverHarnessEnvironment.loader(wd);
...
const myComponentHarness = await loader.getHarness(MyComponent);
```

## 하네스 로더 사용하기

<!--
Harness loader instances correspond to a specific DOM element and are used to create component harness instances for elements under that specific element.

To get `ComponentHarness` for the first instance of the element, use the `getHarness()` method. To get all `ComponentHarness` instances, use the `getAllHarnesses()` method.

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

In addition to `getHarness` and `getAllHarnesses`, `HarnessLoader` has several other useful methods for querying for harnesses:

- `getHarnessAtIndex(...)`: Gets the harness for a component that matches the given criteria at a specific index.
- `countHarnesses(...)`: Counts the number of component instances that match the given criteria.
- `hasHarness(...)`: Checks if at least one component instance matches the given criteria.

As an example, consider a reusable dialog-button component that opens a dialog on click. It contains the following components, each with a corresponding harness:

- `MyDialogButton` (composes the `MyButton` and `MyDialog` with a convenient API)
- `MyButton` (a standard button component)
- `MyDialog` (a dialog appended to `document.body` by `MyDialogButton` upon click)

The following test loads harnesses for each of these components:

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

하네스 로더 인스턴스는 특정 DOM 엘리먼트에 대응하며, 해당 엘리먼트 아래에 있는 엘리먼트의 컴포넌트 하네스 인스턴스를 생성합니다.

첫 번째 엘리먼트의 `ComponentHarness`를 가져오려면 `getHarness()` 메서드를 사용하세요.
모든 `ComponentHarness` 인스턴스를 가져오려면 `getAllHarnesses()` 메서드를 사용합니다.

```ts
// 첫 번째 엘리먼트의 하네스를 가져옵니다
const myComponentHarness = await loader.getHarness(MyComponent);

// 모든 엘리먼트의 하네스를 가져옵니다
const myComponentHarnesses = await loader.getAllHarnesses(MyComponent);
```

`HarnessLoader`에는 `getHarness`, `getAllHarnesses` 외에도 하네스를 조회하는 유용한 메서드가 있습니다.

- `getHarnessAtIndex(...)`: 주어진 조건과 일치하는 컴포넌트 중 특정 인덱스에 있는 컴포넌트의 하네스를 가져옵니다.
- `countHarnesses(...)`: 주어진 조건과 일치하는 컴포넌트 인스턴스의 개수를 구합니다.
- `hasHarness(...)`: 주어진 조건과 일치하는 컴포넌트 인스턴스가 하나 이상 있는지 확인합니다.

예를 들어 클릭하면 대화상자를 여는 재사용 가능한 대화상자 버튼 컴포넌트를 생각해 봅시다.
다음 컴포넌트로 구성되며 각각에 대응하는 하네스가 있습니다.

- `MyDialogButton`: `MyButton`과 `MyDialog`를 조합하고 편리한 API를 제공합니다.
- `MyButton`: 일반적인 버튼 컴포넌트입니다.
- `MyDialog`: 클릭했을 때 `MyDialogButton`이 `document.body`에 추가하는 대화상자입니다.

다음 테스트는 각 컴포넌트의 하네스를 로드합니다.

```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 () => {
  // `harnessForFixture`로 부트스트랩된 컴포넌트의 하네스를 로드합니다
  dialogButtonHarness = await TestbedHarnessEnvironment.harnessForFixture(
    fixture,
    MyDialogButtonHarness,
  );

// 버튼 엘리먼트가 픽스처의 최상위 엘리먼트 안에 있으므로 `loader`를 사용합니다.
  const buttonHarness = await loader.getHarness(MyButtonHarness);

// 버튼을 클릭해서 대화상자를 엽니다
  await buttonHarness.click();

// 대화상자는 픽스처의 최상위 엘리먼트 바깥인 `document.body`에 추가되므로
  // 이 경우에는 `rootLoader`를 사용합니다.
  const dialogHarness = await rootLoader.getHarness(MyDialogHarness);

// ... 결과를 검증합니다
});
```

### 환경에 따른 하네스 동작

하네스가 모든 환경에서 완전히 똑같이 동작하지는 않을 수 있습니다.
실제 사용자 상호작용과 단위 테스트에서 발생시키는 가상 이벤트 사이에는 피할 수 없는 차이가 있습니다.
Angular CDK는 가능한 범위에서 동작을 일관되게 맞춥니다.

### 자식 엘리먼트와 상호작용하기

<!--
To interact with elements below the root element of this harness loader, use the `HarnessLoader` instance of a child element. For the first instance of the child element, use the `getChildLoader()` method. For all instances of the child element, use the `getAllChildLoaders()` method.

```ts
const myComponentHarness = await loader.getHarness(MyComponent);

// Get loader for first instance of child element with '.child' selector
const childLoader = await loader.getChildLoader('.child');

// Get loaders for all instances of child elements with '.child' selector
const allChildLoaders = await loader.getAllChildLoaders('.child');
```
-->

하네스 로더의 최상위 엘리먼트 아래에 있는 엘리먼트와 상호작용하려면 자식 엘리먼트의 `HarnessLoader` 인스턴스를 사용하세요.
첫 번째 자식 엘리먼트에는 `getChildLoader()`, 모든 자식 엘리먼트에는 `getAllChildLoaders()` 메서드를 사용합니다.

```ts
const myComponentHarness = await loader.getHarness(MyComponent);

// '.child' 셀렉터와 일치하는 첫 번째 자식 엘리먼트의 로더를 가져옵니다
const childLoader = await loader.getChildLoader('.child');

// '.child' 셀렉터와 일치하는 모든 자식 엘리먼트의 로더를 가져옵니다
const allChildLoaders = await loader.getAllChildLoaders('.child');
```

### 하네스 필터링하기

<!--
When a page contains multiple instances of a particular component, you may want to filter based on some property of the component to get a particular component instance. You can use a <strong>harness predicate</strong>, a class used to associate a `ComponentHarness` class with predicates functions that can be used to filter component instances, to do so.

When you ask a `HarnessLoader` for a harness, you're actually providing a HarnessQuery. A query can be one of two things:

- A harness constructor. This just gets that harness
- A `HarnessPredicate`, which gets harnesses that are filtered based on one or more conditions

`HarnessPredicate` does support some base filters (selector, ancestor) that work on anything that extends `ComponentHarness`.

```ts
// Example of loading a MyButtonComponentHarness with a harness predicate
const disabledButtonPredicate = new HarnessPredicate(MyButtonComponentHarness, {
  selector: '[disabled]',
});
const disabledButton = await loader.getHarness(disabledButtonPredicate);
```

However it's common for harnesses to implement a static `with()` method that accepts component-specific filtering options and returns a `HarnessPredicate`.

```ts
// Example of loading a MyButtonComponentHarness with a specific selector
const button = await loader.getHarness(MyButtonComponentHarness.with({selector: 'btn'}));
```

For more details refer to the specific harness documentation since additional filtering options are specific to each harness implementation.
-->

페이지에 같은 컴포넌트의 인스턴스가 여러 개 있으면 컴포넌트 프로퍼티를 기준으로 필터링해서 특정 인스턴스를 가져와야 할 수 있습니다.
이때 <strong>하네스 조건식</strong>을 사용할 수 있습니다.
하네스 조건식은 `ComponentHarness` 클래스와 컴포넌트 인스턴스를 필터링하는 조건식 함수를 연결하는 클래스입니다.

`HarnessLoader`에 하네스를 요청할 때 실제로 전달하는 것은 HarnessQuery입니다.
쿼리는 다음 두 가지 중 하나입니다.

- 하네스 생성자: 해당 하네스를 가져옵니다.
- `HarnessPredicate`: 하나 이상의 조건으로 필터링한 하네스를 가져옵니다.

`HarnessPredicate`는 `ComponentHarness`를 상속하는 모든 클래스에 사용할 수 있는 기본 필터(selector, ancestor)를 지원합니다.

```ts
// 하네스 조건식으로 MyButtonComponentHarness를 로드하는 예제
const disabledButtonPredicate = new HarnessPredicate(MyButtonComponentHarness, {
  selector: '[disabled]',
});
const disabledButton = await loader.getHarness(disabledButtonPredicate);
```

하지만 보통 하네스에는 컴포넌트별 필터 옵션을 받고 `HarnessPredicate`를 반환하는 `with()` 정적 메서드를 구현합니다.

```ts
// 특정 셀렉터로 MyButtonComponentHarness를 로드하는 예제
const button = await loader.getHarness(MyButtonComponentHarness.with({selector: 'btn'}));
```

추가 필터 옵션은 하네스 구현마다 다르므로 자세한 내용은 각 하네스 문서를 참고하세요.

## 테스트 하네스 API 사용하기

<!--
While every harness defines an API specific to its corresponding component, they all share a common base class, [ComponentHarness](/api/cdk/testing/ComponentHarness). This base class defines a static property, `hostSelector`, that matches the harness class to instances of the component in the DOM.

Beyond that, the API of any given harness is specific to its corresponding component; refer to the component's documentation to learn how to use a specific harness.

As an example, the following is a test for a component that uses the [Angular Material slider component harness](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);
});
```
-->

각 하네스는 해당 컴포넌트에 맞는 API를 정의하지만, 모두 [ComponentHarness](/api/cdk/testing/ComponentHarness)라는 공통 기본 클래스를 사용합니다.
이 기본 클래스의 `hostSelector` 정적 프로퍼티는 하네스 클래스와 DOM의 컴포넌트 인스턴스를 연결합니다.

그 외의 하네스 API는 해당 컴포넌트마다 다릅니다.
특정 하네스의 사용 방법은 컴포넌트 문서를 참고하세요.

예를 들어 다음은 [Angular Material 슬라이더 컴포넌트 하네스](https://material.angular.dev/components/slider/api#MatSliderHarness)를 사용하는 컴포넌트 테스트입니다.

## Angular 변경 감지와 연동하기

<!--
By default, test harnesses runs Angular's [change detection](/best-practices/runtime-performance) before reading the state of a DOM element and after interacting with a DOM element.

There may be times that you need finer-grained control over change detection in your tests. such as checking the state of a component while an async operation is pending. In these cases use the `manualChangeDetection` function to disable automatic handling of change detection for a block of code.

```ts
it('checks state while async action is in progress', async () => {
  const buttonHarness = await 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);
  });
});
```

Almost all harness methods are asynchronous and return a `Promise` to support the following:

- Support for unit tests
- Support for end-to-end tests
- Insulate tests against changes in asynchronous behavior

The Angular team recommends using [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) to improve the test readability. Calling `await` blocks the execution of your test until the associated `Promise` resolves.

Occasionally, you may want to perform multiple actions simultaneously and wait until they're all done rather than performing each action sequentially. For example, read multiple properties of a single component. In these situations use the `parallel` function to parallelize the operations. The parallel function works similarly to `Promise.all`, while also optimizing change detection checks.

```ts
it('reads properties in parallel', async () => {
  const checkboxHarness = await 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);
});
```
-->

테스트 하네스는 기본으로 DOM 엘리먼트의 상태를 읽기 전과 DOM 엘리먼트와 상호작용한 후에 Angular [변경 감지](/best-practices/runtime-performance)를 실행합니다.

비동기 작업이 진행 중일 때 컴포넌트 상태를 확인하는 등, 테스트에서 변경 감지를 더 세밀하게 제어해야 할 수 있습니다.
이때는 `manualChangeDetection` 함수로 특정 코드 블록의 자동 변경 감지 처리를 비활성화하세요.

```ts
it('checks state while async action is in progress', async () => {
  const buttonHarness = await loader.getHarness(MyButtonHarness);
  await manualChangeDetection(async () => {
    await buttonHarness.click();
    fixture.detectChanges();
    // 비동기 클릭 동작이 진행 중일 때 예상한 상태인지 확인합니다.
    expect(isProgressSpinnerVisible()).toBe(true);
    await fixture.whenStable();
    // 비동기 클릭 동작이 끝난 후 예상한 상태인지 확인합니다.
    expect(isProgressSpinnerVisible()).toBe(false);
  });
});
```

거의 모든 하네스 메서드는 다음 목적을 위해 비동기로 동작하고 `Promise`를 반환합니다.

- 단위 테스트 지원
- E2E 테스트 지원
- 비동기 동작이 변경되어도 테스트가 영향을 받지 않도록 보호

Angular 팀은 테스트의 가독성을 높이기 위해 [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) 사용을 권장합니다.
`await`를 사용하면 해당 `Promise`가 이행될 때까지 테스트 실행을 기다립니다.

각 동작을 순서대로 실행하지 않고 여러 동작을 동시에 실행한 뒤 모두 끝날 때까지 기다려야 할 때도 있습니다.
컴포넌트 하나의 여러 프로퍼티를 읽는 경우가 예입니다.
이때는 `parallel` 함수로 작업을 병렬 실행하세요.
이 함수는 `Promise.all`과 비슷하게 동작하면서 변경 감지 검사도 최적화합니다.

```ts
it('reads properties in parallel', async () => {
  const checkboxHarness = await loader.getHarness(MyCheckboxHarness);
  // checked와 intermediate 프로퍼티를 동시에 읽습니다.
  const [checked, indeterminate] = await parallel(() => [
    checkboxHarness.isChecked(),
    checkboxHarness.isIndeterminate(),
  ]);
  expect(checked).toBe(false);
  expect(indeterminate).toBe(true);
});
```

# 컴포넌트 하네스 만들기

## 시작하기 전에

### 테스트 하네스를 만들면 좋은 경우

<!--
The Angular team recommends creating component test harnesses for shared components that are used in many places and have some user interactivity. This most commonly applies to widget libraries and similar reusable components. Harnesses are valuable for these cases because they provide the consumers of these shared components a well- supported API for interacting with a component. Tests that use harnesses can avoid depending on unreliable implementation details of these shared components, such as DOM structure and specific event listeners.

For components that appear in only one place, such as a page in an application, harnesses don't provide as much benefit. In these situations, a component's tests can reasonably depend on the implementation details of this component, as the tests and components are updated at the same time. However, harnesses still provide some value if you would use the harness in both unit and end-to-end tests.
-->

Angular 팀은 여러 곳에서 사용하고 사용자와 상호작용하는 공유 컴포넌트에 테스트 하네스를 만드는 것을 권장합니다.
위젯 라이브러리나 이와 비슷한 재사용 컴포넌트가 주로 해당합니다.
하네스는 공유 컴포넌트 사용자에게 컴포넌트와 상호작용할 수 있는 안정적으로 지원되는 API를 제공합니다.
하네스로 테스트하면 DOM 구조나 특정 이벤트 리스너처럼 바뀔 수 있는 공유 컴포넌트의 내부 구현에 의존하지 않아도 됩니다.

애플리케이션의 페이지처럼 한 곳에서만 사용하는 컴포넌트는 하네스의 이점이 크지 않습니다.
이런 경우에는 테스트와 컴포넌트를 함께 수정하므로 테스트가 컴포넌트의 내부 구현에 의존해도 무리가 없습니다.
다만 단위 테스트와 E2E 테스트에서 하네스를 함께 사용한다면 여전히 도움이 됩니다.

### CDK 설치하기

```shell
ng add @angular/cdk
```
-->

```shell
ng add @angular/cdk
```

## `ComponentHarness` 상속하기

<!--
The abstract `ComponentHarness` class is the base class for all component harnesses. To create a custom component harness, extend `ComponentHarness` and implement the static property `hostSelector`.

The `hostSelector` property identifies elements in the DOM that match this harness subclass. In most cases, the `hostSelector` should be the same as the selector of the corresponding `Component` or `Directive`. For example, consider a simple popup component:

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

In this case, a minimal harness for the component would look like the following:

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';
}
```

While `ComponentHarness` subclasses require only the `hostSelector` property, most harnesses should also implement a static `with` method to generate `HarnessPredicate` instances. The [filtering harnesses section](guide/testing/using-component-harnesses#filtering-harnesses) covers this in more detail.
-->

추상 클래스 `ComponentHarness`는 모든 컴포넌트 하네스의 기본 클래스입니다.
커스텀 컴포넌트 하네스를 만들려면 `ComponentHarness`를 상속하고 `hostSelector` 정적 프로퍼티를 구현하세요.

`hostSelector` 프로퍼티는 이 하네스 하위 클래스에 대응하는 DOM 엘리먼트를 식별합니다.
대부분의 경우 해당 `Component`나 `Directive`의 셀렉터와 같은 값을 사용하면 됩니다.
간단한 팝업 컴포넌트를 예로 살펴봅시다.

isOpen = signal(false);

toggle() {
    this.isOpen.update((value) => !value);
  }
}
```

이 컴포넌트의 최소한의 하네스는 다음과 같습니다.

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';
}
```

`ComponentHarness` 하위 클래스에서 반드시 필요한 것은 `hostSelector` 프로퍼티뿐이지만, 대부분의 하네스에는 `HarnessPredicate` 인스턴스를 생성하는 `with` 정적 메서드도 구현하는 것이 좋습니다.
자세한 내용은 [하네스 필터링하기](guide/testing/using-component-harnesses#filtering-harnesses)를 참고하세요.

## 컴포넌트 DOM에서 엘리먼트 찾기

<!--
Each instance of a `ComponentHarness` subclass represents a particular instance of the corresponding component. You can access the component's host element via the `host() `method from the `ComponentHarness` base class.

`ComponentHarness` also offers several methods for locating elements within the component's DOM. These methods are `locatorFor()`, `locatorForOptional()`, and `locatorForAll()`. These methods create functions that find elements, they do not directly find elements. This approach safeguards against caching references to out-of-date elements. For example, when an `@if` block hides and then shows an element, the result is a new DOM element; using functions ensures that tests always reference the current state of the DOM.

See the [ComponentHarness API reference page](/api/cdk/testing/ComponentHarness) for the full list details of the different `locatorFor` methods.

For example, the `MyPopupHarness` example discussed above could provide methods to get the trigger and content elements as follows:

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

`ComponentHarness` 하위 클래스의 각 인스턴스는 해당 컴포넌트의 특정 인스턴스를 나타냅니다.
기본 클래스 `ComponentHarness`의 `host() `메서드로 컴포넌트의 호스트 엘리먼트에 접근할 수 있습니다.

`ComponentHarness`는 컴포넌트 DOM 안에서 엘리먼트를 찾는 `locatorFor()`, `locatorForOptional()`, `locatorForAll()` 메서드도 제공합니다.
이 메서드들은 엘리먼트를 직접 찾는 대신 엘리먼트를 찾는 함수를 만듭니다.
이 방식은 더 이상 유효하지 않은 엘리먼트 참조가 캐싱되는 것을 방지합니다.
예를 들어 `@if` 블록이 엘리먼트를 숨겼다가 다시 표시하면 새로운 DOM 엘리먼트가 생성됩니다.
함수를 사용하면 테스트가 항상 현재 DOM 상태를 참조할 수 있습니다.

각 `locatorFor` 메서드의 전체 목록과 자세한 내용은 [ComponentHarness API 문서](/api/cdk/testing/ComponentHarness)를 참고하세요.

앞에서 살펴본 `MyPopupHarness`에 트리거 엘리먼트와 내용 엘리먼트를 가져오는 메서드를 추가하면 다음과 같습니다.

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

// 트리거 엘리먼트를 가져옵니다
  getTriggerElement = this.locatorFor('button');

// 내용 엘리먼트를 가져옵니다.
  getContentElement = this.locatorForOptional('.my-popup-content');
}
```

## `TestElement` 인스턴스 사용하기

<!--
`TestElement` is an abstraction designed to work across different test environments (Unit tests, WebDriver, etc). When using harnesses, you should perform all DOM interaction via this interface. Other means of accessing DOM elements, such as `document.querySelector()`, do not work in all test environments.

`TestElement` has a number of methods to interact with the underlying DOM, such as `blur()`, `click()`, `getAttribute()`, and more. See the [TestElement API reference page](/api/cdk/testing/TestElement) for the full list of methods.

Do not expose `TestElement` instances to harness users unless it's an element the component consumer defines directly, such as the component's host element. Exposing `TestElement` instances for internal elements leads users to depend on a component's internal DOM structure.

Instead, provide more narrow-focused methods for specific actions the end-user may take or particular state they may observe. For example, `MyPopupHarness` from previous sections could provide methods like `toggle` and `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;
  }
}
```
-->

`TestElement`는 단위 테스트, WebDriver 등 여러 테스트 환경에서 동작하도록 만든 추상화입니다.
하네스를 사용할 때는 이 인터페이스로만 DOM과 상호작용해야 합니다.
`document.querySelector()`처럼 DOM 엘리먼트에 접근하는 다른 방법은 모든 테스트 환경에서 동작하지 않습니다.

`TestElement`는 `blur()`, `click()`, `getAttribute()` 등 DOM과 상호작용하는 여러 메서드를 제공합니다.
전체 메서드는 [TestElement API 문서](/api/cdk/testing/TestElement)를 참고하세요.

컴포넌트의 호스트 엘리먼트처럼 컴포넌트 사용자가 직접 정의한 엘리먼트가 아니라면 하네스 사용자에게 `TestElement` 인스턴스를 공개하지 마세요.
내부 엘리먼트의 `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');

/** 팝업의 열림 상태를 전환합니다. */
  async toggle() {
    const trigger = await this.getTriggerElement();
    return trigger.click();
  }

/** 팝업이 열려 있는지 확인합니다. */
  async isOpen() {
    const content = await this.getContentElement();
    return !!content;
  }
}
```

## 하위 컴포넌트 하네스 로드하기

<!--
Larger components often compose sub-components. You can reflect this structure in a component's harness as well. Each of the `locatorFor` methods on `ComponentHarness` has an alternate signature that can be used for locating sub-harnesses rather than elements.

See the [ComponentHarness API reference page](/api/cdk/testing/ComponentHarness) for the full list of the different locatorFor methods.

For example, consider a menu build using the popup from above:

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

The harness for `MyMenu` can then take advantage of other harnesses for `MyPopup` and `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';
}
```
-->

큰 컴포넌트는 여러 하위 컴포넌트로 구성되는 경우가 많습니다.
컴포넌트 하네스에도 이 구조를 반영할 수 있습니다.
`ComponentHarness`의 각 `locatorFor` 메서드는 엘리먼트 대신 하위 하네스를 찾는 시그니처도 제공합니다.

각 locatorFor 메서드의 전체 목록은 [ComponentHarness API 문서](/api/cdk/testing/ComponentHarness)를 참고하세요.

위에서 살펴본 팝업으로 메뉴를 구성한 예제를 보겠습니다.

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

그러면 `MyMenu` 하네스는 `MyPopup`, `MyMenuItem`의 하네스를 활용할 수 있습니다.

```ts
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

protected getPopupHarness = this.locatorFor(MyPopupHarness);

/** 현재 표시된 메뉴 항목을 가져옵니다. 메뉴가 닫혀 있으면 빈 목록을 반환합니다. */
  getItems = this.locatorForAll(MyMenuItemHarness);

/** 메뉴의 열림 상태를 전환합니다. */
  async toggle() {
    const popupHarness = await this.getPopupHarness();
    return popupHarness.toggle();
  }
}

class MyMenuItemHarness extends ComponentHarness {
  static hostSelector = 'my-menu-item';
}
```

## `HarnessPredicate`로 하네스 인스턴스 필터링하기

<!--
When a page contains multiple instances of a particular component, you may want to filter based on some property of the component to get a particular component instance. For example, you may want a button with some specific text, or a menu with a specific ID. The `HarnessPredicate` class can capture criteria like this for a `ComponentHarness` subclass. While the test author is able to construct `HarnessPredicate` instances manually, it's easier when the `ComponentHarness` subclass provides a helper method to construct predicates for common filters.

You should create a static `with()` method on each `ComponentHarness` subclass that returns a `HarnessPredicate` for that class. This allows test authors to write easily understandable code, e.g. `loader.getHarness(MyMenuHarness.with({selector: '#menu1'}))`. In addition to the standard selector and ancestor options, the `with` method should add any other options that make sense for the particular subclass.

Harnesses that need to add additional options should extend the `BaseHarnessFilters` interface and additional optional properties as needed. `HarnessPredicate` provides several convenience methods for adding options: `stringMatches()`, `addOption()`, and `add()`. See the [HarnessPredicate API page](/api/cdk/testing/HarnessPredicate) for the full description.

For example, when working with a menu it is useful to filter based on trigger text and to filter menu items based on their text:

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

You can pass a `HarnessPredicate` instead of a `ComponentHarness` class to any of the APIs on `HarnessLoader`, `LocatorFactory`, or `ComponentHarness`. This allows test authors to easily target a particular component instance when creating a harness instance. It also allows the harness author to leverage the same `HarnessPredicate` to enable more powerful APIs on their harness class. For example, consider the `getItems` method on the `MyMenuHarness` shown above. Adding a filtering API allows users of the harness to search for particular menu items:

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

페이지에 같은 컴포넌트의 인스턴스가 여러 개 있으면 컴포넌트 프로퍼티로 필터링해서 특정 인스턴스를 가져와야 할 수 있습니다.
특정 텍스트가 있는 버튼이나 특정 ID를 가진 메뉴를 찾는 경우가 예입니다.
`HarnessPredicate` 클래스는 `ComponentHarness` 하위 클래스에 이런 조건을 지정할 수 있습니다.
테스트 작성자가 `HarnessPredicate` 인스턴스를 직접 만들 수도 있지만, `ComponentHarness` 하위 클래스에서 자주 사용하는 필터의 조건식을 생성하는 헬퍼 메서드를 제공하면 더 편리합니다.

각 `ComponentHarness` 하위 클래스에 해당 클래스의 `HarnessPredicate`를 반환하는 `with()` 정적 메서드를 만드세요.
그러면 테스트 작성자는 `loader.getHarness(MyMenuHarness.with({selector: '#menu1'}))`처럼 이해하기 쉬운 코드를 작성할 수 있습니다.
`with` 메서드에는 기본 selector, ancestor 옵션 외에도 해당 하위 클래스에 유용한 옵션을 추가하는 것이 좋습니다.

옵션을 추가해야 하는 하네스는 `BaseHarnessFilters` 인터페이스를 상속하고 필요한 선택적 프로퍼티를 추가하세요.
`HarnessPredicate`는 `stringMatches()`, `addOption()`, `add()`처럼 옵션 추가를 돕는 메서드를 제공합니다.
자세한 내용은 [HarnessPredicate API 문서](/api/cdk/testing/HarnessPredicate)를 참고하세요.

예를 들어 메뉴를 다룰 때는 트리거 텍스트로 메뉴를 필터링하고, 항목의 텍스트로 메뉴 항목을 필터링하면 유용합니다.

```ts
interface MyMenuHarnessFilters extends BaseHarnessFilters {
  /** 메뉴의 트리거 텍스트로 필터링합니다. */
  triggerText?: string | RegExp;
}

interface MyMenuItemHarnessFilters extends BaseHarnessFilters {
  /** 메뉴 항목의 텍스트로 필터링합니다. */
  text?: string | RegExp;
}

class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

/** 특정 `MyMenuHarness`를 찾는 `HarnessPredicate`를 생성합니다. */
  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);

/** 메뉴 트리거의 텍스트를 가져옵니다. */
  async getTriggerText(): Promise<string> {
    const popupHarness = await this.getPopupHarness();
    return popupHarness.getTriggerText();
  }
}

class MyMenuItemHarness extends ComponentHarness {
  static hostSelector = 'my-menu-item';

/** 특정 `MyMenuItemHarness`를 찾는 `HarnessPredicate`를 생성합니다. */
  static with(options: MyMenuItemHarnessFilters): HarnessPredicate<MyMenuItemHarness> {
    return new HarnessPredicate(MyMenuItemHarness, options).addOption(
      'text',
      options.text,
      (harness, text) => HarnessPredicate.stringMatches(harness.getText(), text),
    );
  }

/** 메뉴 항목의 텍스트를 가져옵니다. */
  async getText(): Promise<string> {
    const host = await this.host();
    return host.text();
  }
}
```

`HarnessLoader`, `LocatorFactory`, `ComponentHarness`의 모든 API에 `ComponentHarness` 클래스 대신 `HarnessPredicate`를 전달할 수 있습니다.
따라서 테스트 작성자는 특정 컴포넌트 인스턴스를 대상으로 하네스 인스턴스를 쉽게 생성할 수 있습니다.
하네스 작성자도 같은 `HarnessPredicate`를 활용해서 하네스 클래스에 더 강력한 API를 제공할 수 있습니다.
앞의 `MyMenuHarness`에 있는 `getItems` 메서드를 예로 살펴봅시다.
필터 API를 추가하면 하네스 사용자가 특정 메뉴 항목을 검색할 수 있습니다.

```ts
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

/** 메뉴 항목 목록을 가져옵니다. 선택적으로 주어진 조건에 따라 필터링합니다. */
  async getItems(filters: MyMenuItemHarnessFilters = {}): Promise<MyMenuItemHarness[]> {
    const getFilteredItems = this.locatorForAll(MyMenuItemHarness.with(filters));
    return getFilteredItems();
  }
  ...
}
```

## 콘텐츠 프로젝션을 사용하는 엘리먼트의 `HarnessLoader` 만들기

<!--
Some components project additional content into the component's template. See the [content projection guide](guide/components/content-projection) for more information.

Add a `HarnessLoader` instance scoped to the element containing the `<ng-content>` when you create a harness for a component that uses content projection. This allows the user of the harness to load additional harnesses for whatever components were passed in as content. `ComponentHarness` has several methods that can be used to create HarnessLoader instances for cases like this: `harnessLoaderFor()`, `harnessLoaderForOptional()`, `harnessLoaderForAll()`. See the [HarnessLoader interface API reference page](/api/cdk/testing/HarnessLoader) for more details.

For example, the `MyPopupHarness` example from above can extend `ContentContainerComponentHarness` to add support to load harnesses within the `<ng-content>` of the component.

```ts
class MyPopupHarness extends ContentContainerComponentHarness<string> {
  static hostSelector = 'my-popup';
}
```
-->

일부 컴포넌트는 추가 콘텐츠를 컴포넌트 템플릿 안에 투영합니다.
자세한 내용은 [콘텐츠 프로젝션](guide/components/content-projection) 문서를 참고하세요.

콘텐츠 프로젝션을 사용하는 컴포넌트의 하네스를 만들 때는 `<ng-content>`가 포함된 엘리먼트를 범위로 하는 `HarnessLoader` 인스턴스를 추가하세요.
그러면 하네스 사용자는 콘텐츠로 전달한 컴포넌트의 하네스도 로드할 수 있습니다.
`ComponentHarness`는 이런 경우에 HarnessLoader 인스턴스를 만드는 `harnessLoaderFor()`, `harnessLoaderForOptional()`, `harnessLoaderForAll()` 메서드를 제공합니다.
자세한 내용은 [HarnessLoader 인터페이스 API 문서](/api/cdk/testing/HarnessLoader)를 참고하세요.

예를 들어 앞의 `MyPopupHarness`가 `ContentContainerComponentHarness`를 상속하면 컴포넌트의 `<ng-content>` 안에 있는 하네스를 로드하도록 지원할 수 있습니다.

```ts
class MyPopupHarness extends ContentContainerComponentHarness<string> {
  static hostSelector = 'my-popup';
}
```

## 컴포넌트 호스트 엘리먼트 바깥에 접근하기

<!--
There are times when a component harness might need to access elements outside of its corresponding component's host element. For example, code that displays a floating element or pop-up often attaches DOM elements directly to the document body, such as the `Overlay` service in Angular CDK.

In this case, `ComponentHarness` provides a method that can be used to get a `LocatorFactory` for the root element of the document. The `LocatorFactory` supports most of the same APIs as the `ComponentHarness` base class, and can then be used to query relative to the document's root element.

Consider if the `MyPopup` component above used the CDK overlay for the popup content, rather than an element in its own template. In this case, `MyPopupHarness` would have to access the content element via `documentRootLocatorFactory()` method that gets a locator factory rooted at the document root.

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

컴포넌트 하네스가 해당 컴포넌트의 호스트 엘리먼트 바깥에 접근해야 할 때도 있습니다.
예를 들어 떠 있는 엘리먼트나 팝업을 표시하는 코드는 DOM 엘리먼트를 문서의 body에 직접 추가하는 경우가 많습니다.
Angular CDK의 `Overlay` 서비스가 이에 해당합니다.

이런 경우를 위해 `ComponentHarness`는 문서의 최상위 엘리먼트에 대한 `LocatorFactory`를 가져오는 메서드를 제공합니다.
`LocatorFactory`는 기본 클래스 `ComponentHarness`와 거의 같은 API를 지원하며, 문서의 최상위 엘리먼트를 기준으로 쿼리할 수 있습니다.

위의 `MyPopup` 컴포넌트가 자체 템플릿의 엘리먼트 대신 CDK 오버레이로 팝업 내용을 표시한다고 가정해 봅시다.
이 경우 `MyPopupHarness`는 문서 최상위를 기준으로 하는 로케이터 팩토리를 가져오는 `documentRootLocatorFactory()` 메서드로 내용 엘리먼트에 접근해야 합니다.

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

/** 팝업의 내용 엘리먼트를 최상위로 하는 `HarnessLoader`를 가져옵니다. */
  async getHarnessLoaderForContent(): Promise<HarnessLoader> {
    const rootLocator = this.documentRootLocatorFactory();
    return rootLocator.harnessLoaderFor('my-popup-content');
  }
}
```

## 비동기 작업 기다리기

<!--
The methods on `TestElement` automatically trigger Angular's change detection and wait for tasks inside the `NgZone`. In most cases no special effort is required for harness authors to wait on asynchronous tasks. However, there are some edge cases where this may not be sufficient.

Under some circumstances, Angular animations may require a second cycle of change detection and subsequent `NgZone` stabilization before animation events are fully flushed. In cases where this is needed, the `ComponentHarness` offers a `forceStabilize()` method that can be called to do the second round.

You can use `NgZone.runOutsideAngular()` to schedule tasks outside of NgZone. Call the `waitForTasksOutsideAngular()` method on the corresponding harness if you need to explicitly wait for tasks outside `NgZone` since this does not happen automatically.
-->

`TestElement`의 메서드는 Angular 변경 감지를 자동으로 실행하고 `NgZone` 안의 작업을 기다립니다.
대부분의 경우 하네스 작성자가 비동기 작업을 기다리기 위해 별도로 처리할 것은 없습니다.
하지만 이것만으로 부족한 예외적인 경우도 있습니다.

상황에 따라 Angular 애니메이션 이벤트를 모두 처리하려면 변경 감지를 한 번 더 실행하고 이후 `NgZone` 안정화까지 기다려야 할 수 있습니다.
이런 경우에는 `ComponentHarness`의 `forceStabilize()` 메서드로 두 번째 과정을 실행할 수 있습니다.

`NgZone.runOutsideAngular()`로 NgZone 바깥에 작업을 예약할 수도 있습니다.
`NgZone` 바깥의 작업은 자동으로 기다리지 않으므로, 명시적으로 기다려야 한다면 해당 하네스의 `waitForTasksOutsideAngular()` 메서드를 실행하세요.

# `animate.enter`와 `animate.leave`로 애플리케이션에 애니메이션 적용하기

<!--
Well-designed animations can make your application more intuitive and engaging, but they aren't just cosmetic.
Animations can improve your application and the user experience in a number of ways:

- Without animations, web page transitions can seem abrupt and jarring
- Motion greatly enhances the user experience, so animations give users a chance to detect the application's response to their actions
- Good animations can smoothly direct the user's attention throughout a workflow

Angular provides `animate.enter` and `animate.leave` to animate your application's elements. These two features apply enter and leave CSS classes at the appropriate times or call functions to apply animations from third party libraries. `animate.enter` and `animate.leave` are not directives. They are special API supported directly by the Angular compiler. They can be used directly on elements and also as a host binding.
-->

잘 설계된 애니메이션은 애플리케이션을 더 직관적이고 매력적으로 만듭니다.
하지만 애니메이션은 단순한 장식에 그치지 않습니다.
애니메이션은 여러 방식으로 애플리케이션과 사용자 경험을 개선할 수 있습니다:

- 애니메이션이 없으면 웹 페이지의 전환이 갑작스럽고 부자연스럽게 느껴질 수 있습니다.
- 움직임은 사용자 경험을 크게 향상시킵니다.
  애니메이션을 통해 사용자는 자신의 행동에 애플리케이션이 어떻게 반응하는지 알아차릴 수 있습니다.
- 좋은 애니메이션은 작업 흐름 전체에서 사용자의 시선을 자연스럽게 유도할 수 있습니다.

Angular는 애플리케이션의 엘리먼트에 애니메이션을 적용하는 `animate.enter`와 `animate.leave`를 제공합니다.
두 기능은 적절한 시점에 진입 및 퇴장 CSS 클래스를 적용하거나, 서드 파티 라이브러리의 애니메이션을 적용하는 함수를 호출합니다.
`animate.enter`와 `animate.leave`는 디렉티브가 아닙니다.
Angular 컴파일러가 직접 지원하는 특별한 API이며, 엘리먼트에 직접 사용하거나 호스트 바인딩으로 사용할 수 있습니다.

## `animate.enter`

<!--
You can use `animate.enter` to animate elements as they _enter_ the DOM. You can define enter animations using CSS classes with either transitions or keyframe animations.

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

When the animation completes, Angular removes the class or classes that you specified in `animate.enter` from the DOM. Animation classes are only present while the animation is active.

NOTE: When using multiple keyframe animations or transition properties on an element, Angular removes all classes only _after_ the longest animation has completed.

You can use `animate.enter` with any other Angular features, such as control flow or dynamic expressions. `animate.enter` accepts both a single class string (with multiple classes separated by spaces), or an array of class strings.

A quick note about using CSS transitions: If you choose to use transitions instead of keyframe animations, the classes added to the element with `animate.enter` represent the state that the transition will animate _to_. Your base element CSS is what the element will look like when no animations run, which is likely similar to the end state of the CSS transition. So you would still need to pair it with `@starting-style` to have an appropriate _from_ state for your transition to work.

<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.enter`를 사용하면 엘리먼트가 DOM에 _진입_ 할 때 애니메이션을 적용할 수 있습니다.
전환이나 키프레임 애니메이션을 지정한 CSS 클래스로 진입 애니메이션을 정의할 수 있습니다.

애니메이션이 완료되면 Angular는 `animate.enter`에 지정한 클래스를 DOM에서 제거합니다.
애니메이션 클래스는 애니메이션이 실행되는 동안에만 존재합니다.

참고: 엘리먼트에 여러 키프레임 애니메이션이나 전환 프로퍼티를 사용하면 Angular는 가장 긴 애니메이션이 완료된 _뒤에_ 모든 클래스를 제거합니다.

`animate.enter`는 제어 흐름이나 동적 표현식 같은 다른 Angular 기능과 함께 사용할 수 있습니다.
`animate.enter`에는 클래스 문자열 하나를 전달하거나, 클래스 문자열의 배열을 전달할 수 있습니다.
문자열 하나에 여러 클래스를 지정할 때는 공백으로 구분합니다.

CSS 전환을 사용할 때는 한 가지 유의할 점이 있습니다.
키프레임 애니메이션 대신 전환을 사용하면 `animate.enter`로 추가한 클래스는 전환의 _도착_ 상태를 나타냅니다.
엘리먼트의 기본 CSS는 애니메이션이 실행되지 않을 때의 모습을 정의하며, 대개 CSS 전환의 최종 상태와 비슷합니다.
따라서 전환이 동작할 수 있도록 `@starting-style`을 함께 사용해서 적절한 _시작_ 상태를 지정해야 합니다.

## `animate.leave`

<!--
You can use `animate.leave` to animate elements as they _leave_ the DOM. You can define leave animations using CSS classes with either transforms or keyframe animations.

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

When the animation completes, Angular automatically removes the animated element from the DOM.

NOTE: When using multiple keyframe animations or transition properties on an element, Angular waits to remove the element only _after_ the longest of those animations has completed.

`animate.leave` can also be used with signals, and other bindings. You can use `animate.leave` with a single class or multiple classes. Either specify it as a simple string with spaces or a string array.

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

`animate.leave`를 사용하면 엘리먼트가 DOM에서 _퇴장_ 할 때 애니메이션을 적용할 수 있습니다.
변형이나 키프레임 애니메이션을 지정한 CSS 클래스로 퇴장 애니메이션을 정의할 수 있습니다.

애니메이션이 완료되면 Angular는 애니메이션이 적용된 엘리먼트를 DOM에서 자동으로 제거합니다.

참고: 엘리먼트에 여러 키프레임 애니메이션이나 전환 프로퍼티를 사용하면 Angular는 가장 긴 애니메이션이 완료된 _뒤에_ 엘리먼트를 제거합니다.

`animate.leave`는 시그널이나 다른 바인딩과 함께 사용할 수도 있습니다.
`animate.leave`에는 클래스 하나 또는 여러 개를 사용할 수 있으며, 공백으로 구분한 문자열이나 문자열 배열로 지정하면 됩니다.

### 엘리먼트 제거 순서

<!--
There is some nuance to how `animate.leave` animations are run and when an animation will occur. `animate.leave` works if it is placed on the element that is being removed, and if `animate.leave` is placed on an element that is a _descendant_ of the element being removed _within the same component template_, those child `animate.leave` animations will happen _before_ the parent node is removed from the DOM. This ensures that you can confidently animate away child elements without the parent node disappearing prematurely.

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.ts">
    <docs-code header="leave-parent.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.ts" />
    <docs-code header="leave-parent.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.html" />
    <docs-code header="leave-parent.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.css"/>
</docs-code-multifile>
-->

`animate.leave` 애니메이션의 실행 방식과 시점에는 알아둘 세부 사항이 있습니다.
제거되는 엘리먼트에 `animate.leave`가 지정되어 있으면 애니메이션이 실행됩니다.
_같은 컴포넌트 템플릿 안에서_ 제거되는 엘리먼트의 _하위_ 엘리먼트에 `animate.leave`가 지정되어 있으면, 자식 `animate.leave` 애니메이션은 부모 노드가 DOM에서 제거되기 _전에_ 실행됩니다.
따라서 부모 노드가 너무 일찍 사라지는 일을 걱정하지 않고 자식 엘리먼트의 퇴장 애니메이션을 적용할 수 있습니다.

중요: 자식 애니메이션은 같은 컴포넌트 템플릿 안의 엘리먼트에 대해서만 실행됩니다. 제거할 엘리먼트에 자식 컴포넌트가 있으면, 자식 컴포넌트 템플릿 안에 정의된 `animate.leave` 애니메이션은 부모가 제거되기 전에 실행되지 **않습니다**. 자식 컴포넌트를 제거할 때 애니메이션을 실행하려면 부모 템플릿에서 자식 컴포넌트의 호스트 엘리먼트에 `animate.leave`를 직접 적용하세요. 또는 코드로 자식 컴포넌트의 애니메이션을 실행하고, 애니메이션이 끝날 때까지 부모 제거를 지연할 수 있습니다.

## 이벤트 바인딩, 함수, 서드 파티 라이브러리

<!--
Both `animate.enter` and `animate.leave` support event binding syntax that allows for function calls. You can use this syntax to call a function in your component code or utilize third-party animation libraries, like [GSAP](https://gsap.com/), [anime.js](https://animejs.com/), or any other JavaScript animation library.

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

The `$event` object has the type `AnimationCallbackEvent`. It includes the element as the `target` and provides an `animationComplete()` function to notify the framework when the animation finishes.

IMPORTANT: You **must** call the `animationComplete()` function when using `animate.leave` for Angular to remove the element.

If you don't call `animationComplete()` when using `animate.leave`, Angular calls the function automatically after a four-second delay. You can configure the duration of the delay by providing the token `MAX_ANIMATION_TIMEOUT` in milliseconds.

```typescript
{ provide: MAX_ANIMATION_TIMEOUT, useValue: 6000 }
```
-->

`animate.enter`와 `animate.leave`는 모두 함수를 호출할 수 있는 이벤트 바인딩 문법을 지원합니다.
이 문법으로 컴포넌트 코드의 함수를 호출하거나, [GSAP](https://gsap.com/), [anime.js](https://animejs.com/) 또는 다른 JavaScript 애니메이션 라이브러리를 사용할 수 있습니다.

`$event` 객체의 타입은 `AnimationCallbackEvent`입니다.
이 객체는 엘리먼트를 `target`으로 포함하며, 애니메이션이 끝났음을 프레임워크에 알리는 `animationComplete()` 함수를 제공합니다.

중요: `animate.leave`를 사용할 때 Angular가 엘리먼트를 제거하도록 하려면 `animationComplete()` 함수를 **반드시** 호출해야 합니다.

`animate.leave`를 사용하면서 `animationComplete()`를 호출하지 않으면 Angular가 4초 뒤에 이 함수를 자동으로 호출합니다.
`MAX_ANIMATION_TIMEOUT` 토큰에 밀리초 단위의 값을 제공하면 지연 시간을 설정할 수 있습니다.

```typescript
{ provide: MAX_ANIMATION_TIMEOUT, useValue: 6000 }
```

## 기존 Angular 애니메이션과의 호환성

같은 컴포넌트 안에서 기존 애니메이션과 `animate.enter`, `animate.leave`를 함께 사용할 수 없습니다.
함께 사용하면 진입 클래스가 엘리먼트에 남아 있거나 퇴장 노드가 제거되지 않는 문제가 생깁니다.
그 외에는 같은 _애플리케이션_ 안에서 기존 애니메이션과 새로운 `animate.enter`, `animate.leave` 애니메이션을 함께 사용해도 됩니다.
다만 콘텐츠 프로젝션은 주의해야 합니다.
기존 애니메이션을 사용하는 컴포넌트의 콘텐츠를 `animate.enter`나 `animate.leave`를 사용하는 다른 컴포넌트에 투영하거나 그 반대로 투영하면, 같은 컴포넌트에서 함께 사용한 것과 같은 문제가 발생합니다.
이 방식은 지원하지 않습니다.

## 테스트하기

<!--
TestBed provides built-in support for enabling or disabling animations in your test environment. CSS animations require a browser to run, and many of the APIs are not available in a test environment. By default, TestBed disables animations for you in your test environments.

If you want to test that the animations are animating in a browser test, for example an end-to-end test, you can configure TestBed to enable animations by specifying `animationsEnabled: true` in your test configuration.

```typescript
TestBed.configureTestingModule({animationsEnabled: true});
```

This will configure animations in your test environment to behave normally.

NOTE: Some test environments do not emit animation events like `animationstart`, `animationend` and their transition event equivalents.
-->

TestBed는 테스트 환경에서 애니메이션을 활성화하거나 비활성화하는 기능을 기본으로 제공합니다.
CSS 애니메이션을 실행하려면 브라우저가 필요하며, 관련 API 중 상당수는 테스트 환경에서 사용할 수 없습니다.
TestBed는 기본적으로 테스트 환경의 애니메이션을 비활성화합니다.

엔드 투 엔드 테스트처럼 브라우저에서 실행하는 테스트에서 애니메이션 동작을 확인하려면, 테스트 설정에 `animationsEnabled: true`를 지정해서 TestBed의 애니메이션을 활성화할 수 있습니다.

```typescript
TestBed.configureTestingModule({animationsEnabled: true});
```

이렇게 설정하면 테스트 환경에서도 애니메이션이 정상적으로 동작합니다.

참고: 일부 테스트 환경은 `animationstart`, `animationend`와 같은 애니메이션 이벤트나 이에 대응하는 전환 이벤트를 발생시키지 않습니다.

## Angular 애니메이션 더 알아보기

다음 문서도 참고해 보세요:

# CSS로 애플리케이션에 애니메이션 적용하기

CSS는 애플리케이션 안에서 아름답고 매력적인 애니메이션을 만드는 데 사용할 수 있는 강력한 도구를 제공합니다.

## 네이티브 CSS로 애니메이션 작성하기

<!--
If you've never written any native CSS animations, there are a number of excellent guides to get you started. Here are a few of them:
[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)

and a couple of videos:
[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)

Check out some of these guides and tutorials, then come back to this guide.
-->

네이티브 CSS 애니메이션을 작성해 본 적이 없다면, 시작하는 데 도움이 되는 훌륭한 가이드가 많이 있습니다.
그중 몇 가지를 소개합니다:
[MDN CSS 애니메이션 가이드](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)
[W3Schools CSS3 애니메이션 가이드](https://www.w3schools.com/css/css3_animations.asp)
[CSS 애니메이션 전체 튜토리얼](https://www.lambdatest.com/blog/css-animations-tutorial/)
[초보자를 위한 CSS 애니메이션](https://thoughtbot.com/blog/css-animation-for-beginners)

다음 동영상도 참고할 수 있습니다:
[9분 만에 배우는 CSS 애니메이션](https://www.youtube.com/watch?v=z2LQYsZhsFw)
[Net Ninja CSS 애니메이션 튜토리얼 재생목록](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)

이 가이드와 튜토리얼 중 몇 가지를 살펴본 뒤 이 문서로 돌아오세요.

## 재사용 가능한 애니메이션 만들기

<!--
You can create reusable animations that can be shared across your application using `@keyframes`. Define keyframe animations in a shared CSS file, and you'll be able to re-use those keyframe animations wherever you want within your application.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>

Adding the class `animated-class` to an element would trigger the animation on that element.
-->

`@keyframes`를 사용하면 애플리케이션 전체에서 공유할 수 있는 재사용 가능한 애니메이션을 만들 수 있습니다.
공통 CSS 파일에 키프레임 애니메이션을 정의하면 애플리케이션의 원하는 곳 어디에서나 재사용할 수 있습니다.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>

엘리먼트에 `animated-class` 클래스를 추가하면 해당 엘리먼트에서 애니메이션이 실행됩니다.

## 전환에 애니메이션 적용하기

### 상태와 스타일에 애니메이션 적용하기

<!--
You may want to animate between two different states, for example when an element is opened or closed. You can accomplish this by using CSS classes, either with a keyframe animation or transition styling.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-states"/>

Triggering the `open` or `closed` state is done by toggling classes on the element in your component. You can find examples of how to do this in our [template guide](guide/templates/binding#css-class-and-style-property-bindings).

You can see similar examples in the template guide for [animating styles directly](guide/templates/binding#css-style-properties).
-->

엘리먼트가 열리거나 닫힐 때처럼 서로 다른 두 상태 사이에 애니메이션을 적용하고 싶을 수 있습니다.
CSS 클래스에 키프레임 애니메이션이나 전환 스타일을 지정하면 됩니다.

<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)에서도 비슷한 예제를 확인할 수 있습니다.

### 전환, 타이밍, 이징

<!--
Animating often requires adjusting timing, delays, and easing behaviors. This can be done using several css properties or shorthand properties.

Specify `animation-duration`, `animation-delay`, and `animation-timing-function` for a keyframe animation in CSS, or alternatively use the `animation` shorthand property.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>

Similarly, you can use `transition-duration`, `transition-delay`, and `transition-timing-function` and the `transition` shorthand for animations that are not using `@keyframes`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>
-->

애니메이션을 만들 때는 타이밍, 지연 시간, 이징 동작을 조절해야 하는 경우가 많습니다.
여러 CSS 프로퍼티나 단축 프로퍼티를 사용해서 설정할 수 있습니다.

CSS 키프레임 애니메이션에는 `animation-duration`, `animation-delay`, `animation-timing-function`을 지정하거나, 단축 프로퍼티인 `animation`을 사용하세요.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>

마찬가지로 `@keyframes`를 사용하지 않는 애니메이션에는 `transition-duration`, `transition-delay`, `transition-timing-function`과 단축 프로퍼티 `transition`을 사용할 수 있습니다.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>

### 애니메이션 실행하기

<!--
Animations can be triggered by toggling CSS styles or classes. Once a class is present on an element, the animation will occur. Removing the class will revert the element back to whatever CSS is defined for that element. Here's an example:

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

CSS 스타일이나 클래스를 전환해서 애니메이션을 실행할 수 있습니다.
엘리먼트에 클래스가 추가되면 애니메이션이 실행됩니다.
클래스를 제거하면 엘리먼트는 원래 정의된 CSS 스타일로 돌아갑니다.
다음 예제를 참고하세요:

## 전환과 트리거

### 자동 높이에 애니메이션 적용하기

<!--
You can use CSS Grid to animate to 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>

If you don't have to worry about supporting all browsers, you can also check out `calc-size()`, which is the true solution to animating auto height. See [MDN's docs](https://developer.mozilla.org/en-US/docs/Web/CSS/calc-size) and [this tutorial](https://frontendmasters.com/blog/one-of-the-boss-battles-of-css-is-almost-won-transitioning-to-auto/) for more information.
-->

CSS Grid를 사용하면 높이가 자동으로 결정되는 상태까지 애니메이션을 적용할 수 있습니다.

모든 브라우저를 지원할 필요가 없다면, 자동 높이 애니메이션을 직접 지원하는 `calc-size()`도 살펴보세요.
자세한 내용은 [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/)을 참고하세요.

### 뷰 진입과 퇴장에 애니메이션 적용하기

<!--
You can create animations for when an item enters a view or leaves a view. Let's start by looking at how to animate an element entering a view. We'll do this with `animate.enter`, which will apply animation classes when an element enters the 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>

Animating an element when it leaves the view is similar to animating when entering a view. Use `animate.leave` to specify which CSS classes to apply when the element leaves the 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>

NOTE: Child `animate.leave` animations fire only within the same component template. Nested component `animate.leave` animations will not fire when a parent element is removed.

For more information on `animate.enter` and `animate.leave`, see the [Enter and Leave animations guide](guide/animations).
-->

항목이 뷰에 진입하거나 뷰에서 퇴장할 때 실행되는 애니메이션을 만들 수 있습니다.
먼저 엘리먼트가 뷰에 진입할 때 애니메이션을 적용하는 방법을 살펴봅시다.
엘리먼트가 뷰에 진입할 때 애니메이션 클래스를 적용하는 `animate.enter`를 사용하겠습니다.

엘리먼트가 뷰에서 퇴장할 때 애니메이션을 적용하는 방법도 진입할 때와 비슷합니다.
`animate.leave`로 엘리먼트가 뷰에서 퇴장할 때 적용할 CSS 클래스를 지정하세요.

참고: 자식 `animate.leave` 애니메이션은 같은 컴포넌트 템플릿 안에서만 실행됩니다. 부모 엘리먼트를 제거할 때 중첩된 컴포넌트 안의 `animate.leave` 애니메이션은 실행되지 않습니다.

`animate.enter`와 `animate.leave`에 대한 자세한 내용은 [진입 및 퇴장 애니메이션 가이드](guide/animations)를 참고하세요.

### 값의 증가와 감소에 애니메이션 적용하기

<!--
Animating on increment and decrement is a common pattern in applications. Here's an example of how you can accomplish that behavior.

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

값이 증가하거나 감소할 때 애니메이션을 적용하는 것은 애플리케이션에서 흔히 사용하는 패턴입니다.
다음 예제에서 이 동작을 구현하는 방법을 확인할 수 있습니다.

### 개별 애니메이션 또는 모든 애니메이션 비활성화하기

<!--
If you'd like to disable the animations that you've specified, you have multiple options.

1. Create a custom class that forces animation and transition to `none`.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

Applying this class to an element prevents any animation from firing on that element. You could alternatively scope this to your entire DOM or section of your DOM to enforce this behavior. However, this prevents animation events from firing. If you are awaiting animation events for element removal, this solution won't work. A workaround is to set durations to 1 millisecond instead.

2. Use the [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) media query to ensure no animations play for users that prefer less animation.

3. Prevent adding animation classes programmatically
-->

지정한 애니메이션을 비활성화하려면 몇 가지 방법을 사용할 수 있습니다.

1. 애니메이션과 전환을 `none`으로 강제 설정하는 커스텀 클래스를 만듭니다.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

이 클래스를 엘리먼트에 적용하면 해당 엘리먼트에서 애니메이션이 실행되지 않습니다.
DOM 전체나 특정 영역에 적용해서 같은 동작을 강제할 수도 있습니다.
하지만 이 방법은 애니메이션 이벤트도 발생하지 않게 합니다.
엘리먼트를 제거하기 위해 애니메이션 이벤트를 기다리고 있다면 이 방법은 사용할 수 없습니다.
대신 지속 시간을 1밀리초로 설정하는 방법이 있습니다.

2. [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) 미디어 쿼리를 사용해서 움직임을 줄이도록 설정한 사용자에게는 애니메이션을 실행하지 않습니다.

3. 코드에서 애니메이션 클래스가 추가되지 않도록 처리합니다.

### 애니메이션 콜백

<!--
If you have actions you would like to execute at certain points during animations, there are a number of available events you can listen to. Here's a few of them.

[`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/animationiteration_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)

The Web Animations API has a lot of additional functionality. [Take a look at the documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) to see all the available animation APIs.

NOTE: Be aware of bubbling issues with these callbacks. If you are animating children and parents, the events bubble up from children to parents. Consider stopping propagation or looking at more details within the event to determine if you're responding to the desired event target rather than an event bubbling up from a child node. You can examine the `animationname` property or the properties being transitioned to verify you have the right nodes.
-->

애니메이션의 특정 시점에 어떤 동작을 실행하려면 여러 이벤트를 감지할 수 있습니다.
다음은 그중 일부입니다.

[`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/animationiteration_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는 이 밖에도 많은 기능을 제공합니다.
사용할 수 있는 애니메이션 API 전체는 [문서](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API)를 참고하세요.

참고: 이런 콜백에서는 버블링에 주의하세요.
자식과 부모에 애니메이션을 적용하면 이벤트가 자식에서 부모로 버블링됩니다.
이벤트 전파를 중단하거나 이벤트의 상세 정보를 확인해서, 자식 노드에서 버블링된 이벤트가 아니라 의도한 대상의 이벤트에 반응하는지 판단하세요.
`animationname` 프로퍼티나 전환 중인 프로퍼티를 조사하면 올바른 노드인지 확인할 수 있습니다.

## 복잡한 시퀀스

애니메이션은 단순히 서서히 나타나거나 사라지는 것보다 복잡한 경우가 많습니다.
여러 복잡한 애니메이션 시퀀스를 실행하고 싶을 수도 있습니다.
가능한 시나리오 몇 가지를 살펴봅시다.

### 목록 애니메이션을 시간차로 실행하기

<!--
One common effect is to stagger the animations of each item in a list to create a cascade effect. This can be accomplished by utilizing `animation-delay` or `transition-delay`. Here is an example of what that CSS might look like.

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

목록의 각 항목에 애니메이션을 시간차로 적용해서 연속적으로 퍼지는 효과를 만드는 것은 흔히 사용하는 방식입니다.
`animation-delay`나 `transition-delay`를 사용하면 됩니다.
다음 예제에서 CSS를 어떻게 작성하는지 확인할 수 있습니다.

### 병렬 애니메이션

<!--
You can apply multiple animations to an element at once using the `animation` shorthand property. Each can have their own durations and delays. This allows you to compose animations together and create complicated effects.

```css
.target-element {
  animation:
    rotate 3s,
    fade-in 2s;
}
```

In this example, the `rotate` and `fade-in` animations fire at the same time, but have different durations.
-->

단축 프로퍼티 `animation`을 사용하면 엘리먼트 하나에 여러 애니메이션을 동시에 적용할 수 있습니다.
각 애니메이션에 서로 다른 지속 시간과 지연 시간을 지정할 수 있습니다.
이렇게 애니메이션을 조합해서 복잡한 효과를 만들 수 있습니다.

```css
.target-element {
  animation:
    rotate 3s,
    fade-in 2s;
}
```

이 예제에서는 `rotate`와 `fade-in` 애니메이션이 동시에 시작하지만, 지속 시간은 서로 다릅니다.

### 순서가 바뀌는 목록 항목에 애니메이션 적용하기

<!--
Items in a `@for` loop will be removed and re-added, which will fire off animations using `@starting-styles` for entry animations. Alternatively, you can use `animate.enter` for this same behavior. Use `animate.leave` to animate elements as they are removed, as seen in the example below.

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

`@for` 반복문의 항목은 제거된 뒤 다시 추가되며, 이때 `@starting-styles`를 사용하는 진입 애니메이션이 실행됩니다.
같은 동작을 구현하기 위해 `animate.enter`를 사용할 수도 있습니다.
아래 예제처럼 엘리먼트가 제거될 때 애니메이션을 적용하려면 `animate.leave`를 사용하세요.

## 코드에서 애니메이션 제어하기

[`Element.getAnimations()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations)로 엘리먼트의 애니메이션을 직접 가져올 수 있습니다.
이 메서드는 해당 엘리먼트의 모든 [`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation)을 배열로 반환합니다.
`Animation` API를 사용하면 애니메이션 패키지의 `AnimationPlayer`가 제공했던 것보다 훨씬 많은 작업을 할 수 있습니다.
`cancel()`, `play()`, `pause()`, `reverse()` 등 다양한 메서드를 사용할 수 있습니다.
이 네이티브 API는 애니메이션을 제어하는 데 필요한 모든 기능을 제공합니다.

## Angular 애니메이션 더 알아보기

다음 문서도 참고해 보세요:

# 라우팅 규칙 전환 애니메이션

<!--
Route transition animations enhance user experience by providing smooth visual transitions when navigating between different views in your Angular application. [Angular Router](/guide/routing) includes built-in support for the browser's View Transitions API, enabling seamless animations between route changes in supported browsers.

HELPFUL: The Router's native View Transitions integration is currently in [developer preview](/reference/releases#developer-preview). Native View Transitions are a relatively new browser feature with limited support across all browsers.
-->

라우팅 규칙 전환 애니메이션은 Angular 애플리케이션의 여러 뷰 사이를 이동할 때 화면을 부드럽게 전환해서 사용자 경험을 개선합니다.
[Angular 라우터](/guide/routing)는 브라우저의 View Transitions API를 기본으로 지원하므로, 지원되는 브라우저에서 라우팅 규칙이 바뀔 때 매끄러운 애니메이션을 적용할 수 있습니다.

참고: 라우터의 네이티브 View Transitions 통합 기능은 현재 [개발자 프리뷰](/reference/releases#developer-preview)입니다.
네이티브 View Transitions는 비교적 새로운 브라우저 기능이므로 모든 브라우저에서 지원되지는 않습니다.

## View Transitions의 동작 방식

<!--
View transitions use the browser's native [`document.startViewTransition` API](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) to create smooth animations between different states of your application. The API works by:

1. **Capturing the current state** - The browser takes a screenshot of the current page
2. **Executing the DOM update** - Your callback function runs to update the DOM
3. **Capturing the new state** - The browser captures the updated page state
4. **Playing the transition** - The browser animates between the old and new states

Here's the basic structure of the `startViewTransition` API:

```ts
document.startViewTransition(async () => {
  await updateTheDOMSomehow();
});
```

For more details about the browser API, see the [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions).
-->

뷰 전환은 브라우저의 기본 [`document.startViewTransition` API](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition)를 사용해서 애플리케이션의 여러 상태 사이를 부드럽게 전환합니다.
이 API는 다음과 같이 동작합니다.

1. **현재 상태 캡처** — 브라우저가 현재 페이지의 스크린샷을 찍습니다.
2. **DOM 갱신 실행** — 콜백 함수가 실행되어 DOM을 갱신합니다.
3. **새 상태 캡처** — 브라우저가 갱신된 페이지 상태를 캡처합니다.
4. **전환 재생** — 브라우저가 이전 상태와 새 상태 사이의 애니메이션을 재생합니다.

`startViewTransition` API의 기본 구조는 다음과 같습니다.

```ts
document.startViewTransition(async () => {
  await updateTheDOMSomehow();
});
```

브라우저 API의 자세한 내용은 [Chrome 설명 문서](https://developer.chrome.com/docs/web-platform/view-transitions)를 참고하세요.

## 라우터의 뷰 전환 사용 방식

<!--
Angular Router integrates view transitions into the navigation lifecycle to create seamless route changes. During navigation, the Router:

1. **Completes navigation preparation** - Route matching, [lazy loading](guide/routing/loading-strategies#lazily-loaded-components-and-routes), [guards](/guide/routing/route-guards), [resources](/guide/routing/data-fetching-with-resources), and [resolvers](/guide/routing/data-resolvers) execute
2. **Initiates the view transition** - Router calls `startViewTransition` when routes are ready for activation
3. **Updates the DOM** - Router activates new routes and deactivates old ones within the transition callback
4. **Finalizes the transition** - The transition Promise resolves when Angular completes rendering

The Router's view transition integration acts as a [progressive enhancement](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement). When browsers don't support the View Transitions API, the Router performs normal DOM updates without animation, ensuring your application works across all browsers.
-->

Angular 라우터는 내비게이션 라이프사이클에 뷰 전환을 통합해서 라우팅 규칙을 매끄럽게 전환합니다.
내비게이션 중 라우터는 다음과 같이 동작합니다.

1. **내비게이션 준비 완료** — 라우팅 규칙 매칭, [지연 로딩](guide/routing/loading-strategies#lazily-loaded-components-and-routes), [가드](/guide/routing/route-guards), [리소스](/guide/routing/data-fetching-with-resources), [리졸버](/guide/routing/data-resolvers)를 실행합니다.
2. **뷰 전환 시작** — 라우팅 규칙 활성화 준비가 끝나면 라우터가 `startViewTransition`을 호출합니다.
3. **DOM 갱신** — 전환 콜백 안에서 새 라우팅 규칙을 활성화하고 이전 라우팅 규칙을 비활성화합니다.
4. **전환 마무리** — Angular가 렌더링을 완료하면 전환 Promise가 이행됩니다.

라우터의 뷰 전환 통합은 [점진적 향상](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement) 방식으로 동작합니다.
브라우저가 View Transitions API를 지원하지 않으면 라우터는 애니메이션 없이 일반적인 DOM 갱신을 수행하므로, 애플리케이션이 모든 브라우저에서 동작할 수 있습니다.

## 라우터에서 View Transitions 활성화하기

[라우터 설정](/guide/routing/define-routes#adding-the-router-to-your-application)에 `withViewTransitions` 기능을 추가하면 뷰 전환을 활성화할 수 있습니다.
Angular는 독립형 방식과 NgModule 방식의 부트스트랩을 모두 지원합니다.

### 독립형 부트스트랩

<!--
```ts
import {bootstrapApplication} from '@angular/platform-browser';
import {provideRouter, withViewTransitions} from '@angular/router';
import {routes} from './app.routes';

bootstrapApplication(MyApp, {
  providers: [provideRouter(routes, withViewTransitions())],
});
```
-->

```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 부트스트랩

<!--
```ts
import {NgModule} from '@angular/core';
import {RouterModule} from '@angular/router';

@NgModule({
  imports: [RouterModule.forRoot(routes, {enableViewTransitions: true})],
})
export class AppRouting {}
```

[Try the "count" example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-2dnvtm?file=src%2Fmain.ts)

This example demonstrates how router navigation can replace direct `startViewTransition` calls for counter updates.
-->

```ts
import {NgModule} from '@angular/core';
import {RouterModule} from '@angular/router';

@NgModule({
  imports: [RouterModule.forRoot(routes, {enableViewTransitions: true})],
})
export class AppRouting {}
```

[StackBlitz에서 "count" 예제 실행하기](https://stackblitz.com/edit/stackblitz-starters-2dnvtm?file=src%2Fmain.ts)

이 예제는 카운터를 갱신할 때 `startViewTransition`을 직접 호출하는 대신 라우터 내비게이션을 사용하는 방법을 보여줍니다.

## CSS로 전환 효과 조정하기

<!--
You can customize view transitions using CSS to create unique animation effects. The browser creates separate transition elements that you can target with CSS selectors.

To create custom transitions:

1. **Add view-transition-name** - Assign unique names to elements you want to animate
2. **Define global animations** - Create CSS animations in your global styles
3. **Target transition pseudo-elements** - Use `::view-transition-old()` and `::view-transition-new()` selectors

Here's an example that adds a rotation effect to a counter element:

```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: Define view transition animations in your global styles file, not in component styles. Angular's [view encapsulation](/guide/components/styling#style-scoping) scopes component styles, which prevents them from targeting the transition pseudo-elements correctly.

[Try the updated “count” example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-fwn4i7?file=src%2Fmain.ts)
-->

CSS로 뷰 전환을 조정해서 원하는 애니메이션 효과를 만들 수 있습니다.
브라우저는 CSS 셀렉터로 지정할 수 있는 별도의 전환 엘리먼트를 생성합니다.

커스텀 전환을 만들려면 다음 단계를 진행하세요.

1. **view-transition-name 추가** — 애니메이션을 적용할 엘리먼트에 고유한 이름을 지정합니다.
2. **전역 애니메이션 정의** — 전역 스타일에 CSS 애니메이션을 작성합니다.
3. **전환 가상 엘리먼트 지정** — `::view-transition-old()`, `::view-transition-new()` 셀렉터를 사용합니다.

다음 예제는 카운터 엘리먼트에 회전 효과를 추가합니다.

```css
/* 키프레임 애니메이션을 정의합니다. */
@keyframes rotate-out {
  to {
    transform: rotate(90deg);
  }
}

@keyframes rotate-in {
  from {
    transform: rotate(-90deg);
  }
}

/* 뷰 전환 가상 엘리먼트를 지정합니다. */
::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;
}
```

중요: 뷰 전환 애니메이션은 컴포넌트 스타일이 아닌 전역 스타일 파일에 정의하세요.
Angular의 [뷰 캡슐화](/guide/components/styling#style-scoping)는 컴포넌트 스타일의 범위를 제한하기 때문에 전환 가상 엘리먼트를 올바르게 지정할 수 없습니다.

[StackBlitz에서 수정된 "count" 예제 실행하기](https://stackblitz.com/edit/stackblitz-starters-fwn4i7?file=src%2Fmain.ts)

## onViewTransitionCreated로 전환 동작 세밀하게 제어하기

<!--
The `withViewTransitions` feature accepts an options object with an `onViewTransitionCreated` callback for advanced control over view transitions. This callback:

- Runs in an [injection context](/guide/di/dependency-injection-context#run-within-an-injection-context)
- Receives a [`ViewTransitionInfo`](/api/router/ViewTransitionInfo) object containing:
  - The `ViewTransition` instance from `startViewTransition`
  - The [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) for the route being navigated from
  - The [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot) for the route being navigated to

Use this callback to customize transition behavior based on navigation context. For example, you can skip transitions for specific navigation types:

```ts
import {inject} from '@angular/core';
import {Router, withViewTransitions, isActive, IsActiveMatchOptions} from '@angular/router';

withViewTransitions({
  onViewTransitionCreated: ({transition}) => {
    const router = inject(Router);
    const targetUrl = router.currentNavigation()!.finalUrl!;

// Skip transition if only fragment or query params change
    const config: Partial<IsActiveMatchOptions> = {
      paths: 'exact',
      matrixParams: 'exact',
      fragment: 'ignored',
      queryParams: 'ignored',
    };

const isTargetRouteCurrent = isActive(targetUrl, router, config);

if (isTargetRouteCurrent()) {
      transition.skipTransition();
    }
  },
});
```

This example skips the view transition when navigation only changes the [URL fragment or query parameters](/guide/routing/read-route-state#query-parameters) (such as anchor links within the same page). The `skipTransition()` method prevents the animation while still allowing the navigation to complete.
-->

`withViewTransitions` 기능은 뷰 전환을 세밀하게 제어할 수 있도록 `onViewTransitionCreated` 콜백이 있는 옵션 객체를 받습니다.
이 콜백은 다음과 같이 동작합니다.

- [의존성 주입 컨텍스트](/guide/di/dependency-injection-context#run-within-an-injection-context)에서 실행됩니다.
- 다음 정보가 있는 [`ViewTransitionInfo`](/api/router/ViewTransitionInfo) 객체를 받습니다.
  - `startViewTransition`의 `ViewTransition` 인스턴스
  - 떠나는 라우팅 규칙의 [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot)
  - 이동할 라우팅 규칙의 [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot)

이 콜백으로 내비게이션 컨텍스트에 맞게 전환 동작을 조정할 수 있습니다.
예를 들어 특정 종류의 내비게이션에서는 전환을 건너뛸 수 있습니다.

```ts
import {inject} from '@angular/core';
import {Router, withViewTransitions, isActive, IsActiveMatchOptions} from '@angular/router';

withViewTransitions({
  onViewTransitionCreated: ({transition}) => {
    const router = inject(Router);
    const targetUrl = router.currentNavigation()!.finalUrl!;

// 프래그먼트나 쿼리 파라미터만 바뀌면 전환을 건너뜁니다.
    const config: Partial<IsActiveMatchOptions> = {
      paths: 'exact',
      matrixParams: 'exact',
      fragment: 'ignored',
      queryParams: 'ignored',
    };

const isTargetRouteCurrent = isActive(targetUrl, router, config);

if (isTargetRouteCurrent()) {
      transition.skipTransition();
    }
  },
});
```

이 예제에서는 같은 페이지 안의 앵커 링크처럼 [URL 프래그먼트나 쿼리 파라미터](/guide/routing/read-route-state#query-parameters)만 바뀌면 뷰 전환을 건너뜁니다.
`skipTransition()` 메서드는 애니메이션을 생략하면서 내비게이션은 완료할 수 있도록 합니다.

## 사용자의 모션 환경설정 존중하기

라우터는 사용자의 [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) 설정과 관계없이 뷰 전환을 실행합니다.
모션을 줄이는 설정이 모든 움직임을 없애려는 뜻은 아니므로, 프레임워크는 이 선택을 애플리케이션에 맡깁니다.
이런 사용자를 위해 [움직임이 더 적은 애니메이션을 제공](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#react_to_the_reduced_motion_preference)하거나, `onViewTransitionCreated` 콜백으로 전환을 완전히 건너뛸 수 있습니다:

```ts
withViewTransitions({
  onViewTransitionCreated: ({transition}) => {
    if (matchMedia('(prefers-reduced-motion: reduce)').matches) {
      transition.skipTransition();
    }
  },
});
```

## Chrome 설명 문서의 예제를 Angular에 적용하기

다음 예제는 Chrome 팀 문서의 여러 뷰 전환 기법을 Angular 라우터에서 사용하도록 바꾼 것입니다.

### 전환 대상이 같은 DOM 엘리먼트일 필요는 없습니다

<!--
Elements can transition smoothly between different DOM elements as long as they share the same `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 Example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-dh8npr?file=src%2Fmain.ts)
-->

서로 다른 DOM 엘리먼트도 `view-transition-name`이 같으면 부드럽게 전환할 수 있습니다.

- [Chrome 설명 문서](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning_elements_dont_need_to_be_the_same_dom_element)
- [StackBlitz의 Angular 예제](https://stackblitz.com/edit/stackblitz-starters-dh8npr?file=src%2Fmain.ts)

### 커스텀 진입 및 퇴장 애니메이션

<!--
Create unique animations for elements entering and leaving the viewport during route transitions.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#custom_entry_and_exit_transitions)
- [Angular Example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-8kly3o)
-->

라우팅 규칙 전환 중 뷰포트에 들어오고 나가는 엘리먼트에 원하는 애니메이션을 만들 수 있습니다.

- [Chrome 설명 문서](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#custom_entry_and_exit_transitions)
- [StackBlitz의 Angular 예제](https://stackblitz.com/edit/stackblitz-starters-8kly3o)

### 비동기 DOM 갱신과 콘텐츠 대기

<!--
Angular Router prioritizes immediate transitions over waiting for additional content to load.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#async_dom_updates_and_waiting_for_content)

NOTE: Angular Router does not provide a way to delay view transitions. This design choice prevents pages from becoming non-interactive while waiting for additional content. As the Chrome documentation notes: "During this time, the page is frozen, so delays here should be kept to a minimum…in some cases it's better to avoid the delay altogether, and use the content you already have."
-->

Angular 라우터는 추가 콘텐츠가 로드되기를 기다리는 것보다 즉시 전환하는 것을 우선합니다.

- [Chrome 설명 문서](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#async_dom_updates_and_waiting_for_content)

참고: Angular 라우터는 뷰 전환을 지연하는 방법을 제공하지 않습니다.
추가 콘텐츠를 기다리는 동안 페이지와 상호작용할 수 없게 되는 상황을 방지하기 위한 설계입니다.
Chrome 문서에서도 "이 시간에는 페이지가 멈추므로 지연을 최소화해야 합니다.
… 경우에 따라서는 기다리지 않고 이미 확보한 콘텐츠를 사용하는 편이 낫습니다."라고 설명합니다.

### 뷰 전환 타입으로 여러 전환 스타일 처리하기

<!--
Use view transition types to apply different animation styles based on navigation context.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#view-transition-types)
- [Angular Example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-vxzcam)
-->

뷰 전환 타입을 사용하면 내비게이션 컨텍스트에 따라 다른 애니메이션 스타일을 적용할 수 있습니다.

- [Chrome 설명 문서](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#view-transition-types)
- [StackBlitz의 Angular 예제](https://stackblitz.com/edit/stackblitz-starters-vxzcam)

### 뷰 전환 루트의 클래스 이름으로 여러 전환 스타일 처리하기(사용 중단 권고)

<!--
This approach uses CSS classes on the transition root element to control animation styles.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#changing-on-navigation-type)
- [Angular Example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-nmnzzg?file=src%2Fmain.ts)
-->

이 방식은 전환 루트 엘리먼트의 CSS 클래스로 애니메이션 스타일을 제어합니다.

- [Chrome 설명 문서](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#changing-on-navigation-type)
- [StackBlitz의 Angular 예제](https://stackblitz.com/edit/stackblitz-starters-nmnzzg?file=src%2Fmain.ts)

### 다른 애니메이션을 멈추지 않고 전환하기

<!--
Maintain other page animations during view transitions to create more dynamic user experiences.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning-without-freezing)
- [Angular Example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-76kgww)
-->

뷰 전환 중에도 다른 페이지 애니메이션을 유지하면 더 역동적인 사용자 경험을 만들 수 있습니다.

- [Chrome 설명 문서](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning-without-freezing)
- [StackBlitz의 Angular 예제](https://stackblitz.com/edit/stackblitz-starters-76kgww)

### JavaScript로 애니메이션 처리하기

<!--
Control view transitions programmatically using JavaScript APIs for complex animation scenarios.

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#animating-with-javascript)
- [Angular Example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-cklnkm)
-->

복잡한 애니메이션이 필요하면 JavaScript API를 사용해서 뷰 전환을 코드로 제어할 수 있습니다.

- [Chrome 설명 문서](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#animating-with-javascript)
- [StackBlitz의 Angular 예제](https://stackblitz.com/edit/stackblitz-starters-cklnkm)

# Angular 애니메이션 패키지에서 마이그레이션하기

`@angular/animations` 패키지는 v20.2부터 사용 중단 권고(deprecated) 상태이며, 같은 버전에 애플리케이션에 애니메이션을 추가하는 새로운 기능인 `animate.enter`와 `animate.leave`가 도입되었습니다.
이 기능을 사용하면 `@angular/animations` 기반 애니메이션을 모두 일반 CSS나 JavaScript 애니메이션 라이브러리로 대체할 수 있습니다.
애플리케이션에서 `@angular/animations`를 제거하면 JavaScript 번들 크기를 크게 줄일 수 있습니다.
네이티브 CSS 애니메이션은 하드웨어 가속을 활용할 수 있어 일반적으로 더 뛰어난 성능을 제공합니다.
이 가이드에서는 `@angular/animations`를 사용하는 코드를 네이티브 CSS 애니메이션으로 리팩토링하는 과정을 살펴봅니다.

## 네이티브 CSS로 애니메이션 작성하기

Check out some of these guides and tutorials, then come back to this guide.
-->

네이티브 CSS 애니메이션을 작성해 본 적이 없다면, 시작하는 데 도움이 되는 훌륭한 가이드가 많이 있습니다.
그중 몇 가지를 소개합니다:  
[MDN CSS 애니메이션 가이드](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)  
[W3Schools CSS3 애니메이션 가이드](https://www.w3schools.com/css/css3_animations.asp)  
[CSS 애니메이션 전체 튜토리얼](https://www.lambdatest.com/blog/css-animations-tutorial/)  
[초보자를 위한 CSS 애니메이션](https://thoughtbot.com/blog/css-animation-for-beginners)

다음 동영상도 참고할 수 있습니다:  
[9분 만에 배우는 CSS 애니메이션](https://www.youtube.com/watch?v=z2LQYsZhsFw)  
[Net Ninja CSS 애니메이션 튜토리얼 재생목록](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)

이 가이드와 튜토리얼 중 몇 가지를 살펴본 뒤 이 문서로 돌아오세요.

## 재사용 가능한 애니메이션 만들기

애니메이션 패키지를 사용할 때처럼 애플리케이션 전체에서 공유할 수 있는 재사용 가능한 애니메이션을 만들 수 있습니다.
애니메이션 패키지에서는 공통 TypeScript 파일에서 `animation()` 함수를 사용했습니다.
네이티브 CSS 방식도 비슷하지만, 공통 CSS 파일에 정의합니다.

#### 애니메이션 패키지 사용

<docs-code header="animations.ts" path="adev/src/content/examples/animations/src/app/animations.1.ts" region="animation-example"/>

#### 네이티브 CSS 사용

<!--
<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>

Adding the class `animated-class` to an element would trigger the animation on that element.
-->

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>

엘리먼트에 `animated-class` 클래스를 추가하면 해당 엘리먼트에서 애니메이션이 실행됩니다.

## 전환에 애니메이션 적용하기

### 상태와 스타일에 애니메이션 적용하기

애니메이션 패키지에서는 컴포넌트 안에서 [`state()`](api/animations/state) 함수로 여러 상태를 정의할 수 있었습니다.
예를 들어 `open`이나 `closed` 상태를 정의하면서 각 상태에 해당하는 스타일을 포함할 수 있습니다.
다음 예제를 참고하세요:

#### 애니메이션 패키지 사용 {#ko-animating-state-and-styles-with-animations-package}

<!--
<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="state1"/>

This same behavior can be accomplished natively by using CSS classes, either with a keyframe animation or transition styling.
-->

<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="state1"/>

CSS 클래스에 키프레임 애니메이션이나 전환 스타일을 지정하면 네이티브 CSS로도 같은 동작을 구현할 수 있습니다.

#### 네이티브 CSS 사용 {#ko-animating-state-and-styles-with-native-css}

<!--
<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-states"/>

You can see similar examples in the template guide for [animating styles directly](guide/templates/binding#css-style-properties).
-->

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-states"/>

템플릿 가이드의 [스타일에 직접 애니메이션 적용하기](guide/templates/binding#css-style-properties)에서도 비슷한 예제를 확인할 수 있습니다.

### 전환, 타이밍, 이징

<!--
The animations package `animate()` function allows for providing timing, like duration, delays and easing. This can be done natively with CSS using several css properties or shorthand properties.

Specify `animation-duration`, `animation-delay`, and `animation-timing-function` for a keyframe animation in CSS, or alternatively use the `animation` shorthand property.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>

Similarly, you can use `transition-duration`, `transition-delay`, and `transition-timing-function` and the `transition` shorthand for animations that are not using `@keyframes`.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>
-->

애니메이션 패키지의 `animate()` 함수에서는 지속 시간, 지연 시간, 이징 같은 타이밍을 지정할 수 있습니다.
CSS의 여러 프로퍼티나 단축 프로퍼티를 사용하면 네이티브 CSS로도 설정할 수 있습니다.

CSS 키프레임 애니메이션에는 `animation-duration`, `animation-delay`, `animation-timing-function`을 지정하거나, 단축 프로퍼티인 `animation`을 사용하세요.

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>

### 애니메이션 실행하기

애니메이션 패키지에서는 `trigger()` 함수로 트리거를 지정하고, 그 안에 모든 상태를 중첩해서 정의해야 했습니다.
네이티브 CSS에서는 그럴 필요가 없습니다.
CSS 스타일이나 클래스를 전환해서 애니메이션을 실행할 수 있습니다.
엘리먼트에 클래스가 추가되면 애니메이션이 실행됩니다.
클래스를 제거하면 엘리먼트는 원래 정의된 CSS 스타일로 돌아갑니다.
따라서 훨씬 적은 코드로 같은 애니메이션을 구현할 수 있습니다.
다음 예제를 참고하세요:

#### 애니메이션 패키지 사용 {#ko-triggering-an-animation-with-animations-package}

<!--

-->

#### 네이티브 CSS 사용 {#ko-triggering-an-animation-with-native-css}

## 전환과 트리거

### 사전 정의된 상태와 와일드카드 매칭

<!--
The animations package offers the ability to match your defined states to a transition via strings. For example, animating from open to closed would be `open => closed`. You can use wildcards to match any state to a target state, like `* => closed` and the `void` keyword can be used for entering and exiting states. For example: `* => void` for when an element leaves a view or `void => *` for when the element enters a view.

These state matching patterns are not needed at all when animating with CSS directly. You can manage what transitions and `@keyframes` animations apply based on whatever classes you set and / or styles you set on the elements. You can also add `@starting-style` to control how the element looks upon immediately entering the DOM.
-->

애니메이션 패키지에서는 문자열을 사용해서 정의한 상태를 전환과 매칭할 수 있습니다.
예를 들어 열린 상태에서 닫힌 상태로 전환하는 애니메이션은 `open => closed`로 표현합니다.
`* => closed`처럼 와일드카드를 사용하면 모든 상태를 목표 상태와 매칭할 수 있고, `void` 키워드로 진입과 퇴장 상태를 표현할 수도 있습니다.
예를 들어 엘리먼트가 뷰에서 퇴장할 때는 `* => void`, 뷰에 진입할 때는 `void => *`를 사용합니다.

CSS로 직접 애니메이션을 적용할 때는 이런 상태 매칭 패턴이 전혀 필요하지 않습니다.
엘리먼트에 지정한 클래스나 스타일을 기준으로 어떤 전환과 `@keyframes` 애니메이션을 적용할지 관리하면 됩니다.
`@starting-style`을 추가해서 엘리먼트가 DOM에 진입하는 순간의 모습을 제어할 수도 있습니다.

### 와일드카드로 프로퍼티 자동 계산하기

애니메이션 패키지는 고정된 높이에서 `height: auto`로 바꾸는 것처럼, 기존에는 구현하기 어려웠던 애니메이션을 지원합니다.
이제 순수 CSS로도 구현할 수 있습니다.

#### 애니메이션 패키지 사용 {#ko-automatic-property-calculation-with-animations-package}

CSS Grid를 사용하면 높이가 자동으로 결정되는 상태까지 애니메이션을 적용할 수 있습니다.

#### 네이티브 CSS 사용 {#ko-automatic-property-calculation-with-native-css}

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

If you don't have to worry about supporting all browsers, you can also check out `calc-size()`, which is the true solution to animating auto height. See [MDN's docs](https://developer.mozilla.org/en-US/docs/Web/CSS/calc-size) and (this tutorial)[https://frontendmasters.com/blog/one-of-the-boss-battles-of-css-is-almost-won-transitioning-to-auto/] for more information.
-->

모든 브라우저를 지원할 필요가 없다면, 자동 높이 애니메이션을 직접 지원하는 `calc-size()`도 살펴보세요.
자세한 내용은 [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/]을 참고하세요.

### 뷰 진입과 퇴장에 애니메이션 적용하기

애니메이션 패키지는 앞서 설명한 진입 및 퇴장 패턴 매칭뿐 아니라 `:enter`, `:leave`라는 축약 별칭도 제공했습니다.

#### 애니메이션 패키지 사용 {#ko-enter-and-leave-with-animations-package}

<!--

-->

#### 네이티브 CSS 사용 {#ko-enter-with-native-css}

#### 네이티브 CSS 사용 {#ko-leave-with-native-css}

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

For more information on `animate.enter` and `animate.leave`, see the [Enter and Leave animations guide](guide/animations).
-->

`animate.enter`와 `animate.leave`에 대한 자세한 내용은 [진입 및 퇴장 애니메이션 가이드](guide/animations)를 참고하세요.

### 값의 증가와 감소에 애니메이션 적용하기

앞서 설명한 `:enter`, `:leave` 외에도 `:increment`와 `:decrement`가 있습니다.
클래스를 추가하고 제거하는 방식으로 이 애니메이션도 구현할 수 있습니다.
애니메이션 패키지의 내장 별칭과는 달리, 값이 증가하거나 감소할 때 클래스가 자동으로 적용되지는 않습니다.
코드에서 적절한 클래스를 적용하면 됩니다.
다음 예제를 참고하세요:

#### 애니메이션 패키지 사용 {#ko-increment-and-decrement-with-animations-package}

<!--

-->

#### 네이티브 CSS 사용 {#ko-increment-and-decrement-with-native-css}

### 부모와 자식 애니메이션

애니메이션 패키지와 달리, 한 컴포넌트 안에 여러 애니메이션을 지정해도 어느 애니메이션이 다른 애니메이션보다 우선하지 않으며 애니메이션 실행을 차단하지도 않습니다.
애니메이션을 순서대로 실행하려면 CSS 애니메이션 정의에서 애니메이션이나 전환의 지연 시간을 지정하거나, `animationend` 또는 `transitionend` 이벤트에서 다음 애니메이션을 위한 CSS를 추가하도록 처리해야 합니다.

자식 애니메이션은 같은 컴포넌트 템플릿 안에서만 실행됩니다. `@angular/animations` 패키지에서는 부모 애니메이션이 `query()`와 `animateChild()`로 중첩된 자식 컴포넌트의 애니메이션을 찾아 실행할 수 있었습니다. `animate.leave`와 네이티브 CSS 애니메이션에서는 부모 컴포넌트가 엘리먼트나 뷰를 제거해도 중첩된 자식 컴포넌트 템플릿 안의 애니메이션은 실행되지 않습니다. 같은 Angular 컴포넌트 템플릿 안에 중첩된 애니메이션만 실행됩니다. 자세한 내용은 [진입/퇴장 애니메이션 가이드](guide/animations#element-removal-order)를 참고하세요.

### 개별 애니메이션 또는 모든 애니메이션 비활성화하기

<!--
With native CSS animations, if you'd like to disable the animations that you've specified, you have multiple options.

1. Create a custom class that forces animation and transition to `none`.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

2. Use the [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) media query to ensure no animations play for users that prefer less animation.

3. Prevent adding animation classes programmatically
-->

네이티브 CSS 애니메이션에서는 지정한 애니메이션을 비활성화하려면 몇 가지 방법을 사용할 수 있습니다.

1. 애니메이션과 전환을 `none`으로 강제 설정하는 커스텀 클래스를 만듭니다.

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

3. 코드에서 애니메이션 클래스가 추가되지 않도록 처리합니다.

### 애니메이션 콜백

<!--
The animations package exposed callbacks for you to use in the case that you want to do something when the animation has finished. Native CSS animations also have these callbacks.

애니메이션 패키지는 애니메이션이 끝났을 때 어떤 동작을 실행할 수 있도록 콜백을 제공했습니다.
네이티브 CSS 애니메이션에도 이런 콜백이 있습니다.

[`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/animationiteration_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)

## 복잡한 시퀀스

애니메이션 패키지는 복잡한 시퀀스를 만드는 기능을 기본으로 제공합니다.
이 시퀀스는 모두 애니메이션 패키지 없이도 구현할 수 있습니다.

### 특정 엘리먼트 선택하기

<!--
In the animations package, you could target specific elements by using the `query()` function to find specific elements by a CSS class name, similar to [`document.querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector). This is unnecessary in a native CSS animation world. Instead, you can use your CSS selectors to target sub-classes and apply any desired `transform` or `animation`.

To toggle classes for child nodes within a template, you can use class and style bindings to add the animations at the right points.
-->

애니메이션 패키지에서는 [`document.querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector)와 비슷하게 `query()` 함수로 CSS 클래스 이름에 해당하는 특정 엘리먼트를 찾을 수 있었습니다.
네이티브 CSS 애니메이션에서는 이 함수가 필요하지 않습니다.
대신 CSS 셀렉터로 하위 엘리먼트의 클래스를 선택하고 원하는 `transform`이나 `animation`을 적용할 수 있습니다.

템플릿의 자식 노드에서 클래스를 전환하려면 클래스 바인딩과 스타일 바인딩을 사용해서 적절한 시점에 애니메이션을 추가하면 됩니다.

### `stagger()`

`stagger()` 함수는 목록의 각 항목에 지정된 시간만큼 지연을 두고 애니메이션을 실행해서 연속적으로 퍼지는 효과를 만들 수 있게 했습니다.
네이티브 CSS에서는 `animation-delay`나 `transition-delay`로 같은 동작을 구현할 수 있습니다.
다음 예제에서 CSS를 어떻게 작성하는지 확인할 수 있습니다.

#### 애니메이션 패키지 사용 {#ko-stagger-with-animations-package}

<!--

-->

#### 네이티브 CSS 사용 {#ko-stagger-with-native-css}

### 병렬 애니메이션

<!--
The animations package has a `group()` function to play multiple animations at the same time. In CSS, you have full control over animation timing. If you have multiple animations defined, you can apply all of them at once.

```css
.target-element {
  animation:
    rotate 3s,
    fade-in 2s;
}
```

In this example, the `rotate` and `fade-in` animations fire at the same time.
-->

애니메이션 패키지에는 여러 애니메이션을 동시에 실행하는 `group()` 함수가 있습니다.
CSS에서는 애니메이션의 타이밍을 자유롭게 제어할 수 있습니다.
여러 애니메이션을 정의했다면 모두 한 번에 적용할 수 있습니다.

```css
.target-element {
  animation:
    rotate 3s,
    fade-in 2s;
}
```

이 예제에서는 `rotate`와 `fade-in` 애니메이션이 동시에 시작합니다.

### 순서가 바뀌는 목록 항목에 애니메이션 적용하기

앞서 설명한 기법을 사용하면 목록 항목의 순서가 바뀌는 경우에도 별도의 추가 작업 없이 바로 동작합니다.
`@for` 반복문의 항목은 올바르게 제거된 뒤 다시 추가되며, 이때 `@starting-styles`를 사용하는 진입 애니메이션이 실행됩니다.
같은 동작을 구현하기 위해 `animate.enter`를 사용할 수도 있습니다.
위 예제처럼 엘리먼트가 제거될 때 애니메이션을 적용하려면 `animate.leave`를 사용하세요.

#### 애니메이션 패키지 사용 {#ko-reordering-list-with-animations-package}

<!--

-->

#### 네이티브 CSS 사용 {#ko-reordering-list-with-native-css}

## AnimationPlayer 사용 코드 마이그레이션하기

<!--
The `AnimationPlayer` class allows access to an animation to do more advanced things like pause, play, restart, and finish an animation through code. All of these things can be handled natively as well.

You can retrieve animations off an element directly using [`Element.getAnimations()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations). This returns an array of every [`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation) on that element. You can use the `Animation` API to do much more than you could with what the `AnimationPlayer` from the animations package offered. From here you can `cancel()`, `play()`, `pause()`, `reverse()` and much more. This native API should provide everything you need to control your animations.
-->

`AnimationPlayer` 클래스를 사용하면 애니메이션에 접근해서 코드로 일시 중지, 재생, 다시 시작, 종료 같은 고급 작업을 할 수 있습니다.
이 작업은 모두 네이티브 API로도 처리할 수 있습니다.

## 라우팅 규칙 전환

뷰 전환을 사용해서 라우팅 규칙 사이에 애니메이션을 적용할 수 있습니다.
시작하려면 [라우팅 규칙 전환 애니메이션 가이드](guide/routing/route-transition-animations)를 참고하세요.

# ZoneJS 없이 Angular 사용하기(Zoneless)

## Zoneless를 사용하는 이유

<!--
The main advantages to removing ZoneJS as a dependency are:

- **Improved performance**: ZoneJS uses DOM events and async tasks as indicators of when application state _might_ have updated and subsequently triggers application synchronization to run change detection on the application's views. ZoneJS does not have any insight into whether application state actually changed and so this synchronization is triggered more frequently than necessary.
- **Improved Core Web Vitals**: ZoneJS brings a fair amount of overhead, both in payload size and startup time.
- **Improved debugging experience**: ZoneJS makes debugging code more difficult. Stack traces are harder to understand with ZoneJS. It's also difficult to understand when code breaks as a result of being outside the Angular Zone.
- **Better ecosystem compatibility**: ZoneJS works by patching browser APIs but does not automatically have patches for every new browser API. Some APIs, such as `async`/`await`, cannot be patched effectively and must be downleveled to work with ZoneJS. Sometimes libraries in the ecosystem are also incompatible with the way ZoneJS patches the native APIs. Removing ZoneJS as a dependency ensures better long-term compatibility by removing a source of complexity, monkey patching, and ongoing maintenance.
-->

ZoneJS 의존성을 제거하면 다음과 같은 주요 이점이 있습니다.

- **성능 개선**: ZoneJS는 DOM 이벤트와 비동기 작업을 애플리케이션 상태가 변경되었을 _가능성_ 을 나타내는 신호로 사용합니다.
  이후 애플리케이션 동기화를 실행해 애플리케이션 뷰의 변경 감지를 수행합니다.
  ZoneJS는 애플리케이션 상태가 실제로 변경되었는지 알 수 없으므로, 이 동기화가 필요한 것보다 더 자주 실행됩니다.
- **Core Web Vitals 개선**: ZoneJS는 전송 크기와 시작 시간 양쪽 모두에 상당한 오버헤드를 추가합니다.
- **디버깅 경험 개선**: ZoneJS는 코드 디버깅을 더 어렵게 만듭니다.
  ZoneJS를 사용하면 스택 트레이스를 이해하기가 더 어렵습니다.
  또한 코드가 Angular Zone 밖에서 실행되어 문제가 생겼는지 알아내기도 어렵습니다.
- **생태계 호환성 개선**: ZoneJS는 브라우저 API를 패치해 동작하지만, 새로 추가되는 모든 브라우저 API에 대한 패치가 자동으로 제공되지는 않습니다.
  `async`/`await`처럼 효과적으로 패치할 수 없는 API는 ZoneJS에서 동작하도록 하위 버전 문법으로 변환해야 합니다.
  생태계의 라이브러리가 ZoneJS의 네이티브 API 패치 방식과 호환되지 않는 경우도 있습니다.
  ZoneJS 의존성을 제거하면 복잡성, 몽키 패치, 지속적인 유지보수의 원인을 없애 장기적인 호환성을 높일 수 있습니다.

## 애플리케이션에서 Zoneless 활성화하기

<!--
Zoneless is the default in Angular v21+ so you do not need to do anything to enable it. You should verify that `provideZoneChangeDetection` is not used anywhere to override the default configuration.

If you are using Angular v20, enable zoneless change detection by adding `provideZonelessChangeDetection()` at bootstrap:

```ts
{header: 'standalone bootstrap'}
bootstrapApplication(MyApp, {providers: [provideZonelessChangeDetection()]});
```

```ts
{header: 'NgModule bootstrap'}
platformBrowser().bootstrapModule(AppModule);

@NgModule({
  providers: [provideZonelessChangeDetection()],
})
export class AppModule {}
```
-->

Angular v21 이상에서는 Zoneless가 기본값이므로 활성화하기 위해 별도로 할 일은 없습니다.
기본 설정을 재정의하는 `provideZoneChangeDetection`을 사용하는 곳이 없는지 확인하세요.

Angular v20을 사용한다면 부트스트랩할 때 `provideZonelessChangeDetection()`을 추가해 Zoneless 변경 감지를 활성화하세요.

```ts
{header: 'standalone bootstrap'}
bootstrapApplication(MyApp, {providers: [provideZonelessChangeDetection()]});
```

```ts
{header: 'NgModule bootstrap'}
platformBrowser().bootstrapModule(AppModule);

@NgModule({
  providers: [provideZonelessChangeDetection()],
})
export class AppModule {}
```

## ZoneJS 제거하기

<!--
Zoneless applications should remove ZoneJS entirely from the build to reduce bundle size. ZoneJS is typically
loaded via the `polyfills` option in `angular.json`, both in the `build` and `test` targets. Remove `zone.js`
and `zone.js/testing` from both to remove it from the build. Projects which use an explicit `polyfills.ts` file
should remove `import 'zone.js';` and `import 'zone.js/testing';` from the file.

After removing ZoneJS from the build, there is no longer a need for a `zone.js` dependency either and the
package can be removed entirely:

```shell
npm uninstall zone.js
```
-->

Zoneless 애플리케이션에서는 번들 크기를 줄이기 위해 빌드에서 ZoneJS를 완전히 제거해야 합니다.
ZoneJS는 일반적으로 `angular.json`의 `build`와 `test` 대상에 있는 `polyfills` 옵션으로 불러옵니다.
빌드에서 제외하려면 두 대상 모두에서 `zone.js`와 `zone.js/testing`을 제거하세요.
별도의 `polyfills.ts` 파일을 사용하는 프로젝트에서는 해당 파일의 `import 'zone.js';`와 `import 'zone.js/testing';`을 제거해야 합니다.

빌드에서 ZoneJS를 제거한 후에는 `zone.js` 의존성도 더 이상 필요하지 않으므로 패키지를 완전히 제거할 수 있습니다.

```shell
npm uninstall zone.js
```

## Zoneless 호환성을 위한 요구사항

<!--
Angular relies on notifications from core APIs in order to determine when to run change detection and on which views.
These notifications include:

- `ChangeDetectorRef.markForCheck` (called automatically by `AsyncPipe`)
- `ComponentRef.setInput`
- Updating a signal that's read in a template
- Bound host or template listeners callbacks
- Attaching a view that was marked dirty by one of the above
-->

Angular는 핵심 API에서 보내는 알림을 통해 언제 어떤 뷰에서 변경 감지를 실행할지 결정합니다.
이러한 알림에는 다음이 포함됩니다.

- `ChangeDetectorRef.markForCheck`(`AsyncPipe`가 자동으로 호출)
- `ComponentRef.setInput`
- 템플릿에서 읽는 시그널의 갱신
- 바인딩된 호스트 리스너나 템플릿 리스너의 콜백
- 위 방법 중 하나로 변경된 상태로 표시된 뷰의 연결

### `OnPush`와 호환되는 컴포넌트

<!--
One way to ensure that a component is using the correct notification mechanisms from above is to
use [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush).

The `OnPush` change detection strategy is not required, but it is a recommended step towards zoneless compatibility for application components. It is not always possible for library components to use `ChangeDetectionStrategy.OnPush`.
When a library component is a host for user-components which might use `ChangeDetectionStrategy.Eager`/`Default`, it cannot use `OnPush` because that would prevent the child component from being refreshed if it is not `OnPush` compatible and relies on ZoneJS to trigger change detection. Components can use the `Default` strategy as long as they notify Angular when change detection needs to run (calling `markForCheck`, using signals, `AsyncPipe`, etc.).
Being a host for a user component means using an API such as `ViewContainerRef.createComponent` and not just hosting a portion of a template from a user component (i.e. content projection or using a template ref input).
-->

컴포넌트가 위의 알림 방식들을 올바르게 사용하는지 확인하는 방법 중 하나는 [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush)를 사용하는 것입니다.

`OnPush` 변경 감지 전략이 필수는 아니지만, 애플리케이션 컴포넌트의 Zoneless 호환성을 확보하는 과정에서 권장되는 단계입니다.
라이브러리 컴포넌트에서는 항상 `ChangeDetectionStrategy.OnPush`를 사용할 수 있는 것은 아닙니다.
라이브러리 컴포넌트가 `ChangeDetectionStrategy.Eager`/`Default`를 사용할 수 있는 사용자 컴포넌트의 호스트라면 `OnPush`를 사용할 수 없습니다.
자식 컴포넌트가 `OnPush`와 호환되지 않고 ZoneJS에 의존해 변경 감지를 실행하는 경우, `OnPush`가 자식 컴포넌트의 갱신을 막기 때문입니다.
컴포넌트는 변경 감지를 실행해야 할 때 Angular에 알리기만 하면(`markForCheck` 호출, 시그널 사용, `AsyncPipe` 사용 등) `Default` 전략을 사용할 수 있습니다.
사용자 컴포넌트의 호스트라는 것은 `ViewContainerRef.createComponent`와 같은 API를 사용한다는 뜻입니다.
사용자 컴포넌트의 템플릿 일부만 호스팅하는 경우(콘텐츠 프로젝션이나 템플릿 참조 입력값 사용)는 여기에 해당하지 않습니다.

### `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, `NgZone.isStable`, `NgZone.onStable` 제거하기

<!--
Applications and libraries need to remove uses of `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, and `NgZone.onStable`.
These observables will never emit when an Application enables zoneless change detection.
Similarly, `NgZone.isStable` will always be `true` and should not be used as a condition for code execution.

The `NgZone.onMicrotaskEmpty` and `NgZone.onStable` observables are most often used to wait for Angular to
complete change detection before performing a task. Instead, these can be replaced by `afterNextRender`
if they need to wait for a single change detection or `afterEveryRender` if there is some condition that might span
several change detection rounds. In other cases, these observables were used because they happened to be
familiar and have similar timing to what was needed. More straightforward or direct DOM APIs can be used instead,
such as `MutationObserver` when code needs to wait for certain DOM state (rather than waiting for it indirectly
through Angular's render hooks).
`NgZone.run` and `NgZone.runOutsideAngular` do not need to be removed in order for code to be compatible with
Zoneless applications. In fact, removing these calls can lead to performance regressions for libraries that
are used in applications that still rely on ZoneJS.

-->

애플리케이션과 라이브러리에서는 `NgZone.onMicrotaskEmpty`, `NgZone.onUnstable`, `NgZone.onStable` 사용을 제거해야 합니다.
애플리케이션에서 Zoneless 변경 감지를 활성화하면 이 옵저버블은 값을 방출하지 않습니다.
마찬가지로 `NgZone.isStable`은 항상 `true`이므로 코드 실행 조건으로 사용해서는 안 됩니다.

`NgZone.onMicrotaskEmpty`와 `NgZone.onStable` 옵저버블은 작업을 수행하기 전에 Angular의 변경 감지가 완료될 때까지 기다리는 용도로 가장 많이 사용됩니다.
변경 감지 한 번이 끝나기를 기다려야 한다면 `afterNextRender`로, 여러 변경 감지 주기에 걸칠 수 있는 조건을 기다려야 한다면 `afterEveryRender`로 대체할 수 있습니다.
단지 익숙하고 필요한 시점과 실행 시점이 비슷하다는 이유로 이 옵저버블들을 사용한 경우도 있습니다.
이때는 더 간단하거나 직접적인 DOM API로 대체할 수 있습니다.
예를 들어 코드가 특정 DOM 상태를 기다려야 한다면 Angular의 렌더링 훅을 통해 간접적으로 기다리는 대신 `MutationObserver`를 사용할 수 있습니다.
Zoneless 애플리케이션과 호환되도록 만들기 위해 `NgZone.run`과 `NgZone.runOutsideAngular`를 제거할 필요는 없습니다.
오히려 이 호출들을 제거하면 여전히 ZoneJS에 의존하는 애플리케이션에서 사용되는 라이브러리의 성능이 저하될 수 있습니다.

### 서버 측 렌더링(SSR)을 위한 `PendingTasks`

<!--
If you are using SSR with Angular, you may know that it relies on ZoneJS to help determine when the application
is "stable" and can be serialized. If there are asynchronous tasks that should prevent serialization, an application
not using ZoneJS must make Angular aware of these with the [PendingTasks](/api/core/PendingTasks) service. Serialization
will wait for the first moment that all pending tasks have been removed.

The two most straightforward uses of pending tasks are the `run` method:

```typescript
const taskService = inject(PendingTasks);
taskService.run(async () => {
  const someResult = await doSomeWorkThatNeedsToBeRendered();
  this.someState.set(someResult);
});
```

For more complicated use-cases, you can manually add and remove a pending task:

```typescript
const taskService = inject(PendingTasks);
const taskCleanup = taskService.add();
try {
  await doSomeWorkThatNeedsToBeRendered();
} catch {
  // handle error
} finally {
  taskCleanup();
}
```

In addition, the [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent) helper in `rxjs-interop` ensures
the application remains unstable until the observable emits, completes, errors, or is unsubscribed.

```typescript
readonly myObservableState = someObservable.pipe(pendingUntilEvent());
```

The framework uses this service internally as well to prevent serialization until asynchronous tasks are complete. These include, but are not limited to, an ongoing Router navigation and an incomplete `HttpClient` request.
-->

Angular에서 SSR을 사용한다면, 애플리케이션이 "안정된 상태"가 되어 직렬화할 수 있는지 판단하는 데 ZoneJS를 활용한다는 점을 알고 계실 수 있습니다.
직렬화를 지연시켜야 하는 비동기 작업이 있다면, ZoneJS를 사용하지 않는 애플리케이션에서는 [PendingTasks](/api/core/PendingTasks) 서비스로 이 작업을 Angular에 알려야 합니다.
직렬화는 대기 중인 모든 작업이 제거되는 첫 시점까지 기다립니다.

대기 중인 작업을 다루는 가장 간단한 두 방법 중 하나는 `run` 메서드입니다.

```typescript
const taskService = inject(PendingTasks);
taskService.run(async () => {
  const someResult = await doSomeWorkThatNeedsToBeRendered();
  this.someState.set(someResult);
});
```

더 복잡한 경우에는 대기 중인 작업을 수동으로 추가하고 제거할 수 있습니다.

```typescript
const taskService = inject(PendingTasks);
const taskCleanup = taskService.add();
try {
  await doSomeWorkThatNeedsToBeRendered();
} catch {
  // 에러를 처리합니다.
} finally {
  taskCleanup();
}
```

또한 `rxjs-interop`의 [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent) 헬퍼를 사용하면 옵저버블이 값을 방출하거나, 완료되거나, 오류가 발생하거나, 구독이 해제될 때까지 애플리케이션이 불안정한 상태를 유지하도록 할 수 있습니다.

```typescript
readonly myObservableState = someObservable.pipe(pendingUntilEvent());
```

프레임워크도 비동기 작업이 끝날 때까지 직렬화를 방지하기 위해 내부적으로 이 서비스를 사용합니다.
이러한 작업에는 진행 중인 라우터 탐색이나 완료되지 않은 `HttpClient` 요청 등이 포함됩니다.

### Zoneless 애플리케이션의 리액티브 폼

<!--
Reactive forms model updates (`setValue`, `patchValue`, `FormArray.push`, and similar APIs) update form state and emit form observables, but they do not automatically schedule component change detection.

If a template depends on reactive forms state, connect forms observables to a change-detection notification (for example `ChangeDetectorRef.markForCheck()`), or reflect the data through signals consumed by the template.
-->

리액티브 폼 모델을 갱신하는 `setValue`, `patchValue`, `FormArray.push` 등의 API는 폼 상태를 갱신하고 폼 옵저버블에서 값을 방출하지만, 컴포넌트의 변경 감지를 자동으로 예약하지는 않습니다.

템플릿이 리액티브 폼 상태에 의존한다면 폼 옵저버블을 변경 감지 알림(예: `ChangeDetectorRef.markForCheck()`)에 연결하거나, 템플릿에서 사용하는 시그널을 통해 데이터를 반영하세요.

## 테스트와 디버깅

### `TestBed`에서 Zoneless 사용하기

<!--
`TestBed` uses zoneless change detection by default, even when `zone.js` is loaded via the `polyfills`.

To use Zone-based change detection in a test, add `provideZoneChangeDetection()` to the `TestBed` providers. Adding `provideZonelessChangeDetection()` is optional:

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

To ensure tests have the most similar behavior to production code,
avoid using `fixture.detectChanges()` when possible. This forces
change detection to run when Angular might otherwise have not
scheduled change detection. Tests should ensure these notifications
are happening and allow Angular to handle when to synchronize
state rather than manually forcing it to happen in the test.

For existing test suites, using `fixture.detectChanges()` is a common pattern
and it is likely not worth the effort of converting these to
`await fixture.whenStable()`. `TestBed` will still enforce that the
fixture's component is `OnPush` compatible and throws `ExpressionChangedAfterItHasBeenCheckedError`
if it finds that template values were updated without a
change notification (i.e. `fixture.componentInstance.someValue = 'newValue';`).
If the component is used in production, this issue should be addressed by updating
the component to use signals for state or call `ChangeDetectorRef.markForCheck()`.
If the component is only used as a test wrapper and never used in an application,
it is acceptable to use `ChangeDetectionStrategy.Eager` for it and call `fixture.changeDetectorRef.markForCheck()`.

IMPORTANT: `fixture.changeDetectorRef` belongs to the fixture's host view, so its `markForCheck()`
doesn't refresh the template of an `OnPush` component. Your application components shouldn't need it
in tests. If a test needs it, the component usually isn't fully reactive or
[zoneless compatible](#requirements-for-zoneless-compatibility).
-->

`TestBed`는 `polyfills`로 `zone.js`를 불러온 경우에도 기본적으로 Zoneless 변경 감지를 사용합니다.

테스트에서 Zone 기반 변경 감지를 사용하려면 `TestBed` 프로바이더에 `provideZoneChangeDetection()`을 추가하세요. `provideZonelessChangeDetection()` 추가는 선택 사항입니다.

```typescript
TestBed.configureTestingModule({
  // 선택 사항: 프로바이더를 추가해 테스트 환경이
  // Zoneless 애플리케이션과 같은 방식으로 동작하도록 합니다.
  providers: [provideZonelessChangeDetection()],
});

const fixture = TestBed.createComponent(MyComponent);
await fixture.whenStable();
```

테스트가 프로덕션 코드와 최대한 비슷하게 동작하도록 하려면 가능한 한 `fixture.detectChanges()`를 사용하지 마세요.
이 메서드는 Angular가 변경 감지를 예약하지 않았을 상황에서도 변경 감지를 강제로 실행합니다.
테스트에서는 수동으로 상태 동기화를 강제하는 대신, 알림이 발생하는지 확인하고 동기화 시점은 Angular가 결정하도록 해야 합니다.

기존 테스트 모음에서는 `fixture.detectChanges()` 사용이 흔한 패턴이며, 이를 `await fixture.whenStable()`로 바꾸는 데 드는 노력만큼의 이점은 크지 않을 수 있습니다.
`TestBed`는 여전히 fixture의 컴포넌트가 `OnPush`와 호환되는지 확인하며, 변경 알림 없이 템플릿 값이 갱신된 경우(예: `fixture.componentInstance.someValue = 'newValue';`) `ExpressionChangedAfterItHasBeenCheckedError`를 발생시킵니다.
프로덕션에서 사용하는 컴포넌트라면 상태에 시그널을 사용하거나 `ChangeDetectorRef.markForCheck()`를 호출하도록 컴포넌트를 수정해 이 문제를 해결해야 합니다.
컴포넌트가 테스트용 래퍼로만 사용되고 애플리케이션에서는 사용되지 않는다면 해당 컴포넌트에 `ChangeDetectionStrategy.Eager`를 지정하고 `fixture.changeDetectorRef.markForCheck()`를 호출해도 괜찮습니다.

중요: `fixture.changeDetectorRef`는 fixture의 호스트 뷰에 속하기 때문에, 이 객체의 `markForCheck()`를 호출해도 `OnPush` 컴포넌트의 템플릿은 갱신되지 않습니다.
애플리케이션 컴포넌트를 테스트할 때는 이 메서드가 필요하지 않아야 합니다.
테스트에 이 메서드가 필요하다면, 대개 해당 컴포넌트가 완전히 반응형으로 동작하지 않거나 [Zoneless와 호환되지 않는](#requirements-for-zoneless-compatibility) 상태입니다.

### 갱신이 감지되는지 디버그 모드에서 확인하기

<!--
IMPORTANT: `provideCheckNoChangesConfig` is in [developer preview](reference/releases#developer-preview).

Angular also provides an additional tool to help verify that an application is making
updates to state in a zoneless-compatible way. `provideCheckNoChangesConfig({exhaustive: true, interval: <milliseconds>})`
can be used to periodically check to ensure that no bindings have been updated
without a notification. Angular throws `ExpressionChangedAfterItHasBeenCheckedError`
if there is an updated binding that would not have refreshed by the zoneless change
detection.
-->

IMPORTANT: `provideCheckNoChangesConfig`는 [개발자 미리보기](reference/releases#developer-preview) 단계입니다.

Angular는 애플리케이션이 Zoneless와 호환되는 방식으로 상태를 갱신하는지 확인하는 추가 도구도 제공합니다.
`provideCheckNoChangesConfig({exhaustive: true, interval: <milliseconds>})`를 사용하면 알림 없이 갱신된 바인딩이 없는지 주기적으로 확인할 수 있습니다.
Zoneless 변경 감지로는 갱신되지 않을 바인딩의 변경이 발견되면 Angular는 `ExpressionChangedAfterItHasBeenCheckedError`를 발생시킵니다.
<!--
As an open source project, Angular’s daily commits, PRs and momentum is all trackable on GitHub. To increase transparency into how this daily work connects to the framework’s future, our roadmap brings together the team’s current and future planned vision.

The following projects are not associated with a particular Angular version. We will release them on completion, and they will be part of a specific version based on our release schedule, following semantic versioning. For example, we release features in the next minor after completion or the next major if they include breaking changes.

Currently, Angular has three goals for the framework:

1. Improve the [AI experience for developers](/ai)
1. Improve the [Angular developer experience](#improving-the-angular-developer-experience)
1. Improve the framework’s performance

Continue reading to learn how we plan to deliver these objectives with specific project work.
-->
Angular는 오픈 소스 프로젝트이므로 매일 이루어지는 커밋, PR, 개발 현황을 GitHub에서 모두 확인할 수 있습니다. 이러한 일상적인 작업이 프레임워크의 미래와 어떻게 연결되는지 더 투명하게 보여 주기 위해, 로드맵에는 팀이 현재 진행 중인 작업과 앞으로 계획하는 방향을 함께 정리했습니다.

다음 프로젝트는 특정 Angular 버전에 연결되어 있지 않습니다. 완료되면 릴리즈하며, 유의적 버전 관리와 릴리즈 일정에 따라 특정 버전에 포함합니다. 예를 들어 기능이 완성되면 다음 마이너 버전에 포함하고, 호환성을 깨뜨리는 변경이 있다면 다음 메이저 버전에 포함합니다.

현재 Angular 프레임워크의 목표는 세 가지입니다.

1. [개발자의 AI 활용 경험](/ai) 개선
1. [Angular 개발자 경험](#improving-the-angular-developer-experience) 개선
1. 프레임워크 성능 개선

각 프로젝트를 통해 이러한 목표를 어떻게 실현할 계획인지 계속 읽어 보세요.

## 최신 Angular 살펴보기

로드맵에 있는 최신 Angular 기능으로 개발을 시작해 보세요. 다음 목록은 로드맵의 새로운 기능들이 현재 어떤 상태인지 보여 줍니다.

### 실험적으로 사용 가능

- [Web MCP](/ai/webmcp)

### 프로덕션에서 사용 가능

- [시그널 폼](/guide/forms/signals/overview)
- [리소스 API](/guide/signals/resource)
- [httpResource](/api/common/http/httpResource)
- [존리스 변경 감지](/guide/zoneless)
- [연결된 시그널 API](/guide/signals/linked-signal)
- [점진적 하이드레이션](/guide/incremental-hydration)
- [이펙트 함수 API](/api/core/effect)
- [SSR에서 이벤트 재실행](/api/platform-browser/withEventReplay)
- [라우팅 규칙 수준 렌더링 모드](/guide/ssr)

## Angular 개발자의 AI 활용 경험 개선

### Angular에 AI의 장점 도입
-->
<!--

-->
<!--

-->

## Angular 개발자 경험 개선

### 개발 속도 향상
-->
<!--

-->
<!--

-->

### 도구 개선
-->

## 완료된 프로젝트
-->
<!--

-->
<!--

-->

# Angular 프로젝트를 최신 상태로 유지하기

<!--
Just like Web and the entire web ecosystem, Angular is continuously improving.
Angular balances continuous improvement with a strong focus on stability and making updates straightforward.
Keeping your Angular application up-to-date enables you to take advantage of leading-edge new features, as well as optimizations and bug fixes.

This document contains information and resources to help you keep your Angular applications and libraries up-to-date.

For information about our versioning policy and practices — including support and deprecation practices, as well as the release schedule — see [Angular versioning and releases](reference/releases 'Angular versioning and releases').

HELPFUL: If you are currently using AngularJS, see [Upgrading from AngularJS](https://angular.io/guide/upgrade 'Upgrading from AngularJS').
_AngularJS_ is the name for all v1.x versions of Angular.
-->

웹과 웹 생태계 전체가 그렇듯 Angular도 지속적으로 개선되고 있습니다.
Angular는 안정성과 간편한 업데이트를 중시하면서 지속적인 개선과 균형을 맞춥니다.
Angular 애플리케이션을 최신 상태로 유지하면 최신 기능과 최적화, 버그 수정을 활용할 수 있습니다.

이 문서는 Angular 애플리케이션과 라이브러리를 최신 상태로 유지하는 데 도움이 되는 정보와 리소스를 제공합니다.

지원 및 사용 중단 권고 정책, 릴리즈 일정 등 버전 정책과 운영 방식은 [Angular 버전 관리와 릴리즈](reference/releases 'Angular 버전 관리와 릴리즈')를 참고하세요.

도움말: 현재 AngularJS를 사용하고 있다면 [AngularJS에서 업그레이드하기](https://angular.io/guide/upgrade 'AngularJS에서 업그레이드하기')를 참고하세요.
_AngularJS_ 는 Angular의 모든 v1.x 버전을 가리키는 이름입니다.

## 새 릴리즈 알림 받기

새 릴리즈가 나왔을 때 알림을 받으려면 X(이전 Twitter)에서 [@angular](https://x.com/angular 'X의 @angular')를 팔로우하거나 [Angular 블로그](https://blog.angular.dev 'Angular 블로그')를 구독하세요.

## 새로운 기능 알아보기

<!--
What's new? What's changed? We share the most important things you need to know on the Angular blog in [release announcements](https://blog.angular.dev/ 'Angular blog - release announcements').

To review a complete list of changes, organized by version, see the [Angular change log](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular change log').
-->

어떤 기능이 새로 생겼고 무엇이 바뀌었을까요?
꼭 알아야 할 주요 내용은 Angular 블로그의 [릴리즈 안내](https://blog.angular.dev/ 'Angular 블로그 - 릴리즈 안내')에서 공유합니다.

버전별 전체 변경 사항은 [Angular 변경 이력](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular 변경 이력')을 참고하세요.

## 사용 중인 Angular 버전 확인하기

애플리케이션의 Angular 버전을 확인하려면 프로젝트 디렉터리에서 `ng version` 명령을 실행하세요.

## Angular 최신 버전 확인하기

<!--
The most recent stable released version of Angular appears [on npm](https://www.npmjs.com/package/@angular/core 'Angular on npm') under "Version." For example, `16.2.4`.

You can also find the most current version of Angular by using the CLI command [`ng update`](cli/update).
By default, [`ng update`](cli/update) (without additional arguments) lists the updates that are available to you.
-->

Angular의 최신 안정 버전은 [npm](https://www.npmjs.com/package/@angular/core 'npm의 Angular')의 "Version" 항목에 표시됩니다.
예를 들어 `16.2.4`와 같은 형식입니다.

CLI의 [`ng update`](cli/update) 명령으로도 Angular 최신 버전을 확인할 수 있습니다.
추가 인자 없이 [`ng update`](cli/update)를 실행하면 기본적으로 적용할 수 있는 업데이트 목록이 표시됩니다.

## 개발 환경과 앱 업데이트하기

<!--
To make updating uncomplicated, we provide complete instructions in the interactive [Angular Update Guide](update-guide).

The Angular Update Guide provides customized update instructions, based on the current and target versions that you specify.
It includes basic and advanced update paths, to match the complexity of your applications.
It also includes troubleshooting information and any recommended manual changes to help you get the most out of the new release.

For simple updates, the CLI command [`ng update`](cli/update) is all you need.
Without additional arguments, [`ng update`](cli/update) lists the updates that are available to you and provides recommended steps to update your application to the most current version.

[Angular Versioning and Releases](reference/releases#angular-versioning 'Angular Release Practices, Versioning') describes the level of change that you can expect based on a release's version number.
It also describes supported update paths.
-->

업데이트를 쉽게 진행할 수 있도록 대화형 [Angular 업데이트 가이드](update-guide)에서 전체 절차를 안내합니다.

Angular 업데이트 가이드는 지정한 현재 버전과 목표 버전에 따라 맞춤형 업데이트 지침을 제공합니다.
애플리케이션의 복잡도에 맞게 기본 및 고급 업데이트 경로를 포함합니다.
새 릴리즈를 최대한 활용할 수 있도록 문제 해결 정보와 권장하는 수동 변경 사항도 안내합니다.

간단한 업데이트는 CLI의 [`ng update`](cli/update) 명령만 있으면 됩니다.
추가 인자 없이 [`ng update`](cli/update)를 실행하면 적용할 수 있는 업데이트 목록과 애플리케이션을 최신 버전으로 업데이트하는 권장 절차를 제공합니다.

[Angular 버전 관리와 릴리즈](reference/releases#angular-versioning 'Angular 릴리즈 방식과 버전 관리')에서는 릴리즈 버전 번호에 따라 어느 정도의 변경을 예상할 수 있는지 설명합니다.
지원하는 업데이트 경로도 설명합니다.

## 참고 리소스

<!--
- Release announcements:
  [Angular blog - release announcements](https://blog.angular.dev/ 'Angular blog announcements about recent releases')

- Release details:
  [Angular change log](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular change log')

- Update instructions:
  [Angular Update Guide](update-guide)

- Update command reference:
  [Angular CLI `ng update` command reference](cli/update)

- Versioning, release, support, and deprecation practices:
  [Angular versioning and releases](reference/releases 'Angular versioning and releases')
-->

- 릴리즈 안내:
  [Angular 블로그 - 릴리즈 안내](https://blog.angular.dev/ '최근 릴리즈에 관한 Angular 블로그 안내')

- 릴리즈 세부 정보:
  [Angular 변경 이력](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular 변경 이력')

- 업데이트 지침:
  [Angular 업데이트 가이드](update-guide)

- 업데이트 명령 레퍼런스:
  [Angular CLI `ng update` 명령 레퍼런스](cli/update)

- 버전 관리, 릴리즈, 지원, 사용 중단 권고 정책:
  [Angular 버전 관리와 릴리즈](reference/releases 'Angular 버전 관리와 릴리즈')
<!--

-->

<a id="angular-internationalization-i18n"></a>
<!--
_Internationalization_, sometimes referenced as i18n, is the process of designing and preparing your project for use in different locales around the world.
_Localization_ is the process of building versions of your project for different locales.
The localization process includes the following actions.

- Extract text for translation into different languages
- Format data for a specific locale

A _locale_ identifies a region in which people speak a particular language or language variant.
Possible regions include countries and geographical regions.
A locale determines the formatting and parsing of the following details.

- Measurement units including date and time, numbers, and currencies
- Translated names including time zones, languages, and countries

For a quick introduction to localization and internationalization watch this video:

<docs-video src="https://www.youtube.com/embed/KNTN-nsbV7M"/>
-->

_국제화(Internationalization)_ 는 i18n이라고도 하며, 프로젝트를 전 세계 여러 지역에서 사용할 수 있도록 설계하고 준비하는 과정입니다.
_현지화(Localization)_ 는 여러 지역에 맞는 프로젝트 버전을 만드는 과정입니다.
현지화 과정에는 다음 작업이 포함됩니다.

- 여러 언어로 번역할 텍스트 추출
- 특정 지역에 맞게 데이터 형식 지정

_지역(locale)_ 은 특정 언어나 언어의 변형을 사용하는 지역을 나타냅니다.
이 지역에는 국가나 지리적 지역이 포함될 수 있습니다.
지역은 다음 항목의 형식을 지정하고 파싱하는 방식을 결정합니다.

- 날짜와 시간, 숫자, 통화 등의 측정 단위
- 시간대, 언어, 국가 등의 번역된 이름

현지화와 국제화를 간단히 알아보려면 다음 동영상을 참고하세요.

<docs-video src="https://www.youtube.com/embed/KNTN-nsbV7M"/>

## Angular 국제화 알아보기

# 보안

<!--
This topic describes Angular's built-in protections against common web application vulnerabilities and attacks such as cross-site scripting attacks.
It doesn't cover application-level security, such as authentication and authorization.

For more information about the attacks and mitigations described below, see the [Open Web Application Security Project (OWASP) Guide](https://www.owasp.org/index.php/Category:OWASP_Guide_Project).

<a id="report-issues"></a>
Angular is part of Google [Open Source Software Vulnerability Reward Program](https://bughunters.google.com/about/rules/6521337925468160/google-open-source-software-vulnerability-reward-program-rules). For vulnerabilities in Angular, please submit your report at [https://bughunters.google.com](https://bughunters.google.com/report).

For more information about how Google handles security issues, see [Google's security philosophy](https://www.google.com/about/appsecurity).
-->

이 문서는 크로스 사이트 스크립팅 공격과 같은 일반적인 웹 애플리케이션 취약점과 공격에 대응하는 Angular의 내장 보호 기능을 설명합니다.
인증이나 인가처럼 애플리케이션 수준에서 다루는 보안은 설명하지 않습니다.

아래에 설명하는 공격과 대응 방법에 대한 자세한 내용은 [Open Web Application Security Project(OWASP) 가이드](https://www.owasp.org/index.php/Category:OWASP_Guide_Project)를 참고하세요.

<a id="report-issues"></a>
Angular는 Google [오픈소스 소프트웨어 취약점 보상 프로그램](https://bughunters.google.com/about/rules/6521337925468160/google-open-source-software-vulnerability-reward-program-rules)에 참여하고 있습니다.
Angular의 취약점은 [https://bughunters.google.com](https://bughunters.google.com/report)에서 신고해 주세요.

Google의 보안 문제 처리 방식에 대한 자세한 내용은 [Google의 보안 철학](https://www.google.com/about/appsecurity)을 참고하세요.

## 모범 사례

<!--
These are some best practices to ensure that your Angular application is secure.

1. **Keep current with the latest Angular library releases** - The Angular libraries get regular updates, and these updates might fix security defects discovered in previous versions. Check the Angular [change log](https://github.com/angular/angular/blob/main/CHANGELOG.md) for security-related updates.
2. **Don't alter your copy of Angular** - Private, customized versions of Angular tend to fall behind the current version and might not include important security fixes and enhancements. Instead, share your Angular improvements with the community and make a pull request.
3. **Avoid Angular APIs marked in the documentation as "_Security Risk_"** - For more information, see the [Trusting safe values](#trusting-safe-values) section of this page.
-->

Angular 애플리케이션의 보안을 유지하기 위한 모범 사례는 다음과 같습니다.

1. **Angular 라이브러리를 최신 버전으로 유지하세요.**
   Angular 라이브러리는 정기적으로 갱신되며, 이전 버전에서 발견된 보안 결함이 수정될 수 있습니다.
   Angular [변경 이력](https://github.com/angular/angular/blob/main/CHANGELOG.md)에서 보안 관련 갱신 사항을 확인하세요.
2. **사용 중인 Angular 자체를 수정하지 마세요.**
   Angular를 비공개로 수정한 커스텀 버전은 최신 버전보다 뒤처지기 쉬우며, 중요한 보안 수정과 개선 사항이 포함되지 않을 수 있습니다.
   대신 Angular 개선 사항을 커뮤니티에 공유하고 풀 리퀘스트를 보내세요.
3. **문서에 "_Security Risk_"로 표시된 Angular API는 사용을 피하세요.**
   자세한 내용은 이 페이지의 [안전한 값을 신뢰하도록 지정하기](#trusting-safe-values) 섹션을 참고하세요.

## 크로스 사이트 스크립팅(XSS) 방지하기

<!--
[Cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) enables attackers to inject malicious code into web pages.
Such code can then, for example, steal user and login data, or perform actions that impersonate the user.
This is one of the most common attacks on the web.

To block XSS attacks, you must prevent malicious code from entering the Document Object Model (DOM).
For example, if attackers can trick you into inserting a `<script>` tag in the DOM, they can run arbitrary code on your website.
The attack isn't limited to `<script>` tags —many elements and properties in the DOM allow code execution, for example, `<img alt="" onerror="...">` and `<a href="javascript:...">`.
If attacker-controlled data enters the DOM, expect security vulnerabilities.
-->

[크로스 사이트 스크립팅(XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting)은 공격자가 웹 페이지에 악성 코드를 삽입할 수 있게 하는 공격입니다.
이 코드는 사용자 정보나 로그인 정보를 훔치거나 사용자를 사칭해 작업을 수행하는 데 사용될 수 있습니다.
웹에서 가장 흔한 공격 중 하나입니다.

XSS 공격을 차단하려면 악성 코드가 문서 객체 모델(DOM)에 들어가지 못하도록 해야 합니다.
예를 들어 공격자가 개발자를 속여 DOM에 `<script>` 태그를 삽입하게 만들면 웹사이트에서 임의의 코드를 실행할 수 있습니다.
이 공격은 `<script>` 태그에만 한정되지 않습니다.
`<img alt="" onerror="...">`나 `<a href="javascript:...">`처럼 DOM의 여러 엘리먼트와 프로퍼티에서 코드를 실행할 수 있습니다.
공격자가 제어하는 데이터가 DOM에 들어오면 보안 취약점이 발생할 수 있다고 보아야 합니다.

### Angular의 크로스 사이트 스크립팅 보안 모델

<!--
To systematically block XSS bugs, Angular treats all values as untrusted by default.
When a value is inserted into the DOM from a template binding, or interpolation, Angular sanitizes and escapes untrusted values.
If a value was already sanitized outside of Angular and is considered safe, communicate this to Angular by marking the [value as trusted](#trusting-safe-values).

Unlike values to be used for rendering, Angular templates are considered trusted by default, and should be treated as executable code.
Never create templates by concatenating user input and template syntax.
Doing this would enable attackers to [inject arbitrary code](https://en.wikipedia.org/wiki/Code_injection) into your application.
To prevent these vulnerabilities, always use the default [Ahead-Of-Time (AOT) template compiler](#use-the-aot-template-compiler) in production deployments.

An extra layer of protection can be provided through the use of Content security policy and Trusted Types.
These web platform features operate at the DOM level which is the most effective place to prevent XSS issues. Here they can't be bypassed using other, lower-level APIs.
For this reason, it is strongly encouraged to take advantage of these features. To do this, configure the [content security policy](#content-security-policy) for the application and enable [trusted types enforcement](#enforcing-trusted-types).
-->

Angular는 XSS 버그를 체계적으로 차단하기 위해 기본적으로 모든 값을 신뢰할 수 없는 값으로 취급합니다.
템플릿 바인딩이나 문자열 바인딩을 통해 DOM에 값을 삽입할 때 Angular는 신뢰할 수 없는 값을 정제(sanitize)하고 이스케이프합니다.
Angular 외부에서 이미 정제되어 안전하다고 판단한 값이라면, [신뢰할 수 있는 값으로 표시](#trusting-safe-values)해 Angular에 알려주세요.

렌더링에 사용하는 값과 달리 Angular 템플릿은 기본적으로 신뢰할 수 있다고 간주되며, 실행 가능한 코드로 취급해야 합니다.
사용자 입력과 템플릿 구문을 이어 붙여 템플릿을 만들지 마세요.
그렇게 하면 공격자가 애플리케이션에 [임의의 코드를 삽입](https://en.wikipedia.org/wiki/Code_injection)할 수 있습니다.
이러한 취약점을 방지하려면 프로덕션 배포에서 항상 기본 [AOT(Ahead-Of-Time) 템플릿 컴파일러](#use-the-aot-template-compiler)를 사용하세요.

콘텐츠 보안 정책과 Trusted Types를 사용하면 보호 계층을 추가할 수 있습니다.
이 웹 플랫폼 기능들은 XSS 문제를 방지하기에 가장 효과적인 DOM 수준에서 동작합니다.
따라서 더 저수준의 다른 API를 사용해 우회할 수 없습니다.
이러한 이유로 이 기능들을 적극적으로 활용하는 것을 권장합니다.
애플리케이션의 [콘텐츠 보안 정책](#content-security-policy)을 설정하고 [Trusted Types 강제 적용](#enforcing-trusted-types)을 활성화하세요.

### 정제와 보안 컨텍스트

<!--
_Sanitization_ is the inspection of an untrusted value, turning it into a value that's safe to insert into the DOM.
In many cases, sanitization doesn't change a value at all.
Sanitization depends on a context.
For example, a value that's harmless in CSS is potentially dangerous in a URL.

Angular defines the following security contexts:

Angular sanitizes untrusted values for HTML and URLs. Sanitizing resource URLs isn't possible because they contain arbitrary code.
In development mode, Angular prints a console warning when it has to change a value during sanitization.
-->

_정제_ 는 신뢰할 수 없는 값을 검사해 DOM에 안전하게 삽입할 수 있는 값으로 바꾸는 과정입니다.
정제 과정에서 값이 전혀 바뀌지 않는 경우도 많습니다.
정제 방식은 컨텍스트에 따라 달라집니다.
예를 들어 CSS에서는 무해한 값이 URL에서는 위험할 수 있습니다.

Angular는 다음 보안 컨텍스트를 정의합니다.

Angular는 HTML과 URL에서 신뢰할 수 없는 값을 정제합니다.
리소스 URL은 임의의 코드를 포함하므로 정제할 수 없습니다.
개발 모드에서는 Angular가 정제 과정에서 값을 변경해야 할 때 콘솔에 경고를 출력합니다.

### 정제 예제

<!--
The following template binds the value of `htmlSnippet`. Once by interpolating it into an element's content, and once by binding it to the `innerHTML` property of an element:

<docs-code header="inner-html-binding.component.html" path="adev/src/content/examples/security/src/app/inner-html-binding.component.html"/>

Interpolated content is always escaped —the HTML isn't interpreted and the browser displays angle brackets in the element's text content.

For the HTML to be interpreted, bind it to an HTML property such as `innerHTML`.
Be aware that binding a value that an attacker might control into `innerHTML` normally causes an XSS vulnerability.
For example, one could run JavaScript in a following way:

<docs-code header="inner-html-binding.component.ts (class)" path="adev/src/content/examples/security/src/app/inner-html-binding.component.ts" region="class"/>

Angular recognizes the value as unsafe and automatically sanitizes it, which removes the `script` element but keeps safe content such as the `<b>` element.

다음 템플릿은 `htmlSnippet`의 값을 두 가지 방식으로 바인딩합니다.
하나는 문자열 바인딩을 사용해 엘리먼트의 내용에 넣고, 다른 하나는 엘리먼트의 `innerHTML` 프로퍼티에 바인딩합니다.

<docs-code header="inner-html-binding.component.html" path="adev/src/content/examples/security/src/app/inner-html-binding.component.html"/>

문자열 바인딩으로 넣은 내용은 항상 이스케이프됩니다.
HTML로 해석되지 않으므로 브라우저는 꺾쇠괄호를 엘리먼트의 텍스트 내용으로 표시합니다.

HTML로 해석하게 하려면 `innerHTML`과 같은 HTML 프로퍼티에 바인딩하세요.
공격자가 제어할 수 있는 값을 `innerHTML`에 바인딩하면 일반적으로 XSS 취약점이 생긴다는 점에 유의하세요.
예를 들어 다음과 같은 방식으로 JavaScript를 실행할 수 있습니다.

<docs-code header="inner-html-binding.component.ts (클래스)" path="adev/src/content/examples/security/src/app/inner-html-binding.component.ts" region="class"/>

Angular는 이 값을 안전하지 않다고 인식해 자동으로 정제합니다.
`script` 엘리먼트는 제거하지만 `<b>` 엘리먼트와 같은 안전한 내용은 유지합니다.

### DOM API 직접 사용과 명시적 정제 호출

<!--
Unless you enforce Trusted Types, the built-in browser DOM APIs don't automatically protect you from security vulnerabilities.
For example, `document`, the node available through `ElementRef`, and many third-party APIs contain unsafe methods.
Likewise, if you interact with other libraries that manipulate the DOM, you likely won't have the same automatic sanitization as with Angular interpolations.
Avoid directly interacting with the DOM and instead use Angular templates where possible.

For cases where this is unavoidable, use the built-in Angular sanitization functions.
Sanitize untrusted values with the [DomSanitizer.sanitize](api/platform-browser/DomSanitizer#sanitize) method and the appropriate `SecurityContext`.
That function also accepts values that were marked as trusted using the `bypassSecurityTrust` functions, and does not sanitize them, as [described below](#trusting-safe-values).
-->

Trusted Types를 강제 적용하지 않는 한, 브라우저의 내장 DOM API는 보안 취약점을 자동으로 방어하지 않습니다.
예를 들어 `document`, `ElementRef`를 통해 접근하는 노드, 여러 서드 파티 API에는 안전하지 않은 메서드가 포함되어 있습니다.
마찬가지로 DOM을 조작하는 다른 라이브러리와 상호작용할 때는 Angular 문자열 바인딩과 같은 자동 정제 기능을 제공받지 못할 가능성이 높습니다.
DOM을 직접 조작하는 것은 피하고, 가능하면 Angular 템플릿을 사용하세요.

직접 조작이 불가피하다면 Angular에 내장된 정제 함수를 사용하세요.
[DomSanitizer.sanitize](api/platform-browser/DomSanitizer#sanitize) 메서드와 적절한 `SecurityContext`로 신뢰할 수 없는 값을 정제하세요.
이 함수는 `bypassSecurityTrust` 함수로 신뢰할 수 있다고 표시한 값도 받으며, [아래에서 설명하는 것처럼](#trusting-safe-values) 해당 값은 정제하지 않습니다.

### 안전한 값을 신뢰하도록 지정하기

<!--
Sometimes applications genuinely need to include executable code, display an `<iframe>` from some URL, or construct potentially dangerous URLs.
To prevent automatic sanitization in these situations, tell Angular that you inspected a value, checked how it was created, and made sure it is secure.
Do _be careful_.
If you trust a value that might be malicious, you are introducing a security vulnerability into your application.
If in doubt, find a professional security reviewer.

To mark a value as trusted, inject `DomSanitizer` and call one of the following methods:

- `bypassSecurityTrustHtml`
- `bypassSecurityTrustScript`
- `bypassSecurityTrustStyle`
- `bypassSecurityTrustUrl`
- `bypassSecurityTrustResourceUrl`

Remember, whether a value is safe depends on context, so choose the right context for your intended use of the value.
Imagine that the following template needs to bind a URL to a `javascript:alert(...)` call:

<docs-code header="bypass-security.component.html (URL)" path="adev/src/content/examples/security/src/app/bypass-security.component.html" region="URL"/>

Normally, Angular automatically sanitizes the URL, disables the dangerous code, and in development mode, logs this action to the console.
To prevent this, mark the URL value as a trusted URL using the `bypassSecurityTrustUrl` call:

<docs-code header="bypass-security.component.ts (trust-url)" path="adev/src/content/examples/security/src/app/bypass-security.component.ts" region="trust-url"/>

If you need to convert user input into a trusted value, use a component method.
The following template lets users enter a YouTube video ID and load the corresponding video in an `<iframe>`.
The `<iframe src>` attribute is a resource URL security context, because an untrusted source can, for example, smuggle in file downloads that unsuspecting users could run.
To prevent this, call a method on the component to construct a trusted video URL, which causes Angular to let binding into `<iframe src>`:

<docs-code header="bypass-security.component.html (iframe)" path="adev/src/content/examples/security/src/app/bypass-security.component.html" region="iframe"/>

<docs-code header="bypass-security.component.ts (trust-video-url)" path="adev/src/content/examples/security/src/app/bypass-security.component.ts" region="trust-video-url"/>
-->

애플리케이션에 실행 가능한 코드를 포함하거나, 특정 URL의 `<iframe>`을 표시하거나, 잠재적으로 위험한 URL을 구성해야 할 때가 있습니다.
이러한 상황에서 자동 정제를 막으려면 값을 검사하고, 생성 방식을 확인했으며, 안전하다는 것을 확인했다고 Angular에 알려주세요.
이 작업은 _주의해서_ 수행해야 합니다.
악성일 수 있는 값을 신뢰하면 애플리케이션에 보안 취약점을 만들게 됩니다.
확신이 없다면 보안 전문가의 검토를 받으세요.

값을 신뢰할 수 있다고 표시하려면 `DomSanitizer`를 주입하고 다음 메서드 중 하나를 호출하세요.

- `bypassSecurityTrustHtml`
- `bypassSecurityTrustScript`
- `bypassSecurityTrustStyle`
- `bypassSecurityTrustUrl`
- `bypassSecurityTrustResourceUrl`

값의 안전성은 컨텍스트에 따라 달라지므로, 값을 사용할 목적에 맞는 컨텍스트를 선택해야 합니다.
다음 템플릿에서 `javascript:alert(...)` 호출을 URL에 바인딩해야 한다고 가정해 봅시다.

<docs-code header="bypass-security.component.html (URL)" path="adev/src/content/examples/security/src/app/bypass-security.component.html" region="URL"/>

일반적으로 Angular는 URL을 자동으로 정제해 위험한 코드를 비활성화하고, 개발 모드에서는 이 작업을 콘솔에 기록합니다.
이를 막으려면 `bypassSecurityTrustUrl`을 호출해 해당 URL 값을 신뢰할 수 있는 URL로 표시하세요.

<docs-code header="bypass-security.component.ts (trust-url)" path="adev/src/content/examples/security/src/app/bypass-security.component.ts" region="trust-url"/>

사용자 입력을 신뢰할 수 있는 값으로 변환해야 한다면 컴포넌트 메서드를 사용하세요.
다음 템플릿에서는 사용자가 YouTube 동영상 ID를 입력하면 해당 동영상을 `<iframe>`에 불러옵니다.
`<iframe src>` 어트리뷰트는 리소스 URL 보안 컨텍스트에 해당합니다.
신뢰할 수 없는 출처가 사용자가 의심 없이 실행할 수 있는 파일을 몰래 다운로드하게 만드는 등의 위험이 있기 때문입니다.
이를 방지하려면 컴포넌트의 메서드를 호출해 신뢰할 수 있는 동영상 URL을 구성하세요.
그러면 Angular가 `<iframe src>` 바인딩을 허용합니다.

<docs-code header="bypass-security.component.html (iframe)" path="adev/src/content/examples/security/src/app/bypass-security.component.html" region="iframe"/>

<docs-code header="bypass-security.component.ts (trust-video-url)" path="adev/src/content/examples/security/src/app/bypass-security.component.ts" region="trust-video-url"/>

### 콘텐츠 보안 정책

<!--
Content Security Policy $CSP$ is a defense-in-depth technique to prevent XSS.
To enable CSP, configure your web server to return an appropriate `Content-Security-Policy` HTTP header.
Read more about content security policy at the [Web Fundamentals guide](https://developers.google.com/web/fundamentals/security/csp) on the Google Developers website.

The minimal policy required for a brand-new Angular application is:

```txt
default-src 'self'; style-src 'self' 'nonce-randomNonceGoesHere'; script-src 'self' 'nonce-randomNonceGoesHere';
```

When serving your Angular application, the server should include a randomly-generated nonce in the HTTP header for each request.
You must provide this nonce to Angular so that the framework can render `<style>` elements.
You can set the nonce for Angular in one of the following ways:

1. Set the `ngCspNonce` attribute on the root application element as `<app ngCspNonce="randomNonceGoesHere"></app>`. Use this approach if you have access to server-side templating that can add the nonce both to the header and the `index.html` when constructing the response.
1. Provide the nonce using the `CSP_NONCE` injection token. Use this approach if you have access to the nonce at runtime and you want to be able to cache the `index.html`.

```ts
import {CSP_NONCE} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';
import {AppComponent} from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    {
      provide: CSP_NONCE,
      useValue: globalThis.myRandomNonceValue,
    },
  ],
});
```
Always ensure that the nonces you provide are <strong>unique per request</strong> and that they are not predictable or guessable.
If an attacker can predict future nonces, they can circumvent the protections offered by CSP.

Generating a nonce at the origin server is generally discouraged when using a CDN, as responses are frequently cached. If the server generates a nonce and the CDN caches that HTML response, every subsequent visitor receives the same "unique" value, allowing an attacker to discover the static value and bypass CSP protections.

To maintain the "one-time-use" integrity of a nonce, it should ideally be generated at the Edge layer (e.g., CDN) just before the content is delivered to the user.
NOTE: If you want to [inline the critical CSS](/tools/cli/build#critical-css-inlining) of your application, you can not use the `CSP_NONCE` token, and should prefer the `security.autoCsp` option in the [workspace configuration](reference/configs/workspace-config#extra-build-and-test-options) or set the `ngCspNonce` attribute on the root application element.

If you cannot generate nonces in your project, you can allow inline styles by adding `'unsafe-inline'` to the `style-src` section of the CSP header.

| Sections                                         | Details                                                                                                                                                                                                                                                                                                                                                  |
| :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default-src 'self';`                            | Allows the page to load all its required resources from the same origin.                                                                                                                                                                                                                                                                                 |
| `style-src 'self' 'nonce-randomNonceGoesHere';`  | Allows the page to load global styles from the same origin $`'self'`$ and styles inserted by Angular with the `nonce-randomNonceGoesHere`.                                                                                                                                                                                                             |
| `script-src 'self' 'nonce-randomNonceGoesHere';` | Allows the page to load JavaScript from the same origin $`'self'`$ and scripts inserted by the Angular CLI with the `nonce-randomNonceGoesHere`. Required only when you enable critical CSS inlining or subresource integrity (which injects an import map to validate dynamically imported chunks), both of which add inline scripts to `index.html`. |

Angular itself requires only these settings to function correctly.
As your project grows, you may need to expand your CSP settings to accommodate extra features specific to your application.
-->

콘텐츠 보안 정책(Content Security Policy, CSP)은 XSS를 방지하는 심층 방어 기법입니다.
CSP를 활성화하려면 웹 서버가 적절한 `Content-Security-Policy` HTTP 헤더를 반환하도록 설정하세요.
콘텐츠 보안 정책에 대한 자세한 내용은 Google Developers 웹사이트의 [Web Fundamentals 가이드](https://developers.google.com/web/fundamentals/security/csp)를 참고하세요.

새로 생성한 Angular 애플리케이션에 필요한 최소 정책은 다음과 같습니다.

```txt
default-src 'self'; style-src 'self' 'nonce-randomNonceGoesHere'; script-src 'self' 'nonce-randomNonceGoesHere';
```

Angular 애플리케이션을 제공할 때 서버는 요청마다 무작위로 생성한 nonce를 HTTP 헤더에 포함해야 합니다.
프레임워크가 `<style>` 엘리먼트를 렌더링할 수 있도록 이 nonce를 Angular에 제공해야 합니다.
다음 방법 중 하나로 Angular에 nonce를 설정할 수 있습니다.

1. 최상위 애플리케이션 엘리먼트에 `<app ngCspNonce="randomNonceGoesHere"></app>`와 같이 `ngCspNonce` 어트리뷰트를 지정합니다.
   응답을 구성할 때 헤더와 `index.html` 모두에 nonce를 추가할 수 있는 서버 측 템플릿 기능을 사용할 수 있다면 이 방식을 사용하세요.
1. `CSP_NONCE` 주입 토큰으로 nonce를 제공합니다.
   런타임에 nonce에 접근할 수 있고 `index.html`을 캐시하려는 경우 이 방식을 사용하세요.

```ts
import {CSP_NONCE} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';
import {AppComponent} from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    {
      provide: CSP_NONCE,
      useValue: globalThis.myRandomNonceValue,
    },
  ],
});
```
제공하는 nonce가 항상 <strong>요청마다 고유</strong>하고, 예측하거나 추측할 수 없는 값인지 확인하세요.
공격자가 앞으로 사용될 nonce를 예측할 수 있으면 CSP가 제공하는 보호를 우회할 수 있습니다.

CDN을 사용하는 경우 응답이 자주 캐시되므로 일반적으로 원본 서버에서 nonce를 생성하는 것은 권장하지 않습니다.
서버가 nonce를 생성하고 CDN이 해당 HTML 응답을 캐시하면 이후의 모든 방문자가 같은 "고유한" 값을 받게 됩니다.
그러면 공격자가 이 고정된 값을 알아내 CSP 보호를 우회할 수 있습니다.

nonce의 "일회용" 속성을 유지하려면 콘텐츠가 사용자에게 전달되기 직전에 엣지 계층(예: CDN)에서 생성하는 것이 이상적입니다.
참고: 애플리케이션의 [핵심 CSS를 인라인으로 포함](/tools/cli/build#critical-css-inlining)하려면 `CSP_NONCE` 토큰을 사용할 수 없습니다.
이 경우 [워크스페이스 설정](reference/configs/workspace-config#extra-build-and-test-options)의 `security.autoCsp` 옵션을 사용하거나 최상위 애플리케이션 엘리먼트에 `ngCspNonce` 어트리뷰트를 설정하세요.

프로젝트에서 nonce를 생성할 수 없다면 CSP 헤더의 `style-src` 항목에 `'unsafe-inline'`을 추가해 인라인 스타일을 허용할 수 있습니다.

| 항목                                             | 설명                                                                                                                                                                                                                                                                                                                                                              |
| :----------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default-src 'self';`                            | 페이지가 필요한 모든 리소스를 동일 출처에서 불러올 수 있도록 허용합니다.                                                                                                                                                                                                                                                                                          |
| `style-src 'self' 'nonce-randomNonceGoesHere';`  | 페이지가 동일 출처(`'self'`)의 전역 스타일과 Angular가 `nonce-randomNonceGoesHere`를 사용해 삽입한 스타일을 불러올 수 있도록 허용합니다.                                                                                                                                                                                                                          |
| `script-src 'self' 'nonce-randomNonceGoesHere';` | 페이지가 동일 출처(`'self'`)의 JavaScript와 Angular CLI가 `nonce-randomNonceGoesHere`를 사용해 삽입한 스크립트를 불러올 수 있도록 허용합니다. 중요 CSS 인라인 처리 또는 하위 리소스 무결성을 활성화한 경우에만 필요합니다. 하위 리소스 무결성은 동적으로 불러오는 청크를 검증하는 임포트 맵을 삽입하며, 두 기능 모두 `index.html`에 인라인 스크립트를 추가합니다. |

Angular 자체는 이 설정만 있으면 정상적으로 동작합니다.
프로젝트가 커지면 애플리케이션에 특화된 추가 기능을 지원하도록 CSP 설정을 확장해야 할 수 있습니다.

<!--
#### Static hosting without per-response nonces

If your hosting environment or CDN can replace a placeholder token in cached HTML at the edge (for example, using SSI, ESI, or an edge function), you can build `index.html` with a placeholder in `ngCspNonce` (such as `<app ngCspNonce="__CSP_NONCE__"></app>`) and replace it with a unique nonce on each response.

If you deploy your application to a static host that serves `index.html` unchanged without edge transformation, do not hard-code a static nonce. Instead, use one of the following approaches:
-->

#### 응답마다 nonce를 만들 수 없는 정적 호스팅

호스팅 환경이나 CDN이 SSI, ESI, 엣지 함수 등으로 캐시된 HTML의 플레이스홀더를 교체할 수 있다면, `ngCspNonce`에 플레이스홀더를 넣어 `index.html`을 빌드할 수 있습니다. 예를 들어 `<app ngCspNonce="__CSP_NONCE__"></app>`을 사용하고, 응답마다 고유한 nonce로 교체합니다.

엣지에서 변환하지 않고 `index.html`을 그대로 제공하는 정적 호스트에 배포한다면 고정된 nonce를 하드코딩하지 마세요. 대신 다음 방법 중 하나를 사용하세요.

<!--
##### Hash inline scripts with `autoCsp`

Set the `security.autoCsp` option to `true` in the [workspace configuration](reference/configs/workspace-config#extra-build-and-test-options).
At build time, the Angular CLI computes a hash of every inline script in `index.html`, including the scripts added by critical CSS inlining and subresource integrity.
The CLI replaces the `<script src>` elements with a hashed loader script and adds a `<meta>` tag at the start of `<head>`:

```txt
script-src 'strict-dynamic' 'sha256-...' https: 'unsafe-inline'; object-src 'none'; base-uri 'self';
```

Because hashes depend only on the content of the scripts, `index.html` remains valid for every visitor and can be cached.
Browsers that support hashes and `'strict-dynamic'` ignore the `https:` and `'unsafe-inline'` fallback sources.

The policy generated by `autoCsp` has the following limitations:

- It only covers scripts. You must configure `style-src` separately.
- Browsers ignore some directives, such as `frame-ancestors`, `report-uri`, and `sandbox`, when they appear in a `<meta>` tag. Send these directives in a `Content-Security-Policy` HTTP header.
- When a page has multiple policies, the browser enforces all of them. If you also send a CSP header, omit both `script-src` and `default-src` from the header so they do not block the hashed inline scripts.
- You cannot use `autoCsp` with server-side rendering.
-->

##### `autoCsp`로 인라인 스크립트 해시 생성하기

[워크스페이스 설정](reference/configs/workspace-config#extra-build-and-test-options)에서 `security.autoCsp` 옵션을 `true`로 설정하세요.
Angular CLI는 빌드 시 `index.html`의 모든 인라인 스크립트에 대해 해시를 계산합니다. 중요 CSS 인라인 처리와 하위 리소스 무결성 기능이 추가한 스크립트도 포함합니다.
CLI는 `<script src>` 엘리먼트를 해시가 있는 로더 스크립트로 교체하고, `<head>` 시작 부분에 다음 정책을 담은 `<meta>` 태그를 추가합니다.

```txt
script-src 'strict-dynamic' 'sha256-...' https: 'unsafe-inline'; object-src 'none'; base-uri 'self';
```

해시는 스크립트 내용에만 의존하므로 `index.html`은 모든 방문자에게 유효하며 캐시할 수 있습니다.
해시와 `'strict-dynamic'`을 지원하는 브라우저는 대체 소스인 `https:`와 `'unsafe-inline'`을 무시합니다.

`autoCsp`가 생성하는 정책에는 다음과 같은 제약이 있습니다.

- 스크립트에만 적용됩니다. `style-src`는 별도로 설정해야 합니다.
- 브라우저는 `<meta>` 태그에 포함된 `frame-ancestors`, `report-uri`, `sandbox` 등의 일부 지시자를 무시합니다. 이러한 지시자는 `Content-Security-Policy` HTTP 헤더로 전달하세요.
- 페이지에 여러 정책이 있으면 브라우저는 모든 정책을 적용합니다. CSP 헤더도 함께 전송한다면 해시가 있는 인라인 스크립트를 차단하지 않도록 헤더에서 `script-src`와 `default-src`를 모두 생략하세요.
- `autoCsp`는 서버 사이드 렌더링과 함께 사용할 수 없습니다.

<!--
##### Avoid inline scripts

The Angular CLI only adds inline scripts to `index.html` for critical CSS inlining and subresource integrity (which emits an import map to carry integrity metadata for dynamic module imports).
If you set `optimization.styles.inlineCritical` to `false` and leave `subresourceIntegrity` disabled, `index.html` does not contain inline scripts. You can then configure a `Content-Security-Policy` header with `script-src 'self'`.

NOTE: Disabling critical CSS inlining can slow down the initial render of your application, and disabling subresource integrity removes script integrity checks.
-->

##### 인라인 스크립트 사용하지 않기

Angular CLI는 중요 CSS 인라인 처리와 하위 리소스 무결성을 위해서만 `index.html`에 인라인 스크립트를 추가합니다. 하위 리소스 무결성 기능은 동적 모듈 임포트의 무결성 메타데이터를 전달하는 임포트 맵을 생성합니다.
`optimization.styles.inlineCritical`을 `false`로 설정하고 `subresourceIntegrity`를 비활성화한 상태로 유지하면 `index.html`에 인라인 스크립트가 포함되지 않습니다. 이때 `script-src 'self'`를 사용하는 `Content-Security-Policy` 헤더를 설정할 수 있습니다.

참고: 중요 CSS 인라인 처리를 비활성화하면 애플리케이션의 초기 렌더링이 느려질 수 있으며, 하위 리소스 무결성을 비활성화하면 스크립트 무결성 검사가 제거됩니다.

<!--
##### Configure styles for static hosting

Angular inserts `<style>` elements for component styles at runtime, and critical CSS inlining adds a `<style>` element to `index.html`.
Neither `autoCsp` nor disabling inline scripts covers these styles. Without a per-response nonce, allow them by adding `'unsafe-inline'` to `style-src`.
For example, if your build avoids inline scripts, configure your host to send the following header:

```txt
default-src 'self'; style-src 'self' 'unsafe-inline';
```

If you use `autoCsp`, send `style-src 'self' 'unsafe-inline'` in the HTTP header without `default-src` or `script-src`.

Your application code and third-party libraries might require additional directives in both cases.
-->

##### 정적 호스팅에 맞게 스타일 설정하기

Angular는 실행 중에 컴포넌트 스타일용 `<style>` 엘리먼트를 삽입하며, 중요 CSS 인라인 처리는 `index.html`에 `<style>` 엘리먼트를 추가합니다.
`autoCsp`를 사용하거나 인라인 스크립트를 비활성화해도 이 스타일에는 적용되지 않습니다. 응답별 nonce가 없다면 `style-src`에 `'unsafe-inline'`을 추가해 허용하세요.
예를 들어 인라인 스크립트를 사용하지 않는 빌드라면 호스트가 다음 헤더를 보내도록 설정하세요.

```txt
default-src 'self'; style-src 'self' 'unsafe-inline';
```

`autoCsp`를 사용한다면 HTTP 헤더에 `default-src`나 `script-src` 없이 `style-src 'self' 'unsafe-inline'`을 보내세요.

두 경우 모두 애플리케이션 코드와 서드 파티 라이브러리에 따라 추가 지시자가 필요할 수 있습니다.

### Trusted Types 강제 적용하기

<!--
It is recommended that you use [Trusted Types](https://w3c.github.io/trusted-types/dist/spec/) as a way to help secure your applications from cross-site scripting attacks.
Trusted Types is a [web platform](https://en.wikipedia.org/wiki/Web_platform) feature that can help you prevent cross-site scripting attacks by enforcing safer coding practices.
Trusted Types can also help simplify the auditing of application code.
Trusted Types might not yet be available in all browsers your application targets.
In the case your Trusted-Types-enabled application runs in a browser that doesn't support Trusted Types, the features of the application are preserved. Your application is guarded against XSS by way of Angular's DomSanitizer.
See [caniuse.com/trusted-types](https://caniuse.com/trusted-types) for the current browser support.
To enforce Trusted Types for your application, you must configure your application's web server to emit HTTP headers with one of the following Angular policies:

| Policies                 | Detail                                                                                                                                                                                                                                                                                     |
| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `angular`                | This policy is used in security-reviewed code that is internal to Angular, and is required for Angular to function when Trusted Types are enforced. Any inline template values or content sanitized by Angular is treated as safe by this policy.                                          |
| `angular#bundler`        | This policy is used by the Angular CLI bundler when creating lazy chunk files.                                                                                                                                                                                                             |
| `angular#unsafe-bypass`  | This policy is used for applications that use any of the methods in Angular's [DomSanitizer](api/platform-browser/DomSanitizer) that bypass security, such as `bypassSecurityTrustHtml`. Any application that uses these methods must enable this policy.                                  |
| `angular#unsafe-jit`     | This policy is used by the [Just-In-Time (JIT) compiler](api/core/Compiler). You must enable this policy if your application interacts directly with the JIT compiler or is running in JIT mode using the [platform browser dynamic](api/platform-browser-dynamic/platformBrowserDynamic). |
| `angular#unsafe-upgrade` | This policy is used by the [@angular/upgrade](api/upgrade/static/UpgradeModule) package. You must enable this policy if your application is an AngularJS hybrid.                                                                                                                           |

You should configure the HTTP headers for Trusted Types in the following locations:

- Production serving infrastructure
- Angular CLI $`ng serve`$, using the `headers` property in the `angular.json` file, for local development and end-to-end testing
- Karma $`ng test`$, using the `customHeaders` property in the `karma.config.js` file, for unit testing

The following is an example of a header specifically configured for Trusted Types and Angular:

```html
Content-Security-Policy: trusted-types angular; require-trusted-types-for 'script';
```

An example of a header specifically configured for Trusted Types and Angular applications that use any of Angular's methods in [DomSanitizer](api/platform-browser/DomSanitizer) that bypasses security:

```html
Content-Security-Policy: trusted-types angular angular#unsafe-bypass; require-trusted-types-for
'script';
```

The following is an example of a header specifically configured for Trusted Types and Angular applications using JIT:

```html
Content-Security-Policy: trusted-types angular angular#unsafe-jit; require-trusted-types-for
'script';
```

The following is an example of a header specifically configured for Trusted Types and Angular applications that use lazy loading of modules:

```html
Content-Security-Policy: trusted-types angular angular#bundler; require-trusted-types-for 'script';
```
To learn more about troubleshooting Trusted Type configurations, the following resource might be helpful:

[Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types](https://web.dev/trusted-types/#how-to-use-trusted-types)
-->

크로스 사이트 스크립팅 공격으로부터 애플리케이션을 보호하는 방법으로 [Trusted Types](https://w3c.github.io/trusted-types/dist/spec/) 사용을 권장합니다.
Trusted Types는 더 안전한 코딩 방식을 강제해 크로스 사이트 스크립팅 공격을 방지하는 데 도움이 되는 [웹 플랫폼](https://en.wikipedia.org/wiki/Web_platform) 기능입니다.
Trusted Types를 사용하면 애플리케이션 코드의 보안 점검도 간단해질 수 있습니다.
애플리케이션이 지원하는 모든 브라우저에서 Trusted Types를 사용할 수 있는 것은 아닐 수 있습니다.
Trusted Types를 활성화한 애플리케이션을 이를 지원하지 않는 브라우저에서 실행해도 애플리케이션 기능은 유지됩니다.
이 경우 Angular의 DomSanitizer가 XSS로부터 애플리케이션을 보호합니다.
현재 브라우저 지원 현황은 [caniuse.com/trusted-types](https://caniuse.com/trusted-types)를 참고하세요.
애플리케이션에 Trusted Types를 강제 적용하려면 웹 서버가 다음 Angular 정책 중 필요한 정책을 포함한 HTTP 헤더를 보내도록 설정해야 합니다.

| 정책                     | 설명                                                                                                                                                                                                                                                                    |
| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `angular`                | 보안 검토를 마친 Angular 내부 코드에서 사용하는 정책이며, Trusted Types가 강제 적용될 때 Angular가 동작하는 데 필요합니다. 이 정책은 모든 인라인 템플릿 값과 Angular가 정제한 내용을 안전하다고 취급합니다.                                                             |
| `angular#bundler`        | Angular CLI 번들러가 지연 로딩 청크 파일을 생성할 때 사용하는 정책입니다.                                                                                                                                                                                               |
| `angular#unsafe-bypass`  | Angular의 [DomSanitizer](api/platform-browser/DomSanitizer)에서 `bypassSecurityTrustHtml`처럼 보안 검사를 우회하는 메서드를 사용하는 애플리케이션에 적용하는 정책입니다. 이러한 메서드를 사용하는 모든 애플리케이션은 이 정책을 활성화해야 합니다.                      |
| `angular#unsafe-jit`     | [JIT(Just-In-Time) 컴파일러](api/core/Compiler)가 사용하는 정책입니다. 애플리케이션이 JIT 컴파일러와 직접 상호작용하거나 [platform browser dynamic](api/platform-browser-dynamic/platformBrowserDynamic)을 사용해 JIT 모드로 실행되는 경우 이 정책을 활성화해야 합니다. |
| `angular#unsafe-upgrade` | [@angular/upgrade](api/upgrade/static/UpgradeModule) 패키지가 사용하는 정책입니다. AngularJS 하이브리드 애플리케이션이라면 이 정책을 활성화해야 합니다.                                                                                                                 |

다음 위치에서 Trusted Types용 HTTP 헤더를 설정해야 합니다.

- 프로덕션 서비스 인프라
- 로컬 개발과 엔드 투 엔드 테스트를 위한 Angular CLI(`ng serve`): `angular.json` 파일의 `headers` 프로퍼티 사용
- 단위 테스트를 위한 Karma(`ng test`): `karma.config.js` 파일의 `customHeaders` 프로퍼티 사용

다음은 Trusted Types와 Angular에 맞게 설정한 헤더의 예제입니다.

```html
Content-Security-Policy: trusted-types angular; require-trusted-types-for 'script';
```

다음은 [DomSanitizer](api/platform-browser/DomSanitizer)에서 보안 검사를 우회하는 Angular 메서드를 사용하는 애플리케이션에 Trusted Types를 적용한 헤더의 예제입니다.

```html
Content-Security-Policy: trusted-types angular angular#unsafe-bypass; require-trusted-types-for
'script';
```

다음은 JIT를 사용하는 Angular 애플리케이션에 Trusted Types를 적용한 헤더의 예제입니다.

```html
Content-Security-Policy: trusted-types angular angular#unsafe-jit; require-trusted-types-for
'script';
```

다음은 모듈 지연 로딩을 사용하는 Angular 애플리케이션에 Trusted Types를 적용한 헤더의 예제입니다.

```html
Content-Security-Policy: trusted-types angular angular#bundler; require-trusted-types-for 'script';
```
Trusted Types 설정 문제 해결에 대한 자세한 내용은 다음 자료가 도움이 될 수 있습니다.

[Trusted Types로 DOM 기반 크로스 사이트 스크립팅 취약점 방지하기](https://web.dev/trusted-types/#how-to-use-trusted-types)

### AOT 템플릿 컴파일러 사용하기

<!--
The AOT template compiler prevents a whole class of vulnerabilities called template injection, and greatly improves application performance.
The AOT template compiler is the default compiler used by Angular CLI applications, and you should use it in all production deployments.

An alternative to the AOT compiler is the JIT compiler which compiles templates to executable template code within the browser at runtime.
Angular trusts template code, so dynamically generating templates and compiling them, in particular templates containing user data, circumvents Angular's built-in protections. This is a security anti-pattern.
For information about dynamically constructing forms in a safe way, see the [Dynamic Forms](guide/forms/dynamic-forms) guide.
-->

AOT 템플릿 컴파일러는 템플릿 인젝션이라는 유형의 취약점을 방지하고 애플리케이션 성능을 크게 개선합니다.
AOT 템플릿 컴파일러는 Angular CLI 애플리케이션에서 사용하는 기본 컴파일러이며, 모든 프로덕션 배포에서 사용해야 합니다.

AOT 컴파일러 대신 사용할 수 있는 JIT 컴파일러는 런타임에 브라우저 안에서 템플릿을 실행 가능한 템플릿 코드로 컴파일합니다.
Angular는 템플릿 코드를 신뢰하므로 템플릿을 동적으로 생성해 컴파일하면 Angular의 내장 보호 기능을 우회하게 됩니다.
특히 사용자 데이터가 들어 있는 템플릿이 그렇습니다.
이는 보안 측면에서 피해야 하는 패턴입니다.
안전하게 폼을 동적으로 구성하는 방법은 [동적 폼](guide/forms/dynamic-forms) 가이드를 참고하세요.

### 서버 측 XSS 방어

서버에서 구성한 HTML은 인젝션 공격에 취약합니다.
Angular 애플리케이션에 템플릿 코드를 삽입하는 것은 실행 가능한 코드를 삽입하는 것과 같습니다.
공격자가 애플리케이션을 완전히 제어할 수 있게 됩니다.
이를 방지하려면 값을 자동으로 이스케이프하는 템플릿 언어를 사용해 서버의 XSS 취약점을 막으세요.
서버 측에서 템플릿 언어를 사용해 Angular 템플릿을 생성하지 마세요.
템플릿 인젝션 취약점을 만들 위험이 높습니다.

## HTTP 수준의 취약점

Angular에는 흔한 HTTP 취약점인 크로스 사이트 요청 위조(CSRF 또는 XSRF)와 크로스 사이트 스크립트 포함(XSSI)을 방지하는 데 도움이 되는 기능이 내장되어 있습니다.
두 취약점 모두 주로 서버 측에서 대응해야 하지만, Angular는 클라이언트 측 통합을 쉽게 하는 헬퍼를 제공합니다.

### 크로스 사이트 요청 위조

<!--
In a cross-site request forgery $CSRF or XSRF$, an attacker tricks the user into visiting a different web page $such as `evil.com`$ with malignant code. This web page secretly sends a malicious request to the application's web server $such as `example-bank.com`$.

Assume the user is logged into the application at `example-bank.com`.
The user opens an email and clicks a link to `evil.com`, which opens in a new tab.

The `evil.com` page immediately sends a malicious request to `example-bank.com`.
Perhaps it's a request to transfer money from the user's account to the attacker's account.
The browser automatically sends the `example-bank.com` cookies, including the authentication cookie, with this request.

If the `example-bank.com` server lacks XSRF protection, it can't tell the difference between a legitimate request from the application and the forged request from `evil.com`.

To prevent this, the application must ensure that a user request originates from the real application, not from a different site.
The server and client must cooperate to thwart this attack.

In a common anti-XSRF technique, the application server sends a randomly created authentication token in a cookie.
The client code reads the cookie and adds a custom request header with the token in all following requests.
The server compares the received cookie value to the request header value and rejects the request if the values are missing or don't match.

This technique is effective because all browsers implement the _same origin policy_.
Only code from the website on which cookies are set can read the cookies from that site and set custom headers on requests to that site.
That means only your application can read this cookie token and set the custom header.
The malicious code on `evil.com` can't.
-->

크로스 사이트 요청 위조(CSRF 또는 XSRF)에서는 공격자가 사용자를 속여 악성 코드가 있는 다른 웹 페이지(예: `evil.com`)에 방문하게 만듭니다.
이 웹 페이지는 애플리케이션의 웹 서버(예: `example-bank.com`)로 악성 요청을 몰래 보냅니다.

사용자가 `example-bank.com`의 애플리케이션에 로그인한 상태라고 가정해 봅시다.
사용자가 이메일을 열고 `evil.com` 링크를 클릭하면 새 탭에서 해당 사이트가 열립니다.

`evil.com` 페이지는 즉시 `example-bank.com`으로 악성 요청을 보냅니다.
사용자 계좌에서 공격자 계좌로 돈을 이체하는 요청일 수 있습니다.
브라우저는 인증 쿠키를 포함한 `example-bank.com` 쿠키를 이 요청에 자동으로 첨부합니다.

`example-bank.com` 서버에 XSRF 방어가 없다면 애플리케이션의 정상 요청과 `evil.com`이 위조한 요청을 구분할 수 없습니다.

이를 방지하려면 애플리케이션은 사용자의 요청이 다른 사이트가 아니라 실제 애플리케이션에서 시작되었음을 확인해야 합니다.
이 공격을 막으려면 서버와 클라이언트가 협력해야 합니다.

일반적인 XSRF 방어 기법에서는 애플리케이션 서버가 무작위로 생성한 인증 토큰을 쿠키에 담아 보냅니다.
클라이언트 코드는 쿠키를 읽고 이후의 모든 요청에 이 토큰이 담긴 커스텀 요청 헤더를 추가합니다.
서버는 받은 쿠키 값과 요청 헤더 값을 비교하고, 값이 없거나 서로 다르면 요청을 거부합니다.

이 기법이 효과적인 이유는 모든 브라우저가 _동일 출처 정책_ 을 구현하기 때문입니다.
쿠키가 설정된 웹사이트의 코드만 해당 사이트의 쿠키를 읽고 해당 사이트로 보내는 요청에 커스텀 헤더를 설정할 수 있습니다.
즉, 해당 애플리케이션만 이 쿠키 토큰을 읽고 커스텀 헤더를 설정할 수 있습니다.
`evil.com`의 악성 코드는 할 수 없습니다.

### `HttpClient`의 XSRF/CSRF 보안

<!--
`HttpClient` supports a [common mechanism](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Cookie-to-header_token) used to prevent XSRF attacks. When performing HTTP requests, an interceptor reads a token from a cookie, by default `XSRF-TOKEN`, and sets it as an HTTP header, `X-XSRF-TOKEN`. Because only code that runs on your domain could read the cookie, the backend can be certain that the HTTP request came from your client application and not an attacker.

By default, an interceptor sends this header on all mutating requests (such as `POST`) to relative and same origin URLs, but not on `GET` or `HEAD` requests.
CSRF protection is only needed for requests that can change state on the backend. By their nature, CSRF attacks cross domain boundaries, and the web's [same-origin policy](https://developer.mozilla.org/docs/Web/Security/Same-origin_policy) will prevent an attacking page from retrieving the results of authenticated `GET` requests.
To take advantage of this, your server needs to set a token in a JavaScript readable session cookie called `XSRF-TOKEN` on either the page load or the first GET request. On subsequent requests the server can verify that the cookie matches the `X-XSRF-TOKEN` HTTP header, and therefore be sure that only code running on your domain could have sent the request. The token must be unique for each user and must be verifiable by the server; this prevents the client from making up its own tokens. Set the token to a digest of your site's authentication cookie with a salt for added security.

To prevent collisions in environments where multiple Angular apps share the same domain or subdomain, give each application a unique cookie name.
  Your backend service must be configured to set the cookie for your page, and to verify that the header is present on all eligible requests. Failing to do so renders Angular's default protection ineffective.

-->

`HttpClient`는 XSRF 공격을 방지하는 [일반적인 방식](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Cookie-to-header_token)을 지원합니다.
HTTP 요청을 보낼 때 인터셉터는 기본적으로 `XSRF-TOKEN`이라는 쿠키에서 토큰을 읽어 `X-XSRF-TOKEN` HTTP 헤더에 설정합니다.
해당 도메인에서 실행되는 코드만 쿠키를 읽을 수 있으므로, 백엔드는 HTTP 요청이 공격자가 아니라 클라이언트 애플리케이션에서 왔다는 것을 확인할 수 있습니다.

기본적으로 인터셉터는 상대 URL과 동일 출처 URL로 보내는 모든 변경 요청(예: `POST`)에 이 헤더를 첨부하지만, `GET`이나 `HEAD` 요청에는 첨부하지 않습니다.
CSRF 방어는 백엔드 상태를 변경할 수 있는 요청에만 필요합니다.
CSRF 공격은 본질적으로 도메인 경계를 넘으며, 웹의 [동일 출처 정책](https://developer.mozilla.org/docs/Web/Security/Same-origin_policy)은 공격 페이지가 인증된 `GET` 요청의 결과를 읽지 못하도록 막습니다.
이 기능을 사용하려면 서버는 페이지를 불러올 때나 첫 번째 GET 요청에서 JavaScript가 읽을 수 있는 `XSRF-TOKEN`이라는 세션 쿠키에 토큰을 설정해야 합니다.
이후 요청에서는 서버가 쿠키와 `X-XSRF-TOKEN` HTTP 헤더가 일치하는지 확인해, 해당 도메인에서 실행되는 코드만 요청을 보낼 수 있었다는 것을 확인할 수 있습니다.
토큰은 사용자마다 고유해야 하며 서버에서 검증할 수 있어야 합니다.
그래야 클라이언트가 자체적으로 토큰을 만들어내지 못합니다.
보안을 강화하려면 사이트의 인증 쿠키에 솔트를 더해 만든 다이제스트를 토큰으로 사용하세요.

여러 Angular 앱이 같은 도메인이나 하위 도메인을 공유하는 환경에서 충돌하지 않도록 애플리케이션마다 고유한 쿠키 이름을 지정하세요.
  백엔드 서비스는 페이지의 쿠키를 설정하고 적용 대상인 모든 요청에 헤더가 존재하는지 확인하도록 구성해야 합니다.
  이렇게 하지 않으면 Angular의 기본 보호 기능은 효과가 없습니다.

### 커스텀 쿠키와 헤더 이름 설정하기

<!--
If your backend service uses different names for the XSRF token cookie or header, use `withXsrfConfiguration` to override the defaults.

Add it to the `provideHttpClient` call as follows:

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withXsrfConfiguration({
        cookieName: 'CUSTOM_XSRF_TOKEN',
        headerName: 'X-Custom-Xsrf-Header',
      }),
    ),
  ],
};
```
-->

백엔드 서비스가 XSRF 토큰 쿠키나 헤더에 다른 이름을 사용한다면 `withXsrfConfiguration`으로 기본값을 재정의하세요.

다음과 같이 `provideHttpClient` 호출에 추가하세요.

### XSRF 방어 비활성화하기

<!--
If the built-in XSRF protection mechanism doesn't work for your application, you can disable it using the `withNoXsrfProtection` feature:

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withNoXsrfProtection())],
};
```

For information about CSRF at the Open Web Application Security Project $OWASP$, see [Cross-Site Request Forgery (CSRF)](https://owasp.org/www-community/attacks/csrf) and [Cross-Site Request Forgery (CSRF) Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html).
The Stanford University paper [Robust Defenses for Cross-Site Request Forgery](https://seclab.stanford.edu/websec/csrf/csrf.pdf) is a rich source of detail.

See also Dave Smith's [talk on XSRF at AngularConnect 2016](https://www.youtube.com/watch?v=9inczw6qtpY 'Cross Site Request Funkery Securing Your Angular Apps From Evil Doers').
-->

내장 XSRF 방어 방식이 애플리케이션에 맞지 않는다면 `withNoXsrfProtection` 기능으로 비활성화할 수 있습니다.

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withNoXsrfProtection())],
};
```

Open Web Application Security Project(OWASP)의 CSRF 자료는 [크로스 사이트 요청 위조(CSRF)](https://owasp.org/www-community/attacks/csrf)와 [크로스 사이트 요청 위조(CSRF) 방지 치트 시트](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)를 참고하세요.
스탠퍼드 대학교의 논문 [크로스 사이트 요청 위조에 대한 강력한 방어](https://seclab.stanford.edu/websec/csrf/csrf.pdf)에도 상세한 정보가 담겨 있습니다.

Dave Smith의 [AngularConnect 2016 XSRF 발표](https://www.youtube.com/watch?v=9inczw6qtpY '크로스 사이트 요청 공격: 악의적인 공격자로부터 Angular 앱 보호하기')도 참고하세요.

### 크로스 사이트 스크립트 포함(XSSI)

<!--
Cross-site script inclusion, also known as JSON vulnerability, can allow an attacker's website to read data from a JSON API.
The attack works on older browsers by overriding built-in JavaScript object constructors, and then including an API URL using a `<script>` tag.

This attack is only successful if the returned JSON is executable as JavaScript.
Servers can prevent an attack by prefixing all JSON responses to make them non-executable, by convention, using the well-known string `")]}',\n"`.

Angular's `HttpClient` library recognizes this convention and automatically strips the string `")]}',\n"` from all responses before further parsing.

For more information, see the XSSI section of this [Google web security blog post](https://security.googleblog.com/2011/05/website-security-for-webmasters.html).
-->

JSON 취약점이라고도 하는 크로스 사이트 스크립트 포함은 공격자의 웹사이트가 JSON API에서 데이터를 읽을 수 있게 합니다.
이 공격은 오래된 브라우저에서 JavaScript 내장 객체 생성자를 재정의한 다음 `<script>` 태그로 API URL을 포함하는 방식으로 동작합니다.

이 공격은 반환된 JSON을 JavaScript로 실행할 수 있을 때만 성공합니다.
서버는 모든 JSON 응답 앞에 접두사를 붙여 실행할 수 없게 만들어 공격을 방지할 수 있습니다.
관례적으로 잘 알려진 문자열인 `")]}',\n"`을 사용합니다.

Angular의 `HttpClient` 라이브러리는 이 관례를 인식하고, 모든 응답에서 `")]}',\n"` 문자열을 자동으로 제거한 다음 파싱을 진행합니다.

자세한 내용은 이 [Google 웹 보안 블로그 글](https://security.googleblog.com/2011/05/website-security-for-webmasters.html)의 XSSI 섹션을 참고하세요.

## 서버 측 요청 위조(SSRF) 방지하기

<!--
Angular includes strict validation for `Host`, `Forwarded`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Forwarded-Prefix`, and `X-Forwarded-Port` headers in the request handling pipeline to prevent header-based [Server-Side Request Forgery (SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF).

The validation rules are:

- `Host`, `X-Forwarded-Host`, and the `host` parameter of the `Forwarded` header are validated against a strict allowlist and cannot contain path separators.
- `X-Forwarded-Port` header must be numeric.
- `X-Forwarded-Proto` header and the `proto` parameter of the `Forwarded` header must be `http` or `https`.
- `X-Forwarded-Prefix` header must start with `/` and contain only alphanumeric characters, hyphens, and underscores, separated by single slashes.
- By default, the `Forwarded` header and all `X-Forwarded-*` headers are treated as untrusted and are removed from the request. To retain them, they must be explicitly allowed by configuring `trustProxyHeaders`.

Invalid headers trigger an error log, and unallowed proxy headers are removed from the request. Requests with unrecognized hostnames will result in a `400 Bad Request`.

NOTE: Most cloud providers and CDN providers perform automatic validation of these headers before a request ever reaches the application origin. This inherent filtering significantly reduces the practical attack surface.
-->

Angular는 헤더 기반 [서버 측 요청 위조(SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF)를 방지하기 위해 요청 처리 과정에서 `Host`, `Forwarded`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Forwarded-Prefix`, `X-Forwarded-Port` 헤더를 엄격하게 검증합니다.

검증 규칙은 다음과 같습니다.

- `Host`, `X-Forwarded-Host` 헤더와 `Forwarded` 헤더의 `host` 파라미터는 엄격한 허용 목록으로 검증하며, 경로 구분자를 포함할 수 없습니다.
- `X-Forwarded-Port` 헤더는 숫자여야 합니다.
- `X-Forwarded-Proto` 헤더와 `Forwarded` 헤더의 `proto` 파라미터는 `http` 또는 `https`여야 합니다.
- `X-Forwarded-Prefix` 헤더는 `/`로 시작해야 하며, 단일 슬래시로 구분된 영문자·숫자·하이픈·밑줄만 포함할 수 있습니다.
- 기본적으로 `Forwarded` 헤더와 모든 `X-Forwarded-*` 헤더는 신뢰할 수 없다고 취급되어 요청에서 제거됩니다.
  유지하려면 `trustProxyHeaders` 설정으로 명시적으로 허용해야 합니다.

유효하지 않은 헤더는 오류 로그를 발생시키며, 허용되지 않은 프록시 헤더는 요청에서 제거됩니다.
인식할 수 없는 호스트 이름이 있는 요청에는 `400 Bad Request`가 반환됩니다.

참고: 대부분의 클라우드 제공업체와 CDN 제공업체는 요청이 애플리케이션 원본 서버에 도착하기 전에 이 헤더들을 자동으로 검증합니다.
이러한 기본 필터링은 실제 공격 가능 영역을 크게 줄입니다.

### 허용할 호스트 설정하기

<!--
To allow specific hostnames, you need to add them to the allowlist. This is critical for ensuring your application works correctly and securely when deployed. The patterns support wildcards for flexible hostname matching.

You can configure the `allowedHosts` option in your `angular.json`:

```json
{hideCopy}
{
  // ...
  "projects": {
    "your-project-name": {
      // ...
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "security": {
              "allowedHosts": [
                "example.com",
                "*.example.com" // allows all subdomains of example.com
              ]
            }
            // ... other options
          }
        }
      }
    }
  }
}
```

You can also configure `allowedHosts` when initializing the application engine:

```typescript
const appEngine = new AngularAppEngine({
  allowedHosts: ['example.com', '*.trusted-example.com'],
});

const nodeAppEngine = new AngularNodeAppEngine({
  allowedHosts: ['example.com', '*.trusted-example.com'],
});
```

For the Node.js variant `AngularNodeAppEngine`, you can also provide `NG_ALLOWED_HOSTS` (comma-separated list) environment variable for authorizing hosts.

```bash
{hideDollar}
export NG_ALLOWED_HOSTS="example.com,*.trusted-example.com"
```

IMPORTANT: You can use `*` as a value in `allowedHosts` to allow all hostnames, though this is generally discouraged and presents a security risk. Accepting any host header can expose your application to host header injection and [Server-Side Request Forgery (SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF) attacks. This configuration should only be used when validation for `Host` and `X-Forwarded-Host` headers is performed in another layer, such as a load balancer or reverse proxy. For better security, we recommend using an explicit list of allowed hosts whenever possible. See [GHSA-x288-3778-4hhx](https://github.com/angular/angular-cli/security/advisories/GHSA-x288-3778-4hhx) for more details.
-->

특정 호스트 이름을 허용하려면 허용 목록에 추가해야 합니다.
이는 배포된 애플리케이션이 올바르고 안전하게 동작하는 데 필수적입니다.
패턴에서 와일드카드를 지원하므로 호스트 이름을 유연하게 일치시킬 수 있습니다.

`angular.json`에서 `allowedHosts` 옵션을 설정할 수 있습니다.

```json
{hideCopy}
{
  // ...
  "projects": {
    "your-project-name": {
      // ...
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "security": {
              "allowedHosts": [
                "example.com",
                "*.example.com" // example.com의 모든 하위 도메인을 허용합니다.
              ]
            }
            // ... 다른 옵션
          }
        }
      }
    }
  }
}
```

애플리케이션 엔진을 초기화할 때도 `allowedHosts`를 설정할 수 있습니다.

```typescript
const appEngine = new AngularAppEngine({
  allowedHosts: ['example.com', '*.trusted-example.com'],
});

const nodeAppEngine = new AngularNodeAppEngine({
  allowedHosts: ['example.com', '*.trusted-example.com'],
});
```

Node.js용 `AngularNodeAppEngine`에서는 `NG_ALLOWED_HOSTS` 환경 변수(쉼표로 구분한 목록)로 호스트를 허용할 수도 있습니다.

```bash
{hideDollar}
export NG_ALLOWED_HOSTS="example.com,*.trusted-example.com"
```

중요: `allowedHosts` 값으로 `*`를 사용하면 모든 호스트 이름을 허용할 수 있지만, 일반적으로 권장하지 않으며 보안 위험이 있습니다.
임의의 Host 헤더를 허용하면 애플리케이션이 Host 헤더 인젝션과 [서버 측 요청 위조(SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF) 공격에 노출될 수 있습니다.
이 설정은 로드 밸런서나 리버스 프록시 등 다른 계층에서 `Host`와 `X-Forwarded-Host` 헤더를 검증하는 경우에만 사용해야 합니다.
보안을 강화하려면 가능한 한 허용할 호스트 목록을 명시하는 것을 권장합니다.
자세한 내용은 [GHSA-x288-3778-4hhx](https://github.com/angular/angular-cli/security/advisories/GHSA-x288-3778-4hhx)를 참고하세요.

### 신뢰할 프록시 헤더 설정하기

<!--
By default, Angular ignores the standard `Forwarded` header and all `X-Forwarded-*` headers. If your application is behind a trusted reverse proxy (like a load balancer) that sets these headers, you can configure Angular to trust them.

If the `Forwarded` header is trusted, its `host` and `proto` parameters are extracted and take precedence over the corresponding `x-forwarded-host` and `x-forwarded-proto` headers.

You can configure `trustProxyHeaders` when initializing the application engine:

```typescript
const appEngine = new AngularAppEngine({
  trustProxyHeaders: ['forwarded'], // Trust the standard Forwarded header
});

const appEngine = new AngularAppEngine({
  trustProxyHeaders: ['x-forwarded-host', 'x-forwarded-proto'], // Trust non-standard headers
});

const nodeAppEngine = new AngularNodeAppEngine({
  trustProxyHeaders: true, // Trust standard Forwarded and all X-Forwarded-* headers
});
```

For the Node.js variant `AngularNodeAppEngine`, you can also provide the `NG_TRUST_PROXY_HEADERS` environment variable (with a comma-separated list of headers as a value) to allow the usage of these headers.

```bash
{hideDollar}
export NG_TRUST_PROXY_HEADERS="X-FORWARDED-HOST,X-FORWARDED-PREFIX"
```

IMPORTANT: Only enable `trustProxyHeaders` if your application is behind a trusted proxy that strictly validates or overrides these headers. Otherwise, attackers can spoof these headers to cause [Server-Side Request Forgery (SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF) attacks.
-->

Angular는 기본적으로 표준 `Forwarded` 헤더와 모든 `X-Forwarded-*` 헤더를 무시합니다.
애플리케이션 앞에 이 헤더들을 설정하는 신뢰할 수 있는 리버스 프록시(예: 로드 밸런서)가 있다면, Angular가 해당 헤더를 신뢰하도록 설정할 수 있습니다.

`Forwarded` 헤더를 신뢰하면 이 헤더에서 추출한 `host`와 `proto` 파라미터가 각각 `x-forwarded-host`, `x-forwarded-proto` 헤더보다 우선합니다.

애플리케이션 엔진을 초기화할 때 `trustProxyHeaders`를 설정할 수 있습니다.

```typescript
const appEngine = new AngularAppEngine({
  trustProxyHeaders: ['forwarded'], // 표준 Forwarded 헤더를 신뢰합니다.
});

const appEngine = new AngularAppEngine({
  trustProxyHeaders: ['x-forwarded-host', 'x-forwarded-proto'], // 비표준 헤더를 신뢰합니다.
});

const nodeAppEngine = new AngularNodeAppEngine({
  trustProxyHeaders: true, // 표준 Forwarded와 모든 X-Forwarded-* 헤더를 신뢰합니다.
});
```

Node.js용 `AngularNodeAppEngine`에서는 `NG_TRUST_PROXY_HEADERS` 환경 변수에 쉼표로 구분한 헤더 목록을 지정해 해당 헤더의 사용을 허용할 수도 있습니다.

```bash
{hideDollar}
export NG_TRUST_PROXY_HEADERS="X-FORWARDED-HOST,X-FORWARDED-PREFIX"
```

중요: 애플리케이션 앞의 신뢰할 수 있는 프록시가 이 헤더들을 엄격하게 검증하거나 덮어쓰는 경우에만 `trustProxyHeaders`를 활성화하세요.
그렇지 않으면 공격자가 헤더를 위조해 [서버 측 요청 위조(SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF) 공격을 일으킬 수 있습니다.

## Angular 애플리케이션 보안 점검하기

Angular 애플리케이션은 일반적인 웹 애플리케이션과 같은 보안 원칙을 따라야 하며, 같은 기준으로 보안 점검을 받아야 합니다.
[_bypassSecurityTrust_](#trusting-safe-values) 메서드처럼 보안 검토에서 확인해야 하는 Angular 전용 API는 문서에 보안상 민감한 API로 표시되어 있습니다.