Web 应用清单

来自 MDN 文档：

网络应用清单（web app manifest）以 JSON 格式提供关于网络应用的信息；这是将网络应用下载并呈现给用户所必需的，类似于原生应用（例如，可安装到设备主屏幕，为用户提供更快的访问速度和更丰富的体验）。

注册网络应用清单

通常情况下，清单文件存储在网页应用的根目录下。它可以命名为 manifest.json，也可以是 anythingYouWant.webmanifest（只要文件扩展名为 .webmanifest 即可），并以媒体类型 application/manifest+json 提供。

为了将清单与网页应用关联，我们可以在 HTML 文档的 <head> 部分使用 <link> 标签（通常是 index.html）：

1<head>
2  <link rel="manifest" href="/manifest.webmanifest">
3</head>

上述代码表示，用户代理应采用清单中的元数据，而不是文档对象（即 HTML 文档的根节点）中的元数据。

如果某些属性设置不正确，用户代理将回退到文档的元数据。

清单请求不会携带任何凭据（即使它位于同一域名下）。因此，如果清单需要凭据，我们必须添加 crossorigin="use-credentials" 属性：

1<head>
2  <link rel="manifest" href="/manifest.webmanifest" crossorigin="use-credentials">
3</head>

如果未指定该属性，资源将以非 CORS 请求方式获取（即不发送 Origin HTTP 头），从而防止其被非污染使用。若值无效，则视为使用了枚举关键字 anonymous。

如果没有 cross-origin 属性，即便本地运行一切正常，部署后 manifest.json 文件仍可能引发错误。

错误信息通常较为笼统：

1Manifest: Line: 1, column: 1, Unexpected token.

大多数浏览器都支持清单文件。Safari 目前正在逐步增强对它的支持：

文件结构

1
2{
3  "short_name": "MyCoolPWA",
4  "name": "My cool Progressive Web App",
5  "orientation": "landscape",
6  "description": "A simple experiment with PWAs",
7  "background_color": "#3367D6",
8  "theme_color": "#3367D6",
9  "scope": "/",
10  "start_url": "/?source=pwa",
11  "display": "standalone",
12  "icons": [
13    {
14      "src": "/images/icons-144.png",
15      "type": "image/png",
16      "sizes": "144x144",
17      "purpose": "maskable any"
18    },    
19    {
20      "src": "/images/icons-192.png",
21      "type": "image/png",
22      "sizes": "192x192",
23      "purpose": "maskable any"
24    },
25    {
26      "src": "/images/icons-512.png",
27      "type": "image/png",
28      "sizes": "512x512",
29      "purpose": "maskable any"
30    }
31  ],
32  "prefer_related_applications": true,
33  "related_applications": [
34    {
35      "platform": "itunes",
36      "url": "https://itunes.apple.com/app/native-app/id345"
37    },
38    {
39      "platform": "play",
40      "id": "com.my-domain.native",
41      "url": "https://play.google.com/store/apps/details?id=com.my-domain.native"
42    }
43  ],
44  "dir": "ltr"
45}

下面我们逐项解析该文件内容。

安装对话框所需的字段

以下字段为使“添加到主屏幕”（A2HS）对话框出现所必需的。

name / short_name

应用安装到用户设备后，name 字段的值将显示在应用图标下方。当空间不足时，short_name 将作为备用名称。建议将其控制在 12 个字符以内，以避免截断。
在 Chrome 中，name 属性还会用于启动画面，并在 PWA 加载时显示。

start_url

start_url 指定应用启动时应加载的页面路径。这非常有用，因为我们希望应用始终从同一页面（如首页）启动，而不是从用户上次访问的页面开始。

💡 小知识！
通过在 URL 中添加查询字符串，我们可以向网页分析工具传递上下文信息，从而判断有多少用户是通过主屏幕图标访问应用的。这有助于我们了解用户行为。

display

display 指定应用在浏览器中的显示方式。
可选值包括不同的浏览器体验：

• browser

  提供标准浏览器体验，用户可通过移动设备像访问普通网站一样打开应用。

• standalone

  此选项非常有趣：应用会在独立窗口中打开，与浏览器窗口分离。这使得 PWA 看起来像原生应用。此外，部分浏览器 UI 元素（如地址栏）将不再显示。

• fullscreen

  如其名所示，PWA 将占据设备整个屏幕，不显示任何浏览器 UI 元素。此选项特别适合游戏或多媒体类应用。

icons

定义设备主屏幕或启动画面使用的图标。至少需提供一个分辨率不低于 144px 的图标。
Chrome 建议提供两个图标：192px 与 512px 分辨率。浏览器会根据用户设备自动缩放图标。为确保用户获得像素级精准的视觉体验，最佳做法是明确目标设备，并为其提供相应分辨率的图标。purpose 属性用于告知用户代理图标的具体用途或上下文。

maskable 和 any 可同时使用，遵循降级原则。例如上例中使用 maskable any，其中 any 作为后备选项。

• badge

  用户代理可在空间受限或颜色要求不同的地方使用此图标。

• maskable

  图标设计时已考虑图标遮罩和安全区域，因此图像超出安全区的部分可被用户代理安全地裁剪或遮盖。关于 maskable 图标的详细内容将在下一课中讲解。

• any

  用户代理可自由在任意场景中显示该图标。

background_color

设置应用的背景颜色。若使用 Chrome 将 PWA 添加到主屏幕，该颜色也会用于启动画面。

补充属性

其他属性虽为可选，但推荐配置：

orientation

指定应用应以纵向（竖屏）或横向（横屏）模式显示。后者通常更适合游戏或多媒体应用。

theme_color

在移动设备上，设置页面周围的主题颜色；在桌面端，用于美化标题栏样式。

description

用于描述你的应用。

scope

定义网站的导航范围。当用户导航出此范围时，应用将返回正常的浏览器页面。

prefer_related_applications

允许我们建议用户优先使用原生应用（通过 related_applications 属性设置相关详情）。当存在功能更完整的原生应用时，此属性非常有用。我们可以引导用户使用原生应用以获得更完整的体验。

related_applications

此处可提供从应用商店（如 Google Play 或 Apple App Store）安装原生应用的相关信息。 可配置的字段包括：

• platform

  指定应用可用的平台，支持以下选项：

  • chrome_web_store：Google Chrome 网络商店
  • play：Google Play 商店
  • itunes：iTunes 应用商店
  • windows：Windows 应用商店

• url

  应用商店的链接地址

• id

  用于唯一标识原生应用在指定平台上的 ID

dir

定义 name、short_name 与 description 属性的文本方向。可接受的值为 ltr（从左到右）、rtl（从右到左）和 auto（默认值）。

清单生成工具

如果不希望手动编写清单文件，可以使用 清单生成器。

这是一个简单工具，能生成清单的基本框架，你只需填写所需属性的值即可。