添加 Web 应用清单

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Web 应用清单是一个 JSON 文件，告诉浏览器 渐进式 Web 应用 (PWA) 安装在用户桌面设备或 。一个典型的清单文件至少包括：

• 应用的名称
• 应用应使用的图标
• 应用启动时应打开的网址

创建清单文件

清单文件可以有任何名称，但通常命名为 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 the 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 the 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 中的一个。如果 您同时提供两者，name 在安装应用时使用，short_name 是 应用的快捷方式 受限。

icons

当用户安装 PWA 时，您可以为浏览器定义一组图标 在主屏幕、应用启动器、任务切换器、启动画面和 。

icons 属性是图片对象的数组。每个对象都必须 包含 src、sizes 属性和图片的 type。要使用 可遮盖式图标，有时称为自适应图标 图标，请将 "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

您可以自定义应用启动时要显示的浏览器界面。对于 例如，您可以隐藏地址栏和浏览器界面元素。游戏 甚至可以全屏启动display 属性接受以下参数之一： 以下值：

属性	行为
fullscreen	在没有任何浏览器界面的情况下打开 Web 应用，并占据所有 可用的显示区域
standalone	打开 Web 应用，其外观和风格与独立应用相似。应用运行 单独的窗口中，与浏览器分离开来 浏览器界面元素，例如地址栏。 <ph type="x-smartling-placeholder"> </ph>
minimal-ui	此模式与 standalone 类似， 用户具有用于控制导航的最小界面元素集； 例如“返回”和“重新加载”按钮 <ph type="x-smartling-placeholder"> </ph>
browser	标准浏览器体验。

display_override

如需选择 Web 应用的显示方式，请在其清单中设置 display 模式，如下所示 如前面所述。浏览器不一定要支持所有显示屏 模式，但必须支持 规范定义的后备链 ("fullscreen" → "standalone" → "minimal-ui" → "browser")。否则 支持给定模式，它们会回退到链中的下一个显示模式。在 在极少数情况下，这些回退可能会引发问题。例如，开发者不能 请求 "minimal-ui"，而不强制返回到 "browser" 显示屏 （当 "minimal-ui" 不受支持时）。当前的行为也使得 无法以向后兼容的方式引入新的显示模式， 因为它们在后备链中没有位置

您可以使用 display_override 属性设置自己的后备序列， 浏览器会将此时间视为 display 属性之前。其值为 按所列顺序视为顺序的字符串，并且第一个 支持的显示模式。如果所有值都不受支持，浏览器会回退 以对 display 字段求值。如果没有 display 字段，浏览器 忽略 display_override。

以下示例展示了如何使用 display_override。有关 "window-control-overlay"不在范围内 。

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

加载此应用时，浏览器会尝试使用 "window-control-overlay" 。如果不可用，则回退到 "minimal-ui"，然后回退到 display 属性中的 "standalone"。如果这些都不可用 浏览器会返回到标准后备链

scope

应用的 scope 是浏览器视为的一部分的网址集 。scope 可控制包含所有进入和退出操作的网址结构 指向应用程序，浏览器使用它确定用户何时离开 应用。

关于 scope 的一些其他说明：

• 如果您不在清单中添加 scope，则默认为 scope 是起始网址，但移除了其文件名、查询和片段。
• scope 属性可以是相对路径 (../)，也可以是任何更高级别 路径 (/)，可扩大导航覆盖范围 。
• start_url 必须在范围内。
• start_url 是相对于 scope 属性中定义的路径而言的。
• 以 / 开头的 start_url 将始终是源站的根。

theme_color

theme_color 用于设置工具栏的颜色，并可在 任务切换器中的应用预览。theme_color 应与 在文档标题中指定的meta主题颜色。

</ph> <ph type="x-smartling-placeholder">

媒体查询中的theme_color

您可以使用媒体查询的 media 属性来调整媒体查询中的 theme_color， 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 属性是应用快捷方式的数组 对象，让用户能够快速访问应用内的关键任务。每位成员 是至少包含 name 和 url 的字典。

description

description 属性说明应用的用途。

在 Chrome 中，所有平台上的说明长度上限为 300 个字符。 如果说明长度超过此限制，浏览器会使用 省略号字符。在 Android 设备上，说明最多只能使用 7 行文字。

screenshots

screenshots 属性是一个表示应用的图片对象数组 常见使用场景中。每个对象都必须包含 src（一个 sizes） 属性，以及图片的 type。form_factor 属性是可选的。 对于适用于宽屏的屏幕截图，您可以将此政策设为 "wide"。 仅限较窄的屏幕截图，也可使用 "narrow"。

在 Chrome 中，图片必须满足以下条件：

• 宽度和高度必须介于 320 像素到 3840 像素之间。
• 最大尺寸不能超过最小长度的 2.3 倍 维度。
• 与相应设备规格匹配的所有屏幕截图必须相同 宽高比。
  • 在 Chrome 109 中，仅限 form_factor 设置为 "wide" 的屏幕截图 在桌面设备上展示。
• 从 Chrome 109 开始，form_factor 设为 "wide" 的屏幕截图会 在 Android 上会被忽略不含form_factor的屏幕截图仍会显示 向后兼容性

桌面版 Chrome 至少会显示 1-8 张符合要求的屏幕截图 这些条件其余部分会被忽略。

Android 版 Chrome 至少显示一张或最多 5 张符合要求的屏幕截图 这些条件其余部分会被忽略。

</ph> <ph type="x-smartling-placeholder">

将 Web 应用清单添加到您的页面

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

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

测试清单

如需验证清单是否已正确设置，请使用清单窗格 Application 面板。

</ph> <ph type="x-smartling-placeholder">

此窗格提供人类可读版本的许多清单 属性，让您可以验证是否所有图片都在 正确。

移动设备上的启动画面

当您的应用首次在移动设备上启动时，浏览器可能需要一些时间才能启动 以及要开始呈现的初始内容。与显示 白色屏幕，可能会让用户认为应用无法正常运行，浏览器 在首次绘制之前显示启动画面。

Chrome 会自动通过 name 创建启动画面， background_color 和 icons。为了创建流畅的 从启动画面到应用的过渡，可让您background_color 与加载页面颜色相同

Chrome 会选择与 启动画面。在大多数情况下，提供 192 像素和 512 像素的图标就足够了 但您可以提供更多图标以获得更好的匹配效果。

深入阅读

要了解可添加到 Web 应用清单的其他属性，请参阅 MDN Web 应用清单文档。