Googleの専門チームによって管理されているAngularは、開発ワークフローを簡素化および効率化するための幅広いツール、API、ライブラリのスイートを提供します。Angularは、チームの規模とコードベースの規模の両方に合わせて拡張できる、高速で信頼性の高いアプリケーションを構築するための堅実なプラットフォームを提供します。

Angularの使い方の概要

ブラウザで表示されるステップバイステップの手順

オンラインスターターを使ってAngularをすぐに始めましょう。または、ターミナルを使ってローカルでも開始できます。 ## オンラインで試す {#play-online} プロジェクトを設定せずに、ブラウザでAngularを試したい場合は、オンラインサンドボックスを使うことができます。 ## ローカルに新しいプロジェクトを設定する {#set-up-a-new-project-locally} 新しいプロジェクトを開始する場合、Gitなどのツールを使用するために、ローカルにプロジェクトを作成するのが一般的です。 ### 前提条件 {#prerequisites} - **Node.js** - [v20.19.0以降](/reference/versions) - **テキストエディタ** - [Visual Studio Code](https://code.visualstudio.com/)を推奨 - **ターミナル** - Angular CLIコマンドを実行するために必要 - **開発ツール** - 開発ワークフローを改善するために、[Angular Language Service](/tools/language-service) をおすすめします ### 手順 {#instructions} 以下のガイドは、ローカルにAngularプロジェクトを設定する手順を説明します。 #### Angular CLIをインストールする {#install-angular-cli} ターミナルを開き（[Visual Studio Code](https://code.visualstudio.com/)を使用している場合は、[統合ターミナル](https://code.visualstudio.com/docs/editor/integrated-terminal)を開くことができます）、次のコマンドを実行します。 ```shell // npm npm install -g @angular/cli ``` ```shell // pnpm pnpm install -g @angular/cli ``` ```shell // yarn yarn global add @angular/cli ``` ```shell // bun bun install -g @angular/cli ``` WindowsまたはUnixでこのコマンドを実行する際に問題が発生した場合は、[CLIドキュメント](/tools/cli/setup-local#install-the-angular-cli)を参照してください。 #### 新しいプロジェクトを作成する {#create-a-new-project} ターミナルで、CLIコマンド`ng new`を実行し、目的のプロジェクト名を入力します。次の例では、`my-first-angular-app`というプロジェクト名を使用します。 ```shell ng new ``` プロジェクトの設定に関するいくつかのオプションが表示されます。矢印キーとEnterキーを使ってナビゲートし、必要なオプションを選択します。特に好みがなければ、Enterキーを押してデフォルトのオプションを採用し、設定を続行してください。設定オプションを選択し、CLIがセットアップを実行すると、次のようなメッセージが表示されます。 ```text ✔ Packages installed successfully. Successfully initialized git. ``` これで、ローカルにプロジェクトを実行する準備が整いました！ #### ローカルに新しいプロジェクトを実行する {#running-your-new-project-locally} ターミナルで、新しいAngularプロジェクトに切り替えます。 ```shell cd my-first-angular-app ``` この時点で、すべての依存関係がインストールされているはずです（プロジェクト内に`node_modules`フォルダの存在を確認できます）。次のコマンドを実行してプロジェクトを開始できます。 ```shell npm start ``` すべてが正常に完了すると、ターミナルに次のような確認メッセージが表示されます。 ```text Watch mode enabled. Watching for file changes... NOTE: Raw file sizes do not reflect development server per-request transformations. ➜ Local: http://localhost:4200/ ➜ press h + enter to show help ``` これで、`Local`のパス（例：`http://localhost:4200`）にアクセスしてアプリケーションを確認できます。コーディングを楽しんでください！🎉 ### 開発でのAIの使用 {#using-ai-for-development} AI搭載IDEでの開発を開始するには、[Angularプロンプトルールとベストプラクティスをチェックしてください](/ai/develop-with-ai)。 ## 次のステップ {#next-steps} Angularプロジェクトを作成したので、[基本ガイド](/essentials)でAngularの詳細について学ぶか、詳しいガイドからトピックを選択してください！ # Angular コーディングスタイルガイド ## はじめに {#introduction} このガイドでは、Angularアプリケーションコードのさまざまなスタイル規約について説明します。これらの推奨事項は Angularが機能するために必須ではありませんが、Angularエコシステム全体で一貫性を促進する一連のコーディングプラクティスを確立します。一貫したプラクティスセットにより、コードの共有やプロジェクト間の移動が容易になります。このガイドは、TypeScriptやAngularに無関係な一般的なコーディングプラクティスは_対象としていません_。 TypeScriptについては、 [GoogleのTypeScriptスタイルガイド](https://google.github.io/styleguide/tsguide.html)を確認してください。 ### 迷ったときは一貫性を優先する {#when-in-doubt-prefer-consistency} これらのルールが特定のファイルのスタイルと矛盾する状況に遭遇した場合は、ファイル内の一貫性を維持することを優先してください。単一のファイル内で異なるスタイル規約を混在させることは、このガイドの推奨事項から逸脱するよりも多くの混乱を生み出します。 ## 命名 {#naming} ### ファイル名では単語をハイフンで区切る {#separate-words-in-file-names-with-hyphens} ファイル名内の単語はハイフン (`-`) で区切ります。例えば、`UserProfile`という名前のコンポーネントは `user-profile.ts`というファイル名を持ちます。 ### ファイルのテストには末尾に`.spec`を付けて同じ名前を使用する {#use-the-same-name-for-a-files-tests-with-spec-at-the-end} 単体テストの場合、ファイル名の末尾を`.spec.ts`にします。例えば、 `UserProfile`コンポーネントの単体テストファイルは`user-profile.spec.ts`というファイル名を持ちます。 ### ファイル名を内部のTypeScript識別子と一致させる {#match-file-names-to-the-typescript-identifier-within} ファイル名は一般的にファイル内のコードの内容を記述するべきです。ファイルが TypeScriptクラスを含む場合、ファイル名はそのクラス名を反映するべきです。例えば、 `UserProfile`という名前のコンポーネントを含むファイルは`user-profile.ts`という名前を持ちます。ファイルが複数の主要な名前を付けられる識別子を含む場合、内部のコードの共通のテーマを記述する名前を選択します。ファイル内のコードが共通のテーマや機能領域に収まらない場合、コードを異なるファイルに分割することを検討してください。 `helpers.ts`、`utils.ts`、`common.ts`のような過度に一般的なファイル名は避けてください。 ### コンポーネントのTypeScript、テンプレート、スタイルに同じファイル名を使用する {#use-the-same-file-name-for-a-components-typescript-template-and-styles} コンポーネントは通常、1つのTypeScriptファイル、1つのテンプレートファイル、 1つのスタイルファイルで構成されます。これらのファイルは異なるファイル拡張子を持つ同じ名前を共有するべきです。例えば、`UserProfile`コンポーネントは `user-profile.ts`、`user-profile.html`、`user-profile.css`というファイルを持つことができます。コンポーネントが複数のスタイルファイルを持つ場合、そのファイルに固有のスタイルを記述する追加の単語を名前に付加します。例えば、`UserProfile`は `user-profile-settings.css`と`user-profile-subscription.css`というスタイルファイルを持つかもしれません。 ## プロジェクト構造 {#project-structure} ### アプリケーションのすべてのコードは`src`という名前のディレクトリに配置する {#all-the-applications-code-goes-in-a-directory-named-src} すべてのAngular UIコード（TypeScript、HTML、スタイル）は、 `src`という名前のディレクトリ内に配置する必要があります。設定ファイルやスクリプトなど、UIに関連しないコードは`src`ディレクトリの外に配置する必要があります。これにより、ルートアプリケーションディレクトリが異なるAngularプロジェクト間で一貫性を保ち、プロジェクト内のUIコードとその他のコードとの明確な分離が生まれます。 ### アプリケーションを`src`直下の`main.ts`という名前のファイルでブートストラップする {#bootstrap-your-application-in-a-file-named-maints-directly-inside-src} Angularアプリケーションを起動、つまり**ブートストラップ**するためのコードは、常に`main.ts`という名前のファイルに配置する必要があります。これはアプリケーションの主要なエントリポイントを表します。 ### 密接に関連するファイルを同じディレクトリにまとめる {#group-closely-related-files-together-in-the-same-directory} Angularコンポーネントは、TypeScriptファイルと、オプションでテンプレートおよび1つ以上のスタイルファイルで構成されます。これらは同じディレクトリにまとめる必要があります。単体テストは、テスト対象のコードと同じディレクトリに配置する必要があります。関連性のないテストを単一の`tests`ディレクトリに集めるのは避けてください。 ### プロジェクトを機能領域ごとに整理する {#organize-your-project-by-feature-areas} アプリケーションの機能や、それらのディレクトリ内のコードに共通するテーマに基づいて、プロジェクトをサブディレクトリに整理します。例えば、映画館サイトMovieReelのプロジェクト構造は次のようになるでしょう。 ``` src/ ├─ movie-reel/ │ ├─ show-times/ │ │ ├─ film-calendar/ │ │ ├─ film-details/ │ ├─ reserve-tickets/ │ │ ├─ payment-info/ │ │ ├─ purchase-confirmation/ ``` それらのディレクトリに存在するコードのタイプに基づいてサブディレクトリを作成するのは避けてください。例えば、`components`、`directives`、`services`のようなディレクトリを作成するのは避けてください。 1つのディレクトリにあまりにも多くのファイルを配置して、読み取りやナビゲーションが困難になるのは避けてください。ディレクトリ内のファイル数が増えるにつれて、さらに追加のサブディレクトリに分割することを検討してください。 ### 1ファイル1コンセプト {#one-concept-per-file} ソースファイルは単一の_コンセプト_に焦点を当てることを推奨します。特にAngularクラスの場合、これは通常、1ファイルにつき1つのコンポーネント、ディレクティブ、またはサービスを意味します。ただし、クラスが比較的小さく、単一のコンセプトの一部として結びついている場合は、 1つのファイルに複数のコンポーネントやディレクティブが含まれていても問題ありません。迷った場合は、より小さなファイルになるアプローチを選択してください。 ## 依存性の注入 {#dependency-injection} ### コンストラクターパラメーターインジェクションよりも`inject`関数を推奨 {#prefer-the-inject-function-over-constructor-parameter-injection} コンストラクターパラメーターインジェクションよりも[`inject`](/api/core/inject)関数を使用することを推奨します。[`inject`](/api/core/inject)関数はコンストラクターパラメーターインジェクションと同じように機能しますが、いくつかのスタイルの利点があります。 - [`inject`](/api/core/inject)は、特にクラスが多くの依存性を注入する場合に、一般的に読みやすくなります。 - 注入された依存性へのコメント追加が、構文的に見てより簡単です。 - [`inject`](/api/core/inject)はより優れた型推論を提供します。 - [`useDefineForClassFields`](https://www.typescriptlang.org/tsconfig/#useDefineForClassFields)を使用してES2022+をターゲットにする場合、注入された依存性でフィールドを読み取る際に、フィールド宣言と初期化を分離することを回避できます。 [既存のコードを自動ツールで`inject`にリファクタリングできます](reference/migrations/inject-function)。 ## コンポーネントとディレクティブ {#components-and-directives} ### コンポーネントセレクターの選択 {#choosing-component-selectors} コンポーネントセレクターの選択に関する詳細は [コンポーネントガイド](guide/components/selectors#choosing-a-selector)を参照してください。 ### コンポーネントとディレクティブのメンバーの命名 {#naming-component-and-directive-members} 入力プロパティの[命名](guide/components/inputs#choosing-input-names) および出力プロパティの[命名](guide/components/outputs#choosing-event-names)に関する詳細はコンポーネントガイドを参照してください。 ### ディレクティブセレクターの選択 {#choosing-directive-selectors} ディレクティブはコンポーネントと同様に [アプリケーション固有のプレフィックス](guide/components/selectors#selector-prefixes) を使用すべきです。ディレクティブに属性セレクターを使用する場合、camelCaseの属性名を使用してください。例えば、アプリケーション名が「MovieReel」で、要素にツールチップを追加するディレクティブを構築する場合、セレクターとして`[mrTooltip]`を使用できます。 ### メソッドの前にAngular固有のプロパティをグループ化する {#group-angular-specific-properties-before-methods} コンポーネントとディレクティブは、通常クラス宣言の先頭近くにAngular固有のプロパティをまとめてグループ化すべきです。これには、注入された依存関係、入力、出力、およびクエリが含まれます。これらやその他のプロパティは、クラスのメソッドの前に定義してください。この慣行により、クラスのテンプレートAPIと依存関係を見つけやすくなります。 ### コンポーネントとディレクティブをプレゼンテーションに集中させる {#keep-components-and-directives-focused-on-presentation} コンポーネントとディレクティブ内のコードは、一般的にページに表示されるUIに関連するものであるべきです。 UIから切り離され、それ自体で意味をなすコードについては、他のファイルへのリファクタリングを推奨します。例えば、フォームの検証ルールやデータ変換を個別の関数やクラスに分割できます。 ### テンプレート内の過度に複雑なロジックを避ける {#avoid-overly-complex-logic-in-templates} Angularテンプレートは [JavaScriptのような式](guide/templates/expression-syntax) に対応するように設計されています。これらの式を活用して、比較的単純なロジックをテンプレート式に直接記述すべきです。ただし、テンプレート内のコードが複雑になりすぎた場合は、ロジックをTypeScriptコード（通常は[computed](guide/signals#computed-signals)を使用）にリファクタリングしてください。何が「複雑」であるかを決定する厳格なルールはありません。最善の判断を使用してください。 ### コンポーネントのテンプレートのみで使用されるクラスメンバーには`protected`を使用する {#use-protected-on-class-members-that-are-only-used-by-a-components-template} コンポーネントクラスのpublicメンバーは、依存性の注入と[クエリ](guide/components/queries)を介してアクセス可能なpublic APIを本質的に定義します。コンポーネントのテンプレートから読み取られることを意図したメンバーには、`protected`アクセスを推奨します。 ```ts @Component({ ..., template: `

`, }) export class UserProfile { firstName = input(); lastName = input(); // `fullName` is not part of the component's public API, but is used in the template. protected fullName = computed(() => `${this.firstName()} ${this.lastName()}`); } ``` ### 変更されるべきでないプロパティには`readonly`を使用する {#use-readonly-for-properties-that-shouldnt-change} Angularによって初期化されるコンポーネントとディレクティブのプロパティを`readonly`としてマークします。これには、`input`、`model`、`output`、およびクエリによって初期化されるプロパティが含まれます。 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`を推奨する {#prefer-class-and-style-over-ngclass-and-ngstyle} `class`および`style`バインディングを、[`NgClass`](/api/common/NgClass)および[`NgStyle`](/api/common/NgStyle)ディレクティブの使用よりも推奨します。 ```html {prefer}

``` ```html {avoid}

``` `class`および`style`バインディングはどちらも、標準のHTML属性と密接に連携する、より直接的な構文を使用します。これにより、特に基本的なHTMLに慣れている開発者にとって、テンプレートが読みやすく理解しやすくなります。さらに、`NgClass`および`NgStyle`ディレクティブは、組み込みの`class`および`style`バインディング構文と比較して、追加のパフォーマンスコストが発生します。詳細については、[バインディングガイド](/guide/templates/binding#css-class-and-style-property-bindings)を参照してください。 ### イベントハンドラーはトリガーイベントではなく、*実行する内容*で命名する {#name-event-handlers-for-what-they-do-not-for-the-triggering-event} イベントハンドラーは、トリガーイベントではなく、実行するアクションで命名することを推奨します。 ```html {prefer} ``` ```html {avoid} ``` このように意味のある名前を使用すると、テンプレートを読むだけでイベントが何をするのかを簡単に判断できます。キーボードイベントの場合、Angularのキーイベント修飾子を特定のハンドラー名とともに使用できます。 ```html

```

イベント処理ロジックが特に長く複雑な場合、単一の適切な名前のハンドラーを宣言するのは非現実的です。
このような場合、「handleKeydown」のような名前に戻し、
イベントの詳細に基づいてより具体的な動作に委譲しても問題ありません。

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

### ライフサイクルメソッドをシンプルに保つ {#keep-lifecycle-methods-simple}

`ngOnInit`のようなライフサイクルフック内に長く複雑なロジックを配置することは避けてください。
代わりに、そのロジックを含む適切な名前のメソッドを作成し、ライフサイクルフック内で _それらのメソッドを呼び出す_ ことを推奨します。
ライフサイクルフック名は、それらが _いつ_ 実行されるかを記述するため、
内部のコードには、そのコードが何をしているかを記述する意味のある名前がありません。

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

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

### ライフサイクルフックインターフェースを使用する {#use-lifecycle-hook-interfaces}

Angularは、各ライフサイクルメソッドに対応するTypeScriptインターフェースを提供します。
クラスにライフサイクルフックを追加する際は、これらのインターフェースをインポートして`implement`し、メソッドが正しく命名されていることを確認してください。

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

@Component({
  /* ... */
})
export class UserProfile implements OnInit {
  // The `OnInit` interface ensures this method is named correctly.
  ngOnInit() {
    /* ... */
  }
}
```
コンポーネントは、Angularアプリケーションの主要な構成要素です。各コンポーネントは、より大きなウェブページの一部を表します。アプリケーションをコンポーネントに整理することで、プロジェクトに構造が与えられ、コードが特定の部分に明確に分割されるため、保守と拡張が容易になります。

## コンポーネントの定義 {#defining-a-component}

すべてのコンポーネントには、いくつかの主要な部分があります。

1. Angularによって使用されるいくつかの設定を含む`@Component`[デコレーター](https://www.typescriptlang.org/docs/handbook/decorators.html)。
2. DOMにレンダリングされる内容を制御するHTMLテンプレート。
3. HTMLでコンポーネントがどのように使用されるかを定義する[CSSセレクター](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors)。
4. ユーザー入力の処理やサーバーへのリクエストの実行など、動作を定義するTypeScriptクラス。

`UserProfile`コンポーネントの簡略化された例を以下に示します。

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

`@Component`デコレーターは、テンプレートに適用するCSSを指定するために、オプションで`styles`プロパティも受け付けます。

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

### HTMLとCSSを別々のファイルに分離する {#separating-html-and-css-into-separate-files}

`templateUrl`と`styleUrl`を使用して、コンポーネントのHTMLとCSSを別々のファイルで定義できます。

```typescript
// user-profile.ts
@Component({
  selector: 'user-profile',
  templateUrl: 'user-profile.html',
  styleUrl: 'user-profile.css',
})
export class UserProfile {
  // コンポーネントの動作はここに定義されます
}
```

```html

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

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

## コンポーネントの使用 {#using-components}

アプリケーションは複数のコンポーネントを組み合わせて構築します。例えば、ユーザーのプロファイルページを作成する場合、次のようにページをいくつかのコンポーネントに分割できます。

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

ここで、`UserProfile`コンポーネントは他のいくつかのコンポーネントを使用して最終的なページを作成します。

コンポーネントをインポートして使用するには、次の手順が必要です。

1. コンポーネントのTypeScriptファイルに、使用するコンポーネントの`import`文を追加します。
2. `@Component`デコレーターの`imports`配列に、使用するコンポーネントのエントリを追加します。
3. コンポーネントのテンプレートに、使用するコンポーネントのセレクターと一致する要素を追加します。

`ProfilePhoto`コンポーネントをインポートする`UserProfile`コンポーネントの例を次に示します。

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

@Component({
  selector: 'user-profile',
  imports: [ProfilePhoto],
  template: `
    <h1>User profile</h1>
    <profile-photo />
    <p>This is the user profile page</p>
  `,
})
export class UserProfile {
  // コンポーネントの動作はここに定義されます
}
```

TIP: Angularコンポーネントの詳細については、[詳細なコンポーネントガイド](guide/components)を参照してください。

## 次の手順 {#next-step}

Angularでのコンポーネントの動作が分かったところで、アプリケーションに動的なデータをどのように追加して管理するかを学ぶ時です。
# コンポーネントセレクター

TIP: このガイドは、[基本概念のガイド](essentials) を既にお読みになっていることを前提としています。Angularを初めて使用する場合は、まずこちらをお読みください。

各コンポーネントは、
コンポーネントの使用方法を決定する
[CSS セレクター](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) を定義します。

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

コンポーネントを使用するには、*他の*コンポーネントのテンプレートに一致するHTML要素を作成します。

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

**Angularはコンパイル時にセレクターを静的にマッチングします。**
AngularバインディングやDOM APIを介して実行時にDOMを変更しても、レンダリングされるコンポーネントには影響しません。

**1つの要素は、1つのコンポーネントセレクターにのみマッチングできます。**
複数のコンポーネント セレクターが1つの要素にマッチングする場合、Angularはエラーを報告します。

**コンポーネント セレクターは大文字と小文字を区別します。**

## セレクターの種類

Angularは、コンポーネントセレクターで
[基本的なCSSセレクターの種類](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors)
の一部をサポートしています。

| **セレクターの種類**  | **説明**                                                                                                 | **例**                  |
| ------------------ | --------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| タイプセレクター      | HTML タグ名またはノード名に基づいて要素をマッチングします。                                                    | `profile-photo`               |
| 属性セレクター | HTML 属性の存在に基づいて要素をマッチングし、オプションでその属性の正確な値を指定します。 | `[dropzone]` `[type="reset"]` |
| クラスセレクター     | CSS クラスの存在に基づいて要素をマッチングします。                                                          | `.menu-item`                  |

属性値の場合、Angularは等号 (`=`) 演算子を使用して、正確な属性値をマッチングすることをサポートしています。
Angularは他の属性値の演算子をサポートしていません。

Angularコンポーネントセレクターは、
[子孫結合子](https://developer.mozilla.org/docs/Web/CSS/Descendant_combinator) や
[子結合子](https://developer.mozilla.org/docs/Web/CSS/Child_combinator) を含む結合子をサポートしていません。

Angularコンポーネントセレクターは、
[名前空間](https://developer.mozilla.org/docs/Web/SVG/Namespaces_Crash_Course) を指定することをサポートしていません。

### `:not` 擬似クラス

Angularは [`:not` 擬似クラス](https://developer.mozilla.org/docs/Web/CSS/:not) をサポートしています。
他のセレクターにこの擬似クラスを追加することで、コンポーネントのセレクターがマッチングする要素を絞り込むことができます。
たとえば、`[dropzone]` 属性セレクターを定義して、
`textarea` 要素のマッチングを防ぐことができます。

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

Angularは、コンポーネント セレクターで他の擬似クラスまたは擬似要素をサポートしていません。

### セレクターの組み合わせ

複数のセレクターを連結することで、組み合わせられます。
たとえば、`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 { }
```

Angularは、リスト内の_いずれか_のセレクターにマッチングする要素ごとにコンポーネントを作成します。

## セレクターの選択

ほとんどのコンポーネントは、カスタム要素名をセレクターとして使用する必要があります。
すべてのカスタム要素名は、
[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) を参照してください。

### セレクターのプレフィックス

Angularチームは、プロジェクト内で定義されているすべてのカスタムコンポーネントに
短い一貫性のあるプレフィックスを使用することをお勧めします。
たとえば、AngularでYouTubeを構築する場合、コンポーネントに `yt-` プレフィックスを付け、`yt-menu`、`yt-player` などのコンポーネントを作成できます。
このようにセレクターに名前空間を付けると、特定のコンポーネントの出所がすぐにわかります。
デフォルトでは、Angular CLIは `app-` を使用します。

IMPORTANT: Angularは、独自のフレームワークAPIに対して `ng` セレクタープレフィックスを使用します。独自のカスタムコンポーネントのセレクタープレフィックスとして `ng` を使用しないでください。

### 属性セレクターを使用する場合

標準のネイティブ要素にコンポーネントを作成する場合は、属性セレクターを検討する必要があります。
たとえば、カスタムボタンコンポーネントを作成する場合、
属性セレクターを使用して、標準の `<button>` 要素を活用できます。

```typescript
@Component({
  selector: 'button[yt-upload]',
   ...
})
export class YouTubeUploadButton { }
```
この方法により、コンポーネントの利用者は、追加の作業なしで要素のすべての標準APIを直接使用できます。
これは、`aria-label` などのARIA属性に特に役立ちます。

Angularは、使用可能なコンポーネントと一致しないカスタム属性に出会ってもエラーを報告しません。
属性セレクターを使用してコンポーネントを使用する場合、
利用者はコンポーネントまたはそのNgModuleをインポートし忘れることがあり、その結果、コンポーネントがレンダリングされません。
詳細については、[コンポーネントのインポートと使用](guide/components/importing) を参照してください。

属性セレクターを定義するコンポーネントは、小文字、ダッシュ区切りの属性を使用する必要があります。
上記で説明したプレフィックスの推奨事項に従うことができます。
# コンポーネントのスタイリング

TIP: このガイドでは、すでに[基本概念のガイド](essentials)を読んでいることを前提としています。Angularを初めて使用する場合は、まずそちらをお読みください。

コンポーネントには、そのコンポーネントのDOMに適用されるCSSスタイルを含めることができます。

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

また、別のファイルにスタイルを記述できます。

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

Angularがコンポーネントをコンパイルすると、これらのスタイルはコンポーネントのJavaScript出力と共に発行されます。
つまり、コンポーネントのスタイルはJavaScriptモジュールシステムに参加します。
Angularコンポーネントをレンダリングすると、フレームワークはコンポーネントの関連するスタイルを自動的に含めます。
これは、コンポーネントを遅延読み込みする場合でも同様です。

Angularは、[Sass](https://sass-lang.com)、
[less](https://lesscss.org)、[stylus](https://stylus-lang.com)など、
CSSを出力するすべてのツールと連携します。

## スタイルのスコープ

各コンポーネントには、**ビューカプセル化**設定があり、フレームワークがコンポーネントのスタイルをどのようにスコープするかを決定します。
ビューカプセル化モードには、`Emulated`、`ShadowDom`、`ExperimentalIsolatedShadowDom`、`None`の4つのモードがあります。
モードは、`@Component`デコレーターで指定できます。

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

### ViewEncapsulation.Emulated

デフォルトでは、Angularはエミュレートされたカプセル化を使用するため、
コンポーネントのスタイルは、そのコンポーネントのテンプレートで定義された要素にのみ適用されます。
このモードでは、フレームワークは各コンポーネントインスタンスに対して一意のHTML属性を生成し、
その属性をコンポーネントのテンプレート内の要素に追加し、その属性をコンポーネントのスタイルで定義されたCSSセレクターに挿入します。

このモードにより、コンポーネントのスタイルが外部に漏れて他のコンポーネントに影響を与えることがなくなります。
ただし、コンポーネントの外側に定義されたグローバルスタイルは、
エミュレートされたカプセル化を持つコンポーネント内の要素に影響を与える可能性があります。

エミュレートされたモードでは、Angularは
[`:host`](https://developer.mozilla.org/docs/Web/CSS/:host)擬似クラスをサポートします。
[`:host-context()`](https://developer.mozilla.org/docs/Web/CSS/:host-context)擬似クラスは
モダンブラウザでは非推奨ですが、Angularのコンパイラは完全にサポートします。これらの擬似クラスは
ネイティブの[Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM)
に依存せずに使用できます。
コンパイル時に、フレームワークはこれらの擬似クラスを属性に変換するため、実行時にこれらのネイティブ擬似クラスのルール(ブラウザの互換性、特異性など)に準拠しません。Angularの
エミュレートされたカプセル化モードは、
`::shadow`や`::part`など、Shadow DOMに関連するその他の擬似クラスをサポートしていません。

#### `::ng-deep`

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`では、Angularは`<p>`要素がコンポーネント自身のテンプレートから来ることを要求しますが、`<a>`要素はアプリケーション内の任意の場所にある可能性があります。

したがって、実際には、`<a>`要素はコンポーネントのテンプレート内、または投影されたコンテンツや子コンテンツ内にある可能性があります。

- `:host ::ng-deep p a`では、`<a>`要素と`<p>`要素の両方が、コンポーネントのホスト要素の子孫である必要があります。

それらはコンポーネントのテンプレートまたはその子コンポーネントのビューから来る可能性がありますが、アプリケーション内の他の場所からは来ません。

### ViewEncapsulation.ShadowDom

このモードは、
[Web標準のShadow DOM API](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM)
を使用して、コンポーネント内のスタイルをスコープします。
このモードを有効にすると、Angularはコンポーネントのホスト要素にシャドウルートを添付し、コンポーネントのテンプレートとスタイルを対応するシャドウツリーにレンダリングします。

シャドウツリー内のスタイルは、そのシャドウツリー外の要素に影響を与えることができません。

ただし、`ShadowDom`カプセル化を有効にすると、スタイルのスコープ以外にも影響があります。
シャドウツリーにコンポーネントをレンダリングすると、イベントの伝播、
[`<slot>` API](https://developer.mozilla.org/docs/Web/Web_Components/Using_templates_and_slots)
とのやり取り、ブラウザの開発者ツールによる要素の表示方法に影響を与えます。
このオプションを有効にする前に、アプリケーションでShadow DOMを使用することのすべての影響を理解してください。

### ViewEncapsulation.ExperimentalIsolatedShadowDom

上記と同様に動作しますが、このモードでは、_そのコンポーネントのスタイルのみ_が
コンポーネントのテンプレート内の要素に適用されることが厳密に保証されます。グローバルスタイルはシャドウツリー内の要素に影響を与えることができず、シャドウツリー内の
スタイルはシャドウツリー外の要素に影響を与えることができません。

### ViewEncapsulation.None

このモードは、コンポーネントのすべてのスタイルカプセル化を無効にします。
コンポーネントに関連付けられたすべてのスタイルはグローバルスタイルとして動作します。

NOTE: `Emulated`および`ShadowDom`モードでも、Angularはコンポーネントのスタイルが必ずしも外部のスタイルを100%上書きできることを保証しません。
競合が発生した場合、これらのスタイルはコンポーネントのスタイルと同じ詳細度（specificity）を持つと見なされます。

## テンプレートでのスタイルの定義

コンポーネントのテンプレートで`<style>`要素を使用すると、追加のスタイルを定義できます。
コンポーネントのビューカプセル化モードはこのように定義されたスタイルに適用されます。

Angularは、スタイル要素内のバインディングをサポートしていません。

## 外部スタイルファイルの参照

コンポーネントのテンプレートは、
[`<link>`要素](https://developer.mozilla.org/docs/Web/HTML/Element/link)
を使用してCSSファイルを参照できます。さらに、CSSは
[ `@import` at-rule](https://developer.mozilla.org/docs/Web/CSS/@import)
を使用してCSSファイルを参照できます。
Angularはこれらの参照を*外部*スタイルとして扱います。外部スタイルは、エミュレートされたビューカプセル化の影響を受けません。

# 入力プロパティによるデータの受け取り

TIP: このガイドは、既に[基本概念ガイド](essentials)を読んでいることを前提としています。Angularを初めて使用する場合は、まずそちらをお読みください。

TIP: 他のウェブフレームワークに精通している場合は、入力プロパティは_props_に似ています。

コンポーネントを使用する際に、一般的にいくつかのデータを渡したいことがあります。
コンポーネントは、**入力**を宣言することで、受け入れるデータを指定します。

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

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

これにより、テンプレートのプロパティにバインドできます。

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

入力にデフォルト値がある場合、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`は、コンポーネントとディレクティブのプロパティ初期化子でのみ呼び出すことができます。**

コンポーネントクラスを拡張する場合、**入力は子クラスによって継承されます。**

**入力名は大文字と小文字が区別されます。**

## 入力の読み取り

`input`関数は`InputSignal`を返します。シグナルを呼び出すことで値を読み取ることができます。

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

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

// Create a computed expression that reads the value input
  label = computed(() => `The slider's value is ${this.value()}`);
}
```

`input`関数によって作成されたシグナルは読み取り専用です。

## 必須入力

`input`の代わりに`input.required`を呼び出すことで、入力が`required`であることを宣言できます。

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

Angularは、テンプレートでコンポーネントを使用する際に、必須入力が_必ず_設定されていることを強制します。すべての必須入力を指定せずにコンポーネントを使用しようとすると、Angularはビルド時にエラーを報告します。

必須入力は、返される`InputSignal`のジェネリックパラメーターに`undefined`を自動的に含めません。

## 入力の構成

`input`関数は、入力の動作を変更できる2番目のパラメーターとしてconfigオブジェクトを受け取ります。

### 入力変換

入力がAngularによって設定されるときに、その値を変更する`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`の値が変更されるたびに、Angularは`trimString`を実行し、`label`に結果を設定します。

入力変換の最も一般的なユースケースは、テンプレートでより広い範囲の値型を受け入れることであり、多くの場合`null`と`undefined`を含みます。

**入力変換関数は、ビルド時に静的に分析可能でなければなりません。**条件付きで、または式の評価の結果として、変換関数は設定できません。

**入力変換関数は常に[純粋関数](https://en.wikipedia.org/wiki/Pure_function)でなければなりません。**変換関数外の状態に依存すると、予期せぬ動作につながる可能性があります。

#### 型チェック

入力変換を指定すると、変換関数の引数の型によって、テンプレートで入力に設定できる値の型が決まります。

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

function appendPx(value: number): string {
  return `${value}px`;
}
```
上記の例では、`widthPx`入力は`number`を受け入れる一方、`InputSignal`プロパティは`string`を返します。

#### 組み込み変換

Angularには、最も一般的な2つのシナリオのための2つの組み込み変換関数が含まれています。ブール値と数値への値の強制変換です。

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

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

`booleanAttribute`は、属性の_存在_が「true」値を示す標準的なHTML[ブール属性](https://developer.mozilla.org/docs/Glossary/Boolean/HTML)の動作を模倣します。
ただし、Angularの`booleanAttribute`は、リテラル文字列`"false"`をブール値`false`として扱います。

`numberAttribute`は、与えられた値を数値として解析しようと試み、解析に失敗した場合は`NaN`を生成します。

### 入力エイリアス

`alias`オプションを指定して、テンプレートでの入力の名前を変更できます。

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

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

このエイリアスは、TypeScriptコードでのプロパティの使用には影響しません。

一般的にコンポーネントの入力をエイリアス化することは避けるべきですが、この機能は、元の名前のエイリアスを保持しながらプロパティの名前を変更したり、ネイティブDOM要素プロパティの名前との競合を回避したりする場合に役立ちます。

## モデル入力

**モデル入力**は、コンポーネントが新しい値を親コンポーネントに伝播できるようにする特殊なタイプの入力です。

コンポーネントを作成する際に、通常の入力と同様にモデル入力を定義できます。

どちらの種類の入力も、値をプロパティにバインドすることを可能にします。しかし、**モデル入力は、コンポーネントの作者がプロパティに値を書き込むことを可能にします。**プロパティが双方向バインディングでバインドされている場合、新しい値はそのバインディングに伝播します。

```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/signals#reactive-contexts)内を含め、シグナル関数を呼び出すことで値を読み取ることができます。

テンプレートでの双方向バインディングの詳細については、[双方向バインディング](guide/templates/two-way-binding)を参照してください。

### プレーンプロパティとの双方向バインディング

プレーンなJavaScriptプロパティをモデル入力にバインドできます。

```typescript
@Component({
  /* ... */
  // `value`はモデル入力です。
  // 角かっこ内のかっこ記法（別名「バナナインアボックス」）は、双方向バインディングを作成します
  template: '<custom-slider [(value)]="volume" />',
})
export class MediaControls {
  protected volume = 0;
}
```

上記の例では、`CustomSlider`は`value`モデル入力に値を書き込むことができ、それによって`MediaControls`の`volume`プロパティに値が伝播します。このバインディングにより、`value`と`volume`の値が同期します。

### 暗黙的な`change`イベント

コンポーネントまたはディレクティブでモデル入力を宣言すると、Angularはそのモデルに対応する[出力](guide/components/outputs)を自動的に作成します。出力の名前は、モデル入力の名前に「Change」が付いたものです。

```ts
@Directive({
  /* ... */
})
export class CustomCheckbox {
  // これにより、「checkedChange」という名前の出力が自動的に作成されます。
  // テンプレートで `(checkedChange)="handler()"` を使用して購読できます。
  checked = model(false);
}
```

`set`メソッドまたは`update`メソッドを呼び出すことで、モデル入力に新しい値を書き込むたびに、Angularはこの変更イベントを発生させます。

出力の詳細については、[出力によるカスタムイベント](guide/components/outputs)を参照してください。

### モデル入力のカスタマイズ

[通常の入力](guide/signals/inputs)と同様に、モデル入力を必須としてマークしたり、エイリアスを提供したりできます。

モデル入力は入力変換をサポートしません。

### モデル入力を使用する場合

コンポーネントが双方向バインディングをサポートする場合に、モデル入力を使用します。これは通常、ユーザーの操作に基づいて値を変更するためにコンポーネントが存在する場合に適しています。最も一般的には、日付ピッカーやコンボボックスなどのカスタムフォームコントロールは、主要な値にモデル入力を使用する必要があります。

# 入力名の選択

DOM要素のプロパティ（HTMLElementなど）と競合する入力名を選択することは避けてください。名前の競合は、バインドされたプロパティがコンポーネントのものであるか、DOM要素のものであるかについて混乱を招きます。

コンポーネントセレクターのように、コンポーネント入力にプレフィックスを追加することは避けてください。特定の要素は1つのコンポーネントしかホストできないため、カスタムプロパティはすべてコンポーネントに属すると見なすことができます。

# `@Input`デコレーターによる入力の宣言

TIP: Angularチームは新しいプロジェクトにはシグナルベースの`input`関数の使用を推奨していますが、元のデコレーターベースの`@Input` APIは引き続き完全にサポートされています。

コンポーネント入力を宣言する代わりに、プロパティに`@Input`デコレーターを追加できます。

```ts
@Component({...})
export class CustomSlider {
  @Input() value = 0;
}
```
入力へのバインディングは、シグナルベースの入力とデコレーターベースの入力の両方で同じです。

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

### デコレーターベースの入力のカスタマイズ

`@Input`デコレーターは、入力の動作を変更できるconfigオブジェクトを受け取ります。

#### 必須入力

`required`オプションを指定して、特定の入力が常に値を持つ必要があることを強制できます。

```ts
@Component({...})
export class CustomSlider {
  @Input({required: true}) value = 0;
}
```
すべての必須入力を指定せずにコンポーネントを使用しようとすると、Angularはビルド時にエラーを報告します。

#### 入力変換

Angularによって入力が設定されるときにその値を変更する`transform`関数を指定できます。この変換関数は、上記で説明したシグナルベースの入力の変換関数と同様に機能します。

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

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

#### 入力エイリアス

`alias`オプションを指定して、テンプレートでの入力の名前を変更できます。

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

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

`@Input`デコレーターは、configオブジェクトの代わりに、エイリアスを最初のパラメーターとして受け取ります。

入力エイリアスは、上記で説明したシグナルベースの入力と同じように機能します。

### ゲッターとセッターを持つ入力

デコレーターベースの入力を使用する場合、ゲッターとセッターで実装されたプロパティを入力にできます。

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

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

private internalValue = 0;
}
```

パブリックセッターのみを定義することで、_書き込み専用_の入力を作成できます。

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

private internalValue = 0;
}
```

可能な場合は、**ゲッターとセッターの代わりに、入力変換を使用することをお勧めします。**

複雑なゲッターとセッター、またはコストの高いゲッターとセッターは避けてください。Angularは入力のセッターを複数回呼び出す可能性があり、セッターがDOM操作などのコストの高い処理を実行する場合、アプリケーションのパフォーマンスに悪影響を与える可能性があります。

## `@Component`デコレーターでの入力の指定

`@Input`デコレーターに加えて、`@Component`デコレーターの`inputs`プロパティを使用して、コンポーネントの入力を指定できます。これは、コンポーネントが基本クラスからプロパティを継承する場合に役立ちます。

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

文字列の後にコロンを付けてエイリアスを`inputs`リストに指定できます。

```ts
{highlight:[4]}
// `CustomSlider` inherits the `disabled` property from `BaseSlider`.
@Component({
  ...,
  inputs: ['disabled: sliderDisabled'],
})
export class CustomSlider extends BaseSlider { }
```
# カスタムイベントと出力

TIP: このガイドは、[基本概念のガイド](essentials) を既読していることを前提としています。Angularを初めて使用する場合は、まずそちらをお読みください。

Angularコンポーネントは、`output`関数にプロパティを割り当てることでカスタムイベントを定義できます。

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

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

`output`関数は`OutputEmitterRef`を返します。`OutputEmitterRef`の`emit`メソッドを呼び出すことで、イベントを発生させることができます。

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

Angularでは、`output`関数で初期化されたプロパティを**出力**と呼びます。出力を使用すると、`click`などのネイティブブラウザイベントと同様に、カスタムイベントを発生させることができます。

**Angular カスタムイベントは DOM を伝播しません。**

**出力名は、大文字と小文字が区別されます。**

コンポーネントクラスを拡張する場合、**outputsは子クラスによって継承されます。**

`output`関数は、Angularコンパイラにとって特別な意味を持ちます。**`output`は、コンポーネントとディレクティブのプロパティ初期化子でのみ呼び出すことができます。**

## イベントデータの送出

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

```

## 出力名のカスタマイズ

`output`関数は、テンプレートでイベントに異なる名前を指定できるパラメーターを受け入れます。

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

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

このエイリアスは、TypeScriptコードでのプロパティの使用には影響しません。

一般的に、コンポーネントの出力のエイリアスは避けるべきですが、この機能は元の名前のエイリアスを保持しながらプロパティの名前を変更する場合や、ネイティブDOMイベントの名前との衝突を避ける場合に役立ちます。

## プログラムによる出力の購読

コンポーネントを動的に作成する場合は、コンポーネントインスタンスから出力イベントをプログラムで購読できます。
`OutputRef`型には`subscribe`メソッドが含まれています。

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

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

Angularは、サブスクライバーを持つコンポーネントを破棄するときに、イベントサブスクリプションを自動的にクリーンアップします。または、イベントから手動で購読解除できます。`subscribe`関数は、`unsubscribe`メソッドを持つ`OutputRefSubscription`を返します。

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

// ...

eventSubscription.unsubscribe();
```

## イベント名の選択

HTMLElementなどのDOM要素のイベントと衝突する出力名を選択することは避けてください。名前の衝突は、バインドされたプロパティがコンポーネントのものであるか、DOM要素のものであるかについて混乱を招きます。

コンポーネントセレクターのように、コンポーネント出力にプレフィックスを追加することは避けてください。特定の要素は1つのコンポーネントしかホストできないため、カスタムプロパティはすべてコンポーネントに属すると見なすことができます。

常に[camelCase](https://en.wikipedia.org/wiki/Camel_case)出力名を使用してください。「on」で始まる出力名は避けてください。

## RxJSを使用したoutputs

outputsとRxJSの相互運用性については、[RxJS interop with component and directive outputs](ecosystem/rxjs-interop/output-interop)を参照してください。

## `@Output`デコレーターを使用した出力の宣言

TIP: Angularチームは新規プロジェクトでは`output`関数の使用を推奨していますが、
元のデコレーターベースの`@Output`APIは引き続き完全にサポートされています。

代替として、新しい`EventEmitter`にプロパティを割り当て、`@Output`デコレーターを追加することで、カスタムイベントを定義できます。

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

`EventEmitter`の`emit`メソッドを呼び出すことで、イベントを発生させることができます。

### `@Output`デコレーターを使用したエイリアス

`@Output`デコレーターは、テンプレートでイベントに異なる名前を指定できるパラメーターを受け入れます。

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

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

このエイリアスは、TypeScriptコードでのプロパティの使用には影響しません。

## `@Component`デコレーターでの出力の指定

`@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: このガイドは、すでに [基本ガイド](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 {/* ... */}
```

TIP: `<ng-content>`は、
[ネイティブの`<slot>`要素](https://developer.mozilla.org/docs/Web/HTML/Element/slot)と似ていますが、
Angular固有の機能も備えています。

`<ng-content>`を使用したコンポーネントを使用する場合、
コンポーネントホスト要素の子要素はすべて、その`<ng-content>`の場所にレンダリング、あるいは**投影されます**:

```typescript
// コンポーネントソース
@Component({
  selector: 'custom-card',
  template: `
    <div class="card-shadow">
      <ng-content />
    </div>
  `,
})
export class CustomCard {/* ... */}
```

```html

<custom-card>
  <p>これは投影されたコンテンツです</p>
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <p>これは投影されたコンテンツです</p>
  </div>
</custom-card>
```

Angularは、このように渡されるコンポーネントの子要素を、そのコンポーネントの**コンテンツ**と呼びます。
これはコンポーネントの**ビュー**とは異なります。
ビューは、コンポーネントのテンプレートで定義された要素を指します。

**`<ng-content>`要素は、コンポーネントでもDOM要素でもありません。**
代わりに、コンテンツをレンダリングする場所をAngularに伝える特別なプレースホルダーです。
Angularのコンパイラは、ビルド時にすべての`<ng-content>`要素を処理します。
実行時に`<ng-content>`の挿入や削除、変更はできません。ディレクティブやスタイル、任意の属性も`<ng-content>`には追加できません。

IMPORTANT: `<ng-content>`を`@if`、`@for`、または`@switch`によって条件付きで含めるべきではありません。
Angularは常にレンダリングされたコンテンツのDOMノードをインスタンス化して作成します。
その`<ng-content>`プレースホルダが非表示であってもです。コンポーネントコンテンツの条件付きレンダリングについては
[テンプレートフラグメント](api/core/ng-template)を参照してください。

## 複数のコンテンツプレースホルダー {#multiple-content-placeholders}

Angularは、CSSセレクターに基づいて、複数の異なる要素を異なる`<ng-content>`プレースホルダーへの投影をサポートしています。
上記のカードの例を拡張して、`select`属性を使用して、
カードのタイトルと本文の2つのプレースホルダーを作成できます。

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

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

```typescript

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

```typescript

@Component({
  selector: 'app-root',
  imports: [CustomCard, CardTitle, CardBody],
  template: `
    <custom-card>
      <card-title>こんにちは</card-title>
      <card-body>例へようこそ</card-body>
    </custom-card>
`,
})
export class App {}
```

```html

<custom-card>
  <div class="card-shadow">
    <card-title>こんにちは</card-title>
    <div class="card-divider"></div>
    <card-body>例へようこそ</card-body>
  </div>
</custom-card>
```

`<ng-content>`プレースホルダーは、
[コンポーネントセレクター](guide/components/selectors)と同じCSSセレクターをサポートしています。

`select`属性を持つ`<ng-content>`プレースホルダーを1つ以上、
`select`属性を持たない`<ng-content>`プレースホルダーを1つ含める場合、
後者は`select`属性に一致しなかったすべての要素をキャプチャします。

```html

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

```html

<custom-card>
  <card-title>こんにちは</card-title>
  <img src="..." />
  <p>例へようこそ</p>
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <card-title>こんにちは</card-title>
    <div class="card-divider"></div>
    <img src="..." />
    <p>例へようこそ</p>
  </div>
</custom-card>
```

コンポーネントに`select`属性を持たない`<ng-content>`プレースホルダーが含まれていない場合、
コンポーネントのいずれかのプレースホルダーに一致しない要素はDOMにレンダリングされません。

## フォールバックコンテンツ {#fallback-content}

Angularは、コンポーネントの`<ng-content>`プレースホルダーに一致する子コンテンツがない場合、コンポーネントの`<ng-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>
```

## 投影のためのコンテンツのエイリアシング {#aliasing-content-for-projection}

Angularは、任意の要素にCSSセレクターを指定できる特殊な属性`ngProjectAs`をサポートしています。
`ngProjectAs`を持つ要素が`<ng-content>`プレースホルダーに対してチェックされると、
Angularは要素のIDではなく`ngProjectAs`の値と比較します。

```html

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

```html

<custom-card>
  <h3 ngProjectAs="card-title">こんにちは</h3>

<p>例へようこそ</p>
</custom-card>
```

```html

<custom-card>
  <div class="card-shadow">
    <h3>こんにちは</h3>
    <div class="card-divider"></div>
    <p>例へようこそ</p>
  </div>
</custom-card>
```

`ngProjectAs`は静的な値のみをサポートし、動的な式にはバインドできません。
# コンポーネントライフサイクル

TIP: このガイドは、[基本概念のガイド](essentials) を既にお読みになっていることを前提としています。Angularを初めて使用する場合は、まずそちらをお読みください。

コンポーネントの**ライフサイクル**とは、コンポーネントの作成から破棄までの間に起こる一連のステップのことです。
各ステップは、Angularがコンポーネントをレンダリングし、
時間の経過とともに更新をチェックするプロセスにおける異なる部分を表しています。

コンポーネントでは、これらのステップ中にコードを実行するために**ライフサイクルフック**を実装できます。
特定のコンポーネントインスタンスに関連するライフサイクルフックは、コンポーネントクラスのメソッドとして実装されます。
Angularアプリケーション全体に関連するライフサイクルフックは、
コールバックを受け取る関数として実装されます。

コンポーネントのライフサイクルは、Angularが時間の経過とともにコンポーネントの変更をチェックする方法と密接に関連しています。
このライフサイクルを理解するために必要なのは、Angularがアプリケーションツリーを上から下に歩き、
テンプレートバインディングの変更をチェックすることだけです。
以下で説明するライフサイクルフックは、Angularがこのトラバーサルを実行している間に実行されます。
このトラバーサルは、各コンポーネントをちょうど1回だけ訪問するため、
プロセス中にさらに状態を変更することは避けるべきです。

## 概要

<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">変更検知</td>
      <td><code>ngOnInit</code>
      </td>
      <td>Angular がコンポーネントのすべての入力を初期化した後に1回実行されます。</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>コンテンツ</em>が初期化された後に1回実行されます。</td>
    </tr>
    <tr>
      <td><code>ngAfterContentChecked</code></td>
      <td>このコンポーネントのコンテンツが変更のためにチェックされるたびに実行されます。</td>
    </tr>
    <tr>
      <td><code>ngAfterViewInit</code></td>
      <td>コンポーネントの<em>ビュー</em>が初期化された後に1回実行されます。</td>
    </tr>
    <tr>
      <td><code>ngAfterViewChecked</code></td>
      <td>コンポーネントのビューが変更のためにチェックされるたびに実行されます。</td>
    </tr>
    <tr>
      <td rowspan="2">レンダリング</td>
      <td><code>afterNextRender</code></td>
      <td><strong>すべての</strong>コンポーネントがDOMにレンダリングされた次の時間に1回実行されます。</td>
    </tr>
    <tr>
      <td><code>afterEveryRender</code></td>
      <td><strong>すべての</strong>コンポーネントがDOMにレンダリングされるたびに実行されます。</td>
    </tr>
    <tr>
      <td>破棄</td>
      <td><code>ngOnDestroy</code></td>
      <td>コンポーネントが破棄される直前に1回実行されます。</td>
    </tr>
  </table>
</div>

### ngOnInit

`ngOnInit` メソッドは、Angularがすべてのコンポーネントの入力を初期値で初期化した後に実行されます。
コンポーネントの `ngOnInit` は、ちょうど1回だけ実行されます。

このステップは、コンポーネント自身のテンプレートが初期化される<em>前</em>に発生します。
これは、初期入力値に基づいてコンポーネントの状態を更新できることを意味します。

### ngOnChanges

`ngOnChanges` メソッドは、コンポーネントの入力が変更された後に実行されます。

このステップは、コンポーネント自身のテンプレートがチェックされる<em>前</em>に発生します。
これは、初期入力値に基づいてコンポーネントの状態を更新できることを意味します。

初期化中は、最初の `ngOnChanges` は `ngOnInit` の前に実行されます。

#### 変更の検査

`ngOnChanges` メソッドは、1つの `SimpleChanges` 引数を受け取ります。
このオブジェクトは、[`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) であり、
各コンポーネントの入力名を `SimpleChange` オブジェクトにマッピングします。
各 `SimpleChange` には、入力の以前の値、現在の値、
および入力が初めて変更されたかどうかを示すフラグが含まれています。

より強力な型チェックのために、オプションで現在のクラスまたはthisを最初のジェネリック引数として渡すことができます。

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

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

入力プロパティに `alias` を指定した場合、`SimpleChanges` Recordは、エイリアスではなく、
TypeScriptプロパティ名をキーとして使用します。

### ngOnDestroy

`ngOnDestroy` メソッドは、コンポーネントが破棄される直前に1回だけ実行されます。
Angularは、コンポーネントがページに表示されなくなった場合（`@if` によって隠された場合や、別のページに移動した場合など）、
コンポーネントを破棄します。

#### DestroyRef

`ngOnDestroy` メソッドの代わりに、`DestroyRef` のインスタンスを注入できます。
コンポーネントの破棄時に呼び出されるコールバックを登録するには、
`DestroyRef` の `onDestroy` メソッドを呼び出します。

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

`DestroyRef` インスタンスを、
コンポーネント外部の関数やクラスに渡すことができます。
このパターンは、コンポーネントが破棄されたときにクリーンアップを実行する必要がある他のコードがある場合に使用します。

`DestroyRef` を使用して、クリーンアップコードをすべて `ngOnDestroy` メソッドに置くのではなく、
クリーンアップコードに近い場所にセットアップコードを保持できます。

##### インスタンス破棄の検出

`DestroyRef` は、指定されたインスタンスが既に破棄されているかどうかを確認できる `destroyed` プロパティを提供します。これは、特に遅延または非同期ロジックを扱う際に、破棄されたコンポーネントでの操作を避けるのに役立ちます。

`destroyRef.destroyed` をチェックすることで、インスタンスがクリーンアップされた後にコードが実行されるのを防ぎ、`NG0911: View has already been destroyed.` などの潜在的なエラーを回避できます。

### ngDoCheck

`ngDoCheck` メソッドは、
Angularがコンポーネントのテンプレートの変更をチェックするたびに実行されます。

このライフサイクルフックを使用して、Angularの通常の変更検知の外部で状態の変更を手動でチェックし、コンポーネントの状態を手動で更新できます。

このメソッドは非常に頻繁に実行され、ページのパフォーマンスに大きく影響する可能性があります。
可能な限り、このフックの定義を避け、代替手段がない場合にのみ使用してください。

初期化中は、最初の `ngDoCheck` は `ngOnInit` の後に実行されます。

### ngAfterContentInit

`ngAfterContentInit` メソッドは、
コンポーネント（その*コンテンツ*）内にネストされたすべての子が初期化された後に1回だけ実行されます。

このライフサイクルフックを使用して、
[コンテンツクエリ](guide/components/queries#content-queries) の結果を読み取ることができます。
これらのクエリの初期化された状態にアクセスできますが、このメソッドで状態を変更しようとすると、
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100) が発生します。

### ngAfterContentChecked

`ngAfterContentChecked` メソッドは、
コンポーネント（その*コンテンツ*）内にネストされたすべての子が変更のためにチェックされるたびに実行されます。

[コンテンツクエリ](guide/components/queries#content-queries)
の更新された状態にアクセスできますが、
このメソッドで状態を変更しようとすると、
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100) が発生します。

### ngAfterViewInit

`ngAfterViewInit` メソッドは、
コンポーネントのテンプレート（その*ビュー*）内のすべての子が初期化された後に1回だけ実行されます。

このライフサイクルフックを使用して、
[ビュークエリ](guide/components/queries#view-queries) の結果を読み取ることができます。
これらのクエリの初期化された状態にアクセスできますが、このメソッドで状態を変更しようとすると、
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100) が発生します。

### ngAfterViewChecked

`ngAfterViewChecked` メソッドは、
コンポーネントのテンプレート（その*ビュー*）内のすべての子が変更のためにチェックされるたびに実行されます。

[ビュークエリ](guide/components/queries#view-queries) 
の更新された状態にアクセスできますが、
このメソッドで状態を変更しようとすると、
[ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100) が発生します。

### afterEveryRender と afterNextRender

`afterEveryRender` と `afterNextRender` 関数は、
Angularがページ上の*すべてのコンポーネント*をDOMにレンダリングし終えた後に呼び出される**レンダリングコールバック** を登録できます。

これらの関数は、このガイドで説明した他のライフサイクルフックとは異なります。
クラスメソッドではなく、コールバックを受け取るスタンドアロン関数です。
レンダリングコールバックの実行は、特定のコンポーネントインスタンスに結び付けられるのではなく、アプリケーション全体のフックに結び付けられます。

`afterEveryRender` と `afterNextRender` は、
[注入コンテキスト](guide/di/dependency-injection-context)（通常はコンポーネントのコンストラクター）
で呼び出す必要があります。

レンダリングコールバックを使用して、手動でDOMを操作できます。
AngularでDOMを操作する方法については、[DOM API の使用](guide/components/dom-apis) を参照してください。

レンダリングコールバックは、サーバーサイドレンダリング中またはビルド時の事前レンダリング中は実行されません。

#### after\*Render フェーズ

`afterEveryRender` または `afterNextRender` を使用する場合、
オプションで作業をフェーズに分割できます。
フェーズを使用すると、DOM操作のシーケンスを制御でき、[レイアウトのスラッシング](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing) を最小限に抑えるために、
*書き込み*操作を*読み込み*操作の前にシーケンスできます。
フェーズ間で通信するために、フェーズ関数は、
次のフェーズでアクセスできる結果値を返すことができます。

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

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

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

afterNextRender({
      // `Write` フェーズを使用して、ジオメトリのプロパティに書き込みます。
      write: () => {
        const padding = computePadding();
        const changed = padding !== this.prevPadding;
        if (changed) {
          nativeElement.style.padding = padding;
        }
        return changed; // 何か変更があったかどうかを `Read` フェーズに伝えます。
      },

// `Read` フェーズを使用して、すべての書き込みが完了した後にジオメトリのプロパティを読み取ります。
      read: (didWrite) => {
        if (didWrite) {
          this.elementHeight = nativeElement.getBoundingClientRect().height;
        }
      }
    });
  }
}
```

フェーズは4つあり、次の順序で実行されます。

| フェーズ              | 説明                                                                                                                                                                                                      |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `earlyRead`        | このフェーズを使用して、その後の計算に厳密に必要な、レイアウトに影響を与えるDOMプロパティとスタイルを読み取ります。可能な限り、このフェーズを避け、`write` フェーズと `read` フェーズを優先します。     |
| `write`             | このフェーズを使用して、レイアウトに影響を与えるDOMプロパティとスタイルを書き込みます。                                                                                                                     |
| `mixedReadWrite`    | デフォルトのフェーズ。レイアウトに影響を与えるプロパティとスタイルを読み書きする必要がある操作に使用します。可能な限り、このフェーズを避け、明示的な `write` フェーズと `read` フェーズを優先します。  |
| `read`              | このフェーズを使用して、レイアウトに影響を与えるDOMプロパティを読み取ります。                                                                                                                              |

## ライフサイクルインターフェース

Angularは、各ライフサイクルメソッド用のTypeScriptインターフェースを提供します。
これらのインターフェースをインポートして `implement` することで、
実装に誤字脱字がないことを保証できます。

各インターフェースは、`ng` プレフィックスのない対応するメソッドと同じ名前を持っています。
たとえば、`ngOnInit` のインターフェースは `OnInit` です。

```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--Rendering-->afterNextRender-->afterEveryRender
```

### 後続の更新

```mermaid
graph TD;
subgraph CHANGE [変更検知]
direction TB
ngOnChanges-->ngDoCheck
ngDoCheck-->ngAfterContentChecked;
ngDoCheck-->ngAfterViewChecked
end
CHANGE--Rendering-->afterEveryRender
```

### ディレクティブとの順序付け

テンプレートまたは `hostDirectives` プロパティで、コンポーネントと同じ要素に1つ以上のディレクティブを配置する場合、
フレームワークは単一の要素上のコンポーネントとディレクティブの間で特定のライフサイクルフックの順序を保証しません。
観察された順序に依存しないでください。
これは、Angularの以降のバージョンで変更される可能性があります。
コンポーネントテンプレートは静的なHTMLだけではありません。コンポーネントクラスのデータを使用し、ユーザーインタラクションのハンドラーを設定できます。

## 動的なテキストの表示 {#showing-dynamic-text}

Angularでは、*バインディング*によって、コンポーネントのテンプレートとそのデータ間に動的な接続が作成されます。この接続により、コンポーネントのデータの変更がレンダリングされたテンプレートに自動的に反映されます。

二重中括弧を使用して、テンプレートに動的なテキストを表示するバインディングを作成できます。

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

Angularがコンポーネントをレンダリングすると、以下が表示されます。

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

シグナルの値が変更されると、Angularはバインディングを自動的に最新の状態に保ちます。
上記の例を基に、`userName`シグナルの値を更新する場合:

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

レンダリングされたページは新しい値を反映して更新されます。

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

## 動的なプロパティと属性の設定 {#setting-dynamic-properties-and-attributes}

Angularは、角括弧を使用して動的な値をDOMプロパティにバインドすることをサポートしています。

```typescript
@Component({
  /*...*/
  // `isValidUserId`の値に基づいて、ボタンの`disabled`プロパティを設定します。
  template: `<button [disabled]="!isValidUserId()">Save changes</button>`,
})
export class UserProfile {
  isValidUserId = signal(false);
}
```

属性名に`attr.`をプレフィックスとして付けることで、HTMLの_属性_にもバインドできます。

```html

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

バインドされた値が変更されると、AngularはDOMプロパティと属性を自動的に更新します。

## ユーザーインタラクションの処理 {#handling-user-interaction}

Angularを使用すると、括弧を使用してテンプレート内の要素にイベントリスナーを追加できます。

```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`による制御フロー {#control-flow-with-if-and-for}

Angularの`@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>
  
}
```

Angularの`@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は、上記の例に示すように`track`キーワードを使用して、`@for`によって作成されたDOM要素にデータを関連付けます。詳細については、[_なぜ@forブロック内のtrackは重要ですか？_](guide/templates/control-flow#why-is-track-in-for-blocks-important)を参照してください。

TIP: Angularテンプレートの詳細を知りたい場合は、[詳細なテンプレートガイド](guide/templates)を参照してください。

## 次の手順 {#next-step}

アプリケーションに動的なデータとテンプレートが用意できたので、次は特定の要素を条件付きで非表示または表示したり、要素をループ処理したりするなど、テンプレートを強化する方法を学習します。
# イベントリスナーの追加

Angularは、イベント名とイベントが発生するたびに実行されるステートメントを括弧で囲むことで、テンプレート内の要素にイベントリスナーを定義することをサポートしています。

## ネイティブイベントのリスナー

HTML要素にイベントリスナーを追加する場合は、イベントを括弧 `()` で囲みます。これにより、リスナーのステートメントを指定できます。

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

この例では、Angularは `<input>` 要素が `keyup` イベントを発行するたびに `updateField` を呼び出します。

`click`、`keydown`、`mouseover` などのネイティブイベントのリスナーを追加できます。詳細については、[MDNの要素のすべての利用可能なイベント](https://developer.mozilla.org/en-US/docs/Web/API/Element#events)をご覧ください。

## イベント引数へのアクセス

Angularは、すべてのテンプレートイベントリスナーで、イベントオブジェクトへの参照を含む `$event` という名前の変数を提供します。

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

## キー修飾子の使用

特定のキーの特定のキーボードイベントをキャプチャする場合は、次のようなコードを記述できます。

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

ただし、これは一般的なシナリオであるため、Angularではピリオド（`.`）文字を使用して特定のキーを指定することでイベントをフィルタリングできます。これにより、コードを簡素化できます。

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

追加のキー修飾子を追加できます。

```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.shiftleft)="updateField($event)" />
```

これは、異なるオペレーティングシステム間でキーボードイベントを一貫して処理する場合に役立ちます。たとえば、MacOSデバイスでAltキーを使用する場合、`key` プロパティはAltキーで既に修飾された文字に基づいてキーを報告します。これは、Alt + Sのような組み合わせが `'ß'` の `key` 値を報告することを意味します。ただし、`code` プロパティは、生成された文字ではなく、押された物理的なまたは仮想的なボタンに対応します。

## イベントのデフォルト動作の防止 {#preventing-event-default-behavior}

イベントハンドラーがネイティブのブラウザ動作を置き換える必要がある場合は、イベントオブジェクトの [`preventDefault` メソッド](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault)を使用できます。

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

イベントハンドラーのステートメントが `false` と評価された場合、Angularは自動的に `preventDefault()` を呼び出します。これは、[ネイティブのイベントハンドラー属性](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes)と同様です。_常に明示的に `preventDefault` を呼び出すことを推奨します_。このアプローチによって、コードの意図が明確になります。

## イベント処理の拡張 {#extend-event-handling}

Angularのイベントシステムは、`EVENT_MANAGER_PLUGINS` インジェクショントークンで登録されたカスタムイベントプラグインを介して拡張可能です。

### Event Pluginの実装 {#implementing-event-plugin}

カスタムイベントプラグインを作成するには、`EventManagerPlugin` クラスを拡張し、必要なメソッドを実装します。

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

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

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

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

let timeoutId: number;

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

element.addEventListener(event, listener);

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

アプリケーションのプロバイダーで `EVENT_MANAGER_PLUGINS` トークンを使用してカスタムプラグインを登録します。

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

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

登録後、テンプレート内でカスタムイベント構文を使用できます。`host` プロパティでも使用できます。

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

```ts
@Component({
  ...,
  host: {
    '(click.debounce.500)': 'handleDebouncedClick()',
  },
})
export class AwesomeCard {
  handleDebouncedClick(): void {
   console.log('Debounced click!');
  }
}
```
# 動的なテキスト、プロパティ、属性のバインディング

Angularでは、**バインディング**によってコンポーネントのテンプレートとそのデータ間に動的な接続が作成されます。この接続により、コンポーネントのデータの変更がレンダリングされたテンプレートに自動的に反映されます。

## テキスト補間による動的テキストのレンダリング {#render-dynamic-text-with-text-interpolation}

テンプレートで動的なテキストをバインドするには、二重中括弧を使用します。これは、Angularに内部の式を担当し、それが正しく更新されるように指示します。これは**テキスト補間**と呼ばれます。

```typescript
@Component({
  template: `
    <p>Your color preference is {{ theme }}.</p>
  `,
  ...
})
export class AppComponent {
  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 AppComponent {
  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で通常テキストを記述する場所ならどこでも使用できます。

すべての式の値は文字列に変換されます。オブジェクトと配列は、値の`toString`メソッドを使用して変換されます。

## 動的なプロパティと属性のバインディング

Angularは、角括弧を使用して、動的な値をオブジェクトのプロパティとHTML属性にバインドすることをサポートしています。

HTML要素のDOMインスタンス、[コンポーネント](guide/components)インスタンス、または[ディレクティブ](guide/directives)インスタンスのプロパティにバインドできます。

### ネイティブ要素のプロパティ

すべてのHTML要素には、対応するDOM表現があります。たとえば、各`<button>`HTML要素は、DOM内の`HTMLButtonElement`のインスタンスに対応します。Angularでは、プロパティバインディングを使用して、要素のDOM表現に直接値を設定します。

```html

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

この例では、`isFormValid`が変更されるたびに、Angularは`HTMLButtonElement`インスタンスの`disabled`プロパティを自動的に設定します。

### コンポーネントとディレクティブのプロパティ

要素がAngularコンポーネントの場合、同じ角括弧構文を使用して、コンポーネントの入力プロパティに値を設定するためにプロパティバインディングを使用できます。

```html

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

この例では、`mySelection`が変更されるたびに、Angularは`MyListbox`インスタンスの`value`プロパティを自動的に設定します。

ディレクティブのプロパティにもバインドできます。

```html

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

### 属性 {#attributes}

対応するDOMプロパティを持たないHTML属性(SVG属性など)を設定する必要がある場合は、テンプレート内の要素に属性をバインドするために`attr.`プレフィックスを使用できます。

```html

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

この例では、`listRole`が変更されるたびに、Angularは`setAttribute`を呼び出して`<ul>`要素の`role`属性を自動的に設定します。

属性バインディングの値が`null`の場合、Angularは`removeAttribute`を呼び出して属性を削除します。

### プロパティと属性でのテキスト補間

二重中括弧構文を使用して、プロパティと属性にテキスト補間構文を使用できます。この構文を使用すると、Angularは代入をプロパティバインディングとして扱います。

```html

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

## CSSクラスとスタイルプロパティのバインディング {#css-class-and-style-property-bindings}

Angularは、要素にCSSクラスとCSSスタイルプロパティをバインドするための追加機能をサポートしています。

### CSSクラス

CSSクラスバインディングを作成して、バインドされた値が[真偽値](https://developer.mozilla.org/en-US/docs/Glossary/Truthy)かどうかによって、要素にCSSクラスを追加または削除できます。

```html

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

`class`プロパティに直接バインドもできます。Angularは、3種類の値を受け付けます。

| `class`値の説明                                                                                                                                      | TypeScript型       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| スペースで区切られた1つ以上のCSSクラスを含む文字列                                                                                                   | `string`              |
| CSSクラス文字列の配列                                                                                                                                     | `string[]`            |
| 各プロパティ名がCSSクラス名で、対応する値がそのクラスが要素に適用されるかどうかを真偽値に基づいて決定するオブジェクト。 | `Record<string, any>` |

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

上記の例は、以下のDOMをレンダリングします。

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

Angularは、有効なCSSクラス名ではない文字列値を無視します。

静的CSSクラスを使用する場合、`class`に直接バインドする場合、および特定のクラスをバインドする場合、Angularはレンダリングされた結果ですべてのクラスをインテリジェントに組み合わせます。

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

上記の例では、Angularは`ul`要素を3つのCSSクラスすべてでレンダリングします。

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

Angularは、レンダリングされた要素のCSSクラスの特定の順序を保証しません。

`class`を配列かオブジェクトにバインドする場合、Angularは以前の値と現在の値を三重等号演算子(`===`)を使用して比較します。これらの値を変更する場合は、Angularが更新を適用するために新しいオブジェクトか配列インスタンスを作成する必要があります。

要素に同じCSSクラスの複数のバインディングがある場合、Angularはスタイルの優先順位に従って競合を解決します。

NOTE: クラスバインディングは、単一のキーでスペース区切りのクラス名をサポートしていません。また、バインディングの参照が同じままであるため、オブジェクトの変更もサポートしていません。どちらかが必要な場合は、[ngClass](/api/common/NgClass)ディレクティブを使用してください。

### CSSスタイルプロパティ

要素に直接CSSスタイルプロパティをバインドできます。

```html

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

単位を受け付けるCSSプロパティについては、さらに単位を指定できます。

```html

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

複数のスタイル値を1つのバインディングで設定もできます。Angularは、以下の種類の値を受け付けます。

| `style`値の説明                                                                                              | TypeScript型       |
| ------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `"display: flex; margin: 8px"`などの、0個以上のCSS宣言を含む文字列。                                | `string`              |
| 各プロパティ名がCSSプロパティ名で、対応する値がそのCSSプロパティの値であるオブジェクト。 | `Record<string, any>` |

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

上記の例は、以下のDOMをレンダリングします。

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

`style`をオブジェクトにバインドする場合、Angularは以前の値と現在の値を3つ等しい演算子(`===`)を使用して比較します。これらの値を変更する場合は、Angularが更新を適用するために、新しいオブジェクトインスタンスを作成する必要があります。

要素に同じスタイルプロパティの複数のバインディングがある場合、Angularはスタイルの優先順位に従って競合を解決します。

## ARIA属性 {#aria-attributes}

Angularは、ARIA属性への文字列値のバインディングをサポートしています。

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

Angularは、要素の`aria-label`属性に文字列値を書き込み、バインドされた値が`null`の場合は削除します。

一部のARIA機能は、構造化された値(要素参照など)を受け取るDOMプロパティまたはディレクティブ入力を公開しています。これらの場合は、標準のプロパティバインディングを使用してください。例と追加のガイダンスについては、[アクセシビリティガイド](best-practices/a11y#aria-attributes-and-properties)を参照してください。
# 組み込み制御フロー

Angularテンプレートは制御フローブロックをサポートしており、要素の表示、非表示、繰り返しを条件付きで行うことができます。

## `@if`、`@else if`、`@else`で条件付きのコンテンツを表示する

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

### 条件式の結果への参照

`@if`条件式は、ブロック内で再利用できるように、条件式の結果を変数に保存できます。

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

これは、テンプレート内で読みやすく保守しやすいように長い式を参照するのに便利です。

## `@for`ブロックでコンテンツを繰り返す

`@for` ブロックは、コレクションをループし、ブロックのコンテンツを繰り返しレンダリングします。 コレクションは、任意のJavaScriptの[反復可能オブジェクト](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` は重要なのか？

`track` 式を使用すると、Angularはデータとページ上のDOMノードの関係を維持できます。 これにより、Angularはデータが変更されたときに、必要なDOM操作を最小限に抑えてパフォーマンスを最適化できます。

`track` を効果的に使用すると、データコレクションをループ処理する場合に、アプリケーションのレンダリングパフォーマンスを大幅に向上させることができます。

`track` 式には、コレクション内の各アイテムを一意に識別するプロパティを選択します。 データモデルに一意の識別プロパティ（一般的には `id` または `uuid`）が含まれている場合は、この値を使用します。 データにこのようなフィールドが含まれていない場合は、追加することを強くお勧めします。

変更されない静的なコレクションの場合、`$index` を使用して、コレクション内のインデックスで各アイテムを追跡するようにAngularに指示できます。

他のオプションが利用できない場合は、`identity` を指定できます。 これは、Angularに三重等号演算子 (`===`) を使用して参照の同一性でアイテムを追跡するように指示します。 AngularはどのデータアイテムがどのDOMノードに対応するかをマップする方法がないため、可能な限りこのオプションを避けてください。レンダリングの更新が大幅に遅くなる可能性があります。

### `@for` ブロックのコンテキスト変数

`@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` ブロックをネストする場合に役立ちます。これにより、外側の `@for` ブロックから内側の `@for` ブロックの変数を取得できます。

### `@empty` ブロックを使用した `@for` ブロックのフォールバックの提供

`@for` ブロックのコンテンツの直後に、オプションで `@empty` セクションを含めることができます。 `@empty` ブロックのコンテンツは、アイテムがない場合に表示されます。

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

## `@switch` ブロックを使用して条件付きでコンテンツを表示する

`@if` ブロックはほとんどのシナリオで適していますが、`@switch` ブロックは条件付きでデータをレンダリングするための代替構文を提供します。 構文はJavaScriptの `switch` 文と非常によく似ています。

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

条件式値は、三重等号 (`===`) 演算子を使用してケース式と比較されます。

**`@switch` にはフォールスルーはありません**。そのため、ブロックに `break` や `return` ステートメントに相当するものは必要ありません。

オプションで `@default` ブロックを含めることができます。 `@default` ブロックのコンテンツは、前のケース式のいずれもスイッチ値と一致しない場合に表示されます。

`@case` が式と一致せず、`@default` ブロックがない場合は、何も表示されません。
# テンプレート内の変数

Angularには、テンプレート内で2種類の変数宣言があります。 ローカルテンプレート変数とテンプレート参照変数です。

## `@let` を使ったローカルテンプレート変数

Angularの `@let` 構文を使用すると、ローカル変数を定義し、テンプレート全体で再利用できます。これは、[JavaScriptの`let`構文](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let)に似ています。

### `@let` の使用方法

`@let` を使用して、テンプレート式の結果に基づいた値を持つ変数を宣言します。 Angularは、[バインディング](./templates/bindings)と同様に、指定された式を使用して変数の値を自動的に最新の状態に保ちます。

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

各`@let`ブロックでは、ちょうど1つの変数を宣言できます。コンマを使用して同じブロックに複数の変数の宣言はできません。

### `@let` の値を参照する

`@let` で変数を宣言したら、同じテンプレート内で再利用できます。

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

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

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

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

### 代入可能性

`@let` とJavaScriptの `let` の主な違いは、`@let` は宣言後に再代入できないことです。ただし、Angularは指定された式を使用して変数の値を自動的に最新の状態に保ちます。

```html
@let value = 1;

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

### 変数のスコープ

`@let` 宣言は、現在のビューとその子孫にスコープされます。 Angularは、コンポーネントの境界と、テンプレートに動的なコンテンツ（制御フローブロック、`@defer`ブロック、または構造ディレクティブなど）が含まれる可能性がある場所に新しいビューを作成します。

`@let` 宣言はホイスティングされないため、親ビューまたは兄弟から**アクセスできません**。

```html
@let topLevel = value;

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

{{topLevel}} 
{{insideDiv}}

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

@let nested = value;

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

{{nested}} 
```

### 構文全体

`@let`構文は正式には次のように定義されています。

- `@let`キーワード。
- その後に空白が1つ以上続きます（改行は含まれません）。
- その後に、有効なJavaScript名と空白が0個以上続きます。
- その後に `=` 記号と空白が0個以上続きます。
- その後に、複数行になる可能性のあるAngular式が続きます。
- `；`記号で終了します。

## テンプレート参照変数 {#template-reference-variables}

テンプレート参照変数は、テンプレート内の要素の値を参照する変数を宣言する方法です。

テンプレート参照変数は、次を指すことができます。

- テンプレート内の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)

テンプレート参照変数を使用すると、テンプレートの1つの部分から同じテンプレートの別の部分の情報を取得できます。

### テンプレート参照変数を宣言する

テンプレート内の要素に、ハッシュ記号 (`#`) と変数名の後に続く属性を追加することで、変数を宣言できます。

```html

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

### テンプレート参照変数に値を代入する

Angularは、変数が宣言されている要素に基づいて、テンプレート変数に値を代入します。

変数をAngularコンポーネントに宣言した場合、変数はコンポーネントインスタンスを参照します。

```html

<my-datepicker #startDate />
```

変数を `<ng-template>` 要素に宣言した場合、変数はテンプレートを表すTemplateRefインスタンスを参照します。詳細については、[構造ディレクティブ](/guide/directives/structural-directives)の[Angularがアスタリスク、\*、構文を使用する方法](/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ディレクティブには、テンプレートでディレクティブを参照できる名前を定義する `exportAs` プロパティがある場合があります。

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

要素にテンプレート変数を宣言する場合、この `exportAs` 名を指定することで、変数にディレクティブインスタンスを代入できます。

```html

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

`exportAs` 名を指定していないディレクティブは参照できません。

### クエリでのテンプレート参照変数の使用

テンプレート参照変数は、同じテンプレートの別の部分から値を読み取るだけでなく、[コンポーネントとディレクティブのクエリ](/guide/components/queries)のために要素を「マーク」するためにも使用できます。

テンプレート内の特定の要素をクエリする場合は、その要素にテンプレート変数を宣言し、変数名に基づいて要素をクエリできます。

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

```typescript
@Component({
  /* ... */,
  template: `<input #description value="Original description">`,
})
export class AppComponent {
  // テンプレート変数名に基づいて入力要素をクエリします。
  @ViewChild('description') input: ElementRef | undefined;
}
```

クエリの詳細については、[クエリによる子の参照](/guide/components/queries)を参照してください。
# `@defer`を用いた遅延読み込み

遅延可能ビュー（別名`@defer`ブロック）は、ページの初期レンダリングに厳密に必要ないコードの読み込みを遅らせることで、アプリケーションの初期バンドルサイズを削減します。これにより、多くの場合、初期読み込みが高速化され、特にLargest Contentful Paint（LCP）とTime to First Byte（TTFB）に関してCore Web Vitals（CWV）が向上します。

この機能を使用するには、テンプレートのセクションを`@defer`ブロックで宣言的にラップします。

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

`@defer`ブロック内のコンポーネント、ディレクティブ、パイプのコードは、別のJavaScriptファイルに分割され、残りのテンプレートがレンダリングされた後、必要な場合にのみ読み込まれます。

遅延可能ビューは、さまざまなトリガーやプリフェッチオプションおよびプレースホルダー、読み込み、エラー状態の管理のためのサブブロックをサポートしています。

## どの依存関係が遅延されますか？

アプリケーションを読み込む際に、コンポーネント、ディレクティブ、パイプ、およびコンポーネントCSSスタイルを遅延させることができます。

`@defer`ブロック内の依存関係を遅延させるためには、2つの条件を満たす必要があります。

1. **スタンドアロンである必要があります。** スタンドアロンでない依存関係は遅延させることができず、`@defer`ブロック内にあっても、依然として先に読み込まれます。
1. **同じファイル内の`@defer`ブロックの外側では参照できません。** `@defer`ブロックの外側で参照される場合、またはViewChildクエリ内で参照される場合、依存関係は先に読み込まれます。

`@defer`ブロックで使用されるコンポーネント、ディレクティブ、パイプの_推移的_依存関係は、厳密にはスタンドアロンである必要はありません。推移的依存関係は依然として`NgModule`で宣言でき、遅延読み込みに参加できます。

Angularのコンパイラは、`@defer`ブロックで使用される各コンポーネント、ディレクティブ、およびパイプに対して[動的インポート](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)文を生成します。ブロックのメインコンテンツは、すべてのインポートが解決された後にレンダリングされます。Angularは、これらのインポートの特定の順序を保証しません。

## 遅延読み込みのさまざまなステージを管理する方法

`@defer`ブロックには、遅延読み込みプロセスにおけるさまざまなステージを適切に処理できるように、いくつかのサブブロックがあります。

### `@defer`

これは、遅延読み込みされるコンテンツのセクションを定義するプライマリブロックです。これは最初はレンダリングされません。遅延コンテンツは、指定された[トリガー](/guide/templates/defer#triggers)が発生するか、`when`条件が満たされたときに読み込まれてレンダリングされます。

デフォルトでは、`@defer`ブロックはブラウザの状態が[アイドル](/guide/templates/defer#idle)になるとトリガーされます。

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

### `@placeholder`でプレースホルダーコンテンツを表示する

デフォルトでは、`@defer`ブロックはトリガーされる前にコンテンツをレンダリングしません。

`@placeholder`は、`@defer`ブロックがトリガーされる前に表示するコンテンツを宣言するオプションのブロックです。

```html
@defer {
  <large-component />
} @placeholder {
  <p>プレースホルダーコンテンツ</p>
}
```

オプションですが、特定のトリガーでは、`@placeholder`または[テンプレート参照変数](/guide/templates/variables#template-reference-variables)のいずれかの存在が必要になる場合があります。詳細については、[トリガー](/guide/templates/defer#triggers)セクションを参照してください。

Angularは、読み込みが完了すると、プレースホルダーコンテンツをメインコンテンツに置き換えます。プレースホルダーセクションには、プレーンHTML、コンポーネント、ディレクティブ、パイプなど、あらゆるコンテンツを使用できます。_プレースホルダーブロックの依存関係は先に読み込まれます_。

`@placeholder`ブロックは、プレースホルダーコンテンツが最初にレンダリングされた後にこのプレースホルダーを表示する`minimum`時間を指定するオプションのパラメータを受け入れます。

```html
@defer {
  <large-component />
} @placeholder (minimum 500ms) {
  <p>プレースホルダーコンテンツ</p>
}
```

この`minimum`パラメータは、ミリ秒(ms)または秒(s)の時間増分で指定されます。このパラメータを使用して、遅延された依存関係がすばやく取得された場合にプレースホルダーコンテンツが高速でちらつくのを防ぐことができます。

### `@loading`で読み込みコンテンツを表示する

`@loading`ブロックは、遅延された依存関係が読み込まれている間に表示するコンテンツを宣言できるようにするオプションのブロックです。これは、読み込みがトリガーされると`@placeholder`ブロックを置き換えます。

```html
@defer {
  <large-component />
} @loading {
  <img alt="読み込み中..." src="loading.gif" />
} @placeholder {
  <p>プレースホルダーコンテンツ</p>
}
```

その依存関係は先に読み込まれます(`@placeholder`と同様)。

`@loading`ブロックは、遅延された依存関係がすばやく取得された場合に発生する可能性のあるコンテンツの高速なちらつきを防ぐために、2つのパラメータを受け入れます。

- `minimum` - このプレースホルダーを表示する最小時間
- `after` - 読み込みが開始されてから読み込みテンプレートを表示するまでの待機時間

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

両方のパラメータは、ミリ秒(ms)または秒(s)の時間増分で指定されます。さらに、両方のパラメータのタイマーは、読み込みがトリガーされた直後に開始されます。

### 遅延読み込みが失敗した場合に`@error`でエラー状態を表示する

`@error`ブロックは、遅延読み込みが失敗した場合に表示するオプションのブロックです。`@placeholder`や`@loading`と同様に、`@error`ブロックの依存関係は先に読み込まれます。

```html
@defer {
  <large-component />
} @error {
  <p>大型コンポーネントの読み込みに失敗しました。</p>
}
```

## トリガーを使用した遅延コンテンツ読み込みの制御

遅延コンテンツがいつ読み込まれて表示されるかを制御する**トリガー**を指定できます。

`@defer`ブロックがトリガーされると、プレースホルダーコンテンツが遅延読み込みされたコンテンツに置き換えられます。

複数のイベントトリガーを、セミコロン(`;`)で区切って定義でき、OR条件として評価されます。

トリガーには、`on`と`when`の2種類があります。

### `on`

`on`は、`@defer`ブロックがトリガーされる条件を指定します。

使用可能なトリガーは次のとおりです。

| トリガー                       | 説明                                                            |
| ----------------------------- | ---------------------------------------------------------------------- |
| [`idle`](#idle)               | ブラウザがアイドル状態になるとトリガーされます。                                     |
| [`viewport`](#viewport)       | 指定されたコンテンツがビューポートに入るとトリガーされます。                    |
| [`interaction`](#interaction) | ユーザーが指定された要素と対話するとトリガーされます。                |
| [`hover`](#hover)             | マウスが指定された領域にホバーするとトリガーされます。                     |
| [`immediate`](#immediate)     | 遅延されていないコンテンツのレンダリングが完了した直後にトリガーされます。 |
| [`timer`](#timer)             | 特定の期間後にトリガーされます。                                     |

#### `idle`

`idle`トリガーは、ブラウザがrequestIdleCallbackに基づいてアイドル状態に達すると、遅延コンテンツを読み込みます。これは、`@defer`ブロックのデフォルトの動作です。

```html

@defer {
  <large-cmp />
} @placeholder {
  <div>大型コンポーネントのプレースホルダー</div>
}
```

#### `viewport`

`viewport`トリガーは、[Intersection Observer API](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API)を使用して、指定されたコンテンツがビューポートに入ると、遅延コンテンツを読み込みます。観測されるコンテンツは、`@placeholder`コンテンツまたは明示的な要素参照にできます。

デフォルトでは、`@defer`は、プレースホルダーがビューポートに入っているかどうかを観察します。このように使用されるプレースホルダーは、単一のルート要素を持つ必要があります。

```html
@defer (on viewport) {
  <large-cmp />
} @placeholder {
  <div>大型コンポーネントのプレースホルダー</div>
}
```

または、`@defer`ブロックと同じテンプレート内に、ビューポートに入っているかどうかが監視される要素として[テンプレート参照変数](/guide/templates/variables)を指定できます。この変数は、ビューポートトリガーのパラメータとして渡されます。

```html
<div #greeting>こんにちは！</div>
@defer (on viewport(greeting)) {
  <greetings-cmp />
}
```

`IntersectionObserver`のオプションをカスタマイズしたい場合、`viewport`トリガーはオブジェクトリテラルの受け渡しをサポートしています。このリテラルは、`root`を除く`IntersectionObserver`の2番目のパラメータからすべてのプロパティをサポートしています。オブジェクトリテラル記法を使用する場合は、`trigger`プロパティを使用してトリガーを渡す必要があります。

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

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

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

#### `interaction`

`interaction`トリガーは、ユーザーが`click`または`keydown`イベントを通じて指定された要素と対話すると、遅延コンテンツを読み込みます。

デフォルトでは、プレースホルダーが対話要素として機能します。このように使用されるプレースホルダーは、単一のルート要素を持つ必要があります。

```html
@defer (on interaction) {
  <large-cmp />
} @placeholder {
  <div>大型コンポーネントのプレースホルダー</div>
}
```

または、`@defer`ブロックと同じテンプレート内に、対話が監視される要素として[テンプレート参照変数](/guide/templates/variables)を指定できます。この変数は、viewportトリガーのパラメータとして渡されます。

```html
<div #greeting>こんにちは！</div>
@defer (on interaction(greeting)) {
  <greetings-cmp />
}
```

#### `hover`

`hover`トリガーは、マウスが`mouseover`イベントと`focusin`イベントを通じてトリガーされた領域にホバーすると、遅延コンテンツを読み込みます。

```html
@defer (on hover) {
  <large-cmp />
} @placeholder {
  <div>大型コンポーネントのプレースホルダー</div>
}
```

```html
<div #greeting>こんにちは！</div>
@defer (on hover(greeting)) {
  <greetings-cmp />
}
```

#### `immediate`

`immediate`トリガーは、遅延コンテンツをすぐに読み込みます。これは、遅延ブロックは、他のすべての遅延されていないコンテンツのレンダリングが完了するとすぐに読み込まれることを意味します。

```html
@defer (on immediate) {
  <large-cmp />
} @placeholder {
  <div>大型コンポーネントのプレースホルダー</div>
}
```

#### `timer`

`timer`トリガーは、指定された期間後に遅延コンテンツを読み込みます。

```html
@defer (on timer(500ms)) {
  <large-cmp />
} @placeholder {
  <div>大型コンポーネントのプレースホルダー</div>
}
```

期間パラメータは、ミリ秒(`ms`)または秒(`s`)で指定する必要があります。

### `when`

`when`トリガーは、カスタムの条件式を受け取り、条件が真になったときに遅延コンテンツを読み込みます。

```html
@defer (when condition) {
  <large-cmp />
} @placeholder {
  <div>大型コンポーネントのプレースホルダー</div>
}
```

これは1回限りの操作です。`@defer`ブロックは、真になった後に偽の値に変更された場合、プレースホルダーに復帰しません。

## `prefetch`でデータをプリフェッチする

遅延コンテンツが表示される条件を指定することに加えて、**プリフェッチトリガー**をオプションで指定できます。このトリガーを使用すると、`@defer`ブロックに関連付けられたJavaScriptを、遅延コンテンツが表示される前に読み込むことができます。

プリフェッチを使用すると、ユーザーが実際に`@defer`ブロックを表示または対話する前に、ユーザーがすぐに対話する可能性のあるリソースのプリフェッチを開始します。これにより、リソースをより高速に利用できるようにするなど、より高度な動作が可能になります。

プリフェッチトリガーは、ブロックのメイントリガーと同様に指定できますが、`prefetch`キーワードを前に付けます。ブロックのメイントリガーとプリフェッチトリガーは、セミコロン(`;`)で区切られます。

次の例では、プリフェッチはブラウザがアイドル状態になると開始され、ブロックのコンテンツは、ユーザーがプレースホルダーと対話したときにのみレンダリングされます。

```html
@defer (on interaction; prefetch on idle) {
  <large-cmp />
} @placeholder {
  <div>大型コンポーネントのプレースホルダー</div>
}
```

## `@defer`ブロックのテスト

Angularは、`@defer`ブロックのテストと、テスト中のさまざまな状態のトリガーを簡素化するTestBed APIを提供しています。デフォルトでは、テスト内の`@defer`ブロックは、実際のアプリケーションで`@defer`ブロックが動作するのと同じように動作します。状態を手動でステップ実行する場合は、TestBedの構成で`@defer`ブロックの動作を`Manual`に切り替えることができます。

```typescript
it('さまざまな状態で`@defer`ブロックをレンダリングする', async () => {
  // 手動制御のために`@defer`ブロックの動作を"一時停止"状態から開始するように構成します。
  TestBed.configureTestingModule({deferBlockBehavior: DeferBlockBehavior.Manual});
  @Component({
    // ...
    template: `
      @defer {
        <large-component />
      } @placeholder {
        プレースホルダー
      } @loading {
        読み込み中...
      }
    `
  })
  class ComponentA {}
  // コンポーネントのfixtureを作成します。
  const componentFixture = TestBed.createComponent(ComponentA);
  // すべての`@defer`ブロックのfixtureを取得し、最初のブロックを取得します。
  const deferBlockFixture = (await componentFixture.getDeferBlocks())[0];
  // デフォルトでプレースホルダー状態をレンダリングします。
  expect(componentFixture.nativeElement.innerHTML).toContain('プレースホルダー');
  // 読み込み状態をレンダリングし、レンダリングされた出力を検証します。
  await deferBlockFixture.render(DeferBlockState.Loading);
  expect(componentFixture.nativeElement.innerHTML).toContain('読み込み中');
  // 最終状態をレンダリングし、出力を検証します。
  await deferBlockFixture.render(DeferBlockState.Complete);
  expect(componentFixture.nativeElement.innerHTML).toContain('large works!');
});
```

## `@defer`は`NgModule`と連携しますか？

`@defer`ブロックは、スタンドアロンコンポーネントと`NgModule`ベースのコンポーネント、ディレクティブ、パイプの両方と互換性があります。ただし、**スタンドアロンコンポーネント、ディレクティブ、パイプのみを遅延させることができます。**`NgModule`ベースの依存関係は遅延されず、即座に読み込まれたバンドルに含まれます。

## `@defer`ブロックとホットモジュールリロード(HMR)との互換性

ホットモジュール置換(HMR)がアクティブな場合、すべての`@defer`ブロックチャンクが即座にフェッチされ、設定されたトリガーを上書きします。標準的なトリガー動作を復元するには、`--no-hmr`フラグを使用してアプリケーションを提供し、HMRを無効にする必要があります。

## `@defer`は、サーバーサイドレンダリング(SSR)と静的サイト生成(SSG)とどのように連携しますか？

デフォルトでは、サーバー上でアプリケーションをレンダリングする際(SSRまたはSSGを使用する場合)、`@defer`ブロックは常にその`@placeholder`(プレースホルダーが指定されていない場合は何も表示されません)をレンダリングし、トリガーは呼び出されません。クライアント側では、`@placeholder`の内容が水和され、トリガーがアクティブになります。

サーバー上(SSRとSSGの両方)で`@defer`ブロックのメインコンテンツをレンダリングするには、[Incremental Hydration機能](/guide/incremental-hydration)を有効にして、必要なブロックの`hydrate`トリガーを構成できます。

## ビューを遅延させるためのベストプラクティス

### ネストされた`@defer`ブロックによるカスケード読み込みを避ける

ネストされた`@defer`ブロックがある場合は、同時に読み込まれないように、異なるトリガーを指定する必要があります。これにより、カスケードリクエストが発生し、ページ読み込みのパフォーマンスが低下する可能性があります。

### レイアウトのシフトを避ける

初期読み込み時にユーザーのビューポートに表示されるコンポーネントを遅延させることは避けてください。これを行うと、累積レイアウトシフト(CLS)が増加するため、Core Web Vitalsに悪影響を与える可能性があります。

必要な場合、初期ページレンダリング中にコンテンツが読み込まれる`immediate`、`timer`、`viewport`、カスタム`when`トリガーは避けてください。

### アクセシビリティに配慮する {#keep-accessibility-in-mind}

`@defer`ブロックを使用する場合は、スクリーンリーダーなどの支援技術を使用するユーザーへの影響を考慮してください。
遅延セクションにフォーカスしているスクリーンリーダーは、最初はプレースホルダーまたは読み込み中のコンテンツを読み上げますが、遅延コンテンツが読み込まれたときに変更を通知しない場合があります。

遅延コンテンツの変更がスクリーンリーダーに通知されるようにするには、`@defer`ブロックをライブリージョンを持つ要素でラップできます。

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

これにより、遷移（プレースホルダー → 読み込み中 → コンテンツ/エラー）が発生したときに、変更がユーザーに通知されるようになります。
# 式構文

Angular式はJavaScriptに基づいていますが、いくつかの重要な点で異なります。このガイドでは、Angular式と標準JavaScriptの類似点と相違点を説明します。

## 値リテラル

Angularは、[リテラル値](https://developer.mozilla.org/en-US/docs/Glossary/Literal)のサブセットをJavaScriptからサポートしています。

### サポートされる値リテラル

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

### サポートされていない値リテラル

| Literal type | Example values |
| ------------ | -------------- |
| BigInt       | `1n`           |

## グローバル

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)

その他のJavaScriptグローバルはサポートされていません。一般的なJavaScriptグローバルには、`Number`、`Boolean`、`NaN`、`Infinity`、`parseInt`などがあります。

## ローカル変数

Angularは、特定のコンテキストで式に使用できる特別なローカル変数を自動的に用意します。これらの特別な変数は、常にドル記号文字（`$`）で始まります。

たとえば、`@for`ブロックはループに関する情報に対応する複数のローカル変数（`$index`など）を提供します。

## どのような演算子がサポートされていますか？

### サポートされる演算子

Angularは、標準JavaScriptの次の演算子をサポートしています。

| 演算子                      | 例(複数)                                     |
| ----------------------------- | ---------------------------------------------- |
| 加算/連結                    | `1 + 2`                                        |
| 減算                        | `52 - 3`                                       |
| 乗算                        | `41 * 6`                                       |
| 除算                        | `20 / 4`                                       |
| 余り（剰余）                 | `17 % 5`                                       |
| Exponentiation              | `10 ** 3`                                      |
| 括弧                        | `9 * (8 + 4)`                                  |
| 条件式（三項演算子）          | `a > b ? true : false`                         |
| 論理積                      | `&&`                                           |
| 論理和                      | `\|\|`                                         |
| 論理否定                    | `!`                                            |
| Nullish Coalescing          | `possiblyNullValue ?? 'default'`               |
| 比較演算子                  | `<`, `<=`, `>`, `>=`, `==`, `===`, `!==`, `!=` |
| Unary Negation              | `-x`                                           |
| Unary Plus                  | `+y`                                           |
| Property Accessor           | `person['name']`                               |
| 代入                        | `a = b`                                        |
| 加算代入                    | `a += b`                                       |
| 減算代入                    | `a -= b`                                       |
| 乗算代入                    | `a *= b`                                       |
| 除算代入                    | `a /= b`                                       |
| 余り代入                    | `a %= b`                                       |
| Exponentiation Assignment   | `a **= b`                                      |
| 論理積代入                  | `a &&= b`                                      |
| 論理和代入                  | `a \|\|= b`                                    |
| Nullish Coalescing Assignment | `a ??= b`                                      |

Angular式は、さらに次の非標準の演算子もサポートしています。

| 演算子                        | 例(複数)                     |
| ------------------------------- | ------------------------------ |
| [パイプ](/guide/templates/pipes)  | `{{ total \| currency }}`      |
| オプショナルチェーン\*             | `someObj.someProp?.nestedProp` |
| 非nullアサーション（TypeScript） | `someObj!.someProp`            |

NOTE: オプショナルチェーンは、標準JavaScriptバージョンとは異なる動作をします。Angularのオプショナルチェーン演算子の左辺が`null`または`undefined`の場合、`undefined`ではなく`null`を返します。

### サポートされていない演算子

| 演算子              | 例(複数)                        |
| --------------------- | --------------------------------- |
| すべてのビット演算子 | `&`, `&=`, `~`, `\|=`, `^=`, etc. |
| オブジェクトのデストラクタリング | `const { name } = person`         |
| 配列のデストラクタリング   | `const [firstItem] = items`       |
| カンマ演算子        | `x = (x++, x)`                    |
| instanceof            | `car instanceof Automobile`       |
| new                   | `new Car()`                       |

## 式の字句コンテキスト

Angular式は、コンポーネントクラスのコンテキストと、関連する[テンプレート変数](/guide/templates/variables)、ローカル変数、およびグローバル変数のコンテキストで評価されます。

コンポーネントクラスのメンバーを参照する場合、`this`は常に暗黙的に指定されます。ただし、テンプレートが同じ名前の[テンプレート変数](guide/templates/variables)を宣言している場合、その変数はメンバーをシャドウします。このようなクラスメンバーは、明示的に`this.`を使用することで明確に参照できます。これは、クラスメンバーをシャドウする`@let`宣言を作成する場合に便利です。たとえば、シグナルの絞り込み目的で使用できます。

## 宣言

一般的に、Angular式では宣言はサポートされていません。これには、以下が含まれますが、これらに限定されません。

| 宣言          | 例(複数)                                  |
| --------------- | ------------------------------------------- |
| 変数            | `let label = 'abc'`, `const item = 'apple'` |
| 関数            | `function myCustomFunction() { }`           |
| アロー関数       | `() => { }`                                 |
| クラス          | `class Rectangle { }`                       |

# イベントリスナー文

イベントハンドラーは、**式**ではなく**文**です。Angular式と同じ構文をすべてサポートしていますが、2つの重要な違いがあります。

1. 文は**代入演算子**をサポートします（ただし、分割代入はサポートされていません）。
1. 文は**パイプをサポートしていません**
# 属性ディレクティブ

属性ディレクティブを使用して、DOM要素とAngularコンポーネントの外観や動作を変更します。

## 属性ディレクティブの作成

このセクションでは、ホスト要素の背景色を黄色に設定するハイライトディレクティブを作成する方法について説明します。

1. ディレクティブを作成するには、CLIコマンド[`ng generate directive`](tools/cli/schematics)を使用します。

```shell
ng generate directive highlight
   ```

CLIは`src/app/highlight.directive.ts`と、対応するテストファイル`src/app/highlight.directive.spec.ts`を作成します。

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

`@Directive()`デコレーターの構成プロパティは、ディレクティブのCSS属性セレクター`[appHighlight]`を指定します。

1. `@angular/core`から`ElementRef`をインポートします。
   `ElementRef`は、`nativeElement`プロパティを通じてホストDOM要素への直接アクセスを提供します。

1. ディレクティブの`constructor()`に`ElementRef`を追加して、`appHighlight`を適用する要素であるホストDOM要素への参照を[注入](guide/di)します。

1. 背景を黄色に設定するロジックを`HighlightDirective`クラスに追加します。

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

HELPFUL: ディレクティブは_ネームスペース_をサポートしていません。

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

## 属性ディレクティブの適用

`HighlightDirective`を使用するには、ディレクティブを属性として持つ`<p>`要素をHTMLテンプレートに追加します。

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

Angularは`HighlightDirective`クラスのインスタンスを作成し、`<p>`要素への参照をディレクティブのコンストラクターに注入します。これにより、`<p>`要素の背景スタイルが黄色に設定されます。

## ユーザーイベントの処理

このセクションでは、ユーザーが要素内または要素外にマウスを移動したときに検出する方法と、ハイライトカラーを設定またはクリアして応答する方法について説明します。

1. `@Directive()`デコレーターの`host`プロパティを使用してホストイベントバインディングを構成します。

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

1. 2つのイベントハンドラーメソッドを追加し、`host`プロパティを介してホスト要素イベントをそれらにマッピングします。

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

属性ディレクティブをホストするDOM要素（この場合は`<p>`）のイベントを購読するには、ディレクティブの[`host`プロパティ](guide/components/host-elements#binding-to-the-host-element)でイベントリスナーを構成します。

HELPFUL: ハンドラーは、ホストDOM要素`el`に色を設定するヘルパーメソッド`highlight()`に委任します。

完全なディレクティブは次のとおりです。

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

ポインタが段落要素の上にホバーすると背景色が表示され、ポインタが外れると背景色が消えます。

## 属性ディレクティブに値を渡す

このセクションでは、`HighlightDirective`を適用するときにハイライトカラーを設定する方法について説明します。

1. `highlight.directive.ts`で、`@angular/core`から`input`をインポートします。

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

1. `appHighlight` `input`プロパティを追加します。

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

`input()`関数は、ディレクティブの`appHighlight`プロパティをバインディングで使用できるようにするメタデータをクラスに追加します。

1. `app.component.ts`で、`AppComponent`に`color`プロパティを追加します。

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

1. ディレクティブと色を同時に適用するには、`appHighlight`ディレクティブセレクターを使用してプロパティバインディングを使用し、それを`color`に設定します。

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

`[appHighlight]`属性バインディングは次の2つのタスクを実行します。
   - `<p>`要素にハイライトディレクティブを適用する
   - プロパティバインディングを使用してディレクティブのハイライトカラーを設定する

### ユーザー入力を使用して値を設定する

このセクションでは、カラー選択を`appHighlight`ディレクティブにバインドするラジオボタンを追加する方法について説明します。

1. 色を選択するためのマークアップを`app.component.html`に追加します。

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

1. `AppComponent.color`を修正して、初期値を持たないようにします。

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

1. `highlight.directive.ts`で、`onMouseEnter`メソッドを修正して、最初に`appHighlight`でハイライトしようとします。`appHighlight`が`undefined`の場合は`red`にフォールバックします。

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

4. アプリケーションを起動して、ユーザーがラジオボタンで色を選択できることを確認します。

## 2番目のプロパティにバインドする

このセクションでは、開発者がデフォルトカラーを設定できるようにアプリケーションを構成する方法について説明します。

1. `HighlightDirective`に`defaultColor`という名前の2番目の`input()`プロパティを追加します。

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

2. ディレクティブの`onMouseEnter`を修正して、最初に`appHighlight`でハイライトしようとします。次に`defaultColor`でハイライトしようとします。両方のプロパティが`undefined`の場合は`red`にフォールバックします。

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

3. `AppComponent.color`にバインドし、デフォルトカラーとして「violet」を使用するには、次のHTMLを追加します。
   この場合、`defaultColor`バインディングは、静的であるため、角括弧`[]`を使用しません。

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

コンポーネントと同様に、ホスト要素に複数のディレクティブプロパティバインディングを追加できます。

デフォルトカラーは、デフォルトカラーバインディングがない場合は赤です。
ユーザーが色を選択すると、選択した色がアクティブなハイライトカラーになります。

## `NgNonBindable`を使用してAngularの処理を無効にする

ブラウザでの式評価を防ぐには、ホスト要素に`ngNonBindable`を追加します。
`ngNonBindable`は、テンプレート内の補間、ディレクティブ、バインディングを無効にします。

次の例では、式`{{ 1 + 1 }}`はコードエディタと同じようにレンダリングされ、`2`は表示されません。

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

`ngNonBindable`を要素に適用すると、その要素の子要素のバインディングが停止します。
ただし、`ngNonBindable`は、`ngNonBindable`を適用した要素に対しては、ディレクティブを動作させます。
次の例では、`appHighlight`ディレクティブはアクティブですが、Angularは式`{{ 1 + 1 }}`を評価しません。

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

`ngNonBindable`を親要素に適用すると、Angularは要素の子要素に対して、プロパティバインディングやイベントバインディングなどあらゆる種類の補間とバインディングを無効にします。# 構造ディレクティブ

構造ディレクティブは、`<ng-template>`要素に適用され、その`<ng-template>`の内容を条件付きまたは繰り返しでレンダリングするディレクティブです。

## 使用例

このガイドでは、指定されたデータソースからデータを取得し、そのデータが利用可能になったときにテンプレートをレンダリングする構造ディレクティブを作成します。このディレクティブは、SQLキーワード`SELECT`にちなんで`SelectDirective`と呼ばれ、属性セレクター`[select]`と一致させます。

`SelectDirective`には、使用するデータソースの名前を指定する入力があり、`selectFrom`と呼びます。この入力の`select`プレフィックスは、[省略記法](#structural-directive-shorthand)にとって重要です。ディレクティブは、選択されたデータを提供するテンプレートコンテキストを使用して、`<ng-template>`をインスタンス化します。

以下は、`<ng-template>`に直接このディレクティブを適用した例です。

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

構造ディレクティブは、データが利用可能になるまで待機してから、`<ng-template>`をレンダリングできます。

HELPFUL: Angularの`<ng-template>`要素は、デフォルトでは何もレンダリングしないテンプレートを定義します。構造ディレクティブを適用せずに`<ng-template>`で要素をラップした場合、それらの要素はレンダリングされません。

詳細については、[ng-template API](api/core/ng-template)のドキュメントを参照してください。

## 構造ディレクティブの省略記法 {#structural-directive-shorthand}

Angularは、構造ディレクティブの省略記法をサポートしており、`<ng-template>`要素を明示的に記述する必要がなくなります。

構造ディレクティブは、アスタリスク(`*`)をディレクティブ属性セレクターの前に付けることで、要素に直接適用できます。たとえば、`*select`のようにします。Angularは、構造ディレクティブの前にあるアスタリスクを、ディレクティブをホストし、要素とその子孫を囲む`<ng-template>`に変換します。

以下は、`SelectDirective`を使用した例です。

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

この例は、構造ディレクティブの省略記法の柔軟性を示しており、これはマイクロシンタックスと呼ばれることもあります。

このように使用した場合、構造ディレクティブとそのバインディングのみが`<ng-template>`に適用されます。`<p>`タグの他の属性やバインディングはそのまま残されます。たとえば、次の2つの形式は同等です。

```html

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

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

省略記法は、一連の規則によって展開されます。以下に、より詳細な[文法](#structural-directive-syntax-reference)が定義されていますが、上記の例では、この変換を次のように説明できます。

`*select`式の最初の部分は`let data`で、テンプレート変数`data`を宣言しています。割り当てが続かないため、テンプレート変数はテンプレートコンテキストプロパティ`$implicit`にバインドされます。

2番目の構文は、キーと式のペアである`from source`です。`from`はバインディングキーで、`source`は通常のテンプレート式です。バインディングキーは、PascalCaseに変換し、構造ディレクティブセレクターを先頭に付けることで、プロパティにマップされます。`from`キーは`selectFrom`にマップされ、次に式`source`にバインドされます。そのため、多くの構造ディレクティブは、すべて構造ディレクティブのセレクターで始まるプレフィックスを持つ入力を持つことになります。

## 要素あたりの構造ディレクティブは1つのみ {#one-structural-directive-per-element}

省略記法を使用する場合、要素ごとに適用できる構造ディレクティブは1つだけです。これは、ディレクティブが展開される`<ng-template>`要素が1つしかないためです。複数のディレクティブには、複数の子ネストされた`<ng-template>`が必要であり、どのディレクティブを最初にすべきかは明確ではありません。`<ng-container>`は、同じ物理的なDOM要素またはコンポーネントに複数の構造ディレクティブを適用する必要がある場合に、ラッパーレイヤーを作成するために使用できます。これにより、ユーザーはネストされた構造を定義できます。

## 構造ディレクティブの作成

このセクションでは、`SelectDirective`の作成について説明します。

<docs-workflow>
<docs-step title="ディレクティブを生成">
Angular CLIを使用して、次のコマンドを実行します。ここで、`select`はディレクティブの名前です。

```shell
ng generate directive select
```

Angularは、ディレクティブクラスを作成し、テンプレートでディレクティブを識別するCSSセレクター`[select]`を指定します。
</docs-step>
<docs-step title="ディレクティブを構造化">
`TemplateRef`と`ViewContainerRef`をインポートし、ディレクティブ内で`TemplateRef`と`ViewContainerRef`をプライベートプロパティとしてインジェクトします。

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

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

</docs-step>
<docs-step title="'selectFrom'入力を追加">
`selectFrom` `input()`プロパティを追加します。

```ts
export class SelectDirective {
  // ...
  selectFrom = input.required<DataSource>();
}
```

</docs-step>
<docs-step title="ビジネスロジックを追加">
`SelectDirective`が、入力を持つ構造ディレクティブとしてスキャフォールディングされたので、データを取得し、テンプレートをデータと共にレンダリングするロジックを追加できます。

```ts
export class SelectDirective {
  // ...
  async ngOnInit() {
    const data = await this.selectFrom.load();
    this.viewContainerRef.createEmbeddedView(this.templateRef, {
      // テンプレートコンテキストに`$implicit`キーでデータを含むオブジェクトが含まれるように、
      // 埋め込みビューを作成します。
      $implicit: data,
    });
  }
}
```

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

これで`SelectDirective`は起動して実行できるようになりました。次のステップとして、[テンプレートタイプチェックのサポートを追加](#typing-the-directives-context)できます。

## 構造ディレクティブの構文リファレンス {#structural-directive-syntax-reference}

独自の構造ディレクティブを作成する際は、次の構文を使用します。

```ts
{hideCopy}
_: prefix = "( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )_";
```

次のパターンは、構造ディレクティブ文法の各部分を説明しています。

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

### Angularが省略記法をどのように変換するか

Angularは、構造ディレクティブの省略記法を次の通常のバインディング構文に変換します。

### 省略記法の例

次の表は、省略記法の例を示しています。

| 省略記法                                                             | 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">`                                                               |

## カスタムディレクティブのテンプレートタイプチェックを改善する

カスタムディレクティブのテンプレートタイプチェックを改善するには、ディレクティブ定義にテンプレートガードを追加します。
これらのガードは、Angularテンプレートタイプチェッカーがコンパイル時にテンプレート内の間違いを見つけるのに役立ち、ランタイムエラーを回避できます。
2種類のガードが可能です。

- `ngTemplateGuard_(input)`を使用すると、特定の入力の型に基づいて入力式をどのように絞り込むかを制御できます。
- `ngTemplateContextGuard`は、ディレクティブ自体の型に基づいて、テンプレートのコンテキストオブジェクトの型を判断するために使用されます。

このセクションでは、両方の種類のガードの例を示します。
詳細については、[テンプレートタイプチェック](tools/cli/template-typecheck 'テンプレートタイプチェックガイド')を参照してください。

### テンプレートガードによるタイプの絞り込み

テンプレート内の構造ディレクティブは、そのテンプレートがランタイムにレンダリングされるかどうかを制御します。一部の構造ディレクティブは、入力式の型に基づいてタイプの絞り込みを実行したいと考えています。

入力ガードで可能な絞り込みは2つあります。

- TypeScriptの型アサーション関数に基づいて入力式を絞り込む。
- 入力式の真偽値に基づいて入力式を絞り込む。

型アサーション関数を定義して入力式を絞り込むには、次の手順を実行します。

```ts
// このディレクティブは、アクターがユーザーの場合にのみテンプレートをレンダリングします。
// テンプレート内では、`actor`式の型が`User`に絞り込まれていることを
// アサートしたいと考えています。
@Directive(...)
class ActorIsUser {
  actor = input<User | Robot>();

static ngTemplateGuard_actor(dir: ActorIsUser, expr: User | Robot): expr is User {
    // 実際にはreturn文は不要ですが、
    // TypeScriptエラーを防ぐために含めています。
    return true;
  }
}
```

タイプチェックは、`ngTemplateGuard_actor`が入力にバインドされた式に対してアサートされたかのように、テンプレート内で動作します。

一部のディレクティブは、入力の真偽値が真の場合にのみテンプレートをレンダリングします。真偽値の完全な意味を型アサーション関数で捉えることはできないため、代わりに`'binding'`というリテラル型を使用して、テンプレートタイプチェッカーに、バインディング式自体をガードとして使用する必要があることを示すことができます。

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

static ngTemplateGuard_condition: 'binding';
}
```

テンプレートタイプチェッカーは、`condition`にバインドされた式がテンプレート内で真であるとアサートされたかのように動作します。

### ディレクティブのコンテキストの型付け {#typing-the-directives-context}

構造ディレクティブがインスタンス化されたテンプレートにコンテキストを提供する場合、ディレクティブ自体型に基づいてコンテキストの型を導き出すことができる静的`ngTemplateContextGuard`型アサーション関数を提供することで、テンプレート内でそのコンテキストを正しく型付けできます。これは、ディレクティブの型がジェネリックである場合に役立ちます。

上記の`SelectDirective`では、データソースがジェネリックであっても、`ngTemplateContextGuard`を実装してデータ型を正しく指定できます。

```ts
// テンプレートコンテキストのインターフェースを宣言します。
export interface SelectTemplateContext<T> {
  $implicit: T;
}

@Directive(...)
export class SelectDirective<T> {
  // ディレクティブのジェネリック型`T`は、
  // 入力に渡される`DataSource`型から推測されます。
  selectFrom = input.required<DataSource<T>>();

// ジェネリック型のディレクティブを使用して、コンテキストの型を絞り込みます。
  static ngTemplateContextGuard<T>(dir: SelectDirective<T>, ctx: any): ctx is SelectTemplateContext<T> {
    // 前述のように、ガードの本体は実行時に使用されず、
    // TypeScriptエラーを防ぐためだけに含まれています。
    return true;
  }
}
```
# ディレクティブ合成API

Angularディレクティブは、再利用可能な動作をカプセル化するすばらしい方法を提供します。
ディレクティブは、属性、CSSクラス、およびイベントリスナーを要素に適用できます。

*ディレクティブ合成API* を使用すると、
コンポーネントのTypeScriptクラスの*内部*からコンポーネントのホスト要素にディレクティブを適用できます。

## コンポーネントにディレクティブを追加する

コンポーネントにディレクティブを適用するには、コンポーネントのデコレーターに `hostDirectives` プロパティを追加します。
このようなディレクティブを*ホストディレクティブ*と呼びます。

この例では、`MenuBehavior` ディレクティブを `AdminMenu` のホスト要素に適用します。
これは、テンプレートの `<admin-menu>` 要素に `MenuBehavior` を適用するのと同じように機能します。

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

フレームワークがコンポーネントをレンダリングすると、Angularは各ホストディレクティブのインスタンスも作成します。
ディレクティブのホストバインディングは、コンポーネントのホスト要素に適用されます。
デフォルトでは、ホストディレクティブの入力と出力は、コンポーネントの公開APIの一部として公開されません。
詳細については、以下の[入力と出力を含める](#including-inputs-and-outputs)を参照してください。

**Angularはコンパイル時に静的にホストディレクティブを適用します。** 
ランタイム時には動的にディレクティブを追加できません。

**`hostDirectives` で使用されるディレクティブは `standalone: false` を指定できません。**

**Angularは `hostDirectives` プロパティで適用されたディレクティブの `selector` を無視します。**

## 入力と出力を含める {#including-inputs-and-outputs}

コンポーネントに `hostDirectives` を適用すると、
ホストディレクティブからの入力と出力は、デフォルトではコンポーネントのAPIには含まれません。
`hostDirectives` のエントリを拡張することで、コンポーネントのAPIに入力と出力を明示的に含めることができます。

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

入力と出力を明示的に指定することで、`hostDirective` を持つコンポーネントのコンシューマーは
テンプレートでそれらにバインドできます。

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

さらに、`hostDirective` から入力と出力をエイリアスして、
コンポーネントのAPIをカスタマイズできます。

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

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

## 別のディレクティブにディレクティブを追加する

コンポーネントに加えて、他のディレクティブにも `hostDirectives` を追加できます。
これにより、複数の動作を推移的に集約できます。

次の例では、`Menu` と `Tooltip` の2つのディレクティブを定義しています。
次に、`MenuWithTooltip` でこれらの2つのディレクティブの動作を構成します。
最後に、`SpecializedMenuWithTooltip` に `MenuWithTooltip` を適用します。

`SpecializedMenuWithTooltip` がテンプレートで使用されると、
`Menu`、`Tooltip`、`MenuWithTooltip` のすべてをインスタンス化します。
これらのディレクティブの各ホストバインディングは、`SpecializedMenuWithTooltip` のホスト要素に適用されます。

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

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

// MenuWithTooltip は、他の複数のディレクティブから動作を構成できます
@Directive({
  hostDirectives: [Tooltip, Menu],
})
export class MenuWithTooltip { }

// CustomWidget は、すでに構成されている MenuWithTooltip からの動作を適用できます
@Directive({
  hostDirectives: [MenuWithTooltip],
})
export class SpecializedMenuWithTooltip { }
```

## ホストディレクティブのセマンティクス

### ディレクティブの実行順序

ホストディレクティブは、テンプレートで直接使用されるコンポーネントやディレクティブと同じライフサイクルを経ます。
ただし、ホストディレクティブは常に適用されているコンポーネントまたはディレクティブの*前*に、コンストラクターやライフサイクルフックおよびバインディングを実行します。

次の例は、ホストディレクティブの最小限の使用を示しています。

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

ここでの実行順序は次のとおりです。

1. `MenuBehavior` がインスタンス化される
2. `AdminMenu` がインスタンス化される
3. `MenuBehavior` が入力を受信する (`ngOnInit`)
4. `AdminMenu` が入力を受信する (`ngOnInit`)
5. `MenuBehavior` がホストバインディングを適用する
6. `AdminMenu` がホストバインディングを適用する

この動作順序により、`hostDirectives` を持つコンポーネントは、
ホストディレクティブで指定されたホストバインディングをオーバーライドできます。

この動作順序は次の例のように、
ホストディレクティブのネストされたチェーンにも適用されます。

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

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

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

上記の例では、実行順序は次のとおりです。

1. `Tooltip` がインスタンス化される
2. `CustomTooltip` がインスタンス化される
3. `EvenMoreCustomTooltip` がインスタンス化される
4. `Tooltip` が入力を受信する (`ngOnInit`)
5. `CustomTooltip` が入力を受信する (`ngOnInit`)
6. `EvenMoreCustomTooltip` が入力を受信する (`ngOnInit`)
7. `Tooltip` がホストバインディングを適用する
8. `CustomTooltip` がホストバインディングを適用する
9. `EvenMoreCustomTooltip` がホストバインディングを適用する

### 依存性の注入

`hostDirectives` を指定するコンポーネントまたはディレクティブは、
それらのホストディレクティブのインスタンスを注入でき、その逆も可能です。

ホストディレクティブをコンポーネントに適用する場合、
コンポーネントとホストディレクティブの両方でプロバイダーを定義できます。

`hostDirectives` を持つコンポーネントと、それらのホストディレクティブの両方が同じ注入トークンを提供する場合、
`hostDirectives` を持つクラスで定義されたプロバイダーは
ホストディレクティブで定義されたプロバイダーよりも優先されます。
# NgOptimizedImage の使用開始

`NgOptimizedImage` ディレクティブは、画像の読み込みにおけるパフォーマンスのベストプラクティスを簡単に採用できるようにします。

このディレクティブは、[Largest Contentful Paint (LCP)](http://web.dev/lcp) 画像の読み込みが以下の方法で優先されるようにします。

- `<img>` タグに `fetchpriority` 属性を自動的に設定する
- デフォルトで他の画像を遅延読み込みする
- ドキュメントのヘッドにプリコネクトリンクタグを自動的に生成する
- `srcset` 属性を自動的に生成する
- アプリケーションがSSRを使用している場合、[プリロードヒント](https://developer.mozilla.org/docs/Web/HTML/Link_types/preload)を生成する

LCP画像の読み込みを最適化することに加えて、`NgOptimizedImage` は以下のようないくつかの画像のベストプラクティスを強制します。

- [画像最適化を適用するための画像CDNのURLの使用](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options)
- `width` と `height` を要求することでレイアウトシフトを防ぐ
- `width` または `height` が誤って設定されている場合に警告する
- 画像がレンダリング時に視覚的に歪む場合に警告する

CSSで背景画像を使用している場合は、[こちらから開始してください](#how-to-migrate-your-background-image)。

**NOTE: `NgOptimizedImage` ディレクティブはAngularバージョン15で安定版機能となりましたが、バックポートされており、バージョン13.4.0および14.3.0でも安定版機能として利用可能です。**

## はじめに {#getting-started}

<docs-workflow>
<docs-step title="`NgOptimizedImage`ディレクティブのインポート">
`NgOptimizedImage`ディレクティブを`@angular/common`からインポートします。

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

そして、スタンドアロンコンポーネントまたはNgModuleの`imports`配列に含めます。

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

</docs-step>
<docs-step title="(オプション)ローダーの設定">
NgOptimizedImageを使用するために画像ローダーは**必須ではありません**が、画像CDNと組み合わせて使用すると、画像の自動`srcset`を含む強力なパフォーマンス機能が有効になります。

ローダーの設定に関する簡単なガイドは、このページの最後にある[画像ローダーの設定](#configuring-an-image-loader-for-ngoptimizedimage)セクションにあります。
</docs-step>
<docs-step title="ディレクティブの有効化">
`NgOptimizedImage`ディレクティブを有効にするには、画像の`src`属性を`ngSrc`に置き換えます。

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

[組み込みのサードパーティローダー](#built-in-loaders)を使用している場合は、`src`からベースURLパスを省略してください。これはローダーによって自動的に前置されます。
</docs-step>
<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 for Web Vitals](https://web.dev/css-web-vitals/#images-and-largest-contentful-paint-lcp)を参照してください。
</docs-step>
<docs-step title="幅と高さを含める">
[画像関連のレイアウトシフト](https://web.dev/css-web-vitals/#images-and-layout-shifts)を防ぐため、NgOptimizedImageでは次のように画像の高さと幅を指定する必要があります。

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

**レスポンシブ画像**（ビューポートに対して拡大縮小するようにスタイル設定された画像）の場合、`width`および`height`属性は画像ファイルの固有のサイズである必要があります。レスポンシブ画像の場合、[`sizes`の値を設定する](#responsive-images)ことも重要です。

**固定サイズ画像**の場合、`width`および`height`属性は画像の目的のレンダリングサイズを反映する必要があります。これらの属性のアスペクト比は、常に画像の固有のアスペクト比と一致する必要があります。

NOTE: 画像のサイズが不明な場合は、以下で説明するように、親コンテナのサイズを継承するために「フィルモード」の使用を検討してください。
</docs-step>
</docs-workflow>

## `fill`モードの使用 {#using-fill-mode}

画像をコンテナ要素にフィットさせたい場合、`fill`属性を使用できます。これは、「背景画像」のような動作を実現したい場合にしばしば役立ちます。また、画像の正確な幅と高さが不明な場合でも、既知のサイズを持つ親コンテナに画像をフィットさせたい場合に役立ちます（下記の「object-fit」を参照）。

画像に`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)を使用して画像をスタイル設定し、コンテナ要素内での位置を調整できます。

IMPORTANT:「fill」画像が適切にレンダリングされるには、その親要素は`position: "relative"`、`position: "fixed"`、または`position: "absolute"`でスタイル設定されている**必要があります**。

## 背景画像の移行方法 {#how-to-migrate-your-background-image}

`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`属性を追加します。

背景画像がコンテナをどのように埋めるかは、[フィルモードの使用](#using-fill-mode)セクションで説明されているように調整できます。

## プレースホルダーの使用 {#using-placeholders}

### 自動プレースホルダー {#automatic-placeholders}

NgOptimizedImageは、CDNまたは画像ホストが自動画像リサイズを提供している場合、画像の低解像度の自動プレースホルダーを表示できます。この機能を利用するには、画像に`placeholder`属性を追加します。

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

この属性を追加すると、指定された画像ローダーを使用して、画像の2番目の小さいバージョンが自動的にリクエストされます。この小さい画像は、画像が読み込まれる間、CSSのぼかしを伴う`background-image`スタイルとして適用されます。画像ローダーが提供されていない場合、プレースホルダー画像は生成されず、エラーがスローされます。

生成されるプレースホルダーのデフォルトサイズは幅30pxです。このサイズは、以下に示すように`IMAGE_CONFIG`プロバイダーでピクセル値を指定することで変更できます。

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      placeholderResolution: 40
    }
  },
],
```

ぼかされたプレースホルダーの周りにシャープなエッジが必要な場合は、画像を`overflow: hidden`スタイルを持つコンテナ`<div>`でラップできます。`<div>`が画像と同じサイズである限り（例えば`width: fit-content`スタイルを使用するなど）、プレースホルダーの「ぼやけたエッジ」は非表示になります。

### データURLプレースホルダー {#data-url-placeholders}

画像ローダーなしで、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バンドルのサイズを増やし、ページロードを遅くします。画像ローダーを使用できない場合、Angularチームはbase64プレースホルダー画像を4KB未満に保ち、重要な画像にのみ使用することを推奨しています。プレースホルダーの寸法を小さくすることに加えて、画像形式や画像を保存する際に使用するパラメーターの変更も検討してください。非常に低い解像度では、これらのパラメーターがファイルサイズに大きな影響を与える可能性があります。

### ぼかしなしプレースホルダー {#non-blurred-placeholders}

デフォルトでは、NgOptimizedImageは画像プレースホルダーにCSSのぼかし効果を適用します。ぼかしなしでプレースホルダーをレンダリングするには、`blur`プロパティをfalseに設定したオブジェクトを含む`placeholderConfig`引数を指定します。例:

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder [placeholderConfig]="{blur: false}" />
```

## 画像のスタイル調整 {#adjusting-image-styling}

画像のスタイル設定によっては、`width`属性と`height`属性を追加すると画像の表示が異なる場合があります。`NgOptimizedImage`は、画像のスタイル設定によって画像が歪んだアスペクト比で表示される場合に警告します。

通常、画像のスタイルに`height: auto`または`width: auto`を追加することでこれを修正できます。詳細については、[`<img>`タグに関するweb.devの記事](https://web.dev/patterns/web-vitals-patterns/images/img-tag)を参照してください。

画像の`width`属性と`height`属性が、CSSで画像を希望どおりにサイズ調整するのを妨げている場合は、代わりに`fill`モードを使用し、画像の親要素をスタイル設定することを検討してください。

## パフォーマンス機能 {#performance-features}

NgOptimizedImageには、アプリケーションの読み込みパフォーマンスを向上させるために設計された多くの機能が含まれています。これらの機能は本セクションで説明します。

### リソースヒントの追加 {#add-resource-hints}

画像オリジンに対する[`preconnect`リソースヒント](https://web.dev/preconnect-and-dns-prefetch)は、LCP画像が可能な限り迅速に読み込まれることを保証します。

プリコネクトリンクは、[ローダー](#configuring-an-image-loader-for-ngoptimizedimage)への引数として提供されたドメインに対して自動的に生成されます。画像オリジンを自動的に識別できない場合、またはLCP画像に対してプリコネクトリンクが検出されない場合、`NgOptimizedImage`は開発中に警告を表示します。その場合、`index.html`にリソースヒントを手動で追加する必要があります。ドキュメントの`<head>`内に、以下に示すように`rel="preconnect"`を持つ`link`タグを追加します。

```html
<link rel="preconnect" href="https://my.cdn.origin" />
```

プリコネクト警告を無効にするには、`PRECONNECT_CHECK_BLOCKLIST`トークンをインジェクトします。

```ts
providers: [
{provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
],

```

自動プリコネクト生成に関する詳細情報は[こちら](#why-is-a-preconnect-element-not-being-generated-for-my-image-domain)を参照してください。

### 自動`srcset`による適切なサイズの画像リクエスト {#request-images-at-the-correct-size-with-automatic-srcset}

[`srcset`属性](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/srcset)を定義することで、ブラウザがユーザーのビューポートに適切なサイズの画像をリクエストするようになります。これにより、大きすぎる画像をダウンロードする時間の無駄を省きます。`NgOptimizedImage`は、画像タグの[`sizes`属性](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes)の有無と値に基づいて、画像に適切な`srcset`を生成します。

#### 固定サイズの画像 {#fixed-size-images}

画像がサイズ「固定」である（つまり、[ピクセル密度](https://web.dev/codelab-density-descriptors/)を除いてデバイス間で同じサイズ）場合、`sizes`属性を設定する必要はありません。画像の`width`属性と`height`属性から、追加の入力なしで`srcset`を自動的に生成できます。

生成されるsrcsetの例:

```html
<img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x" />
```

#### レスポンシブ画像 {#responsive-images}

画像がレスポンシブである（つまり、ビューポートサイズに応じて拡大縮小する）場合、`srcset`を生成するために[`sizes`属性](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes)を定義する必要があります。

`sizes`を以前に使用したことがない場合、ビューポート幅に基づいて設定することから始めるのが良いでしょう。例えば、CSSによって画像がビューポート幅の100%を占める場合、`sizes`を`100vw`に設定すると、ブラウザは（ピクセル密度を考慮した上で）ビューポート幅に最も近い`srcset`内の画像を選択します。画像が画面の半分しか占めない可能性が高い場合（例: サイドバー内）、ブラウザがより小さな画像を選択するように`sizes`を`50vw`に設定します。以下同様です。

上記が目的の画像動作をカバーしない場合、[高度なsizes値](#advanced-sizes-values)に関するドキュメントを参照してください。

NOTE: `NgOptimizedImage`は、提供された`sizes`値の前に自動的に`"auto"`を付加します。これは`sizes="auto"`をサポートするブラウザでのsrcset選択の精度を高める最適化であり、サポートしないブラウザでは無視されます。

デフォルトでは、レスポンシブブレークポイントは次のとおりです:

`[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`から推測します。このディレクティブは、幅記述子（例: `100w`）と密度記述子（例: `1x`）の両方をサポートしています。

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw" />
```

### 自動srcset生成の無効化 {#disabling-automatic-srcset-generation}

単一の画像に対してsrcset生成を無効にするには、画像に`disableOptimizedSrcset`属性を追加できます。

```html
<img ngSrc="about.jpg" disableOptimizedSrcset />
```

### 画像の遅延読み込みの無効化 {#disabling-image-lazy-loading}

デフォルトでは、`NgOptimizedImage`は`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" />
```

### 画像のデコード制御 {#controlling-image-decoding}

デフォルトでは、`NgOptimizedImage`はすべての画像に対して`decoding="auto"`を設定します。これにより、ブラウザは画像が取得された後にデコードする最適なタイミングを決定できます。画像が`priority`としてマークされている場合、Angularは自動的に`decoding="sync"`を設定し、画像ができるだけ早くデコードされてペイントされるようにし、**Largest Contentful Paint(LCP)**パフォーマンスの向上に役立ちます。

`decoding`属性を明示的に設定することで、この動作をオーバーライドできます。
詳細については、[標準の画像`decoding`属性に関するドキュメントを参照してください](https://developer.mozilla.org/docs/Web/HTML/Element/img#decoding)。

```html

<img ngSrc="gallery/landscape.jpg" width="1200" height="800" />

<img ngSrc="gallery/preview.jpg" width="600" height="400" decoding="async" />

<img ngSrc="awesome.jpg" width="500" height="625" priority />

<img ngSrc="hero.jpg" width="1600" height="900" decoding="sync" />
```

**許可される値**

- `auto`（デフォルト）: ブラウザが最適な戦略を選択します。
- `async`: 画像を非同期にデコードし、可能な場合はメインスレッドのブロックを避けます。
- `sync`: 画像を即座にデコードします。レンダリングをブロックする可能性がありますが、画像が利用可能になり次第ピクセルが準備されることを保証します。

### 高度な'sizes'値 {#advanced-sizes-values}

異なるサイズの画面で画像を異なる幅で表示したい場合があります。このパターンの一般的な例は、モバイルデバイスでは単一の列を、より大きなデバイスでは2つの列をレンダリングするグリッドベースまたはカラムベースのレイアウトです。この動作は、以下のような「メディアクエリ」構文を使用して`sizes`属性で表現できます。

```html
<img ngSrc="cat.jpg" width="400" height="200" sizes="(max-width: 768px) 100vw, 50vw" />
```

上記の例の`sizes`属性は、「この画像は幅768px未満のデバイスでは画面幅の100%になることを想定しています。それ以外の場合は、画面幅の50%になることを想定しています。」という意味です。

`sizes`属性に関する追加情報については、[web.dev](https://web.dev/learn/design/responsive-images/#sizes)または[mdn](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes)を参照してください。

## NgOptimizedImageの画像ローダーを設定する {#configuring-an-image-loader-for-ngoptimizedimage}

「ローダー」とは、指定された画像ファイルに対して[画像変換URL](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options)を生成する関数です。必要に応じて、`NgOptimizedImage`は画像のサイズ、フォーマット、画質の変換を設定します。

`NgOptimizedImage`は、変換を適用しない汎用ローダーと、様々なサードパーティ画像サービス用のローダーの両方を提供します。また、独自のカスタムローダーを作成することもサポートしています。

| ローダーの種類                         | 動作                                                                                                                                             |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| 汎用ローダー                           | 汎用ローダーが返すURLは常に`src`の値と一致します。つまり、このローダーは変換を適用しません。Angularを使用して画像を配信するサイトが、このローダーの主な想定されるユースケースです。 |
| サードパーティ画像サービス用ローダー   | サードパーティ画像サービス用ローダーが返すURLは、その特定の画像サービスで使用されるAPI規約に従います。                                                |
| カスタムローダー                       | カスタムローダーの動作は、その開発者によって定義されます。`NgOptimizedImage`に事前設定されているローダーで画像サービスがサポートされていない場合は、カスタムローダーを使用する必要があります。 |

Angularアプリケーションで一般的に使用される画像サービスに基づいて、`NgOptimizedImage`は以下の画像サービスで動作するように事前設定されたローダーを提供します。

**汎用ローダー**を使用するために、追加のコード変更は不要です。これがデフォルトの動作です。

### 組み込みローダー {#built-in-loaders}

**サードパーティ画像サービス**用の既存のローダーを使用するには、選択したサービスのプロバイダーファクトリを`providers`配列に追加します。以下の例では、Imgixローダーが使用されています。

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

画像アセットのベースURLは、プロバイダーファクトリに引数として渡す必要があります。ほとんどのサイトでは、このベースURLは以下のいずれかのパターンに一致する必要があります。

- <https://yoursite.yourcdn.com>
- <https://subdomain.yoursite.com>
- <https://subdomain.yourcdn.com/yoursite>

ベースURL構造の詳細については、対応するCDNプロバイダーのドキュメントで確認できます。

### カスタムローダー {#custom-loaders}

**カスタムローダー**を使用するには、`IMAGE_LOADER` DIトークンの値としてローダー関数を提供します。以下の例では、カスタムローダー関数は`https://example.com`で始まるURLを返し、`src`と`width`をURLパラメータとして含んでいます。

```ts
providers: [
  {
    provide: IMAGE_LOADER,
    useValue: (config: ImageLoaderConfig) => {
      return `https://example.com/images?src=${config.src}&width=${config.width}`;
    },
  },
],
```

`NgOptimizedImage`ディレクティブのローダー関数は、`ImageLoaderConfig`型（`@angular/common`から）のオブジェクトを引数として受け取り、画像アセットの絶対URLを返します。`ImageLoaderConfig`オブジェクトには、`src`プロパティと、オプションの`width`および`loaderParams`プロパティが含まれています。

NOTE: `width`プロパティが常に存在するとは限りませんが、`ngSrcset`が正しく機能するためには、カスタムローダーが様々な幅で画像をリクエストすることをサポートするためにこれを使用する必要があります。

### `loaderParams`プロパティ {#the-loaderparams-property}

`NgOptimizedImage`ディレクティブには、`loaderParams`と呼ばれる追加の属性があり、これはカスタムローダーの使用をサポートするために特別に設計されています。`loaderParams`属性は、任意のプロパティを持つオブジェクトを値として受け取りますが、それ自体では何も行いません。`loaderParams`内のデータは、カスタムローダーに渡される`ImageLoaderConfig`オブジェクトに追加され、ローダーの動作を制御するために使用できます。

`loaderParams`の一般的な用途は、高度な画像CDN機能を制御することです。

### カスタムローダーの例 {#example-custom-loader}

以下にカスタムローダー関数の例を示します。この例の関数は`src`と`width`を連結し、`loaderParams`を使用して角丸のためのカスタムCDN機能を制御します。

```ts
const myCustomLoader = (config: ImageLoaderConfig) => {
  let url = `https://example.com/images/${config.src}?`;
  let queryParams = [];
  if (config.width) {
    queryParams.push(`w=${config.width}`);
  }
  if (config.loaderParams?.roundedCorners) {
    queryParams.push('mask=corners&corner-radius=5');
  }
  return url + queryParams.join('&');
};
```

上記の例では、カスタムローダーの機能を制御するために「roundedCorners」というプロパティ名を考案したことに注意してください。この機能は、画像を生成する際に次のように使用できます。

```html
<img ngSrc="profile.jpg" width="300" height="300" [loaderParams]="{roundedCorners: true}" />
```

## よくある質問 {#frequently-asked-questions}

### NgOptimizedImageは`background-image`CSSプロパティをサポートしていますか？ {#does-ngoptimizedimage-support-the-background-image-css-property}

NgOptimizedImageは`background-image`CSSプロパティを直接サポートしていませんが、別の要素の背景として画像を使用するユースケースに容易に対応できるように設計されています。

`background-image`からNgOptimizedImageへの移行の段階的なプロセスについては、上記の[背景画像の移行方法](#how-to-migrate-your-background-image)セクションを参照してください。

### NgOptimizedImageで`src`を使用できないのはなぜですか？ {#why-cant-i-use-src-with-ngoptimizedimage}

`ngSrc`属性は、ブラウザが画像を読み込む方法に関する技術的な考慮事項から、NgOptimizedImageのトリガーとして選択されました。NgOptimizedImageは`loading`属性にプログラムによる変更を加えます。ブラウザがこれらの変更が行われる前に`src`属性を認識すると、画像ファイルの積極的なダウンロードを開始し、読み込みの変更は無視されます。

### 画像ドメインのプリコネクト要素が生成されないのはなぜですか？ {#why-is-a-preconnect-element-not-being-generated-for-my-image-domain}

プリコネクトの生成は、アプリケーションの静的解析に基づいて実行されます。つまり、画像ドメインは、次の例のように、ローダーパラメーターに直接含める必要があります。

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

変数を使用してドメイン文字列をローダーに渡している場合、またはローダーを使用していない場合、静的解析はドメインを識別できず、プリコネクトリンクは生成されません。この場合、[上記で説明されている](#add-resource-hints)ように、ドキュメントのヘッドにプリコネクトリンクを手動で追加する必要があります。

### 同じページで2つの異なる画像ドメインを使用できますか？ {#can-i-use-two-different-image-domains-in-the-same-page}

[画像ローダー](#configuring-an-image-loader-for-ngoptimizedimage)プロバイダーパターンは、コンポーネント内で単一の画像CDNのみを使用するという一般的なユースケースに対して、可能な限りシンプルになるように設計されています。ただし、単一のプロバイダーを使用して複数の画像CDNを管理することは依然として非常に可能です。

これを行うには、[カスタム画像ローダー](#custom-loaders)を作成し、[`loaderParams`プロパティ](#the-loaderparams-property)を使用して、どの画像CDNを使用すべきかを指定するフラグを渡し、そのフラグに基づいて適切なローダーを呼び出すことをお勧めします。

### 優先するCDN用の新しい組み込みローダーを追加できますか？ {#can-you-add-a-new-built-in-loader-for-my-preferred-cdn}

メンテナンス上の理由から、現在Angularリポジトリで追加の組み込みローダーをサポートする予定はありません。代わりに、開発者には追加の画像ローダーをサードパーティパッケージとして公開することを推奨しています。

### これを`<picture>`タグで使用できますか？ {#can-i-use-this-with-the-picture-tag}

いいえ、しかしこれは私たちのロードマップにありますので、ご期待ください。

この機能を待っている場合は、Githubのイシューを[こちら](https://github.com/angular/angular/issues/56594)でアップボートしてください。

### Chrome DevToolsでLCP画像を見つけるにはどうすればよいですか？ {#how-do-i-find-my-lcp-image-with-chrome-devtools}

1. Chrome DevToolsのパフォーマンスタブを使用して、左上にある「プロファイリングを開始してページを再読み込み」ボタンをクリックします。これはページ更新アイコンのように見えます。

2. これにより、Angularアプリケーションのプロファイリングスナップショットがトリガーされます。

3. プロファイリング結果が利用可能になったら、タイミングセクションで「LCP」を選択します。

4. 下部のパネルに概要エントリが表示されます。「関連ノード」の行でLCP要素を見つけることができます。それをクリックすると、要素がElementsパネルに表示されます。

NOTE: これは、テストしているページのビューポート内のLCP要素のみを識別します。より小さな画面のLCP要素を識別するために、モバイルエミュレーションを使用することも推奨されます。
Angularでは、*シグナル*を使用して状態を作成および管理します。シグナルは、値をラップする軽量なラッパーです。

`signal`関数を用いて、ローカル状態を保持するためのシグナルを作成します。

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

// `signal` 関数でシグナルを作成します。
const firstName = signal('Morgan');

// シグナルの値を読み取るには、それを呼び出します。シグナルは関数です。
console.log(firstName());

// 新しい値を指定して `set` メソッドを呼び出すことで、このシグナルの値を変更します。
firstName.set('Jaime');

// `update` メソッドを使用して、
// 前の値に基づいて値を変更することもできます。
firstName.update((name) => name.toUpperCase()); 
```

Angularは、シグナルがどこで読み取られ、いつ更新されたかを追跡します。フレームワークはこの情報を使用して、新しい状態をDOMに更新するなど、追加の作業をします。時間の経過とともに変化するシグナル値に応答するこの機能は、*リアクティビティ*として知られています。

## 算出式 {#computed-expressions}

`computed`は、他のシグナルに基づいて値を生成するシグナルです。

```typescript
import {signal, computed} from '@angular/core';

const firstName = signal('Morgan');
const firstNameCapitalized = computed(() => firstName().toUpperCase());

console.log(firstNameCapitalized()); // MORGAN
```

`computed`シグナルは読み取り専用です。`set`メソッドまたは`update`メソッドはありません。代わりに、`computed`シグナルの値は、読み取るシグナルのいずれかが変更されると自動的に変更されます。

```typescript
import {signal, computed} from '@angular/core';

const firstName = signal('Morgan');
const firstNameCapitalized = computed(() => firstName().toUpperCase());
console.log(firstNameCapitalized()); // MORGAN

firstName.set('Jaime');
console.log(firstNameCapitalized()); // JAIME
```

## コンポーネントでシグナルを使う {#using-signals-in-components}

`signal`と`computed`をコンポーネント内で使用して、状態を作成および管理します。

```typescript
@Component({
  /* ... */
})
export class UserProfile {
  isTrial = signal(false);
  isTrialExpired = signal(false);
  showTrialDuration = computed(() => this.isTrial() && !this.isTrialExpired());

activateTrial() {
    this.isTrial.set(true);
  }
}
```

TIP: Angularのシグナルについてもっと知りたいですか？[詳細なシグナルガイド](guide/signals)を参照してください。

## 次の手順 {#next-step}

動的なデータの宣言と管理方法を学習したので、テンプレート内でそのデータを使用する方法を学習する時間です。
# `linkedSignal`による依存状態

`signal`関数は、Angularコードで状態を保持するために使用できます。この状態は、他の状態に依存することがあります。例えば、ユーザーが注文の配送方法を選択できるコンポーネントを考えてみましょう。

```typescript
@Component({
  /* ... */
})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// デフォルトで最初の配送オプションを選択します。
  selectedOption = signal(this.shippingOptions()[0]);

changeShipping(newOptionIndex: number) {
    this.selectedOption.set(this.shippingOptions()[newOptionIndex]);
  }
}
```

この例では、`selectedOption`は最初のオプションにデフォルト設定されますが、ユーザーが別のオプションを選択すると変更されます。しかし、`shippingOptions`はシグナルであり、その値は変更される可能性があります！`shippingOptions`が変更されると、`selectedOption`はもはや有効なオプションではない値を含む可能性があります。

**`linkedSignal`関数は、本質的に他の状態に_リンク_された状態を保持するシグナルを作成できます。**上記の例を再考すると、`linkedSignal`は`signal`を置き換えることができます。

```typescript
@Component({
  /* ... */
})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// selectedOptionを最初の配送オプションに初期化します。
  selectedOption = linkedSignal(() => this.shippingOptions()[0]);

changeShipping(index: number) {
    this.selectedOption.set(this.shippingOptions()[index]);
  }
}
```

`linkedSignal`は`signal`と同様に動作しますが、重要な違いが1つあります。デフォルト値を渡す代わりに、`computed`のように*算出関数*を渡します。算出値が変更されると、`linkedSignal`の値は計算結果に変更されます。これは、`linkedSignal`が常に有効な値を持つようにするのに役立ちます。

次の例は、`linkedSignal`の値がリンクされた状態に基づいてどのように変化するかを示しています。

```typescript
const shippingOptions = signal(['Ground', 'Air', 'Sea']);
const selectedOption = linkedSignal(() => shippingOptions()[0]);
console.log(selectedOption()); // 'Ground'

selectedOption.set(shippingOptions()[2]);
console.log(selectedOption()); // 'Sea'

shippingOptions.set(['Email', 'Will Call', 'Postal service']);
console.log(selectedOption()); // 'Email'
```

## 以前の状態を考慮する

場合によっては、`linkedSignal`の計算で`linkedSignal`の以前の値を考慮する必要があります。

上記の例では、`shippingOptions`が変更されると、`selectedOption`は常に最初のオプションに戻って更新されます。しかし、選択したオプションがリスト内にまだ存在する場合は、ユーザーの選択を維持したい場合があります。これを実現するには、別々の*ソース*と*算出*を使用して`linkedSignal`を作成できます。

```typescript
interface ShippingMethod {
  id: number;
  name: string;
}

@Component({
  /* ... */
})
export class ShippingMethodPicker {
  constructor() {
    this.changeShipping(2);
    this.changeShippingOptions();
    console.log(this.selectedOption()); // {"id":2,"name":"Postal Service"}
  }

shippingOptions = signal<ShippingMethod[]>([
    {id: 0, name: 'Ground'},
    {id: 1, name: 'Air'},
    {id: 2, name: 'Sea'},
  ]);

selectedOption = linkedSignal<ShippingMethod[], ShippingMethod>({
    // `selectedOption` is set to the `computation` result whenever this `source` changes.
    source: this.shippingOptions,
    computation: (newOptions, previous) => {
      // If the newOptions contain the previously selected option, preserve that selection.
      // Otherwise, default to the first option.
      return newOptions.find((opt) => opt.id === previous?.value.id) ?? newOptions[0];
    },
  });

changeShipping(index: number) {
    this.selectedOption.set(this.shippingOptions()[index]);
  }

changeShippingOptions() {
    this.shippingOptions.set([
      {id: 0, name: 'Email'},
      {id: 1, name: 'Sea'},
      {id: 2, name: 'Postal Service'},
    ]);
  }
}
```

`linkedSignal`を作成する際には、算出関数だけを提供する代わりに、個別の`source`プロパティと`computation`プロパティを持つオブジェクトを渡すことができます。

`source`は、`computed`やコンポーネントの`input`などの任意のシグナルにできます。`linkedSignal`は、`source`が変更されたとき、または`computation`内で参照されている任意のシグナルが変更されたときに、提供された`computation`の結果でその値を更新します。

`computation`は、`source`の新しい値と`previous`オブジェクトを受け取る関数です。`previous`オブジェクトには、`previous.source`（`source`の以前の値）、`previous.value`（`linkedSignal`の以前の値）の2つのプロパティがあります。これらの以前の値を使用して、計算の新しい結果を決定できます。

HELPFUL: `previous`パラメーターを使用する場合、`linkedSignal`のジェネリック型引数を明示的に指定する必要があります。最初のジェネリック型は`source`の型に対応し、2番目のジェネリック型は`computation`の出力型を決定します。

## カスタムの等価比較

`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,
});
```
# 非同期リアクティビティとリソース

IMPORTANT: `resource`は[実験的](reference/releases#experimental)です。お試しいただけますが、安定版になる前に変更される可能性があります。

すべてのシグナルAPIは同期的です（`signal`、`computed`、`input`など）。しかし、アプリケーションは多くの場合、非同期的に利用可能なデータを処理する必要があります。`Resource`を使用すると、非同期データをアプリケーションのシグナルベースのコードに組み込み、そのデータに同期的にアクセスできるようになります。

`Resource`を使用してあらゆる種類の非同期処理を実行できますが、`Resource`の最も一般的なユースケースはサーバーからデータを取得することです。以下は、ユーザーデータを取得するためのリソースを作成する例です。

`Resource`を作成する最も簡単な方法は、`resource`関数を使用することです。

```typescript
import {resource, Signal} from '@angular/core';

const userId: Signal<string> = getUserId();

const userResource = resource({
  // Define a reactive computation.
  // The params value recomputes whenever any read signals change.
  params: () => ({id: userId()}),

// Define an async loader that retrieves data.
  // The resource calls this function every time the `params` value changes.
  loader: ({params}) => fetchUser(params),
});

// Create a computed signal based on the result of the resource's loader function.
const firstName = computed(() => {
  if (userResource.hasValue()) {
    // `hasValue` serves 2 purposes:
    // - It acts as type guard to strip `undefined` from the type
    // - If protects against reading a throwing `value` when the resource is in error state
    return userResource.value().firstName;
  }

// fallback in case the resource value is `undefined` or if the resource is in error state
  return undefined;
});
```

`resource`関数は、2つの主なプロパティである`params`と`loader`を持つ`ResourceOptions`オブジェクトを受け入れます。

`params`プロパティは、パラメータ値を生成するリアクティブな計算を定義します。この計算で読み取られるシグナルが変更されるたびに、リソースは新しいパラメータ値を生成します。これは`computed`と同様です。

`loader`プロパティは`ResourceLoader`を定義します。これは、状態を取得する非同期関数です。リソースは、`params`計算が新しい値を生成するたびにローダーを呼び出し、その値をローダーに渡します。詳細は下記の[Resourceローダー](#resource-loaders)を参照してください。

`Resource`には、ローダーの結果を含む`value`シグナルがあります。

## リソースローダー {#resource-loaders}

リソースを作成する際には、`ResourceLoader`を指定します。このローダーは、単一のパラメーター（`ResourceLoaderParams`オブジェクト）を受け入れ、値を返す非同期関数です。

`ResourceLoaderParams`オブジェクトには、`params`、`previous`、`abortSignal`の3つのプロパティが含まれています。

| プロパティ      | 説明                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`     | リソースの`params`計算の値。                                                                                               |
| `previous`    | `status`プロパティを含む、前の`ResourceStatus`を持つオブジェクト。                                                                    |
| `abortSignal` | [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)。詳細は下記の[リクエストの中断](#aborting-requests)を参照してください。 |

`params`の計算が`undefined`を返す場合、ローダー関数は実行されず、リソースの状態は`Idle`になります。

### リクエストの中断 {#aborting-requests}

リソースが読み込み中の場合に`params`計算が変更されると、リソースは未処理の読み込み処理を中断します。

`ResourceLoaderParams`内の`abortSignal`を使用して、中断されたリクエストに応答できます。例えば、ネイティブの`fetch`関数は`AbortSignal`を受け入れます。

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params, abortSignal}): Promise<User> => {
    // 与えられた`AbortSignal`がリクエストの中断を示している場合、
    // fetchは未処理のHTTPリクエストをキャンセルします。
    return fetch(`users/${params.id}`, {signal: abortSignal});
  },
});
```

`AbortSignal`によるリクエストのキャンセルについては、[`AbortSignal` on MDN](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)を参照してください。

### 再読み込み {#reloading}

`reload`メソッドを呼び出すことで、プログラム的にリソースの`loader`をトリガーできます。

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

// ...

userResource.reload();
```

## リソースの状態

リソースオブジェクトには、非同期ローダーの状態を読み取るためのいくつかのシグナルプロパティがあります。

| プロパティ    | 説明                                                                                                     |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| `value`     | リソースの最新の値、または値が受信されていない場合は`undefined`。                            |
| `hasValue`  | リソースが値を持っているかどうか。                                                                               |
| `error`     | リソースのローダーの実行中に発生した最新のエラー、またはエラーが発生していない場合は`undefined`。 |
| `isLoading` | リソースローダーが現在実行中かどうか。                                                               |
| `status`    | 後述のリソースの特定の`ResourceStatus`。                                                   |

`status` シグナルは、文字列定数を使用してリソースの状態を説明する特定の `ResourceStatus` を提供します。

| ステータス        | `value()`         | 説明                                                                  |
| ------------- | :---------------- | ---------------------------------------------------------------------------- |
| `'idle'`      | `undefined`       | リソースに有効なリクエストがなく、ローダーが実行されていません。                |
| `'error'`     | `undefined`       | ローダーの読み込みがエラーになりました。                                         |
| `'loading'`   | `undefined`       | `params` 値の変更の結果としてローダーが実行中です。            |
| `'reloading'` | 前の値    | リソースの `reload` メソッドの呼び出しの結果としてローダーが実行中です。 |
| `'resolved'`  | 解決された値    | ローダーが完了しました。                                                    |
| `'local'`     | ローカルに設定された値 | リソースの値が `.set()` または `.update()` を介してローカルに設定されています。        |

この状態情報を使用して、ローディングインジケーターやエラーメッセージなどのユーザーインターフェース要素を条件付きで表示できます。

## `httpResource` を使用したリアクティブデータ取得

[`httpResource`](/guide/http/http-resource) は `HttpClient` のラッパーで、リクエストの状態とレスポンスをシグナルとして提供します。これはインターセプターを含むAngular HTTPスタックを通してHTTPリクエストを行います。
# Creating an injectable service

Service is a broad category encompassing any value, function, or feature that an application needs.
A service is typically a class with a narrow, well-defined purpose.
A component is one type of class that can use DI.

Angular distinguishes components from services to increase modularity and reusability.
By separating a component's view-related features from other kinds of processing, you can make your component classes lean and efficient.

Ideally, a component's job is to enable the user experience and nothing more.
A component should present properties and methods for data binding, to mediate between the view (rendered by the template) and the application logic (which often includes some notion of a model).

A component can delegate certain tasks to services, such as fetching data from the server, validating user input, or logging directly to the console.
By defining such processing tasks in an injectable service class, you make those tasks available to any component.
You can also make your application more adaptable by configuring different providers of the same kind of service, as appropriate in different circumstances.

Angular does not enforce these principles.
Angular helps you follow these principles by making it easy to factor your application logic into services and make those services available to components through DI.

## Service examples

Here's an example of a service class that logs to the browser console:

```ts
{header: "logger.service.ts (class)"}
export class Logger {
  log(msg: unknown) {
    console.log(msg);
  }
  error(msg: unknown) {
    console.error(msg);
  }
  warn(msg: unknown) {
    console.warn(msg);
  }
}
```

Services can depend on other services.
For example, here's a `HeroService` that depends on the `Logger` service, and also uses `BackendService` to get heroes.
That service in turn might depend on the `HttpClient` service to fetch heroes asynchronously from a server:

```ts
{header: "hero.service.ts", highlight="[7,8,12,13]"}
import {inject} from '@angular/core';

export class HeroService {
  private heroes: Hero[] = [];

private backend = inject(BackendService);
  private logger = inject(Logger);

async getHeroes() {
    // Fetch
    this.heroes = await this.backend.getAll(Hero);
    // Log
    this.logger.log(`Fetched ${this.heroes.length} heroes.`);
    return this.heroes;
  }
}
```

## Creating an injectable service with the CLI

The Angular CLI provides a command to create a new service. In the following example, you add a new service to an existing application.

To generate a new `HeroService` class in the `src/app/heroes` folder, follow these steps:

1. Run this [Angular CLI](/tools/cli) command:

```sh
ng generate service heroes/hero
```

This command creates the following default `HeroService`:

```ts
{header: 'heroes/hero.service.ts (CLI-generated)'}
import {Injectable} from '@angular/core';

@Injectable({
  providedIn: 'root',
})
export class HeroService {}
```

The `@Injectable()` decorator specifies that Angular can use this class in the DI system.
The metadata, `providedIn: 'root'`, means that the `HeroService` is provided throughout the application.

Add a `getHeroes()` method that returns the heroes from `mock.heroes.ts` to get the hero mock data:

```ts
{header: 'hero.service.ts'}
import {Injectable} from '@angular/core';
import {HEROES} from './mock-heroes';

@Injectable({
  // declares that this service should be created
  // by the root application injector.
  providedIn: 'root',
})
export class HeroService {
  getHeroes() {
    return HEROES;
  }
}
```

For clarity and maintainability, it is recommended that you define components and services in separate files.

## Injecting services

To inject a service as a dependency into a component, you can declare a class field representing the dependency and use Angular's [`inject`](/api/core/inject) function to initialize it.

The following example specifies the `HeroService` in the `HeroListComponent`.
The type of `heroService` is `HeroService`.

```ts
import {inject} from '@angular/core';

export class HeroListComponent {
  private heroService = inject(HeroService);
}
```

It is also possible to inject a service into a component using the component's constructor:

```ts
{header: 'hero-list.component.ts (constructor signature)'}
  constructor(private heroService: HeroService)
```

The [`inject`](/api/core/inject) method can be used in both classes and functions, while the constructor method can naturally only be used in a class constructor. However, in either case a dependency may only be injected in a valid [injection context](guide/di/dependency-injection-context), usually in the construction or initialization of a component.

## Injecting services in other services

When a service depends on another service, follow the same pattern as injecting into a component.
In the following example, `HeroService` depends on a `Logger` service to report its activities:

```ts
{header: 'hero.service.ts, highlight: [[3],[9],[12]]}
import {inject, Injectable} from '@angular/core';
import {HEROES} from './mock-heroes';
import {Logger} from '../logger.service';

@Injectable({
  providedIn: 'root',
})
export class HeroService {
  private logger = inject(Logger);

getHeroes() {
    this.logger.log('Getting heroes.');
    return HEROES;
  }
}
```

In this example, the `getHeroes()` method uses the `Logger` service by logging a message when fetching heroes.

## What's next
# 依存関係プロバイダーの設定

前のセクションでは、クラスインスタンスを依存関係として使用する仕組みについて説明しました。
クラスに加えて、`boolean`、`string`、`Date`、オブジェクトなどの値を依存関係として使用できます。
Angularは、依存関係の設定を柔軟にするために必要なAPIを提供しており、これらの値をDIで利用可能にできます。

## プロバイダートークンの指定

プロバイダートークンとしてサービスクラスを指定した場合、インジェクターはデフォルトで`new`演算子を使用してそのクラスをインスタンス化します。

次の例では、アプリケーションコンポーネントは`Logger`インスタンスを提供します。

```
providers: [Logger],
```
ただし、DIを構成して、`Logger`プロバイダートークンを別のクラスまたはその他の値に関連付けることができます。
そのため、`Logger`が注入されると、構成された値が代わりに使用されます。

実際、クラスプロバイダーの構文は、`Provider`インターフェースで定義されたプロバイダー構成に展開される省略記号です。
Angularは、この場合の`providers`値を、次のように完全なプロバイダーオブジェクトに展開します。

```
[{ provide: Logger, useClass: Logger }]
```
展開されたプロバイダー構成は、2つのプロパティを持つオブジェクトリテラルです。

- `provide`プロパティは、依存関係値を消費するためのキーとして機能するトークンを保持します。
- 2番目のプロパティはプロバイダー定義オブジェクトで、インジェクターが依存関係値を**どのように**作成するかを指示します。プロバイダー定義は、次のいずれかになります。
  - `useClass` - このオプションは、依存関係が注入されるときに、Angular DIが提供されたクラスをインスタンス化することを指示します。
  - `useExisting` - トークンにエイリアスを付けて、既存のトークンを参照できます。
  - `useFactory` - 依存関係を作成する関数を定義できます。
  - `useValue` - 依存関係として使用する静的な値を提供します。

以下のセクションでは、さまざまなプロバイダー定義の使用方法について説明します。

### クラスプロバイダー: useClass

`useClass`プロバイダーキーを使用すると、指定されたクラスの新しいインスタンスを作成して返します。

このタイプのプロバイダーを使用して、共通またはデフォルトのクラスの代替実装を置き換えることができます。
代替実装はたとえば異なる戦略を実装したり、デフォルトクラスを拡張したり、テストケースで実際のクラスの動作をエミュレートしたりできます。

次の例では、`Logger`依存関係がコンポーネントまたはその他のクラスで要求されると、`BetterLogger`がインスタンス化されます。

```
[{ provide: Logger, useClass: BetterLogger }]
```
代替クラスプロバイダーが独自の依存関係を持つ場合は、親モジュールまたはコンポーネントの`providers`メタデータプロパティに両方のプロバイダーを指定します。

```
[
  UserService, // `EvenBetterLogger`に必要な依存関係。
  { provide: Logger, useClass: EvenBetterLogger },
]
```
この例では、`EvenBetterLogger`はログメッセージにユーザー名を表示します。このロガーは、注入された`UserService`インスタンスからユーザーを取得します。

```
@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}`);
  }
}
```
Angular DIは、`UserService`依存関係を構成する方法を知っています。なぜなら、`UserService`は上記で構成されており、インジェクターで利用可能だからです。

### エイリアスプロバイダー: useExisting

`useExisting`プロバイダーキーを使用すると、1つのトークンを別のトークンにマッピングできます。
つまり、最初のトークンは2番目のトークンに関連付けられたサービスのエイリアスになり、同じサービスオブジェクトにアクセスする2つの方法が作成されます。

次の例では、コンポーネントが新しいロガーまたは古いロガーのいずれかを要求すると、インジェクターは`NewLogger`のシングルトンインスタンスを注入します。
このように、`OldLogger`は`NewLogger`のエイリアスです。

```
[
  NewLogger,
  // NewLoggerへの参照でOldLoggerにエイリアスを付ける
  { provide: OldLogger, useExisting: NewLogger},
]
```
NOTE: `useClass`を使用して`OldLogger`に`NewLogger`をエイリアス付けしないようにしてください。これは、2つの異なる`NewLogger`インスタンスが作成されるためです。

### ファクトリプロバイダー: useFactory

`useFactory`プロバイダーキーを使用すると、ファクトリ関数を呼び出すことで依存関係オブジェクトを作成できます。
このアプローチでは、DIとアプリケーションの他の場所で利用可能な情報に基づいて、動的な値を作成できます。

次の例では、承認されたユーザーのみが`HeroService`で秘密のヒーローを表示できます。
承認は、別のユーザーがログインした場合など、単一のアプリケーションセッション中に変更される可能性があります。

`UserService`内のセキュリティに敏感な情報を`HeroService`から分離するには、`HeroService`コンストラクターに、秘密のヒーローの表示を制御するためのブール型のフラグを与えます。

```
class HeroService {
  constructor(
    private logger: Logger,
    private isAuthorized: boolean) { }

getHeroes() {
    const auth = this.isAuthorized ? 'authorized' : 'unauthorized';
    this.logger.log(`Getting heroes for ${auth} user.`);
    return HEROES.filter(hero => this.isAuthorized || !hero.isSecret);
  }
}
```
`isAuthorized`フラグを実装するには、ファクトリプロバイダーを使用して、`HeroService`の新しいロガーインスタンスを作成します。
これは、ヒーローサービスを構築する際に`Logger`を手動で渡す必要があるためです。

```
const heroServiceFactory = (logger: Logger, userService: UserService) =>
  new HeroService(logger, userService.user.isAuthorized);
```
ファクトリ関数は`UserService`にアクセスできます。
`Logger`と`UserService`の両方をファクトリプロバイダーに注入して、インジェクターがファクトリ関数に渡せるようにします。

```
export const heroServiceProvider = {
  provide: HeroService,
  useFactory: heroServiceFactory,
  deps: [Logger, UserService]
};
```
- `useFactory`フィールドは、プロバイダーが`heroServiceFactory`の実装であるファクトリ関数であることを指定します。
- `deps`プロパティは、プロバイダートークンの配列です。
`Logger`クラスと`UserService`クラスは、それ自身のクラスプロバイダーのトークンとして機能します。
インジェクターは、指定された順序に基づいて、これらのトークンを解決し、対応するサービスを`heroServiceFactory`ファクトリ関数の対応するパラメーターに注入します。

エクスポートされた変数`heroServiceProvider`にファクトリプロバイダーをキャプチャすると、ファクトリプロバイダーを再利用できます。

### 値プロバイダー: useValue

`useValue`キーを使用すると、静的な値をDIトークンに関連付けることができます。

このテクニックを使用して、Webサイトの基本アドレスや機能フラグなどのランタイム構成定数を提供します。
また、ユニットテストで値プロバイダーを使用して、本番データサービスの代わりにモックデータを提供できます。

次のセクションでは、`useValue`キーの詳細について説明します。

## `InjectionToken`オブジェクトの使用

非クラス依存関係のプロバイダートークンとして`InjectionToken`オブジェクトを使用します。
次の例では、`APP_CONFIG`というトークンを`InjectionToken`の型で定義しています。

```
import { InjectionToken } from '@angular/core';

export interface AppConfig {
  title: string;
}

export const APP_CONFIG = new InjectionToken<AppConfig>('app.config description');
```
オプションの型パラメーター`<AppConfig>`とトークン説明`app.config description`は、トークンの目的を指定します。

次に、`APP_CONFIG`の`InjectionToken`オブジェクトを使用して、コンポーネントに依存関係プロバイダーを登録します。

```
const MY_APP_CONFIG_VARIABLE: AppConfig = {
  title: 'Hello',
};

providers: [{ provide: APP_CONFIG, useValue: MY_APP_CONFIG_VARIABLE }]
```
Now, inject the configuration object in the constructor body with the `inject` function:

```
export class AppComponent {
  constructor() {
    const config = inject(APP_CONFIG);
    this.title = config.title;
  }
}
```
### インターフェースとDI

TypeScriptの`AppConfig`インターフェースは、クラス内の型付けをサポートしますが、`AppConfig`インターフェースはDIで役割を果たしません。
TypeScriptでは、インターフェースは設計時のアーティファクトであり、DIフレームワークが使用できるランタイム表現またはトークンを持ちません。

TypeScriptがJavaScriptにトランスパイルされると、インターフェースは消えてしまいます。なぜなら、JavaScriptにはインターフェースがないからです。
Angularがランタイムでインターフェースを見つけられないため、インターフェースはトークンになることができず、インターフェースの注入もできません。

```
// インターフェースをプロバイダートークンとして使用できません
[{ provide: AppConfig, useValue: MY_APP_CONFIG_VARIABLE })]
```
```
export class AppComponent {
  // インターフェースをパラメータータイプとして使用して注入することはできません
  private config = inject(AppConfig);
}
```

# 注入コンテキスト

依存性の注入 (DI) システムは、内部的に現在のインジェクターが利用可能なランタイムコンテキストに依存しています。

これは、インジェクターは、このようなコンテキストでコードが実行される場合にのみ動作することを意味します。

注入コンテキストは、次の状況で使用できます。

- DIシステムによってインスタンス化されるクラス（`@Injectable` または `@Component` など）の構築（`constructor` を使用）中。
- このようなクラスのフィールドのイニシャライザー。
- `Provider` または `@Injectable` の `useFactory` に指定されたファクトリー関数。
- `InjectionToken` に指定された `factory` 関数。
- 注入コンテキストで実行されるスタックフレーム内。

注入コンテキストにいるかどうかを知ることで、[`inject`](api/core/inject) 関数を使用してインスタンスを注入できます。

NOTE: クラスコンストラクターとフィールドイニシャライザーでの `inject()` の基本的な使用例については、[概要ガイド](/guide/di#where-can-inject-be-used)を参照してください。

## コンテキスト内のスタックフレーム

一部のAPIは、注入コンテキストで実行されるように設計されています。これは、たとえば、ルーターガードの場合です。これにより、ガード関数内で [`inject`](api/core/inject) を使用してサービスにアクセスできます。

`CanActivateFn` の例を次に示します。

```ts
{highlight: [3]}
const canActivateTeam: CanActivateFn = (
  route: ActivatedRouteSnapshot,
  state: RouterStateSnapshot,
) => {
  return inject(PermissionsService).canActivate(inject(UserToken), route.params.id);
};
```

## 注入コンテキスト内で実行する

すでに注入コンテキスト内にいない状態で、特定の関数を注入コンテキスト内で実行したい場合は、`runInInjectionContext` を使用できます。
これには、たとえば `EnvironmentInjector` のような特定のインジェクターへのアクセスが必要です。

```ts
{highlight: [9], header"hero.service.ts"}
@Injectable({
  providedIn: 'root',
})
export class HeroService {
  private environmentInjector = inject(EnvironmentInjector);

someMethod() {
    runInInjectionContext(this.environmentInjector, () => {
      inject(SomeService); // 注入されたサービスで必要な処理を行います
    });
  }
}
```

[`inject`](/api/core/inject) は、インジェクターが要求されたトークンを解決できる場合にのみインスタンスを返します。

## コンテキストのアサート

Angularは、現在のコンテキストが注入コンテキストであることをアサートし、そうでない場合は明確なエラーをスローするための `assertInInjectionContext` ヘルパー関数を提供します。呼び出し元の関数への参照を渡すと、エラーメッセージが正しいAPIエントリーポイントを指し示すようになります。これにより、デフォルトの汎用的な注入エラーよりも明確で実用的なメッセージが生成されます。

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

export function injectNativeElement<T extends Element>(): T {
  assertInInjectionContext(injectNativeElement);
  return inject(ElementRef).nativeElement;
}
```

このヘルパーは、**注入コンテキスト内から**（コンストラクター、フィールドイニシャライザー、プロバイダーファクトリー、または `runInInjectionContext` 経由で実行されるコード）呼び出すことができます。

```ts
import {Component, inject} from '@angular/core';
import {injectNativeElement} from './dom-helpers';

@Component({
  /* … */
})
export class PreviewCard {
  readonly hostEl = injectNativeElement<HTMLElement>(); // フィールドイニシャライザーは注入コンテキスト内で実行されます。

onAction() {
    const anotherRef = injectNativeElement<HTMLElement>(); // 失敗: 注入コンテキスト外で実行されます。
  }
}
```

## コンテキスト外での DI の使用

注入コンテキスト外で [`inject`](api/core/inject) を呼び出したり、`assertInInjectionContext` を呼び出したりすると、[エラー NG0203](/errors/NG0203) がスローされます。
# 階層型インジェクター

このガイドでは、解決ルール、修飾子、および高度なパターンを含む、Angularの階層的な依存性の注入システムについて詳しく説明します。

NOTE: インジェクター階層とプロバイダースコープに関する基本概念については、[依存性プロバイダーの定義ガイド](guide/di/defining-dependency-providers#injector-hierarchy-in-angular)を参照してください。

## インジェクター階層のタイプ {#types-of-injector-hierarchies}

Angularには、次の2つのインジェクター階層があります。

| インジェクター階層            | 詳細                                                                                                                                                             |
| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `EnvironmentInjector` 階層   | `@Injectable()` または `ApplicationConfig` の `providers` 配列を使用して、この階層で `EnvironmentInjector` を構成します。                                            |
| `ElementInjector` 階層       | 各 DOM 要素で暗黙的に作成されます。 `ElementInjector` は、 `@Directive()` または `@Component()` の `providers` プロパティで構成しない限り、デフォルトでは空です。 |
`NgModule` ベースのアプリケーションの場合、`@NgModule()` または `@Injectable()` アノテーションを使用して、`ModuleInjector` 階層で依存関係を提供できます。
### `EnvironmentInjector`

`EnvironmentInjector` は、次のいずれかの方法で構成できます。

- `@Injectable()` の `providedIn` プロパティを使用して `root` または `platform` を参照する
- `ApplicationConfig` の `providers` 配列を使用する
`@Injectable()` の `providedIn` プロパティを使用することは、 `ApplicationConfig` の `providers` 配列を使用するよりも好ましいです。 `@Injectable()` の `providedIn` を使用すると、最適化ツールはツリーシェイクを実行して、アプリケーションで使用されていないサービスを削除できます。これにより、バンドルサイズが小さくなります。

ツリーシェイクは、特にライブラリにとって有用です。なぜなら、ライブラリを使用するアプリケーションは、ライブラリを注入する必要がない場合があるからです。
`EnvironmentInjector` は、 `ApplicationConfig.providers` によって構成されます。

`providedIn` を使用して、次のように `@Injectable()` を使用してサービスを提供します。

```ts
{highlight:[4]}
import {Injectable} from '@angular/core';

@Injectable({
  providedIn: 'root', // <--ルート EnvironmentInjector でこのサービスを提供します
})
export class ItemService {
  name = 'telephone';
}
```

`@Injectable()` デコレーターは、サービスクラスを識別します。
`providedIn` プロパティは、特定の `EnvironmentInjector`（ここでは `root`）を構成します。これにより、サービスは `root` `EnvironmentInjector` で使用可能になります。

### ModuleInjector

`NgModule` ベースのアプリケーションの場合、`ModuleInjector` は、次のいずれかの方法で構成できます。

- `@Injectable()` の `providedIn` プロパティを使用して `root` または `platform` を参照する
- `@NgModule()` の `providers` 配列を使用する

`ModuleInjector` は、 `@NgModule.providers` および `NgModule.imports` プロパティによって構成されます。 `ModuleInjector` は、 `NgModule.imports` を再帰的にたどることによって到達できるすべてのプロバイダー配列をフラット化したものです。

子 `ModuleInjector` 階層は、他の `@NgModules` を遅延読み込みするときに作成されます。

### プラットフォームインジェクター {#platform-injector}

`root` の上にさらに2つのインジェクター、追加の `EnvironmentInjector` と `NullInjector()` があります。

Angularが `main.ts` の次の内容でアプリケーションをブートストラップする方法を検討してください。

```ts
bootstrapApplication(AppComponent, appConfig);
```

`bootstrapApplication()` メソッドは、 `ApplicationConfig` インスタンスによって構成されたプラットフォームインジェクターの子インジェクターを作成します。
これが `root` `EnvironmentInjector` です。

`platformBrowserDynamic()` メソッドは、プラットフォーム固有の依存関係を含む `PlatformModule` によって構成されたインジェクターを作成します。
これにより、複数のアプリケーションがプラットフォーム構成を共有できます。
たとえば、ブラウザには、実行中のアプリケーションの数にかかわらず、URLバーは1つだけです。
`platformBrowser()` 関数を使用して `extraProviders` を提供することにより、プラットフォームレベルで追加のプラットフォーム固有のプロバイダーを構成できます。

階層の次の親インジェクターは `NullInjector()` で、ツリーのトップです。
ツリーをそこまで上に移動して `NullInjector()` 内でサービスを検索した場合、 `@Optional()` を使用していない限り、エラーが発生します。最終的にはすべて `NullInjector()` で終了し、エラーを返すか、 `@Optional()` の場合、 `null` を返します。
`@Optional()` の詳細については、このガイドの [`@Optional()` セクション](#optional) を参照してください。

次の図は、前の段落で説明したように、 `root` `ModuleInjector` とその親インジェクターの関係を表しています。

```mermaid
stateDiagram-v2
    elementInjector: EnvironmentInjector<br>(configured by Angular)<br>has special things like DomSanitizer => providedIn 'platform'
    rootInjector: root EnvironmentInjector<br>(configured by AppConfig)<br>has things for your app => bootstrapApplication(..., AppConfig)
    nullInjector: NullInjector<br>always throws an error unless<br>you use @Optional()

direction BT
    rootInjector --> elementInjector
    elementInjector --> nullInjector
```

`root` という名前は特別なエイリアスですが、他の `EnvironmentInjector` 階層にはエイリアスがありません。
動的にロードされたコンポーネントが作成されるたびに `EnvironmentInjector` 階層を作成するオプションがあります。たとえば、ルーターを使用すると、子 `EnvironmentInjector` 階層が作成されます。

`ApplicationConfig` インスタンスを `bootstrapApplication()` メソッドに渡して構成するか、 `root` で独自のサービスにすべてのプロバイダーを登録したかにかかわらず、すべての要求はルートインジェクターに転送されます。
`bootstrapApplication()` の `ApplicationConfig` でアプリケーション全体のプロバイダーを構成すると、 `@Injectable()` メタデータの `root` で構成されたプロバイダーがオーバーライドされます。
これは、複数のアプリケーションで共有されるサービスのデフォルト以外のプロバイダーを構成する場合に行うことができます。

コンポーネントルーターの構成にデフォルト以外の [ロケーション戦略](guide/routing#location-strategy) が含まれている場合、 `ApplicationConfig` の `providers` リストにそのプロバイダーをリストすることによって、その例を示します。

```ts
providers: [{provide: LocationStrategy, useClass: HashLocationStrategy}];
```

`NgModule` ベースのアプリケーションの場合、アプリケーション全体のプロバイダーを `AppModule` の `providers` で構成します。
### `ElementInjector`

Angularは、各DOM要素に対して `ElementInjector` 階層を暗黙的に作成します。

`@Component()` デコレーターの `providers` または `viewProviders` プロパティを使用してサービスを提供すると、 `ElementInjector` が構成されます。
たとえば、次の `TestComponent` は、次のようにサービスを提供することで `ElementInjector` を構成します。

```ts
{highlight:[3]}
@Component({
  /* … */
  providers: [{ provide: ItemService, useValue: { name: 'lamp' } }]
})
export class TestComponent
```

HELPFUL: [解決ルール](#resolution-rules) セクションを参照して、 `EnvironmentInjector` ツリー、 `ModuleInjector`、および `ElementInjector` ツリーの関係を理解してください。

コンポーネントでサービスを提供すると、そのサービスは、そのコンポーネントインスタンスの `ElementInjector` を介して使用可能になります。
[解決ルール](#resolution-rules) セクションで説明されている可視性ルールに基づいて、子コンポーネント/ディレクティブでも可視化される可能性があります。

コンポーネントインスタンスが破棄されると、そのサービスインスタンスも破棄されます。

#### `@Directive()` と `@Component()`

コンポーネントは特殊なタイプのディレクティブであるため、 `@Directive()` に `providers` プロパティがあるように、 `@Component()` にも `providers` プロパティがあります。
つまり、ディレクティブとコンポーネントは、 `providers` プロパティを使用してプロバイダーを構成できます。
`providers` プロパティを使用してコンポーネントまたはディレクティブのプロバイダーを構成すると、そのプロバイダーはそのコンポーネントまたはディレクティブの `ElementInjector` に属します。
同じ要素上のコンポーネントとディレクティブは、インジェクターを共有します。

## 解決ルール {#resolution-rules}

コンポーネント/ディレクティブのトークンを解決する場合、Angularは次の2つのフェーズで解決します。

1. `ElementInjector` 階層の親に対して。
2. `EnvironmentInjector` 階層の親に対して。

コンポーネントが依存関係を宣言すると、Angularはその依存関係を自身の `ElementInjector` で満たそうとします。
コンポーネントのインジェクターにプロバイダーがない場合、そのリクエストを親コンポーネントの `ElementInjector` に渡します。

リクエストは、Angularがリクエストを処理できるインジェクターを見つけるか、祖先 `ElementInjector` 階層を使い果たすまで、転送され続けます。

Angularがいずれの `ElementInjector` 階層でもプロバイダーを見つけられない場合、リクエストが発生した要素に戻り、 `EnvironmentInjector` 階層を調べます。
それでもAngularがプロバイダーを見つけられない場合、エラーをスローします。

同じDIトークンのプロバイダーを異なるレベルで登録した場合、Angularが最初に遭遇するプロバイダーが、依存関係を解決するために使用するプロバイダーです。
たとえば、サービスを必要とするコンポーネントにプロバイダーがローカルに登録されている場合、
Angularは同じサービスの別のプロバイダーを探しません。

HELPFUL: `NgModule` ベースのアプリケーションの場合、Angularは `ElementInjector` 階層でプロバイダーが見つからない場合、 `ModuleInjector` 階層を検索します。

## 解決修飾子 {#resolution-modifiers}

Angularの解決動作は、`optional`、`self`、`skipSelf`、および `host` を使用して変更できます。
`@angular/core` からそれぞれをインポートし、サービスを注入するときに [`inject`](/api/core/inject) 構成でそれぞれを使用します。

### 修飾子の種類 {#types-of-modifiers}

解決修飾子は、次の3つのカテゴリーに分類されます。

- Angularが探しているものを見つけられない場合にどうするか、つまり `optional`
- どこから探し始めるか、つまり `skipSelf`
- どこで探すのをやめるか、`host` および `self`

デフォルトでは、Angularは常に現在の `Injector` から始めて、すべてを上に検索し続けます。
修飾子を使用すると、開始位置（または _self_ 位置）と終了位置を変更できます。

さらに、次の修飾子を除いて、すべての修飾子を組み合わせることができます。

- `host` と `self`
- `skipSelf` と `self`

### `optional`

`optional` を使用すると、Angularは注入するサービスをオプションと見なすことができます。
そのため、実行時に解決できない場合、Angularはサービスをエラーをスローするのではなく、 `null` として解決します。
次の例では、サービス `OptionalService` はサービス `ApplicationConfig`や`@NgModule()`、コンポーネントクラスで提供されていないため、アプリケーションのどこにも使用できません。

```ts
{header:"src/app/optional/optional.component.ts"}
export class OptionalComponent {
  public optional? = inject(OptionalService, {optional: true});
}
```

### `self`

`self` を使用すると、Angularは現在のコンポーネントまたはディレクティブの `ElementInjector` のみを調べます。

`self` の適切なユースケースは、サービスを注入するが、現在のホスト要素で使用可能な場合のみにすることです。
このような状況でエラーを回避するには、`self` を `optional` と組み合わせます。

たとえば、次の `SelfNoDataComponent` では、プロパティとして注入された `LeafService` に注目してください。

```ts
{header: 'self-no-data.component.ts', highlight: [7]}
@Component({
  selector: 'app-self-no-data',
  templateUrl: './self-no-data.component.html',
  styleUrls: ['./self-no-data.component.css'],
})
export class SelfNoDataComponent {
  public leaf = inject(LeafService, {optional: true, self: true});
}
```

この例では、親プロバイダーがあり、サービスを注入すると値が返されますが、`self` と `optional` を使用してサービスを注入すると `null` が返されます。これは、`self` がインジェクターに現在のホスト要素で検索を停止するよう指示するためです。

別の例では、 `FlowerService` のプロバイダーを備えたコンポーネントクラスを示しています。
この場合、インジェクターは現在の `ElementInjector` より先を見ずに、 `FlowerService` を見つけて、チューリップ 🌷 を返します。

```ts
{header:"src/app/self/self.component.ts"}
@Component({
  selector: 'app-self',
  templateUrl: './self.component.html',
  styleUrls: ['./self.component.css'],
  providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}],
})
export class SelfComponent {
  constructor(@Self() public flower: FlowerService) {}
}
```

### `skipSelf`

`skipSelf` は `self` の反対です。
`skipSelf` を使用すると、Angularは現在の `ElementInjector` ではなく、親 `ElementInjector` でサービスの検索を開始します。
そのため、親`ElementInjector`が`emoji`にシダ<code>🌿</code>値を使用していたが、コンポーネントの`providers`配列にカエデの葉<code>🍁</code>が含まれている場合、Angularはカエデの葉<code>🍁</code>を無視して、シダ<code>🌿</code>を使用します。

これをコードで確認するために、親コンポーネントが使用する `emoji` の次の値を想定します。これは、このサービスと同じです。

```ts
{header: 'leaf.service.ts'}
export class LeafService {
  emoji = '🌿';
}
```

子コンポーネントに、異なる値、カエデの葉 🍁 が含まれていると想像してください。ただし、親の値を使用したいとします。
これが `skipSelf` を使用する場合です。

```ts
{header:"skipself.component.ts" highlight:[[6],[10]]}
@Component({
  selector: 'app-skipself',
  templateUrl: './skipself.component.html',
  styleUrls: ['./skipself.component.css'],
  // Angular はこの LeafService インスタンスを無視します
  providers: [{provide: LeafService, useValue: {emoji: '🍁'}}],
})
export class SkipselfComponent {
  // Use skipSelf as inject option
  public leaf = inject(LeafService, {skipSelf: true});
}
```

この場合、 `emoji` に対して取得する値は、カエデの葉 <code>🍁</code> ではなく、シダ <code>🌿</code> になります。

#### `skipSelf` オプションと `optional` {#skipself-option-with-optional}

値が `null` の場合にエラーを防ぐために、`skipSelf` オプションを `optional` と一緒に使用します。

次の例では、 `Person` サービスはプロパティの初期化中に注入されます。
`skipSelf` はAngularに現在のインジェクターをスキップするよう指示し、`optional` は `Person` サービスが `null` の場合にエラーを防ぎます。

```ts
class Person {
  parent = inject(Person, {optional: true, skipSelf: true});
}
```

### `host`

`host` を使用すると、プロバイダーを検索するときに、コンポーネントをインジェクターツリーの最後の停止点として指定できます。

ツリーのさらに上にサービスインスタンスがある場合でも、Angularは検索を続けません。
`host` を次のように使用します。

```ts
{header:"host.component.ts" highlight:[[6],[9]]}
@Component({
  selector: 'app-host',
  templateUrl: './host.component.html',
  styleUrls: ['./host.component.css'],
  // provide the service
  providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}],
})
export class HostComponent {
  // use host when injecting the service
  flower = inject(FlowerService, {host: true, optional: true});
}
```

`HostComponent`に`host`オプションがあるため、`HostComponent`の親が`flower.emoji`にどのような値を持っていても、`HostComponent`はチューリップ<code>🌷</code>を使用します。

### コンストラクター注入での修飾子 {#modifiers-with-constructor-injection}

前に示したように、コンストラクター注入の動作は、`@Optional()`、`@Self()`、`@SkipSelf()`、および `@Host()` を使用して変更できます。

`@angular/core` からそれぞれをインポートし、サービスを注入するときにコンポーネントクラスのコンストラクターでそれぞれを使用します。

```ts
{header:"self-no-data.component.ts" highlight:[2]}
export class SelfNoDataComponent {
  constructor(@Self() @Optional() public leaf?: LeafService) {}
}
```

## テンプレートの論理構造 {#logical-structure-of-the-template}

コンポーネントクラスでサービスを提供する場合、サービスは、サービスの提供場所と方法に応じて、 `ElementInjector` ツリー内で可視になります。

Angularテンプレートの基になる論理構造を理解すると、サービスの構成と、その可視性の制御のための基礎が得られます。

コンポーネントは、次の例のようにテンプレートで使用されます。

```html
<app-root> <app-child />; </app-root>
```

HELPFUL: 通常、コンポーネントとそのテンプレートは別々のファイルに宣言します。
注入システムの動作を理解するために、それらを組み合わせた論理ツリーの視点から見ると便利です。
用語 _論理_ は、アプリケーションのDOMツリーであるレンダリングツリーと区別しています。
コンポーネントテンプレートの場所を示すために、このガイドでは `<#VIEW>` 疑似要素を使用します。この疑似要素は、レンダリングツリーには実際に存在せず、メンタルモデルの目的でのみ存在します。

以下は、 `<app-root>` と `<app-child>` のビューツリーを1つの論理ツリーに結合した例です。

```html
<app-root>
  <#VIEW>
    <app-child>
     <#VIEW>
       …content goes here…
     </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

`<#VIEW>` の区切りの考え方を理解することは、特にコンポーネントクラスでサービスを構成する場合に重要です。

## 例： `@Component()` でサービスを提供する {#example-providing-services-in-component}

`@Component()`（または `@Directive()`）デコレーターを使用してサービスを提供する方法は、サービスの可視性を決めます。
次のセクションでは、`providers` と `viewProviders` について、および `skipSelf` と `host` を使用してサービスの可視性を変更する方法を説明します。

コンポーネントクラスでは、次の2つの方法でサービスを提供できます。

| 配列                         | 詳細                                           |
| :--------------------------- | :--------------------------------------------- |
| `providers` 配列を使用する     | `@Component({ providers: [SomeService] })`     |
| `viewProviders` 配列を使用する | `@Component({ viewProviders: [SomeService] })` |

次の例では、Angularアプリケーションの論理ツリーが表示されます。
テンプレートのコンテキストでインジェクターがどのように動作するかを示すために、論理ツリーはアプリケーションのHTML構造を表します。
たとえば、論理ツリーは、 `<child-component>` が `<parent-component>` の直接の子であることを示します。

論理ツリーでは、 `@Provide` 、 `@Inject` 、および `@ApplicationConfig` という特殊な属性が表示されます。
これらは実際の属性ではなく、内部で何が起こっているかを説明するためにここにあります。

### アプリケーション構造の例 {#example-app-structure}

この例では、 `emoji` の値が赤いハイビスカス <code>🌺</code> である、 `root` に提供される `FlowerService` があります。

```ts
{header:"lower.service.ts"}
@Injectable({
  providedIn: 'root',
})
export class FlowerService {
  emoji = '🌺';
}
```

`AppComponent` と `ChildComponent` のみが含まれるアプリケーションを検討してください。
最も基本的なレンダリングされたビューは、次のようなネストされたHTML要素のように見えます。

```html
<app-root>
  
  <app-child>  </app-child>
</app-root>
```

ただし、裏側では、Angularはインジェクションリクエストを解決するときに、次のような論理ビュー表現を使用します。

```html
<app-root> 
  <#VIEW>
    <app-child> 
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

ここでの `<#VIEW>` は、テンプレートのインスタンスを表しています。
各コンポーネントには、独自の `<#VIEW>` があることに注意してください。

この構造を理解することで、サービスの提供方法と注入方法を把握し、サービスの可視性を完全に制御できます。

次に、 `<app-root>` が `FlowerService` を注入しているとします。

```typescript
export class AppComponent {
  flower = inject(FlowerService);
}
```

結果を視覚化するために、 `<app-root>` テンプレートにバインディングを追加します。

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

ビューに出力されるのは次のとおりです。

```shell
Emoji from FlowerService: 🌺
```

論理ツリーでは、これは次のように表されます。

```html
<app-root @ApplicationConfig
        @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
    <p>Emoji from FlowerService: {{flower.emoji}} (🌺)</p>
    <app-child>
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

`<app-root>` が `FlowerService` を要求すると、インジェクターは `FlowerService` トークンを解決します。
トークンの解決は次の2つのフェーズで行われます。

1. インジェクターは、論理ツリー内の開始位置と検索の終了位置を決定します。
   インジェクターは開始位置から始めて、論理ツリーの各ビューレベルでトークンを検索します。
   トークンが見つかると、そのトークンが返されます。

1. トークンが見つからない場合、インジェクターはリクエストを委任する最も近い親 `EnvironmentInjector` を検索します。

この例の場合、制約は次のとおりです。

1. `<app-root>` に属する `<#VIEW>` から始めて、 `<app-root>` で終了します。
   - 通常、検索の開始点は注入ポイントです。
     ただし、この場合、 `<app-root>` はコンポーネントです。 `@Component` は特殊で、独自の `viewProviders` も含まれています。そのため、検索は `<app-root>` に属する `<#VIEW>` から開始されます。
     これは、同じ場所に一致するディレクティブでは発生しません。
   - 終了位置は、コンポーネント自体と同じになります。なぜなら、これはこのアプリケーションの最上位コンポーネントだからです。

1. `ApplicationConfig` によって提供される `EnvironmentInjector` は、インジェクショントークンが `ElementInjector` 階層で見つからない場合のフォールバックインジェクターとして機能します。

### `providers` 配列を使用する {#using-the-providers-array}

次に、 `ChildComponent` クラスで、今後のセクションでより複雑な解決ルールを説明するために、 `FlowerService` のプロバイダーを追加します。

```ts
@Component({
  selector: 'app-child',
  templateUrl: './child.component.html',
  styleUrls: ['./child.component.css'],
  // use the providers array to provide a service
  providers: [{provide: FlowerService, useValue: {emoji: '🌻'}}],
})
export class ChildComponent {
  // inject the service
  flower = inject(FlowerService);
}
```

`FlowerService` が `@Component()` デコレーターで提供されるようになったため、 `<app-child>` がサービスを要求すると、インジェクターは `<app-child>` の `ElementInjector` ほど遠くまでしか見なくてもよくなります。
インジェクターは、インジェクターツリーをさらに検索する必要はありません。

次のステップは、 `ChildComponent` テンプレートにバインディングを追加することです。

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

新しい値をレンダリングするために、ビューにひまわりも表示されるように、 `AppComponent` テンプレートの下部に `<app-child>` を追加します。

```shell
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>`（`@Component()` から注入されるため `<#VIEW>` が含まれています）から始めて、 `<app-child>` で終了します。
この場合、 `FlowerService` は、 `<app-child>` の `providers` 配列で、ひまわり <code>🌻</code> を使用して解決されます。
インジェクターは、インジェクターツリーをさらに検索する必要はありません。
`FlowerService` を見つけるとすぐに停止し、赤いハイビスカス <code>🌺</code> は見えません。

### `viewProviders` 配列を使用する {#using-the-viewproviders-array}

`viewProviders` 配列は、 `@Component()` デコレーターでサービスを提供する別の方法です。
`viewProviders` を使用すると、サービスは `<#VIEW>` で可視になります。

HELPFUL: ステップは `providers` 配列を使用する場合と同じですが、 `viewProviders` 配列を使用する点が異なります。

ステップバイステップの手順については、このセクションを続行してください。
自分で設定できる場合は、[サービスの可用性を変更する](#visibility-of-provided-tokens) に進んでください。

デモのために、 `AnimalService` を作成して、 `viewProviders` を示します。
最初に、 `emoji` プロパティがクジラ <code>🐳</code> である `AnimalService` を作成します。

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

@Injectable({
  providedIn: 'root',
})
export class AnimalService {
  emoji = '🐳';
}
```

`FlowerService` と同じパターンに従って、 `AppComponent` クラスに `AnimalService` を注入します。

```ts
export class AppComponent {
  public flower = inject(FlowerService);
  public animal = inject(AnimalService);
}
```

HELPFUL: `FlowerService` に関連するコードはすべてそのままにしておくことができます。これにより、 `AnimalService` との比較が可能になります。

`viewProviders` 配列を追加し、 `<app-child>` クラスにも `AnimalService` を注入しますが、 `emoji` に異なる値を与えます。
ここでは、犬 🐶 の値があります。

```typescript
@Component({
  selector: 'app-child',
  templateUrl: './child.component.html',
  styleUrls: ['./child.component.css'],
  // provide services
  providers: [{provide: FlowerService, useValue: {emoji: '🌻'}}],
  viewProviders: [{provide: AnimalService, useValue: {emoji: '🐶'}}],
})
export class ChildComponent {
  // inject services
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

`ChildComponent` と `AppComponent` のテンプレートにバインディングを追加します。
`ChildComponent` テンプレートに、次のバインディングを追加します。

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

さらに、 `AppComponent` テンプレートにも同じものを追加します。

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
s
```

これで、ブラウザに両方の値が表示されます。

```shell
AppComponent
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` と `viewProviders` の違い {#providers-vs-viewproviders}

`viewProviders` フィールドは、概念的には `providers` と似ていますが、1つの顕著な違いがあります。
`viewProviders` で構成されたプロバイダーは、コンポーネントの論理的な子になる投影されたコンテンツには可視ではありません。

`providers` と `viewProviders` の違いを確認するために、別のコンポーネントを例に追加して、 `InspectorComponent` と呼びます。
`InspectorComponent` は、 `ChildComponent` の子になります。
`inspector.component.ts` では、プロパティの初期化中に `FlowerService` と `AnimalService` を注入します。

```typescript
export class InspectorComponent {
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

`providers` または `viewProviders` 配列は必要ありません。
次に、 `inspector.component.html` に、以前のコンポーネントと同じマークアップを追加します。

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

`InspectorComponent` を `ChildComponent` の `imports` 配列に追加することを忘れないでください。

```ts
@Component({
  ...
  imports: [InspectorComponent]
})
```

次に、 `child.component.html` に次を追加します。

```html
...

<div class="container">
  <h3>Content projection</h3>
  <ng-content />
</div>
<h3>Inside the view</h3>

<app-inspector />
```

`<ng-content>` を使用するとコンテンツを投影でき、 `ChildComponent` テンプレート内の `<app-inspector>` は、 `InspectorComponent` を `ChildComponent` の子コンポーネントにします。

次に、コンテンツ投影を活用するために、 `app.component.html` に次を追加します。

```html
<app-child>
  <app-inspector />
</app-child>
```

これで、ブラウザには、以前の例は省略して、次のものがレンダリングされます。

```shell
...
Content projection

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐳

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐶
```

これらの4つのバインディングは、 `providers` と `viewProviders` の違いを示しています。
犬の絵文字 <code>🐶</code> は、 `ChildComponent` の `<#VIEW>` 内に宣言され、投影されたコンテンツには可視ではないことを覚えておいてください。
代わりに、投影されたコンテンツには、クジラ <code>🐳</code> が表示されます。

ただし、次の出力セクションでは `InspectorComponent` は `ChildComponent` の実際の子コンポーネントです。そして `InspectorComponent` は `<#VIEW>` の内側にあるため、 `AnimalService` を要求すると、犬 <code>🐶</code> が表示されます。

論理ツリー内の `AnimalService` は、次のようになります。

```html
<app-root @ApplicationConfig
          @Inject(AnimalService) animal=>"🐳">
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService=>"🐶")>

<p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>

<div class="container">
      <h3>Content projection</h3>
      <app-inspector @Inject(AnimalService) animal=>"🐳">
        <p>Emoji from AnimalService: {{animal.emoji}} (🐳)</p>
      </app-inspector>
    </div>

<app-inspector>
      <#VIEW @Inject(AnimalService) animal=>"🐶">
      <p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>
    </
    #VIEW>
    </app-inspector>
  </
  #VIEW>
  </app-child>

</#VIEW>
</app-root>
```

`<app-inspector>` の投影されたコンテンツには、クジラ <code>🐳</code> が表示され、犬 <code>🐶</code> は表示されません。これは、犬 <code>🐶</code> が `<app-child>` の `<#VIEW>` の内側にあるためです。
`<app-inspector>` は、 `<#VIEW>` の内側にある場合にのみ、犬 <code>🐶</code> を表示できます。

### 提供されたトークンの可視性 {#visibility-of-provided-tokens}

可視性デコレーターは、論理ツリー内でインジェクショントークンの検索を開始する場所と終了する場所を制御します。
これを行うには、宣言のポイントではなく、注入のポイント、つまり `inject()` を呼び出すときに可視性構成を配置します。

インジェクターが `FlowerService` の検索を開始する場所を変更するには、`FlowerService` が注入される `<app-child>` の `inject()` 呼び出しに `skipSelf` を追加します。
この呼び出しは、`child.component.ts` に示すように、`<app-child>` のプロパティ初期化子です。

```typescript
flower = inject(FlowerService, {skipSelf: true});
```

`skipSelf` を使用すると、`<app-child>` インジェクターは `FlowerService` を自分自身で探しません。
代わりに、インジェクターは `<app-root>` の `ElementInjector` で `FlowerService` の検索を開始し、何も見つかりません。
次に、 `<app-child>` の `ModuleInjector` に戻り、 `<app-child>` と `<app-root>` が同じ `ModuleInjector` を共有しているため、赤いハイビスカス <code>🌺</code> 値が見つかります。
UIには次のように表示されます。

```shell
Emoji from FlowerService: 🌺
```

論理ツリーでは、この同じ考え方は次のようになります。

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
  <app-child @Provide(FlowerService="🌻" )>
    <#VIEW @Inject(FlowerService, SkipSelf)=>"🌺">

</
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

`<app-child>`がひまわり<code>🌻</code>を提供しているにもかかわらず、アプリケーションは赤いハイビスカス<code>🌺</code>をレンダリングします。これは、`skipSelf`が現在のインジェクター（`app-child`）に自身をスキップして親を探すよう指示するためです。

今度、（`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-parent>
</#VIEW>
</app-root>
```

ここでは、サービスとその値は同じですが、`host` はインジェクターが `<#VIEW>` より先を `FlowerService` について探すのを止めるため、見つからずに `null` を返します。

### `skipSelf` と `viewProviders` {#skipself-and-viewproviders}

覚えておいてください。 `<app-child>` は、 `viewProviders` 配列で `AnimalService` を提供し、その値は犬 <code>🐶</code> です。
インジェクターは、 `<app-child>` の `ElementInjector` を `AnimalService` について調べるだけなので、クジラ <code>🐳</code> は見えません。

`FlowerService` の例と同様に、`AnimalService` の `inject()` に `skipSelf` を追加すると、インジェクターは現在の `<app-child>` の `ElementInjector` で `AnimalService` を探しません。
代わりに、インジェクターは `<app-root>` の `ElementInjector` で検索を開始します。

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ],
})
```

論理ツリーは、`<app-child>` で `skipSelf` を使用すると次のようになります。

```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`の検索を開始し、クジラ🐳を見つけます。

### `host` と `viewProviders` {#host-and-viewproviders}

`AnimalService`のインジェクションに`host`だけを使用する場合、インジェクターは`<app-child>`の`<#VIEW>`自体で`AnimalService`を見つけるため、結果は犬<code>🐶</code>になります。
`ChildComponent`は`viewProviders`を設定し、犬の絵文字が`AnimalService`の値として提供されます。
`inject()`では`host`も使用できます：

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ]
})
export class ChildComponent {
  animal = inject(AnimalService, { host: true })
}
```

`host: true` はインジェクターに `<#VIEW>` の端に遭遇するまで探すよう指示します。

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    inject(AnimalService, {host: true}=>"🐶")> 
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

3番目の動物、ハリネズミ <code>🦔</code> を含む `viewProviders` 配列を、 `app.component.ts` の `@Component()` メタデータに追加します。

```typescript
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: [ './app.component.css' ],
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🦔' } },
  ],
})
```

次に、`child.component.ts` の `AnimalService` 注入の `inject()` に `host` とともに `skipSelf` を追加します。
`animal` プロパティの初期化における `host` と `skipSelf` は次のとおりです。

```typescript
export class ChildComponent {
  animal = inject(AnimalService, {host: true, skipSelf: true});
}
```

`providers` 配列にある `FlowerService` に `host` と `skipSelf` を適用した場合、結果は `null` でした。これは、`skipSelf` が `<app-child>` インジェクターで検索を開始しますが、`host` は `<#VIEW>` で検索を停止するためです。そこには `FlowerService` がありません。
論理ツリーでは、 `FlowerService` は `<app-child>` で可視であり、 `<#VIEW>` では可視ではないことがわかります。

ただし、 `AppComponent` の `viewProviders` 配列で提供されている `AnimalService` は可視です。

論理ツリーの表現は、これが理由を示しています。

```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> を見つけます。

## 例： `ElementInjector` のユースケース {#example-elementinjector-use-cases}

さまざまなレベルで1つ以上のプロバイダーを構成する機能により、便利な可能性が開かれます。

### シナリオ：サービスの分離 {#scenario-service-isolation}

アーキテクチャ上の理由から、サービスへのアクセスを属するアプリケーションドメインに制限する必要がある場合があります。
たとえば、悪役のリストを表示する `VillainsListComponent` を構築するとします。
この悪役は、 `VillainsService` から取得されます。

`VillainsService` をルートの `AppModule` で提供すると、 `VillainsService` がアプリケーションのすべての場所で可視になります。
後で `VillainsService` を変更した場合、誤ってこのサービスに依存し始めた他のコンポーネントで何かが壊れる可能性があります。

代わりに、次のように `VillainsListComponent` の `providers` メタデータで `VillainsService` を提供する必要があります。

```typescript
@Component({
  selector: 'app-villains-list',
  templateUrl: './villains-list.component.html',
  providers: [VillainsService],
})
export class VillainsListComponent {}
```

`VillainsService` を `VillainsListComponent` メタデータで提供し、他の場所では提供しないと、サービスは `VillainsListComponent` とそのサブコンポーネントツリーのみに使用可能になります。

`VillainService` は、 `VillainsListComponent` に対してシングルトンです。なぜなら、それが宣言されている場所だからです。
`VillainsListComponent` が破棄されない限り `VillainService` のインスタンスは同じです。ただし `VillainsListComponent` のインスタンスが複数ある場合、 `VillainsListComponent` の各インスタンスには、独自の `VillainService` インスタンスが1つずつあります。

### シナリオ：複数の編集セッション {#scenario-multiple-edit-sessions}

多くのアプリケーションでは、ユーザーは同時に複数のオープンタスクで作業できます。
たとえば、税務申告の作成アプリケーションでは、作成者は複数の税務申告で作業し、1日を通してそれらを切り替えることができます。

そのシナリオを示すために、スーパーヒーローのリストを表示する `HeroListComponent` を考えてみてください。

ヒーローの税務申告を開くために、作成者はヒーローの名前をクリックすると、その申告を編集するためのコンポーネントが開きます。
選択したヒーローの税務申告は、それぞれ独自のコンポーネントで開き、複数の申告を同時に開くことができます。

各税務申告コンポーネントには、次の機能があります。

- 独自の税務申告の編集セッションを持ちます
- 別のコンポーネントの申告に影響を与えずに税務申告を変更できます
- 税務申告の変更を保存するか、キャンセルする機能があります

`HeroTaxReturnComponent` に、変更を管理および復元するためのロジックがあるとします。
これは、ヒーローの税務申告にとっては簡単なタスクです。
現実世界では、豊富な税務申告データモデルでは、変更管理が複雑になります。
この例のように、この管理をヘルパーサービスに委任できます。

`HeroTaxReturnService` は、単一の `HeroTaxReturn` をキャッシュし、その申告への変更を追跡し、保存または復元できます。
また、注入によって取得したアプリケーション全体のシングルトン `HeroService` に委任します。

```typescript
import {inject, Injectable} from '@angular/core';
import {HeroTaxReturn} from './hero';
import {HeroesService} from './heroes.service';

@Injectable()
export class HeroTaxReturnService {
  private currentTaxReturn!: HeroTaxReturn;
  private originalTaxReturn!: HeroTaxReturn;

private heroService = inject(HeroesService);

set taxReturn(htr: HeroTaxReturn) {
    this.originalTaxReturn = htr;
    this.currentTaxReturn = htr.clone();
  }

get taxReturn(): HeroTaxReturn {
    return this.currentTaxReturn;
  }

restoreTaxReturn() {
    this.taxReturn = this.originalTaxReturn;
  }

saveTaxReturn() {
    this.taxReturn = this.currentTaxReturn;
    this.heroService.saveTaxReturn(this.currentTaxReturn).subscribe();
  }
}
```

以下は、 `HeroTaxReturnService` を使用する `HeroTaxReturnComponent` です。

```typescript
import {Component, input, output} from '@angular/core';
import {HeroTaxReturn} from './hero';
import {HeroTaxReturnService} from './hero-tax-return.service';

@Component({
  selector: 'app-hero-tax-return',
  templateUrl: './hero-tax-return.component.html',
  styleUrls: ['./hero-tax-return.component.css'],
  providers: [HeroTaxReturnService],
})
export class HeroTaxReturnComponent {
  message = '';

close = output<void>();

get taxReturn(): HeroTaxReturn {
    return this.heroTaxReturnService.taxReturn;
  }

taxReturn = input.required<HeroTaxReturn>();

constructor() {
    effect(() => {
      this.heroTaxReturnService.taxReturn = this.taxReturn();
    });
  }

private heroTaxReturnService = inject(HeroTaxReturnService);

onCanceled() {
    this.flashMessage('Canceled');
    this.heroTaxReturnService.restoreTaxReturn();
  }

onClose() {
    this.close.emit();
  }

onSaved() {
    this.flashMessage('Saved');
    this.heroTaxReturnService.saveTaxReturn();
  }

flashMessage(msg: string) {
    this.message = msg;
    setTimeout(() => (this.message = ''), 500);
  }
}
```

_編集対象の税務申告_ は、 `input` プロパティを介して到着します。これは、ゲッターとセッターで実装されています。
セッターは、コンポーネント自身の `HeroTaxReturnService` インスタンスを、受信した申告で初期化します。
ゲッターは常に、そのサービスがヒーローの現在の状態であると判断したものを返します。
コンポーネントは、この税務申告を保存および復元することもサービスに要求します。

これは、サービスがアプリケーション全体のシングルトンである場合に機能しません。
すべてのコンポーネントは同じサービスインスタンスを共有し、各コンポーネントは別のヒーローに属する税務申告を上書きします。

これを防ぐために、コンポーネントレベルのインジェクター `HeroTaxReturnComponent` を構成して、コンポーネントメタデータの `providers` プロパティを使用してサービスを提供します。

```typescript
providers: [HeroTaxReturnService];
```

`HeroTaxReturnComponent` には、 `HeroTaxReturnService` の独自の提供者がいます。
覚えておいてください。すべてのコンポーネントの _インスタンス_ には、独自のインジェクターがあります。
コンポーネントレベルでサービスを提供すると、コンポーネントの _すべての_ インスタンスは、サービスのプライベートインスタンスを1つずつ取得することが保証されます。これにより、税務申告が上書きされないようにします。

HELPFUL: シナリオコードの残りは、ドキュメントの他の場所で学習できる他のAngular機能とテクニックに依存しています。

### シナリオ：特殊なプロバイダー {#scenario-specialized-providers}

別のレベルでサービスを再度提供するもう1つの理由は、コンポーネントツリーのさらに深い場所で、そのサービスの _より特殊な_ 実装を置き換えるためです。

たとえば、タイヤサービスの情報を含み、他のサービスに依存して車の詳細情報を提供する `Car` コンポーネントを検討してください。

ルートインジェクター（(A) とマーク付け）は、 `CarService` と `EngineService` について、_汎用的な_ プロバイダーを使用します。

1. `Car` コンポーネント (A)。コンポーネント (A) は、車のタイヤサービスデータを表示し、車の詳細情報を提供するための汎用サービスを指定します。

2. 子コンポーネント (B)。コンポーネント (B) は、コンポーネント (B) で行われていることに適した特別な機能を持つ、 `CarService` と `EngineService` の独自の _特殊な_ プロバイダーを定義します。

3. コンポーネント (B) の子である子コンポーネント (C)。コンポーネント (C) は、 `CarService` の独自の、さらに _特殊な_ プロバイダーを定義します。

```mermaid
graph TD;
subgraph COMPONENT_A[Component A]
subgraph COMPONENT_B[Component B]
COMPONENT_C[Component C]
end
end

style COMPONENT_A fill:#BDD7EE
style COMPONENT_B fill:#FFE699
style COMPONENT_C fill:#A9D18E,color:#000
classDef noShadow filter:none
class COMPONENT_A,COMPONENT_B,COMPONENT_C noShadow
```

裏側では、各コンポーネントはコンポーネント自体に定義された、0、1または複数のプロバイダーで独自のインジェクターを設定します。

最も深いコンポーネント (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

class car,engine,tires,RootInjector,ParentInjector,ChildInjector,ServicesA,ServicesB,ServicesC,A,B,C noShadow
style car fill:#A9D18E,color:#000
style ChildInjector fill:#A9D18E,color:#000
style engine fill:#FFE699,color:#000
style ParentInjector fill:#FFE699,color:#000
style tires fill:#BDD7EE,color:#000
style RootInjector fill:#BDD7EE,color:#000
```

## 依存性の注入の詳細 {#more-on-dependency-injection}
# 軽量インジェクショントークンを使用したクライアントアプリケーションサイズの最適化

このページでは、ライブラリ開発者に推奨される依存性の注入テクニックの概要を概念的に説明します。
_軽量インジェクショントークン_ を使用してライブラリを設計すると、ライブラリを使用するクライアントアプリケーションのバンドルサイズを最適化できます。

ツリーシェイク可能なプロバイダーを使用することで、コンポーネントと注入可能なサービス間の依存関係の構造を管理してバンドルサイズを最適化できます。
通常、これにより、アプリケーションで実際に使用されていない提供されたコンポーネントまたはサービスが、コンパイラによってバンドルから削除されます。

Angularがインジェクショントークンを格納する方法により、使用されていないコンポーネントまたはサービスがバンドルに含まれてしまう場合があります。
このページでは、軽量なインジェクショントークンを使用することで適切なツリーシェイクをサポートする依存性の注入の設計パターンについて説明します。

軽量なインジェクショントークン設計パターンは、特にライブラリ開発者にとって重要です。
これにより、アプリケーションがライブラリの機能の一部のみを使用する場合、未使用のコードをクライアントのアプリケーションバンドルから削除できます。

アプリケーションがライブラリを使用する場合、ライブラリが提供するサービスの中には、クライアントアプリケーションで使用されないものがある場合があります。
この場合、アプリケーション開発者は、そのサービスがツリーシェイクされ、コンパイルされたアプリケーションのサイズに影響を与えないことを期待する必要があります。
アプリケーション開発者はライブラリのツリーシェイクの問題を認識したり、修正したりできないため、ライブラリ開発者の責任となります。
未使用のコンポーネントの保持を防ぐため、ライブラリでは軽量インジェクショントークン設計パターンを使用する必要があります。

## トークンが保持される場合

トークン保持が発生する状況をより明確に説明するために、ライブラリカードコンポーネントを提供するライブラリを検討してください。
このコンポーネントには本体が含まれており、オプションでヘッダーを含めることができます。

```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` への参照が2つあるためです。

```ts
readonly header = contentChild(LibHeader);
```

- これらの参照の1つは _型の位置_ にあります。つまり、 `LibHeader` を型として指定します: `readonly header: Signal<LibHeader|undefined>`。
- もう1つの参照は _値の位置_ にあります。つまり、`LibHeader` は `contentChild` 関数に渡される値です: `contentChild(LibHeader)`。

コンパイラはこれらの位置にあるトークン参照を異なる方法で処理します。

- コンパイラは、TypeScriptから変換した後の _型の位置_ の参照を消去するため、ツリーシェイクには影響しません。
- コンパイラは、_値の位置_ の参照をランタイムに保持する必要があり、これが**妨げます** コンポーネントがツリーシェイクされること。

この例では、コンパイラは値位置にある `LibHeader` トークンを保持します。
これにより、アプリケーションで実際に `<lib-header>` をどこでも使用していない場合でも、参照されるコンポーネントがツリーシェイクされることがなくなります。
`LibHeader` のコード、テンプレート、スタイルを組み合わせると大きくなりすぎるため、不要に含めるとクライアントアプリケーションのサイズが大幅に増加する可能性があります。

## 軽量インジェクショントークンパターンを使用する場合

ツリーシェイクの問題は、コンポーネントがインジェクショントークンとして使用されると発生します。
これは次の2つのケースで発生します。

- トークンは、[コンテンツクエリ](guide/components/queries#content-queries)で値の位置で使用されます。
- トークンは、コンストラクター注入の型指定子として使用されます。

次の例では、 `OtherComponent` トークンの両方の使用により、 `OtherComponent` が保持され、使用されていない場合にツリーシェイクされることがなくなります。

```ts
{highlight: [[2],[4]]}
class MyComponent {
  constructor(@Optional() other: OtherComponent) {}

@ContentChild(OtherComponent) other: OtherComponent | null;
}
```

型指定子としてのみ使用されるトークンは、JavaScriptに変換されると削除されますが、依存性の注入に使用されるすべてのトークンはランタイムで必要です。
これらは実質的に `constructor(@Optional() other: OtherComponent)` を `constructor(@Optional() @Inject(OtherComponent) other)` に変更されます。
トークンはこれで値位置にあるため、ツリーシェーカーは参照を保持します。

HELPFUL: ライブラリは、[ツリーシェイク可能なプロバイダー](guide/di/dependency-injection#providing-dependency) をすべてのサービスに使用し、コンポーネントやモジュールではなく、ルートレベルで依存関係を提供する必要があります。

## 軽量インジェクショントークンの使用

軽量インジェクショントークン設計パターンは、小さな抽象クラスをインジェクショントークンとして使用し、後で実際のインプリメンテーションを提供します。
抽象クラスは保持され、ツリーシェイクされませんが、小さく、アプリケーションのサイズにはほとんど影響を与えません。

次の例は、 `LibHeaderComponent` でどのように機能するかを示しています。

```ts
{highlight: [[1],[5], [15]]}
abstract class LibHeaderToken {}

@Component({
  selector: 'lib-header',
  providers: [{provide: LibHeaderToken, useExisting: LibHeaderComponent}],
  …,
})
class LibHeaderComponent extends LibHeaderToken {}

@Component({
  selector: 'lib-card',
  …,
})
class LibCardComponent {
  @ContentChild(LibHeaderToken) header: LibHeaderToken | null = null;
}
```

この例では、 `LibCardComponent` 実装は、型位置と値位置のいずれでも `LibHeaderComponent` を参照しなくなりました。
これにより、 `LibHeaderComponent` の完全なツリーシェイクが可能になります。
`LibHeaderToken` は保持されますが、具体的なインプリメンテーションのないクラス宣言に過ぎません。
小さく、コンパイル後に保持されてもアプリケーションのサイズにはほとんど影響を与えません。

代わりに、 `LibHeaderComponent` 自体が抽象 `LibHeaderToken` クラスを実装します。
このトークンをコンポーネント定義のプロバイダーとして安全に使用することで、Angularは具体的な型を正しく注入できます。

要約すると、軽量インジェクショントークンパターンは次のとおりです。

1. 抽象クラスとして表される軽量なインジェクショントークン。
2. 抽象クラスを実装するコンポーネント定義。
3. `@ContentChild()` または `@ContentChildren()` を使用した軽量なパターンの注入。
4. 軽量なインジェクショントークンを実装するプロバイダーであり、軽量インジェクショントークンを実装に関連付けます。

### API 定義に軽量インジェクショントークンを使用する

軽量インジェクショントークンを注入するコンポーネントは、注入されたクラスのメソッドを呼び出す必要がある場合があります。
トークンはこれで抽象クラスです。注入可能コンポーネントはそのクラスを実装するため、軽量インジェクショントークンの抽象クラスに抽象メソッドも宣言する必要があります。
メソッドの実装とそのすべてのコードオーバーヘッドは、ツリーシェイク可能な注入可能コンポーネントに存在します。
これにより、親は、存在する場合、子と型安全な方法で通信できます。

たとえば、 `LibCardComponent` はこれで `LibHeaderComponent` ではなく `LibHeaderToken` をクエリします。
次の例は、パターンにより `LibCardComponent` が `LibHeaderComponent` を実際に参照せずに `LibHeaderComponent` と通信する方法を示しています。

```ts
{highlight: [[2],[9],[11],[19]]}
abstract class LibHeaderToken {
  abstract doSomething(): void;
}

@Component({
  selector: 'lib-header',
  providers: [{provide: LibHeaderToken, useExisting: LibHeaderComponent}],
})
class LibHeaderComponent extends LibHeaderToken {
  doSomething(): void {
    // Concrete implementation of `doSomething`
  }
}

@Component({
  selector: 'lib-card',
})
class LibCardComponent implements AfterContentInit {
  @ContentChild(LibHeaderToken) header: LibHeaderToken | null = null;

ngAfterContentInit(): void {
    if (this.header !== null) {
      this.header?.doSomething();
    }
  }
}
```

この例では、親はトークンをクエリして子コンポーネントを取得し、存在する場合、結果のコンポーネント参照を保存します。
子コンポーネントのメソッドを呼び出す前に、親コンポーネントは子コンポーネントが存在するかどうかを確認します。
子コンポーネントがツリーシェイクされている場合、子コンポーネントへのランタイム参照はありません。メソッドも呼び出されません。

### 軽量インジェクショントークンの名前付け

軽量インジェクショントークンは、コンポーネントでのみ役立ちます。
Angularスタイルガイドでは、コンポーネントに "Component" サフィックスを使用して名前を付けることを推奨しています。
例 "LibHeaderComponent" はこの規則に従っています。

コンポーネントとそのトークン間の関係を維持しながら、両者を区別する必要があります。
推奨されるスタイルは、コンポーネントのベース名にサフィックス " `Token` " を使用して軽量インジェクショントークンに名前を付けることです: " `LibHeaderToken` "。
# RxJS interop with Angular signals

The `@angular/core/rxjs-interop` package offers APIs that help you integrate RxJS and Angular signals.

## Create a signal from an RxJs Observable with `toSignal`

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.

### Injection context

`toSignal` by default needs to run in an [injection context](guide/di/dependency-injection-context), such as during construction of a component or service. If an injection context is not available, you can manually specify the `Injector` to use instead.

### Initial values

Observables may not produce a value synchronously on subscription, but signals always require a current value. There are several ways to deal with this "initial" value of `toSignal` signals.

#### The `initialValue` option

As in the example above, you can specify an `initialValue` option with the value the signal should return before the Observable emits for the first time.

#### `undefined` initial values

If you don't provide an `initialValue`, the resulting signal will return `undefined` until the Observable emits. This is similar to the `async` pipe's behavior of returning `null`.

#### The `requireSync` option

Some Observables are guaranteed to emit synchronously, such as `BehaviorSubject`. In those cases, you can specify the `requireSync: true` option.

When `requiredSync` 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.

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

#### Custom equality comparison

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

### Error and Completion

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.

## Create an RxJS Observable from a signal with `toObservable`

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} from '@angular/core';
import {toObservable} from '@angular/core/rxjs-interop';

@Component(/* ... */)
export class SearchResults {
  query: Signal<string> = inject(QueryService).query;
  query$ = toObservable(this.query);

results$ = this.query$.pipe(switchMap((query) => this.http.get('/search?q=' + query)));
}
```

As the `query` signal changes, the `query$` Observable emits the latest query and triggers a new HTTP request.

### Injection context

`toObservable` by default needs to run in an [injection context](guide/di/dependency-injection-context), such as during construction of a component or service. If an injection context is not available, you can manually specify the `Injector` to use instead.

### Timing of `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.

## Using `rxResource` for async data

IMPORTANT: `rxResource` is [experimental](reference/releases#experimental). It's ready for you to try, but it might change before it is stable.

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 accepts an RxJS `Observable`.

```typescript
import {Component, inject} from '@angular/core';
import {rxResource} from '@angular/core/rxjs-interop';

@Component(/* ... */)
export class UserProfile {
  // This component relies on a service that exposes data through an RxJS Observable.
  private userData = inject(MyUserDataClient);

protected userId = input<string>();

private userResource = rxResource({
    params: () => ({userId: this.userId()}),

// The `stream` property expects a factory function that returns
    // a data stream as an RxJS Observable.
    stream: ({params}) => this.userData.load(params.userId),
  });
}
```

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.
# RxJS interop with component and directive outputs

TIP: This guide assumes you're familiar with [component and directive outputs](guide/components/outputs).

The `@angular/rxjs-interop` package offers two APIs related to component and directive outputs.

## Creating an output based on an RxJs Observable

The `outputFromObservable` lets you create a component or directive output that emits based on an RxJS observable:

```ts
{highlight:[11]}
import {Directive} from '@angular/core';
import {outputFromObservable} from '@angular/core/rxjs-interop';

@Directive({
  /*...*/
})
class Draggable {
  pointerMoves$: Observable<PointerMovements> = listenToPointerMoves();

// Whenever `pointerMoves$` emits, the `pointerMove` event fires.
  pointerMove = outputFromObservable(this.pointerMoves$);
}
```

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.

## Creating an RxJS Observable from a component or directive output

The `outputToObservable` function lets you create an RxJS observable from a component output.

```ts
{highlight:[11]}
import {outputToObservable} from '@angular/core/rxjs-interop';

@Component(/*...*/)
    class CustomSlider {
    valueChange = output<number>();
}

// Instance reference to `CustomSlider`.
const slider: CustomSlider = createSlider();

outputToObservable(slider.valueChange) // Observable<number>
    .pipe(...)
    .subscribe(...);
```

HELPFUL: Consider using the `subscribe` method on `OutputRef` directly if it meets your needs.
# `HttpClient` の設定

`HttpClient` をアプリケーションで使用するには、まず [依存性の注入](guide/di) を使って設定する必要があります。

## 依存性の注入による `HttpClient` の提供

`HttpClient` は `provideHttpClient` ヘルパー関数を使って提供されます。ほとんどのアプリケーションは、`app.config.ts` のアプリケーション `providers` にこれを含めます。

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient()],
};
```

アプリケーションがNgModuleベースのブートストラップを使用している場合は、アプリケーションのNgModuleのプロバイダーに `provideHttpClient` を含めることができます。

```ts
@NgModule({
  providers: [provideHttpClient()],
  // ...その他のアプリケーション設定
})
export class AppModule {}
```

その後、`HttpClient` サービスを、コンポーネント、サービス、またはその他のクラスの依存関係として注入できます。

```ts
@Injectable({providedIn: 'root'})
export class ConfigService {
  private http = inject(HttpClient);
  // このサービスは、`this.http` を介して HTTP リクエストを実行できるようになりました。
}
```

## `HttpClient` の機能の設定

`provideHttpClient` は、クライアントのさまざまな側面の動作を有効化または設定するための、オプションの機能設定のリストを受け取ります。このセクションでは、オプションの機能とその使用方法について詳しく説明します。

### `withFetch`

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withFetch())],
};
```

デフォルトでは、`HttpClient` は [`XMLHttpRequest`](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest) APIを使ってリクエストを行います。`withFetch` 機能は、クライアントを [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) APIを代わりに使うように切り替えます。

`fetch` はより新しいAPIであり、`XMLHttpRequest` がサポートされていないいくつかの環境で使用できます。アップロードの進行状況イベントを生成しないなど、いくつかの制限があります。

### `withInterceptors(...)`

`withInterceptors` は、`HttpClient` を介して行われたリクエストを処理する、インターセプター関数のセットを設定します。詳細については、[インターセプターガイド](guide/http/interceptors) を参照してください。

### `withInterceptorsFromDi()`

`withInterceptorsFromDi` は、`HttpClient` 設定に、古いスタイルのクラスベースのインターセプターを含めます。詳細については、[インターセプターガイド](guide/http/interceptors) を参照してください。

HELPFUL: 関数インターセプター（`withInterceptors` を介して）は、より予測可能な順序を持ち、DIベースのインターセプターよりも推奨されます。

### `withRequestsMadeViaParent()`

デフォルトでは、`provideHttpClient` を使って特定のインジェクター内で `HttpClient` を設定すると、この設定は、親インジェクターに存在する可能性のある `HttpClient` の設定を上書きします。

`withRequestsMadeViaParent()` を追加すると、`HttpClient` は、このレベルで設定されたインターセプターを通過した後、親インジェクターの `HttpClient` インスタンスにリクエストを渡すように設定されます。これは、親インジェクターのインターセプターも通過しながら、子インジェクターにインターセプターを追加したい場合に役立ちます。

CRITICAL: 現在のインジェクターよりも上の `HttpClient` のインスタンスを設定する必要があります。そうしないと、このオプションは無効となり、使用しようとすると実行時エラーが発生します。

### `withJsonpSupport()`

`withJsonpSupport` を含めると、`HttpClient` の `.jsonp()` メソッドが有効になり、[JSONP 規約](https://en.wikipedia.org/wiki/JSONP) を介してGETリクエストを行い、データのクロスドメインロードを行います。

HELPFUL: 可能であれば、JSONPの代わりに [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) を使ってクロスドメインリクエストを行うことをお勧めします。

### `withXsrfConfiguration(...)`

このオプションを含めると、`HttpClient` の組み込みのXSRFセキュリティ機能をカスタマイズできます。詳細については、[セキュリティガイド](best-practices/security) を参照してください。

### `withNoXsrfProtection()`

このオプションを含めると、`HttpClient` の組み込みのXSRFセキュリティ機能が無効になります。詳細については、[セキュリティガイド](best-practices/security) を参照してください。

## `HttpClientModule` ベースの設定

一部のアプリケーションでは、NgModuleベースの古いAPIを使って `HttpClient` を設定している場合があります。

この表は、`@angular/common/http` から使用できるNgModuleと、上記のプロバイダー設定関数との関係を示しています。

| **NgModule**                            | `provideHttpClient()` に相当する               |
| --------------------------------------- | --------------------------------------------- |
| `HttpClientModule`                      | `provideHttpClient(withInterceptorsFromDi())` |
| `HttpClientJsonpModule`                 | `withJsonpSupport()`                          |
| `HttpClientXsrfModule.withOptions(...)` | `withXsrfConfiguration(...)`                  |
| `HttpClientXsrfModule.disable()`        | `withNoXsrfProtection()`                      |
`HttpClientModule` が複数のインジェクターに存在する場合、インターセプターの動作は明確に定義されておらず、オプションやプロバイダー/インポートの順序に依存します。

マルチインジェクター構成には、`provideHttpClient` を使用することをお勧めします。これは、より安定した動作をします。上記の `withRequestsMadeViaParent` 機能を参照してください。

## HTTP リクエストを行う

`HttpClient` には、データの読み込みとサーバーへの変更の適用に使用されるさまざまなHTTP動詞に対応するメソッドがあります。各メソッドは[RxJS `Observable`](https://rxjs.dev/guide/observable) を返し、これはサブスクライブされるとリクエストを送信し、サーバーが応答すると結果を発行します。

NOTE: `HttpClient` によって作成された `Observable` は、何度でもサブスクライブでき、各サブスクライブごとに新しいバックエンドリクエストが行われます。

リクエストメソッドに渡されるオプションオブジェクトを通じて、リクエストのさまざまなプロパティと返されるレスポンスタイプを調整できます。

## JSON データの取得 {#fetching-json-data}

バックエンドからデータを取得するには、多くの場合、[`HttpClient.get()`](api/common/http/HttpClient#get) メソッドを使用してGETリクエストを行う必要があります。このメソッドは、2つの引数を取ります。1つ目は、フェッチする文字列のエンドポイントURL、2つ目はリクエストを構成するための*オプションオブジェクト*です（省略可能）。

たとえば、`HttpClient.get()` メソッドを使用して、仮説上のAPIから構成データを取得するには、次のようになります。

```ts
http.get<Config>('/api/config').subscribe((config) => {
  // 構成を処理します。
});
```

サーバーによって返されるデータが `Config` 型であることを指定するジェネリック型引数に注意してください。この引数は省略可能であり、省略すると、返されるデータは `Object` 型になります。

TIP: 不確実な構造のデータや `undefined` または `null` の値を扱う場合、レスポンスタイプとして `Object` の代わりに `unknown` 型を使用することを検討してください。

CRITICAL: リクエストメソッドのジェネリック型は、サーバーによって返されるデータに関する**アサーション**です。`HttpClient` は、実際の戻り値データがこの型と一致することを検証しません。

## 他のタイプのデータの取得 {#fetching-other-types-of-data}

デフォルトでは、`HttpClient` はサーバーがJSONデータを返すことを想定しています。JSON以外のAPIと対話する場合、`HttpClient` にリクエストを行うときに期待されるレスポンス型と返す型を伝えることができます。これは、`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('画像は ' + buffer.byteLength + ' バイトです');
});
```
`responseType` の値は、`HttpClient` によって返される型に影響を与えるため、`string` 型ではなく、リテラル型である必要があります。

これは、リクエストメソッドに渡されるオプションオブジェクトがリテラルオブジェクトの場合に自動的に発生しますが、リクエストオプションを変数やヘルパーメソッドに抽出している場合は、`responseType: 'text' as const` のように明示的にリテラルとして指定する必要があるかもしれません。
## サーバーの状態を変更する {#mutating-server-state}

変更を伴うサーバーAPIは多くの場合、新しい状態または行うべき変更を指定したリクエストボディを使用してPOSTリクエストを行う必要があります。

[`HttpClient.post()`](api/common/http/HttpClient#post) メソッドは `get()` と同様に動作し、オプションの前に `body` 引数を追加で受け取ります。

```ts
http.post<Config>('/api/config', newConfig).subscribe((config) => {
  console.log('更新された構成:', 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` 形式の文字列 |

IMPORTANT: 変更リクエスト `Observable` を `.subscribe()` することを忘れないでください。そうしないと、リクエストは実際に発行されません。

## URL パラメータの設定 {#setting-url-parameters}

リクエストURLに含めるべきリクエストパラメータは、`params` オプションを使用して指定します。

オブジェクトリテラルを渡すことは、URLパラメータを構成するための最も簡単な方法です。

```ts
http
  .get('/api/config', {
    params: {filter: 'all'},
  })
  .subscribe((config) => {
    // ...
  });
```

あるいは、パラメータの構築やシリアル化をより細かく制御する必要がある場合は、`HttpParams` のインスタンスを渡します。

IMPORTANT: `HttpParams` のインスタンスは*変更不可能*であり、直接変更できません。代わりに、`append()` などの変更メソッドは、変更が適用された新しい `HttpParams` のインスタンスを返します。

```ts
const baseParams = new HttpParams().set('filter', 'all');

http
  .get('/api/config', {
    params: baseParams.set('details', 'enabled'),
  })
  .subscribe((config) => {
    // ...
  });
```

`HttpParams` を、`HttpClient` がパラメータをURLにエンコードする方法を決定するカスタム `HttpParameterCodec` でインスタンス化できます。

### カスタムパラメータエンコーディング {#custom-parameter-encoding}

デフォルトでは、`HttpParams` は組み込みの [`HttpUrlEncodingCodec`](api/common/http/HttpUrlEncodingCodec) を使用してパラメータのキーと値をエンコードおよびデコードします。

[`HttpParameterCodec`](api/common/http/HttpParameterCodec) の独自の実装を提供することで、エンコードとデコードの適用方法をカスタマイズできます。

```ts
import {HttpClient, HttpParams, HttpParameterCodec} from '@angular/common/http';
import {inject} from '@angular/core';

export class CustomHttpParamEncoder implements HttpParameterCodec {
  encodeKey(key: string): string {
    return encodeURIComponent(key);
  }

encodeValue(value: string): string {
    return encodeURIComponent(value);
  }

decodeKey(key: string): string {
    return decodeURIComponent(key);
  }

decodeValue(value: string): string {
    return decodeURIComponent(value);
  }
}

export class ApiService {
  private http = inject(HttpClient);

search() {
    const params = new HttpParams({
      encoder: new CustomHttpParamEncoder(),
    })
      .set('email', 'dev+alerts@example.com')
      .set('q', 'a & b? c/d = e');

return this.http.get('/api/items', {params});
  }
}
```

## リクエストヘッダーの設定 {#setting-request-headers}

リクエストに含めるべきリクエストヘッダーは、`headers` オプションを使用して指定します。

オブジェクトリテラルを渡すことは、リクエストヘッダーを構成するための最も簡単な方法です。

```ts
http
  .get('/api/config', {
    headers: {
      'X-Debug-Level': 'verbose',
    },
  })
  .subscribe((config) => {
    // ...
  });
```

あるいは、ヘッダーの構築をより細かく制御する必要がある場合は、`HttpHeaders` のインスタンスを渡します。

IMPORTANT: `HttpHeaders` のインスタンスは*変更不可能*であり、直接変更できません。代わりに、`append()` などの変更メソッドは、変更が適用された新しい `HttpHeaders` のインスタンスを返します。

```ts
const baseHeaders = new HttpHeaders().set('X-Debug-Level', 'minimal');

http
  .get<Config>('/api/config', {
    headers: baseHeaders.set('X-Debug-Level', 'verbose'),
  })
  .subscribe((config) => {
    // ...
  });
```

## サーバーレスポンスイベントとの対話 {#interacting-with-the-server-response-events}

便宜上、`HttpClient` はデフォルトでサーバーによって返されるデータ（レスポンスボディ）の `Observable` を返します。場合によっては、特定のレスポンスヘッダーを取得するなど、実際のレスポンスを調べる必要がある場合もあります。

レスポンス全体にアクセスするには、`observe` オプションを `'response'` に設定します。

```ts
http.get<Config>('/api/config', {observe: 'response'}).subscribe((res) => {
  console.log('レスポンスステータス:', res.status);
  console.log('ボディ:', res.body);
});
```
`observe` の値は、`HttpClient` によって返される型に影響を与えるため、`string` 型ではなく、リテラル型である必要があります。

これは、リクエストメソッドに渡されるオプションオブジェクトがリテラルオブジェクトの場合に自動的に発生しますが、リクエストオプションを変数やヘルパーメソッドに抽出している場合は、`observe: 'response' as const` のように明示的にリテラルとして指定する必要があるかもしれません。
## 生の進捗イベントを受信する {#receiving-raw-progress-events}

`HttpClient` は、レスポンスボディとレスポンスオブジェクトに加えて、リクエストライフサイクルの特定の時点に対応する生の*イベント*のストリームを返せます。これらのイベントには、リクエストが送信されたとき、レスポンスヘッダーが返されたとき、ボディが完了したときなどが含まれます。これらのイベントには、大きなリクエストボディとレスポンスボディのアップロードとダウンロードの状態を報告する*進捗イベント*も含まれる場合があります。

進捗イベントは、デフォルトでは無効になっています（パフォーマンス上のコストがかかるため）が、`reportProgress` オプションを使用して有効にできます。

NOTE: `HttpClient` のオプションの `fetch` 実装は、*アップロード*の進捗イベントを報告しません。

イベントストリームを観察するには、`observe` オプションを `'events'` に設定します。

```ts
http
  .post('/api/upload', myData, {
    reportProgress: true,
    observe: 'events',
  })
  .subscribe((event) => {
    switch (event.type) {
      case HttpEventType.UploadProgress:
        console.log('Uploaded ' + event.loaded + ' out of ' + event.total + ' bytes');
        break;
      case HttpEventType.Response:
        console.log('Finished uploading!');
        break;
    }
  });
```
`observe` の値は、`HttpClient` によって返される型に影響を与えるため、`string` 型ではなく、リテラル型である必要があります。

これは、リクエストメソッドに渡されるオプションオブジェクトがリテラルオブジェクトの場合に自動的に発生しますが、リクエストオプションを変数やヘルパーメソッドに抽出している場合は、`observe: 'events' as const` のように明示的にリテラルとして指定する必要があるかもしれません。
イベントストリームで報告される各 `HttpEvent` には、イベントを表す `type` があります。

| **`type` 値**                 | **イベントの意味**                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| `HttpEventType.Sent`             | リクエストがサーバーに送信されました                                                     |
| `HttpEventType.UploadProgress`   | リクエストボディのアップロードの進捗状況を報告する `HttpUploadProgressEvent`            |
| `HttpEventType.ResponseHeader`   | レスポンスのヘッダーが受信されました。ステータスとヘッダーが含まれています                  |
| `HttpEventType.DownloadProgress` | レスポンスボディのダウンロードの進捗状況を報告する `HttpDownloadProgressEvent` |
| `HttpEventType.Response`         | レスポンス全体が受信されました。レスポンスボディが含まれています                         |
| `HttpEventType.User`             | Http インターセプターからのカスタムイベント                                           |

## リクエスト失敗の処理 {#handling-request-failure}

HTTPリクエストは、次の3つの方法で失敗する可能性があります。

- ネットワークエラーまたは接続エラーにより、リクエストがバックエンドサーバーに到達できない場合があります。
- timeoutオプションが設定されている場合に、リクエストが時間内に応答しませんでした。
- バックエンドがリクエストを受け取りますが、処理に失敗し、エラーレスポンスを返す場合があります。

`HttpClient` は、上記のすべての種類のエラーを `HttpErrorResponse` に捕捉し、`Observable` のエラーチャネルを通じて返します。ネットワークエラーとタイムアウトエラーの `status` コードは `0` で、`error` は [`ProgressEvent`](https://developer.mozilla.org/docs/Web/API/ProgressEvent) のインスタンスです。バックエンドエラーの `status` コードは、バックエンドによって返された失敗したコードであり、`error` はエラーレスポンスです。レスポンスを調べて、エラーの原因とエラーを処理するための適切なアクションを特定します。

[RxJS ライブラリ](https://rxjs.dev/) は、エラー処理に役立つ演算子をいくつか提供しています。

`catchError` 演算子を使用して、エラーレスポンスをUI用の値に変換できます。この値は、UIにエラーページまたは値を表示し、必要に応じてエラーの原因を捕捉します。

ネットワークの中断など、一時的なエラーにより、予期せずリクエストが失敗することがあります。リクエストを再試行するだけで成功する場合があります。RxJSは、特定の条件下で失敗した `Observable` に自動的に再購読する、複数の*再試行*演算子を提供しています。たとえば、`retry()` 演算子は、指定された回数だけ自動的に再サブスクライブを試みます。

### タイムアウト {#timeouts}

リクエストにタイムアウトを設定するには、他のリクエストオプションと一緒に `timeout` オプションをミリ秒数に設定できます。バックエンドリクエストが指定された時間内に完了しない場合、リクエストは中止され、エラーが発行されます。

NOTE: タイムアウトは、バックエンドHTTPリクエスト自体にのみ適用されます。リクエスト処理チェーン全体のタイムアウトではありません。したがって、このオプションは、インターセプターによって導入される遅延の影響を受けません。

```ts
http
  .get('/api/config', {
    timeout: 3000,
  })
  .subscribe({
    next: (config) => {
      console.log('設定の取得に成功:', config);
    },
    error: (err) => {
      // リクエストがタイムアウトした場合、エラーが発行されます。
    },
  });
```

## 高度な fetch オプション {#advanced-fetch-options}

`withFetch()` プロバイダーを使用する場合、Angularの `HttpClient` は、パフォーマンスとユーザー体験を改善できる高度なfetch APIオプションへのアクセスを提供します。これらのオプションは、fetchバックエンドを使用する場合にのみ利用できます。

### Fetch オプション {#fetch-options}

以下のオプションは、fetchバックエンドを使用する際のリクエスト動作を細かく制御します。

#### Keep-alive 接続 {#keep-alive-connections}

`keepalive` オプションにより、リクエストはそれを開始したページよりも長く存続できます。これは、ユーザーがページから移動した場合でも完了する必要がある分析やログリクエストに特に有用です。

```ts
http
  .post('/api/analytics', analyticsData, {
    keepalive: true,
  })
  .subscribe();
```

#### HTTP キャッシュ制御 {#http-caching-control}

`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 のためのリクエスト優先度 {#request-priority-for-core-web-vitals}

`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'`: 高優先度、早期に読み込まれる（例：重要なユーザーデータ、above-the-foldコンテンツ）
- `'low'`: 低優先度、リソースが利用可能なときに読み込まれる（例：分析、プリフェッチデータ）
- `'auto'`: ブラウザがリクエストコンテキストに基づいて優先度を決定（デフォルト）

TIP: Largest Contentful Paint (LCP) に影響するリクエストには `priority: 'high'` を使用し、初期ユーザー体験に影響しないリクエストには `priority: 'low'` を使用してください。

#### リクエストモード {#request-mode}

`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なしでシンプルなクロスオリジンリクエストを許可、レスポンスは不透明

TIP: クロスオリジンに行くべきでない機密リクエストには `mode: 'same-origin'` を使用してください。

#### リダイレクト処理 {#redirect-handling}

`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'`: リダイレクトを自動的に追跡せず、リダイレクトレスポンスを返す

TIP: カスタムロジックでリダイレクトを処理する必要がある場合は `redirect: 'manual'` を使用してください。

#### 認証情報の処理 {#credentials-handling}

`credentials` オプションは、Cookie、認証ヘッダー、その他の認証情報がクロスオリジンリクエストと一緒に送信されるかどうかを制御します。これは認証シナリオで特に重要です。

```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' と同等
  });
```

IMPORTANT: `withCredentials` オプションは `credentials` オプションより優先されます。両方が指定されている場合、明示的な `credentials` 値に関係なく、`withCredentials: true` は常に `credentials: 'include'` になります。

利用可能な `credentials` 値：

- `'omit'`: 認証情報を送信しない
- `'same-origin'`: 同一オリジンリクエストのみに認証情報を送信（デフォルト）
- `'include'`: クロスオリジンリクエストでも常に認証情報を送信

TIP: CORSをサポートする異なるドメインに認証Cookieやヘッダーを送信する必要がある場合は `credentials: 'include'` を使用してください。混乱を避けるため、`credentials` と `withCredentials` オプションを混在させることは避けてください。

#### Referrer {#referrer}

`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）を使用

TIP: 参照元ページのURLを漏らしたくない機密リクエストには `referrer: ''` を使用してください。

#### Referrerポリシー {#referrer-policy}

`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（パスとクエリを含む）を送信します。これは機密データを公開する可能性があるため、注意して使用する必要があります。

TIP: プライバシーに配慮したリクエストには、`'no-referrer'`、`'origin'`、または `'strict-origin-when-cross-origin'` などの保守的な値を優先してください。

#### Integrity {#integrity}

`integrity` オプションを使用すると、期待されるコンテンツの暗号化ハッシュを提供することで、レスポンスが改ざんされていないことを検証できます。これは、CDNからスクリプトやその他のリソースを読み込む際に特に有用です。

```ts
// SHA-256ハッシュでレスポンスの整合性を検証
http
  .get('/api/script.js', {
    integrity: 'sha256-ABC123...',
    responseType: 'text',
  })
  .subscribe((script) => {
    // スクリプトのコンテンツがハッシュに対して検証されます
  });
```

IMPORTANT: `integrity` オプションには、レスポンスコンテンツと提供されたハッシュとの厳密な一致が必要です。コンテンツが一致しない場合、リクエストはネットワークエラーで失敗します。

TIP: 外部ソースから重要なリソースを読み込む際は、それらが変更されていないことを確実にするため、サブリソースの整合性を使用してください。`openssl` などのツールを使用してハッシュを生成してください。

## Http `Observable` {#http-observables}

`HttpClient` の各リクエストメソッドは、要求されたレスポンス型の `Observable` を構築して返します。これらの `Observable` の仕組みを理解することは、`HttpClient` を使用する場合に重要です。

`HttpClient` は、RxJSが「コールド」と呼ぶ `Observable` を生成します。つまり、`Observable` がサブスクライブされるまでは、実際のリクエストは行われません。リクエストが実際にサーバーに送信されるのは、そのときだけです。同じ `Observable` を複数回購読すると、複数のバックエンドリクエストがトリガーされます。各サブスクライブは独立しています。

Tip: `HttpClient` の `Observable` は、実際のリクエストの*ブループリント*と考えることができます。

いったんサブスクライブされると、アン購読すると、進行中のリクエストが中止されます。これは、`Observable` が `async` パイプを使用してサブスクライブされている場合に非常に便利です。ユーザーが現在のページから移動すると、リクエストが自動的にキャンセルされます。さらに、`Observable` を `switchMap` などのRxJSコンビネータと使用する場合、このキャンセルによって、古いリクエストがすべてクリーンアップされます。

レスポンスが返されると、`HttpClient` からの `Observable` は通常完了します（ただし、インターセプターがこれに影響を与える可能性があります）。

自動完了のため、`HttpClient` のサブスクライブがクリーンアップされなくても、通常はメモリリークのリスクはありません。ただし、他の非同期操作と同様に、サブスクライブを使用しているコンポーネントが破棄されたときにサブスクライブをクリーンアップすることを強くお勧めします。そうしないと、サブスクライブコールバックが実行され、破棄されたコンポーネントと対話するときにエラーが発生する可能性があります。

TIP: `async` パイプまたは `toSignal` 演算子を使用して `Observable` に購読すると、サブスクライブが適切に破棄されます。

## ベストプラクティス {#best-practices}

`HttpClient` はコンポーネントから直接注入して使用できますが、一般的にはデータアクセスロジックを分離してカプセル化する、再利用できる注入可能なサービスを作成することをお勧めします。たとえば、この `UserService` は、IDでユーザーのデータをリクエストするロジックをカプセル化しています。

```ts
@Injectable({providedIn: 'root'})
export class UserService {
  private http = inject(HttpClient);

getUser(id: string): Observable<User> {
    return this.http.get<User>(`/api/user/${id}`);
  }
}
```

コンポーネント内で、`@if` を `async` パイプと組み合わせて、データの読み込みが完了した後にのみ、データのUIをレンダリングできます。

```typescript
import { AsyncPipe } from '@angular/common';

@Component({
  imports: [AsyncPipe],
  template: `
    @if (user$ | async; as user) {
      <p>名前: {{ user.name }}</p>
      <p>経歴: {{ user.biography }}</p>
    }
  `,
})
export class UserProfileComponent {
  userId = input.required<string>();
  user$!: Observable<User>;

private userService = inject(UserService);

constructor(): void {
    effect(() => {
      this.user$ = this.userService.getUser(this.userId());
    });
  }
}
```
# インターセプター

`HttpClient` は、_インターセプター_ と呼ばれるミドルウェアの一種をサポートしています。

TLDR: インターセプターは、再試行、キャッシュ、ロギング、認証など、一般的なパターンを個々のリクエストから抽象化できるミドルウェアです。

`HttpClient` は、関数型インターセプターとDIベースのインターセプターの2種類のインターセプターをサポートしています。複雑な設定では特に、関数型インターセプターの方が動作が予測しやすいので、関数型インターセプターの使用をお勧めします。このガイドの例では、関数型インターセプターを使用しており、[DI ベースのインターセプター](#di-based-interceptors)については、最後に別のセクションで説明します。

## インターセプター

インターセプターは、一般的には各リクエストに対して実行できる関数であり、リクエストとレスポンスの内容と全体的なフローに影響を与える幅広い機能を持っています。複数のインターセプターをインストールできます。インストールしたインターセプターはインターセプターチェーンを形成します。各インターセプターは、リクエストまたはレスポンスをチェーン内の次のインターセプターに転送する前に処理します。

インターセプターを使用して、さまざまな一般的なパターンを実装できます。たとえば、以下のようなものがあります。

- 特定のAPIへの送信リクエストに認証ヘッダーを追加する。
- 失敗したリクエストを指数関数的バックオフで再試行する。
- レスポンスを一定時間キャッシュするか、変更によって無効になるまでキャッシュする。
- レスポンスの解析をカスタマイズする。
- サーバーの応答時間を測定してログに記録する。
- ネットワーク操作が進行中の間、ローディングスピナーなどのUI要素を制御する。
- 特定のタイムフレーム内で作成されたリクエストを収集してバッチ処理する。
- 設定可能な期限またはタイムアウト後にリクエストを自動的に失敗させる。
- サーバーを定期的にポーリングして結果を更新する。

## インターセプターの定義

インターセプターの基本的な形式は、送信される `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` がインターセプターを使用するように構成する必要があります。

## インターセプターの構成

`HttpClient` を構成するときに使用するインターセプターのセットは、`withInterceptors` 機能を使用して、依存性の注入によって宣言します。

```ts
bootstrapApplication(AppComponent, {
  providers: [provideHttpClient(withInterceptors([loggingInterceptor, cachingInterceptor]))],
});
```

構成したインターセプターは、プロバイダーにリストした順序でチェーンされます。上記の例では、`loggingInterceptor` がリクエストを処理し、`cachingInterceptor` に転送します。

### レスポンスイベントのインターセプト

インターセプターは、`next` から返される `HttpEvent` の `Observable` ストリームを変換して、レスポンスにアクセスしたり、レスポンスを操作したりできます。このストリームにはすべてのレスポンスイベントが含まれているため、最終的なレスポンスオブジェクトを識別するためには、各イベントの `.type` を調べる必要がある場合があります。

```ts
export function loggingInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  return next(req).pipe(
    tap((event) => {
      if (event.type === HttpEventType.Response) {
        console.log(req.url, 'returned a response with status', event.status);
      }
    }),
  );
}
```

TIP: インターセプターは、レスポンスストリームをリクエストオブジェクトをキャプチャするクロージャー内で変換するため、レスポンスを送信リクエストに自然に関連付けます。

## リクエストの変更

`HttpRequest` と `HttpResponse` インスタンスのほとんどの側面は _変更不可能_ であり、インターセプターは直接変更できません。代わりに、インターセプターは `.clone()` 操作を使用してこれらのオブジェクトを複製し、新しいインスタンスでどのプロパティを変更するべきかを指定することによって、変更を適用します。これには、値自体（`HttpHeaders` や `HttpParams` など）に対しては変更不可能な更新が含まれる場合があります。

たとえば、リクエストにヘッダーを追加するには、次のようにします。

```ts
const reqWithHeader = req.clone({
  headers: req.headers.set('X-New-Header', 'new header value'),
});
```

この変更不能性により、ほとんどのインターセプターは、同じ `HttpRequest` がインターセプターチェーンに複数回送信された場合でも、べき等性を持つことができます。これは、リクエストが失敗後に再試行された場合など、いくつかの理由で発生する可能性があります。

CRITICAL: リクエストまたはレスポンスの本文は、深い変更から **保護されません**。インターセプターが本文を変更する必要がある場合は、同じリクエストに対して複数回実行される場合の処理に注意してください。

## インターセプターでの依存性の注入

インターセプターは、インターセプターを登録したインジェクターの _注入コンテキスト_ で実行され、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);
}
```

## リクエストとレスポンスのメタデータ

多くの場合、バックエンドに送信されないリクエストに情報を含めたり、インターセプター専用の情報をリクエストに含めたりすると便利です。`HttpRequest` には、`.context` オブジェクトがあり、このオブジェクトは、この種のメタデータを `HttpContext` のインスタンスとして格納します。このオブジェクトは型付きマップとして機能し、キーは `HttpContextToken` 型です。

このシステムの動作を説明するために、メタデータを使用して、特定のリクエストに対してキャッシュインターセプターを有効にするかどうかを制御します。

### コンテキストトークンの定義

特定のリクエストの `.context` マップに、キャッシュインターセプターがリクエストをキャッシュするかどうかを格納するには、キーとして機能する新しい `HttpContextToken` を定義します。

```ts
export const CACHING_ENABLED = new HttpContextToken<boolean>(() => true);
```

提供される関数は、明示的に値が設定されていないリクエストのトークンのデフォルト値を作成します。関数を用いることで、トークンの値がオブジェクトまたは配列である場合、各リクエストが独自のインスタンスを取得することが保証されます。

### インターセプターでのトークンの読み込み

インターセプターは、トークンを読み取り、その値に基づいてキャッシュロジックを適用するかどうかを選択できます。

```ts
export function cachingInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> {
  if (req.context.get(CACHING_ENABLED)) {
    // キャッシュロジックを適用する
    return ...;
  } else {
    // このリクエストに対してキャッシュが無効になっている
    return next(req);
  }
}
```

### リクエストの作成時のコンテキストトークンの設定

`HttpClient` APIを介してリクエストを作成する際には、`HttpContextToken` の値を指定できます。

```ts
const data$ = http.get('/sensitive/data', {
  context: new HttpContext().set(CACHING_ENABLED, false),
});
```

インターセプターは、リクエストの `HttpContext` からこれらの値を読み取ることができます。

### リクエストコンテキストは変更可能

`HttpRequest` の他のプロパティとは異なり、関連付けられた `HttpContext` は _変更可能_ です。インターセプターが後で再試行されるリクエストのコンテキストを変更した場合、同じインターセプターは、再度実行されるときに、コンテキストの変更を認識します。これは、必要に応じて、複数回の再試行にわたって状態を渡す場合に便利です。

## 合成レスポンス

ほとんどのインターセプターは、リクエストまたはレスポンスを変換しながら、単に `next` ハンドラーを呼び出すだけです。しかし、これは厳密には必須ではありません。このセクションでは、インターセプターがより高度な動作を組み込むことができるいくつかの方法について説明します。

インターセプターは `next` を呼び出す必要はありません。代わりに、キャッシュからレスポンスを作成したり、別の手法でリクエストを送信したりするなど、別の方法でもレスポンスを作成できます。

`HttpResponse` コンストラクターを使用して、レスポンスを作成できます。

```ts
const resp = new HttpResponse({
  body: 'response body',
});
```

## リダイレクト情報の操作

`HttpClient` を `withFetch` プロバイダーと一緒に使用する場合、レスポンスには、そのレスポンスがリダイレクトの結果であるかどうかを示す `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();
        }
      }
    }),
  );
}
```

## レスポンスタイプの操作 {#working-with-response-types}

`HttpClient` を `withFetch` プロバイダーと一緒に使用する場合、レスポンスには、CORSポリシーとリクエストモードに基づいてブラウザがレスポンスを処理した方法を示す `type` プロパティが含まれます。このプロパティはネイティブのFetch API仕様に沿っており、CORSの問題をデバッグしたり、レスポンスのアクセス可能性を理解したりするための貴重な洞察を提供します。

レスポンスの `type` プロパティには、次の値を設定できます。

- `'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(
    map((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 ベースのインターセプター {#di-based-interceptors}

`HttpClient` は、注入可能なクラスとして定義され、DIシステムによって構成されるインターセプターもサポートしています。DIベースのインターセプターの機能は、関数型インターセプターと同じですが、構成方法が異なります。

DIベースのインターセプターは、`HttpInterceptor` インターフェースを実装する、注入可能なクラスです。

```ts
@Injectable()
export class LoggingInterceptor implements HttpInterceptor {
  intercept(req: HttpRequest<any>, handler: HttpHandler): Observable<HttpEvent<any>> {
    console.log('Request URL: ' + req.url);
    return handler.handle(req);
  }
}
```

DIベースのインターセプターは、依存性の注入のマルチプロバイダーによって構成されます。

```ts
bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(
      // DI ベースのインターセプターは明示的に有効にする必要があります。
      withInterceptorsFromDi(),
    ),

{provide: HTTP_INTERCEPTORS, useClass: LoggingInterceptor, multi: true},
  ],
});
```

DIベースのインターセプターは、プロバイダーが登録された順序で実行されます。DI構成が複雑で階層的なアプリケーションでは、この順序を予測することは非常に難しい場合があります。
## リクエストのテスト

外部へ依存する場合、テストでリモートサーバーとのやり取りをシミュレートできるように、HTTPバックエンドをモックする必要があります。`@angular/common/http/testing` ライブラリは、アプリケーションによって行われたリクエストをキャプチャし、それらについてアサーションを行い、バックエンドの動作をエミュレートするためにレスポンスをモックするためのツールを提供します。

テストライブラリは、アプリケーションがコードを実行して最初にリクエストを行うというパターン用に設計されています。その後、テストは特定のリクエストが行われたか、行われなかったかを期待し、それらのリクエストに対してアサーションを行い、最後に各期待されるリクエストにレスポンスを提供することによってそれらを「フラッシュ」します。

最後に、テストはアプリケーションが予期しないリクエストを行わなかったことを検証できます。

## テストの設定

`HttpClient` の使用のテストを開始するには、`TestBed` を構成してテストの設定に `provideHttpClient()` と `provideHttpClientTesting()` を含めます。これにより、`HttpClient` が実際のネットワークではなくテストバックエンドを使用するように構成されます。また、`HttpTestingController` も提供され、これを使用してテストバックエンドとやり取ります。そして、どのリクエストが行われたかについての期待を設定し、それらのリクエストに対するレスポンスを流します。`HttpTestingController` は、構成されたら `TestBed` から注入できます。

IMPORTANT: `provideHttpClientTesting()` は `provideHttpClient()` の一部を上書きするため、`provideHttpClient()` を `provideHttpClientTesting()` の**前**に提供することに留意してください。これを逆に行うと、テストが壊れてしまう可能性があります。

```ts
TestBed.configureTestingModule({
  providers: [
    // ...その他のテストプロバイダー
    provideHttpClient(),
    provideHttpClientTesting(),
  ],
});

const httpTesting = TestBed.inject(HttpTestingController);
```

これで、テストでリクエストを行うと、通常のバックエンドではなくテストバックエンドにヒットするようになります。`httpTesting` を使用して、それらのリクエストについてアサーションを行うことができます。

## リクエストの期待と応答

たとえば、GETリクエストが発生することを期待し、モックレスポンスを提供するテストを作成できます。

```ts
TestBed.configureTestingModule({
  providers: [ConfigService, provideHttpClient(), 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', '構成をロードするリクエスト');

// 必要に応じて、リクエストのさまざまなプロパティをアサートできます。
expect(req.request.method).toBe('GET');

// リクエストをフラッシュすると、リクエストが完了し、結果が配信されます。
req.flush(DEFAULT_CONFIG);

// その後、`ConfigService` によってレスポンスが正常に配信されたことをアサートできます。
expect(await configPromise).toEqual(DEFAULT_CONFIG);

// 最後に、他のリクエストが行われていないことをアサートできます。
httpTesting.verify();
```

NOTE: `expectOne` は、テストが指定された基準に一致するリクエストを2つ以上行った場合に失敗します。

`req.method` についてアサートする代わりに、`expectOne` の拡張形式を使用してリクエストメソッドも一致させることができます。

```ts
const req = httpTesting.expectOne(
  {
    method: 'GET',
    url: '/api/config',
  },
  '構成をロードするリクエスト',
);
```

HELPFUL: 期待APIは、クエリパラメータを含むリクエストの完全なURLと一致します。

最後のステップである、保留中のリクエストがないことを検証する操作は十分に一般的なので、`afterEach()` ステップに移動できます。

```ts
afterEach(() => {
  // テストが追加の HTTP リクエストを行わないことを確認します。
  TestBed.inject(HttpTestingController).verify();
});
```

## 複数のリクエストを一度に処理する

テストで重複するリクエストに応答する必要がある場合は、`expectOne()` ではなく `match()` APIを使用します。これは同じ引数を受け取りますが、一致するリクエストの配列を返します。返された後、これらのリクエストは今後のマッチングから削除され、それらをフラッシュして検証する責任はあなたにあります。

```ts
const allGetRequests = httpTesting.match({method: 'GET'});
for (const req of allGetRequests) {
  // 各リクエストへの応答処理。
}
```

## 高度なマッチング

すべてのマッチング関数は、カスタムマッチングロジックの述語関数を受け取ります。

```ts
// リクエストボディを持つリクエストを 1 つ探します。
const requestsWithBody = httpTesting.expectOne((req) => req.body !== null);
```

`expectNone` 関数は、指定された基準に一致するリクエストがないことをアサートします。

```ts
// 突然変異リクエストが発行されていないことをアサートします。
httpTesting.expectNone((req) => req.method !== 'GET');
```

## エラー処理のテスト

HTTPリクエストが失敗した場合のアプリケーションのレスポンスをテストする必要があります。

### バックエンドエラー

バックエンドエラー（サーバーが成功ではないステータスコードを返す場合）の処理をテストするには、リクエストが失敗した場合にバックエンドが返すものとエミュレートしたエラーレスポンスを使用して、リクエストをフラッシュします。

```ts
const req = httpTesting.expectOne('/api/config');
req.flush('Failed!', {status: 500, statusText: 'Internal Server Error'});

// アプリケーションがバックエンドエラーを正常に処理したことをアサートします。
```

### ネットワークエラー

リクエストは、ネットワークエラーが原因で失敗することもあり、`ProgressEvent` エラーとして現れます。これらは、`error()` メソッドを使用して配信できます。

```ts
const req = httpTesting.expectOne('/api/config');
req.error(new ProgressEvent('network error!'));

// アプリケーションがネットワークエラーを正常に処理したことをアサートします。
```

## インターセプターのテスト {#testing-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);
}
```

このインターセプターの `TestBed` 構成は、`withInterceptors` 機能に依存する必要があります。

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    // 一度に1つのインターセプターをテストすることをお勧めします。
    provideHttpClient(withInterceptors([authInterceptor])),
    provideHttpClientTesting(),
  ],
});
```

`HttpTestingController` は、リクエストインスタンスを取得でき、それを検査してリクエストが変更されたことを確認できます。

```ts
const service = TestBed.inject(AuthService);
const req = httpTesting.expectOne('/api/config');

expect(req.request.headers.get('X-Authentication-Token')).toEqual(service.getAuthToken());
```

同様のインターセプターは、クラスベースのインターセプターで実装できます。

```ts
@Injectable()
export class AuthInterceptor implements HttpInterceptor {
  private authService = inject(AuthService);

intercept(request: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>> {
    const clonedRequest = request.clone({
      headers: request.headers.append('X-Authentication-Token', this.authService.getAuthToken()),
    });
    return next.handle(clonedRequest);
  }
}
```

これをテストするには、`TestBed` 構成を次のようにする必要があります。

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    provideHttpClient(withInterceptorsFromDi()),
    provideHttpClientTesting(),
    // HTTP_INTERCEPTORS トークンに依存して、AuthInterceptor を HttpInterceptor として登録します
    {provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true},
  ],
});
```
# リアクティブフォームの概要

リアクティブフォームは、時間の経過とともに値が変化するフォーム入力の処理に、モデル駆動型のアプローチを提供します。
このガイドでは、基本的なフォームコントロールの作成と更新、複数のコントロールをグループで使用すること、フォーム値の検証、実行時にコントロールを追加または削除できる動的フォームの作成について説明します。

## リアクティブフォームの概要

リアクティブフォームは、特定の時点におけるフォームの状態を管理するために、明示的で不変のアプローチを使用します。
フォーム状態に対する各変更は、新しい状態を返します。この状態は、変更間でモデルの整合性を維持します。
リアクティブフォームは、Observableストリームに基づいて構築されています。フォーム入力と値は入力値のストリームとして提供され、同期的にアクセスできます。

リアクティブフォームは、データが要求時に一貫性があり予測可能であることが保証されるため、テストの簡単な道も提供します。
ストリームのコンシューマーは誰でも、そのデータを安全に操作できます。

リアクティブフォームは、[テンプレート駆動型フォーム](guide/forms/template-driven-forms)とは異なる方法で異なります。
リアクティブフォームは、データモデルへの同期アクセス、Observable演算子を使用した不変性、Observableストリームを使用した変更追跡を提供します。

テンプレート駆動型フォームでは、テンプレート内の直接アクセスを使用してデータを変更できますが、リアクティブフォームほど明示的ではありません。これは、テンプレートに埋め込まれたディレクティブと、変更を非同期的に追跡するミュータブルデータに依存するためです。
2つのパラダイムの詳細な比較については、[フォームの概要](guide/forms)を参照してください。

## 基本的なフォームコントロールの追加

フォームコントロールを使用するには、次の3つの手順があります。

1. Generate a new component and register the reactive forms module. This module declares the reactive-form directives that you need to use reactive forms.
1. Instantiate a new `FormControl`.
1. テンプレートに `FormControl` を登録します。

次に、コンポーネントをテンプレートに追加することで、フォームを表示できます。

次の例では、単一のフォームコントロールを追加する方法を示します。
この例では、ユーザーは入力フィールドに名前を入力し、その入力値をキャプチャし、フォームコントロール要素の現在の値を表示します。

<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="テンプレートにコントロールを登録">
コンポーネントクラスでコントロールを作成したら、テンプレートのフォームコントロール要素に関連付ける必要があります。`ReactiveFormsModule` にも含まれている `FormControlDirective` によって提供される `formControl` バインディングを使用して、フォームコントロールをテンプレートのフォームコントロールに関連付けます。

<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="コンポーネントを表示">
`name` プロパティに割り当てられた `FormControl` は、`<app-name-editor>` コンポーネントをテンプレートに追加すると表示されます。

<docs-code header="app.component.html (name editor)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" region="app-name-editor"/>
</docs-step>
</docs-workflow>

### フォームコントロール値の表示

値は、次の方法で表示できます。

- `valueChanges` Observableを介して、`AsyncPipe` を使用してテンプレートで、または `subscribe()` メソッドを使用してコンポーネントクラスで、フォームの値の変更をリッスンできます。
- `value` プロパティを使用すると、現在の値のスナップショットを取得できます。

次の例では、テンプレートの補間を使用して、現在の値を表示する方法を示します。

<docs-code header="name-editor.component.html (control value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="display-value"/>

表示される値は、フォームコントロール要素を更新すると変更されます。

リアクティブフォームは、各インスタンスに提供されるプロパティとメソッドを介して、特定のコントロールに関する情報にアクセスできます。
基になる [AbstractControl](api/forms/AbstractControl "API リファレンス") クラスのプロパティとメソッドは、フォームの状態を制御し、[入力検証](#validating-form-input "フォーム入力の検証について学ぶ") を処理するときにメッセージを表示するタイミングを判断するために使用されます。

[API リファレンス](api/forms/FormControl "詳細な構文リファレンス") で、他の `FormControl` プロパティとメソッドについて説明します。

### フォームコントロール値の置換

リアクティブフォームには、ユーザーの操作なしに値をプログラムで更新できる、コントロールの値をプログラムで変更するためのメソッドがあります。
フォームコントロールインスタンスは、フォームコントロールの値を更新し、提供された値の構造をコントロールの構造に対して検証する `setValue()` メソッドを提供します。
たとえば、バックエンドAPIまたはサービスからフォームデータを取得する場合は、`setValue()` メソッドを使用してコントロールを新しい値に更新し、古い値を完全に置き換えます。

次の例では、`setValue()` メソッドを使用してコントロールの値を _Nancy_ に更新するメソッドをコンポーネントクラスに追加します。

<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"/>

テンプレートに、名前の更新をシミュレートするボタンを追加します。
**名前の更新** ボタンをクリックすると、フォームコントロール要素に入力された値は現在の値として反映されます。

<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"/>

フォームモデルはコントロールの真実の源であるため、ボタンをクリックすると、コンポーネントクラス内で入力の値が変更され、現在の値が上書きされます。

HELPFUL: この例では、単一のコントロールを使用しています。
[フォームグループ](#grouping-form-controls) または [フォーム配列](#creating-dynamic-forms) インスタンスで `setValue()` メソッドを使用する場合は、値がグループまたは配列の構造と一致する必要があります。

## フォームコントロールのグループ化 {#grouping-form-controls}

フォームには、通常、いくつかの関連するコントロールが含まれています。
リアクティブフォームは、複数の関連するコントロールを単一の入力フォームにグループ化する2つの方法を提供します。

フォームコントロールインスタンスが単一の入力フィールドを制御するのと同じように、フォームグループインスタンスは、フォームコントロールインスタンスのグループ（たとえば、フォーム）のフォーム状態を追跡します。
フォームグループインスタンスの各コントロールは、フォームグループを作成するときに名前で追跡されます。
次の例は、単一のグループで複数のフォームコントロールインスタンスを管理する方法を示します。

`ProfileEditor` コンポーネントを生成し、`@angular/forms` パッケージから `FormGroup` と `FormControl` クラスをインポートします。

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

このコンポーネントにフォームグループを追加するには、次の手順を実行します。

1. `FormGroup` インスタンスを作成します。
1. `FormGroup` モデルとビューを関連付けます。
1. フォームデータを保存します。

<docs-workflow>

<docs-step title="FormGroup インスタンスの作成">
コンポーネントクラスに `profileForm` という名前のプロパティを作成し、プロパティを新しいフォームグループインスタンスに設定します。フォームグループを初期化するには、コンストラクターに、名前付きキーのオブジェクトを、そのコントロールにマップして渡します。

プロファイルフォームの場合、`firstName` と `lastName` という名前の2つのフォームコントロールインスタンスを追加します

<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"/>

個々のフォームコントロールは、グループ内に収集されました。`FormGroup` インスタンスは、グループの各コントロールの値から縮小されたオブジェクトとしてモデル値を提供します。フォームグループインスタンスには、フォームコントロールインスタンスと同じプロパティ（`value` や `untouched` など）とメソッド（`setValue()` など）があります。
</docs-step>

<docs-step title="FormGroup モデルとビューの関連付け">
フォームグループは、その各コントロールのステータスと変更を追跡するため、コントロールのいずれかが変更されると、親コントロールも新しいステータスまたは値の変更を発行します。グループのモデルは、そのメンバーから維持されます。モデルを定義したら、テンプレートを更新して、ビューにモデルを反映する必要があります。

<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="フォームデータの保存">
`ProfileEditor` コンポーネントはユーザーからの入力を受け付けますが、実際のシナリオでは、フォーム値をキャプチャして、コンポーネント外部でさらに処理できるようにする必要があります。`FormGroup` ディレクティブは、`form` 要素によって発行された `submit` イベントをリッスンし、`ngSubmit` イベントを発行します。このイベントは、コールバック関数にバインドできます。`onSubmit()` コールバックメソッドを使用して、`form` タグに `ngSubmit` イベントリスナーを追加します。

<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"/>

`ProfileEditor` コンポーネントの `onSubmit()` メソッドは、`profileForm` の現在の値をキャプチャします。`EventEmitter` を使用してフォームをカプセル化し、コンポーネント外部にフォーム値を提供します。次の例では、`console.warn` を使用して、ブラウザコンソールにメッセージをログ出力します。

<docs-code header="profile-editor.component.ts (submit method)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="on-submit"/>

`submit` イベントは、組み込みのDOMイベントを使用して `form` タグによって発行されます。`submit` タイプのボタンをクリックすることで、イベントをトリガーします。これにより、ユーザーは **Enter** キーを押して、完了したフォームを送信できます。

`button` 要素を使用して、フォームの最下部にボタンを追加して、フォーム送信をトリガーします。

<docs-code header="profile-editor.component.html (submit button)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="submit-button"/>

前述のスニペットのボタンにも、`disabled` バインディングが付けられています。これにより、`profileForm` が無効な場合、ボタンが無効になります。まだ検証していないため、ボタンは常に有効になっています。基本的なフォーム検証については、[フォーム入力の検証](#validating-form-input) セクションを参照してください。
</docs-step>

<docs-step title="コンポーネントを表示">
フォームを含む `ProfileEditor` コンポーネントを表示するには、コンポーネントテンプレートに追加します。

<docs-code header="app.component.html (profile editor)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" region="app-profile-editor"/>

`ProfileEditor` を使用して、フォームグループインスタンス内の `firstName` と `lastName` コントロールのフォームコントロールインスタンスを管理できます。

### ネストされたフォームグループの作成 {#creating-nested-form-groups}

フォームグループは、個々のフォームコントロールインスタンスと、他のフォームグループインスタンスの両方を受け入れることができます。
これにより、複雑なフォームモデルの構成を、維持しやすく、論理的にグループ化できます。

複雑なフォームを構築する場合、情報のさまざまな領域を、より小さなセクションで管理する方が簡単です。
ネストされたフォームグループインスタンスを使用すると、大きなフォームグループを、より小さく、管理しやすいグループに分割できます。

より複雑なフォームを作成するには、次の手順を実行します。

1. ネストされたグループを作成します。
1. テンプレートでネストされたフォームをグループ化します。

情報のいくつかのタイプは、自然と同一のグループに分類されます。
名前と住所は、そのようなネストされたグループの典型的な例であり、次の例で使用されます。

<docs-workflow>
<docs-step title="ネストされたグループの作成">
`profileForm` にネストされたグループを作成するには、フォームグループインスタンスにネストされた `address` 要素を追加します。

<docs-code header="profile-editor.component.ts (nested form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="nested-formgroup"/>

この例では、`address group` は、現在の `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 (template nested form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="formgroupname"/>

`ProfileEditor` フォームは、1つのグループとして表示されますが、モデルはさらに分解されて、論理的なグループ化領域を表します。

`value` プロパティと `JsonPipe` を使用して、コンポーネントテンプレートにフォームグループインスタンスの値を表示します。
</docs-step>
</docs-workflow>

### データモデルの一部を更新する

複数のコントロールを含むフォームグループインスタンスの値を更新する場合は、モデルの一部だけを更新する場合があります。
このセクションでは、フォームコントロールデータモデルの特定の部分を更新する方法について説明します。

モデル値を更新するには、次の2つの方法があります。

`setValue()` メソッドの厳密なチェックは、複雑なフォームのネストエラーを検出するのに役立ちますが、`patchValue()` は、これらのエラーでサイレントに失敗します。

`ProfileEditorComponent` では、次の例を使用して、ユーザーの氏名と住所を更新する `updateProfile` メソッドを使用します。

<docs-code header="profile-editor.component.ts (patch value)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="patch-value"/>

テンプレートにボタンを追加して、オンデマンドでユーザープロファイルを更新することで、更新をシミュレートします。

<docs-code header="profile-editor.component.html (update value)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="patch-value"/>

ユーザーがボタンをクリックすると、`profileForm` モデルが、`firstName` と `street` の新しい値で更新されます。`street` は、`address` プロパティ内のオブジェクトで提供されることに注意してください。
これは、`patchValue()` メソッドが、モデル構造に対して更新を適用するためです。
`PatchValue()` は、フォームモデルで定義されているプロパティのみを更新します。

## FormBuilder サービスを使用してコントロールを生成する

複数のフォームを扱う場合は、手動でフォームコントロールインスタンスを作成すると、反復処理になる可能性があります。
`FormBuilder` サービスは、コントロールを生成するための便利なメソッドを提供します。

このサービスを利用するには、次の手順を実行します。

1. `FormBuilder` クラスをインポートします。
1. `FormBuilder` サービスを注入します。
1. フォームの内容を生成します。

次の例では、`FormBuilder` サービスを使用して、フォームコントロールとフォームグループインスタンスを作成し、`ProfileEditor` コンポーネントをリファクタリングする方法を示します。

<docs-workflow>
<docs-step title="FormBuilder クラスのインポート">
`@angular/forms` パッケージから `FormBuilder` クラスをインポートします。

<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="FormBuilder サービスの注入">
`FormBuilder` サービスは、リアクティブフォームモジュールで提供される、注入可能なプロバイダーです。`inject()`関数を使ってこの依存関係を注入します。

<docs-code header="profile-editor.component.ts (property init)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="inject-form-builder"/>

</docs-step>
<docs-step title="フォームコントロールの生成">
`FormBuilder` サービスには、`control()`、`group()`、`array()` の3つのメソッドがあります。これらは、フォームコントロール、フォームグループ、フォーム配列を含む、コンポーネントクラスでインスタンスを生成するためのファクトリメソッドです。`group` メソッドを使用して、`profileForm` コントロールを作成します。

<docs-code header="profile-editor.component.ts (form builder)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-builder"/>

前の例では、モデルのプロパティを定義するために、同じオブジェクトを使用して `group()` メソッドを使用しています。各コントロール名の値は、配列に含まれ、初期値を配列の最初の項目として含みます。

TIP: コントロールを初期値だけで定義できますが、コントロールに同期または非同期検証が必要な場合は、配列の2番目と3番目の項目として同期バリデーターと非同期バリデーターを追加します。フォームビルダーの使用を、手動でインスタンスを作成する方法と比較します。
</docs-step>

</docs-workflow>

## フォーム入力の検証 {#validating-form-input}

_フォーム検証_ は、ユーザー入力が完全で正しいことを確認するために使用されます。
このセクションでは、フォームコントロールに単一のバリデーターを追加し、フォーム全体のステータスを表示する方法について説明します。
フォーム検証については、[フォーム検証](guide/forms/form-validation) ガイドで、より詳しく説明しています。

フォーム検証を追加するには、次の手順を実行します。

1. フォームコンポーネントにバリデーター関数をインポートします。
1. フォームのフィールドにバリデーターを追加します。
1. 検証ステータスを処理するロジックを追加します。

最も一般的な検証は、フィールドを必須にすることです。
次の例では、`firstName` コントロールに必須の検証を追加し、検証の結果を表示する方法を示します。

<docs-workflow>
<docs-step title="検証子関数のインポート">
リアクティブフォームには、一般的なユースケース向けの検証子関数のセットが含まれています。これらの関数は、検証するコントロールを受け取り、検証チェックに基づいてエラーオブジェクトまたはnull値を返します。

`@angular/forms` パッケージから `Validators` クラスをインポートします。

<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="フィールドを必須にする">
`ProfileEditor` コンポーネントで、`firstName` コントロールの配列の2番目の項目として、`Validators.required` 静的メソッドを追加します。

<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="フォームステータスの表示">
フォームコントロールに必須フィールドを追加すると、その初期ステータスは無効になります。この無効なステータスは、親フォームグループ要素に伝達され、そのステータスが無効になります。フォームグループインスタンスの現在のステータスには、`status` プロパティを介してアクセスできます。

`profileForm` の現在のステータスを補間を使用して表示します。

<docs-code header="profile-editor.component.html (display status)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="display-status"/>

**Submit** ボタンは無効になっています。これは、必須の `firstName` フォームコントロールのため、`profileForm` が無効になっているためです。`firstName` 入力に値を入力すると、フォームは有効になり、**Submit** ボタンが有効になります。

フォーム検証の詳細については、[フォーム検証](guide/forms/form-validation) ガイドを参照してください。
</docs-step>
</docs-workflow>

## 動的フォームの作成 {#creating-dynamic-forms}

`FormArray` は、名前のないコントロールを任意の数管理するための `FormGroup` の代替手段です。
フォームグループインスタンスと同様に、フォーム配列インスタンスにコントロールを動的に挿入および削除でき、フォーム配列インスタンスの値と検証ステータスは、その子コントロールから計算されます。
ただし、各コントロールのキーを名前で定義する必要がないため、コントロールの数があらかじめわからない場合は、このオプションが適しています。

動的フォームを定義するには、次の手順を実行します。

1. `FormArray` クラスをインポートします。
1. `FormArray` コントロールを定義します。
1. ゲッターメソッドを使用して、`FormArray` コントロールにアクセスします。
1. テンプレートにフォーム配列を表示します。

次の例では、`ProfileEditor` で _エイリアス_ の配列を管理する方法を示します。

<docs-workflow>
<docs-step title="`FormArray` クラスのインポート">
`@angular/forms` から `FormArray` クラスをインポートして、タイプ情報に使用します。`FormBuilder` サービスは、`FormArray` インスタンスを作成する準備ができています。

<docs-code header="profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-array-imports"/>
</docs-step>

<docs-step title="`FormArray` コントロールの定義">
`FormArray` を、任意の数のコントロール（0から多数）で初期化できます。これらは、配列で定義します。`profileForm` のフォームグループインスタンスに `aliases` プロパティを追加して、フォーム配列を定義します。

`FormBuilder.array()` メソッドを使用して配列を定義し、`FormBuilder.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"/>

フォームグループインスタンスのエイリアスコントロールは、動的にコントロールを追加するまで、単一のコントロールで設定されます。
</docs-step>

<docs-step title="`FormArray` コントロールにアクセス">
`profileForm.get()` メソッドを繰り返し使用して各インスタンスを取得するのではなく、ゲッターは、フォーム配列インスタンスのエイリアスにアクセスできます。フォーム配列インスタンスは、配列内の未定義数のコントロールを表します。ゲッターを介してコントロールにアクセスするのは便利で、このアプローチは、追加のコントロールに対して簡単に繰り返すことができます。 <br />

ゲッター構文を使用して、`aliases` クラスプロパティを作成し、親フォームグループからエイリアスのフォーム配列コントロールを取得します。

<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"/>

返されるコントロールは `AbstractControl` 型であるため、フォーム配列インスタンスのメソッド構文にアクセスするには、明示的な型を指定する必要があります。フォーム配列にエイリアスコントロールを動的に挿入するメソッドを定義します。`FormArray.push()` メソッドは、コントロールを配列の新しい項目として挿入します。また、コントロールの配列をFormArray.push()に渡すと、複数のコントロールを一度に登録できます。

<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"/>

テンプレートでは、各コントロールが個別の入力フィールドとして表示されます。

</docs-step>

<docs-step title="テンプレートにフォーム配列を表示">

フォームモデルからエイリアスを添付するには、テンプレートに追加する必要があります。`FormGroupNameDirective` によって提供される `formGroupName` 入力と同様に、`formArrayName` は、フォーム配列インスタンスからの通信を、`FormArrayNameDirective` を使用してテンプレートにバインドします。

次のテンプレートHTMLを、`formGroupName` 要素を閉じる `<div>` の後に追加します。

<docs-code header="profile-editor.component.html (aliases form array template)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="formarrayname"/>

`@for` ブロックは、エイリアスのフォーム配列インスタンスによって提供される各フォームコントロールインスタンスを反復処理します。フォーム配列要素は名前がないため、インデックスを `i` 変数に割り当て、`formControlName` 入力に渡して、各コントロールをバインドします。

新しいエイリアスインスタンスが追加されるたびに、新しいフォーム配列インスタンスに、インデックスに基づいてコントロールが提供されます。これにより、ルートコントロールのステータスと値を計算する際に、各個別のコントロールを追跡できます。

</docs-step>

### トップレベルフォーム配列での `FormArrayDirective` の使用

`FormArrayDirective` を使用して、`FormArray` を `<form>` 要素に直接バインドできます。
これは、フォームがトップレベルの `FormGroup` を使用せず、配列自体が完全なフォームモデルを表す場合に便利です。

```typescript
import { Component } from '@angular/core';
import { FormArray, FormControl } from '@angular/forms';

@Component({
  selector: 'form-array-example',
  template: `
    <form [formArray]="form">
      @for (control of form.controls; track $index) {
        <input [formControlName]="$index">
      }
    </form>
  `,
})
export class FormArrayExampleComponent {
  controls = [
    new FormControl('fish'),
    new FormControl('cat'),
    new FormControl('dog'),
  ];

form = new FormArray(this.controls);
}
```

<docs-step title="エイリアスの追加">

最初は、フォームには `Alias` フィールドが1つ含まれています。別のフィールドを追加するには、**エイリアスの追加** ボタンをクリックします。また、テンプレートの下部にある `Form Value` によって表示されるフォームモデルに報告されるエイリアスの配列も検証できます。各エイリアスについて、フォームコントロールインスタンスではなく、追加のフィールドを持つ別のフォームグループインスタンスを構成できます。各項目のコントロールを定義するプロセスは同じです。
</docs-step>

</docs-workflow>

## 統一されたコントロール状態変更イベント {#unified-control-state-change-events}

すべてのフォームコントロールは、`AbstractControl`（`FormControl`、`FormGroup`、`FormArray`、`FormRecord`）の `events` Observableを介して、**コントロール状態変更イベント**の単一の統一されたストリームを公開します。
この統一されたストリームにより、**value**、**status**、**pristine**、**touched**、**reset** の状態変更、および **submit** などの **フォームレベルのアクション** に反応でき、複数のObservableを配線する代わりに、1つのサブスクリプションですべての更新を処理できます。

### イベントタイプ {#event-types}

`events` によって発行される各アイテムは、特定のイベントクラスのインスタンスです。

- **`ValueChangeEvent`** — コントロールの **value** が変更されたとき。
- **`StatusChangeEvent`** — コントロールの **検証ステータス** が `FormControlStatus` 値（`VALID`、`INVALID`、`PENDING`、または `DISABLED`）のいずれかに更新されたとき。
- **`PristineChangeEvent`** — コントロールの **pristine/dirty** 状態が変更されたとき。
- **`TouchedChangeEvent`** — コントロールの **touched/untouched** 状態が変更されたとき。
- **`FormResetEvent`** — `reset()` APIまたはネイティブアクションを介してコントロールまたはフォームがリセットされたとき。
- **`FormSubmittedEvent`** — フォームが送信されたとき。

すべてのイベントクラスは `ControlEvent` を拡張し、変更を発生させた `AbstractControl` への `source` 参照が含まれます。これは大規模なフォームで便利です。

```ts
import {Component} from '@angular/core';
import {
  FormControl,
  ValueChangeEvent,
  StatusChangeEvent,
  PristineChangeEvent,
  TouchedChangeEvent,
  FormResetEvent,
  FormSubmittedEvent,
  ReactiveFormsModule,
  FormGroup,
} from '@angular/forms';

@Component({
  /* ... */
})
export class UnifiedEventsBasicComponent {
  form = new FormGroup({
    username: new FormControl(''),
  });

constructor() {
    this.form.events.subscribe((e) => {
      if (e instanceof ValueChangeEvent) {
        console.log('Value changed to: ', e.value);
      }

if (e instanceof StatusChangeEvent) {
        console.log('Status changed to: ', e.status);
      }

if (e instanceof PristineChangeEvent) {
        console.log('Pristine status changed to: ', e.pristine);
      }

if (e instanceof TouchedChangeEvent) {
        console.log('Touched status changed to: ', e.touched);
      }

if (e instanceof FormResetEvent) {
        console.log('Form was reset');
      }

if (e instanceof FormSubmittedEvent) {
        console.log('Form was submitted');
      }
    });
  }
}
```

### 特定のイベントのフィルタリング {#filtering-specific-events}

イベントタイプのサブセットのみが必要な場合は、RxJS演算子を使用します。

```ts
import {filter} from 'rxjs/operators';
import {StatusChangeEvent} from '@angular/forms';

control.events
  .pipe(filter((e) => e instanceof StatusChangeEvent))
  .subscribe((e) => console.log('Status:', e.status));
```

### 複数のサブスクリプションからの統一 {#unifying-from-multiple-subscriptions}

**Before**

```ts
import {combineLatest} from 'rxjs/operators';

combineLatest([control.valueChanges, control.statusChanges]).subscribe(([value, status]) => {
  /* ... */
});
```

**After**

```ts
control.events.subscribe((e) => {
  // Handle ValueChangeEvent, StatusChangeEvent, etc.
});
```

NOTE: 値の変更時、このコントロールの値が更新された直後に発行が発生します。親コントロールの値（たとえば、このFormControlがFormGroupの一部である場合）は後で更新されるため、このイベントのコールバックから親コントロールの値（`value` プロパティを使用）にアクセスすると、まだ更新されていない値を取得する可能性があります。代わりに親コントロールの `events` をサブスクライブしてください。

## フォームコントロール状態の管理

リアクティブフォームは、**touched/untouched** と **pristine/dirty** を通じてコントロールの状態を追跡します。AngularはDOM操作中にこれらを自動的に更新しますが、プログラムで管理もできます。

**[`markAsTouched`](api/forms/FormControl#markAsTouched)** — フォーカスとブラーイベントによってコントロールまたはフォームを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();
}
```

## イベント発行と伝播の制御

フォームコントロールをプログラムで更新する場合、フォーム階層を通じて変更を伝播する方法と、イベントを発行するかどうかを正確に制御できます。

### イベント発行の理解

デフォルトで `emitEvent: true` の場合、コントロールへの変更は `valueChanges` と `statusChanges` Observableを通じてイベントを発行します。`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 });
  }

}
```

### 伝播制御の理解

デフォルトで `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 });
}
```

## フォームコントロールタイプを絞り込むユーティリティ関数 {#utility-functions-for-narrowing-form-control-types}

Angularは、`AbstractControl` の具体的な型を判定するのに役立つ4つのユーティリティ関数を提供します。これらの関数は **型ガード** として機能し、`true` を返すときにコントロールタイプを絞り込むため、同じブロック内でサブタイプ固有のプロパティに安全にアクセスできます。

これらのヘルパーは、関数シグネチャが `AbstractControl` を受け取りますが、ロジックが特定のコントロールの種類を対象としている **カスタムバリデーター** で特に便利です。

```ts
import {AbstractControl, isFormArray} from '@angular/forms';

export function positiveValues(control: AbstractControl) {
  if (!isFormArray(control)) {
    return null; // Not a FormArray: validator is not applicable.
  }

// Safe to access FormArray-specific API after narrowing.
  const hasNegative = control.controls.some((c) => c.value < 0);
  return hasNegative ? {positiveValues: true} : null;
}
```

## リアクティブフォームAPIの概要 {#reactive-forms-api-summary}

次の表は、リアクティブフォームコントロールの作成と管理に使用されるベースクラスとサービスをリストしています。
構文の詳細については、[フォームパッケージ](api#forms "API リファレンス") のAPIリファレンスドキュメントを参照してください。

### クラス

### ディレクティブ

Angular 14から、リアクティブフォームはデフォルトで厳密に型付けされるようになりました。

このガイドの背景として、[Angular リアクティブフォーム](guide/forms/reactive-forms) に既に精通している必要があります。

## 型付きフォームの概要

<docs-video src="https://www.youtube.com/embed/L-odCf4MfJc" alt="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) ではありません）のみに適用されます。

## 型なしフォーム

型なしフォームは引き続きサポートされており、これまでどおり動作します。それらを使用するには、`@angular/forms` から `Untyped` シンボルをインポートする必要があります。

```ts
const login = new UntypedFormGroup({
  email: new UntypedFormControl(''),
  password: new UntypedFormControl(''),
});
```

各 `Untyped` シンボルは、以前のバージョンのAngularとまったく同じ意味を持ちます。`Untyped` プレフィックスを削除することで、段階的に型を有効にできます。

## `FormControl`: はじめに

最も単純なフォームは、単一のコントロールで構成されます。

```ts
const email = new FormControl('angularrox@gmail.com');
```

このコントロールは、自動的に `FormControl<string|null>` 型であると推測されます。TypeScriptは、`email.value`、`email.valueChanges`、`email.setValue(...)` など、[`FormControl` API](api/forms/FormControl) 全体にわたってこの型を自動的に強制します。

### ヌラビリティ

疑問に思うかもしれません。なぜこのコントロールの型には `null` が含まれているのでしょうか? これは、コントロールがいつでも `reset` を呼び出すことで `null` になる可能性があるためです。

```ts
const email = new FormControl('angularrox@gmail.com');
email.reset();
console.log(email.value); // null
```

TypeScriptは、コントロールが `null` になっている可能性を常に処理するように強制します。このコントロールをヌラブルでないものにする場合は、`nonNullable` オプションを使用できます。これにより、コントロールは `null` ではなく、初期値にリセットされます。

```ts
const email = new FormControl('angularrox@gmail.com', {nonNullable: true});
email.reset();
console.log(email.value); // angularrox@gmail.com
```

繰り返しますが、このオプションは `.reset()` が呼び出されたときのフォームのランタイム動作に影響を与え、注意深く切り替える必要があります。

### 明示的な型の指定

推測に頼るのではなく、型を指定できます。初期値が `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`: 動的な同種コレクション

`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` という型を提供します。

### 部分的な値

再びログインフォームを考えてみましょう。

```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は、`undefined` である可能性のある値を処理するように強制します（`strictNullChecks` を有効にしている場合）。

無効なコントロールを_含む_値にアクセスしたい場合、つまり `undefined` である可能性のあるフィールドをバイパスしたい場合は、`login.getRawValue()` を使用できます。

### オプションのコントロールと動的グループ

一部のフォームには、存在する可能性がある場合とない場合があるコントロールが含まれており、実行時に追加または削除できます。これらのコントロールは、_オプションフィールド_ を使用して表すことができます。

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

一部の `FormGroup` の使用方法は、上記の例に当てはまりません。なぜなら、キーが事前にわからないからです。`FormRecord` クラスは、そのケース用に設計されています。

```ts
const addresses = new FormRecord<FormControl<string | null>>({});
addresses.addControl('Andrew', new FormControl('2340 Folsom St'));
```

`string|null` 型の任意のコントロールを、この `FormRecord` に追加できます。

動的（オープンエンド）でかつ異種（コントロールが異なる型である）な `FormGroup` が必要な場合、型安全性の向上は不可能であり、`UntypedFormGroup` を使用する必要があります。

`FormRecord` は、`FormBuilder` を使用して構築もできます。

```ts
const addresses = fb.record({'Andrew': '2340 Folsom St'});
```

## `FormBuilder` と `NonNullableFormBuilder`

`FormBuilder` クラスは、上記の例と同じように、新しい型をサポートするようにアップグレードされました。

さらに、追加のビルダー `NonNullableFormBuilder` が使用できます。この型は、すべてのコントロールに `nonNullable: true}` を指定するための省略記号であり、大きなヌラブルでないフォームからかなりのボイラープレートを排除できます。`FormBuilder` の `nonNullable` プロパティを使用してアクセスできます。

```ts
const fb = new FormBuilder();
const login = fb.nonNullable.group({
  email: '',
  password: '',
});
```

上記の例では、両方の内部コントロールはヌラブルではありません（つまり、`nonNullable` が設定されます）。

`NonNullableFormBuilder` という名前を使用した注入もできます。
# テンプレート駆動型フォームの作成

このチュートリアルでは、テンプレート駆動型フォームの作成方法について説明します。フォーム内のコントロール要素は、入力検証を含むデータプロパティにバインドされています。入力検証は、データの整合性を維持し、ユーザー体験を向上させるためのスタイリングに役立ちます。

テンプレート駆動型フォームは、[双方向データバインディング](guide/templates/two-way-binding)を使用して、テンプレートでの変更が加えられたときにコンポーネントのデータモデルを更新し、その逆も同様に行います。
Angularは、インタラクティブフォームのために2つの設計アプローチをサポートしています。テンプレート駆動型フォームでは、Angularテンプレートでフォーム固有のディレクティブを使用できます。リアクティブフォームは、フォーム構築のためのモデル駆動型アプローチを提供します。

テンプレート駆動型フォームは、小規模または単純なフォームに適していますが、リアクティブフォームはよりスケーラブルで、複雑なフォームに適しています。2つのアプローチの比較については、[アプローチの選択](guide/forms#choosing-an-approach)を参照してください。
Angularテンプレートを使用して、ログインフォーム、コンタクトフォーム、ほとんどのビジネスフォームなど、あらゆる種類のフォームを構築できます。
コントロールをクリエイティブにレイアウトし、オブジェクトモデル内のデータにバインドできます。
検証ルールを指定し、検証エラーを表示し、特定のコントロールからの入力を条件付きで許可します。そして、組み込みの視覚的なフィードバックをトリガーし、その他多くのことができます。

## 目標

このチュートリアルでは、次の方法について学びます。

- コンポーネントとテンプレートを使用してAngularフォームを構築する
- `ngModel`を使用して、入力コントロールの値を読み書きするための双方向データバインディングを作成する
- コントロールの状態を追跡する特別なCSSクラスを使用して、視覚的なフィードバックを提供する
- ユーザーに検証エラーを表示し、フォームの状態に基づいてフォームコントロールからの入力を条件付きで許可する
- [テンプレート参照変数](guide/templates/variables#template-reference-variables)を使用して、HTML要素間で情報を共有する

## テンプレート駆動型フォームの構築

テンプレート駆動型フォームは、`FormsModule`で定義されたディレクティブに依存します。

| ディレクティブ     | 詳細 |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NgModel`      | アタッチされたフォーム要素の値の変更とデータモデルの変更を調整し、入力検証やエラー処理を使用してユーザー入力に対応できるようにします。                                                                                                           |
| `NgForm`       | トップレベルの`FormGroup`インスタンスを作成し、`<form>`要素にバインドして、集計されたフォームの値と検証の状態を追跡します。`FormsModule`をインポートすると、このディレクティブはすべての`<form>`タグでデフォルトでアクティブになります。特別なセレクターを追加する必要はありません。 |
| `NgModelGroup` | DOM要素に`FormGroup`インスタンスを作成してバインドします。                                                                                                                                                                                                                      |

### ステップの概要

このチュートリアルでは、次の手順を使用して、サンプルフォームをデータにバインドし、ユーザー入力を処理します。

1. 基本的なフォームを構築する。
   - サンプルデータモデルを定義する
   - `FormsModule`など、必要なインフラストラクチャを含める
1. `ngModel`ディレクティブと双方向データバインディング構文を使用して、フォームコントロールをデータプロパティにバインドする。
   - `ngModel`がCSSクラスを使用してコントロールの状態を報告する方法を調べる
   - コントロールに名前を付けて、`ngModel`からアクセスできるようにする
1. `ngModel`を使用して、入力の有効性とコントロールの状態を追跡する。
   - 状態に基づいて視覚的なフィードバックを提供するためのカスタムCSSを追加する
   - 検証エラーメッセージを表示および非表示にする
1. モデルデータに追加することで、ネイティブHTMLボタンのクリックイベントに対応する。
1. フォームの[`ngSubmit`](api/forms/NgForm#properties)出力プロパティを使用して、フォームの送信を処理する。
   - フォームが有効になるまで、**Submit**ボタンを無効にする
   - 送信後、ページ上の異なるコンテンツに、完了したフォームを交換する

## フォームの構築

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"/>

初期テンプレートは、2つのフォームグループと送信ボタンを持つフォームのレイアウトを定義します。
   フォームグループは、Actorデータモデルの2つのプロパティ（名前とスタジオ）に対応します。
   各グループには、ラベルとユーザー入力を得るためのボックスがあります。
   - **名前**`<input>`コントロール要素には、HTML5の`required`属性があります
   - **スタジオ**`<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 (skills)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="skills"/>

アプリケーションを今すぐ実行すると、選択コントロールにスキルのリストが表示されます。
入力要素は、まだデータ値やイベントにバインドされていないため、空欄であり、動作しません。

## 入力コントロールをデータプロパティにバインドする

次のステップは、入力コントロールを対応する`Actor`プロパティに双方向データバインディングでバインドすることです。これにより、ユーザー入力がデータモデルを更新し、データのプログラムによる変更がディスプレイを更新します。

`FormsModule`で宣言された`ngModel`ディレクティブを使用すると、テンプレート駆動型フォームのテンプレート内のコントロールを、データモデルのプロパティにバインドできます。
双方向データバインディングの構文`[(ngModel)]="..."`を使用してディレクティブを含めると、Angularはコントロールの値とユーザー操作を追跡し、ビューとモデルを同期させることができます。

1. テンプレートファイル`actor-form.component.html`を編集します。
1. **名前**ラベルの隣の`<input>`タグを探します。
1. `ngModel`ディレクティブを追加し、双方向データバインディング構文`[(ngModel)]="..."`を使用します。

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngModelName-1"/>

HELPFUL: この例では、各入力タグの後に一時的な診断用補間`{{model.name}}`が追加され、対応するプロパティの現在のデータ値が表示されます。コメントは、双方向データバインディングの動作を観察し終わったら、診断用行を削除するよう思い出させてくれます。

### フォーム全体のステータスにアクセスする

コンポーネントで`FormsModule`をインポートすると、Angularはテンプレートの`<form>`タグに[NgForm](api/forms/NgForm)ディレクティブを自動的に作成してアタッチします（`NgForm`のセレクターは`<form>`要素と一致する`form`だからです）。

`NgForm`とフォーム全体のステータスにアクセスするには、[テンプレート参照変数](guide/templates/variables#template-reference-variables)を宣言します。

1. テンプレートファイル`actor-form.component.html`を編集します。
1. テンプレート参照変数`#actorForm`を付けて`<form>`タグを更新し、次の値を設定します。

<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"/>

`actorForm`テンプレート変数は、フォーム全体を管理する`NgForm`ディレクティブインスタンスへの参照になります。

1. アプリケーションを実行します。
1. **名前**入力ボックスに入力し始めます。

文字を追加したり削除したりすると、データモデルにも表示および非表示されます。

補間された値を表示する診断用行は、値が実際に入力ボックスからモデルに、そしてモデルから入力ボックスに戻っていることを示しています。

### コントロール要素に名前を付ける

`[(ngModel)]`を要素に使用する場合は、その要素の`name`属性を定義する必要があります。
Angularは、割り当てられた名前を使用して、親`<form>`要素にアタッチされた`NgForm`ディレクティブに要素を登録します。

例では、`<input>`要素に`name`属性を追加し、"name"に設定しました。これは、アクターの名前を表現するのに理にかなっています。
任意のユニークな値で構いませんが、わかりやすい名前を使用すると便利です。

1. **スタジオ**と**スキル**に同様の`[(ngModel)]`バインディングと`name`属性を追加します。
1. 補間された値を表示する診断メッセージを削除できます。
1. アクターモデル全体に双方向データバインディングが機能することを確認するために、コンポーネントのテンプレートの最上部に、[`json`](api/common/JsonPipe)パイプを使用した新しいテキストバインディングを追加します。これは、データを文字列にシリアライズします。

これらの変更を加えた後、フォームテンプレートは次のようになります。

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngModel-2"/>

次のことに注意してください。

- 各`<input>`要素には`id`プロパティがあります。
   これは、`<label>`要素の`for`属性によって使用され、ラベルを入力コントロールに一致させます。
   これは[標準的なHTML機能](https://developer.mozilla.org/docs/Web/HTML/Element/label)です。

- 各`<input>`要素には、Angularがフォームにコントロールを登録するために使用する必要な`name`プロパティもあります。

効果を確認したら、`{{ model | json }}`テキストバインディングを削除できます。

## フォームの状態を追跡する

Angularは、フォームが送信された後に`form`要素に`ng-submitted`クラスを適用します。このクラスは、フォームが送信された後にフォームのスタイルを変更するために使用できます。

## コントロールの状態を追跡する

コントロールに`NgModel`ディレクティブを追加すると、コントロールの状態を表すクラス名がコントロールに追加されます。
これらのクラスは、コントロールの状態に基づいてコントロールのスタイルを変更するために使用できます。

次の表は、コントロールの状態に基づいてAngularが適用するクラス名を説明しています。

Angularは、`form`要素に`ng-submitted`クラスを適用しますが、
`form`要素内のコントロールには適用しません。

これらのCSSクラスを使用して、コントロールの状態に基づいてコントロールのスタイルを定義します。

### コントロールの状態を観察する

フレームワークによるクラスの追加と削除を確認するには、ブラウザの開発者ツールを開き、アクターの名前を表す`<input>`要素を調べます。

1. ブラウザの開発者ツールを使用して、**Name**入力ボックスに対応する`<input>`要素を探します。
   要素には、"form-control"に加えて、複数のCSSクラスがあることがわかります。

1. 最初に表示すると、クラスは、値が有効であり、初期化またはリセット以降値が変更されていないこと、初期化またはリセット以降コントロールが訪問されていないことを示しています。

```html
<input class="form-control ng-untouched ng-pristine ng-valid" />;
   ```

1. **Name** `<input>`ボックスで次のように操作し、表示されるクラスを観察します。
   - 見るだけで触れずにいます。
     クラスは触られていないか、原始状態または有効であることを示しています。

- 名前のボックスをクリックし、外をクリックします。
     コントロールは訪問されたため、要素には`ng-untouched`クラスではなく`ng-touched`クラスがあります。

- 名前の最後にスラッシュを追加します。
     これで触れられて、汚れています。

- 名前を消去します。
     これにより値が無効になるため、`ng-invalid`クラスが`ng-valid`クラスに置き換えられます。

### 状態の視覚的なフィードバックを作成する

`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 (styles)" path="adev/src/content/examples/forms/src/index.html" region="styles"/>

### 検証エラーメッセージの表示と非表示

**名前**入力ボックスは必須であり、クリアするとバーが赤くなります。
これは何かが間違っていることを示していますが、ユーザーは何が間違っているのか、どうすればいいのかわかりません。
コントロールの状態をチェックして対応することで、役立つメッセージを提供できます。

**スキル**選択ボックスも必須ですが、この種のエラー処理は必要ありません。なぜなら、選択ボックスはすでに選択を有効な値に制限しているからです。

エラーメッセージを適切に定義して表示するには、次の手順を実行します。

<docs-workflow>
<docs-step title="入力へのローカル参照を追加">
テンプレートから入力ボックスのAngularコントロールにアクセスするために使用できるテンプレート参照変数を使用して、`input`タグを拡張します。例では、変数は`#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 (hidden-error-msg)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="hidden-error-msg"/>

<docs-step title="名前への条件付きエラーメッセージを追加">
次の例のように、`name`入力ボックスに条件付きエラーメッセージを追加します。

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="name-with-error-msg"/>
</docs-step>
</docs-workflow>
この例では、コントロールが有効あるいは_原始状態_のいずれかの場合にメッセージを非表示にします。
原始状態とは、ユーザーがこのフォームに表示されてから値を変更していないことを意味します。
`pristine`状態を無視すると、値が有効な場合にのみメッセージを非表示にします。
新しい空白のアクターか無効なアクターがこのコンポーネントに表示されると、何も操作する前にエラーメッセージがすぐに表示されます。

メッセージは、ユーザーが無効な変更を加えた場合にのみ表示されるようにしたいかもしれません。
コントロールが`pristine`状態の間にメッセージを非表示にすると、その目的を達成できます。
次のステップで新しいアクターをフォームに追加すると、この選択肢の重要性についてわかります。
## 新しいアクターを追加する

この演習では、モデルデータに追加することで、ネイティブHTMLボタンのクリックイベントに対応する方法を示します。
フォームユーザーが新しいアクターを追加できるようにするには、クリックイベントに対応する**New Actor**ボタンを追加します。

1. テンプレートで、フォームの下部に"New Actor"`<button>`要素を配置します。
1. コンポーネントファイルで、アクターデータモデルにアクター作成メソッドを追加します。

<docs-code header="actor-form.component.ts (New Actor method)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="new-actor"/>

1. ボタンのクリックイベントを、アクター作成メソッド`newActor()`にバインドします。

<docs-code header="actor-form.component.html (New Actor button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="new-actor-button-no-reset"/>

1. アプリケーションを再度実行し、**New Actor**ボタンをクリックします。

フォームがクリアされ、入力ボックスの左側の_必須_バーが赤くなり、`name`と`skill`プロパティが無効であることを示しています。
   エラーメッセージは非表示になっていることに注意してください。
   これは、フォームが原始状態であるためです。まだ何も変更していません。

1. 名前を入力し、**New Actor**を再度クリックします。

入力ボックスはもはや原始状態ではないため、`名前は必須です`というエラーメッセージが表示されます。
   フォームは、**New Actor**をクリックする前に名前を入力したことを覚えています。

1. フォームコントロールの原始状態を復元するには、`newActor()`メソッドを呼び出した後に、フォームの`reset()`メソッドを呼び出してすべてのフラグを強制的にクリアします。

<docs-code header="actor-form.component.html (Reset the form)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="new-actor-button-form-reset"/>

これで、**New Actor**をクリックすると、フォームとそのコントロールフラグの両方がリセットされます。

## `ngSubmit`でフォームを送信する

ユーザーは、フォームに記入したら送信できる必要があります。
フォームの下部にある**Submit**ボタンは、それ自体では何も実行しませんが、`type="submit"`であるため、フォームの送信イベントをトリガーします。

このイベントに対応するには、次の手順を実行します。

<docs-workflow>

<docs-step title="ngOnSubmitを監視する">
フォームの[`ngSubmit`](api/forms/NgForm#properties)イベントプロパティを、アクターフォームコンポーネントの`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 (submit-button)" 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="名前の値を削除する">
これは"必須"ルールに違反するため、エラーメッセージが表示されます。また、**Submit**ボタンが無効になることにも注意してください。

ボタンの有効状態をフォームの有効性に明示的にワイヤリングする必要はありませんでした。
テンプレート参照変数を拡張されたフォーム要素に定義してから、ボタンコントロールでその変数を参照すると、`FormsModule`がこれを自動的に行いました。
</docs-step>
</docs-workflow>

### フォーム送信に対応する

フォーム送信への応答を表示するには、データ入力領域を非表示にし、代わりに別のものを表示できます。

<docs-workflow>
<docs-step title="フォームをラップする">
フォーム全体を`<div>`でラップし、その`hidden`プロパティを`ActorFormComponent.submitted`プロパティにバインドします。

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="edit-div"/>

メインフォームは、`submitted`プロパティがフォームを送信するまでは偽であるため、最初から表示されます。これは、`ActorFormComponent`からの次のフラグメントで示されています。

<docs-code header="actor-form.component.ts (submitted)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="submitted"/>

**Submit**ボタンをクリックすると、`submitted`フラグが真になり、フォームが消えます。
</docs-step>

<docs-step title="送信された状態を追加する">
フォームが送信された状態の間に別のものを表示するには、新しい`<div>`ラッパーの下に次のHTMLを追加します。

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="submitted"/>

この`<div>`は、補間バインディングで読み取り専用の俳優を表示します。これは、コンポーネントが送信された状態の間にのみ表示されます。

代替表示には、_編集_ボタンが含まれます。このボタンのクリックイベントは、`submitted`フラグをクリアする式にバインドされています。
</docs-step>

<docs-step title="編集ボタンをテストする">
*編集*ボタンをクリックして、表示を編集可能なフォームに戻します。
</docs-step>
</docs-workflow>

## まとめ

このページで説明したAngularフォームは、データの修正や検証などをサポートするために、
次のフレームワーク機能を活用しています。

- Angular HTMLフォームテンプレート
- `@Component`デコレーターを含むフォームコンポーネントクラス
- `NgForm.ngSubmit`イベントプロパティにバインドすることで、フォーム送信を処理する
- `#actorForm`や`#name`などのテンプレート参照変数
- 双方向データバインディングのための`[(ngModel)]`構文
- 検証とフォーム要素の変更追跡のための`name`属性の使用
- 入力コントロールの参照変数の`valid`プロパティは、コントロールが有効であるか、エラーメッセージを表示する必要があるかを示します
- `NgForm`の有効性にバインドすることで、**Submit**ボタンの有効状態を制御する
- 有効でないコントロールについてユーザーに視覚的なフィードバックを提供するカスタムCSSクラス

アプリケーションの最終バージョンを示すコードを次に示します。
# フォーム入力の検証

正確性と完全性を確保するために、ユーザー入力を検証することで、データ品質を全体的に向上させることができます。
このページでは、UIからのユーザー入力を検証し、リアクティブフォームとテンプレート駆動フォームの両方で、役立つ検証メッセージを表示する方法について説明します。

## テンプレート駆動フォームでの入力検証 {#validating-input-in-template-driven-forms}

テンプレート駆動フォームに検証を追加するには、[ネイティブ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`は、考えられる検証エラーの1つに対してカスタムメッセージを表示できます。
    `required`、`minlength`、`forbiddenName`のメッセージがあります。

HELPFUL: ユーザーがフォームを編集する機会がある前に、バリデーターがエラーを表示しないようにするには、コントロールの`dirty`または`touched`状態のいずれかをチェックする必要があります。

- ユーザーが監視対象のフィールドの値を変更すると、コントロールは「dirty」としてマークされます。
- ユーザーがフォームコントロール要素からフォーカスを外すと、コントロールは「touched」としてマークされます。

## リアクティブフォームでの入力検証 {#validating-input-in-reactive-forms}

リアクティブフォームでは、真実の源はコンポーネントクラスです。
テンプレートで属性を通じてバリデーターを追加する代わりに、コンポーネントクラスのフォームコントロールモデルに直接バリデーター関数を追加します。
その後、Angularは、コントロールの値が変更されるたびにこれらの関数を呼び出します。

### バリデーター関数 {#validator-functions}

バリデーター関数は、同期または非同期にできます。

| バリデーターの種類   | 詳細                                                                                                                                                                                          |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 同期バリデーター     | コントロールインスタンスを受け取り、検証エラーのセットまたは`null`をすぐに返す同期関数。`FormControl`をインスタンス化する際に、第2引数として渡します。                                        |
| 非同期バリデーター   | コントロールインスタンスを受け取り、後で検証エラーのセットまたは`null`を発行するPromiseまたはObservableを返す非同期関数。`FormControl`をインスタンス化する際に、第3引数として渡します。 |

パフォーマンス上の理由から、Angularは、すべての同期バリデーターが合格した場合にのみ非同期バリデーターを実行します。
各バリデーターは、エラーが設定される前に完了する必要があります。

### 組み込みのバリデーター関数 {#built-in-validator-functions}

[独自のバリデーター関数](#defining-custom-validators)を作成したり、Angularの組み込みのバリデーターのいくつかを使用したりできます。

`required`や`minlength`など、テンプレート駆動フォームで属性として使用できるものと同じ組み込みバリデーターはすべて、`Validators`クラスから関数として使用できます。
組み込みのバリデーターの完全なリストについては、[Validators](api/forms/Validators) APIリファレンスを参照してください。

アクターフォームをリアクティブフォームに更新するには、いくつかの組み込みバリデーターを使用します。
今回は、関数形式で、次の例のようにします。

<docs-code header="actor-form-reactive.component.ts (validator functions)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" region="form-group"/>

この例では、`name`コントロールは、2つの組み込みバリデーター(`Validators.required`と`Validators.minLength(4)`)と、1つのカスタムバリデーター`forbiddenNameValidator`を設定しています。

これらすべてのバリデーターは同期であるため、第2引数として渡されます。
関数を配列として渡すことで、複数のバリデーターをサポートできることに注意してください。

この例では、いくつかのゲッターメソッドも追加されています。
リアクティブフォームでは、常に親グループの`get`メソッドを通じて任意のフォームコントロールにアクセスできますが、テンプレートの省略形としてゲッターを定義することが便利な場合があります。

`name`入力のテンプレートをもう一度見ると、テンプレート駆動の例とかなり似ています。

<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"/>

このフォームは、テンプレート駆動バージョンとは、ディレクティブをエクスポートしなくなった点が異なります。代わりに、コンポーネントクラスで定義された`name`ゲッターを使用します。

`required`属性は、テンプレートにまだ存在することに注意してください。検証には必要ありませんが、アクセシビリティの目的で保持する必要があります。

## カスタムバリデーターの定義 {#defining-custom-validators}

組み込みのバリデーターは、アプリケーションのユースケースに常に一致するわけではありません。そのため、カスタムバリデーターを作成する必要がある場合があります。

前の例の`forbiddenNameValidator`関数を考えてみてください。
その関数の定義は次のようになります。

<docs-code header="forbidden-name.directive.ts (forbiddenNameValidator)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="custom-validator"/>

関数は、_特定の_禁止されている名前を検出するための正規表現を受け取り、バリデーター関数を返すファクトリです。

このサンプルでは、禁止されている名前は「bob」なので、バリデーターは「bob」を含むアクター名をすべて拒否します。
他の場所では、「alice」や、構成された正規表現に一致する名前を拒否できます。

`forbiddenNameValidator`ファクトリは、構成されたバリデーター関数を返します。
その関数はAngularコントロールオブジェクトを受け取り、コントロール値が有効な場合は`null`を返し、_無効な場合は_検証エラーオブジェクトを返します。
検証エラーオブジェクトには通常、検証キーの名前である`'forbiddenName'`というプロパティと、エラーメッセージに挿入できる任意の値の辞書である`{name}`という値を持つプロパティがあります。

カスタム非同期バリデーターは同期バリデーターに似ていますが、代わりに後で`null`または検証エラーオブジェクトを発行するPromiseまたはObservableを返す必要があります。
Observableの場合、Observableは完了する必要があります。その時点で、フォームは最後の発行された値を検証に使用します。

### カスタムバリデーターをリアクティブフォームに追加する {#adding-custom-validators-to-reactive-forms}

リアクティブフォームでは、`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"/>

### カスタムバリデーターをテンプレート駆動フォームに追加する {#adding-custom-validators-to-template-driven-forms}

テンプレート駆動フォームでは、テンプレートにディレクティブを追加します。ディレクティブは、バリデーター関数をラップします。
たとえば、対応する`ForbiddenValidatorDirective`は、`forbiddenNameValidator`のラッパーとして機能します。

Angularは、ディレクティブが`NG_VALIDATORS`プロバイダーに自身を登録するため、ディレクティブの検証プロセスにおける役割を認識します。次の例に示すように。
`NG_VALIDATORS`は、拡張可能なバリデーターのコレクションを持つ、定義済みのプロバイダーです。

<docs-code header="forbidden-name.directive.ts (providers)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="directive-providers"/>

その後、ディレクティブクラスは`Validator`インターフェースを実装するため、Angularフォームと簡単に統合できます。
以下は、ディレクティブ全体の概要です。

<docs-code header="forbidden-name.directive.ts (directive)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="directive"/>

`ForbiddenValidatorDirective`の準備ができたら、セレクター`appForbiddenName`を入力要素に追加して、アクティブ化できます。
たとえば、次のとおりです。

<docs-code header="actor-form-template.component.html (forbidden-name-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="name-input"/>

HELPFUL: カスタム検証ディレクティブが`useExisting`ではなく`useClass`でインスタンス化されていることに注意してください。
登録されたバリデーターは、`ForbiddenValidatorDirective`の_このインスタンス_である必要があります。フォーム内のインスタンスで、`forbiddenName`プロパティが「bob」にバインドされています。

`useExisting`を`useClass`に置き換えると、`forbiddenName`を持たない新しいクラスインスタンスを登録することになります。

## コントロールステータスCSSクラス {#control-status-css-classes}

Angularは、多くのコントロールプロパティをフォームコントロール要素にCSSクラスとして自動的にミラーリングします。
これらのクラスを使用して、フォームの状態に応じてフォームコントロール要素のスタイルを設定します。
現在サポートされているクラスは次のとおりです。

- `.ng-valid`
- `.ng-invalid`
- `.ng-pending`
- `.ng-pristine`
- `.ng-dirty`
- `.ng-untouched`
- `.ng-touched`
- `.ng-submitted` $囲んでいるフォーム要素のみ$

次の例では、アクターフォームは`.ng-valid`と`.ng-invalid`クラスを使用して、
各フォームコントロールの境界線の色を設定しています。

<docs-code header="forms.css (status classes)" path="adev/src/content/examples/form-validation/src/assets/forms.css"/>

## クロスフィールド検証 {#cross-field-validation}

クロスフィールドバリデーターは、フォーム内の異なるフィールドの値を比較し、組み合わせで受け入れるか拒否する[カスタムバリデーター](#defining-custom-validators 'カスタムバリデーターについて読む')です。
たとえば、互いに非互換なオプションを提供するフォームがある場合、ユーザーはAまたはBを選択できますが、両方は選択できません。
フィールドの値によっては、他の値に依存する場合もあります。ユーザーは、Aを選択した場合にのみBを選択できます。

次のクロス検証の例は、次の方法を示しています。

- 2つの兄弟コントロールの値に基づいて、リアクティブまたはテンプレートベースのフォーム入力を検証する
- ユーザーがフォームとやり取りし、検証に失敗した場合に、説明的なエラーメッセージを表示する

これらの例では、クロス検証を使用して、アクターがアクターフォームに記入することで、役割で同じ名前を再利用しないようにしています。
バリデーターは、アクター名と役割が一致しないことを確認することで、これを実現します。

### クロス検証をリアクティブフォームに追加する {#adding-cross-validation-to-reactive-forms}

フォームは、次の構造になっています。

```ts
const actorForm = new FormGroup({
  'name': new FormControl(),
  'role': new FormControl(),
  'skill': new FormControl(),
});
```

`name`と`role`は兄弟コントロールであることに注意してください。
1つのカスタムバリデーターで両方のコントロールを評価するには、共通の祖先コントロールである`FormGroup`で検証する必要があります。
子コントロールを取得するために`FormGroup`をクエリして、値を比較します。

`FormGroup`にバリデーターを追加するには、作成時に第2引数として新しいバリデーターを渡します。

```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-template.component.html" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" region="cross-validation-error-message"/>

この`@if`は、`FormGroup`に`unambiguousRoleValidator`バリデーターが返したクロス検証エラーがある場合に、エラーを表示しますが、ユーザーが[フォームとやり取りを完了](#control-status-css-classes)した場合のみです。

### クロス検証をテンプレート駆動フォームに追加する {#adding-cross-validation-to-template-driven-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-register-validator"/>

より良いユーザー体験を提供するために、フォームが無効な場合、適切なエラーメッセージが表示されます。

<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"/>

これは、テンプレート駆動フォームとリアクティブフォームの両方で同じです。

## 非同期バリデーターの作成 {#creating-asynchronous-validators}

非同期バリデーターは、`AsyncValidatorFn`と`AsyncValidator`インターフェースを実装します。
これらは、同期バリデーターと非常に似ており、次の点が異なります。

- `validate()`関数はPromiseまたはObservableを返す必要があります。
- 返されるObservableは有限である必要があります。つまり、ある時点で完了する必要があります。
  無限のObservableを有限のObservableに変換するには、Observableを`first`、`last`、`take`、`takeUntil`などのフィルタリング演算子でパイプします。

非同期検証は、同期検証の後に実行され、同期検証が成功した場合にのみ実行されます。
このチェックにより、フォームは、基本的な検証方法がすでに無効な入力を検出している場合、潜在的にコストのかかる非同期検証プロセス（HTTPリクエストなど）を回避できます。

非同期検証が開始されると、フォームコントロールは`pending`状態になります。
コントロールの`pending`プロパティを調べ、それを利用して、進行中の検証操作に関する視覚的なフィードバックを提供します。

一般的なUIパターンは、非同期検証の実行中にスピナーを表示することです。
次の例は、テンプレート駆動フォームでこれを実現する方法を示しています。

```html
<input [(ngModel)]="name" #model="ngModel" appSomeAsyncValidator>

@if(model.pending) {
  <app-spinner />
}
```

### カスタム非同期バリデーターの実装 {#implementing-a-custom-async-validator}

次の例では、非同期バリデーターは、アクターがすでに割り当てられている役割にキャストされないようにします。
新しいアクターは常にオーディションを受けており、古いアクターは引退しているため、利用可能な役割のリストを事前に取得はできません。
潜在的な役割のエントリを検証するために、バリデーターは、現在キャストされているすべてのアクターの中央データベースを照会する非同期操作を開始する必要があります。

次のコードは、`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`インターフェースに対してのみコードを作成できます。

検証が始まると、`UnambiguousRoleValidator`は、現在のコントロール値で`ActorsService`の`isRoleTaken()`メソッドに委任します。
この時点で、コントロールは`pending`としてマークされ、`validate()`メソッドから返されるObservableチェーンが完了するまで、この状態を維持します。

`isRoleTaken()`メソッドは、役割が利用可能かどうかを確認するHTTPリクエストをディスパッチし、結果として`Observable<boolean>`を返します。
`validate()`メソッドは、応答を`map`演算子でパイプし、検証結果に変換します。

その後、メソッドは、他のバリデーターと同様に、フォームが有効な場合は`null`を返し、無効な場合は`ValidationErrors`を返します。
このバリデーターは、`catchError`演算子を使用して、潜在的なエラーを処理します。
この場合、バリデーターは`isRoleTaken()`エラーを正常な検証として扱います。検証リクエストの実行に失敗したとしても、役割が無効であるとは限りません。
エラーを異なる方法で処理し、代わりに`ValidationError`オブジェクトを返すこともできます。

しばらくすると、Observableチェーンが完了し、非同期検証が完了します。
`pending`フラグは`false`に設定され、フォームの有効性が更新されます。

### 非同期バリデーターをリアクティブフォームに追加する {#adding-async-validators-to-reactive-forms}

リアクティブフォームで非同期バリデーターを使用するには、最初にバリデーターをコンポーネントクラスのプロパティに注入します。

<docs-code header="actor-form-reactive.component.2.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-inject"/>

次に、バリデーター関数を`FormControl`に直接渡して、適用します。

次の例では、`UnambiguousRoleValidator`の`validate`関数が、`roleControl`に適用されています。この関数をコントロールの`asyncValidators`オプションに渡し、`ActorFormReactiveComponent`に注入された`UnambiguousRoleValidator`のインスタンスにバインドしています。
`asyncValidators`の値は、単一の非同期バリデーター関数、または関数の配列にできます。
`FormControl`オプションの詳細については、[AbstractControlOptions](api/forms/AbstractControlOptions) APIリファレンスを参照してください。

<docs-code header="actor-form-reactive.component.2.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-usage"/>

### 非同期バリデーターをテンプレート駆動フォームに追加する {#adding-async-validators-to-template-driven-forms}

テンプレート駆動フォームで非同期バリデーターを使用するには、新しいディレクティブを作成し、そのディレクティブに`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"/>

その後、同期バリデーターと同様に、ディレクティブのセレクターを入力に追加して、アクティブ化します。

<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"/>

### 非同期バリデーターのパフォーマンスの最適化 {#optimizing-performance-of-async-validators}

デフォルトでは、すべてのバリデーターは、フォームの値が変更されるたびに実行されます。
同期バリデーターの場合、これは通常、アプリケーションのパフォーマンスに目立った影響を与えません。
ただし、非同期バリデーターは通常、コントロールを検証するために何らかのHTTPリクエストを実行します。
キーストロークごとにHTTPリクエストをディスパッチすると、バックエンドAPIに負担がかかる可能性があり、可能な限り回避する必要があります。

`updateOn`プロパティを`change`（デフォルト）から`submit`または`blur`に変更することで、フォームの有効性の更新を遅らせることができます。

テンプレート駆動フォームでは、テンプレートでプロパティを設定します。

```html
<input [(ngModel)]="name" [ngModelOptions]="{updateOn: 'blur'}">
```

リアクティブフォームでは、`FormControl`インスタンスでプロパティを設定します。

```ts
new FormControl('', {updateOn: 'blur'});
```

## ネイティブHTMLフォーム検証との相互作用 {#interaction-with-native-html-form-validation}

デフォルトでは、Angularは囲んでいる`<form>`に`novalidate`属性を追加することで[ネイティブHTMLフォーム検証](https://developer.mozilla.org/docs/Web/Guide/HTML/Constraint_validation)を無効にし、これらの属性をフレームワーク内のバリデーター関数と一致させるためにディレクティブを使用します。
ネイティブ検証を**組み合わせて**Angularベースの検証を使用したい場合は、`ngNativeValidate`ディレクティブを使用して、ネイティブ検証を再び有効にできます。
詳細については、[APIドキュメント](api/forms/NgForm#native-dom-validation-ui)を参照してください。
# 動的フォームの作成

アンケートなどの多くのフォームは、フォーマットと意図において非常に類似している場合があります。
このようなフォームの異なるバージョンをより速く簡単に生成できるように、ビジネスオブジェクトモデルを記述するメタデータに基づいて、_動的フォームテンプレート_を作成できます。
その後、テンプレートを使用して、データモデルの変更に応じて、新しいフォームを自動的に生成します。

このテクニックは、ビジネスや規制要件の急速な変化に対応するために、コンテンツを頻繁に変更する必要があるフォームの種類を持つ場合に特に役立ちます。
一般的なユースケースはアンケートです。
さまざまなコンテキストでユーザーからの入力を受け取る必要がある場合があります。
ユーザーが見ているフォームのフォーマットとスタイルは一定に保つ必要がありますが、実際に尋ねる必要がある質問はコンテキストによって異なります。

このチュートリアルでは、基本的なアンケートを表示する動的フォームを作成します。
雇用を求めるヒーローのためのオンラインアプリケーションを構築します。
エージェンシーは常にアプリケーションプロセスをいじっていますが、
動的フォームを使用することでアプリケーションコードを変更せずに新しいフォームをオンザフライで作成できます。

このチュートリアルでは、次の手順について説明します。

1. プロジェクトでリアクティブフォームを有効にする。
1. フォームコントロールを表すデータモデルを確立する。
1. サンプルデータでモデルを埋める。
1. フォームコントロールを動的に作成するコンポーネントを開発する。

作成するフォームでは、入力検証とスタイリングを使用してユーザー体験を向上させます。
すべてのユーザー入力が有効な場合にのみ有効になる送信ボタンがあり、無効な入力を色分けとエラーメッセージでフラグ付けします。

この基本バージョンは、より多くの種類の質問、より洗練されたレンダリング、優れたユーザー体験をサポートするように進化させることができます。

## プロジェクトでリアクティブフォームを有効にする {#enable-reactive-forms-for-your-project}

動的フォームはリアクティブフォームに基づいています。

アプリケーションにリアクティブフォームディレクティブへのアクセス権を与えるには、必要なコンポーネントに `@angular/forms` ライブラリから `ReactiveFormsModule` をインポートします。
## フォームオブジェクトモデルを作成する {#create-a-form-object-model}

動的フォームには、フォーム機能に必要なすべてのシナリオを記述できるオブジェクトモデルが必要です。
例のヒーローアプリケーションフォームは、一連の質問です。つまり、フォーム内の各コントロールは質問をし、回答を受け入れる必要があります。

このタイプのフォームのデータモデルは、質問を表す必要があります。
例には、`DynamicFormQuestionComponent` が含まれており、質問をモデルの基本オブジェクトとして定義しています。

次の `QuestionBase` は、フォーム内の質問とその回答を表すことができる一連のコントロールのベースクラスです。

<docs-code header="question-base.ts" path="adev/src/content/examples/dynamic-form/src/app/question-base.ts"/>

### コントロールクラスを定義する {#define-control-classes}

このベースから、例では、異なるコントロールタイプを表す `TextboxQuestion` と `DropdownQuestion` の2つの新しいクラスを派生させます。
次のステップでフォームテンプレートを作成するときは、適切なコントロールを動的にレンダリングするために、これらの特定の質問タイプをインスタンス化します。

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

### フォームグループを構成する {#compose-form-groups}

動的フォームは、サービスを使用して、質問モデルのメタデータに基づいて、入力コントロールのグループ化されたセットを作成します。
次の `QuestionControlService` は、質問モデルからメタデータを使用する `FormGroup` インスタンスのセットを収集します。
デフォルト値と検証ルールを指定できます。

<docs-code header="question-control.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question-control.service.ts"/>

## 動的フォームコンテンツを構成する {#compose-dynamic-form-contents}

動的フォーム自体は、後で追加するコンテナーコンポーネントで表されます。
各質問は、フォームコンポーネントのテンプレートで、`DynamicFormQuestionComponent` のインスタンスと一致する `<app-question>` タグで表されます。

`DynamicFormQuestionComponent` は、データバインドされた質問オブジェクトの値に基づいて、個々の質問の詳細をレンダリングする責任があります。
フォームは、[`[formGroup]` ディレクティブ](api/forms/FormGroupDirective 'API リファレンス') に依存して、テンプレートHTMLを基礎となるコントロールオブジェクトに接続します。
`DynamicFormQuestionComponent` は、フォームグループを作成し、質問モデルにより定義されたコントロールでそれらを埋め、表示と検証ルールを指定します。
`DynamicFormQuestionComponent` の目標は、モデルで定義された質問タイプを提示することです。
現時点では質問タイプが2つしかありませんが、さらに多くのタイプが考えられます。
テンプレートの `@switch` ブロックは、表示する質問タイプを決定します。
スイッチは、[`formControlName`](api/forms/FormControlName 'FormControlName ディレクティブ API リファレンス') と [`formGroup`](api/forms/FormGroupDirective 'FormGroupDirective API リファレンス') セレクターを持つディレクティブを使用します。
両方のディレクティブは `ReactiveFormsModule` で定義されています。

### データを供給する {#supply-data}

個々のフォームを構築するために、特定の質問セットを供給するサービスも必要です。
この演習では、ハードコードされたサンプルデータからこの質問の配列を供給する `QuestionService` を作成します。
実際のアプリケーションでは、サービスはバックエンドシステムからデータを取得する可能性があります。
ただし、重要な点は、ヒーローの求人質問を `QuestionService` から返されるオブジェクトを通じて完全に制御できることです。
要件が変更された場合にアンケートを維持するには、`questions` 配列からオブジェクトを追加、更新、削除するだけです。

`QuestionService` は、`input()` questionsにバインドされた配列の形式で、質問セットを供給します。

<docs-code header="question.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question.service.ts"/>

## 動的フォームテンプレートを作成する {#create-a-dynamic-form-template}

`DynamicFormComponent` コンポーネントは、テンプレートで `<app-dynamic-form>` を使用して表されるフォームのエントリポイントであり、メインコンテナーです。

`DynamicFormComponent` コンポーネントは、各質問を、`DynamicFormQuestionComponent` と一致する `<app-question>` 要素にバインドすることによって、質問のリストを表示します。
### フォームを表示する {#display-the-form}

動的フォームのインスタンスを表示するには、`AppComponent` シェルテンプレートは、`QuestionService` から返された `questions` 配列を、フォームコンテナーコンポーネント `<app-dynamic-form>` に渡します。

<docs-code header="app.component.ts" path="adev/src/content/examples/dynamic-form/src/app/app.component.ts"/>

このモデルとデータの分離により、_質問_ オブジェクトモデルと互換性がある限り、あらゆるタイプのアンケートにコンポーネントを再利用できます。

### 有効なデータを確保する {#ensuring-valid-data}

フォームテンプレートは、特定の質問についてハードコードされた仮定を一切行わずに、メタデータの動的データバインドを使用してフォームをレンダリングします。
コントロールメタデータと検証基準の両方を動的に追加します。

有効な入力を確保するために、フォームが有効な状態になるまで、_保存_ ボタンは無効になっています。
フォームが有効になったら、_保存_ をクリックすると、アプリケーションは現在のフォーム値をJSONとしてレンダリングします。

次の図は、最終的なフォームを示しています。

## 次のステップ {#next-steps}
Angular Router (`@angular/router`) は、Angularアプリケーションでナビゲーションを管理するための公式ライブラリであり、フレームワークの核となる部分です。Angular CLIによって作成されたすべてのプロジェクトにデフォルトで含まれています。

## SPAでルーティングが必要な理由 {#why-is-routing-necessary-in-a-spa}

WebブラウザでURLに移動すると、ブラウザは通常、Webサーバーにネットワークリクエストを行い、返されたHTMLページを表示します。リンクをクリックするなどの別のURLに移動すると、ブラウザは別のネットワークリクエストを行い、ページ全体を新しいものに置き換えます。

シングルページアプリケーション（SPA）は、ブラウザが最初のページである`index.html`に対してのみWebサーバーにリクエストを行う点で異なります。その後、クライアントサイドルーターが引き継ぎ、URLに基づいて表示するコンテンツを制御します。ユーザーが別のURLに移動すると、ルーターはページ全体のリロードをトリガーすることなく、その場でページコンテンツを更新します。

## Angularがルーティングを管理する方法 {#how-angular-manages-routing}

Angularにおけるルーティングは、主に3つの要素で構成されています。

1.  **ルート**は、ユーザーが特定のURLにアクセスしたときにどのコンポーネントを表示するかを定義します。
2.  **アウトレット**は、アクティブなルートに基づいてコンポーネントを動的にロードおよびレンダリングする、テンプレート内のプレースホルダーです。
3.  **リンク**は、フルページリロードをトリガーすることなく、アプリケーション内の異なるルート間をユーザーが移動するための手段を提供します。

さらに、Angularルーティングライブラリは、次のような追加機能を提供します。

-   ネストされたルート
-   プログラムによるナビゲーション
-   ルートパラメーター、クエリ、ワイルドカード
-   `ActivatedRoute`によるアクティブ化されたルート情報
-   ビュートランジション効果
-   ナビゲーションガード

## 次のステップ {#next-steps}

[Angularルーターを使用してルートを定義する](/guide/routing/define-routes)方法について学びましょう。
# ルートを定義する

ルートは、Angularアプリケーション内のナビゲーションのための基本的な構成要素として機能します。

## ルートとは {#what-are-routes}

Angularでは、**ルート**は特定のURLパスまたはパターンに対してどのコンポーネントをレンダリングするか、およびユーザーがそのURLにナビゲートしたときに何が起こるかに関する追加の構成オプションを定義するオブジェクトです。

次にルートの基本的な例を示します。

```ts
import {AdminPage} from './app-admin/app-admin.component';

const adminPage = {
  path: 'admin',
  component: AdminPage,
};
```

このルートの場合、ユーザーが`/admin`パスにアクセスすると、アプリケーションは`AdminPage`コンポーネントを表示します。

### アプリケーションでルートを管理する {#managing-routes-in-your-application}

ほとんどのプロジェクトでは、ファイル名に`routes`を含む別のファイルでルートを定義します。

ルートのコレクションは次のようになります。

```ts
import {Routes} from '@angular/router';
import {HomePage} from './home-page/home-page.component';
import {AdminPage} from './about-page/admin-page.component';

export const routes: Routes = [
  {
    path: '',
    component: HomePage,
  },
  {
    path: 'admin',
    component: AdminPage,
  },
];
```

Tip: Angular CLIでプロジェクトを生成した場合、ルートは`src/app/app.routes.ts`で定義されます。

### アプリケーションにルーターを追加する {#adding-the-router-to-your-application}

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パス {#route-url-paths}

### 静的なURLパス {#static-url-paths}

静的なURLパスとは、動的なパラメーターに基づいて変化しない、事前に定義されたパスを持つルートを指します。これらは`path`文字列に正確に一致し、固定された結果を持つルートです。

例としては次のものがあります。

- "/admin"
- "/blog"
- "/settings/account"

### ルートパラメーターでURLパスを定義する {#define-url-paths-with-route-parameters}

パラメーター化されたURLを使用すると、複数のURLを同じコンポーネントに許可しながら、URL内のパラメーターに基づいてデータを動的に表示する動的なパスを定義できます。

このタイプのパターンは、ルートの`path`文字列にパラメーターを追加し、各パラメーターの前にコロン(`:`)文字を付けることで定義できます。

IMPORTANT: パラメーターは、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/user-profile.component';
import {SocialMediaFeed} from './user-profile/social–media-feed.component';

const routes: Routes = [
  {path: 'user/:id/:social-media', component: SocialMediaFeed},
  {path: 'user/:id/', component: UserProfile},
];
```

この新しいパスにより、ユーザーは`/user/leeroy/youtube`や`/user/leeroy/bluesky`にアクセスし、ユーザーleeroyのパラメーターに基づいてそれぞれのソーシャルメディアフィードを見ることができます。

ルートパラメーターの読み取りの詳細については、[ルート状態の読み取り](/guide/routing/read-route-state)を参照してください。

### ワイルドカード {#wildcards}

特定のパスのすべてのルートをキャッチする必要がある場合、解決策は二重アスタリスク(`**`)で定義されるワイルドカードルートです。

一般的な例は、ページが見つかりませんコンポーネントの定義です。

```ts
import {Home} from './home/home.component';
import {UserProfile} from './user-profile/user-profile.component';
import {NotFound} from './not-found/not-found.component';

const routes: Routes = [
  {path: 'home', component: Home},
  {path: 'user/:id', component: UserProfile},
  {path: '**', component: NotFound},
];
```

このルート配列では、ユーザーが`home`と`user/:id`以外のパスにアクセスすると、アプリケーションは`NotFound`コンポーネントを表示します。

Tip: ワイルドカードルートは通常、ルート配列の最後に配置されます。

## AngularがURLを照合する方法 {#how-angular-matches-urls}

ルートを定義する際、Angularは最初の一致が優先される戦略を使用するため、順序が重要です。これは、AngularがURLをルート`path`と照合すると、それ以上ルートの確認を停止することを意味します。結果として、常に、より具体的なルートを、より具体的でないルートの前に配置してください。

次の例は、最も具体的なものから最も具体的でないものへと定義されたルートを示しています。

```ts
const routes: Routes = [
  {path: '', component: HomeComponent}, // 空のパス
  {path: 'users/new', component: NewUserComponent}, // 静的、最も具体的
  {path: 'users/:id', component: UserDetailComponent}, // 動的
  {path: 'users', component: UsersComponent}, // 静的、具体的でない
  {path: '**', component: NotFoundComponent}, // ワイルドカード - 常に最後
];
```

ユーザーが`/users/new`にアクセスした場合、Angularルーターは次の手順を実行します。

1. `''`をチェック - 一致しません
1. `users/new`をチェック - 一致します！ここで停止します
1. 一致する可能性があるにもかかわらず、`users/:id`には到達しません
1. `users`には到達しません
1. `**`には到達しません

## ルートの読み込み戦略 {#route-loading-strategies}

Angularルーティングでルートとコンポーネントがどのように、いつ読み込まれるかを理解することは、応答性の高いWebアプリケーションを構築するために不可欠です。Angularは、読み込み動作を制御するための2つの主要な戦略を提供します。

1. **即時読み込み (Eagerly loaded)**: すぐに読み込まれるルートとコンポーネント
2. **遅延読み込み (Lazily loaded)**: 必要になったときにのみ読み込まれるルートとコンポーネント

それぞれのアプローチは、異なるシナリオに対して明確な利点を提供します。

### 即時読み込みされるコンポーネント {#eagerly-loaded-components}

`component`プロパティでルートを定義すると、参照されるコンポーネントは、ルート構成と同じJavaScriptバンドルの一部として即時読み込みされます。

```ts
import {Routes} from '@angular/router';
import {HomePage} from './components/home/home-page';
import {LoginPage} from './components/auth/login-page';

export const routes: Routes = [
  // HomePageとLoginPageはどちらもこの設定で直接参照されているため、
  // そのコードはこのファイルと同じJavaScriptバンドルに即時含まれます。
  {
    path: '',
    component: HomePage,
  },
  {
    path: 'login',
    component: LoginPage,
  },
];
```

このようにルートコンポーネントを即時読み込みすることは、ブラウザが初期ページ読み込みの一部としてこれらのコンポーネントのすべてのJavaScriptをダウンロードして解析する必要があることを意味しますが、コンポーネントはAngularですぐに利用できます。

初期ページ読み込みに多くのJavaScriptを含めると初期読み込み時間は遅くなりますが、ユーザーがアプリケーション内を移動する際のよりシームレスな遷移につながる可能性があります。

### 遅延読み込みされるコンポーネントとルート {#lazily-loaded-components-and-routes}

`loadComponent`プロパティを使用すると、そのルートがアクティブになる時点でのみ、コンポーネントのJavaScriptを遅延読み込みできます。`loadChildren`プロパティは、ルートマッチング時に子ルートを遅延読み込みします。

```ts
import {Routes} from '@angular/router';

export const routes: Routes = [
  {
    path: 'login',
    loadComponent: () => import('./components/auth/login-page'),
  },
  {
    path: 'admin',
    loadComponent: () => import('./admin/admin.component'),
    loadChildren: () => import('./admin/admin.routes'),
  },
];
```

`loadComponent`と`loadChildren`プロパティは、それぞれAngularコンポーネントまたはルートのセットに解決されるPromiseを返すローダー関数を受け入れます。ほとんどの場合、この関数は標準の[JavaScript動的インポートAPI](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)を使用します。ただし、任意の非同期ローダー関数も使用できます。

遅延読み込みされるファイルが`default`エクスポートを使用している場合、エクスポートされたクラスを選択するための追加の`.then`呼び出しなしで、`import()`Promiseを直接返すことができます。

遅延読み込みルートは、初期バンドルからJavaScriptの大部分を削除することで、Angularアプリケーションの読み込み速度を大幅に向上させることができます。これらのコード部分は、ユーザーが対応するルートにアクセスしたときにのみルーターが要求する個別のJavaScript「チャンク」にコンパイルされます。

### 注入コンテキストでの遅延読み込み {#injection-context-lazy-loading}

ルーターは`loadComponent`と`loadChildren`を**現在のルートの注入コンテキスト**内で実行します。これにより、これらのローダー関数内で[`inject`](/api/core/inject)を呼び出して、そのルートで宣言されたプロバイダー、階層的な依存性の注入を介して親ルートから継承されたプロバイダー、またはグローバルに利用可能なプロバイダーにアクセスできます。これにより、コンテキストを認識した遅延読み込みが可能になります。

```ts
import {Routes} from '@angular/router';
import {inject} from '@angular/core';
import {FeatureFlags} from './feature-flags';

export const routes: Routes = [
  {
    path: 'dashboard',
    // ルートのインジェクションコンテキスト内で実行されます
    loadComponent: () => {
      const flags = inject(FeatureFlags);
      return flags.isPremium
        ? import('./dashboard/premium-dashboard')
        : import('./dashboard/basic-dashboard');
    },
  },
];
```

### 即時ルートと遅延ルートのどちらを使用すべきか {#should-i-use-an-eager-or-a-lazy-route}

ルートが即時読み込みか遅延読み込みかを決定する際には、多くの要素を考慮する必要があります。

一般的に、プライマリランディングページには即時読み込みが推奨され、他のページは遅延読み込みされます。

NOTE: 遅延ルートは、ユーザーが要求する初期データの量を減らすという先行的なパフォーマンス上の利点がありますが、望ましくない可能性のある将来のデータ要求を追加します。これは、複数のレベルでのネストされた遅延読み込みを扱う場合に特に当てはまり、パフォーマンスに大きな影響を与える可能性があります。

## リダイレクト {#redirects}

コンポーネントをレンダリングする代わりに、別のルートにリダイレクトするルートを定義できます。

```ts
import {BlogComponent} from './home/blog.component';

const routes: Routes = [
  {
    path: 'articles',
    redirectTo: '/blog',
  },
  {
    path: 'blog',
    component: BlogComponent,
  },
];
```

ルートを変更または削除した場合でも、一部のユーザーは古いリンクやブックマークをクリックしてそのルートにアクセスする可能性があります。そのようなユーザーを「見つかりません」ページではなく、適切な代替ルートに誘導するためにリダイレクトを追加できます。

## ページタイトル {#page-titles}

各ルートには**タイトル**を関連付けることができます。ルートがアクティブになると、Angularは[ページタイトル](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title)を自動的に更新します。アクセシブルな体験を作成するためにこれらのタイトルが必要となるため、アプリケーションに適切なページタイトルを常に定義してください。

```ts
import {Routes} from '@angular/router';
import {HomeComponent} from './home/home.component';
import {AboutComponent} from './about/about.component';

const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    title: 'Home Page',
  },
  {
    path: 'about',
    component: AboutComponent,
    title: 'About Us',
  },
];
```

ページの `title` プロパティは、[`ResolveFn`](/api/router/ResolveFn)を使用してリゾルバー関数に動的に設定できます。

```ts
const titleResolver: ResolveFn<string> = (route) => route.queryParams['id'];
const routes: Routes = [
  ...{
    path: 'products',
    component: ProductsComponent,
    title: titleResolver,
  },
];
```

ルートタイトルは、[`TitleStrategy`](/api/router/TitleStrategy) 抽象クラスを継承するサービスを介しても設定できます。デフォルトでは、Angularは[`DefaultTitleStrategy`](/api/router/DefaultTitleStrategy)を使用します。

### ページタイトルのためのTitleStrategyの使用 {#using-titlestrategy-for-page-titles}

ドキュメントタイトルの構成方法を一元的に制御する必要がある高度なシナリオでは、`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 {
    // PageTitleは、ルートの"Title"が設定されている場合はそれと等しくなります
    // 設定されていない場合は、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}],
};
```

## 依存性の注入のためのルートレベルプロバイダー {#route-level-providers-for-dependency-injection}

各ルートには、[依存性の注入](/guide/di)を介してそのルートのコンテンツに依存性を提供する`providers`プロパティがあります。

これが役立つ一般的なシナリオには、ユーザーが管理者であるかどうかに基づいて異なるサービスを持つアプリケーションが含まれます。

```ts
export const ROUTES: Route[] = [
  {
    path: 'admin',
    providers: [AdminService, {provide: ADMIN_API_KEY, useValue: '12345'}],
    children: [
      {path: 'users', component: AdminUsersComponent},
      {path: 'teams', component: AdminTeamsComponent},
    ],
  },
  // ... other application routes that don't
  //     have access to ADMIN_API_KEY or AdminService.
];
```

このコードサンプルでは、`admin`パスには`ADMIN_API_KEY`という保護されたデータプロパティが含まれており、そのセクション内の子にのみ利用できます。結果として、他のパスは`ADMIN_API_KEY`を介して提供されるデータにアクセスできません。

Angularのプロバイダーと注入に関する詳細については、[依存性の注入ガイド](/guide/di)を参照してください。

## ルートにデータを関連付ける {#associating-data-with-routes}

ルートデータを使用すると、ルートに追加情報を付加できます。このデータに基づいてコンポーネントの動作を設定できます。

ルートデータを扱う方法は2つあります。定数として保持される静的データと、実行時の条件に基づいて変化する動的データです。

### 静的データ {#static-data}

`data`プロパティを介して任意の静的データをルートに関連付けることで、ルート固有のメタデータ（例: 分析トラッキング、権限など）を一元化できます。

```ts
import {Routes} from '@angular/router';
import {HomeComponent} from './home/home.component';
import {AboutComponent} from './about/about.component';
import {ProductsComponent} from './products/products.component';

const routes: Routes = [
  {
    path: 'about',
    component: AboutComponent,
    data: {analyticsId: '456'},
  },
  {
    path: '',
    component: HomeComponent,
    data: {analyticsId: '123'},
  },
];
```

このコードサンプルでは、ホームページとアバウトページが特定の`analyticsId`で構成されており、それぞれのコンポーネントでページトラッキング分析に使用されます。

この静的データは`ActivatedRoute`を注入することで読み取ることができます。詳細については、[ルート状態の読み取り](/guide/routing/read-route-state)を参照してください。

### データリゾルバーによる動的データ {#dynamic-data-with-data-resolvers}

ルートに動的データを提供する必要がある場合は、[ルートデータリゾルバーに関するガイド](/guide/routing/data-resolvers)を参照してください。

## ネストされたルート {#nested-routes}

ネストされたルートは、子ルートとも呼ばれ、URLに基づいてサブビューが変化する、より複雑なナビゲーションルートを管理するための一般的な手法です。

`children`プロパティを使用して、任意のルート定義に子ルートを追加できます。

```ts
const routes: Routes = [
  {
    path: 'product/:id',
    component: ProductComponent,
    children: [
      {
        path: 'info',
        component: ProductInfoComponent,
      },
      {
        path: 'reviews',
        component: ProductReviewsComponent,
      },
    ],
  },
];
```

上記の例では、ユーザーがURLに基づいて製品情報またはレビューのどちらを表示するかを変更できる製品ページのルートを定義しています。

`children`プロパティは`Route`オブジェクトの配列を受け入れます。

子ルートを表示するには、親コンポーネント（上記の例では`ProductComponent`）に独自の`<router-outlet>`を含めます。

```html

<article>
  <h1>Product {{ id }}</h1>
  <router-outlet />
</article>
```

設定に子ルートを追加し、コンポーネントに`<router-outlet>`を追加すると、子ルートに一致するURL間のナビゲーションは、ネストされたアウトレットのみを更新します。

## 次のステップ {#next-steps}

[アウトレットでルートのコンテンツを表示する方法](/guide/routing/show-routes-with-outlets)を学びましょう。

# アウトレットにルートを表示する

`RouterOutlet`ディレクティブは、ルーターが現在のURLに対応するコンポーネントをレンダリングする場所を示すプレースホルダーです。

```html
<app-header />
<router-outlet />  
<app-footer />
```

```ts
import {Component} from '@angular/core';
import {RouterOutlet} from '@angular/router';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css',
})
export class AppComponent {}
```

この例では、アプリケーションに次のルートが定義されている場合:

```ts
import {Routes} from '@angular/router';
import {HomeComponent} from './home/home.component';
import {ProductsComponent} from './products/products.component';

const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    title: 'Home Page',
  },
  {
    path: 'products',
    component: ProductsComponent,
    title: 'Our Products',
  },
];
```

ユーザーが`/products`にアクセスすると、Angularは次のようにレンダリングします。

```html
<app-header />
<app-products />
<app-footer />
```

ユーザーがホームページに戻ると、Angularは次のようにレンダリングします。

```html
<app-header />
<app-home />
<app-footer />
```

ルートを表示するとき、`<router-outlet>`要素は将来のナビゲーションのための参照点としてDOMに存在し続けます。Angularはルーティングされたコンテンツをアウトレット要素の直後に兄弟要素として挿入します。

```html

<app-header />
<router-outlet />
<app-footer />
```

```html

<app-header />
<router-outlet />
<app-admin-page />
<app-footer />
```

## 子ルートでルートをネストする {#nesting-routes-with-child-routes}

アプリケーションが複雑になるにつれて、ルートコンポーネント以外のコンポーネントに相対的なルートを作成したい場合があります。これにより、URLが変更されたときにアプリケーションの一部のみが変更されるような体験を作成でき、ユーザーがページ全体がリフレッシュされたように感じるのを避けることができます。

これらの種類のネストされたルートは子ルートと呼ばれます。これは、`AppComponent`内の`<router-outlet>`に加えて、アプリケーションに2つ目の`<router-outlet>`を追加することを意味します。

この例では、`Settings`コンポーネントは、ユーザーが選択した内容に基づいて目的のパネルを表示します。子ルートについて気づくユニークな点の1つは、コンポーネントが独自の`<nav>`と`<router-outlet>`を持つことが多いことです。

```html
<h1>Settings</h1>
<nav>
  <ul>
    <li><a routerLink="profile">Profile</a></li>
    <li><a routerLink="security">Security</a></li>
  </ul>
</nav>
<router-outlet />
```

子ルートは他のルートと同様に、`path`と`component`の両方が必要です。唯一の違いは、子ルートを親ルート内の`children`配列に配置することです。

```ts
const routes: Routes = [
  {
    path: 'settings-component',
    component: SettingsComponent, // これはテンプレートに<router-outlet>を持つコンポーネントです
    children: [
      {
        path: 'profile', // 子ルートのパス
        component: ProfileComponent, // ルーターがレンダリングする子ルートコンポーネント
      },
      {
        path: 'security',
        component: SecurityComponent, // ルーターがレンダリングする別の子ルートコンポーネント
      },
    ],
  },
];
```

`routes`と`<router-outlet>`の両方が正しく設定されると、アプリケーションはネストされたルートを使用するようになります！

## 名前付きアウトレットによるセカンダリールート {#secondary-routes-with-named-outlets}

ページには複数のアウトレットがある場合があります。各アウトレットに名前を割り当てて、どのコンテンツがどのアウトレットに属するかを指定できます。

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

## アウトレットのライフサイクルイベント {#outlet-lifecycle-events}

ルーターアウトレットが発行できるライフサイクルイベントは4つあります。

| イベント       | 説明                                           |
| ------------ | ---------------------------------------------- |
| `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}

ルーティングされたコンポーネントにコンテキストデータを渡すには、多くの場合、グローバルステートや複雑なルート設定が必要です。これを簡単にするために、各`RouterOutlet`は`routerOutletData`入力をサポートしています。ルーティングされたコンポーネントとその子コンポーネントは、`ROUTER_OUTLET_DATA`インジェクショントークンを使用してこのデータをシグナルとして読み取ることができ、ルート定義を変更せずにアウトレット固有の設定が可能になります。

```typescript
import {Component} from '@angular/core';
import {RouterOutlet} from '@angular/router';

@Component({
  selector: 'app-dashboard',
  imports: [RouterOutlet],
  template: `
    <h2>Dashboard</h2>
    <router-outlet [routerOutletData]="{ layout: 'sidebar' }" />
  `,
})
export class DashboardComponent {}
```

ルーティングされたコンポーネントは、`ROUTER_OUTLET_DATA`を使用して提供されたアウトレットデータをインジェクトできます。

```typescript
import {Component, inject} from '@angular/core';
import {ROUTER_OUTLET_DATA} from '@angular/router';

@Component({
  selector: 'app-stats',
  template: `<p>Stats view (layout: {{ outletData().layout }})</p>`,
})
export class StatsComponent {
  outletData = inject(ROUTER_OUTLET_DATA) as Signal<{ layout: string }>;
}
```

Angularがそのアウトレット内で`StatsComponent`をアクティブ化すると、インジェクトされたデータとして`{ layout: 'sidebar' }`を受け取ります。

NOTE: `routerOutletData`入力が設定されていない場合、インジェクトされる値はデフォルトでnullです。

---

## 次のステップ {#next-steps}

Angularルーターで[ルートへナビゲーションする](/guide/routing/navigate-to-routes)方法を学びましょう。
# ルートへのナビゲーション

`RouterLink`ディレクティブは、Angularのナビゲーションに対する宣言的なアプローチです。これにより、Angularのルーティングシステムとシームレスに統合される標準のアンカー要素（`<a>`）を使用できます。

## RouterLinkの使い方 {#how-to-use-routerlink}

通常のアンカー要素`<a>`に`href`属性を使用する代わりに、Angularルーティングを活用するために、適切なパスを持つ`RouterLink`ディレクティブを追加します。

```typescript
import {RouterLink} from '@angular/router';

@Component({
  template: `
    <nav>
      <a routerLink="/user-profile">User profile</a>
      <a routerLink="/settings">Settings</a>
    </nav>
  `
  imports: [RouterLink],
  ...
})
export class App {}
```

### 絶対リンクと相対リンクの使用 {#using-absolute-or-relative-links}

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`）が明示的に定義された完全なパスを含んでいます。対照的に、2番目の例は、ユーザーがすでに`/essentials`の正しいルートドメインにいることを前提としています。

一般的に、相対URLは、ルーティング階層内での絶対位置を知る必要がないため、アプリケーション全体で保守しやすいため、推奨されます。

### 相対URLの仕組み {#how-relative-urls-work}

Angularルーティングには、相対URLを定義するための2つの構文があります。文字列と配列です。

```html

<a routerLink="dashboard">Dashboard</a>
<a [routerLink]="['dashboard']">Dashboard</a>
```

HELPFUL: 文字列を渡すのが、相対URLを定義する最も一般的な方法です。

相対URLで動的なパラメーターを定義する必要がある場合は、配列構文を使用します。

```html
<a [routerLink]="['user', currentUserId]">Current User</a>
```

さらに、Angularルーティングでは、相対パスがスラッシュ（`/`）で始まるかどうかによって、パスを現在のURLに対する相対パスにするか、ルートドメインに対する相対パスにするかを指定できます。

たとえば、ユーザーが`example.com/settings`にいる場合、さまざまなシナリオで異なる相対パスを定義する方法を次に示します。

```html

<a routerLink="notifications">Notifications</a>
<a routerLink="/settings/notifications">Notifications</a>

<a routerLink="/team/123/user/456">User 456</a>
<a [routerLink]="['/team', teamId, 'user', userId]">Current User</a>”
```

## ルートへのプログラムによるナビゲーション {#programmatic-navigation-to-routes}

`RouterLink`がテンプレートでの宣言的なナビゲーションを処理する一方で、Angularはロジック、ユーザーアクション、またはアプリケーションの状態に基づいてナビゲートする必要があるシナリオのために、プログラムによるナビゲーションを提供します。`Router`を注入することで、ルートへ動的にナビゲートし、パラメーターを渡し、TypeScriptコードでナビゲーションの動作を制御できます。

### `router.navigate()` {#router-navigate}

`router.navigate()`メソッドを使用して、URLパス配列を指定することで、ルート間をプログラムでナビゲートできます。

```typescript
import { Router } from '@angular/router';

@Component({
  selector: 'app-dashboard',
  template: `
    <button (click)="navigateToProfile()">View Profile</button>
  `
})
export class AppDashboard {
  private router = inject(Router);

navigateToProfile() {
    // Standard navigation
    this.router.navigate(['/profile']);

// With route parameters
    this.router.navigate(['/users', userId]);

// With query parameters
    this.router.navigate(['/search'], {
      queryParams: { category: 'books', sort: 'price' }
    });

// With matrix parameters
    this.router.navigate(['/products', { featured: true, onSale: true }]);
  }
}
```

`router.navigate()`は、シンプルおよび複雑なルーティングシナリオの両方をサポートしており、ルートパラメーター、[クエリパラメーター](/guide/routing/read-route-state#query-parameters)を渡し、ナビゲーションの動作を制御できます。

また、`relativeTo`オプションを使用して、ルーティングツリー内のコンポーネントの場所に対する動的なナビゲーションパスを構築できます。

```typescript
import { Router, ActivatedRoute } from '@angular/router';

@Component({
  selector: 'app-user-detail',
  template: `
    <button (click)="navigateToEdit()">Edit User</button>
    <button (click)="navigateToParent()">Back to List</button>
  `
})
export class UserDetailComponent {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

constructor() {}

// Navigate to a sibling route
  navigateToEdit() {
    // From: /users/123
    // To:   /users/123/edit
    this.router.navigate(['edit'], { relativeTo: this.route });
  }

// Navigate to parent
  navigateToParent() {
    // From: /users/123
    // To:   /users
    this.router.navigate(['..'], { relativeTo: this.route });
  }
}
```

### `router.navigateByUrl()` {#router-navigatebyurl}

`router.navigateByUrl()`メソッドは、配列セグメントではなくURLパス文字列を使用してプログラムでナビゲートする直接的な方法を提供します。このメソッドは、完全なURLパスがあり、絶対ナビゲーションを実行する必要がある場合に最適です。特に、外部から提供されるURLやディープリンクのシナリオで役立ちます。

```ts
// Standard route navigation
router.navigateByUrl('/products');

// Navigate to nested route
router.navigateByUrl('/products/featured');

// Complete URL with parameters and fragment
router.navigateByUrl('/products/123?view=details#reviews');

// Navigate with query parameters
router.navigateByUrl('/search?category=books&sortBy=price');

// With matrix parameters
router.navigateByUrl('/sales-awesome;isOffer=true;showModal=false');
```

履歴内の現在のURLを置き換える必要がある場合、`navigateByUrl`は`replaceUrl`オプションを持つ設定オブジェクトも受け入れます。

```ts
// Replace current URL in history
router.navigateByUrl('/checkout', {
  replaceUrl: true,
});
```

## 次のステップ {#next-steps}

レスポンシブでコンテキストを認識するコンポーネントを作成するために、[ルートの状態を読み取る](/guide/routing/read-route-state)方法を学びましょう。
# ルートの状態を読み取る {#read-route-state}

Angularルーターを使用すると、ルートに関連付けられた情報を読み取り、使用して、応答性が高く、コンテキストを認識するコンポーネントを作成できます。

## ActivatedRouteで現在のルートに関する情報を取得する {#get-information-about-the-current-route-with-activatedroute}

`ActivatedRoute`は、現在のルートに関連付けられたすべての情報を提供する`@angular/router`からのサービスです。

```typescript
import { Component } from '@angular/core';
import { ActivatedRoute } from '@angular/router';

@Component({
  selector: 'app-product',
})
export class ProductComponent {
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    console.log(this.activatedRoute);
  }
}
```

`ActivatedRoute`は、ルートに関するさまざまな情報を提供できます。一般的なプロパティには次のものがあります。

ルート内でアクセスできるものの完全なリストについては、[`ActivatedRoute` APIドキュメント](/api/router/ActivatedRoute)を参照してください。

## ルートスナップショットを理解する {#understanding-route-snapshots}

ページナビゲーションは時間の経過とともに発生するイベントであり、ルートスナップショットを取得することで、特定の時点でのルーターの状態にアクセスできます。

ルートスナップショットには、パラメーター、データ、子ルートなど、ルートに関する本質的な情報が含まれています。さらに、スナップショットは静的であり、将来の変更を反映しません。

ルートスナップショットにアクセスする方法の例を次に示します。

```typescript
import { ActivatedRoute, ActivatedRouteSnapshot } from '@angular/router';

@Component({ ... })
export class UserProfileComponent {
  readonly userId: string;
  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,           // https://www.angular.dev
      // ルートパラメーターオブジェクト: {id: '123'}
      params: snapshot.params,
      // クエリパラメーターオブジェクト: {role: 'admin', status: 'active'}
      queryParams: snapshot.queryParams,  // クエリパラメーター
    });
  }
}
```

アクセスできるすべてのプロパティの完全なリストについては、[`ActivatedRoute` APIドキュメント](/api/router/ActivatedRoute)と[`ActivatedRouteSnapshot` APIドキュメント](/api/router/ActivatedRouteSnapshot)を参照してください。

## ルート上のパラメーターを読み取る {#reading-parameters-on-a-route}

開発者はルートからルートパラメーターとクエリパラメーターの2種類のパラメーターを利用できます。

### ルートパラメーター {#route-parameters}

ルートパラメーターを使用すると、URLを介してコンポーネントにデータを渡すことができます。これは、ユーザーIDや製品IDなど、URL内の識別子に基づいて特定のコンテンツを表示したい場合に役立ちます。

パラメーター名の前にコロン (`:`) を付けることで、[ルートパラメーターを定義](/guide/routing/define-routes#define-url-paths-with-route-parameters)できます。

```typescript
import { Routes } from '@angular/router';
import { ProductComponent } from './product/product.component';

const routes: Routes = [
  { path: 'product/:id', component: ProductComponent }
];
```

`route.params`を購読することでパラメーターにアクセスできます。

```typescript
import { Component, inject, signal } from '@angular/core';
import { ActivatedRoute } from '@angular/router';

@Component({
  selector: 'app-product-detail',
  template: `<h1>Product Details: {{ productId() }}</h1>`,
})
export class ProductDetailComponent {
  productId = signal('');
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    // ルートパラメーターにアクセス
    this.activatedRoute.params.subscribe((params) => {
      this.productId.set(params['id']);
    });
  }
}
```

### クエリパラメーター {#query-parameters}

[クエリパラメーター](https://developer.mozilla.org/ja-JP/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`でクエリパラメーターにアクセスできます。

次に、製品リストの表示方法に影響を与えるクエリパラメーターを更新する`ProductListComponent`の例を示します。

```typescript
import { ActivatedRoute, Router } from '@angular/router';

@Component({
  selector: 'app-product-list',
  template: `
    <div>
      <select (change)="updateSort($event)">
        <option value="price">Price</option>
        <option value="name">Name</option>
      </select>
      
    </div>
  `
})
export class ProductListComponent implements OnInit {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

constructor() {
    // クエリパラメーターにリアクティブにアクセス
    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' // 他のクエリパラメーターを保持
    });
  }
}
```

この例では、ユーザーは選択要素を使用して製品リストを名前または価格でソートできます。関連する変更ハンドラーはURLのクエリパラメーターを更新し、それが更新されたクエリパラメーターを読み取り、製品リストを更新できる変更イベントをトリガーします。

詳細については、[QueryParamsHandlingに関する公式ドキュメント](/api/router/QueryParamsHandling)を参照してください。

### マトリックスパラメーター {#matrix-parameters}

マトリックスパラメーターは、ルート全体に適用されるのではなく、特定の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'
    });
  }
}
```

NOTE: `ActivatedRoute`を使用する代わりに、`withComponentInputBinding`を使用する場合、マトリックスパラメーターはコンポーネント入力にもバインドされます。

## RouterLinkActiveでアクティブな現在のルートを検出する {#detect-active-current-route-with-routerlinkactive}

`RouterLinkActive`ディレクティブを使用すると、現在の有効なルートに基づいてナビゲーション要素を動的にスタイル設定できます。これは、ユーザーにアクティブなルートが何かを知らせるために、ナビゲーション要素でよく使用されます。

```html
<nav>
  <a class="button"
     routerLink="/about"
     routerLinkActive="active-button"
     ariaCurrentWhenActive="page">
    About
  </a> |
  <a class="button"
     routerLink="/settings"
     routerLinkActive="active-button"
     ariaCurrentWhenActive="page">
    Settings
  </a>
</nav>
```

この例では、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`に値を指定すると、`ariaCurrentWhenActive`にも同じ値が定義されます。これにより、視覚障害のあるユーザー（適用されている異なるスタイルを認識できない場合がある）もアクティブなボタンを識別できます。

ariaに異なる値を定義したい場合は、`ariaCurrentWhenActive`ディレクティブを使用して明示的に値を設定する必要があります。

### ルートマッチング戦略 {#route-matching-strategy}

デフォルトでは、`RouterLinkActive`はルート内のすべての祖先を一致と見なします。

```html
<a [routerLink]="['/user/jane']" routerLinkActive="active-link">
  User
</a>
<a [routerLink]="['/user/jane/role/admin']" routerLinkActive="active-link">
  Role
</a>
```

ユーザーが`/user/jane/role/admin`にアクセスすると、両方のリンクに`active-link`クラスが適用されます。

### RouterLinkActiveを厳密なルート一致にのみ適用する {#only-apply-routerlinkactive-on-exact-route-matches}

厳密な一致の場合にのみクラスを適用したい場合は、`routerLinkActiveOptions`ディレクティブに`exact: true`という値を含む設定オブジェクトを提供する必要があります。

```html
<a [routerLink]="['/user/jane']"
  routerLinkActive="active-link"
  [routerLinkActiveOptions]="{exact: true}"
>
  User
</a>
<a [routerLink]="['/user/jane/role/admin']"
  routerLinkActive="active-link"
  [routerLinkActiveOptions]="{exact: true}"
>
  Role
</a>
```

ルートがどのように一致するかをより正確にしたい場合、`exact: true`は実際には一致オプションの完全なセットに対するシンタックスシュガーであることに注意する価値があります。

```typescript
// `exact: true`は以下と同等です
{
  paths: 'exact',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'exact',
}

// `exact: false`は以下と同等です
{
  paths: 'subset',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'subset',
}
```

詳細については、[isActiveMatchOptionsに関する公式ドキュメント](/api/router/IsActiveMatchOptions)を参照してください。

### RouterLinkActiveを祖先に適用する {#apply-routerlinkactive-to-an-ancestor}

`RouterLinkActive`ディレクティブは、開発者が要素を希望どおりにスタイル設定できるように、祖先要素にも適用できます。

```html
<div routerLinkActive="active-link" [routerLinkActiveOptions]="{exact: true}">
  <a routerLink="/user/jim">Jim</a>
  <a routerLink="/user/bob">Bob</a>
</div>
```

詳細については、[RouterLinkActiveのAPIドキュメント](/api/router/RouterLinkActive)を参照してください。
# その他の一般的なルーティングタスク

このガイドでは、アプリケーションでAngularルーターを使用する際によくあるその他のタスクについて説明します。

## ルート情報の取得

多くの場合、ユーザーがアプリケーションをナビゲートするときに、一方のコンポーネントからもう一方のコンポーネントに情報を渡す必要があります。
たとえば、食料品のショッピングリストを表示するアプリケーションを考えてみてください。
リストの各アイテムには、一意の `id` があります。
アイテムを編集するには、ユーザーは[編集]ボタンをクリックします。これにより、`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(id()));
```

</docs-step>
<docs-step title="Optional: Use a default value">
`withComponentInputBinding` が有効な場合、ルーターは現在のルートに基づいてすべての入力に値を割り当てます。
オプションのクエリパラメータが欠落している場合など、ルートデータが入力キーと一致しない場合、ルーターは `undefined` を割り当てます。
入力がルートによって一致しない可能性がある場合は、`input` の型に `undefined` を含める必要があります。

`input` の `transform` オプションを使用するか、`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: 静的なルートデータ、解決されたルートデータ、パスパラメータ、マトリックスパラメータ、クエリパラメータなど、すべてのルートデータをキーと値のペアでコンポーネントの入力にバインドできます。
親コンポーネントのルート情報を使用する場合は、ルーターの `paramsInheritanceStrategy` オプションを設定する必要があります。
`withRouterConfig({paramsInheritanceStrategy: 'always'})` 。他の利用可能な設定の詳細については、[ルーター設定オプション](guide/routing/customizing-route-behavior#router-configuration-options)を参照してください。

## 404 ページの表示 {#displaying-a-404-page}

404ページを表示するには、[ワイルドカードルート](guide/routing/common-router-tasks#setting-up-wildcard-routes) を設定します。このルートの `component` プロパティは、404ページに使用したいコンポーネントに設定します。

```ts
const routes: Routes = [
  {path: 'first-component', component: FirstComponent},
  {path: 'second-component', component: SecondComponent},
  {path: '**', component: PageNotFoundComponent}, // Wildcard route for a 404 page
];
```

`path` が `**` の最後のルートは、ワイルドカードルートです。
ルーターは、要求されたURLがリストの先頭にあるパスと一致しない場合、このルートを選択し、ユーザーを `PageNotFoundComponent` にルーティングします。

## リンクパラメータ配列 {#link-parameters-array}

リンクパラメータ配列には、ルーターナビゲーションの次の要素が含まれています。

- 宛先コンポーネントへのルートのパス
- ルートURLに含まれる、必須とオプションのルートパラメータ

次のように、`RouterLink` ディレクティブをこのような配列にバインドします。

```html
<a [routerLink]="['/heroes']">Heroes</a>
```

ルートパラメータを指定する場合は、次の2つの要素の配列になります。

```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)の詳細をご覧ください。

これらの3つの例は、ルーティングが1レベルのアプリケーションのニーズを満たしています。
ただし、危機センターなどの子ルーターを使用すると、新しいリンク配列の選択肢が生まれます。

次の最小限の `RouterLink` の例は、危機センターの指定されたデフォルトの子ルートを基に構築されています。

```html
<a [routerLink]="['/crisis-center']">Crisis Center</a>
```

次の点を確認してください。

- 配列の最初の項目は、親ルート $`/crisis-center`$ を識別します
- この親ルートのパラメータはありません
- 子ルートのデフォルトがないため、1つを選択する必要があります
- `CrisisListComponent` にナビゲートしており、そのルートパスは `/` ですが、スラッシュを明示的に追加する必要はありません

危機センターのルートを排他的に使用して、`AppComponent` テンプレートを再定義できます。

```html
<a [routerLink]="['/crisis-center', 1]">Dragon Crisis</a>
```

- 配列の最初の項目は、親ルート $`/crisis-center`$ を識別します
- この親ルートのパラメータはありません
- 2番目の項目は、特定の危機に関する詳細の子ルートを識別します。
- 詳細の子ルートには `id` ルートパラメータが必要です。
- 配列の2番目の項目として、Dragon Crisisの `id` を追加しました。
- 結果のパスは `/crisis-center/1` です。

また、`AppComponent`テンプレートを危機センターのルート専用に再定義できます：

```typescript
@Component({
  template: `
    <h1 class="title">Angular Router</h1>
    <nav>
      <a [routerLink]="['/crisis-center']">Crisis Center</a>
      <a [routerLink]="['/crisis-center/1', { foo: 'foo' }]">Dragon Crisis</a>
      <a [routerLink]="['/crisis-center/2']">Shark Crisis</a>
    </nav>
    <router-outlet />
  `
})
export class AppComponent {}
```

要約すると、ルーティングが1レベル、2レベル、または複数レベルのアプリケーションを作成できます。
リンクパラメータ配列により、任意のルーティング深度、および任意の有効なルートパスのシーケンス、$必須$ ルーターパラメータ、および $オプション$ ルーターパラメータオブジェクトを表すことができます。

## `LocationStrategy` とブラウザ URL のスタイル {#locationstrategy-and-browser-url-styles}

ルーターが新しいコンポーネントビューにナビゲートすると、ブラウザの場所と履歴が、そのビューのURLで更新されます。

最新のHTML5ブラウザは、[history.pushState](https://developer.mozilla.org/docs/Web/API/History_API/Working_with_the_History_API#adding_and_modifying_history_entries 'HTML5 browser history push-state') をサポートしています。これは、サーバーページのリクエストをトリガーせずに、ブラウザの場所と履歴を変更するテクニックです。
ルーターは、サーバーページロードと区別できない「自然な」URLを作成できます。

この「HTML5 pushState」スタイルの危機センターのURLを示します。

```text
localhost:3002/crisis-center
```

古いブラウザは、場所URLが変更された場合、変更が「#」$ハッシュ$ の後に発生しない限り、サーバーにページリクエストを送信します。
ルーターは、この例外を利用して、ハッシュを含むアプリケーション内ルートURLを作成できます。
危機センターにルーティングする「ハッシュURL」を以下に示します。

```text
localhost:3002/src/#/crisis-center
```

ルーターは、2つの `LocationStrategy` プロバイダーで、両方のスタイルをサポートしています。

`RouterModule.forRoot()` 関数は、`LocationStrategy` を `PathLocationStrategy` に設定します。これにより、デフォルトの戦略になります。
ブートストラッププロセス中にオーバーライドを使用して、`HashLocationStrategy` に切り替えることもできます。

HELPFUL: プロバイダーとブートストラッププロセスの詳細については、[依存性の注入](guide/di/dependency-injection-providers) を参照してください。
# シングルページアプリケーションでAngularルートを使う

このチュートリアルでは、複数のAngularルートを使用するシングルページアプリケーション（SPA）を構築する方法について説明します。

シングルページアプリケーション（SPA）では、アプリケーションのすべての機能が単一のHTMLページに存在します。
ユーザーがアプリケーションの機能にアクセスすると、ブラウザは新しいページを読み込む代わりに、ユーザーにとって重要な部分のみをレンダリングする必要があります。
このパターンは、アプリケーションのユーザー体験を大幅に向上させることができます。

ユーザーがアプリケーション内をどのように移動するかを定義するには、ルートを使用します。
ユーザーがアプリケーションのある部分から別の部分へ移動する方法を定義するために、ルートを追加します。
また、予期せぬ動作や不正な動作から保護するために、ルートを設定できます。

## 目的 {#objectives}

- サンプルアプリケーションの機能をモジュールに整理する。
- コンポーネントへのナビゲーション方法を定義する。
- パラメーターを使用してコンポーネントに情報を渡す。
- 複数のルートをネストしてルートを構成する。
- ユーザーがルートにアクセスできるか確認する。
- アプリケーションが未保存の変更を破棄できるかどうかを制御する。
- ルートデータのプリフェッチと機能モジュールの遅延読み込みによってパフォーマンスを向上させる。
- コンポーネントをロードするための特定の条件を要求する。

## サンプルアプリケーションを作成 {#create-a-sample-application}

Angular CLIを使用して、新しいアプリケーション_angular-router-sample_を作成します。
このアプリケーションには、_crisis-list_と_heroes-list_の2つのコンポーネントが含まれます。

1. 新しいAngularプロジェクト_angular-router-sample_を作成します。

```shell
ng new angular-router-sample
   ```

`Would you like to add Angular routing?`と表示されたら、`N`を選択します。

`Which stylesheet format would you like to use?`と表示されたら、`CSS`を選択します。

しばらくすると、新しいプロジェクト`angular-router-sample`の準備が整います。

1. ターミナルから、`angular-router-sample`ディレクトリに移動します。
1. コンポーネント_crisis-list_を作成します。

```shell
ng generate component crisis-list
```

1. コードエディターで、ファイル`crisis-list.component.html`を見つけて、プレースホルダーの内容を以下のHTMLに置き換えます。

```
1. 2番目のコンポーネント_heroes-list_を作成します。

```shell
ng generate component heroes-list
```

1. コードエディターで、ファイル`heroes-list.component.html`を見つけて、プレースホルダーの内容を以下のHTMLに置き換えます。

<docs-code header="heroes-list.component.html" path="adev/src/content/examples/router-tutorial/src/app/heroes-list/heroes-list.component.html"/>

1. コードエディターで、ファイル`app.component.html`を開き、その内容を以下のHTMLに置き換えます。

<docs-code header="app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" region="setup"/>

1. 新しいアプリケーションが期待どおりに動作することを確認するには、`ng serve`コマンドを実行します。

```shell
ng serve
```

1. ブラウザで`http://localhost:4200`を開きます。

タイトルと2つのコンポーネントのHTMLで構成される単一のWebページが表示されるはずです。

## ルートを定義する {#define-your-routes}

このセクションでは、2つのルートを定義します。

- ルート`/crisis-center`は`crisis-center`コンポーネントを開きます。
- ルート`/heroes-list`は`heroes-list`コンポーネントを開きます。

ルート定義はJavaScriptオブジェクトです。
各ルートには通常2つのプロパティがあります。
最初のプロパティである`path`は、ルートのURLパスを指定する文字列です。
2番目のプロパティである`component`は、アプリケーションがそのパスに表示すべきコンポーネントを指定する文字列です。

1. コードエディターから、`app.routes.ts`ファイルを作成して開きます。
1. アプリケーションのルートリストを作成してエクスポートします。

```ts
import {Routes} from '@angular/router';

export const routes = [];
   ```

1. 最初の2つのコンポーネントに2つのルートを追加します。

```ts
{path: 'crisis-list', component: CrisisListComponent},
   {path: 'heroes-list', component: HeroesListComponent},
   ```

このルートリストはJavaScriptオブジェクトの配列であり、各オブジェクトがルートのプロパティを定義しています。

## `@angular/router`から`provideRouter`をインポートする {#import-providerouter-from-angularrouter}

ルーティングを使用すると、URLパスに応じてアプリケーションの特定のビューを表示できます。
この機能をサンプルアプリケーションに追加するには、`app.config.ts`ファイルを更新して、ルータープロバイダー関数である`provideRouter`を使用する必要があります。
このプロバイダー関数は`@angular/router`からインポートします。

1. コードエディターで`app.config.ts`ファイルを開きます。
1. 次のインポートステートメントを追加します。

```ts
import {provideRouter} from '@angular/router';
   import {routes} from './app.routes';
   ```

1. `appConfig`のプロバイダーを更新します。

```ts
providers: [provideRouter(routes)];
   ```

`NgModule`ベースのアプリケーションの場合、`provideRouter`は`AppModule`の`providers`リスト、またはアプリケーションで`bootstrapModule`に渡されるモジュールに配置します。

## `router-outlet`を使ってコンポーネントを更新する {#update-your-component-with-router-outlet}

この時点で、アプリケーションに2つのルートを定義しました。
しかし、アプリケーションの`app.component.html`テンプレートには、`crisis-list`と`heroes-list`の両コンポーネントがまだハードコードされています。
ルートが機能するためには、URLパスに基づいてコンポーネントを動的にロードするようにテンプレートを更新する必要があります。

この機能を実装するには、テンプレートファイルに`router-outlet`ディレクティブを追加します。

1. コードエディターで`app.component.html`ファイルを開きます。
1. 以下の行を削除します。

<docs-code header="app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" region="components"/>

1. `router-outlet`ディレクティブを追加します。

<docs-code header="app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" region="router-outlet"/>

1. `app.component.ts`の`AppComponent`のインポートに`RouterOutlet`を追加します。

```ts
imports: [RouterOutlet],
   ```

更新されたアプリケーションをブラウザで表示します。
アプリケーションのタイトルのみが表示されるはずです。
`crisis-list`コンポーネントを表示するには、ブラウザのアドレスバーのパスの末尾に`crisis-list`を追加します。
例:

<docs-code language="http">
http://localhost:4200/crisis-list
```
`crisis-list`コンポーネントが表示されることに注目してください。
Angularは、定義したルートを使用してコンポーネントを動的にロードしています。
同じ方法で`heroes-list`コンポーネントをロードできます。

```http
http://localhost:4200/heroes-list
```
## UI要素でナビゲーションを制御する {#control-navigation-with-ui-elements}

現在、アプリケーションは2つのルートをサポートしています。
しかし、これらのルートを使用する唯一の方法は、ユーザーがブラウザのアドレスバーにパスを手動で入力することです。
このセクションでは、ユーザーがクリックして`heroes-list`コンポーネントと`crisis-list`コンポーネント間を移動できる2つのリンクを追加します。
また、いくつかのCSSスタイルも追加します。
これらのスタイルは必須ではありませんが、現在表示されているコンポーネントのリンクを識別しやすくします。
この機能は次のセクションで追加します。

1. `app.component.html`ファイルを開き、タイトルの下に以下のHTMLを追加します。

<docs-code header="app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" region="nav"/>

このHTMLはAngularディレクティブである`routerLink`を使用しています。
   このディレクティブは、定義したルートをテンプレートファイルに接続します。

1. `app.component.ts`の`AppComponent`のimportsリストに`RouterLink`ディレクティブを追加します。

1. `app.component.css`ファイルを開き、以下のスタイルを追加します。

<docs-code header="app.component.css" path="adev/src/content/examples/router-tutorial/src/app/app.component.css"/>

ブラウザでアプリケーションを表示すると、これら2つのリンクが表示されるはずです。
リンクをクリックすると、対応するコンポーネントが表示されます。

## アクティブルートの特定 {#identify-the-active-route}

ユーザーは前のセクションで追加したリンクを使用してアプリケーションをナビゲートできますが、アクティブルートが何かを特定する簡単な方法がありません。
Angularの`routerLinkActive`ディレクティブを使用してこの機能を追加します。

1. コードエディターで、`app.component.html`ファイルを開きます。
1. アンカータグを更新して、`routerLinkActive`ディレクティブを含めるようにします。

<docs-code header="app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" region="routeractivelink"/>

1. `app.component.ts`の`AppComponent`の`imports`リストに`RouterLinkActive`ディレクティブを追加します。

アプリケーションを再度表示します。
いずれかのボタンをクリックすると、そのボタンのスタイルが自動的に更新され、アクティブなコンポーネントをユーザーに特定します。
`routerLinkActive`ディレクティブを追加することで、アプリケーションに特定のCSSクラスをアクティブルートに適用するよう指示します。
このチュートリアルでは、そのCSSクラスは`activebutton`ですが、好きな任意のクラスを使用できます。

Note: `routerLinkActive`の`ariaCurrentWhenActive`に値を指定していることにも注意してください。これにより、視覚に障がいのあるユーザー（適用されている異なるスタイルを認識できない可能性のあるユーザー）もアクティブなボタンを特定できます。詳細については、アクセシビリティのベストプラクティス[アクティブリンクの識別セクション](/best-practices/a11y#active-links-identification)を参照してください。

## リダイレクトの追加 {#adding-a-redirect}

このチュートリアルのステップでは、ユーザーを`/heroes-list`コンポーネントの表示にリダイレクトするルートを追加します。

1. コードエディターで`app.routes.ts`ファイルを開きます。
1. `routes`セクションを次のように更新します。

```ts
{path: '', redirectTo: '/heroes-list', pathMatch: 'full'},
   ```

この新しいルートは、パスとして空の文字列を使用していることに注意してください。
   さらに、`component`プロパティを2つの新しいプロパティに置き換えます。

| プロパティ   | 詳細                                                                                                                                                                                                                                                                          |
   | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `redirectTo` | このプロパティは、Angularに空のパスから`heroes-list`パスへのリダイレクトを指示します。                                                                                                                                                                                        |
   | `pathMatch`  | このプロパティは、AngularにURLのどの部分を一致させるかを指示します。このチュートリアルでは、このプロパティを`full`に設定する必要があります。この戦略は、パスに空の文字列がある場合に推奨されます。このプロパティの詳細については、[Route API documentation](api/router/Route)を参照してください。 |

これでアプリケーションを開くと、デフォルトで`heroes-list`コンポーネントが表示されます。

## 404ページを追加する {#adding-a-404-page}

ユーザーが未定義のルートにアクセスしようとする可能性があります。
この動作に対応するには、404ページを表示するのがベストプラクティスです。
このセクションでは、404ページを作成し、未指定のルートに対してそのページを表示するようにルート設定を更新します。

1. ターミナルから、新しいコンポーネント`PageNotFound`を作成します。

```shell
ng generate component page-not-found
```

1. コードエディターで、`page-not-found.component.html`ファイルを開き、その内容を以下のHTMLに置き換えます。

<docs-code header="page-not-found.component.html" path="adev/src/content/examples/router-tutorial/src/app/page-not-found/page-not-found.component.html"/>

1. `app.routes.ts`ファイルを開き、以下のルートをルートリストに追加します。

```ts
{path: '**', component: PageNotFoundComponent}
   ```

新しいルートはパス`**`を使用します。
   このパスは、Angularがワイルドカードルートを識別する方法です。
   設定内の既存のルートと一致しないルートは、すべてこのルートを使用します。

IMPORTANT: ワイルドカードルートが配列の最後に配置されていることに注意してください。
Angularはルートを順番に適用し、最初に見つかった一致を使用するため、ルートの順序は重要です。

`http://localhost:4200/powers`のような、アプリケーション上に存在しないルートに移動してみてください。
このルートは、`app.routes.ts`ファイルで定義されているものと一致しません。
しかし、ワイルドカードルートを定義したため、アプリケーションは自動的に`PageNotFound`コンポーネントを表示します。

## 次のステップ {#next-steps}

この時点で、Angularのルーティング機能を使用して、URLアドレスに基づいてユーザーが見ることができるコンポーネントを変更する基本的なアプリケーションができています。
これらの機能を拡張して、リダイレクトや、カスタムの404ページを表示するためのワイルドカードルートを含めました。

ルーティングの詳細については、以下のトピックを参照してください。
# カスタムルートマッチの作成

Angular Routerは、アプリケーションのナビゲーションを支援するために使用できる強力なマッチング戦略をサポートしています。
このマッチング戦略は、パラメーター付きの静的ルート、可変ルート、ワイルドカードルートなどをサポートしています。
また、URLがより複雑な状況で独自のカスタムパターンマッチを作成できます。

このチュートリアルでは、Angularの`UrlMatcher`を使用してカスタムルートマッチャーを作成します。
このマッチャーは、URL内のTwitterハンドルを検索します。

## 目標

Angularの`UrlMatcher`を実装してカスタムルートマッチャーを作成します。

## サンプルアプリケーションの作成

Angular CLIを使用して、新しいアプリケーション_angular-custom-route-match_を作成します。
デフォルトのAngularアプリケーションフレームワークに加えて、_profile_コンポーネントも作成します。

1. 新しいAngularプロジェクト、_angular-custom-route-match_を作成します。

```shell
ng new angular-custom-route-match
   ```

`Angular routingを追加しますか？`と表示されたら、`Y`を選択します。

`どのスタイルシート形式を使用しますか？`と表示されたら、`CSS`を選択します。

しばらくすると、新しいプロジェクト`angular-custom-route-match`の準備が整います。

1. ターミナルから`angular-custom-route-match`ディレクトリに移動します。
1. コンポーネント、_profile_を作成します。

```shell
ng generate component profile
   ```

1. コードエディタで`profile.component.html`ファイルを見つけ、プレースホルダーコンテンツを次のHTMLに置き換えます。

<docs-code header="profile.component.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/profile/profile.component.html"/>

1. コードエディタで`app.component.html`ファイルを見つけ、プレースホルダーコンテンツを次のHTMLに置き換えます。

<docs-code header="app.component.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.component.html"/>

## アプリケーションのルートを構成する

アプリケーションフレームワークが整ったら、次に`app.config.ts`ファイルにルーティング機能を追加する必要があります。
このプロセスの一環として、URL内のTwitterハンドルを検索するカスタムURLマッチャーを作成します。
このハンドルは、先行する`@`シンボルによって識別されます。

1. コードエディタで`app.config.ts`ファイルを開きます。
1. Angularの`provideRouter`と`withComponentInputBinding`、およびアプリケーションルートの`import`ステートメントを追加します。

```ts
import {provideRouter, withComponentInputBinding} from '@angular/router';

import {routes} from './app.routes';
   ```

1. プロバイダー配列に`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"/>

このカスタムマッチャーは、次のタスクを実行する関数です。

- マッチャーは、配列にセグメントが1つしかないことを確認します
- マッチャーは正規表現を使用して、ユーザー名の形式が一致することを確認します
- 一致があれば、関数は完全なURLを返し、`username`ルートパラメーターをパスのサブストリングとして定義します
- 一致しなければ、関数はnullを返し、ルーターはURLと一致する他のルートを探し続けます

HELPFUL: カスタムURLマッチャーは、他のルート定義と同じように動作します。他のルートと同じように、子ルートまたは遅延読み込みルートを定義します。

## ルートパラメーターの読み取り

カスタムマッチャーが設定されたので、`profile`コンポーネントでルートパラメーターをバインドできます。

コードエディタで`profile.component.ts`ファイルを開き、`username`パラメーターと一致する`input`を作成します。
以前、`provideRouter`で`withComponentInputBinding`機能を追加しました。
これにより、`Router`はルートコンポーネントに直接情報をバインドできます。

```ts
username = input.required<string>();
```

## カスタムURLマッチャーをテストする

コードが設定されたので、カスタムURLマッチャーをテストできます。

1. ターミナルウィンドウから`ng serve`コマンドを実行します。

```shell
ng serve
   ```

1. ブラウザを`http://localhost:4200`に開きます。

`私のプロフィールに移動`という文章を含む単一のWebページが表示されます。

1. **私のプロフィール**ハイパーリンクをクリックします。

`こんにちは、Angular！`という新しい文章がページに表示されます。

## 次のステップ

Angular Routerのパターンマッチングを使用すると、アプリケーションで動的なURLがある場合に、多くの柔軟性を得られます。
Angular Routerの詳細については、以下のトピックを参照してください。
HELPFUL: このコンテンツは、[Brandon Roberts](https://twitter.com/brandontroberts)による[Angular Routerを使用したカスタムルートマッチング](https://medium.com/@brandontroberts/custom-route-matching-with-the-angular-router-fbdd48665483)に基づいています。
# サーバーとハイブリッドレンダリング

Angularはデフォルトですべてのアプリケーションをクライアントサイドレンダリング (CSR) として提供します。このアプローチは軽量な初期ペイロードを提供しますが、ユーザーのデバイスがほとんどの計算をするため、ロード時間の遅延、パフォーマンス指標の低下、リソース要件の増加といったトレードオフを伴います。その結果、多くのアプリケーションはサーバーサイドレンダリング (SSR) をハイブリッドレンダリング戦略に統合することで、大幅なパフォーマンス向上を実現しています。

## ハイブリッドレンダリングとは？ {#what-is-hybrid-rendering}

ハイブリッドレンダリングにより、開発者はサーバーサイドレンダリング (SSR)、プリレンダリング (「静的サイト生成」またはSSGとも呼ばれる)、およびクライアントサイドレンダリング (CSR) の利点を活用して、Angularアプリケーションを最適化できます。これにより、アプリケーションのさまざまな部分がどのようにレンダリングされるかをきめ細かく制御し、ユーザーに可能な限り最高のユーザー体験を提供できます。

## ハイブリッドレンダリングのセットアップ {#setting-up-hybrid-rendering}

Angular CLIの `ng new` コマンドでサーバーサイドレンダリングフラグ (つまり、`--ssr`) を使用すると、ハイブリッドレンダリングを有効にした**新しい**プロジェクトを作成できます。

```shell
ng new --ssr
```

既存のプロジェクトにサーバーサイドレンダリングを追加して、ハイブリッドレンダリングを有効にできます。

```shell
ng add @angular/ssr
```

NOTE: デフォルトでは、Angularはアプリケーション全体をプリレンダリングし、サーバーファイルを生成します。これを無効にして完全に静的なアプリケーションを作成するには、`outputMode` を `static` に設定します。SSRを有効にするには、サーバーのルートを更新して `RenderMode.Server` を使用します。詳細については、[`サーバールーティング`](#server-routing) および [`完全に静的なアプリケーションを生成する`](#generate-a-fully-static-application) を参照してください。

## サーバールーティング {#server-routing}

### サーバールートの設定 {#configuring-server-routes}

[`ServerRoute`](api/ssr/ServerRoute 'API reference') オブジェクトの配列を宣言することで、サーバールート設定を作成できます。この設定は通常、`app.routes.server.ts` というファイルに記述されます。

```typescript
// app.routes.server.ts
import {RenderMode, ServerRoute} from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: '', // これはクライアントで "/" ルートをレンダリングします (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 reference') 関数を使用して [`provideServerRendering`](api/ssr/provideServerRendering 'API reference') でアプリケーションに追加できます。

```typescript
import {provideServerRendering, withRoutes} from '@angular/ssr';
import {serverRoutes} from './app.routes.server';

// app.config.server.ts
const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes)),
    // ... その他のプロバイダー ...
  ],
};
```

[App shellパターン](ecosystem/service-workers/app-shell)を使用する場合、クライアントサイドレンダリングされたルートのApp shellとして使用するコンポーネントを指定する必要があります。これを行うには、[`withAppShell`](api/ssr/withAppShell 'API reference') 機能を使用します。

```typescript
import {provideServerRendering, withRoutes, withAppShell} from '@angular/ssr';
import {AppShellComponent} from './app-shell/app-shell.component';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes), withAppShell(AppShellComponent)),
    // ... その他のプロバイダー ...
  ],
};
```

### レンダリングモード {#rendering-modes}

サーバールーティング設定では、[`RenderMode`](api/ssr/RenderMode 'API reference') を設定することで、アプリケーションの各ルートをどのようにレンダリングするかを指定できます。

| レンダリングモード    | 説明                                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------------- |
| **Server (SSR)**    | 各リクエストに対してアプリケーションをサーバーでレンダリングし、完全にデータが投入されたHTMLページをブラウザに送信します。 |
| **Client (CSR)**    | アプリケーションをブラウザでレンダリングします。これはAngularのデフォルトの動作です。                               |
| **Prerender (SSG)** | ビルド時にアプリケーションをプリレンダリングし、各ルートの静的HTMLファイルを生成します。                               |

#### レンダリングモードの選択 {#choosing-a-rendering-mode}

各レンダリングモードには異なる利点と欠点があります。アプリケーションの特定のニーズに基づいてレンダリングモードを選択できます。

##### クライアントサイドレンダリング (CSR) {#client-side-rendering-csr}

クライアントサイドレンダリングは、常にWebブラウザで実行されることを前提としたコードを記述できるため、最もシンプルな開発モデルです。これにより、ブラウザで実行されることを前提とした幅広いクライアントサイドライブラリを使用できます。

クライアントサイドレンダリングは、ユーザーがレンダリングされたコンテンツを見る前にページのJavaScriptをダウンロード、解析、実行する必要があるため、一般的に他のレンダリングモードよりもパフォーマンスが劣ります。ページがレンダリング中にサーバーからさらにデータを取得する場合、ユーザーは完全なコンテンツを表示する前にそれらの追加リクエストを待つ必要があります。

ページが検索クローラーによってインデックス付けされる場合、検索クローラーはページのインデックス付け時に実行するJavaScriptの量に制限があるため、クライアントサイドレンダリングは検索エンジン最適化 (SEO) に悪影響を与える可能性があります。

クライアントサイドレンダリングの場合、サーバーは静的なJavaScriptアセットを配信する以外に、ページをレンダリングするための作業をする必要がありません。サーバーコストが懸念される場合は、この要素を考慮してもよいでしょう。

Service Workerによるインストール可能でオフラインのユーザー体験をサポートするアプリケーションは、サーバーと通信することなくクライアントサイドレンダリングに依存できます。

##### サーバーサイドレンダリング (SSR) {#server-side-rendering-ssr}

サーバーサイドレンダリングは、クライアントサイドレンダリングよりも高速なページロードを提供します。JavaScriptのダウンロードと実行を待つ代わりに、サーバーはブラウザからのリクエストを受信すると、直接HTMLドキュメントをレンダリングします。ユーザーは、サーバーがデータを取得し、要求されたページをレンダリングするために必要な遅延のみを経験します。このモードでは、コードがサーバーでのレンダリング中にデータを取得できるため、ブラウザからの追加のネットワークリクエストも不要になります。

サーバーサイドレンダリングは、検索クローラーが完全にレンダリングされたHTMLドキュメントを受け取るため、一般的に優れた検索エンジン最適化 (SEO) を実現します。

サーバーサイドレンダリングでは、ブラウザAPIに厳密に依存しないコードを作成する必要があり、ブラウザで実行されることを前提としたJavaScriptライブラリの選択が制限されます。

サーバーサイドレンダリングの場合、サーバーはAngularを実行してすべてのリクエストに対してHTMLレスポンスを生成するため、サーバーのホスティングコストが増加する可能性があります。

##### ビルド時プリレンダリング {#build-time-prerendering}

プリレンダリングは、クライアントサイドレンダリングとサーバーサイドレンダリングの両方よりも高速なページロードを提供します。プリレンダリングは_ビルド時_にHTMLドキュメントを作成するため、サーバーは追加の作業なしに静的なHTMLドキュメントで直接リクエストに応答できます。

プリレンダリングでは、ページをレンダリングするために必要なすべての情報が_ビルド時_に利用可能である必要があります。これは、プリレンダリングされたページに、ページをロードする特定のユーザーに関するデータを含めることができないことを意味します。プリレンダリングは、アプリケーションのすべてのユーザーにとって同じであるページに主に役立ちます。

プリレンダリングはビルド時に行われるため、本番ビルドにかなりの時間を追加する可能性があります。[`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') を使用して多数のHTMLドキュメントを生成すると、デプロイの合計ファイルサイズに影響を与え、デプロイが遅くなる可能性があります。

プリレンダリングは、検索クローラーが完全にレンダリングされたHTMLドキュメントを受け取るため、一般的に優れた検索エンジン最適化 (SEO) を実現します。

プリレンダリングでは、ブラウザAPIに厳密に依存しないコードを作成する必要があり、ブラウザで実行されることを前提としたJavaScriptライブラリの選択が制限されます。

プリレンダリングは、サーバーが静的なHTMLドキュメントで応答するため、サーバーリクエストあたりのオーバーヘッドが非常に少なくなります。静的ファイルは、コンテンツデリバリーネットワーク (CDN)、ブラウザ、および中間キャッシュレイヤーによって簡単にキャッシュされ、その後のページロードをさらに高速化できます。完全に静的なサイトは、CDNまたは静的ファイルサーバーのみを介したデプロイもでき、アプリケーション用のカスタムサーバー実行時を維持する必要がなくなります。これにより、アプリケーションWebサーバーからの作業をオフロードすることでスケーラビリティが向上し、トラフィックの多いアプリケーションにとって特に有益です。

NOTE: Angular Service Workerを使用する場合、最初のリクエストはサーバーレンダリングされますが、それ以降のすべてのリクエストはService Workerによって処理され、クライアントサイドでレンダリングされます。

### ヘッダーとステータスコードの設定 {#setting-headers-and-status-codes}

`ServerRoute` 設定の `headers` および `status` プロパティを使用して、個々のサーバールートにカスタムヘッダーとステータスコードを設定できます。

```typescript
// app.routes.server.ts
import {RenderMode, ServerRoute} from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'profile',
    renderMode: RenderMode.Server,
    headers: {
      'X-My-Custom-Header': 'some-value',
    },
    status: 201,
  },
  // ... その他のルート
];
```

### リダイレクト {#redirects}

Angularは、ルート設定の [`redirectTo`](api/router/Route#redirectTo 'API reference') プロパティで指定されたリダイレクトを、サーバーサイドでは異なる方法で処理します。

**サーバーサイドレンダリング (SSR)**
リダイレクトは、サーバーサイドレンダリングプロセス内で標準的なHTTPリダイレクト (例: 301、302) を使用して実行されます。

**プリレンダリング (SSG)**
リダイレクトは、プリレンダリングされたHTML内の [`<meta http-equiv="refresh">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#refresh) タグを使用して「ソフトリダイレクト」として実装されます。

### ビルド時プリレンダリング (SSG) のカスタマイズ {#customizing-build-time-prerendering-ssg}

[`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') を使用する場合、プリレンダリングと提供プロセスをカスタマイズするためのいくつかの設定オプションを指定できます。

#### パラメーター化されたルート {#parameterized-routes}

[`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') を持つ各ルートについて、[`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') 関数を指定できます。この関数を使用すると、どの特定のパラメーターが個別のプリレンダリングされたドキュメントを生成するかを制御できます。

[`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') 関数は、オブジェクトの配列に解決される `Promise` を返します。各オブジェクトは、ルートパラメーター名から値へのキーと値のマップです。たとえば、`post/:id` のようなルートを定義した場合、`getPrerenderParams` は配列 `[{id: 123}, {id: 456}]` を返し、`post/123` と `post/456` の個別のドキュメントをレンダリングできます。

[`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') の本体は、Angularの [`inject`](api/core/inject 'API reference') 関数を使用して依存性を注入し、どのルートをプリレンダリングするかを決定するための任意の作業ができます。これには通常、パラメーター値の配列を構築するためにデータを取得するリクエストを行うことが含まれます。

この関数は、キャッチオールルート (例: `/**`) でも使用できます。この場合、パラメーター名は `"**"` となり、戻り値は `foo/bar` のようなパスのセグメントになります。これらは他のパラメーター (例: `/post/:id/**`) と組み合わせて、より複雑なルート設定を処理できます。

```ts
// app.routes.server.ts
import {RenderMode, ServerRoute} from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'post/:id',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      const dataService = inject(PostService);
      const ids = await dataService.getIds(); // これは ['1', '2', '3'] を返すと仮定します

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 reference') は [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') にのみ適用されるため、この関数は常に_ビルド時_に実行されます。`getPrerenderParams` は、データのためにブラウザ固有またはサーバー固有のAPIに依存してはなりません。

IMPORTANT: `getPrerenderParams` 内で [`inject`](api/core/inject 'API reference') を使用する場合、`inject` は同期的に使用する必要があることに注意してください。非同期コールバック内や `await` ステートメントの後に呼び出すことはできません。詳細については、`runInInjectionContext` を参照してください。

#### フォールバック戦略 {#fallback-strategies}

[`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') モードを使用する場合、プリレンダリングされていないパスへのリクエストを処理するためのフォールバック戦略を指定できます。

利用可能なフォールバック戦略は次のとおりです。

- **Server:** サーバーサイドレンダリングにフォールバックします。これは、`fallback` プロパティが指定されていない場合の**デフォルト**の動作です。
- **Client:** クライアントサイドレンダリングにフォールバックします。
- **None:** フォールバックなし。Angularは、プリレンダリングされていないパスへのリクエストを処理しません。

```ts
// app.routes.server.ts
import {RenderMode, PrerenderFallback, ServerRoute} from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'post/:id',
    renderMode: RenderMode.Prerender,
    fallback: PrerenderFallback.Client, // プリレンダリングされていない場合はCSRにフォールバック
    async getPrerenderParams() {
      // この関数は、/post/1、/post/2、/post/3 のパスで
      // プリレンダリングされた投稿を表すオブジェクトの配列を返します。
      // /post/4 のパスがリクエストされた場合、フォールバック動作が利用されます。
      return [{id: 1}, {id: 2}, {id: 3}];
    },
  },
];
```

## サーバー互換コンポーネントの作成 {#authoring-server-compatible-components}

一部の一般的なブラウザAPIと機能は、サーバーでは利用できない場合があります。アプリケーションは、`window`、`document`、`navigator`、`location` などのブラウザ固有のグローバルオブジェクトや、`HTMLElement` の特定のプロパティを使用できません。

一般に、ブラウザ固有のシンボルに依存するコードは、サーバーではなくブラウザでのみ実行されるべきです。これは、`afterEveryRender` および `afterNextRender` ライフサイクルフックによって強制できます。これらはブラウザでのみ実行され、サーバーではスキップされます。

```typescript
import { Component, viewChild, afterNextRender } from '@angular/core';

@Component({
  selector: 'my-cmp',
  template: `<span #content>{{ ... }}</span>`,
})
export class MyComponent {
  contentRef = viewChild.required<ElementRef>('content');

constructor() {
    afterNextRender(() => {
      // これはサーバーではなくブラウザでのみ実行されるため、`scrollHeight` のチェックは安全です。
      console.log('content height: ' + this.contentRef().nativeElement.scrollHeight);
    });
  }
}
```

NOTE: `isPlatformBrowser` や `isPlatformServer` を使用したランタイムチェックよりも、[プラットフォーム固有のプロバイダー](guide/ssr#providing-platform-specific-implementations)を推奨します。

IMPORTANT: テンプレートで `isPlatformBrowser` を `@if` やその他の条件と共に使用して、サーバーとクライアントで異なるコンテンツをレンダリングすることは避けてください。これはハイドレーションの不一致やレイアウトシフトを引き起こし、ユーザー体験と[Core Web Vitals](https://web.dev/learn-core-web-vitals/)に悪影響を与えます。代わりに、ブラウザ固有の初期化には `afterNextRender` を使用し、レンダリングされるコンテンツをプラットフォーム間で一貫性のあるものに保ちます。

## サーバーでプロバイダーを設定する {#setting-providers-on-the-server}

サーバー側では、トップレベルのプロバイダー値は、アプリケーションコードが最初に解析および評価されたときに一度設定されます。
これは、`useValue` で設定されたプロバイダーは、サーバーアプリケーションが再起動されるまで、複数のリクエストにわたって値を保持することを意味します。

リクエストごとに新しい値を生成したい場合は、`useFactory` を使用してファクトリープロバイダーを使用します。ファクトリー関数は、受信リクエストごとに実行され、毎回新しい値が作成されてトークンに割り当てられることを保証します。

## プラットフォーム固有の実装を提供する {#providing-platform-specific-implementations}

アプリケーションがブラウザとサーバーで異なる動作を必要とする場合、各プラットフォーム用に個別のサービス実装を提供します。このアプローチにより、プラットフォームロジックを専用のサービスに集中させることができます。

```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
// app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: BrowserAnalyticsService}],
};
```

サーバー構成の中で、サーバー実装でオーバーライドします。

```ts
// app.config.server.ts
const serverConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: ServerAnalyticsService}],
};
```

コンポーネントでサービスを注入して使用します。

```ts
@Component({
  /* ... */
})
export class Checkout {
  private analytics = inject(AnalyticsService);

onAction() {
    this.analytics.trackEvent('action');
  }
}
```

## DIを介したDocumentへのアクセス {#accessing-document-via-di}

サーバーサイドレンダリングを使用する場合、`document` のようなブラウザ固有のグローバルを直接参照することは避けるべきです。代わりに、[`DOCUMENT`](api/core/DOCUMENT) トークンを使用して、プラットフォームに依存しない方法でdocumentオブジェクトにアクセスします。

```ts
import {Injectable, inject, DOCUMENT} from '@angular/core';

@Injectable({providedIn: 'root'})
export class CanonicalLinkService {
  private readonly document = inject(DOCUMENT);

// サーバーレンダリング中に <link rel="canonical"> タグを注入し、
  // 生成されたHTMLに正しいcanonical URLが含まれるようにします
  setCanonical(href: string): void {
    const link = this.document.createElement('link');
    link.rel = 'canonical';
    link.href = href;
    this.document.head.appendChild(link);
  }
}
```

HELPFUL: メタタグの管理には、Angularは `Meta` サービスを提供しています。

## DIを介したリクエストとレスポンスへのアクセス {#accessing-request-and-response-via-di}

`@angular/core` パッケージは、サーバーサイドレンダリング環境と対話するためのいくつかのトークンを提供します。これらのトークンにより、SSR中にAngularアプリケーション内で重要な情報とオブジェクトにアクセスできます。

-   **[`REQUEST`](api/core/REQUEST 'API reference'):** Web APIの [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) 型である現在のリクエストオブジェクトへのアクセスを提供します。これにより、ヘッダー、Cookie、その他のリクエスト情報にアクセスできます。
-   **[`RESPONSE_INIT`](api/core/RESPONSE_INIT 'API reference'):** Web APIの [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#parameters) 型であるレスポンス初期化オプションへのアクセスを提供します。これにより、レスポンスのヘッダーとステータスコードを動的に設定できます。このトークンを使用して、実行時に決定する必要があるヘッダーまたはステータスコードを設定します。
-   **[`REQUEST_CONTEXT`](api/core/REQUEST_CONTEXT 'API reference'):** 現在のリクエストに関連する追加のコンテキストへのアクセスを提供します。このコンテキストは、[`handle`](api/ssr/AngularAppEngine#handle 'API reference') 関数の2番目のパラメーターとして渡すことができます。通常、これは標準のWeb APIの一部ではない追加のリクエスト関連情報を提供するために使用されます。

```typescript
import { inject, REQUEST } from '@angular/core';

@Component({
  selector: 'app-my-component',
  template: `<h1>My Component</h1>`,
})
export class MyComponent {
  constructor() {
    const request = inject(REQUEST);
    console.log(request?.url);
  }
}
```

IMPORTANT: 上記のトークンは、次のシナリオでは `null` になります。

-   ビルドプロセス中。
-   アプリケーションがブラウザでレンダリングされるとき (CSR)。
-   静的サイト生成 (SSG) を実行するとき。
-   開発中のルート抽出時 (リクエスト時)。

## 完全に静的なアプリケーションを生成する {#generate-a-fully-static-application}

デフォルトでは、Angularはアプリケーション全体をプリレンダリングし、リクエストを処理するためのサーバーファイルを生成します。これにより、アプリケーションはプリレンダリングされたコンテンツをユーザーに提供できます。ただし、サーバーなしで完全に静的なサイトを希望する場合は、`angular.json` 設定ファイルで `outputMode` を `static` に設定することで、この動作を無効にできます。

`outputMode` が `static` に設定されている場合、Angularはビルド時に各ルートのプリレンダリングされたHTMLファイルを生成しますが、サーバーファイルを生成したり、アプリケーションを提供するためにNode.jsサーバーを必要としたりしません。これは、バックエンドサーバーが不要な静的ホスティングプロバイダーにデプロイする場合に便利です。

これを設定するには、`angular.json` ファイルを次のように更新します。

```json
{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "outputMode": "static"
          }
        }
      }
    }
  }
}
```

## HttpClient使用時のデータキャッシュ {#caching-data-when-using-httpclient}

`HttpClient` は、サーバーで実行されているときに送信ネットワークリクエストをキャッシュします。この情報はシリアル化され、サーバーから送信される初期HTMLの一部としてブラウザに転送されます。ブラウザでは、`HttpClient` はキャッシュにデータがあるかどうかを確認し、ある場合は、初期アプリケーションレンダリング中に新しいHTTPリクエストを行う代わりにそれを再利用します。`HttpClient` は、ブラウザで実行中にアプリケーションが[安定](api/core/ApplicationRef#isStable)すると、キャッシュの使用を停止します。

### キャッシュオプションの設定 {#configuring-the-caching-options}

サーバーサイドレンダリング (SSR) 中にAngularがHTTPレスポンスをキャッシュし、ハイドレーション中にそれらを再利用する方法を、`HttpTransferCacheOptions` を設定することでカスタマイズできます。
この設定は、`provideClientHydration()` 内で `withHttpTransferCacheOptions` を使用してグローバルに提供されます。

デフォルトでは、`HttpClient` は `Authorization` または `Proxy-Authorization` ヘッダーを含まないすべての `HEAD` および `GET` リクエストをキャッシュします。ハイドレーション設定に `withHttpTransferCacheOptions` を使用することで、これらの設定をオーバーライドできます。

```ts
import {bootstrapApplication} from '@angular/platform-browser';
import {provideClientHydration, withHttpTransferCacheOptions} from '@angular/platform-browser';

bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        includeHeaders: ['ETag', 'Cache-Control'],
        filter: (req) => !req.url.includes('/api/profile'),
        includePostRequests: true,
        includeRequestsWithAuthHeaders: false,
      }),
    ),
  ],
});
```

---

### `includeHeaders` {#includeheaders}

サーバーレスポンスのどのヘッダーをキャッシュエントリに含めるかを指定します。
デフォルトではヘッダーは含まれません。

```ts
withHttpTransferCacheOptions({
  includeHeaders: ['ETag', 'Cache-Control'],
});
```

IMPORTANT: 認証トークンのような機密性の高いヘッダーを含めることは避けてください。これらはリクエスト間でユーザー固有のデータを漏洩させる可能性があります。

---

### `includePostRequests` {#includepostrequests}

デフォルトでは、`GET` および `HEAD` リクエストのみがキャッシュされます。
GraphQLクエリなどの読み取り操作として使用される場合、`POST` リクエストのキャッシュを有効にできます。

```ts
withHttpTransferCacheOptions({
  includePostRequests: true,
});
```

これは、`POST` リクエストが**冪等**であり、サーバーとクライアントのレンダリング間で再利用しても安全な場合にのみ使用してください。

---

### `includeRequestsWithAuthHeaders` {#includerequestswithauthheaders}

`Authorization` または `Proxy-Authorization` ヘッダーを含むリクエストをキャッシュ対象とするかどうかを決定します。
デフォルトでは、ユーザー固有のレスポンスのキャッシュを防ぐために、これらは除外されます。

```ts
withHttpTransferCacheOptions({
  includeRequestsWithAuthHeaders: true,
});
```

認証ヘッダーがレスポンス内容に影響を**与えない**場合(例: 分析API用のパブリックトークン)のみ有効にしてください。

### リクエストごとのオーバーライド {#perrequest-overrides}

`transferCache` リクエストオプションを使用して、特定のリクエストのキャッシュ動作をオーバーライドできます。

```ts
// このリクエストに特定のヘッダーを含める
http.get('/api/profile', {transferCache: {includeHeaders: ['CustomHeader']}});
```

### キャッシュの無効化 {#disabling-caching}

サーバーから送信されるリクエストのHTTPキャッシュを、グローバルまたは個別に無効にできます。

#### グローバル {#globally}

アプリケーション内のすべてのリクエストのキャッシュを無効にするには、`withNoHttpTransferCache` 機能を使用します。

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoHttpTransferCache,
} from '@angular/platform-browser';

bootstrapApplication(AppComponent, {
  providers: [provideClientHydration(withNoHttpTransferCache())],
});
```

#### `filter` {#filter}

`withHttpTransferCacheOptions` の [`filter`](api/common/http/HttpTransferCacheOptions) オプションを使用して、特定のリクエストのキャッシュを選択的に無効にできます。たとえば、特定のAPIエンドポイントのキャッシュを無効にできます。

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

bootstrapApplication(AppComponent, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        filter: (req) => !req.url.includes('/api/sensitive-data'),
      }),
    ),
  ],
});
```

このオプションを使用して、ユーザー固有または動的なデータ(例: `/api/profile`)を持つエンドポイントを除外します。

#### 個別 {#individually}

個々のリクエストのキャッシュを無効にするには、`HttpRequest` で [`transferCache`](api/common/http/HttpRequest#transferCache) オプションを指定できます。

```ts
httpClient.get('/api/sensitive-data', {transferCache: false});
```

NOTE: アプリケーションがサーバーとクライアントで異なるHTTPオリジンを使用してAPIコールを行う場合、`HTTP_TRANSFER_CACHE_ORIGIN_MAP`トークンを使用してそれらのオリジン間のマッピングを確立できます。これにより、`HttpTransferCache`機能がそれらのリクエストを同じものとして認識し、クライアントでのハイドレーション中にサーバーでキャッシュされたデータを再利用できます。

## サーバーの設定 {#configuring-a-server}

### Node.js {#node-js}

`@angular/ssr/node` は、Node.js環境向けに `@angular/ssr` を拡張したものです。Node.jsアプリケーション内でサーバーサイドレンダリングを実装しやすくするAPIを提供します。関数と使用例の完全なリストについては、[`@angular/ssr/node` APIリファレンス](api/ssr/node/AngularNodeAppEngine) を参照してください。

```ts
// server.ts
import {
  AngularNodeAppEngine,
  createNodeRequestHandler,
  writeResponseToNodeResponse,
} from '@angular/ssr/node';
import express from 'express';

const app = express();
const angularApp = new AngularNodeAppEngine();

app.use('*', (req, res, next) => {
  angularApp
    .handle(req)
    .then((response) => {
      if (response) {
        writeResponseToNodeResponse(response, res);
      } else {
        next(); // 次のミドルウェアに制御を渡す
      }
    })
    .catch(next);
});

/**
 * Angular CLI (開発サーバーおよびビルド時) で使用されるリクエストハンドラー。
 */
export const reqHandler = createNodeRequestHandler(app);
```

### Node.js以外 {#non-node-js}

`@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
// 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.render(req);

// ...
});
```
# ハイドレーション

## ハイドレーションとは {#what-is-hydration}

ハイドレーションとは、サーバーサイドでレンダリングされたアプリケーションをクライアントで復元するプロセスです。これには、サーバーでレンダリングされたDOM構造の再利用、アプリケーション状態の永続化、サーバーによってすでに取得されたアプリケーションデータの転送、その他のプロセスが含まれます。

## ハイドレーションが重要な理由 {#why-is-hydration-important}

ハイドレーションは、DOMノードの再作成という余分な作業を回避することで、アプリケーションのパフォーマンスを向上させます。Angularは実行時に既存のDOM要素をアプリケーションの構造に一致させようとし、可能な場合はDOMノードを再利用します。これにより、First Input Delay ([FID](https://web.dev/fid/)) やLargest Contentful Paint ([LCP](https://web.dev/lcp/))、Cumulative Layout Shift ([CLS](https://web.dev/cls/)) の削減など、[Core Web Vitals (CWV)](https://web.dev/learn-core-web-vitals/) の統計を使用して測定できるパフォーマンスが向上します。これらの数値を改善することは、SEOパフォーマンスなどにも良い影響を与えます。

ハイドレーションが有効になっていない場合、サーバーサイドでレンダリングされたAngularアプリケーションは、アプリケーションのDOMを破棄して再レンダリングするため、目に見えるUIのちらつきが発生する場合があります。この再レンダリングは、[LCP](https://web.dev/lcp/) などの [Core Web Vitals](https://web.dev/learn-core-web-vitals/) に悪影響を与え、レイアウトシフトを引き起こす可能性があります。ハイドレーションを有効にすると、既存のDOMを再利用でき、ちらつきを防ぎます。

## Angularでハイドレーションを有効にする方法 {#how-do-you-enable-hydration-in-angular}

ハイドレーションは、サーバーサイドレンダリング (SSR) アプリケーションでのみ有効にできます。まず、[Angular SSRガイド](guide/ssr)に従ってサーバーサイドレンダリングを有効にしてください。

### Angular CLIを使用する {#using-angular-cli}

Angular CLIを使用してSSRを有効にした場合 (アプリケーション作成時、または後で `ng add @angular/ssr` を介して有効にした場合)、ハイドレーションを有効にするコードはすでにアプリケーションに含まれているはずです。

### 手動セットアップ {#manual-setup}

カスタムセットアップを使用しており、Angular CLIを使用してSSRを有効にしなかった場合は、メインアプリケーションコンポーネントまたはモジュールにアクセスし、`@angular/platform-browser` から `provideClientHydration` をインポートすることで、手動でハイドレーションを有効にできます。その後、そのプロバイダーをアプリケーションのブートストラッププロバイダーリストに追加します。

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
} from '@angular/platform-browser';
...

bootstrapApplication(AppComponent, {
  providers: [provideClientHydration()]
});
```

あるいは、NgModulesを使用している場合は、ルートアプリケーションモジュールのプロバイダーリストに `provideClientHydration` を追加します。

```typescript
import {provideClientHydration} from '@angular/platform-browser';
import {NgModule} from '@angular/core';

@NgModule({
  declarations: [AppComponent],
  exports: [AppComponent],
  bootstrap: [AppComponent],
  providers: [provideClientHydration()],
})
export class AppModule {}
```

IMPORTANT: `provideClientHydration()` の呼び出しが、**サーバー**でアプリケーションをブートストラップするために使用されるプロバイダーセットにも含まれていることを確認してください。デフォルトのプロジェクト構造 ( `ng new` コマンドで生成されたもの) を持つアプリケーションでは、このモジュールはサーバーモジュールによってインポートされるため、ルート `AppModule` への呼び出しを追加するだけで十分です。カスタムセットアップを使用している場合は、サーバーブートストラップ設定のプロバイダーリストに `provideClientHydration()` の呼び出しを追加してください。

### ハイドレーションが有効になっていることを確認する {#verify-that-hydration-is-enabled}

ハイドレーションを設定し、サーバーを起動したら、ブラウザでアプリケーションをロードします。

HELPFUL: Angularの構成要素に切り替えるか、`ngSkipHydration` を使用して、ハイドレーションが完全に機能する前に、DOMの直接操作のインスタンスを修正する必要があるでしょう。詳細については、[制約](#constraints)、[DOMの直接操作](#direct-dom-manipulation)、および[特定のコンポーネントのハイドレーションをスキップする方法](#how-to-skip-hydration-for-particular-components)を参照してください。

開発モードでアプリケーションを実行している間は、ブラウザで開発者ツールを開き、コンソールを表示することで、ハイドレーションが有効になっていることを確認できます。ハイドレーションされたコンポーネントとノードの数など、ハイドレーション関連の統計を含むメッセージが表示されるはずです。Angularは、サードパーティライブラリから提供されるものを含め、ページにレンダリングされたすべてのコンポーネントに基づいて統計を計算します。

[Angular DevToolsブラウザ拡張機能](tools/devtools)を使用して、ページのコンポーネントのハイドレーションステータスを確認できます。Angular DevToolsでは、ページのどの部分がハイドレーションされたかを示すオーバーレイを有効にもできます。ハイドレーションの不一致エラーがある場合、DevToolsはエラーの原因となったコンポーネントも強調表示します。

## イベントのキャプチャとリプレイ {#capturing-and-replaying-events}

アプリケーションがサーバーでレンダリングされると、生成されたHTMLがロードされ次第、ブラウザに表示されます。ユーザーはページを操作できると考えるかもしれませんが、ハイドレーションが完了するまでイベントリスナーはアタッチされません。v18以降では、ハイドレーションの前に発生したすべてのイベントをキャプチャし、ハイドレーションが完了した後にそれらのイベントをリプレイできるようにするイベントリプレイ機能を有効にできます。たとえば、`withEventReplay()` 関数を使用して有効にできます。

```typescript
import {provideClientHydration, withEventReplay} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withEventReplay())],
});
```

### イベントリプレイの仕組み {#how-event-replay-works}

イベントリプレイは、ハイドレーションプロセスが完了する前にトリガーされたユーザーイベントをキャプチャすることで、ユーザー体験を向上させる機能です。その後、それらのイベントがリプレイされ、インタラクションが失われないようにします。

イベントリプレイは主に3つのフェーズに分かれています。

- **ユーザーインタラクションのキャプチャ**<br>
  **ハイドレーション**の前に、イベントリプレイは、クリックやその他のブラウザネイティブイベントなど、ユーザーが行う可能性のあるすべてのインタラクションをキャプチャして保存します。

- **イベントの保存**<br>
  **イベントコントラクト**は、前のステップで記録されたすべてのインタラクションをメモリに保持し、後でリプレイするために失われないようにします。

- **イベントの再実行**<br>
  **ハイドレーション**が完了すると、Angularはキャプチャされたイベントを再呼び出しします。

イベントリプレイは、`click`、`mouseover`、`focusin` などの _ネイティブブラウザイベント_ をサポートしています。イベントリプレイを強化するライブラリであるJSActionについて詳しく知りたい場合は、[readme](https://github.com/angular/angular/tree/main/packages/core/primitives/event-dispatch#readme) を参照してください。

---

この機能は、ハイドレーションの前に実行されたユーザーアクションが無視されるのを防ぎ、一貫したユーザー体験を保証します。NOTE: [インクリメンタルハイドレーション](guide/incremental-hydration)を有効にしている場合、イベントリプレイは内部的に自動で有効になります。

## 制約 {#constraints}

ハイドレーションは、ハイドレーションが有効になっていない場合には存在しないいくつかの制約をアプリケーションに課します。アプリケーションは、サーバーとクライアントの両方で同じ生成されたDOM構造を持つ必要があります。ハイドレーションのプロセスは、DOMツリーが両方の場所で同じ構造を持つことを期待します。これには、Angularがサーバーでのレンダリング中に生成する空白やコメントノードも含まれます。これらの空白やノードは、サーバーサイドレンダリングプロセスによって生成されたHTMLに存在する必要があります。

IMPORTANT: サーバーサイドレンダリング操作によって生成されたHTMLは、サーバーとクライアントの間で変更されてはなりません。

サーバーとクライアントのDOMツリー構造に不一致がある場合、ハイドレーションプロセスは、期待されたものと実際にDOMに存在するものを一致させようとするときに問題に遭遇します。ネイティブDOM APIを使用してDOMを直接操作するコンポーネントが最も一般的な原因です。

### DOMの直接操作 {#direct-dom-manipulation}

ネイティブDOM APIを使用してDOMを操作したり、`innerHTML` または `outerHTML` を使用したりするコンポーネントがある場合、ハイドレーションプロセスはエラーに遭遇します。DOM操作が問題となる具体的なケースは、`document` へのアクセス、特定の要素のクエリ、`appendChild` を使用した追加ノードの注入などです。DOMノードをデタッチして別の場所に移動することもエラーにつながります。

これは、AngularがこれらのDOM変更を認識せず、ハイドレーションプロセス中にそれらを解決できないためです。Angularは特定の構造を期待しますが、ハイドレーションを試みるときに異なる構造に遭遇します。この不一致はハイドレーションの失敗につながり、DOM不一致エラー ([下記参照](#errors)) をスローします。

このようなDOM操作を避けるために、コンポーネントをリファクタリングするのが最善です。可能であれば、Angular APIを使用して作業してください。この動作をリファクタリングできない場合は、ハイドレーションに適したソリューションにリファクタリングできるまで、`ngSkipHydration` 属性 ([下記参照](#how-to-skip-hydration-for-particular-components)) を使用してください。

### 有効なHTML構造 {#valid-html-structure}

コンポーネントテンプレートに有効なHTML構造がない場合、ハイドレーション中にDOM不一致エラーが発生する可能性のあるケースがいくつかあります。

例として、この問題の最も一般的なケースをいくつか示します。

- `<tbody>` のない `<table>`
- `<p>` 内の `<div>`
- 別の `<a>` 内の `<a>`

HTMLが有効かどうか不明な場合は、[構文バリデーター](https://validator.w3.org/)を使用して確認できます。

NOTE: HTML標準ではテーブル内に `<tbody>` 要素を必須としていませんが、最新のブラウザは `<tbody>` を宣言していないテーブルに自動的に `<tbody>` 要素を作成します。この不整合のため、ハイドレーションエラーを避けるために、テーブルでは常に `<tbody>` 要素を明示的に宣言してください。

### preserveWhitespaces設定 {#preserve-whitespaces-configuration}

ハイドレーション機能を使用する場合、`preserveWhitespaces` のデフォルト設定である `false` を使用することをお勧めします。この設定がtsconfigにない場合、値は `false` であり、変更は不要です。`preserveWhitespaces: true` をtsconfigに追加して空白の保持を有効にすることを選択した場合、ハイドレーションで問題が発生する可能性があります。これはまだ完全にサポートされている構成ではありません。

HELPFUL: この設定が、サーバーの `tsconfig.server.json` とブラウザビルドの `tsconfig.app.json` で**一貫して**設定されていることを確認してください。値が一致しないと、ハイドレーションが壊れます。

この設定をtsconfigで設定することを選択した場合、デフォルトで `tsconfig.server.json` が継承する `tsconfig.app.json` のみに設定することをお勧めします。

### カスタムまたはNoop Zone.jsはまだサポートされていません {#custom-or-oop-zonejs-are-not-yet-supported}

ハイドレーションは、アプリケーション内でZone.jsが安定したときにZone.jsからのシグナルに依存しており、これによりAngularはサーバーでシリアル化プロセスを開始したり、クライアントでハイドレーション後のクリーンアップを実行して未請求のDOMノードを削除したりできます。

カスタムまたは「noop」Zone.jsの実装を提供すると、「安定」イベントのタイミングが異なり、シリアル化またはクリーンアップが早すぎたり遅すぎたりする可能性があります。これはまだ完全にサポートされている構成ではなく、カスタムZone.js実装の `onStable` イベントのタイミングを調整する必要がある場合があります。

## エラー {#errors}

ノードの不一致から、`ngSkipHydration` が無効なホストノードで使用されたケースまで、ハイドレーション関連のいくつかのエラーに遭遇する可能性があります。最も一般的なエラーケースは、ネイティブAPIを使用したDOMの直接操作が原因で発生するもので、ハイドレーションがサーバーによってレンダリングされたクライアント上の期待されるDOMツリー構造を見つけたり一致させたりできないというものです。この種のエラーに遭遇するもう1つのケースは、以前の[有効なHTML構造](#valid-html-structure)セクションで述べました。したがって、テンプレート内のHTMLが有効な構造を使用していることを確認すれば、そのエラーケースを回避できます。

ハイドレーション関連のエラーの完全なリファレンスについては、[エラーリファレンスガイド](/errors)を参照してください。

## 特定のコンポーネントのハイドレーションをスキップする方法 {#how-to-skip-hydration-for-particular-components}

一部のコンポーネントは、[DOMの直接操作](#direct-dom-manipulation)のような前述の問題により、ハイドレーションが有効になっていると正しく機能しない場合があります。回避策として、コンポーネントのタグに `ngSkipHydration` 属性を追加して、コンポーネント全体のハイドレーションをスキップできます。

```html
<app-example ngSkipHydration />
```

あるいは、`ngSkipHydration` をホストバインディングとして設定できます。

```typescript
@Component({
  ...
  host: {ngSkipHydration: 'true'},
})
class ExampleComponent {}
```

`ngSkipHydration` 属性は、Angularにコンポーネント全体とその子孫のハイドレーションをスキップさせます。この属性を使用すると、コンポーネントはハイドレーションが有効になっていないかのように動作し、自身を破棄して再レンダリングします。

HELPFUL: これによりレンダリングの問題は修正されますが、このコンポーネント (およびその子孫) ではハイドレーションの恩恵を受けられないことを意味します。ハイドレーションを壊すパターン (例: DOMの直接操作) を避けるために、コンポーネントの実装を調整して、ハイドレーションスキップのアノテーションを削除できるようにする必要があります。

`ngSkipHydration` 属性は、コンポーネントのホストノードでのみ使用できます。この属性が他のノードに追加された場合、Angularはエラーをスローします。

ルートアプリケーションコンポーネントに `ngSkipHydration` 属性を追加すると、アプリケーション全体のハイドレーションが実質的に無効になることに注意してください。この属性の使用には注意と検討が必要です。これは最後の手段の回避策として意図されています。ハイドレーションを壊すコンポーネントは、修正が必要なバグと見なされるべきです。

## ハイドレーションのタイミングとアプリケーションの安定性 {#hydration-timing-and-application-stability}

アプリケーションの安定性は、ハイドレーションプロセスにおいて重要な部分です。ハイドレーションおよびハイドレーション後のプロセスは、アプリケーションが安定性を報告した後にのみ発生します。安定性が遅延する可能性のある方法はいくつかあります。例としては、タイムアウトとインターバルの設定、未解決のPromise、保留中のマイクロタスクなどがあります。これらの場合、アプリケーションが10秒後に安定状態に達していないことを示す [アプリケーションが不安定なままです](errors/NG0506) エラーに遭遇する可能性があります。アプリケーションがすぐにハイドレーションされない場合は、アプリケーションの安定性に影響を与えているものを見直し、これらの遅延を引き起こさないようにリファクタリングしてください。

### アプリケーションの安定性のデバッグ {#debugging-application-stability}

`provideStabilityDebugging` ユーティリティは、アプリケーションが安定化に失敗する理由を特定するのに役立ちます。このユーティリティは、`provideClientHydration` を使用する場合、devモードではデフォルトで提供されます。また、本番バンドルで使用したり、たとえばハイドレーションなしでSSRを使用する場合に、アプリケーションプロバイダーに手動で追加できます。この機能は、予想よりもアプリケーションの安定化に時間がかかる場合、コンソールに情報をログ出力します。

```typescript
import {provideStabilityDebugging} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';
import 'zone.js/plugins/task-tracking'; // `provideZoneChangeDetection` でZone.jsを使用している場合に使用

bootstrapApplication(AppComponent, {
  providers: [provideStabilityDebugging()],
});
```

有効にすると、ユーティリティは保留中のタスク（`PendingTasks`）をコンソールにログ出力します。アプリケーションでZone.jsを使用している場合は、`zone.js/plugins/task-tracking` をインポートして、AngularゾーンがUnstableになる原因となっているマクロタスクを確認できます。このプラグインは、マクロタスク作成のスタックトレースを提供し、遅延の原因を効果的に特定するのに役立ちます。

IMPORTANT: Angularは、zone.jsタスクトラッキングプラグインやこのユーティリティを本番バンドルから削除しません。これらは、最適化された本番ビルドを含む、開発中の安定性の問題を一時的にデバッグするためにのみ使用してください。

## I18N {#i18n}

HELPFUL: デフォルトでは、Angularはi18nブロックを使用するコンポーネントのハイドレーションをスキップし、それらのコンポーネントを最初から再レンダリングします。

i18nブロックのハイドレーションを有効にするには、`provideClientHydration` の呼び出しに [`withI18nSupport`](/api/platform-browser/withI18nSupport) を追加します。

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withI18nSupport,
} from '@angular/platform-browser';
...

bootstrapApplication(AppComponent, {
  providers: [provideClientHydration(withI18nSupport())]
});
```

## サーバーサイドとクライアントサイドでの一貫したレンダリング {#consistent-rendering-across-server-side-and-client-side}

サーバーサイドレンダリング時とクライアントサイドレンダリング時で異なるコンテンツを表示する `@if` ブロックやその他の条件分岐 (Angularの `isPlatformBrowser` 関数を `@if` ブロックで使用するなど) を導入することは避けてください。これらのレンダリングの違いはレイアウトシフトを引き起こし、ユーザー体験とCore Web Vitalsに悪影響を与えます。

## DOM操作を伴うサードパーティライブラリ {#third-party-libraries-with-dom-manipulation}

レンダリングのためにDOM操作に依存するサードパーティライブラリが多数存在します。D3チャートはその典型的な例です。これらのライブラリはハイドレーションなしでは機能しましたが、ハイドレーションが有効な場合はDOM不一致エラーを引き起こす可能性があります。現時点では、これらのライブラリのいずれかを使用してDOM不一致エラーが発生した場合、そのライブラリを使用してレンダリングするコンポーネントに `ngSkipHydration` 属性を追加できます。

## DOM操作を伴うサードパーティスクリプト {#third-party-scripts-with-dom-manipulation}

広告トラッカーやアナリティクスなど、多くのサードパーティスクリプトは、ハイドレーションが行われる前にDOMを変更します。これらのスクリプトは、ページがAngularが期待する構造と一致しなくなるため、ハイドレーションエラーを引き起こす可能性があります。可能な限り、この種のスクリプトをハイドレーション後まで遅らせることを推奨します。[`AfterNextRender`](api/core/afterNextRender) を使用して、ハイドレーション後のプロセスが完了するまでスクリプトを遅延させることを検討してください。

## インクリメンタルハイドレーション {#incremental-hydration}

インクリメンタルハイドレーションは、ハイドレーションがいつ発生するかをよりきめ細かく制御できる、高度なハイドレーション形式です。詳細については、[インクリメンタルハイドレーションガイド](guide/incremental-hydration)を参照してください。
# インクリメンタルハイドレーション

**インクリメンタルハイドレーション**は、アプリケーションの一部を非ハイドレーション状態のままにし、必要に応じてそれらのセクションのハイドレーションを*段階的に*トリガーできる、高度なタイプの[ハイドレーション](guide/hydration)です。

## インクリメンタルハイドレーションを使用する理由

インクリメンタルハイドレーションは、完全なアプリケーションハイドレーションを基盤としたパフォーマンス向上策です。完全なアプリケーションハイドレーションと同等のエンドユーザー体験を提供しながら、より小さな初期バンドルを作成できます。バンドルサイズが小さくなると、初期ロード時間が短縮され、[First Input Delay (FID)](https://web.dev/fid)と[Cumulative Layout Shift (CLS)](https://web.dev/cls)が改善されます。

インクリメンタルハイドレーションを使用すると、以前は遅延できなかった可能性のあるコンテンツに遅延可能ビュー(`@defer`)を使用できるようになります。具体的には、画面の上部に表示されるコンテンツに遅延可能ビューを使用できるようになりました。インクリメンタルハイドレーション以前は、画面の上部に`@defer`ブロックを配置すると、プレースホルダーコンテンツがレンダリングされ、その後`@defer`ブロックのメインテンプレートコンテンツに置き換えられます。これにより、レイアウトシフトが発生します。インクリメンタルハイドレーションを使用すると、`@defer`ブロックのメインテンプレートは、ハイドレーション時にレイアウトシフトなしでレンダリングされます。

## Angularでインクリメンタルハイドレーションを有効にする方法

ハイドレーションによるサーバーサイドレンダリング(SSR)を既に使用しているアプリケーションでインクリメンタルハイドレーションを有効にできます。サーバーサイドレンダリングを有効にするには[Angular SSRガイド](guide/ssr)を、ハイドレーションを有効にするには[Angularハイドレーションガイド](guide/hydration)を参照してください。

`provideClientHydration`プロバイダーに`withIncrementalHydration()`関数を追加することで、インクリメンタルハイドレーションを有効にします。

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withIncrementalHydration,
} from '@angular/platform-browser';
...

bootstrapApplication(AppComponent, {
  providers: [provideClientHydration(withIncrementalHydration())]
});
```

インクリメンタルハイドレーションは[イベントリプレイ](guide/hydration#capturing-and-replaying-events)に依存し、自動的に有効にします。既にリストに`withEventReplay()`がある場合は、インクリメンタルハイドレーションを有効にした後、安全に削除できます。

## インクリメンタルハイドレーションの動作方法

インクリメンタルハイドレーションは、完全なアプリケーション[ハイドレーション](guide/hydration)、[遅延可能ビュー](guide/defer)、および[イベントリプレイ](guide/hydration#capturing-and-replaying-events)を基盤として構築されています。インクリメンタルハイドレーションを使用すると、インクリメンタルハイドレーションの境界を定義する`@defer`ブロックに追加のトリガーを追加できます。`defer`ブロックに`hydrate`トリガーを追加すると、Angularはサーバーサイドレンダリング中にその`defer`ブロックの依存関係をロードし、`@placeholder`ではなくメインテンプレートをレンダリングする必要があることを認識します。クライアントサイドレンダリングの場合、依存関係はまだ遅延され、`hydrate`トリガーが起動するまで`defer`ブロックのコンテンツは非ハイドレーション状態のままです。そのトリガーは、`defer`ブロックに依存関係を取得してコンテンツをハイドレーションするよう指示します。ハイドレーションの前にユーザーによってトリガーされたブラウザイベント、特にコンポーネントに登録されたリスナーと一致するイベントは、キューに入れられ、ハイドレーションプロセスが完了すると再生されます。

## トリガーによるコンテンツのハイドレーション制御

Angularが遅延コンテンツをロードしてハイドレーションするタイミングを制御する**ハイドレーショントリガー**を指定できます。これらは、通常の`@defer`トリガーとともに使用できる追加のトリガーです。

各`@defer`ブロックには、セミコロン(`;`)で区切られた複数のハイドレーションイベントトリガーを含めることができます。Angularは、いずれかのトリガーが起動するとハイドレーションを開始します。

ハイドレーショントリガーには、`hydrate on`、`hydrate when`、`hydrate never`の3種類があります。

### `hydrate on`

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

`hydrate on idle`トリガーは、`requestIdleCallback`に基づいてブラウザがアイドル状態に達すると、遅延可能ビューの依存関係をロードし、コンテンツをハイドレーションします。

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

#### `hydrate on viewport`

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

`hydrate on interaction`トリガーは、ユーザーが`click`または`keydown`イベントを通じて指定された要素と対話したときに、
遅延可能ビューの依存関係をロードし、コンテンツをハイドレーションします。

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

#### `hydrate on hover`

`hydrate on hover`トリガーは、`mouseover`および`focusin`イベントを通じてマウスがトリガー領域にホバーしたときに、
遅延可能ビューの依存関係をロードし、コンテンツをハイドレーションします。

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

#### `hydrate on immediate`

`hydrate on immediate`トリガーは、遅延可能ビューの依存関係をロードし、すぐにコンテンツをハイドレーションします。
これは、他のすべての非遅延コンテンツのレンダリングが完了するとすぐに、遅延ブロックがロードされることを意味します。

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

#### `hydrate on timer`

`hydrate on timer`トリガーは、指定された期間後に遅延可能ビューの依存関係をロードし、コンテンツをハイドレーションします。

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

期間パラメーターは、ミリ秒(`ms`)または秒(`s`)で指定する必要があります。

### `hydrate when`

`hydrate when`トリガーはカスタムの条件式を受け入れ、条件が真になったときに
遅延可能ビューの依存関係をロードし、コンテンツをハイドレーションします。

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

NOTE: `hydrate when`条件は、最上位の非ハイドレーション`@defer`ブロックである場合にのみトリガーされます。
トリガーに提供される条件は親コンポーネントで指定され、トリガーされる前に存在する必要があります。
親ブロックが非ハイドレーション状態の場合、その式はまだAngularによって解決できません。

### `hydrate never`

`hydrate never`を使用すると、`defer`ブロック内のコンテンツを無期限に非ハイドレーション状態のままにでき、事実上静的コンテンツになります。
これは最初のレンダリングにのみ適用されることに注意してください。
後続のクライアントサイドレンダリングでは、`hydrate never`を含む`@defer`ブロックは依存関係をロードします。ハイドレーションはサーバーサイドレンダリングされたコンテンツの最初のロードにのみ適用されるためです。
次の例では、後続のクライアントサイドレンダリングでは、ビューポートで`@defer`ブロックの依存関係がロードされます。

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

NOTE: `hydrate never`を使用すると、指定された`@defer`ブロックのネストされたサブツリー全体のハイドレーションが防止されます。そのブロックの下にネストされたコンテンツに対しては、他の`hydrate`トリガーは起動しません。

## 通常のトリガーとハイドレーショントリガーの併用

ハイドレーショントリガーは、`@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のコンポーネントと依存関係のシステムは階層的であるため、コンポーネントをハイドレーションするには、そのすべての親もハイドレーションされている必要があります。したがって、ネストされた非ハイドレーション`@defer`ブロックのセットの子`@defer`ブロックでハイドレーションがトリガーされた場合、ハイドレーションは最上位の非ハイドレーション`@defer`ブロックからトリガーされた子まで順にトリガーされ、その順序で実行されます。

```html
@defer (hydrate on interaction) {
  <parent-block-cmp />
  @defer (hydrate on hover) {
    <child-block-cmp />
  } @placeholder {
    <div>Child placeholder</div>
  }
} @placeholder{
  <div>Parent Placeholder</div>
}
```

上記の例では、ネストされた`@defer`ブロックにホバーするとハイドレーションがトリガーされます。`<parent-block-cmp />`を含む親`@defer`ブロックが最初にハイドレーションされ、その後`<child-block-cmp />`を含む子`@defer`ブロックがハイドレーションされます。

## 制約事項

インクリメンタルハイドレーションには、完全なアプリケーションハイドレーションと同じ制約事項があり、直接的なDOM操作の制限や有効なHTML構造の必要性などが含まれます。詳細については、[ハイドレーションガイドの制約事項](guide/hydration#constraints)セクションを参照してください。

## `@placeholder`ブロックはまだ指定する必要がありますか？

はい。`@placeholder`ブロックのコンテンツはインクリメンタルハイドレーションには使用されませんが、後続のクライアントサイドレンダリングの場合には`@placeholder`が必要です。コンテンツが最初のロードの一部であったルートにない場合、`@defer`ブロックコンテンツを持つルートへのナビゲーションは、通常の`@defer`ブロックのようにレンダリングされます。そのため、`@placeholder`はこれらのクライアントサイドレンダリングの場合にレンダリングされます。
# ユニットテスト

Angularアプリケーションをテストすると、期待どおりに動作していることを確認できます。ユニットテストは、バグを早期に発見し、コード品質を確保し、安全なリファクタリングを促進するために不可欠です。

NOTE: このガイドでは、Vitestを使用した新しいAngular CLIプロジェクトのデフォルトテスト設定について説明します。既存のプロジェクトをKarmaから移行する場合は、[KarmaからVitestへの移行ガイド](guide/testing/migrating-to-vitest)を参照してください。Karmaは引き続きサポートされています。詳細については、[Karmaテストガイド](guide/testing/karma)を参照してください。

## テストの設定 {#set-up-for-testing}

Angular CLIは、[Vitestテストフレームワーク](https://vitest.dev)を使用してAngularアプリケーションをテストするために必要なものをすべてダウンロードしてインストールします。新しいプロジェクトには、デフォルトで`vitest`と`jsdom`が含まれています。

Vitestは、Node.js環境でユニットテストを実行します。ブラウザのDOMをシミュレートするために、Vitestは`jsdom`というライブラリを使用します。これにより、ブラウザを起動するオーバーヘッドを回避して、テストの実行を高速化できます。`happy-dom`のような代替手段に`jsdom`を置き換えることもできます。`happy-dom`をインストールして`jsdom`をアンインストールすれば、置き換えられます。現在、`jsdom`と`happy-dom`がサポートされているDOMエミュレーションライブラリです。

CLIで作成したプロジェクトは、すぐにテストできます。[`ng test`](cli/test)コマンドを実行します:

```shell
ng test
```

`ng test`コマンドはアプリケーションを_監視モード_でビルドし、[Vitestテストランナー](https://vitest.dev)を起動します。

コンソールの出力は次のようになります:

```shell
✓ src/app/app.spec.ts (3)
   ✓ AppComponent should create the app
   ✓ AppComponent should have as title 'my-app'
   ✓ AppComponent should render title
 Test Files  1 passed (1)
      Tests  3 passed (3)
   Start at  18:18:01
   Duration  2.46s (transform 615ms, setup 2ms, collect 2.21s, tests 5ms)
```

`ng test`コマンドは、ファイルの変更も監視します。ファイルを変更して保存すると、テストが再び実行されます。

## 設定 {#configuration}

Angular CLIは、Vitestの設定のほとんどを処理します。`angular.json`ファイルの`test`ターゲットオプションを変更することで、テストの動作をカスタマイズできます。

### Angular.jsonオプション {#angularjson-options}

- `include`: テストに含めるファイルのGlobパターン。デフォルトは`['**/*.spec.ts', '**/*.test.ts']`です。
- `exclude`: テストから除外するファイルのGlobパターン。
- `setupFiles`: テストの前に実行されるグローバルセットアップファイル（ポリフィルやグローバルモックなど）へのパスのリスト。
- `providersFile`: テスト環境用のAngularプロバイダーのデフォルト配列をエクスポートするファイルへのパス。これは、テストに注入されるグローバルテストプロバイダーをセットアップするのに役立ちます。
- `coverage`: コードカバレッジレポートを有効または無効にするブール値。デフォルトは`false`です。
- `browsers`: 実際のブラウザでテストを実行するブラウザ名の配列（例: `["chromium"]`）。ブラウザプロバイダーのインストールが必要です。詳細については、[ブラウザでのテストの実行](#running-tests-in-a-browser)セクションを参照してください。

### グローバルテスト設定とプロバイダー {#global-test-setup-and-providers}

`setupFiles`と`providersFile`オプションは、グローバルテスト設定を管理するのに特に役立ちます。

たとえば、`src/test-providers.ts`ファイルを作成して、すべてのテストに`provideHttpClientTesting`を提供できます:

```typescript
{header: "src/test-providers.ts"}
import {Provider} from '@angular/core';
import {provideHttpClient} from '@angular/common/http';
import {provideHttpClientTesting} from '@angular/common/http/testing';

const testProviders: Provider[] = [provideHttpClient(), provideHttpClientTesting()];

export default testProviders;
```

次に、このファイルを`angular.json`で参照します:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "providersFile": "src/test-providers.ts"
          }
        }
      }
    }
  }
}
```

HELPFUL: テスト設定やプロバイダー用に`src/test-providers.ts`のような新しいTypeScriptファイルを作成する場合は、プロジェクトのテスト用TypeScript設定ファイル（通常は`tsconfig.spec.json`）にそれらを含めるようにしてください。これにより、TypeScriptコンパイラがテスト中にこれらのファイルを適切に処理できるようになります。

### 高度なVitest設定 {#advanced-vitest-configuration}

高度なユースケースでは、`angular.json`の`configFile`オプションを使用してカスタムVitest設定ファイルを提供できます。

IMPORTANT: カスタム設定を使用すると高度なオプションが有効になりますが、Angularチームは設定ファイルの内容やサードパーティプラグインについてサポートを提供していません。また、CLIは適切な統合を保証するために特定のプロパティ（`test.projects`、`test.include`）を上書きします。

Vitest設定ファイル（例: `vitest-base.config.ts`）を作成し、`angular.json`で参照できます:

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "runnerConfig": "vitest-base.config.ts"
          }
        }
      }
    }
  }
}
```

CLIを使用して基本設定ファイルを生成できます:

```shell
ng generate config vitest
```

これにより、カスタマイズ可能な`vitest-base.config.ts`ファイルが作成されます。

HELPFUL: Vitestの設定について詳しくは、[Vitestの公式ドキュメント](https://vitest.dev/config/)を参照してください。

## コードカバレッジ {#code-coverage}

`ng test`コマンドに`--coverage`フラグを追加することで、コードカバレッジレポートを生成できます。レポートは`coverage/`ディレクトリに生成されます。

詳細については、[コードカバレッジガイド](guide/testing/code-coverage)を参照してください。

## ブラウザでのテストの実行 {#running-tests-in-a-browser}

デフォルトのNode.js環境はほとんどのユニットテストで高速ですが、実際のブラウザでテストを実行できます。これは、ブラウザ固有のAPI（レンダリングなど）に依存するテストやデバッグに役立ちます。

ブラウザでテストを実行するには、最初にブラウザプロバイダーをインストールする必要があります。Vitestのブラウザモードの詳細については、[公式ドキュメント](https://vitest.dev/guide/browser)を参照してください。

プロバイダーがインストールされたら、`angular.json`の`browsers`オプションを設定するか、`--browsers` CLIフラグを使用してブラウザでテストを実行できます。テストは、デフォルトではヘッドフルブラウザが使用されます。`CI`環境変数が設定されている場合は、代わりにヘッドレスモードが使用されます。ヘッドレスモードを明示的に制御するには、ブラウザ名に`Headless`をサフィックスとして追加できます（例: `chromiumHeadless`）。

```bash
# Playwrightの例（ヘッドフル）
ng test --browsers=chromium

# Playwrightの例（ヘッドレス）
ng test --browsers=chromiumHeadless

# WebdriverIOの例（ヘッドフル）
ng test --browsers=chrome

# WebdriverIOの例（ヘッドレス）
ng test --browsers=chromeHeadless
```

ニーズに基づいて、次のブラウザプロバイダーのいずれかを選択してください:

### Playwright

[Playwright](https://playwright.dev/)は、Chromium、Firefox、WebKitをサポートするブラウザ自動化ライブラリです。

```shell
// npm
npm install --save-dev @vitest/browser-playwright playwright
```
```shell
// yarn
yarn add --dev @vitest/browser-playwright playwright
```
```shell
// pnpm
pnpm add -D @vitest/browser-playwright playwright
```
```shell
// bun
bun add --dev @vitest/browser-playwright playwright
```
### WebdriverIO

[WebdriverIO](https://webdriver.io/)は、Chrome、Firefox、Safari、Edgeをサポートするブラウザとモバイル自動化テストフレームワークです。

```shell
// npm
npm install --save-dev @vitest/browser-webdriverio webdriverio
```
```shell
// yarn
yarn add --dev @vitest/browser-webdriverio webdriverio
```
```shell
// pnpm
pnpm add -D @vitest/browser-webdriverio webdriverio
```
```shell
// bun
bun add --dev @vitest/browser-webdriverio webdriverio
```
### Preview

`@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
```
HELPFUL: より高度なブラウザ固有の設定については、[高度なVitest設定](#advanced-vitest-configuration)セクションを参照してください。

## その他のテストフレームワーク {#other-test-frameworks}

Angularアプリケーションは、他のテストライブラリとテストランナーでもユニットテストできます。各ライブラリとランナーには、それぞれ独自のインストール手順、設定、構文があります。

## 継続的インテグレーションでのテスト {#testing-in-continuous-integration}

堅牢なテストスイートは、継続的インテグレーション（CI）パイプラインの重要な部分です。CIサーバーを使用すると、すべてのコミットとプルリクエストでテストを自動的に実行できます。

CIサーバーでAngularアプリケーションをテストするには、標準のテストコマンドを実行します:

```shell
ng test
```

ほとんどのCIサーバーは`CI=true`環境変数を設定しており、`ng test`はこれを検出します。これにより、非対話型のシングルランモードでテストが自動的に設定されます。

CIサーバーがこの変数を設定しない場合、または手動でシングルランモードを強制する必要がある場合は、`--no-watch`および`--no-progress`フラグを使用できます:

```shell
ng test --no-watch --no-progress
```

## テストに関する追加情報 {#more-information-on-testing}

アプリケーションのテストを設定したら、次のテストガイドが役立つ場合があります。

|                                                                    | 詳細                                                                           |
| :----------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| [コードカバレッジ](guide/testing/code-coverage)                       | テストがアプリケーションのどの部分をカバーしているか、および必要な量の指定方法。 |
| [サービスのテスト](guide/testing/services)                         | アプリケーションで使用しているサービスのテスト方法。                                   |
| [コンポーネントのテストの基本](guide/testing/components-basics)    | Angularコンポーネントのテストの基本。                                             |
| [コンポーネントテストシナリオ](guide/testing/components-scenarios)  | さまざまな種類のコンポーネントテストシナリオとユースケース。                       |
| [属性ディレクティブのテスト](guide/testing/attribute-directives) | 属性ディレクティブのテスト方法。                                            |
| [パイプのテスト](guide/testing/pipes)                               | パイプのテスト方法。                                                                |
| [テストのデバッグ](guide/testing/debugging)                         | 一般的なテストのバグ。                                                              |
| [ユーティリティAPIのテスト](guide/testing/utility-apis)                 | Angularのテスト機能。                                                         |
# コードカバレッジ {#code-coverage}

コードカバレッジレポートは、単体テストで適切にテストされていないコードベースの箇所を示します。

## 前提条件 {#prerequisites}

Vitestでコードカバレッジレポートを生成するには、`@vitest/coverage-v8` パッケージをインストールする必要があります。

```shell
// npm
npm install --save-dev @vitest/coverage-v8
```
```shell
// yarn
yarn add --dev @vitest/coverage-v8
```
```shell
// pnpm
pnpm add -D @vitest/coverage-v8
```
```shell
// bun
bun add --dev @vitest/coverage-v8
```
## レポートの生成 {#generating-a-report}

カバレッジレポートを生成するには、`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
          }
        }
      }
    }
  }
}
```

## コードカバレッジのしきい値の強制 {#enforcing-code-coverage-thresholds}

コードカバレッジのパーセンテージは、コードのどの程度がテストされているかを推定できます。チームが単体テストを行う最小限の量を決定した場合、構成でその最小限を強制できます。

たとえば、コードベースのコードカバレッジを最低80%にしたいとします。これを有効にするには、`angular.json` ファイルに `coverageThresholds` オプションを追加します。

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true,
            "coverageThresholds": {
              "statements": 80,
              "branches": 80,
              "functions": 80,
              "lines": 80
            }
          }
        }
      }
    }
  }
}
```

これで、テストを実行したときにカバレッジが80%を下回ると、コマンドは失敗します。

## 高度な設定 {#advanced-configuration}

`angular.json` ファイルで、他にもいくつかのカバレッジオプションを設定できます。

- `coverageInclude`: カバレッジレポートに含めるファイルのglobパターン。
- `coverageReporters`: 使用するレポーターの配列（例: `html`、`lcov`、`json`）。
- `coverageWatermarks`: HTMLレポーターの `[low, high]` ウォーターマークを指定するオブジェクト。レポートの色分けに影響を与える可能性があります。

```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テストユーティリティの助けを借りずに記述された `ValueService` の同期および非同期のユニットテストです。

```ts
describe('ValueService', () => {
  let service: ValueService;

beforeEach(() => {
    // Only works if the service doesn't rely on Angular inject()
    service = new ValueService();
  });

it('getValue should return real value', () => {
    expect(service.getValue()).toBe('real value');
  });

it('getObservableValue should return value from observable', async () => {
    const value = await new Promise<string>((resolve) => {
      service.getObservableValue().subscribe(resolve);
    });

expect(value).toBe('observable value');
  });

it('getPromiseValue should return value from a promise', async () => {
    const value = await service.getPromiseValue();
    expect(value).toBe('promise value');
  });
});
```

## `TestBed` を使用したサービスのテスト {#testing-services-with-the-testbed}

アプリケーションは、Angularの [依存関係注入 (DI)](guide/di) に依存してサービスを作成します。
サービスが依存サービスを持っている場合、DIはその依存サービスを見つけたり、作成します。
さらに、その依存サービスに独自の依存関係がある場合、DIはそれらも探し出して作成します。

サービスの _消費者_ として、あなたはこれらについて心配する必要はありません。
コンストラクター引数の順序や、それらがどのように作成されるかについて心配する必要はありません。

サービスの _テスター_ として、少なくともサービス依存関係の最初のレベルについて考える必要はありますが、`TestBed` テストユーティリティを使用してサービスを提供して作成し、コンストラクター引数の順序を処理するときは、Angular DIにサービスの作成を任せることができます。

## Angular `TestBed` {#angular-testbed}

`TestBed` は、Angularのテストユーティリティの中で最も重要なものです。
`TestBed` は、Angularの [@NgModule](guide/ngmodules) をエミュレートする、動的に構築されたAngularの _テスト_ モジュールを作成します。

`TestBed.configureTestingModule()` メソッドは、[@NgModule](guide/ngmodules) のほとんどのプロパティを持つことができるメタデータオブジェクトを受け取ります。

サービスをテストするには、テストまたはモックするサービスの配列を `providers` メタデータプロパティに設定します。

```ts
let service: ValueService;
beforeEach(() => {
  TestBed.configureTestingModule({providers: [ValueService]});
});
```

次に、サービスクラスを引数として `TestBed.inject()` を呼び出して、テスト内でサービスを注入します。

```ts
it('should use ValueService', () => {
  service = TestBed.inject(ValueService);
  expect(service.getValue()).toBe('real value');
});
```

または、セットアップの一部としてサービスを注入したい場合は、`beforeEach()` 内で行います。

```ts
beforeEach(() => {
  TestBed.configureTestingModule({providers: [ValueService]});
  service = TestBed.inject(ValueService);
});
```

依存関係のあるサービスをテストする場合は、`providers` 配列にモックを提供します。

次の例では、モックはスパイオブジェクトです。

```ts
let masterService: MainService;
let valueServiceSpy: Mocked<ValueService>;

beforeEach(() => {
  const spy: Mocked<ValueService> = {getValue: vi.fn()};

TestBed.configureTestingModule({
    providers: [MainService, {provide: ValueService, useValue: spy}],
  });

masterService = TestBed.inject(MainService);
  valueServiceSpy = TestBed.inject(ValueService) as Mocked<ValueService>;
});
```

テストでは、以前と同じように、そのスパイを使用します。

```ts
it('getValue should return stubbed value from a spy', () => {
  const stubValue = 'stub value';

valueServiceSpy.getValue.mockReturnValue(stubValue);

expect(masterService.getValue(), 'service returned stub value').toBe(stubValue);
  expect(valueServiceSpy.getValue, 'spy method was called once').toHaveBeenCalledTimes(1);
  expect(valueServiceSpy.getValue.mock.results.at(-1)?.value).toBe(stubValue);
});
```

## HTTP サービスのテスト {#testing-http-services}

`HttpClient`に依存するサービスのテストについては、[専用ガイド](/guide/http/testing)を参照してください。
# コンポーネントテストの基本

コンポーネントは、Angularアプリケーションの他のすべての部分とは異なり、HTMLテンプレートとTypeScriptクラスを組み合わせたものです。
コンポーネントは、実際にはテンプレートとクラスが _連携_ したものです。
コンポーネントを適切にテストするには、意図したとおりに連携して動作することをテストする必要があります。

このようなテストには、Angularと同様にブラウザのDOMにコンポーネントのホスト要素を作成し、そのテンプレートで記述されているように、DOMとのコンポーネントクラスの対話を調査することが必要です。

Angularの `TestBed` は、次のセクションで説明するように、この種類のテストを容易にします。
しかし、多くの場合、_DOM を伴わないコンポーネントクラス単独のテスト_ は、コンポーネントの動作の大部分を、より簡単で明らかな方法で検証できます。

## コンポーネント DOM テスト

コンポーネントは、そのクラスだけではありません。
コンポーネントはDOMと他のコンポーネントと対話します。
クラスだけでは、コンポーネントが正しくレンダリングされるか、ユーザーの入力やジェスチャーに応答するか、親コンポーネントと子コンポーネントと統合されるかを判断できません。

- `Lightswitch.clicked()` はユーザーが呼び出せるように何かとバインドされていますか？
- `Lightswitch.message` は表示されますか？
- ユーザーは `DashboardHero` コンポーネントによって表示されるヒーローを実際に選択できますか？
- ヒーローの名前は期待通り（たとえば、大文字）に表示されますか？
- `Welcome` コンポーネントのテンプレートによってウェルカムメッセージは表示されますか？

これらの質問は、説明した前の簡単なコンポーネントにとっては問題ないかもしれません。
しかし、多くのコンポーネントは、そのテンプレートで記述されているDOM要素との複雑な対話を持ち、コンポーネントの状態が変わるとHTMLが表示および非表示になります。

これらの質問に答えるには、コンポーネントに関連付けられたDOM要素を作成し、DOMを調べて適切なタイミングでコンポーネントの状態が正しく表示されていることを確認します。そしてユーザーが画面と対話するようにシミュレートして、それらの対話がコンポーネントが期待通りに動作するかどうかを判断する必要があります。

これらの種類のテストを書くには、`TestBed` の追加機能と、他のテストヘルパーを使用します。

### CLI で生成されたテスト

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 () => {
    await TestBed.configureTestingModule({
      imports: [Banner],
    }).compileComponents();

fixture = TestBed.createComponent(Banner);
    component = fixture.componentInstance;
    await fixture.whenStable();
  });

it('should create', () => {
    expect(component).toBeTruthy();
  });
});
```

### セットアップの削減

このファイルの最後の3行だけが実際にコンポーネントをテストしており、Angularがコンポーネントを作成できることをアサートするだけです。

ファイルの残りの部分は、コンポーネントが実質的なものへと進化した場合に必要になる _可能性のある_、より高度なテストを予期した定型文のセットアップコードです。

これらの高度なテスト機能については、次のセクションで説明します。
今のところ、このテストファイルをより管理しやすいサイズに大幅に縮小できます。

```ts
describe('Banner (minimal)', () => {
  it('should create', () => {
    const fixture = TestBed.createComponent(Banner);
    const component = fixture.componentInstance;
    expect(component).toBeDefined();
  });
});
```

後で `TestBed.configureTestingModule()` を呼び出して、インポート、プロバイダー、その他の宣言を追加して、テストのニーズに合わせて構成します。
オプションの `override` メソッドは、構成の側面をさらに微調整できます。

NOTE: `TestBed.compileComponents` は、テストされるコンポーネントで `@defer` ブロックが使用されている場合にのみ必要です。

### `createComponent()`

`TestBed` を構成したら、その `createComponent()` メソッドを呼び出します。

```ts
const fixture = TestBed.createComponent(Banner);
```

`TestBed.createComponent()` は `Banner` コンポーネントのインスタンスを作成し、対応する要素をテストランナーのDOMに追加し、[`ComponentFixture`](#componentfixture) を返します。

IMPORTANT: `createComponent` を呼び出した後に `TestBed` を再構成しないでください。

`createComponent` メソッドは、現在の `TestBed` 定義を凍結し、さらなる構成を締め切ります。

`configureTestingModule()` や `get()`、`override...` メソッドなど、`TestBed` の構成メソッドをさらに呼び出すことはできません。
呼び出そうとすると、`TestBed` はエラーをスローします。

### `ComponentFixture`

[`ComponentFixture`](api/core/testing/ComponentFixture) は、作成されたコンポーネントとその対応する要素を操作するためのテストハーネスです。

fixtureを介してコンポーネントインスタンスにアクセスし、期待を使用して存在を確認します。

```ts
const component = fixture.componentInstance;
expect(component).toBeDefined();
```

### `beforeEach()`

このコンポーネントが進化するにつれて、さらに多くのテストを追加するでしょう。
各テストのために `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(); // necessary to wait for the initial rendering
  });

it('should create', () => {
    expect(component).toBeDefined();
  });
});
```

HELPFUL: `beforeEach` で `await fixture.whenStable` を使用して初期レンダリングを待機することで、個別のテストは同期的になります。

次に、fixture.nativeElementからコンポーネントの要素を取得し、期待されるテキストを探すテストを追加します。

```ts
it('should contain "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  expect(bannerElement.textContent).toContain('banner works!');
});
```

### `setup` 関数の作成

`beforeEach` の代わりに、各テストで呼び出すsetup関数を作成できます。
setup関数は、パラメーターを介してカスタマイズできるという利点があります。

setup関数の例を次に示します。

```ts
function setup(providers?: StaticProviders[]): ComponentFixture<Banner> {
  TestBed.configureTestingModule({providers});
  return TestBed.createComponent(Banner);
}
```

### `nativeElement`

`ComponentFixture.nativeElement` の値は `any` 型です。
後で `DebugElement.nativeElement` に遭遇しますが、これも `any` 型です。

Angularは、コンパイル時に `nativeElement` がどのようなHTML要素であるか、あるいはHTML要素であるかどうかすらを知ることができません。
アプリケーションは、サーバーやNode環境などの _非ブラウザープラットフォーム_ で実行されている可能性があり、その場合、要素のAPIが制限されているか、存在しない可能性があります。

このガイドのテストはブラウザで実行されるように設計されているため、`nativeElement` の値は常に `HTMLElement` またはその派生クラスのいずれかになります。

それが何らかの `HTMLElement` であることを知っているので、標準のHTML `querySelector` を使用して、要素ツリーをさらに深く掘り下げます。

次に、`HTMLElement.querySelector` を呼び出して段落要素を取得し、バナーテキストを探すテストを示します。

```ts
it('should have <p> with "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  const p = bannerElement.querySelector('p')!;
  expect(p.textContent).toEqual('banner works!');
});
```

### `DebugElement`

Angularの _fixture_ は、`fixture.nativeElement` を介してコンポーネントの要素を直接提供します。

```ts
const bannerElement: HTMLElement = fixture.nativeElement;
```

これは実際には、`fixture.debugElement.nativeElement` として実装された便利なメソッドです。

```ts
const bannerDe: DebugElement = fixture.debugElement;
const bannerEl: HTMLElement = bannerDe.nativeElement;
```

この回りくどい要素へのパスには、正当な理由があります。

`nativeElement` のプロパティは、実行時環境によって異なります。
これらのテストは、DOMがないか、DOMエミュレーションが完全な `HTMLElement` APIをサポートしていない _非ブラウザープラットフォーム_ で実行されている可能性があります。

Angularは、_すべてのサポートされているプラットフォーム_ で安全に動作するために、`DebugElement` 抽象化に依存しています。
AngularはHTML要素ツリーを作成するのではなく、実行時プラットフォームの _ネイティブ要素_ をラップする `DebugElement` ツリーを作成します。
`nativeElement` プロパティは `DebugElement` をラップ解除し、プラットフォーム固有の要素オブジェクトを返します。

このガイドのサンプルテストはブラウザでのみ実行されるように設計されているため、これらのテストの `nativeElement` は常に `HTMLElement` であり、そのおなじみのメソッドとプロパティはテスト内で調べることができます。

次に、`fixture.debugElement.nativeElement` を使用して再実装された前のテストを示します。

```ts
it('should find the <p> with fixture.debugElement.nativeElement', () => {
  const bannerDe: DebugElement = fixture.debugElement;
  const bannerEl: HTMLElement = bannerDe.nativeElement;
  const p = bannerEl.querySelector('p')!;
  expect(p.textContent).toEqual('banner works!');
});
```

`DebugElement` には、このガイドの他の場所で説明されているように、テストで役立つ他のメソッドとプロパティがあります。

Angularコアライブラリから `DebugElement` シンボルをインポートします。

```ts
import {DebugElement} from '@angular/core';
```

### `By.css()`

このガイドのテストはすべてブラウザで実行されますが、一部のアプリケーションは少なくとも一部の時間を別のプラットフォームで実行することがあります。

たとえば、コンポーネントは、接続の悪いデバイスでのアプリケーションの起動を高速化するための戦略の一部として、最初にサーバーでレンダリングされる可能性があります。
サーバー側レンダラーは、完全なHTML要素APIをサポートしていない可能性があります。
`querySelector` をサポートしていない場合、前のテストは失敗する可能性があります。

`DebugElement` は、すべてのサポートされているプラットフォームで動作するクエリメソッドを提供します。
これらのクエリメソッドは、`DebugElement` ツリー内のノードが選択基準に一致した場合に `true` を返す _述語_ 関数を取ります。

実行時プラットフォームのライブラリからインポートされた `By` クラスの助けを借りて _述語_ を作成します。
次に、ブラウザプラットフォームの `By` のインポートを示します。

```ts
import {By} from '@angular/platform-browser';
```

次の例は、`DebugElement.query()` とブラウザの `By.css` メソッドを使用して、前のテストを再実装したものです。

```ts
it('should find the <p> with fixture.debugElement.query(By.css)', () => {
  const bannerDe: DebugElement = fixture.debugElement;
  const paragraphDe = bannerDe.query(By.css('p'));
  const p: HTMLElement = paragraphDe.nativeElement;
  expect(p.textContent).toEqual('banner works!');
});
```

注目すべき観察結果をいくつか紹介します。

- `By.css()` 静的メソッドは、[標準の CSS セレクター](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors 'CSS セレクター') を持つ `DebugElement` ノードを選択します。
- クエリは、段落の `DebugElement` を返します。
- その結果をラップ解除して、段落要素を取得する必要があります。

CSSセレクターでフィルタリングし、ブラウザの _ネイティブ要素_ のプロパティのみをテストする場合は、`By.css` アプローチはやり過ぎになる可能性があります。

多くの場合、`querySelector()` や `querySelectorAll()` などの標準の `HTMLElement` メソッドを使用してフィルタリングする方が簡単で明確です。
# コンポーネントテストのシナリオ

このガイドでは、一般的なコンポーネントテストのユースケースについて解説します。

## コンポーネントのバインディング {#component-binding}

サンプルアプリケーションでは、`Banner`コンポーネントはHTMLテンプレート内に静的なタイトルテキストを表示します。

いくつかの変更を加えた後、`Banner`コンポーネントは次のようにコンポーネントの`title`プロパティにバインドすることで、動的なタイトルを表示します。

```typescript
{header="banner.ts"}
import {Component, signal} from '@angular/core';

@Component({
  selector: 'app-banner',
  template: '<h1>{{ title() }}</h1>',
  styles: ['h1 { color: green; font-size: 350%}'],
})
export class Banner {
  title = signal('Test Tour of Heroes');
}
```

これは最小限のものですが、コンポーネントが実際に想定した場所に正しいコンテンツを表示していることを確認するためのテストを追加することにします。

### `<h1>`のクエリ {#query-for-the-h1}

_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 test instance
  h1 = fixture.nativeElement.querySelector('h1');
});
```

### `createComponent()`はデータをバインドしない {#createcomponent-does-not-bind-data}

最初のテストでは、画面にデフォルトの`title`が表示されることを確認したいと思います。
直感的には、次のように`<h1>`をすぐに検査するテストを書きたくなるでしょう。

```ts
it('should display original title', () => {
  expect(h1.textContent).toContain(component.title());
});
```

_そのテストは失敗し_、次のメッセージが表示されます。

```shell
{hideCopy}
expected '' to contain 'Test Tour of Heroes'.
```

バインディングは、Angularが**変更検知**を実行したときに発生します。

本番環境では、例えばAngularがコンポーネントを作成したときや、ユーザーがキー入力したときなどに、変更検知が自動的に開始されます。

`TestBed.createComponent`は同期的に変更検知をトリガーしません。この事実は修正されたテストで確認されています。

```ts
it('no title in the DOM after createComponent()', () => {
  expect(h1.textContent).toEqual('');
});
```

### `whenStable()` {#whenstable}

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

### シグナルを入力にバインドする {#binding-signals-to-inputs}

入力への変更を反映し、出力をリッスンするために、シグナルを入力に、関数を出力に動的にバインドできます。

```ts
import {inputBinding, outputBinding} from '@angular/core';

const fixture = TestBed.createComponent(ValueDisplay, {
  bindings: [
    inputBinding('value', value),
    outputBinding('valueChange', () =>  (/* ... */) ),
  ],
});
```

### `dispatchEvent()`で入力値を変更する {#change-an-input-value-with-dispatchevent}

ユーザー入力をシミュレートするには、input要素を見つけてその`value`プロパティを設定します。

しかし、不可欠な中間ステップがあります。

Angularは、あなたがinput要素の`value`プロパティを設定したことを知りません。
`dispatchEvent()`を呼び出して要素の`input`イベントを発生させるまで、Angularはそのプロパティを読み取りません。

`TitleCasePipe`を使用するコンポーネントの次の例は、適切な手順を示しています。

```ts
it('should convert hero name to Title Case', async () => {
  const hostElement = fixture.nativeElement;
  const nameInput: HTMLInputElement = hostElement.querySelector('input')!;
  const nameDisplay: HTMLElement = hostElement.querySelector('span')!;

// simulate user entering a new name into the input box
  nameInput.value = 'quick BROWN  fOx';

// Dispatch a DOM event so that Angular learns of input value change.
  nameInput.dispatchEvent(new Event('input'));

// Wait for Angular to update the display binding through the title pipe
  await fixture.whenStable();

expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
```

## 依存関係を持つコンポーネント {#component-with-a-dependency}

コンポーネントはしばしばサービスの依存関係を持ちます。

`Welcome`コンポーネントは、ログインしているユーザーにウェルカムメッセージを表示します。
注入された`UserAuthentication`のプロパティに基づいて、ユーザーが誰であるかを認識します。

```typescript
import {Component, inject, OnInit, signal} from '@angular/core';
import {UserAuthentication} from '../model/user.authentication';

@Component({
  selector: 'app-welcome',
  template: '<h3 class="welcome"><i>{{ welcome() }}</i></h3>',
})
export class Welcome {
  private userAuth = inject(UserAuthentication);
  welcome = signal(
    this.userAuth.isLoggedIn() ? `Welcome, ${this.userAuth.user().name}` : 'Please log in.',
  );
}
```

`Welcome`コンポーネントにはサービスと対話する決定ロジックがあり、このロジックがこのコンポーネントをテストする価値のあるものにしています。

### サービスのテストダブルを提供する {#provide-service-test-doubles}

_テスト対象コンポーネント_（component-under-test）に実際のサービスを提供する必要はありません。

実際の`UserAuthentication`を注入するのは難しい場合があります。
実際のサービスは、ユーザーにログイン資格情報を求め、認証サーバーへの接続を試みるかもしれません。
これらの動作を傍受するのは困難な場合があります。テストダブルを使用するとテストの動作が本番環境と異なるものになるため、使用は控えめにすることに注意してください。

### 注入されたサービスを取得する {#get-injected-services}

テストでは、`Welcome`コンポーネントに注入された`UserAuthentication`にアクセスする必要があります。

Angularには階層的な注入システムがあります。
`TestBed`によって作成されたルートインジェクターからコンポーネントツリーの下層に至るまで、複数のレベルにインジェクターが存在する可能性があります。

注入されたサービスを取得する最も安全な方法、つまり**_常に機能する_**方法は、
**_テスト対象コンポーネント_のインジェクターから取得すること**です。
コンポーネントインジェクターは、フィクスチャの`DebugElement`のプロパティです。

```ts
// UserAuthentication actually injected into the component
userAuth = fixture.debugElement.injector.get(UserAuthentication);
```

HELPFUL: これは_通常_必要ありません。サービスは多くの場合、ルートまたはTestBedのオーバーライドで提供され、`TestBed.inject()`を使用してより簡単に取得できます（下記参照）。

### `TestBed.inject()` {#testbedinject}

これは、フィクスチャの`DebugElement`を使用してサービスを取得するよりも覚えやすく、冗長ではありません。

このテストスイートでは、`UserAuthentication`の_唯一の_プロバイダーはルートテストモジュールであるため、次のように`TestBed.inject()`を呼び出しても安全です。

```ts
userAuth = TestBed.inject(UserAuthentication);
```

HELPFUL: `TestBed.inject()`が機能しないユースケースについては、コンポーネントのインジェクターからサービスを取得する必要がある場合とその理由を説明している[_コンポーネントプロバイダーのオーバーライド_](#override-component-providers)セクションを参照してください。

### 最終的なセットアップとテスト {#final-setup-and-tests}

`TestBed.inject()`を使用した完全な`beforeEach()`は次のとおりです。

```ts
let fixture: ComponentFixture<Welcome>;
let comp: Welcome;
let userAuth: UserAuthentication; // the TestBed injected service
let el: HTMLElement; // the DOM element with the welcome message

beforeEach(() => {
  fixture = TestBed.createComponent(Welcome);
  comp = fixture.componentInstance;

// UserAuthentication from the root injector
  userAuth = TestBed.inject(UserAuthentication);

//  get the "welcome" element by CSS selector (e.g., by class name)
  el = fixture.nativeElement.querySelector('.welcome');
});
```

そして、いくつかのテストを以下に示します。

```ts
it('should welcome the user', async () => {
  await fixture.whenStable();
  const content = el.textContent;

expect(content, '"Welcome ..."').toContain('Welcome');
  expect(content, 'expected name').toContain('Test User');
});

it('should welcome "Bubba"', async () => {
  userAuth.user.set({name: 'Bubba'}); // welcome message hasn't been shown yet
  await fixture.whenStable();

expect(el.textContent).toContain('Bubba');
});

it('should request login if not logged in', async () => {
  userAuth.isLoggedIn.set(false); // welcome message hasn't been shown yet
  await fixture.whenStable();
  const content = el.textContent;

expect(content, 'not welcomed').not.toContain('Welcome');
  expect(content, '"log in"').toMatch(/log in/i);
});
```

1つ目はサニティテスト（健全性確認）です。これは`UserAuthentication`が呼び出され、機能していることを確認します。

HELPFUL: `expect`の2番目の引数（たとえば`'expected name'`）は、オプションの失敗ラベルです。
期待値の検証（expectation）が失敗した場合、Vitestはこのラベルを検証失敗メッセージに追加します。
複数の検証を含むスペックでは、何が間違っていたのか、どの検証が失敗したのかを明確にするのに役立ちます。

残りのテストは、サービスが異なる値を返すときのコンポーネントのロジックを確認します。
2番目のテストは、ユーザー名を変更した際の影響を検証します。
3番目のテストは、ログインしているユーザーがいない場合にコンポーネントが適切なメッセージを表示することを確認します。

## 非同期サービスを使用するコンポーネント {#component-with-async-service}

このサンプルでは、`About`コンポーネントテンプレートが`Twain`コンポーネントをホストしています。
`Twain`コンポーネントはマーク・トウェインの名言を表示します。

```html
<p class="twain">
  <i>{{ quote | async }}</i>
</p>
<button type="button" (click)="getQuote()">Next quote</button>
@if (errorMessage()) {
  <p class="error">{{ errorMessage() }}</p>
}
```

HELPFUL: コンポーネントの`quote`プロパティの値は`AsyncPipe`を通過します。
つまり、このプロパティは`Promise`または`Observable`を返します。

この例では、`TwainQuotes.getQuote()`メソッドにより、`quote`プロパティが`Observable`を返すことがわかります。

```ts
getQuote() {
  this.errorMessage.set('');
  this.quote = this.twainQuotes.getQuote().pipe(
    startWith('...'),
    catchError((err: any) => {
      this.errorMessage.set(err.message || err.toString());
      return of('...'); // reset message to placeholder
    }),
  );
}
```

`Twain`コンポーネントは、注入された`TwainQuotes`から名言を取得します。
コンポーネントは、サービスが最初の名言を返す前に、返された`Observable`をプレースホルダー値（`'...'`）で開始します。

`catchError`はサービスエラーを傍受し、エラーメッセージを準備して、成功チャネルでプレースホルダー値を返します。

これらはすべてテストしたい機能です。

### `HttpTestingController`を使用したHTTPリクエストのモックによるテスト {#testing-by-mocking-http-requests-with-the-httptestingcontroller}

コンポーネントをテストする場合、サービスのパブリックAPIのみが重要であるべきです。
一般に、テスト自体がリモートサーバーを呼び出すべきではありません。
テストはそのような呼び出しをエミュレートする必要があります。

非同期サービスがリモートデータをロードするために`HttpClient`に依存している場合、`HttpTestingController`を使用してHTTPレベルでモックレスポンスを返すことを推奨します。

`HttpBackend`のモック作成の詳細については、[専用ガイド](guide/http/testing)を参照してください。

### サービスのスタブ実装を提供することによるテスト {#testing-by-providing-a-stubbed-implementation-of-a-service}

HTTPレベルでの非同期リクエストのモックが不可能な場合、代替手段としてスパイを活用します。

この`app/twain/twain-quotes.spec.ts`の設定は、その方法の1つを示しています。

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

スタブ実装がどのように元の実装を置き換えるかに注目してください。

```ts
TestBed.configureTestingModule({
  providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
});
```

スタブは、それを注入するコンポーネントやサービスがスタブ化された実装を受け取るように設計されています。
つまり、`getQuote`への呼び出しはすべて、テスト用の名言を含むObservableを受け取ります。

実際の`getQuote()`メソッドとは異なり、このスパイはサーバーをバイパスし、値が即座に利用可能な同期Observableを返します。

### Vitestのフェイクタイマーを使用した非同期テスト {#async-test-with-a-vitest-fake-timers}

`setTimeout`や`Promise`のような非同期関数をモックするには、Vitestのフェイクタイマーを活用して発火のタイミングを制御できます。

```ts
it('should display error when TwainQuotes service fails', async () => {
  class TwainQuotesStub implements TwainQuotes {
    getQuote() {
      return defer(() => {
        return new Promise<string>((_, reject) => {
          setTimeout(() => reject('TwainService test failure'));
        });
      });
    }

// ... Implement everything to conform to the API
  }

TestBed.configureTestingModule({
    providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
  });

vi.useFakeTimers(); // setting up the fake timers
  const fixture = TestBed.createComponent(TwainComponent);

// rendering isn't async, we need to flush
  await vi.runAllTimersAsync();

await expect(fixture.nativeElement.querySelector('.error')!.textContent).toMatch(/test failure/);
  expect(fixture.nativeElement.querySelector('.twain')!.textContent).toBe('...');

vi.useRealTimers(); // resets to regular async execution
});
```

### その他の非同期テスト {#more-async-tests}

スタブサービスが非同期Observableを返す場合、テストのほとんども非同期である必要があります。

ここに、実世界で想定されるデータフローを示すテストがあります。

```ts
it('should show quote after getQuote', async () => {
  class MockTwainQuotes implements TwainQuotes {
    private subject = new Subject<string>();

getQuote() {
      return this.subject.asObservable();
    }

emit(val: string) {
      this.subject.next(val);
    }
  }

it('should show quote after getQuote (success)', async () => {
    vi.useFakeTimers();

TestBed.configureTestingModule({
      providers: [{provide: TwainQuotes, useClass: MockTwainQuotes}],
    });

const fixture = TestBed.createComponent(TwainComponent);
    const twainQuotes = TestBed.inject(TwainQuotes) as MockTwainQuotes;
    await vi.runAllTimersAsync(); // render before the quote is recieved

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

最初のレンダリング時に、名言要素がプレースホルダー値（`'...'`）を表示していることに注目してください。
最初の名言はまだ到着していません。

その後、名言要素が期待されるテキストを表示していることをアサートできます。

### `zone.js`と`fakeAsync`を使用した非同期テスト {#async-tests-with-zonejs-and-fakeasync}

`fakeAsync`ヘルパー関数は、`zone.js`で非同期APIにパッチを当てることに依存するもう1つのモッククロックです。これは`zone.js`ベースのアプリケーションのテストで一般的に使用されていました。`fakeAsync`の使用は現在推奨されていません。

TIP: ネイティブの非同期テスト戦略や、VitestやJasmineなどの他のフェイクタイマー（モッククロックとも呼ばれます）を使用することを推奨します。

IMPORTANT: `fakeAsync`はVitestテストランナーでは使用できません。このランナーには`zone.js`パッチが適用されないためです。

## 入力と出力を持つコンポーネント {#component-with-inputs-and-outputs}

入力と出力を持つコンポーネントは通常、ホストコンポーネントのビューテンプレート内に現れます。
ホストはプロパティバインディングを使用して入力プロパティを設定し、イベントバインディングを使用して出力プロパティによって発生したイベントをリッスンします。

テストの目的は、そのようなバインディングが期待どおりに機能することを確認することです。
テストでは、入力値を設定し、出力イベントをリッスンする必要があります。

`DashboardHero`コンポーネントは、この役割を果たすコンポーネントの小さな例です。
これは、`Dashboard`コンポーネントによって提供される個々のヒーローを表示します。
そのヒーローをクリックすると、ユーザーがそのヒーローを選択したことが`Dashboard`コンポーネントに通知されます。

`DashboardHero`コンポーネントは、次のように`Dashboard`コンポーネントのテンプレートに埋め込まれています。

```html
@for (hero of heroes; track hero) {
  <dashboard-hero class="col-1-4" [hero]="hero" (selected)="gotoDetail($event)"/>
}
```

`DashboardHero`コンポーネントは`@for`ブロック内に現れ、各コンポーネントの`hero`入力プロパティをループ値に設定し、コンポーネントの`selected`イベントをリッスンします。

コンポーネントの完全な定義は次のとおりです。

```typescript
@Component({
  selector: 'dashboard-hero',
  imports: [UpperCasePipe],
  template: `
    <button type="button" (click)="click()" class="hero">
      {{ hero().name | uppercase }}
    </button>
  `,
})
export class DashboardHero {
  readonly hero = input.required<Hero>();
  readonly selected = output<Hero>();

click() {
    this.selected.emit(this.hero());
  }
}
```

このように単純なコンポーネントをテストすること自体にはあまり価値がありませんが、その方法を知っておくことには価値があります。
次のアプローチのいずれかを使用します。

- `Dashboard`コンポーネントで使用されている状態でテストする
- スタンドアロンコンポーネントとしてテストする
- `Dashboard`コンポーネントの代替で使用されている状態でテストする

当面の目標は`Dashboard`コンポーネントではなく`DashboardHero`コンポーネントをテストすることなので、2番目と3番目のオプションを試します。

### DashboardHeroコンポーネントを単体でテストする {#test-the-dashboardhero-component-standalone}

スペックファイルのセットアップの要点は次のとおりです。

```ts
let fixture: ComponentFixture<DashboardHero>;
let comp: DashboardHero;
let heroDe: DebugElement;
let heroEl: HTMLElement;
let expectedHero: Hero;

beforeEach(async () => {
  fixture = TestBed.createComponent(DashboardHero);
  comp = fixture.componentInstance;

// find the hero's DebugElement and element
  heroDe = fixture.debugElement.query(By.css('.hero'));
  heroEl = heroDe.nativeElement;

// mock the hero supplied by the parent component
  expectedHero = {id: 42, name: 'Test Name'};

// simulate the parent setting the input property with that hero
  fixture.componentRef.setInput('hero', expectedHero);

// wait for initial data binding
  await fixture.whenStable();
});
```

セットアップコードがテスト用ヒーロー（`expectedHero`）をコンポーネントの`hero`プロパティに割り当てていることに注目してください。これは、`Dashboard`がリピーター内のプロパティバインディングを使用して設定する方法をエミュレートしています。

次のテストは、ヒーロー名がバインディングを使用してテンプレートに伝播されることを検証します。

```ts
it('should display hero name in uppercase', () => {
  const expectedPipedName = expectedHero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});
```

テンプレートはAngularの`UpperCasePipe`を通してヒーロー名を渡すため、テストでは要素の値を大文字の名前に一致させる必要があります。

### クリック {#clicking}

ヒーローをクリックすると、ホストコンポーネント（おそらく`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`プロパティは`EventEmitter`を返します。これはコンシューマーにはRxJSの同期的な`Observable`のように見えます。
テストは、ホストコンポーネントが_暗黙的に_行うのと同様に、_明示的に_それにサブスクライブします。

コンポーネントが期待どおりに動作する場合、ヒーローの要素をクリックすると、コンポーネントの`selected`プロパティに`hero`オブジェクトを発行するように指示するはずです。

テストは、`selected`へのサブスクリプションを通じてそのイベントを検出します。

### `triggerEventHandler` {#triggereventhandler}

前のテストの`heroDe`は、ヒーローの`<div>`を表す`DebugElement`です。

これには、ネイティブ要素との対話を抽象化するAngularのプロパティとメソッドがあります。
このテストは、"click"イベント名を指定して`DebugElement.triggerEventHandler`を呼び出します。
"click"イベントバインディングは、`DashboardHero.click()`を呼び出すことで応答します。

Angularの`DebugElement.triggerEventHandler`は、_イベント名_によって_任意のデータバインドされたイベント_を発生させることができます。
2番目のパラメータは、ハンドラーに渡されるイベントオブジェクトです。

テストは"click"イベントをトリガーしました。

```ts
heroDe.triggerEventHandler('click');
```

この場合、テストは、ランタイムイベントハンドラーであるコンポーネントの`click()`メソッドがイベントオブジェクトを気にしないと正しく想定しています。

HELPFUL: 他のハンドラーはそれほど寛容ではありません。
たとえば、`RouterLink`ディレクティブは、クリック中にどのマウスボタン（もしあれば）が押されたかを識別する`button`プロパティを持つオブジェクトを期待します。
イベントオブジェクトがない場合、`RouterLink`ディレクティブはエラーをスローします。

### 要素をクリックする {#click-the-element}

次のテストの代替案は、ネイティブ要素独自の`click()`メソッドを呼び出します。これは_このコンポーネント_にとっては全く問題ありません。

```ts
it('should raise selected event when clicked (element.click)', () => {
  let selectedHero: Hero | undefined;
  comp.selected.subscribe((hero: Hero) => (selectedHero = hero));

heroEl.click();
  expect(selectedHero).toBe(expectedHero);
});
```

### `click()`ヘルパー {#click-helper}

ボタン、アンカー、または任意のHTML要素をクリックすることは、一般的なテストタスクです。

次の`click()`関数のようなヘルパーに_クリックトリガー_プロセスをカプセル化することで、それを一貫性のある簡単なものにします。

```ts
/** Button events to pass to `DebugElement.triggerEventHandler` for RouterLink event handler */
export const ButtonClickEvents = {
  left: {button: 0},
  right: {button: 2},
};

/** Simulate element click. Defaults to mouse left-button click event. */
export function click(
  el: DebugElement | HTMLElement,
  eventObj: any = ButtonClickEvents.left,
): void {
  if (el instanceof HTMLElement) {
    el.click();
  } else {
    el.triggerEventHandler('click', eventObj);
  }
}
```

最初のパラメータは_クリックする要素_です。
必要に応じて、2番目のパラメータとしてカスタムイベントオブジェクトを渡します。
デフォルトは、`RouterLink`ディレクティブを含む多くのハンドラーによって受け入れられる部分的な[左ボタンマウスイベントオブジェクト](https://developer.mozilla.org/docs/Web/API/MouseEvent/button)です。

IMPORTANT: `click()`ヘルパー関数は、Angularテストユーティリティの1つでは**ありません**。
これは、_このガイドのサンプルコード_で定義されている関数です。
すべてのサンプルテストでこれを使用しています。
気に入ったら、独自のヘルパーコレクションに追加してください。

クリックヘルパーを使用して書き直した前のテストは次のとおりです。

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

## テストホスト内のコンポーネント {#component-inside-a-test-host}

以前のテストは、それ自体がホストである`Dashboard`コンポーネントの役割を果たしていました。
しかし、`DashboardHero`コンポーネントは、ホストコンポーネントに適切にデータバインディングされたときに正しく動作するでしょうか？

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

テストホストは、コンポーネントの`hero`入力プロパティにテスト用のヒーローを設定します。
コンポーネントの`selected`イベントを自身の`onSelected`ハンドラーにバインドし、発行されたヒーローを自身の`selectedHero`プロパティに記録します。

その後、テストは`selectedHero`を確認して、`DashboardHero.selected`イベントが期待されるヒーローを発行したことを検証できます。

`test-host`テストのセットアップは、スタンドアロンテストのセットアップと似ています。

```ts
beforeEach(async () => {
  // create TestHost instead of DashboardHero
  fixture = TestBed.createComponent(TestHost);
  testHost = fixture.componentInstance;
  heroEl = fixture.nativeElement.querySelector('.hero');

await fixture.whenStable();
});
```

このテストモジュールの構成には、2つの重要な違いがあります。

- `DashboardHero`の代わりに`TestHost`コンポーネントを*作成*します
- `TestHost`コンポーネントはバインディングを使用して`DashboardHero.hero`を設定します

`createComponent`は、`DashboardHero`のインスタンスではなく、`TestHost`のインスタンスを保持する`fixture`を返します。

`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);
  // selected hero should be the same data bound hero
  expect(testHost.selectedHero).toBe(testHost.hero);
});
```

選択イベントのテストのみが異なります。
これは、選択された`DashboardHero`のヒーローが、イベントバインディングを通じてホストコンポーネントまで実際に到達することを確認します。

## ルーティングコンポーネント {#routing-component}

_ルーティングコンポーネント_とは、`Router`に対して別のコンポーネントへナビゲートするよう指示するコンポーネントです。
`Dashboard`コンポーネントは、ユーザーがダッシュボード上の_ヒーローボタン_の1つをクリックすることで`HeroDetail`コンポーネントへナビゲートできるため、_ルーティングコンポーネント_です。

Angularは、ボイラープレートを削減し、`HttpClient`に依存するコードをより効果的にテストするためのテストヘルパーを提供します。`provideRouter`関数は、テストモジュール内で直接使用できます。

```ts
beforeEach(async () => {
  TestBed.configureTestingModule({
    providers: [
      provideRouter([{path: '**', component: Dashboard}]),
      provideHttpClientTesting(),
      HeroService,
    ],
  });
  harness = await RouterTestingHarness.create();
  comp = await harness.navigateByUrl('/', Dashboard);
  TestBed.inject(HttpTestingController).expectOne('api/heroes').flush(getTestHeroes());
});
```

次のテストは、表示されたヒーローをクリックし、期待されるURLへナビゲートすることを確認します。

```ts
it('should tell navigate when hero clicked', async () => {
  // get first <dashboard-hero> DebugElement
  const heroDe = harness.routeDebugElement!.query(By.css('dashboard-hero'));
  heroDe.triggerEventHandler('selected', comp.heroes[0]);

// expecting to navigate to id of the component's first hero
  const id = comp.heroes[0].id;
  expect(TestBed.inject(Router).url, 'should nav to HeroDetail for first hero').toEqual(
    `/heroes/${id}`,
  );
});
```

## ルーティングされたコンポーネント {#routed-components}

_ルーティングされたコンポーネント_は、`Router`ナビゲーションの宛先です。
特にコンポーネントへのルートに_パラメータが含まれている_場合、テストが難しくなることがあります。
`HeroDetail`は、そのようなルートの宛先となる_ルーティングされたコンポーネント_です。

ユーザーが_ダッシュボード_のヒーローをクリックすると、`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` observableを_サブスクライブ_し、そのライフサイクル中に`id`が変更されることに備える必要があります。

```ts
constructor() {
  // get hero when `id` param changes
  this.route.paramMap
    .pipe(takeUntilDestroyed())
    .subscribe((pmap) => this.getHero(pmap.get('id')));
}
```

テストでは、異なるルートにナビゲートすることで、`HeroDetail`が異なる`id`パラメータ値にどのように応答するかを確認できます。

## ネストされたコンポーネントのテスト {#nested-component-tests}

コンポーネントテンプレートには、ネストされたコンポーネントが含まれることがよくあり、そのテンプレートにもさらにコンポーネントが含まれる場合があります。

コンポーネントツリーは非常に深くなることがあり、ネストされたコンポーネントがツリーの最上位にあるコンポーネントのテストにおいて何の役割も果たさない場合があります。

たとえば、`App`コンポーネントは、アンカーとそれらの`RouterLink`ディレクティブを持つナビゲーションバーを表示します。

```html
<app-banner />
<app-welcome />

<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>

<router-outlet />
```

ナビゲーションではなくリンクを検証するには、ナビゲートするための`Router`は必要ありませんし、`Router`が*ルーティングされたコンポーネント*を挿入する場所を示すための`<router-outlet>`も必要ありません。

`Banner`および`Welcome`コンポーネント（`<app-banner>`および`<app-welcome>`で示される）も無関係です。

しかし、DOM内に`App`コンポーネントを作成するテストはすべて、これら3つのコンポーネントのインスタンスも作成します。もしそれを許可する場合、それらを作成するように`TestBed`を設定する必要があります。

それらを宣言し忘れると、Angularコンパイラは`App`テンプレート内の`<app-banner>`、`<app-welcome>`、および`<router-outlet>`タグを認識せず、エラーをスローします。

実際のコンポーネントを宣言する場合、*それらの*ネストされたコンポーネントも宣言し、ツリー内の*任意の*コンポーネントに注入される*すべての*サービスを提供する必要があります。

このセクションでは、セットアップを最小限に抑えるための2つのテクニックについて説明します。
プライマリコンポーネントのテストに集中するために、それらを単独で、または組み合わせて使用してください。

### 不要なコンポーネントのスタブ化 {#stubbing-unneeded-components}

最初のテクニックでは、テストにおいてほとんど、あるいはまったく役割を果たさないコンポーネントやディレクティブのスタブバージョンを作成して宣言します。

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

beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    set: {
      imports: [RouterLink, BannerStub, RouterOutletStub, WelcomeStub],
    },
  });

fixture = TestBed.createComponent(App);
  comp = fixture.componentInstance;
});
```

HELPFUL: この例の`set`キーは、コンポーネント上の既存のすべてのインポートを置き換えます。スタブだけでなく、すべての依存関係をインポートするようにしてください。あるいは、`remove`/`add`キーを使用して、インポートを選択的に削除および追加できます。

### `NO_ERRORS_SCHEMA` {#noerrorsschema}

2つ目のアプローチでは、コンポーネントのメタデータオーバーライドに`NO_ERRORS_SCHEMA`を追加します。

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    set: {
      imports: [], // resets all imports
      schemas: [NO_ERRORS_SCHEMA],
    },
  });
});
```

`NO_ERRORS_SCHEMA`は、認識されない要素や属性を無視するようにAngularコンパイラに指示します。

コンパイラは、`TestBed`構成で対応する`App`コンポーネントと`RouterLink`を宣言したため、`<app-root>`要素と`routerLink`属性を認識します。

しかし、コンパイラは`<app-banner>`、`<app-welcome>`、または`<router-outlet>`に遭遇してもエラーをスローしません。
単にそれらを空のタグとしてレンダリングし、ブラウザはそれらを無視します。

スタブコンポーネントはもう必要ありません。

### 両方のテクニックを併用する {#use-both-techniques-together}

これらは*浅いコンポーネントテスト（Shallow Component Testing）*のためのテクニックであり、コンポーネントの視覚的な表面を、テストにとって重要なコンポーネントテンプレート内の要素だけに縮小することからそう呼ばれています。

`NO_ERRORS_SCHEMA`アプローチは2つのうち簡単な方ですが、使いすぎないようにしてください。

`NO_ERRORS_SCHEMA`はまた、うっかり省略したりスペルミスしたりした不足しているコンポーネントや属性について、コンパイラが通知するのを防ぎます。
コンパイラなら一瞬で発見できたはずの幻のバグを追いかけるのに、何時間も無駄にする可能性があります。

*スタブコンポーネント*アプローチには別の利点があります。
*この*例のスタブは空でしたが、テストにおいて何らかの方法でそれらと対話する必要がある場合は、機能を削ぎ落としたテンプレートやクラスを与えることができます。

実際には、この例に見られるように、同じセットアップで2つのテクニックを組み合わせることになります。

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    remove: {imports: [RouterOutlet, Welcome]},
    set: {schemas: [NO_ERRORS_SCHEMA]},
  });
});
```

Angularコンパイラは、`<app-banner>`要素に対して`BannerStub`を作成し、`routerLink`属性を持つアンカーに`RouterLink`を適用しますが、`<app-welcome>`および`<router-outlet>`タグは無視します。

### `By.directive`と注入されたディレクティブ {#bydirective-and-injected-directives}

もう少しセットアップを行うと、初期データバインディングがトリガーされ、ナビゲーションリンクへの参照が取得されます。

```ts
beforeEach(async () => {
  await fixture.whenStable();

// find DebugElements with an attached RouterLinkStubDirective
  linkDes = fixture.debugElement.queryAll(By.directive(RouterLink));

// get attached link directive instances
  // using each DebugElement's injector
  routerLinks = linkDes.map((de) => de.injector.get(RouterLink));
});
```

特に興味深い3つのポイント：

- `By.directive`を使用して、ディレクティブがアタッチされたアンカー要素を見つけます
- クエリは、一致する要素をラップした`DebugElement`を返します
- 各`DebugElement`は、その要素にアタッチされたディレクティブの特定のインスタンスを持つ依存性の注入（DI）を公開します

検証する`App`コンポーネントのリンクは次のとおりです。

```html
<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>
```

これらのリンクが期待どおりに`routerLink`ディレクティブに接続されていることを確認するいくつかのテストを以下に示します。

```ts
it('can get RouterLinks from template', () => {
  expect(routerLinks.length, 'should have 3 routerLinks').toBe(3);
  expect(routerLinks[0].href).toBe('/dashboard');
  expect(routerLinks[1].href).toBe('/heroes');
  expect(routerLinks[2].href).toBe('/about');
});

it('can click Heroes link in template', async () => {
  const heroesLinkDe = linkDes[1]; // heroes link DebugElement

TestBed.inject(Router).resetConfig([{path: '**', children: []}]);
  heroesLinkDe.triggerEventHandler('click', {button: 0});

await fixture.whenStable();

expect(TestBed.inject(Router).url).toBe('/heroes');
});
```

## `page`オブジェクトの使用 {#use-a-page-object}

`HeroDetail`コンポーネントは、タイトル、2つのヒーローフィールド、2つのボタンを持つシンプルなビューです。

しかし、この単純なフォームでさえ、テンプレートには多くの複雑さがあります。

```html
@if (hero) {
  <div>
    <h2>
      <span>{{ hero.name | titlecase }}</span> Details
    </h2>
    <div><span>id: </span>{{ hero.id }}</div>
    <div>
      <label for="name">name: </label>
      <input id="name" [(ngModel)]="hero.name" placeholder="name" />
    </div>
    <button type="button" (click)="save()">Save</button>
    <button type="button" (click)="cancel()">Cancel</button>
  </div>
}
```

コンポーネントを検証するテストには以下が必要です…

- DOMに要素が表示される前に、ヒーローが到着するのを待つこと
- タイトルテキストへの参照
- 検査および設定するための名前入力ボックスへの参照
- クリックできるようにするための2つのボタンへの参照

このような小さなフォームでさえ、条件付きセットアップやCSS要素選択が入り組んで混乱を招く可能性があります。

コンポーネントプロパティへのアクセスを処理し、それらを設定するロジックをカプセル化する`Page`クラスを使用して、複雑さを制御します。

以下は、`hero-detail.component.spec.ts`用のそのような`Page`クラスです。

```ts
class Page {
  // getter properties wait to query the DOM until called.
  get buttons() {
    return this.queryAll<HTMLButtonElement>('button');
  }
  get saveBtn() {
    return this.buttons[0];
  }
  get cancelBtn() {
    return this.buttons[1];
  }
  get nameDisplay() {
    return this.query<HTMLElement>('span');
  }
  get nameInput() {
    return this.query<HTMLInputElement>('input');
  }

//// query helpers ////
  private query<T>(selector: string): T {
    return harness.routeNativeElement!.querySelector(selector)! as T;
  }

private queryAll<T>(selector: string): T[] {
    return harness.routeNativeElement!.querySelectorAll(selector) as any as T[];
  }
}
```

これで、コンポーネントの操作と検査のための重要なフックが整理され、`Page`のインスタンスからアクセスできるようになりました。

`createComponent`メソッドは`page`オブジェクトを作成し、`hero`が到着すると空白を埋めます。

```ts
async function createComponent(id: number) {
  harness = await RouterTestingHarness.create();
  component = await harness.navigateByUrl(`/heroes/${id}`, HeroDetail);
  page = new Page();

const request = TestBed.inject(HttpTestingController).expectOne(`api/heroes/?id=${id}`);
  const hero = getTestHeroes().find((h) => h.id === Number(id));
  request.flush(hero ? [hero] : []);
  await harness.fixture.whenStable();
}
```

要点を強調するために、さらにいくつかの`HeroDetail`コンポーネントテストを以下に示します。

```ts
it("should display that hero's name", () => {
  expect(page.nameDisplay.textContent).toBe(expectedHero.name);
});

it('should navigate when click cancel', () => {
  click(page.cancelBtn);
  expect(TestBed.inject(Router).url).toEqual(`/heroes/${expectedHero.id}`);
});

it('should save when click save but not navigate immediately', () => {
  click(page.saveBtn);
  expect(TestBed.inject(HttpTestingController).expectOne({method: 'PUT', url: 'api/heroes'}));
  expect(TestBed.inject(Router).url).toEqual('/heroes/41');
});

it('should navigate when click save and save resolves', async () => {
  click(page.saveBtn);
  await harness.fixture.whenStable();
  expect(TestBed.inject(Router).url).toEqual('/heroes/41');
});

it('should convert hero name to Title Case', async () => {
  // get the name's input and display elements from the DOM
  const hostElement: HTMLElement = harness.routeNativeElement!;
  const nameInput: HTMLInputElement = hostElement.querySelector('input')!;
  const nameDisplay: HTMLElement = hostElement.querySelector('span')!;

// simulate user entering a new name into the input box
  nameInput.value = 'quick BROWN  fOx';

// Dispatch a DOM event so that Angular learns of input value change.
  nameInput.dispatchEvent(new Event('input'));

// Wait for Angular to update the display binding through the title pipe
  await harness.fixture.whenStable();

expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
```

## コンポーネントプロバイダーのオーバーライド {#override-component-providers}

`HeroDetail`は独自の`HeroDetailService`を提供します。

```ts
@Component({
  /* ... */
  providers: [HeroDetailService],
})
export class HeroDetail {
  private heroDetailService = inject(HeroDetailService);
  private route = inject(ActivatedRoute);
  private router = inject(Router);
}
```

`TestBed.configureTestingModule`の`providers`でコンポーネントの`HeroDetailService`をスタブできません。
これらは*テストモジュール*のプロバイダーであり、コンポーネントのものではありません。
これらは*フィクスチャレベル*で依存性インジェクターを準備します。

Angularは、フィクスチャインジェクターの*子*である*独自の*インジェクターを使用してコンポーネントを作成します。
コンポーネントのプロバイダー（この場合は`HeroDetailService`）を子インジェクターに登録します。

テストはフィクスチャインジェクターから子インジェクターのサービスにアクセスできません。
また、`TestBed.configureTestingModule`もそれらを設定できません。

Angularはずっと本物の`HeroDetailService`の新しいインスタンスを作成していたのです！

HELPFUL: `HeroDetailService`がリモートサーバーへの独自のXHR呼び出しをする場合、これらのテストは失敗またはタイムアウトする可能性があります。
呼び出すリモートサーバーが存在しないかもしれません。

幸いなことに、`HeroDetailService`はリモートデータアクセスの責任を注入された`HeroService`に委譲しています。

```ts
@Injectable({providedIn: 'root'})
export class HeroDetailService {
  private heroService = inject(HeroService);
}
```

前のテスト構成では、本物の`HeroService`を、サーバーリクエストを傍受してレスポンスを偽装する`TestHeroService`に置き換えています。

もし運が悪かったらどうでしょう。
`HeroService`を偽装するのが難しい場合はどうでしょう？
`HeroDetailService`が独自のサーバーリクエストを行う場合はどうでしょう？

`TestBed.overrideComponent`メソッドを使用すると、次のセットアップのバリエーションに見られるように、コンポーネントの`providers`を管理しやすい*テストダブル*に置き換えることができます。

```ts
beforeEach(async () => {
  await TestBed.configureTestingModule({
    providers: [
      provideRouter([
        {path: 'heroes', component: HeroList},
        {path: 'heroes/:id', component: HeroDetail},
      ]),
      // HeroDetailService at this level is IRRELEVANT!
      {provide: HeroDetailService, useValue: {}},
    ],
  }).overrideComponent(HeroDetail, {
    set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
  });
});
```

`TestBed.configureTestingModule`はもはや偽の`HeroService`を提供していないことに注意してください。なぜなら、それは[必要ない](#provide-a-spy-stub-herodetailservicespy)からです。

### `overrideComponent`メソッド {#the-overridecomponent-method}

`overrideComponent`メソッドに注目してください。

```ts
.overrideComponent(HeroDetail, {
  set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
});
```

これは2つの引数を取ります。オーバーライドするコンポーネント型（`HeroDetail`）と、オーバーライドメタデータオブジェクトです。
[オーバーライドメタデータオブジェクト](guide/testing/utility-apis#metadata-override-object)は、次のように定義されたジェネリックです。

```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`）を提供する {#provide-a-spy-stub-herodetailservicespy}

この例では、コンポーネントの`providers`配列を、`HeroDetailServiceSpy`を含む新しい配列に完全に置き換えます。

`HeroDetailServiceSpy`は、そのサービスの必要なすべての機能を偽装する、本物の`HeroDetailService`のスタブバージョンです。
これは下位レベルの`HeroService`を注入や委譲をしないため、そのためのテストダブルを提供する必要はありません。

関連する`HeroDetail`コンポーネントのテストは、サービスメソッドをスパイすることで、`HeroDetailService`のメソッドが呼び出されたことをアサートします。
したがって、スタブはそのメソッドをスパイとして実装します。

```ts
import {vi} from 'vitest';

class HeroDetailServiceSpy {
  testHero: Hero = {...testHero};

/* emit cloned test hero */
  getHero = vi.fn(() => asyncData({...this.testHero}));

/* emit clone of test hero, with changes merged in */
  saveHero = vi.fn((hero: Hero) => asyncData(Object.assign(this.testHero, hero)));
}
```

### オーバーライドテスト {#the-override-tests}

これでテストは、スパイスタブの`testHero`を操作することでコンポーネントのヒーローを直接制御し、サービスメソッドが呼び出されたことを確認できます。

```ts
let hdsSpy: HeroDetailServiceSpy;

beforeEach(async () => {
  harness = await RouterTestingHarness.create();
  component = await harness.navigateByUrl(`/heroes/${testHero.id}`, HeroDetail);
  page = new Page();
  // get the component's injected HeroDetailServiceSpy
  hdsSpy = harness.routeDebugElement!.injector.get(HeroDetailService) as any;

harness.detectChanges();
});

it('should have called `getHero`', () => {
  expect(hdsSpy.getHero, 'getHero called once').toHaveBeenCalledTimes(1);
});

it("should display stub hero's name", () => {
  expect(page.nameDisplay.textContent).toBe(hdsSpy.testHero.name);
});

it('should save stub hero change', async () => {
  const origName = hdsSpy.testHero.name;
  const newName = 'New Name';

page.nameInput.value = newName;

page.nameInput.dispatchEvent(new Event('input')); // tell Angular

expect(component.hero.name, 'component hero has new name').toBe(newName);
  expect(hdsSpy.testHero.name, 'service hero unchanged before save').toBe(origName);

click(page.saveBtn);
  expect(hdsSpy.saveHero, 'saveHero called once').toHaveBeenCalledTimes(1);

await harness.fixture.whenStable();
  expect(hdsSpy.testHero.name, 'service hero has new name after save').toBe(newName);
  expect(TestBed.inject(Router).url).toEqual('/heroes');
});
```

### その他のオーバーライド {#more-overrides}

`TestBed.overrideComponent`メソッドは、同じコンポーネントまたは異なるコンポーネントに対して複数回呼び出すことができます。
`TestBed`は、これらの他のクラスの一部を掘り下げて置き換えるための同様の`overrideDirective`、`overrideModule`、および`overridePipe`メソッドを提供します。

独自のオプションと組み合わせを試してみてください。
# デバッグテスト

テストが期待通りに動作しない場合、デフォルトのNode.js環境と実際のブラウザの両方でデバッグできます。

## Node.jsでのデバッグ {#debugging-in-nodejs}

デフォルトのNode.js環境でのデバッグは、ブラウザ固有のAPIやレンダリングに関連しない問題を診断する最も迅速な方法です。

1.  `ng test`コマンドを`--debug`フラグ付きで実行します:
    ```shell
ng test --debug
    ```
2.  テストランナーがデバッグモードで起動し、デバッガーがアタッチされるのを待ちます。
3.  任意のデバッガーをアタッチできます。たとえば、VS Codeの組み込みNode.jsデバッガーや、Node.js用のChrome DevToolsを使用できます。

## ブラウザでのデバッグ {#debugging-in-a-browser}

Vitestと[ブラウザモード](/guide/testing/migrating-to-vitest#5-configure-browser-mode-optional)を使用したデバッグは、現在サポートされていません。

<!-- https://github.com/angular/angular-cli/issues/31652 が修正されたら、このセクションを更新してください>
# テストユーティリティAPI

NOTE: このガイドはVitestに向けて更新中ですが、一部の説明とユーティリティAPIの例は現在Karma/Jasmineのコンテキストで提供されています。該当する場合、Vitestの同等のものと更新されたガイダンスを提供するよう積極的に取り組んでいます。

このページでは、最も役立つAngularテスト機能について説明します。

Angularテストユーティリティには、`TestBed`、`ComponentFixture`、およびテスト環境を制御するいくつかの関数が含まれています。
[`TestBed`](#testbed-class-summary) および [`ComponentFixture`](#the-componentfixture) クラスは、別途説明します。

以下は、スタンドアロン関数の概要を、ユーティリティの利用頻度順に示します。

| 関数         | 詳細                                                                                                                                                                                                                                               |
| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`inject`]   | 現在の `TestBed` インジェクターから、1 つ以上のサービスをテスト関数に注入します。これは、コンポーネント自体によって提供されるサービスを注入することはできません。[debugElement.injector](guide/testing/components-scenarios#get-injected-services) の議論を参照してください。 |
| `getTestBed` | 現在の `TestBed` のインスタンスを取得します。通常、`TestBed` クラスの静的クラスメソッドが十分なため、これは不要です。`TestBed` インスタンスは、静的メソッドとして利用できない、まれに使用されるメンバーをいくつか公開します。                        |

複雑な非同期シナリオの処理やレガシーのZone.jsベースのアプリケーションのテストについては、[Zone.jsテストユーティリティ](guide/testing/zone-js-testing-utilities)ガイドを参照してください。

## `TestBed` クラスの概要 {#testbed-class-summary}

`TestBed` クラスは、主要なAngularテストユーティリティの1つです。
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 /> `configureTestingModule` を呼び出して、インポート、宣言（コンポーネント、ディレクティブ、およびパイプ）、およびプロバイダーを追加および削除することで、特定のテストセットのテストモジュール構成を洗練します。 |
| `compileComponents`      | テストモジュールを構成し終えたら、非同期にコンパイルします。_いずれかの_ テストモジュールコンポーネントが非同期に読み込まれるリソース（@deferブロックなど）を持つ場合は、このメソッドを **必ず** 呼び出す必要があります。 <br /> `compileComponents` を呼び出すと、現在の仕様の期間中、`TestBed` の構成は固定されます。                                                 |
| `createComponent<T>`     | 現在の `TestBed` の構成に基づいて、`T` 型のコンポーネントのインスタンスを作成します。`createComponent` を呼び出すと、現在の仕様の期間中、`TestBed` の構成は固定されます。                                                                                                                                                                                               |
| `overrideComponent`      | 指定されたコンポーネントクラスのメタデータを置き換えます。これは、内部モジュールの中に深くネストされている可能性があります。                                                                                                                                                                                                                                                   |
| `overrideDirective`      | 指定されたディレクティブクラスのメタデータを置き換えます。これは、内部モジュールの中に深くネストされている可能性があります。                                                                                                                                                                                                                                                   |
| `overridePipe`           | 指定されたパイプクラスのメタデータを置き換えます。これは、内部モジュールの中に深くネストされている可能性があります。                                                                                                                                                                                                                                                          |
| `overrideModule`         | 指定された `NgModule` のメタデータを置き換えます。モジュールは他のモジュールをインポートできることに注意してください。`overrideModule` メソッドは、現在のテストモジュールを深く掘り下げて、これらの内部モジュールのいずれかを変更できます。                                                                                                                            |

|
`inject` | 現在の `TestBed` インジェクターからサービスを取得します。`inject` 関数は、この目的には多くの場合で十分です。ただし、`inject` は、サービスを提供できない場合にエラーをスローします。 <br /> サービスがオプションの場合どうすればよいですか？ <br /> `TestBed.inject()` メソッドは、オプションの第2パラメーターとして、Angularがプロバイダーを見つけられない場合に返すオブジェクト（この例では `null`）を取ります。 `expect(TestBed.inject(NotProvided, null)).toBeNull();` `TestBed.inject` を呼び出すと、現在の仕様の期間中、`TestBed` の構成は固定されます。 |
|
`initTestEnvironment` | テストの実行全体でテスト環境を初期化します。 <br /> テストシムはこれを実行するため、自分で呼び出す必要はほとんどありません。 <br /> このメソッドは _ちょうど 1 回_ 呼び出します。テストの実行中にこのデフォルトを変更するには、最初に `resetTestEnvironment` を呼び出します。 <br /> Angularコンパイラーファクトリ、`PlatformRef`、およびデフォルトのAngularテストモジュールを指定します。ブラウザ以外のプラットフォームの代替手段は、`@angular/platform-<platform_name>/testing/<platform_name>` という一般的な形式で利用できます。 |
| `resetTestEnvironment` | デフォルトのテストモジュールを含む、初期テスト環境をリセットします。 |

`TestBed` インスタンスのメソッドのいくつかは、静的な `TestBed` _クラス_ メソッドではカバーされていません。
これらは、めったに必要ありません。

## `ComponentFixture` {#the-componentfixture}

`TestBed.createComponent<T>` は、コンポーネント `T` のインスタンスを作成し、そのコンポーネントの強く型付けされた `ComponentFixture` を返します。

`ComponentFixture` のプロパティとメソッドは、コンポーネント、そのDOM表現、およびAngular環境の側面へのアクセスを提供します。

### `ComponentFixture` のプロパティ {#componentfixture-properties}

以下は、テスターにとって最も重要なプロパティを、ユーティリティの利用頻度順に示します。

| プロパティ          | 詳細                                                                                                                                                                                                                                                                                   |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentInstance` | `TestBed.createComponent` によって作成されたコンポーネントクラスのインスタンス。                                                                                                                                                                                                       |
| `debugElement`      | コンポーネントのルート要素に関連付けられた `DebugElement`。 <br /> `debugElement` は、テストとデバッグ中に、コンポーネントとその DOM 要素に関する洞察を提供します。これは、テスターにとって重要なプロパティです。最も興味深いメンバーは、[下記](#debugelement) に記載されています。 |
| `nativeElement`     | コンポーネントのルートにあるネイティブ DOM 要素。                                                                                                                                                                                                                                      |
| `changeDetectorRef` | コンポーネントの `ChangeDetectorRef`。 <br /> `ChangeDetectorRef` は、コンポーネントが `ChangeDetectionStrategy.OnPush` メソッドを持っているか、コンポーネントの変更検知がプログラムによって制御されている場合に最も役立ちます。                                                          |

### `ComponentFixture` のメソッド {#componentfixture-methods}

*fixture* メソッドは、Angularにコンポーネントツリーで特定のタスクを実行させます。
シミュレートされたユーザーアクションに応答して、Angularの動作をトリガーするには、これらのメソッドを呼び出します。

以下は、テスターにとって最も役立つメソッドです。

| メソッド            | 詳細                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detectChanges`     | コンポーネントの変更検知サイクルをトリガーします。 <br /> コンポーネントを初期化するには、これを呼び出します（`ngOnInit` を呼び出します）。また、テストコードの後、コンポーネントのデータバインドプロパティ値を変更します。Angular は、`personComponent.name` を変更したことを認識していないため、`detectChanges` を呼び出すまで、`name` バインディングを更新しません。 <br /> `detectChanges(false)` として呼び出さない限り、後続で `checkNoChanges` を実行して、循環的な更新がないことを確認します。                   |
| `autoDetectChanges` | `true` に設定すると、fixture が変更を自動的に検出します。 <br /> 自動検出が `true` の場合、テスト fixture はコンポーネントの作成直後に `detectChanges` を呼び出します。その後、適切なゾーンイベントを監視し、それに応じて `detectChanges` を呼び出します。テストコードでコンポーネントのプロパティ値を直接変更する場合は、それでもデータバインディングの更新をトリガーするために、`fixture.detectChanges` を呼び出す必要がある可能性があります。 <br /> デフォルトは `false` です。テストの動作を細かく制御したいテスターは、通常、これを `false` のままにします。 |
| `checkNoChanges`    | 変更検知を実行して、保留中の変更がないことを確認します。変更がある場合は、例外をスローします。                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `isStable`          | fixture が現在 _安定_ している場合は、`true` を返します。非同期タスクがまだ完了していない場合は、`false` を返します。                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `whenStable`        | fixture が安定したら解決される Promise を返します。 <br /> 非同期アクティビティまたは非同期的な変更検知の完了後にテストを再開するには、その Promise をフックします。[whenStable](guide/testing/components-scenarios#whenstable) を参照してください。                                                                                                                                                                                                                                                                                                   |
| `destroy`           | コンポーネントの破棄をトリガーします。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

#### `DebugElement` {#debugelement}

`DebugElement` は、コンポーネントのDOM表現に関する重要な洞察を提供します。

テストのルートコンポーネントの `DebugElement`（`fixture.debugElement` によって返される）から、fixtureの要素とコンポーネントのサブツリー全体を（クエリを使用して）移動できます。

以下は、テスターにとって最も役立つ `DebugElement` のメンバーを、ユーティリティの利用頻度順に示します。

| メンバー              | 詳細                                                                                                                                                                                                                                                                                                                                               |
| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nativeElement`       | ブラウザの対応する DOM 要素                                                                                                                                                                                                                                                                                                                        |
| `query`               | `query(predicate: Predicate<DebugElement>)` を呼び出すと、サブツリーの任意の深さで、述語と一致する最初の `DebugElement` が返されます。                                                                                                                                                                                                            |
| `queryAll`            | `queryAll(predicate: Predicate<DebugElement>)` を呼び出すと、サブツリーの任意の深さで、述語と一致するすべての `DebugElements` が返されます。                                                                                                                                                                                                       |
| `injector`            | ホスト依存インジェクター。たとえば、ルート要素のコンポーネントインスタンスインジェクター。                                                                                                                                                                                                                                                         |
| `componentInstance`   | 要素自身のコンポーネントインスタンス（存在する場合）。                                                                                                                                                                                                                                                                                             |
| `context`             | この要素の親コンテキストを提供するオブジェクト。多くの場合、この要素を管理する祖先コンポーネントインスタンス。 <br /> 要素が `@for` ブロック内で繰り返される場合、コンテキストは `RepeaterContext` であり、その `$implicit` プロパティは行インスタンスの値です。たとえば、`@for(hero of heroes; ...)` の `hero` です。                                  |
| `children`            | 直近の `DebugElement` の子。`children` を介して階層を下降することで、ツリーを移動します。 `DebugElement` には `childNodes` もあり、これは `DebugNode` オブジェクトのリストです。`DebugElement` は `DebugNode` オブジェクトから派生しており、多くの場合、要素よりも多くのノードがあります。テスターは、通常、プレーンノードを無視できます。 |
| `parent`              | `DebugElement` の親。これがルート要素の場合は `null` です。                                                                                                                                                                                                                                                                                        |
| `name`                | 要素が要素の場合、要素のタグ名。                                                                                                                                                                                                                                                                                                                   |
| `triggerEventHandler` | イベントに名前が付けられている場合、要素の `listeners` コレクションに対応するリスナーがある場合は、そのイベントをトリガーします。第 2 パラメーターは、ハンドラーで予想される _イベントオブジェクト_ です。[triggerEventHandler](guide/testing/components-scenarios#trigger-event-handler) を参照してください。 <br /> イベントにリスナーがない場合や、その他の問題がある場合は、`nativeElement.dispatchEvent(eventObject)` を呼び出すことを検討してください。 |
| `listeners`           | コンポーネントの `@Output` プロパティまたは要素のイベントプロパティに添付されたコールバック。                                                                                                                                                                                                                                                      |
| `providerTokens`      | このコンポーネントのインジェクターのルックアップトークン。コンポーネント自体と、コンポーネントが `providers` メタデータにリストしているトークンが含まれます。                                                                                                                                                                                       |
| `source`              | ソースコンポーネントテンプレートでこの要素を見つける場所。                                                                                                                                                                                                                                                                                         |
| `references`          | テンプレートローカル変数（たとえば、`#foo`）に関連付けられているオブジェクトの辞書。ローカル変数名でキー付けされます。                                                                                                                                                                                                                             |

`DebugElement.query(predicate)` および `DebugElement.queryAll(predicate)` メソッドは、ソース要素のサブツリーをフィルター処理して、一致する `DebugElement` を見つける述語を受け取ります。

述語は、`DebugElement` を受け取り、_真偽値_ を返す任意のメソッドです。
次の例は、"content" という名前のテンプレートローカル変数への参照を持つすべての `DebugElements` を見つけます。

```ts
// Filter for DebugElements with a #content reference
const contentRefs = el.queryAll((de) => de.references['content']);
```

Angularの `By` クラスには、一般的な述語の3つの静的メソッドがあります。

```ts
// Can find DebugElement either by css selector or by directive
const h2 = fixture.debugElement.query(By.css('h2'));
const directive = fixture.debugElement.query(By.directive(Highlight));
```
# コンポーネントハーネスの概要

<strong>コンポーネントハーネス</strong>は、テストがサポートされているAPIを介してエンドユーザーと同じ方法でコンポーネントと対話できるようにするクラスです。小さな再利用可能なウィジェットからフルページまで、あらゆるコンポーネントのテストハーネスを作成できます。

ハーネスにはいくつかの利点があります:

- コンポーネントのDOM構造などの実装詳細から自身を隔離することで、テストの脆さを軽減します
- テストの可読性を高め、保守を容易にします
- 複数のテスト環境で使用できます

```typescript
// Example of test with a harness for a component called MyButtonComponent
it('should load button with exact text', async () => {
  const button = await loader.getHarness(MyButtonComponentHarness);
  expect(await button.getText()).toBe('Confirm');
});
```
コンポーネントハーネスは、共有UIウィジェットに特に役立ちます。開発者は、DOM構造やCSSクラスなど、ウィジェットのプライベートな実装詳細に依存するテストを記述することがよくあります。これらの依存関係はテストを脆くし、保守を困難にします。ハーネスは代替手段を提供します。それは、エンドユーザーと同じ方法でウィジェットと対話するサポートされたAPIです。ウィジェットの実装変更がユーザーテストを壊す可能性は低くなります。例えば、[Angular Material](https://material.angular.dev/components/categories)は、ライブラリ内の各コンポーネントにテストハーネスを提供しています。

コンポーネントハーネスは複数のテスト環境をサポートしています。同じハーネス実装をユニットテストとエンドツーエンドテストの両方で使用できます。テスト作成者は1つのAPIを学ぶだけでよく、コンポーネント作成者は個別のユニットテストとエンドツーエンドテストの実装を保守する必要がありません。

多くの開発者は、以下の開発者タイプカテゴリーのいずれかに分類できます: テスト作成者、コンポーネントハーネス作成者、ハーネス環境作成者。以下の表を使用して、これらのカテゴリーに基づいてこのガイドの最も関連性の高いセクションを見つけてください:

| 開発者タイプ              | 説明                                                                                                                                                                                                                                                                                            | 関連セクション                                                                                             |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| テスト作成者                | 他の誰かが作成したコンポーネントハーネスを使用してアプリケーションをテストする開発者。例えば、サードパーティのメニューコンポーネントを使用し、ユニットテストでそのメニューと対話する必要があるアプリケーション開発者などがこれに該当します。                                                                       | [テストでのコンポーネントハーネスの使用](guide/testing/using-component-harnesses)                                |
| コンポーネントハーネス作成者   | 再利用可能なAngularコンポーネントを保守し、ユーザーがテストで使用するためのテストハーネスを作成したい開発者。例えば、サードパーティのAngularコンポーネントライブラリの作成者や、大規模なAngularアプリケーション向けに共通コンポーネントのセットを保守する開発者などがこれに該当します。             | [コンポーネントハーネスの作成](guide/testing/creating-component-harnesses)               |
| ハーネス環境作成者 | 追加のテスト環境でコンポーネントハーネスを使用するためのサポートを追加したい開発者。すぐに利用できるサポートされているテスト環境については、[テストハーネス環境とローダー](guide/testing/using-component-harnesses#test-harness-environments-and-loaders)を参照してください。 | [テスト環境にハーネスサポートを追加する](guide/testing/component-harnesses-testing-environments) |

完全なAPIリファレンスについては、[Angular CDKのコンポーネントハーネスAPIリファレンスページ](/api#angular_cdk_testing)を参照してください。
# テストでコンポーネントハーネスを使う

## 始める前に

TIP: このガイドは、すでに[コンポーネントハーネスの概要ガイド](guide/testing/component-harnesses-overview)を読んでいることを前提としています。コンポーネントハーネスの利用が初めての場合は、まずそちらを読んでください。

### CDKのインストール {#cdk-installation}

[Component Dev Kit (CDK)](https://material.angular.dev/cdk/categories)は、コンポーネントを構築するための動作プリミティブのセットです。コンポーネントハーネスを使用するには、まずnpmから`@angular/cdk`をインストールします。これは、Angular CLIを使用してターミナルから実行できます。

```shell
ng add @angular/cdk
```

## テストハーネス環境とローダー

コンポーネントテストハーネスはさまざまなテスト環境で使用できます。AngularCDKは2つの組み込み環境をサポートしています。

- Angularの`TestBed`を使用した単体テスト
- [WebDriver](https://developer.mozilla.org/en-US/docs/Web/WebDriver)を使用したエンドツーエンドテスト

各環境は<strong>ハーネスローダー</strong>を提供します。ローダーはテスト全体で使用するハーネスインスタンスを作成します。サポートされているテスト環境に関するより具体的なガイダンスについては、以下を参照してください。

追加のテスト環境にはカスタムバインディングが必要です。詳細については、[追加のテスト環境へのハーネスサポートの追加ガイド](guide/testing/component-harnesses-testing-environments)を参照してください。

### 単体テストでの`TestbedHarnessEnvironment`からのローダーの使用 {#using-the-loader-from-testbedharnessenvironment-for-unit-tests}

単体テストでは、[TestbedHarnessEnvironment](/api/cdk/testing/TestbedHarnessEnvironment)からハーネスローダーを作成できます。この環境は、Angularの`TestBed`によって作成された[コンポーネントフィクスチャ](api/core/testing/ComponentFixture)を使用します。

フィクスチャのルート要素にルートを持つハーネスローダーを作成するには、`loader()`メソッドを使用します。

```ts
const fixture = TestBed.createComponent(MyComponent);

// Create a harness loader from the fixture
const loader = TestbedHarnessEnvironment.loader(fixture);
...

// Use the loader to get harness instances
const myComponentHarness = await loader.getHarness(MyComponent);
```

フィクスチャの外部にある要素のハーネス用のハーネスローダーを作成するには、`documentRootLoader()`メソッドを使用します。たとえば、フローティング要素やポップアップを表示するコードは、AngularCDKの`Overlay`サービスのように、DOM要素をドキュメントボディに直接アタッチすることがよくあります。

また、そのフィクスチャのルート要素にあるハーネス用に、`harnessForFixture()`を使用してハーネスローダーを直接作成できます。

### エンドツーエンドテストでの`SeleniumWebDriverHarnessEnvironment`からのローダーの使用 {#using-the-loader-from-seleniumwebdriverharnessenvironment-for-end-to-end-tests}

WebDriverベースのエンドツーエンドテストでは、`SeleniumWebDriverHarnessEnvironment`を使用してハーネスローダーを作成できます。

現在のHTMLドキュメントのハーネスローダーインスタンスを、ドキュメントのルート要素にルートを持つ形で取得するには、`loader()`メソッドを使用します。この環境はWebDriverクライアントを使用します。

```ts
let wd: webdriver.WebDriver = getMyWebDriverClient();
const loader = SeleniumWebDriverHarnessEnvironment.loader(wd);
...
const myComponentHarness = await loader.getHarness(MyComponent);
```

## ハーネスローダーの使用 {#using-a-harness-loader}

ハーネスローダーインスタンスは特定のDOM要素に対応し、その特定の要素配下の要素に対してコンポーネントハーネスインスタンスを作成するために使用されます。

要素の最初のインスタンスの`ComponentHarness`を取得するには、`getHarness()`メソッドを使用します。すべての`ComponentHarness`インスタンスを取得するには、`getAllHarnesses()`メソッドを使用します。

```ts
// Get harness for first instance of the element
const myComponentHarness = await loader.getHarness(MyComponent);

// Get harnesses for all instances of the element
const myComponentHarnesses = await loader.getHarnesses(MyComponent);
```

`getHarness`と`getAllHarnesses`に加えて、`HarnessLoader`にはハーネスを検索するためのその他の有用なメソッドがいくつかあります。

- `getHarnessAtIndex(...)`: 特定のインデックスで指定された条件に一致するコンポーネントのハーネスを取得します。
- `countHarnesses(...)`: 指定された条件に一致するコンポーネントインスタンスの数をカウントします。
- `hasHarness(...)`: 指定された条件に一致するコンポーネントインスタンスが少なくとも1つ存在するかどうかを確認します。

例として、クリック時にダイアログを開く再利用可能なダイアログボタンコンポーネントを考えます。これには、それぞれに対応するハーネスを持つ以下のコンポーネントが含まれています。

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

### 異なる環境でのハーネスの動作 {#harness-behavior-in-different-environments}

ハーネスは、すべての環境でまったく同じように動作するとは限りません。実際のユーザーインタラクションと単体テストで生成されるシミュレートされたイベントの間には、避けられない違いがあります。Angular CDKは、可能な限り動作を正規化するために最善を尽くします。

### 子要素とのインタラクション {#interacting-with-child-elements}

このハーネスローダーのルート要素より下位の要素とインタラクトするには、子要素の`HarnessLoader`インスタンスを使用します。子要素の最初のインスタンスには`getChildLoader()`メソッドを、すべての子要素のインスタンスには`getAllChildLoaders()`メソッドを使用します。

```ts
const myComponentHarness = await loader.getHarness(MyComponent);

// Get loader for first instance of child element with '.child' selector
const childLoader = await myComponentHarness.getLoader('.child');

// Get loaders for all instances of child elements with '.child' selector
const allChildLoaders = await myComponentHarness.getAllChildLoaders('.child');
```

### ハーネスのフィルタリング {#filtering-harnesses}

ページに特定のコンポーネントの複数のインスタンスが含まれている場合、特定のコンポーネントインスタンスを取得するために、コンポーネントの何らかのプロパティに基づいてフィルタリングしたい場合があります。これを行うには、<strong>ハーネス述語</strong>を使用できます。これは、`ComponentHarness`クラスを、コンポーネントインスタンスをフィルタリングするために使用できる述語関数と関連付けるために使用されるクラスです。

`HarnessLoader`にハーネスを要求するとき、実際にはHarnessQueryを提供しています。クエリは次の2つのいずれかです。

- ハーネスコンストラクター。これは単にそのハーネスを取得します
- `HarnessPredicate`。これは1つ以上の条件に基づいてフィルタリングされたハーネスを取得します

`HarnessPredicate`は、`ComponentHarness`を拡張するあらゆるものに機能するいくつかの基本フィルター（selector、ancestor）をサポートしています。

```ts
// Example of loading a MyButtonComponentHarness with a harness predicate
const disabledButtonPredicate = new HarnessPredicate(MyButtonComponentHarness, {
  selector: '[disabled]',
});
const disabledButton = await loader.getHarness(disabledButtonPredicate);
```

ただし、ハーネスがコンポーネント固有のフィルタリングオプションを受け入れ、`HarnessPredicate`を返す静的`with()`メソッドを実装することは一般的です。

```ts
// Example of loading a MyButtonComponentHarness with a specific selector
const button = await loader.getHarness(MyButtonComponentHarness.with({selector: 'btn'}));
```

追加のフィルタリングオプションは各ハーネスの実装に固有であるため、詳細については特定のハーネスのドキュメントを参照してください。

## テストハーネスAPIの使用 {#using-test-harness-apis}

各ハーネスは対応するコンポーネントに固有のAPIを定義していますが、それらはすべて共通の基底クラスである[ComponentHarness](/api/cdk/testing/ComponentHarness)を共有しています。この基底クラスは、ハーネスクラスをDOM内のコンポーネントインスタンスに一致させる静的プロパティ`hostSelector`を定義します。

それ以外に、特定のハーネスのAPIは対応するコンポーネントに固有です。特定のハーネスの使用方法については、コンポーネントのドキュメントを参照してください。

例として、[Angular Materialスライダーコンポーネントハーネス](https://material.angular.dev/components/slider/api#MatSliderHarness)を使用するコンポーネントのテストを以下に示します。

```ts
it('should get value of slider thumb', async () => {
  const slider = await loader.getHarness(MatSliderHarness);
  const thumb = await slider.getEndThumb();
  expect(await thumb.getValue()).toBe(50);
});
```

## Angularの変更検知との連携 {#interop-with-angular-change-detection}

デフォルトでは、テストハーネスはAngularの[変更検知](/best-practices/runtime-performance)をDOM要素の状態を読み取る前と、DOM要素と対話した後に実行します。

テストで変更検知をより細かく制御する必要がある場合があります。例えば、非同期操作が保留中の間にコンポーネントの状態を確認する場合などです。このような場合は、`manualChangeDetection`関数を使用して、コードブロックの変更検知の自動処理を無効にします。

```ts
it('checks state while async action is in progress', async () => {
  const buttonHarness = loader.getHarness(MyButtonHarness);
  await manualChangeDetection(async () => {
    await buttonHarness.click();
    fixture.detectChanges();
    // Check expectations while async click operation is in progress.
    expect(isProgressSpinnerVisible()).toBe(true);
    await fixture.whenStable();
    // Check expectations after async click operation complete.
    expect(isProgressSpinnerVisible()).toBe(false);
  });
});
```

ほとんどすべてのハーネスメソッドは非同期であり、以下をサポートするために`Promise`を返します。

- 単体テストのサポート
- エンドツーエンドテストのサポート
- 非同期動作の変更からテストを保護

Angularチームは、テストの可読性を向上させるために[await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)の使用を推奨しています。`await`を呼び出すと、関連する`Promise`が解決されるまでテストの実行がブロックされます。

場合によっては、複数のアクションを同時に実行し、それぞれのアクションを順次実行するのではなく、すべてが完了するまで待機したい場合があります。例えば、単一コンポーネントの複数のプロパティを読み取る場合などです。このような状況では、`parallel`関数を使用して操作を並列化します。`parallel`関数は`Promise.all`と同様に機能し、変更検知チェックも最適化します。

```ts
it('reads properties in parallel', async () => {
  const checkboxHarness = loader.getHarness(MyCheckboxHarness);
  // Read the checked and intermediate properties simultaneously.
  const [checked, indeterminate] = await parallel(() => [
    checkboxHarness.isChecked(),
    checkboxHarness.isIndeterminate(),
  ]);
  expect(checked).toBe(false);
  expect(indeterminate).toBe(true);
});
```
# コンポーネントハーネスを作成する

## 始める前に {#before-you-start}

TIP: このガイドは、[コンポーネントハーネスの概要ガイド](guide/testing/component-harnesses-overview)をすでに読んでいることを前提としています。コンポーネントハーネスの使用が初めての場合は、まずそちらをお読みください。

### テストハーネスの作成はどのような場合に意味がありますか？ {#when-does-creating-a-test-harness-make-sense}

Angularチームは、多くの場所で使用され、ユーザーインタラクティビティを持つ共有コンポーネントに対して、コンポーネントテストハーネスを作成することを推奨しています。これはウィジェットライブラリや同様の再利用可能なコンポーネントに最も一般的に適用されます。ハーネスは、これらの共有コンポーネントの利用者に、コンポーネントと対話するための十分にサポートされたAPIを提供するため、これらのケースで価値があります。ハーネスを使用するテストは、DOM構造や特定のイベントリスナーなど、これらの共有コンポーネントの信頼性の低い実装詳細に依存することを避けることができます。

アプリケーション内のページなど、1か所にのみ出現するコンポーネントの場合、ハーネスはそれほど多くの利点を提供しません。このような状況では、テストとコンポーネントが同時に更新されるため、コンポーネントのテストは、そのコンポーネントの実装詳細に合理的に依存できます。ただし、ユニットテストとエンドツーエンドテストの両方でハーネスを使用する場合、ハーネスは依然としていくつかの価値を提供します。

### CDKのインストール {#cdk-installation}

```shell
ng add @angular/cdk
```

## ComponentHarnessの拡張 {#extending-componentharness}

抽象クラス`ComponentHarness`は、すべてのコンポーネントハーネスの基底クラスです。カスタムコンポーネントハーネスを作成するには、`ComponentHarness`を拡張し、静的プロパティ`hostSelector`を実装します。

`hostSelector`プロパティは、このハーネスサブクラスに一致するDOM内の要素を識別します。ほとんどの場合、`hostSelector`は対応する`Component`または`Directive`のセレクターと同じである必要があります。例えば、シンプルなポップアップコンポーネントを考えてみましょう。

```ts
@Component({
  selector: 'my-popup',
  template: `
    <button (click)="toggle()">{{ triggerText() }}</button>
    @if (isOpen()) {
      <div class="my-popup-content"><ng-content></ng-content></div>
    }
  `,
})
class MyPopup {
  triggerText = input('');

isOpen = signal(false);

toggle() {
    this.isOpen.update((value) => !value);
  }
}
```

この場合、コンポーネントの最小限のハーネスは次のようになります。

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';
}
```

`ComponentHarness`のサブクラスは`hostSelector`プロパティのみを必要としますが、ほとんどのハーネスは`HarnessPredicate`インスタンスを生成するために静的な`with`メソッドも実装する必要があります。[ハーネスのフィルタリングセクション](guide/testing/using-component-harnesses#filtering-harnesses)で、これについて詳しく説明しています。

## コンポーネントのDOM内の要素を見つける {#finding-elements-in-the-component's-dom}

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

// Gets the trigger element
  getTriggerElement = this.locatorFor('button');

// Gets the content element.
  getContentElement = this.locatorForOptional('.my-popup-content');
}
```

## TestElementインスタンスの操作 {#working-with-testelement-instances}

`TestElement`は、さまざまなテスト環境（Unit tests, WebDriverなど）で動作するように設計された抽象化です。ハーネスを使用する場合、すべてのDOM操作はこのインターフェースを介して実行する必要があります。`document.querySelector()`のようなDOM要素にアクセスする他の手段は、すべてのテスト環境で機能するわけではありません。

`TestElement`には、`blur()`、`click()`、`getAttribute()`など、基になるDOMと対話するための多数のメソッドがあります。メソッドの完全なリストについては、[TestElement API reference page](/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');

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

## サブコンポーネントのハーネスのロード {#loading-harnesses-for-subcomponents}

より大きなコンポーネントは、しばしばサブコンポーネントで構成されます。この構造は、コンポーネントのハーネスにも反映できます。`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('');

@ContentChildren(MyMenuItem) items: QueryList<MyMenuItem>;
}
```

これにより、`MyMenu`のハーネスは、`MyPopup`および`MyMenuItem`の他のハーネスを利用できます。

```ts
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

protected getPopupHarness = this.locatorFor(MyPopupHarness);

/** Gets the currently shown menu items (empty list if menu is closed). */
  getItems = this.locatorForAll(MyMenuItemHarness);

/** Toggles open state of the menu. */
  async toggle() {
    const popupHarness = await this.getPopupHarness();
    return popupHarness.toggle();
  }
}

class MyMenuItemHarness extends ComponentHarness {
  static hostSelector = 'my-menu-item';
}
```

## HarnessPredicateによるハーネスインスタンスのフィルタリング {#filtering-harness-instances-with-harnesspredicate}

ページに特定のコンポーネントの複数のインスタンスが含まれている場合、特定のコンポーネントインスタンスを取得するために、コンポーネントの何らかのプロパティに基づいてフィルタリングしたい場合があります。例えば、特定のテキストを持つボタンや、特定のIDを持つメニューが必要になるかもしれません。`HarnessPredicate`クラスは、`ComponentHarness`サブクラスに対してこのような条件を捕捉できます。テスト作成者が`HarnessPredicate`インスタンスを手動で構築できますが、`ComponentHarness`サブクラスが一般的なフィルター用の述語を構築するヘルパーメソッドを提供すると、より簡単になります。

各`ComponentHarness`サブクラスに、そのクラスの`HarnessPredicate`を返す静的`with()`メソッドを作成する必要があります。これにより、テスト作成者は`loader.getHarness(MyMenuHarness.with({selector: '#menu1'}))`のような、理解しやすいコードを書くことができます。標準セレクターと祖先オプションに加えて、`with`メソッドは、特定のサブクラスに意味のある他のオプションを追加する必要があります。

追加オプションを追加する必要があるハーネスは、`BaseHarnessFilters`インターフェースを拡張し、必要に応じて追加のオプションプロパティを追加する必要があります。`HarnessPredicate`は、オプションを追加するためのいくつかの便利なメソッドを提供します: `stringMatches()`、`addOption()`、および`add()`。詳細については、[HarnessPredicate APIページ](/api/cdk/testing/HarnessPredicate)を参照してください。

例えば、メニューを操作する場合、トリガーテキストに基づいてフィルタリングしたり、メニュー項目をそのテキストに基づいてフィルタリングしたりすると便利です。

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

`HarnessLoader`、`LocatorFactory`、または`ComponentHarness`のいずれかのAPIに、`ComponentHarness`クラスの代わりに`HarnessPredicate`を渡すことができます。これにより、テスト作成者はハーネスインスタンスを作成する際に、特定のコンポーネントインスタンスを簡単にターゲットにできます。また、ハーネス作成者は同じ`HarnessPredicate`を活用して、ハーネスクラスでより強力なAPIを有効にできます。例えば、上記の`MyMenuHarness`の`getItems`メソッドを考えてみましょう。フィルタリングAPIを追加することで、ハーネスのユーザーは特定のメニュー項目を検索できるようになります。

```ts
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

/** Gets a list of items in the menu, optionally filtered based on the given criteria. */
  async getItems(filters: MyMenuItemHarnessFilters = {}): Promise<MyMenuItemHarness[]> {
    const getFilteredItems = this.locatorForAll(MyMenuItemHarness.with(filters));
    return getFilteredItems();
  }
  ...
}
```

## コンテンツプロジェクションを使用する要素のための`HarnessLoader`の作成 {#creating-harnessloader-for-elements-that-use-content-projection}

一部のコンポーネントは、追加のコンテンツをコンポーネントのテンプレートに投影します。詳細については、[コンテンツプロジェクションガイド](guide/components/content-projection)を参照してください。

コンテンツプロジェクションを使用するコンポーネントのハーネスを作成する際には、`<ng-content>`を含む要素にスコープされた`HarnessLoader`インスタンスを追加します。これにより、ハーネスのユーザーは、コンテンツとして渡されたコンポーネントのために追加のハーネスをロードできます。`ComponentHarness`には、このような場合に`HarnessLoader`インスタンスを作成するために使用できるいくつかのメソッドがあります:`harnessLoaderFor()`、`harnessLoaderForOptional()`、`harnessLoaderForAll()`。詳細については、[HarnessLoaderインターフェースAPIリファレンスページ](/api/cdk/testing/HarnessLoader)を参照してください。

例えば、上記の`MyPopupHarness`の例は、コンポーネントの`<ng-content>`内でハーネスをロードするサポートを追加するために、`ContentContainerComponentHarness`を拡張できます。

```ts
class MyPopupHarness extends ContentContainerComponentHarness<string> {
  static hostSelector = 'my-popup';
}
```

## コンポーネントのホスト要素外の要素へのアクセス {#accessing-elements-outside-of-the-component's-host-element}

コンポーネントハーネスが、対応するコンポーネントのホスト要素外の要素にアクセスする必要がある場合があります。たとえば、フローティング要素やポップアップを表示するコードは、Angular CDKの`Overlay`サービスのように、DOM要素をドキュメントボディに直接アタッチすることがよくあります。

この場合、`ComponentHarness`は、ドキュメントのルート要素の`LocatorFactory`を取得するために使用できるメソッドを提供します。`LocatorFactory`は、`ComponentHarness`基底クラスとほとんど同じAPIをサポートしており、ドキュメントのルート要素を基準にクエリするために使用できます。

上記の`MyPopup`コンポーネントが、自身のテンプレート内の要素ではなく、ポップアップコンテンツにCDKオーバーレイを使用した場合を考えてみましょう。この場合、`MyPopupHarness`は、ドキュメントルートにルートを持つロケーターファクトリを取得する`documentRootLocatorFactory()`メソッドを介してコンテンツ要素にアクセスする必要があります。

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

/** Gets a `HarnessLoader` whose root element is the popup's content element. */
  async getHarnessLoaderForContent(): Promise<HarnessLoader> {
    const rootLocator = this.documentRootLocatorFactory();
    return rootLocator.harnessLoaderFor('my-popup-content');
  }
}
```

## 非同期タスクの待機 {#waiting-for-asynchronous-tasks}

`TestElement`のメソッドは、Angularの変更検知を自動的にトリガーし、`NgZone`内のタスクを待機します。ほとんどの場合、ハーネスの作成者が非同期タスクを待機するために特別な努力は必要ありません。しかし、これが十分でないエッジケースがいくつかあります。

特定の状況下では、Angularアニメーションは、アニメーションイベントが完全にフラッシュされる前に、変更検知の2回目のサイクルとそれに続く`NgZone`の安定化を必要とする場合があります。これが必要な場合、`ComponentHarness`は2回目の処理を行うために呼び出すことができる`forceStabilize()`メソッドを提供します。

`NgZone.runOutsideAngular()`を使用して、NgZone外でタスクをスケジュールできます。自動的に行われないため、`NgZone`外のタスクを明示的に待機する必要がある場合は、対応するハーネスで`waitForTasksOutsideAngular()`メソッドを呼び出してください。
# `animate.enter`と`animate.leave`を使ったアプリケーションのアニメーション

適切に設計されたアニメーションは、アプリケーションをより楽しく、分かりやすく使用できるようにしますが、単なる装飾ではありません。
アニメーションは、いくつかの方法でアプリケーションとユーザー体験を向上させることができます。

- アニメーションがないと、ウェブページの遷移は突然で不快に感じられることがあります
- モーションはユーザー体験を大幅に向上させるため、アニメーションはユーザーが自分のアクションに対するアプリケーションの応答を検出する機会を与えます
- 優れたアニメーションは、ワークフロー全体でユーザーの注意をスムーズに誘導できます

Angularは、アプリケーションの要素をアニメーション化するために`animate.enter`と`animate.leave`を提供します。これら2つの機能は、適切なタイミングでenterおよびleaveのCSSクラスを適用するか、サードパーティライブラリからアニメーションを適用する関数を呼び出します。`animate.enter`と`animate.leave`はディレクティブではありません。これらはAngularコンパイラによって直接サポートされる特別なAPIです。これらは要素に直接使用できるほか、ホストバインディングとしても使用できます。

## `animate.enter`

`animate.enter`はDOMに_入る_要素をアニメーション化するために使用できます。CSSクラスと、transitionまたはキーフレームアニメーションのいずれかを使用して、enterアニメーションを定義できます。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.ts">
    <docs-code header="enter.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.ts" />
    <docs-code header="enter.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.html" />
    <docs-code header="enter.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.css"/>
</docs-code-multifile>

アニメーションが完了すると、Angularは`animate.enter`で指定したクラスをDOMから削除します。アニメーションクラスは、アニメーションがアクティブな間のみ存在します。

NOTE: 要素で複数のキーフレームアニメーションまたはtransitionプロパティを使用している場合、Angularは最も長いアニメーションが完了した_後にのみ_すべてのクラスを削除します。

`animate.enter`は、制御フローや動的式など、他のAngular機能と組み合わせて使用できます。`animate.enter`は、単一のクラス文字列（複数のクラスがスペースで区切られているもの）またはクラス文字列の配列を受け入れます。

CSSトランジションの使用についての簡単な注意：キーフレームアニメーションの代わりにトランジションを使用することを選択した場合、`animate.enter`で要素に追加されるクラスは、トランジションがアニメーション_する先の_状態を表します。基本要素のCSSは、アニメーションが実行されないときの要素の外観であり、CSSトランジションの終了状態に似ている可能性があります。そのため、トランジションが機能するために適切な_from_状態を持つために、`@starting-style`と組み合わせる必要があります。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.ts">
    <docs-code header="enter-binding.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.ts" />
    <docs-code header="enter-binding.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.html" />
    <docs-code header="enter-binding.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.css"/>
</docs-code-multifile>

## `animate.leave`

`animate.leave` を使用して、要素がDOMから_離れる_ときにアニメーションを適用できます。CSSクラスと、transformまたはキーフレームアニメーションのいずれかを使用して、離脱アニメーションを定義できます。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.ts">
    <docs-code header="leave.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.ts" />
    <docs-code header="leave.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.html" />
    <docs-code header="leave.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.css"/>
</docs-code-multifile>

アニメーションが完了すると、Angularはアニメーション化された要素をDOMから自動的に削除します。

NOTE: 要素に複数のキーフレームアニメーションまたはtransitionプロパティを使用する場合、Angularはそれらのアニメーションの中で最も長いものが完了した_後にのみ_要素を削除します。

`animate.leave` はsignalsやその他のbindingでも使用できます。`animate.leave` は単一のクラスまたは複数のクラスで使用できます。スペースで区切られた単純な文字列として指定するか、文字列配列として指定します。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.ts">
    <docs-code header="leave-binding.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.ts" />
    <docs-code header="leave-binding.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.html" />
    <docs-code header="leave-binding.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.css"/>
</docs-code-multifile>

## イベントバインディング、関数、およびサードパーティライブラリ {#event-bindings-functions-and-third-party-libraries}

`animate.enter`と`animate.leave`はどちらも、関数呼び出しを可能にするイベントバインディング構文をサポートしています。この構文を使用して、コンポーネントコード内の関数を呼び出したり、[GSAP](https://gsap.com/)、[anime.js](https://animejs.com/)などのサードパーティのアニメーションライブラリ、またはその他のJavaScriptアニメーションライブラリを利用したり可能です。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.ts">
    <docs-code header="leave-event.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.ts" />
    <docs-code header="leave-event.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.html" />
    <docs-code header="leave-event.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.css"/>
</docs-code-multifile>

`$event`オブジェクトは`AnimationCallbackEvent`型です。これには`target`として要素が含まれ、アニメーションが終了したときにフレームワークに通知するための`animationComplete()`関数を提供します。

IMPORTANT: Angularが要素を削除するためには、`animate.leave`を使用する際に`animationComplete()`関数を**必ず**呼び出す必要があります。

`animate.leave`を使用する際に`animationComplete()`を呼び出さない場合、Angularは4秒の遅延後に自動的にその関数を呼び出します。遅延の期間は、`MAX_ANIMATION_TIMEOUT`トークンをミリ秒単位で提供することにより設定できます。

```typescript
{ provide: MAX_ANIMATION_TIMEOUT, useValue: 6000 }
```

## レガシーAngularアニメーションとの互換性 {#compatibility-with-legacy-angular-animations}

同じコンポーネント内でレガシーアニメーションと`animate.enter`および`animate.leave`を一緒に使用できません。そうすると、enterクラスが要素に残ったり、leavingノードが削除されなかったりします。それ以外では、同じ_アプリケーション_内でレガシーアニメーションと新しい`animate.enter`および`animate.leave`アニメーションの両方を使用することは問題ありません。唯一の注意点はコンテンツプロジェクションです。レガシーアニメーションを持つコンポーネントから`animate.enter`または`animate.leave`を持つ別のコンポーネントにコンテンツをプロジェクトする場合、またはその逆の場合、これは同じコンポーネント内で一緒に使用した場合と同じ動作になります。これはサポートされていません。

## テスト {#testing}

TestBedは、テスト環境でアニメーションを有効または無効にするための組み込みサポートを提供します。CSSアニメーションはブラウザでの実行が必要であり、多くのAPIはテスト環境では利用できません。デフォルトでは、TestBedはテスト環境でアニメーションを無効にします。

ブラウザテスト、例えばエンドツーエンドテストでアニメーションが動作していることをテストしたい場合は、テスト設定で`animationsEnabled: true`を指定することで、TestBedをアニメーションを有効にするように設定できます。

```typescript
TestBed.configureTestingModule({animationsEnabled: true});
```

これにより、テスト環境でのアニメーションが通常通りに動作するように設定されます。

NOTE: 一部のテスト環境では、`animationstart`、`animationend`のようなアニメーションイベントや、それらに相当するトランジションイベントを発行しません。

## Angularアニメーションについてさらに詳しく

以下の項目にも興味があるかもしれません：
# Animating your Application with CSS

CSS offers a robust set of tools for you to create beautiful and engaging animations within your application.

## How to write animations in native CSS

If you've never written any native CSS animations, there are a number of excellent guides to get you started. Here's 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 some of these various guides and tutorials out, and then come back to this guide.

## Creating Reusable Animations

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.

## Animating a Transition

### Animating State and Styles

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 using 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).

### Transitions, Timing, and Easing

Animating often requires adjusting timing, delays and easeing 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"/>

### Triggering an Animation

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.component.ts">
    <docs-code header="open-close.component.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts" />
    <docs-code header="open-close.component.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.html" />
    <docs-code header="open-close.component.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.css"/>
</docs-code-multifile>

## Transition and Triggers

### Animating Auto Height

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.component.ts">
    <docs-code header="auto-height.component.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts" />
    <docs-code header="auto-height.component.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.html" />
    <docs-code header="auto-height.component.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.css"  />
</docs-code-multifile>

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.

### Animate entering and leaving a view

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.component.ts">
    <docs-code header="insert.component.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts" />
    <docs-code header="insert.component.html" path="adev/src/content/examples/animations/src/app/native-css/insert.component.html" />
    <docs-code header="insert.component.css" path="adev/src/content/examples/animations/src/app/native-css/insert.component.css"  />
</docs-code-multifile>

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.component.ts">
    <docs-code header="remove.component.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts" />
    <docs-code header="remove.component.html" path="adev/src/content/examples/animations/src/app/native-css/remove.component.html" />
    <docs-code header="remove.component.css" path="adev/src/content/examples/animations/src/app/native-css/remove.component.css"  />
</docs-code-multifile>

For more information on `animate.enter` and `animate.leave`, see the [Enter and Leave animations guide](guide/animations).

### Animating increment and decrement

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.component.ts">
    <docs-code header="increment-decrement.component.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts" />
    <docs-code header="increment-decrement.component.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.html" />
    <docs-code header="increment-decrement.component.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.css" />
</docs-code-multifile>

### Disabling an animation or all 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;
}
```

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 programatically

### Animation Callbacks

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/animationitration_event)  
[`OnAnimationCancel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationcancel_event)

[`OnTransitionStart`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionstart_event)  
[`OnTransitionRun`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionrun_event)  
[`OnTransitionEnd`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionend_event)  
[`OnTransitionCancel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitioncancel_event)

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.

## Complex Sequences

Animations are often more complicated than just a simple fade in or fade out. You may have lots of complicated sequences of animations you may want to run. Let's take a look at some of those possible scenarios.

### Staggering animations in a list

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.component.ts">
    <docs-code header="stagger.component.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts" />
    <docs-code header="stagger.component.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.html" />
    <docs-code header="stagger.component.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.css" />
</docs-code-multifile>

### Parallel Animations

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.

### Animating the items of a reordering list

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.component.ts">
    <docs-code header="reorder.component.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts" />
    <docs-code header="reorder.component.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.html" />
    <docs-code header="reorder.component.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.css" />
</docs-code-multifile>

## Programmatic control of animations

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.

## More on Angular animations

You might also be interested in the following:
# ルート遷移アニメーション

ルート遷移アニメーションは、Angularアプリケーション内の異なるビュー間を移動する際にスムーズな視覚的遷移を提供することで、ユーザー体験を向上させます。[Angular Router](/guide/routing/overview)は、ブラウザのView Transitions APIの組み込みサポートを含んでおり、サポートされているブラウザでルート変更間のシームレスなアニメーションを可能にします。

HELPFUL: RouterのネイティブView Transitions統合は現在[デベロッパープレビュー](/reference/releases#developer-preview)中です。ネイティブView Transitionsは比較的新しいブラウザ機能であり、すべてのブラウザでのサポートは限られています。

## Viewトランジションの仕組み {#how-view-transitions-work}

Viewトランジションは、ブラウザのネイティブな[`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 Explainer](https://developer.chrome.com/docs/web-platform/view-transitions)を参照してください。

## Routerがビュー遷移をどのように使用するか {#how-the-router-uses-view-transitions}

Angular Routerは、シームレスなルート変更を作成するために、ナビゲーションライフサイクルにビュー遷移を統合します。ナビゲーション中、Routerは以下を行います。

1. **ナビゲーションの準備を完了する** - ルートのマッチング、[遅延ロード](/guide/routing/define-routes#lazily-loaded-components)、[ガード](/guide/routing/route-guards)、および[リゾルバー](/guide/routing/data-resolvers)が実行されます
2. **ビュー遷移を開始する** - ルートがアクティベーションの準備ができたときに、Routerは`startViewTransition`を呼び出します
3. **DOMを更新する** - Routerは、遷移コールバック内で新しいルートをアクティブ化し、古いルートを非アクティブ化します
4. **遷移を完了する** - Angularがレンダリングを完了すると、遷移Promiseが解決されます

Routerのビュー遷移統合は[プログレッシブエンハンスメント](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement)として機能します。ブラウザがView Transitions APIをサポートしていない場合、Routerはアニメーションなしで通常のDOMを更新し、アプリケーションがすべてのブラウザで動作することを保証します。

## ルーターでのビュー遷移の有効化 {#enabling-view-transitions-in-the-router}

ビュー遷移を有効にするには、`withViewTransitions`機能を[ルーター設定](/guide/routing/define-routes#adding-the-router-to-your-application)に追加します。Angularは、スタンドアロンとNgModuleの両方のブートストラップアプローチをサポートしています。

### スタンドアロンブートストラップ {#standalone-bootstrap}

```ts
import {bootstrapApplication} from '@angular/platform-browser';
import {provideRouter, withViewTransitions} from '@angular/router';
import {routes} from './app.routes';

bootstrapApplication(MyApp, {
  providers: [provideRouter(routes, withViewTransitions())],
});
```

### NgModuleブートストラップ {#ngmodule-bootstrap}

```ts
import {NgModule} from '@angular/core';
import {RouterModule} from '@angular/router';

@NgModule({
  imports: [RouterModule.forRoot(routes, {enableViewTransitions: true})],
})
export class AppRouting {}
```

[StackBlitzで「count」の例を試す](https://stackblitz.com/edit/stackblitz-starters-2dnvtm?file=src%2Fmain.ts)

この例は、カウンターの更新に対して、ルーターナビゲーションが直接の`startViewTransition`呼び出しを置き換えることができる方法を示しています。

## CSSでトランジションをカスタマイズする {#customizing-transitions-with-css}

CSSを使用してビューのトランジションをカスタマイズし、独自のアニメーション効果を作成できます。ブラウザは、CSSセレクターでターゲットできる個別のトランジション要素を作成します。

カスタムトランジションを作成するには：

1. **view-transition-nameを追加する** - アニメーション化したい要素に一意の名前を割り当てる
2. **グローバルアニメーションを定義する** - グローバルスタイルでCSSアニメーションを作成する
3. **トランジション擬似要素をターゲットにする** - `::view-transition-old()`および`::view-transition-new()`セレクターを使用する

カウンター要素に回転効果を追加する例を次に示します。

```css
/* Define keyframe animations */
@keyframes rotate-out {
  to {
    transform: rotate(90deg);
  }
}

@keyframes rotate-in {
  from {
    transform: rotate(-90deg);
  }
}

/* Target view transition pseudo-elements */
::view-transition-old(count),
::view-transition-new(count) {
  animation-duration: 200ms;
  animation-name: -ua-view-transition-fade-in, rotate-in;
}

::view-transition-old(count) {
  animation-name: -ua-view-transition-fade-out, rotate-out;
}
```

IMPORTANT: ビューのトランジションアニメーションは、コンポーネントスタイルではなく、グローバルスタイルファイルで定義してください。Angularの[ビューカプセル化](/guide/components/styling#view-encapsulation)はコンポーネントスタイルをスコープするため、トランジション擬似要素を正しくターゲットできなくなります。

[StackBlitzで更新された「count」の例を試す](https://stackblitz.com/edit/stackblitz-starters-fwn4i7?file=src%2Fmain.ts)

## onViewTransitionCreatedによる高度なトランジション制御 {#advanced-transition-control-with-onviewtransitioncreated}

`withViewTransitions`機能は、ビュー遷移を高度に制御するための`onViewTransitionCreated`コールバックを含むオプションオブジェクトを受け入れます。このコールバックは次のとおりです。

- [インジェクションコンテキスト](/guide/di/dependency-injection-context#run-within-an-injection-context)で実行されます
- 以下を含む[`ViewTransitionInfo`](/api/router/ViewTransitionInfo)オブジェクトを受け取ります。
  - `startViewTransition`からの`ViewTransition`インスタンス
  - ナビゲート元のルートに対する[`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot)
  - ナビゲート先のルートに対する[`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot)

このコールバックを使用して、ナビゲーションコンテキストに基づいてトランジション動作をカスタマイズできます。たとえば、特定のナビゲーションタイプではトランジションをスキップできます。

```ts
import {inject} from '@angular/core';
import {Router, withViewTransitions} from '@angular/router';

withViewTransitions({
  onViewTransitionCreated: ({transition}) => {
    const router = inject(Router);
    const targetUrl = router.currentNavigation()!.finalUrl!;

// Skip transition if only fragment or query params change
    const config = {
      paths: 'exact',
      matrixParams: 'exact',
      fragment: 'ignored',
      queryParams: 'ignored',
    };

if (router.isActive(targetUrl, config)) {
      transition.skipTransition();
    }
  },
});
```

この例では、ナビゲーションが[URLフラグメントまたはクエリパラメータ](/guide/routing/read-route-state#query-parameters)のみを変更する場合（同じページ内のアンカーリンクなど）にビュー遷移をスキップします。`skipTransition()`メソッドは、ナビゲーションの完了を許可しながらアニメーションを防止します。

## Chrome ExplainerのAngularへの適応例 {#examples-from-the-chrome-explainer-adapted-to-angular}

以下の例は、ChromeチームのドキュメントからAngular Routerで使用するために適応された、さまざまなビュー遷移テクニックを示しています。

### 遷移する要素は同じDOM要素である必要はない {#transitioning-elements-dont-need-to-be-the-same-dom-element}

要素は、同じ`view-transition-name`を共有している限り、異なるDOM要素間をスムーズに遷移できます。

- [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)

### カスタムエントリー/イグジットアニメーション {#custom-entry-and-exit-animations}

ルート遷移中にビューポートに出入りする要素に対して、ユニークなアニメーションを作成します。

- [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)

### 非同期DOM更新とコンテンツの待機 {#async-dom-updates-and-waiting-for-content}

Angular Routerは、追加コンテンツの読み込みを待つよりも、即時遷移を優先します。

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#async_dom_updates_and_waiting_for_content)

NOTE: Angular Routerはビュー遷移を遅延させる方法を提供していません。この設計上の選択により、追加コンテンツを待っている間にページが非インタラクティブになるのを防ぎます。Chromeのドキュメントが指摘するように、「この間、ページはフリーズするため、ここでの遅延は最小限に抑えるべきです…場合によっては、遅延を完全に避け、すでに持っているコンテンツを使用する方が良いでしょう。」

### ビュー遷移タイプで複数のビュー遷移スタイルを処理する {#handle-multiple-view-transition-styles-with-view-transition-types}

ナビゲーションコンテキストに基づいて異なるアニメーションスタイルを適用するために、ビュー遷移タイプを使用します。

- [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)

### ビュー遷移ルートのクラス名で複数のビュー遷移スタイルを処理する（非推奨） {#handle-multiple-view-transition-styles-with-a-class-name-on-the-view-transition-root-deprecated}

このアプローチは、遷移ルート要素のCSSクラスを使用してアニメーションスタイルを制御します。

- [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#changing-on-navigation-type)
- [Angular Example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-nmnzzg?file=src%2Fmain.ts)

### 他のアニメーションをフリーズさせずに遷移する {#transitioning-without-freezing-other-animations}

ビュー遷移中に他のページアニメーションを維持し、よりダイナミックなユーザー体験を作成します。

- [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)

### JavaScriptでアニメーション化する {#animating-with-javascript}

複雑なアニメーションシナリオのために、JavaScript APIを使用してビュー遷移をプログラムで制御します。

- [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)
# Migrating away from Angular's Animations package

The `@angular/animations` package is deprecated as of v20.2, which also introduced the new `animate.enter` and `animate.leave` feature to add animations to your application. Using these new features, you can replace all animations based on `@angular/animations` with plain CSS or JS animation libraries. Removing `@angular/animations` from your application can significantly reduce the size of your JavaScript bundle. Native CSS animations generally offer superior performance, as they can benefit from hardware acceleration. This guide walks through the process of refactoring your code from `@angular/animations` to native CSS animations.

## How to write animations in native CSS

If you've never written any native CSS animations, there are a number of excellent guides to get you started. Here's 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 some of these various guides and tutorials out, and then come back to this guide.

## Creating Reusable Animations

Just like with the animations package, you can create reusable animations that can be shared across your application. The animations package version of this had you using the `animation()` function in a shared typescript file. The native CSS version of this is similar, but lives in a shared CSS file.

#### With Animations Package

<docs-code header="animations.ts" path="adev/src/content/examples/animations/src/app/animations.1.ts" region="animation-example"/>

#### With Native 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.

## Animating a Transition

### Animating State and Styles

The animations package allowed you to define various states using the [`state()`](api/animations/state) function within a component. Examples might be an `open` or `closed` state containing the styles for each respective state within the definition. For example:

#### With Animations Package

<docs-code header="open-close.component.ts" path="adev/src/content/examples/animations/src/app/open-close.component.ts" region="state1"/>

This same behavior can be accomplished natively by using CSS classes either using a keyframe animation or transition styling.

#### 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).

### Transitions, Timing, and Easing

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"/>

### Triggering an Animation

The animations package required specifying triggers using the `trigger()` function and nesting all of your states within it. With native CSS, this is unnecessary. 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. This results in significantly less code to do the same animation. Here's an example:

#### With Animations Package
#### With Native CSS

## Transition and Triggers

### Predefined State and wildcard matching

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.

### Automatic Property Calculation with Wildcards

The animations package offers the ability to animate things that have been historically difficult to animate, like animating a set height to `height: auto`. You can now do this with pure CSS as well.

#### With Animations Package
You can use css-grid to animate to auto height.

#### With Native CSS

### Animate entering and leaving a view

The animations package offered the previously mentioned pattern matching for entering and leaving but also included the shorthand aliases of `:enter` and `:leave`.

#### With Animations Package
Here's how the same thing can be accomplished without the animations package using `animate.enter`.

#### With Native CSS

Use `animate.leave` to animate elements as they leave the view, which will apply the specified CSS classes to the element as it leaves the view.

#### With Native CSS

For more information on `animate.enter` and `animate.leave`, see the [Enter and Leave animations guide](guide/animations).

### Animating increment and decrement

Along with the aforementioned `:enter` and `:leave`, there's also `:increment` and `:decrement`. You can animate these also by adding and removing classes. Unlike the animation package built-in aliases, there is no automatic application of classes when the values go up or down. You can apply the appropriate classes programmatically. Here's an example:

#### With Animations Package
#### With Native CSS

### Parent / Child Animations

Unlike the animations package, when multiple animations are specified within a given component, no animation has priority over another and nothing blocks any animation from firing. Any sequencing of animations would have to be handled by your definition of your CSS animation, using animation / transition delay, and / or using `animationend` or `transitionend` to handle adding the next css to be animated.

### Disabling an animation or all animations

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 programatically

### Animation Callbacks

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.

## Complex Sequences

The animations package has built-in functionality for creating complex sequences. These sequences are all entirely possible without the animations package.

### Targeting specific elements

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.

### Stagger()

The `stagger()` function allowed you to delay the animation of each item in a list of items by a specified time to create a cascade effect. You can replicate this behavior in native CSS by utilizing `animation-delay` or `transition-delay`. Here is an example of what that CSS might look like.

#### With Animations Package
#### With Native CSS

### Parallel Animations

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.

### Animating the items of a reordering list

Items reordering in a list works out of the box using the previously described techniques. No additional special work is required. Items in a `@for` loop will be removed and re-added properly, 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 above.

#### With Animations Package<
#### With Native CSS

## Migrating usages of 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.

## Route Transitions

You can use view transitions to animate between routes. See the [Route Transition Animations Guide](guide/routing/route-transition-animations) to get started.
# ZoneJSを使わないAngular (Zoneless)

## なぜZonelessを使うのか？

ZoneJSを依存関係として削除する主な利点は次のとおりです。

- **パフォーマンスの向上**: ZoneJSは、アプリケーションの状態が*更新された可能性がある*タイミングの指標としてDOMイベントと非同期タスクを使用し、その後、アプリケーションのビューで変更検知を実行するためにアプリケーションの同期をトリガーします。ZoneJSは、アプリケーションの状態が実際に変更されたかどうかを把握していないため、この同期は必要以上に頻繁にトリガーされます。
- **Core Web Vitalsの改善**: ZoneJSは、ペイロードサイズと起動時間の両方で、かなりのオーバーヘッドをもたらします。
- **デバッグ体験の向上**: ZoneJSは、コードのデバッグをより困難にします。スタックトレースはZoneJSでは理解しにくくなります。また、コードがAngular Zoneの外部にあるために壊れた場合も理解しにくいです。
- **より良いエコシステム互換性**: ZoneJSはブラウザAPIをパッチ適用することで動作しますが、すべての新しいブラウザAPIに対して自動的にパッチが適用されるわけではありません。一部のAPIは、`async`/`await`のように効果的にパッチを適用できず、ZoneJSで動作するようにダウンレベルする必要があります。場合によっては、エコシステム内のライブラリも、ZoneJSがネイティブAPIにパッチを適用する方法と互換性がないことがあります。ZoneJSを依存関係として削除すると、複雑さ、モンキーパッチ、および継続的なメンテナンスのソースが削除されるため、長期的な互換性が向上します。

## アプリケーションでZonelessを有効にする

```typescript
// スタンドアロン ブートストラップ
bootstrapApplication(MyApp, {providers: [provideZonelessChangeDetection()]});

// NgModule ブートストラップ
platformBrowser().bootstrapModule(AppModule);
@NgModule({
  providers: [provideZonelessChangeDetection()],
})
export class AppModule {}
```

## ZoneJSの削除

Zonelessアプリケーションは、バンドルサイズを削減するために、ビルドからZoneJSを完全に削除する必要があります。ZoneJSは通常、
`angular.json`の`polyfills`オプションを介して、`build`と`test`の両方のターゲットでロードされます。ビルドから削除するには、
両方から`zone.js`と`zone.js/testing`を削除します。明示的な`polyfills.ts`ファイルを
使用するプロジェクトは、ファイルから`import 'zone.js';`と`import 'zone.js/testing';`を削除する必要があります。

ビルドからZoneJSを削除すると、`zone.js`の依存関係も不要になり、
パッケージを完全に削除できます。

```shell
npm uninstall zone.js
```

## Zoneless互換性の要件

Angularは、変更検知をいつ、どのビューで実行するかを判断するために、コアAPIからの通知に依存しています。
これらの通知には次のものが含まれます。

- `ChangeDetectorRef.markForCheck` (`AsyncPipe`によって自動的に呼び出されます)
- `ComponentRef.setInput`
- テンプレートで読み取られるシグナルの更新
- バインドされたホストまたはテンプレートリスナーのコールバック
- 上記のいずれかによってダーティーとしてマークされたビューのアタッチ

### `OnPush`互換コンポーネント

コンポーネントが上記の正しい通知メカニズムを使用していることを確認する1つの方法は、
[ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush)を使用することです。

`OnPush`変更検知戦略は必須ではありませんが、アプリケーションコンポーネントのZoneless互換性への推奨されるステップです。ライブラリコンポーネントが`ChangeDetectionStrategy.OnPush`を使用することが常に可能であるとは限りません。
ライブラリコンポーネントが`ChangeDetectionStrategy.Default`を使用する可能性のあるユーザーコンポーネントのホストである場合、子コンポーネントが`OnPush`互換ではなく、ZoneJSに依存して変更検知をトリガーする場合、子コンポーネントが更新されなくなるため、`OnPush`を使用できません。コンポーネントは、変更検知を実行する必要があるときにAngularに通知する限り（`markForCheck`の呼び出し、シグナルの使用、`AsyncPipe`など）、`Default`戦略を使用できます。
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 a using a template ref input).

### `NgZone.onMicrotaskEmpty`、`NgZone.onUnstable`、`NgZone.isStable`、または`NgZone.onStable`の削除

アプリケーションとライブラリは、`NgZone.onMicrotaskEmpty`、`NgZone.onUnstable`、および`NgZone.onStable`の使用を削除する必要があります。
アプリケーションがZoneless変更検知を有効にすると、これらのObservableは発行されません。
同様に、`NgZone.isStable`は常に`true`になり、コード実行の条件として使用できません。

`NgZone.onMicrotaskEmpty`および`NgZone.onStable`のObservableは、多くの場合、タスクを実行する前にAngularが
変更検知を完了するのを待つために最もよく使用されます。代わりに、単一の変更検知を
待つ必要がある場合は`afterNextRender`、 またはいくつかの変更検知ラウンドにまたがる可能性のある
条件がある場合は`afterEveryRender`に置き換えることができます。 他のケースでは、これらのObservableは
たまたま馴染みがあり、必要なものと似たタイミングであったために使用されています。 
コードが特定のDOM状態を待つ必要がある場合（Angularのレンダリングフックを介して間接的に待つのではなく）、
`MutationObserver`など、より簡単または直接的なDOM APIを代わりに使用できます。
`NgZone.run`と`NgZone.runOutsideAngular`は、コードをZonelessアプリケーションと互換性を持たせるために
削除する必要はありません。実際、これらの呼び出しを削除すると、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());
```

フレームワークは、非同期タスクが完了するまでシリアライズを防ぐために、このサービスを内部的にも使用します。これには、
進行中のルーターナビゲーションや未完了の`HttpClient`リクエストが含まれますが、これらに限定されません。

## テストとデバッグ

### `TestBed`でZonelessを使用する

Zonelessプロバイダー関数は、`TestBed`でも使用して、
テスト対象のコンポーネントがZoneless Angularアプリケーションと
互換性があることを確認できます。

```typescript
TestBed.configureTestingModule({
  providers: [provideZonelessChangeDetection()],
});

const fixture = TestBed.createComponent(MyComponent);
await fixture.whenStable();
```

テストが本番コードと最も類似した動作をすることを確認するには、
可能な限り`fixture.detectChanges()`の使用を避けてください。これにより、
Angularが変更検知をスケジュールしていない場合に、
変更検知が強制的に実行されます。テストでは、これらの通知が発生していることを確認し、
手動で強制的に発生させるのではなく、
Angularが状態を同期するタイミングを処理できるようにする必要があります。

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 `fixture.changeDetectorRef.markForCheck()`.

### 更新が検出されることを確認するためのデバッグモードチェック

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.
オープンソースプロジェクトとして、Angularの日々のコミット、PR、勢いはすべてGitHubで追跡できます。この日々の作業がフレームワークの将来とどのように関係しているかについての透明性を高めるために、私たちのロードマップはチームの現在および将来計画されているビジョンをまとめています。

以下のプロジェクトは、特定のAngularバージョンには関連付けられていません。完成次第リリースし、リリーススケジュールに従ってセマンティックバージョニングに基づいて特定のバージョンに含まれます。例えば、破壊的変更を含む場合は次のメジャー、そうでない場合は次のマイナーで機能をリリースします。

現在、Angularはフレームワークに2つの目標を持っています。

1. [Angular開発者体験の改善](#improving-the-angular-developer-experience)と
2. フレームワークのパフォーマンスの向上。

具体的なプロジェクト作業でこれらの目標をどのように達成する予定かについて、読み進めてください。

## 最新のAngularを探る

ロードマップからAngularの最新機能を使用して開発を始めましょう。このリストは、ロードマップから生まれた新機能の現在の状況を表しています。

### 実験的に利用可能

- [Resource API](/guide/signals/resource)
- [httpResource](/api/common/http/httpResource)

### 本番環境向け

- [Zoneless change detection](/guide/zoneless)
- [Linked Signal API](/guide/signals/linked-signal)
- [Incremental hydration](/guide/incremental-hydration)
- [Effect API](/api/core/effect)
- [Event replay with SSR](/api/platform-browser/withEventReplay)
- [Route-level render mode](/guide/ssr)

## Angular開発者体験の改善

### 開発速度
### Angular MaterialとCDKの改善
### ツールの改善
## 将来の作業、調査、プロトタイピング

このセクションは、将来の潜在的なプロジェクトの調査とプロトタイピングを表しています。妥当な結果は、現在のソリューションが最適なオプションであると判断することです。他のプロジェクトは、ウェブがフレームワークとともに革新を続けるにつれて、RFC、進行中のプロジェクトへの昇格、または優先順位の低下につながる可能性があります。
## 完了したプロジェクト
# Angular プロジェクトを最新の状態に保つ

WebやWebエコシステム全体と同様に、Angularも継続的に改善されています。
Angularは、継続的な改善と、安定性とアップデートの容易さに重点を置いてバランスを取っています。
Angularアプリケーションを最新の状態に保つことで、最先端の新しい機能、最適化、バグ修正を活用できます。

このドキュメントには、Angularアプリケーションとライブラリを最新の状態に保つための情報とリソースが含まれています。

バージョン管理ポリシーとプラクティス（サポートと非推奨のプラクティス、リリーススケジュールを含む）については、[Angular バージョン管理とリリース](reference/releases 'Angular バージョン管理とリリース')をご覧ください。

HELPFUL: 現在AngularJSを使用している場合は、[AngularJS からのアップグレード](https://angular.io/guide/upgrade 'Angular JS からのアップグレード')をご覧ください。
_AngularJS_ は、Angularのすべてのv1.xバージョンを表します。

## 新しいリリースの通知を受け取る

新しいリリースが利用可能になったときに通知を受け取るには、X (formerly Twitter)で [@angular](https://x.com/angular '@angular on X') をフォローするか、[Angular ブログ](https://blog.angular.dev 'Angular ブログ')を購読してください。

## 新しい機能について学ぶ

何が新しくなったのか？何が変わったのか？最新のリリースに関する最も重要な情報をAngularブログの[リリースアナウンスメント](https://blog.angular.dev/ 'Angular ブログ - リリースアナウンスメント')で共有しています。

バージョン別に整理された変更の完全なリストを確認するには、[Angularの変更履歴](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angularの変更履歴')をご覧ください。

## Angular のバージョンを確認する

アプリケーションのAngularバージョンを確認するには、プロジェクトディレクトリ内で `ng version` コマンドを使用します。

## Angular の最新バージョンを見つける

Angularの最新の安定したリリースバージョンは、"Version"の下にある[npm](https://www.npmjs.com/package/@angular/core 'Angular on npm')に表示されます。たとえば、`16.2.4`です。

また、CLIコマンド [`ng update`](cli/update) を使用して、Angularの最新バージョンを見つけることもできます。
デフォルトでは、[`ng update`](cli/update)（追加の引数なし）は、使用可能なアップデートをリストします。

## 環境とアプリケーションを更新する

アップデートを簡単に行うために、対話型の[Angularアップデートガイド](update-guide)に完全な手順を記載しています。

Angularアップデートガイドは、指定した現在のバージョンとターゲットバージョンに基づいて、カスタマイズされたアップデート手順を提供します。
アプリケーションの複雑さに合わせて、基本的なアップデートパスと高度なアップデートパスが用意されています。
また、新しいリリースを最大限に活用するためのトラブルシューティング情報と、推奨される手動変更も含まれています。

簡単なアップデートの場合は、CLIコマンド [`ng update`](cli/update) で十分です。
追加の引数なしで、[`ng update`](cli/update)は、使用可能なアップデートをリストし、アプリケーションを最新バージョンにアップデートするための推奨される手順を提供します。

[Angularのバージョン管理とリリース](reference/releases#versioning 'Angular リリースプラクティス、バージョン管理')では、リリースのバージョン番号に基づいて期待できる変更レベルについて説明しています。
また、サポートされているアップデートパスについても説明しています。

## リソースの概要

- リリースアナウンスメント:
  [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 バージョン管理とリリース')
# `HttpClient`のセキュリティ

`HttpClient` は、一般的な2つのHTTPセキュリティメカニズム (XSSI保護とXSRF/CSRF保護) のための組み込みサポートを提供します。

TIP: APIに [Content Security Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) を導入することも検討してください。

## XSSI 保護

クロスサイトスクリプトインクルージョン (XSSI) は、攻撃者がAPIエンドポイントからJSONデータを攻撃者が制御するページの `<script>` として読み込む [クロスサイトスクリプト](https://en.wikipedia.org/wiki/Cross-site_scripting) 攻撃の一種です。その後、さまざまなJavaScriptテクニックを使用してこのデータにアクセスできます。

XSSIを防ぐための一般的なテクニックは、JSONレスポンスを "非実行可能なプレフィックス" (通常は `)]}',\n`) で提供することです。このプレフィックスにより、JSONレスポンスが有効な実行可能なJavaScriptとして解釈されるのを防ぎます。APIがデータとして読み込まれる場合、JSONパースの前にプレフィックスを削除できます。

`HttpClient` は、レスポンスからJSONをパースする際に、このXSSIプレフィックス (存在する場合) を自動的に削除します。

## XSRF/CSRF 保護

[クロスサイトリクエストフォージェリ (XSRF または CSRF)](https://en.wikipedia.org/wiki/Cross-site_request_forgery) は、攻撃者が認証されたユーザーをだまして、ユーザーが知らずにWebサイトでアクションを実行させる攻撃手法です。

`HttpClient` は、XSRF攻撃を防ぐために使用される [一般的なメカニズム](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Cookie-to-header_token) をサポートしています。HTTPリクエストを実行すると、インターセプターはデフォルトで `XSRF-TOKEN` という名前のCookieからトークンを読み取り、`X-XSRF-TOKEN` というHTTPヘッダーに設定します。ドメイン上で実行されるコードのみがCookieを読み取ることができるため、バックエンドはHTTPリクエストが攻撃者ではなくクライアントアプリケーションから来たものであると確信できます。

デフォルトでは、インターセプターは、相対URLおよび同一オリジンURLへのすべての変更要求 (例: `POST`) にこのヘッダーを送信しますが、`GET`または`HEAD`リクエストには送信しません。
CSRF 保護は、バックエンドの状態を変更できるリクエストでのみ必要です。本質的に、CSRF 攻撃はドメイン境界を超えて実行され、Web の [same-origin ポリシー](https://developer.mozilla.org/docs/Web/Security/Same-origin_policy) は、攻撃するページが認証された `GET` リクエストの結果を取得するのを防ぎます。
この機能を利用するには、サーバーはページの読み込み時または最初のGETリクエスト時に、`XSRF-TOKEN` というJavaScriptで読み取り可能なセッションCookieにトークンを設定する必要があります。その後のリクエストでは、サーバーはCookieが `X-XSRF-TOKEN` HTTPヘッダーと一致することを確認し、ドメイン上で実行されているコードのみがリクエストを送信できたことを確認できます。トークンはユーザーごとに一意である必要があり、サーバーで検証可能である必要があります。これにより、クライアントが独自のトークンを作成することが防止されます。セキュリティを高めるために、トークンをサイトの認証Cookieのダイジェストに設定し、塩で設定します。

複数のAngularアプリケーションが同じドメインまたはサブドメインを共有する環境で衝突を防ぐには、各アプリケーションに一意のCookie名を指定します。
  バックエンドサービスは、ページの Cookie を設定し、すべての適格なリクエストにヘッダーが存在することを確認するように構成する必要があります。これを実行しないと、Angular のデフォルトの保護が無効になります。
### カスタム Cookie/ヘッダー名の構成

バックエンドサービスがXSRFトークンCookieまたはヘッダーに異なる名前を使用している場合は、`withXsrfConfiguration` を使用してデフォルト値をオーバーライドします。

以下のように `provideHttpClient` コールに追加します。

```ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withXsrfConfiguration({
        cookieName: 'CUSTOM_XSRF_TOKEN',
        headerName: 'X-Custom-Xsrf-Header',
      }),
    ),
  ],
};
```

### XSRF 保護の無効化

組み込みのXSRF保護メカニズムがアプリケーションで機能しない場合は、`withNoXsrfProtection` 機能を使用して無効にできます。

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withNoXsrfProtection())],
};
```
# Angular Internationalization (i18n)

_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"/>

## Learn about Angular internationalization