@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 请求宿主打开受 SDK 白名单约束的黑盒 App 页面或公开小程序。

      参数

      返回 Promise<void>

      Host 接收参数并发起页面路由后 resolve undefined;不会等待目标页加载或返回目标页结果。

      HbMiniProgramSDKError INVALID_PARAMS 表示 options、target、必填 ID、 gameType、page 或其他已知字段不合法。SDK 会在调用 bridge 前拒绝这些输入。

      HbMiniProgramSDKError METHOD_FORBIDDEN / METHOD_NOT_FOUND 表示当前 Host 未实现或未开放该能力;REQUEST_UNSUPPORTED 表示 Host 不支持所选目标或路由形状,例如 当前 PC Host 的 user_detail、post_detail,或缺少 navigation.openGameDetail 子能力。

      HbMiniProgramSDKError RUNTIME_DESTROYED / RUNTIME_UNAVAILABLE / SDK_DESTROYED 表示 Runtime、容器或 SDK 已进入终态。SDK 握手失败或 Host 路由调用超时 时,还会返回对应握手错误码或 REQUEST_TIMEOUT;其他 Host 路由失败保留其 SDK 错误码。

      公开白名单包含游戏详情、用户详情、帖子详情和公开小程序;不能传任意 URL、scheme、版本 或客户端内部路径。mini_program 只接受 miniProgramId 与可选 extra,目标版本和访问性 由 Host 决定。extra 与分享扩展数据使用相同格式,目标小程序通过 share.getExtra() 读取。 Runtime 会在 Host 边界再次校验,页面提供的字段不能覆盖目标路径或窗口展示参数。

      打开 mini_program 前,支持方向控制的 Host 会先把当前容器恢复为竖屏、非全屏,并等待 宿主确认后才打开目标;确认状态变化时发出 display_change(source: 'api')。恢复阶段 最多等待 10 秒,超时返回 ORIENTATION_TIMEOUT 并取消宿主方向操作。SDK 总请求超时 返回 REQUEST_TIMEOUT,同时通知 Runtime 取消;SDK 销毁也会取消尚未完成的跳转。 恢复错误或请求取消后不会打开目标,晚到的方向成功回复也不会继续跳转。没有方向原语 或返回 supported: false 的旧 Host 仍允许跳转。返回当前小程序后不会 自动回到原方向,需要横屏的页面应在 show 事件中重新调用 viewport.setDisplay()。

      移动端 Host 支持全部四类目标。当前 Windows/macOS PC Host 支持 game_detail 和 mini_program,仍不支持 user_detail、post_detail;游戏详情只把 appId 交给导航, gameType 仍须合法,而 page、hSrc、skuId 不保证在 PC 生效。调用方应按目标和平台 处理 REQUEST_UNSUPPORTED,不能仅凭方法出现在能力目录中推断每种目标都可用。

      该调用无需 package.json#heybox.permissions 声明、平台批准、用户授权或可信用户手势。 它只发起一次 App 导航,没有返回值或 disposer,也不会替代 navigation.close 或 navigation.reload 对当前小程序容器的控制。

      import hbSDK from '@heybox/hb-sdk'

      async function openGameWiki() {
      await hbSDK.navigation.openAppPage({
      target: 'game_detail',
      appId: 578080,
      gameType: 'pc',
      page: 'wiki',
      hSrc: 'workshop',
      })
      }

      async function openUserProfile(heyboxId: string) {
      await hbSDK.navigation.openAppPage({
      target: 'user_detail',
      userId: heyboxId,
      })
      }

      async function openPostComment(linkId: number, rootCommentId: number, commentId: number) {
      await hbSDK.navigation.openAppPage({
      target: 'post_detail',
      linkId,
      rootCommentId,
      commentId,
      })
      }

      async function openMiniProgram() {
      await hbSDK.navigation.openAppPage({
      target: 'mini_program',
      miniProgramId: '2e2b8e19-8d73-45f8-8785-b87fd5535510',
      extra: { page: 'ranking' },
      })
      }

      0.5.2

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none