填寫這份《一分鐘調查》,幫我們(開發組)做得更好!去填寫Home

模組(NgModule)建立指南

Guidelines for creating NgModules

本主題提供了一個概念性的概述,講的是你可以建立不同類別的模組 使用模組化結構來組織程式碼。這些類別並不是一成不變的,而是建議性的。你可能想為其他目的建立模組,或者把其中某些類別的特徵結合在一起。

This topic provides a conceptual overview of the different categories of NgModules you can create in order to organize your code in a modular structure. These categories are not cast in stone—they are suggestions. You may want to create NgModules for other purposes, or combine the characteristics of some of these categories.

模組是組織應用的好辦法,可以讓與特定功能或特性有關的程式碼與其他程式碼分開。可以使用模組把元件指令管道整合成一些內聚的程式碼塊。專注於某項功能或業務領域、工作流程或導航流程、通用工具集,或者一個或多個服務提供者

NgModules are a great way to organize an app and keep code related to a specific functionality or feature separate from other code. Use NgModules to consolidate components, directives, and pipes into cohesive blocks of functionality. Focus each block on a feature or business domain, a workflow or navigation flow, a common collection of utilities, or one or more providers for services.

關於模組的更多資訊,請參閱使用模組組織你的應用

For more about NgModules, see Organizing your app with NgModules.

要獲得模組相關主題中使用的範例應用,參閱現場演練 / 下載範例

For the example app used in NgModules-related topics, see the現場演練 / 下載範例.

模組類別彙總

Summary of NgModule categories

所有的應用都是從引導一個根模組開始的。你可以按照自己喜歡的方式組織其它模組。

All apps start by bootstrapping a root NgModule. You can organize your other NgModules any way you wish.

本主題為下列常見模組類別提供了一些指導:

This topic provides some guidelines for the following general categories of NgModules:

  • 領域模組:領域模組圍繞特性、業務領域或使用者體驗進行組織。

    Domain: A domain NgModule is organized around a feature, business domain, or user experience.

  • 帶路由的模組:模組的最上層元件充當路由器訪問這部分路由時的目的地。

    Routed: The top component of the NgModule acts as the destination of a router navigation route.

  • 路由配置模組:路由配置模組為另一個模組提供路由配置。

    Routing: A routing NgModule provides the routing configuration for another NgModule.

  • 服務模組:服務模組提供實用服務,比如資料訪問和訊息傳遞。

    Service: A service NgModule provides utility services such as data access and messaging.

  • 小部件:小部件模組可以為其它模組提供某些元件、指令或管道。

    Widget: A widget NgModule makes a component, directive, or pipe available to other NgModules.

  • 共享模組:共享模組可以為其它的模組提供元件,指令和管道的集合。

    Shared: A shared NgModule makes a set of components, directives, and pipes available to other NgModules.

下表總結了每個類別的主要特性。

The following table summarizes the key characteristics of each category.

模組

NgModule

可宣告物件

Declarations

提供者

Providers

匯出

Exports

被誰匯入

Imported by

領域模組

Domain

Yes

罕見

Rare

最上層元件

Top component

其它領域模組、根模組

Another domain, AppModule

帶路由的模組

Routed

Yes

罕見

Rare

No

None

路由定義模組

Routing

No

是 (路由守衛)

Yes (Guards)

RouterModule

其它領域模組(為獲取路由定義)

Another domain (for routing)

服務模組

Service

No

Yes

No

AppModule

小部件模組

Widget

Yes

罕見

Rare

Yes

其它領域模組

Another domain

共享模組

Shared

Yes

No

Yes

其它領域模組

Another domain

領域模組

Domain NgModules

使用領域模組來提供專屬於特定功能或應用領域的介面,比如編輯客戶或下單。例子之一是現場演練 / 下載範例中的 ContactModule

Use a domain NgModule to deliver a user experience dedicated to a particular feature or app domain, such as editing a customer or placing an order. One example is ContactModule in the現場演練 / 下載範例.

領域模組用來組織與特定功能有關的程式碼,裡面包含構成此功能的所有元件、路由和範本。領域模組中的最上層元件是該特性或領域的根,是你要匯出的唯一元件。各種私有的支撐子元件都是它的後代。

A domain NgModule organizes the code related to a certain function, containing all of the components, routing, and templates that make up the function. Your top component in the domain NgModule acts as the feature or domain's root, and is the only component you export. Private supporting subcomponents descend from it.

領域模組要匯入到另一個模組中一次並且只能一次,比如一個領域模組,或者一個只包含少量模組的應用的根模組(AppModule)中。

Import a domain NgModule exactly once into another NgModule, such as a domain NgModule, or into the root NgModule (AppModule) of an app that contains only a few NgModules.

領域模組主要由可宣告物件組成,很少會在此提供服務。如果一定要提供,那麼這些服務的生命週期應和該模組的生命週期一致。

Domain NgModules consist mostly of declarations. You rarely include providers. If you do, the lifetime of the provided services should be the same as the lifetime of the NgModule.

關於生命週期的詳細資訊,請參閱“元件生命週期鉤子”

For more information about lifecycles, see Hooking into the component lifecycle.

帶路由的模組

Routed NgModules

所有延遲載入模組都要用帶路由的模組。使用該模組的最上層元件作為路由器導航路由的目標。帶路由的模組不會匯出任何內容,因為它們的元件永遠不會出現在外部元件的範本中。

Use a routed NgModule for all lazy-loaded NgModules. Use the top component of the NgModule as the destination of a router navigation route. Routed NgModules don’t export anything because their components never appear in the template of an external component.

不要把延遲載入的帶路由的模組匯入到另一個模組中,因為這會觸發一個急性載入,從而破壞了延遲載入它的目的。

Don't import a lazy-loaded routed NgModule into another NgModule, as this would trigger an eager load, defeating the purpose of lazy loading.

帶路由的模組很少有提供者,因為你只在需要的時候載入帶路由的模組(例如透過路由導航過來時)。 provider 陣列中列出的服務不可用,因為根注入器不可能預先知道延遲載入的模組。如果你包含了提供者,那麼它們所提供的服務的生命週期應該和該模組的生命週期完全一樣。不要在帶路由的模組及其匯入的相關模組中提供全應用範圍內的單例服務。

Routed NgModules rarely have providers because you load a routed NgModule only when needed (such as for routing). Services listed in the NgModules' provider array would not be available because the root injector wouldn’t know about the lazy-loaded NgModule. If you include providers, the lifetime of the provided services should be the same as the lifetime of the NgModule. Don't provide app-wide singleton services in a routed NgModule or in an NgModule that the routed NgModule imports.

關於服務提供者和延遲載入的帶路由模組的更多資訊,請參閱限制提供者的範圍

For more information about providers and lazy-loaded routed NgModules, see Limiting provider scope.

路由定義模組

Routing NgModules

使用路由定義模組來為領域模組提供路由配置,從而將路由相關的關注點從其伴生領域模組中分離出來。例子之一是現場演練 / 下載範例中的 ContactRoutingModule,它為其伴生領域模組 ContactModule 提供路由。

Use a routing NgModule to provide the routing configuration for a domain NgModule, thereby separating routing concerns from its companion domain NgModule. One example is ContactRoutingModule in the現場演練 / 下載範例, which provides the routing for its companion domain NgModule ContactModule.

關於路由定義的概述和詳細資訊,請參閱應用內導航:路由到檢視

For an overview and details about routing, see In-app navigation: routing to views.

使用路由定義模組來完成如下任務:

Use a routing NgModule to do the following tasks:

  • 定義路由。

    Define routes.

  • 把路由器配置檔案新增到模組的匯入表中。

    Add router configuration to the NgModule's import.

  • 往模組的提供者列表中新增路由守衛和解析器(resolver)提供者。

    Add guard and resolver service providers to the NgModule's providers.

路由定義模組的名字應該和其伴生模組的名字平行,但使用 Routing 字尾。例如, contact.module.ts 中的 ContactModule 有一個位於 contact-routing.module.ts 中的名為 ContactRoutingModule 的路由定義模組。

The name of the routing NgModule should parallel the name of its companion NgModule, using the suffix Routing. For example, ContactModule in contact.module.ts has a routing NgModule named ContactRoutingModule in contact-routing.module.ts.

路由定義模組只能匯入它的伴生模組中。如果伴生模組是根模組 AppModule ,那麼 AppRoutingModule 就會透過其匯入表中的 RouterModule.forRoot(routes) 來新增路由器配置。所有其他的子路由定義模組都會匯入 RouterModule.forChild(routes)

Import a routing NgModule only into its companion NgModule. If the companion NgModule is the root AppModule, the AppRoutingModule adds router configuration to its imports with RouterModule.forRoot(routes). All other routing NgModules are children that import RouterModule.forChild(routes).

在路由定義模組中,要重新匯出 RouterModule,以便其伴生模組中的元件可以訪問路由器指令,比如 RouterLinkRouterOutlet

In your routing NgModule, re-export the RouterModule as a convenience so that components of the companion NgModule have access to router directives such as RouterLink and RouterOutlet.

不要在路由定義模組中使用可宣告物件。元件、指令和管道都是伴生領域模組的責任,而不是路由定義模組的。

Don't use declarations in a routing NgModule. Components, directives, and pipes are the responsibility of the companion domain NgModule, not the routing NgModule.

服務模組

Service NgModules

使用服務模組來提供實用工具服務,比如資料訪問或訊息傳遞。理想的服務模組完全由提供者組成,沒有可宣告物件。 Angular 的 HttpClientModule 是服務模組的一個典範。

Use a service NgModule to provide a utility service such as data access or messaging. Ideal service NgModules consist entirely of providers and have no declarations. Angular's HttpClientModule is a good example of a service NgModule.

只能使用根模組 AppModule 來匯入各種服務模組。

Use only the root AppModule to import service NgModules.

小部件模組

Widget NgModules

使用小部件模組可以把元件、指令或管道提供給外部模組使用。把小部件模組匯入到任何需要在範本使用這些小部件的模組中。很多第三方 UI 元件庫都是作為小部件模組提供的。

Use a widget NgModule to make a component, directive, or pipe available to external NgModules. Import widget NgModules into any NgModules that need the widgets in their templates. Many third-party UI component libraries are provided as widget NgModules.

小部件模組應該完全由可宣告物件組成,其中大部分都是匯出的。服務提供者非常罕見。

A widget NgModule should consist entirely of declarations, most of them exported. It would rarely have providers.

共享模組

Shared NgModules

把常用的指令、管道和元件放到一個模組中,通常叫做 SharedModule,然後在應用的其他部分只需要匯入這個模組就可以了。你可以在領域模組(包括延遲載入模組)中匯入共享模組。例子之一就是現場演練 / 下載範例中的 SharedModule,它提供了自訂管道 AwesomePipeHighlightDirective 指令。

Put commonly used directives, pipes, and components into one NgModule, typically named SharedModule, and then import just that NgModule wherever you need it in other parts of your app. You can import the shared NgModule in your domain NgModules, including lazy-loaded NgModules. One example is SharedModule in the現場演練 / 下載範例, which provides the AwesomePipe custom pipe and HighlightDirective directive.

共享模組不應該包含服務提供者,它所匯入或重新匯出的任何模組也都不應該包含提供者。

Shared NgModules should not include providers, nor should any of its imported or re-exported NgModules include providers.

要了解如何使用共享模組來組織和簡化程式碼,請參閱在應用中使用共享模組

To learn how to use shared modules to organize and streamline your code, see Sharing NgModules in an app.

下一步

Next steps

你可能也對下列內容感興趣:

You may also be interested in the following:

如果你想管理模組的載入以及依賴和服務的使用,參閱下列內容:

If you want to manage NgModule loading and the use of dependencies and services, see the following: