对象操作API

对象操作API的方法分为两类，操作和属性。操作对控件做实际的动作，属性是获得控件的运行时属性。因为控件访问是异步的，所以获取属性也是以方法的形式，即调用时需要加上括号”()”，并且返回目标值的Promise对象——Promise<T>，需要在调用前加上await关键字来取得Promise中的结果。

阅读API文档前…

API语法说明

Qt的API文档建立在leanpro.qt的类型文件上（比如可以进入leanpro.qt.d.ts类型定义文件中查看API的调用方式），因此采用的是TypeScript语法，下面会根据阅读文档所需知识进行简单的介绍，如果希望进一步了解，可以前往TypeScript中文介绍了解更多相关语法。

首先是当前类的名称，在这里是IQtControl，全称可以理解为Interface of Qt Control，代表广义的Qt控件的接口定义。

其次是基类，代表当前类扩展自哪个基类，扩展代表会继承基类中的属性和方法。这里扩展自容器类IQtContainer，容器包含了各种获取对象API，这样的扩展可以实现链式的对象获取。

比如取得“Table OverView”窗口中的”sheet1”表格里的”Family”单元格的完整调用可以写作:
model.getWindow("Table Overview").getTable("sheet1").getTableItem("Family");
CukeTest在实际生成控件调用代码时会进行优化，所以我们平时不会看到这么长的调用。

最后就是当前类的操作方法和属性方法，操作方法和属性方法之间空了一行表示区分。()中代表了传入的参数个数，参数的格式为[argName]:[argType]，如果:前有?，代表该参数有缺省值，即使为空也不影响运行。方法的尾部（即最后一个:后面）代表方法的返回值，Promise<T>表示该方法是一个异步方法，只有T则代表是同步方法。

这里的T表示类型名称，比如void、string、number等。

各个类的关系

在CukeTest中，几个类之间的扩展关系大致如下:

最底层基类，容器类IQtContainer，包含获取自动化对象的方法；
第二层基类，基本控件类IQtControl，包含了各个控件通用的操作和属性方法；
具体控件类，有IQWindow、IQLabel…等等一系列具体Qt控件，除了扩展而来的方法外，大部分控件都包含自己特有的操作和属性方法，来实现针对不同控件的自动化。

通用的API

不同类型的对象操作有不同的操作和属性。它们都有一些共用的操作和属性，无论是哪个控件都可以调用的，如下:

export interface IQtControl extends IQtContainer {
    click(x?: number, y?: number, mousekey?: number): Promise<void>;
    dblClick(x?: number, y?: number, mousekey?: number): Promise<void>;
    moveMouse(x?: number, y?: number): Promise<void>;
    wheel(value: number): Promise<void>;
    takeScreenshot():Promise<string>;
    rect(): Promise<Rect> 
}

click(x, y, mousekey): Promise<void>

发送点击信号，缺省为左键点击目标控件中心位置。

x: number类型，相对坐标的水平像素，缺省为水平中心；
y: number类型，相对坐标的垂直像素，缺省为垂直中心；
mouseKey: 鼠标左右键，1为左键，2为右键；缺省值为1；
返回值: 不返回任何值的异步方法。

dblClick(x, y, mousekey): Promise<void>

发送双击信号，缺省为左键双击目标控件中心位置。

x: number类型，相对坐标的水平像素；缺省为水平中心；
y: number类型，相对坐标的垂直像素；缺省为垂直中心；
mouseKey: number类型，鼠标左右键，1为左键，2为右键；缺省值为1；
返回值: 不返回任何值的异步方法。

wheel(value): Promise<void>

发送鼠标滚轮信号。

value: number类型，正值滚轮往前滚动，负值往后滚动。例如 1往前滚动一格，-1往后滚动一格
返回值: 不返回任何值的异步方法。

moveMouse(x, y): Promise<void>

将鼠标位置移至指定位置，x和y为相对控件位置的水平像素和垂直像素。

x: number类型，相对坐标的水平像素；
y: number类型，相对坐标的垂直像素；
返回值: 不返回任何值的异步方法。

rect(): Promise<Rect>

取得目标控件的形状与位置信息。

返回值: 返回一个Rect对象，包含控件的坐标信息x和y，宽度和高度信息width和height。

Rect类型

用于描述控件形状与位置信息的对象。在CukeTest中，所有控件都可以用一个矩形(Bounding Rectangle)来描述位置和形状信息，Rect对象包含以下属性:

x: number类型，相对坐标的水平像素；
y: number类型，相对坐标的垂直像素；
width: number类型，水平宽度，单位为像素；
height: number类型，垂直高度，单位为像素；

本篇只介绍了对象操作的基本概念和两个基类的方法，更多关于API介绍的文档可以继续阅读下一篇：基础类型对象的API。

另外，具体每个操作和属性的定义都可以在模型管理器中找到，也可以打开CukeTest中自带的Qt自动化API库的类型文件——leanpro.qt的类型文件进行查找，具体方法可以查看更多API介绍一节的介绍。

API调用技巧

同步方法与异步方法的区分技巧

在IQContainer接口类中定义了获取对象的API，如下:

export interface IQtContainer {
    parent: IQtContainer;
    getGeneric(...conditions: ConditionFilter[]): IQtControl;
    getWindow(...conditions: ConditionFilter[]): IQWindow;
    getButton(...conditions: ConditionFilter[]): IQButton;
    ......
    getTable(...conditions: ConditionFilter[]): IQTable;
    getTableItem(...conditions: ConditionFilter[]): IQTableItem;
    getTree(...conditions: ConditionFilter[]): IQTree;
    getTreeItem(...conditions: ConditionFilter[]): IQTreeItem;
    getVirtual(...conditions: ConditionFilter[]): IVirtual;
}

如果和上节中的对象操作API的返回值比较可以立刻注意到，获取对象API的返回值都是直接的数据类型，而不是Promise<T>，这代表这些都是同步方法，即不需要添加await关键字即可取到返回结果。而对象操作API中也有一个特别的同步方法，就是属于Table、List、Tree控件的getItem方法，它也是对象操作API中唯一一个同步方法。

看到这里你可能有点意识到了，没错，CukeTest中同步方法和异步方法从命名上就有区别，含get-前缀的方法是同步方法，无需await关键字；而没有这个前缀的是异步方法，不加await的话只会返回一个Promise对象，加上await才是正确的返回值。

value()、text()与data()方法的区别

你可能会注意到，几乎每个控件都有获取控件信息的方法，比如标签控件Label的text()方法、文本框控件Edit的value()方法、表格控件Table的data()方法，都是获取控件内容的方法。那么它们之间的区别呢？主要是根据目标数据不同的性质决定的:

text(): 目标控件中的数据是不可变的，比如标签、按钮、菜单项等等，属于在运行过程中不会轻易变动的持久数据；
value(): 目标控件中的数据是可编辑的，比如输入框、单元格等等，属于在运行中随时会发生修改的非持久数据；
data(): 目标控件中的数据比较复杂，比如表格、列表等等，作为视图组件，其中包含了很多子控件，会根据控件结构返回相应结构的数据。比如Table控件的data()方法返回一串二维数组，而List控件的data()方法返回一串一维数组。

按照以上规律，当你需要获取控件的内容时，可以先对控件的内容性质进行判断，接着就可以大致的猜出对应的方法了。