跳到主要内容

体温（Temperature）

体温模块提供体温测量、自动监测和历史数据同步功能。一次采样可能同时包含体温和腕温，SDK 使用一个 TSTempValueItem 表示同一采样事件，避免拆成两条时间相同的记录。

前提条件​

  1. 设备已连接到 SDK
  2. 确认设备支持体温测量功能（通过相应的支持检查方法）
  3. 对于自动监测功能，需要确认设备支持该特性
  4. 获取 TSTemperatureInterface 实例以调用相关接口

数据模型​

TSTempValueItem​

属性名类型说明
bodyTemperatureCGFloat体温（摄氏度）；正数表示有效值，0 表示本次采样没有体温数据
wristTemperatureCGFloat腕温（摄氏度）；正数表示有效值，0 表示本次采样没有腕温数据
isUserInitiatedBOOL标识该测量是否为用户主动发起

bodyTemperature 与 wristTemperature 属于同一次采样，可以同时有效，也可以只有一个有效。只有两者都为 0 时，该条目才表示没有有效温度数据。

此版本将温度模型调整为成对字段，属于破坏性变更。升级后必须直接读取 bodyTemperature 和 wristTemperature。

TSTempDailyModel​

属性名类型说明
maxBodyTempItemTSTempValueItem *当天体温最高的采样条目，独立基于有效 bodyTemperature 计算
minBodyTempItemTSTempValueItem *当天体温最低的采样条目，独立基于有效 bodyTemperature 计算
maxWristTempItemTSTempValueItem *当天腕温最高的采样条目，独立基于有效 wristTemperature 计算
minWristTempItemTSTempValueItem *当天腕温最低的采样条目，独立基于有效 wristTemperature 计算
manualItemsNSArray<TSTempValueItem *> *用户主动采样事件，按时间升序排列；成对温度只出现一次
autoItemsNSArray<TSTempValueItem *> *设备自动采样事件，按时间升序排列；成对温度只出现一次

回调类型​

回调类型说明
void (^)(BOOL isSuccess, NSError *error)TSCompletionBlock，用于停止测量及配置操作完成回调，包含成功标志和错误信息
void (^)(BOOL success, NSError *error)用于测量开始与结束的回调，包含成功标志和错误信息
void (^)(TSTempValueItem *data, NSError *error)用于接收实时测量数据的回调，返回温度数据或错误信息
void (^)(NSArray<TSTempValueItem *> *tempItems, NSError *error)用于原始温度数据同步完成的回调
void (^)(NSArray<TSTempDailyModel *> *dailyModels, NSError *error)用于每日温度数据同步完成的回调
void (^)(TSAutoMonitorConfigs *configuration, NSError *error)用于获取自动监测配置的回调

接口方法​

检查设备是否支持手动温度测量​

- (BOOL)isSupportActivityMeasureByUser;
参数类型说明
返回值BOOLYES 表示设备支持手动温度测量，NO 表示不支持

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

BOOL isSupported = [tempInterface isSupportActivityMeasureByUser];
if (isSupported) {
    TSLog(@"设备支持手动温度测量");
} else {
    TSLog(@"设备不支持手动温度测量");
}

开始温度测量​

- (void)startMeasureWithParam:(TSActivityMeasureParam *_Nonnull)measureParam
                 startHandler:(void(^_Nullable)(BOOL success, NSError * _Nullable error))startHandler
                  dataHandler:(void(^_Nullable)(TSTempValueItem * _Nullable data, NSError * _Nullable error))dataHandler
                   endHandler:(void(^_Nullable)(BOOL success, NSError * _Nullable error))endHandler;
参数类型说明
measureParamTSActivityMeasureParam *测量活动的参数配置
startHandlervoid (^)(BOOL success, NSError *error)测量开始或失败时的回调。success 表示测量是否成功开始，error 为失败时的错误信息
dataHandlervoid (^)(TSTempValueItem *data, NSError *error)接收实时测量数据的回调。data 为实时温度数据，error 为错误信息
endHandlervoid (^)(BOOL success, NSError *error)测量结束时的回调。success 表示测量是否正常结束，error 为异常结束时的错误信息

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

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

[tempInterface startMeasureWithParam:param
                       startHandler:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"温度测量已启动");
    } else {
        TSLog(@"启动温度测量失败: %@", error.localizedDescription);
    }
}
                        dataHandler:^(TSTempValueItem * _Nullable data, NSError * _Nullable error) {
    if (data) {
        TSLog(@"实时体温: %.1f°C, 腕温: %.1f°C",
              data.bodyTemperature,
              data.wristTemperature);
    } else {
        TSLog(@"接收数据失败: %@", error.localizedDescription);
    }
}
                         endHandler:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"温度测量已正常结束");
    } else {
        TSLog(@"温度测量异常结束: %@", error.localizedDescription);
    }
}];

停止温度测量​

- (void)stopMeasureCompletion:(nonnull TSCompletionBlock)completion;
参数类型说明
completionTSCompletionBlock测量停止完成时的回调，参数为 isSuccess 和 error

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

[tempInterface stopMeasureCompletion:^(BOOL isSuccess, NSError * _Nullable error) {
    if (isSuccess) {
        TSLog(@"温度测量已停止");
    } else {
        TSLog(@"停止温度测量失败: %@", error.localizedDescription);
    }
}];

检查设备是否支持自动温度监测​

- (BOOL)isSupportAutomaticMonitoring;
参数类型说明
返回值BOOLYES 表示设备支持自动温度监测，NO 表示不支持

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

BOOL isSupported = [tempInterface isSupportAutomaticMonitoring];
if (isSupported) {
    TSLog(@"设备支持自动温度监测");
} else {
    TSLog(@"设备不支持自动温度监测");
}

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

- (BOOL)isSupportMonitorScheduleTime;
参数类型说明
返回值BOOLYES 表示设备支持配置监测开始/结束时间，NO 表示不支持

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

BOOL isSupported = [tempInterface isSupportMonitorScheduleTime];
if (isSupported) {
    TSLog(@"设备支持配置体温监测时间段");
}

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

- (BOOL)isSupportMonitorScheduleInterval;
参数类型说明
返回值BOOLYES 表示设备支持配置监测间隔，NO 表示不支持

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

BOOL isSupported = [tempInterface isSupportMonitorScheduleInterval];
if (isSupported) {
    TSLog(@"设备支持配置体温监测时间间隔");
}

配置自动温度监测​

- (void)pushAutoMonitorConfig:(TSAutoMonitorConfigs *_Nonnull)configuration
                   completion:(nonnull TSCompletionBlock)completion;
参数类型说明
configurationTSAutoMonitorConfigs *自动监测的配置参数
completionTSCompletionBlock配置设置完成时的回调，参数为 isSuccess 和 error

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

TSAutoMonitorConfigs *config = [[TSAutoMonitorConfigs alloc] init];
config.schedule.enabled = YES;

[tempInterface pushAutoMonitorConfig:config completion:^(BOOL isSuccess, NSError * _Nullable error) {
    if (isSuccess) {
        TSLog(@"自动温度监测配置已设置");
    } else {
        TSLog(@"设置自动监测配置失败: %@", error.localizedDescription);
    }
}];

获取自动温度监测配置​

- (void)fetchAutoMonitorConfigsWithCompletion:(nonnull void (^)(TSAutoMonitorConfigs *_Nullable configuration, NSError *_Nullable error))completion;
参数类型说明
completionvoid (^)(TSAutoMonitorConfigs *configuration, NSError *error)获取配置完成时的回调，返回当前配置或错误信息

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

[tempInterface fetchAutoMonitorConfigsWithCompletion:^(TSAutoMonitorConfigs * _Nullable configuration, NSError * _Nullable error) {
    if (configuration && !error) {
        TSLog(@"自动监测已启用: %@", configuration.schedule.enabled ? @"是" : @"否");
    } else {
        TSLog(@"获取自动监测配置失败: %@", error.localizedDescription);
    }
}];

同步指定时间范围内的原始温度数据​

- (void)syncRawDataFromStartTime:(NSTimeInterval)startTime
                         endTime:(NSTimeInterval)endTime
                      completion:(nonnull void (^)(NSArray<TSTempValueItem *> *_Nullable tempItems, NSError *_Nullable error))completion;
参数类型说明
startTimeNSTimeInterval数据同步的开始时间（1970年以来的秒数时间戳）
endTimeNSTimeInterval数据同步的结束时间（1970年以来的秒数时间戳）
completionvoid (^)(NSArray<TSTempValueItem *> *tempItems, NSError *error)同步完成时的回调，返回原始温度数据或错误信息

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-86400] timeIntervalSince1970]; // 24小时前
NSTimeInterval endTime = [[NSDate date] timeIntervalSince1970]; // 当前时间

[tempInterface syncRawDataFromStartTime:startTime
                               endTime:endTime
                            completion:^(NSArray<TSTempValueItem *> * _Nullable tempItems, NSError * _Nullable error) {
    if (tempItems && !error) {
        TSLog(@"同步了 %lu 条原始温度数据", (unsigned long)tempItems.count);
        for (TSTempValueItem *item in tempItems) {
            TSLog(@"体温: %.1f°C, 腕温: %.1f°C",
                  item.bodyTemperature,
                  item.wristTemperature);
        }
    } else {
        TSLog(@"同步原始数据失败: %@", error.localizedDescription);
    }
}];

同步从指定时间至今的原始温度数据​

- (void)syncRawDataFromStartTime:(NSTimeInterval)startTime
                      completion:(nonnull void (^)(NSArray<TSTempValueItem *> *_Nullable tempItems, NSError *_Nullable error))completion;
参数类型说明
startTimeNSTimeInterval数据同步的开始时间（1970年以来的秒数时间戳）
completionvoid (^)(NSArray<TSTempValueItem *> *tempItems, NSError *error)同步完成时的回调，返回原始温度数据或错误信息

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-604800] timeIntervalSince1970]; // 7天前

[tempInterface syncRawDataFromStartTime:startTime
                            completion:^(NSArray<TSTempValueItem *> * _Nullable tempItems, NSError * _Nullable error) {
    if (tempItems && !error) {
        TSLog(@"同步了 %lu 条原始温度数据", (unsigned long)tempItems.count);
    } else {
        TSLog(@"同步原始数据失败: %@", error.localizedDescription);
    }
}];

同步指定时间范围内的每日温度数据​

- (void)syncDailyDataFromStartTime:(NSTimeInterval)startTime
                           endTime:(NSTimeInterval)endTime
                        completion:(nonnull void (^)(NSArray<TSTempDailyModel *> *_Nullable dailyModels, NSError *_Nullable error))completion;
参数类型说明
startTimeNSTimeInterval数据同步的开始时间（1970年以来的秒数时间戳），将自动规范化为指定日期的 00:00:00
endTimeNSTimeInterval数据同步的结束时间（1970年以来的秒数时间戳），将自动规范化为指定日期的 23:59:59
completionvoid (^)(NSArray<TSTempDailyModel *> *dailyModels, NSError *error)同步完成时的回调，返回每日温度数据或错误信息

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

NSDate *startDate = [NSDate dateWithTimeIntervalSinceNow:-604800]; // 7天前
NSDate *endDate = [NSDate date]; // 当前时间

[tempInterface syncDailyDataFromStartTime:[startDate timeIntervalSince1970]
                                 endTime:[endDate timeIntervalSince1970]
                              completion:^(NSArray<TSTempDailyModel *> * _Nullable dailyModels, NSError * _Nullable error) {
    if (dailyModels && !error) {
        TSLog(@"同步了 %lu 天的每日温度数据", (unsigned long)dailyModels.count);
        for (TSTempDailyModel *dailyModel in dailyModels) {
            TSLog(@"日期: %@, 最高体温: %.1f°C, 最低体温: %.1f°C",
                  [NSDate dateWithTimeIntervalSince1970:dailyModel.startTime],
                  [dailyModel maxBodyTemperature],
                  [dailyModel minBodyTemperature]);
        }
    } else {
        TSLog(@"同步每日数据失败: %@", error.localizedDescription);
    }
}];

同步从指定时间至今的每日温度数据​

- (void)syncDailyDataFromStartTime:(NSTimeInterval)startTime
                        completion:(nonnull void (^)(NSArray<TSTempDailyModel *> *_Nullable dailyModels, NSError *_Nullable error))completion;
参数类型说明
startTimeNSTimeInterval数据同步的开始时间（1970年以来的秒数时间戳），将自动规范化为指定日期的 00:00:00
completionvoid (^)(NSArray<TSTempDailyModel *> *dailyModels, NSError *error)同步完成时的回调，返回每日温度数据或错误信息

代码示例：

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)deviceInstance;

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

[tempInterface syncDailyDataFromStartTime:[startDate timeIntervalSince1970]
                            completion:^(NSArray<TSTempDailyModel *> * _Nullable dailyModels, NSError * _Nullable error) {
    if (dailyModels && !error) {
        TSLog(@"同步了 %lu 天的每日温度数据", (unsigned long)dailyModels.count);
        for (TSTempDailyModel *dailyModel in dailyModels) {
            CGFloat maxTemp = [dailyModel maxBodyTemperature];
            CGFloat minTemp = [dailyModel minBodyTemperature];
            NSArray<TSTempValueItem *> *allItems = [dailyModel allMeasuredItems];
            TSLog(@"日期: %@, 最高体温: %.1f°C, 最低体温: %.1f°C, 总测量数: %lu",
                  [NSDate dateWithTimeIntervalSince1970:dailyModel.startTime],
                  maxTemp, minTemp, (unsigned long)allItems.count);
        }
    } else {
        TSLog(@"同步每日数据失败: %@", error.localizedDescription);
    }
}];

注意事项​

  1. 使用手动温度测量前，必须先通过 isSupportActivityMeasureByUser 检查设备是否支持该功能
  2. 调用 startMeasureWithParam:startHandler:dataHandler:endHandler: 时，所有回调块都是可选的，但建议至少实现 startHandler 和 endHandler 来监控测量状态
  3. 在调用 stopMeasureCompletion: 前，确保已成功启动了测量（通过 startHandler 回调确认）
  4. 自动监测配置通过 pushAutoMonitorConfig:completion: 设置后，需确保设备支持该功能（通过 isSupportAutomaticMonitoring 确认）
  5. 对于时间范围的同步方法，时间参数应为 Unix 时间戳（秒数），可通过 NSDate 的 timeIntervalSince1970 属性获取
  6. 每日数据同步时，时间参数会自动规范化到日期边界，不需要手动调整时间
  7. 每日数据同步的完成回调在主线程中调用，可以安全地更新 UI
  8. TSTempDailyModel 提供了便捷方法 maxBodyTemperature、minBodyTemperature 等来获取聚合数据
  9. TSTempDailyModel 的 allMeasuredItems 方法返回该天所有的测量条目（手动 + 自动），按时间升序排列
  10. 温度单位统一为摄氏度（°C），不需要进行单位转换
  11. 一个 TSTempValueItem 表示一次采样事件；体温和腕温可同时存在，任一字段为 0 只表示该分量缺失
  12. 温度模型只提供 bodyTemperature 和 wristTemperature；升级 SDK 时需同步迁移所有模型读取点