控件的属性区编程
上一章里详细介绍了表单控件的各项配置和对应的代码,表单控件自身自带的属性设置非常丰富,有些属性的设置在很多控件中重复出现,例如:目标类设置,目标属性设置,如下图所示,当用户打开DWF的表单建模工具的时候,工具会显示下面的一些区域:
图-表单建模工具的组成
- 控件区:主要显示可以拖入的控件。
- 画布区:主要显示拖入表单以后的控件布局和控件的展示方式。
- 工具条:展示属于整个表单的公共属性。
- 属性区:表单控件可以展示的个性化属性。
- 属性编辑区:控件的每一个属性对应一个属性编辑区,这些属性编辑区对应的属性取值将和控件规范中的args中包含的变量对应。
如果这些设置都需要重新开发,不仅增加程序员的负担,还会导致用户体验的不一致,为了针对这一问题,DWF封装了一套标准的交互组件,如果使用这些交互组件进行设置可以大幅度降低控件属性设置的难度,提高用户体验的一致性。
以目标属性为例,交互组件的形式如下所示:
图-DWF表单控件中目标属性参数的标准交互示意
本章介绍交互组件的使用方法介绍这些缺省设置对应的使用方法,和上一章一样,本章将开发一个名为“空白控件”的控件开发,围绕一个可以设置高度、宽度和显示的内容,如下所示:
图-空白控件示意图
控件属性编辑区
(一)控件初始标签设置
和上一节入门控件一样,这里即将开发白板控件对应的建模端包含图标,预览和属性编辑三大块标签,如下代码所示:
<template> <!-- 建模时的预览前端,即插件的实际显示样式 :addinName="name"和ref="main"一般情况不可去除 --> <section v-if="t_preview" :addinName="name" ref="main" :style="{ width: args.width + args.widthType }" > <!-- 在画布区的显示内容 --> <span :style="{ height: args.height + args.heightType, width: 100 }" style=" font-size: 50px; display: flex; justify-content: center; align-items: center;" >{{ args.label }}</span> <span v-show="t_edit" ref="edit"> <!-- 编辑区暂时为空 --> </span> </section> <section v-else :addinName="name"> <span style="text-align: center;"> <div class="form-addin-icon"> <!-- 控件拖放区图标的样式 --> <i class="iconfont"></i> </div> <!-- 在控件拖放区图标的名字 --> <div class="form-addin-name">空白控件</div> </span> </section> </template>
在上面的代码中注意看到:
- 已经使用了vue的数据绑定能力将整体宽度、整体高度和标签内容设置为args.height,heightType,width,widthType以及args.label五个参数。
- 其中<span v-show="t_edit" ref="edit">标签的内容仍然保持为空,因此如果此时调试控件是不会有和上述5个参数对应的属性编辑框出现的。
下面看如何得到属性编辑框。
(二)给控件增加自动配置能力
为了给控件增加属性编辑功能,DWF提供了一个称之为EditBox的标签和配套的函数,只要控件的代码中包含args属性是DWF建模工具可以自动识别的,表单建模工具会自动为其在属性编辑区建立对应的输入控件。增加EditBox需要执行下面的步骤:
- 在控件vue文件中的<template>内增加<EditBox>标签并配置参数。
- 在脚本部分通过import引入_EditBox.vue文件和EditBox的component组件。
- 引入DWF表单引擎传入的prop参数,以便EditBox作为标签参数绑定。
(1)引入EditBox标签
首先,引入EditBox标签的方法很简单,如下代码所示:
<span v-show="t_edit" ref="edit"> <!-- 属性编辑框区域 需要该插件获取attributes, router, route, root, query_oprs, itemValue的prop 对于不需要设置目标属性的插件,可以将attributes去掉 对于不需要设置事件的插件,可以将router, route, root, query_oprs去掉 --> <EditBox v-model="args" :router="router" :route="route" :root="root" :itemValue="itemValue" :query_oprs="query_oprs" :targetclass="itemValue.data.targetClass" > <div slot="attribute"> <!-- 属性选项放置区域 一般一个控件的prop都属于属性选项 --> </div> <div slot="layout"> <!-- 样式选项放置区域 仅有涉及到高度,宽度,对齐等样式的选项放在这里 --> </div> <div slot="operation"> <!-- 事件选项放置区域 --> </div> </EditBox> </span>
- 在EditBox里增加了一系列prop变量绑定,例如:attributes, router, route, root, query_oprs, itemValue。
- 在标签里如果出现需要自定义的部分可以分别在<div slot>标签里添加,这里先不考虑添加自定义属性。
(2)引入EditBox脚本
接下来,直接引入EditBox标签对应的脚本实现,具体代码片段如下所示:
<script> // 引入控件自身的属性编辑框,DWF给出的标准实现 import EditBox from "@/ext_components/form/_EditBox.vue"; export default { // 引入控件的设置框对应的组件,对应在标签内可以引用 components: { EditBox, }, // 引入DWF的控件编辑辅助属性 props: [ "widgetAnnotation", "itemValue", "attributes", "route", "router", "root", ], ... </script>
上述代码中import和component部分是标准操作直接引入即可
props是vue的对象传递机制,DWF在控件初始化的时候会将一些全局js变量传入,可以传入的对象并且被EditBox识别的有:
- widgetAnnotation="widgetAnnotation":控件标注所用参数,DWF会通过props直接传递一个缺省值进来
- router="router":当前路由对象,DWF会通过props直接传递一个缺省值进来
- route="route":当前路由信息,DWF会通过props直接传递一个缺省值进来
- root="root":根组件对象,DWF会通过props直接传递一个缺省值进来
- itemValue="itemValue":表单对应JSON实例化以后的对象,DWF会通过props直接传递一个缺省值进来
- dataTypes="dataTypes":目标属性类型
- attributes="filter_attributes":过滤之后的目标属性
- targetclass="itemValue.data.targetClass":表单类
(3)增加args属性
引入了EditBox以后,还需要在vue文件脚本部分的data()函数中返回args对象,用于保存和初始化需要展示的控件属性。
对于表单控件而言args非常重要,其作用包括:
- 通知表单建模工具需要保留在数据库中的参数。
- 还原表单上次保存的样子,此时控件的setArgs和getArgs会被建模工具调用。
- 在应用端表单展现的时候,展示真实的表单,同样的,控件的setArgs和getArgs会被建模工具调用。
- EditBox会自动扫描args的内容并自动识别可以产生属性配置的界面,这些属性在编辑以后,DWF会自动将其保存在表单对应JSON文件中,详细的自动识别清单可以参阅: DWF可自动识别的args参数
对于本章提到的args参数,height,heightType,width,widthType,label代码如下所示:
// Vue数据绑定的时候要求返回的结果 data() { return { //插件的名字 name: "blankControl", //表示是否已经进入画布区 t_preview: false, //是否需要编辑属性 t_edit: false, // 属性配置项,按需设置 args: { height: 300, heightType: "px", width: 100, widthType: "%", label: "Empty!", }, }; },
(三)了配置项以外,控件内的事件也可以添加到里面来,如果需要添加控件自身的事件响应,具体操作是:
建模工具里的事件配置
在args属性里添加两个配置参数:eventRange,events,它们的作用是:
args.eventRange:是一个数组类型,要求元素为字符串,这些元素在空间被点击后,表单建模工具里,会在“事件”页签里出现对应名称的操作点选配置下拉框,比如:
args: { ... // 给出控件可以支持的事件类型 eventRange: ["单击", "双击"], events: [] }
在参数区的事件栏里,就会出现单击和双击事件对应的操作配置框。
args.events:用于保存事件对应的操作名称,在配置框里下拉选择以后对应的配置信息会在这个变量里出现,同理,表单再次被打开的时候events也会被表单引擎重新赋值。
下面给出了一个表单JSON的例子,包含了一个单击事件和一个双击事件对应的表单配置,在这个配置中每一个事件对应的操作对应了三个属性:events: [ { opr_path: "save", opr_type: "sys", name: "单击", }, { opr_path: "1144803D337D7349A3EA8E4132143C54", opr_type: "query", name: "双击", }, ],
opr_path:代表操作对象的系统内部标识。
opr_type:操作类型,sys表示系统操作,query表示用户新建的操作。
name:对应事件的名称和eventRange里事件名称形成对应关系。
综上所述,如果希望为进阶的控件添加单击和双击事件,那么可以在args添加如下的代码:
// Vue数据绑定的时候要求返回的结果 data() { return { //插件的名字 name: "blankControl", //表示是否已经进入画布区 t_preview: false, //是否需要编辑属性 t_edit: false, // 属性配置项,按需设置 args: { height: 300, heightType: "px", width: 100, widthType: "%", label: "Empty!", eventRange: ["单击", "双击"], events: [], }, }; },
上述代码添加到进阶插件的args列表之中以后,在画布中添加进阶控件,可以看到如下的效果:
图-控件增加单击、双击事件
(1)表单应用中的事件触发
通过this.invokeOperation触发操作
在表单具体实例显示到表单引擎里面以后,控件事件和操作的配置信息会由DWF表单引擎传递给控件具体的实现,此时控件开发者应在代码里根据事件的名称编写捕获事件的逻辑,并且根据事件的配置触发相应的操作,这一任务在app端实现需要调用DWF前端提供的invokeOperation方法,该方法要求控件传入4个参数,典型的调用方法如下:
this.invokeOperation( opr_type, opr_path, this.itemValue, this.store );
- opr_type, opr_path是事件配置的基本信息,在初始化控件的时候,表单引擎通过setArgs传入args.events数组。
- itemValue和store是vue上层控件传入的信息,可以直接通过props: ["itemValue", "store"]传入。
为了方便可以实现一个用事件名称触发操作的函数,假设名字为trigerEvent():
export default { props: ["itemValue", "store"], // Vue数据绑定的时候要求返回的结果 data() { return { ... // 省略无关代码 args: { ... // 省略无关代码 events: [], }, }; }, methods: { ... //省略无关代码 triggerEvent(eventName) { let eventConfig = null; // 提取事件对应的操作参数 if (this.args.events && this.args.events.length > 0) { eventConfig = this.args.events.find((val) => { return val.name === eventName; }); } // 触发实际操作 if (eventConfig) { this.invokeOperation( eventConfig.opr_type, eventConfig.opr_path, this.itemValue, this.store ); } }, }, };
(2)绑定标签的原始事件
了解如何绑定原始事件并且触发操作以后,剩余的部分就非常简单了,在标签部分将标签的原始事件与函数对应起来,然后调用前面描述的triggerEvent方法触发事件配置对应的参数,先看如何绑定标签上的事件,以本章的进阶控件为例,原本设计了两个事件:单击和双击,运用vue规定的语法在template部分的标签中增加@click和@dbclick分别绑定到onClick() 和 onDoubleClick()方法上,代码如下:
<template> <section :style="{ width: args.width + args.widthType, }" :addinName="name" ref="main"> <!-- 在画布区的显示内容 --> <span :style="{ height: args.height+ args.heightType, width: args.width + args.widthType, }" style=" font-size: 50px; display: flex; justify-content: center; align-items: center;" <!-- 绑定标签上的时间调用函数 --> @click="onClick" @dblclick="onDoubleClick" >{{args.label}}</span> </section> </template>
然后在script里面的onClick和onDoubleClick的实现里调用triggerEvent,代码如下:
// 区域被单击以后的响应 onClick() { this.triggerEvent("单击"); }, // 区域被双击以后的响应 onDoubleClick() { this.triggerEvent("双击"); },
好了,上述代码补充到之前的实现里,打开表单即可让脚本开发者验证是否具有单击和双击实现,关于操作脚本的开发详见 第五章 多对象表单控件脚本:
图-控件增加单击和双击事件后的效果
(四)完整代码
(1)建模端完整代码
上面两节介绍了最关键的操作,下面公布空白控件在建模工具里的完整代码,此时控件的methods部分包含了表单建模工具将要调用的大部分函数:setDisplayType,getEditBox,setHeight,setArgs,getArgs,getAllow,getFormName
(2)应用端完整代码
在上述讨论之后,对应插件的应用端代码和入门控件的应用端类似,除了入门控件提到的setDisplayType, setArgs, getArgs以外,应用端代码还实现了用于和表单引擎交互的一些其他函数包括:
validate:当涉及到数据的时候表单引擎会调用这两个函数要求控件对自身的数据进行校验。
setError:当脚本在整个表单范围内发现存在错误的时候会调用setError请求控件显示错误信息,一般是将控件的外延设置为红色并给出提示。
setValue,getValue:表单引擎会将存储在数据库里的值通过这两个函数送给控件,由控件将取值显示出来或者读出控件正在绑定的取值。
getFormName:当控件绑定属性时,表单引擎会询问控件需要哪个属性的取值,收到这个值以后,表单引擎会调用setValue写入数值。
对于多对象控件,表单还会调用这些方法:
getSelected:返回当前空间中被用户选中的所有对象。
getAll:返回当前控件中显示出来的所有对象数组。
freshData:根据给定的查询条件刷新表单,如果没有给定则使用默认的查询条件。
小结
本章是在入门插件的基础上重点介绍了如何利用DWF提供的EditBox内部组件自动识别控件的属性,并自动产生属性编辑区对应输入界面的方法,使用EditBox的要点是:
在控件vue文件中的<template>内增加<EditBox>标签并配置参数。
在脚本部分通过import引入_EditBox.vue文件和EditBox的component组件。
引入DWF表单引擎传入的prop参数,以便EditBox作为标签参数绑定。
如果存在DWF无法识别的参数,用户可以在EditBox内增加slot标签实现自己的配置内容,下一章将结合数据绑定的实现介绍如何实现控件独有的配置界面。
本章在最后还介绍了控件应用端的一些额外函数,当控件需要和DWF数据绑定并进行交互的时候这些函数就会被调用,接下来在表单建模进阶里将会介绍控件如何与后台数据交互。
示例代码附件
建模端进阶控件:
应用端进阶控件: