HarmonyOS之后台代理定时提醒的功能使用

一、简介

• 在应用开发时，可以调用后台代理提醒类 ReminderRequest 去创建定时提醒，包括倒计时、日历、闹钟三种提醒类型。
• 使用后台代理提醒能力后，应用可以被冻结或退出，计时和弹出提醒的功能将被后台系统服务代理。

二、API 说明

• ReminderRequest 涉及的基础类包括 ReminderHelper、ReminderRequestTimer、ReminderRequestCalendar、ReminderRequestAlarm，基础类之间的关系如下图所示：

• ReminderHelper：封装了发布、取消提醒类通知的方法。ReminderHelper 主要接口：

接口名	描述
public static int publishReminder(ReminderRequest reminderReq) throws RemoteException, ReminderManager.AppLimitExceedsException, ReminderManager.SysLimitExceedsException	发布一个定时提醒类通知 ReminderManager.AppLimitExceedsException 系统中保存的当前应用有效的提醒个数超出最大限制数量30个时抛出（不包括已经超时，即后续不会再提醒的提醒实例） ReminderManager.SysLimitExceedsException 系统中保存的整个系统有效的提醒个数超出最大限制数量2000个时抛出（不包括已经超时，即后续不会再提醒的提醒实例）
public static void addNotificationSlot(NotificationSlot slot) throws RemoteException	注册一个提醒类需要使用的NotificationSlot
public static void cancelReminder(int reminderId) throws RemoteException	取消一个指定的提醒类通知。(reminderId从publishReminder的返回值获取)
public static void removeNotificationSlot(String slotId) throws RemoteException	删除一个slot实例
public static List getValidReminders() throws RemoteException	获取当前应用设置的所有有效的提醒
public static void cancelAllReminders() throws RemoteException	取消当前应用设置的所有提醒

• ReminderRequest：后台代理提醒类基类，封装了提醒相关的属性查询和设置的操作。ReminderRequest 主要接口：

接口名	描述
public long getRingDuration()	获取设置的提醒时长，单位秒。如设置的开始响铃后的响铃时长
public int getSnoozeTimes()	获取设置的延迟提醒次数
public long getTimeInterval()	获取设置的延迟提醒间隔
public ReminderRequest setRingDuration(long ringDurationInSeconds)	设置提醒时长，单位秒，如设置开始响铃后的响铃时长
public ReminderRequest setSnoozeTimes(int snoozeTimes)	设置延迟提醒的次数。(倒计时设置延迟提醒无效)
public ReminderRequest setTimeInterval(long timeIntervalInSeconds)	设置延迟提醒的时间间隔。(倒计时设置延迟提醒无效)
public ReminderRequest setActionButton(String title, int type)	在提醒弹出的通知界面中添加NotificationActionButton
public ReminderRequest setIntentAgent(String pkgName, String abilityName)	设置点击通知信息后需要跳转的目标包的信息
public ReminderRequest setMaxScreenIntentAgent(String pkgName, String abilityName)	设置提醒到达时跳转的目标包。如果设备正在使用中，则弹出一个通知框
public String getTitle()	获取提醒的标题
public ReminderRequest setTitle(String title)	设置提醒的标题
public String getContent()	获取提醒的内容
public ReminderRequest setContent(String content)	设置提醒的内容
public String getExpiredContent()	获取提醒“过期”时显示的扩展内容
public ReminderRequest setExpiredContent(String expiredContent)	设置提醒“过期”时显示的扩展内容
public String getSnoozeContent()	获取提醒“再响”时显示的扩展内容
public ReminderRequest setSnoozeContent(String snoozeContent)	设置提醒“再响”时显示的扩展内容
public int getNotificationId()	获取提醒使用的notificationRequest的id，参见NotificationRequest.setNotificationId(int id)
public ReminderRequest setNotificationId(int notificationId)	设置提醒使用的notificationRequest的id
public String getSlotId()	获取提醒使用的slot id
public String SetSlotId(String slotId)	设置提醒使用的slot id

• ReminderRequestTimer：提醒类子类，用于倒计时提醒。ReminderRequestTimer 主要接口：

接口名	描述
public ReminderRequestTimer(long triggerTimeInSeconds)	创建一个倒计时提醒实例。经过指定时间后触发提醒

• ReminderRequestCalendar：提醒类子类，用于日历类提醒。可以指定提醒时间精确为：年月日时分，可以指定哪些月份的哪些天的同一时间重复提醒。ReminderRequestCalendar 主要接口：

接口名	描述
public ReminderRequestCalendar(LocalDateTime dateTime, int[] repeatMonths, int[] repeatDays)	创建一个日历类提醒实例，在指定的时间触发提醒

• ReminderRequestAlarm：提醒类子类，用于闹钟类提醒，可以指定几点几分提醒，或者每周哪几天指定时间提醒。ReminderRequestAlarm 主要接口：

接口名	描述
public ReminderRequestAlarm(int hour, int minute, int[] daysOfWeek)	创建一个闹钟类提醒实例，在指定的时间触发提醒

三、后台代理定时提醒

• 声明使用权限：使用后台代理提醒需要在配置文件中声明需要此权限：

  "reqPermissions": [  {"name": "ohos.permission.PUBLISH_AGENT_REMINDER"  }]

• 创建一个提醒的步骤如下：

	// 1. 设置渠道信息
	NotificationSlot slot = new NotificationSlot("slot_id", "slot_name", NotificationSlot.LEVEL_HIGH);
	slot.setEnableLight(false);
	slot.setEnableVibration(true);
	// 2. 向代理服务添加渠道对象
	try {
	    ReminderHelper.addNotificationSlot(slot);
	} catch (RemoteException e) {
	    e.printStackTrace();
	}
	// 3. 创建提醒类通知对象
	int[] repeatDay = {};
	ReminderRequest reminder = new ReminderRequestAlarm(10, 30, repeatDay);
	// 4. 设置提醒内容
	reminder.setTitle("set title here").setContent("set content here");
	// 5. 设置提醒时长等属性
	reminder.setSnoozeTimes(1).setTimeInterval(5 * 60).setRingDuration(10);
	// 6. 设置IntentAgent, （假设包名为：com.ohos.aaa，Ability类名为FirstAbility）
	reminder.setIntentAgent("com.ohos.aaa", FirstAbility.class.getName());
	// 7. 设置提醒信息框中的“延迟提醒”和“关闭”按钮（可选）（ActionButton）
	reminder.setActionButton("snooze", ReminderRequest.ACTION_BUTTON_TYPE_SNOOZE).setActionButton("close", ReminderRequest.ACTION_BUTTON_TYPE_CLOSE);
	// 8. 发布提醒类通知
	try {
	    ReminderHelper.publishReminder(reminder);
	} catch (ReminderManager.AppLimitExceedsException e) {
	    e.printStackTrace();
	} catch (ReminderManager.SysLimitExceedsException e) {
	    e.printStackTrace();
	} catch (RemoteException e) {
	    e.printStackTrace();
	}

• 创建一个倒计时提醒示例如下：

	// 经过1分钟后提醒
	ReminderRequest reminderRequestTimer = new ReminderRequestTimer(60);

• 创建一个一次性日历提醒的示例如下：

	// 2021年3月2日14点30分提醒
	int[] repeatMonths = {};
	int[] repeatDays = {};
	ReminderRequestCalendar reminderRequestCalendar = new ReminderRequestCalendar( LocalDateTime.of(2021, 3, 2, 14, 30), repeatMonths, repeatDays);

• 创建一个重复的日历提醒的示例如下：

	// 3月份，5月份的9号和15号 14点30分提醒，延迟10分钟后再次提醒，默认延迟次数为3次
	
	int[] repeatMonths = {3, 5};
	int[] repeatDaysOfMonth = {9, 15};
	ReminderRequestCalendar reminderRequestCalender = new ReminderRequestCalendar( LocalDateTime.of(2021, 3, 2, 14, 30), repeatMonths, repeatDaysOfMonth);
	reminderRequestCalender.setTimeInterval(10 * 60);

• 创建一个一次性闹钟提醒的示例如下：

	// 13点59分提醒，如果当前时间大于13点59分，则取后一天的13点59分
	int[] repeatDay = {};
	ReminderRequest reminderRequestAlarm = new ReminderRequestAlarm(13, 59, repeatDay);

• 创建一个重复的闹钟提醒的示例如下：

	// 每周1，2，3，4的13点59分提醒
	int[] repeatDay = {1, 2, 3, 4};
	ReminderRequest reminderRequestAlarm = new ReminderRequestAlarm(13, 59, repeatDay);

• 创建一个用于延迟提醒的 ActionButton 界面的示例如下：

	reminderRequest.setActionButton("snooze", ReminderRequest.ACTION_BUTTON_TYPE_SNOOZE);

• 创建一个用于关闭提醒的 ActionButton 界面的示例如下：

	reminderRequest.setActionButton("close", ReminderRequest.ACTION_BUTTON_TYPE_CLOSE);

• 注意：
• • notificationId 相同的不同 NotificationRequest 请求，在通知栏展示的内容会被覆盖，对于提醒来说，可能不希望被覆盖，开发时可以注意设置不同的 notificationId；
• • 倒计时不支持持久化，系统重启后，所有倒计时失效。