---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/sdk-leaderboard.md
  - https://yandex.com/dev/games/doc/hi/sdk/sdk-leaderboard.md
  - https://yandex.com/dev/games/doc/ko/sdk/sdk-leaderboard.md
  - https://yandex.com/dev/games/doc/ru/sdk/sdk-leaderboard.md
  - https://yandex.com/dev/games/doc/tr/sdk/sdk-leaderboard.md
  - https://yandex.com/dev/games/doc/vi/sdk/sdk-leaderboard.md
  - https://yandex.com/dev/games/doc/zh/sdk/sdk-leaderboard.md
  - href: zh/sdk/sdk-leaderboard.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/games/doc/zh/llms.txt

# 排行榜

<!-- source: zh/_includes/script-common.md -->
<!-- source: zh/_includes/script/index-js.md -->

<!-- endsource: zh/_includes/script/index-js.md -->

<!-- source: zh/_includes/script/requirements-js.md -->

<!-- endsource: zh/_includes/script/requirements-js.md -->

<!-- source: zh/_includes/script/image-modal-js.md -->

<!-- endsource: zh/_includes/script/image-modal-js.md -->
<!-- endsource: zh/_includes/script-common.md -->

在游戏页面上，您可以显示个性化排行榜（排名表），展示最佳玩家的成绩以及已授权用户在排名中的位置。

要使排行榜请求正常工作，请满足以下条件：

- 在游戏代码中[连接并配置 SDK](https://yandex.com/dev/games/doc/zh/sdk/sdk-about.md#use)，使其对象可通过变量 `ysdk` 访问；
- 在开发人员控制台中[创建](https://yandex.com/dev/games/doc/zh/concepts/leaderboards.md)排行榜。

{% note alert %}

如果[开发人员控制台](https://games.yandex.com/console){.external}中没有**Technical leaderboard name**字段中相应名称的排行榜，请求将返回404错误。

{% endnote %}



## 初始化 {#init}

要调用排行榜方法，请直接访问 `ysdk.leaderboards`。

{% note alert %}

使用 `ysdk.getLeaderboards()` 方法初始化 `lb` 对象的方式已弃用。

{% cut "旧方法" %}

```javascript showLineNumbers
const ysdk = await YaGames.init();

const lb = await ysdk.getLeaderboards();

// 排行榜方法调用的新旧方式对应关系：
// lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription()
// lb.setLeaderboardScore() → ysdk.leaderboards.setScore()
// lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry()
// lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries()
```

{% endcut %}

{% endnote %}



## 排行榜描述 {#description}

要按名称获取排行榜描述，请使用 `ysdk.leaderboards.getDescription()` 方法。

**方法签名**

```typescript showLineNumbers
interface ILeaderboardDescription {
    [appID](*key_appID): string;
    [default](*key_default): boolean;
    description: {
        [invert_sort_order](*key_invert_sort_order): boolean;
        score_format: {
            options: {
                [decimal_offset](*key_decimal_offset): number;
            };
            [type](*key_type): 'numeric' | 'time';
        };
        [sort_order](*key_sort_order): string;
    };
    [name](*key_name): string;
    [title](*key_title): Record<Locale, string>;
}

function getDescription(
    [leaderboardName](*key_name): string
): Promise<ILeaderboardDescription> {}
```

接受排行榜技术名称 `leaderboardName` 作为唯一参数。返回包含排行榜描述的对象，包括以下字段：

<div class="table-25 table-2c25">

#|
|| **参数** | **类型** | **描述** ||
|| `appID` | `string` | 应用程序标识符。 ||
|| `default` | `boolean` | 如果为 `true`，则该排行榜为主排行榜。 ||
|| `invert_sort_order` | `boolean` | 排序方向：
- `false` —— 降序（得分最高的用户排在前面）。
- `true` —— 升序（得分最低的用户排在前面）。 ||
|| `sort_order` | `string` | 字符串格式的排序方向：
- `'DESC'` —— 降序。
- `'ASC'` —— 升序。 ||
|| `decimal_offset` | `number` | 分数的小数部分大小。例如，当 `decimal_offset: 2` 时，数字 1234 将显示为 12.34。 ||
|| `type` | `'numeric'` \| `'time'` | 排行榜结果类型。可用值：`numeric`（数字）、`time`（毫秒）。 ||
|| `name` | `string` | 在控制台的 **Technical leaderboard name** 字段中指定的排行榜名称。 ||
|| `title` | `Record<Locale, string>` | 本地化名称列表。可用的语言代码列在 [语言与域名](https://yandex.com/dev/games/doc/zh/concepts/languages-and-domains.md) 页面上。 ||
|#


</div>


#### 示例 {#description-example}

```javascript showLineNumbers
const ysdk = await YaGames.init();

const lb = await ysdk.leaderboards.getDescription('leaderboard2021');

console.log(lb);
```



## 新成绩 {#set-score}

{% note alert %}

该请求仅适用于已授权用户。如何检查授权状态并调用登录对话框，请参见[用户授权](https://yandex.com/dev/games/doc/zh/sdk/sdk-player.md#auth)部分。

在发送请求之前，使用 `ysdk.isAvailableMethod('leaderboards.setScore')` 检查方法的可用性。该方法返回 `Promise<Boolean>`。

为了确保所有用户的成绩都能保存，无论是否授权，建议在应用程序代码中自行实现自定义排行榜。技术选择不受限制。

{% endnote %}

要为玩家设置新成绩，请使用 `ysdk.leaderboards.setScore()` 方法。

**方法签名**

```typescript showLineNumbers
function setScore(
    [leaderboardName](*key_name): string,
    [score](*key_score): number,
    [extraData](*key_extraData)?: string
): Promise<void> {}
```

接受参数：

<div class="table-25 table-2c25">

#|
|| **参数** | **类型** | **描述** ||
|| `leaderboardName` | `string` | 在控制台的 **Technical leaderboard name** 字段中指定的排行榜名称。 ||
|| `score` | `number` | 结果值。不能为负数，最大值仅受 JavaScript 逻辑限制。如果[排行榜类型](*key_type)为 `time`，则该值必须以毫秒为单位传递。 ||
|| `extraData` | `string` | 用户描述。可选参数。 ||
|#

</div>

{% note info %}

请求发送频率不能超过每秒 1 次，否则将被拒绝并返回错误。

{% endnote %}


#### 示例 {#set-score-example}

```javascript showLineNumbers
const ysdk = await YaGames.init();

await ysdk.leaderboards.setScore('leaderboard2021', 120);

await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');
```



## 获取排名 {#get-entry}

{% note alert %}

该请求仅适用于已授权用户。如何检查授权状态并调用登录对话框，请参见[用户授权](https://yandex.com/dev/games/doc/zh/sdk/sdk-player.md#auth)部分。

在发送请求之前，使用 `ysdk.isAvailableMethod('leaderboards.getPlayerEntry')` 检查方法的可用性。该方法返回 `Promise<Boolean>`。

为了确保所有用户的成绩都能保存，无论是否授权，建议在应用程序代码中自行实现自定义排行榜。技术选择不受限制。

{% endnote %}

要获取用户排名，请使用 `ysdk.leaderboards.getPlayerEntry()` 方法。

**方法签名**

```typescript showLineNumbers
interface ILeaderboardEntry {
    [extraData](*key_extraData): string;
    [rank](*key_userRank): number;
    [score](*key_score): number;
    player: {
        [publicName](*key_publicName): string;
        [uniqueID](*key_uniqueID): string;
        [getAvatarSrc](*key_getAvatarSrc): (size?: 'small' | 'medium' | 'large') => string;
        [getAvatarSrcSet](*key_getAvatarSrcSet): (size?: 'small' | 'medium' | 'large') => string;
    }
}

function getPlayerEntry(
    [leaderboardName](*key_name): string
): Promise<ILeaderboardEntry> {}
```

接受排行榜技术名称 `leaderboardName` 作为唯一参数。返回包含用户排名的对象，包括以下字段：

<div class="table-25 table-2c25">

#|
|| **参数** | **类型** | **描述** ||
|| `score` | `number` | 结果值。 ||
|| `rank` | `number` | 用户在排行榜中的位置。 ||
|| `extraData` | `string` | 用户描述。 ||
|| `publicName` | `string` | 用户名。 ||
|| `uniqueID` | `string` | 用户的唯一标识符 ||
|| `getAvatarSrc` | `(size?: TSize) => string` | 返回指定大小的用户头像 URL。`size` 的可用值：`small`、`medium`、`large`。 ||
|| `getAvatarSrcSet` | `(size?: TSize) => string` | 返回适用于 Retina 显示屏的用户头像 srcset。`size` 的可用值：`small`、`medium`、`large`。 ||
|#

</div>

{% note info %}

请求发送频率不能超过 5 分钟内 60 次，否则将被拒绝并返回错误。

{% endnote %}


#### 示例 {#get-entry-example}

```javascript showLineNumbers
const ysdk = await YaGames.init();

try {
    const res = await ysdk.leaderboards.getPlayerEntry('leaderboard2021');

    console.log(res);
} catch (err) {
    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
        // 当玩家在排行榜中没有记录时触发。
    }
}
```



## 排行榜记录 {#get-entries}

要显示用户排名，请使用 `ysdk.leaderboards.getEntries()` 方法。

**方法签名**

```typescript showLineNumbers
interface ILeaderboardEntries {
    [leaderboard](*key_leaderboard): ILeaderboardDescription;
    [ranges](*key_ranges): {
        [start](*key_start): number;
        [size](*key_size): number;
    }[];
    [userRank](*key_userRank): number;
    [entries](*key_entries): ILeaderboardEntry[];
}

function getEntries(
    [leaderboardName](*key_name): string,
    options: {
        [includeUser](*key_includeUser)?: boolean;
        [quantityAround](*key_quantityAround)?: number;
        [quantityTop](*key_quantityTop)?: number;
    }
): Promise<ILeaderboardEntries> {}
```

接受排行榜技术名称 `leaderboardName` 和可选参数 `options`：

<div class="table-25 table-2c25">

#|
|| **选项** | **类型** | **描述** ||
|| `includeUser` | `boolean` | 确定是否在响应中包含已授权用户：
- `true` —— 包含在响应中。
- `false`（默认）—— 不包含。 ||
|| `quantityAround` | `number` | 需要返回的排行榜中用户上下的记录数量。最小值为 1，最大值为 10。默认返回 5。 ||
|| `quantityTop` | `number` | 排行榜顶部的记录数量。最小值为 1，最大值为 20。默认返回 5。 ||
|#

</div>

返回包含用户排名的对象 `Promise<ILeaderboardEntries>`，包括以下字段：

<div class="table-25 table-2c25">

#|
|| **参数** | **类型** | **描述** ||
|| `leaderboard` | `ILeaderboardDescription` | [排行榜描述](#description) ||
|| `ranges` | `object[]` | 响应中的位置区间。 ||
|| `start` | `number` | 排名中的位置。从零开始计数，因此第 1 名被视为第零个元素。 ||
|| `size` | `number` | 请求的记录数量。如果数据不足，可能与响应不符。 ||
|| `userRank` | `number` | 用户在排名中的位置。如果不存在，或者是不包含用户的顶部请求，则等于 0。 ||
|| `entries` | `ILeaderboardEntry[]` | 排名记录数组。记录与 [获取排名](#get-entry) 方法返回的值相同。 ||
|#

</div>

{% note info %}

请求发送频率不能超过 5 分钟内 20 次，否则将被拒绝并返回错误。

{% endnote %}


#### 示例 {#get-entries-example}

```javascript showLineNumbers
const ysdk = await YaGames.init();

// 获取前 10 名玩家和用户附近的 3 条记录。
const entries = await ysdk.leaderboards.getEntries('leaderboard2021', {
    quantityTop: 10,
    includeUser: true,
    quantityAround: 3
});

console.log(entries);
```



## 方法限制 {#limits}

<div class="table-25">

#|
|| **方法** | **描述** | **限制** | **用户授权** ||
|| `ysdk.leaderboards.setScore()` | [设置玩家的新结果](#set-score) | 每秒 1 次请求 | 必需 ||
|| `ysdk.leaderboards.getPlayerEntry()` | [显示单个用户的排名](#get-entry) | 每 5 分钟 60 次请求 | 必需 ||
|| `ysdk.leaderboards.getEntries()` | [获取多个用户的排名](#get-entries) | 每 5 分钟 20 次请求 | 可选 ||
|#

</div>

其他请求的限制：5 分钟内 20 次请求。



## 问题解决 {#faq}

{% note tip %}

使用 `ysdk.isAvailableMethod()` 和 `ysdk.leaderboards.setScore()` 方法组合时，未授权用户不会出现在排行榜中，也看不到自己的进度。为了确保所有玩家的成绩都能保存，建议在应用程序代码中创建自定义排行榜。技术选择不受限制。

{% endnote %}

### Object already exists {#object-already-exists}

尝试使用旧名称创建新排行榜时会出现此错误。请输入以前未使用过的名称。

### 用户已隐藏 {#player-hidden}

如果玩家不允许使用其头像和名称，则会显示"用户已隐藏"。对用户数据的访问取决于其[个人资料](https://yandex.com/games/user){.external}中的设置。详见[初始化](https://yandex.com/dev/games/doc/zh/sdk/sdk-player.md#getplayer)部分。

### 错误 404 {#leaderboard-404}

如果调用排行榜 SDK 方法时出现 404 错误，请检查[开发人员控制台](https://games.yandex.com/console){.external}中是否创建了 **Technical leaderboard name** 字段中具有相应名称的排行榜。


---

<!-- source: zh/_includes/sdk-support.md -->
{% note info %}

技术支持团队将协助您将已完成的游戏发布到 Yandex 游戏平台。关于开发和测试方面的具体问题，其他开发人员将在[Discord 频道](https://discord.com/invite/wU4p3whr4T){.external}中进行回答。

{% endnote %}

如果您遇到 Yandex Games SDK 方面的问题或有其他问题想要咨询，请联系支持部门：

<!-- source: zh/_includes/button-chat.md -->
<a href="https://yandex.com/chat/#/user/a4fa5c06-75db-9b38-6eea-b1673785f7d5">
  <span class="button">写入聊天信息</span>
</a>
<!-- endsource: zh/_includes/button-chat.md -->
<!-- endsource: zh/_includes/sdk-support.md -->

[*key_name]: 在控制台的**Technical leaderboard name**字段中指定的排行榜名称。

[*key_appID]: 应用程序标识符。

[*key_default]: 如果为`true`，则该排行榜为主排行榜。

[*key_invert_sort_order]: 排序方向：
- `false` —— 降序（得分最高的用户排在前面）。
- `true` —— 升序（得分最低的用户排在前面）。

[*key_sort_order]: 字符串格式的排序方向：
- `'DESC'` —— 降序（得分最高的用户排在前面）。
- `'ASC'` – 升序（得分最低的用户排在前面）。

[*key_decimal_offset]: 分数的小数部分大小。例如，当`decimal_offset: 2`时，数字1234将显示为12.34。

[*key_type]: 排行榜结果类型。可用值：`numeric`（数字）、`time`（毫秒）。

[*key_title]: 本地化名称列表。可能的语言代码列在[{#T}](../concepts/languages-and-domains.md)页面上。

[*key_score]: 结果值。不能为负数，最大值仅受JavaScript逻辑限制。

[*key_extraData]: 用户描述。

[*key_userRank]: 用户在排行榜中的位置。

[*key_publicName]: 用户名。

[*key_uniqueID]: 用户唯一标识符。

[*key_getAvatarSrc]: 返回用户头像的URL。可能的`size`值：`small`、`medium`、`large`。

[*key_getAvatarSrcSet]: 返回适用于Retina显示屏的用户头像srcset。可能的`size`值：`small`、`medium`、`large`。

[*key_includeUser]: 确定是否在响应中包含已授权用户：
- `true` - 包含在响应中。
- `false`（默认）- 不包含。

[*key_quantityAround]: 需要返回的排行榜中用户上下的记录数量。最小值为1，最大值为10。默认返回5条。

[*key_quantityTop]: 排行榜顶部的记录数量。最小值为1，最大值为20。默认返回5条。

[*key_leaderboard]: [{#T}](#description)。

[*key_ranges]: 响应中的位置区间。

[*key_start]: 排名中的位置。从零开始计数，因此第1名被视为第零个元素。

[*key_size]: 请求的记录数量。如果数据不足，可能与响应不符。

[*key_entries]: 排名记录数组。记录与[{#T}](#get-entry)方法返回的值相同。