跳转到内容

安装中的概念

安装提示 UX

发布于 更新于

有限可用不支持的浏览器: Firefox (Desktop)、Firefox (Android)、Safari (macOS)、Safari (iOS)WICG 草案

安装提示让用户从页面安装 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,就可以用这些文档记载的标签引导用户手动安装。

规范

规范状态
安装提示(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
  1. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  2. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  3. browser-compat-data 未记录 Firefox 的支持。
  4. browser-compat-data 未记录 Firefox for Android 的支持。
  5. 由 browser-compat-data 镜像自 Firefox 的数据推导。
  6. browser-compat-data 未记录 Safari 的支持。
  7. browser-compat-data 未记录 iOS 版 Safari 的支持。
  8. 由 browser-compat-data 镜像自 Safari 的数据推导。
  9. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/install-prompt.json · 全球使用占比: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-20 · 置信度: 高 (由来源计算)