Web 应用清单: Web 应用清单是您创建的一种文件,用于告知浏览器您希望自己的 Web 内容在操作系统中如何显示为应用。
该清单可以包含基本信息,例如应用名称、图标和主题颜色;
高级偏好设置,例如所需的屏幕方向和应用快捷方式;
以及目录元数据,例如屏幕截图。
每个 PWA 都应为每个应用包含一个清单,该清单通常托管在根文件夹中,并在可以从所有可安装 PWA 的 HTML 页面上提供相应链接。其官方扩展名为 .webmanifest
,因此您可以将清单命名为 app.webmanifest
之类的名称。
(以下命名为“manifest
”)
TIP: 虽然建议的扩展名为
.webmanifest
,但只要随application/manifest+json
内容类型或其他
JSON 有效的内容类型(例如 text/json)一起提交,就可以使用任何文件名。因此,许多 PWA(尤其是旧版 PWA)改用manifest.json。
向 PWA 添加 Web 应用清单manifest.json
如需创建 Web 应用清单,请先创建一个包含 JSON 对象的文本文件,其中至少包含具有字符串值的 name 字段:
{
"name": "My First Application"
}
但创建文件是不够的,浏览器也需要知道它存在。
链接到清单
如需让浏览器感知您的 Web 应用清单,您需要使用 <link> HTML 元素
,并在 PWA
的所有 HTML
页面上将 rel
属性设置为 manifest
,以将其关联到您的 PWA。这与将 CSS 样式表链接到文档的方式类似。
// index.html:
<html lang="en">
<title>This is my first PWA</title>
<link rel="manifest" href="/manifest">
TIP: 如果您的 PWA 包含多个 HTML 网页,请务必将其清单链接到所有这些网页。
调试清单
- Chromium 浏览器在开发者工具中: 1. 在左侧窗格的应用下,选择清单。 2. 检查浏览器解析的清单字段。
- Firefox浏览器1. 打开检查器。 2. 转到“Application”(应用)标签页。3. 在左侧面板中选择“清单”选项。4. 检查浏览器解析的清单字段。
设计您的 PWA 体验, 设置manifest
中的字段
TIPS:
在定义 Web 应用清单规范之前,一些浏览器(包括 iOS/iPadOS 上的 Safari 和 Android 上的 Chrome)都支持自定义 元素(例如apple-mobile-web-app-capable)来描述应用体验。
目前不要使用这些 元素;我们已不再推荐使用这些元素,而且当浏览器无法正确加载清单时,安装体验可能会受到影响;您获得的后备体验可能会有所不同且出乎意料。
PWA的manifest
中的基本字段
PWA 的核心信息
这些核心信息用于构建已安装 PWA 的图标和窗口,并确定其启动方式。
-
name:
您的 PWA 的全名。此图标会与图标一起显示在操作系统的主屏幕、启动器、Dock 或菜单中。 -
short_name:
可选,即您的 PWA 的较短名称,在没有足够的空间来显示name
字段的全部值时使用。请将字符数控制在 12 个以内,以尽可能降低被截断的可能性。 -
icons:
包含src、type、sizes
和可选purpose
字段的图标对象数组,描述应表示 PWA 的图片。 -
start_url:
当用户通过已安装的图标启动 PWA 时,该应用应加载的网址。建议使用绝对路径,因此,如果 PWA 的首页是您网站的根目录,您可以将此属性设为“/”
,以便在应用启动时打开该页面。如果您未提供启动网址,浏览器可以使用安装 PWA 时所用的网址作为起始网址。它可以是深层链接,例如产品的详细信息,而不是主屏幕。 -
display:
fullscreen
、standalone
、minimal-ui
或browser
之一,用于描述操作系统应如何绘制 PWA 窗口。您可以在“应用设计”章节中详细了解不同的显示模式。大多数用例都实现了standalone
。 -
id:
一个字符串,用于对照可托管在同一源上的其他 PWA 独一无二地标识此 PWA。如果未设置,start_url 将用作后备值。请注意,如果日后更改 start_url(例如,更改查询字符串值时),浏览器可能无法检测已安装 PWA。
id 属性有何用途?id
属性向浏览器表示 PWA 的身份。当浏览器发现一个清单没有与已安装的 PWA 匹配的身份时,它会将其视为新的 PWA,即使它是通过与另一个 PWA 相同的网址提供的。但是,如果它发现其身份与已安装的 PWA 匹配,则会将其视为已安装的 PWA。 -
图标:
PWA 的图标是 PWA 在用户设备上安装后的视觉标识,因此请务必定义至少一个图标。
由于 icons 属性是图标对象的集合,因此您可以定义多个不同格式的图标,以便为用户提供最佳图标体验。
每个浏览器都会根据自身的需求和安装的操作系统来挑选一个或多个图标,图标越接近所需的规格。
(如果您只需要选择一个图标大小,那么它应该为 512 x 512 像素。不过,我们建议您提供更多尺寸的图片,包括 192 x 192、384 x 384 和 1024 x 1024 像素的图片。)
"icons": [
{
"src": "icons/512.png",
"type": "image/png",
"sizes": "512x512"
},
{
"src": "icons/1024.png",
"type": "image/png",
"sizes": "1024x1024"
}
]
安装的效果&更详细的桌面安装、IOS和IPadOS安装,Android安装
PWA的manifest
中的建议字段
下一组需要包含的字段可以改善用户体验,尽管它们并不是安装性所必需的字段。
- theme_color:
应用的默认颜色,有时会影响操作系统显示网站的方式(例如,桌面设备上的窗口和标题栏颜色,或移动设备上的状态栏颜色)。此颜色可被HTML theme-color <meta>
元素替换。 - background_color:
在应用样式表加载之前要在应用背景中显示的占位符颜色。iOS
和iPadOS
上的Safari
以及大多数桌面浏览器目前会忽略此字段。 - scope:
更改PWA
的导航范围,让您能够定义在已安装应用的窗口中显示和不显示哪些内容。例如,如果您链接到的网页不在该范围内,则该网页会在应用内浏览器中(而不是在 PWA 窗口中)呈现。不过,这不会更改 Service Worker 的作用域。
下图显示了当您安装 PWA
时,桌面设备上标题栏的 theme_color
字段是怎样的。
Tips:
请勿使用透明度、CSS 变量、渐变函数或有透明度的颜色函数(例如rgba()),因为大多数浏览器都不支持它们。您将会获得不一致的结果。
启动画面
在某些设备上,系统会在加载 PWA 时渲染静态图片,以向用户提供即时反馈。
Android
使用 theme_color
、background_color
和 icon
值生成启动画面。
当您在 Android
上安装 PWA
时,设备会生成启动画面,其中包含来自清单的信息,如下图所示。
另一方面,iOS
和 iPadOS
上的 Safari
不使用网络应用清单来生成启动画面。而是使用从专有 元素链接的图片,这与处理图标的方式类似。如需了解详情,请参阅增强功能一章。
PWA的manifest
中的扩展字段
以下都是可选字段:
- lang:
一个语言标记,用于指定清单值的主要语言,例如en
表示英语,pt-BR
表示巴西葡萄牙语,in
表示印地语。 - dir:
支持方向的清单字段(例如name、short_name 和 description
)的显示方向。有效值为auto
、ltr
(从左到右)和rtl
(从右到左)。 - orientation:
安装应用后的预期屏幕方向。游戏可以将其设置为请求仅限横向方向。可接受多个值,但如果包含值,则通常为portrait
或landscape
。
PWA的manifest
中的促销字段
- description:
介绍 PWA 的用途。 - screenshots:
屏幕截图对象数组,包含src、type 和 sizes
(类似于icons
对象),用于展示 PWA。没有大小限制。 - categories:
PWA 应属于的类别数组用作列表提示,可以选择来自已知类别列表。这些值通常为小写形式。 - iarc_rating_id:
PWA 的国际年龄分级联盟认证代码(如果有)。它旨在确定您的 PWA 适合哪些年龄段。
PWA的manifest
中的功能字段
最后,您的 PWA 可以在受支持的浏览器中使用许多与不同功能相关的字段,例如 shortcuts
、share_target
、display_overrides
字段(如“功能”章节中所述)。此外,还有 related_apps
和 prefer_related_apps
等字段(如需了解详情,请参阅检测章节),用于将 PWA 连接到已安装的应用(通常来自应用商店)。
👉判断用户是否在pwa环境中打开运行?(已安装的 PWA 与未安装的 PWA 网站之间有什么区别?)
👉vue3+ts+vite项目中使用vite-plugin-pwa搭建 PWA 项目,以及如何处理pwa安装图标的显示隐藏
👉pwa在iframe下能否显示,以及在iframe下相关问题解析
👉PWA遇到的一些问题。PWA的manifest
中display
设置的显示模式区别;PWA设置display为fullscreen时安卓上的fixed消失隐藏;在ios系统下需要的兼容性设置;