睡眠 (TSSleep)

TopStepComKit iOS SDK 睡眠模块提供从设备同步睡眠数据的完整接口，包括夜间睡眠和日间小睡（如支持）。数据包含详细的睡眠阶段、质量指标和全面的睡眠分析。

前提条件

设备已配对并连接
设备支持睡眠数据采集功能
用户已授予睡眠数据访问权限

数据模型

TSSleepDailyModel（每日睡眠数据）

属性名	类型	说明
`statisticsRule`	`TSSleepStatisticsRule`	此睡眠记录使用的统计规则
`dailySummary`	`TSSleepSummary *`	当日睡眠总体汇总
`rawSleepItems`	`NSArray<TSSleepDetailItem > `	原始睡眠数据条目数组
`nightSleeps`	`NSArray<TSSleepSegment > `	夜间睡眠段数组
`daytimeSleeps`	`NSArray<TSSleepSegment > `	日间睡眠段数组

TSSleepDetailItem（睡眠详情条目）

属性名	类型	说明
`stage`	`TSSleepStage`	睡眠阶段类型（清醒/浅睡/深睡/REM）
`belongingDate`	`NSTimeInterval`	所属日期时间戳（0时0分0秒）

TSSleepSegment（睡眠段）

属性名	类型	说明
`periodType`	`TSSleepPeriodType`	睡眠时段类型（夜间/日间）
`summary`	`TSSleepSummary *`	睡眠汇总统计
`detailItems`	`NSArray<TSSleepDetailItem > `	按时间顺序的睡眠阶段详情条目数组

TSSleepSummary（睡眠汇总）

属性名	类型	说明
`startTime`	`NSTimeInterval`	睡眠开始时间（Unix时间戳）
`endTime`	`NSTimeInterval`	睡眠结束时间（Unix时间戳）
`duration`	`NSTimeInterval`	总持续时间（秒）
`totalSleepDuration`	`NSTimeInterval`	总睡眠时长（秒）
`qualityScore`	`UInt8`	睡眠质量评分（0-100）
`awakeDuration`	`NSTimeInterval`	睡眠期间总清醒时长（秒）
`lightSleepDuration`	`NSTimeInterval`	总浅睡时长（秒）
`deepSleepDuration`	`NSTimeInterval`	总深睡时长（秒）
`remDuration`	`NSTimeInterval`	总REM时长（秒）
`awakePercentage`	`UInt8`	清醒时间百分比
`lightSleepPercentage`	`UInt8`	浅睡时间百分比
`deepSleepPercentage`	`UInt8`	深睡时间百分比
`remPercentage`	`UInt8`	REM时间百分比
`awakeCount`	`UInt16`	觉醒次数
`lightSleepCount`	`UInt16`	浅睡次数
`deepSleepCount`	`UInt16`	深睡次数
`remCount`	`UInt16`	REM次数

枚举与常量

TSSleepStatisticsRule（睡眠统计规则）

值	说明
`TSSleepStatisticsRuleWithoutNap`	不带小睡功能，传感器20:00-12:00激活，所有睡眠视为夜间睡眠
`TSSleepStatisticsRuleWithNap`	带小睡功能，传感器24小时激活，区分夜间和日间睡眠
`TSSleepStatisticsRuleLongestNight`	使用最长连续夜间睡眠段（20:00-08:00），有效小睡计入统计
`TSSleepStatisticsRuleLongestOnly`	不区分夜间和日间，仅使用最长连续睡眠段

TSSleepStage（睡眠阶段）

值	说明
`TSSleepStageAwake`	清醒阶段
`TSSleepStageLight`	浅睡阶段（N1和N2期）
`TSSleepStageDeep`	深睡阶段（N3期，慢波睡眠）
`TSSleepStageREM`	快速眼动阶段（做梦阶段）

TSSleepPeriodType（睡眠时段类型）

值	说明
`TSSleepPeriodTypeNight`	夜间睡眠（20:00-09:00）
`TSSleepPeriodTypeDaytime`	日间睡眠（09:00-20:00）

接口方法

获取睡眠统计规则

- (TSSleepStatisticsRule)sleepStatisticsRule;

获取当前设备使用的睡眠统计规则（算法）。

参数	类型	说明
返回值	`TSSleepStatisticsRule`	设备使用的睡眠统计规则

代码示例：

id<TSSleepInterface> sleepInterface = [device getInterface:@protocol(TSSleepInterface)];
TSSleepStatisticsRule rule = [sleepInterface sleepStatisticsRule];
TSLog(@"设备睡眠统计规则: %ld", (long)rule);

检查REM睡眠支持

- (BOOL)isSupportREMSleep;

检查设备是否支持REM（快速眼动）睡眠阶段识别。

参数	类型	说明
返回值	`BOOL`	是否支持REM睡眠

代码示例：

id<TSSleepInterface> sleepInterface = [device getInterface:@protocol(TSSleepInterface)];
BOOL supportREM = [sleepInterface isSupportREMSleep];
TSLog(@"设备支持REM睡眠: %@", supportREM ? @"是" : @"否");

检查睡眠分析支持

- (BOOL)isSupportSleepAnalysis;

返回设备是否支持睡眠分析能力；调用分析相关功能前应先检查该值。

同步原始睡眠分段（从指定时间开始）

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

从指定开始时间同步原始睡眠分段数据。

参数	类型	说明
`startTime`	`NSTimeInterval`	起始时间的Unix时间戳（秒）
`completion`	`void (^)(NSArray<TSSleepDetailItem > , NSError *)`	回调返回睡眠条目数组或错误

代码示例：

id<TSSleepInterface> sleepInterface = [device getInterface:@protocol(TSSleepInterface)];
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-7*24*3600] timeIntervalSince1970];

[sleepInterface syncRawDataFromStartTime:startTime completion:^(NSArray<TSSleepDetailItem *> * _Nullable sleepItems, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步失败: %@", error.localizedDescription);
        return;
    }
    TSLog(@"同步成功，获得 %lu 条睡眠数据", (unsigned long)sleepItems.count);
    for (TSSleepDetailItem *item in sleepItems) {
        TSLog(@"阶段: %ld, 时长: %.0f秒", (long)item.stage, item.duration);
    }
}];

同步原始睡眠分段（时间范围）

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

在指定时间区间内同步原始睡眠分段数据。

参数	类型	说明
`startTime`	`NSTimeInterval`	区间开始时间的Unix时间戳（秒，含）
`endTime`	`NSTimeInterval`	区间结束时间的Unix时间戳（秒，不含）
`completion`	`void (^)(NSArray<TSSleepDetailItem > , NSError *)`	回调返回睡眠条目数组或错误

代码示例：

id<TSSleepInterface> sleepInterface = [device getInterface:@protocol(TSSleepInterface)];
NSDate *startDate = [NSDate dateWithTimeIntervalSinceNow:-7*24*3600];
NSDate *endDate = [NSDate date];

[sleepInterface syncRawDataFromStartTime:[startDate timeIntervalSince1970]
                                 endTime:[endDate timeIntervalSince1970]
                              completion:^(NSArray<TSSleepDetailItem *> * _Nullable sleepItems, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步失败: %@", error.localizedDescription);
        return;
    }
    TSLog(@"获得 %lu 条睡眠数据", (unsigned long)sleepItems.count);
}];

同步按天聚合睡眠数据（从指定时间开始）

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

从指定开始时间同步按天聚合的睡眠数据。

参数	类型	说明
`startTime`	`NSTimeInterval`	起始"自然日"的Unix时间戳（秒）
`completion`	`void (^)(NSArray<TSSleepDailyModel > , NSError *)`	回调返回每日睡眠模型数组或错误

代码示例：

id<TSSleepInterface> sleepInterface = [device getInterface:@protocol(TSSleepInterface)];
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-30*24*3600] timeIntervalSince1970];

[sleepInterface syncDailyDataFromStartTime:startTime completion:^(NSArray<TSSleepDailyModel *> * _Nullable sleepModels, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步失败: %@", error.localizedDescription);
        return;
    }
    for (TSSleepDailyModel *model in sleepModels) {
        TSLog(@"日期: %@, 总睡眠: %.0f秒, 质量评分: %d", 
              [NSDate dateWithTimeIntervalSince1970:model.dailySummary.startTime],
              model.dailySummary.totalSleepDuration,
              model.dailySummary.qualityScore);
    }
}];

同步按天聚合睡眠数据（时间范围）

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

在指定时间区间内同步按天聚合的睡眠数据。

参数	类型	说明
`startTime`	`NSTimeInterval`	区间起始"自然日"的Unix时间戳（秒，含）
`endTime`	`NSTimeInterval`	区间结束"自然日"的Unix时间戳（秒，不含）
`completion`	`void (^)(NSArray<TSSleepDailyModel > , NSError *)`	回调返回每日睡眠模型数组或错误

代码示例：

id<TSSleepInterface> sleepInterface = [device getInterface:@protocol(TSSleepInterface)];
NSDate *startDate = [NSDate dateWithTimeIntervalSinceNow:-30*24*3600];
NSDate *endDate = [NSDate date];

[sleepInterface syncDailyDataFromStartTime:[startDate timeIntervalSince1970]
                                   endTime:[endDate timeIntervalSince1970]
                                completion:^(NSArray<TSSleepDailyModel *> * _Nullable sleepModels, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步失败: %@", error.localizedDescription);
        return;
    }
    TSLog(@"获得 %lu 天的睡眠数据", (unsigned long)sleepModels.count);
    for (TSSleepDailyModel *model in sleepModels) {
        NSArray<TSSleepSegment *> *validNaps = [model validNaps];
        TSLog(@"夜间睡眠段: %lu, 有效小睡: %lu", 
              (unsigned long)model.nightSleeps.count,
              (unsigned long)validNaps.count);
    }
}];

注意事项

睡眠数据以20:00为跨天分隔线，即20:00-20:00为一个睡眠日，不同于自然日（00:00-00:00）
不同设备支持的睡眠统计规则不同，使用前应调用sleepStatisticsRule确认设备规则
REM睡眠阶段并非所有设备都支持，使用前应调用isSupportREMSleep检查
原始睡眠数据包含清醒段，用于精细分析；按天聚合数据已处理清醒段，用于日常统计
有效小睡定义为时长在20分钟至3小时之间的日间睡眠段
时间参数均为Unix时间戳（秒），范围为[startTime, endTime)，不包含endTime
同步操作为异步操作，回调在主线程执行

前提条件​

数据模型​

TSSleepDailyModel（每日睡眠数据）​

TSSleepDetailItem（睡眠详情条目）​

TSSleepSegment（睡眠段）​

TSSleepSummary（睡眠汇总）​

枚举与常量​

TSSleepStatisticsRule（睡眠统计规则）​

TSSleepStage（睡眠阶段）​

TSSleepPeriodType（睡眠时段类型）​

接口方法​

获取睡眠统计规则​

检查REM睡眠支持​

检查睡眠分析支持​

同步原始睡眠分段（从指定时间开始）​

同步原始睡眠分段（时间范围）​

同步按天聚合睡眠数据（从指定时间开始）​

同步按天聚合睡眠数据（时间范围）​

注意事项​

前提条件

数据模型

TSSleepDailyModel（每日睡眠数据）

TSSleepDetailItem（睡眠详情条目）

TSSleepSegment（睡眠段）

TSSleepSummary（睡眠汇总）

枚举与常量

TSSleepStatisticsRule（睡眠统计规则）

TSSleepStage（睡眠阶段）

TSSleepPeriodType（睡眠时段类型）

接口方法

获取睡眠统计规则

检查REM睡眠支持

检查睡眠分析支持

同步原始睡眠分段（从指定时间开始）

同步原始睡眠分段（时间范围）

同步按天聚合睡眠数据（从指定时间开始）

同步按天聚合睡眠数据（时间范围）

注意事项