拖拽控件的方法选择

在 CukeTest 中提供了几种拖拽的方式，其各自适用于不同的场合。那么在什么场合选择哪种方式来完成拖拽呢？这篇文档将介绍这两类拖拽方式的选择依据，以及各个拖拽 API 的具体调用方式。

实现拖拽的不同方式

CukeTest 提供了几种不同的拖拽方式，可以分为：面向对象方式与面向屏幕操作方式。

• 面向对象方式：拖拽的是一个控件，作为测试对象的一个方法；坐标通常相对于控件左上角。
• 面向屏幕操作方式：完成一个拖拽的操作，需要起点与终点的屏幕坐标（以屏幕左上角为坐标原点），而无需在意被操作的目标。

具体的异同点可以参考以下表格:

拖拽动作的组成

将拖拽动作的整个流程拆解后如下:

1. 移动到起点位置
2. 按下鼠标左键（保持）
3. 移动到终点位置
4. 松开鼠标左键

拖拽控件的实现

最常见的情况是要拖拽一个控件到指定位置，那么每个控件都提供的对象操作 API——drag 和 drop 方法无疑是实现拖拽的最好途径。

drag(x, y, mouseKey)

此方法标志拖拽操作的开始，模拟在目标位置按下鼠标左键并保持不松手。

参数

• x: （可选）number 类型。拖拽的起点相对控件左上角的水平像素点。当 x 和 y 同时为 0 或缺省时，默认为点击控件中心。
• y: （可选）number 类型。拖拽的起点相对控件左上角的垂直像素点。
• mouseKey: （可选）number 类型。拖拽时使用的鼠标键，1 表示左键，2 表示右键。默认值为左键（1）。

返回值

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

drop(x, y, options)

拖拽操作的结束步骤，模拟将鼠标移至指定位置并释放。

参数

• x: （可选）number 类型。释放鼠标的位置相对控件左上角的水平像素点。当 x 和 y 同时为 0 或缺省时，默认为点击控件中心。
• y: （可选）number 类型。释放鼠标的位置相对控件左上角的垂直像素点。
• options: （可选）object 类型。自定义拖拽行为的配置对象。支持的选项包括：
  • duration: number 类型。鼠标移动到目标位置的持续时间，单位为秒。默认值为 1，即 1 秒。
  • mouseKeys: number 类型。在拖拽操作中使用的鼠标按键。1 表示左键，2 表示右键。默认值为左键（1）。

返回值

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

示例：拖拽桌面图标

假设我们要拖拽桌面上的“回收站”图标，水平向右移动 400 像素，那么在模型管理器中添加该控件后，使用如下脚本完成拖拽:

const { WinAuto } = require('leanpro.win');
const model = WinAuto.loadModel(__dirname + "\\model1.tmodel");

(async function () {
    let item = model.getListItem("回收站");
    await item.drag();
    await item.drop(400, 0);
})();

import os
from leanproAuto import WinAuto

modelWin = WinAuto.loadModel(os.path.dirname(__file__) + "/model1.tmodel")

if __name__ == "__main__":
    item = modelWin.getListItem("回收站")
    item.drag()
    item.drop(400, 0)

如果希望使用右键拖拽，可以将最后两行改为：

await item.drag(0, 0, 2);
await item.drop(400, 0, { mouseKey: 2 });

item.drag(0, 0, 2)
item.drop(400, 0, {"mouseKey": 2})

上述的脚本可以将桌面中的“回收站”图标水平向右移动 400 个像素。

鼠标拖拽的实现

除了对于控件的拖拽外，CukeTest 还提供了模拟用户鼠标操作的拖拽方式，由 leanpro.common 中的 Mouse 模块完成。这种方式直接操作屏幕坐标，不依赖于特定控件。

方法说明

• Mouse.move(x, y): 移动鼠标到屏幕坐标 (x, y)。
• Mouse.keyDown(key): 按下鼠标键。
• Mouse.keyUp(key): 松开鼠标键。
• Mouse.drag(x, y, mouseKey): 在按下鼠标键的状态下，拖拽（移动）到新的屏幕坐标 (x, y)。
• Mouse.drop(x, y, {duration, mouseKey}): 在指定位置释放拖拽操作。

样例

假设使用模拟操作的方式完成上一节中对于“回收站”图标的操作，那么应该写成如下:

const { Mouse } = require('leanpro.common');
const { WinAuto } = require('leanpro.win');
const model = WinAuto.loadModel(__dirname + "\\model1.tmodel");

(async function () {
    let item = model.getListItem("回收站");
    // 获取控件中心点的屏幕坐标
    let x = await item.x();
    let y = await item.y();

    await Mouse.move(x, y);
    await Mouse.keyDown(1);
    await Mouse.move(x + 400, y); // 拖拽至水平向右 400 像素的位置
    await Mouse.keyUp(1);
})();

import os
from leanproAuto import WinAuto, Mouse

modelWin = WinAuto.loadModel(os.path.dirname(__file__) + "/model1.tmodel")

if __name__ == "__main__":
    item = modelWin.getListItem("回收站")
    # 获取控件中心点的屏幕坐标
    x = item.x()
    y = item.y()

    Mouse.move(x, y)
    Mouse.keyDown(1)
    Mouse.move(x + 400, y) # 拖拽至水平向右 400 像素的位置
    Mouse.keyUp(1)

注意: 在这种方式中，x 和 y 参数代表的是屏幕坐标系中的绝对位置，需要传入具体坐标值，从而实现更为灵活的拖拽操作。

通过对比不同方法的特点和适用场景，您可以更有效地选择合适的拖拽方式来满足测试需求。