主题
DataStoreService
DataStoreService 数据存储服务，提供数据持久化的读写、版本管理和排序查询能力。
概览
DataStoreService 是持久化键值数据的统一入口：通过 GetDataStore、GetGlobalDataStore、GetOrderedDataStore 按名称与作用域取出普通、全局或有序的数据集合句柄，供后续写入与读取使用。除日常读写入口外，它还支持用 ListDataStoresAsync、ListOrderedDataStoresAsync 分页枚举已有集合，用 TotalSummaryAsync 查看总体统计，并用 RemoveDataStoreAsync、RemoveOrderedDataStoreAsync、RestoreDataStoreAsync、RestoreOrderedDataStoreAsync 对集合做删除与恢复。
Get by:
lua
-- @runtime editor
local service = editor:GetService("DataStoreService")函数
GetDataStore
获取一个普通数据存储集合对象（DataStore），用于后续对该集合执行键值读写等操作。调用时通过 name 指定集合名称，scope 指定作用域，options 传入 DataStoreOptions 配置对象；后两个参数均为可选。返回值为 DataStore 实例，不能自行构造，只能由本接口获取。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
name | String | 数据存储名称 |
scope | String | 作用域（可选） |
options | DataStoreOptions | 存储选项（可选） |
返回值
| 类型 | 说明 |
|---|---|
DataStore | 数据存储集合对象，用于键值读写 |
调用 GetDataStore
lua
-- @runtime editor
local dataStoreService = editor:GetService("DataStoreService")
local name = "default" -- String
local scope = "default" -- String
local options = DataStoreOptions.New()
local result = dataStoreService:GetDataStore(name, scope, options) -- 返回 DataStore
if result ~= nil then
print("调用成功，结果: " .. tostring(result))
endGetGlobalDataStore
获取全局数据存储集合对象（DataStore），其效果等价于调用 GetDataStore("", "global", options)。该接口只接受一个可选的 options 参数（DataStoreOptions），返回值为 DataStore 实例，用于键值读写。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
options | DataStoreOptions | 存储选项（可选） |
返回值
| 类型 | 说明 |
|---|---|
DataStore | 全局数据存储集合对象 |
调用 GetGlobalDataStore
lua
-- @runtime editor
local dataStoreService = editor:GetService("DataStoreService")
local options = DataStoreOptions.New()
local result = dataStoreService:GetGlobalDataStore(options) -- 返回 DataStore
if result ~= nil then
print("调用成功，结果: " .. tostring(result))
endGetOrderedDataStore
获取一个有序数据存储集合对象（OrderedDataStore），用于按值排序的数据存储。调用时通过 name 指定集合名称，scope 指定作用域，options 传入 DataStoreOptions 配置对象，后两个参数可选。返回值为 OrderedDataStore 实例。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
name | String | 有序数据存储名称 |
scope | String | 作用域（可选） |
options | DataStoreOptions | 存储选项（可选） |
返回值
| 类型 | 说明 |
|---|---|
OrderedDataStore | 有序数据存储集合对象，支持按值排序 |
获取有序数据存储集合并验证其存在
lua
-- @runtime editor
local dataStoreService = editor:GetService("DataStoreService")
-- 第一步：同步获取一个按值排序的有序数据存储集合句柄（只返回句柄，不发起网络请求）
local orderedStore = dataStoreService:GetOrderedDataStore("PlayerScores", "Season1")
if orderedStore == nil then
print("获取有序数据存储集合失败：GetOrderedDataStore 返回 nil")
return
end
print("已获取有序数据存储集合句柄：PlayerScores（scope = Season1）")
-- 第二步：用查询类方法确认该有序集合已在客户端登记；异步方法必须放入协程执行
local listThread = coroutine.wrap(function()
local pages = dataStoreService:ListOrderedDataStoresAsync("PlayerScores")
if pages == nil then
print("ListOrderedDataStoresAsync 未返回分页结果")
return
end
print("客户端已登记的有序数据存储分页结果：", pages)
end)
listThread()ListDataStoresAsync
异步分页列出当前所有的普通 DataStore 集合，返回 DataStoreInfoPages 分页迭代器。可通过 prefix 限定集合名称前缀，pageSize 指定分页大小，cursor 指定游标，options 传入 DataStoreListOptions 配置对象，全部参数均为可选。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
prefix | String | 名称前缀过滤（可选） |
pageSize | Int | 每页数量（可选） |
cursor | String | 分页游标（可选） |
options | DataStoreListOptions | 分页选项（可选） |
返回值
| 类型 | 说明 |
|---|---|
DataStoreInfoPages | 数据存储信息的分页迭代器 |
协程中分页列出普通 DataStore 集合
lua
-- @runtime editor
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor:GetService('Task')
local listOptions = DataStoreListOptions.New()
-- ListDataStoresAsync 是异步方法，必须在协程中调用
Task:Spawn(function()
local pages = DataStoreService:ListDataStoresAsync('', 10, '', listOptions)
local currentPage = pages:GetCurrentPage()
print('当前页 DataStore 数量:', #currentPage)
end)ListOrderedDataStoresAsync
异步分页列出当前所有的有序 OrderedDataStore 集合，返回 DataStoreInfoPages 分页迭代器。可通过 prefix 限定集合名称前缀，pageSize 指定分页大小，cursor 指定游标，options 传入 DataStoreListOptions 配置对象，全部参数均为可选。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
prefix | String | 名称前缀过滤（可选） |
pageSize | Int | 每页数量（可选） |
cursor | String | 分页游标（可选） |
options | DataStoreListOptions | 分页选项（可选） |
返回值
| 类型 | 说明 |
|---|---|
DataStoreInfoPages | 有序数据存储信息的分页迭代器 |
协程中分页列出有序 OrderedDataStore 集合
lua
-- @runtime editor
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor:GetService('Task')
local listOptions = DataStoreListOptions.New()
Task:Spawn(function()
local pages = DataStoreService:ListOrderedDataStoresAsync('', 10, '', listOptions)
local currentPage = pages:GetCurrentPage()
print('当前页 OrderedDataStore 数量:', #currentPage)
end)TotalSummaryAsync
获取当前命名空间的聚合统计信息。该调用不需要额外参数，直接返回统计结果。
返回值
| 类型 | 说明 |
|---|---|
Map | 当前 namespace 的聚合统计数据 |
调用 TotalSummaryAsync
lua
-- @runtime editor
local Task = editor:GetService("Task")
Task:Spawn(function()
local dataStoreService = editor:GetService("DataStoreService")
local result = dataStoreService:TotalSummaryAsync() -- 返回 Map
if result ~= nil then
for key, item in pairs(result) do
print(key, item)
end
end
end)RemoveDataStoreAsync
删除指定的普通 DataStore 集合，属于软删除操作。参数为集合名称 name，返回被删除集合的 DataStoreInfo 信息对象。
注意： 该操作会删除整个 DataStore 集合。示例仅定义辅助函数；调用方确认目标是自己拥有且可删除的测试集合后，再显式传入集合名称调用。异步调用必须位于协程中。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
name | String | 要删除的数据存储名称 |
返回值
| 类型 | 说明 |
|---|---|
DataStoreInfo | 被删除集合的信息对象 |
删除文档验证专用 DataStore
lua
-- @runtime editor
local service = editor:GetService("DataStoreService")
local Task = editor:GetService("Task")
local function removeOwnedTestDataStore(testStoreName)
if type(testStoreName) ~= "string" or testStoreName == "" then return end
Task:Spawn(function()
local info = service:RemoveDataStoreAsync(testStoreName)
print("删除结果:", info)
end)
end
-- 确认集合属于自己且可删除后，显式调用 removeOwnedTestDataStore(testStoreName)。RemoveOrderedDataStoreAsync
删除指定的有序 OrderedDataStore 集合，属于软删除操作。参数为集合名称 name，返回被删除集合的 DataStoreInfo 信息对象。
注意： 该操作会删除整个 OrderedDataStore 集合。示例仅定义辅助函数；调用方确认目标是自己拥有且可删除的测试集合后，再显式传入集合名称调用。异步调用必须位于协程中。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
name | String | 要删除的有序数据存储名称 |
返回值
| 类型 | 说明 |
|---|---|
DataStoreInfo | 被删除集合的信息对象 |
删除文档验证专用 OrderedDataStore
lua
-- @runtime editor
local service = editor:GetService("DataStoreService")
local Task = editor:GetService("Task")
local function removeOwnedTestOrderedDataStore(testStoreName)
if type(testStoreName) ~= "string" or testStoreName == "" then return end
Task:Spawn(function()
local info = service:RemoveOrderedDataStoreAsync(testStoreName)
print("删除结果:", info)
end)
end
-- 确认集合属于自己且可删除后，显式调用 removeOwnedTestOrderedDataStore(testStoreName)。RestoreDataStoreAsync
恢复已删除的普通 DataStore 集合。参数为集合名称 name，返回被恢复集合的 DataStoreInfo 信息对象。
注意： 示例仅定义辅助函数；调用方显式传入自己拥有且处于可恢复期限内的测试集合名称后才执行恢复。没有可恢复记录时返回空结果。异步调用必须位于协程中。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
name | String | 要恢复的数据存储名称 |
返回值
| 类型 | 说明 |
|---|---|
DataStoreInfo | 被恢复集合的信息对象 |
恢复文档验证专用 DataStore
lua
-- @runtime editor
local service = editor:GetService("DataStoreService")
local Task = editor:GetService("Task")
local function restoreOwnedTestDataStore(testStoreName)
if type(testStoreName) ~= "string" or testStoreName == "" then return end
Task:Spawn(function()
local info = service:RestoreDataStoreAsync(testStoreName)
print("恢复结果:", info)
end)
end
-- 显式调用 restoreOwnedTestDataStore(testStoreName)，只恢复自己拥有的测试集合。RestoreOrderedDataStoreAsync
恢复已删除的有序 OrderedDataStore 集合。参数为集合名称 name，返回被恢复集合的 DataStoreInfo 信息对象。
注意： 示例仅定义辅助函数；调用方显式传入自己拥有且处于可恢复期限内的测试集合名称后才执行恢复。没有可恢复记录时返回空结果。异步调用必须位于协程中。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
name | String | 要恢复的有序数据存储名称 |
返回值
| 类型 | 说明 |
|---|---|
DataStoreInfo | 被恢复集合的信息对象 |
恢复文档验证专用 OrderedDataStore
lua
-- @runtime editor
local service = editor:GetService("DataStoreService")
local Task = editor:GetService("Task")
local function restoreOwnedTestOrderedDataStore(testStoreName)
if type(testStoreName) ~= "string" or testStoreName == "" then return end
Task:Spawn(function()
local info = service:RestoreOrderedDataStoreAsync(testStoreName)
print("恢复结果:", info)
end)
end
-- 显式调用 restoreOwnedTestOrderedDataStore(testStoreName)，只恢复自己拥有的测试集合。