harmony 鸿蒙@ohos.reminderAgentManager (后台代理提醒)

  • 2022-10-28
  • 浏览 (979)

@ohos.reminderAgentManager (后台代理提醒)

本模块提供后台代理提醒的能力，即当应用被冻结或应用退出时，计时和提醒的功能将被系统服务代理。在开发过程中，开发者可以调用本模块接口创建定时提醒，提醒类型支持倒计时、日历、闹钟三种。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import reminderAgentManager from'@ohos.reminderAgentManager';

reminderAgentManager.publishReminder

publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void

发布后台代理提醒。使用callback异步回调。

说明：

该接口需要申请通知弹窗权限Notification.requestEnableNotification后调用。

需要权限： ohos.permission.PUBLISH_AGENT_REMINDER

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明
reminderReq ReminderRequest 是 需要发布的代理提醒实例。
callback AsyncCallback<number> 是 回调函数，返回当前发布提醒的id。

错误码：

以下错误码的详细介绍请参见reminderAgentManager错误码。

错误码ID 错误信息
1700001 Notification is not enabled.
1700002 The number of reminders exceeds the limit.

示例：

import { BusinessError } from '@ohos.base';

let timer: reminderAgentManager.ReminderRequestTimer = {
  reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,
  triggerTimeInSeconds: 10
}

reminderAgentManager.publishReminder(timer, (err: BusinessError, reminderId: number) => {
  if (err) {
    console.log("callback err code:" + err.code + " message:" + err.message);
  } else {
    console.log("callback, reminderId = " + reminderId);
  }
});

reminderAgentManager.publishReminder

publishReminder(reminderReq: ReminderRequest): Promise<number>

发布后台代理提醒。使用promise异步回调。

说明：

该接口需要申请通知弹窗权限Notification.requestEnableNotification后调用。

需要权限： ohos.permission.PUBLISH_AGENT_REMINDER

系统能力： SystemCapability.Notification.ReminderAgent

参数： |参数名|类型|必填|说明| |——–|——–|——–|——–| |reminderReq|ReminderRequest|是|需要发布的代理提醒实例。|

返回值： |类型|说明| |——–|——–| |Promise<number>|Promise对象，返回提醒的id。|

错误码：

以下错误码的详细介绍请参见reminderAgentManager错误码。

错误码ID 错误信息
1700001 Notification is not enabled.
1700002 The number of reminders exceeds the limit.

示例：

import { BusinessError } from '@ohos.base';

let timer: reminderAgentManager.ReminderRequestTimer = {
  reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER,
  triggerTimeInSeconds: 10
}

reminderAgentManager.publishReminder(timer).then((reminderId: number) => {
  console.log("promise, reminderId = " + reminderId);
}).catch((err: BusinessError) => {
  console.log("promise err code:" + err.code + " message:" + err.message);
});

reminderAgentManager.cancelReminder

cancelReminder(reminderId: number, callback: AsyncCallback<void>): void

取消指定Id的代理提醒。使用callback异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明
reminderId number 是 需要取消的代理提醒的Id。
callback AsyncCallback<void> 是 回调函数，取消代理提醒成功，err为undefined，否则返回err信息。

错误码：

以下错误码的详细介绍请参见reminderAgentManager错误码。

错误码ID 错误信息
1700003 The reminder does not exist.
1700004 The bundle name does not exist.

示例：

import { BusinessError } from '@ohos.base';

let reminderId: number = 1;
reminderAgentManager.cancelReminder(reminderId, (err: BusinessError, data: void) => {
  if (err) {
    console.log("callback err code:" + err.code + " message:" + err.message);
  } else {
    console.log("cancelReminder callback");
  }
});

reminderAgentManager.cancelReminder

cancelReminder(reminderId: number): Promise<void>

取消指定Id的代理提醒。使用Promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明
reminderId number 是 需要取消的代理提醒的Id。

返回值：

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见reminderAgentManager错误码。

错误码ID 错误信息
1700003 The reminder does not exist.
1700004 The bundle name does not exist.

示例：

import { BusinessError } from '@ohos.base';

let reminderId: number = 1;
reminderAgentManager.cancelReminder(reminderId).then(() => {
  console.log("cancelReminder promise");
}).catch((err: BusinessError) => {
  console.log("promise err code:" + err.code + " message:" + err.message);
});

reminderAgentManager.getValidReminders

getValidReminders(callback: AsyncCallback>): void

获取当前应用设置的所有有效（未过期）的代理提醒。使用callback异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明
callback AsyncCallback<Array<ReminderRequest>> 是 回调函数，返回当前应用设置的所有有效的代理提醒。

错误码：

以下错误码的详细介绍请参见reminderAgentManager错误码。

错误码ID 错误信息
1700004 The bundle name does not exist.

示例：

import { BusinessError } from '@ohos.base';

reminderAgentManager.getValidReminders((err: BusinessError, reminders: Array<reminderAgentManager.ReminderRequest>) => {
  if (err) {
    console.log("callback err code:" + err.code + " message:" + err.message);
  } else {
    console.log("callback, getValidReminders length = " + reminders.length);
    for (let i = 0; i < reminders.length; i++) {
      console.log("getValidReminders = " + reminders[i]);
      console.log("getValidReminders, reminderType = " + reminders[i].reminderType);
      const actionButton = reminders[i].actionButton||[];
      for (let j = 0; j < actionButton.length; j++) {
        console.log("getValidReminders, actionButton.title = " + actionButton[j]?.title);
        console.log("getValidReminders, actionButton.type = " + actionButton[j]?.type);
      }
      console.log("getValidReminders, wantAgent.pkgName = " + reminders[i].wantAgent?.pkgName);
      console.log("getValidReminders, wantAgent.abilityName = " + reminders[i].wantAgent?.abilityName);
      console.log("getValidReminders, maxScreenWantAgent.pkgName = " + reminders[i].maxScreenWantAgent?.pkgName);
      console.log("getValidReminders, maxScreenWantAgent.abilityName = " + reminders[i].maxScreenWantAgent?.abilityName);
      console.log("getValidReminders, ringDuration = " + reminders[i].ringDuration);
      console.log("getValidReminders, snoozeTimes = " + reminders[i].snoozeTimes);
      console.log("getValidReminders, timeInterval = " + reminders[i].timeInterval);
      console.log("getValidReminders, title = " + reminders[i].title);
      console.log("getValidReminders, content = " + reminders[i].content);
      console.log("getValidReminders, expiredContent = " + reminders[i].expiredContent);
      console.log("getValidReminders, snoozeContent = " + reminders[i].snoozeContent);
      console.log("getValidReminders, notificationId = " + reminders[i].notificationId);
      console.log("getValidReminders, slotType = " + reminders[i].slotType);
    }
  }
});

reminderAgentManager.getValidReminders

getValidReminders(): Promise<Array<ReminderRequest>>

获取当前应用设置的所有有效（未过期）的代理提醒。使用promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

返回值：

类型 说明
Promise<Array<ReminderRequest>> Promise对象，返回当前应用设置的所有有效的代理提醒。

错误码：

以下错误码的详细介绍请参见reminderAgentManager错误码。

错误码ID 错误信息
1700004 The bundle name does not exist.

示例：

import { BusinessError } from '@ohos.base';

reminderAgentManager.getValidReminders().then((reminders: Array<reminderAgentManager.ReminderRequest>) => {
  console.log("promise, getValidReminders length = " + reminders.length);
  for (let i = 0; i < reminders.length; i++) {
    console.log("getValidReminders = " + reminders[i]);
    console.log("getValidReminders, reminderType = " + reminders[i].reminderType);
    const actionButton = reminders[i].actionButton||[];
    for (let j = 0; j < actionButton.length; j++) {
      console.log("getValidReminders, actionButton.title = " + actionButton[j]?.title);
      console.log("getValidReminders, actionButton.type = " + actionButton[j]?.type);
    }
    console.log("getValidReminders, wantAgent.pkgName = " + reminders[i].wantAgent?.pkgName);
    console.log("getValidReminders, wantAgent.abilityName = " + reminders[i].wantAgent?.abilityName);
    console.log("getValidReminders, maxScreenWantAgent.pkgName = " + reminders[i].maxScreenWantAgent?.pkgName);
    console.log("getValidReminders, maxScreenWantAgent.abilityName = " + reminders[i].maxScreenWantAgent?.abilityName);
    console.log("getValidReminders, ringDuration = " + reminders[i].ringDuration);
    console.log("getValidReminders, snoozeTimes = " + reminders[i].snoozeTimes);
    console.log("getValidReminders, timeInterval = " + reminders[i].timeInterval);
    console.log("getValidReminders, title = " + reminders[i].title);
    console.log("getValidReminders, content = " + reminders[i].content);
    console.log("getValidReminders, expiredContent = " + reminders[i].expiredContent);
    console.log("getValidReminders, snoozeContent = " + reminders[i].snoozeContent);
    console.log("getValidReminders, notificationId = " + reminders[i].notificationId);
    console.log("getValidReminders, slotType = " + reminders[i].slotType);
  }
}).catch((err: BusinessError) => {
  console.log("promise err code:" + err.code + " message:" + err.message);
});

reminderAgentManager.cancelAllReminders

cancelAllReminders(callback: AsyncCallback<void>): void

取消当前应用设置的所有代理提醒。使用callback异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明
callback AsyncCallback<void> 是 回调函数，取消代理提醒成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见reminderAgentManager错误码。

错误码ID 错误信息
1700004 The bundle name does not exist.

示例：

import { BusinessError } from '@ohos.base';

reminderAgentManager.cancelAllReminders((err: BusinessError, data: void) =>{
  if (err) {
    console.log("callback err code:" + err.code + " message:" + err.message);
  } else {
    console.log("cancelAllReminders callback")
  }
});

reminderAgentManager.cancelAllReminders

cancelAllReminders(): Promise<void>

取消当前应用设置的所有代理提醒。使用Promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

返回值：

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见reminderAgentManager错误码。

错误码ID 错误信息
1700004 The bundle name does not exist.

示例：

import { BusinessError } from '@ohos.base';

reminderAgentManager.cancelAllReminders().then(() => {
  console.log("cancelAllReminders promise")
}).catch((err: BusinessError) => {
  console.log("promise err code:" + err.code + " message:" + err.message);
});

reminderAgentManager.addNotificationSlot

addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void

添加NotificationSlot（通知槽）。使用callback异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明
slot NotificationSlot 是 notification.slot实例，仅支持设置其type属性。
callback AsyncCallback<void> 是 回调函数，添加NotificationSlot成功时，err为undefined，否则err为错误对象。

示例：

import notification from '@ohos.notificationManager'
import { BusinessError } from '@ohos.base';

let mySlot: notification.NotificationSlot = {
  type: notification.SlotType.SOCIAL_COMMUNICATION
}

reminderAgentManager.addNotificationSlot(mySlot, (err: BusinessError, data: void) => {
  if (err) {
    console.log("callback err code:" + err.code + " message:" + err.message);
  } else {
    console.log("addNotificationSlot callback");
  }
});

reminderAgentManager.addNotificationSlot

addNotificationSlot(slot: NotificationSlot): Promise<void>

添加NotificationSlot（通知槽）。使用promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明
slot NotificationSlot 是 notification.slot实例，仅支持设置其type属性。

返回值：

类型 说明
Promise<void> 无返回结果的Promise对象。

示例：

import notification from '@ohos.notificationManager'
import { BusinessError } from '@ohos.base';

let mySlot: notification.NotificationSlot = {
  type: notification.SlotType.SOCIAL_COMMUNICATION
}
reminderAgentManager.addNotificationSlot(mySlot).then(() => {
  console.log("addNotificationSlot promise");
}).catch((err: BusinessError) => {
  console.log("promise err code:" + err.code + " message:" + err.message);
});

reminderAgentManager.removeNotificationSlot

removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void

删除目标NotificationSlot（通知槽），使用callback异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明
slotType notification.SlotType 是 目标notification.slot的类型。
callback AsyncCallback<void> 是 回调函数，当删除成功时，err为undefined，否则为错误对象。

示例：

import notification from '@ohos.notificationManager'
import { BusinessError } from '@ohos.base';

reminderAgentManager.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION,
  (err: BusinessError, data: void) => {
  if (err) {
    console.log("callback err code:" + err.code + " message:" + err.message);
  } else {
    console.log("removeNotificationSlot callback");
  }
});

reminderAgentManager.removeNotificationSlot

removeNotificationSlot(slotType: notification.SlotType): Promise<void>

删除目标NotificationSlot（通知槽）。使用Promise异步回调。

系统能力： SystemCapability.Notification.ReminderAgent

参数：

参数名 类型 必填 说明
slotType notification.SlotType 是 目标notification.slot的类型。

返回值：

类型 说明
Promise<void> 无返回结果的Promise对象。

示例：

import notification from '@ohos.notificationManager'
import { BusinessError } from '@ohos.base';

reminderAgentManager.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION).then(() => {
  console.log("removeNotificationSlot promise");
}).catch((err: BusinessError) => {
  console.log("promise err code:" + err.code + " message:" + err.message);
});

ActionButtonType

按钮的类型。

系统能力：SystemCapability.Notification.ReminderAgent

名称 值 说明
ACTION_BUTTON_TYPE_CLOSE 0 表示关闭提醒的按钮。
ACTION_BUTTON_TYPE_SNOOZE 1 表示延迟提醒的按钮。
ACTION_BUTTON_TYPE_CUSTOM10+ 2 表示自定义的按钮。
系统接口: 系统接口，三方应用不支持调用。

ReminderType

提醒的类型。

系统能力：SystemCapability.Notification.ReminderAgent

名称 值 说明
REMINDER_TYPE_TIMER 0 表示提醒类型：倒计时。
REMINDER_TYPE_CALENDAR 1 表示提醒类型：日历。
REMINDER_TYPE_ALARM 2 表示提醒类型：闹钟。

ActionButton

弹出的提醒通知中按钮的类型和标题。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明
title string 是 按钮显示的标题。
type ActionButtonType 是 按钮的类型。
wantAgent10+ WantAgent 否 点击按钮跳转的ability信息。
系统接口: 系统接口，三方应用不支持调用。

WantAgent

跳转目标的ability信息。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明
pkgName string 是 指明跳转目标的包名。
abilityName string 是 指明跳转目标的ability名称。
uri10+ string 否 指明跳转目标的uri信息。
系统接口: 系统接口，三方应用不支持调用。

MaxScreenWantAgent

提醒到达时，全屏显示自动拉起目标的ability信息。该接口为预留接口，暂不支持使用。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明
pkgName string 是 指明提醒到达时自动拉起的目标包名（如果设备在使用中，则只弹出通知横幅框）。
abilityName string 是 指明提醒到达时自动拉起的目标ability名（如果设备在使用中，则只弹出通知横幅框）。

ReminderRequest

代理提醒对象，用于设置提醒类型、响铃时长等具体信息。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明
reminderType ReminderType 是 指明代理提醒类型。
actionButton ActionButton 否 弹出的提醒通知栏中显示的按钮。
-普通应用：最多支持两个按钮。
-系统应用：API9最多支持两个按钮，在API10开始最多支持三个按钮。
wantAgent WantAgent 否 点击通知后需要跳转的目标ability信息。
maxScreenWantAgent MaxScreenWantAgent 否 提醒到达时，全屏显示自动拉起目标的ability信息。如果设备正在使用中，则弹出一个通知框。
说明：该接口为预留接口，暂不支持使用。
ringDuration number 否 指明响铃时长（单位：秒），默认1秒。
snoozeTimes number 否 指明延迟提醒次数，默认0次。
timeInterval number 否 执行延迟提醒间隔（单位：秒），最少5分钟。
title string 否 指明提醒标题。
content string 否 指明提醒内容。
expiredContent string 否 指明提醒过期后需要显示的内容。
snoozeContent string 否 指明延迟提醒时需要显示的内容。
notificationId number 否 指明提醒使用的通知的id号，相同id号的提醒会覆盖。
slotType notification.SlotType 否 指明提醒的slot类型。
tapDismissed10+ boolean 否 通知是否自动清除，具体请参考NotificationRequest.tapDismissed。
autoDeletedTime10+ number 否 自动清除的时间，具体请参考NotificationRequest.autoDeletedTime。

ReminderRequestCalendar

ReminderRequestCalendar extends ReminderRequest

日历实例对象，用于设置提醒的时间。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明
dateTime LocalDateTime 是 指明提醒的目标时间。
repeatMonths Array<number> 否 指明重复提醒的月份。
repeatDays Array<number> 否 指明重复提醒的日期。

ReminderRequestAlarm

ReminderRequestAlarm extends ReminderRequest

闹钟实例对象，用于设置提醒的时间。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明
hour number 是 指明提醒的目标时刻。
minute number 是 指明提醒的目标分钟。
daysOfWeek Array<number> 否 指明每周哪几天需要重复提醒。范围为周一到周末，对应数字为1到7。

ReminderRequestTimer

ReminderRequestTimer extends ReminderRequest

倒计时实例对象，用于设置提醒的时间。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明
triggerTimeInSeconds number 是 指明倒计时的秒数。

LocalDateTime

用于日历类提醒设置时指定时间信息。

系统能力：SystemCapability.Notification.ReminderAgent

名称 类型 必填 说明
year number 是 年
month number 是 月，取值范围是[1, 12]。
day number 是 日，取值范围是[1, 31]。
hour number 是 时，取值范围是[0, 23]。
minute number 是 分，取值范围是[0, 59]。
second number 否 秒，取值范围是[0, 59]。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙接口

harmony 鸿蒙系统公共事件定义(待停用)

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙开发说明

harmony 鸿蒙企业设备管理概述（仅对系统应用开放）

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)

harmony 鸿蒙@ohos.distributedBundle (分布式包管理)

harmony 鸿蒙@ohos.bundle (Bundle模块)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/bfecf1f912e948d9a72f80476faa390a
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录