跳到主要内容

天气（TSWeather）

TopStepComKit iOS SDK 天气模块提供了完整的天气信息管理功能，支持获取、推送和控制天气数据的显示。

前提条件​

  1. 已成功初始化 TopStepComKit SDK
  2. 设备已连接并配对
  3. 具有访问天气接口的权限

数据模型​

TSWeatherCity（城市信息）​

属性名类型说明
cityNameNSString *城市名称（必需）。城市的名称，如"北京"、"上海"
cityCodeNSString *城市代码（可选）。城市的唯一标识符，通常遵循国家/国际标准，如中国北京的代码为"101010100"
latitudedouble纬度（可选）。城市中心的纬度，使用十进制度数，范围：-90.0到90.0（南纬为负，北纬为正）
longitudedouble经度（可选）。城市中心的经度，使用十进制度数，范围：-180.0到180.0（西经为负，东经为正）
provinceNameNSString *省份/州名（可选）。城市所在的省份或州的名称，例如"广东省"、"加利福尼亚州"
countryNameNSString *国家名称（可选）。城市所在的国家名称，例如"中国"、"美国"

TSWeatherCodeModel（天气代码）​

属性名类型说明
codeTSWeatherCode天气代码枚举值，表示不同的天气状况
nameNSString *天气状况名称。天气状况的文字描述，例如"晴天"、"阳光明媚"、"多云"等

TSWeatherDay（每日天气）​

属性名类型说明
timestampNSTimeInterval天气信息的时间戳。Unix时间戳（秒），表示该天气信息的记录时间
dayCodeTSWeatherCodeModel *白天天气代码信息。包含天气代码和对应的描述信息
nightCodeTSWeatherCodeModel *夜间天气代码信息。夜间的天气代码和对应的描述信息
curTemperatureSInt8当前温度。当前温度，单位：摄氏度
minTemperatureSInt8最低温度。当天的最低温度，单位：摄氏度
maxTemperatureSInt8最高温度。当天的最高温度，单位：摄氏度
airpressureNSInteger气压。大气压力，单位：百帕
windScaleUInt8风力等级。风力等级（0-18），0级无风至18级17级以上
windAngleNSInteger风向角度。风向角度（0-359），0/360：北，90：东，180：南，270：西
windSpeedUInt8风速。风速，单位：米/秒
humidityUInt8湿度。相对湿度百分比（0-100）
uvIndexUInt8紫外线指数。紫外线强度指数（0：无、1-2：很弱、3-4：弱、5-6：中等、7-8：强、9-10：很强、11：极强）
visibilityCGFloat能见度。能见度，单位：米

TSWeatherHour（每小时天气）​

属性名类型说明
timestampNSTimeInterval天气信息的时间戳。Unix时间戳（秒），表示该天气信息的记录时间
weatherCodeTSWeatherCodeModel *天气代码信息。白天的天气代码和对应的描述信息
temperatureSInt8温度。当前温度，单位：摄氏度
windScaleNSInteger风力等级。风力等级（0-18），0级无风至18级17级以上
uvIndexNSInteger紫外线指数。紫外线强度指数（0：无、1-2：很弱、3-4：弱、5-6：中等、7-8：强、9-10：很强、11：极强）
visibilityNSInteger能见度。能见度，单位：米
humidityNSInteger湿度。相对湿度百分比（0-100）

TopStepWeather（天气信息）​

属性名类型说明
timestampNSTimeInterval天气信息的时间戳。Unix时间戳（秒），表示该天气信息的记录时间
updateTimestampNSTimeInterval天气信息时间戳。天气信息最后更新时的Unix时间戳（秒）
sunriseTimeNSTimeInterval日出时间。Unix时间戳（秒），表示当天的日出时间，不可用时为0
sunsetTimeNSTimeInterval日落时间。Unix时间戳（秒），表示当天的日落时间，不可用时为0
cityTSWeatherCity *城市信息。包含正在报告天气的城市信息
dayCodeTSWeatherCodeModel *天气代码信息。包含天气代码和对应的描述信息
nightCodeTSWeatherCodeModel *夜间天气代码信息。夜间的天气代码和对应的描述信息，可选
minTemperatureSInt8最低温度。当天的最低温度，单位：摄氏度
maxTemperatureSInt8最高温度。当天的最高温度，单位：摄氏度
curTemperatureSInt8当前温度。当前温度，单位：摄氏度
airpressureNSInteger气压。大气压力，单位：百帕（hPa）
qualityNSInteger空气质量。空气质量指数（AQI）数值（0：优、1：良、2：轻度污染、3：中度污染、4：重度污染、5：严重污染）
humidityNSInteger湿度。相对湿度百分比（0-100）
uvIndexNSInteger紫外线指数。紫外线强度指数（0：无、1-2：很弱、3-4：弱、5-6：中等、7-8：强、9-10：很强、11：极强）
windAngleCGFloat风向角度。风向角度（0-359），0/360：北，90：东，180：南，270：西
windScaleNSInteger风力等级。风力等级（0-18），0级无风至18级17级以上
windSpeedCGFloat风速。风速，单位：米/秒
visibilityCGFloat能见度。能见度，单位：米
futhureSevenDaysNSArray<TSWeatherDay *> *未来七天天气预报。未来七天的天气预报（包含当天），TSWeatherDay对象数组，按日期排序
futhure24HoursNSArray<TSWeatherHour *> *未来24小时天气预报。未来24小时的天气预报（包含当前小时），TSWeatherHour对象数组，按时间排序

枚举与常量​

TSWeatherCode（天气代码枚举）​

枚举值说明
TSWeatherCodeUnknown未知天气
TSWeatherCodeTornado龙卷风
TSWeatherCodeTropicalStorm热带风暴
TSWeatherCodeHurricane飓风
TSWeatherCodeStrongStorms强风暴
TSWeatherCodeThunderstorms雷雨
TSWeatherCodeRainSnow雨雪
TSWeatherCodeRainSleet雨冰雹
TSWeatherCodeWintryMix雨夹雪
TSWeatherCodeFreezingDrizzle冻毛毛雨
TSWeatherCodeDrizzle毛毛雨
TSWeatherCodeFreezingRain冻雨
TSWeatherCodeShowers阵雨
TSWeatherCodeRain雨天
TSWeatherCodeFlurries小雪
TSWeatherCodeSnowShowers阵雪
TSWeatherCodeBlowingSnow风吹雪
TSWeatherCodeSnow雪
TSWeatherCodeHail冰雹
TSWeatherCodeSleet雨雪（霰）
TSWeatherCodeDustSandstorm扬尘、沙暴
TSWeatherCodeFoggy有雾
TSWeatherCodeHaze霾
TSWeatherCodeSmoke烟雾
TSWeatherCodeBreezy微风
TSWeatherCodeWindy大风
TSWeatherCodeFrigidIceCrystals冰珠
TSWeatherCodeOvercast多云
TSWeatherCodeMostlyCloudyNight夜间大部分多云
TSWeatherCodeMostlyCloudyDay白天大部分多云
TSWeatherCodePartlyCloudyNight夜间局部多云
TSWeatherCodePartlyCloudyDay白天局部多云
TSWeatherCodeClearNight夜间晴天
TSWeatherCodeSunnyDay白天晴天
TSWeatherCodeFairNight夜间晴时多云
TSWeatherCodeFairDay白天晴时多云
TSWeatherCodeMixedRainHail雨加冰雹
TSWeatherCodeHot热
TSWeatherCodeIsolatedThunderstorms局部雷暴
TSWeatherCodeScatteredStormDay白天局部雷阵雨
TSWeatherCodeScatteredShowersDay白天零星阵雨
TSWeatherCodeHeavyRain暴雨
TSWeatherCodeScatteredSnowDay白天零星阵雪
TSWeatherCodeHeavySnow大雪
TSWeatherCodeBlizzard暴风雪
TSWeatherCodeNotAvailable无法使用
TSWeatherCodeScatteredShowersNight夜间零星阵雨
TSWeatherCodeScatteredSnowNight夜间零星阵雪
TSWeatherCodeScatteredStormNight夜间局部雷阵雨

回调类型​

回调类型说明
void (^)(TopStepWeather *_Nullable weather, NSError *_Nullable error)获取天气信息的完成回调。weather：包含所有天气数据的天气信息模型；error：获取失败时的错误信息，成功时为nil
void (^)(BOOL success, NSError *_Nullable error)设置天气信息的完成回调。success：是否操作成功；error：操作失败时的错误信息，成功时为nil
void (^)(BOOL enabled, NSError *_Nullable error)获取天气开关状态的完成回调。enabled：天气功能是否启用；error：获取失败时的错误信息，成功时为nil

接口方法​

获取天气信息​

获取设备中的当前天气信息，包括当前天气状况、每日预报、每小时预报和位置信息。

- (void)fetchWeatherWithCompletion:(void (^)(TopStepWeather *_Nullable weather, NSError *_Nullable error))completion;
参数名类型说明
completionvoid (^)(TopStepWeather *_Nullable weather, NSError *_Nullable error)获取完成的回调。weather：包含所有天气数据的天气信息模型；error：获取失败时的错误信息，成功时为nil

代码示例：

id<TSWeatherInterface> weather = [TopStepComKit sharedInstance].weather;

[weather fetchWeatherWithCompletion:^(TopStepWeather * _Nullable weather, NSError * _Nullable error) {
    if (error) {
        TSLog(@"获取天气信息失败: %@", error.localizedDescription);
    } else {
        TSLog(@"城市: %@", weather.city.cityName);
        TSLog(@"当前温度: %d°C", weather.curTemperature);
        TSLog(@"最高温度: %d°C", weather.maxTemperature);
        TSLog(@"最低温度: %d°C", weather.minTemperature);
        TSLog(@"白天天气: %@", weather.dayCode.name);
        TSLog(@"夜间天气: %@", weather.nightCode.name);
        TSLog(@"风速: %.0f m/s", weather.windSpeed);
        TSLog(@"湿度: %ld%%", (long)weather.humidity);
    }
}];

推送天气信息​

将天气信息同步到设备，包括当前天气状况、每日预报和每小时预报。

- (void)pushWeather:(TopStepWeather *)weather completion:(TSCompletionBlock)completion;
参数名类型说明
weatherTopStepWeather *包含所有天气数据的天气信息模型
completionTSCompletionBlock设置完成的回调。success：是否设置成功；error：设置失败时的错误信息，成功时为nil

代码示例：

id<TSWeatherInterface> weather = [TopStepComKit sharedInstance].weather;

// 创建城市信息
TSWeatherCity *city = [TSWeatherCity cityWithName:@"北京"];
city.latitude = 39.9042;
city.longitude = 116.4074;
city.provinceName = @"北京市";
city.countryName = @"中国";

// 创建天气代码
TSWeatherCodeModel *dayCode = [TSWeatherCodeModel weatherCodeWithCode:TSWeatherCodeSunnyDay];
TSWeatherCodeModel *nightCode = [TSWeatherCodeModel weatherCodeWithCode:TSWeatherCodeClearNight];

// 创建天气信息
TopStepWeather *weather = [[TopStepWeather alloc] init];
weather.city = city;
weather.dayCode = dayCode;
weather.nightCode = nightCode;
weather.curTemperature = 25;
weather.minTemperature = 18;
weather.maxTemperature = 28;
weather.humidity = 65;
weather.windScale = 3;
weather.windSpeed = 5.0;
weather.airpressure = 1013;
weather.uvIndex = 6;
weather.visibility = 10000;
weather.sunriseTime = [[NSDate dateWithTimeIntervalSinceNow:3600*6] timeIntervalSince1970];
weather.sunsetTime = [[NSDate dateWithTimeIntervalSinceNow:3600*18] timeIntervalSince1970];

// 创建每日预报
TSWeatherDay *day1 = [TSWeatherDay modelWithDayCode:dayCode
                                            nightCode:nightCode
                                              curTemp:25
                                              minTemp:18
                                              maxTemp:28];
weather.futhureSevenDays = @[day1];

// 创建每小时预报
TSWeatherHour *hour1 = [TSWeatherHour modelWithCode:dayCode
                                         temperature:25
                                           windScale:3];
weather.futhure24Hours = @[hour1];

// 推送天气信息
[weather pushWeather:weather completion:^(BOOL success, NSError * _Nullable error) {
    if (error) {
        TSLog(@"推送天气信息失败: %@", error.localizedDescription);
    } else {
        TSLog(@"推送天气信息成功");
    }
}];

设置天气功能开关​

控制设备是否显示天气信息。禁用时，设备将不会显示任何天气信息；启用时，如果有天气信息，设备将显示天气信息。

- (void)setWeatherEnable:(BOOL)enable completion:(TSCompletionBlock)completion;
参数名类型说明
enableBOOL是否启用天气功能。YES：启用天气功能；NO：禁用天气功能
completionTSCompletionBlock设置完成的回调。success：是否设置成功；error：设置失败时的错误信息，成功时为nil

代码示例：

id<TSWeatherInterface> weather = [TopStepComKit sharedInstance].weather;

// 启用天气功能
[weather setWeatherEnable:YES completion:^(BOOL success, NSError * _Nullable error) {
    if (error) {
        TSLog(@"设置天气功能失败: %@", error.localizedDescription);
    } else {
        TSLog(@"天气功能已启用");
    }
}];

获取天气功能开关状态​

获取设备中当前天气显示功能的状态，该状态表明设备当前是否正在显示天气信息。

- (void)fetchWeatherEnableWithCompletion:(void (^)(BOOL enabled, NSError *_Nullable error))completion;
参数名类型说明
completionvoid (^)(BOOL enabled, NSError *_Nullable error)获取完成的回调。enabled：天气功能是否启用；error：获取失败时的错误信息，成功时为nil

代码示例：

id<TSWeatherInterface> weather = [TopStepComKit sharedInstance].weather;

[weather fetchWeatherEnableWithCompletion:^(BOOL enabled, NSError * _Nullable error) {
    if (error) {
        TSLog(@"获取天气功能状态失败: %@", error.localizedDescription);
    } else {
        if (enabled) {
            TSLog(@"天气功能已启用");
        } else {
            TSLog(@"天气功能已禁用");
        }
    }
}];

注意事项​

  1. 权限要求：在使用天气接口前，确保已获得访问天气接口的权限
  2. 城市名称必需：TSWeatherCity 中的 cityName 属性为必需，其他属性均为可选
  3. 时间戳格式：所有时间戳均为 Unix 时间戳（秒），不是毫秒
  4. 温度单位：所有温度值均使用摄氏度（°C）
  5. 风力等级：风力等级范围为 0-18，其中 0 级表示无风，18 级表示 17 级以上
  6. 湿度范围：湿度为相对湿度百分比，范围为 0-100
  7. 紫外线指数：紫外线指数范围为 0-11，0 表示无紫外线，11 表示极强紫外线
  8. 空气质量：空气质量指数（AQI）范围为 0-5，分别表示优、良、轻度污染、中度污染、重度污染和严重污染
  9. 预报数据：futhureSevenDays 包含未来七天的预报（包含当天），futhure24Hours 包含未来 24 小时的预报（包含当前小时），均按时间顺序排列
  10. 夜间天气信息：nightCode 属性为可选，如果夜间天气信息不可用可设为 nil