云端排行榜

cloud.leaderboard 用来提交和读取跨用户排名，适合最高分、最短耗时、关卡成绩等场景。用户身份由宿主注入，页面不要传 appUserId。

创建榜单

页面使用排行榜前，需要先为当前小程序创建一个榜单。开发时可以用 hb-sdk remote：

bash

hb-sdk remote cloud leaderboard create cube_run_total --order desc --rank-limit 500

创建后，页面里使用同一个 key：

const LEADERBOARD_KEY = 'cube_run_total'

key 必须是 1-64 位，只能包含 [A-Za-z0-9_-]；空字符串、中文、空格、点号或超长 key 会以 INVALID_PARAMS 拒绝。

order 决定排名方向：desc 表示分数越高越靠前，asc 表示分数越低越靠前。更多管理命令见 CLI 与本地 mock 调试。

如果项目使用 default 榜单，运行时可以省略 key。默认榜单也需要先创建。

提交分数

import hbSDK from '@heybox/hb-sdk'

const entry = await hbSDK.cloud.leaderboard.submit({
  key: 'cube_run_total',
  score: 150,
  extra: {
    stage: 'forest',
  },
})

console.log(entry.ranked ? `当前排名：${entry.rank}` : '已保存成绩', entry.score)

同一个用户在同一个榜单里只有一条记录。submit() 只会在新分数更优时更新记录，并返回当前用户最终记录。

“更优”由创建榜单时的 order 决定：desc 只保留更高分，asc 只保留更低分。提交相同或更差的分数不会覆盖已有 score 或 extra，但调用仍会成功并返回已保存的最终记录。因此页面应以返回的 entry 更新 UI，不要假设本次传入值一定落库。多个窗口或快速重复提交也遵循同一服务端比较规则，无需在前端用“先查后写”实现锁。

返回状态	含义	UI 建议
`ranked: true`	成绩已保存，并且当前名次可精确展示	展示 `rank`
`ranked: false, rank: 0`	成绩已保存，但超出榜单展示范围或前 5000 名精确排名范围	展示“成绩已保存”，不要显示第 0 名

读取榜单

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

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

appUserId 是当前用户在当前小程序内稳定的隔离标识，不是黑盒用户 ID；同一用户在不同小程序中的值不同。它只由平台写入排行榜记录，页面只能读取，不能在提交参数中传入或据此跨小程序关联用户。

limit 默认 20，最大 100。需要下一页时，把返回的 cursor 原样传回同一 key 的下一次 getList()。hasMore: false 表示本次遍历结束；不要自行解析游标，也不要仅凭 entries.length === limit 推断还有下一页。

展示昵称、头像等用户资料

排行榜不会自动附带昵称和头像；需要时，通过 hbSDK.user.getInfo() 读取资料，随分数写入 extra，读取榜单时再从 entry.extra 取出展示。见附带用户展示资料示例。

读取榜单信息

const info = await hbSDK.cloud.leaderboard.getInfo({
  key: 'cube_run_total',
})

console.log(info.order, info.rankLimit)

getInfo() 返回 key、order 和 rankLimit。rankLimit 为 0 时表示列表不限制展示名次。

当前用户记录

const current = await hbSDK.cloud.leaderboard.getCurrentUserEntry({
  key: 'cube_run_total',
})

console.log(current)

当前用户没有记录时，getCurrentUserEntry() 正常返回 undefined，不应直接解引用。submit()、getCurrentUserEntry() 和 deleteCurrentUserEntry() 都由平台代管能力校验 Host 登录状态；未登录调用会抛出 HbMiniProgramSDKError，错误码为 UNAUTHORIZED。不要通过用户资料 API做前置探测，公开的 getList() 和 getInfo() 不要求登录。

删除成绩会立即移除当前用户在该榜单中的记录，应只在明确的用户操作和二次确认后调用：

async function deleteMyLeaderboardEntryFromUserAction() {
  const confirmed = window.confirm('确定删除自己的榜单成绩吗？')
  if (!confirmed) return

  const result = await hbSDK.cloud.leaderboard.deleteCurrentUserEntry({
    key: 'cube_run_total',
  })
  console.log(result.deleted)
}

deleteCurrentUserEntry() 只能删除当前用户自己的记录。没有现存记录时，删除结果中的字段为 deleted: false，这是一种正常空结果，不代表请求失败。

注意事项

score 必须是有限安全数字。
extra 会随榜单记录返回给榜单中的其他读取者，只能放公开展示需要的小 JSON；不要写入邮箱、外部账号、设备标识、token 或非必要的行为数据。它不参与排序和查询。
ranked: false 表示已保存成绩，但没有进入榜单展示范围。
宿主会将相同的排行榜读请求缓存 5 分钟；当前 runtime 内提交或删除成绩会刷新榜单和当前用户记录，其他用户的成绩变化可能延迟显示。
未创建默认榜单时，运行时请求会返回 LEADERBOARD_DEFAULT_NOT_FOUND。
getCurrentUserEntry() 返回 undefined、删除返回 deleted: false 都是正常空结果，不应记录为异常。
排行榜数据属于远端平台能力；页面 reload、Host 重启或更换设备不会清空记录。本地 loading 状态和分页游标不属于该持久状态。
常见组合写法见排行榜页面 Recipe。

云端排行榜 ​

创建榜单 ​

提交分数 ​

读取榜单 ​

展示昵称、头像等用户资料 ​

读取榜单信息 ​

当前用户记录 ​

注意事项 ​