@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 请求宿主重载当前小程序容器。

      返回 Promise<void>

      Host reload 原语接受请求后 resolve undefined;这不是旧页面仍可继续执行的确认。

      HbMiniProgramSDKError INVALID_PARAMS 表示通过底层协议传入了非空 payload; App-facing reload() 本身没有参数。

      HbMiniProgramSDKError METHOD_FORBIDDEN / METHOD_NOT_FOUND 表示当前 Host 未实现或未开放 reload 原语;REQUEST_UNSUPPORTED 表示 Host 无法执行当前 reload 请求。

      HbMiniProgramSDKError RUNTIME_DESTROYED / RUNTIME_UNAVAILABLE / SDK_DESTROYED 表示 Runtime、旧页面上下文或 SDK 已进入终态。SDK 握手失败或 Host 在 调用超时内未接受请求时,还会返回对应握手错误码或 REQUEST_TIMEOUT;其他 Host reload 错误保留其 SDK 错误码。

      该方法在 android、ios、ohos、windows、macos 上公开,但实际 Host 必须提供 presentation.reload 原语;缺失时 fail closed。调用无需 package.json#heybox.permissions 声明、平台批准、用户授权或可信用户手势。

      Host 接受请求后会用新的页面运行上下文替换当前上下文。模块内变量、DOM、timer、未完成 Promise、当前 SDK 实例以及通过 on() / onHandshakeStateChange() 注册的监听都不会跨 reload 保留;新页面会重新加载 SDK、重新握手并重新注册所需监听。不要依赖 await reload() 后的语句完成初始化或清理。每次调用都会直接转发给 Host,不会合并为 幂等的“正在重载”状态。

      需要跨 reload 恢复的数据必须在调用前写完并等待成功,例如先 await storage.setStorage 或业务服务端请求。SDK storage 按 canonical 小程序身份持久化,可由新页面重新读取,但 storage.setStorage 自身要求 storage 权限;这不会让 navigation.reload 也需要该权限。

      Host 终止旧页面时会尽力派发 on('unload'),但 unload 不重放且可能来不及送达,只适合停止轮询、释放观察者等快速幂等清理,不能作为最后一次 持久化机会。若要终止整个小程序容器而不是创建新页面上下文,使用 navigation.close。

      import hbSDK from '@heybox/hb-sdk'

      async function persistFiltersAndReload(filters: { tag: string }) {
      await hbSDK.storage.setStorage({
      key: 'game_filters',
      data: filters,
      })

      await hbSDK.navigation.reload()
      // 不要在这里安排必须执行的逻辑;新页面应从 storage 恢复 filters。
      }

      0.4.4

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none