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

docs: Edits to remove jargon (#42029) 

PR Close #42029
This commit is contained in:
Teri Glover 2021-05-10 19:48:18 +00:00 committed by Zach Arend
parent 850028d000
commit 8109cba576
8 changed files with 103 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
aio/content/guide/ajs-quick-reference.md
View File

@ -190,7 +190,7 @@ The following are some of the key AngularJS built-in directives and their equiva
The application startup process is called **bootstrapping**. The application startup process is called **bootstrapping**.
Although you can bootstrap an AngularJS app in code, Although you can bootstrap an AngularJS application in code,
many applications bootstrap declaratively with the `ng-app` directive, many applications bootstrap declaratively with the `ng-app` directive,
giving it the name of the application's module (`movieHunter`). giving it the name of the application's module (`movieHunter`).
</td> </td>
@ -207,7 +207,7 @@ The following are some of the key AngularJS built-in directives and their equiva
Angular doesn't have a bootstrap directive. Angular doesn't have a bootstrap directive.
To launch the app in code, explicitly bootstrap the application's root module (`AppModule`) To launch the application in code, explicitly bootstrap the application's root module (`AppModule`)
in `main.ts` in `main.ts`
and the application's root component (`AppComponent`) in `app.module.ts`. and the application's root component (`AppComponent`) in `app.module.ts`.
</td> </td>
@ -691,9 +691,9 @@ The following are some of the key AngularJS built-in directives and their equiva
In this example, if `favoriteHero` is not set, the `ngSwitch` value is `null` In this example, if `favoriteHero` is not set, the `ngSwitch` value is `null`
and `*ngSwitchDefault` displays, "Please enter ...". and `*ngSwitchDefault` displays, "Please enter ...".
If `favoriteHero` is set, the app checks the movie hero by calling a component method. If `favoriteHero` is set, the application checks the movie hero by calling a component method.
If that method returns `true`, the app selects `*ngSwitchCase="true"` and displays: "Excellent choice!" If that method returns `true`, the application selects `*ngSwitchCase="true"` and displays: "Excellent choice!"
If that methods returns `false`, the app selects `*ngSwitchCase="false"` and displays: "No movie, sorry!" If that methods returns `false`, the application selects `*ngSwitchCase="false"` and displays: "No movie, sorry!"
The (*) before `ngSwitchCase` and `ngSwitchDefault` is required in this example. The (*) before `ngSwitchCase` and `ngSwitchDefault` is required in this example.

16
aio/content/guide/deprecations.md
View File

@ -3,7 +3,7 @@
Angular strives to balance innovation and stability. Angular strives to balance innovation and stability.
Sometimes, APIs and features become obsolete and need to be removed or replaced so that Angular can stay current with new best practices, changing dependencies, or changes in the (web) platform itself. Sometimes, APIs and features become obsolete and need to be removed or replaced so that Angular can stay current with new best practices, changing dependencies, or changes in the (web) platform itself.
To make these transitions as easy as possible, we deprecate APIs and features for a period of time before removing them. This gives you time to update your apps to the latest APIs and best practices. To make these transitions as easy as possible, we deprecate APIs and features for a period of time before removing them. This gives you time to update your applications to the latest APIs and best practices.
This guide contains a summary of all Angular APIs and features that are currently deprecated. This guide contains a summary of all Angular APIs and features that are currently deprecated.
@ -20,7 +20,7 @@ For step-by-step instructions on how to update to the latest Angular release, us
## Index ## Index
To help you future-proof your apps, the following table lists all deprecated APIs and features, organized by the release in which they are candidates for removal. Each item is linked to the section later in this guide that describes the deprecation reason and replacement options. To help you future-proof your projects, the following table lists all deprecated APIs and features, organized by the release in which they are candidates for removal. Each item is linked to the section later in this guide that describes the deprecation reason and replacement options.
<!-- <!--
deprecation -> removal cheat sheet deprecation -> removal cheat sheet
@ -71,7 +71,7 @@ This section contains a complete list all of the currently-deprecated APIs, with
<div class="alert is-helpful"> <div class="alert is-helpful">
Tip: In the [API reference section](api) of this doc site, deprecated APIs are indicated by ~~strikethrough.~~ You can filter the API list by [**Status: deprecated**](api?status=deprecated). Tip: In the [API reference section](api) of this site, deprecated APIs are indicated by ~~strikethrough.~~ You can filter the API list by [**Status: deprecated**](api?status=deprecated).
</div> </div>
@ -230,7 +230,7 @@ this.value = 'some value';
``` ```
By default, when you use this pattern, you will see a deprecation warning once in dev By default, when you use this pattern, you will see a deprecation warning once in dev
mode. You can choose to silence this warning by providing a config for mode. You can choose to silence this warning by configuring
`ReactiveFormsModule` at import time: `ReactiveFormsModule` at import time:
```ts ```ts
@ -240,7 +240,7 @@ imports: [
``` ```
Alternatively, you can choose to surface a separate warning for each instance of this Alternatively, you can choose to surface a separate warning for each instance of this
pattern with a config value of `"always"`. This may help to track down where in the code pattern with a configuration value of `"always"`. This may help to track down where in the code
the pattern is being used as the code is being updated. the pattern is being used as the code is being updated.
@ -358,7 +358,7 @@ should be written when the `valueChange` event fires.
<option *ngFor="let optionName of options" [(value)]="optionName"></option> <option *ngFor="let optionName of options" [(value)]="optionName"></option>
``` ```
However, in practice, Angular simply ignores two-way bindings to template variables. Starting in version 8, attempting to write to template variables is deprecated. In a future version, we will throw to indicate that the write is not supported. However, in practice, Angular ignores two-way bindings to template variables. Starting in version 8, attempting to write to template variables is deprecated. In a future version, we will throw to indicate that the write is not supported.
```html ```html
<option *ngFor="let optionName of options" [value]="optionName"></option> <option *ngFor="let optionName of options" [value]="optionName"></option>
@ -385,7 +385,7 @@ Previously, the `entryComponents` array in the `NgModule` definition was used to
{@a moduleWithProviders} {@a moduleWithProviders}
### `ModuleWithProviders` type without a generic ### `ModuleWithProviders` type without a generic
Some Angular libraries, such as `@angular/router` and `@ngrx/store`, implement APIs that return a type called `ModuleWithProviders` (typically via a method named `forRoot()`). Some Angular libraries, such as `@angular/router` and `@ngrx/store`, implement APIs that return a type called `ModuleWithProviders` (typically using a method named `forRoot()`).
This type represents an `NgModule` along with additional providers. This type represents an `NgModule` along with additional providers.
Angular version 9 deprecates use of `ModuleWithProviders` without an explicitly generic type, where the generic type refers to the type of the `NgModule`. Angular version 9 deprecates use of `ModuleWithProviders` without an explicitly generic type, where the generic type refers to the type of the `NgModule`.
In a future version of Angular, the generic will no longer be optional. In a future version of Angular, the generic will no longer be optional.
@ -483,7 +483,7 @@ The following APIs have been removed starting with version 11.0.0*:
{@a esm5-fesm5} {@a esm5-fesm5}
### `esm5` and `fesm5` code formats in @angular/* npm packages ### `esm5` and `fesm5` code formats in @angular/* npm packages
As of Angular v8, the CLI primarily consumes the `fesm2015` variant of the code distributed via `@angular/*` npm packages. As of Angular v8, the CLI primarily consumes the `fesm2015` variant of the code distributed as part of `@angular/*` npm packages.
This renders the `esm5` and `fesm5` distributions obsolete and unnecessary, adding bloat to the package size and slowing down npm installations. This renders the `esm5` and `fesm5` distributions obsolete and unnecessary, adding bloat to the package size and slowing down npm installations.
This removal has no impact on CLI users, unless they modified their build configuration to explicitly consume these code distributions. This removal has no impact on CLI users, unless they modified their build configuration to explicitly consume these code distributions.

17
aio/content/guide/ivy-compatibility.md
View File

@ -8,7 +8,7 @@ That said, some applications will likely need to apply some manual updates.
{@a debugging} {@a debugging}
## How to debug errors with Ivy ## How to debug errors with Ivy
If you're seeing errors, first temporarily [turn off Ivy](guide/ivy#opting-out-of-angular-ivy) in your `tsconfig.json` and re-start your app. If you're seeing errors, first temporarily [turn off Ivy](guide/ivy#opting-out-of-angular-ivy) in your `tsconfig.json` and re-start your application.
If you're still seeing the errors, they are not specific to Ivy. In this case, you may want to consult the [general update guide](guide/updating-to-version-12). If you've opted into any of the new, stricter type-checking settings, you may also want to check out the [template type-checking guide](guide/template-typecheck). If you're still seeing the errors, they are not specific to Ivy. In this case, you may want to consult the [general update guide](guide/updating-to-version-12). If you've opted into any of the new, stricter type-checking settings, you may also want to check out the [template type-checking guide](guide/template-typecheck).
@ -24,13 +24,12 @@ Anything that you import outside lazy modules can end up in the main bundle.
See more details in the original issue [here](https://github.com/angular/angular-cli/issues/16146#issuecomment-557559287). See more details in the original issue [here](https://github.com/angular/angular-cli/issues/16146#issuecomment-557559287).
1. Check that imported libraries have been marked side-effect-free. 1. Check that imported libraries have been marked side-effect-free.
If your app imports from shared libraries that are meant to be free from side effects, add "sideEffects": false to their `package.json`. If your application imports from shared libraries that are meant to be free from side effects, add "sideEffects": false to their `package.json`.
This will ensure that the libraries will be properly tree-shaken if they are imported but not directly referenced. This will ensure that the libraries will be properly tree-shaken if they are imported but not directly referenced.
See more details in the original issue [here](https://github.com/angular/angular-cli/issues/16799#issuecomment-580912090). See more details in the original issue [here](https://github.com/angular/angular-cli/issues/16799#issuecomment-580912090).
1. Projects not using Angular CLI will see a significant size regression unless they update their minifier settings and set compile-time constants `ngDevMode`, `ngI18nClosureMode` and `ngJitMode` to `false` (for Terser, please set these to `false` via [`global_defs` config option](https://terser.org/docs/api-reference.html#conditional-compilation)). 1. Projects not using Angular CLI will see a significant size regression unless they update their minifier settings and set compile-time constants `ngDevMode`, `ngI18nClosureMode` and `ngJitMode` to `false` (for Terser, set these to `false` using [`global_defs` config option](https://terser.org/docs/api-reference.html#conditional-compilation)).
Please note that these constants are not meant to be used by 3rd party library or application code as they are not part of our public API surface and might change in the future. Note that these constants are not meant to be used by 3rd party library or application code as they are not part of our public api surface and might change in the future.
{@a common-changes} {@a common-changes}
### Changes you may see ### Changes you may see
@ -39,7 +38,7 @@ Please note that these constants are not meant to be used by 3rd party library o
* All classes that use Angular DI must have an Angular decorator like `@Directive()` or `@Injectable` (previously, undecorated classes were allowed in AOT mode only or if injection flags were used). See further [details](guide/ivy-compatibility-examples#undecorated-classes). * All classes that use Angular DI must have an Angular decorator like `@Directive()` or `@Injectable` (previously, undecorated classes were allowed in AOT mode only or if injection flags were used). See further [details](guide/ivy-compatibility-examples#undecorated-classes).
* Unbound inputs for directives (e.g. name in `<my-comp name="">`) are now set upon creation of the view, before change detection runs (previously, all inputs were set during change detection). * Unbound inputs for directives (for example, name in `<my-comp name="">`) are now set upon creation of the view, before change detection runs (previously, all inputs were set during change detection).
* Static attributes set directly in the HTML of a template will override any conflicting host attributes set by directives or components (previously, static host attributes set by directives / components would override static template attributes if conflicting). * Static attributes set directly in the HTML of a template will override any conflicting host attributes set by directives or components (previously, static host attributes set by directives / components would override static template attributes if conflicting).
@ -48,7 +47,7 @@ Please note that these constants are not meant to be used by 3rd party library o
* Properties like `host` inside `@Component` and `@Directive` decorators can be inherited (previously, only properties with explicit field decorators like `@HostBinding` would be inherited). * Properties like `host` inside `@Component` and `@Directive` decorators can be inherited (previously, only properties with explicit field decorators like `@HostBinding` would be inherited).
* HammerJS support is opt-in through importing the `HammerModule` (previously, it was always included in production bundles regardless of whether the app used HammerJS). * HammerJS support is opt-in through importing the `HammerModule` (previously, it was always included in production bundles regardless of whether the application used HammerJS).
* `@ContentChild` and `@ContentChildren` queries will no longer be able to match their directive's own host node (previously, these queries would match the host node in addition to its content children). * `@ContentChild` and `@ContentChildren` queries will no longer be able to match their directive's own host node (previously, these queries would match the host node in addition to its content children).
@ -83,9 +82,9 @@ For more information about the updated style precedence in Ivy, refer to the [st
* `DebugElement.classes` returns `undefined` for classes that were added and then subsequently removed (previously, classes added and later removed would have a value of `false`). * `DebugElement.classes` returns `undefined` for classes that were added and then subsequently removed (previously, classes added and later removed would have a value of `false`).
* If selecting the native `<option>` element in a `<select>` where the `<option>`s are created via `*ngFor`, use the `[selected]` property of an `<option>` instead of binding to the `[value]` property of the `<select>` element (previously, you could bind to either.) [details](guide/ivy-compatibility-examples#select-value-binding) * If selecting the native `<option>` element in a `<select>` where the `<option>`s are created using `*ngFor`, use the `[selected]` property of an `<option>` instead of binding to the `[value]` property of the `<select>` element (previously, you could bind to either.) [details](guide/ivy-compatibility-examples#select-value-binding)
* Embedded views (such as ones created by `*ngFor`) are now inserted in front of anchor DOM comment node (e.g. `<!--ng-for-of-->`) rather than behind it as was the case previously. * Embedded views (such as ones created by `*ngFor`) are now inserted in front of anchor DOM comment node (for example, `<!--ng-for-of-->`) rather than behind it as was the case previously.
In most cases this does not have any impact on rendered DOM. In most cases this does not have any impact on rendered DOM.
In some cases (such as animations delaying the removal of an embedded view) any new embedded views will be inserted after the embedded view being animated away. In some cases (such as animations delaying the removal of an embedded view) any new embedded views will be inserted after the embedded view being animated away.
This difference only last while the animation is active, and might alter the visual appearance of the animation. This difference only last while the animation is active, and might alter the visual appearance of the animation.

8
aio/content/guide/releases.md
View File

@ -4,7 +4,7 @@ We recognize that you need stability from the Angular framework. Stability ensur
We also share with you the desire for Angular to keep evolving. We strive to ensure that the foundation on top of which you are building is continuously improving and enabling you to stay up-to-date with the rest of the web ecosystem and your user needs. We also share with you the desire for Angular to keep evolving. We strive to ensure that the foundation on top of which you are building is continuously improving and enabling you to stay up-to-date with the rest of the web ecosystem and your user needs.
This document contains the practices that we follow to provide you with a leading-edge app development platform, balanced with stability. We strive to ensure that future changes are always introduced in a predictable way. We want everyone who depends on Angular to know when and how new features are added, and to be well-prepared when obsolete ones are removed. This document contains the practices that we follow to provide you with a leading-edge application development platform, balanced with stability. We strive to ensure that future changes are always introduced in a predictable way. We want everyone who depends on Angular to know when and how new features are added, and to be well-prepared when obsolete ones are removed.
<div class="alert is-helpful"> <div class="alert is-helpful">
@ -26,7 +26,7 @@ The version number is incremented based on the level of change included in the r
* **Major releases** contain significant new features, some but minimal developer assistance is expected during the update. When updating to a new major release, you may need to run update scripts, refactor code, run additional tests, and learn new APIs. * **Major releases** contain significant new features, some but minimal developer assistance is expected during the update. When updating to a new major release, you may need to run update scripts, refactor code, run additional tests, and learn new APIs.
* **Minor releases** contain new smaller features. Minor releases are fully backward-compatible; no developer assistance is expected during update, but you can optionally modify your apps and libraries to begin using new APIs, features, and capabilities that were added in the release. We update peer dependencies in minor versions by expanding the supported versions, but we do not require projects to update these dependencies. * **Minor releases** contain new smaller features. Minor releases are fully backward-compatible; no developer assistance is expected during update, but you can optionally modify your applications and libraries to begin using new APIs, features, and capabilities that were added in the release. We update peer dependencies in minor versions by expanding the supported versions, but we do not require projects to update these dependencies.
* **Patch releases** are low risk, bug fix releases. No developer assistance is expected during update. * **Patch releases** are low risk, bug fix releases. No developer assistance is expected during update.
@ -131,7 +131,7 @@ To make these transitions as easy as possible, we make these commitments to you:
* We work hard to minimize the number of breaking changes and to provide migration tools when possible. * We work hard to minimize the number of breaking changes and to provide migration tools when possible.
* We follow the deprecation policy described here, so you have time to update your apps to the latest APIs and best practices. * We follow the deprecation policy described here, so you have time to update your applications to the latest APIs and best practices.
To help ensure that you have sufficient time and a clear path to update, this is our deprecation policy: To help ensure that you have sufficient time and a clear path to update, this is our deprecation policy:
@ -141,7 +141,7 @@ To help ensure that you have sufficient time and a clear path to update, this is
* **Deprecation period:** When an API or a feature is deprecated, it will still be present in the next two major releases. After that, deprecated APIs and features will be candidates for removal. A deprecation can be announced in any release, but the removal of a deprecated API or feature will happen only in major release. Until a deprecated API or feature is removed, it will be maintained according to the LTS support policy, meaning that only critical and security issues will be fixed. * **Deprecation period:** When an API or a feature is deprecated, it will still be present in the next two major releases. After that, deprecated APIs and features will be candidates for removal. A deprecation can be announced in any release, but the removal of a deprecated API or feature will happen only in major release. Until a deprecated API or feature is removed, it will be maintained according to the LTS support policy, meaning that only critical and security issues will be fixed.
* **npm dependencies:** We only make npm dependency updates that require changes to your apps in a major release. * **npm dependencies:** We only make npm dependency updates that require changes to your applications in a major release.
In minor releases, we update peer dependencies by expanding the supported versions, but we do not require projects to update these dependencies until a future major version. This means that during minor Angular releases, npm dependency updates within Angular applications and libraries are optional. In minor releases, we update peer dependencies by expanding the supported versions, but we do not require projects to update these dependencies until a future major version. This means that during minor Angular releases, npm dependency updates within Angular applications and libraries are optional.

2
aio/content/guide/roadmap.md
View File

@ -1,6 +1,6 @@
# Angular Roadmap # Angular Roadmap
Angular receives a large number of feature requests, both from inside Google and from the broader open-source community. At the same time, our list of projects contains plenty of maintenance tasks, code refactorings, potential performance improvements, and so on. We bring together representatives from developer relations, product management, and engineering to prioritize this list. As new projects come into the queue, we regularly position them based on relative priority to other projects. As work gets done, projects will move up in the queue. Angular receives a large number of feature requests, both from inside Google and from the broader open-source community. At the same time, our list of projects contains plenty of maintenance tasks, code refactorings, and potential performance improvements. We bring together representatives from developer relations, product management, and engineering to prioritize this list. As new projects come into the queue, we regularly position them based on relative priority to other projects. As work gets done, projects will move up in the queue.
The projects below are not associated with a particular Angular version. We'll release them on completion, and they will be part of a specific version based on our release schedule, following semantic versioning. For example, features are released in the next minor after they are complete, or the next major if they include breaking changes. The projects below are not associated with a particular Angular version. We'll release them on completion, and they will be part of a specific version based on our release schedule, following semantic versioning. For example, features are released in the next minor after they are complete, or the next major if they include breaking changes.

72
aio/content/guide/upgrade-performance.md
View File

@ -11,9 +11,9 @@ This guide describes some of the built-in tools for efficiently migrating Angula
the Angular platform, one piece at a time. It is very similar to the Angular platform, one piece at a time. It is very similar to
[Upgrading from AngularJS](guide/upgrade) with the exception that this one uses the {@link [Upgrading from AngularJS](guide/upgrade) with the exception that this one uses the {@link
downgradeModule downgradeModule()} helper function instead of the {@link UpgradeModule downgradeModule downgradeModule()} helper function instead of the {@link UpgradeModule
UpgradeModule} class. This affects how the app is bootstrapped and how change detection is UpgradeModule} class. This affects how the application is bootstrapped and how change detection is
propagated between the two frameworks. It allows you to upgrade incrementally while improving the propagated between the two frameworks. It allows you to upgrade incrementally while improving the
speed of your hybrid apps and leveraging the latest of Angular in AngularJS apps early in the speed of your hybrid applications and leveraging the latest of Angular in AngularJS applications early in the
process of upgrading. process of upgrading.
@ -28,8 +28,8 @@ same regardless of how you upgrade, refer to the [Preparation](guide/upgrade#pre
## Upgrading with `ngUpgrade` ## Upgrading with `ngUpgrade`
With the `ngUpgrade` library in Angular you can upgrade an existing AngularJS app incrementally by With the `ngUpgrade` library in Angular you can upgrade an existing AngularJS application incrementally by
building a hybrid app where you can run both frameworks side-by-side. In these hybrid apps you can building a hybrid app where you can run both frameworks side-by-side. In these hybrid applications you can
mix and match AngularJS and Angular components and services and have them interoperate seamlessly. mix and match AngularJS and Angular components and services and have them interoperate seamlessly.
That means you don't have to do the upgrade work all at once as there is a natural coexistence That means you don't have to do the upgrade work all at once as there is a natural coexistence
between the two frameworks during the transition period. between the two frameworks during the transition period.
@ -46,7 +46,7 @@ upgrade/static} utilities remain the same. For more information, see the
<div class="alert is-helpful"> <div class="alert is-helpful">
The [Change Detection](guide/upgrade#change-detection) section of The [Change Detection](guide/upgrade#change-detection) section of
[Upgrading from AngularJS](guide/upgrade) only applies to apps that use `UpgradeModule`. Though [Upgrading from AngularJS](guide/upgrade) only applies to applications that use `UpgradeModule`. Though
you handle change detection differently with `downgradeModule()`, which is the focus of this you handle change detection differently with `downgradeModule()`, which is the focus of this
guide, reading the [Change Detection](guide/upgrade#change-detection) section provides helpful guide, reading the [Change Detection](guide/upgrade#change-detection) section provides helpful
context for what follows. context for what follows.
@ -65,14 +65,14 @@ the Angular part and vice versa. This is convenient as it ensures that neither f
important change. Most of the time, though, these extra change detection runs are unnecessary. important change. Most of the time, though, these extra change detection runs are unnecessary.
`downgradeModule()`, on the other side, avoids explicitly triggering change detection unless it `downgradeModule()`, on the other side, avoids explicitly triggering change detection unless it
knows the other part of the app is interested in the changes. For example, if a downgraded component knows the other part of the application is interested in the changes. For example, if a downgraded component
defines an `@Input()`, chances are that the app needs to be aware when that value changes. Thus, defines an `@Input()`, chances are that the application needs to be aware when that value changes. Thus,
`downgradeComponent()` automatically triggers change detection on that component. `downgradeComponent()` automatically triggers change detection on that component.
In most cases, though, the changes made locally in a particular component are of no interest to the In most cases, though, the changes made locally in a particular component are of no interest to the
rest of the app. For example, if the user clicks a button that submits a form, the component usually rest of the application. For example, if the user clicks a button that submits a form, the component usually
handles the result of this action. That being said, there _are_ cases where you want to propagate handles the result of this action. That being said, there _are_ cases where you want to propagate
changes to some other part of the app that may be controlled by the other framework. In such cases, changes to some other part of the application that may be controlled by the other framework. In such cases,
you are responsible for notifying the interested parties by manually triggering change detection. you are responsible for notifying the interested parties by manually triggering change detection.
If you want a particular piece of code to trigger change detection in the AngularJS part of the app, If you want a particular piece of code to trigger change detection in the AngularJS part of the app,
@ -81,14 +81,14 @@ you need to wrap it in
triggering change detection in Angular you would use {@link NgZone#run ngZone.run()}. triggering change detection in Angular you would use {@link NgZone#run ngZone.run()}.
In many cases, a few extra change detection runs may not matter much. However, on larger or In many cases, a few extra change detection runs may not matter much. However, on larger or
change-detection-heavy apps they can have a noticeable impact. By giving you more fine-grained change-detection-heavy applications they can have a noticeable impact. By giving you more fine-grained
control over the change detection propagation, `downgradeModule()` allows you to achieve better control over the change detection propagation, `downgradeModule()` allows you to achieve better
performance for your hybrid apps. performance for your hybrid applications.
## Using `downgradeModule()` ## Using `downgradeModule()`
Both AngularJS and Angular have their own concept of modules to help organize an app into cohesive Both AngularJS and Angular have their own concept of modules to help organize an application into cohesive
blocks of functionality. blocks of functionality.
Their details are quite different in architecture and implementation. In AngularJS, you create a Their details are quite different in architecture and implementation. In AngularJS, you create a
@ -97,10 +97,10 @@ module by specifying its name and dependencies with
assets using its various methods. In Angular, you create a class adorned with an {@link NgModule assets using its various methods. In Angular, you create a class adorned with an {@link NgModule
NgModule} decorator that describes assets in metadata. NgModule} decorator that describes assets in metadata.
In a hybrid app you run both frameworks at the same time. This means that you need at least one In a hybrid application you run both frameworks at the same time. This means that you need at least one
module each from both AngularJS and Angular. module each from both AngularJS and Angular.
For the most part, you specify the modules in the same way you would for a regular app. Then, you For the most part, you specify the modules in the same way you would for a regular application. Then, you
use the `upgrade/static` helpers to let the two frameworks know about assets they can use from each use the `upgrade/static` helpers to let the two frameworks know about assets they can use from each
other. This is known as "upgrading" and "downgrading". other. This is known as "upgrading" and "downgrading".
@ -109,16 +109,16 @@ other. This is known as "upgrading" and "downgrading".
<b>Definitions:</b> <b>Definitions:</b>
- _Upgrading_: The act of making an AngularJS asset, such as a component or service, available to - _Upgrading_: The act of making an AngularJS asset, such as a component or service, available to
the Angular part of the app. the Angular part of the application.
- _Downgrading_: The act of making an Angular asset, such as a component or service, available to - _Downgrading_: The act of making an Angular asset, such as a component or service, available to
the AngularJS part of the app. the AngularJS part of the application.
</div> </div>
An important part of inter-linking dependencies is linking the two main modules together. This is An important part of inter-linking dependencies is linking the two main modules together. This is
where `downgradeModule()` comes in. Use it to create an AngularJS module&mdash;one that you can use where `downgradeModule()` comes in. Use it to create an AngularJS module&mdash;one that you can use
as a dependency in your main AngularJS module&mdash;that will bootstrap your main Angular module and as a dependency in your main AngularJS module&mdash;that will bootstrap your main Angular module and
kick off the Angular part of the hybrid app. In a sense, it "downgrades" an Angular module to an kick off the Angular part of the hybrid application. In a sense, it "downgrades" an Angular module to an
AngularJS module. AngularJS module.
There are a few things to note, though: There are a few things to note, though:
@ -126,7 +126,7 @@ There are a few things to note, though:
1. You don't pass the Angular module directly to `downgradeModule()`. All `downgradeModule()` needs 1. You don't pass the Angular module directly to `downgradeModule()`. All `downgradeModule()` needs
is a "recipe", for example, a factory function, to create an instance for your module. is a "recipe", for example, a factory function, to create an instance for your module.
2. The Angular module is not instantiated until the app actually needs it. 2. The Angular module is not instantiated until the application actually needs it.
The following is an example of how you can use `downgradeModule()` to link the two modules. The following is an example of how you can use `downgradeModule()` to link the two modules.
@ -156,11 +156,11 @@ of the Angular module. `downgradeModule()` accepts two types of factory function
When you pass an `NgModuleFactory`, `downgradeModule()` uses it to instantiate the module using When you pass an `NgModuleFactory`, `downgradeModule()` uses it to instantiate the module using
{@link platformBrowser platformBrowser}'s {@link PlatformRef#bootstrapModuleFactory {@link platformBrowser platformBrowser}'s {@link PlatformRef#bootstrapModuleFactory
bootstrapModuleFactory()}, which is compatible with ahead-of-time (AOT) compilation. AOT compilation bootstrapModuleFactory()}, which is compatible with ahead-of-time (AOT) compilation. AOT compilation
helps make your apps load faster. For more about AOT and how to create an `NgModuleFactory`, see the helps make your applications load faster. For more about AOT and how to create an `NgModuleFactory`, see the
[Ahead-of-Time Compilation](guide/aot-compiler) guide. [Ahead-of-Time Compilation](guide/aot-compiler) guide.
Alternatively, you can pass a plain function, which is expected to return a promise resolving to an Alternatively, you can pass a plain function, which is expected to return a promise resolving to an
{@link NgModuleRef NgModuleRef} (i.e. an instance of your Angular module). The function is called {@link NgModuleRef NgModuleRef} (that is, an instance of your Angular module). The function is called
with an array of extra {@link StaticProvider Providers} that are expected to be available on the with an array of extra {@link StaticProvider Providers} that are expected to be available on the
returned `NgModuleRef`'s {@link Injector Injector}. For example, if you are using {@link returned `NgModuleRef`'s {@link Injector Injector}. For example, if you are using {@link
platformBrowser platformBrowser} or {@link platformBrowserDynamic platformBrowserDynamic}, you can platformBrowser platformBrowser} or {@link platformBrowserDynamic platformBrowserDynamic}, you can
@ -192,9 +192,9 @@ until later. `downgradeModule()` is again less aggressive. It will only instanti
when it is required for the first time; that is, as soon as it needs to create a downgraded when it is required for the first time; that is, as soon as it needs to create a downgraded
component. component.
You could go a step further and not even download the code for the Angular part of the app to the You could go a step further and not even download the code for the Angular part of the application to the
user's browser until it is needed. This is especially useful when you use Angular on parts of the user's browser until it is needed. This is especially useful when you use Angular on parts of the
hybrid app that are not necessary for the initial rendering or that the user doesn't reach. hybrid application that are not necessary for the initial rendering or that the user doesn't reach.
A few examples are: A few examples are:
@ -203,23 +203,23 @@ A few examples are:
- You use Angular for features that are only visible to specific types of users; for example, - You use Angular for features that are only visible to specific types of users; for example,
logged-in users, administrators, or VIP members. You don't need to load Angular until a user is logged-in users, administrators, or VIP members. You don't need to load Angular until a user is
authenticated. authenticated.
- You use Angular for a feature that is not critical for the initial rendering of the app and you - You use Angular for a feature that is not critical for the initial rendering of the application and you
can afford a small delay in favor of better initial load performance. can afford a small delay in favor of better initial load performance.
### Bootstrapping with `downgradeModule()` ### Bootstrapping with `downgradeModule()`
As you might have guessed, you don't need to change anything in the way you bootstrap your existing As you might have guessed, you don't need to change anything in the way you bootstrap your existing
AngularJS app. Unlike `UpgradeModule`&mdash;which requires some extra steps&mdash; AngularJS application. Unlike `UpgradeModule`&mdash;which requires some extra steps&mdash;
`downgradeModule()` is able to take care of bootstrapping the Angular module, as long as you provide `downgradeModule()` is able to take care of bootstrapping the Angular module, as long as you provide
the recipe. the recipe.
In order to start using any `upgrade/static` APIs, you still need to load the Angular framework as In order to start using any `upgrade/static` APIs, you still need to load the Angular framework as
you would in a normal Angular app. You can see how this can be done with SystemJS by following the you would in a normal Angular application. You can see how this can be done with SystemJS by following the
instructions in the [Upgrade Setup](guide/upgrade-setup "Setup for Upgrading from AngularJS") guide, selectively copying code from the instructions in the [Upgrade Setup](guide/upgrade-setup "Setup for Upgrading from AngularJS") guide, selectively copying code from the
[QuickStart github repository](https://github.com/angular/quickstart). [QuickStart github repository](https://github.com/angular/quickstart).
You also need to install the `@angular/upgrade` package via `npm install @angular/upgrade --save` You also need to install the `@angular/upgrade` package using `npm install @angular/upgrade --save`
and add a mapping for the `@angular/upgrade/static` package: and add a mapping for the `@angular/upgrade/static` package:
<code-example header="system.config.js"> <code-example header="system.config.js">
@ -251,7 +251,7 @@ declaration on its `NgModule` decorator.
<div class="alert is-important"> <div class="alert is-important">
You do not add a `bootstrap` declaration to the `NgModule` decorator since AngularJS owns the root You do not add a `bootstrap` declaration to the `NgModule` decorator since AngularJS owns the root
template of the app and `ngUpgrade` bootstraps the necessary components. template of the application and `ngUpgrade` bootstraps the necessary components.
</div> </div>
@ -278,7 +278,7 @@ The existing AngularJS code works as before _and_ you are ready to start adding
### Using Components and Injectables ### Using Components and Injectables
The differences between `downgradeModule()` and `UpgradeModule` end here. The rest of the The differences between `downgradeModule()` and `UpgradeModule` end here. The rest of the
`upgrade/static` APIs and concepts work in the exact same way for both types of hybrid apps. `upgrade/static` APIs and concepts work in the exact same way for both types of hybrid applications.
See [Upgrading from AngularJS](guide/upgrade) to learn about: See [Upgrading from AngularJS](guide/upgrade) to learn about:
- [Using Angular Components from AngularJS Code](guide/upgrade#using-angular-components-from-angularjs-code).<br /> - [Using Angular Components from AngularJS Code](guide/upgrade#using-angular-components-from-angularjs-code).<br />
@ -296,7 +296,7 @@ See [Upgrading from AngularJS](guide/upgrade) to learn about:
While it is possible to downgrade injectables, downgraded injectables will not be available until While it is possible to downgrade injectables, downgraded injectables will not be available until
the Angular module that provides them is instantiated. In order to be safe, you need to ensure the Angular module that provides them is instantiated. In order to be safe, you need to ensure
that the downgraded injectables are not used anywhere _outside_ the part of the app where it is that the downgraded injectables are not used anywhere _outside_ the part of the application where it is
guaranteed that their module has been instantiated. guaranteed that their module has been instantiated.
For example, it is _OK_ to use a downgraded service in an upgraded component that is only used For example, it is _OK_ to use a downgraded service in an upgraded component that is only used
@ -309,8 +309,8 @@ See [Upgrading from AngularJS](guide/upgrade) to learn about:
## Using ahead-of-time compilation with hybrid apps ## Using ahead-of-time compilation with hybrid apps
You can take advantage of ahead-of-time (AOT) compilation in hybrid apps just like in any other You can take advantage of ahead-of-time (AOT) compilation in hybrid applications just like in any other
Angular app. The setup for a hybrid app is mostly the same as described in the Angular application. The setup for a hybrid application is mostly the same as described in the
[Ahead-of-Time Compilation](guide/aot-compiler) guide save for differences in `index.html` and [Ahead-of-Time Compilation](guide/aot-compiler) guide save for differences in `index.html` and
`main-aot.ts`. `main-aot.ts`.
@ -331,17 +331,17 @@ angular.module('mainAngularJsModule', [
]); ]);
</code-example> </code-example>
And that is all you need to do to get the full benefit of AOT for hybrid Angular apps. And that is all you need to do to get the full benefit of AOT for hybrid Angular applications.
## Conclusion ## Conclusion
This page covered how to use the {@link upgrade/static upgrade/static} package to incrementally This page covered how to use the {@link upgrade/static upgrade/static} package to incrementally
upgrade existing AngularJS apps at your own pace and without impeding further development of the app upgrade existing AngularJS applications at your own pace and without impeding further development of the app
for the duration of the upgrade process. for the duration of the upgrade process.
Specifically, this guide showed how you can achieve better performance and greater flexibility in Specifically, this guide showed how you can achieve better performance and greater flexibility in
your hybrid apps by using {@link downgradeModule downgradeModule()} instead of {@link UpgradeModule your hybrid applications by using {@link downgradeModule downgradeModule()} instead of {@link UpgradeModule
UpgradeModule}. UpgradeModule}.
To summarize, the key differentiating factors of `downgradeModule()` are: To summarize, the key differentiating factors of `downgradeModule()` are:
@ -350,9 +350,9 @@ To summarize, the key differentiating factors of `downgradeModule()` are:
loading time. In some cases this may waive the cost of running a second framework altogether. loading time. In some cases this may waive the cost of running a second framework altogether.
2. It improves performance by avoiding unnecessary change detection runs while giving the developer 2. It improves performance by avoiding unnecessary change detection runs while giving the developer
greater ability to customize. greater ability to customize.
3. It does not require you to change how you bootstrap your AngularJS app. 3. It does not require you to change how you bootstrap your AngularJS application.
Using `downgradeModule()` is a good option for hybrid apps when you want to keep the AngularJS and Using `downgradeModule()` is a good option for hybrid applications when you want to keep the AngularJS and
Angular parts less coupled. You can still mix and match components and services from both Angular parts less coupled. You can still mix and match components and services from both
frameworks, but you might need to manually propagate change detection. In return, frameworks, but you might need to manually propagate change detection. In return,
`downgradeModule()` offers more control and better performance. `downgradeModule()` offers more control and better performance.

8
aio/content/guide/upgrade-setup.md
View File

@ -204,10 +204,10 @@ Focus on the following three TypeScript (`.ts`) files in the **`/src`** folder.
All guides and cookbooks have _at least these core files_. All guides and cookbooks have _at least these core files_.
Each file has a distinct purpose and evolves independently as the application grows. Each file has a distinct purpose and evolves independently as the application grows.
Files outside `src/` concern building, deploying, and testing your app. Files outside `src/` concern building, deploying, and testing your application.
They include configuration files and external dependencies. They include configuration files and external dependencies.
Files inside `src/` "belong" to your app. Files inside `src/` "belong" to your application.
Add new Typescript, HTML and CSS files inside the `src/` directory, most of them inside `src/app`, Add new Typescript, HTML and CSS files inside the `src/` directory, most of them inside `src/app`,
unless told to do otherwise. unless told to do otherwise.
@ -299,10 +299,10 @@ The following are all in `src/`
## Appendix: Develop locally with IE ## Appendix: Develop locally with IE
If you develop Angular locally with `ng serve`, a `websocket` connection is set up automatically between browser and local dev server, so when your code changes, the browser can automatically refresh. If you develop Angular locally with `ng serve`, a `websocket` connection is set up automatically between browser and local development server, so when your code changes, the browser can automatically refresh.
In Windows, by default, one application can only have 6 websocket connections, <a href="https://msdn.microsoft.com/library/ee330736%28v=vs.85%29.aspx?f=255&MSPPError=-2147217396#websocket_maxconn" title="MSDN WebSocket settings">MSDN WebSocket Settings</a>. In Windows, by default, one application can only have 6 websocket connections, <a href="https://msdn.microsoft.com/library/ee330736%28v=vs.85%29.aspx?f=255&MSPPError=-2147217396#websocket_maxconn" title="MSDN WebSocket settings">MSDN WebSocket Settings</a>.
So when IE is refreshed (manually or automatically by `ng serve`), sometimes the websocket does not close properly. When websocket connections exceed the limitations, a `SecurityError` will be thrown. This error will not affect the Angular application, you can just restart IE to clear this error, or modify the windows registry to update the limitations. So when IE is refreshed (manually or automatically by `ng serve`), sometimes the websocket does not close properly. When websocket connections exceed the limitations, a `SecurityError` will be thrown. This error will not affect the Angular application, you can restart IE to clear this error, or modify the windows registry to update the limitations.
## Appendix: Test using `fakeAsync()/waitForAsync()` ## Appendix: Test using `fakeAsync()/waitForAsync()`

74
aio/content/guide/upgrade.md
View File

@ -3,7 +3,7 @@
_Angular_ is the name for the Angular of today and tomorrow.<br /> _Angular_ is the name for the Angular of today and tomorrow.<br />
_AngularJS_ is the name for all 1.x versions of Angular. _AngularJS_ is the name for all 1.x versions of Angular.
AngularJS apps are great. AngularJS applications are great.
Always consider the business case before moving to Angular. Always consider the business case before moving to Angular.
An important part of that case is the time and effort to get there. An important part of that case is the time and effort to get there.
This guide describes the built-in tools for efficiently migrating AngularJS projects over to the This guide describes the built-in tools for efficiently migrating AngularJS projects over to the
@ -30,7 +30,7 @@ make incremental upgrading seamless.
There are many ways to structure AngularJS applications. When you begin There are many ways to structure AngularJS applications. When you begin
to upgrade these applications to Angular, some will turn out to be to upgrade these applications to Angular, some will turn out to be
much more easy to work with than others. There are a few key techniques much more easy to work with than others. There are a few key techniques
and patterns that you can apply to future proof apps even before you and patterns that you can apply to future proof applications even before you
begin the migration. begin the migration.
{@a follow-the-angular-styleguide} {@a follow-the-angular-styleguide}
@ -46,8 +46,8 @@ importantly - how **not** to write and organize AngularJS code.
Angular is a reimagined version of the best parts of AngularJS. In that Angular is a reimagined version of the best parts of AngularJS. In that
sense, its goals are the same as the AngularJS Style Guide's: To preserve sense, its goals are the same as the AngularJS Style Guide's: To preserve
the good parts of AngularJS, and to avoid the bad parts. There's a lot the good parts of AngularJS, and to avoid the bad parts. There's a lot
more to Angular than just that of course, but this does mean that more to Angular than that of course, but this does mean that
*following the style guide helps make your AngularJS app more closely *following the style guide helps make your AngularJS application more closely
aligned with Angular*. aligned with Angular*.
There are a few rules in particular that will make it much easier to do There are a few rules in particular that will make it much easier to do
@ -284,7 +284,7 @@ owned by AngularJS, Angular treats it as if it didn't exist,
and vice versa. and vice versa.
So normally a hybrid application begins life as an AngularJS application, So normally a hybrid application begins life as an AngularJS application,
and it is AngularJS that processes the root template, e.g. the index.html. and it is AngularJS that processes the root template, for example, the index.html.
Angular then steps into the picture when an Angular component is used somewhere Angular then steps into the picture when an Angular component is used somewhere
in an AngularJS template. That component's template will then be managed in an AngularJS template. That component's template will then be managed
by Angular, and it may contain any number of Angular components and by Angular, and it may contain any number of Angular components and
@ -404,7 +404,7 @@ be used to bootstrap the AngularJS application.
</code-example> </code-example>
Pure AngularJS applications can be automatically bootstrapped by using an `ng-app` Pure AngularJS applications can be automatically bootstrapped by using an `ng-app`
directive somewhere on the HTML page. But for hybrid applications, you manually bootstrap via the directive somewhere on the HTML page. But for hybrid applications, you manually bootstrap using the
`UpgradeModule`. Therefore, it is a good preliminary step to switch AngularJS applications to use the `UpgradeModule`. Therefore, it is a good preliminary step to switch AngularJS applications to use the
manual JavaScript [`angular.bootstrap`](https://docs.angularjs.org/api/ng/function/angular.bootstrap) manual JavaScript [`angular.bootstrap`](https://docs.angularjs.org/api/ng/function/angular.bootstrap)
method even before switching them to hybrid mode. method even before switching them to hybrid mode.
@ -424,7 +424,7 @@ will result in the same thing:
To begin converting your AngularJS application to a hybrid, you need to load the Angular framework. To begin converting your AngularJS application to a hybrid, you need to load the Angular framework.
You can see how this can be done with SystemJS by following the instructions in [Setup for Upgrading to AngularJS](guide/upgrade-setup) for selectively copying code from the [QuickStart github repository](https://github.com/angular/quickstart). You can see how this can be done with SystemJS by following the instructions in [Setup for Upgrading to AngularJS](guide/upgrade-setup) for selectively copying code from the [QuickStart github repository](https://github.com/angular/quickstart).
You also need to install the `@angular/upgrade` package via `npm install @angular/upgrade --save` You also need to install the `@angular/upgrade` package using `npm install @angular/upgrade --save`
and add a mapping for the `@angular/upgrade/static` package: and add a mapping for the `@angular/upgrade/static` package:
<code-example path="upgrade-module/src/systemjs.config.1.js" region="upgrade-static-umd" header="systemjs.config.js (map)"> <code-example path="upgrade-module/src/systemjs.config.1.js" region="upgrade-static-umd" header="systemjs.config.js (map)">
@ -435,12 +435,12 @@ Next, create an `app.module.ts` file and add the following `NgModule` class:
<code-example path="upgrade-module/src/app/ajs-a-hybrid-bootstrap/app.module.ts" region="ngmodule" header="app.module.ts"> <code-example path="upgrade-module/src/app/ajs-a-hybrid-bootstrap/app.module.ts" region="ngmodule" header="app.module.ts">
</code-example> </code-example>
This bare minimum `NgModule` imports `BrowserModule`, the module every Angular browser-based app must have. This bare minimum `NgModule` imports `BrowserModule`, the module every Angular browser-based application must have.
It also imports `UpgradeModule` from `@angular/upgrade/static`, which exports providers that will be used It also imports `UpgradeModule` from `@angular/upgrade/static`, which exports providers that will be used
for upgrading and downgrading services and components. for upgrading and downgrading services and components.
In the constructor of the `AppModule`, use dependency injection to get a hold of the `UpgradeModule` instance, In the constructor of the `AppModule`, use dependency injection to get a hold of the `UpgradeModule` instance,
and use it to bootstrap the AngularJS app in the `AppModule.ngDoBootstrap` method. and use it to bootstrap the AngularJS application in the `AppModule.ngDoBootstrap` method.
The `upgrade.bootstrap` method takes the exact same arguments as [angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap): The `upgrade.bootstrap` method takes the exact same arguments as [angular.bootstrap](https://docs.angularjs.org/api/ng/function/angular.bootstrap):
<div class="alert is-helpful"> <div class="alert is-helpful">
@ -467,7 +467,7 @@ code. One of the more common patterns for doing that is to use an Angular compon
in an AngularJS context. This could be a completely new component or one that was in an AngularJS context. This could be a completely new component or one that was
previously AngularJS but has been rewritten for Angular. previously AngularJS but has been rewritten for Angular.
Say you have a simple Angular component that shows information about a hero: Say you have an Angular component that shows information about a hero:
<code-example path="upgrade-module/src/app/downgrade-static/hero-detail.component.ts" header="hero-detail.component.ts"> <code-example path="upgrade-module/src/app/downgrade-static/hero-detail.component.ts" header="hero-detail.component.ts">
</code-example> </code-example>
@ -482,7 +482,7 @@ using the `downgradeComponent()` method. The result is an AngularJS
<div class="alert is-helpful"> <div class="alert is-helpful">
By default, Angular change detection will also run on the component for every By default, Angular change detection will also run on the component for every
AngularJS `$digest` cycle. If you wish to only have change detection run when AngularJS `$digest` cycle. If you want to only have change detection run when
the inputs change, you can set `propagateDigest` to `false` when calling the inputs change, you can set `propagateDigest` to `false` when calling
`downgradeComponent()`. `downgradeComponent()`.
@ -590,7 +590,7 @@ The safest bet for ensuring compatibility is using the
[component API](https://docs.angularjs.org/api/ng/type/angular.Module) [component API](https://docs.angularjs.org/api/ng/type/angular.Module)
introduced in AngularJS 1.5. introduced in AngularJS 1.5.
A simple example of an upgradable component is one that just has a template An example of an upgradable component is one that just has a template
and a controller: and a controller:
<code-example path="upgrade-module/src/app/upgrade-static/hero-detail.component.ts" region="hero-detail" header="hero-detail.component.ts"> <code-example path="upgrade-module/src/app/upgrade-static/hero-detail.component.ts" region="hero-detail" header="hero-detail.component.ts">
@ -791,7 +791,7 @@ compilation can pick it up.
<div class="alert is-helpful"> <div class="alert is-helpful">
**Note:** The 'heroes' string inside the factory refers to the AngularJS `HeroesService`. **Note:** The 'heroes' string inside the factory refers to the AngularJS `HeroesService`.
It is common in AngularJS apps to choose a service name for the token, for example "heroes", It is common in AngularJS applications to choose a service name for the token, for example "heroes",
and append the "Service" suffix to create the class name. and append the "Service" suffix to create the class name.
</div> </div>
@ -860,7 +860,7 @@ In most environments where both Angular and AngularJS are used to render the app
Overall application performance is affected in cases where the user stays on Angular-rendered pages because the AngularJS framework and application are still loaded and running, even if they are never accessed. Overall application performance is affected in cases where the user stays on Angular-rendered pages because the AngularJS framework and application are still loaded and running, even if they are never accessed.
You can take steps to mitigate both bundle size and performance issues. By isolating your AngularJS app to a separate bundle, you can take advantage of [lazy loading](guide/glossary#lazy-loading) to load, bootstrap, and render the AngularJS application only when needed. This strategy reduces your initial bundle size, defers any potential impact from loading both frameworks until absolutely necessary, and keeps your application running as efficiently as possible. You can take steps to mitigate both bundle size and performance issues. By isolating your AngularJS application to a separate bundle, you can take advantage of [lazy loading](guide/glossary#lazy-loading) to load, bootstrap, and render the AngularJS application only when needed. This strategy reduces your initial bundle size, defers any potential impact from loading both frameworks until absolutely necessary, and keeps your application running as efficiently as possible.
The steps below show you how to do the following: The steps below show you how to do the following:
@ -871,19 +871,19 @@ The steps below show you how to do the following:
### Create a service to lazy load AngularJS ### Create a service to lazy load AngularJS
As of Angular version 8, lazy loading code can be accomplished simply by using the dynamic import syntax `import('...')`. In your application, you create a new service that uses dynamic imports to lazy load AngularJS. As of Angular version 8, lazy loading code can be accomplished by using the dynamic import syntax `import('...')`. In your application, you create a new service that uses dynamic imports to lazy load AngularJS.
<code-example path="upgrade-lazy-load-ajs/src/app/lazy-loader.service.ts" header="src/app/lazy-loader.service.ts"> <code-example path="upgrade-lazy-load-ajs/src/app/lazy-loader.service.ts" header="src/app/lazy-loader.service.ts">
</code-example> </code-example>
The service uses the `import()` method to load your bundled AngularJS application lazily. This decreases the initial bundle size of your application as you're not loading code your user doesn't need yet. You also need to provide a way to _bootstrap_ the application manually after it has been loaded. AngularJS provides a way to manually bootstrap an application using the [angular.bootstrap()](https://docs.angularjs.org/api/ng/function/angular.bootstrap) method with a provided HTML element. Your AngularJS app should also expose a `bootstrap` method that bootstraps the AngularJS app. The service uses the `import()` method to load your bundled AngularJS application lazily. This decreases the initial bundle size of your application as you're not loading code your user doesn't need yet. You also need to provide a way to _bootstrap_ the application manually after it has been loaded. AngularJS provides a way to manually bootstrap an application using the [angular.bootstrap()](https://docs.angularjs.org/api/ng/function/angular.bootstrap) method with a provided HTML element. Your AngularJS application should also expose a `bootstrap` method that bootstraps the AngularJS app.
To ensure any necessary teardown is triggered in the AngularJS app, such as removal of global listeners, you also implement a method to call the `$rootScope.destroy()` method. To ensure any necessary teardown is triggered in the AngularJS app, such as removal of global listeners, you also implement a method to call the `$rootScope.destroy()` method.
<code-example path="upgrade-lazy-load-ajs/src/app/angularjs-app/index.ts" header="angularjs-app"> <code-example path="upgrade-lazy-load-ajs/src/app/angularjs-app/index.ts" header="angularjs-app">
</code-example> </code-example>
Your AngularJS application is configured with only the routes it needs to render content. The remaining routes in your application are handled by the Angular Router. The exposed `bootstrap` method is called in your Angular app to bootstrap the AngularJS application after the bundle is loaded. Your AngularJS application is configured with only the routes it needs to render content. The remaining routes in your application are handled by the Angular Router. The exposed `bootstrap` method is called in your Angular application to bootstrap the AngularJS application after the bundle is loaded.
<div class="alert is-important"> <div class="alert is-important">
@ -893,7 +893,7 @@ Your AngularJS application is configured with only the routes it needs to render
### Create a component to render AngularJS content ### Create a component to render AngularJS content
In your Angular application, you need a component as a placeholder for your AngularJS content. This component uses the service you create to load and bootstrap your AngularJS app after the component is initialized. In your Angular application, you need a component as a placeholder for your AngularJS content. This component uses the service you create to load and bootstrap your AngularJS application after the component is initialized.
<code-example path="upgrade-lazy-load-ajs/src/app/angular-js/angular-js.component.ts" header="src/app/angular-js/angular-js.component.ts"> <code-example path="upgrade-lazy-load-ajs/src/app/angular-js/angular-js.component.ts" header="src/app/angular-js/angular-js.component.ts">
</code-example> </code-example>
@ -914,7 +914,7 @@ The following code adds a route object to your routing configuration using the `
<code-example path="upgrade-lazy-load-ajs/src/app/app-routing.module.ts" header="src/app/app-routing.module.ts"> <code-example path="upgrade-lazy-load-ajs/src/app/app-routing.module.ts" header="src/app/app-routing.module.ts">
</code-example> </code-example>
When your application matches a route that needs AngularJS, the AngularJS app is loaded and bootstrapped, the AngularJS routes match the necessary URL to render their content, and your application continues to run with both AngularJS and Angular frameworks. When your application matches a route that needs AngularJS, the AngularJS application is loaded and bootstrapped, the AngularJS routes match the necessary URL to render their content, and your application continues to run with both AngularJS and Angular frameworks.
## Using the Unified Angular Location Service ## Using the Unified Angular Location Service
@ -999,7 +999,7 @@ And that's all you need do to get the full benefit of AOT for Angular apps!
## PhoneCat Upgrade Tutorial ## PhoneCat Upgrade Tutorial
In this section, you'll learn to prepare and upgrade an application with `ngUpgrade`. In this section, you'll learn to prepare and upgrade an application with `ngUpgrade`.
The example app is [Angular PhoneCat](https://github.com/angular/angular-phonecat) The example application is [Angular PhoneCat](https://github.com/angular/angular-phonecat)
from [the original AngularJS tutorial](https://docs.angularjs.org/tutorial), from [the original AngularJS tutorial](https://docs.angularjs.org/tutorial),
which is where many of us began our Angular adventures. Now you'll see how to which is where many of us began our Angular adventures. Now you'll see how to
bring that application to the brave new world of Angular. bring that application to the brave new world of Angular.
@ -1220,7 +1220,7 @@ Keep this process running in the background, watching and recompiling as you mak
Next, convert your current JavaScript files into TypeScript. Since Next, convert your current JavaScript files into TypeScript. Since
TypeScript is a super-set of ECMAScript 2015, which in turn is a super-set TypeScript is a super-set of ECMAScript 2015, which in turn is a super-set
of ECMAScript 5, you can simply switch the file extensions from `.js` to `.ts` of ECMAScript 5, you can switch the file extensions from `.js` to `.ts`
and everything will work just like it did before. As the TypeScript compiler and everything will work just like it did before. As the TypeScript compiler
runs, it emits the corresponding `.js` file for every `.ts` file and the runs, it emits the corresponding `.js` file for every `.ts` file and the
compiled JavaScript is what actually gets executed. If you start compiled JavaScript is what actually gets executed. If you start
@ -1230,7 +1230,7 @@ application in your browser.
Now that you have TypeScript though, you can start benefiting from some of its Now that you have TypeScript though, you can start benefiting from some of its
features. There's a lot of value the language can provide to AngularJS applications. features. There's a lot of value the language can provide to AngularJS applications.
For one thing, TypeScript is a superset of ES2015. Any app that has previously For one thing, TypeScript is a superset of ES2015. Any application that has previously
been written in ES5 - like the PhoneCat example has - can with TypeScript been written in ES5 - like the PhoneCat example has - can with TypeScript
start incorporating all of the JavaScript features that are new to ES2015. start incorporating all of the JavaScript features that are new to ES2015.
These include things like `let`s and `const`s, arrow functions, default function These include things like `let`s and `const`s, arrow functions, default function
@ -1348,7 +1348,7 @@ Once these are done, run:
npm install npm install
</code-example> </code-example>
Soon you can load Angular dependencies into the application via `index.html`, Soon you can load Angular dependencies into the application using `index.html`,
but first you need to do some directory path adjustments. but first you need to do some directory path adjustments.
You'll need to load files from `node_modules` and the project root instead of You'll need to load files from `node_modules` and the project root instead of
from the `/app` directory as you've been doing to this point. from the `/app` directory as you've been doing to this point.
@ -1369,8 +1369,8 @@ cause relative URLs to be resolved back to the `/app` directory:
<code-example path="upgrade-phonecat-2-hybrid/index.html" region="base" header="index.html"> <code-example path="upgrade-phonecat-2-hybrid/index.html" region="base" header="index.html">
</code-example> </code-example>
Now you can load Angular via SystemJS. You'll add the Angular polyfills and the Now you can load Angular using SystemJS. You'll add the Angular polyfills and the
SystemJS config to the end of the `<head>` section, and then you'll use `System.import` SystemJS configuration to the end of the `<head>` section, and then you'll use `System.import`
to load the actual application: to load the actual application:
<code-example path="upgrade-phonecat-2-hybrid/index.html" region="angular" header="index.html"> <code-example path="upgrade-phonecat-2-hybrid/index.html" region="angular" header="index.html">
@ -1382,7 +1382,7 @@ to the `systemjs.config.js` file installed during [upgrade setup](guide/upgrade-
Point the browser to the project root when loading things through SystemJS, Point the browser to the project root when loading things through SystemJS,
instead of using the `<base>` URL. instead of using the `<base>` URL.
Install the `upgrade` package via `npm install @angular/upgrade --save` Install the `upgrade` package using `npm install @angular/upgrade --save`
and add a mapping for the `@angular/upgrade/static` package. and add a mapping for the `@angular/upgrade/static` package.
<code-example path="upgrade-phonecat-2-hybrid/systemjs.config.1.js" region="paths" header="systemjs.config.js"> <code-example path="upgrade-phonecat-2-hybrid/systemjs.config.1.js" region="paths" header="systemjs.config.js">
@ -1411,7 +1411,7 @@ you can start converting the individual pieces to Angular.
The application is currently bootstrapped using the AngularJS `ng-app` directive The application is currently bootstrapped using the AngularJS `ng-app` directive
attached to the `<html>` element of the host page. This will no longer work in the hybrid attached to the `<html>` element of the host page. This will no longer work in the hybrid
app. Switch to the [ngUpgrade bootstrap](#bootstrapping-hybrid-applications) method application. Switch to the [ngUpgrade bootstrap](#bootstrapping-hybrid-applications) method
instead. instead.
First, remove the `ng-app` attribute from `index.html`. First, remove the `ng-app` attribute from `index.html`.
@ -1442,12 +1442,12 @@ exciting! You're not running any actual Angular components yet. That's next.
`@types/angular` is declared as a UMD module, and due to the way `@types/angular` is declared as a UMD module, and due to the way
<a href="https://github.com/Microsoft/TypeScript/wiki/What's-new-in-TypeScript#support-for-umd-module-definitions">UMD typings</a> <a href="https://github.com/Microsoft/TypeScript/wiki/What's-new-in-TypeScript#support-for-umd-module-definitions">UMD typings</a>
work, once you have an ES6 `import` statement in a file all UMD typed modules must also be work, once you have an ES6 `import` statement in a file all UMD typed modules must also be
imported via `import` statements instead of being globally available. imported using `import` statements instead of being globally available.
AngularJS is currently loaded by a script tag in `index.html`, which means that the whole app AngularJS is currently loaded by a script tag in `index.html`, which means that the whole app
has access to it as a global and uses the same instance of the `angular` variable. has access to it as a global and uses the same instance of the `angular` variable.
If you used `import * as angular from 'angular'` instead, you'd also have to If you used `import * as angular from 'angular'` instead, you'd also have to
load every file in the AngularJS app to use ES2015 modules in order to ensure AngularJS was being load every file in the AngularJS application to use ES2015 modules in order to ensure AngularJS was being
loaded correctly. loaded correctly.
This is a considerable effort and it often isn't worth it, especially since you are in the This is a considerable effort and it often isn't worth it, especially since you are in the
@ -1624,7 +1624,7 @@ which was injected into `PhoneDetails` when it was still an AngularJS controller
You intend to inject it into the new `PhoneDetailsComponent`. You intend to inject it into the new `PhoneDetailsComponent`.
Unfortunately, AngularJS dependencies are not automatically available to Angular components. Unfortunately, AngularJS dependencies are not automatically available to Angular components.
You must upgrade this service via a [factory provider](guide/upgrade#making-angularjs-dependencies-injectable-to-angular) You must upgrade this service using a [factory provider](guide/upgrade#making-angularjs-dependencies-injectable-to-angular)
to make `$routeParams` an Angular injectable. to make `$routeParams` an Angular injectable.
Do that in a new file called `ajs-upgraded-providers.ts` and import it in `app.module.ts`: Do that in a new file called `ajs-upgraded-providers.ts` and import it in `app.module.ts`:
@ -1708,7 +1708,7 @@ as well:
These files need to be copied together with the polyfills. The files the application These files need to be copied together with the polyfills. The files the application
needs at runtime, like the `.json` phone lists and images, also need to be copied. needs at runtime, like the `.json` phone lists and images, also need to be copied.
Install `fs-extra` via `npm install fs-extra --save-dev` for better file copying, and change Install `fs-extra` using `npm install fs-extra --save-dev` for better file copying, and change
`copy-dist-files.js` to the following: `copy-dist-files.js` to the following:
<code-example path="upgrade-phonecat-2-hybrid/copy-dist-files.js" header="copy-dist-files.js"> <code-example path="upgrade-phonecat-2-hybrid/copy-dist-files.js" header="copy-dist-files.js">
@ -1729,13 +1729,13 @@ Like all routers, it needs a place in the UI to display routed views.
For Angular that's the `<router-outlet>` and it belongs in a *root component* For Angular that's the `<router-outlet>` and it belongs in a *root component*
at the top of the applications component tree. at the top of the applications component tree.
You don't yet have such a root component, because the app is still managed as an AngularJS app. You don't yet have such a root component, because the application is still managed as an AngularJS app.
Create a new `app.component.ts` file with the following `AppComponent` class: Create a new `app.component.ts` file with the following `AppComponent` class:
<code-example path="upgrade-phonecat-3-final/app/app.component.ts" header="app/app.component.ts"> <code-example path="upgrade-phonecat-3-final/app/app.component.ts" header="app/app.component.ts">
</code-example> </code-example>
It has a simple template that only includes the `<router-outlet>`. It has a template that only includes the `<router-outlet>`.
This component just renders the contents of the active route and nothing else. This component just renders the contents of the active route and nothing else.
The selector tells Angular to plug this root component into the `<phonecat-app>` The selector tells Angular to plug this root component into the `<phonecat-app>`
@ -1765,7 +1765,7 @@ instead of the default "push state" strategy.
Now update the `AppModule` to import this `AppRoutingModule` and also the Now update the `AppModule` to import this `AppRoutingModule` and also the
declare the root `AppComponent` as the bootstrap component. declare the root `AppComponent` as the bootstrap component.
That tells Angular that it should bootstrap the app with the _root_ `AppComponent` and That tells Angular that it should bootstrap the application with the _root_ `AppComponent` and
insert its view into the host web page. insert its view into the host web page.
You must also remove the bootstrap of the AngularJS module from `ngDoBootstrap()` in `app.module.ts` You must also remove the bootstrap of the AngularJS module from `ngDoBootstrap()` in `app.module.ts`
@ -1868,7 +1868,7 @@ break during the upgrade. E2E tests are especially useful for this purpose.
The PhoneCat project has both E2E Protractor tests and some Karma unit tests in it. The PhoneCat project has both E2E Protractor tests and some Karma unit tests in it.
Of these two, E2E tests can be dealt with much more easily: By definition, Of these two, E2E tests can be dealt with much more easily: By definition,
E2E tests access the application from the *outside* by interacting with E2E tests access the application from the *outside* by interacting with
the various UI elements the app puts on the screen. E2E tests aren't really that the various UI elements the application puts on the screen. E2E tests aren't really that
concerned with the internal structure of the application components. That concerned with the internal structure of the application components. That
also means that, although you modify the project quite a bit during the upgrade, the E2E also means that, although you modify the project quite a bit during the upgrade, the E2E
test suite should keep passing with just minor modifications. You test suite should keep passing with just minor modifications. You
@ -1878,7 +1878,7 @@ During TypeScript conversion, there is nothing to do to keep E2E tests
working. But when you change the bootstrap to that of a Hybrid app, working. But when you change the bootstrap to that of a Hybrid app,
you must make a few changes. you must make a few changes.
Update the `protractor-conf.js` to sync with hybrid apps: Update the `protractor-conf.js` to sync with hybrid applications:
<code-example format=""> <code-example format="">
ng12Hybrid: true ng12Hybrid: true
@ -1991,7 +1991,7 @@ For PhoneCat you need to make the following changes in order to make things work
When the bootstrap method is switched from that of `UpgradeModule` to When the bootstrap method is switched from that of `UpgradeModule` to
pure Angular, AngularJS ceases to exist on the page completely. pure Angular, AngularJS ceases to exist on the page completely.
At this point, you need to tell Protractor that it should not be looking for At this point, you need to tell Protractor that it should not be looking for
an AngularJS app anymore, but instead it should find *Angular apps* from an AngularJS application anymore, but instead it should find *Angular apps* from
the page. the page.
Replace the `ng12Hybrid` previously added with the following in `protractor-conf.js`: Replace the `ng12Hybrid` previously added with the following in `protractor-conf.js`: