虚拟控件API

虚拟控件的API大致可分为三类：

  1. 基础操作API：与传统控件操作类似的通用方法，用于点击、双击、存在性检查、高亮、鼠标移动、键盘输入、截图等。
  2. 文字识别（OCR）相关API：通过OCR识别虚拟控件中的文字，并可对识别出的文字进行点击操作。
  3. 图像比较API：通过图像比对技术检查虚拟控件当前界面与预期图像是否一致，以实现视觉验证。

类型定义

JavaScript
Python
export interface Virtual {
    // 基础操作
    click(x?: number, y?: number, mousekey?: number): Promise<void>;
    dblClick(x?: number, y?: number, mousekey?: number): Promise<void>;
    exists(seconds: number): Promise<boolean>;
    highlight(duration?: number): Promise<void>;
    moveMouse(x?: number, y?: number, seconds?: number): Promise<void>;
    pressKeys(keys: string, opt?: PressKeysOptions | number): Promise<void>;
    rect(): Promise<Rect>;
    takeScreenshot(filePath?: string): Promise<string>;
    wheel(value: number): Promise<void>;
    modelImage(options?: {encoding: 'buffer' | 'base64'}): Promise<string | Buffer>;
    modelProperties(all?: boolean): {[x: string]: any};
    // OCR相关
    visualText(options?: { whitespace: boolean }): Promise<string>;
    clickVisualText(text: string, options?: { cache: boolean, x: number, y: number }): Promise<void>;
    // 图像比较相关
    checkImage(options?: {
        colorTolerance?: number,        //default to 0.1
        pixelPercentTolerance?: number, //default 1, means 1% 
        pixelNumberTolerance?: number,  //no default value
        ignoreExtraPart?: boolean       //default to false
        auto?: boolean                  //default to false
    }): Promise<void>; 
}
class Virtual:
   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 exists(seconds: int) -> bool:
   def highlight(duration: Optional[int] = None) -> None:
   def moveMouse(x: Optional[int] = None, y: Optional[int] = None, seconds: Optional[int] = None) -> None:
   def pressKeys(keys: str, opt: Union[PressKeysOptions, int] = None) -> None:
   def rect() -> Dict[str, int]:
   def takeScreenshot(filePath: Optional[str] = None) -> str:
   def wheel(value: int) -> None:
   def modelImage(options: Optional[Dict[str, str]] = {'encoding': 'base64'}) -> Union[str, bytes]:
   def modelProperties(all: Optional[bool] = False) -> Dict[str, Any]:
   # OCR相关
   def visualText(options: Dict[str, bool]) -> str:
   def clickVisualText(text: str, options: Dict[str, Union[bool, int]]) -> None:
   # 图像比较相关
   def checkImage(options: Optional[Dict[str, Union[float, bool]]] = None) -> None:

1. 基础操作API

这些方法的用法与Qt或Windows自动化的通用控件操作类似，可参考：

主要API如下：

  • click / dblClick：点击或双击虚拟控件内指定位置（坐标可选，不传则默认控件中心）。
  • exists(seconds: number)：在指定秒数内检查该虚拟控件是否存在。
  • highlight(duration?: number)：高亮显示该虚拟控件，辅助调试和定位。
  • moveMouse：将鼠标移动到虚拟控件内某点。
  • pressKeys：在该控件中输入特定按键序列。
  • rect()：获取虚拟控件的矩形区域信息。
  • takeScreenshot(filePath?: string)：截取虚拟控件当前区域的屏幕图像。
  • wheel(value: number)：在虚拟控件区域内滚动鼠标滚轮。

2. OCR相关API

当界面中的文字控件无法直接识别时，可通过OCR从虚拟控件中提取文本，并基于文本进行点击操作。更多OCR原理与详情请参考图像字符识别（OCR）。

visualText(options?: {whitespace: boolean})

将虚拟控件区域内的图像进行OCR识别，并返回识别出的文本字符串。

参数:

  • options: （可选）识别选项
    • whitespace：boolean类型，指定是否识别空格，默认为 false。

返回值:

  • Promise<string> - 返回图片中的文本内容。

示例代码

JavaScript
Python
let text = await model.getVirtual("Virtual1").visualText();
console.log('识别出的文本:', text);
text = model.getVirtual("Virtual1").visualText()
print('识别出的文本:', text)

clickVisualText(text: string, options?: {cache: boolean, x: number, y: number})

使用OCR在虚拟控件中查找指定文字，并对该文字区域进行点击。

参数:

  • text：string - 待查找的文字（如“打开”）。
  • options: （可选）object类型，文字点击时的操作选项。
    • cache：boolean 类型，设置是否缓存识别信息，默认为 false。设置为 true 时，将复用上一次OCR结果，从而提高后续在同一控件内点击其他文字的响应速度。
    • x: number 类型，点击位置相对于文字区域左上角的水平偏移量（像素）。0 表示点击文字区域的水平中心位置。默认值为 0。
    • y: number 类型，点击位置相对于文字区域左上角的垂直偏移量（像素）。0 表示点击文字区域的垂直中心位置。默认值为 0。

返回值:

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

示例代码（复用OCR缓存信息）

以下示例演示了如何使用 cache 选项。以 Windows 自带的计算器为例，识别计算器的数字面板，并将其添加到模型中，对象名为 "Number pad"。

JavaScript
Python
(async function () {
   let numPad = model.getGeneric("Number pad").getVirtual();
   await numPad.clickVisualText('4', { cache: true });
   await numPad.clickVisualText('5', { cache: true });
   await numPad.clickVisualText('6', { cache: true });
})();
numPad = model.getGeneric("Number pad").getVirtual()
numPad.clickVisualText('4', { 'cache': True })
numPad.clickVisualText('5', { 'cache': True })
numPad.clickVisualText('6', { 'cache': True })
在此示例中，首次点击数字 "4" 时会进行 OCR 识别并稍作停留。随后点击 "5" 和 "6" 时，由于启用了缓存选项，因此无需再次进行 OCR 识别，操作速度更快。

异常处理

当在指定控件内未找到给定文字时，将抛出异常。可通过takeScreenshot()截屏和Ocr.getTextLocations()查看识别的文字块信息以进行诊断。

JavaScript
(async function () {
    let numPad = model.getGeneric("Number pad").getVirtual();
    let snapshot = await numPad.takeScreenshot();
    let blocks = await Ocr.getTextLocations(snapshot);
    console.log(JSON.stringify(blocks, null, 2))
})();

3. 图像比较API

通过图像比较技术检查虚拟控件当前画面与预期图像是否一致。可用于视觉验证，如检测控件的状态变化。

checkImage(options?: CompareOptions)

校验控件的图像是否与预期的参考图像匹配。如果存在差异，测试会抛出错误并显示图像间的差异。适用于自动化测试中的视觉校验，确保虚拟控件的图像呈现按预期进行。

参数:

  • options: （可选）object类型，用于配置图像比较的选项。这些选项与 Image.imageEqual 方法的参数相同，包含以下属性：
    • colorTolerance: number 类型，定义了在颜色匹配时允许的最大差异容忍度。默认值为 0.1。
    • pixelPercentTolerance: number 类型，定义了允许的最大像素百分比差异容忍度。默认值为 1，表示最多允许 1% 的像素差异。
    • pixelNumberTolerance: number 类型，定义了允许的像素数量差异容忍度。如果设置为0，则无差异容忍。
    • ignoreExtraPart: boolean 类型，用于指定是否忽略图像中的额外部分。默认为 false。
    • auto：boolean类型，如果设置为true，则根据图像特征自动识别两幅图片，并将它们缩放到一致的比例进行比较，默认适应到较小尺寸那张图片的比例。

返回值:

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

示例代码:

JavaScript
Python
await modelQt.getVirtual("button_image").checkImage({
    colorTolerance: 0.05,
    pixelPercentTolerance: 0.5
});
modelQt.getVirtual("button_image").checkImage({
    "colorTolerance": 0.05,
    "pixelPercentTolerance": 0.5
})

在这个例子中，checkImage 方法将会验证 "button_image" 虚拟控件的图像在颜色容忍度为 0.05 和像素百分比差异容忍度为 0.5% 的条件下是否与预设图像相匹配。如果存在超出这些指定容忍度的差异，测试将会抛出错误。

results matching ""

全部 API Walkthrough 其他

    No results matching ""