` 时间格式化方法)
WezTerm Lua API深入解析Time:format_utc()时间格式化方法【免费下载链接】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 API 中wezterm.time模块的Time:format_utc(format)方法讲解如何将Time时间对象按指定格式字符串输出为UTC协调世界时表示的时间文本。文中将结合 format_utc.md 原文档 的说明与 time-funcs 源码 的真实实现对比format()与format_utc()的时区差异并给出可在状态栏、Tab 标题等场景直接落地的 Lua 配置示例。读完本文你将掌握 WezTerm 中时间格式化占位符的完整用法以及如何在自己 的wezterm.lua配置里输出任意时区语义的时间字符串。方法签名与返回值Time:format_utc(format)将Time对象格式化为字符串返回值为 UTC 日期/时间表示。Time:format_utc(format: string) - string该方法自版本20220807-113146-c2fee766起可用见 format_utc.md。参数format是一个格式字符串支持 chrono 库 strftime 格式化占位符集。官方文档给出的最小示例交互式 Lua REPL wezterm.time.now():format_utc(%Y-%m-%d %H:%M:%S) 2022-07-17 18:14:15wezterm.time.now()返回一个表示调用时刻的 Time 对象随后通过:format_utc()按%Y-%m-%d %H:%M:%S输出为年-月-日 时:分:秒的标准文本。内部机制Time 对象天然以 UTC 存储要理解format_utc()首先需要了解Time对象的数据模型。根据 Time/index.markdown 文档 的说明Represents a date and time that is tracked internally as UTC——即Time对象内部始终以 UTC 时刻存储不携带任何本地时区信息。这一设计在源码中得到直接印证。在 time-funcs/src/lib.rs 中Time结构体的定义只有一个字段#[derive(Clone, Debug)] pub struct Time { utc: DateTimeUtc, }Time对象所依赖的 chrono crate 通过 workspace 统一引入见 time-funcs/Cargo.toml 中的chrono.workspace true。format_utc的实现极其直接——它不做任何时区换算直接把内部 UTC 时刻按格式串渲染methods.add_method(format_utc, |_, this, format: String| { Ok(this.utc.format(format).to_string()) });对应代码位于 time-funcs/src/lib.rs。此外对Time对象调用tostring()也会显示其内部追踪的 UTC 信息例如来自 parse.md 的示例输出Time(utc: 1983-04-13T12:09:14.27400:00)这正是对Time实现MetaMethod::ToString后的结果见 time-funcs/src/lib.rs。format_utc()与format()时区语义的差异Time对象同时提供了两个格式化方法其区别仅在于渲染时使用的时区方法渲染时区说明Time:format(format)本地时区Local先把内部 UTC 时刻换算成系统本地时间再格式化Time:format_utc(format)UTC协调世界时直接对内部 UTC 时刻格式化不做任何换算format()的源码实现印证了这一差异见 time-funcs/src/lib.rsmethods.add_method(format, |_, this, format: String| { let local: DateTimeLocal this.utc.into(); Ok(local.format(format).to_string()) });可以看到format()会先将内部DateTimeUtc通过IntoDateTimeLocal转换为本地时间。同一个Time对象两个方法在非 UTC 时区下会输出不同的时刻文本。官方文档同时给出了两者的对比示例UTC7 时区下 wezterm.time.now():format_utc(%Y-%m-%d %H:%M:%S) 2022-07-17 18:14:15 wezterm.time.now():format(%Y-%m-%d %H:%M:%S) 2022-07-17 11:14:15同一时刻format_utc()输出18:14:15UTCformat()输出11:14:15本地时间两者相差正好 7 小时。类似的对比同样出现在 format.md 文档 中。因此在配置中选择哪个方法取决于你想要的语义日志、时间戳等需要跨机器一致的场景用format_utc()面向用户展示当前时间时用format()。格式字符串chrono strftime 占位符速查format参数直接透传给 chrono 的DateTime::format因此支持的占位符与 Rust chrono crate 的 strftime 格式集完全一致。以下为高频占位符速查表占位符含义示例输出%Y四位年份2022%y两位年份22%m两位月份01-1207%b缩写月份名Jul%B完整月份名July%d两位日01-3117%e空格填充的日1-317%a缩写星期名Sun%A完整星期名Sunday%H24 小时制小时00-2318%I12 小时制小时01-1206%M分钟00-5914%S秒00-5915%f小数秒纳秒精度026490000%.f小数秒去掉末尾零.026490%3f/%6f/%9f固定位数小数秒毫秒/微秒/纳秒%pAM/PM 指示PM%z时区偏移hhmm0000%Z时区名称UTC%j年内第几天001-366198%U/%W年内周数以周日/周一为周首28%sUnix 时间戳自 1970-01-01 的秒数1657994855%%字面量百分号%注上表占位符行为源自 chrono crate 的 strftime 格式化规则具体到某一位占位符的完整边界语义如%U/%W的周起始约定、%f的精度行为建议以 chrono 官方 strftime 文档为准。这些占位符可以自由组合例如%Y-%m-%dT%H:%M:%S%.f%z即可输出近似 RFC 3339 风格的时间戳若想要严格符合 RFC 3339 的时间文本也可以直接使用 wezterm.time.parse_rfc3339() 的逆过程思路来校验格式。实战在状态栏与 Tab 标题中输出 UTC 时间format_utc()最常见的落地场景是在wezterm.lua配置中输出时间文本。以下是一个可直接粘贴使用的配置片段——在右侧状态栏区域显示 UTC 时间local wezterm require(wezterm) wezterm.on(update-right-status, function(window, pane) -- now() 返回当前时刻的 Time 对象 local time wezterm.time.now() -- 用 UTC 语义格式化避免本地时区干扰 window:set_right_status(UTC: .. time:format_utc(%Y-%m-%d %H:%M:%S)) end) return {}也可以把它用在 Tab 标题等需要稳定时间戳的界面元素上local wezterm require(wezterm) wezterm.on(format-tab-title, function(tab, tabs, panes, config, hover, max_width) local now wezterm.time.now():format_utc(%H:%M:%S) return tab .. tab.tab_index 1 .. [ .. now .. ] end) return {}需要强调的一个易错点由于format_utc()不做本地时区换算同一个时刻在不同时区的机器上运行format_utc()的输出是绝对一致的而format()的输出会随系统时区变化。如果你的场景是给用户看本地现在几点请用format()如果是记录一个可跨机器对比的时间戳请用format_utc()。与wezterm.time模块其他函数的协同format_utc()作为Time对象的方法通常与wezterm.time模块中的以下函数搭配使用wezterm.time.now()返回当前时刻的 Time 对象是获取Time对象的入口之一。wezterm.time.parse(str, format)按格式串反向解析字符串为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)。解析出的对象同样可以调用:format_utc()重新渲染成任意格式。wezterm.time.parse_rfc3339(str)解析 RFC 3339 格式字符串为Time对象见 parse_rfc3339.md解析失败会抛错。wezterm.time.call_after延迟执行回调见 call_after.md可在回调里用now():format_utc()生成定时刷新状态的日志时间戳。此外模块还提供了两个旧版兼容函数wezterm.strftime与wezterm.strftime_utc见 time-funcs/src/lib.rs。其中strftime_utc的实现思路与Time:format_utc完全一致——Utc::now()后直接按格式串渲染但它是模块级函数而非Time对象方法无法对任意历史时刻格式化新配置建议统一使用Time对象方法。版本与注意事项小结版本要求format_utc()与wezterm.time模块整体一样自20220807-113146-c2fee766版本引入更早版本无法使用。返回字符串方法始终返回字符串不做任何时区换算内部存储始终为 UTC。无效格式串chrono 在遇到未知占位符时按字面量输出该字符不会抛错因此格式串写错时表现为输出与预期不符调试时注意核对占位符拼写。时区判断需要绝对时间戳选format_utc()需要本地展示时间选format()二者输出差异即为系统时区与 UTC 的偏移。【免费下载链接】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 API深入解析Time:format_utc()时间格式化方法【免费下载链接】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 API 中wezterm.time模块的Time:format_utc(format)方法讲解如何将Time时间对象按指定格式字符串输出为UTC协调世界时表示的时间文本。文中将结合 format_utc.md 原文档 的说明与 time-funcs 源码 的真实实现对比format()与format_utc()的时区差异并给出可在状态栏、Tab 标题等场景直接落地的 Lua 配置示例。读完本文你将掌握 WezTerm 中时间格式化占位符的完整用法以及如何在自己 的wezterm.lua配置里输出任意时区语义的时间字符串。方法签名与返回值Time:format_utc(format)将Time对象格式化为字符串返回值为 UTC 日期/时间表示。Time:format_utc(format: string) - string该方法自版本20220807-113146-c2fee766起可用见 format_utc.md。参数format是一个格式字符串支持 chrono 库 strftime 格式化占位符集。官方文档给出的最小示例交互式 Lua REPL wezterm.time.now():format_utc(%Y-%m-%d %H:%M:%S) 2022-07-17 18:14:15wezterm.time.now()返回一个表示调用时刻的 Time 对象随后通过:format_utc()按%Y-%m-%d %H:%M:%S输出为年-月-日 时:分:秒的标准文本。内部机制Time 对象天然以 UTC 存储要理解format_utc()首先需要了解Time对象的数据模型。根据 Time/index.markdown 文档 的说明Represents a date and time that is tracked internally as UTC——即Time对象内部始终以 UTC 时刻存储不携带任何本地时区信息。这一设计在源码中得到直接印证。在 time-funcs/src/lib.rs 中Time结构体的定义只有一个字段#[derive(Clone, Debug)] pub struct Time { utc: DateTimeUtc, }Time对象所依赖的 chrono crate 通过 workspace 统一引入见 time-funcs/Cargo.toml 中的chrono.workspace true。format_utc的实现极其直接——它不做任何时区换算直接把内部 UTC 时刻按格式串渲染methods.add_method(format_utc, |_, this, format: String| { Ok(this.utc.format(format).to_string()) });对应代码位于 time-funcs/src/lib.rs。此外对Time对象调用tostring()也会显示其内部追踪的 UTC 信息例如来自 parse.md 的示例输出Time(utc: 1983-04-13T12:09:14.27400:00)这正是对Time实现MetaMethod::ToString后的结果见 time-funcs/src/lib.rs。format_utc()与format()时区语义的差异Time对象同时提供了两个格式化方法其区别仅在于渲染时使用的时区方法渲染时区说明Time:format(format)本地时区Local先把内部 UTC 时刻换算成系统本地时间再格式化Time:format_utc(format)UTC协调世界时直接对内部 UTC 时刻格式化不做任何换算format()的源码实现印证了这一差异见 time-funcs/src/lib.rsmethods.add_method(format, |_, this, format: String| { let local: DateTimeLocal this.utc.into(); Ok(local.format(format).to_string()) });可以看到format()会先将内部DateTimeUtc通过IntoDateTimeLocal转换为本地时间。同一个Time对象两个方法在非 UTC 时区下会输出不同的时刻文本。官方文档同时给出了两者的对比示例UTC7 时区下 wezterm.time.now():format_utc(%Y-%m-%d %H:%M:%S) 2022-07-17 18:14:15 wezterm.time.now():format(%Y-%m-%d %H:%M:%S) 2022-07-17 11:14:15同一时刻format_utc()输出18:14:15UTCformat()输出11:14:15本地时间两者相差正好 7 小时。类似的对比同样出现在 format.md 文档 中。因此在配置中选择哪个方法取决于你想要的语义日志、时间戳等需要跨机器一致的场景用format_utc()面向用户展示当前时间时用format()。格式字符串chrono strftime 占位符速查format参数直接透传给 chrono 的DateTime::format因此支持的占位符与 Rust chrono crate 的 strftime 格式集完全一致。以下为高频占位符速查表占位符含义示例输出%Y四位年份2022%y两位年份22%m两位月份01-1207%b缩写月份名Jul%B完整月份名July%d两位日01-3117%e空格填充的日1-317%a缩写星期名Sun%A完整星期名Sunday%H24 小时制小时00-2318%I12 小时制小时01-1206%M分钟00-5914%S秒00-5915%f小数秒纳秒精度026490000%.f小数秒去掉末尾零.026490%3f/%6f/%9f固定位数小数秒毫秒/微秒/纳秒%pAM/PM 指示PM%z时区偏移hhmm0000%Z时区名称UTC%j年内第几天001-366198%U/%W年内周数以周日/周一为周首28%sUnix 时间戳自 1970-01-01 的秒数1657994855%%字面量百分号%注上表占位符行为源自 chrono crate 的 strftime 格式化规则具体到某一位占位符的完整边界语义如%U/%W的周起始约定、%f的精度行为建议以 chrono 官方 strftime 文档为准。这些占位符可以自由组合例如%Y-%m-%dT%H:%M:%S%.f%z即可输出近似 RFC 3339 风格的时间戳若想要严格符合 RFC 3339 的时间文本也可以直接使用 wezterm.time.parse_rfc3339() 的逆过程思路来校验格式。实战在状态栏与 Tab 标题中输出 UTC 时间format_utc()最常见的落地场景是在wezterm.lua配置中输出时间文本。以下是一个可直接粘贴使用的配置片段——在右侧状态栏区域显示 UTC 时间local wezterm require(wezterm) wezterm.on(update-right-status, function(window, pane) -- now() 返回当前时刻的 Time 对象 local time wezterm.time.now() -- 用 UTC 语义格式化避免本地时区干扰 window:set_right_status(UTC: .. time:format_utc(%Y-%m-%d %H:%M:%S)) end) return {}也可以把它用在 Tab 标题等需要稳定时间戳的界面元素上local wezterm require(wezterm) wezterm.on(format-tab-title, function(tab, tabs, panes, config, hover, max_width) local now wezterm.time.now():format_utc(%H:%M:%S) return tab .. tab.tab_index 1 .. [ .. now .. ] end) return {}需要强调的一个易错点由于format_utc()不做本地时区换算同一个时刻在不同时区的机器上运行format_utc()的输出是绝对一致的而format()的输出会随系统时区变化。如果你的场景是给用户看本地现在几点请用format()如果是记录一个可跨机器对比的时间戳请用format_utc()。与wezterm.time模块其他函数的协同format_utc()作为Time对象的方法通常与wezterm.time模块中的以下函数搭配使用wezterm.time.now()返回当前时刻的 Time 对象是获取Time对象的入口之一。wezterm.time.parse(str, format)按格式串反向解析字符串为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)。解析出的对象同样可以调用:format_utc()重新渲染成任意格式。wezterm.time.parse_rfc3339(str)解析 RFC 3339 格式字符串为Time对象见 parse_rfc3339.md解析失败会抛错。wezterm.time.call_after延迟执行回调见 call_after.md可在回调里用now():format_utc()生成定时刷新状态的日志时间戳。此外模块还提供了两个旧版兼容函数wezterm.strftime与wezterm.strftime_utc见 time-funcs/src/lib.rs。其中strftime_utc的实现思路与Time:format_utc完全一致——Utc::now()后直接按格式串渲染但它是模块级函数而非Time对象方法无法对任意历史时刻格式化新配置建议统一使用Time对象方法。版本与注意事项小结版本要求format_utc()与wezterm.time模块整体一样自20220807-113146-c2fee766版本引入更早版本无法使用。返回字符串方法始终返回字符串不做任何时区换算内部存储始终为 UTC。无效格式串chrono 在遇到未知占位符时按字面量输出该字符不会抛错因此格式串写错时表现为输出与预期不符调试时注意核对占位符拼写。时区判断需要绝对时间戳选format_utc()需要本地展示时间选format()二者输出差异即为系统时区与 UTC 的偏移。【免费下载链接】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），仅供参考
)
)
