-
- 使用校验框架
更多资料下载请点--> 蓝凌开发资料大全
EKP产品提供了前端校验框架,使用前端校验框架很简单,步骤如下:
- 页面引入validation.js 、plugin.js和validation.jsp。在EKP中可以使用以下方式引入这这三个文件。
<script type="text/javascript"> Com_IncludeFile("validation.js|plugin.js|validation.jsp "); </script> |
使用modelstry生成的编辑页面头部会默认引入
<%@ include file="/resource/jsp/edit_top.jsp"%> |
在这个页面会引入校验框架需要的文件。
- 为需要校验的字段配置校验器,配置的方法是给字段添加validate属性。比如文档的标题不能为空:
<input name="docSubject" class="inputsgl" style="width: 80%;" type="text" validate="required maxLength(200)" subject="主题"/> |
校验框架起作用的核心是HTML标签的validate属性,validate配置校验器的名称,多个校验器以空格隔开。上例中的校验器分别是必填、最大长度为200的校验。subject属性为字段的描述名,字段的描述名会在校验失败的提示信息中显示。
- 开启校验框架
<script> $KMSSValidation(); </script> |
校验框架本质上是写了些内置的校验方法,将需要校验的字段绑定事件来触发校验方法。具体如下:
- 页面调用校验主函数$KMSSValidation(form, options),这个函数在plugin.js文件有定义。
- $KMSSValidation(form, options)主函数定义了校验框架的默认配置参数,并根据配置参数初始化检验框架,默认的配置参数具体如下:
var defaultOpt = {onSubmit: false, immediate: true, onElementFocus: $KMSSValidation_OnElementFocus, getLang: $KMSSValidation_GetLang, msgInsertPoint: $KMSSValidation_GetInsertPoint, msgShowWhere: 'beforeend'}; |
- 校验框架初始化过程基本上分为四步:
- 更新配置参数:配置参数定义了校验框架的开关
- 装配内置校验器:校验框架定义了常用的内置校验器,我们可以通过this.addValidators(KMSSValidation.ExtValidator)方法添加扩展的校验器。
- 获取页面需校验的字段:校验框架会获取字段中有validate属性的form字段
- 根据配置参数给字段绑定onSubmit,onBlur事件:根据配置参数中是否绑定onSubmit、onBlur事件的参数来给需要校验的字段绑定事件,事件中触发的是校验器的验证方法,这样需要校验的字段在失去焦点或表单提交的时候就会进行校验。
具体的初始化过程详见validation.js
调用校验主函数$KMSSValidation(form, options)时可以传入配置参数,这些配置参数其实是校验框架的开关,灵活的使用配置参数能很好的实现项目的需求。可使用的参数如下:
this.options = { // 绑定onSubmit onSubmit : true, // 校验不通过则停止校验 stopOnFirst : false, // 离开一个验证区域时立即进行验证 immediate : false, // 校验不通过则相关字段获得焦点 focusOnError : true, // 获得相应语言下的信息(多语言) getLang : function(validator) {return validator.error;}, // 指定字段获得焦点 onElementFocus : function(element) {}, // 表单执行校验后事件 afterFormValidate : function(result, form) {return true;}, // 字段执行校验后事件 afterElementValidate : function(result, element) {return true;}, // 错误消息需放置对象 msgInsertPoint : function(element) {return element;}, // 错误消息显示位置 msgShowWhere : 'afterEnd', // 错误信息提醒方式(default:缺省,alert:alert提醒方式) msgShowType : 'default' }; |
- onSubmit:指定校验框架是否绑定onSubmit事件,也就是是否在提交表单时进行校验。Plugin.js中的校验主函数$KMSSValidation(form, options)定义的默认参数中onSubmit属性虽然为false,但是校验器主函数在onSubmit事件队列开头添加了校验器的校验,如下:
var _validation = new KMSSValidation(form, defaultOpt); _validation.addValidators($KMSSValidation.ExtValidator); // 兼容Java产品默认提交表单模式 if (Com_Parameter.event["submit"]) { Com_Parameter.event["submit"].unshift(function() { return _validation.validate(); }); } |
- stopOnFirst:在表单提交时校验框架会根据这个参数进行校验处理。当这个参数为true时,校验框架发现第一个校验不通过的字段后就会停止校验,否则会继续对所有需要校验的字段进行校验。默认情况下这个参数为false。
- immediate:指定校验框架是否绑定onBlur事件。当这个参数为true时,焦点离开字段后会立即触发校验;否则就不会触发校验。默认情况下这个参数为true。
- focusOnError:当校验不通过时设置onElementFocus得到的字段获取焦点。目前只是在form表单提交时校验不通过会把焦点定位到第一个校验不同的字段。如果不需要这个功能可以将这个参数设置为false。注意字段为只读时,即使设置了获取焦点,也是无效的。
- getLang:校验框架支持多语言参数,可以自定义获取校验不通过的提示信息。比如plugin.js中定义的getLang参数:
var defaultOpt = {getLang: $KMSSValidation_GetLang}; function $KMSSValidation_GetLang(validator) { if (typeof($KMSSValidation_Lang) == 'undefined') return validator.error; return $KMSSValidation_Lang[validator.type] || validator.error; }; |
使用校验主函数$KMSSValidation(form, options)获取提示信息的方式是有判断$KMSSValidation_Lang变量,当变量存在时会优先获取变量中定义的提示信息。其中validator.type指的是校验器的类型,不包括参数列表,比如maxLength(length)校验器的类型是maxLength。我们可以看下validation.jsp中$KMSSValidation_Lang变量的定义,框架采用了国际化资源文件定义了校验失败的提示信息。具体定义如下:
$KMSSValidation_Lang = { "required" : "<bean:message key="errors.required" arg0="{name}" />", "number" : "<bean:message key="errors.number" arg0="{name}" />", "date" : "<bean:message key="errors.date" arg0="{name}" />", "email" : "<bean:message key="errors.email" arg0="{name}" />", "maxLength" : "<bean:message key="errors.maxLength" arg0="{name}" arg1="{length}" />", "range" : "<bean:message key="errors.range" arg0="{name}" arg1="{min}" arg2="{max}" />", "min" : "<bean:message key="errors.min" arg0="{name}" arg1="{num}" />", "max" : "<bean:message key="errors.max" arg0="{name}" arg1="{num}" />", "scaleLength" : "<bean:message key="errors.scaleLength" arg0="{name}" arg1="{num}" />" } |
- onElementFocus:与参数focusOnError相关,当focusOnError设置为true时,使用onElementFocus定义的方法设置焦点。
- afterFormValidate:表单执行验证后执行的方法,方法包括两个参数,其中result表示校验是否通过,通过时为true,不通过为false。form指的是表单form。
- afterElementValidate:字段执行校验后会执行的方法,方法参数result指校验是否通过,element指执行校验的表单元素。
- msgInsertPoint:返回放置错误信息的对象,方法参数element传递的是当前校验的表单元素。Plugin.js中的校验主函数$KMSSValidation(form, options)重新定义了这个参数,返回的是包裹当前校验表单元素的td。我们可以自定义这个方法,比如需求是统一将校验消息放在页面最上部,就可以通过这个开关来实现。
- msgShowWhere:指定显示消息的位置,这个位置相对的是msgInsertPoint参数返回的对象。可用参数包括:beforebegin(插入到标签开始前), afterbegin(插入到标签开始标记之后), beforeend(插入到标签结束标记前), afterend(插入到标签结束标记后),具体参数意思不懂的可以参看insertAdjacentHTML方法解释。
- msgShowType:错误消息的提示方式,可用的参数包括default(缺省提示方式)、alert(alert提醒方式)
校验器一般包括三个部分:type(校验类型)、error(验证错误提示信息)、test(验证方法)。以下介绍目前EKP框架内置的校验器。
- required:非空校验
- number:数值校验,包括负数、小数
- digits:正整数校验,不包括空格或其他字符,如点或逗号
- alpha:字母校验,包括大小写字母(a-zA-Z)
- alphanum:字母或数字校验,包括大小写字母(a-zA-Z)或数字(0-9)
- date:日期时间校验,校验格式为“yyyy-MM-dd”、“HH:mm”、“yyyy-MM-dd HH:mm”
- email:有效电子邮件地址校验
- url:url地址校验,url必须以“http://”或“https://”或“ftp://”开头
- currency-dollar:有效货币表示校验,以这些格式[$]1[##][,###]+[.##]、[$]1###+[.##]、[$]0.##、[$].##输入的货币数值有效
- maxLength(length):最大长度校验,长度不能超过设定的最大值,一个中文字符的长度为3
- range(min,max):最大值与最小值区间校验,区间为min <= value && value <= max
- max(num):最大值校验,区间为value <= num
- min(num):最小值校验,区间为value >= num
- scaleLength(num):最大小数位校验,输入的小数位必须小于等于num
- before:时间不能晚于当前时间
- after:时间不能早于当前时间
- __date:日期校验,校验格式为“yyyy-MM-dd”或“MM/dd/yyyy”(多语言情况)
- __time:时间校验,校验格式为“HH:mm”
- __datetime:日期时间校验:校验格式为“yyyy-MM-dd HH:mm”或“MM/dd/yyyy HH:mm”
校验框架不仅提供了自定义校验器验证错误的提示信息方法,也提供了设置提示信息样式的方法。可以给校验字段添加一个名为reminder的属性。此属性为验证错误的提示信息样式。
格式:显示位置 + # + 样式。
显示位置与msgShowWhere参数一致;#为分隔符;样式如***{Msg}***,其中{Msg}会替换成验证错误的提示信息,{Msg}不区分大小写。
例如改变文档标题的显示样式,将提示信息显示在td开始标签之后同时在提示信息前后加3个*号:
<input type="text" name="docSubject" subject="文档标题" validate=" required number" reminder="afterbegin#***{msg}***"><span class="txtstrong">*</span>
实现的效果如图:
- xform标签与校验框架
通过第一章的介绍我们知道校验框架是根据HTML标签的validate属性来进行校验的。不过项目中我们一般不会写HTML标签,更多的是使用我们公司的xform标签。xform标签包括了校验框架的使用,具体介绍如下:
-
- xform标签使用校验框架
xform标签的公共属性中validators、required、subject与校验框架直接相关。
- validators:校验框架使用的属性,值为校验器名,可多值,以空格分隔。注意:当xform标签与数据字典关联时,数据字典没有配置validate="true"时该属性也不生效。具体内容见下文。
<xform:text property="docSubject" subject="文档标题" validators=" required number"/>
输出:
<input type="text" name="docSubject" subject="文档标题" validate=" required number">
- required:是否必填。当设置的值为必填时,会生成非空校验。
<xform:text property="docSubject" subject="文档标题" required ="true"/>
输出:
<input type="text" name="docSubject" subject="文档标题" validate="required"><span class="txtstrong">*</span>
- subject:校验框架使用的提示信息属性。
- xform标签与数据字典
除了显示的使用xform标签的属性来使用校验框架,xform标签还使用了数据字典来生成字段需要的校验器。我们看下标题的数据字典配置:
<simpleProperty name="docSubject" messageKey="example-demo:exampleDemoMain.docSubject" type="String" column="doc_subject" notNull="true" length="200" validate="true" /> |
xform的公共属性isLoadDataDict是控制是否加载数据字典的开关,不配置这个属性的情况下默认为true,也就是需要加载数据字典生成相应的控制。数据字典配置与生成的HTML标签属性对应关系如下:
数据字典配置 | 生成的HTML属性 |
messageKey="…" | subject="通过messageKey找到的 提示信息" |
数据字典配置validate="true"的时候xform标签的validators属性以及下面配置才起作用:
数据字典配置 | 生成的HTML属性 |
notNull="true" | 非空校验:validate="required" |
type="Integer" | 正整数校验:validate="digits" |
type=" Long" 或者type=" Double" | 数值校验:validate="number" |
type=" Date" | 日期校验:validate="__date" |
type=" Time" | 时间校验:validate=" __time" |
type=" DateTime" | 日期时间校验:validate=" __datetime" |
type=" String " 并且length="200" | 最大长度校验:validate=" maxLength(200)" |
另外:数据字典生成的校验器与xform标签属性validators配置的校验器最后是并集关系,所以当数据字典中可以配置的校验还不满足需求时可以使用validators属性配置其他的校验器。
由第一章可知框架内置的校验器都是些常用的校验器,这些校验器能满足大部分项目的需求,当内置的校验器不满足项目需求时,我们可以扩展自己的校验器以满足需求。
校验框架提供了两个外部函数来添加扩展的校验器,分别是添加单个校验器的addValidator函数和添加多个校验器的addValidators函数。
this.addValidator = KMSSValidation_AddValidator; // 添加校验器 function KMSSValidation_AddValidator(type, error, test) { var _validators = {}, _parseArray = this._parseValidatorName(type); var _type = _parseArray.shift(); _validators[_type] = new Validator(_type, error, test, _parseArray); KMSSValidation.extend(this.methods, _validators); }; |
从上面代码我们可知addValidator函数需要传递三个参数,其中type指的是校验器类型,error为校验失败的提示信息,test为校验方法。
- type:校验器类型。以内置校验器举例来说,type参数传递的是:required、number、maxLength(length)。
- error:校验失败提示信息。可以像$KMSSValidation_Lang变量一样使用<bean:message/>标签来支持多语言,注意定义的提示信息中可以包含{name}、{参数},校验框架会自动将subject属性值替换掉{name},具体的参数值替换{参数}。例如maxLength(length)的提示信息为“{name} 不能大于 {length} 英文字符(1个中文字符相当于3个英文字符).”。另外我们也可以在$KMSSValidation_Lang变量中添加我们的校验提示信息,注意里面定义的类型是不包括参数列表的。
- test:校验方法。校验方法返回true表示校验通过,返回false表示校验不通过。校验框架调用校验方法会给传递三个参数,function(v, e, o)其中v表示校验字段的值;e表示校验字段的dom对象;o表示参数对象,参数对象中以json形式封装了参数值。举例来说文档的标题一般会做最大长度校验,一般情况下校验为maxLength(200),当在标题中输入“123”时,触发校验方法时,v值为“123”,e值为“标题字段的<input>的Dom节点”,o值为“{length : 200}”的json对象,在校验方法中使用o[‘length’]可以得到参数值200。
添加单个校验器例子:
<script> var _validation = $KMSSValidation(); _validation.addValidator('maxLength(length)', '{name} 不能大于 {length} 英文字符(1个中文字符相当于3个英文字符).', function(v,e,o){ var length = isNaN(o['length']) ? 0 : parseInt(o['length']); return length == 0 || this.getValidator('isEmpty').test(v) || v.length <= length; }); _validation.addValidator(…); </script> |
当需要扩展多个校验器时,最方便的方式是定义一个校验器json对象并使用addValidators函数添加所有扩展的校验器。最好的例子在plugin.js中,以下摘录部分重要代码:
var _validation = new KMSSValidation(form, defaultOpt); _validation.addValidators($KMSSValidation.ExtValidator); $KMSSValidation.ExtValidator = { 'range(min,max)' : { error : '输入值必须是大于等于 {min},小于等于 {max}。', test : function(v, e, o) { if (this.getValidator('isEmpty').test(v)) return true; if ((!isNaN(v) && !/^\s+$/.test(v))) { var min = isNaN(o['min']) ? 0 : parseFloat(o['min']); var max = isNaN(o['max']) ? 0 : parseFloat(o['max']); var value = parseFloat(v); return (min <= value && value <= max); } return false; } }, 'max(num)' : { error : '输入值必须小于等于 {num}。', test : function(v, e, o) { if (this.getValidator('isEmpty').test(v)) return true; if ((!isNaN(v) && !/^\s+$/.test(v))) { var num = isNaN(o['num']) ? 0 : parseFloat(o['num']); var value = parseFloat(v); return (value <= num); } return false; } }, …… } |