对象操作API

Windows对象操作API的方法分为两类，操作和属性。操作对控件做实际的动作，属性是获得控件的运行时属性。因为控件访问是异步的，所以获取属性也是以方法的形式，即调用时需要加上括号”()”，并且返回的是Promise。在async函数中可通过加await获得实际的值。

共有的API

不同类型的对象操作有不同的操作和属性。它们都有一些共用的操作和属性，如下：

JavaScript

Python

export interface IWinControl extends IWinContainer {
  //methods
	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);

  //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>;
	visible(): Promise<boolean>;
  
	//navigation methods
	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>
}

class WinControl(WinContainer):
	def click(x: Optional[int]=None, y: Optional[int]=None, mousekey: Optional[int]=None) -> None
	def dblClick(x: Optional[int]=None, y: Optional[int]=None, mousekey: Optional[int]=None) -> None
	def moveMouse(x: Optional[int]=None, y: Optional[int]=None, seconds: Optional[int]=None) -> None
	def wheel(value: int) -> None
	def exists(time: Optional[int]=None) -> bool
	def hScroll(value: int) -> None
	def vScroll(value: int) -> None
	def property(propertyds: str) -> Union[str, int, bool, Rect]
	def waitProperty(propertyds: str, value: str, timeoutSeconds: Optional[int]=None) -> bool
	def checkProperty(propertyName: str, expectedValue: Union[str, int, bool], optionsOrMessage: Optional[Union[str, TypedDict]]=None) -> "bool"
	def checkImage(options: Optional[any]=None) -> None
	def drop(x: Optional[int]=None, y: Optional[int]=None) -> None
	def drag(x: Optional[int]=None, y: Optional[int]=None) -> None
	def pressKeys(keys: str, opt: Optional[Union[int, PressKeysOptions]]=None) -> None
	def takeScreenshot(filePath: Optional[str]=None) -> Union[str, None]
	def highlight(duration: Optional[int]=None) -> None
	def type() -> str
	def text() -> str
	def name() -> str
	def hwnd() -> int
	def x() -> int
	def y() -> int
	def height() -> int
	def width() -> int
	def enabled() -> bool
	def focused() -> bool
	def visible() -> bool
	def helpText() -> str
	def labeledText() -> str
	def value() -> Union[str, int]
	def processId() -> int
	def rect() -> "Rect"
	def firstChild(controlType: Optional[str]=None) -> "WinControl"
	def lastChild(controlType: Optional[str]=None) -> "WinControl"
	def next(controlType: Optional[str]=None) -> "WinControl"
	def previous(controlType: Optional[str]=None) -> "WinControl"
	def parent() -> "WinControl"
	def findControls(*conditions: List[Union[str, Dict]]) -> List[WinControl]
	def modelmage(encoding: Optional[str]=None) -> Union[str, bytearray]
	def modelProperties(all: Optional[bool]=None) -> TypedDict
	def all() -> List[WinControl]
	def allProperties() -> TypedDict
	def doDefaultAction() -> None
	def rawText() -> str

具体每个操作和属性的帮助可以在模型管理器中找到。或者查看对象共有的方法和属性

每个对象自己的API

其它的对象因为是继承IWinControl，所以除了这些操作和属性外，还有一些其它的操作和属性。例如：

CheckBox控件有一个操作，check用于设置是勾选还是清除勾选，一个属性checked用于判断CheckBox的勾选状态：

JavaScript

Python

export interface IWinCheckBox extends IWinControl {
  check(value: boolean): Promise<void>;
  checked(): Promise<boolean>;
}

class WinCheckBox(WinControl):
	def check(checked: bool) -> None
	def checkState() -> Union[bool, str]
	def toggleCheck(checkState: Union[bool, str]) -> None

下面是ComboBox特有的方法和属性：

JavaScript

Python

export interface IWinComboBox extends IWinControl {
  options(index: number): Promise<string>;
  itemCount(): Promise<number>;
  selectedName(): Promise<string>;
  select(value: string | number): Promise<void>;
  open(): void;
}

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

窗口对象Window

窗口对象Window通常是一个应用的顶层控件（或者容器），因此为其提供了几个窗口操作的API:

activate(): 激活窗口，使窗口上浮到最上层。如果窗口处在最小化状态则无效。
close(): 关闭窗口。
maximize(): 最大化窗口。如果窗口处在最小化状态则无效。
minimize(): 最小化窗口，将目标窗口收起到任务栏。
restore(): 还原窗口，将窗口从最小化或最大化状态退出，恢复默认大小。
isModal(): 获取指定窗口是否为模态窗口的值。
interactionState(): 窗口交互状态，返回值可以是这些: Running, ReadyForUserInteraction, BlockedByModalWindow, Closing, NotResponding。
visualState(): 窗口状态，返回值为Minimized, Maximized或Normal。

详细的api说明参见：窗口控件: Window

类型文件定义如下:

JavaScript

Python

export interface IWinWindow extends IWinControl {
    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

灵活的调用窗口操作

虽然大部分情况下应用的顶层控件会是Windows控件，但是由于桌面应用框架的实现之间存在差异，有些应用的顶层控件可能是其它的容器，比如面板控件Pane、自定义控件Custom。那这种情况该如何进行窗口操作呢？实际上CukeTest中的窗口操作并不严格要求控件类型为Window，因此如果假设目标应用的顶层为Pane("新标签页")（Chrome窗口会被识别为Pane），那么有以下两种调用窗口操作方法的脚本写法:

方法一:

JavaScript

Python

await model.getPane("新标签页").maximize();

model.getPane("新标签页").maximize()

由于窗口操作不限制控件类型，因此这种写法是合法，但是存在一个问题是这种写法不支持代码提示，所以在弹出的指令中将看不到窗口操作的方法。但是在模型管理器中可以看到这些方法，直接复制即可。

因此推荐的还是下面一种写法。

方法二:

JavaScript

Python

await model.getWindow("新标签页").maximize();

model.getWindow("新标签页").maximize()

即使测试对象"新标签页"的控件类型为Pane，但是仍然可以通过getWindow()方法来获取到这个对象，从而对其进行窗口操作。

注意: 以上的操作是被允许的，但是假如目标控件并不是顶层控件，而是应用内的某一层容器，那么窗口操作理所当然的不会生效。

更多的控件的操作和属性的帮助可以在模型管理器中找到。

虚拟控件API

虚拟控件是特殊的控件，因此它的操作不同于其它控件。它没有其它Windows控件共有的操作和属性，更多关于虚拟控件的说明：虚拟控件

results matching ""

全部 API Walkthrough 其他

对象操作API

共有的API

每个对象自己的API

窗口对象Window

灵活的调用窗口操作

虚拟控件API

results matching ""

No results matching ""