@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 同步读取握手完成后缓存的环境快照。

      返回 MiniProgramEnvironmentInfo

      握手阶段缓存的同一份 MiniProgramEnvironmentInfo 深度冻结快照,包含:

      • runtime.mode:当前实例的 MiniProgramRuntimeMode;
      • host.appVersion:Host 提供的小黑盒 App 版本,缺失或非法时为 null;
      • miniProgram.id:平台确认的 canonical 小程序 ID,缺失或非法时为 null;
      • miniProgram.version:当前加载的小程序版本,缺失或非法时为 null;
      • operatingSystem.name:Host 提供的 MiniProgramOperatingSystemName;
      • operatingSystem.version:Host 提供的系统版本,缺失或非法时为 null;
      • sdk.version:当前页面实际运行的 @heybox/hb-sdk 版本。

      HbMiniProgramSDKError 当前握手状态为 connecting 时同步抛出 ENVIRONMENT_NOT_READY。这也包括 Host 已返回握手响应、但 SDK 尚未收到 ready 事件的短暂阶段。

      HbMiniProgramSDKError 当前握手状态为 failed 时原样重抛 state.error;其错误码可能是 NOT_IN_IFRAME、MISSING_NONCE、READY_TIMEOUT、 HANDSHAKE_FAILED、RUNTIME_UNAVAILABLE 或 SDK_DESTROYED 等握手错误,而不是 ENVIRONMENT_NOT_READY。

      该方法不接收参数、不等待握手,也不会向 Host 发起新请求。它严格按当前持久握手状态同步返回 或抛错:connecting 抛出 ENVIRONMENT_NOT_READY,failed 重抛原始握手错误,只有 ready 返回快照。一般业务代码应优先使用会自动等待握手的 environment.getInfo();本方法适用于已经由同步控制流确认 ready,且调用方不能引入异步边界的场景。

      SDK 会在发布 ready 状态前缓存快照,因此在 onHandshakeStateChange() 的 ready 分支中可立即 调用。也可以先检查 getHandshakeState(),但检查与读取 应在同一段同步代码中完成。不要依赖不会重放的 ready 生命周期事件判断当前状态。

      首次成功读取、后续同步读取和异步 getInfo() 都返回引用相同的对象,不会重新请求、重新创建或 随页面生命周期更新。返回对象及全部嵌套对象均已冻结;旧版 Host 缺失环境信息时仍返回固定结构, 字符串字段以 null、枚举字段以 unknown 表示未知值。除 sdk.version 外,版本字段都是不透明 字符串,不能用于版本大小判断。

      该 API 无需权限且不触发用户授权。快照适合在同步渲染、界面适配、兼容降级、埋点或诊断中使用; 它不包含账号信息或设备唯一标识,也不能作为鉴权、权限控制或风控依据。

      import {
      environment,
      onHandshakeStateChange,
      } from '@heybox/hb-sdk'

      const unsubscribe = onHandshakeStateChange(state => {
      if (state.status === 'connecting') return

      if (state.status === 'failed') {
      console.error('SDK 握手失败', state.error.code)
      return
      }

      // ready 发布前快照已经缓存,这里不会抛 ENVIRONMENT_NOT_READY。
      const info = environment.getInfoSync()
      renderForPlatform(info.operatingSystem.name)
      })

      window.addEventListener('unload', unsubscribe, { once: true })

      0.8.1

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none