心率（TSHeartRate）

该模块提供心率测量、自动监测、历史数据同步和静息心率分析的方法。用户可以进行手动心率测量、配置自动监测参数、同步各类心率历史数据，并查询设备对不同心率功能的支持情况。

前提条件

设备已通过蓝牙连接并完成配对
设备支持相应的心率功能（通过相关 isSupport* 方法确认）
用户已授予应用必要的健康数据访问权限
网络连接正常（用于数据同步）

数据模型

TSHRValueItem（心率测量条目）

属性名	类型	说明
`hrValue`	`UInt8`	心率值，单位为每分钟心跳次数（BPM）
`isUserInitiated`	`BOOL`	指示测量是否为用户主动发起
`startTime`	`NSTimeInterval`	测量开始时间戳（秒）
`endTime`	`NSTimeInterval`	测量结束时间戳（秒）
`duration`	`NSTimeInterval`	测量持续时间（秒）
`valueType`	`TSItemValueType`	数据类型（普通、最大值、最小值、静息等）

TSHRDailyModel（每日心率聚合数据）

属性名	类型	说明
`maxHRItem`	`TSHRValueItem *`	当天最大心率条目
`minHRItem`	`TSHRValueItem *`	当天最小心率条目
`restingItems`	`NSArray<TSHRValueItem > `	当天静息心率条目数组（按时间升序）
`manualItems`	`NSArray<TSHRValueItem > `	用户主动测量的心率条目数组（按时间升序）
`autoItems`	`NSArray<TSHRValueItem > `	设备自动监测的心率条目数组（按时间升序）
`dayStartTime`	`NSTimeInterval`	当天开始时间戳（秒）

接口方法

能力查询方法

查询心率预警监测支持情况

- (BOOL)isSupportHeartRateAlert;

说明： 检查设备是否支持心率预警监测。心率预警监测允许设备在用户心率超出正常范围或达到潜在危险水平时通知用户。

参数	类型	说明
返回值	`BOOL`	设备支持则返回 `YES`，否则返回 `NO`

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
if ([hrInterface isSupportHeartRateAlert]) {
    TSLog(@"设备支持心率预警监测");
} else {
    TSLog(@"设备不支持心率预警监测");
}

查询加强心率监测支持情况

- (BOOL)isSupportEnhancedMonitoring;

说明： 检查设备是否支持加强心率监测。加强监测提供更频繁和准确的测量，但通常消耗更多电池。

参数	类型	说明
返回值	`BOOL`	设备支持则返回 `YES`，否则返回 `NO`

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
if ([hrInterface isSupportEnhancedMonitoring]) {
    TSLog(@"设备支持加强心率监测");
}

查询手动心率测量支持情况

- (BOOL)isSupportActivityMeasureByUser;

说明： 检查设备是否支持用户手动测量心率。

参数	类型	说明
返回值	`BOOL`	设备支持则返回 `YES`，否则返回 `NO`

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
if ([hrInterface isSupportActivityMeasureByUser]) {
    TSLog(@"设备支持用户手动测量心率");
}

查询自动心率监测支持情况

- (BOOL)isSupportAutomaticMonitoring;

说明： 检查设备是否支持自动心率监测。

参数	类型	说明
返回值	`BOOL`	设备支持则返回 `YES`，否则返回 `NO`

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
if ([hrInterface isSupportAutomaticMonitoring]) {
    TSLog(@"设备支持自动心率监测");
}

查询安静心率预警支持情况

- (BOOL)isSupportRestHRAlert;

说明： 检查设备是否支持安静心率异常预警。当返回 YES 时，可以通过 TSAutoMonitorHRConfigs 配置安静心率预警的上下限。

参数	类型	说明
返回值	`BOOL`	设备支持则返回 `YES`，否则返回 `NO`

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
if ([hrInterface isSupportRestHRAlert]) {
    TSLog(@"设备支持安静心率预警");
}

查询运动心率预警支持情况

- (BOOL)isSupportExerciseHRAlert;

说明： 检查设备是否支持运动心率异常预警。当返回 YES 时，可以通过 TSAutoMonitorHRConfigs 配置运动心率预警的上下限。

参数	类型	说明
返回值	`BOOL`	设备支持则返回 `YES`，否则返回 `NO`

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
if ([hrInterface isSupportExerciseHRAlert]) {
    TSLog(@"设备支持运动心率预警");
}

查询监测时间段配置支持情况

- (BOOL)isSupportMonitorScheduleTime;

说明： 检查设备是否支持配置心率监测的起始和结束时间。当返回 YES 时，TSMonitorSchedule 的 startTime 和 endTime 字段有效。

参数	类型	说明
返回值	`BOOL`	设备支持则返回 `YES`，否则返回 `NO`

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
if ([hrInterface isSupportMonitorScheduleTime]) {
    TSLog(@"设备支持配置监测时间段");
}

查询监测间隔配置支持情况

- (BOOL)isSupportMonitorScheduleInterval;

说明： 检查设备是否支持配置心率监测的时间间隔。当返回 YES 时，TSMonitorSchedule 的 interval 字段有效。

参数	类型	说明
返回值	`BOOL`	设备支持则返回 `YES`，否则返回 `NO`

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
if ([hrInterface isSupportMonitorScheduleInterval]) {
    TSLog(@"设备支持配置监测间隔");
}

查询静息心率监测支持情况

- (BOOL)isSupportRestingHeartRate;

说明： 检查设备是否支持静息心率监测。静息心率是在完全休息时（通常在睡眠期间）测量的心率，是心血管健康和健身水平的重要指标。

参数	类型	说明
返回值	`BOOL`	设备支持则返回 `YES`，否则返回 `NO`

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
if ([hrInterface isSupportRestingHeartRate]) {
    TSLog(@"设备支持静息心率监测");
}

心率测量方法

启动心率测量

- (void)startMeasureWithParam:(TSActivityMeasureParam *_Nonnull)measureParam
                 startHandler:(void(^_Nullable)(BOOL success, NSError * _Nullable error))startHandler
                  dataHandler:(void(^_Nullable)(TSHRValueItem * _Nullable data, NSError * _Nullable error))dataHandler
                   endHandler:(void(^_Nullable)(BOOL success, NSError * _Nullable error))endHandler;

说明： 使用指定参数启动心率测量，支持实时数据回调和测量状态监听。

参数	类型	说明
`measureParam`	`TSActivityMeasureParam *`	测量活动的参数配置
`startHandler`	`void (^)(BOOL, NSError *)`	测量启动回调，`success` 为测量是否成功启动，`error` 为失败时的错误信息
`dataHandler`	`void (^)(TSHRValueItem , NSError )`	实时数据回调，`data` 为实时心率数据，`error` 为接收失败时的错误信息
`endHandler`	`void (^)(BOOL, NSError *)`	测量结束回调，`success` 表示是否正常结束，`error` 为异常结束时的错误信息

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
TSActivityMeasureParam *param = [[TSActivityMeasureParam alloc] init];

[hrInterface startMeasureWithParam:param
                     startHandler:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"心率测量已启动");
    } else {
        TSLog(@"心率测量启动失败: %@", error.localizedDescription);
    }
} dataHandler:^(TSHRValueItem * _Nullable data, NSError * _Nullable error) {
    if (data) {
        TSLog(@"实时心率: %u BPM", data.hrValue);
    } else if (error) {
        TSLog(@"数据接收失败: %@", error.localizedDescription);
    }
} endHandler:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"心率测量正常结束");
    } else {
        TSLog(@"心率测量异常结束: %@", error.localizedDescription);
    }
}];

停止心率测量

- (void)stopMeasureCompletion:(nonnull TSCompletionBlock)completion;

说明： 停止正在进行的心率测量。

参数	类型	说明
`completion`	`TSCompletionBlock`	停止操作的完成回调

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
[hrInterface stopMeasureCompletion:^(NSError * _Nullable error) {
    if (error) {
        TSLog(@"停止测量失败: %@", error.localizedDescription);
    } else {
        TSLog(@"心率测量已停止");
    }
}];

自动监测配置方法

配置自动心率监测

- (void)pushAutoMonitorConfigs:(TSAutoMonitorHRConfigs *_Nonnull)configuration
                    completion:(nonnull TSCompletionBlock)completion;

说明： 将自动心率监测配置推送到设备。

参数	类型	说明
`configuration`	`TSAutoMonitorHRConfigs *`	自动监测配置参数
`completion`	`TSCompletionBlock`	配置设置完成回调

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
TSAutoMonitorHRConfigs *config = [[TSAutoMonitorHRConfigs alloc] init];
// 根据需要配置参数
config.enabled = YES;

[hrInterface pushAutoMonitorConfigs:config completion:^(NSError * _Nullable error) {
    if (error) {
        TSLog(@"配置设置失败: %@", error.localizedDescription);
    } else {
        TSLog(@"自动心率监测配置已设置");
    }
}];

获取自动心率监测配置

- (void)fetchAutoMonitorConfigsWithCompletion:(nonnull void (^)(TSAutoMonitorHRConfigs *_Nullable configuration, NSError *_Nullable error))completion;

说明： 从设备获取当前的自动心率监测配置。

参数	类型	说明
`completion`	`void (^)(TSAutoMonitorHRConfigs , NSError )`	配置获取完成回调，返回当前配置或错误信息

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;
[hrInterface fetchAutoMonitorConfigsWithCompletion:^(TSAutoMonitorHRConfigs * _Nullable configuration, NSError * _Nullable error) {
    if (error) {
        TSLog(@"获取配置失败: %@", error.localizedDescription);
    } else {
        TSLog(@"自动监测已启用: %@", configuration.enabled ? @"YES" : @"NO");
    }
}];

原始心率数据同步方法

同步指定时间范围内的原始心率数据

- (void)syncRawDataFromStartTime:(NSTimeInterval)startTime
                         endTime:(NSTimeInterval)endTime
                      completion:(nonnull void (^)(NSArray<TSHRValueItem *> *_Nullable hrItems, NSError *_Nullable error))completion;

说明： 同步指定时间范围内的原始心率测量数据。

参数	类型	说明
`startTime`	`NSTimeInterval`	数据同步的开始时间戳（秒）
`endTime`	`NSTimeInterval`	数据同步的结束时间戳（秒）
`completion`	`void (^)(NSArray<TSHRValueItem > , NSError *)`	同步完成回调，返回心率条目数组或错误信息

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;

// 计算7天前的时间戳
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-7*24*3600] timeIntervalSince1970];
NSTimeInterval endTime = [[NSDate date] timeIntervalSince1970];

[hrInterface syncRawDataFromStartTime:startTime endTime:endTime 
                           completion:^(NSArray<TSHRValueItem *> * _Nullable hrItems, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步原始心率数据失败: %@", error.localizedDescription);
    } else {
        TSLog(@"同步到 %lu 条心率记录", (unsigned long)hrItems.count);
        for (TSHRValueItem *item in hrItems) {
            TSLog(@"心率: %u BPM, 时间: %f", item.hrValue, item.startTime);
        }
    }
}];

同步从指定时间开始至今的原始心率数据

- (void)syncRawDataFromStartTime:(NSTimeInterval)startTime
                      completion:(nonnull void (^)(NSArray<TSHRValueItem *> *_Nullable hrItems, NSError *_Nullable error))completion;

说明： 同步从指定开始时间到当前时间的原始心率测量数据。

参数	类型	说明
`startTime`	`NSTimeInterval`	数据同步的开始时间戳（秒）
`completion`	`void (^)(NSArray<TSHRValueItem > , NSError *)`	同步完成回调，返回心率条目数组或错误信息

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;

// 同步30天前至今的数据
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-30*24*3600] timeIntervalSince1970];

[hrInterface syncRawDataFromStartTime:startTime 
                           completion:^(NSArray<TSHRValueItem *> * _Nullable hrItems, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步数据失败: %@", error.localizedDescription);
    } else {
        TSLog(@"同步完成，共 %lu 条记录", (unsigned long)hrItems.count);
    }
}];

每日心率数据同步方法

同步指定时间范围内的每日心率数据

- (void)syncDailyDataFromStartTime:(NSTimeInterval)startTime
                           endTime:(NSTimeInterval)endTime
                        completion:(nonnull void (^)(NSArray<TSHRDailyModel *> *_Nullable dailyModels, NSError *_Nullable error))completion;

说明： 同步指定时间范围内的每日聚合心率数据。时间参数会自动规范化为日期边界。

参数	类型	说明
`startTime`	`NSTimeInterval`	数据同步的开始时间戳，将规范化为当天 00:00:00
`endTime`	`NSTimeInterval`	数据同步的结束时间戳，将规范化为当天 23:59:59
`completion`	`void (^)(NSArray<TSHRDailyModel > , NSError *)`	同步完成回调，返回每日心率模型数组或错误信息

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;

// 同步过去7天的每日数据
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-7*24*3600] timeIntervalSince1970];
NSTimeInterval endTime = [[NSDate date] timeIntervalSince1970];

[hrInterface syncDailyDataFromStartTime:startTime endTime:endTime 
                             completion:^(NSArray<TSHRDailyModel *> * _Nullable dailyModels, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步每日心率数据失败: %@", error.localizedDescription);
    } else {
        TSLog(@"同步到 %lu 天的数据", (unsigned long)dailyModels.count);
        for (TSHRDailyModel *dailyModel in dailyModels) {
            TSLog(@"日期: %f, 最大心率: %u BPM, 最小心率: %u BPM", 
                  dailyModel.dayStartTime, 
                  [dailyModel maxBPM], 
                  [dailyModel minBPM]);
        }
    }
}];

同步从指定时间开始至今的每日心率数据

- (void)syncDailyDataFromStartTime:(NSTimeInterval)startTime
                        completion:(nonnull void (^)(NSArray<TSHRDailyModel *> *_Nullable dailyModels, NSError *_Nullable error))completion;

说明： 同步从指定开始时间到当前时间的每日聚合心率数据。开始时间会自动规范化为当天 00:00:00。

参数	类型	说明
`startTime`	`NSTimeInterval`	数据同步的开始时间戳，将规范化为当天 00:00:00
`completion`	`void (^)(NSArray<TSHRDailyModel > , NSError *)`	同步完成回调，返回每日心率模型数组或错误信息

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;

// 同步30天前至今的每日数据
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-30*24*3600] timeIntervalSince1970];

[hrInterface syncDailyDataFromStartTime:startTime 
                             completion:^(NSArray<TSHRDailyModel *> * _Nullable dailyModels, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步数据失败: %@", error.localizedDescription);
    } else {
        TSLog(@"同步完成，共 %lu 天的数据", (unsigned long)dailyModels.count);
    }
}];

静息心率数据同步方法

同步指定时间范围内的原始静息心率数据

- (void)syncRawRestingHeartRateDataFromStartTime:(NSTimeInterval)startTime
                                         endTime:(NSTimeInterval)endTime
                                      completion:(nonnull void (^)(NSArray<TSHRValueItem *> *_Nullable restingHRItems, NSError *_Nullable error))completion;

说明： 同步指定时间范围内的原始静息心率测量数据。

参数	类型	说明
`startTime`	`NSTimeInterval`	数据同步的开始时间戳（秒）
`endTime`	`NSTimeInterval`	数据同步的结束时间戳（秒）
`completion`	`void (^)(NSArray<TSHRValueItem > , NSError *)`	同步完成回调，返回静息心率条目数组或错误信息

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;

// 计算过去30天的时间范围
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-30*24*3600] timeIntervalSince1970];
NSTimeInterval endTime = [[NSDate date] timeIntervalSince1970];

[hrInterface syncRawRestingHeartRateDataFromStartTime:startTime endTime:endTime 
                                           completion:^(NSArray<TSHRValueItem *> * _Nullable restingHRItems, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步静息心率数据失败: %@", error.localizedDescription);
    } else {
        TSLog(@"同步到 %lu 条静息心率记录", (unsigned long)restingHRItems.count);
        for (TSHRValueItem *item in restingHRItems) {
            TSLog(@"静息心率: %u BPM", item.hrValue);
        }
    }
}];

同步从指定时间开始至今的原始静息心率数据

- (void)syncRawRestingHeartRateDataFromStartTime:(NSTimeInterval)startTime
                                      completion:(nonnull void (^)(NSArray<TSHRValueItem *> *_Nullable restingHRItems, NSError *_Nullable error))completion;

说明： 同步从指定开始时间到当前时间的原始静息心率测量数据。

参数	类型	说明
`startTime`	`NSTimeInterval`	数据同步的开始时间戳（秒）
`completion`	`void (^)(NSArray<TSHRValueItem > , NSError *)`	同步完成回调，返回静息心率条目数组或错误信息

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;

// 同步7天前至今的静息心率数据
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-7*24*3600] timeIntervalSince1970];

[hrInterface syncRawRestingHeartRateDataFromStartTime:startTime 
                                           completion:^(NSArray<TSHRValueItem *> * _Nullable restingHRItems, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步数据失败: %@", error.localizedDescription);
    } else {
        TSLog(@"同步完成，共 %lu 条记录", (unsigned long)restingHRItems.count);
    }
}];

同步今天的静息心率数据

- (void)syncTodayRestingHeartRateDataWithCompletion:(nonnull void (^)(TSHRValueItem *_Nullable todayRestingHR, NSError *_Nullable error))completion;

说明： 同步当天的静息心率数据。返回今天记录的单个静息心率条目。

参数	类型	说明
`completion`	`void (^)(TSHRValueItem , NSError )`	同步完成回调，返回今天的静息心率条目或错误信息

代码示例：

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthDevice;

[hrInterface syncTodayRestingHeartRateDataWithCompletion:^(TSHRValueItem * _Nullable todayRestingHR, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步今天的静息心率数据失败: %@", error.localizedDescription);
    } else if (todayRestingHR) {
        TSLog(@"今天的静息心率: %u BPM", todayRestingHR.hrValue);
    } else {
        TSLog(@"今天暂无静息心率数据");
    }
}];

TSHRDailyModel 便捷方法

获取最大心率

- (UInt8)maxBPM;

说明： 获取该天的最大心率值（BPM）。

参数	类型	说明
返回值	`UInt8`	最大心率（BPM），无数据时返回 0

代码示例：

TSHRDailyModel *dailyModel = ...;
UInt8 maxHR = [dailyModel maxBPM];
TSLog(@"今天最大心率: %u BPM", maxHR);

获取最小心率

- (UInt8)minBPM;

说明： 获取该天的最小心率值（BPM）。

参数	类型	说明

前提条件​

数据模型​

TSHRValueItem（心率测量条目）​

TSHRDailyModel（每日心率聚合数据）​

接口方法​

能力查询方法​

查询心率预警监测支持情况​

查询加强心率监测支持情况​

查询手动心率测量支持情况​

查询自动心率监测支持情况​

查询安静心率预警支持情况​

查询运动心率预警支持情况​

查询监测时间段配置支持情况​

查询监测间隔配置支持情况​

查询静息心率监测支持情况​

心率测量方法​

启动心率测量​

停止心率测量​

自动监测配置方法​

配置自动心率监测​

获取自动心率监测配置​

原始心率数据同步方法​

同步指定时间范围内的原始心率数据​

同步从指定时间开始至今的原始心率数据​

每日心率数据同步方法​

同步指定时间范围内的每日心率数据​

同步从指定时间开始至今的每日心率数据​

静息心率数据同步方法​

同步指定时间范围内的原始静息心率数据​

同步从指定时间开始至今的原始静息心率数据​

同步今天的静息心率数据​

TSHRDailyModel 便捷方法​

获取最大心率​

获取最小心率​

前提条件

数据模型

TSHRValueItem（心率测量条目）

TSHRDailyModel（每日心率聚合数据）

接口方法

能力查询方法

查询心率预警监测支持情况

查询加强心率监测支持情况

查询手动心率测量支持情况

查询自动心率监测支持情况

查询安静心率预警支持情况

查询运动心率预警支持情况

查询监测时间段配置支持情况

查询监测间隔配置支持情况

查询静息心率监测支持情况

心率测量方法

启动心率测量

停止心率测量

自动监测配置方法

配置自动心率监测

获取自动心率监测配置

原始心率数据同步方法

同步指定时间范围内的原始心率数据

同步从指定时间开始至今的原始心率数据

每日心率数据同步方法

同步指定时间范围内的每日心率数据

同步从指定时间开始至今的每日心率数据

静息心率数据同步方法

同步指定时间范围内的原始静息心率数据

同步从指定时间开始至今的原始静息心率数据

同步今天的静息心率数据

TSHRDailyModel 便捷方法

获取最大心率

获取最小心率