Angular 由 Google 一支專責團隊維護，提供一整套豐富的工具、API 與函式庫，簡化並加速你的開發流程。Angular 為你提供穩固的平台，讓你建置快速、可靠的應用程式，無論團隊人數或程式碼庫規模如何成長，都能從容因應。Angular.dev 是 Angular 官方文件的所在地。

總覽使用 Angular 的實際樣貌

在你的瀏覽器中一步步跟著操作

透過線上入門範本快速上手 Angular，或在本機用終端機開始。 ## 線上遊玩如果你只想在瀏覽器裡玩玩 Angular，不想建立專案，可以使用我們的線上沙箱： ## 在本機建立新專案如果你要開始一個新專案，通常會想建立本機專案，這樣才能使用 Git 之類的工具。 ### 前置需求 - **Node.js**：[v22.22.3 或更新版本](/reference/versions) - **文字編輯器**：我們推薦 [Visual Studio Code](https://code.visualstudio.com/) - **終端機**：執行 [Angular CLI](/tools/cli) 指令時需要 - **開發工具**：為了改善你的開發流程，我們推薦 [Angular Language Service](/tools/language-service) ### 操作說明以下指南會帶你一步步建立本機 Angular 專案。 #### 安裝 Angular CLI 開啟終端機（如果你使用 [Visual Studio Code](https://code.visualstudio.com/)，可以開啟[整合式終端機](https://code.visualstudio.com/docs/editor/integrated-terminal)），然後執行下列指令： ```shell // npm npm install -g @angular/cli ``` ```shell // pnpm pnpm install -g @angular/cli ``` ```shell // yarn yarn global add @angular/cli ``` ```shell // bun bun install -g @angular/cli ``` 如果你在 Windows 或 Unix 上執行這個指令時遇到問題，請查看 [CLI 文件](/tools/cli/setup-local#install-the-angular-cli)了解更多資訊。 #### 建立新專案在你的終端機中，執行 CLI 指令 [`ng new`](cli/new)，並加上想要的專案名稱。在以下範例中，我們使用的範例專案名稱是 `my-first-angular-app`。 ```shell ng new ``` 畫面會呈現一些專案的設定選項讓你選擇。使用方向鍵與 Enter 鍵來瀏覽並選取你想要的選項。如果你沒有特別偏好，只要按下 Enter 鍵採用預設選項，即可繼續進行設定。在你選好設定選項、CLI 完成設定流程後，你應該會看到下列訊息： ```text ✔ Packages installed successfully. Successfully initialized git. ``` 到了這一步，你的專案已經可以在本機執行了！ #### 在本機執行你的新專案在終端機中，切換到你的新 Angular 專案。 ```shell cd my-first-angular-app ``` 此時你所有的相依套件都應該已安裝完成（你可以檢查專案中是否存在 `node_modules` 資料夾來確認），因此你可以執行下列指令來啟動專案： ```shell npm start ``` 如果一切順利，你應該會在終端機看到類似的確認訊息： ```text Watch mode enabled. Watching for file changes... NOTE: Raw file sizes do not reflect development server per-request transformations. ➜ Local: http://localhost:4200/ ➜ press h + enter to show help ``` 現在你可以前往 `Local` 顯示的路徑（例如 `http://localhost:4200`）查看你的應用程式。祝你寫程式愉快！🎉 ### 運用 AI 協助開發想在你偏好的 AI 驅動 IDE 中開始建置，請[查看 Angular 提示詞規則與最佳實務](/ai/develop-with-ai)。 ## 下一步現在你已經建立好 Angular 專案，可以在我們的[精華指南](/essentials)中進一步了解 Angular，或從深入指南裡挑選一個主題！ # Angular 程式碼樣式指南 ## 簡介本指南涵蓋 Angular 應用程式程式碼的一系列樣式慣例。這些建議並不是 Angular 運作所必需的，而是建立一套程式碼實務，促進整個 Angular 生態系的一致性。一致的實務讓分享程式碼與在專案之間移動變得更容易。本指南_不_涵蓋 TypeScript 或與 Angular 無關的一般程式碼實務。關於 TypeScript，請參閱 [Google 的 TypeScript 樣式指南](https://google.github.io/styleguide/tsguide.html)。 ### 有疑慮時，以一致性為優先只要你遇到這些規則與某個特定檔案的樣式相矛盾的情況，就優先維持該檔案內部的一致性。在單一檔案中混用不同的樣式慣例，造成的混亂會比偏離本指南的建議更大。 ## 命名 ### 檔案名稱中的單字以連字號分隔檔案名稱中的單字以連字號（`-`）分隔。例如，名為 `UserProfile` 的元件，其檔案名稱是 `user-profile.ts`。 ### 檔案的測試檔使用相同名稱，結尾加上 `.spec` 單元測試的檔案名稱以 `.spec.ts` 結尾。例如，`UserProfile` 元件的單元測試檔案名稱是 `user-profile.spec.ts`。 ### 讓檔案名稱對應其中的 TypeScript 識別碼檔案名稱通常應該描述檔案中程式碼的內容。當檔案包含 TypeScript 類別時，檔案名稱應該反映該類別名稱。例如，包含名為 `UserProfile` 元件的檔案，名稱是 `user-profile.ts`。若檔案包含不止一個主要的、可命名的識別碼，請選一個能描述檔案中程式碼共同主題的名稱。若檔案中的程式碼不屬於某個共同主題或功能領域，請考慮把程式碼拆到不同檔案。避免使用過於籠統的檔案名稱，例如 `helpers.ts`、`utils.ts` 或 `common.ts`。 ### 元件的 TypeScript、範本與樣式使用相同檔案名稱元件通常由一個 TypeScript 檔案、一個範本檔案與一個樣式檔案組成。這些檔案應該共用相同名稱，只有副檔名不同。例如，`UserProfile` 元件可以有 `user-profile.ts`、`user-profile.html` 與 `user-profile.css` 這些檔案。若元件有不止一個樣式檔案，請在名稱後加上額外的單字，描述該檔案特有的樣式。例如，`UserProfile` 可能有 `user-profile-settings.css` 與 `user-profile-subscription.css` 這兩個樣式檔案。 ## 專案結構 ### 應用程式的所有程式碼都放在名為 `src` 的目錄中你的所有 Angular UI 程式碼（TypeScript、HTML 與樣式）都應該放在名為 `src` 的目錄裡。與 UI 無關的程式碼，例如設定檔或指令碼，應該放在 `src` 目錄之外。這能讓不同 Angular 專案的根應用程式目錄保持一致，並在專案中清楚區隔 UI 程式碼與其他程式碼。 ### 在 `src` 正下方的 `main.ts` 中啟動你的應用程式啟動 Angular 應用程式的程式碼，也就是**啟動**（bootstrap），應該永遠放在名為 `main.ts` 的檔案中。這代表應用程式的主要進入點。 ### 把密切相關的檔案放在同一個目錄中 Angular 元件由一個 TypeScript 檔案組成，另外可以選擇性地加上範本與一或多個樣式檔案。你應該把這些檔案放在同一個目錄中。單元測試應該與被測程式碼放在同一個目錄。避免把不相關的測試收集到單一的 `tests` 目錄中。 ### 依功能領域組織你的專案請依應用程式的功能或目錄中程式碼的共同主題，把專案組織成子目錄。例如，電影院網站 MovieReel 的專案結構可能像這樣： ``` src/ ├─ movie-reel/ │ ├─ show-times/ │ │ ├─ film-calendar/ │ │ ├─ film-details/ │ ├─ reserve-tickets/ │ │ ├─ payment-info/ │ │ ├─ purchase-confirmation/ ``` 避免依目錄中程式碼的類型來建立子目錄。例如，避免建立 `components`、`directives` 與 `services` 這類目錄。避免把太多檔案放進同一個目錄，以至於變得難以閱讀或導覽。隨著目錄中的檔案數量增加，請考慮進一步拆成額外的子目錄。 ### 一個檔案一個概念讓原始檔案專注在單一_概念_上。具體對 Angular 類別而言，這通常意味著一個檔案放一個元件、指令或服務。不過，若你的類別相對小，而且作為單一概念的一部分彼此緊密相連，一個檔案包含不止一個元件或指令也沒關係。有疑慮時，選擇能帶來更小檔案的做法。 ## 依賴注入 ### 優先使用 `inject` 函式，而非建構函式參數注入請優先使用 [`inject`](/api/core/inject) 函式，而不是注入建構函式參數。[`inject`](/api/core/inject) 函式的運作方式與建構函式參數注入相同，但有幾個樣式上的優點： - [`inject`](/api/core/inject) 通常更易讀，尤其當一個類別注入許多相依性時。 - 在語法上，為注入的相依性加上註解更直接。 - [`inject`](/api/core/inject) 提供更好的型別推斷。 - 當以 ES2022+ 為目標、搭配 [`useDefineForClassFields`](https://www.typescriptlang.org/tsconfig/#useDefineForClassFields) 時，對於會讀取注入相依性的欄位，你可以避免把欄位宣告與初始化分開。 [你可以用自動化工具把既有程式碼重構為 `inject`](reference/migrations/inject-function)。 ## 元件與指令 ### 選擇元件選擇器 {#choosing-component-selectors} 詳情請參閱[元件指南中關於選擇元件選擇器的說明](guide/components/selectors#choosing-a-selector)。 ### 命名元件與指令的成員詳情請參閱元件指南中關於[命名輸入屬性](guide/components/inputs#choosing-input-names)與[命名輸出屬性](guide/components/outputs#choosing-event-names)的說明。 ### 選擇指令選擇器指令應該使用與你的元件相同的[應用程式專屬前綴](guide/components/selectors#selector-prefixes)。為指令使用屬性選擇器時，請使用 camelCase 屬性名稱。例如，若你的應用程式名為「MovieReel」，而你建立了一個為元素加上工具提示的指令，你可能會使用 `[mrTooltip]` 這個選擇器。 ### 把 Angular 專屬屬性放在方法之前元件與指令應該把 Angular 專屬屬性放在一起，通常靠近類別宣告的頂部。這包括注入的相依性、輸入、輸出與查詢。請先定義這些與其他屬性，再定義類別的方法。這種實務讓人更容易找到類別的範本 API 與相依性。 ### 讓元件與指令專注在呈現上你的元件與指令內的程式碼，通常應該與頁面上顯示的 UI 有關。對於本身就有意義、與 UI 解耦的程式碼，請優先重構到其他檔案。例如，你可以把表單驗證規則或資料轉換抽成獨立的函式或類別。 ### 避免在範本中放過於複雜的邏輯 Angular 範本的設計能容納[類似 JavaScript 的運算式](guide/templates/expression-syntax)。你應該善用這些運算式，直接在範本運算式中擷取相對簡單的邏輯。不過，當範本中的程式碼變得太複雜時，請把邏輯重構到 TypeScript 程式碼中（通常用 [computed](guide/signals#computed-signals)）。並沒有單一絕對的規則能判定什麼構成「複雜」。請用你最好的判斷。 ### 對只被元件範本使用的類別成員使用 `protected` 元件類別的公開成員，本質上定義了一個可透過依賴注入與[查詢](guide/components/queries)存取的公開 API。對於打算從元件範本讀取的任何成員，請優先使用 `protected` 存取層級。 ```ts @Component({ ..., template: `

`, }) export class UserProfile { firstName = input(); lastName = input(); // `fullName` is not part of the component's public API, but is used in the template. protected fullName = computed(() => `${this.firstName()} ${this.lastName()}`); } ``` ### 對不應該變更的屬性使用 `readonly` 把由 Angular 初始化的元件與指令屬性標記為 `readonly`。這包括由 `input`、`model`、`output` 與查詢初始化的屬性。readonly 存取修飾詞能確保 Angular 設定的值不會被覆寫。 ```ts @Component(/* ... */) export class UserProfile { readonly userId = input(); readonly userSaved = output(); readonly userName = model(); } ``` 對於使用裝飾器式 `@Input`、`@Output` 與查詢 API 的元件與指令，這項建議適用於輸出屬性與查詢，但不適用於輸入屬性。 ```ts @Component(/* ... */) export class UserProfile { @Output() readonly userSaved = new EventEmitter(); @ViewChildren(PaymentMethod) readonly paymentMethods?: QueryList; } ``` ### 優先使用 `class` 與 `style`，而非 `ngClass` 與 `ngStyle` 請優先使用 `class` 與 `style` 繫結，而不是使用 [`NgClass`](/api/common/NgClass) 與 [`NgStyle`](/api/common/NgStyle) 指令。 ```html {prefer}

``` ```html {avoid}

``` `class` 與 `style` 繫結都使用更直接的語法，與標準 HTML 屬性密切對齊。這讓你的範本更容易閱讀與理解，尤其對熟悉基本 HTML 的開發人員而言。此外，相較於內建的 `class` 與 `style` 繫結語法，`NgClass` 與 `NgStyle` 指令會帶來額外的效能成本。更多細節，請參閱[繫結指南](/guide/templates/binding#css-class-and-style-property-bindings) ### 依事件處理常式做的事來命名，而非觸發事件請優先依事件處理常式執行的動作來命名，而不是依觸發事件來命名： ```html {prefer} ``` ```html {avoid} ``` 使用這種有意義的名稱，讓人光看範本就能更容易看出事件在做什麼。對於鍵盤事件，你可以搭配具體的處理常式名稱，使用 Angular 的鍵盤事件修飾詞： ```html

```

有時候，事件處理邏輯特別長或複雜，使得宣告單一命名良好的處理常式不切實際。在這種情況下，退而使用像 'handleKeydown' 這樣的名稱，然後再依事件細節委派給更具體的行為，是可以的：

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

### 讓生命週期方法保持簡單

避免在 `ngOnInit` 之類的生命週期鉤子裡放冗長或複雜的邏輯。反之，請優先建立命名良好的方法來容納那些邏輯，然後_在你的生命週期鉤子中呼叫那些方法_。
生命週期鉤子的名稱描述的是它們_何時_執行，意味著裡面的程式碼沒有一個有意義的名稱能描述它在做什麼。

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

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

### 使用生命週期鉤子介面

Angular 為每個生命週期方法提供一個 TypeScript 介面。當你為類別加上生命週期鉤子時，請匯入並 `implement` 這些介面，以確保方法命名正確。

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

@Component(/* ... */)
export class UserProfile implements OnInit {
  // The `OnInit` interface ensures this method is named correctly.
  ngOnInit() {
    /* ... */
  }
}
```
元件是 Angular 應用程式的主要建構單位。每個元件代表一個較大網頁的一部分。把應用程式組織成元件，能為專案提供清晰的結構，將程式碼明確區分成各自獨立的部分，方便日後維護與擴展。

## 定義元件

每個元件都由幾個主要部分組成：

1. 一個 `@Component` [裝飾器](https://www.typescriptlang.org/docs/handbook/decorators.html)，其中包含 Angular 所使用的部分設定。
2. 一個 HTML 範本，決定要渲染到 DOM 中的內容。
3. 一個 [CSS 選擇器](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors)，定義元件在 HTML 中的使用方式。
4. 一個 TypeScript 類別，包含各種行為，例如處理使用者輸入，或向伺服器發出請求。

以下是一個經過簡化的 `UserProfile` 元件範例。

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

`@Component` 裝飾器也可以選擇性地接受 `styles` 屬性，放入你想套用到範本的任何 CSS：

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

### 將 HTML 與 CSS 分開放在獨立檔案中

你可以使用 `templateUrl` 和 `styleUrl`，把元件的 HTML 與 CSS 定義在個別檔案中：

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

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

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

## 使用元件 {#using-components}

你會把多個元件組合在一起，來建構應用程式。舉例來說，如果你要建立一個使用者個人檔案頁面，你可能會像這樣把頁面拆成幾個元件：

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

在這個例子中，`UserProfile` 元件使用了其他幾個元件，組合成最終的頁面。

要匯入並使用一個元件，你需要：

1. 在你元件的 TypeScript 檔案中，為要使用的元件加上一個 `import` 陳述式。
2. 在你的 `@Component` 裝飾器中，把要使用的元件加到 `imports` 陣列裡。
3. 在你元件的範本中，加上一個與要使用的元件之選擇器相符的元素。

以下範例展示 `UserProfile` 元件如何匯入 `ProfilePhoto` 元件：

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

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

TIP: 想更深入了解 Angular 元件嗎？請參閱[元件深入指南](guide/components)，取得完整說明。

## 下一步

現在你已經了解元件在 Angular 中的運作方式，接著來學習如何在應用程式中加入並管理動態資料。
# 元件選擇器

TIP: 本指南假設你已讀過[基礎指南](essentials)。如果你是 Angular 新手，請先讀該指南。

每個元件都會定義一個 [CSS 選擇器](https://developer.mozilla.org/docs/Web/CSS/CSS_selectors)，決定該元件的使用方式：

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

你透過在_其他_元件的範本中建立相符的 HTML 元素來使用元件：

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

**Angular 會在編譯時期靜態比對選擇器**。在執行時期更動 DOM，無論是透過 Angular 繫結還是 DOM API，都不會影響所渲染的元件。

**一個元素恰好只能比對一個元件選擇器**。如果有多個元件選擇器比對到同一個元素，Angular 會回報錯誤。

**元件選擇器區分大小寫**。

## 選擇器的類型

Angular 在元件選擇器中，支援[基本 CSS 選擇器類型](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors)的一個有限子集：

| **選擇器類型**     | **說明**                                                                                                 | **範例**                      |
| ------------------ | --------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| 類型選擇器         | 依據元素的 HTML 標籤名稱或節點名稱來比對元素。                                                    | `profile-photo`               |
| 屬性選擇器         | 依據元素是否具有某個 HTML 屬性，並可選擇性地比對該屬性的精確值來比對元素。 | `[dropzone]` `[type="reset"]` |
| 類別選擇器         | 依據元素是否具有某個 CSS 類別來比對元素。                                                          | `.menu-item`                  |

對於屬性值，Angular 支援使用等號（`=`）運算子比對精確的屬性值。Angular 不支援其他屬性值運算子。

Angular 元件選擇器不支援組合子，包括[後代組合子](https://developer.mozilla.org/docs/Web/CSS/Descendant_combinator)或[子組合子](https://developer.mozilla.org/docs/Web/CSS/Child_combinator)。

Angular 元件選擇器不支援指定[命名空間](https://developer.mozilla.org/docs/Web/SVG/Namespaces_Crash_Course)。

### `:not` 偽類別

Angular 支援 [`:not` 偽類別](https://developer.mozilla.org/docs/Web/CSS/:not)。你可以將這個偽類別附加到任何其他選擇器之後，以縮小元件選擇器的比對範圍。例如，你可以定義一個 `[dropzone]` 屬性選擇器，並防止它比對到 `textarea` 元素：

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

Angular 不支援在元件選擇器中使用任何其他偽類別或偽元素。

### 組合選擇器

你可以透過串連多個選擇器來組合它們。例如，你可以比對指定了 `type="reset"` 的 `<button>` 元素：

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

你也可以使用逗號分隔的清單來定義多個選擇器：

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

Angular 會為比對到清單中_任何_選擇器的每個元素建立一個元件。

## 如何選擇選擇器 {#choosing-a-selector}

絕大多數元件應使用自訂元素名稱作為其選擇器。所有自訂元素名稱都應包含連字號，如 [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)。

### 選擇器前綴 {#selector-prefixes}

Angular 團隊建議為專案內定義的所有自訂元件，使用簡短且一致的前綴。例如，如果你要用 Angular 打造 YouTube，你可能會為元件加上 `yt-` 前綴，像是 `yt-menu`、`yt-player` 等元件。像這樣為選擇器加上命名空間，能讓人一眼就看出特定元件的來源。依預設，Angular CLI 使用 `app-`。

IMPORTANT: Angular 將 `ng` 選擇器前綴保留給它自己的框架 API。切勿將 `ng` 作為你自己自訂元件的選擇器前綴。

### 何時使用屬性選擇器

當你想在標準原生元素上建立元件時，應考慮使用屬性選擇器。例如，如果你想建立一個自訂按鈕元件，你可以利用標準的 `<button>` 元素，使用屬性選擇器：

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

這種做法可讓元件的使用者直接使用該元素的所有標準 API，無需額外工作。這對 `aria-label` 等 ARIA 屬性特別有價值。

當 Angular 遇到不符合任何可用元件的自訂屬性時，不會回報錯誤。使用具有屬性選擇器的元件時，使用者可能忘記匯入該元件或其 NgModule，導致元件無法渲染。更多資訊請參閱[匯入與使用元件](guide/components#imports-in-the-component-decorator)。

定義屬性選擇器的元件，應使用小寫、以連字號分隔（dash-case）的屬性。你可以遵循上面說明的相同前綴建議。
# 元件樣式

TIP: 本指南假設你已讀過[基礎指南](essentials)。如果你是 Angular 新手，請先讀該指南。

元件可以選擇性地包含套用到該元件 DOM 的 CSS 樣式：

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

你也可以選擇將樣式寫在獨立的檔案中：

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

當 Angular 編譯你的元件時，這些樣式會隨該元件的 JavaScript 輸出一併產生。這表示元件樣式會參與 JavaScript 模組系統。當你渲染 Angular 元件時，框架會自動包含其關聯的樣式，即使是延遲載入的元件也一樣。

Angular 可搭配任何輸出 CSS 的工具，包括 [Sass](https://sass-lang.com)、[Less](https://lesscss.org) 與 [Stylus](https://stylus-lang.com)。

## 樣式作用域 {#style-scoping}

每個元件都有一個**檢視封裝**設定，決定框架如何界定元件樣式的作用域。共有四種檢視封裝模式：`Emulated`、`ShadowDom`、`ExperimentalIsolatedShadowDom` 與 `None`。你可以在 `@Component` 裝飾器中指定模式：

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

### ViewEncapsulation.Emulated

依預設，Angular 使用模擬封裝，讓元件的樣式只套用到在該元件範本中定義的元素。在此模式下，框架會為每個元件實例產生一個唯一的 HTML 屬性，將該屬性加到元件範本中的元素上，並將該屬性插入你在元件樣式中定義的 CSS 選擇器中。

這種模式可確保元件的樣式不會外洩而影響其他元件。然而，在元件之外定義的全域樣式，仍可能影響採用模擬封裝之元件內的元素。

在模擬模式下，Angular 支援 [`:host`](https://developer.mozilla.org/docs/Web/CSS/:host) 偽類別。雖然 [`:host-context()`](https://developer.mozilla.org/docs/Web/CSS/:host-context) 偽類別在現代瀏覽器中已被棄用，Angular 的編譯器仍完整支援它。這兩個偽類別都可以在不依賴原生 [Shadow DOM](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM) 的情況下使用。在編譯期間，框架會將這些偽類別轉換為屬性，因此在執行時期並不遵循這些原生偽類別的規則（例如瀏覽器相容性、特異性）。Angular 的模擬封裝模式不支援任何其他與 Shadow DOM 相關的偽類別，例如 `::shadow` 或 `::part`。

#### `::ng-deep`

Angular 的模擬封裝模式支援一個自訂偽類別 `::ng-deep`。**Angular 團隊強烈不建議新程式碼使用 `::ng-deep`**。這些 API 僅為向後相容而保留。

當選擇器包含 `::ng-deep` 時，Angular 會在選擇器的該位置之後，停止套用檢視封裝邊界。選擇器中位於 `::ng-deep` 之後的任何部分，都可以比對到元件範本之外的元素。

例如：

- 像 `p a` 這樣的 CSS 規則選擇器，在模擬封裝下，會比對到作為 `<p>` 元素後代的 `<a>` 元素，兩者都位於元件自身的範本內。

- 像 `::ng-deep p a` 這樣的選擇器，會比對到應用程式中任何位置、作為應用程式中任何 `<p>` 元素後代的 `<a>` 元素。

這實際上讓它表現得像全域樣式。

- 在 `p ::ng-deep a` 中，Angular 要求 `<p>` 元素必須來自元件自身的範本，但 `<a>` 元素可以位於應用程式中的任何位置。

因此，實際上，`<a>` 元素可能位於元件的範本中，或其任何投射內容或子內容中。

- 使用 `:host ::ng-deep p a` 時，`<a>` 與 `<p>` 元素都必須是元件 host 元素的後代。

它們可以來自元件的範本或其子元件的檢視，但不能來自應用程式中的其他位置。

### ViewEncapsulation.ShadowDom

此模式透過使用 [Web 標準的 Shadow DOM API](https://developer.mozilla.org/docs/Web/Web_Components/Using_shadow_DOM)，將樣式的作用域限定在元件內。啟用此模式時，Angular 會將一個 shadow root 附加到元件的 host 元素上，並將元件的範本與樣式渲染至對應的 shadow tree 中。

shadow tree 內的樣式無法影響該 shadow tree 之外的元素。

然而，啟用 `ShadowDom` 封裝的影響不只是樣式作用域。將元件渲染在 shadow tree 中，會影響事件傳播、與 [`<slot>` API](https://developer.mozilla.org/docs/Web/Web_Components/Using_templates_and_slots) 的互動，以及瀏覽器開發者工具顯示元素的方式。在你的應用程式中啟用此選項之前，請務必充分了解使用 Shadow DOM 的完整影響。

### ViewEncapsulation.ExperimentalIsolatedShadowDom

行為與上述相同，但此模式嚴格保證_只有_該元件的樣式會套用到元件範本中的元素。全域樣式無法影響 shadow tree 中的元素，shadow tree 內的樣式也無法影響該 shadow tree 之外的元素。

### ViewEncapsulation.None

此模式會停用元件的所有樣式封裝。與元件關聯的任何樣式都會表現得像全域樣式。

NOTE: 在 `Emulated` 與 `ShadowDom` 模式下，Angular 並不 100% 保證你的元件樣式永遠會覆寫來自外部的樣式。在發生衝突時，會假設這些樣式與你的元件樣式具有相同的特異性。

## 在範本中定義樣式 {#defining-styles-in-templates}

你可以在元件的範本中使用 `<style>` 元素來定義額外的樣式。元件的檢視封裝模式會套用到以這種方式定義的樣式。

Angular 不支援在 style 元素內使用繫結。

## 參照外部樣式檔案 {#referencing-external-style-files}

元件範本可以使用 [`<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 將這些參照視為_外部_樣式。外部樣式不受模擬檢視封裝的影響。

## 為 CSS 自訂屬性加上命名空間 {#namespacing-css-custom-properties}

Angular 可以為你的元件樣式所宣告與讀取的 CSS 自訂屬性（也稱為 CSS 變數）加上前綴。自訂屬性會沿著 DOM 樹向下繼承，因此當你應用程式之外的某個東西在祖先元素上定義了如 `--primary-color` 這樣的自訂屬性時，你的元件會讀到該值。當你的應用程式與另一個應用程式、或你無法控制的標記共用同一個頁面時，這一點就很重要。在你要求之前，Angular 不會為自訂屬性加上命名空間，而擁有自己頁面的應用程式不需要命名空間。

若要將你元件樣式中自訂屬性的作用域限定在你的應用程式，請將 [`provideCssVarNamespacing`](api/platform-browser/provideCssVarNamespacing) 加到應用程式的 providers 中。它會使用應用程式的 [`APP_ID`](api/core/APP_ID) 作為命名空間：

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

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

Angular 會為你元件樣式中的自訂屬性加上該命名空間，後面接著一個底線，因此 `--primary-color` 會變成 `--my-app_primary-color`。這個前綴會套用到宣告、`var()` 參照、`@property` 規則，以及像 `[style.--primary-color]` 這樣的樣式繫結，包括元件在其 `host` 物件中宣告的樣式繫結。

除非你另行設定，`APP_ID` 的值為 `ng`，因此請為頁面上的每個應用程式指定各自的 `APP_ID`。否則，這些應用程式會共用同一個前綴，再次發生衝突。若要使用與應用程式 id 不同的命名空間，請將它傳給 `provideCssVarNamespacing`。Angular 會自行附加底線：`provideCssVarNamespacing('my-app_')` 會產生 `--my-app__primary-color`。

Angular 會為它編譯進元件的樣式加上命名空間：元件的 `styles` 與 `styleUrl`、你在範本的 [`<style>` 元素](#defining-styles-in-templates) 中撰寫的樣式、其範本以相對路徑 `<link rel="stylesheet">` 參照的樣式表，以及使用 `ViewEncapsulation.None` 之元件的樣式。Angular 不會為瀏覽器在執行時期載入的樣式表加上命名空間，例如你的建置設定所列出的全域樣式表，或你的建置未內嵌的[外部樣式](#referencing-external-style-files)。

命名空間會套用到 Angular 所編譯的每個元件，包括你所安裝之程式庫的元件。當程式庫的樣式讀取由全域樣式表定義的自訂屬性（例如佈景主題的屬性）時，該參照就不再相符，瀏覽器會使用 `var()` 的備援值（如果有的話），否則使用[該屬性的繼承值或初始值](https://www.w3.org/TR/css-variables-1/#invalid-variables)，而且不會有任何錯誤回報。在為現有應用程式啟用命名空間之前，請先檢視在你的全域樣式表與元件之間跨越使用的自訂屬性。

IMPORTANT: Angular 只會在其所編譯的樣式與繫結中重寫自訂屬性名稱。其他所有地方都保留你所寫的名稱，而且不會回報不一致的情況。

Angular 不會在以下地方重寫名稱：

- 靜態 style 屬性，例如 `style="--primary-color: red"`，包括元件 `host` 物件中的 `style` 項目。
- 物件與字串樣式繫結，例如 `[style]="{'--primary-color': color}"`、`[style]="'--primary-color: red'"` 與 `ngStyle`，包括元件 `host` 物件中的 `[style]` 項目。
- 繫結值內部的自訂屬性名稱，例如 `[style.border-color]="'var(--primary-color)'"`。
- 對 `Renderer2.setStyle` 的呼叫。

這些都會產生一個你的已命名空間樣式不再讀取的屬性。請自行為這些名稱加上命名空間，方法如[在 TypeScript 中使用已命名空間的屬性](#using-namespaced-properties-in-typescript)所述。

### 退出命名空間處理

若要宣告或讀取 Angular 不會加上命名空間的自訂屬性，例如在全域樣式表中定義的屬性，請在其名稱前加上 `--global--`。Angular 會移除 `--global`，並保留其後的 `--` 與名稱的其餘部分不變：

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

在 `global` 之後要寫兩個連字號。單一個連字號，例如 `--global-brand-color`，並不會退出命名空間處理，Angular 會像處理任何其他名稱一樣為該名稱加上命名空間。請避免使用以 `--global-` 開頭、其後不是第二個連字號的名稱；未來的重大版本預計會在建置時拒絕這類名稱。Angular 會在每個應用程式中移除 `--global`，包括從未設定命名空間的應用程式。

### 在 TypeScript 中使用已命名空間的屬性 {#using-namespaced-properties-in-typescript}

優先使用像 `[style.--primary-color]` 這樣的樣式繫結，Angular 會為你加上命名空間。當你改透過 DOM API 操作時，請將你在樣式中所寫的名稱（包括開頭的 `--`）傳給 [`CssVarNamespacer`](api/platform-browser/CssVarNamespacer)：

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

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

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

對於你以 `--global--` 宣告的屬性，請使用其純名稱，因為 Angular 永遠不會為它們加上命名空間。對於其他所有屬性，當應用程式未設定命名空間時，`namespace` 會原封不動地傳回該名稱，因此程式庫可以為其自身樣式所宣告的自訂屬性呼叫它。
# 以輸入屬性接受資料

TIP: 本指南假設你已讀過[基礎指南](essentials)。如果你是 Angular 新手，請先閱讀該指南。如果你熟悉其他網頁框架，輸入屬性類似 _props_。

當你使用某個元件時，通常會想傳一些資料給它。元件透過宣告**輸入**，來指明它接受的資料：

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

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

這讓你可以在範本中繫結到該屬性：

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

如果輸入有預設值，TypeScript 會從預設值推斷其型別：

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

你可以為 `input` 函式指定泛型參數，明確宣告輸入的型別。

如果沒有預設值的輸入未被設定，其值為 `undefined`：

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

**Angular 在編譯時期靜態記錄輸入**。輸入無法在執行時期加入或移除。

`input` 函式對 Angular 編譯器有特殊意義。**你只能在元件與指令的屬性初始化器中呼叫 `input`**。

擴充元件類別時，**輸入會由子類別繼承**。

**輸入名稱區分大小寫**。

## 讀取輸入

`input` 函式會回傳一個 `InputSignal`。你可以呼叫這個訊號來讀取其值：

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

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

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

由 `input` 函式建立的訊號是唯讀的。

## 必要輸入 {#required-inputs}

你可以呼叫 `input.required` 而非 `input`，來宣告某個輸入是 `required`：

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

Angular 會強制規定，在範本中使用元件時，必要輸入_必須_被設定。如果你嘗試使用某個元件，卻沒有指明它的所有必要輸入，Angular 會在建置時期回報錯誤。

必要輸入不會自動在回傳的 `InputSignal` 泛型參數中包含 `undefined`。

## 設定輸入

`input` 函式接受設定物件作為第二個參數，讓你可以變更輸入的運作方式。

### 輸入轉換 {#input-transforms}

你可以指定 `transform` 函式，在 Angular 設定輸入時變更其值。

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

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

```html
<custom-slider [label]="systemVolume" />
```

在上面的範例中，只要 `systemVolume` 的值變更，Angular 就會執行 `trimString`，並將 `label` 設為其結果。

輸入轉換最常見的應用情境，是在範本中接受更廣泛的值型別，通常包括 `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`。

#### 內建轉換 {#built-in-transformations}

Angular 為兩個最常見的情境提供內建轉換函式：將值強制轉換為布林值與數字。

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

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

`booleanAttribute` 模仿標準 HTML [布林屬性](https://developer.mozilla.org/docs/Glossary/Boolean/HTML)的行為，也就是屬性的_存在_即表示「true」值。不過，Angular 的 `booleanAttribute` 會將字面字串 `"false"` 視為布林值 `false`。

`numberAttribute` 會嘗試將給定的值剖析為數字，剖析失敗時產生 `NaN`。

### 輸入別名 {#input-aliases}

你可以指定 `alias` 選項，變更輸入在範本中的名稱。

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

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

這個別名不影響該屬性在 TypeScript 程式碼中的使用方式。

雖然一般來說應避免為元件輸入取別名，這個功能在重新命名屬性時保留原名稱別名，或避免與原生 DOM 元素屬性名稱衝突時，會很有用。

## 模型輸入 {#model-inputs}

**模型輸入**是輸入的一種特殊類型，讓元件能將新值傳播回其父元件。

建立元件時，你可以比照建立標準輸入的方式，定義模型輸入。

兩種類型的輸入都允許他人將值繫結到屬性中。不過，**模型輸入允許元件作者將值寫入屬性**。如果該屬性以雙向繫結方式繫結，新值會傳播到該繫結。

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

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

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

在上面的範例中，`CustomSlider` 可以將值寫入它的 `value` 模型輸入，這些值接著會傳播回 `MediaControls` 中的 `volume` 訊號。這個繫結讓 `value` 與 `volume` 的值保持同步。請注意，這個繫結傳遞的是 `volume` 訊號執行個體，而不是訊號的_值_。

在其他方面，模型輸入的運作方式與標準輸入類似。你可以呼叫訊號函式來讀取其值，包括在 `computed` 與 `effect` 這類[反應式情境](guide/signals#reactive-contexts)中。

關於範本中雙向繫結的更多細節，請參閱[雙向繫結](guide/templates/two-way-binding)。

### 與純屬性進行雙向繫結

你可以將純 JavaScript 屬性繫結到模型輸入。

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

在上面的範例中，`CustomSlider` 可以將值寫入它的 `value` 模型輸入，這些值接著會傳播回 `MediaControls` 中的 `volume` 屬性。這個繫結讓 `value` 與 `volume` 的值保持同步。

### 隱含的 `change` 事件

當你在元件或指令中宣告模型輸入時，Angular 會自動為該模型建立對應的[輸出](guide/components/outputs)。輸出的名稱是模型輸入的名稱加上「Change」後綴。

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

每當你透過呼叫模型輸入的 `set` 或 `update` 方法將新值寫入它時，Angular 就會發出這個變更事件。

關於輸出的更多細節，請參閱[以輸出建立自訂事件](guide/components/outputs)。

### 自訂模型輸入 {#customizing-model-inputs}

你可以比照標準輸入的方式，將模型輸入標記為[必要](#required-inputs)，或為它提供[別名](#input-aliases)。

模型輸入不支援輸入轉換。

### 何時使用模型輸入

當你希望元件支援雙向繫結時，請使用模型輸入。當元件的存在目的是依據使用者互動修改某個值時，這通常很合適。最常見的情況是，自訂表單控制項，例如日期選擇器或 combobox，應該以模型輸入作為其主要值。

## 選擇輸入名稱 {#choosing-input-names}

應避免選擇會與 `HTMLElement` 等 DOM 元素屬性衝突的輸入名稱。名稱衝突會讓人混淆被繫結的屬性究竟屬於元件還是 DOM 元素。

應避免像元件選擇器那樣，為元件輸入加上前綴。由於一個給定的元素只能承載一個元件，任何自訂屬性都可以假定屬於該元件。

## 以 `@Input` 裝飾器宣告輸入

TIP: 雖然 Angular 團隊建議新專案使用以訊號為基礎的 `input` 函式，原本以裝飾器為基礎的 `@Input` API 仍受到完整支援。

你也可以將 `@Input` 裝飾器加到屬性上，來宣告元件輸入：

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

無論是以訊號為基礎還是以裝飾器為基礎的輸入，繫結到輸入的方式都相同：

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

### 自訂以裝飾器為基礎的輸入

`@Input` 裝飾器接受設定物件，讓你可以變更輸入的運作方式。

#### 必要輸入 {#required-inputs-decorator}

你可以指定 `required` 選項，強制規定某個輸入必須一律有值。

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

如果你嘗試使用某個元件，卻沒有指明它的所有必要輸入，Angular 會在建置時期回報錯誤。

#### 輸入轉換 {#input-transforms-decorator}

你可以指定 `transform` 函式，在 Angular 設定輸入時變更其值。這個轉換函式的運作方式，與上述以訊號為基礎的輸入轉換函式完全相同。

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

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

#### 輸入別名 {#input-aliases-decorator}

你可以指定 `alias` 選項，變更輸入在範本中的名稱。

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

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

`@Input` 裝飾器也接受以別名作為第一個參數，來取代設定物件。

輸入別名的運作方式與上述以訊號為基礎的輸入相同。

### 帶有 getter 與 setter 的輸入

使用以裝飾器為基礎的輸入時，以 getter 與 setter 實作的屬性也可以是輸入：

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

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

private internalValue = 0;
}
```

你甚至可以只定義公開的 setter，來建立_唯寫_輸入：

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

private internalValue = 0;
}
```

如果可以，**請優先使用輸入轉換，而非 getter 與 setter**。

應避免複雜或成本高昂的 getter 與 setter。Angular 可能多次呼叫輸入的 setter，如果 setter 執行任何成本高昂的行為（例如 DOM 操作），可能對應用程式效能造成負面影響。

## 在 `@Component` 裝飾器中指明輸入

除了 `@Input` 裝飾器之外，你也可以用 `@Component` 裝飾器中的 `inputs` 屬性，來指明元件的輸入。當元件從基底類別繼承某個屬性時，這會很有用：

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

你也可以在 `inputs` 清單的字串中，在冒號後面指明輸入別名：

```ts
{highlight:[4]}
// `CustomSlider` inherits the `disabled` property from `BaseSlider`.
@Component({
  ...,
  inputs: ['disabled: sliderDisabled'],
})
export class CustomSlider extends BaseSlider { }
```
# 使用 outputs 的自訂事件

TIP: 本指南假設你已讀過[基礎指南](essentials)。如果你是 Angular 新手，請先讀該指南。

Angular 元件可以透過將屬性指派給 `output` 函式來定義自訂事件：

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

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

`output` 函式會傳回一個 `OutputEmitterRef`。你可以呼叫 `OutputEmitterRef` 上的 `emit` 方法來發出事件：

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

Angular 將以 `output` 函式初始化的屬性稱為 **outputs**。你可以使用 outputs 來引發自訂事件，類似 `click` 等原生瀏覽器事件。

**Angular 自訂事件不會沿 DOM 向上冒泡**。

**Output 名稱區分大小寫**。

擴充元件類別時，**outputs 會由子類別繼承**。

`output` 函式對 Angular 編譯器具有特殊意義。**你只能在元件與指令的屬性初始化器中呼叫 `output`**。

## 發出事件資料

呼叫 `emit` 時，你可以傳遞事件資料：

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

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

在範本中定義事件監聽器時，你可以從 `$event` 變數存取事件資料：

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

在父元件中接收事件資料：

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

```

## 自訂 output 名稱 {#customizing-output-names}

`output` 函式接受一個參數，可讓你為範本中的事件指定不同的名稱：

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

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

這個別名不會影響該屬性在 TypeScript 程式碼中的使用方式。

雖然一般來說應避免為元件的 outputs 取別名，但這項功能在重新命名屬性時保留原始名稱的別名，或避免與原生 DOM 事件名稱衝突時非常有用。

## 以程式方式訂閱 outputs {#subscribing-to-outputs-programmatically}

動態建立元件時，你可以從元件實例以程式方式訂閱 output 事件。`OutputRef` 型別包含一個 `subscribe` 方法：

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

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

當 Angular 銷毀具有訂閱者的元件時，會自動清理事件訂閱。或者，你也可以手動取消訂閱事件。`subscribe` 函式會傳回一個 `OutputRefSubscription`，其中有一個 `unsubscribe` 方法：

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

// ...

eventSubscription.unsubscribe();
```

## 選擇事件名稱 {#choosing-event-names}

避免選擇會與 `HTMLElement` 等 DOM 元素上的事件衝突的 output 名稱。名稱衝突會讓人混淆所繫結的屬性究竟屬於元件還是 DOM 元素。

避免像為元件選擇器那樣，為元件 outputs 加上前綴。由於一個元素只能承載一個元件，任何自訂屬性都可以假定屬於該元件。

一律使用 [camelCase](https://en.wikipedia.org/wiki/Camel_case) 作為 output 名稱。避免在 output 名稱前加上「on」前綴。

## 搭配 RxJS 使用 outputs

關於 outputs 與 RxJS 之間互通性的詳情，請參閱 [RxJS 與元件及指令 outputs 的互通](ecosystem/rxjs-interop/output-interop)。

## 使用 `@Output` 裝飾器宣告 outputs {#declaring-outputs-with-the-output-decorator}

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` 裝飾器中指定 outputs

除了 `@Output` 裝飾器之外，你也可以使用 `@Component` 裝飾器中的 `outputs` 屬性來指定元件的 outputs。當元件從基底類別繼承屬性時，這非常有用：

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

你也可以在 `outputs` 清單中指定 output 別名，方法是在字串中以冒號分隔，並在冒號後寫上別名：

```ts
// `CustomSlider` inherits the `valueChanged` property from `BaseSlider`.
@Component({
  /*...*/
  outputs: ['valueChanged: volumeChanged'],
})
export class CustomSlider extends BaseSlider {}
```
# 使用 ng-content 進行內容投影

TIP: 本指南假設你已讀過[基礎指南](essentials)。如果你是 Angular 新手，請先閱讀該指南。

你經常需要建立可作為不同類型內容容器的元件。例如，你可能想建立一個自訂卡片元件：

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

**你可以使用 `<ng-content>` 元素作為佔位符，標示內容應該放置的位置**：

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

TIP: `<ng-content>` 的運作方式類似[原生的 `<slot>` 元素](https://developer.mozilla.org/docs/Web/HTML/Element/slot)，但帶有一些 Angular 專屬功能。

當你使用帶有 `<ng-content>` 的元件時，元件宿主元素的任何子元素都會在該 `<ng-content>` 的位置算繪，也就是被**投影**過去：

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

```html

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

```html

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

Angular 將以這種方式傳給元件的任何子元素稱為該元件的**內容**。這與元件的**檢視**不同，檢視指的是元件範本中定義的元素。

**`<ng-content>` 元素既不是元件，也不是 DOM 元素**。它是一個特殊的佔位符，用來告訴 Angular 應該在哪裡算繪內容。Angular 的編譯器會在建置時期處理所有 `<ng-content>` 元素。你無法在執行時期插入、移除或修改 `<ng-content>`。你也無法為 `<ng-content>` 加上指令、樣式或任意屬性。

IMPORTANT: 你不應該用 `@if`、`@for` 或 `@switch` 條件式地包含 `<ng-content>`。即使該 `<ng-content>` 佔位符被隱藏，Angular 仍會一律具現化並為算繪到 `<ng-content>` 佔位符的內容建立 DOM 節點。如需條件式算繪元件內容，請參閱[範本片段](api/core/ng-template)。

## 多個內容佔位符

Angular 支援依據 CSS 選擇器，將多個不同的元素投影到不同的 `<ng-content>` 佔位符。擴充上面的卡片範例，你可以使用 `select` 屬性，建立卡片標題與卡片主體兩個佔位符：

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

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

```typescript

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

```typescript

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

```html

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

`<ng-content>` 佔位符支援的 CSS 選擇器，與[元件選擇器](guide/components/selectors)相同。

IMPORTANT: 若使用屬性或類別選擇器，必須以靜態方式設定，例如 `class="within"`。
動態繫結如 `[class.within]="isWithin()"` 不會被 `select` 選擇器看見。

如果你同時包含一個或多個帶有 `select` 屬性的 `<ng-content>` 佔位符，以及一個不帶 `select` 屬性的 `<ng-content>` 佔位符，後者會擷取所有未符合任何 `select` 屬性的元素：

```html

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

```html

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

```html

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

如果元件沒有包含不帶 `select` 屬性的 `<ng-content>` 佔位符，任何未符合該元件佔位符的元素都不會算繪到 DOM 中。

## 備用內容

如果元件沒有任何相符的子內容，Angular 可以為元件的 `<ng-content>` 佔位符顯示_備用內容_。你可以將子內容直接加到 `<ng-content>` 元素本身，來指定備用內容。

```html

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

```html

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

```html

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

## 為投影內容加上別名 {#aliasing-content-for-projection}

Angular 支援一個特殊屬性 `ngProjectAs`，讓你可以在任何元素上指定 CSS 選擇器。當帶有 `ngProjectAs` 的元素要與 `<ng-content>` 佔位符比對時，Angular 會改以 `ngProjectAs` 的值來比對，而不是元素本身的身分：

```html

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

```html

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

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

```html

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

`ngProjectAs` 只支援靜態值，無法繫結到動態運算式。

## 注意事項

### 投影內容存活在父元件的檢視中

即使投影內容是_算繪_在接收元件的內部，它仍然屬於宣告它的元件所有。Angular 將它追蹤為父元件檢視的一部分，這有幾個值得了解的副作用。

**變更偵測**：投影內容會在_父元件_執行變更偵測時被檢查。如果接收元件使用 `OnPush`，Angular 可以略過檢查該元件自己的範本，但不會略過投影內容，因為那屬於父元件。

```html

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

**依賴注入**：投影內容的依賴來自父元件的注入器，而不是接收元件的 `viewProviders`。詳情請參閱[提供者與 viewProviders](guide/di/hierarchical-dependency-injection)。

### 有些函式庫元件不支援投影子元素

某些元件，例如選單、頁籤、清單，會使用 `ContentChildren` 來尋找它們的子元素，並接上鍵盤導覽、焦點管理或 ARIA 屬性等行為。它們的撰寫方式假設自己直接擁有子元素，因此將外部內容投影進去，往往會以微妙的方式弄壞功能。

例如，將 `<mat-menu-item>` 元素多包一層再投影到 `<mat-menu>` 中，可能會無聲地弄壞鍵盤導覽與螢幕閱讀器支援。查詢仍能找到這些項目，但當項目來自不同的檢視情境時，讓它們具備互動性的內部設定可能無法正確運作。

如果某個函式庫元件會管理其子元素的行為，在使用內容投影之前，請先查閱它的文件，該元件可能不支援內容投影。
# 元件生命週期

TIP: 本指南假設你已讀過[基礎指南](essentials)。如果你是 Angular 新手，請先讀該指南。

元件的**生命週期**，是從元件建立到銷毀之間所經歷的一連串步驟。每個步驟代表 Angular 渲染元件、並隨時間檢查其更新的不同環節。

你可以在元件中實作**生命週期鉤子**，在這些步驟期間執行程式碼。與特定元件實例相關的生命週期鉤子，會以你元件類別上的方法來實作；與整個 Angular 應用程式相關的生命週期鉤子，則以接受回呼的函式形式實作。

元件的生命週期與 Angular 如何隨時間檢查元件的變更緊密相關。為了理解這個生命週期，你只需要知道：Angular 會由上而下走訪你的應用程式樹，檢查範本繫結是否有變更。以下說明的生命週期鉤子，會在 Angular 執行這趟走訪時執行。這趟走訪恰好造訪每個元件一次，因此你應避免在這個過程進行到一半時再更動狀態。

## 摘要

<div class="docs-table docs-scroll-track-transparent">
  <table>
    <tr>
      <td><strong>階段</strong></td>
      <td><strong>方法</strong></td>
      <td><strong>摘要</strong></td>
    </tr>
    <tr>
      <td>建立</td>
      <td><code>constructor</code></td>
      <td>
        <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Classes/constructor" target="_blank">
          標準 JavaScript 類別建構子
        </a>。在 Angular 具現化元件時執行。
      </td>
    </tr>
    <tr>
      <td rowspan="7">變更<br>偵測</td>
      <td><code>ngOnInit</code>
      </td>
      <td>在 Angular 初始化元件的所有 inputs 之後執行一次。</td>
    </tr>
    <tr>
      <td><code>ngOnChanges</code></td>
      <td>每當元件的 inputs 變更時執行。</td>
    </tr>
    <tr>
      <td><code>ngDoCheck</code></td>
      <td>每當檢查此元件是否有變更時執行。</td>
    </tr>
    <tr>
      <td><code>ngAfterContentInit</code></td>
      <td>在元件的 <em>content</em> 初始化之後執行一次。</td>
    </tr>
    <tr>
      <td><code>ngAfterContentChecked</code></td>
      <td>每當檢查此元件的內容是否有變更時執行。</td>
    </tr>
    <tr>
      <td><code>ngAfterViewInit</code></td>
      <td>在元件的 <em>view</em> 初始化之後執行一次。</td>
    </tr>
    <tr>
      <td><code>ngAfterViewChecked</code></td>
      <td>每當檢查元件的檢視是否有變更時執行。</td>
    </tr>
    <tr>
      <td rowspan="2">渲染</td>
      <td><code>afterNextRender</code></td>
      <td>在下一次<strong>所有</strong>元件都渲染至 DOM 時執行一次。</td>
    </tr>
    <tr>
      <td><code>afterEveryRender</code></td>
      <td>每當<strong>所有</strong>元件都渲染至 DOM 時執行。</td>
    </tr>
    <tr>
      <td>銷毀</td>
      <td><code>ngOnDestroy</code></td>
      <td>在元件銷毀前執行一次。</td>
    </tr>
  </table>
</div>

### ngOnInit

`ngOnInit` 方法會在 Angular 以初始值初始化元件的所有 inputs 之後執行。元件的 `ngOnInit` 恰好執行一次。

這個步驟發生在元件自身的範本初始化_之前_。這表示你可以依據元件 inputs 的初始值來更新元件的狀態。

### ngOnChanges

`ngOnChanges` 方法會在任何元件 inputs 變更之後執行。

這個步驟發生在檢查元件自身的範本_之前_。這表示你可以依據元件 inputs 的初始值來更新元件的狀態。

在初始化期間，第一個 `ngOnChanges` 會在 `ngOnInit` 之前執行。

#### 檢視變更 {#inspecting-changes}

`ngOnChanges` 方法接受一個 `SimpleChanges` 引數。這個物件是一個 [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)，將每個元件 input 名稱對應到一個 `SimpleChange` 物件。每個 `SimpleChange` 都包含該 input 的前一個值、目前值，以及一個旗標，表示這是否為該 input 第一次變更。

你也可以選擇將目前的類別或 this 作為第一個泛型引數傳入，以獲得更嚴格的型別檢查。

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

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

若你為任何 input 屬性提供了 `alias`，`SimpleChanges` 這個 Record 仍會以 TypeScript 屬性名稱作為鍵，而不是使用別名。

### ngOnDestroy

`ngOnDestroy` 方法會在元件銷毀前執行一次。當元件不再顯示於頁面上時，Angular 會銷毀該元件，例如被 `@if` 隱藏，或導覽至其他頁面時。

#### DestroyRef

除了 `ngOnDestroy` 方法之外，你也可以注入 `DestroyRef` 的一個實例。呼叫 `DestroyRef` 的 `onDestroy` 方法，即可註冊一個在元件銷毀時被呼叫的回呼。

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

你可以將 `DestroyRef` 實例傳給元件之外的函式或類別。當元件銷毀時，若有其他程式碼需要執行某些清理行為，請使用這個模式。

你也可以使用 `DestroyRef`，讓設定程式碼靠近清理程式碼，而不必將所有清理程式碼都放在 `ngOnDestroy` 方法中。

##### 偵測實例銷毀 {#detecting-instance-destruction}

`DestroyRef` 提供了一個 `destroyed` 屬性，可用來檢查指定的實例是否已被銷毀。這在避免對已銷毀的元件進行操作時非常有用，特別是處理延遲或非同步邏輯時。

透過檢查 `destroyRef.destroyed`，你可以避免在實例清理完成後執行程式碼，從而避免如 `NG0911: View has already been destroyed.` 等潛在錯誤。

### ngDoCheck

`ngDoCheck` 方法會在 Angular 每次檢查元件範本是否有變更之前執行。

你可以使用這個生命週期鉤子，在 Angular 一般的變更偵測之外手動檢查狀態變更，並手動更新元件的狀態。

這個方法執行得非常頻繁，可能大幅影響頁面的效能。請盡可能避免定義這個鉤子，只在別無選擇時才使用。

在初始化期間，第一個 `ngDoCheck` 會在 `ngOnInit` 之後執行。

### ngAfterContentInit

`ngAfterContentInit` 方法會在巢狀置於元件內的所有子元素（其 _content_）初始化之後執行一次。

你可以使用這個生命週期鉤子來讀取[內容查詢](guide/components/queries#content-queries)的結果。雖然你可以存取這些查詢已初始化的狀態，但請避免更動某個祖先元件的範本已經渲染過的非訊號狀態。這麼做可能導致 [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)。

### ngAfterContentChecked

`ngAfterContentChecked` 方法會在巢狀置於元件內的所有子元素（其 _content_）檢查完變更之後，每次都執行。

這個方法執行得非常頻繁，可能大幅影響頁面的效能。請盡可能避免定義這個鉤子，只在別無選擇時才使用。

雖然你可以在這裡存取[內容查詢](guide/components/queries#content-queries)的更新後狀態，但請避免更動某個祖先元件的範本已經渲染過的非訊號狀態。這麼做可能導致 [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)。

### ngAfterViewInit

`ngAfterViewInit` 方法會在元件範本中的所有子元素（其 _view_）初始化之後執行一次。

你可以使用這個生命週期鉤子來讀取[檢視查詢](guide/components/queries#view-queries)的結果。雖然你可以存取這些查詢已初始化的狀態，但請避免更動某個範本已經渲染過的非訊號狀態。這麼做可能導致 [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)。

### ngAfterViewChecked

`ngAfterViewChecked` 方法會在元件範本中的所有子元素（其 _view_）檢查完變更之後，每次都執行。

這個方法執行得非常頻繁，可能大幅影響頁面的效能。請盡可能避免定義這個鉤子，只在別無選擇時才使用。

雖然你可以在這裡存取[檢視查詢](guide/components/queries#view-queries)的更新後狀態，但請避免更動某個範本已經渲染過的非訊號狀態。這麼做可能導致 [ExpressionChangedAfterItHasBeenCheckedError](errors/NG0100)。

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

`afterEveryRender` 與 `afterNextRender` 函式可讓你註冊一個**渲染回呼**，在 Angular 完成將頁面上的_所有元件_渲染至 DOM 之後被呼叫。

這些函式與本指南中說明的其他生命週期鉤子不同。它們不是類別方法，而是接受回呼的獨立函式。渲染回呼的執行並不綁定任何特定的元件實例，而是應用程式層級的鉤子。

`afterEveryRender` 與 `afterNextRender` 必須在[注入情境](guide/di/dependency-injection-context)中呼叫，通常是在元件的建構子中。

你可以使用渲染回呼來執行手動的 DOM 操作。關於在 Angular 中處理 DOM 的指引，請參閱[使用 DOM API](guide/components/dom-apis)。

渲染回呼不會在伺服器端渲染或建置時預渲染期間執行。

#### after\*Render 的階段

使用 `afterEveryRender` 或 `afterNextRender` 時，你可以選擇將工作拆分為多個階段。階段讓你能控制 DOM 操作的先後順序，例如將_寫入_操作排在_讀取_操作之前，以盡量減少[版面抖動](https://web.dev/avoid-large-complex-layouts-and-layout-thrashing)。為了在階段之間溝通，階段函式可以傳回一個結果值，供下一個階段存取。

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

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

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

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

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

共有四個階段，依以下順序執行：

| 階段             | 說明                                                                                                                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `earlyRead`      | 使用此階段讀取任何會影響版面、且後續計算嚴格需要的 DOM 屬性與樣式。請盡可能避免使用此階段，優先使用 `write` 與 `read` 階段。 |
| `write`          | 使用此階段寫入會影響版面的 DOM 屬性與樣式。                                                                                                                                   |
| `mixedReadWrite` | 預設階段。用於需要同時讀取與寫入會影響版面的屬性與樣式的操作。請盡可能避免使用此階段，優先使用明確的 `write` 與 `read` 階段。            |
| `read`           | 使用此階段讀取任何會影響版面的 DOM 屬性。                                                                                                                                           |

## 生命週期介面

Angular 為每個生命週期方法提供了一個 TypeScript 介面。你可以選擇匯入並 `implement` 這些介面，確保你的實作沒有錯字或拼寫錯誤。

每個介面的名稱都與對應的方法相同，但不含 `ng` 前綴。例如，`ngOnInit` 的介面是 `OnInit`。

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

## 執行順序

以下圖表顯示 Angular 生命週期鉤子的執行順序。

### 初始化期間

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

### 後續更新

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

### 與指令的順序關係

當你在與元件相同的元素上放置一個或多個指令時，無論是在範本中還是透過 `hostDirectives` 屬性，框架都不保證在同一個元素上，某個生命週期鉤子在元件與指令之間的執行順序。切勿依賴觀察到的順序，因為這在 Angular 的後續版本中可能會改變。
元件範本不只是靜態 HTML，它還能使用元件類別中的資料，並為使用者互動設定處理常式。

## 顯示動態文字 {#showing-dynamic-text}

在 Angular 中，繫結會在元件的範本與其資料之間建立動態連結。這個連結能確保元件資料一旦變更，渲染出的範本就會自動更新。

你可以使用雙大括號來建立繫結，在範本中顯示動態文字：

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

當 Angular 渲染這個元件時，你會看到：

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

當訊號的值改變時，Angular 會自動讓繫結保持最新。延續上面的範例，如果我們更新 `userName` 訊號的值：

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

渲染出的頁面就會更新，反映新的值：

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

## 設定動態的屬性與屬性值 {#setting-dynamic-properties-and-attributes}

Angular 支援使用方括號，把動態值繫結到 DOM 屬性上：

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

你也可以在屬性名稱前加上 `attr.` 前綴，來繫結 HTML 屬性值：

```html

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

當被繫結的值改變時，Angular 會自動更新 DOM 屬性與屬性值。

## 處理使用者互動 {#handling-user-interaction}

Angular 讓你可以使用括號，為範本中的元素加上事件監聽器：

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

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

如果你需要把 [event](https://developer.mozilla.org/docs/Web/API/Event) 物件傳給你的監聽器，可以在函式呼叫中使用 Angular 內建的 `$event` 變數：

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

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

## 使用 `@if` 與 `@for` 控制流程 {#control-flow-with-if-and-for}

你可以使用 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 App{
  updateField(): void {
    console.log('Field is updated!');
  }
}
```

在這個範例中，每當 `<input>` 元素發出 `keyup` 事件，Angular 就會呼叫 `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 App {
  updateField(event: KeyboardEvent): void {
    console.log(`The user pressed: ${event.key}`);
  }
}
```

## 使用按鍵修飾符 {#using-key-modifiers}

當你想為特定按鍵捕捉特定的鍵盤事件時，你可能會寫出如下的程式碼：

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

然而，由於這是常見的情境，Angular 讓你可以使用句點（`.`）字元指定特定按鍵來篩選事件。如此一來，程式碼可以簡化為：

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

你也可以加入額外的按鍵修飾符：

```html

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

Angular 支援 `alt`、`control`、`meta` 與 `shift` 等修飾符。

你可以指定要繫結到鍵盤事件的按鍵或代碼。按鍵與代碼欄位是瀏覽器鍵盤事件物件的原生部分。依預設，事件繫結假設你想使用[鍵盤事件的 Key 值](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_key_values)。

Angular 也允許你提供內建的 `code` 後綴，來指定[鍵盤事件的 Code 值](https://developer.mozilla.org/docs/Web/API/UI_Events/Keyboard_event_code_values)。

```html

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

這在跨不同作業系統一致地處理鍵盤事件時很有用。例如，在 macOS 裝置上使用 Alt 鍵時，`key` 屬性會回報已經過 Alt 鍵修飾的字元所對應的按鍵。這意味著像 Alt + S 這樣的組合會回報 `'ß'` 的 `key` 值。然而，`code` 屬性對應的是被按下的實體或虛擬按鈕，而不是產生的字元。

## 監聽全域目標

全域名稱可以用來作為事件的前綴。支援的 3 個全域目標是 `window`、`document` 與 `body`。

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

## 防止事件的預設行為

如果你的事件處理常式應取代瀏覽器的原生行為，你可以使用事件物件的 [`preventDefault` 方法](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault)：

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

如果事件處理常式陳述式的評估結果為 `false`，Angular 會自動呼叫 `preventDefault()`，類似於[原生事件處理常式 attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes#event_handler_attributes)。請一律優先明確呼叫 `preventDefault`，因為這種做法能讓程式碼的意圖一目了然。

## 擴充事件處理 {#extend-event-handling}

Angular 的事件系統可以透過以 `EVENT_MANAGER_PLUGINS` 注入權杖註冊的自訂事件外掛來擴充。

### 實作事件外掛

若要建立自訂事件外掛，請繼承 `EventManagerPlugin` 類別並實作所需的方法。

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

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

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

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

let timeoutId: ReturnType<typeof setTimeout>;

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

element.addEventListener(event, listener);

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

使用 `EVENT_MANAGER_PLUGINS` 權杖，在你的應用程式 providers 中註冊你的自訂外掛：

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

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

註冊後，你可以在範本中使用你的自訂事件語法，也可以搭配 `host` 屬性使用：

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

```ts
@Component({
  ...,
  host: {
    '(click.debounce.500)': 'handleDebouncedClick()',
  },
})
export class AwesomeCard {
  handleDebouncedClick(): void {
   console.log('Debounced click!');
  }
}
```
# 繫結動態文字、屬性與 attribute

在 Angular 中，**繫結**會在元件的範本與其資料之間建立動態連接。這個連接能確保元件資料的變更會自動更新算繪後的範本。

## 以文字插值算繪動態文字 {#render-dynamic-text-with-text-interpolation}

你可以使用雙大括號在範本中繫結動態文字，這會告訴 Angular，它負責處理其中的運算式，並確保其正確更新。這稱為**文字插值**。

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

在這個範例中，當程式碼片段算繪到頁面時，Angular 會將 `{{ theme }}` 取代為 `dark`。

```html

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

會隨時間變化的繫結，應從[訊號](/guide/signals)讀取值。Angular 會追蹤範本中讀取到的訊號，並在那些訊號值變更時更新算繪後的頁面。

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

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

如需更多細節，請參閱[訊號指南](/guide/signals)。

延續主題的範例，如果使用者在頁面載入後點選按鈕，將 `theme` 訊號更新為 `'light'`，頁面就會相應更新為：

```html

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

你可以在任何通常會在 HTML 中寫文字的地方使用文字插值。

運算式的值會轉換為字串。`null` 與 `undefined` 會算繪為空字串。物件與陣列則使用該值的 `toString` 方法進行轉換。

## 繫結動態屬性與 attribute {#binding-dynamic-properties-and-attributes}

Angular 支援以中括號將動態值繫結到物件屬性與 HTML attribute。

你可以繫結到 HTML 元素的 DOM 實例、[元件](/guide/components)實例或[指令](/guide/directives)實例上的屬性。

### 原生元素屬性

每個 HTML 元素都有對應的 DOM 表示。例如，每個 `<button>` HTML 元素都對應到 DOM 中 `HTMLButtonElement` 的一個實例。在 Angular 中，你使用屬性繫結將值直接設定到元素的 DOM 表示上。

```html

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

在這個範例中，每當 `isFormValid` 變更時，Angular 會自動設定 `HTMLButtonElement` 實例的 `disabled` 屬性。

### 元件與指令屬性

當元素是 Angular 元件時，你可以用相同的中括號語法，以屬性繫結設定元件的輸入屬性。

```html

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

在這個範例中，每當 `mySelection` 變更時，Angular 會自動設定 `MyListbox` 實例的 `value` 屬性。

你也可以繫結到指令屬性。

```html

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

### Attribute

當你需要設定沒有對應 DOM 屬性的 HTML attribute（例如 SVG attribute）時，你可以使用 `attr.` 前綴，將 attribute 繫結到範本中的元素。

```html

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

在這個範例中，每當 `listRole` 變更時，Angular 會呼叫 `setAttribute`，自動設定 `<ul>` 元素的 `role` attribute。

如果 attribute 繫結的值為 `null` 或 `undefined`，Angular 會呼叫 `removeAttribute` 移除該 attribute。

### 屬性與 attribute 中的文字插值

你也可以在屬性與 attribute 中使用文字插值語法：以雙大括號語法取代屬性或 attribute 名稱周圍的中括號。使用這種語法時，Angular 會將該指派視為屬性繫結。

```html

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

## CSS 類別與樣式屬性繫結 {#css-class-and-style-property-bindings}

Angular 為將 CSS 類別與 CSS 樣式屬性繫結到元素提供了額外的功能。

### CSS 類別

你可以建立 CSS 類別繫結，依繫結值為 [truthy 或 falsy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy)，有條件地在元素上加入或移除 CSS 類別。

```html

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

你也可以直接繫結到 `class` 屬性。Angular 接受三種類型的值：

| `class` 值的說明                                                                               | TypeScript 型別       |
| ---------------------------------------------------------------------------------------------- | --------------------- |
| 包含一或多個以空白分隔的 CSS 類別的字串                                                        | `string`              |
| CSS 類別字串的陣列                                                                             | `string[]`            |
| 一個物件，其每個屬性名稱都是 CSS 類別名稱，每個對應值依 truthiness 決定該類別是否套用到元素上 | `Record<string, any>` |

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

上述範例會算繪出下列 DOM：

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

Angular 會依空白切割字串值，並忽略空字串。

當同時使用靜態 CSS 類別、直接繫結 `class` 以及繫結特定類別時，Angular 會智慧地將所有類別合併到算繪結果中。

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

在上述範例中，Angular 會以三個 CSS 類別算繪 `ul` 元素。

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

Angular 不保證算繪後元素上 CSS 類別的任何特定順序。

當把 `class` 繫結到陣列或物件時，Angular 會以三等號運算子（`===`）比較先前的值與目前的值。當你修改這些值時，必須建立新的物件或陣列實例，Angular 才會套用任何更新。

如果一個元素對同一個 CSS 類別有多個繫結，Angular 會依照其樣式優先順序解決衝突。

NOTE: 類別繫結不支援在單一鍵中使用以空白分隔的類別名稱。它們也不支援對物件的變更（mutation），因為繫結的參照維持不變。如果你需要其中任一行為，請使用 [ngClass](/api/common/NgClass) 指令。

### CSS 樣式屬性 {#css-style-properties}

你也可以直接繫結到元素上的 CSS 樣式屬性。

```html

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

對於接受單位的 CSS 屬性，你可以進一步指定單位。

```html

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

你也可以在一個繫結中設定多個樣式值。Angular 接受下列類型的值：

| `style` 值的說明                                                          | TypeScript 型別       |
| ------------------------------------------------------------------------- | --------------------- |
| 包含零或多個 CSS 宣告的字串，例如 `"display: flex; margin: 8px"`          | `string`              |
| 一個物件，其每個屬性名稱都是 CSS 屬性名稱，每個對應值是該 CSS 屬性的值    | `Record<string, any>` |

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

上述範例會算繪出下列 DOM。

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

當把 `style` 繫結到物件時，Angular 會以三等號運算子（`===`）比較先前的值與目前的值。當你修改這些值時，必須建立新的物件實例，Angular 才會套用任何更新。

如果一個元素對同一個樣式屬性有多個繫結，Angular 會依照其樣式優先順序解決衝突。

## ARIA attribute {#aria-attributes}

Angular 支援將字串值繫結到 ARIA attribute。

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

Angular 會將字串值寫入元素的 `aria-label` attribute，並在繫結值為 `null` 或 `undefined` 時將它移除。

某些 ARIA 功能會公開接受結構化值（例如元素參照）的 DOM 屬性或指令輸入。遇到這類情況，請使用標準屬性繫結。範例與進一步說明請參閱[無障礙指南](/best-practices/a11y#aria-attributes-and-properties)。
# 控制流程

Angular 範本支援控制流程區塊，讓你能依條件顯示、隱藏與重複元素。

## 以 `@if`、`@else if` 與 `@else` 依條件顯示內容

當條件運算式為 truthy 時，`@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` 區塊重複內容 {#repeat-content-with-the-for-block}

`@for` 區塊會逐一走訪集合，並重複算繪區塊的內容。集合可以是任何 JavaScript [iterable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols)，但 Angular 對 `Array` 值有額外的效能最佳化。

典型的 `@for` 迴圈如下所示：

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

Angular 的 `@for` 區塊不支援 JavaScript 的 `continue` 或 `break` 這類改變流程的陳述式。

### 為什麼 `@for` 區塊中的 `track` 很重要？ {#why-is-track-in-for-blocks-important}

`track` 運算式讓 Angular 能維持你的資料與頁面上 DOM 節點之間的對應關係。這讓 Angular 在資料變更時，只執行最少必要的 DOM 操作，進而最佳化效能。

有效運用 track，能在對資料集合進行迴圈時大幅提升應用程式的算繪效能。

請在 `track` 運算式中選用能唯一識別每個項目的屬性。如果你的資料模型包含唯一識別屬性，通常是 `id` 或 `uuid`，請使用該值。如果你的資料沒有這類欄位，強烈建議新增一個。

對於永不變更的靜態集合，你可以使用 `$index`，告訴 Angular 依項目在集合中的索引來追蹤每個項目。

如果沒有其他選擇，你可以使用項目本身作為追蹤鍵。這會告訴 Angular 使用三等號運算子（`===`）依參照同一性來追蹤項目。請盡量避免這個選項，因為它可能導致算繪更新明顯變慢：Angular 無法對應哪筆資料項目對應到哪些 DOM 節點。

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

NOTE: 與 `*ngFor` 不同，`@for` 區塊優先重複使用檢視。如果被追蹤的屬性變更，但物件參照維持不變，Angular 會更新檢視的繫結（包括元件輸入），而不是銷毀並重新建立整個元素。

### `@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` 區塊提供備援內容 {#providing-a-fallback-for-for-blocks-with-the-empty-block}

你可以選擇在 `@for` 區塊內容之後緊接著加入 `@empty` 區段。當集合中沒有任何項目時，會顯示 `@empty` 區塊的內容：

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

## 以 `@switch` 區塊依條件顯示內容

雖然 `@if` 區塊適用於大多數情境，`@switch` 區塊提供了另一種依條件算繪資料的語法。它的語法與 JavaScript 的 `switch` 陳述式十分相似。

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

條件運算式的值會使用三等號（`===`）運算子與各 case 運算式進行比較。

`@switch` **沒有 fallthrough 行為**，因此你不需要在區塊中寫相當於 `break` 或 `return` 的陳述式。

你可以連續寫多個 `@case` 陳述式，為單一區塊指定多個條件。

你也可以選擇加入 `@default` 區塊。當前面所有 case 運算式都不符合 switch 值時，會顯示 `@default` 區塊的內容。

如果沒有任何 `@case` 符合運算式，也沒有 `@default` 區塊，就不會顯示任何內容。

### 窮舉型別檢查

`@switch` 支援窮舉型別檢查，讓 Angular 能在編譯時期驗證聯合型別的所有可能值都已被處理。

透過使用 `@default never;`，你可以明確宣告不應再有其他剩餘情況。如果日後聯合型別擴充、新增了未被 @case 涵蓋的情況，Angular 的範本型別檢查器會回報錯誤，協助你及早發現遺漏的分支。

NOTE: 窮舉檢查依賴 TypeScript 的型別縮小（type narrowing），這只對變數有效。如果 switch 條件是函式呼叫或訊號（例如 `@switch (state())`），就無法運作。若要繞過此限制，請將訊號指派給 `@let` 變數，例如：`@let mySignal = this.mySignal()`。

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

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

@default never;
      
    }
  `,
})
export class AppComponent {
  state: 'loggedOut' | 'loading' | 'loggedIn' = 'loggedOut';
}
```

當被 switch 的運算式巢狀於聯合型別之中時，你必須明確指定要檢查窮舉性的運算式。

```typescript
@Component({
  template: `
    @switch (state.mode) {
      @case ('show') {
        {{ state.menu }};
      }
      @case ('hide') {}
      @default never(state);
    }
  `,
})
export class App {
  state!: {mode: 'hide'} | {mode: 'show'; menu: number};
}
```
# 範本中的變數

Angular 在範本中有兩種變數宣告：區域範本變數與範本參照變數。

HELPFUL: 在本指南中，「範本」並不是指整個 HTML 範本檔案。它只指檔案中某個特定的範本結構或運算式。

## 使用 `@let` 的區域範本變數 {#local-template-variables-with-let}

Angular 的 `@let` 語法讓你能定義一個區域變數，並在整個範本中重複使用它，類似 [JavaScript `let` 語法](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let)。

### 使用 `@let`

使用 `@let` 宣告一個變數，其值以範本運算式的結果為基礎。Angular 會自動讓變數的值隨著給定的運算式保持最新，類似[繫結](/guide/templates/binding)。

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

每個 `@let` 區塊只能宣告一個變數。你不能在同一個區塊中用逗號宣告多個變數。

### 參照 `@let` 的值

用 `@let` 宣告變數之後，你可以在同一個範本中重複使用它：

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

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

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

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

### 可指派性

`@let` 與 JavaScript 的 `let` 之間的一個關鍵差異是，`@let` 在宣告之後不能重新指派。不過，Angular 會自動讓變數的值隨著給定的運算式保持最新。

```html
@let value = 1;

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

### 變數範圍

`@let` 宣告的範圍限於目前檢視及其後代。Angular 會在元件邊界，以及範本中可能包含動態內容的任何地方建立新檢視，例如控制流程區塊、`@defer` 區塊或結構指令。

由於 `@let` 宣告不會被提升（hoist），它們**無法**被父檢視或同層檢視存取：

```html
@let topLevel = value;

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

{{ topLevel }}

{{ insideDiv }}

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

@let nested = value;

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

{{ nested }}
```

### 完整語法

`@let` 語法的正式定義如下：

- `@let` 關鍵字。
- 接著一個或多個空白字元，不包括換行。
- 接著一個有效的 JavaScript 名稱與零個或多個空白字元。
- 接著 = 符號與零個或多個空白字元。
- 接著一個 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)

你可以使用範本參照變數，在同一個範本中，從某個部分讀取資訊並用於另一個部分。

### 宣告範本參照變數 {#declaring-a-template-reference-variable}

你可以在範本中的元素上加入一個以井字字元（`#`）開頭、後接變數名稱的屬性，來宣告變數。

```html

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

### 將值指派給範本參照變數 {#assigning-values-to-template-reference-variables}

Angular 會根據變數宣告所在的元素，將值指派給範本變數。

如果你在 Angular 元件上宣告變數，該變數會參照該元件執行個體。

```html

<my-datepicker #startDate />
```

如果你在 `<ng-template>` 元素上宣告變數，該變數會參照代表該範本的 TemplateRef 執行個體。詳情請參閱[結構指令](/guide/directives/structural-directives)中的[Angular 如何使用星號 \* 語法](/guide/directives/structural-directives#structural-directive-shorthand)。

```html

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

如果你在任何其他顯示元素上宣告變數，該變數會參照 `HTMLElement` 執行個體。

```html

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

#### 將參照指派給 Angular 指令 {#assigning-a-reference-to-an-angular-directive}

Angular 指令可能有一個 `exportAs` 屬性，定義該指令在範本中可被參照的名稱：

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

當你在元素上宣告範本變數時，可以指定這個 `exportAs` 名稱，將該變數指派為指令執行個體：

```html

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

你不能參照沒有指定 `exportAs` 名稱的指令。

### 搭配查詢使用範本參照變數

除了使用範本變數從同一個範本的其他部分讀取值之外，你也可以使用這種變數宣告方式，「標記」某個元素，以供[元件與指令查詢](/guide/components/queries)使用。

當你想查詢範本中的特定元素時，你可以在該元素上宣告範本變數，然後根據變數名稱查詢該元素。

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

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

若要了解查詢的更多資訊，請參閱[使用查詢參照子項](/guide/components/queries)。

### 範本變數範圍

就像 JavaScript 或 TypeScript 程式碼中的變數一樣，範本變數的範圍限於宣告它們的範本。

同樣地，像 `@if` 與 `@for` 這類[控制流程區塊](guide/templates/control-flow)、[結構指令](guide/directives/structural-directives)與 `<ng-template>` 宣告都會建立一個新的巢狀範本範圍，很像 JavaScript 的 `if` 與 `for` 這類控制流程敘述會建立新的語彙範圍。你不能從這些巢狀範本的邊界之外，存取其中的範本變數。

HELPFUL: 在範本中只定義變數一次，讓執行階段的值保持可預測。

#### 在巢狀範本中存取

內層範本可以存取外層範本定義的範本變數。

在以下範例中，變更 `<input>` 中的文字會變更 `<span>` 中的值，因為 Angular 會透過範本變數 `ref1` 立即更新變更。

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

@if (true) {
  <span>Value: {{ ref1.value }}</span>
}
```

在這個情況下，`@if` 區塊會建立一個新的範本範圍，其中包含來自父範圍的 `ref1` 變數。

不過，從父範本存取子範圍中的範本變數並不可行：

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

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

在這裡，`ref2` 是在 `@if` 建立的子範圍中宣告的，無法從父範本存取。
# 以 `@defer` 延遲載入

可延遲檢視（deferrable views），也稱為 `@defer` 區塊，能將初始呈現頁面時並非絕對必要的程式碼延遲載入，進而縮小應用程式的初始套件大小。這通常能帶來更快的初始載入，並改善 Core Web Vitals (CWV)，主要是最大內容繪製 (LCP) 與第一個位元組時間 (TTFB)。

若要使用這項功能，你可以以宣告方式將範本的一個區段包進 @defer 區塊：

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

`@defer` 區塊內任何元件、指令與管道的程式碼，都會被拆分到獨立的 JavaScript 檔案，並且只在必要時、在範本其餘部分算繪完成之後才載入。

可延遲檢視支援多種觸發條件、預先擷取選項，以及用於管理預留位置、載入與錯誤狀態的子區塊。

## 哪些相依性會被延遲？

在載入應用程式時，元件、指令、管道以及任何元件 CSS 樣式都可以被延遲。

若要讓 `@defer` 區塊內的相依性能被延遲，它們需要符合兩個條件：

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`

這是定義要延遲載入之內容區段的主要區塊。它一開始不會算繪，延遲的內容會在指定的[觸發條件](#controlling-deferred-content-loading-with-triggers)發生，或 `when` 條件達成時載入並算繪。

依預設，`@defer` 區塊會在瀏覽器狀態變為 [idle](/guide/templates/defer#idle) 時觸發。

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

### 以 `@placeholder` 顯示預留內容

依預設，延遲區塊在被觸發之前不會算繪任何內容。

`@placeholder` 是一個選擇性區塊，用來宣告在 `@defer` 區塊被觸發之前要顯示的內容。

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

雖然是選擇性的，但某些觸發條件可能需要有 `@placeholder` 或[範本參照變數](/guide/templates/variables#template-reference-variables)才能運作。詳情請參閱[觸發條件](#controlling-deferred-content-loading-with-triggers)一節。

載入完成後，Angular 會以主要內容取代預留內容。你可以在預留區段中使用任何內容，包括純 HTML、元件、指令與管道。請記住，預留區塊的*相依性會被預先載入*。

`@placeholder` 區塊接受一個選擇性參數，用來指定在預留內容初始算繪後，這個預留內容應顯示的 `minimum`（最短）時間。

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

這個 `minimum` 參數以毫秒 (ms) 或秒 (s) 的時間增量指定。你可以使用這個參數，在延遲相依性被快速取得的情況下，避免預留內容快速閃爍。

### 以 `@loading` 顯示載入中內容

`@loading` 區塊是一個選擇性區塊，讓你宣告在延遲相依性載入期間要顯示的內容。一旦載入被觸發，它會取代 `@placeholder` 區塊。

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

它的相依性會被預先載入（與 `@placeholder` 類似）。

`@loading` 區塊接受兩個選擇性參數，協助避免在延遲相依性被快速取得時可能發生的內容快速閃爍：

- `minimum`：這個預留內容應顯示的最短時間
- `after`：載入開始後，要等多久才顯示載入範本

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

這兩個參數都以毫秒 (ms) 或秒 (s) 的時間增量指定。此外，這兩個參數的計時器都會在載入被觸發後立即開始計時。

### 以 `@error` 在延遲載入失敗時顯示錯誤狀態

`@error` 區塊是一個選擇性區塊，在延遲載入失敗時顯示。與 `@placeholder` 和 `@loading` 類似，@error 區塊的相依性會被預先載入。

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

## 以觸發條件控制延遲內容的載入 {#controlling-deferred-content-loading-with-triggers}

你可以指定**觸發條件**，控制 Angular 何時載入並顯示延遲內容。

當 `@defer` 區塊被觸發時，它會以延遲載入的內容取代預留內容。

你可以以分號 `;` 分隔來定義多個事件觸發條件，它們會以 OR 條件評估。

觸發條件有兩種類型：`on` 與 `when`。

### `on`

`on` 指定 `@defer` 區塊被觸發的條件。

可用的觸發條件如下：

| 觸發條件                      | 說明                                                           |
| ----------------------------- | -------------------------------------------------------------- |
| [`idle`](#idle)               | 在瀏覽器閒置時觸發。支援選擇性的逾時。                         |
| [`viewport`](#viewport)       | 在指定內容進入可視區域時觸發                                   |
| [`interaction`](#interaction) | 在使用者與指定元素互動時觸發                                   |
| [`hover`](#hover)             | 在滑鼠懸停於指定區域時觸發                                     |
| [`immediate`](#immediate)     | 在非延遲內容算繪完成後立即觸發                                 |
| [`timer`](#timer)             | 在特定持續時間後觸發                                           |

#### `idle` {#idle}

`idle` 觸發條件會在瀏覽器達到閒置狀態時（以 requestIdleCallback 為依據）載入延遲內容。這是延遲區塊的預設行為。

你也可以選擇指定一個以毫秒為單位的逾時，傳給 [`requestIdleCallback`](https://developer.mozilla.org/docs/Web/API/Window/requestIdleCallback)。如果瀏覽器沒有及時排程該回呼，這項工作最遲會在指定的逾時時間執行。

```html

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

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

##### 自訂 `idle` 行為 {#customizing-idle-behavior}

你可以提供你自己的 `IdleService` 實作，並以 `provideIdleServiceWith` 在你的應用程式 providers 中註冊，來自訂 `idle` 觸發條件。

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

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

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

#### `viewport` {#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>Large component placeholder</div>
}
```

或者，你可以在與 `@defer` 區塊相同的範本中指定一個[範本參照變數](/guide/templates/variables)，作為要監看其進入可視區域的元素。這個變數會作為參數傳給 viewport 觸發條件。

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

如果你想自訂 `IntersectionObserver` 的選項，`viewport` 觸發條件支援傳入物件字面值。這個字面值支援 `IntersectionObserver` 第二個參數的所有屬性，但 `root` 除外。使用物件字面值表示法時，你必須透過 `trigger` 屬性傳入你的觸發條件。

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

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

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

#### `interaction` {#interaction}

`interaction` 觸發條件會在使用者透過 `click` 或 `keydown` 事件與指定元素互動時，載入延遲內容。

依預設，預留內容會作為互動元素。以此方式使用的預留內容必須具有單一根元素。

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

或者，你可以在與 `@defer` 區塊相同的範本中指定一個[範本參照變數](/guide/templates/variables)，作為要監看互動的元素。這個變數會作為參數傳給 interaction 觸發條件。

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

#### `hover` {#hover}

`hover` 觸發條件會在滑鼠透過 `mouseover` 與 `focusin` 事件懸停於觸發區域時，載入延遲內容。

依預設，預留內容會作為互動元素。以此方式使用的預留內容必須具有單一根元素。

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

或者，你可以在與 `@defer` 區塊相同的範本中指定一個[範本參照變數](/guide/templates/variables)，作為要監看懸停的元素。這個變數會作為參數傳給 hover 觸發條件。

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

#### `immediate` {#immediate}

`immediate` 觸發條件會立即載入延遲內容。這意味著延遲區塊會在所有其他非延遲內容算繪完成後，隨即載入。

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

#### `timer` {#timer}

`timer` 觸發條件會在指定的持續時間後載入延遲內容。

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

持續時間參數必須以毫秒 (`ms`) 或秒 (`s`) 指定。

### `when`

`when` 觸發條件接受自訂的條件運算式，並在條件變為 truthy 時載入延遲內容。

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

這是一次性的操作：`@defer` 區塊在條件變為 truthy 之後，即使條件再變為 falsy 值，也不會回復到預留內容。

## 以 `prefetch` 預先擷取資料

除了指定決定延遲內容何時顯示的條件外，你也可以選擇指定**預先擷取觸發條件**。這個觸發條件讓你能在延遲內容顯示之前，就先載入與 `@defer` 區塊相關聯的 JavaScript。

預先擷取能實現更進階的行為，例如讓你在使用者實際看見延遲區塊或與之互動之前、但可能即將與之互動時，就開始預先擷取資源，讓資源能更快就緒。

你可以比照區塊的主要觸發條件來指定預先擷取觸發條件，但要加上 `prefetch` 關鍵字作為前綴。區塊的主要觸發條件與預先擷取觸發條件以分號字元 (`;`) 分隔。

在下列範例中，預先擷取會在瀏覽器變為閒置時開始，而區塊的內容只在使用者與預留內容互動後才算繪。

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

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

## 測試 `@defer` 區塊

Angular 提供 TestBed API，簡化測試 `@defer` 區塊與在測試期間觸發不同狀態的流程。依預設，測試中的 `@defer` 區塊會如同延遲區塊在真實應用程式中的行為一樣播放。如果你想手動逐步切換狀態，可以在 TestBed 設定中將延遲區塊行為切換為 `Manual`。

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

## `@defer` 能與 `NgModule` 搭配使用嗎？

`@defer` 區塊與獨立元件以及基於 NgModule 的元件、指令與管道都相容。然而，**只有獨立元件、指令與管道能被延遲**。基於 NgModule 的相依性不會被延遲，而是包含在預先載入的套件中。

## `@defer` 區塊與熱模組重載 (HMR) 的相容性

當熱模組置換 (HMR) 啟用時，所有 `@defer` 區塊的區塊檔案都會被預先取得，覆寫任何已設定的觸發條件。若要恢復標準的觸發條件行為，你必須以 `--no-hmr` 旗標提供你的應用程式，以停用 HMR。

## `@defer` 如何與伺服器端算繪 (SSR) 和靜態網站產生 (SSG) 搭配運作？

依預設，在伺服器上算繪應用程式時（使用 SSR 或 SSG 皆然），延遲區塊永遠算繪其 `@placeholder`（如果未指定預留內容，則什麼都不算繪），且觸發條件不會被叫用。在用戶端，`@placeholder` 的內容會進行水合，觸發條件則會被啟用。

若要在伺服器上（SSR 與 SSG 皆然）算繪 `@defer` 區塊的主要內容，你可以啟用[漸進式水合功能](/guide/incremental-hydration)，並為必要的區塊設定 `hydrate` 觸發條件。

## Barrel 檔案與延遲區塊檔案

如果你使用了 `@defer`，卻在建置輸出中沒有看到獨立的延遲區塊檔案，請檢查你匯入被延遲元件的方式。透過 barrel 檔案 (`index.ts`) 匯入是常見的元兇：打包工具會將 barrel 視為單一模組，將它的所有匯出保持在一起，因此無論 `@defer` 如何設定，你的元件最終都會進入主要套件。

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

```typescript
{header: "parent.component.ts"}
import {Component} from '@angular/core';
import {HeavyComponent} from './index'; // pulls in OtherComponent too

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

修正方法很直接：直接從元件自己的檔案匯入：

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

這樣就足以讓打包工具將它拆分到自己的區塊檔案，並在觸發條件發生時延遲載入它。

## 延遲檢視的最佳實務

### 避免以巢狀 `@defer` 區塊造成串聯載入

當你有巢狀的 `@defer` 區塊時，它們應該使用不同的觸發條件，以避免同時載入，造成串聯請求，並可能對頁面載入效能產生負面影響。

### 避免版面位移

避免延遲在初始載入時位於使用者可視區域內的元件。這樣做可能會增加累計版面位移 (CLS)，對 Core Web Vitals 產生負面影響。

萬一有此必要，請避免使用會導致內容在初始頁面算繪期間載入的 `immediate`、`timer`、`viewport` 與自訂 `when` 觸發條件。

### 將無障礙納入考量 {#keep-accessibility-in-mind}

使用 `@defer` 區塊時，請考量對使用螢幕閱讀器等輔助技術的使用者的影響。
聚焦於延遲區段的螢幕閱讀器一開始會讀出預留或載入中內容，但在延遲內容載入時可能不會宣告變更。

若要確保延遲內容的變更會向螢幕閱讀器宣告，你可以將 `@defer` 區塊包在帶有 live region 的元素中：

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

這能確保在轉換（預留內容 → 載入中 → 內容/錯誤）發生時，變更會向使用者宣告。
# 運算式語法

Angular 運算式以 JavaScript 為基礎，但在一些關鍵方面有所不同。本指南將逐一說明 Angular 運算式與標準 JavaScript 之間的異同。

## 值字面值

Angular 支援 JavaScript [字面值](https://developer.mozilla.org/en-US/docs/Glossary/Literal)的一個子集。

### 支援的值字面值

| 字面值類型     | 範例值                          |
| -------------- | ------------------------------- |
| 字串           | `'Hello'`, `"World"`            |
| 布林           | `true`, `false`                 |
| 數字           | `123`, `3.14`                   |
| 物件           | `{name: 'Alice'}`               |
| 陣列           | `['Onion', 'Cheese', 'Garlic']` |
| null           | `null`                          |
| RegExp         | `/\d+/`                         |
| 範本字串       | `` `Hello ${name}` ``           |
| 標記範本字串   | `` tag`Hello ${name}` ``        |

### 不支援的值字面值

| 字面值類型 | 範例值 |
| ---------- | ------ |
| BigInt     | `1n`   |

## 全域值

Angular 運算式支援下列[全域值](https://developer.mozilla.org/en-US/docs/Glossary/Global_object)：

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

不支援任何其他 JavaScript 全域值。常見的 JavaScript 全域值包括 `Number`、`Boolean`、`NaN`、`Infinity`、`parseInt` 等。

## 區域變數

Angular 會在特定上下文中，自動提供特殊的區域變數供運算式使用。這些特殊變數一律以貨幣符號（`$`）開頭。

例如，`@for` 區塊會提供數個與迴圈資訊對應的區域變數，例如 `$index`。

## 支援哪些運算子？

### 支援的運算子

Angular 支援下列來自標準 JavaScript 的運算子。

| 運算子                        | 範例                                   |
| ----------------------------- | -------------------------------------- |
| 加法／串接                    | `1 + 2`                                |
| 減法                          | `52 - 3`                               |
| 乘法                          | `41 * 6`                               |
| 除法                          | `20 / 4`                               |
| 餘數（模數）                  | `17 % 5`                               |
| 冪運算                        | `10 ** 3`                              |
| 括號                          | `9 * (8 + 4)`                          |
| 條件（三元）                  | `a > b ? true : false`                 |
| 邏輯 AND                      | `&&`                                   |
| 邏輯 OR                       | `\|\|`                                 |
| 邏輯 NOT                      | `!`                                    |
| 空值合併                      | `possiblyNullValue ?? 'default'`       |
| 比較運算子                    | `<`, `<=`, `>`, `>=`, `==`, `===`, `!==`, `!=` |
| 一元否定                      | `-x`                                   |
| 一元正號                      | `+y`                                   |
| 屬性存取子                    | `person['name']`                       |
| typeof                        | `typeof 42`                            |
| void                          | `void 1`                               |
| in                            | `'model' in car`                       |
| instanceof                    | `car instanceof Automobile`            |
| 指派                          | `a = b`                                |
| 遞增                          | `a++`, `++a`                           |
| 遞減                          | `a--`, `--a`                           |
| 加法指派                      | `a += b`                               |
| 減法指派                      | `a -= b`                               |
| 乘法指派                      | `a *= b`                               |
| 除法指派                      | `a /= b`                               |
| 餘數指派                      | `a %= b`                               |
| 冪運算指派                    | `a **= b`                              |
| 邏輯 AND 指派                 | `a &&= b`                              |
| 邏輯 OR 指派                  | `a \|\|= b`                            |
| 空值合併指派                  | `a ??= b`                              |
| 物件字面值中的展開            | `{...obj, foo: 'bar'}`                 |
| 陣列字面值中的展開            | `[...arr, 1, 2, 3]`                    |
| 函式呼叫中的其餘參數          | `fn(...args)`                          |
| 箭頭函式                      | `items.filter((i) => i.active)`        |

NOTE: 指派與遞增／遞減運算子只在[事件監聽器陳述式](#event-listener-statements)中有效。在繫結或插值中使用它們會造成編譯錯誤，除非它們位於箭頭函式之內。

箭頭函式必須具有運算式主體。管道不能在箭頭函式內使用，但你可以將箭頭函式作為引數傳給管道。

Angular 運算式另外還支援下列非標準運算子：

| 運算子                          | 範例                           |
| ------------------------------- | ------------------------------ |
| [管道](/guide/templates/pipes)  | `{{ total \| currency }}`      |
| 選擇性串連\*                    | `someObj.someProp?.nestedProp` |
| 非空斷言（TypeScript）          | `someObj!.someProp`            |

### 安全導覽遷移

在 Angular 22 之前，當選擇性串連運算子（`?.`）的左側為 `null` 或 `undefined` 時，它會回傳 `null`，而標準 JavaScript 的 `?.` 則回傳 `undefined`。
自 Angular 22 起，Angular 運算式中選擇性串連運算子的行為已與標準 JavaScript 行為一致。

在遷移到 v22 期間，`ng update` 的原理圖會在既有運算式中加入 `$safeNavigationMigration` 函式，以保留先前的行為。

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

`$safeNavigationMigration` **只是暫時的遷移輔助工具**。它會指示編譯器以舊有的回傳 null 語義（而非標準 JavaScript 的 `?.` 語義）來編譯被包住的安全導覽運算式。它不是真正的函式，無法從 TypeScript 呼叫。

NOTE: 請優先遷移運算式，讓它們不再依賴 `null` 與 `undefined` 的區別，這樣就能移除 `$safeNavigationMigration`。這個函式可能會在 Angular 的未來版本中移除。

### 不支援的運算子

| 運算子              | 範例                              |
| ------------------- | --------------------------------- |
| 所有位元運算子      | `&`, `&=`, `~`, `\|=`, `^=`, etc. |
| 物件解構            | `const { name } = person`         |
| 陣列解構            | `const [firstItem] = items`       |
| 逗號運算子          | `x = (x++, x)`                    |
| new                 | `new Car()`                       |

## 運算式的詞彙上下文

Angular 運算式會在元件類別的上下文中評估，同時也會參照任何相關的[範本變數](/guide/templates/variables)、區域變數與全域值。

參照元件類別成員時，`this` 永遠是隱含的。然而，如果範本宣告了與成員同名的[範本變數](guide/templates/variables)，該變數會遮蔽該成員。你可以明確使用 `this.` 來無歧義地參照這類類別成員。這在建立會遮蔽類別成員的 `@let` 宣告時很有用，例如為了縮小訊號型別範圍。

## 宣告

一般而言，Angular 運算式不支援宣告。這包括但不限於：

| 宣告                        | 範例                                        |
| --------------------------- | ------------------------------------------- |
| 變數                        | `let label = 'abc'`, `const item = 'apple'` |
| 函式                        | `function myCustomFunction() { }`           |
| 具區塊主體的箭頭函式        | `() => { }`                                 |
| 類別                        | `class Rectangle { }`                       |

## 事件監聽器陳述式 {#event-listener-statements}

事件處理常式是**陳述式**，而非運算式。雖然它們支援與 Angular 運算式相同的全部語法，但有兩個關鍵差異：

1. 陳述式**確實支援**指派運算子（但不支援解構指派）
1. 陳述式**不支援**管道
# 屬性指令

屬性指令會改變 DOM 元素和 Angular 元件的外觀或行為。

## 一次性行為請用範本繫結

Angular 的範本語法已經涵蓋了變更單一元素的類別、樣式、屬性和事件：

- [類別與樣式繫結](guide/templates/binding#css-class-and-style-property-bindings)可新增與移除 CSS 類別和行內樣式。
- [屬性與特性繫結](guide/templates/binding)可設定 DOM 特性和 HTML 屬性。
- [事件監聽器](guide/templates/event-listeners)可回應使用者互動。

當你想把這類行為打包成可重複使用的單位、套用到任何元素或元件時，屬性指令就很有用。

## 建立屬性指令

自訂屬性指令是一個帶有 `@Directive()` 裝飾器的 JavaScript 類別。裝飾器的 `selector` 定義了套用該指令的屬性。方括號使它成為屬性選擇器，因此該指令會比對帶有該屬性的元素。依慣例，使用像 `app` 這樣的前綴來避免命名衝突：

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

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

HELPFUL: CLI 指令 [`ng generate directive`](tools/cli/schematics) 會產生一個指令及其測試檔案的鷹架。

指令可以透過宿主繫結以宣告方式改變其宿主，也可以透過宿主元素的參考以命令方式改變。這個範例[注入](guide/di) [`ElementRef`](api/core/ElementRef)，並透過其 `nativeElement` 屬性存取元素，把背景設為黃色：

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

IMPORTANT: 指令*不*支援命名空間。

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

## 套用屬性指令

若要套用該指令，在元素上以屬性形式加上它的選擇器：

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

Angular 會為該 `<p>` 元素建立一個 `HighlightDirective` 實例，注入該元素的參考，並把它的背景設為黃色。

## 處理使用者事件

若要回應使用者互動，透過 `@Directive()` 裝飾器的 `host` 屬性，把宿主元素事件繫結到處理方法。以下指令在指標停留在宿主元素上時將其反白，指標離開時清除反白：

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

`host` 屬性把 `mouseenter` 和 `mouseleave` 事件對應到 `onMouseEnter()` 和 `onMouseLeave()` 方法，這兩個方法會委派給一個 `highlight()` 輔助函式，由它在宿主元素上設定背景顏色。關於宿主事件繫結的更多資訊，請參閱[繫結到宿主元素](guide/components/host-elements#binding-to-the-host-element)。

## 接受輸入值

和元件一樣，指令透過 [`input()`](guide/components/inputs) 函式接受輸入。讓輸入與選擇器同名，使單一繫結既能套用指令，又能把值傳給它：

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

透過把它當作訊號來叫用，讀取輸入值；當沒有設定顏色時，退回使用預設值：

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

在範本中，把值繫結到選擇器。由於輸入與選擇器同名，`[appHighlight]` 既能套用指令，也能設定它的值。這裡繫結的 `color` 是元件上的一個屬性：

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

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

指令可以宣告一個以上的輸入。以下指令新增了一個 `defaultColor` 輸入，接著依序退回使用 `appHighlight`、`defaultColor`，最後是 `red`：

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

在同一個元素上繫結兩個輸入。由於 `defaultColor` 接受的是靜態字串而非動態運算式，不需要方括號：

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

## 使用 `NgNonBindable` 停用 Angular 處理

若要防止瀏覽器中的運算式求值，在宿主元素上加上 `ngNonBindable`。
`ngNonBindable` 會停用範本中的插值、指令和繫結。

在以下範例中，運算式 `{{ 1 + 1 }}` 會就像在你的程式碼編輯器中一樣呈現，不會顯示 `2`。

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

把 `ngNonBindable` 套用到某個元素，會停止該元素的子元素的繫結。
不過，`ngNonBindable` 仍然讓指令在你套用 `ngNonBindable` 的元素上運作。
在以下範例中，`appHighlight` 指令仍然有效，但 Angular 不會對運算式 `{{ 1 + 1 }}` 求值。

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

如果你把 `ngNonBindable` 套用到父元素，Angular 會停用該元素子元素的任何形式的插值和繫結，例如屬性繫結或事件繫結。

## 後續步驟
# 結構指令

結構指令是套用在 `<ng-template>` 元素上的指令，會依條件或重複地算繪該 `<ng-template>` 的內容。

日常的條件與重複算繪，請使用 Angular 內建的[控制流程區塊](guide/templates/control-flow)（`@if`、`@for` 與 `@switch`）。當你需要控制流程涵蓋不到的可重複使用算繪行為時，才撰寫結構指令，例如依權限檢查決定是否顯示內容，或以外部來源的資料提供範本。

## 使用案例範例

本指南以名為 `SelectDirective` 的指令作為貫穿全篇的範例。該指令會從指定的資料來源擷取資料，並在資料可用時算繪其範本。它的名稱源自 SQL 關鍵字 `SELECT`，並以屬性選擇器 `[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>` 標籤上的其他屬性或繫結都不受影響。例如，下列兩種形式是等價的：

```html

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

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

簡寫語法是透過一組慣例展開的。更完整的[文法](#structural-directive-syntax-reference)定義在下方，不過以上述範例來說，這個轉換可以這樣解釋：

`*select` 運算式的第一部分是 `let data`，它宣告了一個範本變數 `data`。由於後面沒有指派，這個範本變數會繫結到範本上下文屬性 `$implicit`。

第二段語法是鍵與運算式的組合 `from source`。`from` 是繫結鍵，`source` 是一般的範本運算式。繫結鍵會先轉換為 PascalCase，再在前面加上結構指令的選擇器，藉此對應到屬性。`from` 鍵對應到 `selectFrom`，再繫結到運算式 `source`。這就是為什麼許多結構指令的輸入全都以結構指令的選擇器作為前綴。

## 每個元素只能有一個結構指令 {#one-structural-directive-per-element}

使用簡寫語法時，每個元素只能套用一個結構指令。這是因為該指令只能展開到一個 `<ng-template>` 元素上。多個指令需要多個巢狀的 `<ng-template>`，而且無法確定哪個指令應該排第一。當多個結構指令需要套用在同一個實際 DOM 元素或元件周圍時，可以使用 `<ng-container>` 建立包裝層，讓使用者自行定義巢狀結構。

## 建立結構指令

結構指令是一個注入兩項相依性的指令類別：

- [`TemplateRef`](api/core/TemplateRef) 讓指令能存取它所套用的 `<ng-template>` 的內容。
- [`ViewContainerRef`](api/core/ViewContainerRef) 代表指令可以在 DOM 中算繪該範本的位置。

指令透過在檢視容器中從範本建立（或不建立）內嵌檢視，來控制算繪。完整的 `SelectDirective` 如下：

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

export interface DataSource<T> {
  load(): Promise<T>;
}

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

selectFrom = input.required<DataSource<unknown>>();

async ngOnInit() {
    const data = await this.selectFrom().load();
    this.viewContainerRef.createEmbeddedView(this.templateRef, {
      // Create the embedded view with a context object that contains
      // the data via the key `$implicit`.
      $implicit: data,
    });
  }
}
```

`selectFrom` 輸入指定了指令要讀取的資料來源。它使用 [`input.required()`](guide/components/inputs#required-inputs)，因為沒有資料來源，指令就無法做任何有用的事。

當 Angular 初始化該指令時，它會載入資料，然後呼叫 `createEmbeddedView()` 來算繪範本。第二個參數是範本的_上下文物件_：範本可以用 `let` 宣告繫結的值。把資料指派給 `$implicit` 鍵，就能讓它成為 `let-data`（或簡寫中的 `let data`）接收到的預設值。

NOTE: 這個範例只在指令初始化時算繪一次範本。當繫結的資料來源改變時，它不會重新算繪。

指令運作正常後，可以考慮[加入範本型別檢查支援](#typing-the-directives-context)。

HELPFUL: CLI 指令 [`ng generate directive`](tools/cli/schematics) 會產生指令及其測試檔的鷹架。

## 結構指令語法參考 {#structural-directive-syntax-reference}

撰寫自己的結構指令時，請使用下列語法：

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

下列模式描述了結構指令文法的每個部分：

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

### Angular 如何轉譯簡寫

Angular 會把結構指令簡寫轉譯為一般的繫結語法，如下所示：

### 簡寫範例

下表提供簡寫範例：

| 簡寫                                                                  | Angular 如何解讀該語法                                                                                        |
| :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| `*myDir="let item of [1,2,3]"`                                        | `<ng-template myDir let-item [myDirOf]="[1, 2, 3]">`                                                          |
| `*myDir="let item of [1,2,3] as items; trackBy: myTrack; index as i"` | `<ng-template myDir let-item [myDirOf]="[1,2,3]" let-items="myDirOf" [myDirTrackBy]="myTrack" let-i="index">` |
| `*ngComponentOutlet="componentClass"`                                 | `<ng-template [ngComponentOutlet]="componentClass">`                                                          |
| `*ngComponentOutlet="componentClass; inputs: myInputs"`               | `<ng-template [ngComponentOutlet]="componentClass" [ngComponentOutletInputs]="myInputs">`                     |
| `*myDir="exp as value"`                                               | `<ng-template [myDir]="exp" let-value="myDir">`                                                               |

## 改善自訂指令的範本型別檢查 {#improving-template-type-checking-for-custom-directives}

你可以為指令定義加入範本守衛，來改善自訂指令的範本型別檢查。這些守衛能協助 Angular 範本型別檢查器在編譯時期找出範本中的錯誤，進而避免執行時期錯誤。守衛有兩種不同的類型：

- `ngTemplateGuard_(input)` 讓你能依特定輸入的型別，控制輸入運算式應如何縮小範圍。
- `ngTemplateContextGuard` 用來依指令本身的型別，決定範本上下文物件的型別。

本節提供這兩種守衛的範例。如需更多資訊，請參閱[範本型別檢查](tools/cli/template-typecheck 'Template type-checking guide')。

### 以範本守衛進行型別縮小

範本中的結構指令控制該範本在執行時期是否算繪。有些結構指令想依輸入運算式的型別來進行型別縮小。

輸入守衛可以進行兩種縮小：

- 依 TypeScript 型別斷言函式縮小輸入運算式。
- 依輸入運算式是否為真值來縮小輸入運算式。

若要透過定義型別斷言函式來縮小輸入運算式：

```ts
// This directive only renders its template if the actor is a user.
// You want to assert that within the template, the type of the `actor`
// expression is narrowed to `User`.
@Directive(...)
class ActorIsUser {
  actor = input<User | Robot>();

static ngTemplateGuard_actor(dir: ActorIsUser, expr: User | Robot): expr is User {
    // The return statement is unnecessary in practice, but included to
    // prevent TypeScript errors.
    return true;
  }
}
```

型別檢查在範本中的行為，就如同已對繫結到該輸入的運算式套用了 `ngTemplateGuard_actor` 斷言。

有些指令只在輸入為真值時才算繪其範本。型別斷言函式無法完整捕捉真值性的語義，因此可以改用字面型別 `'binding'`，向範本型別檢查器表明：應以繫結運算式本身作為守衛：

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

static ngTemplateGuard_condition: 'binding';
}
```

範本型別檢查器的行為，就如同已斷言繫結到 `condition` 的運算式在範本中為真值。

### 為指令的上下文定型別 {#typing-the-directives-context}

如果你的結構指令為具現化的範本提供了上下文，你可以提供靜態的 `ngTemplateContextGuard` 型別斷言函式，在範本中正確地為它定型別。這個函式可以利用指令的型別推導出上下文的型別，當指令的型別是泛型時特別有用。

對於上述的 `SelectDirective`，你可以實作 `ngTemplateContextGuard` 來正確指定資料型別，即使資料來源是泛型也沒問題。

```ts
// Declare an interface for the template context:
export interface SelectTemplateContext<T> {
  $implicit: T;
}

@Directive(...)
export class SelectDirective<T> {
  // The directive's generic type `T` will be inferred from the `DataSource` type
  // passed to the input.
  selectFrom = input.required<DataSource<T>>();

// Narrow the type of the context using the generic type of the directive.
  static ngTemplateContextGuard<T>(dir: SelectDirective<T>, ctx: any): ctx is SelectTemplateContext<T> {
    // As before the guard body is not used at runtime, and included only to avoid
    // TypeScript errors.
    return true;
  }
}
```

## 後續步驟
# 指令組合 API

Angular 指令是封裝可重複使用行為的好方法。指令可以為元素套用屬性、CSS 類別與事件監聽器。

_指令組合 API_ 讓你能從元件的 TypeScript 類別內部，將指令套用到元件的宿主元素。

## 為元件加上指令

在元件的裝飾器中加入 `hostDirectives` 屬性，即可為元件套用指令。這類指令稱為_宿主指令_。

在此範例中，`MenuBehavior` 指令被套用到 `AdminMenu` 的宿主元素。其運作方式類似於在範本中把 `MenuBehavior` 套用到 `<admin-menu>` 元素。

```ts
@Component({
  selector: 'admin-menu',
  templateUrl: './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：

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

明確指定輸入與輸出後，使用帶有 `hostDirectives` 的元件時，就能在範本中繫結這些輸入與輸出：

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

此外，你可以為宿主指令的輸入與輸出設定別名，藉此自訂元件的 API：

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

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

## 為另一個指令加上指令

除了元件，你也可以為其他指令加上 `hostDirectives`。這能讓多種行為以遞移方式聚合在一起。

下列範例定義了兩個指令 `Menu` 與 `Tooltip`，再把兩者的行為組合在 `MenuWithTooltip` 中。最後，把 `MenuWithTooltip` 套用到 `SpecializedMenuWithTooltip`。

當 `SpecializedMenuWithTooltip` 在範本中使用時，它會建立 `Menu`、`Tooltip` 與 `MenuWithTooltip` 全部的執行個體。這些指令各自的宿主繫結都會套用到 `SpecializedMenuWithTooltip` 的宿主元素。

```ts
@Directive({/* ... */})
export class Menu {}

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

// MenuWithTooltip can compose behaviors from multiple other directives
@Directive({
  hostDirectives: [Tooltip, Menu],
})
export class MenuWithTooltip {}

// CustomWidget can apply the already-composed behaviors from MenuWithTooltip
@Directive({
  hostDirectives: [MenuWithTooltip],
})
export class SpecializedMenuWithTooltip {}
```

## 宿主指令的語義 {#host-directive-semantics}

### 指令執行順序

宿主指令的生命週期與直接在範本中使用的元件及指令相同。不過，宿主指令的建構函式、生命週期鉤子與繫結一定會_先於_它所套用的元件或指令執行。

下列範例展示宿主指令的最小用法：

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

這裡的執行順序為：

1. 建立 `MenuBehavior` 執行個體
2. 建立 `AdminMenu` 執行個體
3. `MenuBehavior` 接收輸入（`ngOnInit`）
4. `AdminMenu` 接收輸入（`ngOnInit`）
5. `MenuBehavior` 套用宿主繫結
6. `AdminMenu` 套用宿主繫結

這樣的執行順序意味著，帶有 `hostDirectives` 的元件可以覆寫宿主指令所指定的任何宿主繫結。

這種執行順序也適用於巢狀的宿主指令鏈，如下列範例所示。

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

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

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

在上例中，執行順序為：

1. 建立 `Tooltip` 執行個體
2. 建立 `CustomTooltip` 執行個體
3. 建立 `EvenMoreCustomTooltip` 執行個體
4. `Tooltip` 接收輸入（`ngOnInit`）
5. `CustomTooltip` 接收輸入（`ngOnInit`）
6. `EvenMoreCustomTooltip` 接收輸入（`ngOnInit`）
7. `Tooltip` 套用宿主繫結
8. `CustomTooltip` 套用宿主繫結
9. `EvenMoreCustomTooltip` 套用宿主繫結

### 依賴注入

指定了 `hostDirectives` 的元件或指令可以注入這些宿主指令的執行個體，反之亦然。

把宿主指令套用到元件時，元件與宿主指令雙方都可以定義提供者。

如果帶有 `hostDirectives` 的元件或指令與其宿主指令提供了相同的注入權杖，則由帶有 `hostDirectives` 的類別所定義的提供者，優先於宿主指令所定義的提供者。

### 宿主指令去重複 {#host-directive-de-duplication}

當同一個指令在解析後的宿主指令樹中出現多次時，Angular 會自動去除重複，而不是擲出錯誤。要決定保留哪一個符合項，會依兩條確定性規則判斷。

#### 範本符合優先

如果某個指令透過**範本選擇器**符合某個元素一次，同時也以**宿主指令**的身分出現，Angular 只會保留範本符合項，並捨棄所有宿主指令符合項。

可以這樣理解：宿主指令符合項代表的是 `Partial<YourDirective>`，也就是只公開在 `hostDirectives` 中明確列出的輸入與輸出的部分套用；而範本符合項代表的是擁有完整公開 API 的完整指令。

```ts
@Directive({selector: '[hoverable]'})
export class Hoverable {}

@Component({
  selector: 'app-button',
  hostDirectives: [Hoverable],
})
export class Button {}
```

```html


<app-button hoverable></app-button>
```

#### 多個宿主指令符合項會合併

如果同一個指令**以宿主指令的身分出現多次**，例如兩個指令都在各自的 `hostDirectives` 中宣告了共同的相依性，Angular 會把所有執行個體合併為單一指令執行個體。所有執行個體的輸入與輸出對應也會合併在一起。

這解決了宿主指令組合中經典的[菱形問題](https://en.wikipedia.org/wiki/Multiple_inheritance#The_diamond_problem)：

```ts
// A shared behavior that both triggers need
@Directive({
  host: {
    '[attr.data-trigger-id]': 'triggerId()',
  },
})
export class TriggerRef {
  readonly triggerId = input(`trigger-${crypto.randomUUID()}`);
}

// Two separate triggers, each declaring TriggerRef as a host directive
@Directive({
  selector: '[popoverTrigger]',
  hostDirectives: [TriggerRef],
})
export class PopoverTrigger {
  readonly triggerRef = inject(TriggerRef);
}

@Directive({
  selector: '[dropdownTrigger]',
  hostDirectives: [TriggerRef],
})
export class DropdownTrigger {
  readonly triggerRef = inject(TriggerRef);
}
```

```html

<button popoverTrigger dropdownTrigger>Actions</button>
```

HELPFUL: 因為 Angular 只會產生一個共用指令的執行個體，所以 `PopoverTrigger` 與 `DropdownTrigger` 注入時，收到的都是同一個 `TriggerRef` 執行個體。

#### 別名衝突

Angular 合併重複的宿主指令符合項時，也會合併它們的輸入與輸出對應。

如果同一個宿主指令的兩個執行個體以**不同的別名公開同一個輸入或輸出**，Angular 會在編譯時期擲出錯誤（[NG8024](errors/NG8024)）。

```ts
@Directive({
  selector: '[popoverTrigger]',
  hostDirectives: [{directive: TriggerRef, inputs: ['triggerId: popoverTriggerId']}],
})
export class PopoverTrigger {}

@Directive({
  selector: '[dropdownTrigger]',
  hostDirectives: [
    {directive: TriggerRef, inputs: ['triggerId: dropdownTriggerId']}, // different alias!
  ],
})
export class DropdownTrigger {}
```

```html

<button popoverTrigger dropdownTrigger></button>
```

若要解決這個問題，請確保兩條路徑都以相同的別名公開共用的輸入或輸出，或完全不公開它。

## 後續步驟
# 開始使用 NgOptimizedImage

`NgOptimizedImage` 指令讓你輕鬆採用載入圖片的效能最佳實務。

該指令透過下列方式，確保 [Largest Contentful Paint (LCP)](https://web.dev/lcp) 圖片的載入被優先處理：

- 自動在 `<img>` 標籤上設定 `fetchpriority` 屬性
- 預設延遲載入其他圖片
- 自動在文件 head 中產生 preconnect 連結標籤
- 自動產生 `srcset` 屬性
- 如果應用程式使用 SSR，會產生 [preload 提示](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 版成為穩定功能的，但它已被回移植（backported），在 13.4.0 版與 14.3.0 版中也作為穩定功能提供。

## 開始使用

<docs-workflow>
<docs-step title="匯入 `NgOptimizedImage` 指令">
從 `@angular/common` 匯入 `NgOptimizedImage` 指令：

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

並將它加入獨立元件或 NgModule 的 `imports` 陣列：

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

</docs-step>
<docs-step title="（可選）設定 Loader {#optional-set-up-a-loader}">
使用 NgOptimizedImage 並不**需要**圖片載入器（loader），但搭配圖片 CDN 使用載入器可以啟用強大的效能功能，包括為你的圖片自動產生 `srcset`。

設定載入器的簡要指南，請參閱本頁結尾的[為 NgOptimizedImage 設定圖片載入器](#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` {#mark-images-as-priority}">
務必將頁面上的 [LCP 圖片](https://web.dev/lcp/#what-elements-are-considered) 標記為 `priority`，讓它優先載入。

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

將圖片標記為 `priority` 會套用下列最佳化：

- 設定 `fetchpriority=high`（有關優先提示的更多資訊請見[這裡](https://web.dev/priority-hints)）
- 設定 `loading=eager`（有關原生延遲載入的更多資訊請見[這裡](https://web.dev/browser-level-image-lazy-loading)）
- 如果[在伺服器上渲染](guide/ssr)，會自動產生 [preload 連結元素](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: 如果你不知道圖片的尺寸，可以考慮使用「fill mode」來繼承父容器的尺寸，如下所述。
</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"`，圖片會保持它的長寬比，並以「letterboxed」方式符合元素。如果你設定 `object-fit: "cover"`，元素會保留它的長寬比、完全填滿元素，且部分內容可能會被「裁切」掉。

上述視覺範例請見 [MDN object-fit 文件](https://developer.mozilla.org/docs/Web/CSS/object-fit)。

你也可以用 [object-position 屬性](https://developer.mozilla.org/docs/Web/CSS/object-position) 為圖片設定樣式，調整它在容器元素中的位置。

IMPORTANT: 若要讓「fill」圖片正確渲染，它的父元素**必須**設定 `position: "relative"`、`position: "fixed"` 或 `position: "absolute"` 樣式。

## 如何遷移你的背景圖片 {#how-to-migrate-your-background-image}

以下是一個將 `background-image` 遷移到 `NgOptimizedImage` 的簡單逐步流程。在這些步驟中，我們將具有圖片背景的元素稱為「容器元素」：

1. 從容器元素移除 `background-image` 樣式。
2. 確保容器元素具有 `position: "relative"`、`position: "fixed"` 或 `position: "absolute"`。
3. 在容器元素底下建立一個新的圖片元素作為子元素，使用 `ngSrc` 來啟用 `NgOptimizedImage` 指令。
4. 為該元素加上 `fill` 屬性。不要加入 `height` 與 `width`。
5. 如果你認為這張圖片可能是你的 [LCP 元素](https://web.dev/lcp/)，請為圖片元素加入 `priority` 屬性。

你可以依照[使用 fill 模式](#using-fill-mode)章節所述，調整背景圖片填滿容器的方式。

## 使用佔位符 {#using-placeholders}

### 自動佔位符

如果你的 CDN 或圖片主機提供自動調整圖片大小的功能，NgOptimizedImage 可以為你的圖片顯示自動產生的低解析度佔位符。為你的圖片加入 `placeholder` 屬性即可利用此功能：

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

加入這個屬性後，會使用你指定的圖片載入器，自動請求第二個較小版本的圖片。這張小圖片會在你的圖片載入期間，以帶有 CSS 模糊效果的 `background-image` 樣式套用。如果沒有提供圖片載入器，就無法產生佔位圖片，並會拋出錯誤。

自動產生的佔位符預設大小為寬 30px。你可以在 `IMAGE_CONFIG` 提供者中指定像素值來變更這個大小，如下所示：

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      placeholderResolution: 40
    }
  },
],
```

如果你想讓模糊的佔位符周圍有銳利的邊緣，可以將圖片包在一個帶有 `overflow: hidden` 樣式的 `<div>` 容器中。只要 `<div>` 與圖片大小相同（例如使用 `width: fit-content` 樣式），佔位符的「模糊邊緣」就會被隱藏。

### Data URL 佔位符

你也可以在不使用圖片載入器的情況下，使用 base64 [data URL](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) 指定佔位符。data URL 的格式是 `data:image/[imagetype];[data]`，其中 `[imagetype]` 是圖片格式，例如 `png`，而 `[data]` 是圖片的 base64 編碼。該編碼可以使用命令列或在 JavaScript 中完成。具體指令請參閱 [MDN 文件](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URLs#encoding_data_into_base64_format)。帶有截斷資料的 data URL 佔位符範例如下所示：

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder="data:image/png;base64,iVBORw0K..." />
```

不過，較大的 data URL 會增加 Angular 套件的大小，並拖慢頁面載入。如果你無法使用圖片載入器，Angular 團隊建議將 base64 佔位圖片保持在 4KB 以下，並且只用在關鍵圖片上。除了縮小佔位符的尺寸外，也可以考慮變更儲存圖片時使用的圖片格式或參數。在非常低的解析度下，這些參數對檔案大小會有很大的影響。

### 非模糊佔位符

預設情況下，NgOptimizedImage 會對圖片佔位符套用 CSS 模糊效果。若要渲染不帶模糊的佔位符，請提供一個 `placeholderConfig` 參數，其物件包含 `blur` 屬性並設為 false。例如：

```html
<img ngSrc="cat.jpg" width="400" height="200" placeholder [placeholderConfig]="{blur: false}" />
```

## 調整圖片樣式

視圖片的樣式而定，加入 `width` 與 `height` 屬性可能會讓圖片的渲染方式不同。如果你的圖片樣式讓圖片以扭曲的長寬比渲染，`NgOptimizedImage` 會提出警告。

你通常可以將 `height: auto` 或 `width: auto` 加入圖片樣式來修正這個問題。更多資訊請參閱 [web.dev 有關 `<img>` 標籤的文章](https://web.dev/patterns/web-vitals-patterns/images/img-tag)。

如果圖片上的 `width` 與 `height` 屬性妨礙你用 CSS 以想要的方式調整圖片大小，可以考慮改用 `fill` 模式，並為圖片的父元素設定樣式。

## 效能功能

NgOptimizedImage 包含多項旨在改善應用程式載入效能的功能。本章節將說明這些功能。

### 加入資源提示 {#add-resource-hints}

為你的圖片來源加入 [`preconnect` 資源提示](https://web.dev/preconnect-and-dns-prefetch)，可以確保 LCP 圖片盡快載入。

對於作為[載入器](#optional-set-up-a-loader)參數提供的網域，preconnect 連結會自動產生。如果無法自動識別圖片來源，且未偵測到 LCP 圖片的 preconnect 連結，`NgOptimizedImage` 會在開發期間提出警告。在這種情況下，你應該手動將資源提示加入 `index.html`。在文件的 `<head>` 中，加入一個帶有 `rel="preconnect"` 的 `link` 標籤，如下所示：

```html
<link rel="preconnect" href="https://my.cdn.origin" />
```

若要停用 preconnect 警告，請注入 `PRECONNECT_CHECK_BLOCKLIST` token：

```ts
providers: [
{provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
],

```

有關自動產生 preconnect 的更多資訊，請見[這裡](#why-is-a-preconnect-element-not-being-generated-for-my-image-domain)。

### 以自動產生的 `srcset` 請求正確大小的圖片 {#request-images-at-the-correct-size-with-automatic-srcset}

定義 [`srcset` 屬性](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/srcset)可以確保瀏覽器針對使用者的可視區域請求正確大小的圖片，才不會浪費時間下載過大的圖片。`NgOptimizedImage` 會根據圖片標籤上 [`sizes` 屬性](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes)的有無與其值，為圖片產生適當的 `srcset`。

#### 固定尺寸圖片

如果你的圖片大小應該是「固定的」（也就是在不同裝置上大小相同，但[像素密度](https://web.dev/codelab-density-descriptors/)除外），就不需要設定 `sizes` 屬性。`srcset` 可以從圖片的寬度與高度屬性自動產生，不需要進一步的輸入。

自動產生的 srcset 範例：

```html
<img ... srcset="image-400w.jpg 1x, image-800w.jpg 2x" />
```

#### 響應式圖片 {#responsive-images}

如果你的圖片應該是響應式的（也就是依可視區域大小放大縮小），你就需要定義 [`sizes` 屬性](https://developer.mozilla.org/docs/Web/API/HTMLImageElement/sizes)來產生 `srcset`。

如果你以前沒用過 `sizes`，一個好的起點是根據可視區域寬度來設定它。例如，如果你的 CSS 讓圖片填滿可視區域寬度的 100%，就將 `sizes` 設為 `100vw`，瀏覽器會在 `srcset` 中選擇最接近可視區域寬度的圖片（在考慮像素密度之後）。如果你的圖片可能只佔據螢幕的一半（例如在側邊欄中），就將 `sizes` 設為 `50vw`，確保瀏覽器選擇較小的圖片。依此類推。

如果你發現上述內容無法涵蓋你想要的圖片行為，請參閱[進階 sizes 值](#advanced-sizes-values)的文件。

請注意，對於延遲載入的圖片，`NgOptimizedImage` 會自動在提供的 `sizes` 值前面加上 `"auto"`。這是一項最佳化，能提高支援 `sizes="auto"` 的瀏覽器在 srcset 選擇上的準確度，而不支援的瀏覽器會忽略它。未延遲載入的圖片（例如 `priority` 圖片）會保留所提供的 `sizes` 值。

預設的響應式斷點為：

`[16, 32, 48, 64, 96, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840]`

如果你想自訂這些斷點，可以使用 `IMAGE_CONFIG` 提供者來完成：

```ts
providers: [
  {
    provide: IMAGE_CONFIG,
    useValue: {
      breakpoints: [16, 48, 96, 128, 384, 640, 750, 828, 1080, 1200, 1920]
    }
  },
],
```

如果你想手動定義 `srcset` 屬性，可以使用 `ngSrcset` 屬性提供你自己的值：

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" />
```

如果有 `ngSrcset` 屬性，`NgOptimizedImage` 會根據其中包含的大小產生並設定 `srcset`。不要在 `ngSrcset` 中包含圖片檔案名稱，指令會從 `ngSrc` 推斷這項資訊。該指令同時支援寬度描述符（例如 `100w`）與密度描述符（例如 `1x`）。

```html
<img ngSrc="hero.jpg" ngSrcset="100w, 200w, 300w" sizes="50vw" />
```

### 停用自動產生 srcset

若要停用單一圖片的 srcset 產生，你可以在圖片上加入 `disableOptimizedSrcset` 屬性：

```html
<img ngSrc="about.jpg" disableOptimizedSrcset />
```

### 停用圖片延遲載入

預設情況下，`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" />
```

### 控制圖片解碼

預設情況下，`NgOptimizedImage` 會為所有圖片設定 `decoding="auto"`。這讓瀏覽器可以決定在取得圖片後解碼的最佳時機。當圖片被標記為 `priority` 時，Angular 會自動設定 `decoding="sync"`，確保圖片盡早解碼並繪製，有助於改善 **Largest Contentful Paint (LCP)** 效能。

你可以明確設定 `decoding` 屬性，來覆寫非優先圖片的預設 `auto`。優先圖片永遠使用 `decoding="sync"`。  
[詳情請參閱標準圖片 `decoding` 屬性的文件](https://developer.mozilla.org/docs/Web/HTML/Element/img#decoding)。

```html

<img ngSrc="gallery/landscape.jpg" width="1200" height="800" />

<img ngSrc="gallery/preview.jpg" width="600" height="400" decoding="async" />

<img ngSrc="awesome.jpg" width="500" height="625" priority />

<img ngSrc="hero.jpg" width="1600" height="900" decoding="sync" />
```

**允許的值**

- `auto`（預設）：讓瀏覽器選擇最佳策略。
- `async`：以非同步方式解碼圖片，盡可能避免阻塞主執行緒。
- `sync`：立即解碼圖片；可能會阻塞渲染，但能確保圖片一可用，像素就已就緒。

### 進階的 'sizes' 值 {#advanced-sizes-values}

你可能想讓圖片在不同大小的螢幕上以不同的寬度顯示。這種模式的一個常見範例是網格或欄位式版面：在行動裝置上渲染單欄，在較大的裝置上渲染雙欄。你可以使用「media query」語法，在 `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}

「loader」（載入器）是一個函式，會為指定的圖片檔案產生[圖片轉換 URL](https://web.dev/image-cdns/#how-image-cdns-use-urls-to-indicate-optimization-options)。在適當的情況下，`NgOptimizedImage` 會為圖片設定大小、格式與圖片品質的轉換。

`NgOptimizedImage` 既提供不套用任何轉換的通用載入器，也提供多種第三方圖片服務的載入器。它也支援撰寫你自己的自訂載入器。

| 載入器類型                            | 行為                                                                                                                                                                                                                       |
| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 通用載入器                         | 通用載入器回傳的 URL 永遠與 `src` 的值相符。換句話說，這個載入器不套用任何轉換。使用 Angular 提供圖片的網站，是這個載入器的主要目標使用案例。 |
| 第三方圖片服務的載入器 | 第三方圖片服務載入器回傳的 URL，會遵循該圖片服務所使用的 API 慣例。                                                                                              |
| 自訂載入器                         | 自訂載入器的行為由其開發者定義。如果你的圖片服務不被 `NgOptimizedImage` 預先設定的載入器支援，你應該使用自訂載入器。                                   |

根據 Angular 應用程式常用的圖片服務，`NgOptimizedImage` 提供預先設定好、可與下列圖片服務搭配使用的載入器：

若要使用**通用載入器**，不需要額外的程式碼變更。這是預設行為。

### 內建載入器 {#built-in-loaders}

若要使用現有的**第三方圖片服務**載入器，請將你所選服務的提供者工廠加入 `providers` 陣列。在下面的範例中，使用的是 Imgix 載入器：

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

你的圖片資產的基礎 URL 應該作為參數傳給提供者工廠。對大多數網站來說，這個基礎 URL 應該符合下列其中一種模式：

- <https://yoursite.yourcdn.com>
- <https://subdomain.yoursite.com>
- <https://subdomain.yourcdn.com/yoursite>

你可以在對應 CDN 提供者的文件中，進一步了解基礎 URL 的結構。

### 自訂載入器 {#custom-loaders}

若要使用**自訂載入器**，請將你的載入器函式作為 `IMAGE_LOADER` DI token 的值提供。在下面的範例中，自訂載入器函式回傳一個以 `https://example.com` 開頭的 URL，其中包含 `src`、`width` 與 `height` 作為 URL 參數。

```ts
providers: [
  {
    provide: IMAGE_LOADER,
    useValue: (config: ImageLoaderConfig) => {
      return `https://example.com/images?src=${config.src}&width=${config.width}&height=${config.height}`;
    },
  },
],
```

`NgOptimizedImage` 指令的載入器函式，接受一個型別為 `ImageLoaderConfig`（來自 `@angular/common`）的物件作為參數，並回傳圖片資產的絕對 URL。`ImageLoaderConfig` 物件包含 `src` 屬性，以及可選的 `width`、`height` 與 `loaderParams` 屬性。

NOTE: 即使 `width` 屬性並不總是存在，自訂載入器也必須使用它，來支援以各種寬度請求圖片，讓 `ngSrcset` 能正常運作。

### `loaderParams` 屬性 {#the-loaderparams-property}

`NgOptimizedImage` 指令還支援一個額外的屬性，稱為 `loaderParams`，專門設計來支援自訂載入器的使用。`loaderParams` 屬性接受一個具有任意屬性的物件作為值，它本身不會做任何事。`loaderParams` 中的資料會被加入傳給你的自訂載入器的 `ImageLoaderConfig` 物件中，可用來控制載入器的行為。

`loaderParams` 的一個常見用途，是控制進階的圖片 CDN 功能。

### 搭配內建載入器使用 `transform` 屬性

Cloudinary、Cloudflare、ImageKit 與 Imgix 的內建載入器，支援 `loaderParams` 中一個特殊的 `transform` 屬性。這個屬性讓你可以套用 CDN 提供的自訂圖片轉換。

`transform` 屬性接受兩種格式：

#### 字串格式

使用你的 CDN 的轉換語法，將轉換以逗號分隔的字串提供：

```html
<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: 'e_grayscale,r_10'}"
/>
```

#### 物件格式

將轉換以具有鍵值對的物件提供。

```html
<img
  ngSrc="my-image.jpg"
  width="400"
  height="300"
  [loaderParams]="{transform: {e: 'grayscale', r: 10}}"
/>
```

NOTE: Netlify 載入器不支援 `transform` 屬性，因為 Netlify 的圖片 CDN 不提供自訂轉換參數。

### 自訂載入器範例

以下顯示一個自訂載入器函式的範例。這個範例函式串接 `src`、`width` 與 `height`，並使用 `loaderParams` 來控制一個圓角的自訂 CDN 功能：

```ts
const myCustomLoader = (config: ImageLoaderConfig) => {
  let url = `https://example.com/images/${config.src}?`;
  let queryParams = [];
  if (config.width) {
    queryParams.push(`w=${config.width}`);
  }
  if (config.height) {
    queryParams.push(`h=${config.height}`);
  }
  if (config.loaderParams?.roundedCorners) {
    queryParams.push('mask=corners&corner-radius=5');
  }
  return url + queryParams.join('&');
};
```

請注意，在上例中，我們虛構了 'roundedCorners' 屬性名稱，來控制自訂載入器的一項功能。接著我們可以在建立圖片時使用這項功能，如下所示：

```html
<img ngSrc="profile.jpg" width="300" height="300" [loaderParams]="{roundedCorners: true}" />
```

## 常見問題

### NgOptimizedImage 支援 `background-image` css 屬性嗎？

NgOptimizedImage 並不直接支援 `background-image` css 屬性，但它的設計能輕鬆應付將圖片作為另一個元素背景的使用案例。

將 `background-image` 遷移到 `NgOptimizedImage` 的逐步流程，請參閱上方的[如何遷移你的背景圖片](#how-to-migrate-your-background-image)章節。

### 為什麼不能將 `src` 與 `NgOptimizedImage` 一起使用？

之所以選擇以 `ngSrc` 屬性作為 NgOptimizedImage 的觸發方式，是基於瀏覽器載入圖片方式的技術考量。NgOptimizedImage 會以程式方式變更 `loading` 屬性——如果瀏覽器在這些變更完成之前就看到 `src` 屬性，它就會開始積極下載圖片檔案，而載入方式的變更將被忽略。

### 為什麼我的圖片網域沒有產生 preconnect 元素？ {#why-is-a-preconnect-element-not-being-generated-for-my-image-domain}

preconnect 的產生是根據對你應用程式的靜態分析來執行的。這表示圖片網域必須直接包含在載入器參數中，如下列範例所示：

```ts
providers: [
  provideImgixLoader('https://my.base.url/'),
],
```

如果你使用變數將網域字串傳給載入器，或你沒有使用載入器，靜態分析將無法識別該網域，也就不會產生 preconnect 連結。在這種情況下，你應該如[上所述](#add-resource-hints)，手動將 preconnect 連結加入文件 head 中。

### 我可以在同一個頁面中使用兩個不同的圖片網域嗎？

[圖片載入器](#configuring-an-image-loader-for-ngoptimizedimage)的提供者模式，設計上力求簡單，以應付元件中只使用單一圖片 CDN 的常見使用案例。不過，使用單一提供者來管理多個圖片 CDN 仍然完全可行。

若要做到這一點，我們建議撰寫一個[自訂圖片載入器](#custom-loaders)，使用 [`loaderParams` 屬性](#the-loaderparams-property)傳遞一個旗標，指定應該使用哪個圖片 CDN，然後根據該旗標呼叫適當的載入器。

### 你們可以為我偏好的 CDN 新增內建載入器嗎？

基於維護上的考量，我們目前不打算在 Angular 儲存庫中支援額外的內建載入器。相反地，我們鼓勵開發者將任何額外的圖片載入器以第三方套件的形式發佈。

### 我可以將它與 `<picture>` 標籤一起使用嗎？

不行，但這已列入我們的藍圖，敬請期待。

如果你正在等待這項功能，請在[這裡](https://github.com/angular/angular/issues/56594)為該 GitHub issue 投下贊成票。

### 如何用 Chrome DevTools 找出我的 LCP 圖片？

1. 使用 Chrome DevTools 的 performance 分頁，點選左上角的「start profiling and reload page」按鈕。它的外觀像一個頁面重新整理圖示。

2. 這會觸發一份你 Angular 應用程式的效能分析快照。

3. 效能分析結果可用後，在 timings 區段中選取「LCP」。

4. 底部面板中應該會出現一個摘要項目。你可以在「related node」那一列找到 LCP 元素。點選它會在 Elements 面板中顯示該元素。

NOTE: 這只會識別你正在測試的頁面可視區域內的 LCP 元素。也建議使用行動裝置模擬，來識別較小螢幕的 LCP 元素。
在 Angular 中，你會用訊號來建立與管理狀態。訊號是對某個值的輕量包裝。

使用 `signal` 函式來建立一個保存本機狀態的訊號：

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

// Create a signal with the `signal` function.
const firstName = signal('Morgan');

// Read a signal value by calling it— signals are functions.
console.log(firstName());

// Change the value of this signal by calling its `set` method with a new value.
firstName.set('Jaime');

// You can also use the `update` method to change the value
// based on the previous value.
firstName.update((name) => name.toUpperCase());
```

Angular 會追蹤訊號在哪些地方被讀取，以及何時被更新。框架會利用這些資訊來執行額外的工作，例如以新狀態更新 DOM。這種隨著訊號值變化而作出反應的能力，就稱為反應式機制。

## 計算運算式

`computed` 是一種訊號，它的值是由其他訊號推導出來的。

```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` 來建立並管理狀態：

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

// Select the first shipping option by default.
  selectedOption = signal(this.shippingOptions()[0]);

changeShipping(newOptionIndex: number) {
    this.selectedOption.set(this.shippingOptions()[newOptionIndex]);
  }
}
```

在這個範例中，`selectedOption` 預設為第一個選項，但使用者選擇其他選項時就會改變。然而 `shippingOptions` 是個訊號，它的值可能會變！如果 `shippingOptions` 改變，`selectedOption` 可能會包含一個不再有效的選項值。

**`linkedSignal` 函式讓你建立一個訊號，用來保存與其他狀態本質上_相連結_的狀態**。回到上面的範例，`linkedSignal` 可以取代 `signal`：

```ts
@Component({
  /* ... */
})
export class ShippingMethodPicker {
  shippingOptions: Signal<ShippingMethod[]> = getShippingOptions();

// Initialize selectedOption to the first shipping option.
  selectedOption = linkedSignal(() => this.shippingOptions()[0]);

changeShipping(index: number) {
    this.selectedOption.set(this.shippingOptions()[index]);
  }
}
```

`linkedSignal` 的運作方式與 `signal` 類似，但有一個關鍵差異——你傳入的不是預設值，而是一個_計算函式_，就像 `computed` 一樣。當計算的值改變時，`linkedSignal` 的值就會變成計算結果。這能確保 `linkedSignal` 隨時都持有有效的值。

以下範例展示 `linkedSignal` 的值如何隨其連結的狀態而改變：

```ts
const shippingOptions = signal(['Ground', 'Air', 'Sea']);
const selectedOption = linkedSignal(() => shippingOptions()[0]);
console.log(selectedOption()); // 'Ground'

selectedOption.set(shippingOptions()[2]);
console.log(selectedOption()); // 'Sea'

shippingOptions.set(['Email', 'Will Call', 'Postal service']);
console.log(selectedOption()); // 'Email'
```

## 將先前狀態納入考量 {#accounting-for-previous-state}

在某些情況下，`linkedSignal` 的計算需要把 `linkedSignal` 的先前值納入考量。

在上面的範例中，當 `shippingOptions` 改變時，`selectedOption` 總是會回到第一個選項。然而，如果使用者已選的選項仍在清單中，你可能會想保留使用者的選擇。為此，你可以建立一個帶有分開的 _source_ 與 _computation_ 的 `linkedSignal`：

```ts
interface ShippingMethod {
  id: number;
  name: string;
}

@Component({
  /* ... */
})
export class ShippingMethodPicker {
  constructor() {
    this.changeShipping(2);
    this.changeShippingOptions();
    console.log(this.selectedOption()); // {"id":2,"name":"Postal Service"}
  }

shippingOptions = signal<ShippingMethod[]>([
    {id: 0, name: 'Ground'},
    {id: 1, name: 'Air'},
    {id: 2, name: 'Sea'},
  ]);

selectedOption = linkedSignal<ShippingMethod[], ShippingMethod>({
    // `selectedOption` is set to the `computation` result whenever this `source` changes.
    source: this.shippingOptions,
    computation: (newOptions, previous) => {
      // If the newOptions contain the previously selected option, preserve that selection.
      // Otherwise, default to the first option.
      return newOptions.find((opt) => opt.id === previous?.value.id) ?? newOptions[0];
    },
  });

changeShipping(index: number) {
    this.selectedOption.set(this.shippingOptions()[index]);
  }

changeShippingOptions() {
    this.shippingOptions.set([
      {id: 0, name: 'Email'},
      {id: 1, name: 'Sea'},
      {id: 2, name: 'Postal Service'},
    ]);
  }
}
```

建立 `linkedSignal` 時，你可以傳入一個帶有分開的 `source` 與 `computation` 屬性的物件，而不只是提供一個計算函式。

`source` 可以是任何訊號，例如 `computed` 或元件的 `input`。當 `source` 改變、或 `computation` 中參考的任何訊號改變時，`linkedSignal` 就會以所提供 `computation` 的結果更新自己的值。

`computation` 是一個函式，會收到 `source` 的新值和一個 `previous` 物件。`previous` 物件有兩個屬性——`previous.source` 是 `source` 的先前值，`previous.value` 是 `linkedSignal` 的先前值。你可以用這些先前值來決定計算的新結果。

HELPFUL: 使用 `previous` 參數時，你必須明確提供 `linkedSignal` 的泛型型別引數。第一個泛型型別對應 `source` 的型別，第二個泛型型別決定 `computation` 的輸出型別。

## 自訂相等比較

`linkedSignal` 和其他任何訊號一樣，可以設定自訂的相等比較函式。下游依賴會使用這個函式來判斷 `linkedSignal` 的值（即計算結果）是否已改變：

```typescript
const activeUser = signal({id: 123, name: 'Morgan', isAdmin: true});

const activeUserEditCopy = linkedSignal(() => activeUser(), {
  // Consider the user as the same if it's the same `id`.
  equal: (a, b) => a.id === b.id,
});

// Or, if separating `source` and `computation`
const activeUserEditCopy = linkedSignal({
  source: activeUser,
  computation: (user) => user,
  equal: (a, b) => a.id === b.id,
});
```

## 自訂 set 操作

有時，你會希望 `linkedSignal` 的 `set` 與 `update` 操作能寫回真實來源，而不是直接更新 `linkedSignal` 本身的值。你可以在選項中傳入一個 `set` 函式來自訂這個行為。

自訂的 `set` 函式會收到兩個引數：

1. 要設定的新值。
2. 一個 `rawSet` 函式，你可以呼叫它來直接更新 `linkedSignal` 的內部狀態（與預設行為相同）。

NOTE: 使用 `rawSet` 可以讓你直接更新 `linkedSignal` 的值。當你不想讓計算執行時這很有用，例如該衍生運算成本高昂、而你已經知道結果。

### 寫回來源訊號

想像一個元件，它顯示並允許編輯華氏溫度，但以一個攝氏溫度訊號作為真實來源：

```typescript
const tempC = signal(0);
const tempF = linkedSignal(() => (tempC() * 9) / 5 + 32, {
  set: (valF) => tempC.set(((valF - 32) * 5) / 9),
});

console.log(tempF()); // 32

// Setting Fahrenheit updates Celsius, which reactively updates Fahrenheit
tempF.set(212);
console.log(tempC()); // 100
console.log(tempF()); // 212
```

### 更新父物件內的屬性

另一個常見情境是更新父物件內的特定屬性。父物件保存在一個訊號中，而你連結到其中一個巢狀屬性：

```typescript
interface Order {
  id: number;
  shippingMethod: string;
}

const order = signal<Order>({
  id: 42,
  shippingMethod: 'Ground',
});

const shippingMethod = linkedSignal(() => order().shippingMethod, {
  set: (newMethod) => {
    // Perform an immutable update to write the change back to the order
    order.update((currentOrder) => ({
      ...currentOrder,
      shippingMethod: newMethod,
    }));
  },
});

console.log(shippingMethod()); // 'Ground'

// Updating the shippingMethod updates the parent order object
shippingMethod.set('Air');
console.log(order()); // { id: 42, shippingMethod: 'Air' }
console.log(shippingMethod()); // 'Air'
```
# 使用資源處理非同步反應式

所有訊號 API 都是同步的——`signal`、`computed`、`input` 等。然而，應用程式經常需要處理以非同步方式取得的資料。`Resource` 讓你可以將非同步資料納入應用程式以訊號為基礎的程式碼中，同時仍能以同步方式存取其資料。

你可以使用 `Resource` 執行任何種類的非同步操作，但 `Resource` 最常見的用途是從伺服器擷取資料。以下範例建立一個資源來擷取某些使用者資料。

建立 `Resource` 最簡單的方法是使用 `resource` 函式。

```typescript
import {computed, resource, Signal} from '@angular/core';

const userId: Signal<string> = getUserId();

const userResource = resource({
  // Define a reactive computation.
  // The params value recomputes whenever any read signals change.
  params: () => ({id: userId()}),

// Define an async loader that retrieves data.
  // The resource calls this function every time the `params` value changes.
  loader: ({params}) => fetchUser(params),
});

// Create a computed signal based on the result of the resource's loader function.
const firstName = computed(() => {
  if (userResource.hasValue()) {
    // `hasValue` serves 2 purposes:
    // - It acts as type guard to strip `undefined` from the type
    // - It protects against reading a throwing `value` when the resource is in error state
    return userResource.value().firstName;
  }

// fallback in case the resource value is `undefined` or if the resource is in error state
  return undefined;
});
```

`resource` 函式接受一個 `ResourceOptions` 物件，它有兩個主要屬性：`params` 與 `loader`。

`params` 屬性定義一個反應式計算，用來產生參數值。每當這個計算中讀取的訊號改變時，資源就會產生新的參數值，類似 `computed` 的行為。

`loader` 屬性定義一個 `ResourceLoader`——一個用來擷取某些狀態的非同步函式。每當 `params` 計算產生新值時，資源就會呼叫 loader，並把該值傳給它。詳情請參閱下方的[資源載入器](#resource-loaders)。

`Resource` 有一個 `value` 訊號，其中包含 loader 的結果。

## 資源載入器 {#resource-loaders}

建立資源時，你要指定一個 `ResourceLoader`。這個 loader 是一個非同步函式，接受單一參數——一個 `ResourceLoaderParams` 物件——並傳回一個值。

`ResourceLoaderParams` 物件包含三個屬性：`params`、`previous` 與 `abortSignal`。

| Property      | 說明                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `params`      | 資源的 `params` 計算所產生的值。                                                                                                |
| `previous`    | 一個帶有 `status` 屬性的物件，包含先前的 `ResourceStatus`。                                                                    |
| `abortSignal` | 一個 [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)。詳情請參閱下方的[中止請求](#aborting-requests)。 |

如果 `params` 計算傳回 `undefined`，loader 函式就不會執行，資源狀態會變成 `'idle'`。

### 串流資源

某些非同步資料來源會隨時間產生多個值，而不是傳回單一結果。例如 WebSockets、Server-Sent Events (SSE)，以及 Firestore 的 `onSnapshot` 監聽器。

對於這類持續更新的資料來源，請使用 `stream`。與每個請求只解析一次的 `loader` 不同，`stream` 傳回的訊號其值可以隨著新資料到來而持續更新。

對於一次性的非同步操作，例如從 HTTP 端點擷取資料，請使用 `loader`。

在這個範例中，`userUpdates` 模擬一個外部來源，例如 WebSocket 或 SSE 連線。

```typescript
const userUpdates = signal({value: 'Alice'});

const userResource = resource({
  stream: () => userUpdates,
});

// Simulate a new value arriving from the external data source:
userUpdates.set({value: 'Bob'});
```

### 中止請求 {#aborting-requests}

如果資源載入期間 `params` 計算改變，資源會中止尚未完成的載入操作。

你可以使用 `ResourceLoaderParams` 中的 `abortSignal` 來回應被中止的請求。例如，原生的 `fetch` 函式就接受一個 `AbortSignal`：

```typescript
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params, abortSignal}): Promise<User> => {
    // fetch cancels any outstanding HTTP requests when the given `AbortSignal`
    // indicates that the request has been aborted.
    return fetch(`users/${params.id}`, {signal: abortSignal}).then((res) => res.json());
  },
});
```

關於使用 `AbortSignal` 取消請求的更多詳情，請參閱 [MDN 上的 `AbortSignal`](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();
```

## 資源狀態 {#resource-status}

資源物件有數個訊號屬性，可用來讀取非同步 loader 的狀態。

| Property    | 說明                                                                                                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`     | 資源的最新值；如果尚未收到任何值，則為預設值（除非有設定 `defaultValue`，否則為 `undefined`）。當狀態為 `'error'` 時，讀取 `value()` 會擲出錯誤。 |
| `hasValue`  | 資源是否有值。                                                                                                                                                            |
| `error`     | 執行資源 loader 時遇到的最新錯誤；如果尚未發生錯誤，則為 `undefined`。                                                                              |
| `isLoading` | 資源 loader 目前是否正在執行。                                                                                                                                            |
| `status`    | 資源的具體 `ResourceStatus`，如下所述。                                                                                                                                |

`status` 訊號提供一個具體的 `ResourceStatus`，以字串常數描述資源的狀態。

| Status        | `value()`         | 說明                                                                  |
| ------------- | :---------------- | ---------------------------------------------------------------------------- |
| `'idle'`      | `undefined`       | 資源沒有有效的請求，且 loader 尚未執行。                |
| `'error'`     | 擲出錯誤   | loader 遇到了錯誤。                                         |
| `'loading'`   | `undefined`       | loader 因 `params` 值改變而正在執行。            |
| `'reloading'` | 先前的值    | loader 因呼叫資源的 `reload` 方法而正在執行。 |
| `'resolved'`  | 解析完成的值    | loader 已完成。                                                    |
| `'local'`     | 在本機設定的值 | 資源的值已透過 `.set()` 或 `.update()` 在本機設定。        |

你可以使用這些狀態資訊來條件式地顯示使用者介面元素，例如載入指示器與錯誤訊息。

## 搭配 SSR 快取 `resource` 資料

當應用程式在伺服器上渲染時，資源 loader 會執行一次以產生初始 HTML。在水合（hydration）期間，瀏覽器通常會再執行一次同一個 loader。

若要重用伺服器端的結果，請為資源提供一個 `id`。Angular 會在伺服器上把解析完成的值存入 `TransferState`，並在用戶端用它把資源初始化為 `'resolved'` 狀態。

```ts
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
  id: 'user-unique-id',
});
```

`id` 值在你的應用程式中必須唯一，且在伺服器與用戶端上必須相同，Angular 才能把快取項目對應到提出請求的資源。

IMPORTANT: 由於快取值會被序列化進頁面的 HTML 中，請避免在載入特定使用者資料的資源上設定 `id`，尤其是那些資料屬於觸發伺服器端渲染的使用者、且渲染出的 HTML 可能被快取或在使用者之間共用時。

## 串連資源 {#chaining-resources}

有時，一個資源會依賴另一個資源的結果。你可以使用 `params` 上下文物件中提供的 `chain` 函式來表達這種依賴關係。

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

const userResource = resource({
  params: () => ({id: getUserId()}),
  loader: ({params}) => fetchUser(params),
});

const companyResource = resource({
  params: ({chain}) => chain(userResource)?.companyId,
  loader: ({params: companyId}) => fetchCompany(companyId),
});
```

這裡的 `companyResource` 依賴使用者的 `companyId`，而這個值要等 `userResource` 載入後才知道。`chain(userResource)` 會讀取 `userResource` 的值，並自動把它的狀態傳播給 `companyResource`：

- 如果 `userResource` 為 **idle**，`companyResource` 也會變成 `idle`。
- 如果 `userResource` 為 **loading** 或 **reloading**，`companyResource` 會進入 `loading` 狀態，且其 loader 不會執行。請注意，在 `reloading` 期間，`chain` 不會傳回先前解析完成的值。
- 如果 `userResource` 處於 **error** 狀態，`companyResource` 也會進入 `error` 狀態。
- 如果 `userResource` 為 **resolved** 或 **local**，`chain` 會傳回它目前的值，`companyResource` 接著會把該值用作自己的 params。

當 `chain` 從 `userResource` 傳播狀態（`idle`、`loading`、`reloading` 或 `error`）時，params 函式不會繼續執行。當 `userResource` 為 `resolved` 或 `local` 時，`chain` 會傳回它的值，而該值本身也可能是 `undefined`。範例用 `chain(userResource)?.companyId` 處理這種情況，因此 `undefined` 值會導致 params 為 `undefined`，`companyResource` 也隨之變成 `idle`。

NOTE: 請把串連得到的值直接作為 params 值傳入，不要把它包在物件裡。像 `{companyId: undefined}` 這樣的 params 值仍然是已定義的值，因此 loader 會以 `undefined` 的 `companyId` 執行，而不是讓資源變成 `idle`。

### 串連與直接讀取資源值的比較

你可能會想在 `params` 裡直接讀取資源的值：

```typescript
{avoid, header: '直接讀取 value()，不傳播狀態'}
const companyResource = resource({
  params: () => {
    const user = userResource.value(); // may be undefined
    return user ? {companyId: user.companyId} : undefined;
  },
  loader: ({params}) => fetchCompany(params.companyId),
});
```

雖然這樣做可行，但從 `params` 傳回 `undefined` 會讓資源變成 `idle`，而不是反映上游資源的實際狀態。使用 `chain` 是較好的做法，因為它能正確鏡像 `loading` 與 `error` 狀態。

只有當下游資源需要執行依賴上游值的非同步工作時，才使用 `chain`。如果你只需要從資源同步衍生出一個值，改用 `computed` 即可。

## 使用 `httpResource` 進行反應式資料擷取 {#reactive-data-fetching-with-httpresource}

[`httpResource`](/guide/http/http-resource) 是 `HttpClient` 的包裝器，它會把請求狀態與回應以訊號的形式提供給你。它透過 Angular 的 HTTP 堆疊（包括攔截器）發出 HTTP 請求。

## 使用快照組合資源 {#resource-composition-with-snapshots}

`ResourceSnapshot` 是資源目前狀態的結構化表示。每個資源都有一個 `snapshot` 屬性，提供其目前狀態的訊號。

```ts
const userId: Signal<string> = getUserId();

const userResource = resource({
  params: () => ({id: userId()}),
  loader: ({params}) => fetchUser(params),
});

const userSnapshot = userResource.snapshot;
```

每個快照都包含一個 `status`，以及一個 `value` 或一個 `error`。

### 使用快照組合資源 {#composing-resources-with-snapshots}

IMPORTANT: `resourceFromSnapshots` 是[實驗性](reference/releases#experimental)功能。它已經可以試用，但在穩定之前仍可能改變。

你可以使用 `resourceFromSnapshots` 從快照建立新的資源。這讓你能與 `computed`、`linkedSignal` 等訊號 API 組合，來轉換資源的行為。

```ts
import {
  Component,
  input,
  linkedSignal,
  resourceFromSnapshots,
  Resource,
  ResourceSnapshot,
} from '@angular/core';
import {httpResource} from '@angular/common/http';

function withPreviousValue<T>(input: Resource<T>): Resource<T> {
  const derived = linkedSignal<ResourceSnapshot<T>, ResourceSnapshot<T>>({
    source: input.snapshot,
    computation: (snap, previous) => {
      if (snap.status === 'loading' && previous && previous.value.status !== 'error') {
        // When the input resource enters loading state, we keep the value
        // from its previous state, if any.
        return {status: 'loading' as const, value: previous.value.value};
      }

// Otherwise we simply forward the state of the input resource.
      return snap;
    },
  });

return resourceFromSnapshots(derived);
}

@Component({/*... */})
export class AwesomeProfile {
  userId = input.required<number>();
  user = withPreviousValue(httpResource(() => `/user/${this.userId()}`));
  // When userId changes, user.value() keeps the old user data until the new one loads
}
```
TIP: 在深入這份完整指南之前，先看看 Angular 的[精華篇](essentials/dependency-injection)。

隨著應用程式成長，開發者經常需要在程式碼庫的不同部分重複使用並共用功能。[依賴注入（DI）](https://en.wikipedia.org/wiki/Dependency_injection)能幫助你達成這一點：你把依賴提供給類別，而不是在類別內部直接建立它們。這讓應用程式的不同部分更容易重複使用，也更容易管理。

依賴注入之所以廣受歡迎，是因為它能讓開發者處理一些常見挑戰，例如：

- **提升程式碼可維護性**：依賴注入促進清晰的關注點分離，讓程式碼更容易重構，也減少重複。
- **可擴充性**：你可以在應用程式的不同部分重複使用模組化功能，讓擴充更容易。
- **更好的測試**：DI 讓單元測試在需要時能用[測試替身](https://en.wikipedia.org/wiki/Test_double)取代真正的實作。

## 依賴注入在 Angular 中如何運作？

依賴是類別運作所需、但不會自己建立的任何物件、值、函式或服務。相反地，你從外部提供它，在應用程式的不同部分之間建立清晰的關係。

你主要透過兩種方式與依賴注入系統互動：

- 你可以*提供*，也就是讓值可供取用。
- 你可以*注入*，也就是索取那些值作為依賴。

在這個脈絡中，「值」可以指任何 JavaScript 值，包括物件、函式或類別實例。常見的注入依賴類型包括：

- **設定值**：與環境相關的常數、API URL、功能旗標等。
- **工廠**：依執行階段條件建立物件或值的函式
- **服務**：提供共用功能、業務邏輯或狀態的類別

Angular 元件和指令會自動參與 DI，意思是你可以把依賴注入它們，也可以讓它們可供注入。

## 什麼是服務？

Angular _服務_是以 `@Service` 裝飾的 TypeScript 類別，讓你可以把該類別的實例作為依賴注入。服務是跨應用程式共用資料與功能最常見的方式。

常見的服務類型包括：

- **資料用戶端**：抽象化向伺服器發出資料取得與異動請求的細節
- **狀態管理**：定義跨多個元件或頁面共用的狀態
- **驗證與授權**：管理使用者驗證、token 儲存與存取控制
- **記錄與錯誤處理**：為記錄或向使用者傳達錯誤狀態建立共用 API
- **事件處理與派送**：處理不屬於特定元件的事件或通知，或把事件和通知派送給元件，遵循[觀察者模式](https://en.wikipedia.org/wiki/Observer_pattern)
- **工具函式**：提供可重複使用的工具函式，例如資料格式化、驗證或計算

以下範例宣告了一個名為 `AnalyticsLogger` 的服務：

```ts
import {Service} from '@angular/core';

@Service()
export class AnalyticsLogger {
  trackEvent(category: string, value: string) {
    console.log('Analytics event logged:', {
      category,
      value,
      timestamp: new Date().toISOString(),
    });
  }
}
```

NOTE: `@Service` 讓這個服務在整個應用程式中以單例的形式可供使用。這是大多數服務的建議做法。

HELPFUL: [`@Service`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator)裝飾器是 `@Injectable({providedIn: 'root'})` 的順手簡寫。

## 使用 `inject()` 注入依賴 {#injecting-dependencies-with-inject}

你可以使用 Angular 的 `inject()` 函式來注入依賴。

以下是一個導覽列的範例，它注入了 `AnalyticsLogger` 和 Angular 的 `Router` 服務，讓使用者在導覽到其他頁面的同時也能追蹤事件。

```typescript
import {Component, inject} from '@angular/core';
import {Router} from '@angular/router';
import {AnalyticsLogger} from './analytics-logger';

@Component({
  selector: 'app-navbar',
  template: `<a href="#" (click)="navigateToDetail($event)">Detail Page</a>`,
})
export class Navbar {
  private router = inject(Router);
  private analytics = inject(AnalyticsLogger);

navigateToDetail(event: Event) {
    event.preventDefault();
    this.analytics.trackEvent('navigation', '/details');
    this.router.navigate(['/details']);
  }
}
```

### `inject()` 可以用在哪裡？ {#where-can-inject-be-used}

你可以在元件、指令或服務的建構期間注入依賴。對 [`inject`](/api/core/inject) 的呼叫可以出現在 `constructor` 中，也可以出現在欄位初始化器中。以下是一些常見範例：

```ts
@Component(/* ... */)
export class MyComponent {
  // ✅ In class field initializer
  private service = inject(MyService);

// ✅ In constructor body
  private anotherService: MyService;

constructor() {
    this.anotherService = inject(MyService);
  }
}
```

```ts
@Directive({...})
export class MyDirective {
  // ✅ In class field initializer
  private element = inject(ElementRef);
}
```

```ts
import {Service, inject} from '@angular/core';
import {HttpClient} from '@angular/common/http';

@Service()
export class MyService {
  // ✅ In a service
  private http = inject(HttpClient);
}
```

```ts
export const authGuard = () => {
  // ✅ In a route guard
  const auth = inject(AuthService);
  return auth.isAuthenticated();
};
```

Angular 用「注入上下文」一詞來描述程式碼中任何可以呼叫 [`inject`](/api/core/inject) 的位置。元件、指令與服務的建構是最常見的情形，詳情請參閱[注入上下文](/guide/di/dependency-injection-context)。

更多資訊請參閱 [inject API 文件](api/core/inject#usage-notes)。

## 後續步驟

現在你已了解 Angular 依賴注入的基本原理，可以開始學習如何建立自己的服務了。

下一篇指南[建立與使用服務](guide/di/creating-and-using-services)將示範：

- 如何用 Angular CLI 或手動建立服務
- `providedIn: 'root'` 模式如何運作
- 如何把服務注入元件和其他服務

這涵蓋了 Angular 應用程式中最常見的服務使用情境。
# 建立與使用服務

服務是可重用的程式碼片段，你可以在整個 Angular 應用程式中共用。你通常會用它們來處理資料擷取、業務邏輯，或其他多個元件需要存取的功能。

## 建立服務

你可以使用 [Angular CLI](tools/cli)，以下列指令建立服務：

```bash
ng generate service CUSTOM_NAME
```

這個指令會在你的 `src` 目錄中，建立一個專屬的 `CUSTOM_NAME.ts` 檔案。

你也可以透過為 TypeScript 類別加上 `@Service()` 裝飾器，來手動建立服務。這告訴 Angular，你可以將該類別用作可注入的依賴。

以下範例定義了一個服務，讓使用者新增與擷取資料：

```ts
{header: "src/app/basic-data-store.ts"}
import {Service} from '@angular/core';

@Service()
export class BasicDataStore {
  private data: string[] = [];

addData(item: string): void {
    this.data.push(item);
  }

getData(): string[] {
    return [...this.data];
  }
}
```

## 服務如何變得可用

服務依預設在根層級提供。當服務在全域提供時，Angular 保證以下三個主要好處：

- **單例實例**：為整個應用程式建立單一、共用的實例。
- **全域可用**：在任何地方自動可存取，無需手動註冊提供者。
- **可搖樹優化**（tree-shaking）：確保若你的程式碼從未明確使用該服務，最終的生產 bundle 就不會包含它。

### 使用 `@Service` 與 `@Injectable` 裝飾器的比較 {#using-the-service-vs-injectable-decorator}

`@Service` 裝飾器是傳統 `@Injectable({ providedIn: 'root' })` 寫法的現代、符合人體工學的簡寫。

請使用這份快速參考，決定哪個裝飾器適合你的情境：

| 功能／需求                                    | `@Service` | `@Injectable`                           |
| --------------------------------------------- | ---------- | --------------------------------------- |
| **`inject()` 函式支援**                       | 是         | 是                                      |
| **以建構子進行依賴注入**                      | ❌ 否      | 是                                      |
| **隱含的根層級單例提供者**                    | 是         | ❌ 否（需要 `{providedIn: 'root'}`）    |
| **進階提供者設定鍵**（`useClass` 等）         | ❌ 否      | 是                                      |
| **自訂初始化工廠**                            | 是         | 是                                      |
| **非根層級作用域**（`platform` 等）           | ❌ 否      | 是                                      |

### 以工廠取代實作

如果你需要控制單例的建立方式，例如依據環境換上不同的實作，請傳入一個 `factory` 函式。

這個工廠會在[注入情境](guide/di/dependency-injection-context)中執行，因此你可以在其中使用 [`inject()`](api/core/inject) 來讀取其他依賴。

以下的 `Analytics` 服務在本機不執行任何動作（no-op），以免事件在開發期間污染主控台。在生產環境中，工廠會讀取一個 `ANALYTICS_ENABLED` token，並傳回一個 `GoogleAnalytics` 子類別，將事件轉送到真正的追蹤器：

```ts
{header: "src/app/analytics.ts"}
import {inject, InjectionToken, Service} from '@angular/core';
import {ANALYTICS_ENABLED} from './token';

@Service({
  factory: () => (inject(ANALYTICS_ENABLED) ? new GoogleAnalytics() : new Analytics()),
})
export class Analytics {
  track(event: string, payload?: Record<string, unknown>) {
    // No-op by default.
  }
}

class GoogleAnalytics extends Analytics {
  override track(event: string, payload?: Record<string, unknown>) {
    // Dispatches an analytics event to Google Analytics
  }
}
```

NOTE: `factory` 選項取代了 `@Injectable` 的 `useClass`、`useValue`、`useExisting` 與 `useFactory` 選項。如果你需要其中任何一項，請繼續使用 `@Injectable`。

### 退出自動提供 {#opting-out-of-automatic-provisioning}

依預設，`@Service` 會在根 injector 提供該類別。如果你想手動提供它，例如將其作用域限定於特定路由或元件，請設定 `autoProvided: false`：

```ts
{header: "src/app/analytics-logger.ts"}
import {Service} from '@angular/core';

@Service({autoProvided: false})
export class AnalyticsLogger {
  trackEvent(name: string) {
    console.log('event:', name);
  }
}
```

接著你需要負責將該服務加到 `providers` 陣列中，就像使用一般的 `@Injectable()` 一樣：

### 何時使用 `@Service`、何時使用 `@Injectable`

當你在建立一個使用 `inject()` 取得其依賴的新單例類別時，請使用 `@Service`。當你需要以下任何一項時，請繼續使用 `@Injectable`：

- **以建構子進行依賴注入**：`@Service` 只支援 [`inject()`](api/core/inject) 函式。
- **進階提供者設定**：例如 `useClass`、`useValue`、`useExisting` 或 `useFactory`。`@Service` 改為提供單一的 `factory` 選項。
- **非根層級作用域**：例如 `providedIn: 'platform'`。

## 注入服務

一旦你以 `providedIn: 'root'` 建立了服務，你就可以使用 `@angular/core` 的 `inject()` 函式，在應用程式中的任何地方注入它。

### 注入到元件中

```typescript
import {Component, inject} from '@angular/core';
import {BasicDataStore} from './basic-data-store';

@Component({
  selector: 'app-example',
  template: `
    <div>
      <p>{{ dataStore.getData() }}</p>
      <button (click)="dataStore.addData('More data')">Add more data</button>
    </div>
  `,
})
export class Example {
  dataStore = inject(BasicDataStore);
}
```

### 注入到另一個服務中

```ts
import {inject, Service} from '@angular/core';
import {AdvancedDataStore} from './advanced-data-store';

@Service()
export class BasicDataStore {
  private advancedDataStore = inject(AdvancedDataStore);
  private data: string[] = [];

addData(item: string): void {
    this.data.push(item);
  }

getData(): string[] {
    return [...this.data, ...this.advancedDataStore.getData()];
  }
}
```

## 後續步驟

雖然 `providedIn: 'root'` 涵蓋了大多數使用情境，Angular 也提供其他方式，讓你為更特殊的情境設定服務：

- **元件專屬實例**：當元件需要各自獨立的服務實例時
- **手動設定**：適用於需要執行階段設定的服務
- **工廠提供者**：依據執行階段條件動態建立服務
- **值提供者**：提供設定物件或常數

你可以在下一篇指南中進一步了解這些進階模式：[定義依賴提供者](/guide/di/defining-dependency-providers)。
# 定義依賴提供者

Angular 提供兩種方式，讓服務可供注入：

1. **自動提供**：使用 `@Injectable` 裝飾器中的 `providedIn`、[`@Service`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator) 裝飾器，或在 `InjectionToken` 設定中提供工廠
2. **手動提供**：使用元件、指令、路由或應用程式設定中的 `providers` 陣列

在[上一篇指南](/guide/di/creating-and-using-services)中，你學到了如何使用 `providedIn: 'root'` 建立服務，這涵蓋了最常見的使用情境。本指南將探討自動與手動提供者設定的其他模式。

## 非類別依賴的自動提供

帶有 `providedIn: 'root'` 的 `@Injectable` 裝飾器對服務（類別）很好用，但你可能需要全域提供其他類型的值，例如設定物件、函式或原始值。Angular 為此提供了 `InjectionToken`。

### 什麼是 InjectionToken？ {#what-is-an-injectiontoken}

`InjectionToken` 是 Angular 依賴注入系統用來唯一識別可注入值的物件。可以把它想成一把特殊的鑰匙，讓你能在 Angular 的 DI 系統中儲存和擷取任何類型的值：

```ts
import {InjectionToken} from '@angular/core';

// Create a token for a string value
export const API_URL = new InjectionToken<string>('api.url');

// Create a token for a function
export const LOGGER = new InjectionToken<(msg: string) => void>('logger.function');

// Create a token for a complex type
export interface Config {
  apiUrl: string;
  timeout: number;
}
export const CONFIG_TOKEN = new InjectionToken<Config>('app.config');
```

NOTE: 字串參數（例如 `'api.url'`）只是一個純粹用於除錯的描述，Angular 是以物件參考來識別 token，而不是這個字串。

### 搭配 `providedIn: 'root'` 的 InjectionToken

帶有 `factory` 的 `InjectionToken`，預設即為 `providedIn: 'root'`（但可以透過 `providedIn` 屬性覆寫）。

```ts
{header: "/app/config.token.ts"}
import {InjectionToken, Component, inject} from '@angular/core';

export interface AppConfig {
  apiUrl: string;
  version: string;
  features: Record<string, boolean>;
}

// Globally available configuration using providedIn
export const APP_CONFIG = new InjectionToken<AppConfig>('app.config', {
  providedIn: 'root',
  factory: () => ({
    apiUrl: 'https://api.example.com',
    version: '1.0.0',
    features: {
      darkMode: true,
      analytics: false,
    },
  }),
});

// No need to add to providers array - available everywhere!
@Component({
  selector: 'app-header',
  template: `<h1>Version: {{ config.version }}</h1>`,
})
export class Header {
  config = inject(APP_CONFIG); // Automatically available
}
```

### 何時該使用帶工廠函式的 InjectionToken

當你無法使用類別、但需要全域提供依賴時，帶工廠函式的 InjectionToken 是理想選擇：

```ts
{header: "/app/logger.token.ts"}
import {InjectionToken, inject} from '@angular/core';
import {APP_CONFIG} from './config.token';

// Logger function type
export type LoggerFn = (level: 'log' | 'warn' | 'error', message: string) => void;

// Global logger function with dependencies
export const LOGGER_FN = new InjectionToken<LoggerFn>('logger.function', {
  providedIn: 'root',
  factory: () => {
    const config = inject(APP_CONFIG);

return (level: 'log' | 'warn' | 'error', message: string) => {
      if (config.features.logging !== false) {
        console[level](`[${new Date().toISOString()}] ${message}`);
      }
    };
  },
});
```

```ts
{header: "/app/storage.token.ts"}
// Providing browser APIs as tokens
export const LOCAL_STORAGE = new InjectionToken<Storage>('localStorage', {
  // providedIn: 'root' is configured as the default
  factory: () => window.localStorage,
});

export const SESSION_STORAGE = new InjectionToken<Storage>('sessionStorage', {
  providedIn: 'root',
  factory: () => window.sessionStorage,
});
```

```ts
{header: "/app/feature-flags.token.ts"}
// Complex configuration with runtime logic
export const FEATURE_FLAGS = new InjectionToken<Map<string, boolean>>('feature.flags', {
  providedIn: 'root',
  factory: () => {
    const flags = new Map<string, boolean>();

// Parse from environment or URL params
    const urlParams = new URLSearchParams(window.location.search);
    const enableBeta = urlParams.get('beta') === 'true';

flags.set('betaFeatures', enableBeta);
    flags.set('darkMode', true);
    flags.set('newDashboard', false);

return flags;
  },
});
```

這種做法有幾個優點：

- **不需要手動設定提供者**：運作方式就像服務的 `providedIn: 'root'` 一樣
- **可搖樹**：只有在實際被使用時才會包含進來
- **型別安全**：對非類別值提供完整的 TypeScript 支援
- **可以注入其他依賴**：工廠函式可以使用 `inject()` 來存取其他服務

## 了解手動提供者設定

當你需要比 `providedIn: 'root'` 更強的控制時，可以手動設定提供者。在以下情況，透過 `providers` 陣列手動設定很有用：

1. **服務沒有 `providedIn`**：沒有自動提供的服務必須手動提供
2. **你想要新的實例**：在元件／指令層級建立獨立的實例，而不是用共用的那個
3. **你需要執行階段設定**：當服務行為取決於執行階段的值時
4. **你提供的是非類別值**：設定物件、函式或原始值

### 範例：沒有 `providedIn` 的服務

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

// Service without providedIn
@Injectable()
export class LocalDataStore {
  private data: string[] = [];

addData(item: string) {
    this.data.push(item);
  }
}

// Component must provide it
@Component({
  selector: 'app-example',
  // A provider is required here because the `LocalDataStore` service has no providedIn.
  providers: [LocalDataStore],
  template: `...`,
})
export class Example {
  dataStore = inject(LocalDataStore);
}
```

### 範例：建立元件專屬的實例

帶有 `providedIn: 'root'` 的服務可以在元件層級被覆寫。這會把服務實例與元件的生命週期綁在一起。因此，當元件被銷毀時，所提供的服務也會一併被銷毀。

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

@Injectable({providedIn: 'root'})
export class DataStore {
  private data: string[] = [];
}

// This component gets its own instance
@Component({
  selector: 'app-isolated',
  // Creates new instance of `DataStore` rather than using the root-provided instance.
  providers: [DataStore],
  template: `...`,
})
export class Isolated {
  dataStore = inject(DataStore); // Component-specific instance
}
```

## Angular 中的注入器階層 {#injector-hierarchy-in-angular}

Angular 的依賴注入系統是階層式的。當元件請求某個依賴時，Angular 會從該元件的注入器開始，沿著樹往上尋找，直到找到該依賴的提供者為止。應用程式樹中的每個元件都可以有自己的注入器，這些注入器形成一個與元件樹相對應的階層。

這個階層帶來以下能力：

- **限定範圍的實例**：應用程式的不同部分可以擁有同一個服務的不同實例
- **覆寫行為**：子元件可以覆寫父元件的提供者
- **記憶體效率**：服務只在需要的地方被實例化

在 Angular 中，任何帶有元件或指令的元素，都可以把值提供給它的所有後代。

```mermaid
graph TD
    subgraph platform
        subgraph root
            direction TB
            A[SocialApp] --> B[UserProfile]
            A --> C[FriendList]
            C --> D[FriendEntry]
        end
    end
```

在上面的範例中：

1. `SocialApp` 可以把值提供給 `UserProfile` 和 `FriendList`
2. `FriendList` 可以把值提供給 `FriendEntry` 注入，但無法提供給 `UserProfile` 注入，因為它不在同一棵樹中

## 宣告提供者

可以把 Angular 的依賴注入系統想成雜湊表或字典。每個提供者設定物件都定義了一組鍵值對：

- **鍵**（提供者識別項）：你用來請求依賴的唯一識別項
- **值**：當該 token 被請求時，Angular 應該傳回的內容

手動提供依賴時，你通常會看到這種簡寫語法：

```typescript
import {Component} from '@angular/core';
import {LocalService} from './local-service';

@Component({
  selector: 'app-example',
  providers: [LocalService], // Service without providedIn
})
export class Example {}
```

這其實是一種更詳細的提供者設定的簡寫：

```ts
{
  // This is the shorthand version
  providers: [LocalService],

// This is the full version
  providers: [
    { provide: LocalService, useClass: LocalService }
  ]
}
```

### 提供者設定物件

每個提供者設定物件都有兩個主要部分：

1. **提供者識別項**：Angular 用來取得依賴的唯一鍵（透過 `provide` 屬性設定）
2. **值**：你想讓 Angular 取得的實際依賴，依所需的類型用不同的鍵來設定：
   - `useClass`：提供一個 JavaScript 類別
   - `useValue`：提供一個靜態值
   - `useFactory`：提供一個傳回值的工廠函式
   - `useExisting`：提供一個既有提供者的別名

### 提供者識別項

提供者識別項讓 Angular 的依賴注入（DI）系統能透過唯一 ID 擷取依賴。你可以用兩種方式產生提供者識別項：

1. [類別名稱](#class-names)
2. [Injection token](#injection-tokens)

#### 類別名稱 {#class-names}

類別名稱直接使用匯入的類別作為識別項：

```typescript
import {Component} from '@angular/core';
import {LocalService} from './local-service';

@Component({
  selector: 'app-example',
  providers: [{provide: LocalService, useClass: LocalService}],
})
export class Example {
  /* ... */
}
```

類別同時充當識別項和實作，這就是 Angular 提供 `providers: [LocalService]` 這種簡寫的原因。

#### Injection token {#injection-tokens}

Angular 提供內建的 [`InjectionToken`](api/core/InjectionToken) 類別，用來為可注入的值建立唯一的物件參考，或在你想為同一個介面提供多個實作時使用。

```ts
{header: "/app/tokens.ts"}
import {InjectionToken} from '@angular/core';
import {DataService} from './data-service.interface';

export const DATA_SERVICE_TOKEN = new InjectionToken<DataService>('DataService');
```

NOTE: 字串 `'DataService'` 只是一個純粹用於除錯的描述。Angular 是以物件參考來識別 token，而不是這個字串。

在你的提供者設定中使用這個 token：

```typescript
import {Component, inject} from '@angular/core';
import {LocalDataService} from './local-data-service';
import {DATA_SERVICE_TOKEN} from './tokens';

@Component({
  selector: 'app-example',
  providers: [{provide: DATA_SERVICE_TOKEN, useClass: LocalDataService}],
})
export class Example {
  private dataService = inject(DATA_SERVICE_TOKEN);
}
```

#### TypeScript 介面可以作為注入的識別項嗎？

TypeScript 介面無法用於注入，因為它們在執行階段並不存在：

```ts
// ❌ This won't work!
interface DataService {
  getData(): string[];
}

// Interfaces disappear after TypeScript compilation
@Component({
  providers: [
    {provide: DataService, useClass: LocalDataService}, // Error!
  ],
})
export class Example {
  private dataService = inject(DataService); // Error!
}

// ✅ Use InjectionToken instead
export const DATA_SERVICE_TOKEN = new InjectionToken<DataService>('DataService');

@Component({
  providers: [{provide: DATA_SERVICE_TOKEN, useClass: LocalDataService}],
})
export class Example {
  private dataService = inject(DATA_SERVICE_TOKEN); // Works!
}
```

InjectionToken 提供了一個 Angular DI 系統可以在執行階段使用的值，同時透過 TypeScript 的泛型型別參數維持型別安全。

### 提供者值的類型

#### useClass

`useClass` 把一個 JavaScript 類別提供為依賴。使用簡寫語法時，這是預設行為：

```ts
// Shorthand
providers: [DataService];

// Full syntax
providers: [{provide: DataService, useClass: DataService}];

// Different implementation
providers: [{provide: DataService, useClass: MockDataService}];

// Conditional implementation
providers: [
  {
    provide: StorageService,
    useClass: environment.production ? CloudStorageService : LocalStorageService,
  },
];
```

#### 實務範例：替換 Logger

你可以替換實作來擴充功能：

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

// Base logger
@Injectable()
export class Logger {
  log(message: string) {
    console.log(message);
  }
}

// Enhanced logger with timestamp
@Injectable()
export class BetterLogger extends Logger {
  override log(message: string) {
    super.log(`[${new Date().toISOString()}] ${message}`);
  }
}

// Logger that includes user context
@Injectable()
export class EvenBetterLogger extends Logger {
  private userService = inject(UserService);

override log(message: string) {
    const name = this.userService.user.name;
    super.log(`Message to ${name}: ${message}`);
  }
}

// In your component
@Component({
  selector: 'app-example',
  providers: [
    UserService, // EvenBetterLogger needs this
    {provide: Logger, useClass: EvenBetterLogger},
  ],
})
export class Example {
  private logger = inject(Logger); // Gets EvenBetterLogger instance
}
```

#### useValue

`useValue` 把任何 JavaScript 資料型別提供為靜態值：

```ts
providers: [
  {provide: API_URL_TOKEN, useValue: 'https://api.example.com'},
  {provide: MAX_RETRIES_TOKEN, useValue: 3},
  {provide: FEATURE_FLAGS_TOKEN, useValue: {darkMode: true, beta: false}},
];
```

IMPORTANT: TypeScript 型別和介面不能作為依賴值。它們只存在於編譯時期。

#### 實務範例：應用程式設定

`useValue` 的一個常見使用情境是提供應用程式設定：

```ts
// Define configuration interface
export interface AppConfig {
  apiUrl: string;
  appTitle: string;
  features: {
    darkMode: boolean;
    analytics: boolean;
  };
}

// Create injection token
export const APP_CONFIG = new InjectionToken<AppConfig>('app.config');

// Define configuration
const appConfig: AppConfig = {
  apiUrl: 'https://api.example.com',
  appTitle: 'My Application',
  features: {
    darkMode: true,
    analytics: false,
  },
};

// Provide in bootstrap
bootstrapApplication(AppComponent, {
  providers: [{provide: APP_CONFIG, useValue: appConfig}],
});

// Use in component
@Component({
  selector: 'app-header',
  template: `<h1>{{ title }}</h1>`,
})
export class Header {
  private config = inject(APP_CONFIG);
  title = this.config.appTitle;
}
```

#### useFactory

`useFactory` 提供一個函式，用來產生供注入的新值：

```ts
export const loggerFactory = (config: AppConfig) => {
  return new LoggerService(config.logLevel, config.endpoint);
};

providers: [
  {
    provide: LoggerService,
    useFactory: loggerFactory,
    deps: [APP_CONFIG], // Dependencies for the factory function
  },
];
```

你可以把工廠的依賴標記為可選：

```ts
import {Optional} from '@angular/core';

providers: [
  {
    provide: MyService,
    useFactory: (required: RequiredService, optional?: OptionalService) => {
      return new MyService(required, optional || new DefaultService());
    },
    deps: [RequiredService, [new Optional(), OptionalService]],
  },
];
```

#### 實務範例：以設定為基礎的 API 用戶端

以下是一個完整範例，示範如何使用工廠來建立帶有執行階段設定的服務：

```ts
// Service that needs runtime configuration
class ApiClient {
  constructor(
    private http: HttpClient,
    private baseUrl: string,
    private rateLimitMs: number,
  ) {}

async fetchData(endpoint: string) {
    // Apply rate limiting based on user tier
    await this.applyRateLimit();
    return this.http.get(`${this.baseUrl}/${endpoint}`);
  }

private async applyRateLimit() {
    // Simplified example - real implementation would track request timing
    return new Promise((resolve) => setTimeout(resolve, this.rateLimitMs));
  }
}

// Factory function that configures based on user tier
import {inject, Component} from '@angular/core';
import {HttpClient} from '@angular/common/http';
const apiClientFactory = () => {
  const http = inject(HttpClient);
  const userService = inject(UserService);

// Assuming userService provides these values
  const baseUrl = userService.getApiBaseUrl();
  const rateLimitMs = userService.getRateLimit();

return new ApiClient(http, baseUrl, rateLimitMs);
};

// Provider configuration
export const apiClientProvider = {
  provide: ApiClient,
  useFactory: apiClientFactory,
};

// Usage in component
@Component({
  selector: 'app-dashboard',
  providers: [apiClientProvider],
})
export class Dashboard {
  private apiClient = inject(ApiClient);
}
```

#### useExisting

`useExisting` 為已經定義的提供者建立別名。兩個 token 都會傳回同一個實例：

```ts
providers: [
  NewLogger, // The actual service
  {provide: OldLogger, useExisting: NewLogger}, // The alias
];
```

IMPORTANT: 不要把 `useExisting` 和 `useClass` 混淆。`useClass` 會建立各自獨立的實例，而 `useExisting` 確保你取得的是同一個單例實例。

### 多重提供者

當多個提供者要為同一個 token 貢獻值時，使用 `multi: true` 旗標：

```ts
export const INTERCEPTOR_TOKEN = new InjectionToken<Interceptor[]>('interceptors');

providers: [
  {provide: INTERCEPTOR_TOKEN, useClass: AuthInterceptor, multi: true},
  {provide: INTERCEPTOR_TOKEN, useClass: LoggingInterceptor, multi: true},
  {provide: INTERCEPTOR_TOKEN, useClass: RetryInterceptor, multi: true},
];
```

當你注入 `INTERCEPTOR_TOKEN` 時，你會收到一個陣列，其中包含全部三個攔截器的實例。

## 你可以在哪些地方指定提供者？

Angular 提供多個可以註冊提供者的層級，每個層級對範圍、生命週期和效能都有不同的影響：

- [**應用程式啟動**](#application-bootstrap)：隨處可用的全域單例
- [**在元素上**（元件或指令）](#component-or-directive-providers)：特定元件樹的隔離實例
- [**路由**](#route-providers)：延遲載入模組的功能專屬服務

### 應用程式啟動 {#application-bootstrap}

在以下情況，把應用程式層級的提供者放在 `bootstrapApplication` 中：

- **服務跨多個功能區域使用**：例如 HTTP 用戶端、記錄或驗證等應用程式許多部分都需要的服務
- **你想要真正的單例**：由整個應用程式共用的一個實例
- **服務沒有元件專屬的設定**：在任何地方運作方式都相同的通用工具
- **你提供的是全域設定**：API 端點、功能旗標或環境設定

```ts
{header: "main.ts"}
bootstrapApplication(App, {
  providers: [
    {provide: API_BASE_URL, useValue: 'https://api.example.com'},
    {provide: INTERCEPTOR_TOKEN, useClass: AuthInterceptor, multi: true},
    LoggingService, // Used throughout the app
    {provide: ErrorHandler, useClass: GlobalErrorHandler},
  ],
});
```

**優點**：

- 單一實例可減少記憶體用量
- 隨處可用，不需要額外設定
- 更容易管理全域狀態

**缺點**：

- 永遠會包含在你的 JavaScript bundle 中，即使該值從未被注入
- 無法輕易地依功能客製化
- 較難單獨測試個別元件

#### 為什麼要在啟動時提供，而不是使用 `providedIn: 'root'`？

在以下情況，你可能會想在啟動時提供提供者：

- 提供者有副作用（例如安裝用戶端路由器）
- 提供者需要設定（例如路由）
- 你使用的是 Angular 的 `provideSomething` 模式（例如 `provideRouter`、`provideHttpClient`）

### 元件或指令提供者 {#component-or-directive-providers}

在以下情況，使用元件或指令提供者：

- **服務有元件專屬的狀態**：表單驗證器、元件專屬的快取或 UI 狀態管理器
- **你需要隔離的實例**：每個元件需要自己的服務副本
- **服務只被一棵元件樹使用**：不需要全域存取的專門服務
- **你在建立可重複使用的元件**：應該能以自己的服務獨立運作的元件

```typescript
// Specialized form component with its own validation service
@Component({
  selector: 'app-advanced-form',
  providers: [
    FormValidationService, // Each form gets its own validator
    {provide: FORM_CONFIG, useValue: {strictMode: true}},
  ],
})
export class AdvancedForm {}

// Modal component with isolated state management
@Component({
  selector: 'app-modal',
  providers: [
    ModalStateService, // Each modal manages its own state
  ],
})
export class Modal {}
```

**優點**：

- 更好的封裝與隔離
- 更容易單獨測試元件
- 多個實例可以以不同設定共存

**缺點**：

- 每個元件都會建立新實例（記憶體用量較高）
- 元件之間沒有共用狀態
- 需要在每個需要的地方提供
- 永遠會和元件或指令包含在同一個 JavaScript bundle 中，即使該值從未被注入

NOTE: 如果同一個元素上的多個指令提供了同一個 token，其中一個會勝出，但哪一個會勝出並未定義。

### 路由提供者 {#route-providers}

路由層級的提供者適用於：

- **功能專屬的服務**：只在特定路由或功能模組中需要的服務
- **延遲載入模組的依賴**：應該只隨特定功能一起載入的服務
- **路由專屬的設定**：依應用程式區域而不同的設定

```ts
{header: "routes.ts"}
export const routes: Routes = [
  {
    path: 'admin',
    providers: [
      AdminService, // Only loaded with admin routes
      {provide: FEATURE_FLAGS, useValue: {adminMode: true}},
    ],
    loadChildren: () => import('./admin/admin.routes'),
  },
  {
    path: 'shop',
    providers: [
      ShoppingCartService, // Isolated shopping state
      PaymentService,
    ],
    loadChildren: () => import('./shop/shop.routes'),
  },
];
```

在路由層級提供的服務，可供該路由內的所有元件和指令使用，也可供它的守衛和解析器使用。

由於這些服務是在路由的元件之外獨立實例化的，它們無法直接存取路由專屬的資訊。

## 函式庫作者模式

建立 Angular 函式庫時，你經常需要為使用者提供彈性的設定選項，同時維持乾淨的 API。Angular 自己的函式庫就示範了達成此目標的強大模式。

### `provide` 模式

函式庫作者可以匯出傳回提供者設定的函式，而不是要求使用者手動設定複雜的提供者：

```ts
{header: "/libs/analytics/src/providers.ts"}
import {InjectionToken, Provider, inject} from '@angular/core';

// Configuration interface
export interface AnalyticsConfig {
  trackingId: string;
  enableDebugMode?: boolean;
  anonymizeIp?: boolean;
}

// Internal token for configuration
const ANALYTICS_CONFIG = new InjectionToken<AnalyticsConfig>('analytics.config');

// Main service that uses the configuration
export class AnalyticsService {
  private config = inject(ANALYTICS_CONFIG);

track(event: string, properties?: any) {
    // Implementation using config
  }
}

// Provider function for consumers
export function provideAnalytics(config: AnalyticsConfig): Provider[] {
  return [{provide: ANALYTICS_CONFIG, useValue: config}, AnalyticsService];
}
```

```ts
{header: "main.ts"}
// Usage in consumer app
bootstrapApplication(App, {
  providers: [
    provideAnalytics({
      trackingId: 'GA-12345',
      enableDebugMode: !environment.production,
    }),
  ],
});
```

### 帶選項的進階提供者模式

對於更複雜的情境，你可以結合多種設定方式：

```ts
{header: "/libs/http-client/src/provider.ts"}
import {Provider, InjectionToken, inject} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';

// Feature flags for optional functionality
export enum HttpFeatures {
  Interceptors = 'interceptors',
  Caching = 'caching',
  Retry = 'retry',
}

// Configuration interfaces
export interface HttpConfig {
  baseUrl?: string;
  timeout?: number;
  headers?: Record<string, string>;
}

export interface RetryConfig {
  maxAttempts: number;
  delayMs: number;
}

// Internal tokens
const HTTP_CONFIG = new InjectionToken<HttpConfig>('http.config');
const RETRY_CONFIG = new InjectionToken<RetryConfig>('retry.config');
const HTTP_FEATURES = new InjectionToken<Set<HttpFeatures>>('http.features');

// Core service
class HttpClientService {
  private config = inject(HTTP_CONFIG, {optional: true});
  private features = inject(HTTP_FEATURES);

get(url: string) {
    // Use config and check features
  }
}

// Feature services
class RetryInterceptor {
  private config = inject(RETRY_CONFIG);
  // Retry logic
}

class CacheInterceptor {
  // Caching logic
}

// Main provider function
export function provideHttpClient(config?: HttpConfig, ...features: HttpFeature[]): Provider[] {
  const providers: Provider[] = [
    {provide: HTTP_CONFIG, useValue: config || {}},
    {provide: HTTP_FEATURES, useValue: new Set(features.map((f) => f.kind))},
    HttpClientService,
  ];

// Add feature-specific providers
  features.forEach((feature) => {
    providers.push(...feature.providers);
  });

return providers;
}

// Feature configuration functions
export interface HttpFeature {
  kind: HttpFeatures;
  providers: Provider[];
}

export function withInterceptors(...interceptors: any[]): HttpFeature {
  return {
    kind: HttpFeatures.Interceptors,
    providers: interceptors.map((interceptor) => ({
      provide: INTERCEPTOR_TOKEN,
      useClass: interceptor,
      multi: true,
    })),
  };
}

export function withCaching(): HttpFeature {
  return {
    kind: HttpFeatures.Caching,
    providers: [CacheInterceptor],
  };
}

export function withRetry(config: RetryConfig): HttpFeature {
  return {
    kind: HttpFeatures.Retry,
    providers: [{provide: RETRY_CONFIG, useValue: config}, RetryInterceptor],
  };
}

// Consumer usage with multiple features
bootstrapApplication(App, {
  providers: [
    provideHttpClient(
      {baseUrl: 'https://api.example.com'},
      withInterceptors(AuthInterceptor, LoggingInterceptor),
      withCaching(),
      withRetry({maxAttempts: 3, delayMs: 1000}),
    ),
  ],
});
```

### 為什麼要用提供者函式，而不是直接設定？

提供者函式為函式庫作者帶來幾個優點：

1. **封裝**：內部 token 和實作細節保持私密
2. **型別安全**：TypeScript 確保編譯時期的設定正確
3. **彈性**：用 `with*` 模式輕鬆組合功能
4. **面向未來**：內部實作可以變更，而不會破壞使用者的程式
5. **一致性**：與 Angular 自己的模式一致（例如 `provideRouter`、`provideHttpClient` 等）

這個模式在 Angular 自己的函式庫中被廣泛使用，被視為需要提供可設定服務的函式庫作者的最佳實務。
# 延遲載入服務

IMPORTANT: 若要讓延遲載入運作，你載入的服務必須是自動提供的。請用 `@Injectable({providedIn: 'root'})` 或 [`@Service()`](guide/di/creating-and-using-services#using-the-service-vs-injectable-decorator) 裝飾它。若沒有自動提供，Angular 在服務載入後就無法建構它。

Angular 的 `injectAsync` 函式讓你按需載入服務，只在真正需要時才載入。當服務依賴大型函式庫或不常使用的功能、而你不想在初始頁面載入時就付出這個成本時，這非常有用。

當你使用 `injectAsync` 時，服務的程式碼會被你的打包工具拆成獨立的 JavaScript chunk，在你第一次索取實例時下載。載入後，Angular 會透過一般的 DI 系統解析該服務，因此它仍然可以依賴其他可注入項，行為也和任何其他單例一樣。

## 延遲注入服務

想像一個依賴厚重試算表函式庫的 `ReportExporter`。大多數使用者只會開啟報表，只有少數人會點擊 **Export**。按需載入匯出器：

```typescript
import {Component, injectAsync} from '@angular/core';

@Component({
  selector: 'app-report',
  template: `<button (click)="export()">Export</button>`,
})
export class Report {
  private exporter = injectAsync(() => import('./report-exporter').then((m) => m.ReportExporter));

async export() {
    const exporter = await this.exporter();
    exporter.export();
  }
}
```

第一次呼叫 `this.exporter()` 會觸發動態匯入，並從 DI 解析該服務。後續呼叫會重複使用同一個 promise，因此 chunk 只會擷取一次。

如果延遲載入的服務是[預設匯出](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/export#using_the_default_export)，可以直接傳入動態匯入，Angular 會幫你解開 `default`：

```ts
{header: "report-exporter.ts"}
@Service()
export default class ReportExporter {
  /* … */
}
```

```ts
{header: "report.ts"}
private exporter = injectAsync(() => import('./report-exporter'));
```

## 預先擷取依賴 {#prefetching-the-dependency}

依預設，延遲的 chunk 只在你叫用傳回的函式時才會擷取。你可以在選項中傳入 `prefetch` 觸發器，讓下載更早開始。觸發器是任何傳回 `Promise` 的函式，當它解析完成時，Angular 就會啟動載入器。

Angular 內建了 `onIdle` 觸發器，它會等到瀏覽器閒置時才觸發：

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

@Component({/* … */})
export class Report {
  private exporter = injectAsync(() => import('./report-exporter').then((m) => m.ReportExporter), {
    prefetch: onIdle,
  });
}
```

你也可以為 `onIdle` 設定最長等待時間，讓預先擷取在已知的時間範圍內一定會發生，即使頁面很忙也一樣：

```ts
injectAsync(loader, {prefetch: () => onIdle({timeout: 1_000})});
```

NOTE: 預先擷取是機會性的。如果使用者在預先擷取觸發前就叫用該功能，Angular 仍會立即載入依賴，並在準備好時儘快解析你的 `await`。

## 提供自訂預先擷取觸發器

`PrefetchTrigger` 就只是一個傳回 promise 的函式，promise 一解析完成，載入器就會執行。用它來把預先擷取與你自己的訊號對齊，例如懸停事件或排程器的 tick：

```ts
import {PrefetchTrigger} from '@angular/core';

export function onHover(target: HTMLElement): PrefetchTrigger {
  return () =>
    new Promise<void>((resolve) => {
      target.addEventListener('pointerenter', () => resolve(), {once: true});
    });
}
```
# 注入上下文

依賴注入（DI）系統仰賴一個執行階段上下文，在這個上下文中，目前的注入器可供使用。

這表示注入器只有在你於這個上下文中執行程式碼時才會運作。

在以下情境中，你會有可用的注入上下文：

- 在由 DI 系統實例化的類別（例如 `@Injectable` 或 `@Component`）建構期間（透過 `constructor`）。
- 在這類類別的欄位初始化器中。
- 在為 `Provider` 或 `@Injectable` 的 `useFactory` 指定的工廠函式中。
- 在為 `InjectionToken` 指定的 `factory` 函式中。
- 在於注入上下文中執行的堆疊框架內。

知道自己何時處於注入上下文中，你就能使用 [`inject`](api/core/inject) 函式來取得依賴。

NOTE: 關於在類別建構子和欄位初始化器中使用 `inject()` 的基本範例，請參閱[總覽指南](/guide/di#where-can-inject-be-used)。

## 上下文中的堆疊框架

有些 API 被設計成在注入上下文中執行。例如路由守衛就是如此。這讓你可以在守衛函式中使用 [`inject`](api/core/inject) 來存取服務。

以下是一個 `CanActivateFn` 的範例：

```ts
{highlight: [3]}
const canActivateTeam: CanActivateFn = (
  route: ActivatedRouteSnapshot,
  state: RouterStateSnapshot,
) => {
  return inject(PermissionsService).canActivate(inject(UserToken), route.params.id);
};
```

## 在注入上下文中執行 {#run-within-an-injection-context}

如果你需要在注入上下文中執行某個函式，但自己目前並不在這樣的上下文中，可以使用 `runInInjectionContext`。
這需要能存取一個注入器，例如 `EnvironmentInjector`：

```ts
{highlight: [7], header:"hero.service.ts"}
@Service()
export class HeroService {
  private environmentInjector = inject(EnvironmentInjector);

someMethod() {
    runInInjectionContext(this.environmentInjector, () => {
      inject(SomeService); // Do what you need with the injected service
    });
  }
}
```

請注意，只有當注入器能解析所請求的 token 時，[`inject`](/api/core/inject) 才會傳回實例。

## 斷言上下文 {#asserts-the-context}

Angular 提供 `assertInInjectionContext` 輔助函式，用來驗證目前的上下文是注入上下文，若不是則擲出清楚的錯誤。傳入呼叫端函式的參考，讓錯誤訊息指向正確的 API 入口點。這會產生比預設的通用注入錯誤更清楚、更可操作的訊息。

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

export function injectNativeElement<T extends Element>(): T {
  assertInInjectionContext(injectNativeElement);
  return inject(ElementRef).nativeElement;
}
```

接著你可以**從注入上下文中**（建構子、欄位初始化器、提供者工廠，或透過 `runInInjectionContext` 執行的程式碼）呼叫這個輔助函式：

```ts
import {Component, inject} from '@angular/core';
import {injectNativeElement} from './dom-helpers';

@Component({/* … */})
export class PreviewCard {
  readonly hostEl = injectNativeElement<HTMLElement>(); // Field initializer runs in an injection context.

onAction() {
    const anotherRef = injectNativeElement<HTMLElement>(); // Fails: runs outside an injection context.
  }
}
```

## 在上下文之外使用 DI

如果你在注入上下文之外呼叫 [`inject`](api/core/inject) 或 `assertInInjectionContext`，Angular 會擲出[錯誤 NG0203](/errors/NG0203)。
# 階層式注入器

本指南深入說明 Angular 的階層式依賴注入系統，包括解析規則、修飾符和進階模式。

NOTE: 關於注入器階層和提供者範圍的基本概念，請參閱[定義依賴提供者指南](guide/di/defining-dependency-providers#injector-hierarchy-in-angular)。

## 注入器階層的類型 {#types-of-injector-hierarchies}

Angular 有兩種注入器階層：

| 注入器階層                      | 詳細資訊                                                                                                                                                                  |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `EnvironmentInjector` 階層      | 使用 `@Service()` 或 `ApplicationConfig` 中的 `providers` 陣列，在此階層中設定 `EnvironmentInjector`。                                                                    |
| `ElementInjector` 階層          | 在每個 DOM 元素上隱含地建立。`ElementInjector` 預設是空的，除非你在 `@Directive()` 或 `@Component()` 的 `providers` 屬性中設定它。                                       |
對於以 `NgModule` 為基礎的應用程式，你可以使用 `@NgModule()` 或 `@Injectable()` 註記，透過 `ModuleInjector` 階層提供依賴。
### `EnvironmentInjector`

`EnvironmentInjector` 可以用以下兩種方式之一來設定：

- `@Service()`
- `ApplicationConfig` 的 `providers` 陣列
使用 `@Service()` 裝飾器比使用 `ApplicationConfig` 的 `providers` 陣列更可取。有了 `@Service`，最佳化工具可以執行搖樹優化，移除你的應用程式沒有使用的服務。如此能產生更小的 bundle。

搖樹優化對函式庫特別有用，因為使用該函式庫的應用程式可能不需要注入它。
`EnvironmentInjector` 由 `ApplicationConfig.providers` 設定。

使用 `@Service()` 提供服務的方式如下：

```ts
{highlight:[4]}
import {Service} from '@angular/core';

@Service() // <--provides this service in the root EnvironmentInjector
export class ItemService {
  name = 'telephone';
}
```

`@Service()` 或 `@Injectable()` 裝飾器用來標識服務類別。

### ModuleInjector

對於以 `NgModule` 為基礎的應用程式，ModuleInjector 可以用以下兩種方式之一來設定：

- `@Service()` 裝飾器，
- 以 `@Injectable()` 的 `providedIn` 屬性指向 `root` 或 `platform`
- `@NgModule()` 的 `providers` 陣列

`ModuleInjector` 由 `@NgModule.providers` 和 `NgModule.imports` 屬性設定。`ModuleInjector` 是沿著 `NgModule.imports` 遞迴追蹤可觸及的所有 providers 陣列攤平後的結果。

延遲載入其他 `@NgModules` 時，會建立子 `ModuleInjector` 階層。

### 平台注入器

在 `root` 之上還有兩個注入器：一個額外的 `EnvironmentInjector` 和 `NullInjector()`。

想想 Angular 如何以 `main.ts` 中的以下程式碼啟動應用程式：

```ts
bootstrapApplication(App, appConfig);
```

`bootstrapApplication()` 方法會建立平台注入器的一個子注入器，它由 `ApplicationConfig` 實例設定。
這就是 `root` `EnvironmentInjector`。

`bootstrapApplication()` 方法也會建立（或重複使用）平台注入器，其中包含平台專屬的依賴。
這讓多個應用程式可以共用一個平台設定。
例如，無論你執行多少個應用程式，瀏覽器都只有一個網址列。
你可以使用 `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 PlatformLocation => providedIn 'platform'
    rootInjector: root EnvironmentInjector<br>(configured by AppConfig)<br>has things for your app => bootstrapApplication(..., AppConfig)
    nullInjector: NullInjector<br>always throws an error unless<br>you use @Optional()

direction BT
    rootInjector --> elementInjector
    elementInjector --> nullInjector
```

雖然 `root` 這個名稱是一個特殊的別名，其他 `EnvironmentInjector` 階層沒有別名。
你可以在動態載入元件建立時建立 `EnvironmentInjector` 階層，例如透過 Router，它會建立子 `EnvironmentInjector` 階層。

所有請求都會向上轉送到根注入器，無論你是用傳給 `bootstrapApplication()` 方法的 `ApplicationConfig` 實例來設定它，或是在各個服務本身以 `root` 註冊所有提供者。
如果你在 `bootstrapApplication` 的 `ApplicationConfig` 中設定了一個全應用程式的提供者，它會覆寫在 `@Injectable()` 詮釋資料中為 `root` 設定的提供者。
你可以這樣做，來為一個與多個應用程式共用的服務設定非預設的提供者。

以下是一個範例：元件路由設定把非預設的[位置策略](guide/routing/common-router-tasks#locationstrategy-and-browser-url-styles)提供者列在 `ApplicationConfig` 的 `providers` 清單中。

```ts
providers: [{provide: LocationStrategy, useClass: HashLocationStrategy}];
```

對於以 `NgModule` 為基礎的應用程式，請在 `AppModule` 的 `providers` 中設定全應用程式的提供者。
### `ElementInjector`

Angular 會為每個 DOM 元素隱含地建立 `ElementInjector` 階層。

在 `@Component()` 裝飾器中使用它的 `providers` 或 `viewProviders` 屬性提供服務，就能設定一個 `ElementInjector`。
例如，以下 `TestComponent` 透過如下方式提供服務來設定 `ElementInjector`：

```ts
{highlight:[3]}
@Component({
  /* … */
  providers: [{ provide: ItemService, useValue: { name: 'lamp' } }]
})
export class TestComponent
```

HELPFUL: 請參閱[解析規則](#resolution-rules)一節，了解 `EnvironmentInjector` 樹、`ModuleInjector` 和 `ElementInjector` 樹之間的關係。

當你在元件中提供服務時，該服務透過該元件實例的 `ElementInjector` 可供使用。
根據[解析規則](#resolution-rules)一節所述的可見性規則，它在子元件／指令中也可能可見。

當元件實例被銷毀時，該服務實例也會一併被銷毀。

#### `@Directive()` 與 `@Component()`

元件是指令的一種特殊類型，意思是就像 `@Directive()` 有 `providers` 屬性一樣，`@Component()` 也有。
這表示指令和元件都可以使用 `providers` 屬性來設定提供者。
當你使用 `providers` 屬性為元件或指令設定提供者時，該提供者屬於該元件或指令的 `ElementInjector`。
同一個元素上的元件和指令共用一個注入器。

## 解析規則 {#resolution-rules}

為元件／指令解析 token 時，Angular 會分兩個階段進行：

1. 對照它在 `ElementInjector` 階層中的父層。
2. 對照它在 `EnvironmentInjector` 階層中的父層。

當元件宣告一個依賴時，Angular 會試圖用它自己的 `ElementInjector` 來滿足該依賴。
如果元件的注入器缺少該提供者，它會把請求往上傳給父元件的 `ElementInjector`。

請求會不斷向上轉送，直到 Angular 找到能處理該請求的注入器，或用盡所有祖先 `ElementInjector` 階層為止。

如果 Angular 在任何 `ElementInjector` 階層中都找不到該提供者，它會回到請求發出的元素，並在 `EnvironmentInjector` 階層中尋找。
如果 Angular 仍然找不到該提供者，它就會擲出錯誤。

如果你在不同層級為同一個 DI token 註冊了提供者，Angular 遇到的第一個就是它用來解析該依賴的提供者。
例如，如果提供者在需要某個服務的元件中就地註冊，
Angular 就不會再尋找同一個服務的其他提供者。

HELPFUL: 對於以 `NgModule` 為基礎的應用程式，如果 Angular 在 `ElementInjector` 階層中找不到提供者，它會搜尋 `ModuleInjector` 階層。

## 解析修飾符

Angular 的解析行為可以用 `optional`、`self`、`skipSelf` 和 `host` 來修改。
從 `@angular/core` 匯入它們，並在你注入服務時，在 [`inject`](/api/core/inject) 設定中使用它們。

### 修飾符的類型

解析修飾符分為三類：

- 找不到你要找的東西時該怎麼做，也就是 `optional`
- 從哪裡開始找，也就是 `skipSelf`
- 在哪裡停止尋找，也就是 `host` 和 `self`

依預設，Angular 一律從目前的 `Injector` 開始，一路往上搜尋。
修飾符讓你可以改變開始（也就是 *self*）的位置和結束的位置。

此外，你可以組合所有修飾符，但以下組合除外：

- `host` 和 `self`
- `skipSelf` 和 `self`。

### `optional` {#optional}

`optional` 讓 Angular 把你注入的服務視為可選。
這樣一來，如果它在執行階段無法被解析，Angular 會把該服務解析為 `null`，而不是擲出錯誤。
在以下範例中，服務 `OptionalService` 沒有在服務、`ApplicationConfig`、`@NgModule()` 或元件類別中被提供，因此它在應用程式的任何地方都不可用。

```ts
{header:"src/app/optional/optional.ts"}
export class Optional {
  public optional? = inject(OptionalService, {optional: true});
}
```

### `self`

使用 `self`，讓 Angular 只查看目前元件或指令的 `ElementInjector`。

`self` 的一個很好的使用情境是注入一個服務，但前提是它在目前的宿主元素上可用。
為了在這種情況下避免錯誤，把 `self` 與 `optional` 組合使用。

例如，在以下的 `SelfNoData` 中，注意作為屬性的被注入的 `LeafService`。

```ts
{header: 'self-no-data.ts', highlight: [7]}
@Component({
  selector: 'app-self-no-data',
  templateUrl: './self-no-data.html',
  styleUrls: ['./self-no-data.css'],
})
export class SelfNoData {
  public leaf = inject(LeafService, {optional: true, self: true});
}
```

在這個範例中，存在一個父提供者，注入該服務會傳回該值；然而，以 `self` 和 `optional` 注入該服務會傳回 `null`，因為 `self` 告訴注入器在目前的宿主元素就停止搜尋。

另一個範例顯示帶有 `FlowerService` 提供者的元件類別。
在這種情況下，注入器不需要再往別處尋找，因為它在目前的 `ElementInjector` 中就找到了 `FlowerService`，並傳回鬱金香 🌷。

```ts
{header:"src/app/self/self.ts"}
@Component({
  selector: 'app-self',
  templateUrl: './self.html',
  styleUrls: ['./self.css'],
  providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}],
})
export class Self {
  public flower = inject(FlowerService, {self: true});
}
```

### `skipSelf`

`skipSelf` 是 `self` 的相反。
有了 `skipSelf`，Angular 會從父 `ElementInjector` 開始搜尋服務，而不是從目前的注入器開始。
因此，如果父 `ElementInjector` 為 `emoji` 使用的是蕨類 <code>🌿</code> 的值，但你在元件的 `providers` 陣列中有楓葉 <code>🍁</code>，Angular 會忽略楓葉 <code>🍁</code>，改用蕨類 <code>🌿</code>。

要在程式碼中看這一點，假設父元件使用的是以下的 `emoji` 值，如同這個服務：

```ts
{header: 'leaf.service.ts'}
export class LeafService {
  emoji = '🌿';
}
```

想像在子元件中，你有一個不同的值，楓葉 🍁，但你想改用父元件的值。
這時你就會用 `skipSelf`：

```ts
{header:"skipself.ts" highlight:[[6],[10]]}
@Component({
  selector: 'app-skipself',
  templateUrl: './skipself.html',
  styleUrls: ['./skipself.css'],
  // Angular would ignore this LeafService instance
  providers: [{provide: LeafService, useValue: {emoji: '🍁'}}],
})
export class Skipself {
  // Use skipSelf as inject option
  public leaf = inject(LeafService, {skipSelf: true});
}
```

在這種情況下，你為 `emoji` 取得的值會是蕨類 <code>🌿</code>，而不是楓葉 <code>🍁</code>。

#### `skipSelf` 選項搭配 `optional`

把 `skipSelf` 選項與 `optional` 一起使用，可以在值為 `null` 時避免錯誤。

在以下範例中，`Person` 服務在屬性初始化期間被注入。
`skipSelf` 告訴 Angular 跳過目前的注入器，而 `optional` 會在 `Person` 服務為 `null` 時避免錯誤。

```ts
class Person {
  parent = inject(Person, {optional: true, skipSelf: true});
}
```

### `host`

`host` 讓你在搜尋提供者時，把某個元件指定為注入器樹中的最後一站。

即使樹的更上方還有服務實例，Angular 也不會繼續尋找。
`host` 的使用方式如下：

```ts
{header:"host.ts" highlight:[[6],[9]]}
@Component({
  selector: 'app-host',
  templateUrl: './host.html',
  styleUrls: ['./host.css'],
  // provide the service
  providers: [{provide: FlowerService, useValue: {emoji: '🌷'}}],
})
export class Host {
  // use host when injecting the service
  flower = inject(FlowerService, {host: true, optional: true});
}
```

由於 `Host` 有 `host` 選項，無論 `Host` 的父層的 `flower.emoji` 值是什麼，`Host` 都會使用鬱金香 <code>🌷</code>。

### 建構子注入的修飾符

如同先前所呈現的，建構子注入的行為可以用 `@Optional()`、`@Self()`、`@SkipSelf()` 和 `@Host()` 來修改。

從 `@angular/core` 匯入它們，並在你注入服務時，在元件類別的建構子中使用它們。

```ts
{header:"self-no-data.ts" highlight:[2]}
export class SelfNoData {
  constructor(@Self() @Optional() public leaf?: LeafService) {}
}
```

## 範本的邏輯結構

當你在元件類別中提供服務時，服務在 `ElementInjector` 樹中的可見性，取決於你提供這些服務的位置和方式。

了解 Angular 範本底層的邏輯結構，能為你設定服務、進而控制它們的可見性打下基礎。

元件在你的範本中被使用，如以下範例：

```html
<app-root> <app-child />; </app-root>
```

HELPFUL: 通常，你會把元件和它們的範本宣告在不同的檔案中。
為了理解注入系統如何運作，從合併後的邏輯樹的角度來看它們會很有幫助。
*邏輯*一詞是為了把它與算繪樹區分開來，算繪樹就是你的應用程式的 DOM 樹。
為了標記元件範本所在的位置，本指南使用 `<#VIEW>` 虛擬元素，它實際上並不存在於算繪樹中，只是為了心智模型而存在。

以下是一個範例，示範 `<app-root>` 和 `<app-child>` 的檢視樹如何合併成單一的邏輯樹：

```html
<app-root>
  <#VIEW>
    <app-child>
     <#VIEW>
       …content goes here…
     </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

了解 `<#VIEW>` 分界的概念，在你於元件類別中設定服務時尤其重要。

## 範例：在 `@Component()` 中提供服務

你使用 `@Component()`（或 `@Directive()`）裝飾器提供服務的方式，決定了它們的可見性。
以下各節示範 `providers` 和 `viewProviders`，以及用 `skipSelf` 和 `host` 修改服務可見性的方法。

元件類別可以用兩種方式提供服務：

| 陣列                         | 詳細資訊                                       |
| :--------------------------- | :--------------------------------------------- |
| 使用 `providers` 陣列        | `@Component({ providers: [SomeService] })`     |
| 使用 `viewProviders` 陣列    | `@Component({ viewProviders: [SomeService] })` |

在以下範例中，你會看到一個 Angular 應用程式的邏輯樹。
為了說明注入器在範本脈絡中如何運作，邏輯樹將呈現應用程式的 HTML 結構。
例如，邏輯樹會顯示 `<child-component>` 是 `<parent-component>` 的直接子元素。

在邏輯樹中，你會看到特殊屬性：`@Provide`、`@Inject` 和 `@ApplicationConfig`。
這些不是真正的屬性，而是用來示範底層發生了什麼。

### 範例應用程式結構

範例應用程式有一個在 `root` 提供的 `FlowerService`，其 `emoji` 值為紅色扶桑花 <code>🌺</code>。

```ts
{header:"flower.service.ts"}
@Service()
export class FlowerService {
  emoji = '🌺';
}
```

設想一個只有 `App` 和 `Child` 的應用程式。
最基本的算繪檢視會像以下這樣巢狀的 HTML 元素：

```html
<app-root>
  
  <app-child>  </app-child>
</app-root>
```

然而，在幕後，Angular 在解析注入請求時使用如下的邏輯檢視表示法：

```html
<app-root> 
  <#VIEW>
    <app-child> 
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

這裡的 `<#VIEW>` 代表一個範本的實例。
注意每個元件都有自己的 `<#VIEW>`。

了解這個結構能幫助你決定如何提供和注入服務，並讓你完全掌控服務的可見性。

現在，設想 `<app-root>` 注入了 `FlowerService`：

```typescript
export class App {
  flower = inject(FlowerService);
}
```

在 `<app-root>` 範本中加入一個繫結，來視覺化結果：

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

檢視中的輸出會是：

```text
{hideCopy}
Emoji from FlowerService: 🌺
```

在邏輯樹中，這會表示如下：

```html
<app-root @ApplicationConfig
        @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
    <p>Emoji from FlowerService: {{flower.emoji}} (🌺)</p>
    <app-child>
      <#VIEW>
      </#VIEW>
    </app-child>
  </#VIEW>
</app-root>
```

當 `<app-root>` 請求 `FlowerService` 時，解析 `FlowerService` token 是注入器的工作。
token 的解析分兩個階段進行：

1. 注入器決定邏輯樹中的起始位置和搜尋的結束位置。
   注入器從起始位置開始，在邏輯樹的每個檢視層級尋找 token。
   如果找到 token，就把它傳回。

1. 如果找不到 token，注入器會尋找最近的父 `EnvironmentInjector`，把請求委派給它。

在這個範例中，限制條件如下：

1. 從屬於 `<app-root>` 的 `<#VIEW>` 開始，以 `<app-root>` 結束。
   - 一般來說，搜尋的起點是注入的位置。
     然而，在這個情況下，`<app-root>` 是一個元件。`@Component` 的特殊之處在於它們也包含自己的 `viewProviders`，這就是搜尋從屬於 `<app-root>` 的 `<#VIEW>` 開始的原因。
     對於在同一個位置比對到的指令，情況就不是這樣。
   - 結束位置恰好與元件本身相同，因為它是這個應用程式中最上層的元件。

1. 由 `ApplicationConfig` 提供的 `EnvironmentInjector`，在 `ElementInjector` 階層中找不到注入 token 時，充當備用注入器。

### 使用 `providers` 陣列

現在，在 `Child` 類別中，為 `FlowerService` 加入一個提供者，以在接下來的章節中示範更複雜的解析規則：

```ts
@Component({
  selector: 'app-child',
  templateUrl: './child.html',
  styleUrls: ['./child.css'],
  // use the providers array to provide a service
  providers: [{provide: FlowerService, useValue: {emoji: '🌻'}}],
})
export class Child {
  // inject the service
  flower = inject(FlowerService);
}
```

既然 `FlowerService` 已在 `@Component()` 裝飾器中提供，當 `<app-child>` 請求該服務時，注入器只需要找到 `<app-child>` 中的 `ElementInjector` 為止。
它不需要再沿著注入器樹繼續搜尋。

下一步是在 `Child` 範本中加入一個繫結。

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
```

若要算繪新的值，把 `<app-child>` 加入 `App` 範本的底部，讓檢視也顯示向日葵：

```text
{hideCopy}
Child Component
Emoji from FlowerService: 🌻
```

在邏輯樹中，這表示如下：

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW>

<p>Emoji from FlowerService: {{flower.emoji}} (🌺)</p>
  <app-child @Provide(FlowerService="🌻" )
             @Inject(FlowerService)=>"🌻"> 
    <#VIEW> 
    <h2>Child Component</h2>
    <p>Emoji from FlowerService: {{flower.emoji}} (🌻)</p>
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

當 `<app-child>` 請求 `FlowerService` 時，注入器從屬於 `<app-child>` 的 `<#VIEW>` 開始搜尋（`<#VIEW>` 被包括在內，是因為它從 `@Component()` 注入），並以 `<app-child>` 結束。
在這種情況下，`FlowerService` 以 `<app-child>` 的 `providers` 陣列中向日葵 <code>🌻</code> 的值被解析。
注入器不需要在注入器樹中再往別處尋找。
它一找到 `FlowerService` 就停下來，永遠不會看到紅色扶桑花 <code>🌺</code>。

### 使用 `viewProviders` 陣列 {#using-the-viewproviders-array}

使用 `viewProviders` 陣列，是在 `@Component()` 裝飾器中提供服務的另一種方式。
使用 `viewProviders` 讓服務在 `<#VIEW>` 中可見。

HELPFUL: 步驟與使用 `providers` 陣列相同，唯一的例外是改用 `viewProviders` 陣列。

如需逐步說明，請繼續閱讀本節。
如果你可以自行設定，請跳到[修改服務可用性](#visibility-of-provided-tokens)。

為了示範，我們建立一個 `AnimalService` 來示範 `viewProviders`。
首先，建立一個 `AnimalService`，其 `emoji` 屬性為鯨魚 <code>🐳</code>：

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

@Service()
export class AnimalService {
  emoji = '🐳';
}
```

遵循與 `FlowerService` 相同的模式，在 `App` 類別中注入 `AnimalService`：

```ts
export class App {
  public flower = inject(FlowerService);
  public animal = inject(AnimalService);
}
```

HELPFUL: 你可以保留所有 `FlowerService` 相關的程式碼，因為這能讓你與 `AnimalService` 做對照比較。

也為 `<app-child>` 類別加入 `viewProviders` 陣列並注入 `AnimalService`，但給 `emoji` 一個不同的值。
在這裡，它的值是狗 🐶。

```typescript
@Component({
  selector: 'app-child',
  templateUrl: './child.html',
  styleUrls: ['./child.css'],
  // provide services
  providers: [{provide: FlowerService, useValue: {emoji: '🌻'}}],
  viewProviders: [{provide: AnimalService, useValue: {emoji: '🐶'}}],
})
export class Child {
  // inject services
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

在 `Child` 和 `App` 範本中加入繫結。
在 `Child` 範本中，加入以下繫結：

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

此外，在 `App` 範本中也加入相同的繫結：

```html
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

現在你應該能在瀏覽器中看到這兩個值：

```text
{hideCopy}
App
Emoji from AnimalService: 🐳

Child Component
Emoji from AnimalService: 🐶
```

這個 `viewProviders` 範例的邏輯樹如下：

```html
<app-root @ApplicationConfig
          @Inject(AnimalService) animal=>"🐳">
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService=>"🐶")>

<p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

就如同 `FlowerService` 範例一樣，`AnimalService` 在 `<app-child>` 的 `@Component()` 裝飾器中被提供。
這表示由於注入器先在元件的 `ElementInjector` 中尋找，它找到了狗 <code>🐶</code> 的 `AnimalService` 值。
它不需要繼續搜尋 `ElementInjector` 樹，也不需要搜尋 `ModuleInjector`。

### `providers` 與 `viewProviders`

`viewProviders` 欄位在概念上與 `providers` 相似，但有一個值得注意的差異。
`viewProviders` 中的提供者只在元件自己的檢視內可見，透過 `<ng-content>` 投影進元件的內容看不到它們。

若要看出使用 `providers` 與 `viewProviders` 的差異，在範例中再加入一個元件，稱它為 `Inspector`。
`Inspector` 將是 `Child` 的子元件。
在 `inspector.ts` 中，在屬性初始化期間注入 `FlowerService` 和 `AnimalService`：

```typescript
export class Inspector {
  flower = inject(FlowerService);
  animal = inject(AnimalService);
}
```

你不需要 `providers` 或 `viewProviders` 陣列。
接著，在 `inspector.html` 中，加入與前面元件相同的標記：

```html
<p>Emoji from FlowerService: {{flower.emoji}}</p>
<p>Emoji from AnimalService: {{animal.emoji}}</p>
```

記得把 `Inspector` 加入 `Child` 的 `imports` 陣列。

```ts
@Component({
  ...
  imports: [Inspector]
})
```

接著，在 `child.html` 中加入以下內容：

```html
...

<div class="container">
  <h3>Content projection</h3>
  <ng-content />
</div>
<h3>Inside the view</h3>

<app-inspector />
```

`<ng-content>` 讓你可以投影內容，而 `Child` 範本內的 `<app-inspector>` 使 `Inspector` 成為 `Child` 的子元件。

接著，在 `app.html` 中加入以下內容，以運用內容投影。

```html
<app-child>
  <app-inspector />
</app-child>
```

瀏覽器現在算繪出以下內容（為求簡潔，省略先前的範例）：

```text
{hideCopy}
...
Content projection

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐳

Emoji from FlowerService: 🌻
Emoji from AnimalService: 🐶
```

這四個繫結示範了 `providers` 與 `viewProviders` 的差異。
記住，狗 emoji <code>🐶</code> 是在 `Child` 的 `<#VIEW>` 內宣告的，對投影進來的內容不可見。
相反地，投影進來的內容看到的是鯨魚 <code>🐳</code>。

你可能會疑惑，為什麼被投影的 `<app-inspector>` 仍然看得到 <code>🐳</code>，也就是根層級提供的 `AnimalService`。
原因是 Angular DI 追蹤的是**元件在哪裡被宣告**，而不是它最終在哪裡被算繪。
`<app-inspector>` 位於 `App` 的範本中，在 `App` 的 `<#VIEW>` 內，因此它的查找永遠不會經過 `Child` 的 `<#VIEW>`。
把它投影進 `Child`，切斷了它對 `Child` 的 `viewProviders`（<code>🐶</code>）的存取，但根層級的 `AnimalService`（<code>🐳</code>）仍然可以沿著樹往上觸及。

然而，在下一個輸出區段中，`Inspector` 是 `Child` 的實際子元件，`Inspector` 在 `<#VIEW>` 內，因此當它索取 `AnimalService` 時，它看到的是狗 <code>🐶</code>。

邏輯樹中的 `AnimalService` 會像這樣：

```html
<app-root @ApplicationConfig
          @Inject(AnimalService) animal=>"🐳">
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService=>"🐶")>

<p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>

<div class="container">
      <h3>Content projection</h3>
      <app-inspector @Inject(AnimalService) animal=>"🐳">
        <p>Emoji from AnimalService: {{animal.emoji}} (🐳)</p>
      </app-inspector>
    </div>

<app-inspector>
      <#VIEW @Inject(AnimalService) animal=>"🐶">
      <p>Emoji from AnimalService: {{animal.emoji}} (🐶)</p>
    </
    #VIEW>
    </app-inspector>
  </
  #VIEW>
  </app-child>

</#VIEW>
</app-root>
```

被投影的 `<app-inspector>` 取得 <code>🐳</code>，因為 <code>🐶</code> 屬於 `Child` 的檢視，投影進來的內容觸及不到它。
<code>🐳</code> 可以被存取，是因為 `<app-inspector>` 是在 `App` 的範本中宣告的，因此它仍然可以沿著樹往上走到根層級的 `AnimalService`。

直接位於 `Child` 範本內（不是被投影）的 `<app-inspector>` 取得 <code>🐶</code>，因為它在 `<#VIEW>` 內，沒有邊界需要跨越。

### 讓投影進來的內容存取檢視注入器

以 `<ng-content>` 投影進來的內容看不到元件的 `viewProviders`，因為 Angular 是對照內容被宣告位置的注入器來解析注入，而不是它算繪的位置。

當你特別想讓投影進來的內容觸及檢視層級的服務（或投影元件實例本身）時，把內容作為範本接受，而不是用 `<ng-content>`，並以明確的注入器來算繪它。

更新 `Child`，在 `viewProviders` 中提供 `AnimalService`，查詢被投影的範本，並透過 [`NgTemplateOutlet`](/api/common/NgTemplateOutlet) 算繪它，把 `ngTemplateOutletInjector` 設為一個看得到該服務的注入器：

```ts
@Component({
  selector: 'app-child',
  viewProviders: [AnimalService],
  imports: [NgTemplateOutlet],
  template: `
    <ng-container [ngTemplateOutlet]="content()" [ngTemplateOutletInjector]="injector" />
  `,
})
export class Child {
  readonly content = contentChild.required(TemplateRef);
  readonly injector = inject(Injector);
}
```

使用者把被投影的標記包在 `<ng-template>` 中：

```html
<app-child>
  <ng-template>
    <app-inspector />
  </ng-template>
</app-child>
```

`Child` 現在用自己的注入器在出口處建立 `<app-inspector>`，因此即使標記寫在 `App` 的範本中，`AnimalService` 也會解析為狗 <code>🐶</code>。代價是與 `<ng-content>` 相比，兩邊都要多寫一點標記。

### 被提供 token 的可見性 {#visibility-of-provided-tokens}

可見性裝飾器影響在邏輯樹中搜尋注入 token 的起點和終點。
若要做到這一點，把可見性設定放在注入點，也就是叫用 `inject()` 時，而不是宣告點。

若要改變注入器開始尋找 `FlowerService` 的位置，在 `<app-child>` 注入 `FlowerService` 的 `inject()` 叫用中加入 `skipSelf`。
這個叫用是 `<app-child>` 中的一個屬性初始化器，如 `child.ts` 所示：

```typescript
flower = inject(FlowerService, {skipSelf: true});
```

有了 `skipSelf`，`<app-child>` 注入器不會向自己尋找 `FlowerService`。
相反地，注入器從 `<app-root>` 的 `ElementInjector` 開始尋找 `FlowerService`，但在那裡什麼也找不到。
接著，它回到 `<app-child>` 的 `ModuleInjector`，找到紅色扶桑花 <code>🌺</code> 的值，它之所以可用，是因為 `<app-child>` 和 `<app-root>` 共用同一個 `ModuleInjector`。
UI 算繪出以下內容：

```text
{hideCopy}
Emoji from FlowerService: 🌺
```

在邏輯樹中，同樣的概念可能像這樣：

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW>
  <app-child @Provide(FlowerService="🌻" )>
    <#VIEW @Inject(FlowerService, SkipSelf)=>"🌺">

</
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

儘管 `<app-child>` 提供了向日葵 <code>🌻</code>，應用程式卻算繪出紅色扶桑花 <code>🌺</code>，因為 `skipSelf` 使目前的注入器（`app-child`）跳過自己、看向它的父層。

如果你現在再加上 `host`（除了 `skipSelf` 之外），結果會是 `null`。
這是因為 `host` 把搜尋的上限限制在 `app-child` 的 `<#VIEW>`。
邏輯樹中的概念如下：

```html
<app-root @ApplicationConfig
          @Inject(FlowerService) flower=>"🌺">
  <#VIEW> 
  <app-child @Provide(FlowerService="🌻" )> 
    <#VIEW inject(FlowerService, {skipSelf: true, host: true, optional:true})=>null>
  </
  #VIEW>
  </app-parent>
</#VIEW>
</app-root>
```

在這裡，服務和它們的值都相同，但 `host` 阻止注入器在 `<#VIEW>` 之外繼續尋找 `FlowerService`，因此它找不到該服務並傳回 `null`。

### `skipSelf` 與 `viewProviders`

記住，`<app-child>` 在 `viewProviders` 陣列中提供了 `AnimalService`，其值為狗 <code>🐶</code>。
因為注入器只需要查看 `<app-child>` 的 `ElementInjector` 就能找到 `AnimalService`，它永遠不會看到鯨魚 <code>🐳</code>。

如同 `FlowerService` 範例，如果你把 `skipSelf` 加入 `AnimalService` 的 `inject()`，注入器就不會在目前 `<app-child>` 的 `ElementInjector` 中尋找 `AnimalService`。
相反地，注入器會從 `<app-root>` 的 `ElementInjector` 開始。

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ],
})
```

在 `<app-child>` 中有 `skipSelf` 時，邏輯樹看起來像這樣：

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    @Inject(AnimalService, SkipSelf=>"🐳")>

</
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

在 `<app-child>` 中有 `skipSelf` 時，注入器從 `<app-root>` 的 `ElementInjector` 開始搜尋 `AnimalService`，並找到鯨魚 🐳。

### `host` 與 `viewProviders`

如果你只對 `AnimalService` 的注入使用 `host`，結果會是狗 <code>🐶</code>，因為注入器在 `<app-child>` 的 `<#VIEW>` 本身就找到了 `AnimalService`。
`Child` 設定了 `viewProviders`，使狗 emoji 被提供為 `AnimalService` 的值。
你也可以在 `inject()` 中看到 `host`：

```typescript
@Component({
  selector: 'app-child',
  …
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🐶' } },
  ]
})
export class Child {
  animal = inject(AnimalService, { host: true })
}
```

`host: true` 使注入器一直找到 `<#VIEW>` 的邊界為止。

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW>
  <app-child>
    <#VIEW @Provide(AnimalService="🐶")
    inject(AnimalService, {host: true}=>"🐶")> 
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

在 `app.ts` 的 `@Component()` 詮釋資料中，加入一個帶有第三種動物，刺蝟 <code>🦔</code> 的 `viewProviders` 陣列：

```typescript
@Component({
  selector: 'app-root',
  templateUrl: './app.html',
  styleUrls: [ './app.css' ],
  viewProviders: [
    { provide: AnimalService, useValue: { emoji: '🦔' } },
  ],
})
```

接著，在 `child.ts` 中為 `AnimalService` 注入的 `inject()` 加入 `skipSelf` 以及 `host`。
以下是在 `animal` 屬性初始化中的 `host` 和 `skipSelf`：

```typescript
export class Child {
  animal = inject(AnimalService, {host: true, skipSelf: true});
}
```

當 `host` 和 `skipSelf` 被套用到位於 `providers` 陣列中的 `FlowerService` 時，結果是 `null`，因為 `skipSelf` 從 `<app-child>` 注入器開始搜尋，但 `host` 在 `<#VIEW>` 就停止搜尋，而那裡沒有 `FlowerService`。
在邏輯樹中，你可以看到 `FlowerService` 在 `<app-child>` 中可見，而不是在它的 `<#VIEW>` 中。

然而，在 `App` 的 `viewProviders` 陣列中提供的 `AnimalService` 是可見的。

邏輯樹的表示法說明了為什麼會這樣：

```html
<app-root @ApplicationConfig
          @Inject(AnimalService=>"🐳")>
  <#VIEW @Provide(AnimalService="🦔")
  @Inject(AnimalService, @Optional)=>"🦔">

<app-child>
    <#VIEW @Provide(AnimalService="🐶")
    inject(AnimalService, {skipSelf:true, host: true, optional: true})=>"🦔">
    
  </
  #VIEW>
  </app-child>
</#VIEW>
</app-root>
```

`skipSelf` 使注入器從 `<app-root>` 開始搜尋 `AnimalService`，而不是請求發出的 `<app-child>`，而 `host` 在 `<app-root>` 的 `<#VIEW>` 停止搜尋。
由於 `AnimalService` 是透過 `viewProviders` 陣列提供的，注入器在 `<#VIEW>` 中找到了刺蝟 <code>🦔</code>。

## 範例：`ElementInjector` 使用情境

能在不同層級設定一個或多個提供者，開啟了許多有用的可能性。

### 情境：服務隔離

架構上的理由可能讓你想把對某個服務的存取，限制在它所屬的應用程式領域內。
例如，設想我們建立一個 `VillainsList` 來顯示反派清單。
它從 `VillainsService` 取得那些反派。

如果你在根層級的 `AppModule` 中提供 `VillainsService`，它會讓 `VillainsService` 在應用程式的任何地方都可見。
如果你日後修改 `VillainsService`，你可能會破壞其他不小心開始依賴這個服務的元件。

相反地，你應該像這樣在 `VillainsList` 的 `providers` 詮釋資料中提供 `VillainsService`：

```typescript
@Component({
  selector: 'app-villains-list',
  templateUrl: './villains-list.html',
  providers: [VillainsService],
})
export class VillainsList {}
```

透過只在 `VillainsList` 的詮釋資料中提供 `VillainsService`、而不在其他任何地方提供，該服務就只在 `VillainsList` 及其子元件樹中可用。

`VillainsService` 相對於 `VillainsList` 而言是單例，因為它就是在那裡宣告的。
只要 `VillainsList` 沒有被銷毀，它就會是同一個 `VillainsService` 實例；但如果有多個 `VillainsList` 實例，那麼每個 `VillainsList` 實例都會有自己的 `VillainsService` 實例。

### 情境：多個編輯工作階段

許多應用程式允許使用者同時處理多個開啟中的工作。
例如，在報稅應用程式中，報稅人員可以同時處理多份報稅表，在一天中在它們之間切換。

若要示範這個情境，想像一個顯示超級英雄清單的 `HeroList`。

若要開啟某位英雄的報稅表，報稅人員點擊英雄的名字，就會開啟一個用於編輯該報稅表的元件。
每份被選取的英雄報稅表都在自己的元件中開啟，多份報稅表可以同時開啟。

每個報稅表元件都有以下特點：

- 是它自己的報稅表編輯工作階段
- 可以變更報稅表，而不會影響另一個元件中的報稅表
- 能夠儲存對其報稅表的變更，或取消它們

假設 `HeroTaxReturnEditor` 有管理與還原變更的邏輯。
對於英雄報稅表來說，那會是一件直截了當的工作。
在真實世界中，面對豐富的報稅表資料模型，變更管理工作會很棘手。
你可以把這項管理委派給一個輔助服務，如本範例所示。

`HeroTaxReturnService` 快取單一的 `HeroTaxReturn`，追蹤對該報稅表的變更，並能儲存或還原它。
它也會委派給整個應用程式範圍的單例 `HeroService`，它透過注入取得該服務。

```typescript
import {inject, Service} from '@angular/core';
import {HeroTaxReturn} from './hero';
import {HeroesService} from './heroes.service';

@Service({autoProvided: false})
export class HeroTaxReturnService {
  private currentTaxReturn!: HeroTaxReturn;
  private originalTaxReturn!: HeroTaxReturn;

private heroService = inject(HeroesService);

set taxReturn(htr: HeroTaxReturn) {
    this.originalTaxReturn = htr;
    this.currentTaxReturn = htr.clone();
  }

get taxReturn(): HeroTaxReturn {
    return this.currentTaxReturn;
  }

restoreTaxReturn() {
    this.taxReturn = this.originalTaxReturn;
  }

saveTaxReturn() {
    this.taxReturn = this.currentTaxReturn;
    this.heroService.saveTaxReturn(this.currentTaxReturn).subscribe();
  }
}
```

以下是使用 `HeroTaxReturnService` 的 `HeroTaxReturnEditor`。

```typescript
import {Component, effect, inject, input, output} from '@angular/core';
import {HeroTaxReturn} from './hero';
import {HeroTaxReturnService} from './hero-tax-return.service';

@Component({
  selector: 'app-hero-tax-return',
  templateUrl: './hero-tax-return.html',
  styleUrls: ['./hero-tax-return.css'],
  providers: [HeroTaxReturnService],
})
export class HeroTaxReturnEditor {
  message = '';

close = output<void>();

taxReturn = input.required<HeroTaxReturn>();

private heroTaxReturnService = inject(HeroTaxReturnService);

constructor() {
    effect(() => {
      this.heroTaxReturnService.taxReturn = this.taxReturn();
    });
  }

onCanceled() {
    this.flashMessage('Canceled');
    this.heroTaxReturnService.restoreTaxReturn();
  }

onClose() {
    this.close.emit();
  }

onSaved() {
    this.flashMessage('Saved');
    this.heroTaxReturnService.saveTaxReturn();
  }

flashMessage(msg: string) {
    this.message = msg;
    setTimeout(() => (this.message = ''), 500);
  }
}
```

*要編輯的報稅表*透過 `taxReturn` 訊號輸入抵達。
每當輸入變更時，一個 `effect` 就會以傳入的報稅表初始化元件自己的 `HeroTaxReturnService` 實例。
服務的 getter 永遠傳回服務所稱的英雄目前狀態。
元件也會要求服務儲存與還原這份報稅表。

如果服務是整個應用程式範圍的單例，這就行不通了。
每個元件都會共用同一個服務實例，而每個元件都會覆寫屬於另一位英雄的報稅表。

若要防止這一點，設定 `HeroTaxReturnEditor` 的元件層級注入器來提供該服務，使用元件詮釋資料中的 `providers` 屬性。

```typescript
providers: [HeroTaxReturnService];
```

`HeroTaxReturnEditor` 有它自己的 `HeroTaxReturnService` 提供者。
回想一下，每個元件*實例*都有自己的注入器。
在元件層級提供服務，確保該元件的*每個*實例都能取得服務的一個私密實例。這能確保沒有任何報稅表會被覆寫。

HELPFUL: 本情境其餘的程式碼仰賴其他 Angular 功能與技巧，你可以在文件其他地方學到它們。

### 情境：專門化的提供者

在另一個層級再次提供服務的另一個理由是，在元件樹更深處替換成該服務*更專門化*的實作。

例如，設想一個 `Car` 元件，它包含輪胎服務資訊，並依賴其他服務來提供關於汽車的更多細節。

根注入器，標記為 (A)，為 `CarService` 和 `EngineService` 的細節使用*通用*提供者。

1. `Car` 元件 (A)。元件 (A) 顯示關於汽車的輪胎服務資料，並指定通用服務來提供關於汽車的更多資訊。

2. 子元件 (B)。元件 (B) 為 `CarService` 和 `EngineService` 定義它自己的*專門化*提供者，它們具有適合元件 (B) 中發生之事的特殊能力。

3. 子元件 (C)，是元件 (B) 的子元件。元件 (C) 為 `CarService` 定義它自己的、甚至*更專門化*的提供者。

```mermaid
graph TD;
subgraph COMPONENT_A[Component A]
subgraph COMPONENT_B[Component B]
COMPONENT_C[Component C]
end
end

style COMPONENT_A fill:#BDD7EE
style COMPONENT_B fill:#FFE699
style COMPONENT_C fill:#A9D18E,color:#000
classDef noShadow filter:none
class COMPONENT_A,COMPONENT_B,COMPONENT_C noShadow
```

在幕後，每個元件都設定了自己的注入器，其中為該元件本身定義了零個、一個或多個提供者。

當你在最深的元件 (C) 解析 `Car` 的一個實例時，它的注入器產生：

- 一個由注入器 (C) 解析的 `Car` 實例
- 一個由注入器 (B) 解析的 `Engine`
- 它的 `Tires` 由根注入器 (A) 解析。

```mermaid
graph BT;

subgraph A[" "]
direction LR
RootInjector["(A) RootInjector"]
ServicesA["CarService, EngineService, TiresService"]
end

subgraph B[" "]
direction LR
ParentInjector["(B) ParentInjector"]
ServicesB["CarService2, EngineService2"]
end

subgraph C[" "]
direction LR
ChildInjector["(C) ChildInjector"]
ServicesC["CarService3"]
end

direction LR
car["(C) Car"]
engine["(B) Engine"]
tires["(A) Tires"]

direction BT
car-->ChildInjector
ChildInjector-->ParentInjector-->RootInjector

class car,engine,tires,RootInjector,ParentInjector,ChildInjector,ServicesA,ServicesB,ServicesC,A,B,C noShadow
style car fill:#A9D18E,color:#000
style ChildInjector fill:#A9D18E,color:#000
style engine fill:#FFE699,color:#000
style ParentInjector fill:#FFE699,color:#000
style tires fill:#BDD7EE,color:#000
style RootInjector fill:#BDD7EE,color:#000
```

## 依賴注入的更多資訊
# 以輕量注入 token 最佳化用戶端應用程式大小

本頁從概念上總覽一項建議函式庫開發者採用的依賴注入技巧。
以*輕量注入 token* 來設計你的函式庫，有助於最佳化使用你函式庫的用戶端應用程式的 bundle 大小。

你可以透過可搖樹的提供者，管理元件與可注入服務之間的依賴結構，藉此最佳化 bundle 大小。
這通常能確保：如果提供的元件或服務從未被應用程式實際使用，編譯器就能把它的程式碼從 bundle 中移除。

礙於 Angular 儲存注入 token 的方式，這類未使用的元件或服務還是有可能最終出現在 bundle 中。
本頁說明一種依賴注入設計模式，透過輕量注入 token 來支援正確的搖樹優化。

輕量注入 token 設計模式對函式庫開發者尤其重要。
它能確保當應用程式只使用你函式庫的部分功能時，未使用的程式碼可以從用戶端應用程式的 bundle 中消除。

當應用程式使用你的函式庫時，你的函式庫提供的某些服務，用戶端應用程式可能並不會用到。
在這種情況下，應用程式開發者理應期待該服務被搖樹優化移除，而不是增加編譯後應用程式的大小。
由於應用程式開發者無從得知函式庫中的搖樹優化問題、也無法加以補救，防止未使用元件被保留下來是函式庫開發者的責任。
為此，你的函式庫應該採用輕量注入 token 設計模式。

## token 何時會被保留

為了更清楚地說明 token 被保留的條件，設想一個提供 library-card 元件的函式庫。
這個元件包含一個主體，還可以包含一個可選的標頭：

```html
<lib-card>
  <lib-header>…</lib-header>
</lib-card>
```

一種可能的實作是，`<lib-card>` 元件使用 `contentChild` 或 `contentChildren` 來取得 `<lib-header>` 和 `<lib-body>`，如下所示：

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

@Component({
  selector: 'lib-header',
  …,
})
class LibHeader {}

@Component({
  selector: 'lib-card',
  …,
})
class LibCard {
  readonly header = contentChild(LibHeader);
}
```

由於 `<lib-header>` 是可選的，該元素在範本中可以以最精簡的形式出現：`<lib-card />`。
在這種情況下，`<lib-header>` 沒有被使用，你會期待它被搖樹優化移除，但實際並非如此。
這是因為 `LibCard` 其實包含兩處對 `LibHeader` 的參考：

```ts
readonly header = contentChild(LibHeader);
```

- 其中一處參考位於*型別位置*，也就是它把 `LibHeader` 指定為型別：`readonly header: Signal<LibHeader|undefined>`。
- 另一處參考位於*值位置*，也就是 `LibHeader` 是傳入 `contentChild` 函式的值：`contentChild(LibHeader)`。

編譯器對這兩個位置的 token 參考處理方式不同：

- 編譯器會在從 TypeScript 轉換後清除*型別位置*的參考，因此它們對搖樹優化沒有影響。
- 編譯器必須在執行階段保留*值位置*的參考，這會**阻止**元件被搖樹優化移除。

在這個範例中，編譯器保留了出現在值位置的 `LibHeader` token。
這會阻止被參考的元件被搖樹優化移除，即使應用程式實際上沒有在任何地方使用 `<lib-header>`。
如果 `LibHeader` 的程式碼、範本和樣式合計起來太大，不必要地包含它會顯著增加用戶端應用程式的大小。

## 何時該使用輕量注入 token 模式

當元件被當作注入 token 使用時，就會出現搖樹優化問題。
有兩種情況會發生這種事：

- token 用在[內容查詢](guide/components/queries#content-queries)的值位置。
- token 搭配 `inject` 函式使用。

在以下範例中，`CustomOther` token 的兩種用法都會造成 `CustomOther` 被保留，在它未被使用時阻止它被搖樹優化移除：

```ts
{highlight: [[2],[4]]}
class App {
  private readonly other = inject(CustomOther, {optional: true});

readonly header = contentChild(CustomOther);
}
```

雖然只用作型別指定項的 token 在轉換為 JavaScript 時會被移除，但所有用於依賴注入的 token 在執行階段都是必需的。
使用 `inject(CustomOther)` 時，`CustomOther` 是以值引數的形式傳入。
token 此時位於值位置，這會導致搖樹優化器保留該參考。

HELPFUL: 函式庫的所有服務都應該使用[可搖樹的提供者](guide/di/defining-dependency-providers)，在根層級提供依賴，而不是在元件或模組中提供。

## 使用輕量注入 token

輕量注入 token 設計模式的做法是：使用一個小的抽象類別作為注入 token，並在稍後的階段提供實際實作。
抽象類別會被保留、不會被搖樹優化移除，但它很小，對應用程式大小沒有實質影響。

以下範例示範這如何應用於 `LibHeader`：

```ts
{highlight: [[1],[5], [15]]}
abstract class LibHeaderToken {}

@Component({
  selector: 'lib-header',
  providers: [{provide: LibHeaderToken, useExisting: LibHeader}],
  …,
})
class LibHeader extends LibHeaderToken {}

@Component({
  selector: 'lib-card',
  …,
})
class LibCard {
  readonly header = contentChild(LibHeaderToken);
}
```

在這個範例中，`LibCard` 的實作不再於型別位置或值位置參考 `LibHeader`。
這讓 `LibHeader` 可以被完整地搖樹優化移除。
`LibHeaderToken` 會被保留，但它只是一個類別宣告，沒有具體實作。
它很小，在編譯後被保留下來時，不會對應用程式大小造成實質影響。

反過來，`LibHeader` 本身實作了抽象的 `LibHeaderToken` 類別。
你可以放心地把該 token 用作成元件定義中的提供者，讓 Angular 正確地注入具體型別。

總結來說，輕量注入 token 模式包含以下幾項：

1. 一個以抽象類別表示的輕量注入 token。
2. 一個實作該抽象類別的元件定義。
3. 使用 `contentChild` 或 `contentChildren` 注入輕量模式。
4. 輕量注入 token 實作中的一個提供者，它把輕量注入 token 與實作關聯起來。

### 使用輕量注入 token 定義 API

注入輕量注入 token 的元件，可能需要叫用被注入類別中的某個方法。
token 現在是一個抽象類別。由於可注入元件實作了該類別，你還必須在抽象的輕量注入 token 類別中宣告一個抽象方法。
方法的實作連同其所有程式碼開銷，都位於可以被搖樹優化移除的可注入元件中。
這讓父元件能在子元件存在時，以型別安全的方式與它通訊。

例如，`LibCard` 現在查詢的是 `LibHeaderToken`，而不是 `LibHeader`。
以下範例示範這個模式如何讓 `LibCard` 在不實際參考 `LibHeader` 的情況下與 `LibHeader` 通訊：

```ts
{highlight: [[2],[7],[11],[19]]}
abstract class LibHeaderToken {
  abstract doSomething(): void;
}

@Component({
  selector: 'lib-header',
  providers: [{provide: LibHeaderToken, useExisting: LibHeader}],
})
class LibHeader extends LibHeaderToken {
  doSomething(): void {
    // Concrete implementation of `doSomething`
  }
}

@Component({
  selector: 'lib-card',
})
class LibCard implements AfterContentInit {
  readonly header = contentChild(LibHeaderToken);

ngAfterContentInit(): void {
    if (this.header() !== undefined) {
      this.header()!.doSomething();
    }
  }
}
```

在這個範例中，父元件查詢 token 以取得子元件，並在子元件存在時儲存取得的元件參考。
在叫用子元件的方法之前，父元件會先檢查子元件是否存在。
如果子元件已被搖樹優化移除，執行階段就沒有對它的參考，也就不會叫用它的方法。

### 為你的輕量注入 token 命名

輕量注入 token 只對元件有用。
[Angular 風格指南](style-guide)建議為元件命名時不要加上 `Component` 後綴。
範例中的 `LibHeader` 就遵循了這個慣例。

你應該維持元件與其 token 之間的關係，同時又能區分兩者。
建議的風格是使用元件的基礎名稱加上 `Token` 後綴，來為你的輕量注入 token 命名：`LibHeaderToken`。
# RxJS 與 Angular 訊號的互通

`@angular/core/rxjs-interop` 套件提供多個 API，協助你整合 RxJS 與 Angular 訊號。

## 使用 `toSignal` 從 RxJS Observable 建立訊號

使用 `toSignal` 函式建立一個訊號，用來追蹤 Observable 的值。它的行為類似範本中的 `async` 管道，但更具彈性，可用在應用程式的任何地方。

```typescript
import {Component} from '@angular/core';
import {AsyncPipe} from '@angular/common';
import {interval} from 'rxjs';
import {toSignal} from '@angular/core/rxjs-interop';

@Component({
  template: `{{ counter() }}`,
})
export class Ticker {
  counterObservable = interval(1000);

// Get a `Signal` representing the `counterObservable`'s value.
  counter = toSignal(this.counterObservable, {initialValue: 0});
}
```

和 `async` 管道一樣，`toSignal` 會立即訂閱 Observable，這可能會觸發副作用。`toSignal` 建立的訂閱，會在呼叫 `toSignal` 的元件或服務被銷毀時，自動取消訂閱指定的 Observable。

IMPORTANT: `toSignal` 會建立一個訂閱。你應避免對同一個 Observable 重複呼叫它，改為重複使用它回傳的訊號。

### 注入上下文

`toSignal` 預設需要在[注入上下文](guide/di/dependency-injection-context)中執行，例如在元件或服務的建構期間。如果沒有可用的注入上下文，你可以手動指定要改用的 `Injector`。

### 初始值

Observable 在訂閱時不一定會同步產生值，但訊號永遠需要一個目前值。以下有幾種方式可以處理 `toSignal` 訊號的這個「初始」值。

#### `initialValue` 選項

如上例所示，你可以指定 `initialValue` 選項，作為訊號在 Observable 首次發送前應回傳的值。

#### `undefined` 初始值

如果你不提供 `initialValue`，產生的訊號會在 Observable 發送前回傳 `undefined`。這類似 `async` 管道回傳 `null` 的行為。

#### `requireSync` 選項

有些 Observable 保證會同步發送，例如 `BehaviorSubject`。在這種情況下，你可以指定 `requireSync: true` 選項。

當 `requireSync` 為 `true` 時，`toSignal` 會強制要求 Observable 在訂閱時同步發送。這保證訊號永遠有值，不需要 `undefined` 型別，也不需要初始值。

### `manualCleanup`

預設情況下，當建立訊號的元件或服務被銷毀時，`toSignal` 會自動取消訂閱 Observable。

若要覆寫這個行為，可以傳入 `manualCleanup` 選項。這個設定適用於會自然完成的 Observable。

#### 自訂相等比較

有些 observable 發送的值，雖然參考不同或細節略有差異，卻應該視為**相等**。`equal` 選項讓你定義一個**自訂相等函式**，判斷兩個連續的值在何時應視為相同。

當兩個發送的值被視為相等時，產生的訊號**不會更新**。這能避免多餘的運算、DOM 更新或 effect 不必要地重新執行。

```ts
import {Component} from '@angular/core';
import {toSignal} from '@angular/core/rxjs-interop';
import {interval, map} from 'rxjs';

@Component(/* ... */)
export class EqualExample {
  temperature$ = interval(1000).pipe(
    map(() => ({temperature: Math.floor(Math.random() * 3) + 20})), // 20, 21, or 22 randomly
  );

// Only update if the temperature changes
  temperature = toSignal(this.temperature$, {
    initialValue: {temperature: 20},
    equal: (prev, curr) => prev.temperature === curr.temperature,
  });
}
```

### 錯誤與完成

如果用於 `toSignal` 的 Observable 產生錯誤，該錯誤會在讀取訊號時拋出。

如果用於 `toSignal` 的 Observable 完成，訊號會繼續回傳完成前最後發送的值。

## 使用 `toObservable` 從訊號建立 RxJS Observable

使用 `toObservable` 工具函式建立一個 `Observable`，用來追蹤訊號的值。訊號的值由一個 `effect` 監控，當值變更時，effect 會把值發送給 Observable。

```ts
import {Component, signal, Signal, inject} from '@angular/core';
import {toObservable} from '@angular/core/rxjs-interop';
import {switchMap} from 'rxjs';

@Component(/* ... */)
export class SearchResults {
  query: Signal<string> = inject(QueryService).query;
  query$ = toObservable(this.query);

results$ = this.query$.pipe(switchMap((query) => this.http.get('/search?q=' + query)));
}
```

隨著 `query` 訊號變更，`query$` Observable 會發送最新的查詢並觸發一個新的 HTTP 請求。

### 注入上下文 {#injection-context-to-observable}

`toObservable` 預設需要在[注入上下文](guide/di/dependency-injection-context)中執行，例如在元件或服務的建構期間。如果沒有可用的注入上下文，你可以手動指定要改用的 `Injector`。

### `toObservable` 的時機

`toObservable` 使用 effect 在 `ReplaySubject` 中追蹤訊號的值。訂閱時，第一個值（如果有的話）可能會同步發送，之後的所有值都會是非同步的。

與 Observable 不同，訊號永遠不會同步通知變更。即使你多次更新訊號的值，`toObservable` 也只會在訊號穩定後才發送該值。

```ts
const obs$ = toObservable(mySignal);
obs$.subscribe((value) => console.log(value));

mySignal.set(1);
mySignal.set(2);
mySignal.set(3);
```

在這裡，只有最後的值（3）會被記錄下來。

## 使用 `rxResource` 處理非同步資料 {#using-rxresource-for-async-data}

Angular 的 [`resource` 函式](/guide/signals/resource)讓你把非同步資料納入應用程式以訊號為基礎的程式碼。在這個模式之上，`rxResource` 讓你定義一個 resource，其資料來源以 RxJS `Observable` 表示。`rxResource` 不接受 `loader` 函式，而是接受一個回傳 RxJS `Observable` 的 `stream` 函式。

```typescript
import {Component, inject, input} from '@angular/core';
import {rxResource} from '@angular/core/rxjs-interop';

@Component(/* ... */)
export class UserProfile {
  // This component relies on a service that exposes data through an RxJS Observable.
  private userData = inject(MyUserDataClient);

protected userId = input<string>();

private userResource = rxResource({
    params: () => ({userId: this.userId()}),

// The `stream` property expects a factory function that returns
    // a data stream as an RxJS Observable.
    stream: ({params}) => this.userData.load(params.userId),
  });
}
```

`stream` 屬性接受一個 RxJS `Observable` 的工廠函式。這個工廠函式會收到 resource 的 `params` 值，並回傳一個 `Observable`。每當 `params` 運算產生新值時，resource 就會呼叫這個工廠函式。工廠函式收到的參數詳情，請參閱 [Resource loaders](/guide/signals/resource#resource-loaders)。

在其他方面，`rxResource` 的行為與 `resource` 相同，並提供相同的 API，用於指定參數、讀取值、檢查載入狀態與檢視錯誤。

從 `stream` 回傳的 `Observable` 必須在完成前永遠先發送一個值或一個錯誤；否則會發生什麼情況、以及如何避免，請參閱 [`NG0991`](/errors/NG0991)。
# RxJS 與元件及指令輸出的互通

TIP: 本指南假設你已熟悉[元件與指令的輸出](guide/components/outputs)。

`@angular/core/rxjs-interop` 套件提供兩個與元件及指令輸出相關的 API。

## 根據 RxJS Observable 建立輸出

`outputFromObservable` 讓你建立一個元件或指令輸出，其發送行為依 RxJS observable 而定：

```ts
{highlight:[9]}
import {Directive} from '@angular/core';
import {outputFromObservable} from '@angular/core/rxjs-interop';
import {Observable} from 'rxjs';

@Directive(/* ... */)
class Draggable {
  pointerMoves$: Observable<PointerMovements> = listenToPointerMoves();

// Whenever `pointerMoves$` emits, the `pointerMove` event fires.
  pointerMove = outputFromObservable(this.pointerMoves$);
}
```

`outputFromObservable` 函式對 Angular 編譯器具有特殊意義。**你只能在元件與指令的屬性初始化運算式中呼叫 `outputFromObservable`**。

當你 `subscribe` 這個輸出時，Angular 會自動把訂閱轉發給底層的 observable。當元件或指令被銷毀時，Angular 就會停止轉發值。

HELPFUL: 如果你能以命令式的方式發送值，可以考慮直接使用 `output()`。

## 從元件或指令輸出建立 RxJS Observable

`outputToObservable` 函式讓你從元件輸出建立 RxJS observable。

```ts
{highlight:[11]}
import {outputToObservable} from '@angular/core/rxjs-interop';
import {Component, output} from '@angular/core';

@Component(/*...*/)
class CustomSlider {
    valueChange = output<number>();
}

// Instance reference to `CustomSlider`.
const slider: CustomSlider = createSlider();

outputToObservable(slider.valueChange) // Observable<number>
    .pipe(...)
    .subscribe(...);
```

HELPFUL: 如果 `OutputRef` 上的 `subscribe` 方法已能滿足你的需求，可以考慮直接使用它。
# 設定 `HttpClient`

在 Angular v21 及之後版本，`HttpClient` 預設即可供注入使用。

## 透過依賴注入提供 `HttpClient`

你可以使用 `provideHttpClient` 輔助函式，在 `app.config.ts` 的應用程式 `providers` 中設定預設的 HTTP 功能集，或加入其他功能。

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(/* add features here, such as withInterceptors(...) */)],
};
```

如果你的應用程式改用以 NgModule 為基礎的啟動方式，你可以把 `provideHttpClient` 加入應用程式 NgModule 的 providers，以設定預設的 HTTP 功能集或加入其他功能：

```ts
@NgModule({
  providers: [provideHttpClient(/* add features here, such as withInterceptors(...) */)],
  // ... other application configuration
})
export class AppModule {}
```

之後，你就可以把 `HttpClient` 服務注入為元件、服務或其他類別的依賴：

```ts
@Service()
export class ConfigService {
  private http = inject(HttpClient);
  // This service can now make HTTP requests via `this.http`.
}
```

## 設定 `HttpClient` 的功能

`provideHttpClient` 接受一份選用的功能設定清單，用來啟用或設定用戶端的各個面向。本節詳述這些選用功能與其用法。

### `withXhr`

```ts
export const appConfig: ApplicationConfig = {
  providers: [provideHttpClient(withXhr())],
};
```

`HttpClient` 預設使用 [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) API 來發出請求。`withXhr` 功能會把用戶端改為使用 [`XMLHttpRequest`](https://developer.mozilla.org/docs/Web/API/XMLHttpRequest) API。

`fetch` 是較現代的 API，可用於少數不支援 `XMLHttpRequest` 的環境。不過它也有一些限制，例如不會產生上傳進度事件。
伺服器上的 XHR 支援已**棄用**，預計在 Angular 23 移除。底層的 `xhr2` 函式庫無法安全地處理重新導向：它可能在跨來源重新導向時轉送 `Authorization` 標頭，也容易因重新導向迴圈而遭受阻斷服務（DoS）攻擊。SSR 應用程式請改用預設的 `fetch` 後端。
### `withInterceptors(...)`

`withInterceptors` 用來設定一組攔截器函式，負責處理透過 `HttpClient` 發出的請求。詳情請見[攔截器指南](guide/http/interceptors)。

### `withInterceptorsFromDi()`

`withInterceptorsFromDi` 會把舊式的類別型攔截器納入 `HttpClient` 設定。詳情請見[攔截器指南](guide/http/interceptors)。

HELPFUL: 函式型攔截器（透過 `withInterceptors`）的執行順序較可預期，建議優先於 DI 型攔截器使用。

### `withRequestsMadeViaParent()`

預設情況下，當你在某個注入器內使用 `provideHttpClient` 設定 `HttpClient` 時，該設定會覆蓋上層注入器中可能存在的任何 `HttpClient` 設定。

加入 `withRequestsMadeViaParent()` 後，`HttpClient` 會改為把請求往上傳給上層注入器的 `HttpClient` 執行個體，前提是請求已先通過本層級設定的所有攔截器。當你想在子注入器中「加入」攔截器、同時仍讓請求通過上層注入器的攔截器時，這個功能很有用。

CRITICAL: 你必須在目前注入器的上層設定一個 `HttpClient` 執行個體，否則此選項無效，使用時會發生執行階段錯誤。

### `withJsonpSupport()`
`withJsonpSupport`、`HttpClientJsonpModule` 以及 `HttpClient` 的 `.jsonp()` 方法都已棄用，因為 JSONP 可能造成跨網站指令碼（XSS）弱點。請改用搭配 [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) 的標準 HTTP 請求。
加入 `withJsonpSupport` 會啟用 `HttpClient` 的 `.jsonp()` 方法，透過 [JSONP 慣例](https://en.wikipedia.org/wiki/JSONP)以 GET 請求跨網域載入資料。

HELPFUL: 進行跨網域請求時，請盡可能優先使用 [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) 而非 JSONP。

### `withXsrfConfiguration(...)`

加入此選項可自訂 `HttpClient` 內建的 XSRF 安全功能。詳情請見[安全性指南](best-practices/security)。

### `withNoXsrfProtection()`

加入此選項會停用 `HttpClient` 內建的 XSRF 安全功能。詳情請見[安全性指南](best-practices/security)。

## 以 `HttpClientModule` 為基礎的設定

有些應用程式可能使用較舊的、以 NgModule 為基礎的 API 來設定 `HttpClient`。

下表列出 `@angular/common/http` 提供的 NgModule，以及它們與上方 provider 設定函式的對應關係。

| **NgModule**                            | `provideHttpClient()` 的對應寫法                         |
| --------------------------------------- | -------------------------------------------------------- |
| `HttpClientModule`                      | `provideHttpClient(withInterceptorsFromDi(), withXhr())` |
| `HttpClientJsonpModule`（已棄用）    | `withJsonpSupport()`（已棄用）                        |
| `HttpClientXsrfModule.withOptions(...)` | `withXsrfConfiguration(...)`                             |
| `HttpClientXsrfModule.disable()`        | `withNoXsrfProtection()`                                 |

NOTE: `HttpClientModule` 與 `HttpClientXsrfModule` 也已棄用。請改用 `provideHttpClient` 搭配對應的功能。
當 `HttpClientModule` 同時存在於多個注入器時，攔截器的行為並不明確，會受到確切選項以及 provider／匯入順序的影響。

多注入器設定請優先使用 `provideHttpClient`，其行為較穩定。詳情請見上方的 `withRequestsMadeViaParent` 功能。

# 發出 HTTP 請求

`HttpClient` 具有對應各種 HTTP 動詞的方法，用來發出請求，既可載入資料，也可對伺服器套用變更。每個方法都會回傳一個 [RxJS `Observable`](https://rxjs.dev/guide/observable)，當它被訂閱時，就會送出請求，並在伺服器回應時發出結果。

NOTE: 由 `HttpClient` 建立的 `Observable` 可以被訂閱任意多次，每次訂閱都會向後端發出一個新請求。

透過傳給請求方法的 options 物件，可以調整請求的各種屬性，以及回傳的回應型別。

## 擷取 JSON 資料 {#fetching-json-data}

從後端擷取資料通常需要使用 [`HttpClient.get()`](api/common/http/HttpClient#get) 方法發出 GET 請求。此方法接受兩個參數：要擷取資料的字串端點 URL，以及一個用來設定請求的「選用 options」物件。

例如，使用 `HttpClient.get()` 方法從一個假設的 API 擷取設定資料：

```ts
http.get<Config>('/api/config').subscribe((config) => {
  // process the configuration.
});
```

請注意其中的泛型型別參數，它指定伺服器回傳的資料型別為 `Config`。此參數為選用，如果省略，回傳資料的型別將為 `Object`。

TIP: 處理結構不確定、且可能含 `undefined` 或 `null` 值的資料時，請考慮使用 `unknown` 型別而非 `Object` 作為回應型別。

CRITICAL: 請求方法的泛型型別，是對伺服器回傳資料的一種型別「斷言」。`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('The image is ' + buffer.byteLength + ' bytes large');
});
```
因為 `responseType` 的值會影響 `HttpClient` 回傳的型別，它必須是字面型別，而非 `string` 型別。

如果傳給請求方法的 options 物件本身是字面物件，這會自動成立；但如果你把請求選項抽出到變數或輔助方法中，你可能需要明確將其指定為字面值，例如 `responseType: 'text' as const`。
## 變更伺服器狀態

執行變更的伺服器 API，通常需要發出 POST 請求，並在請求主體中指定新狀態或要套用的變更。

[`HttpClient.post()`](api/common/http/HttpClient#post) 方法的行為與 `get()` 類似，並在其 options 之前接受一個額外的 `body` 參數：

```ts
http.post<Config>('/api/config', newConfig).subscribe((config) => {
  console.log('Updated config:', config);
});
```

請求的 `body` 可以提供許多不同型別的值，`HttpClient` 會相應地將它們序列化：

| **`body` 型別**                                                                                                               | **序列化為**                                    |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| string                                                                                                                        | 純文字                                           |
| number、boolean、array 或 plain object                                                                                       | JSON                                                 |
| [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)                       | 來自緩衝區的原始資料                             |
| [`Blob`](https://developer.mozilla.org/docs/Web/API/Blob)                                                                     | 帶有 `Blob` 內容型別的原始資料              |
| [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData)                                                             | `multipart/form-data` 編碼資料                   |
| [`HttpParams`](api/common/http/HttpParams) 或 [`URLSearchParams`](https://developer.mozilla.org/docs/Web/API/URLSearchParams) | `application/x-www-form-urlencoded` 格式字串 |

IMPORTANT: 請記得對變更請求的 `Observable` 呼叫 `.subscribe()`，請求才會真正發出。

## 設定 URL 參數 {#setting-url-parameters}

使用 `params` 選項，指定應包含在請求 URL 中的請求參數。

傳入物件字面值是設定 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) => {
    // ...
  });
```

你可以使用自訂的 `HttpParameterCodec` 來建立 `HttpParams`，由它決定 `HttpClient` 如何將參數編碼進 URL。

### 自訂參數編碼 {#custom-parameter-encoding}

`HttpParams` 預設使用內建的 [`HttpUrlEncodingCodec`](api/common/http/HttpUrlEncodingCodec) 來編碼與解碼參數的鍵與值。

你可以提供自己的 [`HttpParameterCodec`](api/common/http/HttpParameterCodec) 實作，自訂編碼與解碼的套用方式。

```ts
import {HttpClient, HttpParams, HttpParameterCodec} from '@angular/common/http';
import {inject} from '@angular/core';

export class CustomHttpParamEncoder implements HttpParameterCodec {
  encodeKey(key: string): string {
    return encodeURIComponent(key);
  }

encodeValue(value: string): string {
    return encodeURIComponent(value);
  }

decodeKey(key: string): string {
    return decodeURIComponent(key);
  }

decodeValue(value: string): string {
    return decodeURIComponent(value);
  }
}

export class ApiService {
  private http = inject(HttpClient);

search() {
    const params = new HttpParams({
      encoder: new CustomHttpParamEncoder(),
    })
      .set('email', 'dev+alerts@example.com')
      .set('q', 'a & b? c/d = e');

return this.http.get('/api/items', {params});
  }
}
```

## 設定請求標頭 {#setting-request-headers}

使用 `headers` 選項，指定應包含在請求中的請求標頭。

傳入物件字面值是設定請求標頭最簡單的方式：

```ts
http
  .get('/api/config', {
    headers: {
      'X-Debug-Level': 'verbose',
    },
  })
  .subscribe((config) => {
    // ...
  });
```

或者，如果你需要對標頭的建構有更多控制，可以傳入 `HttpHeaders` 的執行個體。

IMPORTANT: `HttpHeaders` 的執行個體是「不可變」的，無法直接變更。變更方法（例如 `append()`）會回傳一個套用了變更的新 `HttpHeaders` 執行個體。

```ts
const baseHeaders = new HttpHeaders().set('X-Debug-Level', 'minimal');

http
  .get<Config>('/api/config', {
    headers: baseHeaders.set('X-Debug-Level', 'verbose'),
  })
  .subscribe((config) => {
    // ...
  });
```

## 與伺服器回應事件互動 {#interacting-with-the-server-response-events}

為了方便，`HttpClient` 預設回傳伺服器回傳資料（回應主體）的 `Observable`。有時我們會想檢視實際的回應，例如擷取特定的回應標頭。

若要存取完整的回應，請將 `observe` 選項設定為 `'response'`：

```ts
http.get<Config>('/api/config', {observe: 'response'}).subscribe((res) => {
  console.log('Response status:', res.status);
  console.log('Body:', res.body);
});
```
因為 `observe` 的值會影響 `HttpClient` 回傳的型別，它必須是字面型別，而非 `string` 型別。

如果傳給請求方法的 options 物件本身是字面物件，這會自動成立；但如果你把請求選項抽出到變數或輔助方法中，你可能需要明確將其指定為字面值，例如 `observe: 'response' as const`。
## 接收原始進度事件 {#receiving-raw-progress-events}

除了回應主體或回應物件之外，`HttpClient` 也可以回傳一串原始「事件」，對應請求生命週期中的特定時刻。這些事件包括請求送出時、回應標頭回傳時，以及主體完成時。這些事件還可以包括「進度事件」，回報大型請求或回應主體的上傳與下載狀態。

進度事件預設為停用（因為它們有效能成本），但可以透過 `reportUploadProgress` 與 `reportDownloadProgress` 選項啟用。

NOTE: `HttpClient` 的預設 fetch 後端不支援「上傳」進度事件，如果你設定 `reportUploadProgress` 將會擲出錯誤。如果你的應用程式需要上傳進度事件，請在 `provideHttpClient(...)` 中以 `withXhr()` 設定 `HttpClient`。

若要觀察事件串流，請將 `observe` 選項設定為 `'events'`：

```ts
http
  .get('/api/download', {
    reportDownloadProgress: true,
    observe: 'events',
  })
  .subscribe((event) => {
    switch (event.type) {
      case HttpEventType.DownloadProgress:
        console.log('Downloaded ' + event.loaded + ' out of ' + event.total + ' bytes');
        break;
      case HttpEventType.Response:
        console.log('Finished downloading!');
        break;
    }
  });
```
因為 `observe` 的值會影響 `HttpClient` 回傳的型別，它必須是字面型別，而非 `string` 型別。

如果傳給請求方法的 options 物件本身是字面物件，這會自動成立；但如果你把請求選項抽出到變數或輔助方法中，你可能需要明確將其指定為字面值，例如 `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 請求可能以三種方式失敗：

- 網路或連線錯誤可能使請求無法到達後端伺服器。
- 當設定了 timeout 選項時，請求未在時間內回應。
- 後端可以收到請求，但處理失敗，並回傳錯誤回應。

`HttpClient` 會將上述所有類型的錯誤擷取在 `HttpErrorResponse` 中，並透過 `Observable` 的錯誤通道回傳。網路與逾時錯誤的 `status` 碼為 `0`。對於逾時，`error` 是名為 `TimeoutError` 的 `DOMException`；對於網路錯誤，則是 `fetch` 擲出的錯誤（或使用 `withXhr()` 時為 [`ProgressEvent`](https://developer.mozilla.org/docs/Web/API/ProgressEvent)）。後端錯誤帶有後端回傳的失敗 `status` 碼，並以錯誤回應作為 `error`。請檢查回應，以找出錯誤的成因，以及處理錯誤的適當行動。

[RxJS 函式庫](https://rxjs.dev/)提供多個對錯誤處理有幫助的運算子。

你可以使用 `catchError` 運算子，將錯誤回應轉換為給 UI 使用的值。這個值可以告訴 UI 顯示錯誤頁面或錯誤值，並在必要時擷取錯誤的成因。

有時，網路中斷等暫時性錯誤可能導致請求意外失敗，而只要重試請求就能成功。RxJS 提供多個「重試」運算子，會在特定條件下自動重新訂閱失敗的 `Observable`。例如，`retry()` 運算子會自動嘗試重新訂閱指定的次數。

### 逾時

若要為請求設定逾時，你可以將 `timeout` 選項連同其他請求選項一起設定為毫秒數。如果後端請求未在指定時間內完成，請求將被中止，並發出一個錯誤。

NOTE: 逾時只會套用到後端 HTTP 請求本身。它不是整個請求處理鏈的逾時。因此，此選項不受攔截器引入的任何延遲影響。

```ts
http
  .get('/api/config', {
    timeout: 3000,
  })
  .subscribe({
    next: (config) => {
      console.log('Config fetched successfully:', config);
    },
    error: (err) => {
      // If the request times out, an error will have been emitted.
    },
  });
```

## 進階 fetch 選項 {#advanced-fetch-options}

Angular 的 `HttpClient` 支援進階的 fetch API 選項，可以提升效能與使用者體驗。這些選項在使用 fetch 後端時可用，而 fetch 後端是預設後端。

### Fetch 選項

下列選項在使用 fetch 後端時，能對請求行為提供細粒度的控制。

#### 保持連線（keep-alive）

`keepalive` 選項讓請求的生命週期能超過發起它的頁面。這對於分析或記錄請求特別有用，因為這類請求即使在使用者離開頁面後也需要完成。

```ts
http
  .post('/api/analytics', analyticsData, {
    keepalive: true,
  })
  .subscribe();
```

#### HTTP 快取控制

`cache` 選項控制請求如何與瀏覽器的 HTTP 快取互動，這能顯著提升重複請求的效能。

```ts
//  Use cached response regardless of freshness
http
  .get('/api/config', {
    cache: 'force-cache',
  })
  .subscribe((config) => {
    // ...
  });

// Always fetch from network, bypass cache
http
  .get('/api/live-data', {
    cache: 'no-cache',
  })
  .subscribe((data) => {
    // ...
  });

// Use cached response only, fail if not in cache
http
  .get('/api/static-data', {
    cache: 'only-if-cached',
  })
  .subscribe((data) => {
    // ...
  });
```

#### 用於 Core Web Vitals 的請求優先級

`priority` 選項讓你指出請求的相對重要性，協助瀏覽器最佳化資源載入，以獲得更好的 Core Web Vitals 分數。

```ts
// High priority for critical resources
http
  .get('/api/user-profile', {
    priority: 'high',
  })
  .subscribe((profile) => {
    // ...
  });

// Low priority for non-critical resources
http
  .get('/api/recommendations', {
    priority: 'low',
  })
  .subscribe((recommendations) => {
    // ...
  });

// Auto priority (default) lets the browser decide
http
  .get('/api/settings', {
    priority: 'auto',
  })
  .subscribe((settings) => {
    // ...
  });
```

可用的 `priority` 值：

- `'high'`：高優先級，提早載入（例如關鍵使用者資料、首屏即可見的內容）
- `'low'`：低優先級，在資源可用時載入（例如分析、預擷取資料）
- `'auto'`：瀏覽器依請求上下文決定優先級（預設）

TIP: 對於影響最大內容繪製（LCP）的請求，請使用 `priority: 'high'`；對於不影響初始使用者體驗的請求，請使用 `priority: 'low'`。

#### 請求模式

`mode` 選項控制請求如何處理跨來源請求，並決定回應型別。

```ts
// Same-origin requests only
http
  .get('/api/local-data', {
    mode: 'same-origin',
  })
  .subscribe((data) => {
    // ...
  });

// CORS-enabled cross-origin requests
http
  .get('https://api.external.com/data', {
    mode: 'cors',
  })
  .subscribe((data) => {
    // ...
  });

// No-CORS mode for simple cross-origin requests
http
  .get('https://external-api.com/public-data', {
    mode: 'no-cors',
  })
  .subscribe((data) => {
    // ...
  });
```

可用的 `mode` 值：

- `'same-origin'`：只允許同來源請求，跨來源請求將失敗
- `'cors'`：允許搭配 CORS 的跨來源請求（預設）
- `'no-cors'`：允許不搭配 CORS 的簡單跨來源請求，回應為不透明（opaque）

TIP: 在瀏覽器中，對於絕不應跨來源的敏感請求，請使用 `mode: 'same-origin'`。

IMPORTANT: 在 Node.js 上進行 SSR 期間，`HttpClient` 使用 Node.js 的 [Undici 版 Fetch 實作](https://nodejs.org/api/globals.html#fetch)。[Undici 不強制執行瀏覽器的 CORS 檢查](https://undici.nodejs.org/#cors)，因此 `mode: 'same-origin'` 不會限制伺服器端請求。請針對允許清單驗證受使用者影響的 URL。

#### 重新導向處理

`redirect` 選項指定如何處理來自伺服器的重新導向回應。

```ts
// Follow redirects automatically (default behavior)
http
  .get('/api/resource', {
    redirect: 'follow',
  })
  .subscribe((data) => {
    // ...
  });

// Prevent automatic redirects
http
  .get('/api/resource', {
    redirect: 'manual',
  })
  .subscribe((response) => {
    // Handle redirect manually
  });

// Treat redirects as errors
http
  .get('/api/resource', {
    redirect: 'error',
  })
  .subscribe({
    next: (data) => {
      // Success response
    },
    error: (err) => {
      // Redirect responses will trigger this error handler
    },
  });
```

可用的 `redirect` 值：

- `'follow'`：自動跟隨重新導向（預設）
- `'error'`：將重新導向視為錯誤
- `'manual'`：不自動跟隨重新導向，回傳重新導向回應

TIP: 當你需要以自訂邏輯處理重新導向時，請使用 `redirect: 'manual'`。

#### 憑證處理

`credentials` 選項控制在跨來源請求時，是否隨請求傳送 cookie、授權標頭及其他憑證。這在驗證情境中特別重要。

```ts
// Include credentials for cross-origin requests
http
  .get('https://api.example.com/protected-data', {
    credentials: 'include',
  })
  .subscribe((data) => {
    // ...
  });

// Never send credentials (default for cross-origin)
http
  .get('https://api.example.com/public-data', {
    credentials: 'omit',
  })
  .subscribe((data) => {
    // ...
  });

// Send credentials only for same-origin requests
http
  .get('/api/user-data', {
    credentials: 'same-origin',
  })
  .subscribe((data) => {
    // ...
  });

// withCredentials overrides credentials setting
http
  .get('https://api.example.com/data', {
    credentials: 'omit', // This will be ignored
    withCredentials: true, // This forces credentials: 'include'
  })
  .subscribe((data) => {
    // Request will include credentials despite credentials: 'omit'
  });

// Legacy approach (still supported)
http
  .get('https://api.example.com/data', {
    withCredentials: true,
  })
  .subscribe((data) => {
    // Equivalent to credentials: 'include'
  });
```

IMPORTANT: `withCredentials` 選項的優先級高於 `credentials` 選項。如果兩者都指定，`withCredentials: true` 將一律導致 `credentials: 'include'`，無論明確指定的 `credentials` 值為何。

可用的 `credentials` 值：

- `'omit'`：永不傳送憑證
- `'same-origin'`：只對同來源請求傳送憑證（預設）
- `'include'`：一律傳送憑證，即使是跨來源請求

TIP: 當你需要把驗證 cookie 或標頭傳送到支援 CORS 的不同網域時，請使用 `credentials: 'include'`。避免混用 `credentials` 與 `withCredentials` 選項，以免混淆。

IMPORTANT: 在 Node.js 上進行 SSR 期間，`credentials: 'include'` 不會自動轉送來自瀏覽器請求的 cookie。`credentials` 選項不會移除你明確加入的 `Cookie` 或 `Authorization` 標頭。[Undici 允許某些瀏覽器禁止的標頭](https://undici.nodejs.org/#forbidden-and-safelisted-header-names)，因此只應將憑證標頭轉送至受信任的來源。

#### Referrer

`referrer` 選項讓你控制隨請求傳送的 referrer 資訊。這對隱私與安全考量很重要。

```ts
// Send a specific referrer URL
http
  .get('/api/data', {
    referrer: 'https://example.com/page',
  })
  .subscribe((data) => {
    // ...
  });

// Use the current page as referrer (default behavior)
http
  .get('/api/analytics', {
    referrer: 'about:client',
  })
  .subscribe((data) => {
    // ...
  });
```

`referrer` 選項接受：

- 有效的 URL 字串：設定要傳送的特定 referrer URL
- 空字串 `''`：不傳送 referrer 資訊
- `'about:client'`：使用預設 referrer（目前頁面的 URL）

TIP: 對於不希望洩漏來源頁面 URL 的敏感請求，請使用 `referrer: ''`。

#### Referrer 政策

`referrerPolicy` 選項控制隨 HTTP 請求傳送多少 referrer 資訊，也就是發出請求頁面的 URL。此設定同時影響隱私與分析，讓你在資料可見性與安全考量之間取得平衡。

```ts
// Send no referrer information regardless of the current page
http
  .get('/api/data', {
    referrerPolicy: 'no-referrer',
  })
  .subscribe();

// Send origin only (e.g. https://example.com)
http
  .get('/api/analytics', {
    referrerPolicy: 'origin',
  })
  .subscribe();
```

`referrerPolicy` 選項接受：

- `'no-referrer'` 永不傳送 `Referer` 標頭。
- `'no-referrer-when-downgrade'` 對同來源與安全（HTTPS→HTTPS）請求傳送 referrer，但從安全來源導向較不安全的來源（HTTPS→HTTP）時省略。
- `'origin'` 只傳送 referrer 的來源（scheme、host、port），省略路徑與查詢資訊。
- `'origin-when-cross-origin'` 對同來源請求傳送完整 URL，但對跨來源請求只傳送來源。
- `'same-origin'` 對同來源請求傳送完整 URL，對跨來源請求不傳送 referrer。
- `'strict-origin'` 只傳送來源，且僅在通訊協定安全等級未降級時（例如 HTTPS→HTTPS）。降級時省略 referrer。
- `'strict-origin-when-cross-origin'` 瀏覽器的預設行為。對同來源請求傳送完整 URL；對未降級的跨來源請求傳送來源；降級時省略 referrer。
- `'unsafe-url'` 一律傳送完整 URL（包括路徑與查詢）。這可能暴露敏感資料，應謹慎使用。

TIP: 對於注重隱私的請求，請優先使用保守的值，例如 `'no-referrer'`、`'origin'` 或 `'strict-origin-when-cross-origin'`。

#### 完整性

`integrity` 選項讓你透過提供預期內容的加密雜湊，驗證回應是否遭到竄改。這在從 CDN 載入指令碼或其他資源時特別有用。

```ts
// Verify response integrity with SHA-256 hash
http
  .get('/api/script.js', {
    integrity: 'sha256-ABC123...',
    responseType: 'text',
  })
  .subscribe((script) => {
    // Script content is verified against the hash
  });
```

IMPORTANT: `integrity` 選項要求回應內容與所提供的雜湊完全相符。如果內容不符，請求將以網路錯誤失敗。

CRITICAL: 在 SSR 期間，Fetch 實作會在回傳回應之前讀取整個回應主體來驗證 `integrity`，這是 [Fetch 標準](https://fetch.spec.whatwg.org/#concept-main-fetch)的要求。Angular 只有在 Fetch 回傳回應之後，才強制執行 [`maxResponseBodySize`](/guide/ssr#configuring-the-response-body-size-limit)，因此此限制不會約束在完整性驗證期間緩衝的資料。

TIP: 從外部來源載入關鍵資源時，請使用子資源完整性（subresource integrity）來確保它們未被修改。請使用 `openssl` 等工具產生雜湊。

## HTTP `Observable`

`HttpClient` 上的每個請求方法都會建構並回傳一個所請求回應型別的 `Observable`。在使用 `HttpClient` 時，了解這些 `Observable` 如何運作非常重要。

`HttpClient` 產生 RxJS 所謂的「冷」`Observable`，意思是除非 `Observable` 被訂閱，否則不會發生真正的請求。只有到那時，請求才會真正送往伺服器。多次訂閱同一個 `Observable` 將觸發多次後端請求。每次訂閱都是獨立的。

TIP: 你可以把 `HttpClient` 的 `Observable` 想像成真正伺服器請求的「藍圖」。

一旦訂閱，取消訂閱將中止進行中的請求。如果 `Observable` 是透過 `async` 管道訂閱的，這非常有用，因為當使用者離開目前頁面時，它會自動取消請求。此外，如果你搭配 RxJS 組合器（例如 `switchMap`）使用 `Observable`，這種取消機制會清除所有過時的請求。

回應回傳後，來自 `HttpClient` 的 `Observable` 通常會完成（但攔截器可能影響這一點）。

由於會自動完成，如果不清理 `HttpClient` 的訂閱，通常沒有記憶體洩漏的風險。然而，如同任何非同步操作，我們強烈建議在元件銷毀時清理訂閱，否則訂閱回呼可能會執行，並在試圖與已銷毀的元件互動時遇到錯誤。

TIP: 使用 `async` 管道或 `toSignal` 操作來訂閱 `Observable`，可確保訂閱被妥善處置。

## 最佳實務

雖然 `HttpClient` 可以直接注入並在元件中使用，我們一般建議你建立可重複使用、可注入的服務，將資料存取邏輯隔離並封裝。例如，這個 `UserService` 封裝了依 id 請求使用者資料的邏輯：

```ts
@Service()
export class UserService {
  private http = inject(HttpClient);

getUser(id: string): Observable<User> {
    return this.http.get<User>(`/api/user/${id}`);
  }
}
```

在元件內，你可以結合 `@if` 與 `async` 管道，僅在資料載入完成後，才渲染該資料的 UI：

```typescript
import {AsyncPipe} from '@angular/common';
import {Component, input, inject, effect} from '@angular/core';
import {Observable} from 'rxjs';

@Component({
  imports: [AsyncPipe],
  template: `
    @if (user$ | async; as user) {
      <p>Name: {{ user.name }}</p>
      <p>Biography: {{ user.biography }}</p>
    }
  `,
})
export class UserProfile {
  userId = input.required<string>();
  user$!: Observable<User>;

private userService = inject(UserService);

constructor() {
    effect(() => {
      this.user$ = this.userService.getUser(this.userId());
    });
  }
}
```
# 攔截器

`HttpClient` 支援一種稱為「攔截器」的中介層形式。

TLDR: 攔截器是一種中介層，讓重試、快取、記錄與驗證等常見模式能從個別請求中抽象出來，統一處理。

`HttpClient` 支援兩種攔截器：函式型與 DI 型。我們建議使用函式型攔截器，因為它們的行為較可預期，在複雜設定下尤其如此。本指南的範例使用函式型攔截器，[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(App, {
  providers: [provideHttpClient(withInterceptors([loggingInterceptor, cachingInterceptor]))],
});
```

你設定的攔截器會依你在 providers 中列出的順序串連在一起。在上例中，`loggingInterceptor` 會先處理請求，然後轉交給 `cachingInterceptor`。

### 攔截回應事件 {#intercepting-response-events}

攔截器可以轉換 `next` 回傳的 `HttpEvent` 的 `Observable` 串流，以存取或操作回應。由於此串流包含所有回應事件，為了辨識最終的回應物件，可能需要檢查每個事件的 `.type`。

```ts
export function loggingInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  return next(req).pipe(
    tap((event) => {
      if (event.type === HttpEventType.Response) {
        console.log(req.url, 'returned a response with status', event.status);
      }
    }),
  );
}
```

TIP: 攔截器天生就能把回應與其對應的外送請求關聯起來，因為它們是在擷取了請求物件的閉包中轉換回應串流。

## 修改請求

`HttpRequest` 與 `HttpResponse` 執行個體的大多數面向都是「不可變」的，攔截器無法直接修改它們。攔截器改以使用 `.clone()` 操作複製這些物件，並指定在新執行個體中要變更哪些屬性，來套用變更。這可能涉及對值本身進行不可變更新（例如 `HttpHeaders` 或 `HttpParams`）。

例如，為請求加入一個標頭：

```ts
const reqWithHeader = req.clone({
  headers: req.headers.set('X-New-Header', 'new header value'),
});
```

這種不可變性讓大多數攔截器在同一個 `HttpRequest` 被多次提交到攔截器鏈時，仍能保持冪等。這種情況可能因多種原因發生，包括請求在失敗後被重試時。

CRITICAL: 請求或回應的主體「不」受深層變更的保護。如果攔截器必須變更主體，務必小心處理同一個請求被多次執行的情況。

## 攔截器中的依賴注入

攔截器在註冊它的注入器的「注入上下文」中執行，可以使用 Angular 的 [`inject`](/api/core/inject) API 來取得依賴。

例如，假設應用程式有一個名為 `AuthService` 的服務，負責為外送請求建立驗證權杖。攔截器可以注入並使用這個服務：

```ts
export function authInterceptor(req: HttpRequest<unknown>, next: HttpHandlerFn) {
  // Inject the current `AuthService` and use it to get an authentication token:
  const authToken = inject(AuthService).getAuthToken();

// Clone the request to add the authentication header.
  const newReq = req.clone({
    headers: req.headers.append('X-Authentication-Token', authToken),
  });
  return next(newReq);
}
```

## 請求與回應的中繼資料 {#request-and-response-metadata}

在請求中加入不傳送給後端、而是專門給攔截器使用的資訊，往往很有用。`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)) {
    // apply caching logic
    return ...;
  } else {
    // caching has been disabled for this request
    return next(req);
  }
}
```

### 發出請求時設定上下文權杖

透過 `HttpClient` API 發出請求時，你可以為 `HttpContextToken` 提供值：

```ts
const data$ = http.get('/sensitive/data', {
  context: new HttpContext().set(CACHING_ENABLED, false),
});
```

攔截器可以從請求的 `HttpContext` 讀取這些值。

### 請求上下文是可變的

與 `HttpRequest` 的其他屬性不同，相關聯的 `HttpContext` 是「可變」的。如果攔截器變更了一個之後會被重試的請求的上下文，同一個攔截器在再次執行時會觀察到該上下文變更。在需要跨多次重試傳遞狀態時，這很有用。

## 合成回應

大多數攔截器只會呼叫 `next` 處理器，同時轉換請求或回應，但這並非嚴格必要。本節討論攔截器納入更進階行為的幾種方式。

攔截器不一定要呼叫 `next`。它們可以改為透過其他機制建構回應，例如從快取取得，或透過替代機制傳送請求。

可以使用 `HttpResponse` 建構函式來建構回應：

```ts
const resp = new HttpResponse({
  body: 'response body',
});
```

## 處理重新導向資訊

當 `HttpClient` 使用 fetch 後端時，回應會包含一個 `redirected` 屬性，指出該回應是否為重新導向的結果。此屬性與原生 Fetch API 規格一致，在攔截器處理重新導向情境時很有用。

攔截器可以存取重新導向資訊並據此採取行動：

```ts
export function redirectTrackingInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  return next(req).pipe(
    tap((event) => {
      if (event.type === HttpEventType.Response && event.redirected) {
        console.log('Request to', req.url, 'was redirected to', event.url);
        // Handle redirect logic - maybe update analytics, security checks, etc.
      }
    }),
  );
}
```

你也可以使用重新導向資訊，在攔截器中實作條件邏輯：

```ts
export function authRedirectInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  return next(req).pipe(
    tap((event) => {
      if (event.type === HttpEventType.Response && event.redirected) {
        // Check if we were redirected to a login page
        if (event.url?.includes('/login')) {
          // Handle authentication redirect
          handleAuthRedirect();
        }
      }
    }),
  );
}
```

## 處理回應型別

當 `HttpClient` 使用 fetch 後端時，回應會包含一個 `responseType` 屬性，指出瀏覽器如何依 CORS 政策與請求模式處理該回應。此屬性與原生 Fetch API 規格一致，為除錯 CORS 問題與了解回應可存取性提供寶貴的線索。

回應的 `responseType` 屬性可以是下列值：

- `'basic'`：同來源回應，所有標頭皆可存取
- `'cors'`：跨來源回應，CORS 標頭已正確設定
- `'opaque'`：沒有 CORS 的跨來源回應，標頭與主體可能受限
- `'opaqueredirect'`：在 no-cors 模式下，來自重新導向請求的回應
- `'error'`：發生網路錯誤

攔截器可以利用回應型別資訊進行 CORS 除錯與錯誤處理：

```ts
export function responseTypeInterceptor(
  req: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  return next(req).pipe(
    tap((event) => {
      if (event.type === HttpEventType.Response) {
        // Handle different response types appropriately
        switch (event.responseType) {
          case 'opaque':
            // Limited access to response data
            console.warn('Limited response data due to CORS policy');
            break;
          case 'cors':
          case 'basic':
            // Full access to response data
            break;
          case 'error':
            // Handle network errors
            console.error('Network error in response');
            break;
        }
      }
    }),
  );
}
```

## 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 型攔截器透過依賴注入的多重 provider 來設定：

```ts
bootstrapApplication(App, {
  providers: [
    provideHttpClient(
      // DI-based interceptors must be explicitly enabled.
      withInterceptorsFromDi(),
    ),

{provide: HTTP_INTERCEPTORS, useClass: LoggingInterceptor, multi: true},
  ],
});
```

DI 型攔截器依其 provider 註冊的順序執行。在 DI 設定龐大且具階層的應用程式中，這個順序可能非常難以預測。
# 測試請求

如同任何外部依賴，你必須模擬 HTTP 後端，讓測試能模擬與遠端伺服器的互動。`@angular/common/http/testing` 函式庫提供工具，用來擷取應用程式發出的請求、對這些請求進行斷言，並模擬回應以仿效後端的行為。

此測試函式庫的設計模式是：應用程式先執行程式碼並發出請求。接著，測試預期某些請求已經或尚未發出，對這些請求進行斷言，最後透過對每個預期請求呼叫「flush」來提供回應。

最後，測試可以驗證應用程式沒有發出任何未預期的請求。

## 測試設定

若要開始測試 `HttpClient` 的用法，請設定 `TestBed`，並在測試設定中加入 `provideHttpClientTesting()`。`HttpClient` 由 Angular 的測試環境提供，而 `provideHttpClientTesting()` 會把它設定為使用測試後端，而非真實網路。它同時提供 `HttpTestingController`，你將用它與測試後端互動、設定對已發出請求的預期，並對這些請求送出回應（flush）。設定完成後，`HttpTestingController` 可以從 `TestBed` 注入取得。

```ts
TestBed.configureTestingModule({
  providers: [
    // ... other test providers
    provideHttpClientTesting(),
  ],
});

const httpTesting = TestBed.inject(HttpTestingController);
```

現在，當你的測試發出請求時，它們會打到測試後端，而非一般後端。你可以使用 `httpTesting` 對這些請求進行斷言。

### 在測試中設定 `HttpClient`

如果測試需要設定 `HttpClient` 的功能，例如攔截器，請在 `provideHttpClientTesting()` 之前先加入 `provideHttpClient(...)`。
IMPORTANT: 請務必在 `provideHttpClientTesting()` 「之前」提供 `provideHttpClient()`，因為 `provideHttpClientTesting()` 會覆寫 `provideHttpClient()` 的部分內容。順序顛倒可能會讓你的測試壞掉。

```ts
TestBed.configureTestingModule({
  providers: [provideHttpClient(withInterceptors([authInterceptor])), provideHttpClientTesting()],
});
```

## 預期與回應請求

例如，你可以撰寫一個測試，預期會發生一個 GET 請求，並提供一個模擬回應：

```ts
TestBed.configureTestingModule({
  providers: [ConfigService, provideHttpClientTesting()],
});

const httpTesting = TestBed.inject(HttpTestingController);

// Load `ConfigService` and request the current configuration.
const service = TestBed.inject(ConfigService);
const config$ = service.getConfig<Config>();

// `firstValueFrom` subscribes to the `Observable`, which makes the HTTP request,
// and creates a `Promise` of the response.
const configPromise = firstValueFrom(config$);

// At this point, the request is pending, and we can assert it was made
// via the `HttpTestingController`:
const req = httpTesting.expectOne('/api/config', 'Request to load the configuration');

// We can assert various properties of the request if desired.
expect(req.request.method).toBe('GET');

// Flushing the request causes it to complete, delivering the result.
req.flush(DEFAULT_CONFIG);

// We can then assert that the response was successfully delivered by the `ConfigService`:
expect(await configPromise).toEqual(DEFAULT_CONFIG);

// Finally, we can assert that no other requests were made.
httpTesting.verify();
```

NOTE: 如果測試發出了多個符合指定條件的請求，`expectOne` 將會失敗。

除了對 `req.method` 進行斷言，你也可以改用 `expectOne` 的擴充形式，同時比對請求方法：

```ts
const req = httpTesting.expectOne(
  {
    method: 'GET',
    url: '/api/config',
  },
  'Request to load the configuration',
);
```

HELPFUL: 預期 API 會比對請求的完整 URL，包括任何查詢參數。

最後一個步驟 — 驗證沒有請求仍未處理 — 相當常見，你可以把它移到 `afterEach()` 步驟中：

```ts
afterEach(() => {
  // Verify that none of the tests make any extra HTTP requests.
  TestBed.inject(HttpTestingController).verify();
});
```

## 一次處理多個請求

如果你的測試需要回應重複的請求，請使用 `match()` API 而非 `expectOne()`。它接受相同的參數，但回傳一個符合條件的請求陣列。回傳後，這些請求會從後續的比對中移除，你需要負責對它們送出回應並驗證。

```ts
const allGetRequests = httpTesting.match({method: 'GET'});
for (const req of allGetRequests) {
  // Handle responding to each request.
}
```

## 進階比對

所有比對函式都接受述詞函式，以進行自訂比對邏輯：

```ts
// Look for one request that has a request body.
const requestsWithBody = httpTesting.expectOne((req) => req.body !== null);
```

`expectNone` 函式斷言沒有請求符合指定條件。

```ts
// Assert that no mutation requests have been issued.
httpTesting.expectNone((req) => req.method !== 'GET');
```

## 測試錯誤處理

你應該測試應用程式在 HTTP 請求失敗時的回應。

### 後端錯誤

若要測試後端錯誤的處理（當伺服器回傳非成功的狀態碼時），請以錯誤回應對請求呼叫 flush，模擬後端在請求失敗時會回傳的內容。

```ts
const req = httpTesting.expectOne('/api/config');
req.flush('Failed!', {status: 500, statusText: 'Internal Server Error'});

// Assert that the application successfully handled the backend error.
```

### 網路錯誤

請求也可能因網路錯誤而失敗，`HttpClient` 會將這類錯誤回報為 `status` 為 `0` 的 `HttpErrorResponse`。你可以用 `error()` 方法模擬這類錯誤，它會把給定的 `ProgressEvent` 包裝成這種回應：

```ts
const req = httpTesting.expectOne('/api/config');
req.error(new ProgressEvent('network error!'));

// Assert that the application successfully handled the network error.
```

## 測試攔截器

你應該測試攔截器在預期情況下是否正常運作。

例如，應用程式可能需要把由服務產生的驗證權杖加入每個外送請求。
這個行為可以透過使用攔截器來強制實現：

```ts
export function authInterceptor(
  request: HttpRequest<unknown>,
  next: HttpHandlerFn,
): Observable<HttpEvent<unknown>> {
  const authService = inject(AuthService);

const clonedRequest = request.clone({
    headers: request.headers.append('X-Authentication-Token', authService.getAuthToken()),
  });
  return next(clonedRequest);
}
```

這個攔截器的 `TestBed` 設定應依賴 `withInterceptors` 功能。

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    // Testing one interceptor at a time is recommended.
    provideHttpClient(withInterceptors([authInterceptor])),
    provideHttpClientTesting(),
  ],
});
```

`HttpTestingController` 可以取得請求執行個體，接著便可檢查它，以確保請求已被修改。

```ts
const service = TestBed.inject(AuthService);
const http = TestBed.inject(HttpClient);

// Make an HTTP request.
const response = firstValueFrom(http.get('/api/config'));

const req = httpTesting.expectOne('/api/config');

expect(req.request.headers.get('X-Authentication-Token')).toEqual(service.getAuthToken());
```

類似的攔截器也可以用類別型攔截器實作：

```ts
@Injectable()
export class AuthInterceptor implements HttpInterceptor {
  private authService = inject(AuthService);

intercept(request: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>> {
    const clonedRequest = request.clone({
      headers: request.headers.append('X-Authentication-Token', this.authService.getAuthToken()),
    });
    return next.handle(clonedRequest);
  }
}
```

若要測試它，`TestBed` 設定應改為：

```ts
TestBed.configureTestingModule({
  providers: [
    AuthService,
    provideHttpClient(withInterceptorsFromDi()),
    provideHttpClientTesting(),
    // We rely on the HTTP_INTERCEPTORS token to register the AuthInterceptor as an HttpInterceptor
    {provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true},
  ],
});
```
# 反應式表單

反應式表單提供一種模型驅動的方法，來處理值會隨時間變化的表單輸入。
本指南說明如何建立與更新一個基本的表單控制項、在群組中使用多個控制項、驗證表單值，以及建立可以在執行階段新增或移除控制項的動態表單。

## 反應式表單概觀

反應式表單使用明確且不可變的方法，來管理表單在某個時間點的狀態。
表單狀態的每次變更都會回傳一個新狀態，讓模型在變更之間維持完整性。
反應式表單建立在 observable 串流之上，其中表單輸入與值被提供為可同步存取的串流。

反應式表單也提供了直接的測試路徑，因為你能確信在被要求時，你的資料是一致且可預測的。
這些串流的任何消費者都可以安全地操作資料。

反應式表單與[範本驅動表單](guide/forms/template-driven-forms)在明顯的方面有所不同。
反應式表單提供對資料模型的同步存取、以 observable 運算子實現的不可變性，以及透過 observable 串流進行的變更追蹤。

範本驅動表單允許直接存取以修改範本中的資料，但不如反應式表單明確，因為它們依賴嵌在範本中的指令，以及可變資料來非同步追蹤變更。
兩種範式之間的詳細比較請見[表單概觀](guide/forms)。

## 加入一個基本的表單控制項 {#adding-a-basic-form-control}

使用表單控制項有三個步驟。

1. 產生一個新元件，並註冊反應式表單模組。這個模組宣告了使用反應式表單所需的反應式表單指令。
1. 實例化一個新的 `FormControl`。
1. 在範本中註冊該 `FormControl`。

接著，你可以把元件加入範本，來顯示表單。

下列範例示範如何加入單一表單控制項。
在範例中，使用者把姓名輸入到一個輸入欄位，擷取該輸入值，並顯示表單控制項元素的目前值。

<docs-workflow>

<docs-step title="產生新元件並匯入 ReactiveFormsModule">
使用 CLI 指令 `ng generate component` 在你的專案中產生一個元件，並從 `@angular/forms` 套件匯入 `ReactiveFormsModule`，把它加入元件的 `imports` 陣列。

<docs-code header="name-editor.component.ts (excerpt)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" region="imports" />
</docs-step>

<docs-step title="宣告一個 FormControl 實例">
使用 `FormControl` 的建構子設定它的初始值，在這個案例中是一個空字串。透過在元件類別中建立這些控制項，你可以立即存取它們，監聽、更新並驗證表單輸入的狀態。

<docs-code header="name-editor.component.ts" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" region="create-control"/>
</docs-step>

<docs-step title="在範本中註冊控制項">
在元件類別中建立控制項之後，你必須把它與範本中的表單控制項元素建立關聯。使用 `FormControlDirective` 提供的 `formControl` 繫結來更新範本，該指令同樣包含在 `ReactiveFormsModule` 中。

<docs-code header="name-editor.component.html" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="control-binding" />

使用範本繫結語法後，表單控制項現在已註冊到範本中的 `name` 輸入元素。表單控制項與 DOM 元素彼此溝通：view 反映模型中的變更，模型也反映 view 中的變更。
</docs-step>

<docs-step title="顯示元件">
當 `<app-name-editor>` 元件被加入範本時，指派給 `name` 屬性的 `FormControl` 就會被顯示。

<docs-code header="app.component.html (name editor)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" region="app-name-editor"/>
</docs-step>
</docs-workflow>

### 顯示表單控制項的值

你可以用下列方式顯示值：

- 透過 `valueChanges` observable，你可以使用 `AsyncPipe` 在範本中監聽表單值的變更，或在元件類別中使用 `subscribe()` 方法監聽
- 使用 `value` 屬性，它提供目前值的快照

下列範例示範如何使用範本中的插值顯示目前值。

<docs-code header="name-editor.component.html (control value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="display-value"/>

當你更新表單控制項元素時，顯示的值也會隨之變更。

反應式表單透過每個實例所提供的屬性與方法，提供對指定控制項資訊的存取。
底層 [AbstractControl](api/forms/AbstractControl 'API 參考文件') 類別的這些屬性與方法，被用來控制表單狀態，並決定在處理[輸入驗證](#validating-form-input '進一步了解如何驗證表單輸入')時何時顯示訊息。

其他 `FormControl` 屬性與方法請見 [API 參考文件](api/forms/FormControl '詳細語法參考')。

### 取代表單控制項的值

反應式表單有以程式化方式變更控制項值的方法，讓你能靈活地在沒有使用者互動的情況下更新值。
表單控制項實例提供了一個 `setValue()` 方法，它會更新表單控制項的值，並依據控制項的結構驗證所提供值的結構。
例如，當從後端 API 或服務擷取表單資料時，使用 `setValue()` 方法把控制項更新為它的新值，完全取代舊值。

下列範例為元件類別加入一個方法，使用 `setValue()` 方法把控制項的值更新為 _Nancy_。

<docs-code header="name-editor.component.ts (update value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.ts" region="update-value"/>

在範本中加入一個按鈕，模擬姓名更新。
當你點選 **Update Name** 按鈕時，表單控制項元素中輸入的值會反映為它的目前值。

<docs-code header="name-editor.component.html (update value)" path="adev/src/content/examples/reactive-forms/src/app/name-editor/name-editor.component.html" region="update-value"/>

表單模型是控制項的真相來源，因此當你點選按鈕時，輸入的值會在元件類別中被變更，覆寫它的目前值。

HELPFUL: 在這個範例中，你使用的是單一控制項。
當對[表單群組](#grouping-form-controls)或[表單陣列](#creating-dynamic-forms)實例使用 `setValue()` 方法時，值需要符合群組或陣列的結構。

## 將表單控制項分組 {#grouping-form-controls}

表單通常包含數個相關的控制項。
反應式表單提供兩種方法，將多個相關控制項分組為單一輸入表單。

| 表單群組 | 說明                                                                                                                                                                                                                                                |
| :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 表單群組  | 定義一個帶有固定一組控制項的表單，你可以把它們一起管理。表單群組的基礎在本節討論。你也可以[巢狀表單群組](#creating-nested-form-groups '進一步了解巢狀群組')來建立更複雜的表單。 |
| 表單陣列  | 定義一個動態表單，你可以在執行階段新增與移除控制項。你也可以巢狀表單陣列來建立更複雜的表單。這個選項的詳情請見[建立動態表單](#creating-dynamic-forms)。                              |

正如表單控制項實例讓你能控制單一輸入欄位，表單群組實例會追蹤一組表單控制項實例的表單狀態（例如一個表單）。
在建立表單群組時，群組實例中的每個控制項都以名稱追蹤。
下列範例示範如何在單一群組中管理多個表單控制項實例。

產生一個 `ProfileEditor` 元件，並從 `@angular/forms` 套件匯入 `FormGroup` 與 `FormControl` 類別。

```shell
ng generate component ProfileEditor
```

<docs-code header="profile-editor.component.ts (imports)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="imports"/>

若要為這個元件加入表單群組，請採取下列步驟。

1. 建立一個 `FormGroup` 實例。
1. 將 `FormGroup` 模型與 view 建立關聯。
1. 儲存表單資料。

<docs-workflow>

<docs-step title="建立一個 FormGroup 實例">
在元件類別中建立一個名為 `profileForm` 的屬性，並把該屬性設為一個新的表單群組實例。若要初始化表單群組，請為建構子提供一個物件，其具名鍵對應到各自的控制項。

對於個人資料表單，加入兩個名為 `firstName` 與 `lastName` 的表單控制項實例

<docs-code header="profile-editor.component.ts (form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="formgroup"/>

個別的表單控制項現在被收集在一個群組之中。`FormGroup` 實例以一個物件的形式提供它的模型值，該物件是從群組中每個控制項的值歸納而來。表單群組實例與表單控制項實例具有相同的屬性（例如 `value` 與 `untouched`）與方法（例如 `setValue()`）。
</docs-step>

<docs-step title="將 FormGroup 模型與 view 建立關聯">
表單群組會追蹤其每個控制項的狀態與變更，因此如果其中一個控制項變更，父控制項也會發出新的狀態或值變更。群組的模型由它的成員維持。在你定義模型之後，必須更新範本，讓模型反映在 view 中。

<docs-code header="profile-editor.component.html (template form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="formgroup"/>

正如表單群組包含一組控制項，_profileForm_ `FormGroup` 透過 `FormGroup` 指令繫結到 `form` 元素，在模型與包含輸入的表單之間建立一個溝通層。`FormControlName` 指令提供的 `formControlName` 輸入，將每個個別輸入繫結到 `FormGroup` 中定義的表單控制項。表單控制項與它們各自的元素溝通。它們也會把變更傳達給表單群組實例，該實例提供模型值的真相來源。
</docs-step>

<docs-step title="儲存表單資料">
`ProfileEditor` 元件接受使用者的輸入，但在真實情境中，你會想擷取表單值，讓它能在元件之外進一步處理。`FormGroup` 指令監聽 `form` 元素發出的 `submit` 事件，並發出一個 `ngSubmit` 事件，你可以把它繫結到一個回呼函式。在 `form` 標籤上加入一個 `ngSubmit` 事件監聽器，搭配 `onSubmit()` 回呼方法。

<docs-code header="profile-editor.component.html (submit event)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="ng-submit"/>

`ProfileEditor` 元件中的 `onSubmit()` 方法擷取 `profileForm` 的目前值。使用 `output()` 讓表單保持封裝，並在元件之外提供表單值。下列範例使用 `console.warn` 把訊息記錄到瀏覽器主控台。

<docs-code header="profile-editor.component.ts (submit method)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="on-submit"/>

`submit` 事件由 `form` 標籤使用內建的 DOM 事件發出。你透過點選一個 `submit` 類型的按鈕來觸發這個事件。這讓使用者能按下 **Enter** 鍵，送出已完成的表單。

使用一個 `button` 元素，在表單底部加入一個按鈕來觸發表單送出。

<docs-code header="profile-editor.component.html (submit button)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="submit-button"/>

前面片段中的按鈕還附帶了一個 `disabled` 繫結，在 `profileForm` 無效時停用該按鈕。你目前尚未執行任何驗證，因此按鈕永遠處於啟用狀態。基本的表單驗證在[驗證表單輸入](#validating-form-input)一節中介紹。
</docs-step>

<docs-step title="顯示元件 {#display-the-component-form-group}">
若要顯示包含該表單的 `ProfileEditor` 元件，請把它加入一個元件範本。

<docs-code header="app.component.html (profile editor)" path="adev/src/content/examples/reactive-forms/src/app/app.component.1.html" region="app-profile-editor"/>

`ProfileEditor` 讓你能在表單群組實例中，管理 `firstName` 與 `lastName` 控制項的表單控制項實例。
</docs-step>
</docs-workflow>

### 建立巢狀表單群組 {#creating-nested-form-groups}

表單群組可以接受個別表單控制項實例與其他表單群組實例作為子項。
這讓組合複雜的表單模型更容易維護，也更容易在邏輯上分組。

在建置複雜表單時，把不同區域的資訊拆成較小的區段會更容易管理。
使用巢狀表單群組實例，讓你能把大型表單群組拆成更小、更易管理的群組。

若要建立更複雜的表單，請採取下列步驟。

1. 建立一個巢狀群組。
1. 在範本中將巢狀表單分組。

某些類型的資訊自然會落入同一組。
姓名與地址就是這類巢狀群組的典型範例，並在下列範例中使用。

<docs-workflow>
<docs-step title="建立一個巢狀群組">
若要在 `profileForm` 中建立巢狀群組，請為表單群組實例加入一個巢狀的 `address` 元素。

<docs-code header="profile-editor.component.ts (nested form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="nested-formgroup"/>

在這個範例中，`address group` 把目前的 `firstName` 與 `lastName` 控制項，與新的 `street`、`city`、`state` 與 `zip` 控制項結合起來。即使表單群組中的 `address` 元素是整體 `profileForm` 元素的一個子項，值與狀態變更的規則同樣適用。巢狀表單群組的狀態與值變更會傳播到父表單群組，讓整體模型保持一致。
</docs-step>

<docs-step title="在範本中將巢狀表單分組">
在元件類別中更新模型之後，更新範本，把表單群組實例與它的輸入元素連接起來。把包含 `street`、`city`、`state` 與 `zip` 欄位的 `address` 表單群組，加入 `ProfileEditor` 範本。

<docs-code header="profile-editor.component.html (template nested form group)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="formgroupname"/>

`ProfileEditor` 表單顯示為一個群組，但模型被進一步拆解，以呈現邏輯分組區域。

使用 `value` 屬性與 `JsonPipe`，在元件範本中顯示表單群組實例的值。
</docs-step>
</docs-workflow>

### 更新資料模型的部分內容

當更新一個包含多個控制項的表單群組實例的值時，你可能只想更新模型的一部分。
本節介紹如何更新表單控制項資料模型的特定部分。

有兩種方法可以更新模型值：

| 方法        | 說明                                                                                                                                                               |
| :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setValue()`   | 為個別控制項設定新值。`setValue()` 方法嚴格遵守表單群組的結構，並取代控制項的整個值。 |
| `patchValue()` | 取代物件中已在表單模型裡變更的任何已定義屬性。                                                                                     |

`setValue()` 方法的嚴格檢查有助於在複雜表單中抓出巢狀錯誤，而 `patchValue()` 則會在這些錯誤上無聲地失敗。

在 `ProfileEditorComponent` 中，使用 `updateProfile` 方法搭配下列範例，更新使用者的名字與街道地址。

<docs-code header="profile-editor.component.ts (patch value)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.ts" region="patch-value"/>

加入一個按鈕到範本中，模擬依需求更新使用者個人資料。

<docs-code header="profile-editor.component.html (update value)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.1.html" region="patch-value"/>

當使用者點選按鈕時，`profileForm` 模型會以 `firstName` 與 `street` 的新值更新。請注意，`street` 是在 `address` 屬性內的一個物件中提供的。
這是必要的，因為 `patchValue()` 方法會依據模型結構套用更新。
`patchValue()` 只更新表單模型所定義的屬性。

## 使用 FormBuilder 服務產生控制項

在處理多個表單時，手動建立表單控制項實例可能會變得繁瑣重複。
`FormBuilder` 服務提供產生控制項的便利方法。

採取下列步驟來利用這個服務。

1. 匯入 `FormBuilder` 類別。
1. 注入 `FormBuilder` 服務。
1. 產生表單內容。

下列範例示範如何重構 `ProfileEditor` 元件，使用表單建置器服務來建立表單控制項與表單群組實例。

<docs-workflow>
<docs-step title="匯入 FormBuilder 類別">
從 `@angular/forms` 套件匯入 `FormBuilder` 類別。

<docs-code header="profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-builder-imports"/>

</docs-step>

<docs-step title="注入 FormBuilder 服務">
`FormBuilder` 服務是來自反應式表單模組的可注入 provider。使用 `inject()` 函式在你的元件中注入這個相依性。

<docs-code header="profile-editor.component.ts (property init)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="inject-form-builder"/>

</docs-step>
<docs-step title="產生表單控制項">
`FormBuilder` 服務有四個方法：`control()`、`group()`、`record()` 與 `array()`。這些是在元件類別中產生實例的工廠方法，包括表單控制項、表單群組、表單記錄與表單陣列。使用 `group` 方法建立 `profileForm` 控制項。

<docs-code header="profile-editor.component.ts (form builder)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-builder"/>

在前面的範例中，你使用 `group()` 方法搭配同一個物件來定義模型中的屬性。每個控制項名稱的值，都是一個陣列，其第一個項目是初始值。

TIP: 你可以只用初始值定義控制項，但如果你的控制項需要同步或非同步驗證，請把同步與非同步驗證器分別作為陣列的第二與第三個項目加入。將使用表單建置器與手動建立實例兩者做比較。
</docs-step>

</docs-workflow>

## 驗證表單輸入 {#validating-form-input}

_表單驗證_用來確保使用者輸入完整且正確。
本節介紹如何為表單控制項加入單一驗證器，並顯示整體表單狀態。
表單驗證在[表單驗證](guide/forms/form-validation)指南中有更完整的介紹。

採取下列步驟來加入表單驗證。

1. 在你的表單元件中匯入一個驗證器函式。
1. 把驗證器加入表單中的欄位。
1. 加入處理驗證狀態的邏輯。

最常見的驗證是把欄位設為必填。
下列範例示範如何為 `firstName` 控制項加入必填驗證，並顯示驗證結果。

<docs-workflow>
<docs-step title="匯入驗證器函式">
反應式表單包含一組適用於常見使用情境的驗證器函式。這些函式接收一個待驗證的控制項，並依據驗證檢查回傳一個錯誤物件或 null 值。

從 `@angular/forms` 套件匯入 `Validators` 類別。

<docs-code header="profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="validator-imports"/>
</docs-step>

<docs-step title="把欄位設為必填">
在 `ProfileEditor` 元件中，把 `Validators.required` 靜態方法作為陣列的第二個項目，加入 `firstName` 控制項。

<docs-code header="profile-editor.component.ts (required validator)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="required-validator"/>
</docs-step>

<docs-step title="顯示表單狀態">
當你把必填欄位加入表單控制項時，它的初始狀態是無效的。這個無效狀態會傳播到父表單群組元素，使其狀態也變成無效。透過表單群組實例的 `status` 屬性，存取它的目前狀態。

使用插值顯示 `profileForm` 的目前狀態。

<docs-code header="profile-editor.component.html (display status)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="display-status"/>

**Submit** 按鈕被停用，因為 `profileForm` 由於必填的 `firstName` 表單控制項而無效。在你填寫 `firstName` 輸入後，表單變成有效，**Submit** 按鈕隨即啟用。

若要進一步了解表單驗證，請造訪[表單驗證](guide/forms/form-validation)指南。
</docs-step>
</docs-workflow>

## 建立動態表單 {#creating-dynamic-forms}

`FormArray` 是 `FormGroup` 的替代方案，用來管理任意數量的未命名控制項。
如同表單群組實例，你可以動態地在表單陣列實例中插入與移除控制項，而且表單陣列實例的值與驗證狀態是從它的子控制項計算而來。
不過，你不需要為每個控制項以名稱定義鍵，因此如果你事先不知道子值的數量，這是個很好的選項。

若要定義動態表單，請採取下列步驟。

1. 匯入 `FormArray` 類別。
1. 定義一個 `FormArray` 控制項。
1. 以 getter 方法存取 `FormArray` 控制項。
1. 在範本中顯示表單陣列。

下列範例示範如何在 `ProfileEditor` 中管理一個 _aliases_ 陣列。

<docs-workflow>
<docs-step title="匯入 `FormArray` 類別">
從 `@angular/forms` 匯入 `FormArray` 類別，用於型別資訊。`FormBuilder` 服務已準備好建立 `FormArray` 實例。

<docs-code header="profile-editor.component.ts (import)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.2.ts" region="form-array-imports"/>
</docs-step>

<docs-step title="定義一個 `FormArray` 控制項">
你可以把任意數量的控制項（從零到多個）定義在一個陣列中，來初始化表單陣列。為 `profileForm` 的表單群組實例加入一個 `aliases` 屬性，來定義表單陣列。

使用 `FormBuilder.array()` 方法定義陣列，並使用 `FormBuilder.control()` 方法，以一個初始控制項填入陣列。

<docs-code header="profile-editor.component.ts (aliases form array)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="aliases"/>

表單群組實例中的 aliases 控制項現在被填入單一控制項，直到有更多控制項被動態加入為止。
</docs-step>

<docs-step title="存取 `FormArray` 控制項">
與重複使用 `profileForm.get()` 方法取得每個實例相比，getter 提供了對表單陣列實例中 aliases 的存取。表單陣列實例代表陣列中未定數量的控制項。透過 getter 存取控制項很方便，而且這個做法很容易對其他控制項重複套用。 <br />

使用 getter 語法建立一個 `aliases` 類別屬性，從父表單群組擷取 alias 的表單陣列控制項。

<docs-code header="profile-editor.component.ts (aliases getter)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="aliases-getter"/>

由於回傳的控制項型別是 `AbstractControl`，你需要提供明確的型別，才能存取表單陣列實例的方法語法。定義一個方法，將 alias 控制項動態插入 alias 的表單陣列。`FormArray.push()` 方法把控制項作為新項目插入陣列，你也可以把一組控制項陣列傳給 FormArray.push()，一次註冊多個控制項。

<docs-code header="profile-editor.component.ts (add alias)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.ts" region="add-alias"/>

在範本中，每個控制項都顯示為個別的輸入欄位。

</docs-step>

<docs-step title="在範本中顯示表單陣列">

若要把 aliases 從你的表單模型附著上來，你必須把它加入範本。與 `FormGroupName` 提供的 `formGroupName` 輸入相似，`formArrayName` 透過 `FormArrayName`，將表單陣列實例的溝通繫結到範本。

在關閉 `formGroupName` 元素的 `<div>` 之後，加入下列範本 HTML。

<docs-code header="profile-editor.component.html (aliases form array template)" path="adev/src/content/examples/reactive-forms/src/app/profile-editor/profile-editor.component.html" region="formarrayname"/>

`@for` 區塊會迭代 aliases 表單陣列實例所提供的每個表單控制項實例。由於表單陣列元素未命名，你把索引指派給 `i` 變數，並把它傳給每個控制項，將它繫結到 `formControlName` 輸入。

每當加入新的 alias 實例時，新的表單陣列實例就會依索引取得它的控制項。這讓你能在計算根控制項的狀態與值時，追蹤每個個別控制項。

NOTE: 在 zoneless 應用程式中，變更反應式表單模型（例如呼叫 `FormArray.push()`）不會自動排程元件的變更偵測。如果你的範本依賴 `aliases.controls` 這類結構性的模型變更，請確保元件通知 Angular 執行變更偵測，例如把 forms observable 橋接到 `ChangeDetectorRef.markForCheck()`：

```ts
import {ChangeDetectorRef, Component, inject} from '@angular/core';
import {takeUntilDestroyed} from '@angular/core/rxjs-interop';

@Component({/* ... */})
export class ProfileEditor {
  private readonly cdr = inject(ChangeDetectorRef);

constructor() {
    this.profileForm.valueChanges
      .pipe(takeUntilDestroyed())
      .subscribe(() => this.cdr.markForCheck());
  }
}
```

</docs-step>

### 對頂層表單陣列使用 `FormArrayDirective`

你可以使用 `FormArrayDirective`，把 `FormArray` 直接繫結到 `<form>` 元素。
這在表單不使用頂層 `FormGroup`、而陣列本身就代表完整表單模型時很有用。

```typescript
import {Component} from '@angular/core';
import {FormArray, FormControl, ReactiveFormsModule} from '@angular/forms';

@Component({
  selector: 'form-array-example',
  imports: [ReactiveFormsModule],
  template: `
    <form [formArray]="form">
      @for (control of form.controls; track $index) {
        <input [formControlName]="$index" />
      }
    </form>
  `,
})
export class FormArrayExampleComponent {
  controls = [new FormControl('fish'), new FormControl('cat'), new FormControl('dog')];

form = new FormArray(this.controls);
}
```

<docs-step title="加入一個 alias">

一開始，表單包含一個 `Alias` 欄位。若要加入另一個欄位，點選 **Add Alias** 按鈕。你也可以驗證範本底部 `Form Value` 所顯示的表單模型回報的 aliases 陣列。你不必為每個 alias 使用一個表單控制項實例，而是可以組合另一個帶有額外欄位的表單群組實例。為每個項目定義控制項的流程是相同的。
</docs-step>

</docs-workflow>

## 統一的控制項狀態變更事件 {#unified-control-state-change-events}

所有表單控制項都透過 `AbstractControl` 上的 `events` observable（`FormControl`、`FormGroup`、`FormArray` 與 `FormRecord`），公開單一統一的**控制項狀態變更事件**串流。
這個統一串流讓你能對**值**、**狀態**、**pristine**、**touched** 與 **reset** 狀態變更做出反應，也能對 **submit** 等**表單層級動作**做出反應，讓你用單一訂閱處理所有更新，而不必串接多個 observable。

### 事件類型

`events` 發出的每個項目都是特定事件類別的實例：

- **`ValueChangeEvent`** — 當控制項的**值**變更時。
- **`StatusChangeEvent`** — 當控制項的**驗證狀態**更新為 `FormControlStatus` 值之一時（`VALID`、`INVALID`、`PENDING` 或 `DISABLED`）。
- **`PristineChangeEvent`** — 當控制項的 **pristine/dirty** 狀態變更時。
- **`TouchedChangeEvent`** — 當控制項的 **touched/untouched** 狀態變更時。
- **`FormResetEvent`** — 當控制項或表單被重設時，無論是透過 `reset()` API 或原生動作。
- **`FormSubmittedEvent`** — 當表單被送出時。

所有事件類別都繼承 `ControlEvent`，並包含一個 `source` 參考，指向引發變更的 `AbstractControl`，這在大表單中很有用。

```ts
import {Component} from '@angular/core';
import {
  FormControl,
  ValueChangeEvent,
  StatusChangeEvent,
  PristineChangeEvent,
  TouchedChangeEvent,
  FormResetEvent,
  FormSubmittedEvent,
  ReactiveFormsModule,
  FormGroup,
} from '@angular/forms';

@Component(/* ... */)
export class UnifiedEventsBasicComponent {
  form = new FormGroup({
    username: new FormControl(''),
  });

constructor() {
    this.form.events.subscribe((e) => {
      if (e instanceof ValueChangeEvent) {
        console.log('Value changed to: ', e.value);
      }

if (e instanceof StatusChangeEvent) {
        console.log('Status changed to: ', e.status);
      }

if (e instanceof PristineChangeEvent) {
        console.log('Pristine status changed to: ', e.pristine);
      }

if (e instanceof TouchedChangeEvent) {
        console.log('Touched status changed to: ', e.touched);
      }

if (e instanceof FormResetEvent) {
        console.log('Form was reset');
      }

if (e instanceof FormSubmittedEvent) {
        console.log('Form was submitted');
      }
    });
  }
}
```

### 篩選特定事件

當你只需要事件類型的子集時，優先使用 RxJS 運算子。

```ts
import {filter} from 'rxjs/operators';
import {StatusChangeEvent} from '@angular/forms';

control.events
  .pipe(filter((e) => e instanceof StatusChangeEvent))
  .subscribe((e) => console.log('Status:', e.status));
```

### 從多個訂閱統一

**之前**

```ts
import {combineLatest} from 'rxjs';

combineLatest([control.valueChanges, control.statusChanges]).subscribe(([value, status]) => {
  /* ... */
});
```

**之後**

```ts
control.events.subscribe((e) => {
  // Handle ValueChangeEvent, StatusChangeEvent, etc.
});
```

NOTE: 在值變更時，發出（emit）發生在此控制項的值被更新之後。父控制項的值（例如此 FormControl 是 FormGroup 的一部分時）會稍後才更新，因此從此事件的回呼中存取父控制項的值（使用 `value` 屬性），可能會取得尚未更新的值。改為訂閱父控制項的 `events`。

## 管理表單控制項狀態 {#managing-form-control-state}

反應式表單透過 **touched/untouched** 與 **pristine/dirty** 追蹤控制項狀態。Angular 在 DOM 互動期間自動更新這些狀態，但你也可以用程式化方式管理它們。

**[`markAsTouched`](api/forms/FormControl#markAsTouched)** — 將控制項或表單標記為 touched，適用於 focus 與 blur 這類不改變值的事件。預設會傳播到父控制項。

```ts
// Show validation errors after user leaves a field
onEmailBlur() {
  const email = this.form.get('email');
  email.markAsTouched();
}
```

**[`markAsUntouched`](api/forms/FormControl#markAsUntouched)** — 將控制項或表單標記為 untouched。會連帶影響所有子控制項，並重新計算所有父控制項的 touched 狀態。

```ts
// Reset form state after successful submission
onSubmitSuccess() {
  this.form.markAsUntouched();
  this.form.markAsPristine();
}
```

**[`markAsDirty`](api/forms/FormControl#markAsDirty)** — 將控制項或表單標記為 dirty，意思是值已被變更。預設會傳播到父控制項。

```ts
// Mark programmatically changed values as modified
autofillAddress() {
  const previousAddress = getAddress();
  this.form.patchValue(previousAddress, { emitEvent: false });
  this.form.markAsDirty();
}
```

**[`markAsPristine`](api/forms/FormControl#markAsPristine)** — 將控制項或表單標記為 pristine。會把所有子控制項標記為 pristine，並重新計算所有父控制項的 pristine 狀態。

```ts
// Reset pristine state after saving to track new changes
saveForm() {
  this.api.save(this.form.value).subscribe(() => {
    this.form.markAsPristine();
  });
}
```

**[`markAllAsDirty`](api/forms/FormControl#markAllAsDirty)** — 將控制項或表單以及它所有的後代控制項標記為 dirty。

```ts
// Mark imported data as dirty
loadData(data: FormData) {
  this.form.patchValue(data);
  this.form.markAllAsDirty();
}
```

**[`markAllAsTouched`](api/forms/FormControl#markAllAsTouched)** — 將控制項或表單以及它所有的後代控制項標記為 touched。適合用來在整個表單顯示驗證錯誤。

```ts
// Show all validation errors before submission
onSubmit() {
  if (this.form.invalid) {
    this.form.markAllAsTouched();
    return;
  }
  this.saveForm();
}
```

## 控制事件發送與傳播

當以程式化方式更新表單控制項時，你可以精確控制變更如何在表單階層中傳播，以及是否發出事件。

### 了解事件發送 {#understanding-event-emission}

預設 `emitEvent: true` 時，控制項的任何變更都會透過 `valueChanges` 與 `statusChanges` observable 發出事件。設定 `emitEvent: false` 會抑制這些發出，這在以程式方式設定值而不想觸發像自動儲存這樣的反應式行為、避免控制項之間的循環更新，或執行批次更新（事件應該只在最後發出一次）時很有用。

```ts
@Component({/* ... */})
export class BlogPostEditor {
  postForm = new FormGroup({
    title: new FormControl(''),
    content: new FormControl(''),
  });

constructor() {
    // Auto-save draft every time user types
    this.postForm.valueChanges.subscribe((formValue) => {
      this.autosaveDraft(formValue);
    });
  }

loadExistingDraft(savedDraft: {title: string; content: string}) {
    // Restore draft without triggering auto-save
    this.postForm.setValue(savedDraft, {emitEvent: false});
  }
}
```

### 了解傳播控制

預設 `onlySelf: false` 時，更新會連帶影響父控制項，重新計算它們的值與驗證狀態。設定 `onlySelf: true` 會把更新隔離在目前控制項，不通知父控制項。這在批次操作時很有用，你可以手動只觸發一次父項更新。

```ts
updatePostalCodeValidator(country: string) {
  const postal = this.addressForm.get('postalCode');

const validators = country === 'US'
    ? [Validators.maxLength(5)]
    : [Validators.maxLength(7)];

postal.setValidators(validators);
  postal.updateValueAndValidity({ onlySelf: true, emitEvent: false });
}
```

HELPFUL: 若要在執行階段動態管理驗證器，請見表單驗證指南中的[在反應式表單中動態管理驗證器](guide/forms/form-validation#managing-validators-dynamically-in-reactive-forms)一節。

## 用來縮小表單控制項型別的工具函式 {#utility-functions-for-narrowing-form-control-types}

Angular 提供四個工具函式，幫助判斷 `AbstractControl` 的具體型別。這些函式扮演**型別守衛**的角色，當它們回傳 `true` 時會縮小控制項型別，讓你能在同一個區塊中安全地存取子型別專屬的屬性。

這些輔助函式在**自訂驗證器**中特別有用，因為函式簽名接收的是一個 `AbstractControl`，但邏輯是針對特定種類的控制項。

```ts
import {AbstractControl, isFormArray} from '@angular/forms';

export function positiveValues(control: AbstractControl) {
  if (!isFormArray(control)) {
    return null; // Not a FormArray: validator is not applicable.
  }

// Safe to access FormArray-specific API after narrowing.
  const hasNegative = control.controls.some((c) => c.value < 0);
  return hasNegative ? {positiveValues: true} : null;
}
```

## 反應式表單 API 總覽

下表列出用來建立與管理反應式表單控制項的基礎類別與服務。
完整的語法詳情請見 [Forms 套件](api#angular_forms 'API 參考文件') 的 API 參考文件。

### 類別

### 指令

自 Angular 14 起，反應式表單預設為嚴格型別化。

作為本指南的背景，你應該已經熟悉 [Angular 反應式表單](guide/forms/reactive-forms)。

## 型別化表單概覽

<docs-video src="https://www.youtube.com/embed/L-odCf4MfJc" title="Angular 中的型別化表單" />

使用 Angular 反應式表單時，你會明確指定一個_表單模型_。舉一個簡單的例子，想想這個基本的使用者登入表單：

```ts
const login = new FormGroup({
  email: new FormControl(''),
  password: new FormControl(''),
});
```

Angular 提供許多與這個 `FormGroup` 互動的 API。例如，你可以呼叫 `login.value`、`login.controls`、`login.patchValue` 等。（如需完整的 API 參考，請參閱 [API 文件](api/forms/FormGroup)。）

在先前的 Angular 版本中，這些 API 大多在型別的某處包含 `any`，與控制項結構或值本身互動時並非型別安全的。例如：你可以撰寫以下無效的程式碼：

```ts
const emailDomain = login.value.email.domain;
```

使用嚴格型別化的反應式表單時，上述程式碼無法編譯，因為 `email` 上沒有 `domain` 屬性。

除了增加安全性之外，型別還帶來了其他各種改進，例如 IDE 中更好的自動完成，以及明確指定表單結構的方式。

這些改進目前只適用於_反應式_表單（不適用於[_範本驅動_表單](guide/forms/template-driven-forms)）。

## 非型別化表單

非型別化表單仍然受支援，並會繼續像以前一樣運作。若要使用它們，你必須從 `@angular/forms` 匯入 `Untyped` 符號：

```ts
const login = new UntypedFormGroup({
  email: new UntypedFormControl(''),
  password: new UntypedFormControl(''),
});
```

每個 `Untyped` 符號都與先前 Angular 版本中的語意完全相同。移除 `Untyped` 前置詞後，你可以逐步啟用型別。

## `FormControl`：快速入門 {#formcontrol-getting-started}

最簡單的表單由單一控制項組成：

```ts
const email = new FormControl('angularrox@gmail.com');
```

這個控制項會自動被推斷為型別 `FormControl<string|null>`。TypeScript 會在 [`FormControl` API](api/forms/FormControl) 中全面強制這個型別，例如 `email.value`、`email.valueChanges` 與 `email.setValue(...)`。

### 可為 null 的特性

你可能會想：為什麼這個控制項的型別包含 `null`？這是因為控制項隨時可能透過呼叫 reset 而變成 `null`：

```ts
const email = new FormControl('angularrox@gmail.com');
email.reset();
console.log(email.value); // null
```

TypeScript 會強制你隨時處理控制項已變成 `null` 的可能性。如果你想讓這個控制項不可為 null，可以使用 `nonNullable` 選項。這會使控制項重設為其初始值，而不是 `null`：

```ts
const email = new FormControl('angularrox@gmail.com', {nonNullable: true});
email.reset();
console.log(email.value); // angularrox@gmail.com
```

再次強調，這個選項會影響呼叫 `.reset()` 時表單的執行階段行為，變更時應謹慎。

### 指定明確型別

你可以指定型別，而不是依賴推斷。想想一個初始化為 `null` 的控制項。由於初始值是 `null`，TypeScript 會推斷出 `FormControl<null>`，這比我們想要的範圍更窄。

```ts
const email = new FormControl(null);
email.setValue('angularrox@gmail.com'); // Error!
```

若要避免這種情況，我們明確地將型別指定為 `string|null`：

```ts
const email = new FormControl<string | null>(null);
email.setValue('angularrox@gmail.com');
```

## `FormArray`：動態、同質的集合 {#formarray-dynamic-homogenous-collections}

`FormArray` 包含一份開放式的控制項清單。型別參數對應到每個內部控制項的型別：

```ts
const names = new FormArray([new FormControl('Alex')]);
names.push(new FormControl('Jess'));
```

當你需要一次加入多個項目時，將控制項陣列傳給 `aliases.push()`。

```ts
const aliases = new FormArray([new FormControl('ng')]);
aliases.push([new FormControl('ngDev'), new FormControl('ngAwesome')]);
```

這個 `FormArray` 的內部控制項型別會是 `FormControl<string|null>`。

如果你想在陣列中放入多種不同的元素型別，你必須使用 `UntypedFormArray`，因為 TypeScript 無法推斷哪個位置會出現哪種元素型別。

`FormArray` 也提供 `clear()` 方法，用來移除它包含的所有控制項：

```ts
const aliases = new FormArray([new FormControl('ngDev'), new FormControl('ngAwesome')]);
aliases.clear();
console.log(aliases.length); // 0
```

## `FormGroup` 與 `FormRecord` {#formgroup-and-formrecord}

Angular 為具有列舉鍵集合的表單提供 `FormGroup` 型別，並為開放式或動態群組提供稱為 `FormRecord` 的型別。

### 部分值

再想想一個登入表單：

```ts
const login = new FormGroup({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});
```

在任何 `FormGroup` 上，都可以[停用控制項](api/forms/FormGroup)。任何停用的控制項都不會出現在群組的值中。

因此，`login.value` 的型別是 `Partial<{email: string, password: string}>`。這個型別中的 `Partial` 表示每個成員都可能是 undefined。

更具體地說，`login.value.email` 的型別是 `string|undefined`，TypeScript 會強制你處理可能為 `undefined` 的值（如果你啟用了 `strictNullChecks`）。

如果你想存取_包含_停用控制項的值，進而繞過可能為 `undefined` 的欄位，你可以使用 `login.getRawValue()`。

### 選擇性控制項與動態群組

有些表單的控制項可能存在、也可能不存在，可以在執行階段加入與移除。你可以使用_選擇性欄位_來表示這些控制項：

```ts
interface LoginForm {
  email: FormControl<string>;
  password?: FormControl<string>;
}

const login = new FormGroup<LoginForm>({
  email: new FormControl('', {nonNullable: true}),
  password: new FormControl('', {nonNullable: true}),
});

在這個表單中，我們明確指定型別，這使我們能讓 `password` 控制項成為選擇性的。TypeScript 會強制規定只有選擇性控制項可以被加入或移除。

### `FormRecord`

有些 `FormGroup` 的用法不符合上述模式，因為鍵無法事先知道。`FormRecord` 類別正是為這種情況設計的：

```ts
const addresses = new FormRecord<FormControl<string | null>>({});
addresses.addControl('Andrew', new FormControl('2340 Folsom St'));
```

任何型別為 `string|null` 的控制項都可以加入這個 `FormRecord`。

如果你需要一個既是動態（開放式）、又是異質（控制項為不同型別）的 `FormGroup`，就無法獲得更好的型別安全性，你應該使用 `UntypedFormGroup`。

`FormRecord` 也可以使用 `FormBuilder` 來建立：

```ts
const addresses = fb.record({'Andrew': '2340 Folsom St'});
```

## `FormBuilder` 與 `NonNullableFormBuilder` {#formbuilder-and-nonnullableformbuilder}

`FormBuilder` 類別也已升級，支援新的型別，方式與上述範例相同。

此外，還有一個額外的建置器可供使用：`NonNullableFormBuilder`。這個型別是對每個控制項指定 `{nonNullable: true}` 的簡寫，可以從大型不可為 null 的表單中消除大量重複的樣板程式碼。你可以使用 `FormBuilder` 上的 `nonNullable` 屬性來存取它：

```ts
const fb = new FormBuilder();
const login = fb.nonNullable.group({
  email: '',
  password: '',
});
```

在上述範例中，兩個內部控制項都會是不可為 null 的（也就是會設定 `nonNullable`）。

你也可以使用名稱 `NonNullableFormBuilder` 來注入它。
# 建立範本驅動表單

本教學將示範如何建立範本驅動表單。表單中的控制元素綁定到具有輸入驗證的資料屬性。輸入驗證有助於維護資料完整性與樣式，進而改善使用者體驗。

範本驅動表單使用[雙向資料綁定](guide/templates/two-way-binding)，在範本發生變更時更新元件中的資料模型，反之亦然。
Angular 支援兩種互動式表單的設計方式。範本驅動表單讓你在 Angular 範本中使用表單專用的指令；反應式表單則提供以模型驅動的方式來建立表單。

範本驅動表單非常適合小型或簡單的表單，反應式表單則更具擴展性，適合複雜的表單。如需比較這兩種方式，請參閱[選擇方式](guide/forms#choosing-an-approach)
你幾乎可以使用 Angular 範本建立任何種類的表單——登入表單、聯絡表單，以及幾乎任何業務表單。
你可以自由安排控制項的版面，並將它們綁定到物件模型中的資料。
你可以指定驗證規則並顯示驗證錯誤、依條件允許特定控制項輸入、觸發內建的視覺回饋，還有更多功能。

## 學習目標

本教學將教你如何完成以下事項：

- 使用元件與範本建立 Angular 表單
- 使用 `ngModel` 建立雙向資料綁定，以讀取與寫入輸入控制項的值
- 使用追蹤控制項狀態的特殊 CSS 類別提供視覺回饋
- 向使用者顯示驗證錯誤，並根據表單狀態依條件允許表單控制項輸入
- 使用[範本參照變數](guide/templates/variables#template-reference-variables)在 HTML 元素之間共用資訊

## 建立範本驅動表單

範本驅動表單依賴 `FormsModule` 中定義的指令。

| 指令           | 詳細說明                                                                                                                                                                                                                                                                        |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NgModel`      | 協調附加表單元素的值變更與資料模型的變更，讓你能以輸入驗證與錯誤處理來回應使用者輸入。                                                                                                                                                                                          |
| `NgForm`       | 建立頂層 `FormGroup` 執行個體，並將它綁定到 `<form>` 元素，以追蹤彙總的表單值與驗證狀態。只要你匯入 `FormsModule`，這個指令預設就會在所有 `<form>` 標籤上啟用。你不需要加入特殊的選擇器。                                                                                  |
| `NgModelGroup` | 建立 `FormGroup` 執行個體，並將它綁定到 DOM 元素。                                                                                                                                                                                                                              |

### 步驟概覽

在本教學中，你將依照以下步驟，把範例表單綁定到資料並處理使用者輸入。

1. 建立基本表單。
   - 定義範例資料模型
   - 加入必要的基礎設施，例如 `FormsModule`
1. 使用 `ngModel` 指令與雙向資料綁定語法，將表單控制項綁定到資料屬性。
   - 檢視 `ngModel` 如何使用 CSS 類別回報控制項狀態
   - 為控制項命名，讓 `ngModel` 可以存取它們
1. 使用 `ngModel` 追蹤輸入有效性與控制項狀態。
   - 加入自訂 CSS，針對狀態提供視覺回饋
   - 顯示與隱藏驗證錯誤訊息
1. 回應原生 HTML 按鈕的點擊事件，將資料加入模型。
1. 使用表單的 [`ngSubmit`](api/forms/NgForm#ngSubmit) 輸出屬性處理表單提交。
   - 在表單有效之前停用 **Submit** 按鈕
   - 提交後，將完成的表單換成頁面上的其他內容

## 建立表單

1. 提供的範例應用程式建立了 `Actor` 類別，其中定義了表單所反映的資料模型。

<docs-code header="actor.ts" language="typescript" path="adev/src/content/examples/forms/src/app/actor.ts"/>

1. 表單的版面與詳細內容定義在 `ActorFormComponent` 類別中。

<docs-code header="actor-form.component.ts (v1)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="v1"/>

元件的 `selector` 值為 "app-actor-form"，表示你可以使用 `<app-actor-form>` 標籤，將這個表單放入父範本中。

1. 以下程式碼建立了一個新的演員執行個體，讓初始表單可以顯示一位範例演員。

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" region="Marilyn"/>

這個示範對 `model` 與 `skills` 使用假資料。
   在真實應用程式中，你會注入資料服務來取得與儲存真實資料，或將這些屬性公開為輸入與輸出。

1. 元件透過匯入 `FormsModule` 模組來啟用表單功能。

<docs-code language="typescript" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" language="typescript" region="imports"/>

1. 表單顯示在根元件範本所定義的應用程式版面中。

<docs-code header="app.component.html" language="html" path="adev/src/content/examples/forms/src/app/app.component.html"/>

初始範本定義了一個表單的版面，其中包含兩個表單群組與一個提交按鈕。
   這兩個表單群組對應到 Actor 資料模型的兩個屬性：name 與 studio。
   每個群組都有一個標籤，以及一個供使用者輸入的方框。
   - **Name** `<input>` 控制元素具有 HTML5 的 `required` 屬性
   - **Studio** `<input>` 控制元素則沒有，因為 `studio` 是選擇性的

**Submit** 按鈕上有一些用於樣式的類別。
   在這個階段，表單版面完全是純 HTML5，沒有任何綁定或指令。

1. 範例表單使用 [Twitter Bootstrap](https://getbootstrap.com/css) 的一些樣式類別：`container`、`form-group`、`form-control` 與 `btn`。
   若要使用這些樣式，應用程式的樣式表會匯入該程式庫。

<docs-code header="styles.css" path="adev/src/content/examples/forms/src/styles.1.css"/>

1. 表單要求演員的技能必須從 `ActorFormComponent` 內部維護的預先定義 `skills` 清單中選擇。
   Angular 的 `@for` 迴圈會逐一走訪資料值，填入 `<select>` 元素。

<docs-code header="actor-form.component.html (skills)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="skills"/>

如果你現在執行應用程式，你會在選取控制項中看到技能清單。
輸入元素尚未綁定到資料值或事件，因此它們仍然是空白的，而且沒有任何行為。

## 將輸入控制項綁定到資料屬性

下一步是使用雙向資料綁定，將輸入控制項綁定到 `Actor` 中對應的屬性，讓它們在使用者輸入時更新資料模型，也能在資料發生程式化變更時更新顯示。

`FormsModule` 中宣告的 `ngModel` 指令，讓你可以將範本驅動表單中的控制項綁定到資料模型中的屬性。
當你使用雙向資料綁定語法 `[(ngModel)]` 加入這個指令時，Angular 可以追蹤控制項的值與使用者互動，並讓檢視與模型保持同步。

1. 編輯範本檔案 `actor-form.component.html`。
1. 找到 **Name** 標籤旁的 `<input>` 標籤。
1. 加入 `ngModel` 指令，使用雙向資料綁定語法 `[(ngModel)]="..."`。

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngModelName-1"/>

HELPFUL: 這個範例在每個輸入標籤後都有一個暫時的診斷插值 `{{model.name}}`，用來顯示對應屬性的目前資料值。註解提醒你，在觀察完雙向資料綁定的運作後，要移除這些診斷行。

### 存取整體表單狀態

當你在元件中匯入 `FormsModule` 時，Angular 會自動在範本的 `<form>` 標籤上建立並附加一個 [NgForm](api/forms/NgForm) 指令（因為 `NgForm` 的選擇器 `form` 與 `<form>` 元素相符）。

若要存取 `NgForm` 與整體表單狀態，請宣告一個[範本參照變數](guide/templates/variables#template-reference-variables)。

1. 編輯範本檔案 `actor-form.component.html`。
1. 使用範本參照變數 `#actorForm` 更新 `<form>` 標籤，並如下設定它的值。

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="template-variable"/>

`actorForm` 範本變數現在是控管整個表單的 `NgForm` 指令執行個體的參照。

1. 執行應用程式。
1. 開始在 **Name** 輸入框中輸入。

當你新增與刪除字元時，你可以看到它們在資料模型中出現與消失。

顯示插值值的診斷行證明了值確實從輸入框流向模型，再流回來。

### 為控制元素命名

當你在元素上使用 `[(ngModel)]` 時，你必須為該元素定義 `name` 屬性。
Angular 會使用指定的名稱，向附加在父 `<form>` 元素上的 `NgForm` 指令註冊該元素。

範例為 `<input>` 元素加入了 `name` 屬性，並將它設為 "name"，這對演員的姓名來說很合理。
任何唯一值都可以，但使用具描述性的名稱會更有幫助。

1. 為 **Studio** 與 **Skill** 加入類似的 `[(ngModel)]` 綁定與 `name` 屬性。
1. 現在你可以移除顯示插值值的診斷訊息。
1. 若要確認雙向資料綁定對整個演員模型都有效，請在元件範本頂端加入一個新的文字綁定，使用 [`json`](api/common/JsonPipe) 管道將資料序列化為字串。

完成這些修改後，表單範本應該如下所示：

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngModel-2"/>

你會注意到：

- 每個 `<input>` 元素都有一個 `id` 屬性。
  `<label>` 元素的 `for` 屬性會使用它，將標籤與其輸入控制項對應起來。
  這是[標準的 HTML 功能](https://developer.mozilla.org/docs/Web/HTML/Element/label)。

- 每個 `<input>` 元素也都有必要的 `name` 屬性，Angular 會使用它向表單註冊控制項。

觀察完效果後，你可以刪除 `{{ model | json }}` 文字綁定。

## 追蹤表單狀態

Angular 會在表單提交後，將 `ng-submitted` 類別套用到 `form` 元素。這個類別可以用來在表單提交後變更表單的樣式。

## 追蹤控制項狀態 {#track-control-states}

將 `NgModel` 指令加入控制項，會為控制項加入描述其狀態的類別名稱。
這些類別可以用來根據控制項的狀態變更其樣式。

下表說明 Angular 根據控制項狀態套用的類別名稱。

Angular 也會在提交時將 `ng-submitted` 類別套用到 `form` 元素，但不會套用到 `form` 元素內的控制項。

你可以使用這些 CSS 類別，根據控制項的狀態定義其樣式。

### 觀察控制項狀態

若要查看框架如何加入與移除這些類別，請開啟瀏覽器的開發人員工具，檢查代表演員姓名的 `<input>` 元素。

1. 使用瀏覽器的開發人員工具，找到對應到 **Name** 輸入框的 `<input>` 元素。
   你可以看到該元素除了 "form-control" 之外，還有多個 CSS 類別。

1. 當你第一次開啟它時，這些類別表示它有一個有效的值、該值自初始化或重設後尚未變更，且控制項自初始化或重設後尚未被造訪。

```html
<input class="form-control ng-untouched ng-pristine ng-valid" />
   ```

1. 在 **Name** `<input>` 方框上執行以下操作，並觀察哪些類別出現。
   - 只看不要碰。
     這些類別表示它是未碰觸、未變更且有效的。

- 點按姓名方框內部，然後點按方框外部。
     控制項現在已被造訪，元素具有 `ng-touched` 類別，而不是 `ng-untouched` 類別。

- 在姓名末尾加上斜線。
     它現在是已碰觸且已變更的。

- 清除姓名。
     這會使值無效，因此 `ng-invalid` 類別會取代 `ng-valid` 類別。

### 為狀態建立視覺回饋

`ng-valid`/`ng-invalid` 這一對特別值得注意，因為當值無效時，你會想要送出強烈的視覺訊號。
你也會想要標示必填欄位。

你可以同時標示必填欄位與無效資料，方法是在輸入框左側加上一個彩色長條。

若要以這種方式變更外觀，請執行以下步驟。

1. 為 `ng-*` CSS 類別加入定義。
1. 將這些類別定義加入新的 `forms.css` 檔案。
1. 將新檔案加入專案，作為 `index.html` 的同層檔案：

<docs-code header="forms.css" language="css" path="adev/src/content/examples/forms/src/assets/forms.css"/>

1. 在 `index.html` 檔案中，更新 `<head>` 標籤以包含新的樣式表。

<docs-code header="index.html (styles)" path="adev/src/content/examples/forms/src/index.html" region="styles"/>

### 顯示與隱藏驗證錯誤訊息

**Name** 輸入框是必填的，清除它會讓長條變成紅色。
這表示有地方出錯了，但使用者不知道哪裡出錯，也不知道該怎麼做。
你可以透過檢查並回應控制項的狀態，提供有幫助的訊息。

**Skill** 選取方框也是必填的，但它不需要這種錯誤處理，因為選取方框本身已將選項限制在有效值內。

若要在適當時機定義並顯示錯誤訊息，請執行以下步驟。

<docs-workflow>
<docs-step title="為輸入框加入本地參照">
使用範本參照變數擴充 `input` 標籤，讓你可以從範本內存取輸入框的 Angular 控制項。在範例中，變數是 `#name="ngModel"`。

範本參照變數（`#name`）被設為 `"ngModel"`，因為那是 [`NgModel.exportAs`](api/core/Directive#exportAs) 屬性的值。這個屬性告訴 Angular 如何將參照變數連結到指令。
</docs-step>

<docs-step title="加入錯誤訊息">
加入一個包含適當錯誤訊息的 `<div>`。
</docs-step>

<docs-step title="讓錯誤訊息有條件地顯示">
將 `name` 控制項的屬性綁定到訊息 `<div>` 元素的 `hidden` 屬性，以顯示或隱藏錯誤訊息。
</docs-step>

<docs-code header="actor-form.component.html (hidden-error-msg)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="hidden-error-msg"/>

<docs-step title="為 name 加入條件式錯誤訊息">
如下列範例所示，為 `name` 輸入框加入條件式錯誤訊息。

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="name-with-error-msg"/>
</docs-step>
</docs-workflow>
在這個範例中，當控制項有效或處於 _pristine_ 狀態時，你會隱藏訊息。
Pristine 表示使用者自它在此表單中顯示以來，尚未變更該值。
如果你忽略 `pristine` 狀態，你只會在值有效時隱藏訊息。
如果你帶著一位新的空白演員或無效的演員來到這個元件，你會立刻看到錯誤訊息，在你做任何事之前就出現。

你可能希望訊息只在使用者做出無效變更時才顯示。
在控制項處於 `pristine` 狀態時隱藏訊息，就能達到這個目標。
當你在下一步驟中將新演員加入表單時，你會看到這個選擇的重要性。
## 新增一位演員

這個練習示範如何回應原生 HTML 按鈕的點擊事件，將資料加入模型。
若要讓表單使用者新增一位演員，你會加入一個 **New Actor** 按鈕來回應點擊事件。

1. 在範本中，將一個 "New Actor" `<button>` 元素放在表單底部。
1. 在元件檔案中，將建立演員的方法加入演員資料模型。

<docs-code header="actor-form.component.ts (New Actor method)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="new-actor"/>

1. 將按鈕的點擊事件綁定到建立演員的方法 `newActor()`。

<docs-code header="actor-form.component.html (New Actor button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="new-actor-button-no-reset"/>

1. 再次執行應用程式，並點按 **New Actor** 按鈕。

表單會被清除，輸入框左側的 _required_ 長條是紅色的，表示 `name` 與 `skill` 屬性無效。
   請注意錯誤訊息是隱藏的。
   這是因為表單處於 pristine 狀態；你還沒有變更任何東西。

1. 輸入姓名，再次點按 **New Actor**。

現在應用程式會顯示 `Name is required` 錯誤訊息，因為輸入框不再是 pristine 狀態。
   表單記得你在點按 **New Actor** 之前輸入過姓名。

1. 若要還原表單控制項的 pristine 狀態，請在呼叫 `newActor()` 方法後，呼叫表單的 `reset()` 方法，以命令式方式清除所有旗標。

<docs-code header="actor-form.component.html (Reset the form)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="new-actor-button-form-reset"/>

現在點按 **New Actor** 會同時重設表單與其控制項旗標。

## 使用 `ngSubmit` 提交表單

使用者應該能在填寫完這個表單後提交它。
表單底部的 **Submit** 按鈕本身沒有任何作用，但它確實會因為其類型（`type="submit"`）而觸發表單提交事件。

若要回應這個事件，請執行以下步驟。

<docs-workflow>

<docs-step title="監聽 ngOnSubmit">
將表單的 [`ngSubmit`](api/forms/NgForm#ngSubmit) 事件屬性綁定到演員表單元件的 `onSubmit()` 方法。

<docs-code header="actor-form.component.html (ngSubmit)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="ngSubmit"/>
</docs-step>

<docs-step title="綁定 disabled 屬性">
使用範本參照變數 `#actorForm` 存取包含 **Submit** 按鈕的表單，並建立事件綁定。

你會將表示表單整體有效性的表單屬性，綁定到 **Submit** 按鈕的 `disabled` 屬性。

<docs-code header="actor-form.component.html (submit-button)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="submit-button"/>
</docs-step>

<docs-step title="執行應用程式">
請注意按鈕已啟用——雖然它還沒有做任何有用的事。
</docs-step>

<docs-step title="刪除 Name 的值">
這違反了 "required" 規則，因此它會顯示錯誤訊息——同時請注意，它也會停用 **Submit** 按鈕。

你不必明確地將按鈕的啟用狀態連接到表單的有效性。
當你在增強的表單元素上定義範本參照變數，然後在按鈕控制項中參照該變數時，`FormsModule` 已自動完成這件事。
</docs-step>
</docs-workflow>

### 回應表單提交

若要顯示對表單提交的回應，你可以隱藏資料輸入區域，並在它的位置顯示其他內容。

<docs-workflow>
<docs-step title="包裝表單">
將整個表單包裝在一個 `<div>` 中，並將它的 `hidden` 屬性綁定到 `ActorFormComponent.submitted` 屬性。

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="edit-div"/>

主表單從一開始就可見，因為 `submitted` 屬性在你提交表單之前都是 false，如 `ActorFormComponent` 的這個片段所示：

<docs-code header="actor-form.component.ts (submitted)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.ts" region="submitted"/>

當你點按 **Submit** 按鈕時，`submitted` 旗標會變為 true，表單就會消失。
</docs-step>

<docs-step title="加入已提交狀態">
若要在表單處於已提交狀態時顯示其他內容，請在新的 `<div>` 包裝器下方加入以下 HTML。

<docs-code header="actor-form.component.html (excerpt)" path="adev/src/content/examples/forms/src/app/actor-form/actor-form.component.html" region="submitted"/>

這個 `<div>` 顯示一個具有插值綁定的唯讀演員，只在元件處於已提交狀態時才出現。

替代顯示內容包含一個 _Edit_ 按鈕，其點擊事件綁定到一個會清除 `submitted` 旗標的運算式。
</docs-step>

<docs-step title="測試 Edit 按鈕">
點按 *Edit* 按鈕，將顯示切換回可編輯的表單。
</docs-step>
</docs-workflow>

## 摘要

本頁討論的 Angular 表單利用以下框架功能，為資料修改、驗證等提供支援。

- Angular HTML 表單範本
- 具有 `@Component` 裝飾器的表單元件類別
- 透過綁定到 `NgForm.ngSubmit` 事件屬性來處理表單提交
- 例如 `#actorForm` 與 `#name` 等範本參照變數
- 用於雙向資料綁定的 `[(ngModel)]` 語法
- 使用 `name` 屬性進行驗證與表單元素變更追蹤
- 輸入控制項上參照變數的 `valid` 屬性，表示控制項是否有效，或是否應顯示錯誤訊息
- 透過綁定到 `NgForm` 的有效性，控制 **Submit** 按鈕的啟用狀態
- 自訂 CSS 類別，為使用者提供關於無效控制項的視覺回饋

以下是應用程式最終版本的程式碼：
# 驗證表單輸入

驗證使用者輸入的正確性與完整性，可以提升整體資料品質。
本頁說明如何從 UI 驗證使用者輸入，並顯示實用的驗證訊息，內容涵蓋反應式表單與範本驅動表單。

## 在範本驅動表單中驗證輸入 {#validating-input-in-template-driven-forms}

若要為範本驅動表單加上驗證，你要加入的驗證屬性與[原生 HTML 表單驗證](https://developer.mozilla.org/docs/Web/Guide/HTML/HTML5/Constraint_validation)所用的相同。
Angular 使用指令，將這些屬性與框架中的驗證器函式對應起來。

每當表單控制項的值變更時，Angular 就會執行驗證，並產生一份驗證錯誤清單（使狀態成為 `INVALID`），或是 `null`（使狀態成為 `VALID`）。

接著，你可以把 `ngModel` 匯出為範本區域變數，藉此檢視控制項的狀態。
下列範例將 `NgModel` 匯出為名為 `name` 的變數：

<docs-code header="actor-form-template.component.html (name)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="name-with-error-msg"/>

請注意範例所示範的下列特點。

- `<input>` 元素帶有 HTML 驗證屬性：`required` 與 `minlength`。
  它也帶有一個自訂驗證器指令 `forbiddenName`。
  詳情請見[自訂驗證器](#defining-custom-validators)一節。

- `#name="ngModel"` 將 `NgModel` 匯出為名為 `name` 的區域變數。
  `NgModel` 鏡像了其底層 `FormControl` 實例的許多屬性，因此你可以在範本中使用它來檢查 `valid`、`dirty` 等控制項狀態。
  控制項屬性的完整清單請見 [AbstractControl](api/forms/AbstractControl) API 參考文件。
  - 最外層的 `@if` 只有在 `name` 無效，且控制項處於 `dirty` 或 `touched` 狀態時，才會顯示一組巢狀訊息。

- 每個巢狀 `@if` 都可以針對某一種可能的驗證錯誤呈現自訂訊息。
    這裡有 `required`、`minlength` 與 `forbiddenName` 的訊息。

HELPFUL: 為了避免驗證器在使用者還來不及編輯表單前就顯示錯誤，你應該檢查控制項是否處於 `dirty` 或 `touched` 狀態。

- 當使用者變更受監看欄位的值時，該控制項會被標記為「dirty」
- 當使用者讓表單控制項元素失焦時，該控制項會被標記為「touched」

## 在反應式表單中驗證輸入 {#validating-input-in-reactive-forms}

在反應式表單中，真相來源是元件類別。
你不是透過範本中的屬性加入驗證器，而是直接把驗證器函式加入元件類別中的表單控制項模型。
接著，每當控制項的值變更時，Angular 就會呼叫這些函式。

### 驗證器函式

驗證器函式可以是同步的，也可以是非同步的。

| 驗證器類型     | 說明                                                                                                                                                                                                                 |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 同步驗證器  | 同步函式，接受一個控制項實例，並立即回傳一組驗證錯誤或 `null`。在實例化 `FormControl` 時，將這些函式作為第二個引數傳入。                       |
| 非同步驗證器 | 非同步函式，接受一個控制項實例，並回傳一個 Promise 或 Observable，稍後發出（emit）一組驗證錯誤或 `null`。在實例化 `FormControl` 時，將這些函式作為第三個引數傳入。 |

基於效能考量，Angular 只有在所有同步驗證器都通過時，才會執行非同步驗證器。
每個驗證器都必須先完成，錯誤才會被設定。

### 內建驗證器函式

你可以選擇[撰寫自己的驗證器函式](#defining-custom-validators)，也可以使用 Angular 的一些內建驗證器。

範本驅動表單中可作為屬性使用的同一批內建驗證器，例如 `required` 與 `minlength`，全都可以作為 `Validators` 類別的函式來使用。
內建驗證器的完整清單請見 [Validators](api/forms/Validators) API 參考文件。

若要把演員表單改成反應式表單，可以使用同一批內建驗證器——這次改以函式形式使用，如下列範例所示。

<docs-code header="actor-form-reactive.component.ts (validator functions)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" region="form-group"/>

在這個範例中，`name` 控制項設定了兩個內建驗證器——`Validators.required` 與 `Validators.minLength(4)`——以及一個自訂驗證器 `forbiddenNameValidator`。

這些驗證器全都是同步的，所以作為第二個引數傳入。
請注意，你可以把多個驗證器函式組成陣列傳入，藉此支援多個驗證器。

這個範例也加入了幾個 getter 方法。
在反應式表單中，你隨時都可以透過父群組的 `get` 方法存取任何表單控制項，但有時把 getter 定義成範本用的簡寫會更方便。

如果你再看一次 `name` 輸入欄位的範本，它與範本驅動的範例相當相似。

<docs-code header="actor-form-reactive.component.html (name with error msg)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" region="name-with-error-msg"/>

這個表單與範本驅動版本的不同之處，在於它不再匯出任何指令，而是使用元件類別中定義的 `name` getter。

請注意，範本中仍然保留了 `required` 屬性。雖然它對驗證而言並非必要，但為了無障礙的目的，應該將它保留。

## 定義自訂驗證器 {#defining-custom-validators}

內建驗證器不見得總是符合你應用程式的確切使用情境，因此有時你需要建立自訂驗證器。

以前面範例中的 `forbiddenNameValidator` 函式為例。
這個函式的定義如下所示。

<docs-code header="forbidden-name.directive.ts (forbiddenNameValidator)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="custom-validator"/>

這個函式是一個工廠函式，它接受一個正規表示式，用來偵測特定的禁止名稱，並回傳一個驗證器函式。

在這個範例中，禁止名稱是 "bob"，因此驗證器會拒絕任何包含 "bob" 的演員姓名。
在其他地方，它也可以拒絕 "alice"，或任何符合所設定正規表示式的名稱。

`forbiddenNameValidator` 工廠函式會回傳設定好的驗證器函式。
該函式接受一個 Angular 控制項物件，並回傳 null（若控制項的值有效）或一個驗證錯誤物件。
驗證錯誤物件通常有一個屬性，其名稱就是驗證鍵 `'forbiddenName'`，其值則是一個任意的字典，你可以把這些值插入錯誤訊息中，例如 `{name}`。

自訂非同步驗證器與同步驗證器相似，但它們必須改為回傳一個 Promise 或 observable，稍後發出 null 或驗證錯誤物件。
若是 observable，該 observable 必須完成，屆時表單會使用最後發出的值來進行驗證。

### 將自訂驗證器加入反應式表單

在反應式表單中，將函式直接傳給 `FormControl`，即可加入自訂驗證器。

<docs-code header="actor-form-reactive.component.ts (validator functions)" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.1.ts" region="custom-validator"/>

### 將自訂驗證器加入範本驅動表單

在範本驅動表單中，要在範本中加入一個指令，由該指令包裝驗證器函式。
例如，對應的 `ForbiddenValidatorDirective` 就是 `forbiddenNameValidator` 的包裝。

Angular 之所以能辨識這個指令在驗證流程中的角色，是因為該指令向 `NG_VALIDATORS` provider 註冊了自己，如下列範例所示。
`NG_VALIDATORS` 是一個預先定義的 provider，帶有一組可擴充的驗證器集合。

<docs-code header="forbidden-name.directive.ts (providers)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="directive-providers"/>

接著，指令類別實作了 `Validator` 介面，使它能輕鬆與 Angular 表單整合。
以下是指令的其餘部分，幫助你了解這一切如何組合起來。

<docs-code header="forbidden-name.directive.ts (directive)" path="adev/src/content/examples/form-validation/src/app/shared/forbidden-name.directive.ts" region="directive"/>

`ForbiddenValidatorDirective` 準備好之後，你可以把它的 selector `appForbiddenName` 加入任何 input 元素來啟用它。
例如：

<docs-code header="actor-form-template.component.html (forbidden-name-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="name-input"/>

HELPFUL: 請注意，自訂驗證指令是用 `useExisting` 而不是 `useClass` 來實例化的。
註冊的驗證器必須是 `ForbiddenValidatorDirective` 的這個實例——也就是表單中那個實例，其 `forbiddenName` 屬性繫結到 "bob"。

如果你把 `useExisting` 換成 `useClass`，註冊的就會是一個新的類別實例，而它並沒有 `forbiddenName`。

## 控制項狀態 CSS 類別 {#control-status-css-classes}

Angular 會自動將許多控制項屬性鏡像到表單控制項元素上，作為 CSS 類別。
你可以使用這些類別，依據表單的狀態為表單控制項元素設定樣式。
目前支援下列類別。

- `.ng-valid`
- `.ng-invalid`
- `.ng-pending`
- `.ng-pristine`
- `.ng-dirty`
- `.ng-untouched`
- `.ng-touched`
- `.ng-submitted`（僅限最外層的 form 元素）

在下列範例中，演員表單使用 `.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。

下列跨欄位驗證範例示範如何做到下列事項：

- 依據兩個同層控制項的值，驗證反應式或範本驅動的表單輸入，
- 在使用者與表單互動且驗證失敗後，顯示具描述性的錯誤訊息。

這些範例使用跨欄位驗證，透過填寫演員表單，確保演員不會在自己的角色上重複使用相同姓名。
驗證器的做法是檢查演員的姓名與角色是否相符。

### 將跨欄位驗證加入反應式表單

這個表單的結構如下：

```ts
const actorForm = new FormGroup({
  'name': new FormControl(),
  'role': new FormControl(),
  'skill': new FormControl(),
});
```

請注意，`name` 與 `role` 是同層控制項。
若要在單一自訂驗證器中同時評估這兩個控制項，你必須在它們共同的祖先控制項中執行驗證：也就是 `FormGroup`。
你向 `FormGroup` 查詢它的子控制項，以便比較它們的值。

若要為 `FormGroup` 加入驗證器，請在建立時把新的驗證器作為第二個引數傳入。

```ts
const actorForm = new FormGroup(
  {
    'name': new FormControl(),
    'role': new FormControl(),
    'skill': new FormControl(),
  },
  {validators: unambiguousRoleValidator},
);
```

驗證器的程式碼如下。

<docs-code header="unambiguous-role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/unambiguous-role.directive.ts" region="cross-validation-validator"/>

`unambiguousRoleValidator` 驗證器實作了 `ValidatorFn` 介面。
它接受一個 Angular 控制項物件作為引數，若表單有效則回傳 null，否則回傳 `ValidationErrors`。

這個驗證器透過呼叫 `FormGroup` 的 [get](api/forms/AbstractControl#get) 方法取得子控制項，然後比較 `name` 與 `role` 控制項的值。

如果兩個值不相符，表示角色並不含糊，兩者都有效，驗證器回傳 null。
如果兩者相符，表示演員的角色含糊不清，驗證器必須回傳一個錯誤物件，把表單標記為無效。

為了提供更好的使用者體驗，當表單無效時，範本會顯示適當的錯誤訊息。

<docs-code header="actor-form-reactive.component.html" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.html" region="cross-validation-error-message"/>

這個 `@if` 會在 `FormGroup` 帶有 `unambiguousRoleValidator` 驗證器回傳的跨欄位驗證錯誤時顯示該錯誤，但前提是使用者已完成[與表單的互動](#control-status-css-classes)。

### 將跨欄位驗證加入範本驅動表單

對於範本驅動表單，你必須建立一個指令來包裝驗證器函式。
你使用 [`NG_VALIDATORS` token](/api/forms/NG_VALIDATORS) 把該指令提供為驗證器，如下列範例所示。

<docs-code header="unambiguous-role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/unambiguous-role.directive.ts" region="cross-validation-directive"/>

你必須把這個新指令加入 HTML 範本。
由於驗證器必須在表單的最高層級註冊，下列範本把指令放在 `form` 標籤上。

<docs-code header="actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="cross-validation-register-validator"/>

為了提供更好的使用者體驗，當表單無效時，會出現適當的錯誤訊息。

<docs-code header="actor-form-template.component.html" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="cross-validation-error-message"/>

這一點在範本驅動表單與反應式表單中都相同。

## 建立非同步驗證器 {#creating-asynchronous-validators}

非同步驗證器實作了 `AsyncValidatorFn` 與 `AsyncValidator` 介面。
它們與同步的對應物非常相似，只有下列差異。

- `validate()` 函式必須回傳 Promise 或 observable，
- 回傳的 observable 必須是有限的，也就是它必須在某個時間點完成。
  若要把無限 observable 轉成有限的，可以透過 `first`、`last`、`take` 或 `takeUntil` 等過濾運算子來串接（pipe）observable。

非同步驗證在同步驗證之後進行，而且只有在同步驗證成功時才會執行。
這道檢查讓表單得以避免潛在成本高昂的非同步驗證流程（例如 HTTP 請求），前提是較基本的驗證方法已經發現無效的輸入。

非同步驗證開始後，表單控制項會進入 `pending` 狀態。
你可以檢視控制項的 `pending` 屬性，並用它來提供有關進行中驗證操作的視覺回饋。

一個常見的 UI 模式是在執行非同步驗證時顯示一個 spinner。
下列範例示範如何在範本驅動表單中做到這一點。

```html
<input [(ngModel)]="name" #model="ngModel" appSomeAsyncValidator />

@if (model.pending) {
  <app-spinner />
}
```

### 實作自訂非同步驗證器 {#implementing-a-custom-async-validator}

在下列範例中，一個非同步驗證器確保演員被安排到尚未被佔用的角色。
新演員不斷來試鏡，舊演員不斷退休，因此可用角色的清單無法事先取得。
若要驗證潛在的角色輸入，驗證器必須啟動一個非同步操作，去查詢目前所有已選角演員的中央資料庫。

下列程式碼建立了驗證器類別 `UniqueRoleValidator`，它實作了 `AsyncValidator` 介面。

<docs-code header="role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" region="async-validator"/>

`actorsService` 屬性以 `ActorsService` token 的實例初始化，該 token 定義了下列介面。

```ts
interface ActorsService {
  isRoleTaken: (role: string) => Observable<boolean>;
}
```

在真實世界的應用程式中，`ActorsService` 會負責向演員資料庫發出 HTTP 請求，檢查角色是否可用。
從驗證器的角度來看，服務的實際實作並不重要，因此範例可以直接針對 `ActorsService` 介面來撰寫程式。

驗證開始時，`UniqueRoleValidator` 會以目前的控制項值，委派給 `ActorsService` 的 `isRoleTaken()` 方法。
此時控制項會被標記為 `pending`，並維持這個狀態，直到 `validate()` 方法回傳的 observable 鏈完成為止。

`isRoleTaken()` 方法會發出一個 HTTP 請求，檢查角色是否可用，並回傳 `Observable<boolean>` 作為結果。
`validate()` 方法透過 `map` 運算子串接回應，並將它轉換成驗證結果。

接著，這個方法就像任何驗證器一樣，若表單有效就回傳 `null`，若無效就回傳 `ValidationErrors`。
這個驗證器使用 `catchError` 運算子處理任何潛在錯誤。
在這個案例中，驗證器把 `isRoleTaken()` 的錯誤視為驗證成功，因為驗證請求失敗並不一定表示角色無效。
你可以改以不同方式處理錯誤，改為回傳 `ValidationError` 物件。

一段時間過去後，observable 鏈完成，非同步驗證也隨之結束。
`pending` 旗標被設為 `false`，表單的有效性也隨之更新。

### 將非同步驗證器加入反應式表單

若要在反應式表單中使用非同步驗證器，先把驗證器注入到元件類別的一個屬性中。

<docs-code header="actor-form-reactive.component.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-inject"/>

接著，把驗證器函式直接傳給 `FormControl` 來套用它。

在下列範例中，`UniqueRoleValidator` 的 `validate` 函式被套用到 `roleControl`，做法是把它傳給控制項的 `asyncValidators` 選項，並把它繫結到注入到 `ActorFormReactiveComponent` 的 `UniqueRoleValidator` 實例。
`asyncValidators` 的值可以是單一非同步驗證器函式，也可以是函式陣列。
若要進一步了解 `FormControl` 選項，請見 [AbstractControlOptions](api/forms/AbstractControlOptions) API 參考文件。

<docs-code header="actor-form-reactive.component.ts" path="adev/src/content/examples/form-validation/src/app/reactive/actor-form-reactive.component.2.ts" region="async-validator-usage"/>

### 將非同步驗證器加入範本驅動表單

若要在範本驅動表單中使用非同步驗證器，請建立一個新指令，並在它上面註冊 `NG_ASYNC_VALIDATORS` provider。

在下面的範例中，該指令注入了包含實際驗證邏輯的 `UniqueRoleValidator` 類別，並在 `validate` 函式中呼叫它；這個函式會在 Angular 認為應該進行驗證時被觸發。

<docs-code header="role.directive.ts" path="adev/src/content/examples/form-validation/src/app/shared/role.directive.ts" region="async-validator-directive"/>

接著，如同同步驗證器一樣，把指令的 selector 加入某個 input 來啟用它。

<docs-code header="actor-form-template.component.html (unique-unambiguous-role-input)" path="adev/src/content/examples/form-validation/src/app/template/actor-form-template.component.html" region="role-input"/>

### 優化非同步驗證器的效能

預設情況下，所有驗證器都會在每次表單值變更後執行。
使用同步驗證器時，這通常不會對應用程式效能造成明顯影響。
然而，非同步驗證器通常會執行某種 HTTP 請求來驗證控制項。
每次按鍵都發出 HTTP 請求，可能會對後端 API 造成負擔，能避免就應該避免。

你可以把 `updateOn` 屬性從 `change`（預設）改為 `submit` 或 `blur`，藉此延後更新表單的有效性狀態。

在範本驅動表單中，請在範本中設定這個屬性。

```html
<input [(ngModel)]="name" [ngModelOptions]="{updateOn: 'blur'}" />
```

在反應式表單中，請在 `FormControl` 實例中設定這個屬性。

```ts
new FormControl('', {updateOn: 'blur'});
```

## 在反應式表單中動態管理驗證器 {#managing-validators-dynamically-in-reactive-forms}

在複雜的反應式表單中，你可能需要依據使用者輸入或應用程式狀態，新增、移除或修改驗證器。
Angular 在 `AbstractControl` 上提供了數個方法，讓你在執行階段管理驗證器，而不必重新建立表單控制項。

### 新增與移除驗證器

[`addValidators`](api/forms/AbstractControl#addValidators) 與 [`removeValidators`](api/forms/AbstractControl#removeValidators) 方法讓你可以在初始化之後修改控制項的驗證器。
Angular 以參考來比對驗證器，因此你傳給 `removeValidators` 的函式，必須與你傳給 `addValidators` 的是同一個函式。

```ts
private readonly usPostalCode = Validators.pattern(/^\d{5}$/);

onCountryChange(country: string) {
    const postalCodeControl = this.profileForm.get('postalCode');

if (country === 'US') {
      // Add validators for US postal codes
      postalCodeControl.addValidators([Validators.required, this.usPostalCode]);
    } else {
      // Remove validators when not US
      postalCodeControl.removeValidators([Validators.required, this.usPostalCode]);
    }

postalCodeControl.updateValueAndValidity();
}
```

### 取代所有驗證器

使用 [`setValidators`](api/forms/AbstractControl#setValidators) 可以取代控制項上所有現有的同步驗證器，使用 [`clearValidators`](api/forms/AbstractControl#clearValidators) 則可以移除所有驗證器。

```ts
toggleStrictNameValidation(isStrict: boolean) {
  const nameControl = this.profileForm.get('name');

if (isStrict) {
    // Set strict validation rules
    nameControl.setValidators([
      Validators.required,
      Validators.minLength(3),
      Validators.pattern(/^[a-zA-Z]+$/),
    ]);
  } else {
    // Clear all validators
    nameControl.clearValidators();
  }

nameControl.updateValueAndValidity();
}
```

同樣的模式也適用於非同步驗證器，使用 [`addAsyncValidators`](api/forms/AbstractControl#addAsyncValidators)、[`removeAsyncValidators`](api/forms/AbstractControl#removeAsyncValidators)、[`setAsyncValidators`](api/forms/AbstractControl#setAsyncValidators) 與 [`clearAsyncValidators`](api/forms/AbstractControl#clearAsyncValidators)。

### 觸發驗證更新

修改驗證器之後，呼叫 [`updateValueAndValidity`](api/forms/AbstractControl#updateValueAndValidity) 來重新計算控制項的驗證狀態。
這個方法接受選項，用來控制更新行為。

```ts
// Update control and notify parent
control.updateValueAndValidity();

// Update control only, don't notify parent or emit events
control.updateValueAndValidity({onlySelf: true, emitEvent: false});
```

## 與原生 HTML 表單驗證的互動

預設情況下，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. 開發一個動態建立表單控制項的元件。

你建立的表單使用輸入驗證與樣式來改善使用者體驗。
它有一個 Save 按鈕，只有在所有使用者輸入都有效時才會啟用，並以顏色標示與錯誤訊息標記無效的輸入。

這個基本版本可以逐步演進，支援更豐富多樣的問題、更優雅的算繪，以及更好的使用者體驗。

## 為專案啟用反應式表單

動態表單是以反應式表單為基礎。

若要讓應用程式能存取反應式表單指令，請把 `@angular/forms` 套件的 `ReactiveFormsModule` 匯入需要的元件。
## 建立表單物件模型

動態表單需要一個物件模型，能描述表單功能所需的所有情境。
範例中的英雄應徵表單是一組問題，也就是說，表單中的每個控制項都必須提出一個問題並接受一個答案。

這類表單的資料模型必須能表示一個問題。
範例包含 `DynamicFormQuestionComponent`，它把問題定義為模型中的基本物件。

下列 `QuestionBase` 是一組控制項的基底類別，這些控制項可以在表單中表示問題及其答案。

<docs-code header="question-base.ts" path="adev/src/content/examples/dynamic-form/src/app/question-base.ts"/>

### 定義控制項類別

範例從這個基底衍生出兩個新類別 `TextboxQuestion` 與 `DropdownQuestion`，代表不同的控制項類型。
在下一步建立表單範本時，你會具現化這些特定的問題類型，以便動態算繪適當的控制項。

`TextboxQuestion` 控制項類型在表單範本中使用 `<input>` 元素表示。它呈現一個問題，讓使用者輸入內容。該元素的 `type` 屬性依 `options` 參數中指定的 `type` 欄位來定義（例如 `text`、`email`、`url`）。

<docs-code header="question-textbox.ts" path="adev/src/content/examples/dynamic-form/src/app/question-textbox.ts"/>

`DropdownQuestion` 控制項類型會在選取框中呈現一份選項清單。

<docs-code header="question-dropdown.ts" path="adev/src/content/examples/dynamic-form/src/app/question-dropdown.ts"/>

### 組合表單群組

動態表單使用服務，依表單模型建立分組的輸入控制項集合。
下列 `QuestionControlService` 會根據問題模型中的中繼資料，建立一個由 `FormControl` 執行個體組成的 `FormGroup`。
你可以指定預設值與驗證規則。

<docs-code header="question-control.service.ts" path="adev/src/content/examples/dynamic-form/src/app/question-control.service.ts"/>

## 組合動態表單內容

動態表單本身由一個容器元件表示，你會在後面的步驟中加入它。
每個問題在表單元件的範本中都以 `<app-question>` 標籤表示，它對應到 `DynamicFormQuestionComponent` 的一個執行個體。

`DynamicFormQuestionComponent` 負責依資料繫結的問題物件中的值，算繪個別問題的詳細內容。
表單仰賴 [`[formGroup]` 指令](api/forms/FormGroupDirective 'API reference') 把範本 HTML 連接到底層的控制項物件。
`DynamicFormQuestionComponent` 會接收由 `QuestionControlService` 建立的表單群組，並為其問題算繪控制項，依據該處設定的規則顯示驗證狀態。
`DynamicFormQuestionComponent` 的目標是呈現你在模型中定義的問題類型。
目前你只有兩種問題類型，但你可以想像還能有更多。
範本中的 `@switch` 區塊決定要顯示哪一種問題類型。
這個 switch 使用了帶有 [`formControlName`](api/forms/FormControlName 'FormControlName directive API reference') 與 [`formGroup`](api/forms/FormGroupDirective 'FormGroupDirective API reference') 選擇器的指令。
這兩個指令都定義在 `ReactiveFormsModule` 中。

### 提供資料

還需要另一個服務，來提供一組特定的問題，藉此建立個別表單。
在本練習中，你建立 `QuestionService`，從硬編碼的範例資料提供這份問題陣列。
在真實世界的應用程式中，該服務可能會從後端系統擷取資料。
不過，關鍵在於：你完全可以透過 `QuestionService` 傳回的物件來控制英雄求職的問題。
當需求改變時，若要維護這份問卷，你只需要在 `questions` 陣列中新增、更新與移除物件。

`QuestionService` 以陣列形式提供一組問題，該陣列繫結到 `input()` 問題。

<docs-code header="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"/>

模型與資料如此分離，讓你可以把這些元件重新用於任何類型的問卷調查，只要它與_問題_物件模型相容即可。

### 確保資料有效

表單範本使用中繼資料的動態資料繫結來算繪表單，不對特定問題做任何寫死的假設。
它會動態加入控制項中繼資料與驗證條件。

為了確保輸入有效，_Save_ 按鈕在表單處於有效狀態之前會保持停用。
當表單有效時，點選 _Save_，應用程式就會把目前的表單值以 JSON 形式算繪出來。

下圖顯示最終的表單。

## 後續步驟
Angular Router（`@angular/router`）是管理 Angular 應用程式導覽的官方函式庫，也是框架的核心組成部分。所有由 Angular CLI 建立的專案都預設包含它。

## 為什麼 SPA 需要路由？

當你在網頁瀏覽器中導覽至某個 URL 時，瀏覽器通常會向網頁伺服器發出網路請求，並顯示回傳的 HTML 頁面。當你導覽至不同的 URL（例如點選連結），瀏覽器會再發出另一個網路請求，並以新頁面完全取代整個頁面。

單頁應用程式（SPA）不同之處在於，瀏覽器只會向網頁伺服器請求第一個頁面，也就是 `index.html`。之後便由用戶端路由接手，根據 URL 控制要顯示的內容。當使用者導覽至不同的 URL 時，路由會就地更新頁面內容，而不觸發整頁重新載入。

## Angular 如何管理路由

Angular 的路由由三個主要部分組成：

1. **路由**定義使用者造訪特定 URL 時要顯示哪個元件。
2. **出口**是範本中的佔位元素，會根據目前啟用的路由，動態載入並渲染元件。
3. **連結**讓使用者能在應用程式的不同路由之間導覽，而不觸發整頁重新載入。

此外，Angular 路由函式庫還提供以下額外功能：

- 巢狀路由
- 程式化導覽
- 路由參數、查詢與萬用字元
- 透過 `ActivatedRoute` 取得已啟用路由的資訊
- 透過路由資源與解析器擷取資料
- 檢視轉場效果
- 導覽守衛

## 後續步驟

進一步了解如何[使用 Angular Router 定義路由](/guide/routing/define-routes)。
# 定義路由

路由是 Angular 應用程式中導覽的基本組成單位。

## 什麼是路由？

在 Angular 中，**路由**是一個物件，定義了針對特定 URL 路徑或模式應渲染哪個元件，以及使用者導覽到該 URL 時還會發生什麼的其他設定選項。

以下是一個路由的基本範例：

```ts
import {AdminPage} from './app-admin';

const adminPage = {
  path: 'admin',
  component: AdminPage,
};
```

對於這條路由，當使用者造訪 `/admin` 路徑時，應用程式會顯示 `AdminPage` 元件。

### 在應用程式中管理路由

大多數專案把路由定義在一個獨立檔案中，其檔名包含 `routes`。

一組路由看起來像這樣：

```ts
import {Routes} from '@angular/router';
import {HomePage} from './home-page';
import {AdminPage} from './admin-page';

export const routes: Routes = [
  {
    path: '',
    component: HomePage,
  },
  {
    path: 'admin',
    component: AdminPage,
  },
];
```

TIP: 若你使用 Angular CLI 產生專案，你的路由定義在 `src/app/app.routes.ts`。

### 把路由加入應用程式 {#adding-the-router-to-your-application}

在不使用 Angular CLI 引導 Angular 應用程式時，你可以傳入一個包含 `providers` 陣列的設定物件。

在 `providers` 陣列內，你可以呼叫 `provideRouter` 函式並傳入你的路由，把 Angular 路由加入應用程式。

```ts
import {ApplicationConfig} from '@angular/core';
import {provideRouter} from '@angular/router';

import {routes} from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    // ...
  ],
};
```

## 路由 URL 路徑

### 靜態 URL 路徑

靜態 URL 路徑指的是具有預先定義路徑、不隨動態參數改變的路由。這些路由會精確比對 `path` 字串，並有固定的結果。

這類範例包括：

- "/admin"
- "/blog"
- "/settings/account"

### 使用路由參數定義 URL 路徑 {#define-url-paths-with-route-parameters}

參數化 URL 讓你定義動態路徑，使多個 URL 能通往同一個元件，同時依據 URL 中的參數動態顯示資料。

你可以把參數加入路由的 `path` 字串，並在每個參數前面加上冒號（`:`）字元，來定義這類模式。

IMPORTANT: 參數與 URL 的[查詢字串](https://en.wikipedia.org/wiki/Query_string)中的資訊不同。
如需深入瞭解 Angular 中的查詢參數，請參閱[本指南](/guide/routing/read-route-state#query-parameters)。

下列範例依據透過 URL 傳入的使用者 id，顯示使用者個人資料元件。

```ts
import {Routes} from '@angular/router';
import {UserProfile} from './user-profile/user-profile';

const routes: Routes = [{path: 'user/:id', component: UserProfile}];
```

在此範例中，`/user/leeroy` 與 `/user/jenkins` 等 URL 會渲染 `UserProfile` 元件。此元件接著可以讀取 `id` 參數，並用它執行額外的工作，例如擷取資料。讀取路由參數的詳細資訊，請參閱[讀取路由狀態指南](/guide/routing/read-route-state)。

有效的路由參數名稱必須以字母（a-z、A-Z）開頭，且只能包含：

- 字母（a-z、A-Z）
- 數字（0-9）
- 底線（\_）
- 連字號（-）

你也可以定義具有多個參數的路徑：

```ts
import {Routes} from '@angular/router';
import {UserProfile} from './user-profile';
import {SocialMediaFeed} from './social-media-feed';

const routes: Routes = [
  {path: 'user/:id/:social-media', component: SocialMediaFeed},
  {path: 'user/:id', component: UserProfile},
];
```

有了這條新路徑，使用者可以造訪 `/user/leeroy/youtube` 與 `/user/leeroy/bluesky`，並依據使用者 leeroy 的參數，看到各自的社群媒體動態。

讀取路由參數的詳細資訊，請參閱[讀取路由狀態](/guide/routing/read-route-state)。

### 萬用字元 {#wildcards}

當你需要攔截特定路徑的所有路由時，解決方法是使用以雙星號（`**`）定義的萬用字元路由。

一個常見的範例是定義找不到頁面的元件。

```ts
import {Routes} from '@angular/router';
import {Home} from './home/home';
import {UserProfile} from './user-profile';
import {NotFound} from './not-found';

const routes: Routes = [
  {path: 'home', component: Home},
  {path: 'user/:id', component: UserProfile},
  {path: '**', component: NotFound},
];
```

在此路由陣列中，當使用者造訪 `home` 與 `user/:id` 以外的任何路徑時，應用程式會顯示 `NotFound` 元件。

TIP: 萬用字元路由通常放在路由陣列的末尾。

## Angular 如何比對 URL

當你定義路由時，順序很重要，因為 Angular 採用先比對先贏的策略。這表示一旦 Angular 把某個 URL 與一條路由的 `path` 比對成功，就會停止檢查後續的路由。因此，請務必把更具體的路由放在較不具體的路由之前。

下列範例顯示了從最具體到最不具體定義的路由：

```ts
const routes: Routes = [
  {path: '', component: Home}, // Empty path
  {path: 'users/new', component: NewUser}, // Static, most specific
  {path: 'users/:id', component: UserDetail}, // Dynamic
  {path: 'users', component: Users}, // Static, less specific
  {path: '**', component: NotFound}, // Wildcard - always last
];
```

若使用者造訪 `/users/new`，Angular 路由會經過下列步驟：

1. 檢查 `''`：不相符
1. 檢查 `users/new`：相符！在此停止
1. 永遠不會到達 `users/:id`，即使它也可能相符
1. 永遠不會到達 `users`
1. 永遠不會到達 `**`

## 重新導向

你可以定義一條路由，讓它重新導向到另一條路由，而不是渲染元件：

```ts
import {Routes} from '@angular/router';
import {Blog} from './home/blog';

const routes: Routes = [
  {
    path: 'articles',
    redirectTo: '/blog',
  },
  {
    path: 'blog',
    component: Blog,
  },
];
```

若你修改或移除了某條路由，有些使用者仍可能點選指向該路由的過時連結或書籤。你可以加入重新導向，把這些使用者導向適當的替代路由，而不是「找不到」頁面。

## 頁面標題 {#page-titles}

你可以為每條路由關聯一個 **title**。Angular 會在路由啟用時自動更新[頁面標題](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title)。請務必為應用程式定義適當的頁面標題，因為這些標題是打造無障礙體驗的必要元素。

```ts
import {Routes} from '@angular/router';
import {Home} from './home';
import {About} from './about';
import {Products} from './products';

const routes: Routes = [
  {
    path: '',
    component: Home,
    title: 'Home Page',
  },
  {
    path: 'about',
    component: About,
    title: 'About Us',
  },
];
```

頁面的 `title` 屬性可以使用 [`ResolveFn`](/api/router/ResolveFn) 動態設定為一個解析器函式。

```ts
const titleResolver: ResolveFn<string> = (route) => route.queryParams['id'];
const routes: Routes = [
  // ...
  {
    path: 'products',
    component: Products,
    title: titleResolver,
  },
];
```

路由標題也可以透過繼承 [`TitleStrategy`](/api/router/TitleStrategy) 抽象類別的服務來設定。預設情況下，Angular 使用 [`DefaultTitleStrategy`](/api/router/DefaultTitleStrategy)。

### 使用 TitleStrategy 設定頁面標題 {#using-titlestrategy-for-page-titles}

在需要集中控制文件標題組成方式的進階情境中，請實作 `TitleStrategy`。

`TitleStrategy` 是一個你可以提供的 token，用來覆寫 Angular 使用的預設標題策略。你可以提供自訂的 `TitleStrategy`，實作諸如加上應用程式字尾、從麵包屑格式化標題，或從路由資料動態產生標題等慣例。

```ts
import {inject, Injectable} from '@angular/core';
import {Title} from '@angular/platform-browser';
import {TitleStrategy, RouterStateSnapshot} from '@angular/router';

@Injectable()
export class AppTitleStrategy extends TitleStrategy {
  private readonly title = inject(Title);
  // Read once: getTitle() returns the prefixed title after the first update
  private readonly defaultTitle = this.title.getTitle();

updateTitle(snapshot: RouterStateSnapshot): void {
    // PageTitle is equal to the "Title" of a route if it's set
    // If it's not set, it uses the "title" given in index.html
    const pageTitle = this.buildTitle(snapshot) || this.defaultTitle;
    this.title.setTitle(`MyAwesomeApp - ${pageTitle}`);
  }
}
```

若要使用自訂策略，請在應用程式層級以 `TitleStrategy` token 提供它：

```ts
import {provideRouter, TitleStrategy} from '@angular/router';
import {AppTitleStrategy} from './app-title.strategy';

export const appConfig = {
  providers: [provideRouter(routes), {provide: TitleStrategy, useClass: AppTitleStrategy}],
};
```

## 用於依賴注入的路由層級提供者

每條路由都有一個 `providers` 屬性，讓你透過[依賴注入](/guide/di)把相依性提供給該路由的內容。

常見的適用情境包括：依據使用者是否為管理員而使用不同服務的應用程式。

```ts
export const ROUTES: Route[] = [
  {
    path: 'admin',
    providers: [AdminService, {provide: ADMIN_API_KEY, useValue: '12345'}],
    children: [
      {path: 'users', component: AdminUsers},
      {path: 'teams', component: AdminTeams},
    ],
  },
  // ... other application routes that don't
  //     have access to ADMIN_API_KEY or AdminService.
];
```

在此程式碼範例中，`admin` 路徑包含受保護的資料屬性 `ADMIN_API_KEY`，只有其區段內的子路由才能使用。因此，其他任何路徑都無法存取透過 `ADMIN_API_KEY` 提供的資料。

如需深入瞭解 Angular 中的提供者與注入，請參閱[依賴注入指南](/guide/di)。

## 為路由關聯資料

路由資料讓你把額外資訊附加到路由上。你可以依據這些資料設定元件的行為方式。

處理路由資料有兩種方式：保持不變的靜態資料，以及可依據執行階段條件改變的動態資料。

### 靜態資料

你可以透過 `data` 屬性為路由關聯任意的靜態資料，以集中管理路由專屬的中繼資料（例如分析追蹤、權限等）：

```ts
import {Routes} from '@angular/router';
import {Home} from './home';
import {About} from './about';
import {Products} from './products';

const routes: Routes = [
  {
    path: 'about',
    component: About,
    data: {analyticsId: '456'},
  },
  {
    path: '',
    component: Home,
    data: {analyticsId: '123'},
  },
];
```

在此程式碼範例中，首頁與關於頁面設定了特定的 `analyticsId`，之後會在各自的元件中用於頁面追蹤分析。

你可以注入 `ActivatedRoute` 來讀取這份靜態資料。詳細資訊請參閱[讀取路由狀態](/guide/routing/read-route-state)。

### 使用資源與解析器的動態資料

當你需要為路由擷取資料時，Angular 路由支援反應式路由資源以及資料解析器：

- [使用資源擷取資料](/guide/routing/data-fetching-with-resources)：使用 Angular Signals 的 `Resource` API，以反應式的方式擷取資料。
- [路由資料解析器](/guide/routing/data-resolvers)：在路由啟用之前，使用解析器函式擷取資料。

### 錯誤後備元件

你可以在路由上指定 `errorComponent`，讓路由元件在初始化或渲染期間擲出錯誤時，渲染一個專用的後備元件：

```ts
import {Routes} from '@angular/router';
import {ProductDetails} from './product-details';
import {ProductErrorFallback} from './product-error-fallback';

export const routes: Routes = [
  {
    path: 'product/:id',
    component: ProductDetails,
    errorComponent: ProductErrorFallback,
  },
];
```

如需進一步了解如何設定錯誤後備機制與重試失敗的路由，請參閱[錯誤邊界指南](/guide/routing/error-boundaries)。

## 巢狀路由

巢狀路由（也稱為子路由）是一種常見技術，用來管理較複雜的導覽路由：某個元件擁有一個會依據 URL 改變的子檢視。

你可以使用 `children` 屬性，為任何路由定義加入子路由：

```ts
const routes: Routes = [
  {
    path: 'product/:id',
    component: Product,
    children: [
      {
        path: 'info',
        component: ProductInfo,
      },
      {
        path: 'reviews',
        component: ProductReviews,
      },
    ],
  },
];
```

上述範例定義了一條產品頁面的路由，讓使用者能依據 URL 切換顯示產品資訊或評論。

`children` 屬性接受一個 `Route` 物件陣列。

若要顯示子路由，父元件（範例中的 `Product`）需包含它自己的 `<router-outlet>`。

```html

<article>
  <h1>Product {{ id }}</h1>
  <router-outlet />
</article>
```

在設定中加入子路由，並在元件中加入 `<router-outlet>` 之後，在符合子路由的 URL 之間導覽，只會更新巢狀的 outlet。

## 後續步驟
# 使用 outlet 顯示路由

`RouterOutlet` 指令是一個預留位置，標示路由器應在此處渲染目前 URL 對應的元件。

```html
<app-header />

<router-outlet />
<app-footer />
```

```ts
import {Component} from '@angular/core';
import {RouterOutlet} from '@angular/router';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet],
  templateUrl: './app.html',
  styleUrl: './app.css',
})
export class App {}
```

在本範例中，假設應用程式定義了下列路由：

```ts
import {Routes} from '@angular/router';
import {Home} from './home';
import {Products} from './products';

const routes: Routes = [
  {
    path: '',
    component: Home,
    title: 'Home Page',
  },
  {
    path: 'products',
    component: Products,
    title: 'Our Products',
  },
];
```

當使用者造訪 `/products` 時，Angular 會渲染下列內容：

```html
<app-header />
<app-products />
<app-footer />
```

若使用者回到首頁，Angular 則會渲染：

```html
<app-header />
<app-home />
<app-footer />
```

顯示路由時，`<router-outlet>` 元素會保留在 DOM 中，作為後續導覽的參照點。Angular 會把路由內容插入在 outlet 元素之後，作為其同層元素。

```html

<app-header />
<router-outlet />
<app-footer />
```

```html

<app-header />
<router-outlet />
<app-admin-page />
<app-footer />
```

## 使用子路由建立巢狀路由

隨著應用程式越來越複雜，你可能會想建立相對於根元件以外元件的路由。這樣一來，URL 改變時只有應用程式的一部分會跟著改變，使用者不會感覺整個頁面都被重新整理。

這類巢狀路由稱為子路由。這表示你要在應用程式中再加入第二個 `<router-outlet>`，因為它是在 AppComponent 的 `<router-outlet>` 之外額外增加的。

在本範例中，`Settings` 元件會依使用者選取的項目顯示對應的面板。子路由的一個特別之處是，該元件通常有自己的 `<nav>` 與 `<router-outlet>`。

```html
<h1>Settings</h1>
<nav>
  <ul>
    <li><a routerLink="profile">Profile</a></li>
    <li><a routerLink="security">Security</a></li>
  </ul>
</nav>
<router-outlet />
```

子路由與其他路由一樣，都需要 `path` 與 `component`。唯一的差別是，子路由要放在父路由內的 children 陣列中。

```ts
const routes: Routes = [
  {
    path: 'settings',
    component: Settings, // this is the component with the <router-outlet> in the template
    children: [
      {
        path: 'profile', // child route path
        component: Profile, // child route component that the router renders
      },
      {
        path: 'security',
        component: Security, // another child route component that the router renders
      },
    ],
  },
];
```

只要 `routes` 與 `<router-outlet>` 都設定正確，你的應用程式就已經用上巢狀路由了！

## 使用具名 outlet 的次要路由

一個頁面可以有多個 outlet，你可以為每個 outlet 指定名稱，表明哪些內容屬於哪個 outlet。

```html
<app-header />
<router-outlet />
<router-outlet name="read-more" />
<router-outlet name="additional-actions" />
<app-footer />
```

每個 outlet 的名稱必須唯一。你可以把名稱繫結到一個值；當值改變時，outlet 會銷毀目前的元件，並在有符合的路由時，渲染新名稱對應的路由。名稱預設為 `'primary'`。

Angular 會把 outlet 的名稱與每條路由上定義的 `outlet` 屬性進行比對：

```ts
{
  path: 'user/:id',
  component: UserDetails,
  outlet: 'additional-actions'
}
```

## Outlet 生命週期事件

路由器 outlet 可以發出四種生命週期事件：

| 事件         | 說明                                                     |
| ------------ | -------------------------------------------------------- |
| `activate`   | 新元件被實例化時                                         |
| `deactivate` | 元件被銷毀時                                             |
| `attach`     | `RouteReuseStrategy` 指示 outlet 附加子樹時              |
| `detach`     | `RouteReuseStrategy` 指示 outlet 分離子樹時              |

你可以使用標準的事件繫結語法加入事件監聽器：

```html
<router-outlet
  (activate)="onActivate($event)"
  (deactivate)="onDeactivate($event)"
  (attach)="onAttach($event)"
  (detach)="onDetach($event)"
/>
```

若想深入了解，請參閱 [RouterOutlet 的 API 文件](/api/router/RouterOutlet?tab=api)。

## 把上下文資料傳給路由元件 {#passing-contextual-data-to-routed-components}

把上下文資料傳給路由元件，往往需要全域狀態或複雜的路由設定。為了簡化這件事，每個 `RouterOutlet` 都支援 `routerOutletData` 輸入。路由元件及其子元件可以使用 `ROUTER_OUTLET_DATA` 注入權杖，把這份資料當作訊號讀取，藉此進行 outlet 專屬的設定，而不必修改路由定義。

```typescript
import {Component} from '@angular/core';
import {RouterOutlet} from '@angular/router';

@Component({
  selector: 'app-dashboard',
  imports: [RouterOutlet],
  template: `
    <h2>Dashboard</h2>
    <router-outlet [routerOutletData]="{layout: 'sidebar'}" />
  `,
})
export class Dashboard {}
```

路由元件可以使用 `ROUTER_OUTLET_DATA` 注入所提供的 outlet 資料：

```typescript
import {Component, inject, Signal} from '@angular/core';
import {ROUTER_OUTLET_DATA} from '@angular/router';

@Component({
  selector: 'app-stats',
  template: `<p>Stats view (layout: {{ outletData().layout }})</p>`,
})
export class Stats {
  outletData = inject(ROUTER_OUTLET_DATA) as Signal<{layout: string}>;
}
```

當 Angular 在該 outlet 中啟用 `Stats` 時，它會收到 `{ layout: 'sidebar' }` 作為注入的資料。

NOTE: 未設定 `routerOutletData` 輸入時，注入訊號的值預設為 `undefined`。

---

## 後續步驟

了解如何使用 Angular Router [導覽至路由](/guide/routing/navigate-to-routes)。
# 導覽至路由

RouterLink 指令是 Angular 宣告式的導覽做法。它讓你能使用標準的錨點元素（`<a>`），並與 Angular 的路由系統無縫整合。

## 如何使用 RouterLink

與其使用帶有 `href` 屬性的一般錨點元素 `<a>`，不如加入帶有適當路徑的 RouterLink 指令，以善用 Angular 路由。

```typescript
import {RouterLink} from '@angular/router';
import {Component} from '@angular/core';

@Component({
  template: `
    <nav>
      <a routerLink="/user-profile">User profile</a>
      <a routerLink="/settings">Settings</a>
    </nav>
  `,
  imports: [RouterLink],
  ...
})
export class App {}
```

### 使用絕對連結或相對連結

Angular 路由中的**相對 URL**，讓你能相對於目前路由的位置來定義導覽路徑。相較之下，**絕對 URL** 包含帶有通訊協定（例如 `http://`）的完整路徑，以及**根網域**（例如 `google.com`）。

```html

<a href="https://www.angular.dev/essentials">Angular Essentials Guide</a>

<a href="/essentials">Angular Essentials Guide</a>
```

在這個範例中，第一個範例明確定義了 essentials 頁面的完整路徑，包含通訊協定（即 `https://`）與根網域（即 `angular.dev`）。相較之下，第二個範例假設使用者已經位於 `/essentials` 的正確根網域上。

一般而言，相對 URL 較受青睞，因為它們在不同應用程式之間更容易維護，不需要知道自己在路由階層中的絕對位置。

### 相對 URL 如何運作

Angular 路由有兩種定義相對 URL 的語法：字串與陣列。

```html

<a routerLink="dashboard">Dashboard</a>
<a [routerLink]="['dashboard']">Dashboard</a>
```

HELPFUL: 傳入字串是定義相對 URL 最常見的方式。

當你需要在相對 URL 中定義動態參數時，請使用陣列語法：

```html
<a [routerLink]="['user', currentUserId]">Current User</a>
```

此外，Angular 路由允許你根據相對路徑是否以斜線（`/`）開頭，來指定路徑是相對於目前的 URL，還是相對於根網域。

例如，如果使用者位於 `example.com/settings`，以下是針對不同情境定義相對路徑的方式：

```html

<a routerLink="notifications">Notifications</a>
<a routerLink="/settings/notifications">Notifications</a>

<a routerLink="/team/123/user/456">User 456</a>
<a [routerLink]="['/team', teamId, 'user', userId]">Current User</a>
```

## 以程式化方式導覽至路由

雖然 `RouterLink` 負責處理範本中的宣告式導覽，Angular 也提供程式化導覽，適用於需要根據邏輯、使用者動作或應用程式狀態來導覽的情境。透過注入 `Router`，你可以在 TypeScript 程式碼中動態導覽至各個路由、傳遞參數，並控制導覽行為。

### `router.navigate()`

你可以使用 `router.navigate()` 方法，透過指定 URL 路徑陣列，以程式化方式在路由之間導覽。

```typescript
import {Router} from '@angular/router';
import {Component, inject} from '@angular/core';

@Component({
  selector: 'app-dashboard',
  template: ` <button (click)="navigateToProfile()">View Profile</button> `,
})
export class AppDashboard {
  private router = inject(Router);

navigateToProfile() {
    // Standard navigation
    this.router.navigate(['/profile']);

// With route parameters
    this.router.navigate(['/users', userId]);

// With query parameters
    this.router.navigate(['/search'], {
      queryParams: {category: 'books', sort: 'price'},
    });

// With matrix parameters
    this.router.navigate(['/products', {featured: true, onSale: true}]);
  }
}
```

`router.navigate()` 同時支援簡單與複雜的路由情境，讓你能傳遞路由參數、[查詢參數](/guide/routing/read-route-state#query-parameters)，並控制導覽行為。

你也可以使用 `relativeTo` 選項，相對於你的元件在路由樹中的位置，來建立動態導覽路徑。

```typescript
import {Router, ActivatedRoute} from '@angular/router';
import {Component, inject} from '@angular/core';

@Component({
  selector: 'app-user-detail',
  template: `
    <button (click)="navigateToEdit()">Edit User</button>
    <button (click)="navigateToParent()">Back to List</button>
  `,
})
export class UserDetail {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

// Navigate to a sibling route
  navigateToEdit() {
    // From: /users/123
    // To:   /users/123/edit
    this.router.navigate(['edit'], {relativeTo: this.route});
  }

// Navigate to parent
  navigateToParent() {
    // From: /users/123
    // To:   /users
    this.router.navigate(['..'], {relativeTo: this.route});
  }

navigateToList() {
    // Angular resolves the commands array as a single navigation path relative to the current route.
    // From: /users/123
    // Result: /users/list
    this.router.navigate(['..', 'list'], {relativeTo: this.route});
  }
}
```

當向上導覽多個層級時，所有的 `..` 區段都必須位於命令陣列的**第一個元素**中。Router 只會解析第一個命令字串中的 `..`，後續的陣列元素會被視為字面上的路徑區段。

```typescript
{prefer}
// From: /team/123/users/456
// Result: /team/123/settings
this.router.navigate(['../../settings'], {relativeTo: this.route});
```

使用 `relativeTo` 時，絕不要在第一個命令前面加上 `/`。開頭的 `/` 會使導覽變成絕對導覽，並完全忽略 `relativeTo`。

```typescript
{prefer}
// From: /team/123/users/456
// Result: /team/123/users/456/edit
this.router.navigate(['edit'], {relativeTo: this.route});
```

```typescript
{avoid}
// From: /team/123/users/456
// Leading '/' causes absolute navigation — relativeTo is ignored
// Result: /edit
this.router.navigate(['/edit'], {relativeTo: this.route});
```

### `router.navigateByUrl()`

`router.navigateByUrl()` 方法提供了一種直接的方式，使用 URL 路徑字串（而非陣列區段）以程式化方式導覽。當你擁有完整的 URL 路徑並需要執行絕對導覽時，這個方法非常理想，特別是在處理外部提供的 URL，或深層連結的情境時。

```ts
// Standard route navigation
router.navigateByUrl('/products');

// Navigate to nested route
router.navigateByUrl('/products/featured');

// Complete URL with parameters and fragment
router.navigateByUrl('/products/123?view=details#reviews');

// Navigate with query parameters
router.navigateByUrl('/search?category=books&sortBy=price');

// With matrix parameters
router.navigateByUrl('/sales-awesome;isOffer=true;showModal=false');
```

如果你需要在瀏覽歷史中取代目前的 URL，`navigateByUrl` 也接受一個帶有 `replaceUrl` 選項的設定物件。

```ts
// Replace current URL in history
router.navigateByUrl('/checkout', {
  replaceUrl: true,
});
```

### 在網址列顯示不同的 URL

你可以將 browserUrl 選項傳給 navigateByUrl，在瀏覽器的網址列中顯示與用於路由比對不同的 URL。

當你想將使用者重新導向至不同的路由（例如錯誤頁面），但又不想改變使用者原本嘗試造訪的 URL 時，這個功能非常有用。

```ts
router.navigateByUrl('/not-found', {browserUrl: '/products/missing-item'});
```

Angular 會導覽至 `/not-found` 路由並將其渲染，但瀏覽器網址列顯示的是 `/products/missing-item`。

NOTE: `browserUrl` 只會影響瀏覽器網址列中顯示的內容。

## 使用 RouterLink 自訂瀏覽器 URL

`RouterLink` 指令也支援 `browserUrl` 輸入，讓你在連結被點選時，能控制瀏覽器網址列中顯示的 URL，獨立於 Angular 實際導覽至的路由之外。

```html

<a [routerLink]="['/dashboard']" [browserUrl]="'/home'">Go to Dashboard</a>
```

你也可以綁定一個 `UrlTree`，以應對更動態的使用情境：

```typescript
import {Component, inject} from '@angular/core';
import {Router, RouterLink, UrlTree} from '@angular/router';

@Component({
  template: `
    <a [routerLink]="['/products', product.id]" [browserUrl]="displayUrl">
      {{ product.name }}
    </a>
  `,
  imports: [RouterLink],
})
export class ProductList {
  private router = inject(Router);

product = {id: 42, name: 'Widget'};

// Create a UrlTree to display in the address bar
  displayUrl: UrlTree = this.router.createUrlTree(['/products', 'widget']);
}
```

## 使用 RouterLink 控制捲動行為

當以 `withInMemoryScrolling({scrollPositionRestoration: 'enabled'})`（或 `'top'`）啟用記憶體內捲動時，即使連結只改變了查詢參數，Router 也會在連結被點選後捲動到頁面頂部。`RouterLink` 指令支援 `scroll` 輸入，讓單一連結能選擇退出這種行為：

```html

<a routerLink="/products/42" [queryParams]="{tab: 'reviews'}" scroll="manual">Reviews</a>
```

使用 `scroll="manual"` 時，Router 不會針對該次導覽進行捲動。預設值 `'after-transition'` 則會依照 Router 的捲動設定進行捲動。

程式化導覽也可以使用相同的選項：

```ts
router.navigateByUrl('/products/42?tab=reviews', {scroll: 'manual'});
```

## 後續步驟

了解如何[讀取路由狀態](/guide/routing/read-route-state)，以建立反應敏捷且具上下文感知能力的元件。
# 讀取路由狀態

Angular Router 讓你能讀取並使用與路由相關聯的資訊，藉此建立反應敏捷且具上下文感知能力的元件。

## 透過 ActivatedRoute 取得目前路由的資訊 {#get-information-about-the-current-route-with-activatedroute}

`ActivatedRoute` 是來自 `@angular/router` 的服務，提供與目前路由相關聯的全部資訊。

```typescript
import {Component, inject} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component({
  selector: 'app-product',
})
export class Product {
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    console.log(this.activatedRoute);
  }
}
```

`ActivatedRoute` 能提供關於路由的各種不同資訊，一些常見的屬性包括：

請參閱 [`ActivatedRoute` API 文件](/api/router/ActivatedRoute)，取得你可以透過路由存取之內容的完整清單。

## 了解路由快照 {#understanding-route-snapshots}

頁面導覽是隨著時間發生的事件，你可以擷取路由快照，來存取 Router 在某個時間點的狀態。

路由快照包含關於路由的必要資訊，包括它的參數、資料與子路由。此外，快照是靜態的，不會反映未來的變化。

以下是如何存取路由快照的範例：

```typescript
import {Component, inject} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component(/* ... */)
export class UserProfile {
  readonly userId: string | null;
  private route = inject(ActivatedRoute);

constructor() {
    // Example URL: https://www.angular.dev/users/123?role=admin&status=active#contact

// Access route parameters from snapshot
    this.userId = this.route.snapshot.paramMap.get('id');

// Access multiple route elements
    const snapshot = this.route.snapshot;
    console.log({
      url: snapshot.url, // Array of UrlSegments matched by this route
      // Route parameters object: {id: '123'}
      params: snapshot.params,
      // Query parameters object: {role: 'admin', status: 'active'}
      queryParams: snapshot.queryParams, // Query parameters
    });
  }
}
```

請參閱 [`ActivatedRoute` API 文件](/api/router/ActivatedRoute) 與 [`ActivatedRouteSnapshot` API 文件](/api/router/ActivatedRouteSnapshot)，取得你可以存取之所有屬性的完整清單。

## 讀取路由上的參數

開發者可以從路由利用兩種類型的參數：路由參數與查詢參數。

### 路由參數

路由參數讓你能透過 URL 將資料傳遞給元件。當你想根據 URL 中的識別碼（例如使用者 ID 或產品 ID）來顯示特定內容時，這非常有用。

你可以透過在參數名稱前加上冒號（`:`），來[定義路由參數](/guide/routing/define-routes#define-url-paths-with-route-parameters)。

```typescript
import {Routes} from '@angular/router';
import {Product} from './product';

const routes: Routes = [{path: 'product/:id', component: Product}];
```

你可以訂閱 `route.params` 來存取參數。

```typescript
import {Component, inject, signal} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component({
  selector: 'app-product-detail',
  template: `<h1>Product Details: {{ productId() }}</h1>`,
})
export class ProductDetail {
  productId = signal('');
  private activatedRoute = inject(ActivatedRoute);

constructor() {
    // Access route parameters
    this.activatedRoute.params.subscribe((params) => {
      this.productId.set(params['id']);
    });
  }
}
```

### 查詢參數 {#query-parameters}

[查詢參數](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) 提供了一種靈活的方式，透過 URL 傳遞選擇性資料，而不會影響路由結構。與路由參數不同，查詢參數可以在多次導覽事件之間持續存在，非常適合處理篩選、排序、分頁，以及其他具狀態性的 UI 元素。

```typescript
// Single parameter structure
// /products?category=electronics
router.navigate(['/products'], {
  queryParams: {category: 'electronics'},
});

// Multiple parameters
// /products?category=electronics&sort=price&page=1
router.navigate(['/products'], {
  queryParams: {
    category: 'electronics',
    sort: 'price',
    page: 1,
  },
});
```

你可以使用 `route.queryParams` 來存取查詢參數。

以下是一個 `ProductList` 的範例，它會更新影響其產品清單顯示方式的查詢參數：

```typescript
import {Component, inject} from '@angular/core';
import {ActivatedRoute, Router} from '@angular/router';

@Component({
  selector: 'app-product-list',
  template: `
    <div>
      <select (change)="updateSort($event)">
        <option value="price">Price</option>
        <option value="name">Name</option>
      </select>
      
    </div>
  `,
})
export class ProductList {
  private route = inject(ActivatedRoute);
  private router = inject(Router);

constructor() {
    // Access query parameters reactively
    this.route.queryParams.subscribe((params) => {
      const sort = params['sort'] || 'price';
      const page = Number(params['page']) || 1;
      this.loadProducts(sort, page);
    });
  }

updateSort(event: Event) {
    const sort = (event.target as HTMLSelectElement).value;
    // Update URL with new query parameter
    this.router.navigate([], {
      queryParams: {sort},
      queryParamsHandling: 'merge', // Preserve other query parameters
    });
  }
}
```

在這個範例中，使用者可以使用下拉選單，依名稱或價格排序產品清單。與其相關聯的變更處理常式會更新 URL 的查詢參數，進而觸發變更事件，藉此讀取更新後的查詢參數，並更新產品清單。

如需更多資訊，請參閱 [QueryParamsHandling 的官方文件](/api/router/QueryParamsHandling)。

### 矩陣參數 {#matrix-parameters}

矩陣參數是屬於特定 URL 區段的選擇性參數，而不是套用到整個路由。與出現在 `?` 之後並全域套用的查詢參數不同，矩陣參數使用分號（`;`），且只套用到個別的路徑區段。

矩陣參數非常適合在不影響路由定義或比對行為的情況下，將輔助資料傳遞給特定的路由區段。與查詢參數一樣，它們不需要在你的路由設定中定義。

```ts
// URL format: /path;key=value
// Multiple parameters: /path;key1=value1;key2=value2

// Navigate with matrix parameters
this.router.navigate(['/awesome-products', {view: 'grid', filter: 'new'}]);
// Results in URL: /awesome-products;view=grid;filter=new
```

**使用 ActivatedRoute**

```ts
import {Component, inject} from '@angular/core';
import {ActivatedRoute} from '@angular/router';

@Component(/* ... */)
export class AwesomeProducts {
  private route = inject(ActivatedRoute);

constructor() {
    // Access matrix parameters via params
    this.route.params.subscribe((params) => {
      const view = params['view']; // e.g., 'grid'
      const filter = params['filter']; // e.g., 'new'
    });
  }
}
```

NOTE: 除了使用 `ActivatedRoute` 之外，當使用 `withComponentInputBinding` 時，矩陣參數也會綁定到元件輸入上。

## 使用 RouterLinkActive 偵測目前啟用的路由 {#detect-active-current-route-with-routerlinkactive}

你可以使用 `RouterLinkActive` 指令，根據目前啟用的路由，動態地為導覽元素套用樣式。這在導覽元素中很常見，用來通知使用者目前啟用的是哪個路由。

```html
<nav>
  <a
    class="button"
    routerLink="/about"
    routerLinkActive="active-button"
    ariaCurrentWhenActive="page"
  >
    About
  </a>
  |
  <a
    class="button"
    routerLink="/settings"
    routerLinkActive="active-button"
    ariaCurrentWhenActive="page"
  >
    Settings
  </a>
</nav>
```

在這個範例中，當 URL 與對應的 `routerLink` 相符時，Angular Router 會將 `active-button` 類別套用到正確的錨點連結上，並將 `ariaCurrentWhenActive` 設定為 `page`。

如果你需要在單一元素上加入多個類別，你可以使用以空格分隔的字串，或使用陣列：

```html

<a routerLink="/user/bob" routerLinkActive="class1 class2">Bob</a>

<a routerLink="/user/bob" [routerLinkActive]="['class1', 'class2']">Bob</a>
```

只設定 `routerLinkActive` 並不會設定 `aria-current`。請如上例所示設定 `ariaCurrentWhenActive` 輸入，讓視覺障礙使用者（他們可能無法察覺所套用的不同樣式）也能辨識出目前啟用的連結。

### 路由比對策略

在預設情況下，`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

如果你只想在精確相符時才套用該類別，你需要為 `routerLinkActiveOptions` 指令提供一個設定物件，其中包含 `exact: true` 這個值。

```html
<a
  [routerLink]="['/user/jane']"
  routerLinkActive="active-link"
  [routerLinkActiveOptions]="{exact: true}"
>
  User
</a>
<a
  [routerLink]="['/user/jane/role/admin']"
  routerLinkActive="active-link"
  [routerLinkActiveOptions]="{exact: true}"
>
  Role
</a>
```

如果你想更精確地控制路由的比對方式，值得注意的是，`exact: true` 其實是整套比對選項的語法糖衣：

```typescript
// `exact: true` is equivalent to
{
  paths: 'exact',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'exact',
}

// `exact: false` is equivalent
{
  paths: 'subset',
  fragment: 'ignored',
  matrixParams: 'ignored',
  queryParams: 'subset',
}
```

如需更多資訊，請參閱 [isActiveMatchOptions 的官方文件](/api/router/IsActiveMatchOptions)。

### 將 RouterLinkActive 套用到祖先元素上

RouterLinkActive 指令也可以套用到祖先元素上，讓開發者能隨心所欲地為其中的元素套用樣式。

```html
<div routerLinkActive="active-link" [routerLinkActiveOptions]="{exact: true}">
  <a routerLink="/user/jim">Jim</a>
  <a routerLink="/user/bob">Bob</a>
</div>
```

如需更多資訊，請參閱 [RouterLinkActive 的 API 文件](/api/router/RouterLinkActive)。

## 檢查某個 URL 是否處於啟用狀態 {#check-if-a-url-is-active}

`isActive` 函式會回傳一個 computed 訊號，用來追蹤給定的 URL 目前在 Router 中是否處於啟用狀態。隨著 Router 狀態的變化，這個訊號會自動更新。

```typescript
import {Component, inject} from '@angular/core';
import {isActive, Router} from '@angular/router';

@Component({
  template: `
    <div [class.active]="isSettingsActive()">
      <h2>Settings</h2>
    </div>
  `,
})
export class Panel {
  private router = inject(Router);

isSettingsActive = isActive('/settings', this.router, {
    paths: 'subset',
    queryParams: 'ignored',
    fragment: 'ignored',
    matrixParams: 'ignored',
  });
}
```
# 其他常見的路由任務

本指南涵蓋在應用程式中使用 Angular 路由時的其他一些常見任務。

## 取得路由資訊 {#getting-route-information}

使用者在應用程式中導覽時，你常會想把資訊從一個元件傳遞到另一個元件。
例如，假設有一個顯示雜貨購物清單的應用程式。
清單中的每個項目都有唯一的 `id`。
若要編輯某個項目，使用者會點選 Edit 按鈕，開啟 `EditGroceryItem` 元件。
你希望這個元件能取得該雜貨項目的 `id`，以便向使用者顯示正確的資訊。

可以使用路由把這類資訊傳遞給應用程式的元件。
做法是搭配 `provideRouter` 使用 `withComponentInputBinding` 功能，或使用 `RouterModule.forRoot` 的 `bindToComponentInputs` 選項。

若要從路由取得資訊：

<docs-workflow>

<docs-step title="加入 `withComponentInputBinding`">

把 `withComponentInputBinding` 功能加入 `provideRouter` 方法。

```ts
providers: [provideRouter(appRoutes, withComponentInputBinding())];
```

</docs-step>

<docs-step title="為元件加入 `input`">

更新元件，讓它有一個名稱與參數相符的 `input()` 屬性。

```ts
id = input.required<string>();
hero = computed(() => this.service.getHero(this.id()));
```

</docs-step>
<docs-step title="選用：使用預設值">
當 `withComponentInputBinding` 啟用時，路由會依據目前的路由，把值指派給所有輸入。
若沒有路由資料符合輸入的鍵，路由會指派 `undefined`，例如選用的查詢參數缺失時。
當輸入有可能無法被路由比對到時，應在 `input` 的型別中包含 `undefined`。

你可以透過在輸入上使用 `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: 你可以把所有以鍵值對表示的路由資料繫結到元件輸入：路由資源、靜態或已解析的路由資料、路徑參數、矩陣參數與查詢參數。

### 輸入繫結的優先順序

當多個路由來源定義了相同的鍵時，路由會以下列優先順序（由高到低）解決衝突：

1. **路由資源**：在路由的 `resources` 對應表中定義的值。阻擋型資源繫結其解包後的值（`resource.value()`），非阻擋型資源則繫結 `Resource` 實例。
2. **路由資料與解析器**：在 `data` 中定義的靜態資料，或透過 `resolve` 解析的值。
3. **路徑參數與矩陣參數**：來自 URL 路徑的參數（例如 `:id`）與矩陣參數。
4. **查詢參數**：來自查詢字串的參數（例如 `?id=123`）。

例如，若一條路由同時有路徑參數 `:id` 與查詢參數 `?id=...`，路徑參數的值會繫結到元件的 `id` 輸入。若該路由還定義了名為 `id` 的資源，資源的值優先於兩者。

### 停用查詢參數繫結 {#disable-query-parameter-binding}

若你另外管理查詢參數，可使用 `ComponentInputBindingOptions` 停用查詢參數繫結：

```ts
provideRouter(appRoutes, withComponentInputBinding({queryParams: false}));
```

### 設定路由資料中沒有對應輸入時的行為

預設情況下，若某個輸入在導覽期間無法從路由資料取得，路由會把該輸入設為 `undefined`。這可確保不會保留過時的資料。

若你想避免為在作用中的元件實例上從未出現在路由資料中的輸入設定 `undefined`，可把 `unmatchedInputBehavior` 選項設為 `'undefinedIfStale'`：

```ts
provideRouter(appRoutes, withComponentInputBinding({unmatchedInputBehavior: 'undefinedIfStale'}));
```

當你把 `unmatchedInputBehavior: 'undefinedIfStale'` 與 `queryParams: false` 組合使用時，輸入會保留其初始值，除非路由明確提供。唯一的例外是矩陣參數：若矩陣參數在一次導覽中提供、卻在後續導覽中被移除，路由會把該輸入設為 `undefined`，以避免保留過時資料。

```ts
provideRouter(
  appRoutes,
  withComponentInputBinding({
    queryParams: false,
    unmatchedInputBehavior: 'undefinedIfStale',
  }),
);
```

### 繼承父路由資料

預設情況下，子路由會繼承父路由的參數與資料（等同於 `paramsInheritanceStrategy: 'always'`）。這表示你可以直接在子元件中存取父路由的資訊。

若你需要還原舊有行為（參數只從空路徑路由繼承），可把 `paramsInheritanceStrategy` 設為 `'emptyOnly'`：

```ts
provideRouter(routes, withRouterConfig({paramsInheritanceStrategy: 'emptyOnly'}));
```

其他可用設定的詳細資訊，請參閱[路由設定選項](guide/routing/customizing-route-behavior#router-configuration-options)。

## 顯示 404 頁面 {#displaying-a-404-page}

若要顯示 404 頁面，請設定一條[萬用字元路由](guide/routing/define-routes#wildcards)，把它的 `component` 屬性設為你想用作 404 頁面的元件，如下所示：

```ts
const routes: Routes = [
  {path: 'first-component', component: First},
  {path: 'second-component', component: Second},
  {path: '**', component: PageNotFound}, // Wildcard route for a 404 page
];
```

最後一條 `path` 為 `**` 的路由是萬用字元路由。
若請求的 URL 與清單中較前面的任何路徑都不符，路由會選取這條路由，並把使用者送往 `PageNotFound`。

## 連結參數陣列

連結參數陣列包含路由導覽所需的下列要素：

- 通往目標元件的路由路徑
- 進入路由 URL 的必要與選用路由參數

把 `RouterLink` 指令繫結到這樣的陣列，如下所示：

```html
<a [routerLink]="['/heroes']">Heroes</a>
```

以下是在指定路由參數時包含兩個元素的陣列：

```html
<a [routerLink]="['/hero', hero.id]">
  <span class="badge">{{ hero.id }}</span
  >{{ hero.name }}
</a>
```

在物件中提供選用的路由參數，如 `{ foo: 'foo' }`：

```html
<a [routerLink]="['/crisis-center', {foo: 'foo'}]">Crisis Center</a>
```

這種語法傳遞的是矩陣參數，也就是與特定 URL 區段相關聯的選用參數。深入瞭解[矩陣參數](/guide/routing/read-route-state#matrix-parameters)。

這三個範例涵蓋了只有一層路由的應用程式的需求。
不過，若有子路由（例如危機中心），就會產生新的連結陣列可能性。

下列極簡的 `RouterLink` 範例，以危機中心指定的預設子路由為基礎。

```html
<a [routerLink]="['/crisis-center']">Crisis Center</a>
```

請檢視下列事項：

- 陣列的第一個項目識別父路由 $`/crisis-center`$
- 此父路由沒有參數
- 子路由沒有預設值，所以你需要挑選一個
- 你要導覽到 `CrisisList`，其路由路徑是 `/`，但你不需要明確加上斜線

考慮下列路由連結：它從應用程式的根目錄一路導覽到 Dragon Crisis：

```html
<a [routerLink]="['/crisis-center', 1]">Dragon Crisis</a>
```

- 陣列的第一個項目識別父路由 $`/crisis-center`$
- 此父路由沒有參數
- 第二個項目識別特定危機的子路由詳細資訊 $`/:id`$
- 該詳細資訊子路由需要一個 `id` 路由參數
- 你把 Dragon Crisis 的 `id` 作為陣列的第二個項目加入 $`1`$
- 產生的路徑是 `/crisis-center/1`

你也可以只用 Crisis Center 路由重新定義 `App` 範本：

```typescript
@Component({
  template: `
    <h1 class="title">Angular Router</h1>
    <nav>
      <a [routerLink]="['/crisis-center']">Crisis Center</a>
      <a [routerLink]="['/crisis-center/1', {foo: 'foo'}]">Dragon Crisis</a>
      <a [routerLink]="['/crisis-center/2']">Shark Crisis</a>
    </nav>
    <router-outlet />
  `,
})
export class App {}
```

總之，你可以撰寫具有一層、兩層或更多層路由的應用程式。
連結參數陣列提供了足夠的彈性，可以表示任意路由深度，以及任意合法的路由路徑、（必要的）路由參數與（選用的）路由參數物件序列。

## `LocationStrategy` 與瀏覽器 URL 樣式 {#locationstrategy-and-browser-url-styles}

當路由導覽到新的元件檢視時，它會以該檢視的 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，與原本需要載入頁面才得到的 URL 無法區分。

以下是這種「HTML5 pushState」樣式的 Crisis Center URL：

```text
localhost:3002/crisis-center
```

較舊的瀏覽器在位置 URL 變更時會向伺服器送出頁面請求，除非變更發生在 "#" 之後（稱為「hash」）。
路由可以利用這個例外，以 hash 組出應用程式內的路由 URL。
以下是一個導向 Crisis Center 的「hash URL」。

```text
localhost:3002/src/#/crisis-center
```

路由透過兩個 `LocationStrategy` 提供者支援這兩種樣式：

`RouterModule.forRoot()` 函式把 `LocationStrategy` 設為 `PathLocationStrategy`，使它成為預設策略。
你也可以在引導過程中透過覆寫，切換到 `HashLocationStrategy`。

HELPFUL: 如需深入瞭解提供者與引導程序，請參閱[依賴注入](guide/di/defining-dependency-providers)。
# 建立自訂路由比對

Angular Router 支援強大的比對策略，協助使用者在你的應用程式中導覽。
這套比對策略支援靜態路由、帶參數的可變路由、萬用字元路由等。
你也可以為 URL 較複雜的情境，建立自己的自訂模式比對。

在本教學中，你將使用 Angular 的 `UrlMatcher` 建立自訂路由比對器。
這個比對器會在 URL 中尋找 X（前身為 Twitter）帳號名稱。

## 目標

實作 Angular 的 `UrlMatcher`，建立自訂路由比對器。

## 建立範例應用程式

使用 Angular CLI 建立一個新應用程式 _angular-custom-route-match_。
除了預設的 Angular 應用程式框架外，你還會建立一個 _profile_ 元件。

1. 建立一個新的 Angular 專案 _angular-custom-route-match_。

```shell
ng new angular-custom-route-match
   ```

當畫面提示 `Would you like to add Angular routing?` 時，選取 `Y`。

當畫面提示 `Which stylesheet format would you like to use?` 時，選取 `CSS`。

稍待片刻，新專案 `angular-custom-route-match` 就準備好了。

1. 在終端機中，切換到 `angular-custom-route-match` 目錄。
1. 建立一個元件 _profile_。

```shell
ng generate component profile
   ```

1. 在程式碼編輯器中，找到 `profile.html` 檔案，把預留內容換成下列 HTML。

<docs-code header="profile.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/profile/profile.html"/>

1. 在程式碼編輯器中，找到 `app.html` 檔案，把預留內容換成下列 HTML。

<docs-code header="app.html" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.html"/>

## 為應用程式設定路由

應用程式框架就緒後，接下來你需要把路由功能加入 `app.config.ts` 檔案。
在這個過程中，你將建立一個自訂 URL 比對器，在 URL 中尋找 X 帳號名稱。
帳號名稱前面會帶有 `@` 符號。

1. 在程式碼編輯器中，開啟 `app.config.ts` 檔案。
1. 加入 Angular 的 `provideRouter` 與 `withComponentInputBinding` 以及應用程式路由的 `import` 陳述式。

```ts
import {provideRouter, withComponentInputBinding} from '@angular/router';

import {routes} from './app.routes';
   ```

1. 在 providers 陣列中，加入 `provideRouter(routes, withComponentInputBinding())` 陳述式。

1. 把下列程式碼加入應用程式路由，定義自訂路由比對器。

<docs-code header="app.routes.ts" path="adev/src/content/examples/routing-with-urlmatcher/src/app/app.routes.ts" region="matcher"/>

這個自訂比對器是一個函式，負責以下工作：

- 確認陣列中只有一個區段
- 使用正規表示式確認使用者名稱的格式符合
- 若符合，函式傳回整個 URL，並把路徑的子字串定義為 `username` 路由參數
- 若不符合，函式傳回 null，路由器繼續尋找其他符合該 URL 的路由

HELPFUL: 自訂 URL 比對器的行為與其他路由定義相同。定義子路由或延遲載入路由的方式，都與一般路由無異。

## 讀取路由參數

自訂比對器就緒後，你現在可以在 `profile` 元件中繫結路由參數。

在程式碼編輯器中，開啟 `profile.ts` 檔案，建立一個與 `username` 參數對應的 `input`。
我們先前已在 `provideRouter` 中加入 `withComponentInputBinding` 功能。
這讓 `Router` 能把資訊直接繫結到路由元件。

```ts
username = input.required<string>();
```

## 測試自訂 URL 比對器

程式碼就緒後，你現在可以測試自訂 URL 比對器了。

1. 在終端機視窗中，執行 `ng serve` 指令。

```shell
ng serve
   ```

1. 在瀏覽器開啟 `http://localhost:4200`。

你應該會看到一個只有一句話的網頁，內容是 `Navigate to my profile`。

1. 點選 **my profile** 超連結。

頁面上會出現一句新的話：`Hello, Angular!`。

## 後續步驟

Angular Router 的模式比對，讓你的應用程式在處理動態 URL 時擁有很大的彈性。
若要深入了解 Angular Router，請參閱下列主題：
HELPFUL: 本內容改編自 [Brandon Roberts](https://x.com/brandontroberts) 所撰寫的 [Custom Route Matching with the Angular Router](https://medium.com/@brandontroberts/custom-route-matching-with-the-angular-router-fbdd48665483)。
# 伺服器端與混合渲染

Angular 預設將所有應用程式以用戶端渲染（CSR）的方式交付。雖然這種做法的初始負載較輕量，但它帶來一些取捨，包括載入時間較慢、效能指標較差，以及資源需求較高，因為大部分運算都由使用者的裝置執行。因此，許多應用程式透過將伺服器端渲染（SSR）納入混合渲染策略，獲得了顯著的效能提升。

## 什麼是混合渲染？

混合渲染讓開發者能善用伺服器端渲染（SSR）、預先渲染（也稱為「靜態網站生成」或 SSG）與用戶端渲染（CSR）的優點，來最佳化你的 Angular 應用程式。它讓你能細緻地控制應用程式不同部分的渲染方式，為使用者提供最佳體驗。

## 設定混合渲染

你可以在使用 Angular CLI 的 `ng new` 指令時加上伺服器端渲染旗標（即 `--ssr`），來建立一個採用混合渲染的**新**專案：

```shell
ng new --ssr
```

你也可以用 `ng add` 指令為既有專案加入伺服器端渲染，來啟用混合渲染：

```shell
ng add @angular/ssr
```

NOTE: 預設情況下，Angular 會預先渲染你的整個應用程式，並產生一個伺服器檔案。若要停用此行為並建立完全靜態的應用程式，請將 `outputMode` 設為 `static`。若要啟用 SSR，請更新伺服器路由以使用 `RenderMode.Server`。詳情請參閱 [`Server routing`](#server-routing) 與 [`Generate a fully static application`](#generate-a-fully-static-application)。

## 伺服器路由 {#server-routing}

### 設定伺服器路由

你可以宣告一個由 [`ServerRoute`](api/ssr/ServerRoute 'API reference') 物件組成的陣列，來建立伺服器路由設定。這個設定通常放在名為 `app.routes.server.ts` 的檔案中。

```typescript
{header: "app.routes.server.ts"}
import {RenderMode, ServerRoute} from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: '', // This renders the "/" route on the client (CSR)
    renderMode: RenderMode.Client,
  },
  {
    path: 'about', // This page is static, so we prerender it (SSG)
    renderMode: RenderMode.Prerender,
  },
  {
    path: 'profile', // This page requires user-specific data, so we use SSR
    renderMode: RenderMode.Server,
  },
  {
    path: '**', // All other routes will be rendered on the server (SSR)
    renderMode: RenderMode.Server,
  },
];
```

你可以使用 [`withRoutes`](api/ssr/withRoutes 'API reference') 函式，透過 [`provideServerRendering`](api/ssr/provideServerRendering 'API reference') 將這個設定加入你的應用程式：

```typescript
{header: "app.config.server.ts"}
import {provideServerRendering, withRoutes} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {serverRoutes} from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes)),
    // ... other providers ...
  ],
};
```

使用 [App shell 模式](ecosystem/service-workers/app-shell)時，你必須指定用來作為用戶端渲染路由 app shell 的元件。要做到這一點，請使用 [`withAppShell`](api/ssr/withAppShell 'API reference') 功能：

```typescript
import {provideServerRendering, withRoutes, withAppShell} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {AppShell} from './app-shell';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(withRoutes(serverRoutes), withAppShell(AppShell)),
    // ... other providers ...
  ],
};
```

### 渲染模式

伺服器路由設定讓你可以透過設定 [`RenderMode`](api/ssr/RenderMode 'API reference')，來指定應用程式中每條路由應該如何渲染：

| Rendering mode      | 說明                                                                                                 |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Server (SSR)**    | 針對每個請求在伺服器上渲染應用程式，並將內容完整的 HTML 頁面傳送給瀏覽器。 |
| **Client (CSR)**    | 在瀏覽器中渲染應用程式。這是 Angular 的預設行為。                               |
| **Prerender (SSG)** | 在建置時預先渲染應用程式，為每條路由產生靜態 HTML 檔案。                      |

#### 選擇渲染模式

每種渲染模式都有不同的優點與缺點。你可以依應用程式的具體需求選擇渲染模式。

##### 用戶端渲染（CSR）

用戶端渲染的開發模型最簡單，因為你可以假設程式碼總是在網頁瀏覽器中執行來撰寫它。這讓你能使用各種同樣假設自己在瀏覽器中執行的用戶端函式庫。

用戶端渲染的效能通常比其他渲染模式差，因為它必須先下載、解析並執行頁面的 JavaScript，使用者才能看到任何渲染出的內容。如果你的頁面在渲染時還要從伺服器擷取更多資料，使用者還必須等待這些額外請求完成，才能看到完整內容。

如果你的頁面會被搜尋爬蟲建立索引，用戶端渲染可能對搜尋引擎最佳化（SEO）產生負面影響，因為搜尋爬蟲在索引頁面時能執行的 JavaScript 量有其限制。

採用用戶端渲染時，伺服器除了提供靜態 JavaScript 資源外，不需要做任何渲染頁面的工作。如果伺服器成本是考量因素，你可以將這一點納入評估。

支援可安裝、離線體驗並搭配 [service workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) 的應用程式，可以仰賴用戶端渲染，而不需要與伺服器通訊。

##### 伺服器端渲染（SSR）

伺服器端渲染的頁面載入速度比用戶端渲染快。伺服器在收到瀏覽器的請求後會直接渲染 HTML 文件，不需要等待 JavaScript 下載並執行。使用者只需經歷伺服器擷取資料並渲染所請求頁面所需的延遲。這種模式也省去了瀏覽器發出額外網路請求的需要，因為你的程式碼可以在伺服器上渲染時擷取資料。

伺服器端渲染通常有出色的搜尋引擎最佳化（SEO）表現，因為搜尋爬蟲收到的是完整渲染的 HTML 文件。

伺服器端渲染要求你撰寫不嚴格依賴瀏覽器 API 的程式碼，也限制了你對那些假設自己在瀏覽器中執行的 JavaScript 函式庫的選擇。

採用伺服器端渲染時，你的伺服器會為每個請求執行 Angular 來產生 HTML 回應，這可能增加伺服器託管成本。

##### 建置時預先渲染

預先渲染的頁面載入速度比用戶端渲染和伺服器端渲染都快。因為預先渲染是在_建置時_建立 HTML 文件，伺服器可以直接以靜態 HTML 文件回應請求，不需要任何額外工作。

預先渲染要求渲染頁面所需的所有資訊在_建置時_都已備齊。這表示預先渲染的頁面不能包含針對載入頁面的特定使用者的任何資料。預先渲染主要適用於對應用程式所有使用者都相同的頁面。

因為預先渲染發生在建置時，它可能大幅增加正式建置的時間。使用 [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') 產生大量 HTML 文件，可能影響部署的總檔案大小，進而導致部署變慢。

預先渲染通常有出色的搜尋引擎最佳化（SEO）表現，因為搜尋爬蟲收到的是完整渲染的 HTML 文件。

預先渲染要求你撰寫不嚴格依賴瀏覽器 API 的程式碼，也限制了你對那些假設自己在瀏覽器中執行的 JavaScript 函式庫的選擇。

預先渲染對每個伺服器請求產生的額外負擔極低，因為你的伺服器是以靜態 HTML 文件回應。靜態檔案也很容易被內容傳遞網路（CDN）、瀏覽器與中間快取層快取，讓後續的頁面載入更快。完全靜態的網站也可以僅透過 CDN 或靜態檔案伺服器部署，不需要為你的應用程式維護自訂的伺服器執行環境。這能將工作從應用程式的 Web 伺服器卸載，從而提升可擴展性，對高流量應用程式特別有益。

NOTE: 使用 Angular service worker 時，第一個請求由伺服器渲染，但後續所有請求都由 service worker 處理並在用戶端渲染。

### 設定標頭與狀態碼

你可以使用 `ServerRoute` 設定中的 `headers` 與 `status` 屬性，為個別伺服器路由設定自訂標頭與狀態碼。

```typescript
{header: "app.routes.server.ts"}
import {RenderMode, ServerRoute} from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'profile',
    renderMode: RenderMode.Server,
    headers: {
      'X-My-Custom-Header': 'some-value',
    },
    status: 201,
  },
  // ... other routes
];
```

### 重新導向

對於路由設定中以 [`redirectTo`](api/router/Route#redirectTo 'API reference') 屬性指定的重新導向，Angular 在伺服器端的處理方式有所不同。

**伺服器端渲染（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') 時，你可以指定數個設定選項，來自訂預先渲染與提供的流程。

#### 參數化路由

對於每條使用 [`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') 函式來注入依賴，並執行任何用來決定要預先渲染哪些路由的工作。這通常包括發出請求來擷取資料，以建構參數值陣列。

你也可以將這個函式用於 catch-all 路由（例如 `/**`），其中參數名稱會是 `"**"`，傳回值會是路徑的區段，例如 `foo/bar`。這些可以與其他參數結合（例如 `/post/:id/**`），以處理更複雜的路由設定。

```ts
{header: "app.routes.server.ts"}
import {RenderMode, ServerRoute} from '@angular/ssr';
import {inject} from '@angular/core';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'post/:id',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      const dataService = inject(PostService);
      const ids = await dataService.getIds(); // Assuming this returns ['1', '2', '3']

return ids.map((id) => ({id})); // Generates paths like: /post/1, /post/2, /post/3
    },
  },
  {
    path: 'post/:id/**',
    renderMode: RenderMode.Prerender,
    async getPrerenderParams() {
      return [
        {id: '1', '**': 'foo/3'},
        {id: '2', '**': 'bar/4'},
      ]; // Generates paths like: /post/1/foo/3, /post/2/bar/4
    },
  },
];
```

由於 [`getPrerenderParams`](api/ssr/ServerRoutePrerenderWithParams#getPrerenderParams 'API reference') 專門適用於 [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference')，這個函式總是在_建置時_執行。`getPrerenderParams` 不得依賴任何瀏覽器專屬或伺服器專屬的 API 來取得資料。

IMPORTANT: 在 `getPrerenderParams` 內使用 [`inject`](api/core/inject 'API reference') 時，請記住 `inject` 必須以同步方式使用。它不能在非同步回呼中、或在任何 `await` 陳述式之後被呼叫。更多資訊請參閱 `runInInjectionContext`。

#### 後備策略

使用 [`RenderMode.Prerender`](api/ssr/RenderMode#Prerender 'API reference') 模式時，你可以指定一個後備策略，來處理尚未預先渲染之路徑的請求。

可用的後備策略有：

- **Server**：後備為伺服器端渲染。如果沒有指定 `fallback` 屬性，這就是**預設**行為。
- **Client**：後備為用戶端渲染。
- **None**：不做後備。Angular 不會處理未預先渲染之路徑的請求。

```ts
{header: "app.routes.server.ts"}
import {RenderMode, PrerenderFallback, ServerRoute} from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  {
    path: 'post/:id',
    renderMode: RenderMode.Prerender,
    fallback: PrerenderFallback.Client, // Fallback to CSR if not prerendered
    async getPrerenderParams() {
      // This function returns an array of objects representing prerendered posts at the paths:
      // `/post/1`, `/post/2`, and `/post/3`.
      // The path `/post/4` will utilize the fallback behavior if it's requested.
      return [{id: '1'}, {id: '2'}, {id: '3'}];
    },
  },
];
```

## 撰寫與伺服器相容的元件 {#authoring-server-compatible-components}

某些常見的瀏覽器 API 與功能在伺服器上可能無法使用。應用程式無法使用 `window`、`document`、`navigator` 或 `location` 等瀏覽器專屬的全域物件，以及 `HTMLElement` 的某些屬性。

一般而言，依賴瀏覽器專屬符號的程式碼應該只在瀏覽器中執行，不要在伺服器上執行。這可以透過 `afterEveryRender` 與 `afterNextRender` 生命週期鉤子來強制達成。這些鉤子只在瀏覽器中執行，在伺服器上會被略過。

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

@Component({
  selector: 'my-cmp',
  template: `<span #content>{{ ... }}</span>`,
})
export class MyComponent {
  contentRef = viewChild.required<ElementRef>('content');

constructor() {
    afterNextRender(() => {
      // Safe to check `scrollHeight` because this will only run in the browser, not the server.
      console.log('content height: ' + this.contentRef().nativeElement.scrollHeight);
    });
  }
}
```

NOTE: 請優先使用[平台專屬的提供者](guide/ssr#providing-platform-specific-implementations)，而不是以 `isPlatformBrowser` 或 `isPlatformServer` 做執行階段檢查。

IMPORTANT: 避免在範本中使用 `isPlatformBrowser` 搭配 `@if` 或其他條件式，來在伺服器與用戶端渲染不同內容。這會造成水合不一致與版面位移，對使用者體驗與 [Core Web Vitals](https://web.dev/learn-core-web-vitals/) 產生負面影響。請改用 `afterNextRender` 進行瀏覽器專屬的初始化，並讓渲染出的內容在各平台上保持一致。

## 在伺服器上設定提供者

在伺服器端，頂層提供者的值會在應用程式程式碼初次解析與求值時設定一次。
這表示以 `useValue` 設定的提供者會在多個請求之間保持其值，直到伺服器應用程式重新啟動為止。

如果你想為每個請求產生新值，請使用帶有 `useFactory` 的工廠提供者。工廠函式會為每個傳入的請求執行，確保每次都建立新值並指派給該 token。

## 提供平台專屬的實作 {#providing-platform-specific-implementations}

當你的應用程式在瀏覽器與伺服器上需要不同行為時，請為每個平台提供分開的服務實作。這種做法能把平台邏輯集中在專屬的服務中。

```ts
export abstract class AnalyticsService {
  abstract trackEvent(name: string): void;
}
```

建立瀏覽器端的實作：

```ts
@Injectable()
export class BrowserAnalyticsService implements AnalyticsService {
  trackEvent(name: string): void {
    // Sends the event to the browser-based third-party analytics provider
  }
}
```

建立伺服器端的實作：

```ts
@Injectable()
export class ServerAnalyticsService implements AnalyticsService {
  trackEvent(name: string): void {
    // Records the event on the server
  }
}
```

在你的主應用程式設定中註冊瀏覽器端的實作：

```ts
{header: "app.config.ts"}
export const appConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: BrowserAnalyticsService}],
};
```

在你的伺服器設定中以伺服器端的實作覆寫：

```ts
{header: "app.config.server.ts"}
const serverConfig: ApplicationConfig = {
  providers: [{provide: AnalyticsService, useClass: ServerAnalyticsService}],
};
```

在你的元件中注入並使用該服務：

```ts
@Component(/* ... */)
export class Checkout {
  private analytics = inject(AnalyticsService);

onAction() {
    this.analytics.trackEvent('action');
  }
}
```

## 透過 DI 存取 Document {#accessing-document-via-di}

在使用伺服器端渲染時，你應該避免直接參考 `document` 等瀏覽器專屬的全域變數。請改用 [`DOCUMENT`](api/core/DOCUMENT) token，以與平台無關的方式存取 document 物件。

```ts
import {inject, DOCUMENT, Service} from '@angular/core';

@Service()
export class CanonicalLinkService {
  private readonly document = inject(DOCUMENT);

// During server rendering, inject a <link rel="canonical"> tag
  // so the generated HTML includes the correct canonical URL
  setCanonical(href: string): void {
    const link = this.document.createElement('link');
    link.rel = 'canonical';
    link.href = href;
    this.document.head.appendChild(link);
  }
}
```

HELPFUL: 對於管理 meta 標籤，Angular 提供了 `Meta` 服務。

## 透過 DI 存取 Request 與 Response {#accessing-request-and-response-via-di}

`@angular/core` 套件提供數個用來與伺服器端渲染環境互動的 token。這些 token 讓你在 SSR 期間能存取 Angular 應用程式中的關鍵資訊與物件。

- **[`REQUEST`](api/core/REQUEST 'API reference')**：提供對目前請求物件的存取，該物件的型別是 Web API 的 [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)。這讓你能存取標頭、cookies 與其他請求資訊。
- **[`RESPONSE_INIT`](api/core/RESPONSE_INIT 'API reference')**：提供對回應初始化選項的存取，該選項的型別是 Web API 的 [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#parameters)。這讓你能動態設定回應的標頭與狀態碼。當標頭或狀態碼需要在執行階段決定時，請使用這個 token。
- **[`REQUEST_CONTEXT`](api/core/REQUEST_CONTEXT 'API reference')**：提供對目前請求相關額外上下文的存取。這個上下文可以作為 [`handle`](api/ssr/AngularAppEngine#handle 'API reference') 函式的第二個參數傳入。通常用來提供不屬於標準 Web API 的額外請求相關資訊。

```typescript
import {inject, REQUEST, Component} from '@angular/core';

@Component({
  selector: 'app-my-component',
  template: `<h1>My Component</h1>`,
})
export class MyComponent {
  constructor() {
    const request = inject(REQUEST);
    console.log(request?.url);
  }
}
```

IMPORTANT: 上述 token 在以下情境中會是 `null`：<ul class="docs-list">
  <li>在建置過程中。</li>
  <li>當應用程式在瀏覽器中渲染（CSR）時。</li>
  <li>執行靜態網站生成（SSG）時。</li>
  <li>在開發期間的路由擷取過程中（於請求當下）。</li>
</ul>

## 產生完全靜態的應用程式 {#generate-a-fully-static-application}

預設情況下，Angular 會預先渲染你的整個應用程式，並產生一個用來處理請求的伺服器檔案。這讓你的應用程式能把預先渲染好的內容提供給使用者。然而，如果你偏好沒有伺服器的完全靜態網站，可以在 `angular.json` 設定檔中將 `outputMode` 設為 `static`，來退出這個行為。

當 `outputMode` 設為 `static` 時，Angular 會在建置時為每條路由產生預先渲染的 HTML 檔案，但不會產生伺服器檔案，也不需要 Node.js 伺服器來提供應用程式。這在部署到不需要後端伺服器的靜態託管服務時很有用。

要進行此設定，請如下更新你的 `angular.json` 檔案：

```json
{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "options": {
            "outputMode": "static"
          }
        }
      }
    }
  }
}
```

### 預先渲染檔案的輸出格式

`prerender` 選項的 `format` 屬性控制 Angular 為每條預先渲染路由寫出的檔案結構。以路徑為 `about` 的路由為例：

| `format`              | 預先渲染的檔案   |
| --------------------- | ------------------ |
| `directory` (default) | `about/index.html` |
| `file`                | `about.html`       |

依你的靜態託管服務而定，如果主機要求以 `<route>.html` 檔案來提供路由、而不重新導向到尾隨斜線，你可以將 `format` 設為 `"file"`。

```json
{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "options": {
            "outputMode": "static",
            "prerender": {
              "format": "file"
            }
          }
        }
      }
    }
  }
}
```

NOTE: `format` 選項只有在建置不產生伺服器時才會被考量。

## 使用 HttpClient 時快取資料 {#caching-data-when-using-httpclient}

`HttpClient` 在伺服器上執行時會快取對外發出的網路請求。這些資訊會被序列化，並作為伺服器傳送的初始 HTML 的一部分傳給瀏覽器。在瀏覽器中，`HttpClient` 會檢查快取中是否有資料，若有，就在應用程式初始渲染期間重用它，而不發出新的 HTTP 請求。一旦應用程式在瀏覽器中執行時變得[穩定](api/core/ApplicationRef#isStable)，`HttpClient` 就會停止使用快取。

### 設定回應主體大小上限 {#configuring-the-response-body-size-limit}

當 `HttpClient` 在伺服器端渲染期間使用預設的 fetch 後端時，Angular 會將每個回應主體限制為 1 MB。這個限制可防止伺服器在渲染期間緩衝意外過大的回應。如果回應超過設定的上限，請求會失敗並產生 [NG02825](errors/NG02825) 錯誤。

如果你的應用程式需要在伺服器渲染期間擷取更大的回應，請在 `provideServerRendering` 選項中設定 `maxResponseBodySize`：

```ts
import {provideServerRendering, withRoutes} from '@angular/ssr';
import {ApplicationConfig} from '@angular/core';
import {serverRoutes} from './app.routes.server';

const serverConfig: ApplicationConfig = {
  providers: [
    provideServerRendering(
      {
        maxResponseBodySize: 5 * 1024 * 1024, // 5MB
      },
      withRoutes(serverRoutes),
    ),
  ],
};
```

`maxResponseBodySize` 以位元組為單位設定，並全域套用到伺服器端使用 fetch 後端的 `HttpClient` 請求。

IMPORTANT: 請把這個上限保持在你的應用程式所能允許的最小值。提高它會讓伺服器端請求緩衝更大的回應主體，可能增加記憶體用量與阻斷服務攻擊的風險。請優先把大型下載移到伺服器渲染之外處理。

CRITICAL: 在 SSR 期間，Fetch 實作會依照 [Fetch 標準](https://fetch.spec.whatwg.org/#concept-main-fetch) 的要求，在傳回回應之前讀取整個回應主體來驗證 `integrity`。Angular 只在 Fetch 傳回回應之後才強制執行 [`maxResponseBodySize`](/guide/ssr#configuring-the-response-body-size-limit)，因此這個上限並不限制完整性驗證期間所緩衝的資料。

### 設定快取選項 {#configuring-the-caching-options}

你可以透過設定 `HttpTransferCacheOptions`，來自訂 Angular 在伺服器端渲染（SSR）期間如何快取 HTTP 回應，以及在水合期間如何重用它們。  
這個設定是透過在 `provideClientHydration()` 內使用 `withHttpTransferCacheOptions` 全域提供的。

預設情況下，`HttpClient` 會快取所有不含 `Authorization`、`Proxy-Authorization` 或 `Cookie` 標頭、且不是以可傳送憑證的 `withCredentials` 或 Fetch API `credentials` 模式送出的 `HEAD`、`QUERY` 與 `GET` 請求。當請求或回應包含禁止快取的 `Cache-Control` 指令（`no-store`、`no-cache` 或 `private`），或 Fetch API 的 `cache` 選項設為 `no-store` 或 `no-cache` 時，Angular 也會跳過傳輸快取。帶有 `Set-Cookie` 標頭的回應同樣會被跳過。你可以在水合設定中使用 `withHttpTransferCacheOptions` 來覆寫請求篩選設定。

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        includeHeaders: ['ETag', 'Cache-Control'],
        filter: (req) => !req.url.includes('/api/profile'),
        includePostRequests: true,
        includeRequestsWithAuthHeaders: false,
      }),
    ),
  ],
});
```

### `includeHeaders`

指定伺服器回應中哪些標頭應該包含在快取項目裡。  
預設不包含任何標頭。

```ts
withHttpTransferCacheOptions({
  includeHeaders: ['ETag', 'Cache-Control'],
});
```

IMPORTANT: 避免包含驗證 token 等敏感標頭。這些標頭可能會在請求之間洩漏使用者專屬資料。

在 `includeHeaders` 中包含 `Cache-Control`，只是讓該標頭能在水合後的回應上使用。Angular 在決定請求或回應是否符合傳輸快取資格時，本來就會自動評估 `Cache-Control` 標頭。

### `includePostRequests`

預設情況下，只有 `GET`、`QUERY` 與 `HEAD` 請求會被快取。  
當 `POST` 請求被用作讀取操作（例如 GraphQL 查詢）時，你可以為它們啟用快取。

```ts
withHttpTransferCacheOptions({
  includePostRequests: true,
});
```

只有當 `POST` 請求具**冪等性**，且在伺服器與用戶端渲染之間重用是安全的，才使用此設定。

### `includeRequestsWithAuthHeaders`

決定包含 `Authorization`、`Proxy-Authorization` 或 `Cookie` 標頭的請求是否符合快取資格。  
預設情況下，這些請求會被排除，以防止快取使用者專屬的回應。

```ts
withHttpTransferCacheOptions({
  includeRequestsWithAuthHeaders: true,
});
```

只有當驗證標頭**不**影響回應內容時（例如分析 API 的公開 token），才啟用此設定。

### `includeRequestsWithCredentials`

決定使用 `withCredentials` 或 Fetch API `credentials` 模式（`include` 或 `same-origin`）送出的請求是否符合快取資格。  
預設情況下，這些請求會被排除，以防止快取使用者專屬的回應。

```ts
withHttpTransferCacheOptions({
  includeRequestsWithCredentials: true,
});
```

只有當帶憑證的請求所傳回的回應可以安全快取時，才啟用此設定。

### `includeNonCacheableRequests`

決定包含禁止快取之 `Cache-Control` 指令（`no-store`、`no-cache` 或 `private`）的請求與回應、帶有 `Set-Cookie` 標頭的回應，或使用 Fetch API `cache` 選項（`no-store` 或 `no-cache`）的請求，是否符合快取資格。  
預設情況下，這些會被排除，以尊重 HTTP 快取控制。

```ts
withHttpTransferCacheOptions({
  includeNonCacheableRequests: true,
});
```

只有當你需要繞過快取控制限制來進行傳輸快取時，才啟用此設定。

### 個別請求的覆寫

你可以使用 `transferCache` 請求選項，為特定請求覆寫快取行為。

```ts
// Include specific headers for this request
http.get('/api/profile', {transferCache: {includeHeaders: ['CustomHeader']}});
```

### 停用快取 {#disabling-caching}

你可以全域或個別停用從伺服器送出之請求的 HTTP 快取。

#### 全域停用

若要停用應用程式中所有請求的快取，請使用 `withNoHttpTransferCache` 功能：

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoHttpTransferCache,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoHttpTransferCache())],
});
```

#### 篩選

你也可以使用 `withHttpTransferCacheOptions` 中的 [`filter`](api/common/http/HttpTransferCacheOptions) 選項，選擇性地停用某些請求的快取。例如，你可以停用特定 API 端點的快取：

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withHttpTransferCacheOptions,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [
    provideClientHydration(
      withHttpTransferCacheOptions({
        filter: (req) => !req.url.includes('/api/sensitive-data'),
      }),
    ),
  ],
});
```

使用這個選項來排除帶有使用者專屬或動態資料的端點（例如 `/api/profile`）。

#### 個別請求

若要停用個別請求的快取，你可以在 `HttpRequest` 中指定 [`transferCache`](api/common/http/HttpRequest#transferCache) 選項。

```ts
httpClient.get('/api/sensitive-data', {transferCache: false});
```

`HttpTransferCache` 不會快取明確選擇退出快取的請求或回應。當請求包含值為 `no-store`、`no-cache` 或 `private` 的 `Cache-Control` 標頭，或請求使用設為 `no-store` 或 `no-cache` 的 Fetch API `cache` 選項時，Angular 會跳過傳輸快取項目。帶有 `Cache-Control: no-store`、`Cache-Control: no-cache` 或 `Cache-Control: private` 的回應也不會存入傳輸快取。包含 `Set-Cookie` 標頭的回應同樣不會被儲存，因為它們通常帶有使用者專屬的狀態。

NOTE: 如果你的應用程式在伺服器與用戶端使用不同的 HTTP 來源來呼叫 API，`HTTP_TRANSFER_CACHE_ORIGIN_MAP` token 讓你能在這些來源之間建立對應，使 `HttpTransferCache` 功能能將這些請求識別為相同的請求，並在用戶端水合期間重用伺服器上快取的資料。

## 設定伺服器

### Node.js

`@angular/ssr/node` 是專為 Node.js 環境擴充 `@angular/ssr` 的套件。它提供的 API 讓你在 Node.js 應用程式中實作伺服器端渲染更容易。完整的函式清單與使用範例，請參閱 [`@angular/ssr/node` API 參考](api/ssr/node/AngularNodeAppEngine)。

```ts
{header: "server.ts"}
import {
  AngularNodeAppEngine,
  createNodeRequestHandler,
  writeResponseToNodeResponse,
} from '@angular/ssr/node';
import express from 'express';

const app = express();
const angularApp = new AngularNodeAppEngine();

app.use((req, res, next) => {
  angularApp
    .handle(req)
    .then((response) => {
      if (response) {
        writeResponseToNodeResponse(response, res);
      } else {
        next(); // Pass control to the next middleware
      }
    })
    .catch(next);
});

/**
 * The request handler used by the Angular CLI (dev-server and during build).
 */
export const reqHandler = createNodeRequestHandler(app);
```

### Non-Node.js

`@angular/ssr` 提供在 Node.js 以外的平台上為你的 Angular 應用程式進行伺服器端渲染所需的核心 API。它利用 Web API 中標準的 [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) 與 [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) 物件，讓你能將 Angular SSR 整合到各種伺服器環境中。詳細資訊與範例，請參閱 [`@angular/ssr` API 參考](api/ssr/AngularAppEngine)。

```ts
{header: "server.ts"}
import {AngularAppEngine, createRequestHandler} from '@angular/ssr';

const angularApp = new AngularAppEngine();

/**
 * This is a request handler used by the Angular CLI (dev-server and during build).
 */
export const reqHandler = createRequestHandler(async (req: Request) => {
  const res: Response | null = await angularApp.handle(req);

// ...
});
```

## 安全性

關於防止伺服器端請求偽造（SSRF）與設定允許主機的詳細資訊，請參閱[伺服器端安全性](best-practices/security#preventing-server-side-request-forgery-ssrf)指南。
# 水合

## 什麼是水合 {#what-is-hydration}

水合是在用戶端還原伺服器端渲染應用程式的程序。這包括重用伺服器渲染出的 DOM 結構、保留應用程式狀態、傳遞伺服器先前已取得的應用程式資料等程序。

## 為什麼水合很重要？

水合避免了重新建立 DOM 節點的額外工作，因而提升應用程式效能。Angular 會在執行時嘗試將現有的 DOM 元素與應用程式結構對應，並在可能的情況下重用 DOM 節點。帶來的效能提升可以用 [Core Web Vitals (CWV)](https://web.dev/learn-core-web-vitals/) 指標來衡量，例如降低 First Input Delay（[FID](https://web.dev/fid/)）與 Largest Contentful Paint（[LCP](https://web.dev/lcp/)），以及 Cumulative Layout Shift（[CLS](https://web.dev/cls/)）。改善這些指標也會影響 SEO 表現等面向。

若未啟用水合，伺服器端渲染的 Angular 應用程式會毀掉並重新渲染應用程式的 DOM，可能造成肉眼可見的 UI 閃爍。這種重新渲染會對 [Core Web Vitals](https://web.dev/learn-core-web-vitals/)（例如 [LCP](https://web.dev/lcp/)）造成負面影響，並導致版面位移。啟用水合後，現有的 DOM 可以被重用，也能避免閃爍。

## 如何在 Angular 中啟用水合

水合只能在伺服器端渲染（SSR）的應用程式中啟用。請先依照 [Angular SSR 指南](guide/ssr) 啟用伺服器端渲染。

### 使用 Angular CLI

若你已使用 Angular CLI 啟用 SSR（不論是在建立應用程式時啟用，或之後透過 `ng add @angular/ssr` 啟用），啟用水合的程式碼應該已經包含在你的應用程式中。

### 手動設定

若你使用自訂設定、未透過 Angular CLI 啟用 SSR，可以手動啟用水合：在主要的應用程式元件或模組中，從 `@angular/platform-browser` 匯入 `provideClientHydration`，再將該提供者加入應用程式的啟動提供者清單。

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
} from '@angular/platform-browser';
...

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

若你使用 NgModule，則將 `provideClientHydration` 加入根應用程式模組的提供者清單。

```typescript
import {provideClientHydration} from '@angular/platform-browser';
import {NgModule} from '@angular/core';

@NgModule({
  declarations: [App],
  exports: [App],
  bootstrap: [App],
  providers: [provideClientHydration()],
})
export class AppModule {}
```

IMPORTANT: 請確認 `provideClientHydration()` 呼叫也包含在用於在**伺服器**上啟動應用程式的提供者集合中。在預設專案結構（由 `ng new` 指令產生）的應用程式中，只要把呼叫加入根 `AppModule` 應該就足夠了，因為伺服器模組會匯入這個模組。若你使用自訂設定，請將 `provideClientHydration()` 呼叫加入伺服器啟動設定中的提供者清單。

### 確認水合已啟用

設定好水合並啟動伺服器後，在瀏覽器中載入你的應用程式。

HELPFUL: 在水合完全運作之前，你很可能需要修正直接操作 DOM 的地方：改用 Angular 的寫法，或使用 `ngSkipHydration`。詳情請見[限制](#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 一載入，頁面就會出現在瀏覽器中。使用者可能會以為已經可以與頁面互動，但事件監聽器要等到水合完成後才會掛上。事件重播功能會擷取水合完成前發生的所有事件，並在水合完成後重播這些事件。

事件重播會隨著[漸進式水合](guide/incremental-hydration)一併啟用。若你以 `withNoIncrementalHydration()` 停用漸進式水合，仍可使用 `withEventReplay()` 函式啟用事件重播：

```typescript
import {
  provideClientHydration,
  withEventReplay,
  withNoIncrementalHydration,
  bootstrapApplication,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoIncrementalHydration(), withEventReplay())],
});
```

### 事件重播的運作方式

事件重播是一項提升使用者體驗的功能：它會擷取水合程序完成前觸發的使用者事件，再將這些事件重播，確保任何互動都不會遺失。

事件重播分為三個主要階段：

- **擷取使用者互動**<br>
  在**水合**之前，事件重播會擷取並儲存使用者可能進行的所有互動，例如點擊與其他瀏覽器原生事件。

- **儲存事件**<br>
  **Event Contract** 會將前一步記錄的所有互動保存在記憶體中，確保它們不會在稍後重播前遺失。

- **重新派發事件**<br>
  **水合**完成後，Angular 會重新觸發擷取到的事件。

事件重播支援_原生瀏覽器事件_，例如 `click`、`mouseover` 與 `focusin`。若想深入了解驅動事件重播的函式庫 JSAction，請見其 [README](https://github.com/angular/angular/tree/main/packages/core/primitives/event-dispatch#readme)。

這項功能確保一致的使用者體驗，避免使用者在水合前進行的操作被忽略。

## 限制 {#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 不符錯誤。

例如，以下是這個問題最常見的幾種情況。

- `<table>` without a `<tbody>`
- `<div>` inside a `<p>`
- `<a>` inside another `<a>`

若不確定自己的 HTML 是否有效，可以使用[語法驗證工具](https://validator.w3.org/)檢查。

NOTE: 雖然 HTML 標準並未要求表格中必須有 `<tbody>` 元素，但現代瀏覽器會自動為未宣告 `<tbody>` 的表格建立一個。為了避免這種不一致造成的問題，請務必在表格中明確宣告 `<tbody>` 元素，以免發生水合錯誤。

### Preserve Whitespaces 設定 {#preserve-whitespaces-configuration}

使用水合功能時，建議將 `preserveWhitespaces` 保持預設值 `false`。若你的 tsconfig 中沒有這項設定，其值即為 `false`，不需要做任何變更。若你選擇將 `preserveWhitespaces: true` 加入 tsconfig 來啟用保留空白，可能會遇到水合相關問題；這項目尚未完整支援的設定。

HELPFUL: 請確認這項設定在伺服器用的 `tsconfig.server.json` 與瀏覽器建置用的 `tsconfig.app.json` 中**保持一致**；值不一致會導致水合失效。

若要在 tsconfig 中設定這項設定，建議只在 `tsconfig.app.json` 中設定，`tsconfig.server.json` 預設會繼承它。

### 尚不支援自訂或 Noop 的 Zone.js

水合仰賴 Zone.js 在應用程式內部達到穩定時發出的訊號，讓 Angular 能在伺服器上啟動序列化程序，或在用戶端進行水合後清理，移除未被認領的 DOM 節點。

提供自訂或「noop」的 Zone.js 實作，可能會改變「stable」事件的時機，導致序列化或清理過早或過晚觸發。這項目尚未完整支援的設定，你可能需要調整自訂 Zone.js 實作中 `onStable` 事件的時機。

## 錯誤 {#errors}

你可能會遇到幾種與水合相關的錯誤，從節點不符，到在無效的宿主節點上使用 `ngSkipHydration` 的情況都有。最常見的錯誤原因是使用原生 API 直接操作 DOM，導致水合無法在用戶端找到或對應伺服器所渲染的預期 DOM 樹狀結構。另一種可能遇到這類錯誤的情況，已在前文的[有效的 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` 屬性加到根應用程式元件上，等於停用整個應用程式的水合。使用這個屬性時請謹慎考慮；它只是最後手段的因應方法。會破壞水合的元件應該視為需要修正的錯誤。

## 水合時機與應用程式穩定性

應用程式穩定性是水合程序的重要一環。水合與任何水合後程序，都要等應用程式回報達到穩定後才會進行。穩定可能被多種因素延遲，例如設定了計時器與週期性工作、promise 尚未完成，或有待處理的微任務。在這些情況下，你可能會遇到[應用程式持續不穩定](errors/NG0506)錯誤，表示你的應用程式在 10 秒後仍未達到穩定狀態。若你發現應用程式沒有立即水合，請檢查是什麼影響了應用程式的穩定性，並重構以避免這些延遲。

### 偵錯應用程式穩定性

`provideStabilityDebugging` 工具能協助你找出應用程式無法穩定的原因。使用 `provideClientHydration` 時，這個工具在開發模式下會預設提供。你也可以手動將它加入應用程式提供者，例如用於生產環境的程式包，或在不使用水合的 SSR 情境中。若應用程式穩定所需的時間超過預期，這項功能會將資訊記錄到主控台。

```typescript
import {provideStabilityDebugging} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';
import 'zone.js/plugins/task-tracking'; // Use if you have Zone.js with `provideZoneChangeDetection`

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

啟用後，這個工具會將待處理的工作（`PendingTasks`）記錄到主控台。若你的應用程式使用 Zone.js，也可以匯入 `zone.js/plugins/task-tracking`，查看哪些巨集任務讓 Angular Zone 無法穩定。這個外掛程式提供巨集任務建立時的堆疊追蹤，能有效協助你找出延遲的來源。

IMPORTANT: Angular 不會從生產環境的程式包中移除 zone.js 工作追蹤外掛程式或這個工具。請只在開發期間用它們暫時偵錯穩定性問題，包含最佳化後的生產環境建置。

## I18N

HELPFUL: 預設情況下，Angular 會略過使用 i18n 區塊的元件的水合，等同於從頭重新渲染這些元件。

若要為 i18n 區塊啟用水合，可以將 [`withI18nSupport`](/api/platform-browser/withI18nSupport) 加入你的 `provideClientHydration` 呼叫。

```typescript
import {
  bootstrapApplication,
  provideClientHydration,
  withI18nSupport,
} from '@angular/platform-browser';
...

bootstrapApplication(App, {
  providers: [provideClientHydration(withI18nSupport())]
});
```

## 伺服器端與用戶端之間的一致渲染

避免使用 `@if` 區塊或其他條件式，讓伺服器端渲染與用戶端渲染顯示不同內容，例如搭配 Angular 的 `isPlatformBrowser` 函式使用 `@if` 區塊。這類渲染差異會造成版面位移，對使用者體驗與 Core Web Vitals 造成負面影響。

## 操作 DOM 的第三方函式庫

有不少第三方函式庫仰賴 DOM 操作才能渲染，D3 圖表就是典型的例子。這些函式庫在未啟用水合時運作正常，但啟用水合後可能造成 DOM 不符錯誤。目前若你使用這類函式庫時遇到 DOM 不符錯誤，可以將 `ngSkipHydration` 屬性加到使用該函式庫渲染的元件上。

## 操作 DOM 的第三方指令碼 {#third-party-scripts-with-dom-manipulation}

許多第三方指令碼（例如廣告追蹤與分析工具）會在水合發生前修改 DOM。這些指令碼可能造成水合錯誤，因為頁面不再符合 Angular 預期的結構。請儘量將這類指令碼延後到水合完成後再執行。可以考慮使用 [`AfterNextRender`](api/core/afterNextRender)，將指令碼延後到水合後程序完成才執行。

### CDN 與瀏覽器擴充功能 {#cdns-and-browser-extensions}

應用程式以外的程式碼可能會在水合開始前變更來自伺服器的 HTML。這類錯誤在你的電腦上往往看不見，因為它們不會發生在你的本機伺服器上。

**會變更 HTML 的 CDN**。有些 CDN 功能會在 HTML 傳往瀏覽器的途中變更它。例如，有些功能會移除註解節點與空白，但水合需要這些節點。另一個例子是 Cloudflare 預設開啟的 Email Address Obfuscation（電子郵件地址混淆）功能，這項功能會把電子郵件地址改成像 `<span class="__cf_email__" data-cfemail="...">` 這樣的元素。它也會變更 `mailto:` 連結，並加入一個指令碼把內容改回來。如果這個指令碼在水合開始前沒有執行，Angular 會在預期是文字的地方找到一個元素。你的本機伺服器沒有使用 CDN，所以應用程式在你的電腦上可以正常運作，只在生產環境中失敗。

**瀏覽器擴充功能**。有些瀏覽器擴充功能會在水合開始前變更頁面，例如一鍵撥號工具、翻譯工具與密碼管理員。你無法控制這些擴充功能。只有安裝了它們的使用者會遇到問題，因此你可能只會看到部分使用者的錯誤。

要修正這類錯誤：

- 在被變更內容周圍的元件宿主上加入 `ngSkipHydration`。在你撰寫該內容的範本中加入，例如：`<app-contact ngSkipHydration><a href="tel:...">...</a></app-contact>`。Angular 接著會在瀏覽器中重新算繪這段內容，藉此移除那些變更。這個屬性只能用在元件宿主元素上，所以你不能把它加到 `<a>` 元素上。更多資訊請見[如何為特定元件略過水合](#how-to-skip-hydration-for-particular-components)。
- 關閉應用程式的 CDN 功能。在 Cloudflare 中，於安全性設定關閉 [Email Address Obfuscation](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/)，或使用 [Configuration Rule](https://developers.cloudflare.com/rules/configuration-rules/settings/)，針對應用程式的 host 停用它。

NOTE: Cloudflare 的 `` 註解在 Angular 範本中沒有幫助，因為編譯器會從範本中移除註解。

## 漸進式水合

漸進式水合是水合的進階形式，能更細緻地控制水合發生的時機。詳情請見[漸進式水合指南](guide/incremental-hydration)。
# 漸進式水合

**漸進式水合**（incremental hydration）是一種進階的水合（hydration）方式，能讓應用程式的某些區塊保持未水合狀態，並在需要時漸進觸發這些區塊的水合。

## 為什麼要使用漸進式水合？

漸進式水合是在完整應用程式水合之上建構的效能改善。它能產生更小的初始套件，同時仍提供與完整應用程式水合相當的最終使用者體驗。更小的套件能改善初始載入時間，進而降低 [First Input Delay (FID)](https://web.dev/fid) 與 [Cumulative Layout Shift (CLS)](https://web.dev/cls)。

漸進式水合也讓你能將可延遲檢視（deferrable views，`@defer`）用在以前可能無法延遲的內容上。具體來說，你現在可以把可延遲檢視用在首屏（above the fold）的內容上。在漸進式水合出現之前，把 `@defer` 區塊放在首屏會導致佔位內容先渲染出來，然後再被 `@defer` 區塊的主要範本內容取代，進而造成版面位移。漸進式水合則表示 `@defer` 區塊的主要範本在水合時會直接渲染，不會產生版面位移。

## 如何在 Angular 中啟用漸進式水合？ {#how-do-you-enable-incremental-hydration-in-angular}

對於已經使用伺服器端渲染（SSR）與水合的應用程式，你可以啟用漸進式水合。請先依照 [Angular SSR 指南](guide/ssr) 啟用伺服器端渲染，並依照 [Angular 水合指南](guide/hydration) 啟用水合。

當你使用 `provideClientHydration()` 時，漸進式水合預設就會啟用。

```ts
import {bootstrapApplication, provideClientHydration} from '@angular/platform-browser';

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

NOTE: 漸進式水合會依賴並自動啟用[事件重播](guide/hydration#capturing-and-replaying-events)。如果你的清單中已有 `withEventReplay()`，可以放心將它移除。

若要退出漸進式水合，請使用 `withNoIncrementalHydration()`：

```ts
import {
  bootstrapApplication,
  provideClientHydration,
  withNoIncrementalHydration,
} from '@angular/platform-browser';

bootstrapApplication(App, {
  providers: [provideClientHydration(withNoIncrementalHydration())],
});
```

## 漸進式水合如何運作？

漸進式水合建立在完整應用程式[水合](guide/hydration)、[可延遲檢視](/guide/templates/defer)與[事件重播](guide/hydration#capturing-and-replaying-events)之上。透過漸進式水合，你可以為 `@defer` 區塊加入額外的觸發條件，來定義漸進式水合的邊界。在延遲區塊加入 `hydrate` 觸發條件，是告訴 Angular 它應該在伺服器端渲染期間載入該延遲區塊的相依性，並渲染主要範本，而不是 `@placeholder`。在用戶端渲染時，相依性仍會被延遲，且延遲區塊的內容會保持未水合狀態，直到它的 `hydrate` 觸發條件被觸發為止。該觸發條件會告訴延遲區塊去取得它的相依性並水合內容。使用者在水合之前觸發的任何瀏覽器事件（特別是與你元件中註冊的監聽器相符的事件），都會先被排入佇列，並在水合程序完成後重播。

## 以觸發條件控制內容的水合

你可以指定 **hydrate 觸發條件**（hydrate triggers），來控制 Angular 何時載入並水合延遲的內容。這些是可與一般 `@defer` 觸發條件併用的額外觸發條件。

每個 `@defer` 區塊可以有多個 hydrate 事件觸發條件，以分號（`;`）分隔。只要有任一觸發條件被觸發，Angular 就會觸發水合。

hydrate 觸發條件有三種類型：`hydrate on`、`hydrate when` 與 `hydrate never`。

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

`hydrate on idle` 觸發條件會在瀏覽器達到閒置狀態時，根據 `requestIdleCallback` 載入可延遲檢視的相依性並水合內容。

你可以選擇性地指定一個以毫秒為單位的逾時，傳給 [`requestIdleCallback`](https://developer.mozilla.org/docs/Web/API/Window/requestIdleCallback)。如果瀏覽器沒有及時排程該回呼，工作最遲會在指定的逾時時間執行。

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

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

#### `hydrate on viewport` {#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}

`hydrate on interaction` 觸發條件會在使用者透過 `click` 或 `keydown` 事件與指定元素互動時，載入可延遲檢視的相依性並水合內容。

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

#### `hydrate on hover` {#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}

`hydrate on immediate` 觸發條件會立即載入可延遲檢視的相依性並水合內容。這表示延遲區塊會在所有其他非延遲內容完成渲染後，立刻載入。

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

#### `hydrate on timer` {#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` 觸發條件接受自訂的條件運算式，並在條件變為 truthy 時，載入可延遲檢視的相依性並水合內容。

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

NOTE: `hydrate when` 條件只有在它們是最上層未水合的 `@defer` 區塊時才會觸發。觸發條件所提供的條件是在父元件中指定的，而父元件必須先存在，才能被觸發。如果父區塊尚未水合，Angular 還無法解析該運算式。

### `hydrate never`

`hydrate never` 讓使用者能指定延遲區塊中的內容應無限期保持未水合狀態，實際上成為靜態內容。請注意，這只適用於初始渲染。在後續的用戶端渲染期間，帶有 `hydrate never` 的 `@defer` 區塊仍會取得相依性，因為水合只適用於伺服器端渲染內容的初始載入。在下面的範例中，後續的用戶端渲染會在進入可視區域時載入 `@defer` 區塊的相依性。

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

NOTE: 使用 `hydrate never` 會防止指定 `@defer` 區塊的整個巢狀子樹被水合。在該區塊底下巢狀的內容，不會有任何其他 `hydrate` 觸發條件被觸發。

## Hydrate 觸發條件與一般觸發條件併用

Hydrate 觸發條件是與 `@defer` 區塊的一般觸發條件併用的額外觸發條件。水合是一種初始載入最佳化，這表示 hydrate 觸發條件只適用於該次初始載入。任何後續的用戶端渲染仍會使用一般觸發條件。

```html
@defer (on idle; hydrate on interaction) {
  <example-cmp />
} @placeholder {
  <div>Example Placeholder</div>
}
```

在此範例中，在初始載入時，適用的是 `hydrate on interaction`。水合會在與 `<example-cmp />` 元件互動時觸發。在任何後續以用戶端渲染的頁面載入中（例如當使用者點選一個 routerLink，載入包含此元件的頁面時），適用的則是 `on idle`。

## 漸進式水合如何處理巢狀 `@defer` 區塊？

Angular 的元件與相依性系統是階層式的，這表示水合任何元件都需要它的所有父層也一併水合。因此，如果巢狀的一組未水合 `@defer` 區塊中的子 `@defer` 區塊觸發了水合，水合會從最上層未水合的 `@defer` 區塊開始，一路觸發到被觸發的子區塊，並依該順序執行。

```html
@defer (hydrate on interaction) {
  <parent-block-cmp />
  @defer (hydrate on hover) {
    <child-block-cmp />
  } @placeholder {
    <div>Child placeholder</div>
  }
} @placeholder {
  <div>Parent Placeholder</div>
}
```

在上例中，懸停於巢狀 `@defer` 區塊會觸發水合。帶有 `<parent-block-cmp />` 的父 `@defer` 區塊會先水合，然後帶有 `<child-block-cmp />` 的子 `@defer` 區塊才接著水合。

## 限制

漸進式水合的限制與完整應用程式水合相同，包括直接操作 DOM 的限制，以及要求有效的 HTML 結構。更多細節請參閱[水合指南的限制](guide/hydration#constraints)章節。

## 我還需要指定 `@placeholder` 區塊嗎？

需要。`@placeholder` 區塊的內容不會用於漸進式水合，但後續用戶端渲染的情況仍需要 `@placeholder`。如果你的內容不在初始載入所屬的路由上，那麼任何導覽到包含你的 `@defer` 區塊內容的路由時，都會像一般 `@defer` 區塊一樣渲染。因此在那些用戶端渲染的情況中，會渲染 `@placeholder`。
# 單元測試

測試你的 Angular 應用程式，能協助你確認它是否如預期般運作。單元測試對於及早發現錯誤、確保程式碼品質，以及讓重構更安全，都至關重要。

NOTE: 本指南介紹新建 Angular CLI 專案的預設測試設定，使用的是 Vitest。如果你要將既有專案從 Karma 遷移，請參閱[從 Karma 遷移至 Vitest 指南](guide/testing/migrating-to-vitest)。Karma 仍受支援；更多資訊請參閱 [Karma 測試指南](guide/testing/karma)。

## 測試設定 {#set-up-for-testing}

Angular CLI 會下載並安裝使用 [Vitest 測試框架](https://vitest.dev)測試 Angular 應用程式所需的一切。新專案預設包含 `vitest` 與 `jsdom`。

Vitest 在 Node.js 環境中執行你的單元測試。為了模擬瀏覽器的 DOM，Vitest 使用一個名為 `jsdom` 的函式庫。這樣可以避免啟動瀏覽器的額外負擔，讓測試執行得更快。你可以安裝 `happy-dom` 並解除安裝 `jsdom`，改用 `happy-dom` 作為替代方案。目前受支援的 DOM 模擬函式庫為 `jsdom` 與 `happy-dom`。

用 CLI 建立的專案開箱即可執行測試。執行 [`ng test`](cli/test) 指令：

```shell
ng test
```

`ng test` 指令會以_監看模式_建置應用程式，並啟動 [Vitest 測試執行器](https://vitest.dev)。

主控台輸出如下：

```shell
✓ src/app/app.spec.ts (2)
   ✓ App should create the app
   ✓ App should render title
 Test Files  1 passed (1)
      Tests  2 passed (2)
   Start at  18:18:01
   Duration  2.46s (transform 615ms, setup 2ms, collect 2.21s, tests 5ms)
```

`ng test` 指令也會監看你的檔案變更。如果你修改檔案並儲存，測試會再次執行。

## 設定

Angular CLI 會為你處理大部分的 Vitest 設定。你可以修改 `angular.json` 檔案中的 `test` 目標選項，來自訂測試行為。

### Angular.json 選項

- `include`：要納入測試的檔案 glob 模式。預設為 `['**/*.spec.ts', '**/*.test.ts']`。
- `exclude`：要從測試中排除的檔案 glob 模式。
- `setupFiles`：全域設定檔案的路徑清單（例如 polyfills 或全域 mock），會在你的測試之前執行。
- `providersFile`：匯出 Angular providers 預設陣列、供測試環境使用的檔案路徑。這對於設定注入到測試中的全域測試 providers 很有用。
- `coverage`：用來啟用或停用程式碼覆蓋率報告的布林值。預設為 `false`。
- `browsers`：要在真正的瀏覽器中執行測試的瀏覽器名稱陣列（例如 `["chromium"]`）。需要安裝瀏覽器 provider。詳情請參閱[在瀏覽器中執行測試](#running-tests-in-a-browser)一節。

### 全域測試設定與 providers

`setupFiles` 與 `providersFile` 選項對於管理全域測試設定特別有用。

例如，你可以建立一個 `src/test-providers.ts` 檔案，為所有測試提供 `provideHttpClientTesting`：

```typescript
{header: "src/test-providers.ts"}
import {EnvironmentProviders, Provider} from '@angular/core';
import {provideHttpClientTesting} from '@angular/common/http/testing';

const testProviders: (Provider | EnvironmentProviders)[] = [provideHttpClientTesting()];

export default testProviders;
```

接著在你的 `angular.json` 中引用這個檔案：

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "providersFile": "src/test-providers.ts"
          }
        }
      }
    }
  }
}
```

HELPFUL: 建立像 `src/test-providers.ts` 這樣的新 TypeScript 檔案作為測試設定或 providers 時，請確保它們有被納入專案的測試 TypeScript 設定檔（通常是 `tsconfig.spec.json`）。這樣 TypeScript 編譯器才能在測試期間正確處理這些檔案。

### 進階 Vitest 設定 {#advanced-vitest-configuration}

對於進階使用情境，你可以使用 `angular.json` 中的 `runnerConfig` 選項，提供自訂的 Vitest 設定檔。

IMPORTANT: 使用自訂設定雖然能啟用進階選項，但 Angular 團隊不支援設定檔的內容或任何第三方外掛。CLI 也會覆寫某些屬性（`test.projects`、`test.include`）以確保正確整合。

你可以建立一個 Vitest 設定檔（例如 `vitest-base.config.mts`），並在 `angular.json` 中引用它：

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "runnerConfig": "vitest-base.config.mts"
          }
        }
      }
    }
  }
}
```

你也可以使用 CLI 產生基礎設定檔：

```shell
ng generate config vitest
```

這會建立一個 `vitest-base.config.mts` 檔案，供你自訂。

HELPFUL: 關於 Vitest 設定的更多資訊，請參閱 [Vitest 官方文件](https://vitest.dev/config/)。

## 程式碼覆蓋率

在 `ng test` 指令加上 `--coverage` 旗標，即可產生程式碼覆蓋率報告。報告會產生在 `coverage/` 目錄中。

更詳細的資訊請參閱[程式碼覆蓋率指南](guide/testing/code-coverage)。

## 在瀏覽器中執行測試 {#running-tests-in-a-browser}

雖然預設的 Node.js 環境對大多數單元測試來說速度較快，你也可以在真正的瀏覽器中執行測試。這對於仰賴瀏覽器專屬 API（例如渲染）的測試，或除錯時很有用。

若要在瀏覽器中執行測試，你必須先安裝瀏覽器 provider。關於 Vitest 瀏覽器模式的更多資訊，請參閱[官方文件](https://vitest.dev/guide/browser)。

provider 安裝完成後，你可以透過設定 `angular.json` 中的 `browsers` 選項，或使用 `--browsers` CLI 旗標，在瀏覽器中執行測試。測試預設在有介面的瀏覽器中執行。如果設定了 `CI` 環境變數，則改用無頭模式。若要明確控制無頭模式，可以在瀏覽器名稱後加上 `Headless` 後綴（例如 `chromiumHeadless`）。

```bash
# Example for Playwright (headed)
ng test --browsers=chromium

# Example for Playwright (headless)
ng test --browsers=chromiumHeadless

# Example for WebdriverIO (headed)
ng test --browsers=chrome

# Example for WebdriverIO (headless)
ng test --browsers=chromeHeadless
```

請依需求選擇下列其中一個瀏覽器 provider：

### Playwright

[Playwright](https://playwright.dev/) 是一個瀏覽器自動化函式庫，支援 Chromium、Firefox 與 WebKit。

```shell
// npm
npm install --save-dev @vitest/browser-playwright playwright
```
```shell
// yarn
yarn add --dev @vitest/browser-playwright playwright
```
```shell
// pnpm
pnpm add -D @vitest/browser-playwright playwright
```
```shell
// bun
bun add --dev @vitest/browser-playwright playwright
```
### WebdriverIO

[WebdriverIO](https://webdriver.io/) 是一個瀏覽器與行動裝置自動化測試框架，支援 Chrome、Firefox、Safari 與 Edge。

```shell
// npm
npm install --save-dev @vitest/browser-webdriverio webdriverio
```
```shell
// yarn
yarn add --dev @vitest/browser-webdriverio webdriverio
```
```shell
// pnpm
pnpm add -D @vitest/browser-webdriverio webdriverio
```
```shell
// bun
bun add --dev @vitest/browser-webdriverio webdriverio
```
### Preview

`@vitest/browser-preview` provider 是為 StackBlitz 這類 WebContainer 環境設計的，不適合用在 CI/CD 中。

```shell
// npm
npm install --save-dev @vitest/browser-preview
```
```shell
// yarn
yarn add --dev @vitest/browser-preview
```
```shell
// pnpm
pnpm add -D @vitest/browser-preview
```
```shell
// bun
bun add --dev @vitest/browser-preview
```
HELPFUL: 更多進階的瀏覽器專屬設定，請參閱[進階 Vitest 設定](#advanced-vitest-configuration)一節。

## 其他測試框架

你也可以使用其他測試函式庫與測試執行器來對 Angular 應用程式進行單元測試。每個函式庫與執行器都有各自的安裝程序、設定與語法。

## 在持續整合中測試

健全的測試套件是持續整合（CI）管線的重要一環。CI 伺服器讓你能自動在每次提交與提取請求時執行測試。

若要在 CI 伺服器中測試你的 Angular 應用程式，請執行標準測試指令：

```shell
ng test
```

大多數 CI 伺服器會設定 `CI=true` 環境變數，`ng test` 能偵測到它。這會自動將你的測試設定為以非互動、單次執行模式執行。

如果你的 CI 伺服器沒有設定這個變數，或你需要手動強制使用單次執行模式，可以使用 `--no-watch` 與 `--no-progress` 旗標：

```shell
ng test --no-watch --no-progress
```

## 更多測試資訊

應用程式的測試設定完成後，下列測試指南可能對你有幫助。

程式碼覆蓋率報告會向你顯示程式碼庫中有哪些部分可能沒有被單元測試妥善測試到。

## 前置需求

若要使用 Vitest 產生程式碼覆蓋率報告，你必須安裝 `@vitest/coverage-v8` 套件：

```shell
// npm
npm install --save-dev @vitest/coverage-v8
```
```shell
// yarn
yarn add --dev @vitest/coverage-v8
```
```shell
// pnpm
pnpm add -D @vitest/coverage-v8
```
```shell
// bun
bun add --dev @vitest/coverage-v8
```
## 產生報告

若要產生覆蓋率報告，請在 `ng test` 指令加上 `--coverage` 旗標：

```shell
ng test --coverage
```

測試執行完畢後，該指令會在專案中建立一個新的 `coverage/` 目錄。開啟 `index.html` 檔案，即可看到包含你的原始碼與程式碼覆蓋率數值的報告。

如果你希望每次測試時都建立程式碼覆蓋率報告，可以在 `angular.json` 檔案中將 `coverage` 選項設定為 `true`：

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true
          }
        }
      }
    }
  }
}
```

## 強制執行程式碼覆蓋率門檻

程式碼覆蓋率百分比可以讓你估算有多少程式碼已被測試。如果你們團隊決定了單元測試的最低比例，你可以在設定中強制執行這個最低要求。

例如，假設你希望程式碼庫至少有 80% 的程式碼覆蓋率。若要啟用這個要求，請在 `angular.json` 檔案中加入 `coverageThresholds` 選項：

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true,
            "coverageThresholds": {
              "statements": 80,
              "branches": 80,
              "functions": 80,
              "lines": 80
            }
          }
        }
      }
    }
  }
}
```

如此一來，當你執行測試時，如果覆蓋率低於 80%，該指令就會失敗。

## 進階設定

你可以在 `angular.json` 檔案中設定其他幾個覆蓋率選項：

- `coverageInclude`：要包含在覆蓋率報告中的檔案 Glob 模式。
- `coverageExclude`：要從覆蓋率報告中排除的檔案 Glob 模式。
- `coverageReporters`：要使用的報告器陣列（例如 `html`、`lcov`、`json`）。
- `coverageWatermarks`：一個物件，指定 HTML 報告器的 `[low, high]` 浮水印值，可能影響報告的顏色標示。

```json
{
  "projects": {
    "your-project-name": {
      "architect": {
        "test": {
          "builder": "@angular/build:unit-test",
          "options": {
            "coverage": true,
            "coverageReporters": ["html", "lcov"],
            "coverageWatermarks": {
              "statements": [50, 80],
              "branches": [50, 80],
              "functions": [50, 80],
              "lines": [50, 80]
            }
          }
        }
      }
    }
  }
}
```
# 測試服務

服務通常包含應用程式的業務邏輯，而元件仰賴這些邏輯。測試服務可以驗證這些邏輯在獨立狀態下是否正確運作，不受任何元件或範本影響。

本指南使用 [Vitest](https://vitest.dev/)，Angular CLI 專案預設即包含它。關於測試設定的更多資訊，請參閱[測試總覽指南](guide/testing#set-up-for-testing)。

## 測試服務

以一個執行基本算術運算的 `Calculator` 服務為例：

```ts
{ header: 'calculator.ts' }
import {Service} from '@angular/core';

@Service()
export class Calculator {
  add(a: number, b: number): number {
    return a + b;
  }

subtract(a: number, b: number): number {
    return a - b;
  }
}
```

若要測試這個服務，需要設定 `TestBed`；它是 Angular 的測試工具，能為每個測試建立獨立的測試環境。它會設定依賴注入，讓你取得服務的實例，模擬 Angular 在真正的應用程式中串連各部分的作法。

```ts
{ header: 'calculator.spec.ts' }
import {TestBed} from '@angular/core/testing';
import {beforeEach, describe, expect, it} from 'vitest';
import {Calculator} from './calculator';

describe('Calculator', () => {
  let service: Calculator;

beforeEach(() => {
    // Injects the Calculator service which is available to Angular
    // because the service uses `@Service`
    service = TestBed.inject(Calculator);
  });

it('adds two numbers', () => {
    expect(service.add(1, 2)).toBe(3);
  });

it('subtracts two numbers', () => {
    expect(service.subtract(5, 3)).toBe(2);
  });
});
```

在上例中，`beforeEach` 區塊會在每個測試之前注入服務的新實例。這能確保每個測試都在獨立狀態下執行，不會殘留先前測試的狀態。

## 測試具有相依性的服務

大多數服務需要相依於其他服務才能正常運作。`TestBed` 預設提供這些相依性的真正實作，也就是說，你的測試會執行應用程式實際使用的程式碼路徑。不過，有些相依性可能很複雜、緩慢，或結果不可預測。在這些情況下，你可以將它換成受控的替代實作。

以一個仰賴 `TaxCalculator` 計算訂單最終價格的 `OrderTotal` 服務為例：

```ts
{ header: 'tax-calculator.ts' }
import {Service} from '@angular/core';

@Service()
export class TaxCalculator {
  calculate(subtotal: number): number {
    return subtotal * 0.05;
  }
}
```

```ts
{ header: 'order-total.ts' }
import {inject, Service} from '@angular/core';
import {TaxCalculator} from './tax-calculator';

@Service()
export class OrderTotal {
  private taxCalculator = inject(TaxCalculator);

total(subtotal: number): number {
    return subtotal + this.taxCalculator.calculate(subtotal);
  }
}
```

在這個範例中，`OrderTotal` 使用 `inject()` 向 Angular 的依賴注入系統請求 `TaxCalculator`。`TestBed` 預設提供真正的 `TaxCalculator`，對於像這樣簡單的計算非常合適。不過，如果 `TaxCalculator` 涉及複雜邏輯、網路請求或不可預測的結果，你可能會想將它換成受控的替代實作。

### 以 stub 取代相依性

stub 是一種取代相依性或方法的方式，讓它傳回可預測的值，使測試結果更容易驗證。

若要在不仰賴真正 `TaxCalculator` 的情況下測試 `OrderTotal`，你可以在 `TestBed` 設定中提供一個 stub。

```ts
{ header: 'order-total.spec.ts' }
import {TestBed} from '@angular/core/testing';
import {beforeEach, describe, expect, it, vi, type Mocked} from 'vitest';
import {OrderTotal} from './order-total';
import {TaxCalculator} from './tax-calculator';

// Vitest's `Mocked` utility type ensures the stub is type-safe,
// while `vi.fn()` creates a mock function for each method
const taxCalculatorStub: Mocked<TaxCalculator> = {
  calculate: vi.fn(),
};

describe('OrderTotal', () => {
  let service: OrderTotal;

beforeEach(() => {
    // `mockReturnValue` sets a controlled return value for the stub
    taxCalculatorStub.calculate.mockReturnValue(5);

TestBed.configureTestingModule({
      // The `providers` array accepts a provider object where `provide`
      // specifies the dependency to replace and `useValue` defines the stub
      providers: [{provide: TaxCalculator, useValue: taxCalculatorStub}],
    });
    service = TestBed.inject(OrderTotal);
  });

it('adds tax to the subtotal', () => {
    expect(service.total(100)).toBe(105);
  });
});
```

有了這個 stub，每當 `OrderTotal` 請求 `TaxCalculator` 時，`TestBed` 就知道要改用 `taxCalculatorStub`。由於 stub 永遠傳回 5，這個測試驗證了 `OrderTotal` 能正確地將稅額加到小計上，無論 `TaxCalculator` 中的稅率如何變化。

### 使用 spy 驗證互動

stub 能控制相依性傳回什麼，但有時你還需要驗證服務是否以正確的引數呼叫了它的相依性。這可以透過 spy 達成，spy 會追蹤函式被呼叫的方式。在 Vitest 中，這項功能內建於 `vi.fn()`，讓你能對服務之間的互動進行斷言。

```ts
{ header: 'order-total.spec.ts' }
import {TestBed} from '@angular/core/testing';
import {afterEach, beforeEach, describe, expect, it, vi, type Mocked} from 'vitest';
import {OrderTotal} from './order-total';
import {TaxCalculator} from './tax-calculator';

const taxCalculatorStub: Mocked<TaxCalculator> = {
  calculate: vi.fn(),
};

describe('OrderTotal', () => {
  let service: OrderTotal;

beforeEach(() => {
    taxCalculatorStub.calculate.mockReturnValue(5);

TestBed.configureTestingModule({
      providers: [{provide: TaxCalculator, useValue: taxCalculatorStub}],
    });
    service = TestBed.inject(OrderTotal);
  });

afterEach(() => {
    taxCalculatorStub.calculate.mockClear();
  });

it('adds tax to the subtotal', () => {
    expect(service.total(100)).toBe(105);
  });

// Verify the interaction with a spy
  it('calls the tax calculator', () => {
    service.total(100);
    expect(taxCalculatorStub.calculate).toHaveBeenCalledExactlyOnceWith(100);
  });
});
```

新增的測試驗證了 `OrderTotal` 在計算總額時有呼叫 `TaxCalculator.calculate`。這在驗證服務之間的互動是否正確發生時很有用。

## 測試 HTTP 服務

許多服務使用 Angular 的 `HttpClient` 從伺服器取得資料。Angular 為 `HttpClient` 提供了專門的測試工具，讓你能控制 HTTP 回應，不必發出真正的網路請求。

關於測試使用 `HttpClient` 的服務，詳情請參閱 [HTTP 測試指南](guide/http/testing)。
# 測試元件的基礎知識

元件與 Angular 應用程式的所有其他部分不同，它結合了 HTML 範本與 TypeScript 類別。
元件真正的是範本與類別_共同運作_。
若要妥善測試元件，你應該測試它們是否如預期般共同運作。

這類測試需要在瀏覽器 DOM 中建立元件的宿主元素（如同 Angular 所做的），並研究元件類別如何依照其範本所描述的方式與 DOM 互動。

Angular `TestBed` 促進了這類測試，你將在以下章節中看到。
但在許多情況下，_單獨測試元件類別_、不涉及 DOM，就能以直接、更明顯的方式驗證元件的大部分行為。

## 元件 DOM 測試

元件不只是它的類別而已。
元件會與 DOM 以及其他元件互動。
光靠類別無法告訴你元件是否能正確渲染、回應使用者輸入與手勢，或與其父元件和子元件整合。

- `Lightswitch.clicked()` 是否繫結到任何東西，讓使用者可以叫用它？
- `Lightswitch.message` 是否有顯示？
- 使用者是否真的能選取 `DashboardHero` 元件顯示的英雄？
- 英雄名稱是否如預期般顯示（例如大寫）？
- `Welcome` 元件的範本是否顯示了歡迎訊息？

對前面說明的簡單元件來說，這些問題可能不令人困擾。
但許多元件與其範本中所描述的 DOM 元素有複雜的互動，隨著元件狀態變更，HTML 會出現和消失。

若要回答這類問題，你必須建立與元件相關聯的 DOM 元素，必須檢查 DOM 以確認元件狀態在適當的時機正確顯示，並且必須模擬使用者與螢幕的互動，以判斷這些互動是否讓元件如預期般運作。

若要撰寫這類測試，你將使用 `TestBed` 的額外功能以及其他測試輔助工具。

### CLI 產生的測試

當你要求 CLI 產生新元件時，CLI 依預設會為你建立一個初始測試檔案。

例如，以下 CLI 指令會在 `app/banner` 資料夾中產生一個 `Banner` 元件（帶有內嵌範本與樣式）：

```shell
ng generate component banner --inline-template --inline-style
```

它也會為該元件產生一個初始測試檔案 `banner.spec.ts`，看起來像這樣：

```ts
import {ComponentFixture, TestBed} from '@angular/core/testing';
import {Banner} from './banner';

describe('Banner', () => {
  let component: Banner;
  let fixture: ComponentFixture<Banner>;

beforeEach(async () => {
    TestBed.configureTestingModule({});

fixture = TestBed.createComponent(Banner);
    component = fixture.componentInstance;
    await fixture.whenStable();
  });

it('should create', () => {
    expect(component).toBeTruthy();
  });
});
```

### 減少設定

這個檔案中只有最後三行真正在測試元件，而且它們所做的只是斷言 Angular 可以建立該元件。

檔案的其餘部分都是樣板設定程式碼，預先為更進階的測試做準備——如果元件演變成實質的東西，這些測試_可能_會變得有必要。

你將在以下章節中了解這些進階測試功能。
目前，你可以大幅縮減這個測試檔案，使其大小更易於管理：

```ts
describe('Banner (minimal)', () => {
  it('should create', () => {
    const fixture = TestBed.createComponent(Banner);
    const component = fixture.componentInstance;
    expect(component).toBeDefined();
  });
});
```

稍後你將呼叫 `TestBed.configureTestingModule()`，帶入匯入、提供者與更多宣告，以滿足你的測試需求。
選擇性的 `override` 方法可以進一步微調設定的各個面向。

NOTE: 只有在受測元件使用 `@defer` 區塊時，才需要 `TestBed.compileComponents`。

### `createComponent()`

設定好 `TestBed` 之後，你呼叫它的 `createComponent()` 方法。

```ts
const fixture = TestBed.createComponent(Banner);
```

`TestBed.createComponent()` 會建立 `Banner` 元件的一個執行個體，將對應的元素加入測試執行器 DOM，並回傳一個 [`ComponentFixture`](#componentfixture)。

IMPORTANT: 呼叫 `createComponent` 之後，不要重新設定 `TestBed`。

`createComponent` 方法會凍結目前的 `TestBed` 定義，使其無法再進行進一步設定。

你不能再呼叫任何 `TestBed` 設定方法，不能呼叫 `configureTestingModule()`，也不能呼叫任何 `override...` 方法。
如果你嘗試這麼做，`TestBed` 會擲出錯誤。

### `ComponentFixture` {#componentfixture}

[`ComponentFixture`](api/core/testing/ComponentFixture) 是一個測試工具，用於與建立的元件及其對應元素互動。

透過 fixture 存取元件執行個體，並用期望確認它存在：

```ts
const component = fixture.componentInstance;
expect(component).toBeDefined();
```

### `beforeEach()`

隨著這個元件演變，你將加入更多測試。
與其為每個測試重複 `TestBed` 設定，不如重構，將設定抽到 `beforeEach()` 與一些輔助變數中：

```ts
describe('Banner (with beforeEach)', () => {
  let component: Banner;
  let fixture: ComponentFixture<Banner>;

beforeEach(async () => {
    fixture = TestBed.createComponent(Banner);
    component = fixture.componentInstance;

await fixture.whenStable(); // necessary to wait for the initial rendering
  });

it('should create', () => {
    expect(component).toBeDefined();
  });
});
```

HELPFUL: 在 `beforeEach` 中以 `await fixture.whenStable` 等待初始渲染，可以讓個別測試保持同步。

現在加入一個測試，從 `fixture.nativeElement` 取得元件的元素，並尋找預期的文字。

```ts
it('should contain "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  expect(bannerElement.textContent).toContain('banner works!');
});
```

### 建立 `setup` 函式

作為 `beforeEach` 的替代方案，你也可以建立一個 setup 函式，在每個測試中呼叫它。
setup 函式的優點是它可以透過參數自訂。

以下是一個 setup 函式可能長什麼樣子的範例：

```ts
function setup(providers?: Provider[]): ComponentFixture<Banner> {
  TestBed.configureTestingModule({providers});
  return TestBed.createComponent(Banner);
}
```

### `nativeElement`

`ComponentFixture.nativeElement` 的值型別為 `any`。
稍後你會遇到 `DebugElement.nativeElement`，它的型別同樣是 `any`。

Angular 在編譯時期無法知道 `nativeElement` 是哪一種 HTML 元素，甚至不知道它是否為 HTML 元素。
應用程式可能正在_非瀏覽器平台_上執行，例如伺服器或 node 環境，在這些環境中，該元素可能擁有縮減的 API，甚至根本不存在。

本指南中的測試設計為在瀏覽器中執行，因此 `nativeElement` 值永遠都會是 `HTMLElement` 或其衍生類別之一。

知道它是某種 `HTMLElement` 之後，就可以使用標準的 HTML `querySelector` 深入元素樹。

以下另一個測試呼叫 `HTMLElement.querySelector` 來取得段落元素，並尋找橫幅文字：

```ts
it('should have <p> with "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  const p = bannerElement.querySelector('p')!;
  expect(p.textContent).toEqual('banner works!');
});
```

### `DebugElement`

Angular _fixture_ 透過 `fixture.nativeElement` 直接提供元件的元素。

```ts
const bannerElement: HTMLElement = fixture.nativeElement;
```

這實際上是一個便利方法，實作方式為 `fixture.debugElement.nativeElement`。

```ts
const bannerDe: DebugElement = fixture.debugElement;
const bannerEl: HTMLElement = bannerDe.nativeElement;
```

透過這條迂迴路徑取得元素，是有充分理由的。

`nativeElement` 的屬性取決於執行階段環境。
你可能正在_非瀏覽器_平台上執行這些測試，該平台沒有 DOM，或其 DOM 模擬不支援完整的 `HTMLElement` API。

Angular 仰賴 `DebugElement` 抽象層，才能在_所有受支援的平台_上安全運作。
Angular 不會建立 HTML 元素樹，而是建立 `DebugElement` 樹，包裝執行階段平台的_原生元素_。
`nativeElement` 屬性會解開 `DebugElement`，回傳平台專屬的元素物件。

由於本指南的範例測試設計為只在瀏覽器中執行，這些測試中的 `nativeElement` 永遠是 `HTMLElement`，你可以在測試中探索它熟悉的方法與屬性。

以下先前的測試以 `fixture.debugElement.nativeElement` 重新實作：

```ts
it('should find the <p> with fixture.debugElement.nativeElement', () => {
  const bannerDe: DebugElement = fixture.debugElement;
  const bannerEl: HTMLElement = bannerDe.nativeElement;
  const p = bannerEl.querySelector('p')!;
  expect(p.textContent).toEqual('banner works!');
});
```

`DebugElement` 還有其他在測試中很有用的方法與屬性，你將在本指南的其他地方看到。

你從 Angular 核心函式庫匯入 `DebugElement` 符號。

```ts
import {DebugElement} from '@angular/core';
```

### `By.css()`

雖然本指南中的測試全都在瀏覽器中執行，但有些應用程式至少有一部分時間可能在不同平台上執行。

例如，元件可能先在伺服器上渲染，作為讓應用程式在連線不佳的裝置上更快啟動的策略的一部分。
伺服器端渲染器可能不支援完整的 HTML 元素 API。
如果它不支援 `querySelector`，前面的測試可能會失敗。

`DebugElement` 提供適用於所有受支援平台的查詢方法。
這些查詢方法接受一個_謂詞_函式，當 `DebugElement` 樹中的節點符合選取條件時，該函式回傳 `true`。

你借助從執行階段平台函式庫匯入的 `By` 類別，建立一個_謂詞_。
以下是瀏覽器平台的 `By` 匯入：

```ts
import {By} from '@angular/platform-browser';
```

以下範例以 `DebugElement.query()` 與瀏覽器的 `By.css` 方法重新實作先前的測試。

```ts
it('should find the <p> with fixture.debugElement.query(By.css)', () => {
  const bannerDe: DebugElement = fixture.debugElement;
  const paragraphDe = bannerDe.query(By.css('p'));
  const p: HTMLElement = paragraphDe.nativeElement;
  expect(p.textContent).toEqual('banner works!');
});
```

一些值得注意的觀察：

- `By.css()` 靜態方法會以[標準 CSS 選擇器](https://developer.mozilla.org/docs/Learn/CSS/Building_blocks/Selectors 'CSS selectors')選取 `DebugElement` 節點。
- 查詢會回傳段落的 `DebugElement`。
- 你必須解開該結果，才能取得段落元素。

當你以 CSS 選擇器篩選，並且只測試瀏覽器_原生元素_的屬性時，`By.css` 的方式可能有點過度。

使用標準的 `HTMLElement` 方法（例如 `querySelector()` 或 `querySelectorAll()`）來篩選，往往更直接、更清楚。
# 元件測試情境

本指南探討常見的元件測試使用情境。

## 元件繫結

在範例應用程式中，`Banner` 元件在 HTML 範本中呈現靜態的標題文字。

經過幾次變更後，`Banner` 元件透過繫結到元件的 `title` 屬性，呈現動態標題，如下所示。

```typescript
{header: "banner.ts"}
import {Component, signal} from '@angular/core';

@Component({
  selector: 'app-banner',
  template: '<h1>{{ title() }}</h1>',
  styles: ['h1 { color: green; font-size: 350%}'],
})
export class Banner {
  title = signal('Test Tour of Heroes');
}
```

即使內容如此精簡，你還是決定加入一個測試，確認元件確實在你預期的位置顯示正確的內容。

### 查詢 `<h1>`

你將撰寫一系列測試，檢查包住 _title_ 屬性插值繫結的 `<h1>` 元素之值。

你更新 `beforeEach`，使用標準的 HTML `querySelector` 找到該元素，並將它指派給 `h1` 變數。

```ts
{header: "banner.component.spec.ts"}
let component: Banner;
let fixture: ComponentFixture<Banner>;
let h1: HTMLElement;

beforeEach(() => {
  fixture = TestBed.createComponent(Banner);
  component = fixture.componentInstance; // Banner test instance
  h1 = fixture.nativeElement.querySelector('h1');
});
```

### `createComponent()` 不會繫結資料

在你的第一個測試中，你想看到畫面顯示預設的 `title`。
你的直覺是撰寫一個立即檢查 `<h1>` 的測試，如下所示：

```ts
it('should display original title', () => {
  expect(h1.textContent).toContain(component.title());
});
```

_該測試失敗_，並顯示下列訊息：

```shell
{hideCopy}
expected '' to contain 'Test Tour of Heroes'.
```

繫結發生在 Angular 執行**變更偵測**時。

在正式環境中，舉例來說，當 Angular 建立一個元件，或使用者輸入按鍵時，變更偵測會自動啟動。

`TestBed.createComponent` 不會同步觸發變更偵測；修訂後的測試證實了這個事實：

```ts
it('no title in the DOM after createComponent()', () => {
  expect(h1.textContent).toEqual('');
});
```

### `whenStable()` {#whenstable}

你可以透過 `await fixture.whenStable()` 告訴 `TestBed` 等待變更偵測執行。
只有到那時，`<h1>` 才會有預期的標題。

```ts
it('should display original title', async () => {
  await fixture.whenStable();
  expect(h1.textContent).toContain(component.title());
});
```

延遲變更偵測是有意設計且實用的。
它讓測試者有機會在 _Angular 開始資料繫結並呼叫[生命週期鉤子](guide/components/lifecycle)之前_，檢查並變更元件的狀態。

這是另一個測試，它在呼叫 `fixture.whenStable()` _之前_ 先變更元件的 `title` 屬性。

```ts
it('should display a different test title', async () => {
  component.title.set('Test Title');
  await fixture.whenStable();
  expect(h1.textContent).toContain('Test Title');
});
```

### 將訊號繫結到輸入

若要反映輸入的變更並監聽輸出，你可以將訊號動態繫結到輸入，並將函式繫結到輸出。

```ts
import {inputBinding, outputBinding} from '@angular/core';
import {TestBed} from '@angular/core/testing';

const fixture = TestBed.createComponent(ValueDisplay, {
  bindings: [
    inputBinding('value', value),
    outputBinding('valueChange', () =>  (/* ... */) ),
  ],
});
```

### 以 `dispatchEvent()` 變更輸入值

若要模擬使用者輸入，請找到輸入元素並設定它的 `value` 屬性。

但這中間有一個不可或缺的步驟。

Angular 並不知道你設定了輸入元素的 `value` 屬性。
在你呼叫 `dispatchEvent()` 引發元素的 `input` 事件之前，它不會讀取該屬性。

下列使用 `TitleCasePipe` 的元件範例示範了正確的順序。

```ts
it('should convert hero name to Title Case', async () => {
  const hostElement = fixture.nativeElement;
  const nameInput: HTMLInputElement = hostElement.querySelector('input')!;
  const nameDisplay: HTMLElement = hostElement.querySelector('span')!;

// simulate user entering a new name into the input box
  nameInput.value = 'quick BROWN  fOx';

// Dispatch a DOM event so that Angular learns of input value change.
  nameInput.dispatchEvent(new Event('input'));

// Wait for Angular to update the display binding through the title pipe
  await fixture.whenStable();

expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
```

## 具有相依性的元件

元件經常有服務相依性。

`Welcome` 元件會向已登入的使用者顯示歡迎訊息。
它依據注入的 `UserAuthentication` 的某個屬性，知道使用者是誰：

```typescript
import {Component, computed, inject} from '@angular/core';
import {UserAuthentication} from '../model/user.authentication';

@Component({
  selector: 'app-welcome',
  template: '<h3 class="welcome"><i>{{ welcome() }}</i></h3>',
})
export class Welcome {
  private userAuth = inject(UserAuthentication);
  welcome = computed(() =>
    this.userAuth.isLoggedIn() ? `Welcome, ${this.userAuth.user().name}` : 'Please log in.',
  );
}
```

`Welcome` 元件具有與服務互動的決策邏輯，這些邏輯讓這個元件值得測試。

### 提供服務測試替身

_受測元件_ 不一定要搭配真實的服務。

注入真實的 `UserAuthentication` 可能很困難。
真實的服務可能會要求使用者提供登入憑證，並嘗試連線到驗證伺服器。
這些行為可能很難攔截。請注意，使用測試替身會讓測試的行為與正式環境不同，因此請謹慎使用。

### 取得注入的服務 {#get-injected-services}

測試需要存取注入到 `Welcome` 元件中的 `UserAuthentication`。

Angular 有一套階層式注入系統。
從 `TestBed` 建立的根注入器，一路往下到元件樹，注入器可以存在於多個層級。

取得注入服務最安全、**永遠有效**的方法，
是**從受測元件的注入器取得它**。
元件注入器是 fixture 的 `DebugElement` 的一個屬性。

```ts
// UserAuthentication actually injected into the component
userAuth = fixture.debugElement.injector.get(UserAuthentication);
```

HELPFUL: 這_通常_沒有必要。服務經常在根層級提供，或由 TestBed 覆寫，而且可以更容易地以 `TestBed.inject()` 取得（見下文）。

### `TestBed.inject()`

比起使用 fixture 的 `DebugElement` 取得服務，這個方法更容易記住，也更簡潔。

在這個測試套件中，`UserAuthentication` 的_唯一_提供者是根測試模組，因此可以安全地如下呼叫 `TestBed.inject()`：

```ts
userAuth = TestBed.inject(UserAuthentication);
```

HELPFUL: 關於 `TestBed.inject()` 無法運作的使用情境，請參閱[覆寫元件的提供者](#override-component-providers)一節，該節說明了何時以及為何你必須改從元件的注入器取得服務。

### 最終設定與測試

以下是完整的 `beforeEach()`，使用 `TestBed.inject()`：

```ts
let fixture: ComponentFixture<Welcome>;
let comp: Welcome;
let userAuth: UserAuthentication; // the TestBed injected service
let el: HTMLElement; // the DOM element with the welcome message

beforeEach(() => {
  fixture = TestBed.createComponent(Welcome);
  comp = fixture.componentInstance;

// UserAuthentication from the root injector
  userAuth = TestBed.inject(UserAuthentication);

//  get the "welcome" element by CSS selector (e.g., by class name)
  el = fixture.nativeElement.querySelector('.welcome');
});
```

以下是一些測試：

```ts
it('should welcome the user', async () => {
  await fixture.whenStable();
  const content = el.textContent;

expect(content, '"Welcome ..."').toContain('Welcome');
  expect(content, 'expected name').toContain('Test User');
});

it('should welcome "Bubba"', async () => {
  userAuth.user.set({name: 'Bubba'}); // welcome message hasn't been shown yet
  await fixture.whenStable();

expect(el.textContent).toContain('Bubba');
});

it('should request login if not logged in', async () => {
  userAuth.isLoggedIn.set(false); // welcome message hasn't been shown yet
  await fixture.whenStable();
  const content = el.textContent;

expect(content, 'not welcomed').not.toContain('Welcome');
  expect(content, '"log in"').toMatch(/log in/i);
});
```

第一個是健全性測試；它確認 `UserAuthentication` 有被呼叫且正常運作。

HELPFUL: `expect` 的第 2 個參數（例如 `'expected name'`）是選擇性的失敗標籤。
如果期望不成立，Vitest 會將這個標籤附加到期望失敗訊息中。
在包含多個期望的規格中，它能幫助釐清出了什麼問題，以及是哪個期望失敗。

其餘的測試則確認服務傳回不同值時元件的邏輯。
第二個測試驗證變更使用者名稱的效果。
第三個測試檢查在沒有已登入使用者時，元件是否顯示適當的訊息。

## 具有非同步服務的元件

在這個範例中，`About` 元件範本承載了一個 `Twain` 元件。
`Twain` 元件會顯示 Mark Twain 的名言。

```html
<p class="twain">
  <i>{{ quote | async }}</i>
</p>
<button type="button" (click)="getQuote()">Next quote</button>
@if (errorMessage()) {
  <p class="error">{{ errorMessage() }}</p>
}
```

HELPFUL: 元件的 `quote` 屬性之值會通過一個 `AsyncPipe`。
這表示該屬性傳回的是 `Promise` 或 `Observable`。

在這個範例中，`TwainQuotes.getQuote()` 方法告訴你，`quote` 屬性傳回的是一個 `Observable`。

```ts
getQuote() {
  this.errorMessage.set('');
  this.quote = this.twainQuotes.getQuote().pipe(
    startWith('...'),
    catchError((err: any) => {
      this.errorMessage.set(err.message || err.toString());
      return of('...'); // reset message to placeholder
    }),
  );
}
```

`Twain` 元件從注入的 `TwainQuotes` 取得名言。
在服務能傳回第一句名言之前，元件先以一個佔位值（`'...'`）作為傳回的 `Observable` 的起始值。

`catchError` 會攔截服務錯誤、準備錯誤訊息，並在成功通道上傳回佔位值。

這些都是你會想測試的功能。

### 透過以 `HttpTestingController` 模擬 HTTP 請求進行測試

測試元件時，重要的應該只有服務的公開 API。
一般而言，測試本身不應該呼叫遠端伺服器。
它們應該模擬這類呼叫。

如果你的非同步服務依賴 `HttpClient` 來載入遠端資料，建議在 HTTP 層級以 `HttpTestingController` 傳回模擬回應。

關於模擬 `HttpBackend` 的更多細節，請參閱[專門的指南](guide/http/testing)。

### 透過提供服務的替身實作進行測試

當無法在 HTTP 層級模擬非同步請求時，另一個選擇是利用 spy。

這個 `app/twain/twain-quotes.spec.ts` 中的設定展示了其中一種做法：

```ts
{header: "twain.spec.ts"}
class TwainQuotesStub implements TwainQuotes {
  private testQuote = 'Test Quote';

getQuote() {
    return of(this.testQuote);
  }

// ... Implement everything to conform to the API
}

beforeEach(async () => {
  TestBed.configureTestingModule({
    providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
  });

fixture = TestBed.createComponent(Twain);
  component = fixture.componentInstance;
  await fixture.whenStable();
  quoteEl = fixture.nativeElement.querySelector('.twain');
});
```

請注意替身實作如何取代原始實作。

```ts
TestBed.configureTestingModule({
  providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
});
```

這個替身的設計方式，讓任何注入它的元件或服務都會收到替身實作。
這表示對 `getQuote` 的任何呼叫，都會收到一個帶有測試名言的 observable。

與真實的 `getQuote()` 方法不同，這個 spy 繞過了伺服器，傳回一個值可立即取得的同步 observable。

### 使用 Vitest 假計時器的非同步測試 {#async-test-with-a-vitest-fake-timers}

若要模擬像 `setTimeout` 或 `Promise` 這類非同步函式，你可以利用 Vitest 假計時器來控制它們觸發的時機。

```ts
it('should display error when TwainQuotes service fails', async () => {
  class TwainQuotesStub implements TwainQuotes {
    getQuote() {
      return defer(() => {
        return new Promise<string>((_, reject) => {
          setTimeout(() => reject('TwainService test failure'));
        });
      });
    }

// ... Implement everything to conform to the API
  }

TestBed.configureTestingModule({
    providers: [{provide: TwainQuotes, useClass: TwainQuotesStub}],
  });

vi.useFakeTimers(); // setting up the fake timers
  const fixture = TestBed.createComponent(TwainComponent);

// rendering isn't async, we need to flush
  await vi.runAllTimersAsync();

await expect(fixture.nativeElement.querySelector('.error')!.textContent).toMatch(/test failure/);
  expect(fixture.nativeElement.querySelector('.twain')!.textContent).toBe('...');

vi.useRealTimers(); // resets to regular async execution
});
```

### 更多非同步測試

在替身服務傳回非同步 observable 的情況下，你的大多數測試也必須是非同步的。

以下是一個展示你在真實世界中預期之資料流的測試。

```ts
class MockTwainQuotes implements TwainQuotes {
  private subject = new Subject<string>();

getQuote() {
    return this.subject.asObservable();
  }

emit(val: string) {
    this.subject.next(val);
  }
}

it('should show quote after getQuote (success)', async () => {
  vi.useFakeTimers();

TestBed.configureTestingModule({
    providers: [{provide: TwainQuotes, useClass: MockTwainQuotes}],
  });

const fixture = TestBed.createComponent(TwainComponent);
  const twainQuotes = TestBed.inject(TwainQuotes) as MockTwainQuotes;
  await vi.runAllTimersAsync(); // render before the quote is received

const quoteEl = fixture.nativeElement.querySelector('.twain');
  expect(quoteEl.textContent).toBe('...');

twainQuotes.emit('Twain Quote'); // emits the quote
  await vi.runAllTimersAsync(); // render with the quote received

expect(quoteEl.textContent).toBe('Twain Quote');
  expect(fixture.nativeElement.querySelector('.error')).toBeNull();

vi.useRealTimers();
});
```

請注意，名言元素在第一次渲染時顯示的是佔位值（`'...'`）。
第一句名言尚未送達。

接著你就可以斷言名言元素顯示預期的文字。

### 使用 `zone.js` 與 `fakeAsync` 的非同步測試

`fakeAsync` 輔助函式是另一種模擬時鐘，它依賴以 `zone.js` 修補非同步 API。過去它常在以 `zone.js` 為基礎的應用程式中用於測試。現在已不再建議使用 `fakeAsync`。

TIP: 請優先使用原生非同步測試策略，或其他像 Vitest 或 Jasmine 提供的假計時器（也稱為模擬時鐘）。

IMPORTANT: `fakeAsync` 需要 `zone.js`。若要搭配 Vitest 測試執行器使用它，請依 [Vitest 遷移指南](guide/testing/migrating-to-vitest#zonejs-vitest-patch)所述，加入 `zone.js/plugins/vitest-patch` polyfill。

## 具有輸入與輸出的元件

具有輸入與輸出的元件，通常出現在宿主元件的檢視範本內。
宿主使用屬性繫結來設定輸入屬性，並使用事件繫結來監聽輸出屬性引發的事件。

測試的目標是驗證這類繫結是否如預期運作。
測試應該設定輸入值，並監聽輸出事件。

`DashboardHero` 元件是處於這個角色的元件的一個小範例。
它會顯示由 `Dashboard` 元件提供的單一英雄。
點選該英雄會告訴 `Dashboard` 元件：使用者已選取該英雄。

`DashboardHero` 元件像這樣內嵌在 `Dashboard` 元件範本中：

```html
@for (hero of heroes; track hero) {
  <dashboard-hero class="col-1-4" [hero]="hero" (selected)="gotoDetail($event)" />
}
```

`DashboardHero` 元件出現在一個 `@for` 區塊中，該區塊將每個元件的 `hero` 輸入屬性設為迴圈的值，並監聽元件的 `selected` 事件。

以下是元件的完整定義：

```typescript
@Component({
  selector: 'dashboard-hero',
  imports: [UpperCasePipe],
  template: `
    <button type="button" (click)="click()" class="hero">
      {{ hero().name | uppercase }}
    </button>
  `,
})
export class DashboardHero {
  readonly hero = input.required<Hero>();
  readonly selected = output<Hero>();

click() {
    this.selected.emit(this.hero());
  }
}
```

雖然測試這麼簡單的元件本身沒有多少價值，但知道怎麼做還是有用的。
請使用下列方法之一：

- 依它被 `Dashboard` 元件使用的方式來測試它
- 將它作為獨立元件來測試
- 依它被 `Dashboard` 元件的替代者使用的方式來測試它

眼前的目標是測試 `DashboardHero` 元件，而不是 `Dashboard` 元件，所以請試試第二與第三個選項。

### 以獨立方式測試 `DashboardHero` 元件

以下是規格檔案設定的核心部分。

```ts
let fixture: ComponentFixture<DashboardHero>;
let comp: DashboardHero;
let heroDe: DebugElement;
let heroEl: HTMLElement;
let expectedHero: Hero;

beforeEach(async () => {
  fixture = TestBed.createComponent(DashboardHero);
  comp = fixture.componentInstance;

// find the hero's DebugElement and element
  heroDe = fixture.debugElement.query(By.css('.hero'));
  heroEl = heroDe.nativeElement;

// mock the hero supplied by the parent component
  expectedHero = {id: 42, name: 'Test Name'};

// simulate the parent setting the input property with that hero
  fixture.componentRef.setInput('hero', expectedHero);

// wait for initial data binding
  await fixture.whenStable();
});
```

請注意，設定程式碼如何把一個測試英雄（`expectedHero`）指派給元件的 `hero` 屬性，模擬 `Dashboard` 在其重複器中使用屬性繫結設定它的方式。

下列測試驗證英雄名稱是否透過繫結傳遞到範本中。

```ts
it('should display hero name in uppercase', () => {
  const expectedPipedName = expectedHero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});
```

由於範本會讓英雄名稱通過 Angular `UpperCasePipe`，測試必須以轉成大寫的名稱來比對元素的值。

### 點選

點選英雄應該引發一個 `selected` 事件，讓宿主元件（推測是 `Dashboard`）能聽到：

```ts
it('should raise selected event when clicked (triggerEventHandler)', () => {
  let selectedHero: Hero | undefined;
  comp.selected.subscribe((hero: Hero) => (selectedHero = hero));

heroDe.triggerEventHandler('click');
  expect(selectedHero).toBe(expectedHero);
});
```

元件的 `selected` 屬性是一個 `OutputEmitterRef`，它的 `subscribe` 方法會同步通知訂閱者。
測試_明確地_訂閱它，就像宿主元件_隱含地_做的那樣。

如果元件如預期運作，點選英雄的元素應該會讓元件的 `selected` 屬性發出 `hero` 物件。

測試透過它對 `selected` 的訂閱偵測到該事件。

### `triggerEventHandler`

上一個測試中的 `heroDe` 是一個 `DebugElement`，代表英雄的 `<button>`。

它具有 Angular 的屬性與方法，抽象化了與原生元素的互動。
這個測試以「click」事件名稱呼叫 `DebugElement.triggerEventHandler`。
「click」事件繫結會以呼叫 `DashboardHero.click()` 來回應。

Angular 的 `DebugElement.triggerEventHandler` 可以依_事件名稱_引發_任何資料繫結事件_。
第二個參數是傳給處理常式的事件物件。

這個測試觸發了一個「click」事件。

```ts
heroDe.triggerEventHandler('click');
```

在這個情況下，測試正確地假設執行期事件處理常式，也就是元件的 `click()` 方法，並不在意事件物件。

HELPFUL: 其他處理常式就沒這麼寬容了。
舉例來說，`RouterLink` 指令預期事件物件帶有一個 `button` 屬性，用來識別點選期間按下了哪個滑鼠按鈕（如果有的話）。
如果事件物件缺失，`RouterLink` 指令會擲出錯誤。

### 點選元素

下列替代測試呼叫原生元素自己的 `click()` 方法，這對_這個元件_來說完全沒問題。

```ts
it('should raise selected event when clicked (element.click)', () => {
  let selectedHero: Hero | undefined;
  comp.selected.subscribe((hero: Hero) => (selectedHero = hero));

heroEl.click();
  expect(selectedHero).toBe(expectedHero);
});
```

### `click()` 輔助函式

點選按鈕、錨點或任意 HTML 元素，是常見的測試工作。

將_觸發點選_的過程封裝在像下列 `click()` 函式這樣的輔助函式中，讓這件事保持一致且簡單明瞭：

```ts
/** Button events to pass to `DebugElement.triggerEventHandler` for RouterLink event handler */
export const ButtonClickEvents = {
  left: {button: 0},
  right: {button: 2},
};

/** Simulate element click. Defaults to mouse left-button click event. */
export function click(
  el: DebugElement | HTMLElement,
  eventObj: any = ButtonClickEvents.left,
): void {
  if (el instanceof HTMLElement) {
    el.click();
  } else {
    el.triggerEventHandler('click', eventObj);
  }
}
```

第一個參數是_要點選的元素_。
如果你想的話，可以將自訂事件物件作為第二個參數傳入。
預設值是一個部分的[左鍵滑鼠事件物件](https://developer.mozilla.org/docs/Web/API/MouseEvent/button)，許多處理常式（包括 `RouterLink` 指令）都能接受它。

IMPORTANT: `click()` 輔助函式**不是** Angular 測試公用程式之一。
它是定義在_本指南範例程式碼_中的函式。
所有的範例測試都使用它。
如果你喜歡它，就將它加入你自己的輔助函式收藏中。

以下是上一個測試以點選輔助函式改寫後的版本。

```ts
it('should raise selected event when clicked (click helper with DebugElement)', () => {
  let selectedHero: Hero | undefined;
  comp.selected.subscribe((hero: Hero) => (selectedHero = hero));

click(heroDe); // click helper with DebugElement

expect(selectedHero).toBe(expectedHero);
});
```

## 位於測試宿主中的元件

前面的測試自己扮演了宿主 `Dashboard` 元件的角色。
但當 `DashboardHero` 元件正確地資料繫結到一個宿主元件時，它能正常運作嗎？

```typescript
@Component({
  imports: [DashboardHero],
  template: ` <dashboard-hero [hero]="hero" (selected)="onSelected($event)" />`,
})
class TestHost {
  hero: Hero = {id: 42, name: 'Test Name'};
  selectedHero: Hero | undefined;

onSelected(hero: Hero) {
    this.selectedHero = hero;
  }
}
```

測試宿主以它的測試英雄設定元件的 `hero` 輸入屬性。
它以自己的 `onSelected` 處理常式繫結元件的 `selected` 事件，該處理常式會將發出的英雄記錄在它的 `selectedHero` 屬性中。

稍後，測試將能檢查 `selectedHero`，驗證 `DashboardHero.selected` 事件是否發出了預期的英雄。

`test-host` 測試的設定與獨立測試的設定類似：

```ts
beforeEach(async () => {
  // create TestHost instead of DashboardHero
  fixture = TestBed.createComponent(TestHost);
  testHost = fixture.componentInstance;
  heroEl = fixture.nativeElement.querySelector('.hero');

await fixture.whenStable();
});
```

這個測試模組設定展示了兩個重要的差異：

- 它_建立_的是 `TestHost` 元件，而不是 `DashboardHero`
- `TestHost` 元件以繫結設定 `DashboardHero.hero`

`createComponent` 傳回的 `fixture` 持有的是 `TestHost` 的實例，而不是 `DashboardHero` 的實例。

建立 `TestHost` 的副作用是建立了一個 `DashboardHero`，因為後者出現在前者的範本中。
對英雄元素的查詢（`heroEl`）仍然能在測試 DOM 中找到它，儘管它在元素樹中的深度比之前更大。

這些測試本身與獨立版本幾乎完全相同：

```ts
it('should display hero name', () => {
  const expectedPipedName = testHost.hero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});

it('should raise selected event when clicked', () => {
  click(heroEl);
  // selected hero should be the same data bound hero
  expect(testHost.selectedHero).toBe(testHost.hero);
});
```

只有 selected 事件測試不同。
它確認所選的 `DashboardHero` 英雄確實透過事件繫結一路傳遞到宿主元件。

## 路由元件

_路由元件_ 是告訴 `Router` 導航到另一個元件的元件。
`Dashboard` 元件是一個_路由元件_，因為使用者可以點選儀表板上的某個_英雄按鈕_，導航到 `HeroDetail` 元件。

Angular 提供測試輔助工具，以減少樣板程式碼，並更有效地測試依賴 `HttpClient` 的程式碼。`provideRouter` 函式也可以直接用在測試模組中。

```ts
beforeEach(async () => {
  TestBed.configureTestingModule({
    providers: [
      provideRouter([{path: '**', component: Dashboard}]),
      provideHttpClientTesting(),
      HeroService,
    ],
  });
  harness = await RouterTestingHarness.create();
  comp = await harness.navigateByUrl('/', Dashboard);
  TestBed.inject(HttpTestingController).expectOne('api/heroes').flush(getTestHeroes());
});
```

下列測試點選顯示的英雄，並確認我們導航到預期的 URL。

```ts
it('should tell navigate when hero clicked', async () => {
  // get first <dashboard-hero> DebugElement
  const heroDe = harness.routeDebugElement!.query(By.css('dashboard-hero'));
  heroDe.triggerEventHandler('selected', comp.heroes[0]);

// expecting to navigate to id of the component's first hero
  const id = comp.heroes[0].id;
  expect(TestBed.inject(Router).url, 'should nav to HeroDetail for first hero').toEqual(
    `/heroes/${id}`,
  );
});
```

## 路由目標元件

_路由目標元件_ 是 `Router` 導航的目的地。
它可能比較難測試，尤其是當通往該元件的路由_包含參數_時。
`HeroDetail` 是一個_路由目標元件_，是這類路由的目的地。

當使用者點選一個 _Dashboard_ 英雄時，`Dashboard` 會告訴 `Router` 導航到 `heroes/:id`。
`:id` 是一個路由參數，其值是要編輯之英雄的 `id`。

`Router` 將該 URL 比對到通往 `HeroDetail` 的路由。
它會建立一個帶有路由資訊的 `ActivatedRoute` 物件，並將它注入到 `HeroDetail` 的新實例中。

以下是注入到 `HeroDetail` 中的服務：

```ts
private heroDetailService = inject(HeroDetailService);
private route = inject(ActivatedRoute);
private router = inject(Router);
```

`HeroDetail` 元件需要 `id` 參數，才能使用 `HeroDetailService` 取得對應的英雄。
元件必須從 `ActivatedRoute.paramMap` 屬性取得 `id`，而該屬性是一個 `Observable`。

它不能只參照 `ActivatedRoute.paramMap` 的 `id` 屬性。
元件必須_訂閱_ `ActivatedRoute.paramMap` observable，並為 `id` 在它的生命週期中變更做好準備。

```ts
constructor() {
  // get hero when `id` param changes
  this.route.paramMap.subscribe((pmap) => this.getHero(pmap.get('id')));
}
```

測試可以透過導航到不同的路由，探索 `HeroDetail` 如何回應不同的 `id` 參數值。

## 巢狀元件測試 {#nested-component-tests}

元件範本經常有巢狀元件，而這些元件的範本可能又包含更多元件。

元件樹可能非常深，有時候巢狀元件在測試樹頂端元件時並不扮演任何角色。

舉例來說，`App` 元件會顯示一個導覽列，其中有錨點與它們的 `RouterLink` 指令。

```html
<app-banner />
<app-welcome />

<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>

<router-outlet />
```

若只要驗證連結而不驗證導航，你不需要 `Router` 進行導航，也不需要 `<router-outlet>` 來標示 `Router` 插入_路由目標元件_的位置。

`Banner` 與 `Welcome` 元件（由 `<app-banner>` 與 `<app-welcome>` 表示）同樣不相關。

然而，任何在 DOM 中建立 `App` 元件的測試，也會建立這三個元件的實例，而且如果你放任這件事發生，你就必須設定 `TestBed` 來建立它們。

如果你疏於宣告它們，Angular 編譯器將無法辨識 `App` 範本中的 `<app-banner>`、`<app-welcome>` 與 `<router-outlet>` 標籤，並會擲出錯誤。

如果你宣告的是真實元件，你還必須宣告_它們的_巢狀元件，並為樹中_任何_元件注入的_所有_服務做準備。

本節描述兩種將設定工作降到最低的技巧。
你可以單獨使用它們，或合併使用，讓自己專注於測試主要元件。

### 為不需要的元件建立替身

在第一種技巧中，你建立並宣告在測試中幾乎不扮演任何角色的元件與指令的替身版本。

```ts
@Component({selector: 'app-banner', template: ''})
class BannerStub {}

@Component({selector: 'router-outlet', template: ''})
class RouterOutletStub {}

@Component({selector: 'app-welcome', template: ''})
class WelcomeStub {}
```

替身的選擇器與對應真實元件的選擇器相符。
但它們的範本與類別是空的。

接著，使用 `TestBed.overrideComponent` 覆寫你元件的 `imports` 來宣告它們。

```ts
let comp: App;
let fixture: ComponentFixture<App>;

beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    set: {
      imports: [RouterLink, BannerStub, RouterOutletStub, WelcomeStub],
    },
  });

fixture = TestBed.createComponent(App);
  comp = fixture.componentInstance;
});
```

HELPFUL: 這個範例中的 `set` 鍵會取代你元件上所有現有的 imports，請務必匯入所有相依性，不只是替身。或者，你可以使用 `remove`/`add` 鍵，選擇性地移除與加入 imports。

### `NO_ERRORS_SCHEMA`

在第二種方法中，將 `NO_ERRORS_SCHEMA` 加入你元件的中繼資料覆寫。

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    set: {
      imports: [], // resets all imports
      schemas: [NO_ERRORS_SCHEMA],
    },
  });
});
```

`NO_ERRORS_SCHEMA` 告訴 Angular 編譯器忽略無法辨識的元素與屬性。

編譯器能辨識 `<app-root>` 元素與 `routerLink` 屬性，因為你在 `TestBed` 設定中宣告了對應的 `App` 元件與 `RouterLink`。

但當編譯器遇到 `<app-banner>`、`<app-welcome>` 或 `<router-outlet>` 時，它不會擲出錯誤。
它只是將它們渲染為空標籤，瀏覽器會忽略它們。

你不再需要替身元件了。

### 兩種技巧合併使用

這些是_淺層元件測試_的技巧，會如此命名，是因為它們將元件的視覺介面縮減到只剩範本中對測試重要的元素。

`NO_ERRORS_SCHEMA` 方法是兩者中較容易的一個，但不要過度使用它。

`NO_ERRORS_SCHEMA` 也會讓編譯器無法告訴你，你不慎遺漏或拼錯的元件與屬性。
你可能會浪費好幾個小時追查編譯器本可在一瞬間抓到的幽靈錯誤。

_替身元件_ 方法還有另一個優點。
雖然_這個_範例中的替身是空的，但如果你的測試需要以某種方式與它們互動，你可以給它們精簡過的範本與類別。

實務上，你會在同一個設定中合併這兩種技巧，如這個範例所示。

```ts
beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [provideRouter([]), UserAuthentication],
  }).overrideComponent(App, {
    remove: {imports: [RouterOutlet, Welcome]},
    set: {schemas: [NO_ERRORS_SCHEMA]},
  });
});
```

Angular 編譯器為 `<app-banner>` 元素建立 `BannerStub`，並將 `RouterLink` 套用到帶有 `routerLink` 屬性的錨點上，但它會忽略 `<app-welcome>` 與 `<router-outlet>` 標籤。

### `By.directive` 與注入的指令

再多一點設定，就能觸發初始資料繫結，並取得導覽連結的參照：

```ts
beforeEach(async () => {
  await fixture.whenStable();

// find DebugElements with an attached RouterLinkStubDirective
  linkDes = fixture.debugElement.queryAll(By.directive(RouterLink));

// get attached link directive instances
  // using each DebugElement's injector
  routerLinks = linkDes.map((de) => de.injector.get(RouterLink));
});
```

有三個特別值得注意的點：

- 使用 `By.directive` 定位附有指令的錨點元素
- 查詢傳回包住相符元素的 `DebugElement` 包裝
- 每個 `DebugElement` 都暴露一個相依性注入器，帶有附加到該元素的指令之特定實例

要驗證的 `App` 元件連結如下：

```html
<nav>
  <a routerLink="/dashboard">Dashboard</a>
  <a routerLink="/heroes">Heroes</a>
  <a routerLink="/about">About</a>
</nav>
```

以下是一些確認這些連結如預期接上 `routerLink` 指令的測試：

```ts
it('can get RouterLinks from template', () => {
  expect(routerLinks.length, 'should have 3 routerLinks').toBe(3);
  expect(routerLinks[0].href).toBe('/dashboard');
  expect(routerLinks[1].href).toBe('/heroes');
  expect(routerLinks[2].href).toBe('/about');
});

it('can click Heroes link in template', async () => {
  const heroesLinkDe = linkDes[1]; // heroes link DebugElement

TestBed.inject(Router).resetConfig([{path: '**', children: []}]);
  heroesLinkDe.triggerEventHandler('click', {button: 0});

await fixture.whenStable();

expect(TestBed.inject(Router).url).toBe('/heroes');
});
```

## 使用 `page` 物件

`HeroDetail` 元件是一個簡單的檢視，帶有一個標題、兩個英雄欄位與兩個按鈕。

但即使是這麼簡單的表單，範本也有不少複雜度。

```html
@if (hero) {
  <div>
    <h2>
      <span>{{ hero.name | titlecase }}</span> Details
    </h2>
    <div><span>id: </span>{{ hero.id }}</div>
    <div>
      <label for="name">name: </label>
      <input id="name" [(ngModel)]="hero.name" placeholder="name" />
    </div>
    <button type="button" (click)="save()">Save</button>
    <button type="button" (click)="cancel()">Cancel</button>
  </div>
}
```

操作這個元件的測試需要……

- 等到英雄送達後，元素才會出現在 DOM 中
- 取得標題文字的參照
- 取得名稱輸入框的參照，以檢查並設定它
- 取得兩個按鈕的參照，以便點選它們

即使是這樣的小表單，也可能產生一團混亂、充滿折磨人的條件式設定與 CSS 元素選取。

以一個 `Page` 類別馴服這份複雜度，它負責處理對元件屬性的存取，並封裝設定它們的邏輯。

以下是一個用於 `hero-detail.component.spec.ts` 的 `Page` 類別：

```ts
class Page {
  // getter properties wait to query the DOM until called.
  get buttons() {
    return this.queryAll<HTMLButtonElement>('button');
  }
  get saveBtn() {
    return this.buttons[0];
  }
  get cancelBtn() {
    return this.buttons[1];
  }
  get nameDisplay() {
    return this.query<HTMLElement>('span');
  }
  get nameInput() {
    return this.query<HTMLInputElement>('input');
  }

//// query helpers ////
  private query<T>(selector: string): T {
    return harness.routeNativeElement!.querySelector(selector)! as T;
  }

private queryAll<T>(selector: string): T[] {
    return harness.routeNativeElement!.querySelectorAll(selector) as any as T[];
  }
}
```

現在，用於操作與檢查元件的重要掛鉤都整齊地組織起來，並可從 `Page` 的實例存取。

一個 `createComponent` 方法會建立一個 `page` 物件，並在 `hero` 送達後填補空白。

```ts
async function createComponent(id: number) {
  harness = await RouterTestingHarness.create();
  component = await harness.navigateByUrl(`/heroes/${id}`, HeroDetail);
  page = new Page();

const request = TestBed.inject(HttpTestingController).expectOne(`api/heroes/?id=${id}`);
  const hero = getTestHeroes().find((h) => h.id === Number(id));
  request.flush(hero ? [hero] : []);
  await harness.fixture.whenStable();
}
```

以下再列舉幾個 `HeroDetail` 元件測試來強化這個重點。

```ts
it("should display that hero's name", () => {
  expect(page.nameDisplay.textContent).toBe(expectedHero.name);
});

it('should navigate when click cancel', () => {
  click(page.cancelBtn);
  expect(TestBed.inject(Router).url).toEqual(`/heroes/${expectedHero.id}`);
});

it('should save when click save but not navigate immediately', () => {
  click(page.saveBtn);
  expect(TestBed.inject(HttpTestingController).expectOne({method: 'PUT', url: 'api/heroes'}));
  expect(TestBed.inject(Router).url).toEqual('/heroes/41');
});

it('should navigate when click save and save resolves', async () => {
  click(page.saveBtn);
  await harness.fixture.whenStable();
  expect(TestBed.inject(Router).url).toEqual('/heroes/41');
});

it('should convert hero name to Title Case', async () => {
  // get the name's input and display elements from the DOM
  const hostElement: HTMLElement = harness.routeNativeElement!;
  const nameInput: HTMLInputElement = hostElement.querySelector('input')!;
  const nameDisplay: HTMLElement = hostElement.querySelector('span')!;

// simulate user entering a new name into the input box
  nameInput.value = 'quick BROWN  fOx';

// Dispatch a DOM event so that Angular learns of input value change.
  nameInput.dispatchEvent(new Event('input'));

// Wait for Angular to update the display binding through the title pipe
  await harness.fixture.whenStable();

expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
```

## 覆寫元件的提供者 {#override-component-providers}

`HeroDetail` 提供它自己的 `HeroDetailService`。

```ts
@Component({
  /* ... */
  providers: [HeroDetailService],
})
export class HeroDetail {
  private heroDetailService = inject(HeroDetailService);
  private route = inject(ActivatedRoute);
  private router = inject(Router);
}
```

在 `TestBed.configureTestingModule` 的 `providers` 中無法為元件的 `HeroDetailService` 建立替身。
那些是_測試模組_的提供者，不是元件的。
它們準備的是 _fixture 層級_的相依性注入器。

Angular 以它_自己的_注入器建立元件，而該注入器是 fixture 注入器的_子注入器_。
它向子注入器註冊元件的提供者（在這個例子中是 `HeroDetailService`）。

測試無法從 fixture 注入器取得子注入器的服務。
`TestBed.configureTestingModule` 也無法設定它們。

Angular 一直以來建立的都是真實 `HeroDetailService` 的新實例！

HELPFUL: 如果 `HeroDetailService` 自己向遠端伺服器發出 XHR 呼叫，這些測試可能會失敗或逾時。
可能根本沒有遠端伺服器可以呼叫。

所幸，`HeroDetailService` 將遠端資料存取的責任委派給注入的 `HeroService`。

```ts
@Service()
export class HeroDetailService {
  private heroService = inject(HeroService);
}
```

先前的測試設定將真實的 `HeroService` 換成 `TestHeroService`，由它攔截伺服器請求並偽造回應。

但如果你沒有這麼幸運呢？
如果偽造 `HeroService` 很困難呢？
如果 `HeroDetailService` 自己發出伺服器請求呢？

`TestBed.overrideComponent` 方法可以將元件的 `providers` 換成容易管理的_測試替身_，如以下設定變體所示：

```ts
beforeEach(async () => {
  await TestBed.configureTestingModule({
    providers: [
      provideRouter([
        {path: 'heroes', component: HeroList},
        {path: 'heroes/:id', component: HeroDetail},
      ]),
      // HeroDetailService at this level is IRRELEVANT!
      {provide: HeroDetailService, useValue: {}},
    ],
  }).overrideComponent(HeroDetail, {
    set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
  });
});
```

請注意，`TestBed.configureTestingModule` 不再提供假的 `HeroService`，因為它[不需要了](#provide-a-spy-stub-herodetailservicespy)。

### `overrideComponent` 方法

請聚焦在 `overrideComponent` 方法上。

```ts
.overrideComponent(HeroDetail, {
  set: {providers: [{provide: HeroDetailService, useClass: HeroDetailServiceSpy}]},
});
```

它接受兩個參數：要覆寫的元件型別（`HeroDetail`）與一個覆寫中繼資料物件。
[覆寫中繼資料物件](/guide/testing/utility-apis#testbed-class-summary)是一個泛型，定義如下：

```ts
type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```

中繼資料覆寫物件可以在中繼資料屬性中加入與移除元素，或完全重設那些屬性。
這個範例重設了元件的 `providers` 中繼資料。

型別參數 `T` 是你會傳給 `@Component` 裝飾器的中繼資料種類：

```ts
selector?: string;
template?: string;
templateUrl?: string;
providers?: any[];
…
```

### 提供 _spy 替身_（`HeroDetailServiceSpy`） {#provide-a-spy-stub-herodetailservicespy}

這個範例將元件的 `providers` 陣列完全換成一個新陣列，其中包含一個 `HeroDetailServiceSpy`。

`HeroDetailServiceSpy` 是真實 `HeroDetailService` 的替身版本，它偽造了該服務所有必要的功能。
它既不注入也不委派給較低層級的 `HeroService`，因此不需要為後者提供測試替身。

相關的 `HeroDetail` 元件測試會透過監控服務方法，來斷言 `HeroDetailService` 的方法有被呼叫。
因此，這個替身將它的方法實作為 spy：

```ts
import {vi} from 'vitest';

class HeroDetailServiceSpy {
  testHero: Hero = {...testHero};

/* emit cloned test hero */
  getHero = vi.fn(() => asyncData({...this.testHero}));

/* emit clone of test hero, with changes merged in */
  saveHero = vi.fn((hero: Hero) => asyncData(Object.assign(this.testHero, hero)));
}
```

### 覆寫測試

現在，測試可以直接操控替身的 `testHero` 來控制元件的英雄，並確認服務方法有被呼叫。

```ts
let hdsSpy: HeroDetailServiceSpy;

beforeEach(async () => {
  harness = await RouterTestingHarness.create();
  component = await harness.navigateByUrl(`/heroes/${testHero.id}`, HeroDetail);
  page = new Page();
  // get the component's injected HeroDetailServiceSpy
  hdsSpy = harness.routeDebugElement!.injector.get(HeroDetailService) as any;

harness.detectChanges();
});

it('should have called `getHero`', () => {
  expect(hdsSpy.getHero, 'getHero called once').toHaveBeenCalledTimes(1);
});

it("should display stub hero's name", () => {
  expect(page.nameDisplay.textContent).toBe(hdsSpy.testHero.name);
});

it('should save stub hero change', async () => {
  const origName = hdsSpy.testHero.name;
  const newName = 'New Name';

page.nameInput.value = newName;

page.nameInput.dispatchEvent(new Event('input')); // tell Angular

expect(component.hero.name, 'component hero has new name').toBe(newName);
  expect(hdsSpy.testHero.name, 'service hero unchanged before save').toBe(origName);

click(page.saveBtn);
  expect(hdsSpy.saveHero, 'saveHero called once').toHaveBeenCalledTimes(1);

await harness.fixture.whenStable();
  expect(hdsSpy.testHero.name, 'service hero has new name after save').toBe(newName);
  expect(TestBed.inject(Router).url).toEqual('/heroes');
});
```

### 更多覆寫

`TestBed.overrideComponent` 方法可以針對相同或不同的元件呼叫多次。
`TestBed` 也提供類似的 `overrideDirective`、`overrideModule` 與 `overridePipe` 方法，用來深入並取代這些其他類別的部分內容。

請自行探索這些選項與組合。
# 為測試除錯

如果測試沒有如預期運作，你可以在預設的 Node.js 環境與真實瀏覽器中為它們除錯。

## 在 Node.js 中除錯

在預設的 Node.js 環境中除錯，通常是診斷與瀏覽器專屬 API 或渲染無關之問題最快的方法。

1.  以 `--debug` 旗標執行 `ng test` 指令：
    ```shell
ng test --debug
    ```
2.  測試執行器會以除錯模式啟動，並等待除錯器連接。
3.  現在你可以連接慣用的除錯器。例如，你可以使用 VS Code 內建的 Node.js 除錯器，或用於 Node.js 的 Chrome DevTools。

## 在瀏覽器中除錯

如同在 Node 中啟動除錯工作階段，你也可以搭配 Vitest 與[瀏覽器模式](/guide/testing/migrating-to-vitest#5-configure-browser-mode-optional)使用帶有 `--debug` 旗標的 `ng test`。

測試執行器會以除錯模式啟動，並等待你開啟瀏覽器開發者工具來為測試除錯。
# 測試工具 API

NOTE: 本指南正陸續更新為 Vitest 版本，目前部分工具 API 的說明與範例仍以 Karma/Jasmine 的情境呈現。我們正積極提供 Vitest 的對等內容與更新後的指引。

本頁說明最實用的 Angular 測試功能。

Angular 測試工具包括 `TestBed`、`ComponentFixture`，以及一些控制測試環境的函式。
[`TestBed`](#testbed-class-summary) 與 [`ComponentFixture`](#the-componentfixture) 類別另有專節說明。

以下是獨立函式的摘要，依可能的實用程度排序：

| Function     | Details                                                                                                                                                                                                                                                      |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`inject`]   | 將目前 `TestBed` 注入器中的一或多個服務注入測試函式。它無法注入由元件本身提供的服務。請參閱 [debugElement.injector](guide/testing/components-scenarios#get-injected-services) 的討論。 |
| `getTestBed` | 取得 `TestBed` 的目前實例。通常不需要使用，因為 `TestBed` 類別的靜態類別方法一般就已足夠。`TestBed` 實例公開了一些較少使用、且沒有靜態方法版本的成員。         |

如需處理複雜的非同步情境，或測試舊版以 Zone.js 為基礎的應用程式，請參閱 [Zone.js 測試工具](guide/testing/zone-js-testing-utilities) 指南。

## `TestBed` 類別摘要 {#testbed-class-summary}

`TestBed` 類別是主要的 Angular 測試工具之一。
它的 API 相當龐大，在你逐漸探索之前可能會覺得難以招架。
請先閱讀本指南前面的部分掌握基礎，再試著理解完整的 API。

傳入 `configureTestingModule` 的模組定義，是 `@NgModule` 中繼資料屬性的子集。

```ts
type TestModuleMetadata = {
  providers?: any[];
  declarations?: any[];
  imports?: any[];
  schemas?: Array<SchemaMetadata | any[]>;
};
```

每個覆寫方法都接受一個 `MetadataOverride<T>`，其中 `T` 是適合該方法的中繼資料種類，也就是 `@NgModule`、`@Component`、`@Directive` 或 `@Pipe` 的參數。

```ts
type MetadataOverride<T> = {
  add?: Partial<T>;
  remove?: Partial<T>;
  set?: Partial<T>;
};
```

`TestBed` API 由靜態類別方法組成，這些方法不是更新、就是引用 `TestBed` 的_全域_實例。

在內部，所有靜態方法都是目前執行期 `TestBed` 實例的方法的包裝，而該實例也會由 `getTestBed()` 函式傳回。

請在 `beforeEach()` _內_呼叫 `TestBed` 方法，確保每個個別測試開始前都是全新狀態。

以下是最重要的靜態方法，依可能的實用程度排序。

| Methods                  | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `configureTestingModule` | 測試墊片會建立[初始測試環境](guide/testing)與預設的測試模組。預設測試模組設定了基本的宣告式成員，以及每位測試者都需要的一些 Angular 服務替代實作。<br /> 呼叫 `configureTestingModule`，可以加入與移除匯入、宣告（元件、指令與管道）及 providers，為特定的測試組調整測試模組設定。                                                                                               |
| `compileComponents`      | 在你完成測試模組的設定後，以非同步方式編譯該模組。如果測試模組的_任何_元件具有非同步載入的資源（例如 @defer 區塊），你**必須**呼叫這個方法。                                                                                                                                                                                                                                                                                                                                       |
| `createComponent<T>`     | 根據目前的 `TestBed` 設定，建立型別為 `T` 的元件實例。呼叫 `createComponent` 之後，`TestBed` 設定會在目前規格的執行期間凍結。                                                                                                                                                                                                                                                                                                                                                 |
| `overrideComponent`      | 取代指定元件類別的中繼資料，該元件可能深藏在內層模組之中。                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `overrideDirective`      | 取代指定指令類別的中繼資料，該指令可能深藏在內層模組之中。                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `overridePipe`           | 取代指定管道類別的中繼資料，該管道可能深藏在內層模組之中。                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `overrideModule`         | 取代指定的 `NgModule`。請記住，模組可以匯入其他模組。`overrideModule` 方法可以深入目前的測試模組，修改其中某個內層模組。                                                                                                                                                                                                                                                                                                                                              |
| `inject`                 | 從目前的 `TestBed` 注入器取得服務。`inject` 函式通常就足以勝任此用途。但若 `inject` 無法提供該服務，就會擲出錯誤。<br /> 如果該服務是選用的，該怎麼辦？<br /> `TestBed.inject()` 方法接受一個選用的第二個參數，也就是 Angular 找不到 provider 時要傳回的物件（此例為 `null`）：`expect(TestBed.inject(NotProvided, null)).toBeNull();` 呼叫 `TestBed.inject` 之後，`TestBed` 設定會在目前規格的執行期間凍結。 |
| `initTestEnvironment`    | 為整個測試執行初始化測試環境。<br /> 測試墊片會為你呼叫它，所以你幾乎不需要自己呼叫。<br /> 這個方法只能呼叫_恰好一次_。若要在測試執行中途變更這個預設值，請先呼叫 `resetTestEnvironment`。<br /> 指定一個預設的 Angular 測試模組與一個 `PlatformRef`。非瀏覽器平台的替代方案可在 `@angular/platform-<platform_name>/testing` 這個一般形式下取得。                                                                  |
| `resetTestEnvironment`   | 重設初始測試環境，包括預設的測試模組。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

少數 `TestBed` 實例方法沒有對應的靜態 `TestBed` _類別_方法。
這些方法很少需要使用。

## `ComponentFixture` {#the-componentfixture}

`TestBed.createComponent<T>` 會建立元件 `T` 的實例，並為該元件傳回強型別的 `ComponentFixture`。

`ComponentFixture` 的屬性與方法提供對元件、其 DOM 表示方式，以及其 Angular 環境各方面的存取。

### `ComponentFixture` 屬性

以下是對測試者最重要的屬性，依可能的實用程度排序。

| Properties          | Details                                                                                                                                                                                                                                                                                   |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentInstance` | 由 `TestBed.createComponent` 建立的元件類別實例。                                                                                                                                                                                                                 |
| `debugElement`      | 與元件根元素相關聯的 `DebugElement`。<br /> `debugElement` 讓你在測試與除錯期間深入了解元件及其 DOM 元素。這是測試者的關鍵屬性。最值得關注的成員在[下文](#debugelement)說明。 |
| `nativeElement`     | 位於元件根部的原生 DOM 元素。                                                                                                                                                                                                                                      |
| `changeDetectorRef` | 元件宿主檢視的 `ChangeDetectorRef`，不是元件本身的。請參閱[在 `TestBed` 中使用 Zoneless](guide/zoneless#using-zoneless-in-testbed)。                                                                                                                           |

### `ComponentFixture` 方法

_fixture_ 方法會讓 Angular 對元件樹執行某些工作。
呼叫這些方法，可以觸發 Angular 行為以回應模擬的使用者動作。

以下是最實用的方法。

| Methods             | Details                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detectChanges`     | 為元件觸發一個變更偵測週期。<br /> 呼叫它來初始化元件（它會呼叫 `ngOnInit`），以及在測試程式碼變更元件的資料繫結屬性值之後呼叫。Angular 無法得知你已變更 `personComponent.name`，在你呼叫 `detectChanges` 之前，不會更新 `name` 繫結。<br /> 之後會執行 `checkNoChanges`，確認沒有循環更新，除非以 `detectChanges(false)` 的方式呼叫；                                                                                                           |
| `autoDetectChanges` | 當你希望 fixture 自動偵測變更時，將它設為 `true`。<br /> 當自動偵測為 `true` 時，測試 fixture 會在建立元件後立即呼叫 `detectChanges`。接著它會監聽相關的 zone 事件，並相應地呼叫 `detectChanges`。當你的測試程式碼直接修改元件屬性值時，你可能仍然必須呼叫 `fixture.detectChanges` 來觸發資料繫結更新。<br /> 使用 zoneless 變更偵測時（`TestBed` 的預設值），預設為 `true`；使用以 Zone 為基礎的變更偵測時，預設為 `false`。 |
| `checkNoChanges`    | 執行一次變更偵測，確保沒有待處理的變更。若有變更則擲出例外。                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `isStable`          | 若 fixture 目前_穩定_，傳回 `true`。若有尚未完成的非同步工作，傳回 `false`。                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `whenStable`        | 傳回一個在 fixture 穩定時完成的 promise。<br /> 若要在非同步活動或非同步變更偵測完成後繼續測試，請掛接該 promise。請參閱 [whenStable](guide/testing/components-scenarios#whenstable)。                                                                                                                                                                                                                                                                                                                          |
| `destroy`           | 觸發元件銷毀。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

#### `DebugElement` {#debugelement}

`DebugElement` 提供對元件 DOM 表示方式的關鍵洞察。

從測試根元件由 `fixture.debugElement` 傳回的 `DebugElement`，你可以走訪（並查詢）fixture 的整個元素與元件子樹。

以下是對測試者最實用的 `DebugElement` 成員，依大約的實用程度排序：

| Members               | Details                                                                                                                                                                                                                                                                                                                                         |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nativeElement`       | 瀏覽器中對應的 DOM 元素                                                                                                                                                                                                                                                                                                    |
| `query`               | 呼叫 `query(predicate: Predicate<DebugElement>)`，傳回子樹中任意深度第一個符合述詞的 `DebugElement`。                                                                                                                                                                                                    |
| `queryAll`            | 呼叫 `queryAll(predicate: Predicate<DebugElement>)`，傳回子樹中任意深度所有符合述詞的 `DebugElement`。                                                                                                                                                                                                          |
| `injector`            | 宿主的相依性注入器。例如，根元素的元件實例注入器。                                                                                                                                                                                                                                                      |
| `componentInstance`   | 元素自身的元件實例（如果有的話）。                                                                                                                                                                                                                                                                                            |
| `context`             | 提供此元素父層上下文的物件。通常是掌管此元素的祖先元件實例。<br /> 當元素在 `@for` 區塊內重複時，其 context 是一個 `RepeaterContext`，其 `$implicit` 屬性是該列實例的值。例如 `@for(hero of heroes; ...)` 中的 `hero`。 |
| `children`            | 直接的 `DebugElement` 子元素。透過 `children` 逐層往下走訪整棵樹。`DebugElement` 也有 `childNodes`，是 `DebugNode` 物件的清單。`DebugElement` 源自 `DebugNode` 物件，而且節點的數量往往比元素多。測試者通常可以忽略純節點。                                               |
| `parent`              | `DebugElement` 的父元素。若這是根元素，則為 Null。                                                                                                                                                                                                                                                                                    |
| `name`                | 元素的標籤名稱（如果它是元素的話）。                                                                                                                                                                                                                                                                                                      |
| `triggerEventHandler` | 若元素的 `listeners` 集合中有對應的監聽器，則依名稱觸發該事件。第二個參數是處理常式預期的_事件物件_。 <br /> 若事件缺少監聽器，或有其他問題，請考慮呼叫 `nativeElement.dispatchEvent(eventObject)`。                               |
| `listeners`           | 附加在元件 `@Output` 屬性及／或元素事件屬性上的回呼。                                                                                                                                                                                                                                           |
| `providerTokens`      | 此元件的注入器查找權杖。包括元件本身，加上元件在其 `providers` 中繼資料中所列的權杖。                                                                                                                                                                                                    |
| `references`          | 與範本區域變數相關聯的物件字典（例如 `#foo`），以區域變數名稱為鍵。                                                                                                                                                                                                                       |

`DebugElement.query(predicate)` 與 `DebugElement.queryAll(predicate)` 方法接受一個述詞，用來篩選來源元素的子樹，找出符合的 `DebugElement`。

述詞可以是任何接受 `DebugElement` 並傳回_真值_的方法。
下列範例找出所有具有名為 "content" 的範本區域變數參照的 `DebugElement`：

```ts
// Filter for DebugElements with a #content reference
const contentRefs = el.queryAll((de) => de.references['content']);
```

Angular 的 `By` 類別有三個靜態方法，用於常見的述詞：

```ts
// Can find DebugElement either by css selector or by directive
const h2 = fixture.debugElement.query(By.css('h2'));
const directive = fixture.debugElement.query(By.directive(Highlight));
```
# 元件測試工具總覽

<strong>元件測試工具</strong>（component harness）是一個類別，讓測試能透過受支援的 API，以終端使用者與元件互動的方式與元件互動。你可以為任何元件建立測試工具，從小型可重複使用的小工具到完整頁面都行。

測試工具有幾個好處：

- 它們讓測試不那麼脆弱，因為它們隔絕了元件的實作細節，例如其 DOM 結構
- 它們讓測試更易讀、更容易維護
- 它們可以在多個測試環境中使用

```ts
// Example of test with a harness for a component called MyButtonComponent
it('should load button with exact text', async () => {
  const button = await loader.getHarness(MyButtonComponentHarness);
  expect(await button.getText()).toBe('Confirm');
});
```

元件測試工具對共用的 UI 小工具特別有用。開發者經常撰寫仰賴小工具私有實作細節的測試，例如 DOM 結構與 CSS 類別。這些依賴讓測試變得脆弱且難以維護。測試工具提供了一個替代方案——一個受支援的 API，以與終端使用者相同的方式與小工具互動。如此一來，小工具的實作變更就不太可能弄壞使用者的測試。例如，[Angular Material](https://material.angular.dev/components/categories) 為函式庫中的每個元件都提供了測試工具。

元件測試工具支援多個測試環境。你可以在單元測試與端到端測試中使用相同的測試工具實作。測試作者只需要學習一套 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)。
# 在測試中使用元件測試工具（component harness）

## 開始之前

TIP: 本指南假設你已閱讀過[元件測試工具總覽指南](guide/testing/component-harnesses-overview)。如果你是第一次使用元件測試工具，請先閱讀該指南。

### 安裝 CDK

[Component Dev Kit (CDK)](https://material.angular.dev/cdk/categories) 是一組用來建構元件的行為基礎元件。若要使用元件測試工具，先從 npm 安裝 `@angular/cdk`。你可以在終端機中使用 Angular CLI 完成安裝：

```shell
ng add @angular/cdk
```

## 測試工具環境與載入器 {#test-harness-environments-and-loaders}

你可以在不同的測試環境中使用元件測試工具。Angular CDK 支援兩種內建環境：

- 使用 Angular `TestBed` 的單元測試
- 使用 [WebDriver](https://developer.mozilla.org/en-US/docs/Web/WebDriver) 的端到端測試

每個環境都提供一個<strong>測試工具載入器</strong>。載入器負責建立你在測試中使用的測試工具實例。關於受支援測試環境的更具體指引，請見下文。

其他測試環境需要自訂綁定。更多資訊請參閱[為其他測試環境加入測試工具支援指南](guide/testing/component-harnesses-testing-environments)。

### 在單元測試中使用 `TestbedHarnessEnvironment` 的載入器

在單元測試中，你可以從 [TestbedHarnessEnvironment](/api/cdk/testing/testbed/TestbedHarnessEnvironment) 建立測試工具載入器。這個環境使用由 Angular `TestBed` 建立的[元件 fixture](api/core/testing/ComponentFixture)。

若要建立以 fixture 根元素為根的測試工具載入器，請使用 `loader()` 方法：

```ts
const fixture = TestBed.createComponent(MyComponent);

// Create a harness loader from the fixture
const loader = TestbedHarnessEnvironment.loader(fixture);
...

// Use the loader to get harness instances
const myComponentHarness = await loader.getHarness(MyComponent);
```

若要為 fixture 之外的元素建立測試工具載入器，請使用 `documentRootLoader()` 方法。例如，顯示浮動元素或彈出視窗的程式碼，通常會將 DOM 元素直接附加到文件主體上，例如 Angular CDK 中的 `Overlay` 服務。

你也可以直接使用 `harnessForFixture()`，為該 fixture 根元素處的測試工具建立載入器。

### 在端到端測試中使用 `SeleniumWebDriverHarnessEnvironment` 的載入器

在以 WebDriver 為基礎的端到端測試中，你可以使用 `SeleniumWebDriverHarnessEnvironment` 建立測試工具載入器。

使用 `loader()` 方法取得目前 HTML 文件的測試工具載入器實例，其根為文件的根元素。這個環境使用 WebDriver 用戶端。

```ts
let wd: webdriver.WebDriver = getMyWebDriverClient();
const loader = SeleniumWebDriverHarnessEnvironment.loader(wd);
...
const myComponentHarness = await loader.getHarness(MyComponent);
```

## 使用測試工具載入器

測試工具載入器實例對應到特定的 DOM 元素，用來為該元素底下的元素建立元件測試工具實例。

若要取得元素第一個實例的 `ComponentHarness`，請使用 `getHarness()` 方法。若要取得所有 `ComponentHarness` 實例，請使用 `getAllHarnesses()` 方法。

```ts
// Get harness for first instance of the element
const myComponentHarness = await loader.getHarness(MyComponent);

// Get harnesses for all instances of the element
const myComponentHarnesses = await loader.getAllHarnesses(MyComponent);
```

除了 `getHarness` 與 `getAllHarnesses` 之外，`HarnessLoader` 還有幾個其他實用的方法可用來查詢測試工具：

- `getHarnessAtIndex(...)`：取得在特定索引處符合指定條件的元件測試工具。
- `countHarnesses(...)`：計算符合指定條件的元件實例數量。
- `hasHarness(...)`：檢查是否至少有一個元件實例符合指定條件。

舉例來說，想像一個可重複使用的對話方塊按鈕元件，按下後會開啟對話方塊。它包含下列元件，每個元件都有對應的測試工具：

- `MyDialogButton`（組合 `MyButton` 與 `MyDialog`，提供方便的 API）
- `MyButton`（標準的按鈕元件）
- `MyDialog`（由 `MyDialogButton` 在點擊時附加到 `document.body` 的對話方塊）

下列測試會載入這些元件各自的測試工具：

```ts
let fixture: ComponentFixture<MyDialogButton>;
let loader: HarnessLoader;
let rootLoader: HarnessLoader;

beforeEach(() => {
  fixture = TestBed.createComponent(MyDialogButton);
  loader = TestbedHarnessEnvironment.loader(fixture);
  rootLoader = TestbedHarnessEnvironment.documentRootLoader(fixture);
});

it('loads harnesses', async () => {
  // 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
});
```

### 測試工具在不同環境中的行為

測試工具在所有環境中的行為未必完全相同。真正的使用者互動與單元測試中產生的模擬事件之間，有些差異無可避免。Angular CDK 會盡最大努力，在可能的範圍內讓行為一致。

### 與子元素互動

若要與此測試工具載入器根元素底下的元素互動，請使用子元素的 `HarnessLoader` 實例。對於子元素的第一個實例，請使用 `getChildLoader()` 方法。對於子元素的所有實例，請使用 `getAllChildLoaders()` 方法。

```ts
const myComponentHarness = await loader.getHarness(MyComponent);

// Get loader for first instance of child element with '.child' selector
const childLoader = await loader.getChildLoader('.child');

// Get loaders for all instances of child elements with '.child' selector
const allChildLoaders = await loader.getAllChildLoaders('.child');
```

### 篩選測試工具 {#filtering-harnesses}

當頁面包含某個元件的多個實例時，你可能會想根據元件的某個屬性來篩選，以取得特定的元件實例。你可以使用<strong>測試工具述詞</strong>來做到這一點；它是一個類別，用來將 `ComponentHarness` 類別與可用來篩選元件實例的述詞函式關聯起來。

當你向 `HarnessLoader` 請求一個測試工具時，你實際上提供的是 HarnessQuery。查詢可以是下列兩者之一：

- 測試工具建構函式。這只會取得該測試工具
- `HarnessPredicate`，會取得依一或多個條件篩選後的測試工具

`HarnessPredicate` 支援一些基礎篩選條件（selector、ancestor），適用於任何繼承 `ComponentHarness` 的類別。

```ts
// Example of loading a MyButtonComponentHarness with a harness predicate
const disabledButtonPredicate = new HarnessPredicate(MyButtonComponentHarness, {
  selector: '[disabled]',
});
const disabledButton = await loader.getHarness(disabledButtonPredicate);
```

不過，測試工具通常會實作一個靜態 `with()` 方法，接受元件專屬的篩選選項，並傳回 `HarnessPredicate`。

```ts
// Example of loading a MyButtonComponentHarness with a specific selector
const button = await loader.getHarness(MyButtonComponentHarness.with({selector: 'btn'}));
```

更多細節請參閱各測試工具的文件，因為額外的篩選選項是每個測試工具實作各自專屬的。

## 使用測試工具 API

雖然每個測試工具都定義了對應元件專屬的 API，但它們全都共用一個共同的基礎類別 [ComponentHarness](/api/cdk/testing/ComponentHarness)。這個基礎類別定義了一個靜態屬性 `hostSelector`，用來將測試工具類別與 DOM 中的元件實例對應起來。

除此之外，任何測試工具的 API 都專屬於其對應的元件；請參閱該元件的文件，了解如何使用特定的測試工具。

舉例來說，以下是使用 [Angular Material 滑桿元件測試工具](https://material.angular.dev/components/slider/api#MatSliderHarness) 的元件測試：

```ts
it('should get value of slider thumb', async () => {
  const slider = await loader.getHarness(MatSliderHarness);
  const thumb = await slider.getEndThumb();
  expect(await thumb.getValue()).toBe(50);
});
```

## 與 Angular 變更偵測的互動

預設情況下，測試工具會在讀取 DOM 元素的狀態之前，以及與 DOM 元素互動之後，執行 Angular 的[變更偵測](/best-practices/runtime-performance)。

有些時候，你需要在測試中更細緻地控制變更偵測，例如在非同步操作尚在進行時檢查元件的狀態。在這些情況下，請使用 `manualChangeDetection` 函式，為一段程式碼停用變更偵測的自動處理。

```ts
it('checks state while async action is in progress', async () => {
  const buttonHarness = await loader.getHarness(MyButtonHarness);
  await manualChangeDetection(async () => {
    await buttonHarness.click();
    fixture.detectChanges();
    // Check expectations while async click operation is in progress.
    expect(isProgressSpinnerVisible()).toBe(true);
    await fixture.whenStable();
    // Check expectations after async click operation complete.
    expect(isProgressSpinnerVisible()).toBe(false);
  });
});
```

幾乎所有測試工具方法都是非同步的，並傳回 `Promise`，以支援下列需求：

- 支援單元測試
- 支援端到端測試
- 讓測試不受非同步行為變更的影響

Angular 團隊建議使用 [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) 來提升測試的可讀性。呼叫 `await` 會阻擋測試的執行，直到相關的 `Promise` 完成為止。

偶爾，你可能會想同時執行多個動作，並等到它們全部完成，而不是依序執行每個動作。例如，讀取單一元件的多個屬性。在這些情況下，請使用 `parallel` 函式來平行化這些操作。`parallel` 函式的運作方式與 `Promise.all` 類似，同時也會最佳化變更偵測的檢查。

```ts
it('reads properties in parallel', async () => {
  const checkboxHarness = await loader.getHarness(MyCheckboxHarness);
  // Read the checked and intermediate properties simultaneously.
  const [checked, indeterminate] = await parallel(() => [
    checkboxHarness.isChecked(),
    checkboxHarness.isIndeterminate(),
  ]);
  expect(checked).toBe(false);
  expect(indeterminate).toBe(true);
});
```
# 為你的元件建立元件測試工具

## 開始之前

TIP: 本指南假設你已經閱讀過[元件測試工具總覽指南](guide/testing/component-harnesses-overview)。如果你還不熟悉元件測試工具的用法，請先閱讀該指南。

### 什麼時候適合建立元件測試工具？

Angular 團隊建議，為在許多地方使用且具備一定使用者互動性的共用元件建立元件測試工具。這最常見於小工具程式庫與類似的可重用元件。元件測試工具對這類情境很有價值，因為它們為這些共用元件的使用者提供了一套受到完善支援的 API 來與元件互動。使用元件測試工具的測試可以避免依賴這些共用元件不可靠的實作細節，例如 DOM 結構與特定的事件監聽器。

對於只出現在單一位置的元件，例如應用程式中的某個頁面，元件測試工具帶來的效益就沒那麼大。在這類情境中，元件的測試可以合理地依賴該元件的實作細節，因為測試與元件會在同一時間更新。不過，如果你會在單元測試與端到端測試中都使用同一個元件測試工具，它仍然能提供一些價值。

### CDK 安裝

[Component Dev Kit (CDK)](https://material.angular.dev/cdk/categories) 是一組建構元件用的行為基礎元件。若要使用元件測試工具，請先從 npm 安裝 `@angular/cdk`。你可以在終端機中使用 Angular CLI 完成安裝：

```shell
ng add @angular/cdk
```

## 擴充 `ComponentHarness`

抽象類別 `ComponentHarness` 是所有元件測試工具的基底類別。若要建立自訂的元件測試工具，請擴充 `ComponentHarness` 並實作靜態屬性 `hostSelector`。

`hostSelector` 屬性用來識別 DOM 中符合這個元件測試工具子類別的元素。在大多數情況下，`hostSelector` 應該與對應的 `Component` 或 `Directive` 的選擇器相同。舉例來說，考慮一個簡單的彈出式元件：

```ts
@Component({
  selector: 'my-popup',
  template: `
    <button (click)="toggle()">{{ triggerText() }}</button>
    @if (isOpen()) {
      <div class="my-popup-content"><ng-content /></div>
    }
  `,
})
class MyPopup {
  triggerText = input('');

isOpen = signal(false);

toggle() {
    this.isOpen.update((value) => !value);
  }
}
```

在這個例子中，這個元件最精簡的元件測試工具如下所示：

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';
}
```

雖然 `ComponentHarness` 子類別只需要 `hostSelector` 屬性，但大多數元件測試工具也應該實作靜態的 `with` 方法來產生 `HarnessPredicate` 實例。[篩選元件測試工具一節](guide/testing/using-component-harnesses#filtering-harnesses)會更詳細地說明這一點。

## 在元件的 DOM 中尋找元素

`ComponentHarness` 子類別的每個實例都代表對應元件的一個特定實例。你可以透過 `ComponentHarness` 基底類別的 `host()` 方法取得元件的宿主元素。

`ComponentHarness` 也提供了數個在元件 DOM 中定位元素的方法。這些方法是 `locatorFor()`、`locatorForOptional()` 與 `locatorForAll()`。這些方法建立的是用來尋找元素的函式，它們並不直接尋找元素。這種做法可以避免快取到過時元素的參照。舉例來說，當一個 `@if` 區塊先隱藏再顯示某個元素時，產生的會是一個新的 DOM 元素；使用函式能確保測試永遠參照到 DOM 目前的狀態。

完整的 `locatorFor` 方法清單與詳細說明，請參閱 [ComponentHarness API 參考頁面](/api/cdk/testing/ComponentHarness)。

舉例來說，前面討論的 `MyPopupHarness` 範例可以提供取得觸發元素與內容元素的方法，如下所示：

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

// Gets the trigger element
  getTriggerElement = this.locatorFor('button');

// Gets the content element.
  getContentElement = this.locatorForOptional('.my-popup-content');
}
```

## 使用 `TestElement` 實例

`TestElement` 是一種抽象化設計，能在不同的測試環境（單元測試、WebDriver 等）中運作。使用元件測試工具時，你應該透過這個介面進行所有的 DOM 互動。其他存取 DOM 元素的方式，例如 `document.querySelector()`，並不適用於所有測試環境。

`TestElement` 有許多與底層 DOM 互動的方法，例如 `blur()`、`click()`、`getAttribute()` 等。完整的方法清單請參閱 [TestElement API 參考頁面](/api/cdk/testing/TestElement)。

不要將 `TestElement` 實例暴露給元件測試工具的使用者，除非那是元件使用者直接定義的元素，例如元件的宿主元素。為內部元素暴露 `TestElement` 實例，會讓使用者依賴元件內部的 DOM 結構。

你應該改為針對終端使用者可能採取的特定動作，或他們可能觀察的特定狀態，提供範圍更聚焦的方法。舉例來說，前面幾節的 `MyPopupHarness` 可以提供像 `toggle` 與 `isOpen` 這樣的方法：

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

protected getTriggerElement = this.locatorFor('button');
  protected getContentElement = this.locatorForOptional('.my-popup-content');

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

## 為子元件載入元件測試工具

較大的元件通常由子元件組成。你也可以在元件的元件測試工具中反映這種結構。`ComponentHarness` 上的每個 `locatorFor` 方法都有另一種簽章，可以用來定位子元件測試工具而非元素。

不同的 locatorFor 方法完整清單，請參閱 [ComponentHarness API 參考頁面](/api/cdk/testing/ComponentHarness)。

舉例來說，考慮一個使用上述彈出式元件建構的選單：

```ts
@Directive({
  selector: 'my-menu-item',
})
class MyMenuItem {}

@Component({
  selector: 'my-menu',
  template: `
    <my-popup>
      <ng-content />
    </my-popup>
  `,
})
class MyMenu {
  triggerText = input('');

items = contentChildren(MyMenuItem);
}
```

`MyMenu` 的元件測試工具接著就可以利用 `MyPopup` 與 `MyMenuItem` 的其他元件測試工具：

```ts
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

protected getPopupHarness = this.locatorFor(MyPopupHarness);

/** 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` 篩選元件測試工具實例

當一個頁面包含某個特定元件的多個實例時，你可能會想依據元件的某個屬性來篩選，以取得特定的元件實例。舉例來說，你可能會想要一個帶有特定文字的按鈕，或一個帶有特定 ID 的選單。`HarnessPredicate` 類別可以為 `ComponentHarness` 子類別捕捉這類條件。雖然測試作者可以手動建構 `HarnessPredicate` 實例，但如果 `ComponentHarness` 子類別提供一個輔助方法來為常見的篩選條件建構述詞，會容易得多。

你應該在每個 `ComponentHarness` 子類別上建立一個靜態的 `with()` 方法，傳回該類別的 `HarnessPredicate`。如此一來，測試作者就能寫出容易理解的程式碼，例如 `loader.getHarness(MyMenuHarness.with({selector: '#menu1'}))`。除了標準的 selector 與 ancestor 選項之外，`with` 方法還應該加入對該特定子類別而言有意義的其他選項。

需要加入額外選項的元件測試工具，應該擴充 `BaseHarnessFilters` 介面，並視需要加入額外的選擇性屬性。`HarnessPredicate` 提供了數個加入選項的便利方法：`stringMatches()`、`addOption()` 與 `add()`。完整說明請參閱 [HarnessPredicate API 頁面](/api/cdk/testing/HarnessPredicate)。

舉例來說，處理選單時，依據觸發文字來篩選，以及依據選單項目的文字來篩選，都很實用：

```ts
interface MyMenuHarnessFilters extends BaseHarnessFilters {
  /** Filters based on the trigger text for the menu. */
  triggerText?: string | RegExp;
}

interface MyMenuItemHarnessFilters extends BaseHarnessFilters {
  /** Filters based on the text of the menu item. */
  text?: string | RegExp;
}

class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

/** Creates a `HarnessPredicate` used to locate a particular `MyMenuHarness`. */
  static with(options: MyMenuHarnessFilters): HarnessPredicate<MyMenuHarness> {
    return new HarnessPredicate(MyMenuHarness, options).addOption(
      'trigger text',
      options.triggerText,
      (harness, text) => HarnessPredicate.stringMatches(harness.getTriggerText(), text),
    );
  }

protected getPopupHarness = this.locatorFor(MyPopupHarness);

/** Gets the text of the menu trigger. */
  async getTriggerText(): Promise<string> {
    const popupHarness = await this.getPopupHarness();
    return popupHarness.getTriggerText();
  }
}

class MyMenuItemHarness extends ComponentHarness {
  static hostSelector = 'my-menu-item';

/** Creates a `HarnessPredicate` used to locate a particular `MyMenuItemHarness`. */
  static with(options: MyMenuItemHarnessFilters): HarnessPredicate<MyMenuItemHarness> {
    return new HarnessPredicate(MyMenuItemHarness, options).addOption(
      'text',
      options.text,
      (harness, text) => HarnessPredicate.stringMatches(harness.getText(), text),
    );
  }

/** Gets the text of the menu item. */
  async getText(): Promise<string> {
    const host = await this.host();
    return host.text();
  }
}
```

你可以將 `HarnessPredicate` 而非 `ComponentHarness` 類別，傳給 `HarnessLoader`、`LocatorFactory` 或 `ComponentHarness` 上的任何 API。這讓測試作者在建立元件測試工具實例時，能輕易鎖定特定的元件實例。它也讓元件測試工具作者能利用同一個 `HarnessPredicate`，在自己的元件測試工具類別上啟用更強大的 API。舉例來說，考慮上面展示的 `MyMenuHarness` 上的 `getItems` 方法。加入篩選 API 後，元件測試工具的使用者就能搜尋特定的選單項目：

```ts
class MyMenuHarness extends ComponentHarness {
  static hostSelector = 'my-menu';

/** Gets a list of items in the menu, optionally filtered based on the given criteria. */
  async getItems(filters: MyMenuItemHarnessFilters = {}): Promise<MyMenuItemHarness[]> {
    const getFilteredItems = this.locatorForAll(MyMenuItemHarness.with(filters));
    return getFilteredItems();
  }
  ...
}
```

## 為使用內容投影的元素建立 `HarnessLoader`

有些元件會將額外內容投影到元件的範本中。更多資訊請參閱[內容投影指南](guide/components/content-projection)。

當你為使用內容投影的元件建立元件測試工具時，請加入一個作用域限定在包含 `<ng-content>` 之元素的 `HarnessLoader` 實例。這讓元件測試工具的使用者能為任何作為內容傳入的元件載入額外的元件測試工具。針對這類情境，`ComponentHarness` 提供了數個可以建立 HarnessLoader 實例的方法：`harnessLoaderFor()`、`harnessLoaderForOptional()`、`harnessLoaderForAll()`。更多細節請參閱 [HarnessLoader 介面 API 參考頁面](/api/cdk/testing/HarnessLoader)。

舉例來說，上面的 `MyPopupHarness` 範例可以擴充 `ContentContainerComponentHarness`，加入在元件的 `<ng-content>` 內載入元件測試工具的支援。

```ts
class MyPopupHarness extends ContentContainerComponentHarness<string> {
  static hostSelector = 'my-popup';
}
```

## 存取元件宿主元素之外的元素

有些時候，元件測試工具可能需要存取其對應元件宿主元素之外的元素。舉例來說，顯示浮動元素或彈出式內容的程式碼，經常會將 DOM 元素直接附加到文件主體上，例如 Angular CDK 中的 `Overlay` 服務。

在這個情況下，`ComponentHarness` 提供了一個方法，可以取得文件根元素的 `LocatorFactory`。`LocatorFactory` 支援與 `ComponentHarness` 基底類別相同的大多數 API，接著就能用來相對於文件的根元素進行查詢。

考慮看看：如果上面的 `MyPopup` 元件使用 CDK overlay 來呈現彈出內容，而不是使用自己範本中的元素，會怎麼樣。在這個情況下，`MyPopupHarness` 就必須透過 `documentRootLocatorFactory()` 方法存取內容元素，該方法會取得一個以文件根為根的 locator factory。

```ts
class MyPopupHarness extends ComponentHarness {
  static hostSelector = 'my-popup';

/** Gets a `HarnessLoader` whose root element is the popup's content element. */
  async getHarnessLoaderForContent(): Promise<HarnessLoader> {
    const rootLocator = this.documentRootLocatorFactory();
    return rootLocator.harnessLoaderFor('my-popup-content');
  }
}
```

## 等待非同步工作

`TestElement` 上的方法會自動觸發 Angular 的變更偵測，並等待 `NgZone` 內的工作。在大多數情況下，元件測試工具作者不需要為了等待非同步工作而做特別的處理。不過，在某些邊緣情境下，這可能還不夠。

在某些情況下，Angular 動畫可能需要第二輪變更偵測以及後續的 `NgZone` 穩定，才能完全排清動畫事件。在需要這麼做的情況下，`ComponentHarness` 提供了 `forceStabilize()` 方法，可以呼叫它來進行第二輪處理。

你可以使用 `NgZone.runOutsideAngular()` 在 NgZone 之外排程工作。如果你需要明確等待 `NgZone` 之外的工作，請呼叫對應元件測試工具上的 `waitForTasksOutsideAngular()` 方法，因為這件事不會自動發生。
# 使用 `animate.enter` 與 `animate.leave` 為應用程式加入動畫

設計良好的動畫能讓應用程式更直覺、更吸引人，但它不只是裝飾。
動畫能從多方面改善應用程式與使用者體驗：

- 沒有動畫時，網頁轉場容易顯得突兀生硬
- 動態效果能大幅提升使用者體驗，讓使用者察覺應用程式對其操作的回應
- 良好的動畫能在整個工作流程中順暢地引導使用者的注意力

Angular 提供 `animate.enter` 與 `animate.leave` 來為應用程式的元素加入動畫。這兩個功能會在適當的時機套用進入與離開的 CSS 類別，或呼叫函式以套用第三方函式庫的動畫。`animate.enter` 與 `animate.leave` 不是指令，而是由 Angular 編譯器直接支援的特殊 API。它們可以直接用在元素上，也可以作為宿主繫結使用。

## `animate.enter`

你可以用 `animate.enter` 讓元素在*進入* DOM 時播放動畫。你可以用 CSS 類別搭配轉場或關鍵影格動畫來定義進入動畫。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.ts">
    <docs-code header="enter.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.ts" />
    <docs-code header="enter.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.html" />
    <docs-code header="enter.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter.css"/>
</docs-code-multifile>

動畫完成後，Angular 會從 DOM 移除你在 `animate.enter` 中指定的類別。動畫類別只會在動畫進行期間存在。

NOTE: 在同一個元素上使用多個關鍵影格動畫或轉場屬性時，Angular 會等到最長的那個動畫完成後，才移除所有類別。

你可以將 `animate.enter` 與任何其他 Angular 功能搭配使用，例如控制流程或動態運算式。`animate.enter` 接受單一類別字串（多個類別以空格分隔），或類別字串陣列。

順帶說明 CSS 轉場的用法：若你選擇使用轉場而非關鍵影格動畫，透過 `animate.enter` 加入元素的類別，代表的是轉場要動畫到的目標狀態。當沒有動畫執行時，元素基礎 CSS 的外觀，通常會與 CSS 轉場的結束狀態相似。因此，你仍需要搭配 `@starting-style`，讓轉場有適當的起始狀態才能正常運作。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.ts">
    <docs-code header="enter-binding.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.ts" />
    <docs-code header="enter-binding.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.html" />
    <docs-code header="enter-binding.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/enter-binding.css"/>
</docs-code-multifile>

## `animate.leave`

你可以用 `animate.leave` 讓元素在*離開* DOM 時播放動畫。你可以用 CSS 類別搭配 transform 或關鍵影格動畫來定義離開動畫。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.ts">
    <docs-code header="leave.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.ts" />
    <docs-code header="leave.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.html" />
    <docs-code header="leave.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave.css"/>
</docs-code-multifile>

動畫完成後，Angular 會自動把該元素從 DOM 移除。

NOTE: 在同一個元素上使用多個關鍵影格動畫或轉場屬性時，Angular 會等到其中最長的那個動畫完成後，才移除元素。

`animate.leave` 也可以搭配訊號與其他繫結使用。你可以為 `animate.leave` 指定單一類別或多個類別，用以空格分隔的簡單字串或字串陣列指定皆可。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.ts">
    <docs-code header="leave-binding.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.ts" />
    <docs-code header="leave-binding.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.html" />
    <docs-code header="leave-binding.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-binding.css"/>
</docs-code-multifile>

### 元素移除順序 {#element-removal-order}

`animate.leave` 動畫如何執行、何時發生，其中有些細微差別。當 `animate.leave` 放在正被移除的元素上時，它會生效；而若 `animate.leave` 放在被移除元素的*後代*元素上、且位於同一個元件範本內，這些子元素的 `animate.leave` 動畫會在父節點從 DOM 移除*之前*先執行。這能確保你可以放心地讓子元素以動畫離場，父節點不會提早消失。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.ts">
    <docs-code header="leave-parent.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.ts" />
    <docs-code header="leave-parent.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.html" />
    <docs-code header="leave-parent.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-parent.css"/>
</docs-code-multifile>

IMPORTANT: 子元素動畫只會對同一個元件範本內的元素觸發。若被移除的元素包含子元件，那些子元件範本內定義的任何 `animate.leave` 動畫，都**不會**在父元素被移除前執行。若要在移除時為子元件播放動畫，請改在父範本內直接把 `animate.leave` 套用到子元件的宿主元素上，或以程式方式在子元件中觸發動畫，並延遲父元素的移除，直到該動畫完成。

## 事件繫結、函式與第三方函式庫

`animate.enter` 與 `animate.leave` 都支援事件繫結語法，可以用來呼叫函式。你可以利用這個語法呼叫元件程式碼中的函式，或使用第三方動畫函式庫，例如 [GSAP](https://gsap.com/)、[anime.js](https://animejs.com/)，或任何其他 JavaScript 動畫函式庫。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.ts">
    <docs-code header="leave-event.ts" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.ts" />
    <docs-code header="leave-event.html" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.html" />
    <docs-code header="leave-event.css" path="adev/src/content/examples/animations/src/app/enter-and-leave/leave-event.css"/>
</docs-code-multifile>

`$event` 物件的型別為 `AnimationCallbackEvent`。它包含作為 `target` 的元素，並提供 `animationComplete()` 函式，用來在動畫結束時通知框架。

IMPORTANT: 使用 `animate.leave` 時，你**必須**呼叫 `animationComplete()` 函式，Angular 才會移除元素。

若你在使用 `animate.leave` 時沒有呼叫 `animationComplete()`，Angular 會在延遲四秒後自動呼叫該函式。你可以以毫秒為單位提供 `MAX_ANIMATION_TIMEOUT` token，來設定這段延遲的長度。

```typescript
{ provide: MAX_ANIMATION_TIMEOUT, useValue: 6000 }
```

## 與舊版 Angular 動畫的相容性

你不能在同一個元件內同時使用舊版動畫與 `animate.enter`、`animate.leave`。這樣做會導致進入類別殘留在元素上，或離開的節點無法被移除。但在同一個*應用程式*內同時使用舊版動畫與新的 `animate.enter`、`animate.leave` 動畫則沒有問題。唯一的例外是內容投影：若你把帶有舊版動畫的元件內容投影到帶有 `animate.enter` 或 `animate.leave` 的元件中（或反過來），其行為會與在同一個元件內一起使用相同，這是不支援的。

## 測試

TestBed 內建支援在測試環境中啟用或停用動畫。CSS 動畫需要瀏覽器才能執行，許多相關 API 在測試環境中無法使用。TestBed 預設會在你的測試環境中停用動畫。

若你想測試動畫是否真的在瀏覽器測試（例如端到端測試）中播放，可以在測試設定中指定 `animationsEnabled: true`，將 TestBed 設定為啟用動畫。

```typescript
TestBed.configureTestingModule({animationsEnabled: true});
```

這樣就會讓測試環境中的動畫正常運作。

NOTE: 有些測試環境不會發出 `animationstart`、`animationend` 這類動畫事件，以及它們對應的轉場事件。

## 深入了解 Angular 動畫

你可能也會對以下內容有興趣：
# 使用 CSS 為應用程式加入動畫

CSS 提供了一套強大的工具，讓你在應用程式中建立美觀且吸引人的動畫。

## 如何用原生 CSS 撰寫動畫

若你從未寫過任何原生 CSS 動畫，有許多優秀的指南可以帶你入門。以下列出幾篇：
[MDN 的 CSS Animations 指南](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)
[W3Schools CSS3 Animations 指南](https://www.w3schools.com/css/css3_animations.asp)
[The Complete CSS Animations Tutorial](https://www.lambdatest.com/blog/css-animations-tutorial/)
[CSS Animation for Beginners](https://thoughtbot.com/blog/css-animation-for-beginners)

以及幾部影片：
[Learn CSS Animation in 9 Minutes](https://www.youtube.com/watch?v=z2LQYsZhsFw)
[Net Ninja CSS Animation Tutorial Playlist](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)

先看看其中一些指南與教學，再回來繼續閱讀本指南。

## 建立可重複使用的動畫

你可以使用 `@keyframes` 建立可在整個應用程式共用的可重複使用動畫。把關鍵影格動畫定義在共用的 CSS 檔案中，你就能在應用程式的任何地方重複使用這些關鍵影格動畫。

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>

把 `animated-class` 類別加到元素上，就會觸發該元素的動畫。

## 為轉場加入動畫

### 為狀態與樣式加入動畫

你可能想在兩種不同狀態之間加入動畫，例如元素開啟或關閉時。你可以用 CSS 類別搭配關鍵影格動畫或轉場樣式來達成。

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-states"/>

觸發 `open` 或 `closed` 狀態的方法，是在元件中切換元素上的類別。你可以在我們的[範本指南](guide/templates/binding#css-class-and-style-property-bindings)中找到做法範例。

範本指南中也有[直接為樣式加入動畫](guide/templates/binding#css-style-properties)的類似範例。

### 轉場、時間與緩動

加入動畫時，常需要調整時間、延遲與緩動行為。這可以透過多個 CSS 屬性或簡寫屬性完成。

在 CSS 中為關鍵影格動畫指定 `animation-duration`、`animation-delay` 與 `animation-timing-function`，或改用 `animation` 簡寫屬性。

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>

同樣地，對於不使用 `@keyframes` 的動畫，你可以使用 `transition-duration`、`transition-delay`、`transition-timing-function` 以及 `transition` 簡寫屬性。

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>

### 觸發動畫

只要切換 CSS 樣式或類別，就能觸發動畫。當類別出現在元素上時，動畫就會發生。移除類別後，元素會還原為該元素所定義的 CSS。以下是一個範例：

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/open-close.ts">
    <docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/native-css/open-close.ts" />
    <docs-code header="open-close.html" path="adev/src/content/examples/animations/src/app/native-css/open-close.html" />
    <docs-code header="open-close.css" path="adev/src/content/examples/animations/src/app/native-css/open-close.css"/>
</docs-code-multifile>

## 轉場與觸發器

### 為自動高度加入動畫

你可以使用 CSS Grid 為自動高度加入動畫。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/auto-height.ts">
    <docs-code header="auto-height.ts" path="adev/src/content/examples/animations/src/app/native-css/auto-height.ts" />
    <docs-code header="auto-height.html" path="adev/src/content/examples/animations/src/app/native-css/auto-height.html" />
    <docs-code header="auto-height.css" path="adev/src/content/examples/animations/src/app/native-css/auto-height.css"  />
</docs-code-multifile>

若你不需要顧慮支援所有瀏覽器，也可以看看 `calc-size()`，那是為自動高度加入動畫的真正解法。更多資訊請見 [MDN 的文件](https://developer.mozilla.org/en-US/docs/Web/CSS/calc-size)與[這篇教學](https://frontendmasters.com/blog/one-of-the-boss-battles-of-css-is-almost-won-transitioning-to-auto/)。

### 為進入與離開檢視加入動畫

你可以為項目進入檢視或離開檢視時建立動畫。先看看如何為進入檢視的元素加入動畫。我們會用 `animate.enter` 來做，它會在元素進入檢視時套用動畫類別。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/insert.ts">
    <docs-code header="insert.ts" path="adev/src/content/examples/animations/src/app/native-css/insert.ts" />
    <docs-code header="insert.html" path="adev/src/content/examples/animations/src/app/native-css/insert.html" />
    <docs-code header="insert.css" path="adev/src/content/examples/animations/src/app/native-css/insert.css"  />
</docs-code-multifile>

為離開檢視的元素加入動畫，與為進入檢視的元素加入動畫相似。使用 `animate.leave` 指定元素離開檢視時要套用的 CSS 類別。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/remove.ts">
    <docs-code header="remove.ts" path="adev/src/content/examples/animations/src/app/native-css/remove.ts" />
    <docs-code header="remove.html" path="adev/src/content/examples/animations/src/app/native-css/remove.html" />
    <docs-code header="remove.css" path="adev/src/content/examples/animations/src/app/native-css/remove.css"  />
</docs-code-multifile>

NOTE: 子元素的 `animate.leave` 動畫只會在同一個元件範本內觸發。當父元素被移除時，巢狀元件的 `animate.leave` 動畫不會觸發。

更多關於 `animate.enter` 與 `animate.leave` 的資訊，請見[進入與離開動畫指南](guide/animations)。

### 為遞增與遞減加入動畫

為遞增與遞減加入動畫，是應用程式中常見的模式。以下範例示範如何達成這種行為。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.ts">
    <docs-code header="increment-decrement.ts" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.ts" />
    <docs-code header="increment-decrement.html" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.html" />
    <docs-code header="increment-decrement.css" path="adev/src/content/examples/animations/src/app/native-css/increment-decrement.css" />
</docs-code-multifile>

### 停用單一動畫或所有動畫

若你想停用已指定的動畫，有多種做法。

1. 建立一個自訂類別，強制把 animation 與 transition 設為 `none`。

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

把這個類別套用到元素上，就能避免該元素觸發任何動畫。你也可以把作用範圍設定為整個 DOM 或 DOM 的某個區段，來強制這種行為。不過，這會讓動畫事件無法觸發。若你正在等待動畫事件來移除元素，這個做法就行不通。替代方案是把持續時間設為 1 毫秒。

2. 使用 [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) media query，確保偏好減少動畫的使用者不會看到動畫播放。

3. 避免以程式方式加入動畫類別

### 動畫回呼

若你有想在動畫的特定時間點執行的動作，有多個可監聽的事件可用。以下列出其中幾個。

[`OnAnimationStart`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationstart_event)  
[`OnAnimationEnd`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationend_event)  
[`OnAnimationIteration`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationiteration_event)  
[`OnAnimationCancel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animationcancel_event)

[`OnTransitionStart`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionstart_event)  
[`OnTransitionRun`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionrun_event)  
[`OnTransitionEnd`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitionend_event)  
[`OnTransitionCancel`](https://developer.mozilla.org/en-US/docs/Web/API/Element/transitioncancel_event)

Web Animations API 還提供許多額外功能。[請參閱文件](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API)，了解所有可用的動畫 API。

NOTE: 使用這些回呼時請注意事件冒泡問題。若你同時為子元素與父元素加入動畫，事件會從子元素向上冒泡到父元素。請考慮停止事件傳播，或查看事件中的更多細節，確認你回應的是想要的事件目標、而不是從子節點冒泡上來的事件。你可以檢查 `animationname` 屬性或正在轉場的屬性，確認處理的是正確的節點。

## 複雜序列

動畫通常不只是簡單的淡入或淡出。你可能有許多想執行的複雜動畫序列。以下來看看其中一些可能的情境。

### 讓清單中的動畫錯開播放

一個常見的效果，是讓清單中每個項目的動畫錯開播放，形成瀑布般的效果。這可以利用 `animation-delay` 或 `transition-delay` 達成。以下範例示範這類 CSS 可能的寫法。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/stagger.ts">
    <docs-code header="stagger.ts" path="adev/src/content/examples/animations/src/app/native-css/stagger.ts" />
    <docs-code header="stagger.html" path="adev/src/content/examples/animations/src/app/native-css/stagger.html" />
    <docs-code header="stagger.css" path="adev/src/content/examples/animations/src/app/native-css/stagger.css" />
</docs-code-multifile>

### 平行動畫

你可以使用 `animation` 簡寫屬性，同時把多個動畫套用到一個元素上。每個動畫都可以有各自的持續時間與延遲。這讓你能把動畫組合在一起，創造出複雜的效果。

```css
.target-element {
  animation:
    rotate 3s,
    fade-in 2s;
}
```

在這個範例中，`rotate` 與 `fade-in` 動畫會同時觸發，但持續時間不同。

### 為重新排序清單的項目加入動畫

`@for` 迴圈中的項目會被移除再重新加入，進入動畫會透過 `@starting-styles` 觸發。或者，你也可以用 `animate.enter` 達成相同行為。使用 `animate.leave` 讓元素在被移除時播放動畫，如下例所示。

<docs-code-multifile preview path="adev/src/content/examples/animations/src/app/native-css/reorder.ts">
    <docs-code header="reorder.ts" path="adev/src/content/examples/animations/src/app/native-css/reorder.ts" />
    <docs-code header="reorder.html" path="adev/src/content/examples/animations/src/app/native-css/reorder.html" />
    <docs-code header="reorder.css" path="adev/src/content/examples/animations/src/app/native-css/reorder.css" />
</docs-code-multifile>

## 以程式方式控制動畫

你可以使用 [`Element.getAnimations()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations) 直接從元素取得動畫。它會回傳該元素上每一個 [`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation) 組成的陣列。你可以用 `Animation` API 做到比 animations 套件的 `AnimationPlayer` 更多的事。由此你可以 `cancel()`、`play()`、`pause()`、`reverse()` 等等。這個原生 API 應該能提供你控制動畫所需的一切。

## 深入了解 Angular 動畫

你可能也會對以下內容有興趣：
# 路由轉場動畫

路由轉場動畫能在使用者於 Angular 應用程式的不同畫面間導覽時，提供流暢的視覺轉換效果，藉此提升使用者體驗。[Angular Router](/guide/routing) 內建支援瀏覽器的 View Transitions API，能在支援的瀏覽器中，為路由切換帶來無縫的動畫效果。

## View Transitions 的運作方式

View Transitions 會使用瀏覽器原生的 [`document.startViewTransition` API](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition)，為應用程式在不同狀態之間建立流暢的動畫。這個 API 的運作步驟如下：

1. **捕獲目前狀態**：瀏覽器會擷取目前頁面的螢幕快照
2. **執行 DOM 更新**：執行你的回呼函式來更新 DOM
3. **捕獲新狀態**：瀏覽器會擷取更新後的頁面狀態
4. **播放轉場動畫**：瀏覽器會在新舊兩個狀態之間播放動畫

以下是 `startViewTransition` API 的基本結構：

```ts
document.startViewTransition(async () => {
  await updateTheDOMSomehow();
});
```

欲了解瀏覽器 API 的更多細節，請參閱 [Chrome 官方說明](https://developer.chrome.com/docs/web-platform/view-transitions)。

## Router 如何使用 View Transitions

Angular Router 已經將 View Transitions 整合到導覽的生命週期中，以實現無縫的路由切換。在導覽過程中，Router 會執行以下步驟：

1. **完成導覽的事前準備**：執行路由比對、[延遲載入](guide/routing/loading-strategies#lazily-loaded-components-and-routes)、[路由守衛](/guide/routing/route-guards)、[資源](/guide/routing/data-fetching-with-resources)與[解析器](/guide/routing/data-resolvers)
2. **啟動 View Transition**：當路由準備好要被啟用時，Router 會呼叫 `startViewTransition`
3. **更新 DOM**：Router 會在轉換回呼函式中，啟用新的路由並停用舊的路由
4. **完成轉場作業**：當 Angular 完成畫面算繪時，轉場作業的 Promise 就會完成

Router 對於 View Transitions 的整合，本身是一種[漸進增強](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement)的做法。當瀏覽器不支援 View Transitions API 時，Router 就會執行不含動畫效果的一般 DOM 更新，確保你的應用程式能在所有瀏覽器上正常運作。

## 在 Router 中啟用 View Transitions

只要在你的[路由設定](/guide/routing/define-routes#adding-the-router-to-your-application)中，加入 `withViewTransitions` 功能，即可啟用 View Transitions。Angular 同時支援獨立元件與 NgModule 這兩種啟動方式：

### 以獨立元件方式啟動

```ts
import {bootstrapApplication} from '@angular/platform-browser';
import {provideRouter, withViewTransitions} from '@angular/router';
import {routes} from './app.routes';

bootstrapApplication(MyApp, {
  providers: [provideRouter(routes, withViewTransitions())],
});
```

### 以 NgModule 方式啟動

```ts
import {NgModule} from '@angular/core';
import {RouterModule} from '@angular/router';

@NgModule({
  imports: [RouterModule.forRoot(routes, {enableViewTransitions: true})],
})
export class AppRouting {}
```

[在 StackBlitz 上試用「count」範例](https://stackblitz.com/edit/stackblitz-starters-2dnvtm?file=src%2Fmain.ts)

這個範例示範了如何使用路由導覽，來取代直接呼叫 `startViewTransition` 處理計數器更新的作法。

## 使用 CSS 自訂轉場效果

你可以使用 CSS 來自訂 View Transitions，藉此創造獨一無二的動畫效果。瀏覽器會建立專門的轉場元素，讓你可以使用 CSS 選擇器來指定這些元素的樣式。

建立自訂轉場效果的步驟如下：

1. **加上 view-transition-name**：為你想要加入動畫的元素，指定一個專屬的名稱
2. **定義全域動畫**：在全域樣式檔案中，建立 CSS 動畫
3. **指定轉場虛擬元素**：使用 `::view-transition-old()` 與 `::view-transition-new()` 選擇器

以下範例會為計數器元素加上旋轉效果：

```css
/* Define keyframe animations */
@keyframes rotate-out {
  to {
    transform: rotate(90deg);
  }
}

@keyframes rotate-in {
  from {
    transform: rotate(-90deg);
  }
}

/* Target view transition pseudo-elements */
::view-transition-old(count),
::view-transition-new(count) {
  animation-duration: 200ms;
  animation-name: -ua-view-transition-fade-in, rotate-in;
}

::view-transition-old(count) {
  animation-name: -ua-view-transition-fade-out, rotate-out;
}
```

IMPORTANT: 請務必將 View Transition 動畫定義在你的全域樣式檔案裡，而不是寫在元件樣式中。Angular 的[檢視封裝](/guide/components/styling#style-scoping)機制會限制元件樣式的套用範圍，導致這些樣式無法正確指定到轉場虛擬元素上。

[在 StackBlitz 上試用更新版的「count」範例](https://stackblitz.com/edit/stackblitz-starters-fwn4i7?file=src%2Fmain.ts)

## 透過 onViewTransitionCreated 進行進階轉場控制

`withViewTransitions` 功能可以接受一個選項物件，裡頭帶有 `onViewTransitionCreated` 回呼，以對 View Transitions 進行更進階的控制。這個回呼函式具有以下特性：

- 會在[注入上下文](/guide/di/dependency-injection-context#run-within-an-injection-context)中執行
- 會接收到一個 [`ViewTransitionInfo`](/api/router/ViewTransitionInfo) 物件，其中包含：
  - 從 `startViewTransition` 所建立的 `ViewTransition` 實例
  - 導覽來源路由的 [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot)
  - 導覽目標路由的 [`ActivatedRouteSnapshot`](/api/router/ActivatedRouteSnapshot)

你可以運用這個回呼函式，依據導覽上下文來客製化轉場行為。例如，你可以針對特定類型的導覽略過轉場效果：

```ts
import {inject} from '@angular/core';
import {Router, withViewTransitions, isActive, IsActiveMatchOptions} from '@angular/router';

withViewTransitions({
  onViewTransitionCreated: ({transition}) => {
    const router = inject(Router);
    const targetUrl = router.currentNavigation()!.finalUrl!;

// Skip transition if only fragment or query params change
    const config: Partial<IsActiveMatchOptions> = {
      paths: 'exact',
      matrixParams: 'exact',
      fragment: 'ignored',
      queryParams: 'ignored',
    };

const isTargetRouteCurrent = isActive(targetUrl, router, config);

if (isTargetRouteCurrent()) {
      transition.skipTransition();
    }
  },
});
```

這個範例會在導覽僅僅更動到 [URL 的錨點片段或查詢參數](/guide/routing/read-route-state#query-parameters)（例如同一個頁面中的錨點連結）時，略過 View Transition。`skipTransition()` 方法會避免播放動畫效果，同時仍會確保導覽能夠順利完成。

## 尊重使用者的動態偏好設定

無論使用者的 [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) 設定值為何，Router 都會照常執行 View Transitions。偏好減少動態效果，並不一定代表使用者希望完全沒有任何動作，因此框架會將選擇權交給應用程式自行決定：你可以為這類使用者[提供較為低調、細膩的動畫](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#react_to_the_reduced_motion_preference)，或是利用 `onViewTransitionCreated` 回呼，完全略過版面轉場效果：

```ts
withViewTransitions({
  onViewTransitionCreated: ({transition}) => {
    if (matchMedia('(prefers-reduced-motion: reduce)').matches) {
      transition.skipTransition();
    }
  },
});
```

## 改編自 Chrome 官方說明的 Angular 範例

以下範例展示了各種 View Transition 的技巧，這些範例均改編自 Chrome 團隊的說明文件，並針對 Angular Router 的使用方式進行調整：

### 進行轉場的元素不一定要是同一個 DOM 元素

只要 DOM 元素共用相同的 `view-transition-name`，就能在不同的 DOM 元素之間流暢地進行轉場。

- [Chrome 官方說明文件](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning_elements_dont_need_to_be_the_same_dom_element)
- [在 StackBlitz 上的 Angular 範例](https://stackblitz.com/edit/stackblitz-starters-dh8npr?file=src%2Fmain.ts)

### 自訂進場與離場動畫

你可以為路由轉場過程中，進入或離開可視區域的元素，建立專屬的進場與離場動畫效果。

- [Chrome 官方說明文件](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#custom_entry_and_exit_transitions)
- [在 StackBlitz 上的 Angular 範例](https://stackblitz.com/edit/stackblitz-starters-8kly3o)

### 非同步 DOM 更新與等待內容載入

Angular Router 會優先執行即時的版面轉場，而不會為了等待額外的內容載入完成而停下等候。

- [Chrome 官方說明文件](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#async_dom_updates_and_waiting_for_content)

NOTE: Angular Router 並不提供用來延遲 View Transition 的方法。這項設計抉擇的目的，是為了避免在等待額外內容時，整個頁面變得無法互動。正如 Chrome 官方文件所提及的：「在此期間，頁面會完全凍結，因此這段延遲時間應盡可能縮短……在某些情況下，寧可直接跳過延遲，直接使用現有的內容。」

### 使用 View Transition 類型來切換多種轉場樣式

你可以根據導覽的上下文，運用 View Transition 類型來套用不同的動畫風格。

- [Chrome 官方說明文件](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#view-transition-types)
- [在 StackBlitz 上的 Angular 範例](https://stackblitz.com/edit/stackblitz-starters-vxzcam)

### 在 View Transition 根元素上套用類別名稱來切換多種轉場樣式（已棄用）

這種作法會使用轉場根元素上的 CSS 類別名稱，來控制整體的動畫樣式。

- [Chrome 官方說明文件](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#changing-on-navigation-type)
- [在 StackBlitz 上的 Angular 範例](https://stackblitz.com/edit/stackblitz-starters-nmnzzg?file=src%2Fmain.ts)

### 進行轉場的同時不凍結其他動畫

你可以在執行 View Transition 的過程中，讓頁面上的其他動畫持續播放，打造更豐富的使用者互動體驗。

- [Chrome 官方說明文件](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#transitioning-without-freezing)
- [在 StackBlitz 上的 Angular 範例](https://stackblitz.com/edit/stackblitz-starters-76kgww)

### 使用 JavaScript 操控動畫

針對複雜的動畫情境，你可以使用 JavaScript API，以程式化的方式控制 View Transition 的播放過程。

- [Chrome 官方說明文件](https://developer.chrome.com/docs/web-platform/view-transitions/same-document#animating-with-javascript)
- [在 StackBlitz 上的 Angular 範例](https://stackblitz.com/edit/stackblitz-starters-cklnkm)
# 從 Angular Animations 套件遷移

`@angular/animations` 套件自 v20.2 起已棄用，該版本同時引入了新的 `animate.enter` 與 `animate.leave` 功能，讓你為應用程式加入動畫。運用這些新功能，你可以把所有以 `@angular/animations` 為基礎的動畫，改為純 CSS 或 JS 動畫函式庫。從應用程式移除 `@angular/animations`，能顯著縮小 JavaScript 套件包的大小。原生 CSS 動畫通常能提供更優異的效能，因為它們可以受益於硬體加速。本指南將帶你走過把程式碼從 `@angular/animations` 重構為原生 CSS 動畫的過程。

## 如何用原生 CSS 撰寫動畫

若你從未寫過任何原生 CSS 動畫，有許多優秀的指南可以帶你入門。以下列出幾篇：  
[MDN 的 CSS Animations 指南](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)  
[W3Schools CSS3 Animations 指南](https://www.w3schools.com/css/css3_animations.asp)  
[The Complete CSS Animations Tutorial](https://www.lambdatest.com/blog/css-animations-tutorial/)  
[CSS Animation for Beginners](https://thoughtbot.com/blog/css-animation-for-beginners)

以及幾部影片：  
[Learn CSS Animation in 9 Minutes](https://www.youtube.com/watch?v=z2LQYsZhsFw)  
[Net Ninja CSS Animation Tutorial Playlist](https://www.youtube.com/watch?v=jgw82b5Y2MU&list=PL4cUxeGkcC9iGYgmEd2dm3zAKzyCGDtM5)

先看看其中一些指南與教學，再回來繼續閱讀本指南。

## 建立可重複使用的動畫

就和 animations 套件一樣，你可以建立可在整個應用程式共用的可重複使用動畫。animations 套件的版本是讓你在共用的 TypeScript 檔案中使用 `animation()` 函式。原生 CSS 的版本與此類似，但放在共用的 CSS 檔案中。

#### 使用 Animations 套件

<docs-code header="animations.ts" path="adev/src/content/examples/animations/src/app/animations.1.ts" region="animation-example"/>

#### 使用原生 CSS

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-shared"/>

把 `animated-class` 類別加到元素上，就會觸發該元素的動畫。

## 為轉場加入動畫

### 為狀態與樣式加入動畫

animations 套件讓你能在元件內使用 [`state()`](api/animations/state) 函式定義各種狀態。範例可能是 `open` 或 `closed` 狀態，定義中包含各自狀態的樣式。例如：

#### 使用 Animations 套件 {#animating-state-and-styles-with-animations-package}

<docs-code header="open-close.ts" path="adev/src/content/examples/animations/src/app/open-close.ts" region="state1"/>

同樣的行為也可以用原生方式達成：使用 CSS 類別，搭配關鍵影格動畫或轉場樣式。

#### 使用原生 CSS {#animating-state-and-styles-with-native-css}

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-states"/>

範本指南中也有[直接為樣式加入動畫](guide/templates/binding#css-style-properties)的類似範例。

### 轉場、時間與緩動

animations 套件的 `animate()` 函式允許提供時間資訊，例如持續時間、延遲與緩動。這可以用 CSS 原生達成，使用多個 CSS 屬性或簡寫屬性即可。

在 CSS 中為關鍵影格動畫指定 `animation-duration`、`animation-delay` 與 `animation-timing-function`，或改用 `animation` 簡寫屬性。

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="animation-timing"/>

同樣地，對於不使用 `@keyframes` 的動畫，你可以使用 `transition-duration`、`transition-delay`、`transition-timing-function` 以及 `transition` 簡寫屬性。

<docs-code header="animations.css" path="adev/src/content/examples/animations/src/app/animations.css" region="transition-timing"/>

### 觸發動畫

animations 套件要求使用 `trigger()` 函式指定觸發器，並把所有狀態都巢狀放在其中。使用原生 CSS 時，這就不必要了。只要切換 CSS 樣式或類別，就能觸發動畫。當類別出現在元素上時，動畫就會發生。移除類別後，元素會還原為該元素所定義的 CSS。這讓完成相同動畫所需的程式碼顯著減少。以下是一個範例：

#### 使用 Animations 套件 {#triggering-an-animation-with-animations-package}
#### 使用原生 CSS {#triggering-an-animation-with-native-css}

## 轉場與觸發器

### 預先定義的狀態與萬用字元比對

animations 套件提供透過字串把你定義的狀態與轉場比對的能力。例如，從開啟到關閉的動畫會是 `open => closed`。你可以使用萬用字元把任何狀態與目標狀態比對，例如 `* => closed`，而 `void` 關鍵字可用於進入與退出狀態。例如：元素離開檢視時用 `* => void`，元素進入檢視時用 `void => *`。

用 CSS 直接製作動畫時，完全不需要這些狀態比對模式。你可以根據你在元素上設定的類別和／或樣式，管理要套用哪些轉場與 `@keyframes` 動畫。你也可以加入 `@starting-style`，控制元素剛進入 DOM 時的外觀。

### 使用萬用字元自動計算屬性

animations 套件提供為歷來難以加入動畫的項目加入動畫的能力，例如把固定高度動畫化為 `height: auto`。現在用純 CSS 也能做到這一點。

#### 使用 Animations 套件 {#automatic-property-calculation-with-animations-package}
你可以使用 CSS Grid 為自動高度加入動畫。

#### 使用原生 CSS {#automatic-property-calculation-with-native-css}

### 為進入與離開檢視加入動畫

animations 套件除了提供前面提到的進入與離開模式比對，還包含 `:enter` 與 `:leave` 的簡寫別名。

#### 使用 Animations 套件 {#enter-and-leave-with-animations-package}
#### 使用原生 CSS {#enter-with-native-css}

#### 使用原生 CSS {#leave-with-native-css}

更多關於 `animate.enter` 與 `animate.leave` 的資訊，請見[進入與離開動畫指南](guide/animations)。

### 為遞增與遞減加入動畫

除了前面提到的 `:enter` 與 `:leave`，還有 `:increment` 與 `:decrement`。你也可以透過加入與移除類別為它們加入動畫。與 animations 套件的內建別名不同，當值上升或下降時，不會自動套用類別。你可以以程式方式套用適當的類別。以下是一個範例：

#### 使用 Animations 套件 {#increment-and-decrement-with-animations-package}
#### 使用原生 CSS {#increment-and-decrement-with-native-css}

### 父／子動畫

與 animations 套件不同，當在指定元件內指定多個動畫時，沒有任何動畫會優先於其他動畫，也沒有任何東西會阻止動畫觸發。任何動畫的順序安排，都必須由你的 CSS 動畫定義來處理，使用 animation／transition 的延遲，和／或使用 `animationend` 或 `transitionend` 來處理加入下一個要動畫化的 CSS。

子元素動畫只會在同一個元件範本內觸發。在 `@angular/animations` 套件中，父動畫可以使用 `query()` 與 `animateChild()` 查詢並觸發巢狀子元件中的動畫。使用 `animate.leave` 與原生 CSS 動畫時，定義在巢狀子元件範本內的動畫，不會在父元件移除元素或檢視時觸發。只有同一個 Angular 元件範本內的巢狀動畫會執行。更多資訊請見[進入與離開動畫指南](guide/animations#element-removal-order)。

### 停用單一動畫或所有動畫

使用原生 CSS 動畫時，若你想停用已指定的動畫，有多種做法。

1. 建立一個自訂類別，強制把 animation 與 transition 設為 `none`。

```css
.no-animation {
  animation: none !important;
  transition: none !important;
}
```

2. 使用 [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) media query，確保偏好減少動畫的使用者不會看到動畫播放。

3. 避免以程式方式加入動畫類別

### 動畫回呼

animations 套件提供了回呼，讓你在動畫結束時想做某些事時使用。原生 CSS 動畫也有這些回呼。

Web Animations API 還提供許多額外功能。[請參閱文件](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API)，了解所有可用的動畫 API。

## 複雜序列

animations 套件內建了建立複雜序列的功能。這些序列在不用 animations 套件的情況下，也完全做得到。

### 鎖定特定元素

在 animations 套件中，你可以使用 `query()` 函式依 CSS 類別名稱尋找特定元素，類似 [`document.querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelector)。在原生 CSS 動畫的世界裡，這就不必要了。取而代之的是，你可以使用 CSS 選擇器鎖定子類別，並套用任何想要的 `transform` 或 `animation`。

若要在範本內切換子節點的類別，你可以使用 class 與 style 繫結，在正確的時間點加入動畫。

### Stagger()

`stagger()` 函式讓你能把清單中每個項目的動畫延遲一段指定時間，創造瀑布般的效果。你可以在原生 CSS 中利用 `animation-delay` 或 `transition-delay` 複製這種行為。以下範例示範這類 CSS 可能的寫法。

#### 使用 Animations 套件 {#stagger-with-animations-package}
#### 使用原生 CSS {#stagger-with-native-css}

### 平行動畫

animations 套件有一個 `group()` 函式，可以同時播放多個動畫。在 CSS 中，你可以完全控制動畫時間。若你定義了多個動畫，可以一次全部套用。

```css
.target-element {
  animation:
    rotate 3s,
    fade-in 2s;
}
```

在這個範例中，`rotate` 與 `fade-in` 動畫會同時觸發。

### 為重新排序清單的項目加入動畫

清單中的項目重新排序，運用前面說明的技巧即可開箱運作，不需要額外的特殊處理。`@for` 迴圈中的項目會被正確地移除再重新加入，進入動畫會透過 `@starting-styles` 觸發。或者，你也可以用 `animate.enter` 達成相同行為。使用 `animate.leave` 讓元素在被移除時播放動畫，如上例所示。

#### 使用 Animations 套件 {#reordering-list-with-animations-package}
#### 使用原生 CSS {#reordering-list-with-native-css}

## 遷移 AnimationPlayer 的用法

`AnimationPlayer` 類別讓你存取動畫，透過程式碼做更進階的事，例如暫停、播放、重新開始與結束動畫。這些事全都可以原生處理。

## 路由轉場

你可以使用檢視轉場為路由之間加入動畫。開始使用請見[路由轉場動畫指南](guide/routing/route-transition-animations)。
# 不使用 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

Zoneless 是 Angular v21 以上的預設值，所以你不需要做任何事就能啟用它。你應該確認沒有任何地方使用 `provideZoneChangeDetection` 覆寫預設設定。

如果你使用的是 Angular v20，在啟動時加入 `provideZonelessChangeDetection()`，即可啟用 zoneless 變更偵測：

```ts
{header: 'standalone 啟動'}
bootstrapApplication(MyApp, {providers: [provideZonelessChangeDetection()]});
```

```ts
{header: '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 相容性的要求 {#requirements-for-zoneless-compatibility}

Angular 仰賴核心 API 的通知，來判斷何時執行變更偵測，以及對哪些檢視執行。
這些通知包括：

- `ChangeDetectorRef.markForCheck`（由 `AsyncPipe` 自動呼叫）
- `ComponentRef.setInput`
- 更新在範本中讀取的訊號
- 繫結的宿主或範本監聽器回呼
- 附加一個被上述任一機制標記為已變更的檢視

### 與 `OnPush` 相容的元件

確保元件使用上述正確通知機制的其中一種方法，就是使用 [ChangeDetectionStrategy.OnPush](/best-practices/skipping-subtrees#using-onpush)。

`OnPush` 變更偵測策略不是必要的，但對於應用程式元件來說，是邁向 zoneless 相容性的建議步驟。函式庫元件並非總是能使用 `ChangeDetectionStrategy.OnPush`。
當函式庫元件是使用者元件的宿主，而該使用者元件可能使用 `ChangeDetectionStrategy.Eager` 時，它不能使用 `OnPush`，因為那會讓子元件在不具備 `OnPush` 相容性、且仰賴 ZoneJS 觸發變更偵測時，無法被重新整理。元件可以使用 `Eager` 策略，前提是它們在需要執行變更偵測時通知 Angular（呼叫 `markForCheck`、使用訊號、`AsyncPipe` 等）。
作為使用者元件的宿主，指的是使用像 `ViewContainerRef.createComponent` 這樣的 API，而不是僅僅承載使用者元件範本的一部分（也就是內容投影，或使用範本參照輸入）。

### 移除 `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 API，例如當程式碼需要等待特定的 DOM 狀態時（而不是透過 Angular 的渲染鉤子間接等待），可以使用 `MutationObserver`。
為了讓程式碼與 Zoneless 應用程式相容，`NgZone.run` 與 `NgZone.runOutsideAngular` 不需要移除。事實上，移除這些呼叫可能會讓那些用在仍仰賴 ZoneJS 的應用程式中的函式庫，出現效能退化的情形。
### 用於伺服器端渲染（SSR）的 `PendingTasks` {#pendingtasks-for-server-side-rendering-ssr}

如果你在 Angular 中使用 SSR，你可能知道它仰賴 ZoneJS 來協助判斷應用程式何時「穩定」、可以被序列化。如果有非同步工作應該阻止序列化，不使用 ZoneJS 的應用程式必須透過 [PendingTasks](/api/core/PendingTasks) 服務讓 Angular 知道這些工作。序列化會等待所有待處理工作都被移除的第一個時刻。

待處理工作最直接的兩種使用方式是 `run` 方法：

```typescript
const taskService = inject(PendingTasks);
taskService.run(async () => {
  const someResult = await doSomeWorkThatNeedsToBeRendered();
  this.someState.set(someResult);
});
```

對於更複雜的使用情境，你可以手動加入與移除待處理工作：

```typescript
const taskService = inject(PendingTasks);
const taskCleanup = taskService.add();
try {
  await doSomeWorkThatNeedsToBeRendered();
} catch {
  // handle error
} finally {
  taskCleanup();
}
```

此外，`rxjs-interop` 中的 [pendingUntilEvent](/api/core/rxjs-interop/pendingUntilEvent) 輔助函式，能確保應用程式在 observable 發出值、完成、發生錯誤或被取消訂閱之前，一直保持不穩定。

```typescript
readonly myObservableState = someObservable.pipe(pendingUntilEvent());
```

框架內部也使用這個服務，來防止序列化在非同步工作完成之前進行。這些工作包括但不限於：正在進行的 Router 導航，以及尚未完成的 `HttpClient` 請求。

### Zoneless 應用程式中的反應式表單

反應式表單的模型更新（`setValue`、`patchValue`、`FormArray.push` 與類似 API）會更新表單狀態並發出表單 observable，但不會自動排程元件的變更偵測。

如果範本仰賴反應式表單的狀態，請將表單 observable 連接到變更偵測通知（例如 `ChangeDetectorRef.markForCheck()`），或透過範本所使用的訊號來反映資料。

## 測試與除錯

### 在 `TestBed` 中使用 Zoneless {#using-zoneless-in-testbed}

`TestBed` 預設使用 zoneless 變更偵測，即使 `zone.js` 是透過 `polyfills` 載入的也一樣。

若要在測試中使用以 Zone 為基礎的變更偵測，請將 `provideZoneChangeDetection()` 加入 `TestBed` providers。加入 `provideZonelessChangeDetection()` 是選用的：

```typescript
TestBed.configureTestingModule({
  // Optional: include the provider to force the testing environment
  // uses the same zoneless behavior as a zoneless application.
  providers: [provideZonelessChangeDetection()],
});

const fixture = TestBed.createComponent(MyComponent);
await fixture.whenStable();
```

為了確保測試的行為與正式環境程式碼盡可能相似，請盡可能避免使用 `fixture.detectChanges()`。這會強制執行變更偵測，而在當時 Angular 可能原本並沒有排程變更偵測。測試應該確保這些通知有在發生，並讓 Angular 處理何時同步狀態，而不是在測試中手動強制它發生。

對於既有的測試套件來說，使用 `fixture.detectChanges()` 是常見的模式，可能不值得花力氣把這些改成 `await fixture.whenStable()`。`TestBed` 仍會強制要求 fixture 的元件與 `OnPush` 相容，且若它發現範本值在沒有變更通知的情況下被更新（也就是 `fixture.componentInstance.someValue = 'newValue';`），會擲出 `ExpressionChangedAfterItHasBeenCheckedError`。
如果該元件用在正式環境中，應該透過將元件改為使用訊號管理狀態，或呼叫 `ChangeDetectorRef.markForCheck()` 來解決這個問題。
如果該元件僅作為測試包裝器使用、從不用在應用程式中，那麼為它使用 `ChangeDetectionStrategy.Eager` 並呼叫 `fixture.changeDetectorRef.markForCheck()` 是可以接受的。

IMPORTANT: `fixture.changeDetectorRef` 屬於 fixture 的宿主檢視，因此它的 `markForCheck()` 不會重新整理 `OnPush` 元件的範本。你的應用程式元件在測試中不需要它。如果測試需要它，通常表示該元件並非完全反應式，或未[符合 Zoneless 相容性要求](#requirements-for-zoneless-compatibility)。

### 以除錯模式檢查確保更新被偵測到

IMPORTANT: `provideCheckNoChangesConfig` 處於[開發者預覽](reference/releases#developer-preview)階段。

Angular 還提供了一個額外工具，協助驗證應用程式是否以符合 zoneless 相容性的方式更新狀態。`provideCheckNoChangesConfig({exhaustive: true, interval: <milliseconds>})` 可以用來定期檢查，確保沒有繫結在未通知的情況下被更新。如果有已更新但不會被 zoneless 變更偵測重新整理的繫結，Angular 會擲出 `ExpressionChangedAfterItHasBeenCheckedError`。
身為一個開源專案，Angular 每日的提交、PR 與動能都可以在 GitHub 上追蹤。為了讓這份日常工作如何與框架的未來相連更加透明，我們的藍圖彙整了團隊目前與未來規劃的願景。

下列專案並未與特定的 Angular 版本綁定。我們會在完成時發布它們，並依我們的版本發布時程、遵循語意化版本管理，將它們納入特定版本。例如，我們會在功能完成後的下一個次要版本中發布它，如果包含破壞性變更，則會在下一個主要版本中發布。

目前，Angular 對框架有三個目標：

1. 改善[開發者的 AI 體驗](/ai)
1. 改善 [Angular 開發者體驗](#improving-the-angular-developer-experience)
1. 改善框架的效能

繼續閱讀，了解我們打算如何透過具體的專案工作來實現這些目標。

## 探索現代 Angular

開始使用我們藍圖中最新的 Angular 功能進行開發。這份清單代表我們藍圖中新功能的目前狀態：

### 可供實驗

- [Web MCP](/ai/webmcp)

### 已可投入生產環境

- [Signal Forms](/guide/forms/signals/overview)
- [Resource API](/guide/signals/resource)
- [httpResource](/api/common/http/httpResource)
- [無 Zone 變更偵測](/guide/zoneless)
- [Linked Signal API](/guide/signals/linked-signal)
- [漸進式水合](/guide/incremental-hydration)
- [Effect API](/api/core/effect)
- [SSR 事件重播](/api/platform-browser/withEventReplay)
- [路由層級渲染模式](/guide/ssr)

## 改善 Angular 開發者的 AI 體驗

### 將最好的 AI 帶給 Angular
## 改善 Angular 開發者體驗 {#improving-the-angular-developer-experience}

### 開發速度
### 改善工具
## 已完成的專案
# 讓你的 Angular 專案保持最新

就像 Web 與整個網路生態系一樣，Angular 也在持續進步。
Angular 在持續改進的同時，也非常重視穩定性，並讓更新變得簡單直接。
讓你的 Angular 應用程式保持最新，能讓你利用最先進的新功能，以及最佳化與錯誤修正。

本文件包含資訊與資源，協助你讓 Angular 應用程式與程式庫保持最新。

關於我們的版本政策與實務（包括支援與棄用實務，以及發行時程），請參閱 [Angular 版本與發行](reference/releases 'Angular 版本管理與版本發布')。

HELPFUL: 若你目前使用的是 AngularJS，請參閱 [Upgrading from AngularJS](https://angular.io/guide/upgrade 'Upgrading from AngularJS')。
_AngularJS_ 是所有 v1.x 版本 Angular 的名稱。

## 收到新版本發行的通知

若想在新版本推出時收到通知，請在 X（前身為 Twitter）上追蹤 [@angular](https://x.com/angular '@angular on X')，或訂閱 [Angular 部落格](https://blog.angular.dev 'Angular blog')。

## 了解新功能

有什麼新東西？有什麼改變？我們會在 Angular 部落格的[發行公告](https://blog.angular.dev/ 'Angular blog - release announcements')中，分享你最需要知道的重要事項。

若要檢視依版本整理的完整變更清單，請參閱 [Angular 變更記錄](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular change log')。

## 檢查你的 Angular 版本

若要檢查你應用程式的 Angular 版本，請在專案目錄中使用 `ng version` 指令。

## 尋找目前的 Angular 版本

最新穩定發行的 Angular 版本會出現在 [npm](https://www.npmjs.com/package/@angular/core 'Angular on npm') 的「Version」下方。例如 `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#angular-versioning 'Angular 版本發布實務與版本編號') 說明了你可以依發行版本號預期何種程度的變更。
它也說明了受支援的更新路徑。

## 資源摘要

- 發行公告：
  [Angular 部落格 - 發行公告](https://blog.angular.dev/ 'Angular blog announcements about recent releases')

- 發行細節：
  [Angular 變更記錄](https://github.com/angular/angular/blob/main/CHANGELOG.md 'Angular change log')

- 更新說明：
  [Angular 更新指南](update-guide)

- 更新指令參考：
  [Angular CLI `ng update` 指令參考](cli/update)

- 版本、發行、支援與棄用實務：
  [Angular 版本與發行](reference/releases 'Angular 版本管理與版本發布')
_國際化_（有時簡稱為 i18n）是設計並準備你的專案，讓它能在世界各地的不同地區設定中使用的程序。
_在地化_是為不同地區設定建立專案版本的程序。
在地化程序包括下列動作。

- 擷取文字，以便翻譯成不同語言
- 依特定地區設定格式化資料

_地區設定_識別人們使用某種語言或其變體所在的區域。
可能的區域包括國家與地理區域。
地區設定決定了下列細節的格式化與解析方式。

- 度量單位，包括日期與時間、數字與貨幣
- 翻譯後的名稱，包括時區、語言與國家

想快速了解在地化與國際化，請觀看這支影片：

<docs-video src="https://www.youtube.com/embed/KNTN-nsbV7M"/>

## 了解 Angular 國際化
# 安全性

本主題說明 Angular 內建的防護措施，如何抵禦常見的 Web 應用程式弱點與攻擊，例如跨站指令碼攻擊。
本主題不涵蓋應用程式層級的安全性，例如驗證與授權。

關於下述攻擊與緩解措施的更多資訊，請參閱 [Open Web Application Security Project (OWASP) Guide](https://www.owasp.org/index.php/Category:OWASP_Guide_Project)。

<a id="report-issues"></a>
Angular 是 Google [Open Source Software Vulnerability Reward Program](https://bughunters.google.com/about/rules/6521337925468160/google-open-source-software-vulnerability-reward-program-rules) 的一部分。若發現 Angular 的弱點，請至 [https://bughunters.google.com](https://bughunters.google.com/report) 提交報告。

關於 Google 如何處理安全性問題的更多資訊，請參閱 [Google's security philosophy](https://www.google.com/about/appsecurity)。
## 最佳實務

以下是一些確保 Angular 應用程式安全的最佳實務。

1. **與最新版的 Angular 程式庫保持同步**：Angular 程式庫會定期更新，這些更新可能修復先前版本中發現的安全性缺陷。請查看 Angular 的 [變更日誌](https://github.com/angular/angular/blob/main/CHANGELOG.md)，了解與安全性相關的更新。
2. **不要修改你手邊的 Angular 副本**：私自客製化的 Angular 版本往往跟不上目前版本，可能未包含重要的安全性修復與增強。請改為與社群分享你的 Angular 改進，並提交 pull request。
3. **避免使用文件中標示為「_Security Risk_」的 Angular API**：更多資訊請參閱本頁的 [信任安全值](#trusting-safe-values) 一節。

## 防止跨站指令碼攻擊 (XSS)

[跨站指令碼攻擊 (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) 讓攻擊者能把惡意程式碼注入網頁。
這類程式碼接著可能竊取使用者與登入資料，或冒充使用者執行操作。
這是網路上最常見的攻擊之一。

要阻擋 XSS 攻擊，你必須防止惡意程式碼進入文件物件模型 (DOM)。
例如，攻擊者若能誘使你把 `<script>` 標籤插入 DOM，就能在你的網站上執行任意程式碼。
攻擊不限於 `<script>` 標籤，DOM 中許多元素與屬性都允許執行程式碼，例如 `<img alt="" onerror="...">` 與 `<a href="javascript:...">`。
只要攻擊者控制的資料進入 DOM，就要預期會出現安全性弱點。

### Angular 的跨站指令碼安全性模型

為了有系統地阻擋 XSS 漏洞，Angular 預設把所有值都視為不受信任。
當一個值透過範本繫結或插值插入 DOM 時，Angular 會清理並跳脫不受信任的值。
若某個值已在 Angular 之外清理完成且被視為安全，請把該 [值標示為受信任](#trusting-safe-values)，以告知 Angular。

與用於渲染的值不同，Angular 範本預設被視為受信任，應當作可執行程式碼看待。
絕不要把使用者輸入與範本語法串接起來建立範本。
這麼做會讓攻擊者能把 [任意程式碼注入](https://en.wikipedia.org/wiki/Code_injection) 你的應用程式。
為了防止這類弱點，在正式部署時請務必使用預設的 [Ahead-Of-Time (AOT) 範本編譯器](#use-the-aot-template-compiler)。

使用內容安全性原則與 Trusted Types，可以提供額外一層防護。
這些 Web 平台功能在 DOM 層級運作，而這正是防止 XSS 問題最有效的位置。在這一層，它們無法被其他較低層級的 API 繞過。
因此，強烈建議善用這些功能。作法是：為應用程式設定 [內容安全性原則](#content-security-policy)，並啟用 [Trusted Types 強制執行](#enforcing-trusted-types)。

### 清理與安全性上下文

_清理_ 是檢查不受信任的值，把它轉換為可以安全插入 DOM 的值。
在許多情況下，清理根本不會改變值。
清理取決於上下文。
例如，在 CSS 中無害的值，在 URL 中可能具有危險性。

Angular 定義了下列安全性上下文：

Angular 會清理 HTML 與 URL 中不受信任的值。資源 URL 無法清理，因為它們含有任意程式碼。
在開發模式下，當 Angular 必須在清理過程中改變某個值時，會在主控台印出警告。

### 清理範例

下列範本繫結了 `htmlSnippet` 的值：一次是把它插值到元素的內容中，另一次是把它繫結到元素的 `innerHTML` 屬性：

<docs-code header="inner-html-binding.component.html" path="adev/src/content/examples/security/src/app/inner-html-binding.component.html"/>

插值的內容一律會被跳脫，HTML 不會被解讀，瀏覽器會在元素的文字內容中顯示角括號。

若要讓 HTML 被解讀，請把它繫結到 `innerHTML` 這類 HTML 屬性。
請注意，把攻擊者可能控制的值繫結到 `innerHTML`，通常會造成 XSS 弱點。
例如，可以用下列方式執行 JavaScript：

<docs-code header="inner-html-binding.component.ts (class)" path="adev/src/content/examples/security/src/app/inner-html-binding.component.ts" region="class"/>

Angular 會把該值辨識為不安全並自動清理，移除 `script` 元素，但保留 `<b>` 元素這類安全內容。

### 直接使用 DOM API 與明確的清理呼叫

除非你強制執行 Trusted Types，否則瀏覽器內建的 DOM API 不會自動保護你免於安全性弱點。
例如，`document`、透過 `ElementRef` 取得的節點，以及許多第三方 API，都含有不安全的方法。
同樣地，若你與其他操作 DOM 的程式庫互動，很可能無法享有與 Angular 插值相同的自動清理。
請盡量避免直接與 DOM 互動，改用 Angular 範本。

若無法避開這種情況，請使用 Angular 內建的清理函式。
以 [DomSanitizer.sanitize](api/platform-browser/DomSanitizer#sanitize) 方法與適當的 `SecurityContext`，清理不受信任的值。
該函式也接受使用 `bypassSecurityTrust` 函式標示為受信任的值，並且不會清理它們，如 [下文所述](#trusting-safe-values)。

### 信任安全值 {#trusting-safe-values}

有時應用程式確實需要包含可執行程式碼、顯示來自某個 URL 的 `<iframe>`，或建構可能危險的 URL。
在這些情況下若要防止自動清理，請告知 Angular：你已檢查該值、確認它的建立方式，並確定它安全無虞。
請務必 _小心謹慎_。
若你信任了一個可能惡意的值，就是在應用程式中引入安全性弱點。
如有疑問，請找專業的安全性審查人員。

若要把值標示為受信任，請注入 `DomSanitizer`，並呼叫下列其中一個方法：

- `bypassSecurityTrustHtml`
- `bypassSecurityTrustScript`
- `bypassSecurityTrustStyle`
- `bypassSecurityTrustUrl`
- `bypassSecurityTrustResourceUrl`

請記住，值是否安全取決於上下文，所以請依值的預期用途選擇正確的上下文。
假設下列範本需要把 URL 繫結到一個 `javascript:alert(...)` 呼叫：

<docs-code header="bypass-security.component.html (URL)" path="adev/src/content/examples/security/src/app/bypass-security.component.html" region="URL"/>

通常，Angular 會自動清理 URL、停用危險的程式碼，並在開發模式下把這個動作記錄到主控台。
若要防止這件事，請使用 `bypassSecurityTrustUrl` 呼叫，把 URL 值標示為受信任的 URL：

<docs-code header="bypass-security.component.ts (trust-url)" path="adev/src/content/examples/security/src/app/bypass-security.component.ts" region="trust-url"/>

若需要把使用者輸入轉換為受信任的值，請使用元件方法。
下列範本讓使用者輸入 YouTube 影片 ID，並在 `<iframe>` 中載入對應的影片。
`<iframe src>` 屬性屬於資源 URL 安全性上下文，因為不受信任的來源可能夾帶檔案下載，讓不知情的使用者執行。
為了防止這件事，請呼叫元件上的方法來建構受信任的影片 URL，讓 Angular 允許繫結到 `<iframe src>`：

<docs-code header="bypass-security.component.html (iframe)" path="adev/src/content/examples/security/src/app/bypass-security.component.html" region="iframe"/>

<docs-code header="bypass-security.component.ts (trust-video-url)" path="adev/src/content/examples/security/src/app/bypass-security.component.ts" region="trust-video-url"/>

### 內容安全性原則 {#content-security-policy}

內容安全性原則 $CSP$ 是一種防止 XSS 的深度防禦技術。
若要啟用 CSP，請設定你的 Web 伺服器傳回適當的 `Content-Security-Policy` HTTP 標頭。
關於內容安全性原則的更多資訊，請參閱 Google Developers 網站上的 [Web Fundamentals guide](https://developers.google.com/web/fundamentals/security/csp)。

全新 Angular 應用程式所需的最小原則如下：

```txt
default-src 'self'; style-src 'self' 'nonce-randomNonceGoesHere'; script-src 'self' 'nonce-randomNonceGoesHere';
```

提供 Angular 應用程式服務時，伺服器應在每個請求的 HTTP 標頭中包含隨機產生的 nonce。
你必須把這個 nonce 提供給 Angular，框架才能渲染 `<style>` 元素。
你可以用下列其中一種方式為 Angular 設定 nonce：

1. 把 `ngCspNonce` 屬性設在根應用程式元素上，如 `<app ngCspNonce="randomNonceGoesHere"></app>`。若你能使用伺服器端範本，在建構回應時同時把 nonce 加入標頭與 `index.html`，請使用這個作法。
1. 使用 `CSP_NONCE` 注入權杖提供 nonce。若你在執行時能取得 nonce，且希望能快取 `index.html`，請使用這個作法。

```ts
import {CSP_NONCE} from '@angular/core';
import {bootstrapApplication} from '@angular/platform-browser';
import {AppComponent} from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    {
      provide: CSP_NONCE,
      useValue: globalThis.myRandomNonceValue,
    },
  ],
});
```
請務必確保你提供的 nonce <strong>每個請求都唯一</strong>，且不可預測或猜測。
若攻擊者能預測未來的 nonce，就能繞過 CSP 提供的防護。

使用 CDN 時，一般不建議在來源伺服器產生 nonce，因為回應經常被快取。若伺服器產生 nonce 而 CDN 快取了該 HTML 回應，每位後續訪客都會收到相同的「唯一」值，攻擊者就能發現這個靜態值並繞過 CSP 防護。

為了維持 nonce「單次使用」的完整性，理想上它應在內容交付給使用者之前，於邊緣層（例如 CDN）產生。
NOTE: 若你想把應用程式的 [關鍵 CSS 內嵌](/tools/cli/build#critical-css-inlining)，就不能使用 `CSP_NONCE` 權杖，應優先採用 [工作區設定](reference/configs/workspace-config#extra-build-and-test-options) 中的 `security.autoCsp` 選項，或在根應用程式元素上設定 `ngCspNonce` 屬性。

若你的專案無法產生 nonce，你可以把 `'unsafe-inline'` 加入 CSP 標頭的 `style-src` 區段，允許內嵌樣式。

| 區段                                             | 說明                                                                                                                                                                                                                                                                                                                                                     |
| :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default-src 'self';`                            | 允許頁面從相同來源載入所有需要的資源。                                                                                                                                                                                                                                                                                                                   |
| `style-src 'self' 'nonce-randomNonceGoesHere';`  | 允許頁面從相同來源 $`'self'`$ 載入全域樣式，以及 Angular 以 `nonce-randomNonceGoesHere` 插入的樣式。                                                                                                                                                                                                                                                    |
| `script-src 'self' 'nonce-randomNonceGoesHere';` | 允許頁面從相同來源 $`'self'`$ 載入 JavaScript，以及 Angular CLI 以 `nonce-randomNonceGoesHere` 插入的指令碼。只有在啟用關鍵 CSS 內嵌或子資源完整性（會注入 import map 以驗證動態匯入的區塊）時才需要，因為兩者都會把內嵌指令碼加入 `index.html`。                                                                                                       |

Angular 本身只需要這些設定就能正確運作。
隨著專案成長，你可能需要擴充 CSP 設定，以因應應用程式特有的額外功能。

#### 沒有每回應 nonce 的靜態託管

若你的託管環境或 CDN 能在邊緣替換快取 HTML 中的預留權杖（例如使用 SSI、ESI 或邊緣函式），你可以在建置 `index.html` 時，於 `ngCspNonce` 中放入預留值（例如 `<app ngCspNonce="__CSP_NONCE__"></app>`），並在每次回應時把它換成唯一的 nonce。

若你把應用程式部署到靜態主機，該主機未經邊緣轉換就原樣提供 `index.html`，請不要硬編碼靜態 nonce。改用下列其中一種作法：

##### 以 `autoCsp` 對內嵌指令碼進行雜湊 {#hash-inline-scripts-with-autocsp}

在 [工作區設定](reference/configs/workspace-config#extra-build-and-test-options) 中，把 `security.autoCsp` 選項設為 `true`。
建置時，Angular CLI 會計算 `index.html` 中每個內嵌指令碼的雜湊，包括關鍵 CSS 內嵌與子資源完整性加入的指令碼。
CLI 會把 `<script src>` 元素換成經過雜湊的載入器指令碼，並在 `<head>` 開頭加入一個 `<meta>` 標籤：

```txt
script-src 'strict-dynamic' 'sha256-...' https: 'unsafe-inline'; object-src 'none'; base-uri 'self';
```

由於雜湊只取決於指令碼的內容，`index.html` 對每位訪客都保持有效，且可以快取。
支援雜湊與 `'strict-dynamic'` 的瀏覽器會忽略 `https:` 與 `'unsafe-inline'` 這些備援來源。

`autoCsp` 產生的原則有下列限制：

- 它只涵蓋指令碼。你必須另外設定 `style-src`。
- 某些指示詞出現在 `<meta>` 標籤中時會被瀏覽器忽略，例如 `frame-ancestors`、`report-uri` 與 `sandbox`。請在 `Content-Security-Policy` HTTP 標頭中傳送這些指示詞。
- 當頁面有多個原則時，瀏覽器會全部強制執行。若你也傳送 CSP 標頭，請從標頭中省略 `script-src` 與 `default-src`，以免它們阻擋經過雜湊的內嵌指令碼。
- `autoCsp` 不能與伺服器端渲染一起使用。

##### 避免內嵌指令碼

Angular CLI 只會為了關鍵 CSS 內嵌與子資源完整性（會發出 import map，攜帶動態模組匯入的完整性中繼資料），把內嵌指令碼加入 `index.html`。
若你把 `optimization.styles.inlineCritical` 設為 `false`，並讓 `subresourceIntegrity` 保持停用，`index.html` 就不會包含內嵌指令碼。你接著便可以設定帶有 `script-src 'self'` 的 `Content-Security-Policy` 標頭。

NOTE: 停用關鍵 CSS 內嵌可能拖慢應用程式的初次渲染，停用子資源完整性則會移除指令碼完整性檢查。

##### 為靜態託管設定樣式

Angular 會在執行時為元件樣式插入 `<style>` 元素，關鍵 CSS 內嵌也會把一個 `<style>` 元素加入 `index.html`。
`autoCsp` 與停用內嵌指令碼都不涵蓋這些樣式。在沒有每回應 nonce 的情況下，請把 `'unsafe-inline'` 加入 `style-src` 來允許它們。
例如，若你的建置避免了內嵌指令碼，請設定主機傳送下列標頭：

```txt
default-src 'self'; style-src 'self' 'unsafe-inline';
```

若你使用 `autoCsp`，請在 HTTP 標頭中傳送 `style-src 'self' 'unsafe-inline'`，且不要包含 `default-src` 或 `script-src`。

在這兩種情況下，你的應用程式程式碼與第三方程式庫都可能需要額外的指示詞。

### 強制執行 Trusted Types {#enforcing-trusted-types}

建議你使用 [Trusted Types](https://w3c.github.io/trusted-types/dist/spec/)，協助保護應用程式免於跨站指令碼攻擊。
Trusted Types 是一項 [Web 平台](https://en.wikipedia.org/wiki/Web_platform) 功能，透過強制更安全的撰碼實務，協助你防止跨站指令碼攻擊。
Trusted Types 也能協助簡化應用程式程式碼的稽核。
Trusted Types 可能尚未在你的應用程式目標的所有瀏覽器中提供。
若啟用 Trusted Types 的應用程式在不支援 Trusted Types 的瀏覽器中執行，應用程式的功能仍會保留。你的應用程式會透過 Angular 的 DomSanitizer 防範 XSS。
目前的瀏覽器支援情況請參閱 [caniuse.com/trusted-types](https://caniuse.com/trusted-types)。
若要為應用程式強制執行 Trusted Types，你必須設定應用程式的 Web 伺服器，發出帶有下列其中一個 Angular 原則的 HTTP 標頭：

| 原則                     | 說明                                                                                                                                                                                                                                                                                     |
| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `angular`                | 此原則用於 Angular 內部經過安全性審查的程式碼，在強制執行 Trusted Types 時，Angular 需要它才能運作。任何內嵌範本值或經 Angular 清理的內容，都會被此原則視為安全。                                                                                                                            |
| `angular#bundler`        | Angular CLI 建置器在建立延遲載入區塊檔案時使用此原則。                                                                                                                                                                                                                                     |
| `angular#unsafe-bypass`  | 使用 Angular [DomSanitizer](api/platform-browser/DomSanitizer) 中任何繞過安全性的方法（例如 `bypassSecurityTrustHtml`）的應用程式，會使用此原則。任何使用這些方法的應用程式都必須啟用此原則。                                                                                                  |
| `angular#unsafe-jit`     | 此原則由 [Just-In-Time (JIT) 編譯器](api/core/Compiler) 使用。若你的應用程式直接與 JIT 編譯器互動，或使用 [platform browser dynamic](api/platform-browser-dynamic/platformBrowserDynamic) 在 JIT 模式下執行，就必須啟用此原則。                                                                    |
| `angular#unsafe-upgrade` | 此原則由 [@angular/upgrade](api/upgrade/static/UpgradeModule) 套件使用。若你的應用程式是 AngularJS 混合應用程式，就必須啟用此原則。                                                                                                                                                           |

你應在下列位置設定 Trusted Types 的 HTTP 標頭：

- 正式環境的服務基礎設施
- Angular CLI $`ng serve`$：使用 `angular.json` 檔案中的 `headers` 屬性，用於本機開發與端對端測試
- Karma $`ng test`$：使用 `karma.config.js` 檔案中的 `customHeaders` 屬性，用於單元測試

以下是專為 Trusted Types 與 Angular 設定的標頭範例：

```html
Content-Security-Policy: trusted-types angular; require-trusted-types-for 'script';
```

以下是專為 Trusted Types，以及使用 Angular [DomSanitizer](api/platform-browser/DomSanitizer) 中任何繞過安全性方法的 Angular 應用程式所設定的標頭範例：

```html
Content-Security-Policy: trusted-types angular angular#unsafe-bypass; require-trusted-types-for
'script';
```

以下是專為 Trusted Types 與使用 JIT 的 Angular 應用程式所設定的標頭範例：

```html
Content-Security-Policy: trusted-types angular angular#unsafe-jit; require-trusted-types-for
'script';
```

以下是專為 Trusted Types 與使用模組延遲載入的 Angular 應用程式所設定的標頭範例：

```html
Content-Security-Policy: trusted-types angular angular#bundler; require-trusted-types-for 'script';
```
若要深入了解如何疑難排解 Trusted Types 設定，下列資源可能有幫助：

[Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types](https://web.dev/trusted-types/#how-to-use-trusted-types)
### 使用 AOT 範本編譯器 {#use-the-aot-template-compiler}

AOT 範本編譯器能防止一整類稱為範本注入的弱點，並大幅提升應用程式效能。
AOT 範本編譯器是 Angular CLI 應用程式使用的預設編譯器，你應在所有正式部署中使用它。

AOT 編譯器的替代方案是 JIT 編譯器，它在執行時於瀏覽器內把範本編譯為可執行的範本程式碼。Angular 信任範本程式碼，因此動態產生範本並加以編譯（尤其是含有使用者資料的範本），會繞過 Angular 內建的防護。這是一種安全性反模式。
關於如何安全地動態建構表單，請參閱 [動態表單](guide/forms/dynamic-forms) 指南。

### 伺服器端 XSS 防護

在伺服器上建構的 HTML 容易受到注入攻擊。
把範本程式碼注入 Angular 應用程式，等同於把可執行程式碼注入應用程式：攻擊者將取得應用程式的完全控制權。
為了防止這件事，請使用會自動跳脫值的範本語言，以防止伺服器端的 XSS 弱點。
不要在伺服器端使用範本語言建立 Angular 範本。這麼做很有可能引入範本注入弱點。

## HTTP 層級的弱點

Angular 內建支援，協助防止兩種常見的 HTTP 弱點：跨站請求偽造 $CSRF 或 XSRF$ 與跨站指令碼包含 $XSSI$。
這兩者都必須主要在伺服器端緩解，但 Angular 提供了輔助工具，讓用戶端的整合更容易。

### 跨站請求偽造

在跨站請求偽造 $CSRF 或 XSRF$ 攻擊中，攻擊者誘使使用者造訪另一個帶有惡意程式碼的網頁 $例如 `evil.com`$。這個網頁會秘密地向應用程式的 Web 伺服器 $例如 `example-bank.com`$ 傳送惡意請求。

假設使用者已登入 `example-bank.com` 的應用程式。
使用者開啟一封電子郵件，點選連往 `evil.com` 的連結，連結在新分頁中開啟。

`evil.com` 頁面立即向 `example-bank.com` 傳送惡意請求。
這個請求可能是把使用者的帳戶資金轉到攻擊者的帳戶。
瀏覽器會自動把 `example-bank.com` 的 cookie（包括驗證 cookie）隨這個請求一起傳送。

若 `example-bank.com` 伺服器缺乏 XSRF 防護，就無法分辨來自應用程式的合法請求與來自 `evil.com` 的偽造請求。

為了防止這件事，應用程式必須確保使用者請求源自真正的應用程式，而不是其他網站。
伺服器與用戶端必須合作，才能阻擋這類攻擊。

在一種常見的反 XSRF 技術中，應用程式伺服器會在 cookie 中傳送隨機建立的驗證權杖。
用戶端程式碼讀取該 cookie，並在後續所有請求中加入帶有該權杖的自訂請求標頭。
伺服器會把收到的 cookie 值與請求標頭值進行比較，若值缺失或不相符，就拒絕該請求。

這項技術之所以有效，是因為所有瀏覽器都實作了 _同源政策_。
只有設定 cookie 的網站的程式碼，才能讀取該網站的 cookie，並對發往該網站的請求設定自訂標頭。
這表示只有你的應用程式能讀取這個 cookie 權杖並設定自訂標頭。
`evil.com` 上的惡意程式碼做不到。

### `HttpClient` 的 XSRF/CSRF 安全性

`HttpClient` 支援一種用來防止 XSRF 攻擊的 [常見機制](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Cookie-to-header_token)。執行 HTTP 請求時，攔截器會從 cookie 讀取權杖（預設為 `XSRF-TOKEN`），並把它設為 HTTP 標頭 `X-XSRF-TOKEN`。由於只有在你的網域上執行的程式碼能讀取該 cookie，後端可以確定 HTTP 請求來自你的用戶端應用程式，而不是攻擊者。

預設情況下，攔截器會在所有發往相對 URL 與同源 URL 的變更型請求（例如 `POST`）上傳送這個標頭，但不會在 `GET` 或 `HEAD` 請求上傳送。
CSRF 防護只對能改變後端狀態的請求才有必要。CSRF 攻擊本質上會跨越網域界線，而 Web 的 [同源政策](https://developer.mozilla.org/docs/Web/Security/Same-origin_policy) 會防止攻擊頁面取得已驗證 `GET` 請求的結果。
若要善用這項機制，你的伺服器需要在頁面載入時或第一個 GET 請求時，把權杖設在一個 JavaScript 可讀取、名為 `XSRF-TOKEN` 的工作階段 cookie 中。在後續請求中，伺服器可以驗證 cookie 是否與 `X-XSRF-TOKEN` HTTP 標頭相符，藉此確定只有在你的網域上執行的程式碼可能傳送該請求。權杖對每位使用者都必須唯一，且必須可由伺服器驗證；這能防止用戶端自行捏造權杖。請把權杖設為你網站驗證 cookie 加上 salt 的摘要，以加強安全性。

為了防止多個 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())],
};
```

關於 Open Web Application Security Project $OWASP$ 的 CSRF 資訊，請參閱 [Cross-Site Request Forgery (CSRF)](https://owasp.org/www-community/attacks/csrf) 與 [Cross-Site Request Forgery (CSRF) Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)。
史丹佛大學的論文 [Robust Defenses for Cross-Site Request Forgery](https://seclab.stanford.edu/websec/csrf/csrf.pdf) 提供了豐富的細節。

另請參閱 Dave Smith 在 AngularConnect 2016 的 [XSRF 演講](https://www.youtube.com/watch?v=9inczw6qtpY 'Cross Site Request Funkery Securing Your Angular Apps From Evil Doers')。

### 跨站指令碼包含 (XSSI)

跨站指令碼包含，也稱為 JSON 弱點，可讓攻擊者的網站讀取 JSON API 的資料。
這種攻擊在較舊的瀏覽器上，透過覆寫內建的 JavaScript 物件建構函式，再使用 `<script>` 標籤包含 API URL 來達成。

只有當傳回的 JSON 可作為 JavaScript 執行時，這種攻擊才會成功。
伺服器可以為所有 JSON 回應加上前綴，使其無法執行，藉此防止攻擊；慣例上使用眾所周知的字串 `")]}',\n"`。

Angular 的 `HttpClient` 程式庫認得這項慣例，會在進一步剖析之前，自動從所有回應中移除字串 `")]}',\n"`。

更多資訊請參閱這篇 [Google Web 安全性部落格文章](https://security.googleblog.com/2011/05/website-security-for-webmasters.html) 的 XSSI 一節。

## 防止伺服器端請求偽造 (SSRF) {#preventing-server-side-request-forgery-ssrf}

Angular 在請求處理管線中，對 `Host`、`Forwarded`、`X-Forwarded-Host`、`X-Forwarded-Proto`、`X-Forwarded-Prefix` 與 `X-Forwarded-Port` 標頭進行嚴格驗證，以防止以標頭為基礎的 [伺服器端請求偽造 (SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF)。

驗證規則如下：

- `Host`、`X-Forwarded-Host`，以及 `Forwarded` 標頭的 `host` 參數，會對照嚴格的允許清單進行驗證，且不能包含路徑分隔符號。
- `X-Forwarded-Port` 標頭必須是數字。
- `X-Forwarded-Proto` 標頭與 `Forwarded` 標頭的 `proto` 參數，必須是 `http` 或 `https`。
- `X-Forwarded-Prefix` 標頭必須以 `/` 開頭，且只能包含英數字元、連字號與底線，並以單個斜線分隔。
- 預設情況下，`Forwarded` 標頭與所有 `X-Forwarded-*` 標頭都會被視為不受信任，並從請求中移除。若要保留它們，必須設定 `trustProxyHeaders` 明確允許。

無效的標頭會觸發錯誤記錄，未經允許的 proxy 標頭會從請求中移除。主機名稱無法辨識的請求，將導致 `400 Bad Request`。

NOTE: 大多數雲端供應商與 CDN 供應商，會在請求到達應用程式來源之前，自動驗證這些標頭。這種內建的過濾大幅縮小了實際的攻擊面。

### 設定允許的主機

若要允許特定的主機名稱，你需要把它們加入允許清單。這對確保應用程式在部署時正確且安全地運作至關重要。這些模式支援萬用字元，讓主機名稱比對更有彈性。

你可以在 `angular.json` 中設定 `allowedHosts` 選項：

```json
{hideCopy}
{
  // ...
  "projects": {
    "your-project-name": {
      // ...
      "architect": {
        "build": {
          "builder": "@angular/build:application",
          "options": {
            "security": {
              "allowedHosts": [
                "example.com",
                "*.example.com" // allows all subdomains of example.com
              ]
            }
            // ... other options
          }
        }
      }
    }
  }
}
```

你也可以在初始化應用程式引擎時設定 `allowedHosts`：

```typescript
const appEngine = new AngularAppEngine({
  allowedHosts: ['example.com', '*.trusted-example.com'],
});

const nodeAppEngine = new AngularNodeAppEngine({
  allowedHosts: ['example.com', '*.trusted-example.com'],
});
```

對於 Node.js 版本的 `AngularNodeAppEngine`，你也可以提供 `NG_ALLOWED_HOSTS`（以逗號分隔的清單）環境變數來授權主機。

```bash
{hideDollar}
export NG_ALLOWED_HOSTS="example.com,*.trusted-example.com"
```

IMPORTANT: 你可以在 `allowedHosts` 中使用 `*` 作為值，允許所有主機名稱，但一般不建議這麼做，因為這會帶來安全性風險。接受任何主機標頭，可能使你的應用程式暴露於主機標頭注入與 [伺服器端請求偽造 (SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF) 攻擊。只有在另一層（例如負載平衡器或反向 proxy）已對 `Host` 與 `X-Forwarded-Host` 標頭進行驗證時，才應使用這項設定。為了更好的安全性，我們建議盡可能使用明確的允許主機清單。更多細節請參閱 [GHSA-x288-3778-4hhx](https://github.com/angular/angular-cli/security/advisories/GHSA-x288-3778-4hhx)。

### 設定受信任的 proxy 標頭

預設情況下，Angular 會忽略標準的 `Forwarded` 標頭與所有 `X-Forwarded-*` 標頭。若你的應用程式位於會設定這些標頭的受信任反向 proxy（例如負載平衡器）之後，你可以設定 Angular 信任它們。

若 `Forwarded` 標頭受信任，它的 `host` 與 `proto` 參數會被擷取出來，並優先於對應的 `x-forwarded-host` 與 `x-forwarded-proto` 標頭。

你可以在初始化應用程式引擎時設定 `trustProxyHeaders`：

```typescript
const appEngine = new AngularAppEngine({
  trustProxyHeaders: ['forwarded'], // Trust the standard Forwarded header
});

const appEngine = new AngularAppEngine({
  trustProxyHeaders: ['x-forwarded-host', 'x-forwarded-proto'], // Trust non-standard headers
});

const nodeAppEngine = new AngularNodeAppEngine({
  trustProxyHeaders: true, // Trust standard Forwarded and all X-Forwarded-* headers
});
```

對於 Node.js 版本的 `AngularNodeAppEngine`，你也可以提供 `NG_TRUST_PROXY_HEADERS` 環境變數（值為以逗號分隔的標頭清單），允許使用這些標頭。

```bash
{hideDollar}
export NG_TRUST_PROXY_HEADERS="X-FORWARDED-HOST,X-FORWARDED-PREFIX"
```

IMPORTANT: 只有當你的應用程式位於會嚴格驗證或覆寫這些標頭的受信任 proxy 之後，才啟用 `trustProxyHeaders`。否則，攻擊者可以偽造這些標頭，造成 [伺服器端請求偽造 (SSRF)](https://developer.mozilla.org/en-US/docs/Web/Security/Attacks/SSRF) 攻擊。

## 稽核 Angular 應用程式

Angular 應用程式必須遵循與一般 Web 應用程式相同的安全性原則，並依此接受稽核。
在安全性審查中應稽核的 Angular 專屬 API（例如 [_bypassSecurityTrust_](#trusting-safe-values) 方法），在文件中會被標示為安全性敏感。