cloud.leaderboard.submit @heybox/hb-sdk android ios ohos windows macos android numeric-dot >= 1.3.390 平台基线 ios numeric-dot >= 1.3.390 平台基线 ohos numeric-dot >= 1.3.390 平台基线 windows semver >= 1.0.0 平台基线 macos semver >= 1.0.0 平台基线
[Reference](../../../index.md) / [cloud.leaderboard](./index.md) / `submit`
# cloud.leaderboard.submit
为当前登录用户创建记录，或仅在分数更优时更新已有记录。
## 签名
## 权限
| 权限 | 要求 | 配置 |
| --- | --- | --- |
| `leaderboard` | 声明后可用 | 无 |
在项目根目录的 `package.json#heybox.permissions` 中声明。详见[权限声明](../../../../guide/permissions.md)。
## 兼容性
| 项目 | 内容 |
| --- | --- |
| 加入版本 | SDK `0.5.11` |
| 支持平台 | `android`、`ios`、`ohos`、`windows`、`macos` |
| 客户端要求 | `android: numeric-dot >= 1.3.390`（平台基线）、`ios: numeric-dot >= 1.3.390`（平台基线）、`ohos: numeric-dot >= 1.3.390`（平台基线）、`windows: semver >= 1.0.0`（平台基线）、`macos: semver >= 1.0.0`（平台基线） |
| 稳定性 | 稳定 |
## 参数
| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `options` | `SubmitLeaderboardEntryPayload` | 必填分数、可选榜单 key 和公开展示 extra；必须符合
SubmitLeaderboardEntryPayload 的字段、数值与序列化约束。 |
## 相关类型
- [`LeaderboardEntry`](../../../symbols/root/interfaces/LeaderboardEntry.md)
- [`SubmitLeaderboardEntryPayload`](../../../symbols/root/interfaces/SubmitLeaderboardEntryPayload.md)
## 返回值
服务端保存的当前用户最终 LeaderboardEntry。首次提交返回新记录；同分
或更差时调用仍成功，但返回原有记录，不代表本次 score / extra 已更新。
## 异常
- HbMiniProgramSDKError `INVALID_PARAMS`：`options` 不是对象、含未知字段，
key 不合法，score 缺失/非有限数字/超出安全范围，或 extra 不是对象、不可 JSON 序列化、
超过 2048 UTF-8 bytes。
- HbMiniProgramSDKError `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`：当前运行快照
缺少或未启用 `leaderboard`；`UNAUTHORIZED`：Host 未登录、服务端会话失效，或
请求期间登录账号发生变化。
- HbMiniProgramSDKError `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
小程序未创建 `default` 榜单；`LEADERBOARD_SUBMIT_LOCKED`：同一用户记录正在被另一提交
更新，可在稍后重新提交。命名榜单不存在或后端拒绝时保留服务端错误码。
- HbMiniProgramSDKError `INVALID_STATE`：canonical 小程序身份未就绪；
`METHOD_FORBIDDEN` / `REQUEST_UNSUPPORTED`：当前 Host 缺少所需账号或受信网络能力；
`REQUEST_FAILED`：平台请求失败；`INVALID_RESPONSE`：返回记录字段不符合公开合同。
其他 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'`。两者都应停止立即重试。
- `DOMException` extra 含函数、Symbol 等不可 structured-clone 的内容时，浏览器可能
在请求发送前抛出 `DataCloneError`。
## 说明
当前用户不来自参数。Runtime 先向 Host 读取当前登录状态，再用 Host 持有的受信会话和
canonical 小程序 identity 调用平台；页面不能指定 `appUserId` 或提交其他用户的成绩。
不要先调用用户资料 API 探测登录，直接处理 `UNAUTHORIZED`。该 API 需要声明
`leaderboard`，但不需要公开 `network` 权限或可信用户手势。
“更优”由榜单创建时的 `order` 决定，可通过
getInfo 查询：`desc` 只用更高分更新，
`asc` 只用更低分更新。首次合法分数创建记录；同分和更差分数不更新 score、extra 或
updatedAt。同分记录按更早达到当前分数的 updatedAt 优先，再以 appUserId 稳定排序。
extra 跟随最终保留的分数记录：首次省略时为 `{}`；更优更新省略时保留旧值，传 `{}`
才清空；同分或更差时传入的新值被忽略。由于 extra 会出现在
getList 中，只能保存公开展示数据。
每次成功响应（包括同分/更差而未更新）都会失效同一小程序、同一榜单的全部列表页和
getCurrentUserEntry 五分钟
读缓存；下一次读取重新请求远端。`getInfo` 配置缓存和其他榜单缓存不受影响；提交前已
在途的旧读取可能仍返回给原调用方，但不会回填已失效的缓存。需要移除记录时使用
deleteCurrentUserEntry。
## 示例
```ts
import hbSDK from '@heybox/hb-sdk'
const submittedScore = 1200
const entry = await hbSDK.cloud.leaderboard.submit({
key: 'weekly',
score: submittedScore,
extra: { level: 8 },
})
if (entry.score !== submittedScore) {
console.log('已有成绩更优，本次未覆盖', entry.score)
} else if (entry.ranked) {
console.log(`成绩已保存，当前排名 ${entry.rank}`)
} else {
console.log('成绩已保存，暂未获得精确名次')
}
```
## 相关 API 与文档
- [cloud.leaderboard.getInfo](./getInfo.md)
- [cloud.leaderboard.getList](./getList.md)
- [cloud.leaderboard.getCurrentUserEntry](./getCurrentUserEntry.md)
- [cloud.leaderboard.deleteCurrentUserEntry](./deleteCurrentUserEntry.md)
- [云端排行榜指南](https://docs.xiaoheihe.cn/hb_sdk/guide/cloud-leaderboard)
## 浏览
- 上一个：[`cloud.leaderboard.getList`](./getList.md)