`)
WezTerm Lua 配置时间格式化深入解析wezterm.time与Time:format()【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读在 WezTerm 的 Lua 配置体系中wezterm.time模块提供了处理时间对象的能力其中Time:format()与Time:format_utc()用于将时间对象按指定格式串格式化为字符串是状态栏时钟、日志时间戳、定时任务输出等场景的基础工具。本文以官方文档 docs/config/lua/wezterm.time/Time/format.md 为骨架结合仓库内 time-funcs 模块源码 的实现细节系统讲解时间对象的创建、格式化占位符语法、本地时区与 UTC 的差异以及相关解析方法的完整用法帮助你写出准确、可维护的时间格式化配置。一、wezterm.time模块与Time对象wezterm.time模块自版本20220807-113146-c2fee766起随 WezTerm 提供用于在 Lua 配置中操作时间。模块的可用函数在官方索引 docs/config/lua/wezterm.time/index.markdown 中列出主要包括函数作用wezterm.time.now()返回调用时刻对应的Time对象wezterm.time.parse(str, format)按指定格式串解析字符串返回Time对象wezterm.time.parse_rfc3339(str)按 RFC 3339 规范解析字符串返回Time对象wezterm.time.call_after(interval, func)延迟指定秒数后执行回调定时任务Time对象详见 docs/config/lua/wezterm.time/Time/index.markdown内部始终以 UTC 方式跟踪一个日期时间点。这意味着无论你的系统位于哪个时区Time对象内部存储的都是同一个绝对时刻只有当你把它格式化为字符串时才会涉及时区换算。对Time对象执行tostring()会直接显示其内部记录的 UTC 时间。从源码 lua-api-crates/time-funcs/src/lib.rs 可以看到该结构体的定义#[derive(Clone, Debug)] pub struct Time { utc: DateTimeUtc, }它基于 Rust 生态的chronocrate内部字段utc的类型是DateTimeUtc。理解了内部 UTC、外部按需换算时区这一设计就很容易理解接下来format与format_utc两个方法的差异。二、Time:format(format)按本地时区格式化Time:format(format)是Time对象的核心方法其作用是使用当前系统的本地时区local date/time表示将时间对象格式化为字符串。官方文档给出如下示例 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对比同一时刻的两个输出可以直观看到假设示例执行时系统处于 UTC7 时区18:14:15 减去 11:14:15format输出的11:14:15是换算成本地时区后的时间而format_utc输出的18:14:15是 UTC 原始时间。两者内部是同一个绝对时刻只是显示时区不同。源码级实现验证在 lua-api-crates/time-funcs/src/lib.rs 中两个方法的实现如下methods.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内部先把内部存储的DateTimeUtc通过Into转换成本地时区的DateTimeLocal再调用 chrono 的format渲染字符串——这就是使用本地时区表示的底层来源format_utc则直接对this.utc即DateTimeUtc调用format不做任何时区转换。两个方法都会把格式串原样传给 chrono crate 的formatAPI。若格式串中有无法解析的占位符chrono 会将其按字面文本输出不会抛出运行时错误这一点在实际配置排查时值得注意。三、格式化占位符语法chrono strftime 风格format与format_utc的格式串均支持与 Rust chrono crate 的 strftime 风格一致的占位符集合官方文档标注为 chrono 的chrono/format/strftime占位符。下面结合官方示例与常见配置需求列出最常用的占位符及含义占位符含义示例输出%Y四位数的年份2022%m两位数的月份01–1207%d两位数的日期01–3117%H24 小时制的小时00–2311%M分钟00–5914%S秒00–5915%b缩写的月份名称Apr%B完整的月份名称April%Y之外的%y两位数的年份22%z与 UTC 的时区偏移0000%Z时区名称UTC%.3f小数秒3 位精度毫秒274%a缩写的星期名称Sat%A完整的星期名称Saturday%j一年中的第几天001–366198%s自 Unix 纪元以来的秒数1658049255需要说明上表是 POSIX strftime 与 chrono 兼容占位符的标准含义官方文档明确格式串支持 chrono crate strftime 占位符集合在parse中同样适用。你也可以自由组合字面字符与占位符例如%Y-%m-%d %H:%M:%S中的连字符、空格、冒号都会原样出现在输出中。毫秒与时间戳的实践若需要在状态栏或日志中显示毫秒精度可组合%.3fwezterm.time.now():format(%H:%M:%S%.3f) -- 例如输出 11:14:15.274若要记录绝对时间戳便于脚本比较或排序可使用%swezterm.time.now():format(%s)四、本地时区与 UTCformatvsformat_utc官方文档在 format.md 与 format_utc.md 中互为引用二者区别总结如下方法时区语义适用场景Time:format(format)将内部 UTC 时刻换算为系统本地时区后格式化状态栏显示本地时间、面向用户的输出Time:format_utc(format)直接以内部 UTC 时刻格式化日志统一记录、跨时区协作、时间戳排序两个方法签名相同均接受一个格式串字符串返回格式化后的字符串。用sun_times进一步利用时区语义Time对象还提供了sun_times(latitude, longitude)方法见 Time/index.markdown可依据地理坐标计算日出日落local t wezterm.time.now():sun_times(31.2304, 121.4737) -- 返回包含 rise / set / up / progression 字段的 table其中up表示此刻太阳是否在地平线之上progression表示昼夜进程的归一化进度0.0–1.0。从源码 lib.rs 可以看到其内部基于内部 UTC 时刻与传入经纬度调用spa::calc_sunrise_and_set计算并在极昼/极夜时分别返回特殊状态。这常被用于编写白天/夜晚主题自动切换配置。五、创建时间对象now、parse与parse_rfc33391.wezterm.time.now()返回调用时刻对应的Time对象docs/config/lua/wezterm.time/now.md。注意它捕获的是调用时刻而不是求值时的字符串因此适合用于计算时间差或作为format的输入。源码实现为time_mod.set(now, lua.create_function(|_, _: ()| Ok(Time { utc: Utc::now() }))?);2.wezterm.time.parse(str, format)按给定的格式串解析字符串得到Time对象docs/config/lua/wezterm.time/parse.md 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缩写月份也包含%z时区偏移说明格式串必须与输入字符串的每一段精确对应若格式串无法完整匹配输入parse会抛出错误。源码实现使用DateTime::parse_from_str并将解析结果转换为内部 UTC 存储lib.rs。3.wezterm.time.parse_rfc3339(str)按 RFC 3339ISO 8601 的互联网配置文件解析字符串如1983-04-13T12:09:14.27400:00docs/config/lua/wezterm.time/parse_rfc3339.md。这是解析标准时间戳例如配置文件、API 响应中的时间字段最可靠的方式若输入不符合 RFC 3339 语法函数会直接抛出错误。源码中通过DateTime::parse_from_rfc3339实现lib.rs。4. 定时任务wezterm.time.call_after(interval, func)call_after接收以秒为单位的浮点数间隔与回调函数在延迟后执行docs/config/lua/wezterm.time/call_after.md。从源码看它会把回调包装进 registry并记录配置代数generation当配置被重新加载后旧代数的定时回调会被跳过执行避免配置热重载导致回调重复累积lib.rs 与 lib.rs 中的schedule/run逻辑。可结合now()在回调中记录精确触发时刻。六、综合实战在状态栏显示本地时间与 UTC 时间format最常见的用途是在update-right-status事件中渲染状态栏时钟。以下配置展示如何同时输出本地时间与 UTC 时间以 2022-07-17 时刻为例假设系统为 UTC7local wezterm require(wezterm) wezterm.on(update-right-status, function(window, pane) local now wezterm.time.now() -- 本地时区时间 local local_time now:format(%Y-%m-%d %H:%M:%S) -- UTC 时间 local utc_time now:format_utc(%Y-%m-%d %H:%M:%S) -- 简洁的时钟显示仅本地时间 local clock now:format(%a %H:%M) window:set_right_status(wezterm.format({ { Text 本地 .. local_time .. UTC .. utc_time }, })) end) return {}执行效果等价于官方文档示例中的对比 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若希望在状态栏中体现昼夜状态可扩展使用sun_timeslocal s wezterm.time.now():sun_times(31.2304, 121.4737) if s.up then -- 白天使用浅色主题相关显示 end七、版本可用性与其他注意事项wezterm.time模块及其全部函数含Time:format自版本20220807-113146-c2fee766起可用配置前请确认 WezTerm 版本不低于该版本。format输出的时区取决于运行 WezTerm 进程时系统的本地时区设置如TZ环境变量而非终端内 shell 的时区同一台机器上不同TZ启动的实例会得到不同本地时间输出。格式串对占位符的识别遵循 chrono 的 strftime 规则如需在输出中包含%字面字符应使用转义方式处理具体可参考 chrono 的转义约定避免被误解析为占位符。对于需要跨机器、跨时区保持一致的日志时间推荐始终使用format_utc或%sUnix 时间戳而非format。延伸阅读模块总览docs/config/lua/wezterm.time/index.markdown时间对象docs/config/lua/wezterm.time/Time/index.markdownUTC 格式化docs/config/lua/wezterm.time/Time/format_utc.md获取当前时间docs/config/lua/wezterm.time/now.md解析时间字符串docs/config/lua/wezterm.time/parse.md、docs/config/lua/wezterm.time/parse_rfc3339.md定时任务docs/config/lua/wezterm.time/call_after.md源码实现lua-api-crates/time-funcs/src/lib.rs【免费下载链接】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），仅供参考
WezTerm Lua 配置时间格式化：深入解析 `wezterm.time` 与 `Time:format()`
WezTerm Lua 配置时间格式化深入解析wezterm.time与Time:format()【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm导读在 WezTerm 的 Lua 配置体系中wezterm.time模块提供了处理时间对象的能力其中Time:format()与Time:format_utc()用于将时间对象按指定格式串格式化为字符串是状态栏时钟、日志时间戳、定时任务输出等场景的基础工具。本文以官方文档 docs/config/lua/wezterm.time/Time/format.md 为骨架结合仓库内 time-funcs 模块源码 的实现细节系统讲解时间对象的创建、格式化占位符语法、本地时区与 UTC 的差异以及相关解析方法的完整用法帮助你写出准确、可维护的时间格式化配置。一、wezterm.time模块与Time对象wezterm.time模块自版本20220807-113146-c2fee766起随 WezTerm 提供用于在 Lua 配置中操作时间。模块的可用函数在官方索引 docs/config/lua/wezterm.time/index.markdown 中列出主要包括函数作用wezterm.time.now()返回调用时刻对应的Time对象wezterm.time.parse(str, format)按指定格式串解析字符串返回Time对象wezterm.time.parse_rfc3339(str)按 RFC 3339 规范解析字符串返回Time对象wezterm.time.call_after(interval, func)延迟指定秒数后执行回调定时任务Time对象详见 docs/config/lua/wezterm.time/Time/index.markdown内部始终以 UTC 方式跟踪一个日期时间点。这意味着无论你的系统位于哪个时区Time对象内部存储的都是同一个绝对时刻只有当你把它格式化为字符串时才会涉及时区换算。对Time对象执行tostring()会直接显示其内部记录的 UTC 时间。从源码 lua-api-crates/time-funcs/src/lib.rs 可以看到该结构体的定义#[derive(Clone, Debug)] pub struct Time { utc: DateTimeUtc, }它基于 Rust 生态的chronocrate内部字段utc的类型是DateTimeUtc。理解了内部 UTC、外部按需换算时区这一设计就很容易理解接下来format与format_utc两个方法的差异。二、Time:format(format)按本地时区格式化Time:format(format)是Time对象的核心方法其作用是使用当前系统的本地时区local date/time表示将时间对象格式化为字符串。官方文档给出如下示例 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对比同一时刻的两个输出可以直观看到假设示例执行时系统处于 UTC7 时区18:14:15 减去 11:14:15format输出的11:14:15是换算成本地时区后的时间而format_utc输出的18:14:15是 UTC 原始时间。两者内部是同一个绝对时刻只是显示时区不同。源码级实现验证在 lua-api-crates/time-funcs/src/lib.rs 中两个方法的实现如下methods.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内部先把内部存储的DateTimeUtc通过Into转换成本地时区的DateTimeLocal再调用 chrono 的format渲染字符串——这就是使用本地时区表示的底层来源format_utc则直接对this.utc即DateTimeUtc调用format不做任何时区转换。两个方法都会把格式串原样传给 chrono crate 的formatAPI。若格式串中有无法解析的占位符chrono 会将其按字面文本输出不会抛出运行时错误这一点在实际配置排查时值得注意。三、格式化占位符语法chrono strftime 风格format与format_utc的格式串均支持与 Rust chrono crate 的 strftime 风格一致的占位符集合官方文档标注为 chrono 的chrono/format/strftime占位符。下面结合官方示例与常见配置需求列出最常用的占位符及含义占位符含义示例输出%Y四位数的年份2022%m两位数的月份01–1207%d两位数的日期01–3117%H24 小时制的小时00–2311%M分钟00–5914%S秒00–5915%b缩写的月份名称Apr%B完整的月份名称April%Y之外的%y两位数的年份22%z与 UTC 的时区偏移0000%Z时区名称UTC%.3f小数秒3 位精度毫秒274%a缩写的星期名称Sat%A完整的星期名称Saturday%j一年中的第几天001–366198%s自 Unix 纪元以来的秒数1658049255需要说明上表是 POSIX strftime 与 chrono 兼容占位符的标准含义官方文档明确格式串支持 chrono crate strftime 占位符集合在parse中同样适用。你也可以自由组合字面字符与占位符例如%Y-%m-%d %H:%M:%S中的连字符、空格、冒号都会原样出现在输出中。毫秒与时间戳的实践若需要在状态栏或日志中显示毫秒精度可组合%.3fwezterm.time.now():format(%H:%M:%S%.3f) -- 例如输出 11:14:15.274若要记录绝对时间戳便于脚本比较或排序可使用%swezterm.time.now():format(%s)四、本地时区与 UTCformatvsformat_utc官方文档在 format.md 与 format_utc.md 中互为引用二者区别总结如下方法时区语义适用场景Time:format(format)将内部 UTC 时刻换算为系统本地时区后格式化状态栏显示本地时间、面向用户的输出Time:format_utc(format)直接以内部 UTC 时刻格式化日志统一记录、跨时区协作、时间戳排序两个方法签名相同均接受一个格式串字符串返回格式化后的字符串。用sun_times进一步利用时区语义Time对象还提供了sun_times(latitude, longitude)方法见 Time/index.markdown可依据地理坐标计算日出日落local t wezterm.time.now():sun_times(31.2304, 121.4737) -- 返回包含 rise / set / up / progression 字段的 table其中up表示此刻太阳是否在地平线之上progression表示昼夜进程的归一化进度0.0–1.0。从源码 lib.rs 可以看到其内部基于内部 UTC 时刻与传入经纬度调用spa::calc_sunrise_and_set计算并在极昼/极夜时分别返回特殊状态。这常被用于编写白天/夜晚主题自动切换配置。五、创建时间对象now、parse与parse_rfc33391.wezterm.time.now()返回调用时刻对应的Time对象docs/config/lua/wezterm.time/now.md。注意它捕获的是调用时刻而不是求值时的字符串因此适合用于计算时间差或作为format的输入。源码实现为time_mod.set(now, lua.create_function(|_, _: ()| Ok(Time { utc: Utc::now() }))?);2.wezterm.time.parse(str, format)按给定的格式串解析字符串得到Time对象docs/config/lua/wezterm.time/parse.md 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缩写月份也包含%z时区偏移说明格式串必须与输入字符串的每一段精确对应若格式串无法完整匹配输入parse会抛出错误。源码实现使用DateTime::parse_from_str并将解析结果转换为内部 UTC 存储lib.rs。3.wezterm.time.parse_rfc3339(str)按 RFC 3339ISO 8601 的互联网配置文件解析字符串如1983-04-13T12:09:14.27400:00docs/config/lua/wezterm.time/parse_rfc3339.md。这是解析标准时间戳例如配置文件、API 响应中的时间字段最可靠的方式若输入不符合 RFC 3339 语法函数会直接抛出错误。源码中通过DateTime::parse_from_rfc3339实现lib.rs。4. 定时任务wezterm.time.call_after(interval, func)call_after接收以秒为单位的浮点数间隔与回调函数在延迟后执行docs/config/lua/wezterm.time/call_after.md。从源码看它会把回调包装进 registry并记录配置代数generation当配置被重新加载后旧代数的定时回调会被跳过执行避免配置热重载导致回调重复累积lib.rs 与 lib.rs 中的schedule/run逻辑。可结合now()在回调中记录精确触发时刻。六、综合实战在状态栏显示本地时间与 UTC 时间format最常见的用途是在update-right-status事件中渲染状态栏时钟。以下配置展示如何同时输出本地时间与 UTC 时间以 2022-07-17 时刻为例假设系统为 UTC7local wezterm require(wezterm) wezterm.on(update-right-status, function(window, pane) local now wezterm.time.now() -- 本地时区时间 local local_time now:format(%Y-%m-%d %H:%M:%S) -- UTC 时间 local utc_time now:format_utc(%Y-%m-%d %H:%M:%S) -- 简洁的时钟显示仅本地时间 local clock now:format(%a %H:%M) window:set_right_status(wezterm.format({ { Text 本地 .. local_time .. UTC .. utc_time }, })) end) return {}执行效果等价于官方文档示例中的对比 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若希望在状态栏中体现昼夜状态可扩展使用sun_timeslocal s wezterm.time.now():sun_times(31.2304, 121.4737) if s.up then -- 白天使用浅色主题相关显示 end七、版本可用性与其他注意事项wezterm.time模块及其全部函数含Time:format自版本20220807-113146-c2fee766起可用配置前请确认 WezTerm 版本不低于该版本。format输出的时区取决于运行 WezTerm 进程时系统的本地时区设置如TZ环境变量而非终端内 shell 的时区同一台机器上不同TZ启动的实例会得到不同本地时间输出。格式串对占位符的识别遵循 chrono 的 strftime 规则如需在输出中包含%字面字符应使用转义方式处理具体可参考 chrono 的转义约定避免被误解析为占位符。对于需要跨机器、跨时区保持一致的日志时间推荐始终使用format_utc或%sUnix 时间戳而非format。延伸阅读模块总览docs/config/lua/wezterm.time/index.markdown时间对象docs/config/lua/wezterm.time/Time/index.markdownUTC 格式化docs/config/lua/wezterm.time/Time/format_utc.md获取当前时间docs/config/lua/wezterm.time/now.md解析时间字符串docs/config/lua/wezterm.time/parse.md、docs/config/lua/wezterm.time/parse_rfc3339.md定时任务docs/config/lua/wezterm.time/call_after.md源码实现lua-api-crates/time-funcs/src/lib.rs【免费下载链接】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），仅供参考