可选options: GetLeaderboardInfoPayload可选榜单选择参数;省略时读取 default 榜单。显式 options.key 必须
符合 GetLeaderboardInfoPayload.key 的格式约束。
规范化的 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)
读取指定排行榜创建时确定的排序与展示配置。