鸿蒙0基础学习【代理提醒(ArkTS)】后台任务开发

概述

功能介绍

应用退到后台或进程终止后，仍然有一些提醒用户的定时类任务，例如购物类应用抢购提醒等，为满足此类功能场景，系统提供了代理提醒（reminderAgentManager）的能力。当应用退至后台或进程终止后，系统会代理应用做相应的提醒。当前支持的提醒类型包括：倒计时、日历和闹钟。为了防止代理提醒被滥用于广告、营销类提醒，影响用户体验，代理提醒增加了管控机制，应用无法直接使用代理提醒

• 倒计时类：基于倒计时的提醒功能。
• 日历类：基于日历的提醒功能。
• 闹钟类：基于时钟的提醒功能。

约束与限制

• 个数限制：

1. 单个普通应用提醒数量不超过30个。
2. 从API version10开始，所有应用提醒数量总和不超过12000个。API version 9及之前的版本，提醒数量总和不超过2000个。

说明

当到达设置的提醒时间点时，通知中心会弹出相应提醒。若未点击提醒上的关闭/CLOSE按钮，则代理提醒是有效/未过期的；若点击了关闭/CLOSE按钮，则代理提醒过期。

当代理提醒是周期性提醒时，如设置每天提醒，无论是否点击关闭/CLOSE按钮，代理提醒都是有效的。

• 跳转限制：点击提醒通知后跳转的应用必须是申请代理提醒的本应用。

• 管控限制：管控后可通过日历Calendar Kit替代代理提醒，实现相应的提醒功能，具体请参考[开发指南]；或者参考如下邮件格式向华为侧申请代理提醒权限，申请通过后会开通权益，即可正常调用代理提醒接口，当前仅对纯工具类应用开放申请。

  邮件格式：

  通过[email protected]邮箱向华为侧申请，邮件会在10个工作日内回复（含权益开通结果），邮件提示申请通过后1天权益生效，请留意邮箱消息。邮件的规定格式如下：

  邮件主题：【代理提醒权限申请】

  邮件正文：

  申请权限名称：代理提醒

  企业名称：

  应用名称：***

  应用包名：com. .

  使用场景：提供申请理由/用途/尽可能附上图片，及使用代理提醒发通知/提醒的必要性。

  通知标题：***

  通知文本：***

  通知场景：***

  通知频率：***

接口说明

表1 主要接口

以下是代理提醒的相关接口，下表均以Promise形式为例，更多接口及使用方式请见[后台代理提醒]文档。

接口名	描述
publishReminder(reminderReq: ReminderRequest): Promise	发布一个定时提醒类通知。
cancelReminder(reminderId: number): Promise	取消一个指定的提醒类通知。
getValidReminders(): Promise	获取当前应用设置的所有有效的提醒。
cancelAllReminders(): Promise	取消当前应用设置的所有提醒。
addNotificationSlot(slot: NotificationSlot): Promise	注册一个提醒类需要使用的通知通道（NotificationSlot）。
removeNotificationSlot(slotType: notification.SlotType): Promise	删除指定的通知通道（NotificationSlot）。

开发步骤

1. 申请ohos.permission.PUBLISH_AGENT_REMINDER权限，配置方式请参阅[声明权限]。

2. [请求通知授权]。获得用户授权后，才能使用代理提醒功能。

3. 导入模块。

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

1. 定义目标提醒代理。开发者根据实际需要，选择定义如下类型的提醒。

   • 定义倒计时实例。

let targetReminderAgent: reminderAgentManager.ReminderRequestTimer = {
  reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,   // 提醒类型为倒计时类型
  triggerTimeInSeconds: 10,
  actionButton: [ // 设置弹出的提醒通知信息上显示的按钮类型和标题
    {
      title: 'close',
      type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
    }
  ],
  wantAgent: {     // 点击提醒通知后跳转的目标UIAbility信息
    pkgName: 'com.example.myapplication',
    abilityName: 'EntryAbility'
  },
  title: 'this is title', // 指明提醒标题
  content: 'this is content', // 指明提醒内容
  expiredContent: 'this reminder has expired', // 指明提醒过期后需要显示的内容
  notificationId: 100, // 指明提醒使用的通知的ID号，相同ID号的提醒会覆盖
  slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // 指明提醒的Slot类型
}

-   定义日历实例。

let targetReminderAgent: reminderAgentManager.ReminderRequestCalendar = {
  reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR, // 提醒类型为日历类型
  dateTime: {   // 指明提醒的目标时间
    year: 2023,
    month: 1,
    day: 1,
    hour: 11,
    minute: 14,
    second: 30
  },
  repeatMonths: [1], // 指明重复提醒的月份
  repeatDays: [1], // 指明重复提醒的日期
  actionButton: [ // 设置弹出的提醒通知信息上显示的按钮类型和标题
    {
      title: 'close',
      type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
    },
    {
      title: 'snooze',
      type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
    },
  ],
  wantAgent: { // 点击提醒通知后跳转的目标UIAbility信息
    pkgName: 'com.example.myapplication',
    abilityName: 'EntryAbility'
  },
  ringDuration: 5, // 指明响铃时长（单位：秒）
  snoozeTimes: 2, // 指明延迟提醒次数
  timeInterval: 5*60, // 执行延迟提醒间隔（单位：秒）
  title: 'this is title', // 指明提醒标题
  content: 'this is content', // 指明提醒内容
  expiredContent: 'this reminder has expired', // 指明提醒过期后需要显示的内容
  snoozeContent: 'remind later', // 指明延迟提醒时需要显示的内容
  notificationId: 100, // 指明提醒使用的通知的ID号，相同ID号的提醒会覆盖
  slotType: notificationManager.SlotType.SOCIAL_COMMUNICATION // 指明提醒的Slot类型
}

-   定义闹钟实例。

let targetReminderAgent: reminderAgentManager.ReminderRequestAlarm = {
  reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM, // 提醒类型为闹钟类型
  hour: 23, // 指明提醒的目标时刻
  minute: 9, // 指明提醒的目标分钟
  daysOfWeek: [2], // 指明每周哪几天需要重复提醒
  actionButton: [ // 设置弹出的提醒通知信息上显示的按钮类型和标题
    {
      title: 'close',
      type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE
    },
    {
      title: 'snooze',
      type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE
    },
  ],
  wantAgent: { // 点击提醒通知后跳转的目标UIAbility信息
    pkgName: 'com.example.myapplication',
    abilityName: 'EntryAbility'
  },
  ringDuration: 5, // 指明响铃时长（单位：秒）
  snoozeTimes: 2, // 指明延迟提醒次数
  timeInterval: 5*60, // 执行延迟提醒间隔（单位：秒）
  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类型
}

1. 发布相应的提醒代理。代理发布后，应用即可使用后台代理提醒功能。

 reminderAgentManager.publishReminder(targetReminderAgent).then((res: number) => {
   console.info('Succeeded in publishing reminder. ');
   let reminderId: number = res; // 发布的提醒ID
 }).catch((err: BusinessError) => {
   console.error(`Failed to publish reminder. Code: ${err.code}, message: ${err.message}`);
 })

1. 根据需要删除提醒任务。

 let reminderId: number = 1;
 // reminderId的值从发布提醒代理成功之后的回调中获得
 reminderAgentManager.cancelReminder(reminderId).then(() => {
   console.log('Succeeded in canceling reminder.');
 }).catch((err: BusinessError) => {
   console.error(`Failed to cancel reminder. Code: ${err.code}, message: ${err.message}`);
 });

更多内容：

在↓