1. 为什么需要GetLocalTime秒级时间不够用前几天群里有个朋友问我想给一个自动点击脚本加日志每次操作耗时只有几十毫秒但用易语言的“取现行时间 ()”记下来的时间秒数几乎不变根本看不出操作之间的先后顺序和间隔。这个场景我太熟悉了早年写按键监控工具时也栽过这个跟头。易语言自带的取现行时间确实只能拿到秒级精度要想把时间精确到毫秒就必须绕开命令直接调用Windows系统API这里最顺手的就是GetLocalTime。这篇东西我就以“易语言API GetLocalTime获取时间到毫秒”为主线把从结构体定义、DLL声明、格式化输出到实战封装的整套做法整理出来。无论你是做日志、测耗时的还是想在界面上显示一个带毫秒的时钟照着这个思路走都不会跑偏。内容偏实践我尽量把底层原理也讲透这样你遇到问题时不至于只会抄代码还能自己排查。1.1 一个日志场景引发的需求先回到那个自动点击脚本的需求。用户的操作流程是点击按钮A等待一小段时间点击按钮B再等待点击按钮C。整个流程可能在几十到几百毫秒内完成。如果日志只记录到秒那么三条记录的秒数可能完全相同排错的时候根本分不清顺序更看不出哪一步卡了多久。我在实际项目里还遇到过更尴尬的情况某个模拟器界面响应很慢界面上的进度条会卡住程序在等待窗口句柄的过程中需要把“等待了多久”写进日志。用秒级时间粗看全是0秒拿到客户那边根本解释不清软件卡顿到底发生在哪一段。换用毫秒级时间之后等待时长一目了然问题定位效率直接提升一个档次。这种场景非常多不只是日志。比如数据采集程序需要在1秒内采样多个点如果不用毫秒时间戳数据点会叠在一起绘图时根本展不开又比如随机数种子直接用秒级时间去初始化同一秒内产生的随机序列完全相同这在抽奖、洗牌、加密等场景里是致命的。1.2 易语言里获取时间有哪些路径易语言新手最容易想到的就是“取现行时间 ()”这个命令返回一个日期时间型变量显示格式是“2024-01-01 12:00:00”精度到秒。还有一个“取启动时间 ()”返回的是从程序启动到现在的毫秒数但它不是“当前日历时间”没法直接当时间戳用。想要真正的毫秒级日历时间只能走API。Windows提供的时间相关API不算少我简单梳理一下容易混淆的几个API返回值精度用途GetLocalTimeSYSTEMTIME结构体毫秒获取本地当前时间带毫秒字段GetSystemTimeSYSTEMTIME结构体毫秒获取UTC世界标准时间带毫秒字段GetTickCountDWORD整数毫秒系统启动至今的毫秒数有效期约49.7天GetTickCount6464位整数毫秒无回绕问题的启动毫秒数timeGetTimeDWORD整数毫秒多媒体定时器默认受系统分辨率影响QueryPerformanceCounter64位整数微秒级高精度性能计数用于测量时间间隔GetLocalTime的特点是它既给你“年/月/日/时/分/秒”这种日历信息又额外给了一个毫秒字段。这就解决了取现行时间精度不足的问题同时又比GetTickCount这类“纯毫秒计数”更直观因为你不需要自己换算成日期。1.3 GetSystemTime与GetLocalTime选错时区就白干了很多刚接触API的人在搜索资料时会同时看到GetSystemTime和GetLocalTime然后犯迷糊。这两者的区别其实就一句话GetSystemTime返回的是UTC时间也就是格林尼治标准时间不带时区偏移GetLocalTime返回的是本地时间也就是Windows按你系统设置的时区自动换算后的时间。在中国一般就是UTC8。从使用习惯上讲本地展示和日志记录选GetLocalTime就够了人看的日志当然要显示本地时间。但如果你的程序要跟服务器、云服务或者跨时区的其他机器对时间那就得选GetSystemTime。因为两台机器如果时区不同本地时间完全没有可比性只有UTC时间才是同一把尺子。我之前做过一个模拟数据上报的Demo本机记录的数据和另一台机器上的数据要做时间排序当时图省事全用了本地时间结果两个机器时区差了5个小时排序结果完全对不上。后来统一改成GetSystemTime再在展示层做时区转换问题才解决。所以动手之前想清楚一个重要问题你拿到这个毫秒时间到底是为了人看还是要给机器比这决定了你该用哪个函数。2. 看懂SYSTEMTIME结构体再动手写代码调用GetLocalTime之前必须先弄清楚它的输出参数。这个API只有一个参数是一个指向SYSTEMTIME结构体的指针函数内部会把当前时间填进这个结构体里。很多人第一次写就卡在这里因为易语言里没有一个现成的“系统时间”数据类型你得自己定义一个一模一样的结构体出来。定义结构体之前先把SYSTEMTIME的原型搞明白。这是Windows SDK里的标准定义我在下面逐个字段拆开讲。2.1 八个字段和每字节的含义SYSTEMTIME结构体一共8个成员每个成员都是WORD类型也就是无符号16位整数范围0到65535。8个成员加起来正好16字节。结构体顺序如下字段类型含义取值范围wYearWORD年份1601到30827wMonthWORD月份1到12wDayOfWeekWORD星期几0代表周日1代表周一wDayWORD日1到31wHourWORD小时0到23wMinuteWORD分钟0到59wSecondWORD秒0到59wMillisecondsWORD毫秒0到999这里有两处特别容易踩坑。第一字段顺序是“年、月、星期、日”不是“年、月、日、星期”。wDayOfWeek夹在月份和日之间定义结构体时顺序写错后边所有字段都会错位。第二毫秒字段的取值范围是0到999如果看到1000那说明你的取值逻辑或者系统状态有问题正常API不会给到1000。2.2 易语言数据类型映射短整数型不是整数型易语言没有WORD这个数据类型最接近的是“短整数型”它也是16位有符号整数范围-32768到32767。年份、月份这些值都在这个范围内所以直接用短整数型定义没有问题。这也是最容易忽略的一步很多人图省事把8个字段全定义成“整数型”结果结构体长度变成32字节API往里面写16字节数据后边字段读出来全是乱的。在易语言里定义这个结构体标准的写法是.版本 2 .数据类型 SYSTEMTIME wYear 为 短整数型 wMonth 为 短整数型 wDayOfWeek 为 短整数型 wDay 为 短整数型 wHour 为 短整数型 wMinute 为 短整数型 wSecond 为 短整数型 wMilliseconds 为 短整数型定义完成之后你就可以声明一个SYSTEMTIME类型的变量把它当成一个“盒子”传给APIAPI会把时间数据填到这个盒子的对应位置里。2.3 不要忘记的成员对齐概念结构体在内存中不是简单地把每个成员码放起来成员之间可能因为“对齐”产生间隙。不过SYSTEMTIME这个结构体很幸运8个WORD类型成员都是2字节在Windows默认的4字节对齐规则下16字节正好是4的倍数成员之间没有任何填充所以结构体长度就是精确的16字节。但你如果手痒在结构体末尾额外加了一个“文本型”或者“整数型”成员事情就变了。文本型在易语言里本质是一个指针占4字节加在末尾会让整个结构体变成20字节以上而且对齐规则可能在你本地机器上正常换个系统就出问题。我的建议是结构体保持原样一个多余字段都不要加所有额外信息自己用单独的变量保存。如果你实在想验证结构体长度是不是16字节可以用“取字节集长度”配合“指针到字节集”来检查。先把结构体变量取地址然后用“指针到字节集 (取变量数据地址 (结构体变量), 16)”取回16字节数据正常情况下字节集长度就是16多一字节就说明定义出错了。3. 易语言调用GetLocalTime的完整实现结构体定义好了接下来就是正式的DLL声明和调用环节。这一块是实操重头戏我会把每一步都拆开写清楚包括常见的声明歧义和调用习惯。3.1 DLL命令声明参数类型怎么选GetLocalTime的原型是void GetLocalTime(LPSYSTEMTIME lpSystemTime);注意这个参数是一个指针指向SYSTEMTIME结构体的地址。所以在易语言的DLL命令声明里最不容易出错的参数类型是“整数型”然后在调用时用“取变量数据地址 ()”把结构体的内存地址传进去。声明方式如下.版本 2 .DLL命令 取本地系统时间, , kernel32.dll, GetLocalTime .参数 lpSystemTime, 整数型, , 指向SYSTEMTIME结构体的指针这里有几个细节值得说明第一DLL库名写“kernel32.dll”这是Windows核心动态库GetLocalTime就在里面不用额外注册任何东西。第二函数返回类型留空因为GetLocalTime本身没有返回值它的输出完全通过参数带回。第三命令名可以自己起中文名比如“取本地系统时间”调用时用中文名就清爽很多。也有一种写法是在参数类型里直接选“SYSTEMTIME”这个自定义类型让易语言自动处理指针。这种写法在某些易语言版本里确实能跑但问题在于不同版本对自定义类型传参的底层处理方式不完全一致有的传的是结构体副本有的传的是地址一旦遇到API需要写回就会出幺蛾子。为了避免这种不确定的坑我一律用“整数型取变量数据地址”这套方案稳。3.2 定义结构体变量并调用现在可以写一个最简单的调用了。新建一个易语言程序在程序集变量或者子程序局部变量里声明一个SYSTEMTIME类型的变量然后调用DLL命令把变量地址传进去最后读取各个字段。.版本 2 .支持库 spec .程序集 程序集1 .子程序 _启动子程序, 整数型 .局部变量 系统时间, SYSTEMTIME .局部变量 调试文本, 文本型 取本地系统时间 (取变量数据地址 (系统时间)) 调试文本 年份 到文本 (系统时间.wYear) 毫秒 到文本 (系统时间.wMilliseconds) 调试输出 (调试文本) 返回 (0)这段代码跑起来之后调试输出会显示类似“年份2024 毫秒326”的结果。如果你看到毫秒字段在不断变化说明调用已经成功了。这里要注意局部变量的生命周期只在子程序内有效如果你想在多个子程序里共用这个时间数据应该把SYSTEMTIME变量声明成程序集变量或者全局变量或者每次调用都重新取得一份数据。3.3 格式化输出补齐前导零直接读字段数值得到的往往是“2024-1-5 9:3:27”这种不整齐的文本。做日志的话最好统一成“YYYY-MM-DD HH:mm:ss.fff”格式这样按字符串排序时时间顺序天然正确。问题在于易语言并没有现成的“格式化日期时间”命令能把数值自动补零你得自己写一个补零函数。我用得最多的补零写法是这样的.版本 2 .子程序 补零, 文本型 .参数 原文本, 文本型 .参数 总长度, 整数型 .局部变量 结果, 文本型 .局部变量 差距, 整数型 .局部变量 i, 整数型 结果 原文本 差距 总长度 - 取文本长度 (结果) 计次循环首 (差距, i) 结果 0 结果 计次循环尾 () 返回 (结果)有了补零函数再写一个格式化子程序.版本 2 .子程序 格式化带毫秒时间, 文本型 .参数 系统时间, SYSTEMTIME .局部变量 结果, 文本型 结果 到文本 (系统时间.wYear) - 结果 结果 补零 (到文本 (系统时间.wMonth), 2) - 结果 结果 补零 (到文本 (系统时间.wDay), 2) 结果 结果 补零 (到文本 (系统时间.wHour), 2) : 结果 结果 补零 (到文本 (系统时间.wMinute), 2) : 结果 结果 补零 (到文本 (系统时间.wSecond), 2) . 结果 结果 补零 (到文本 (系统时间.wMilliseconds), 3) 返回 (结果)注意毫秒要补到3位“5”要显示为“005”而不是“5”。否则日志里“2024-01-01 00:00:00.5”和“2024-01-01 00:00:00.05”排序时后者的字典序反而更靠前一秒内的顺序就错了。3.4 完整示例程序与实测输出把上面的内容拼起来一个完整的控制台测试程序如下.版本 2 .支持库 spec .程序集 程序集1 .子程序 _启动子程序, 整数型 .局部变量 系统时间, SYSTEMTIME .局部变量 i, 整数型 .局部变量 时间文本, 文本型 计次循环首 (5, i) 取本地系统时间 (取变量数据地址 (系统时间)) 时间文本 格式化带毫秒时间 (系统时间) 调试输出 (时间文本) 延时 (10) 计次循环尾 () 返回 (0)在实际运行中你可能会看到这样的结果* “2024-11-03 15:22:31.106” * “2024-11-03 15:22:31.118” * “2024-11-03 15:22:31.128” * “2024-11-03 15:22:31.138” * “2024-11-03 15:22:31.148”注意毫秒值的间隔不是固定的10而是随着系统任务调度略有浮动。这是正常现象不用紧张。如果你发现毫秒值完全不变化或者出现0、1、2这种规律递增的小数值多半是结构和调用方式还有问题。4. 实战毫秒时间模块与真实场景单次调用能拿到带毫秒的时间这只是第一步。真正写程序时你要的是“能直接用、能复用”的模块。我这里整理一个可落地的封装思路顺带讲讲我在日志和耗时统计里是怎么用的。4.1 把时间获取封装成通用子程序我习惯把“获取本地毫秒时间文本”和“获取当前时间的总毫秒数”分别封装成两个子程序一个给人看一个给机器算。给人看的子程序本质就是把之前的格式化调用包一层调用方不用关心SYSTEMTIME结构体也不用关心补零逻辑.版本 2 .子程序 取本地毫秒时间文本, 文本型 .局部变量 系统时间, SYSTEMTIME 取本地系统时间 (取变量数据地址 (系统时间)) 返回 (格式化带毫秒时间 (系统时间))以后任何地方要打日志直接一行写到文件 (取运行目录 () \log.txt, 到字节集 (取本地毫秒时间文本 () 内容 日志信息 #换行符))这个封装看起来平平无奇但它最大的价值是“隔离变化”。假如你以后想从GetLocalTime换成GetSystemTime或者想在返回文本前面加上程序版本号你只需要改这一个子程序全工程的调用处都不用动。这就是模块化的意义。4.2 用毫秒时间戳做一个日志记录器日志记录器是我在易语言项目里用得最多的模块。核心逻辑很简单每次写日志时先取一次带毫秒的当前时间拼上日志级别和内容再追加到文件末尾。完整参考实现.版本 2 .子程序 写日志, .参数 日志内容, 文本型 .参数 日志级别, 整数型, , 0信息 1警告 2错误 .局部变量 日志文件, 文本型 .局部变量 级别文本, 文本型 日志文件 取运行目录 () \app.log 级别文本 多选 (日志级别, 信息, 警告, 错误) 写到文件 (日志文件, 读入文件 (日志文件) 到字节集 (取本地毫秒时间文本 () [ 级别文本 ] 日志内容 #换行符))这里我用了“读入文件追加”的方式简单直接适合日志量不是特别大的工具类程序。如果你写的是高频率日志比如每秒几十条建议改成分行缓冲或者用“打开文件移到文件尾写出字节集”的方式避免频繁读入整个文件导致性能下降。写日志的细节上我个人有一个偏好日志级别文本要紧跟时间戳比如“2024-11-03 15:22:31.118 [信息] 启动成功”。这样用文本编辑器打开日志时哪怕不借助任何工具扫一眼就能看出某条日志发生在哪个具体时刻状态是高是低。4.3 用GetLocalTime做耗时统计的简单实现耗时统计有两种做法。第一种是直接用GetLocalTime取两次时间然后计算差值。因为SYSTEMTIME里有时、分、秒、毫秒四个字段直接做减法容易出进位问题所以在做差值之前最好把时间统一换算成“从当天0点开始的总毫秒数”。换算公式很简单总毫秒数 wHour × 3600000 wMinute × 60000 wSecond × 1000 wMilliseconds换算成易语言子程序.版本 2 .子程序 系统时间转总毫秒, 长整数型 .参数 系统时间, SYSTEMTIME 返回 (到长整数型 (系统时间.wHour) × 3600000 到长整数型 (系统时间.wMinute) × 60000 到长整数型 (系统时间.wSecond) × 1000 到长整数型 (系统时间.wMilliseconds))注意这里一定要先把短整数型转成“长整数型”再乘否则短整数型和整数型运算时可能溢出。之前我写过一版直接用整数型做乘法在计算到晚上11点以后的时间时结果变成负数排查了半天才发现是溢出问题。然后在测耗时的地方这样用.版本 2 .子程序 测试操作耗时 .局部变量 开始时间, SYSTEMTIME .局部变量 结束时间, SYSTEMTIME .局部变量 开始毫秒, 长整数型 .局部变量 结束毫秒, 长整数型 取本地系统时间 (取变量数据地址 (开始时间)) 开始毫秒 系统时间转总毫秒 (开始时间) 这里放你要测的操作 延时 (50) 取本地系统时间 (取变量数据地址 (结束时间)) 结束毫秒 系统时间转总毫秒 (结束时间) 调试输出 (“耗时(毫秒):” 到文本 (结束毫秒 - 开始毫秒))这套逻辑有一个注意点它只适合测量“当日内”的耗时。假如你的操作跨越了午夜0点也就是开始时间是23:59:59.950结束时间是00:00:00.050算出来的差值会是负数。不过对于绝大多数工具类程序来说单个操作的耗时都在秒级甚至毫秒级跨天的情况几乎不会出现所以我一般不做跨天处理。真要严谨的话配合日期字段一起判断把跨过日界线的部分补上24小时总毫秒数。4.4 GetLocalTime与GetTickCount/QueryPerformanceCounter对照我遇到很多朋友会问既然有GetTickCount为什么还要用GetLocalTime用途不同。我把这几个常用方案摆在一起对比一下你就明白了方案能拿到当前日历时间能拿毫秒适合场景取现行时间能否只需要秒级展示GetLocalTime能能日志、界面显示、毫秒时间戳GetTickCount / 取启动时间否能测相对耗时、超时判断QueryPerformanceCounter否微秒级高精度性能分析结论很简单需要“此时此刻是几点几分几秒”时用GetLocalTime需要“这个函数跑了多少毫秒”时用GetTickCount往往更省事因为它不需要处理结构体两次调用一减就完事需要分析性能热点达到微秒甚至纳秒级别时用QueryPerformanceCounter。我之前做图像处理Demo时分析某个滤镜函数的耗时用GetLocalTime测根本测不出来因为单次执行耗时才几十微秒毫秒字段经常是0。后来换成QueryPerformanceCounter才能稳定测出每次执行的微秒级差异。所以工具的选用要看量级GetLocalTime在毫秒级应用里够用再往下就不够看了。5. 常见问题与排查经验写到这里核心内容基本完整了。最后集中整理一下我实际使用中遇到的坑以及对应的处理经验。这些内容正常文档里看不到但对你会很有帮助。5.1 毫秒值按15ms步进是不是代码错了新手最容易困惑的现象调用GetLocalTime得到的毫秒字段不是每1毫秒变化一次而是每隔大约15毫秒或者16毫秒才变一次有时候连续三次数值都一样。很多人第一反应是自己代码写错了其实不是。Windows系统有一个“系统计时器分辨率”的概念默认情况下通常是15.625毫秒也就是操作系统底层时钟大约64Hz。GetLocalTime的毫秒字段依赖这个系统时钟节拍所以它表现出来的变化粒度不是1毫秒而是约15毫秒。换句话说你在大多数Windows系统上哪怕每秒调用GetLocalTime一百次毫秒字段的取值频率也跟不上真实时间。如果你确实需要按1毫秒级别的分辨率取时间可以在程序启动时调用timeBeginPeriod(1)提高系统计时器分辨率程序退出时调用timeEndPeriod(1)恢复。不过要注意提高计时器频率会增加系统功耗和中断负载对笔记本续航有一定影响所以用完必须恢复不是万不得已不要常开。我个人在易语言里的做法是给日志模块加一个“毫秒分辨率增强”的开关默认关闭。需要精确到1毫秒的场景比如按键间隔非常短的自动化测试我才打开这个开关。5.2 结构体参数传参导致崩溃或乱码调用GetLocalTime时程序崩溃十有八九是参数传错。最典型的有三种第一种参数类型声明成了“文本型”或“字节集”忘了用取变量数据地址。GetLocalTime要求的是一个指针你把文本型变量地址传过去级别相当于是把一块字符缓冲区当成SYSTEMTIME来写数据越界程序自然崩溃。第二种结构体字段类型定义错误。用整数型代替短整数型结构体长度变成32字节API只写前16字节后边的字段读出来就是初始值0或者乱码。症状通常表现为年月日都对但时分秒和毫秒全是0或者月份之后所有字段都不对。第三种DLL声明里的库名或者函数名写错。比如写成“kernel32”→“Kernel32.dll”时大小写不对或者函数名写成了“GetLocalTIme”多了一个字母。这种问题在编译阶段不会报错运行调试时才会看到调用失败或者返回异常。排查这类问题最快的办法是打印结构体的字节集。先用“取指针到字节集”把16字节数据输出为十六进制文本然后对照SYSTEMTIME的字段顺序人工分析。如果每个WORD按顺序显示说明API调用成功了如果数据变形问题一定出在声明或传参上。5.3 调用频繁是否拖慢程序有些朋友会担心在循环里每次点击或者每次界面刷新都调用GetLocalTime会不会拖慢程序。实际测试下来GetLocalTime是一个很轻量的系统调用单次开销在微秒级别远低于一次“延时 (10)”或者一次界面重绘。正常情况下哪怕你在500毫秒延时循环里每帧调用一次性能影响可以忽略不计。真正该注意的是“频繁取毫秒时间然后写文件”这类组合操作。日志写文件是磁盘IO才是性能瓶颈。如果日志频率很高建议在内存里先缓冲一批日志定时批量写盘而不是每条日志都打开、写入、关闭文件一次。我做过一个模拟按键记录工具运行一小时后生成了几万条日志用的就是批量缓冲方案。启动时创建一个内存列表到了100条或者时间过了1秒就统一写入一次性能稳定日志也不会丢。5.4 需要高精度计时时怎么办再扩展一下如果GetLocalTime的毫秒精度已经不能满足你比如你要测一段代码跑了多少微秒就应该用QueryPerformanceCounter。这是Windows提供的高精度性能计数频率通常与CPU主频相关能达到微秒级甚至纳秒级。在易语言里调用它需要稍微多写几步。QueryPerformanceCounter接受一个LARGE_INTEGER指针这是一个64位结构体。易语言可以用两个整数型字段来定义高32位和低32位分别存放。具体实现我简单给一个思路.版本 2 .数据类型 LARGE_INTEGER 低32位 为 整数型 高32位 为 整数型 .DLL命令 取性能计数, 整数型, kernel32.dll, QueryPerformanceCounter .参数 lpPerformanceCount, 整数型 .DLL命令 取性能频率, 整数型, kernel32.dll, QueryPerformanceFrequency .参数 lpFrequency, 整数型 .子程序 取微秒耗时, 长整数型 .参数 开始计数, LARGE_INTEGER .参数 结束计数, LARGE_INTEGER .局部变量 频率, LARGE_INTEGER .局部变量 差值, 长整数型 取性能频率 (取变量数据地址 (频率)) 差值 (结束计数.高32位 × 4294967296 结束计数.低32位) - (开始计数.高32位 × 4294967296 开始计数.低32位) 返回 (差值 × 1000000 ÷ (频率.高32位 × 4294967296 频率.低32位))这套做法的核心是GetLocalTime给你的是“日历时间的绝对时刻”而QueryPerformanceCounter给你的是“时间间隔的精密刻钟”。两者配合使用既能写出带毫秒的日志时间戳又能精确分析每段操作的开销。做了这么多年易语言我最深的体会是遇到精度不够的问题先别急着怀疑语言不行Windows底层其实提供了足够丰富的API关键是你要知道去哪里找、怎么声明、怎么传参。GetLocalTime这条链路解决的是“带毫秒的当前时间”它不复杂但每一步都有讲究。希望这篇整理能帮你少走几步弯路遇到具体问题的时候也能自己分析出到底是结构体定义错了还是系统时钟精度不够而不是一味地改运气。 
长河君 · 2026/10/14 3:42:51 · 阅读 1.2k 易语言调用GetLocalTime获取毫秒级时间：结构体与DLL声明实战
1. 为什么需要GetLocalTime秒级时间不够用前几天群里有个朋友问我想给一个自动点击脚本加日志每次操作耗时只有几十毫秒但用易语言的“取现行时间 ()”记下来的时间秒数几乎不变根本看不出操作之间的先后顺序和间隔。这个场景我太熟悉了早年写按键监控工具时也栽过这个跟头。易语言自带的取现行时间确实只能拿到秒级精度要想把时间精确到毫秒就必须绕开命令直接调用Windows系统API这里最顺手的就是GetLocalTime。这篇东西我就以“易语言API GetLocalTime获取时间到毫秒”为主线把从结构体定义、DLL声明、格式化输出到实战封装的整套做法整理出来。无论你是做日志、测耗时的还是想在界面上显示一个带毫秒的时钟照着这个思路走都不会跑偏。内容偏实践我尽量把底层原理也讲透这样你遇到问题时不至于只会抄代码还能自己排查。1.1 一个日志场景引发的需求先回到那个自动点击脚本的需求。用户的操作流程是点击按钮A等待一小段时间点击按钮B再等待点击按钮C。整个流程可能在几十到几百毫秒内完成。如果日志只记录到秒那么三条记录的秒数可能完全相同排错的时候根本分不清顺序更看不出哪一步卡了多久。我在实际项目里还遇到过更尴尬的情况某个模拟器界面响应很慢界面上的进度条会卡住程序在等待窗口句柄的过程中需要把“等待了多久”写进日志。用秒级时间粗看全是0秒拿到客户那边根本解释不清软件卡顿到底发生在哪一段。换用毫秒级时间之后等待时长一目了然问题定位效率直接提升一个档次。这种场景非常多不只是日志。比如数据采集程序需要在1秒内采样多个点如果不用毫秒时间戳数据点会叠在一起绘图时根本展不开又比如随机数种子直接用秒级时间去初始化同一秒内产生的随机序列完全相同这在抽奖、洗牌、加密等场景里是致命的。1.2 易语言里获取时间有哪些路径易语言新手最容易想到的就是“取现行时间 ()”这个命令返回一个日期时间型变量显示格式是“2024-01-01 12:00:00”精度到秒。还有一个“取启动时间 ()”返回的是从程序启动到现在的毫秒数但它不是“当前日历时间”没法直接当时间戳用。想要真正的毫秒级日历时间只能走API。Windows提供的时间相关API不算少我简单梳理一下容易混淆的几个API返回值精度用途GetLocalTimeSYSTEMTIME结构体毫秒获取本地当前时间带毫秒字段GetSystemTimeSYSTEMTIME结构体毫秒获取UTC世界标准时间带毫秒字段GetTickCountDWORD整数毫秒系统启动至今的毫秒数有效期约49.7天GetTickCount6464位整数毫秒无回绕问题的启动毫秒数timeGetTimeDWORD整数毫秒多媒体定时器默认受系统分辨率影响QueryPerformanceCounter64位整数微秒级高精度性能计数用于测量时间间隔GetLocalTime的特点是它既给你“年/月/日/时/分/秒”这种日历信息又额外给了一个毫秒字段。这就解决了取现行时间精度不足的问题同时又比GetTickCount这类“纯毫秒计数”更直观因为你不需要自己换算成日期。1.3 GetSystemTime与GetLocalTime选错时区就白干了很多刚接触API的人在搜索资料时会同时看到GetSystemTime和GetLocalTime然后犯迷糊。这两者的区别其实就一句话GetSystemTime返回的是UTC时间也就是格林尼治标准时间不带时区偏移GetLocalTime返回的是本地时间也就是Windows按你系统设置的时区自动换算后的时间。在中国一般就是UTC8。从使用习惯上讲本地展示和日志记录选GetLocalTime就够了人看的日志当然要显示本地时间。但如果你的程序要跟服务器、云服务或者跨时区的其他机器对时间那就得选GetSystemTime。因为两台机器如果时区不同本地时间完全没有可比性只有UTC时间才是同一把尺子。我之前做过一个模拟数据上报的Demo本机记录的数据和另一台机器上的数据要做时间排序当时图省事全用了本地时间结果两个机器时区差了5个小时排序结果完全对不上。后来统一改成GetSystemTime再在展示层做时区转换问题才解决。所以动手之前想清楚一个重要问题你拿到这个毫秒时间到底是为了人看还是要给机器比这决定了你该用哪个函数。2. 看懂SYSTEMTIME结构体再动手写代码调用GetLocalTime之前必须先弄清楚它的输出参数。这个API只有一个参数是一个指向SYSTEMTIME结构体的指针函数内部会把当前时间填进这个结构体里。很多人第一次写就卡在这里因为易语言里没有一个现成的“系统时间”数据类型你得自己定义一个一模一样的结构体出来。定义结构体之前先把SYSTEMTIME的原型搞明白。这是Windows SDK里的标准定义我在下面逐个字段拆开讲。2.1 八个字段和每字节的含义SYSTEMTIME结构体一共8个成员每个成员都是WORD类型也就是无符号16位整数范围0到65535。8个成员加起来正好16字节。结构体顺序如下字段类型含义取值范围wYearWORD年份1601到30827wMonthWORD月份1到12wDayOfWeekWORD星期几0代表周日1代表周一wDayWORD日1到31wHourWORD小时0到23wMinuteWORD分钟0到59wSecondWORD秒0到59wMillisecondsWORD毫秒0到999这里有两处特别容易踩坑。第一字段顺序是“年、月、星期、日”不是“年、月、日、星期”。wDayOfWeek夹在月份和日之间定义结构体时顺序写错后边所有字段都会错位。第二毫秒字段的取值范围是0到999如果看到1000那说明你的取值逻辑或者系统状态有问题正常API不会给到1000。2.2 易语言数据类型映射短整数型不是整数型易语言没有WORD这个数据类型最接近的是“短整数型”它也是16位有符号整数范围-32768到32767。年份、月份这些值都在这个范围内所以直接用短整数型定义没有问题。这也是最容易忽略的一步很多人图省事把8个字段全定义成“整数型”结果结构体长度变成32字节API往里面写16字节数据后边字段读出来全是乱的。在易语言里定义这个结构体标准的写法是.版本 2 .数据类型 SYSTEMTIME wYear 为 短整数型 wMonth 为 短整数型 wDayOfWeek 为 短整数型 wDay 为 短整数型 wHour 为 短整数型 wMinute 为 短整数型 wSecond 为 短整数型 wMilliseconds 为 短整数型定义完成之后你就可以声明一个SYSTEMTIME类型的变量把它当成一个“盒子”传给APIAPI会把时间数据填到这个盒子的对应位置里。2.3 不要忘记的成员对齐概念结构体在内存中不是简单地把每个成员码放起来成员之间可能因为“对齐”产生间隙。不过SYSTEMTIME这个结构体很幸运8个WORD类型成员都是2字节在Windows默认的4字节对齐规则下16字节正好是4的倍数成员之间没有任何填充所以结构体长度就是精确的16字节。但你如果手痒在结构体末尾额外加了一个“文本型”或者“整数型”成员事情就变了。文本型在易语言里本质是一个指针占4字节加在末尾会让整个结构体变成20字节以上而且对齐规则可能在你本地机器上正常换个系统就出问题。我的建议是结构体保持原样一个多余字段都不要加所有额外信息自己用单独的变量保存。如果你实在想验证结构体长度是不是16字节可以用“取字节集长度”配合“指针到字节集”来检查。先把结构体变量取地址然后用“指针到字节集 (取变量数据地址 (结构体变量), 16)”取回16字节数据正常情况下字节集长度就是16多一字节就说明定义出错了。3. 易语言调用GetLocalTime的完整实现结构体定义好了接下来就是正式的DLL声明和调用环节。这一块是实操重头戏我会把每一步都拆开写清楚包括常见的声明歧义和调用习惯。3.1 DLL命令声明参数类型怎么选GetLocalTime的原型是void GetLocalTime(LPSYSTEMTIME lpSystemTime);注意这个参数是一个指针指向SYSTEMTIME结构体的地址。所以在易语言的DLL命令声明里最不容易出错的参数类型是“整数型”然后在调用时用“取变量数据地址 ()”把结构体的内存地址传进去。声明方式如下.版本 2 .DLL命令 取本地系统时间, , kernel32.dll, GetLocalTime .参数 lpSystemTime, 整数型, , 指向SYSTEMTIME结构体的指针这里有几个细节值得说明第一DLL库名写“kernel32.dll”这是Windows核心动态库GetLocalTime就在里面不用额外注册任何东西。第二函数返回类型留空因为GetLocalTime本身没有返回值它的输出完全通过参数带回。第三命令名可以自己起中文名比如“取本地系统时间”调用时用中文名就清爽很多。也有一种写法是在参数类型里直接选“SYSTEMTIME”这个自定义类型让易语言自动处理指针。这种写法在某些易语言版本里确实能跑但问题在于不同版本对自定义类型传参的底层处理方式不完全一致有的传的是结构体副本有的传的是地址一旦遇到API需要写回就会出幺蛾子。为了避免这种不确定的坑我一律用“整数型取变量数据地址”这套方案稳。3.2 定义结构体变量并调用现在可以写一个最简单的调用了。新建一个易语言程序在程序集变量或者子程序局部变量里声明一个SYSTEMTIME类型的变量然后调用DLL命令把变量地址传进去最后读取各个字段。.版本 2 .支持库 spec .程序集 程序集1 .子程序 _启动子程序, 整数型 .局部变量 系统时间, SYSTEMTIME .局部变量 调试文本, 文本型 取本地系统时间 (取变量数据地址 (系统时间)) 调试文本 年份 到文本 (系统时间.wYear) 毫秒 到文本 (系统时间.wMilliseconds) 调试输出 (调试文本) 返回 (0)这段代码跑起来之后调试输出会显示类似“年份2024 毫秒326”的结果。如果你看到毫秒字段在不断变化说明调用已经成功了。这里要注意局部变量的生命周期只在子程序内有效如果你想在多个子程序里共用这个时间数据应该把SYSTEMTIME变量声明成程序集变量或者全局变量或者每次调用都重新取得一份数据。3.3 格式化输出补齐前导零直接读字段数值得到的往往是“2024-1-5 9:3:27”这种不整齐的文本。做日志的话最好统一成“YYYY-MM-DD HH:mm:ss.fff”格式这样按字符串排序时时间顺序天然正确。问题在于易语言并没有现成的“格式化日期时间”命令能把数值自动补零你得自己写一个补零函数。我用得最多的补零写法是这样的.版本 2 .子程序 补零, 文本型 .参数 原文本, 文本型 .参数 总长度, 整数型 .局部变量 结果, 文本型 .局部变量 差距, 整数型 .局部变量 i, 整数型 结果 原文本 差距 总长度 - 取文本长度 (结果) 计次循环首 (差距, i) 结果 0 结果 计次循环尾 () 返回 (结果)有了补零函数再写一个格式化子程序.版本 2 .子程序 格式化带毫秒时间, 文本型 .参数 系统时间, SYSTEMTIME .局部变量 结果, 文本型 结果 到文本 (系统时间.wYear) - 结果 结果 补零 (到文本 (系统时间.wMonth), 2) - 结果 结果 补零 (到文本 (系统时间.wDay), 2) 结果 结果 补零 (到文本 (系统时间.wHour), 2) : 结果 结果 补零 (到文本 (系统时间.wMinute), 2) : 结果 结果 补零 (到文本 (系统时间.wSecond), 2) . 结果 结果 补零 (到文本 (系统时间.wMilliseconds), 3) 返回 (结果)注意毫秒要补到3位“5”要显示为“005”而不是“5”。否则日志里“2024-01-01 00:00:00.5”和“2024-01-01 00:00:00.05”排序时后者的字典序反而更靠前一秒内的顺序就错了。3.4 完整示例程序与实测输出把上面的内容拼起来一个完整的控制台测试程序如下.版本 2 .支持库 spec .程序集 程序集1 .子程序 _启动子程序, 整数型 .局部变量 系统时间, SYSTEMTIME .局部变量 i, 整数型 .局部变量 时间文本, 文本型 计次循环首 (5, i) 取本地系统时间 (取变量数据地址 (系统时间)) 时间文本 格式化带毫秒时间 (系统时间) 调试输出 (时间文本) 延时 (10) 计次循环尾 () 返回 (0)在实际运行中你可能会看到这样的结果* “2024-11-03 15:22:31.106” * “2024-11-03 15:22:31.118” * “2024-11-03 15:22:31.128” * “2024-11-03 15:22:31.138” * “2024-11-03 15:22:31.148”注意毫秒值的间隔不是固定的10而是随着系统任务调度略有浮动。这是正常现象不用紧张。如果你发现毫秒值完全不变化或者出现0、1、2这种规律递增的小数值多半是结构和调用方式还有问题。4. 实战毫秒时间模块与真实场景单次调用能拿到带毫秒的时间这只是第一步。真正写程序时你要的是“能直接用、能复用”的模块。我这里整理一个可落地的封装思路顺带讲讲我在日志和耗时统计里是怎么用的。4.1 把时间获取封装成通用子程序我习惯把“获取本地毫秒时间文本”和“获取当前时间的总毫秒数”分别封装成两个子程序一个给人看一个给机器算。给人看的子程序本质就是把之前的格式化调用包一层调用方不用关心SYSTEMTIME结构体也不用关心补零逻辑.版本 2 .子程序 取本地毫秒时间文本, 文本型 .局部变量 系统时间, SYSTEMTIME 取本地系统时间 (取变量数据地址 (系统时间)) 返回 (格式化带毫秒时间 (系统时间))以后任何地方要打日志直接一行写到文件 (取运行目录 () \log.txt, 到字节集 (取本地毫秒时间文本 () 内容 日志信息 #换行符))这个封装看起来平平无奇但它最大的价值是“隔离变化”。假如你以后想从GetLocalTime换成GetSystemTime或者想在返回文本前面加上程序版本号你只需要改这一个子程序全工程的调用处都不用动。这就是模块化的意义。4.2 用毫秒时间戳做一个日志记录器日志记录器是我在易语言项目里用得最多的模块。核心逻辑很简单每次写日志时先取一次带毫秒的当前时间拼上日志级别和内容再追加到文件末尾。完整参考实现.版本 2 .子程序 写日志, .参数 日志内容, 文本型 .参数 日志级别, 整数型, , 0信息 1警告 2错误 .局部变量 日志文件, 文本型 .局部变量 级别文本, 文本型 日志文件 取运行目录 () \app.log 级别文本 多选 (日志级别, 信息, 警告, 错误) 写到文件 (日志文件, 读入文件 (日志文件) 到字节集 (取本地毫秒时间文本 () [ 级别文本 ] 日志内容 #换行符))这里我用了“读入文件追加”的方式简单直接适合日志量不是特别大的工具类程序。如果你写的是高频率日志比如每秒几十条建议改成分行缓冲或者用“打开文件移到文件尾写出字节集”的方式避免频繁读入整个文件导致性能下降。写日志的细节上我个人有一个偏好日志级别文本要紧跟时间戳比如“2024-11-03 15:22:31.118 [信息] 启动成功”。这样用文本编辑器打开日志时哪怕不借助任何工具扫一眼就能看出某条日志发生在哪个具体时刻状态是高是低。4.3 用GetLocalTime做耗时统计的简单实现耗时统计有两种做法。第一种是直接用GetLocalTime取两次时间然后计算差值。因为SYSTEMTIME里有时、分、秒、毫秒四个字段直接做减法容易出进位问题所以在做差值之前最好把时间统一换算成“从当天0点开始的总毫秒数”。换算公式很简单总毫秒数 wHour × 3600000 wMinute × 60000 wSecond × 1000 wMilliseconds换算成易语言子程序.版本 2 .子程序 系统时间转总毫秒, 长整数型 .参数 系统时间, SYSTEMTIME 返回 (到长整数型 (系统时间.wHour) × 3600000 到长整数型 (系统时间.wMinute) × 60000 到长整数型 (系统时间.wSecond) × 1000 到长整数型 (系统时间.wMilliseconds))注意这里一定要先把短整数型转成“长整数型”再乘否则短整数型和整数型运算时可能溢出。之前我写过一版直接用整数型做乘法在计算到晚上11点以后的时间时结果变成负数排查了半天才发现是溢出问题。然后在测耗时的地方这样用.版本 2 .子程序 测试操作耗时 .局部变量 开始时间, SYSTEMTIME .局部变量 结束时间, SYSTEMTIME .局部变量 开始毫秒, 长整数型 .局部变量 结束毫秒, 长整数型 取本地系统时间 (取变量数据地址 (开始时间)) 开始毫秒 系统时间转总毫秒 (开始时间) 这里放你要测的操作 延时 (50) 取本地系统时间 (取变量数据地址 (结束时间)) 结束毫秒 系统时间转总毫秒 (结束时间) 调试输出 (“耗时(毫秒):” 到文本 (结束毫秒 - 开始毫秒))这套逻辑有一个注意点它只适合测量“当日内”的耗时。假如你的操作跨越了午夜0点也就是开始时间是23:59:59.950结束时间是00:00:00.050算出来的差值会是负数。不过对于绝大多数工具类程序来说单个操作的耗时都在秒级甚至毫秒级跨天的情况几乎不会出现所以我一般不做跨天处理。真要严谨的话配合日期字段一起判断把跨过日界线的部分补上24小时总毫秒数。4.4 GetLocalTime与GetTickCount/QueryPerformanceCounter对照我遇到很多朋友会问既然有GetTickCount为什么还要用GetLocalTime用途不同。我把这几个常用方案摆在一起对比一下你就明白了方案能拿到当前日历时间能拿毫秒适合场景取现行时间能否只需要秒级展示GetLocalTime能能日志、界面显示、毫秒时间戳GetTickCount / 取启动时间否能测相对耗时、超时判断QueryPerformanceCounter否微秒级高精度性能分析结论很简单需要“此时此刻是几点几分几秒”时用GetLocalTime需要“这个函数跑了多少毫秒”时用GetTickCount往往更省事因为它不需要处理结构体两次调用一减就完事需要分析性能热点达到微秒甚至纳秒级别时用QueryPerformanceCounter。我之前做图像处理Demo时分析某个滤镜函数的耗时用GetLocalTime测根本测不出来因为单次执行耗时才几十微秒毫秒字段经常是0。后来换成QueryPerformanceCounter才能稳定测出每次执行的微秒级差异。所以工具的选用要看量级GetLocalTime在毫秒级应用里够用再往下就不够看了。5. 常见问题与排查经验写到这里核心内容基本完整了。最后集中整理一下我实际使用中遇到的坑以及对应的处理经验。这些内容正常文档里看不到但对你会很有帮助。5.1 毫秒值按15ms步进是不是代码错了新手最容易困惑的现象调用GetLocalTime得到的毫秒字段不是每1毫秒变化一次而是每隔大约15毫秒或者16毫秒才变一次有时候连续三次数值都一样。很多人第一反应是自己代码写错了其实不是。Windows系统有一个“系统计时器分辨率”的概念默认情况下通常是15.625毫秒也就是操作系统底层时钟大约64Hz。GetLocalTime的毫秒字段依赖这个系统时钟节拍所以它表现出来的变化粒度不是1毫秒而是约15毫秒。换句话说你在大多数Windows系统上哪怕每秒调用GetLocalTime一百次毫秒字段的取值频率也跟不上真实时间。如果你确实需要按1毫秒级别的分辨率取时间可以在程序启动时调用timeBeginPeriod(1)提高系统计时器分辨率程序退出时调用timeEndPeriod(1)恢复。不过要注意提高计时器频率会增加系统功耗和中断负载对笔记本续航有一定影响所以用完必须恢复不是万不得已不要常开。我个人在易语言里的做法是给日志模块加一个“毫秒分辨率增强”的开关默认关闭。需要精确到1毫秒的场景比如按键间隔非常短的自动化测试我才打开这个开关。5.2 结构体参数传参导致崩溃或乱码调用GetLocalTime时程序崩溃十有八九是参数传错。最典型的有三种第一种参数类型声明成了“文本型”或“字节集”忘了用取变量数据地址。GetLocalTime要求的是一个指针你把文本型变量地址传过去级别相当于是把一块字符缓冲区当成SYSTEMTIME来写数据越界程序自然崩溃。第二种结构体字段类型定义错误。用整数型代替短整数型结构体长度变成32字节API只写前16字节后边的字段读出来就是初始值0或者乱码。症状通常表现为年月日都对但时分秒和毫秒全是0或者月份之后所有字段都不对。第三种DLL声明里的库名或者函数名写错。比如写成“kernel32”→“Kernel32.dll”时大小写不对或者函数名写成了“GetLocalTIme”多了一个字母。这种问题在编译阶段不会报错运行调试时才会看到调用失败或者返回异常。排查这类问题最快的办法是打印结构体的字节集。先用“取指针到字节集”把16字节数据输出为十六进制文本然后对照SYSTEMTIME的字段顺序人工分析。如果每个WORD按顺序显示说明API调用成功了如果数据变形问题一定出在声明或传参上。5.3 调用频繁是否拖慢程序有些朋友会担心在循环里每次点击或者每次界面刷新都调用GetLocalTime会不会拖慢程序。实际测试下来GetLocalTime是一个很轻量的系统调用单次开销在微秒级别远低于一次“延时 (10)”或者一次界面重绘。正常情况下哪怕你在500毫秒延时循环里每帧调用一次性能影响可以忽略不计。真正该注意的是“频繁取毫秒时间然后写文件”这类组合操作。日志写文件是磁盘IO才是性能瓶颈。如果日志频率很高建议在内存里先缓冲一批日志定时批量写盘而不是每条日志都打开、写入、关闭文件一次。我做过一个模拟按键记录工具运行一小时后生成了几万条日志用的就是批量缓冲方案。启动时创建一个内存列表到了100条或者时间过了1秒就统一写入一次性能稳定日志也不会丢。5.4 需要高精度计时时怎么办再扩展一下如果GetLocalTime的毫秒精度已经不能满足你比如你要测一段代码跑了多少微秒就应该用QueryPerformanceCounter。这是Windows提供的高精度性能计数频率通常与CPU主频相关能达到微秒级甚至纳秒级。在易语言里调用它需要稍微多写几步。QueryPerformanceCounter接受一个LARGE_INTEGER指针这是一个64位结构体。易语言可以用两个整数型字段来定义高32位和低32位分别存放。具体实现我简单给一个思路.版本 2 .数据类型 LARGE_INTEGER 低32位 为 整数型 高32位 为 整数型 .DLL命令 取性能计数, 整数型, kernel32.dll, QueryPerformanceCounter .参数 lpPerformanceCount, 整数型 .DLL命令 取性能频率, 整数型, kernel32.dll, QueryPerformanceFrequency .参数 lpFrequency, 整数型 .子程序 取微秒耗时, 长整数型 .参数 开始计数, LARGE_INTEGER .参数 结束计数, LARGE_INTEGER .局部变量 频率, LARGE_INTEGER .局部变量 差值, 长整数型 取性能频率 (取变量数据地址 (频率)) 差值 (结束计数.高32位 × 4294967296 结束计数.低32位) - (开始计数.高32位 × 4294967296 开始计数.低32位) 返回 (差值 × 1000000 ÷ (频率.高32位 × 4294967296 频率.低32位))这套做法的核心是GetLocalTime给你的是“日历时间的绝对时刻”而QueryPerformanceCounter给你的是“时间间隔的精密刻钟”。两者配合使用既能写出带毫秒的日志时间戳又能精确分析每段操作的开销。做了这么多年易语言我最深的体会是遇到精度不够的问题先别急着怀疑语言不行Windows底层其实提供了足够丰富的API关键是你要知道去哪里找、怎么声明、怎么传参。GetLocalTime这条链路解决的是“带毫秒的当前时间”它不复杂但每一步都有讲究。希望这篇整理能帮你少走几步弯路遇到具体问题的时候也能自己分析出到底是结构体定义错了还是系统时钟精度不够而不是一味地改运气。