【前端接口】GUI:Text_COUNTDOWN：倒计时控件与活动节奏的可视化

实战应用：用在哪里

倒计时是活动节奏的可视化心脏：拍卖截止、活动剩余、刷新等待全靠 GUI:Text_COUNTDOWN 一个接口驱动。它把时间戳转成 时：分：秒 的自动跳字控件，秒级刷新不需要业务写定时器。

创建倒计时

---倒计时控件 widget:文本对象 time:目标时间戳 callback:结束回调 showType:显示样式
function Text_COUNTDOWN(widget, time, callback, showType) end

-- 拍卖截止倒计时：挂到文本控件上
local txt = GUI:Text_Create(win, "auctionCd", 180, 220, 16, "#FFAA00", "")
Text_COUNTDOWN(txt, auction.endTime, function()
    GUI:Text_setString(txt, "已截拍")
    refreshAuctionList()
end, 0)

widget 参数传一个文本控件，time 传目标时间戳（不是剩余秒），控件自动按秒刷新显示剩余时间。倒计时走完触发 callback：拍卖的截止回调里改文案并刷新列表，回调让倒计时从展示升级为节奏控制器。showType 控制显示格式：超过一天的显示 天时分，一天的显示 时分秒，格式的自动适配省去业务判断。

与服务端时间的对齐

-- 以服务端下发的截止时间为准
local function syncCountdown(win, serverEndTime)
    local txt = GUI:Text_Create(win, "actCd", 150, 30, 14, "#FFFFFF", "")
    Text_COUNTDOWN(txt, serverEndTime, function()
        SL:SendNetMsg(8802, 0, 0, 0, "")
    end)
end

倒计时的目标时间用服务端下发的截止时间戳，本地时间的偏差不影响倒计时的准确性，时间权威在服务端是倒计时可信的前提。倒计时结束的回调里向服务端发消息拉取最新状态，客户端的倒计时走完与服务端的截止之间允许秒级误差，状态的最终确认以服务端为准。

验证与监控

倒计时控件的走时偏差监控（与服务端时间的秒差），偏差超过两秒的客户端进时区与时间的排查。

踩坑记录

倒计时的目标时间传了剩余秒而不是目标时间戳，倒计时显示成了 1970 年起步的天数，参数语义的两种流派（目标时间戳与剩余秒）要在团队内统一。回调的重复触发在控件复用时出现过，旧的倒计时回调没有随控件销毁而解除，复用控件前重置倒计时是标准动作。

上线要点

倒计时控件的复用场景（列表里的多个倒计时）要注意控件与回调的对应关系，列表滚动复用控件时倒计时数据要重新绑定。倒计时的显示样式与活动的紧迫感匹配：拍卖的倒计时红色渐变、活动的倒计时稳定白色，颜色语言服务场景语义。服务端时间与本地时间的同步校准在登录时完成一次，倒计时的准确性依赖这次校准。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。