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
|
|
@ -4,9 +4,12 @@
|
|||
|
||||
Process: [Main](../glossary.md#main-process)
|
||||
|
||||
## Using in the renderer process
|
||||
:::info Renderer process notifications
|
||||
|
||||
If you want to show Notifications from a renderer process you should use the [HTML5 Notification API](../tutorial/notifications.md)
|
||||
If you want to show notifications from a renderer process you should use the
|
||||
[web Notifications API](../tutorial/notifications.md)
|
||||
|
||||
:::
|
||||
|
||||
## Class: Notification
|
||||
|
||||
|
|
@ -29,10 +32,10 @@ Returns `boolean` - Whether or not desktop notifications are supported on the cu
|
|||
### `new Notification([options])`
|
||||
|
||||
* `options` Object (optional)
|
||||
* `title` string (optional) - A title for the notification, which will be shown at the top of the notification window when it is shown.
|
||||
* `title` string (optional) - A title for the notification, which will be displayed at the top of the notification window when it is shown.
|
||||
* `subtitle` string (optional) _macOS_ - A subtitle for the notification, which will be displayed below the title.
|
||||
* `body` string (optional) - The body text of the notification, which will be displayed below the title or subtitle.
|
||||
* `silent` boolean (optional) - Whether or not to emit an OS notification noise when showing the notification.
|
||||
* `silent` boolean (optional) - Whether or not to suppress the OS notification noise when showing the notification.
|
||||
* `icon` (string | [NativeImage](native-image.md)) (optional) - An icon to use in the notification.
|
||||
* `hasReply` boolean (optional) _macOS_ - Whether or not to add an inline reply option to the notification.
|
||||
* `timeoutType` string (optional) _Linux_ _Windows_ - The timeout duration of the notification. Can be 'default' or 'never'.
|
||||
|
|
@ -47,8 +50,11 @@ Returns `boolean` - Whether or not desktop notifications are supported on the cu
|
|||
|
||||
Objects created with `new Notification` emit the following events:
|
||||
|
||||
**Note:** Some events are only available on specific operating systems and are
|
||||
labeled as such.
|
||||
:::info
|
||||
|
||||
Some events are only available on specific operating systems and are labeled as such.
|
||||
|
||||
:::
|
||||
|
||||
#### Event: 'show'
|
||||
|
||||
|
|
@ -56,7 +62,7 @@ Returns:
|
|||
|
||||
* `event` Event
|
||||
|
||||
Emitted when the notification is shown to the user, note this could be fired
|
||||
Emitted when the notification is shown to the user. Note that this event can be fired
|
||||
multiple times as a notification can be shown multiple times through the
|
||||
`show()` method.
|
||||
|
||||
|
|
@ -106,14 +112,13 @@ Emitted when an error is encountered while creating and showing the native notif
|
|||
|
||||
### Instance Methods
|
||||
|
||||
Objects created with `new Notification` have the following instance methods:
|
||||
Objects created with the `new Notification()` constructor have the following instance methods:
|
||||
|
||||
#### `notification.show()`
|
||||
|
||||
Immediately shows the notification to the user, please note this means unlike the
|
||||
HTML5 Notification implementation, instantiating a `new Notification` does
|
||||
not immediately show it to the user, you need to call this method before the OS
|
||||
will display it.
|
||||
Immediately shows the notification to the user. Unlike the web notification API,
|
||||
instantiating a `new Notification()` does not immediately show it to the user. Instead, you need to
|
||||
call this method before the OS will display it.
|
||||
|
||||
If the notification has been shown before, this method will dismiss the previously
|
||||
shown notification and create a new one with identical properties.
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 22 KiB |
|
|
@ -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…
Reference in a new issue