Formatter

基本用法

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

Formatter 仅能用于只读组件，比如 文本标签，表格列 等等。对于可编辑的组件值，比如 TextField 应该用 Datatype 机制来格式化。

在界面的 XML 描述中，组件的 formatter 可以在内部的 formatter 元素中定义。

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

下面是为 Table.Column 组件添加 formatter 的示例：

add formatter

框架包含了一组最常用的 formatter 实现，可以直接在项目中使用。

每个 formatter 都是一个 Prototype Bean，如果希望在 Java 代码中使用验证器，需要通过 ApplicationContext 来获取。

使用编程的方式给组件设置 formatter 类，调用组件的 setFormatter() 方法添加 formatter 的实例。

在界面控制器中编程式设置 formatter 类的示例请参阅 数字 formatter。

数字 Formatter

数字 formatter 用于将 Number 值按照特定格式转换为字符串。

支持下列属性：

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

XML 描述中用法：

<table id="ordersTable"
       width="100%"
       dataContainer="ordersDc">
    <columns>
        <column id="amount">
            <formatter>
                <number format="#,##0.00"/>
            </formatter>
        </column>
    </columns>
</table>

Java 代码用法：

@Autowired
protected ApplicationContext applicationContext;

@Autowired
protected Table<Order> ordersTable1;

@Subscribe
protected void onInit(InitEvent event) {
    NumberFormatter formatter = applicationContext.getBean(NumberFormatter.class); (1)
    formatter.setFormat("#,##0.00");
    ordersTable1.getColumn("amount").setFormatter(formatter);
}
1 用 ApplicationContext 获取 NumberFormatter 实例。

日期时间 Formatter

日期 formatter 用于将 Date 值按照特定格式转换为字符串。

支持下列属性：

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

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

  • useUserTimezone - 设置 formatter 是否以当前用户的时区展示日期和时间。默认情况下，DateFormatter 以服务器的时区展示日期和时间。如需显示用户的时区，设置 formatter 的 useUserTimezone 属性为 true。

XML 描述中用法：

<table id="ordersTable"
       width="100%"
       dataContainer="ordersDc">
    <columns>
        <column id="deliveryTime">
            <formatter>
                <date format="h:mm a"/>
            </formatter>
        </column>
    </columns>
</table>

Java 代码用法：

@Autowired
protected ApplicationContext applicationContext;

@Autowired
protected Table<Order> ordersTable1;

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

集合 Formatter

日期 formatter 用于将集合（Collection）按照特定格式转换为字符串，其中多个元素用逗号分隔。

XML 描述中用法：

<table id="customersTable"
       width="100%"
       dataContainer="customersDc">
    <columns>
        <column id="favouriteBrands">
            <formatter>
                <collection/>
            </formatter>
        </column>
    </columns>
</table>

Java 代码用法：

@Autowired
protected ApplicationContext applicationContext;

@Autowired
protected Table<Customer> customersTable;

@Subscribe
protected void onInit(InitEvent event) {
    CollectionFormatter collectionFormatter = applicationContext.getBean(CollectionFormatter.class);
    customersTable.getColumn("favouriteBrands").setFormatter(collectionFormatter);
}

自定义 Formatter

可以自定义 Java 类作为 formatter。需实现 Formatter 接口。

实现一个自定义 formatter：

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

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

在界面 XML 中，自定义 formatter 可以在内部的 custom 元素定义：

<column id="amount">
    <formatter>
        <custom bean="ui_CurrencyFormatter"/>
    </formatter>
</column>

在界面控制器中创建自定义 formatter 的示例：

@Autowired
protected Table<Customer> customersTable;

@Subscribe
protected void onInit(InitEvent event) {
    customersTable.getColumn("age").setFormatter(value -> value + " y.o.");
}