The system provides APIs for setting the notification badge, which is displayed in the upper right corner of the application icon on the home screen to notify the user of the count of unread notifications.
When a new notification arrives, the count on the badge is incremented by 1.
After a notification is read, the count on the badge is decremented by 1. If there is no unread notification, the badge is not displayed.
When the badge count is set to a value less than or equal to 0, the badge is cleared. When the value is greater than 99, the notification badge displays 99+.
You can use either of the following methods to increase the count on the badge:
When publishing a notification, pass the badgeNumber parameter in NotificationRequest. After the notification is received, the count on the badge is incremented.
Call the setBadgeNumber() API to set the count on the badge.
To decrease the count on the badge, call the setBadgeNumber() API.
| API | Description |
|---|---|
| setBadgeNumber(badgeNumber: number): Promise<void> | Sets the number count on the badge. |
Import the NotificationManager module.
import { notificationManager } from '@kit.NotificationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
const TAG: string = '[PublishOperation]';
const DOMAIN_NUMBER: number = 0xFF00; Increase the count on the badge.
When publishing a notification, you can carry the related information in the badgeNumber field of NotificationRequest. For details, see Publishing a Text Notification.
In this example, the setBadgeNumber API is called to add a badge. This API is called after a new notification is published.
let badgeNumber: number = 9;
notificationManager.setBadgeNumber(badgeNumber).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, `Succeeded in setting badge number.`);
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG,
`Failed to set badge number. Code is ${err.code}, message is ${err.message}`);
}); Decrease the count on the badge.
After a notification is read, the application needs to call the API to set the number of remaining unread notifications. The badge is then updated.
let badgeNumber: number = 8;
notificationManager.setBadgeNumber(badgeNumber).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, `Succeeded in setting badge number.`);
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG,
`Failed to set badge number. Code is ${err.code}, message is ${err.message}`);
}); setBadgeNumber is an asynchronous API. When setBadgeNumber is used to set badges consecutively, you should not set the value until the previous setting is complete, ensuring that the execution sequence meets the expectation.
Negative example
Independent API calling cannot guarantee a proper calling sequence during actual execution.
The sample code is as follows:
let badgeNumber: number = 10;
notificationManager.setBadgeNumber(badgeNumber).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, `setBadgeNumber 10 success.`);
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG,
`Failed to set badge number. Code is ${err.code}, message is ${err.message}`);
});
badgeNumber = 11;
notificationManager.setBadgeNumber(badgeNumber).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, `setBadgeNumber 11 success.`);
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG,
`Failed to set badge number. Code is ${err.code}, message is ${err.message}`);
}); Positive example
Dependencies existing between multiple API callings ensure that the next setting can be performed only after the previous setting is complete.
The sample code is as follows:
let badgeNumber: number = 10;
notificationManager.setBadgeNumber(badgeNumber).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, `setBadgeNumber 10 success.`);
badgeNumber = 11;
notificationManager.setBadgeNumber(badgeNumber).then(() => {
hilog.info(DOMAIN_NUMBER, TAG, `setBadgeNumber 11 success.`);
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG,
`Failed to set badge number. Code is ${err.code}, message is ${err.message}`);
});
}).catch((err: BusinessError) => {
hilog.error(DOMAIN_NUMBER, TAG,
`Failed to set badge number. Code is ${err.code}, message is ${err.message}`);
});