安装中的概念
安装提示 UX
发布于 更新于
安装提示让用户从页面安装 PWA。你可以决定何时显示自定义安装按钮;浏览器没有提供程序化提示时,则显示安装帮助。自定义按钮依赖 beforeinstallprompt 事件,只有部分浏览器支持,需要保留浏览器自带的安装入口。
工作原理
链接到“工作原理”一节站点的安装按钮初始为隐藏状态。beforeinstallprompt 触发后,处理函数可以调用 preventDefault()、保留事件并显示按钮。之后的点击会调用所保留事件的 prompt() 方法。web.dev 说明,保留的事件只能使用一次,因此页面在提示后将它清除(How to provide your own in-app install experience,web.dev)。
browser-compat-data 记载,Firefox 和 Safari 不支持 BeforeInstallPromptEvent。用这个事件增强安装流程时,要保留浏览器自带的安装方式。
display-mode 媒体特性报告正在使用的显示模式。MDN 记录的值包括 browser、standalone、minimal-ui、fullscreen 和 window-controls-overlay。匹配某个值描述的是生效的显示模式,本身不能证明所有可能的安装状态。
让安装操作使用保留的事件。显示模式要单独检测,不能据此判断所有安装状态。
仅在事件到达后显示按钮
链接到“仅在事件到达后显示按钮”一节没有收到事件时,保留浏览器自带的安装界面。事件用过一次就清除。
<button id="install" type="button" hidden>安装应用</button>
<script>const installButton = document.querySelector('#install');let deferredInstall;
window.addEventListener('beforeinstallprompt', (event) => { event.preventDefault(); deferredInstall = event; installButton.hidden = false;});
installButton.addEventListener('click', async () => { if (!deferredInstall) return; await deferredInstall.prompt(); deferredInstall = undefined; installButton.hidden = true;});
window.addEventListener('appinstalled', () => { deferredInstall = undefined; installButton.hidden = true;});</script>如果没有收到 beforeinstallprompt 事件,按钮会保持隐藏。
选择页面内消息或手动回退
链接到“选择页面内消息或手动回退”一节功能检测决定是否等待事件。回退时按持续维护的说明显示对应浏览器的安装帮助,不要在 JavaScript 中猜菜单名称。
const standalone = window.matchMedia('(display-mode: standalone)').matches;const canReceivePrompt = 'onbeforeinstallprompt' in window;
if (standalone) { hideInstallPromotion();} else if (canReceivePrompt) { keepInstallButtonHiddenUntilEvent();} else { showManualInstallHelp();}没有事件时也要有对应的处理分支。如果应用还支持其他安装后的显示模式,可以分别检测。
实测行为
链接到“实测行为”一节安装说明如果针对 iOS 或 iPadOS 上的 Safari 26,就可以用这些文档记载的标签引导用户手动安装。
另请参阅
链接到“另请参阅”一节- How to provide your own in-app install experience(web.dev)
- Window: beforeinstallprompt event(developer.mozilla.org)
- beforeinstallprompt 事件
- 可安装性条件
- iOS 添加到主屏幕
- 桌面端安装
规范
| 规范 | 状态 |
|---|---|
| 安装提示(beforeinstallprompt) | WICG 草案 |
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| Chrome (Desktop)# | 支持 | 44 | 高 | 来源 | — |
| Chrome (Android)# | 支持 | 44 | 高 | 来源 | 1 |
| Edge (Desktop)# | 支持 | 79 | 高 | 来源 | 2 |
| Firefox (Desktop)# | 不支持 | — | 高 | 来源 | 3 |
| Firefox (Android)# | 不支持 | — | 高 | 来源 | 45 |
| Safari (macOS)# | 不支持 | — | 高 | 来源 | 6 |
| Safari (iOS)# | 不支持 | — | 高 | 来源 | 78 |
| Samsung Internet# | 支持 | 5.0 | 高 | 来源 | — |
| WebView (Android)# | 支持 | 44 | 高 | 来源 | 9 |
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- browser-compat-data 未记录 Firefox 的支持。
- browser-compat-data 未记录 Firefox for Android 的支持。
- 由 browser-compat-data 镜像自 Firefox 的数据推导。
- browser-compat-data 未记录 Safari 的支持。
- browser-compat-data 未记录 iOS 版 Safari 的支持。
- 由 browser-compat-data 镜像自 Safari 的数据推导。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
在线试用
在 OpenPWA 演示应用中运行此能力: /demo/#install