docs: several minor `NgModule` guide fixes/improvements (#21589)
PR Close #21589
This commit is contained in:
George Kalpakas
Miško Hevery
parent
bf248792eb
commit
81e87095b4
|
|
@ -15,8 +15,7 @@ const routes: Routes = [
|
|||
|
||||
@NgModule({
|
||||
imports: [RouterModule.forChild(routes)],
|
||||
exports: [RouterModule],
|
||||
providers: []
|
||||
exports: [RouterModule]
|
||||
})
|
||||
export class CustomersRoutingModule { }
|
||||
// #enddocregion customers-routing-module
|
||||
|
|
|
|||
|
|
@ -6,23 +6,17 @@ import { Routes, RouterModule } from '@angular/router';
|
|||
// #docregion orders-routing-module-detail
|
||||
import { OrderListComponent } from './order-list/order-list.component';
|
||||
|
||||
|
||||
const routes: Routes = [
|
||||
{
|
||||
path: '',
|
||||
component: OrderListComponent
|
||||
}
|
||||
];
|
||||
|
||||
// #enddocregion orders-routing-module-detail
|
||||
|
||||
@NgModule({
|
||||
imports: [
|
||||
RouterModule.forChild(routes)
|
||||
],
|
||||
exports: [
|
||||
RouterModule
|
||||
]
|
||||
imports: [RouterModule.forChild(routes)],
|
||||
exports: [RouterModule]
|
||||
})
|
||||
export class OrdersRoutingModule { }
|
||||
// #enddocregion orders-routing-module
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ A basic understanding of the following concepts:
|
|||
|
||||
<hr />
|
||||
|
||||
An entry component is any component that Angular loads imperatively, (which means you’re not referencing it in the template), by type. You specify an entry component by bootstrapping it in an NgModule,or including it in a routing definition.
|
||||
An entry component is any component that Angular loads imperatively, (which means you’re not referencing it in the template), by type. You specify an entry component by bootstrapping it in an NgModule, or including it in a routing definition.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
|
|
@ -28,7 +28,7 @@ There are two main kinds of entry components:
|
|||
The following is an example of specifying a bootstrapped component,
|
||||
`AppComponent`, in a basic `app.module.ts`:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
@NgModule({
|
||||
declarations: [
|
||||
AppComponent
|
||||
|
|
@ -43,15 +43,16 @@ The following is an example of specifying a bootstrapped component,
|
|||
bootstrap: [AppComponent] // bootstrapped entry component
|
||||
})
|
||||
```
|
||||
|
||||
A bootstrapped component is an entry component
|
||||
that Angular loads into the DOM during the bootstrap (application launch), process.
|
||||
that Angular loads into the DOM during the bootstrap process (application launch).
|
||||
Other entry components are loaded dynamically by other means, such as with the router.
|
||||
|
||||
Angular loads a root `AppComponent` dynamically because it's listed by type in `@NgModule.bootstrap`.
|
||||
|
||||
<div class="alert is-helpful">
|
||||
|
||||
A component can also be bootstrapped imperatively with the module's `ngDoBootstrap()` method.
|
||||
A component can also be bootstrapped imperatively in the module's `ngDoBootstrap()` method.
|
||||
The `@NgModule.bootstrap` property tells the compiler that this is an entry component and
|
||||
it should generate code to bootstrap the application with this component.
|
||||
|
||||
|
|
@ -66,7 +67,7 @@ A bootstrapped component is necessarily an entry component because bootstrapping
|
|||
The second kind of entry component occurs in a route definition like
|
||||
this:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
const routes: Routes = [
|
||||
{
|
||||
path: '',
|
||||
|
|
@ -77,7 +78,7 @@ const routes: Routes = [
|
|||
|
||||
A route definition refers to a component by its type with `component: CustomerListComponent`.
|
||||
|
||||
All router components must be `entryComponents`. Because this would require you to add the component in two places (router and `entryComponent`) the Compiler is smart enough to recognize that this is a router definition and automatically add the router component into `entryComponents`.
|
||||
All router components must be entry components. Because this would require you to add the component in two places (router and `entryComponents`) the Compiler is smart enough to recognize that this is a router definition and automatically add the router component into `entryComponents`.
|
||||
|
||||
|
||||
## The `entryComponents` array
|
||||
|
|
@ -93,11 +94,11 @@ The code should contain only the classes that you actually need and
|
|||
exclude components that are never used. For this reason, the Angular compiler only generates code for components which are reachable from the `entryComponents`; This means that adding more references to `@NgModule.declarations` does not imply that they will necessarily be included in the final bundle.
|
||||
|
||||
In fact, many libraries declare and export components you'll never use.
|
||||
For example, a material design library will export all components because it doesn’t know which ones the you will use. However, it is unlikely that the you will use them all.
|
||||
For example, a material design library will export all components because it doesn’t know which ones you will use. However, it is unlikely that you will use them all.
|
||||
For the ones you don't reference, the tree shaker drops these components from the final code package.
|
||||
|
||||
If a component isn't an _entry component_ or isn't found in a template,
|
||||
The tree shaker will throw it away. So, it's best to add only the components that are truly entry components to help keep your app
|
||||
the tree shaker will throw it away. So, it's best to add only the components that are truly entry components to help keep your app
|
||||
as trim as possible.
|
||||
|
||||
|
||||
|
|
@ -110,7 +111,3 @@ You may also be interested in the following:
|
|||
* [Lazy Loading Modules with the Angular Router](guide/lazy-loading-ngmodules).
|
||||
* [Providers](guide/providers).
|
||||
* [NgModules FAQ](guide/ngmodule-faq).
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -36,7 +36,7 @@ pipes that it shares.
|
|||
Assuming you already have a CLI generated app, create a feature
|
||||
module using the CLI by entering the following command in the
|
||||
root project directory. Replace `CustomerDashboard` with the
|
||||
name of your module. You can omit the word module because the CLI appends it:
|
||||
name of your module. You can omit the "Module" suffix from the name because the CLI appends it:
|
||||
|
||||
```sh
|
||||
ng generate module CustomerDashboard
|
||||
|
|
@ -46,8 +46,7 @@ ng generate module CustomerDashboard
|
|||
|
||||
This causes the CLI to create a folder called `customer-dashboard` with a file inside called `customer-dashboard.module.ts` with the following contents:
|
||||
|
||||
```ts
|
||||
|
||||
```typescript
|
||||
import { NgModule } from '@angular/core';
|
||||
import { CommonModule } from '@angular/common';
|
||||
|
||||
|
|
@ -57,10 +56,7 @@ import { CommonModule } from '@angular/common';
|
|||
],
|
||||
declarations: []
|
||||
})
|
||||
|
||||
export class CustomerDashboardModule { }
|
||||
|
||||
|
||||
```
|
||||
|
||||
The structure of an NgModule is the same whether it is a root module or a feature module. In the CLI generated feature module, there are two JavaScript import statements at the top of the file: the first imports `NgModule`, which, like the root module, lets you use the `@NgModule` decorator; the second imports `CommonModule`, which contributes many common directives such as `ngIf` and `ngFor`. Feature modules import `CommonModule` instead of `BrowserModule`, which is only imported once in the root module. `CommonModule` only contains information for common directives such as `ngIf` and `ngFor` which are needed in most templates, whereas `BrowserModule` configures the Angular app for the browser which needs to be done only once.
|
||||
|
|
@ -76,7 +72,7 @@ ng generate component customer-dashboard/CustomerDashboard
|
|||
This generates a folder for the new component within the customer-dashboard folder and updates the feature module with the `CustomerDashboardComponent` info:
|
||||
|
||||
|
||||
<code-example path="feature-modules/src/app/customer-dashboard/customer-dashboard.module.ts" region="customer-dashboard-component" title="src/app/customer-dashboard.module.ts" linenums="false">
|
||||
<code-example path="feature-modules/src/app/customer-dashboard/customer-dashboard.module.ts" region="customer-dashboard-component" title="src/app/customer-dashboard/customer-dashboard.module.ts" linenums="false">
|
||||
</code-example>
|
||||
|
||||
|
||||
|
|
@ -85,7 +81,7 @@ The `CustomerDashboardComponent` is now in the JavaScript import list at the top
|
|||
|
||||
## Importing a feature module
|
||||
|
||||
To incorporate the feature module into your app, you have to let the root module, `app.module.ts`, know about it. Notice the `CustomerDashboardModule` export at the bottom of `customer-dashboard.module.ts`. This exposes it so that other modules can get to it. To import it into the AppModule, add it to the imports in `app.module.ts` and to the imports array:
|
||||
To incorporate the feature module into your app, you have to let the root module, `app.module.ts`, know about it. Notice the `CustomerDashboardModule` export at the bottom of `customer-dashboard.module.ts`. This exposes it so that other modules can get to it. To import it into the `AppModule`, add it to the imports in `app.module.ts` and to the `imports` array:
|
||||
|
||||
<code-example path="feature-modules/src/app/app.module.ts" region="app-module" title="src/app/app.module.ts" linenums="false">
|
||||
</code-example>
|
||||
|
|
@ -104,7 +100,7 @@ When the CLI generated the `CustomerDashboardComponent` for the feature module,
|
|||
|
||||
To see this HTML in the `AppComponent`, you first have to export the `CustomerDashboardComponent` in the `CustomerDashboardModule`. In `customer-dashboard.module.ts`, just beneath the declarations array, add an exports array containing `CustomerDashboardModule`:
|
||||
|
||||
<code-example path="feature-modules/src/app/customer-dashboard/customer-dashboard.module.ts" region="component-exports" title="src/app/customer-dashboard.module.ts" linenums="false">
|
||||
<code-example path="feature-modules/src/app/customer-dashboard/customer-dashboard.module.ts" region="component-exports" title="src/app/customer-dashboard/customer-dashboard.module.ts" linenums="false">
|
||||
</code-example>
|
||||
|
||||
|
||||
|
|
@ -129,6 +125,4 @@ Now, in addition to the title that renders by default, the `CustomerDashboardCom
|
|||
You may also be interested in the following:
|
||||
* [Lazy Loading Modules with the Angular Router](guide/lazy-loading-ngmodules).
|
||||
* [Providers](guide/providers).
|
||||
* [Types of NgModules](guide/module-types).
|
||||
|
||||
|
||||
* [Types of Feature Modules](guide/module-types).
|
||||
|
|
|
|||
|
|
@ -55,13 +55,13 @@ of some of the things they contain:
|
|||
|
||||
<tr>
|
||||
<td><code>RouterModule</code></td>
|
||||
<td><code>@angular/forms</code></td>
|
||||
<td><code>@angular/router</code></td>
|
||||
<td>For Routing and when you want to use <code>RouterLink</code>,<code>.forRoot()</code>, and <code>.forChild()</code></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><code>HttpModule</code></td>
|
||||
<td><code>@angular/http</code></td>
|
||||
<td><code>HttpClientModule</code></td>
|
||||
<td><code>@angular/common/http</code></td>
|
||||
<td>When you to talk to a server</td>
|
||||
</tr>
|
||||
|
||||
|
|
@ -73,29 +73,25 @@ When you use these Angular modules, import them in `AppModule`,
|
|||
or your feature module as appropriate, and list them in the `@NgModule`
|
||||
`imports` array. For example, in the basic app generated by the CLI,
|
||||
`BrowserModule` is the first import at the top of the `AppModule`,
|
||||
`app.module.ts`. Notice that this is the same case for `FormsModule` and `HttpModule`.
|
||||
`app.module.ts`.
|
||||
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
/* import modules so that AppModule can access them */
|
||||
import { BrowserModule } from '@angular/platform-browser';
|
||||
import { NgModule } from '@angular/core';
|
||||
import { FormsModule } from '@angular/forms';
|
||||
import { HttpModule } from '@angular/http';
|
||||
|
||||
import { AppComponent } from './app.component';
|
||||
|
||||
@NgModule({
|
||||
declarations: [
|
||||
declarations: [
|
||||
AppComponent
|
||||
],
|
||||
imports: [ /* add modules here so Angular knows to use them */
|
||||
],
|
||||
imports: [ /* add modules here so Angular knows to use them */
|
||||
BrowserModule,
|
||||
FormsModule,
|
||||
HttpModule
|
||||
],
|
||||
providers: [],
|
||||
bootstrap: [AppComponent]
|
||||
],
|
||||
providers: [],
|
||||
bootstrap: [AppComponent]
|
||||
})
|
||||
export class AppModule { }
|
||||
```
|
||||
|
|
@ -135,4 +131,3 @@ You may also be interested in the following:
|
|||
* [Bootstrapping](guide/bootstrapping).
|
||||
* [NgModules](guide/ngmodules).
|
||||
* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
|
||||
|
||||
|
|
|
|||
|
|
@ -5,10 +5,11 @@ A basic understanding of the following:
|
|||
* [Feature Modules](guide/feature-modules).
|
||||
* [JavaScript Modules vs. NgModules](guide/ngmodule-vs-jsmodule).
|
||||
* [Frequently Used Modules](guide/frequent-ngmodules).
|
||||
* [Types of Modules](guide/module-types).
|
||||
* [Types of Feature Modules](guide/module-types).
|
||||
* [Routing and Navigation](guide/router).
|
||||
|
||||
For the final sample app with two lazy loaded modules that this page describes, see the <live-example></live-example>.
|
||||
For the final sample app with two lazy loaded modules that this page describes, see the
|
||||
<live-example></live-example>.
|
||||
|
||||
<hr>
|
||||
|
||||
|
|
@ -224,7 +225,4 @@ knows that the route list is only responsible for providing additional routes an
|
|||
You may also be interested in the following:
|
||||
* [Routing and Navigation](guide/router).
|
||||
* [Providers](guide/providers).
|
||||
* [Types of NgModules](guide/module-types).
|
||||
|
||||
|
||||
|
||||
* [Types of Feature Modules](guide/module-types).
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ typical characteristics, in real world apps, you may see hybrids.
|
|||
|
||||
A lazy-loaded routed feature module should not be imported by any module. Doing so would trigger an eager load, defeating the purpose of lazy loading.That means you won’t see them mentioned among the `AppModule` imports. An eager loaded routed feature module must be imported by another module so that the compiler learns about its components.
|
||||
|
||||
Routed feature modules rarely have providers for reasons explained in Lazy Loading Feature Modules(page forthcoming). When they do, the lifetime of the provided services should be the same as the lifetime of the module. Don't provide application-wide singleton services in a routed feature module or in a module that the routed module imports.
|
||||
Routed feature modules rarely have providers for reasons explained in [Lazy Loading Feature Modules](/guide/lazy-loading-ngmodules). When they do, the lifetime of the provided services should be the same as the lifetime of the module. Don't provide application-wide singleton services in a routed feature module or in a module that the routed module imports.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
|
|
@ -92,7 +92,7 @@ typical characteristics, in real world apps, you may see hybrids.
|
|||
<td>Service</td>
|
||||
<td>
|
||||
|
||||
Service modules provide utility services such as data access and messaging. Ideally, they consist entirely of providers and have no declarations. Angular's `HttpModule` is a good example of a service module.
|
||||
Service modules provide utility services such as data access and messaging. Ideally, they consist entirely of providers and have no declarations. Angular's `HttpClientModule` is a good example of a service module.
|
||||
|
||||
The root `AppModule` is the only module that should import service modules.
|
||||
|
||||
|
|
@ -189,4 +189,3 @@ The following table summarizes the key characteristics of each feature module gr
|
|||
You may also be interested in the following:
|
||||
* [Lazy Loading Modules with the Angular Router](guide/lazy-loading-ngmodules).
|
||||
* [Providers](guide/providers).
|
||||
* [Types of NgModules](guide/module-types).
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@ into three categories:
|
|||
* **Runtime:** Injector configuration via the `providers` array.
|
||||
* **Composability/Grouping:** Bringing NgModules together and making them available via the `imports` and `exports` arrays.
|
||||
|
||||
```ts
|
||||
```typescript
|
||||
@NgModule({
|
||||
// Static, that is compiler configuration
|
||||
declarations: [], // Configure the selectors
|
||||
|
|
@ -36,7 +36,7 @@ into three categories:
|
|||
|
||||
## `@NgModule` metadata
|
||||
|
||||
The following table summarizes the `NgModule` metadata properties.
|
||||
The following table summarizes the `@NgModule` metadata properties.
|
||||
|
||||
<table>
|
||||
|
||||
|
|
@ -60,15 +60,19 @@ The following table summarizes the `NgModule` metadata properties.
|
|||
|
||||
<td>
|
||||
|
||||
|
||||
A list of [declarable](guide/ngmodule-faq#q-declarable) classes,
|
||||
(*components*, *directives*, and *pipes*) that _belong to this module_.
|
||||
|
||||
1) When compiling a template, you need to determine a set of selectors which should be used for triggering their corresponding directives.
|
||||
2) The template is compiled within a context of an `NgModule`—the `NgModule` which this template's component is declared in—which determines the set of selectors using the following rules:
|
||||
a) All selectors of directives listed in `declarations`
|
||||
b) All exported selectors of imported `NgModules`.
|
||||
|
||||
<ol>
|
||||
<li>When compiling a template, you need to determine a set of selectors which should be used for triggering their corresponding directives.</li>
|
||||
<li>
|
||||
The template is compiled within the context of an NgModule—the NgModule within which the template's component is declared—which determines the set of selectors using the following rules:
|
||||
<ul>
|
||||
<li>All selectors of directives listed in `declarations`.</li>
|
||||
<li>All selectors of directives exported from imported NgModules.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
Components, directives, and pipes must belong to _exactly_ one module.
|
||||
The compiler emits an error if you try to declare the same class in more than one module.
|
||||
|
|
@ -87,11 +91,10 @@ The following table summarizes the `NgModule` metadata properties.
|
|||
|
||||
<td>
|
||||
|
||||
|
||||
A list of dependency-injection providers.
|
||||
|
||||
Angular registers these providers with the NgModule's injector.
|
||||
If it is the NgModule used for bootstrapping that it is the root injector.
|
||||
If it is the NgModule used for bootstrapping then it is the root injector.
|
||||
|
||||
These services become available for injection into any component, directive, pipe or service which is a child of this injector.
|
||||
|
||||
|
|
@ -119,16 +122,14 @@ The following table summarizes the `NgModule` metadata properties.
|
|||
|
||||
<td>
|
||||
|
||||
|
||||
A list of modules which should be folded into this module. Folded means it is
|
||||
as if all of the imported NgModule properties were declared here.
|
||||
as if all the imported NgModule's exported properties were declared here.
|
||||
|
||||
Specifically, it is as if the list of modules whose exported components, directives, or pipes
|
||||
are referenced by the component templates were declared in this module.
|
||||
|
||||
A component template can [reference](guide/ngmodule-faq#q-template-reference) another component, directive, or pipe
|
||||
when the reference is declared in this module
|
||||
or if the imported module has exported it.
|
||||
when the reference is declared in this module or if the imported module has exported it.
|
||||
For example, a component can use the `NgIf` and `NgFor` directives only if the
|
||||
module has imported the Angular `CommonModule` (perhaps indirectly by importing `BrowserModule`).
|
||||
|
||||
|
|
@ -136,6 +137,7 @@ The following table summarizes the `NgModule` metadata properties.
|
|||
but some familiar directives belong to other modules.
|
||||
For example, you can use `[(ngModel)]` only
|
||||
after importing the Angular `FormsModule`.
|
||||
|
||||
</td>
|
||||
|
||||
</tr>
|
||||
|
|
@ -148,19 +150,19 @@ The following table summarizes the `NgModule` metadata properties.
|
|||
|
||||
<td>
|
||||
|
||||
|
||||
A list of declarations—*component*, *directive*, and *pipe* classes—that
|
||||
an importing module can use.
|
||||
|
||||
Exported declarations are the module's _public API_.
|
||||
A component in another module can [use](guide/ngmodule-faq#q-template-reference) _this_ module's `UserComponent`
|
||||
if it imports this module and this module exports `UserComponent`.
|
||||
A component in another module can [use](guide/ngmodule-faq#q-template-reference) _this_
|
||||
module's `UserComponent` if it imports this module and this module exports `UserComponent`.
|
||||
|
||||
Declarations are private by default.
|
||||
If this module does _not_ export `UserComponent`, than only the components within where the `UserComponent` has been declared can use `UserComponent.
|
||||
If this module does _not_ export `UserComponent`, then only the components within _this_
|
||||
module can use `UserComponent`.
|
||||
|
||||
Importing a module does _not_ automatically re-export the imported module's imports.
|
||||
Module 'B' can't use `ngIf` just because it imported module `A` which imported `CommonModule`.
|
||||
Module 'B' can't use `ngIf` just because it imported module 'A' which imported `CommonModule`.
|
||||
Module 'B' must import `CommonModule` itself.
|
||||
|
||||
A module can list another module among its `exports`, in which case
|
||||
|
|
@ -182,7 +184,6 @@ The following table summarizes the `NgModule` metadata properties.
|
|||
|
||||
<td>
|
||||
|
||||
|
||||
A list of components that are automatically bootstrapped.
|
||||
|
||||
Usually there's only one component in this list, the _root component_ of the application.
|
||||
|
|
@ -204,7 +205,6 @@ The following table summarizes the `NgModule` metadata properties.
|
|||
|
||||
<td>
|
||||
|
||||
|
||||
A list of components that can be dynamically loaded into the view.
|
||||
|
||||
By default, an Angular app always has at least one entry component, the root component, `AppComponent`. Its purpose is to serve as a point of entry into the app, that is, you bootstrap it to launch the app.
|
||||
|
|
@ -218,11 +218,12 @@ The following table summarizes the `NgModule` metadata properties.
|
|||
|
||||
Angular automatically adds components in the module's `bootstrap` and route definitions into the `entryComponents` list.
|
||||
|
||||
That leaves only components bootstrapped using one of the imperative techniques, such as [`ViewComponentRef.createComponent()`](https://angular.io/api/core/ViewContainerRef#createComponent) as undiscoverable.
|
||||
That leaves only components bootstrapped using one of the imperative techniques, such as [`ViewComponentRef.createComponent()`](https://angular.io/api/core/ViewContainerRef#createComponent) as undiscoverable.
|
||||
|
||||
Dynamic component loading is not common in most apps beyond the router. If you need to dynamically load components, you must add these components to the `entryComponents` list yourself.
|
||||
|
||||
For more information, see [Entry Components](guide/entry-components).
|
||||
|
||||
</td>
|
||||
|
||||
</tr>
|
||||
|
|
@ -238,7 +239,4 @@ You may also be interested in the following:
|
|||
* [Feature Modules](guide/feature-modules).
|
||||
* [Entry Components](guide/entry-components).
|
||||
* [Providers](guide/providers).
|
||||
* [Types of NgModules](guide/module-types).
|
||||
|
||||
|
||||
|
||||
* [Types of Feature Modules](guide/module-types).
|
||||
|
|
|
|||
|
|
@ -120,7 +120,7 @@ Importing `CommonModule` also frees feature modules for use on _any_ target plat
|
|||
|
||||
<hr/>
|
||||
|
||||
<a id="q-reimport"></a>
|
||||
{@a q-reimport}
|
||||
|
||||
## What if I import the same module twice?
|
||||
|
||||
|
|
@ -136,13 +136,13 @@ Angular doesn't like NgModules with circular references, so don't let Module 'A'
|
|||
|
||||
<hr/>
|
||||
|
||||
<a id="q-reexport"></a>
|
||||
{@a q-reexport}
|
||||
|
||||
## What should I export?
|
||||
|
||||
Export [declarable](guide/bootstrapping#the-declarations-array) classes that components in _other_ NgModules
|
||||
are able to reference in their templates. These are your _public_ classes.
|
||||
If you don't export a class, it stays _private_, visible only to other component
|
||||
If you don't export a declarable class, it stays _private_, visible only to other components
|
||||
declared in this NgModule.
|
||||
|
||||
You _can_ export any declarable class—components, directives, and pipes—whether
|
||||
|
|
@ -164,7 +164,7 @@ If you don't want another NgModule to see it, don't export it.
|
|||
Such [entry components](guide/ngmodule-faq#q-entry-component-defined) can never be selected in another component's template.
|
||||
While there's no harm in exporting them, there's also no benefit.
|
||||
* Pure service modules that don't have public (exported) declarations.
|
||||
For example, there's no point in re-exporting `HttpModule` because it doesn't export anything.
|
||||
For example, there's no point in re-exporting `HttpClientModule` because it doesn't export anything.
|
||||
It's only purpose is to add http service providers to the application as a whole.
|
||||
|
||||
<hr/>
|
||||
|
|
@ -183,14 +183,13 @@ Angular's own `BrowserModule` exports a couple of NgModules like this:
|
|||
|
||||
```typescript
|
||||
exports: [CommonModule, ApplicationModule]
|
||||
|
||||
```
|
||||
|
||||
An NgModule can export a combination of its own declarations, selected imported classes, and imported NgModules.
|
||||
|
||||
Don't bother re-exporting pure service modules.
|
||||
Pure service modules don't export [declarable](guide/bootstrapping#the-declarations-array) classes that another NgModule could use.
|
||||
For example, there's no point in re-exporting `HttpModule` because it doesn't export anything.
|
||||
For example, there's no point in re-exporting `HttpClientModule` because it doesn't export anything.
|
||||
It's only purpose is to add http service providers to the application as a whole.
|
||||
|
||||
|
||||
|
|
@ -209,6 +208,7 @@ You add that result to the `imports` list of the root `AppModule`.
|
|||
Only call and import a `.forRoot()` result in the root application module, `AppModule`.
|
||||
Importing it in any other module, particularly in a lazy-loaded module,
|
||||
is contrary to the intent and will likely produce a runtime error.
|
||||
For more information, see [Singleton Services](guide/singleton-services).
|
||||
|
||||
`RouterModule` also offers a `forChild` static method for configuring the routes of lazy-loaded modules.
|
||||
|
||||
|
|
@ -237,7 +237,7 @@ This is by design.
|
|||
Extensibility through NgModule imports is a primary goal of the NgModule system.
|
||||
Merging NgModule providers into the application injector
|
||||
makes it easy for a module library to enrich the entire application with new services.
|
||||
By adding the `HttpModule` once, every application component can make HTTP requests.
|
||||
By adding the `HttpClientModule` once, every application component can make HTTP requests.
|
||||
|
||||
However, this might feel like an unwelcome surprise if you expect the module's services
|
||||
to be visible only to the components declared by that feature module.
|
||||
|
|
@ -247,9 +247,7 @@ not just the classes declared in the `HeroModule`.
|
|||
|
||||
<hr/>
|
||||
|
||||
<a id="q-lazy-loaded-module-provider-visibility"></a>
|
||||
{@ q-lazy-loaded-module-provider-visibility}
|
||||
|
||||
{@a q-lazy-loaded-module-provider-visibility}
|
||||
|
||||
## Why is a service provided in a lazy-loaded module visible only to that module?
|
||||
|
||||
|
|
@ -303,10 +301,10 @@ That's also usually the best place to configure, wrap, and override them.
|
|||
|
||||
Suppose a module requires a customized `HttpBackend` that adds a special header for all Http requests.
|
||||
If another module elsewhere in the application also customizes `HttpBackend`
|
||||
or merely imports the `HttpModule`, it could override this module's `HttpBackend` provider,
|
||||
or merely imports the `HttpClientModule`, it could override this module's `HttpBackend` provider,
|
||||
losing the special header. The server will reject http requests from this module.
|
||||
|
||||
To avoid this problem, import the `HttpModule` only in the `AppModule`, the application _root module_.
|
||||
To avoid this problem, import the `HttpClientModule` only in the `AppModule`, the application _root module_.
|
||||
|
||||
If you must guard against this kind of "provider corruption", *don't rely on a launch-time module's `providers`.*
|
||||
|
||||
|
|
@ -337,9 +335,8 @@ Define child routes and let the router load module components into that outlet.
|
|||
|
||||
<hr/>
|
||||
|
||||
<a id="q-root-component-or-module"></a>
|
||||
{@a q-root-component-or-module}
|
||||
|
||||
{@ q-root-component-or-module}
|
||||
|
||||
## Should I add application-wide providers to the root `AppModule` or the root `AppComponent`?
|
||||
|
||||
|
|
@ -372,9 +369,8 @@ where `AppComponent` services don't exist.
|
|||
This means that lazy-loaded modules can't reach them.
|
||||
|
||||
<hr/>
|
||||
<a id="q-component-or-module"></a>
|
||||
|
||||
{@ q-component-or-module}
|
||||
{@a q-component-or-module}
|
||||
|
||||
## Should I add other providers to a module or a component?
|
||||
|
||||
|
|
@ -395,9 +391,8 @@ not the root `AppComponent`.
|
|||
|
||||
<hr/>
|
||||
|
||||
<a id="q-why-bad"></a>
|
||||
{@a q-why-bad}
|
||||
|
||||
{@ q-why-bad}
|
||||
|
||||
## Why is it bad if a shared module provides a service to a lazy-loaded module?
|
||||
|
||||
|
|
@ -509,13 +504,13 @@ For more information, see [Entry Components](guide/entry-components).
|
|||
## What's the difference between a _bootstrap_ component and an _entry component_?
|
||||
|
||||
A bootstrapped component _is_ an [entry component](guide/ngmodule-faq#q-entry-component-defined)
|
||||
that Angular loads into the DOM during the bootstrap (application launch) process.
|
||||
that Angular loads into the DOM during the bootstrap process (application launch).
|
||||
Other entry components are loaded dynamically by other means, such as with the router.
|
||||
|
||||
The `@NgModule.bootstrap` property tells the compiler that this is an entry component _and_
|
||||
it should generate code to bootstrap the application with this component.
|
||||
|
||||
There's no need to list a component in both the `bootstrap` and `entryComponent` lists,
|
||||
There's no need to list a component in both the `bootstrap` and `entryComponents` lists,
|
||||
although doing so is harmless.
|
||||
|
||||
For more information, see [Entry Components](guide/entry-components).
|
||||
|
|
@ -631,7 +626,7 @@ For more information, see [JavaScript Modules vs. NgModules](guide/ngmodule-vs-j
|
|||
|
||||
<hr/>
|
||||
|
||||
<a id="q-template-reference"></a>
|
||||
{@a q-template-reference}
|
||||
|
||||
## How does Angular find components, directives, and pipes in a template?<br>What is a <i><b>template reference</b></i>?
|
||||
|
||||
|
|
@ -647,9 +642,7 @@ or exported by a module that this module imports.
|
|||
|
||||
<hr/>
|
||||
|
||||
<a id="q-angular-compiler"></a>
|
||||
|
||||
{@ q-angular-compiler}
|
||||
{@a q-angular-compiler}
|
||||
|
||||
## What is the Angular compiler?
|
||||
|
||||
|
|
@ -671,4 +664,3 @@ the Angular compiler incorporates them into compiled component code too.
|
|||
|
||||
`@NgModule` metadata tells the Angular compiler what components to compile for this module and
|
||||
how to link this module with other modules.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,13 +12,13 @@ though they organize it differently, Angular apps rely on both.
|
|||
|
||||
In JavaScript, modules are individual files with JavaScript code in them. To make what’s in them available, you write an export statement, usually after the relevant code, like this:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
export class AppComponent { ... }
|
||||
```
|
||||
|
||||
Then, when you need that file’s code in another file, you import it like this:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
import { AppComponent } from './app.component';
|
||||
```
|
||||
|
||||
|
|
@ -31,27 +31,23 @@ NgModules are classes decorated with `@NgModule`. The `@NgModule` decorator’s
|
|||
|
||||
The `AppModule` generated from the Angular CLI demonstrates both kinds of modules in action:
|
||||
|
||||
```javascript
|
||||
```typescript
|
||||
/* These are JavaScript import statements. Angular doesn’t know anything about these. */
|
||||
import { BrowserModule } from '@angular/platform-browser';
|
||||
import { NgModule } from '@angular/core';
|
||||
import { FormsModule } from '@angular/forms';
|
||||
import { HttpModule } from '@angular/http';
|
||||
|
||||
import { AppComponent } from './app.component';
|
||||
|
||||
/* The @NgModule decorator lets Angular know that this is an NgModule. */
|
||||
@NgModule({
|
||||
declarations: [
|
||||
declarations: [
|
||||
AppComponent
|
||||
],
|
||||
imports: [ /* These are NgModule imports. */
|
||||
BrowserModule,
|
||||
FormsModule,
|
||||
HttpModule
|
||||
],
|
||||
providers: [],
|
||||
bootstrap: [AppComponent]
|
||||
],
|
||||
imports: [ /* These are NgModule imports. */
|
||||
BrowserModule
|
||||
],
|
||||
providers: [],
|
||||
bootstrap: [AppComponent]
|
||||
})
|
||||
export class AppModule { }
|
||||
```
|
||||
|
|
@ -76,5 +72,3 @@ For more information on NgModules, see:
|
|||
* [Bootstrapping](guide/bootstrapping).
|
||||
* [Frequently used modules](guide/frequent-ngmodules).
|
||||
* [Providers](guide/providers).
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -8,12 +8,12 @@ A basic understanding of the following concepts:
|
|||
|
||||
<hr>
|
||||
|
||||
**NgModules** configure the injector and the compiler and help organize related things together
|
||||
**NgModules** configure the injector and the compiler and help organize related things together.
|
||||
|
||||
An NgModule is a class marked by the `@NgModule` decorator.
|
||||
`@NgModule` takes a metadata object that describes how to compile a component's templates and how to create an injector at runtime.
|
||||
`@NgModule` takes a metadata object that describes how to compile a component's template and how to create an injector at runtime.
|
||||
It identifies the module's own components, directives, and pipes,
|
||||
making some of them public, through the `exports` property public, so that external components can use them.
|
||||
making some of them public, through the `exports` property, so that external components can use them.
|
||||
`@NgModule` can also add service providers to the application dependency injectors.
|
||||
|
||||
For an example app showcasing all the techniques that NgModules related pages
|
||||
|
|
@ -25,7 +25,7 @@ section.
|
|||
|
||||
Modules are a great way to organize an application and extend it with capabilities from external libraries.
|
||||
|
||||
Angular libraries are NgModules, such as `FormsModule`, `HttpModule`, and `RouterModule`.
|
||||
Angular libraries are NgModules, such as `FormsModule`, `HttpClientModule`, and `RouterModule`.
|
||||
Many third-party libraries are available as NgModules such as
|
||||
<a href="https://material.angular.io/">Material Design</a>,
|
||||
<a href="http://ionicframework.com/">Ionic</a>, and
|
||||
|
|
|
|||
|
|
@ -21,15 +21,17 @@ Consider the following module from an imaginary app:
|
|||
|
||||
|
||||
```typescript
|
||||
import { NgModule } from '@angular/core';
|
||||
import { CommonModule } from '@angular/common';
|
||||
import { NgModule } from '@angular/core';
|
||||
import { FormsModule } from '@angular/forms';
|
||||
import { CustomerComponent } from './customer.component';
|
||||
import { NewItemDirective } from './new-item.directive';
|
||||
import { OrdersPipe } from './orders.pipe';
|
||||
import { NewItemDirective } from './newitem.directive';
|
||||
|
||||
@NgModule({
|
||||
imports: [ CommonModule ],
|
||||
declarations: [ OrdersPipe, NewItemDirective ],
|
||||
exports: [ OrdersPipe, NewItemDirective,
|
||||
declarations: [ CustomerComponent, NewItemDirective, OrdersPipe ],
|
||||
exports: [ CustomerComponent, NewItemDirective, OrdersPipe,
|
||||
CommonModule, FormsModule ]
|
||||
})
|
||||
export class SharedModule { }
|
||||
|
|
@ -56,9 +58,9 @@ having to import it directly into the `@NgModule` decorator.
|
|||
|
||||
There is an important distinction between using another module's component and
|
||||
using a service from another module. Import modules when you want to use
|
||||
directives, pipes, and components. Importing a module with services means that you will have a new instance of that service, which typically is not what you need, (typically one wants to reuse an existing service.) Use module imports to control service instantiation.
|
||||
directives, pipes, and components. Importing a module with services means that you will have a new instance of that service, which typically is not what you need (typically one wants to reuse an existing service). Use module imports to control service instantiation.
|
||||
|
||||
The most common way to get a hold of sharedservices is through Angular
|
||||
The most common way to get a hold of shared services is through Angular
|
||||
[dependency injection](guide/dependency-injection), rather than through the module system (importing a module will result in a new service instance, which is not a typical usage).
|
||||
|
||||
To read about sharing services, see [Providers](guide/providers).
|
||||
|
|
@ -70,7 +72,4 @@ To read about sharing services, see [Providers](guide/providers).
|
|||
|
||||
You may also be interested in the following:
|
||||
* [Providers](guide/providers).
|
||||
* [Types of Modules](guide/module-types).
|
||||
|
||||
|
||||
|
||||
* [Types of Feature Modules](guide/module-types).
|
||||
|
|
|
|||
|
|
@ -14,7 +14,13 @@ showcasing all the documented features of NgModules.
|
|||
|
||||
## Providing a singleton service
|
||||
|
||||
An injector created from a module definition will have services which are singletons with respect to that injector. To control the lifetime of services, one controls the creation and destruction of injectors. For example, a route will have an associated module. When the route is activated, an injector is created from that module as a child of the current injector. When you navigate away from the route, the injector is destroyed. This means that services declared in a route module will have a lifetime equal to that of the route. Similarly, services provided in an application module will have the same lifetime of the application, hence singleton.
|
||||
An injector created from a module definition will have services which are singletons with respect to
|
||||
that injector. To control the lifetime of services, one controls the creation and destruction of
|
||||
injectors. For example, a route will have an associated module. When the route is activated, an
|
||||
injector is created from that module as a child of the current injector. When you navigate away from
|
||||
the route, the injector is destroyed. This means that services declared in a route module will have
|
||||
a lifetime equal to that of the route. Similarly, services provided in an application module will
|
||||
have the same lifetime of the application, hence singleton.
|
||||
|
||||
The following example module is called, as a convention, `CoreModule`. This use of `@NgModule` creates organizational infrastructure and gives you
|
||||
a way of providing services from a designated NgModule.
|
||||
|
|
@ -47,8 +53,8 @@ As a general rule, import modules with providers _exactly once_,
|
|||
preferably in the application's _root module_.
|
||||
That's also usually the best place to configure, wrap, and override them.
|
||||
|
||||
For more detailed information on services, see
|
||||
[part 5](tutorial/toh-pt4) of the [Tour of Heroes tutorial](tutorial).
|
||||
For more detailed information on services, see the [Services](tutorial/toh-pt4) chapter of the
|
||||
[Tour of Heroes tutorial](tutorial).
|
||||
|
||||
|
||||
## `forRoot()`
|
||||
|
|
@ -171,9 +177,6 @@ Here are the two files in their entirety for reference:
|
|||
## More on NgModules
|
||||
|
||||
You may also be interested in:
|
||||
* [Sharing NgModules](guide/singleton-services), which elaborates on the concepts covered on this page.
|
||||
* [Sharing Modules](guide/sharing-ngmodules), which elaborates on the concepts covered on this page.
|
||||
* [Lazy Loading Modules](guide/lazy-loading-ngmodules).
|
||||
* [NgModule FAQ](guide/ngmodule-faq).
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -240,8 +240,8 @@
|
|||
},
|
||||
{
|
||||
"url": "guide/module-types",
|
||||
"title": "Types of NgModules",
|
||||
"tooltip": "Description of the different types of feature module."
|
||||
"title": "Types of Feature Modules",
|
||||
"tooltip": "Description of the different types of feature modules."
|
||||
},
|
||||
{
|
||||
"url": "guide/entry-components",
|
||||
|
|
|
|||
Loading…
Reference in New Issue