# ios_battery_indicator

**Repository Path**: noob-coder/ios_battery_indicator

## Basic Information

- **Project Name**: ios_battery_indicator
- **Description**: A Flutter widget that replicates the native iOS battery indicator, including support for iOS 27 style and automatic system battery monitoring.
- **Primary Language**: Dart
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://github.com/runoob-coder/ios_battery_indicator
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-03
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Flutter

## README

# 🔋 iOS 电池指示器

<div align="center">
  <a href="https://runoob-coder.github.io/ios_battery_indicator/" target="_blank" rel="noopener"> 
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/runoob-coder/ios_battery_indicator/master/example/web/icons/battery_dark.svg">
      <img src="https://raw.githubusercontent.com/runoob-coder/ios_battery_indicator/master/example/web/icons/battery.svg" width="200" style="width: 200px;" alt="ios_battery_indicator">
    </picture>
  </a>
</div>

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

[![Pub Version](https://img.shields.io/pub/v/ios_battery_indicator.svg)](https://pub.dev/packages/ios_battery_indicator)
[![API Reference](https://img.shields.io/badge/API-Reference-0175C2.svg)](https://pub-web.flutter-io.cn/documentation/ios_battery_indicator/latest/)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/runoob-coder/ios_battery_indicator)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Flutter Demo](https://img.shields.io/badge/demo-Flutter-brightgreen.svg)][preview]
[![CI](https://img.shields.io/github/actions/workflow/status/runoob-coder/ios_battery_indicator/deploy_web.yml?label=CI)](https://github.com/runoob-coder/ios_battery_indicator/actions/workflows/deploy_web.yml)
[![GitHub stars](https://img.shields.io/github/stars/runoob-coder/ios_battery_indicator.svg?style=social)](https://github.com/runoob-coder/ios_battery_indicator)

Language: [English](README.md) | 中文

| [![iOS Battery Indicator][states-with-percentage-img]][preview] | [![iOS Battery Indicator][states-no-percentage-img]][preview] | [![iOS Battery Indicator][states-ios-27-img]][preview] |
|-----------------------------------------------------------------|---------------------------------------------------------------|--------------------------------------------------------|

## ✨ 特性

- **原生 iOS 外观** — 精确复刻 iOS 电池图标，采用圆角超椭圆形状和合适的尺寸。
- **自动读取系统电池** — 未手动指定时，实时从设备读取电池电量、充电状态和低功耗模式。
- **系统事件回调** — `onBatteryLevelChanged` 和 `onBatteryStateChanged` 在自动模式下通知父组件系统值变化。
- **手动控制** — 可选择性传入 `batteryLevel`、`batteryState` 和 `isInBatterySaveMode` 用于演示或自定义场景。
- **iOS 27 风格** — 支持 iOS 27 引入的无边框设计，可自动检测 iOS 版本。
- **充电闪电图标** — 充电时使用原生 Cupertino 图标字体渲染闪电 (⚡) 符号。
- **镂空百分比** — 在正常未充电模式下，百分比文字通过镂空效果穿透填充区域，呈现精致的外观。
- **原生 SF Pro 字体** — 内置打包 SF Pro 字体，电池百分比在各个平台中与 iOS 原生排版一致。
- **低电量警告** — 电量低于可配置阈值（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](https://pub-web.flutter-io.cn/packages/ios_battery_indicator/install)

[在线演示](https://runoob-coder.github.io/ios_battery_indicator/) — 立即体验

### ⚙️ 平台配置

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

## 📖 使用示例

### 🤖 自动模式（系统电池）

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

```dart
IosBatteryIndicator();
```

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

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

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

### 🎮 手动控制

提供明确的值：

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

### 🎛️ 控制显示选项

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

### 🔊 充电音效（仅 iOS）

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

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

> [!NOTE]
> 此功能依赖 [ios_system_sound](https://pub-web.flutter-io.cn/packages/ios_system_sound)
> 且仅支持 iOS 平台。在 Web 或其他平台上无效，自动模式（`batteryState` 为 `null`）下不播放。

### 🎨 样式设置

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

### 📐 尺寸设置

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

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

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

### 📡 回调

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

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

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

### 🔋 省电模式实时监控

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

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

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

### 🖌️ 自定义主题

可通过 `ThemeData.extensions` 提供 [`BatteryIndicatorTheme`](https://pub-web.flutter-io.cn/documentation/ios_battery_indicator/latest/ios_battery_indicator/BatteryIndicatorTheme-class.html) 来自定义颜色：

```dart
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 参考](https://pub-web.flutter-io.cn/documentation/ios_battery_indicator/latest/)

### 🧩 [`IosBatteryIndicator`](https://pub-web.flutter-io.cn/documentation/ios_battery_indicator/latest/ios_battery_indicator/IosBatteryIndicator-class.html)

| 属性                         | 类型                            | 默认值                           | 描述                                                                                                    |
|----------------------------|-------------------------------|-------------------------------|-------------------------------------------------------------------------------------------------------|
| `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`](https://pub-web.flutter-io.cn/documentation/ios_battery_indicator/latest/ios_battery_indicator/BatteryIndicatorTheme-class.html)

| 属性                        | 类型      | 描述                                              |
|---------------------------|---------|-------------------------------------------------|
| `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` 类](https://pub-web.flutter-io.cn/documentation/ios_battery_indicator/latest/ios_battery_indicator/BatteryIndicatorTheme-class.html)。

### 👁️ 视觉状态

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

## ℹ️ 更多信息

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

## 💛 支持

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

- ⭐ [GitHub 上点星](https://github.com/runoob-coder/ios_battery_indicator)
- 👍 [pub.dev 上点赞](https://pub.dev/packages/ios_battery_indicator)

## ☕️ 请我喝咖啡

<a href="https://ko-fi.com/noob_coder" target="_blank">
  <img src="https://storage.ko-fi.com/cdn/kofi6.png" alt="Buy Me a Coffee at ko-fi.com" />
</a>

[preview]: https://runoob-coder.github.io/ios_battery_indicator/
[states-with-percentage-img]: https://github.com/runoob-coder/ios_battery_indicator/raw/master/screenshots/battery-states-with-percentage.png
[states-no-percentage-img]: https://github.com/runoob-coder/ios_battery_indicator/raw/master/screenshots/battery-states-no-percentage.png
[states-ios-27-img]: https://github.com/runoob-coder/ios_battery_indicator/raw/master/screenshots/battery-states-ios-27.png