使用 AoT 编译 时,可以通过在 TypeScript 配置文件中 指定模板编译器选项来控制如何编译应用程序。
模板选项对象 angularCompilerOptions
和为 TypeScript 编译器提供标准选项的 compilerOptions
对象是兄弟。
{
"compileOnSave": false,
"compilerOptions": {
"baseUrl": "./",
// ...
},
"angularCompilerOptions": {
"enableI18nLegacyMessageIdFormat": false,
"strictInjectionParameters": true,
// ...
}
}
像 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 模板编译器。
如果为 true
,则生成所有可能的文件 —— 即使它们为空。默认值为 false
。Bazel 的构建规则使用它来简化 Bazel 规则跟踪文件依赖性的方式。不要在 Bazel 规则之外使用此选项。
修改 Angular 专有注解的生成方式,以改善摇树优化。非 Angular 注解不受影响。可选值为 static fields
(默认值)或 decorators
。
decorators
值会将装饰器保留在原处,这将使编译速度更快。TypeScript 会生成对辅助器 __decorate
的调用。使用 --emitDecoratorMetadata
以支持运行时反射。注意:如果为 true
,则使用 Tsickle 来用 JSDoc对生成的 JavaScript 代码进行注解,这些注释是供 Closure 编译器 使用的。默认值为 false
。
指定要使用的编译模式。可以使用以下模式:
模式 | 详情 |
---|---|
'full' | 根据当前使用的 Angular 版本生成完全 AOT 编译的代码。 |
'partial' | 生成稳定的中间代码,适用于已发布的库。 |
默认值为 'full'
。
如果为 true
(默认值),则转换在注解中使用或允许使用的代码,以允许从模板的工厂模块导入代码。
如果为 false
,则禁用此重写,你必须手动进行重写。
如果为 true
,则在使用不受支持的 TypeScript 版本时,编译器不会检查 TypeScript 版本,并且不会报错。不建议使用,因为不受支持的 TypeScript 版本可能具有未定义的行为。默认值为 false
。
指示 Angular 模板编译器为模板中用 i18n
属性标出的消息生成旧版 ID。
除非你的项目依赖先前已用旧版 ID 生成的翻译,否则请将此选项设置为 false
。默认值为 true
。
Ivy 之前版本的消息提取工具为所提取的消息 id 生成了多种旧格式。这些消息格式存在许多问题,比如对空白字符的处理和对模板原始 HTML 内部信息的依赖。
新的消息格式对空白字符的改动更宽容,在所有翻译文件格式中都相同,并且可以直接通过调用 $localize
生成。这允许应用程序代码中的 $localize
消息使用与组件模板中 i18n
消息完全相同的 id。
当为 true
时,将所有 @Component
装饰器中的 templateUrl
和 styleUrls
属性替换为 template
和 styles
属性中的内联内容。
启用后,ngc
的 .js
输出不会包含任何惰性加载的模板或样式 URL。
对于使用 CLI 生成的库项目,dev 配置下默认为 true
。
如果为 true
,则启用 Angular 4.0 中为了避免与同名的 DOM 元素冲突而不推荐使用的 <template>
元素(推荐改用 <ng-template>
)。默认值为 false
。某些第三方 Angular 库可能需要它。
用于导入扁平模块的模块 ID(当 flatModuleOutFile
为 true
时)。从扁平模块中导入符号时,模板编译器生成的引用将使用该模块的名称。如果 flatModuleOutFile
为 false
则忽略。
为 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"
。
为 true
(推荐)时,会启用模板编译器的绑定表达式验证阶段,该阶段使用 TypeScript 来验证绑定表达式。
默认值为 false
,但是当你使用 CLI 命令 ng new --strict
时,默认生成的项目配置中会将其设置为 true
。
fullTemplateTypeCheck
选项已经在 Angular 13 中弃用,改为使用 strictTemplates
家族的编译器选项。
如果为 true
(默认值),就会为 .d.ts
和相应的 .metadata.json
生成工厂文件(.ngfactory.js
和 .ngstyle.js
)。
如果为 false
,则仅为 .ts
文件生成工厂文件。当要使用工厂摘要(summary)时,请这么设置。
如果为 false
(默认值),则从编译的模板中删除空白文本节点,这将生成较小的模板工厂模块。设置为 true
为 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。以保留空白文本节点。
为 true
时,不生成 .ngfactory.js
和 .ngstyle.js
文件。这将关闭大多数模板编译器,并禁用模板诊断报告。
可用于指示模板编译器生成 .metadata.json
文件,以使用 npm
软件包进行分发,同时避免产生无法分发至 npm
的 .ngfactory.js
和 .ngstyle.js
文件。
对于使用 CLI 生成的库项目,dev 配置默认为 true
。
为 true
时,如果 "skipMetadataEmit"
为 false
则向 .metadata.json
文件中报告错误。默认值为 false
。只在 "skipMetadataEmit"
为 false
且 "skipTemplateCodegen"
为 true
时使用。
该选项是为了验证为生成 npm
包而产生的 .metadata.json
文件。这种验证是严格的,并且会报告元数据中的错误,以免当模板编译器使用它时再出错。你可以通过在某个导出符号的注释文档中使用 @dynamic
注解来暂时防止(suppress)该选项报告错误。
.metadata.json
文件即使包含错误也是有效的。如果这些元数据用来确定注解的内容,则模板编译器会报告这些错误。元数据收集器无法预测哪些符号是为了在注解中使用而设计,因此它会先在元数据中为导出的符号中包含错误节点。然后,如果使用了这些符号,则模板编译器可以使用这些错误节点来报告错误。
如果库的客户代码打算在注解中使用某个符号,则模板编译器通常不会在客户方用到该符号之前就报错。此选项允许你在库的构建阶段就检测到这些错误,比如用于生成 Angular 库本身时。
对于使用 CLI 生成的库项目,dev 配置中默认为 true
。
如果为 true
(推荐),则报告所提供的参数的错误,无法确定该参数的注入类型。如果为 false
(当前为默认值),则标记为 @Injectable
但其类型无法解析的类的构造函数参数会产生警告。
当你使用 CLI 命令 ng new --strict
时,默认生成的项目配置中将其设置为 true
。
如果为 true
,则启用严格的模板类型检查。
其它严格性标志允许你启用和禁用特定类型的严格模板类型检查。
当你使用 CLI 命令 ng new --strict
时,默认生成的项目配置中将其设置为 true
。
如果为 true
,则在编译模板时输出额外的信息。默认值为 false
。
虽然大多数时候你都会使用 Angular CLI 间接与 Angular 编译器交互,但在调试某些问题时,你可能会发现直接调用 Angular 编译器很有用。你可以使用 @angular/compiler-cli
npm 包提供的 ngc
命令从命令行调用编译器。
ngc
命令只是 TypeScript 的 tsc
编译器命令的包装器,主要通过前面部分讲过的 tsconfig.json
配置选项进行配置。
除了配置文件,你还可以使用一些 tsc命令行选项来配置 ngc
。