docs: update notifications tutorial (#37602)
* docs: update notifications tutorial * delete unused assets
This commit is contained in:
Erick Zhao
GitHub
parent
5023b49713
commit
52481bc923
4 changed files with 107 additions and 92 deletions
|
|
@ -1,98 +1,108 @@
|
|||
# Notifications
|
||||
|
||||
## Overview
|
||||
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.
|
||||
|
||||
All three operating systems provide means for applications to send
|
||||
notifications to the user. The technique of showing notifications is different
|
||||
for the Main and Renderer processes.
|
||||
If you want to use a renderer process API in the main process or vice-versa, consider using
|
||||
[inter-process communication](./ipc.md).
|
||||
|
||||
For the Renderer process, Electron conveniently allows developers to send
|
||||
notifications with the [HTML5 Notification API](https://notifications.spec.whatwg.org/),
|
||||
using the currently running operating system's native notification APIs
|
||||
to display it.
|
||||
## Usage
|
||||
|
||||
To show notifications in the Main process, you need to use the
|
||||
[Notification](../api/notification.md) module.
|
||||
Below are two examples showing how to display notifications for each process type.
|
||||
|
||||
## Example
|
||||
### Show notifications in the main process
|
||||
|
||||
### Show notifications in the Renderer process
|
||||
Main process notifications are displayed using Electron's [Notification module](../api/notification.md).
|
||||
Notification objects created using this module do not appear unless their `show()` instance
|
||||
method is called.
|
||||
|
||||
Starting with a working application from the
|
||||
[Quick Start Guide](quick-start.md), add the following line to the
|
||||
`index.html` file before the closing `</body>` tag:
|
||||
```js title='Main Process'
|
||||
const { Notification } = require("electron");
|
||||
|
||||
```html
|
||||
<script src="renderer.js"></script>
|
||||
const NOTIFICATION_TITLE = "Basic Notification";
|
||||
const NOTIFICATION_BODY = "Notification from the Main process";
|
||||
|
||||
new Notification({
|
||||
title: NOTIFICATION_TITLE,
|
||||
body: NOTIFICATION_BODY,
|
||||
}).show();
|
||||
```
|
||||
|
||||
...and add the `renderer.js` file:
|
||||
|
||||
```javascript fiddle='docs/fiddles/features/notifications/renderer'
|
||||
const NOTIFICATION_TITLE = 'Title'
|
||||
const NOTIFICATION_BODY = '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)
|
||||
```
|
||||
|
||||
After launching the Electron application, you should see the notification:
|
||||
|
||||
|
||||
|
||||
Additionally, if you click on the notification, the DOM will update to show "Notification clicked!".
|
||||
|
||||
### Show notifications in the Main process
|
||||
|
||||
Starting with a working application from the
|
||||
[Quick Start Guide](quick-start.md), update the `main.js` file with the following lines:
|
||||
Here's a full example that you can open with Electron Fiddle:
|
||||
|
||||
```javascript fiddle='docs/fiddles/features/notifications/main'
|
||||
const { Notification } = require('electron')
|
||||
const { Notification } = require("electron");
|
||||
|
||||
const NOTIFICATION_TITLE = 'Basic Notification'
|
||||
const NOTIFICATION_BODY = 'Notification from the Main process'
|
||||
const NOTIFICATION_TITLE = "Basic Notification";
|
||||
const NOTIFICATION_BODY = "Notification from the Main process";
|
||||
|
||||
const showNotification = () => {
|
||||
new Notification({ title: NOTIFICATION_TITLE, body: NOTIFICATION_BODY }).show()
|
||||
}
|
||||
|
||||
app.whenReady().then(createWindow).then(showNotification)
|
||||
new Notification({
|
||||
title: NOTIFICATION_TITLE,
|
||||
body: NOTIFICATION_BODY,
|
||||
}).show();
|
||||
```
|
||||
|
||||
After launching the Electron application, you should see the system notification:
|
||||
### Show notifications in the renderer process
|
||||
|
||||
|
||||
Notifications can be displayed directly from the renderer process with the
|
||||
[web Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API/Using_the_Notifications_API).
|
||||
|
||||
## Additional information
|
||||
```js title='Renderer Process'
|
||||
const NOTIFICATION_TITLE = "Title";
|
||||
const NOTIFICATION_BODY =
|
||||
"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:
|
||||
|
||||
```javascript fiddle='docs/fiddles/features/notifications/renderer'
|
||||
const NOTIFICATION_TITLE = "Title";
|
||||
const NOTIFICATION_BODY =
|
||||
"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);
|
||||
```
|
||||
|
||||
## Platform considerations
|
||||
|
||||
While code and user experience across operating systems are similar, there
|
||||
are subtle differences.
|
||||
|
||||
### Windows
|
||||
|
||||
* On Windows 10, a shortcut to your app with an
|
||||
[Application User Model ID][app-user-model-id] must be installed to the
|
||||
Start Menu. This can be overkill during development, so adding
|
||||
`node_modules\electron\dist\electron.exe` to your Start Menu also does the
|
||||
trick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'.
|
||||
You will then need to add the line `app.setAppUserModelId(process.execPath)` to
|
||||
your main process to see notifications.
|
||||
For notifications on Windows, your Electron app needs to have a Start Menu shortcut with an
|
||||
[AppUserModelID][app-user-model-id] and a corresponding [ToastActivatorCLSID][toast-activator-clsid].
|
||||
|
||||
Electron attempts to automate the work around the Application User Model ID. When
|
||||
Electron is used together with the installation and update framework Squirrel,
|
||||
[shortcuts will automatically be set correctly][squirrel-events]. Furthermore,
|
||||
Electron will detect that Squirrel was used and will automatically call
|
||||
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][squirrel-events].
|
||||
|
||||
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()`][set-app-user-model-id] yourself.
|
||||
|
||||
#### Advanced Notifications
|
||||
:::info Notifications in development
|
||||
|
||||
Later versions of Windows allow for advanced notifications, with custom templates,
|
||||
images, and other flexible elements. To send those notifications (from either the
|
||||
main process or the renderer process), use the userland module
|
||||
[electron-windows-notifications](https://github.com/felixrieseberg/electron-windows-notifications),
|
||||
To quickly bootstrap notifications during development, adding
|
||||
`node_modules\electron\dist\electron.exe` to your Start Menu also does the
|
||||
trick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'.
|
||||
Then, call `app.setAppUserModelId(process.execPath)` in the main process to see notifications.
|
||||
|
||||
:::
|
||||
|
||||
#### Use advanced notifications
|
||||
|
||||
Windows also allow for advanced notifications with custom templates, images, and other flexible
|
||||
elements.
|
||||
|
||||
To send those notifications from the main process, you can use the userland module
|
||||
[`electron-windows-notifications`](https://github.com/felixrieseberg/electron-windows-notifications),
|
||||
which uses native Node addons to send `ToastNotification` and `TileNotification` objects.
|
||||
|
||||
While notifications including buttons work with `electron-windows-notifications`,
|
||||
|
|
@ -101,41 +111,41 @@ handling replies requires the use of
|
|||
which helps with registering the required COM components and calling your
|
||||
Electron app with the entered user data.
|
||||
|
||||
#### Quiet Hours / Presentation Mode
|
||||
#### Query notification state
|
||||
|
||||
To detect whether or not you're allowed to send a notification, use the
|
||||
userland module [electron-notification-state](https://github.com/felixrieseberg/electron-notification-state).
|
||||
userland module [`windows-notification-state`][windows-notification-state].
|
||||
|
||||
This allows you to determine ahead of time whether or not Windows will
|
||||
silently throw the notification away.
|
||||
This module allows you to determine ahead of time whether or not Windows will silently throw the
|
||||
notification away.
|
||||
|
||||
### macOS
|
||||
|
||||
Notifications are straight-forward on macOS, but you should be aware of
|
||||
Notifications are straightforward on macOS, but you should be aware of
|
||||
[Apple's Human Interface guidelines regarding notifications][apple-notification-guidelines].
|
||||
|
||||
Note that notifications are limited to 256 bytes in size and will be truncated
|
||||
if you exceed that limit.
|
||||
|
||||
[apple-notification-guidelines]: https://developer.apple.com/macos/human-interface-guidelines/system-capabilities/notifications/
|
||||
|
||||
#### Do not disturb / Session State
|
||||
#### Query notification state
|
||||
|
||||
To detect whether or not you're allowed to send a notification, use the userland module
|
||||
[electron-notification-state][electron-notification-state].
|
||||
[`macos-notification-state`][macos-notification-state].
|
||||
|
||||
This will allow you to detect ahead of time whether or not the notification will be displayed.
|
||||
|
||||
[electron-notification-state]: https://github.com/felixrieseberg/electron-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
|
||||
Notifications are sent using `libnotify`, which can show notifications on any
|
||||
desktop environment that follows [Desktop Notifications
|
||||
Specification][notification-spec], including Cinnamon, Enlightenment, Unity,
|
||||
GNOME, KDE.
|
||||
GNOME, and KDE.
|
||||
|
||||
[notification-spec]: https://developer-old.gnome.org/notification-spec/
|
||||
[app-user-model-id]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx
|
||||
[app-user-model-id]: https://learn.microsoft.com/en-us/windows/win32/shell/appids
|
||||
[set-app-user-model-id]: ../api/app.md#appsetappusermodelidid-windows
|
||||
[squirrel-events]: https://github.com/electron/windows-installer/blob/main/README.md#handling-squirrel-events
|
||||
[toast-activator-clsid]: https://learn.microsoft.com/en-us/windows/win32/properties/props-system-appusermodel-toastactivatorclsid
|
||||
[apple-notification-guidelines]: https://developer.apple.com/macos/human-interface-guidelines/system-capabilities/notifications/
|
||||
[windows-notification-state]: https://github.com/felixrieseberg/windows-notification-state
|
||||
[macos-notification-state]: https://github.com/felixrieseberg/macos-notification-state
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue