diff --git a/aio/content/guide/service-worker-config.md b/aio/content/guide/service-worker-config.md index a67d935a79..aaec1ea491 100644 --- a/aio/content/guide/service-worker-config.md +++ b/aio/content/guide/service-worker-config.md @@ -2,6 +2,8 @@ # Service worker configuration +# Service Worker 配置 + #### Prerequisites #### 前提条件 @@ -12,6 +14,8 @@ A basic understanding of the following: * [Service Worker in Production](guide/service-worker-devops). + [产品环境下的 Service Worker](guide/service-worker-devops). +
The `src/ngsw-config.json` configuration file specifies which files and data URLs the Angular @@ -19,6 +23,10 @@ service worker should cache and how it should update the cached files and data. CLI processes the configuration file during `ng build --prod`. Manually, you can process it with the `ngsw-config` tool: +配置文件 `src/ngsw-config.json` 指定了 Angular Service Worker 应该缓存哪些文件和数据的 URL,以及如何更新缓存的文件和数据。 +CLI 会在 `ng build --prod` 期间处理配置文件。 +如果想手动,你可以使用 `ngsw-config` 工具来处理它: + ```sh ngsw-config dist src/ngsw-config.json /base/href @@ -27,39 +35,72 @@ ngsw-config dist src/ngsw-config.json /base/href The configuration file uses the JSON format. All file paths must begin with `/`, which is the deployment directory—usually `dist` in CLI projects. +该配置文件使用 JSON 格式。 +所有文件路径必须以 `/` 开头,也就是部署目录 —— 在 CLI 项目中的它通常是 `dist`。 + Patterns use a limited glob format: +它的模式使用受限的 glob 格式: + * `**` matches 0 or more path segments. + `**` 匹配 0 到多段路径。 + * `*` matches exactly one path segment or filename segment. + `*` 只匹配一段路径或者文件名。 + * The `!` prefix marks the pattern as being negative, meaning that only files that don't match the pattern will be included. + `!` 前缀表示该模式是否定的,也就是说只包含与该模式不匹配的文件。 + Example patterns: +范例模式: + * `/**/*.html` specifies all HTML files. + `/**/*.html` 指定所有 HTML 文件。 + * `/*.html` specifies only HTML files in the root. + `/*.html` 仅指定根目录下的 HTML 文件。 + * `!/**/*.map` exclude all sourcemaps. + `!/**/*.map` 排除了所有源码映射文件。 + 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. +该区允许你传递要用来描述这个特定应用版本的任何数据。 +`SwUpdate` 服务会在更新通知中包含这些数据。 +许多应用会使用该区来提供用于 UI 弹窗显示的附加信息,以通知用户有可用的更新。 + ## `index` Specifies the file that serves as the index page to satisfy navigation requests. Usually this is `/index.html`. +指定用来充当索引页的文件以满足导航请求。通常是`/index.html`。 + ## `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)*是与应用一起更新的应用版本的一部分。 +它们可以包含从页面的源地址加载的资源以及从 CDN 和其他外部 URL 加载的第三方资源。 +由于并非所有这些外部URL都能在构建时就知道,因此可以指定 URL 的模式。 + 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. +该字段包含一个资产组的数组,每个资产组中会定义一组资产资源和它们的缓存策略。 + ```json { @@ -74,8 +115,13 @@ This field contains an array of asset groups, each of which defines a set of ass Each asset group specifies both a group of resources and a policy that governs them. This policy determines when the resources are fetched and what happens when changes are detected. +每个资产组都会指定一组资源和一个管理它们的策略。 +此策略用来决定何时获取资源以及当检测到更改时会发生什么。 + Asset groups follow the Typescript interface shown here: +这些资产组会遵循这里显示的 Typescript 接口: + ```typescript interface AssetGroup { @@ -95,14 +141,25 @@ interface AssetGroup { A `name` is mandatory. It identifies this particular group of assets between versions of the configuration. +`name` 是强制性的。它用来标识该配置文件版本中这个特定的资产组。 + ### `installMode` The `installMode` determines how these resources are initially cached. The `installMode` can be either of two values: +`installMode` 决定了这些资源最初的缓存方式。`installMode` 可以是以下两个值之一: + * `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` 告诉 Angular Service Worker 在缓存当前版本的应用时获取每一个列出的资源。 + 这是个带宽密集型的模式,但可以确保这些资源在被请求时可用,即使浏览器当前处于离线状态。 + * `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. + `lazy` 不会预先缓存任何资源。 相反,Angular Service Worker 只会缓存它收到请求的资源。 + 这是一种按需缓存模式。永远不会请求的资源也不会被缓存。 + 这对于像针对不同分辨率的图片之类的东西很有用,那样 Service Worker 就只会为特定的屏幕和方向缓存正确的资源。 + ### `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`. diff --git a/aio/content/guide/service-worker-devops.md b/aio/content/guide/service-worker-devops.md index 3d78cab0ee..0e8f700f7e 100644 --- a/aio/content/guide/service-worker-devops.md +++ b/aio/content/guide/service-worker-devops.md @@ -1,7 +1,12 @@ # Service worker in production +# 产品环境下的 Service Worker + 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 recourses and fail-safes. +本页讲的是如何使用 Angular Service Worker 发布和支持产品环境下的应用。 +它解释了 Angular Service Worker 如何满足大规模产品环境的需求、Service Worker 在多种条件下有哪些行为以及有哪些可用的资源和故障保护机制。 + #### Prerequisites #### 前提条件 @@ -12,26 +17,52 @@ A basic understanding of the following: * [Service Worker Communication](guide/service-worker-communications). + [与 Service Worker 通讯](guide/service-worker-communications). +
## Service worker and caching of app resources +## Service Worker 与应用资源的缓存 + 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. +从概念上说,你可以把 Angular Service Worker 想象成一个转发式缓存或装在最终用户浏览器中的 CDN 边缘。 +Service Worker 的工作是从本地缓存中满足 Angular 应用对资源或数据的请求,而不用等待网络。 +和所有缓存一样,它有一些规则来决定内容该如何过期或更新。 + {@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. +在 Angular Service Worker 的语境下,“版本”是指用来表示 Angular 应用的某一次构建成果的一组资源。 +当应用的一个新的构建发布时,Service Worker 就把它看做此应用的一个新版本。 +就算只修改了一个文件,也同样如此。 +在任何一个给定的时间,Service Worker 可能会在它的缓存中拥有此应用的多个版本,这几个版本也都能用于提供服务。 +要了解更多,参见稍后的 [App 选项卡](guide/service-worker-devops#tabs)。 + 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 `