oh-my-zsh battery 插件实战:在终端提示符中显示跨平台电池状态
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 要求两个条件:
- 安装
Termux:API附加应用(可从 Google Play 或 F-Droid 获取); - 在 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),需先按上文"其他平台的实现与依赖要求"一节安装对应依赖,插件才能输出有效数据。