Defines the data structure of a notification request, which is used to describe all information of a notification, including notification content, identifier, display style, interaction behavior, and so on.
The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
NotificationRequest
Defines the data structure of a notification request, which is used to describe all information of a notification, including notification content, identifier, display style, interaction behavior, and so on.
System capability: SystemCapability.Notification.Notification
| Name | Type | Read Only | Optional | Description |
|---|---|---|---|---|
| content | NotificationContent | No | No | Notification display content, including the notification title and body. |
| id | number | No | Yes | Notification ID. The default value is 0. If a notification with the same ID exists, the notification is updated. If no notification with the same ID exists, a new notification is created. |
| updateOnly18+ | boolean | No | Yes | Whether to update notifications only. The default value is false. - true: If a notification with the same ID exists, the notification is updated. If no notification with the same ID exists, the update fails and no new notification is created. - false: If a notification with the same ID exists, the notification is updated. If no notification with the same ID exists, a new notification is created. |
| appMessageId12+ | string | No | Yes | Unique identifier field carried by a notification sent by an application. It is used for notification deduplication. If the same application publishes notifications carrying the same appMessageId through different slots such as local and cloud, the device displays only one message, and subsequent duplicate notifications received will be silently deduplicated without being displayed or alerted. The deduplication identifier is valid only within 24 hours after the notification is published, and becomes invalid after 24 hours or after the device restarts. The size does not exceed 202 bytes, and the excess part will be truncated. The value is empty by default. |
| notificationSlotType11+ | notificationManager.SlotType | No | Yes | Type of the notification slot. The default value is OTHER_TYPES. Different slot types have different notification reminder modes. |
| notificationFlags8+ | NotificationFlags | No | Yes | Notification flag settings. The value is empty by default. This parameter becomes writable since API version 23. Setting this parameter can limit the notification reminder modes. When the notification slot type is LIVE_VIEW, setting this parameter does not take effect. |
| priorityNotificationType23+ | notificationManager.PriorityNotificationType | No | Yes | Notification priority type. The default value is OTHER. Setting this parameter can pin the notification to the top and display it prominently in the notification center. The actual display effect depends on device capabilities and the notification center UI style. Model restriction: This API can be used only in the stage model. |
| isAlertOnce | boolean | No | Yes | Whether to send a notification only once when the notification is published or updated. The default value is false. - true: A notification is sent only when the notification is published for the first time. For subsequent update, the notification mode is changed to LEVEL_LOW. - false: A notification is sent based on the configured notification mode. |
| sound12+ | string | No | Yes | Resource path of the application notification customized ringtone. The value is empty by default. Two audio resource sources are supported: - Resource file: a preset audio file of the application. The resource file must be placed in the resources/rawfile directory, and the file name is passed in directly when used. - Sandbox file: an audio file downloaded from the network or generated by the user. It must be placed in the files directory or its subdirectories in the EL1 area of the sandbox file directory. The format passed in is uri::{fileUri}, where fileUri is the path obtained through getUriFromPath. For example, the application passes the downloaded audio resource demo.mp3 into the sandbox file directory /data/storage/el1/base/files/, and the path obtained through getUriFromPath is file://{bundleName}/data/storage/el1/base/files/demo.mp3. Publishing a notification with this path plays the audio resource downloaded by the application. Formats such as m4a, aac, mp3, ogg, wav, flac, and amr are supported. |
| badgeNumber9+ | number | No | Yes | Number of notifications displayed on the application icon. The number is displayed cumulatively. The default value is 0. When the value of badgeNumber is less than or equal to 0, this badge setting is ignored. When the cumulative badge number is greater than 99, the notification badge displays 99+. For example, if the application publishes three notifications and sets badgeNumber to 2, 0, and 3 in sequence, the application displays 2, 2, and 5 in sequence. |
| wantAgent | WantAgent | No | Yes | Behavior intent of an application, which is triggered when a notification is clicked. This parameter is left empty by default. |
| actionButtons | Array<NotificationActionButton> | No | Yes | Notification buttons. The value is empty by default. A notification can contain at most two buttons. Since API version 16, a notification on a wearable device can contain at most three buttons. |
| removalWantAgent9+ | WantAgent | No | Yes | Behavior intent of an application, which is triggered when a notification is removed. This parameter is left empty by default. Currently, redirection to UIAbility is not supported. Only common events can be published (that is, the actionType field of WantAgentInfo is set to 4). |
| tapDismissed | boolean | No | Yes | Whether the notification is automatically cleared when the notification carries wantAgent or actionButtons. This parameter is valid only when the notification carries wantAgent or actionButtons. The default value is true. - true: The current notification is automatically cleared after the notification or button is tapped. - false: The current notification is retained after the notification or button is tapped. |
| autoDeletedTime | number | No | Yes | Scheduled auto-delete time for the notification. You can set this parameter to automatically delete the notification after the specified time. Default value: 0. This parameter does not take effect if a value less than 0 or a past time is passed in. Data format: timestamp. Unit: millisecond. For example, to delete a notification after it has been retained for 3 seconds (3000 ms), the corresponding deletion time is: new Date().getTime() + 3000. |
| deliveryTime | number | No | Yes | Notification delivery time. This parameter is automatically generated by the system and does not require configuration. Data format: timestamp. Unit: millisecond. |
| label | string | No | Yes | Notification label. The label field functions similarly to an ID and can be used alone or combined with the ID to serve as the notification identifier. It is recommended to use the ID. If the label is not empty when a notification is published, the corresponding label must also be specified when the notification is updated or deleted. The size does not exceed 202 bytes, and the excess part will be truncated. The value is empty by default. |
| smallIcon | image.PixelMap | No | Yes | Icon on the left of the notification. The value is empty by default. It is automatically generated by the system and requires no developer configuration. The icon's total pixel data must not exceed 192 KB (measured using getPixelBytesNumber). If this limit is exceeded, the setting does not take effect. The recommended icon pixel dimensions are 128*128. The actual display effect depends on device capabilities and the notification center UI style. |
| largeIcon | image.PixelMap | No | Yes | Icon on the right of the notification. The value is empty by default. When content uses NotificationPictureContent, setting this parameter does not take effect. The icon's total pixel data must not exceed 192 KB (measured using getPixelBytesNumber). If this limit is exceeded, the setting does not take effect. The recommended icon pixel dimensions are 128*128. The actual display effect depends on device capabilities and the notification center UI styleThis field takes effect only after the permission to send custom notification tones is obtained from the Push Kit server.. |
| overlayIcon23+ | image.PixelMap | No | Yes | Overlay icon of the notification, which replaces the icon on the left of the notification. The value is empty by default. This API takes effect only when notificationSlotType is set to SOCIAL_COMMUNICATION. The icon's total pixel data must not exceed 192 KB (measured using getPixelBytesNumber). If this limit is exceeded, the setting does not take effect. The recommended icon pixel dimensions are 128*128. The actual display effect depends on device capabilities and the notification center UI style. |
| groupName8+ | string | No | Yes | Group to which the notification belongs. When different notifications have the same groupName, these notifications will be displayed as a group. The size does not exceed 202 bytes, and the excess part will be truncated. The value is empty by default. |
| template8+ | NotificationTemplate | No | Yes | Notification template. This parameter is left empty by default. |
| extraInfo | {[key: string]: any} | No | Yes | Extended parameters, used to provide custom services for applications. This parameter is left empty by default. The key value is assigned by the system. Manual modification does not take effect. The system automatically changes the value to the actual value during data transmission. - 'ohos.notificationManager.wantUri': uri field in the Want object, which is passed to the application when the user taps a notification. This field can be obtained via the getActiveNotifications API call. |
| slotType(deprecated) | notification.SlotType | No | Yes | Notification slot type. The default value is OTHER_TYPES. This attribute is supported since API version 7 and deprecated since API version 11. You are advised to use notificationSlotType instead. |
| hashCode | string | Yes | Yes | Unique ID of the notification. |
| creatorBundleName | string | Yes | Yes | Bundle name of the application that creates the notification. |
| creatorUid | number | Yes | Yes | UID of the application that creates the notification. |
| creatorPid | number | Yes | Yes | PID used for creating the notification. |
| creatorUserId8+ | number | Yes | Yes | ID of the user who creates the notification. |
| isOngoing | boolean | No | Yes | Not supported currently. |
| isUnremovable | boolean | No | Yes | Not supported currently. |
| color | number | No | Yes | Background color of the notification. Not supported currently. |
| colorEnabled | boolean | No | Yes | Whether the notification background color can be enabled. Not supported currently. |
| isStopwatch | boolean | No | Yes | Whether to display the stopwatch. Not supported currently. |
| isCountDown | boolean | No | Yes | Whether to display the countdown time. Not supported currently. |
| isFloatingIcon | boolean | No | Yes | Whether the notification is displayed as a floating icon in the status bar. Not supported currently. |
| distributedOption8+ | DistributedOptions | No | Yes | Options of the distributed notification. Not supported currently. |
| badgeIconStyle | number | No | Yes | Notification badge type. Not supported currently. |
| showDeliveryTime | boolean | No | Yes | Whether to display the time when the notification is delivered. Not supported currently. |
DistributedOptions8+
Describes the cross-device collaboration options. This is a reserved capability and is not yet supported.
System capability: SystemCapability.Notification.Notification
| Name | Type | Read Only | Optional | Description |
|---|---|---|---|---|
| isDistributed | boolean | No | Yes | Whether cross-device notifications are supported. The default value is true. - true: cross-device notifications are supported. - false: cross-device notifications are not supported. |
| supportDisplayDevices | Array<string> | No | Yes | List of the devices to which the notification can be synchronized. |
| supportOperateDevices | Array<string> | No | Yes | List of the devices on which the notification can be opened. |
NotificationParameters24+
Describes part of the wantAgent information about in NotificationRequest.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.Notification.Notification
| Name | Type | Read Only | Optional | Description |
|---|---|---|---|---|
| wantAction | string | No | Yes | action field passed in Want when wantAgent is created. For details, see action. |
| wantUri | string | No | Yes | uri field passed in Want when wantAgent is created. For details, see uri. |
| wantParameters | Record<string, Object> | No | Yes | parameters field passed in Want when wantAgent is created. For details, see parameters. |