此页面由 Cloud Translation API 翻译。

添加 Web 应用清单

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

浏览器支持

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

来源

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主题颜色。

具有自定义 theme_color 的 PWA 窗口示例。 — </ph> 包含自定义 `theme_color` 的 PWA 窗口示例。

媒体查询中的`theme_color`

浏览器支持

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

来源

您可以使用媒体查询的 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> 在桌面设备和移动设备上更丰富的安装界面。

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

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

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

发出清单请求没有即使在同一网域中，也要执行此操作如果清单要求凭据，您必须添加 crossorigin="use-credentials" 。

测试清单

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

Chrome 开发者工具中的应用面板，其中“清单”标签页处于选中状态。 — </ph> 在开发者工具中测试您的清单。

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

移动设备上的启动画面

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

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

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

深入阅读

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

添加 Web 应用清单

创建清单文件

关键清单属性

short_name和name

icons

id

start_url

background_color

display

display_override

scope

theme_color

媒体查询中的theme_color

shortcuts

description

screenshots