valuePicker

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

valuePicker отображает значение любого типа. Он состоит из текстового поля и набора кнопок, определяемых действиями.

XML-элемент

valuePicker

Java-класс

JmixValuePicker

Атрибуты

id - alignSelf - allowCustomValue - ariaLabel - ariaLabelledBy - autofocus - classNames - colspan - css - dataContainer - enabled - errorMessage - focusShortcut - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - placeholder - property - readOnly - required - requiredMessage - tabIndex - themeNames - title - visible - width

Обработчики

AttachEvent - BlurEvent - ComponentValueChangeEvent - CustomValueSetEvent - DetachEvent - FocusEvent - formatter - statusChangeHandler - validator

Элементы

actions - formatter - prefix - suffix - tooltip - validator

Основы

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

value picker basic

Пример определения valuePicker c label и двумя действиями:

<valuePicker id="valuePicker" label="Code">
    <actions>
        <action id="generate" icon="REFRESH"/>
        <action id="valueClear" type="value_clear"/>
    </actions>
</valuePicker>

Чтобы создать valuePicker, связанный с данными, используйте атрибуты dataContainer и property:

<data>
    <instance class="com.company.onboarding.entity.Step" id="stepDc"> (1)
        <fetchPlan extends="_base"/> (2)
        <loader id="stepDl"/>
    </instance>
</data>
<layout>
    <valuePicker label="msg://com.company.onboarding.entity/Step.name"
                 dataContainer="stepDc"
                 property="name"> (3)
        <actions>
            <action id="lookup" icon="ELLIPSIS_DOTS_H"/>
            <action id="valueClear" type="value_clear"/>
        </actions>
    </valuePicker>
</layout>
1 InstanceContainer для сущности Step.
2 Встроенный план выборки экземпляра сущности, находящегося в контейнере.
3 Привязка компонента к контейнеру данных и свойству. Атрибут dataContainer содержит ссылку на контейнер данных stepDc, а атрибут property ссылается на атрибут сущности name.

Действия

Вы можете определить пользовательские и предопределенные действия для valuePicker, которые отображаются в виде кнопок справа. Это можно сделать либо в XML-дескрипторе, используя вложенный элемент actions, либо программно в контроллере, используя метод addAction().

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

Предопределенные

Фреймворк предоставляет только одно предопределенное действие - value_clear:

<action id="valueClear" type="value_clear"/>

Используйте атрибуты type и id для объявления предопределенного действия в XML.

Используйте addAction() для установки предопределенного действия программно:

@ViewComponent
private JmixValuePicker<String> loginValuePicker;

@Autowired
private Actions actions;

@Subscribe
public void onInit(InitEvent event) {
    loginValuePicker.addAction(actions.create(ValueClearAction.ID));
}

Пользовательские

Чтобы определить пользовательское действие в XML, используйте вложенный элемент actions. Укажите атрибуты id и icon для действия:

<valuePicker id="generateLoginPicker" label="Login">
    <actions>
        <action id="valueClear" type="value_clear"/>
        <action id="generate" icon="REFRESH"/>
    </actions>
</valuePicker>

Затем реализуйте пользовательскую логику в контроллере экрана, подписавшись на событие ActionPerformedEvent:

@ViewComponent
private JmixValuePicker<String> generateLoginPicker;

@Subscribe("generateLoginPicker.generate")
public void onGenerateLoginPickerGenerate(ActionPerformedEvent event) {
    generateLoginPicker.setValue(RandomStringUtils.randomAlphabetic(5, 10));
}

Обработка пользовательского ввода

valuePicker позволяет вам настроить его для принятия пользовательских значений.

Когда атрибут allowCustomValue установлен в true, пользователи могут вводить произвольные строковые значения. Это приводит к событию CustomValueSetEvent.

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

Пример обработки пользовательского ввода:

@Autowired
private Notifications notifications;

@ViewComponent
private JmixValuePicker<String> vPicker;

@Subscribe("vPicker")
public void onVPickerCustomValueSet(
        CustomValueSetEvent<JmixValuePicker<String>, Object> event) {
    String text = event.getText(); (1)
    notifications.create("Entered value: " + text)
            .show();
    if (!Strings.isNullOrEmpty(text))
        vPicker.setValue(text); (2)
}
1 Получите значение ввода пользователя как строку.
2 Установите это значение в vPicker.

Форматер

Добавляет экземпляр форматера к компоненту.

В примере ниже мы покажем использование форматера для vPicker:

@Install(to = "vPicker", subject = "formatter")
private String vPickerFormatter(String value) {
    return value != null ? "Code: " + value : null;
}

Чтобы добавить форматер программно, используйте метод компонента setFormatter().

Валидация

Чтобы проверить значения, введенные в компонент valuePicker вы можете использовать валидатор в элементе validators.

Доступны следующие предопределенные валидаторы для valuePicker:

XML-элемент

validators

Предопределенные валидаторы

custom - decimalMax - decimalMin - digits - doubleMax - doubleMin - email - max - min - negativeOrZero - negative - notBlank - notEmpty - notNull - positiveOrZero - positive - regexp - size

Атрибуты

В Jmix есть множество общих атрибутов, которые выполняют одну и ту же функцию для всех компонентов.

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

Название

Описание

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

allowCustomValue

По умолчанию пользователи не могут вручную вводить значения в поле valuePicker. Если вы установите атрибут allowCustomValue в true, вы включите ручной ввод. Имейте в виду, что введенное значение не будет автоматически установлено в модели данных. Для обработки пользовательского ввода используйте событие CustomValueSetEvent. Смотрите Обработка пользовательского ввода.

false

Обработчики

В Jmix существует множество общих обработчиков, которые конфигурируются одинаково для всех компонентов.

Ниже приведены обработчики, специфичные для valuePicker.

Чтобы сгенерировать заглушку обработчика в Jmix Studio, используйте вкладку Handlers панели инспектора Jmix UI, или команду Generate Handler, доступную на верхней панели контроллера экрана и через меню Code → Generate (Alt+Insert / Cmd+N).

Название

Описание

CustomValueSetEvent

Событие io.jmix.flowui.kit.component.valuepicker.CustomValueSetEvent генерируется, когда пользователь вводит непустое значение. Чтобы разрешить ввод пользовательских значений, установите атрибут allowCustomValue в true. Смотрите Обработка пользовательского ввода.

formatter

Добавляет экземпляр форматера к компоненту. Смотрите Форматер.