Formatter

Formatter предназначен для преобразования некоторого значения в его строковое представление.

Форматтер можно использовать только с нередактируемыми компонентами, такими как valuePicker, multiValuePicker и entityPicker. Значения непосредственно редактируемых компонентов, например textField, форматируются механизмом Datatype.

Фреймворк содержит набор форматтеров, которые можно использовать в проекте.

В XML-дескрипторах экранов форматтеры добавляются компонентам во вложенном в компонент элементе formatter.

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

Ниже приведен пример добавления форматтера компоненту valuePicker:

add formatter

Каждый форматтер представляет собой prototype bean, поэтому если необходимо использовать форматтеры в коде Java, их нужно получать с помощью ApplicationContext или ObjectProvider. См. примеры ниже.

Number Formatter

Форматтер чисел представляет числовое значение в виде строки в соответствии с указанным форматом.

Он имеет следующий атрибут:

  • format - строка формата, которая используется для создания экземпляра DecimalFormat. Это может быть либо сама строка формата, либо ключ в пакете сообщений.

Использование в XML:

<valuePicker id="valueNumberPicker" label="Number">
    <actions>
        <action id="generate" icon="REFRESH"/>
    </actions>
    <formatter>
        <number format="#,##0.00"/>
    </formatter>
</valuePicker>

Использование в Java:

@ViewComponent
private JmixValuePicker<BigDecimal> valueNumberPicker;

@Autowired
private ApplicationContext applicationContext;

@Subscribe
public void onInit(InitEvent event) {
    NumberFormatter formatter = applicationContext.getBean(NumberFormatter.class);
    formatter.setFormat("#,##0.00");
    valueNumberPicker.setFormatter(formatter);
}

Date and Time Formatter

Форматтер даты и времени представляет временное значение в виде строки в соответствии с указанным форматом.

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

  • format - строка формата, который используется для создания экземпляра SimpleDateFormat. Это может быть либо сама строка формата, либо ключ в пакете сообщений.

  • type - тип форматтера: DATE или DATETIME. Если он указан, значение будет отформатировано с использованием DateDatatype или DateTimeDatatype соответственно.

  • useUserTimezone - должен ли форматтер отображать дату и время в часовом поясе текущего пользователя. По умолчанию форматтер отображает дату и время в часовом поясе сервера. Чтобы отобразить часовой пояс текущего пользователя, установите true в данном атрибуте.

Использование в XML:

<valuePicker id="valuePicker" label="Date">
    <actions>
        <action id="generate" icon="REFRESH"/>
    </actions>
    <formatter>
        <date type="DATE" format="h:mm a"/>
    </formatter>
</valuePicker>

Использование в Java:

@ViewComponent
private JmixValuePicker<LocalDateTime> valuePicker;

@Autowired
private ApplicationContext applicationContext;

@Subscribe
public void onInit(InitEvent event) {
    DateFormatter dateFormatter = applicationContext.getBean(DateFormatter.class);
    dateFormatter.setFormat("h:mm a");
    valuePicker.setFormatter(dateFormatter);
}

Collection Formatter

Форматтер коллекций представляет коллекцию в виде строки с элементами коллекции, разделенными запятыми.

Создание собственных форматтеров

Собственный форматтер можно определить в бине-прототипе, реализующем интерфейс Formatter.

Пример объявления пользовательского форматтера:

@Component
@Scope(BeanDefinition.SCOPE_PROTOTYPE)
public class CurrencyFormatter implements Formatter<BigDecimal> {

    @Override
    public String apply(BigDecimal value) {
        return NumberFormat.getCurrencyInstance(Locale.getDefault()).format(value);
    }
}

В XML-дескрипторе экрана пользовательский форматтер используется во вложенном элементе custom:

<valuePicker id="numberPicker" label="Number with CurrencyFormatter">
    <actions>
        <action id="generate" icon="REFRESH"/>
    </actions>
    <formatter>
        <custom bean="currencyFormatter"/>
    </formatter>
</valuePicker>

Форматтер может быть также задан лямбдой и добавлен программно, например:

@ViewComponent
private EntityPicker<Department> entityPicker;

@Subscribe
public void onInit(InitEvent event) {
    entityPicker.setFormatter(value -> value.getName() + " department");
}