树类型对象

针对树控件以及树中的节点，模型管理器提供了Tree和TreeItem两个控件。Tree控件代表整棵树，而TreeItem代表树中的各个节点。由于节点的名称并不唯一，因此将节点名称作为识别属性是不可靠的，因此在操作树节点的时候，大多使用的是TreePath来描述树节点的路径信息。

树状视图控件: Tree

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

export interface IWinTree extends IWinControl {
    childCount(path: TreePath): Promise<number>;
    treeNodeText(path: TreePath): Promise<string>;
    select(path: TreePath): Promise<IWinTreeItem>;
    expandTo(path: TreePath): Promise<IWinTreeItem>;
    collapseAll(path: TreePath): Promise<void>;
    showHeader(nameOrIndex: string | number): Promise<IWinTreeItem>;
    itemCheckedStatus(path: TreePath): Promise<boolean>;
    setItemCheckedStatus(path: TreePath, Checked: boolean): Promise<void>;
    scrollLeft(): Promise<void>;
    scrollToTop(): Promise<void>;
    scrollToBottom(): Promise<void>;
    columnHeaders(): Promise<string[]>;
    treeNodeCount(path: TreePath): Promise<number>; //obsolete, use childCount
    selectTreeNode(path: TreePath): Promise<IWinTreeItem>; //obsolete, use select
    expandTreeNode(path: TreePath): Promise<IWinTreeItem>; //obsolete, use expandTo
    collapseTreeNode(path: TreePath): Promise<void>; //obsolete, use collapseAll
    dblClickTreeNode(path: TreePath): Promise<void>; //obsolete
}
export type TreePath = string | (string | number)[];

TreePath类型

TreePath类型一组描述节点路径和位置的数组，字符串代表节点的名称，数字代表的是节点的索引值。比如一个TreePath数组为[‘b’,‘u’,‘f’]，那么描述的就是f节点。

──b
  └─u
    └─f

对象操作API

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

select(path): Promise<TreeItem>

选中指定位置的树节点。

• path: TreePath类型，目标节点的位置。
• 返回值: Promise<TreeItem>类型，异步的返回目标树节点的TreeItem对象。

childCount(path): Promise<number>

获取目标节点的子节点数量。会展开目标节点，接着统计展开的子节点数量。

• path: TreePath类型，目标节点的位置。
• 返回值: Promise<number>类型，异步的统计并返回目标节点的子节点数量。

treeNodeText(path): Promise<string>

获取目标节点的内容。会展开目标节点，接着统计展开的内容。

• path: TreePath类型，目标节点的位置。
• 返回值: Promise<string>类型，异步的返回目标节点的内容。

expandTo(path): Promise<TreeItem>

展开到使目标树节点可见的位置。同时也会滚动到目标节点的位置并返回节点对应的对象。

• path: TreePath类型，目标节点的位置。
• 返回值: Promise<TreeItem>，目标节点的对象。

collapseAll(path): Promise<void>

折叠路径上所有的节点。与expandTo()方法相反，但是不返回任何对象。

• path: TreePath类型，目标节点的位置。
• 返回值: 不返回任何值的异步方法。

showHeader(nameOrIndex: string | number): Promise<TreeItem>

水平滚动使得目标列可见，并返回该列顶部的TreeItem对象。

• 返回值: Promise<TreeItem>类型，异步的返回目标列头的对象。

itemCheckedStatus(path): Promise<boolean>

获取目标节点被选中的状态。

• path: TreePath类型，目标节点的位置。
• 返回值: Promise<boolean>类型，是否被选中。

setItemCheckedStatus(path, Checked: boolean): Promise<void>

设置目标节点的选中状态。

• path: TreePath类型，目标节点的位置。
• Checked: boolean类型，true代表选中，false代表取消选中。
• 返回值: 不返回任何值的异步方法。

columnHeaders(): Promise<string[]>

获取树中所有属性的名称。并以字符串数组的形式返回。

• 返回值: Promise<string>类型，异步的返回所有属性的名称。

scrollLeft(): Promise<void>

滚动到树最左侧。

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

scrollToTop(): Promise<void>

滚动到树的顶部。

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

scrollTo(path): Promise<void>

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

• path: TreePath类型，目标节点的位置。
• 返回值: 不返回任何值的异步方法。

scrollToBottom(): Promise<void>

滚动到树的底部。

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

树节点控件: TreeItem

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

类型定义文件

类型定义文件如下:

export interface IWinTreeItem extends IWinCheckBox {
    expand(): Promise<void>;
    collapse(): Promise<void>;
    expandState(): Promise<ExpandCollapseState>;
    setSelect(value: boolean): Promise<void>;
    treePath(useName: boolean): Promise<string[] | number[]>;
    //qt only
    rowData(): Promise<string[]>;
    cell(index: number): Promise<IWinTreeCell>;
}

对象操作API

scrollIntoView(): Promise<void>

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

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

select(): Promise<void>

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

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

setSelect(select): Promise<void>

当树节点包含复选框（来标识选中状态）时，setSelect()方法可以使得多个列表项同时被选中。最常见的场景是Windows文件管理器中的文件复选框。类似CheckBox控件的toggleCheck()方法。

• select: Boolean类型，true代表选中复选框，false代表取消选中目标复选框。
• 返回值: 不返回任何值的异步方法。

expand(): Promise<void>

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

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

collapse(): Promise<void>

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

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

expand(): Promise<void>

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

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

expandState(): Promise<ExpandCollapseState>

获取当前树节点的展开情况。（仅适用于UIA） 返回值: 返回展开状态ExpandCollapseState，有以下几种状态:

export enum ExpandCollapseState {
    collapsed = 0,
    expanded = 1,
    partiallyExpanded = 2,
    leafNode = 3,
    unknown = -1
}

treePath(useName: boolean): Promise<string[] | number[]>

获取当前节点的路径信息。

• useName: boolean类型，是否使用节点名称组成路径。
• 返回值: Promise<string[]>或Promise<number[]>类型，取决与useName这一输入参数。

rowData(): Promise<string[]>

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

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

cell(index: number): Promise<CellItem>

获取树节点中指定索引属性的内容，并返回CellItem对象。类似表格行对象的cell方法。

• index: number类型，目标属性的索引值。

• 返回值: Promise<CellItem>类型。

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

树节点单元控件: TreeCell

所谓树节点单元，就像表格中的单元格一样，代表某一行某个属性的树节点单元控件，是树中的最小单元控件。比如一个树节点有4个属性：[文件名, 文件大小, 文件类型, 最后修改时间]，那么这个节点底下就有4个树节点单元。

类型文件

export interface IWinTreeCell extends IWinTableItem {
}

你可能会奇怪为什么TreeCell控件的类型文件没有定义任何方法，这是因为它继承自TableCell因此享有它的所有方法，而TableCell的类型定义如下:

export interface IWinTableItem {
    value(): Promise<string>;
    select(): Promise<void>;
    set(value: string): Promise<void>;
    row(): Promise<IWinTableRow>;
}

对象操作API介绍

select(): Promise<void>

选中树节点单元控件，并且会将目标树节点滚动到可视区域内。

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

set(value): Promise<void>

直接修改树节点单元控件的值，前提是其自身可编辑。

• value: string类型，期望的单元格值。
• 返回值: 不返回任何值的异步方法。

value(): Promise<string>

获取树节点单元的值。

• 返回值: string类型，目标单元格中的值。

row(): Promise<TreeItem>

获取树节点单元所在的树节点对象，也就是它的父对象，返回所在行的TreeItem对象。

• 返回值: Promise<TreeItem>类型，异步的目标树节点对象。