WezTerm Lua 配置中的时间模块wezterm.time.now()与Time对象完全指南【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwezterm.time是 WezTerm 在 Lua 配置体系中提供的时间处理模块其中wezterm.time.now()是获取当前时刻快照的入口它返回一个内部以 UTC 追踪的Time对象供后续格式化、解析与按时刻动态调整配置使用。本文以wezterm.time.now()为核心完整覆盖该模块的函数与Time对象的全部方法并结合仓库源码说明其底层实现帮助你写出按时间自动变化的配色、定时刷新配置等实战配置。wezterm.time模块概览wezterm.time模块自版本20220807-113146-c2fee766起随 WezTerm 一起提供它在 Lua 侧暴露了一组与时间打交道的能力获取当前时间、解析时间字符串、格式化时间、以及延时调度回调。模块的完整函数清单见 模块索引包括函数作用wezterm.time.now()返回一个表示当前调用时刻的Time对象wezterm.time.parse(str, format)按给定格式字符串解析时间文本返回Time对象wezterm.time.parse_rfc3339(str)按 RFC 3339 格式解析时间文本返回Time对象wezterm.time.call_after(interval_seconds, function)在指定秒数后调用回调函数这些函数在 Lua 配置文件中通过require wezterm之后即可使用无需额外引入包。wezterm.time.now()获取当前时刻wezterm.time.now()的语义非常简单且直白返回一个 Time 对象该对象表示wezterm.time.now()被调用那一刻的时间。它在配置文件中调用一次就固定住当时的时间不会随着后续时间的流逝而变化因此如果你需要在多个地方使用同一个时间基准例如同时格式化本地时间与 UTC 时间做对比应当先把它保存到一个局部变量中。从源码看该函数在 lua-api-crates/time-funcs/src/lib.rs 中注册其实现直接调用了 Rust 侧的时间来源time_mod.set( now, lua.create_function(|_, _: ()| Ok(Time { utc: Utc::now() }))?, )?;可以看到now()底层就是chronocrate 的Utc::now()返回的Time结构体内部只保存了一个DateTimeUtc字段。这意味着无论你本地时区是什么Time对象内部一律以 UTC 为唯一事实来源本地时间只是在展示/格式化阶段才进行转换。Time对象内部以 UTC 追踪的时刻所有时间函数最终都会产出Time对象。官方文档对它的描述是表示一个内部以 UTC 追踪的日期与时间。Time对象的__tostring元方法被实现为输出其内部 UTC 表示见 time-funcs/src/lib.rsmethods.add_meta_method(MetaMethod::ToString, |_, this, _: ()| { let utc this.utc.to_rfc3339(); Ok(format!(Time(utc: {utc}))) });因此在 Lua 命令行或配置中对Time对象调用tostring()会得到类似下面的输出其中时间部分为内部 UTC 时间与你所在的本地时区可能不同Time(utc: 2022-07-17T18:14:15.00000:00)Time对象提供了三个方法Time:format(format)按格式字符串输出该时刻的本地时间表示Time:format_utc(format)按格式字符串输出该时刻的UTC 时间表示Time:sun_times(lat, lon)根据该时刻的日期与时间分量计算指定经纬度的日出日落信息。格式化Time:format()与Time:format_utc()format使用时刻的本地时区表示进行格式化format_utc则固定使用 UTC 表示。二者对格式字符串的支持范围相同格式占位符体系由底层 chrono crate 的 strftime 风格格式提供常用的%Y、%m、%d、%H、%M、%S等占位符均可直接使用。文档给出的对比示例很直观——同一时刻在 UTC7 时区下的本地格式化与 UTC 格式化相差 7 小时 wezterm.time.now():format(%Y-%m-%d %H:%M:%S) 2022-07-17 11:14:15 wezterm.time.now():format_utc(%Y-%m-%d %H:%M:%S) 2022-07-17 18:14:15注意上面两次调用now()产生的是两个几乎相同但不同的时刻对象实际使用时建议复用同一个Time变量以保证基准一致。从源码看format的实现先把内部 UTC 时间转换为Local再格式化而format_utc直接对内部 UTC 值做格式化见 time-funcs/src/lib.rsmethods.add_method(format, |_, this, format: String| { let local: DateTimeLocal this.utc.into(); Ok(local.format(format).to_string()) }); methods.add_method(format_utc, |_, this, format: String| { Ok(this.utc.format(format).to_string()) });这解释了为什么两者输出不同format多了一次 UTC → 本地时区的转换。日出日落Time:sun_times(lat, lon)sun_times(lat, lon)是wezterm.time模块中最有创意的能力针对Time对象中携带的日期与时间计算给定经纬度的日出rise与日落set时刻并判断当前时间是否处于白天。它返回一个 Lua table包含四个字段rise日出时刻的Time对象UTCset日落时刻的Time对象UTCup布尔值当前时刻太阳是否在地平线以上progression浮点数0.0 ~ 1.0当前时刻在白天up true时或夜晚up false时进程中的进度比例。文档中给出的示例是计算美国凤凰城北纬 33.44西经 112的时刻信息 wezterm.time.now():sun_times(33.44, -112) { progression: 0.41843971631205673, rise: Time(utc: 2022-07-17T12:29:42.49344968700:00), set: Time(utc: 2022-07-18T02:36:40.77624773900:00), up: true, }这个结果表示当时太阳正处于白昼且已经走过了白天时长的约 41%progression ≈ 0.418。如果调用时太阳已落山则up false此时progression表示夜间时长的进度比例。源码中progression的计算逻辑很清晰见 time-funcs/src/lib.rs以rise与set之间为白天时长、其余为夜间时长把当前时刻在对应区段内的位置按分钟折算成比例。日出前、白天、日落后三种情况分别计算。还有一个特殊的边界情况如果经纬度位于两极可能出现白昼或黑夜连续超过 24 小时。此时rise与set均为nilprogression为0up直接表示处于极昼true还是极夜false。这一分支在源码中对应spa::calc_sunrise_and_set返回的PolarDay/PolarNight枚举见 time-funcs/src/lib.rs。官方文档特别点明了该方法的用途如果你希望根据一天中的时段变化来切换配色方案或其他配置sun_times提供的信息正是为此设计的——不需要硬编码日落日出时刻而是让 WezTerm 根据地理坐标自动计算。与其他时间函数的配合使用虽然now()是最常用的入口但wezterm.time模块的价值在于整套函数可以互相配合。理解它们有助于你把now()用得更顺手。解析时间字符串wezterm.time.parse(str, format) 按照显式给定的格式字符串解析时间文本。文档示例 wezterm.time.parse(1983 Apr 13 12:09:14.274 0000, %Y %b %d %H:%M:%S%.3f %z) Time(utc: 1983-04-13T12:09:14.27400:00)这里%b是英文月份缩写%.3f是毫秒级小数秒%z是时区偏移。格式字符串支持 chrono crate 的 strftime 风格占位符体系。其源码实现见 time-funcs/src/lib.rs先调用DateTime::parse_from_str成功后再把解析结果统一转换为内部 UTC 存储。wezterm.time.parse_rfc3339(str) 则直接按 RFC 3339 时间格式解析例如2022-07-17T18:14:1500:00这类带时区偏移的 ISO 风格字符串。如果输入字符串无法按 RFC 3339 解析会直接抛出 Lua 错误源码见 time-funcs/src/lib.rs。parse与parse_rfc3339都返回标准的Time对象因此解析结果同样可以调用format、format_utc、sun_times等方法实现了任意来源的时间 → 统一Time对象的设计。定时调度wezterm.time.call_after()wezterm.time.call_after(interval_seconds, function) 用于在指定秒数之后调用回调函数常与now()搭配实现周期性刷新配置。自版本20230320-124340-559cb7b0起interval_seconds支持小数秒可以进行更精确的延时。官方文档给出的经典示例是根据当前时刻是小时内的第几分钟动态生成背景色并借助call_after每分钟刷新一次配置local wezterm require wezterm -- Reload the configuration every minute wezterm.time.call_after(60, function() wezterm.reload_configuration() end) local amount math.ceil((tonumber(wezterm.time.now():format %M) / 60) * 255) return { colors { background rgb( .. amount .. , .. amount .. , .. amount .. ), }, }这段配置的工作流程是配置文件加载时调用一次now()取出当前分钟数%M0~59映射到 0~255 得到灰度值作为背景色写入colors.background同时用call_after(60, ...)安排一个 60 秒后的回调回调里调用 wezterm.reload_configuration() 让配置重新加载从而在下一次加载时得到新的分钟数——如此循环往复实现背景色每分钟变化一次。需要特别注意的是官方文档在该示例后附了一段明确的警告能力越大责任越大。如果你调度了大量频繁的回调或者频繁地这样重载配置会增加系统 CPU 负载因为这是让计算机做更多的工作。此外wezterm.reload_configuration() 的文档还强调如果在配置文件的顶层文件作用域直接调用它会造成无限循环使 WezTerm 失去响应它应当只在事件或定时器回调中使用。从源码层面看call_after的实现要复杂得多见 time-funcs/src/lib.rs回调会被包装为事件 ID与延时一起封装成ScheduledEvent通过 promise 运行时调度在配置重载时WezTerm 会把所有已注册的定时事件用配置代数generation标记当定时器到期后如果当前配置代数与注册时不一致就跳过执行从而避免配置重载导致回调按 2 倍、4 倍指数级重复累积见 time-funcs/src/lib.rs 的注释与实现。这一机制保证了定时刷新配置模式在实际高频重载下是安全且受控的。实战按昼夜自动切换配色方案综合以上 API一个实用的落地场景是用sun_times判断当前是否处于白天再决定采用亮色还是暗色配色同时用call_after定时重载配置以保证配色随日出日落自动切换。示例框架如下local wezterm require wezterm -- 每 5 分钟检查一次让昼夜切换及时生效 wezterm.time.call_after(300, function() wezterm.reload_configuration() end) local t wezterm.time.now() -- 以北京为例北纬 39.9东经 116.4 local sun t:sun_times(39.9, 116.4) local scheme if sun.up then scheme One Light -- 白天用亮色 else scheme One Dark -- 夜晚用暗色 end return { color_scheme scheme, }说明几点sun_times的经纬度请按你自己的实际位置填写数值可参考公开的地理坐标资料定时器间隔请根据你对切换及时性与CPU 开销的权衡设置官方建议不要过于频繁该方案完全由 WezTerm 自身计算日出日落无需依赖外部服务或硬编码昼夜时刻。如果你想按分钟粒度而不是昼夜粒度做更细的动态调整now():format %M这类分钟提取手法配合 Time:format()就是官方示例所展示的路径。小结wezterm.time.now()看似只是一个取时间的函数但它是整个wezterm.time模块的起点它产出的Time对象内部以 UTC 为准统一支撑本地/UTC 两种格式化输出也能直接参与日出日落计算与parse/parse_rfc3339把外部时间文本纳入同一体系以及call_after定时驱动配置重载组合就构成了 WezTerm 配置随时间变化的完整能力闭环。底层实现集中在 lua-api-crates/time-funcs/src/lib.rs其UTC 存储 展示时转换和配置代数防重复调度两个设计细节值得在阅读源码时重点关注。相关函数的完整说明与更多示例可继续查阅 wezterm.time 模块索引。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考