---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.4
alternate:
  - https://yandex.com/dev/games/doc/en/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/hi/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/ko/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/ru/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/tr/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/vi/sdk/defold/leaderboard.md
  - https://yandex.com/dev/games/doc/zh/sdk/defold/leaderboard.md
  - href: zh/sdk/defold/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 %}

如果开发者仪表板中的**技术排行榜名称**字段中没有该名称的排行榜，请求将返回 404 错误。

{% endnote %}

## 排行榜描述 {#leaderboard-description}

要通过名称获取排行榜的描述，请使用 `ysdk.leaderboards.get_description()`:

```lua showLineNumbers
ysdk.leaderboards.get_description(
    leaderboard_name: string,
    callback: function
)
```

`callback: function` —— 被调用方法的处理程序。格式如下：

```lua
function(self, description: table|nil): nil
```

- `description: table` —— 排行榜的描述。包含以下属性：

```lua showLineNumbers
description: {
  app_id: string,
  default: boolean,
  invert_sort_order: boolean,
  decimal_offset: integer,
  type: string,
  name: string,
  title: {
    en: string,
    ru: string
  }
}
```

**示例**

```lua showLineNumbers
function display_leaderboard()
  ysdk.leaderboards.get_description("highscores",
    function (self, description)
      if description then
        print(
          description.name,
          description.title.en
        )
    end
  end)
end
```

## 最新得分 {#new-score}

{% note alert %}

请求仅适用于已授权用户。如有需要，请使用[授权](https://yandex.com/dev/games/doc/zh/sdk/sdk-player.md#auth)。

{% endnote %}

要为玩家设置最新得分，请使用 `ysdk.leaderboards.set_score()`:

```lua showLineNumbers
ysdk.leaderboards.set_score(
    leaderboard_name: string,
    score: integer,
    extraData: string|nil
)
```

{% note info %}

请求的发送频率不能超过每秒一次。否则，请求会被拒绝并引发错误。

{% endnote %}

## 获取排名 {#getting-ranking}

{% note alert %}

请求仅供授权用户使用。必要时，请使用[授权](https://yandex.com/dev/games/doc/zh/sdk/sdk-player.md#auth)。

{% endnote %}

要获取用户排名，请使用 `ysdk.leaderboards.get_player_entry()`:

```lua showLineNumbers
ysdk.leaderboards.get_player_entry(
    leaderboard_name: string,
    callback: function
)
```

`callback: function` —— 被调用方法的处理程序。格式如下：

```lua
function(self, player_entry: table|nil): nil
```

- `player_entry: table` —— 用户排名。包含以下属性：

```lua showLineNumbers
player_entry: {
  score: integer,
  extraData: string,
  rank: integer,
  avatar_src: {
    small: string,
    medium: string,
    large: string,
  },
  avatar_srcset: {
    small: string,
    medium: string,
    large: string,
  },
  lang: string,
  public_name: string,
  unique_id: string,
  formatted_score: string
}
```

**示例**

```lua showLineNumbers
function display_high_score()
  ysdk.leaderboards.get_player_entry("highscores",
    function (self, player_entry)
      if player_entry then
        print("highscore: " .. player_entry.score)
      end
    end)
end
```

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

要显示用户排名，请使用 `ysdk.leaderboards.get_entries()`:

```lua showLineNumbers
ysdk.leaderboards.get_entries(
    leaderboardName: string,
    callback: function,
    options: {
        include_user: boolean|nil,
        quantity_around: number|nil,
        quantity_top: number|nil
    }
)
```

`callback: function`— 被调用方法的处理程序。格式如下：

```lua
function(self, entries: table|nil): nil
```

`entries: table` —— 用户排行榜。包含以下属性：

```lua showLineNumbers
entries: {
  leaderboard: {
    ...
  },
  ranges: [
    {
      start: integer,
      size: integer
    }
  ],
  userRank: integer,
  entries: [
    {
      score: integer,
      extraData: string,
      rank: integer,
      avatar_src: {
        small: string,
        medium: string,
        large: string,
      },
      avatar_srcset: {
        small: string,
        medium: string,
        large: string,
      },
      lang: string,
      public_name: string,
      unique_id: string,
      formatted_score: string
    },
    ...
  ]
}
```

---


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