``` Both `class` and `style` bindings use a more straightforward syntax that aligns closely with standard HTML attributes. This makes your templates easier to read and understand, especially for developers familiar with basic HTML. Additionally, the `NgClass` and `NgStyle` directives incur an additional performance cost compared to the built-in `class` and `style` binding syntax. For more details, refer to the [bindings guide](/guide/templates/binding#css-class-and-style-property-bindings) ### Name event handlers for what they _do_, not for the triggering event Prefer naming event handlers for the action they perform rather than for the triggering event: ```html Save Save ``` Using meaningful names like this makes it easier to tell what an event does from reading the template. For keyboard events, you can use Angular's key event modifiers with specific handler names: ```html ``` Sometimes, event handling logic is especially long or complex, making it impractical to declare a single well-named handler. In these cases, it's fine to fall back to a name like 'handleKeydown' and then delegate to more specific behaviors based on the event details: ```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 Avoid putting long or complex logic inside lifecycle hooks like `ngOnInit`. Instead, prefer creating well-named methods to contain that logic and then _call those methods_ in your lifecycle hooks. Lifecycle hook names describe _when_ they run, meaning that the code inside doesn't have a meaningful name that describes what the code inside is doing. ```typescript // PREFER ngOnInit() { this.startLogging(); this.runBackgroundTask(); } // 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 provides a TypeScript interface for each lifecycle method. When adding a lifecycle hook to your class, import and `implement` these interfaces to ensure that the methods are named correctly. ```ts import {Component, OnInit} from '@angular/core'; @Component({/* ... */}) export class UserProfile implements OnInit { // The `OnInit` interface ensures this method is named correctly. ngOnInit() { /* ... */ } } ``` コンポーネントは、Angularアプリケーションの主要な構成要素です。各コンポーネントは、より大きなウェブページの一部を表します。アプリケーションをコンポーネントに整理することで、プロジェクトに構造が与えられ、コードが特定の部分に明確に分割されるため、保守と拡張が容易になります。 ## コンポーネントの定義 すべてのコンポーネントには、いくつかの主要な部分があります。 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を別々のファイルに分離する `templateUrl`と`styleUrl`を使用して、コンポーネントのHTMLとCSSを別々のファイルで定義できます。 ```typescript // user-profile.ts @Component({ selector: 'user-profile', templateUrl: 'user-profile.html', styleUrl: 'user-profile.css', }) export class UserProfile { // コンポーネントの動作はここに定義されます } ``` ```html <!-- user-profile.html --> <h1>User profile</h1> <p>This is the user profile page</p> ``` ```css /* user-profile.css */ h1 { font-size: 3em; } ``` ## コンポーネントの使用 アプリケーションは複数のコンポーネントを組み合わせて構築します。例えば、ユーザーのプロファイルページを作成する場合、次のようにページをいくつかのコンポーネントに分割できます。 ```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)を参照してください。 ## 次の手順 Angularでのコンポーネントの動作が分かったところで、アプリケーションに動的なデータをどのように追加して管理するかを学ぶ時です。 # コンポーネントセレクター TIP: このガイドは、[基本概念のガイド](essentials) を既にお読みになっていることを前提としています。Angularを初めて使用する場合は、まずこちらをお読みください。 各コンポーネントは、 コンポーネントの使用方法を決定する [CSS セレクター](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) を定義します。 ```typescript @Component({ selector: 'profile-photo', ... }) export class ProfilePhoto { } ``` コンポーネントを使用するには、*他の*コンポーネントのテンプレートに一致するHTML要素を作成します。 ```typescript @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 @Component({ selector: '[dropzone]:not(textarea)', ... }) export class DropZone { } ``` Angularは、コンポーネント セレクターで他の擬似クラスまたは擬似要素をサポートしていません。 ### セレクターの組み合わせ 複数のセレクターを連結することで、組み合わせられます。 たとえば、`type="reset"` を指定した `<button>` 要素をマッチングできます。 ```typescript @Component({ selector: 'button[type="reset"]', ... }) export class ResetButton { } ``` カンマ区切りのリストで、複数のセレクターを定義できます。 ```typescript @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-` を使用します。 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 @Component({ selector: 'profile-photo', template: `<img src="profile-photo.jpg" alt="Your profile photo">`, styles: ` img { border-radius: 50%; } `, }) export class ProfilePhoto { } ``` また、別のファイルにスタイルを記述できます。 ```typescript @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`、`None`の3つのモードがあります。 モードは、`@Component`デコレーターで指定できます。 ```typescript @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)擬似 クラスを、 [Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM) を使用せずにサポートします。 コンパイル時に、フレームワークはこれらの擬似クラスを属性に変換するため、実行時にこれらのネイティブ擬似クラスのルール(ブラウザの互換性、特異性など)に準拠しません。 Angularのエミュレートされたカプセル化モードは、 `::shadow`や`::part`など、Shadow DOMに関連するその他の擬似クラスをサポートしていません。 #### `::ng-deep` Angularのエミュレートされたカプセル化モードは、カスタム擬似クラス`::ng-deep`をサポートしています。 この擬似クラスをCSSルールに適用すると、そのルールのカプセル化が無効になり、実質的にグローバルスタイルになります。 **Angularチームは、`::ng-deep`の新しい使用を強くお勧めしません。** これらのAPIは、下位互換性のためにのみ残っています。 ### 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.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 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はデフォルト値から型を推論します。 ```typescript @Component({/*...*/}) export class CustomSlider { // TypeScriptは、この入力が数値であると推論し、InputSignal<number>を返します。 value = input(0); } ``` 関数のジェネリックパラメーターを指定することで、入力の型を明示的に宣言できます。 デフォルト値のない入力が設定されていない場合、その値は`undefined`になります。 ```typescript @Component({/*...*/}) export class CustomSlider { // `value`は設定されない可能性があるため、InputSignal<number | undefined>を生成します。 value = input<number>(); } ``` **Angularはコンパイル時に静的に入力を記録します。**実行時に入力の追加や削除はできません。 `input`関数は、Angularコンパイラにとって特別な意味を持ちます。**`input`は、コンポーネントとディレクティブのプロパティ初期化子でのみ呼び出すことができます。** コンポーネントクラスを拡張する場合、**入力は子クラスによって継承されます。** **入力名は大文字と小文字が区別されます。** ## 入力の読み取り `input`関数は`InputSignal`を返します。シグナルを呼び出すことで値を読み取ることができます。 ```ts import {Component, input} from '@angular/core'; @Component({/*...*/}) export class CustomSlider { // Declare an input named 'value' with a default value of zero. value = input(0); // Create a computed expression that reads the value input label = computed(() => `The slider's value is ${this.value()}`); } ``` `input`関数によって作成されたシグナルは読み取り専用です。 ## 必須入力 `input`の代わりに`input.required`を呼び出すことで、入力が`required`であることを宣言できます。 ```ts @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 @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 @Component({/*...*/}) export class CustomSlider { value = input(0, {alias: 'sliderValue'}); } ``` ```html <custom-slider [sliderValue]="50" /> ``` このエイリアスは、TypeScriptコードでのプロパティの使用には影響しません。 一般的にコンポーネントの入力をエイリアス化することは避けるべきですが、この機能は、元の名前のエイリアスを保持しながらプロパティの名前を変更したり、ネイティブDOM要素プロパティの名前との競合を回避したりする場合に役立ちます。 ## モデル入力 **モデル入力**は、コンポーネントが新しい値を親コンポーネントに伝播できるようにする特殊なタイプの入力です。 コンポーネントを作成する際に、通常の入力と同様にモデル入力を定義できます。 どちらの種類の入力も、値をプロパティにバインドすることを可能にします。しかし、**モデル入力は、コンポーネントの作者がプロパティに値を書き込むことを可能にします。**プロパティが双方向バインディングでバインドされている場合、新しい値はそのバインディングに伝播します。 ```typescript @Component({ /* ... */}) export class CustomSlider { // "value"という名前のモデル入力を定義します。 value = model(0); increment() { // 新しい値でモデル入力を更新し、値をすべてのバインディングに伝播します。 this.value.update(oldValue => oldValue + 10); } } @Component({ /* ... */ // 双方向バインディング構文を使用すると、スライダーの値の変更は、 // `volume`シグナルに自動的に伝播します。 // このバインディングは、シグナルの値ではなく、シグナルのインスタンスを使用していることに注意してください。 template: `<custom-slider [(value)]="volume" />`, }) export class MediaControls { // `volume`ローカル状態の書き込み可能なシグナルを作成します。 volume = signal(0); } ``` 上記の例では、`CustomSlider`は`value`モデル入力に値を書き込むことができ、それによって`MediaControls`の`volume`シグナルに値が伝播します。このバインディングにより、`value`と`volume`の値が同期します。バインディングはシグナルの_値_ではなく、`volume`シグナルのインスタンスを渡していることに注意してください。 他の点では、モデル入力は標準入力と同様に機能します。`computed`や`effect`のようなリアクティブなコンテキスト内を含め、シグナル関数を呼び出すことで値を読み取ることができます。 テンプレートでの双方向バインディングの詳細については、[双方向バインディング](guide/templates/two-way-binding)を参照してください。 ### プレーンプロパティとの双方向バインディング プレーンな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」が付いたものです。 ```typescript @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 @Component({ selector: 'custom-slider', ... }) export class CustomSlider { @Input({transform: trimString}) label = ''; } function trimString(value: string | undefined) { return value?.trim() ?? ''; } ``` #### 入力エイリアス `alias`オプションを指定して、テンプレートでの入力の名前を変更できます。 ```ts @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 // `CustomSlider` inherits the `disabled` property from `BaseSlider`. @Component({ ..., inputs: ['disabled'], }) export class CustomSlider extends BaseSlider { } ``` 文字列の後にコロンを付けてエイリアスを`inputs`リストに指定できます。 ```ts // `CustomSlider` inherits the `disabled` property from `BaseSlider`. @Component({ ..., inputs: ['disabled: sliderDisabled'], }) export class CustomSlider extends BaseSlider { } ``` # カスタムイベントと出力 TIP: このガイドは、[基本概念のガイド](essentials) を既読していることを前提としています。Angularを初めて使用する場合は、まずそちらをお読みください。 Angularコンポーネントは、`output`関数にプロパティを割り当てることでカスタムイベントを定義できます。 ```ts @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)" /> ``` ## 出力名のカスタマイズ `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`を返します。 ```typescript 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"> <!-- card content goes here --> </div>', }) export class CustomCard {/* ... */} ``` **`<ng-content>`要素は、コンテンツを配置する場所を示すプレースホルダーとして使用できます。**: ```typescript @Component({ selector: 'custom-card', template: '<div class="card-shadow"> <ng-content></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 <!-- レンダリングされたDOM --> <custom-card> <div class="card-shadow"> <p>これは投影されたコンテンツです</p> </div> </custom-card> ``` Angularは、このように渡されるコンポーネントの子要素を、そのコンポーネントの**コンテンツ**と呼びます。 これはコンポーネントの**ビュー**とは異なります。 ビューは、コンポーネントのテンプレートで定義された要素を指します。 **`<ng-content>`要素は、コンポーネントでもDOM要素でもありません。** 代わりに、コンテンツをレンダリングする場所をAngularに伝える特別なプレースホルダーです。 Angularのコンパイラは、ビルド時にすべての`<ng-content>`要素を処理します。 実行時に`<ng-content>`の挿入や削除、変更はできません。ディレクティブやスタイル、任意の属性も`<ng-content>`には追加できません。 `<ng-content>`を`@if`、`@for`、または`@switch`によって条件付きで含めるべきではありません。 Angularは常にレンダリングされたコンテンツのDOMノードをインスタンス化して作成します。 その`<ng-content>`プレースホルダが非表示であってもです。コンポーネントコンテンツの条件付きレンダリングについては [テンプレートフラグメント](api/core/ng-template)を参照してください。 ## 複数のコンテンツプレースホルダー Angularは、CSSセレクターに基づいて、複数の異なる要素を異なる`<ng-content>`プレースホルダーへの投影をサポートしています。 上記のカードの例を拡張して、`select`属性を使用して、 カードのタイトルと本文の2つのプレースホルダーを作成できます。 ```html <!-- コンポーネントテンプレート --> <div class="card-shadow"> <ng-content select="card-title"></ng-content> <div class="card-divider"></div> <ng-content select="card-body"></ng-content> </div> ``` ```html <!-- コンポーネントの利用 --> <custom-card> <card-title>こんにちは</card-title> <card-body>例へようこそ</card-body> </custom-card> ``` ```html <!-- レンダリングされたDOM --> <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> <!-- "card-title"以外をすべてキャプチャ --> <ng-content></ng-content> </div> ``` ```html <!-- コンポーネントの利用 --> <custom-card> <card-title>こんにちは</card-title> <img src="..." /> <p>例へようこそ</p> </custom-card> ``` ```html <!-- レンダリングされたDOM --> <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にレンダリングされません。 ## フォールバックコンテンツ 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> <!-- No card-body provided --> </custom-card> ``` ```html <!-- レンダリングされたDOM --> <custom-card> <div class="card-shadow"> <card-title>Hello</card-title> <div class="card-divider"></div> Default Body </div> </custom-card> ``` ## 投影のためのコンテンツのエイリアシング 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></ng-content> </div> ``` ```html <!-- コンポーネントの利用 --> <custom-card> <h3 ngProjectAs="card-title">こんにちは</h3> <p>例へようこそ</p> </custom-card> ``` ```html <!-- レンダリングされたDOM --> <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` には、入力の以前の値、現在の値、 および入力が初めて変更されたかどうかを示すフラグが含まれています。 ```ts @Component({ /* ... */ }) export class UserProfile { name = input(''); ngOnChanges(changes: SimpleChanges) { for (const inputName in changes) { const inputValues = changes[inputName]; console.log(`Previous ${inputName} == ${inputValues.previousValue}`); console.log(`Current ${inputName} == ${inputValues.currentValue}`); console.log(`Is first ${inputName} change == ${inputValues.firstChange}`); } } } ``` 入力プロパティに `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` メソッドに置くのではなく、 クリーンアップコードに近い場所にセットアップコードを保持できます。 ### 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) を参照してください。 レンダリングコールバックは、サーバーサイドレンダリング中またはビルド時の事前レンダリング中は実行されません。 #### afterEveryRender フェーズ `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() { private 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` フェーズを優先します。 | | `mixedReadWrite` | デフォルトのフェーズ。レイアウトに影響を与えるプロパティとスタイルを読み書きする必要がある操作に使用します。可能な限り、このフェーズを避け、明示的な `write` フェーズと `read` フェーズを優先します。 | | `write` | このフェーズを使用して、レイアウトに影響を与えるDOMプロパティとスタイルを書き込みます。 | | `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だけではありません。コンポーネントクラスのデータを使用し、ユーザーインタラクションのハンドラーを設定できます。 ## 動的なテキストの表示 Angularでは、*バインディング*によって、コンポーネントのテンプレートとそのデータ間に動的な接続が作成されます。この接続により、コンポーネントのデータの変更がレンダリングされたテンプレートに自動的に反映されます。 二重中括弧を使用して、テンプレートに動的なテキストを表示するバインディングを作成できます。 ```typescript @Component({ selector: 'user-profile', template: `<h1>Profile for {{userName()}}</h1>`, }) export class TodoListItem { userName = signal('pro_programmer_123'); } ``` Angularがコンポーネントをレンダリングすると、以下が表示されます。 ```html <h1>Profile for pro_programmer_123</h1> ``` シグナルの値が変更されると、Angularはバインディングを自動的に最新の状態に保ちます。 上記の例を基に、`userName`シグナルの値を更新する場合: ```typescript this.userName.set('cool_coder_789'); ``` レンダリングされたページは新しい値を反映して更新されます。 ```html <h1>Profile for cool_coder_789</h1> ``` ## 動的なプロパティと属性の設定 Angularは、角括弧を使用して動的な値をDOMプロパティにバインドすることをサポートしています。 ```typescript @Component({ /*...*/ // `isValidUserId`の値に基づいて、ボタンの`disabled`プロパティを設定します。 template: `<button [disabled]="isValidUserId()">Save changes</button>`, }) export class UserProfile { isValidUserId = signal(false); } ``` 属性名に`attr.`をプレフィックスとして付けることで、HTMLの_属性_にもバインドできます。 ```html <!-- `<ul>`要素の`role`属性を`listRole`の値にバインドします。 --> <ul [attr.role]="listRole()"> ``` バインドされた値が変更されると、AngularはDOMプロパティと属性を自動的に更新します。 ## ユーザーインタラクションの処理 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`による制御フロー 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)を参照してください。 ## 次の手順 アプリケーションに動的なデータとテンプレートが用意できたので、次は特定の要素を条件付きで非表示または表示したり、要素をループ処理したりするなど、テンプレートを強化する方法を学習します。 # イベントリスナーの追加 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 <!-- Matches shift and enter --> <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 <!-- Matches alt and left shift --> <input type="text" (keydown.code.alt.shiftleft)="updateField($event)" /> ``` これは、異なるオペレーティングシステム間でキーボードイベントを一貫して処理する場合に役立ちます。たとえば、MacOSデバイスでAltキーを使用する場合、`key` プロパティはAltキーで既に修飾された文字に基づいてキーを報告します。これは、Alt + Sのような組み合わせが `'ß'` の `key` 値を報告することを意味します。ただし、`code` プロパティは、生成された文字ではなく、押された物理的なまたは仮想的なボタンに対応します。 ## Preventing event default behavior If your event handler should replace the native browser behavior, you can use the event object's [`preventDefault` method](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault): ```typescript @Component({ template: ` <a href="#overlay" (click)="showOverlay($event)"> `, ... }) export class AppComponent{ showOverlay(event: PointerEvent): void { event.preventDefault(); console.log('Show overlay without updating the URL!'); } } ``` If the event handler statement evaluates to `false`, Angular automatically calls `preventDefault()`, similar to [native event handler attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes). *Always prefer explicitly calling `preventDefault`*, as this approach makes the code's intent obvious. # 動的なテキスト、プロパティ、属性のバインディング 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 <!-- Rendered Output --> <p>Your color preference is dark.</p> ``` Angularは、最初のレンダリング時に式を評価するだけでなく、式の値が変更されると、レンダリングされたコンテンツも更新します。 テーマの例を続けると、ユーザーがページの読み込み後に`theme`の値を`'light'`に変更するボタンをクリックした場合、ページはそれに応じて以下のように更新されます。 ```html <!-- Rendered Output --> <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 <!-- ボタン要素のDOMオブジェクトの`disabled`プロパティをバインドします --> <button [disabled]="isFormValid">Save</button> ``` この例では、`isFormValid`が変更されるたびに、Angularは`HTMLButtonElement`インスタンスの`disabled`プロパティを自動的に設定します。 ### コンポーネントとディレクティブのプロパティ 要素がAngularコンポーネントの場合、同じ角括弧構文を使用して、コンポーネントの入力プロパティに値を設定するためにプロパティバインディングを使用できます。 ```html <!-- `MyListbox`コンポーネントインスタンスの`value`プロパティをバインドします。 --> <my-listbox [value]="mySelection" /> ``` この例では、`mySelection`が変更されるたびに、Angularは`MyListbox`インスタンスの`value`プロパティを自動的に設定します。 ディレクティブのプロパティにもバインドできます。 ```html <!-- `NgOptimizedImage`ディレクティブの`ngSrc`プロパティにバインドします --> <img [ngSrc]="profilePhotoUrl" alt="The current user's profile photo"> ``` ### 属性 対応するDOMプロパティを持たないHTML属性（ARIA属性やSVG属性など）を設定する必要がある場合は、テンプレート内の要素に属性をバインドするために`attr.`プレフィックスを使用できます。 ```html <!-- `<ul>`要素の`role`属性をコンポーネントの`listRole`プロパティにバインドします。 --> <ul [attr.role]="listRole"> ``` この例では、`listRole`が変更されるたびに、Angularは`setAttribute`を呼び出して`<ul>`要素の`role`属性を自動的に設定します。 属性バインディングの値が`null`の場合、Angularは`removeAttribute`を呼び出して属性を削除します。 ### プロパティと属性でのテキスト補間 二重中括弧構文を使用して、プロパティと属性にテキスト補間構文を使用できます。この構文を使用すると、Angularは代入をプロパティバインディングとして扱います。 ```html <!-- 画像要素のDOMオブジェクトの`alt`プロパティに値をバインドします。 --> <img src="profile-photo.jpg" alt="Profile photo of {{ firstName }}" > ``` テキスト補間構文を使用して属性にバインドするには、属性名の前に`attr.`を付けます。 ```html <button attr.aria-label="Save changes to {{ objectType }}"> ``` ## CSSクラスとスタイルプロパティのバインディング Angularは、要素にCSSクラスとCSSスタイルプロパティをバインドするための追加機能をサポートしています。 ### CSSクラス CSSクラスバインディングを作成して、バインドされた値が[真偽値](https://developer.mozilla.org/en-US/docs/Glossary/Truthy)かどうかによって、要素にCSSクラスを追加または削除できます。 ```html <!-- `isExpanded`が真偽値の場合、`expanded`CSSクラスを追加します。 --> <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 = ['expandable', 'elevated']; buttonClasses = { 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 = 'box'; isExpanded = 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 <!-- `isExpanded`プロパティに基づいてCSSの`display`プロパティを設定します。 --> <section [style.display]="isExpanded ? 'block' : 'none'"> ``` 単位を受け付けるCSSプロパティについては、さらに単位を指定できます。 ```html <!-- `sectionHeightInPixels`プロパティに基づいてCSSの`height`プロパティをピクセル値に設定します。 --> <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 = 'display: flex; padding: 8px'; sectionStyles = { 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はスタイルの優先順位に従って競合を解決します。 # 組み込み制御フロー 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 aria-hidden="true"> 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.1459; @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; <!-- Invalid - This does not work! --> <button (click)="value = value + 1">Increment the value</button> ``` ### 変数のスコープ `@let` 宣言は、現在のビューとその子孫にスコープされます。 Angularは、コンポーネントの境界と、テンプレートに動的なコンテンツ（制御フローブロック、`@defer`ブロック、または構造ディレクティブなど）が含まれる可能性がある場所に新しいビューを作成します。 `@let` 宣言はホイスティングされないため、親ビューまたは兄弟から**アクセスできません**。 ```html @let topLevel = value; <div> @let insideDiv = value; </div> {{topLevel}} <!-- Valid --> {{insideDiv}} <!-- Valid --> @if (condition) { {{topLevel + insideDiv}} <!-- Valid --> @let nested = value; @if (condition) { {{topLevel + insideDiv + nested}} <!-- Valid --> } } {{nested}} <!-- Error, not hoisted from @if --> ``` ### 構文全体 `@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 <!-- "taskInput" という名前のテンプレート参照変数を、HTMLInputElementに関連付ける --> <input #taskInput placeholder="Enter task name"> ``` ### テンプレート参照変数に値を代入する Angularは、変数が宣言されている要素に基づいて、テンプレート変数に値を代入します。 変数をAngularコンポーネントに宣言した場合、変数はコンポーネントインスタンスを参照します。 ```html <!-- `startDate` 変数は、`MyDatepicker` のインスタンスに代入されます。 --> <my-datepicker #startDate /> ``` 変数を `<ng-template>` 要素に宣言した場合、変数はテンプレートを表すTemplateRefインスタンスを参照します。詳細については、[構造ディレクティブ](/guide/directives/structural-directives)の[Angularがアスタリスク、\*、構文を使用する方法](/guide/directives/structural-directives#structural-directive-shorthand)を参照してください。 ```html <!-- `myFragment` 変数は、このテンプレートフラグメントに対応する `TemplateRef` インスタンスに代入されます。 --> <ng-template #myFragment> <p>This is a template fragment</p> </ng-template> ``` 変数を他の表示されている要素に宣言した場合、変数は `HTMLElement` インスタンスを参照します。 ```html <!-- "taskInput" 変数は、HTMLInputElement インスタンスを参照します。 --> <input #taskInput placeholder="Enter task name"> ``` #### Angularディレクティブへの参照を代入する Angularディレクティブには、テンプレートでディレクティブを参照できる名前を定義する `exportAs` プロパティがある場合があります。 ```typescript @Directive({ selector: '[dropZone]', exportAs: 'dropZone', }) export class DropZone { /* ... */ } ``` 要素にテンプレート変数を宣言する場合、この `exportAs` 名を指定することで、変数にディレクティブインスタンスを代入できます。 ```html <!-- `firstZone` 変数は、`DropZone` ディレクティブインスタンスを参照します。 --> <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 (on idle) --> @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 /> } ``` #### `interaction` `interaction`トリガーは、ユーザーが`click`または`keydown`イベントを通じて指定された要素と対話すると、遅延コンテンツを読み込みます。 デフォルトでは、プレースホルダーが対話要素として機能します。このように使用されるプレースホルダーは、単一のルート要素を持つ必要があります。 ```html @defer (on interaction) { <large-cmp /> } @placeholder { <div>大型コンポーネントのプレースホルダー</div> } ``` Alternatively, you can specify a [template reference variable](/guide/templates/variables) in the same template as the `@defer` block as the element that is watched for interactions. This variable is passed in as a parameter on the viewport trigger. ```html <div #greeting>こんにちは！</div> @defer (on interaction(greeting)) { <greetings-cmp /> } ``` #### `hover` `hover`トリガーは、マウスが`mouseover`イベントと`focusin`イベントを通じてトリガーされた領域にホバーすると、遅延コンテンツを読み込みます。 デフォルトでは、プレースホルダーが対話要素として機能します。このように使用されるプレースホルダーは、単一のルート要素を持つ必要があります。 ```html @defer (on hover) { <large-cmp /> } @placeholder { <div>大型コンポーネントのプレースホルダー</div> } ``` または、`@defer`ブロックと同じテンプレート内に、ビューポートに入っているかどうかが監視される要素として[テンプレート参照変数](/guide/templates/variables)を指定できます。この変数は、ビューポートトリガーのパラメータとして渡されます。 ```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`は、サーバーサイドレンダリング(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`トリガーは避けてください。 # 式構文 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}` `` | ### サポートされていないリテラル | Literal type | Example value | | ---------------------- | ------------------------ | | RegExp | `/\d+/` | ## グローバル 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)、ローカル変数、およびグローバル変数のコンテキストで評価されます。 When referring to component class members, `this` is always implied. However, if a template declares a [template variables](guide/templates/variables) with the same name as a member, the variable shadows that member. You can unambiguously reference such a class member by explicitly using `this.`. This can be useful when creating an `@let` declaration that shadows a class member, e.g. for signal narrowing purposes. ## 宣言 一般的に、Angular式では宣言はサポートされていません。これには、以下が含まれますが、これらに限定されません。 | 宣言 | 例(複数) | | --------------- | ------------------------------------------- | | 変数 | `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="src/app/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要素（`appHighlight`を適用する要素）への直接アクセスを提供します。 1. ディレクティブの`constructor()`に`ElementRef`を追加して、ホストDOM要素への参照を[注入](guide/di)します。 1. 背景を黄色に設定するロジックを`HighlightDirective`クラスに追加します。 <docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.1.ts"/> HELPFUL: ディレクティブは*ネームスペース*をサポートしていません。 <docs-code header="src/app/app.component.avoid.html (unsupported)" path="adev/src/content/examples/attribute-directives/src/app/app.component.avoid.html" visibleRegion="unsupported"/> ## 属性ディレクティブの適用 1. `HighlightDirective`を使用するには、ディレクティブを属性として持つ`<p>`要素をHTMLテンプレートに追加します。 <docs-code header="src/app/app.component.html" path="adev/src/content/examples/attribute-directives/src/app/app.component.1.html" visibleRegion="applied"/> Angularは`HighlightDirective`クラスのインスタンスを作成し、`<p>`要素への参照をディレクティブのコンストラクターに注入します。これにより、`<p>`要素の背景スタイルが黄色に設定されます。 ## ユーザーイベントの処理 このセクションでは、ユーザーが要素内または要素外にマウスを移動したときに検出する方法と、ハイライトカラーを設定またはクリアして応答する方法について説明します。 1. `@angular/core`から`HostListener`をインポートします。 <docs-code header="src/app/highlight.directive.ts (imports)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.2.ts" visibleRegion="imports"/> 1. マウスが入りまたは出たときに応答する2つのイベントハンドラーを追加します。それぞれに`@HostListener()`デコレーターを使用します。 <docs-code header="src/app/highlight.directive.ts (mouse-methods)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.2.ts" visibleRegion="mouse-methods"/> `@HostListener()`デコレーターを使用して、属性ディレクティブをホストするDOM要素（この場合は`<p>`）のイベントを購読します。 HELPFUL: ハンドラーは、ホストDOM要素`el`に色を設定するヘルパーメソッド`highlight()`に委任します。 完全なディレクティブは次のとおりです。 <docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.2.ts"/> ポインタが段落要素の上にホバーすると背景色が表示され、ポインタが外れると背景色が消えます。 <img alt="Second Highlight" src="assets/images/guide/attribute-directives/highlight-directive-anim.gif"> ## 属性ディレクティブに値を渡す このセクションでは、`HighlightDirective`を適用するときにハイライトカラーを設定する方法について説明します。 1. `highlight.directive.ts`で、`@angular/core`から`Input`をインポートします。 <docs-code header="src/app/highlight.directive.ts (imports)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" visibleRegion="imports"/> 1. `appHighlight` `input`プロパティを追加します。 <docs-code header="src/app/highlight.directive.ts" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" visibleRegion="input"/> `input`関数は、ディレクティブの`appHighlight`プロパティをバインディングで使用できるようにするメタデータをクラスに追加します。 2. `app.component.ts`で、`AppComponent`に`color`プロパティを追加します。 <docs-code header="src/app/app.component.ts (class)" path="adev/src/content/examples/attribute-directives/src/app/app.component.1.ts" visibleRegion="class"/> 3. ディレクティブと色を同時に適用するには、`appHighlight`ディレクティブセレクターを使用してプロパティバインディングを使用し、それを`color`に設定します。 <docs-code header="src/app/app.component.html (color)" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="color"/> `[appHighlight]`属性バインディングは次の2つのタスクを実行します。 * `<p>`要素にハイライトディレクティブを適用する * プロパティバインディングを使用してディレクティブのハイライトカラーを設定する ### ユーザー入力を使用して値を設定する このセクションでは、カラー選択を`appHighlight`ディレクティブにバインドするラジオボタンを追加する方法について説明します。 1. 色を選択するためのマークアップを`app.component.html`に追加します。 <docs-code header="src/app/app.component.html (v2)" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="v2"/> 1. `AppComponent.color`を修正して、初期値を持たないようにします。 <docs-code header="src/app/app.component.ts (class)" path="adev/src/content/examples/attribute-directives/src/app/app.component.ts" visibleRegion="class"/> 1. `highlight.directive.ts`で、`onMouseEnter`メソッドを修正して、最初に`appHighlight`でハイライトしようとします。`appHighlight`が`undefined`の場合は`red`にフォールバックします。 <docs-code header="src/app/highlight.directive.ts (mouse-enter)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.3.ts" visibleRegion="mouse-enter"/> 1. アプリケーションを起動して、ユーザーがラジオボタンで色を選択できることを確認します。 <img alt="Animated gif of the refactored highlight directive changing color according to the radio button the user selects" src="assets/images/guide/attribute-directives/highlight-directive-v2-anim.gif"> ## 2番目のプロパティにバインドする このセクションでは、開発者がデフォルトカラーを設定できるようにアプリケーションを構成する方法について説明します。 1. `HighlightDirective`に`defaultColor`という名前の2番目の`Input()`プロパティを追加します。 <docs-code header="src/app/highlight.directive.ts (defaultColor)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.ts" visibleRegion="defaultColor"/> 1. ディレクティブの`onMouseEnter`を修正して、最初に`appHighlight`でハイライトしようとします。次に`defaultColor`でハイライトしようとします。両方のプロパティが`undefined`の場合は`red`にフォールバックします。 <docs-code header="src/app/highlight.directive.ts (mouse-enter)" path="adev/src/content/examples/attribute-directives/src/app/highlight.directive.ts" visibleRegion="mouse-enter"/> 1. `AppComponent.color`にバインドし、デフォルトカラーとして「violet」を使用するには、次のHTMLを追加します。 この場合、`defaultColor`バインディングは、静的であるため、角括弧`[]`を使用しません。 <docs-code header="src/app/app.component.html (defaultColor)" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="defaultColor"/> コンポーネントと同様に、ホスト要素に複数のディレクティブプロパティバインディングを追加できます。 デフォルトカラーは、デフォルトカラーバインディングがない場合は赤です。 ユーザーが色を選択すると、選択した色がアクティブなハイライトカラーになります。 <img alt="Animated gif of final highlight directive that shows red color with no binding and violet with the default color set. When user selects color, the selection takes precedence." src="assets/images/guide/attribute-directives/highlight-directive-final-anim.gif"> ## `NgNonBindable`を使用してAngularの処理を無効にする ブラウザでの式評価を防ぐには、ホスト要素に`ngNonBindable`を追加します。 `ngNonBindable`は、テンプレート内の補間、ディレクティブ、バインディングを無効にします。 次の例では、式`{{ 1 + 1 }}`はコードエディタと同じようにレンダリングされ、`2`は表示されません。 <docs-code header="src/app/app.component.html" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="ngNonBindable"/> `ngNonBindable`を要素に適用すると、その要素の子要素のバインディングが停止します。 ただし、`ngNonBindable`は、`ngNonBindable`を適用した要素に対しては、ディレクティブを動作させます。 次の例では、`appHighlight`ディレクティブはアクティブですが、Angularは式`{{ 1 + 1 }}`を評価しません。 <docs-code header="src/app/app.component.html" path="adev/src/content/examples/attribute-directives/src/app/app.component.html" visibleRegion="ngNonBindable-with-directive"/> `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)できます。 ## 構造ディレクティブの構文リファレンス 独自の構造ディレクティブを作成する際は、次の構文を使用します。 ``` *:prefix="( :let | :expression ) (';' | ',')? ( :let | :as | :keyExp )*" ``` 次のパターンは、構造ディレクティブ文法の各部分を説明しています。 ```ts as = :export "as" :local ";"? keyExp = :key ":"? :expression ("as" :local)? ";"? let = "let" :local "=" :export ";"? ``` | キーワード | 詳細 | | :----------- | :------------------------------------------------- | | `prefix` | HTML属性キー | | `key` | HTML属性キー | | `local` | テンプレートで使用されるローカル変数名 | | `export` | 与えられた名前の下でディレクティブによってエクスポートされる値 | | `expression` | 標準的なAngular式 | ### Angularが省略記法をどのように変換するか Angularは、構造ディレクティブの省略記法を次の通常のバインディング構文に変換します。 | 省略記法 | 変換 | |:--- |:--- | | `prefix`と裸の`expression` | `[prefix]="expression"` | | `keyExp` | `[prefixKey]="expression"` (`prefix`が`key`に追加されます) | | `let local` | `let-local="export"` | ### 省略記法の例 次の表は、省略記法の例を示しています。 | 省略記法 | 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でも安定版機能として利用可能です。** ## はじめに <docs-workflow> <docs-step title="`NgOptimizedImage`ディレクティブのインポート"> `NgOptimizedImage`ディレクティブを`@angular/common`からインポートします。 ```typescript import { NgOptimizedImage } from '@angular/common' ``` そして、スタンドアロンコンポーネントまたはNgModuleの`imports`配列に含めます。 ```typescript 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`属性を追加します。 ``` <img ngSrc="cat.jpg" width="400" height="200" placeholder> ``` この属性を追加すると、指定された画像ローダーを使用して、画像の2番目の小さいバージョンが自動的にリクエストされます。この小さい画像は、画像が読み込まれる間、CSSのぼかしを伴う`background-image`スタイルとして適用されます。画像ローダーが提供されていない場合、プレースホルダー画像は生成されず、エラーがスローされます。 生成されるプレースホルダーのデフォルトサイズは幅30pxです。このサイズは、以下に示すように`IMAGE_CONFIG`プロバイダーでピクセル値を指定することで変更できます。 ``` 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画像が可能な限り迅速に読み込まれることを保証します。 プリコネクトリンクは、[ローダー](#optional-set-up-a-loader)への引数として提供されたドメインに対して自動的に生成されます。画像オリジンを自動的に識別できない場合、またはLCP画像に対してプリコネクトリンクが検出されない場合、`NgOptimizedImage`は開発中に警告を表示します。その場合、`index.html`にリソースヒントを手動で追加する必要があります。ドキュメントの`<head>`内に、以下に示すように`rel="preconnect"`を持つ`link`タグを追加します。 ```html <link rel="preconnect" href="https://my.cdn.origin" /> ``` プリコネクト警告を無効にするには、`PRECONNECT_CHECK_BLOCKLIST`トークンをインジェクトします。 ```typescript 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`プロバイダーを使用して行うことができます: ```typescript 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"> ``` ### 高度な'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`は以下の画像サービスで動作するように事前設定されたローダーを提供します。 | 画像サービス | Angular API | ドキュメント | |:--- |:--- |:--- | | Cloudflare Image Resizing | `provideCloudflareLoader` | [ドキュメント](https://developers.cloudflare.com/images/image-resizing/) | | Cloudinary | `provideCloudinaryLoader` | [ドキュメント](https://cloudinary.com/documentation/resizing_and_cropping) | | ImageKit | `provideImageKitLoader` | [ドキュメント](https://docs.imagekit.io/) | | Imgix | `provideImgixLoader` | [ドキュメント](https://docs.imgix.com/) | | Netlify | `provideNetlifyLoader` | [ドキュメント](https://docs.netlify.com/image-cdn/overview/) | **汎用ローダー**を使用するために、追加のコード変更は不要です。これがデフォルトの動作です。 ### 組み込みローダー {#built-in-loaders} **サードパーティ画像サービス**用の既存のローダーを使用するには、選択したサービスのプロバイダーファクトリを`providers`配列に追加します。以下の例では、Imgixローダーが使用されています。 ```typescript 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パラメータとして含んでいます。 ```typescript 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機能を制御します。 ```typescript 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} プリコネクトの生成は、アプリケーションの静的解析に基づいて実行されます。つまり、画像ドメインは、次の例のように、ローダーパラメーターに直接含める必要があります。 ```typescript 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パネルに表示されます。 <img alt="Chrome DevToolsのLCP" src="assets/images/guide/image-optimization/devtools-lcp.png"> 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`は、他のシグナルに基づいて値を生成するシグナルです。 ```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 ``` ## コンポーネントでシグナルを使う `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)を参照してください。 ## 次の手順 動的なデータの宣言と管理方法を学習したので、テンプレート内でそのデータを使用する方法を学習する時間です。 # `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`などの任意のシグナルにできます。`source`の値が変更されると、`linkedSignal`は提供された`computation`の結果にその値を更新します。 `computation`は、`source`の新しい値と`previous`オブジェクトを受け取る関数です。`previous`オブジェクトには、`previous.source`（`source`の以前の値）、`previous.value`（`computation`の以前の結果）の2つのプロパティがあります。これらの以前の値を使用して、計算の新しい結果を決定できます。 HELPFUL: When using the `previous` parameter, it is necessary to provide the generic type arguments of `linkedSignal` explicitly. The first generic type corresponds with the type of `source` and the second generic type determines the output type of `computation`. ## カスタムの等価比較 `linkedSignal`は他のシグナルと同様に、カスタムの等価比較関数を設定できます。この関数は、下流の依存関係によって`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リクエストを行います。 # 依存性の注入について 依存性の注入 (DI) はAngularの基本的な概念の1つです。DIはAngularフレームワークに組み込まれており、コンポーネント、ディレクティブ、パイプ、注入可能などのAngularデコレーターを持つクラスが、必要な依存関係を設定できるようにします。 DIシステムには、依存関係のコンシューマーと依存関係のプロバイダーという2つの主要な役割があります。 Angularは `Injector` という抽象化を使用して、依存関係のコンシューマーと依存関係のプロバイダー間の相互作用を促進します。依存関係が要求されると、インジェクターは、そのレジストリにすでにインスタンスが存在するかどうかを確認します。存在しない場合は、新しいインスタンスが作成され、レジストリに格納されます。Angularは、アプリケーションのブートストラップ処理中に、アプリケーション全体で使用されるインジェクター（「ルート」インジェクターとも呼ばれます）を作成します。ほとんどの場合、インジェクターを手動で作成する必要はありませんが、プロバイダーとコンシューマーを結び付けるレイヤーがあることを知っておく必要があります。 このトピックでは、クラスが依存関係としてどのように機能するかという基本的なシナリオについて説明します。Angularでは、関数やオブジェクト、文字列やブール値などのプリミティブ型あるいはその他の型も依存関係として使用できます。詳細については、[依存関係のプロバイダー](guide/di/dependency-injection-providers) を参照してください。 ## 依存関係を提供する コンポーネントで依存関係として機能する必要がある `HeroService` というクラスを考えてみましょう。 最初のステップは、`@Injectable` デコレーターを追加して、クラスを注入できることを示すことです。 ```typescript @Injectable() class HeroService {} ``` 次のステップは、それをDIで提供できるようにすることです。 依存関係は、複数の場所で提供できます。 - [**推奨**: `providedIn` を使用してアプリケーションのルートレベルで提供する](#推奨-アプリケーションのルートレベルでprovidedInを使用して提供する) - [コンポーネントレベルで提供する](#コンポーネントレベルで提供する) - [`ApplicationConfig` を使用してアプリケーションのルートレベルで提供する](#applicationconfigを使用してアプリケーションのルートレベルで提供する) - [`NgModule` ベースのアプリケーション](#ngmoduleベースのアプリケーション) ### **推奨**: `providedIn` を使用してアプリケーションのルートレベルで提供する `providedIn` を使用してアプリケーションのルートレベルでサービスを提供すると、そのサービスを他のすべてのクラスに注入できます。 `providedIn` を使用すると、AngularとJavaScriptコードのオプティマイザーは、使用されていないサービスを効果的に削除できます（ツリーシェーキングとして知られています）。 `@Injectable` デコレーターで `providedIn: 'root'` を使用して、サービスを提供できます。 ```typescript @Injectable({ providedIn: 'root' }) class HeroService {} ``` ルートレベルでサービスを提供すると、Angularは `HeroService` の単一の共有インスタンスを作成し、それを要求するすべてのクラスに注入します。 ### コンポーネントレベルで提供する `@Component` デコレーターの `providers` フィールドを使用して、`@Component` レベルでサービスを提供できます。 この場合、`HeroService` は、このコンポーネントのすべてのインスタンス、およびテンプレートで使用される他のコンポーネントやディレクティブで使用できるようになります。 例： ```typescript @Component({ selector: 'hero-list', template: '...', providers: [HeroService] }) class HeroListComponent {} ``` コンポーネントレベルでプロバイダーを登録すると、そのコンポーネントの新しいインスタンスごとに、サービスの新しいインスタンスが取得されます。 NOTE: このようにサービスを宣言すると、`HeroService` は、サービスが使用されていなくても、常にアプリケーションに含まれます。 ### `ApplicationConfig` を使用してアプリケーションのルートレベルで提供する `bootstrapApplication` 関数に渡される `ApplicationConfig` の `providers` フィールドを使用して、アプリケーションレベルでサービスまたはその他の `Injectable` を提供できます。 以下の例では、`HeroService` は、すべてのコンポーネント、ディレクティブ、およびパイプで使用できます。 ```typescript export const appConfig: ApplicationConfig = { providers: [ { provide: HeroService }, ] }; ``` 次に、`main.ts` で： ```typescript bootstrapApplication(AppComponent, appConfig) ``` NOTE: このようにサービスを宣言すると、`HeroService` は、サービスが使用されていなくても、常にアプリケーションに含まれます。 ### `NgModule` ベースのアプリケーション `@NgModule` ベースのアプリケーションは、`@NgModule` デコレーターの `providers` フィールドを使用して、アプリケーションレベルで使用可能なサービスまたはその他の `Injectable` を提供します。 モジュールで提供されたサービスは、モジュールのすべての宣言または同じ `ModuleInjector` を共有する他のモジュールで使用できます。 すべてのエッジケースを理解するには、[階層型インジェクター](guide/di/hierarchical-dependency-injection) を参照してください。 Note: `providers` を使用してサービスを宣言すると、サービスが使用されていなくても、サービスはアプリケーションに含まれます。 ## 依存関係を注入する/消費する Use Angular's `inject` function to retrieve dependencies. ```ts import {inject, Component} from 'angular/core'; @Component({/* ... */}) export class UserProfile { // You can use the `inject` function in property initializers. private userClient = inject(UserClient); constructor() { // You can also use the `inject` function in a constructor. const logger = inject(Logger); } } ``` You can use the `inject` function in any [injection context](guide/di/dependency-injection-context). Most of the time, this is in a class property initializer or a class constructor for components, directives, services, and pipes. Angularがコンポーネントがサービスに依存していることを発見すると、最初にインジェクターにそのサービスの既存のインスタンスがあるかどうかを確認します。要求されたサービスインスタンスがまだ存在しない場合、インジェクターは登録されたプロバイダーを使用してインスタンスを作成し、サービスをAngularに返す前に、インジェクターに追加します。 要求されたすべてのサービスが解決され返されると、Angularはこれらのサービスを引数として、コンポーネントのコンストラクターを呼び出せます。 ```mermaid graph TD; subgraph Injector serviceA[Service A] heroService[HeroService] serviceC[Service C] serviceD[Service D] end direction TB componentProperty["Component <br> heroService = inject(HeroService)"] heroService-->componentProperty style componentProperty text-align: left ``` ## 次のステップ # 注入可能なサービスの作成 サービスとは、アプリケーションが必要とする値、関数、または機能を包括的に表すカテゴリーです。 サービスは、通常、狭く明確に定義された目的を持つクラスです。 コンポーネントは、DIを使用できるクラスの一種です。 Angularは、モジュール性と再利用性を高めるために、コンポーネントとサービスを区別しています。 コンポーネントのビュー関連の機能を他の処理から分離することで、コンポーネントクラスをスリムで効率的にできます。 理想的には、コンポーネントの役割は、ユーザー体験を実現することだけです。 コンポーネントは、データバインディング用のプロパティとメソッドを提供し、ビュー（テンプレートによってレンダリングされる）とアプリケーションロジック（多くの場合、モデルの概念が含まれる）の仲介役を果たすべきです。 コンポーネントは、サーバーからのデータの取得、ユーザー入力の検証、またはコンソールへの直接ログ記録など、特定のタスクをサービスに委譲できます。 このような処理タスクを注入可能サービスクラスで定義することで、これらのタスクをどのコンポーネントからも利用できるようになります。 また、状況に応じて、同じ種類のサービスの異なるプロバイダーを構成することで、アプリケーションをより適応性高くできます。 Angularは、これらの原則を強制しません。 Angularは、アプリケーションロジックをサービスに分解し、それらのサービスをDIを介してコンポーネントに提供することを容易にすることで、これらの原則に従うように支援します。 ## サービスの例 ブラウザコンソールにログ記録するサービスクラスの例を以下に示します。 ``` export class Logger { log(msg: unknown) { console.log(msg); } error(msg: unknown) { console.error(msg); } warn(msg: unknown) { console.warn(msg); } } ``` サービスは、他のサービスに依存できます。 たとえば、次の`HeroService`は`Logger`サービスに依存し、`BackendService`を使用してヒーローを取得します。 そのサービスは、さらに`HttpClient`サービスに依存して、サーバーからヒーローを非同期に取得する場合があります。 ``` 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; } } ``` ## 注入可能なサービスの作成 Angular CLIは、新しいサービスを作成するためのコマンドを提供します。 次の例では、既存のアプリケーションに新しいサービスを追加します。 `src/app/heroes`フォルダーに新しい`HeroService`クラスを生成するには、次の手順に従います。 1. 次の[Angular CLI](/tools/cli)コマンドを実行します。 ```sh ng generate service heroes/hero ``` このコマンドは、次のデフォルトの`HeroService`を作成します。 ``` import { Injectable } from '@angular/core'; @Injectable({ providedIn: 'root', }) export class HeroService {} ``` `@Injectable()`デコレーターは、AngularがDIシステムでこのクラスを使用できることを指定します。 メタデータ`providedIn: 'root'`は、`HeroService`がアプリケーション全体で提供されることを意味します。 ヒーローのモックデータを取得するために、`mock.heroes.ts`からヒーローを返す`getHeroes()`メソッドを追加します。 ``` import { Injectable } from '@angular/core'; import { HEROES } from './mock-heroes'; @Injectable({ // このサービスがルートアプリケーションインジェクターによって作成されることを宣言します。 providedIn: 'root', }) export class HeroService { getHeroes() { return HEROES; } } ``` 明確さと保守性の観点から、コンポーネントとサービスは別々のファイルに定義することをお勧めします。 ## サービスの注入 コンポーネントに依存性としてサービスを注入するには、依存性を表すクラスフィールドを宣言し、Angularの`inject`関数を使用して初期化できます。 次の例では、`HeroListComponent`内で`HeroService`を指定しています。 `heroService`の型は`HeroService`です。 ``` import { inject } from "@angular/core"; export class HeroListComponent { private heroService = inject(HeroService); } ``` コンポーネントのコンストラクターを使用しても同様に、サービスをコンポーネントに注入できます: ``` constructor(private heroService: HeroService) ``` `inject`メソッドはクラスと関数の両方で使用できますが、コンストラクターメソッドは当然ながらクラスコンストラクターでのみ使用できます。ただし、いずれの場合も、依存性は通常コンポーネントの構築または初期化において、有効な[注入コンテキスト](guide/di/dependency-injection-context)でのみ注入できます。 ## 他のサービスでのサービスの注入 サービスが別のサービスに依存する場合、コンポーネントへの注入と同じパターンに従います。 次の例では、`HeroService`は`Logger`サービスに依存して、そのアクティビティを報告します。 ``` 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; } } ``` この例では、`getHeroes()`メソッドは、ヒーローを取得する際にメッセージをログ記録することで、`Logger`サービスを使用しています。 ## 次のステップ # 依存関係プロバイダーの設定 前のセクションでは、クラスインスタンスを依存関係として使用する仕組みについて説明しました。 クラスに加えて、`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) 関数を使用してインスタンスを注入できます。 ## クラスコンストラクター DIシステムがクラスをインスタンス化するたびに、注入コンテキスト内でインスタンス化されます。これは、フレームワーク自体によって処理されます。クラスのコンストラクターは、そのランタイムコンテキストで実行され、これにより [`inject`](api/core/inject) 関数を使用してトークンを注入できます。 ```typescript class MyComponent { private service1: Service1; private service2: Service2 = inject(Service2); // コンテキスト内 constructor() { this.service1 = inject(Service1) // コンテキスト内 } } ``` ## コンテキスト内のスタックフレーム 一部のAPIは、注入コンテキストで実行されるように設計されています。これは、たとえば、ルーターガードの場合です。これにより、ガード関数内で [`inject`](api/core/inject) を使用してサービスにアクセスできます。 `CanActivateFn` の例を次に示します。 ```typescript const canActivateTeam: CanActivateFn = (route: ActivatedRouteSnapshot, state: RouterStateSnapshot) => { return inject(PermissionsService).canActivate(inject(UserToken), route.params.id); }; ``` ## 注入コンテキスト内で実行する すでに注入コンテキスト内にいない状態で、特定の関数を注入コンテキスト内で実行したい場合は、`runInInjectionContext` を使用できます。 これには、たとえば `EnvironmentInjector` のような特定のインジェクターへのアクセスが必要です。 ``` @Injectable({ providedIn: 'root', }) export class HeroService { private environmentInjector = inject(EnvironmentInjector); someMethod() { runInInjectionContext(this.environmentInjector, () => { inject(SomeService); // 注入されたサービスで必要な処理を行います }); } } ``` `inject` は、インジェクターが要求されたトークンを解決できる場合にのみインスタンスを返します。 ## コンテキストのアサート Angularは、現在のコンテキストが注入コンテキストであることをアサートするための `assertInInjectionContext` ヘルパー関数を提供します。 ## コンテキスト外での DI の使用 注入コンテキスト外で [`inject`](api/core/inject) を呼び出したり、`assertInInjectionContext` を呼び出したりすると、[エラー NG0203](/errors/NG0203) がスローされます。 ## 階層型インジェクター Angularのインジェクターには、注入可能なオブジェクトのアプリケーション内での可視性を思いどおりにするために活用できるルールがあります。 これらのルールを理解することで、プロバイダーをアプリケーションレベル、コンポーネント内、またはディレクティブ内で宣言する必要があるかどうかを判断できます。 Angularで構築するアプリケーションは非常に大きくなる可能性があり、この複雑さを管理する1つの方法は、アプリケーションを明確に定義されたコンポーネントツリーに分割することです。 ページのセクションには、アプリケーションの残りの部分とは完全に独立して動作する部分があり、そのセクションに必要なサービスやその他の依存関係のローカルコピーが持つことができます。 これらのアプリケーションセクションが使用するサービスの一部は、アプリケーションの他の部分やコンポーネントツリーの上位にある親コンポーネントと共有される場合がありますが、他の依存関係はプライベートであることを目的としています。 階層型の依存性の注入を使用すると、アプリケーションのセクションを分離してアプリケーションの残りの部分と共有されていない独自のプライベート依存関係を与えるか、親コンポーネントが特定の依存関係を子コンポーネントのみに共有してコンポーネントツリーの残りの部分には共有しないようにできます。階層型の依存性の注入により、必要な場合にのみ、アプリケーションのさまざまな部分間で依存関係を共有できます。 ## インジェクター階層のタイプ 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()` を使用してサービスを提供します。 ```typescript 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` を遅延読み込みするときに作成されます。 ### プラットフォームインジェクター `root` の上にさらに2つのインジェクター、追加の `EnvironmentInjector` と `NullInjector()` があります。 Angularが `main.ts` の次の内容でアプリケーションをブートストラップする方法を検討してください。 ```javascript 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` を構成します。 ```typescript @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` 階層を検索します。 ## 解決修飾子 Angular's resolution behavior can be modified with `optional`, `self`, `skipSelf` and `host`. Import each of them from `@angular/core` and use each in the `inject` configuration when you inject your service. ### 修飾子の種類 解決修飾子は、次の3つのカテゴリーに分類されます。 * What to do if Angular doesn't find what you're looking for, that is `optional` * Where to start looking, that is `skipSelf` * Where to stop looking, `host` and `self` デフォルトでは、Angularは常に現在の `Injector` から始めて、すべてを上に検索し続けます。 修飾子を使用すると、開始位置（または _self_ 位置）と終了位置を変更できます。 さらに、次の修飾子をすべて組み合わせることができます。 * `host` and `self` * `skipSelf` and `self`. ### `optional` `optional` allows Angular to consider a service you inject to be optional. そのため、実行時に解決できない場合、Angularはサービスをエラーをスローするのではなく、 `null` として解決します。 次の例では、サービス `OptionalService` はサービス `ApplicationConfig`や`@NgModule()`、コンポーネントクラスで提供されていないため、アプリケーションのどこにも使用できません。 ``` export class OptionalComponent { public optional? = inject(OptionalService, {optional: true}); } ``` ### `self` Use `self` so that Angular will only look at the `ElementInjector` for the current component or directive. A good use case for `self` is to inject a service but only if it is available on the current host element. To avoid errors in this situation, combine `self` with `optional`. For example, in the following `SelfNoDataComponent`, notice the injected `LeafService` as a property. ``` @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}); } ``` In this example, there is a parent provider and injecting the service will return the value, however, injecting the service with `self` and `optional` will return `null` because `self` tells the injector to stop searching in the current host element. 別の例では、 `FlowerService` のプロバイダーを備えたコンポーネントクラスを示しています。 この場合、インジェクターは現在の `ElementInjector` より先を見ずに、 `FlowerService` を見つけて、チューリップ <code>🌷</code> を返します。 ``` ### `skipSelf` `skipSelf` is the opposite of `self`. With `skipSelf`, Angular starts its search for a service in the parent `ElementInjector`, rather than in the current one. そのため、親 `ElementInjector` が `emoji` にシダ <code>🌿</code> 値を使用していたが、コンポーネントの `providers` 配列にカエデの葉 <code>🍁</code> が含まれている場合、Angular はカエデの葉 <code>🍁</code> を無視して、シダ <code>🌿</code> を使用します。 これをコードで確認するために、親コンポーネントが使用する `emoji` の次の値を想定します。これは、このサービスと同じです。 <docs-code header="src/app/leaf.service.ts" language="typescript"> export class LeafService { emoji = '🌿'; } ``` 子コンポーネントに、異なる値、カエデの葉 <code>🍁</code> が含まれていると想像してください。ただし、親の値を使用したいとします。 This is when you'd use `skipSelf`: ``` @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` option with `optional` Use the `skipSelf` option with `optional` to prevent an error if the value is `null`. In the following example, the `Person` service is injected during property initialization. `skipSelf` tells Angular to skip the current injector and `optional` will prevent an error should the `Person` service be `null`. ```typescript class Person { parent = inject(Person, {optional: true, skipSelf: true}) } ``` ### `host` <!-- TODO: Remove ambiguity between host and self. --> `host` lets you designate a component as the last stop in the injector tree when searching for providers. Even if there is a service instance further up the tree, Angular won't continue looking. Use `host` as follows: ``` @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}); } ``` Since `HostComponent` has the `host` option , no matter what the parent of `HostComponent` might have as a `flower.emoji` value, the `HostComponent` will use tulip <code>🌷</code>. ### Modifiers with constructor injection Similarly as presented before, the behavior of constructor injection can be modified with `@Optional()`, `@Self()`, `@SkipSelf()` and `@Host()`. Import each of them from `@angular/core` and use each in the component class constructor when you inject your service. ``` export class SelfNoDataComponent { constructor(@Self() @Optional() public leaf?: LeafService) { } } ``` ## テンプレートの論理構造 コンポーネントクラスでサービスを提供する場合、サービスは、サービスの提供場所と方法に応じて、 `ElementInjector` ツリー内で可視になります。 Angularテンプレートの基になる論理構造を理解すると、サービスの構成と、その可視性の制御のための基礎が得られます。 コンポーネントは、次の例のようにテンプレートで使用されます。 ```html <app-root> <app-child></app-child>; </app-root> ``` HELPFUL: 通常、コンポーネントとそのテンプレートは別々のファイルに宣言します。 注入システムの動作を理解するために、それらを組み合わせた論理ツリーの視点から見ると便利です。 用語 _論理_ は、アプリケーションのDOMツリーであるレンダリングツリーと区別しています。 コンポーネントテンプレートの場所を示すために、このガイドでは `<#VIEW>` 疑似要素を使用します。この疑似要素は、レンダリングツリーには実際に存在せず、メンタルモデルの目的でのみ存在します。 以下は、 `<app-root>` と `<app-child>` のビューツリーを1つの論理ツリーに結合した例です。 ```html <app-root> <#VIEW> <app-child> <#VIEW> …ここにコンテンツが挿入されます… </#VIEW> </app-child> </#VIEW> </app-root> ``` `<#VIEW>` の区切りの考え方を理解することは、特にコンポーネントクラスでサービスを構成する場合に重要です。 ## 例： `@Component()` でサービスを提供する `@Component()`（または `@Directive()`）デコレーターを使用してサービスを提供する方法は、サービスの可視性を決めます。 The following sections demonstrate `providers` and `viewProviders` along with ways to modify service visibility with `skipSelf` and `host`. コンポーネントクラスでは、次の2つの方法でサービスを提供できます。 | 配列 | 詳細 | |:--- |:--- | | `providers` 配列を使用する | `@Component({ providers: [SomeService] })` | | `viewProviders` 配列を使用する | `@Component({ viewProviders: [SomeService] })` | 次の例では、Angularアプリケーションの論理ツリーが表示されます。 テンプレートのコンテキストでインジェクターがどのように動作するかを示すために、論理ツリーはアプリケーションのHTML構造を表します。 たとえば、論理ツリーは、 `<child-component>` が `<parent-component>` の直接の子であることを示します。 論理ツリーでは、 `@Provide` 、 `@Inject` 、および `@ApplicationConfig` という特殊な属性が表示されます。 これらは実際の属性ではなく、内部で何が起こっているかを説明するためにここにあります。 | Angular サービス属性 | 詳細 | |:--- |:--- | | `@Inject(Token)=>Value` | 論理ツリーのこの場所に `Token` が注入されている場合、その値は `Value` になります。 | | `@Provide(Token=Value)` | 論理ツリーのこの場所に `Token` が `Value` で提供されていることを示します。 | | `@ApplicationConfig` | この場所でフォールバック `EnvironmentInjector` を使用する必要があることを示します。 | ### アプリケーション構造の例 この例では、 `emoji` の値が赤いハイビスカス <code>🌺</code> である、 `root` に提供される `FlowerService` があります。 ``` @Injectable({ providedIn: 'root' }) export class FlowerService { emoji = '🌺'; } ``` `AppComponent` と `ChildComponent` のみが含まれるアプリケーションを検討してください。 最も基本的なレンダリングされたビューは、次のようなネストされたHTML要素のように見えます。 ```html <app-root> <!-- AppComponent セレクター --> <app-child> <!-- ChildComponent セレクター --> </app-child> </app-root> ``` ただし、裏側では、Angularはインジェクションリクエストを解決するときに、次のような論理ビュー表現を使用します。 ```html <app-root> <!-- AppComponent セレクター --> <#VIEW> <app-child> <!-- ChildComponent セレクター --> <#VIEW> </#VIEW> </app-child> </#VIEW> </app-root> ``` ここでの `<#VIEW>` は、テンプレートのインスタンスを表しています。 各コンポーネントには、独自の `<#VIEW>` があることに注意してください。 この構造を理解することで、サービスの提供方法と注入方法を把握し、サービスの可視性を完全に制御できます。 次に、 `<app-root>` が `FlowerService` を注入しているとします。 ``` export class AppComponent { flower = inject(FlowerService); } ``` 結果を視覚化するために、 `<app-root>` テンプレートにバインディングを追加します。 ``` <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` 配列を使用する 次に、 `ChildComponent` クラスで、今後のセクションでより複雑な解決ルールを説明するために、 `FlowerService` のプロバイダーを追加します。 ``` @Component({ selector: 'app-child', templateUrl: './child.component.html', styleUrls: ['./child.component.css'], // プロバイダー配列を使用してサービスを提供します providers: [{ provide: FlowerService, useValue: { emoji: '🌻' } }] }) export class ChildComponent { // サービスを注入します flower = inject(FlowerService); } ``` `FlowerService` が `@Component()` デコレーターで提供されるようになったため、 `<app-child>` がサービスを要求すると、インジェクターは `<app-child>` の `ElementInjector` ほど遠くまでしか見なくてもよくなります。 インジェクターは、インジェクターツリーをさらに検索する必要はありません。 次のステップは、 `ChildComponent` テンプレートにバインディングを追加することです。 ``` <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` 配列を使用する `viewProviders` 配列は、 `@Component()` デコレーターでサービスを提供する別の方法です。 `viewProviders` を使用すると、サービスは `<#VIEW>` で可視になります。 HELPFUL: ステップは `providers` 配列を使用する場合と同じですが、 `viewProviders` 配列を使用する点が異なります。 ステップバイステップの手順については、このセクションを続行してください。 自分で設定できる場合は、[サービスの可用性を変更する](#visibility-of-provided-tokens) に進んでください。 デモのために、 `AnimalService` を作成して、 `viewProviders` を示します。 最初に、 `emoji` プロパティがクジラ <code>🐳</code> である `AnimalService` を作成します。 ``` import { Injectable } from '@angular/core'; @Injectable({ providedIn: 'root' }) export class AnimalService { emoji = '🐳'; } ``` `FlowerService` と同じパターンに従って、 `AppComponent` クラスに `AnimalService` を注入します。 ``` export class AppComponent { public flower = inject(FlowerService); public animal = inject(AnimalService); } ``` HELPFUL: `FlowerService` に関連するコードはすべてそのままにしておくことができます。これにより、 `AnimalService` との比較が可能になります。 `viewProviders` 配列を追加し、 `<app-child>` クラスにも `AnimalService` を注入しますが、 `emoji` に異なる値を与えます。 ここでは、犬 <code>🐶</code> の値があります。 ``` @Component({ selector: 'app-child', templateUrl: './child.component.html', styleUrls: ['./child.component.css'], // サービスを提供します providers: [{ provide: FlowerService, useValue: { emoji: '🌻' } }], viewProviders: [{ provide: AnimalService, useValue: { emoji: '🐶' } }] }) export class ChildComponent { // サービスを注入します flower = inject(FlowerService); animal = inject(AnimalService) ... } ``` `ChildComponent` と `AppComponent` のテンプレートにバインディングを追加します。 `ChildComponent` テンプレートに、次のバインディングを追加します。 ``` <p>Emoji from AnimalService: {{animal.emoji}}</p> ``` さらに、 `AppComponent` テンプレートにも同じものを追加します。 ``` <p>Emoji from AnimalService: {{animal.emoji}}</p>s ``` これで、ブラウザに両方の値が表示されます。 ``` 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=>"🐶")> <!-- ^^viewProviders を使用すると、AnimalService は <#VIEW> で使用可能になります--> <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` の違い `viewProviders` フィールドは、概念的には `providers` と似ていますが、1つの顕著な違いがあります。 `viewProviders` で構成されたプロバイダーは、コンポーネントの論理的な子になる投影されたコンテンツには可視ではありません。 `providers` と `viewProviders` の違いを確認するために、別のコンポーネントを例に追加して、 `InspectorComponent` と呼びます。 `InspectorComponent` は、 `ChildComponent` の子になります。 In `inspector.component.ts`, inject the `FlowerService` and `AnimalService` during property initialization: ``` export class InspectorComponent { flower = inject(FlowerService); animal = inject(AnimalService); } ``` `providers` または `viewProviders` 配列は必要ありません。 次に、 `inspector.component.html` に、以前のコンポーネントと同じマークアップを追加します。 ``` <p>Emoji from FlowerService: {{flower.emoji}}</p> <p>Emoji from AnimalService: {{animal.emoji}}</p> ``` `InspectorComponent` を `ChildComponent` の `imports` 配列に追加することを忘れないでください。 ``` @Component({ ... imports: [InspectorComponent] }) ``` 次に、 `child.component.html` に次を追加します。 ``` ... <div class="container"> <h3>Content projection</h3> <ng-content></ng-content> </div> <h3>Inside the view</h3> <app-inspector></app-inspector> ``` `<ng-content>` を使用するとコンテンツを投影でき、 `ChildComponent` テンプレート内の `<app-inspector>` は、 `InspectorComponent` を `ChildComponent` の子コンポーネントにします。 次に、コンテンツ投影を活用するために、 `app.component.html` に次を追加します。 ``` <app-child> <app-inspector></app-inspector> </app-child> ``` これで、ブラウザには、以前の例は省略して、次のものがレンダリングされます。 ``` ... 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=>"🐶")> <!-- ^^viewProviders を使用すると、AnimalService は <#VIEW> で使用可能になります--> <p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p> <div class="container"> <h3>Content projection</h3> <app-inspector @Inject(AnimalService) animal=>"🐳"> <p>Emoji from AnimalService: {{animal.emoji}} (🐳)</p> </app-inspector> </div> <app-inspector> <#VIEW @Inject(AnimalService) animal=>"🐶"> <p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p> </#VIEW> </app-inspector> </#VIEW> </app-child> </#VIEW> </app-root> ``` `<app-inspector>` の投影されたコンテンツには、クジラ <code>🐳</code> が表示され、犬 <code>🐶</code> は表示されません。これは、犬 <code>🐶</code> が `<app-child>` の `<#VIEW>` の内側にあるためです。 `<app-inspector>` は、 `<#VIEW>` の内側にある場合にのみ、犬 <code>🐶</code> を表示できます。 ### 提供されたトークンの可視性 可視性デコレーターは、論理ツリー内でインジェクショントークンの検索を開始する場所と終了する場所を制御します。 To do this, place visibility configuration at the point of injection, that is, when invoking `inject()`, rather than at a point of declaration. To alter where the injector starts looking for `FlowerService`, add `skipSelf` to the `<app-child>` `inject()` invocation where `FlowerService` is injected. This invocation is a property initializer the `<app-child>` as shown in `child.component.ts`: ```typescript flower = inject(FlowerService, { skipSelf: true }) ``` With `skipSelf`, the `<app-child>` injector doesn't look to itself for the `FlowerService`. 代わりに、インジェクターは `<app-root>` の `ElementInjector` で `FlowerService` の検索を開始し、何も見つかりません。 次に、 `<app-child>` の `ModuleInjector` に戻り、 `<app-child>` と `<app-root>` が同じ `ModuleInjector` を共有しているため、赤いハイビスカス <code>🌺</code> 値が見つかります。 UIには次のように表示されます。 ``` Emoji from FlowerService: 🌺 ``` 論理ツリーでは、この同じ考え方は次のようになります。 ```html <app-root @ApplicationConfig @Inject(FlowerService) flower=>"🌺"> <#VIEW> <app-child @Provide(FlowerService="🌻")> <#VIEW @Inject(FlowerService, SkipSelf)=>"🌺"> <!-- SkipSelf を使用すると、インジェクターはツリー上の次のインジェクター（app-root）を調べます --> </#VIEW> </app-child> </#VIEW> </app-root> ``` Though `<app-child>` provides the sunflower <code>🌻</code>, the application renders the red hibiscus <code>🌺</code> because `skipSelf` causes the current injector (`app-child`) to skip itself and look to its parent. If you now add `host` (in addition to the `skipSelf`), the result will be `null`. This is because `host` limits the upper bound of the search to the `app-child` `<#VIEW>`. 論理ツリーでの考え方は次のとおりです。 ```html <app-root @ApplicationConfig @Inject(FlowerService) flower=>"🌺"> <#VIEW> <!-- ここで検索を終了して null を返します--> <app-child @Provide(FlowerService="🌻")> <!-- ここで検索を開始します --> <#VIEW inject(FlowerService, {skipSelf: true, host: true, optional:true})=>null> </#VIEW> </app-parent> </#VIEW> </app-root> ``` Here, the services and their values are the same, but `host` stops the injector from looking any further than the `<#VIEW>` for `FlowerService`, so it doesn't find it and returns `null`. ### `skipSelf` and `viewProviders` 覚えておいてください。 `<app-child>` は、 `viewProviders` 配列で `AnimalService` を提供し、その値は犬 <code>🐶</code> です。 インジェクターは、 `<app-child>` の `ElementInjector` を `AnimalService` について調べるだけなので、クジラ <code>🐳</code> は見えません。 As in the `FlowerService` example, if you add `skipSelf` to the `inject()` of `AnimalService`, the injector won't look in the `ElementInjector` of the current `<app-child>` for the `AnimalService`. 代わりに、インジェクターは `<app-root>` の `ElementInjector` で検索を開始します。 ```typescript @Component({ selector: 'app-child', … viewProviders: [ { provide: AnimalService, useValue: { emoji: '🐶' } }, ], }) ``` The logical tree looks like this with `skipSelf` in `<app-child>`: ```html <app-root @ApplicationConfig @Inject(AnimalService=>"🐳")> <#VIEW><!-- 検索はここで開始します --> <app-child> <#VIEW @Provide(AnimalService="🐶") @Inject(AnimalService, SkipSelf=>"🐳")> <!--Add skipSelf --> </#VIEW> </app-child> </#VIEW> </app-root> ``` With `skipSelf` in the `<app-child>`, the injector begins its search for the `AnimalService` in the `<app-root>` `ElementInjector` and finds whale <code>🐳</code>. ### `host` and `viewProviders` If you just use `host` for the injection of `AnimalService`, the result is dog <code>🐶</code> because the injector finds the `AnimalService` in the `<app-child>` `<#VIEW>` itself. The `ChildComponent` configures the `viewProviders` so that the dog emoji is provided as `AnimalService` value. You can also see `host` the `inject()`: ```typescript @Component({ selector: 'app-child', … viewProviders: [ { provide: AnimalService, useValue: { emoji: '🐶' } }, ] }) export class ChildComponent { animal = inject(AnimalService, { host: true }) } ``` `host: true` causes the injector to look until it encounters the edge of the `<#VIEW>`. ```html <app-root @ApplicationConfig @Inject(AnimalService=>"🐳")> <#VIEW> <app-child> <#VIEW @Provide(AnimalService="🐶") inject(AnimalService, {host: true}=>"🐶")> <!-- host stops search here --> </#VIEW> </app-child> </#VIEW> </app-root> ``` 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: '🦔' } }, ], }) ``` Next, add `skipSelf` along with `host` to the `inject()` for the `AnimalService` injection in `child.component.ts`. Here are `host` and `skipSelf` in the `animal` property initialization: ```typescript export class ChildComponent { animal = inject(AnimalService, { host: true, skipSelf: true }); } ``` <!-- TODO: This requires a rework. It seems not well explained what `viewProviders`/`injectors` is here and how `host` works. --> When `host` and `skipSelf` were applied to the `FlowerService`, which is in the `providers` array, the result was `null` because `skipSelf` starts its search in the `<app-child>` injector, but `host` stops searching at `<#VIEW>` —where there is no `FlowerService` 論理ツリーでは、 `FlowerService` は `<app-child>` で可視であり、 `<#VIEW>` では可視ではないことがわかります。 ただし、 `AppComponent` の `viewProviders` 配列で提供されている `AnimalService` は可視です。 論理ツリーの表現は、これが理由を示しています。 ```html <app-root @ApplicationConfig @Inject(AnimalService=>"🐳")> <#VIEW @Provide(AnimalService="🦔") @Inject(AnimalService, @Optional)=>"🦔"> <!-- ^^skipSelf starts here, host stops here^^ --> <app-child> <#VIEW @Provide(AnimalService="🐶") inject(AnimalService, {skipSelf:true, host: true, optional: true})=>"🦔"> <!-- Add skipSelf ^^--> </#VIEW> </app-child> </#VIEW> </app-root> ``` `skipSelf`, causes the injector to start its search for the `AnimalService` at the `<app-root>`, not the `<app-child>`, where the request originates, and `host` stops the search at the `<app-root>` `<#VIEW>`. `AnimalService` は `viewProviders` 配列を介して提供されるため、インジェクターは `<#VIEW>` でハリネズミ <code>🦔</code> を見つけます。 ## 例： `ElementInjector` のユースケース さまざまなレベルで1つ以上のプロバイダーを構成する機能により、便利な可能性が開かれます。 ### シナリオ：サービスの分離 アーキテクチャ上の理由から、サービスへのアクセスを属するアプリケーションドメインに制限する必要がある場合があります。 たとえば、悪役のリストを表示する `VillainsListComponent` を構築するとします。 この悪役は、 `VillainsService` から取得されます。 `VillainsService` をルートの `AppModule` で提供すると、 `VillainsService` がアプリケーションのすべての場所で可視になります。 後で `VillainsService` を変更した場合、誤ってこのサービスに依存し始めた他のコンポーネントで何かが壊れる可能性があります。 代わりに、次のように `VillainsListComponent` の `providers` メタデータで `VillainsService` を提供する必要があります。 ``` @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つずつあります。 ### シナリオ：複数の編集セッション 多くのアプリケーションでは、ユーザーは同時に複数のオープンタスクで作業できます。 たとえば、税務申告の作成アプリケーションでは、作成者は複数の税務申告で作業し、1日を通してそれらを切り替えることができます。 そのシナリオを示すために、スーパーヒーローのリストを表示する `HeroListComponent` を考えてみてください。 ヒーローの税務申告を開くために、作成者はヒーローの名前をクリックすると、その申告を編集するためのコンポーネントが開きます。 選択したヒーローの税務申告は、それぞれ独自のコンポーネントで開き、複数の申告を同時に開くことができます。 各税務申告コンポーネントには、次の機能があります。 * 独自の税務申告の編集セッションを持ちます * 別のコンポーネントの申告に影響を与えずに税務申告を変更できます * 税務申告の変更を保存するか、キャンセルする機能があります `HeroTaxReturnComponent` に、変更を管理および復元するためのロジックがあるとします。 これは、ヒーローの税務申告にとっては簡単なタスクです。 現実世界では、豊富な税務申告データモデルでは、変更管理が複雑になります。 この例のように、この管理をヘルパーサービスに委任できます。 `HeroTaxReturnService` は、単一の `HeroTaxReturn` をキャッシュし、その申告への変更を追跡し、保存または復元できます。 また、注入によって取得したアプリケーション全体のシングルトン `HeroService` に委任します。 ``` import { Injectable } from '@angular/core'; import { HeroTaxReturn } from './hero'; import { HeroesService } from './heroes.service'; @Injectable() export class HeroTaxReturnService { private currentTaxReturn!: HeroTaxReturn; private originalTaxReturn!: HeroTaxReturn; private heroService = inject(HeroesService); set taxReturn(htr: HeroTaxReturn) { this.originalTaxReturn = htr; this.currentTaxReturn = htr.clone(); } get taxReturn(): HeroTaxReturn { return this.currentTaxReturn; } restoreTaxReturn() { this.taxReturn = this.originalTaxReturn; } saveTaxReturn() { this.taxReturn = this.currentTaxReturn; this.heroService.saveTaxReturn(this.currentTaxReturn).subscribe(); } } ``` 以下は、 `HeroTaxReturnService` を使用する `HeroTaxReturnComponent` です。 ``` import { Component, EventEmitter, input, output } from '@angular/core'; import { HeroTaxReturn } from './hero'; import { HeroTaxReturnService } from './hero-tax-return.service'; @Component({ selector: 'app-hero-tax-return', templateUrl: './hero-tax-return.component.html', styleUrls: [ './hero-tax-return.component.css' ], providers: [ HeroTaxReturnService ] }) export class HeroTaxReturnComponent { message = ''; close = output<void>(); get taxReturn(): HeroTaxReturn { return this.heroTaxReturnService.taxReturn; } taxReturn = input.required<HeroTaxReturn>(); constructor() { effect(() => { this.heroTaxReturnService.taxReturn = this.taxReturn(); }) } private heroTaxReturnService = inject(HeroTaxReturnService); onCanceled() { this.flashMessage('Canceled'); this.heroTaxReturnService.restoreTaxReturn(); } onClose() { this.close.emit(); } onSaved() { this.flashMessage('Saved'); this.heroTaxReturnService.saveTaxReturn(); } flashMessage(msg: string) { this.message = msg; setTimeout(() => this.message = '', 500); } } ``` _編集対象の税務申告_ は、 `input` プロパティを介して到着します。これは、ゲッターとセッターで実装されています。 セッターは、コンポーネント自身の `HeroTaxReturnService` インスタンスを、受信した申告で初期化します。 ゲッターは常に、そのサービスがヒーローの現在の状態であると判断したものを返します。 コンポーネントは、この税務申告を保存および復元することもサービスに要求します。 これは、サービスがアプリケーション全体のシングルトンである場合に機能しません。 すべてのコンポーネントは同じサービスインスタンスを共有し、各コンポーネントは別のヒーローに属する税務申告を上書きします。 これを防ぐために、コンポーネントレベルのインジェクター `HeroTaxReturnComponent` を構成して、コンポーネントメタデータの `providers` プロパティを使用してサービスを提供します。 ``` providers: [HeroTaxReturnService] ``` `HeroTaxReturnComponent` には、 `HeroTaxReturnService` の独自の提供者がいます。 覚えておいてください。すべてのコンポーネントの _インスタンス_ には、独自のインジェクターがあります。 コンポーネントレベルでサービスを提供すると、コンポーネントの _すべての_ インスタンスは、サービスのプライベートインスタンスを1つずつ取得することが保証されます。これにより、税務申告が上書きされないようにします。 HELPFUL: シナリオコードの残りは、ドキュメントの他の場所で学習できる他のAngular機能とテクニックに依存しています。 ### シナリオ：特殊なプロバイダー 別のレベルでサービスを再度提供するもう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 ``` ## 依存性の注入の詳細 # 軽量インジェクショントークンを使用したクライアントアプリケーションサイズの最適化 このページでは、ライブラリ開発者に推奨される依存性の注入テクニックの概要を概念的に説明します。 *軽量インジェクショントークン* を使用してライブラリを設計すると、ライブラリを使用するクライアントアプリケーションのバンドルサイズを最適化できます。 ツリーシェイク可能なプロバイダーを使用することで、コンポーネントと注入可能なサービス間の依存関係の構造を管理してバンドルサイズを最適化できます。 通常、これにより、アプリケーションで実際に使用されていない提供されたコンポーネントまたはサービスが、コンパイラによってバンドルから削除されます。 Angularがインジェクショントークンを格納する方法により、使用されていないコンポーネントまたはサービスがバンドルに含まれてしまう場合があります。 このページでは、軽量なインジェクショントークンを使用することで適切なツリーシェイクをサポートする依存性の注入の設計パターンについて説明します。 軽量なインジェクショントークン設計パターンは、特にライブラリ開発者にとって重要です。 これにより、アプリケーションがライブラリの機能の一部のみを使用する場合、未使用のコードをクライアントのアプリケーションバンドルから削除できます。 アプリケーションがライブラリを使用する場合、ライブラリが提供するサービスの中には、クライアントアプリケーションで使用されないものがある場合があります。 この場合、アプリケーション開発者は、そのサービスがツリーシェイクされ、コンパイルされたアプリケーションのサイズに影響を与えないことを期待する必要があります。 アプリケーション開発者はライブラリのツリーシェイクの問題を認識したり、修正したりできないため、ライブラリ開発者の責任となります。 未使用のコンポーネントの保持を防ぐため、ライブラリでは軽量インジェクショントークン設計パターンを使用する必要があります。 ## トークンが保持される場合 トークン保持が発生する状況をより明確に説明するために、ライブラリカードコンポーネントを提供するライブラリを検討してください。 このコンポーネントには本体が含まれており、オプションでヘッダーを含めることができます。 ```html <lib-card>; <lib-header>…</lib-header>; </lib-card>; ``` 一般的な実装では、 `<lib-card>` コンポーネントは、次の例のように `@ContentChild()` または `@ContentChildren()` を使用して `<lib-header>` と `<lib-body>` を取得します。 ```typescript @Component({ selector: 'lib-header', …, }) class LibHeaderComponent {} @Component({ selector: 'lib-card', …, }) class LibCardComponent { @ContentChild(LibHeaderComponent) header: LibHeaderComponent|null = null; } ``` `<lib-header>` はオプションなので、要素はテンプレートに最小限の形式 `<lib-card></lib-card>` で表示できます。 この場合、 `<lib-header>` は使用されず、ツリーシェイクされることを期待しますが、実際にはそうなりません。 これは、 `LibCardComponent` には `LibHeaderComponent` への参照が2つあるためです。 ```typescript @ContentChild(LibHeaderComponent) header: LibHeaderComponent; ``` * これらの参照の1つは *型の位置* にあります。つまり、 `LibHeaderComponent` を型として指定します: `header: LibHeaderComponent;`。 * もう1つの参照は *値の位置* にあります。つまり、LibHeaderComponentは `@ContentChild()` パラメータデコレーターの値です: `@ContentChild(LibHeaderComponent)`。 コンパイラはこれらの位置にあるトークン参照を異なる方法で処理します。 * コンパイラは、TypeScriptから変換した後の *型の位置* の参照を消去するため、ツリーシェイクには影響しません。 * コンパイラは、*値の位置* の参照をランタイムに保持する必要があり、これが**妨げます** コンポーネントがツリーシェイクされること。 この例では、コンパイラは値位置にある `LibHeaderComponent` トークンを保持します。 これにより、アプリケーションで実際に `<lib-header>` をどこでも使用していない場合でも、参照されるコンポーネントがツリーシェイクされることがなくなります。 `LibHeaderComponent` のコード、テンプレート、スタイルを組み合わせると大きくなりすぎるため、不要に含めるとクライアントアプリケーションのサイズが大幅に増加する可能性があります。 ## 軽量インジェクショントークンパターンを使用する場合 ツリーシェイクの問題は、コンポーネントがインジェクショントークンとして使用されると発生します。 これは次の2つのケースで発生します。 * トークンは、[コンテンツクエリ](guide/components/queries#content-queries)で値の位置で使用されます。 * トークンは、コンストラクター注入の型指定子として使用されます。 次の例では、 `OtherComponent` トークンの両方の使用により、 `OtherComponent` が保持され、使用されていない場合にツリーシェイクされることがなくなります。 ```typescript 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` でどのように機能するかを示しています。 ```typescript abstract class LibHeaderToken {} @Component({ selector: 'lib-header', providers: [ {provide: LibHeaderToken, useExisting: LibHeaderComponent} ] …, }) class LibHeaderComponent extends LibHeaderToken {} @Component({ selector: 'lib-card', …, }) class LibCardComponent { @ContentChild(LibHeaderToken) header: LibHeaderToken|null = null; } ``` この例では、 `LibCardComponent` 実装は、型位置と値位置のいずれでも `LibHeaderComponent` を参照しなくなりました。 これにより、 `LibHeaderComponent` の完全なツリーシェイクが可能になります。 `LibHeaderToken` は保持されますが、具体的なインプリメンテーションのないクラス宣言に過ぎません。 小さく、コンパイル後に保持されてもアプリケーションのサイズにはほとんど影響を与えません。 代わりに、 `LibHeaderComponent` 自体が抽象 `LibHeaderToken` クラスを実装します。 このトークンをコンポーネント定義のプロバイダーとして安全に使用することで、Angularは具体的な型を正しく注入できます。 要約すると、軽量インジェクショントークンパターンは次のとおりです。 1. 抽象クラスとして表される軽量なインジェクショントークン。 1. 抽象クラスを実装するコンポーネント定義。 1. `@ContentChild()` または `@ContentChildren()` を使用した軽量なパターンの注入。 1. 軽量なインジェクショントークンを実装するプロバイダーであり、軽量インジェクショントークンを実装に関連付けます。 ### API 定義に軽量インジェクショントークンを使用する 軽量インジェクショントークンを注入するコンポーネントは、注入されたクラスのメソッドを呼び出す必要がある場合があります。 トークンはこれで抽象クラスです。注入可能コンポーネントはそのクラスを実装するため、軽量インジェクショントークンの抽象クラスに抽象メソッドも宣言する必要があります。 メソッドの実装とそのすべてのコードオーバーヘッドは、ツリーシェイク可能な注入可能コンポーネントに存在します。 これにより、親は、存在する場合、子と型安全な方法で通信できます。 たとえば、 `LibCardComponent` はこれで `LibHeaderComponent` ではなく `LibHeaderToken` をクエリします。 次の例は、パターンにより `LibCardComponent` が `LibHeaderComponent` を実際に参照せずに `LibHeaderComponent` と通信する方法を示しています。 ```typescript abstract class LibHeaderToken { abstract doSomething(): void; } @Component({ selector: 'lib-header', providers: [ {provide: LibHeaderToken, useExisting: LibHeaderComponent} ] …, }) class LibHeaderComponent extends LibHeaderToken { doSomething(): void { // Concrete implementation of `doSomething` } } @Component({ selector: 'lib-card', …, }) class LibCardComponent implement AfterContentInit { @ContentChild(LibHeaderToken) header: LibHeaderToken|null = null; ngAfterContentInit(): void { if (this.header !== null) { this.header?.doSomething(); } } } ``` この例では、親はトークンをクエリして子コンポーネントを取得し、存在する場合、結果のコンポーネント参照を保存します。 子コンポーネントのメソッドを呼び出す前に、親コンポーネントは子コンポーネントが存在するかどうかを確認します。 子コンポーネントがツリーシェイクされている場合、子コンポーネントへのランタイム参照はありません。メソッドも呼び出されません。 ### 軽量インジェクショントークンの名前付け 軽量インジェクショントークンは、コンポーネントでのみ役立ちます。 Angularスタイルガイドでは、コンポーネントに "Component" サフィックスを使用して名前を付けることを推奨しています。 例 "LibHeaderComponent" はこの規則に従っています。 コンポーネントとそのトークン間の関係を維持しながら、両者を区別する必要があります。 推奨されるスタイルは、コンポーネントのベース名にサフィックス " `Token` " を使用して軽量インジェクショントークンに名前を付けることです: " `LibHeaderToken` "。 # RxJS interop with Angular signals The `@angular/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. ```ts 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. ### 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. # 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 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 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` 型を使用することを検討してください。 CTIRICAL: リクエストメソッドのジェネリック型は、サーバーによって返されるデータに関する**アサーション**です。`HttpClient` は、実際の戻り値データがこの型と一致することを検証しません。 ## 他のタイプのデータの取得 デフォルトでは、`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` のように明示的にリテラルとして指定する必要があるかもしれません。 ## サーバーの状態を変更する 変更を伴うサーバー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 パラメータの設定 リクエスト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` でインスタンス化できます。 ## リクエストヘッダーの設定 リクエストに含めるべきリクエストヘッダーは、`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 => { // ... }); ``` ## サーバーレスポンスイベントとの対話 便宜上、`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` のように明示的にリテラルとして指定する必要があるかもしれません。 ## 生の進捗イベントを受信する `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()` 演算子は、指定された回数だけ自動的に再サブスクライブを試みます。 ### タイムアウト リクエストにタイムアウトを設定するには、他のリクエストオプションと一緒に `timeout` オプションをミリ秒数に設定できます。バックエンドリクエストが指定された時間内に完了しない場合、リクエストは中止され、エラーが発行されます。 NOTE: タイムアウトは、バックエンドHTTPリクエスト自体にのみ適用されます。リクエスト処理チェーン全体のタイムアウトではありません。したがって、このオプションは、インターセプターによって導入される遅延の影響を受けません。 ```ts http.get('/api/config', { timeout: 3000, }).subscribe({ next: config => { console.log('設定の取得に成功:', config); }, error: err => { // リクエストがタイムアウトした場合、エラーが発行されます。 } }); ``` ## 高度な fetch オプション `withFetch()` プロバイダーを使用する場合、Angularの `HttpClient` は、パフォーマンスとユーザー体験を改善できる高度なfetch APIオプションへのアクセスを提供します。これらのオプションは、fetchバックエンドを使用する場合にのみ利用できます。 ### Fetch オプション 以下のオプションは、fetchバックエンドを使用する際のリクエスト動作を細かく制御します。 #### Keep-alive 接続 `keepalive` オプションにより、リクエストはそれを開始したページよりも長く存続できます。これは、ユーザーがページから移動した場合でも完了する必要がある分析やログリクエストに特に有用です。 ```ts http.post('/api/analytics', analyticsData, { keepalive: true }).subscribe(); ``` #### HTTP キャッシュ制御 `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 のためのリクエスト優先度 `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'` を使用してください。 #### リクエストモード `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` オプションは、サーバーからのリダイレクトレスポンスを処理する方法を指定します。 ```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` オプションは、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` オプションを混在させることは避けてください。 ## Http `Observable` `HttpClient` の各リクエストメソッドは、要求されたレスポンス型の `Observable` を構築して返します。これらの `Observable` の仕組みを理解することは、`HttpClient` を使用する場合に重要です。 `HttpClient` は、RxJSが「コールド」と呼ぶ `Observable` を生成します。つまり、`Observable` がサブスクライブされるまでは、実際のリクエストは行われません。リクエストが実際にサーバーに送信されるのは、そのときだけです。同じ `Observable` を複数回購読すると、複数のバックエンドリクエストがトリガーされます。各サブスクライブは独立しています。 Tip: `HttpClient` の `Observable` は、実際のリクエストの*ブループリント*と考えることができます。 いったんサブスクライブされると、アン購読すると、進行中のリクエストが中止されます。これは、`Observable` が `async` パイプを使用してサブスクライブされている場合に非常に便利です。ユーザーが現在のページから移動すると、リクエストが自動的にキャンセルされます。さらに、`Observable` を `switchMap` などのRxJSコンビネータと使用する場合、このキャンセルによって、古いリクエストがすべてクリーンアップされます。 レスポンスが返されると、`HttpClient` からの `Observable` は通常完了します（ただし、インターセプターがこれに影響を与える可能性があります）。 自動完了のため、`HttpClient` のサブスクライブがクリーンアップされなくても、通常はメモリリークのリスクはありません。ただし、他の非同期操作と同様に、サブスクライブを使用しているコンポーネントが破棄されたときにサブスクライブをクリーンアップすることを強くお勧めします。そうしないと、サブスクライブコールバックが実行され、破棄されたコンポーネントと対話するときにエラーが発生する可能性があります。 Tip: `async` パイプまたは `toSignal` 演算子を使用して `Observable` に購読すると、サブスクライブが適切に破棄されます。 ## ベストプラクティス `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をレンダリングできます。 ```ts 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を使用して依存関係を取得できます。 たとえば、アプリケーションに `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', }); ``` ## 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` から注入できます。 `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$ = this.configService.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 You should test that your interceptors work under the desired circumstances. For example, an application may be required to add an authentication token generated by a service to each outgoing request. This behavior can be enforced with the use of an interceptor: ```ts export function authInterceptor(request: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> { const authService = inject(AuthService); const clonedRequest = request.clone({ headers: request.headers.append('X-Authentication-Token', authService.getAuthToken()), }); return next(clonedRequest); } ``` The `TestBed` configuration for this interceptor should rely on the `withInterceptors` feature. ```ts TestBed.configureTestingModule({ providers: [ AuthService, // Testing one interceptor at a time is recommended. provideHttpClient(withInterceptors([authInterceptor])), provideHttpClientTesting(), ], }); ``` The `HttpTestingController` can retrieve the request instance which can then be inspected to ensure that the request was modified. ```ts const service = TestBed.inject(AuthService); const req = httpTesting.expectOne('/api/config'); expect(req.request.headers.get('X-Authentication-Token')).toEqual(service.getAuthToken()); ``` A similar interceptor could be implemented with class based interceptors: ```ts @Injectable() export class AuthInterceptor implements HttpInterceptor { private authService = inject(AuthService); intercept(request: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>> { const clonedRequest = request.clone({ headers: request.headers.append('X-Authentication-Token', this.authService.getAuthToken()), }); return next.handle(clonedRequest); } } ``` In order to test it, the `TestBed` configuration should instead be: ```ts TestBed.configureTestingModule({ providers: [ AuthService, provideHttpClient(withInterceptorsFromDi()), provideHttpClientTesting(), // We rely on the HTTP_INTERCEPTORS token to register the AuthInterceptor as an HttpInterceptor { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true }, ], }); ``` # リアクティブフォームの概要 リアクティブフォームは、時間の経過とともに値が変化するフォーム入力の処理に、モデル駆動型のアプローチを提供します。 このガイドでは、基本的なフォームコントロールの作成と更新、複数のコントロールをグループで使用すること、フォーム値の検証、実行時にコントロールを追加または削除できる動的フォームの作成について説明します。 ## リアクティブフォームの概要 リアクティブフォームは、特定の時点におけるフォームの状態を管理するために、明示的で不変のアプローチを使用します。 フォーム状態に対する各変更は、新しい状態を返します。この状態は、変更間でモデルの整合性を維持します。 リアクティブフォームは、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-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="src/app/name-editor/name-editor.component.ts" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" visibleRegion="create-control"/> </docs-step> <docs-step title="テンプレートにコントロールを登録"> コンポーネントクラスでコントロールを作成したら、テンプレートのフォームコントロール要素に関連付ける必要があります。`ReactiveFormsModule` にも含まれている `FormControlDirective` によって提供される `formControl` バインディングを使用して、フォームコントロールをテンプレートのフォームコントロールに関連付けます。 <docs-code header="src/app/name-editor/name-editor.component.html" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" visibleRegion="control-binding" /> テンプレートバインディング構文を使用することで、フォームコントロールがテンプレートの `name` 入力要素に登録されました。フォームコントロールとDOM要素は相互に通信します。ビューはモデルの変更を反映し、モデルはビューの変更を反映します。 </docs-step> <docs-step title="コンポーネントを表示"> `name` プロパティに割り当てられた `FormControl` は、`<app-name-editor>` コンポーネントをテンプレートに追加すると表示されます。 <docs-code header="src/app/app.component.html (名前エディター)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" visibleRegion="app-name-editor"/> </docs-step> </docs-workflow> ### フォームコントロール値の表示 値は、次の方法で表示できます。 - `valueChanges` オブザーバブルを介して、`AsyncPipe` を使用してテンプレートで、または `subscribe()` メソッドを使用してコンポーネントクラスで、フォームの値の変更をリッスンできます。 - `value` プロパティを使用すると、現在の値のスナップショットを取得できます。 次の例では、テンプレートの補間を使用して、現在の値を表示する方法を示します。 <docs-code header="src/app/name-editor/name-editor.component.html (コントロール値)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" visibleRegion="display-value"/> 表示される値は、フォームコントロール要素を更新すると変更されます。 リアクティブフォームは、各インスタンスに提供されるプロパティとメソッドを介して、特定のコントロールに関する情報にアクセスできます。 基になる [AbstractControl](api/forms/AbstractControl "API リファレンス") クラスのプロパティとメソッドは、フォームの状態を制御し、[入力検証](#validating-form-input "フォーム入力の検証について学ぶ") を処理するときにメッセージを表示するタイミングを判断するために使用されます。 [API リファレンス](api/forms/FormControl "詳細な構文リファレンス") で、他の `FormControl` プロパティとメソッドについて説明します。 ### フォームコントロール値の置換 リアクティブフォームには、ユーザーの操作なしに値をプログラムで更新できる、コントロールの値をプログラムで変更するためのメソッドがあります。 フォームコントロールインスタンスは、フォームコントロールの値を更新し、提供された値の構造をコントロールの構造に対して検証する `setValue()` メソッドを提供します。 たとえば、バックエンドAPIまたはサービスからフォームデータを取得する場合は、`setValue()` メソッドを使用してコントロールを新しい値に更新し、古い値を完全に置き換えます。 次の例では、`setValue()` メソッドを使用してコントロールの値を _Nancy_ に更新するメソッドをコンポーネントクラスに追加します。 <docs-code header="src/app/name-editor/name-editor.component.ts (値の更新)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" visibleRegion="update-value"/> テンプレートに、名前の更新をシミュレートするボタンを追加します。 **名前の更新** ボタンをクリックすると、フォームコントロール要素に入力された値は現在の値として反映されます。 <docs-code header="src/app/name-editor/name-editor.component.html (値の更新)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" visibleRegion="update-value"/> フォームモデルはコントロールの真実の源であるため、ボタンをクリックすると、コンポーネントクラス内で入力の値が変更され、現在の値が上書きされます。 HELPFUL: この例では、単一のコントロールを使用しています。 [フォームグループ](#grouping-form-controls) または [フォーム配列](#creating-dynamic-forms) インスタンスで `setValue()` メソッドを使用する場合は、値がグループまたは配列の構造と一致する必要があります。 ## フォームコントロールのグループ化 {#grouping-form-controls} フォームには、通常、いくつかの関連するコントロールが含まれています。 リアクティブフォームは、複数の関連するコントロールを単一の入力フォームにグループ化する2つの方法を提供します。 | フォームグループ | 詳細 | |:--- |:--- | | フォームグループ | 一緒に管理できるコントロールの固定セットを持つフォームを定義します。このセクションでは、フォームグループの基本について説明します。また、[フォームグループのネスト](#creating-nested-form-groups "グループのネストについてさらに学ぶ") を使用して、より複雑なフォームを作成することもできます。 | | フォーム配列 | 実行時にコントロールを追加および削除できる動的フォームを定義します。また、フォーム配列をネストして、より複雑なフォームを作成することもできます。このオプションの詳細については、[動的フォームの作成](#creating-dynamic-forms)を参照してください。 | フォームコントロールインスタンスが単一の入力フィールドを制御するのと同じように、フォームグループインスタンスは、フォームコントロールインスタンスのグループ（たとえば、フォーム）のフォーム状態を追跡します。 フォームグループインスタンスの各コントロールは、フォームグループを作成するときに名前で追跡されます。 次の例は、単一のグループで複数のフォームコントロールインスタンスを管理する方法を示します。 `ProfileEditor` コンポーネントを生成し、`@angular/forms` パッケージから `FormGroup` と `FormControl` クラスをインポートします。 <docs-code language="shell"> ng generate component ProfileEditor ``` <docs-code header="src/app/profile-editor/profile-editor.component.ts (インポート)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="imports"/> このコンポーネントにフォームグループを追加するには、次の手順を実行します。 1. `FormGroup` インスタンスを作成します。 1. `FormGroup` モデルとビューを関連付けます。 1. フォームデータを保存します。 <docs-workflow> <docs-step title="FormGroup インスタンスの作成"> コンポーネントクラスに `profileForm` という名前のプロパティを作成し、プロパティを新しいフォームグループインスタンスに設定します。フォームグループを初期化するには、コンストラクターに、名前付きキーのオブジェクトを、そのコントロールにマップして渡します。 プロファイルフォームの場合、`firstName` と `lastName` という名前の2つのフォームコントロールインスタンスを追加します <docs-code header="src/app/profile-editor/profile-editor.component.ts (フォームグループ)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="formgroup"/> 個々のフォームコントロールは、グループ内に収集されました。`FormGroup` インスタンスは、グループの各コントロールの値から縮小されたオブジェクトとしてモデル値を提供します。フォームグループインスタンスには、フォームコントロールインスタンスと同じプロパティ（`value` や `untouched` など）とメソッド（`setValue()` など）があります。 </docs-step> <docs-step title="FormGroup モデルとビューの関連付け"> フォームグループは、その各コントロールのステータスと変更を追跡するため、コントロールのいずれかが変更されると、親コントロールも新しいステータスまたは値の変更を発行します。グループのモデルは、そのメンバーから維持されます。モデルを定義したら、テンプレートを更新して、ビューにモデルを反映する必要があります。 <docs-code header="src/app/profile-editor/profile-editor.component.html (テンプレートフォームグループ)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" visibleRegion="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="src/app/profile-editor/profile-editor.component.html (submit イベント)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="ng-submit"/> `ProfileEditor` コンポーネントの `onSubmit()` メソッドは、`profileForm` の現在の値をキャプチャします。`EventEmitter` を使用してフォームをカプセル化し、コンポーネント外部にフォーム値を提供します。次の例では、`console.warn` を使用して、ブラウザコンソールにメッセージをログ出力します。 <docs-code header="src/app/profile-editor/profile-editor.component.ts (submit メソッド)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="on-submit"/> `submit` イベントは、組み込みのDOMイベントを使用して `form` タグによって発行されます。`submit` タイプのボタンをクリックすることで、イベントをトリガーします。これにより、ユーザーは **Enter** キーを押して、完了したフォームを送信できます。 `button` 要素を使用して、フォームの最下部にボタンを追加して、フォーム送信をトリガーします。 <docs-code header="src/app/profile-editor/profile-editor.component.html (submit ボタン)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="submit-button"/> 前述のスニペットのボタンにも、`disabled` バインディングが付けられています。これにより、`profileForm` が無効な場合、ボタンが無効になります。まだ検証していないため、ボタンは常に有効になっています。基本的なフォーム検証については、[フォーム入力の検証](#validating-form-input) セクションを参照してください。 </docs-step> <docs-step title="コンポーネントを表示"> フォームを含む `ProfileEditor` コンポーネントを表示するには、コンポーネントテンプレートに追加します。 <docs-code header="src/app/app.component.html (プロファイルエディター)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" visibleRegion="app-profile-editor"/> `ProfileEditor` を使用して、フォームグループインスタンス内の `firstName` と `lastName` コントロールのフォームコントロールインスタンスを管理できます。 ### ネストされたフォームグループの作成 {#creating-nested-form-groups} フォームグループは、個々のフォームコントロールインスタンスと、他のフォームグループインスタンスの両方を受け入れることができます。 これにより、複雑なフォームモデルの構成を、維持しやすく、論理的にグループ化できます。 複雑なフォームを構築する場合、情報のさまざまな領域を、より小さなセクションで管理する方が簡単です。 ネストされたフォームグループインスタンスを使用すると、大きなフォームグループを、より小さく、管理しやすいグループに分割できます。 より複雑なフォームを作成するには、次の手順を実行します。 1. ネストされたグループを作成します。 1. テンプレートでネストされたフォームをグループ化します。 情報のいくつかのタイプは、自然と同一のグループに分類されます。 名前と住所は、そのようなネストされたグループの典型的な例であり、次の例で使用されます。 <docs-workflow> <docs-step title="ネストされたグループの作成"> `profileForm` にネストされたグループを作成するには、フォームグループインスタンスにネストされた `address` 要素を追加します。 <docs-code header="src/app/profile-editor/profile-editor.component.ts (ネストされたフォームグループ)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="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="src/app/profile-editor/profile-editor.component.html (テンプレートネストされたフォームグループ)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" visibleRegion="formgroupname"/> `ProfileEditor` フォームは、1つのグループとして表示されますが、モデルはさらに分解されて、論理的なグループ化領域を表します。 `value` プロパティと `JsonPipe` を使用して、コンポーネントテンプレートにフォームグループインスタンスの値を表示します。 </docs-step> </docs-workflow> ### データモデルの一部を更新する 複数のコントロールを含むフォームグループインスタンスの値を更新する場合は、モデルの一部だけを更新する場合があります。 このセクションでは、フォームコントロールデータモデルの特定の部分を更新する方法について説明します。 モデル値を更新するには、次の2つの方法があります。 | メソッド | 詳細 | |:--- |:--- | | `setValue()` | 個別のコントロールに新しい値を設定します。`setValue()` メソッドは、フォームグループの構造に厳密に従い、コントロールの値全体を置き換えます。 | | `patchValue()` | フォームモデルで変更されたオブジェクトに定義されているプロパティを置き換えます。 | `setValue()` メソッドの厳密なチェックは、複雑なフォームのネストエラーを検出するのに役立ちますが、`patchValue()` は、これらのエラーでサイレントに失敗します。 `ProfileEditorComponent` では、次の例を使用して、ユーザーの氏名と住所を更新する `updateProfile` メソッドを使用します。 <docs-code header="src/app/profile-editor/profile-editor.component.ts (patch value)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" visibleRegion="patch-value"/> テンプレートにボタンを追加して、オンデマンドでユーザープロファイルを更新することで、更新をシミュレートします。 <docs-code header="src/app/profile-editor/profile-editor.component.html (update value)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" visibleRegion="patch-value"/> ユーザーがボタンをクリックすると、`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="src/app/profile-editor/profile-editor.component.ts (インポート)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="form-builder-imports"/> </docs-step> <docs-step title="FormBuilder サービスの注入"> `FormBuilder` サービスは、リアクティブフォームモジュールで提供される、注入可能なプロバイダーです。`inject()`関数を使ってこの依存関係を注入します。 <docs-code header="src/app/profile-editor/profile-editor.component.ts (property init)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="inject-form-builder"/> </docs-step> <docs-step title="フォームコントロールの生成"> `FormBuilder` サービスには、`control()`、`group()`、`array()` の3つのメソッドがあります。これらは、フォームコントロール、フォームグループ、フォーム配列を含む、コンポーネントクラスでインスタンスを生成するためのファクトリメソッドです。`group` メソッドを使用して、`profileForm` コントロールを作成します。 <docs-code header="src/app/profile-editor/profile-editor.component.ts (フォームビルダー)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="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="src/app/profile-editor/profile-editor.component.ts (インポート)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="validator-imports"/> </docs-step> <docs-step title="フィールドを必須にする"> `ProfileEditor` コンポーネントで、`firstName` コントロールの配列の2番目の項目として、`Validators.required` 静的メソッドを追加します。 <docs-code header="src/app/profile-editor/profile-editor.component.ts (必須入力の検証)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="required-validator"/> </docs-step> <docs-step title="フォームステータスの表示"> フォームコントロールに必須フィールドを追加すると、その初期ステータスは無効になります。この無効なステータスは、親フォームグループ要素に伝達され、そのステータスが無効になります。フォームグループインスタンスの現在のステータスには、`status` プロパティを介してアクセスできます。 `profileForm` の現在のステータスを補間を使用して表示します。 <docs-code header="src/app/profile-editor/profile-editor.component.html (ステータスの表示)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="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="src/app/profile-editor/profile-editor.component.ts (インポート)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" visibleRegion="form-array-imports"/> </docs-step> <docs-step title="`FormArray` コントロールの定義"> `FormArray` を、任意の数のコントロール（0から多数）で初期化できます。これらは、配列で定義します。`profileForm` のフォームグループインスタンスに `aliases` プロパティを追加して、フォーム配列を定義します。 `FormBuilder.array()` メソッドを使用して配列を定義し、`FormBuilder.control()` メソッドを使用して配列を初期コントロールで設定します。 <docs-code header="src/app/profile-editor/profile-editor.component.ts (aliases フォーム配列)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="aliases"/> フォームグループインスタンスのエイリアスコントロールは、動的にコントロールを追加するまで、単一のコントロールで設定されます。 </docs-step> <docs-step title="`FormArray` コントロールにアクセス"> `profileForm.get()` メソッドを繰り返し使用して各インスタンスを取得するのではなく、ゲッターは、フォーム配列インスタンスのエイリアスにアクセスできます。フォーム配列インスタンスは、配列内の未定義数のコントロールを表します。ゲッターを介してコントロールにアクセスするのは便利で、このアプローチは、追加のコントロールに対して簡単に繰り返すことができます。 <br /> ゲッター構文を使用して、`aliases` クラスプロパティを作成し、親フォームグループからエイリアスのフォーム配列コントロールを取得します。 <docs-code header="src/app/profile-editor/profile-editor.component.ts (aliases ゲッター)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="aliases-getter"/> 返されるコントロールは `AbstractControl` 型であるため、フォーム配列インスタンスのメソッド構文にアクセスするには、明示的な型を指定する必要があります。フォーム配列にエイリアスコントロールを動的に挿入するメソッドを定義します。`FormArray.push()` メソッドは、コントロールを配列の新しい項目として挿入します。 <docs-code header="src/app/profile-editor/profile-editor.component.ts (エイリアスの追加)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" visibleRegion="add-alias"/> テンプレートでは、各コントロールが個別の入力フィールドとして表示されます。 </docs-step> <docs-step title="テンプレートにフォーム配列を表示"> フォームモデルからエイリアスを添付するには、テンプレートに追加する必要があります。`FormGroupNameDirective` によって提供される `formGroupName` 入力と同様に、`formArrayName` は、フォーム配列インスタンスからの通信を、`FormArrayNameDirective` を使用してテンプレートにバインドします。 次のテンプレートHTMLを、`formGroupName` 要素を閉じる `<div>` の後に追加します。 <docs-code header="src/app/profile-editor/profile-editor.component.html (aliases フォーム配列テンプレート)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" visibleRegion="formarrayname"/> `@for` ブロックは、エイリアスのフォーム配列インスタンスによって提供される各フォームコントロールインスタンスを反復処理します。フォーム配列要素は名前がないため、インデックスを `i` 変数に割り当て、`formControlName` 入力に渡して、各コントロールをバインドします。 新しいエイリアスインスタンスが追加されるたびに、新しいフォーム配列インスタンスに、インデックスに基づいてコントロールが提供されます。これにより、ルートコントロールのステータスと値を計算する際に、各個別のコントロールを追跡できます。 </docs-step> <docs-step title="エイリアスの追加"> 最初は、フォームには `Alias` フィールドが1つ含まれています。別のフィールドを追加するには、**エイリアスの追加** ボタンをクリックします。また、テンプレートの下部にある `Form Value` によって表示されるフォームモデルに報告されるエイリアスの配列も検証できます。各エイリアスについて、フォームコントロールインスタンスではなく、追加のフィールドを持つ別のフォームグループインスタンスを構成できます。各項目のコントロールを定義するプロセスは同じです。 </docs-step> </docs-workflow> ## リアクティブフォームAPIの概要 次の表は、リアクティブフォームコントロールの作成と管理に使用されるベースクラスとサービスをリストしています。 構文の詳細については、[フォームパッケージ](api#forms "API リファレンス") のAPIリファレンスドキュメントを参照してください。 ### クラス | クラス | 詳細 | |:--- |:--- | | `AbstractControl` | コンクリートフォームコントロールクラス `FormControl`、`FormGroup`、`FormArray` の抽象ベースクラスです。共通の動作とプロパティを提供します。 | | `FormControl` | 個別のフォームコントロールの値と有効性ステータスを管理します。`<input>` や `<select>` などのHTMLフォームコントロールに対応します。 | | `FormGroup` | `AbstractControl` インスタンスのグループの値と有効性状態を管理します。グループのプロパティには、その子コントロールが含まれます。コンポーネントの最上位フォームは `FormGroup` です。 | | `FormArray` | 数値でインデックス付けされた `AbstractControl` インスタンスの配列の値と有効性状態を管理します。 | | `FormBuilder` | コントロールインスタンスを作成するためのファクトリメソッドを提供する、注入可能なサービスです。 | | `FormRecord` | 各々が同じ値タイプを持つ `FormControl` インスタンスのコレクションの値と有効性状態を追跡します。 | ### ディレクティブ | ディレクティブ | 詳細 | |:--- |:--- | | `FormControlDirective` | スタンドアロンの `FormControl` インスタンスをフォームコントロール要素に同期します。 | | `FormControlName` | 既存の `FormGroup` インスタンスの `FormControl` を、名前でフォームコントロール要素に同期します。 | | `FormGroupDirective` | 既存の `FormGroup` インスタンスをDOM要素に同期します。 | | `FormGroupName` | ネストされた `FormGroup` インスタンスをDOM要素に同期します。 | | `FormArrayName` | ネストされた `FormArray` インスタンスをDOM要素に同期します。 | ## 型付きフォーム 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')); ``` この `FormArray` は、内部コントロール型 `FormControl<string|null>` を持つことになります。 配列内に複数の異なる要素型を含めたい場合は、`UntypedFormArray` を使用する必要があります。なぜなら、TypeScriptはどの要素型がどの位置に発生するかを推測できないからです。 ## `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}), }); login.removeControl('password'); ``` このフォームでは、型を明示的に指定しているため、`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/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**ボタンを無効にする - 送信後、ページ上の異なるコンテンツに、完了したフォームを交換する ## フォームの構築 <!-- TODO: プレビューへのリンク --> <!-- ``` --> 1. 提供されたサンプルアプリケーションは、フォームに反映されるデータモデルを定義する`Actor`クラスを作成します。 <docs-code header="src/app/actor.ts" language="typescript" path="adev/src/content/examples/forms/src/app/actor.ts"/> 1. フォームのレイアウトと詳細は、`ActorFormComponent`クラスで定義されます。 <docs-code header="src/app/actor-form/actor-form.component.ts (v1)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" visibleRegion="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" visibleRegion="Marilyn"/> このデモでは、`model`と`skills`のダミーデータを使用しています。 実際のアプリでは、データサービスを注入して実際のデータを取得して保存するか、これらのプロパティを入力と出力として公開します。 1. The component enables the Forms feature by importing the `FormsModule` module. <docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" visibleRegion="imports"/> 1. フォームは、ルートコンポーネントのテンプレートで定義されたアプリケーションレイアウトに表示されます。 <docs-code header="src/app/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="src/styles.css" path="adev/src/content/examples/forms/src/styles.1.css"/> 1. フォームでは、アクターのスキルを、`ActorFormComponent`で内部的に維持されている事前定義された`skills`リストから選択する必要があります。 The Angular `@for` loop iterates over the data values to populate the `<select>` element. <docs-code header="src/app/actor-form/actor-form.component.html (skills)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="skills"/> アプリケーションを今すぐ実行すると、選択コントロールにスキルのリストが表示されます。 入力要素は、まだデータ値やイベントにバインドされていないため、空欄であり、動作しません。 ## 入力コントロールをデータプロパティにバインドする 次のステップは、入力コントロールを対応する`Actor`プロパティに双方向データバインディングでバインドすることです。これにより、ユーザー入力がデータモデルを更新し、データのプログラムによる変更がディスプレイを更新します。 `FormsModule`で宣言された`ngModel`ディレクティブを使用すると、テンプレート駆動型フォームのテンプレート内のコントロールを、データモデルのプロパティにバインドできます。 双方向データバインディングの構文`[(ngModel)]="..."`を使用してディレクティブを含めると、Angularはコントロールの値とユーザー操作を追跡し、ビューとモデルを同期させることができます。 1. テンプレートファイル`actor-form.component.html`を編集します。 1. **名前**ラベルの隣の`<input>`タグを探します。 1. `ngModel`ディレクティブを追加し、双方向データバインディング構文`[(ngModel)]="..."`を使用します。 <docs-code header="src/app/actor-form/actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="ngModelName-1"/> HELPFUL: この例では、各入力タグの後に一時的な診断用補間`{{model.name}}`が追加され、対応するプロパティの現在のデータ値が表示されます。コメントは、双方向データバインディングの動作を観察し終わったら、診断用行を削除するよう思い出させてくれます。 ### フォーム全体のステータスにアクセスする コンポーネントで`FormsModule`をインポートすると、Angularはテンプレートの`<form>`タグに[NgForm](api/forms/NgForm)ディレクティブを自動的に作成してアタッチします（`NgForm`のセレクターは`<form>`要素と一致する`form`だからです）。 `NgForm`とフォーム全体のステータスにアクセスするには、[テンプレート参照変数](guide/templates/reference-variables)を宣言します。 1. テンプレートファイル`actor-form.component.html`を編集します。 1. テンプレート参照変数`#actorForm`を付けて`<form>`タグを更新し、次の値を設定します。 <docs-code header="src/app/actor-form/actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="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="src/app/actor-form/actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="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が適用するクラス名を説明しています。 | 状態 | クラス（真の場合） | クラス（偽の場合） | | :------------------------------- | :------------ | :------------- | | コントロールが訪問された。 | `ng-touched` | `ng-untouched` | | コントロールの値が変更された。 | `ng-dirty` | `ng-pristine` | | コントロールの値が有効。 | `ng-valid` | `ng-invalid` | Angularは、`form`要素に`ng-submitted`クラスを適用しますが、 `form`要素内のコントロールには適用しません。 これらのCSSクラスを使用して、コントロールの状態に基づいてコントロールのスタイルを定義します。 ### コントロールの状態を観察する フレームワークによるクラスの追加と削除を確認するには、ブラウザの開発者ツールを開き、アクターの名前を表す`<input>`要素を調べます。 1. ブラウザの開発者ツールを使用して、**Name**入力ボックスに対応する`<input>`要素を探します。 要素には、"form-control"に加えて、複数のCSSクラスがあることがわかります。 1. 最初に表示すると、クラスは、値が有効であり、初期化またはリセット以降値が変更されていないこと、初期化またはリセット以降コントロールが訪問されていないことを示しています。 <docs-code language="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="src/assets/forms.css" language="css" path="adev/src/content/examples/forms/src/assets/forms.css"/> 1. `index.html`ファイルで、新しいスタイルシートを含めるように`<head>`タグを更新します。 <docs-code header="src/index.html (styles)" path="adev/src/content/examples/forms/src/index.html" visibleRegion="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="src/app/actor-form/actor-form.component.html (hidden-error-msg)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="hidden-error-msg"/> <docs-step title="名前への条件付きエラーメッセージを追加"> 次の例のように、`name`入力ボックスに条件付きエラーメッセージを追加します。 <docs-code header="src/app/actor-form/actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="name-with-error-msg"/> </docs-step> </docs-workflow> この例では、コントロールが有効あるいは_原始状態_のいずれかの場合にメッセージを非表示にします。 原始状態とは、ユーザーがこのフォームに表示されてから値を変更していないことを意味します。 `pristine`状態を無視すると、値が有効な場合にのみメッセージを非表示にします。 新しい空白のアクターか無効なアクターがこのコンポーネントに表示されると、何も操作する前にエラーメッセージがすぐに表示されます。 メッセージは、ユーザーが無効な変更を加えた場合にのみ表示されるようにしたいかもしれません。 コントロールが`pristine`状態の間にメッセージを非表示にすると、その目的を達成できます。 次のステップで新しいアクターをフォームに追加すると、この選択肢の重要性についてわかります。 ## 新しいアクターを追加する この演習では、モデルデータに追加することで、ネイティブHTMLボタンのクリックイベントに対応する方法を示します。 フォームユーザーが新しいアクターを追加できるようにするには、クリックイベントに対応する**New Actor**ボタンを追加します。 1. テンプレートで、フォームの下部に"New Actor"`<button>`要素を配置します。 1. コンポーネントファイルで、アクターデータモデルにアクター作成メソッドを追加します。 <docs-code header="src/app/actor-form/actor-form.component.ts (New Actor method)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" visibleRegion="new-actor"/> 1. ボタンのクリックイベントを、アクター作成メソッド`newActor()`にバインドします。 <docs-code header="src/app/actor-form/actor-form.component.html (New Actor button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="new-actor-button-no-reset"/> 1. アプリケーションを再度実行し、**New Actor**ボタンをクリックします。 フォームがクリアされ、入力ボックスの左側の_必須_バーが赤くなり、`name`と`skill`プロパティが無効であることを示しています。 エラーメッセージは非表示になっていることに注意してください。 これは、フォームが原始状態であるためです。まだ何も変更していません。 1. 名前を入力し、**New Actor**を再度クリックします。 入力ボックスはもはや原始状態ではないため、`名前は必須です`というエラーメッセージが表示されます。 フォームは、**New Actor**をクリックする前に名前を入力したことを覚えています。 1. フォームコントロールの原始状態を復元するには、`newActor()`メソッドを呼び出した後に、フォームの`reset()`メソッドを呼び出してすべてのフラグを強制的にクリアします。 <docs-code header="src/app/actor-form/actor-form.component.html (Reset the form)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="new-actor-button-form-reset"/> これで、**New Actor**をクリックすると、フォームとそのコントロールフラグの両方がリセットされます。 ## `ngSubmit`でフォームを送信する ユーザーは、フォームに記入したら送信できる必要があります。 フォームの下部にある**Submit**ボタンは、それ自体では何も実行しませんが、`type="submit"`であるため、フォームの送信イベントをトリガーします。 このイベントに対応するには、次の手順を実行します。 <docs-workflow> <docs-step title="ngOnSubmitを監視する"> フォームの[`ngSubmit`](api/forms/NgForm#properties)イベントプロパティを、アクターフォームコンポーネントの`onSubmit()`メソッドにバインドします。 <docs-code header="src/app/actor-form/actor-form.component.html (ngSubmit)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="ngSubmit"/> </docs-step> <docs-step title="disabledプロパティをバインドする"> テンプレート参照変数`#actorForm`を使用して、**Submit**ボタンを含むフォームにアクセスし、イベントバインディングを作成します。 フォームの全体的な有効性を示すプロパティを、**Submit**ボタンの`disabled`プロパティにバインドします。 <docs-code header="src/app/actor-form/actor-form.component.html (submit-button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="submit-button"/> </docs-step> <docs-step title="アプリケーションを実行する"> ボタンが有効になっていることに注意してください。まだ何も役に立つことはしていません。 </docs-step> <docs-step title="名前の値を削除する"> これは"必須"ルールに違反するため、エラーメッセージが表示されます。また、**Submit**ボタンが無効になることにも注意してください。 ボタンの有効状態をフォームの有効性に明示的にワイヤリングする必要はありませんでした。 テンプレート参照変数を拡張されたフォーム要素に定義してから、ボタンコントロールでその変数を参照すると、`FormsModule`がこれを自動的に行いました。 </docs-step> </docs-workflow> ### フォーム送信に対応する フォーム送信への応答を表示するには、データ入力領域を非表示にし、代わりに別のものを表示できます。 <docs-workflow> <docs-step title="フォームをラップする"> フォーム全体を`<div>`でラップし、その`hidden`プロパティを`ActorFormComponent.submitted`プロパティにバインドします。 <docs-code header="src/app/actor-form/actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="edit-div"/> メインフォームは、`submitted`プロパティがフォームを送信するまでは偽であるため、最初から表示されます。これは、`ActorFormComponent`からの次のフラグメントで示されています。 <docs-code header="src/app/actor-form/actor-form.component.ts (submitted)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" visibleRegion="submitted"/> **Submit**ボタンをクリックすると、`submitted`フラグが真になり、フォームが消えます。 </docs-step> <docs-step title="送信された状態を追加する"> フォームが送信された状態の間に別のものを表示するには、新しい`<div>`ラッパーの下に次のHTMLを追加します。 <docs-code header="src/app/actor-form/actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" visibleRegion="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からのユーザー入力を検証し、リアクティブフォームとテンプレート駆動フォームの両方で、役立つ検証メッセージを表示する方法について説明します。 ## テンプレート駆動フォームでの入力検証 テンプレート駆動フォームに検証を追加するには、[ネイティブHTMLフォーム検証](https://developer.mozilla.org/docs/Web/Guide/HTML/HTML5/Constraint_validation)の場合と同じように、検証属性を追加します。 Angularは、これらの属性をフレームワーク内のバリデーター関数と一致させるためにディレクティブを使用します。 フォームコントロールの値が変更されるたびに、Angularは検証し、検証エラーのリスト（`INVALID`ステータスをもたらす）または`null`（`VALID`ステータスをもたらす）を生成します。 その後、`ngModel`をローカルテンプレート変数にエクスポートすることで、コントロールの状態を調べることができます。 次の例では、`NgModel`を`name`という変数にエクスポートします。 ``` 例で示されている次の機能に注目してください。 * `<input>`要素には、HTML検証属性(`required`と`minlength`)があります。 また、カスタムバリデーターディレクティブ`forbiddenName`もあります。 詳細については、[カスタムバリデーター](#defining-custom-validators)セクションを参照してください。 * `#name="ngModel"`は、`NgModel`を`name`というローカル変数にエクスポートします。 `NgModel`は、基になる`FormControl`インスタンスの多くのプロパティをミラーリングしているため、テンプレート内でこれを使用して、`valid`や`dirty`などのコントロールの状態を確認できます。 コントロールプロパティの完全なリストについては、[AbstractControl](api/forms/AbstractControl) APIリファレンスを参照してください。 * The outermost `@if` reveals a set of nested messages but only if the `name` is invalid and the control is either `dirty` or `touched`. * Each nested `@if` can present a custom message for one of the possible validation errors. `required`、`minlength`、`forbiddenName`のメッセージがあります。 HELPFUL: ユーザーがフォームを編集する機会がある前に、バリデーターがエラーを表示しないようにするには、コントロールの`dirty`または`touched`状態のいずれかをチェックする必要があります。 * ユーザーが監視対象のフィールドの値を変更すると、コントロールは「dirty」としてマークされます。 * ユーザーがフォームコントロール要素からフォーカスを外すと、コントロールは「touched」としてマークされます。 ## リアクティブフォームでの入力検証 リアクティブフォームでは、真実の源はコンポーネントクラスです。 テンプレートで属性を通じてバリデーターを追加する代わりに、コンポーネントクラスのフォームコントロールモデルに直接バリデーター関数を追加します。 その後、Angularは、コントロールの値が変更されるたびにこれらの関数を呼び出します。 ### バリデーター関数 バリデーター関数は、同期または非同期にすることができます。 | バリデーターの種類 | 詳細 | |:--- |:--- | | 同期バリデーター | コントロールインスタンスを受け取り、検証エラーのセットまたは`null`をすぐに返す同期関数。`FormControl`をインスタンス化する際に、第2引数として渡します。 | | 非同期バリデーター | コントロールインスタンスを受け取り、後で検証エラーのセットまたは`null`を発行するPromiseまたはObservableを返す非同期関数。`FormControl`をインスタンス化する際に、第3引数として渡します。 | パフォーマンス上の理由から、Angularは、すべての同期バリデーターが合格した場合にのみ非同期バリデーターを実行します。 各バリデーターは、エラーが設定される前に完了する必要があります。 ### 組み込みのバリデーター関数 [独自のバリデーター関数](#defining-custom-validators)を作成することも、Angularの組み込みのバリデーターのいくつかを使用することもできます。 `required`や`minlength`など、テンプレート駆動フォームで属性として使用できるものと同じ組み込みバリデーターはすべて、`Validators`クラスから関数として使用できます。 組み込みのバリデーターの完全なリストについては、[Validators](api/forms/Validators) APIリファレンスを参照してください。 アクターフォームをリアクティブフォームに更新するには、いくつかの組み込みバリデーターを使用します。 今回は、関数形式で、次の例のようにします。 <docs-code header="reactive/actor-form-reactive.component.ts (validator functions)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" visibleRegion="form-group"/> この例では、`name`コントロールは、2つの組み込みバリデーター(`Validators.required`と`Validators.minLength(4)`)と、1つのカスタムバリデーター`forbiddenNameValidator`を設定しています。 これらすべてのバリデーターは同期であるため、第2引数として渡されます。 関数を配列として渡すことで、複数のバリデーターをサポートできることに注意してください。 この例では、いくつかのゲッターメソッドも追加されています。 リアクティブフォームでは、常に親グループの`get`メソッドを通じて任意のフォームコントロールにアクセスできますが、テンプレートの省略形としてゲッターを定義することが便利な場合があります。 `name`入力のテンプレートをもう一度見ると、テンプレート駆動の例とかなり似ています。 <docs-code header="reactive/actor-form-reactive.component.html (name with error msg)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" visibleRegion="name-with-error-msg"/> このフォームは、テンプレート駆動バージョンとは、ディレクティブをエクスポートしなくなった点が異なります。代わりに、コンポーネントクラスで定義された`name`ゲッターを使用します。 `required`属性は、テンプレートにまだ存在することに注意してください。検証には必要ありませんが、アクセシビリティの目的で保持する必要があります。 ## カスタムバリデーターの定義 {#defining-custom-validators} 組み込みのバリデーターは、アプリケーションのユースケースに常に一致するわけではありません。そのため、カスタムバリデーターを作成する必要がある場合があります。 前の例の`forbiddenNameValidator`関数を考えてみてください。 その関数の定義は次のようになります。 <docs-code header="shared/forbidden-name.directive.ts (forbiddenNameValidator)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" visibleRegion="custom-validator"/> 関数は、*特定の*禁止されている名前を検出するための正規表現を受け取り、バリデーター関数を返すファクトリです。 このサンプルでは、禁止されている名前は「bob」なので、バリデーターは「bob」を含むアクター名をすべて拒否します。 他の場所では、「alice」や、構成された正規表現に一致する名前を拒否することもできます。 `forbiddenNameValidator`ファクトリは、構成されたバリデーター関数を返します。 その関数はAngularコントロールオブジェクトを受け取り、コントロール値が有効な場合は`null`を返し、無効な場合は検証エラーオブジェクトを返します。 検証エラーオブジェクトには通常、検証キーの名前である`'forbiddenName'`というプロパティと、エラーメッセージに挿入できる任意の値の辞書である`{name}`という値を持つプロパティがあります。 カスタム非同期バリデーターは同期バリデーターに似ていますが、代わりに後で`null`または検証エラーオブジェクトを発行するPromiseまたはオブザーバブルを返す必要があります。 オブザーバブルの場合、オブザーバブルは完了する必要があります。その時点で、フォームは最後の発行された値を検証に使用します。 ### カスタムバリデーターをリアクティブフォームに追加する リアクティブフォームでは、`FormControl`に直接関数を渡すことで、カスタムバリデーターを追加します。 <docs-code header="reactive/actor-form-reactive.component.ts (validator functions)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" visibleRegion="custom-validator"/> ### カスタムバリデーターをテンプレート駆動フォームに追加する テンプレート駆動フォームでは、テンプレートにディレクティブを追加します。ディレクティブは、バリデーター関数をラップします。 たとえば、対応する`ForbiddenValidatorDirective`は、`forbiddenNameValidator`のラッパーとして機能します。 Angularは、ディレクティブが`NG_VALIDATORS`プロバイダーに自身を登録するため、ディレクティブの検証プロセスにおける役割を認識します。次の例に示すように。 `NG_VALIDATORS`は、拡張可能なバリデーターのコレクションを持つ、定義済みのプロバイダーです。 <docs-code header="shared/forbidden-name.directive.ts (providers)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" visibleRegion="directive-providers"/> その後、ディレクティブクラスは`Validator`インターフェースを実装するため、Angularフォームと簡単に統合できます。 以下は、ディレクティブ全体の概要です。 <docs-code header="shared/forbidden-name.directive.ts (directive)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" visibleRegion="directive"/> `ForbiddenValidatorDirective`の準備ができたら、セレクター`appForbiddenName`を入力要素に追加して、アクティブ化できます。 たとえば、次のとおりです。 <docs-code header="template/actor-form-template.component.html (forbidden-name-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="name-input"/> HELPFUL: カスタム検証ディレクティブが`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"/> ## クロスフィールド検証 クロスフィールドバリデーターは、フォーム内の異なるフィールドの値を比較し、組み合わせで受け入れるか拒否する[カスタムバリデーター](#defining-custom-validators "カスタムバリデーターについて読む")です。 たとえば、互いに非互換なオプションを提供するフォームがある場合、ユーザーはAまたはBを選択できますが、両方は選択できません。 フィールドの値によっては、他の値に依存する場合もあります。ユーザーは、Aを選択した場合にのみBを選択できます。 次のクロス検証の例は、次の方法を示しています。 * 2つの兄弟コントロールの値に基づいて、リアクティブまたはテンプレートベースのフォーム入力を検証する * ユーザーがフォームとやり取りし、検証に失敗した場合に、説明的なエラーメッセージを表示する これらの例では、クロス検証を使用して、アクターがアクターフォームに記入することで、役割で同じ名前を再利用しないようにしています。 バリデーターは、アクター名と役割が一致しないことを確認することで、これを実現します。 ### クロス検証をリアクティブフォームに追加する フォームは、次の構造になっています。 <docs-code language="javascript"> const actorForm = new FormGroup({ 'name': new FormControl(), 'role': new FormControl(), 'skill': new FormControl() }); ``` `name`と`role`は兄弟コントロールであることに注意してください。 1つのカスタムバリデーターで両方のコントロールを評価するには、共通の祖先コントロールである`FormGroup`で検証する必要があります。 子コントロールを取得するために`FormGroup`をクエリして、値を比較します。 `FormGroup`にバリデーターを追加するには、作成時に第2引数として新しいバリデーターを渡します。 ```javascript const actorForm = new FormGroup({ 'name': new FormControl(), 'role': new FormControl(), 'skill': new FormControl() }, { validators: unambiguousRoleValidator }); ``` バリデーターのコードは次のとおりです。 ``` `unambiguousRoleValidator`バリデーターは、`ValidatorFn`インターフェースを実装しています。 これはAngularコントロールオブジェクトを引数として受け取り、フォームが有効な場合は`null`を返し、無効な場合は`ValidationErrors`を返します。 バリデーターは、`FormGroup`の[get](api/forms/AbstractControl#get)メソッドを呼び出して子コントロールを取得し、`name`コントロールと`role`コントロールの値を比較します。 値が一致しない場合、役割は曖昧ではなく、両方が有効で、バリデーターは`null`を返します。 値が一致する場合、アクターの役割は曖昧で、バリデーターはエラーオブジェクトを返すことでフォームを無効にする必要があります。 より良いユーザーエクスペリエンスを提供するために、フォームが無効な場合、テンプレートに適切なエラーメッセージが表示されます。 <docs-code header="reactive/actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" visibleRegion="cross-validation-error-message"/> この`@if`は、`FormGroup`に`unambiguousRoleValidator`バリデーターが返したクロス検証エラーがある場合に、エラーを表示しますが、ユーザーが[フォームとやり取りを完了](#control-status-css-classes)した場合のみです。 ### クロス検証をテンプレート駆動フォームに追加する テンプレート駆動フォームの場合、バリデーター関数をラップするディレクティブを作成する必要があります。 次の例に示すように、[`NG_VALIDATORS`トークン](/api/forms/NG_VALIDATORS)を使用して、そのディレクティブをバリデーターとして提供します。 <docs-code header="shared/unambiguous-role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/unambiguous-role.directive.ts" visibleRegion="cross-validation-directive"/> 新しいディレクティブをHTMLテンプレートに追加する必要があります。 バリデーターはフォームの最上位レベルで登録する必要があるため、次のテンプレートは`form`タグにディレクティブを配置しています。 <docs-code header="template/actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="cross-validation-register-validator"/> より良いユーザーエクスペリエンスを提供するために、フォームが無効な場合、適切なエラーメッセージが表示されます。 <docs-code header="template/actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="cross-validation-error-message"/> これは、テンプレート駆動フォームとリアクティブフォームの両方で同じです。 ## 非同期バリデーターの作成 非同期バリデーターは、`AsyncValidatorFn`と`AsyncValidator`インターフェースを実装します。 これらは、同期バリデーターと非常に似ており、次の点が異なります。 * `validate()`関数はPromiseまたはオブザーバブルを返す必要があります。 * 返されるオブザーバブルは有限である必要があります。つまり、ある時点で完了する必要があります。 無限のオブザーバブルを有限のオブザーバブルに変換するには、オブザーバブルを`first`、`last`、`take`、`takeUntil`などのフィルタリング演算子でパイプします。 非同期検証は、同期検証の後に実行され、同期検証が成功した場合にのみ実行されます。 このチェックにより、フォームは、基本的な検証方法がすでに無効な入力を検出している場合、潜在的にコストのかかる非同期検証プロセス（HTTPリクエストなど）を回避できます。 非同期検証が開始されると、フォームコントロールは`pending`状態になります。 コントロールの`pending`プロパティを調べ、それを利用して、進行中の検証操作に関する視覚的なフィードバックを提供します。 一般的なUIパターンは、非同期検証の実行中にスピナーを表示することです。 次の例は、テンプレート駆動フォームでこれを実現する方法を示しています。 <docs-code language="html"> <input [(ngModel)]="name" #model="ngModel" appSomeAsyncValidator> @if(model.pending) { <app-spinner /> } ``` ### カスタム非同期バリデーターの実装 次の例では、非同期バリデーターは、アクターがすでに割り当てられている役割にキャストされないようにします。 新しいアクターは常にオーディションを受けており、古いアクターは引退しているため、利用可能な役割のリストを事前に取得はできません。 潜在的な役割のエントリを検証するために、バリデーターは、現在キャストされているすべてのアクターの中央データベースを照会する非同期操作を開始する必要があります。 次のコードは、`AsyncValidator`インターフェースを実装するバリデータークラス`UniqueRoleValidator`を作成します。 ``` The `actorsService` property is initialized with an instance of the `ActorsService` token, which defines the following interface. <docs-code language="typescript"> 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`に設定され、フォームの有効性が更新されます。 ### 非同期バリデーターをリアクティブフォームに追加する リアクティブフォームで非同期バリデーターを使用するには、最初にバリデーターをコンポーネントクラスのプロパティに注入します。 ``` 次に、バリデーター関数を`FormControl`に直接渡して、適用します。 次の例では、`UnambiguousRoleValidator`の`validate`関数が、`roleControl`に適用されています。この関数をコントロールの`asyncValidators`オプションに渡し、`ActorFormReactiveComponent`に注入された`UnambiguousRoleValidator`のインスタンスにバインドしています。 `asyncValidators`の値は、単一の非同期バリデーター関数、または関数の配列にすることができます。 `FormControl`オプションの詳細については、[AbstractControlOptions](api/forms/AbstractControlOptions) APIリファレンスを参照してください。 <docs-code path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" visibleRegion="async-validator-usage"/> ### 非同期バリデーターをテンプレート駆動フォームに追加する テンプレート駆動フォームで非同期バリデーターを使用するには、新しいディレクティブを作成し、そのディレクティブに`NG_ASYNC_VALIDATORS`プロバイダーを登録します。 次の例では、ディレクティブは、実際の検証ロジックを含む`UniqueRoleValidator`クラスを注入し、検証を実行する必要があるときにAngularによってトリガーされる`validate`関数でそれを呼び出します。 <docs-code path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" visibleRegion="async-validator-directive"/> その後、同期バリデーターと同様に、ディレクティブのセレクターを入力に追加して、アクティブ化します。 <docs-code header="template/actor-form-template.component.html (unique-unambiguous-role-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" visibleRegion="role-input"/> ### 非同期バリデーターのパフォーマンスの最適化 デフォルトでは、すべてのバリデーターは、フォームの値が変更されるたびに実行されます。 同期バリデーターの場合、これは通常、アプリケーションのパフォーマンスに目立った影響を与えません。 ただし、非同期バリデーターは通常、コントロールを検証するために何らかのHTTPリクエストを実行します。 キーストロークごとにHTTPリクエストをディスパッチすると、バックエンドAPIに負担がかかる可能性があり、可能な限り回避する必要があります。 `updateOn`プロパティを`change`（デフォルト）から`submit`または`blur`に変更することで、フォームの有効性の更新を遅らせることができます。 テンプレート駆動フォームでは、テンプレートでプロパティを設定します。 <docs-code language="html"> <input [(ngModel)]="name" [ngModelOptions]="{updateOn: 'blur'}"> ``` リアクティブフォームでは、`FormControl`インスタンスでプロパティを設定します。 ```typescript new FormControl('', {updateOn: 'blur'}); ``` ## ネイティブHTMLフォーム検証との相互作用 デフォルトでは、Angularは囲んでいる`<form>`に`novalidate`属性を追加することで[ネイティブHTMLフォーム検証](https://developer.mozilla.org/docs/Web/Guide/HTML/Constraint_validation)を無効にし、これらの属性をフレームワーク内のバリデーター関数と一致させるためにディレクティブを使用します。 ネイティブ検証を**組み合わせて**Angularベースの検証を使用したい場合は、`ngNativeValidate`ディレクティブを使用して、ネイティブ検証を再び有効にできます。 詳細については、[APIドキュメント](api/forms/NgForm#native-dom-validation-ui)を参照してください。 # 動的フォームの作成 アンケートなどの多くのフォームは、フォーマットと意図において非常に類似している場合があります。 このようなフォームの異なるバージョンをより速く簡単に生成できるように、ビジネスオブジェクトモデルを記述するメタデータに基づいて、_動的フォームテンプレート_を作成できます。 その後、テンプレートを使用して、データモデルの変更に応じて、新しいフォームを自動的に生成します。 このテクニックは、ビジネスや規制要件の急速な変化に対応するために、コンテンツを頻繁に変更する必要があるフォームの種類を持つ場合に特に役立ちます。 一般的なユースケースはアンケートです。 さまざまなコンテキストでユーザーからの入力を受け取る必要がある場合があります。 ユーザーが見ているフォームのフォーマットとスタイルは一定に保つ必要がありますが、実際に尋ねる必要がある質問はコンテキストによって異なります。 このチュートリアルでは、基本的なアンケートを表示する動的フォームを作成します。 雇用を求めるヒーローのためのオンラインアプリケーションを構築します。 エージェンシーは常にアプリケーションプロセスをいじっていますが、 動的フォームを使用することでアプリケーションコードを変更せずに新しいフォームをオンザフライで作成できます。 このチュートリアルでは、次の手順について説明します。 1. プロジェクトでリアクティブフォームを有効にする。 1. フォームコントロールを表すデータモデルを確立する。 1. サンプルデータでモデルを埋める。 1. フォームコントロールを動的に作成するコンポーネントを開発する。 作成するフォームでは、入力検証とスタイリングを使用してユーザー体験を向上させます。 すべてのユーザー入力が有効な場合にのみ有効になる送信ボタンがあり、無効な入力を色分けとエラーメッセージでフラグ付けします。 この基本バージョンは、より多くの種類の質問、より洗練されたレンダリング、優れたユーザー体験をサポートするように進化させることができます。 ## プロジェクトでリアクティブフォームを有効にする 動的フォームはリアクティブフォームに基づいています。 アプリケーションにリアクティブフォームディレクティブへのアクセス権を与えるには、必要なコンポーネントに `@angular/forms` ライブラリから `ReactiveFormsModule` をインポートします。 ## フォームオブジェクトモデルを作成する 動的フォームには、フォーム機能に必要なすべてのシナリオを記述できるオブジェクトモデルが必要です。 例のヒーローアプリケーションフォームは、一連の質問です。つまり、フォーム内の各コントロールは質問をし、回答を受け入れる必要があります。 このタイプのフォームのデータモデルは、質問を表す必要があります。 例には、`DynamicFormQuestionComponent` が含まれており、質問をモデルの基本オブジェクトとして定義しています。 次の `QuestionBase` は、フォーム内の質問とその回答を表すことができる一連のコントロールのベースクラスです。 <docs-code header="src/app/question-base.ts" path="adev/src/content/examples/dynamic-form/src/app/question-base.ts"/> ### コントロールクラスを定義する このベースから、例では、異なるコントロールタイプを表す `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"/> ### フォームグループを構成する 動的フォームは、サービスを使用して、質問モデルのメタデータに基づいて、入力コントロールのグループ化されたセットを作成します。 次の `QuestionControlService` は、質問モデルからメタデータを使用する `FormGroup` インスタンスのセットを収集します。 デフォルト値と検証ルールを指定できます。 <docs-code header="src/app/question-control.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question-control.service.ts"/> ## 動的フォームコンテンツを構成する 動的フォーム自体は、後で追加するコンテナーコンポーネントで表されます。 各質問は、フォームコンポーネントのテンプレートで、`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` で定義されています。 ### データを供給する 個々のフォームを構築するために、特定の質問セットを供給するサービスも必要です。 この演習では、ハードコードされたサンプルデータからこの質問の配列を供給する `QuestionService` を作成します。 実際のアプリケーションでは、サービスはバックエンドシステムからデータを取得する可能性があります。 ただし、重要な点は、ヒーローの求人質問を `QuestionService` から返されるオブジェクトを通じて完全に制御できることです。 要件が変更された場合にアンケートを維持するには、`questions` 配列からオブジェクトを追加、更新、削除するだけです。 `QuestionService` は、`input()` questionsにバインドされた配列の形式で、質問セットを供給します。 <docs-code header="src/app/question.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question.service.ts"/> ## 動的フォームテンプレートを作成する `DynamicFormComponent` コンポーネントは、テンプレートで `<app-dynamic-form>` を使用して表されるフォームのエントリポイントであり、メインコンテナーです。 `DynamicFormComponent` コンポーネントは、各質問を、`DynamicFormQuestionComponent` と一致する `<app-question>` 要素にバインドすることによって、質問のリストを表示します。 ### フォームを表示する 動的フォームのインスタンスを表示するには、`AppComponent` シェルテンプレートは、`QuestionService` から返された `questions` 配列を、フォームコンテナーコンポーネント `<app-dynamic-form>` に渡します。 <docs-code header="app.component.ts" path="adev/src/content/examples/dynamic-form/src/app/app.component.ts"/> このモデルとデータの分離により、_質問_ オブジェクトモデルと互換性がある限り、あらゆるタイプのアンケートにコンポーネントを再利用できます。 ### 有効なデータを確保する フォームテンプレートは、特定の質問についてハードコードされた仮定を一切行わずに、メタデータの動的データバインドを使用してフォームをレンダリングします。 コントロールメタデータと検証基準の両方を動的に追加します。 有効な入力を確保するために、フォームが有効な状態になるまで、_保存_ ボタンは無効になっています。 フォームが有効になったら、_保存_ をクリックすると、アプリケーションは現在のフォーム値をJSONとしてレンダリングします。 次の図は、最終的なフォームを示しています。 <img alt="Dynamic-Form" src="assets/images/guide/dynamic-form/dynamic-form.png"> ## 次のステップ Angular Router (`@angular/router`) is the official library for managing navigation in Angular applications and a core part of the framework. It is included by default in all projects created by Angular CLI. ## Installation Angular Router is included by default in all Angular projects setup with the Angular CLI `ng new` command. ### Prerequisite - Angular CLI ### Add to an existing project If your project does not have routing, you can install it manually with the following command: ```bash ng add @angular/router ``` The Angular CLI will then install all the necessary dependencies. ## Why is routing necessary in a SPA? When you navigate to a URL in your web browser, the browser normally makes a network request to a web server and displays the returned HTML page. When you navigate to a different URL, such as clicking a link, the browser makes another network request and replaces the entire page with a new one. A single-page application (SPA) differs in that the browser only makes a request to a web server for the first page, the `index.html`. After that, a client-side router takes over, controlling which content displays based on the URL. When a user navigates to a different URL, the router updates the page's content in place without triggering a full-page reload. ## How Angular manages routing Routing in Angular is comprised of three primary parts: 1. **Routes** define which component displays when a user visits a specific URL. 2. **Outlets** are placeholders in your templates that dynamically load and render components based on the active route. 3. **Links** provide a way for users to navigate between different routes in your application without triggering a full page reload. In addition, the Angular Routing library offers additional functionality such as: - Nested routes - Programmatic navigation - Route params, queries and wildcards - Activated route information with `ActivatedRoute` - View transition effects - Navigation guards ## Next steps Learn about how you can [define routes using Angular router](/guide/routing/define-routes). # ルートを定義する ルートは、Angularアプリケーション内のナビゲーションのための基本的な構成要素として機能します。 ## ルートとは {#what-are-routes} Angularでは、**ルート**は特定のURLパスまたはパターンに対してどのコンポーネントをレンダリングするか、およびユーザーがそのURLにナビゲートしたときに何が起こるかに関する追加の構成オプションを定義するオブジェクトです。 次にルートの基本的な例を示します。 ```typescript import { AdminPage } from './app-admin/app-admin.component'; const adminPage = { path: 'admin', component: AdminPage } ``` このルートの場合、ユーザーが`/admin`パスにアクセスすると、アプリケーションは`AdminPage`コンポーネントを表示します。 ### アプリケーションでルートを管理する {#managing-routes-in-your-application} ほとんどのプロジェクトでは、ファイル名に`routes`を含む別のファイルでルートを定義します。 ルートのコレクションは次のようになります。 ```typescript 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ルーターをアプリケーションに追加できます。 ```typescript 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に基づいてユーザープロファイルコンポーネントを表示します。 ```typescript 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) - アンダーバー(\_) - ハイフン(-) 複数のパラメーターを持つパスを定義できます。 ```typescript 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} 特定のパスのすべてのルートをキャッチする必要がある場合、解決策は二重アスタリスク(`**`)で定義されるワイルドカードルートです。 一般的な例は、ページが見つかりませんコンポーネントの定義です。 ```typescript 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`と照合すると、それ以上ルートの確認を停止することを意味します。結果として、常に、より具体的なルートを、より具体的でないルートの前に配置してください。 次の例は、最も具体的なものから最も具体的でないものへと定義されたルートを示しています。 ```typescript 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. `**`には到達しません ## ルートコンポーネントの読み込み戦略 {#loading-route-component-strategies} Angularルーティングでコンポーネントがどのように、いつ読み込まれるかを理解することは、応答性の高いWebアプリケーションを構築するために不可欠です。Angularは、コンポーネントの読み込み動作を制御するための2つの主要な戦略を提供します。 1. **即時読み込み (Eagerly loaded)**: すぐに読み込まれるコンポーネント 2. **遅延読み込み (Lazily loaded)**: 必要になったときにのみ読み込まれるコンポーネント それぞれのアプローチは、異なるシナリオに対して明確な利点を提供します。 ### 即時読み込みされるコンポーネント {#eagerly-loaded-components} `component`プロパティでルートを定義すると、参照されるコンポーネントは、ルート構成と同じJavaScriptバンドルの一部として即時読み込みされます。 ```typescript 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} `loadComponent`プロパティを使用すると、そのルートがアクティブになる時点でのみ、ルートのJavaScriptを遅延読み込みできます。 ```typescript import { Routes } from "@angular/router"; export const routes: Routes = [ // HomePageとLoginPageコンポーネントは、 // 対応するルートがアクティブになった時点で遅延読み込みされます。 { path: 'login', loadComponent: () => import('./components/auth/login-page').then(m => m.LoginPage) }, { path: '', loadComponent: () => import('./components/home/home-page').then(m => m.HomePage) } ] ``` `loadComponent`プロパティは、Angularコンポーネントに解決されるPromiseを返すローダー関数を受け入れます。ほとんどの場合、この関数は標準の[JavaScript動的インポートAPI](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)を使用します。ただし、任意の非同期ローダー関数も使用できます。 遅延読み込みルートは、初期バンドルからJavaScriptの大部分を削除することで、Angularアプリケーションの読み込み速度を大幅に向上させることができます。これらのコード部分は、ユーザーが対応するルートにアクセスしたときにのみルーターが要求する個別のJavaScript「チャンク」にコンパイルされます。 ### 即時ルートと遅延ルートのどちらを使用すべきか {#should-i-use-an-eager-or-a-lazy-route} ルートが即時読み込みか遅延読み込みかを決定する際には、多くの要素を考慮する必要があります。 一般的に、プライマリランディングページには即時読み込みが推奨され、他のページは遅延読み込みされます。 Note: 遅延ルートは、ユーザーが要求する初期データの量を減らすという先行的なパフォーマンス上の利点がありますが、望ましくない可能性のある将来のデータ要求を追加します。これは、複数のレベルでのネストされた遅延読み込みを扱う場合に特に当てはまり、パフォーマンスに大きな影響を与える可能性があります。 ## リダイレクト {#redirects} コンポーネントをレンダリングする代わりに、別のルートにリダイレクトするルートを定義できます。 ```typescript 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)を自動的に更新します。アクセシブルな体験を作成するためにこれらのタイトルが必要となるため、アプリケーションに適切なページタイトルを常に定義してください。 ```typescript import { Routes } from '@angular/router'; import { HomeComponent } from './home/home.component'; import { AboutComponent } from './about/about.component'; import { ProductsComponent } from './products/products.component'; const routes: Routes = [ { path: '', component: HomeComponent, title: 'Home Page' }, { path: 'about', component: AboutComponent, title: 'About Us' }, { path: 'products', component: ProductsComponent, title: 'Our Products' } ]; ``` ## 依存性の注入のためのルートレベルプロバイダー {#route-level-providers-for-dependency-injection} 各ルートには、[依存性の注入](/guide/di)を介してそのルートのコンテンツに依存性を提供する`providers`プロパティがあります。 これが役立つ一般的なシナリオには、ユーザーが管理者であるかどうかに基づいて異なるサービスを持つアプリケーションが含まれます。 ```typescript 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`プロパティを介して任意の静的データをルートに関連付けることで、ルート固有のメタデータ（例: 分析トラッキング、権限など）を一元化できます。 ```typescript 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に基づいてサブビューが変化する、より複雑なナビゲーションルートを管理するための一般的な手法です。 <img alt="ネストされたルートを示す図" src="assets/images/guide/router/nested-routing-diagram.svg"> `children`プロパティを使用して、任意のルート定義に子ルートを追加できます。 ```typescript const routes: Routes = [ { path: 'product/:id', component: ProductComponent, children: [ { path: 'info', component: ProductInfoComponent }, { path: 'reviews', component: ProductReviewsComponent } ] } ] ``` 上記の例では、ユーザーがURLに基づいて製品情報またはレビューのどちらを表示するかを変更できる製品ページのルートを定義しています。 `children`プロパティは`Route`オブジェクトの配列を受け入れます。 子ルートを表示するには、親コンポーネント（上記の例では`ProductComponent`）に独自の`<router-outlet>`を含めます。 ```html <!-- ProductComponent --> <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 /> <!-- Angularはここにルートコンテンツを挿入します --> <app-footer /> ``` ```typescript 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 {} ``` この例では、アプリケーションに次のルートが定義されている場合: ```typescript 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 <!-- ユーザーが/adminにアクセスしたときにページにレンダリングされるコンテンツ --> <app-header>...</app-header> <router-outlet></router-outlet> <app-admin-page>...</app-admin-page> <app-footer>...</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`配列に配置することです。 ```typescript 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`プロパティにアウトレットの名前を一致させます。 ```typescript { 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)を参照してください。 ## 次のステップ {#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 <!-- Absolute URL --> <a href="https://www.angular.dev/essentials">Angular Essentials Guide</a> <!-- Relative URL --> <a href="/essentials">Angular Essentials Guide</a> ``` この例では、最初の例は、基本概念ページに対してプロトコル（つまり`https://`）とルートドメイン（つまり`angular.dev`）が明示的に定義された完全なパスを含んでいます。対照的に、2番目の例は、ユーザーがすでに`/essentials`の正しいルートドメインにいることを前提としています。 一般的に、相対URLは、ルーティング階層内での絶対位置を知る必要がないため、アプリケーション全体で保守しやすいため、推奨されます。 ### 相対URLの仕組み {#how-relative-urls-work} Angularルーティングには、相対URLを定義するための2つの構文があります。文字列と配列です。 ```html <!-- Navigates user to /dashboard --> <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 <!-- Navigates to /settings/notifications --> <a routerLink="notifications">Notifications</a> <a routerLink="/settings/notifications">Notifications</a> <!-- Navigates to /team/:teamId/user/:userId --> <a routerLink="/team/123/user/456">User 456</a> <a [routerLink]="['/team', teamId, 'user', userId]">Current User</a>” ``` ## ルートへのプログラムによるナビゲーション {#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' } }); } } ``` `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やディープリンクのシナリオで役立ちます。 ```typescript // 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'); ``` 履歴内の現在のURLを置き換える必要がある場合、`navigateByUrl`は`replaceUrl`オプションを持つ設定オブジェクトも受け入れます。 ```typescript // 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`は、ルートに関するさまざまな情報を提供できます。一般的なプロパティには次のものがあります。 | プロパティ | 詳細 | | :------------ | :-------------------------------------------------------------------------------------------------------------------------------- | | `url` | ルートパスの`Observable`。ルートパスの各部分が文字列の配列として表現されます。 | | `data` | ルートに提供される`data`オブジェクトを含む`Observable`。また、resolveガードから解決された値も含まれます。 | | `params` | ルートに固有の必須およびオプションのパラメーターを含む`Observable`。 | | `queryParams` | すべてのルートで利用可能なクエリパラメーターを含む`Observable`。 | ルート内でアクセスできるものの完全なリストについては、[`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> <!-- Products list --> </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)を参照してください。 ## 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`](api/router/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'})` ## 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> ``` これらの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` プロバイダーで、両方のスタイルをサポートしています。 | プロバイダー | 詳細 | | :--------------------- | :----------------------------------- | | `PathLocationStrategy` | デフォルトの「HTML5 pushState」スタイル。 | | `HashLocationStrategy` | 「ハッシュURL」スタイル。 | `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*を作成します。 <docs-code language="shell"> ng generate component heroes-list ``` 1. コードエディターで、ファイル`heroes-list.component.html`を見つけて、プレースホルダーの内容を以下のHTMLに置き換えます。 ``` 1. コードエディターで、ファイル`app.component.html`を開き、その内容を以下のHTMLに置き換えます。 <docs-code header="src/app/app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="setup"/> 1. 新しいアプリケーションが期待どおりに動作することを確認するには、`ng serve`コマンドを実行します。 <docs-code language="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. 以下の行を削除します。 ``` 1. `router-outlet`ディレクティブを追加します。 <docs-code header="src/app/app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="router-outlet"/> 1. `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を追加します。 ``` このHTMLはAngularディレクティブである`routerLink`を使用しています。 このディレクティブは、定義したルートをテンプレートファイルに接続します。 1. `app.component.ts`の`AppComponent`のimportsリストに`RouterLink`ディレクティブを追加します。 1. `app.component.css`ファイルを開き、以下のスタイルを追加します。 <docs-code header="src/app/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="src/app/app.component.html" path="adev/src/content/examples/router-tutorial/src/app/app.component.html" visibleRegion="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`を作成します。 <docs-code language="shell"> ng generate component page-not-found ``` 1. コードエディターで、`page-not-found.component.html`ファイルを開き、その内容を以下のHTMLに置き換えます。 <docs-code header="src/app/page-not-found/page-not-found.component.html" path="adev/src/content/examples/router-tutorial/src/app/page-not-found/page-not-found.component.html"/> 1. `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に置き換えます。 ``` 1. コードエディタで`app.component.html`ファイルを見つけ、プレースホルダーコンテンツを次のHTMLに置き換えます。 <docs-code header="src/app/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="src/app/app.routes.ts" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.routes.ts" visibleRegion="matcher"/> このカスタムマッチャーは、次のタスクを実行する関数です。 * マッチャーは、配列にセグメントが1つしかないことを確認します * マッチャーは正規表現を使用して、ユーザー名の形式が一致することを確認します * 一致があれば、関数は完全なURLを返し、`username`ルートパラメーターをパスのサブストリングとして定義します * 一致しなければ、関数はnullを返し、ルーターはURLと一致する他のルートを探し続けます HELPFUL: カスタムURLマッチャーは、他のルート定義と同じように動作します。他のルートと同じように、子ルートまたは遅延読み込みルートを定義します。 ## ルートパラメーターの読み取り カスタムマッチャーが設定されたので、`profile`コンポーネントでルートパラメーターをバインドできます。 コードエディタで`profile.component.ts`ファイルを開き、`username`パラメーターと一致する`Input`を作成します。 以前、`provideRouter`で`withComponentInputBinding`機能を追加しました。 これにより、`Router`はルートコンポーネントに直接情報をバインドできます。 ```ts @Input() username!: string; ``` ## カスタムURLマッチャーをテストする コードが設定されたので、カスタムURLマッチャーをテストできます。 1. ターミナルウィンドウから`ng serve`コマンドを実行します。 <docs-code language="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} 各レンダリングモードには異なる利点と欠点があります。アプリケーションの特定のニーズに基づいてレンダリングモードを選択できます。 ##### クライアントサイドレンダリング {#client-side-rendering} クライアントサイドレンダリングは、常にWebブラウザで実行されることを前提としたコードを記述できるため、最もシンプルな開発モデルです。これにより、ブラウザで実行されることを前提とした幅広いクライアントサイドライブラリを使用できます。 クライアントサイドレンダリングは、ユーザーがレンダリングされたコンテンツを見る前にページのJavaScriptをダウンロード、解析、実行する必要があるため、一般的に他のレンダリングモードよりもパフォーマンスが劣ります。ページがレンダリング中にサーバーからさらにデータを取得する場合、ユーザーは完全なコンテンツを表示する前にそれらの追加リクエストを待つ必要があります。 ページが検索クローラーによってインデックス付けされる場合、検索クローラーはページのインデックス付け時に実行するJavaScriptの量に制限があるため、クライアントサイドレンダリングは検索エンジン最適化 (SEO) に悪影響を与える可能性があります。 クライアントサイドレンダリングの場合、サーバーは静的なJavaScriptアセットを配信する以外に、ページをレンダリングするための作業をする必要がありません。サーバーコストが懸念される場合は、この要素を考慮してもよいでしょう。 Service Workerによるインストール可能でオフラインのユーザー体験をサポートするアプリケーションは、サーバーと通信することなくクライアントサイドレンダリングに依存できます。 ##### サーバーサイドレンダリング {#server-side-rendering} サーバーサイドレンダリングは、クライアントサイドレンダリングよりも高速なページロードを提供します。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` を使用する場合、`inject` は同期的に使用する必要があることに注意してください。非同期コールバック内や `await` ステートメントの後に呼び出すことはできません。詳細については、[`runInInjectionContext`](api/core/runInInjectionContext) を参照してください。 #### フォールバック戦略 {#fallback-strategies} [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') モードを使用する場合、プリレンダリングされていないパスへのリクエストを処理するためのフォールバック戦略を指定できます。 利用可能なフォールバック戦略は次のとおりです。 - **Server:** サーバーサイドレンダリングにフォールバックします。これは、`fallback` プロパティが指定されていない場合の**デフォルト**の動作です。 - **Client:** クライアントサイドレンダリングにフォールバックします。 - **None:** フォールバックなし。Angularは、プリレンダリングされていないパスへのリクエストを処理しません。 ```typescript // app.routes.server.ts import { RenderMode, PrerenderFallback, ServerRoute } from '@angular/ssr'; export const serverRoutes: ServerRoute[] = [ { path: 'post/:id', renderMode: RenderMode.Prerender, fallback: PrerenderFallback.Client, // プリレンダリングされていない場合は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`](api/core/afterEveryRender) および [`afterNextRender`](api/core/afterNextRender) ライフサイクルフックによって強制できます。これらはブラウザでのみ実行され、サーバーではスキップされます。 ```typescript import { Component, ViewChild, afterNextRender } from '@angular/core'; @Component({ selector: 'my-cmp', template: `<span #content>{{ ... }}</span>`, }) export class MyComponent { @ViewChild('content') contentRef: ElementRef; constructor() { afterNextRender(() => { // これはサーバーではなくブラウザでのみ実行されるため、`scrollHeight` のチェックは安全です。 console.log('content height: ' + this.contentRef.nativeElement.scrollHeight); }); } } ``` ## 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`](api/common/http/HttpClient) は、サーバーで実行されているときに送信ネットワークリクエストをキャッシュします。この情報はシリアル化され、サーバーから送信される初期HTMLの一部としてブラウザに転送されます。ブラウザでは、`HttpClient` はキャッシュにデータがあるかどうかを確認し、ある場合は、初期アプリケーションレンダリング中に新しいHTTPリクエストを行う代わりにそれを再利用します。`HttpClient` は、ブラウザで実行中にアプリケーションが[安定](api/core/ApplicationRef#isStable)すると、キャッシュの使用を停止します。 デフォルトでは、`HttpClient` は `Authorization` または `Proxy-Authorization` ヘッダーを含まないすべての `HEAD` および `GET` リクエストをキャッシュします。ハイドレーションを提供する際に [`withHttpTransferCacheOptions`](api/platform-browser/withHttpTransferCacheOptions) を使用して、これらの設定をオーバーライドできます。 ```typescript bootstrapApplication(AppComponent, { providers: [ provideClientHydration(withHttpTransferCacheOptions({ includePostRequests: true })) ] }); ``` ## サーバーの設定 {#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) を参照してください。 ```typescript // server.ts import { AngularNodeAppEngine, createNodeRequestHandler, writeResponseToNodeResponse } from '@angular/ssr/node'; import express from 'express'; const app = express(); const angularApp = new AngularNodeAppEngine(); app.use('*', (req, res, next) => { angularApp .handle(req) .then(response => { if (response) { writeResponseToNodeResponse(response, res); } else { next(); // 次のミドルウェアに制御を渡す } }) .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) を参照してください。 ```typescript // 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) エラーに遭遇する可能性があります。アプリケーションがすぐにハイドレーションされない場合は、アプリケーションの安定性に影響を与えているものを見直し、これらの遅延を引き起こさないようにリファクタリングしてください。 ## 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アプリケーションをテストすると、アプリケーションが期待どおりに動作していることを確認できます。 ## テストの設定 Angular CLIは、[Jasmineテストフレームワーク](https://jasmine.github.io)を使用してAngularアプリケーションをテストするために必要なものをすべてダウンロードしてインストールします。 CLIで作成したプロジェクトは、すぐにテストできます。 [`ng test`](cli/test) CLIコマンドを実行するだけです。 ```shell ng test ``` `ng test`コマンドはアプリケーションを*監視モード*でビルドし、 [Karmaテストランナー](https://karma-runner.github.io)を起動します。 コンソールの出力は次のようになります。 ```shell 02 11 2022 09:08:28.605:INFO [karma-server]: Karma v6.4.1 server started at http://localhost:9876/ 02 11 2022 09:08:28.607:INFO [launcher]: Launching browsers Chrome with concurrency unlimited 02 11 2022 09:08:28.620:INFO [launcher]: Starting browser Chrome 02 11 2022 09:08:31.312:INFO [Chrome]: Connected on socket -LaEYvD2R7MdcS0-AAAB with id 31534482 Chrome: Executed 3 of 3 SUCCESS (0.193 secs / 0.172 secs) TOTAL: 3 SUCCESS ``` ログの最後の行は、Karmaが3つのテストを実行し、すべてが合格したことを示しています。 テスト出力は、[Karma Jasmine HTMLレポーター](https://github.com/dfederm/karma-jasmine-html-reporter)を使用してブラウザに表示されます。 <img alt="Jasmine HTML Reporter in the browser" src="assets/images/guide/testing/initial-jasmine-html-reporter.png"> テスト行をクリックしてそのテストのみを再実行するか、説明をクリックして選択したテストグループ（「テストスイート」）のテストを再実行します。 一方、`ng test`コマンドは変更を監視しています。 これが実際にどのように機能するかを確認するには、`app.component.ts`を少し変更して保存します。 テストが再び実行され、ブラウザが更新され、新しいテスト結果が表示されます。 ## 設定 Angular CLIは、JasmineとKarmaの設定を処理します。Angular CLIは、`angular.json`ファイルで指定されたオプションに基づいて、メモリ内に完全な設定を構築します。 Karmaをカスタマイズする場合は、次のコマンドを実行して`karma.conf.js`を作成できます。 ```shell ng generate config karma ``` HELPFUL: [Karma設定ガイド](http://karma-runner.github.io/6.4/config/configuration-file.html)でKarmaの設定について詳しく知ることができます。 ### その他のテストフレームワーク Angularアプリケーションは、他のテストライブラリとテストランナーでもユニットテストできます。 各ライブラリとランナーには、それぞれ独自のインストール手順、構成、構文があります。 ### テストファイル名と場所 Angular CLIは、`src/app`フォルダ内に`AppComponent`のテストファイルを`app.component.spec.ts`という名前で生成しました。 IMPORTANT: テストファイル拡張子は**`.spec.ts`でなければなりません**。これにより、ツールはファイルをテストを含むファイル（*spec*ファイルとも呼ばれる）として識別できます。 `app.component.ts`と`app.component.spec.ts`ファイルは、同じフォルダ内の兄弟です。 ルートファイル名（`app.component`）は、両方のファイルで同じです。 あらゆる種類のテストファイルに対して、これらの2つの規則を独自のプロジェクトで採用してください。 #### テストするファイルの横にspecファイルを配置する ユニットテストのspecファイルを、 テストするアプリケーションソースコードファイルと同じフォルダに入れることをお勧めします。 * このようなテストは簡単に検索できます。 * アプリケーションの一部にテストがないかどうかをひと目で確認できます。 * 近くのテストは、一部がコンテキストでどのように機能するかを示すことができます。 * ソースを移動すると（不可避ですが）、テストも移動することを思い出します。 * ソースファイルを名前変更すると（不可避ですが）、テストファイルの名前も変更することを思い出します。 #### specファイルをテストフォルダに配置する アプリケーションの統合specは、 フォルダとモジュールにまたがる複数の部分の相互作用をテストできます。 それらは、特にどの部分にも属していないため、 特定のファイルの横に自然な場所がありません。 多くの場合、それらに対して`tests`ディレクトリに適切なフォルダを作成する方が良いでしょう。 もちろん、テストヘルパーをテストするspecは、 対応するヘルパーファイルの隣の`test`フォルダに入ります。 ## 継続的インテグレーションでのテスト プロジェクトをバグなしに保つ最良の方法の1つは、テストスイートを使用することですが、常にテストを実行することを忘れてしまうかもしれません。 継続的インテグレーション（CI）サーバーを使用すると、プロジェクトリポジトリを設定して、すべてのコミットとプルリクエストでテストを実行できます。 Angular CLIアプリケーションを継続的インテグレーション（CI）でテストするには、次のコマンドを実行します。 ```shell ng test --no-watch --no-progress --browsers=ChromeHeadless ``` ## テストに関する追加情報 アプリケーションのテストを設定したら、次のテストガイドが役立つ場合があります。 | | 詳細 | |:--- |:--- | | [コードカバレッジ](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のテスト機能。 | # テストされているコードの量を確認する Angular CLIは、単体テストを実行し、コードカバレッジレポートを作成できます。 コードカバレッジレポートは、単体テストで適切にテストされていないコードベースの箇所を示します。 カバレッジレポートを生成するには、プロジェクトのルートで次のコマンドを実行します。 ```shell ng test --no-watch --code-coverage ``` テストが完了すると、コマンドによってプロジェクトに新しい `/coverage` ディレクトリが作成されます。 `index.html` ファイルを開くと、ソースコードとコードカバレッジ値を含むレポートが表示されます。 テストを実行するたびにコードカバレッジレポートを作成する場合は、Angular CLI構成ファイル `angular.json` に次のオプションを設定します。 ```json "test": { "options": { "codeCoverage": true } } ``` ## コードカバレッジの強制 コードカバレッジのパーセンテージは、コードのどの程度がテストされているかを推定できます。 チームが単体テストを行う最小限の量を決定した場合、Angular CLIでその最小限を強制できます。 たとえば、コードベースのコードカバレッジを最低80% にしたいとします。 これを有効にするには、[Karma](https://karma-runner.github.io) テストプラットフォーム構成ファイル `karma.conf.js` を開き、`coverageReporter:` キーに `check` プロパティを追加します。 ```javascript coverageReporter: { dir: require('path').join(__dirname, './coverage/<project-name>'), subdir: '.', reporters: [ { type: 'html' }, { type: 'text-summary' } ], check: { global: { statements: 80, branches: 80, functions: 80, lines: 80 } } } ``` HELPFUL: [テストガイド](guide/testing#configuration) で、Karma構成の作成と微調整について詳しく説明しています。 `check` プロパティによって、プロジェクトで単体テストを実行すると、最低80% のコードカバレッジが強制されます。 [karma カバレッジドキュメント](https://github.com/karma-runner/karma-coverage/blob/master/docs/configuration.md) で、カバレッジ構成オプションの詳細を確認してください。 # サービスのテスト サービスが意図通りに動作していることを確認するには、サービス専用のテストを作成できます。 サービスは、多くの場合、ユニットテストを実行するのに最もスムーズなファイルです。 以下は、Angularテストユーティリティの助けを借りずに記述された `ValueService` の同期および非同期のユニットテストです。 ``` ## 依存関係のあるサービス サービスは、Angular がコンストラクターに注入する他のサービスに依存することがよくあります。 多くの場合、サービスのコンストラクターを呼び出す際に、これらの依存関係を手動で作成して *注入* できます。 `MasterService` は、単純な例です。 <docs-code header="app/demo/demo.ts" path="adev/src/content/examples/testing/src/app/demo/demo.ts" visibleRegion="MasterService"/> `MasterService` は、唯一のメソッドである `getValue` を、注入された `ValueService` に委譲します。 テストを行うには、いくつかの方法があります。 <docs-code header="app/demo/demo.spec.ts" path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="MasterService"/> 最初のテストでは、`new` で `ValueService` を作成し、`MasterService` コンストラクターに渡します。 ただし、実際のサービスを注入することは、ほとんどの場合、うまく機能しません。ほとんどの依存サービスは作成と制御が難しいからです。 代わりに、依存関係をモック化し、ダミー値を使用するか、関連するサービスメソッドに [スパイ](https://jasmine.github.io/tutorials/your_first_suite#section-Spies) を作成します。 HELPFUL: スパイは、通常、サービスをモック化する最良の方法なので、スパイを使用することをお勧めします。 これらの標準的なテストテクニックは、サービスを単体でユニットテストするのに適しています。 ただし、ほとんどの場合、Angular の依存関係注入を使用してサービスをアプリケーションクラスに注入します。そのため、その使用パターンを反映したテストを行う必要があります。 Angular のテストユーティリティを使用すると、注入されたサービスがどのように動作するかを簡単に調査できます。 ## `TestBed` を使用したサービスのテスト アプリケーションは、Angular の [依存関係注入 (DI)](guide/di) に依存してサービスを作成します。 サービスが依存サービスを持っている場合、DI はその依存サービスを見つけたり、作成します。 さらに、その依存サービスに独自の依存関係がある場合、DI はそれらも探し出して作成します。 サービスの *消費者* として、あなたはこれらについて心配する必要はありません。 コンストラクター引数の順序や、それらがどのように作成されるかについて心配する必要はありません。 サービスの *テスター* として、少なくともサービス依存関係の最初のレベルについて考える必要はありますが、`TestBed` テストユーティリティを使用してサービスを提供して作成し、コンストラクター引数の順序を処理するときは、Angular DI にサービスの作成を任せることができます。 ## Angular `TestBed` `TestBed` は、Angular のテストユーティリティの中で最も重要なものです。 `TestBed` は、Angular の [@NgModule](guide/ngmodules) をエミュレートする、動的に構築された Angular の *テスト* モジュールを作成します。 `TestBed.configureTestingModule()` メソッドは、[@NgModule](guide/ngmodules) のほとんどのプロパティを持つことができるメタデータオブジェクトを受け取ります。 サービスをテストするには、テストまたはモックするサービスの配列を `providers` メタデータプロパティに設定します。 <docs-code header="app/demo/demo.testbed.spec.ts (beforeEach で ValueService を提供)" path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="value-service-before-each"/> 次に、サービスクラスを引数として `TestBed.inject()` を呼び出して、テスト内でサービスを注入します。 HELPFUL: `TestBed.get()` は、Angular バージョン 9 以降で非推奨になりました。 重大な変更を最小限に抑えるため、Angular は `TestBed.inject()` という新しい関数を導入しました。これは、代わりに使用する必要があります。 <docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="value-service-inject-it"/> または、セットアップの一部としてサービスを注入したい場合は、`beforeEach()` 内で行います。 <docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="value-service-inject-before-each"> ``` 依存関係のあるサービスをテストする場合は、`providers` 配列にモックを提供します。 次の例では、モックはスパイオブジェクトです。 <docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="master-service-before-each"/> テストでは、以前と同じように、そのスパイを使用します。 <docs-code path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="master-service-it"/> ## `beforeEach()` を使用しないテスト このガイドのほとんどのテストスイートでは、`beforeEach()` を呼び出して各 `it()` テストの前提条件を設定し、`TestBed` にクラスの作成とサービスの注入を任せています。 `beforeEach()` を呼び出さない、別のテストの考え方があり、`TestBed` を使用せず、クラスを明示的に作成することを好みます。 このスタイルで `MasterService` のテストの1つを書き直す方法を以下に示します。 最初に、*セットアップ* 関数に、再利用可能な準備コードを `beforeEach()` の代わりに配置します。 <docs-code header="app/demo/demo.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="no-before-each-setup"/> `setup()` 関数は、テストで参照できる可能性のある変数 `masterService` などの変数を、オブジェクトリテラルとして返します。 `describe()` の本文には、*半グローバル* 変数（例：`let masterService: MasterService`）は定義しません。 次に、各テストは、テスト対象の操作や期待の主張を続行する前に、最初の行で `setup()` を呼び出します。 <docs-code path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="no-before-each-test"/> テストで [*デストラクチャリング代入*](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) を使用して、必要なセットアップ変数を抽出したことに注意してください。 <docs-code path="adev/src/content/examples/testing/src/app/demo/demo.spec.ts" visibleRegion="no-before-each-setup-call"/> 多くの開発者は、このアプローチは従来の `beforeEach()` スタイルよりもクリーンで明示的だと感じるでしょう。 このテストガイドでは、従来のスタイルと、デフォルトの [CLI スキーマ](https://github.com/angular/angular-cli) で `beforeEach()` と `TestBed` を使用してテストファイルが生成されますが、独自のプロジェクトで *この代替アプローチ* を採用することは自由です。 ## HTTP サービスのテスト リモートサーバーにHTTP呼び出しするデータサービスは、通常、Angularの [`HttpClient`](guide/http/testing) サービスを注入して委譲し、XHRを呼び出します。 依存関係が注入された `HttpClient` スパイを使用して、データサービスをテストできます。 <docs-code header="app/model/hero.service.spec.ts (スパイを使用したテスト)" path="adev/src/content/examples/testing/src/app/model/hero.service.spec.ts" visibleRegion="test-with-spies"/> IMPORTANT: `HeroService` メソッドは `Observable` を返します。 Observableに *登録* することで、(a) 実行させ、(b) メソッドが成功したか失敗したかをアサートする必要があります。 `subscribe()` メソッドは、成功 (`next`) と失敗 (`error`) のコールバックを受け取ります。 エラーを捕捉するために、*両方の* コールバックを提供してください。 これを怠ると、非同期でキャッチされないObservableエラーが発生し、テストランナーは別のテストによるエラーであると判断する可能性があります。 ## `HttpClientTestingModule` データサービスと `HttpClient` の間の拡張されたやり取りは複雑で、スパイでモック化するのは難しい場合があります。 `HttpClientTestingModule` を使用すると、これらのテストシナリオをより管理しやすくなります。 このガイドに付属する *コードサンプル* では `HttpClientTestingModule` が示されていますが、このページでは、`HttpClientTestingModule` を使用したテストを詳しく説明している [HTTP ガイド](guide/http/testing) を参照します。 # コンポーネントテストの基本 コンポーネントは、Angularアプリケーションの他のすべての部分とは異なり、HTMLテンプレートとTypeScriptクラスを組み合わせたものです。 コンポーネントは、実際にはテンプレートとクラスが *連携* したものです。 コンポーネントを適切にテストするには、意図したとおりに連携して動作することをテストする必要があります。 このようなテストには、Angularと同様にブラウザのDOMにコンポーネントのホスト要素を作成し、そのテンプレートで記述されているように、DOMとのコンポーネントクラスの対話を調査することが必要です。 Angularの `TestBed` は、次のセクションで説明するように、この種類のテストを容易にします。 しかし、多くの場合、*DOM を伴わないコンポーネントクラス単独のテスト* は、コンポーネントの動作の大部分を、より簡単で明らかな方法で検証できます。 ## コンポーネント DOM テスト コンポーネントは、そのクラスだけではありません。 コンポーネントはDOMと他のコンポーネントと対話します。 クラスだけでは、コンポーネントが正しくレンダリングされるか、ユーザーの入力やジェスチャーに応答するか、親コンポーネントと子コンポーネントと統合されるかを判断できません。 * `Lightswitch.clicked()` はユーザーが呼び出せるように何かとバインドされていますか？ * `Lightswitch.message` は表示されますか？ * ユーザーは `DashboardHeroComponent` によって表示されるヒーローを実際に選択できますか？ * ヒーローの名前は期待通り（たとえば、大文字）に表示されますか？ * `WelcomeComponent` のテンプレートによってウェルカムメッセージは表示されますか？ これらの質問は、説明した前の簡単なコンポーネントにとっては問題ないかもしれません。 しかし、多くのコンポーネントは、そのテンプレートで記述されているDOM要素との複雑な対話を持ち、コンポーネントの状態が変わるとHTMLが表示および非表示になります。 これらの質問に答えるには、コンポーネントに関連付けられたDOM要素を作成し、DOMを調べて適切なタイミングでコンポーネントの状態が正しく表示されていることを確認します。そしてユーザーが画面と対話するようにシミュレートして、それらの対話がコンポーネントが期待通りに動作するかどうかを判断する必要があります。 これらの種類のテストを書くには、`TestBed` の追加機能と、他のテストヘルパーを使用します。 ### CLI で生成されたテスト CLIは、新しいコンポーネントの生成を要求するときに、デフォルトで初期テストファイルを自動的に生成します。 たとえば、次のCLIコマンドは `app/banner` フォルダーに `BannerComponent` を生成します（インラインテンプレートとスタイル付き）。 ```shell ng generate component banner --inline-template --inline-style --module app ``` また、コンポーネントの初期テストファイル `banner-external.component.spec.ts` も生成し、次のようになります。 <docs-code header="app/banner/banner-external.component.spec.ts (初期)" path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v1"/> HELPFUL: `compileComponents` は非同期であるため、`@angular/core/testing` からインポートされた [`waitForAsync`](api/core/testing/waitForAsync) ユーティリティ関数を使用します。 詳細については、[waitForAsync](guide/testing/components-scenarios#waitForAsync) セクションを参照してください。 ### セットアップの削減 このファイルの最後の3行だけが実際にコンポーネントをテストしており、Angularがコンポーネントを作成できることをアサートするだけです。 ファイルの残りの部分は、コンポーネントが実質的なものへと進化した場合に必要になる可能性のある、より高度なテストを予期した定型文のセットアップコードです。 これらの高度なテスト機能については、次のセクションで説明します。 今のところ、このテストファイルをより管理しやすいサイズに大幅に縮小できます。 <docs-code header="app/banner/banner-initial.component.spec.ts (最小限)" path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v2"/> この例では、`TestBed.configureTestingModule` に渡されるメタデータオブジェクトは、単にテスト対象のコンポーネントである `BannerComponent` を宣言します。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="configureTestingModule"/> HELPFUL: 他のものを宣言したりインポートする必要はありません。 デフォルトのテストモジュールは、`@angular/platform-browser` の `BrowserModule` などのモジュールで事前に構成されています。 後で `TestBed.configureTestingModule()` を呼び出して、インポート、プロバイダー、その他の宣言を追加して、テストのニーズに合わせて構成します。 オプションの `override` メソッドは、構成の側面をさらに微調整できます。 ### `createComponent()` `TestBed` を構成したら、その `createComponent()` メソッドを呼び出します。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="createComponent"/> `TestBed.createComponent()` は `BannerComponent` のインスタンスを作成し、対応する要素をテストランナーのDOMに追加し、[`ComponentFixture`](#componentfixture) を返します。 IMPORTANT: `createComponent` を呼び出した後に `TestBed` を再構成しないでください。 `createComponent` メソッドは、現在の `TestBed` 定義を凍結し、さらなる構成を締め切ります。 `configureTestingModule()` や `get()`、`override...` メソッドなど、`TestBed` の構成メソッドをさらに呼び出すことはできません。 呼び出そうとすると、`TestBed` はエラーをスローします。 ### `ComponentFixture` [ComponentFixture](api/core/testing/ComponentFixture) は、作成されたコンポーネントとその対応する要素を操作するためのテストハーネスです。 fixtureを介してコンポーネントインスタンスにアクセスし、Jasmineの期待を使用して存在を確認します。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="componentInstance"/> ### `beforeEach()` このコンポーネントが進化するにつれて、さらに多くのテストを追加するでしょう。 各テストのために `TestBed` 構成を複製するのではなく、セットアップをJasmineの `beforeEach()` といくつかのサポート変数にリファクタリングします。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v3"/> 次に、fixture.nativeElementからコンポーネントの要素を取得し、期待されるテキストを探すテストを追加します。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-2"/> ### `nativeElement` `ComponentFixture.nativeElement` の値は `any` 型です。 後で `DebugElement.nativeElement` に遭遇しますが、これも `any` 型です。 Angularは、コンパイル時に `nativeElement` がどのようなHTML要素であるか、あるいはHTML要素であるかどうかすらを知ることができません。 アプリケーションは、サーバーや [Web Worker](https://developer.mozilla.org/docs/Web/API/Web_Workers_API) などの *非ブラウザープラットフォーム* で実行されている可能性があり、その場合、要素のAPIが制限されているか、存在しない可能性があります。 このガイドのテストはブラウザで実行されるように設計されているため、`nativeElement` の値は常に `HTMLElement` またはその派生クラスのいずれかになります。 それが何らかの `HTMLElement` であることを知っているので、標準のHTML `querySelector` を使用して、要素ツリーをさらに深く掘り下げます。 次に、`HTMLElement.querySelector` を呼び出して段落要素を取得し、バナーテキストを探すテストを示します。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-3"/> ### `DebugElement` Angularの *fixture* は、`fixture.nativeElement` を介してコンポーネントの要素を直接提供します。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="nativeElement"/> これは実際には、`fixture.debugElement.nativeElement` として実装された便利なメソッドです。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="debugElement-nativeElement"/> この回りくどい要素へのパスには、正当な理由があります。 `nativeElement` のプロパティは、実行時環境によって異なります。 これらのテストは、DOMがないか、DOMエミュレーションが完全な `HTMLElement` APIをサポートしていない *非ブラウザープラットフォーム* で実行されている可能性があります。 Angularは、*すべてのサポートされているプラットフォーム* で安全に動作するために、`DebugElement` 抽象化に依存しています。 AngularはHTML要素ツリーを作成するのではなく、実行時プラットフォームの *ネイティブ要素* をラップする `DebugElement` ツリーを作成します。 `nativeElement` プロパティは `DebugElement` をラップ解除し、プラットフォーム固有の要素オブジェクトを返します。 このガイドのサンプルテストはブラウザでのみ実行されるように設計されているため、これらのテストの `nativeElement` は常に `HTMLElement` であり、そのおなじみのメソッドとプロパティはテスト内で調べることができます。 次に、`fixture.debugElement.nativeElement` を使用して再実装された前のテストを示します。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-4"/> `DebugElement` には、このガイドの他の場所で説明されているように、テストで役立つ他のメソッドとプロパティがあります。 Angularコアライブラリから `DebugElement` シンボルをインポートします。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="import-debug-element"/> ### `By.css()` このガイドのテストはすべてブラウザで実行されますが、一部のアプリケーションは少なくとも一部の時間を別のプラットフォームで実行することがあります。 たとえば、コンポーネントは、接続の悪いデバイスでのアプリケーションの起動を高速化するための戦略の一部として、最初にサーバーでレンダリングされる可能性があります。 サーバー側レンダラーは、完全なHTML要素APIをサポートしていない可能性があります。 `querySelector` をサポートしていない場合、前のテストは失敗する可能性があります。 `DebugElement` は、すべてのサポートされているプラットフォームで動作するクエリメソッドを提供します。 これらのクエリメソッドは、`DebugElement` ツリー内のノードが選択基準に一致した場合に `true` を返す *述語* 関数を取ります。 実行時プラットフォームのライブラリからインポートされた `By` クラスの助けを借りて *述語* を作成します。 次に、ブラウザプラットフォームの `By` のインポートを示します。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="import-by"/> 次の例は、`DebugElement.query()` とブラウザの `By.css` メソッドを使用して、前のテストを再実装したものです。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner-initial.component.spec.ts" visibleRegion="v4-test-5"/> 注目すべき観察結果をいくつか紹介します。 * `By.css()` 静的メソッドは、[標準の CSS セレクター](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors 'CSS セレクター') を持つ `DebugElement` ノードを選択します。 * クエリは、段落の `DebugElement` を返します。 * その結果をラップ解除して、段落要素を取得する必要があります。 CSSセレクターでフィルタリングし、ブラウザの *ネイティブ要素* のプロパティのみをテストする場合は、`By.css` アプローチはやり過ぎになる可能性があります。 多くの場合、`querySelector()` や `querySelectorAll()` などの標準の `HTMLElement` メソッドを使用してフィルタリングする方が簡単で明確です。 # コンポーネントテストシナリオ このガイドでは、一般的なコンポーネントテストのユースケースについて説明します。 ## コンポーネントバインディング サンプルアプリケーションでは、`BannerComponent`はHTMLテンプレートに静的なタイトルテキストを表示します。 いくつかの変更を加えた後、`BannerComponent`は、次のようにコンポーネントの`title`プロパティにバインドすることで動的なタイトルを表示します。 ``` これは最小限のものですが、コンポーネントが実際に期待どおりに正しいコンテンツを表示していることを確認するためのテストを追加することにします。 ### `<h1>`のクエリ *タイトル*プロパティの補間バインディングを囲む`<h1>`要素の値を検査する一連のテストを作成します。 `beforeEach`を更新して、標準のHTML`querySelector`でその要素を見つけ、`h1`変数に割り当てます。 <docs-code header="app/banner/banner.component.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="setup"/> ### `createComponent()`はデータをバインドしません 最初のテストでは、画面にデフォルトの`title`が表示されることを確認したいと考えています。 直感的には、次のように`<h1>`をすぐに検査するテストを作成するでしょう。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="expect-h1-default-v1"/> *このテストは失敗します*、メッセージは次のとおりです。 <docs-code language="javascript"> expected '' to contain 'Test Tour of Heroes'. ``` バインディングは、Angularが**変更検知**を実行したときに発生します。 本番環境では、Angularがコンポーネントを作成したり、ユーザーがキーストロークを入力したりしたときに、変更検知は自動的に開始されます。 `TestBed.createComponent`はデフォルトで変更検知をトリガーしません。これは、修正されたテストで確認できます。 ``` ### `detectChanges()` `TestBed`に`fixture.detectChanges()`を呼び出してデータバインディングを実行するように指示することができます。 そうすれば初めて、`<h1>`に期待どおりのタイトルが表示されます。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="expect-h1-default"/> 変更検知が遅延されるのは意図的なことであり、便利です。 これにより、テスターはAngularがデータバインディングを開始し、[ライフサイクルフック](guide/components/lifecycle)を呼び出す*前に*、コンポーネントの状態を検査および変更することができます。 次に、`fixture.detectChanges()`を呼び出す*前に*、コンポーネントの`title`プロパティを変更するテストを示します。 <docs-code path="adev/src/content/examples/testing/src/app/banner/banner.component.spec.ts" visibleRegion="after-change"/> ### 自動変更検知 `BannerComponent`のテストでは、頻繁に`detectChanges`を呼び出しています。 多くのテスターは、Angularのテスト環境が本番環境のように自動的に変更検知を実行することを好みます。 これは、`TestBed`を`ComponentFixtureAutoDetect`プロバイダーで設定することで可能です。 まず、テストユーティリティライブラリからインポートします。 <docs-code header="app/banner/banner.component.detect-changes.spec.ts (import)" path="adev/src/content/examples/testing/src/app/banner/banner.component.detect-changes.spec.ts" visibleRegion="import-ComponentFixtureAutoDetect"/> 次に、テストモジュール設定の`providers`配列に追加します。 <docs-code header="app/banner/banner.component.detect-changes.spec.ts (AutoDetect)" path="adev/src/content/examples/testing/src/app/banner/banner.component.detect-changes.spec.ts" visibleRegion="auto-detect"/> HELPFUL: `fixture.autoDetectChanges()`関数を代わりに使用することもできます。 これは、フィクスチャのコンポーネントの状態を更新した後、自動変更検知を有効にする場合のみです。 また、自動変更検知は`provideZonelessChangeDetection`を使用する場合、デフォルトで有効になっており、オフにすることは推奨されません。 次に、自動変更検知がどのように機能するかを示す3つのテストを示します。 <docs-code header="app/banner/banner.component.detect-changes.spec.ts (AutoDetect Tests)" path="adev/src/content/examples/testing/src/app/banner/banner.component.detect-changes.spec.ts" visibleRegion="auto-detect-tests"/> 最初のテストは、自動変更検知の利点を示しています。 2番目と3番目のテストは、重要な制限を明らかにしています。 Angularのテスト環境は、コンポーネントの`title`を変更したテストケース内で更新が行われた場合、変更検知を同期的に実行しません。 テストは、別の変更検知を待つために`await fixture.whenStable`を呼び出す必要があります。 HELPFUL: Angularは、信号ではない値への直接的な更新については知りません。 変更検知がスケジュールされるようにするための最も簡単な方法は、テンプレートで読み取られる値に信号を使用することです。 ### `dispatchEvent()`を使用して入力値を変更する ユーザー入力をシミュレートするには、入力要素を見つけ、その`value`プロパティを設定します。 しかし、重要な中間ステップがあります。 Angularは、入力要素の`value`プロパティを設定したことを知りません。 `dispatchEvent()`を呼び出して要素の`input`イベントを発生させるまで、そのプロパティを読み込みません。 次の例は、正しいシーケンスを示しています。 <docs-code header="app/hero/hero-detail.component.spec.ts (pipe test)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="title-case-pipe"/> ## 外部ファイルを持つコンポーネント 前の`BannerComponent`は、それぞれ`@Component.template`と`@Component.styles`プロパティで指定された*インラインテンプレート*と*インラインcss*で定義されています。 多くのコンポーネントは、それぞれ`@Component.templateUrl`と`@Component.styleUrls`プロパティで、*外部テンプレート*と*外部css*を指定します。`BannerComponent`の次のバリアントは、そのようにします。 <docs-code header="app/banner/banner-external.component.ts (metadata)" path="adev/src/content/examples/testing/src/app/banner/banner-external.component.ts" visibleRegion="metadata"/> この構文は、Angularコンパイラーに、コンポーネントのコンパイル中に外部ファイルを読み取るように指示します。 これは、CLI`ng test`コマンドを実行するときに問題になりません。なぜなら、CLIは*テストを実行する前にアプリケーションをコンパイルする*からです。 しかし、**CLI以外の環境**でテストを実行する場合、このコンポーネントのテストは失敗する可能性があります。 たとえば、[plunker](https://plnkr.co)などのWebコーディング環境で`BannerComponent`のテストを実行すると、次のようなメッセージが表示されます。 <docs-code hideCopy language="shell"> Error: This test module uses the component BannerComponent which is using a "templateUrl" or "styleUrls", but they were never compiled. Please call "TestBed.compileComponents" before your test. ``` このテストエラーメッセージは、ランタイム環境が*テスト自体の実行中に*ソースコードをコンパイルするときに発生します。 この問題を解決するには、次の[compileComponentsの呼び出し](#calling-compilecomponents)セクションで説明されているように、`compileComponents()`を呼び出します。 ## 依存関係を持つコンポーネント コンポーネントは、多くの場合、サービス依存関係を持ちます。 `WelcomeComponent`は、ログインしたユーザーに歓迎メッセージを表示します。 これは、注入された`UserService`のプロパティに基づいて、ユーザーが誰かを知っています。 ``` `WelcomeComponent`には、サービスと対話する意思決定ロジックがあり、このコンポーネントのテスト価値を高めています。 ### サービステストダブルを提供する *テスト対象のコンポーネント*は、実際のサービスを提供する必要はありません。 実際の`UserService`を注入するのは難しい場合があります。 実際のサービスは、ユーザーにログイン資格情報の入力を求めて、認証サーバーにアクセスしようとするかもしれません。 これらの動作は、インターセプトするのが難しい場合があります。テストダブルを使用すると、テストが本番環境とは異なる動作をするため、控えめに使用してください。 ### 注入されたサービスを取得する テストでは、`WelcomeComponent`に注入された`UserService`にアクセスする必要があります。 Angularには、階層的な注入システムがあります。 `TestBed`によって作成されたルートインジェクターから、コンポーネントツリーを下って、複数のレベルにインジェクターが存在する可能性があります。 注入されたサービスを取得する最も安全な方法は、*常に動作する*方法であり、 *テスト対象のコンポーネント*のインジェクターから取得することです。 コンポーネントインジェクターは、フィクスチャの`DebugElement`のプロパティです。 <docs-code header="WelcomeComponent's injector" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="injected-service"/> HELPFUL: これは_通常_は必要ありません。サービスは、多くの場合、ルートまたは`TestBed`のオーバーライドで提供され、`TestBed.inject()`を使用してより簡単に取得できます（下記参照）。 ### `TestBed.inject()` これは、フィクスチャの`DebugElement`を使用してサービスを取得するよりも覚えやすく、冗長性が少なくなります。 このテストスイートでは、`UserService`のプロバイダーはルートテストモジュールのみであるため、次のように`TestBed.inject()`を呼び出すのは安全です。 <docs-code header="TestBed injector" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="inject-from-testbed" /> HELPFUL: `TestBed.inject()`が機能しないユースケースについては、[*コンポーネントプロバイダーのオーバーライド*](#override-component-providers)セクションを参照してください。このセクションでは、いつ、なぜフィクスチャのインジェクターの代わりにコンポーネントのインジェクターからサービスを取得する必要があるのかを説明しています。 ### 最終的な設定とテスト 次に、`TestBed.inject()`を使用した完全な`beforeEach()`を示します。 <docs-code header="app/welcome/welcome.component.spec.ts" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="setup"/> 次に、いくつかのテストを示します。 <docs-code header="app/welcome/welcome.component.spec.ts" path="adev/src/content/examples/testing/src/app/welcome/welcome.component.spec.ts" visibleRegion="tests"/> 最初のテストは、健全性テストです。これは、`UserService`が呼び出され、機能していることを確認します。 HELPFUL: withContext関数（たとえば、`'expected name'`）は、オプションの失敗ラベルです。 期待値が失敗した場合、Jasmineは期待値の失敗メッセージにこのラベルを追加します。 複数の期待値を持つスペックでは、何が間違っていたのか、どの期待値が失敗したのかを明確にするのに役立ちます。 残りのテストは、サービスが異なる値を返した場合に、コンポーネントのロジックが正しいことを確認します。 2番目のテストは、ユーザー名の変更の効果を検証します。 3番目のテストは、ログインしたユーザーがいない場合に、コンポーネントが適切なメッセージを表示することを確認します。 ## 非同期サービスを持つコンポーネント このサンプルでは、`AboutComponent`テンプレートは`TwainComponent`をホストしています。 `TwainComponent`は、マーク・トウェインの引用を表示します。 <docs-code header="app/twain/twain.component.ts (template)" path="adev/src/content/examples/testing/src/app/twain/twain.component.ts" visibleRegion="template" /> HELPFUL: コンポーネントの`quote`プロパティの値は、`AsyncPipe`を通過します。 つまり、プロパティは`Promise`または`Observable`のいずれかを返します。 この例では、`TwainComponent.getQuote()`メソッドは、`quote`プロパティが`Observable`を返すと伝えています。 <docs-code header="app/twain/twain.component.ts (getQuote)" path="adev/src/content/examples/testing/src/app/twain/twain.component.ts" visibleRegion="get-quote"/> `TwainComponent`は、注入された`TwainService`から引用を取得します。 コンポーネントは、サービスが最初の引用を返す前に、プレースホルダー値（`'...'`）で返された`Observable`を開始します。 `catchError`はサービスエラーをインターセプトし、エラーメッセージを準備し、成功チャネルでプレースホルダー値を返します。 これらはすべて、テストしたい機能です。 ### スパイによるテスト コンポーネントをテストする場合は、サービスのパブリックAPIのみが問題になります。 一般的に、テスト自体がリモートサーバーへの呼び出しを行わないようにする必要があります。 そのような呼び出しをエミュレートする必要があります。 この`app/twain/twain.component.spec.ts`のセットアップは、その方法の1つを示しています。 <docs-code header="app/twain/twain.component.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="setup"/> スパイに注目してください。 <docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="spy"/> スパイは、`getQuote`への呼び出しが、テスト引用を含むObservableを受け取るように設計されています。 実際の`getQuote()`メソッドとは異なり、このスパイはサーバーをバイパスし、値がすぐに利用可能な同期Observableを返します。 このスパイを使用すると、`Observable`が同期的なものであっても、多くの役立つテストを作成できます。 HELPFUL: スパイの使用は、テストに必要なものに限定するのが最善です。必要なもの以上のモックやスパイを作成すると、壊れやすくなる可能性があります。コンポーネントとインジェクタブルが進化するにつれて、関連のないテストは、それ以外ではテストに影響を与えないのに十分な動作をモックしなくなったために失敗する可能性があります。 ### `fakeAsync()`による非同期テスト `fakeAsync()`機能を使用するには、テストセットアップファイルに`zone.js/testing`をインポートする必要があります。 Angular CLIでプロジェクトを作成した場合、`zone-testing`はすでに`src/test.ts`にインポートされています。 次のテストは、サービスが`ErrorObservable`を返した場合に期待される動作を確認します。 <docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="error-test"/> HELPFUL: `it()`関数は、次の形式の引数を受け取ります。 <docs-code language="javascript"> fakeAsync(() => { /*test body*/ }) ``` `fakeAsync()`関数は、特別な`fakeAsync test zone`でテスト本体を実行することで、線形のコーディングスタイルを可能にします。 テスト本体は同期的に見えるようになります。 制御フローを妨げるネストされた構文（`Promise.then()`など）はありません。 HELPFUL: 制限事項: `fakeAsync()`関数は、テスト本体が`XMLHttpRequest`（XHR）呼び出しをすると機能しません。 テスト内のXHR呼び出しはまれですが、XHRを呼び出す必要がある場合は、[`waitForAsync()`](#waitForAsync)セクションを参照してください。 IMPORTANT: `fakeAsync`ゾーン内で発生する非同期タスクは、`flush`または`tick`を使用して手動で実行する必要があることに注意してください。 `fakeAsync`テストヘルパーを使用して時間を進めずに、完了するまで待つと（つまり、`fixture.whenStable`を使用）、テストは失敗する可能性が高いです。 詳細については、以下を参照してください。 ### `tick()`関数 [tick()](api/core/testing/tick)を呼び出して、仮想クロックを進める必要があります。 [tick()](api/core/testing/tick)を呼び出すと、保留中の非同期アクティビティがすべて完了するまで、仮想クロックが前進します。 この場合、Observableの`setTimeout()`を待ちます。 [tick()](api/core/testing/tick)関数は、`millis`と`tickOptions`をパラメーターとして受け取ります。`millis`パラメーターは、仮想クロックがどれだけ進むかを指定し、指定されていない場合はデフォルトで`0`になります。 たとえば、`fakeAsync()`テストに`setTimeout(fn, 100)`がある場合、`fn`のコールバックをトリガーするには、`tick(100)`を使用する必要があります。 オプションの`tickOptions`パラメーターには、`processNewMacroTasksSynchronously`という名前のプロパティがあります。`processNewMacroTasksSynchronously`プロパティは、ティック時に新しい生成されたマクロタスクを呼び出すかどうかを表し、デフォルトでは`true`です。 ``` [tick()](api/core/testing/tick)関数は、`TestBed`でインポートするAngularのテストユーティリティの1つです。 これは`fakeAsync()`の仲間であり、`fakeAsync()`本体内でのみ呼び出すことができます。 ### tickOptions この例では、ネストされた`setTimeout`関数が新しいマクロタスクです。デフォルトでは、`tick`がsetTimeoutの場合、`outside`と`nested`の両方がトリガーされます。 <docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-tick-new-macro-task-sync"/> 場合によっては、ティック時に新しいマクロタスクをトリガーしたくない場合があります。`tick(millis, {processNewMacroTasksSynchronously: false})`を使用して、新しいマクロタスクを呼び出さないようにすることができます。 <docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-tick-new-macro-task-async"/> ### `fakeAsync()`内の日付の比較 `fakeAsync()`は時間の経過をシミュレートするため、`fakeAsync()`内で日付の差を計算することができます。 <docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-date"/> ### `jasmine.clock`と`fakeAsync()` Jasmineは、日付をモックするための`clock`機能も提供しています。 Angularは、`jasmine.clock().install()`が`fakeAsync()`メソッド内で呼び出された後、`jasmine.clock().uninstall()`が呼び出されるまで実行されるテストを自動的に実行します。 `fakeAsync()`は必要なく、ネストされている場合はエラーをスローします。 デフォルトでは、この機能はオフになっています。 有効にするには、`zone-testing`をインポートする前にグローバルフラグを設定します。 Angular CLIを使用している場合は、`src/test.ts`でこのフラグを設定します。 <docs-code language="typescript"> [window as any]('__zone_symbol__fakeAsyncPatchLock') = true; import 'zone.js/testing'; ``` ``` ### `fakeAsync()`内のRxJSスケジューラーの使用 `setTimeout()`や`setInterval()`と同様に、`fakeAsync()`でRxJSスケジューラーを使用することもできますが、RxJSスケジューラーをパッチするために`zone.js/plugins/zone-patch-rxjs-fake-async`をインポートする必要があります。 <docs-code path="adev/src/content/examples/testing/src/app/demo/async-helper.spec.ts" visibleRegion="fake-async-test-rxjs"/> ### より多くのmacroTasksをサポートする デフォルトでは、`fakeAsync()`は次のmacroTasksをサポートしています。 * `setTimeout` * `setInterval` * `requestAnimationFrame` * `webkitRequestAnimationFrame` * `mozRequestAnimationFrame` `HTMLCanvasElement.toBlob()`などの他のmacroTasksを実行すると、「fake async testで不明なmacroTaskがスケジュールされました」というエラーがスローされます。 このような場合をサポートしたい場合は、サポートするmacroTasksを`beforeEach()`で定義する必要があります。 たとえば、次のようになります。 <docs-code header="src/app/shared/canvas.component.spec.ts (excerpt)" path="adev/src/content/examples/testing/src/app/shared/canvas.component.spec.ts" visibleRegion="enable-toBlob-macrotask"/> HELPFUL: アプリで`<canvas>`要素をZone.js対応にするには、`zone-patch-canvas`パッチをインポートする必要があります（`polyfills.ts`または`<canvas>`を使用する特定のファイルにインポートします）。 <docs-code header="src/polyfills.ts or src/app/shared/canvas.component.ts" path="adev/src/content/examples/testing/src/app/shared/canvas.component.ts" visibleRegion="import-canvas-patch"/> ### 非同期Observable これらのテストのテストカバレッジに満足しているかもしれません。 しかし、実際のサービスが完全にこのようには動作していないという事実で悩んでいるかもしれません。 実際のサービスは、リモートサーバーにリクエストを送信します。 サーバーは応答するまでに時間がかかり、応答は前の2つのテストのようにすぐに利用できるわけではありません。 テストでは、次のように`getQuote()`スパイから*非同期*Observableを返すと、現実の世界をより忠実に反映することができます。 <docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="async-setup"/> ### 非同期Observableのヘルパー 非同期Observableは、`asyncData`ヘルパーによって生成されました。 `asyncData`ヘルパーは、自分で記述するか、サンプルコードからこのヘルパーをコピーする必要があるユーティリティ関数です。 <docs-code header="testing/async-observable-helpers.ts" path="adev/src/content/examples/testing/src/testing/async-observable-helpers.ts" visibleRegion="async-data"/> このヘルパーのObservableは、JavaScriptエンジンの次のターンで`data`値を発行します。 [RxJS `defer()`演算子](http://reactivex.io/documentation/operators/defer.html)は、Observableを返します。 これは、`Promise`または`Observable`のいずれかを返すファクトリ関数を取得します。 何かが*defer*のObservableを購読すると、そのファクトリで作成された新しいObservableに購読者を追加します。 `defer()`演算子は、`Promise.resolve()`を、`HttpClient`のように一度発行して完了する新しいObservableに変換します。 購読者は、`data`値を受け取ると購読解除されます。 非同期エラーを生成するための同様のヘルパーがあります。 <docs-code path="adev/src/content/examples/testing/src/testing/async-observable-helpers.ts" visibleRegion="async-error"/> ### さらなる非同期テスト `getQuote()`スパイが非同期Observableを返すようになったので、ほとんどのテストも非同期にする必要があります。 次に、現実の世界で期待されるデータフローを示す`fakeAsync()`テストを示します。 <docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="fake-async-test"/> 引用要素には、`ngOnInit()`の後、プレースホルダー値（`'...'`）が表示されます。 まだ最初の引用は届いていません。 Observableから最初の引用をフラッシュするには、[tick()](api/core/testing/tick)を呼び出します。 次に、`detectChanges()`を呼び出して、Angularに画面を更新するように指示します。 その後、引用要素に期待どおりのテキストが表示されていることをアサートできます。 ### `fakeAsync()`を使わない非同期テスト 次に、前の`fakeAsync()`テストを`async`で書き直したものを示します。 <docs-code path="adev/src/content/examples/testing/src/app/twain/twain.component.spec.ts" visibleRegion="async-test"/> ### `whenStable` テストは、`getQuote()`Observableが次の引用を発行するまで待つ必要があります。 [tick()](api/core/testing/tick)を呼び出す代わりに、`fixture.whenStable()`を呼び出します。 `fixture.whenStable()`は、JavaScriptエンジンのタスクキューが空になったときに解決されるプロミスを返します。 この例では、タスクキューはObservableが最初の引用を発行したときに空になります。 ## 入力と出力を持つコンポーネント 入力と出力を持つコンポーネントは、通常、ホストコンポーネントのビューテンプレート内に表示されます。 ホストは、プロパティバインディングを使用して入力プロパティを設定し、イベントバインディングを使用して出力プロパティによって発生したイベントをリスンします。 テストの目標は、そのようなバインディングが期待どおりに機能することを確認することです。 テストでは、入力値を設定し、出力イベントをリスンする必要があります。 `DashboardHeroComponent`は、この役割を果たすコンポーネントの小さな例です。 これは、`DashboardComponent`によって提供された個々のヒーローを表示します。 そのヒーローをクリックすると、`DashboardComponent`にユーザーがヒーローを選択したことを伝えます。 `DashboardHeroComponent`は、次のように`DashboardComponent`テンプレートに埋め込まれています。 <docs-code header="app/dashboard/dashboard.component.html (excerpt)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard.component.html" visibleRegion="dashboard-hero"/> `DashboardHeroComponent`は`@for`ブロック内に表示され、各コンポーネントの`hero`入力プロパティはループする値に設定され、コンポーネントの`selected`イベントをリスンします。 コンポーネントの完全な定義を次に示します。 <docs-code header="app/dashboard/dashboard-hero.component.ts (component)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.ts" visibleRegion="component"/> この単純なコンポーネントをテストすることは、ほとんど内在的な価値はありませんが、テスト方法を知る価値はあります。 次のいずれかの方法を使用します。 * `DashboardComponent`で使用されているようにテストする * スタンドアロンコンポーネントとしてテストする * `DashboardComponent`の代替として使用されているようにテストする 当面の目標は、`DashboardComponent`ではなく`DashboardHeroComponent`をテストすることなので、2番目と3番目のオプションを試してみましょう。 ### `DashboardHeroComponent`をスタンドアロンでテストする スペックファイルの設定の重要な部分を次に示します。 <docs-code header="app/dashboard/dashboard-hero.component.spec.ts (setup)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="setup"/> 設定コードは、コンポーネントの`hero`プロパティにテストヒーロー（`expectedHero`）を割り当てています。これは、`DashboardComponent`がリピーターのプロパティバインディングを使用して設定する方法をエミュレートしています。 次のテストは、ヒーロー名がバインディングを使用してテンプレートに伝播されることを検証します。 <docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="name-test"/> [テンプレート](#dashboard-hero-component)は、ヒーロー名をAngularの`UpperCasePipe`を通して渡すため、テストでは要素値を大文字の名前と照合する必要があります。 ### クリック ヒーローをクリックすると、ホストコンポーネント（`DashboardComponent`と推測される）が聞き取ることができる`selected`イベントが発生するはずです。 <docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="click-test"/> コンポーネントの`selected`プロパティは、`EventEmitter`を返します。これは、消費者にとってはRxJSの同期`Observable`のように見えます。 テストは、ホストコンポーネントが*暗黙的に*行うように、*明示的に*これを購読します。 コンポーネントが期待どおりに動作すれば、ヒーローの要素をクリックすると、コンポーネントの`selected`プロパティに`hero`オブジェクトを発行するように指示されます。 テストは、`selected`への購読を通じてそのイベントを検出します。 ### `triggerEventHandler` 前のテストの`heroDe`は、ヒーロー`<div>`を表す`DebugElement`です。 これは、ネイティブ要素との対話を抽象化するAngularのプロパティとメソッドを持っています。 このテストは、"click"イベント名で`DebugElement.triggerEventHandler`を呼び出します。 "click"イベントバインディングは、`DashboardHeroComponent.click()`を呼び出すことで応答します。 Angularの`DebugElement.triggerEventHandler`は、*イベント名*を使用して、*データバインドされたイベント*を発生させることができます。 2番目のパラメーターは、ハンドラーに渡されるイベントオブジェクトです。 テストでは、"click"イベントをトリガーしました。 <docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="trigger-event-handler"/> この場合、テストでは、ランタイムイベントハンドラーであるコンポーネントの`click()`メソッドがイベントオブジェクトを気にしないことを正しく想定しています。 HELPFUL: 他のハンドラーは、それほど寛容ではありません。 たとえば、`RouterLink`ディレクティブは、クリック時にどのマウスボタンが押されたかを識別する`button`プロパティを持つオブジェクトを期待しています。 `RouterLink`ディレクティブは、イベントオブジェクトが不足している場合、エラーをスローします。 ### 要素をクリックする 次のテストの代替案は、ネイティブ要素自身の`click()`メソッドを呼び出します。これは、*このコンポーネント*には完全に適しています。 <docs-code path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="click-test-2"/> ### `click()`ヘルパー ボタン、アンカー、または任意のHTML要素をクリックすることは、一般的なテストタスクです。 次の`click()`関数のようなヘルパーに*クリックをトリガーする*プロセスをカプセル化することで、それを一貫性があり、簡単に行うことができます。 <docs-code header="testing/index.ts (click helper)" path="adev/src/content/examples/testing/src/testing/index.ts" visibleRegion="click-event"/> 最初の引数は、*クリックする要素*です。 必要に応じて、2番目の引数としてカスタムイベントオブジェクトを渡すことができます。 デフォルトは、`RouterLink`ディレクティブを含む多くのハンドラーで受け入れられる、部分的な[左ボタンのマウスイベントオブジェクト](https://developer.mozilla.org/docs/Web/API/MouseEvent/button)です。 IMPORTANT: `click()`ヘルパー関数は、Angularのテストユーティリティの**1つではありません**。 これは、*このガイドのサンプルコード*で定義された関数です。 サンプルテストはすべてこれを利用しています。 気に入ったら、自分のヘルパーのコレクションに追加してください。 次に、クリックヘルパーを使用した前のテストを示します。 <docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test with click helper)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="click-test-3"/> ## テストホスト内のコンポーネント 前のテストは、ホスト`DashboardComponent`の役割を自身で演じていました。 しかし、`DashboardHeroComponent`は、ホストコンポーネントに適切にデータバインドされている場合、正しく動作するでしょうか？ <docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test host)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="test-host"/> テストホストは、コンポーネントの`hero`入力プロパティをテストヒーローで設定します。 これは、コンポーネントの`selected`イベントを`onSelected`ハンドラーにバインドし、これは`selectedHero`プロパティに発行されたヒーローを記録します。 後で、テストは`selectedHero`をチェックして、`DashboardHeroComponent.selected`イベントが期待どおりのヒーローを発行したことを確認できます。 `test-host`テストの設定は、スタンドアロンテストの設定に似ています。 <docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test host setup)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="test-host-setup"/> このテストモジュール設定は、3つの重要な違いを示しています。 * `DashboardHeroComponent`と`TestHostComponent`の両方を*インポート*します * `DashboardHeroComponent`ではなく`TestHostComponent`を*作成*します * `TestHostComponent`は、バインディングで`DashboardHeroComponent.hero`を設定します `createComponent`は、`DashboardHeroComponent`のインスタンスではなく、`TestHostComponent`のインスタンスを保持する`fixture`を返します。 `TestHostComponent`を作成すると、後者が前者のテンプレート内に表示されているため、`DashboardHeroComponent`が作成されます。 ヒーロー要素（`heroEl`）のクエリは、テストDOM内で見つかりますが、前のテストよりも要素ツリーの深さが大きくなります。 テスト自体は、スタンドアロンバージョンとほとんど同じです。 <docs-code header="app/dashboard/dashboard-hero.component.spec.ts (test-host)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="test-host-tests"/> 選択されたイベントテストのみが異なります。 これは、選択された`DashboardHeroComponent`のヒーローが、実際にイベントバインディングを通じてホストコンポーネントに到達することを確認します。 ## ルーティングコンポーネント *ルーティングコンポーネント*は、`Router`に別のコンポーネントにナビゲートするように指示するコンポーネントです。 `DashboardComponent`は、ユーザーがダッシュボードの*ヒーローボタン*の1つをクリックすることで`HeroDetailComponent`にナビゲートできるため、*ルーティングコンポーネント*です。 Angularは、`HttpClient`に依存するコードをより効果的にテストするために、テストヘルパーを提供しています。`provideRouter`関数はテストモジュール内でも直接使えます。 <docs-code header="app/dashboard/dashboard.component.spec.ts" path="adev/src/content/examples/testing/src/app/dashboard/dashboard.component.spec.ts" visibleRegion="router-harness"/> 次のテストは、表示されているヒーローをクリックし、期待されるURLにナビゲートしたことを確認します。 <docs-code header="app/dashboard/dashboard.component.spec.ts (navigate test)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard.component.spec.ts" visibleRegion="navigate-test"/> ## ルーティングされたコンポーネント *ルーティングされたコンポーネント*は、`Router`ナビゲーションの宛先です。 特に、コンポーネントへのルートに*パラメーターが含まれている場合*、テストが難しくなる場合があります。 `HeroDetailComponent`は、このようなルートの宛先である*ルーティングされたコンポーネント*です。 ユーザーが*Dashboard*のヒーローをクリックすると、`DashboardComponent`は`Router`に`heroes/:id`にナビゲートするように指示します。 `:id`は、編集するヒーローの`id`であるルートパラメーターです。 `Router`は、そのURLを`HeroDetailComponent`へのルートと照合します。 これは、ルーティング情報を持つ`ActivatedRoute`オブジェクトを作成し、`HeroDetailComponent`の新しいインスタンスに注入します。 Here are the services injected into `HeroDetailComponent`: <docs-code header="app/hero/hero-detail.component.ts (constructor)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.ts" visibleRegion="ctor"/> `HeroDetail`コンポーネントは、`id`パラメーターが必要であり、これにより`HeroDetailService`を使用して対応するヒーローを取得できます。 コンポーネントは、`Observable`である`ActivatedRoute.paramMap`プロパティから`id`を取得する必要があります。 コンポーネントは、`ActivatedRoute.paramMap`の`id`プロパティを参照することはできません。 コンポーネントは、`ActivatedRoute.paramMap`Observableを*購読*し、ライフタイム中に`id`が変更される場合に備えておく必要があります。 <docs-code header="app/hero/hero-detail.component.ts (constructor)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.ts" visibleRegion="ctor"/> テストでは、異なるルートにナビゲートすることで、`HeroDetailComponent`が異なる`id`パラメーター値にどのように応答するかを調べることができます。 ### `RouterTestingHarness`によるテスト 次に、観察された`id`が既存のヒーローを参照している場合に、コンポーネントの動作を示すテストを示します。 <docs-code header="app/hero/hero-detail.component.spec.ts (existing id)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="route-good-id"/> HELPFUL: 後のセクションでは、`createComponent()`メソッドと`page`オブジェクトについて説明します。 今のところ、直感的に理解してください。 `id`が見つからない場合、コンポーネントは`HeroListComponent`にリダイレクトする必要があります。 テストスイートの設定では、同じルーターハーネスが提供されました[上記を参照](#routing-component)。 このテストは、コンポーネントが`HeroListComponent`へのナビゲーションを試みると予想しています。 <docs-code header="app/hero/hero-detail.component.spec.ts (bad id)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="route-bad-id"/> ## ネストされたコンポーネントテスト コンポーネントテンプレートには、多くの場合、ネストされたコンポーネントが含まれています。そのテンプレートには、さらに多くのコンポーネントが含まれている場合があります。 コンポーネントツリーは非常に深くなる可能性があり、ネストされたコンポーネントはツリーの先頭に配置されたコンポーネントをテストする際に役割を果たさないことがあります。 たとえば、`AppComponent`は、アンカーと`RouterLink`ディレクティブを持つナビゲーションバーを表示します。 <docs-code header="app/app.component.html" path="adev/src/content/examples/testing/src/app/app.component.html"/> ナビゲーションではなくリンクを検証するために、`Router`が*ルーティングされたコンポーネント*を挿入する場所を示す`<router-outlet>`も必要ありません。 `BannerComponent`と`WelcomeComponent`（`<app-banner>`と`<app-welcome>`で示されています）も関係ありません。 しかし、DOMに`AppComponent`を作成するテストは、これらの3つのコンポーネントのインスタンスも作成し、それを許可した場合、`TestBed`を設定してそれらを作成する必要があります。 それらを宣言することを怠ると、Angularコンパイラーは`AppComponent`テンプレートの`<app-banner>`、`<app-welcome>`、および`<router-outlet>`タグを認識せず、エラーをスローします。 実際のコンポーネントを宣言すると、*それら*のネストされたコンポーネントも宣言し、ツリー内の*任意の*コンポーネントに注入された*すべての*サービスを提供する必要があります。 このセクションでは、セットアップを最小限にするための2つのテクニックについて説明します。 これらを単独で、または組み合わせて使用して、主要なコンポーネントのテストに集中してください。 ### 不要なコンポーネントのスタブ化 最初のテクニックでは、テストでほとんど役割を果たさないコンポーネントとディレクティブのスタブバージョンを作成して宣言します。 <docs-code header="app/app.component.spec.ts (stub declaration)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="component-stubs"/> スタブセレクターは、対応する実際のコンポーネントのセレクターと一致します。 しかし、それらのテンプレートとクラスは空です。 次に、`TestBed`設定内で、実際にする必要があるコンポーネント、ディレクティブ、パイプの横に宣言します。 <docs-code header="app/app.component.spec.ts (TestBed stubs)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="testbed-stubs"/> `AppComponent`はテスト対象なので、当然、実際のバージョンを宣言します。 残りはスタブです。 ### `NO_ERRORS_SCHEMA` 2番目の方法では、`TestBed.schemas`メタデータに`NO_ERRORS_SCHEMA`を追加します。 <docs-code header="app/app.component.spec.ts (NO_ERRORS_SCHEMA)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="no-errors-schema"/> `NO_ERRORS_SCHEMA`は、Angularコンパイラーに、認識されていない要素と属性を無視するように指示します。 コンパイラーは、`TestBed`設定で対応する`AppComponent`と`RouterLink`を宣言したため、`<app-root>`要素と`routerLink`属性を認識します。 しかし、コンパイラーは`<app-banner>`、`<app-welcome>`、または`<router-outlet>`に遭遇してもエラーをスローしません。 単にそれらを空のタグとしてレンダリングし、ブラウザはそれらを無視します。 スタブコンポーネントは不要になりました。 ### 2つのテクニックを組み合わせて使用する これらは、*シャローコンポーネントテスト*のためのテクニックであり、コンポーネントの視覚的な表面を、テストにとって重要なコンポーネントのテンプレート内の要素だけに制限するため、そう呼ばれています。 `NO_ERRORS_SCHEMA`アプローチは2つのうちより簡単ですが、使い過ぎないでください。 `NO_ERRORS_SCHEMA`は、コンパイラーが意図的に省略した、または誤ってスペルミスをした、見逃したコンポーネントと属性について警告するのを防ぎます。 コンパイラーが瞬時に検出できたはずの幽霊バグを追いかけて何時間も無駄にする可能性があります。 *スタブコンポーネント*アプローチには、もう1つの利点があります。 *この*例ではスタブは空でしたが、テストでそれらと何らかの形で対話する必要がある場合は、縮小されたテンプレートとクラスを与えることができます。 実際には、次の例のように、2つのテクニックを同じセットアップに組み合わせます。 <docs-code header="app/app.component.spec.ts (mixed setup)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="mixed-setup"/> Angularコンパイラーは、`<app-banner>`要素に対して`BannerStubComponent`を作成し、`routerLink`属性を持つアンカーに`RouterLink`を適用しますが、`<app-welcome>`と`<router-outlet>`タグは無視します。 ### `By.directive`と注入されたディレクティブ さらに少しセットアップすると、初期データバインディングがトリガーされ、ナビゲーションリンクへの参照が取得されます。 <docs-code header="app/app.component.spec.ts (test setup)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="test-setup"/> 3つの重要なポイントを次に示します。 * `By.directive`を使用して、アタッチされたディレクティブを持つアンカー要素を見つけます * クエリは、一致する要素をラップする`DebugElement`ラッパーを返します * 各`DebugElement`は、その要素にアタッチされたディレクティブの特定のインスタンスを含む依存関係インジェクターを公開します `AppComponent`が検証するリンクは次のとおりです。 <docs-code header="app/app.component.html (navigation links)" path="adev/src/content/examples/testing/src/app/app.component.html" visibleRegion="links"/> 次に、これらのリンクが期待どおりに`routerLink`ディレクティブに配線されていることを確認するテストを示します。 <docs-code header="app/app.component.spec.ts (selected tests)" path="adev/src/content/examples/testing/src/app/app.component.spec.ts" visibleRegion="tests"/> ## `page`オブジェクトの使用 `HeroDetailComponent`は、タイトル、2つのヒーローフィールド、2つのボタンを持つ単純なビューです。 しかし、この単純な形式でも、テンプレートの複雑さはたくさんあります。 <docs-code path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.html" header="app/hero/hero-detail.component.html"/> コンポーネントをテストするものは、… * ヒーローが到着するまで待つ必要がある * タイトルテキストへの参照 * 検査および設定するための名前入力ボックスへの参照 * クリックできる2つのボタンへの参照 このような小さなフォームでも、むち打ちの条件付きセットアップとCSS要素の選択の混乱を招く可能性があります。 コンポーネントのプロパティへのアクセスを処理し、それらを設定するロジックをカプセル化する`Page`クラスを使用して、複雑さを抑制します。 次に、`hero-detail.component.spec.ts`の`Page`クラスを示します。 <docs-code header="app/hero/hero-detail.component.spec.ts (Page)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="page"/> これで、コンポーネントの操作と検査のための重要なフックが、整理され、`Page`のインスタンスからアクセスできるようになりました。 `createComponent`メソッドは、`page`オブジェクトを作成し、`hero`が到着すると空白を埋めます。 <docs-code header="app/hero/hero-detail.component.spec.ts (createComponent)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="create-component"/> 次に、ポイントを強化するための`HeroDetailComponent`のテストをいくつか示します。 <docs-code header="app/hero/hero-detail.component.spec.ts (selected tests)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="selected-tests"/> ## `compileComponents()`の呼び出し HELPFUL: CLI`ng test`コマンドでのみテストを実行している場合は、このセクションを無視してください。なぜなら、CLIはテストを実行する前にアプリケーションをコンパイルするからです。 **CLI以外の環境**でテストを実行する場合、テストは次のようなメッセージで失敗する可能性があります。 <docs-code hideCopy language="shell"> Error: This test module uses the component BannerComponent which is using a "templateUrl" or "styleUrls", but they were never compiled. Please call "TestBed.compileComponents" before your test. ``` 問題の根本は、テストに関与するコンポーネントの少なくとも1つが、`BannerComponent`の次のバージョンで行われているように、外部テンプレートまたはCSSファイルを指定していることです。 ``` テストは、`TestBed`がコンポーネントの作成を試みたときに失敗します。 <docs-code avoid header="app/banner/banner-external.component.spec.ts (setup that fails)" path="adev/src/content/examples/testing/src/app/banner/banner-external.component.spec.ts" visibleRegion="setup-may-fail"/> アプリケーションはコンパイルされていないことを思い出してください。 そのため、`createComponent()`を呼び出すと、`TestBed`は暗黙的にコンパイルします。 これは、ソースコードがメモリ内にある場合は問題ありません。 しかし、`BannerComponent`は外部ファイルが必要であり、コンパイラーはファイルシステムからそれらを読み取る必要があります。これは本質的に*非同期*操作です。 `TestBed`が続行することを許可すると、テストが実行され、コンパイラーが完了する前に、不可解な理由で失敗します。 予防的なエラーメッセージは、`compileComponents()`で明示的にコンパイルするように指示しています。 ### `compileComponents()`は非同期です `compileComponents()`は、非同期テスト関数内で呼び出す必要があります。 CRITICAL: テスト関数を非同期にするのを怠ると（たとえば、[waitForAsync()](#waitForAsync)の使用を忘れると）、次のようなエラーメッセージが表示されます。 <docs-code hideCopy language="shell"> Error: ViewDestroyedError: Attempt to use a destroyed view ``` 一般的なアプローチは、セットアップロジックを2つの別の`beforeEach()`関数に分割することです。 | 関数 | 詳細 | | :----------------------- | :---------------------------- | | 非同期`beforeEach()` | コンポーネントをコンパイルする | | 同期`beforeEach()` | 残りのセットアップを実行する | ### 非同期`beforeEach` 最初の非同期`beforeEach`は、次のように記述します。 ``` `TestBed.configureTestingModule()`メソッドは、`TestBed`クラスを返し、`compileComponents()`などの他の`TestBed`の静的メソッドへの呼び出しをチェーンすることができます。 この例では、`BannerComponent`はコンパイルする必要がある唯一のコンポーネントです。 他の例では、複数のコンポーネントでテストモジュールを設定し、さらに多くのコンポーネントを保持するアプリケーションモジュールをインポートする場合があります。 それらのいずれかが外部ファイルが必要になる可能性があります。 `TestBed.compileComponents`メソッドは、テストモジュールで設定されたすべてのコンポーネントを非同期的にコンパイルします。 IMPORTANT: `compileComponents()`を呼び出した後、`TestBed`を再設定しないでください。 `compileComponents()`を呼び出すと、現在の`TestBed`インスタンスがさらに設定されなくなります。 `configureTestingModule()`や`override...`メソッドなど、`TestBed`の構成メソッドをさらに呼び出すことはできません。 `TestBed`は、試行するとエラーをスローします。 `compileComponents()`を、`TestBed.createComponent()`を呼び出す前の最後のステップにしてください。 ### 同期`beforeEach` 2番目の、同期`beforeEach()`には、残りのセットアップ手順が含まれます。これには、コンポーネントの作成と、検査する要素のクエリが含まれます。 <docs-code header="app/banner/banner-external.component.spec.ts (synchronous beforeEach)" path="adev/src/content/examples/testing/src/app/banner/banner-external.component.spec.ts" visibleRegion="sync-before-each"/> テストランナーは、最初の非同期`beforeEach`が終了するまで待ってから、2番目を呼び出します。 ### 統合された設定 2つの`beforeEach()`関数を、1つの非同期`beforeEach()`に統合できます。 `compileComponents()`メソッドはプロミスを返すため、同期セットアップタスクを*コンパイル後*に実行することができます。そのため、同期コードを`await`キーワードの後に移動します。この時点で、プロミスは解決されています。 <docs-code header="app/banner/banner-external.component.spec.ts (one beforeEach)" path="adev/src/content/examples/testing/src/app/banner/banner-external.component.spec.ts" visibleRegion="one-before-each"/> ### `compileComponents()`は安全です `compileComponents()`を呼び出しても、必要ない場合でも害はありません。 CLIによって生成されたコンポーネントテストファイルは、`ng test`を実行しているときは不要ですが、`compileComponents()`を呼び出します。 このガイドのテストでは、必要に応じてのみ`compileComponents`を呼び出します。 ## モジュールインポートによるセットアップ 以前のコンポーネントテストでは、次のようにテストモジュールをいくつかの`declarations`で設定していました。 <docs-code header="app/dashboard/dashboard-hero.component.spec.ts (configure TestBed)" path="adev/src/content/examples/testing/src/app/dashboard/dashboard-hero.component.spec.ts" visibleRegion="config-testbed"/> `DashboardComponent`はシンプルです。 助けは必要ありません。 しかし、より複雑なコンポーネントは、多くの場合、他のコンポーネント、ディレクティブ、パイプ、およびプロバイダーに依存しており、これらをテストモジュールにも追加する必要があります。 幸いなことに、`TestBed.configureTestingModule`のパラメーターは、`@NgModule`デコレーターに渡されるメタデータと並行しているため、`providers`と`imports`も指定できます。 `HeroDetailComponent`は、小さいサイズでシンプルな構造にもかかわらず、多くの助けを必要としています。 デフォルトのテストモジュール`CommonModule`からサポートを受けることに加えて、次のようなものが必要です。 * `FormsModule`の`NgModel`など、双方向データバインディングを有効にする * `shared`フォルダの`TitleCasePipe` * ルーターサービス * ヒーローのデータアクセスサービス 1つのアプローチは、次の例のように、個々のピースからテストモジュールを設定することです。 <docs-code header="app/hero/hero-detail.component.spec.ts (FormsModule setup)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="setup-forms-module"/> HELPFUL: `beforeEach()`が非同期であり、`TestBed.compileComponents`を呼び出していることに注意してください。なぜなら、`HeroDetailComponent`は外部テンプレートとcssファイルを持っているからです。 [compileComponentsの呼び出し](#calling-compilecomponents)で説明されているように、これらのテストは、Angularがブラウザでそれらをコンパイルする必要がある、CLI以外の環境で実行することができます。 ### 共有モジュールのインポート 多くのアプリケーションコンポーネントが`FormsModule`と`TitleCasePipe`を必要とするため、開発者は`SharedModule`を作成して、これらと他の頻繁に要求される部分を組み合わせました。 テスト設定では、次の例のように、`SharedModule`も使用できます。 <docs-code header="app/hero/hero-detail.component.spec.ts (SharedModule setup)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="setup-shared-module"/> これは少しタイトで小さく、インポートステートメントが少なくなります。この例では示されていません。 ### 機能モジュールのインポート `HeroDetailComponent`は、`SharedModule`など、相互依存する部分をさらにまとめた`HeroModule` [機能モジュール](guide/ngmodules/feature-modules)の一部です。 次のような`HeroModule`をインポートするテスト設定を試してみましょう。 <docs-code header="app/hero/hero-detail.component.spec.ts (HeroModule setup)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="setup-hero-module"/> `providers`の*テストダブル*のみが残ります。 `HeroDetailComponent`の宣言でさえなくなっています。 実際、宣言しようとすると、Angularはエラーをスローします。なぜなら、`HeroDetailComponent`は`HeroModule`と`TestBed`によって作成された`DynamicTestModule`の両方で宣言されているからです。 HELPFUL: コンポーネントの機能モジュールをインポートすると、モジュール内に多くの相互依存関係があり、モジュールが小さい場合（機能モジュールは通常小さい）にテストを設定する最良の方法になる場合があります。 ## コンポーネントプロバイダーのオーバーライド `HeroDetailComponent`は独自の`HeroDetailService`を提供します。 <docs-code header="app/hero/hero-detail.component.ts (prototype)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.ts" visibleRegion="prototype"/> `TestBed.configureTestingModule`の`providers`でコンポーネントの`HeroDetailService`をスタブすることはできません。 それらは*テストモジュール*のプロバイダーであり、コンポーネントのプロバイダーではありません。 それらは*フィクスチャレベル*で依存関係インジェクターを準備します。 Angularは、コンポーネントを*独自の*インジェクターで作成します。これは、フィクスチャインジェクターの*子*です。 これは、コンポーネントのプロバイダー（この場合は`HeroDetailService`）を子インジェクターに登録します。 テストは、フィクスチャインジェクターから子インジェクターのサービスを取得できません。 `TestBed.configureTestingModule`もそれらを設定することはできません。 Angularは、ずっと前から実際の`HeroDetailService`の新しいインスタンスを作成していました！ HELPFUL: これらのテストは、`HeroDetailService`がリモートサーバーに独自のXHR呼び出しを行う場合、失敗したり、タイムアウトしたりする可能性があります。 呼び出すリモートサーバーがない可能性があります。 幸いなことに、`HeroDetailService`は、リモートデータアクセスの責任を注入された`HeroService`に委任しています。 <docs-code header="app/hero/hero-detail.service.ts (prototype)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.service.ts" visibleRegion="prototype"/> [前のテスト設定](#import-a-feature-module)は、実際の`HeroService`を`TestHeroService`に置き換えます。これは、サーバーリクエストをインターセプトし、その応答を偽造します。 もし、そんなに恵まれていなかったらどうでしょうか？ `HeroService`を偽造するのが難しい場合はどうでしょうか？ `HeroDetailService`が独自のサーバーリクエストを行う場合はどうでしょうか？ `TestBed.overrideComponent`メソッドは、次のようなセットアップのバリエーションのように、コンポーネントの`providers`を管理しやすい*テストダブル*に置き換えることができます。 <docs-code header="app/hero/hero-detail.component.spec.ts (Override setup)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="setup-override"/> `TestBed.configureTestingModule`は、[不要になったため](#spy-stub)、偽の`HeroService`を提供しなくなっていることに注意してください。 ### `overrideComponent`メソッド `overrideComponent`メソッドに注目してください。 <docs-code header="app/hero/hero-detail.component.spec.ts (overrideComponent)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="override-component-method"/> これは、2つの引数を取ります。オーバーライドするコンポーネントタイプ（`HeroDetailComponent`）と、オーバーライドメタデータオブジェクトです。 [オーバーライドメタデータオブジェクト](guide/testing/utility-apis#metadata-override-object)は、次のように定義された汎用型です。 <docs-code language="javascript"> type MetadataOverride<T> = { add?: Partial<T>; remove?: Partial<T>; set?: Partial<T>; }; ``` メタデータオーバーライドオブジェクトは、メタデータプロパティの要素を追加および削除するか、それらのプロパティを完全にリセットできます。 この例では、コンポーネントの`providers`メタデータをリセットします。 型パラメーター`T`は、`@Component`デコレーターに渡すメタデータの種類です。 ```javascript selector?: string; template?: string; templateUrl?: string; providers?: any[]; … ``` ### *スパイスタブ*（`HeroDetailServiceSpy`）を提供する この例では、コンポーネントの`providers`配列を、`HeroDetailServiceSpy`を含む新しい配列に完全に置き換えます。 `HeroDetailServiceSpy`は、実際の`HeroDetailService`のスタブバージョンであり、そのサービスに必要なすべての機能を偽造します。 これは、下位の`HeroService`を注入したり、委任したりしないため、そのためのテストダブルを提供する必要はありません。 関連する`HeroDetailComponent`のテストは、サービスメソッドをスパイすることで、`HeroDetailService`のメソッドが呼び出されたことをアサートします。 それに応じて、スタブはメソッドをスパイとして実装します。 <docs-code header="app/hero/hero-detail.component.spec.ts (HeroDetailServiceSpy)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="hds-spy"/> ### オーバーライドテスト これでテストは、スパイスタブの`testHero`を操作することでコンポーネントのヒーローを直接制御し、サービスメソッドが呼び出されたことを確認できます。 <docs-code header="app/hero/hero-detail.component.spec.ts (override tests)" path="adev/src/content/examples/testing/src/app/hero/hero-detail.component.spec.ts" visibleRegion="override-tests"/> ### さらなるオーバーライド `TestBed.overrideComponent`メソッドは、同じコンポーネントまたは異なるコンポーネントに対して複数回呼び出すことができます。 `TestBed`はこれらの他のクラスの一部を掘り下げて置き換えるために、`overrideDirective`や`overrideModule`、`overridePipe`などの類似のメソッドを提供します。 これらのオプションと組み合わせを自分で調べてみてください。 # デバッグテスト テストが期待通りに動作しない場合は、ブラウザでテストを検査してデバッグできます。 アプリケーションをデバッグするのと同じように、ブラウザでスペックをデバッグできます。 1. Karmaブラウザウィンドウを表示します。 この手順で助けが必要な場合は、[テストの設定](guide/testing#set-up-testing)をご覧ください。 1. **DEBUG**ボタンをクリックして新しいブラウザタブを開き、テストを再実行します。 1. ブラウザの**開発者ツール**を開きます。Windowsでは`Ctrl-Shift-I`、macOSでは`Command-Option-I`を押します。 1. **Sources**セクションを選択します。 1. `Control/Command-P`を押して、テストファイルの名前を入力し始めると、ファイルが開きます。 1. テストにブレークポイントを設定します。 1. ブラウザを更新すると、ブレークポイントで停止します。 <img alt="Karma debugging" src="assets/images/guide/testing/karma-1st-spec-debug.png"> # テストユーティリティAPI このページでは、最も役立つAngularテスト機能について説明します。 Angularテストユーティリティには、`TestBed`、`ComponentFixture`、およびテスト環境を制御するいくつかの関数が含まれています。 [`TestBed`](#testbed-api-summary) および [`ComponentFixture`](#component-fixture-api-summary) クラスは、別途説明します。 以下は、スタンドアロン関数の概要を、ユーティリティの利用頻度順に示します。 | 関数 | 詳細 | |:--- |:--- | | `waitForAsync` | テスト（`it`）または設定（`beforeEach`）関数の本体を、特別な *非同期テストゾーン* 内で実行します。[waitForAsync](guide/testing/components-scenarios#waitForAsync) を参照してください。 | | `fakeAsync` | テスト（`it`）関数の本体を、特別な *fakeAsync テストゾーン* 内で実行します。これにより、線形制御フローのコーディングスタイルが可能になります。[fakeAsync](guide/testing/components-scenarios#fake-async) を参照してください。 | | `tick` | 時間の経過と保留中の非同期アクティビティの完了をシミュレートし、*fakeAsync テストゾーン* 内の *タイマー* および *マイクロタスク* キューの両方をフラッシュします。興味のある読者向けに、この長いブログ投稿、[*タスク、マイクロタスク、キュー、スケジュール*](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules)を紹介します。オプションの引数を受け付け、仮想クロックを指定されたミリ秒数だけ進めます。これにより、その時間枠内にスケジュールされた非同期アクティビティがクリアされます。[tick](guide/testing/components-scenarios#tick) を参照してください。 | | `inject` | 現在の `TestBed` インジェクターから、1 つ以上のサービスをテスト関数に注入します。これは、コンポーネント自体によって提供されるサービスを注入することはできません。[debugElement.injector](guide/testing/components-scenarios#get-injected-services) の議論を参照してください。 | | `discardPeriodicTasks` | `fakeAsync()` テストが保留中のタイマーイベント *タスク*（キューに入れられた `setTimeOut` および `setInterval` コールバック）で終了すると、テストは明確なエラーメッセージで失敗します。 <br /> 一般的に、テストはキューに入れられたタスクなしで終了する必要があります。保留中のタイマータスクが予想される場合は、`discardPeriodicTasks` を呼び出して *タスク* キューをフラッシュし、エラーを回避します。 | | `flushMicrotasks` | `fakeAsync()` テストが保留中の *マイクロタスク*（未解決の Promise など）で終了すると、テストは明確なエラーメッセージで失敗します。 <br /> 一般的に、テストはマイクロタスクが完了するまで待つ必要があります。保留中のマイクロタスクが予想される場合は、`flushMicrotasks` を呼び出して *マイクロタスク* キューをフラッシュし、エラーを回避します。 | | `ComponentFixtureAutoDetect` | [自動的な変更検出](guide/testing/components-scenarios#automatic-change-detection) をオンにするサービスの提供トークン。 | | `getTestBed` | 現在の `TestBed` のインスタンスを取得します。通常、`TestBed` クラスの静的クラスメソッドが十分なため、これは不要です。`TestBed` インスタンスは、静的メソッドとして利用できない、まれに使用されるメンバーをいくつか公開します。 | ## `TestBed` クラスの概要 `TestBed` クラスは、主要なAngularテストユーティリティの1つです。 APIは非常に大きく、少しづつ調べていくまで、圧倒される可能性があります。 API全体を理解しようとする前に、このガイドの前半部分を読んで、基本を理解してください。 `configureTestingModule` に渡されるモジュール定義は、`@NgModule` メタデータプロパティのサブセットです。 ```javascript type TestModuleMetadata = { providers?: any[]; declarations?: any[]; imports?: any[]; schemas?: Array<SchemaMetadata | any[]>; }; ``` 各オーバーライドメソッドは、`MetadataOverride<T>` を受け取ります。ここで `T` はメソッドに適したメタデータの種類、つまり `@NgModule`、`@Component`、`@Directive`、または `@Pipe` のパラメーターです。 ```javascript type MetadataOverride<T> = { add?: Partial<T>; remove?: Partial<T>; set?: Partial<T>; }; ``` `TestBed` APIは、現在の `TestBed` の *グローバル* インスタンスを更新または参照する静的クラスメソッドで構成されています。 内部的には、すべての静的メソッドは、現在のランタイム `TestBed` インスタンスのメソッドをカバーしています。これは、`getTestBed()` 関数によっても返されます。 `beforeEach()` *内* で `TestBed` メソッドを呼び出して、各テストの前に新しい開始を確保します。 以下は、最も重要な静的メソッドを、ユーティリティの利用頻度順に示します。 | メソッド | 詳細 | |:--- |:--- | | `configureTestingModule` | テストシム（`karma-test-shim`、`browser-test-shim`）は、[初期テスト環境](guide/testing) とデフォルトのテストモジュールを確立します。デフォルトのテストモジュールは、基本的な宣言と、すべてのテスターに必要な、いくつかの Angular サービスの代替で構成されています。 <br /> `configureTestingModule` を呼び出して、インポート、宣言（コンポーネント、ディレクティブ、およびパイプ）、およびプロバイダーを追加および削除することで、特定のテストセットのテストモジュール構成を洗練します。 | | `compileComponents` | テストモジュールを構成し終えたら、非同期にコンパイルします。*いずれかの* テストモジュールコンポーネントに `templateUrl` または `styleUrls` がある場合は、このメソッドを **必ず** 呼び出す必要があります。これは、コンポーネントテンプレートとスタイルファイルの取得が必ず非同期であるためです。[compileComponents](guide/testing/components-scenarios#calling-compilecomponents) を参照してください。 <br /> `compileComponents` を呼び出すと、現在の仕様の期間中、`TestBed` の構成は固定されます。 | | `createComponent<T>` | 現在の `TestBed` の構成に基づいて、`T` 型のコンポーネントのインスタンスを作成します。`createComponent` を呼び出すと、現在の仕様の期間中、`TestBed` の構成は固定されます。 | | `overrideModule` | 指定された `NgModule` のメタデータを置き換えます。モジュールは他のモジュールをインポートできることに注意してください。`overrideModule` メソッドは、現在のテストモジュールを深く掘り下げて、これらの内部モジュールのいずれかを変更できます。 | | `overrideComponent` | 指定されたコンポーネントクラスのメタデータを置き換えます。これは、内部モジュールの中に深くネストされている可能性があります。 | | `overrideDirective` | 指定されたディレクティブクラスのメタデータを置き換えます。これは、内部モジュールの中に深くネストされている可能性があります。 | | `overridePipe` | 指定されたパイプクラスのメタデータを置き換えます。これは、内部モジュールの中に深くネストされている可能性があります。 | | `inject` | 現在の `TestBed` インジェクターからサービスを取得します。`inject` 関数は、この目的には多くの場合で十分です。ただし、`inject` は、サービスを提供できない場合にエラーをスローします。 <br /> サービスがオプションの場合どうすればよいですか？ <br /> `TestBed.inject()` メソッドは、オプションの第 2 パラメーターとして、Angular がプロバイダーを見つけられない場合に返すオブジェクト（この例では `null`）を取ります。 <docs-code header="app/demo/demo.testbed.spec.ts" path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="testbed-get-w-null"/> `TestBed.inject` を呼び出すと、現在の仕様の期間中、`TestBed` の構成は固定されます。 | | `initTestEnvironment` | テストの実行全体でテスト環境を初期化します。 <br /> テストシム（`karma-test-shim`、`browser-test-shim`）はこれを実行するため、自分で呼び出す必要はほとんどありません。 <br /> このメソッドは *ちょうど 1 回* 呼び出します。テストの実行中にこのデフォルトを変更するには、最初に `resetTestEnvironment` を呼び出します。 <br /> Angular コンパイラーファクトリ、`PlatformRef`、およびデフォルトの Angular テストモジュールを指定します。ブラウザ以外のプラットフォームの代替手段は、`@angular/platform-<platform_name>/testing/<platform_name>` という一般的な形式で利用できます。 | | `resetTestEnvironment` | デフォルトのテストモジュールを含む、初期テスト環境をリセットします。 | `TestBed` インスタンスのメソッドのいくつかは、静的な `TestBed` *クラス* メソッドではカバーされていません。 これらは、めったに必要ありません。 ## `ComponentFixture` `TestBed.createComponent<T>` は、コンポーネント `T` のインスタンスを作成し、そのコンポーネントの強く型付けされた `ComponentFixture` を返します。 `ComponentFixture` のプロパティとメソッドは、コンポーネント、そのDOM表現、およびAngular環境の側面へのアクセスを提供します。 ### `ComponentFixture` のプロパティ 以下は、テスターにとって最も重要なプロパティを、ユーティリティの利用頻度順に示します。 | プロパティ | 詳細 | |:--- |:--- | | `componentInstance` | `TestBed.createComponent` によって作成されたコンポーネントクラスのインスタンス。 | | `debugElement` | コンポーネントのルート要素に関連付けられた `DebugElement`。 <br /> `debugElement` は、テストとデバッグ中に、コンポーネントとその DOM 要素に関する洞察を提供します。これは、テスターにとって重要なプロパティです。最も興味深いメンバーは、[下記](#debug-element-details) に記載されています。 | | `nativeElement` | コンポーネントのルートにあるネイティブ DOM 要素。 | | `changeDetectorRef` | コンポーネントの `ChangeDetectorRef`。 <br /> `ChangeDetectorRef` は、コンポーネントが `ChangeDetectionStrategy.OnPush` メソッドを持っているか、コンポーネントの変更検知がプログラムによって制御されている場合に最も役立ちます。 | ### `ComponentFixture` のメソッド *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` は、コンポーネントのDOM表現に関する重要な洞察を提供します。 テストのルートコンポーネントの `DebugElement`（`fixture.debugElement` によって返される）から、fixtureの要素とコンポーネントのサブツリー全体を（クエリを使用して）移動できます。 以下は、テスターにとって最も役立つ `DebugElement` のメンバーを、ユーティリティの利用頻度順に示します。 | メンバー | 詳細 | |:--- |:--- | | `nativeElement` | ブラウザの対応する DOM 要素 | | `query` | `query(predicate: Predicate<DebugElement>)` を呼び出すと、サブツリーの任意の深さで、[述語](#query-predicate) と一致する最初の `DebugElement` が返されます。 | | `queryAll` | `queryAll(predicate: Predicate<DebugElement>)` を呼び出すと、サブツリーの任意の深さで、[述語](#query-predicate) と一致するすべての `DebugElements` が返されます。 | | `injector` | ホスト依存インジェクター。たとえば、ルート要素のコンポーネントインスタンスインジェクター。 | | `componentInstance` | 要素自身のコンポーネントインスタンス（存在する場合）。 | | `context` | An object that provides parent context for this element. Often an ancestor component instance that governs this element. <br /> When an element is repeated within `@for` block, the context is an `RepeaterContext` whose `$implicit` property is the value of the row instance value. For example, the `hero` in `@for(hero of heroes; ...)`. | | `children` | 直近の `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` を見つけます。 <docs-code header="app/demo/demo.testbed.spec.ts" path="adev/src/content/examples/testing/src/app/demo/demo.testbed.spec.ts" visibleRegion="custom-predicate"/> Angularの `By` クラスには、一般的な述語の3つの静的メソッドがあります。 | 静的メソッド | 詳細 | |:--- |:--- | | `By.all` | すべての要素を返す | | `By.css(selector)` | 一致する CSS セレクターを持つ要素を返す | | `By.directive(directive)` | ディレクティブクラスのインスタンスに Angular が一致させた要素を返す | <docs-code header="app/hero/hero-list.component.spec.ts" path="adev/src/content/examples/testing/src/app/hero/hero-list.component.spec.ts" visibleRegion="by"/> # コンポーネントハーネスの概要 <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()`メソッドを使用します。 ```typescript const fixture = TestBed.createComponent(MyComponent); // Create a harness loader from the fixture const loader = TestbedHarnessEnvironment.loader(fixture); ... // Use the loader to get harness instances const myComponentHarness = await loader.getHarness(MyComponent); ``` フィクスチャの外部にある要素のハーネス用のハーネスローダーを作成するには、`documentRootLoader()`メソッドを使用します。たとえば、フローティング要素やポップアップを表示するコードは、AngularCDKの`Overlay`サービスのように、DOM要素をドキュメントボディに直接アタッチすることがよくあります。 また、そのフィクスチャのルート要素にあるハーネス用に、`harnessForFixture()`を使用してハーネスローダーを直接作成できます。 ### エンドツーエンドテストでの`SeleniumWebDriverHarnessEnvironment`からのローダーの使用 {#using-the-loader-from-seleniumwebdriverharnessenvironment-for-end-to-end-tests} WebDriverベースのエンドツーエンドテストでは、`SeleniumWebDriverHarnessEnvironment`を使用してハーネスローダーを作成できます。 現在のHTMLドキュメントのハーネスローダーインスタンスを、ドキュメントのルート要素にルートを持つ形で取得するには、`loader()`メソッドを使用します。この環境はWebDriverクライアントを使用します。 ```typescript 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()`メソッドを使用します。 ```typescript // Get harness for first instance of the element const myComponentHarness = await loader.getHarness(MyComponent); // Get harnesses for all instances of the element const myComponentHarnesses = await loader.getHarnesses(MyComponent); ``` 例として、クリック時にダイアログを開く再利用可能なダイアログボタンコンポーネントを考えます。これには、それぞれに対応するハーネスを持つ以下のコンポーネントが含まれています。 - `MyDialogButton` (`MyButton`と`MyDialog`を便利なAPIで構成) - `MyButton` (標準のボタンコンポーネント) - `MyDialog` (`MyDialogButton`によってクリック時に`document.body`に追加されるダイアログ) 以下のテストは、これらの各コンポーネントのハーネスをロードします。 ```typescript let fixture: ComponentFixture<MyDialogButton>; let loader: HarnessLoader; let rootLoader: HarnessLoader; beforeEach(() => { fixture = TestBed.createComponent(MyDialogButton); loader = TestbedHarnessEnvironment.loader(fixture); rootLoader = TestbedHarnessEnvironment.documentRootLoader(fixture); }); it('loads harnesses', async () => { // Load a harness for the bootstrapped component with `harnessForFixture` dialogButtonHarness = await TestbedHarnessEnvironment.harnessForFixture(fixture, MyDialogButtonHarness); // The button element is inside the fixture's root element, so we use `loader`. const buttonHarness = await loader.getHarness(MyButtonHarness); // Click the button to open the dialog await buttonHarness.click(); // The dialog is appended to `document.body`, outside of the fixture's root element, // so we use `rootLoader` in this case. const dialogHarness = await rootLoader.getHarness(MyDialogHarness); // ... make some assertions }); ``` ### 異なる環境でのハーネスの動作 {#harness-behavior-in-different-environments} ハーネスは、すべての環境でまったく同じように動作するとは限りません。実際のユーザーインタラクションと単体テストで生成されるシミュレートされたイベントの間には、避けられない違いがあります。Angular CDKは、可能な限り動作を正規化するために最善を尽くします。 ### 子要素とのインタラクション {#interacting-with-child-elements} このハーネスローダーのルート要素より下位の要素とインタラクトするには、子要素の`HarnessLoader`インスタンスを使用します。子要素の最初のインスタンスには`getChildLoader()`メソッドを、すべての子要素のインスタンスには`getAllChildLoaders()`メソッドを使用します。 ```typescript const myComponentHarness = await loader.getHarness(MyComponent); // Get loader for first instance of child element with '.child' selector const childLoader = await myComponentHarness.getLoader('.child'); // Get loaders for all instances of child elements with '.child' selector const allChildLoaders = await myComponentHarness.getAllChildLoaders('.child'); ``` ### ハーネスのフィルタリング {#filtering-harnesses} ページに特定のコンポーネントの複数のインスタンスが含まれている場合、特定のコンポーネントインスタンスを取得するために、コンポーネントの何らかのプロパティに基づいてフィルタリングしたい場合があります。これを行うには、<strong>ハーネス述語</strong>を使用できます。これは、`ComponentHarness`クラスを、コンポーネントインスタンスをフィルタリングするために使用できる述語関数と関連付けるために使用されるクラスです。 `HarnessLoader`にハーネスを要求するとき、実際にはHarnessQueryを提供しています。クエリは次の2つのいずれかです。 - ハーネスコンストラクター。これは単にそのハーネスを取得します - `HarnessPredicate`。これは1つ以上の条件に基づいてフィルタリングされたハーネスを取得します `HarnessPredicate`は、`ComponentHarness`を拡張するあらゆるものに機能するいくつかの基本フィルター（selector、ancestor）をサポートしています。 ```typescript // Example of loading a MyButtonComponentHarness with a harness predicate const disabledButtonPredicate = new HarnessPredicate(MyButtonComponentHarness, {selector: '[disabled]'}); const disabledButton = await loader.getHarness(disabledButtonPredicate); ``` ただし、ハーネスがコンポーネント固有のフィルタリングオプションを受け入れ、`HarnessPredicate`を返す静的`with()`メソッドを実装することは一般的です。 ```typescript // 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)を使用するコンポーネントのテストを以下に示します。 ```typescript it('should get value of slider thumb', async () => { const slider = await loader.getHarness(MatSliderHarness); const thumb = await slider.getEndThumb(); expect(await thumb.getValue()).toBe(50); }); ``` ## Angularの変更検知との連携 {#interop-with-angular-change-detection} デフォルトでは、テストハーネスはAngularの[変更検知](https://angular.dev/best-practices/runtime-performance)をDOM要素の状態を読み取る前と、DOM要素と対話した後に実行します。 テストで変更検知をより細かく制御する必要がある場合があります。例えば、非同期操作が保留中の間にコンポーネントの状態を確認する場合などです。このような場合は、`manualChangeDetection`関数を使用して、コードブロックの変更検知の自動処理を無効にします。 ```typescript it('checks state while async action is in progress', async () => { const buttonHarness = loader.getHarness(MyButtonHarness); await manualChangeDetection(async () => { await buttonHarness.click(); fixture.detectChanges(); // Check expectations while async click operation is in progress. expect(isProgressSpinnerVisible()).toBe(true); await fixture.whenStable(); // Check expectations after async click operation complete. expect(isProgressSpinnerVisible()).toBe(false); }); }); ``` ほとんどすべてのハーネスメソッドは非同期であり、以下をサポートするために`Promise`を返します。 - 単体テストのサポート - エンドツーエンドテストのサポート - 非同期動作の変更からテストを保護 Angularチームは、テストの可読性を向上させるために[await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)の使用を推奨しています。`await`を呼び出すと、関連する`Promise`が解決されるまでテストの実行がブロックされます。 場合によっては、複数のアクションを同時に実行し、それぞれのアクションを順次実行するのではなく、すべてが完了するまで待機したい場合があります。例えば、単一コンポーネントの複数のプロパティを読み取る場合などです。このような状況では、`parallel`関数を使用して操作を並列化します。`parallel`関数は`Promise.all`と同様に機能し、変更検知チェックも最適化します。 ```typescript it('reads properties in parallel', async () => { const checkboxHarness = loader.getHarness(MyCheckboxHarness); // Read the checked and intermediate properties simultaneously. const [checked, indeterminate] = await parallel(() => [ checkboxHarness.isChecked(), checkboxHarness.isIndeterminate() ]); expect(checked).toBe(false); expect(indeterminate).toBe(true); }); ``` # コンポーネントハーネスを作成する ## 始める前に {#before-you-start} TIP: このガイドは、[コンポーネントハーネスの概要ガイド](guide/testing/component-harnesses-overview)をすでに読んでいることを前提としています。コンポーネントハーネスの使用が初めての場合は、まずそちらをお読みください。 ### テストハーネスの作成はどのような場合に意味がありますか？ {#when-does-creating-a-test-harness-make-sense} Angularチームは、多くの場所で使用され、ユーザーインタラクティビティを持つ共有コンポーネントに対して、コンポーネントテストハーネスを作成することを推奨しています。これはウィジェットライブラリや同様の再利用可能なコンポーネントに最も一般的に適用されます。ハーネスは、これらの共有コンポーネントの利用者に、コンポーネントと対話するための十分にサポートされたAPIを提供するため、これらのケースで価値があります。ハーネスを使用するテストは、DOM構造や特定のイベントリスナーなど、これらの共有コンポーネントの信頼性の低い実装詳細に依存することを避けることができます。 アプリケーション内のページなど、1か所にのみ出現するコンポーネントの場合、ハーネスはそれほど多くの利点を提供しません。このような状況では、テストとコンポーネントが同時に更新されるため、コンポーネントのテストは、そのコンポーネントの実装詳細に合理的に依存できます。ただし、ユニットテストとエンドツーエンドテストの両方でハーネスを使用する場合、ハーネスは依然としていくつかの価値を提供します。 ### CDKのインストール {#cdk-installation} [Component Dev Kit (CDK)](https://material.angular.dev/cdk/categories)は、コンポーネントを構築するための動作プリミティブのセットです。コンポーネントハーネスを使用するには、まずnpmから`@angular/cdk`をインストールします。これは、Angular CLIを使用してターミナルから実行できます。 ```shell ng add @angular/cdk ``` ## ComponentHarnessの拡張 {#extending-componentharness} 抽象クラス`ComponentHarness`は、すべてのコンポーネントハーネスの基底クラスです。カスタムコンポーネントハーネスを作成するには、`ComponentHarness`を拡張し、静的プロパティ`hostSelector`を実装します。 `hostSelector`プロパティは、このハーネスサブクラスに一致するDOM内の要素を識別します。ほとんどの場合、`hostSelector`は対応する`Component`または`Directive`のセレクターと同じである必要があります。例えば、シンプルなポップアップコンポーネントを考えてみましょう。 ```typescript @Component({ selector: 'my-popup', template: ` <button (click)="toggle()">{{triggerText()}}</button> @if (isOpen()) { <div class="my-popup-content"><ng-content></ng-content></div> } ` }) class MyPopup { triggerText = input(''); isOpen = signal(false); toggle() { this.isOpen.update((value) => !value); } } ``` この場合、コンポーネントの最小限のハーネスは次のようになります。 ```typescript 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`の例では、トリガー要素とコンテンツ要素を取得するメソッドを次のように提供できます。 ```typescript class MyPopupHarness extends ComponentHarness { static hostSelector = 'my-popup'; // Gets the trigger element getTriggerElement = this.locatorFor('button'); // Gets the content element. getContentElement = this.locatorForOptional('.my-popup-content'); } ``` ## 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`のようなメソッドを提供できます。 ```typescript class MyPopupHarness extends ComponentHarness { static hostSelector = 'my-popup'; protected getTriggerElement = this.locatorFor('button'); protected getContentElement = this.locatorForOptional('.my-popup-content'); /** Toggles the open state of the popup. */ async toggle() { const trigger = await this.getTriggerElement(); return trigger.click(); } /** Checks if the popup us open. */ async isOpen() { const content = await this.getContentElement(); return !!content; } } ``` ## サブコンポーネントのハーネスのロード {#loading-harnesses-for-subcomponents} より大きなコンポーネントは、しばしばサブコンポーネントで構成されます。この構造は、コンポーネントのハーネスにも反映できます。`ComponentHarness`の各`locatorFor`メソッドには、要素ではなくサブハーネスを特定するために使用できる代替シグネチャがあります。 異なるlocatorForメソッドの完全なリストについては、[ComponentHarness APIリファレンスページ](/api/cdk/testing/ComponentHarness)を参照してください。 例えば、上記ポップアップを使用して構築されたメニューを考えてみましょう。 ```typescript @Directive({ selector: 'my-menu-item' }) class MyMenuItem {} @Component({ selector: 'my-menu', template: ` <my-popup> <ng-content></ng-content> </my-popup> ` }) class MyMenu { triggerText = input(''); @ContentChildren(MyMenuItem) items: QueryList<MyMenuItem>; } ``` これにより、`MyMenu`のハーネスは、`MyPopup`および`MyMenuItem`の他のハーネスを利用できます。 ```typescript class MyMenuHarness extends ComponentHarness { static hostSelector = 'my-menu'; protected getPopupHarness = this.locatorFor(MyPopupHarness); /** Gets the currently shown menu items (empty list if menu is closed). */ getItems = this.locatorForAll(MyMenuItemHarness); /** Toggles open state of the menu. */ async toggle() { const popupHarness = await this.getPopupHarness(); return popupHarness.toggle(); } } class MyMenuItemHarness extends ComponentHarness { static hostSelector = 'my-menu-item'; } ``` ## 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)を参照してください。 例えば、メニューを操作する場合、トリガーテキストに基づいてフィルタリングしたり、メニュー項目をそのテキストに基づいてフィルタリングしたりすると便利です。 ```typescript interface MyMenuHarnessFilters extends BaseHarnessFilters { /** Filters based on the trigger text for the menu. */ triggerText?: string | RegExp; } interface MyMenuItemHarnessFilters extends BaseHarnessFilters { /** Filters based on the text of the menu item. */ text?: string | RegExp; } class MyMenuHarness extends ComponentHarness { static hostSelector = 'my-menu'; /** Creates a `HarnessPredicate` used to locate a particular `MyMenuHarness`. */ static with(options: MyMenuHarnessFilters): HarnessPredicate<MyMenuHarness> { return new HarnessPredicate(MyMenuHarness, options) .addOption('trigger text', options.triggerText, (harness, text) => HarnessPredicate.stringMatches(harness.getTriggerText(), text)); } protected getPopupHarness = this.locatorFor(MyPopupHarness); /** Gets the text of the menu trigger. */ async getTriggerText(): Promise<string> { const popupHarness = await this.getPopupHarness(); return popupHarness.getTriggerText(); } ... } class MyMenuItemHarness extends ComponentHarness { static hostSelector = 'my-menu-item'; /** Creates a `HarnessPredicate` used to locate a particular `MyMenuItemHarness`. */ static with(options: MyMenuItemHarnessFilters): HarnessPredicate<MyMenuItemHarness> { return new HarnessPredicate(MyMenuItemHarness, options) .addOption('text', options.text, (harness, text) => HarnessPredicate.stringMatches(harness.getText(), text)); } /** Gets the text of the menu item. */ async getText(): Promise<string> { const host = await this.host(); return host.text(); } } ``` `HarnessLoader`、`LocatorFactory`、または`ComponentHarness`のいずれかのAPIに、`ComponentHarness`クラスの代わりに`HarnessPredicate`を渡すことができます。これにより、テスト作成者はハーネスインスタンスを作成する際に、特定のコンポーネントインスタンスを簡単にターゲットにできます。また、ハーネス作成者は同じ`HarnessPredicate`を活用して、ハーネスクラスでより強力なAPIを有効にできます。例えば、上記の`MyMenuHarness`の`getItems`メソッドを考えてみましょう。フィルタリングAPIを追加することで、ハーネスのユーザーは特定のメニュー項目を検索できるようになります。 ```typescript class MyMenuHarness extends ComponentHarness { static hostSelector = 'my-menu'; /** Gets a list of items in the menu, optionally filtered based on the given criteria. */ async getItems(filters: MyMenuItemHarnessFilters = {}): Promise<MyMenuItemHarness[]> { const getFilteredItems = this.locatorForAll(MyMenuItemHarness.with(filters)); return getFilteredItems(); } ... } ``` ## コンテンツプロジェクションを使用する要素のための`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`を拡張できます。 ```typescript 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()`メソッドを介してコンテンツ要素にアクセスする必要があります。 ```typescript class MyPopupHarness extends ComponentHarness { static hostSelector = 'my-popup'; /** Gets a `HarnessLoader` whose root element is the popup's content element. */ async getHarnessLoaderForContent(): Promise<HarnessLoader> { const rootLocator = this.documentRootLocatorFactory(); return rootLocator.harnessLoaderFor('my-popup-content'); } } ``` ## 非同期タスクの待機 {#waiting-for-asynchronous-tasks} `TestElement`のメソッドは、Angularの変更検知を自動的にトリガーし、`NgZone`内のタスクを待機します。ほとんどの場合、ハーネスの作成者が非同期タスクを待機するために特別な努力は必要ありません。しかし、これが十分でないエッジケースがいくつかあります。 特定の状況下では、Angularアニメーションは、アニメーションイベントが完全にフラッシュされる前に、変更検知の2回目のサイクルとそれに続く`NgZone`の安定化を必要とする場合があります。これが必要な場合、`ComponentHarness`は2回目の処理を行うために呼び出すことができる`forceStabilize()`メソッドを提供します。 `NgZone.runOutsideAngular()`を使用して、NgZone外でタスクをスケジュールできます。自動的に行われないため、`NgZone`外のタスクを明示的に待機する必要がある場合は、対応するハーネスで`waitForTasksOutsideAngular()`メソッドを呼び出してください。 # 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="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="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="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="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="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="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="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="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="src/app/open-close.component.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts" /> <docs-code header="src/app/open-close.component.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.html" /> <docs-code header="src/app/open-close.component.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.css"/> </docs-code-multifile> ## Transition 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="src/app/auto-height.component.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts" /> <docs-code header="src/app/auto-height.component.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.html" /> <docs-code header="src/app/auto-height.component.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.css" /> </docs-code-multifile> 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 leaving a view. <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts"> <docs-code header="src/app/insert.component.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts" /> <docs-code header="src/app/insert.component.html" path="adev/src/content/examples/animations/src/app/native-css/insert.component.html" /> <docs-code header="src/app/insert.component.css" path="adev/src/content/examples/animations/src/app/native-css/insert.component.css" /> </docs-code-multifile> Leaving a view is slightly more complex. The element removal needs to be delayed until the exit animation is complete. This requires a bit of extra code in your component class to accomplish. <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts"> <docs-code header="src/app/remove.component.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts" /> <docs-code header="src/app/remove.component.html" path="adev/src/content/examples/animations/src/app/native-css/remove.component.html" /> <docs-code header="src/app/remove.component.css" path="adev/src/content/examples/animations/src/app/native-css/remove.component.css" /> </docs-code-multifile> ### 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="src/app/increment-decrement.component.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts" /> <docs-code header="src/app/increment-decrement.component.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.html" /> <docs-code header="src/app/increment-decrement.component.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.css" /> </docs-code-multifile> ### 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="src/app/stagger.component.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts" /> <docs-code header="src/app/stagger.component.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.html" /> <docs-code header="src/app/stagger.component.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.css" /> </docs-code-multifile> ### 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. Removal animations will require additional code to add the event listener, as seen in the example above. <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts"> <docs-code header="src/app/reorder.component.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts" /> <docs-code header="src/app/reorder.component.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.html" /> <docs-code header="src/app/reorder.component.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.css" /> </docs-code-multifile> ## 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. # Route transition animations When a user navigates from one route to another, the Angular Router maps the URL path to the relevant component and displays its view. Animating this route transition can greatly enhance the user experience. The Router has support for the View Transitions API when navigating between routes in Chrome/Chromium browsers. HELPFUL: The Router's native View Transitions integration is currently in [developer preview](/reference/releases#developer-preview). Native View Transitions are also a relatively new feature so there may be limited support in some browsers. ## How View Transitions work The native browser method that’s used for view transitions is `document.startViewTransition`. When `startViewTransition()` is called, the browser captures the current state of the page which includes taking a screenshot. The method takes a callback that updates the DOM and this function can be asynchronous. The new state is captured and the transition begins in the next animation frame when the promise returned by the callback resolves. Here’s an example of the startViewTransition api: ```ts document.startViewTransition(async () => { await updateTheDOMSomehow(); }); ``` If you’re curious to read more about the details of the browser API, the [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions) is an invaluable resource. ## How the Router uses view transitions Several things happen after navigation starts in the router: route matching, loading lazy routes and components, executing guards and resolvers to name a few. Once these have completed successfully, the new routes are ready to be activated. This route activation is the DOM update that we want to perform as part of the view transition. When the view transition feature is enabled, navigation “pauses” and a call is made to the browser’s `startViewTransition` method. Once the `startViewTransition` callback executes (this happens asynchronously, as outlined in the spec here), navigation “resumes”. The remaining steps for the router navigation include updating the browser URL and activating or deactivating the matched routes (the DOM update). Finally, the callback passed to `startViewTransition` returns a Promise that resolves once Angular has finished rendering. As described above, this indicates to the browser that the new DOM state should be captured and the transition should begin. View transitions are a [progressive enhancement](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement). If the browser does not support the API, the Router will perform the DOM updates without calling `startViewTransition` and the navigation will not be animated. ## Enabling View Transitions in the Router To enable this feature, simply add `withViewTransitions` to the `provideRouter` or set `enableViewTransitions: true` in `RouterModule.forRoot`: ```ts // Standalone bootstrap bootstrapApplication(MyApp, {providers: [ provideRouter(ROUTES, withViewTransitions()), ]}); // NgModule bootstrap @NgModule({ imports: [RouterModule.forRoot(routes, {enableViewTransitions: true})] }) export class AppRouting {} ``` [Try the “count” example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-2dnvtm?file=src%2Fmain.ts) This example uses the counter application from the Chrome explainer and replaces the direct call to startViewTransition when the counter increments with a router navigation. ## Using CSS to customize transitions View transitions can be customized with CSS. We can also instruct the browser to create separate elements for the transition by setting a view-transition-name. We can expand the first example by adding view-transition-name: count to the .count style in the Counter component. Then, in the global styles, we can define a custom animation for this view transition: ```css /* Custom transition */ @keyframes rotate-out { to { transform: rotate(90deg); } } @keyframes rotate-in { from { transform: rotate(-90deg); } } ::view-transition-old(count), ::view-transition-new(count) { animation-duration: 200ms; animation-name: -ua-view-transition-fade-in, rotate-in; } ::view-transition-old(count) { animation-name: -ua-view-transition-fade-out, rotate-out; } ``` It is important that the view transition animations are defined in a global style file. They cannot be defined in the component styles because the default view encapsulation will scope the styles to the component. [Try the updated “count” example on StackBlitz](https://stackblitz.com/edit/stackblitz-starters-fwn4i7?file=src%2Fmain.ts) ## Controlling transitions with onViewTransitionCreated The `withViewTransitions` router feature can also be called with an options object that includes an `onViewTransitionCreated` callback. This callback is run in an [injection context](/guide/di/dependency-injection-context#run-within-an-injection-context) and receives a [ViewTransitionInfo](/api/router/ViewTransitionInfo) object that includes the `ViewTransition` returned from `startViewTransition`, as well as the `ActivatedRouteSnapshot` that the navigation is transitioning from and the new one that it is transitioning to. This callback can be used for any number of customizations. For example, you might want to skip transitions under certain conditions. We use this on the new angular.dev docs site: ```ts withViewTransitions({ onViewTransitionCreated: ({transition}) => { const router = inject(Router); const targetUrl = router.getCurrentNavigation()!.finalUrl!; // Skip the transition if the only thing // changing is the fragment and queryParams const config = { paths: 'exact', matrixParams: 'exact', fragment: 'ignored', queryParams: 'ignored', }; if (router.isActive(targetUrl, config)) { transition.skipTransition(); } }, }), ``` In this code snippet, we create a `UrlTree` from the `ActivatedRouteSnapshot` the navigation is going to. We then check with the Router to see if this `UrlTree` is already active, ignoring any differences in the fragment or query parameters. If it is already active, we call skipTransition which will skip the animation portion of the view transition. This is the case when clicking on an anchor link that will only scroll to another location in the same document. ## Examples from the Chrome explainer adapted to Angular We’ve recreated some of the great examples from the Chrome Team in Angular for you to explore. ### Transitioning elements don’t need to be the same DOM element * [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) ### Async DOM updates and waiting for content * [Chrome Explainer](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#async_dom_updates_and_waiting_for_content) > During this time, the page is frozen, so delays here should be kept to a minimum…in some cases it’s better to avoid the delay altogether, and use the content you already have. The view transition feature in the Angular router does not provide a way to delay the animation. For the moment, our stance is that it’s always better to use the content you have rather than making the page non-interactive for any additional amount of time. ### 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) * [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) ### Animating with Javascript * [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) ## Native View Transitions Alternative Animating the transition between routes can also be done with the `@angular/animations` package. The animation [triggers and transitions](/guide/animations/transition-and-triggers) can be derived from the router state, such as the current URL or `ActivatedRoute`. # Migrating away from Angular's Animations package Almost all the features supported by `@angular/animations` have simpler alternatives with native CSS. Consider removing the Angular Animations package from your application, as the package can contribute around 60 kilobytes to your JavaScript bundle. Native CSS animations offer superior performance, as they can benefit from hardware acceleration. Animations defined in the animations package lack that ability. 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="src/app/animations.ts" path="adev/src/content/examples/animations/src/app/animations.1.ts" visibleRegion="animation-example"/> #### With Native CSS <docs-code header="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="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="src/app/open-close.component.ts" path="adev/src/content/examples/animations/src/app/open-close.component.ts" visibleRegion="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="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="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 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="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="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="src/app/animations.css" path="adev/src/content/examples/animations/src/app/animations.css" visibleRegion="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 <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts"> <docs-code header="src/app/open-close.component.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.ts" /> <docs-code header="src/app/open-close.component.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.html" /> <docs-code header="src/app/open-close.component.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.component.css"/> </docs-code-multifile> ## Transition 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 <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts"> <docs-code header="src/app/auto-height.component.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.ts" /> <docs-code header="src/app/auto-height.component.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.html" /> <docs-code header="src/app/auto-height.component.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.component.css" /> </docs-code-multifile> 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 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. #### With Native CSS <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts"> <docs-code header="src/app/insert.component.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.component.ts" /> <docs-code header="src/app/insert.component.html" path="adev/src/content/examples/animations/src/app/native-css/insert.component.html" /> <docs-code header="src/app/insert.component.css" path="adev/src/content/examples/animations/src/app/native-css/insert.component.css" /> </docs-code-multifile> Leaving a view is slightly more complex. The element removal needs to be delayed until the exit animation is complete. This requires a bit of extra code in your component class to accomplish. #### With Native CSS <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts"> <docs-code header="src/app/remove.component.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.component.ts" /> <docs-code header="src/app/remove.component.html" path="adev/src/content/examples/animations/src/app/native-css/remove.component.html" /> <docs-code header="src/app/remove.component.css" path="adev/src/content/examples/animations/src/app/native-css/remove.component.css" /> </docs-code-multifile> ### 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 <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts"> <docs-code header="src/app/increment-decrement.component.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.ts" /> <docs-code header="src/app/increment-decrement.component.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.html" /> <docs-code header="src/app/increment-decrement.component.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.component.css" /> </docs-code-multifile> ### 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; } ``` 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 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. [`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 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 <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts"> <docs-code header="src/app/stagger.component.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.ts" /> <docs-code header="src/app/stagger.component.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.html" /> <docs-code header="src/app/stagger.component.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.component.css" /> </docs-code-multifile> ### 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. Removal animations will require additional code to add the event listener, as seen in the example above. #### With Animations Package< #### With Native CSS <docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts"> <docs-code header="src/app/reorder.component.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.ts" /> <docs-code header="src/app/reorder.component.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.html" /> <docs-code header="src/app/reorder.component.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.component.css" /> </docs-code-multifile> ## 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. 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. ## Route Transitions You can use view transitions to animate between routes. See the [Route Transition Animations Guide](guide/animations/route-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を有効にする The API for enabling Zoneless is currently in developer preview. The shape of the API and underlying behavior can change in patch versions. ```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 manuall add and remove a pending tasks: ```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, complets, 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. [フレームワークのパフォーマンスの向上](#fast-by-default)。 具体的なプロジェクト作業でこれらの目標をどのように達成する予定かについて、読み進めてください。 ## 最新のAngularを探る ロードマップからAngularの最新機能を使用して開発を始めましょう。このリストは、ロードマップから生まれた新機能の現在の状況を表しています。 ### 実験的に利用可能 * [Zoneless change detection](/guide/zoneless) * [Resource API](/guide/signals/resource) * [httpResource](/api/common/http/httpResource) ### 本番環境向け * [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バージョンを表します。 ## 新しいリリースの通知を受け取る 新しいリリースが利用可能になったときに通知を受け取るには、Twitterで [@angular](https://x.com/angular "@angular on X (formerly Twitter)") をフォローするか、[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へのすべての変更要求 (例: `POST`) にこのヘッダーを送信しますが、GET/HEADリクエストまたは絶対URLを持つリクエストには送信しません。 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 *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