angular-docs-cn/aio/content/tutorial/toh-pt4.md

446 lines
16 KiB
Markdown
Raw Normal View History

2017-11-06 13:02:18 -05:00
# Services
2017-11-06 13:02:18 -05:00
The Tour of Heroes `HeroesComponent` is currently getting and displaying fake data.
2017-11-06 13:02:18 -05:00
After the refactoring in this tutorial, `HeroesComponent` will be lean and focused on supporting the view.
It will also be easier to unit-test with a mock service.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
## Why services
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Components shouldn't fetch or save data directly and they certainly shouldn't knowingly present fake data.
They should focus on presenting data and delegate data access to a service.
2017-11-06 13:02:18 -05:00
In this tutorial, you'll create a `HeroService` that all application classes can use to get heroes.
Instead of creating that service with `new`,
you'll rely on Angular [*dependency injection*](guide/dependency-injection)
to inject it into the `HeroesComponent` constructor.
2017-11-06 13:02:18 -05:00
Services are a great way to share information among classes that _don't know each other_.
You'll create a `MessageService` and inject it in two places:
2017-11-06 13:02:18 -05:00
1. in `HeroService` which uses the service to send a message.
2. in `MessagesComponent` which displays that message.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
## Create the _HeroService_
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Using the Angular CLI, create a service called `hero`.
<code-example language="sh" class="code-shell">
2017-11-06 13:02:18 -05:00
ng generate service hero
</code-example>
The command generates skeleton `HeroService` class in `src/app/hero.service.ts`
The `HeroService` class should look like the following example.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/hero.service.1.ts" region="new"
title="src/app/hero.service.ts (new service)" linenums="false">
</code-example>
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
### _@Injectable()_ services
2017-11-06 13:02:18 -05:00
Notice that the new service imports the Angular `Injectable` symbol and annotates
the class with the `@Injectable()` decorator. This marks the class as one that participates in the _dependency injection system_. The `HeroService` class is going to provide an injectable service, and it can also have its own injected dependencies.
It doesn't have any dependencies yet, but [it will soon](#inject-message-service).
The `@Injectable()` decorator accepts a metadata object for the service, the same way the `@Component()` decorator did for your component classes.
2017-11-06 13:02:18 -05:00
### Get hero data
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
The `HeroService` could get hero data from anywhere&mdash;a web service, local storage, or a mock data source.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Removing data access from components means you can change your mind about the implementation anytime, without touching any components.
They don't know how the service works.
2017-11-06 13:02:18 -05:00
The implementation in _this_ tutorial will continue to deliver _mock heroes_.
2017-11-06 13:02:18 -05:00
Import the `Hero` and `HEROES`.
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/hero.service.ts" region="import-heroes">
</code-example>
2017-11-06 13:02:18 -05:00
Add a `getHeroes` method to return the _mock heroes_.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/hero.service.1.ts" region="getHeroes">
</code-example>
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
{@a provide}
## Provide the `HeroService`
2017-03-31 19:57:13 -04:00
You must make the `HeroService` available to the dependency injection system
2017-11-06 13:02:18 -05:00
before Angular can _inject_ it into the `HeroesComponent`,
as you will do [below](#inject). You do this by registering a _provider_. A provider is something that can create or deliver a service; in this case, it instantiates the `HeroService` class to provide the service.
2017-03-31 19:57:13 -04:00
Now, you need to make sure that the `HeroService` is registered as the provider of this service.
You are registering it with an _injector_, which is the object that is responsible for choosing and injecting the provider where it is required.
By default, the Angular CLI command `ng generate service` registers a provider with the _root injector_ for your service by including provider metadata in the `@Injectable` decorator.
2017-03-31 19:57:13 -04:00
If you look at the `@Injectable()` statement right before the `HeroService` class definition, you can see that the `providedIn` metadata value is 'root':
2017-03-31 19:57:13 -04:00
```
@Injectable({
providedIn: 'root',
})
```
When you provide the service at the root level, Angular creates a single, shared instance of `HeroService` and injects into any class that asks for it.
Registering the provider in the `@Injectable` metadata also allows Angular to optimize an app by removing the service if it turns out not to be used after all.
<div class="l-sub-section">
If you need to, you can register providers at different levels:
in the `HeroesComponent`, in the `AppComponent`, in the `AppModule`.
For instance, you could have told the CLI to provide the service at the module level automatically by appending `--module=app`.
<code-example language="sh" class="code-shell">
ng generate service hero --module=app
</code-example>
To learn more about providers and injectors, see the [Dependency Injection guide](guide/dependency-injection).
</div>
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
The `HeroService` is now ready to plug into the `HeroesComponent`.
2017-03-31 19:57:13 -04:00
<div class="alert is-important">
This is a interim code sample that will allow you to provide and use the `HeroService`. At this point, the code will differ from the `HeroService` in the ["final code review"](#final-code-review).
</div>
2017-11-06 13:02:18 -05:00
## Update `HeroesComponent`
2017-11-06 13:02:18 -05:00
Open the `HeroesComponent` class file.
Delete the `HEROES` import, because you won't need that anymore.
2017-11-06 13:02:18 -05:00
Import the `HeroService` instead.
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/heroes/heroes.component.ts" title="src/app/heroes/heroes.component.ts (import HeroService)" region="hero-service-import">
</code-example>
Replace the definition of the `heroes` property with a simple declaration.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/heroes/heroes.component.ts" region="heroes">
</code-example>
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
{@a inject}
2017-11-06 13:02:18 -05:00
### Inject the `HeroService`
2017-11-06 13:02:18 -05:00
Add a private `heroService` parameter of type `HeroService` to the constructor.
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/heroes/heroes.component.ts" region="ctor">
</code-example>
2017-11-06 13:02:18 -05:00
The parameter simultaneously defines a private `heroService` property and identifies it as a `HeroService` injection site.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
When Angular creates a `HeroesComponent`, the [Dependency Injection](guide/dependency-injection) system
sets the `heroService` parameter to the singleton instance of `HeroService`.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
### Add _getHeroes()_
2017-11-06 13:02:18 -05:00
Create a function to retrieve the heroes from the service.
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/heroes/heroes.component.1.ts" region="getHeroes">
</code-example>
2017-11-06 13:02:18 -05:00
{@a oninit}
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
### Call it in `ngOnInit`
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
While you could call `getHeroes()` in the constructor, that's not the best practice.
2017-11-06 13:02:18 -05:00
Reserve the constructor for simple initialization such as wiring constructor parameters to properties.
The constructor shouldn't _do anything_.
It certainly shouldn't call a function that makes HTTP requests to a remote server as a _real_ data service would.
2017-11-06 13:02:18 -05:00
Instead, call `getHeroes()` inside the [*ngOnInit lifecycle hook*](guide/lifecycle-hooks) and
let Angular call `ngOnInit` at an appropriate time _after_ constructing a `HeroesComponent` instance.
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/heroes/heroes.component.ts" region="ng-on-init">
</code-example>
2017-11-06 13:02:18 -05:00
### See it run
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
After the browser refreshes, the app should run as before,
showing a list of heroes and a hero detail view when you click on a hero name.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
## Observable data
2017-11-06 13:02:18 -05:00
The `HeroService.getHeroes()` method has a _synchronous signature_,
which implies that the `HeroService` can fetch heroes synchronously.
The `HeroesComponent` consumes the `getHeroes()` result
as if heroes could be fetched synchronously.
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/heroes/heroes.component.1.ts" region="get-heroes">
</code-example>
2017-11-06 13:02:18 -05:00
This will not work in a real app.
You're getting away with it now because the service currently returns _mock heroes_.
But soon the app will fetch heroes from a remote server,
which is an inherently _asynchronous_ operation.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
The `HeroService` must wait for the server to respond,
`getHeroes()` cannot return immediately with hero data,
and the browser will not block while the service waits.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
`HeroService.getHeroes()` must have an _asynchronous signature_ of some kind.
2017-11-06 13:02:18 -05:00
It can take a callback. It could return a `Promise`. It could return an `Observable`.
2017-11-06 13:02:18 -05:00
In this tutorial, `HeroService.getHeroes()` will return an `Observable`
in part because it will eventually use the Angular `HttpClient.get` method to fetch the heroes
and [`HttpClient.get()` returns an `Observable`](guide/http).
2017-11-06 13:02:18 -05:00
### Observable _HeroService_
2017-11-06 13:02:18 -05:00
`Observable` is one of the key classes in the [RxJS library](http://reactivex.io/rxjs/).
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
In a [later tutorial on HTTP](tutorial/toh-pt6), you'll learn that Angular's `HttpClient` methods return RxJS `Observable`s.
In this tutorial, you'll simulate getting data from the server with the RxJS `of()` function.
2017-11-06 13:02:18 -05:00
Open the `HeroService` file and import the `Observable` and `of` symbols from RxJS.
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/hero.service.ts"
title="src/app/hero.service.ts (Observable imports)" region="import-observable">
</code-example>
2017-11-06 13:02:18 -05:00
Replace the `getHeroes` method with this one.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/hero.service.ts" region="getHeroes-1"></code-example>
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
`of(HEROES)` returns an `Observable<Hero[]>` that emits _a single value_, the array of mock heroes.
2017-04-10 11:51:13 -04:00
<div class="l-sub-section">
2017-11-06 13:02:18 -05:00
In the [HTTP tutorial](tutorial/toh-pt6), you'll call `HttpClient.get<Hero[]>()` which also returns an `Observable<Hero[]>` that emits _a single value_, an array of heroes from the body of the HTTP response.
2017-04-10 11:51:13 -04:00
</div>
2017-11-06 13:02:18 -05:00
### Subscribe in _HeroesComponent_
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
The `HeroService.getHeroes` method used to return a `Hero[]`.
Now it returns an `Observable<Hero[]>`.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
You'll have to adjust to that difference in `HeroesComponent`.
2017-11-06 13:02:18 -05:00
Find the `getHeroes` method and replace it with the following code
(shown side-by-side with the previous version for comparison)
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-tabs>
2017-03-31 19:57:13 -04:00
<code-pane title="heroes.component.ts (Observable)"
2017-11-06 13:02:18 -05:00
path="toh-pt4/src/app/heroes/heroes.component.ts" region="getHeroes">
</code-pane>
<code-pane title="heroes.component.ts (Original)"
2017-11-06 13:02:18 -05:00
path="toh-pt4/src/app/heroes/heroes.component.1.ts" region="getHeroes">
</code-pane>
2017-11-06 13:02:18 -05:00
</code-tabs>
2017-11-06 13:02:18 -05:00
`Observable.subscribe()` is the critical difference.
2017-11-06 13:02:18 -05:00
The previous version assigns an array of heroes to the component's `heroes` property.
The assignment occurs _synchronously_, as if the server could return heroes instantly
or the browser could freeze the UI while it waited for the server's response.
2017-11-06 13:02:18 -05:00
That _won't work_ when the `HeroService` is actually making requests of a remote server.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
The new version waits for the `Observable` to emit the array of heroes&mdash;
which could happen now or several minutes from now.
Then `subscribe` passes the emitted array to the callback,
which sets the component's `heroes` property.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
This asynchronous approach _will work_ when
the `HeroService` requests heroes from the server.
2017-11-06 13:02:18 -05:00
## Show messages
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
In this section you will
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
* add a `MessagesComponent` that displays app messages at the bottom of the screen.
* create an injectable, app-wide `MessageService` for sending messages to be displayed
* inject `MessageService` into the `HeroService`
* display a message when `HeroService` fetches heroes successfully.
2017-11-06 13:02:18 -05:00
### Create _MessagesComponent_
2017-11-06 13:02:18 -05:00
Use the CLI to create the `MessagesComponent`.
2017-11-06 13:02:18 -05:00
<code-example language="sh" class="code-shell">
ng generate component messages
</code-example>
2017-11-06 13:02:18 -05:00
The CLI creates the component files in the `src/app/messages` folder and declare `MessagesComponent` in `AppModule`.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Modify the `AppComponent` template to display the generated `MessagesComponent`
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example
title = "/src/app/app.component.html"
path="toh-pt4/src/app/app.component.html">
</code-example>
2017-11-06 13:02:18 -05:00
You should see the default paragraph from `MessagesComponent` at the bottom of the page.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
### Create the _MessageService_
2017-11-06 13:02:18 -05:00
Use the CLI to create the `MessageService` in `src/app`.
2017-11-06 13:02:18 -05:00
<code-example language="sh" class="code-shell">
ng generate service message
</code-example>
2017-11-06 13:02:18 -05:00
Open `MessageService` and replace its contents with the following.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example
title = "/src/app/message.service.ts"
path="toh-pt4/src/app/message.service.ts">
</code-example>
2017-11-06 13:02:18 -05:00
The service exposes its cache of `messages` and two methods: one to `add()` a message to the cache and another to `clear()` the cache.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
{@a inject-message-service}
### Inject it into the `HeroService`
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Re-open the `HeroService` and import the `MessageService`.
2017-11-06 13:02:18 -05:00
<code-example
title = "/src/app/hero.service.ts (import MessageService)"
path="toh-pt4/src/app/hero.service.ts" region="import-message-service">
</code-example>
2017-11-06 13:02:18 -05:00
Modify the constructor with a parameter that declares a private `messageService` property.
Angular will inject the singleton `MessageService` into that property
when it creates the `HeroService`.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example
path="toh-pt4/src/app/hero.service.ts" region="ctor">
</code-example>
2017-04-10 11:51:13 -04:00
<div class="l-sub-section">
2017-11-06 13:02:18 -05:00
This is a typical "*service-in-service*" scenario:
you inject the `MessageService` into the `HeroService` which is injected into the `HeroesComponent`.
2017-04-10 11:51:13 -04:00
</div>
2017-11-06 13:02:18 -05:00
### Send a message from `HeroService`
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Modify the `getHeroes` method to send a message when the heroes are fetched.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt4/src/app/hero.service.ts" region="getHeroes">
</code-example>
2017-11-06 13:02:18 -05:00
### Display the message from `HeroService`
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
The `MessagesComponent` should display all messages,
including the message sent by the `HeroService` when it fetches heroes.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Open `MessagesComponent` and import the `MessageService`.
2017-11-06 13:02:18 -05:00
<code-example
title = "/src/app/messages/messages.component.ts (import MessageService)"
path="toh-pt4/src/app/messages/messages.component.ts" region="import-message-service">
</code-example>
2017-11-06 13:02:18 -05:00
Modify the constructor with a parameter that declares a **public** `messageService` property.
Angular will inject the singleton `MessageService` into that property
when it creates the `MessagesComponent`.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example
path="toh-pt4/src/app/messages/messages.component.ts" region="ctor">
</code-example>
2017-11-06 13:02:18 -05:00
The `messageService` property **must be public** because you're about to bind to it in the template.
2017-11-06 13:02:18 -05:00
<div class="alert is-important">
2017-11-06 13:02:18 -05:00
Angular only binds to _public_ component properties.
2017-04-10 11:51:13 -04:00
</div>
2017-11-06 13:02:18 -05:00
### Bind to the _MessageService_
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Replace the CLI-generated `MessagesComponent` template with the following.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example
title = "src/app/messages/messages.component.html"
path="toh-pt4/src/app/messages/messages.component.html">
</code-example>
2017-11-06 13:02:18 -05:00
This template binds directly to the component's `messageService`.
2017-11-06 13:02:18 -05:00
* The `*ngIf` only displays the messages area if there are messages to show.
2017-11-06 13:02:18 -05:00
* An `*ngFor` presents the list of messages in repeated `<div>` elements.
2017-11-06 13:02:18 -05:00
* An Angular [event binding](guide/template-syntax#event-binding) binds the button's click event
to `MessageService.clear()`.
2017-11-06 13:02:18 -05:00
The messages will look better when you add the private CSS styles to `messages.component.css`
as listed in one of the ["final code review"](#final-code-review) tabs below.
2017-11-06 13:02:18 -05:00
The browser refreshes and the page displays the list of heroes.
Scroll to the bottom to see the message from the `HeroService` in the message area.
Click the "clear" button and the message area disappears.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
{@a final-code-review}
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
## Final code review
2017-11-06 13:02:18 -05:00
Here are the code files discussed on this page and your app should look like this <live-example></live-example>.
<code-tabs>
2017-11-06 13:02:18 -05:00
<code-pane title="src/app/hero.service.ts"
path="toh-pt4/src/app/hero.service.ts">
</code-pane>
2017-11-06 13:02:18 -05:00
<code-pane title="src/app/message.service.ts"
path="toh-pt4/src/app/message.service.ts">
</code-pane>
2017-11-06 13:02:18 -05:00
<code-pane title="src/app/heroes/heroes.component.ts"
path="toh-pt4/src/app/heroes/heroes.component.ts">
</code-pane>
2017-11-06 13:02:18 -05:00
<code-pane title="src/app/messages/messages.component.ts"
path="toh-pt4/src/app/messages/messages.component.ts">
</code-pane>
2017-11-06 13:02:18 -05:00
<code-pane title="src/app/messages/messages.component.html"
path="toh-pt4/src/app/messages/messages.component.html">
</code-pane>
2017-11-06 13:02:18 -05:00
<code-pane title="src/app/messages/messages.component.css"
path="toh-pt4/src/app/messages/messages.component.css">
</code-pane>
<code-pane title="src/app/app.module.ts"
path="toh-pt4/src/app/app.module.ts">
</code-pane>
2017-11-06 13:02:18 -05:00
<code-pane title="src/app/app.component.html"
path="toh-pt4/src/app/app.component.html">
</code-pane>
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
</code-tabs>
2017-03-31 19:57:13 -04:00
## Summary
2017-11-06 13:02:18 -05:00
* You refactored data access to the `HeroService` class.
* You registered the `HeroService` as the _provider_ of its service at the root level so that it can be injected anywhere in the app.
2017-11-06 13:02:18 -05:00
* You used [Angular Dependency Injection](guide/dependency-injection) to inject it into a component.
* You gave the `HeroService` _get data_ method an asynchronous signature.
* You discovered `Observable` and the RxJS _Observable_ library.
* You used RxJS `of()` to return an observable of mock heroes (`Observable<Hero[]>`).
2017-11-06 13:02:18 -05:00
* The component's `ngOnInit` lifecycle hook calls the `HeroService` method, not the constructor.
* You created a `MessageService` for loosely-coupled communication between classes.
* The `HeroService` injected into a component is created with another injected service,
`MessageService`.