PWA 安装提示管理器 - 自定义 A2HS 行为

A2HS（Add to Home Screen）是现代浏览器提供的一项功能，允许用户将 Progressive Web App（PWA）直接添加到设备的主屏幕上。添加后，PWA 可以像原生应用一样启动，拥有独立的窗口、应用图标和启动画面。Chrome、Edge、Samsung Internet 等基于 Chromium 的浏览器通过 beforeinstallprompt 事件支持自定义安装流程，而 iOS Safari 则需要用户通过分享菜单手动添加。本工具的核心功能就是帮助开发者自定义 A2HS 的提示样式和触发行为，提升用户的安装转化率和品牌体验。

beforeinstallprompt 是浏览器在 PWA 满足安装条件时触发的事件。通过调用 event.preventDefault() 可以阻止浏览器默认的安装提示，并将事件对象保存到变量中。之后可以在自定义的 UI 按钮上调用 deferredPrompt.prompt() 来触发安装流程，安装完成后调用 deferredPrompt.userChoice 获取用户的选择结果。此事件仅在 Chrome 76+、Edge 79+、Samsung Internet 等基于 Chromium 的浏览器中可用，iOS Safari 不支持。本工具生成的代码已内置了完整的事件拦截和处理逻辑，开发者无需手动编写这些代码。

Chrome 浏览器要求 PWA 必须同时满足以下条件才能触发安装提示：网站必须通过 HTTPS 访问（localhost 除外）；必须配置有效的 manifest.json，包含 name、short_name、icons（至少 192x192 和 512x512 两个尺寸）、start_url、display（standalone 或 fullscreen）；必须注册并激活 Service Worker，且至少有一个 fetch 事件监听器；用户需要与网站有足够的交互（Chrome 的参与度检查）。此外，如果用户之前已安装或拒绝安装，浏览器可能会在冷却期后再触发。本工具的 PWA 状态检测功能可以帮助开发者逐一检查这些条件是否满足。

iOS Safari 不支持 beforeinstallprompt 事件，因此无法通过 JavaScript 触发自动安装提示。要在 iOS 上引导用户安装 PWA，需要添加 apple-mobile-web-app-capable meta 标签、配置 apple-mobile-web-app-status-bar-style 和 apple-touch-icon，并在页面中显示自定义引导提示，指引用户点击 Safari 的「分享」按钮然后选择「添加到主屏幕」。可以使用 navigator.standalone 检测是否已在独立模式运行。本工具提供专门的 iOS 引导模板，自动生成适配 Safari 的引导文案和样式，大幅简化了 iOS 平台的适配工作。

可以通过以下几种方式检测 PWA 安装状态：使用 CSS 媒体查询 @media (display-mode: standalone) 在已安装时应用特定样式；使用 JavaScript 的 window.matchMedia('(display-mode: standalone)').matches 进行检测；在 iOS 上检测 navigator.standalone === true；监听 appinstalled 事件在安装成功后执行回调。检测到已安装后，应隐藏安装提示，避免向已安装用户重复展示。本工具生成的代码内置了安装状态检测逻辑，会自动跳过已安装用户，确保用户体验的连贯性。

自定义安装提示时建议遵循以下最佳实践：不要过早显示提示，给用户时间了解网站价值后再提示安装；提供明确的关闭选项，尊重用户选择，允许轻松关闭提示；使用冷却机制，用户关闭后不要立即再次显示，建议等待数小时或数天；使用清晰的文案说明安装的好处（如离线使用、更快加载），而非仅说「安装」；在合适的时机触发，如用户完成关键操作后、浏览多页内容后或滚动到一定深度时；检测已安装状态，避免向已安装用户显示提示。本工具的触发条件设置和冷却时间配置正是基于这些实践设计的。

不是所有浏览器都支持自定义 A2HS 提示。Chrome（桌面和 Android）完全支持 beforeinstallprompt 事件；Edge（桌面和 Android）完全支持；Samsung Internet 完全支持；Opera（Android）支持。Firefox（Android）支持 A2HS 但不支持 beforeinstallprompt 事件，因此无法自定义提示样式。Safari（iOS）不支持 beforeinstallprompt，需使用自定义引导流程。Firefox（桌面）目前不支持 PWA 安装。本工具生成的代码会自动检测浏览器兼容性，在不支持的环境下优雅降级，确保不会因浏览器差异导致页面异常。

是的，在 Chromium 浏览器中，注册并激活 Service Worker 是触发 beforeinstallprompt 事件的必要条件。Service Worker 需要至少有一个 fetch 事件监听器。最简单的 Service Worker 示例只需一行代码：self.addEventListener('fetch', e => e.respondWith(fetch(e.request)))。没有 Service Worker，浏览器不会触发安装提示，这是 Google 确保 PWA 具有离线能力的基本要求。建议开发者使用 Workbox 等工具来管理 Service Worker 的注册和缓存策略，本工具生成的安装提示代码与 Service Worker 互不冲突，可以并行工作。

本工具生成的安装提示代码是独立的 JavaScript 文件，与 Service Worker 的注册和管理完全解耦。代码通过监听 beforeinstallprompt 事件工作，而 Service Worker 负责缓存和离线能力，两者各司其职互不干扰。如果开发者使用 Workbox 等工具管理 Service Worker，只需确保安装提示代码在 Service Worker 注册之后引入即可。在生成的代码中，安装提示的触发逻辑与 Service Worker 的生命周期无关，开发者可以独立调整两者的配置，无需担心兼容性问题。

当冷却时间设为 0 时，表示用户关闭安装提示后在同一会话内不再显示。这里的「同一会话」指的是浏览器标签页从打开到关闭的期间。如果用户关闭标签页后重新打开网站，安装提示会重新出现（前提是触发条件已满足）。这种设置适合希望在单次访问中只展示一次提示的场景。如果设为大于 0 的值（如 24 小时），则即使用户关闭标签页重新访问，在冷却时间内也不会再次显示安装提示。合理设置冷却时间可以平衡提示效果和用户体验，避免对用户造成打扰。

本工具生成的安装提示代码采用响应式设计，自动适配不同屏幕尺寸。底部横幅和顶部通知模板使用 position: fixed 定位，居中弹窗使用 flexbox 居中，确保在手机、平板和桌面设备上均能正确显示。预览区域模拟了手机浏览器的显示环境，但实际效果可能因设备而异。建议在真实设备上进行测试：Android 设备使用 Chrome 检查自定义提示效果，iOS 设备使用 Safari 检查引导流程。Chrome DevTools 的设备模拟功能也可以帮助快速验证不同分辨率下的显示效果。