通知消息

在线示例

通知消息是显示在应用程序主窗口中间或者角落的弹窗消息。用通知消息为用户提供应用程序中的活动、流程和事件的信息。

通知消息弹窗能自动消失，也可以在用户点击界面或按下 Esc 时消失。

如需显示通知消息，可以在界面控制器中注入 Notifications bean 然后使用其流式接口。在下面的例子中，点击按钮会显示通知消息：

@Autowired
private Notifications notifications;

@Subscribe("simple")
public void onSimpleClick(Button.ClickEvent event) {
    notifications.create()
            .withCaption("Upload successful!")
            .show();
}

消息内容

如需设置通知消息的标题，可使用 withCaption() 方法，支持使用主消息包中的本地化消息。

通知消息可以有一条信息内容描述，描述使用更轻的字体展示在标题下面。用 withDescription() 方法传入描述文本。

@Autowired
private Notifications notifications;

@Subscribe("withDescription")
public void onWithDescriptionClick(Button.ClickEvent event) {
    notifications.create()
            .withCaption("Upload complete!")
            .withDescription("Your file was uploaded successfully")
            .show();
}

使用 withContentMode() 方法可以定义消息文本的展示方式。有三种预定义的内容展示模式：

  • ContentMode.TEXT - 文本值作为纯文本展示。默认模式。

  • ContentMode.PREFORMATTED - 文本值作为预格式化的文本展示。在此模式中，在界面渲染时会保留换行。通知消息不支持 ContentMode.PREFORMATTED 模式。

  • ContentMode.HTML - 文本值将被解析并作为 HTML 展示。当使用 HTML 时，别忘了转义内容以防恶意代码注入。

可以在消息中使用 \n 字符来换行。如果要显示 HTML，可以用 withContentMode() 方法带 ContentMode.HTML 参数。

@Autowired
private Notifications notifications;

@Subscribe("withContent")
public void onWithContentClick(Button.ClickEvent event) {
    notifications.create()
            .withCaption("<i>Upload complete!</i>")
            .withContentMode(ContentMode.HTML)
            .show();
}

为 withHtmlSanitizer() 方法传参 true 可以启用通知消息内容的 HTML 清理功能。此时，必须为 withContentMode() 方法传递 ContentMode.HTML 参数。

protected static final String UNSAFE_HTML = "<i>Jackdaws </i><u>love</u> " +
        "<font size=\"javascript:alert(1)\" " +
        "color=\"moccasin\">my</font> " +
        "<font size=\"7\">big</font> <sup>sphinx</sup> " +
        "<font face=\"Verdana\">of</font> <span style=\"background-color: " +
        "red;\">quartz</span><svg/onload=alert(\"XSS\")>";

@Autowired
private Notifications notifications;

@Subscribe("showNotificationOnBtn")
public void onShowNotificationOnBtnClick(Button.ClickEvent event) {
    notifications.create()
            .withCaption("Notification with Sanitizer")
            .withDescription(UNSAFE_HTML)
            .withContentMode(ContentMode.HTML)
            .withHtmlSanitizer(true)
            .show();
}

@Subscribe("showNotificationOffBtn")
public void onShowNotificationOffBtnClick(Button.ClickEvent event) {
    notifications.create()
            .withCaption("Notification without Sanitizer")
            .withDescription(UNSAFE_HTML)
            .withContentMode(ContentMode.HTML)
            .withHtmlSanitizer(false)
            .show();
}

withHtmlSanitizer() 接收的参数会覆盖全局的 jmix.ui.component.htmlSanitizerEnabled 配置。

通知消息类型

通知消息可以是下列类型之一：

  • TRAY - 显示在应用程序右下角的消息，会自动消失。

    tray

  • HUMANIZED - 显示在界面中间的标准消息，会自动消失。

    humanized

  • WARNING - 显示在界面中间的警告消息。当用户点击界面时消失。

    warning

  • ERROR - 显示在界面中间的错误消息。当用户点击界面时消失。

    error

  • SYSTEM - 显示在界面顶部中间的系统通知消息。当用户点击消息时消失。

    system

默认类型是 HUMANIZED。也可以在 create() 方法中使用其他类型：

@Autowired
private Notifications notifications;

@Subscribe("withType")
public void onWithTypeClick(Button.ClickEvent event) {
    notifications.create(Notifications.NotificationType.TRAY)
            .withCaption("Upload complete!")
            .withDescription("Your file was uploaded successfully")
            .show();
}

位置

用 withPosition() 方法可以设置通知消息的位置。支持的标准值为：

  • DEFAULT

  • TOP_RIGHT

  • TOP_LEFT

  • TOP_CENTER

  • MIDDLE_RIGHT

  • MIDDLE_LEFT

  • MIDDLE_CENTER

  • BOTTOM_RIGHT

  • BOTTOM_LEFT

  • BOTTOM_CENTER

延迟

TRAY 和 HUMANIZED 类型的通知默认在界面停留 3 秒。

WARNING、ERROR 和 SYSTEM 类型的通知要求用户点击。

还可以用 withHideDelayMs() 方法设置通知消息停留的时间，以毫秒为单位。-1 表示禁用自动关闭，需要用户点击消息才会消失。

样式

用 withStyleName() 方法为通知设置自定义的 CSS 样式名。参阅 创建新样式 了解详情。