工坊手册

主题

Pages ​

概览 ​

字段值
KindData · 数据 Data
Realmserver

继承关系 ​

Pages 是分页数据的迭代器封装，用于把体量较大的列举结果拆成多页逐步读取。它对外提供当前页内容的读取、是否已迭代完毕的状态标记，以及异步推进到下一页的操作，实例由各类列表类接口在返回值中提供，业务侧不能自行创建。

适用场景 ​

当 DataStore、MemoryStore 等列表接口返回的条目较多、需要分批处理时，会得到 Pages 实例用于逐页遍历结果。典型做法是在循环中读取当前页内容并处理，随后推进到下一页，直到迭代结束。

使用要点 ​

Pages 不能通过 Pages.New 或 Pages() 构造，只能从返回分页迭代器的列表接口获取。拿到实例后先调用 GetCurrentPage 取出当前页数据，处理完后调用 AdvanceToNextPageAsync 并等待其完成，再继续读取下一页；循环过程可用 IsFinished 判断是否已经迭代完毕。

注意事项 ​

Pages 是由 DataStore/MemoryStore 等列表接口返回的分页迭代器，不可直接构造。GetCurrentPage 读取当前页；AdvanceToNextPageAsync 会推进到下一页并返回是否成功，分页循环中应等待该调用完成后再继续读取下一页，不要把 AdvanceToNextPageAsync 放进另一个 Task:Spawn 后让外层 while 立即继续。

代码示例 ​

遍历分页数据 ​

lua
-- @runtime server
local DataStoreService = game:GetService("DataStoreService")
local Task = game:GetService("Task")
local orderedStore = DataStoreService:GetOrderedDataStore("PlayerScores")

Task:Spawn(function()
  local pages = orderedStore:GetSortedAsync(false, 10)
  while true do
    local currentPage = pages:GetCurrentPage()
    for _, item in ipairs(currentPage) do
      print("Key:", item.Key, "Value:", item.Value)
    end

    if pages.IsFinished then
      break
    end

    local ok = pages:AdvanceToNextPageAsync()
    if not ok then
      print("翻页失败，停止遍历")
      break
    end
  end
end)

属性 (1) ​

Name类型默认值说明
IsFinishedBoolfalse布尔型只读属性，用于标识当前分页结果是否已经全部迭代完毕。读取该属性可以判断是否还存在后续页数据，从而决定继续分页还是结束读取。

函数 (2) ​

GetCurrentPage ​

签名：GetCurrentPage() -> Array<String> (当前页的数据对象列表)

返回当前页的数据列表；具体元素结构由创建该分页对象的列表接口决定。

返回值 Array<String> (当前页的数据对象列表)

示例代码

读取当前页数据

lua
-- @runtime server
local DataStoreService = game:GetService("DataStoreService")
local Task = game:GetService("Task")
local orderedStore = DataStoreService:GetOrderedDataStore("PlayerScores")

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

AdvanceToNextPageAsync ​

签名：AdvanceToNextPageAsync() -> Bool (是否成功翻页)

异步将分页数据翻到下一页，并返回是否成功翻页。

⚙ 推进到下一页并返回是否成功。分页循环中应等待该调用完成后再读取下一页，不要在外层 while 中用 Task:Spawn 异步调用后立即继续循环。

返回值 Bool (是否成功翻页)

示例代码

等待翻页并继续读取

lua
-- @runtime server
local DataStoreService = game:GetService("DataStoreService")
local Task = game:GetService("Task")
local orderedStore = DataStoreService:GetOrderedDataStore("PlayerScores")

Task:Spawn(function()
  local pages = orderedStore:GetSortedAsync(false, 10)
  while true do
    for _, item in ipairs(pages:GetCurrentPage()) do
      print("Key:", item.Key, "Value:", item.Value)
    end
    if pages.IsFinished then
      break
    end
    local ok = pages:AdvanceToNextPageAsync()
    if not ok then
      break
    end
  end
end)