Docs

此页面是从官方文档 http://vaadin.com/docs 机器翻译而来，可能包含错误、不准确或误述。Vaadin 不保证翻译的准确性、可靠性或及时性，也不对此承担责任。

Docs

渐进式 Web 应用程序（PWA）

将您的应用程序配置为渐进式 Web 应用程序。

通过一些额外的配置，Vaadin 应用程序可作为_渐进式 Web 应用程序（Progressive Web Application）_（PWA）运行。PWA 旨在提供与原生应用程序相同的体验，具有友好的安装过程，并且支持离线工作。在移动设备主屏桌面或桌面操作系统的应用程序菜单内，PWA 看起来与常规应用程序完全相同。PWA 需要一些元数据，例如应用名称、描述和图标，操作系统使用这些元数据显示应用程序信息。

要启用离线使用，需要使用 TypeScript 来提供离线视图。推荐使用 Hilla 框架来构建客户端视图。

有关 PWA 的一般介绍，请参见 什么是渐进式 Web 应用程序以及为何要构建 PWA 一文。

渐进式 Web 应用程序概念

所有 PWA 都有以下共同特性，以实现类似原生应用的行为：

Web Application Manifest

清单提供有关应用程序信息，例如名称、主题、图标和描述。这些信息是创建可安装版本的 Web 应用程序所必需的。

更多定义清单的细节，请参见 PWA Web 应用程序清单（Web Application Manifest）。

Service Worker

Service worker 是一种_Web Worker_，即一种在后台运行的 JavaScript 程序。它能够拦截网络请求，从而直接从浏览器缓存中提供文件，即使没有网络也可以创建完整的应用程序体验。

本质上，它是一个：

  • 独立于浏览器主线程运行的 JavaScript 文件；

  • 拦截网络请求；

  • 从缓存中缓存和检索资源；

  • 提供推送（Push）消息。

更多定义 service worker 的细节，请参见 PWA Service Worker。

使用 Flow 创建 PWA

当您在 Application Shell 中使用 @PWA 注解时，Vaadin Flow 会自动提供 PWA 所需的所有资源。@PWA 注解必须放在 Application Shell 类中。

例如，可使用下述方式自动提供 PWA 资源：

Source code
Java
@PWA(name = "My Progressive Web Application",
     shortName = "MyPWA")
public class AppShell implements AppShellConfigurator {
}

Vaadin 服务器自动提供 manifest、service worker、icons 和offline experience，并将所需信息添加到应用程序头部。

shortName 参数不得超过 12 个字符。更多有关可以使用的 @PWA 注解参数，请参见 PWA Web 应用程序清单（Web Application Manifest）。

应用程序安装要求

为支持设备安装，需要以下功能。具体实现依赖所使用的设备和浏览器：

图标（Icons）

需要不同尺寸的图标以支持不同设备。此外，为提升用户体验，启动画面图像也必需。

离线支持（Offline support）

当网络不可用时，service worker 必须能够向客户端提供响应。

头信息（Header information）

应用程序必须在头部分包含特定于浏览器或设备的主题和图标数据。这是清单文件的补充。

HTTPS

许多新的浏览器功能（包括 PWA 所需的功能）都要求 HTTPS。即使您的 PWA 当前在某些环境（例如 Android）上仍能在没有 HTTPS 的情况下工作，但这种状况很可能发生变化，未来不支持 HTTPS 的 PWA 有可能无法正常工作。

PWA Web 应用程序清单（Web Application Manifest）

发现 @PWA 注解后，Vaadin 自动生成名为 manifest.webmanifest 的 web 应用程序清单文件。

下面列出了可以自定义的文件属性。除 scope 外，所有属性都可在 @PWA 注解中设定。

name

应用程序名称。在 @PWA 注解的 name 参数中设置此属性。

short_name

应用程序短名称。不应超过 12 个字符。用于设备主屏幕，空间有限。在 @PWA 注解的 shortName 参数中设置此属性。

description

应用程序描述。默认值为空字符串。在 @PWA 注解的 description 参数中设置此属性。

display

定义应用程序首选的显示模式。默认值为 standalone。在 @PWA 注解的 display 参数中设置此属性。

background_color

应用程序的背景颜色。默认值为灰色 #f2f2f2。在 @PWA 注解的 backgroundColor 参数中设置此属性。

theme_color

应用程序主题颜色。默认值为白色 #ffffff。在 @PWA 注解的 backgroundColor 参数中设置此属性。

scope

定义网站上下文导航范围，即当应用清单被应用时能够查看的页面范围。该值设置为应用程序的上下文路径。无法在 @PWA 注解中更改该属性。

start_url

从已安装应用程序（主屏幕）启动时导航的起始 URL。默认值为空字符串 ""，指向应用程序默认的路由目标（用 @Route("") 注解标记）。在 @PWA 注解中的 startPath 参数设置此属性。

icons

自动从 图标资源 创建。

Note
 详细的属性信息，请查看 Mozilla Developer Network (MDN) Web 文档中的 Web 应用程序清单。

重命名清单

您可通过在 @PWA 注解中的 manifestPath 参数，修改清单文件默认名称（manifest.webmanifest）。

修改示例：

Source code
Java
@PWA(name = "My Progressive Web Application",
     shortName = "MyPWA",
     manifestPath = "manifest.json")

覆盖自动生成的清单

您可以用自定义清单覆盖自动生成的清单文件：

  1. 创建与 manifestPath 参数（在 @PWA 注解中）指定文件名匹配的清单文件，例如 manifest.webmanifest；

  2. 将文件保存到您的 src/main/webapp/ 文件夹中。

PWA Service Worker

当存在 @PWA 注解时，Vaadin 在应用程序启动阶段自动生成了一个简单的 service worker。

自动生成的 service worker：

  • 缓存 离线资源（包括 TypeScript 视图、离线页面、图标和自定义离线资源）；

  • 通过提供 TypeScript 视图或单独的离线页面提供 离线体验。

Note
 Service worker 只能响应完全导航事件，例如刷新或直接通过 URL 导航。

Service worker 使用 Google Workbox 缓存资源。

定义自定义缓存资源

您可使用 @PWA 注解的 offlineResources 参数，定义自动缓存资源。

PWA 应用程序图标

PWA 至少需要三个图标：浏览页面上的 favicon、已安装应用程序的设备图标，以及应用启动画面图标。

PWA 离线体验

Vaadin 支持两种构建离线体验的方式：

  • 客户端 TypeScript 视图（默认）

  • 独立的离线页面

更多信息请参见对应的原文部分以保持完整性。