虚拟控件API

虚拟控件的创建和使用

创建虚拟控件

使用虚拟控件

虚拟控件调用代码可通过以下几种方式生成：

  1. 在模型中定义

    你可以在对象模型中某个Windows控件对象或其他类型的对象下创建虚拟控件，相关信息请参见创建虚拟控件

  2. 描述式编程

    通过在代码中指定位置信息创建虚拟控件。详情请参考描述模式。

  3. 不带任何参数的getVirtual()方法

    详见控件的虚拟化

    在代码中你可以直接调用某个对象的getVirtual()方法而不带任何参数，这时它会返回一个虚拟控件对象。这个虚拟控件区域同该对象对应控件的大小一致。这种方式一般用来在某个控件上做图像识别或OCR操作。

    例如，针对Win10的计算器，你可以调用：

JavaScript
Python
let numPad = model.getGeneric("Number pad").getVirtual();
await numPad.clickVisualText('4');
numPad = model.getGeneric("Number pad").getVirtual()
numPad.clickVisualText('4')
这个例子从计算器应用的数字面板控件获得虚拟控件，并通过OCR识别上面的数字"4"来直接点击这个数字按钮。 注意：对于其它Windows版本的计算器应用，代码可能有所不同。

虚拟控件Virtual提供的方法

类型定义文件

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);
    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>;  //base64 is the default
    modelProperties(all?: boolean): {[x: string]: any};

    visualText(options?: {
        whitespace: boolean;
    }): Promise<string>; // use OCR get text in Virtual
    clickVisualText(text: string, options?: {
        cache: boolean,
        x: number,
        y: number
    }): Promise<void>; //click the specified text on the image using OCR
    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(self, x: Optional[int] = None, y: Optional[int] = None, mousekey: Optional[int] = None) -> None:
   def dblClick(self, x: Optional[int] = None, y: Optional[int] = None, mousekey: Optional[int] = None) -> None:
   def exists(self, seconds: int) -> bool:
   def highlight(self, duration: Optional[int] = None) -> None:
   def moveMouse(self, x: Optional[int] = None, y: Optional[int] = None, seconds: Optional[int] = None) -> None:
   def pressKeys(self, keys: str, opt: Union[PressKeysOptions, int] = None) -> None:
   def rect(self) -> Dict[str, int]:
   def takeScreenshot(self, filePath: Optional[str] = None) -> str:
   def wheel(self, value: int) -> None:
   def modelImage(self, options: Optional[Dict[str, str]] = {'encoding': 'base64'}) -> Union[str, bytes]:
   def modelProperties(self, all: Optional[bool] = False) -> Dict[str, Any]:
   def visualText(self, options: Dict[str, bool]) -> str:
   def clickVisualText(self, text: str, options: Dict[str, Union[bool, int]]) -> None:
   def checkImage(self, options: Optional[Dict[str, Union[float, bool]]] = None) -> None:
虚拟控件的API可以简单分为三类：

  1. 基础控件操作：这些API与其它自动化技术的提供的通用操作方法效果和调用方法都类似。因此这里不展开介绍，对于使用有疑问的可以参考：Qt通用控件操作和Windows通用控件操作。
    • click
    • dblClick
    • exists
    • highlight
    • moveMouse
    • pressKeys
    • rect
    • takeSnapshot
    • wheel
  2. 文字识别（OCR）操作：基于OCR技术，识别或定位虚拟控件中的文字内容。识别和定位的原理可以点击图像字符识别（OCR）了解详情。。
  3. 图像操作：基于图像比较技术，判断当前虚拟控件的截图是否和模型中保存的预期图像相同。比较的原理可以点击图像操作API了解详情。

visualText(options?: OcrOptions): Promise<string>

使用 OCR 技术从虚拟控件中提取文本信息。它会将控件区域的截屏图片上通过OCR识别所有的文字信息，并转换成文字返回。

  • options (可选): 一个包含以下属性的对象
    • whitespace：boolean类型，指定是否识别空格，默认为 false。
  • 返回值：异步的返回图片中的文本字符串（string类型）。

例如下面的例子：

JavaScript
Python
const { WinAuto } = require("leanpro.win");
let model = WinAuto.loadModel(__dirname + "test.tmodel");

(async () => {
   let text = await model.getVirtual("Virtual1").visualText();
   console.log('text', text);
})()
from leanproAuto import WinAuto
model = WinAuto.loadModel("models/test.tmodel")

text = model.getVirtual("Virtual1").visualText()
print('text', text)
这个例子里使用了模型中的“Virtual1”虚拟控件，并将其转换为文本返回。

如果某个区域中有多个文字块，需要分别识别，可以定义多个虚拟控件，然后分别对这些控件调用visualText()。

clickVisualText(text: string, options?: ClickVisualTextOptions): Promise<void>

使用OCR在虚拟控件快照上查找指定的文本，然后点击对应的文字。

clickVisualText方法只存在于Virtual控件中。

  • text: String类型，可以为单词或词组，需是图片中存在的连续文字，且在同一行
  • options：可选参数：
    • cache：设置是否缓存识别信息，默认为false；当为true时，快照识别的文字及位置信息会缓存在控件中，下一次再次调用clickVisualText方法并传入cache: true，会重用这些文字位置信息执行操作，无需再次做OCR识别，可加快执行速度。
    • x：设置点击的水平像素位置；
    • y：设置点击的垂直像素位置。例如{x: 1, y: 1}点击文字区域的左上角。如果x和y是缺省值0，则点击文字框中心区域。
  • 返回值：不返回任何值的异步方法。 下面是使用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))
})();

该样例打印出所有控件上文字的识别信息，包括文字和位置。

checkImage(options?: CompareOptions): Promise<void>

用以验证虚拟控件当前的图像与预先设定的参考图像是否匹配。如果控件的图像与预设图像存在差异，测试将抛出错误，并展示两者之间的不同。适用于自动化测试中的视觉校验，确保虚拟控件的图像呈现按预期进行。

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

使用示例

以下示例展示了如何使用 checkImage 方法来验证一个名为 "button_image" 的虚拟控件的图像：

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 ""