popover

Начиная с Jmix 3.1

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

XML-элемент

popover

Java-класс

Popover

Основы

Объявите popover в дескрипторе экрана и укажите в атрибуте target идентификатор компонента:

<button id="infoButton" text="About" icon="INFO_CIRCLE_O"/>
<popover id="infoPopover" target="infoButton" width="20em">
    <vbox padding="false">
        <h4 text="Onboarding"/>
        <span text="New employees complete the onboarding steps during their first weeks."/>
        <button id="closeButton" text="Close"/>
    </vbox>
</popover>
Всплывающее окно под целевым компонентом

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

Всплывающее окно и его содержимое — обычные компоненты экрана. Их можно инжектировать в контроллер экрана и подписываться на их события. В примере выше кнопка во всплывающем окне закрывает его методом close():

@ViewComponent
private Popover infoPopover;

@Subscribe(id = "closeButton", subject = "clickListener")
public void onCloseButtonClick(final ClickEvent<JmixButton> event) {
    infoPopover.close();
}

Целевой компонент

Атрибут target содержит идентификатор компонента того же экрана или фрагмента. Целевой компонент можно объявить как до, так и после всплывающего окна. Если компонента с таким идентификатором нет, экран не откроется и выбросит GuiDevelopmentException.

Атрибут target необязателен. Если целевой компонент создаётся в контроллере экрана, объявите всплывающее окно без target:

<textField id="emailField" label="Email"/>
<popover id="emailHelpPopover" width="16em">
    <span text="Use your corporate address."/>
</popover>

Затем задайте целевой компонент методом setTarget():

@ViewComponent
private Popover emailHelpPopover;
@ViewComponent
private TypedTextField<String> emailField;
@Autowired
private UiComponents uiComponents;

@Subscribe
public void onInit(final InitEvent event) {
    JmixButton helpButton = uiComponents.create(JmixButton.class);
    helpButton.setIcon(VaadinIcon.QUESTION_CIRCLE.create());
    helpButton.addThemeVariants(ButtonVariant.TERTIARY);
    emailField.setSuffixComponent(helpButton);

    emailHelpPopover.setTarget(helpButton);
}

Всплывающее окно без целевого компонента не открывается в ответ на действия пользователя. Если открыть его методом open(), оно появится в центре экрана.

Открытие и закрытие

Атрибуты openOnClick, openOnHover и openOnFocus определяют, какие действия пользователя открывают всплывающее окно. По умолчанию включён только openOnClick. Можно включить несколько атрибутов одновременно.

Открытие при наведении

Следующее всплывающее окно открывается, когда пользователь наводит курсор мыши на аватар:

<avatar id="userAvatar" name="Alice Brown"/>
<popover target="userAvatar"
         openOnClick="false"
         openOnHover="true"
         hoverDelay="300"
         hideDelay="300">
    <vbox padding="false" spacing="false">
        <h5 text="Alice Brown"/>
        <span text="HR manager"/>
        <anchor href="mailto:alice@company.com" text="alice@company.com"/>
    </vbox>
</popover>

Окно закрывается, когда курсор покидает и целевой компонент, и само окно. Поэтому пользователь может перевести курсор на окно и нажать на ссылку в нём.

Атрибут hoverDelay задаёт задержку перед открытием окна, а hideDelay — перед закрытием. Обе задержки указываются в миллисекундах и по умолчанию равны 500.

Открытие при получении фокуса

Следующее всплывающее окно открывается, когда поле пароля получает фокус:

<passwordField id="passwordField" label="Password"/>
<popover target="passwordField"
         openOnClick="false"
         openOnFocus="true"
         position="END">
    <span text="Use at least 8 characters, including a letter and a digit."/>
</popover>

Окно закрывается, когда фокус покидает и целевой компонент, и само окно. Атрибут focusDelay задаёт задержку перед открытием окна, по умолчанию 500 миллисекунд.

Программное открытие

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

<hbox alignItems="BASELINE">
    <textField id="promoCodeField" label="Promo code"/>
    <button id="promoCodeHelpButton" text="Where do I find it?" themeNames="tertiary"/>
</hbox>
<popover id="promoCodePopover"
         target="promoCodeField"
         openOnClick="false"
         width="16em">
    <span text="The promo code is printed on the back of your loyalty card."/>
</popover>
@ViewComponent
private Popover promoCodePopover;

@Subscribe(id = "promoCodeHelpButton", subject = "clickListener")
public void onPromoCodeHelpButtonClick(final ClickEvent<JmixButton> event) {
    promoCodePopover.open();
}

Методы open() и close() открывают и закрывают всплывающее окно, а isOpened() возвращает его текущее состояние.

Закрытие

Как бы ни было открыто всплывающее окно, закрыть его можно нажатием за его пределами или клавишей Esc. Чтобы отключить это поведение, установите атрибутам closeOnOutsideClick и closeOnEsc значение false.

Положение

Атрибут position определяет, где открывается всплывающее окно относительно целевого компонента: сверху (TOP_START, TOP, TOP_END), снизу (BOTTOM_START, BOTTOM, BOTTOM_END), перед ним (START_TOP, START, START_BOTTOM) или после него (END_TOP, END, END_BOTTOM). По умолчанию используется BOTTOM. Если с этой стороны не хватает места, окно открывается с противоположной стороны.

Следующее всплывающее окно открывается после кнопки и показывает указывающую на неё стрелку:

<button id="statusButton" text="Status"/>
<popover target="statusButton" position="END" themeNames="arrow">
    <span text="3 of 5 steps completed"/>
</popover>

Модальное всплывающее окно работает как небольшой диалог рядом с целевым компонентом. Пока оно открыто, пользователь не может работать с остальным интерфейсом, а фокус остаётся внутри окна. Установите modal="true", чтобы сделать окно модальным, и backdropVisible="true", чтобы затемнить интерфейс за ним.

По умолчанию модальное окно закрывается при нажатии за его пределами. В следующем примере задан closeOnOutsideClick="false", поэтому окно остаётся открытым, пока пользователь не нажмёт одну из кнопок в нём:

<h3 id="reportTitle" text="Quarterly report"/>
<button id="renameButton" text="Rename"/>
<popover id="renamePopover"
         target="renameButton"
         modal="true"
         backdropVisible="true"
         closeOnOutsideClick="false"
         width="18em">
    <vbox padding="false">
        <textField id="titleField" label="Title" width="100%"/>
        <hbox>
            <button id="saveButton" text="Save" themeNames="primary"/>
            <button id="cancelButton" text="Cancel"/>
        </hbox>
    </vbox>
</popover>
Модальное всплывающее окно с затемнённым фоном

Контроллер заполняет поле при открытии окна и сохраняет значение, когда пользователь нажимает Save:

@ViewComponent
private Popover renamePopover;
@ViewComponent
private H3 reportTitle;
@ViewComponent
private TypedTextField<String> titleField;

@Subscribe("renamePopover")
public void onRenamePopoverOpenedChange(final Popover.OpenedChangeEvent event) {
    if (event.isOpened()) {
        titleField.setValue(reportTitle.getText());
    }
}

@Subscribe(id = "saveButton", subject = "clickListener")
public void onSaveButtonClick(final ClickEvent<JmixButton> event) {
    reportTitle.setText(titleField.getValue());
    renamePopover.close();
}

@Subscribe(id = "cancelButton", subject = "clickListener")
public void onCancelButtonClick(final ClickEvent<JmixButton> event) {
    renamePopover.close();
}

Размер и стили

Атрибуты width и height задают размер содержимого всплывающего окна. Используйте абсолютные единицы, например px или em: с относительными единицами, такими как %, результат непредсказуем. Без этих атрибутов окно принимает размер своего содержимого. Атрибуты minWidth, maxWidth, minHeight и maxHeight не поддерживаются.

Всплывающее окно отображается в отдельном слое поверх экрана, поэтому атрибут css не поддерживается, а метод getStyle() в Java выбрасывает UnsupportedOperationException. Чтобы задать стиль окна, добавьте ему имена классов атрибутом classNames и опишите стили в теме приложения.

Варианты темы

Используйте атрибут themeNames, чтобы применить вариант темы.

Вариант Описание Поддерживается в

arrow

Показывает стрелку, указывающую на целевой компонент.

Aura, Lumo

no-padding

Убирает внутренние отступы вокруг содержимого.

Aura, Lumo

Атрибуты

Следующие атрибуты относятся к popover:

Имя Описание По умолчанию

ariaRole

Задаёт ARIA-роль всплывающего окна, которую используют программы чтения с экрана.

dialog

autofocus

Если true, содержимое всплывающего окна получает фокус при открытии. Модальные окна делают это по умолчанию.

false

backdropVisible

Если true, интерфейс за открытым всплывающим окном затемняется. См. Модальное всплывающее окно.

false

closeOnEsc

Если true, клавиша Esc закрывает всплывающее окно. См. Закрытие.

true

closeOnOutsideClick

Если true, нажатие за пределами всплывающего окна закрывает его. См. Закрытие.

true

focusDelay

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

500

height

Задаёт высоту содержимого всплывающего окна. См. Размер и стили.

—

hideDelay

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

500

hoverDelay

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

500

modal

Если true, пока всплывающее окно открыто, пользователь не может работать с остальным интерфейсом. См. Модальное всплывающее окно.

false

openOnClick

Если true, нажатие на целевой компонент открывает всплывающее окно. См. Открытие и закрытие.

true

openOnFocus

Если true, всплывающее окно открывается, когда целевой компонент получает фокус. См. Открытие при получении фокуса.

false

openOnHover

Если true, всплывающее окно открывается при наведении курсора на целевой компонент. См. Открытие при наведении.

false

position

Задаёт положение всплывающего окна относительно целевого компонента. См. Положение.

BOTTOM

tabFocusEnabled

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

true

target

Задаёт идентификатор целевого компонента. См. Целевой компонент.

—

themeNames

Применяет один или несколько вариантов из раздела Варианты темы.

—

width

Задаёт ширину содержимого всплывающего окна. См. Размер и стили.

—

Компонент поддерживает следующие общие атрибуты:

id - ariaLabel - ariaLabelledBy - classNames - enabled - visible

Обработчики

Название Описание

AttachEvent

Срабатывает при присоединении компонента к UI.

DetachEvent

Срабатывает при отсоединении компонента от UI.

OpenedChangeEvent

Срабатывает при открытии или закрытии всплывающего окна. Метод isOpened() события показывает, что произошло. См. Модальное всплывающее окно.

Элементы

popover может содержать любые компоненты и контейнеры.

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