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

docs: edits to remove jargon and abbreviations (#41530) 

PR Close #41530
This commit is contained in:
Teri Glover 2021-04-09 05:33:21 +00:00 committed by Andrew Kushnir
parent 9d8f345c0c
commit 391d08f6fb
13 changed files with 110 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
aio/content/guide/accessibility.md
View File

@ -12,7 +12,7 @@ work well for all users, including those who rely on assistive technologies.
<div class="alert is-helpful">
For the sample app that this page describes, see the <live-example></live-example>.
For the sample application that this page describes, see the <live-example></live-example>.
</div>
@ -84,7 +84,7 @@ You can see [`MatFormField`](https://material.angular.io/components/form-field/o
## Case study: Building a custom progress bar
The following example shows how to make a simple progress bar accessible by using host binding to control accessibility-related attributes.
The following example shows how to make a progress bar accessible by using host binding to control accessibility-related attributes.
* The component defines an accessibility-enabled element with both the standard HTML attribute `role`, and ARIA attributes. The ARIA attribute `aria-valuenow` is bound to the user's input.

8
aio/content/guide/app-shell.md
View File

@ -1,9 +1,9 @@
# App shell
App shell is a way to render a portion of your application via a route at build time.
Application shell is a way to render a portion of your application using a route at build time.
It can improve the user experience by quickly launching a static rendered page (a skeleton common to all pages) while the browser downloads the full client version and switches to it automatically after the code loads.
This gives users a meaningful first paint of your application that appears quickly because the browser can simply render the HTML and CSS without the need to initialize any JavaScript.
This gives users a meaningful first paint of your application that appears quickly because the browser can render the HTML and CSS without the need to initialize any JavaScript.
Learn more in [The App Shell Model](https://developers.google.com/web/fundamentals/architecture/app-shell).
@ -18,7 +18,7 @@ For an existing application, you have to manually add the `RouterModule` and def
## Step 2: Create the app shell
Use the CLI to automatically create the app shell.
Use the CLI to automatically create the application shell.
<code-example language="bash">
ng generate app-shell
@ -87,4 +87,4 @@ Or to use the production configuration.
ng run my-app:app-shell:production
</code-example>
To verify the build output, open `dist/my-app/browser/index.html`. Look for default text `app-shell works!` to show that the app shell route was rendered as part of the output.
To verify the build output, open `dist/my-app/browser/index.html`. Look for default text `app-shell works!` to show that the application shell route was rendered as part of the output.

42
aio/content/guide/deployment.md
View File

@ -13,7 +13,7 @@ Before fully deploying your application, you can test the process, build configu
### Building and serving from disk
During development, you typically use the `ng serve` command to build, watch, and serve the application from local memory, using [webpack-dev-server](https://webpack.js.org/guides/development/#webpack-dev-server).
When you are ready to deploy, however, you must use the `ng build` command to build the app and deploy the build artifacts elsewhere.
When you are ready to deploy, however, you must use the `ng build` command to build the application and deploy the build artifacts elsewhere.
Both `ng build` and `ng serve` clear the output folder before they build the project, but only the `ng build` command writes the generated build artifacts to the output folder.
@ -82,7 +82,7 @@ In the table below, you can find a list of packages which implement deployment f
| [NPM](https://npmjs.com/) | [`ngx-deploy-npm`](https://npmjs.org/package/ngx-deploy-npm) |
| [Amazon Cloud S3](https://aws.amazon.com/s3/?nc2=h_ql_prod_st_s3) | [`@jefiozie/ngx-aws-deploy`](https://www.npmjs.com/package/@jefiozie/ngx-aws-deploy) |
If you're deploying to a self-managed server or there's no builder for your favorite cloud platform, you can either create a builder that allows you to use the `ng deploy` command, or read through this guide to learn how to manually deploy your app.
If you're deploying to a self-managed server or there's no builder for your favorite cloud platform, you can either create a builder that allows you to use the `ng deploy` command, or read through this guide to learn how to manually deploy your application.
### Basic deployment to a remote server
@ -112,8 +112,8 @@ To deploy your Angular application to [GitHub Pages](https://help.github.com/art
1. [Create a GitHub repository](https://help.github.com/articles/create-a-repo/) for your project.
1. Configure `git` in your local project by adding a remote that specifies the GitHub repo you created in previous step.
GitHub provides these commands when you create the repo so that you can copy and paste them at your command prompt.
1. Configure `git` in your local project by adding a remote that specifies the GitHub repository you created in previous step.
GitHub provides these commands when you create the repository so that you can copy and paste them at your command prompt.
The commands should be similar to the following, though GitHub fills in your project-specific settings for you:
```sh
@ -165,17 +165,17 @@ This section covers changes you may have to make to the server or to files deplo
### Routed apps must fallback to `index.html`
Angular apps are perfect candidates for serving with a simple static HTML server.
Angular applications are perfect candidates for serving with a simple static HTML server.
You don't need a server-side engine to dynamically compose application pages because
Angular does that on the client-side.
If the app uses the Angular router, you must configure the server
If the application uses the Angular router, you must configure the server
to return the application's host page (`index.html`) when asked for a file that it does not have.
{@a deep-link}
A routed application should support "deep links".
A _deep link_ is a URL that specifies a path to a component inside the app.
A _deep link_ is a URL that specifies a path to a component inside the application.
For example, `http://www.mysite.com/heroes/42` is a _deep link_ to the hero detail page
that displays the hero with `id: 42`.
@ -264,7 +264,7 @@ modified to serve `index.html`:
[directly configure](https://github.com/isaacs/github/issues/408)
the GitHub Pages server, but you can add a 404 page.
Copy `index.html` into `404.html`.
It will still be served as the 404 response, but the browser will process that page and load the app properly.
It will still be served as the 404 response, but the browser will process that page and load the application properly.
It's also a good idea to
[serve from `docs/` on master](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch)
and to
@ -315,7 +315,7 @@ See [`ng build`](cli/build) for more about CLI build options and what they do.
### Enable runtime production mode
In addition to build optimizations, Angular also has a runtime production mode. Angular apps run in development mode by default, as you can see by the following message on the browser console:
In addition to build optimizations, Angular also has a runtime production mode. Angular applications run in development mode by default, as you can see by the following message on the browser console:
<code-example format="nocode">
@ -333,7 +333,7 @@ runtime production mode.
### Lazy loading
You can dramatically reduce launch time by only loading the application modules that
absolutely must be present when the app starts.
absolutely must be present when the application starts.
Configure the Angular Router to defer loading of all other modules (and their associated code), either by
[waiting until the app has launched](guide/router-tutorial-toh#preloading "Preloading")
@ -345,7 +345,7 @@ them on demand.
<header>Don't eagerly import something from a lazy-loaded module</header>
If you mean to lazy-load a module, be careful not to import it
in a file that's eagerly loaded when the app starts (such as the root `AppModule`).
in a file that's eagerly loaded when the application starts (such as the root `AppModule`).
If you do that, the module will be loaded immediately.
The bundling configuration must take lazy loading into consideration.
@ -366,8 +366,8 @@ which automatically recognizes lazy-loaded `NgModules` and creates separate bund
You can make better decisions about what to optimize and how when you have a clear and accurate understanding of
what's making the application slow.
The cause may not be what you think it is.
You can waste a lot of time and money optimizing something that has no tangible benefit or even makes the app slower.
You should measure the app's actual behavior when running in the environments that are important to you.
You can waste a lot of time and money optimizing something that has no tangible benefit or even makes the application slower.
You should measure the application's actual behavior when running in the environments that are important to you.
The
<a href="https://developers.google.com/web/tools/chrome-devtools/network-performance/understanding-resource-timing" title="Chrome DevTools Network Performance">
@ -391,7 +391,7 @@ Install `source-map-explorer`:
</code-example>
Build your app for production _including the source maps_
Build your application for production _including the source maps_
<code-example language="none" class="code-shell">
@ -419,7 +419,7 @@ The following example displays the graph for the _main_ bundle.
The `source-map-explorer` analyzes the source map generated with the bundle and draws a map of all dependencies,
showing exactly which classes are included in the bundle.
Here's the output for the _main_ bundle of an example app called `cli-quickstart`.
Here's the output for the _main_ bundle of an example application called `cli-quickstart`.
<div class="lightbox">
<img src="generated/images/guide/deployment/quickstart-sourcemap-explorer.png" alt="quickstart sourcemap explorer">
@ -442,13 +442,13 @@ See also the [*APP_BASE_HREF*](api/common/APP_BASE_HREF "API: APP_BASE_HREF") al
</div>
In development, you typically start the server in the folder that holds `index.html`.
That's the root folder and you'd add `<base href="/">` near the top of `index.html` because `/` is the root of the app.
That's the root folder and you'd add `<base href="/">` near the top of `index.html` because `/` is the root of the application.
But on the shared or production server, you might serve the app from a subfolder.
For example, when the URL to load the app is something like `http://www.mysite.com/my/app/`,
But on the shared or production server, you might serve the application from a subfolder.
For example, when the URL to load the application is something like `http://www.mysite.com/my/app/`,
the subfolder is `my/app/` and you should add `<base href="/my/app/">` to the server version of the `index.html`.
When the `base` tag is mis-configured, the app fails to load and the browser console displays `404 - Not Found` errors
When the `base` tag is mis-configured, the application fails to load and the browser console displays `404 - Not Found` errors
for the missing files. Look at where it _tried_ to find those files and adjust the base tag appropriately.
{@a differential-loading}
@ -655,7 +655,7 @@ In `angular.json` add two new configuration sections under the `build` and `serv
</code-example>
You can then run the `ng serve` command with this configuration. Make sure to replace `<app-name>` (in `"<app-name>:build:es5"`) with the actual name of the app, as it appears under `projects` in `angular.json`. For example, if your app name is `myAngularApp` the config will become `"browserTarget": "myAngularApp:build:es5"`.
You can then run the `ng serve` command with this configuration. Make sure to replace `<app-name>` (in `"<app-name>:build:es5"`) with the actual name of the app, as it appears under `projects` in `angular.json`. For example, if your application name is `myAngularApp` the configuration will become `"browserTarget": "myAngularApp:build:es5"`.
<code-example language="none" class="code-shell">
@ -727,7 +727,7 @@ Create an [ES5 serve configuration](guide/deployment#configuring-serve-for-es5)
</code-example>
You can then run the `ng e2e` command with this configuration. Make sure to replace `<app-name>` (in `"<app-name>:serve:es5"`) with the actual name of the app, as it appears under `projects` in `angular.json`. For example, if your app name is `myAngularApp` the config will become `"devServerTarget": "myAngularApp:serve:es5"`.
You can then run the `ng e2e` command with this configuration. Make sure to replace `<app-name>` (in `"<app-name>:serve:es5"`) with the actual name of the app, as it appears under `projects` in `angular.json`. For example, if your application name is `myAngularApp` the configuration will become `"devServerTarget": "myAngularApp:serve:es5"`.
<code-example language="none" class="code-shell">

6
aio/content/guide/lightweight-injection-tokens.md
View File

@ -9,10 +9,10 @@ This normally ensures that if a provided component or service is never actually
However, due to the way Angular stores injection tokens, it is possible that such an unused component or service can end up in the bundle anyway.
This page describes a dependency-injection design pattern that supports proper tree-shaking by using lightweight injection tokens.
The lightweight injection token design pattern is especially important for library developers. It ensures that when an application uses only some of your library's capabilities, the unused code can be eliminated from the client's app bundle.
The lightweight injection token design pattern is especially important for library developers. It ensures that when an application uses only some of your library's capabilities, the unused code can be eliminated from the client's application bundle.
When an application uses your library, there might be some services that your library supplies which the client app doesn't use.
In this case, the app developer should expect that service to be tree-shaken, and not contribute to the size of the compiled app.
When an application uses your library, there might be some services that your library supplies which the client application doesn't use.
In this case, the application developer should expect that service to be tree-shaken, and not contribute to the size of the compiled application.
Because the application developer cannot know about or remedy a tree-shaking problem in the library, it is the responsibility of the library developer to do so.
To prevent the retention of unused components, your library should use the lightweight injection token design pattern.

2
aio/content/guide/reusable-animations.md
View File

@ -13,7 +13,7 @@ The [AnimationOptions](api/animations/AnimationOptions) interface in Angular ani
## Creating reusable animations
To create a reusable animation, use the [`animation()`](api/animations/animation) method to define an animation in a separate `.ts` file and declare this animation definition as a `const` export variable. You can then import and reuse this animation in any of your app components using the [`useAnimation()`](api/animations/useAnimation) API.
To create a reusable animation, use the [`animation()`](api/animations/animation) method to define an animation in a separate `.ts` file and declare this animation definition as a `const` export variable. You can then import and reuse this animation in any of your application components using the [`useAnimation()`](api/animations/useAnimation) API.
<code-example path="animations/src/app/animations.ts" header="src/app/animations.ts" region="reusable" language="typescript"></code-example>

2
aio/content/guide/route-animations.md
View File

@ -47,7 +47,7 @@ The following configuration defines the possible routes for the application.
The `home` and `about` paths are associated with the `HomeComponent` and `AboutComponent` views. The route configuration tells the Angular router to instantiate the `HomeComponent` and `AboutComponent` views when the navigation matches the corresponding path.
In addition to `path` and `component`, the `data` property of each route defines the key animation-specific configuration associated with a route. The `data` property value is passed into `AppComponent` when the route changes. You can also pass additional data in route config that is consumed within the animation. The data property value has to match the transitions defined in the `routeAnimation` trigger, which we'll define later.
In addition to `path` and `component`, the `data` property of each route defines the key animation-specific configuration associated with a route. The `data` property value is passed into `AppComponent` when the route changes. You can also pass additional data in route configuration that is consumed within the animation. The data property value has to match the transitions defined in the `routeAnimation` trigger, which we'll define later.
<div class="alert is-helpful">

4
aio/content/guide/schematics-for-libraries.md
View File

@ -202,7 +202,7 @@ For details of these data structures and syntax, see the [Schematics README](htt
<code-example header="projects/my-lib/schematics/my-service/index.ts (Initial Rule)" path="schematics-for-libraries/projects/my-lib/schematics/my-service/index.1.ts" region="factory">
</code-example>
This simple rule factory returns the tree without modification.
This rule factory returns the tree without modification.
The options are the option values passed through from the `ng generate` command.
## Define a generation rule
@ -322,7 +322,7 @@ ng generate my-lib:my-service --name my-data
</code-example>
In the console, you will see that the schematic was run and the `my-data.service.ts` file was created in your app folder.
In the console, you will see that the schematic was run and the `my-data.service.ts` file was created in your application folder.
<code-example language="bash" hideCopy="true">

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

@ -180,7 +180,7 @@ safer coding practices. Trusted Types can also help simplify the auditing of app
<div class="callout is-helpful">
Trusted Types might not yet be available in all browsers your application targets. In the case your Trusted-Types-enabled application runs in a browser that doesn't support Trusted Types, the functionality of the application will be preserved, and your application will be guarded against XSS via Angular's DomSanitizer. See [caniuse.com/trusted-types](https://caniuse.com/trusted-types) for the current browser support.
Trusted Types might not yet be available in all browsers your application targets. In the case your Trusted-Types-enabled application runs in a browser that doesn't support Trusted Types, the functionality of the application will be preserved, and your application will be guarded against XSS by way of Angular's DomSanitizer. See [caniuse.com/trusted-types](https://caniuse.com/trusted-types) for the current browser support.
</div>

38
aio/content/guide/service-worker-communications.md
View File

@ -1,6 +1,6 @@
# Service worker communication
Importing `ServiceWorkerModule` into your `AppModule` doesn't just register the service worker, it also provides a few services you can use to interact with the service worker and control the caching of your app.
Importing `ServiceWorkerModule` into your `AppModule` doesn't just register the service worker, it also provides a few services you can use to interact with the service worker and control the caching of your application.
#### Prerequisites
@ -10,13 +10,13 @@ A basic understanding of the following:
## `SwUpdate` service
The `SwUpdate` service gives you access to events that indicate when the service worker has discovered an available update for your app or when it has activated such an update&mdash;meaning it is now serving content from that update to your app.
The `SwUpdate` service gives you access to events that indicate when the service worker has discovered an available update for your application or when it has activated such an update&mdash;meaning it is now serving content from that update to your application.
The `SwUpdate` service supports four separate operations:
* Getting notified of *available* updates. These are new versions of the app to be loaded if the page is refreshed.
* Getting notified of update *activation*. This is when the service worker starts serving a new version of the app immediately.
* Getting notified of *available* updates. These are new versions of the application to be loaded if the page is refreshed.
* Getting notified of update *activation*. This is when the service worker starts serving a new version of the application immediately.
* Asking the service worker to check the server for new updates.
* Asking the service worker to activate the latest version of the app for the current tab.
* Asking the service worker to activate the latest version of the application for the current tab.
### Available and activated updates
@ -30,31 +30,31 @@ You can use these events to notify the user of a pending update or to refresh th
### Checking for updates
It's possible to ask the service worker to check if any updates have been deployed to the server.
The service worker checks for updates during initialization and on each navigation request&mdash;that is, when the user navigates from a different address to your app.
The service worker checks for updates during initialization and on each navigation request&mdash;that is, when the user navigates from a different address to your application.
However, you might choose to manually check for updates if you have a site that changes frequently or want updates to happen on a schedule.
Do this with the `checkForUpdate()` method:
<code-example path="service-worker-getting-started/src/app/check-for-update.service.ts" header="check-for-update.service.ts"></code-example>
This method returns a `Promise` which indicates that the update check has completed successfully, though it does not indicate whether an update was discovered as a result of the check. Even if one is found, the service worker must still successfully download the changed files, which can fail. If successful, the `available` event will indicate availability of a new version of the app.
This method returns a `Promise` which indicates that the update check has completed successfully, though it does not indicate whether an update was discovered as a result of the check. Even if one is found, the service worker must still successfully download the changed files, which can fail. If successful, the `available` event will indicate availability of a new version of the application.
<div class="alert is-important">
In order to avoid negatively affecting the initial rendering of the page, `ServiceWorkerModule` waits for up to 30 seconds by default for the app to stabilize, before registering the ServiceWorker script.
Constantly polling for updates, for example, with [setInterval()](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval) or RxJS' [interval()](https://rxjs.dev/api/index/function/interval), will prevent the app from stabilizing and the ServiceWorker script will not be registered with the browser until the 30 seconds upper limit is reached.
In order to avoid negatively affecting the initial rendering of the page, `ServiceWorkerModule` waits for up to 30 seconds by default for the application to stabilize, before registering the ServiceWorker script.
Constantly polling for updates, for example, with [setInterval()](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval) or RxJS' [interval()](https://rxjs.dev/api/index/function/interval), will prevent the application from stabilizing and the ServiceWorker script will not be registered with the browser until the 30 seconds upper limit is reached.
Note that this is true for any kind of polling done by your application.
Check the {@link ApplicationRef#isStable isStable} documentation for more information.
You can avoid that delay by waiting for the app to stabilize first, before starting to poll for updates, as shown in the example above.
You can avoid that delay by waiting for the application to stabilize first, before starting to poll for updates, as shown in the example above.
Alternatively, you might want to define a different {@link SwRegistrationOptions#registrationStrategy registration strategy} for the ServiceWorker.
</div>
### Forcing update activation
If the current tab needs to be updated to the latest app version immediately, it can ask to do so with the `activateUpdate()` method:
If the current tab needs to be updated to the latest application version immediately, it can ask to do so with the `activateUpdate()` method:
<code-example path="service-worker-getting-started/src/app/prompt-update.service.ts" header="prompt-update.service.ts" region="sw-activate"></code-example>
@ -67,25 +67,25 @@ Therefore, it is recommended to reload the page once the promise returned by `ac
### Handling an unrecoverable state
In some cases, the version of the app used by the service worker to serve a client might be in a broken state that cannot be recovered from without a full page reload.
In some cases, the version of the application used by the service worker to serve a client might be in a broken state that cannot be recovered from without a full page reload.
For example, imagine the following scenario:
- A user opens the app for the first time and the service worker caches the latest version of the app.
Let's assume the app's cached assets include `index.html`, `main.<main-hash-1>.js` and `lazy-chunk.<lazy-hash-1>.js`.
- The user closes the app and does not open it for a while.
- After some time, a new version of the app is deployed to the server.
- A user opens the application for the first time and the service worker caches the latest version of the application.
Let's assume the application's cached assets include `index.html`, `main.<main-hash-1>.js` and `lazy-chunk.<lazy-hash-1>.js`.
- The user closes the application and does not open it for a while.
- After some time, a new version of the application is deployed to the server.
This newer version includes the files `index.html`, `main.<main-hash-2>.js` and `lazy-chunk.<lazy-hash-2>.js` (note that the hashes are different now, because the content of the files has changed).
The old version is no longer available on the server.
- In the meantime, the user's browser decides to evict `lazy-chunk.<lazy-hash-1>.js` from its cache.
Browsers may decide to evict specific (or all) resources from a cache in order to reclaim disk space.
- The user opens the app again.
- The user opens the application again.
The service worker serves the latest version known to it at this point, namely the old version (`index.html` and `main.<main-hash-1>.js`).
- At some later point, the app requests the lazy bundle, `lazy-chunk.<lazy-hash-1>.js`.
- At some later point, the application requests the lazy bundle, `lazy-chunk.<lazy-hash-1>.js`.
- The service worker is unable to find the asset in the cache (remember that the browser evicted it).
Nor is it able to retrieve it from the server (since the server now only has `lazy-chunk.<lazy-hash-2>.js` from the newer version).
In the above scenario, the service worker is not able to serve an asset that would normally be cached.
That particular app version is broken and there is no way to fix the state of the client without reloading the page.
That particular application version is broken and there is no way to fix the state of the client without reloading the page.
In such cases, the service worker notifies the client by sending an `UnrecoverableStateEvent` event.
You can subscribe to `SwUpdate#unrecoverable` to be notified and handle these errors.

22
aio/content/guide/service-worker-config.md
View File

@ -37,8 +37,8 @@ Each section of the configuration file is described below.
## `appData`
This section enables you to pass any data you want that describes this particular version of the app.
The `SwUpdate` service includes that data in the update notifications. Many apps use this section to provide additional information for the display of UI popups, notifying users of the available update.
This section enables you to pass any data you want that describes this particular version of the application.
The `SwUpdate` service includes that data in the update notifications. Many applications use this section to provide additional information for the display of UI popups, notifying users of the available update.
{@a index-file}
## `index`
@ -47,7 +47,7 @@ Specifies the file that serves as the index page to satisfy navigation requests.
## `assetGroups`
*Assets* are resources that are part of the app version that update along with the app. They can include resources loaded from the page's origin as well as third-party resources loaded from CDNs and other external URLs. As not all such external URLs may be known at build time, URL patterns can be matched.
*Assets* are resources that are part of the application version that update along with the application. They can include resources loaded from the page's origin as well as third-party resources loaded from CDNs and other external URLs. As not all such external URLs may be known at build time, URL patterns can be matched.
This field contains an array of asset groups, each of which defines a set of asset resources and the policy by which they are cached.
@ -101,7 +101,7 @@ A `name` is mandatory. It identifies this particular group of assets between ver
The `installMode` determines how these resources are initially cached. The `installMode` can be either of two values:
* `prefetch` tells the Angular service worker to fetch every single listed resource while it's caching the current version of the app. This is bandwidth-intensive but ensures resources are available whenever they're requested, even if the browser is currently offline.
* `prefetch` tells the Angular service worker to fetch every single listed resource while it's caching the current version of the application. This is bandwidth-intensive but ensures resources are available whenever they're requested, even if the browser is currently offline.
* `lazy` does not cache any of the resources up front. Instead, the Angular service worker only caches resources for which it receives requests. This is an on-demand caching mode. Resources that are never requested will not be cached. This is useful for things like images at different resolutions, so the service worker only caches the correct assets for the particular screen and orientation.
@ -109,7 +109,7 @@ Defaults to `prefetch`.
### `updateMode`
For resources already in the cache, the `updateMode` determines the caching behavior when a new version of the app is discovered. Any resources in the group that have changed since the previous version are updated in accordance with `updateMode`.
For resources already in the cache, the `updateMode` determines the caching behavior when a new version of the application is discovered. Any resources in the group that have changed since the previous version are updated in accordance with `updateMode`.
* `prefetch` tells the service worker to download and cache the changed resources immediately.
@ -124,7 +124,7 @@ This section describes the resources to cache, broken up into the following grou
* `files` lists patterns that match files in the distribution directory. These can be single files or glob-like patterns that match a number of files.
* `urls` includes both URLs and URL patterns that will be matched at runtime. These resources are not fetched directly and do not have content hashes, but they will be cached according to their HTTP headers. This is most useful for CDNs such as the Google Fonts service.<br>
_(Negative glob patterns are not supported and `?` will be matched literally; i.e. it will not match any character other than `?`.)_
_(Negative glob patterns are not supported and `?` will be matched literally; that is, it will not match any character other than `?`.)_
### `cacheQueryOptions`
@ -134,7 +134,7 @@ These options are used to modify the matching behavior of requests. They are pas
## `dataGroups`
Unlike asset resources, data requests are not versioned along with the app. They're cached according to manually-configured policies that are more useful for situations such as API requests and other data dependencies.
Unlike asset resources, data requests are not versioned along with the application. They're cached according to manually-configured policies that are more useful for situations such as API requests and other data dependencies.
This field contains an array of data groups, each of which defines a set of data resources and the policy by which they are cached.
@ -189,7 +189,7 @@ A list of URL patterns. URLs that match these patterns are cached according to t
* `?` is matched literally; that is, it matches *only* the character `?`.
### `version`
Occasionally APIs change formats in a way that is not backward-compatible. A new version of the app may not be compatible with the old API format and thus may not be compatible with existing cached resources from that API.
Occasionally APIs change formats in a way that is not backward-compatible. A new version of the application may not be compatible with the old API format and thus may not be compatible with existing cached resources from that API.
`version` provides a mechanism to indicate that the resources being cached have been updated in a backwards-incompatible way, and that the old cache entries&mdash;those from previous versions&mdash;should be discarded.
@ -240,7 +240,7 @@ To use this strategy set `strategy` to `freshness` and `timeout` to `0u` in `cac
This will essentially do the following:
1. Try to fetch from the network first.
2. If the network request does not complete after 0ms (i.e. immediately), fall back to the cache (ignoring cache age).
2. If the network request does not complete after 0ms (that is, immediately), fall back to the cache (ignoring cache age).
3. Once the network request completes, update the cache for future requests.
4. If the resource does not exist in the cache, wait for the network request anyway.
@ -264,7 +264,7 @@ The ServiceWorker will redirect navigation requests that don't match any `asset`
By default, these criteria are:
1. The URL must not contain a file extension (i.e. a `.`) in the last path segment.
1. The URL must not contain a file extension (that is, a `.`) in the last path segment.
2. The URL must not contain `__`.
<div class="alert is-helpful">
@ -277,7 +277,7 @@ To configure whether navigation requests are sent through to the network or not,
While these default criteria are fine in most cases, it is sometimes desirable to configure different rules. For example, you may want to ignore specific routes (that are not part of the Angular app) and pass them through to the server.
This field contains an array of URLs and [glob-like](#glob-patterns) URL patterns that will be matched at runtime. It can contain both negative patterns (i.e. patterns starting with `!`) and non-negative patterns and URLs.
This field contains an array of URLs and [glob-like](#glob-patterns) URL patterns that will be matched at runtime. It can contain both negative patterns (that is, patterns starting with `!`) and non-negative patterns and URLs.
Only requests whose URLs match _any_ of the non-negative URLs/patterns and _none_ of the negative ones will be considered navigation requests. The URL query will be ignored when matching.

69
aio/content/guide/service-worker-devops.md
View File

@ -1,6 +1,6 @@
# Service worker in production
This page is a reference for deploying and supporting production apps that use the Angular service worker. It explains how the Angular service worker fits into the larger production environment, the service worker's behavior under various conditions, and available resources and fail-safes.
This page is a reference for deploying and supporting production applications that use the Angular service worker. It explains how the Angular service worker fits into the larger production environment, the service worker's behavior under various conditions, and available resources and fail-safes.
#### Prerequisites
@ -9,23 +9,23 @@ A basic understanding of the following:
## Service worker and caching of app resources
Conceptually, you can imagine the Angular service worker as a forward cache or a CDN edge that is installed in the end user's web browser. The service worker's job is to satisfy requests made by the Angular app for resources or data from a local cache, without needing to wait for the network. Like any cache, it has rules for how content is expired and updated.
Conceptually, you can imagine the Angular service worker as a forward cache or a CDN edge that is installed in the end user's web browser. The service worker's job is to satisfy requests made by the Angular application for resources or data from a local cache, without needing to wait for the network. Like any cache, it has rules for how content is expired and updated.
{@a versions}
### App versions
In the context of an Angular service worker, a "version" is a collection of resources that represent a specific build of the Angular app. Whenever a new build of the app is deployed, the service worker treats that build as a new version of the app. This is true even if only a single file is updated. At any given time, the service worker may have multiple versions of the app in its cache and it may be serving them simultaneously. For more information, see the [App tabs](guide/service-worker-devops#tabs) section below.
In the context of an Angular service worker, a "version" is a collection of resources that represent a specific build of the Angular application. Whenever a new build of the application is deployed, the service worker treats that build as a new version of the application. This is true even if only a single file is updated. At any given time, the service worker may have multiple versions of the application in its cache and it may be serving them simultaneously. For more information, see the [App tabs](guide/service-worker-devops#tabs) section below.
To preserve app integrity, the Angular service worker groups all files into a version together. The files grouped into a version usually include HTML, JS, and CSS files. Grouping of these files is essential for integrity because HTML, JS, and CSS files frequently refer to each other and depend on specific content. For example, an `index.html` file might have a `<script>` tag that references `bundle.js` and it might attempt to call a function `startApp()` from within that script. Any time this version of `index.html` is served, the corresponding `bundle.js` must be served with it. For example, assume that the `startApp()` function is renamed to `runApp()` in both files. In this scenario, it is not valid to serve the old `index.html`, which calls `startApp()`, along with the new bundle, which defines `runApp()`.
To preserve application integrity, the Angular service worker groups all files into a version together. The files grouped into a version usually include HTML, JS, and CSS files. Grouping of these files is essential for integrity because HTML, JS, and CSS files frequently refer to each other and depend on specific content. For example, an `index.html` file might have a `<script>` tag that references `bundle.js` and it might attempt to call a function `startApp()` from within that script. Any time this version of `index.html` is served, the corresponding `bundle.js` must be served with it. For example, assume that the `startApp()` function is renamed to `runApp()` in both files. In this scenario, it is not valid to serve the old `index.html`, which calls `startApp()`, along with the new bundle, which defines `runApp()`.
This file integrity is especially important when lazy loading modules.
A JS bundle may reference many lazy chunks, and the filenames of the
lazy chunks are unique to the particular build of the app. If a running
app at version `X` attempts to load a lazy chunk, but the server has
lazy chunks are unique to the particular build of the application. If a running
application at version `X` attempts to load a lazy chunk, but the server has
updated to version `X + 1` already, the lazy loading operation will fail.
The version identifier of the app is determined by the contents of all
The version identifier of the application is determined by the contents of all
resources, and it changes if any of them change. In practice, the version
is determined by the contents of the `ngsw.json` file, which includes
hashes for all known content. If any of the cached files change, the file's
@ -33,12 +33,12 @@ hash will change in `ngsw.json`, causing the Angular service worker to
treat the active set of files as a new version.
With the versioning behavior of the Angular service worker, an application
server can ensure that the Angular app always has a consistent set of files.
server can ensure that the Angular application always has a consistent set of files.
#### Update checks
Every time the user opens or refreshes the application, the Angular service worker
checks for updates to the app by looking for updates to the `ngsw.json` manifest. If
checks for updates to the application by looking for updates to the `ngsw.json` manifest. If
an update is found, it is downloaded and cached automatically, and will be served
the next time the application is loaded.
@ -48,20 +48,20 @@ One of the potential side effects of long caching is inadvertently
caching an invalid resource. In a normal HTTP cache, a hard refresh
or cache expiration limits the negative effects of caching an invalid
file. A service worker ignores such constraints and effectively long
caches the entire app. Consequently, it is essential that the service worker
caches the entire application. Consequently, it is essential that the service worker
gets the correct content.
To ensure resource integrity, the Angular service worker validates
the hashes of all resources for which it has a hash. Typically for
an app created with the [Angular CLI](cli), this is everything in the `dist` directory covered by
an application created with the [Angular CLI](cli), this is everything in the `dist` directory covered by
the user's `src/ngsw-config.json` configuration.
If a particular file fails validation, the Angular service worker
attempts to re-fetch the content using a "cache-busting" URL
parameter to eliminate the effects of browser or intermediate
caching. If that content also fails validation, the service worker
considers the entire version of the app to be invalid and it stops
serving the app. If necessary, the service worker enters a safe mode
considers the entire version of the application to be invalid and it stops
serving the application. If necessary, the service worker enters a safe mode
where requests fall back on the network, opting not to use its cache
if the risk of serving invalid, broken, or outdated content is high.
@ -78,7 +78,7 @@ manifest are resources that were present in the `dist`
directory at the time the manifest was built. Other
resources, especially those loaded from CDNs, have
content that is unknown at build time or are updated
more frequently than the app is deployed.
more frequently than the application is deployed.
If the Angular service worker does not have a hash to validate
a given resource, it still caches its contents but it honors
@ -94,26 +94,26 @@ configured lifetimes.
### App tabs
It can be problematic for an app if the version of resources
It can be problematic for an application if the version of resources
it's receiving changes suddenly or without warning. See the
[Versions](guide/service-worker-devops#versions) section above
for a description of such issues.
The Angular service worker provides a guarantee: a running app
will continue to run the same version of the app. If another
instance of the app is opened in a new web browser tab, then
The Angular service worker provides a guarantee: a running application
will continue to run the same version of the application. If another
instance of the application is opened in a new web browser tab, then
the most current version of the app is served. As a result,
that new tab can be running a different version of the app
that new tab can be running a different version of the application
than the original tab.
It's important to note that this guarantee is **stronger**
than that provided by the normal web deployment model. Without
a service worker, there is no guarantee that code lazily loaded
later in a running app is from the same version as the initial
code for the app.
later in a running application is from the same version as the initial
code for the application.
There are a few limited reasons why the Angular service worker
might change the version of a running app. Some of them are
might change the version of a running application. Some of them are
error conditions:
* The current version becomes invalid due to a failed hash.
@ -124,10 +124,10 @@ use at any given moment and it cleans up versions when
no tab is using them.
Other reasons the Angular service worker might change the version
of a running app are normal events:
of a running application are normal events:
* The page is reloaded/refreshed.
* The page requests an update be immediately activated via the `SwUpdate` service.
* The page requests an update be immediately activated using the `SwUpdate` service.
### Service worker updates
@ -135,22 +135,21 @@ The Angular service worker is a small script that runs in web browsers.
From time to time, the service worker will be updated with bug
fixes and feature improvements.
The Angular service worker is downloaded when the app is first opened
and when the app is accessed after a period of inactivity. If the
The Angular service worker is downloaded when the application is first opened
and when the application is accessed after a period of inactivity. If the
service worker has changed, the service worker will be updated in the background.
Most updates to the Angular service worker are transparent to the
app&mdash;the old caches are still valid and content is still served
normally. However, occasionally a bugfix or feature in the Angular
service worker requires the invalidation of old caches. In this case,
the app will be refreshed transparently from the network.
the application will be refreshed transparently from the network.
### Bypassing the service worker
In some cases, you may want to bypass the service worker entirely and let the browser handle the
request instead. An example is when you rely on a feature that is currently not supported in service
workers (e.g.
[reporting progress on uploaded files](https://github.com/w3c/ServiceWorker/issues/1141)).
workers (for example, [reporting progress on uploaded files](https://github.com/w3c/ServiceWorker/issues/1141)).
To bypass the service worker you can set `ngsw-bypass` as a request header, or as a query parameter.
(The value of the header or query parameter is ignored and can be empty or omitted.)
@ -202,9 +201,9 @@ Driver state: NORMAL ((nominal))
There are two possible degraded states:
* `EXISTING_CLIENTS_ONLY`: the service worker does not have a
clean copy of the latest known version of the app. Older cached
clean copy of the latest known version of the application. Older cached
versions are safe to use, so existing tabs continue to run from
cache, but new loads of the app will be served from the network.
cache, but new loads of the application will be served from the network.
The service worker will try to recover from this state when a new
version of the application is detected and installed (that is,
when a new `ngsw.json` is available).
@ -230,7 +229,7 @@ state of the previous instance.
Latest manifest hash: eea7f5f464f90789b621170af5a569d6be077e5c
```
This is the SHA1 hash of the most up-to-date version of the app that the service worker knows about.
This is the SHA1 hash of the most up-to-date version of the application that the service worker knows about.
#### Last update check
@ -239,7 +238,7 @@ This is the SHA1 hash of the most up-to-date version of the app that the service
Last update check: never
```
This indicates the last time the service worker checked for a new version, or update, of the app. `never` indicates that the service worker has never checked for an update.
This indicates the last time the service worker checked for a new version, or update, of the application. `never` indicates that the service worker has never checked for an update.
In this example debug file, the update check is currently scheduled, as explained the next section.
@ -251,7 +250,7 @@ In this example debug file, the update check is currently scheduled, as explaine
Clients: 7b79a015-69af-4d3d-9ae6-95ba90c79486, 5bc08295-aaf2-42f3-a4cc-9e4ef9100f65
```
In this example, the service worker has one version of the app cached and
In this example, the service worker has one version of the application cached and
being used to serve two different tabs. Note that this version hash
is the "latest manifest hash" listed above. Both clients are on the
latest version. Each client is listed by its ID from the `Clients`
@ -347,7 +346,7 @@ the past on your site.
It is important to note that service workers don't work behind redirect. You
may have already encountered the error `The script resource is behind a redirect, which is disallowed`.
This can be a problem if you have to change your app's location. If you setup
This can be a problem if you have to change your application's location. If you setup
a redirect from the old location (for example `example.com`) to the new
location (for example `www.example.com`) the worker will stop working.
Also, the redirect won't even trigger for users who are loading the site

16
aio/content/guide/service-worker-intro.md
View File

@ -6,7 +6,7 @@ At its simplest, a service worker is a script that runs in the web browser and m
Service workers function as a network proxy. They intercept all outgoing HTTP requests made by the application and can choose how to respond to them. For example, they can query a local cache and deliver a cached response if one is available. Proxying isn't limited to requests made through programmatic APIs, such as `fetch`; it also includes resources referenced in HTML and even the initial request to `index.html`. Service worker-based caching is thus completely programmable and doesn't rely on server-specified caching headers.
Unlike the other scripts that make up an application, such as the Angular app bundle, the service worker is preserved after the user closes the tab. The next time that browser loads the application, the service worker loads first, and can intercept every request for resources to load the application. If the service worker is designed to do so, it can *completely satisfy the loading of the application, without the need for the network*.
Unlike the other scripts that make up an application, such as the Angular application bundle, the service worker is preserved after the user closes the tab. The next time that browser loads the application, the service worker loads first, and can intercept every request for resources to load the application. If the service worker is designed to do so, it can *completely satisfy the loading of the application, without the need for the network*.
Even across a fast reliable network, round-trip delays can introduce significant latency when loading the application. Using a service worker to reduce dependency on the network can significantly improve the user experience.
@ -27,33 +27,33 @@ The Angular service worker's behavior follows that design goal:
To support these behaviors, the Angular service worker loads a *manifest* file from the server. The manifest describes the resources to cache and includes hashes of every file's contents. When an update to the application is deployed, the contents of the manifest change, informing the service worker that a new version of the application should be downloaded and cached. This manifest is generated from a CLI-generated configuration file called `ngsw-config.json`.
Installing the Angular service worker is as simple as including an `NgModule`. In addition to registering the Angular service worker with the browser, this also makes a few services available for injection which interact with the service worker and can be used to control it. For example, an application can ask to be notified when a new update becomes available, or an application can ask the service worker to check the server for available updates.
Installing the Angular service worker is as easy as including an `NgModule`. In addition to registering the Angular service worker with the browser, this also makes a few services available for injection which interact with the service worker and can be used to control it. For example, an application can ask to be notified when a new update becomes available, or an application can ask the service worker to check the server for available updates.
## Prerequisites
To make use of all the features of Angular service worker, use the latest versions of Angular and the Angular CLI.
In order for service workers to be registered, the app must be accessed over HTTPS, not HTTP.
In order for service workers to be registered, the application must be accessed over HTTPS, not HTTP.
Browsers ignore service workers on pages that are served over an insecure connection.
The reason is that service workers are quite powerful, so extra care needs to be taken to ensure the service worker script has not been tampered with.
There is one exception to this rule: to make local development easier, browsers do _not_ require a secure connection when accessing an app on `localhost`.
There is one exception to this rule: to make local development easier, browsers do _not_ require a secure connection when accessing an application on `localhost`.
### Browser support
To benefit from the Angular service worker, your app must run in a web browser that supports service workers in general.
To benefit from the Angular service worker, your application must run in a web browser that supports service workers in general.
Currently, service workers are supported in the latest versions of Chrome, Firefox, Edge, Safari, Opera, UC Browser (Android version) and Samsung Internet.
Browsers like IE and Opera Mini do not support service workers.
If the user is accessing your app via a browser that does not support service workers, the service worker is not registered and related behavior such as offline cache management and push notifications does not happen.
If the user is accessing your application with a browser that does not support service workers, the service worker is not registered and related behavior such as offline cache management and push notifications does not happen.
More specifically:
* The browser does not download the service worker script and `ngsw.json` manifest file.
* Active attempts to interact with the service worker, such as calling `SwUpdate.checkForUpdate()`, return rejected promises.
* The observable events of related services, such as `SwUpdate.available`, are not triggered.
It is highly recommended that you ensure that your app works even without service worker support in the browser.
Although an unsupported browser ignores service worker caching, it will still report errors if the app attempts to interact with the service worker.
It is highly recommended that you ensure that your application works even without service worker support in the browser.
Although an unsupported browser ignores service worker caching, it will still report errors if the application attempts to interact with the service worker.
For example, calling `SwUpdate.checkForUpdate()` will return rejected promises.
To avoid such an error, you can check whether the Angular service worker is enabled using `SwUpdate.isEnabled()`.

6
aio/content/guide/updating.md
View File

@ -1,8 +1,8 @@
# Keeping your Angular projects up-to-date
Just like Web and the entire web ecosystem, Angular is continuously improving. Angular balances continuous improvement with a strong focus on stability and making updates easy. Keeping your Angular app up-to-date enables you to take advantage of leading-edge new features, as well as optimizations and bug fixes.
Just like Web and the entire web ecosystem, Angular is continuously improving. Angular balances continuous improvement with a strong focus on stability and making updates easy. Keeping your Angular application up-to-date enables you to take advantage of leading-edge new features, as well as optimizations and bug fixes.
This document contains information and resources to help you keep your Angular apps and libraries up-to-date.
This document contains information and resources to help you keep your Angular applications and libraries up-to-date.
For information about our versioning policy and practices&mdash;including
support and deprecation practices, as well as the release schedule&mdash;see [Angular versioning and releases](guide/releases "Angular versioning and releases").
@ -31,7 +31,7 @@ To review a complete list of changes, organized by version, see the [Angular cha
{@a checking-version-app}
## Checking your version of Angular
To check your app's version of Angular: From within your project directory, use the `ng version` command.
To check your application's version of Angular: From within your project directory, use the `ng version` command.
{@a checking-version-angular}