diff --git a/packages/core/src/metadata/ng_module.ts b/packages/core/src/metadata/ng_module.ts index 124bd314e3..bd794ac768 100644 --- a/packages/core/src/metadata/ng_module.ts +++ b/packages/core/src/metadata/ng_module.ts @@ -16,11 +16,17 @@ import {TypeDecorator, makeDecorator} from '../util/decorators'; /** * Represents the expansion of an `NgModule` into its scopes. * + * 表示要将 `NgModule` 扩展到其范围中。 + * * A scope is a set of directives and pipes that are visible in a particular context. Each * `NgModule` has two scopes. The `compilation` scope is the set of directives and pipes that will * be recognized in the templates of components declared by the module. The `exported` scope is the * set of directives and pipes exported by a module (that is, module B's exported scope gets added * to module A's compilation scope when module A imports B). + * + * 范围是指一组在特定上下文中可见的指令和管道。每个 `NgModule` 具有两种范围。 + * `compilation` 范围是指能在当前模块的组件模板中识别的指令和管道。 + * `exported` 范围是指当前模块中导出的指令和管道(也就是说,如果模块 A 引入了模块 B,那么模块 B 的范围就会合并到模块 A 的编译范围中)。 */ export interface NgModuleTransitiveScopes { compilation: {directives: Set; pipes: Set;}; @@ -30,42 +36,68 @@ export interface NgModuleTransitiveScopes { /** * A version of {@link NgModuleDef} that represents the runtime type shape only, and excludes * metadata parameters. + * + * 一个 {@link NgModuleDef} 版本只表示其运行时形态,而不包括元数据中的各个参数。 */ export type NgModuleDefInternal = NgModuleDef; /** * Runtime link information for NgModules. * + * NgModule 的运行时链接信息。 + * * This is the internal data structure used by the runtime to assemble components, directives, * pipes, and injectors. * + * 这是在运行期间装配组件、指令、管道和注入器时所需的内部数据结构。 + * * NOTE: Always use `defineNgModule` function to create this object, * never create the object directly since the shape of this object * can change between versions. + * + * 注意:总是使用 `defineNgModule` 函数来创建该对象,永远不要直接创建它,因为该对象的结构在不同版本间可能会不一样。 */ export interface NgModuleDef { - /** Token representing the module. Used by DI. */ + /** Token representing the module. Used by DI. + * + * 用于表示该模块的一个令牌。供 DI 系统使用。 + */ type: T; - /** List of components to bootstrap. */ + /** List of components to bootstrap. + * + * 列出用于引导的组件。 + */ bootstrap: Type[]; - /** List of components, directives, and pipes declared by this module. */ + /** List of components, directives, and pipes declared by this module. + * + * 列出本模块中声明的组件、指令和管道。 + */ declarations: Type[]; - /** List of modules or `ModuleWithProviders` imported by this module. */ + /** List of modules or `ModuleWithProviders` imported by this module. + * + * 列出被本模块导入的模块或 `ModuleWithProviders`。 + */ imports: Type[]; /** * List of modules, `ModuleWithProviders`, components, directives, or pipes exported by this * module. + * + * 列出本模块导出的模块、`ModuleWithProviders`、组件、指令或管道。 */ exports: Type[]; /** * Cached value of computed `transitiveCompileScopes` for this module. * + * 本模块的 `transitiveCompileScopes` 计算结果的缓存值。 + * * This should never be read directly, but accessed via `transitiveScopesFor`. + * + * 永远不要直接使用它,而是通过 `transitiveScopesFor` 来访问。 */ transitiveCompileScopes: NgModuleTransitiveScopes|null; } @@ -73,8 +105,12 @@ export interface NgModuleDef { /** * A wrapper around an NgModule that associates it with the providers. * + * 对 NgModule 及其相关 providers 的包装。 + * * @param T the module type. In Ivy applications, this must be explicitly * provided. + * + * 模块类型。在 Ivy 应用中,它必须显式提供。 */ export interface ModuleWithProviders { ngModule: Type; @@ -83,21 +119,35 @@ export interface ModuleWithProviders { /** * A schema definition associated with an NgModule. - * + * + * 与 NgModule 相关的 schema(HTML架构)定义。 + * * @see `@NgModule`, `CUSTOM_ELEMENTS_SCHEMA`, `NO_ERRORS_SCHEMA` - * + * * @param name The name of a defined schema. * + * 已定义的 schema 的名字。 + * * @experimental */ export interface SchemaMetadata { name: string; } /** * Defines a schema that allows an NgModule to contain the following: + * + * 定义一个 schema,它允许 NgModule 包含下列内容: + * * - Non-Angular elements named with dash case (`-`). + * + * 中线格式(`-`)的非 Angular 元素名。 + * * - Element properties named with dash case (`-`). + * + * 中线格式(`-`)的元素属性名。 + * * Dash case is the naming convention for custom elements. * + * 中线格式是对自定义元素的命名约定。 * */ export const CUSTOM_ELEMENTS_SCHEMA: SchemaMetadata = { @@ -107,6 +157,8 @@ export const CUSTOM_ELEMENTS_SCHEMA: SchemaMetadata = { /** * Defines a schema that allows any property on any element. * + * 定义了一个允许任何元素上的任何属性的 schema。 + * * @experimental */ export const NO_ERRORS_SCHEMA: SchemaMetadata = { @@ -118,10 +170,13 @@ export const NO_ERRORS_SCHEMA: SchemaMetadata = { * Type of the NgModule decorator / constructor function. * * + * NgModule 装饰器和构造函数的类型。 */ export interface NgModuleDecorator { /** * Marks a class as an NgModule and supplies configuration metadata. + * + * 把一个类标记为 NgModule,并提供配置元数据。 */ (obj?: NgModule): TypeDecorator; new (obj?: NgModule): NgModule; @@ -130,13 +185,16 @@ export interface NgModuleDecorator { /** * Type of the NgModule metadata. * + * NgModule 元数据的类型。 * */ export interface NgModule { /** * The set of injectable objects that are available in the injector * of this module. - * + * + * 在当前模块的注入器中可用的一组可注入对象。 + * * @see [Dependency Injection guide](guide/dependency-injection) * @see [NgModule guide](guide/providers) * @@ -146,19 +204,32 @@ export interface NgModule { * into any component, directive, pipe or service that is a child of this injector. * The NgModule used for bootstrapping uses the root injector, and can provide dependencies * to any part of the app. - * + * + * 在这里列出了提供商的依赖项可用于注入到任何组件、指令、管道或该注入器下的服务。 + * 引导用的 NgModule 使用的是根注入器,可以为应用中的任何部件提供依赖。 + * * A lazy-loaded module has its own injector, typically a child of the app root injector. * Lazy-loaded services are scoped to the lazy-loaded module's injector. * If a lazy-loaded module also provides the `UserService`, any component created * within that module's context (such as by router navigation) gets the local instance - * of the service, not the instance in the root injector. + * of the service, not the instance in the root injector. * Components in external modules continue to receive the instance provided by their injectors. - * + * + * 惰性加载的模块有自己的注入器,通常它是根注入器的一个子注入器。 + * 惰性加载的服务,其作用范围局限于这个惰性加载模块的注入器。 + * 如果惰性加载模块也提供了 `UserService`,则任何在该模块的上下文中创建的组件(比如通过路由导航)都会获得该服务的一个局部实例, + * 而不是根注入器中的全局实例。 + * 而外部模块中的组件仍然会使用由它们的注入器提供的实例。 + * * ### Example * + * ### 范例 + * * The following example defines a class that is injected in * the HelloWorld NgModule: * + * 下面的例子定义了一个类,它被注册在 HelloWorld 这个 NgModule 的注入器下: + * * ``` * class Greeter { * greet(name:string) { @@ -186,20 +257,32 @@ export interface NgModule { * The set of components, directives, and pipes ([declarables](guide/glossary#declarable)) * that belong to this module. * + * 属于该模块的一组组件、指令和管道(统称[可声明对象](guide/glossary#declarable))。 + * * @usageNotes * * The set of selectors that are available to a template include those declared here, and * those that are exported from imported NgModules. * + * 在模板中可用的选择器(selector)包括那些直接声明在这里的可声明对象和导入的那些 NgModule 中所导出的可声明对象。 + * * Declarables must belong to exactly one module. * The compiler emits an error if you try to declare the same class in more than one module. * Be careful not to declare a class that is imported from another module. * + * 可声明对象必须属于也只能属于一个模块。 + * 如果你尝试把同一个类声明在多个模块中,那么编译器就会报错。 + * 要注意不能声明那些从其它模块中导入的类。 + * * ### Example * + * ### 范例 + * * The following example allows the CommonModule to use the `NgFor` * directive. * + * 下面的例子允许 CommonModule 使用 `NgFor` 指令。 + * * ```javascript * @NgModule({ * declarations: [NgFor] @@ -214,6 +297,8 @@ export interface NgModule { * The set of NgModules whose exported [declarables](guide/glossary#declarable) * are available to templates in this module. * + * 这里列出的 NgModule 所导出的[可声明对象](guide/glossary#declarable)可用在当前模块内的模板中。 + * * @usageNotes * * A template can use exported declarables from any @@ -223,11 +308,18 @@ export interface NgModule { * it, which makes the declarables from `ModuleB` available * wherever `ModuleA` is imported. * + * 模板可以使用来自任何导入模块中所导出的可声明对象,包括它们从别的模块导入后重新导出的。 + * 例如,`ModuleA` 导入了 `ModuleB` 并导出了它,就会让 `ModuleB` 中的可声明对象也同样在那些导入了 `ModuleA` 的模块中可用。 + * * ### Example * + * ### 范例 + * * The following example allows MainModule to use anthing exported by * `CommonModule`: * + * 下列例子允许 `MainModule` 使用 `CommonModule` 中导入的任意可声明对象: + * * ```javascript * @NgModule({ * imports: [CommonModule] @@ -244,23 +336,37 @@ export interface NgModule { * NgModule that can be used in the template of any component that is part of an * NgModule that imports this NgModule. Exported declarations are the module's public API. * + * 此 NgModule 中声明的一组组件、指令和管道可以在导入了本模块的模块下任何组件的模板中使用。 + * 导出的这些可声明对象就是该模块的公共 API。 + * * A declarable belongs to one and only one NgModule. * A module can list another module among its exports, in which case all of that module's * public declaration are exported. * + * 可声明对象应该且只能属于一个 NgModule。 + * 一个模块可以列出在它的 `exports` 中列出一些其它模块,这些模块中所有公开的可声明对象也同样会导出。 + * * @usageNotes * * Declarations are private by default. * If this ModuleA does not export UserComponent, then only the components within this * ModuleA can use UserComponent. * + * 默认情况下,可声明对象是私有的。 + * * ModuleA can import ModuleB and also export it, making exports from ModuleB * available to an NgModule that imports ModuleA. * + * 导出具有传递性。ModuleA 可以导入 ModuleB 并将其导出,这会让所有 ModuleB 中的导出同样可用在导入了 ModuleA 的那些模块中。 + * * ### Example * + * ### 范例 + * * The following example exports the `NgFor` directive from CommonModule. * + * 下面的例子导出了来自 `CommonModule` 的 `NgFor` 指令。 + * * ```javascript * @NgModule({ * exports: [NgFor] @@ -275,14 +381,21 @@ export interface NgModule { * The set of components to compile when this NgModule is defined, * so that they can be dynamically loaded into the view. * + * 定义此 NgModule 中要编译的组件集,这样它们才可以动态加载到视图中。 + * * For each component listed here, Angular creates a `ComponentFactory` * and stores it in the `ComponentFactoryResolver`. * + * 对于在这里列出的每个组件,Angular 都会为其创建一个 `ComponentFactory`,并将其保存到 `ComponentFactoryResolver` 中。 + * * Angular automatically adds components in the module's bootstrap * and route definitions into the `entryComponents` list. Use this * option to add components that are bootstrapped * using one of the imperative techniques, such as `ViewContainerRef.createComponent()`. * + * Angular 会自动把模块的 `bootstrap`(引导模块)和路由定义中引用的组件添加到 `entryComponents` 列表中。 + * 该选项用于添加那些需要写代码来创建的组件,比如 `ViewContainerRef.createComponent()`。 + * * @see [Entry Components](guide/entry-components) */ entryComponents?: Array|any[]>; @@ -291,6 +404,8 @@ export interface NgModule { * The set of components that are bootstrapped when * this module is bootstrapped. The components listed here * are automatically added to `entryComponents`. + * + * 当该模块引导时需要进行引导的组件。列在这里的所有组件都会自动添加到 `entryComponents` 中。 */ bootstrap?: Array|any[]>; @@ -299,10 +414,17 @@ export interface NgModule { * Elements and properties that are neither Angular components nor directives * must be declared in a schema. * + * 该 NgModule 中允许使用的声明元素的 schema(HTML 架构)。 + * 元素和属性(无论是 Angular 组件还是指令)都必须声明在 schema 中。 + * * Allowed value are `NO_ERRORS_SCHEMA` and `CUSTOM_ELEMENTS_SCHEMA`. * + * 允许的取值包括 `NO_ERRORS_SCHEMA` 和 `CUSTOM_ELEMENTS_SCHEMA`。 + * * @security When using one of `NO_ERRORS_SCHEMA` or `CUSTOM_ELEMENTS_SCHEMA` * you must ensure that allowed elements and properties securely escape inputs. + * + * 当使用 `NO_ERRORS_SCHEMA` 或 `CUSTOM_ELEMENTS_SCHEMA` 之一时,你必须确保所允许的元素和属性的所有输入都经过了安全转义。 */ schemas?: Array; @@ -310,6 +432,9 @@ export interface NgModule { * A name or path that uniquely identifies this NgModule in `getModuleFactory`. * If left `undefined`, the NgModule is not registered with * `getModuleFactory`. + * + * 当前 NgModule 在 `getModuleFactory` 中的名字或唯一标识符。 + * 如果为 `undefined`,则该模块不会被注册进 `getModuleFactory` 中。 */ id?: string; @@ -317,7 +442,11 @@ export interface NgModule { * If true, this module will be skipped by the AOT compiler and so will always be compiled * using JIT. * + * 如果为 `true`,则该模块将会被 AOT 编译器忽略,因此永远不会用 JIT 编译它。 + * * This exists to support future Ivy work and has no effect currently. + * + * 这是为了支持未来的 Ivy 渲染器,目前没什么用。 */ jit?: true; } @@ -339,16 +468,27 @@ function preR3NgModuleCompile(moduleType: InjectorType, metadata: NgModule) * @Annotation */ export const NgModule: NgModuleDecorator = makeDecorator( - 'NgModule', (ngModule: NgModule) => ngModule, undefined, undefined, - /** - * Decorator that marks the following class as an NgModule, and supplies - * configuration metadata for it. - * - * * The `declarations` and `entryComponents` options configure the compiler - * with information about what belongs to the NgModule. - * * The `providers` options configures the NgModule's injector to provide - * dependencies the NgModule members. - * * The `imports` and `exports` options bring in members from other modules, and make - * this module's members available to others. - */ - (type: Type, meta: NgModule) => (R3_COMPILE_NGMODULE || preR3NgModuleCompile)(type, meta)); + 'NgModule', (ngModule: NgModule) => ngModule, undefined, undefined, + /** + * Decorator that marks the following class as an NgModule, and supplies + * configuration metadata for it. + * + * 一个装饰器,用于把当前类标记为一个 NgModule,并为之提供配置元数据。 + * + * * The `declarations` and `entryComponents` options configure the compiler + * with information about what belongs to the NgModule. + * + * `declarations` 和 `entryComponents` 选项告诉编译器,哪些东西是属于本 NgModule 的。 + * + * * The `providers` options configures the NgModule's injector to provide + * dependencies the NgModule members. + * + * `providers` 选项会配置该 NgModule 的注入器,以便为该 NgModule 的所有成员提供依赖项。 + * + * * The `imports` and `exports` options bring in members from other modules, and make + * this module's members available to others. + * + * `imports` 选项用于从其它模块中带入成员,`exports` 选项用于把本模块的成员带给其它模块。 + * + */ + (type: Type, meta: NgModule) => (R3_COMPILE_NGMODULE || preR3NgModuleCompile)(type, meta));