达观RPA实战-自定义控件基础

一、应用背景

当标准控件和实际需求相差较大时，可以设计自定义控件。

或者有些通用功能，也可以做成自定义控件调用，如EXCEL文件表头填充

或者是有些标准控件实际运行会出错，无法解决，如FTP下载控件。

二、知识介绍

在开始开发自定义控件前，先简要介绍几个相关知识:

（一）自定义控件开发的入口

自定义控件开发的入口隐藏得比较深，开发平台的首页没有直接展示，需要创建一个可视化流程或在某个已创建好的可视化流程中才能打开。

打开一个可视化流程后，依次点击菜单栏中——文件——自定义控件，会展示一个控件中心，控件中心中有本地控件库和已发布控件库。本地控件库中有自己创建的控件库。

（二）自定义控件开发顺序

应该是：创建控件库，再创建控件

（三）自定义控件开发界面

创建自定义控件后，编辑区控件主要有控件配置、功能代码两部分，控件配置主要负责设计自定义控件的可视化表单，功能代码主要负责设计自定义控件的生成代码。

1.JSON格式的控件配置

在控件配置左侧区域填写JSON配置，右侧区域会根据配置实时生成可视化表单预览。

（1）新建自定义控件时，会自动生成所有的基础 Field以方便使用。

{"fieldGroups":[
	{"title":"控件标题","fields":[
		{"name":"data1","value":"默认值","type":"String","title":"这里是输入框","required":true,"element":"RpaInput"},
		{"name":"data2","value":"True","type":"Boolean","title":"这里是多选框","element":"RpaCheckbox","params":{"label":"可以点击切换"}},
		{"name":"data3","value":"show","type":"String","title":"这里是单选框","element":"RpaRadio","params":{"options":[{"name":"显示","value":"show"},{"name":"隐藏","value":"hide"}]}},
		{"name":"data4","value":"","type":"String","condition":[["&{data3}","show"]],"title":"我可以根据单选框显示隐藏","element":"RpaInput"},
		{"name":"data5","value":"","type":"String","title":"这里可以选择颜色","element":"RpaColorInput"},
		{"name":"data6","value":"","type":"String","title":"这里可以选择文件","element":"RpaFileInput","params":{"placeholder":"请选择路径"}},
		{"name":"data7","value":"","type":"String","title":"这里可以选择文件夹","element":"RpaFileInput","params":{"type":"dir","placeholder":"请选择路径"}},
		{"name":"data8","value":"","type":"String","title":"这里是下拉选择框","element":"RpaSelect","params":{"options":[{"name":"香蕉","value":"banana"},{"name":"苹果","value":"apple"},{"name":"梨子","value":"pear"}]}}]}],
	"return":"String"
}

代码中几个key的解释：

[1] fieldGroups表示控件表单的大类，为方便表达，我们将fieldGroups的类型定义为Group[]，后面的[]表示它是一个数组类型，Group表示表单中的一个块。

Interface Group{title:string;fields:Field[];}

[2]fields表示块中的框，它的类型是Field[]，这表示它是个类型为Field的数组.

Field 可大致分为预制 Field和基础 Field， 它们都是继承自CFBase 类型,它们CFBase中的字段。

CFBase的定义如下：

Interface. CFBase{
	//【可选】field 名称，在生成python代码时会用到
	name:string;
	//【可选】field 默认值
	value:string;
	//【可选】field 类型
	type:FieldType;
	//【可选】field表单 是否必填
	required?:boolean;
	//【可选】field表单 名称
	title?:string;
	//【可选】是否隐藏
	condition?:[string,string][];
}

[2.1]type表示当前框依赖的类型，通过它可以引用到别的有相同返回值类型的控件，将类型记为FieldType

FieldType常用类型：

• "Any"  //列表或元组等对象
• "Boolean"
• "String"
• "Number"
• "Excel"

[2.2]condition表示当前框的显示条件，如果没有该字段，表示当前框一直显示。

如果填写了该字段，它接受一个数组，数组里的每一个值又是一个长度为2的字符串类型数组，我们记为[string, string][]，控件中心会查看每个数组中两个字符串的值是否都相等，如果都相等，则会显示当前框。

如下：// 当 data1 的值为 True 且 data2 的值为 show 时，当前框才显示

"condition":[["&{data1}","True"],["&{data2}","show"]]

（2）预制 Field

上文中提到Field 可大致分为预制 Field和基础 Field。预制Field指的是达观平台中已经预先定义好的Field.包含隐藏字段，这些隐藏字段同样可以在功能代码区直接使用。

【注意】为避免字段冲突。同一控件中，每种预制 Field最多使用一次，且自定义字段不能和已使用预制 Field的隐藏字段重名。

预制字段主要有：截图组件、屏幕定位、捕获器，如下

{"fieldGroups":[{
	"title":"预制 Field",
	"fields":[{
			"title":"截图组件",
			"element":"RpaScreenPreset",
			"params":{"preview":true,"title":"获取截图"}
		},{
			"title":"屏幕定位",
			"element":"RpaPositionPreset",
			"params":{"title":"获取屏幕位置"}
		},{
			"title":"捕获器",
			"element":
			"RpaInspectorPreset"
		}]
	}]
}

2.Python模板代码

在功能代码左侧区域上半部分填写Python模板代码，右侧区域操作可视化表单预览，左侧区域下半部分会根据Python模板和可视化表单实时生成Python代码。

(1)基础 Field

print('输入框值:',&{data1})
print('多选框值:',&{data2})
print('单选框值:',&{data3})
print('可以隐藏的输入框值:',&{data4})
print('颜色值:',&{data5})
print('文件路径:',&{data6})
print('文件夹路径:',&{data7})
print('下拉选择框值:',&{data8})

(2)预制Field

//截图组件隐藏字段
print('截图左上角横坐标: ',&{x0})
print('截图左上角纵坐标: ',&{y0})
print('截图右下角横坐标: ',&{x1})
print('截图右下角纵坐标: ',&{y1})
print('截图名字: ',&{localImageName})
print('截图路径: ',&{localImagePath})
//获取桌面坐标隐藏字段
print('鼠标点击位置的横坐标: ',&{x})
print('鼠标点击位置的纵坐标: ',&{y})
//捕获器隐藏字段
print('捕获元素的属性: ',&{selectorList})
print('元素选择器转义字符串: ',&{selector})
print('元素选择器原始字符串: ',&{selectorEscape})
print('元素控件类型: ',&{ControlType})
print('元素所在窗口名: ',&{WindowName})
print('元素所在窗口类名: ',&{WindowClassName})
print('元素左上角横坐标: ',&{x0})
print('元素左上角纵坐标: ',&{y0})
print('元素右下角横坐标: ',&{x1})
print('元素右下角纵坐标: ',&{y1})
print('捕获元素所有上层元素的属性列表: ',&{nodeDictList})

3.自定义控件的返回值

return表示当前控件的返回类型，它的类型为FieldType,下面[2.1]会详细说明

该字段可选，如果不填，表示当前控件没有返回值

{

"fieldGroups":  [],

"return":"String"

}

功能代码模板中，返回值是在最后一句，如下图是创建一个自定义的ftp连接控件，最后返回的是ftp对象

（四）自定义控件的使用

在进行自定义控件开发后，可视化开发的控件区中，创建的自定义控件库和下面的自定义控件。