---
title: "排行榜"
description: "用 api.leaderboard 给卡加自己的高分榜：平台存分数排名次，榜长什么样由卡自己画。"
---
<div v-pre>

# 排行榜

给卡加一个高分榜，做法和 Steam 游戏的排行榜一样：卡给榜起个名字、提交分数，平台记住每个玩家的最好成绩并排好名次。**榜长什么样完全由卡自己画**：放在哪、配色、字体、头像、奖杯、上榜动画，都跟着卡的风格走。平台不会在卡外面另加一个榜。

适合有分数、用时、连胜、通关层数的卡：弹球、跑酷、答题、生存天数、解谜用时都行。

## 跟创作助手说

最简单的做法是直接说，比如：

- 「加个排行榜，一局结束时显示我的名次和前十名」
- 「做一个通关用时榜，越快越靠前，标题画面也能看」
- 「榜上加好友那一栏，排名前三用金银铜」

助手会写好提交和读榜的代码，并按卡现有的样子画榜。想改样子，像改别的界面一样跟它说就行。

## 自己写的话

在界面代码里（**面板 → 界面代码**）用 `useYumina()` 拿到 `api`：

- `api.leaderboard.submit(榜名, 分数, { details?, order? })`：一局结束时提交。每人每个榜只留最好的一次，返回 `{ ok, best, rank, total, improved }`。
- `api.leaderboard.get(榜名, { range?, limit? })`：读榜。`range` 是 `"top"`（前几名）、`"around"`（自己上下几名）或 `"friends"`（自己和好友）。返回的每一行是 `{ rank, name, image, score, details, me }`，`me` 为 true 的那行是玩家自己；`board.me` 是玩家自己的名次，即使不在这一页里。

```tsx
const BOARD = "最高分";

export default function Game() {
  const api = useYumina();
  const [range, setRange] = React.useState("top");
  const [board, setBoard] = React.useState(null);
  const [result, setResult] = React.useState(null);

  const load = React.useCallback(async (r) => {
    setBoard(await api.leaderboard.get(BOARD, { range: r, limit: 10 }));
  }, [api]);
  React.useEffect(() => { void load(range); }, [range, load]);

  // 一局结束时调用
  const finish = async (score) => {
    const r = await api.leaderboard.submit(BOARD, score, { details: { hero: "钢珠" } });
    setResult(r);           // { ok, best, rank, total, improved }
    void load(range);
  };

  return (
    <div>
      {/* 榜长什么样完全由你画：配色、字体、头像、奖杯、动画都随卡的风格 */}
      {result?.ok && <div>{result.improved ? "新纪录！" : `你的最好成绩 ${result.best}`} · #{result.rank} / {result.total}</div>}
      {["top", "around", "friends"].map((r) => <button key={r} onClick={() => setRange(r)}>{r}</button>)}
      {board?.ok && board.entries.map((e) => (
        <div key={e.rank + e.name} style={{ fontWeight: e.me ? 800 : 400 }}>
          {e.rank}. {e.name} {e.score}
        </div>
      ))}
      {board && !board.ok && board.reason === "sign-in" && <div>登录后才能上榜</div>}
    </div>
  );
}
```

## 设计上的几个建议

- **在一局结束的地方显示**：分数、是不是新纪录、第几名。标题画面也可以放一个小榜。
- **高亮自己那一行**（`me`）。玩家不在前十名时，在底下单独写一行 `board.me`。
- **`details` 用来放分数旁边的小信息**：用了哪个角色、第几关、每秒几下。最多 500 字符的 JSON。
- **越少越好的榜**（用时、步数）第一次提交时传 `{ order: "asc" }`，这个榜从此按从小到大排。
- **没登录的玩家**会拿到 `{ ok: false, reason: "sign-in" }`，显示一句「登录后才能上榜」就好，别让游戏卡住。
- 一张卡可以有好几个榜，比如「最高分」和「最快通关」，最多 20 个。

## 规则

- 同一张卡的各个语言版本共用一套榜。
- 每人每分钟最多提交 30 次；榜名 1 到 40 个字符；分数的绝对值不超过 1e15。
- 只有已发布的卡能上榜；作者在自己没发布的卡上也能测试。
- 分数是卡在玩家浏览器里算的，所以不要拿名次发奖励或者兑换东西。
- Studio 预览里看到的是一个示例榜，方便看排版；真实的榜在玩的时候才有。

方法签名见 [API 参考](../08-api-reference.md)。

</div>
