Angular13 Angular 编译器选项

2024-02-25 开发教程 Angular13 匿名 2

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​。