前一章初步介绍了如何通过DWF的前端脚本访问加载到界面的业务数据，本章将进一步介绍如何通过DWF的前端脚本访问前端页面中表单控件，进而控制表单控件的隐藏与显示等。

1. 脚本基础

打开DWF建模工具的表单编辑器时，会看见左侧的表单控件区。一般情况下，对这些控件进行配置就可以了。但是也存在一些特殊的逻辑需要实现，例如，希望根据当前编辑对象的取值，动态的显示或者隐藏一部分控件，或者让某些控件进行刷新。要实现这些功能，首先从脚本里找到我们希望用程序控制的控件，DWF的表单控件都有一个唯一的ID，每当控件被拖放到表单编辑工具的画布区以后，DWF会为其默认生成一个128位的UUID（同时也支持手动修改），如下：

图-DWF表单与表单控件示意

1.1 DWF提供的表单控件

DWF表单的控件区控件具体区分了“单对象控件”、“多对象控件”、“可视化控件”、“布局控件”、“模型点选控件”与“时间序列控件”等，如下图所示：

图-DWF表单控件区提供的控件

其中“单对象控件”一般可理解属性级控件（属性级控件相对容易理解），对应绑定业务对象的属性，如文本框可以绑定对象“字符串”类型属性，数字框可以绑定对象“数字”类型属性，日期控件可绑定对象“日期”类型属性等，单对象控件是本章脚本应用重点。

其中“多对象控件”、“可视化控件”、“模型点选控件”与“时间序列控件”可理解为对象级控件（即多对象控件），可以绑定了多对象多属性的界面能力，对象级控件脚本在后续章节具体介绍。

其中“布局控件”属于容器类控件，相对比较独立，主要作用是页面容器布局，其关联的脚本能力主要体现为可见、不可见与调整尺寸大小等。

1.2 表单控件脚本

DWF中表单控件支持自定义操作的脚本控制，即通过脚本能获取到控件对象，获取到控件对象后，进而可基于脚本控制控件的显示、隐藏与调整大小等控件样式，同时也还可以获取或设置控件对象绑定的业务数据等，后面就详细说明控件脚本能力。

1.3 表单控件和数据

在DWF页面中外观能看到的是“表单控件”，表单控件“背后”是其绑定的数据（业务对象、对象属性或内存变量等），因此表单控件与数据是分开的概念；且表单控件取值的变化并不表示其相绑定数据对象的取值变化，只有在表单被（新增或修改）保存的瞬间，控件的取值才会同步到其绑定的数据对象；

表单定义时推拽进去的控件都临时生成了控件ID，在脚本中可通过该ID获取定位到表单控件，进而能获取到绑定的“数据”。

1.4 通用控件函数

getAddinById()，作用是表单控件获取定义，具体调用示例为：var addinA = this.getAddinById(‘控件A的id’)，其中参数为控件的唯一id。

setValue()，作用是表单控件的赋值，具体调用示例为：addinA.setValue('赋值')，其中addinA表示定位到的控件对象，传入参数为具体的赋值。

getValue()，作用是表单控件的取值函数，具体调用示例为：var addinValue= addinA.getValue()，其中addinA表示定位到的控件对象，addinValue为返回控的件取值。

setError()，作用是表单控件的异常提示，具体调用示例为：addinA.setError('异常信息')，其中 addinA表示定位到的控件对象，传入参数为具体的异常信息。

args，该对象主要作用是控制表单控件的样式渲染，如：控件的隐藏、显示、只读、尺寸大小与其它特定的样式选项，具体介绍如下主要几种属性与用法：
- args.readonly ，作用是控制控件是否只读，具体调用示例为：addinA.args.readonly = true/false，其中 addinA表示定位到的控件对象，true值表示控件设置为只读，否则为可写；
- args.hided，作用是控制控件是否隐藏，具体调用示例为：addinA.args.hided= true/false，其中 addinA表示定位到的控件对象，true值表示控件设置为隐藏，否则恢复显示；
- args.selectedList，该选项目前仅对“选择下拉控件”有效，定义其下拉内容，具体调用示例为：addinA.args.selectList = [{label:"label1", value:"value1"}, {label:"label2", value:"value2"}] ，其中addinA表示定位到的控件对象；
- args.filterQuery,该选项目前仅对“单对象下拉框”与部分"多对象控件"有效，设置过滤条件，具体调用示例为：addinA.args.filterQuery = `and obj.state = '已发布'` ,其中addinA表示定义到的控件对象，设置值为字符串，可插入变量。

1.5 高级控件脚本

this.getTargetAddin()

该函数作用是获取当前目标多对象控件，在调用时无需输入参数，便可在脚本引擎会自动寻找表单中的多对象控件，并将当前表单中目标类和多对象控件设置的目标类相同的多对象控件返回；
同时在表单按钮插件里，也可获取目标多对象控件，通过this.getTargetAddin可以相应得到这个按钮所对应的目标多对象控件的数组。

this.selectedObjs

该函数作用是获取当前多对象控件所选的的对象，返回为数组，即多个对象集合，具体调用示例为：var curObj = this.selectedObjs[0]，其中 curObj 为返回的当前多选第一个业务对象，且curObj.oid表示所选对象的oid属性。

1.6 基础控件脚本

Tab控件
- setDisable()，该函数作用是设置Tab控件子页签的可见与不可见，具体脚本示例为：tabAddin.setDisable('子页签名称',true)，其中 tabAddin表示定位到的tab控件对象，,函数约定了两个参数，第一个参数为子页面名称，第二个参数为true/false，true表示禁用显示子页签，false表示取消禁用。
- getSelectedTab()，该函数作用是获取Tab控件当前选中的子页签，具体脚本示例为：tabAddin.getSelectedTab()，其中 tabAddin表示定位到的tab控件对象，函数无参数，反回当前选中的子页签；获取到子页签对象后，可继续获取到其名称，然后可通过脚本继续设置其子页签是否禁用等。
- turnTo() ，该函数作用是跳转激活子页签，具体脚本示例为：tabAddin.turnTo("作业卡下步骤")，其中 tabAddin表示定位到的tab控件对象，,函数有一个参数，即要跳转激活子页签的名称。

2. 脚本案例

接下来，以设备管理中设备创建与修改为主要场景，介绍单对象控件脚本处理能力。

2.1 设置设备照片的显示与隐藏

首先，在点击设备列表中对应的“创建设备”按钮，然后弹出设备创建dialog弹窗，在弹窗的基础属性中上传设备照片，然后就可演示基于脚本控制“设备照片单对象控件的显示与隐藏，如下图所示；

图-通过脚本控制设备照片控件的显示与隐藏示意

如上图中“显示与隐藏”按钮绑定操作的脚本如下所示：

clientScript:	//前端脚本关键字
//获取到设备照片单对象控件
addin = this.getAddinById("Attachments1");
//设置控件的显示状态-方法2（简单）
addin.args.hided = !addin.args.hided;

2.2 设置设备“代号”控件的禁止与启用

在点击设备列表中对应的“编辑设备”按钮，然后弹出编辑设备dialog弹窗，在弹窗中通过“禁用和开启”按钮脚本，设置代号控件的禁止与启用，如下图所示；

图-通过脚本控制设备代号控件的静止与启用示意

如上图中“禁用和开启”按钮绑定操作的脚本如下所示：

clientScript:
//定位获取代号控件
addin = this.getAddinById("TextInput1");
console.log(addin.args);
//通过控件的args参数设置只读状态
addin.args.readonly = !addin.args.readonly;
//同时调用setValue函数设置控件显示
addin.setValue(addin.args.readonly? "我自闭了":"我想开了");

2.3 更新设备最近工作小时数

在点击设备列表中对应的“编辑设备”按钮，然后弹出编辑设备dialog弹窗，在弹窗中通过“更新工作小时数”按钮脚本，直接修改设备“工作小时数”控件显示值，如下图所示；

图-通过脚本定位并改变设备工作小时数控件的值示意

如上图中“更新工作小时数”按钮绑定操作的脚本如下所示：

clientScript:
targetObj = this.obj;
workHoursAddin = this.getAddinById("NumberInput4");
installDateAddin = this.getAddinById("DateInput1");
currentDate = new Date();
installDate = installDateAddin.getValue();
console.log(installDate);
if (installDate){
    workHoursAddin.setValue(parseInt(currentDate - installDate) / 1000 / 3600);
} else{
    workHoursAddin.setError(true,"安装时间未设置");
    installDateAddin.setError(true,"安装时间未设置");
}

2.4 下拉框值变化事件联动其它控件

在点击设备列表中对应的“新建设备”按钮，然后弹出创建设备dialog弹窗，在弹窗中通过选择“设备类型”下拉修改值后，默认改变“设备描述”控件值，如下图所示；

图-设备类型的下拉选择后默认修改设备描述控件值

图-设备类型下拉值变化事件操作脚本

如上图中“设备类型”值变化事件绑定操作的脚本如下所示：

clientScript:
debugger;
//alert('调试阶段');
//获取设备类型（单对象）控件
var assetTypeAddin = this.getAddinById("SelectInput1");
//获取设备描述（单对象）控件
var descriptionAddin = this.getAddinById("TextInput3");
//给设备描述属性控件默认赋值
descriptionAddin.setValue(`这是一台[${assetTypeAddin.getValue()}]类型设备`);

3. 小结

本章主要介绍了单对象表单控件的脚本能力，并且结合四个例子展示了脚本用途，其中需要记住的API函数如下：

表单控件定位： this.getAddinById；
通用控件函数： getValue(), setValue(), setError(), args.hided, args.readonly, args.selectList等;
高级控件函数：
- 对象点选 selectedObjs
- 操作 getTargetAddin()
- 表格 freshData()
基础控件函数：标签控件相关的 setDisable、getSelectedTab 与 turnTo；

下一章，继续介绍表单控件中的多对象控件相关脚本能力。

4. 附件

第四章单对象表单控件.zip

页面树结构

第四章 单对象表单控件脚本