对象操作API

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

共有的API

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

  1. export interface IWinControl extends IWinContainer {
  2.   //methods
  3.   click(x?: number, y?: number, mousekey?: number): Promise<void>;
  4.   dblClick(x?: number, y?: number, mousekey?: number): Promise<void>;
  5.   wheel(value: number): Promise<void>;
  6.   exists(time: number): Promise<boolean>;
  7.   hScroll(value: any): Promise<void>;
  8.   vScroll(value: any): Promise<void>;
  9.   property(propertyIds: PropertyIds): Promise<string | boolean | number>;
  10.   waitProperty(propertyIds: PropertyIds, value: string, timeoutSeconds: number): Promise<boolean>
  11.   moveMouse(x?: number, y?: number): Promise<void>;
  12.   drop(x?: number, y?: number): Promise<void>;
  13.   drag(x?: number, y?: number): Promise<void>;
  14.   pressKeys(keys: string): Promise<void>;
  15.   takeScreenshot(filePath: string): Promise<void>;
  17. //properties
  18.   text(): Promise<string>;
  19.   name(): Promise<string>;
  20.   hwnd(): Promise<number>;
  21.   x(): Promise<number>;
  22.   y(): Promise<number>;
  23.   height(): Promise<number>;
  24.   width(): Promise<number>;
  25.   enabled(): Promise<boolean>;
  26.   focused(): Promise<boolean>;
  27.   helpText(): Promise<string>;
  28.   labeledText(): Promise<string>;
  29.   value(): Promise<string>;
  30.   processId(): Promise<number>;
  31.   modelImage(options?: {encoding: 'buffer' | 'base64'}): Promise<string>  //base64 is the default
  32. }

具体每个操作和属性的帮助可以在模型管理器中找到。

每个对象自己的API

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

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

  1. export interface IWinCheckBox extends IWinControl {
  2.   check(value: boolean): Promise<void>;
  3.   checked(): Promise<boolean>;
  4. }

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

  1. export interface IWinComboBox extends IWinControl {
  2.   options(index: number): Promise<string>;
  3.   itemCount(): Promise<number>;
  4.   selectedName(): Promise<string>;
  5.   select(value: string | number): Promise<void>;
  6.   open(): void;
  7. }

窗口对象Window

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

  • activate(): 激活窗口，使窗口上浮到最上层。如果窗口处在最小化状态则无效。
  • close(): 关闭窗口。
  • maximize(): 最大化窗口。如果窗口处在最小化状态则无效。
  • minimize(): 最小化窗口，将目标窗口收起到任务栏。
  • restore(): 还原窗口，将窗口从最小化或最大化状态退出，恢复默认大小。

类型文件定义如下:

  1. export interface IWinWindow extends IWinControl {
  2.     activate(): Promise<void>;
  3.     close(): Promise<void>;
  4.     maximize(): Promise<void>;
  5.     minimize(): Promise<void>;
  6.     restore(): Promise<void>;
  7. }
灵活的调用窗口操作

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

方法一:

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

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

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

方法二:

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

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

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

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

虚拟控件API

虚拟控件是特殊的控件，因此它的操作不同于其它控件。它没有其它Windows控件共有的操作和属性，它只有下面的操作 和属性。

  2. export interface IWinVirtual {
  3.   click(x: number, y: number, mousekey: number): Promise<void>;
  4.   pressKeys(keys: string): Promise<void>;
  5.   wheel(value: number): Promise<void>;
  6. }

更多关于虚拟控件的说明： 虚拟控件 虚拟控件API