@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 实验性

      设置当前小程序的窗口方向和全屏状态。

      SDK 1.0.0 计划将本方法调整为 Promise<void>:设置完成时正常返回,不支持时抛出明确错误; 切换失败、超时或取消仍抛出对应错误。当前仍返回 { supported: boolean },现有行为保持不变。

      请提前补齐 try/catch,过渡期保留 supported: false 判断,并先检查返回值是否存在再读取该字段; 避免直接解构返回值或将未来的空返回值当作失败。仅在确认设置成功后继续依赖该设置的操作。 不支持时的错误码与适配期限会在 1.0.0 正式发布前公告,并提供预发布版本验证。

      参数

      • options: SetDisplayPayload

        方向与全屏目标,至少提供一个字段;省略的字段保持当前目标值。

      返回 Promise<SetDisplayResult>

      Host 完成原生方向与胶囊设置、布局稳定后返回 { supported: true };能力缺失或 请求不受支持时返回 { supported: false },调用方仍应按实际窗口与安全区布局。

      HbMiniProgramSDKError INVALID_PARAMS 表示参数不合法; ORIENTATION_TIMEOUT 表示展示操作超时,ORIENTATION_FAILED 表示执行失败, ORIENTATION_SUPERSEDED 表示被后续不同目标替代,REQUEST_CANCELLED 表示操作已取消。 SDK 或 Runtime 销毁、握手失败等其他错误保留对应 SDK 错误码。

      新容器默认竖屏、非全屏。省略字段保持当前目标值,至少传一个字段;合并后横屏强制全屏,竖屏按 fullscreen 控制。 全屏同时收起胶囊和宿主额外顶部栏,不保证原生内容铺满容器;页面应按实际 WebView 窗口和安全区适配。 系统状态栏、手势条不保证隐藏,重要控件仍应按实际窗口与安全区信息避让。 横屏时仅设置 fullscreen: false 不会退出全屏;退出需同时设置 orientation: portrait、fullscreen: false。 宿主退出按钮恢复竖屏、非全屏;仅设置 orientation: portrait 则保留当前全屏目标。 设置持续到下次调用或退出容器;SPA 路由应在进入时明确设置所需状态。 后续设置先合并目标,再取消不同的旧设置;旧调用以 ORIENTATION_SUPERSEDED 失败。 相同目标共用操作;方向和全屏一起确认,失败时一起恢复最后确认状态。 本方法等待 Host 展示操作完成,由 Runtime 的操作截止时间控制,不使用普通 bridge 请求的独立超时计时器。 操作超时或 SDK 销毁会向 Host 传递取消;不要依赖迟到的 Host 成功结果推进业务状态。 窗口尺寸与安全区变化通过 viewport_change 事件通知。 方向或全屏状态确认变化时通过 display_change 通知,包括用户点击宿主退出全屏按钮。 display_change 不回放初始状态;重复设置、不支持、失败或取消不会发出展示状态变化通知。 返回 supported: true 表示原生方向与胶囊设置已完成;不支持时返回 supported: false,保留原生状态。 降级时宿主仍尽力收起 H5 顶部栏,不能据此假定屏幕已旋转或胶囊已隐藏;布局始终按实际窗口适配。 SDK 统一处理能力缺失错误;超时、取消、参数或其他执行错误仍抛出。

      import hbSDK from '@heybox/hb-sdk'

      // 同时恢复竖屏和非全屏,避免保留之前的全屏目标。
      const result = await hbSDK.viewport.setDisplay({ orientation: 'portrait', fullscreen: false })
      if (!result.supported) console.log('Host 不支持原生展示设置')

      0.8.3

      android

      ios

      ohos

      android numeric-dot >= 1.3.396

      ios numeric-dot >= 1.3.396

      ohos numeric-dot >= 1.3.396