Notification
创建操作系统桌面通知
进程：主进程
🌐 Process: Main
如果你想从渲染进程显示通知，你应该使用 Web 通知 API
类：Notification
🌐 Class: Notification
创建操作系统桌面通知
进程：主进程
🌐 Process: Main
Notification 是一个 事件触发器。
它会创建一个新的 Notification，其本地属性由 options 设置。
🌐 It creates a new Notification with native properties as set by the options.
Electron 内置的类不能在用户代码中被继承。 欲了解更多信息，请参见 常见问题。
静态方法
🌐 Static Methods
Notification 类具有以下静态方法：
🌐 The Notification class has the following static methods:
Notification.isSupported()
返回 boolean - 当前系统是否支持桌面通知
🌐 Returns boolean - Whether or not desktop notifications are supported on the current system
new Notification([options])
实例事件
🌐 Instance Events
使用 new Notification 创建的对象会触发以下事件：
🌐 Objects created with new Notification emit the following events:
某些事件仅在特定操作系统上可用并如此标记。
🌐 Some events are only available on specific operating systems and are labeled as such.
Event: 'show'
返回：
🌐 Returns:
event活动
当通知显示给用户时触发。请注意，此事件可能会被触发多次，因为通过 show() 方法通知可以显示多次。
🌐 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.
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:
event活动
当用户单击通知时发出。
🌐 Emitted when the notification is clicked by the user.
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:
event活动
当用户手动干预关闭通知时发出。
🌐 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 is closed.
在 Windows 中，close 事件可以通过三种方式触发：使用 notification.close() 进行程序化关闭、用户关闭通知，或者系统超时。如果通知在初始 close 事件触发后仍在操作中心中，调用 notification.close() 将会从操作中心移除该通知，但 close 事件不会再次触发。
🌐 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.
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:
- “details”事件<>
reply字符串 - 用户在内联回复字段中输入的字符串。
reply字符串 已弃用
当用户点击带有 hasReply: true 的通知上的“回复”按钮时触发。
🌐 Emitted when the user clicks the "Reply" button on a notification with hasReply: true.
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:
- “details”事件<>
actionIndex编号 - 被激活动作的索引。selectionIndex数字 Windows - 所选项目的索引，如果已选择某个项目。若未选择，则为 -1。
actionIndex编号 已弃用selectionIndex号码 Windows 已弃用
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
返回：
🌐 Returns:
event活动error字符串 - 在执行show()方法时遇到的错误。
创建和显示原生通知时遇到错误时发出。
🌐 Emitted when an error is encountered while creating and showing the native notification.
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
使用 new Notification() 构造函数创建的对象具有以下实例方法：
🌐 Objects created with the new Notification() constructor have the following instance methods:
notification.show()
立即向用户显示通知。与网页通知 API 不同，实例化 new Notification() 不会立即向用户显示通知。相反，你需要调用此方法，操作系统才会显示通知。
🌐 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.
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.
在 Windows 上，当通知在屏幕上可见时调用 notification.close() 会关闭该通知并将其从操作中心移除。如果在通知不再在屏幕上可见后调用 notification.close()，调用 notification.close() 将尝试将其从操作中心移除。
🌐 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.
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
string 属性，表示通知的标题。
🌐 A string property representing the title of the notification.
notification.subtitle
一个 string 属性，表示通知的副标题。
🌐 A string property representing the subtitle of the notification.
notification.body
一个 string 属性，表示通知的正文。
🌐 A string property representing the body of the notification.
notification.replyPlaceholder
一个 string 属性，表示通知的回复占位符。
🌐 A string property representing the reply placeholder of the notification.
notification.sound
string 属性，表示通知的声音。
🌐 A string property representing the sound of the notification.
notification.closeButtonText
string 属性表示通知的关闭按钮文本。
🌐 A string property representing the close button text of the notification.
notification.silent
boolean 属性，表示通知是否为静音。
🌐 A boolean property representing whether the notification is silent.
notification.hasReply
boolean 属性表示通知是否具有回复操作。
🌐 A boolean property representing whether the notification has a reply action.
notification.urgency Linux
string 属性表示通知的紧急程度。可以是“普通”、“紧急”或“低”。
🌐 A string property representing the urgency level of the notification. Can be 'normal', 'critical', or 'low'.
默认值为“低”－更多信息请参见 NotifyUrgency。
🌐 Default is 'low' - see NotifyUrgency for more information.
notification.timeoutType Linux Windows
string 属性，表示通知的超时时长类型。可以是 'default' 或 'never'。
🌐 A string property representing the type of timeout duration for the notification. Can be 'default' or 'never'.
如果将 timeoutType 设置为“从不”，通知将永不过期。它会一直显示，直到调用 API 或用户将其关闭。
🌐 If timeoutType is set to 'never', the notification never expires. It stays open until closed by the calling API or the user.
notification.actions
一个 NotificationAction[] 属性，表示通知的操作。
🌐 A NotificationAction[] property representing the actions of the notification.
notification.toastXml Windows
string 属性表示通知的自定义 Toast XML。
🌐 A string property representing the custom Toast XML of the notification.
播放声音
🌐 Playing Sounds
在 macOS 上，当显示通知时，你可以指定想要播放的声音名称。除了自定义声音文件外，任何默认声音（在“系统偏好设置 > 声音”下）都可以使用。确保该声音文件已复制到应用包中（例如 YourApp.app/Contents/Resources），或者放置在以下位置之一：
🌐 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
file is copied under the app bundle (e.g., YourApp.app/Contents/Resources),
or one of the following locations:
~/Library/Sounds/Library/Sounds/Network/Library/Sounds/System/Library/Sounds
有关更多信息，请参阅 NSSound 文档。
🌐 See the NSSound docs for more information.