Уведомления

ДЕМОНСТРАЦИЯ

Уведомления представляют собой небольшие окна, всплывающие в центре или в углу главного окна приложения. Они используются для информирования пользователей о действиях, процессах и событиях в приложении.

Уведомления могут исчезать автоматически, или когда пользователь щелкает по экрану или нажимает Esc.

Для того чтобы показать уведомление, необходимо инжектировать в контроллер экрана интерфейс Notifications и воспользоваться его fluent API. В примере ниже уведомление показывается, когда пользователь щелкает по кнопке:

@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 необходимо передать параметр ContentMode.HTML в метод withContentMode().

@Autowired
private Notifications notifications;

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

Вы можете передать значение true в метод withHtmlSanitizer(), чтобы сделать доступной санитизацию HTML для содержимого уведомления. В этом случае параметр ContentMode.HTML должен быть передан в метод withContentMode().

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 стиля для уведомления. Подробнее см. в разделе themes/custom_theme.adoc#creating-new-styles.