Spaceship Prompt Battery 电池电量分区:配置参数、显示策略与跨平台实现原理

原创2026-09-19 12:53:511,434 阅读
文章标签:开发工具CLI

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 依次探测系统中可用的电量查询命令,形成一条完整的跨平台回退链:

  1. 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 别名(如开启颜色高亮)污染解析结果。

  2. 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,说明该机很可能没有电池,直接返回。

  3. Linux:upower(sections/battery.zsh)

    local battery=$(command upower -e | grep battery | head -1)
    

    先枚举电源设备并取第一个电池设备,再 upower -i $battery 获取详情,用 grep percentage / grep state 分别提取百分比与状态。

  4. 兜底:三种命令都不可用时(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% 的文本。

延伸阅读

登录后查看全文
spaceship-prompt