2020-双十一-培训手册
页面树结构
转至元数据结尾
转至元数据起始

上一章节介绍了表单控件定义与单对象表单控件的脚本开发能力，本章主要介绍多对象表单控件的一些通用脚本函数，在此基础上，本章还将结合多对象控件的介绍一个很重要的概念，操作生命周期。

多对象控件顾名思义就是用于在表单中显示多个对象的控件，典型的多对象控件有：表格，关联结构树，多对象卡片，可视化控件等，典型的多对象控件如下图所示。在第二部分已经介绍过，多对象控件都有一个目标类，并且可以显示属于该目标类的一组对象。

图-多对象控件-表格示例

1. 脚本基础

1.1 如何引用多对象控件

和单对象控件一样，如果希望使用脚本操作多对象控件，需要得到对多对象控件的引用，在DWF中获得多对象控件引用的方法有三个：

  • this.getAddinById()：
    这个函数的作用和获得单对象控件的作用是一样的，在表单中的每一个多对象控件都具有一个唯一的ID，通过此调用可以获得指定的多对象控件，脚本示例为this.getAddinById(表单控件唯一ID)。
  • this.getTargetAddin()：
    这个函数在调用时无需输入传参，脚本引擎会自动寻找表单中的多对象控件，即将与当前表单目标类一致的多对象控件集合返回；与getAddinById()相比，getTargetAddin()调用的时候无需字符串作为参数，因此为脚本的跨表单复用提供了基础。
    此外表单中按钮插件也可设置一个目标（多对象）控件，然后通过buttonAddin.getTargetAddin()脚本即可得到这个按钮对应的目标多对象控件的数组。

1.2 多对象控件的通用函数

在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()，返回所选树节点绑定数据对象集合。

1.3. 操作的生命周期和脚本

如果读者学习过第二部分，第三章 表单建模入门(二) ，应该会接触到了按钮控件，在按钮控件里面可以绑定一个操作，并且可以通过前处理脚本对弹出的后续表单中的数据进行初始化。

在第二部分里，对操作的前后处理脚本以及之间的关系、起效的时机并没有进行详细介绍，为了进一步讲解和多对象控件配合的操作，本章将深入介绍DWF操作的一个生命周期。

了解操作执行的生命周期和脚本的关系之后，可以大幅度提高多对象控件与后续关联表单的交互体验，包括：初始化弹框的内容等。

操作执行的关键环节

如下图所示，当用户点击设备列表上一个按钮，弹窗以后用户点击“确定”关闭以后的全过程。这一过程可以分成4个环节：

第1步、DWF脚本引擎会先调用前处理脚本，询问是否需要针对弹窗将要显示的对象，特定的属性进行初始化，例如：是否需要预先设置左右对象的OID。

第2步、在初始化完成，弹窗显示的表单控件被展示出来可见以后，DWF的表单引擎会继续调用一个implement操作，用于对可见的控件的进行进一步设置，例如：设置一些提示信息或者根据上下文设置一下初始值等。

之后，由用户对新展示的表单进行交互。

第3步、当用户点击表单底部的“确认”按钮时，DWF的表单引擎将调用表单指定的一个默认操作，如果该默认操作不为空，则会执行该操作的脚本，用于进行关闭前的善后工作，例如：最后检查是否存在错误。

第4步、当关窗结束以后，脚本引擎将调用操作指定的后处理脚本，用于根据弹窗关闭的结果，对上一级表单进行处理，例如：控制多对象控件进行刷新。

图-操作在DWF中激活后的整个生命周期和关键环节

2. 脚本案例-创建工单弹窗至关闭全过程

接下来以根据选定的设备创建工单，在创建完成后更新设备的总工单数为例，介绍操作生命周期的开发方法。

2.1 创建工单操作的前处理脚本传递设备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对象，用于将其他一些对象带入到后续表单中。

2.2 用初始化操作对表单进行初始化

接下来，用表单建模工具打开工单类的SingleWO工单，点击基础配置，选择创建初始化操作，将操作配置为implement动作，选择前端脚本，填入如下的脚本：

var addin = this.getAddinById("DateInput1");
var deadline = new Date();
deadline.setDate(deadline.getDate() + 3);
addin.setValue(deadline.getTime());

这个脚本的作用是将工单的“要求完成时间”属性设置为三天后。

2.3 设置默认操作检查完成时间

按照同样的方式在默认操作下拉框中添加一个新的操作，名为“检查并创建”，操作的动作类型设置为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可以将一些数据从当前被关闭的弹框带回到前序的表单中。

上述配置完成后的表单的基础设置如下图所示：

图-表单基础配置

2.4 更新对应设备的工单总数

最后，当工单被顺利创建以后，设备上的总工单数需要加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();
    })
}

至此，创建工单的初始化，工单表单的初始化，表单检查和工单创建完成后的更新全部完成。

图-工单创建过程的脚本执行过程和效果

在这个案例中，通过后处理脚本修改设备总工单数目的过程中，如果在修改设备的时候出现断网等异常情况，可能导致设备上记录的总工单数和实际的总工单数不一致的问题，遇到这种情况时，需要使用后端脚本完成任务。在后续的章节中将介绍后处理脚本。

3. 小结

本章主要围绕如何通过脚本操作表单中的多对象控件展开介绍，在此基础上还介绍了操作的生命周期和各个环节的扩展方法。其中主要包括：

  • addin.freshData()：强制多对象控件进行刷新。
  • addin.freshData(query)：可以传入一个变量用于控制多对象控件按照过滤条件更新。
  • addin.getSelected()：返回数组，包含多对象控件被用户点选的对象。
  • addin.getAll()：返回数组，包含多对象控件中所有前端可见的对象。

操作的生命周期4个重要的环节

  • 前处理脚本
  • 表单初始化
  • 表单的默认操作
  • 后处理脚本

下一章，将介绍前端脚本和控件的事件之间的关系。

4. 附件

第五章 多对象表单控件和操作.zip

  • 无标签