Angular 編譯器選項

Angular 編譯器選項

使用 AoT 編譯 時，可以通過在 TypeScript 配置文件中 指定模板編譯器選項來控制如何編譯應用程序。

模板選項對象 ?angularCompilerOptions ?和為 TypeScript 編譯器提供標準選項的 ?compilerOptions ?對象是兄弟。

{
  "compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    // ...
  },
  "angularCompilerOptions": {
    "enableI18nLegacyMessageIdFormat": false,
    "strictInjectionParameters": true,
    // ...
  }
}

用 extends 語法配置繼承方式

像 TypeScript 編譯器一樣，Angular 的 AOT 編譯器也支持對 TypeScript 配置文件中的 ?angularCompilerOptions ?進行 ?extends?。?extends ?屬性位于頂層，和 ?compilerOptions ?和 ?angularCompilerOptions ?平級。

使用 ?extends ?屬性，TypeScript 配置可以從另一個文件中繼承設置。首先從基礎文件中加載配置項，然后被繼承自它的配置文件中的配置項覆寫。

比如：

{
    "extends": "./tsconfig.json",
    "compilerOptions": {
      "outDir": "./out-tsc/app",
    // ...
    "angularCompilerOptions": {
      "strictTemplates": true,
      "preserveWhitespaces": true,
      // ...
    },
  }

欲知詳情，參閱 TypeScript 手冊。

模板選項

以下選項可用于配置 AoT 模板編譯器。

allowEmptyCodegenFiles

如果為 ?true?，則生成所有可能的文件 —— 即使它們?yōu)榭?。默認值為 ?false?。Bazel 的構建規(guī)則使用它來簡化 Bazel 規(guī)則跟蹤文件依賴性的方式。不要在 Bazel 規(guī)則之外使用此選項。

annotationsAs

修改 Angular 專有注解的生成方式，以改善搖樹優(yōu)化。非 Angular 注解不受影響。可選值為 ?static fields?（默認值）或 ?decorators?。

• 默認情況下，編譯器會用類中的靜態(tài)字段替換裝飾器，這允許像 Closure 編譯器 這樣的高級搖樹器刪除未使用的類。
• ?decorators ?值會將裝飾器保留在原處，這將使編譯速度更快。TypeScript 會生成對輔助器 ?__decorate? 的調(diào)用。使用 ?--emitDecoratorMetadata? 以支持運行時反射。

注意：
這樣生成的代碼將無法被正確地搖樹優(yōu)化。

annotateForClosureCompiler

如果為 ?true?，則使用 Tsickle 來用 JSDoc 對生成的 JavaScript 代碼進行注解，這些注釋是供 Closure 編譯器 使用的。默認值為 ?false?。

compilationMode

指定要使用的編譯模式?？梢允褂靡韵履Ｊ剑?/p>

默認值為 'full'。

disableExpressionLowering

如果為 ?true?（默認值），則轉(zhuǎn)換在注解中使用或允許使用的代碼，以允許從模板的工廠模塊導入代碼。

如果為 ?false?，則禁用此重寫，你必須手動進行重寫。

disableTypeScriptVersionCheck

如果為 ?true?，則在使用不受支持的 TypeScript 版本時，編譯器不會檢查 TypeScript 版本，并且不會報錯。不建議使用，因為不受支持的 TypeScript 版本可能具有未定義的行為。默認值為 ?false?。

enableI18nLegacyMessageIdFormat

指示 Angular 模板編譯器為模板中用 ?i18n ?屬性標出的消息生成舊版 ID。

除非你的項目依賴先前已用舊版 ID 生成的翻譯，否則請將此選項設置為 ?false?。默認值為 ?true?。

Ivy 之前版本的消息提取工具為所提取的消息 id 生成了多種舊格式。這些消息格式存在許多問題，比如對空白字符的處理和對模板原始 HTML 內(nèi)部信息的依賴。

新的消息格式對空白字符的改動更寬容，在所有翻譯文件格式中都相同，并且可以直接通過調(diào)用 ?$localize? 生成。這允許應用程序代碼中的 ?$localize? 消息使用與組件模板中 ?i18n ?消息完全相同的 id。

enableResourceInlining

當為 ?true ?時，將所有 ?@Component? 裝飾器中的 ?templateUrl ?和 ?styleUrls ?屬性替換為 ?template ?和 ?styles ?屬性中的內(nèi)聯(lián)內(nèi)容。

啟用后，?ngc ?的 ?.js? 輸出不會包含任何惰性加載的模板或樣式 URL。

對于使用 CLI 生成的庫項目，dev 配置下默認為 ?true?。

enableLegacyTemplate

如果為 ?true?，則啟用 Angular 4.0 中為了避免與同名的 DOM 元素沖突而不推薦使用的 ?<template>? 元素（推薦改用 ?<ng-template>?）。默認值為 ?false?。某些第三方 Angular 庫可能需要它。

flatModuleId

用于導入扁平模塊的模塊 ID（當 ?flatModuleOutFile ?為 ?true ?時）。從扁平模塊中導入符號時，模板編譯器生成的引用將使用該模塊的名稱。如果 ?flatModuleOutFile ?為 ?false ?則忽略。

flatModuleOutFile

為 ?true ?時，將生成指定文件名和相應扁平模塊元數(shù)據(jù)的扁平模塊索引。用于創(chuàng)建像 ?@angular/core? 和 ?@angular/common? 這樣打包的扁平模塊。使用此選項時，庫的 ?package.json? 應引用生成的扁平模塊索引而不是庫的索引文件。

它只會生成一個 ?.metadata.json? 文件，該文件包含從庫索引中導出的符號所需的全部元數(shù)據(jù)。在生成的 ?.ngfactory.js? 文件中，扁平模塊索引用于導入符號，這些符號既包括庫索引中的公共 API，也包括縮進的內(nèi)部符號。

默認情況下，?files ?字段中提供的 ?.ts? 文件會被當做庫索引。如果指定了多個 ?.ts? 文件，則使用 ?libraryIndex ?選擇要使用的文件。如果提供了多個不帶 ?libraryIndex .ts? 文件，則會產(chǎn)生錯誤。

使用指定的 ?flatModuleOutFile ?名在與庫索引 ?.d.ts? 文件相同的位置創(chuàng)建扁平模塊索引 ?.d.ts? 和 ?.js?。

比如，如果一個庫使用 ?public_api.ts? 文件作為模塊的庫索引，則 ?tsconfig.json? 的 ?files ?字段就是 ?["public_api.ts"]?。然后，比如把 ?flatModuleOutFile ?選項設置為 ?"index.js"?，這將生成 ?index.d.ts? 和 ?index.metadata.json? 文件。該庫的 ?package.json? 的 ?module ?字段中就會是 ?"index.js"?，而 ?typings ?字段將是 ?"index.d.ts"?。

fullTemplateTypeCheck

為 ?true?（推薦）時，會啟用模板編譯器的綁定表達式驗證階段，該階段使用 TypeScript 來驗證綁定表達式。

默認值為 ?false?，但是當你使用 CLI 命令 ?ng new --strict? 時，默認生成的項目配置中會將其設置為 ?true?。

?fullTemplateTypeCheck ?選項已經(jīng)在 Angular 13 中棄用，改為使用 ?strictTemplates ?家族的編譯器選項。

generateCodeForLibraries

如果為 ?true?（默認值），就會為 ?.d.ts? 和相應的 ?.metadata.json? 生成工廠文件（?.ngfactory.js? 和 ?.ngstyle.js?）。

如果為 ?false?，則僅為 ?.ts? 文件生成工廠文件。當要使用工廠摘要（summary）時，請這么設置。

preserveWhitespaces

如果為 ?false?（默認值），則從編譯的模板中刪除空白文本節(jié)點，這將生成較小的模板工廠模塊。設置為 ?true ?

skipMetadataEmit

為 ?true ?時，不生成 ?.metadata.json? 文件。默認值為 ?false?。

?.metadata.json? 文件包含模板編譯器從 ?.ts? 文件中獲得的信息，該信息未包含在 TypeScript 編譯器生成的 ?.d.ts? 文件中。該信息包括注解的內(nèi)容（比如組件的模板）等，TypeScript 會將該注解的內(nèi)容發(fā)送到 ?.js? 文件中，但不會發(fā)送到 ?.d.ts? 文件。

你可以在使用工廠摘要（summary）中將其設置為 ?true?，因為工廠摘要中包括 ?.metadata.json? 文件中信息的副本。

如果要使用 TypeScript 的 ?--outFile? 選項，則設置為 ?true?，因為元數(shù)據(jù)文件對于這種 TypeScript 輸出風格無效。但是，我們不建議將 ?--outFile? 和 Angular 一起使用。請使用打包程序，比如 webpack。以保留空白文本節(jié)點。

skipTemplateCodegen

為 ?true ?時，不生成 ?.ngfactory.js? 和 ?.ngstyle.js? 文件。這將關閉大多數(shù)模板編譯器，并禁用模板診斷報告。

可用于指示模板編譯器生成 ?.metadata.json? 文件，以使用 ?npm ?軟件包進行分發(fā)，同時避免產(chǎn)生無法分發(fā)至 ?npm ?的 ?.ngfactory.js? 和 ?.ngstyle.js? 文件。

對于使用 CLI 生成的庫項目，dev 配置默認為 ?true?。

strictMetadataEmit

為 ?true ?時，如果 ?"skipMetadataEmit"? 為 ?false ?則向 ?.metadata.json? 文件中報告錯誤。默認值為 ?false?。只在 ?"skipMetadataEmit"? 為 ?false ?且 ?"skipTemplateCodegen"? 為 ?true ?時使用。

該選項是為了驗證為生成 ?npm ?包而產(chǎn)生的 ?.metadata.json? 文件。這種驗證是嚴格的，并且會報告元數(shù)據(jù)中的錯誤，以免當模板編譯器使用它時再出錯。你可以通過在某個導出符號的注釋文檔中使用 ?@dynamic? 注解來暫時防止（suppress）該選項報告錯誤。

?.metadata.json? 文件即使包含錯誤也是有效的。如果這些元數(shù)據(jù)用來確定注解的內(nèi)容，則模板編譯器會報告這些錯誤。元數(shù)據(jù)收集器無法預測哪些符號是為了在注解中使用而設計，因此它會先在元數(shù)據(jù)中為導出的符號中包含錯誤節(jié)點。然后，如果使用了這些符號，則模板編譯器可以使用這些錯誤節(jié)點來報告錯誤。

如果庫的客戶代碼打算在注解中使用某個符號，則模板編譯器通常不會在客戶方用到該符號之前就報錯。此選項允許你在庫的構建階段就檢測到這些錯誤，比如用于生成 Angular 庫本身時。

對于使用 CLI 生成的庫項目，dev 配置中默認為 ?true?。

strictInjectionParameters

如果為 ?true?（推薦），則報告所提供的參數(shù)的錯誤，無法確定該參數(shù)的注入類型。如果為 ?false?（當前為默認值），則標記為 ?@Injectable? 但其類型無法解析的類的構造函數(shù)參數(shù)會產(chǎn)生警告。

當你使用 CLI 命令 ?ng new --strict? 時，默認生成的項目配置中將其設置為 ?true?。

strictTemplates

如果為 ?true?，則啟用嚴格的模板類型檢查。

其它嚴格性標志允許你啟用和禁用特定類型的嚴格模板類型檢查。

當你使用 CLI 命令 ?ng new --strict? 時，默認生成的項目配置中將其設置為 ?true?。

trace

如果為 ?true?，則在編譯模板時輸出額外的信息。默認值為 ?false?。

命令行選項

雖然大多數(shù)時候你都會使用 Angular CLI 間接與 Angular 編譯器交互，但在調(diào)試某些問題時，你可能會發(fā)現(xiàn)直接調(diào)用 Angular 編譯器很有用。你可以使用 ?@angular/compiler-cli? npm 包提供的 ?ngc ?命令從命令行調(diào)用編譯器。

?ngc ?命令只是 TypeScript 的 ?tsc ?編譯器命令的包裝器，主要通過前面部分講過的 ?tsconfig.json? 配置選項進行配置。

除了配置文件，你還可以使用一些 tsc命令行選項來配置 ?ngc?。