模拟桌面操作API

在CukeTest的leanpro.common库中提供了一套模拟鼠标、键盘和屏幕操作的对象：

• Mouse
• Keyboard
• Screen

由于操作是通过模拟实现的，因此可以全平台上使用。

用途

CukeTest中，有针对控件直接操作的对象识别高级API，有些时候，仍旧需要通过键盘和鼠标的一些组合操作完成自动化。因此CukeTest提供了一套模拟鼠标和键盘操作的对象：Mouse和Keyboard。它们能处理鼠标移动的目标位置没有控件，或对象操作API完成不了的功能。例如某些应用中的菜单是隐藏在屏幕边缘的，需要鼠标移至屏幕边缘才会展开，这个时候就需要使用直接的鼠标和键盘操作。

使得操作鼠标和键盘的自动化脚本可以写作:

Mouse.move(1920,1080);
Keyboard.keyDown("control");
Keyboard.keyTap("a");
Keyboard.keyUp("control");

另外，由于Mouse的移动、点击操作都建立在屏幕坐标系上，因此CukeTest另外提供了操作屏幕的对象Screen，不仅可以获取屏幕属性（分辨率等），还可以进行截屏操作。

Screen.capture();

注意，这些方法都是同步方法，不需要使用await。

鼠标自动化对象: Mouse

用于实现鼠标移动，以及各个鼠标按钮的点击、按下/释放的自动化对象。比如某些应用中的界面是隐藏在屏幕边缘的，需要鼠标移至屏幕边缘才会出现，那么这种场景就不好用控件操作来实现了。而Mouse对象正是为了解决这类问题而推出的。

类型文件定义

export class Mouse {
    static move(x: number, y: number): void;    
    static moveSmooth(x: number, y: number, seconds?: number): void;
    static drag(x: number, y: number, seconds?: number): void;
    static setDelay(delay: number): void;
    static position(): Point;
    static click(button: MouseKey): void;
    static doubleClick(button: MouseKey): void;
    static keyDown(button: MouseKey): void;
    static keyUp(button: MouseKey): void;
    static wheel(vertical: number, horizontal: number): void;
}
enum MouseKey {
    LButton = 1,
    RButton = 2,
    MButton = 4,
    Ctrl = 8,
    Shift = 16,
    Alt = 32
}
interface Point {
    x: number,
    y: number
}

API介绍

move(x, y): void

鼠标移动到目标位置，移动前会释放鼠标按键。

• x: number类型，桌面坐标的水平像素；
• y: number类型，桌面坐标的垂直像素；
• 返回值: 不返回任何值的同步方法。

moveSmooth(x: number, y: number, seconds?: number): void

平滑移动鼠标到目标位置，移动行为更接近人工操作.

• x: number类型，桌面坐标的水平像素；
• y: number类型，桌面坐标的垂直像素；
• seconds: （可选）number类型，动作完成的耗时，值越小动作越快。
• 返回值: 不返回任何值的同步方法。

drag(x: number, y: number): void

鼠标移动到目标位置，配合keyDown()与keyUp()完成拖拽操作。

• x: number类型，桌面坐标的水平像素；
• y: number类型，桌面坐标的垂直像素；
• seconds: （可选）number类型，动作完成的耗时，值越小动作越快。
• 返回值: 不返回任何值的同步方法。

setDelay(delay: number): void

所有的鼠标操作之间的都有10ms的等待时间，也可以使用此方法修改等待时间，单位为毫秒，

• delay: number类型，间隔时间，单位为毫秒。
• 返回值: 不返回任何值的同步方法。

position(): Point

获取鼠标位置。

• 返回值: Point类型。形如{x:100, y:100}

click(button: MouseKey): void

完成一次鼠标点击。

• button: MouseKey类型，可以查看类型文件定义，为枚举型，传入MouseKey.LButton和1效果一样。
• 返回值: 不返回任何值的同步方法。

doubleClick(button: MouseKey): void

完成一次鼠标双击。

• button: MouseKey类型，可以查看类型文件定义，为枚举型，传入MouseKey.LButton和1效果一样。
• 返回值: 不返回任何值的同步方法。

keyDown(button: MouseKey): void

按下鼠标按键，通常用于实现拖拽操作。

• button: MouseKey类型，可以查看类型文件定义，为枚举型，传入MouseKey.LButton和1效果一样。
• 返回值: 不返回任何值的同步方法。

keyUp(button: MouseKey): void

释放鼠标按键，通常用于实现拖拽操作。

• button: MouseKey类型，可以查看类型文件定义，为枚举型，传入MouseKey.LButton和1效果一样。
• 返回值: 不返回任何值的同步方法。

wheel(vertical: number, horizontal: number): void

滚动鼠标滚轮，不仅可以进行常规的垂直滚动，还可以进行水平滚动。

• vertical: number类型，垂直滚动的值，向上滚动为正，向下滚动为负。
• horizontal: number类型，水平滚动的值，向左滚动为正，向右滚动为负。
• 返回值: 不返回任何值的同步方法。

wheel()方法的精度比较高，因此在调用时可以适当的将参数取大一点，好观察到现象。

拖拽操作的脚本

实现拖拽操作的脚本如下:

mouse.move(0, 0);
mouse.keyDown(MouseKey.LButton);
mouse.drag(100, 100);
mouse.keyUp(1);

键盘自动化对象: Keyboard

与模拟鼠标相对应的就是模拟键盘操作了，与键盘相关的操作属于Keyboard对象。

类型文件定义

export class Keyboard {
    static Keys: Keys,
    static keyTap(key: string): void;
    static unicodeTap(keyCode: number): void;
    static keyDown(key: string): void;
    static keyUp(key: string): void;
    static setDelay(milliseconds: number): void;
    static typeString(str: string, cpm?: any): void;
}

API介绍

Keys

Keys是一个枚举对象，枚举了所有的按键，用于keyTap、keyDown、keyUp方法的参数。按键名和描述见下表。

对于字母键和数字键是直接使用同名的字符即可，因此没在下表列出。比如按下字母键b和数字键5直接传入参数"b"和"5"即可。

Windows徽标键: 作为Windows键盘特有的一个控制键，与Mac的cmd键一样，都可以使用"command"的按键名来使用。

keyTap(key): void

按下一个键。

• key: string类型，目标键的键值，可以参考Keys表。
• 返回值: 不返回任何值的同步方法。

keyDown(key): void

按住一个键。

• key: string类型，目标键的键值，可以参考Keys表。
• 返回值: 不返回任何值的同步方法。

keyUp(key): void

释放一个键。

• key: string类型，目标键的键值，可以参考Keys表。
• 返回值: 不返回任何值的同步方法。

setDelay(delay): void

控制每个键盘操作的间隔，默认为10ms。

• delay: number类型，间隔时间，单位为毫秒。
• 返回值: 不返回任何值的同步方法。

typeString(str, cpm): void

输入一串字符。

• str: string类型，需要输入的字符串。
• cpm(可选): number类型，”Character Per Minute”，即每分钟中输入的字符，控制输入字符从速度。

屏幕自动化对象: Screen

屏幕自动化对象Screen，用于获取屏幕属性，以及操作屏幕。

类型文件定义

类型文件定义如下:

export class Screen {
    static screenSize(): {width: number, height: number};
    static colorAt(x: number, y: number): string;
    static capture(rect?: Rect): Buffer;
    static captureToFile(filePath: string, rect?: Rect): void;
    static takeScreenshot(filePath: string, monitor?: number): string | void;
}

API介绍

screenSize(): {width: number, height: number}

获取屏幕尺寸，也就是分辨率大小。返回一个包含屏幕宽跟高的对象。

• 返回值: {width: number, height: number}，即包含屏幕宽跟高的对象，都为数字类型。

colorAt(x: number, y: number): string

获取某个坐标像素点的颜色，返回值为一串十六进制格式的RGB颜色代码字符串，形如"FFFFFF"。

• x: number类型，横坐标;
• y: number类型，纵坐标;
• 返回值: string类型，一串十六进制格式的RGB颜色代码字符串。

capture(rect?: Rect): Buffer

获取屏幕截图。如果指定了rect参数，则会只截取指定方框的截图。

• rect: （可选）Rect类型，具体定义详见Rect类型介绍;
• 返回值: Buffer类型。可以直接用于附件，或者使用Image.from()方法构造Image对象。

captureToFile(filePath: string, rect?: Rect): void

获取屏幕截图并保存为文件。filePath为路径以及文件名。如果指定了rect参数，则会只截取指定方框的截图。

• filePath: string类型，保存文件的路径以及文件名称，比如"./support/image1.png";
• rect: （可选）Rect类型，具体定义详见Rect类型介绍;
• 返回值: 不返回任何值。

takeScreenshot(filePath: string, monitor?: number): string

由原先的Util.takeScreenshot方法合并而来，获取屏幕截屏。详见takeScreenshot()方法介绍。

不推荐使用。