跳到主要内容

排行榜开发指南 · JavaScript

Demo​

您可以通过查看 Demo 感受排行榜功能。

安装 SDK​

排行榜是存储 SDK 中的一个模块，要在 JavaScript 运行环境中使用排行榜功能，需要安装存储 SDK，请参考 JavaScript SDK 安装指南。

SDK 中的类​

SDK 提供了对排行榜、成绩与用户的抽象。在开始之前，请确认您已阅读 排行榜功能介绍，本文中将不再具体解释相关的概念。

AV.Leaderboard​

AV.Leaderboard 类是对排行榜的抽象。Leaderboard 实例有以下属性：

属性类型说明
statisticNamestring所排名的成绩名字
orderAV.LeaderboardOrder排序
updateStrategyAV.LeaderboardUpdateStrategy成绩更新策略
versionChangeIntervalAV.LeaderboardVersionChangeInterval自动重置周期
versionnumber版本
nextResetAtDate计划下次重置时间
createdAtDate创建时间

Statistic​

排行榜是对用户的成绩进行排名的结果。SDK 提供了一个 Statistic 类来表示成绩。Statistic 实例有以下属性：

属性类型说明
namestring成绩名字，对应排行榜的 statisticName
valuenumber成绩值

Ranking​

排行榜排序的结果是一个数组，数组的成员是一个叫 Ranking 的结构：

属性类型说明
ranknumber排名，从 0 开始
userAV.User拥有该成绩的用户
valuenumber该用户的成绩
includedStatisticsStatistic[]该用户的其他成绩

AV.User​

排行榜中的用户指的是 LeanCloud 数据存储服务用户系统中的用户。在客户端，只有登录后才能更新当前登录用户的成绩。您可以通过 内建账户指南了解更多用户系统的功能与用法。

用户成绩管理​

更新成绩​

当用户完成了一局游戏后，你可以使用 SDK 的 updateStatistic 方法更新该用户的成绩。

AV.Leaderboard.updateStatistics(AV.User.current(), {
  score: 3458,
  kills: 28,
}).then(function(statistics) {
  // statistics 是更新后你的最好/最新成绩
}).catch(console.error);

updateStatistic 方法的第二个参数是一个 key-value 的对象，key 为要更新的 statisticName，value 为要更新的成绩。你可以一次更新多个不同的成绩。

警告

更新成绩 API 需要用户登录，且用户只能更新自己的成绩。也可使用 masterKey 更新任意用户的成绩。

强制更新成绩​

有些情况下，你会想要绕过排行榜的 更新策略 强制更新用户的成绩，你可以使用 overwrite 参数实现这一需求：

AV.Leaderboard.updateStatistics(AV.User.current(), { score: 0 }, {
  overwrite: true,
}).then(function(statistics) {
  // score 会被强制更新为 0
}).catch(console.error);

查询成绩​

你可以通过 getStatistics 方法查询某用户的某些成绩：

// 当前玩家需要先登录
AV.User.logIn('playerA', 'passwordA').then((loggedInUser) => {
  // 查询另一个玩家在排行榜中的成绩
  var otherUser = AV.Object.createWithoutData(AV.User, '5cee072ac8959c0069f62ca8');
  return AV.Leaderboard.getStatistics(otherUser, {statisticNames: ['score', 'kills']});
}).then(function(statistics) {
  // statistics 是查询的成绩结果
}).catch(function (error) {
    // 异常处理
});

你也可以省略 statisticNames 选项用来查询某用户的所有成绩：

// 当前玩家需要先登录
AV.User.logIn('playerA', 'passwordA').then((loggedInUser) => {
  // 查询另一个玩家在排行榜中的成绩
  var otherUser = AV.Object.createWithoutData(AV.User, '5cee072ac8959c0069f62ca8');
  return AV.Leaderboard.getStatistics(otherUser)
}).then(function(statistics) {
  // statistics 是查询的成绩结果
}).catch(function (error) {
    // 异常处理
});

获取排行榜结果​

SDK 提供了两种获取排行榜结果的 API：

方法作用
Leaderboard#getResults获取指定区间的排名
Leaderboard#getResultsAroundUser获取指定用户附近的排名

获取指定区间的排名​

获取排行榜结果最常见的使用场景是获取排名前 N 的用户成绩。

var leaderboard = AV.Leaderboard.createWithoutData('score');
leaderboard.getResults({
  limit: 10,
  skip: 0,
}).then(function(rankings) {
  // rankings 为前 10 的排名结果
}).catch(console.error);

Leaderboard#getResults 方法的第一个参数包含以下选项：

选项名类型说明
limitnumber限制返回的结果数量
skipnumber指定从某个位置开始获取，与 limit 一起可以实现翻页
selectUserKeysstring[]指定返回的 Ranking 中的 user 需要包含的属性
includeStatisticsstring[]指定返回的 Ranking 中需要包含的其他成绩
versionnumber指定返回某个历史版本的成绩

默认情况下返回的排行榜结果中的 user 是一个只有 id 属性的 AV.User Pointer。如果想要想下面这个例子一样，在排行榜结果中显示用户名或者其他的用户属性（对应 _User 表中的属性），那么需要使用 selectUserKeys 选项。

排名UsernameAgeScore↓
0Genji353458
1Lúcio263252
2D.Va193140
var leaderboard = AV.Leaderboard.createWithoutData('score');
leaderboard.getResults({
  limit: 10,
  selectUserKeys: ['username', 'age'],
}).then(function(rankings) {
  // ranking 的 user 将包含 username 与 age 属性
}).catch(console.error);

类似的，如果想要在排行榜结果中包含用户的其他成绩，可以使用 includeStatistics 选项。

排名UsernameScore↓Kills
0Genji345828
1Lúcio32522
2D.Va314031
var leaderboard = AV.Leaderboard.createWithoutData('score');
leaderboard.getResults({
  limit: 10,
  includeStatistics: ['kills'],
}).then(function(rankings) {
  // 可以在 ranking 的 includedStatistics 属性中得到该用户的 kills 成绩
}).catch(console.error);

获取当前用户附近的排名​

另一种常见的需求是获取当前登录用户附近的排名：

排名UsernameScore↓
…
24Bastion716
25 (You)Widowmaker698
26Hanzo23
…
var leaderboard = AV.Leaderboard.createWithoutData('score');
leaderboard.getResultsAroundUser({
  limit: 3,
}).then(function(rankings) {
  // rankings 为当前用户附近的 3 条排名结果
}).catch(console.error);

Leaderboard#getResultsAroundUser 方法的第一个参数包含以下选项：

选项名类型说明
limitnumber限制返回的结果数量，当前用户会在结果的中间位置
selectUserKeysstring[]指定返回的 Ranking 中的 user 需要包含的属性
includeStatisticsstring[]指定返回的 Ranking 中需要包含的其他成绩
versionnumber指定返回某个历史版本的成绩

各参数的适用场景与用法与上文 Leaderboard#getResults 的参数类似，不再详述。

获取当前用户的排名​

如果仅需要获取当前用户的排名，使用 获取当前用户附近的排名 中的 Leaderboard#getResultsAroundUser 方法并指定 limit 为 1 时即可。

管理排行榜​

您可以在控制台的「游戏 - 排行榜 - 数据」页面完成排行榜的创建、重置、修改以及删除等操作。除此之外您也可以通过调用 SDK 的 API 来管理排行榜。

请注意，管理排行榜 API 需要 masterKey，因此只能在服务端等可信任的环境中调用。

创建排行榜​

AV.Leaderboard.createLeaderboard({
  statisticName: 'score',
  order: AV.LeaderboardOrder.DESCENDING,
}, { useMasterKey: true }).then(function(leaderboard) {
  // 创建成功得到 leaderboard 实例
}).catch(console.error);

你可以指定以下参数：

参数类型是否可选默认值说明
statisticNamestring所排名的成绩名字
orderAV.LeaderboardOrder排序
updateStrategyAV.LeaderboardUpdateStrategy可选AV.LeaderboardUpdateStrategy.BETTER成绩更新策略
versionChangeIntervalAV.LeaderboardVersionChangeInterval可选AV.LeaderboardVersionChangeInterval.WEEK自动重置周期

详见 创建排行榜 API 文档。

警告

创建排行榜接口需要使用 masterKey。

手动重置排行榜​

排行榜在创建之后会按照自动重置周期的设置自动定期重置，重置后该排行榜中所有用户的成绩都会被清空，你可以在控制台的历史版本中找到历史版本的归档。你也可以随时调用重置排行榜的接口手动进行重置。

var leaderboard = AV.Leaderboard.createWithoutData('score');
leaderboard.reset({ useMasterKey: true })
  .then(function(leaderboard) {
    // 重置成功
  }).catch(console.error);
警告

重置排行榜接口需要使用 masterKey。

获取排行榜属性​

通过这个接口可以获得当前排行榜的属性，例如：重置周期、版本号、更新策略等。

AV.Leaderboard.getLeaderboard('world').then((data) => {
  console.log(data);
}).catch(console.error)

修改排行榜属性​

排行榜创建后，名字与成绩排序方式不可修改。

自动重置周期可以通过调用以下 API 修改：

var leaderboard = AV.Leaderboard.createWithoutData('score');
leaderboard.updateVersionChangeInterval(
  AV.LeaderboardVersionChangeInterval.MONTH,
  { useMasterKey: true }
).then(function(leaderboard) {
  // 修改成功
}).catch(console.error);

成绩更新策略可以通过调用以下 API 修改：

var leaderboard = AV.Leaderboard.createWithoutData('score');
leaderboard.updateUpdateStrategy(
  AV.LeaderboardUpdateStrategy.LAST,
  { useMasterKey: true }
).then(function(leaderboard) {
  // 修改成功
}).catch(console.error);
警告

修改排行榜属性接口需要使用 masterKey。

删除排行榜​

var leaderboard = AV.Leaderboard.createWithoutData('score');
leaderboard.destroy({ useMasterKey: true })
  .then(function() {
    // 删除成功
  }).catch(console.error);
警告
  • 删除排行榜会删除该排行榜的所有数据，包括当前数据及所有历史版本归档。
  • 删除排行榜接口需要使用 masterKey。