oh-my-bash battery 插件实战指南:跨平台电池监控、图形化电量显示与提示符集成

原创2026-10-14 13:35:371,889 阅读
文章标签:CLI开发工具插件系统

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 之类的守卫函数保证提示符不报错。

常见问题与注意事项

  1. 工具缺失时无输出:如果系统上既没有 upower/acpi(Linux)、pmset/ioreg(macOS)、WMIC(Windows),也没有可读的 /sys/class/power_supply/ 目录,各函数将静默返回非零状态或空输出,这是设计预期(battery_charge 会落到 * 分支显示 UNPLG)。
  2. 数值边界处理:battery_percentage 在 acpi 无法识别状态时返回 -1,battery_charge 会将其归入 * 分支显示 UNPLG,而不是渲染出错误的电量图形。
  3. 提示符性能:battery_percentage 每次调用都会执行外部命令(如 upower -i、acpi -b),若放入 PROMPT_COMMAND 会随每次提示刷新执行;对性能敏感的场景可考虑缓存结果或仅在电池状态变化时刷新。
  4. 独立使用不享受更新:脱离 oh-my-bash 直接复制函数文件可以正常工作,但如原文档所述,该副本不会随上游更新,出现问题时需要自行修复。
  5. 与主题的依赖关系: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),你可以快速把电池信息接入自己的提示符主题,打造个性化的终端状态栏。

登录后查看全文
oh-my-bash