@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 按服务端排名顺序读取排行榜的一页记录。

      参数

      返回 Promise<GetLeaderboardListResult>

      当前页 LeaderboardEntry 数组、可选下一页 cursor 和权威 hasMore 标记。

      HbMiniProgramSDKError INVALID_PARAMS:options 不是对象、含未知字段, key 不符合 1 至 64 位 [A-Za-z0-9_-],limit 不是 1 至 100 的整数,或 cursor 不是字符串。

      HbMiniProgramSDKError PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED:当前运行快照 缺少或未启用 leaderboard 权限。

      HbMiniProgramSDKError LEADERBOARD_DEFAULT_NOT_FOUND:省略 key 但当前 小程序未创建 default 榜单。命名榜单不存在、cursor 失效或后端拒绝时保留服务端错误码。

      HbMiniProgramSDKError INVALID_STATE:canonical 小程序身份未就绪; METHOD_FORBIDDEN / REQUEST_UNSUPPORTED:当前 Host 缺少所需受信网络能力; REQUEST_FAILED:平台请求失败;INVALID_RESPONSE:entries、cursor、hasMore 或任一记录 字段不符合公开合同。其他 bridge 超时与 SDK 状态错误会保留对应错误码。

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

      HbMiniProgramSDKError RATE_LIMITED_BY_RUNTIME:Runtime 本地配额或循环检测 拒绝,请求没有到达上游;error.data.origin 为 'budget' 或 'loop'。两者都应停止立即重试。

      该查询不要求 Host 登录、用户授权或可信用户手势。它需要声明 leaderboard,但不需要 公开 network 权限;Runtime 使用 Host 的受信网络端口读取 canonical 小程序所属榜单。 页面不能通过参数查询其他小程序,也不能指定用户过滤列表。

      榜单创建时的 order 决定返回顺序:desc 高分优先,asc 低分优先。非零 rankLimit 限制可展示到的最大名次,0 表示不设置列表名次上限;本方法的 limit 只控制单页最多返回数量,不能修改 order 或突破 rankLimit。可通过 getInfo 读取这两项配置。

      cursor 是服务端分页状态,不是 offset 或页码。首次请求省略 cursor;当 hasMore 为 true 且返回 cursor 时,下一页必须把它原样传回同一 key,并保持相同 limit。 hasMore: false 才表示本次遍历结束,不能仅凭页面不足 limit 条记录提前停止。

      当前 Runtime 最多为 3 个活跃“小程序 + 榜单 key” bucket 缓存每一页五分钟;超过该上限的 榜单读取不进入缓存。无论是否缓存,同参数的并发读取都会合并为一个远端请求;不同页、 不同 limit 或不同榜单互不命中。其他用户成绩变化在缓存期内可能暂时不可见。成功的 submit 或 deleteCurrentUserEntry 会失效同榜单的全部列表页与当前用户缓存,下一次读取重新请求;getInfo 配置缓存和其他 榜单缓存不受影响。

      import hbSDK from '@heybox/hb-sdk'

      let cursor: string | undefined
      do {
      const page = await hbSDK.cloud.leaderboard.getList({
      key: 'weekly',
      limit: 20,
      ...(cursor ? { cursor } : {}),
      })

      for (const entry of page.entries) {
      console.log(entry.rank, entry.score, entry.extra)
      }

      if (!page.hasMore || !page.cursor) break
      cursor = page.cursor
      } while (true)

      0.5.11

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none