Harmony OS 后台任务-代理提醒

三、代理提醒

传送门

1.什么是代理提醒

• 应用退到后台或进程终止后，仍然有一些提醒用户的定时类任务，例如购物类应用抢购提醒等，为满足此类功能场景，系统提供了代理提醒（reminderAgentManager）的能力。当应用退至后台或进程终止后，系统会代理应用做相应的提醒。当前支持的提醒类型包括：
  • 倒计时：基于倒计时的提醒功能
  • 日历：基于日历的提醒功能
  • 闹钟：基于时钟的提醒功能
• 不同的代理提醒主要是通过 reminderType 来设置
  • 倒计时 reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER
  • 日历 reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR
  • 闹钟 reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM
• 倒计时类, 日历类, 闹钟类 代理提醒的操作步骤是一样的, 只不过最初始定义的对象内容不一样。

2.代理提醒限制

• 一个三方应用支持最多30个有效提醒（有效即发布成功），一个系统应用支持最多10000个有效提醒，整个系统最多支持12000个有效提醒
• 点击提醒通知后跳转的应用必须是申请代理提醒的本应用
• 需要一个通知权限, 因为不管是闹钟还是倒计时, 到位以后需要一个提示出现，当你没有申请通知的时候, 这个代理提醒是不会生效的

3.代理提醒api

4.开启代理提醒

4.1 引入依赖

import { reminderAgentManager } from '@kit.BackgroundTasksKit'
import { notificationManager } from '@kit.NotificationKit'

4.2 通知权限申请

// 申请一下通知权限
notificationManager
  .isNotificationEnabled()
  .then((data: boolean) => {
    if (!data) {
      // 表示没有通知权限, 我们申请一个通知权限, 然后在发布代理提醒
      notificationManager
        .requestEnableNotification(this.context)
        .then(() => {
          // 用户同意了通知发送
          // sendReminder()
        })
        .catch(() => console.log('wuwuwu => 用户选择禁用按钮了'))
    } else {
      // 表示有通知权限, 直接发布代理提醒
      this.sendReminder()
    }
  })
  .catch(() => {
    console.log('wuwuwu => 检测到目前通知权限为禁用状态')
  })

4.3 创建 agent 对象

// 倒计时
@State targetReminderAgent: reminderAgentManager.ReminderRequestTimer = Object()
// 日历
@State targetReminderAgent: reminderAgentManager.ReminderRequestCalendar = Object()
// 闹钟
@State targetReminderAgent: reminderAgentManager.ReminderRequestAlarm = Object()

4.3 倒计时类提醒

  // 2. 初始化 agent 对象
  this.targetReminderAgent = {
    // 代理提醒类型
    reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,
    // 触发时间( 多少秒以后 )
    triggerTimeInSeconds: 15,
    // ================ 以下为可选参数 ================
    // 通知的标题
    title: 'title',
    // 通知的内容
    content: 'content',
    // 通知的 id 编号( 两个一样的编号会覆盖 )
    notificationId: 111111,
    // 通知类型
    slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION,
    // 给通知添加一些按钮
    actionButton: [
      {
        // 按钮名称
        title: '关闭按钮',
        // 按钮类型( 其实就是你点击按钮的时候能执行的操作 )
        // 关闭按钮的意思( 当你点击这个按钮的时候, 直接关闭通知 )
        type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
      }
    ],
    // 添加一个简单的 want 对象
    // 是被 reminder 修饰过的 want 对象( 只能添加一些简单的信息 )
    wantAgent: {
      // 当前 App 包名
      pkgName: 'com.example.mytask',
      // 对应拉起的 ability 名称
      abilityName: 'EntryAbility'
    }
  }

4.4 日历类提醒

this.targetReminderAgent = {
  reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR,
  dateTime: {
    // 指明提醒的目标时间
    year: 2024,
    month: 8,
    day: 12,
    hour: 15,
    minute: 30,
    second: 10
  },
  repeatMonths: [8], // 指明重复提醒的月份
  repeatDays: [12], // 指明重复提醒的日期
  wantAgent: {
    // 点击提醒通知后跳转的目标UIAbility信息
    pkgName: 'com.example.mybackgroundtask',
    abilityName: 'EntryAbility'
  },
  ringDuration: 5, // 指明响铃时长（单位：秒）
  snoozeTimes: 2, // 指明延迟提醒次数
  timeInterval: 5, // 执行延迟提醒间隔（单位：秒）

  title: 'this is title', // 指明提醒标题
  content: 'this is content', // 指明提醒内容
  expiredContent: 'this reminder has expired', // 指明提醒过期后需要显示的内容
  snoozeContent: 'remind later', // 指明延迟提醒时需要显示的内容
  notificationId: 1100, // 指明提醒使用的通知的ID号，相同ID号的提醒会覆盖
  slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // 指明提醒的Slot类型
}

4.5 闹钟类提醒

this.targetReminderAgent = {
  reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM,
  hour: 15, // 指明提醒的目标时刻
  minute: 50, // 指明提醒的目标分钟
  daysOfWeek: [1], // 指明每周哪几天需要重复提醒
  wantAgent: {
    // 点击提醒通知后跳转的目标UIAbility信息
    pkgName: 'com.example.mybackgroundtask',
    abilityName: 'EntryAbility'
  },
  actionButton: [// 设置弹出的提醒通知信息上显示的按钮类型和标题
    {
      title: 'close',
      type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
    },
    {
      title: 'snooze',
      type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
    },
  ],
  ringDuration: 5, // 指明响铃时长（单位：秒）
  snoozeTimes: 2, // 指明延迟提醒次数
  timeInterval: 5, // 执行延迟提醒间隔（单位：秒）
  title: 'this is title', // 指明提醒标题
  content: 'this is content', // 指明提醒内容
  expiredContent: 'this reminder has expired', // 指明提醒过期后需要显示的内容
  snoozeContent: 'remind later', // 指明延迟提醒时需要显示的内容
  notificationId: 99, // 指明提醒使用的通知的ID号，相同ID号的提醒会覆盖
  slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // 指明提醒的Slot类型
}

4.6 发送提醒

reminderAgentManager.publishReminder(this.targetReminderAgent)
  .then(() => {
    console.log('wuwuwu => 发布定时提醒成功 ^_^')
  })
  .catch((err: BusinessError) => {
    console.log('wuwuwu => 发布定时提醒失败 : ' + JSON.stringify(err))
  })