港服(Server.HK)Angular教程：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，则生成所有可能的文件 —— 即使它们为空。默认值为 false。Bazel 的构建规则使用它来简化 Bazel 规则跟踪文件依赖性的方式。不要在 Bazel 规则之外使用此选项。

annotationsAs

修改 Angular 专有注解的生成方式，以改善摇树优化。非 Angular 注解不受影响。可选值为 static fields（默认值）或 decorators。

默认情况下，编译器会用类中的静态字段替换装饰器，这允许像 Closure 编译器这样的高级摇树器删除未使用的类。
decorators 值会将装饰器保留在原处，这将使编译速度更快。TypeScript 会生成对辅助器 __decorate 的调用。使用 --emitDecoratorMetadata 以支持运行时反射。

注意：

这样生成的代码将无法被正确地摇树优化。

annotateForClosureCompiler

如果为 true，则使用 Tsickle 来用 JSDoc 对生成的 JavaScript 代码进行注解，这些注释是供 Closure 编译器使用的。默认值为 false。

compilationMode

指定要使用的编译模式。可以使用以下模式：

模式	详情
`'full'`	根据当前使用的 Angular 版本生成完全 AOT 编译的代码。
`'partial'`	生成稳定的中间代码，适用于已发布的库。

默认值为 'full'。

disableExpressionLowering

如果为 true（默认值），则转换在注解中使用或允许使用的代码，以允许从模板的工厂模块导入代码。

如果为 false，则禁用此重写，你必须手动进行重写。

disableTypeScriptVersionCheck

如果为 true，则在使用不受支持的 TypeScript 版本时，编译器不会检查 TypeScript 版本，并且不会报错。不建议使用，因为不受支持的 TypeScript 版本可能具有未定义的行为。默认值为 false。

enableI18nLegacyMessageIdFormat

指示 Angular 模板编译器为模板中用 i18n 属性标出的消息生成旧版 ID。

除非你的项目依赖先前已用旧版 ID 生成的翻译，否则请将此选项设置为 false。默认值为 true。

Ivy 之前版本的消息提取工具为所提取的消息 id 生成了多种旧格式。这些消息格式存在许多问题，比如对空白字符的处理和对模板原始 HTML 内部信息的依赖。

新的消息格式对空白字符的改动更宽容，在所有翻译文件格式中都相同，并且可以直接通过调用 $localize 生成。这允许应用程序代码中的 $localize 消息使用与组件模板中 i18n 消息完全相同的 id。

enableResourceInlining

当为 true 时，将所有 @Component 装饰器中的 templateUrl 和 styleUrls 属性替换为 template 和 styles 属性中的内联内容。

启用后，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 时，将生成指定文件名和相应扁平模块元数据的扁平模块索引。用于创建像 @angular/core 和 @angular/common 这样打包的扁平模块。使用此选项时，库的 package.json 应引用生成的扁平模块索引而不是库的索引文件。

它只会生成一个 .metadata.json 文件，该文件包含从库索引中导出的符号所需的全部元数据。在生成的 .ngfactory.js 文件中，扁平模块索引用于导入符号，这些符号既包括库索引中的公共 API，也包括缩进的内部符号。

默认情况下，files 字段中提供的 .ts 文件会被当做库索引。如果指定了多个 .ts 文件，则使用 libraryIndex 选择要使用的文件。如果提供了多个不带 libraryIndex .ts 文件，则会产生错误。

使用指定的 flatModuleOutFile 名在与库索引 .d.ts 文件相同的位置创建扁平模块索引 .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 选项已经在 Angular 13 中弃用，改为使用 strictTemplates 家族的编译器选项。

generateCodeForLibraries

如果为 true（默认值），就会为 .d.ts 和相应的 .metadata.json 生成工厂文件（.ngfactory.js 和 .ngstyle.js）。

如果为 false，则仅为 .ts 文件生成工厂文件。当要使用工厂摘要（summary）时，请这么设置。

preserveWhitespaces

如果为 false（默认值），则从编译的模板中删除空白文本节点，这将生成较小的模板工厂模块。设置为 true

skipMetadataEmit

为 true 时，不生成 .metadata.json 文件。默认值为 false。

.metadata.json 文件包含模板编译器从 .ts 文件中获得的信息，该信息未包含在 TypeScript 编译器生成的 .d.ts 文件中。该信息包括注解的内容（比如组件的模板）等，TypeScript 会将该注解的内容发送到 .js 文件中，但不会发送到 .d.ts 文件。

你可以在使用工厂摘要（summary）中将其设置为 true，因为工厂摘要中包括 .metadata.json 文件中信息的副本。

如果要使用 TypeScript 的 --outFile 选项，则设置为 true，因为元数据文件对于这种 TypeScript 输出风格无效。但是，我们不建议将 --outFile 和 Angular 一起使用。请使用打包程序，比如 webpack。以保留空白文本节点。

skipTemplateCodegen

为 true 时，不生成 .ngfactory.js 和 .ngstyle.js 文件。这将关闭大多数模板编译器，并禁用模板诊断报告。

可用于指示模板编译器生成 .metadata.json 文件，以使用 npm 软件包进行分发，同时避免产生无法分发至 npm 的 .ngfactory.js 和 .ngstyle.js 文件。

对于使用 CLI 生成的库项目，dev 配置默认为 true。

strictMetadataEmit

为 true 时，如果 "skipMetadataEmit" 为 false 则向 .metadata.json 文件中报告错误。默认值为 false。只在 "skipMetadataEmit" 为 false 且 "skipTemplateCodegen" 为 true 时使用。

该选项是为了验证为生成 npm 包而产生的 .metadata.json 文件。这种验证是严格的，并且会报告元数据中的错误，以免当模板编译器使用它时再出错。你可以通过在某个导出符号的注释文档中使用 @dynamic 注解来暂时防止（suppress）该选项报告错误。

.metadata.json 文件即使包含错误也是有效的。如果这些元数据用来确定注解的内容，则模板编译器会报告这些错误。元数据收集器无法预测哪些符号是为了在注解中使用而设计，因此它会先在元数据中为导出的符号中包含错误节点。然后，如果使用了这些符号，则模板编译器可以使用这些错误节点来报告错误。

如果库的客户代码打算在注解中使用某个符号，则模板编译器通常不会在客户方用到该符号之前就报错。此选项允许你在库的构建阶段就检测到这些错误，比如用于生成 Angular 库本身时。

对于使用 CLI 生成的库项目，dev 配置中默认为 true。

strictInjectionParameters

如果为 true（推荐），则报告所提供的参数的错误，无法确定该参数的注入类型。如果为 false（当前为默认值），则标记为 @Injectable 但其类型无法解析的类的构造函数参数会产生警告。

当你使用 CLI 命令 ng new --strict 时，默认生成的项目配置中将其设置为 true。

strictTemplates

如果为 true，则启用严格的模板类型检查。

其它严格性标志允许你启用和禁用特定类型的严格模板类型检查。

当你使用 CLI 命令 ng new --strict 时，默认生成的项目配置中将其设置为 true。

trace

如果为 true，则在编译模板时输出额外的信息。默认值为 false。

命令行选项

虽然大多数时候你都会使用 Angular CLI 间接与 Angular 编译器交互，但在调试某些问题时，你可能会发现直接调用 Angular 编译器很有用。你可以使用 @angular/compiler-cli npm 包提供的 ngc 命令从命令行调用编译器。

ngc 命令只是 TypeScript 的 tsc 编译器命令的包装器，主要通过前面部分讲过的 tsconfig.json 配置选项进行配置。

除了配置文件，你还可以使用一些 tsc命令行选项来配置 ngc。