树类型对象

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

树状视图控件: Tree

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

方法名	描述
childCount	通过树状结构获取树节点数，路径名可以是索引或名称，默认从根路径开始。
treeNodeText	通过完整树路径获取树节点文本，路径名可以是索引或名称。
select	按树状路径选择树节点，路径名可以是索引或名称。
expandTo	按完整树路径展开树节点，路径名可以是索引或名称。
collapseAll	按完整树路径闭合树节点，路径名可以是索引或名称。
showHeader	将某列头滚动到当前视图，并返回该对象。
itemCheckedStatus	通过完整树路径获取树节点状态，路径名可以是索引或名称。
setItemCheckedStatus	通过完整树路径设置树节点状态，路径名可以是索引或名称。
scrollLeft	通过指定名称或索引滚动到当指定项，并返回指定项的对象。
scrollToTop	滚动到屏幕顶部。
scrollToBottom	滚动到屏幕底部。
columnHeaders	返回表格列标题的数组。

类型定义

JavaScript

Python

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)[];

class WinTree(WinControl):
	def childCount(path: TypedDict) -> int
	def treeNodeText(path: TypedDict) -> str
	def select(path: TypedDict) -> "WinTreeItem"
	def expandTo(path: TypedDict) -> "WinTreeItem"
	def collapseAll(path: Optional[TypedDict]=None) -> None
	def itemCheckedStatus(path: TypedDict) -> bool
	def setItemCheckedStatus(path: TypedDict, checked: Union[bool, str]) -> None
	def scrollLeft() -> None
	def scrollToTop() -> None
	def scrollToBottom() -> None
	def columnHeaders() -> List[str]
	def showHeader(nameOrIndex: Union[str, int]) -> "WinTreeItem"
	def row(rowIndex: int) -> "WinTableRow"

TreePath类型

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

──b
  └─u
    └─f

对象操作API

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

select(path)

选中指定位置的树节点。

参数

path: TreePath类型，目标节点的位置。

返回值

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

示例代码

JavaScript

Python

// 选中 "Top One" 下的 "Sub One" 节点
await model.getTree("Tree").select(["Top One", "Sub One"]);
// 选中第1个节点下的第1个子节点
await model.getTree("Tree").select([0, 0]);

# 选中 "Top One" 下的 "Sub One" 节点
model.getTree("Tree").select(["Top One", "Sub One"])
# 选中第1个节点下的第1个子节点
model.getTree("Tree").select([0, 0])

childCount(path)

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

参数

path: TreePath类型，目标节点的位置。

返回值

Promise<number>类型，异步的统计并返回目标节点的子节点数量。

示例代码

JavaScript

Python

// 获取 "Top One" 下的 "Sub One" 节点的子节点数量
let childCount = await model.getTree("Tree").childCount(["Top One", "Sub One"]);
// 获取第1个节点下的第1个子节点的子节点数量
childCount = await model.getTree("Tree").childCount([0, 0]);
assert.equal(childCount, 2);

# 获取 "Top One" 下的 "Sub One" 节点的子节点数量
childCount = model.getTree("Tree").childCount(["Top One", "Sub One"])
# 获取第1个节点下的第1个子节点的子节点数量
childCount = model.getTree("Tree").childCount([0, 0])
assert childCount == 2

treeNodeText(path)

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

参数

path: TreePath类型，目标节点的位置。

返回值

Promise<string>类型，异步的返回目标节点的内容。

示例代码

JavaScript

Python

// 获取指定节点的文本
let treeNodeText = await model.getTree("Tree").treeNodeText(["Top One", "Sub One"]);
treeNodeText = await model.getTree("Tree").treeNodeText([0, 0]);
assert.equal(treeNodeText, "Sub One");

# 获取指定节点的文本
treeNodeText = model.getTree("Tree").treeNodeText(["Top One", "Sub One"])
treeNodeText = model.getTree("Tree").treeNodeText([0, 0])
assert treeNodeText == "Sub One"

expandTo(path)

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

参数

path: TreePath类型，目标节点的位置。

返回值

Promise<IWinTreeItem>，目标节点的对象。

示例代码

JavaScript

Python

// 展开到指定节点
await model.getTree("Tree").expandTo(["Top One", "Sub One"]);
await model.getTree("Tree").expandTo([0, 0]);

# 展开到指定节点
model.getTree("Tree").expandTo(["Top One", "Sub One"])
model.getTree("Tree").expandTo([0, 0])

collapseAll(path)

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

参数

path: TreePath类型，目标节点的位置。

返回值

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

示例代码

JavaScript

Python

// 折叠指定节点路径上的所有节点
await model.getTree("Tree").collapseAll(["Top One", "Sub One"]);
await model.getTree("Tree").collapseAll([0, 0]);

# 折叠指定节点路径上的所有节点
model.getTree("Tree").collapseAll(["Top One", "Sub One"])
model.getTree("Tree").collapseAll([0, 0])

showHeader(nameOrIndex)

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

参数

nameOrIndex: number类型或string类型，代表列的索引或列的名称。

返回值

Promise<IWinTreeItem>类型，异步的返回目标列头的对象。

示例代码

JavaScript

Python

// 滚动到 "Name" 列
await model.getTree("Tree").showHeader("Name");
// 滚动到第1列
await model.getTree("Tree").showHeader(0);

# 滚动到 "Name" 列
model.getTree("Tree").showHeader("Name")
# 滚动到第1列
model.getTree("Tree").showHeader(0)

itemCheckedStatus(path)

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

参数

path: TreePath类型，目标节点的位置。

返回值

Promise<boolean>类型，是否被选中。

示例代码

JavaScript

Python

// 获取指定节点的勾选状态
let itemCheckedStatus = await model.getTree("Tree").itemCheckedStatus(["Top One", "Sub One"]);
itemCheckedStatus = await model.getTree("Tree").itemCheckedStatus([0, 0]);
assert.ok(itemCheckedStatus);

# 获取指定节点的勾选状态
itemCheckedStatus = model.getTree("Tree").itemCheckedStatus(["Top One", "Sub One"])
itemCheckedStatus = model.getTree("Tree").itemCheckedStatus([0, 0])
assert itemCheckedStatus

setItemCheckedStatus(path, checked)

设置目标节点的选中状态(需要树控件支持勾选)。

参数

path: TreePath类型，目标节点的位置。
checked: boolean类型，true代表选中，false代表取消选中。

返回值

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

示例代码

JavaScript

Python

// 勾选指定节点
await model.getTree("Tree").setItemCheckedStatus(["Top One", "Sub One"], true);
await model.getTree("Tree").setItemCheckedStatus([0, 0], true);

# 勾选指定节点
model.getTree("Tree").setItemCheckedStatus(["Top One", "Sub One"], True)
model.getTree("Tree").setItemCheckedStatus([0, 0], True)

columnHeaders()

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

返回值

Promise<string[]>类型，异步的返回所有属性的名称。

示例代码

JavaScript

Python

// 获取列头
let columnHeaders = await model.getTree("Tree").columnHeaders();
assert.deepEqual(JSON.stringify(columnHeaders), '["Name", "Age", "Sex"]');

# 获取列头
columnHeaders = model.getTree("Tree").columnHeaders()
assert columnHeaders == ["Name", "Age", "Sex"]

scrollLeft()

滚动到树最左侧。

返回值

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

示例代码

JavaScript

Python

// 滚动到最左侧
await model.getTree("Tree").scrollLeft();

# 滚动到最左侧
model.getTree("Tree").scrollLeft()

scrollToTop()

滚动到树的顶部。

返回值

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

示例代码

JavaScript

Python

// 滚动到顶部
await model.getTree("Tree").scrollToTop();

# 滚动到顶部
model.getTree("Tree").scrollToTop()

scrollTo(path)

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

参数

path: TreePath类型，目标节点的位置。

返回值

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

示例代码

JavaScript

Python

// 滚动到指定节点
await model.getTree("Tree").scrollTo(["Top One", "Sub One"]);
await model.getTree("Tree").scrollTo([0, 0]);

# 滚动到指定节点
model.getTree("Tree").scrollTo(["Top One", "Sub One"])
model.getTree("Tree").scrollTo([0, 0])

scrollToBottom()

滚动到树的底部。

返回值

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

示例代码

JavaScript

Python

// 滚动到底部
await model.getTree("Tree").scrollToBottom();

# 滚动到底部
model.getTree("Tree").scrollToBottom()

树节点控件: TreeItem

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

方法名	描述
expand	展开当前树节点。
collapse	折叠当前树节点。
expandState	返回展开折叠的状态：Collapsed = 0, Expanded = 1, PartiallyExpanded = 2, LeafNode = 3, Unknown = -1。
setSelect	设置当前节点是否被选中。
treePath	获取当前节点的路径。

类型定义

JavaScript

Python

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>;
}

class WinTreeItem(WinCheckBox):
	def expand() -> None
	def collapse() -> None
	def expandState() -> "ExpandCollapseState"
	def select() -> None
	def selected() -> bool
	def setSelect(value: bool) -> None
	def scrollIntoView() -> None
	def treePath(useName: Optional[bool]=None) -> Union[List[str], List[int]]
	def next() -> "WinTreeItem"
	def previous() -> "WinTreeItem"
	def rowData() -> List[str]
	def cell(index: int) -> "WinTreeCell"

对象操作API

scrollIntoView()

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

返回值

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

示例代码

JavaScript

Python

// 滚动到 "W (C:)" 节点
await model.getTreeItem("W_(C:)").scrollIntoView();

# 滚动到 "W (C:)" 节点
model.getTreeItem("W_(C:)").scrollIntoView()

select()

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

返回值

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

示例代码

JavaScript

Python

// 选中 "W (C:)" 节点
await model.getTreeItem("W_(C:)").select();

# 选中 "W (C:)" 节点
model.getTreeItem("W_(C:)").select()

setSelect(select)

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

参数

select: Boolean类型，true代表选中复选框，false代表取消选中目标复选框。

返回值

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

示例代码

JavaScript

Python

// 勾选 "W (C:)" 节点
await model.getTreeItem("W_(C:)").setSelect(true);
await model.getTreeItem("W_(C:)").setSelect(false);

# 勾选 "W (C:)" 节点
model.getTreeItem("W_(C:)").setSelect(True)
model.getTreeItem("W_(C:)").setSelect(False)

expand()

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

返回值

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

示例代码

JavaScript

Python

// 展开 "W (C:)" 节点
await model.getTreeItem("W_(C:)").expand();

# 展开 "W (C:)" 节点
model.getTreeItem("W_(C:)").expand()

collapse()

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

返回值

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

示例代码

JavaScript

Python

// 折叠 "W (C:)" 节点
await model.getTreeItem("W_(C:)").collapse();

# 折叠 "W (C:)" 节点
model.getTreeItem("W_(C:)").collapse()

expandState()

获取当前树节点的展开情况。

返回值

返回展开状态ExpandCollapseState，有以下几种状态：

JavaScript

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

示例代码

JavaScript

Python

// 获取展开状态
let state = await model.getTreeItem("W_(C:)").expandState();
console.log(state);

# 获取展开状态
state = model.getTreeItem("W_(C:)").expandState()
print(state)

treePath(useName)

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

参数

useName: boolean类型，是否使用节点名称组成路径。

返回值

Promise<string[]>或Promise<number[]>类型，取决于useName这一输入参数。

示例代码

JavaScript

Python

// 获取节点路径（使用索引）
let path = await model.getTreeItem("W_(C:)").treePath();
assert.equal(JSON.stringify(path), '[0]');
// 获取节点路径（使用名称）
path = await model.getTreeItem("W_(C:)").treePath(true);
assert.equal(JSON.stringify(path), '["W (C:)"]');

# 获取节点路径（使用索引）
path = model.getTreeItem("W_(C:)").treePath()
assert path == [0]
# 获取节点路径（使用名称）
path = model.getTreeItem("W_(C:)").treePath(True)
assert path == ["W (C:)"]

rowData()

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

返回值

Promise<string[]>类型，由树节点的属性构成的字符串数组。

示例代码

JavaScript

Python

// 获取节点所有属性
let data = await model.getTreeItem("W_(C:)").rowData();
assert.equal(JSON.stringify(data), '["W (C:)","","Drive","2025-03-14 9:31:47"]');

# 获取节点所有属性
data = model.getTreeItem("W_(C:)").rowData()
assert data == ["W (C:)","","Drive","2025-03-14 9:31:47"]

cell(index)

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

参数

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

返回值

Promise<IWinTreeCell>类型。

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

示例代码

JavaScript

Python

// 获取第1个属性的单元格
let cell = await model.getTreeItem("W_(C:)").cell(0);

# 获取第1个属性的单元格
cell = model.getTreeItem("W_(C:)").cell(0)

树节点单元控件: TreeCell

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

方法名	描述
value	获取单元的值。
select	选择单元。
set	设置单元的值。
row	获取单元所在行。
selected	获取单元是否被选中。

类型定义

JavaScript

Python

export interface IWinTreeCell extends IWinTableItem {
}

class WinTreeCell(WinTableCell):
	...

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

JavaScript

Python

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

    selected(): Promise<boolean>;
}

class WinTableCell(WinControl):
	def value() -> str
	def select() -> None
	def set(value: str) -> None
	def row() -> Union[WinTableRow, WinTreeItem]
	def scrollIntoView() -> None

对象操作API

select()

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

返回值

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

示例代码

JavaScript

Python

// 选中单元格
let cell = await model.getTreeItem("W_(C:)").cell(0);
await cell.select();

# 选中单元格
cell = model.getTreeItem("W_(C:)").cell(0)
cell.select()

set(value)

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

参数

value: string类型，期望的单元格值。

返回值

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

示例代码

JavaScript

Python

// 修改单元格的值
let cell = await model.getTreeItem("W_(C:)").cell(0);
await cell.set("W (C:)");

# 修改单元格的值
cell = model.getTreeItem("W_(C:)").cell(0)
cell.set("W (C:)")

value()

获取树节点单元的值。

返回值

Promise<string>类型，目标单元格中的值。

示例代码

JavaScript

Python

// 获取单元格的值
let cell = await model.getTreeItem("W_(C:)").cell(0);
let value = await cell.value();
assert.equal(value, "W (C:)");

# 获取单元格的值
cell = model.getTreeItem("W_(C:)").cell(0)
value = cell.value()
assert value == "W (C:)"

row()

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

返回值

Promise<IWinTreeItem>类型，异步的目标树节点对象。

示例代码

JavaScript

Python

// 获取单元格所在的树节点
let cell = await model.getTreeItem("W_(C:)").cell(0);
let row = await cell.row();

# 获取单元格所在的树节点
cell = model.getTreeItem("W_(C:)").cell(0)
row = cell.row()

selected()

目标树节点是否被选中。

返回值

Promise<boolean>类型，异步的返回选中的结果。

示例代码

JavaScript

Python

// 获取单元格的选中状态
let cell = await model.getTreeItem("W_(C:)").cell(0);
let selected = await cell.selected();
assert.equal(selected, true);

# 获取单元格的选中状态
cell = model.getTreeItem("W_(C:)").cell(0)
selected = cell.selected()
assert selected == True

results matching ""

全部 API Walkthrough 其他

树类型对象

树状视图控件: Tree

类型定义

TreePath类型

对象操作API

select(path)

childCount(path)

treeNodeText(path)

expandTo(path)

collapseAll(path)

showHeader(nameOrIndex)

itemCheckedStatus(path)

setItemCheckedStatus(path, checked)

columnHeaders()

scrollLeft()

scrollToTop()

scrollTo(path)

scrollToBottom()

树节点控件: TreeItem

类型定义

对象操作API

scrollIntoView()

select()

setSelect(select)

expand()

collapse()

expandState()

treePath(useName)

rowData()

cell(index)

树节点单元控件: TreeCell

类型定义

对象操作API

select()

set(value)

value()

row()

selected()

results matching ""

No results matching ""