WezTerm 电池状态读取深入理解wezterm.battery_info()及其在状态栏中的应用【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwezterm.battery_info()是 WezTerm 提供给 Lua 配置脚本的系统电池查询接口它返回机器上所有已安装电池的实时电量、厂商、型号、序列号以及充放电状态等信息。在 WezTerm 中该函数最常见的应用场景是配合update-right-status/update-status事件与window:set_right_status在标签栏右侧动态渲染电池百分比形成轻量级的终端状态栏。阅读本文后你将掌握该 API 的完整返回字段语义、底层实现机制以及如何编写一份可落地的电池状态栏配置。函数签名与返回结构wezterm.battery_info()自版本20210314-114017-04b7cedd起可用调用时不需要任何参数返回值为一个数组array数组中的每个元素对应系统上检测到的一块电池。绝大多数台式机没有电池此时返回空数组笔记本电脑通常返回包含一个元素的数组带有可拆卸电池或双电池设计的设备则可能返回多个元素。每个电池对象包含以下字段字段类型说明state_of_chargenumber电池电量归一化为0.0空到1.0满之间的小数vendorstring电池制造商名称未知时为unknownmodelstring电池型号字符串未知时为unknownserialstring电池序列号未知时为unknowntime_to_fullnumber | nil正在充电时预计充满所需的秒数不可用或未充电时为niltime_to_emptynumber | nil正在放电时预计耗尽所需的秒数不可用或未放电时为nilstatestring枚举字符串取值见下表state字段的取值与语义如下Charging— 正在充电Discharging— 正在放电Empty— 已耗尽Full— 已充满Unknown— 状态未知需要注意的是time_to_full与time_to_empty使用了Option语义对应 Lua 中的nil只有处于对应充放电状态且系统能够估算时才返回数值。因此在使用前务必进行nil判空避免拼接字符串或做算术运算时出错。官方示例状态栏中的电量与日期官方文档给出的示例将每个电池的电量百分比与当前日期时间一起渲染到标签栏右侧的状态区域local wezterm require wezterm wezterm.on(update-right-status, function(window, pane) -- Wed Mar 3 08:14 local date wezterm.strftime %a %b %-d %H:%M local bat for _, b in ipairs(wezterm.battery_info()) do bat .. string.format(%.0f%%, b.state_of_charge * 100) end window:set_right_status(wezterm.format { { Text bat .. .. date }, }) end)这段脚本的关键步骤require wezterm引入内置 Lua 模块通过wezterm.on(update-right-status, ...)注册状态栏更新事件更推荐使用 20220903 之后引入的update-status事件详见后文用wezterm.strftime %a %b %-d %H:%M 格式化当前日期时间遍历wezterm.battery_info()返回的数组将state_of_charge0.0~1.0乘以 100 并格式化为整数百分比最后调用window:set_right_status把组合好的文本设置到状态栏文本内容通过 wezterm.format 进行样式化组装。注意示例中bat采用循环赋值若存在多块电池最终只会保留最后一块的电量如需展示所有电池可将它们拼接在同一字符串中。深入源码底层如何获取电池数据wezterm.battery_info()并非 WezTerm 核心二进制直接实现而是位于独立的 Lua API 插件 crate —— battery 中。该 crate 在注册阶段把函数挂载到wezterm模块上let wezterm_mod get_or_create_module(lua, wezterm)?; wezterm_mod.set(battery_info, lua.create_function(battery_info)?)?;其数据来源是 Rust 生态中成熟的开源库starship-battery工作区版本固定在0.10见 根 Cargo.toml 与 battery/Cargo.toml。该库通过系统底层接口Linux 的 sysfs/sys/class/power_supply、macOS 的 IOKit、Windows 的 SetupAPI 等枚举所有电源设备因此wezterm.battery_info()能在三大桌面平台一致地工作。从源码结构看battery_info 的实现 做了以下映射Manager::new()初始化电池管理句柄manager.batteries()迭代出系统上的每一块电池state_of_charge取自bat.state_of_charge().value是 0.0~1.0 的浮点数vendor、model、serial分别取自vendor()、model()、serial_number()若为None则由opt_string统一替换为字符串unknown见 lib.rsstate通过match bat.state()将库内部枚举翻译为文档约定的五个字符串字面量time_to_full与time_to_empty用Option包装对应 Lua 侧的nil。BatteryInfo结构体通过#[derive(FromDynamic, ToDynamic, Debug)]与impl_lua_conversion_dynamic!宏自动生成与 Lua 表之间的序列化转换这解释了为什么在 Lua 中可以直接以b.state_of_charge的形式访问字段。进阶实战多电池展示与充放电状态着色在官方示例基础上可以进一步利用state与time_to_*字段增强信息量。例如同时显示充电状态符号与剩余时间并根据状态着色local wezterm require wezterm wezterm.on(update-status, function(window, pane) local cells {} local icon, color for _, b in ipairs(wezterm.battery_info()) do if b.state Charging then icon, color , #00ff00 elseif b.state Discharging then icon, color , #ffcc00 else icon, color , #888888 end local pct string.format(%.0f%%, b.state_of_charge * 100) local extra if b.time_to_full then extra string.format( (%dm), math.floor(b.time_to_full / 60)) elseif b.time_to_empty then extra string.format( (%dm), math.floor(b.time_to_empty / 60)) end table.insert(cells, { Foreground { Color color } }) table.insert(cells, { Text icon .. .. pct .. extra }) end window:set_right_status(wezterm.format(cells)) end)该示例演示了wezterm.format中Foreground/Text两种FormatItem的用法完整取值清单见 wezterm.format 文档并利用nil判空安全地拼接预计充满/耗尽时间。如果你偏好 PowerLine 风格的分段状态栏set_right_status 文档 中还有一份融合了电池百分比、当前目录、主机名与日期时间的完整 PowerLine 示例其中电池部分同样是通过遍历wezterm.battery_info()实现的。事件机制与刷新时机battery_info()返回的是调用时刻的快照要让状态栏持续刷新必须把它放在周期性触发的事件回调中。WezTerm 提供两个相关事件update-right-status自20210314-114017-04b7cedd起可用按 status_update_interval 配置的毫秒间隔周期性触发回调签名为function(window, pane)典型用途是调用window:set_right_statusupdate-status自20220903-194523-3bb1ed61起引入行为与前者一致但不再局限于右侧状态区官方文档建议新配置迁移到该事件见 update-right-status 与 update-status。WezTerm 保证同一时刻只有一个事件实例在运行若回调执行时间超过status_update_interval则会在上一次调用完成后再经过一个间隔周期才安排下一次调用避免事件堆积。默认的status_update_interval值为 1000 毫秒对电池这类变化缓慢的数据而言足够及时。使用前提与限制wezterm.battery_info()只在 GUI 主进程wezterm-gui的 Lua 环境中可用功能依赖系统电源管理接口因此在没有电池的台式机上会返回空数组这是正常行为而非错误部分平台上vendor、model、serial可能无法读取此时固定返回unknowntime_to_full/time_to_empty为系统估算值仅在实际充电/放电时存在并可能受电源管理策略影响而返回nil该 API 自版本20210314-114017-04b7cedd起提供低于该版本的 WezTerm 无法调用由于battery_info()每次都会重新枚举系统电池设备建议仅在周期性事件回调中调用而不是在热循环代码里高频调用。将以上配置保存为~/.wezterm.lua或$XDG_CONFIG_HOME/wezterm/wezterm.lua后重启 WezTerm即可在标签栏右侧看到实时更新的电量状态。后续只需在回调中扩展cells数组即可把日期、工作目录、主机名等信息一并整合进你的专属状态栏。【免费下载链接】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），仅供参考