OrderedDataStore

概览

字段	值
Kind	Data · 数据 Data
Realm	server

继承关系

• DataStore（10 函数）
  • [OrderedDataStore]（1 函数）

继承成员

1 个来源 / 10 函数

• 来自 DataStore（10 函数）
  • 函数：GetAsync、SetAsync、IncrementAsync、RemoveAsync、UpdateAsync、ListKeysAsync、GetVersionAsync、GetVersionAtTimeAsync、ListVersionsAsync、RemoveVersionAsync

有序数据存储集合，用于存储键值对并支持按值排序检索。它继承自 DataStore，额外提供 GetSortedAsync 方法，可按升序或降序分页获取数据。写入的值必须是整数，适合排行榜、分数记录等需要排序的场景。

适用场景

典型场景是实现玩家排行榜，将玩家分数作为值存入 OrderedDataStore，然后通过 GetSortedAsync 按分数降序获取排名列表。

使用要点

通过 DataStoreService:GetOrderedDataStore 获取实例，使用 SetAsync 写入整数键值对，再调用 GetSortedAsync 并指定排序方向与分页大小，返回的 Pages 对象可通过 GetCurrentPage 和 AdvanceToNextPageAsync 遍历结果。

注意事项

OrderedDataStore 不可直接构造，必须由 DataStoreService:GetOrderedDataStore 返回；写入值必须是整数。GetSortedAsync 是异步读操作，应在 Task:Spawn 或协程中调用；返回 OrderedDataStoreKeyValueInfoPages 后通过 GetCurrentPage/AdvanceToNextPageAsync 分页读取。

代码示例

写入分数并按降序读取排行榜

-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local orderedStore = DataStoreService:GetOrderedDataStore('PlayerScore')

Task:Spawn(function()
    orderedStore:SetAsync('player_1001', 1200)
    orderedStore:SetAsync('player_1002', 900)

    local options = DataStoreGetOptions.New()
    local pages = orderedStore:GetSortedAsync(false, 10, nil, nil, options)
    for _, item in ipairs(pages:GetCurrentPage()) do
        print(item.Key, item.Value)
    end
end)

关联类型

• DataStore

函数 (1)

GetSortedAsync

签名：GetSortedAsync(ascending: Bool, pageSize?: Int, minValue?: Int, maxValue?: Int, options?: DataStoreGetOptions) -> OrderedDataStoreKeyValueInfoPages (分页迭代器)

获取有序数据存储中按 value 排序的分页数据。返回一个分页迭代器，可遍历排序后的键值对。

参数	类型	说明
ascending	Bool	是否升序
pageSize?	Int	页大小, 默认 0 (使用服务端默认值)
minValue?	Int	最小值过滤, 包含
maxValue?	Int	最大值过滤, 包含
options?	DataStoreGetOptions	可选参数, 优先级高于 OrderedDataStore 初始化时的 DataStoreOptions, 可通过 DataStoreGetOptions.New() 创建

返回值 OrderedDataStoreKeyValueInfoPages (分页迭代器)

示例代码

按 value 降序读取分页

-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local orderedStore = DataStoreService:GetOrderedDataStore('PlayerScore')

Task:Spawn(function()
    local options = DataStoreGetOptions.New()
    local pages = orderedStore:GetSortedAsync(false, 10, nil, nil, options)
    for _, item in ipairs(pages:GetCurrentPage()) do
        print(item.Key, item.Value)
    end
end)