可选options: GetCurrentUserLeaderboardEntryPayload可选榜单选择参数;省略时读取 default 榜单。显式 options.key 必须
符合 GetCurrentUserLeaderboardEntryPayload.key 的格式约束。
当前用户的完整 LeaderboardEntry;没有记录时 resolve undefined,这是
正常空结果。返回记录但 ranked: false 时记录仍存在,rank 固定为 0。
HbMiniProgramSDKError INVALID_PARAMS:options 不是对象、含 key 以外
的字段,或 key 不符合 1 至 64 位 [A-Za-z0-9_-] 规则。
HbMiniProgramSDKError PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED:当前运行快照
缺少或未启用 leaderboard;UNAUTHORIZED:Host 未登录、服务端会话失效,或
请求期间登录账号发生变化。
HbMiniProgramSDKError LEADERBOARD_DEFAULT_NOT_FOUND:省略 key 但当前
小程序未创建 default 榜单。命名榜单不存在或后端拒绝时保留服务端错误码。
HbMiniProgramSDKError INVALID_STATE:canonical 小程序身份未就绪;
METHOD_FORBIDDEN / REQUEST_UNSUPPORTED:当前 Host 缺少所需账号或受信网络能力;
其他网络失败、响应字段不合法和 bridge 超时分别保留对应 REQUEST_FAILED、
INVALID_RESPONSE 或 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'。两者都应停止立即重试。
当前用户不来自参数。Runtime 每次调用都会先向 Host 校验当前登录账号,再用 Host 持有的
受信会话读取平台为该账号和 canonical 小程序身份关联的记录。页面不能指定或猜测其他
用户,也不应先调用用户资料 API 探测登录;直接处理本方法的 UNAUTHORIZED 即可。
该 API 需要声明 leaderboard,但不需要公开 network 权限或可信用户手势。
返回的 appUserId 是当前用户在当前小程序内的隔离标识,不是黑盒用户 ID、登录凭据或
可跨小程序关联的账号字段。extra 会随
getList 返回给该榜单的其他读取者,
调用方应把它当作公开展示数据。
ranked 同时受榜单 rankLimit 和当前用户前 5000 名精确排名上限约束:两项均满足时
ranked: true 且 rank 为正整数;任一不满足时记录仍返回,但固定为
ranked: false, rank: 0。即使 rankLimit 为 0(列表不限制),前 5000 名计算上限
仍然存在。不要用 rank === 0 判断“没有记录”,应先判断整个返回值是否为 undefined。
当前 Runtime 最多为 3 个活跃榜单 bucket 缓存结果(包括 undefined)五分钟;超过上限的
榜单读取不进入缓存。同一时刻的重复读取仍会合并为一个远端请求。账号变化会清空全部榜单缓存,并使旧账号的
在途响应以 UNAUTHORIZED 结束;成功的
submit 或
deleteCurrentUserEntry
会使同榜单的当前用户与列表缓存立即失效,下一次读取重新请求远端。
getCurrentUserEntry() 可以返回仍存在但未进入列表展示范围的记录;分页
getList() 中没有当前用户,不等于当前用户没有记录。需要创建或更新记录时调用
submit(),需要删除时调用 deleteCurrentUserEntry()。
import hbSDK from '@heybox/hb-sdk'
const entry = await hbSDK.cloud.leaderboard.getCurrentUserEntry({
key: 'weekly',
})
if (!entry) {
console.log('还没有成绩')
} else if (entry.ranked) {
console.log(`当前成绩 ${entry.score},排名 ${entry.rank}`)
} else {
console.log(`成绩 ${entry.score} 已保存,暂未获得精确名次`)
}
读取当前登录用户在指定排行榜中的记录。