什么是web app manifest (网络应用程序清单)

Web 应用程序清单是一个 JSON 文件，它告诉浏览器有关您的渐进式 Web 应用程序的信息，以及它在安装到用户的桌面或移动设备上时的行为方式。典型的清单文件包括应用程序名称、应用程序应使用的图标以及应用程序启动时应打开的 URL 等。

创建清单文件#

manifest.json清单文件可以有任何名称，但通常从根目录（您网站的顶级目录）命名和提供。规范建议扩展名应该是.webmanifest，但浏览器也支持.json扩展名，这可能更容易让开发人员理解。

一个典型的清单看起来像这样：

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-vector.svg",
      "type": "image/svg+xml",
      "sizes": "512x512"
    },
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "id": "/?source=pwa",
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6",
  "shortcuts": [
    {
      "name": "How's weather today?",
      "short_name": "Today",
      "description": "View weather information for today",
      "url": "/today?source=pwa",
      "icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
    },
    {
      "name": "How's weather tomorrow?",
      "short_name": "Tomorrow",
      "description": "View weather information for tomorrow",
      "url": "/tomorrow?source=pwa",
      "icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
    }
  ],
  "description": "Weather forecast information",
  "screenshots": [
    {
      "src": "/images/screenshot1.png",
      "type": "image/png",
      "sizes": "540x720",
      "form_factor": "narrow"
    },
    {
      "src": "/images/screenshot2.jpg",
      "type": "image/jpg",
      "sizes": "720x540",
      "form_factor": "wide"
    }
  ]
}

关键清单属性#

short_name和/或name #

您必须至少提供short_name或name财产。如果两者都提供，short_name则用于用户的主屏幕、启动器或其他空间可能有限的地方。name安装应用程序时使用。

icons #

当用户安装您的 PWA 时，您可以定义一组图标供浏览器在主屏幕、应用程序启动器、任务切换器、初始屏幕等上使用。

该icons属性是一组图像对象。每个对象必须包含src、sizes属性和type图像的 。要使用可屏蔽图标（有时在 Android 上称为自适应图标），您还需要添加"purpose": "any maskable"到该icon属性。

对于 Chromium，您必须至少提供一个 192x192 像素的图标和一个 512x512 像素的图标。如果仅提供这两种图标大小，Chrome 会自动缩放图标以适合设备。如果您更喜欢缩放自己的图标，并调整它们以实现像素完美，请以 48dp 的增量提供图标。

id #

该id属性允许您显式定义用于您的应用程序的标识符。将属性添加到清单中会消除对清单或清单位置的id依赖，并使它们有可能在将来更新。start_url有关详细信息，请参阅使用 Web 应用程序清单 id 属性唯一标识 PWA。

start_url #

是start_url必需的，它告诉浏览器您的应用程序在启动时应该从哪里开始，并防止应用程序从用户将您的应用程序添加到主屏幕时所在的任何页面启动。

您start_url应该将用户直接引导至您的应用，而不是产品着陆页。想一想用户打开您的应用程序后想要做什么，并将它们放在那里。

background_color #

当应用程序首次在移动设备上启动时，该background_color属性用于启动画面。

display #

您可以自定义应用程序启动时显示的浏览器 UI。例如，您可以隐藏地址栏和浏览器用户界面元素。游戏甚至可以全屏启动。该display属性采用以下值之一：

财产	使用
fullscreen	在没有任何浏览器 UI 的情况下打开 Web 应用程序，并占用整个可用显示区域。
standalone	打开 Web 应用程序，使其看起来像一个独立的应用程序。该应用程序在其自己的窗口中运行，与浏览器分开，并隐藏标准的浏览器 UI 元素，例如 URL 栏。
minimal-ui	此模式类似于standalone，但为用户提供了一组用于控制导航（例如返回和重新加载）的最小 UI 元素。
browser	标准的浏览器体验。

display_override #

如上所述，display Web 应用程序可以通过在其清单中设置模式来选择它们的显示方式。浏览器不需要支持所有显示模式，但它们需要支持规范定义的回退链( → → → )。如果它们不支持给定的模式，它们将回退到链中的下一个显示模式。这种不灵活的行为在极少数情况下可能会出现问题。例如，当"fullscreen""standalone""minimal-ui""browser""minimal-ui""browser""minimal-ui"不支持。另一个问题是当前的行为使得无法以向后兼容的方式引入新的显示模式，因为像选项卡式应用程序模式这样的探索在回退链中没有自然的位置。

这些问题由属性解决display_override，浏览器在属性之前display考虑。它的值是按列出的顺序考虑的字符串序列，并应用第一个支持的显示模式。如果不支持，浏览器将退回到评估该display字段。

考虑下面的例子。（详细信息"window-control-overlay"超出了本文的范围。）

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

如前所述，浏览器将display_override首先查看。

1. "window-control-overlay"
2. "minimal-ui"

如果两个选项都不可用，它会回退到display. 如果"standalone"不可用，它会从该点恢复规范定义的 fallabck 链。

1. "standalone"
2. "minimal-ui"
3. "browser"

scope #

定义了scope浏览器认为在您的应用程序中的 URL 集，并用于决定用户何时离开应用程序。控制scope包含 Web 应用程序中所有入口点和出口点的 URL 结构。您start_url必须位于scope.

警告

其他一些注意事项scope：

• 如果您不在scope您的清单中包含 a，则默认隐含scope是您的 Web 应用程序清单提供服务的目录。
• 该scope属性可以是相对路径 ( ../) 或任何更高级别的路径 ( /)，这将允许增加您的网络应用程序中的导航覆盖范围。
• 必须start_url在范围内。
• start_url相对于属性中定义的路径scope。
• 起点永远是起源start_url的/根源。

theme_color #

设置theme_color工具栏的颜色，并可能反映在任务切换器的应用程序预览中。应与文档标题中指定的主题颜色theme_color相匹配。meta

具有自定义 theme_color 的 PWA 窗口示例。

从 Chromium 93 和 Safari 15 开始，您可以使用theme color 元素media的属性在媒体查询中调整此颜色meta。第一个匹配的将被选中。例如，您可以为浅色模式使用一种颜色，为深色模式使用另一种颜色。在撰写本文时，您无法在清单中定义它们。请参阅w3c/manifest#975 GitHub 问题。

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

shortcuts #

该shortcuts属性是一组应用程序快捷方式对象，其目的是提供对应用程序中关键任务的快速访问。每个成员都是一个至少包含 aname和 a 的字典url。

description #

该description属性描述了您的应用程序的用途。

screenshots #

该screenshots属性是一组图像对象，代表您在常见使用场景中的应用程序。每个对象必须包含src、sizes属性和type图像的 。该form_factor属性是可选的。您可以将其设置为仅"wide"适用于宽屏幕的屏幕截图或"narrow"适用于窄屏幕的屏幕截图。仅当布局因屏幕尺寸而异时才应使用它。

在 Chrome 中，图像必须符合某些条件：

• 宽度和高度必须至少为 320 像素，最多为 3840 像素。
• 最大尺寸不能超过最小尺寸的 2.3 倍。
• 匹配适当外形规格的所有屏幕截图必须具有相同的纵横比。

桌面和移动设备上更丰富的安装 UI。

将网络应用程序清单添加到您的页面#

创建清单后，将<link>标签添加到渐进式 Web 应用程序的所有页面。例如：

<link rel="manifest" href="/manifest.json">

陷阱

测试你的清单#

要验证您的清单是否设置正确，请使用Chrome DevTools应用程序面板中的清单窗格。

在 DevTools 中测试您的清单。

此窗格提供许多清单属性的人类可读版本，并且可以轻松验证所有图像是否正确加载。

手机上的闪屏#

当您的应用程序首次在移动设备上启动时，浏览器可能需要一些时间才能启动，并且初始内容才能开始呈现。浏览器不会向用户显示应用程序停滞的白屏，而是显示启动画面，直到第一次绘制。

Chrome 会根据清单属性自动创建启动画面，特别是：

• name
• background_color
• icons

应该background_color与加载页面的颜色相同，以提供从初始屏幕到您的应用程序的平滑过渡。

Chrome 将为设备选择与设备分辨率最匹配的图标。在大多数情况下，提供 192px 和 512px 图标就足够了，但您可以提供其他图标以实现像素完美。

延伸阅读#

有几个额外的属性可以添加到 Web 应用程序清单中。有关详细信息，请参阅MDN Web 应用程序清单文档。