世界时钟（TSWorldClock）

该模块提供了世界时钟的管理功能，支持设备上多个时区时钟的设置、查询、添加、删除和变化监听。用户可以为不同的城市添加世界时钟，并管理其时区信息和显示格式。

前提条件

TopStepComKit iOS SDK 已正确集成到项目中
设备已连接并初始化完成
已完成 SDK 初始化

数据模型

TSWorldClockModel

属性名	类型	说明
`clockId`	`UInt8`	时钟条目的唯一标识符，取值范围 `[0, supportMaxWorldClockCount - 1]`。`addWorldClock:` 时无需设置（填 0 即可），SDK 自动分配；`deleteWorldClockWithId:` 时需使用 `getAllWorldClocksCompletion:` 返回列表中的 ID
`cityName`	`NSString *`	城市名称。最大字节长度由 `supportMaxCityNameLength` 决定（注意 1 个中文 ≈ 3 字节）
`timeZoneIdentifier`	`NSString *`	IANA 时区标识符，例如 "Asia/Shanghai"
`utcOffsetInSeconds`	`NSInteger`	UTC 偏移量（秒），范围为 -43200 到 +43200。正值表示比 UTC 快（东区），负值表示比 UTC 慢（西区）

timeFormat、longitude、latitude 属性目前 NS_UNAVAILABLE，请勿使用。

回调类型

回调类型	说明
`TSWorldClockResultBlock`	`void(^)(NSArray<TSWorldClockModel > allWorldClocks, NSError * _Nullable error)` — 世界时钟操作结果回调，返回所有世界时钟数组或错误信息

接口方法

获取设备支持的最大世界时钟数量

- (NSInteger)supportMaxWorldClockCount;

参数	类型	说明
返回值	`NSInteger`	设备支持的最大世界时钟数量。返回 0 表示设备不支持世界时钟功能

代码示例：

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;
NSInteger maxCount = [worldClock supportMaxWorldClockCount];
TSLog(@"设备最多支持 %ld 个世界时钟", (long)maxCount);

获取城市名称最大字节长度

- (NSInteger)supportMaxCityNameLength;

参数	类型	说明
返回值	`NSInteger`	城市名称允许的最大字节长度。返回 0 表示设备不支持城市名称

代码示例：

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;
NSInteger maxLen = [worldClock supportMaxCityNameLength];
TSLog(@"城市名称最大字节长度：%ld（注意一个中文字符约占 3 字节）", (long)maxLen);

获取所有世界时钟

- (void)getAllWorldClocksCompletion:(_Nullable TSWorldClockResultBlock)completion;

参数	类型	说明
`completion`	`TSWorldClockResultBlock`	回调块，返回所有世界时钟数组或错误信息

代码示例：

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;

[worldClock getAllWorldClocksCompletion:^(NSArray<TSWorldClockModel *> *allWorldClocks, NSError *error) {
    if (error) {
        TSLog(@"获取世界时钟失败: %@", error.localizedDescription);
        return;
    }
    TSLog(@"获取到 %lu 个世界时钟", (unsigned long)allWorldClocks.count);
    for (TSWorldClockModel *clock in allWorldClocks) {
        TSLog(@"ID: %d, 城市: %@, 时区: %@, UTC偏移: %ld秒",
              clock.clockId, clock.cityName,
              clock.timeZoneIdentifier, (long)clock.utcOffsetInSeconds);
    }
}];

设置所有世界时钟

- (void)setAllWorldClocks:(NSArray<TSWorldClockModel *> *_Nullable)allWorldClocks
               completion:(TSCompletionBlock)completion;

参数	类型	说明
`allWorldClocks`	`NSArray<TSWorldClockModel > `	要设置的世界时钟数组。传 nil 或空数组将清空所有世界时钟
`completion`	`TSCompletionBlock`	操作完成回调

代码示例：

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;

TSWorldClockModel *shanghai = [TSWorldClockModel modelWithClockId:0
                                                         cityName:@"Shanghai"
                                               timeZoneIdentifier:@"Asia/Shanghai"
                                               utcOffsetInSeconds:28800];

TSWorldClockModel *newYork = [TSWorldClockModel modelWithClockId:1
                                                        cityName:@"New York"
                                              timeZoneIdentifier:@"America/New_York"
                                              utcOffsetInSeconds:-18000];

[worldClock setAllWorldClocks:@[shanghai, newYork] completion:^(NSError *error) {
    if (error) {
        TSLog(@"设置世界时钟失败: %@", error.localizedDescription);
    } else {
        TSLog(@"世界时钟设置成功");
    }
}];

添加单个世界时钟

- (void)addWorldClock:(TSWorldClockModel *)worldClock
           completion:(_Nullable TSCompletionBlock)completion;

参数	类型	说明
`worldClock`	`TSWorldClockModel *`	要添加的世界时钟模型。`clockId` 由 SDK 自动分配
`completion`	`TSCompletionBlock`	操作完成回调。已达 `supportMaxWorldClockCount` 时返回错误

代码示例：

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;

TSWorldClockModel *tokyo = [TSWorldClockModel modelWithClockId:0
                                                      cityName:@"Tokyo"
                                            timeZoneIdentifier:@"Asia/Tokyo"
                                            utcOffsetInSeconds:32400];

[worldClock addWorldClock:tokyo completion:^(NSError *error) {
    if (error) {
        TSLog(@"添加世界时钟失败: %@", error.localizedDescription);
    } else {
        TSLog(@"世界时钟添加成功");
    }
}];

通过 clockId 删除单个世界时钟

- (void)deleteWorldClockWithId:(UInt8)clockId
                    completion:(_Nullable TSCompletionBlock)completion;

参数	类型	说明
`clockId`	`UInt8`	要删除的世界时钟 ID。必须是从 `getAllWorldClocksCompletion:` 返回列表中获取的有效 ID
`completion`	`TSCompletionBlock`	操作完成回调。设备上不存在对应 ID 时返回错误

代码示例：

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;

[worldClock deleteWorldClockWithId:1 completion:^(NSError *error) {
    if (error) {
        TSLog(@"删除世界时钟失败: %@", error.localizedDescription);
    } else {
        TSLog(@"世界时钟删除成功");
    }
}];

删除所有世界时钟

- (void)deleteAllWorldClocksWithCompletion:(_Nullable TSCompletionBlock)completion;

参数	类型	说明
`completion`	`TSCompletionBlock`	操作完成回调

代码示例：

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;

[worldClock deleteAllWorldClocksWithCompletion:^(NSError *error) {
    if (error) {
        TSLog(@"删除所有世界时钟失败: %@", error.localizedDescription);
    } else {
        TSLog(@"所有世界时钟已删除");
    }
}];

注册世界时钟变化监听

- (void)registerWorldClocksDidChangedBlock:(_Nullable TSWorldClockResultBlock)completion;

参数	类型	说明
`completion`	`TSWorldClockResultBlock`	世界时钟变化时触发的回调块，返回更新后的所有世界时钟数组或错误信息

代码示例：

id<TSWorldClockInterface> worldClock = [TopStepComKit sharedInstance].worldClock;

[worldClock registerWorldClocksDidChangedBlock:^(NSArray<TSWorldClockModel *> *allWorldClocks, NSError *error) {
    if (error) {
        TSLog(@"监听世界时钟变化失败: %@", error.localizedDescription);
        return;
    }
    TSLog(@"世界时钟已变化，当前共 %lu 个", (unsigned long)allWorldClocks.count);
}];

校验世界时钟模型数组

+ (NSError * _Nullable)validateWorldClocks:(NSArray<TSWorldClockModel *> *)worldClocks
                         maxCityNameLength:(NSInteger)maxCityNameLength;

参数	类型	说明
`worldClocks`	`NSArray<TSWorldClockModel > `	要校验的世界时钟数组
`maxCityNameLength`	`NSInteger`	`cityName` 最大字节长度。传 0 表示不校验
返回值	`NSError *`	校验失败返回错误对象，全部通过返回 nil

代码示例：

NSError *error = [TSWorldClockModel validateWorldClocks:@[shanghai, newYork]
                                      maxCityNameLength:32];
if (error) {
    TSLog(@"世界时钟校验失败：%@", error.localizedDescription);
}

创建世界时钟模型

+ (instancetype)modelWithClockId:(UInt8)clockId
                        cityName:(NSString *)cityName
              timeZoneIdentifier:(NSString *)timeZoneIdentifier
              utcOffsetInSeconds:(NSInteger)utcOffsetInSeconds;

参数	类型	说明
`clockId`	`UInt8`	时钟条目的唯一标识符
`cityName`	`NSString *`	城市名称
`timeZoneIdentifier`	`NSString *`	IANA 时区标识符
`utcOffsetInSeconds`	`NSInteger`	UTC 偏移量（秒），范围 -43200 到 +43200

返回值：新创建的世界时钟模型实例。

比较两个世界时钟模型是否相等

- (BOOL)isEqualToWorldClockModel:(TSWorldClockModel *)otherModel;

两个模型相等的条件是 clockId、cityName、timeZoneIdentifier、utcOffsetInSeconds 都相同。

注意事项

clockId 分配：addWorldClock: 时无需设置 clockId，SDK 自动分配；deleteWorldClockWithId: 时必须使用 getAllWorldClocksCompletion: 返回的有效 ID
UTC 偏移量范围：utcOffsetInSeconds 的有效范围是 -43200 到 +43200 秒，对应 UTC-12 到 UTC+12
时区标识符：使用标准 IANA 时区标识符（例如 "Asia/Shanghai"、"America/New_York"），确保兼容性
setAllWorldClocks: 会覆盖所有现有世界时钟设置，如需保留其他世界时钟，应先调用 getAllWorldClocksCompletion: 获取后再修改
设备支持限制：在添加前先调用 supportMaxWorldClockCount、supportMaxCityNameLength 获取设备能力
模型创建限制：TSWorldClockModel 的 init、new、copy、mutableCopy 不可用，必须使用工厂方法
不可用属性：timeFormat、longitude、latitude 暂不可用
变化监听：同一时间只允许一个监听者，新的注册会替换之前的监听者
错误处理：始终检查回调中的 error 参数

前提条件​

数据模型​

TSWorldClockModel​

回调类型​

接口方法​

获取设备支持的最大世界时钟数量​

获取城市名称最大字节长度​

获取所有世界时钟​

设置所有世界时钟​

添加单个世界时钟​

通过 clockId 删除单个世界时钟​

删除所有世界时钟​

注册世界时钟变化监听​

校验世界时钟模型数组​

创建世界时钟模型​

比较两个世界时钟模型是否相等​

注意事项​

前提条件

数据模型

TSWorldClockModel

回调类型

接口方法

获取设备支持的最大世界时钟数量

获取城市名称最大字节长度

获取所有世界时钟

设置所有世界时钟

添加单个世界时钟

通过 clockId 删除单个世界时钟

删除所有世界时钟

注册世界时钟变化监听

校验世界时钟模型数组

创建世界时钟模型

比较两个世界时钟模型是否相等

注意事项