由 target 判别的目标页参数;字段与规范化规则见 OpenAppPageOptions。
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' },
})
}
请求宿主打开受 SDK 白名单约束的黑盒 App 页面或公开小程序。