握手阶段缓存的同一份 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 })
同步读取握手完成后缓存的环境快照。