键鼠助手 5.20 新增内置函数 GetUpTime()：给宏脚本一个毫秒时钟（用法与示例）

admin

这篇说明 5.20 版本新增的内置函数 GetUpTime()：宏脚本里第一个「读时间」的接口。
它没有参数，返回设备开机以来经过的毫秒数，用来计量耗时、给动作做绝对时间对齐。

相关：键鼠助手 5.0 资源汇总：主程序 / 文档 / 配套工具下载

一句话用法

local t = GetUpTime()   -- 单位毫秒，整型；返回值一般只用来算差值

接口说明

函数	参数	返回值	说明
`GetUpTime()`	无	整型	设备开机以来经过的毫秒数

几点需要说清楚：

不是「当前时间」：它是「开机以来的时长」，设备上电时从 0 开始，不表示几点几分，也不是时间戳。它的用途是算差值。
单位是毫秒，返回值是整型：脚本里 math.type(GetUpTime()) 得到 integer，可以直接参与加减乘除与比较。
分辨率 1 毫秒：设备内部按更细的步长计数，换算成毫秒时向下取整，所以相邻两次调用可能返回同一个值。
不会溢出：毫秒计数是 64 位整数，连续开机到溢出需要以「亿年」计，正常使用无需关心。
大小写不敏感：GetUpTime() 与 getuptime() 是同一个函数，和 IsKeyDown / iskeydown 的规则一致。
它是「读时钟」，不是「等待」：调用本身几乎不耗时、不会阻塞宏；要等一段时间请用 Delay(毫秒)。

在电脑上先调好再上机：两种环境的时间原点不同

同一个 GetUpTime()，在两个地方跑，时间原点不一样：

运行环境	时间原点	典型用途
编辑器 →「脚本校验」	本次校验开始的时刻	在电脑上先确认脚本的节奏与耗时
设备（真机）	设备本次上电的时刻	真实的宏执行计时

所以不要跨环境比较绝对数值（电脑上的 1200 和真机上的 1200 不是一个起点），只比较同一个环境内的差值。

用法一：测量一段宏的耗时

取两次时间戳相减，就能知道中间这段动作真实花了多久 —— 排查「宏为什么比预期慢」时很有用。

local t0 = GetUpTime()

KeyTap("a")
Delay(300)
KeyTap("b")

Log("这一段耗时 %d ms", GetUpTime() - t0)

Log 的首个参数带 %d 时按 printf 格式化，数字会原样打印出来，便于对照。

用法二：用绝对时间对齐，避免 Delay 累积误差

连续多次 Delay(500) 时，每一步自身的执行耗时会让整体越走越慢，误差逐次累加。
改用「目标时刻」判断，就能把每轮的落点重新拉回时间轴上：

-- 执行 4 轮，每轮之间间隔 500ms，落点分别对齐到 500 / 1000 / 1500 / 2000ms
local t0 = GetUpTime()
for i = 1, 4 do
    KeyTap("f")
    local target = i * 500
    while GetUpTime() - t0 < target do
        Delay(10)   -- 小步让出，别用空转等待
    end
end

要点：等待循环里一定要有 Delay(小值)，不要把 while 写成不带 Delay 的紧凑空转。

用法三：把宏做成固定的节拍

需要「每 1 秒做一件事、共 5 次」这类节奏时，用时间戳做判断比用 Delay 堆叠更稳：

local last = GetUpTime()
local count = 0
while count < 5 do
    local now = GetUpTime()
    if now - last >= 1000 then
        last = last + 1000      -- 以理论落点累加，不丢节拍
        KeyTap("space")
        count = count + 1
    end
    Delay(10)
end

last = last + 1000（而不是 last = now）能让误差不累积：即使某轮判定晚了一点，下一轮的落点仍然回到原来的时间轴上。

版本要求与兼容性

组合	结果
5.20 软件 + 配套固件	正常使用
5.20 之前的软件	编译不通过：`GetUpTime` 会被当成未定义的函数
5.20 软件 + 更早的固件	宏在设备上执行到该函数时会失败中断（不会静默返回 0）

所以升级软件时，请把固件一并升到配套版本。软件与固件的版本对应关系，参考资源汇总帖里的说明。

还是有问题？

在本帖下回复，写清楚：软件版本（关于页的 Software version）+ 固件版本 + 你脚本里调用 GetUpTime() 的那几行 + 现象。

一键科技