> ## 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 使用者識別碼。如果是全域排行榜，請設定為 0。

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

遊戲的 UTF-8 編碼服務設定識別碼 (SCID)。

*leaderboardName*\
類型：const char\*

選用。要取得排行榜的 UTF-8 編碼排行榜名稱。如果查詢的是社交排行榜或以遊戲管理統計資料為基礎的排行榜，請設定為 nullptr。

*statName*\
類型：const char\*

選用。要取得排行榜的 UTF-8 編碼統計資料名稱。在查詢社交排行榜或以遊戲管理統計資料為基礎的排行榜時使用。

*socialGroup*\
類型：[XblSocialGroupType](/zh-TW/reference/live/xsapi-c/leaderboard_c/enums/xblsocialgrouptype)

選用。要取得排行榜結果的使用者社交群組。例如，取得「僅限朋友」的排行榜。設定為 XblSocialGroupType\_None 可取得全域排行榜。

*additionalColumnleaderboardNames*\
類型：const char\*\*

選用。其他欄之統計資料名稱的 UTF-8 編碼陣列。

*additionalColumnleaderboardNamesCount*\
類型：size\_t

選用。傳入的 additionalColumnleaderboardNames 數目。

*order*\
類型：[XblLeaderboardSortOrder](/zh-TW/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardsortorder)

設定所產生排行榜的排序順序。

*maxItems*\
類型：uint32\_t

設定所產生排行榜包含的項目數目上限。設定為 0 可讓服務傳回預設的項目數目上限。

*skipToXboxUserId*\
類型：uint64\_t

設定所產生排行榜以哪位使用者為中心。設定為 0 則不跳至特定使用者。

*skipResultToRank*\
類型：uint32\_t

設定所產生排行榜以哪個排名為中心。設定為 0 則不跳至特定排名。

*continuationToken*\
類型：const char\*

用來取得下一組排行榜資料的 UTF-8 編碼 continuationToken。

*queryType*\
類型：[XblLeaderboardQueryType](/zh-TW/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardquerytype)

要查詢的排行榜類型。

## 隸屬於

[XblLeaderboardResult](/zh-TW/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardresult)

## 作為下列項目的引數

[XblLeaderboardGetLeaderboardAsync](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync)

## 備註

### 以事件為基礎的 Stats

搭配 [以事件為基礎的 Stats](/zh-TW/services/xbox-services/player-data/stats-leaderboards/event-based/live-stats-eb-overview) 使用 *statName* 成員時，其值應與 [統計資料執行個體](/zh-TW/services/xbox-services/player-data/stats-leaderboards/event-based/live-stats-eb-overview#defining-stat-instances) 一致。

### 遊戲管理的 Stats

針對排行榜使用 [遊戲管理的 Stats](/zh-TW/services/xbox-services/player-data/stats-leaderboards/title-managed/live-stats-tm-overview) 時，將 *skipToXboxUserId* 設定為非零值，會將指定 *xboxUserId* 的已儲存統計資料與全域排行榜進行比較。

同樣地，將 *socialGroup* 設定為 People 或 Favorites，會比較指定 *xboxUserId* 與相關聯使用者的已儲存統計資料。它不會使用全域排行榜的值。

**請注意，當玩家的已儲存統計資料與其在全域排行榜上的分數不同時，可能會導致輸出不一致。**

<Info>
  對於遊戲管理的 Stats，玩家的全域排行榜項目並非其目前已儲存統計資料的直接投影。排行榜服務**只會保留每位玩家的最高記錄值**。因此，**將較低的值寫入統計資料並不會降低該玩家在全域排行榜上的位置**；排行榜會持續反映先前記錄的最高值。已儲存的統計資料本身 (可透過 `XblUserStatisticsGet*` 或 `XblTitleManagedStatsGetForUserAsync` 查詢) 反映的是最近寫入的值，這就是它可能與排行榜不一致的原因。

  如果您的遊戲需要讓排行榜位置下降，則不適合使用遊戲管理的 Stats。例如會上升或下降的評分，或在落敗時重設的分數。請改為考慮使用具有 `Replace` 規則的以事件為基礎的 Stats，或外部排行榜服務，例如 [PlayFab Leaderboards v2](/zh-TW/services/playfab/community/leaderboards/index)。如需此行為的詳細討論，請參閱 `LeaderboardsTitleManaged` Microsoft Game Development Kit (GDK) 範例的 [實作注意事項](https://github.com/microsoft/Xbox-GDK-Samples/blob/main/Samples/Live/LeaderboardsTitleManaged/readme_en-us.md)。
</Info>

## 需求

**標頭：** leaderboard\_c.h

## 另請參閱

[leaderboard\_c](/zh-TW/reference/live/xsapi-c/leaderboard_c/leaderboard_c_members)\
[以事件為基礎與遊戲管理的 Stats 比較](/zh-TW/services/xbox-services/player-data/stats-leaderboards/live-stats-eb-vs-tm)


## Related topics

- [XblLeaderboardQueryType](/zh-TW/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardquerytype.md)
- [XblLeaderboardSortOrder](/zh-TW/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardsortorder.md)
- [XblLeaderboardGetLeaderboardAsync](/zh-TW/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync.md)
- [取得遊戲管理型排行榜](/zh-TW/services/xbox-services/player-data/stats-leaderboards/title-managed/how-to/live-getting-tm-leaderboard.md)
- [XblSocialGroupType](/zh-TW/reference/live/xsapi-c/leaderboard_c/enums/xblsocialgrouptype.md)