github/electron
1
1
Fork 0
mirror of https://github.com/electron/electron.git synced 2026-02-19 03:14:51 -05:00
Code Issues Packages Projects Releases Wiki Activity

feat: improve Windows Toast actions support (#48132)

Browse Source 
* feat: improve Windows Toast actions support

* fix: ensure MSIX compatibility

* test: add bad clsid format test
This commit is contained in:
Shelley Vohr
2026-02-12 23:25:20 +01:00
committed by GitHub
parent a65cfed500
commit 74fd10450f
20 changed files with 1004 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/api/app.md
View File

@@ -1122,6 +1122,19 @@ Updates the current activity if its type matches `type`, merging the entries fro
Changes the [Application User Model ID][app-user-model-id] to `id`.
### `app.setToastActivatorCLSID(id)` _Windows_
* `id` string
Changes the [Toast Activator CLSID][toast-activator-clsid] to `id`. If one is not set via this method, it will be randomly generated for the app.
* The value must be a valid GUID/CLSID in one of the following forms:
* Canonical brace-wrapped: `{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}` (preferred)
* Canonical without braces: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` (braces will be added automatically)
* Hex digits are case-insensitive.
This method should be called early (before showing notifications) so the value is baked into the registration/shortcut. Supplying an empty string or an unparsable value throws and leaves the existing (or generated) CLSID unchanged. If this method is never called, a random CLSID is generated once per run and exposed via `app.toastActivatorCLSID`.
### `app.setActivationPolicy(policy)` _macOS_
* `policy` string - Can be 'regular', 'accessory', or 'prohibited'.
@@ -1704,8 +1717,13 @@ platforms) that allows you to perform actions on your app icon in the user's doc
A `boolean` property that returns `true` if the app is packaged, `false` otherwise. For many apps, this property can be used to distinguish development and production environments.
### `app.toastActivatorCLSID` _Windows_ _Readonly_
A `string` property that returns the app's [Toast Activator CLSID][toast-activator-clsid].
[tasks]:https://learn.microsoft.com/en-us/windows/win32/shell/taskbar-extensions#tasks
[app-user-model-id]: https://learn.microsoft.com/en-us/windows/win32/shell/appids
[toast-activator-clsid]: https://learn.microsoft.com/en-us/windows/win32/properties/props-system-appusermodel-toastactivatorclsid
[electron-forge]: https://www.electronforge.io/
[electron-packager]: https://github.com/electron/packager
[CFBundleURLTypes]: https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/TP40009249-102207-TPXREF115

154
docs/api/notification.md
View File

@@ -67,6 +67,22 @@ Emitted when the notification is shown to the user. Note that this event can be
multiple times as a notification can be shown multiple times through the
`show()` method.
```js
const { Notification, app } = require('electron')
app.whenReady().then(() => {
const n = new Notification({
title: 'Title!',
subtitle: 'Subtitle!',
body: 'Body!'
})
n.on('show', () => console.log('Notification shown!'))
n.show()
})
```
#### Event: 'click'
Returns:
@@ -75,6 +91,22 @@ Returns:
Emitted when the notification is clicked by the user.
```js
const { Notification, app } = require('electron')
app.whenReady().then(() => {
const n = new Notification({
title: 'Title!',
subtitle: 'Subtitle!',
body: 'Body!'
})
n.on('click', () => console.log('Notification clicked!'))
n.show()
})
```
#### Event: 'close'
Returns:
@@ -88,21 +120,85 @@ is closed.
On Windows, the `close` event can be emitted in one of three ways: programmatic dismissal with `notification.close()`, by the user closing the notification, or via system timeout. If a notification is in the Action Center after the initial `close` event is emitted, a call to `notification.close()` will remove the notification from the action center but the `close` event will not be emitted again.
#### Event: 'reply' _macOS_
```js
const { Notification, app } = require('electron')
app.whenReady().then(() => {
const n = new Notification({
title: 'Title!',
subtitle: 'Subtitle!',
body: 'Body!'
})
n.on('close', () => console.log('Notification closed!'))
n.show()
})
```
#### Event: 'reply' _macOS_ _Windows_
Returns:
* `event` Event
* `reply` string - The string the user entered into the inline reply field.
* `details` Event\<\>
* `reply` string - The string the user entered into the inline reply field.
* `reply` string _Deprecated_
Emitted when the user clicks the "Reply" button on a notification with `hasReply: true`.
#### Event: 'action' _macOS_
```js
const { Notification, app } = require('electron')
app.whenReady().then(() => {
const n = new Notification({
title: 'Send a Message',
body: 'Body Text',
hasReply: true,
replyPlaceholder: 'Message text...'
})
n.on('reply', (e, reply) => console.log(`User replied: ${reply}`))
n.on('click', () => console.log('Notification clicked'))
n.show()
})
```
#### Event: 'action' _macOS_ _Windows_
Returns:
* `event` Event
* `index` number - The index of the action that was activated.
* `details` Event\<\>
* `actionIndex` number - The index of the action that was activated.
* `selectionIndex` number _Windows_ - The index of the selected item, if one was chosen. -1 if none was chosen.
* `actionIndex` number _Deprecated_
* `selectionIndex` number _Windows_ _Deprecated_
```js
const { Notification, app } = require('electron')
app.whenReady().then(() => {
const items = ['One', 'Two', 'Three']
const n = new Notification({
title: 'Choose an Action!',
actions: [
{ type: 'button', text: 'Action 1' },
{ type: 'button', text: 'Action 2' },
{ type: 'selection', text: 'Apply', items }
]
})
n.on('click', () => console.log('Notification clicked'))
n.on('action', (e) => {
console.log(`User triggered action at index: ${e.actionIndex}`)
if (e.selectionIndex > -1) {
console.log(`User chose selection item '${items[e.selectionIndex]}'`)
}
})
n.show()
})
```
#### Event: 'failed' _Windows_
@@ -113,6 +209,22 @@ Returns:
Emitted when an error is encountered while creating and showing the native notification.
```js
const { Notification, app } = require('electron')
app.whenReady().then(() => {
const n = new Notification({
title: 'Bad Action'
})
n.on('failed', (e, err) => {
console.log('Notification failed: ', err)
})
n.show()
})
```
### Instance Methods
Objects created with the `new Notification()` constructor have the following instance methods:
@@ -126,12 +238,42 @@ 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.
```js
const { Notification, app } = require('electron')
app.whenReady().then(() => {
const n = new Notification({
title: 'Title!',
subtitle: 'Subtitle!',
body: 'Body!'
})
n.show()
})
```
#### `notification.close()`
Dismisses the notification.
On Windows, calling `notification.close()` while the notification is visible on screen will dismiss the notification and remove it from the Action Center. If `notification.close()` is called after the notification is no longer visible on screen, calling `notification.close()` will try remove it from the Action Center.
```js
const { Notification, app } = require('electron')
app.whenReady().then(() => {
const n = new Notification({
title: 'Title!',
subtitle: 'Subtitle!',
body: 'Body!'
})
n.show()
setTimeout(() => n.close(), 5000)
})
```
### Instance Properties
#### `notification.title`

37
docs/api/structures/notification-action.md
View File

@@ -1,13 +1,15 @@
# NotificationAction Object
* `type` string - The type of action, can be `button`.
* `type` string - The type of action, can be `button` or `selection`. `selection` is only supported on Windows.
* `text` string (optional) - The label for the given action.
* `items` string[] (optional) _Windows_ - The list of items for the `selection` action `type`.
## Platform / Action Support
| Action Type | Platform Support | Usage of `text` | Default `text` | Limitations |
|-------------|------------------|-----------------|----------------|-------------|
| `button` | macOS | Used as the label for the button | "Show" (or a localized string by system default if first of such `button`, otherwise empty) | Only the first one is used. If multiple are provided, those beyond the first will be listed as additional actions (displayed when mouse active over the action button). Any such action also is incompatible with `hasReply` and will be ignored if `hasReply` is `true`. |
| `button` | macOS, Windows | Used as the label for the button | "Show" on macOS (localized) if first `button`, otherwise empty; Windows uses provided `text` | macOS: Only the first one is used as primary; others shown as additional actions (hover). Incompatible with `hasReply` (beyond first ignored). |
| `selection` | Windows | Used as the label for the submit button for the selection menu | "Select" | Requires an `items` array property specifying option labels. Emits the `action` event with `(index, selectedIndex)` where `selectedIndex` is the chosen option (>= 0). Ignored on platforms that do not support selection actions. |
### Button support on macOS
@@ -18,3 +20,34 @@ following criteria.
* App has its `NSUserNotificationAlertStyle` set to `alert` in the `Info.plist`.
If either of these requirements are not met the button won't appear.
### Selection support on Windows
To add a selection (combo box) style action, include an action with `type: 'selection'`, a `text` label for the submit button, and an `items` array of strings:
```js
const { Notification, app } = require('electron')
app.whenReady().then(() => {
const items = ['One', 'Two', 'Three']
const n = new Notification({
title: 'Choose an option',
actions: [{
type: 'selection',
text: 'Apply',
items
}]
})
n.on('action', (e) => {
console.log(`User triggered action at index: ${e.actionIndex}`)
if (e.selectionIndex > 0) {
console.log(`User chose selection item '${items[e.selectionIndex]}'`)
}
})
n.show()
})
```
When the user activates the selection action, the notification's `action` event will be emitted with two parameters: `actionIndex` (the action's index in the `actions` array) and `selectedIndex` (the zero-based index of the chosen item, or `-1` if unavailable). On non-Windows platforms selection actions are ignored.