跳转到内容

安装中的平台

iOS 添加到主屏幕

发布于 更新于

“添加到主屏幕” 可以把网站添加到 iOS 或 iPadOS 主屏幕,入口在共享菜单中。安装必须由用户手动完成,这是唯一的安装路径。Safari 从 iPhone OS 1 起提供这项操作,第三方浏览器从 iOS 16.4 起也可提供。

页面提供 manifest,以及图标和名称。图标如何启动由用户决定;iOS 26 为此增加了 “Open as Web App” 开关。iOS 各版本均不触发 beforeinstallprompt,也不提供安装 API(BCD api.BeforeInstallPromptEvent)。

点按共享,再点按添加到主屏幕。需要时修改名称,然后点按添加。自 iOS 16.4 起,第三方浏览器在满足以下条件时可以提供同一菜单项:持有 com.apple.developer.web-browser 权限、把一个正在显示 HTTP 或 HTTPS 文档的 WKWebView 放入共享菜单的 activityItems,且设备不是共享 iPad(WebKit,“Web Push for Web Apps on iOS and iPadOS”)。

16.4 与 26 打开主屏幕图标的方式不同。

iOS 版本 以 web 应用方式打开(独立的应用切换器条目、无 Safari 界面)的条件 否则
16.4 至 18 manifest 的 display 为 standalone 或 fullscreen,或旧的 apple-mobile-web-app-capable meta 标签为 yes;用哪个浏览器添加无关 保存为主屏幕书签,在默认浏览器中打开
26 默认对每个添加的站点都成立;用户可以在添加面板中关闭 “Open as Web App”,即使站点已配置为 web 应用 书签,仅当用户关闭了该开关

据 WebKit 说明,Safari 26 没有可安装性要求:无需 manifest 或 service worker,除了页面本身能否加载,也不检查 HTTPS。manifest 仍决定 web 应用的外观。iOS 15.4 起会读取 icons,name 和 short_name 提供可编辑标题的初始值。id(16.4+)与用户选定的名称一起区分同一站点的多次安装,比如 “Shiny (work)” 和 “Shiny (personal)”,专注模式也能分别处理。多次安装同一站点是平台有意支持的用法。

HTML 标记还可设置图标、名称、启动图和状态栏。

  • 两种图标同时存在时,<link rel="apple-touch-icon" sizes="180x180" href="…"> 优先于 manifest 的 icons;Apple 的归档指南记载的选取顺序是:先用与设备推荐尺寸一致的图标;没有时用比推荐尺寸大的最小图标;再没有时用最大的图标。完全没有图标时,iOS 16.4 及以后用站点名称首字母加站点取色生成一个字母图标。
  • 名称取自 <meta name="apple-mobile-web-app-title" content="…">,缺少时取 <title>。用户可以在添加前修改。
  • 启动图默认为上次启动的截图;<link rel="apple-touch-startup-image" href="…"> 覆盖它,离线时尤其重要。
  • <meta name="apple-mobile-web-app-status-bar-style" content="black"> 仅在 standalone 模式下生效;Apple 归档指南写明它 “has no effect unless you first specify standalone mode”。OpenPWA 的真机测试在 iOS 18.6.2 上测量了默认样式与 black-translucent 在已安装应用中的效果:没有状态栏 meta 时,视口从屏幕顶部往下 62 px 处开始(iPhone 16 Pro 上 874 CSS px 中占 812),viewport-fit=cover 只改变底部安全区;black-translucent 配合 viewport-fit=cover 则得到满高视口,env(safe-area-inset-top) 为 62 px。默认样式页面上方的纯色条带取页面的 theme-color meta,只有页面没有 meta 时才取 manifest 的 theme_color(研究正文,实验记录 N25 至 N29、N55、N64、N65)。

主屏幕 web 应用可以使用 Safari 标签页不支持的 Web Push(16.4+,需用户手势;18.4 的 Declarative Web Push 通过 window.pushManager 订阅,无需 service worker)与 Badging API(16.4+,允许通知后绘制)。WebKit 的 16.4 公告还把 Screen Wake Lock、Screen Orientation 与 User Activation 列为主屏幕 web 应用开发者“特别关注”的新 API,但它们随 Safari 16.4 本身发布,并不限于已安装的应用(WebKit,“WebKit Features in Safari 16.4”)。Screen Wake Lock 到 iOS 18.4 才在主屏幕 web 应用中生效,WebKit 将其列为修复项(WebKit,“WebKit Features in Safari 18.4”;BCD api.WakeLock 因此把 16.4 至 18.3 记为部分支持)。WebKit 在任何 iOS 版本中都没有要求主屏幕条目具备 service worker(WebKit,Safari 26.0 文章)。存储仍采用尽力而为模式。开启跨站跟踪防护后,某个源若在 7 天浏览器使用期间没有交互,Safari 会删除它由脚本写入的数据。navigator.storage.persist() 根据交互历史返回结果,不弹提示(MDN,存储配额与清除)。

网页无法检测安装动作,只能在启动后检测显示上下文。

iOS 没有安装事件,代码只能根据显示上下文选择分支。先检查标准媒体特性,再用旧属性兼容老版本 iOS:

const standalone =
matchMedia('(display-mode: standalone)').matches ||
navigator.standalone === true; // 仅 Safari 的旧属性
if (standalone) {
hideInstallHint(); // 从主屏幕启动
} else if (/iPhone|iPad/.test(navigator.userAgent)) {
showShareMenuInstructions(); // "点按共享,然后添加到主屏幕"
}

把提示推迟到第二次或之后的访问,会减少看到提示的人数,但对回访用户更有针对性。已启动的 web 应用不需要安装提示,代码中的分支会隐藏它。user agent 只决定显示哪种说明文字,能力仍从 display-mode 读取。

规范

规范状态
无。