Formatter 格式化器

Formatter - 格式化器 用于将某些值转换成字符串类型展示。

Formatter 仅能用于非编辑组件，比如 valuePicker、multiValuePicker 以及 entityPicker。对于可编辑的组件值，比如 textField 应该用 Datatype 机制来格式化。

框架包含了一组格式化器实现，可以直接在项目中使用。

在视图的 XML 描述中，组件的格式化器可以在内部的 formatter 元素中定义。

如需在 Jmix Studio 中添加内部的 formatter 元素，可以在视图 XML 或者 Jmix UI 层级结构面板中选择组件或者其内部元素，然后点击 Jmix UI 组件面板的 Add 按钮。

下面是为 valuePicker 组件添加格式化器的示例：

add formatter

标准的格式化器都使用 Prototype Bean 定义，如果希望在 Java 代码中创建，需要使用 ApplicationContext 或 ObjectProvider，参考下面的示例。

数字

数字格式化器用于将 Number 值按照特定格式转换为字符串显示。

支持下列属性：

  • 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 值按照特定格式转换为字符串显示。

支持下列属性：

  • format - 用来创建 SimpleDateFormat 实例的格式字符串。该值可以是一个格式字符串或者 消息包 中的键值。

  • type - 格式化器的类型，可取值 DATE 或 DATETIME。因此，会分别使用 DateDatatype 或 DateTimeDatatype 类型对值进行格式化。

  • useUserTimezone - 是否以当前用户的时区展示日期和时间。默认情况下，DateFormatter 以服务器的时区展示日期和时间。如需显示用户的时区，设置该属性为 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）按照多个元素用逗号分隔的格式展示。

创建自定义格式化器

可以自定义一个 prototype bean 的格式化器 Java 类。需实现 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>

格式化器也可以用过 lambda 函数编程式定义，示例：

@ViewComponent
private EntityPicker<Department> entityPicker;

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