跳到主要内容

overview

---
sidebar_position: 1
title: 健康数据概述
---

# 健康数据概述（TSHealthBase）

TopStepComKit iOS SDK 健康数据模块（TSHealthBase）提供主动测量和自动监测两大功能，涵盖心率、血压、血氧、压力、体温、心电等多种健康指标的实时采集和历史数据管理。

## 前提条件

1. 已成功初始化 TopStepComKit SDK 并建立与设备的蓝牙连接
2. 设备支持相应的健康测量类型
3. 用户已授予应用所需的健康数据访问权限
4. 对于自动监测功能，需确认设备固件版本支持相应配置能力

## 数据模型

### TSActivityMeasureParam（主动测量参数）

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `measureType` | `TSActiveMeasureType` | 要执行的测量类型（一次仅支持一种） |
| `interval` | `UInt8` | 采样间隔（秒），有效范围因测量类型而异 |
| `maxMeasureDuration` | `UInt8` | 最大测量时长（秒），0表示持续测量直到手动停止，最小值15秒，默认60秒 |

### TSHealthValueItem（健康数据项）

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `startTime` | `NSTimeInterval` | 数据记录开始时间戳（Unix秒数） |
| `endTime` | `NSTimeInterval` | 数据记录结束时间戳（Unix秒数） |
| `duration` | `double` | 数据记录持续时间（秒） |
| `valueType` | `TSItemValueType` | 心率数据类型（普通、最大值、最小值、静息） |

### TSHealthDailyModel（日级健康数据）

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `startTime` | `NSTimeInterval` | 数据记录开始时间戳（Unix秒数） |
| `endTime` | `NSTimeInterval` | 数据记录结束时间戳（Unix秒数） |
| `duration` | `double` | 数据记录持续时间（秒） |

### TSAutoMonitorConfigs（通用自动监测配置）

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `schedule` | `TSMonitorSchedule *` | 监测计划（开关、时间、间隔） |
| `alert` | `TSMonitorAlert *` | 告警阈值配置（可为nil） |

### TSAutoMonitorHRConfigs（心率自动监测配置）

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `schedule` | `TSMonitorSchedule *` | 监测计划（开关、时间、间隔） |
| `restHRAlert` | `TSMonitorAlert *` | 静息心率告警配置（可为nil） |
| `exerciseHRAlert` | `TSMonitorAlert *` | 运动心率告警配置（可为nil） |
| `exerciseHRLimitMax` | `UInt8` | 最大运动心率（用于心率分区计算，建议100-220 bpm） |

### TSAutoMonitorBPConfigs（血压自动监测配置）

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `schedule` | `TSMonitorSchedule *` | 监测计划（开关、时间、间隔） |
| `alert` | `TSMonitorBPAlert *` | 血压告警配置（可为nil） |

### TSMonitorSchedule（监测计划）

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `enabled` | `BOOL` | 是否启用监测 |
| `startTime` | `UInt16` | 开始时间（距零点分钟数，0-1440） |
| `endTime` | `UInt16` | 结束时间（距零点分钟数，0-1440） |
| `interval` | `UInt16` | 监测间隔（分钟，必须为5的倍数） |

### TSMonitorAlert（告警配置）

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `enabled` | `BOOL` | 是否启用告警 |
| `upperLimit` | `UInt16` | 上限阈值（单位随监测类型） |
| `lowerLimit` | `UInt16` | 下限阈值（单位随监测类型） |

### TSMonitorBPAlert（血压告警配置）

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `enabled` | `BOOL` | 是否启用血压告警 |
| `systolicUpperLimit` | `UInt16` | 收缩压上限（mmHg） |
| `systolicLowerLimit` | `UInt16` | 收缩压下限（mmHg） |
| `diastolicUpperLimit` | `UInt16` | 舒张压上限（mmHg） |
| `diastolicLowerLimit` | `UInt16` | 舒张压下限（mmHg） |

## 枚举与常量

### TSActiveMeasureType（主动测量类型）

| 枚举值 | 数值 | 说明 |
|--------|------|------|
| `TSMeasureTypeNone` | 0 | 无测量项目 |
| `TSMeasureTypeHeartRate` | 1 | 心率 |
| `TSMeasureTypeBloodOxygen` | 2 | 血氧（SpO2） |
| `TSMeasureTypeBloodPressure` | 3 | 血压 |
| `TSMeasureTypeStress` | 4 | 压力 |
| `TSMeasureTypeTemperature` | 5 | 体温 |
| `TSMeasureTypeECG` | 6 | 心电图 |

### TSItemValueType（心率数据类型）

| 枚举值 | 数值 | 说明 |
|--------|------|------|
| `TSItemValueTypeNormal` | 0 | 普通数据（原始时序点，自动或手动采集） |
| `TSItemValueTypeMax` | 1 | 当日最大值（由当日普通数据计算） |
| `TSItemValueTypeMin` | 2 | 当日最小值（由当日普通数据计算） |
| `TSItemValueTypeResting` | 3 | 静息心率（算法基于静息/睡眠区段计算） |

### TSHealthValueType（健康数值类型）

| 枚举值 | 数值 | 说明 |
|--------|------|------|
| `TSHealthValueTypeNormal` | 0 | 普通数据 |
| `TSHealthValueTypeMax` | 1 | 最大值 |
| `TSHealthValueTypeMin` | 2 | 最小值 |
| `TSHealthValueTypeResting` | 3 | 静息数据（仅心率使用） |

## 回调类型

| 回调类型 | 签名 | 说明 |
|---------|------|------|
| `TSMeasureDataBlock` | `void (^)(TSHealthValueItem *value)` | 接收单次测量数据的回调 |
| 测量数据变化回调 | `void (^)(TSHealthValueItem * _Nullable realtimeData, NSError * _Nullable error)` | 实时测量数据通知，包含原始数据或错误信息 |
| 测量结束回调 | `void (^)(BOOL isFinished, NSError * _Nullable error)` | 测量完成通知，指示成功结束或异常 |
| 完成回调 | `void (^)(NSError * _Nullable error)` | 通用异步操作完成回调 |

## 接口方法

### 主动测量接口（TSActiveMeasureInterface）

#### 开始健康测量

```objc
+ (void)startMeasureWithParam:(`TSActivityMeasureParam *`)measureParam 
                   completion:(TSCompletionBlock)completion;

参数

参数名类型说明
measureParamTSActivityMeasureParam *测量参数（包括类型、间隔、时长）
completionTSCompletionBlock完成回调，指示操作成功或失败

代码示例

// 创建心率测量参数
TSActivityMeasureParam *param = [[TSActivityMeasureParam alloc] init];
param.measureType = TSMeasureTypeHeartRate;        // 心率测量
param.interval = 1;                                 // 采样间隔1秒
param.maxMeasureDuration = 60;                      // 最长测量60秒

// 开始测量
[TSActiveMeasureInterface startMeasureWithParam:param completion:^(`NSError *` _Nullable error) {
    if (error) {
        TSLog(@"启动测量失败: %@", error.localizedDescription);
    } else {
        TSLog(@"测量已启动");
    }
}];

停止健康测量​

+ (void)stopMeasureWithParam:(`TSActivityMeasureParam *`)measureParam 
                 completion:(TSCompletionBlock)completion;

参数

参数名类型说明
measureParamTSActivityMeasureParam *测量参数（指定要停止的测量类型）
completionTSCompletionBlock完成回调

代码示例

TSActivityMeasureParam *param = [[TSActivityMeasureParam alloc] init];
param.measureType = TSMeasureTypeHeartRate;

[TSActiveMeasureInterface stopMeasureWithParam:param completion:^(`NSError *` _Nullable error) {
    if (error) {
        TSLog(@"停止测量失败: %@", error.localizedDescription);
    } else {
        TSLog(@"测量已停止");
    }
}];

注册测量数据变化通知​

+ (void)registerMeasurement:(`TSActivityMeasureParam *`)param
             dataDidChanged:(void(^)(`TSHealthValueItem *` _Nullable realtimeData, `NSError *` _Nullable error))dataDidChanged;

参数

参数名类型说明
paramTSActivityMeasureParam *测量参数
dataDidChangedvoid (^)(...)数据变化回调，携带实时数据或错误信息

代码示例

TSActivityMeasureParam *param = [[TSActivityMeasureParam alloc] init];
param.measureType = TSMeasureTypeHeartRate;

[TSActiveMeasureInterface registerMeasurement:param dataDidChanged:^(`TSHealthValueItem *` _Nullable realtimeData, `NSError *` _Nullable error) {
    if (error) {
        TSLog(@"数据接收失败: %@", error.localizedDescription);
    } else if (realtimeData) {
        TSLog(@"当前心率: %d bpm", (int)realtimeData.value);
    }
}];

注册测量结束通知​

+ (void)registerActivityeasureDidFinished:(void(^)(BOOL isFinished, `NSError *` _Nullable error))didFinished;

参数

参数名类型说明
didFinishedvoid (^)(BOOL, NSError *)测量结束回调，包含成功标志和错误信息

代码示例

[TSActiveMeasureInterface registerActivityeasureDidFinished:^(BOOL isFinished, `NSError *` _Nullable error) {
    if (error) {
        TSLog(@"测量异常结束: %@", error.localizedDescription);
    } else if (isFinished) {
        TSLog(@"测量正常完成");
    }
}];

自动监测接口（TSAutoMonitorInterface）​

检查设备能力：单独健康配置支持​

- (BOOL)isSupportIndividualHealthMonitorConfig;

返回值

类型说明
BOOLYES 表示设备支持各测量类型独立配置；NO 表示仅支持全局配置

代码示例

id<TSAutoMonitorInterface> monitorInterface = /* 获取接口实例 */;
if ([monitorInterface isSupportIndividualHealthMonitorConfig]) {
    TSLog(@"设备支持单独配置各健康监测");
} else {
    TSLog(@"设备仅支持全局监测配置");
}

检查设备能力：自定义间隔设置​

- (BOOL)isSupportTimeIntervalSetting;

返回值

类型说明
BOOLYES 表示设备支持自定义间隔；NO 表示设备使用固定间隔

代码示例

if ([monitorInterface isSupportTimeIntervalSetting]) {
    TSLog(@"可设置监测间隔");
} else {
    TSLog(@"使用设备默认间隔");
}

检查设备能力：时间段设置​

- (BOOL)isSupportTimePeriodSetting;

返回值

类型说明
BOOLYES 表示支持设置开始/结束时间；NO 表示全天监测

代码示例

if ([monitorInterface isSupportTimePeriodSetting]) {
    TSLog(@"支持设置监测时间段");
} else {
    TSLog(@"设备全天监测");
}

获取心率自动监测配置​

- (void)fetchHeartRateAutoMonitorConfigsWithCompletion:(void (^)(TSAutoMonitorHRConfigs *_Nullable configs, NSError *_Nullable error))completion;

参数

参数名类型说明
completionvoid (^)(...)完成回调，返回配置对象和错误信息

代码示例

[monitorInterface fetchHeartRateAutoMonitorConfigsWithCompletion:^(`TSAutoMonitorHRConfigs *` _Nullable configs, `NSError *` _Nullable error) {
    if (error) {
        TSLog(@"获取心率配置失败: %@", error.localizedDescription);
    } else {
        TSLog(@"静息心率告警上限: %d bpm", configs.restHRAlert.upperLimit);
        TSLog(@"最大运动心率: %d bpm", configs.exerciseHRLimitMax);
    }
}];

推送心率自动监测配置​

- (void)pushHeartRateAutoMonitorConfig:(`TSAutoMonitorHRConfigs *`)config
                            completion:(TSCompletionBlock)completion;

参数

参数名类型说明
configTSAutoMonitorHRConfigs *心率监测配置
completionTSCompletionBlock完成回调

代码示例

// 创建心率监测配置
TSAutoMonitorHRConfigs *config = [[TSAutoMonitorHRConfigs alloc] init];

// 设置监测计划（每天8am-8pm，每15分钟测量一次）
config.schedule = [[TSMonitorSchedule alloc] init];
config.schedule.enabled = YES;
config.schedule.startTime = 480;   // 8:00 AM
config.schedule.endTime = 1200;    // 8:00 PM
config.schedule.interval = 15;     // 15分钟

// 设置静息心率告警
config.restHRAlert = [[TSMonitorAlert alloc] init];
config.restHRAlert.enabled = YES;
config.restHRAlert.lowerLimit = 50;
config.restHRAlert.upperLimit = 100;

// 设置运动心率告警
config.exerciseHRAlert = [[TSMonitorAlert alloc] init];
config.exerciseHRAlert.enabled = YES;
config.exerciseHRAlert.lowerLimit = 80;
config.exerciseHRAlert.upperLimit = 180;

// 设置最大运动心率（用于计算心率分区）
config.exerciseHRLimitMax = 190;

[monitorInterface pushHeartRateAutoMonitorConfig:config completion:^(`NSError *` _Nullable error) {
    if (error) {
        TSLog(@"推送配置失败: %@", error.localizedDescription);
    } else {
        TSLog(@"心率监测配置已推送");
    }
}];

获取血压自动监测配置​

- (void)fetchBloodPressureAutoMonitorConfigsWithCompletion:(void (^)(TSAutoMonitorBPConfigs *_Nullable configs, NSError *_Nullable error))completion;

参数

参数名类型说明
completionvoid (^)(...)完成回调

代码示例

[monitorInterface fetchBloodPressureAutoMonitorConfigsWithCompletion:^(`TSAutoMonitorBPConfigs *` _Nullable configs, `NSError *` _Nullable error) {
    if (error) {
        TSLog(@"获取血压配置失败: %@", error.localizedDescription);
    } else {
        TSLog(@"收缩压上限: %d mmHg", configs.alert.systolicUpperLimit);
        TSLog(@"舒张压下限: %d mmHg", configs.alert.diastolicLowerLimit);
    }
}];

推送血压自动监测配置​

- (void)pushBloodPressureAutoMonitorConfig:(`TSAutoMonitorBPConfigs *`)config
                                completion:(TSCompletionBlock)completion;

参数

参数名类型说明
configTSAutoMonitorBPConfigs *血压监测配置
completionTSCompletionBlock完成回调

代码示例

TSAutoMonitorBPConfigs *config = [[TSAutoMonitorBPConfigs alloc] init];

// 设置监测计划
config.schedule = [[TSMonitorSchedule alloc] init];
config.schedule.enabled = YES;
config.schedule.startTime = 360;   // 6:00 AM
config.schedule.endTime = 1320;    // 10:00 PM
config.schedule.interval = 30;     // 30分钟

// 设置血压告警阈值
config.alert = [[TSMonitorBPAlert alloc] init];
config.alert.enabled = YES;
config.alert.systolicUpperLimit = 140;    // 收缩压上限
config.alert.systolicLowerLimit = 90;     // 收缩压下限
config.alert.diastolicUpperLimit = 90;    // 舒张压上限
config.alert.diastolicLowerLimit = 60;    // 舒张压下限

[monitorInterface pushBloodPressureAutoMonitorConfig:config completion:^(`NSError *` _Nullable error) {
    if (error) {
        TSLog(@"推送血压配置失败: %@", error.localizedDescription);
    } else {
        TSLog(@"血压监测配置已推送");
    }
}];

获取血氧自动监测配置​

- (void)fetchBloodOxygenAutoMonitorConfigsWithCompletion:(void (^)(TSAutoMonitorConfigs *_Nullable configs, NSError *_Nullable error))completion;

参数

参数名类型说明
completionvoid (^)(...)完成回调

代码示例

[monitorInterface fetchBloodOxygenAutoMonitorConfigsWithCompletion:^(`TSAutoMonitorConfigs *` _Nullable configs, `NSError *` _Nullable error) {
    if (error) {
        TSLog(@"获取血氧配置失败: %@", error.localizedDescription);
    } else {
        TSLog(@"血氧下限: %d%%", configs.alert.lowerLimit);
    }
}];

推送血氧自动监测配置​

- (void)pushBloodOxygenAutoMonitorConfig:(`TSAutoMonitorConfigs *`)config
                            completion:(TSCompletionBlock)completion;

参数

参数名类型说明
configTSAutoMonitorConfigs *血氧监测配置
completionTSCompletionBlock完成回调

代码示例

TSAutoMonitorConfigs *config = [[TSAutoMonitorConfigs alloc] init];

config.schedule = [[TSMonitorSchedule alloc] init];
config.schedule.enabled = YES;
config.schedule.startTime = 0;
config.schedule.endTime = 1440;    // 全天
config.schedule.interval = 30;

config.alert = [[TSMonitorAlert alloc] init];
config.alert.enabled = YES;
config.alert.lowerLimit = 94;      // SpO2下限 94%
config.alert.upperLimit = 100;     // SpO2上限 100%

[monitorInterface pushBloodOxygenAutoMonitorConfig:config completion:^(`NSError *` _Nullable error) {
    if (error) {
        TSLog(@"推送血氧配置失败: %@", error.localizedDescription);
    } else {
        TSLog(@"血氧监测配置已推送");
    }
}];

获取压力自动监测配置​

- (void)fetchStressAutoMonitorConfigsWithCompletion:(void (^)(TSAutoMonitorConfigs *_Nullable configs, NSError *_Nullable error))completion;

参数

参数名类型说明
completionvoid (^)(...)完成回调

推送压力自动监测配置​

- (void)pushStressAutoMonitorConfig:(`TSAutoMonitorConfigs *`)config
                            completion:(TSCompletionBlock)completion;

参数

参数名类型说明
configTSAutoMonitorConfigs *压力监测配置
completionTSCompletionBlock完成回调

代码示例

TSAutoMonitorConfigs *stressConfig = [[TSAutoMonitorConfigs alloc] init];

stressConfig.schedule = [[TSMonitorSchedule alloc] init];
stressConfig.schedule.enabled = YES;
stressConfig.schedule.interval = 60;

stressConfig.alert = [[TSMonitorAlert alloc] init];
stressConfig.alert.enabled = YES;
stressConfig.alert.lowerLimit = 0;
stressConfig.alert.upperLimit = 50;   // 压力等级上限

[monitorInterface pushStressAutoMonitorConfig:stressConfig completion:^(`NSError *` _Nullable error) {
    if (error) {
        TSLog(@"推送压力配置失败: %@", error.localizedDescription);
    } else {
        TSLog(@"压力监测配置已推送");
    }
}];

获取体温自动监测配置​

- (void)fetchTemperatureAutoMonitorConfigsWithCompletion:(void (^)(TSAutoMonitorConfigs *_Nullable configs, NSError *_Nullable error))completion;

参数

参数名类型说明
completionvoid (^)(...)完成回调

推送体温自动监测配置​

- (void)pushTemperatureAutoMonitorConfig:(`TSAutoMonitorConfigs *`)config
                            completion:(TSCompletionBlock)completion;

参数

参数名类型说明
configTSAutoMonitorConfigs *体温监测配置
completionTSCompletionBlock完成回调

代码示例

TSAutoMonitorConfigs *tempConfig = [[TSAutoMonitorConfigs alloc] init];

tempConfig.schedule = [[TSMonitorSchedule alloc] init];
tempConfig.schedule.enabled = YES;
tempConfig.schedule.interval = 120;   // 2小时

tempConfig.alert = [[TSMonitorAlert alloc] init];
tempConfig.alert.enabled = YES;
tempConfig.alert.lowerLimit = 36;     // 36°C
tempConfig.alert.upperLimit = 38;     // 38°C（发热警告）

[monitorInterface pushTemperatureAutoMonitorConfig:tempConfig completion:^(`NSError *` _Nullable error) {
    if (error) {
        TSLog(@"推送体温配置失败: %@", error.localizedDescription);
    } else {
        TSLog(@"体温监测配置已推送");
    }
}];

注意事项​

  1. 主动测量的互斥性：一次只能执行一种测量类型，启动新测量前应先停止现有测量。

  2. 设备能力检查：使用自动监测功能前，必须先通过 isSupportIndividualHealthMonitorConfig、isSupportTimeIntervalSetting 和 isSupportTimePeriodSetting 检查设备支持情况。

  3. 完整的测量流程：

    • 先注册数据变化和结束通知
    • 再调用启动测量接口
    • 接收数据和完成通知
    • 最后调用停止测量接口

  4. 时间格式转换：TSMonitorSchedule 中的 startTime 和 endTime 为距离零点的分钟数，例如 480 表示 8:00 AM。

  5. 间隔设置的约束：TSMonitorSchedule.interval 必须是 5 的倍数，有效值为 5、10、15、20、25、30 等。

  6. 血压告警的独立配置：血压告警需使用 TSMonitorBPAlert 而非通用的 TSMonitorAlert，因为血压需分别配置收缩压和舒张压。

  7. 心率分区计算：TSAutoMonitorHRConfigs.exerciseHRLimitMax 用于心率区间划分，推荐值为 220 减去用户年龄。

  8. 数据类型的语义差异：心率的 TSItemValueType 区分普通采样、每日极值和静息心率，其他测量类型不支持静息类型。

  9. 异步操作处理：所有获取配置和推送配置操作均为异步，完成回调会在主线程调用。

  10. 多监听器支持：可以注册多个测量数据和完成通知监听器，它们会并行接收回调。