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

257 lines
9.3 KiB
Markdown
Raw Normal View History

2017-11-06 13:02:18 -05:00
# The Hero Editor
2017-11-06 13:02:18 -05:00
The application now has a basic title.
Next you will create a new component to display hero information
and place that component in the application shell.
2017-11-06 13:02:18 -05:00
## Create the heroes component
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Using the Angular CLI, generate a new component named `heroes`.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-example language="sh" class="code-shell">
ng generate component heroes
</code-example>
The CLI creates a new folder, `src/app/heroes/`, and generates
the four files of the `HeroesComponent`.
2017-11-06 13:02:18 -05:00
The `HeroesComponent` class file is as follows:
2017-11-06 13:02:18 -05:00
<code-example
path="toh-pt1/src/app/heroes/heroes.component.ts" region="v1"
header="app/heroes/heroes.component.ts (initial version)" linenums="false">
2017-11-06 13:02:18 -05:00
</code-example>
2017-11-06 13:02:18 -05:00
You always import the `Component` symbol from the Angular core library
and annotate the component class with `@Component`.
2017-11-06 13:02:18 -05:00
`@Component` is a decorator function that specifies the Angular metadata for the component.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
The CLI generated three metadata properties:
2017-03-31 19:57:13 -04:00
1. `selector`&mdash; the component's CSS element selector
2017-11-06 13:02:18 -05:00
1. `templateUrl`&mdash; the location of the component's template file.
1. `styleUrls`&mdash; the location of the component's private CSS styles.
2017-11-06 13:02:18 -05:00
{@a selector}
2017-11-06 13:02:18 -05:00
The [CSS element selector](https://developer.mozilla.org/en-US/docs/Web/CSS/Type_selectors),
`'app-heroes'`, matches the name of the HTML element that identifies this component within a parent component's template.
2017-03-31 19:57:13 -04:00
The `ngOnInit` is a [lifecycle hook](guide/lifecycle-hooks#oninit).
2017-11-06 13:02:18 -05:00
Angular calls `ngOnInit` shortly after creating a component.
It's a good place to put initialization logic.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Always `export` the component class so you can `import` it elsewhere ... like in the `AppModule`.
2017-11-06 13:02:18 -05:00
### Add a _hero_ property
2017-11-06 13:02:18 -05:00
Add a `hero` property to the `HeroesComponent` for a hero named "Windstorm."
2017-03-31 19:57:13 -04:00
<code-example path="toh-pt1/src/app/heroes/heroes.component.ts" region="add-hero" header="heroes.component.ts (hero property)" linenums="false">
</code-example>
2017-11-06 13:02:18 -05:00
### Show the hero
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Open the `heroes.component.html` template file.
Delete the default text generated by the Angular CLI and
replace it with a data binding to the new `hero` property.
2017-03-31 19:57:13 -04:00
<code-example path="toh-pt1/src/app/heroes/heroes.component.1.html" header="heroes.component.html" region="show-hero-1" linenums="false">
</code-example>
2017-11-06 13:02:18 -05:00
## Show the _HeroesComponent_ view
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
To display the `HeroesComponent`, you must add it to the template of the shell `AppComponent`.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Remember that `app-heroes` is the [element selector](#selector) for the `HeroesComponent`.
So add an `<app-heroes>` element to the `AppComponent` template file, just below the title.
<code-example path="toh-pt1/src/app/app.component.html" header="src/app/app.component.html" linenums="false">
</code-example>
2017-11-06 13:02:18 -05:00
Assuming that the CLI `ng serve` command is still running,
the browser should refresh and display both the application title and the hero name.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
## Create a Hero class
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
A real hero is more than a name.
2017-11-06 13:02:18 -05:00
Create a `Hero` class in its own file in the `src/app` folder.
Give it `id` and `name` properties.
<code-example path="toh-pt1/src/app/hero.ts" header="src/app/hero.ts" linenums="false">
2017-11-06 13:02:18 -05:00
</code-example>
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Return to the `HeroesComponent` class and import the `Hero` class.
2017-11-06 13:02:18 -05:00
Refactor the component's `hero` property to be of type `Hero`.
Initialize it with an `id` of `1` and the name `Windstorm`.
2017-11-06 13:02:18 -05:00
The revised `HeroesComponent` class file should look like this:
2017-11-06 13:02:18 -05:00
<code-example path="toh-pt1/src/app/heroes/heroes.component.ts" linenums="false"
header= "src/app/heroes/heroes.component.ts">
2017-11-06 13:02:18 -05:00
</code-example>
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
The page no longer displays properly because you changed the hero from a string to an object.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
## Show the hero object
2017-11-06 13:02:18 -05:00
Update the binding in the template to announce the hero's name
and show both `id` and `name` in a details layout like this:
2017-11-06 13:02:18 -05:00
<code-example
path="toh-pt1/src/app/heroes/heroes.component.1.html"
region="show-hero-2"
header="heroes.component.html (HeroesComponent's template)" linenums="false">
2017-11-06 13:02:18 -05:00
</code-example>
The browser refreshes and displays the hero's information.
2017-11-06 13:02:18 -05:00
## Format with the _UppercasePipe_
2017-11-06 13:02:18 -05:00
Modify the `hero.name` binding like this.
<code-example
path="toh-pt1/src/app/heroes/heroes.component.html"
region="pipe">
</code-example>
2017-11-06 13:02:18 -05:00
The browser refreshes and now the hero's name is displayed in capital letters.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
The word `uppercase` in the interpolation binding,
right after the pipe operator ( | ),
activates the built-in `UppercasePipe`.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
[Pipes](guide/pipes) are a good way to format strings, currency amounts, dates and other display data.
Angular ships with several built-in pipes and you can create your own.
2017-11-06 13:02:18 -05:00
## Edit the hero
2017-11-06 13:02:18 -05:00
Users should be able to edit the hero name in an `<input>` textbox.
2017-11-06 13:02:18 -05:00
The textbox should both _display_ the hero's `name` property
and _update_ that property as the user types.
That means data flow from the component class _out to the screen_ and
from the screen _back to the class_.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
To automate that data flow, setup a two-way data binding between the `<input>` form element and the `hero.name` property.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
### Two-way binding
2017-11-06 13:02:18 -05:00
Refactor the details area in the `HeroesComponent` template so it looks like this:
<code-example path="toh-pt1/src/app/heroes/heroes.component.1.html" region="name-input" header="src/app/heroes/heroes.component.html (HeroesComponent's template)" linenums="false">
</code-example>
2017-11-06 13:02:18 -05:00
**[(ngModel)]** is Angular's two-way data binding syntax.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Here it binds the `hero.name` property to the HTML textbox so that data can flow _in both directions:_ from the `hero.name` property to the textbox, and from the textbox back to the `hero.name`.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
### The missing _FormsModule_
2017-11-06 13:02:18 -05:00
Notice that the app stopped working when you added `[(ngModel)]`.
2017-11-06 13:02:18 -05:00
To see the error, open the browser development tools and look in the console
for a message like
2017-11-06 13:02:18 -05:00
<code-example language="sh" class="code-shell">
Template parse errors:
Can't bind to 'ngModel' since it isn't a known property of 'input'.
</code-example>
2017-11-06 13:02:18 -05:00
Although `ngModel` is a valid Angular directive, it isn't available by default.
2017-11-06 13:02:18 -05:00
It belongs to the optional `FormsModule` and you must _opt-in_ to using it.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
## _AppModule_
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Angular needs to know how the pieces of your application fit together
and what other files and libraries the app requires.
This information is called _metadata_
2017-11-06 13:02:18 -05:00
Some of the metadata is in the `@Component` decorators that you added to your component classes.
Other critical metadata is in [`@NgModule`](guide/ngmodules) decorators.
The most important `@NgModule` decorator annotates the top-level **AppModule** class.
2017-11-06 13:02:18 -05:00
The Angular CLI generated an `AppModule` class in `src/app/app.module.ts` when it created the project.
This is where you _opt-in_ to the `FormsModule`.
2017-11-06 13:02:18 -05:00
### Import _FormsModule_
2017-11-06 13:02:18 -05:00
Open `AppModule` (`app.module.ts`) and import the `FormsModule` symbol from the `@angular/forms` library.
<code-example path="toh-pt1/src/app/app.module.ts" header="app.module.ts (FormsModule symbol import)"
2017-11-06 13:02:18 -05:00
region="formsmodule-js-import">
</code-example>
2017-11-06 13:02:18 -05:00
Then add `FormsModule` to the `@NgModule` metadata's `imports` array, which contains a list of external modules that the app needs.
2017-03-31 19:57:13 -04:00
<code-example path="toh-pt1/src/app/app.module.ts" header="app.module.ts ( @NgModule imports)"
2017-11-06 13:02:18 -05:00
region="ng-imports">
</code-example>
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
When the browser refreshes, the app should work again. You can edit the hero's name and see the changes reflected immediately in the `<h2>` above the textbox.
2017-11-06 13:02:18 -05:00
### Declare _HeroesComponent_
Every component must be declared in _exactly one_ [NgModule](guide/ngmodules).
2017-11-06 13:02:18 -05:00
_You_ didn't declare the `HeroesComponent`.
So why did the application work?
2017-11-06 13:02:18 -05:00
It worked because the Angular CLI declared `HeroesComponent` in the `AppModule` when it generated that component.
2017-11-06 13:02:18 -05:00
Open `src/app/app.module.ts` and find `HeroesComponent` imported near the top.
<code-example path="toh-pt1/src/app/app.module.ts" region="heroes-import" >
</code-example>
2017-11-06 13:02:18 -05:00
The `HeroesComponent` is declared in the `@NgModule.declarations` array.
<code-example path="toh-pt1/src/app/app.module.ts" region="declarations">
</code-example>
2017-11-06 13:02:18 -05:00
Note that `AppModule` declares both application components, `AppComponent` and `HeroesComponent`.
2017-11-06 13:02:18 -05:00
## Final code review
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
Your app should look like this <live-example></live-example>. Here are the code files discussed on this page.
2017-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
<code-tabs>
<code-pane header="src/app/heroes/heroes.component.ts" path="toh-pt1/src/app/heroes/heroes.component.ts">
2017-11-06 13:02:18 -05:00
</code-pane>
<code-pane header="src/app/heroes/heroes.component.html" path="toh-pt1/src/app/heroes/heroes.component.html">
2017-11-06 13:02:18 -05:00
</code-pane>
<code-pane header="src/app/app.module.ts"
2017-11-06 13:02:18 -05:00
path="toh-pt1/src/app/app.module.ts">
</code-pane>
2017-03-31 19:57:13 -04:00
<code-pane header="src/app/app.component.ts" path="toh-pt1/src/app/app.component.ts">
2017-11-06 13:02:18 -05:00
</code-pane>
2017-03-31 19:57:13 -04:00
<code-pane header="src/app/app.component.html" path="toh-pt1/src/app/app.component.html">
2017-11-06 13:02:18 -05:00
</code-pane>
<code-pane header="src/app/hero.ts"
2017-11-06 13:02:18 -05:00
path="toh-pt1/src/app/hero.ts">
</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-03-31 19:57:13 -04:00
2017-11-06 13:02:18 -05:00
* You used the CLI to create a second `HeroesComponent`.
* You displayed the `HeroesComponent` by adding it to the `AppComponent` shell.
* You applied the `UppercasePipe` to format the name.
* You used two-way data binding with the `ngModel` directive.
* You learned about the `AppModule`.
* You imported the `FormsModule` in the `AppModule` so that Angular would recognize and apply the `ngModel` directive.
* You learned the importance of declaring components in the `AppModule`
and appreciated that the CLI declared it for you.