useAddToHomescreen()

useAddToHomescreen() 是 <SwAddToHomescreenGuide> 内部使用的 composable，封装了 PWA 添加到主屏幕引导的显示决策 + 生命周期管理：UA 检测、配置读取、会话/持久化记忆、延时触发等。所有 window / navigator 访问都包在 onMounted + import.meta.client 内，SSR 安全。

业务侧通常不直接调用——挂载 <SwAddToHomescreenGuide /> 即可获得完整能力。仅当业务希望完全自定义引导 UI（不用 framework 的 bottom-sheet）时才需要直接消费此 composable。

显示决策（全部满足才返回 `open=true`）

下面的探测器展示你当前的访问环境对各道闸的判定（桌面浏览器通常卡在闸 ④）：

加载中...

客户端环境（import.meta.client）
PWA 已启用（runtimeConfig.public.swiftWebFramework.pwa.enabled）
addToHomescreen 未被显式关闭
不在 standalone 模式（用户尚未把站点加到主屏）
UA 可明确判定为 iOS Safari 或 Android Chromium 主流浏览器
用户最近"没被记住关闭"（由 rememberFor 决定）

基础用法

<script setup lang="ts">
const { open, platform, dismiss } = useAddToHomescreen({
  delay: 2000,
  rememberFor: 'session',
})
</script>

<template>
  <Teleport to="body">
    <div v-if="open" class="my-custom-guide">
      <p v-if="platform === 'ios'">点击 Safari 工具栏的「共享」→「添加到主屏幕」</p>
      <p v-else-if="platform === 'android'">点击右上角菜单 →「添加到主屏幕」</p>
      <button @click="dismiss">关闭</button>
    </div>
  </Teleport>
</template>

配置入口

useAddToHomescreen({
  delay: 3000,        // 可选，mount 后多久弹（毫秒）。默认走 runtimeConfig 或 2000
  rememberFor: '7d',       // 可选，记忆多久。默认走 runtimeConfig 或 'session'
})

参数	类型	默认值	说明
`delay`	`number`	`2000`	mount 后多久弹出。优先级：参数 > runtimeConfig > 2000
`rememberFor`	`'session' \| PeriodSpec`	`'session'`	记忆策略。`'session'` = sessionStorage；`'Nm'`·`'Nh'`·`'Nd'` = N 分·时·天内不再弹；`'0d'` = 不记忆
`trackInstall`	`{ traceId?: string }`	`undefined`	PWA 安装成功埋点（opt-in）：传入即监听 `appinstalled`，经 `useTracker` 上报 WebSDK `appInstall`（`trace_id` 取 `traceId`，缺省空串）。仅需 PWA 启用，不受引导显示闸影响（用户从浏览器菜单安装也计入）；不传零行为

返回值

名称	类型	说明
`open`	`Ref<boolean>`	引导是否显示。延时到点后自动置 `true`，调用 `dismiss()` 后置 `false`
`platform`	`Ref<'ios' \| 'android' \| null>`	当前设备引导目标平台。`null` 表示不弹（应该被外层 `v-if="open"` 兜底）
`dismiss`	`() => void`	主动关闭引导。仅改变 `open`，是否记忆已在 `open` 触发时写入

存储 key

模式	存储	Key	数据
`rememberFor: 'session'`	sessionStorage	`<cachePrefix>sw:a2hs:shown`	`boolean`（AES 加密）
`rememberFor: N`（正数）	localStorage	`<cachePrefix>sw:a2hs:dismissedAt`	`number` timestamp（AES 加密）

两种模式的 key 不同，切换 rememberFor 时不会冲突。<cachePrefix> 来自 runtimeConfig.public.cachePrefix（多项目共用域名时自动隔离）。

注意事项

此 composable 仅供 <SwAddToHomescreenGuide> 内部使用，自定义 UI 时也可消费，但 framework 不保证返回值的稳定性（patch 版本可能微调）
记录"已弹"的时机是 setTimeout 触发那一刻（open 变 true 时），即便用户没看到（标签页失焦等）也算一次"已展示"。这避免了"用户秒关却没记录导致下次又弹"的体验问题
PWA 未启用时（pwa.enabled === false），dev 模式 console 会有 warn 提示要么启用 PWA、要么从 app.vue 注释/删除挂载点