跳到主要内容

设备电量（TSBattery）

TSBattery 模块提供设备电池信息查询及电量变化监听能力，支持单电池设备（手表、单电池眼镜等）和多电池设备（耳机左右耳/充电盒、左右分体眼镜、带麦克风/扬声器的头戴式设备等）。

前提条件​

  1. 已成功集成 TopStepComKit iOS SDK，并完成基础初始化。
  2. 已通过蓝牙完成设备连接，且设备处于在线状态。
  3. 在调用接口前已获得 TSBatteryInterface 协议对象的实例。

数据模型​

TSBatteryModel​

设备电池信息模型，包含电量百分比、充电状态和电池所属部件。

属性名类型说明
chargeStateTSBatteryState设备当前的充电状态
percentageUInt8电池电量百分比（0-100）
partTSBatteryPart电池所属的物理部件标识

构造方法：

方法说明
- initWithPercentage:chargeState:单电池设备便捷构造器，part 默认为 TSBatteryPartMain
- initWithPart:percentage:chargeState:指定构造器，用于多电池设备每个物理电池实例
- partName返回部件可读英文名称（如 "Main"、"Left"），不会为 nil

枚举与常量​

TSBatteryState（电池充电状态）​

枚举值说明
TSBatteryStateUnknown充电状态未知
TSBatteryStateCharging已连接电源并正在充电
TSBatteryStateUnConnectNoCharging未连接电源
TSBatteryStateConnectNotCharging已连接电源但未充电
TSBatteryStateFull电池已充满

TSBatteryPart（电池部件标识）​

枚举值说明
TSBatteryPartUnknown未知部件
TSBatteryPartMain主电池（手表、单电池眼镜等）
TSBatteryPartLeft左侧部件（耳机左耳、左镜腿等）
TSBatteryPartRight右侧部件（耳机右耳、右镜腿等）
TSBatteryPartCase充电盒
TSBatteryPartMic麦克风
TSBatteryPartMainSpeaker主扬声器
TSBatteryPartSideSpeaker副扬声器
TSBatteryPartOther其他部件

回调类型​

类型定义说明
TSBatteryBlockvoid (^)(TSBatteryModel * _Nullable batteryModel, NSError * _Nullable error)单电池信息回调，多电池设备监听场景下每次回调对应单个部件
TSBatteriesBlockvoid (^)(NSArray<TSBatteryModel *> * _Nullable batteryModels, NSError * _Nullable error)多部件电池信息数组回调

接口方法​

获取总览电池信息​

- (void)getBatteryInfoCompletion:(nullable TSBatteryBlock)completion;
参数类型说明
completionTSBatteryBlock获取完成回调，返回总览电池模型；多电池设备将返回电量最低的部件

代码示例：

id<TSBatteryInterface> battery = [TSComKit battery];
[battery getBatteryInfoCompletion:^(TSBatteryModel * _Nullable batteryModel, NSError * _Nullable error) {
    if (error) {
        TSLog(@"获取电池信息失败: %@", error.localizedDescription);
        return;
    }
    TSLog(@"总览电量: %d%%, 充电状态: %d, 部件: %@",
          batteryModel.percentage, batteryModel.chargeState, [batteryModel partName]);
}];

获取所有部件的电池信息​

- (void)getAllBatteriesInfoCompletion:(nullable TSBatteriesBlock)completion;
参数类型说明
completionTSBatteriesBlock完成回调，返回所有部件电池模型数组，单电池设备返回只含一个元素的数组

代码示例：

id<TSBatteryInterface> battery = [TSComKit battery];
[battery getAllBatteriesInfoCompletion:^(NSArray<TSBatteryModel *> * _Nullable batteryModels, NSError * _Nullable error) {
    if (error) {
        TSLog(@"获取多电池信息失败: %@", error.localizedDescription);
        return;
    }
    for (TSBatteryModel *model in batteryModels) {
        TSLog(@"部件: %@, 电量: %d%%, 充电状态: %d",
              [model partName], model.percentage, model.chargeState);
    }
}];

注册电池信息变化监听​

- (void)registerBatteryDidChanged:(nullable TSBatteryBlock)completion;
参数类型说明
completionTSBatteryBlock电池信息变化时的回调，多电池设备每个部件变化时各回调一次

代码示例：

id<TSBatteryInterface> battery = [TSComKit battery];
[battery registerBatteryDidChanged:^(TSBatteryModel * _Nullable batteryModel, NSError * _Nullable error) {
    if (error) {
        TSLog(@"电池监听异常: %@", error.localizedDescription);
        return;
    }
    switch (batteryModel.part) {
        case TSBatteryPartLeft:
            TSLog(@"左耳电量更新: %d%%", batteryModel.percentage);
            break;
        case TSBatteryPartRight:
            TSLog(@"右耳电量更新: %d%%", batteryModel.percentage);
            break;
        case TSBatteryPartCase:
            TSLog(@"充电盒电量更新: %d%%", batteryModel.percentage);
            break;
        default:
            TSLog(@"%@ 电量更新: %d%%", [batteryModel partName], batteryModel.percentage);
            break;
    }
}];

注意事项​

  1. 调用所有接口前必须确保设备已连接，否则回调将返回错误。
  2. getBatteryInfoCompletion: 在多电池设备上返回电量最低的部件，适用于顶部状态栏等总览展示；如需逐个部件展示，请使用 getAllBatteriesInfoCompletion:。
  3. registerBatteryDidChanged: 对多电池设备会针对每个变化的部件分别回调一次，UI 更新时务必通过 batteryModel.part 区分对应部件。
  4. percentage 取值范围为 0-100，使用前请确认数值有效；chargeState 为 TSBatteryStateUnknown 时建议在 UI 上做兜底处理。
  5. partName 仅返回英文名称，仅适用于日志或调试 UI；面向终端用户展示请基于 part 值自行本地化。
  6. TSBatteryModel 禁止使用 init、new、copy，请使用提供的构造方法创建实例。