oh-my-zsh battery 插件实战:在终端提示符中显示跨平台电池状态

原创2026-09-03 21:46:342,683 阅读
文章标签:CLI插件系统开发工具

oh-my-zsh battery 插件实战:在终端提示符中显示跨平台电池状态

oh-my-zsh 的 battery 插件为 zsh 提示符提供了一组跨平台(macOS、Linux、FreeBSD、OpenBSD、Android/Termux)的电池信息函数,让你可以在自定义主题中直接显示电量百分比、剩余时间、充电状态和充电功率。读完本文,你将掌握该插件的启用方式、各平台依赖与底层实现原理,以及如何用 battery_pct_prompt 和 battery_level_gauge 打造带颜色阈值和分段电量条的提示符。

插件概览:一组可组合的提示符函数

battery 插件本身不绘制任何界面,它的职责是向 zsh 环境注册一组函数,供你的主题在 PROMPT 或 RPROMPT 中以 $(函数名) 的形式调用。从 battery.plugin.zsh 的源码可以看到,插件按操作系统分支定义了 5 个核心函数:

函数 作用
battery_is_charging 判断当前是否正在充电(返回 true/false)
battery_pct 返回电池百分比数字(macOS/Android/Linux 等平台的取值方式不同)
battery_pct_remaining 未充电时返回 battery_pct 的值;充电时返回字符串 External Power
battery_time_remaining 返回剩余可用时间(如 macOS 的 ~1:23、02:03:03 格式)
battery_pct_prompt 组合函数:按电量阈值输出带颜色的百分比或充电符号,是最常放进提示符的函数

插件按 $OSTYPE 匹配 darwin*、freebsd*、linux-android(且检测到 termux-battery-status 命令)、openbsd*、linux* 分别生成实现;在不受支持的平台上,插件会定义一组空函数作为兜底(battery.plugin.zsh),保证主题里即使写入了 $(battery_pct_prompt) 也不会报错,只是不输出内容。

安装与快速上手

在 .zshrc 的插件列表中启用 battery:

plugins=(... battery)

然后在你的自定义主题中加入 battery_pct_prompt 调用。官方 README 给出的示例是放入右侧提示符(README):

RPROMPT='$(battery_pct_prompt) ...'

未充电时,battery_pct_prompt 会按电量输出三色百分比:大于 50% 为绿色、大于 20% 为黄色、其余为红色(该阈值逻辑在 battery.plugin.zsh 的 macOS 分支中可见,其他平台分支逻辑一致)。输出使用 %{$fg[color]%}...%{$reset_color%} 包裹颜色码,避免 zsh 计算提示符长度时出错。

充电时,除 macOS 外,插件统一输出 ∞ 符号表示"外部供电"。如果你不想用 ⚡️ 而是自定义充电图标,可以设置 BATTERY_CHARGING 变量:

BATTERY_CHARGING="⚡️"

需要注意实现细节:在 macOS 分支中,充电状态的实际输出是 ${watts}${BATTERY_CHARGING-⚡️}(battery.plugin.zsh),即 BATTERY_CHARGING 未设置时回退为默认的 ⚡️;而在 Linux/FreeBSD 等分支中,充电时 battery_pct_prompt 直接回显 ∞,BATTERY_CHARGING 不生效。

macOS 实现细节:电量、剩余时间与充电功率

macOS(darwin*)分支是功能最全的平台,依赖系统自带工具:

  • 电量百分比:pmset -g batt | grep -Eo "\d+%" | cut -d% -f1(battery.plugin.zsh)。
  • 充电状态:通过 ioreg -rc AppleSmartBattery 检查 ExternalConnected = Yes(battery.plugin.zsh)。
  • 剩余时间:从 ioreg 输出中解析 AvgTimeToEmpty(单位分钟),并格式化为 ~分:秒;若剩余时间超过 720 分钟则输出 ::,处于充电状态则输出 ∞(battery.plugin.zsh)。

此外,macOS 独占支持充电功率显示——这是 README 中明确标注为 "MacOS only" 的功能:

BATTERY_SHOW_WATTS=true

开启后,插件会调用 get_charger_power 函数,从 ioreg -rc AppleSmartBattery 中解析 "Watts"= 字段,输出形如 123W ⚡️(battery.plugin.zsh)。该变量在插件加载时默认为 false(: ${BATTERY_SHOW_WATTS:=false},battery.plugin.zsh),因此不设置时充电状态只显示 BATTERY_CHARGING 符号(默认 ⚡️)。

其他平台的实现与依赖要求

Linux

README 明确了 Linux 上的前置条件:必须安装 acpi 或 acpitool 命令之一,Debian/Ubuntu 系统可用:

sudo apt install acpi
# 或
sudo apt install acpitool

源码中 Linux 分支会优先探测 acpitool,否则退回 acpi(battery.plugin.zsh):

  • battery_pct 解析时兼容多电池场景:acpitool 输出中优先取 All batteries 行的汇总百分比,取不到再取单个 Battery 行(battery.plugin.zsh);acpi 则会跳过 rate information unavailable 的条目,取第一个有效 Battery 行。
  • battery_time_remaining 直接对 acpi 输出 cut -f3 -d ',' 提取剩余时间字段(battery.plugin.zsh)。

Android(Termux)

在 Android 上通过 Termux 使用时,README 要求两个条件:

  1. 安装 Termux:API 附加应用(可从 Google Play 或 F-Droid 获取);
  2. 在 Termux 内安装 termux-api 包:
pkg install termux-api

源码层面,Android 分支以 [[ "$OSTYPE" = linux-android ]] 且系统存在 termux-battery-status 命令作为启用条件(battery.plugin.zsh)。termux-battery-status 输出 JSON(源码注释中给出了示例:"percentage": 93、"status": "DISCHARGING" 等),插件用 awk 从中提取百分比(battery.plugin.zsh),充电状态则判断 status 字段是否为 DISCHARGING(battery.plugin.zsh)。Android 上 battery_time_remaining 是空实现,源码注释明确标注 "Not available on android"(battery.plugin.zsh)。

FreeBSD 与 OpenBSD

  • FreeBSD:通过 sysctl 读取 hw.acpi.battery.state(值为 2 表示充电)、hw.acpi.battery.life(百分比)、hw.acpi.battery.time(剩余分钟数)(battery.plugin.zsh)。
  • OpenBSD:使用系统自带的 apm 命令,apm -b 判断充电(值为 3)、apm -l 读百分比、apm -m 读剩余时间(battery.plugin.zsh)。

这两个平台的 battery_pct_prompt 与其他非 macOS 平台一致:充电输出 ∞,否则按 >50 / >20 阈值着色。

与主题的组合:仓库中的真实用法

oh-my-zsh 内置主题中已有两个主题实际调用了该插件的函数,可作为编写自定义主题的参考。

kiwi.zsh-theme 采用了防御式写法:先检查函数是否存在,不存在就定义一个空函数兜底,然后在 PROMPT 中内联调用:

(( $+functions[battery_pct_prompt] )) || function battery_pct_prompt { }
PROMPT='...$(battery_pct_prompt)'

这样主题在用户未启用 battery 插件时依然可以正常工作。candy-kingdom.zsh-theme 则是在组装 RPROMPT 时先判断函数存在,再追加剩余时间与电量:

if (( $+functions[battery_pct_prompt] )); then
    RPROMPT+='$(battery_time_remaining) $(battery_pct_prompt)%{$reset_color%}'
fi

编写自定义主题时,这两种写法都能避免"用户没装插件、主题却调用未定义函数"的问题,值得照搬。

battery_level_gauge:可高度定制的分段电量条

除 battery_pct_prompt 外,插件还提供了一个 README 未提及、但自定义能力更强的函数:battery_level_gauge(battery.plugin.zsh)。它在所有平台上统一可用(不受操作系统分支限制),输出形如 [▶▶▶▶▶▷▷▷▷▷] 的分段电量条,通过 printf '%.0s' 循环输出填充与空白符号。它暴露了完整的定制接口:

变量 默认值 说明
BATTERY_GAUGE_SLOTS 10 电量条总格数
BATTERY_GREEN_THRESHOLD slots * 0.6 填充格数超过该值时显示绿色
BATTERY_YELLOW_THRESHOLD slots * 0.4 填充格数超过该值(未达绿色阈值)时显示黄色,否则红色
BATTERY_COLOR_GREEN / YELLOW / RED %F{green} 等 三色 ANSI 颜色码,可替换为 256 色码
BATTERY_COLOR_RESET %{%f%k%b%} 颜色复位序列
BATTERY_GAUGE_PREFIX / SUFFIX [ / ] 电量条前后缀
BATTERY_GAUGE_FILLED_SYMBOL / EMPTY_SYMBOL ▶ / ▷ 填充与空格符号
BATTERY_CHARGING_SYMBOL ⚡ 充电时的前缀符号
BATTERY_CHARGING_COLOR 同黄色 充电符号的颜色
BATTERY_UNKNOWN_SYMBOL . 无法读取百分比时的填充符号

几个值得注意的实现行为:

  • 阈值颜色码中的 % 会被转义(printf ${filled_symbol//\%/\%\%},battery.plugin.zsh),因此自定义符号里包含 % 也不会破坏提示符;
  • 当 battery_pct 返回的不是纯数字时(例如某些异常输出),电量条会显示全格并以 BATTERY_UNKNOWN_SYMBOL(默认 .)填充,而不是报错(battery.plugin.zsh);
  • 不支持的平台上由于 battery_pct 是空函数,battery_level_gauge 会输出全格 . 的"未知"状态条。

用法示例:

RPROMPT='$(battery_level_gauge)'

配合上文提到的 RPROMPT='$(battery_pct_prompt) ...',两者可自由组合,实现"图标 + 数字百分比 + 图形电量条"的多种风格。

平台行为差异速查

综合源码,各平台在提示符中的表现可以归纳如下:

场景 macOS Linux / FreeBSD / OpenBSD / Android
未充电 [87%] 按阈值着色,带 [] 括号 87% 按阈值着色(FreeBSD/Linux/Android 输出不带括号,见各分支实现)
充电 123W ⚡️(开启 BATTERY_SHOW_WATTS 时含功率)或 ⚡️ ∞
剩余时间(battery_time_remaining) ~分:秒,充电时为 ∞,>720 分钟时为 :: Linux 为 acpi 原始格式;FreeBSD/OpenBSD 为 HH:MM;Android 不可用(空函数)

编写主题时若同时引用多个电池函数(如 candy-kingdom 的 RPROMPT+='$(battery_time_remaining) $(battery_pct_prompt)' 写法),建议始终先做 (( $+functions[...] )) 存在性检查,以兼容未启用该插件的环境。

小结

battery 插件以极小的代码量覆盖了 5 类平台的电池信息读取,核心是 5 个提示符函数和 1 个图形电量条函数,外加 BATTERY_CHARGING、BATTERY_SHOW_WATTS 以及一组 BATTERY_GAUGE_* / BATTERY_COLOR_* 定制变量。所有实现细节均可在 battery.plugin.zsh 中逐行查证,文档见 plugins/battery/README.md;若你的目标平台缺少 acpi/acpitool(Linux)或 termux-api(Android),需先按上文"其他平台的实现与依赖要求"一节安装对应依赖,插件才能输出有效数据。

登录后查看全文
ohmyzsh