11.3：后台代理提醒

APP 开发过程中会有定时任务的场景，比如闹钟类 APP，设定闹铃后时间到了就触发APP的提醒，ArkUI开发框架在 @kit.BackgroundTasksKit 模块里提供了相关 API 支持定时任务的场景，本节笔者简单介绍一下如何发布和取消一个后台代理提醒。

11.3.1：限制与约束

• 发布后台代理提醒，需要申请 ohos.permission.PUBLISH_AGENT_REMINDER 权限。

11.3.2：reminderAgent API介绍

@kit.BackgroundTasksKit 模块里提供了发布后台代理提醒和取消后台代理提醒的相关 API，部分 API 如下所示：

declare namespace reminderAgentManager {
  // 发送后台代理提醒
  function publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void;
  // 取消后台代理提醒
  function cancelReminder(reminderId: number, callback: AsyncCallback<void>): void;
  // 获取所有后台代理提醒
  function getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void;
  // 取消所有后台代理提醒
  function cancelAllReminders(callback: AsyncCallback<void>): void;
  
  // 省略部分API
  
}

• publishReminder：发布一个后台代理提醒。ReminderRequest 参数说明如下：
  • reminderType：设置后台提醒类型，它支持以下三种类型：
    • REMINDER_TYPE_TIMER：倒计时提醒，当使用该类型时 reminderReq 参数需要使用ReminderRequestTimer配置。
    • REMINDER_TYPE_CALENDAR：日历提醒，当使用该类型时 reminderReq 参数需要使用 ReminderRequestCalendar 配置。
    • REMINDER_TYPE_ALARM：闹钟提醒。当使用该类型时 reminderReq 参数需要使用 ReminderRequestAlarm 配置。
  • actionButton：弹出的提醒通知栏中显示的按钮（参数可选，支持0/1/2个按钮）。
  • wantAgent：点击通知后需要跳转的目标 ability 信息。
  • maxScreenWantAgent：提醒到达时跳转的目标包。如果设备正在使用中，则弹出一个通知框。
  • ringDuration：指明响铃时长。
  • snoozeTimes：指明延迟提醒次数。
  • timeInterval：执行延迟提醒间隔。
  • title：指明提醒标题。
  • content：指明提醒内容。
  • expiredContent：指明提醒过期后需要显示的内容。
  • snoozeContent：指明延迟提醒时需要显示的内容。
  • notificationId：指明提醒使用的通知的id号，相同id号的提醒会覆盖。
  • slotType：指明提醒的slot类型。
• cancelReminder：取消后台代理提醒。
• getValidReminders：获取当前应用已设置的所有有效（未过期）的提醒。
• cancelAllReminders：取消当前应用所有的提醒。

11.3.3：reminderAgentManager 使用步骤

• 引入reminderAgent模块

  import { reminderAgentManager } from '@kit.BackgroundTasksKit';
  

• 发布一个后台代理提醒

  private startTimer() {
    let timer = {
      reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER,
      triggerTimeInSeconds: 10
    }
    reminderAgentManager.publishReminder(timer, (error, reminderId) => {
      if(reminderId) {
        // 发送成功，如果需要取消该提醒，这要使用该reminderId
      }
    })
  }
  

• 取消一个后台代理提醒

  private cancelTimer() {
    reminderAgentManager.cancelReminder(this.reminderId, (error, data) => {
      if(!error) {
        // 取消成功
      }
    })
  }
  

• 取消所有后台代理提醒

  private cancelAllTimer() {
    reminderAgentManager.cancelAllReminders((error, data) => {
      if(!error) {
        // 取消成功
      }
    })
  }
  

11.3.4：reminderAgentManager 完整样例

import { reminderAgentManager } from '@kit.BackgroundTasksKit';
import { notificationManager } from '@kit.NotificationKit';
import { ContextHolder } from './context_holder';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry @Component struct ReminderAgentTest {

  private reminderId: number = 0;
  @State state: string = "订阅状态"

  build() {
    Column({ space: 10 }) {

      Text(this.state)
        .fontSize(20)

      Button("请求通知权限")
        .onClick(() => {
          this.requestNotificationPermission()
        })

      Button('发起定时提醒')
        .onClick(() => {
          this.startTimer();
        })

      Button('取消定时提醒')
        .onClick(() => {
          this.cancelTimer();
        })

      Button('取消所有定时提醒')
        .onClick(() => {
          this.cancelAllTimer();
        })
    }
    .width('100%')
    .height('100%')
    .padding(10)
  }

  private requestNotificationPermission() {
    if (notificationManager.isNotificationEnabledSync()) {
      this.state = "已经获取到通知权限: " + ContextHolder.getContext()
    } else {
      notificationManager.requestEnableNotification(ContextHolder.getContext(), (error: BusinessError) => {
        this.state = "请求通知权限失败: " + JSON.stringify(error)
      })
    }
  }

  // 开启后台代理提醒
  private startTimer() {
    let timer: reminderAgentManager.ReminderRequestTimer = {
      reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,// 定时器
      triggerTimeInSeconds: 5,                                     // 5秒后触发提醒
      title: "标题测试",                                            // 标题
      content: "标题内容测试",                                       // 内容
      notificationId: 10086                                        // 任务ID
    }

    reminderAgentManager.publishReminder(timer, (error, reminderId) => {  // 发布一个提醒
      if (error) {
        this.state = JSON.stringify(error)
      } else {
        // 发送成功
        this.reminderId = reminderId;
        this.state = "订阅成功：" + this.reminderId
      }
    })
  }

  // 取消后台代理提醒
  private cancelTimer() {
    reminderAgentManager.cancelReminder(this.reminderId, (error, data) => {
      if(error) {
        this.state = "取消失败: " + JSON.stringify(error)
      } else {
        this.state = "取消成功"
      }
    })
  }

  private cancelAllTimer() {
    reminderAgentManager.cancelAllReminders((error, data) => {
      if(error) {
        this.state = "所有取消失败: " + JSON.stringify(error)
      } else {
        this.state = "所有取消成功"
      }
    })
  }
}

样例运行结果如下图所示：

(adsbygoogle = window.adsbygoogle || []).push({});