对象操作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 ""