对象共有的方法和属性

下面介绍是每个控件（虚拟控件除外）都有的基础的操作和属性方法。这些方法不管被操作控件是何种控件（或者说都会被当作自定义控件Custom来对待），部分方法是基于模拟用户操作，部分是基于系统提供的底层Accessibility API完成的操作。

类型定义文件

这些方法都写在控件的基类上，可以点击leanpro.win库查看，定义如下:

export interface IWinControl extends IWinContainer {
    click(x?: number, y?: number, mousekey?: MouseKey): Promise<void>;
    dblClick(x?: number, y?: number, mousekey?: MouseKey): Promise<void>;
    moveMouse(x?: number, y?: number): Promise<void>
    wheel(value: number): Promise<void>;
    exists(time: number): Promise<boolean>;
    hScroll(value: number | ScrollAmount): Promise<void>;
    vScroll(value: number | ScrollAmount): Promise<void>;
    property(propertyIds: PropertyIds): Promise<string | boolean | number | Rect>;
    waitProperty(propertyIds: PropertyIds, value: string, timeoutSeconds: number): Promise<boolean>
    drop(x?: number, y?: number): Promise<void>;
    drag(x?: number, y?: number): Promise<void>;
    pressKeys(keys: string): Promise<void>;
    takeScreenshot(filePath?: string): Promise<void | string>;
    //properties
    type(): Promise<string>;
    text(): Promise<string>;
    name(): Promise<string>;
    hwnd(): Promise<number>;
    x(): Promise<number>;
    y(): Promise<number>;
    height(): Promise<number>;
    width(): Promise<number>;
    enabled(): Promise<boolean>;
    focused(): Promise<boolean>;
    helpText(): Promise<string>;
    labeledText(): Promise<string>;
    value(): Promise<string | number>;
    processId(): Promise<number>;
    rect(): Promise<Rect>;
    modelImage(options?: {encoding: 'buffer' | 'base64'}): Promise<string>  //base64 is the default
}

可能用到的类定义

以下是调用共有API时可能会使用到的一些类型定义。

Rect类

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

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

鼠标键枚举类：MouseKey

用于鼠标单击方法click()与双击方法dblClick()的一个枚举类，可以指定点击所使用鼠标按键使用时传入对应的数字即可。

这个枚举类中也包含部分键盘的控制键，但是通常不会用到。
类似的枚举类在鼠标操作库Mouse中也能看到。

enum MouseKey {
    LButton = 1, // 鼠标左键
    RButton = 2, // 鼠标右键
    MButton = 4, // 鼠标中键/滚轮键
    Ctrl = 8, // 键盘CTRL键 
    Shift = 16, // 键盘SHIFT键
    Alt = 32 // 键盘ALT键
}

控件属性名枚举类: PropertyIds

export enum PropertyIds {
    automationId = "automationId",
    name = "name",
    text = "text",
    url = "url",
    title = "title",
    handle = "hwnd",
    x = 'x',
    y = 'y',
    height = 'height',
    width = 'width',
    enabled = 'enabled',
    focused = 'focused',
    helpText = 'helptext',
    value = 'value',
    labeledText = 'labeledtext',
    processId = 'processid',
    rect = 'rect'
}

控件类型枚举类: ControlType

CukeTest中可以识别到的所有控件类型，可以用于getControls()方法中指定控件类型，或者调用控件的type()方法返回结果的类型也都在这个枚举类中。

enum ControlType {
    Button = 'Button',
    Calendar = 'Calendar',
    CheckBox = 'CheckBox',
    ComboBox = 'ComboBox',
    Custom = 'Custom',
    DataGrid = 'DataGrid',
    DataItem = 'DataItem',
    Document = 'Document',
    Edit = 'Edit',
    Group = 'Group',
    Generic = 'Generic',
    Header = 'Header',
    HeaderItem = 'HeaderItem',
    Hyperlink = 'Hyperlink',
    Image = 'Image',
    List = 'List',
    ListItem = 'ListItem',
    MenuItem = 'MenuItem',
    MenuBar = 'MenuBar',
    Menu = 'Menu',
    Pane = 'Pane',
    RadioButton = "RadioButton",
    ScrollBar = 'ScrollBar',
    Slider = 'Slider',
    Spinner = 'Spinner',
    Tab = 'Tab',
    TabItem = 'TabItem',
    Table = 'Table',
    Text = 'Text',
    Thumb = 'Thumb',
    ToolBar = 'ToolBar',
    Tree = 'Tree',
    TreeItem = 'TreeItem',
    Window = 'Window',
    //virtual types
    TableRow = 'TableRow',
    TreeCell = 'TreeCell',
    Virtual = 'Virtual'
}

操作方法定义

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

鼠标点击控件，可以通过传入参数修改点击的相对位置（偏移量）和使用的鼠标键。

• x: number类型，点击位置相对控件左上角的水平像素点，0代表控件的水平中点位置，缺省值为0;
• y: number类型，点击位置相对控件左上角的垂直像素点，0代表控件的垂直中点位置，缺省值为0;
• mouseKey: MouseKey类型，操作的鼠标键，缺省为1，即鼠标左键。

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

鼠标双击控件，与click()方法的调用方式一致，通过传入参数修改点击的相对位置（偏移量）和使用的鼠标键。

• x: number类型，点击位置相对控件左上角的水平像素点，0代表控件的水平中点位置，缺省值为0;
• y: number类型，点击位置相对控件左上角的垂直像素点，0代表控件的垂直中点位置，缺省值为0;
• mouseKey: MouseKey类型，操作的鼠标键，缺省为1，即鼠标左键。

moveMouse(x, y): Promise<void>

移动鼠标光标到控件的相对位置，缺省移动到控件中心。

• x: number类型，点击位置相对控件左上角的水平像素点，0代表控件的水平中点位置，缺省值为0;
• y: number类型，点击位置相对控件左上角的垂直像素点，0代表控件的垂直中点位置，缺省值为0;

wheel(value): Promise<void>

滚动鼠标滚轮，输入参数的单位为滚轮滚动的刻度。

• value: number类型，单位为一个滚轮刻度。

exists(time): Promise<boolean>

检查控件是否存在，输入参数为检查等待的最长时间（超时时间）。缺省调用只会检查一次而不会重试与等待。

• time: number类型，超时时间，单位为秒，当为0时不会重试和等待，缺省参数为0。
• 返回值: 异步的返回控件是否存在，true为存在，false为不存在。

hScroll(value): Promise<void>

在控件上进行水平滚动，即Horizontal Scroll，参数为滚动的百分比。

• value: number类型，为滚动的百分比，0为滚动到顶部，100为滚动到底部。

vScroll(value): Promise<void>

在控件上进行垂直滚动，即Vertical Scroll，参数为滚动的百分比。

• value: number类型，为滚动的百分比，0为滚动到顶部，100为滚动到底部。

property(propertyIds): Promise<string | boolean | number | Rect>

这个方法比较特殊，虽然属于操作方法，但是却是获取指定属性的方法，传入属性名，返回对应的属性值。比如对于某个控件，调用方法.property("rect")其实就等同于直接调用属性方法.rect()，两个操作返回的值始终是相同的。

• propertyIds: propertyIds类型，控件属性的名称。
• 返回值: 异步的返回属性名对应的各种类型的属性值，包括string、number、boolean、Rect类型等等，取决于propertyIds。

waitProperty(propertyIds, value, timeoutSeconds): Promise<boolean>

与上面的property()方法类似，但是会等待直到属性出现某值，返回值表示是否成功等到该值出现。

• propertyIds: propertyIds类型，控件属性的名称。
• value: string类型，期望的值。
• timeoutSeconds: number类型，超时时间，单位为秒。等待超时秒设置，缺省为10秒，-1将无限等待。
• 返回值: boolean类型，等待结果，true是成功等到该值，反之则是超出等待时间。

drag(x, y): Promise<void>

在控件位置按下鼠标左键，也就是拖拽操作的第一步，并等待松开鼠标的指令。传入的(x, y)为点击相对控件的坐标，当x和y同时为0或缺省时点击控件中心。

• x: （可选）number类型，拖拽起点相对控件的水平坐标偏移像素，左负右正。缺省为0。
• y: （可选）number类型，拖拽起点相对控件的水平坐标偏移像素，左负右正。缺省为0。
• 返回值: 不返回任何值的异步方法。

drop(x, y): Promise<void>

在控件位置松开鼠标左键，也就是拖拽操作的第二步。传入的(x, y)为点击相对控件的坐标，当x和y同时为0或缺省时点击控件中心。可以在A控件上执行drag()方法，在B控件上执行drop()方法，实现将A控件拖拽到B控件上的效果，具体文档可以查看拖拽的方法。

• x: （可选）number类型，拖拽起点相对控件的水平坐标偏移像素，左负右正。缺省为0。
• y: （可选）number类型，拖拽起点相对控件的水平坐标偏移像素，左负右正。缺省为0。
• 返回值: 不返回任何值的异步方法。

pressKeys(keys): Promise<void>

输入按键，模拟键盘输入。如果正在使用中文输入法，则可能会触发输入法而导致无法输入。

• keys: string类型，由键位码组成的字符串，具体可以参考附录: 输入键对应表。
• 返回值: 不返回任何值的异步方法。

takeScreenshot(filePath): Promise<string>

控件截图，可以传入路径来将截图保存到路径位置。

• filePath: （可选）string类型，截图的保存路径和文件名，如"./images/screenshot1.png"。
• 返回值: 异步的返回截图的base64字符串。

属性方法定义

需要注意的控件的属性方法都是异步的，在调用后CukeTest会与目标控件通信，获取控件当前的属性，即实时属性，而不是模型对象中的识别属性。下面列出的属性所有控件都支持，但不一定都有值，可以根据建议尝试类似的属性方法来获取目标属性。

type(): Promise<string>

控件的类型，可能的值如控件类型枚举类所示。

text(): Promise<string>

控件的文本内容，通常是可编辑的内容，比如文本输入框Edit、多行输入框Document等控件拥有这个属性。如果返回值不符合预期，可以尝试name()或者value()属性方法。

name(): Promise<string>

控件的名称，这个名称通常情况下与模型管理器中对象的识别属性Name相一致，因此几乎所有的控件都有这一属性的值。如果返回值不符合预期，可以尝试text()或者value()属性方法。

hwnd(): Promise<number>

控件所属的窗口句柄（Handle of WiNDow）。

x(): Promise<number>

控件的水平桌面坐标，返回值为number类型，单位为像素点。

y(): Promise<number>

控件的垂直桌面坐标，返回值为number类型，单位为像素点。

height(): Promise<number>

控件的高度，返回值为number类型，单位为像素点。

width(): Promise<number>

控件的宽度，返回值为number类型，单位为像素点。

enabled(): Promise<boolean>

控件是否可用。

focused(): Promise<boolean>

控件是否被聚焦/被选中，当控件被选中时会返回true，通常会用于验证控件是否被操作到。

helpText(): Promise<string>

控件的帮助文本，即鼠标悬停在控件上时出现的浮动提示消息的内容，通常在WPF、WinForm框架的应用中会遇到。

value(): Promise<string | number>

控件的值，比如滑动条控件Slider、滚动条控件ScrollBar会返回对应的数值。如果希望取得控件显示的名称或者提示文字，可以尝试text()或者value()属性方法。

processId(): Promise<number>

控件所属应用的进程号（Process Id）。

rect(): Promise<Rect>

控件的描述矩形，返回Rect类型，包含控件的x、y``height和width信息，定义Rect类型所示。