@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 读取指定排行榜创建时确定的排序与展示配置。

      参数

      返回 Promise<GetLeaderboardInfoResult>

      规范化的 GetLeaderboardInfoResult:实际榜单 key、排序方向 order 和列表展示上限 rankLimit。不返回榜单记录或当前用户数据。

      HbMiniProgramSDKError INVALID_PARAMS:options 不是对象、含 key 以外 的字段,或 key 不符合 1 至 64 位 [A-Za-z0-9_-] 规则。

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

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

      HbMiniProgramSDKError INVALID_STATE:canonical 小程序身份未就绪; METHOD_FORBIDDEN / REQUEST_UNSUPPORTED:当前 Host 缺少所需受信网络能力; REQUEST_FAILED:平台请求失败;INVALID_RESPONSE:返回 key、order 或 rankLimit 不符合公开合同。其他 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 让低分优先。调用 submit 时无需也不能再次传入 order; 服务端按这里返回的方向决定新分数是否优于已有记录。

      rankLimit 控制 getList 的列表展示 名次范围,0 表示不设该范围上限。它与 getList 的每页 limit 相互独立,也不会删除 范围外记录;当前用户的 ranked 还受前 5000 名精确排名上限限制。

      当前 Runtime 最多为 3 个活跃榜单 bucket 缓存结果五分钟;超过上限的榜单读取不进入缓存。 同时发起的相同查询仍会合并为一个远端请求。submit() 和 deleteCurrentUserEntry() 只失效同榜单的列表/当前用户缓存, 不会失效 getInfo 配置缓存;其他榜单也使用独立缓存。Host 账号变化或 Runtime 销毁会 清空缓存与在途合并状态。SDK 没有强制刷新参数,缓存过期或新 Runtime 才会重新读取。

      import hbSDK from '@heybox/hb-sdk'

      const info = await hbSDK.cloud.leaderboard.getInfo({ key: 'weekly' })
      const page = await hbSDK.cloud.leaderboard.getList({ key: info.key, limit: 20 })

      const direction = info.order === 'desc' ? '高分优先' : '低分优先'
      const range = info.rankLimit === 0 ? '不限制展示名次' : `仅展示前 ${info.rankLimit} 名`
      console.log(direction, range, page.entries)

      0.5.11

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none