---
title: 排行榜
slug: world-sdk-guide-ch/Qyjo8bnyL4jRTlwpGHt3L
docTags:
createdAt: 2024-09-02T08:34:13.135Z
---
## 设置排行榜
排行榜是一个模块，提供保存和管理每个玩家排名和高分的功能。
### 步骤 1 : 创建排行榜
要创建排行榜，请在 ProjectSettings → Zepeto → ZepetoLeaderboard 菜单中选择 \[获取排行榜信息] 按钮。
选择 \[添加排行榜] 以添加新的排行榜。
如果已经存在排行榜，排行榜将出现在设置屏幕上。
### 步骤 2 : 自定义排行榜
当选择 \[添加排行榜] 按钮时，将出现如下弹出窗口。您将能够调整每个参数的值。
| **参数** | **描述** |
| ------- | --------------------------------------------------------------------------------------------- |
| 名称 | 排行榜名称 |
| 更新规则 | 得分更新规则 |
| 最高分 | 记录用户的最高分 |
| 最低分 | 记录用户的最低分 |
| 累计得分 | 添加用户的得分并保存为记录 |
| 重置信息(s) | 您可以设置一个周期来重置得分。
- 如果排行榜需要每个赛季更新，这将很有帮助。
- 默认情况下，得分不会被重置，但您可以通过设置重置周期（每月、每周、每天）进行调整。 |
### 步骤 3 : 设置分数重置
分数重置规则如下：
| **周期** | **描述** |
| ------ | --------------------------------------------------------- |
| 无 | 分数不会重置 |
| 天 | 分数将在设定时间每天重置（例如：每日排名） |
| 周 | 分数将在设定日期和时间每周重置（例如：每周排名） |
| 月 | 分数将在设定日期和时间每月重置（例如：每月排名；最大天数为31，但如果该月没有31天，将自动调整为该月的最后一天） |
### 步骤 4 : 排行榜 ID
要使用 ZEPETOScript 和排行榜，您必须拥有排行榜 ID 信息。
要访问排行榜信息，您可以前往设置（在项目设置菜单的编辑下，转到 Zepeto → Zepeto 排行榜 → 编辑），或从 ZEPETOScript api 加载。
:::hint{type="danger"}
- 一旦重置规则设置完成，排行榜将无法修改。
- 要更改重置规则，您必须创建一个新的排行榜。
- 重置时间基于 UTC+0。将提供偏移量，以便将来可以更改时区。
:::
## 记录分数
LeaderboardAPI.SetScore() 是一个记录用户在排行榜上得分的 API。
排行榜 ID、得分值、完成点和错误点作为参数传递。
得分的用户信息将自动保存。
以下是加载 LeaderboardAPI.SetScore 函数的示例。
```typescript
LeaderboardAPI.SetScore(this.leaderBoardId, this.score, this.OnResult, this.OnError);
```
以下是检索用户得分到排行榜的代码模板。
```typescript
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { SetScoreResponse, LeaderboardAPI } from 'ZEPETO.Script.Leaderboard';
export default class SetScoreExample extends ZepetoScriptBehaviour {
public leaderboardId: string;
public score: number;
Start() {
LeaderboardAPI.SetScore(this.leaderboardId, this.score, this.OnResult, this.OnError);
}
OnResult(result: SetScoreResponse) {
console.log(`result.isSuccess: ${result.isSuccess}`);
}
OnError(error: string) {
console.error(error);
}
}
```
## 搜索排名详情
### 在特定范围内获取排名信息
使用 LeaderboardAPI.GetRangeRank() 函数加载特定范围的排名详细信息。
布尔值用于检索排行榜 ID、起始排名、最后排名、重置规则和上赛季的排名信息，完成时间和错误发生时间的回调函数作为参数传递。
查询排名信息的用户信息会自动输入，每次查询最多可以处理 100 条排名信息（例如：以 1 的格式进行分页~~100, 101~~200 格式进行实现）
:::hint{type="danger"}
**❗️ 注意**
如果一次加载超过 100 条数据，可能由于 API 负载问题和速率限制而无法正常工作。
:::
### 示例函数调用
调用 LeaderboardAPI.GetRangeRank() 函数的示例如下：
```typescript
LeaderboardAPI.GetRangeRank(this.leaderboardId, this.startRank, this.endRank, this.resetRule, false, this.OnResult, this.OnError);
```
以下代码是加载特定范围排名信息的示例。
您可以使用 OnResult 中的 Member 值加载个人资料照片。
:::hint{type="info"}
**📘 **请参考以下指南。\[[用户信息](docId\:lLhNCmcCXkTu-LkEB14QB)]
:::
```typescript
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { GetRangeRankResponse, LeaderboardAPI, ResetRule } from 'ZEPETO.Script.Leaderboard';
export default class GetRangeRankExample extends ZepetoScriptBehaviour {
public leaderboardId: string;
public startRank: number;
public endRank: number;
public resetRule: ResetRule;
Start() {
LeaderboardAPI.GetRangeRank(this.leaderboardId, this.startRank, this.endRank, this.resetRule, false,
this.OnResult, this.OnError);
}
OnResult(result: GetRangeRankResponse) {
console.log(`result.isSuccess: ${result.isSuccess}`);
if (result.rankInfo.myRank) {
console.log(`member: ${result.rankInfo.myRank.member}, rank: ${result.rankInfo.myRank.rank},
score: ${result.rankInfo.myRank.score}, name: ${result.rankInfo.myRank.name}`);
}
if (result.rankInfo.rankList) {
for (let i = 0; i < result.rankInfo.rankList.length; ++i) {
const rank = result.rankInfo.rankList.get_Item(i);
console.log(`i: ${i}, member: ${rank.member}, rank: ${rank.rank}, score: ${rank.score}, name: ${rank.name}`);
}
}
}
OnError(error: string) {
console.error(error);
}
}
```
## 搜索排行榜详情
### 搜索所有排行榜
使用 LeaderboardAPI.GetAllLeaderboards 函数加载指定世界中的所有排行榜信息。
从完成时到发生错误时的回调函数作为参数传递。
加载 LeaderboardAPI.GetAllLeaderboards 函数的示例如下：
```typescript
LeaderboardAPI.GetAllLeaderboards(this.OnResult, this.OnError);
```
以下是加载整个排行榜信息的示例。
```typescript
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { GetAllLeaderboardsResponse, LeaderboardAPI } from 'ZEPETO.Script.Leaderboard';
export default class GetAllLeaderboardExample extends ZepetoScriptBehaviour {
Start() {
LeaderboardAPI.GetAllLeaderboards(this.OnResult, this.OnError);
}
OnResult(result: GetAllLeaderboardsResponse) {
console.log(`result.isSuccess: ${result.isSuccess}`);
if (result.leaderboards) {
for (let i = 0; i < result.leaderboards.length; ++i) {
const leaderboard = result.leaderboards[i];
console.log(`i: ${i}, id: ${leaderboard.id}, name: ${leaderboard.name}`);
}
}
}
OnError(error: string) {
console.error(error);
}
}
```
### 搜索特定排行榜
使用LeaderboardAPI.GetLeaderboards函数加载特定排行榜信息。
排行榜ID、完成时间和错误发生时间的回调函数作为参数传递。
加载LeaderboardAPI.GetLeaderboard函数的示例如下：
```typescript
LeaderboardAPI.GetLeaderboard(this.leaderboardId, this.OnResult, this.OnError);
```
以下是加载某些排行榜信息的示例。
```typescript
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { GetLeaderboardResponse, LeaderboardAPI } from 'ZEPETO.Script.Leaderboard';
export default class GetLeaderboardExample extends ZepetoScriptBehaviour {
public leaderboardId: string;
Start() {
LeaderboardAPI.GetLeaderboard(this.leaderboardId, this.OnResult, this.OnError);
}
OnResult(result: GetLeaderboardResponse) {
console.log(`result.isSuccess: ${result.isSuccess}`);
if (result.leaderboard) {
console.log(`id: ${result.leaderboard.id}, name: ${result.leaderboard.name}`);
}
}
OnError(error: string) {
console.error(error);
}
}
```
## 排行榜使用示例
- 以下是应用于官方ZEPETO世界史莱姆派对的排行榜示例。
- 通过设置、读取和利用API调用来获取特定范围内的排名，您可以在UI中将其结构化如下。
