DesktopNotification

在 webforj 25.00 及更高版本中，DesktopNotification 组件提供了一个简单的接口，用于创建、显示和管理桌面通知。该组件专注于最小的配置和内置事件处理，可用于在用户浏览应用时通知他们实时事件（例如新消息、警报或系统事件）。

实验性功能

DesktopNotification 组件仍在不断发展，因此其 API 可能会随着其成熟而发生变化。要开始使用此功能，请确保在您的 pom.xml 中包含以下依赖项。

<dependency>
  <groupId>com.webforj</groupId>
  <artifactId>webforj-desktop-notification</artifactId>
</dependency>

前提条件

在集成 DesktopNotification 组件之前，请确保：

您的应用在 安全上下文（HTTPS）中运行。
浏览器不处于隐身或私密浏览模式。
用户已与应用进行交互（例如，点击按钮或按下键），因为通知需要用户手势才能显示。
用户已授予通知权限（如果需要，将自动请求此权限）。

基本用法

有多种方法可以创建和显示通知。在大多数情况下，最简单的方法是调用一个静态的 show 方法，该方法封装了整个通知生命周期。

示例：显示一个基本通知

// 带有标题和消息的基本通知
DesktopNotification.show("更新可用", "您的下载已完成！");

这行代码创建了一个带有标题和正文的通知，然后尝试显示它。

自定义通知

根据应用的需求和通知的目的，有多种选项可以自定义显示的通知的外观和感觉。

设置自定义 `Icon`

默认情况下，通知使用您通过 icons 协议定义的应用图标。您可以使用 setIcon 方法设置自定义图标。该组件支持不同的 URL 方案：

context://：解析为指向应用资源文件夹的上下文 URL；图像为 base64 编码。
ws://：解析为 Web 服务器 URL，提供完全限定的 URL。
icons://：解析为图标 URL。

示例：

// 创建带有自定义图标 URL 的通知
DesktopNotification notification = new DesktopNotification(
  "提醒", "会议在 10 分钟后开始。"
);
notification.setIcon("context://images/custom-icon.png");
notification.open();

通知事件

DesktopNotification 支持多个生命周期事件，并可以附加监听器以处理事件，例如当通知被显示、关闭、点击或遇到错误时。

事件	描述	使用时机
打开	当通知显示时触发。	记录通知显示，更新 UI，跟踪参与度。
关闭	当通知关闭时触发。	清理资源，记录关闭，执行后续操作。
错误	当通知出现错误或用户未授予权限时触发。	优雅地处理错误，通知用户，应用后备方案。
点击	当用户点击通知时触发。	导航到特定部分，记录交互，重新聚焦应用。

DesktopNotification notification = new DesktopNotification("警报", "您有一条新消息！")

// 附加打开事件的事件监听器
notification.onOpen(event -> {
  System.out.println("用户打开了通知。");
});

// 同样，监听点击事件
notification.onClick(event -> {
  System.out.println("通知被点击。");
});

点击行为

浏览器的安全政策阻止通知点击事件自动使您的应用窗口或标签页获得焦点。这种行为由浏览器强制执行，无法通过编程覆盖。如果您的应用需要窗口聚焦，您需要指示用户在与通知交互后单击应用内的内容。

安全和兼容性考虑事项

使用 DesktopNotification 组件时，请记住以下几点：

安全上下文： 您的应用必须通过 HTTPS 提供，以确保大多数现代浏览器允许通知。
用户手势要求： 只有在用户触发的操作后，通知才会显示。仅加载页面不会触发通知。
浏览器限制： 并非所有浏览器对自定义图标或焦点行为的处理方式相同。例如，自定义图标可能在 Safari 中不起作用，而事件行为可能在其他浏览器中有所不同。
权限： 始终确保您的应用检查并优雅地请求用户的通知权限。

使用最佳实践

在您的应用中使用 DesktopNotification 组件时，请记住以下最佳实践：

告知用户： 让用户知道为什么需要通知以及他们如何从中受益。
提供后备方案： 由于某些浏览器可能限制通知，请考虑以其他方式提醒用户（例如，在应用内消息）。
错误处理： 始终注册错误监听器，以优雅地处理通知未能显示的情况。

基本用法​

示例：显示一个基本通知​

自定义通知​

设置自定义 Icon​

通知事件​

安全和兼容性考虑事项​

使用最佳实践​