@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...

    函数 on

    • 注册默认 SDK 实例的事件监听。

      类型参数

      参数

      返回 () => void

      只解绑当前 eventName / handler 组合的函数。调用一次或多次都返回 void 且不会抛错, 不影响同一事件上的其他 handler。

      事件名决定 payload 字段:

      • launch:{ timestamp, url? };ready:{ timestamp };
      • show / hide:{ timestamp, source? };unload:{ timestamp };
      • error: MiniProgramBridgeError,包含 code、 message 与可选 data,不是 JavaScript Error 实例;
      • heybox_app_login_change:{ isHeyboxAppLoggedIn, accountKey? }(缺失 key 表示待确认);
      • user_info_authorization_change: UserInfoAuthorization,包含 identity 与 profile 两项授权状态,支持 Steam 账号能力时还可能包含 steam_account;
      • companion.session.output:{ sessionId, controllerGeneration, stream, sequence, data };
      • companion.session.exit:{ sessionId, exit };
      • companion.session.ownershipLost:{ sessionId, controllerGeneration }。

      on() 同步把 handler 加入默认 SDK 实例的本地 event bus,不等待握手、不发送 bridge 请求。 注册本身无需在 package.json#heybox.permissions 中声明权限,不要求可信用户手势,也不会因当前 握手处于 connecting、ready 或 failed 而抛出 SDK 错误。具体事件是否会产生,仍取决于 Host、 Runtime 生命周期和相关业务能力。

      event bus 使用 Set 保存每个事件的 handler。同一事件与同一函数引用重复注册只有一个有效监听; 任一返回的 unsubscribe 或 off() 都会移除该唯一注册。不同函数引用 不会去重,同一函数注册到不同事件也彼此独立。应保存 unsubscribe,并在页面、组件或业务模块销毁 时调用;unsubscribe 可安全重复调用。

      handler 在事件派发时同步执行。SDK 不捕获普通事件 handler 的同步异常,也不等待其 Promise;某个 handler 抛错可能阻断同次派发中的后续 handler,异步拒绝也可能成为未处理 Promise。需要隔离时在 handler 内自行 try/catch,并显式处理异步任务的 rejected Promise。

      所有生命周期与业务事件都不会重放:只派发给事件到达时已经注册的 handler,晚注册无法取回 launch、ready 或其他历史事件。ready 只是握手成功瞬间的边沿通知,Host 重复派发时 handler 也可能再次执行;需要可查询、会向订阅者立即回放且只迁移一次的握手状态时,使用 getHandshakeState() 和 onHandshakeStateChange()。

      收到 unload 后当前 Runtime 上下文不可恢复,在途请求会失败,也不应再依赖后续 bridge 事件; SDK 内部销毁会移除底层 message listener。调用 unsubscribe 只清理该本地事件 handler,不取消 API 请求、业务任务、Companion 进程或握手状态订阅。

      import hbSDK from '@heybox/hb-sdk'

      const stopShow = hbSDK.on('show', ({ timestamp, source }) => {
      try {
      refreshVisibleData({ timestamp, source })
      } catch (error) {
      reportHandlerError(error)
      }
      })

      const stopError = hbSDK.on('error', ({ code, message }) => {
      console.error(code, message)
      })

      // 页面或组件销毁时;重复调用也安全。
      stopShow()
      stopShow()
      stopError()

      0.3.1

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none