Skip to content

Latest commit

 

History

History
674 lines (613 loc) · 17 KB

gui_validator.adoc

File metadata and controls

674 lines (613 loc) · 17 KB
Raw
验证器控件

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

Warning

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

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

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

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

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

gui validator

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

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

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

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

Tip

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

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

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

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

link:../../../../../../source/gui_vcl/validator_2.java[role=include]

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

link:../../../../../../source/gui_vcl/validator_3.xml[role=include]

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

link:../../../../../../source/gui_vcl/validator_4.java[role=include]

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

DecimalMaxValidator

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

它有如下属性：

  • value − 最大值（必须）；

  • inclusive − 当设置成 true 时，值应当小于或等于指定的最大值。默认值是 true。

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

默认消息键值：

  • validation.constraints.decimalMaxInclusive

  • validation.constraints.decimalMax

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorDecimalMax.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorDecimalMax.java[role=include]
DecimalMinValidator

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

它有如下属性：

  • value − 最小值（必须）；

  • inclusive − 当设置成 true 时，值应当大于或等于指定的最小值。默认值是 true。

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

默认消息键值：

  • validation.constraints.decimalMinInclusive

  • validation.constraints.decimalMin

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorDecimalMin.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorDecimalMin.java[role=include]
DigitsValidator

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

它有如下属性：

  • integer − 整数部分数字的个数（必须）；

  • fraction − 小数部分数字的个数（必须）；

  • message − 自定义的消息，用于在验证失败时展示给用户。该消息可以包含 $value、$integer 和 $fraction 关键字，用于格式化输出。

默认消息键值：

  • validation.constraints.digits

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorDigitsValidator.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorDigitsValidator.java[role=include]
FutureOrPresentValidator

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

它有如下属性：

  • checkSeconds − 当设置成 true 时，验证器需要使用秒和毫秒比较日期或者时间。默认值是 false。

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

默认消息键值：

  • validation.constraints.futureOrPresent

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorFutureOrPresent.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorFutureOrPresent.java[role=include]
FutureValidator

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

它有如下属性：

  • checkSeconds − 当设置成 true 时，验证器需要使用秒和毫秒比较日期或者时间。默认值是 false。

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

默认消息键值：

  • validation.constraints.future

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorFuture.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorFuture.java[role=include]
MaxValidator

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

它有如下属性：

  • value − 最大值（必须）；

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

默认消息键值：

  • validation.constraints.max

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorMax.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorMax.java[role=include]
MinValidator

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

它有如下属性：

  • value − 最小值（必须）；

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

默认消息键值：

  • validation.constraints.min

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorMin.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorMin.java[role=include]
NegativeOrZeroValidator

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

它有如下属性：

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

默认消息键值：

  • validation.constraints.negativeOrZero

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorNegativeOrZero.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorNegativeOrZero.java[role=include]
NegativeValidator

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

它有如下属性：

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

默认消息键值：

  • validation.constraints.negative

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorNegative.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorNegative.java[role=include]
NotBlankValidator

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

它有如下属性：

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

默认消息键值：

  • validation.constraints.notBlank

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorNotBlank.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorNotBlank.java[role=include]
NotEmptyValidator

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

它有如下属性：

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

默认消息键值：

  • validation.constraints.notEmpty

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorNotBlank.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorNotBlank.java[role=include]
NotNullValidator

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

它有如下属性：

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

默认消息键值：

  • validation.constraints.notNull

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorNotNull.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorNotNull.java[role=include]
PastOrPresentValidator

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

它有如下属性：

  • checkSeconds − 当设置为 ture 时，验证器需要使用秒和毫秒比较日期或者时间。默认值是 false。

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

默认消息键值：

  • validation.constraints.pastOrPresent

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorPastOrPresent.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorPastOrPresent.java[role=include]
PastValidator

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

它有如下属性：

  • checkSeconds − 当设置为 ture 时，验证器需要使用秒和毫秒比较日期或者时间。默认值是 false。

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

默认消息键值：

  • validation.constraints.past

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorPastOrPresent.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorPastOrPresent.java[role=include]
PositiveOrZeroValidator

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

它有如下属性：

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

默认消息键值：

  • validation.constraints.positiveOrZero

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorPositiveOrZero.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorPositiveOrZero.java[role=include]
PositiveValidator

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

它有如下属性：

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

默认消息键值：

  • validation.constraints.positive

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorPositive.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorPositive.java[role=include]
RegexpValidator

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

它有如下属性：

  • regexp − 一个用于匹配的正则表达式（必须）；

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

默认消息键值：

  • validation.constraints.regexp

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorRegexp.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorRegexp.java[role=include]
SizeValidator

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

它有如下属性：

  • min − 最小值（不包含），不能小于 0。默认值是 0；

  • max − 最大值（不包含），不能小于 0。默认值是 Integer.MAX_VALUE；

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

默认消息键值：

  • validation.constraints.collectionSizeRange

  • validation.constraints.sizeRange

XML 描述中用法：

link:../../../../../../source/gui_vcl/validatorSize.xml[role=include]

Java 代码用法：

link:../../../../../../source/gui_vcl/validatorSize.java[role=include]