可选options: GetLeaderboardListPayload可选榜单 key、页大小和上一页 cursor;全部省略时读取 default 榜单
首屏并使用 limit: 20。各字段必须符合 GetLeaderboardListPayload 的约束。
当前页 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)
按服务端排名顺序读取排行榜的一页记录。