【前端接口】SL:SecondToHMS 与 TimeFormatToStr：时间展示的格式化双雄

实战应用：用在哪里

秒数变成玩家看得懂的时间：SL:SecondToHMS 把秒数拆成 时分秒，SL:TimeFormatToStr 把时间戳转成日期文本。倒计时、在线时长、冷却剩余、活动排期的时间展示全部依赖这对格式化函数，时间展示的统一格式全站由此保证。

秒数的时分秒拆分

---秒转时分秒 sec:秒数 isToStr:转字符串 isSimple:简洁模式
function SL:SecondToHMS(sec, isToStr, isSimple) end

-- 活动剩余 8925 秒的展示
local hms = SL:SecondToHMS(8925, true, false)
GUI:Text_setString(cdText, hms)   -- 输出 02:28:45

-- 简洁模式：超过一天显示 天时分
local simple = SL:SecondToHMS(259200, true, true)  -- 3天0时0分

isToStr 决定返回字符串还是表结构，isSimple 的简洁模式自动升级大单位：不足一天显示时分秒、超过一天自动带天，展示格式的自适应不需要业务判断。倒计时控件（Text_COUNTDOWN）的内部格式化同源于这套函数，散用的格式化与控件的格式保持全站一致。

时间戳的日期文本

---时间戳转字符串 time:时间戳
function SL:TimeFormatToStr(time) end

-- 邮件列表的日期列
for _, mail in ipairs(mailData) do
    local dateStr = SL:TimeFormatToStr(mail.sendAt)
    GUI:Text_Create(item, "date", 260, 12, 11, "#AAAAAA", dateStr)
end

时间戳到日期文本的转换服务于记录类展示：邮件的发送日期、公告的发布时间、拍卖的截止日期。时间的展示格式全站统一（年月日时分的基本格式），格式的一致性让玩家扫一眼就能对齐信息。服务端下发的时间戳统一为秒级 Unix 时间，前端的格式化只做展示不做时区的二次换算，时区的权威在服务端下发时就确定。

验证与监控

时间展示的格式回归测试覆盖边界值：零秒、整点、跨天、闰年的样本集让格式化函数的边界无懈可击。

踩坑记录

秒与毫秒的混淆曾经让倒计时显示成了 49 天（毫秒被当秒），时间单位的统一在接口的入口参数处断言。格式化函数的简洁模式与完整模式的选用曾经随意，展示格式的规范（倒计时用完整、记录用简洁）成文后统一。

上线要点

时间格式化的调用收敛到统一的封装，散落的直调在格式升级时要改遍全站。倒计时与格式化函数的配合：Text_COUNTDOWN 内部已做格式化，散用的场景才需要直调 SecondToHMS，控件的优先级高于散用。时间的本地化展示（中文的年月日与时分秒）在海外版本发布时的适配点提前预留。

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