要监听的
MiniProgramEventName。泛型 T 通常由该字符串
字面量推断,并决定 handler 的 payload 类型。
与 eventName 对应的
MiniProgramEventHandler。payload 由
MiniProgramEventPayloadMap 精确映射。
只解绑当前 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()
注册默认 SDK 实例的事件监听。