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
首先查看。
"window-control-overlay"
"minimal-ui"
如果两个选项都不可用,它会回退到display
. 如果"standalone"
不可用,它会从该点恢复规范定义的 fallabck 链。
"standalone"
"minimal-ui"
"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 窗口示例。](https://web-dev.imgix.net/image/tcFciHGuF3MxnTr1y5ue01OGLBn2/8mkBdT3O0FZLo0PUppvv.png?auto=format)
从 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 截图](https://web-dev.imgix.net/image/vvhSqZboQoZZN9wBvoXq72wzGAf1/5SlCnibmZHqkXdGVgPZY.jpeg?auto=format)
将网络应用程序清单添加到您的页面#
创建清单后,将<link>
标签添加到渐进式 Web 应用程序的所有页面。例如:
<link rel="manifest" href="/manifest.json">
测试你的清单#
要验证您的清单是否设置正确,请使用Chrome DevTools应用程序面板中的清单窗格。
![Chrome Devtools 中的应用程序面板,其中选择了清单选项卡。](https://web-dev.imgix.net/image/tcFciHGuF3MxnTr1y5ue01OGLBn2/FpIOY0Ak6FAA5xMuB9IT.png?auto=format)
此窗格提供许多清单属性的人类可读版本,并且可以轻松验证所有图像是否正确加载。
手机上的闪屏#
当您的应用程序首次在移动设备上启动时,浏览器可能需要一些时间才能启动,并且初始内容才能开始呈现。浏览器不会向用户显示应用程序停滞的白屏,而是显示启动画面,直到第一次绘制。
Chrome 会根据清单属性自动创建启动画面,特别是:
name
background_color
icons
应该background_color
与加载页面的颜色相同,以提供从初始屏幕到您的应用程序的平滑过渡。
Chrome 将为设备选择与设备分辨率最匹配的图标。在大多数情况下,提供 192px 和 512px 图标就足够了,但您可以提供其他图标以实现像素完美。
延伸阅读#
有几个额外的属性可以添加到 Web 应用程序清单中。有关详细信息,请参阅MDN Web 应用程序清单文档。