docs: revised Notifications feature page (#25901)
* docs: revised Notifications feature page * docs: fixed mentions and updated content according to style guide in the notifications feature page * docs: fixed lint errors in the notifications feature page * docs: slightly improved consistency of steps in the notifications feature page * docs: fixed mentions in the notifications feature page
This commit is contained in:
Antonio
GitHub
parent
e6f570d191
commit
aebb56cb33
4 changed files with 93 additions and 27 deletions
BIN
docs/images/message-notification-renderer.png
Normal file
BIN
docs/images/message-notification-renderer.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 10 KiB |
BIN
docs/images/notification-main.png
Normal file
BIN
docs/images/notification-main.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
BIN
docs/images/notification-renderer.png
Normal file
BIN
docs/images/notification-renderer.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
|
|
@ -1,17 +1,36 @@
|
|||
# Notifications (Windows, Linux, macOS)
|
||||
|
||||
All three operating systems provide means for applications to send notifications
|
||||
to the user. 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.
|
||||
## Overview
|
||||
|
||||
**Note:** Since this is an HTML5 API it is only available in the renderer process. If
|
||||
you want to show Notifications in the main process please check out the
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
To show notifications in the Main process, you need to use the
|
||||
[Notification](../api/notification.md) module.
|
||||
|
||||
```javascript
|
||||
## Example
|
||||
|
||||
### Show notifications in the Renderer process
|
||||
|
||||
Assuming you have a working Electron application from the
|
||||
[Quick Start Guide](quick-start.md), add the following line to the
|
||||
`index.html` file before the closing `</body>` tag:
|
||||
|
||||
```html
|
||||
<script src="renderer.js"></script>
|
||||
```
|
||||
|
||||
and add the `renderer.js` file:
|
||||
|
||||
```js
|
||||
const myNotification = new Notification('Title', {
|
||||
body: 'Lorem Ipsum Dolor Sit Amet'
|
||||
body: 'Notification from the Renderer process'
|
||||
})
|
||||
|
||||
myNotification.onclick = () => {
|
||||
|
|
@ -19,12 +38,52 @@ myNotification.onclick = () => {
|
|||
}
|
||||
```
|
||||
|
||||
After launching the Electron application, you should see the notification:
|
||||
|
||||
|
||||
|
||||
If you open the Console and then click the notification, you will see the
|
||||
message that was generated after triggering the `onclick` event:
|
||||
|
||||
|
||||
|
||||
### 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:
|
||||
|
||||
```js
|
||||
const { Notification } = require('electron')
|
||||
|
||||
function showNotification () {
|
||||
const notification = {
|
||||
title: 'Basic Notification',
|
||||
body: 'Notification from the Main process'
|
||||
}
|
||||
new Notification(notification).show()
|
||||
}
|
||||
|
||||
app.whenReady().then(createWindow).then(showNotification)
|
||||
```
|
||||
|
||||
After launching the Electron application, you should see the notification:
|
||||
|
||||
|
||||
|
||||
## Additional information
|
||||
|
||||
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.
|
||||
### 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.
|
||||
* On Windows 8.1 and Windows 8, a shortcut to your app with an [Application User
|
||||
Model ID][app-user-model-id] must be installed to the Start screen. Note,
|
||||
however, that it does not need to be pinned to the Start screen.
|
||||
|
|
@ -44,7 +103,7 @@ to 200 characters. That said, that limitation has been removed in Windows 10, wi
|
|||
the Windows team asking developers to be reasonable. Attempting to send gigantic
|
||||
amounts of text to the API (thousands of characters) might result in instability.
|
||||
|
||||
### Advanced Notifications
|
||||
#### Advanced Notifications
|
||||
|
||||
Later versions of Windows allow for advanced notifications, with custom templates,
|
||||
images, and other flexible elements. To send those notifications (from either the
|
||||
|
|
@ -53,40 +112,47 @@ main process or the renderer process), use the userland module
|
|||
which uses native Node addons to send `ToastNotification` and `TileNotification` objects.
|
||||
|
||||
While notifications including buttons work with `electron-windows-notifications`,
|
||||
handling replies requires the use of [`electron-windows-interactive-notifications`](https://github.com/felixrieseberg/electron-windows-interactive-notifications), which
|
||||
helps with registering the required COM components and calling your Electron app with
|
||||
the entered user data.
|
||||
handling replies requires the use of
|
||||
[`electron-windows-interactive-notifications`](https://github.com/felixrieseberg/electron-windows-interactive-notifications),
|
||||
which helps with registering the required COM components and calling your
|
||||
Electron app with the entered user data.
|
||||
|
||||
### Quiet Hours / Presentation Mode
|
||||
#### Quiet Hours / Presentation Mode
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
This allows you to determine ahead of time whether or not Windows will silently throw
|
||||
the notification away.
|
||||
This allows you to determine ahead of time whether or not Windows will
|
||||
silently throw the notification away.
|
||||
|
||||
## macOS
|
||||
### macOS
|
||||
|
||||
Notifications are straight-forward on macOS, but you should be aware of
|
||||
[Apple's Human Interface guidelines regarding notifications](https://developer.apple.com/macos/human-interface-guidelines/system-capabilities/notifications/).
|
||||
[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.
|
||||
|
||||
### Advanced Notifications
|
||||
[apple-notification-guidelines]: https://developer.apple.com/macos/human-interface-guidelines/system-capabilities/notifications/
|
||||
|
||||
#### Advanced Notifications
|
||||
|
||||
Later versions of macOS allow for notifications with an input field, allowing the user
|
||||
to quickly reply to a notification. In order to send notifications with an input field,
|
||||
use the userland module [node-mac-notifier](https://github.com/CharlieHess/node-mac-notifier).
|
||||
use the userland module [node-mac-notifier][node-mac-notifier].
|
||||
|
||||
### Do not disturb / Session State
|
||||
[node-mac-notifier]: https://github.com/CharlieHess/node-mac-notifier
|
||||
|
||||
#### Do not disturb / Session 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).
|
||||
[electron-notification-state][electron-notification-state].
|
||||
|
||||
This will allow you to detect ahead of time whether or not the notification will be displayed.
|
||||
|
||||
## Linux
|
||||
[electron-notification-state]: https://github.com/felixrieseberg/electron-notification-state
|
||||
|
||||
### Linux
|
||||
|
||||
Notifications are sent using `libnotify` which can show notifications on any
|
||||
desktop environment that follows [Desktop Notifications
|
||||
|
|
|
|||
Loading…
Reference in a new issue