跳到主要内容

Notification

创建操作系统桌面通知

进程：主进程

注意

如果你想从渲染进程显示通知，应该使用Web 通知 API

类：Notification​

创建操作系统桌面通知

进程：主进程

Notification 是一个 EventEmitter。

它使用 options 中设置的本地属性创建一个新的 Notification。

警告

Electron 的内置类无法在用户代码中进行子类化。更多信息，请参阅常见问题。

静态方法​

Notification 类具有以下静态方法

Notification.isSupported()​

返回 boolean - 当前系统是否支持桌面通知

new Notification([options])​

  • options 对象（可选）
    • title 字符串（可选）- 通知标题，在通知显示时会显示在通知窗口的顶部。
    • subtitle 字符串（可选）macOS - 通知副标题，将显示在标题下方。
    • body 字符串（可选）- 通知正文文本，将显示在标题或副标题下方。
    • silent 布尔值（可选）- 显示通知时是否抑制操作系统通知声音。
    • icon (字符串 | NativeImage)（可选）- 通知中使用的图标。如果传递字符串，它必须是本地图标文件的有效路径。
    • hasReply 布尔值（可选）macOS - 是否为通知添加内联回复选项。
    • timeoutType 字符串（可选）Linux Windows - 通知超时时长。可以是 'default' 或 'never'。
    • replyPlaceholder 字符串（可选）macOS - 内联回复输入字段中显示的占位符文本。
    • sound 字符串（可选）macOS - 通知显示时播放的声音文件名。
    • urgency 字符串（可选）Linux - 通知紧急程度。可以是 'normal'、'critical' 或 'low'。
    • actions NotificationAction[] （可选）macOS - 要添加到通知中的操作。请阅读 NotificationAction 文档中可用的操作和限制。
    • closeButtonText 字符串（可选）macOS - 警告框关闭按钮的自定义标题。空字符串将导致使用默认的本地化文本。
    • toastXml 字符串（可选）Windows - Windows 上通知的自定义描述，覆盖上述所有属性。提供对通知设计和行为的完全自定义。

实例事件​

使用 new Notification 创建的对象会触发以下事件

信息

某些事件仅在特定操作系统上可用，并已进行标注。

事件：'show'​

返回

  • event 事件

当通知显示给用户时触发。请注意，此事件可以触发多次，因为通知可以通过 show() 方法多次显示。

事件：'click'​

返回

  • event 事件

当用户点击通知时触发。

事件：'close'​

返回

  • event 事件

当用户手动关闭通知时触发。

在所有通知关闭的情况下，不保证此事件都会触发。

在 Windows 上，close 事件可以通过三种方式之一触发：通过 notification.close() 以编程方式关闭，用户关闭通知，或通过系统超时。如果在初始 close 事件触发后通知仍在操作中心中，调用 notification.close() 将从操作中心移除通知，但 close 事件不会再次触发。

事件：'reply' macOS​

返回

  • event 事件
  • reply 字符串 - 用户在内联回复字段中输入的字符串。

当用户点击带有 hasReply: true 的通知上的“回复”按钮时触发。

事件：'action' macOS​

返回

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

事件：'failed' Windows​

返回

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

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

实例方法​

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

notification.show()​

立即向用户显示通知。与 Web 通知 API 不同，实例化 new Notification() 并不会立即向用户显示通知。你需要在此方法调用之后操作系统才会显示通知。

如果通知之前已显示过，此方法将关闭之前显示的通知，并创建一个具有相同属性的新通知。

notification.close()​

关闭通知。

在 Windows 上，当通知在屏幕上可见时调用 notification.close() 将关闭通知并将其从操作中心移除。如果通知在屏幕上不再可见后调用 notification.close()，它将尝试从操作中心移除通知。

实例属性​

notification.title​

表示通知标题的 string 属性。

notification.subtitle​

表示通知副标题的 string 属性。

notification.body​

表示通知正文的 string 属性。

notification.replyPlaceholder​

表示通知回复占位符的 string 属性。

notification.sound​

表示通知声音的 string 属性。

notification.closeButtonText​

表示通知关闭按钮文本的 string 属性。

notification.silent​

表示通知是否静音的 boolean 属性。

notification.hasReply​

表示通知是否具有回复操作的 boolean 属性。

notification.urgency Linux​

表示通知紧急程度的 string 属性。可以是 'normal'、'critical' 或 'low'。

默认值为 'low' - 更多信息请参阅 NotifyUrgency。

notification.timeoutType Linux Windows​

表示通知超时持续时间类型的 string 属性。可以是 'default' 或 'never'。

如果 timeoutType 设置为 'never'，则通知永不超时。它会保持打开状态，直到被调用 API 或用户关闭。

notification.actions​

表示通知操作的 NotificationAction[] 属性。

notification.toastXml Windows​

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

播放声音​

在 macOS 上，你可以指定通知显示时要播放的声音名称。除了自定义声音文件外，还可以使用任何默认声音（在“系统偏好设置”>“声音”下）。请确保声音文件已复制到应用捆绑包（例如，YourApp.app/Contents/Resources）下，或以下位置之一：

  • ~/Library/Sounds
  • /Library/Sounds
  • /Network/Library/Sounds
  • /System/Library/Sounds

更多信息请参阅 NSSound 文档。