使用校验框架------蓝凌EKP二次开发资料大全 完整蓝凌二次开发资料 蓝凌 EKP开发实战教程 蓝凌OA二次开发培训资料大全

1. 1. 使用校验框架 

更多资料下载请点-->  蓝凌开发资料大全

EKP产品提供了前端校验框架，使用前端校验框架很简单，步骤如下：

1. 页面引入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"%>

在这个页面会引入校验框架需要的文件。

1. 为需要校验的字段配置校验器，配置的方法是给字段添加validate属性。比如文档的标题不能为空：

<input name="docSubject" class="inputsgl" style="width: 80%;" type="text" validate="required maxLength(200)" subject="主题"/>

校验框架起作用的核心是HTML标签的validate属性，validate配置校验器的名称，多个校验器以空格隔开。上例中的校验器分别是必填、最大长度为200的校验。subject属性为字段的描述名，字段的描述名会在校验失败的提示信息中显示。

1. 开启校验框架

<script> $KMSSValidation(); </script>

1. 1. 校验框架原理

校验框架本质上是写了些内置的校验方法，将需要校验的字段绑定事件来触发校验方法。具体如下：

1. 页面调用校验主函数$KMSSValidation(form, options)，这个函数在plugin.js文件有定义。
2. $KMSSValidation(form, options)主函数定义了校验框架的默认配置参数，并根据配置参数初始化检验框架，默认的配置参数具体如下：

var defaultOpt = {onSubmit: false, immediate: true, onElementFocus: $KMSSValidation_OnElementFocus, getLang: $KMSSValidation_GetLang, msgInsertPoint: $KMSSValidation_GetInsertPoint, msgShowWhere: 'beforeend'};

1. 校验框架初始化过程基本上分为四步：

• 更新配置参数：配置参数定义了校验框架的开关
• 装配内置校验器：校验框架定义了常用的内置校验器，我们可以通过this.addValidators(KMSSValidation.ExtValidator)方法添加扩展的校验器。
• 获取页面需校验的字段：校验框架会获取字段中有validate属性的form字段
• 根据配置参数给字段绑定onSubmit，onBlur事件：根据配置参数中是否绑定onSubmit、onBlur事件的参数来给需要校验的字段绑定事件，事件中触发的是校验器的验证方法，这样需要校验的字段在失去焦点或表单提交的时候就会进行校验。

具体的初始化过程详见validation.js

1. 1. 配置参数介绍

   调用校验主函数$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提醒方式）
  1. 内置校验器介绍

校验器一般包括三个部分：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”
  1. 设置提示信息样式

校验框架不仅提供了自定义校验器验证错误的提示信息方法，也提供了设置提示信息样式的方法。可以给校验字段添加一个名为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标签包括了校验框架的使用，具体介绍如下：

1. 1. 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：校验框架使用的提示信息属性。
  1. 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函数。

1. 1. addValidator函数

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>

1. 1. addValidators函数

当需要扩展多个校验器时，最方便的方式是定义一个校验器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;        }     },     …… }