---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.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: zh/sdk/construct-3/leaderboards.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 -->

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

为了使下面描述的请求正常工作，请确保您已在开发人员控制台中创建了[排行榜](https://yandex.com/dev/games/doc/zh/sdk/sdk-leaderboard.md)。



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

{% note info %}

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

![](../../_images/construct-3/leaderboards/player-pre-auth.webp)

{% endnote %}

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

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

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

![](../../_images/construct-3/leaderboards/set-score.webp)

{% note info %}

请求最多每秒发送一次，否则将被拒绝并返回错误。

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

![](../../_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 %}

![](../../_images/construct-3/leaderboards/request-leaderboard.webp)

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

![](../../_images/construct-3/leaderboards/expressions.webp)


---


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