运动（TSSport）

TSSport 模块提供了完整的运动活动数据管理接口，包括运动历史数据同步、详细指标、心率数据和各种运动类型的活动摘要。开发者可以通过该模块获取设备上记录的各类运动活动数据，并进行统计分析。

前提条件

已正确初始化 TopStepComKit SDK 并获取设备连接
设备已支持运动数据记录功能
用户已授予应用健康数据访问权限

数据模型

TSSportModel（运动活动模型）

属性名	类型	说明
`summary`	`TSSportSummaryModel *`	运动活动总结数据，包含整体统计和性能指标
`sportItems`	`NSArray<TSSportItemModel > `	运动详细数据项数组，包含每个时间段的具体指标
`heartRateItems`	`NSArray<TSHRValueItem > `	心率数据数组，包含整个运动过程中的心率测量值

TSSportSummaryModel（运动总结模型）

属性名	类型	说明
`startTime`	`NSTimeInterval`	运动开始时间戳（秒）
`endTime`	`NSTimeInterval`	运动结束时间戳（秒）
`duration`	`double`	运动持续时间（秒）
`userID`	`NSString *`	用户标识符
`macAddress`	`NSString *`	设备MAC地址
`sportID`	`long`	运动活动标识符
`type`	`TSSportTypeEnum`	运动类型
`steps`	`UInt32`	总步数
`distance`	`UInt32`	总距离（米）
`calorie`	`UInt32`	总卡路里消耗
`maxHrValue`	`UInt8`	最大心率（BPM）
`minHrValue`	`UInt8`	最小心率（BPM）
`avgHrValue`	`UInt8`	平均心率（BPM）
`maxPace`	`float`	最大配速（秒/公里）
`minPace`	`float`	最小配速（秒/公里）
`avgPace`	`float`	平均配速（秒/公里）
`maxSpeed`	`float`	最大速度（米/秒）
`minSpeed`	`float`	最小速度（米/秒）
`avgSpeed`	`float`	平均速度（米/秒）
`maxCadence`	`UInt16`	最大步频（步/分钟）
`minCadence`	`UInt16`	最小步频（步/分钟）
`avgCadence`	`UInt16`	平均步频（步/分钟）
`warmHrDuration`	`UInt32`	热身心率区间时长（秒）
`fatBurnHrDuration`	`UInt32`	脂肪燃烧心率区间时长（秒）
`aerobicHrDuration`	`UInt32`	有氧心率区间时长（秒）
`anaerobicHrDuration`	`UInt32`	无氧心率区间时长（秒）
`extremeHrDuration`	`UInt32`	极限心率区间时长（秒）
`warmHrRatio`	`UInt8`	热身心率区间时间占比（0-100%）
`fatBurnHrRatio`	`UInt8`	脂肪燃烧心率区间时间占比（0-100%）
`aerobicHrRatio`	`UInt8`	有氧心率区间时间占比（0-100%）
`anaerobicHrRatio`	`UInt8`	无氧心率区间时间占比（0-100%）
`extremeHrRatio`	`UInt8`	极限心率区间时间占比（0-100%）
`displayConfigs`	`NSData *`	显示配置位图（最大32字节，nil表示不支持）

TSSportItemModel（运动详情项模型）

属性名	类型	说明
`userID`	`NSString *`	用户标识符
`macAddress`	`NSString *`	设备MAC地址
`sportID`	`long`	运动活动标识符
`type`	`UInt16`	运动类型
`distance`	`NSInteger`	距离（米）
`steps`	`NSInteger`	步数
`calories`	`NSInteger`	卡路里消耗
`pace`	`NSInteger`	配速（秒/公里）
`cadence`	`NSInteger`	步频（步/分钟）
`speed`	`NSInteger`	速度（米/分钟）
`swimStyle`	`int`	游泳姿势（1=自由泳、2=蛙泳、3=仰泳、4=蝶泳）
`swimLaps`	`int`	游泳趟数
`swimStrokes`	`int`	游泳划水次数
`swimStrokeFreq`	`int`	游泳划水频率（次/分钟）
`swolf`	`int`	游泳效率指数（SWOLF）
`jumpCount`	`int`	跳绳总次数
`jumpBkCount`	`int`	跳绳中断次数
`jumpConsCount`	`int`	跳绳连续次数
`elCount`	`int`	椭圆机步数
`elFrequecy`	`int`	椭圆机频率（步/分钟）
`elMaxFrequecy`	`int`	椭圆机最大频率（步/分钟）
`elMinFrequecy`	`int`	椭圆机最小频率（步/分钟）
`rowCount`	`int`	划船机划桨次数
`rowFrequecy`	`int`	划船机频率（次/分钟）
`rowMaxFrequecy`	`int`	划船机最大频率（次/分钟）
`rowMinFrequecy`	`int`	划船机最小频率（次/分钟）

TSSportDailyModel（运动日统计模型）

属性名	类型	说明
`sportRecords`	`NSArray<TSSportModel > `	当天的运动活动记录数组
`sportCount`	`NSUInteger`	当天运动次数
`totalDuration`	`NSTimeInterval`	当天总运动时长（秒）
`maxHeartRate`	`UInt8`	当天最大心率（BPM）
`minHeartRate`	`UInt8`	当天最小心率（BPM）

枚举与常量

TSSportTypeEnum（运动类型枚举）

枚举值	说明
`TSSportTypeOutdoorCycling`	户外骑行
`TSSportTypeOutdoorRunning`	户外跑步
`TSSportTypeIndoorRunning`	室内跑步
`TSSportTypeOutdoorWalking`	户外健走
`TSSportTypeClimbing`	登山
`TSSportTypeBasketball`	篮球
`TSSportTypeSwimming`	游泳
`TSSportTypeBadminton`	羽毛球
`TSSportTypeFootball`	足球
`TSSportTypeElliptical`	椭圆机
`TSSportTypeYoga`	瑜伽
`TSSportTypePingPong`	乒乓球
`TSSportTypeRopeSkipping`	跳绳
`TSSportTypeRowing`	划船机
`TSSportTypeLazyBike`	懒人车
`TSSportTypeFitnessBike`	健身车
`TSSportTypeFreeTraining`	自由训练
`TSSportTypeTennis`	网球
`TSSportTypeBaseball`	棒球
`TSSportTypeRugby`	橄榄球
`TSSportTypeCricket`	板球
`TSSportTypeFreeSports`	自由运动
`TSSportTypeStrengthTraining`	力量训练
`TSSportTypeIndoorWalking`	室内走路
`TSSportTypeIndoorCycling`	室内骑行
`TSSportTypeDumbbell`	哑铃
`TSSportTypeDance`	舞蹈
`TSSportTypeHulaHoop`	呼啦圈
`TSSportTypeGolf`	高尔夫
`TSSportTypeLongJump`	跳远
`TSSportTypeSitUp`	仰卧起坐
`TSSportTypeVolleyball`	排球
`TSSportTypeParkour`	跑酷
`TSSportTypeHiking`	徒步
`TSSportTypeHockey`	曲棍球
`TSSportTypeBoating`	划船
`TSSportTypeHIIT`	HIIT
`TSSportTypeSoftball`	垒球
`TSSportTypeTrailRunning`	越野跑
`TSSportTypeSkiing`	滑雪
`TSSportTypeTreadmill`	漫步机
`TSSportTypeRelaxation`	整理放松
`TSSportTypeCrossTraining`	交叉训练
`TSSportTypePilates`	普拉提
`TSSportTypeCrossMatch`	交叉配合
`TSSportTypeFunctionalTraining`	功能性训练
`TSSportTypePhysicalTraining`	体能训练
`TSSportTypeMixedCardio`	混合有氧
`TSSportTypeLatinDance`	拉丁舞
`TSSportTypeStreetDance`	街舞
`TSSportTypeFreeSparring`	自由搏击
`TSSportTypeBallet`	芭蕾
`TSSportTypeAustralianFootball`	澳式足球
`TSSportTypeBowling`	保龄球
`TSSportTypeSquash`	壁球
`TSSportTypeCurling`	冰壶
`TSSportTypeSnowboarding`	单板滑雪
`TSSportTypeFishing`	钓鱼
`TSSportTypeFrisbee`	飞盘
`TSSportTypeAlpineSkiing`	高山滑雪
`TSSportTypeCoreTraining`	核心训练
`TSSportTypeSkating`	滑冰
`TSSportTypeFitnessGaming`	健身游戏
`TSSportTypeAerobics`	健身操
`TSSportTypeGroupCallisthenics`	团体操
`TSSportTypeKickBoxing`	搏击操
`TSSportTypeFencing`	击剑
`TSSportTypeStairClimbing`	爬楼
`TSSportTypeAmericanFootball`	美式橄榄球
`TSSportTypeFoamRolling`	泡沫轴筋膜放松
`TSSportTypePickleball`	匹克球
`TSSportTypeBoxing`	拳击
`TSSportTypeTaekwondo`	跆拳道
`TSSportTypeKarate`	空手道
`TSSportTypeFlexibility`	柔韧度
`TSSportTypeHandball`	手球
`TSSportTypeHandcar`	手摇车
`TSSportTypeMeditation`	舒缓冥想类运动
`TSSportTypeWrestling`	摔跤
`TSSportTypeStepping`	踏步
`TSSportTypeTaiChi`	太极
`TSSportTypeGymnastics`	体操
`TSSportTypeTrackAndField`	田径
`TSSportTypeMartialArts`	武术
`TSSportTypeLeisureSports`	休闲运动
`TSSportTypeSnowSports`	雪上运动
`TSSportTypeLacrosse`	长曲棍球
`TSSportTypeHorizontalBar`	单杠
`TSSportTypeParallelBars`	双杠
`TSSportTypeRollerSkating`	轮滑
`TSSportTypeDarts`	飞镖
`TSSportTypeArchery`	射箭
`TSSportTypeHorseRiding`	骑马
`TSSportTypeShuttlecock`	毽球
`TSSportTypeIceHockey`	冰球
`TSSportTypeAbdominalTraining`	腰腹训练
`TSSportTypeVO2MaxTest`	最大摄氧量测试
`TSSportTypeJudo`	柔道
`TSSportTypeTrampolining`	蹦床
`TSSportTypeSkateboard`	滑板
`TSSportTypeHoverBoard`	平衡车
`TSSportTypeInlineSkating`	溜旱冰
`TSSportTypeTreadmillRunning`	跑步机
`TSSportTypeDiving`	跳水
`TSSportTypeSurfing`	冲浪
`TSSportTypeSnorkeling`	浮潜
`TSSportTypePullUp`	引体向上
`TSSportTypePushUp`	俯卧撑
`TSSportTypePlank`	平板支撑
`TSSportTypeRockClimbing`	攀岩
`TSSportTypeHighJump`	跳高
`TSSportTypeBungeeJumping`	蹦极
`TSSportTypeNationalDance`	民族舞
`TSSportTypeHunting`	打猎
`TSSportTypeShooting`	射击
`TSSportTypeMarathon`	马拉松
`TSSportTypeSpinningBike`	动感单车
`TSSportTypePoolSwimming`	泳池游泳
`TSSportTypeOpenWaterSwimming`	开放水域游泳
`TSSportTypeBallroomDance`	交际舞
`TSSportTypeZumba`	尊巴
`TSSportTypeJazzDance`	爵士舞
`TSSportTypeStepMachine`	踏步机
`TSSportTypeStairMachine`	爬楼机
`TSSportTypeCroquet`	门球
`TSSportTypeWaterPolo`	水球
`TSSportTypeWallBall`	墙球
`TSSportTypeBilliards`	台球
`TSSportTypeSepakTakraw`	藤球
`TSSportTypeStretching`	拉伸
`TSSportTypeFreeGymnastics`	自由体操
`TSSportTypeBarbell`	杠铃
`TSSportTypeWeightlifting`	举重
`TSSportTypeDeadlift`	硬拉
`TSSportTypeBurpee`	波比跳
`TSSportTypeJumpingJack`	开合跳
`TSSportTypeUpperBodyTraining`	上肢训练
`TSSportTypeLowerBodyTraining`	下肢训练
`TSSportTypeBackTraining`	背部训练
`TSSportTypeBeachBuggy`	沙滩车
`TSSportTypeParagliding`	滑翔伞
`TSSportTypeFlyAKite`	放风筝
`TSSportTypeTugOfWar`	拔河
`TSSportTypeTriathlon`	铁人三项
`TSSportTypeSnowmobile`	雪地摩托
`TSSportTypeSnowCar`	雪车
`TSSportTypeSled`	雪橇
`TSSportTypeSkiBoard`	滑雪板
`TSSportTypeCrossCountrySkiing`	越野滑雪
`TSSportTypeIndoorSkating`	室内滑冰
`TSSportTypeKabaddi`	卡巴迪
`TSSportTypeMuayThai`	泰拳
`TSSportTypeKickboxing`	踢拳
`TSSportTypeRacing`	赛车
`TSSportTypeIndoorFitness`	室内健身
`TSSportTypeOutdoorSoccer`	户外足球
`TSSportTypeBellyDance`	肚皮舞
`TSSportTypeSquareDance`	广场舞

TSSportDisplayMetric（运动显示指标枚举）

枚举值	说明
`TSSportDisplayMetricDuration`	持续时间
`TSSportDisplayMetricHeartRate`	心率
`TSSportDisplayMetricSteps`	步数
`TSSportDisplayMetricDistance`	距离
`TSSportDisplayMetricCalories`	卡路里
`TSSportDisplayMetricAvgSpeed`	平均速度
`TSSportDisplayMetricAvgPace`	平均配速
`TSSportDisplayMetricAvgCadence`	平均步频
`TSSportDisplayMetricAvgStride`	平均步幅
`TSSportDisplayMetricTotalAscent`	累计上升
`TSSportDisplayMetricTotalDescent`	累计下降
`TSSportDisplayMetricSwimLaps`	游泳趟数
`TSSportDisplayMetricSwimStrokes`	游泳划水次数
`TSSportDisplayMetricSwimStyle`	泳姿
`TSSportDisplayMetricSwimStrokeRate`	游泳划水频率
`TSSportDisplayMetricSwimEfficiency`	游泳效率(SWOLF)
`TSSportDisplayMetricTriggerCount`	触发次数
`TSSportDisplayMetricTriggerRate`	触发频率
`TSSportDisplayMetricInterruptionCount`	中断次数
`TSSportDisplayMetricContinuousCount`	连续次数

接口方法

同步指定时间范围内的运动历史数据

- (void)syncHistoryDataFormStartTime:(NSTimeInterval)startTime
                             endTime:(NSTimeInterval)endTime
                          completion:(nonnull void (^)(NSArray<TSSportModel *> *_Nullable sports, NSError *_Nullable error))completion;

参数说明

参数名	类型	说明
`startTime`	`NSTimeInterval`	数据同步开始时间（时间戳，单位秒）
`endTime`	`NSTimeInterval`	数据同步结束时间（时间戳，单位秒）
`completion`	`void (^)(NSArray<TSSportModel > , NSError *)`	完成回调，返回同步的运动数据或错误信息

代码示例

id<TSSportInterface> sportInterface = (id<TSSportInterface>)manager;

NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-7*24*3600] timeIntervalSince1970];
NSTimeInterval endTime = [[NSDate date] timeIntervalSince1970];

[sportInterface syncHistoryDataFormStartTime:startTime
                                     endTime:endTime
                                  completion:^(NSArray<TSSportModel *> * _Nullable sports, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步失败: %@", error.localizedDescription);
        return;
    }
    
    TSLog(@"同步成功，获得 %lu 条运动记录", (unsigned long)sports.count);
    
    for (TSSportModel *sport in sports) {
        TSLog(@"运动类型: %ld, 距离: %u m, 卡路里: %u cal, 平均心率: %d bpm",
              (long)sport.summary.type,
              sport.summary.distance,
              sport.summary.calorie,
              sport.summary.avgHrValue);
    }
}];

从指定时间开始同步至今的运动历史数据

- (void)syncHistoryDataFormStartTime:(NSTimeInterval)startTime
                          completion:(nonnull void (^)(NSArray<TSSportModel *> *_Nullable sports, NSError *_Nullable error))completion;

参数说明

参数名	类型	说明
`startTime`	`NSTimeInterval`	数据同步开始时间（时间戳，单位秒）
`completion`	`void (^)(NSArray<TSSportModel > , NSError *)`	完成回调，返回同步的运动数据或错误信息

代码示例

id<TSSportInterface> sportInterface = (id<TSSportInterface>)manager;

// 从30天前开始同步至今
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-30*24*3600] timeIntervalSince1970];

[sportInterface syncHistoryDataFormStartTime:startTime
                                  completion:^(NSArray<TSSportModel *> * _Nullable sports, NSError * _Nullable error) {
    if (error) {
        TSLog(@"同步失败: %@", error.localizedDescription);
        return;
    }
    
    TSLog(@"同步成功，获得 %lu 条运动记录", (unsigned long)sports.count);
    
    // 统计总运动时长
    NSTimeInterval totalDuration = 0;
    NSUInteger totalSteps = 0;
    UInt32 totalCalories = 0;
    
    for (TSSportModel *sport in sports) {
        totalDuration += sport.summary.duration;
        totalSteps += sport.summary.steps;
        totalCalories += sport.summary.calorie;
    }
    
    TSLog(@"统计数据 - 总时长: %.0f分钟, 总步数: %lu, 总卡路里: %u",
          totalDuration / 60,
          (unsigned long)totalSteps,
          totalCalories);
}];

显示指标辅助方法

获取已启用的显示指标数组

- (NSArray<NSNumber *> *)displayMetrics;

返回值

NSArray<NSNumber *> * —— 包含 TSSportDisplayMetric 枚举值的数组，每个数字表示一个启用的指标

代码示例

TSSportSummaryModel *summary = sport.summary;
NSArray<NSNumber *> *metrics = [summary displayMetrics];

TSLog(@"启用的显示指标数量: %lu", (unsigned long)metrics.count);

for (NSNumber *metricNum in metrics) {
    TSSportDisplayMetric metric = (TSSportDisplayMetric)[metricNum unsignedIntegerValue];
    NSString *name = [TSSportSummaryModel nameForDisplayMetric:metric];
    TSLog(@"指标: %@", name);
}

检查特定显示指标是否已启用

- (BOOL)hasDisplayMetric:(TSSportDisplayMetric)metric;

参数说明

参数名	类型	说明
`metric`	`TSSportDisplayMetric`	要检查的显示指标

返回值

BOOL —— 指标已启用返回 YES，否则返回 NO

代码示例

TSSportSummaryModel *summary = sport.summary;

if ([summary hasDisplayMetric:TSSportDisplayMetricHeartRate]) {
    TSLog(@"该运动支持显示心率数据");
}

if ([summary hasDisplayMetric:TSSportDisplayMetricSwimLaps]) {
    TSLog(@"该运动支持显示游泳趟数");
}

获取已启用显示指标的本地化名称数组

- (NSArray<NSString *> *)displayMetricNames;

返回值

NSArray<NSString *> * —— 本地化指标名称数组

代码示例

TSSportSummaryModel *summary = sport.summary;
NSArray<NSString *> *metricNames = [summary displayMetricNames];

TSLog(@"该运动将显示以下指标:");
for (NSString *name in metricNames) {
    TSLog(@"  - %@", name);
}

获取显示指标的本地化名称（类方法）

+ (NSString *)nameForDisplayMetric:(TSSportDisplayMetric)metric;

参数说明

参数名	类型	说明
`metric`	`TSSportDisplayMetric`	显示指标枚举值

返回值

NSString * —— 本地化名称字符串，未定义的值返回"未知指标"

代码示例

NSString *name1 = [TSSportSummaryModel nameForDisplayMetric:TSSportDisplayMetricDuration];
NSString *name2 = [TSSportSummaryModel nameForDisplayMetric:TSSportDisplayMetricHeartRate];
NSString *name3 = [TSSportSummaryModel nameForDisplayMetric:TSSportDisplayMetricDistance];

TSLog(@"指标名称: %@, %@, %@", name1, name2, name3);

注意事项

时间戳格式：syncHistoryDataFormStartTime:endTime:completion: 方法中的时间参数必须为 Unix 时间戳（秒），可通过 [NSDate timeIntervalSince1970] 获取
数据完整性：同步大时间范围的数据时，建议分段同步以避免超时，单次最多建议同步30天内的数据
心率区间计算：心率区间的计算基于公式 (220 - 年龄)，各区间如下：
- 热身：HR < 最大心率 × 60%
- 脂肪燃烧：最大心率 × 60% ≤ HR < 最大心率 × 70%
- 有氧：最大心率 ×

前提条件​

数据模型​

TSSportModel（运动活动模型）​

TSSportSummaryModel（运动总结模型）​

TSSportItemModel（运动详情项模型）​

TSSportDailyModel（运动日统计模型）​

枚举与常量​

TSSportTypeEnum（运动类型枚举）​

TSSportDisplayMetric（运动显示指标枚举）​

接口方法​

同步指定时间范围内的运动历史数据​

从指定时间开始同步至今的运动历史数据​

显示指标辅助方法​

获取已启用的显示指标数组​

检查特定显示指标是否已启用​

获取已启用显示指标的本地化名称数组​

获取显示指标的本地化名称（类方法）​

注意事项​

前提条件

数据模型

TSSportModel（运动活动模型）

TSSportSummaryModel（运动总结模型）

TSSportItemModel（运动详情项模型）

TSSportDailyModel（运动日统计模型）

枚举与常量

TSSportTypeEnum（运动类型枚举）

TSSportDisplayMetric（运动显示指标枚举）

接口方法

同步指定时间范围内的运动历史数据

从指定时间开始同步至今的运动历史数据

显示指标辅助方法

获取已启用的显示指标数组

检查特定显示指标是否已启用

获取已启用显示指标的本地化名称数组

获取显示指标的本地化名称（类方法）

注意事项