Validator
Validator - 验证器
用来检查可视化组件中输入的值。
需要区分验证和输入检查的不同,输入检查是说:假设一个文本组件(比如,textField)的数据类型设置的不是字符串(这种情况可能出现在绑定实体属性或者手动设置控件的 datatype),那么这个组件会阻止用户输入不符合它定义的数据类型的值。当这个组件失去焦点时或者用户按了回车,会显示验证错误信息。 |
框架包含了一组最常用的验证器实现,可以直接在项目中使用。
在视图的 XML 描述中,组件的验证器可以在内部的 validators
元素中定义。
如需在 Jmix Studio 中添加内部的 validators 元素,可以在视图 XML 或者 Jmix UI 层级结构面板中选择组件或者其内部元素,然后点击 Jmix UI 组件面板的 Add 按钮。
|
下面是给 textField 组件添加验证器的例子:

有些验证器在错误消息中使用了 Groovy 字符串。这样的话,可以给错误消息传递参数(比如,${value}
)。这些参数会考虑用户的 locale 配置。
每个验证器都是一个 Prototype Bean
,如果希望在 Java 代码中使用验证器,需要通过 ApplicationContext
来获取:
PositiveValidator validator = applicationContext.getBean(PositiveValidator.class);
使用编程的方式给组件设置验证类,调用组件的 addValidator()
方法添加验证器的实例。
在视图控制器中编程式设置验证器类的示例:
integerField.addValidator(applicationContext.getBean(PositiveValidator.class));
使用自定义验证器
可以使用自定义的 Java 类作为验证器,自定义类需要实现 Validator
接口。
创建验证邮编的验证器类示例:
@Component("ZipValidator")
@Scope(BeanDefinition.SCOPE_PROTOTYPE)
public class ZipValidator implements Validator<String> {
@Override
public void accept(String value) throws ValidationException {
if (value != null && value.length() != 6)
throw new ValidationException("Zip must be of 6 characters length");
}
}
在视图的 XML 描述中,自定义的验证器可以在内部的 custom
元素中定义。
为 textField
组件使用邮编验证器的示例:
<textField id="zipField" datatype="string">
<validators>
<custom bean="ZipValidator"/>
</validators>
</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
时,值应当小于或等于指定的最大值。设置成false
时,值应当小于指定的最大值。默认值是true
; -
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
和$max
关键字,用于格式化输出。
默认消息键值:
-
validation.constraints.decimalMaxInclusive
; -
validation.constraints.decimalMax
。
布局描述中用法:
<textField id="numberField" datatype="decimal">
<validators>
<decimalMax value="1000"
inclusive="true"
message="Value ${value} cannot be greater than ${max}"/>
</validators>
</textField>
Java 代码用法:
DecimalMaxValidator maxValidator = applicationContext
.getBean(DecimalMaxValidator.class, new BigDecimal(1000));
numberField.addValidator(maxValidator);
DecimalMinValidator
检查值大于等于指定的最小值。支持的类型:BigDecimal
、BigInteger
、Long
、Integer
以及使用当前 locale 表示 BigDecimal
的 String
类型。
支持下列属性:
-
value
- 最小值(必需); -
inclusive
- 当设置成true
时,值应当大于或等于指定的最小值。设置成false
时,值应当大于指定的最小值。默认值是true
; -
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
和$min
关键字,用于格式化输出。
默认消息键值:
-
validation.constraints.decimalMinInclusive
; -
validation.constraints.decimalMin
。
布局描述中用法:
<textField id="decimalField" datatype="decimal">
<validators>
<decimalMin value="100"
inclusive="false"
message="Value ${value} cannot be less than ${min}"/>
</validators>
</textField>
Java 代码用法:
DecimalMinValidator minValidator = applicationContext
.getBean(DecimalMinValidator.class, new BigDecimal(100));
decimalField.addValidator(minValidator);
DigitsValidator
检查值是一个指定范围内的数字。支持的类型:BigDecimal
、BigInteger
、Long
、Integer
以及使用当前 locale 表示 BigDecimal
的 String
类型。
支持下列属性:
-
integer
- 整数部分数字的个数(必需); -
fraction
- 小数部分数字的个数(必需); -
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
、$integer
和$fraction
关键字,用于格式化输出。
默认消息键值:
-
validation.constraints.digits
。
布局描述中用法:
<textField id="digitsField">
<validators>
<digits fraction="2"
integer="3"
message="Value ${value} is out of bounds (${integer}
digits are expected in integer part and ${fraction}
in fractional part)"/>
</validators>
</textField>
Java 代码用法:
DigitsValidator digitsValidator = applicationContext
.getBean(DigitsValidator.class, 3, 2);
digitsField.addValidator(digitsValidator);
DoubleMaxValidator
检查值是否小于或等于指定的最大值。支持的类型:Double
以及使用当前 locale 表示 Double
值的 String
类型。
支持下列属性:
-
value
- 最大值(必需); -
inclusive
- 当设置成true
时,值应当小于或等于指定的最大值。设置成false
时,值应当小于指定的最大值。默认值是true
; -
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
和$max
关键字,用于格式化输出。
默认消息键值:
-
validation.constraints.decimalMaxInclusive
; -
validation.constraints.decimalMax
。
布局描述中用法:
<textField id="doubleMaxField" datatype="double">
<validators>
<doubleMax value="1000"
inclusive="false"
message="Value ${value} cannot be greater than ${max}"/>
</validators>
</textField>
Java 代码用法:
DoubleMaxValidator maxValidator = applicationContext
.getBean(DoubleMaxValidator.class, 1000.0);
doubleMaxField.addValidator(maxValidator);
DoubleMinValidator
检查值大于等于指定的最小值。支持的类型:Double
以及使用当前 locale 表示 Double
值的 String
类型。
支持下列属性:
-
value
- 最小值(必需); -
inclusive
- 当设置成true
时,值应当大于或等于指定的最小值。设置成false
时,值应当大于指定的最小值。默认值是true
; -
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
和$min
关键字,用于格式化输出。
默认消息键值:
-
validation.constraints.decimalMinInclusive
; -
validation.constraints.decimalMin
。
布局描述中用法:
<textField id="doubleMinField" datatype="double">
<validators>
<doubleMin value="100"
inclusive="false"
message="Value ${value} cannot be less than ${min}"/>
</validators>
</textField>
Java 代码用法:
DoubleMinValidator minValidator = applicationContext
.getBean(DoubleMinValidator.class, 100.0);
doubleMinField.addValidator(minValidator);
EmailValidator
检查 String
类型的值是否是电子邮件地址或者包含多个用英文分号、逗号分隔的电子邮件地址。支持类型:String
。
支持下列属性:
-
message
- 自定义的消息,在验证失败时展示。
默认消息键值:
-
validation.invalidEmail
。
布局描述中用法:
<textField id="emailField" datatype="string">
<validators>
<email message="Invalid email address"/>
</validators>
</textField>
Java 代码用法:
EmailValidator emailValidator = applicationContext
.getBean(EmailValidator.class);
emailField.addValidator(emailValidator);
FutureOrPresentValidator
检查日期或时间是否是将来时间或者当前时间。不使用 Groovy 字符串,所以没有参数可用于消息格式化。支持的类型:java.util.Date
、LocalDate
、LocalDateTime
、LocalTime
、OffsetDateTime
、OffsetTime
。
支持下列属性:
-
checkSeconds
- 当设置成true
时,验证器需要使用秒和毫秒比较日期或者时间。默认值是false
; -
message
- 自定义的消息,在验证失败时展示。
默认消息键值:
-
validation.constraints.futureOrPresent
。
布局描述中用法:
<timePicker datatype="localTime" id="futureField">
<validators>
<futureOrPresent checkSeconds="true"/>
</validators>
</timePicker>
Java 代码用法:
FutureOrPresentValidator futureOrPresentValidator = applicationContext
.getBean(FutureOrPresentValidator.class);
futureField.addValidator(futureOrPresentValidator);
FutureValidator
检查日期或时间是否是将来时间。不使用 Groovy 字符串,所以没有参数可用于消息格式化。支持的类型:java.util.Date
、LocalDate
、LocalDateTime
、LocalTime
、OffsetDateTime
、OffsetTime
。
支持下列属性:
-
checkSeconds
- 当设置成true
时,验证器需要使用秒和毫秒比较日期或者时间。默认值是false
; -
message
- 自定义的消息,在验证失败时展示。
默认消息键值:
-
validation.constraints.future
。
布局描述中用法:
<timePicker datatype="localTime" id="timeField">
<validators>
<future checkSeconds="true"/>
</validators>
</timePicker>
Java 代码用法:
FutureValidator futureValidator = applicationContext
.getBean(FutureValidator.class);
timeField.addValidator(futureValidator);
MaxValidator
检查值是否小于或等于指定的最大值。支持的类型:BigDecimal
、BigInteger
、Long
、Integer
。
支持下列属性:
-
value
- 最大值(必需); -
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
和$max
关键字,用于格式化输出。
默认消息键值:
-
validation.constraints.max
。
布局描述中用法:
<textField id="maxField" datatype="int">
<validators>
<max value="20500"
message="Value ${value} must be less than or equal to ${max}"/>
</validators>
</textField>
Java 代码用法:
MaxValidator maxValidator = applicationContext
.getBean(MaxValidator.class, 20500);
maxField.addValidator(maxValidator);
MinValidator
检查值大于等于指定的最小值。支持的类型:BigDecimal
、BigInteger
、Long
、Integer
。
支持下列属性:
-
value
- 最小值(必需); -
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
和$min
关键字,用于格式化输出。
默认消息键值:
-
validation.constraints.min
。
布局描述中用法:
<textField id="minField" datatype="int">
<validators>
<min value="30"
message="Value ${value} must be greater than or equal to ${min}"/>
</validators>
</textField>
Java 代码用法:
MinValidator minValidator = applicationContext
.getBean(MinValidator.class, 30);
minField.addValidator(minValidator);
NegativeOrZeroValidator
检查值小于等于 0。支持的类型:BigDecimal
、BigInteger
、Long
、Integer
、Double
、Float
。
支持下列属性:
-
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
关键字,用于格式化输出。注意,Float
并没有它自己的数据类型,不会使用用户的 locale 进行格式化。
默认消息键值:
-
validation.constraints.negativeOrZero
。
布局描述中用法:
<textField id="negativeOrZeroField" datatype="int">
<validators>
<negativeOrZero message="Value ${value} must be less than or equal to 0"/>
</validators>
</textField>
Java 代码用法:
NegativeOrZeroValidator negativeOrZeroValidator = applicationContext
.getBean(NegativeOrZeroValidator.class);
negativeOrZeroField.addValidator(negativeOrZeroValidator);
NegativeValidator
检查值严格小于 0。支持的类型:BigDecimal
、BigInteger
、Long
、Integer
、Double
、Float
。
支持下列属性:
-
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
关键字,用于格式化输出。注意,Float
并没有它自己的数据类型,不会使用用户的 locale 进行格式化。
默认消息键值:
-
validation.constraints.negative
。
布局描述中用法:
<textField id="negativeField" datatype="int">
<validators>
<negative message="Value ${value} must be less than 0"/>
</validators>
</textField>
Java 代码用法:
NegativeValidator negativeValidator = applicationContext
.getBean(NegativeValidator.class);
negativeField.addValidator(negativeValidator);
NotBlankValidator
检查值至少包含一个非空字符。不使用 Groovy 字符串,所以没有参数可用于消息格式化。支持的类型:String
。
支持下列属性:
-
message
- 自定义的消息,在验证失败时展示。
默认消息键值:
-
validation.constraints.notBlank
。
布局描述中用法:
<textField id="notBlankField">
<validators>
<notBlank message="Value must contain at least one non-whitespace character"/>
</validators>
</textField>
Java 代码用法:
NotBlankValidator notBlankValidator = applicationContext
.getBean(NotBlankValidator.class);
notBlankField.addValidator(notBlankValidator);
NotEmptyValidator
检查值不是 null 也非空。支持的类型:Collection
和 String
。
支持下列属性:
-
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
关键字,用于格式化输出,只对String
类型有效。
默认消息键值:
-
validation.constraints.notEmpty
。
布局描述中用法:
<textField id="notEmptyField">
<validators>
<notEmpty/>
</validators>
</textField>
Java 代码用法:
NotEmptyValidator notEmptyValidator = applicationContext
.getBean(NotEmptyValidator.class);
notEmptyField.addValidator(notEmptyValidator);
NotNullValidator
检查值不是 null。不使用 Groovy 字符串,所以没有参数可用于消息格式化。
支持下列属性:
-
message
- 自定义的消息,在验证失败时展示。
默认消息键值:
-
validation.constraints.notNull
。
布局描述中用法:
<textField id="notNullField">
<validators>
<notNull/>
</validators>
</textField>
Java 代码用法:
NotNullValidator notNullValidator = applicationContext
.getBean(NotNullValidator.class);
notNullField.addValidator(notNullValidator);
PastOrPresentValidator
检查日期或时间是过去时间或者当前时间。不使用 Groovy 字符串,所以没有参数可用于消息格式化。支持的类型:java.util.Date
、LocalDate
、LocalDateTime
、LocalTime
、OffsetDateTime
、OffsetTime
。
支持下列属性:
-
checkSeconds
- 当设置为true
时,验证器需要使用秒和毫秒比较日期或者时间。默认值是false
; -
message
- 自定义的消息,在验证失败时展示。
默认消息键值:
-
validation.constraints.pastOrPresent
。
布局描述中用法:
<datePicker id="pastOrPresentField">
<validators>
<pastOrPresent checkSeconds="true"/>
</validators>
</datePicker>
Java 代码用法:
PastOrPresentValidator pastOrPresentValidator = applicationContext
.getBean(PastOrPresentValidator.class);
pastOrPresentField.addValidator(pastOrPresentValidator);
PastValidator
检查日期或时间是过去时间。不使用 Groovy 字符串,所以没有参数可用于消息格式化。支持的类型:java.util.Date
、LocalDate
、LocalDateTime
、LocalTime
、OffsetDateTime
、OffsetTime
。
支持下列属性:
-
checkSeconds
- 当设置成true
时,验证器需要使用秒和毫秒比较日期或者时间。默认值是false
; -
message
- 自定义的消息,在验证失败时展示。
默认消息键值:
-
validation.constraints.past
。
布局描述中用法:
<datePicker id="pastField">
<validators>
<past/>
</validators>
</datePicker>
Java 代码用法:
PastValidator pastValidator = applicationContext
.getBean(PastValidator.class);
pastField.addValidator(pastValidator);
PositiveOrZeroValidator
检查值大于等于 0。支持的类型:BigDecimal
、BigInteger
、Long
、Integer
、Double
、Float
。
支持下列属性:
-
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
关键字,用于格式化输出。注意,Float
并没有它自己的数据类型,不会使用用户的 locale 进行格式化。
默认消息键值:
-
validation.constraints.positiveOrZero
。
布局描述中用法:
<textField id="positiveOrZeroField" datatype="int">
<validators>
<positiveOrZero message="Value ${value} should be greater than or equal to '0'"/>
</validators>
</textField>
Java 代码用法:
PositiveOrZeroValidator positiveOrZeroValidator = applicationContext
.getBean(PositiveOrZeroValidator.class);
positiveOrZeroField.addValidator(positiveOrZeroValidator);
PositiveValidator
检查值严格大于 0。支持的类型:BigDecimal
、BigInteger
、Long
、Integer
、Double
、Float
。
支持下列属性:
-
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
关键字,用于格式化输出。注意,Float
并没有它自己的数据类型,不会使用用户的 locale 进行格式化。
默认消息键值:
-
validation.constraints.positive
。
布局描述中用法:
<textField id="positiveField" datatype="int">
<validators>
<positive message="Value ${value} should be greater than '0'"/>
</validators>
</textField>
Java 代码用法:
PositiveValidator positiveValidator = applicationContext
.getBean(PositiveValidator.class);
positiveField.addValidator(positiveValidator);
RegexpValidator
检查 String
的值是否能匹配提供的正则表达式。支持的类型:String
。
支持下列属性:
-
regexp
- 一个用于匹配的正则表达式(必需); -
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
关键字,用于格式化输出。
默认消息键值:
-
validation.constraints.regexp
。
布局描述中用法:
<textField id="regexpField">
<validators>
<regexp regexp="[a-z]*"/>
</validators>
</textField>
Java 代码用法:
RegexpValidator regexpValidator = applicationContext
.getBean(RegexpValidator.class,"[a-z]*");
regexpField.addValidator(regexpValidator);
SizeValidator
检查值在一定范围内。支持的类型:Collection
和 String
。
支持下列属性:
-
min
- 最小值(含),不能小于0
。默认值是0
; -
max
- 最大值(含),不能小于0
。默认值是Integer.MAX_VALUE
; -
message
- 自定义的消息,在验证失败时展示。该消息可以包含$value
(只对String
类型有效),$min
、$max
关键字,用于格式化输出。
默认消息键值:
-
validation.constraints.collectionSizeRange
; -
validation.constraints.sizeRange
。
布局描述中用法:
<textField id="sizeField">
<validators>
<size max="10"
min="2"
message="Value ${value} should be between ${min} and ${max}"/>
</validators>
</textField>
<multiSelectComboBox id="sizeComboBox"
itemsEnum="com.company.onboarding.entity.OnboardingStatus">
<validators>
<size max="4"
min="2"
message="Collection size must be between ${min} and ${max}"/>
</validators>
</multiSelectComboBox>
Java 代码用法:
SizeValidator sizeValidator = applicationContext
.getBean(SizeValidator.class);
sizeField.addValidator(sizeValidator);