注册 handler 时使用的同一个事件名。只检查该事件自己的监听集合,不影响 其他事件上的注册。
传给 on(eventName, handler) 的同一个函数对象。签名或函数体相同的新函数不是
同一引用,不能移除原监听。
void。移除成功、目标从未注册或此前已经移除时都不返回状态。
该函数同步修改默认 SDK 实例的本地 event bus,不等待握手、不发送 bridge 请求,也不会调用
handler。它无需在 package.json#heybox.permissions 中声明权限,不要求可信用户手势;握手处于
connecting、ready 或 failed,以及已经收到 unload 时,取消操作本身都不会产生 SDK 错误。
匹配规则是 eventName 与 handler 函数引用同时相等。匹配后只移除这一项,同一事件上的其他
handler、同一 handler 在其他事件上的注册均保留。event bus 对同一事件与同一函数引用使用集合
语义,重复 on() 只有一个有效注册,一次 off() 即会移除;重复调用 off() 是幂等的,未知事件
或未注册 handler 会被静默忽略。
大多数场景优先保存并调用 on() 返回的 unsubscribe:它已经闭包绑定
正确的事件名和 handler,同样可以重复调用。只有调用方需要在另一处按具名 handler 精确移除时,
才直接使用 off()。匿名函数必须先保存引用;重新创建一个内容相同的箭头函数无法取消旧监听。
生命周期与业务事件不会重放,只派发给事件到达时仍处于注册状态的 handler。off() 只阻止后续
事件,不能撤销已经执行的 handler,也不能取回注册前错过的 launch、ready、show、hide、
unload 等事件。当前握手状态应通过
getHandshakeState() 或
onHandshakeStateChange() 获取,不要通过重新注册
ready 事件补状态。
Runtime unload 或 SDK 内部销毁后不会再有可依赖的未来 bridge 生命周期事件,但调用 unsubscribe
或 off() 做本地清理仍可安全重复执行。取消监听不会取消已经开始的 API 请求、业务任务或
onHandshakeStateChange() 订阅;后者必须调用其自己返回的取消函数。
import hbSDK from '@heybox/hb-sdk'
const pauseOnHide = () => pausePolling()
const reportHide = () => reportVisibility('hidden')
hbSDK.on('hide', pauseOnHide)
const stopReporting = hbSDK.on('hide', reportHide)
hbSDK.off('hide', pauseOnHide) // 只移除 pauseOnHide
hbSDK.off('hide', pauseOnHide) // 已移除,仍然安全
stopReporting() // 推荐:使用 on() 返回的取消函数
移除默认 SDK 实例的事件监听。