X Tutup
Skip to content

Commit aebb56c

Browse files
bandantoniobandantonio
authored
docs: revised Notifications feature page (electron#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
1 parent e6f570d commit aebb56c

File tree

4 files changed

+93
-27
lines changed

4 files changed

+93
-27
lines changed

‎docs/images/message-notification-renderer.png‎

10.2 KB
Loading

‎docs/images/notification-main.png‎

21.2 KB
Loading

‎docs/images/notification-renderer.png‎

21.8 KB
Loading

‎docs/tutorial/notifications.md‎

Lines changed: 93 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,89 @@
11
# Notifications (Windows, Linux, macOS)
22

3-
All three operating systems provide means for applications to send notifications
4-
to the user. Electron conveniently allows developers to send notifications with
5-
the [HTML5 Notification API](https://notifications.spec.whatwg.org/), using
6-
the currently running operating system's native notification APIs to display it.
3+
## Overview
74

8-
**Note:** Since this is an HTML5 API it is only available in the renderer process. If
9-
you want to show Notifications in the main process please check out the
5+
All three operating systems provide means for applications to send
6+
notifications to the user. The technique of showing notifications is different
7+
for the Main and Renderer processes.
8+
9+
For the Renderer process, Electron conveniently allows developers to send
10+
notifications with the [HTML5 Notification API](https://notifications.spec.whatwg.org/),
11+
using the currently running operating system's native notification APIs
12+
to display it.
13+
14+
To show notifications in the Main process, you need to use the
1015
[Notification](../api/notification.md) module.
1116

12-
```javascript
17+
## Example
18+
19+
### Show notifications in the Renderer process
20+
21+
Assuming you have a working Electron application from the
22+
[Quick Start Guide](quick-start.md), add the following line to the
23+
`index.html` file before the closing `</body>` tag:
24+
25+
```html
26+
<script src="renderer.js"></script>
27+
```
28+
29+
and add the `renderer.js` file:
30+
31+
```js
1332
const myNotification = new Notification('Title', {
14-
body: 'Lorem Ipsum Dolor Sit Amet'
33+
body: 'Notification from the Renderer process'
1534
})
1635

1736
myNotification.onclick = () => {
1837
console.log('Notification clicked')
1938
}
2039
```
2140

41+
After launching the Electron application, you should see the notification:
42+
43+
![Notification in the Renderer process](../images/notification-renderer.png)
44+
45+
If you open the Console and then click the notification, you will see the
46+
message that was generated after triggering the `onclick` event:
47+
48+
![Onclick message for the notification](../images/message-notification-renderer.png)
49+
50+
### Show notifications in the Main process
51+
52+
Starting with a working application from the
53+
[Quick Start Guide](quick-start.md), update the `main.js` file with the following lines:
54+
55+
```js
56+
const { Notification } = require('electron')
57+
58+
function showNotification () {
59+
const notification = {
60+
title: 'Basic Notification',
61+
body: 'Notification from the Main process'
62+
}
63+
new Notification(notification).show()
64+
}
65+
66+
app.whenReady().then(createWindow).then(showNotification)
67+
```
68+
69+
After launching the Electron application, you should see the notification:
70+
71+
![Notification in the Main process](../images/notification-main.png)
72+
73+
## Additional information
74+
2275
While code and user experience across operating systems are similar, there
2376
are subtle differences.
2477

25-
## Windows
26-
* On Windows 10, a shortcut to your app with an [Application User
27-
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.
78+
### Windows
79+
80+
* On Windows 10, a shortcut to your app with an
81+
[Application User Model ID][app-user-model-id] must be installed to the
82+
Start Menu. This can be overkill during development, so adding
83+
`node_modules\electron\dist\electron.exe` to your Start Menu also does the
84+
trick. Navigate to the file in Explorer, right-click and 'Pin to Start Menu'.
85+
You will then need to add the line `app.setAppUserModelId(process.execPath)` to
86+
your main process to see notifications.
2887
* On Windows 8.1 and Windows 8, a shortcut to your app with an [Application User
2988
Model ID][app-user-model-id] must be installed to the Start screen. Note,
3089
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
44103
the Windows team asking developers to be reasonable. Attempting to send gigantic
45104
amounts of text to the API (thousands of characters) might result in instability.
46105

47-
### Advanced Notifications
106+
#### Advanced Notifications
48107

49108
Later versions of Windows allow for advanced notifications, with custom templates,
50109
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
53112
which uses native Node addons to send `ToastNotification` and `TileNotification` objects.
54113

55114
While notifications including buttons work with `electron-windows-notifications`,
56-
handling replies requires the use of [`electron-windows-interactive-notifications`](https://github.com/felixrieseberg/electron-windows-interactive-notifications), which
57-
helps with registering the required COM components and calling your Electron app with
58-
the entered user data.
115+
handling replies requires the use of
116+
[`electron-windows-interactive-notifications`](https://github.com/felixrieseberg/electron-windows-interactive-notifications),
117+
which helps with registering the required COM components and calling your
118+
Electron app with the entered user data.
59119

60-
### Quiet Hours / Presentation Mode
120+
#### Quiet Hours / Presentation Mode
61121

62-
To detect whether or not you're allowed to send a notification, use the userland module
63-
[electron-notification-state](https://github.com/felixrieseberg/electron-notification-state).
122+
To detect whether or not you're allowed to send a notification, use the
123+
userland module [electron-notification-state](https://github.com/felixrieseberg/electron-notification-state).
64124

65-
This allows you to determine ahead of time whether or not Windows will silently throw
66-
the notification away.
125+
This allows you to determine ahead of time whether or not Windows will
126+
silently throw the notification away.
67127

68-
## macOS
128+
### macOS
69129

70130
Notifications are straight-forward on macOS, but you should be aware of
71-
[Apple's Human Interface guidelines regarding notifications](https://developer.apple.com/macos/human-interface-guidelines/system-capabilities/notifications/).
131+
[Apple's Human Interface guidelines regarding notifications][apple-notification-guidelines].
72132

73133
Note that notifications are limited to 256 bytes in size and will be truncated
74134
if you exceed that limit.
75135

76-
### Advanced Notifications
136+
[apple-notification-guidelines]: https://developer.apple.com/macos/human-interface-guidelines/system-capabilities/notifications/
137+
138+
#### Advanced Notifications
77139

78140
Later versions of macOS allow for notifications with an input field, allowing the user
79141
to quickly reply to a notification. In order to send notifications with an input field,
80-
use the userland module [node-mac-notifier](https://github.com/CharlieHess/node-mac-notifier).
142+
use the userland module [node-mac-notifier][node-mac-notifier].
143+
144+
[node-mac-notifier]: https://github.com/CharlieHess/node-mac-notifier
81145

82-
### Do not disturb / Session State
146+
#### Do not disturb / Session State
83147

84148
To detect whether or not you're allowed to send a notification, use the userland module
85-
[electron-notification-state](https://github.com/felixrieseberg/electron-notification-state).
149+
[electron-notification-state][electron-notification-state].
86150

87151
This will allow you to detect ahead of time whether or not the notification will be displayed.
88152

89-
## Linux
153+
[electron-notification-state]: https://github.com/felixrieseberg/electron-notification-state
154+
155+
### Linux
90156

91157
Notifications are sent using `libnotify` which can show notifications on any
92158
desktop environment that follows [Desktop Notifications

0 commit comments

Comments
 (0)
X Tutup