DataStoreSetOptions

DataStoreSetOptions 是 DataStore:SetAsync 的可选参数容器，用于设置 KeyInfo 返回、元数据保留策略、前置版本依赖、用户 ID 和自定义元数据。

概览

DataStoreSetOptions 是 DataStore:SetAsync 的可选参数容器，用于设置 KeyInfo 返回、元数据保留策略、前置版本依赖、用户 ID 和自定义元数据。

可通过 DataStoreSetOptions.New() 构造

代码示例

构造 SetAsync 选项

-- @runtime server
local options = DataStoreSetOptions.New()
options.WithKeyInfo = true
options:SetMetaData('source', 'save')

函数

GetUserIds

签名：GetUserIds() -> Table

获取当前 DataStoreSetOptions 实例中设置的用户 ID 列表。

返回值 Table

读取用户 ID 列表

-- @runtime server
local Players = game:GetService('Players')
local player = Players:GetPlayers()[1]
if player == nil then return end
local options = DataStoreSetOptions.New()
options:SetUserIds({ tostring(player.UserId) })
for _, userId in ipairs(options:GetUserIds() or {}) do
    print(userId)
end

SetUserIds

签名：SetUserIds(userIds: Table)

设置用户 ID 列表，整体替换之前添加的所有用户 ID。

参数	类型	说明
userIds	Table	用户ID列表

整体替换用户 ID 列表

-- @runtime server
local Players = game:GetService('Players')
local player = Players:GetPlayers()[1]
if player == nil then return end
local options = DataStoreSetOptions.New()
options:SetUserIds({ tostring(player.UserId) })

AddUserId

签名：AddUserId(userId: String)

向 DataStoreSetOptions 实例中添加一个用户 ID，用于标记该数据项与指定用户关联。

参数	类型	说明
userId	String	用户ID

追加单个用户 ID

-- @runtime server
local Players = game:GetService('Players')
local player = Players:GetPlayers()[1]
if player == nil then return end
local options = DataStoreSetOptions.New()
options:AddUserId(tostring(player.UserId))

GetMetaDatas

签名：GetMetaDatas() -> Table

获取当前 DataStoreSetOptions 实例中设置的用户自定义元数据字典。

返回值 Table

读取元数据字典

-- @runtime server
local options = DataStoreSetOptions.New()
options:SetMetaData('source', 'save')
local metas = options:GetMetaDatas() or {}
print(metas.source)

SetMetaDatas

签名：SetMetaDatas(dict: Table)

整体替换用户自定义元数据字典，传入的 Table 将完全覆盖之前设置的元数据。

参数	类型	说明
dict	Table	元数据字典

整体替换元数据字典

-- @runtime server
local options = DataStoreSetOptions.New()
options:SetMetaDatas({ source = 'save', season = 's1' })

UpdateMetaDatas

签名：UpdateMetaDatas(dict: Table)

合并更新用户自定义元数据，传入的 Table 中的键值对会合并到现有元数据字典中，已存在的 key 会被覆盖。

参数	类型	说明
dict	Table	要合并的元数据

合并更新元数据字典

-- @runtime server
local options = DataStoreSetOptions.New()
options:SetMetaDatas({ source = 'save' })
options:UpdateMetaDatas({ season = 's1' })

SetMetaData

签名：SetMetaData(name: String, value: String)

设置单个用户自定义元数据键值对，会合并到现有元数据字典中。

参数	类型	说明
name	String	元数据键名
value	String	元数据键值

设置单个元数据

-- @runtime server
local options = DataStoreSetOptions.New()
options:SetMetaData('source', 'save')

属性

名称	类型	默认值	说明
WithKeyInfo	Bool	-	是否在返回结果中附带键信息（version, created/modified time, UserIds, Metas 等键元数据）。
KeepOldMetas	Bool	-	设置更新时是否保留旧的元数据。
DependPrevVersion	String	-	设置依赖的前置版本号，仅当数据的当前版本与此版本一致时才允许更新。