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

更新丢失的文件

Browse Source
This commit is contained in:
YuCheng Hu 2021-04-05 13:50:06 -04:00
parent 61bc0853fb
commit 0bc3fd64dc
5 changed files with 357 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
aio/content/guide/contributors-guide-overview.md Normal file
View File

@ -0,0 +1,34 @@
# Content Contributor's Guide
Angular, as an open source project, depends on its community. This dependence is particularly important to the documentation. The more the community contributes to the documentation, the better the documentation becomes, which helps both new and experienced Angular developers.
The topics in this section cover ways in which you can contribute to the Angular documentation set.
## Before you begin
Before you get started with your contributions, we recommend that you review [Contributing to Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md). That topic explains many of the tasks and guidelines you need to know before you make your first pull request.
## Contributing to Angular
<div class="card-container">
<a href="guide/reviewing-content" class="docs-card" title="Reviewing content">
<section>Review content</section>
<p>Keep Angular content up-to-date by reviewing topics for accuracy.</p>
<p class="card-footer">Help keep content up to date</p>
</a>
<a href="guide/updating-search-keywords" class="docs-card" title="Updating search keywords">
<section>Update search keywords</section>
<p>Help Angular developers by improving the search keywords for existing topics.</p>
<p class="card-footer">Improve documentation search</p>
</a>
<a href="guide/updating-content-github-ui" class="docs-card" title="Updating content through GitHub">
<section>Update content through GitHub</section>
<p>Learn how to make documentation changes through the GitHub UI.</p>
<p class="card-footer">Contribute to Angular in your browser</p>
</a>
<a href="guide/docs-style-guide" class="docs-card" title="Documentation Style Guide">
<section>Documentation style guide</section>
<p>Review the syntax and styles used within the Angular documentation set.</p>
<p class="card-footer">Get to know the writing style</p>
</a>
</div>

41
aio/content/guide/reviewing-content.md Normal file
View File

@ -0,0 +1,41 @@
# Reviewing Content
Angular developers work best when they have access to accurate and complete documentation. Keeping existing content up-to-date is an essential part of ensuring that all developers have a great documentation experience.
This topic describes how you can help keep Angular content up-to-date by reviewing content.
## Before you begin
You can review content even if you've never contributed to Angular before. However, you may find it helpful to have the [Contributing to Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md) guide available if you're filing your first pull request in the repository.
## Reviewing content (`@reviewed`)
All of the task-based guides, tutorials, and conceptual topics that you find on Angular.io support a `@reviewed` tag. When present, this tag is followed by the date representing when a given topic was reviewed for accuracy and completeness. On the published topic, this reviewed information appears at the bottom of the topic; for example, `Last reviewed on` followed by the day of the week, month, day, and year.
<div class="lightbox">
<img src="generated/images/guide/contributors-guide/last-reviewed.png" alt="Example of the last reviewed date specifying the day of the week, the month, the date, and the year on a page footer.">
</div>
This reviewed date indicates when someone last reviewed the topic to ensure that its contents were accurate.
You can review a topic using either the GitHub user interface or in an editor on your local machine. You can also review any topic that you like. Previous experience in the subject of the topic is helpful, but not required.
**To review a topic:**
1. Navigate to the topic that you want to review.
1. Locate the last reviewed date at the bottom of the topic and verify that the topic meets the [review criteria](#review-criteria).
If the topic does not have a last reviewed date, you are welcome to add it to the topic. To add a date, use the `YYYY-MM-DD` date format. Example:
`@reviewed 2021-03-23`
1. Read through the topic.
1. If the topic requires an update, either [file an issue](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#submit-issue) that describes the update required, or [create a pull request](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#submit-pr) with the update.
1. Update the `@reviewed` tag, either through the [GitHub user interface](guide/updating-content-github-ui) or through Angular's [standard pull request process](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#submit-pr).
{@a review-criteria}
### Review criteria
In general, topics should be reviewed either every six months, or around every major release.

37
aio/content/guide/updating-content-github-ui.md Normal file
View File

@ -0,0 +1,37 @@
# Updating topics through the GitHub user interface
This topic describes how to submit pull requests to the Angular repository using GitHub's user interface. If you are unfamiliar with [Git](https://git-scm.com/), you might find this process easier for making changes.
<div class="alert is-important">
Using the GitHub user interface for updates is recommended only for small changes to one file at a time, such as fixing typos, [updating the review date](guide/reviewing-content) or [updating search keywords](guide/updating-search-keywords).
</div>
**To update a topic through the GitHub user interface:**
1. Navigate to the topic for which you want to file a pull request.
1. Click the edit icon at the top of the topic.
<div class="lightbox">
<img src="generated/images/guide/contributors-guide/edit-icon.png" alt="The edit icon for an Angular topic.">
</div>
A GitHub page appears, displaying the source of the topic.
1. Update the topic.
1. At the bottom of the screen, update the **Commit changes** box with a description of the change. Use the format `docs: <short-description-of-change>`, where `<short-description-of-change>` briefly describes your change. Keep the description under 100 characters. For example:
`docs: fix typo in Tour of Heroes pt.1`
1. Verify that the **create new branch** option is selected, then click **Commit changes**.
A Pull Request screen opens.
1. Fill out the form in the Pull Request screen. At a minimum, put an `x` in the **Docs have been added / updated** option and the **Documentation content changes** option.
1. Click **Create pull request**.
At this point, your pull request is added to a list of current requests, which the documentation team reviews weekly.

34
aio/content/guide/updating-search-keywords.md Normal file
View File

@ -0,0 +1,34 @@
# Updating search keywords
In documentation, being able to find the content you need is equally as important as the content itself. In [angular.io](https://angular.io/), users can discover content in several ways, including:
* Organic search results, such as through [google.com](https://google.com/)
* The left navigation bar, also known as sidenav
* Using the search box in the header
You can help improve the documentation experience by adding search keywords to a given topic. Updating search keywords can help bring users to the content they need faster.
## Before you begin
You can update search keywords for a topic even if you've never contributed to Angular before. However, you may find it helpful to have the [Contributing to Angular](https://github.com/angular/angular/blob/master/CONTRIBUTING.md) guide available if you're filing your first pull request in the repository.
## Updating search keywords
To update search keywords:
1. Navigate to the topic to which you want to update search keywords.
1. Decide what search keywords you'd like to add to the topic. For information on how to format keywords, see [Search keywords format](#format).
1. Update the `@searchKeywords` tag, either through the [GitHub user interface](guide/updating-content-github-ui) or through Angular's [standard pull request process](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#submit-pr).
If a topic does not have a `@searchKeywords` tag, you can add it to the end of the topic.
{@a format}
## Search keywords format
You add search keywords to a topic using the `@searchKeywords` tag. This tag takes a set of single words, separated by spaces. The tag and the keywords must be enclosed in curly brackets (`{...}`). For example:
<code-example>
&#123;@searchKeywords route router routing navigation&#125;
</code-example>

211
aio/content/guide/what-is-angular.md Normal file
View File

@ -0,0 +1,211 @@
# What is Angular?
This topic can help you understand Angular: what Angular is, what advantages it provides, and what you might expect as you start to build your applications.
Angular is a development platform, built on [TypeScript](https://www.typescriptlang.org/). As a platform, Angular includes:
* A component-based framework for building scalable web applications
* A collection of well-integrated libraries that cover a wide variety of features, including routing, forms management, client-server communication, and more
* A suite of developer tools to help you develop, build, test, and update your code
With Angular, you're taking advantage of a platform that can scale from single-developer projects to enterprise-level applications. Angular is designed to make updating as easy as possible, so you can take advantage of the latest developments with a minimum of effort. Best of all, the Angular ecosystem consists of a diverse group of over 1.7 million developers, library authors, and content creators.
<div class="alert is-helpful">
See the <live-example name="what-is-angular"></live-example> for a working example containing the code snippets in this guide.
</div>
{@a essentials}
## Angular applications: The essentials
This section explains the core ideas behind Angular. Understanding these ideas can help you design and build your applications more effectively.
{@a components}
### Components
Components are the building blocks that compose an application. A component includes a TypeScript class with a `@Component()` decorator, an HTML template, and styles. The `@Component()` decorator specifies the following Angular-specific information:
* A CSS selector that defines how the component is used in a template. HTML elements in your template that match this selector become instances of the component.
* An HTML template that instructs Angular how to render the component.
* An optional set of CSS styles that define the appearance of the template's HTML elements.
The following is a minimal Angular component.
<code-example
path="what-is-angular/src/app/hello-world/hello-world.component.ts"></code-example>
To use this component, you write the following in a template:
<code-example path="what-is-angular/src/app/app.component.html" region="hello-world-selector"></code-example>
When Angular renders this component, the resulting DOM looks like this:
<code-example path="what-is-angular/src/app/hello-world-example.html" language="html"></code-example>
Angular's component model offers strong encapsulation and an intuitive application structure. Components also make your application easier to unit test and can improve the overall readability of your code.
For more information on what you can do with components, see the [Components](guide/component-overview) section.
{@a templates}
### Templates
Every component has an HTML template that declares how that component renders. You define this template either inline or by file path.
Angular extends HTML with additional syntax that lets you insert dynamic values from your component. Angular automatically updates the rendered DOM when your component’s state changes. One application of this feature is inserting dynamic text, as shown in the following example.
<code-example path="what-is-angular/src/app/hello-world-interpolation/hello-world-interpolation.component.html" region="say-hello"></code-example>
The value for message comes from the component class:
<code-example path="what-is-angular/src/app/hello-world-interpolation/hello-world-interpolation.component.ts"></code-example>
When the application loads the component and its template, the user sees the following:
<code-example language="html">
&lt;p&gt;Hello, World!&lt;/p&gt;
</code-example>
Notice the use of double curly braces--they instruct Angular to interpolate the contents within them.
Angular also supports property bindings, to help you set values for properties and attributes of HTML elements and pass values to your application's presentation logic.
<code-example path="what-is-angular/src/app/hello-world-bindings/hello-world-bindings.component.html" region="bindings"></code-example>
Notice the use of the square brackets--that syntax indicates that you're binding the property or attribute to a value in the component class.
You can also declare event listeners to listen for and respond to user actions such as keystrokes, mouse movements, clicks, and touches. You declare an event listener by specifying the event name in parentheses:
<code-example path="what-is-angular/src/app/hello-world-bindings/hello-world-bindings.component.html" region="event-binding"></code-example>
The preceding example calls a method, which is defined in the component class:
<code-example path="what-is-angular/src/app/hello-world-bindings/hello-world-bindings.component.ts" region="method"></code-example>
The following is an example of interpolation and bindings within an Angular template:
<code-tabs linenums="true">
<code-pane
header="hello-world-bindings.component.ts"
path="what-is-angular/src/app/hello-world-bindings/hello-world-bindings.component.ts">
</code-pane>
<code-pane
header="hello-world-bindings.component.html"
path="what-is-angular/src/app/hello-world-bindings/hello-world-bindings.component.html"
linenums="false">
</code-pane>
</code-tabs>
You can add additional functionality to your templates through the use of [directives](guide/built-in-directives). The most popular directives in Angular are `*ngIf` and `*ngFor`. You can use directives to perform a variety of tasks, such as dynamically modifying the DOM structure. And you can also create your own custom directives to create great user experiences.
The following code is an example of the `*ngIf` directive.
<code-tabs linenums="true">
<code-pane
header="hello-world-ngif.component.ts"
path="what-is-angular/src/app/hello-world-ngif/hello-world-ngif.component.ts">
</code-pane>
<code-pane
header="hello-world-ngif.component.html"
path="what-is-angular/src/app/hello-world-ngif/hello-world-ngif.component.html"
linenums="false">
</code-pane>
</code-tabs>
Angular's declarative templates allow you to cleanly separate your application's logic from its presentation. Templates are based on standard HTML, so they're easy to build, maintain, and update.
For more information on what you can do with templates, see the [Templates](guide/template-syntax) section.
{@a di}
### Dependency injection
Dependency injection allows you to declare the dependencies of your TypeScript classes without taking care of their instantiation. Instead, Angular handles the instantiation for you. This design pattern allows you to write more testable and flexible code. Even though understanding dependency injection is not critical to start using Angular, we strongly recommend it as a best practice and many aspects of Angular take advantage of it to some degree.
To illustrate how dependency injection works, consider the following example. The first file, `logger.service.ts`, defines a `Logger` class. This class contains a `writeCount` function that logs a number to the console.
<code-example path="what-is-angular/src/app/logger.service.ts"></code-example>
Next, the `hello-world-di.component.ts` file defines an Angular component. This component contains a button that uses the `writeCount` function of the Logger class. To access that function, the `Logger` service is injected into the `HelloWorldDI` class by adding `private logger: Logger` to the constructor.
<code-example path="what-is-angular/src/app/hello-world-di/hello-world-di.component.ts"></code-example>
For more information about dependency injection and Angular, see the [Dependency injection in Angular](guide/dependency-injection) section.
{@a cli}
## Angular CLI
The Angular CLI is the fastest, easiest, and recommended way to develop Angular applications. The Angular CLI makes a number of tasks easy. Here are some examples:
<table>
<tr>
<td><a href="cli/build">ng build</a></td>
<td>Compiles an Angular app into an output directory.</td>
</tr>
<tr>
<td><a href="cli/serve">ng serve</a></td>
<td>Builds and serves your application, rebuilding on file changes.</td>
</tr>
<tr>
<td><a href="cli/generate">ng generate</a></td>
<td>Generates or modifies files based on a schematic.</td>
</tr>
<tr>
<td><a href="cli/test">ng test</a></td>
<td>Runs unit tests on a given project.</td>
</tr>
<tr>
<td><a href="cli/e2e">ng e2e</a></td>
<td>Builds and serves an Angular application, then runs end-to-end tests.</td>
</tr>
</table>
You'll find the Angular CLI a valuable tool for building out your applications.
For more information about the Angular CLI, see the [CLI Reference](/cli) section.
{@a 1p-libraries}
## First-party libraries
The section, [Angular applications: The essentials](#essentials), provides a brief overview of a couple of the key architectural elements you'll use when building Angular applications. But the many benefits of Angular really become apparent when your application grows and you want to add additional functions such as site navigation or user input. That's when you can leverage the Angular platform to incorporate one of the many first-party libraries that Angular provides.
Some of the libraries available to you include:
<table>
<tr>
<td><a href="guide/router">Angular Router</a></td>
<td>Advanced client-side navigation and routing based on Angular components. Supports lazy-loading, nested routes, custom path matching, and more.</td>
</tr>
<tr>
<td><a href="guide/forms-overview">Angular Forms</td>
<td>Uniform system for form participation and validation.</td>
<tr>
<td><a href="guide/http">Angular HttpClient</a></td>
<td>Robust HTTP client that can power more advanced client-server communication.</td>
</tr>
<tr>
<td><a href="guide/animations">Angular Animations</a></td>
<td>Rich system for driving animations based on application state.</td>
</tr>
<tr>
<td><a href="guide/service-worker-intro">Angular PWA</a>
<td>Tools for building Progressive Web Applications (PWAs) including a service worker and Web app manifest.</td>
</tr>
<tr>
<td><a href="guide/schematics">Angular Schematics</td>
<td>Automated scaffolding, refactoring, and update tools that simplify development at large scale.</td>
</tr>
</table>
These libraries expand your application's functionality while also allowing you to focus more on the features that make your application unique. And you can add these libraries knowing that they're designed to integrate seamlessly into and update simultaneously with the Angular framework.
These libraries are only required if and when they can help you add functionality to your applications or solve a particular problem.
## Next steps
This topic is intended to give you a brief overview of what Angular is, the advantages it provides, and what you can expect as you start to build your applications.
To see Angular in action, see our [Getting Started](https://angular.io/start) tutorial. This tutorial uses [stackblitz.com](https://stackblitz.com/), so you can explore a working example of Angular without any installation requirements.
To explore Angular's capabilities further, we recommend reading through the sections, Understanding Angular and Developer Guides.
@reviewed 2021-03-08