填寫這份《一分鐘調查》,幫我們(開發組)做得更好!去填寫Home

Angular 編譯器選項

Angular compiler options

使用 AoT 編譯 時,可以透過在 TypeScript 配置檔案中指定範本編譯器選項來控制如何編譯應用程式。

When you use AOT compilation, you can control how your application is compiled by specifying template compiler options in the TypeScript configuration file.

範本選項物件 angularCompilerOptions 和為 TypeScript 編譯器提供標準選項的 compilerOptions 物件是兄弟。

The template options object, angularCompilerOptions, is a sibling to the compilerOptions object that supplies standard options to the TypeScript compiler.

{ "compilerOptions": { "experimentalDecorators": true, ... }, "angularCompilerOptions": { "fullTemplateTypeCheck": true, "preserveWhitespaces": true, ... } }
      
      {
    "compilerOptions": {
      "experimentalDecorators": true,
                ...
    },
    "angularCompilerOptions": {
      "fullTemplateTypeCheck": true,
      "preserveWhitespaces": true,
                ...
    }
}
    

extends 語法配置繼承方式

Configuration inheritance with extends

像 TypeScript 編譯器一樣,Angular 的 AOT 編譯器也支援對 TypeScript 配置檔案中的 angularCompilerOptions 進行 extendsextends 屬性位於最上層,和 compilerOptionsangularCompilerOptions 平級。

Like the TypeScript compiler, The Angular AOT compiler also supports extends in the angularCompilerOptions section of the TypeScript configuration file. The extends property is at the top level, parallel to compilerOptions and angularCompilerOptions.

使用 extends 屬性,TypeScript 配置可以從另一個檔案中繼承設定。首先從基礎檔案中載入配置項,然後被繼承自它的配置檔案中的配置項覆寫。

A TypeScript configuration can inherit settings from another file using the extends property. The configuration options from the base file are loaded first, then overridden by those in the inheriting configuration file.

比如:

For example:

{ "extends": "../tsconfig.json", "compilerOptions": { "experimentalDecorators": true, ... }, "angularCompilerOptions": { "fullTemplateTypeCheck": true, "preserveWhitespaces": true, ... } }
      
      {
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "experimentalDecorators": true,
    ...
  },
  "angularCompilerOptions": {
    "fullTemplateTypeCheck": true,
    "preserveWhitespaces": true,
    ...
  }
}
    

欲知詳情,請參閱 TypeScript 手冊

For more information, see the TypeScript Handbook.

範本選項

Template options

以下選項可用於配置 AoT 範本編譯器。

The following options are available for configuring the AOT template compiler.

allowEmptyCodegenFiles

如果為 true,則產生所有可能的檔案 —— 即使它們為空。預設值為 false。Bazel 的建構規則使用它來簡化 Bazel 規則追蹤檔案依賴性的方式。不要在 Bazel 規則之外使用此選項。

When true, generate all possible files even if they are empty. Default is false. Used by the Bazel build rules to simplify how Bazel rules track file dependencies. Do not use this option outside of the Bazel rules.

annotationsAs

修改 Angular 專有註解的產生方式,以改善搖樹優化。非 Angular 註解不受影響。可選值為 static fields(預設值)或 decorators

Modifies how Angular-specific annotations are emitted to improve tree-shaking. Non-Angular annotations are not affected. One of static fields (the default) or decorators.

  • 預設情況下,編譯器會用類別中的靜態欄位替換裝飾器,這允許像 Closure 編譯器這樣的高階搖樹器刪除未使用的類別。

    By default, the compiler replaces decorators with a static field in the class, which allows advanced tree-shakers like Closure compiler to remove unused classes.

  • decorators 值會將裝飾器保留在原處,這將使編譯速度更快。TypeScript 會發出對 __decorate 輔助程式的呼叫。使用 --emitDecoratorMetadata 進行執行時反射(但請注意,產生的程式碼將無法正確搖樹)。

    The decorators value leaves the decorators in place, which makes compilation faster. TypeScript emits calls to the__decorate helper. Use --emitDecoratorMetadata for runtime reflection (but note that the resulting code will not properly tree-shake.

annotateForClosureCompiler

如果為 true,則使用 Tsickle 來用 JSDoc 對產生的 JavaScript 程式碼進行註解,這些註釋是供 Closure 編譯器 使用的。預設值為 false

When true, use Tsickle to annotate the emitted JavaScript with JSDoc comments needed by the Closure Compiler. Default is false.

disableExpressionLowering

如果為 true(預設值),則轉換在註解中使用或允許使用的程式碼,以允許從範本的工廠模組匯入程式碼。欲知詳情,請參閱元資料重寫

When true (the default), transforms code that is or could be used in an annotation, to allow it to be imported from template factory modules. See metadata rewriting for more information.

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

When false, disables this rewriting, requiring the rewriting to be done manually.

disableTypeScriptVersionCheck

如果為 true,則在使用不受支援的 TypeScript 版本時,編譯器不會檢查 TypeScript 版本,並且不會報錯。不建議使用,因為不受支援的 TypeScript 版本可能具有未定義的行為。預設值為 false

When true, the compiler does not check the TypeScript version and does not report an error when an unsupported version of TypeScript is used. Not recommended, as unsupported versions of TypeScript might have undefined behavior. Default is false.

enableI18nLegacyMessageIdFormat

指示 Angular 範本編譯器為範本中用 i18n 屬性標出的訊息產生舊版 ID。關於為本地化而對訊息進行標記的更多資訊,請參閱本地化你的應用程式。

Instructs the Angular template compiler to generate legacy ids for messages that are tagged in templates by the i18n attribute. See Localizing your app for more information about marking messages for localization.

除非你的專案依賴先前已用舊版 ID 產生的翻譯,否則請將此選項設定為 false。預設值為 true

Set this option to false unless your project relies upon translations that were previously generated using legacy ids. Default is true.

Ivy 之前版本的訊息提取工具為所提取的訊息 id 生成了多種舊格式。這些訊息格式存在許多問題,例如對空白字元的處理和對範本原始 HTML 內部資訊的依賴。

The pre-Ivy message extraction tooling generated a variety of legacy formats for extracted message ids. These message formats have a number of issues, such as whitespace handling and reliance upon information inside the original HTML of a template.

新的訊息格式對空白字元的改動更寬容,在所有翻譯檔案格式中都相同,並且可以直接透過呼叫 $localize 產生。這允許應用程式程式碼中的 $localize 訊息使用與元件範本中 i18n 訊息完全相同的 id。

The new message format is more resilient to whitespace changes, is the same across all translation file formats, and can be generated directly from calls to $localize. This allows $localize messages in application code to use the same id as identical i18n messages in component templates.

enableIvy

啟用 Ivy 編譯和渲染管道。從版本 9 開始,預設值為 true。在版本 9 中,你可以選擇不用 Ivy 而是繼續使用以前的編譯器 View Engine。

Enables the Ivy compilation and rendering pipeline. Default is true, as of version 9. In version 9, you can opt out of Ivy to continue using the previous compiler, View Engine.

對於使用 CLI 產生的函式庫專案,prod 配置預設在版本 9 中為 false

For library projects generated with the CLI, the prod configuration default is false in version 9.

enableResourceInlining

當為 true 時,將所有 @Component 裝飾器中的 templateUrlstyleUrls 屬性替換為 templatestyles 屬性中的內聯內容。

When true, replaces the templateUrl and styleUrls property in all @Component decorators with inlined contents in template and styles properties.

啟用後,ngc.js 輸出不會包含任何延遲載入的範本或樣式 URL。

When enabled, the .js output of ngc does not include any lazy-loaded template or style URLs.

對於使用 CLI 產生的函式庫專案,dev 配置下預設為 true

For library projects generated with the CLI, the dev configuration default is true.

enableLegacyTemplate

如果為 true,則啟用 Angular 4.0 中為了避免與同名的 DOM 元素衝突而不推薦使用的 <template> 元素(推薦改用 <ng-template>)。預設值為 false。某些第三方 Angular 函式庫可能需要它。

When true, enables use of the <template> element, which was deprecated in Angular 4.0, in favor of <ng-template> (to avoid colliding with the DOM's element of the same name). Default is false. Might be required by some third-party Angular libraries.

flatModuleId

用於匯入扁平模組的模組 ID(當 flatModuleOutFiletrue 時)。從扁平模組中匯入符號時,範本編譯器產生的參考將使用該模組的名稱。如果 flatModuleOutFilefalse 則忽略。

The module ID to use for importing a flat module (when flatModuleOutFile is true). References generated by the template compiler use this module name when importing symbols from the flat module. Ignored if flatModuleOutFile is false.

flatModuleOutFile

true 時,將產生指定檔名和相應扁平模組元資料的扁平模組索引。用於建立像 @angular/core@angular/common 這樣打套件的扁平模組。使用此選項時,函式庫的 package.json 應參考產生的扁平模組索引而不是函式庫的索引檔案。

When true, generates a flat module index of the given file name and the corresponding flat module metadata. Use to create flat modules that are packaged similarly to @angular/core and @angular/common. When this option is used, the package.json for the library should refer to the generated flat module index instead of the library index file.

它只會產生一個 .metadata.json 檔案,該檔案包含從函式庫索引中匯出的符號所需的全部元資料。在產生的 .ngfactory.js 檔案中,扁平模組索引用於匯入符號,這些符號既包括函式庫索引中的公共 API,也包括縮排的內部符號。

Produces only one .metadata.json file, which contains all the metadata necessary for symbols exported from the library index. In the generated .ngfactory.js files, the flat module index is used to import symbols that includes both the public API from the library index as well as shrowded internal symbols.

預設情況下,files 欄位中提供的 .ts 檔案會被當做函式庫索引。如果指定了多個 .ts 檔案,則使用 libraryIndex 選擇要使用的檔案。如果提供了多個不帶 libraryIndex .ts 檔案,則會產生錯誤。

By default the .ts file supplied in the files field is assumed to be the library index. If more than one .ts file is specified, libraryIndex is used to select the file to use. If more than one .ts file is supplied without a libraryIndex, an error is produced.

使用指定的 flatModuleOutFile 名在與函式庫索引 .d.ts 檔案相同的位置建立扁平模組索引 .d.ts.js

A flat module index .d.ts and .js is created with the given flatModuleOutFile name in the same location as the library index .d.ts file.

例如,如果一個函式庫使用 public_api.ts 檔案作為模組的函式庫索引,則 tsconfig.jsonfiles 欄位就是 ["public_api.ts"]。然後,比如把 flatModuleOutFile 選項設定為 "index.js",這將產生 index.d.tsindex.metadata.json 檔案。該函式庫的 package.jsonmodule 欄位中就會是 "index.js",而 typings 欄位將是 "index.d.ts"

For example, if a library uses the public_api.ts file as the library index of the module, the tsconfig.json files field would be ["public_api.ts"]. The flatModuleOutFile option could then be set to (for example) "index.js", which produces index.d.ts and index.metadata.json files. The module field of the library's package.json would be "index.js" and the typings field would be "index.d.ts".

fullTemplateTypeCheck

true(推薦)時,會啟用範本編譯器的繫結表示式驗證階段,該階段使用 TypeScript 來驗證繫結表示式。欲知詳情,請參閱範本型別檢查

When true (recommended), enables the binding expression validation phase of the template compiler, which uses TypeScript to validate binding expressions. For more information, see Template type checking.

預設值為 false,但是當你使用 CLI 命令 ng new 時,預設產生的專案配置中會將其設定為 true

Default is false, but when you use the CLI command ng new, it is set to true by default in the generated project's configuration.

generateCodeForLibraries

如果為 true(預設值),就會為 .d.ts 和相應的 .metadata.json 產生工廠檔案(.ngfactory.js.ngstyle.js)。

When true (the default), generates factory files (.ngfactory.js and .ngstyle.js) for .d.ts files with a corresponding .metadata.json file.

如果為 false,則僅為 .ts 檔案產生工廠檔案。當要使用工廠摘要(summary)時,請這麼設定。

When false, factory files are generated only for .ts files. Do this when using factory summaries.

preserveWhitespaces

如果為 false(預設值),則從編譯的範本中刪除空白文字節點,這將產生較小的範本工廠模組。設定為 true 以保留空白文字節點。

When false (the default), removes blank text nodes from compiled templates, which results in smaller emitted template factory modules. Set to true to preserve blank text nodes.

skipMetadataEmit

true 時,不產生 .metadata.json 檔案。預設值為 false

When true, does not produce .metadata.json files. Default is false.

.metadata.json 檔案包含範本編譯器從 .ts 檔案中獲得的資訊,該資訊未包含在 TypeScript 編譯器產生的 .d.ts 檔案中。該資訊包括註解的內容(例如元件的範本)等,TypeScript 會將該註解的內容傳送到 .js 檔案中,但不會發送到 .d.ts 檔案。

The .metadata.json files contain information needed by the template compiler from a .ts file that is not included in the .d.ts file produced by the TypeScript compiler. This information includes, for example, the content of annotations (such as a component's template), which TypeScript emits to the .js file but not to the .d.ts file.

你可以在使用工廠摘要(summary)中將其設定為 true,因為工廠摘要中包括 .metadata.json 檔案中資訊的副本。

You can set to true when using factory summaries, because the factory summaries include a copy of the information that is in the .metadata.json file.

如果要使用 TypeScript 的 --outFile 選項,則設定為 true,因為元資料檔案對於這種 TypeScript 輸出風格無效。但是,我們不建議將 --outFile 和 Angular 一起使用。請使用打包程式,例如 webpack

Set to true if you are using TypeScript's --outFile option, because the metadata files are not valid for this style of TypeScript output. However, we do not recommend using --outFile with Angular. Use a bundler, such as webpack, instead.

skipTemplateCodegen

true 時,不產生 .ngfactory.js.ngstyle.js 檔案。這將關閉大多數範本編譯器,並禁用範本診斷報告。

When true, does not emit .ngfactory.js and .ngstyle.js files. This turns off most of the template compiler and disables the reporting of template diagnostics.

可用於指示範本編譯器產生 .metadata.json 檔案,以使用 npm 軟體套件進行分發,同時避免產生無法分發至 npm.ngfactory.js.ngstyle.js 檔案。

Can be used to instruct the template compiler to produce .metadata.json files for distribution with an npm package while avoiding the production of .ngfactory.js and .ngstyle.js files that cannot be distributed to npm.

對於使用 CLI 產生的函式庫專案,dev 配置預設為 true

For library projects generated with the CLI, the dev configuration default is true.

strictMetadataEmit

true 時,如果 "skipMetadataEmit"false 則向 .metadata.json 檔案中報告錯誤。預設值為 false。只在 "skipMetadataEmit"false"skipTemplateCodeGen"true 時使用。

When true, reports an error to the .metadata.json file if "skipMetadataEmit" is false. Default is false. Use only when "skipMetadataEmit" is false and "skipTemplateCodeGen" is true.

該選項是為了驗證為產生 npm 套件而產生的 .metadata.json 檔案。這種驗證是嚴格的,並且會報告元資料中的錯誤,以免當範本編譯器使用它時再出錯。你可以透過在某個匯出符號的註釋文件中使用 @dynamic 註解來暫時防止(suppress)該選項報告錯誤。

This option is intended to validate the .metadata.json files emitted for bundling with an npm package. The validation is strict and can emit errors for metadata that would never produce an error when used by the template compiler. You can choose to suppress the error emitted by this option for an exported symbol by including @dynamic in the comment documenting the symbol.

.metadata.json 檔案即使包含錯誤也是有效的。如果這些元資料用來確定註解的內容,則範本編譯器會報告這些錯誤。元資料收集器無法預測哪些符號是為了在註解中使用而設計,因此它會先在元資料中為匯出的符號中包含錯誤節點。然後,如果使用了這些符號,則範本編譯器可以使用這些錯誤節點來報告錯誤。

It is valid for .metadata.json files to contain errors. The template compiler reports these errors if the metadata is used to determine the contents of an annotation. The metadata collector cannot predict the symbols that are designed for use in an annotation, so it preemptively includes error nodes in the metadata for the exported symbols. The template compiler can then use the error nodes to report an error if these symbols are used.

如果函式庫的客戶程式碼打算在註解中使用某個符號,則範本編譯器通常不會在客戶方用到該符號之前就報錯。此選項允許你在函式庫的建構階段就檢測到這些錯誤,例如用於產生 Angular 函式庫本身時。

If the client of a library intends to use a symbol in an annotation, the template compiler does not normally report this until the client uses the symbol. This option allows detection of these errors during the build phase of the library and is used, for example, in producing Angular libraries themselves.

對於使用 CLI 產生的函式庫專案,dev 配置中預設為 true

For library projects generated with the CLI, the dev configuration default is true.

strictInjectionParameters

如果為 true(推薦),則報告所提供的引數的錯誤,無法確定該引數的注入型別。如果為 false(當前為預設值),則標記為 @Injectable 但其型別無法解析的類別的建構函式引數會產生警告。

When true (recommended), reports an error for a supplied parameter whose injection type cannot be determined. When false (currently the default), constructor parameters of classes marked with @Injectable whose type cannot be resolved produce a warning.

當你使用 CLI 命令 ng new 時,預設產生的專案配置中將其設定為 true

When you use the CLI command ng new --strict, it is set to true in the generated project's configuration.

strictTemplates

如果為 true,則在 Angular 9 中啟用嚴格的範本型別檢查。僅當使用 Ivy 時,才能使用嚴格模式。

When true, enables strict template type checking. Strict mode is only available when using Ivy (Angular version 9 and later).

其它嚴格性標誌允許你啟用和禁用特定型別的嚴格範本型別檢查。請參閱排除範本錯誤

Additional strictness flags allow you to enable and disable specific types of strict template type checking. See troubleshooting template errors.

當你使用 CLI 命令 ng new --strict 時,預設產生的專案配置中將其設定為 true

When you use the CLI command ng new --strict, it is set to true in the generated project's configuration.

trace

如果為 true,則在編譯範本時輸出額外的資訊。預設值為 false

When true, prints extra information while compiling templates. Default is false.