valuePicker

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

XML-элемент

valuePicker

Java-класс

JmixValuePicker

Основы

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

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

XML
<valuePicker id="valuePicker" dataContainer="customerDc" property="name" allowCustomValue="true"
             label="Name" helperText="Generate or type a customer name">
    <actions>
        <action id="generate" icon="REFRESH" description="Generate name"/>
        <action id="value_clear" type="value_clear"/>
    </actions>
</valuePicker>
Java
@ViewComponent
protected InstanceContainer<Customer> customerDc;
@Autowired
protected Metadata metadata;

protected List<String> names = List.of("Katherine", "John", "Andy", "Edward", "George",
        "Philipp", "Dora", "James", "Daniel", "Michael", "Claire", "Joan", "Peter", "Martin");
@Subscribe
protected void onInit(InitEvent event) {
    Customer customer = metadata.create(Customer.class);
    customer.setName(getRandomName());
    customerDc.setItem(customer);
}
@Subscribe("valuePicker.generate")
protected void onValuePickerGenerateActionPerformed(ActionPerformedEvent event) {
    customerDc.getItem().setName(getRandomName());
}

@Subscribe("valuePicker")
protected void onValuePickerCustomValueChange(CustomValueSetEvent<JmixValuePicker<String>, String> event) {
    customerDc.getItem().setName(event.getText());
}

protected String getRandomName() {
    return names.get(RandomUtils.secure().randomInt() % names.size());
}

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

<data>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"
              fetchPlan="_local"/>
</data>
    <valuePicker id="valuePicker" dataContainer="customerDc" property="name" allowCustomValue="true"
                 label="Name" helperText="Generate or type a customer name">
        <actions>
            <action id="generate" icon="REFRESH" description="Generate name"/>
            <action id="value_clear" type="value_clear"/>
        </actions>
    </valuePicker>

Контейнер экземпляра customerDc хранит сущность Customer. Компонент связан с её атрибутом name.

Действия

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

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

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

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

<valuePicker id="valuePicker1" label="Random string">
    <actions>
        <action id="generate" icon="REFRESH" description="Generate value"/>
        <action id="value_clear" type="value_clear"/>
    </actions>
</valuePicker>

Используйте атрибуты 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. Для action укажите атрибуты id и icon:

<valuePicker id="valuePicker1" label="Random string">
    <actions>
        <action id="generate" icon="REFRESH" description="Generate value"/>
        <action id="value_clear" type="value_clear"/>
    </actions>
</valuePicker>

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

@ViewComponent
protected JmixValuePicker<String> valuePicker1;
@Subscribe("valuePicker1.generate")
protected void onValuePicker1GenerateActionPerformed(ActionPerformedEvent event) {
    generateValue(valuePicker1);
}
protected void generateValue(JmixValuePicker<String> valuePicker) {
    valuePicker.setValue(RandomStringUtils.secure().nextAlphabetic(5, 10));
}

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

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

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

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

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

@ViewComponent
protected JmixValuePicker<String> valuePicker2;
@Subscribe("valuePicker2")
protected void onValuePicker2CustomValueChange(CustomValueSetEvent<JmixValuePicker<String>, String> event) {
    event.getSource().setValue(event.getText());
}

Форматер

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

В примере ниже мы покажем использование форматера для 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

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

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

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

align-left

Выравнивает значение поля по левому краю.

Aura, Lumo

align-center

Выравнивает значение поля по центру.

Aura, Lumo

align-right

Выравнивает значение поля по правому краю.

Aura, Lumo

align-start

Выравнивает значение поля по начальной стороне с учетом текущего направления текста.

Aura

align-end

Выравнивает значение поля по конечной стороне с учетом текущего направления текста.

Aura

helper-above-field

Размещает вспомогательный текст над полем, под меткой.

Aura, Lumo

small

Уменьшает размер компонента.

Aura, Lumo

Атрибуты

valuePicker имеет следующие уникальные атрибуты:

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

allowCustomValue

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

false

valuePicker имеет следующие общие атрибуты:

Обработчики

valuePicker имеет следующие уникальные обработчики:

Имя Описание

CustomValueSetEvent

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

formatter

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

validator

Проверяет значение компонента.

valuePicker имеет следующие общие обработчики:

Элементы

Компонент valuePicker может содержать следующие вложенные элементы: actions, formatter, prefix, suffix, tooltip, и validator.