# 引用对象
动态执行上下文中封装的引用对象分为字段对象、重复节表对象、视图对象、根对象四种,这四种对象上各自封装了不同的属性和方法供动态中使用。
# 字段对象
表单控件的对象分为字段对象和重复节表对象,这两种对象的属性和方法封装有所不同。
在动态配置中您可以使用$fieldXXX.control引用字段对象,也可以在设置在字段上的动态脚本中使用this直接引用本字段对象。
字段对象上封装的属性和方法如下:
# 属性
- permission 字段权限,和流程编辑器中勾选的权限相一致
- readable 是否可读
- writable 是否可写
# 通用方法
字段对象中封装了一些通用方法供动态脚本中使用,这些方法是所有渲染类型的控件的字段对象中都有的。
方法 | 描述 |
---|---|
val | 取值或设置值 |
attr | 取属性或设置属性 |
css | 取样式或设置样式 |
style | 功能同动态样式style |
cellStyle | 功能同动态样式cellStyle |
rowStyle | 功能同动态样式rowStyle |
validate | 执行验证,包括非空验证,正则验证,动态验证 |
visible | 功能同动态动作visible |
rowVisible | 功能同动态动作rowVisible |
colVisible | 功能同动态动作colVisible |
tableVisible | 功能同动态动作tableVisible |
dataSource | 功能同动态动作dataSource |
readOnly | 功能同动态动作readOnly |
tooltip | 功能同动态动作tooltip |
setNotNullMark | 功能同动态动作notNullMark |
clearNotNullMark | 清除动态非空标记 |
showPrompt | 在控件上显示提示气泡,功能上类似动态验证,但区别是动态验证会在表单提交时自动执行 |
hidePrompt | 隐藏控件上的提示气泡 |
focus | 控件获得焦点 |
blur | 控件失去焦点 |
highlight | 高亮控件 |
placeholder | 控件输入提示 |
parent | 获取或者设置控件的父亲值,功能同在字段上设置Parent属性 |
registerValidation | 注册验证 |
scrollIntoView | 滚动到控件位置 |
# val([value, options])
取值或者设置值。当value参数不传就是取值,value参数传了就是设置值。options是选项对象,支持的选项如下:
选项名 | 缺省值 | 描述 |
---|---|---|
highlight | true | 改动值的同时是否高亮字段控件 |
force | false | 是否强制更新,缺省表单初始化时调用val方法设置值是无效的(原因见注意事项),如果想通过val设置初值,需要使force为true |
val方法有以下几个注意事项
- 取出来的值不会带有属性,取属性请使用attr()方法
- 设置值的时候需要注意值的数据类型要匹配,例如当设置Code,User,Organize时需要设置{value,displayValue}的数据结构,设置date,datetime时需要设置unix时间戳,设置integer、double时需要设置数值类型
- 清空值可以使用val(null)或者val(""),如果是Code,User,Organize类型用val({value:"",displayValue:""})也是可以的
- val方法设置值一般不可用于设置初值,因为用val设置初值会忽略表单上原先已经存在的值(用户提交的信息或者保存的字段信息),通常意义上这么做是错误的,除非一些特殊场景下也许才是正确的,所以用val设置初值请充分考虑不使用字段上设置初值而一定要用val方法设置初值的理由。如果一定要用val设置初值,那么请使用force选项参数,例如:this.val('init value',{force:true})可设置字段值为"init value"。如果这个字段还被其他字段的动态所依赖,那么为了让初始化时候正确执行动态,需要将这个设置初值的脚本放到根对象的全局初始化脚本中,因为初始化脚本会在其他动态执行之前执行,从而保证了其他动态执行时依赖字段的值的正确性。
// 动态脚本设置在fieldEdit(String数据类型)上,取fieldUser的值(User数据类型),并且将用户名设置在fieldEdit上,触发字段列表填$fieldUser
// 注意使用val方法时应避免初始化时候使用
if (!$INIT) {
this.val($fieldUser.control.val().name);
}
2
3
4
5
// 动态脚本设置在fieldLabel(Organize数据类型)上,在fieldOption(string类型的Option类型)字段为'1'时设置fieldLabel值为网络信息中心
// 否则清空fieldLabel,触发字段列表填$fieldOption
// 注意使用val方法时应避免初始化时候使用
if (!$INIT) {
if($fieldOption==='1') {
// 由于数据类型为Organize,所以设置值时需要提供value和displayValue,User以及Code类型都是相同的数据结构
this.val({value:"40100",displayValue:"网络信息中心"});
} else {
// 以下三句清空对于Code、User、Organize数据类型是等价的
this.val(null);
this.val("");
this.val({value:"",displayValue:""});
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
// 动态脚本设置在fieldLabel(datetime数据类型)上,在fieldOption(string类型的Option类型)字段不为'1'时设置fieldLabel值为当前时间
// 否则清空fieldLabel,触发字段列表填$fieldOption
// 注意使用val方法时应避免初始化时候使用
if (!$INIT) {
if($fieldOption==='1') {
// 由于数据类型为datetime,所以设置时候需要设置一个unix时间戳
this.val(floor((new Date()).getTime()/1000));
} else {
this.val("");
}
}
2
3
4
5
6
7
8
9
10
11
// 如果没有其他动态依赖这个初值,那么可以将设置初值的脚本放到字段脚本上
this.val('init value',{force:true});
2
// 如果设置初值的字段还被其他动态依赖,那么可以将设置初值的脚本放到根对象的初始化脚本中
$fieldInit.control.val('init value',{force:true});
2
# attr([name, value])
取属性或者设置属性。name参数未传递时就是取所有属性;name参数传递时value参数不传就是取name参数指定的属性,value参数传了就是设置name参数指定的属性。
// 获取用户学工号
this.val($fieldUser.control.attr("userCode"));
2
# css(name[, value])
取样式或者设置样式。name参数必填,value参数传了就是设置name参数指定名称的样式,value参数不传就是获取name参数指定名称的样式。
// 设置背景色为灰色
this.css("background-color","gray");
2
# style(name[, value])
设置样式。当value参数不为空时等同于css方法设置样式;当value参数为空只有name参数时,name参数可以是个样式对象,例如{color:"red",background:"green"},也可以是个样式字符串,例如"color:red;background:green",style方法可根据这个name参数设置样式。
// 设置背景色为灰色,前景色为红色
this.style({"color":"red","background-color":"gray"});
2
# cellStyle(name[, value])
设置所在格子的样式,功能等同于动态样式cellStyle。name和value参数都传递时表示在格子上设置name参数指定的样式值value;当只有name参数时同样name参数可以是个样式对象,或者样式字符串,根据name参数设置格子样式。
# rowStyle(name[, value])
设置所在行的样式,功能等同于动态样式rowStyle。name和value参数都传递时表示在行上设置name参数指定的样式值value;当只有name参数时同样name参数可以是个样式对象,或者样式字符串,根据name参数设置行样式。
# validate()
执行验证,包括非空验证,正则验证,动态验证。
# visible(isVisible)
执行动态visible,参数isVisible表示设置是否可见
# rowVisible(isVisible[, expandType, level])
执行动态rowVisible,参数isVisible表示设置是否可见,参数expandType表示扩展方向,参数level表示扩展层数,详细介绍参见动态rowVisible部分的说明
// 控件所在行以及上一行不可见
this.rowVisible(false,'up',2);
2
# colVisible(isVisible)
执行动态colVisible,参数isVisible表示设置是否可见
# tableVisible(isVisible)
执行动态tableVisible,参数isVisible表示设置是否可见
# dataSource(dataSource[, useFirstAsDefault])
执行动态dataSource,参数dataSource为数据源,参数useFirstAsDefault表示是否选中第一项,其详细介绍参见动态dataSource部分的说明。dataSource参数可以是一个回车分隔的字符串,也可以是一个代码对象的数组。
代码对象数据结构
字段名 | 说明 |
---|---|
code | 代码值 |
name | 代码名称(显示值) |
value | 代码值,code的别名 |
displayValue | 代码名称(显示值),name的别名 |
enabled | 是否可用,缺省true |
parentId | 父亲值 |
attributes | 属性map |
// 设置数据源为用户字段的部门属性,缺省选中第一个
this.dataSource($fieldUser.indepOrganize,true);
// 设置数据源为A B C三个选项
this.dataSource("A\nB\nC");
// 设置数据源为组装的代码,假设表单上有一个重复表,包含fieldCode,fieldName两个字段,以下脚本可根据用户填的值组装数据源
var datasource =[];
if($fieldCode!=null && $fieldCode.length>0){
for(var i=0,len=$fieldCode.length;i<len;i++){
datasource.push({
value:$fieldCode[i],
displayValue:$fieldName[i],
attributes:{index:i+1}
});
}
}
this.dataSource(datasource);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# readOnly(isReadOnly)
设置动态readonly,isReadOnly参数表示是否只读
# tooltip(tooltip)
设置动态tooltip,参数tooltip为提示信息
# setNotNullMark(content[, type, style])
设置动态非空提示,参数content为提示内容,type是提示位置类型(类型取值参见动态notNullMark),style为提示的样式
// 设置位置为自动,样式为蓝色,提示内容为#
this.setNotNullMark('#','auto','color:blue');
2
# clearNotNullMark()
清除动态非空提示,使用该方法的效果与setNotNullMark('')的效果是一致的
# showPrompt(text[, type, position])
在控件上显示提示气泡,text是提示信息,type是类型(可取值warning,info,success,danger,pass),position是气泡位置(可取值topLeft,topRight,bottomLeft,bottomRight)。type参数缺省danger,position参数缺省topRight。
这个方法可以完成类似动态验证的功能,在验证不通过时在控件上气泡提示出错信息,但不同点在于动态验证会在表单提交时自动执行。
# hidePrompt()
隐藏控件上的提示气泡
if (!$INIT) {
if ( this.value === '' ) {
this.showPrompt('请选择');
return;
}
if (this.value==='1') {
this.showPrompt('请勿选择该项','warning','topLeft');
return;
}
this.hidePrompt();
}
2
3
4
5
6
7
8
9
10
11
# focus()
控件获得焦点
# blur()
控件失去焦点
# highlight()
高亮控件,产生闪烁效果
# placeholder([value])
设置控件的输入提示信息,当参数value不传时代表着将placeholder恢复为字段上的Placeholder属性设置内容,value参数有值时代表设置提示为该值
支持动态设置placeholder的控件包括Edit、Textarea、RichText、Remark、Date、Time、Suggester、Suggester2、Select、File、Thing、Button、LinkButton、Check,其中Button、LinkButton、Check的placeholder是点击后的确认提示信息。
// 将控件placeholder设置为提示信息
this.placeholder('提示信息');
// 清空控件placeholder
this.placeholder('');
// 恢复控件placeholder到字段上的PlaceHolder静态配置,如果PlaceHolder未配置就清空提示
this.placeholder();
2
3
4
5
6
# parent([value])
设置控件的父亲值,作用等同于设置字段的Parent属性,主要用于Code数据类型的控件(CheckList、OptionList、Select、Suggester2等)过滤数据。设置Parent属性只能设置到某个字段,用parent方法可以根据表单上多个用户填值来设置父亲值,可以避免再增加额外的父亲字段和动态公式配置。当参数不传递时可获取当前父亲值,当参数为null或者空字串时表示去除父亲设置。
// 在控制台打印当前父亲值
console.log(this.parent());
// 将本控件父亲值设置为001
this.parent('001');
// 去除本控件的父亲值设置
this.parent(null);
2
3
4
5
6
# registerValidation(fn)
在控件上注册验证函数fn,该函数可返回验证不通过时的提示信息,如果返回空字符串或者不返回内容表示验证通过。注册的验证函数会在该控件失去焦点时、函数依赖的其他表单字段值改变时以及提交等时机调用。注意同一个字段上只能注册一次验证脚本,多次注册的话以最后注册的为准。
字段验证函数可在该字段脚本中注册,脚本依赖字段列表为空,这样可以避免多次注册。
验证函数返回不通过时的提示信息有2种格式,可以是一个字符串,也可以是一个字符串的数组表示多行提示,当然如果多行提示也可以用一个字符串返回中间用回车符分隔。
验证函数中的this指向的是注册验证脚本的那个字段控件对象引用。
// 该段脚本放到fieldF1的script上,验证fieldF1不能为0
this.registerValidation(function() {
if (this.val() === 0) {
return '不能为0';
}
});
2
3
4
5
6
this.registerValidation(function() {
var result=[];
if(this.val()>100){
result.push('大于100');
}
if(this.val()>2*$fieldF2){
result.push('超过f2一倍');
}
if(this.val()>$fieldF1){
result.push('超过f1');
}
return result;
});
2
3
4
5
6
7
8
9
10
11
12
13
14
# scrollIntoView([time])
在控件可见时控制页面滚动到控件的位置,参数time是滚动时间(单位毫秒,缺省不填是200毫秒),如果是0表示立即滚动到该位置。注意该方法对普通控件、重复控件、视图都有效。
if(!$INIT) {
if($fieldShowView) {
$VIEWS['审核'].scrollIntoView(1000);
} else {
if(this.val()===true) {
$fieldControl.control.scrollIntoView();
} else {
$groupRepeat.scrollIntoView(0);
}
}
}
2
3
4
5
6
7
8
9
10
11
# 控件方法Exposed Functions
通用方法是所有控件类型的字段对象中都有的,对于不同的控件也会根据需求暴露出不同的方法供动态脚本中调用,这些方法是不同类型控件所独有的,也被称之为暴露方法(Exposed Functions)。在此列出所有控件方法和简要描述,详细的文档请参阅以下链接中各控件文档的说明。
控件 | 方法 | 描述 |
---|---|---|
Check | checkLabel | 设置勾选标签 |
Check | check | 选中 |
Check | uncheck | 不选中 |
Check | toggle | 切换选中状态 |
CheckButton | check | 选中 |
CheckButton | uncheck | 不选中 |
CheckButton | toggle | 切换选中状态 |
CheckList | check | 选中指定值 |
CheckList | uncheck | 不选中指定值 |
CheckList | checkAll | 全选 |
CheckList | uncheckAll | 全不选 |
CheckList | disable | 禁用 |
CheckList | enable | 启用 |
Option | check | 选中指定值 |
Option | uncheck | 不选中指定值 |
OptionList | check | 选中指定值 |
OptionList | uncheck | 不选中指定值 |
OptionList | disable | 禁用 |
OptionList | enable | 启用 |
Hidden | startLocating | 开启定位功能 |
Hidden | stopLocating | 关闭定位功能 |
Date | min | 设置最小可选日期 |
Date | max | 设置最大可选日期 |
Date | range | 设置可选日期范围 |
Suggester2 | dropdownAutoWidth | 设置下拉选项列表自动宽度 |
# 重复节表对象
您可以直接使用$groupXXX引用重复节表对象,也可以在设置在重复节表上的动态脚本中使用this引用本重复节表对象。
# 属性
目前重复节表对象上可以使用以下属性:
- count 重复节表当前行数
- permission 字段权限,和流程编辑器中勾选的权限相一致
# 方法
重复节表对象中封装了一些通用方法供动态脚本中使用
方法 | 描述 |
---|---|
validate | 重复节表内所有控件执行验证,包括非空验证,正则验证,动态验证 |
readOnly | 功能同动态动作readOnly |
visible | 功能同动态动作visible |
rowVisible | 功能同动态动作rowVisible |
colVisible | 功能同动态动作colVisible |
tableVisible | 功能同动态动作tableVisible |
itemVisible | 功能同动态动作itemVisible |
itemReadOnly | 功能同动态动作itemReadOnly |
itemStyle | 功能同动态样式itemStyle |
addRow | 新增数据行 |
removeRow | 删除数据行 |
scrollIntoView | 滚动到重复节表位置 |
# readOnly(add [, remove, move] )
执行重复节表的动态readOnly,如果只有一个参数会设置重复节表总体只读,如果传三个参数就分别设置是否能新增、删除、移动。
// 设置只读(增删移)
this.readOnly(true);
// 设置可删、不可增、不可移动
this.readOnly(true,false,true);
2
3
4
5
# itemVisible(isVisible, index)
执行动态itemVisible,参数isVisible表示设置是否可见,参数index表示表示行序号(从0开始)。
// 触发字段列表填$fieldCheck,脚本内容如下
for(var i=0,length=$fieldCheck.length;i<length;i++) {
this.itemVisible($fieldCheck[i]===true,i);
}
2
3
4
值得注意的是,在重复节表删除时会出现重复节表中的字段项值为undefined的情况,其实这就是被删除的那行数据,在循环过程中注意判断,不判断容易引起脚本错误。
for(var i=0,length=$fieldText.length;i<length;i++) {
if($fieldText[i]!==undefined){
this.itemVisible($fieldText[i].charAt(0)==='a',i);
}
}
2
3
4
5
# itemReadOnly(isReadOnly, index)
执行动态itemReadOnly,参数isReadOnly表示设置是否只读,参数index表示行序号(从0开始)。
# itemStyle(style, index)
执行动态itemStyle,参数style可以直接是样式字串,也可以是个样式对象,参数index表示行序号(从0开始)。
for(var i=0,length=$fieldCheck.length;i<length;i++) {
if($fieldCheck[i]!==undefined) {
if($fieldCheck[i]===true) {
this.itemStyle("background-color:gray",i);
} else {
this.itemStyle({"background-color":"white"},i);
}
}
}
2
3
4
5
6
7
8
9
# addRow([index] [,data])
在index参数指定的位置新增data参数指定数据的行,index以0为第一行,不指定时加入到最后一行,data可不指定表示空行数据,data指定时可按照{fieldName:fieldValue}的格式给值。对于Code,User,Organize类型可用{value,displayValue}格式赋值,也可按这里关于动态值属性的描述赋值,对于日期类型可按"yyyy-MM-dd"格式赋值。
$groupRepeat.addRow(); // 在末尾新增一个空行
$groupRepeat.addRow(0); // 在第一行位置新增一个空行
// 在第二行位置新增一行数据
$groupRepeat.addRow(1, {
fieldA:"a",
fieldB:"b",
fieldDate:"2020-01-01",
fieldCode1:{value:"01",displayValue:"类型1"},
fieldCode2:{code:"02",name:"类型2"},
fieldUser:{account:"tester",name:"测试员"},
fieldOrg:{code:"40100",name:"网络信息中心"}
});
$groupRepeat.addRow({fieldA:"a",fieldB:"b"}); // 在末尾新增一行数据
2
3
4
5
6
7
8
9
10
11
12
13
# removeRow(index)
删除index参数指定的行,以0为第一行
# 视图对象
您可以使用$VIEWS['视图名']来使用视图对象。
# 属性
目前视图对象上可以使用以下属性:
- name 视图名称
# 方法
视图对象中封装了一些通用方法供动态脚本中使用
方法 | 描述 |
---|---|
validate | 视图内所有控件执行验证,包括非空验证,正则验证,动态验证 |
visible | 功能同动态动作visible |
titleVisible | 功能同动态动作titleVisible |
scrollIntoView | 滚动到视图位置 |
# titleVisible(isVisible)
执行动态titleVisible,参数isVisible表示设置是否可见,注意这个动态只对移动端有效。
# 根对象
您可以通过$GLOBAL使用根对象,在设置在根对象的动态脚本中也可以用this引用根对象。
# 属性
根对象中封装一些属性供表达式中使用,目前可以使用以下对象属性:
- views 所有的视图对象map,可通过views['视图名']来引用到视图对象,views上封装了titleVisible方法用于统一设置所有视图是否移动端标题栏可见
// 将审核视图设置隐藏
this.views['审核'].visible(false);
// 将所有视图设置移动端标题栏不可见
this.views.titleVisible(false);
2
3
4
5
# 方法
根对象中封装了一些通用方法供动态脚本中使用
方法 | 描述 |
---|---|
getView | 获取视图对象引用 |
defineGlobalFunction | 定义全局函数,建议在根对象动态脚本中使用 |
defineGlobalVariable | 定义全局变量,建议在根对象动态脚本中使用 |
removeGlobalVariable | 移除全局变量,可在任何动态脚本中使用 |
hidePreviewHead | 隐藏办理说明页头部简介 |
registerScript | 在操作按钮上注册脚本,按按钮时执行并控制是否提交 |
# getView(viewName)
获取参数viewName指定的视图对象,用这个方法获取视图对象和通过views属性获取视图对象是等价的。
// 将审核视图设置隐藏
this.getView['审核'].visible(false);
2
# defineGlobalFunction(name, fn)
按参数name指定的名称定义全局函数,该函数内容即第二个参数fn。建议在根对象动态脚本中使用,确保其他动态脚本中调用这个全局函数时该函数已完成定义。
// 以下动态脚本设置在根对象上,定义全局函数hi,其他脚本可通过hi(name)来使用,定义全局函数的脚本一般触发列表可不填,表示只在表单初始化时候定义函数
this.defineGlobalFunction('hi',function(name){
return 'hello ' + name;
});
// 以下脚本定义在某标签字段上,触发字段列表为$fieldName;当fieldName为张三时,该标签显示'hello 张三'
this.val(hi($fieldName))
2
3
4
5
6
7
# defineGlobalVariable(name, [initValue])
按参数name指定的名称定义全局变量,可选参数initValue为这个全局变量的初值。关于自定义全局变量的概念、用途和使用注意事项请参考此处。
如果这个全局变量已经存在,那么不会赋初值,只有当这个全局变量未定义时,初值才有作用。
// 定义在表单根对象的scripts里
this.defineGlobalVariable("sum",0);
this.defineGlobalVariable("status","starting");
this.defineGlobalVariable("visible",false);
2
3
4
# removeGlobalVariable(name)
按参数name指定的名称移除全局变量,不必定义在根对象的脚本中,任意脚本中都可以使用。
this.removeGlobalVariable("sum");
# hidePreviewHead
隐藏办理说明页头部简介,以便用户可以更好的定制化办理说明页
this.hidePreviewHead();
# registerScript(step, action, script)
在step参数指定的步骤,action参数指定的操作按钮上注册脚本script回调函数,用户按操作按钮时触发,通过script函数的返回值可以控制是否取消提交。
在这个回调函数中返回true则可以提交,返回false可阻止用户提交。如果需要用户的某些交互(比如通过confirmBox或者messageBox确认)才能决定是否能继续提交,那么script这个回调函数可以不返回true或者false,而是通过confirmBox和messageBox按钮回调函数中返回true或者false控制是否提交。由于confirmBox的确定取消按钮缺省就会分别返回true和false,那么使用confirmBox的时候可以不用明确指定具有返回值的回调函数。使用messageBox时未指定按钮参数时,那么缺省按钮会返回true,不阻止用户提交;当指定了按钮回调函数时只有明确返回了true才能使提交继续。
提示
注意如果在同一个步骤的同一个操作按钮执行过多次注册脚本方法,那么只有最后一次注册的脚本才会生效
// 以下代码在步骤add的submit操作上注册回调函数,弹出确认框,用户确认就提交,取消则不提交
this.registerScript('add','submit',function() {
confirmBox("确认提交?");
});
2
3
4
// 以下代码验证了两个表单字段是否相同,相同时直接提交,不同时让用户确认,用户点取消则不再继续提交
this.registerScript('add','submit',function() {
if ($fieldEdit1!=$fieldEdit2){
messageBox("两个值不相等,确认提交吗?",[{text:'提交',click:function(){return true;}},{text:'取消',click:function(){return false;}}]);
// 这里不明确返回true或者false,会等待用户在messageBox中点了提交或取消按钮后再决定是否继续提交
return;
}
return true;
});
2
3
4
5
6
7
8
9