验证器控件 - CUBA 框架开发者手册

3.5.2.4.4. 验证器控件

Validator 设计用来检查可视化组件中输入的值。

验证和输入检查是需要区分开来的，输入检查是说：假设一个文本组件（比如，TextField）的数据类型设置的不是字符串（这种情况可能出现在绑定实体属性或者手动设置控件的 datatype ），那么这个组件会阻止用户输入不符合它定义的数据类型的值。当这个组件失去焦点时或者用户按了回车，会显示验证错误信息。

验证不会在输入同时或者失去焦点时马上反馈，而是会在组件的 validate() 方法调用的时候。也就是说这个组件（还有这个组件关联的实体属性）暂时会包含一个可能并不符合验证规则的值。但是这没关系，因为需要验证的字段一般都会在编辑界面，所有的字段提交前会自动调用验证方法。如果组件不在一个编辑界面，那么这个组件的 validate() 方法需要在界面控制器显式的调用。

CUBA 框架包含了一组最常用的验证器实现，可以直接在项目中使用：

在界面的 XML 描述中，组件的验证器可以在嵌套的 validators 元素中定义。

可以通过 CUBA Studio 添加验证器。下面是给 TextField 组件添加验证器的例子：

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

有些验证器在错误消息中使用了 Groovy 字符串。这样的话，可以给错误消息传递参数（比如，$value）。这些参数会考虑用户的 locale 配置。

你可以使用自定义的 Java 类作为验证器，自定义类需要实现 Consumer 接口。

在界面的 XML 描述中，自定义的验证器可以在嵌套的 validator 元素中定义。

如果验证器是作为内部类实现的话，则需要使用 static 进行声明，然后在 XML 中类名用 "$" 分隔，示例：

<validator class="com.sample.sales.gui.AddressEdit$ZipValidator"/>

给组件设置验证类的方法除了 XML 描述之外，也可以使用编程的方式 - 使用组件的 addValidator() 方法添加验证器的实例。

创建验证邮编的验证器类：

public class ZipValidator implements Consumer<String> {
    @Override
    public void accept(String s) throws ValidationException {
        if (s != null && s.length() != 6)
            throw new ValidationException("Zip must be of 6 characters length");
    }
}

在TextField组件中使用邮编验证器的示例：

<textField id="zipField" property="zip">
    <validator class="com.company.sample.web.ZipValidator"/>
</textField>

在界面控制器用编程的方式设置验证器：

zipField.addValidator(value -> {
    if (value != null && value.length() != 6)
        throw new ValidationException("Zip must be of 6 characters length");
});

下面我们看看框架预定义的这些验证器。

DecimalMaxValidator

检查值小于等于指定的最大值。支持的类型：BigDecimal、BigInteger、Long、Integer 以及使用当前 locale 表示 BigDecimal 的 String 类型。

它有如下属性：

value − 最大值（必须）；
inclusive − 当设置成 true 时，值应当小于或等于指定的最大值。默认值是 true。
message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 和 $max 关键字，用于格式化输出。

默认消息键值：

validation.constraints.decimalMaxInclusive
validation.constraints.decimalMax

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <decimalMax value="1000" inclusive="false" message="Value '$value' cannot be greater than `$max`"/>
    </validators>
</textField>

Java 代码用法：

DecimalMaxValidator maxValidator = beanLocator.getPrototype(DecimalMaxValidator.NAME, new BigDecimal(1000));
numberField.addValidator(maxValidator);

DecimalMinValidator

检查值大于等于指定的最小值。支持的类型：BigDecimal、BigInteger、Long、Integer 以及使用当前 locale 表示 BigDecimal 的 String 类型。

它有如下属性：

value − 最小值（必须）；
inclusive − 当设置成 true 时，值应当大于或等于指定的最小值。默认值是 true。
message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 和 $min 关键字，用于格式化输出。

默认消息键值：

validation.constraints.decimalMinInclusive
validation.constraints.decimalMin

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <decimalMin value="100" inclusive="false" message="Value '$value' cannot be less than `$min`"/>
    </validators>
</textField>

Java 代码用法：

DecimalMinValidator minValidator = beanLocator.getPrototype(DecimalMinValidator.NAME, new BigDecimal(100));
numberField.addValidator(minValidator);

DigitsValidator

检查值是一个指定范围内的数字。支持的类型：BigDecimal、BigInteger、Long、Integer 以及使用当前 locale 表示 BigDecimal 的 String 类型。

它有如下属性：

integer − 整数部分数字的个数（必须）；
fraction − 小数部分数字的个数（必须）；
message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value、$integer 和 $fraction 关键字，用于格式化输出。

默认消息键值：

validation.constraints.digits

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <digits integer="3" fraction="2" message="Value '$value' is out of bounds ($integer digits are expected in integer part and $fraction in fractional part)"/>
    </validators>
</textField>

Java 代码用法：

DigitsValidator digitsValidator = beanLocator.getPrototype(DigitsValidator.NAME, 3, 2);
numberField.addValidator(digitsValidator);

DoubleMaxValidator

检查值是否小于或等于指定的最大值。支持的类型：Double 以及表示 Double 值的 `String`类型（使用当前 locale）。

它有如下属性：

value − 最大值（必须）；
inclusive − 当设置为 true 时，值需要小于等于指定的最大值。默认值是 true；
message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 和 $max 关键字，用于格式化输出。

默认消息键值：

validation.constraints.decimalMaxInclusive
validation.constraints.decimalMax

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <doubleMax value="1000" inclusive="false" message="Value '$value' cannot be greater than `$max`"/>
    </validators>
</textField>

Java 代码用法：

DoubleMaxValidator maxValidator = beanLocator.getPrototype(DoubleMaxValidator.NAME, new Double(1000));
numberField.addValidator(maxValidator);

DoubleMinValidator

检查值是否大于或等于指定的最大值。支持的类型：Double 以及表示 Double 值的 `String`类型（使用当前 locale）。

它有如下属性：

value − 最小值（必须）；
inclusive − 当设置为 true 时，值需要大于等于指定的最大值。默认值是 true；
message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 和 $min 关键字，用于格式化输出。

默认消息键值：

validation.constraints.decimalMinInclusive
validation.constraints.decimalMin

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <doubleMin value="100" inclusive="false" message="Value '$value' cannot be less than `$min`"/>
    </validators>
</textField>

Java 代码用法：

DoubleMinValidator minValidator = beanLocator.getPrototype(DoubleMinValidator.NAME, new Double(100));
numberField.addValidator(minValidator);

FutureOrPresentValidator

检查日期或时间是否在将来或者现在。它不使用 Groovy 字符串，所以没有参数可用于消息格式化。支持的类型：java.util.Date、LocalDate、LocalDateTime、LocalTime、OffsetDateTime、OffsetTime。

它有如下属性：

checkSeconds − 当设置成 true 时，验证器需要使用秒和毫秒比较日期或者时间。默认值是 false。
message − 自定义的消息，用于在验证失败时展示给用户。

默认消息键值：

validation.constraints.futureOrPresent

XML 描述中用法：

<dateField id="dateTimePropertyField" property="dateTimeProperty">
    <validators>
        <futureOrPresent checkSeconds="true"/>
    </validators>
</dateField>

Java 代码用法：

FutureOrPresentValidator futureOrPresentValidator = beanLocator.getPrototype(FutureOrPresentValidator.NAME);
dateField.addValidator(futureOrPresentValidator);

FutureValidator

它验证时间或者日期必须在将来。它不使用 Groovy 字符串，所以没有参数可用于消息格式化。支持的类型：java.util.Date、LocalDate、LocalDateTime、LocalTime、OffsetDateTime、OffsetTime。

它有如下属性：

checkSeconds − 当设置成 true 时，验证器需要使用秒和毫秒比较日期或者时间。默认值是 false。
message − 自定义的消息，用于在验证失败时展示给用户。

默认消息键值：

validation.constraints.future

XML 描述中用法：

<timeField id="localTimeField" property="localTimeProperty" showSeconds="true">
    <validators>
        <future checkSeconds="true"/>
    </validators>
</timeField>

Java 代码用法：

FutureValidator futureValidator = beanLocator.getPrototype(FutureValidator.NAME);
timeField.addValidator(futureValidator);

MaxValidator

检查值小于或等于指定的最大值。支持的类型：BigDecimal、BigInteger、Long、Integer。

它有如下属性：

value − 最大值（必须）；
message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 和 $max 关键字，用于格式化输出。

默认消息键值：

validation.constraints.max

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <max value="20500" message="Value '$value' must be less than or equal to '$max'"/>
    </validators>
</textField>

Java 代码用法：

MaxValidator maxValidator = beanLocator.getPrototype(MaxValidator.NAME, 20500);
numberField.addValidator(maxValidator);

MinValidator

检查值大于等于指定的最小值。支持的类型：BigDecimal、BigInteger、Long、Integer。

它有如下属性：

value − 最小值（必须）；
message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 和 $min 关键字，用于格式化输出。

默认消息键值：

validation.constraints.min

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <min value="30" message="Value '$value' must be greater than or equal to '$min'"/>
    </validators>
</textField>

Java 代码用法：

MinValidator minValidator = beanLocator.getPrototype(MinValidator.NAME, 30);
numberField.addValidator(minValidator);

NegativeOrZeroValidator

检查值小于等于 0。支持的类型：BigDecimal、BigInteger、Long、Integer、Double、Float。

它有如下属性：

message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 关键字，用于格式化输出。注意，Float 并没有它自己的数据类型，不会使用用户的 locale 进行格式化。

默认消息键值：

validation.constraints.negativeOrZero

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <negativeOrZero message="Value '$value' must be less than or equal to 0"/>
    </validators>
</textField>

Java 代码用法：

NegativeOrZeroValidator negativeOrZeroValidator = beanLocator.getPrototype(NegativeOrZeroValidator.NAME);
numberField.addValidator(negativeOrZeroValidator);

NegativeValidator

检查值严格小于 0。支持的类型：BigDecimal、BigInteger、Long、Integer、Double、Float。

它有如下属性：

message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 关键字，用于格式化输出。注意，Float 并没有它自己的数据类型，不会使用用户的 locale 进行格式化。

默认消息键值：

validation.constraints.negative

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <negative message="Value '$value' should be less than 0"/>
    </validators>
</textField>

Java 代码用法：

NegativeValidator negativeValidator = beanLocator.getPrototype(NegativeValidator.NAME);
numberField.addValidator(negativeValidator);

NotBlankValidator

检查值至少包含一个非空字符。它不使用 Groovy 字符串，所以没有参数可用于消息格式化。支持的类型：String。

它有如下属性：

message − 自定义的消息，用于在验证失败时展示给用户。

默认消息键值：

validation.constraints.notBlank

XML 描述中用法：

<textField id="textField" property="textProperty">
    <validators>
        <notBlank message="Value must contain at least one non-whitespace character"/>
    </validators>
</textField>

Java 代码用法：

NotBlankValidator notBlankValidator = beanLocator.getPrototype(NotBlankValidator.NAME);
textField.addValidator(notBlankValidator);

NotEmptyValidator

检查值不是 null 也非空。支持的类型：Collection 和 String。

它有如下属性：

message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 关键字，用于格式化输出，只对 String 类型有效。

默认消息键值：

validation.constraints.notEmpty

XML 描述中用法：

<textField id="textField" property="textProperty">
    <validators>
        <notBlank message="Value must contain at least one non-whitespace character"/>
    </validators>
</textField>

Java 代码用法：

NotBlankValidator notBlankValidator = beanLocator.getPrototype(NotBlankValidator.NAME);
textField.addValidator(notBlankValidator);

NotNullValidator

检查值不是 null。它不使用 Groovy 字符串，所以没有参数可用于消息格式化。

它有如下属性：

message − 自定义的消息，用于在验证失败时展示给用户。

默认消息键值：

validation.constraints.notNull

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <notNull/>
    </validators>
</textField>

Java 代码用法：

NotNullValidator notNullValidator = beanLocator.getPrototype(NotNullValidator.NAME);
numberField.addValidator(notNullValidator);

PastOrPresentValidator

检查时间或者日期在过去或者现在。它不使用 Groovy 字符串，所以没有参数可用于消息格式化。支持的类型：java.util.Date、LocalDate、LocalDateTime、LocalTime、OffsetDateTime、OffsetTime。

它有如下属性：

checkSeconds − 当设置为 ture 时，验证器需要使用秒和毫秒比较日期或者时间。默认值是 false。
message − 自定义的消息，用于在验证失败时展示给用户。

默认消息键值：

validation.constraints.pastOrPresent

XML 描述中用法：

<dateField id="dateTimeField" property="dateTimeProperty">
    <validators>
        <pastOrPresent/>
    </validators>
</dateField>

Java 代码用法：

PastOrPresentValidator pastOrPresentValidator = beanLocator.getPrototype(PastOrPresentValidator.NAME);
numberField.addValidator(pastOrPresentValidator);

PastValidator

检查时间或者日期在过去。它不使用 Groovy 字符串，所以没有参数可用于消息格式化。支持的类型：java.util.Date、LocalDate、LocalDateTime、LocalTime、OffsetDateTime、OffsetTime。

它有如下属性：

checkSeconds − 当设置为 ture 时，验证器需要使用秒和毫秒比较日期或者时间。默认值是 false。
message − 自定义的消息，用于在验证失败时展示给用户。

默认消息键值：

validation.constraints.past

XML 描述中用法：

<dateField id="dateTimeField" property="dateTimeProperty">
    <validators>
        <pastOrPresent/>
    </validators>
</dateField>

Java 代码用法：

PastOrPresentValidator pastOrPresentValidator = beanLocator.getPrototype(PastOrPresentValidator.NAME);
numberField.addValidator(pastOrPresentValidator);

PositiveOrZeroValidator

检查值大于等于 0。支持的类型：BigDecimal、BigInteger、Long、Integer、Double、Float。

它有如下属性：

message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 关键字，用于格式化输出。注意，Float 并没有它自己的数据类型，不会使用用户的 locale 进行格式化。

默认消息键值：

validation.constraints.positiveOrZero

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <positiveOrZero message="Value '$value' should be greater than or equal to '0'"/>
    </validators>
</textField>

Java 代码用法：

PositiveOrZeroValidator positiveOrZeroValidator = beanLocator.getPrototype(PositiveOrZeroValidator.NAME);
numberField.addValidator(positiveOrZeroValidator);

PositiveValidator

检查值严格大于 0。支持的类型：BigDecimal、BigInteger、Long、Integer、Double、Float。

它有如下属性：

message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 关键字，用于格式化输出。注意，Float 并没有它自己的数据类型，不会使用用户的 locale 进行格式化。

默认消息键值：

validation.constraints.positive

XML 描述中用法：

<textField id="numberField" property="numberProperty">
    <validators>
        <positive message="Value '$value' should be greater than '0'"/>
    </validators>
</textField>

Java 代码用法：

PositiveValidator positiveValidator = beanLocator.getPrototype(PositiveValidator.NAME);
numberField.addValidator(positiveValidator);

RegexpValidator

检查 String 的值是否能匹配提供的正则表达式。支持的类型：String。

它有如下属性：

regexp − 一个用于匹配的正则表达式（必须）；
message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value 关键字，用于格式化输出。

默认消息键值：

validation.constraints.regexp

XML 描述中用法：

<textField id="textField" property="textProperty">
    <validators>
        <regexp regexp="[a-z]*"/>
    </validators>
</textField>

Java 代码用法：

RegexpValidator regexpValidator = beanLocator.getPrototype(RegexpValidator.NAME, "[a-z]*");
textField.addValidator(regexpValidator);

SizeValidator

检查值在一定范围内。支持的类型：Collection 和 String。

它有如下属性：

min − 最小值（不包含），不能小于 0。默认值是 0；
max − 最大值（不包含），不能小于 0。默认值是 Integer.MAX_VALUE；
message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value（只对 String 类型有效），$min、$max 关键字，用于格式化输出。

默认消息键值：

validation.constraints.collectionSizeRange
validation.constraints.sizeRange

XML 描述中用法：

<textField id="textField" property="textProperty">
    <validators>
        <size min="2" max="10" message="Value '$value' should be between '$min' and '$max'"/>
    </validators>
</textField>

<twinColumn id="twinColumn">
    <validators>
        <size min="2" max="4" message="Collection size must be between $min and $max"/>
    </validators>
</twinColumn>

Java 代码用法：

SizeValidator sizeValidator = beanLocator.getPrototype(SizeValidator.NAME);
textField.addValidator(sizeValidator);