Skip to main content

Notification

创建操作系统桌面通知

¥Create OS desktop notifications

进程：主进程

¥Process: Main

渲染器进程通知

如果你想显示来自渲染器进程的通知，你应该使用 网络通知 API

¥If you want to show notifications from a renderer process you should use the web Notifications API

类：Notification​

¥Class: Notification

创建操作系统桌面通知

¥Create OS desktop notifications

进程：主进程

¥Process: Main

Notification 是 EventEmitter。

¥Notification is an EventEmitter.

它创建一个新的 Notification，其原生属性由 options 设置。

¥It creates a new Notification with native properties as set by the options.

静态方法​

¥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])​

  • options 对象（可选）

    ¥options Object (optional)

    • title 字符串（可选） - 通知的标题，显示时将显示在通知窗口的顶部。

      ¥title string (optional) - A title for the notification, which will be displayed at the top of the notification window when it is shown.

    • subtitle 字符串（可选）macOS - 通知的副标题，将显示在标题下方。

      ¥subtitle string (optional) macOS - A subtitle for the notification, which will be displayed below the title.

    • body 字符串（可选） - 通知的正文，将显示在标题或副标题下方。

      ¥body string (optional) - The body text of the notification, which will be displayed below the title or subtitle.

    • silent 布尔值（可选） - 显示通知时是否抑制操作系统通知噪音。

      ¥silent boolean (optional) - Whether or not to suppress the OS notification noise when showing the notification.

    • icon（字符串 | NativeImage）（可选） - 在通知中使用的图标。如果传递了字符串，则它必须是本地图标文件的有效路径。

      ¥icon (string | NativeImage) (optional) - An icon to use in the notification. If a string is passed, it must be a valid path to a local icon file.

    • hasReply 布尔值（可选）macOS - 是否向通知添加内联回复选项。

      ¥hasReply boolean (optional) macOS - Whether or not to add an inline reply option to the notification.

    • timeoutType 字符串（可选） Linux Windows - 通知的超时时间。可以是 'default' 或 'never'。

      ¥timeoutType string (optional) Linux Windows - The timeout duration of the notification. Can be 'default' or 'never'.

    • replyPlaceholder 字符串（可选）macOS - 要在内联回复输入字段中写入的占位符。

      ¥replyPlaceholder string (optional) macOS - The placeholder to write in the inline reply input field.

    • sound 字符串（可选）macOS - 显示通知时要播放的声音文件的名称。

      ¥sound string (optional) macOS - The name of the sound file to play when the notification is shown.

    • urgency 字符串（可选） Linux - 通知的紧急程度。可以是 'normal'、'critical' 或 'low'。

      ¥urgency string (optional) Linux - The urgency level of the notification. Can be 'normal', 'critical', or 'low'.

    • actions NotificationAction[]（可选）macOS - 添加到通知的操作。请阅读 NotificationAction 文档中的可用操作和限制。

      ¥actions NotificationAction[] (optional) macOS - Actions to add to the notification. Please read the available actions and limitations in the NotificationAction documentation.

    • closeButtonText 字符串（可选）macOS - 警报关闭按钮的自定义标题。空字符串将导致使用默认的本地化文本。

      ¥closeButtonText string (optional) macOS - A custom title for the close button of an alert. An empty string will cause the default localized text to be used.

    • toastXml 字符串（可选） Windows - Windows 上的通知的自定义描述取代了上述所有属性。提供通知设计和行为的完全自定义。

      ¥toastXml string (optional) Windows - A custom description of the Notification on Windows superseding all properties above. Provides full customization of design and behavior of the notification.

实例事件​

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

事件：'show'​

¥Event: 'show'

返回：

¥Returns:

  • event 事件

    ¥event 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.

事件：'click'​

¥Event: 'click'

返回：

¥Returns:

  • event 事件

    ¥event Event

当用户单击通知时发出。

¥Emitted when the notification is clicked by the user.

事件：'close'​

¥Event: 'close'

返回：

¥Returns:

  • event 事件

    ¥event 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.

事件：'reply' macOS​

¥Event: 'reply' macOS

返回：

¥Returns:

  • event 事件

    ¥event Event

  • reply 字符串 - 用户输入到内联回复字段中的字符串。

    ¥reply string - The string the user entered into the inline reply field.

当用户单击带有 hasReply: true 的通知上的 "响应" 按钮时发出。

¥Emitted when the user clicks the "Reply" button on a notification with hasReply: true.

事件：'action' macOS​

¥Event: 'action' macOS

返回：

¥Returns:

  • event 事件

    ¥event Event

  • index 数字 - 已激活操作的索引。

    ¥index number - The index of the action that was activated.

事件：'failed' Windows​

¥Event: 'failed' Windows

返回：

¥Returns:

  • event 事件

    ¥event Event

  • error 字符串 - 执行 show() 方法期间遇到的错误。

    ¥error string - The error encountered during execution of the show() method.

创建和显示原生通知时遇到错误时发出。

¥Emitted when an error is encountered while creating and showing the native notification.

实例方法​

¥Instance Methods

使用 new Notification() 构造函数创建的对象具有以下实例方法：

¥Objects created with the new Notification() constructor have the following instance methods:

notification.show()​

立即向用户显示通知。与 Web 通知 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.

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.

实例属性​

¥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 属性。可以是 'normal'、'critical' 或 'low'。

¥A string property representing the urgency level of the notification. Can be 'normal', 'critical', or 'low'.

默认为 '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 设置为 'never'，则通知永不过期。它保持打开状态，直到被调用 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​

代表通知的自定义 Toast XML 的 string 属性。

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