Spaceship Prompt Battery 电池电量分区:配置参数、显示策略与跨平台实现原理
Spaceship Prompt Battery 电池电量分区:配置参数、显示策略与跨平台实现原理
导读
battery 是 Spaceship Prompt 内置的电源状态分区(section),用于在 Zsh 提示符中实时展示当前设备的电池电量百分比与充放电状态。本文以 docs/uk/sections/battery.md(乌克兰语文档,与 docs/sections/battery.md 英文版内容一致)为骨架,结合 sections/battery.zsh 源码实现,系统讲解 SPACESHIP_BATTERY_SHOW 等 8 个配置参数的语义、pmset / acpi / upower 三种电量采集后端的探测逻辑,以及“低于阈值变红、充满变绿、颜色随电量分级”的渲染规则。读完本文,你将能按需定制电池分区的显示时机、符号与阈值,并理解其异步渲染与缓存机制的底层原理。
分区概览:默认行为与核心职责
battery 分区只做两件事:读取当前电池的电量百分比和判断其充放电状态,然后将它们渲染为提示符中的一个彩色小片段。
该分区有一个重要的默认行为(原文档在开头即用醒目提示标注):
默认情况下,本分区是异步渲染的(
SPACESHIP_BATTERY_ASYNC=true)。
此外,默认情况下 battery 分区并非总是显示,只有当电量低于阈值 SPACESHIP_BATTERY_THRESHOLD(默认 10,即 10%)时才会出现。换言之,在绝大多数“电量充足”的场景下它保持静默,避免打扰;只有当电量告急时才在提示符中亮起提醒。
显示时机控制:SPACESHIP_BATTERY_SHOW 的四种取值
你可能希望电池分区“始终显示”,或者“只在充满 / 电量低时显示”。原文档指出,通过设置 SPACESHIP_BATTERY_SHOW 即可精确控制显示时机。该参数支持四个取值,其行为与“低于阈值 / 高于阈值 / 完全充满”三种电池状态组合如下:
SPACESHIP_BATTERY_SHOW |
低于阈值 | 高于阈值 | 完全充满 |
|---|---|---|---|
false |
隐藏 | 隐藏 | 隐藏 |
always |
显示 | 显示 | 显示 |
true |
显示 | 隐藏 | 隐藏 |
charged |
显示 | 隐藏 | 显示 |
这张表也是源码 sections/battery.zsh 中注释区的原始设计蓝图。结合源码末尾的渲染条件(sections/battery.zsh),可以还原其判定逻辑:
if [[ $SPACESHIP_BATTERY_SHOW == 'always' ||
$battery_percent -lt $SPACESHIP_BATTERY_THRESHOLD ||
$SPACESHIP_BATTERY_SHOW == 'charged' && $battery_status =~ "(charged|full)" ]]; then
# 渲染分区
fi
解读如下:
false:函数入口处<a href="https://link.gitcode.com/i/261278c386bc5e9cefe5038de010866b" target="_blank">[ $SPACESHIP_BATTERY_SHOW == false ]] && return([sections/battery.zsh)直接短路返回,任何情况下都不显示;always:无条件显示,忽略阈值与充满状态;true(默认):只满足“电量低于阈值”才显示;charged:电量低于阈值时显示,电量充满时也显示(配合“高于阈值但未充满”时隐藏,用于让提示符在充满时给出一次反馈)。
注意“低于阈值”在源码中是严格小于:
battery_percent -lt SPACESHIP_BATTERY_THRESHOLD,即电量恰好等于阈值(如恰好 10%)时不会被判定为“低于阈值”。
完整参数一览
原文档提供了 battery 分区的完整参数表,以下是全部 8 个配置项及其默认值与含义:
| 变量 | 默认值 | 含义 |
|---|---|---|
SPACESHIP_BATTERY_SHOW |
true |
是否显示分区(可选 true、false、always 或 charged) |
SPACESHIP_BATTERY_ASYNC |
true |
是否异步渲染该分区 |
SPACESHIP_BATTERY_PREFIX |
(一个空格) |
分区前缀 |
SPACESHIP_BATTERY_SUFFIX |
$SPACESHIP_PROMPT_DEFAULT_SUFFIX |
分区后缀 |
SPACESHIP_BATTERY_SYMBOL_CHARGING |
⇡ |
充电时显示在分区开头的符号 |
SPACESHIP_BATTERY_SYMBOL_DISCHARGING |
⇣ |
放电时显示在分区开头的符号 |
SPACESHIP_BATTERY_SYMBOL_FULL |
• |
电量 100% 时显示在分区开头的符号 |
SPACESHIP_BATTERY_THRESHOLD |
10 |
电量低于该百分比时显示分区 |
这些默认值均通过 Zsh 的参数展开赋值语法定义在源码顶部(sections/battery.zsh),例如:
SPACESHIP_BATTERY_SHOW="${SPACESHIP_BATTERY_SHOW=true}"
SPACESHIP_BATTERY_ASYNC="${SPACESHIP_BATTERY_ASYNC=true}"
SPACESHIP_BATTERY_PREFIX="${SPACESHIP_BATTERY_PREFIX=""}"
SPACESHIP_BATTERY_SUFFIX="${SPACESHIP_BATTERY_SUFFIX="$SPACESHIP_PROMPT_DEFAULT_SUFFIX"}"
SPACESHIP_BATTERY_SYMBOL_CHARGING="${SPACESHIP_BATTERY_SYMBOL_CHARGING="⇡"}"
SPACESHIP_BATTERY_SYMBOL_DISCHARGING="${SPACESHIP_BATTERY_SYMBOL_DISCHARGING="⇣"}"
SPACESHIP_BATTERY_SYMBOL_FULL="${SPACESHIP_BATTERY_SYMBOL_FULL="•"}"
SPACESHIP_BATTERY_THRESHOLD="${SPACESHIP_BATTERY_THRESHOLD=10}"
注意 SPACESHIP_BATTERY_SUFFIX 的默认值继承自全局的 $SPACESHIP_PROMPT_DEFAULT_SUFFIX,因此电池分区会自动跟随你为整个提示符统一配置的后缀风格,无需单独设置。
跨平台电量采集:三种后端探测链
原文档仅说明“显示当前电池状态与电量”,未展开具体实现。深入 sections/battery.zsh 可以看到,该分区通过 spaceship::exists 依次探测系统中可用的电量查询命令,形成一条完整的跨平台回退链:
-
macOS:
pmset(sections/battery.zsh)battery_data=$(pmset -g batt | grep "InternalBattery")执行
pmset -g batt并过滤出InternalBattery行;若本机没有内置电池(如台式 Mac),battery_data为空,函数立即返回。随后用\grep -oE '[0-9]{1,3}%'提取百分比,用awk -F '; *'切出状态字段(charging、discharging等)。源码特意用反斜杠转义的\grep,避免用户的grep别名(如开启颜色高亮)污染解析结果。 -
Linux:
acpi(sections/battery.zsh)battery_data=$(acpi -b 2>/dev/null | head -1)通过
sed把形如Battery 0: Discharging, 85%, 02:13:45 remaining的输出规整为状态:百分比的键值对,再用 Zsh 数组切分语法("${(@s/:/)battery_status_and_percent}")拆出状态与百分比,并将状态转为小写(battery_status=$battery_status_and_percent_array[1]:l)。同时有一个健壮性处理:若解析出的百分比为0,说明该机很可能没有电池,直接返回。 -
Linux:
upower(sections/battery.zsh)local battery=$(command upower -e | grep battery | head -1)先枚举电源设备并取第一个电池设备,再
upower -i $battery获取详情,用grep percentage/grep state分别提取百分比与状态。 -
兜底:三种命令都不可用时(
else分支)直接return,保证分区在其他系统上静默退出,绝不报错。
颜色分级与符号选择规则
拿到百分比与状态后,分区会依据电量数值动态着色(sections/battery.zsh):
if [[ $battery_percent == 100 || $battery_status =~ "(charged|full)" ]]; then
battery_color="green"
elif [[ $battery_percent -lt $SPACESHIP_BATTERY_THRESHOLD ]]; then
battery_color="red"
else
battery_color="yellow"
fi
- 绿色:电量恰好为 100%,或状态匹配
charged/full(充满); - 红色:电量低于阈值(默认 10%)——这是最重要的“告警”状态;
- 黄色:其余情况(电量充足但未充满)。
符号的选择则完全由充放电状态驱动(sections/battery.zsh):
if [[ $battery_status == "charging" ]]; then
battery_symbol="${SPACESHIP_BATTERY_SYMBOL_CHARGING}" # ⇡
elif [[ $battery_status =~ "^[dD]ischarg.*" ]]; then
battery_symbol="${SPACESHIP_BATTERY_SYMBOL_DISCHARGING}" # ⇣
else
battery_symbol="${SPACESHIP_BATTERY_SYMBOL_FULL}" # •
fi
正则 ^[dD]ischarg.* 兼容 discharging / Discharging 等大小写变体;当状态既非 charging 也不匹配放电时(如充满、静止),统一使用 SPACESHIP_BATTERY_SYMBOL_FULL。
渲染机制:spaceship::section 与 % 转义
最终的渲染入口调用 lib/section.zsh 提供的 spaceship::section 打包函数(sections/battery.zsh):
spaceship::section \
--color "$battery_color" \
--prefix "$SPACESHIP_BATTERY_PREFIX" \
--suffix "$SPACESHIP_BATTERY_SUFFIX" \
--symbol "$battery_symbol" \
"$battery_percent%%"
其中内容部分写作 "$battery_percent%%":因为 % 在 Zsh 提示符展开中是特殊字符,必须转义为 %% 才能在界面上正确显示百分号(源码注释也明确说明了这一点)。打包后的元组(颜色、前缀、后缀、符号、内容)会在渲染阶段由 spaceship::section::render(lib/section.zsh)转换为带 %F{color} 着色指令的最终提示符片段。若分区没有内容也没有符号,渲染函数会直接跳过,避免输出空片段。
异步渲染:默认开启与全局开关
前面提到 battery 分区默认异步渲染。Spaceship 的异步机制在 lib/utils.zsh 的 spaceship::is_section_async 中判定:先检查全局开关 SPACESHIP_PROMPT_ASYNC,再读取各分区自己的 SPACESHIP_<SECTION>_ASYNC 变量——对 battery 而言就是 SPACESHIP_BATTERY_ASYNC。当异步启用时,分区会在后台 worker 中执行(相关实现见 lib/worker.zsh 与 lib/core.zsh),电量数据的读取不会阻塞提示符的即时出现。
如果你的环境存在兼容性问题,可以同时将全局
SPACESHIP_PROMPT_ASYNC与SPACESHIP_BATTERY_ASYNC设为false以关闭异步。
实战配置示例
始终显示并调整阈值
# ~/.zshrc 或 Spaceship 配置文件中
SPACESHIP_BATTERY_SHOW="always" # 无论电量多少都显示
SPACESHIP_BATTERY_THRESHOLD=20 # 电量低于 20% 时显示为红色告警
充满时也提示一次
SPACESHIP_BATTERY_SHOW="charged" # 低于阈值显示,充满时也显示
自定义符号与外观
SPACESHIP_BATTERY_SYMBOL_CHARGING="⚡" # 充电符号
SPACESHIP_BATTERY_SYMBOL_DISCHARGING="🔋" # 放电符号
SPACESHIP_BATTERY_SYMBOL_FULL="●" # 充满符号
SPACESHIP_BATTERY_PREFIX=" " # 分区前缀
彻底关闭电池分区
SPACESHIP_BATTERY_SHOW="false"
若你希望调整分区在提示符中的顺序,可使用 Spaceship CLI(参见 docs/config/loading-sections.md):
spaceship add battery
限制与注意事项
- 数据来源依赖系统命令:该分区依赖
pmset(macOS)、acpi/upower(Linux)。在不支持这些命令的系统上分区会静默隐藏,这是设计内行为而非故障。 - 阈值比较为严格小于:电量恰好等于
SPACESHIP_BATTERY_THRESHOLD时不会触发“低于阈值”的显示/红色判定。 - “完全充满”的判定同时看数值(
== 100)与状态(charged/full),两种途径任一命中即视为充满,着色为绿色并使用SPACESHIP_BATTERY_SYMBOL_FULL符号。 - 百分号转义:分区内容中的
%在 Zsh 提示符展开中是特殊字符,实现中已转义为%%,因此界面上能正常显示诸如85%的文本。
延伸阅读
- 分区英文原版文档:docs/sections/battery.md
- 源码实现:sections/battery.zsh
- 分区渲染 API 与
spaceship::section用法:docs/api/section.md - 异步渲染判定逻辑:lib/utils.zsh
- 提示符整体渲染管线:lib/section.zsh