企业官网建设流程全解析

bottom 电池组件（Battery Widget）完整指南：启用方式、数据显示与多电池切换

【免费下载链接】bottomYet another cross-platform graphical process/system monitor.项目地址: https://gitcode.com/GitHub_Trending/bo/bottom

导读

本文介绍 cross-platform 系统监控工具bottom中的电池组件（Battery Widget）。该组件实时展示系统电池的充电百分比、功耗、充放电状态、剩余/充满时间与电池健康度，并原生支持多电池设备的切换浏览。读完本文，你将掌握电池组件的启用条件、三种开启方式（命令行、配置文件、自定义布局）、全部键盘/鼠标交互绑定，以及通过配置文件定制电池状态颜色的方法。

!!! warning 前置条件

如果二进制在编译时**未启用 `battery` feature**，或系统上**没有电池设备**，则电池功能完全不可用。这一点同时体现在编译期与运行期两层：源码中 `battery` 相关的参数、模块与采集逻辑全部由 `#[cfg(feature = "battery")]` 条件编译控制（见 [src/options/args.rs](https://link.gitcode.com/i/150a619afa07688ce48799e08211627b) 与 [src/canvas/widgets/mod.rs](https://link.gitcode.com/i/715f21b0a0bd6489fd13eb84439042ed)）。

bottom 展开后的电池组件界面

电池组件可用性前提

编译期：batteryfeature

bottom 的电池支持依赖第三方库starship-battery，该依赖是可选的，由 Cargo feature 控制：

• Cargo.toml中声明battery = ["dep:starship-battery"]，并将starship-battery = { version = "0.11.1", optional = true }作为可选依赖（见 Cargo.toml）；
• deploy（发布/部署）feature 会一并启用battery；
• 未启用该 feature 的二进制不具备任何电池数据采集与渲染能力。

运行期：系统平台与硬件

从源码注释看，电池采集覆盖以下平台（见 src/collection/batteries.rs）：

• Linux 2.6.39+
• macOS 10.10+
• iOS
• Windows 7+
• FreeBSD / DragonFlyBSD

运行时，如果设备上不存在任何电池（如台式机、虚拟机），组件同样不会展示有效数据，渲染层会显示 "No data found for this battery" 提示（见 src/canvas/widgets/battery_display.rs）。

三种启用方式

电池组件可通过以下任一方式启用：

1. 命令行--battery标志

在终端启动 bottom 时直接传入标志：

btm --battery

该标志由BatteryArgs定义，help说明为 "Shows the battery widget in non-custom layouts"（在非自定义布局中显示电池组件）。其long_help进一步说明：该标志对自定义布局无效——若你正在使用自定义布局，必须显式将电池组件写入布局配置（见 src/options/args.rs）。

2. 配置文件battery = true

在 TOML 配置文件中设置：

battery = true

对应配置字段为flags.battery（见 src/options/config/flags.rs），效果等同于命令行标志。

3. 自定义布局中显式声明

在使用[layout]的自定义布局方案中，将电池组件以battery类型加入布局即可（其组件类型由布局管理器中的BottomWidgetType枚举对应，见 src/app/states.rs）。这是唯一一种对命令行标志不敏感、完全由用户布局决定的启用方式。

组件展示的核心数据

电池组件为每一块电池展示以下五项数据（继承自原文档 Features，并结合源码细化）：

充电百分比条形图与颜色分级

组件顶部将充电百分比渲染为[||||| 43%]形式的条形图。从渲染实现看（见 src/canvas/widgets/battery_display.rs），条形图长度由组件宽度动态计算（bar_length = full_width - 6），并依据充电百分比套用三档颜色：

• 低于 10%：使用low_battery样式（默认红色）；
• 10% ~ 50%：使用medium_battery样式（默认黄色）；
• 高于 50%：使用high_battery样式（默认绿色）。

时间显示的两种格式

时间估算基于当前电池状态，由底层starship-battery的time_to_full()/time_to_empty()接口获取秒数后换算（见 src/collection/batteries.rs）。渲染时会根据组件宽度自动选择格式（见 src/canvas/widgets/battery_display.rs）：

• 宽度充足时使用长格式：1 hour, 0 minutes, 30 seconds；
• 宽度不足时自动降级为短格式：1h 0m 30s。

这两种格式的换算逻辑（get_hms/long_time/short_time）在源码中附有完整的单元测试覆盖（见 src/canvas/widgets/battery_display.rs）。

多电池设备支持与切换

电池组件支持系统存在多块电池的场景。当检测到多块电池时，组件顶部会渲染一组Battery 0、Battery 1、…… 形式的 Tab 页签，当前选中的电池高亮显示（见 src/canvas/widgets/battery_display.rs）。

键盘切换（按键区分大小写）

鼠标切换

鼠标点击区域由渲染期记录的tab_click_locs（每个 Tab 的坐标范围）提供支持，每次重绘时都会重新计算（见 src/canvas/widgets/battery_display.rs）。

定制电池状态颜色

电池组件的三档状态颜色可在配置文件中定制，字段位于[battery]表（见 src/options/config/style/battery.rs）：

[battery] high_battery_colour = "green" # 电量 > 50% medium_battery_colour = "yellow" # 电量 10% ~ 50% low_battery_colour = "red" # 电量 < 10%

三个字段均支持_color拼写的别名（如high_battery_color），颜色值支持名称、十六进制与 RGB 等多种写法。内置主题（default / gruvbox / nord）均提供了各自的电池配色默认值（见 src/options/config/style/themes/default.rs 等），未显式配置时即采用当前主题的默认配色。

底层实现原理：从采集到渲染

了解底层调用链有助于排查问题与二次开发：

1. 初始化采集器：应用启动时创建starship_battery::Manager，并通过manager.batteries()枚举系统电池列表（见 src/collection.rs）；
2. 周期刷新：主循环每次更新数据时调用refresh_batteries()，对每块电池刷新一次并映射为BatteryData结构——读取state_of_charge()（充电百分比）、energy_rate()（功耗）、state_of_health()（健康度）以及充放电状态与预估时间（见 src/collection/batteries.rs）；
3. 状态存储：结果存入数据存储的battery_harvest列表，供渲染层按当前选中的电池索引取用（见 src/collection.rs 与 src/canvas/widgets/battery_display.rs）；
4. 界面渲染：Painter::draw_battery()完成进度条、信息表格与多电池 Tab 的绘制（见 src/canvas/widgets/battery_display.rs）。

值得留意的是，BatteryState枚举将"充满/耗尽时间"作为可选值（Option<u32>）内嵌在状态变体中——当系统无法估算剩余时间时，对应时间行不会被渲染（见 src/collection/batteries.rs）。

常见限制与排查要点

• 组件不显示：先确认二进制是否启用batteryfeature（可用btm --help查看是否存在--battery参数），再确认系统是否存在电池设备；
• 自定义布局中不出现：--battery标志对自定义布局无效，必须在布局配置中显式声明电池组件；
• 时间显示为空：说明系统未提供time_to_full/time_to_empty估算值，属正常现象，不影响其余数据展示；
• 无电池数据：界面显示 "No data found for this battery" 时，表明采集器未成功刷新到任何电池数据（见 src/canvas/widgets/battery_display.rs）。

相关文档

• 电池组件（Battery Widget）使用文档（本文原始来源）
• 布局配置（自定义布局中声明组件）
• 配置文件索引
• 组件配色与主题样式

【免费下载链接】bottomYet another cross-platform graphical process/system monitor.项目地址: https://gitcode.com/GitHub_Trending/bo/bottom