🔋 iOS 电池指示器

一个复刻 iOS 原生电池指示器的 Flutter 组件，支持 iOS 27 风格以及自动监测系统电池。

Language: English | 中文

✨ 特性

• 原生 iOS 外观 — 精确复刻 iOS 电池图标，采用圆角超椭圆形状和合适的尺寸。
• 自动读取系统电池 — 未手动指定时，实时从设备读取电池电量、充电状态和低功耗模式。
• 系统事件回调 — onBatteryLevelChanged 和 onBatteryStateChanged 在自动模式下通知父组件系统值变化。
• 手动控制 — 可选择性传入 batteryLevel、batteryState 和 isInBatterySaveMode 用于演示或自定义场景。
• iOS 27 风格 — 支持 iOS 27 引入的无边框设计，可自动检测 iOS 版本。
• 充电闪电图标 — 充电时使用原生 Cupertino 图标字体渲染闪电 (⚡) 符号。
• 镂空百分比 — 在正常放电模式下，百分比文字通过镂空效果穿透填充区域，呈现精致的外观。
• 低电量警告 — 电量低于可配置阈值（10–30，默认 20）时，指示器变为红色。
• 省电模式 — 低功耗模式激活时，电池轨道变为黄色。
• 省电模式实时监控 — monitorBatterySaveMode 轮询系统低功耗模式（仅自动模式；轮询间隔可通过
  saveModePollInterval 配置，默认 30 秒；仅支持 Android、iOS、macOS 和 Windows，web 及其他平台不支持）。
• 亮色 / 深色模式 — 自动适配环境的 Brightness，也可通过 brightness 属性强制指定。
• 流畅动画 — 填充进度、颜色变化、充电闪电图标切换以及基础/百分比显示之间的交叉淡入淡出，所有动画时长均可通过
  animationDuration 配置。
• 充电音效 — 在手动模式下进入充电状态时，可选择播放 iOS 原生充电音效（connectedToPower），仅限 iOS
  平台支持。

🚀 快速开始

通过 pub.dev 安装 → pub.dev/packages/ios_battery_indicator/install

在线演示 — 立即体验

⚙️ 平台配置

此包依赖 battery_plus 和 device_info_plus。iOS 和 macOS 无需额外配置。Android 需确保
android/app/build.gradle.kts 目标 API 21 或更高（Flutter 默认模板已满足此要求）。

📖 使用示例

🤖 自动模式（系统电池）

最简单的用法 — 组件从设备读取所有信息：

IosBatteryIndicator();

可配置系统电量轮询间隔（默认 30 秒）：

IosBatteryIndicator(
  batteryLevelPollInterval: const Duration(seconds: 15), // 电量轮询间隔（默认 30 秒）
);

• 默认开启电池百分比显示。
• 监听 Battery.onBatteryStateChanged 以获取实时状态更新。
• 自动检测 iOS 27+ 并渲染无边框风格。

🎮 手动控制

提供明确的值：

IosBatteryIndicator(
  batteryLevel: 80,
  batteryState: BatteryState.charging,
);

🎛️ 控制显示选项

IosBatteryIndicator(
  showBatteryPercentage: false,  // 隐藏百分比数字
  fontFeatures: const [.tabularFigures()],  // 默认值：等宽数字（仅 showBatteryPercentage 为 true 时生效）
  chargingWithBolt: false,  // 充电时隐藏闪电图标
);

🔊 充电音效（仅 iOS）

在手动模式下，将电池状态设置为 BatteryState.charging 时可播放 iOS 原生充电音效：

IosBatteryIndicator(
  batteryState: BatteryState.charging,
  playChargingSound: true,   // 播放 iOS 充电音效
);

[!NOTE]
此功能依赖 ios_system_sound
且仅支持 iOS 平台。在 Web 或其他平台上无效，自动模式（batteryState 为 null）下不播放。

🎨 样式设置

IosBatteryIndicator(
  isIOS27Style: true,             // 强制 iOS 27 无边框风格
  brightness: Brightness.dark,    // 强制深色模式颜色
  lowBatteryThreshold: 15,        // 电量 ≤ 15% 时变红
  animationDuration: const Duration(milliseconds: 500),  // 放慢动画速度
);

📐 尺寸设置

使用 height 或 width（互斥）来缩放：

IosBatteryIndicator(height: 36);   // 36 逻辑像素高，宽度自适应

IosBatteryIndicator(width: 40);   // 40 逻辑像素宽，高度自适应

📡 回调

在自动模式下接收系统电池实时更新：

IosBatteryIndicator(
  onBatteryLevelChanged: (level) => print('电量: $level%'),
  onBatteryStateChanged: (state) => print('状态: $state'),
);

[!NOTE]
回调仅在 batteryLevel / batteryState 为 null（系统模式）时触发。
手动传入值时请使用自己的状态管理。

🔋 省电模式实时监控

默认情况下，系统低功耗模式仅在组件初始化时读取一次。若希望在用户运行时切换低功耗模式时保持同步，可开启
monitorBatterySaveMode —— 该选项仅在 isInBatterySaveMode 为 null（系统模式）时生效。注意此功能仅支持
Android、iOS、macOS 和 Windows，在 web 及其他平台无效：

IosBatteryIndicator(
  isInBatterySaveMode: null,         // 从系统读取
  monitorBatterySaveMode: true,      // 定期重新轮询
  saveModePollInterval: const Duration(seconds: 10), // 轮询间隔（默认 30 秒）
);

[!NOTE]
当显式传入 isInBatterySaveMode 时，此选项不生效。

🖌️ 自定义主题

可通过 ThemeData.extensions 提供 BatteryIndicatorTheme 来自定义颜色：

MaterialApp(
  theme: ThemeData(
    extensions: [
      BatteryIndicatorTheme(
        bgColor: CupertinoColors.black.withValues(alpha: .3),
        dischargingTrackColor: CupertinoColors.black,
        chargingTrackColor: CupertinoColors.activeGreen,
        criticallyLowTrackColor: CupertinoColors.destructiveRed,
        saveModeTrackColor: CupertinoColors.systemYellow,
        contentColor: CupertinoColors.black,
        contentAntiColor: CupertinoColors.white,
      ),
    ],
  ),
  home: /* ... */,
);

对于 Cupertino 应用，将指示器包裹在 Theme 组件中或使用 CupertinoThemeData 扩展。

📚 API 参考

🧩 IosBatteryIndicator

属性	类型	默认值	描述
height	double?	null	首选高度，与 width 互斥。
width	double?	null	首选宽度，与 height 互斥。
batteryLevel	int?	null	电池电量 0–100，为 null 时从系统读取。
batteryLevelPollInterval	Duration	30s	系统模式下电量轮询间隔。
batteryState	BatteryState?	null	充电 / 放电 / 已满。为 null 时从系统读取。
showBatteryPercentage	bool	true	是否在指示器内显示百分比数字。
fontFeatures	List<FontFeature>?	[.tabularFigures()]	百分比数字的字体特性。仅在 showBatteryPercentage 为 true 时生效。当电量恰好为 100% 时，会移除列表中的 tabularFigures 特性（保留其他特性）。
isInBatterySaveMode	bool?	null	低功耗模式。为 null 时从系统读取。
monitorBatterySaveMode	bool	false	当 isInBatterySaveMode 为 null 时轮询系统低功耗模式。仅支持 Android、iOS、macOS 和 Windows（web 及其他平台无效）。
saveModePollInterval	Duration	30s	省电模式轮询间隔。
lowBatteryThreshold	int	20	低电量阈值（10–30），低于此值时指示器变红。
chargingWithBolt	bool	true	充电时是否显示闪电图标。仅在 batteryState 为 .charging 时生效。
playChargingSound	bool	false	手动模式下播放 iOS 充电音效（仅 iOS）。
isIOS27Style	bool?	null	强制 iOS 27 风格。为 null 时自动检测 iOS 版本。
brightness	Brightness?	null	强制亮色或深色。为 null 时使用环境亮度。
animationDuration	Duration	Duration(milliseconds: 250)	电池指示器动画时长（填充、颜色、闪电图标等）。
themeAnimationDuration	Duration	kThemeAnimationDuration	主题切换的动画时长。
onBatteryLevelChanged	ValueChanged<int>?	null	系统电量变化回调（仅系统模式）。
onBatteryStateChanged	ValueChanged<BatteryState>?	null	系统充电状态变化回调（仅系统模式）。

🎨 BatteryIndicatorTheme

属性	类型	描述
bgColor	Color	电池外壳的背景/边框颜色。
dischargingTrackColor	Color	放电（正常状态）时的填充颜色。
chargingTrackColor	Color	充电时的填充颜色，默认 CupertinoColors.activeGreen。
criticallyLowTrackColor	Color	电量极低时的填充颜色，默认 CupertinoColors.destructiveRed。
saveModeTrackColor	Color	省电模式时的填充颜色，默认 CupertinoColors.systemYellow。
contentColor	Color	用于闪电图标和镂空文字描边的颜色。
contentAntiColor	Color	纯色模式下百分比文字的颜色。

工厂构造函数 BatteryIndicatorTheme.light() 和 BatteryIndicatorTheme.dark() 提供了合理的默认值。

完整 API 参考见：BatteryIndicatorTheme 类。

👁️ 视觉状态

状态	外观
正常放电	外壳边框 + 与电量成比例的实心填充。
充电中	绿色填充 + 闪电图标（如果 chargingWithBolt 为 true）。
已满（100%）	绿色填充，无闪电图标。
低电量（≤ 阈值）	红色填充，纯色（无镂空）。
省电模式	黄色填充。

ℹ️ 更多信息

• 仓库: github.com/runoob-coder/ios_battery_indicator
• 问题反馈: github.com/runoob-coder/ios_battery_indicator/issues
• 示例应用: 查看 example/ 目录获取完整的交互式演示，可实时调整每个属性。
• 贡献: 欢迎提交 Pull Request 和 Issue！

💛 支持

如果 ios_battery_indicator 帮助了你，请考虑支持它，只需几秒即可帮助更多 Flutter 开发者发现此库。

• ⭐ GitHub 上点星
• 👍 pub.dev 上点赞

☕️ 请我喝咖啡