honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: edit Getting Started start/index.md copy and headers (#39583) 

PR Close #39583
This commit is contained in:
Kapunahele Wong 2020-11-05 16:11:47 -05:00 committed by Jessica Janiuk
parent 93d689ffa8
commit 9a2f83b826
1 changed files with 194 additions and 277 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

353
aio/content/start/index.md
View File

@ -1,235 +1,169 @@
# Getting started with a basic Angular app
# Getting started with Angular
Welcome to Angular!
This tutorial introduces you to the essentials of Angular by walking you through a simple e-commerce site with a catalog, shopping cart, and check-out form.
To help you get started right away, this guide uses a simple ready-made application that you can examine and modify interactively (without having to [set up a local work environment](guide/setup-local "Setup guide")).
This tutorial introduces you to the essentials of Angular by walking you through building an e-commerce site with a catalog, shopping cart, and check-out form.
<div class="callout is-helpful">
<header>New to web development?</header>
To help you get started right away, this tutorial uses a ready-made application that you can examine and modify interactively on [Stackblitz](https://stackblitz.com/)&mdash;without having to [set up a local work environment](guide/setup-local "Setup guide").
StackBlitz is a browser-based development environment where you can create, save, and share projects using a variety of technologies.
There are many resources to complement the Angular docs. Mozilla's MDN docs include both [HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML "Learning HTML: Guides and tutorials") and [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript "JavaScript") introductions. [TypeScript's docs](https://www.typescriptlang.org/docs/home.html "TypeScript documentation") include a 5-minute tutorial. Various online course platforms, such as [Udemy](https://www.udemy.com/ "Udemy online courses") and [Codecademy](https://www.codecademy.com/ "Codecademy online courses"), also cover web development basics.
## Prerequisites
To get the most out of this tutorial you should already have a basic understanding of the following.
* [HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML "Learning HTML: Guides and tutorials")
* [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript "JavaScript")
* [TypeScript](https://www.typescriptlang.org/docs/home.html "TypeScript documentation")
<hr />
{@a components}
## Take a tour of the example application
You build Angular applications with components.
Components define areas of responsibility in the UI that let you reuse sets of UI functionality.
A component consists of three things:
* **A component class** that handles data and functionality.
* **An HTML template** that determines the UI.
* **Component-specific styles** that define the look and feel.
This guide demonstrates building an application with the following components.
* `<app-root>`&mdash;the first component to load and the container for the other components.
* `<app-top-bar>`&mdash;the store name and checkout button.
* `<app-product-list>`&mdash;the product list.
* `<app-product-alerts>`&mdash;a component that contains the application's alerts.
<div class="lightbox">
<img src="generated/images/guide/start/app-components.png" alt="Online store with three components">
</div>
For more information about components, see [Introduction to Components](guide/architecture-components "Introduction to Components and Templates").
{@a new-project}
## Create the sample project
<h4>
<live-example name="getting-started-v0" noDownload>Click here to create the ready-made sample project in StackBlitz.</live-example>
</h4>
To create the sample project, generate the <live-example name="getting-started-v0" noDownload>ready-made sample project in StackBlitz</live-example>.
To save your work:
1. Log into StackBlitz.
1. Fork the project you generated.
1. Save periodically.
In StackBlitz, the preview pane on the right shows the starting state of the example application.
The preview features two areas:
* a top bar with the store name, *My Store*, and a checkout button
* a header for a product list, *Products*
<div class="lightbox">
<img src="generated/images/guide/start/new-app-all.gif" alt="Starter online store app">
<img src="generated/images/guide/start/new-app-all.gif" alt="Starter online store application">
</div>
* The preview pane on the right shows the starting state of the sample Angular app.
It defines a frame with a top bar (containing the store name and checkout icon) and the title for a product list (which will be populated and dynamically updated with data from the application).
The project section on the left shows the source files that make up the application, including the infrastructure and configuration files.
* The project pane on the left shows the source files that make up the application, including all of the infrastructure and configuration files. The currently selected file shows up in the editor pane in the middle.
When you generate the StackBlitz example apps that accompany the tutorials, StackBlitz creates the starter files and mock data for you.
The files you use throughout the tutorial are in the `src` folder.
Before going into the source structure, the next section shows how to fill out the HTML *template* for the product list, using the provided sample data.
This should give you an idea how easy it is to modify and update the page dynamically.
For more information on how to use StackBlitz, see the [StackBlitz documentation](https://developer.stackblitz.com/docs/platform/).
<div class="callout is-helpful">
<header>StackBlitz tips</header>
{@a product-list}
## Create the product list
* Log into StackBlitz so you can save and resume your work.
If you have a GitHub account, you can log into StackBlitz
with that account. In order to save your progress, first
fork the project using the Fork button at the top left,
then you'll be able to save your work to your own StackBlitz
account by clicking the Save button.
* To copy a code example from this tutorial, click the icon
at the top right of the code example box, and then paste the
code snippet from the clipboard into StackBlitz.
* If the StackBlitz preview pane isn't showing what you
expect, save and then click the refresh button.
* StackBlitz is continually improving, so there may be
slight differences in generated code, but the app's
behavior will be the same.
* When you generate the StackBlitz example apps that
accompany the tutorials, StackBlitz creates the starter
files and mock data for you. The files you'll use throughout
the tutorials are in the `src` folder of the StackBlitz
example apps.
</div>
<div class="alert is-important">
If you go directly to the [StackBlitz online development environment](https://stackblitz.com/) and choose to [start a new Angular workspace](https://stackblitz.com/fork/angular), you get a generic stub application, rather than this [illustrative sample](#new-project). Once you have been introduced to the basic concepts here, this can be helpful for working interactively while you are learning Angular.
In actual development you will typically use the [Angular CLI](guide/glossary#command-line-interface-cli "Definition of CLI"), a powerful command-line tool that lets you generate and modify applications. For a full step-by-step guide that shows how to use the CLI to create a new project and all of its parts, see [Tutorial: Tour of Heroes](tutorial).
</div>
{@a template-syntax}
## Template syntax
Angular's template syntax extends HTML and JavaScript.
This section introduces template syntax by enhancing the "Products" area.
<div class="alert is-helpful">
To help you get going, the following steps use predefined product data from the `products.ts` file (already created in StackBlitz example) and methods from the `product-list.component.ts` file.
</div>
In this section, you'll update the application to display a list of products.
You'll use predefined product data from the `products.ts` file and methods from the `product-list.component.ts` file.
This section guides you through editing the HTML, also known as the template.
1. In the `product-list` folder, open the template file `product-list.component.html`.
1. Modify the product list template to display a list of product names.
1. Each product in the list displays the same way, one after another on the page. To iterate over the predefined list of products, put the `*ngFor` directive on a `<div>`, as follows:
1. Add an `*ngFor` structural directive on a `<div>`, as follows.
<code-example header="src/app/product-list/product-list.component.html" path="getting-started/src/app/product-list/product-list.component.2.html" region="ngfor">
</code-example>
With `*ngFor`, the `<div>` repeats for each product in the list.
<div class="alert is-helpful">
Structural directives shape or reshape the DOM's structure, by adding, removing, and manipulating elements.
For more information about structural directives, see [Structural directives](guide/structural-directives).
`*ngFor` is a "structural directive". Structural directives shape or reshape the DOM's structure, typically by adding, removing, and manipulating the elements to which they are attached. Directives with an asterisk, `*`, are structural directives.
</div>
1. To display the names of the products, use the interpolation syntax `{{ }}`. Interpolation renders a property's value as text. Inside the `<div>`, add an `<h3>` to display the interpolation of the product's name property:
1. Inside the `<div>`, add an `<h3>` and `{{ product.name }}`.
The `{{ product.name }}` statement is an example of Angular's interpolation syntax.
Interpolation `{{ }}` lets you render the property value as text.
<code-example path="getting-started/src/app/product-list/product-list.component.2.html" header="src/app/product-list/product-list.component.html" region="interpolation">
</code-example>
The preview pane immediately updates to display the name of each product in the list.
The preview pane updates to display the name of each product in the list.
<div class="lightbox">
<img src="generated/images/guide/start/template-syntax-product-names.png" alt="Product names added to list">
</div>
1. To make each product name a link to product details, add the `<a>` element and set its title to be the product's name by using the property binding `[ ]` syntax, as follows:
1. To make each product name a link to product details, add the `<a>` element around `{{ product.name }}`.
1. Set the title to be the product's name by using the property binding `[ ]` syntax, as follows:
<code-example path="getting-started/src/app/product-list/product-list.component.2.html" header="src/app/product-list/product-list.component.html">
</code-example>
In the preview pane, hold the pointer over a product
name to see the bound name property value, which is
the product name plus the word "details".
Interpolation `{{ }}` lets you render the
property value as text; property binding `[ ]` lets you
use the property value in a template expression.
In the preview pane, hover over a product name to see the bound name property value, which is the product name plus the word "details".
Property binding `[ ]` lets you use the property value in a template expression.
<div class="lightbox">
<img src="generated/images/guide/start/template-syntax-product-anchor.png" alt="Product name anchor text is product name property">
</div>
4. Add the product descriptions. On the `<p>` element, use an `*ngIf` directive so that Angular only creates the `<p>` element if the current product has a description.
1. Add the product descriptions. On a `<p>` element, use an `*ngIf` directive so that Angular only creates the `<p>` element if the current product has a description.
<code-example path="getting-started/src/app/product-list/product-list.component.3.html" header="src/app/product-list/product-list.component.html">
</code-example>
The app now displays the name and description of each product in the list. Notice that the final product does not have a description paragraph. Because the product's description property is empty, Angular doesn't create the `<p>` element&mdash;including the word "Description".
The application now displays the name and description of each product in the list.
Notice that the final product does not have a description paragraph.
Angular doesn't create the `<p>` element because the product's description property is empty.
<div class="lightbox">
<img src="generated/images/guide/start/template-syntax-product-description.png" alt="Product descriptions added to list">
</div>
5. Add a button so users can share a product with friends. Bind the button's `click` event to the `share()` method (in `product-list.component.ts`). Event binding uses a set of parentheses, `( )`, around the event, as in the following `<button>` element:
1. Add a button so users can share a product.
Bind the button's `click` event to the `share()` method in `product-list.component.ts`. Event binding uses a set of parentheses, `( )`, around the event, as in the `(click)` event on the `<button>` element.
<code-example path="getting-started/src/app/product-list/product-list.component.4.html" header="src/app/product-list/product-list.component.html">
</code-example>
Each product now has a "Share" button:
Each product now has a **Share** button.
<div class="lightbox">
<img src="generated/images/guide/start/template-syntax-product-share-button.png" alt="Share button added for each product">
</div>
Test the "Share" button:
Clicking the **Share** button triggers an alert that states, "The product has been shared!".
<div class="lightbox">
<img src="generated/images/guide/start/template-syntax-product-share-alert.png" alt="Alert box indicating product has been shared">
</div>
The app now has a product list and sharing feature.
In the process, you've learned to use five common features of Angular's template syntax:
* `*ngFor`
* `*ngIf`
* Interpolation `{{ }}`
* Property binding `[ ]`
* Event binding `( )`
In editing the template, you have explored some of the most popular features of Angular templates.
For more information, see [Introduction to components and templates](guide/architecture-components#template-syntax "Template Syntax").
{@a passing-data-in}
<div class="alert is-helpful">
For a fuller introduction to Angular's template syntax, see [Introduction to components and templates](guide/architecture-components#template-syntax "Template Syntax").
</div>
{@a components}
## Components
*Components* define areas of responsibility in the user interface, or UI,
that let you reuse sets of UI functionality.
You've already built one with the product list component.
A component consists of three things:
* **A component class** that handles data and functionality. In the previous section, the product data and the `share()` method in the component class handle data and functionality, respectively.
* **An HTML template** that determines the UI. In the previous section, the product list's HTML template displays the name, description, and a "Share" button for each product.
* **Component-specific styles** that define the look and feel.
Though product list does not define any styles, this is where component CSS
resides.
<!--
### Class definition
Let's take a quick look a the product list component's class definition:
1. In the `product-list` directory, open `product-list.component.ts`.
1. Notice the `@Component` decorator. This provides metadata about the component, including its templates, styles, and a selector.
* The `selector` is used to identify the component. The selector is the name you give the Angular component when it is rendered as an HTML element on the page. By convention, Angular component selectors begin with the prefix such as `app-`, followed by the component name.
* The template and style filename also are provided here. By convention each of the component's parts is in a separate file, all in the same directory and with the same prefix.
1. The component definition also includes an exported class, which handles functionality for the component. This is where the product list data and `Share()` method are defined.
### Composition
-->
An Angular application comprises a tree of components, in which each Angular component has a specific purpose and responsibility.
Currently, the example app has three components:
<div class="lightbox">
<img src="generated/images/guide/start/app-components.png" alt="Online store with three components">
</div>
* `app-root` (orange box) is the application shell. This is the first component to load and the parent of all other components. You can think of it as the base page.
* `app-top-bar` (blue background) is the store name and checkout button.
* `app-product-list` (purple box) is the product list that you modified in the previous section.
The next section expands the app's capabilities by adding a new component&mdash;a product alert&mdash;as a child of the product list component.
<div class="alert is-helpful">
For more information about components and how they interact with templates, see [Introduction to Components](guide/architecture-components "Concepts > Introduction to Components and Templates").
</div>
{@a input}
## Input
## Pass data to a child component
Currently, the product list displays the name and description of each product.
The product list component also defines a `products` property that contains imported data for each product from the `products` array in `products.ts`.
The `ProductListComponent` also defines a `products` property that contains imported data for each product from the `products` array in `products.ts`.
The next step is to create a new alert feature that takes a product as an input. The alert checks the product's price, and, if the price is greater than $700, displays a "Notify Me" button that lets users sign up for notifications when the product goes on sale.
The next step is to create a new alert feature that uses product data from the `ProductListComponent`.
The alert checks the product's price, and, if the price is greater than $700, displays a **Notify Me** button that lets users sign up for notifications when the product goes on sale.
1. Create a new product alerts component.
This section walks you through creating a child component, `ProductAlertsComponent` that can receive data from its parent component, `ProductListComponent`.
1. Right click on the `app` folder and use the `Angular Generator` to generate a new component named `product-alerts`.
@ -237,124 +171,107 @@ The next step is to create a new alert feature that takes a product as an input.
<img src="generated/images/guide/start/generate-component.png" alt="StackBlitz command to generate component">
</div>
The generator creates starter files for all three parts of the component:
The generator creates starter files for the three parts of the component:
* `product-alerts.component.ts`
* `product-alerts.component.html`
* `product-alerts.component.css`
1. Open `product-alerts.component.ts`.
The `@Component()` decorator indicates that the following class is a component.
`@Component()` also provides metadata about the component, including its selector, templates, and styles.
<code-example header="src/app/product-alerts/product-alerts.component.ts" path="getting-started/src/app/product-alerts/product-alerts.component.1.ts" region="as-generated"></code-example>
1. Notice the `@Component()` decorator. This indicates that the following class is a component. It provides metadata about the component, including its selector, templates, and styles.
Key features in the `@Component()` are as follows:
* The `selector` identifies the component. The selector is the name you give the Angular component when it is rendered as an HTML element on the page. By convention, Angular component selectors begin with the prefix `app-`, followed by the component name.
* The `selector`, `app-product-alerts`, identifies the component.
By convention, Angular component selectors begin with the prefix `app-`, followed by the component name.
* The template and style filenames reference the component's HTML and CSS.
* The `@Component()` definition also exports the class, `ProductAlertsComponent`, which handles functionality for the component.
* The template and style filenames reference the HTML and CSS files that StackBlitz generates.
1. The component definition also exports the class, `ProductAlertsComponent`, which handles functionality for the component.
1. Set up the new product alerts component to receive a product as input:
1. Import `Input` from `@angular/core`.
1. To set up `ProductAlertsComponent` to receive product data, first import `Input` from `@angular/core`.
<code-example path="getting-started/src/app/product-alerts/product-alerts.component.1.ts" region="imports" header="src/app/product-alerts/product-alerts.component.ts"></code-example>
1. In the `ProductAlertsComponent` class definition, define a property named `product` with an `@Input()` decorator. The `@Input()` decorator indicates that the property value passes in from the component's parent, the product list component.
1. In the `ProductAlertsComponent` class definition, define a property named `product` with an `@Input()` decorator.
The `@Input()` decorator indicates that the property value passes in from the component's parent, `ProductListComponent`.
<code-example path="getting-started/src/app/product-alerts/product-alerts.component.1.ts" region="input-decorator" header="src/app/product-alerts/product-alerts.component.ts"></code-example>
1. Define the view for the new product alert component.
1. Open the `product-alerts.component.html` template and replace the placeholder paragraph with a "Notify Me" button that appears if the product price is over $700.
1. Open `product-alerts.component.html` and replace the placeholder paragraph with a **Notify Me** button that appears if the product price is over $700.
<code-example header="src/app/product-alerts/product-alerts.component.html" path="getting-started/src/app/product-alerts/product-alerts.component.1.html"></code-example>
1. Display the new product alert component as a child of the product list.
1. Open `product-list.component.html`.
1. To include the new component, use its selector, `app-product-alerts`, as you would an HTML element.
1. Pass the current product as input to the component using property binding.
1. To display `ProductAlertsComponent` as a child of `ProductListComponent`, add the selector, `<app-product-alerts>` to `product-list.component.html`.
Pass the current product as input to the component using property binding.
<code-example header="src/app/product-list/product-list.component.html" path="getting-started/src/app/product-list/product-list.component.5.html" region="app-product-alerts"></code-example>
The new product alert component takes a product as input from the product list. With that input, it shows or hides the "Notify Me" button, based on the price of the product. The Phone XL price is over $700, so the "Notify Me" button appears on that product.
The new product alert component takes a product as input from the product list.
With that input, it shows or hides the **Notify Me** button, based on the price of the product.
The Phone XL price is over $700, so the **Notify Me** button appears on that product.
<div class="lightbox">
<img src="generated/images/guide/start/product-alert-button.png" alt="Product alert button added to products over $700">
</div>
<div class="alert is-helpful">
See [Component Interaction](guide/component-interaction "Components & Templates > Component Interaction") for more information about passing data from a parent to child component, intercepting and acting upon a value from the parent, and detecting and acting on changes to input property values.
</div>
{@a output}
## Output
To make the "Notify Me" button work, you need to configure two things:
## Pass data to a parent component
- the product alert component to emit an event when the user clicks "Notify Me"
- the product list component to act on that event
To make the **Notify Me** button work, the child component needs to notify and pass the data to the parent component.
The `ProductAlertsComponent` needs to emit an event when the user clicks **Notify Me** and the `ProductListComponent` needs to respond to the event.
1. Open `product-alerts.component.ts`.
1. Import `Output` and `EventEmitter` from `@angular/core`:
1. In `product-alerts.component.ts`, import `Output` and `EventEmitter` from `@angular/core`.
<code-example header="src/app/product-alerts/product-alerts.component.ts" path="getting-started/src/app/product-alerts/product-alerts.component.ts" region="imports"></code-example>
1. In the component class, define a property named `notify` with an `@Output()` decorator and an instance of `EventEmitter()`. This allows the product alert component to emit an event when the value of the notify property changes.
<div class="alert is-helpful">
When the Angular CLI generates a new component, it includes an empty constructor, the `OnInit` interface, and the `ngOnInit()` method.
Since the following example isn't using them, they are omitted here for brevity.
</div>
1. In the component class, define a property named `notify` with an `@Output()` decorator and an instance of `EventEmitter()`.
Configuring `ProductAlertsComponent` with an `@Output()` allows the `ProductAlertsComponent` to emit an event when the value of the `notify` property changes.
<code-example path="getting-started/src/app/product-alerts/product-alerts.component.ts" header="src/app/product-alerts/product-alerts.component.ts" region="input-output"></code-example>
1. In the product alert template, `product-alerts.component.html`, update the "Notify Me" button with an event binding to call the `notify.emit()` method.
<div class="alert is-helpful">
In new components, the Angular Generator includes an empty `constructor()`, the `OnInit` interface, and the `ngOnInit()` method.
Since these steps don't use them, the following code example omits them for brevity.
</div>
1. In `product-alerts.component.html`, update the **Notify Me** button with an event binding to call the `notify.emit()` method.
<code-example header="src/app/product-alerts/product-alerts.component.html" path="getting-started/src/app/product-alerts/product-alerts.component.html"></code-example>
1. Next, define the behavior that should happen when the user clicks the button. Recall that it's the parent, product list component&mdash;not the product alerts component&mdash;that acts when the child raises the event. In `product-list.component.ts`, define an `onNotify()` method, similar to the `share()` method:
1. Define the behavior that happens when the user clicks the button.
The parent, `ProductListComponent`&mdash;not the `ProductAlertsComponent`&mdash;acts when the child raises the event.
In `product-list.component.ts`, define an `onNotify()` method, similar to the `share()` method.
<code-example header="src/app/product-list/product-list.component.ts" path="getting-started/src/app/product-list/product-list.component.ts" region="on-notify"></code-example>
1. Finally, update the product list component to receive output from the product alerts component.
1. Update the `ProductListComponent` to receive data from the `ProductAlertsComponent`.
In `product-list.component.html`, bind the `app-product-alerts` component (which is what displays the "Notify Me" button) to the `onNotify()` method of the product list component.
In `product-list.component.html`, bind `<app-product-alerts>` to the `onNotify()` method of the product list component.
`<app-product-alerts>` is what displays the **Notify Me** button.
<code-example header="src/app/product-list/product-list.component.html" path="getting-started/src/app/product-list/product-list.component.6.html" region="on-notify"></code-example>
1. Try the "Notify Me" button:
1. Click the **Notify Me** button to trigger an alert which reads, "You will be notified when the product goes on sale".
<div class="lightbox">
<img src="generated/images/guide/start/product-alert-notification.png" alt="Product alert notification confirmation dialog">
</div>
For more information on communication between components, see [Component Interaction](guide/component-interaction "Component interaction").
<div class="alert is-helpful">
<hr />
See [Component Interaction](guide/component-interaction "Components & Templates > Component Interaction") for more information about listening for events from child components, reading child properties or invoking child methods, and using a service for bi-directional communication between components.
{@a whats-next}
</div>
## What's next
In this section, you've created an application that iterates through data and features components that communicate with each other.
{@a next-steps}
## Next steps
To continue exploring Angular and developing this application:
Congratulations! You've completed your first Angular app!
You have a basic online store catalog with a product list, "Share" button, and "Notify Me" button.
You've learned about the foundation of Angular: components and template syntax.
You've also learned how the component class and template interact, and how components communicate with each other.
To continue exploring Angular, choose either of the following options:
* [Continue to the "In-app navigation" section](start/start-routing "Try it: In-app navigation") to create a product details page that can be accessed by clicking a product name and that has its own URL pattern.
* [Skip ahead to the "Deployment" section](start/start-deployment "Try it: Deployment") to move to local development, or deploy your app to Firebase or your own server.
* Continue to [In-app navigation](start/start-routing "Getting started: In-app navigation") to create a product details page.
* Skip ahead to [Deployment](start/start-deployment "Getting started: Deployment") to move to local development, or deploy your app to Firebase or your own server.