Web 应用清单

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

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

向 PWA 添加 Web 应用清单

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

app.webmanifest:

{
   "name": "My First Application"
}

但创建文件还不够，浏览器还需要知道此文件存在。

链接到您的清单

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

index.html:

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

调试清单

为确保清单设置正确，您可以在每个基于 Chromium 的浏览器中使用 Firefox 中的 Inspector 和 DevTools。

对于 Chromium 浏览器

在开发者工具中

  1. 在左侧窗格的 Application 下，选择 Manifest。
  2. 检查由浏览器解析的清单字段。

适用于 Firefox

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

设计 PWA 体验

现在，您的 PWA 已连接到其清单，接下来该填写其余字段以定义用户体验了。

基本字段

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

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

图标

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。
。

促销字段

通过第 4 组字段，您可以提供有关 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 应用添加更多功能，未来可能会出现许多新字段。

资源