tooltip

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

Всплывающая подсказка (tooltip) - это небольшое всплывающее окно, которое может предоставить дополнительную информацию об элементе пользовательского интерфейса при наведении курсора мыши и фокусировке с помощью клавиатуры.

XML-элемент

tooltip

Атрибуты

focusDelay - hideDelay - hoverDelay - manual - opened - position - text

Основы

tooltip является вложенным элементом почти всех компонентов и контейнеров.

Чтобы добавить вложенный tooltip в Jmix Studio, выберите элемент пользовательского интерфейса в XML-дескрипторе экрана или на панели структуры Jmix UI и нажмите кнопку Add→Tooltip на панели инспектора Jmix UI.

Пример определения кнопки со всплывающей подсказкой:

<button icon="CREDIT_CARD">
    <tooltip text="Add a credit card" position="END_TOP"/>
</button>
tooltip basic

Программное определение

Компонент tooltip можно определить программно в коде вашего приложения. Вот пример того, как вы можете программно определить и использовать всплывающую подсказку для компонента textField:

@ViewComponent
private TypedTextField<String> programmaticField;

@Subscribe
public void onInit(final InitEvent event) {
    programmaticField.setTooltipText("This is a tooltip")
            .setPosition(Tooltip.TooltipPosition.START);
}

Настройка расположения

Всплывающая подсказка, по умолчанию, позиционируется относительно целевого компонента, к которому она прикреплена. Фреймворк автоматически вычисляет оптимальное место для отображения всплывающей подсказки, учитывая доступное пространство на экране и избегая перекрытия с другими элементами.

Атрибут position напрямую влияет на расположение всплывающей подсказки на экране, позволяя вам управлять тем, где она отображается. Атрибут position принимает значения из перечисления TooltipPosition.

Вы можете задать атрибут position с помощью метода setPosition() в вашем коде:

programmaticField.getTooltip()
        .setPosition(Tooltip.TooltipPosition.START);

В XML-дескрипторе экрана вы можете указать атрибут position:

<textField id="textField">
    <tooltip text="Basics tooltip"
             position="END_BOTTOM"/>
</textField>

Управление задержками

tooltip позволяет настроить задержки для появления и исчезновения всплывающей подсказки, что дает вам возможность управлять временем взаимодействия подсказки с пользователем.

Задержка фокусировки

Атрибут focusDelay управляет задержкой, в миллисекундах, перед появлением всплывающей подсказки, когда курсор мыши наводится на компонент с элементом tooltip.

В этом примере всплывающая подсказка появится после 500-миллисекундной задержки, когда курсор мыши наводится на текстовое поле:

<textField label="Text Field">
    <tooltip text="This is a tooltip"
             focusDelay="500"/>
</textField>

Задержка скрытия

Атрибут hideDelay управляет задержкой, в миллисекундах, перед скрытием всплывающей подсказки, когда курсор мыши уходит с компонента с элементом tooltip.

В этом примере всплывающая подсказка будет оставаться видимой в течение 1 секунды после того, как курсор мыши уйдет с текстового поля, прежде чем исчезнуть:

<textField label="Text Field">
    <tooltip text="This is a tooltip"
             hideDelay="1000"/>
</textField>

Задержка наведения

Атрибут hoverDelay управляет задержкой, в миллисекундах, перед появлением всплывающей подсказки, когда курсор мыши наводится на компонент с элементом tooltip.

В этом примере всплывающая подсказка появится после 500-миллисекундной задержки, когда курсор мыши наводится на текстовое поле:

<textField label="Text Field">
    <tooltip text="This is a tooltip"
             hoverDelay="500"/>
</textField>

Принудительное отображение

Вы можете настроить всплывающие подсказки так, чтобы они отображались программно, то есть они не будут появляться при наведении курсора или фокусировке, а только при вызове вашим кодом. Это особенно полезно, когда:

  • Вам необходимо отобразить всплывающую подсказку на основе определенных условий или взаимодействий пользователя.

  • Содержимое всплывающей подсказки должно генерироваться или обновляться динамически.

В XML-дескрипторе экрана установите атрибут manual в значение true. Это означает, что всплывающая подсказка не будет отображаться автоматически и требует ручного управления.

<textField id="manualTextField"
           label="Text Field">
    <tooltip text="This is a tooltip"
             manual="true"/>
</textField>

Затем настройте всплывающую подсказку в контроллере экрана.

@ViewComponent
private TypedTextField<String> manualTextField;

@Autowired
private UiComponents uiComponents;

@Subscribe
public void onInit(final InitEvent event) {
    JmixButton helperButton = createHelperButton();
    Tooltip tooltip = manualTextField.getTooltip();
    helperButton.addClickListener(e ->
            tooltip.setOpened(!tooltip.isOpened())); (1)

    manualTextField.setSuffixComponent(helperButton);
}

protected JmixButton createHelperButton() {
    JmixButton helperButton = uiComponents.create(JmixButton.class);
    helperButton.setIcon(VaadinIcon.QUESTION_CIRCLE.create());
    helperButton.addThemeVariants(ButtonVariant.LUMO_ICON,
            ButtonVariant.LUMO_TERTIARY_INLINE);

    return helperButton;
}
1 Атрибут opened управляет тем, видна ли всплывающая подсказка в данный момент. Это булево значение, где true означает, что подсказка открыта, а false - что она закрыта.
Хотя opened можно устанавливать вручную, обычно им управляет сам фреймворк на основе событий, таких как наведение курсора мыши или фокусировка. Этот атрибут полезен для управления видимостью всплывающей подсказки в сценариях, где вам необходимо программно открыть или закрыть ее.

Атрибуты

Ниже представлены атрибуты, специфичные для tooltip:

Название

Описание

Значение по умолчанию

focusDelay

Определяет задержку в миллисекундах перед открытием всплывающей подсказки при фокусировке с помощью клавиатуры, если tooltip находится не в ручном режиме. Смотрите Задержка фокусировки.

0

hideDelay

Определяет задержку в миллисекундах перед закрытием всплывающей подсказки при уходе курсора мыши, если tooltip находится не в ручном режиме. При потере фокуса (blur) всплывающая подсказка закрывается немедленно. Смотрите Задержка скрытия.

0

hoverDelay

Определяет задержку в миллисекундах перед открытием всплывающей подсказки при наведении курсора мыши, если tooltip находится не в ручном режиме. Смотрите Задержка наведения.

0

manual

Если установлено в true, всплывающая подсказка управляется программно, а не реагирует на события фокусировки и мыши. Смотрите Принудительное отображение.

false

opened

Если установлено в true, всплывающая подсказка открывается программно. Работает, только если manual установлено в true. Смотрите Принудительное отображение.

false

position

Определяет позицию всплывающей подсказки относительно ее целевого элемента. Смотрите Настройка расположения.

text

Определяет строку, используемую в качестве содержимого всплывающей подсказки.

Смотрите также

Смотрите документацию Vaadin для получения дополнительной информации.