electron/docs/api/notification.md

128 lines
4.1 KiB
Markdown
Raw Normal View History

2017-05-20 11:25:26 +00:00
# Notification
> Create OS desktop notifications
Process: [Main](../glossary.md#main-process)
## Using in the renderer process
2017-05-30 09:06:51 +00:00
If you want to show Notifications from a renderer process you should use the [HTML5 Notification API](../tutorial/notifications.md)
2017-05-20 11:25:26 +00:00
## Class: Notification
> Create OS desktop notifications
Process: [Main](../glossary.md#main-process)
`Notification` is an
[EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter).
It creates a new `Notification` with native properties as set by the `options`.
2017-05-30 10:27:24 +00:00
### Static Methods
The `Notification` class has the following static methods:
2017-06-23 10:50:50 +00:00
#### `Notification.isSupported()`
2017-05-30 10:27:24 +00:00
Returns `Boolean` - Whether or not desktop notifications are supported on the current system
2017-05-20 11:25:26 +00:00
2017-05-20 11:25:56 +00:00
### `new Notification([options])` _Experimental_
2017-05-20 11:25:26 +00:00
* `options` Object
* `title` String - A title for the notification, which will be shown 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 - 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.
* `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.
* `replyPlaceholder` String (optional) _macOS_ - The placeholder to write in the inline reply input field.
* `sound` String (optional) _macOS_ - The name of the sound file to play when the notification is shown.
* `actions` [NotificationAction[]](structures/notification-action.md) (optional) _macOS_ - Actions to add to the notification. Please read the available actions and limitations in the `NotificationAction` documentation.
2017-05-20 11:25:26 +00:00
### Instance Events
Objects created with `new Notification` emit the following events:
**Note:** Some events are only available on specific operating systems and are
labeled as such.
2017-05-29 11:33:43 +00:00
#### Event: 'show'
2017-05-20 11:25:26 +00:00
Returns:
* `event` Event
2017-05-29 11:33:43 +00:00
Emitted when the notification is shown to the user, note this could be fired
multiple times as a notification can be shown multiple times through the
`show()` method.
2017-05-20 11:25:26 +00:00
2017-05-29 11:33:43 +00:00
#### Event: 'click'
2017-05-20 11:25:26 +00:00
Returns:
* `event` Event
2017-05-29 11:33:43 +00:00
Emitted when the notification is clicked by the user.
2017-05-20 11:25:26 +00:00
2017-05-29 11:33:43 +00:00
#### Event: 'close'
2017-05-20 11:25:26 +00:00
Returns:
* `event` Event
2017-05-29 11:33:43 +00:00
Emitted when the notification is closed by manual intervention from the user.
This event is not guaranteed to be emitted in all cases where the notification
2017-05-29 11:33:43 +00:00
is closed.
2017-05-20 11:25:26 +00:00
#### Event: 'reply' _macOS_
Returns:
* `event` Event
* `reply` String - The string the user entered into the inline reply field.
2017-05-20 11:25:26 +00:00
Emitted when the user clicks the "Reply" button on a notification with `hasReply: true`.
#### Event: 'action' _macOS_
Returns:
* `event` Event
* `index` Number - The index of the action that was activated.
2017-05-20 11:25:26 +00:00
### Instance Methods
Objects created with `new Notification` have the following instance methods:
#### `notification.show()`
Immediately shows the notification to the user, please note this means unlike the
HTML5 Notification implementation, simply instantiating a `new Notification` does
not immediately show it to the user, you need to call this method before the OS
will display it.
2017-08-21 20:53:50 +00:00
2017-10-27 19:17:30 +00:00
If the notification has been shown before, this method will dismiss the previously
shown notification and create a new one with identical properties.
#### `notification.close()`
2017-10-27 19:17:30 +00:00
Dismisses the notification.
2017-08-21 20:56:10 +00:00
### Playing Sounds
2017-08-21 20:53:50 +00:00
On macOS, you can specify the name of the sound you'd like to play when the
notification is shown. Any of the default sounds (under System Preferences >
Sound) can be used, in addition to custom sound files. Be sure that the sound
2017-08-21 20:56:10 +00:00
file is copied under the app bundle (e.g., `YourApp.app/Contents/Resources`),
or one of the following locations:
2017-08-21 20:53:50 +00:00
* `~/Library/Sounds`
* `/Library/Sounds`
* `/Network/Library/Sounds`
* `/System/Library/Sounds`
See the [`NSSound`](https://developer.apple.com/documentation/appkit/nssound) docs for more information.