From 4cc2dd91db2d0fff2dc4898954a1cc90adbd4cab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BB=96=E5=BA=B7=E5=BA=B7?= Date: Mon, 17 Oct 2022 17:10:59 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8F=90=E9=86=92=E4=BB=A3=E7=90=86=E9=94=99?= =?UTF-8?q?=E8=AF=AF=E7=A0=81=E6=95=B4=E6=94=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 廖康康 --- .../reference/apis/js-apis-reminderAgent.md | 110 +++- .../apis/js-apis-reminderAgentManager.md | 609 ++++++++++++++++++ .../errcode-reminderAgentManager.md | 51 ++ ...ckground-agent-scheduled-reminder-guide.md | 41 +- 4 files changed, 771 insertions(+), 40 deletions(-) create mode 100644 zh-cn/application-dev/reference/apis/js-apis-reminderAgentManager.md create mode 100644 zh-cn/application-dev/reference/errorcodes/errcode-reminderAgentManager.md diff --git a/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md b/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md index 09b727f94f..ff6f931d33 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md +++ b/zh-cn/application-dev/reference/apis/js-apis-reminderAgent.md @@ -15,11 +15,14 @@ import reminderAgent from'@ohos.reminderAgent'; ``` -## reminderAgent.publishReminder +## reminderAgent.publishReminder(deprecated) publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void 发布一个后台代理提醒，使用callback方式实现异步调用，该方法需要申请通知弹窗[Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8)后才能调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.publishReminder](js-apis-reminderAgentManager.md#reminderagentmanagerpublishreminder9) +> +> 从 API version 7开始支持。 **需要权限**： ohos.permission.PUBLISH_AGENT_REMINDER @@ -44,11 +47,14 @@ publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number& ``` -## reminderAgent.publishReminder +## reminderAgent.publishReminder(deprecated) publishReminder(reminderReq: ReminderRequest): Promise<number> 发布一个后台代理提醒，使用Promise方式实现异步调用，该方法需要申请通知弹窗[Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8)后才能调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.publishReminder](js-apis-reminderAgentManager.md#reminderagentmanagerpublishreminder9-1) +> +> 从 API version 7开始支持。 **需要权限**： ohos.permission.PUBLISH_AGENT_REMINDER @@ -76,11 +82,14 @@ publishReminder(reminderReq: ReminderRequest): Promise<number> ``` -## reminderAgent.cancelReminder +## reminderAgent.cancelReminder(deprecated) cancelReminder(reminderId: number, callback: AsyncCallback<void>): void 取消指定id的提醒，使用callback方式实现异步调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.cancelReminder](js-apis-reminderAgentManager.md#reminderagentmanagercancelreminder9) +> +> 从 API version 7开始支持。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -100,11 +109,14 @@ reminderAgent.cancelReminder(1, (err, data) => { ``` -## reminderAgent.cancelReminder +## reminderAgent.cancelReminder(deprecated) cancelReminder(reminderId: number): Promise<void> 取消指定id的提醒，使用Promise方式实现异步调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.cancelReminder](js-apis-reminderAgentManager.md#reminderagentmanagercancelreminder9-1) +> +> 从 API version 7开始支持。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -129,11 +141,14 @@ reminderAgent.cancelReminder(1).then(() => { ``` -## reminderAgent.getValidReminders +## reminderAgent.getValidReminders(deprecated) getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void 获取当前应用已设置的所有有效（未过期）的提醒，使用callback方式实现异步调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.getValidReminders](js-apis-reminderAgentManager.md#reminderagentmanagergetvalidreminders9) +> +> 从 API version 7开始支持。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -173,11 +188,14 @@ reminderAgent.getValidReminders((err, reminders) => { ``` -## reminderAgent.getValidReminders +## reminderAgent.getValidReminders(deprecated) getValidReminders(): Promise<Array<ReminderRequest>> 获取当前应用已设置的所有有效（未过期）的提醒，使用Promise方式实现异步调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.getValidReminders](js-apis-reminderAgentManager.md#reminderagentmanagergetvalidreminders9-1) +> +> 从 API version 7开始支持。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -217,11 +235,14 @@ reminderAgent.getValidReminders().then((reminders) => { ``` -## reminderAgent.cancelAllReminders +## reminderAgent.cancelAllReminders(deprecated) cancelAllReminders(callback: AsyncCallback<void>): void 取消当前应用所有的提醒，使用callback方式实现异步调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.cancelAllReminders](js-apis-reminderAgentManager.md#reminderagentmanagercancelallreminders9) +> +> 从 API version 7开始支持。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -240,11 +261,14 @@ reminderAgent.cancelAllReminders((err, data) =>{ ``` -## reminderAgent.cancelAllReminders +## reminderAgent.cancelAllReminders(deprecated) cancelAllReminders(): Promise<void> 取消当前应用所有的提醒，使用Promise方式实现异步调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.cancelAllReminders](js-apis-reminderAgentManager.md#reminderagentmanagercancelallreminders9-1) +> +> 从 API version 7开始支持。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -263,11 +287,14 @@ reminderAgent.cancelAllReminders().then(() => { ``` -## reminderAgent.addNotificationSlot +## reminderAgent.addNotificationSlot(deprecated) addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void 添加一个NotificationSlot，使用callback方式实现异步调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.addNotificationSlot](js-apis-reminderAgentManager.md#reminderagentmanageraddnotificationslot9) +> +> 从 API version 7开始支持。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -292,11 +319,14 @@ reminderAgent.addNotificationSlot(mySlot, (err, data) => { ``` -## reminderAgent.addNotificationSlot +## reminderAgent.addNotificationSlot(deprecated) addNotificationSlot(slot: NotificationSlot): Promise<void> 添加一个NotificationSlot，使用Promise方式实现异步调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.addNotificationSlot](js-apis-reminderAgentManager.md#reminderagentmanageraddnotificationslot9-1) +> +> 从 API version 7开始支持。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -326,11 +356,14 @@ reminderAgent.addNotificationSlot(mySlot).then(() => { ``` -## reminderAgent.removeNotificationSlot +## reminderAgent.removeNotificationSlot(deprecated) removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void 删除目标NotificationSlot，使用callback方式实现异步调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#reminderagentmanagerremovenotificationslot9) +> +> 从 API version 7开始支持。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -352,11 +385,14 @@ reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION, ``` -## reminderAgent.removeNotificationSlot +## reminderAgent.removeNotificationSlot(deprecated) removeNotificationSlot(slotType: notification.SlotType): Promise<void> 删除目标NotificationSlot，使用Promise方式实现异步调用。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#reminderagentmanagerremovenotificationslot9-1) +> +> 从 API version 7开始支持。 **系统能力**： SystemCapability.Notification.ReminderAgent @@ -383,9 +419,12 @@ reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION). ``` -## ActionButtonType +## ActionButtonType(deprecated) 按钮的类型。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#actionbuttontype9) +> +> 从 API version 7开始支持。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent @@ -395,9 +434,12 @@ reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION). | ACTION_BUTTON_TYPE_SNOOZE | 1 | 表示延迟提醒的按钮。 | -## ReminderType +## ReminderType(deprecated) 提醒的类型。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#remindertype9) +> +> 从 API version 7开始支持。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent @@ -408,9 +450,12 @@ reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION). | REMINDER_TYPE_ALARM | 2 | 表示提醒类型：闹钟。 | -## ActionButton +## ActionButton(deprecated) 用于设置弹出的提醒通知信息上显示的按钮类型和标题。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#actionbutton9) +> +> 从 API version 7开始支持。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent @@ -420,9 +465,12 @@ reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION). | type | [ActionButtonType](#actionbuttontype) | 是 | 按钮的类型。 | -## WantAgent +## WantAgent(deprecated) 点击提醒通知后跳转的目标ability信息。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#wantagent9) +> +> 从 API version 7开始支持。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent @@ -432,9 +480,12 @@ reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION). | abilityName | string | 是 | 指明点击提醒通知栏后跳转的目标ability名称。 | -## MaxScreenWantAgent +## MaxScreenWantAgent(deprecated) 全屏显示提醒到达时自动拉起的目标ability信息，该接口预留。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#maxscreenwantagent9) +> +> 从 API version 7开始支持。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent @@ -444,9 +495,12 @@ reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION). | abilityName | string | 是 | 指明提醒到达时自动拉起的目标ability名（如果设备在使用中，则只弹出通知横幅框）。 | -## ReminderRequest +## ReminderRequest(deprecated) 提醒实例对象，用于设置提醒类型、响铃时长等具体信息。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#reminderrequest9) +> +> 从 API version 7开始支持。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent @@ -467,11 +521,14 @@ reminderAgent.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION). | slotType | [notification.SlotType](js-apis-notification.md#slottype) | 否 | 指明提醒的slot类型。 | -## ReminderRequestCalendar +## ReminderRequestCalendar(deprecated) ReminderRequestCalendar extends ReminderRequest 日历实例对象，用于设置提醒的时间。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#reminderrequestcalendar9) +> +> 从 API version 7开始支持。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent @@ -482,11 +539,14 @@ ReminderRequestCalendar extends ReminderRequest | repeatDays | Array<number> | 否 | 指明重复提醒的日期。 | -## ReminderRequestAlarm +## ReminderRequestAlarm(deprecated) ReminderRequestAlarm extends ReminderRequest 闹钟实例对象，用于设置提醒的时间。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#reminderrequestalarm9) +> +> 从 API version 7开始支持。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent @@ -497,11 +557,14 @@ ReminderRequestAlarm extends ReminderRequest | daysOfWeek | Array<number> | 否 | 指明每周哪几天需要重复提醒。 | -## ReminderRequestTimer +## ReminderRequestTimer(deprecated) ReminderRequestTimer extends ReminderRequest 倒计时实例对象，用于设置提醒的时间。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#reminderrequesttimer9) +> +> 从 API version 7开始支持。 **系统能力**：SystemCapability.Notification.ReminderAgent @@ -510,9 +573,12 @@ ReminderRequestTimer extends ReminderRequest | triggerTimeInSeconds | number | 是 | 指明倒计时的秒数。 | -## LocalDateTime +## LocalDateTime(deprecated) 用于日历类提醒设置时指定时间信息。 +> **说明：** 从API version 9开始废弃，建议使用[reminderAgentManager.removeNotificationSlot](js-apis-reminderAgentManager.md#localdatetime9) +> +> 从 API version 7开始支持。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent diff --git a/zh-cn/application-dev/reference/apis/js-apis-reminderAgentManager.md b/zh-cn/application-dev/reference/apis/js-apis-reminderAgentManager.md new file mode 100644 index 0000000000..59459eaf47 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-reminderAgentManager.md @@ -0,0 +1,609 @@ +# 后台代理提醒 + +本模块提供后台代理提醒的能力。 + +开发应用时，开发者可以调用后台提醒发布的接口创建定时提醒，包括倒计时、日历、闹钟三种提醒类型。使用后台代理提醒能力后，应用可以被冻结或退出，计时和弹出提醒的功能将被后台系统服务代理。 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + +``` +import reminderAgentManager from'@ohos.reminderAgentManager'; +``` + + +## reminderAgentManager.publishReminder9+ + +publishReminder(reminderReq: ReminderRequest, callback: AsyncCallback<number>): void + +发布一个后台代理提醒，使用callback方式实现异步调用，该方法需要申请通知弹窗[Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8)后才能调用。 + +**需要权限**： ohos.permission.PUBLISH_AGENT_REMINDER + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | reminderReq | [ReminderRequest](#reminderrequest) | 是 | 需要发布的提醒实例。 | + | callback | AsyncCallback<number> | 是 | 异步回调，返回当前发布的提醒的reminderId。 | + +**示例**： +```js +let timer = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, + triggerTimeInSeconds: 10 +} +try { + reminderAgentManager.publishReminder(timer, (err, reminderId) => { + if (err) { + console.log("callback err code:" + err.code + " message:" + err.message); + } else { + console.log("callback, reminderId = " + reminderId); + } + }); +} catch (error) { + console.log("publishReminder code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.publishReminder9+ + +publishReminder(reminderReq: ReminderRequest): Promise<number> + +发布一个后台代理提醒，使用Promise方式实现异步调用，该方法需要申请通知弹窗[Notification.requestEnableNotification](js-apis-notification.md#notificationrequestenablenotification8)后才能调用。 + +**需要权限**： ohos.permission.PUBLISH_AGENT_REMINDER + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**参数**： + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | reminderReq | [ReminderRequest](#reminderrequest) | 是 | 需要发布的提醒实例。 | + +**返回值**： + | 类型 | 说明 | + | -------- | -------- | + | Promise<number> | 返回提醒的reminderId。 | + +**示例**： +```js +let timer = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, + triggerTimeInSeconds: 10 +} +try { + reminderAgentManager.publishReminder(timer).then((reminderId) => { + console.log("promise, reminderId = " + reminderId); + }).catch(err => { + console.log("promise err code:" + err.code + " message:" + err.message); + }); +} catch (error) { + console.log("publishReminder code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.cancelReminder9+ + +cancelReminder(reminderId: number, callback: AsyncCallback<void>): void + +取消指定id的提醒，使用callback方式实现异步调用。 + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| reminderId | number | 是 | 目标reminder的id号。 | +| callback | AsyncCallback<void> | 是 | 异步回调。 | + +**示例**： + +```js +try { + reminderAgentManager.cancelReminder(1, (err, data) => { + if (err) { + console.log("callback err code:" + err.code + " message:" + err.message); + } else { + console.log("cancelReminder callback"); + } + }); +} catch (error) { + console.log("cancelReminder code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.cancelReminder9+ + +cancelReminder(reminderId: number): Promise<void> + +取消指定id的提醒，使用Promise方式实现异步调用。 + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| reminderId | number | 是 | 目标reminder的id号。 | + +**返回值**： + +| 类型 | 说明 | +| -------- | -------- | +| Promise<void> | Promise类型异步回调。 | + +**示例**： + +```js +try { + reminderAgentManager.cancelReminder(1).then(() => { + console.log("cancelReminder promise"); + }).catch(err => { + console.log("promise err code:" + err.code + " message:" + err.message); + }); +} catch (error) { + console.log("cancelReminder code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.getValidReminders9+ + +getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void + +获取当前应用已设置的所有有效（未过期）的提醒，使用callback方式实现异步调用。 + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<Array<[ReminderRequest](#reminderrequest)>> | 是 | 异步回调，返回当前应用已设置的所有有效（未过期）的提醒。 | + +**示例**： + +```js +try { + reminderAgentManager.getValidReminders((err, reminders) => { + 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); + for (let j = 0; j < reminders[i].actionButton.length; j++) { + console.log("getValidReminders, actionButton.title = " + reminders[i].actionButton[j].title); + console.log("getValidReminders, actionButton.type = " + reminders[i].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 (error) { + console.log("getValidReminders code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.getValidReminders9+ + +getValidReminders(): Promise<Array<ReminderRequest>> + +获取当前应用已设置的所有有效（未过期）的提醒，使用Promise方式实现异步调用。 + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**返回值**： + +| 类型 | 说明 | +| -------- | -------- | +| Promise<Array<[ReminderRequest](#reminderrequest)>> | 返回当前应用已设置的所有有效（未过期）的提醒。 | + +**示例**： + +```js +try { + reminderAgentManager.getValidReminders().then((reminders) => { + 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); + for (let j = 0; j < reminders[i].actionButton.length; j++) { + console.log("getValidReminders, actionButton.title = " + reminders[i].actionButton[j].title); + console.log("getValidReminders, actionButton.type = " + reminders[i].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 => { + console.log("promise err code:" + err.code + " message:" + err.message); + }); +} catch (error) { + console.log("getValidReminders code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.cancelAllReminders9+ + +cancelAllReminders(callback: AsyncCallback<void>): void + +取消当前应用所有的提醒，使用callback方式实现异步调用。 + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | 是 | 异步回调。 | + +**示例**： + +```js +try { + reminderAgentManager.cancelAllReminders((err, data) =>{ + if (err) { + console.log("callback err code:" + err.code + " message:" + err.message); + } else { + console.log("cancelAllReminders callback") + } + }) +} catch (error) { + console.log("cancelAllReminders code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.cancelAllReminders9+ + +cancelAllReminders(): Promise<void> + +取消当前应用所有的提醒，使用Promise方式实现异步调用。 + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**返回值**： + +| 类型 | 说明 | +| -------- | -------- | +| Promise<void> | Promise类型异步回调。 | + +**示例**： + +```js +try { + reminderAgentManager.cancelAllReminders().then(() => { + console.log("cancelAllReminders promise") + }).catch(err => { + console.log("promise err code:" + err.code + " message:" + err.message); + }); +} catch (error) { + console.log("cancelAllReminders code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.addNotificationSlot9+ + +addNotificationSlot(slot: NotificationSlot, callback: AsyncCallback<void>): void + +添加一个NotificationSlot，使用callback方式实现异步调用。 + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| slot | [NotificationSlot](js-apis-notification.md#notificationslot) | 是 | notification slot实例，仅支持设置其type属性。 | +| callback | AsyncCallback<void> | 是 | 异步回调。 | + +**示例**： + +```js +import notification from '@ohos.notification' + +let mySlot = { + type: notification.SlotType.SOCIAL_COMMUNICATION +} +try { + reminderAgentManager.addNotificationSlot(mySlot, (err, data) => { + if (err) { + console.log("callback err code:" + err.code + " message:" + err.message); + } else { + console.log("addNotificationSlot callback"); + } + }); +} catch (error) { + console.log("addNotificationSlot code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.addNotificationSlot9+ + +addNotificationSlot(slot: NotificationSlot): Promise<void> + +添加一个NotificationSlot，使用Promise方式实现异步调用。 + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| slot | [NotificationSlot](js-apis-notification.md#notificationslot) | 是 | notification slot实例，仅支持设置其type属性。 | + +**返回值**： + +| 类型 | 说明 | +| -------- | -------- | +| Promise<void> | Promise类型异步回调。 | + +**示例**： + +```js +import notification from '@ohos.notification' + +let mySlot = { + type: notification.SlotType.SOCIAL_COMMUNICATION +} +try { + reminderAgentManager.addNotificationSlot(mySlot).then(() => { + console.log("addNotificationSlot promise"); + }).catch(err => { + console.log("promise err code:" + err.code + " message:" + err.message); + }); +} catch (error) { + console.log("addNotificationSlot code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.removeNotificationSlot9+ + +removeNotificationSlot(slotType: notification.SlotType, callback: AsyncCallback<void>): void + +删除目标NotificationSlot，使用callback方式实现异步调用。 + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| slotType | [notification.SlotType](js-apis-notification.md#slottype) | 是 | 目标notification slot的类型。 | +| callback | AsyncCallback<void> | 是 | 异步回调。 | + +**示例**： + +```js +import notification from '@ohos.notification' + +try { + reminderAgentManager.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION, (err, data) => { + if (err) { + console.log("callback err code:" + err.code + " message:" + err.message); + } else { + console.log("removeNotificationSlot callback"); + } + }); +} catch (error) { + console.log("removeNotificationSlot code:" + error.code + " message:" + error.message); +}; +``` + + +## reminderAgentManager.removeNotificationSlot9+ + +removeNotificationSlot(slotType: notification.SlotType): Promise<void> + +删除目标NotificationSlot，使用Promise方式实现异步调用。 + +**系统能力**： SystemCapability.Notification.ReminderAgent + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| slotType | [notification.SlotType](js-apis-notification.md#slottype) | 是 | 目标notification slot的类型。 | + +**返回值**： + +| 类型 | 说明 | +| -------- | -------- | +| Promise<void> | Promise类型异步回调。 | + +**示例**： + +```js +import notification from '@ohos.notification' + +try { + reminderAgentManager.removeNotificationSlot(notification.SlotType.CONTENT_INFORMATION).then(() => { + console.log("removeNotificationSlot promise"); + }).catch(err => { + console.log("promise err code:" + err.code + " message:" + err.message); + }); +} catch (error) { + console.log("removeNotificationSlot code:" + error.code + " message:" + error.message); +}; +``` + +## ActionButtonType9+ + +按钮的类型。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| ACTION_BUTTON_TYPE_CLOSE | 0 | 表示关闭提醒的按钮。 | +| ACTION_BUTTON_TYPE_SNOOZE | 1 | 表示延迟提醒的按钮。 | + + +## ReminderType9+ + +提醒的类型。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent + +| 名称 | 默认值 | 说明 | +| -------- | -------- | -------- | +| REMINDER_TYPE_TIMER | 0 | 表示提醒类型：倒计时。 | +| REMINDER_TYPE_CALENDAR | 1 | 表示提醒类型：日历。 | +| REMINDER_TYPE_ALARM | 2 | 表示提醒类型：闹钟。 | + + +## ActionButton9+ + +用于设置弹出的提醒通知信息上显示的按钮类型和标题。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent + +| 名称 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| title | string | 是 | 按钮显示的标题。 | +| type | [ActionButtonType](#actionbuttontype) | 是 | 按钮的类型。 | + + +## WantAgent9+ + +点击提醒通知后跳转的目标ability信息。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent + +| 名称 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pkgName | string | 是 | 指明点击提醒通知栏后跳转的目标hap包名。 | +| abilityName | string | 是 | 指明点击提醒通知栏后跳转的目标ability名称。 | + + +## MaxScreenWantAgent9+ + +全屏显示提醒到达时自动拉起的目标ability信息，该接口预留。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent + +| 名称 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| pkgName | string | 是 | 指明提醒到达时自动拉起的目标hap包名（如果设备在使用中，则只弹出通知横幅框）。 | +| abilityName | string | 是 | 指明提醒到达时自动拉起的目标ability名（如果设备在使用中，则只弹出通知横幅框）。 | + + +## ReminderRequest9+ + +提醒实例对象，用于设置提醒类型、响铃时长等具体信息。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent + +| 名称 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| reminderType | ReminderType | 是 | 指明提醒类型。 | +| actionButton | [ActionButton?, ActionButton?] | 否 | 弹出的提醒通知栏中显示的按钮（参数可选，支持0/1/2个按钮）。 | +| wantAgent | WantAgent | 否 | 点击通知后需要跳转的目标ability信息。 | +| maxScreenWantAgent | MaxScreenWantAgent | 否 | 提醒到达时跳转的目标包。如果设备正在使用中，则弹出一个通知框。 | +| ringDuration | number | 否 | 指明响铃时长。 | +| snoozeTimes | number | 否 | 指明延迟提醒次数。 | +| timeInterval | number | 否 | 执行延迟提醒间隔。 | +| title | string | 否 | 指明提醒标题。 | +| content | string | 否 | 指明提醒内容。 | +| expiredContent | string | 否 | 指明提醒过期后需要显示的内容。 | +| snoozeContent | string | 否 | 指明延迟提醒时需要显示的内容。 | +| notificationId | number | 否 | 指明提醒使用的通知的id号，相同id号的提醒会覆盖。 | +| slotType | [notification.SlotType](js-apis-notification.md#slottype) | 否 | 指明提醒的slot类型。 | + + +## ReminderRequestCalendar9+ + +ReminderRequestCalendar extends ReminderRequest + +日历实例对象，用于设置提醒的时间。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent + +| 名称 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| dateTime | [LocalDateTime](#localdatetime) | 是 | 指明提醒的目标时间。 | +| repeatMonths | Array<number> | 否 | 指明重复提醒的月份。 | +| repeatDays | Array<number> | 否 | 指明重复提醒的日期。 | + + +## ReminderRequestAlarm9+ + +ReminderRequestAlarm extends ReminderRequest + +闹钟实例对象，用于设置提醒的时间。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent + +| 名称 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| hour | number | 是 | 指明提醒的目标时刻。 | +| minute | number | 是 | 指明提醒的目标分钟。 | +| daysOfWeek | Array<number> | 否 | 指明每周哪几天需要重复提醒。 | + + +## ReminderRequestTimer9+ + +ReminderRequestTimer extends ReminderRequest + +倒计时实例对象，用于设置提醒的时间。 + +**系统能力**：SystemCapability.Notification.ReminderAgent + +| 名称 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| triggerTimeInSeconds | number | 是 | 指明倒计时的秒数。 | + + +## LocalDateTime9+ + +用于日历类提醒设置时指定时间信息。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Notification.ReminderAgent + +| 名称 | 参数类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| year | number | 是 | 年 | +| month | number | 是 | 月 | +| day | number | 是 | 日 | +| hour | number | 是 | 时 | +| minute | number | 是 | 分 | +| second | number | 否 | 秒 | diff --git a/zh-cn/application-dev/reference/errorcodes/errcode-reminderAgentManager.md b/zh-cn/application-dev/reference/errorcodes/errcode-reminderAgentManager.md new file mode 100644 index 0000000000..9bc9cd5ce1 --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errcode-reminderAgentManager.md @@ -0,0 +1,51 @@ +# reminderAgentManager错误码 + +## 1700001 通知使能未开启 + +### 错误信息 +Notification does not enable. + +### 可能原因 +1. 未申请通知使能。 +2. 通知使能被关闭。 + +### 处理步骤 +1. 申请通知使能弹窗[Notification.requestEnableNotification](../apis/js-apis-notification.md#notificationrequestenablenotification8)。 +2. 检查通知使能是否被关闭。 + +## 1700002 提醒数量超出限制 + +### 错误信息 +The number of reminders exceeds the limit. + +### 可能原因 +1. 当前系统提醒超过2000个。 +2. 当前应用提醒超过30个。 + +### 处理步骤 +删除不必要的提醒 + +## 1700003 提醒不存在 + +### 错误信息 +The reminder does not exist. + +### 可能原因 +1. 提醒已过期。 +2. 提醒已被删除。 + +### 处理步骤 +1. 检查提醒是否有效。 +2. 检查提醒是否已被删除。 + +## 1700004 包名不存在 + +### 错误信息 +The package name does not exist. + +### 可能原因 +1. 包名不正确。 +2. 应用未安装。 + +### 处理步骤 +检查应用包名是否存在。 diff --git a/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md b/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md index ca596efaaa..7f86cafc3c 100644 --- a/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md +++ b/zh-cn/application-dev/task-management/background-agent-scheduled-reminder-guide.md @@ -7,11 +7,11 @@ ## 接口说明 -reminderAgent：封装了发布、取消提醒类通知的方法。 +reminderAgentManager：封装了发布、取消提醒类通知的方法。 具体后台提醒相关功能接口请见[后台代理提醒](../reference/apis/js-apis-reminderAgent.md)。 -**表1** reminderAgent主要接口 +**表1** reminderAgentManager主要接口 | 接口名 | 描述 | | -------- | -------- | @@ -34,17 +34,17 @@ reminderAgent：封装了发布、取消提醒类通知的方法。 倒计时实例定义： ```js - import reminderAgent from '@ohos.reminderAgent'; + import reminderAgentManager from '@ohos.reminderAgentManager'; import notification from '@ohos.notification'; export default { // eTS工程： - let timer : reminderAgent.ReminderRequestTimer = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_TIMER, + let timer : reminderAgentManager.ReminderRequestTimer = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_TIMER, triggerTimeInSeconds: 10, actionButton: [ { title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE } ], wantAgent: { @@ -68,8 +68,8 @@ reminderAgent：封装了发布、取消提醒类通知的方法。 ```js // eTS工程： - let calendar : reminderAgent.ReminderRequestCalendar = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_CALENDAR, + let calendar : reminderAgentManager.ReminderRequestCalendar = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_CALENDAR, dateTime: { year: 2050, month: 7, @@ -83,11 +83,11 @@ reminderAgent：封装了发布、取消提醒类通知的方法。 actionButton: [ { title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE }, { title: "snooze", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE }, ], wantAgent: { @@ -114,19 +114,19 @@ reminderAgent：封装了发布、取消提醒类通知的方法。 ```js // eTS工程： - let alarm : reminderAgent.ReminderRequestAlarm = { - reminderType: reminderAgent.ReminderType.REMINDER_TYPE_ALARM, + let alarm : reminderAgentManager.ReminderRequestAlarm = { + reminderType: reminderAgentManager.ReminderType.REMINDER_TYPE_ALARM, hour: 11, minute: 14, daysOfWeek: [0], actionButton: [ { title: "close", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_CLOSE }, { title: "snooze", - type: reminderAgent.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE + type: reminderAgentManager.ActionButtonType.ACTION_BUTTON_TYPE_SNOOZE }, ], wantAgent: { @@ -152,10 +152,15 @@ reminderAgent：封装了发布、取消提醒类通知的方法。 2. 发布倒计时提醒。 ```js startTimer() { - reminderAgent.publishReminder(this.timer, (err, reminderId) =>{ - this.printInfo(JSON.stringify(err)); - this.printInfo("reminderId:" + reminderId); - }); + try { + reminderAgent.publishReminder(this.timer).then(res => { + console.log("publishReminder promise reminderId:" + res); + }).catch(err => { + console.log("publishReminder err code:" + err.code + " message:" + err.message); + }) + } catch (error) { + console.log("publishReminder code:" + error.code + " message:" + error.message); + }; } ``` -- GitLab