@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 取消指定 alias 的在途准备;已进入原子提交时最终提交结果优先于取消意图。

      参数

      • alias: string

        package.json#heybox.companions 中声明的 Companion alias。必须完整匹配 [a-z][a-z0-9-]{0,31}:长度为 1 至 32,第一个字符是小写 ASCII 字母,其余字符 只能是小写字母、数字或连字符;SDK 不会 trim 或改变大小写。

      返回 Promise<void>

      Host 处理本次取消意图后以 undefined resolve。该时点不表示关联的 prepare() Promise 已经 settle,也不返回是否找到在途操作或取消是否赢得竞态。

      HbMiniProgramSDKError alias 不符合格式时在请求前以 INVALID_PARAMS 拒绝;当前审核版本未声明该 alias、目标平台不匹配或 Host 不支持 Companion 时可能以 COMPANION_NOT_DECLARED、COMPANION_TARGET_UNSUPPORTED、COMPANION_UNSUPPORTED 或 METHOD_FORBIDDEN 拒绝。当前运行快照缺少或未启用 companion 权限时分别以 PERMISSION_NOT_IN_SNAPSHOT、PERMISSION_DENIED 拒绝;握手失败、SDK/Runtime 已销毁、 bridge 超时及其他 Host 失败会保留对应 SDK 错误码。

      这是幂等、best-effort 的 Host 取消请求。没有在途准备时调用会成功 no-op;alias 已经 ready 时也会成功,但不会删除、回滚或使已提交产物变回 not-prepared。重复调用不会 叠加取消次数,也不会停止已启动的 Companion Session。

      取消只在 Host 原子提交开始前保证有机会终止下载、校验或解压。取消和提交并发时, 原子提交结果优先:本方法可能已经 resolve,而受影响的 prepare() 仍成功返回,随后 companion.getPreparationStatus 也可能是 ready。取消抢先生效时,在途 prepare() 通常以 COMPANION_PREPARATION_CANCELLED 拒绝;该错误属于准备调用,不是本方法成功 resolve 的 返回值。调用后应重新查询 Host 状态,不能直接把 UI 固定为 not-prepared。

      本方法需要已声明并经平台批准的 companion 权限,但不需要可信用户手势,也不会显示 prepare/launch 的 Host 授权弹窗。显式取消按钮或新页面取消旧的 Host 操作时应 await 本方法;若取消只与当前 prepare() 调用的生命周期绑定,可传入 AbortSignal,在途 调用的 signal 触发时 SDK 会向 Host 发送同类取消意图,但页面 reload 本身不会自动取消 Host 操作。

      import hbSDK from '@heybox/hb-sdk'

      await hbSDK.companion.cancelPreparation('runner')

      const status = await hbSDK.companion.getPreparationStatus('runner')
      if (status.state === 'ready') {
      // 原子提交赢得竞态,产物仍然可以由新的用户操作启动。
      showReadyState()
      } else {
      renderPreparationStatus(status)
      }

      0.8.1

      windows

      macos

      windows none

      macos none