升級 Angular

Updating Angular

本指南包含有關升級到 Angular v12 的資訊。

This guide contains information related to updating to Angular version 12.

升級 CLI 應用

Updating CLI applications

有關如何升級到最新的 Angular 版本以及如何利用我們的自動遷移工具進行升級的分步說明,請使用 update.angular.io 上的互動式升級指南。

For step-by-step instructions on how to update to the latest Angular release and leverage our automated migration tools to do so, use the interactive update guide at update.angular.io.

使用 Ivy 建構應用

Building applications with Ivy

對於函式庫,View Engine 已被棄用,並將在版本 13 中刪除。使用版本 12 或更高版本建立的新函式庫預設為 Ivy。有關使用 View Engine 和 Ivy 分發函式庫的更多資訊,參見 建立函式庫中的使用 Ivy 建構函式庫部分。

For libraries, View Engine is deprecated and will be removed in version 13. New libraries created with version 12 or later default to Ivy. For more information about distributing libraries with View Engine and Ivy, see the Building libraries with Ivy section of Creating libraries.

版本 12 中的更改和棄用

Changes and deprecations in version 12

有關 Angular 棄用和刪除實踐的資訊,請參閱 Angular 發佈實踐

For information about Angular's deprecation and removal practices, see Angular Release Practices.

  • 設定 enableIvy: false 可以讓應用不再使用 View Engine 進行建構。為了向後相容,我們不再支援使用 View Engine 建構函式庫,並且在 Angular 13 版中將不再支援。使用 Angular 12 版建立的新函式庫將預設為使用 Ivy 來建構和分發。有關更多資訊,請參見建立函式庫

    Applications can no longer build with View Engine by setting enableIvy: false. Support for building libraries with View Engine, for backwards compatibility, is deprecated and will be removed in Angular version 13. New libraries created with Angular version 12 will default to building and distributing with Ivy. For more information, see Creating Libraries.

  • 預設情況下,基於 Ivy 的 IDE 語言服務處於開啟狀態。參見 PR#1279

    The Ivy-based IDE language service is now on by default. See PR #1279.

  • Angular 的基於 View Engine 的 i18n 訊息 ID 演算法已經棄用。Angular 12 版添加了一個名為 --migrateMapFilelocalize-extract 標誌,該標誌會產生一個 JSON 檔案,該檔案可用於將舊訊息 ID 對映為規範化的訊息 ID。還有一個名為 localize-migrate 的新指令碼,可以使用此對映檔案進行 localize-extract,來產生並遷移傳入的檔案中的所有 ID。為了獲得更高的穩定性,如果你使用的是 Angular 的 i18n 命令,請執行該遷移,以便使用新的訊息 ID 產生演算法。如果不執行此遷移,則當 Angular 最終刪除 View Engine 編譯器時,所有產生的訊息 ID 都會發生改變。參見 PR#41026

    Angular's View Engine-based algorithm for generating i18n message IDs is deprecated. Angular version 12 adds a new flag to localize-extract called --migrateMapFile which generates a JSON file that can be used to map legacy message IDs to canonical ones. There is also a new script called localize-migrate that can use the mapping file which localize-extract generates and migrate all of the IDs in the files that are passed in. For better stability, if you are using Angular's i18n, run this migration to move to the new message ID generation algorithm. If you don't run this migration, all your generated message IDs will change when Angular removes the View Engine compiler. See PR #41026.

  • 現在有了一個新的建構選項 inlineStyleLanguage,用來以內聯元件樣式的形式定義樣式表。當前支援的語言選項是 CSS(預設)、Sass、SCSS 和 LESS。 CSS 的預設設定使現有專案能夠繼續按預期般執行。參見 PR#20514

    There is now a new build option named inlineStyleLanguage for defining the style sheet language in inline component styles. Currently supported language options are CSS (default), Sass, SCSS, and LESS. The default of CSS enables existing projects to continue to function as expected. See PR #20514.

  • 在新建應用時,嚴格模式現在是 CLI 中的預設模式。參見 PR#20029

    For new applications, strict mode is now the default in the CLI. See PR #20029.

  • AbstractControl 類別方法添加了 emitEvent 選項。參見 PR#31031

    Add emitEvent option for AbstractControl class methods. See PR #31031.

  • 支援將 APP_INITIALIZER 與可觀察物件一起使用。參見 PR#31031

    Support APP_INITIALIZER to work with observables. See PR #31031.

  • HttpClient 支援指定請求的元資料。參見 PR#25751

    HttpClient supports specifying request metadata. See PR #25751.

Angular 12 版中的重大更改

Breaking changes in Angular version 12

  • 新增對 TypeScript 4.2 的支援。不再支援 TypeScript <4.2.3。 TypeScript 版本支援的範圍是 4.2.3 到 4.2.x。參見 PR#41158

    Add support for TypeScript 4.2. TypeScript <4.2.3 is no longer supported. The supported range of TypeScript versions is 4.2.3 to 4.2.x. See PR #41158.

  • Angular CDK 和 Angular Material 的內部現在使用新的 Sass 模組系統,該系統正由 Google 的 Sass 團隊積極維護。因此,應用無法再透過 node-sass npm 軟體套件 使用 Angular CDK / Material 的 Sass。node-sass 已停止維護,並且不支援新的 Sass 功能。相反,應用必須使用 sass npm 軟體套件sass-embedded beta sass-embedded npm 軟體套件

    Angular CDK and Angular Material internally now use the new Sass module system, which is actively maintained by the Sass team at Google. Consequently, applications can no longer consume Angular CDK/Material's Sass with the node-sass npm package. node-sass is unmaintained and does not support newer Sass features. Instead, applications must use the sass npm package, or the sass-embedded npm package for the sass-embedded beta.

  • Angular 工具現在使用 Webpack 5 來建構應用。 Webpack 4 的用法和支援已被刪除。使用正式的 Angular 建構器時,無需進行任何專案級別的配置更改即可使用升級後的 Webpack 版本。基於此程式套件的使用實驗性程式設計 API 的自訂建構器可能需要升級,以便與 Webpack 5 相容。參見 PR#20466

    The Angular tooling now uses Webpack 5 to build applications. Webpack 4 usage and support has been removed. You don't need to make any project level configuration changes to use the upgraded Webpack version when using the official Angular builders. Custom builders based on this package that use the experimental programmatic APIs may need to be updated to become compatible with Webpack 5. See PR #20466.

  • 當啟用了 namedChunks 時,Webpack 5 會為開發配置中延遲載入的 JavaScript 檔案產生相似但不同名的檔案。對於大多數使用者而言,此更改不會對應用或建構過程產生影響。生產版本也不會受到影響,因為在生產配置中預設啟用了 namedChunks。 但是,如果專案的建構後過程對檔名進行了某些假設,則可能需要進行調整以考慮新的命名規範。這類別建構後過程可能包括建構後的自訂檔案轉換、整合到伺服器端框架或部署過程中。開發檔名更改的一個例子是 lazy-lazy-module.js 變為 src_app_lazy_lazy_module_ts.js。參見 PR#20466

    Webpack 5 generates similar but differently named files for lazy-loaded JavaScript files in development configurations when the namedChunks option is enabled. For the majority of users this change should have no effect on the application or build process. Production builds should also not be affected as the namedChunks option is disabled by default in production configurations. However, if a project's post-build process makes assumptions as to the file names, then adjustments may need to be made to account for the new naming paradigm. Such post-build processes could include custom file transformations after the build, integration into service-side frameworks, or deployment procedures. An example of a development file name change is lazy-lazy-module.js becoming src_app_lazy_lazy_module_ts.js. See PR #20466.

  • Webpack 5 現在包括對 Web Worker 的支援。但是,Web Worker 建構函式中 URL 的結構必須採用不同於當前要求的特定格式。要修改 Web Worker 的用法,其中 ./app.worker 是實際的 worker 名稱, new Worker('./app.worker', ...) 要改為 new Worker(new URL('./app.worker', import.meta.url), ...)。參見 PR#20466

    Webpack 5 now includes web worker support. However, the structure of the URL within the worker constructor must be in a specific format that differs from the current requirement. To update web worker usage, where ./app.worker is the actual worker name, change new Worker('./app.worker', ...) to new Worker(new URL('./app.worker', import.meta.url), ...). See PR #20466.

  • 現在,預設情況下已啟用關鍵 CSS 內聯。要關閉此功能,請將 inlineCritical 設定為 false。參見 PR#20096Angular 工作空間配置中的的樣式預處理程式選項部分。

    Critical CSS inlining is now enabled by default. To turn this off, set inlineCritical to false. See PR #20096 and the Style preprocessor options section of Angular workspace configuration.

  • ng build 現在預設情況下會產生針對生產環境的捆綁套件。參見 PR#20128

    ng build now produces production bundle by default. See PR #20128.

  • 以前,Forms 模組會忽略 <input type="number"> 上定義的 minmax 屬性。現在,formControl ,formControlName 或 ngModel 指令都提供了對應的輸入屬性,這些屬性將觸發 minmax 驗證邏輯。參見 PR#39063

    Previously, the Forms module ignored min and max attributes defined on the <input type="number">. Now these attributes trigger min and max validation logic in cases where formControl, formControlName, or ngModel directives are also present on a given input. See PR #39063.


New deprecations

  • 不建議再使用 Internet Explorer 11。參見已棄用的 API 和功能Microsoft 365 應用將告別 Internet Explorer 11 並且 Windows 10 將放棄 Microsoft Edge Legacy

    Support for Internet Explorer 11 is deprecated. See Deprecated APIs and features and Microsoft 365 apps say farewell to Internet Explorer 11 and Windows 10 sunsets Microsoft Edge Legacy.

  • 不建議再從 @angular/material/theming 中匯入 Sass。請改用基於 @use 的新的 Angular Material Sass API。執行遷移指令碼 ng g @angular/material:themingApi 將 Angular CDK 和 Angular Material 的所有 Sass 匯入都切換到新的 API 和 @use

    Sass imports from @angular/material/theming are deprecated. There is a new Angular Material Sass API for @use. Run the migration script ng g @angular/material:themingApi to switch all your Sass imports for Angular CDK and Angular Material to the new API and @use.

  • 不建議再使用 View Engine 發佈函式庫:

    Support for publishing libraries with View Engine has been deprecated:

    • 現在,你可以在部分編譯模式下編譯函式庫,以產生與 Ivy 相容的輸出,當使用該函式庫的應用被打套件時,這些輸出將被連結進去。

      You can now compile libraries in partial compilation mode to generate Ivy compatible output that will be linked when an application using that library is bundled.

    • 使用 Angular CLI 建立的新函式庫預設為部分編譯模式,並且不支援 View Engine。你仍然可以使用 View Engine 建構函式庫。有關更多資訊,參見建立函式庫

      New libraries you create with the Angular CLI default to partial compilation mode, and do not support View Engine. You can still build a library with View Engine. See Creating libraries for more information.

    • 在部分編譯模式下編譯的函式庫將不再包含舊版 i18n 訊息 ID。如果該函式庫以前是由 View Engine 編譯的,並且包含舊版 i18n 訊息 ID,則應用可能已經有翻譯檔案,你需要將其遷移成新的訊息 ID 格式。有關更多資訊,參見 遷移舊版本地化 ID

      Libraries compiled in partial compilation mode will not contain legacy i18n message IDs. If the library was previously compiled by View Engine, and contained legacy i18n message IDs, then applications may have translation files that you'll need to migrate to the new message ID format. For more information, see Migrating legacy localization IDs.

    • 有關上下文,請參見問題#38366

      For context, see Issue #38366.

從版本 9 開始,Angular Ivy 是預設渲染引擎。有關 Ivy 的更多資訊,請參見 Angular Ivy

Since version 9, Angular Ivy is the default rendering engine. For more information about Ivy, see Angular Ivy.