# 引用对象

动态执行上下文中封装的引用对象分为字段对象重复节表对象视图对象根对象四种,这四种对象上各自封装了不同的属性和方法供动态中使用。

# 字段对象

表单控件的对象分为字段对象和重复节表对象,这两种对象的属性和方法封装有所不同。

在动态配置中您可以使用$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);
}
1
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:""});
    }
}
1
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("");
    }
}
1
2
3
4
5
6
7
8
9
10
11
示例 设置初值
// 如果没有其他动态依赖这个初值,那么可以将设置初值的脚本放到字段脚本上
this.val('init value',{force:true});
1
2
// 如果设置初值的字段还被其他动态依赖,那么可以将设置初值的脚本放到根对象的初始化脚本中
$fieldInit.control.val('init value',{force:true});
1
2

# attr([name, value])

取属性或者设置属性。name参数未传递时就是取所有属性;name参数传递时value参数不传就是取name参数指定的属性,value参数传了就是设置name参数指定的属性。

示例 获取属性
// 获取用户学工号
this.val($fieldUser.control.attr("userCode"));
1
2

# css(name[, value])

取样式或者设置样式。name参数必填,value参数传了就是设置name参数指定名称的样式,value参数不传就是获取name参数指定名称的样式。

示例 设置样式
// 设置背景色为灰色
this.css("background-color","gray");
1
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"});
1
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);
1
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
示例 设置动态datasource
// 设置数据源为用户字段的部门属性,缺省选中第一个
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);

1
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');
1
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();
}
1
2
3
4
5
6
7
8
9
10
11

# focus()

控件获得焦点

# blur()

控件失去焦点

# highlight()

高亮控件,产生闪烁效果

# placeholder([value])

设置控件的输入提示信息,当参数value不传时代表着将placeholder恢复为字段上的Placeholder属性设置内容,value参数有值时代表设置提示为该值
支持动态设置placeholder的控件包括EditTextareaRichTextRemarkDateTimeSuggesterSuggester2SelectFileThingButtonLinkButtonCheck,其中Button、LinkButton、Check的placeholder是点击后的确认提示信息。

示例 设置提示
// 将控件placeholder设置为提示信息
this.placeholder('提示信息');
// 清空控件placeholder
this.placeholder('');
// 恢复控件placeholder到字段上的PlaceHolder静态配置,如果PlaceHolder未配置就清空提示
this.placeholder();
1
2
3
4
5
6

# parent([value])

设置控件的父亲值,作用等同于设置字段的Parent属性,主要用于Code数据类型的控件(CheckList、OptionList、Select、Suggester2等)过滤数据。设置Parent属性只能设置到某个字段,用parent方法可以根据表单上多个用户填值来设置父亲值,可以避免再增加额外的父亲字段和动态公式配置。当参数不传递时可获取当前父亲值,当参数为null或者空字串时表示去除父亲设置。

示例 设置Parent
// 在控制台打印当前父亲值
console.log(this.parent());
// 将本控件父亲值设置为001
this.parent('001');
// 去除本控件的父亲值设置
this.parent(null);
1
2
3
4
5
6

# registerValidation(fn)

在控件上注册验证函数fn,该函数可返回验证不通过时的提示信息,如果返回空字符串或者不返回内容表示验证通过。注册的验证函数会在该控件失去焦点时、函数依赖的其他表单字段值改变时以及提交等时机调用。注意同一个字段上只能注册一次验证脚本,多次注册的话以最后注册的为准。

字段验证函数可在该字段脚本中注册,脚本依赖字段列表为空,这样可以避免多次注册。

验证函数返回不通过时的提示信息有2种格式,可以是一个字符串,也可以是一个字符串的数组表示多行提示,当然如果多行提示也可以用一个字符串返回中间用回车符分隔。

验证函数中的this指向的是注册验证脚本的那个字段控件对象引用。

示例 注册验证,返回单行提示
// 该段脚本放到fieldF1的script上,验证fieldF1不能为0
this.registerValidation(function() {
  if (this.val() === 0) {
    return '不能为0';
  }
});
1
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;
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# scrollIntoView([time])

在控件可见时控制页面滚动到控件的位置,参数time是滚动时间(单位毫秒,缺省不填是200毫秒),如果是0表示立即滚动到该位置。注意该方法对普通控件、重复控件、视图都有效。

示例 scrollIntoView
if(!$INIT) {
    if($fieldShowView) {
        $VIEWS['审核'].scrollIntoView(1000);
    } else {
        if(this.val()===true) {
            $fieldControl.control.scrollIntoView();
        } else {
            $groupRepeat.scrollIntoView(0);
        }
    }
}
1
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,如果只有一个参数会设置重复节表总体只读,如果传三个参数就分别设置是否能新增、删除、移动。

示例 readOnly示例
// 设置只读(增删移)
this.readOnly(true);

// 设置可删、不可增、不可移动
this.readOnly(true,false,true);
1
2
3
4
5

# itemVisible(isVisible, index)

执行动态itemVisible,参数isVisible表示设置是否可见,参数index表示表示行序号(从0开始)。

示例 itemVisible示例
// 触发字段列表填$fieldCheck,脚本内容如下
for(var i=0,length=$fieldCheck.length;i<length;i++) {
    this.itemVisible($fieldCheck[i]===true,i);
}
1
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);
    }
}
1
2
3
4
5

# itemReadOnly(isReadOnly, index)

执行动态itemReadOnly,参数isReadOnly表示设置是否只读,参数index表示行序号(从0开始)。

# itemStyle(style, index)

执行动态itemStyle,参数style可以直接是样式字串,也可以是个样式对象,参数index表示行序号(从0开始)。

示例 itemStyle示例

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);
        }
    }
}
1
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"格式赋值。

示例 addRow示例
$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"});    // 在末尾新增一行数据
1
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方法用于统一设置所有视图是否移动端标题栏可见
示例 根对象上views属性使用示例
// 将审核视图设置隐藏
this.views['审核'].visible(false);

// 将所有视图设置移动端标题栏不可见
this.views.titleVisible(false);
1
2
3
4
5

# 方法

根对象中封装了一些通用方法供动态脚本中使用

方法 描述
getView 获取视图对象引用
defineGlobalFunction 定义全局函数,建议在根对象动态脚本中使用
defineGlobalVariable 定义全局变量,建议在根对象动态脚本中使用
removeGlobalVariable 移除全局变量,可在任何动态脚本中使用
hidePreviewHead 隐藏办理说明页头部简介
registerScript 在操作按钮上注册脚本,按按钮时执行并控制是否提交

# getView(viewName)

获取参数viewName指定的视图对象,用这个方法获取视图对象和通过views属性获取视图对象是等价的。

示例 根对象上getView属性使用示例
// 将审核视图设置隐藏
this.getView['审核'].visible(false);
1
2

# defineGlobalFunction(name, fn)

按参数name指定的名称定义全局函数,该函数内容即第二个参数fn。建议在根对象动态脚本中使用,确保其他动态脚本中调用这个全局函数时该函数已完成定义。

示例 定义全局函数示例
// 以下动态脚本设置在根对象上,定义全局函数hi,其他脚本可通过hi(name)来使用,定义全局函数的脚本一般触发列表可不填,表示只在表单初始化时候定义函数
this.defineGlobalFunction('hi',function(name){
  return 'hello ' + name;
});

// 以下脚本定义在某标签字段上,触发字段列表为$fieldName;当fieldName为张三时,该标签显示'hello 张三'
this.val(hi($fieldName))
1
2
3
4
5
6
7

# defineGlobalVariable(name, [initValue])

按参数name指定的名称定义全局变量,可选参数initValue为这个全局变量的初值。关于自定义全局变量的概念、用途和使用注意事项请参考此处
如果这个全局变量已经存在,那么不会赋初值,只有当这个全局变量未定义时,初值才有作用。

示例 定义全局变量示例
// 定义在表单根对象的scripts里
this.defineGlobalVariable("sum",0);
this.defineGlobalVariable("status","starting");
this.defineGlobalVariable("visible",false);
1
2
3
4

# removeGlobalVariable(name)

按参数name指定的名称移除全局变量,不必定义在根对象的脚本中,任意脚本中都可以使用。

示例 移除全局变量示例
this.removeGlobalVariable("sum");
1

# hidePreviewHead

隐藏办理说明页头部简介,以便用户可以更好的定制化办理说明页

示例 隐藏办理说明页头部简介
this.hidePreviewHead();
1

# 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("确认提交?");
});
1
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;
});
1
2
3
4
5
6
7
8
9