> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XblLeaderboardQuery

> XblLeaderboardQuery

# XblLeaderboardQuery

表示使用基于事件的统计信息或基于标题的统计信息提交排行榜查询的参数。

## 语法

```cpp theme={null}
typedef struct XblLeaderboardQuery {  
    uint64_t xboxUserId;  
    char scid[XBL_SCID_LENGTH];  
    const char* leaderboardName;  
    const char* statName;  
    XblSocialGroupType socialGroup;  
    const char** additionalColumnleaderboardNames;  
    size_t additionalColumnleaderboardNamesCount;  
    XblLeaderboardSortOrder order;  
    uint32_t maxItems;  
    uint64_t skipToXboxUserId;  
    uint32_t skipResultToRank;  
    const char* continuationToken;  
    XblLeaderboardQueryType queryType;  
} XblLeaderboardQuery  
```

### 成员

*xboxUserId*\
类型：uint64\_t

可选的请求用户的 XBOX 用户 ID。如果查询全局排行榜，则设置为 0。

*scid*\
类型：char\[XBL\_SCID\_LENGTH]

标题的 UTF-8 编码服务配置 ID (SCID)。

*leaderboardName*\
类型：const char\*

可选的 UTF-8 编码排行榜名称，用于获取该排行榜。查询社交排行榜或由游戏托管的统计信息支持的排行榜时，将其设置为 nullptr。

*statName*\
类型：const char\*

可选的 UTF-8 编码统计信息名称，用于获取该排行榜。查询社交排行榜或由游戏托管的统计信息支持的排行榜时使用。

*socialGroup*\
类型：[XblSocialGroupType](https://devdocs.xbox.com/zh-CN/reference/live/xsapi-c/leaderboard_c/enums/xblsocialgrouptype.md)

可选的用户社交组，用于获取排行榜结果。例如，获取 “仅好友” 排行榜。将其设置为 XblSocialGroupType\_None 以获取全局排行榜。

*additionalColumnleaderboardNames*\
类型：const char\*\*

可选的其他列的统计信息名称的 UTF-8 编码数组。

*additionalColumnleaderboardNamesCount*\
类型：size\_t

可选的传入的 additionalColumnleaderboardNames 的数量。

*order*\
类型：[XblLeaderboardSortOrder](https://devdocs.xbox.com/zh-CN/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardsortorder.md)

设置结果排行榜的排序顺序。

*maxItems*\
类型：uint32\_t

设置结果排行榜可包含的最大项数。将其设置为 0 可让服务返回默认最大项数。

*skipToXboxUserId*\
类型：uint64\_t

设置结果排行榜围绕哪个用户为中心。将其设置为 0 表示不跳到特定用户。

*skipResultToRank*\
类型：uint32\_t

设置结果排行榜围绕哪个排名为中心。将其设置为 0 表示不跳到特定排名。

*continuationToken*\
类型：const char\*

UTF-8 编码的 continuationToken，用于获取下一组排行榜数据。

*queryType*\
类型：[XblLeaderboardQueryType](https://devdocs.xbox.com/zh-CN/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardquerytype.md)

要查询的排行榜类型。

## 成员归属

[XblLeaderboardResult](https://devdocs.xbox.com/zh-CN/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardresult.md)

## 作为参数

[XblLeaderboardGetLeaderboardAsync](https://devdocs.xbox.com/zh-CN/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync.md)

## 备注

### 基于事件的统计信息

在使用 *statName* 成员配合[基于事件的统计信息](https://devdocs.xbox.com/zh-CN/services/xbox-services/player-data/stats-leaderboards/event-based/live-stats-eb-overview.md)时，其值应与[统计信息实例](https://devdocs.xbox.com/zh-CN/services/xbox-services/player-data/stats-leaderboards/event-based/live-stats-eb-overview.md#defining-stat-instances)相对应。

### 游戏托管的统计信息

在将[游戏托管的统计信息](https://devdocs.xbox.com/zh-CN/services/xbox-services/player-data/stats-leaderboards/title-managed/live-stats-tm-overview.md)用于排行榜时，将 *skipToXboxUserId* 设置为非零值会将指定的 *xboxUserId* 的存储统计信息与全局排行榜进行比较。

同样，将 *socialGroup* 设置为 People 或 Favorites 会比较指定 *xboxUserId* 及其关联用户的存储统计信息，不会使用全局排行榜的值。

**请注意，当玩家的存储统计信息与其在全局排行榜上的分数不同时，可能会导致输出不匹配。**

> [!NOTE]
>
> 对于游戏托管的统计信息，玩家在全局排行榜上的条目并非其当前存储统计信息的直接投影。排行榜服务**仅保留每位玩家已记录的最高值**。因此，**向统计信息写入更低的值不会降低该玩家在全局排行榜上的位置**；排行榜将继续反映之前记录的最高值。存储的统计信息本身(可通过 `XblUserStatisticsGet*` 或 `XblTitleManagedStatsGetForUserAsync` 查询)反映最近一次写入的值，这就是它可能与排行榜产生差异的原因。
>
> 如果你的标题需要排行榜位置能够下降，则游戏托管的统计信息并不合适。例如可上下变化的评分，或在失败时会重置的分数。相反，请考虑使用带 `Replace` 规则的基于事件的统计信息，或使用外部排行榜服务，例如 [PlayFab Leaderboards v2](https://learn.microsoft.com/gaming/playfab/community/leaderboards/)。有关此行为的更多讨论，请参阅 `LeaderboardsTitleManaged` Microsoft 游戏开发工具包 (GDK) 示例的[实现说明](https://github.com/microsoft/Xbox-GDK-Samples/blob/main/Samples/Live/LeaderboardsTitleManaged/readme_en-us.md)。

## 要求

**头文件：** leaderboard\_c.h

## 另请参阅

[leaderboard\_c](https://devdocs.xbox.com/zh-CN/reference/live/xsapi-c/leaderboard_c/leaderboard_c_members)\
[基于事件的统计信息与游戏托管的统计信息](https://devdocs.xbox.com/zh-CN/services/xbox-services/player-data/stats-leaderboards/live-stats-eb-vs-tm.md)


## Related topics

- [XblLeaderboardQueryType](https://devdocs.xbox.com/zh-CN/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardquerytype.md)
- [XblLeaderboardSortOrder](https://devdocs.xbox.com/zh-CN/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardsortorder.md)
- [XblLeaderboardGetLeaderboardAsync](https://devdocs.xbox.com/zh-CN/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync.md)
- [获取标题管理的排行榜](https://devdocs.xbox.com/zh-CN/services/xbox-services/player-data/stats-leaderboards/title-managed/how-to/live-getting-tm-leaderboard.md)
- [XblSocialGroupType](https://devdocs.xbox.com/zh-CN/reference/live/xsapi-c/leaderboard_c/enums/xblsocialgrouptype.md)