---
metadata:
  - name: generator
    content: Diplodoc Platform v5.66.0
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/hi/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/ko/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/ru/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/tr/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/vi/sdk/construct-3/leaderboards.md
  - https://yandex.com/dev/games/doc/zh/sdk/construct-3/leaderboards.md
  - href: https://yandex.com/dev/games/doc/zh/sdk/construct-3/leaderboards.md
    type: text/markdown
    title: Markdown version
  - href: https://yandex.com/dev/games/doc/zh/llms.txt?revision=r21993288
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/games/doc/zh/llms.txt?revision=r21993288

# 排行榜

<!-- 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 -->

<!-- source: zh/_includes/sdk/common-with-plugins.md -->
在游戏页面上，您可以展示个性化排行榜（玩家排名表），显示最佳玩家的成绩以及已授权用户在排名中的位置。
<!-- endsource: zh/_includes/sdk/common-with-plugins.md -->

要让下述请求正常工作，请检查是否已在开发人员控制台中[创建](https://yandex.com/dev/games/doc/zh/concepts/leaderboards.md#create)排行榜。

<!-- source: zh/_includes/sdk/common-with-plugins.md -->
{% note alert %}

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

{% endnote %}
<!-- endsource: zh/_includes/sdk/common-with-plugins.md -->

## 提交分数 {#set-score}

{% note alert %}

该请求仅对已授权用户可用。建议提前请求授权，并且仅在用户提供个人数据时才使用排行榜。

![Construct 3 截图：使用 YandexGamesSDK 插件配置排行榜的界面。 一个三列表格（第三列的每个单元格中都有"+ 添加操作"和"+ 添加..."按钮），共三行。 第 1 行 —— "系统"设置图标、"仅执行一次"、"Yan... | 请求玩家信息。 个人数据：False"。 第 2 行 —— "YandexGames…"、"玩家信息已加载"、空单元格。 第 3 行 —— "YandexGames…"、"玩家已授权"、"系..."设置图标 | 将 authorized 设置为 True"。](../../_images/construct-3/leaderboards/player-pre-auth.webp)

{% endnote %}

使用 **Set leaderboard score** 操作向排行榜提交新分数，参数如下：

#|
|| **参数** | **类型** | **描述** ||
|| **Name** | `string` | 排行榜的技术名称。 ||
|| **Score** | `number` | 玩家在排行榜中的分数。 ||
|| **Additional data** | `string` | 随分数一起发送的可选元数据。 ||
|#

例如，向排行榜提交分数可以如下所示：

![Construct 3 截图：使用 YandexGamesSDK 插件配置排行榜的界面。 一个三列表格（第三列的每个单元格中都有"+ 添加操作"和"+ 添加..."按钮），共两行。 第 1 行 —— "按钮"、"点击时"、空单元格。 第 2 行 —— "系统"设置图标、"authorized 为真"、"Yan... | 将分数 10 发送到排行榜 "score"，数据为 """。](../../_images/construct-3/leaderboards/set-score.webp)

{% note info %}

<!-- source: zh/_includes/sdk/common-with-plugins.md -->
请求的发送频率不能超过每 1 秒 1 次，否则将被拒绝并返回错误。
<!-- endsource: zh/_includes/sdk/common-with-plugins.md -->

建议将提交分数与[延迟事件](https://yandex.com/dev/games/doc/zh/sdk/construct-3/throttle-debounce.md)一起使用。

![Construct 3 截图：使用 YandexGamesSDK 插件配置排行榜的界面。 一个三列表格（第三列的每个单元格中都有"+ 添加操作"和"+ 添加..."按钮），共三行。 第 1 行 —— "按钮"、"点击时"、"Yan... | 将 setScore 事件延迟 1 秒"。 第 2 行 —— "YandexGames…"、"延迟事件 "setScore" 时"、空单元格。 第 3 行 —— "系统"设置图标、"authorized 为真"、"Yan... | 将分数 10 发送到排行榜 "score"，数据为 """。](../../_images/construct-3/leaderboards/debounce.webp)

{% endnote %}

## 排行榜条目 {#get-leaderboard}

要开始使用排行榜，请将 **Fetch leaderboard** 操作与触发条件 **Leaderboard is successfully fetched** 和 **Failure to fetch leaderboard** 结合使用。 操作和条件接受以下参数：

#|
|| **参数** | **类型** | **描述** ||
|| **Name** | `string` | 排行榜的技术名称。 ||
|| **Top positions** | `number` | 从排行榜顶部请求的条目数量。 ||
|| **Request player position** | `boolean` | 决定是否请求用户的位置。 ||
|| **Positions around the player's position** | `number` | 在表格中用户下方和上方请求的条目数量。 ||
|#

插件将通过 Yandex Games SDK 请求排行榜数据，请求成功后将开始循环。 此过程需要一些时间。

建议在过程进行期间在屏幕上保留加载指示器。

{% note warning %}

请确保此循环不会被持续调用。 建议在函数或触发器中使用它。

{% endnote %}

![Construct 3 截图：使用 YandexGamesSDK 插件配置排行榜的界面。 一个三列表格（第三列的每个单元格中都有"+ 添加操作"和"+ 添加..."按钮），共 4 行。 第 1 行 —— "系统"设置图标、"仅执行一次"、"Yan... | 请求排行榜 "score"。 前 5 名：5，用户：True，周围：5。 第 2 行 —— "YandexGames…"、"排行榜 "score" 已加载。 前 5 名：5，用户：True，周围：5。"、空单元格。 第 3 行 —— "YandexGames…"、"对于当前排行榜中的每个玩家"、"系..."设置图标 | 将 currentUsernameInLeaderboard 设置为 YandexGamesSDK.当前玩家在排行榜中的名字"。 第 4 行 —— "YandexGames…"、"排行榜 "score" 加载出错。 前 5 名：5，用户：True，周围：5。"、空单元格。](../../_images/construct-3/leaderboards/request-leaderboard.webp)

在循环内部，您可以访问 **Leaderboards** 列表中的表达式。

![Construct 3 截图：屏幕左上方显示"排行榜"字样。 下方是一个两列 14 行的表格。 第 1 行：当前玩家在排行榜中的头像 | 字符串，玩家头像的链接。 如果没有头像访问权限，可能等于""。 第 2 行：当前玩家在排行榜中的大头像 | 字符串，玩家大头像的链接。 第 3 行：当前玩家在排行榜中的附加数据 | 随分数一起发送的可选元数据。 第 4 行：当前玩家在排行榜中的名字 | 字符串，玩家名字。 如果没有名字访问权限，可能等于""。 第 5 行：排行榜中请求区间的索引 | 从排行榜请求位置时，可能会形成多个值区间。 第 6 行：当前玩家在排行榜中的小头像 | 字符串，玩家小头像的链接。 第 7 行：排行榜名称 | 排行榜的本地化名称。 第 8 行：当前玩家在排行榜中的位置 | 通过比较所有玩家的分数获得的位置。 第 9 行：排行榜小数点偏移量 | 分数小数部分的大小。 例如，当 decimal_offset: 2 时，数字 1234 将显示为 12.34。 第 10 行：当前玩家在排行榜中的中等头像 | 字符串，玩家中等头像的链接。 第 11 行：当前玩家在排行榜中的分数 | 玩家在游戏过程中获得的分数。 第 12 行：排行榜技术名称 | 字符串，排行榜的技术名称（不用于向用户显示）。 第 13 行：排行榜类型 | 玩家在排行榜中的分数类型。 可能的值：numeric（数字）、time（秒）。 第 14 行：当前玩家在排行榜中的唯一标识符 | 字符串，玩家的唯一标识符。](../../_images/construct-3/leaderboards/expressions.webp)

---


<!-- source: zh/_includes/sdk/button-git.md -->
<a href="https://github.com/yandex-games-plugins/construct3">
  <span class="button">存储库</span>
</a>
<!-- endsource: zh/_includes/sdk/button-git.md -->