Ir para o conteúdo principal

Notificações

Each operating system has its own mechanism to display notifications to users. Electron's notification APIs are cross-platform, but are different for each process type.

If you want to use a renderer process API in the main process or vice-versa, consider using inter-process communication.

Usando​

Below are two examples showing how to display notifications for each process type.

Show notifications in the main process​

Main process notifications are displayed using Electron's Notification module. Notification objects created using this module do not appear unless their show() instance method is called.

Main Process
const { Notification } = require('electron')

const NOTIFICATION_TITLE = 'Basic Notification'
const NOTIFICATION_BODY = 'Notification from the Main process'

new Notification({
  title: NOTIFICATION_TITLE,
  body: NOTIFICATION_BODY
}).show()

Here's a full example that you can open with Electron Fiddle:

docs/fiddles/features/notifications/main (45.3.2)Open in Fiddle
const { app, BrowserWindow, Notification } = require('electron/main')

function createWindow () {
  const win = new BrowserWindow({
    width: 800,
    height: 600
  })

  win.loadFile('index.html')
}

const NOTIFICATION_TITLE = 'Basic Notification'
const NOTIFICATION_BODY = 'Notification from the Main process'

function showNotification () {
  new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()
}

app.whenReady().then(createWindow).then(showNotification)

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
  }
})

app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0) {
    createWindow()
  }
})

Show notifications in the renderer process​

Notifications can be displayed directly from the renderer process with the web Notifications API.

Renderer Process
const NOTIFICACAO_TITULO = 'Title'
const NOTIFICACAO_CORPO = 'Notification from the Renderer process. Click to log to console.'
const CLICK_MESSAGE = 'Notification clicked'

new Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY }).onclick = () => console.log(CLICK_MESSAGE)

Here's a full example that you can open with Electron Fiddle:

docs/fiddles/features/notifications/renderer (45.3.2)Open in Fiddle
const NOTIFICATION_TITLE = 'Title'
const NOTIFICATION_BODY = 'Notification from the Renderer process. Click to log to console.'
const CLICK_MESSAGE = 'Notification clicked!'

new window.Notification(NOTIFICATION_TITLE, { body: NOTIFICATION_BODY })
  .onclick = () => { document.getElementById('output').innerText = CLICK_MESSAGE }

Platform considerations​

Enquanto o código e a experiência do usuário em sistemas operacionais sejam semelhantes, há algumas diferenças.

Windows​

For notifications on Windows, your Electron app needs to have a Start Menu shortcut with an AppUserModelID and a corresponding ToastActivatorCLSID.

Electron attempts to automate the work around the AppUserModelID and ToastActivatorCLSID. When Electron is used together with Squirrel.Windows (e.g. if you're using electron-winstaller), shortcuts will automatically be set correctly.

In production, Electron will also detect that Squirrel was used and will automatically call app.setAppUserModelId() with the correct value. During development, you may have to call app.setAppUserModelId() yourself.

Notifications in development

To quickly bootstrap notifications during development, adding node_modules\electron\dist\electron.exe to your Start Menu also does the trick. Navegue até o arquivo no Explorer, clique com o botão direito e "Fixar em Iniciar". Then, call app.setAppUserModelId(process.execPath) in the main process to see notifications.

Use advanced notifications​

Windows allows for advanced notifications with custom templates, images, inputs, and action buttons.

To send advanced notifications from the main process on Windows, use the toastXml option of the Notification constructor. This property accepts an XML string conforming to the Microsoft Toast XML Schema and supersedes other notification options.

Main Process
const { Notification } = require('electron')

const xml = `
<toast>
  <visual>
    <binding template="ToastGeneric">
      <text>Notification Title</text>
      <text>Notification body text</text>
    </binding>
  </visual>
  <actions>
    <action content="Confirm" arguments="action=confirm" />
    <action content="Dismiss" arguments="action=dismiss" />
  </actions>
</toast>`

const notification = new Notification({ toastXml: xml })
notification.show()

Important considerations when using Toast XML on Windows:

  • AppUserModelID: You must call app.setAppUserModelId() before showing notifications. Windows uses this ID to associate toast notifications with your application in the notification center.
  • Image paths: When including local images in <image src="..." />, paths must be absolute and formatted as file:/// URLs (for example, using url.pathToFileURL(imagePath).toString()).
  • XML escaping: Dynamic strings placed inside XML elements or attributes must be XML-escaped (&amp;, &lt;, &gt;, &quot;, &apos;) to prevent XML parsing failures.
  • Error handling: If the XML string is malformed or invalid according to the Windows toast schema, the notification will not appear and the failed event will be emitted on the Notification instance.
  • Handling action buttons: Action buttons specify an arguments attribute. When clicked, Electron emits the action event with the action index. For deep-linking or custom protocol activation, specify activationType="protocol" on the <action> element.

Query notification state​

To detect whether or not you're allowed to send a notification, use the userland module windows-notification-state.

This module allows you to determine ahead of time whether or not Windows will silently throw the notification away.

macOS​

For notifications on macOS, your application will need to be code-signed in order for notification events to emit correctly. This requirement stems from the underlying UNNotification API provided by Apple. Unsigned binaries will emit a failed event when notification APIs are called.

Additionally, you should be aware of Apple's Human Interface guidelines regarding notifications.

Note que as notificações tem um limite de 256 bytes de tamanho e serão truncadas se você exceder esse limite.

Query notification state​

To detect whether or not you're allowed to send a notification, use the userland module macos-notification-state.

This module allows you to detect ahead of time whether or not the notification will be displayed.

Linux​

Notifications are sent using libnotify, which can show notifications on any desktop environment that follows Desktop Notifications Specification, including Cinnamon, Enlightenment, Unity, GNOME, and KDE.