閱讀(884) 書簽贊(0) 我要糾錯

后臺代理提醒

2024-01-23 15:53 更新

本模塊提供后臺代理提醒的能力。

開發(fā)應用時，開發(fā)者可以調(diào)用后臺提醒發(fā)布的接口創(chuàng)建定時提醒，包括倒計時、日歷、鬧鐘三種提醒類型。使用后臺代理提醒能力后，應用可以被凍結(jié)或退出，計時和彈出提醒的功能將被后臺系統(tǒng)服務代理。

說明

本模塊首批接口從API version 9開始支持。后續(xù)版本的新增接口，采用上角標單獨標記接口的起始版本。

導入模塊


import reminderAgentManager from'@ohos.reminderAgentManager';

reminderAgentManager.publishReminder

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

發(fā)布一個后臺代理提醒，使用callback方式實現(xiàn)異步調(diào)用，該方法需要申請通知彈窗Notification.requestEnableNotification后才能調(diào)用。

需要權(quán)限： ohos.permission.PUBLISH_AGENT_REMINDER

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

參數(shù)：

參數(shù)名	類型	必填	說明
reminderReq	ReminderRequest	是	需要發(fā)布的提醒實例。
callback	AsyncCallback<number>	是	異步回調(diào)，返回當前發(fā)布的提醒的reminderId。

錯誤碼：

以下錯誤碼的詳細介紹請參見@ohos.reminderAgentManager（后臺代理提醒）錯誤碼。

錯誤碼ID	錯誤信息
1700001	Notification is not enabled.
1700002	The number of reminders exceeds the limit.

示例：


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.publishReminder

publishReminder(reminderReq: ReminderRequest): Promise<number>

發(fā)布一個后臺代理提醒，使用Promise方式實現(xiàn)異步調(diào)用，該方法需要申請通知彈窗Notification.requestEnableNotification后才能調(diào)用。

需要權(quán)限： ohos.permission.PUBLISH_AGENT_REMINDER

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

參數(shù)：

參數(shù)名	類型	必填	說明
reminderReq	ReminderRequest	是	需要發(fā)布的提醒實例。

返回值：

類型	說明
Promise<number>	返回提醒的reminderId。

錯誤碼：

以下錯誤碼的詳細介紹請參見@ohos.reminderAgentManager（后臺代理提醒）錯誤碼。

錯誤碼ID	錯誤信息
1700001	Notification is not enabled.
1700002	The number of reminders exceeds the limit.

示例：


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.cancelReminder

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

取消指定id的提醒，使用callback方式實現(xiàn)異步調(diào)用。

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

參數(shù)：

參數(shù)名	類型	必填	說明
reminderId	number	是	目標reminder的id號。
callback	AsyncCallback<void>	是	異步回調(diào)。

錯誤碼：

以下錯誤碼的詳細介紹請參見@ohos.reminderAgentManager（后臺代理提醒）錯誤碼。

錯誤碼ID	錯誤信息
1700003	The reminder does not exist.
1700004	The bundle name does not exist.

示例：


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.cancelReminder

cancelReminder(reminderId: number): Promise<void>

取消指定id的提醒，使用Promise方式實現(xiàn)異步調(diào)用。

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

參數(shù)：

參數(shù)名	類型	必填	說明
reminderId	number	是	目標reminder的id號。

返回值：

類型	說明
Promise<void>	Promise類型異步回調(diào)。

錯誤碼：

以下錯誤碼的詳細介紹請參見@ohos.reminderAgentManager（后臺代理提醒）錯誤碼。

錯誤碼ID	錯誤信息
1700003	The reminder does not exist.
1700004	The bundle name does not exist.

示例：


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.getValidReminders

getValidReminders(callback: AsyncCallback<Array<ReminderRequest>>): void

獲取當前應用已設置的所有有效（未過期）的提醒，使用callback方式實現(xiàn)異步調(diào)用。

說明

當?shù)竭_設置的提醒時間點時，通知中心會彈出相應提醒的通知卡片（通知欄消息）。若未點擊通知卡片上的關(guān)閉/CLOSE按鈕，則代理提醒是有效/未過期的；若點擊了關(guān)閉/CLOSE按鈕，則代理提醒過期。

當代理提醒類型是鬧鐘時，若設置每天提醒，無論是否點擊關(guān)閉/CLOSE按鈕，代理提醒都是有效的。

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

參數(shù)：

參數(shù)名	類型	必填	說明
callback	AsyncCallback<Array<ReminderRequest>>	是	異步回調(diào)，返回當前應用已設置的所有有效（未過期）的提醒。

錯誤碼：

以下錯誤碼的詳細介紹請參見@ohos.reminderAgentManager（后臺代理提醒）錯誤碼。

錯誤碼ID	錯誤信息
1700004	The bundle name does not exist.

示例：


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.getValidReminders

getValidReminders(): Promise<Array<ReminderRequest>>

獲取當前應用已設置的所有有效（未過期）的提醒，使用Promise方式實現(xiàn)異步調(diào)用。

說明

當代理提醒類型是鬧鐘時，若設置每天提醒，無論是否點擊關(guān)閉/CLOSE按鈕，代理提醒都是有效的。

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

返回值：

類型	說明
Promise<Array<ReminderRequest>>	返回當前應用已設置的所有有效（未過期）的提醒。

錯誤碼：

以下錯誤碼的詳細介紹請參見@ohos.reminderAgentManager（后臺代理提醒）錯誤碼。

錯誤碼ID	錯誤信息
1700004	The bundle name does not exist.

示例：


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.cancelAllReminders

cancelAllReminders(callback: AsyncCallback<void>): void

取消當前應用所有的提醒，使用callback方式實現(xiàn)異步調(diào)用。

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

參數(shù)：

參數(shù)名	類型	必填	說明
callback	AsyncCallback<void>	是	異步回調(diào)。

錯誤碼：

以下錯誤碼的詳細介紹請參見@ohos.reminderAgentManager（后臺代理提醒）錯誤碼。

錯誤碼ID	錯誤信息
1700004	The bundle name does not exist.

示例：


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.cancelAllReminders

cancelAllReminders(): Promise<void>

取消當前應用所有的提醒，使用Promise方式實現(xiàn)異步調(diào)用。

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

返回值：

類型	說明
Promise<void>	Promise類型異步回調(diào)。

錯誤碼：

以下錯誤碼的詳細介紹請參見@ohos.reminderAgentManager（后臺代理提醒）錯誤碼。

錯誤碼ID	錯誤信息
1700004	The bundle name does not exist.

示例：


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.addNotificationSlot

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

添加一個NotificationSlot，使用callback方式實現(xiàn)異步調(diào)用。

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

參數(shù)：

參數(shù)名	類型	必填	說明
slot	NotificationSlot	是	notification slot實例，僅支持設置其type屬性。
callback	AsyncCallback<void>	是	異步回調(diào)。

示例：


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.addNotificationSlot

addNotificationSlot(slot: NotificationSlot): Promise<void>

添加一個NotificationSlot，使用Promise方式實現(xiàn)異步調(diào)用。

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

參數(shù)：

參數(shù)名	類型	必填	說明
slot	NotificationSlot	是	notification slot實例，僅支持設置其type屬性。

返回值：

類型	說明
Promise<void>	Promise類型異步回調(diào)。

示例：


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.removeNotificationSlot

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

刪除目標NotificationSlot，使用callback方式實現(xiàn)異步調(diào)用。

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

參數(shù)：

參數(shù)名	類型	必填	說明
slotType	notification.SlotType	是	目標notification slot的類型。
callback	AsyncCallback<void>	是	異步回調(diào)。

示例：


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.removeNotificationSlot

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

刪除目標NotificationSlot，使用Promise方式實現(xiàn)異步調(diào)用。

系統(tǒng)能力： SystemCapability.Notification.ReminderAgent

參數(shù)：

參數(shù)名	類型	必填	說明
slotType	notification.SlotType	是	目標notification slot的類型。

返回值：

類型	說明
Promise<void>	Promise類型異步回調(diào)。

示例：


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);
};

ActionButtonType

按鈕的類型。

系統(tǒng)能力：以下各項對應的系統(tǒng)能力均為SystemCapability.Notification.ReminderAgent

名稱	值	說明
ACTION_BUTTON_TYPE_CLOSE	0	表示關(guān)閉提醒的按鈕。
ACTION_BUTTON_TYPE_SNOOZE	1	表示延遲提醒的按鈕。

ReminderType

提醒的類型。

系統(tǒng)能力：以下各項對應的系統(tǒng)能力均為SystemCapability.Notification.ReminderAgent

名稱	值	說明
REMINDER_TYPE_TIMER	0	表示提醒類型：倒計時。
REMINDER_TYPE_CALENDAR	1	表示提醒類型：日歷。
REMINDER_TYPE_ALARM	2	表示提醒類型：鬧鐘。

ActionButton

用于設置彈出的提醒通知信息上顯示的按鈕類型和標題。

系統(tǒng)能力：以下各項對應的系統(tǒng)能力均為SystemCapability.Notification.ReminderAgent

名稱	類型	必填	說明
title	string	是	按鈕顯示的標題。
type	ActionButtonType	是	按鈕的類型。

WantAgent

點擊提醒通知后跳轉(zhuǎn)的目標ability信息。

系統(tǒng)能力：以下各項對應的系統(tǒng)能力均為SystemCapability.Notification.ReminderAgent

名稱	類型	必填	說明
pkgName	string	是	指明點擊提醒通知欄后跳轉(zhuǎn)的目標hap包名。
abilityName	string	是	指明點擊提醒通知欄后跳轉(zhuǎn)的目標ability名稱。

MaxScreenWantAgent

全屏顯示提醒到達時自動拉起的目標ability信息，該接口預留。

系統(tǒng)能力：以下各項對應的系統(tǒng)能力均為SystemCapability.Notification.ReminderAgent

名稱	類型	必填	說明
pkgName	string	是	指明提醒到達時自動拉起的目標hap包名（如果設備在使用中，則只彈出通知橫幅框）。
abilityName	string	是	指明提醒到達時自動拉起的目標ability名（如果設備在使用中，則只彈出通知橫幅框）。

ReminderRequest

提醒實例對象，用于設置提醒類型、響鈴時長等具體信息。

系統(tǒng)能力：以下各項對應的系統(tǒng)能力均為SystemCapability.Notification.ReminderAgent

名稱	類型	必填	說明
reminderType	ReminderType	是	指明提醒類型。
actionButton	ActionButton	否	彈出的提醒通知欄中顯示的按鈕（參數(shù)可選，支持0/1/2個按鈕）。
wantAgent	WantAgent	否	點擊通知后需要跳轉(zhuǎn)的目標ability信息。
maxScreenWantAgent	MaxScreenWantAgent	否	提醒到達時跳轉(zhuǎn)的目標包。如果設備正在使用中，則彈出一個通知框。
ringDuration	number	否	指明響鈴時長（單位：秒），默認1秒。
snoozeTimes	number	否	指明延遲提醒次數(shù)，默認0次(不適用于倒計時提醒類型)。
timeInterval	number	否	執(zhí)行延遲提醒間隔（單位：秒），默認0秒(不適用于倒計時提醒類型)。
title	string	否	指明提醒標題。
content	string	否	指明提醒內(nèi)容。
expiredContent	string	否	指明提醒過期后需要顯示的內(nèi)容。
snoozeContent	string	否	指明延遲提醒時需要顯示的內(nèi)容。
notificationId	number	否	指明提醒使用的通知的id號，相同id號的提醒會覆蓋。
slotType	notification.SlotType	否	指明提醒的slot類型。

ReminderRequestCalendar

ReminderRequestCalendar extends ReminderRequest

日歷實例對象，用于設置提醒的時間。

系統(tǒng)能力：以下各項對應的系統(tǒng)能力均為SystemCapability.Notification.ReminderAgent

名稱	類型	必填	說明
dateTime	LocalDateTime	是	指明提醒的目標時間。
repeatMonths	Array<number>	否	指明重復提醒的月份。
repeatDays	Array<number>	否	指明重復提醒的日期。

ReminderRequestAlarm

ReminderRequestAlarm extends ReminderRequest

鬧鐘實例對象，用于設置提醒的時間。

系統(tǒng)能力：以下各項對應的系統(tǒng)能力均為SystemCapability.Notification.ReminderAgent

名稱	類型	必填	說明
hour	number	是	指明提醒的目標時刻。
minute	number	是	指明提醒的目標分鐘。
daysOfWeek	Array<number>	否	指明每周哪幾天需要重復提醒。范圍為周一到周末，對應數(shù)字為1到7。

ReminderRequestTimer

ReminderRequestTimer extends ReminderRequest

倒計時實例對象，用于設置提醒的時間。

系統(tǒng)能力：SystemCapability.Notification.ReminderAgent

名稱	類型	必填	說明
triggerTimeInSeconds	number	是	指明倒計時的秒數(shù)。

LocalDateTime

用于日歷類提醒設置時指定時間信息。

系統(tǒng)能力：以下各項對應的系統(tǒng)能力均為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]。

以上內(nèi)容是否對您有幫助：

← 資源管理

后臺任務管理 →

寫筆記

我要補充

后臺代理提醒

導入模塊

reminderAgentManager.publishReminder

reminderAgentManager.publishReminder

reminderAgentManager.cancelReminder

reminderAgentManager.cancelReminder

reminderAgentManager.getValidReminders

reminderAgentManager.getValidReminders

reminderAgentManager.cancelAllReminders

reminderAgentManager.cancelAllReminders

reminderAgentManager.addNotificationSlot

reminderAgentManager.addNotificationSlot

reminderAgentManager.removeNotificationSlot

reminderAgentManager.removeNotificationSlot

ActionButtonType

ReminderType

ActionButton

WantAgent

MaxScreenWantAgent

ReminderRequest

ReminderRequestCalendar

ReminderRequestAlarm

ReminderRequestTimer

LocalDateTime

推薦文章

推薦教程

推薦課程