@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 获取当前用户的 Steam 游戏库。

      参数

      • 可选options: GetSteamGameListOptions

        Steam 账号、分页、排序和过滤条件;不传时使用默认账号、limit: 20、 offset: 0、sort: 'weeks'、includeHidden: false。

      返回 Promise<GetSteamGameListResult>

      以 isLogin、isBound 为判别字段的联合结果:未登录或未绑定 Steam 时 data 为 null;两者均为 true 时返回游戏列表、hasMore 和 nextOffset。

      HbMiniProgramSDKError INVALID_PARAMS 表示存在未知字段,或参数类型、范围 不合法。

      HbMiniProgramSDKError PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED 表示 当前运行快照缺少或未启用 steamLibrary;METHOD_FORBIDDEN 表示当前 Host 缺少该能力依赖。

      HbMiniProgramSDKError INVALID_STATE 表示缺少 canonical 小程序身份; REQUEST_UNSUPPORTED / REQUEST_FAILED / INVALID_RESPONSE 表示 Host 请求能力、Steam 请求或响应失败;HEYBOX_APP_LOGIN_REQUIRED 表示请求期间 Host 登录态失效。

      HbMiniProgramSDKError AUTHORIZATION_CONTEXT_CHANGED 表示请求期间切换账号 或撤销授权;RUNTIME_DESTROYED / SDK_DESTROYED 表示 Runtime 或 SDK 已终止。SDK 握手失败 或超过调用超时时间时,还会返回对应的握手错误码或 REQUEST_TIMEOUT。

      HbMiniProgramSDKError RATE_LIMITED 表示上游返回 403/429,或该 endpoint 处于 Runtime 熔断窗口;error.data.retryAfterMs(可能缺失)给出建议退避时长。

      HbMiniProgramSDKError RATE_LIMITED_BY_RUNTIME 表示 Runtime 本地拒绝(每 session 配额或同 endpoint 循环检测),请求没有到达上游;error.data.origin 为 'budget' 或 'loop'。 两种情况调用方都应停止立即重试。

      项目必须在 package.json#heybox.permissions 声明 steamLibrary。该能力通过 Host 的受信 请求读取当前账号数据,不要求公开 network 权限,也不展示授权 UI 或要求可信用户手势。 它不会调用 auth.login(),也不会返回授权码、token 或可供开发者服务端使用的 Steam scope;公开 OpenAPI 当前也没有 Steam 游戏库资源。开启网络权限后仍可调用本方法。

      steamId 与 q 会 trim;空 q 会被省略,非空 q 最多保留前 100 个 UTF-16 code unit。limit 必须为正整数并在大于 100 时收窄为 100。继续分页时把返回的 data.nextOffset 原样传给下一次调用。

      游戏条目的 portraitImage 是可选竖版封面;上游未提供有效图片或 Host 尚未支持该字段时 会省略,业务可使用 game.portraitImage ?? game.image 选择封面。

      游戏库条目不提供价格信息。

      Host Runtime 默认将相同查询的成功游戏页缓存 24 小时,游戏新增、游玩时长和隐藏状态 可能延迟更新。支持 sandbox 文件操作的宿主可以跨小程序关闭复用;其他宿主仅在当前 Runtime 内复用。缓存仍检查当前账号和绑定上下文,首次全量读取仍需逐页请求。 缓存行为与有效期由 Host Runtime 策略决定,小程序不能通过本方法指定强制刷新。 系统或用户清理缓存目录后会重新请求;24 小时是有效期上限,不保证文件保留时长。

      先检查 isLogin 和 isBound,再读取 data。需要单独读取小黑盒登录态和当前小程序 隔离身份时使用 user.getInfo;需要为开发者服务端建立会话时, 在可信用户操作中使用 auth.login。这两个 API 都要求 userInfo,不能替代本方法的 steamLibrary 权限。

      import hbSDK from '@heybox/hb-sdk'

      const result = await hbSDK.user.getSteamGameList({
      limit: 20,
      offset: 0,
      sort: 'weeks',
      q: '合作',
      })

      if (!result.isLogin) {
      showHeyboxLoginHint()
      } else if (!result.isBound) {
      showSteamBindingHint()
      } else {
      renderGames(result.data.gameList)
      if (result.data.hasMore) {
      saveNextOffset(result.data.nextOffset)
      }
      }

      0.5.0

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none