基础入门 Flutter for OpenHarmony：battery_plus 电池状态监控详解

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
🎯 欢迎来到 Flutter for OpenHarmony 社区！本文将深入讲解 Flutter 中 battery_plus 电池状态监控插件的使用方法，带你全面掌握获取电池电量、电池状态、节能模式等功能。

---

一、battery_plus 组件概述

在移动应用开发中，电池状态是一个重要的系统信息。battery_plus 是 Flutter 社区官方维护的电池信息获取插件，提供了跨平台的电池状态监控能力。开发者可以通过该插件获取设备电池电量、充电状态，以及监听电池状态变化，从而实现根据电池状态优化应用行为的功能。

📋 battery_plus 组件特点

特点	说明
跨平台支持	支持 Android、iOS、macOS、Web、Linux、Windows、OpenHarmony
电量获取	获取当前电池电量百分比（0-100）
状态获取	获取电池状态（充电中、放电中、满电、未知）
状态监听	实时监听电池状态变化
节能模式检测	检测设备是否处于节能模式
单例模式	使用单例模式确保资源高效利用
鸿蒙适配	完整支持 OpenHarmony 平台

电池状态枚举

battery_plus 使用 BatteryState 枚举来表示电池的不同状态：

状态	说明
full	电池处于满电状态
charging	电池处于充电状态
discharging	电池处于耗电状态
unknown	电池处于未知状态

💡 使用场景：低电量模式优化、后台任务调度、游戏性能调节、下载任务管理等需要根据电池状态调整应用行为的场景。

---

二、OpenHarmony 平台适配说明

2.1 兼容性信息

本项目基于 battery_plus 官方插件开发，已在以下版本测试通过：

Flutter 版本	SDK 版本	IDE 版本	ROM 版本
3.7.12-ohos-1.0.6	5.0.0(12)	DevEco Studio 5.0.13.200	5.1.0.120 SP3
3.22.1-ohos-1.0.1	5.0.0(12)	DevEco Studio 5.0.13.200	5.1.0.120 SP3
3.27.5-ohos-0.0.2	5.0.0(12)	DevEco Studio 5.0.13.200	5.1.0.120 SP3

2.2 支持的功能

在 OpenHarmony 平台上，battery_plus 支持以下功能：

功能	说明	OpenHarmony 支持
batteryLevel	获取电池等级	✅ yes
isInBatterySaveMode	判断是否处于节能模式	✅ yes
batteryState	获取电池状态	✅ yes
onBatteryStateChanged	监听电池状态改变	✅ yes
BatteryState.full	满电状态	✅ yes
BatteryState.charging	充电状态	✅ yes
BatteryState.discharging	放电状态	✅ yes
BatteryState.unknown	未知状态	✅ yes

---

三、项目配置与安装

3.1 添加依赖配置

首先，需要在你的 Flutter 项目的 pubspec.yaml 文件中添加 battery_plus 依赖。

打开项目根目录下的 pubspec.yaml 文件，找到 dependencies 部分，添加以下配置：

dependencies:
  flutter:
    sdk: flutter

  # 添加 battery_plus 依赖（OpenHarmony 适配版本）
  battery_plus:
    git:
      url: https://atomgit.com/openharmony-sig/flutter_plus_plugins.git
      path: packages/battery_plus/battery_plus

配置说明：

• 使用 git 方式引用开源鸿蒙适配的 flutter_plus_plugins 仓库
• url：指定 GitCode 托管的仓库地址
• path：指定 battery_plus 包的具体路径
• battery_plus 是 Flutter Community 官方维护的插件，OpenHarmony 版本完整支持所有功能

3.2 下载依赖

配置完成后，需要在项目根目录执行以下命令下载依赖：

flutter pub get

执行成功后，你会看到类似以下的输出：

Running "flutter pub get" in my_cross_platform_app...
Resolving dependencies...
Got dependencies!

3.3 权限配置

在 OpenHarmony 平台上，使用 battery_plus 获取电池信息不需要额外配置权限。该插件使用系统公开的电池信息接口，无需申请特殊权限。

---

四、battery_plus 基础用法

4.1 导入库

在使用 battery_plus 之前，需要先导入库：

import 'package:battery_plus/battery_plus.dart';

4.2 创建 Battery 实例

battery_plus 使用单例模式，通过工厂构造函数获取实例：

final Battery _battery = Battery();

4.3 获取电池电量

使用 batteryLevel 属性获取当前电池电量百分比：

Future<int> _getBatteryLevel() async {
  final batteryLevel = await _battery.batteryLevel;
  return batteryLevel;
}

返回值为 0-100 的整数，表示电池电量百分比。

4.4 获取电池状态

使用 batteryState 属性获取当前电池状态：

Future<BatteryState> _getBatteryState() async {
  final state = await _battery.batteryState;
  return state;
}

返回值为 BatteryState 枚举，可能的状态包括：

• BatteryState.full：满电状态
• BatteryState.charging：充电中
• BatteryState.discharging：放电中
• BatteryState.unknown：未知状态

4.5 检测节能模式

使用 isInBatterySaveMode 属性检测设备是否处于节能模式：

Future<bool> _isInBatterySaveMode() async {
  final isInSaveMode = await _battery.isInBatterySaveMode;
  return isInSaveMode;
}

返回 true 表示设备处于节能模式，false 表示未处于节能模式。

4.6 监听电池状态变化

使用 onBatteryStateChanged 流监听电池状态的实时变化：

StreamSubscription<BatteryState>? _batteryStateSubscription;

void _startListening() {
  _batteryStateSubscription = _battery.onBatteryStateChanged.listen((BatteryState state) {
    print('电池状态变化: $state');
  });
}

void _stopListening() {
  _batteryStateSubscription?.cancel();
}

⚠️ 注意：监听电池状态变化时，记得在不需要时取消订阅，避免内存泄漏。

---

五、完整示例：电池状态监控应用

下面是一个完整的示例，展示如何实现电池状态监控功能：

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:battery_plus/battery_plus.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Battery Plus Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
        useMaterial3: true,
      ),
      home: const HomePage(),
    );
  }
}

class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final Battery _battery = Battery();

  int _batteryLevel = 0;
  BatteryState _batteryState = BatteryState.unknown;
  bool _isInBatterySaveMode = false;
  StreamSubscription<BatteryState>? _batteryStateSubscription;

  @override
  void initState() {
    super.initState();
    _initBatteryInfo();
    _listenBatteryState();
  }

  Future<void> _initBatteryInfo() async {
    final level = await _battery.batteryLevel;
    final state = await _battery.batteryState;
    final saveMode = await _battery.isInBatterySaveMode;

    setState(() {
      _batteryLevel = level;
      _batteryState = state;
      _isInBatterySaveMode = saveMode;
    });
  }

  void _listenBatteryState() {
    _batteryStateSubscription = _battery.onBatteryStateChanged.listen((state) {
      setState(() {
        _batteryState = state;
      });
    });
  }

  String _getBatteryStateText(BatteryState state) {
    switch (state) {
      case BatteryState.full:
        return '满电';
      case BatteryState.charging:
        return '充电中';
      case BatteryState.discharging:
        return '放电中';
      case BatteryState.unknown:
        return '未知';
    }
  }

  IconData _getBatteryIcon(BatteryState state, int level) {
    if (state == BatteryState.charging) {
      return Icons.battery_charging_full;
    } else if (state == BatteryState.full) {
      return Icons.battery_full;
    } else if (level <= 20) {
      return Icons.battery_alert;
    } else {
      return Icons.battery_std;
    }
  }

  Color _getBatteryColor(int level) {
    if (level <= 20) {
      return Colors.red;
    } else if (level <= 50) {
      return Colors.orange;
    } else {
      return Colors.green;
    }
  }

  @override
  void dispose() {
    _batteryStateSubscription?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Battery Plus Demo'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            Card(
              child: Padding(
                padding: const EdgeInsets.all(24.0),
                child: Column(
                  children: [
                    Icon(
                      _getBatteryIcon(_batteryState, _batteryLevel),
                      size: 100,
                      color: _getBatteryColor(_batteryLevel),
                    ),
                    const SizedBox(height: 16),
                    Text(
                      '$_batteryLevel%',
                      style: const TextStyle(
                        fontSize: 48,
                        fontWeight: FontWeight.bold,
                      ),
                    ),
                    const SizedBox(height: 8),
                    Text(
                      '状态: ${_getBatteryStateText(_batteryState)}',
                      style: const TextStyle(fontSize: 18),
                    ),
                  ],
                ),
              ),
            ),
            const SizedBox(height: 16),
            Card(
              child: ListTile(
                leading: Icon(
                  _isInBatterySaveMode ? Icons.power : Icons.power_off,
                  color: _isInBatterySaveMode ? Colors.orange : Colors.grey,
                ),
                title: const Text('节能模式'),
                subtitle: Text(_isInBatterySaveMode ? '已开启' : '未开启'),
                trailing: Switch(
                  value: _isInBatterySaveMode,
                  onChanged: null,
                ),
              ),
            ),
            const SizedBox(height: 16),
            ElevatedButton.icon(
              icon: const Icon(Icons.refresh),
              label: const Text('刷新电池信息'),
              onPressed: _initBatteryInfo,
            ),
          ],
        ),
      ),
    );
  }
}

---

六、高级用法

6.1 根据电量优化应用行为

根据电池电量动态调整应用行为，例如在低电量时减少后台任务：

class BatteryAwareTaskManager {
  final Battery _battery = Battery();
  
  Future<void> executeTask() async {
    final batteryLevel = await _battery.batteryLevel;
    final isInSaveMode = await _battery.isInBatterySaveMode;
  
    if (batteryLevel < 20 || isInSaveMode) {
      print('低电量或节能模式，跳过非必要任务');
      return;
    }
  
    print('电量充足，执行后台任务');
  }
}

6.2 监听电池状态并更新 UI

使用 StreamBuilder 实现响应式的电池状态显示：

class BatteryStatusWidget extends StatelessWidget {
  final Battery _battery = Battery();

  BatteryStatusWidget({super.key});

  @override
  Widget build(BuildContext context) {
    return StreamBuilder<BatteryState>(
      stream: _battery.onBatteryStateChanged,
      builder: (context, snapshot) {
        final state = snapshot.data ?? BatteryState.unknown;
        return ListTile(
          leading: Icon(
            state == BatteryState.charging 
                ? Icons.battery_charging_full 
                : Icons.battery_std,
          ),
          title: Text('电池状态: ${state.name}'),
        );
      },
    );
  }
}

6.3 低电量警告提示

当电量低于阈值时显示警告对话框：

class LowBatteryWarning {
  final Battery _battery = Battery();
  StreamSubscription<BatteryState>? _subscription;
  static const int _warningThreshold = 20;

  void startMonitoring(BuildContext context) {
    _subscription = _battery.onBatteryStateChanged.listen((state) async {
      if (state == BatteryState.discharging) {
        final level = await _battery.batteryLevel;
        if (level < _warningThreshold) {
          _showWarningDialog(context, level);
        }
      }
    });
  }

  void _showWarningDialog(BuildContext context, int level) {
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: const Text('低电量警告'),
        content: Text('当前电量仅剩 $level%，请及时充电'),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: const Text('知道了'),
          ),
        ],
      ),
    );
  }

  void stopMonitoring() {
    _subscription?.cancel();
  }
}

6.4 充电状态检测

检测设备是否正在充电，用于决定是否执行耗电操作：

Future<bool> isCharging() async {
  final battery = Battery();
  final state = await battery.batteryState;
  return state == BatteryState.charging || state == BatteryState.full;
}

Future<void> performHeavyTask() async {
  if (await isCharging()) {
    print('正在充电，可以执行耗电任务');
  } else {
    print('未在充电，建议推迟耗电任务');
  }
}

---

七、常见问题与解决方案

7.1 电池状态返回 unknown

问题 ：在某些设备上，batteryState 返回 BatteryState.unknown。

解决方案：这通常发生在模拟器或某些特殊设备上。建议：

1. 在真机上测试
2. 对 unknown 状态进行容错处理

String getSafeStateText(BatteryState state) {
  return state == BatteryState.unknown ? '无法获取' : state.name;
}

7.2 电池状态监听不触发

问题 ：onBatteryStateChanged 流没有触发回调。

解决方案：

1. 确保在 initState 或合适的生命周期中启动监听
2. 检查是否在 dispose 中取消了订阅
3. 某些设备可能不会频繁触发状态变化

7.3 节能模式检测不准确

问题 ：isInBatterySaveMode 返回值与系统设置不一致。

解决方案：确保使用的是最新版本的适配插件，OpenHarmony 平台的节能模式检测依赖于系统 API。

---

八、最佳实践

8.1 单例使用

Battery 类设计为单例模式，建议在应用中只创建一个实例：

class BatteryService {
  static final Battery _instance = Battery();
  
  static Battery get instance => _instance;
}

final battery = BatteryService.instance;

8.2 及时取消订阅

监听电池状态变化时，务必在组件销毁时取消订阅：

@override
void dispose() {
  _batteryStateSubscription?.cancel();
  super.dispose();
}

8.3 结合其他信息优化体验

将电池信息与网络状态、应用状态等结合，实现更智能的资源管理：

Future<bool> shouldPerformSync() async {
  final battery = Battery();
  final level = await battery.batteryLevel;
  final state = await battery.batteryState;
  final isInSaveMode = await battery.isInBatterySaveMode;
  
  return level > 30 && 
         state != BatteryState.discharging && 
         !isInSaveMode;
}

---

九、总结

battery_plus 是 Flutter 社区官方维护的电池状态监控插件，提供了完整的电池信息获取能力。在 OpenHarmony 平台上，该插件完整支持所有功能，包括电量获取、状态检测、节能模式判断和状态变化监听。

通过本文的学习，你应该已经掌握了：

• battery_plus 的基本使用方法
• 如何获取电池电量、状态和节能模式信息
• 如何监听电池状态的实时变化
• 如何根据电池状态优化应用行为

在实际开发中，合理利用电池信息可以显著提升用户体验，特别是在需要执行后台任务或耗电操作时，根据电池状态做出智能决策是一个好的实践。

---

参考资料

• battery_plus OpenHarmony 适配仓库
• battery_plus 官方文档
• Flutter for OpenHarmony 官方文档