血氧（TSBloodOxygen）

血氧模块提供设备血氧测量、自动监测和历史数据同步的功能。血氧饱和度（SpO2）是一个重要的生命体征，表示氧气从肺部输送到身体其他部位的效率。

前提条件

设备需支持血氧测量功能
需通过相应的支持检查方法验证设备功能可用性
使用自动监测功能需设备支持相应功能

数据模型

TSBOValueItem

单次血氧测量数据条目。

属性名	类型	说明
`oxyValue`	`UInt8`	血氧值（百分比，范围 0-100）
`isUserInitiated`	`BOOL`	是否为用户主动测量（YES 为主动测量，NO 为自动监测）
继承自 `TSHealthValueItem`	—	继承时间戳等基础属性

TSBODailyModel

按日聚合的血氧数据模型。

属性名	类型	说明
`maxOxygenItem`	`TSBOValueItem *`	当天最大血氧条目（包含数值、时间戳等）
`minOxygenItem`	`TSBOValueItem *`	当天最小血氧条目（包含数值、时间戳等）
`manualItems`	`NSArray<TSBOValueItem *>`	用户主动测量的血氧数组，按时间升序排列
`autoItems`	`NSArray<TSBOValueItem *>`	自动监测的血氧数组，按时间升序排列
继承自 `TSHealthDailyModel`	—	继承日期等基础属性

枚举与常量

无特殊枚举或常量定义。

回调类型

回调类型	签名	说明
测量开始/停止完成	`void (^)(BOOL success, NSError * _Nullable error)`	success：操作是否成功；error：失败时的错误信息
实时数据接收	`void (^)(TSBOValueItem * _Nullable data, NSError * _Nullable error)`	data：实时血氧测量数据；error：接收失败时的错误信息
原始数据同步	`void (^)(NSArray<TSBOValueItem > _Nullable boItems, NSError * _Nullable error)`	boItems：同步的原始血氧条目数组；error：同步失败时的错误
每日数据同步	`void (^)(NSArray<TSBODailyModel > _Nullable dailyModels, NSError * _Nullable error)`	dailyModels：同步的每日血氧模型数组；error：同步失败时的错误
配置获取	`void (^)(TSAutoMonitorConfigs * _Nullable configuration, NSError * _Nullable error)`	configuration：当前自动监测配置；error：获取失败时的错误

接口方法

检查设备是否支持手动血氧测量

- (BOOL)isSupportActivityMeasureByUser;

返回值

返回值	说明
`BOOL`	设备是否支持手动血氧测量，YES 表示支持，NO 表示不支持

代码示例

id<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;
if ([boInterface isSupportActivityMeasureByUser]) {
    TSLog(@"设备支持手动血氧测量");
} else {
    TSLog(@"设备不支持手动血氧测量");
}

开始血氧测量

- (void)startMeasureWithParam:(TSActivityMeasureParam *_Nonnull)measureParam
                 startHandler:(void(^_Nullable)(BOOL success, NSError * _Nullable error))startHandler
                  dataHandler:(void(^_Nullable)(TSBOValueItem * _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 (^)(TSBOValueItem , NSError )`	实时数据接收回调；data：实时测量数据；error：接收失败时的错误
`endHandler`	`void (^)(BOOL, NSError *)`	测量结束时的回调；success：是否正常结束；error：异常结束的错误

代码示例

id<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;

TSActivityMeasureParam *param = [[TSActivityMeasureParam alloc] init];
param.duration = 120; // 测量时长 120 秒

[boInterface startMeasureWithParam:param
                      startHandler:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"血氧测量已开始");
    } else {
        TSLog(@"血氧测量启动失败: %@", error.localizedDescription);
    }
}
                       dataHandler:^(TSBOValueItem * _Nullable data, NSError * _Nullable error) {
    if (data) {
        TSLog(@"实时血氧值: %hhu%%", data.oxyValue);
    } 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<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;

[boInterface stopMeasureCompletion:^(NSError * _Nullable error) {
    if (!error) {
        TSLog(@"血氧测量已停止");
    } else {
        TSLog(@"停止测量失败: %@", error.localizedDescription);
    }
}];

检查设备是否支持自动血氧监测

- (BOOL)isSupportAutomaticMonitoring;

返回值

返回值	说明
`BOOL`	设备是否支持自动血氧监测，YES 表示支持，NO 表示不支持

代码示例

id<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;
if ([boInterface isSupportAutomaticMonitoring]) {
    TSLog(@"设备支持自动血氧监测");
} else {
    TSLog(@"设备不支持自动血氧监测");
}

检查设备是否支持配置监测时间段

- (BOOL)isSupportMonitorScheduleTime;

返回值

返回值	说明
`BOOL`	设备是否支持配置监测时间段（开始/结束时间），YES 表示支持

代码示例

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

检查设备是否支持配置监测时间间隔

- (BOOL)isSupportMonitorScheduleInterval;

返回值

返回值	说明
`BOOL`	设备是否支持配置监测时间间隔，YES 表示支持

代码示例

id<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;
if ([boInterface isSupportMonitorScheduleInterval]) {
    TSLog(@"设备支持配置监测时间间隔");
}

配置自动血氧监测

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

参数

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

代码示例

id<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;

TSAutoMonitorConfigs *config = [[TSAutoMonitorConfigs alloc] init];
config.enabled = YES;
config.monitorSchedule = [[TSMonitorSchedule alloc] init];
config.monitorSchedule.startTime = @"09:00";
config.monitorSchedule.endTime = @"22:00";
config.monitorSchedule.interval = 30; // 每 30 分钟监测一次

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

获取当前自动监测配置

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

参数

参数名	类型	说明
`completion`	`void (^)(TSAutoMonitorConfigs , NSError )`	获取配置完成回调；configuration：当前配置；error：获取失败时的错误

代码示例

id<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;

[boInterface fetchAutoMonitorConfigsWithCompletion:^(TSAutoMonitorConfigs * _Nullable configuration, NSError * _Nullable error) {
    if (configuration) {
        TSLog(@"自动监测已启用: %d", configuration.enabled);
        if (configuration.monitorSchedule) {
            TSLog(@"监测时间段: %@ - %@", 
                  configuration.monitorSchedule.startTime,
                  configuration.monitorSchedule.endTime);
        }
    } else if (error) {
        TSLog(@"获取配置失败: %@", error.localizedDescription);
    }
}];

同步指定时间范围内的原始血氧数据

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

参数

参数名	类型	说明
`startTime`	`NSTimeInterval`	同步开始时间（1970年以来的秒数时间戳）
`endTime`	`NSTimeInterval`	同步结束时间（1970年以来的秒数时间戳）
`completion`	`void (^)(NSArray<TSBOValueItem > , NSError *)`	同步完成回调；boItems：原始血氧条目数组；error：同步失败时的错误

代码示例

id<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;

NSDate *startDate = [NSDate dateWithTimeIntervalSinceNow:-86400]; // 24 小时前
NSDate *endDate = [NSDate date]; // 现在

[boInterface syncRawDataFromStartTime:[startDate timeIntervalSince1970]
                              endTime:[endDate timeIntervalSince1970]
                           completion:^(NSArray<TSBOValueItem *> * _Nullable boItems, NSError * _Nullable error) {
    if (boItems) {
        TSLog(@"同步了 %lu 条原始血氧数据", (unsigned long)boItems.count);
        for (TSBOValueItem *item in boItems) {
            TSLog(@"血氧值: %hhu%%, 用户主动: %d", item.oxyValue, item.isUserInitiated);
        }
    } else if (error) {
        TSLog(@"同步失败: %@", error.localizedDescription);
    }
}];

同步指定开始时间至今的原始血氧数据

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

参数

参数名	类型	说明
`startTime`	`NSTimeInterval`	同步开始时间（1970年以来的秒数时间戳）；数据将同步到当前时间
`completion`	`void (^)(NSArray<TSBOValueItem > , NSError *)`	同步完成回调；boItems：原始血氧条目数组；error：同步失败时的错误

代码示例

id<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;

NSDate *startDate = [NSDate dateWithTimeIntervalSinceNow:-604800]; // 7 天前

[boInterface syncRawDataFromStartTime:[startDate timeIntervalSince1970]
                           completion:^(NSArray<TSBOValueItem *> * _Nullable boItems, NSError * _Nullable error) {
    if (boItems) {
        TSLog(@"同步了 %lu 条血氧数据（从7天前至今）", (unsigned long)boItems.count);
    } else if (error) {
        TSLog(@"同步失败: %@", error.localizedDescription);
    }
}];

同步指定时间范围内的每日聚合血氧数据

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

参数

参数名	类型	说明
`startTime`	`NSTimeInterval`	同步开始时间（1970年以来的秒数时间戳），自动规范化为日期的 00:00:00
`endTime`	`NSTimeInterval`	同步结束时间（1970年以来的秒数时间戳），自动规范化为日期的 23:59:59；必须晚于开始时间且不在未来
`completion`	`void (^)(NSArray<TSBODailyModel > , NSError *)`	同步完成回调；dailyModels：每日血氧模型数组（按时间升序）；error：同步失败时的错误

代码示例

id<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;

NSDate *startDate = [NSDate dateWithTimeIntervalSinceNow:-604800]; // 7 天前
NSDate *endDate = [NSDate date]; // 现在

[boInterface syncDailyDataFromStartTime:[startDate timeIntervalSince1970]
                               endTime:[endDate timeIntervalSince1970]
                            completion:^(NSArray<TSBODailyModel *> * _Nullable dailyModels, NSError * _Nullable error) {
    if (dailyModels) {
        TSLog(@"同步了 %lu 天的每日血氧数据", (unsigned long)dailyModels.count);
        for (TSBODailyModel *dailyModel in dailyModels) {
            TSLog(@"日期: %@, 最大值: %hhu%%, 最小值: %hhu%%", 
                  dailyModel.date, 
                  [dailyModel maxOxygenValue], 
                  [dailyModel minOxygenValue]);
        }
    } else if (error) {
        TSLog(@"同步失败: %@", error.localizedDescription);
    }
}];

同步指定开始时间至今的每日聚合血氧数据

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

参数

参数名	类型	说明
`startTime`	`NSTimeInterval`	同步开始时间（1970年以来的秒数时间戳），自动规范化为日期的 00:00:00；数据将同步到当前时间
`completion`	`void (^)(NSArray<TSBODailyModel > , NSError *)`	同步完成回调；dailyModels：每日血氧模型数组（按时间升序）；error：同步失败时的错误

代码示例

id<TSBloodOxygenInterface> boInterface = (id<TSBloodOxygenInterface>)device;

NSDate *startDate = [NSDate dateWithTimeIntervalSinceNow:-2592000]; // 30 天前

[boInterface syncDailyDataFromStartTime:[startDate timeIntervalSince1970]
                            completion:^(NSArray<TSBODailyModel *> * _Nullable dailyModels, NSError * _Nullable error) {
    if (dailyModels) {
        TSLog(@"同步了 %lu 天的每日血氧数据（从30天前至今）", (unsigned long)dailyModels.count);
        
        for (TSBODailyModel *dailyModel in dailyModels) {
            UInt8 maxValue = [dailyModel maxOxygenValue];
            UInt8 minValue = [dailyModel minOxygenValue];
            NSUInteger totalMeasurements = [dailyModel allMeasuredItems].count;
            
            TSLog(@"日期: %@", dailyModel.date);
            TSLog(@"  最大血氧: %hhu%%, 最小血氧: %hhu%%", maxValue, minValue);
            TSLog(@"  总测量次数: %lu", (unsigned long)totalMeasurements);
            TSLog(@"  主动测量: %lu次, 自动监测: %lu次", 
                  (unsigned long)dailyModel.manualItems.count,
                  (unsigned long)dailyModel.autoItems.count);
        }
    } else if (error) {
        TSLog(@"同步失败: %@", error.localizedDescription);
    }
}];

注意事项

功能支持检查：使用测量或监测功能前，应先调用相应的 isSupportXxx 方法检查设备是否支持该功能
时间戳格式：所有涉及时间的参数均为 1970 年 1 月 1 日以来的秒数时间戳，可通过 NSDate 的 timeIntervalSince1970 属性获取
日期规范化：同步每日数据时，时间参数会自动规范化为日期边界（开始时间为 00:00:00，结束时间为 23:59:59）
回调执行：完成回调和同步回调均在主线程中执行，可直接进行 UI 更新
数据排序：所有返回的数据数组均按时间升序排列，便于时间轴展示
监测配置有效性：当 isSupportMonitorScheduleTime 返回 YES 时，TSMonitorSchedule 中的 startTime 和 endTime 字段生效；当 isSupportMonitorScheduleInterval 返回 YES 时，interval 字段生效
自动测量与主动测量：通过 TSBOValueItem 的 isUserInitiated 属性可区分用户主动测量（YES）和设备自动监测（NO）的数据
错误处理：所有异步操作都可能返回错误，应始终检查错误对象并相应处理
并发操作：避免同时进行多个测量操作，应等待当前测量结束后再启动新的测量
内存管理：回调块会持有对 self 的引用，在长期监测场景中应注意避免循环引用，使用弱引用模式

前提条件​

数据模型​

TSBOValueItem​

TSBODailyModel​

枚举与常量​

回调类型​

接口方法​

检查设备是否支持手动血氧测量​

开始血氧测量​

停止血氧测量​

检查设备是否支持自动血氧监测​

检查设备是否支持配置监测时间段​

检查设备是否支持配置监测时间间隔​

配置自动血氧监测​

获取当前自动监测配置​

同步指定时间范围内的原始血氧数据​

同步指定开始时间至今的原始血氧数据​

同步指定时间范围内的每日聚合血氧数据​

同步指定开始时间至今的每日聚合血氧数据​

注意事项​

前提条件

数据模型

TSBOValueItem

TSBODailyModel

枚举与常量

回调类型

接口方法

检查设备是否支持手动血氧测量

开始血氧测量

停止血氧测量

检查设备是否支持自动血氧监测

检查设备是否支持配置监测时间段

检查设备是否支持配置监测时间间隔

配置自动血氧监测

获取当前自动监测配置

同步指定时间范围内的原始血氧数据

同步指定开始时间至今的原始血氧数据

同步指定时间范围内的每日聚合血氧数据

同步指定开始时间至今的每日聚合血氧数据

注意事项