Web 应用 Manifest

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

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

向您的 PWA 添加 Web 应用 Manifest

要创建 Web 应用 Manifest，首先创建一个文本文件，其中包含一个 JSON 对象，该对象至少包含一个带有字符串值的 name 字段

app.webmanifest

{
   "name": "My First Application"
}

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

链接到您的 Manifest

为了使浏览器意识到您的 Web 应用 Manifest，您需要使用 <link> HTML 元素和设置为 manifest 的 rel 属性将其链接到您的 PWA 的所有 HTML 页面上。这类似于您将 CSS 样式表链接到文档的方式。

index.html

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

调试 Manifest

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

对于 Chromium 浏览器

在 DevTools 中

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

对于 Firefox

  1. 打开 Inspector。
  2. 转到 Application 选项卡。
  3. 在左侧面板中选择 Manifest 选项。
  4. 检查浏览器解析的 Manifest 的字段。

设计您的 PWA 体验

现在您的 PWA 已连接到其 Manifest，是时候填写其余字段以定义用户的体验了。

基本字段

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

name
您的 PWA 的全名。它将与图标一起显示在操作系统的主屏幕、启动器、Dock 或菜单中。
short_name
可选，您的 PWA 的较短名称，当没有足够的空间显示 name 字段的完整值时使用。将其保持在 12 个字符以下，以最大限度地减少截断的可能性。
icons
图标对象数组，包含 src、type、sizes 和可选的 purpose 字段，描述哪些图像应代表 PWA。
start_url
用户从已安装的图标启动 PWA 时应加载的 URL。建议使用绝对路径，因此如果您的 PWA 的主页是您网站的根目录，您可以将其设置为“/”，以便在您的应用启动时打开它。如果您未提供启动 URL，浏览器可以使用从中安装 PWA 的 URL 作为启动 URL。它可以是深层链接，例如产品的详细信息，而不是您的主屏幕。
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% 的圆形。（请参见下图。）支持可屏蔽图标的设备将根据需要屏蔽您的图标。

The safe area marked as a 40 percent radius centered circle within the square icon

以下是可屏蔽图标以多种常用形状呈现的示例

在下图中，如果您使用左侧的图标作为可屏蔽图标，则当应用形状蒙版时，您将在设备上获得较差的结果。

An icon that is not suitable for a maskable icon.

通过添加更多内边距，可以使此图像可用。

The icon with more padding is suitable for masks.

可屏蔽图标应至少为 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 应用 Manifest 文档。

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

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

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

The same PWA installed on desktop with a different theme color.

在 Manifest 中定义颜色时，例如在 theme_color 和 background_color 中，您应该使用 CSS 命名颜色，例如 salmon 或 orange、RGB 颜色（例如 #FF5500）或不带透明度的颜色函数（例如 rgb() 或 hsl()）。有关更多信息，请查看应用设计章节。

试用一下

启动画面

在某些设备上，当您的 PWA 正在加载时，会呈现静态图像，以便向用户提供即时反馈。

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

当您在 Android 上安装 PWA 时，设备将使用来自您的 Manifest 的信息生成一个启动画面，如下图所示。

A PWA on Android splash screen taking different values from the manifest.

另一方面，iOS 和 iPadOS 上的 Safari 不使用 Web 应用 Manifest 来生成启动画面。相反，他们使用从专有的 <link> 元素链接的图像，类似于他们处理图标的方式。有关更多详细信息，请查看增强功能章节。

扩展字段

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

lang
一种语言标记，用于指定 Manifest 值的首选语言，例如英语的 en、巴西葡萄牙语的 pt-BR 或印地语的 in。
dir
用于显示支持方向的 Manifest 字段（例如 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 上，如果您为促销字段提供值，您可以获得更好的安装 UI，您可以在下一个视频中看到

查看这些促销字段的实际效果

功能字段

最后，有许多与您的 PWA 可以在受支持的浏览器中使用的不同功能相关的字段，例如 shortcuts、share_target、display_override 字段，正如我们在功能章节中所介绍的那样。还有一些字段，例如 related_apps 和 prefer_related_apps（有关更多信息，请参阅检测章节），用于将您的 PWA 连接到已安装的应用，通常来自应用商店。

当浏览器向渐进式 Web 应用添加更多功能时，将来可能会出现许多新字段。

资源