oh-my-bash battery 插件实战指南:跨平台电池监控、图形化电量显示与提示符集成
oh-my-bash battery 插件实战指南:跨平台电池监控、图形化电量显示与提示符集成
本文以 oh-my-bash 的 battery 插件文档 为核心,结合 battery.plugin.sh 源码,完整讲解如何通过该插件在 Linux、macOS、Windows 等平台上监控电池状态,并深入剖析 ac_adapter_connected、ac_adapter_disconnected、battery_percentage、battery_charge 四个核心函数的多后端实现机制,以及如何将电量信息集成进提示符(Prompt)主题。读完本文,你将能在 ~/.bashrc 中一键启用电池监控,理解底层工具链的探测优先级,并掌握在自定义主题中复用电池函数的方法。
插件概览:battery 能做什么
battery 是 oh-my-bash 提供的一个终端体验增强插件,核心能力是通过一组 Bash 函数监控并展示电池状态与电量信息。它本身不依赖固定的电池读取方式,而是根据当前系统上可用的命令动态选择数据来源,因此一套函数即可覆盖多种操作系统。
插件共提供四个公开函数:
| 函数 | 作用 | 输出/返回 |
|---|---|---|
ac_adapter_connected |
检测电源适配器(AC Adapter)是否已连接 | 退出码 0 表示已连接,非零表示未连接 |
ac_adapter_disconnected |
检测电源适配器是否已断开 | 退出码 0 表示已断开,非零表示未断开 |
battery_percentage |
获取当前电池电量(满电为 100%) | 标准输出输出整数形式的电量百分比 |
battery_charge |
用 ASCII 字符图形化展示电池电量 | 标准输出输出图形化电量条 |
这些函数定义在 plugins/battery/battery.plugin.sh,文件头以 #! bash oh-my-bash.module 标记,是 oh-my-bash 模块系统的标准格式。函数均可直接从交互式 Shell 调用,也可被其他主题或脚本复用(仓库中多个主题都在提示符中调用了它们,下文会详细说明)。
安装与启用
在 oh-my-bash 中启用插件
与所有 oh-my-bash 插件一样,battery 的启用方式是在 ~/.bashrc 的 plugins 数组中追加插件名:
# bashrc
plugins=(... battery)
plugins 数组的书写位置与模板示例可参考 templates/bashrc.osh-template。启用后,重新打开终端或执行 source ~/.bashrc 即可生效。
从源码结构看,oh-my-bash 启动时会调用 oh-my-bash.sh 中的 _omb_module_require_plugin "${plugins[@]}" 加载插件,其模块定位逻辑位于同一文件的 _omb_module_require 函数中:
plugin) locations=({"$OSH_CUSTOM","$OSH"}/plugins/"$name"/"$name".plugin.{bash,sh}) ;;
也就是说,battery 插件会从 $OSH/plugins/battery/battery.plugin.sh 或 $OSH_CUSTOM/plugins/battery/battery.plugin.{bash,sh} 中按顺序查找并加载,同时插件加载会做去重与状态记录(_omb_module_loaded),避免重复 source。
按条件加载插件
如果你希望 battery 只在特定场景下加载,可以在 ~/.bashrc 中把插件从主列表移除,改用条件语句动态追加。例如仅在桌面会话中启用:
[[ $DISPLAY ]] && plugins+=(battery)
这种写法与仓库中 tmux-autoattach 等条件加载插件的推荐用法一致(参见 plugins/README.md)。
独立使用(不安装 oh-my-bash)
原文档特别提示:如果只想使用该插件而不安装完整的 oh-my-bash,可以把 battery.plugin.sh 和 lib/utils.sh 复制到任意位置,然后在 ~/.bashrc(交互式使用)或某个 Shell 脚本(独立脚本程序)中 source 它们:
source /path/to/battery.plugin.sh
source /path/to/utils.sh
也可以把四个函数直接复制粘贴进自己的脚本文件。需要留意的是:独立复制的方式不会再随 oh-my-bash 更新,函数可能存在的问题需要自行维护解决(原文档中的明确警告)。
核心函数详解与源码剖析
ac_adapter_connected / ac_adapter_disconnected:电源适配器状态检测
这两个函数分别判断电源适配器是否连接、是否断开,以退出码作为返回值:
ac_adapter_connected:适配器已连接时返回0,否则返回非零退出状态;ac_adapter_disconnected:适配器已断开时返回0,否则返回非零退出状态。
以 ac_adapter_connected 为例,battery.plugin.sh 的实现是一个典型的多后端探测链:
function ac_adapter_connected {
if _omb_util_command_exists upower; then
_omb_plugin_battery__upower_print_info | grep -qE 'state[:[:blank:]]*(charging|fully-charged)'
elif _omb_util_command_exists acpi; then
acpi -a | grep -q "on-line"
elif _omb_util_command_exists pmset; then
pmset -g batt | grep -q 'AC Power'
elif _omb_util_command_exists ioreg; then
ioreg -n AppleSmartBattery -r | grep -q '"ExternalConnected" = Yes'
elif _omb_util_command_exists WMIC; then
WMIC Path Win32_Battery Get BatteryStatus /Format:List | grep -q 'BatteryStatus=2'
elif [[ -r /sys/class/power_supply/ADP0/online ]]; then
[[ $(< /sys/class/power_supply/ADP0/online) == 1 ]]
fi
}
对应地,ac_adapter_disconnected 使用同样的探测顺序,只是匹配反向状态:upower 匹配 discharging 状态、acpi 匹配 off-line、pmset 匹配 Battery Power、ioreg 匹配 "ExternalConnected" = No、WMIC 匹配 BatteryStatus=1、sysfs 则判断 ADP0/online 文件内容是否为 0。
每个后端的判定依据归纳如下:
| 平台/工具 | 已连接判定依据 | 已断开判定依据 |
|---|---|---|
Linux:upower |
电池状态为 charging 或 fully-charged |
电池状态为 discharging |
Linux:acpi |
acpi -a 输出包含 on-line |
acpi -a 输出包含 off-line |
macOS:pmset |
pmset -g batt 输出包含 AC Power |
输出包含 Battery Power |
macOS:ioreg |
AppleSmartBattery 的 ExternalConnected 为 Yes |
该值为 No |
Windows:WMIC |
BatteryStatus=2 |
BatteryStatus=1 |
| Linux 兜底:sysfs | /sys/class/power_supply/ADP0/online 内容为 1 |
内容为 0 |
注意这里使用的 upower 读取逻辑:_omb_plugin_battery__upower_print_info 会先通过 upower -e 枚举设备并 sed -n '/BAT/{p;q;}' 定位到第一个 BAT 设备,再用 upower -i 打印其详细信息,后续所有 upower 分支(包括电量读取)都复用该辅助函数。
battery_percentage:获取电量百分比
battery_percentage 输出当前电量相对于满电(100%)的整数百分比。同样遵循"按可用工具优先选择"的原则,各后端的解析方式不同(battery.plugin.sh):
upower(首选)
local UPOWER_OUTPUT=$(_omb_plugin_battery__upower_print_info | sed -n 's/.*percentage[:[:blank:]]*\([0-9%]\{1,\}\)$/\1/p')
[[ $UPOWER_OUTPUT ]] && _omb_util_print "${UPOWER_OUTPUT::-1}"
从 upower 的 percentage: 字段提取形如 57% 的值,再用 ${UPOWER_OUTPUT::-1} 去掉末尾的 %,得到纯数字。
acpi
local ACPI_OUTPUT=$(acpi -b)
case $ACPI_OUTPUT in
*" Unknown"*)
# 从固定偏移截取百分比字符,补零后输出
;;
*" Charging"* | *" Discharging"*)
local PERC_OUTPUT=$(awk -F, '/,/{gsub(/ /, "", $0); gsub(/%/,"", $0); print $2}' <<< "$ACPI_OUTPUT")
_omb_util_print ${PERC_OUTPUT}
;;
*" Full"*)
_omb_util_print '100'
;;
*)
_omb_util_print '-1'
;;
esac
即:状态为 Charging/Discharging 时用 awk 提取逗号后的电量数字;状态为 Full 时直接输出 100;状态为 Unknown 时从输出中截取百分比字符;其余未知情况输出 -1。
pmset(macOS)
local PMSET_OUTPUT=$(pmset -g ps | sed -n 's/.*[[:blank:]]+*\(.*%\).*/\1/p')
case $PMSET_OUTPUT in
100*) _omb_util_print '100' ;;
*) head -c 2 <<< "$PMSET_OUTPUT" ;;
esac
从 pmset -g ps 输出中提取 NN%,满电(100*)时输出 100,否则取前两位字符作为整数百分比。
ioreg(macOS)
local IOREG_OUTPUT=$(ioreg -n AppleSmartBattery -r | awk '$1~/Capacity/{c[$1]=$3} END{OFMT="%05.2f%%"; max=c["\"MaxCapacity\""]; print (max>0? 100*c["\"CurrentCapacity\""]/max: "?")}')
读取 AppleSmartBattery 的 CurrentCapacity 与 MaxCapacity,计算 100 * CurrentCapacity / MaxCapacity,同样对 100* 特判为 100、其余取前两位。
WMIC(Windows)
local WINPC=$(grep -o '[0-9]*' <<< "porcent=$(WMIC PATH Win32_Battery Get EstimatedChargeRemaining /Format:List)")
从 EstimatedChargeRemaining 字段中提取数字,100* 特判为 100。
sysfs 兜底(Linux)
elif [[ -r /sys/class/power_supply/BAT0/capacity ]]; then
_omb_util_print "$(< /sys/class/power_supply/BAT0/capacity)"
直接读取 /sys/class/power_supply/BAT0/capacity 文件内容(内核维护的整数电量值)。
所有分支最终都通过 _omb_util_print 输出结果。该函数定义于 lib/omb-util.sh:
function _omb_util_print {
local IFS=$' \t\n'
printf '%s\n' "$*"
}
它用 printf '%s\n' 保证输出内容带换行且不会误解析特殊字符,是插件输出安全的基石。
battery_charge:ASCII 图形化电量显示
battery_charge 调用 battery_percentage 获取电量,再映射为一串"电池格"图形(battery.plugin.sh):
# Full char
local F_C='▸'
# Depleted char
local D_C='▹'
local DEPLETED_COLOR="${_omb_prompt_normal}"
local FULL_COLOR="${_omb_prompt_green}"
local HALF_COLOR="${_omb_prompt_olive}"
local DANGER_COLOR="${_omb_prompt_brown}"
local BATTERY_OUTPUT="${DEPLETED_COLOR}${D_C}${D_C}${D_C}${D_C}${D_C}"
local BATTERY_PERC=$(battery_percentage)
图形由 5 个"电池格"组成:实心 ▸ 表示已充电量,空心 ▹ 表示未充电量。电量与图形的映射规则(根据 BATTERY_PERC 的首位数字匹配):
| 电量(百分比) | 图形效果 |
|---|---|
9x(90%–99%) |
5 格全满,绿色 |
8x(80%–89%) |
4 格满 + 1 格半满 |
7x(70%–79%) |
4 格满 + 1 格空 |
6x(60%–69%) |
3 格满 + 1 半满 + 1 空 |
5x(50%–59%) |
3 格满 + 2 空 |
4x(40%–49%) |
2 格满 + 1 半满 + 2 空 |
3x(30%–39%) |
2 格满 + 3 空 |
2x(20%–29%) |
1 格满 + 1 半满 + 3 空 |
1x(10%–19%) |
1 格满 + 4 空 |
05/04/03/02 |
1 格满(棕色警示色)+ 4 空 |
0x(0%–9%) |
1 格半满(橄榄色)+ 4 空 |
| 其他(无法识别) | 输出棕色 UNPLG(未插电提示) |
源码中还保留了 no 分支,用于在无法取得电量数值时输出空字符串,避免在提示符中显示异常内容。颜色变量 _omb_prompt_green、_omb_prompt_olive、_omb_prompt_brown、_omb_prompt_normal 均来自 oh-my-bash 的提示符调色板,其默认值在 lib/omb-prompt-colors.sh 中初始化(如 _omb_prompt_normal='\[\e[0m\]'、绿色为 \[\e[0;32m\]),并会随终端色数(8/16/256 色)自动适配。
多后端探测机制:一份代码覆盖三种平台
battery 插件最核心的设计,是以"命令是否存在"为线索构建探测优先级链。所有分支都依赖 _omb_util_command_exists 判断工具是否可用,该函数定义于 lib/utils.sh:
if ((_omb_bash_version >= 40000)); then
function _omb_util_command_exists {
type -t -- "$@" &>/dev/null # bash-4.0
}
...
它基于 type -t 检测命令是否已定义(可覆盖别名、关键字、函数、内建命令或外部文件),并根据 Bash 版本(≥ 4.0 或 3.2)提供了两套实现以保证兼容性。
四个函数统一遵循的探测优先级为:
upower → acpi → pmset → ioreg → WMIC → /sys/class/power_supply/
- Linux 桌面环境:通常优先命中
upower(systemd 电源管理栈),其次acpi命令,最后回退到/sys/class/power_supply/下的ADP0/online与BAT0/capacity伪文件; - macOS:
pmset -g batt与ioreg -n AppleSmartBattery分别承担适配器状态与电量读取; - Windows(Git Bash/WSL 等环境):
WMIC Path Win32_Battery提供BatteryStatus与EstimatedChargeRemaining。
原文档明确列出的依赖为:upower(主要工具),acpi、pmset、ioreg、WMIC(备用工具),以及 /sys/class/power_supply/(备用数据源)。插件文件本身还依赖 oh-my-bash 的 lib/utils.sh 模块(提供 _omb_util_command_exists 与 _omb_util_print 等基础工具函数)。
在提示符主题中集成电池信息
battery 插件的典型实战场景是嵌入 PS1 提示符。仓库中已有多个主题直接或间接复用了本插件的函数:
- brunton 主题在 brunton.theme.sh 中直接将
battery_charge的图形结果拼入PS1:
PS1+="${_omb_prompt_normal} $(battery_charge)\n"
- demula / pzq / rana 主题采用"先探测再调用"的安全封装模式,例如 demula.theme.sh:
function safe_battery_charge {
if [ -e "${OSH}/plugins/battery/battery.plugin.sh" ]; then
battery_charge
fi
}
即先检查插件文件是否存在,再调用 battery_charge,避免未启用插件时主题报错;pzq.theme.sh 则改用 _omb_util_function_exists battery_charge 做函数级探测。
- brainy 主题在 brainy.theme.sh 中调用
battery_percentage获取数值,并按阈值切换颜色(小于 50 用橄榄色、小于 25 用棕色),展示"数值 + 分档着色"的另一种集成思路。 - modern 主题(modern.theme.sh)与 powerline 系列(powerline.base.sh)也分别将
battery_charge或battery_percentage接入提示符。
这些主题的用法说明:启用 battery 插件后,battery_percentage 与 battery_charge 就是可被任何主题、函数或脚本直接调用的普通 Bash 函数,开发者可以参照上述示例自定义自己的电量展示逻辑。若主题依赖本插件但插件未启用,多数主题通过 safe_battery_charge 之类的守卫函数保证提示符不报错。
常见问题与注意事项
- 工具缺失时无输出:如果系统上既没有
upower/acpi(Linux)、pmset/ioreg(macOS)、WMIC(Windows),也没有可读的/sys/class/power_supply/目录,各函数将静默返回非零状态或空输出,这是设计预期(battery_charge会落到*分支显示UNPLG)。 - 数值边界处理:
battery_percentage在 acpi 无法识别状态时返回-1,battery_charge会将其归入*分支显示UNPLG,而不是渲染出错误的电量图形。 - 提示符性能:
battery_percentage每次调用都会执行外部命令(如upower -i、acpi -b),若放入PROMPT_COMMAND会随每次提示刷新执行;对性能敏感的场景可考虑缓存结果或仅在电池状态变化时刷新。 - 独立使用不享受更新:脱离 oh-my-bash 直接复制函数文件可以正常工作,但如原文档所述,该副本不会随上游更新,出现问题时需要自行修复。
- 与主题的依赖关系:
brunton、modern、demula、pzq、rana、brainy等主题(含 powerline 系列)会调用 battery 插件函数,如需使用这些主题的电池展示能力,务必先在~/.bashrc的plugins数组中启用battery。
小结
battery 插件通过"upower → acpi → pmset → ioreg → WMIC → sysfs"六层探测链,用极简的 Bash 代码覆盖了 Linux、macOS、Windows 三大平台的电池信息读取,并向外暴露了四个语义清晰的函数:两个适配器状态检测函数以退出码表达布尔结果,battery_percentage 输出整数百分比,battery_charge 输出带颜色的 ASCII 图形电量条。结合 oh-my-bash 的模块加载机制(oh-my-bash.sh)与提示符调色板(lib/omb-prompt-colors.sh),你可以快速把电池信息接入自己的提示符主题,打造个性化的终端状态栏。