树类型对象

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

针对列表控件还提供了相应的演练——演练：操作Qt应用中的List，能够大大加深对于API的理解程度。

树状视图控件: Tree

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

export interface IQTree extends IQtControl {
    getItem(itemPath: ItemPath): IQTreeItem;
    findItem(text: string): Promise<IQTreeItem | null>;  
    scrollTo(itemPath: ItemPath): Promise<void>;
    scrollToTop(): Promise<void>;
    scrollToBottom(): Promise<void>;
    collapseAll(itemPath: ItemPath): Promise<void>;
    children(): Promise<IQTreeItem[]>;
    childCount(): Promise<number>;
    rowData(itemPath: ItemPath): Promise<string[]>;
    columnCount(): Promise<number>;
    columnHeaders(): Promise<string[]>;
}
export type ItemPath = (number | [number, number])[];

对象操作API

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

getItem(itemPath): IQTreeItem

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

• itemPath: ItemPath型，代表节点的位置。
• 返回值: IQTreeItem类型，即ListItem控件的自动化对象。注意这是一个同步方法，不需要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<void>

滚动到目标树节点的位置。如果目标位置还未展开，会一直展开到目标节点使其可见为止。

• 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[]类型，由树节点的属性构成的字符串数组。

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

columnHeaders(): Promise<string[]>

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

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

columnCount(): Promise<number>

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

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

树节点控件: TreeItem

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

类型定义文件

类型定义文件如下:

export interface IQTreeItem extends IQtControl {
    select(): Promise<void>;
    findItem(): Promise<void>;
    expand(): Promise<void>;
    collapse(): Promise<void>;
    scrollIntoView(): Promise<void>;
    set(value: string): Promise<void>;
    exists(seconds: number): Promise<boolean>;
    value(): Promise<string>;
    rowData(): Promise<string[]>;
    expandable(): Promise<boolean>;
    expanded(): Promise<boolean>;
    childCount(): Promise<number>;
    children(): Promise<IQTreeItem[]>;
    rowIndex(): Promise<number>;
    columnIndex(): Promise<number>;
    itemPath(): Promise<ItemPath>;
}

对象操作API

value(): Promise<string>

获得树节点的名称。

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

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

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

• text: string类型，期望目标树节点的内容或者文本;

• 返回值: Promise<IQTreeItem>或Promise<null>类型，异步的搜索应用中的目标树节点，如果没有搜索到则返回null。

  搜索前先展开当前节点可以避免无法找到子节点的情况。

scrollIntoView(): Promise<void>

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

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

select(): Promise<void>

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

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

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

expand(): Promise<void>

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

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

collapse(): Promise<void>

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

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

set(value: string): Promise<void>

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

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

exists(seconds: number): Promise<boolean>

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

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

children(): Promise<IQTreeItem[]>

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

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

childCount(): Promise<number>

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

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

rowData(): Promise<string[]>

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

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

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

expandable(): Promise<boolean>

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

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

expanded(): Promise<boolean>

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

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

itemPath(): Promise<ItemPath>

树节点的位置。

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