docs: update notifications tutorial (#37602)

* docs: update notifications tutorial

* delete unused assets
This commit is contained in:
Erick Zhao 2023-03-21 18:40:43 -07:00 коммит произвёл GitHub
Родитель 5023b49713
Коммит 52481bc923
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
4 изменённых файлов: 107 добавлений и 92 удалений

Просмотреть файл

@ -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.

Двоичные данные
docs/images/notification-main.png

Двоичный файл не отображается.

До

Ширина:  |  Высота:  |  Размер: 21 KiB

Двоичные данные
docs/images/notification-renderer.png

Двоичный файл не отображается.

До

Ширина:  |  Высота:  |  Размер: 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:
![Notification in the Renderer process](../images/notification-renderer.png)
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
![Notification in the Main process](../images/notification-main.png)
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