Qt的识别属性

跨平台Qt技术的也是对象识别技术，即通过使用控件的属性来定位控件，并执行自动化操作。

要了解更多关于模型对象及其属性，请查阅模型对象及属性文档。

共用识别属性

以下是在Qt中使用的识别属性，这些属性在其他自动化技术（如Windows自动化）中也存在，但在Qt中它们可能具有不同的含义。

type

• 控件的类型，是一个必需的属性，不可更改或删除。
• 影响控件提供的操作API。
• 类型包括但不限于Button、Text、Window、List、Table、Tree等。

name

• 对应Qt控件的objectName属性。
• 是控件的内部对象名称。

text

• 控件显示的文本值。
• 如果控件在开发时设置了text、label、title等属性，这些属性通常与用户看到的内容一致，因此会首先选择这个值进行识别。
• 如果控件没有设置上述任何值，则认为该属性不存在。

className

• 控件所属的类名称，源自控件在代码中的类定义。
• 例如，Qt中常用于窗口的控件是QWidget，因此窗口的type为Window，而className为QWidget，如图所示：
  
• 由于className的值取决于控件在开发时所采用的具体组件，所以表示的是该控件所使用的Qt组件，也可用于认识应用结构。

toolTip

• 控件的提示信息。
• 对于一些没有text属性但提供了固定的toolTip属性的控件（例如图像按钮），toolTip也可作为识别属性使用。

windowTitle

• 控件的windowTitle属性。
• 适用于顶级窗口或任何可以独立作为窗口的控件，如QMainWindow、QDialog、QToolBar等，是一个重要的识别属性。

特有识别属性

特有识别属性是指那些仅出现在特定类型控件中的属性，这些属性可以帮助我们更准确地定位和操作这些特定的控件。

itemIndex

目标控件在容器中的索引位置，存在与标签页项TabItem中，指示目标标签页处于第几个索引位置。由于标签页的位置可变，因此这一识别属性通常会配合TabItem的text属性进行匹配，匹配的规则如下:

• 优先使用text识别属性匹配;
• 如果text无法精确匹配或匹配到多个相同的TabItem时，使用itemIndex属性；
• 如果仍无法找到对象，则抛出错误。

itemPath

目标控件在整个视图组件中所处的位置，存在于ListItem、TableItem、TreeItem和ViewItem中，但对于不同类型的item中路径的定义也有些许区别。在类型文件中的定义如下：

export type ItemPath = number; // 常见于ListItem，用数字表示列表项位置。
export type ItemPath = number[]; // 常见于TreeItem，用数字数组表示树节点的路径
export type ItemPath = string[]; // 常见于TreeItem，用字符串数组表示树节点的名称路径，会自动地在树中寻找符合的树节点
export type ItemPath = [number, number]; // 常见于TableItem中，一个长度为2的数组数组，数组中的两个数字分别代表行和列，通过行列来表示单元格位置。
export type ItemPath = (number | string | [number, number])[]; // 常见于TreeItem，用更复杂数组表示树节点的某列属性，数组的最后一个值为类似行列的数组。如果ItemPath写作 [0, [0, 0]]，则代表树的第1个节点的第1个子节点的第1列属性。

ItemPath: int # 常见于ListItem，用数字表示列表项位置。
ItemPath: List[int] # 常见于TreeItem，用数字数组表示树节点的路径
ItemPath: List[str] # 常见于TreeItem，用字符串数组表示树节点的名称路径，会自动地在树中寻找符合的树节点
ItemPath: [int, int] # 常见于TableItem中，一个长度为2的数组数组.
# 数组中的两个数字分别代表行和列，通过行列来表示单元格位置。
ItemPath: List[Union(str, int, ItemPath)] # 常见于TreeItem，用更复杂数组表示树节点的某列属性，数组的最后一个值为类似行列的数组。  
# 如果ItemPath写作 [0, [0, 0]]，则代表树的第1个节点的第1个子节点的第1列属性。

可以将ItemPath作为一种通用的描述数据视图中项（Item）的位置的格式，只是在不同类型的视图中有不同形式的简写。由于可以将表格（Table）类比为单层级的树（Tree），也可以将列表（List）类比为单列的表格（Table），因此其实所有ItemPath都可以写成相同的形式（只是更复杂更不易读）。

• 列表（List）：[1] 可以写作[[1,0]]。
• 表格（Table）：[1, 1]可以写作[[1, 1]]。
• 树（Tree）：[1, 1]可以写作[1, [1, 0]]。

可以发现，无论哪一种数据视图的ItemPath都可以写成相同的、完整的二维数组的格式。

appName

目标控件所属应用的进程名，存在于模型根节点Application类型中。

appPath

同样通常不作为识别属性使用，指目标控件所属应用的路径，存在于模型的根节点Application类型中。

position

用于图元控件的识别属性。代表图元在画布（scene）中的位置，即QGraphicsItem控件类的scenePos()属性方法的值。

bounding

用于图元控件的识别属性。代表图元的碰撞箱，即QGraphicsItem控件类的boundingRect()属性方法的值。

objectName

用于图元控件的识别属性。图元的名称，属于QGraphicsObject控件类（QObject和QGraphicsItem控件的子类）的objectName()的属性方法。即使图元位置变动或存在多个重复图元，通过这个属性也能精确定位到特定图元。

提示：如果想要应用中绘制生成的控件拥有较好的测试友好性，可以让被绘制的控件从QGraphicsObject派生，而不是QGraphicsItem。

辅助识别属性

index

当多个控件的属性完全相同或部分属性相同导致无法精确识别时，可以使用 index 属性来指定目标控件在匹配到的控件列表中的位置。比如，当页面上有两个完全相同的按钮时，可以通过设置 index 为 0 或 1 来区分它们。 具体用法可参考Windows的识别属性

objectType

用于定义目标控件的抽象类型。通过使用 objectType，可以更精确地控制和操作这些控件。 详细信息可参考Windows的识别属性

meta

meta 属性提供了一种利用控件内部信息进行定位的功能，以应对标准属性无法满足特定需求的情况。您可以通过在控件的“对象属性”中点击加号来手动添加 meta，或者在浏览控件树时，直接在对应控件的 meta 属性中选择所需的特定属性。

例如，在侦测 Qtitan 的 RibbonGroup 和 RibbonPage 控件时，通过添加 meta.title，使得控件内部的 title 属性参与到识别过程中，从而实现更精确的控件识别与操作。

该属性支持使用正则表达式进行匹配，详情请参考修改匹配模式。