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 的浏览器中使用 DevTools。

对于 Chromium 浏览器

在开发者工具中

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

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

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 不会使用 Web 应用清单生成启动画面。而是使用从专有 <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 应用添加更多功能，未来可能会出现许多新字段。

资源