树类型对象

针对树控件以及树中的节点,模型管理器提供了TreeTreeItem两个控件。Tree控件代表整棵树,而TreeItem代表树中的各个节点。由于节点的名称并不唯一,因此将节点名称作为识别属性是不可靠的,模型管理器提供了一个描述节点位置的识别属性——itemPath,可以点击itemPath属性查看具体介绍。

针对树件还提供了相应的演练——演练:操作Qt应用中的List,能够大大加深对于API的理解程度。

树状视图控件: Tree

针对Tree控件,大多是以传入itemPath来操作相关节点;而TreeItem控件自身本来代表的就是节点,因此对其操作通常情况下不需要传参数。

JavaScript
Python
export interface IQTree extends IQtControl {
    getItem(itemPath: ItemPath): IQTreeItem;
    findItem(text: string): Promise<IQTreeItem | null>;  
    scrollTo(itemPath: ItemPath): Promise<IQTreeItem>;
    scrollToTop(): Promise<void>;
    scrollToBottom(): Promise<void>;
    collapseAll(itemPath: ItemPath): Promise<void>;
    columnData(nameOrIndex: number | string): Promise<string[]>;

    children(): Promise<IQTreeItem[]>;
    childCount(): Promise<number>;
    rowData(itemPath: ItemPath): Promise<string[]>;
    columnCount(): Promise<number>;
    columnHeaders(): Promise<string[]>;
}
export type ItemPath = (number | [number, number])[];
class QTree(QtControl):
	def columnHeaders() -> List[str]
	def collapseAll(itemPath: TypedDict) -> None
	def getItem(itemPath: TypedDict) -> "QTreeItem"
	def findItem(text: str, options: Optional[FindItemOptional]=None) -> "QTreeItem"
	def rowData(itemPath: TypedDict) -> List[str]
	def columnData(nameOrIndex: Union[str, int]) -> List[str]
	def select(itemPath: TypedDict) -> "QTreeItem"
	def childCount() -> int
	def children() -> List[QTreeItem]
	def columnCount() -> int
	def scrollToTop() -> None
	def scrollTo(itemPath: TypedDict) -> "QTreeItem"
	def scrollToBottom() -> None

对象操作API

下面是针对Tree控件的对象操作API。

getItem(itemPath): IQTreeItem

获取指定itemPath位置的树节点对应的自动化对象。

  • itemPath: ItemPath型,代表节点的位置。
  • 返回值: IQTreeItem类型,即TreeItem控件的自动化对象。注意这是一个同步方法,不需要await关键字,也不会匹配应用中的控件。只有在执行对象上的异步方法时才会进行匹配。

findItem(text: string): Promise<IQTreeItem | null>

在树中根据名称搜索目标树节点,返回目标树节点的自动化对象,如果没有搜索到则返回null。由于需要实时的搜索应用中的树,因此是异步方法。

  • text: string类型,期望目标树节点的内容或者文本;
  • 返回值: Promise<IQTreeItem>Promise<null>类型,异步的搜索应用中的目标树节点,如果没有搜索到则返回null

    findItem()的搜索策略: findItem()方法采取的是“广度优先”的搜索策略,即先在当前层级中搜索满足条件(即符合名称的树节点);如果全都不满足,才会进入下一层级。如果是未展开的节点,那么通常不会被搜索到,因此如果是需要获取比较深层的树节点,最佳的方式还是一层一层的调用findItem()方法来保证所有的节点都可以被正确搜索到。对此,树节点也提供了findItem()方法

select(itemPath): Promise<void>

选中指定位置的树节点。

  • index: ItemPath型,目标节点的位置。
  • 返回值: 不返回任何值的异步方法。

scrollToTop(): Promise<void>

滚动到树的顶部。

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

scrollTo(itemPath): Promise<IQTreeItem>

滚动到目标树节点的位置,并返回此对象。如果目标位置还未展开,会一直展开到目标节点使其可见为止。

  • itemPath: ItemPath型,目标节点的位置。
  • 返回值: 不返回任何值的异步方法。

scrollToBottom(): Promise<void>

滚动到树的底部。

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

collapseAll(itemPath: ItemPath): Promise<void>

折叠指定路径上的所有树节点。

  • itemPath: ItemPath型,目标节点的位置。
  • 返回值: 不返回任何值的异步方法。

children(): Promise<IQTreeItem[]>

异步的获取当前树的所有的直系子节点,以数组的形式返回。

  • 返回值: 由TreeItem类型的自动化对象组成的数组。并且是异步方法,需要使用await关键字。

childCount(): Promise<number>

异步的获取当前树的所有的直系子节点的数量,返回数字。

  • 返回值: number类型,直系子节点的数量,可以理解为children()方法返回的数组的长度。并且是异步方法,需要使用await关键字。

rowData(itemPath: ItemPath): Promise<string[]>

获取目标树节点的所有属性,并以数组形式返回。

  • itemPath: ItemPath型,目标节点的位置。
  • 返回值: string[]类型,由树节点的属性构成的字符串数组。

    比如针对文件树,某个文件节点的属性可能包含了[文件名, 文件大小, 文件类型, 最后修改时间]这些值。

columnData(nameOrIndex): Promise<string>

获取树的某列属性的全部数据,允许指定列的名称或是索引。可选的列名或索引可以参考columnHeaders()方法的返回值。

出于性能和使用场景考虑,只获取顶层树节点的数据。

  • 返回值 string[]类型,该列的全部属性。

columnHeaders(): Promise<string[]>

获取树的属性名称,也就是树中每一列的列头内容,并以字符串数组的形式返回。

如果希望进一步的操作树的属性标题行,可以参考表格中的表头控件HeaderItem的操作。

  • 返回值: string[]类型,由属性名称组成的字符串数组。

columnCount(): Promise<number>

获取树的属性个数,也就是树中有几列。在数值上等于columnHeaders()方法返回数组的长度。

  • 返回值 number类型,属性个数。

树节点控件: TreeItem

针对树中每个节点控件的自动化对象TreeItem,可以对它展开或折叠,获取它的子节点等等操作。
相比于上一节中所有大部分树节点操作都要传入itemPath参数来定位被操作的树节点,

类型定义文件

类型定义文件如下:

JavaScript
Python
export interface IQTreeItem extends IQtControl {
    select(): Promise<void>;
    getItem(itemPath: ItemPath): IQTreeItem;
    findItem(text: string): Promise<IQTreeItem | null>;  
    expand(): Promise<void>;
    collapse(): Promise<void>;
    scrollIntoView(): Promise<void>;
    set(value: string): Promise<void>;
    toggleCheck(checkState: boolean | 'partial'): Promise<void>;
    data(roleId?: number): Promise<string|int>;
    
    exists(seconds: number): Promise<boolean>;
    value(): Promise<string>;
    rowData(): Promise<string[]>;
    expandable(): Promise<boolean>;
    editable(): Promise<boolean>;
    selected(): Promise<boolean>;
    expanded(): Promise<boolean>;
    childCount(): Promise<number>;
    children(): Promise<IQTreeItem[]>;
    rowIndex(): Promise<number>;
    columnIndex(): Promise<number>;
    itemPath(): Promise<ItemPath>;
    checkState(): Promise<boolean | 'partial'>;
}
class QTreeItem(QItemViewItem):
	def expand() -> None
	def collapse() -> None
	def exists(seconds: int) -> bool
	def value() -> str
	def rowData() -> List[str]
	def scrollIntoView() -> None
	def set(value: str) -> None
  def data(roleId: int = None) -> Union[str, int]
	def select() -> None
	def expandable() -> bool
	def expanded() -> bool
	def childCount() -> int
	def children() -> List[QTreeItem]
	def rowIndex() -> int
	def columnIndex() -> int
	def itemPath() -> TypedDict
	def getItem(itemPath: TypedDict) -> "QTreeItem"
	def findItem(text: str, options: Optional[FindItemOptional]=None) -> "QTreeItem"
	def checkState() -> Union[bool, str]
	def toggleCheck(checkState: Union[bool, str]) -> None

对象操作API

value(): Promise<string>

获得树节点的名称。

  • 返回值: Promise<string>类型,表示树节点的名称。需要使用await关键字取出其中的结果。

校验获取树节点temp控件的控件值。

JavaScript
Python
let value = await model.getTreeItem("temp").value();
assert.equal(value,'temp');
value = model.getTreeItem("temp").value()
assert value == 'temp'

getItem(itemPath): IQTreeItem

获取以当前节点为起点,指定itemPath位置的树节点对应的自动化对象。相比于Tree对象上的getItem()方法需要传入完整的itemPath才能索引到目标节点,TreeItem对象的getItem()方法会自动的将传入的itemPath与当前树节点的itemPath属性拼接后再进行索引,实现类似相对路径的效果。

  • itemPath: ItemPath型,代表目标节点相对当前节点的位置。
  • 返回值: IQTreeItem类型,即TreeItem控件的自动化对象。注意这是一个同步方法,不需要await关键字,也不会匹配应用中的控件。只有在执行对象上的异步方法时才会进行匹配。

假设TreeItem对象A的itemPath属性为[0,1],那么脚本调用getTreeItem("A").getItem([2,3])时,会将两者的itemPath进行拼接,等效于getTree("Tree").getItem([0,1,2,3])

findItem(text: string, options?:object): Promise<IQTreeItem | null>

根据名称搜索目标树节点,返回目标树节点的自动化对象TreeItem,默认采取模糊搜索,不区分大小写,返回部分匹配的第一个结果,如果没有搜索到则返回null

虽然采取模糊匹配,但是如果有完全匹配的结果,则会最优先返回,无论是作为第几个结果。

  • text: string类型,期望目标列表项的内容或者文本;
  • options: (可选)搜索选项。
    • exact: 精确匹配选项,boolean类型,默认为false。设为true后会从模糊搜索改为精确搜索,只返回完全匹配的第一个结果,否则返回null
  • 返回值: Promise<IQTreeItem>Promise<null>类型,异步的搜索应用中的目标单元格,如果没有搜索到则返回null
    对于展开后才开始加载子节点的树,搜索前先展开当前节点可以避免无法找到子节点的情况。

scrollIntoView(): Promise<void>

滚动到树节点位置。如果树节点所在的位置被折叠,则会展开所有路径上的树节点。

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

select(): Promise<void>

选中树节点。如果该节点不在可视范围内,还会自动的滚动到该项所在的位置。

这个方法当节点不在不在可视范围内时,会自动的执行scrollIntoView()方法来展开并滚动到目标节点。

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

expand(): Promise<void>

展开树节点,如果是无法展开的节点,则不会有任何效果。

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

collapse(): Promise<void>

展开树节点,如果是无法折叠的节点,则不会有任何效果。

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

set(value: string): Promise<void>

修改树节点的值,如果是无法编辑的节点,则不会有任何结果。

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

toggleCheck(checkState: boolean | 'partial'): Promise<void>

选中或是取消选中树节点中的复选框。

  • checkState: boolean类型或是partial字符串。true代表选中,false代表未选中,"partial"代表部分选中(常见于含子选项的复选框)。
  • 返回值: 不返回任何值的异步方法。

data(roleId?:number): Promise<string|int>

传入role,返回树节点数据内容,不传使用缺省role=DisplayRole

  • 返回值:string类型或是int类型数据内容。

role值可参考enum Qt::ItemDataRole

获取树节点的文本数据内容:

JavaScript
Python
const { RunSettings } = require("leanpro.common");
const { QtAuto } = require("leanpro.qt");
(async () => {
  await RunSettings.set({slowMo: 1000, reportSteps: true});

  let modelQt = QtAuto.loadModel(__dirname + "/recording_1.tmodel");
  await QtAuto.launchQtProcessAsync("C:\\Program Files\\LeanPro\\CukeTest\\bin/dirview.exe");
  const role = 0;

  console.log(await modelQt.getTreeItem("C:").data(role));
  console.log(await modelQt.getTreeItem("TreeItem").data(role));
  console.log(await modelQt.getTreeItem("Drive").data(role));
  console.log(await modelQt.getTreeItem("2023/7/24_18:40:46").data(role));
})();
import os
from leanproAuto import RunSettings, QtAuto

RunSettings.set({"slowMo": 1000, "reportSteps": True})

modelQt = QtAuto.loadModel(os.path.dirname(os.path.realpath(__file__)) + "/recording_4.tmodel")

QtAuto.launchQtProcessAsync("C:\\Program Files\\LeanPro\\CukeTest\\bin\\dirview.exe")
role = 0

modelQt.getApplication("dirview").exists(10)

print(modelQt.getTreeItem("C:").data(role))
print(modelQt.getTreeItem("TreeItem").data(role))
print(modelQt.getTreeItem("Drive").data(role))
print(modelQt.getTreeItem("2023/7/24_18:40:46").data(role))

exists(seconds: number): Promise<boolean>

当前树节点是否在已展开的树中,传入参数为等待时间。

  • seconds: number类型,等待时间,如果超过等待时间仍然为false,则返回。
  • 返回值: boolean类型,是否存在。

可参考Qt对象操作API的exists()

children(): Promise<IQTreeItem[]>

异步的获取当前树节点的所有的直系子节点,以数组的形式返回。

  • 返回值: 由TreeItem类型的自动化对象组成的数组。并且是异步方法,需要使用await关键字。

rowIndex(): Promise<number>

获取当前树节点的在直系父节点中的行索引位置。

  • 返回值: number类型,单元格中的行索引位置。

columnIndex(): Promise<number>

获取当前树节点的在直系父节点中的列索引位置。

  • 返回值: number类型,单元格中的列索引位置。

itemPath(): Promise<ItemPath>

树节点的位置。

  • 返回值: ItemPath类型,代表树节点的位置。

childCount(): Promise<number>

异步的获取当前树节点的所有的直系子节点的数量,返回数字。

  • 返回值: number类型,直系子节点的数量,可以理解为children()方法返回的数组的长度。并且是异步方法,需要使用await关键字。

rowData(): Promise<string[]>

获取树节点的所有属性,并以数组形式返回。

  • 返回值: string[]类型,由树节点的属性构成的字符串数组。

    比如针对文件树,某个文件节点的属性可能包含了[文件名, 文件大小, 文件类型, 最后修改时间]这些值。

expandable(): Promise<boolean>

树节点是否可以被展开,可展开为true,不可展开为false

  • 返回值: boolean类型,是否可展开。

editable(): Promise<boolean>

树节点是否可以被编辑,可编辑为true,不可编辑为false

  • 返回值: boolean类型,是否可编辑。

expanded(): Promise<boolean>

树节点的展开情况,已展开为true,未展开(折叠)为false

  • 返回值: boolean类型,是否已展开。

selected(): Promise<boolean>

树节点的选中情况,已选中为true,未选中(折叠)为false

  • 返回值: boolean类型,是否已选中。

checkState(): Promise<boolean | 'partial'>

获取列表项中的树节点选中状态。

  • 返回值: boolean类型或是partial字符串。true代表选中,false代表未选中,"partial"代表部分选中(常见于含子选项的复选框)。

results matching ""

    No results matching ""