基础对象操作API介绍

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

由于各个控件类因为是继承自IWintControl，因此每个控件类都拥有通用控件的所有操作和属性方法。以CheckBox控件类举例：

CheckBox控件有一个操作方法——toggleCheck()用于设置勾选状态; 一个属性方法checkState()用于判断CheckBox的勾选状态。true表示勾选，false代表未勾选，indeterminate代表中间状态:

JavaScript
Python
export interface IWinCheckBox extends IWintControl {    
    toggleCheck(checkState: boolean | 'indeterminate'): Promise<void>
    checkState(): Promise<boolean | 'indeterminate'>
}
class WinCheckBox(WinControl):
	def check(checked: bool) -> None
	def checkState() -> Union[bool, str]
	def toggleCheck(checkState: Union[bool, str]) -> None
但实际上CheckBox除了这两个方法，还从IWintControl基类继承了所有的方法，所以CheckBox的方法实际上应该包含了基类的方法：
JavaScript
export interface IWinCheckBox extends IWintControl {
    
    // CheckBox的操作方法
    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, seconds?: 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 | string): Promise<string | boolean | number | Rect>;
	checkImage(options?: CompareOptions): Promise<void>;
	checkProperty(propertyName: string, expectedValue: string | number | boolean | RegExp, message: string): Promise<void>;
	checkProperty(propertyName: string, expectedValue: string | number | boolean | RegExp, options: {message: string, operation: any}): Promise<void>;
	waitProperty(propertyIds: PropertyIds, value: string, timeoutSeconds?: number/* default value 5 seconds */): Promise<boolean>;
	drop(x?: number, y?: number, seconds?: number): Promise<void>;
	drag(x?: number, y?: number): Promise<void>;
	pressKeys(keys: string, opt?: PressKeysOptions | number): Promise<void>;
	takeScreenshot(filePath?: string): Promise<void | string>;
	highlight(duration?: number);
    firstChild(controlType?: ControlType): Promise<IWinControl>;
	lastChild(controlType?: ControlType): Promise<IWinControl>;
	next(controlType?: ControlType): Promise<IWinControl>;
	previous(controlType?: ControlType): Promise<IWinControl>;
	parent(): Promise<IWinControl>;
	all(): Promise<IWinControl[]>;
	findControls(...conditions: ConditionFilter[]): Promise<IWinControl[]>; //used to be getControls
	modelImage(options?: {encoding: 'buffer' | 'base64'}): Promise<string | Buffer>;  //base64 is the default
	modelProperties(all?: boolean): {[x: string]: any};
	allProperties(): Promise<object>;
	doDefaultAction(): Promise<void>;
	rawText(): Promise<string>

    // CheckBox的属性
    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>;
	visible(): Promise<boolean>;
}
如果一个对象不包含任何操作和属性方法，代表它只适用其基类——也就是IWintControl和IWintContainer中的操作和属性方法而没有自己特有的，比如Button控件。

基础控件类介绍

按钮控件: Button

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

JavaScript
Python
export interface IWinButton extends IWintControl {

}
class WinButton(WinControl):
	...

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

窗口控件: Window

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

JavaScript
Python
export interface IWinWindow extends IWintControl {
    activate(): Promise<void>;
    close(): Promise<void>;
    maximize(): Promise<void>;
    minimize(): Promise<void>;
    restore(): Promise<void>;
    isModal(): Promise<boolean>;
    interactionState(): Promise<string>;
    visualState(): Promise<string>;
}
class WinWindow(WinControl):
	def activate() -> None
	def close() -> None
	def maximize() -> None
	def minimize() -> None
	def restore() -> None
    def isModal() -> bool
	def interactionState() -> str
	def visualState() -> str

activate(): Promise<void>

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

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

close(): Promise<void>

关闭目标窗口。

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

maximize(): Promise<void>

最大化目标窗口。

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

minimize(): Promise<void>

最小化目标窗口。

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

restore(): Promise<void>

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

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

isModal(): Promise<boolean>

获取指定窗口是否为模态窗口的值。isModal返回false不一定代表窗口不是模态窗口，推荐使用interactionState来判断。

  • 返回值: Boolean类型，它会返回一个布尔值（true 或 false），表示窗口是否为模态窗口。如果返回值为 true，则表示该窗口是一个模态窗口；如果返回值为 false，则表示该窗口可能不是一个模态窗口。

interactionState(): Promise<string>

表示窗口的交互状态。

  • 返回值: string类型，返回值可以是这些:
    • Running：窗口正在运行。这并不保证窗口已经准备好进行用户交互或正在响应。
    • ReadyForUserInteraction：窗口已经准备好进行用户交互。
    • BlockedByModalWindow：窗口被模态窗口阻塞。
    • Closing：窗口正在关闭。
    • NotResponding：窗口没有响应。

visualState(): Promise<string>

表示当前窗口的状态

  • 返回值：string类型，Minimized, Maximized或Normal。

在Windows环境中打开记事本，菜单栏点击【文件】选择【打开】来打开文件资源管理器窗口：

JavaScript
Python
let isModal
let interactionState
let visualState

isModal = await modelWin.getWindow("文件资源管理器").isModal()
console.log(isModal) // 返回true

interactionState = await modelWin.getWindow("文件资源管理器").interactionState()
console.log(interactionState) //返回 ReadyForUserInteraction

interactionState = await modelWin.getWindow("记事本").interactionState()
console.log(interactionState) //返回 BlockedByModalWindow

visualState = await modelWin.getWindow("文件资源管理器").visualState()
console.log(visualState) //返回 Normal
isModal = modelWin.getWindow("文件资源管理器").isModal()
print(isModal) # 返回True

interactionState = modelWin.getWindow("文件资源管理器").interactionState()
print(interactionState) # 返回 ReadyForUserInteraction

interactionState = modelWin.getWindow("记事本").interactionState()
print(interactionState) # 返回 BlockedByModalWindow

visualState = modelWin.getWindow("文件资源管理器").visualState()
print(visualState) # 返回 Normal

输入框控件: Edit与Document

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

JavaScript
Python
export interface IWinEdit extends IWintControl {
    set(value: string): Promise<void>;
    clearAll(): Promise<void>;
    readOnly(): Promise<boolean>;
}
export interface IWinDocument extends IWinControl {
    set(value: string): Promise<void>;
    clearAll(): Promise<void>;
    readOnly(): Promise<boolean>;
}
class WinEdit(WinControl):
	def set(value: str) -> None
	def clearAll() -> None
	def readOnly() -> bool
class WinDocument(WinControl):
	def set(value: str) -> None
	def clearAll() -> None
	def readOnly() -> bool
另外，文本框控件Text和容器控件Pane在一些情况下也是可编辑的，因此也提供了set方法，用法与Edit、Document一致。

JavaScript
Python
export interface IWinText extends IWinControl {
    set(value: string): Promise<void>;
}
export interface IWinPane extends IWinControl {
    set(value: string): Promise<void>;
}
class WinText(WinControl):
	def set(value: str) -> None
class WinPane(WinControl):
	def set(value: str) -> None

set(value): Promise<void>

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

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

clearAll(): Promise<void>

清除输入框中的值。

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

readOnly(): Promise<boolean>

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

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

单选按钮控件: RadioButton

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

JavaScript
Python
export interface IWinRadioButton extends IWintControl {
    check(): Promise<void>;
    checked(): Promise<boolean>;
}
class WinRadioButton(WinControl):
	def checked() -> Union[bool, str]
	def check() -> None

check(): Promise<void>

选中目标单选按钮。

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

checked(): Promise<boolean>

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

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

复选框控件: CheckBox

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

JavaScript
Python
export interface IWinCheckBox extends IWintControl {
    toggleCheck(checkState: boolean | 'indeterminate'): Promise<void>
    checkState(): Promise<boolean | 'indeterminate'>
}
class WinCheckBox():
	def check(checked: bool) -> None
	def checkState() -> Union[bool, str]
	def toggleCheck(checkState: Union[bool, str]) -> None
checkState是为了Windows复选框创建的类，支持的值有true|false|'indeterminate'三种，true代表选中复选框，false代表取消选中目标复选框。'indeterminate'代表中间值。因为Windows复选框有时候存在三种状态，无法直接用布尔型boolean表示。

toggleCheck(checkState): Promise<void>

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

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

checked(): Promise<checkState>

获取目标单选按钮的选中状态。

  • 返回值: Promise<checkState>类型。

组合/下拉框: ComboBox

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

JavaScript
Python
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>;
}
class WinComboBox(WinControl):
	def options(index: Optional[int]=None) -> Union[str, List[str]]
	def itemCount() -> int
	def selectedName() -> str
	def select(value: Union[str, int]) -> None
	def open() -> None

open(): Promise<void>

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

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

select(nameOrIndex): Promise<void>

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

selectedName(): Promise<string>

获取当前选中的值。

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

options(): Promise<string[]>

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

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

itemCount(): Promise<number>

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

选值框: Spinner

针对应用中带上下箭头的选值框Spinner控件，提供了与输入框Edit控件类似的输入、编辑和清空的方法。并另外提供了单步增加/减少值的操作API。

该控件的类型定义如下:

JavaScript
Python
export interface IWinSpinner extends IWinEdit {
    set(value: string): Promise<void>;
    clearAll(): Promise<void>;
    readOnly(): Promise<boolean>;
    increment(): Promise<void>;
    decrement(): Promise<void>;
}
class WinSpinner(WinControl):
	def set(value: str) -> None
	def clearAll() -> None
	def readOnly() -> bool
	def increment() -> None
	def decrement() -> None

set(value): Promise<void>

见set()方法。如果输入字符串会失效，因为控件只接受数值参数。

也可以使用pressKeys()方法完成输入。

clearAll(): Promise<void>

见clearAll()方法。

readOnly(): Promise<boolean>

见readOnly()方法。

increment(): Promise<void>

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

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

decrement(): Promise<void>

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

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

滑动条: Slider

用于滑动调整数值的滑动条控件。

JavaScript
export interface WinSlider extends WinControl {
    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>

获取滑动条的值。

  • 返回值: number类型，滑动条的值。

maximum(): Promise<number>

获取滑动条的最大值。

  • 返回值: number类型，滑动条的最大值。

minimum(): Promise<number>

获取滑动条的最小值。

  • 返回值: number类型，滑动条的最小值。

readOnly(): Promise<boolean>

滑动条是否可调整。

  • 返回值：boolean类型，是否可调整。

滚动条控件: ScrollBar

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

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

类型文件如下:

JavaScript
Python
export interface IWinScrollBar extends IWinControl {
    setValue(value: number): 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>;
}
class WinScrollBar(WinControl):
	def setValue(value: int) -> None
	def isTop() -> bool
	def isBottom() -> bool
	def lineUp() -> None
	def lineDown() -> None
	def pageUp() -> None
	def pageDown() -> None
	def scrollToTop() -> None
	def scrollToBottom() -> None

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类型，滚动条是否处在底部。

图片控件: Image

图片控件。

JavaScript
export interface IWinImage extends IWintControl {    
    visualText(): Promise<string>;
}

visualText(): Promise<string>

使用OCR识别图片中的文本。

  • 返回值: string类型，图片控件中的文本内容。

超链接控件。

JavaScript
export interface IWinLink extends IWintControl {    
    url(): Promise<string>;
}
export interface IWinHyperlink extends IWinLink {    
}

获取超链接指向的地址。

  • 返回值: string类型，链接的地址。

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

JavaScript
Python
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>;  
    
    itemCount(menuPath:string): Promise<number>; 
    itemName(menuPath:string): Promise<string>;
    itemNames(): Promise<string[]>;
}
export interface IWinMenuItem extends IWintControl {
    invoke(): Promise<void>;
    open(): Promise<void>
}
class WinMenuBar(WinControl):
	def itemNames(index: int) -> str
	def open(itemNameOrndex: Union[str, int]) -> None
	def itemCount() -> int
class WinMenu(WinControl):
	def itemCount(menuPath: str) -> int
	def itemName(menuPath: str) -> str
	def itemNames() -> List[str]
	def select(menuPath: str) -> bool
class WinMenuItem(WinControl):
	def invoke() -> None
	def open() -> None
菜单栏MenuBar的API介绍

itemNames(index) : Promise<string>

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

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

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

  • 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介绍

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

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

invoke(): Promise<void>

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

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

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

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

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

JavaScript
Python
export interface IWinTab extends IWintControl {
    activate(nameOrIndex: 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>;
}
export interface IWinTabItem extends IWintControl {
    activate(): Promise<void>;
    text(): Promise<string>;
    itemIndex(): Promise<number>;
}
class WinTab(WinControl):
	def activate(nameOrndex: Union[str, int]) -> None
	def tabNames(index: Optional[int]=None) -> Union[str, List[str]]
	def findItem(nameOrndex: Union[str, int]) -> "WinTabItem"
	def select(item: Union[str, int]) -> None
	def activeName() -> str
	def activendex() -> int
	def count() -> int
class WinTabItem(WinControl):
	def activate() -> None
	def text() -> str
	def itemndex() -> int

findItem(itemNameOrIndex): IWinTabItem

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

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

activate(itemNameOrIndex): Promise<void>

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

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

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

activateIndex(): Promise<number>

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

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

activateName(): Promise<string>

获取当前界面中被激活的标签名称。

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

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

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

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

count(): Promise<number>

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

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

以下是TabItem对象的方法。

activate(): Promise<void>

激活标签页。

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

text(): Promise<string>

重写自基类的text()方法，获取标签页标题。

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

校验获取到的标签页标题

JavaScript
Python
let title = await model.getTabItem("One").click();
assert.equal(title, 'One');
title = model.getTabItem("One").click()
assert title == 'One'

itemIndex(): Promise<number>

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

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

results matching ""

全部 API Walkthrough 其他

    No results matching ""