Web 应用清单

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

每个 PWA 应为每个应用包含一个清单，该清单通常托管在根文件夹中，并在可安装 PWA 的所有 HTML 页面上建立关联。其官方扩展名为 .webmanifest，因此您可以将清单命名为 app.webmanifest 等。

向 PWA 添加 Web 应用清单

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

app.webmanifest:

{
   "name": "My First Application"
}

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

关联到清单

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

index.html:

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

调试清单

为确保清单设置正确无误，您可以在 Firefox 中使用检查器，也可以在所有基于 Chromium 的浏览器中使用开发者工具。

对于 Chromium 浏览器

在 DevTools 中

  1. 在左侧窗格中，点击“应用”下方的清单。
  2. 检查浏览器解析的清单字段。

对于 Firefox

  1. 打开检查器。
  2. 前往“应用”标签页。
  3. 选择左侧面板中的“清单”选项。
  4. 检查浏览器解析的清单字段。

设计 PWA 体验

现在，您的 PWA 已与其清单相关联，接下来需要填写其余字段，为用户定义体验。

基本字段

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

name
您的 PWA 的完整名称。它将与图标一起显示在操作系统的主屏幕、启动器、底部工具栏或菜单中。
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 的功能。

图标

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 是一款免费的在线工具，可用于测试和创建可遮罩的图标版本。

如果您的图标用于一般用途且可遮盖，您可以将 purpose 字段设置为 "any maskable"。如需了解详情，请参阅 MDN Web 应用清单文档。

接下来要添加的字段有助于改善用户体验，但它们并非安装性所必需的。

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

下图展示了在您安装 PWA 时，theme_color 字段如何用于桌面设备上的标题栏。

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

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

试试看

启动画面

在某些设备上，系统会在加载 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_override 字段。此外，还有一些字段（例如 related_apps 和 prefer_related_apps，如需了解详情，请参阅“检测”章节），可将您的 PWA 与已安装的应用（通常来自应用商店）相关联。

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

资源