Notification

Créer des notifications bureau spécifique à l'OS

Process: Main

[!Si vous souhaitez afficher les notifications à partir d’un processus de rendu, vous devrez utiliser l'API Web Notifications

[!NOTE] Sur MacOS, les notifications utilisent l'API UNNotification comme framework sous-jacent. Cette API nécessite qu'une application soit signée par code pour que les notifications apparaissent. Les binaires non signés émettront un événement de type failed lors d'appels aux notifications.

Classe : Notification

Créer des notifications bureau spécifique à l'OS

Process: Main

Notification est un EventEmitter.

Cela crée une nouvelle Notification avec les propriétés natives définies par les options.

[!WARNING] Electron's built-in classes cannot be subclassed in user code. For more information, see the FAQ.

Méthodes statiques

La classe Notification dispose des méthodes statiques suivantes :

`Notification.isSupported()`

Retourne boolean - Indique si le système actuel prend en charge les notification du bureau

`Notification.handleActivation(callback)` Windows

callback Function
- details ActivationArguments - Details about the notification activation.

Registers a callback to handle all notification activations. The callback is invoked whenever a notification is clicked, replied to, or has an action button pressed - regardless of whether the original Notification object is still in memory.

This method handles timing automatically:

If an activation already occurred before calling this method, the callback is invoked immediately with those details.
For all subsequent activations, the callback is invoked when they occur.

The callback remains registered until replaced by another call to handleActivation.

This provides a centralized way to handle notification interactions that works in all scenarios:

Cold start (app launched from notification click)
Notifications persisted in AC that have no in-memory representation after app re-start
Notification object was garbage collected
Notification object is still in memory (callback is invoked in addition to instance events)

`Notification.getHistory()` macOS

Returns Promise<Notification[]> - Resolves with an array of Notification objects representing all delivered notifications still present in Notification Center.

Each returned Notification is a live object connected to the corresponding delivered notification. Interaction events (click, reply, action, close) will fire on these objects when the user interacts with the notification in Notification Center. This is useful after an app restart to re-attach event handlers to notifications from a previous session.

The returned notifications have their id, groupId, title, subtitle, and body properties populated from information available in the Notification Center. Other properties (e.g., actions, silent, icon) are not available from delivered notifications and will have default values.

[!NOTE] Like all macOS notification APIs, this method requires the application to be code-signed. In unsigned development builds, notifications are not delivered to Notification Center and this method will resolve with an empty array.

[!NOTE] Unlike notifications created with new Notification(), notifications returned by getHistory() will remain visible in Notification Center when the object is garbage collected. Calling show() on a restored notification will remove the original from Notification Center and post a new one with the same properties.

const { Notification, app } = require('electron')

app.whenReady().then(async () => {
  // Restore notifications from a previous session
  const notifications = await Notification.getHistory()
  for (const n of notifications) {
    console.log(`Found delivered notification: ${n.id} - ${n.title}`)
    n.on('click', () => {
      console.log(`User clicked: ${n.id}`)
    })
    n.on('reply', (event) => {
      console.log(`User replied to ${n.id}: ${event.reply}`)
    })
  }
  // Keep references so events continue to fire
})

`Notification.remove(id)` macOS

id (string | string[]) - The notification identifier(s) to remove. These correspond to the id values set in the Notification constructor.

Removes one or more delivered notifications from Notification Center by their identifier(s).

const { Notification } = require('electron')

// Remove a single notification
Notification.remove('my-notification-id')

// Remove multiple notifications
Notification.remove(['msg-1', 'msg-2', 'msg-3'])

`Notification.removeAll()` macOS

Removes all of the app's delivered notifications from Notification Center.

const { Notification } = require('electron')

Notification.removeAll()

`Notification.removeGroup(groupId)` macOS

groupId string - The group identifier of the notifications to remove. This corresponds to the groupId value set in the Notification constructor.

Removes all delivered notifications with the given groupId from Notification Center.

const { Notification } = require('electron')

// Remove all notifications in the 'chat-thread-1' group
Notification.removeGroup('chat-thread-1')

`new Notification([options])`

options Object (facultatif)
- id string (optional) macOS Windows - A unique identifier for the notification. On macOS, maps to UNNotificationRequest's identifier property. On Windows, maps to the toast notification's Tag property. Defaults to a random UUID if not provided or if an empty string is passed. Use this identifier with Notification.remove() to remove specific delivered notifications, or with Notification.getHistory() to identify them.
- groupId string (optional) macOS Windows - A string identifier used to visually group notifications together in Notification Center / Action Center. On macOS, maps to UNNotificationContent's threadIdentifier property. On Windows, maps to the toast notification's Group property. Use this identifier with Notification.removeGroup() to remove all notifications in a group.
- groupTitle string (optional) Windows - A title for the notification group header. When both groupId and groupTitle are specified, Windows will display a header above the notification that groups related notifications together. Maps to the toast notification's header element.
- title string (optionelle) - Titre pour la notification, il sera affiché en haut de la fenêtre de notification lorsqu'elle sera affiché.
- subtitle string (facultatif) macOS -0 Sous-titre pour la notification, qui sera affiché sous le titre.
- body string (optionelle) - Texte du body de la notification, qui va être affichée en dessous le titre et le sous-titre.
- silent boolean (facultatif) - Supprime ou non le bruit de notification de l'OS lors de l'affichage de la notification.
- icon (string | NativeImage) (optional) - An icon to use in the notification. If a string is passed, it must be a valid path to a local icon file.
- hasReply boolean (optional) macOS Windows - Whether or not to add an inline reply option to the notification.
- timeoutType string (facultatif) Linux Windows - Durée du timeout de la notification. Peut être 'default' ou 'never'.
- replyPlaceholder string (optional) macOS Windows - The placeholder to write in the inline reply input field.
- sound string (facultatif) macOS - Le nom du fichier audio à jouer lorsque la notification est affichée.
- urgency string (optional) Linux Windows - The urgency level of the notification. Peut être 'normal', 'critical' ou 'low'.
- actions NotificationAction[] (optional) macOS Windows - Actions to add to the notification. Vous trouverez les actions et limitations disponibles dans la documentation de NotificationAction.
- closeButtonText string (facultatif) macOS - Titre personnalisé pour le bouton de fermeture d'une alerte. Si la chaîne est vide le texte localisé par défaut sera utilisé.
- toastXml string (facultatif) Windows - Description personnalisée de la notification remplaçant toutes les propriétés ci-dessus. Fournit une personnalisation complète du design et du comportement de la notification.

[!NOTE] On Windows, urgency type 'critical' sorts the notification higher in Action Center (above default priority notifications), but does not prevent auto-dismissal. To prevent auto-dismissal, you should also set timeoutType to 'never'.

Événements d’instance

Les objets créés avec new Notification émettent les événements suivants :

info

Certains événements ne sont disponibles que sur des systèmes d'exploitation spécifiques et sont étiquetés comme tels.

Événement : 'show'

Retourne :

event Event

Émis lorsque la notification est affichée. Notez que cet événement peut être déclenché plusieurs fois car une notification peut être affichée plusieurs fois via la méthode show().

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Title!',
    subtitle: 'Subtitle!',
    body: 'Body!'
  })

  n.on('show', () => console.log('Notification shown!'))

  n.show()
})

Événement : 'click'

Retourne :

event Event

Émis lorsque l'utilisateur clique sur la notification.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Title!',
    subtitle: 'Subtitle!',
    body: 'Body!'
  })

  n.on('click', () => console.log('Notification clicked!'))

  n.show()
})

Événement : 'close'

Retourne :

details Event<>
- reason Windows string (optional) - The reason the notification was closed. This can be 'userCanceled', 'applicationHidden', or 'timedOut'.

Émis lorsque la notification est fermée manuellement par l'utilisateur.

Cet événement ne garantit pas d'être émis dans tous les cas de fermeture de la notification.

On Windows, the close event can be emitted in one of three ways: programmatic dismissal with notification.close(), by the user closing the notification, or via system timeout. If a notification is in the Action Center after the initial close event is emitted, a call to notification.close() will remove the notification from the action center but the close event will not be emitted again.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Title!',
    subtitle: 'Subtitle!',
    body: 'Body!'
  })

  n.on('close', () => console.log('Notification closed!'))

  n.show()
})

Event: 'reply' macOS Windows

Retourne :

details Event<>
- reply string - La chaîne de caractères que l'utilisateur a écrite dans le champ de réponse.
reply string Deprecated

Émis lorsque l'utilisateur clique sur le bouton "Reply" sur une notification avec hasReply: true.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Send a Message',
    body: 'Body Text',
    hasReply: true,
    replyPlaceholder: 'Message text...'
  })

  n.on('reply', (e, reply) => console.log(`User replied: ${reply}`))
  n.on('click', () => console.log('Notification clicked'))

  n.show()
})

Event: 'action' macOS Windows

Retourne :

details Event<>
- actionIndex number - L'indice de l'action qui a été activée.
- selectionIndex number Windows - The index of the selected item, if one was chosen. -1 if none was chosen.
actionIndex number Deprecated
selectionIndex number Windows Deprecated

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const items = ['One', 'Two', 'Three']
  const n = new Notification({
    title: 'Choose an Action!',
    actions: [
      { type: 'button', text: 'Action 1' },
      { type: 'button', text: 'Action 2' },
      { type: 'selection', text: 'Apply', items }
    ]
  })

  n.on('click', () => console.log('Notification clicked'))
  n.on('action', (e) => {
    console.log(`User triggered action at index: ${e.actionIndex}`)
    if (e.selectionIndex > -1) {
      console.log(`User chose selection item '${items[e.selectionIndex]}'`)
    }
  })

  n.show()
})

Event: 'failed' macOS Windows

Retourne :

event Event
error string - L'erreur rencontrée lors de l'exécution de la méthode show().

Émis lorsqu'une erreur est rencontrée lors de la création et de l'affichage de la notification native.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Bad Action'
  })

  n.on('failed', (e, err) => {
    console.log('Notification failed: ', err)
  })

  n.show()
})

Méthodes d’instance

Les objets créés avec le constructeur new Notification() ont les méthodes d'instance suivantes :

`notification.show()`

Affiche immédiatement la notification à l'utilisateur. Contrairement à l'API de notification web, l'instanciation par new Notification() ne l'affiche pas immédiatement à l'utilisateur. Au lieu de cela, vous devez appeler la méthode show pour que l'OS l'affiche.

Si la notification a déjà été affichée auparavant, cette méthode rejettera la notification précédemment affichée et en créera une nouvelle avec des propriétés identiques.

On macOS, calling show() on a notification returned by Notification.getHistory() will remove the original notification from Notification Center and post a new one with the same properties.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Title!',
    subtitle: 'Subtitle!',
    body: 'Body!'
  })

  n.show()
})

`notification.close()`

Rejette la notification.

On Windows, calling notification.close() while the notification is visible on screen will dismiss the notification and remove it from the Action Center. If notification.close() is called after the notification is no longer visible on screen, calling notification.close() will try remove it from the Action Center.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Title!',
    subtitle: 'Subtitle!',
    body: 'Body!'
  })

  n.show()

  setTimeout(() => n.close(), 5000)
})

Propriétés d'instance

`notification.id` macOS Windows Readonly

A string property representing the unique identifier of the notification. This is set at construction time — either from the id option or as a generated UUID if none was provided.

`notification.groupId` macOS Windows Readonly

A string property representing the group identifier of the notification. Notifications with the same groupId will be visually grouped together in Notification Center (macOS) or Action Center (Windows).

`notification.groupTitle` Windows Readonly

A string property representing the title of the notification group header.

`notification.title`

Une propriété string représentant le titre de la notification.

`notification.subtitle`

Une propriété string représentant le sous-titre de la notification.

`notification.body`

Une propriété string représentant le corps de la notification.

`notification.replyPlaceholder`

Une propriété string représentant le placeholder de la réponse de la notification.

`notification.sound`

Une propriété string représentant le son de la notification.

`notification.closeButtonText`

Une propriété string représentant le texte du bouton de fermeture de la notification.

`notification.silent`

Une propriété boolean qui indique si la notification est silencieuse.

`notification.hasReply`

Propriété boolean indiquant si la notification a une action de réponse.

`notification.urgency` Linux

Propriété de type string représentant l'urgence de la notification. Peut être 'normal', 'critical' ou 'low'.

Default is 'low' - see NotifyUrgency for more information.

`notification.timeoutType` Linux Windows

Propriété string représentant le type de la durée du timeout pour la notification. Peut être 'default' ou 'never'.

Si timeoutType est défini à 'never', la notification n'expirera jamais. Elle restera ouverte jusqu'à sa fermeture par l'API ou par l'utilisateur.

`notification.actions`

A NotificationAction[] property representing the actions of the notification.

`notification.toastXml` Windows

Propriété de type string représentant le Toast XML de la notification.

Émettre des sons

Sur macOS, vous pouvez spécifier le nom du son que vous voulez jouer lors de l'affichage de la notification. N'importe quel son par défaut (dans préférences système > Son) peut être utilisé, en plus des fichiers audio personnalisés. Assurez-vous que le fichier audio soit copié dans l'"app bundle" (par exemple, VotreApp.app/Contents/Resources), ou l'un des emplacements suivants :

~/Library/Sounds
/Library/Sounds
/Network/Library/Sounds
/System/Library/Sounds

See the NSSound docs for more information.

Classe : Notification​

Méthodes statiques​

Notification.isSupported()​

Notification.handleActivation(callback) Windows​

Notification.getHistory() macOS​

Notification.remove(id) macOS​

Notification.removeAll() macOS​

Notification.removeGroup(groupId) macOS​

new Notification([options])​

Événements d’instance​

Événement : 'show'​

Événement : 'click'​

Événement : 'close'​

Event: 'reply' macOS Windows​

Event: 'action' macOS Windows​

Event: 'failed' macOS Windows​

Méthodes d’instance​

notification.show()​

notification.close()​

Propriétés d'instance​

notification.id macOS Windows Readonly​

notification.groupId macOS Windows Readonly​

notification.groupTitle Windows Readonly​

notification.title​

notification.subtitle​

notification.body​

notification.replyPlaceholder​

notification.sound​

notification.closeButtonText​

notification.silent​

notification.hasReply​

notification.urgency Linux​

notification.timeoutType Linux Windows​

notification.actions​

notification.toastXml Windows​

Émettre des sons​

Classe : Notification

Méthodes statiques

`Notification.isSupported()`

`Notification.handleActivation(callback)` Windows

`Notification.getHistory()` macOS

`Notification.remove(id)` macOS

`Notification.removeAll()` macOS

`Notification.removeGroup(groupId)` macOS

`new Notification([options])`

Événements d’instance

Événement : 'show'

Événement : 'click'

Événement : 'close'

Event: 'reply' macOS Windows

Event: 'action' macOS Windows

Event: 'failed' macOS Windows

Méthodes d’instance

`notification.show()`

`notification.close()`

Propriétés d'instance

`notification.id` macOS Windows Readonly

`notification.groupId` macOS Windows Readonly

`notification.groupTitle` Windows Readonly

`notification.title`

`notification.subtitle`

`notification.body`

`notification.replyPlaceholder`

`notification.sound`

`notification.closeButtonText`

`notification.silent`

`notification.hasReply`

`notification.urgency` Linux

`notification.timeoutType` Linux Windows

`notification.actions`

`notification.toastXml` Windows

Émettre des sons