本章主要介绍多对象表单控件的一些通用脚本函数,在此基础上,本章还将结合多对象控件的介绍一个很重要的概念,操作生命周期。
多对象控件顾名思义就是用于在表单中显示多个对象的控件,典型的多对象控件有:表格,关联结构树,多对象卡片,可视化控件等,典型的多对象控件如下图所示。在第二部分已经介绍过,多对象控件都有一个目标类,并且可以显示属于该目标类的一组对象。
图-多对象控件-表格示例
脚本基础
(一)如何引用多对象控件
和单对象控件一样,如果希望使用脚本操作多对象控件,需要得到对多对象控件的引用,在DWF中获得多对象控件引用的方法有三个:
- this.getAddinById():
这个函数的作用和获得单对象控件的作用是一样的,在表单中的每一个多对象控件都具有一个唯一的ID,通过此调用可以获得指定的多对象控件,脚本示例为this.getAddinById(表单控件唯一ID)。 - this.getTargetAddin():
这个函数在调用时无需输入传参,脚本引擎会自动寻找表单中的多对象控件,即将与当前表单目标类一致的多对象控件集合返回;与getAddinById()相比,getTargetAddin()调用的时候无需字符串作为参数,因此为脚本的跨表单复用提供了基础。
此外表单中按钮插件也可设置一个目标(多对象)控件,然后通过buttonAddin.getTargetAddin()脚本即可得到这个按钮对应的目标多对象控件的数组。
(二)多对象控件的通用函数
在DWF中的多对象控件有一系列标准的通用保留函数,这些函数代表了多对象控件的一般意义上的行为,例如:刷新,获取选中对象等,当得到了多对象控件的引用后,调用这些函数可以控制被调用的多对象控件实现这些行为。
假设获得的多对象控件对应的变量名为addin,这些通用函数有:
- addin.freshData():强制多对象控件进行刷新。
- addin.freshData(query):可以传入一个字符串变量用于控制多对象控件按照过滤条件更新,其中查询条件的编写方式可以参阅附录 (一)DWF内部查询条件语法。
- addin.getSelected():返回数组,包含多对象控件被用户点选的对象。
- addin.getAll():返回数组,包含多对象控件中所有前端可见的对象。
以本章一开始的设备列表的表单为例,如果希望在操作中通过脚本删除选中的设备,可以这么编写脚本:
targetClass = this.className; grids = this.getTargetAddin(); //获得表格控件的引用 if (grids && grids.lenth > 0) { targetObjs = grids[0].getSelected(); if (targetObjs && targetObjs.length > 0) { targetObjs.forEach(targetObj => { this.delete(targetObj, targetClass); }); } }
同样的,在上一部分里提到的关联结构树控件也具有上述功能
- getSelected(),该函数作用是获取树当前所选节点;具体脚本示例为:treeAddin.getSelected(),返回所选树节点绑定数据对象集合。
(三)操作的生命周期和脚本
4.3.4.2 表单建模入门(二)接触到了按钮控件,在按钮控件里面可以绑定一个操作,并且可以通过前处理脚本对弹出的后续表单中的数据进行初始化。
在第二部分里,对操作的前后处理脚本以及之间的关系、起效的时机并没有进行详细介绍,为了进一步讲解和多对象控件配合的操作,本章将深入介绍DWF操作的一个生命周期。
了解操作执行的生命周期和脚本的关系之后,可以大幅度提高多对象控件与后续关联表单的交互体验,包括:初始化弹框的内容等。
操作执行的关键环节
如下图所示,当用户点击设备列表上一个按钮,弹窗以后用户点击“确定”关闭以后的全过程。这一过程可以分成4个环节:
第1步、DWF脚本引擎会先调用前处理脚本,询问是否需要针对弹窗将要显示的对象,特定的属性进行初始化,例如:是否需要预先设置左右对象的OID。
第2步、在初始化完成,弹窗显示的表单控件被展示出来可见以后,DWF的表单引擎会继续调用一个implement操作,用于对可见的控件的进行进一步设置,例如:设置一些提示信息或者根据上下文设置一下初始值等。
之后,由用户对新展示的表单进行交互。
第3步、当用户点击表单底部的“确认”按钮时,DWF的表单引擎将调用表单指定的一个默认操作,如果该默认操作不为空,则会执行该操作的脚本,用于进行关闭前的善后工作,例如:最后检查是否存在错误。
第4步、当关窗结束以后,脚本引擎将调用操作指定的后处理脚本,用于根据弹窗关闭的结果,对上一级表单进行处理,例如:控制多对象控件进行刷新。
图-操作在DWF中激活后的整个生命周期和关键环节
脚本案例-创建工单弹窗至关闭全过程
接下来以根据选定的设备创建工单,在创建完成后更新设备的总工单数为例,介绍操作生命周期的开发方法。
(一)创建工单操作的前处理脚本传递设备oid到创建工单弹窗中
首先,在点击设备列表中对应的“创建工单”按钮后dialog弹窗时,需要得到设备对象的oid,并且将其传递到新建的工单对象之中对其“故障设备”属性进行初始化。
在操作中可以利用如下的前处理脚本,将希望被创建的工单对象进行如下的初始化:
if (this.selectedObjs && this.selectedObjs.length > 0){ return { //表明返回一个工单对象 obj: { assetOid: this.selectedObjs[0].oid //用被选中的设备对象的oid设置工单对象的assetOid } } }
DWF表单引擎等待前处理脚本返回一个传参JSON对象,其中“obj”的KV键值对表示对后续(新建)对象的哪些属性进行初始化赋值。
操作的前处理脚本填写的地方如下图所示,该操作希望打开一个工单类的SingleWO表单,弹窗创建新的工单。
图-操作的前处理脚本
除了return { obj: { ...}}之外,前处理脚本还可通过返回其他对象的方式控制后续弹框的行为,这些方式包括:
- return { query: ''}:一个查询字符串,如果后续打开的是另一个多对象控件,并且其查询条件设置为空,则可以利用前处理脚本对后续弹框进行默认的过滤。
- return { data: {}}:一个额外的JSON对象,用于将其他一些对象带入到后续表单中。
(二)用初始化操作对表单进行初始化
接下来,用表单建模工具打开工单类的SingleWO工单,点击基础配置,选择创建初始化操作,将操作配置为implement动作,选择前端脚本,填入如下的脚本:
var addin = this.getAddinById("DateInput1"); var deadline = new Date(); deadline.setDate(deadline.getDate() + 3); addin.setValue(deadline.getTime());
这个脚本的作用是将工单的“要求完成时间”属性设置为三天后。
(三)设置默认操作检查完成时间
按照同样的方式在默认操作下拉框中添加一个新的操作,名为“检查并创建”,操作的动作类型设置为implement,选择前端脚本填入如下的脚本:
if (this.obj.woTitle.length == 0){ var titleAddin = this.getAddinById("TextInput1"); titleAddin.setError(true,"内容为空"); return { error:'当前弹窗保存时发生错误,该Dialog窗口不能关闭!' } } else { this.create(this.obj, this.className); }
上述脚本的表示,如果在关闭的时候出现工单的标题为空,则阻止窗口关闭,其中return { error: }提示脚本引擎不能关闭窗口,并显示错误。
除了return{ error: ''}的返回方式以外,还有另一种返回方式:
- return {/*返回对象,在弹窗后处理操作脚本中通过‘this.confirmData变量获取’*/}://通过confirmData可以将一些数据从当前被关闭的弹框带回到前序的表单中。
上述配置完成后的表单的基础设置如下图所示:
图-表单基础配置
(四)更新对应设备的工单总数
最后,当工单被顺利创建以后,设备上的总工单数需要加1,因此可以在后处理脚本中添加一段如下的脚本:
if (this.selectedObjs && this.selectedObjs.length > 0){ targetAsset = this.selectedObjs[0]; targetAsset.assetWoCount += 1; this.edit(targetAsset, this.className).then(r => { grid = this.getAddinById("Grid1"); grid.freshData(); }) }
至此,创建工单的初始化,工单表单的初始化,表单检查和工单创建完成后的更新全部完成。
图-工单创建过程的脚本执行过程和效果
在这个案例中,通过后处理脚本修改设备总工单数目的过程中,如果在修改设备的时候出现断网等异常情况,可能导致设备上记录的总工单数和实际的总工单数不一致的问题,遇到这种情况时,需要使用后端脚本完成任务。在后续的章节中将介绍后处理脚本。
小结
本章主要围绕如何通过脚本操作表单中的多对象控件展开介绍,在此基础上还介绍了操作的生命周期和各个环节的扩展方法。其中主要包括:
- addin.freshData():强制多对象控件进行刷新。
- addin.freshData(query):可以传入一个变量用于控制多对象控件按照过滤条件更新。
- addin.getSelected():返回数组,包含多对象控件被用户点选的对象。
- addin.getAll():返回数组,包含多对象控件中所有前端可见的对象。
操作的生命周期4个重要的环节
- 前处理脚本
- 表单初始化
- 表单的默认操作
- 后处理脚本
下一章,将介绍前端脚本和控件的事件之间的关系。
示例模型包