Platform.spells.GetSpellCooldown

调用方式

addon.Platform:GetSpellCooldown(spell)

可直接通过 addon 使用，无需依赖项。

作用

读取各受支持客户端的法术冷却并将其规范化。返回的记录包含 startTime、duration、isEnabled 和 modRate。时间戳和持续时间已经以 GetTime() 秒数描述到期时间；不要再除以 modRate。当客户端隐藏时间时（正式服和永久服的战斗中），记录为 nil，原因为 restricted-value，在可以读取时其后会附上永不为机密的 isEnabled、isActive 和 isOnGCD 标志。

参数

名称	类型	作用
`self`	`RMPlatform`	Rotation Master 平台适配器。点号引用需要将 addon.Platform 作为第一个参数；冒号调用会隐含提供它。
`spell`	`number \| string`	要读取其冷却的法术 ID 或客户端可识别的法术名称。

返回值

1	`table \| nil`	可读的冷却记录；不可用时为 nil。
2	`string \| nil`	记录为 nil 时的可用性或验证原因。
3	`boolean \| nil`	仅限 restricted-value：isEnabled，冷却处于暂停时为 false。
4	`boolean \| nil`	仅限 restricted-value：isActive，在冷却（其自身冷却或公共冷却）进行中时为 true。
5	`boolean \| nil`	仅限 restricted-value：isOnGCD，当进行中的冷却是公共冷却时为 true；可能为 nil。

版本

内置辅助函数在每个版本上都会注册。不同的是它们读取的游戏 API；某个 API 缺失时，辅助函数会改用后备方案，或返回 nil 并附上原因。

该版本不可用（原因见提示）
仅在暴雪的弃用兼容层开启时

游戏 API
`C_Spell.GetSpellCooldown`
`GetSpellCooldown`

秘密值（正式服和永久服）

在正式服和永久服上，游戏交给插件的是秘密值。此辅助函数会检查它读取的内容（addon.Platform:CanReadValue），遇到无法比较的秘密值时返回 nil 并附上原因（例如 restricted-value），而不是返回该秘密值。请将 nil 视为不可用，而不是假。

示例

local record, reason, isEnabled, isActive = addon.Platform:GetSpellCooldown(value.spell)
if record then return record.isEnabled and record.duration == 0 end
-- Times are secret in combat on Retail and Forever; fall back to the flags.
if reason == "restricted-value" and isActive ~= nil then return isEnabled and not isActive end
return nil

依赖项

cooldownFields (builtin:Platform/spells.lua:cooldownFields)
cooldownFlags → Platform.spells.cooldownFlags
identifier → Platform.spells.identifier
own → Platform.spells.own

源码

Platform/spells.lua，第 393 行。在游戏中为只读；“复制”会生成一份可编辑的副本。

Platform.spells.GetSpellCooldown(self, spell)

    local valid, reason = identifier(spell)
    if not valid then return nil, reason end
    local ok, record, built
    if C_Spell and type(C_Spell.GetSpellCooldown) == "function" then
        ok, record = pcall(C_Spell.GetSpellCooldown, spell)
    elseif type(GetSpellCooldown) == "function" then
        local start, duration, enabled, rate
        ok, start, duration, enabled, rate = pcall(GetSpellCooldown, spell)
        if not ok then return nil, "api-error" end
        if not self:CanReadValue(start) or not self:CanReadValue(duration) or not self:CanReadValue(enabled)
            or not self:CanReadValue(rate) then return nil, "restricted-value" end
        if start ~= nil then
            if enabled ~= 0 and enabled ~= 1 then return nil, "invalid-api-result" end
            record = {startTime=start, duration=duration, isEnabled=enabled == 1, modRate=rate or 1};built = true
        end
    else return nil, "missing-api" end
    if not ok then return nil, "api-error" end
    if not self:CanReadValue(record) then return nil, "restricted-value" end
    if record == nil then return nil, "spell-data-unavailable" end
    local cooldown, why = own(record, cooldownFields, built)
    if not cooldown then
        if why == "restricted-value" and not built then return nil, why, cooldownFlags(self, record) end
        return nil, why
    end
    if cooldown.startTime == nil or cooldown.duration == nil or cooldown.isEnabled == nil
        or cooldown.startTime < 0 or cooldown.duration < 0 or (cooldown.modRate and cooldown.modRate <= 0) then
        return nil, "invalid-api-result"
    end
    cooldown.modRate = cooldown.modRate or 1
    return cooldown

返回函数参考