您可以通过查看 Demo 感受排行榜功能。
排行榜是存储 SDK 中的一个模块,要在 JavaScript 运行环境中使用排行榜功能,需要安装存储 SDK,请参考《 JavaScript SDK 安装指南》。
SDK 提供了对排行榜、成绩与用户的抽象。在开始之前,请确认您已阅读《排行榜总览》,本文中将不再具体解释相关的概念。
AV.Leaderboard 类是对排行榜的抽象。Leaderboard 实例有以下属性:
AV.Leaderboard
Leaderboard
statisticName
string
order
AV.LeaderboardOrder
updateStrategy
AV.LeaderboardUpdateStrategy
versionChangeInterval
AV.LeaderboardVersionChangeInterval
version
number
nextResetAt
Date
createdAt
排行榜是对用户的成绩进行排名的结果。SDK 提供了一个 Statistic 类来表示成绩。Statistic 实例有以下属性:
Statistic
name
value
排行榜排序的结果是一个数组,数组的成员是一个叫 Ranking 的结构:
Ranking
rank
user
AV.User
includedStatistics
Statistic[]
排行榜中的用户指的是 LeanCloud 数据存储服务用户系统中的用户。在客户端,只有登录后才能更新当前登录用户的成绩。您可以通过《数据存储开发指南 - 用户》了解更多用户系统的功能与用法。
当用户完成了一局游戏后,你可以使用 SDK 的 updateStatistic 方法更新该用户的成绩。
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 参数实现这一需求:
overwrite
AV.Leaderboard.updateStatistics(AV.User.current(), { score: 0 }, { overwrite: true, }).then(function(statistics) { // score 会被强制更新为 0 }).catch(console.error);
你可以通过 getStatistics 方法查询某用户的某些成绩:
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 选项用来查询某用户的所有成绩:
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 方法的第一个参数包含以下选项:
limit
skip
selectUserKeys
string[]
includeStatistics
默认情况下返回的排行榜结果中的 user 是一个只有 id 属性的 AV.User Pointer。如果想要想下面这个例子一样,在排行榜结果中显示用户名或者其他的用户属性(对应 _User 表中的属性),那么需要使用 selectUserKeys 选项。
id
_User
var leaderboard = AV.Leaderboard.createWithoutData('score'); leaderboard.getResults({ limit: 10, selectUserKeys: ['username', 'age'], }).then(function(rankings) { // ranking 的 user 将包含 username 与 age 属性 }).catch(console.error);
类似的,如果想要在排行榜结果中包含用户的其他成绩,可以使用 includeStatistics 选项。
var leaderboard = AV.Leaderboard.createWithoutData('score'); leaderboard.getResults({ limit: 10, includeStatistics: ['kills'], }).then(function(rankings) { // 可以在 ranking 的 includedStatistics 属性中得到该用户的 kills 成绩 }).catch(console.error);
另一种常见的需求是获取当前登录用户附近的排名:
var leaderboard = AV.Leaderboard.createWithoutData('score'); leaderboard.getResultsAroundUser({ limit: 3, }).then(function(rankings) { // rankings 为当前用户附近的 3 条排名结果 }).catch(console.error);
Leaderboard#getResultsAroundUser 方法的第一个参数包含以下选项:
各参数的适用场景与用法与上文 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);
你可以指定以下参数:
AV.LeaderboardUpdateStrategy.BETTER
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。
排行榜开发指南 · JavaScript
Demo
您可以通过查看 Demo 感受排行榜功能。
安装 SDK
排行榜是存储 SDK 中的一个模块,要在 JavaScript 运行环境中使用排行榜功能,需要安装存储 SDK,请参考《 JavaScript SDK 安装指南》。
SDK 中的类
SDK 提供了对排行榜、成绩与用户的抽象。在开始之前,请确认您已阅读《排行榜总览》,本文中将不再具体解释相关的概念。
AV.Leaderboard
AV.Leaderboard
类是对排行榜的抽象。Leaderboard
实例有以下属性:statisticName
string
order
AV.LeaderboardOrder
updateStrategy
AV.LeaderboardUpdateStrategy
versionChangeInterval
AV.LeaderboardVersionChangeInterval
version
number
nextResetAt
Date
createdAt
Date
Statistic
排行榜是对用户的成绩进行排名的结果。SDK 提供了一个
Statistic
类来表示成绩。Statistic
实例有以下属性:name
string
statisticName
value
number
Ranking
排行榜排序的结果是一个数组,数组的成员是一个叫
Ranking
的结构:rank
number
user
AV.User
value
number
includedStatistics
Statistic[]
AV.User
排行榜中的用户指的是 LeanCloud 数据存储服务用户系统中的用户。在客户端,只有登录后才能更新当前登录用户的成绩。您可以通过《数据存储开发指南 - 用户》了解更多用户系统的功能与用法。
用户成绩管理
更新成绩
当用户完成了一局游戏后,你可以使用 SDK 的
updateStatistic
方法更新该用户的成绩。updateStatistic
方法的第二个参数是一个 key-value 的对象,key 为要更新的statisticName
,value 为要更新的成绩。你可以一次更新多个不同的成绩。更新成绩 API 需要用户登录,且用户只能更新自己的成绩。也可使用 masterKey 更新任意用户的成绩。
强制更新成绩
有些情况下,你会想要绕过排行榜的 更新策略 强制更新用户的成绩,你可以使用
overwrite
参数实现这一需求:查询成绩
你可以通过
getStatistics
方法查询某用户的某些成绩:你也可以省略
statisticNames
选项用来查询某用户的所有成绩:获取排行榜结果
SDK 提供了两种获取排行榜结果的 API:
Leaderboard#getResults
Leaderboard#getResultsAroundUser
获取指定区间的排名
获取排行榜结果最常见的使用场景是获取排名前 N 的用户成绩。
Leaderboard#getResults
方法的第一个参数包含以下选项:limit
number
skip
number
limit
一起可以实现翻页selectUserKeys
string[]
Ranking
中的user
需要包含的属性includeStatistics
string[]
Ranking
中需要包含的其他成绩version
number
默认情况下返回的排行榜结果中的
user
是一个只有id
属性的AV.User
Pointer。如果想要想下面这个例子一样,在排行榜结果中显示用户名或者其他的用户属性(对应_User
表中的属性),那么需要使用selectUserKeys
选项。类似的,如果想要在排行榜结果中包含用户的其他成绩,可以使用
includeStatistics
选项。获取当前用户附近的排名
另一种常见的需求是获取当前登录用户附近的排名:
Leaderboard#getResultsAroundUser
方法的第一个参数包含以下选项:limit
number
selectUserKeys
string[]
Ranking
中的user
需要包含的属性includeStatistics
string[]
Ranking
中需要包含的其他成绩version
number
各参数的适用场景与用法与上文
Leaderboard#getResults
的参数类似,不再详述。获取当前用户的排名
如果仅需要获取当前用户的排名,使用 获取当前用户附近的排名 中的
Leaderboard#getResultsAroundUser
方法并指定limit
为 1 时即可。管理排行榜
您可以在控制台的「游戏 - 排行榜 - 数据」页面完成排行榜的创建、重置、修改以及删除等操作。除此之外您也可以通过调用 SDK 的 API 来管理排行榜。
请注意,管理排行榜 API 需要 masterKey,因此只能在服务端等可信任的环境中调用。
创建排行榜
你可以指定以下参数:
statisticName
string
order
AV.LeaderboardOrder
updateStrategy
AV.LeaderboardUpdateStrategy
AV.LeaderboardUpdateStrategy.BETTER
versionChangeInterval
AV.LeaderboardVersionChangeInterval
AV.LeaderboardVersionChangeInterval.WEEK
详见《创建排行榜 API 文档》。
创建排行榜接口需要使用 masterKey。
手动重置排行榜
排行榜在创建之后会按照自动重置周期的设置自动定期重置,重置后该排行榜中所有用户的成绩都会被清空,你可以在控制台的历史版本中找到历史版本的归档。你也可以随时调用重置排行榜的接口手动进行重置。
重置排行榜接口需要使用 masterKey。
获取排行榜属性
通过这个接口可以获得当前排行榜的属性,例如:重置周期、版本号、更新策略等。
修改排行榜属性
排行榜创建后,名字与成绩排序方式不可修改。
自动重置周期可以通过调用以下 API 修改:
成绩更新策略可以通过调用以下 API 修改:
修改排行榜属性接口需要使用 masterKey。
删除排行榜
删除排行榜会删除该排行榜的所有数据,包括当前数据及所有历史版本归档。
删除排行榜接口需要使用 masterKey。