# 11.3:后台代理提醒

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

# 11.3.1:限制与约束

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

# 11.3.2:reminderAgent API介绍

@ohos.reminderAgent 模块里提供了发布后台代理提醒和取消后台代理提醒的相关 API,部分 API 如下所示:

declare namespace reminderAgent {
  // 发送后台代理提醒
  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
  
}
1
2
3
4
5
6
7
8
9
10
11
12
13
  • 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:reminderAgent 使用步骤

  • 引入reminderAgent模块

    import reminderAgent from '@ohos.reminderAgent';
    
    1
  • 发布一个后台代理提醒

    private startTimer() {
      let timer = {
        reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER,
        triggerTimeInSeconds: 10
      }
      reminderAgent.publishReminder(timer, (error, reminderId) => {
        if(reminderId) {
          // 发送成功,如果需要取消该提醒,这要使用该reminderId
        }
      })
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
  • 取消一个后台代理提醒

    private cancelTimer() {
      reminderAgent.cancelReminder(this.reminderId, (error, data) => {
        if(!error) {
          // 取消成功
        }
      })
    }
    
    1
    2
    3
    4
    5
    6
    7
  • 取消所有后台代理提醒

    private cancelAllTimer() {
      reminderAgent.cancelAllReminders((error, data) => {
        if(!error) {
          // 取消成功
        }
      })
    }
    
    1
    2
    3
    4
    5
    6
    7

# 11.3.4:reminderAgent 完整样例

import reminderAgent from '@ohos.reminderAgent';

@Entry @Component struct ReminderAgentTest {

  private reminderId: number = 0;
  
  build() {
    Column({ space: 10 }) {
      Button('发起定时提醒')
        .onClick(() => {
          this.startTimer();
        })

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

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

  // 开启后台代理提醒
  private startTimer() {
    let timer = {
      reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER,// 定时器
      triggerTimeInSeconds: 5,                                     // 5秒后触发提醒
      title: "标题测试",                                            // 标题
      content: "标题内容测试",                                       // 内容
      notificationId: 10086                                        // 任务ID
    }
    reminderAgent.publishReminder(timer, (error, reminderId) => {  // 发布一个提醒
      if(reminderId) {
        // 发送成功
        this.reminderId = reminderId;
      }
    })
  }

  // 取消后台代理提醒
  private cancelTimer() {
    reminderAgent.cancelReminder(this.reminderId, (error, data) => {
      if(!error) {
        // 取消成功
      }
    })
  }

  private cancelAllTimer() {
    reminderAgent.cancelAllReminders((error, data) => {
      if(!error) {
        // 取消成功
      }
    })
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

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

11_3_4_1
(adsbygoogle = window.adsbygoogle || []).push({});
请作者喝杯咖啡

津公网安备 12011402001367号

津ICP备2020008934号-2