棄用的 API 和特性link

Deprecated APIs and featureslink

Angular 力圖兼顧創新與穩定。但有時，API 和特性已經過時，需要進行刪除或替換，以便 Angular 可以及時跟上新的最佳實踐、依賴項變更或者 Web 平臺自身的變化。

Angular strives to balance innovation and stability. Sometimes, APIs and features become obsolete and need to be removed or replaced so that Angular can stay current with new best practices, changing dependencies, or changes in the (web) platform itself.

為了讓這些轉換變得儘可能簡單，我們會在刪除 API 和特性之前先棄用它們一段時間。讓你有時間把應用更新到最新的 API 和最佳實踐。

To make these transitions as easy as possible, we deprecate APIs and features for a period of time before removing them. This gives you time to update your apps to the latest APIs and best practices.

本指南包含了當前不推薦使用的所有 Angular API 和特性的彙總表。

This guide contains a summary of all Angular APIs and features that are currently deprecated.

索引link

Indexlink

為了幫助你確保應用程式的前瞻性，下表列出了所有已棄用的 API 和功能，這些 API 和功能按發行版進行組織，它們將被刪除。每個條目都連結到本指南後面的部分，該部分描述了棄用原因和替換選項。

To help you future-proof your apps, the following table lists all deprecated APIs and features, organized by the release in which they are candidates for removal. Each item is linked to the section later in this guide that describes the deprecation reason and replacement options.

要了解 Angular CDK 和 Angular Material 的棄用情況，參閱變更記錄。

For information about Angular CDK and Angular Material deprecations, see the changelog.

已棄用的 APIlink

Deprecated APIslink

本節包含所有當前已棄用的 API 的完整列表，其中包含一些可幫助你規劃如何遷移到其替代品的詳細資訊。

This section contains a complete list all of the currently-deprecated APIs, with details to help you plan your migration to a replacement.

@angular/commonlink

@angular/common/httplink

@angular/corelink

@angular/core/testinglink

@angular/formslink

@angular/upgradelink

@angular/upgrade/staticlink

已棄用的特性link

Deprecated featureslink

本節列出了所有當前已棄用的特性，包括範本語法、配置選項，以及前面已棄用的 API 部分未列出的其它棄用。它還包括已棄用的 API 用例或 API 組合，以增強上述資訊。

This section lists all of the currently-deprecated features, which includes template syntax, configuration options, and any other deprecations not listed in the Deprecated APIs section above. It also includes deprecated API usage scenarios or API combinations, to augment the information above.

Bazel 建構器及其原理圖link

Bazel builder and schematicslink

Bazel 建構器及其原理圖曾經被引入到 Angular Labs 中，以便讓使用者嘗試 Bazel，而不用管理 Bazel 的版本和 BUILD 檔案。 該特性已經棄用了。欲知詳情，參閱遷移文件。

Bazel builder and schematics were introduced in Angular Labs to let users try out Bazel without having to manage Bazel version and BUILD files. This feature has been deprecated. For more information, please refer to the migration doc.

Web 追蹤框架整合link

Web Tracing Framework integrationlink

Angular 以前支援與 Web 追蹤框架（WTF）整合，用於 Angular 應用程式的效能測試。此整合已經停止維護並失效。因此，該整合在 Angular 版本 8 中被棄用，並且由於沒有證據表明在版本 9 中刪除了任何現有用法。

Angular previously has supported an integration with the Web Tracing Framework (WTF) for performance testing of Angular applications. This integration has not been maintained and defunct. As a result, the integration was deprecated in Angular version 8 and due to no evidence of any existing usage removed in version 9.

/deep/，>>> 和 :ng-deep 元件樣式選擇器link

/deep/, >>> and :ng-deep component style selectorslink

刺穿 Shadow DOM 的 CSS 組合符已經棄用，並且主要的瀏覽器和工具都已刪除它。因此，在 v4 中，Angular 也棄用了對 /deep/，>>> 和 ::ng-deep 的支援。在徹底刪除它之前，我們首選 ::ng-deep，以便和各種工具實現更廣泛的相容。

The shadow-dom-piercing descendant combinator is deprecated and support is being removed from major browsers and tools. As such, in v4 we deprecated support in Angular for all 3 of /deep/, >>> and ::ng-deep. Until removal, ::ng-deep is preferred for broader compatibility with the tools.

欲知詳情，參閱“元件樣式”一章中的 /deep/，>>> 和 :: ng-deep。

For more information, see /deep/, >>>, and ::ng-deep in the Component Styles guide.

<template> 標籤link

<template> taglink

<template> 標籤在 v4 中已經棄用，以消除和 DOM 中同名元素的衝突（比如在使用 Web Components 時）。請用 <ng-template> 代替。欲知詳情，參閱預先編譯一章。

The <template> tag was deprecated in v4 to avoid colliding with the DOM's element of the same name (such as when using web components). Use <ng-template> instead. For more information, see the Ahead-of-Time Compilation guide.

和響應式表單一起使用 ngModellink

ngModel with reactive formslink

對於和響應式表單指令一起使用輸入屬性 ngModel 和事件 ngModelChange 的支援已經在 Angular 6 中棄用，並且會在未來的 Angular 版本中移除。

Support for using the ngModel input property and ngModelChange event with reactive form directives has been deprecated in Angular v6 and will be removed in a future version of Angular.

現在已經棄用：

Now deprecated:

      
        content_copy
      
      <input [formControl]="control" [(ngModel)]="value">
    

      
        content_copy
      
      this.value = 'some value';
    

這種棄用有一系列理由。 首先，開發人員會對這種模式感到困惑。它看起來像是在使用 ngModel 指令，但實際上它是響應式表單指令上一個名叫 ngModel 的輸入輸出屬性。它和 ngModel 指令的行為很相似，但又不完全一樣。 它執行讀取或設定一個值，並且攔截該值的事件，但是 ngModel 的其它特性，比如透過 ngModelOptions 指定更新顯示的時機，或者匯出該指令，卻沒法用。

This has been deprecated for several reasons. First, developers have found this pattern confusing. It seems like the actual ngModel directive is being used, but in fact it's an input/output property named ngModel on the reactive form directive that approximates some, but not all, of the directive's behavior. It allows getting and setting a value and intercepting value events, but some of ngModel's other features, such as delaying updates with ngModelOptions or exporting the directive, don't work.

另外，該模式混用了範本驅動和響應式這兩種表單策略，這會妨礙我們獲取任何一種策略的全部優點。 在範本中設定值的方式，違反了響應式表單所遵循的“範本無關”原則；反之，在類別中新增 FormControl/FormGroup 層也破壞了“在範本中定義表單”的約定。

In addition, this pattern mixes template-driven and reactive forms strategies, which prevents taking advantage of the full benefits of either strategy. Setting the value in the template violates the template-agnostic principles behind reactive forms, whereas adding a FormControl/FormGroup layer in the class removes the convenience of defining forms in the template.

要想在它被移除之間修改程式碼，你需要決定是選定響應式表單指令（以及使用響應式表單模式來存取這些值），還是切換到範本驅動指令。

To update your code before support is removed, you'll want to decide whether to stick with reactive form directives (and get/set values using reactive forms patterns) or switch over to template-driven directives.

改後（選擇 1 - 使用響應式表單）：

After (choice 1 - use reactive forms):

      
        content_copy
      
      <input [formControl]="control">
    

      
        content_copy
      
      this.control.setValue('some value');
    

改後（選擇 2 - 使用範本驅動表單）：

After (choice 2 - use template-driven forms):

      
        content_copy
      
      <input [(ngModel)]="value">
    

      
        content_copy
      
      this.value = 'some value';
    

預設情況下，當使用這種模式時，你會在開發模式下看到一個棄用警告。你可以透過在匯入 ReactiveFormsModule 時提供一個配置來來禁用此警告：

By default, when you use this pattern, you will see a deprecation warning once in dev mode. You can choose to silence this warning by providing a config for ReactiveFormsModule at import time:

      
        content_copy
      
      imports: [
  ReactiveFormsModule.withConfig({warnOnNgModelWithFormControl: 'never'});
]
    

另外，你可以選擇針對使用此模式的每個實例來使用配置值 "always" 來為它們單獨顯示警告。當修改程式碼時，這可以幫助你追蹤都有哪裡使用了該模式。

Alternatively, you can choose to surface a separate warning for each instance of this pattern with a config value of "always". This may help to track down where in the code the pattern is being used as the code is being updated.

ReflectiveInjectorlink

在 v5 中，Angular 用 StaticInjector 代替了 ReflectiveInjector。該注入器不再需要 Reflect 的Polyfill指令碼，對大部分開發人員來說都顯著減小了應用的體積。

In v5, Angular replaced the ReflectiveInjector with the StaticInjector. The injector no longer requires the Reflect polyfill, reducing application size for most developers.

之前：

Before:

      
        content_copy
      
      ReflectiveInjector.resolveAndCreate(providers);
    

之後：

After:

      
        content_copy
      
      Injector.create({providers});
    

loadChildren 字串語法link

loadChildren string syntaxlink

當 Angular 第一次引入惰性路由時，還沒有瀏覽器能支援動態載入額外的 JavaScript。因此 Angular 建立了自己的方案，所用的語法是 loadChildren: './lazy/lazy.module#LazyModule' 並且還建構了一些工具來支援它。現在，很多瀏覽器都已支援 ECMAScript 的動態匯入，Angular 也正朝著這個新語法前進。

When Angular first introduced lazy routes, there wasn't browser support for dynamically loading additional JavaScript. Angular created our own scheme using the syntax loadChildren: './lazy/lazy.module#LazyModule' and built tooling to support it. Now that ECMAScript dynamic import is supported in many browsers, Angular is moving toward this new syntax.

在第 8 版中，不推薦使用 loadChildren路由規範的字串語法，loadChildren支援使用基於 import() 的新語法。

In version 8, the string syntax for the loadChildrenroute specification was deprecated, in favor of new syntax that uses import() syntax.

之前：

Before:

      
        content_copy
      
      const routes: Routes = [{
  path: 'lazy',
  // The following string syntax for loadChildren is deprecated
  loadChildren: './lazy/lazy.module#LazyModule'
}];
    

之後：

After:

      
        content_copy
      
      const routes: Routes = [{
  path: 'lazy',
  // The new import() syntax
  loadChildren: () => import('./lazy/lazy.module').then(m => m.LazyModule)
}];
    

ActivatedRoute 的 params 和 queryParams 屬性link

ActivatedRoute params and queryParams propertieslink

ActivatedRoute 包含兩個屬性，它們的能力低於它們的替代品，在將來的 Angular 版本中可能會棄用。

ActivatedRoute contains two properties that are less capable than their replacements and may be deprecated in a future Angular version.

欲知詳情，參閱路由器指南。

For more information see the Getting route information section of the Router guide.

在 JIT 模式下對 reflect-metadata Polyfill指令碼的依賴link

Dependency on a reflect-metadata polyfill in JIT modelink

Angular 應用程式，特別是依賴於 JIT 編譯器的應用程式，過去常常需要 reflect-metadata API 的Polyfill指令碼。

Angular applications, and specifically applications that relied on the JIT compiler, used to require a polyfill for the reflect-metadata APIs.

在 Angular 8.0 版中不再需要這種 polyfill（參閱#14473 ），從而使大多數 Angular 應用程式中都不需要使用這個Polyfill指令碼。因為這個Polyfill指令碼可能由第三方函式庫依賴，所以沒有從所有 Angular 專案中刪除它，所以我們不建議從 8.0 版本開始再使用這個Polyfill指令碼。這應該能給函式庫作者和應用程式開發人員足夠的時間來評估他們是否需要這個Polyfill指令碼，並執行必要的重構以消除對它的依賴。

The need for this polyfill was removed in Angular version 8.0 (see #14473), rendering the presence of the poylfill in most Angular applications unnecessary. Because the polyfill can be depended on by 3rd-party libraries, instead of removing it from all Angular projects, we are deprecating the requirement for this polyfill as of version 8.0. This should give library authors and application developers sufficient time to evaluate if they need the polyfill, and perform any refactoring necessary to remove the dependency on it.

在典型的 Angular 專案中，這個Polyfill指令碼不用於生產版本，因此刪除它不會影響生產環境的應用程式。刪除它是為了從整體上上簡化建構設定並減少外部依賴項的數量。

In a typical Angular project, the polyfill is not used in production builds, so removing it should not impact production applications. The goal behind this removal is overall simplification of the build setup and decrease in the number of external dependencies.

把 @ViewChild() / @ContentChild() 靜態解析為預設值link

@ViewChild() / @ContentChild() static resolution as the defaultlink

參閱靜態查詢的專用遷移指南。

See the dedicated migration guide for static queries.

@ContentChild() / @Input() 一起使用link

@ContentChild() / @Input() used togetherlink

以下模式已棄用：

The following pattern is deprecated:

      
        content_copy
      
      @Input() @ContentChild(TemplateRef) tpl !: TemplateRef<any>;
    

與其使用這種模式，還不如將兩個裝飾器新增到各自的屬性上並添加回退邏輯，如以下範例所示：

Rather than using this pattern, separate the two decorators into their own properties and add fallback logic as in the following example:

      
        content_copy
      
      @Input() tpl !: TemplateRef<any>;
@ContentChild(TemplateRef) inlineTemplate !: TemplateRef<any>;
    

無法賦值給範本變數link

Cannot assign to template variableslink

在下面的範例中，雙向繫結意味著在 valueChange 事件觸發時應該寫入 optionName。

In the following example, the two-way binding means that optionName should be written when the valueChange event fires.

      
        content_copy
      
      <option *ngFor="let optionName of options" [(value)]="optionName"></option>
    

但實際上，Angular 只是忽略了對範本變數的雙向繫結。從版本 8 開始，試圖寫入範本變數已棄用。在將來的版本中，我們將不支援這種寫操作。

However, in practice, Angular simply ignores two-way bindings to template variables. Starting in version 8, attempting to write to template variables is deprecated. In a future version, we will throw to indicate that the write is not supported.

      
        content_copy
      
      <option *ngFor="let optionName of options" [value]="optionName"></option>
    

在 platform-server 中繫結到 innerTextlink

Binding to innerText in platform-serverlink

在伺服器端渲染中使用的 Domino 不支援 innerText，因此在平臺伺服器中的 “domino 介面卡”中，如果嘗試繫結到 innerText，則有一些特殊程式碼可以退回到 textContent。

Domino, which is used in server-side rendering, doesn't support innerText, so in platform-server's "domino adapter", there was special code to fall back to textContent if you tried to bind to innerText.

這兩個屬性有細微的差異，切換到 textContent 可能會讓使用者感到驚訝。因此，我們棄用了此行為。展望未來，使用者應該在使用 Domino 時顯式繫結到 textContent。

These two properties have subtle differences, so switching to textContent under the hood can be surprising to users. For this reason, we are deprecating this behavior. Going forward, users should explicitly bind to textContent when using Domino.

wtfStartTimeRange 和所有 wtf* APIlink

wtfStartTimeRange and all wtf* APIslink

所有 wtf* API 均已棄用，並將在以後的版本中刪除。

All of the wtf* APIs are deprecated and will be removed in a future version.

不再需要 entryComponents 和 ANALYZE_FOR_ENTRY_COMPONENTSlink

entryComponents and ANALYZE_FOR_ENTRY_COMPONENTS no longer requiredlink

以前，NgModule 定義中的 entryComponents 陣列用於告訴編譯器將動態建立和插入哪些元件。改用 Ivy 後，將不再需要它們，並且可以從現有模組宣告中刪除 entryComponents 陣列。ANALYZE_FOR_ENTRY_COMPONENTS 注入令牌也是如此。

Previously, the entryComponents array in the NgModule definition was used to tell the compiler which components would be created and inserted dynamically. With Ivy, this isn't a requirement anymore and the entryComponents array can be removed from existing module declarations. The same applies to the ANALYZE_FOR_ENTRY_COMPONENTS injection token.

不帶泛型的 ModuleWithProviders 型別link

ModuleWithProviders type without a genericlink

一些 Angular 函式庫，例如 @angular/router 和 @ngrx/store，實現了一種返回 ModuleWithProviders 型別的 API（通常藉助名為 forRoot() 的方法）。此型別表示 NgModule 以及其它服務提供者。Angular 版本 9 不建議使用不帶顯式泛型型別的 ModuleWithProviders，泛型型別是指 NgModule 的型別。在 Angular 的未來版本中，泛型將不再是可選的。

Some Angular libraries, such as @angular/router and @ngrx/store, implement APIs that return a type called ModuleWithProviders (typically via a method named forRoot()). This type represents an NgModule along with additional providers. Angular version 9 deprecates use of ModuleWithProviders without an explicitly generic type, where the generic type refers to the type of the NgModule. In a future version of Angular, the generic will no longer be optional.

如果你使用的是 CLI，則 ng update 應該會自動遷移程式碼。如果沒有使用 CLI，則可以將任何缺失的泛型型別手動新增到應用程式中。例如：

If you're using the CLI, ng update should migrate your code automatically. If you're not using the CLI, you can add any missing generic types to your application manually. For example:

之前

Before

      
        content_copy
      
      @NgModule({...})
export class MyModule {
  static forRoot(config: SomeConfig): ModuleWithProviders {
    return {
      ngModule: SomeModule,
      providers: [
        {provide: SomeConfig, useValue: config}
      ]
    };
  }
}
    

後

After

      
        content_copy
      
      @NgModule({...})
export class MyModule {
  static forRoot(config: SomeConfig): ModuleWithProviders<SomeModule> {
    return {
      ngModule: SomeModule,
      providers: [
        {provide: SomeConfig, useValue: config }
      ]
    };
  }
}
    

WrappedValuelink

WrappedValue 的目的是讓同一個物件實例被視為不同的物件，以便進行變更檢測。比如當 Observable 產生相同實例的時候，它常用於 async 管道。

The purpose of WrappedValue is to allow the same object instance to be treated as different for the purposes of change detection. It is commonly used with the async pipe in the case where the Observable produces the same instance of the value.

鑑於此用例相對較少，並且特殊處理會影響應用效能，因此我們已在第 10 版中棄用它。這項棄用並沒有提供替代方案。

Given that this use case is relatively rare and special handling impacts application performance, we have deprecated it in v10. No replacement is planned for this deprecation.

如果你要依賴同一個物件實例引起變更檢測的行為，那麼有兩個選擇：

If you rely on the behavior that the same object instance should cause change detection, you have two options:

• 複製結果值，使其具有新的標識。

  Clone the resulting value so that it has a new identity.

• 顯式呼叫 ChangeDetectorRef.detectChanges()進行強制更新。

  Explicitly call ChangeDetectorRef.detectChanges()to force the update.

Internet Explorer 11link

Angular 對 IE11 的支援已經棄用，將會在 Angular v13 中移除。 結束對 IE11 的支援，可以讓 Angular 從那些只出現在長青瀏覽器中的 Web 平臺 API 中受益，為開發人員帶來更好地 API，並為應用的使用者提供更多的能力。 本次移除還有一個動機在於全球範圍內 IE11 的使用率已經只有 ~1%（2021年3月）。關於這次棄用的全部論證和討論，參見 RFC: Internet Explorer 11 support deprecation and removal。

Angular support for Microsoft's Internet Explorer 11 (IE11) is deprecated and will be removed in Angular v13. Ending IE11 support allows Angular to take advantage of web platform APIs present only in evergreen browsers, resulting in better APIs for developers and more capabilities for application users. An additional motivation behind this removal is the drop in global usage of IE11 to just ~1% (as of March 2021). For full rationale and discussion behind this deprecation see RFC: Internet Explorer 11 support deprecation and removal.

*注意：Angular v12 的 LTS 版本將會繼續支援 IE11，一直到 2022 年 11 月。

Note: IE11 will be supported in Angular v12 LTS releases through November 2022.

棄用的 CLI API 和選項link

Deprecated CLI APIs and Optionslink

這部分包含一個當前棄用的 CLI 標誌的完整列表。

This section contains a complete list all of the currently deprecated CLI flags.

@angular-devkit/build-angularlink

@schematics/angularlink

刪除的 APIlink

Removed APIslink

下列 API 已從 11.0.0* 版本開始移除：

The following APIs have been removed starting with version 11.0.0*:

要檢視版本 10 中移除的 API，請檢視版本 10 文件站上本指南。

*To see APIs removed in version 10, check out this guide on the version 10 docs site.

@angular/* npm 軟體套件中的 esm5 和 fesm5 程式碼格式link

esm5 and fesm5 code formats in @angular/* npm packageslink

從 Angular v8 開始，CLI 就主要使用透過 @angular/* 系列 npm 包分發的 fesm2015 變體程式碼。這就讓 esm5 和 fesm5 的發行版變得過時和不必要，只會增加軟體包大小並拖累 npm 的安裝速度。

As of Angular v8, the CLI primarily consumes the fesm2015 variant of the code distributed via @angular/* npm packages. This renders the esm5 and fesm5 distributions obsolete and unnecessary, adding bloat to the package size and slowing down npm installations.

移除它們不會對 CLI 使用者產生任何影響，除非他們修改了自己的建構配置以顯式使用程式碼的這些發行版。

This removal has no impact on CLI users, unless they modified their build configuration to explicitly consume these code distributions.

任何仍依賴 esm5 和 fesm5 作為其建構系統輸入的應用程式都需要確保建構管道能夠接受符合 ECMAScript 2015（ES2015） 語言規範的 JavaScript 程式碼。

Any application still relying on the esm5 and fesm5 as the input to its build system will need to ensure that the build pipeline is capable of accepting JavaScript code conforming to ECMAScript 2015 (ES2015) language specification.

請注意，此更改不會使以這種格式分發的現有函式庫與 Angular CLI 不相容。如果其它發行版不可用，CLI 將回退並以不太理想的格式使用函式庫。但是，我們確實建議函式庫以 ES2015 格式發佈其程式碼，以加快建構速度並減小建構輸出。

Note that this change doesn't make existing libraries distributed in this format incompatible with the Angular CLI. The CLI will fall back and consume libraries in less desirable formats if others are not available. However, we do recommend that libraries ship their code in ES2015 format in order to make builds faster and build output smaller.

實際上，所有 @angular 軟體套件的 package.json 都將以如下方式更改：

In practical terms, the package.json of all @angular packages has changed in the following way:

之前：

Before:

      
        content_copy
      
      {
  "name": "@angular/core",
  "version": "9.0.0",
  "main": "./bundles/core.umd.js",
  "module": "./fesm5/core.js",
  "es2015": "./fesm2015/core.js",
  "esm5": "./esm5/core.js",
  "esm2015": "./esm2015/core.js",
  "fesm5": "./fesm5/core.js",
  "fesm2015": "./fesm2015/core.js",
  ...
}
    

之後：

After:

      
        content_copy
      
      {
  "name": "@angular/core",
  "version": "10.0.0",
  "main": "./bundles/core.umd.js",
  "module": "./fesm2015/core.js",
  "es2015": "./fesm2015/core.js",
  "esm2015": "./esm2015/core.js",
  "fesm2015": "./fesm2015/core.js",
  ...
}
    

關於 npm 軟體包格式的更多資訊，請參閱 Angular 軟體包格式規範。

For more information about the npm package format, see the Angular Package Format spec.

[style] 和 [style.prop] 繫結的樣式無害化link

Style Sanitization for [style] and [style.prop] bindingslink

Angular 會清理 [style] 和 [style.prop] 繫結，以防止惡意程式碼透過 CSS url() 條目中的 javascript: 表示式進行插入。但是，大多數現代瀏覽器都已不再支援這些表示式的使用，所以這種清理只對 IE 6 和 7 才有意義。鑑於 Angular 不支援 IE 6 或 7，並且這種清理有效能代價，因此我們將不再清理 Angular 版本 10 中的樣式繫結。

Angular used to sanitize [style] and [style.prop] bindings to prevent malicious code from being inserted through javascript: expressions in CSS url() entries. However, most modern browsers no longer support the usage of these expressions, so sanitization was only maintained for the sake of IE 6 and 7. Given that Angular does not support either IE 6 or 7 and sanitization has a performance cost, we will no longer sanitize style bindings as of version 10 of Angular.