Angular 編譯器選項(xiàng)

Angular 編譯器選項(xiàng)

使用 AoT 編譯 時(shí)，可以通過在 TypeScript 配置文件中 指定模板編譯器選項(xiàng)來控制如何編譯應(yīng)用程序。

模板選項(xiàng)對(duì)象 ?angularCompilerOptions ?和為 TypeScript 編譯器提供標(biāo)準(zhǔn)選項(xiàng)的 ?compilerOptions ?對(duì)象是兄弟。

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

用 extends 語法配置繼承方式

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

使用 ?extends ?屬性，TypeScript 配置可以從另一個(gè)文件中繼承設(shè)置。首先從基礎(chǔ)文件中加載配置項(xiàng)，然后被繼承自它的配置文件中的配置項(xiàng)覆寫。

比如：

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

欲知詳情，參閱 TypeScript 手冊(cè)。

模板選項(xiàng)

以下選項(xiàng)可用于配置 AoT 模板編譯器。

allowEmptyCodegenFiles

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

annotationsAs

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

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

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

annotateForClosureCompiler

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

compilationMode

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

默認(rèn)值為 'full'。

disableExpressionLowering

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

如果為 ?false?，則禁用此重寫，你必須手動(dòng)進(jìn)行重寫。

disableTypeScriptVersionCheck

如果為 ?true?，則在使用不受支持的 TypeScript 版本時(shí)，編譯器不會(huì)檢查 TypeScript 版本，并且不會(huì)報(bào)錯(cuò)。不建議使用，因?yàn)椴皇苤С值?nbsp;TypeScript 版本可能具有未定義的行為。默認(rèn)值為 ?false?。

enableI18nLegacyMessageIdFormat

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

除非你的項(xiàng)目依賴先前已用舊版 ID 生成的翻譯，否則請(qǐng)將此選項(xiàng)設(shè)置為 ?false?。默認(rèn)值為 ?true?。

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

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

enableResourceInlining

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

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

對(duì)于使用 CLI 生成的庫項(xiàng)目，dev 配置下默認(rèn)為 ?true?。

enableLegacyTemplate

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

flatModuleId

用于導(dǎo)入扁平模塊的模塊 ID（當(dāng) ?flatModuleOutFile ?為 ?true ?時(shí)）。從扁平模塊中導(dǎo)入符號(hào)時(shí)，模板編譯器生成的引用將使用該模塊的名稱。如果 ?flatModuleOutFile ?為 ?false ?則忽略。

flatModuleOutFile

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

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

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

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

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

fullTemplateTypeCheck

為 ?true?（推薦）時(shí)，會(huì)啟用模板編譯器的綁定表達(dá)式驗(yàn)證階段，該階段使用 TypeScript 來驗(yàn)證綁定表達(dá)式。

默認(rèn)值為 ?false?，但是當(dāng)你使用 CLI 命令 ?ng new --strict? 時(shí)，默認(rèn)生成的項(xiàng)目配置中會(huì)將其設(shè)置為 ?true?。

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

generateCodeForLibraries

如果為 ?true?（默認(rèn)值），就會(huì)為 ?.d.ts? 和相應(yīng)的 ?.metadata.json? 生成工廠文件（?.ngfactory.js? 和 ?.ngstyle.js?）。

如果為 ?false?，則僅為 ?.ts? 文件生成工廠文件。當(dāng)要使用工廠摘要（summary）時(shí)，請(qǐng)這么設(shè)置。

preserveWhitespaces

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

skipMetadataEmit

為 ?true ?時(shí)，不生成 ?.metadata.json? 文件。默認(rèn)值為 ?false?。

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

你可以在使用工廠摘要（summary）中將其設(shè)置為 ?true?，因?yàn)楣S摘要中包括 ?.metadata.json? 文件中信息的副本。

如果要使用 TypeScript 的 ?--outFile? 選項(xiàng)，則設(shè)置為 ?true?，因?yàn)樵獢?shù)據(jù)文件對(duì)于這種 TypeScript 輸出風(fēng)格無效。但是，我們不建議將 ?--outFile? 和 Angular 一起使用。請(qǐng)使用打包程序，比如 webpack。以保留空白文本節(jié)點(diǎn)。

skipTemplateCodegen

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

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

對(duì)于使用 CLI 生成的庫項(xiàng)目，dev 配置默認(rèn)為 ?true?。

strictMetadataEmit

為 ?true ?時(shí)，如果 ?"skipMetadataEmit"? 為 ?false ?則向 ?.metadata.json? 文件中報(bào)告錯(cuò)誤。默認(rèn)值為 ?false?。只在 ?"skipMetadataEmit"? 為 ?false ?且 ?"skipTemplateCodegen"? 為 ?true ?時(shí)使用。

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

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

如果庫的客戶代碼打算在注解中使用某個(gè)符號(hào)，則模板編譯器通常不會(huì)在客戶方用到該符號(hào)之前就報(bào)錯(cuò)。此選項(xiàng)允許你在庫的構(gòu)建階段就檢測(cè)到這些錯(cuò)誤，比如用于生成 Angular 庫本身時(shí)。

對(duì)于使用 CLI 生成的庫項(xiàng)目，dev 配置中默認(rèn)為 ?true?。

strictInjectionParameters

如果為 ?true?（推薦），則報(bào)告所提供的參數(shù)的錯(cuò)誤，無法確定該參數(shù)的注入類型。如果為 ?false?（當(dāng)前為默認(rèn)值），則標(biāo)記為 ?@Injectable? 但其類型無法解析的類的構(gòu)造函數(shù)參數(shù)會(huì)產(chǎn)生警告。

當(dāng)你使用 CLI 命令 ?ng new --strict? 時(shí)，默認(rèn)生成的項(xiàng)目配置中將其設(shè)置為 ?true?。

strictTemplates

如果為 ?true?，則啟用嚴(yán)格的模板類型檢查。

其它嚴(yán)格性標(biāo)志允許你啟用和禁用特定類型的嚴(yán)格模板類型檢查。

當(dāng)你使用 CLI 命令 ?ng new --strict? 時(shí)，默認(rèn)生成的項(xiàng)目配置中將其設(shè)置為 ?true?。

trace

如果為 ?true?，則在編譯模板時(shí)輸出額外的信息。默認(rèn)值為 ?false?。

命令行選項(xiàng)

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

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

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