为 Chrome 中第三方 Cookie 的停用做好准备。立即测试您的网站是否存在任何服务中断问题。

此页面由 Cloud Translation API 翻译。

Web 应用清单

Web 应用清单是您创建的一种文件，用于告知浏览器您希望自己的 Web 内容在操作系统中如何显示为应用。该清单可以包含基本信息，例如应用名称、图标和主题颜色；高级偏好设置，例如所需的屏幕方向和应用快捷方式；以及目录元数据，例如屏幕截图。

每个 PWA 都应为每个应用包含一个清单，该清单通常托管在根文件夹中，并在可以从所有可安装 PWA 的 HTML 页面上提供相应链接。其官方扩展名为 .webmanifest，因此您可以将清单命名为 app.webmanifest 之类的名称。

注意：虽然建议的扩展名为 .webmanifest，但只要随 application/manifest+json 内容类型或其他 JSON 有效的内容类型（例如 text/json）一起提交，就可以使用任何文件名。因此，许多 PWA（尤其是旧版 PWA）改用 manifest.json。

向 PWA 添加 Web 应用清单

如需创建 Web 应用清单，请先创建一个包含 JSON 对象的文本文件，其中至少包含具有字符串值的 name 字段：

app.webmanifest:

{
   "name": "My First Application"
}

但创建文件是不够的，浏览器也需要知道它存在。

链接到清单

如需让浏览器感知您的 Web 应用清单，您需要使用 <link> HTML 元素，并在 PWA 的所有 HTML 页面上将 rel 属性设置为 manifest，以将其关联到您的 PWA。这与将 CSS 样式表链接到文档的方式类似。

index.html:

<html lang="en">
  <title>This is my first PWA</title>
  <link rel="manifest" href="/app.webmanifest">

调试清单

为确保清单已正确设置，您可以在 Firefox 中使用检查器，并在每个基于 Chromium 的浏览器中使用开发者工具。

如果您看到一条消息，指出浏览器未检测到清单，并且您已将 <link> 正确添加到其中，请检查以确保您可以在浏览器中加载清单，并且其内容类型已正确设置。您也可以尝试将其重命名为 manifest.json。

适用于 Chromium 浏览器

在开发者工具中

在左侧窗格的应用下，选择清单。
检查浏览器解析的清单字段。

适用于 Firefox

打开检查器。
转到“Application”（应用）标签页。
在左侧面板中选择“清单”选项。
检查浏览器解析的清单字段。

设计您的 PWA 体验

将 PWA 与其清单关联后，您就可以填写其余字段了，以便为用户定义体验。

警告：在定义 Web 应用清单规范之前，一些浏览器（包括 iOS/iPadOS 上的 Safari 和 Android 上的 Chrome）都支持自定义 <meta> 元素（例如 apple-mobile-web-app-capable）来描述应用体验。目前不要使用这些 <meta> 元素；我们已不再推荐使用这些元素，而且当浏览器无法正确加载清单时，安装体验可能会受到影响；您获得的后备体验可能会有所不同且出乎意料。

基本字段

第一组字段表示有关 PWA 的核心信息。它们用于构建已安装 PWA 的图标和窗口，并确定其启动方式。它们是：

name: 您的 PWA 的全名。此图标会与图标一起显示在操作系统的主屏幕、启动器、Dock 或菜单中。
short_name: 可选，即您的 PWA 的较短名称，在没有足够的空间来显示 name 字段的全部值时使用。请将字符数控制在 12 个以内，以尽可能降低被截断的可能性。
icons: 包含 src、type、sizes 和可选 purpose 字段的图标对象数组，描述应表示 PWA 的图片。
start_url: 当用户通过已安装的图标启动 PWA 时，该应用应加载的网址。建议使用绝对路径，因此，如果 PWA 的首页是您网站的根目录，您可以将此属性设为“/”，以便在应用启动时打开该页面。如果您未提供启动网址，浏览器可以使用安装 PWA 时所用的网址作为起始网址。它可以是深层链接，例如产品的详细信息，而不是主屏幕。
display: fullscreen、standalone、minimal-ui 或 browser 之一，用于描述操作系统应如何绘制 PWA 窗口。您可以在“应用设计”章节中详细了解不同的显示模式。大多数用例都实现了 standalone。
id: 一个字符串，用于对照可托管在同一源上的其他 PWA 独一无二地标识此 PWA。如果未设置，start_url 将用作后备值。请注意，如果日后更改 start_url（例如，更改查询字符串值时），浏览器可能无法检测已安装 PWA。

注意：如果您在 2021 年 9 月之前发布了 PWA，请立即阅读使用 Web 应用清单 ID 属性唯一标识 PWA 了解添加 id 资源的最佳做法。

图标

PWA 的图标是 PWA 在用户设备上安装后的视觉标识，因此请务必定义至少一个图标。由于 icons 属性是图标对象的集合，因此您可以定义多个不同格式的图标，以便为用户提供最佳图标体验。每个浏览器都会根据自身的需求和安装的操作系统来挑选一个或多个图标，图标越接近所需的规格。

如果您只需要选择一个图标大小，那么它应该为 512 x 512 像素。不过，我们建议您提供更多尺寸的图片，包括 192 x 192、384 x 384 和 1024 x 1024 像素的图片。

"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]

如果您没有提供图标，或者图标的尺寸不符合建议的尺寸，那么在某些平台上就不符合安装条件。在其他平台上，系统会自动生成图标，例如根据 PWA 的屏幕截图或使用通用图标生成图标。

可遮盖式图标

有些操作系统（如 Android）会根据不同的大小和形状调整图标。例如，在 Android 12 中，不同的制造商或设置可能会将图标形状从圆形更改为方形，再改为圆角方形。如需支持这些类型的自适应图标，您可以使用 purpose 字段提供可遮盖图标。

为此，请提供一个方形图片文件，其主图标位于“安全区域”内，一个以图标为中心、半径为图标宽度 40% 的圆圈。（如下图所示。）支持可遮盖图标的设备将根据需要遮盖图标。

方形图标内以 40% 半径为中心的圆圈表示的安全区域

下例中的可遮盖图标以多种常用形状渲染：

在下图中，如果您将左侧的图标用作可遮盖图标，那么应用形状蒙版后，最终在设备上的显示效果会很糟糕。

此图片可通过更多内边距使用。

可遮盖图标的大小至少为 512 x 512。创建好后，您就可以将其添加到 icons 集合中，以改善受支持设备的体验：

"icons": [
   {
      "src": "/icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "/icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   },
   {
      "src": "/icons/512-maskable.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
   },
]

在大多数情况下，如果可遮盖图标的显示效果不理想，您可以通过添加更多内边距来改善显示效果。Maskable.app 是一款免费的在线工具，用于测试和创建可遮盖式图标的图标版本。

建议字段

下一组需要包含的字段可以改善用户体验，尽管它们并不是安装性所必需的字段。

theme_color: 应用的默认颜色，有时会影响操作系统显示网站的方式（例如，桌面设备上的窗口和标题栏颜色，或移动设备上的状态栏颜色）。此颜色可被 HTML theme-color <meta> 元素替换。
background_color: 在应用样式表加载之前要在应用背景中显示的占位符颜色。iOS 和 iPadOS 上的 Safari 以及大多数桌面浏览器目前会忽略此字段。
scope: 更改 PWA 的导航范围，让您能够定义在已安装应用的窗口中显示和不显示哪些内容。例如，如果您链接到的网页不在该范围内，则该网页会在应用内浏览器中（而不是在 PWA 窗口中）呈现。不过，这不会更改 Service Worker 的作用域。

下图显示了当您安装 PWA 时，桌面设备上标题栏的 theme_color 字段是怎样的。

在桌面设备上安装的同一 PWA 采用不同主题颜色。

注意：如果您要为深色模式和浅色模式提供不同的主题颜色，可以使用媒体查询（例如使用 <meta name="theme-color" content="red" media="(prefers-color-scheme: dark)">）在 HTML 中使用元标记替换清单的值

在清单中（例如，在 theme_color 和 background_color 内）定义颜色时，您应使用 CSS 具名颜色（例如 salmon 或 orange）、RGB 颜色（例如 #FF5500）或颜色函数（例如 rgb() 或 hsl()）。如需了解详情，请参阅应用设计一章。

警告：请勿使用透明度、CSS 变量、渐变函数或有透明度的颜色函数（例如 rgba()），因为大多数浏览器都不支持它们。您将会获得不一致的结果。

试试看

启动画面

在某些设备上，系统会在加载 PWA 时渲染静态图片，以向用户提供即时反馈。

Android 使用 theme_color、background_color 和 icon 值生成启动画面。

当您在 Android 上安装 PWA 时，设备会生成启动画面，其中包含来自清单的信息，如下图所示。

Android 启动画面中的 PWA 从清单中获取不同的值。

另一方面，iOS 和 iPadOS 上的 Safari 不使用网络应用清单来生成启动画面。而是使用从专有 <link> 元素链接的图片，这与处理图标的方式类似。如需了解详情，请参阅增强功能一章。

扩展字段

下一组字段提供有关 PWA 的额外信息。它们都是可选的。

lang: 一个语言标记，用于指定清单值的主要语言，例如 en 表示英语，pt-BR 表示巴西葡萄牙语，in 表示印地语。
dir: 支持方向的清单字段（例如 name、short_name 和 description）的显示方向。有效值为 auto、ltr（从左到右）和 rtl（从右到左）。
orientation: 安装应用后的预期屏幕方向。游戏可以将其设置为请求仅限横向方向。可接受多个值，但如果包含值，则通常为 portrait 或 landscape。

促销字段

通过第四组字段，您可以在安装流程、列表和搜索结果中提供有关 PWA 的宣传信息。

description: 介绍 PWA 的用途。
screenshots: 屏幕截图对象数组，包含 src、type 和 sizes（类似于 icons 对象），用于展示 PWA。没有大小限制。
categories: PWA 应属于的类别数组用作列表提示，可以选择来自已知类别列表。这些值通常为小写形式。
iarc_rating_id: PWA 的国际年龄分级联盟认证代码（如果有）。它旨在确定您的 PWA 适合哪些年龄段。

您现在就可以看到这些推广字段的实际运用。例如，在 Android 上，如果您的 PWA 是可安装的，并且您至少为 description 和 screenshots 字段提供了值，安装对话框体验将从简单的“添加到主屏幕”信息栏转变为内容更丰富的安装对话框，类似于应用商店中的对话框。

在 Android 上，如果您为推广字段提供值，则可以获得更美观的安装界面，正如下一个视频所示

请参考以下推广字段的实际运用：

功能字段

最后，您的 PWA 可以在受支持的浏览器中使用许多与不同功能相关的字段，例如 shortcuts、share_target、display_overrides 字段（如“功能”章节中所述）。此外，还有 related_apps 和 prefer_related_apps 等字段（如需了解详情，请参阅检测章节），用于将 PWA 连接到已安装的应用（通常来自应用商店）。

随着浏览器为渐进式 Web 应用添加更多功能，未来可能会出现许多新的字段。