跳到主要内容

提醒 (TSReminders)

提醒模块提供了完整的提醒管理功能，包括获取、创建、修改和删除设备上的提醒。支持内置提醒类型（久坐、喝水、吃药）和自定义提醒。

前提条件​

  1. 已成功初始化 TopStepComKit SDK
  2. 与设备建立了有效的蓝牙连接
  3. 设备支持提醒功能

数据模型​

TSRemindersModel​

提醒数据模型类，代表设备上的一个提醒。

属性名类型说明
reminderIdNSString *提醒的唯一标识符，由系统自动分配，请勿手动修改
reminderNameNSString *提醒的名称
enabledBOOL提醒是否启用（getter=isEnabled，读取用 reminder.isEnabled，赋值用 reminder.enabled = YES）
reminderTypeTSReminderType提醒的类型（未知、内置、自定义等）
repeatDaysTSRemindersRepeat提醒重复的星期几（位运算选项）
timeTypeTSReminderTimeType时间类型（时间点或时间段）
startTimeNSInteger提醒的开始时间（从0开始的分钟数，如360表示6:00）
endTimeNSInteger提醒的结束时间（从0开始的分钟数，如720表示12:00）
intervalNSInteger提醒间隔（分钟）
timePointsNSArray<NSNumber *> *具体的时间点数组（每个元素为从0开始的分钟数）
notesNSString *提醒的备注
isLunchBreakDNDEnabledBOOL午休免打扰功能是否启用
lunchBreakDNDStartTimeNSInteger午休免打扰开始时间（分钟，建议720即12:00）
lunchBreakDNDEndTimeNSInteger午休免打扰结束时间（分钟，建议840即14:00）

枚举与常量​

TSReminderType​

提醒类型枚举。

值说明
TSReminderTypeUnknown未知类型
TSReminderTypeSedentary久坐提醒
TSReminderTypeDrinking喝水提醒
TSReminderTypeTakeMedicine吃药提醒
TSReminderTypeCustom自定义提醒

TSRemindersRepeat​

提醒重复日期选项（位运算）。

值说明
TSRemindersRepeatMonday星期一
TSRemindersRepeatTuesday星期二
TSRemindersRepeatWednesday星期三
TSRemindersRepeatThursday星期四
TSRemindersRepeatFriday星期五
TSRemindersRepeatSaturday星期六
TSRemindersRepeatSunday星期日
TSRemindersRepeatWorkday工作日（周一至周五）
TSRemindersRepeatWeekend周末（周六至周日）
TSRemindersRepeatEveryday每天

TSReminderTimeType​

提醒时间类型枚举。

值说明
TSReminderTimeTypePeriod时间段（使用 startTime、endTime 和 interval）
TSReminderTimeTypePoint时间点（使用 timePoints 数组）

回调类型​

类型说明
void (^)(TSRemindersModel * _Nullable reminder, NSError * _Nullable error)创建自定义提醒模板的完成回调，返回提醒模型和错误信息
void (^)(NSArray<TSRemindersModel *> * _Nullable reminders, NSError * _Nullable error)获取所有提醒的完成回调，返回提醒数组和错误信息
void (^)(BOOL success, NSError * _Nullable error)通用操作完成回调，返回操作是否成功和错误信息（别名：TSCompletionBlock）

接口方法​

获取设备支持的最大自定义提醒数量​

- (NSInteger)maxSupportedCustomReminderCount;

获取设备支持的最大自定义提醒数量。

参数

无

返回值

类型说明
NSInteger设备上可以设置的最大自定义提醒数量

代码示例

id<TSRemindersInterface> remindersInterface = ...;
NSInteger maxCount = [remindersInterface maxSupportedCustomReminderCount];
TSLog(@"最大自定义提醒数量: %ld", (long)maxCount);

创建自定义提醒模板​

- (void)createCustomReminderTemplateWithCompletion:(void (^)(TSRemindersModel * _Nullable reminder, NSError * _Nullable error))completion;

创建一个自定义提醒模板（推荐使用）。此方法会自动分配有效的唯一ID、设置默认值，并确保在不同设备平台的兼容性。

参数

参数名类型说明
completionvoid (^)(TSRemindersModel * _Nullable, NSError * _Nullable)完成回调，返回一个可用的自定义提醒模型和错误信息

代码示例

id<TSRemindersInterface> remindersInterface = ...;

[remindersInterface createCustomReminderTemplateWithCompletion:^(TSRemindersModel * _Nullable reminder, NSError * _Nullable error) {
    if (error) {
        TSLog(@"创建提醒模板失败: %@", error.localizedDescription);
        return;
    }
    
    // 配置提醒
    reminder.reminderName = @"运动提醒";
    reminder.enabled = YES;
    reminder.repeatDays = TSRemindersRepeatEveryday;
    reminder.timeType = TSReminderTimeTypePoint;
    reminder.timePoints = @[@360, @720]; // 6:00 和 12:00
    
    // 保存提醒到设备
    [remindersInterface setReminder:reminder completion:^(BOOL success, NSError * _Nullable error) {
        if (success) {
            TSLog(@"提醒已保存到设备");
        } else {
            TSLog(@"保存提醒失败: %@", error.localizedDescription);
        }
    }];
}];

获取所有提醒设置​

- (void)fetchAllRemindersWithCompletion:(void (^)(NSArray<TSRemindersModel *> * _Nullable reminders, NSError * _Nullable error))completion;

获取设备上的所有提醒设置。

参数

参数名类型说明
completionvoid (^)(NSArray<TSRemindersModel *> * _Nullable, NSError * _Nullable)完成回调，返回提醒对象数组和错误信息

代码示例

id<TSRemindersInterface> remindersInterface = ...;

[remindersInterface fetchAllRemindersWithCompletion:^(NSArray<TSRemindersModel *> * _Nullable reminders, NSError * _Nullable error) {
    if (error) {
        TSLog(@"获取提醒失败: %@", error.localizedDescription);
        return;
    }
    
    TSLog(@"获取到 %lu 个提醒", (unsigned long)reminders.count);
    for (TSRemindersModel *reminder in reminders) {
        TSLog(@"提醒: %@ (类型: %ld, 启用: %@)", 
              reminder.reminderName, 
              (long)reminder.reminderType,
              reminder.isEnabled ? @"是" : @"否");
    }
}];

全量替换提醒设置​

- (void)replaceAllReminders:(NSArray<TSRemindersModel *> *)reminders completion:(TSCompletionBlock)completion;

用提供的数组全量替换设备上的所有提醒。

参数

参数名类型说明
remindersNSArray<TSRemindersModel *> *用于替换当前提醒的提醒对象数组
completionvoid (^)(BOOL, NSError * _Nullable)完成回调，返回是否成功和错误信息

代码示例

id<TSRemindersInterface> remindersInterface = ...;

// 先获取所有提醒
[remindersInterface fetchAllRemindersWithCompletion:^(NSArray<TSRemindersModel *> * _Nullable reminders, NSError * _Nullable error) {
    if (error || !reminders) return;
    
    NSMutableArray *updatedReminders = [NSMutableArray arrayWithArray:reminders];
    
    // 修改某个提醒
    if (updatedReminders.count > 0) {
        TSRemindersModel *firstReminder = updatedReminders[0];
        firstReminder.enabled = NO;
    }
    
    // 全量替换
    [remindersInterface replaceAllReminders:updatedReminders completion:^(BOOL success, NSError * _Nullable error) {
        if (success) {
            TSLog(@"提醒已全量替换");
        } else {
            TSLog(@"替换提醒失败: %@", error.localizedDescription);
        }
    }];
}];

更新或新增提醒​

- (void)setReminder:(TSRemindersModel *)reminder completion:(TSCompletionBlock)completion;

根据提醒ID更新提醒。如果指定ID的提醒存在则更新，不存在则自动新增（受设备数量上限约束）。

参数

参数名类型说明
reminderTSRemindersModel *包含更新信息的提醒模型，必须具有有效的 reminderId
completionvoid (^)(BOOL, NSError * _Nullable)完成回调，返回是否成功和错误信息

代码示例

id<TSRemindersInterface> remindersInterface = ...;

// 创建新提醒
[remindersInterface createCustomReminderTemplateWithCompletion:^(TSRemindersModel * _Nullable reminder, NSError * _Nullable error) {
    if (error) {
        TSLog(@"创建模板失败: %@", error.localizedDescription);
        return;
    }
    
    // 配置提醒参数
    reminder.reminderName = @"喝水提醒";
    reminder.enabled = YES;
    reminder.reminderType = TSReminderTypeCustom;
    reminder.repeatDays = TSRemindersRepeatWorkday; // 工作日
    reminder.timeType = TSReminderTypeTypePeriod; // 时间段
    reminder.startTime = 480;  // 8:00
    reminder.endTime = 1020;   // 17:00
    reminder.interval = 60;    // 每60分钟提醒一次
    reminder.isLunchBreakDNDEnabled = YES;
    reminder.lunchBreakDNDStartTime = 720;  // 12:00
    reminder.lunchBreakDNDEndTime = 840;    // 14:00
    
    // 设置提醒
    [remindersInterface setReminder:reminder completion:^(BOOL success, NSError * _Nullable error) {
        if (success) {
            TSLog(@"提醒 '%@' 已保存", reminder.reminderName);
        } else {
            TSLog(@"保存提醒失败: %@", error.localizedDescription);
        }
    }];
}];

删除提醒​

- (void)deleteReminderWithId:(NSString *)reminderId completion:(TSCompletionBlock)completion;

根据提醒ID删除提醒。

参数

参数名类型说明
reminderIdNSString *要删除的提醒的唯一标识符
completionvoid (^)(BOOL, NSError * _Nullable)完成回调，返回是否成功和错误信息

代码示例

id<TSRemindersInterface> remindersInterface = ...;

// 假设已获取提醒的 reminderId
NSString *reminderId = @"reminder_001";

[remindersInterface deleteReminderWithId:reminderId completion:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"提醒已删除");
    } else {
        TSLog(@"删除提醒失败: %@", error.localizedDescription);
    }
}];

验证提醒模型数组​

+ (NSError * _Nullable)validateReminders:(NSArray<TSRemindersModel *> *)reminders;

验证一个提醒模型数组，检查每个模型的有效性。

参数

参数名类型说明
remindersNSArray<TSRemindersModel *> *要验证的提醒模型数组

返回值

类型说明
NSError * _Nullable返回第一个错误，如果所有模型都有效则返回 nil

代码示例

// 验证提醒数组
NSArray<TSRemindersModel *> *reminders = ...;
NSError *validationError = [TSRemindersModel validateReminders:reminders];

if (validationError) {
    TSLog(@"提醒验证失败: %@", validationError.localizedDescription);
} else {
    TSLog(@"所有提醒验证通过");
}

注意事项​

  1. 勿直接创建实例：请勿使用 [[TSRemindersModel alloc] init] 直接创建提醒实例。获取提醒的方式应为：

    • 通过 fetchAllRemindersWithCompletion: 获取现有提醒
    • 通过 createCustomReminderTemplateWithCompletion: 创建新的自定义提醒

  2. 内置提醒无法删除：久坐、喝水、吃药等内置提醒无法通过 deleteReminderWithId: 删除，只能通过修改 enabled 属性来禁用。

  3. 自定义提醒可完全管理：自定义提醒可以进行全部操作：创建、修改、删除。

  4. 设备数量限制：创建自定义提醒时应检查 maxSupportedCustomReminderCount 限制，避免超过设备支持的最大数量。

  5. 时间格式：所有时间都以从午夜（0:00）开始的分钟数表示：

    • 0 = 00:00（午夜）
    • 360 = 06:00（早上6点）
    • 720 = 12:00（中午）
    • 1020 = 17:00（下午5点）
    • 1440 = 24:00（下一天的午夜）

  6. 时间类型选择：

    • 使用 TSReminderTimeTypePoint 时，应配置 timePoints 数组
    • 使用 TSReminderTimeTypePeriod 时，应配置 startTime、endTime 和 interval

  7. 重复日期配置：使用位运算组合多个日期，例如 TSRemindersRepeatMonday | TSRemindersRepeatWednesday | TSRemindersRepeatFriday 表示周一、周三、周五。

  8. 午休免打扰：当启用 isLunchBreakDNDEnabled 时，建议将 lunchBreakDNDStartTime 设为 720（12:00）、lunchBreakDNDEndTime 设为 840（14:00）。

  9. 全量替换的危险性：调用 replaceAllReminders:completion: 会完全覆盖设备上的所有提醒，使用前应谨慎确认。

  10. 异步操作：所有操作都是异步的，必须通过 completion 回调获取结果，不要在同步上下文中依赖操作结果。