基础类型对象的API

在上一篇中我们了解了CukeTest中的容器类和控件基类，接下来就是针对各种不同的控件类的API介绍了。本篇文章中将介绍以下几个基础的控件类：

• 按钮控件: Button
• 窗口控件: Window
• 输入框控件: Edit/Text
• 单选按钮控件: RadioButton
• 复选框控件: CheckBox
• 组合框: ComboBox
• 进度条控件: ProgressBar
• 滑动条控件: Slider
• 滚动条控件: ScrollBar
• 菜单相关的控件和菜单栏选项控件: MenuBar & Menu & MenuItem
• 标签栏控件和标签页控件: Tab & TabItem

由于各个控件类因为是继承自IWintControl，因此每个控件类都拥有[通用控件](node_operations.html#common-control]的所有操作和属性方法。以CheckBox控件类举例：

CheckBox控件有一个操作方法——check()用于设置是勾选还是清除勾选; 一个属性方法checked()用于判断CheckBox的勾选状态。true表示勾选，false代表未勾选:

export interface IWinCheckBox extends IWintControl {
}

但实际上CheckBox除了这两个方法，还从IWintControl基类继承了所有的方法，所以CheckBox的方法实际上应该包含了基类的方法：

export interface IWinCheckBox extends IWintControl {
    toggleCheck(checkState: boolean): Promise<void>
    // 继承自基类的操作方法
    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>;
    checkState(): Promise<boolean>
    // 继承自基类的属性方法
    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
}

如果一个对象不包含任何操作和属性方法，代表它只适用其基类——也就是IWintControl和IWintContainer中的操作和属性方法而没有自己特有的，比如Button控件。

基础控件类介绍

按钮控件: Button

针对普通的按钮控件，模型管理器提供了Button对象类型。

export interface IWinButton extends IWintControl {
}

由于Button控件的操作和属性方法与基类IWintControl的一致，没有自己特有的方法，因此为空。它的操作方法可以参考容器类方法介绍。

窗口控件: Window

针对应用窗口控件，模型管理器提供了Window对象类型。

export interface IWinWindow extends IWintControl {
    activate(): Promise<void>;
    close(): Promise<void>;
    maximize(): Promise<void>;
    minimize(): Promise<void>;
    restore(): Promise<void>;
}

activate(): Promise<void>

激活目标窗口，使目标窗口出现在桌面最上层，避免被其它窗口遮盖。

• 返回值: 不返回任何值的异步方法。

close(): Promise<void>

关闭目标窗口。

• 返回值: 不返回任何值的异步方法。

maximize(): Promise<void>

最大化目标窗口。

• 返回值: 不返回任何值的异步方法。

minimize(): Promise<void>

最小化目标窗口。

• 返回值: 不返回任何值的异步方法。

restore(): Promise<void>

恢复目标窗口。当目标最小化以后可以使用这个方法恢复为正常状态。

• 返回值: 不返回任何值的异步方法。

输入框控件: Edit与Text

针对用于接收用户输入的输入框控件Edit，而多行输入框有时为Text。提供的操作方法和属性方法都是针对输入框中的值。

export interface IWinEdit extends IWintControl {
    set(value: string): Promise<void>;
    clearAll(): Promise<void>;
    readOnly(): Promise<boolean>;
}
export interface IWinText extends IWinControl {
    set(value: string): Promise<void>;
}

set(value): Promise<void>

设置输入框中的值。将目标输入框中的值替换为传入的字符串。

• value: String类型，期望写入到输入框的值；
• 返回值: 不返回任何值的异步方法。

clearAll(): Promise<void>

清除输入框中的值。

• 返回值: 不返回任何值的异步方法。

readOnly(): Promise<boolean>

当前输入框是否为只读。只读返回true，可读写返回false。

• 返回值: Promise<boolean>类型，需要使用await关键字取出其中的结果。

单选按钮控件: RadioButton

针对单选按钮的RatioButton控件，按照使用逻辑提供了选中和获取选中状态的方法。

export interface IWinRadioButton extends IWintControl {
    check(): Promise<void>;
    checked(): Promise<boolean>;
}

check(): Promise<void>

选中目标单选按钮。

• 返回值: 不返回任何值的异步方法。

checked(): Promise<boolean>

获取目标单选按钮的选中状态，true代表已选中，false代表未选中。

• 返回值: Promise<boolean>类型，代表目标复选框是否选中。需要使用await关键字取出其中的结果。

复选框控件: CheckBox

针对复选框控件的CheckBox控件，能够直接设定选中状态，当然也可以获取状态。

    export interface IWinCheckBox extends IWintControl {
        toggleCheck(checkState: boolean): Promise<void>
        checkState(): Promise<boolean>
    }

toggleCheck(checkState): Promise<void>

设置目标复选框的选中状态。

• checkState: Boolean类型，true代表选中复选框，false代表取消选中目标复选框。
• 返回值: 不返回任何值的异步方法。

checked(): Promise<boolean>

获取目标单选按钮的选中状态，true代表已选中，false代表未选中。

• 返回值: Promise<boolean>类型，代表目标复选框是否选中。需要使用await关键字取出其中的结果。

组合/下拉框: ComboBox

针对带下拉框的一类特殊输入框的ComboBox控件，提供了选择指定下拉选项的操作方法。

export interface IWinComboBox extends IWintControl {
    open(): Promise<void>;
    select(nameOrIndex: String | number): Promise<void>;
    options(index: number): Promise<string | string[]>;
    itemCount(): Promise<number>;
    selectedName(): Promise<string>;
}

open(): Promise<void>

展开下拉框，可以视作触发了目标右侧的▼按钮。

• 返回值: 不返回任何值的异步方法。

select(nameOrIndex): Promise<void>

• nameOrIndex: number或String类型。如果为数字，则会选中下拉框中相应索引位置的选项；如果为字符串，则会选择下拉框中相应名称的选项。
• 返回值: 不返回任何值的异步方法。

selecteddName(): Promise<string>

获取当前选中的值。

• 返回值: Promise<string>类型，代表当前选中的值。需要使用await关键字取出其中的结果。

options(): Promise<string[]>

获取目标组合框中所有可选选项的名称。

• 返回值: Promise<string[]>类型，即字符串数组，获取目标组合框中所有可选选项的名称。需要使用await关键字取出其中的结果。

itemCount(): Promise<number>

获取目标组合框中所有可选选项的数量。可以理解为options()方法返回数组的长度。 返回值: Promise<number>类型，异步的返回选项数量。

选值框: SpinBox

针对应用中带上下箭头的选值框SpinBox控件，为其提供了触发其增加/减少值的操作API。

SpinBox控件继承自Edit控件，也就是说它除了以下的方法外，还能够使用Edit控件的方法。这点可以从类型文件中看出来。

该控件的类型定义如下:

export interface IWinSpinBox extends IWinEdit {
    increment(): Promise<void>;
    decrement(): Promise<void>;
}

increment(): Promise<void>

使取值框的值增加一个单位，单位大小取决于应用中的设置。可以理解为触发了一次取值框中的上箭头。

• 返回值: 不返回任何值的异步方法。

decrement(): Promise<void>

使取值框的值减少一个单位，单位大小取决于应用中的设置。可以理解为触发了一次取值框中的下箭头。

• 返回值: 不返回任何值的异步方法。

进度条控件: ProgressBar

针对应用中的进度条所支持的控件，可以通过调用value()方法取得进度条的值。

由于进度条的值通常是受控于内部逻辑或者其它控件，因此不支持直接修改其值。

形状如下:

类型文件如下:

export interface IWinProgressBar extends IWintControl {
    value(): Promise<number>;
}

value(): Promise<number>

获取当前进度条中的值并返回。因为返回结果是数字，因此会省略百分比%号。

• 返回值: Promise<number>类型，需要使用await关键字取出其中的结果。

滑动条控件: Slider

针对用于接收用户设定的值的滑动条控件。

export interface IWinSlider extends IWintControl {
    setPosition(value: number): Promise<void>;
    position(): Promise<number>;
    maximum(): Promise<number>;
    minimum(): Promise<number>;
    readOnly(): Promise<boolean>;
}

setPosition(value): Promise<void>

设置滑动条的值，将滑块拖拽至指定值的位置，但不会超出最大值。

• value: number类型，将滑块拖拽至指定值的位置;
• 返回值: 不返回任何值的异步方法。

position(): Promise<number>

获取当前滑动条的值并返回。

• 返回值: Promise<number>类型，需要使用await关键字取出其中的结果。

maximum(): Promise<number>

获取当前滑动条的最大值并返回。

• 返回值: Promise<number>类型，需要使用await关键字取出其中的结果。

minimum(): Promise<number>

获取当前滑动条的最小值并返回。

• 返回值: Promise<number>类型，需要使用await关键字取出其中的结果。

滚动条控件: ScrollBar

针对操作滚动区域中的滚动条控件，但需要滚动操作时，识别到该区域的滚动条控件，再通过调用滚动条上的方法来完成区域的滚动操作是一种非常方便的选择。

滚动条控件实际上是一种特殊的滑动条。

类型文件如下:

export interface IWinScrollBar extends IWinControl {
    setValue(value: number): void; // Q: 是否为Promise<void>
    isTop(): Promise<boolean>;
    isBottom(): Promise<boolean>;
    lineUp(): Promise<void>;
    lineDown(): Promise<void>;
    pageUp(): Promise<void>;
    pageDown(): Promise<void>;
    scrollToTop(): Promise<void>;
    scrollToBottom(): Promise<void>;
}

setValue(value: number): Promise<void>

设置滚动条的值，将滑块拖拽至指定值的位置，但不会超出最大值。单位可以理解为滚轮格数。

• value: number类型，将滑块拖拽至指定值的位置;
• 返回值: 不返回任何值的异步方法。

lineUp(): Promise<void>

向上/左滚动一个单位，单位可以当作滚轮格数，也就是按下一次上/左方向键滚动的量。

• 返回值: 不返回任何值的异步方法。

lineDown(): Promise<void>

向下/右滚动一个单位，单位可以当作滚轮格数，也就是按下一次下/右方向键滚动的量。

• 返回值: 不返回任何值的异步方法。

pageUp(): Promise<void>

向上/左滚动一页，也就是按下一次PageUp键滚动的量。

• 返回值: 不返回任何值的异步方法。

pageDown(): Promise<void>

向下/右滚动一页，也就是按下一次PageDown键滚动的量。

• 返回值: 不返回任何值的异步方法。

scrollToTop(): Promise<void>

将滚动条滚动到顶部。

• 返回值: 不返回任何值的异步方法。

scrollToBottom(): Promise<void>

将滚动条滚动到底部。

• 返回值: 不返回任何值的异步方法。

isTop(): Promise<boolean>

滚动条是否处在顶部。

• 返回值: boolean类型，滚动条是否处在顶部。

isBottom(): Promise<boolean>

滚动条是否处在底部。

• 返回值: boolean类型，滚动条是否处在底部。

菜单相关的控件和菜单栏选项控件: MenuBar & Menu & MenuItem

针对应用中的菜单操作相关的有MenuBar、Menu和MenuItem三种控件。其中前两个控件都属于容器控件（菜单栏容器与展开菜单容器），实际可以点击的选项都是MenuItem控件。

export interface IWinMenuBar extends IWintControl {    
    itemNames(index:number) : Promise<string>;
    open(itemNameOrIndex: string | number): Promise<void>;
    //Get the menu item count
    itemCount(): Promise<number>;
}
export interface IWinMenu extends IWintControl {
    select(menuPath: string): Promise<boolean>;  // Q: 返回的boolean的含义
    itemCount(menuPath:string): Promise<number>;    // Q: 是否应该不需要传参的
    itemName(menuPath:string): Promise<string>;
    itemNames(): Promise<string[]>;
}
export interface IWinMenuItem extends IWintControl {
    invoke(): Promise<void>;
    open(): Promise<void>
}

菜单栏MenuBar的API介绍

itemNames(index) : Promise<string>

获取目标索引值的菜单项名称。

• index: number类型，目标菜单项的索引值。
• 返回值: Promise<string>类型，异步的返回目标索引值对应的菜单项名称。

open(itemNameOrIndex: string | number): Promise<void>

展开目标索引值的菜单项。

• index: number类型，目标菜单项的索引值; string类型，目标菜单项的名称。
• 返回值: 不返回任何值的异步方法。

itemCount(): Promise<number>

获取菜单栏中菜单项总数。

• 返回值: Promise<number>类型，异步的返回菜单项数量。

菜单容器Menu的API介绍

itemCount(): Promise<number>

获取菜单容器中菜单项总数。

• 返回值: Promise<number>类型，异步的返回菜单项数量。

itemName(menuPath): Promise<string>

获取目标索引值的菜单项名称。

• menuPath: number类型，目标菜单项的索引值。
• 返回值: Promise<string>类型，异步的返回目标索引值对应的菜单项名称。

itemNames(): Promise<string[]>

获取所有菜单项的名称。

• 返回值: Promise<string[]>类型，异步的返回菜单中所有菜单项的名称。

select(menuPath: string): Promise<boolean>

选中目标索引值的菜单项。

• menuPath: number类型，目标菜单项的索引值。
• 返回值: Promise<boolean>类型，异步的返回目标是否成功选中了。

菜单项MenuItem的API介绍

open(): Promise<void>

展开菜单项所在的菜单容器。

• 返回值: 没有任何返回值的异步方法。

invoke(): Promise<void>

点击/触发菜单项。建议先使用open()方法展开菜单，再进行点击。

• 返回值: 没有任何返回值的异步方法。

子菜单的点击方法:
对于一些需要悬停展开后才能点击到的子菜单项，可以先调用父菜单项上的.moveMouse()通用方法将鼠标移动到该位置上，再点击子菜单。
这是因为两次点击之前的鼠标轨迹是不能确定的，部分控件的点击是不会移动鼠标的，此时如果需要鼠标光标出现在确定的位置，则最好使用.moveMouse()来手动的移动光标。

标签栏控件和标签页控件: Tab & TabItem

针对应用中的标签页的控件，Tab和TabItem，进行标签页的切换。
关于标签栏控件的定义如下:

export interface IWinTab extends IWintControl {
    select(item: string | number): Promise<void>;
    activate(itemNameOrIndex: string | number): Promise<void>;
    tabNames(index: number): Promise<string[] | string>;
    findItem(nameOrIndex: string | number): Promise<IWinTabItem>;
    activeName(): Promise<string>;
    activeIndex(): Promise<number>;
    count(): Promise<number>;
    selectedItem(): Promise<string>;
}
export interface IWinTabItem extends IWintControl {
    activate(): Promise<void>;
    text(): Promise<string>;
    itemIndex(): Promise<number>;
}

findItem(itemNameOrIndex): IWinTabItem

获取指定标签页的自动化对象，传入标签页的索引值或标题。

• itemNameOrIndex: number或string类型，目标标签页的索引值或标签页标题。
• 返回值: TabItem类型，同步的返回一个TabItem类型的操作对象。

activate(itemNameOrIndex): Promise<void>

激活目标标签页，传入标签页的索引值或标题。

如果是TabItem上的activate()方法则不需要传入任何参数。

• itemNameOrIndex: number或string类型，目标标签页的索引值或标签页标题。
• 返回值: 不返回任何值的异步方法。

activateIndex(): Promise<number>

获取当前界面中被激活的标签索引值。

• 返回值: number类型，标签页索引值。

tabNames(index): Promise<string[] | string>

获取所有标签页的标题，如果传入数字，则获取对应索引值的标签页标题。

• index: number类型，目标标签页的索引值，默认值为-1，会获取全部标题。
• 返回值: 当index为-1时，为string[]，为所有标签页标题组成的字符串数组；当index为其它值时，为string，返回目标索引值对应的标签页标题。

count(): Promise<number>

获取标签栏中的标签页数量。

• 返回值: number类型，标签页的数量。

以下是TabItem对象的方法。

activate(): Promise<void>

激活标签页。

• 返回值: 不返回任何值的异步方法。

text(): Promise<string>

获取标签页标题。

• 返回值: string类型，返回标签页的标题。

itemIndex(): Promise<number>

获取标签页在整个标签栏中的次序。

• 返回值: number类型，返回标签页的索引值。