072 Tree · 树

用途

展示层级数据：节点展开、选择、键盘导航、外部加载子项与空状态。只构建可见行，10 万节点同样流畅；折叠的子树不创建任何界面元素。

最小示例

kids := map[string][]string{"Nave": {"Pulpit", "Pews"}}
var state data.TreeState[string]
view := func(c *ui.Context) {
	core.Use(c, core.Settings{})
	data.Tree(c, &state, data.TreeOptions[string]{
		Roots:    []string{"Nave", "Sacristy"},
		Children: func(n string) []string { return kids[n] },
		Label:    func(n string) string { return n },
	}).Element.Size(280, 240)
}
ui.Render(view, 400, 300, 1)

参数

func Tree[K comparable](c *ui.Context, s *TreeState[K], opts TreeOptions[K]) TreeView。节点值本身即稳定键。TreeState 方法：Selected()、SetOpen(item, open)、IsOpen(item)；字段 Selection ui.Selection[K] 保存多选。

字段	类型	默认值	含义
`Roots`	`[]K`	空	顶层节点；为空时显示空状态。
`Children`	`func(K) []K`	必填	子节点：nil 表示叶子；未加载的节点返回空的非 nil 切片。
`Label`	`func(K) string`	必填	节点文字。
`ItemStatus`	`func(K) DataStatus`	nil	子项加载状态：`DataUnloaded`、`DataLoading`（行尾加载标记）、`DataFailed`（行尾错误与重试）；nil 表示全部已加载。
`Load`	`func(K)`	nil	节点以 `DataUnloaded` 状态展开时调用一次，点击重试时再次调用。
`Multiple`	`bool`	false	多选。
`Status`	`DataStatus`	`DataReady`	加载状态：`DataLoading` 首次加载（无行时显示加载标记）、`DataLoadingMore` 追加加载（行下方显示“正在加载更多”）、`DataFailed` 失败（显示错误与“重试”）。
`Error`	`string`	内置“加载失败”	`DataFailed` 时显示的具体错误。
`Empty`	`string`	内置“暂无数据”	无数据时的说明文字。

状态

默认、悬停、选中（Selection 背景 + AccentText 勾选标记）、聚焦、展开/折叠（箭头旋转）、子项加载中、子项加载失败、空、首次加载与失败。

事件

Changed()：选择变化；Submitted()：Enter 或双击；Retried()：整树失败时点击重试。子项重试直接调用 Load。

键盘操作

↑/↓：移动；→：展开或进入第一个子节点；←：折叠或回到父节点；macOS 上 Option、其他平台 Shift 配合 ←/→ 展开或折叠全部子孙。
输入字母按 Label 定位；Enter 提交。

限制

基于 MyGo ui.Outline 而不是 ui.Tree：ui.Tree 会构建全部已展开节点（docs/ui/tree.md “A tree builds every item it shows”），不满足大量节点虚拟化要求。
Outline 每帧遍历已展开的节点以计算行（ui/outline.go flatten），元素数受可见区域限制，但遍历成本随展开节点数增长。
单选按节点保存：行移动超过 MyGo 的 1000 行搜索范围（ui/list.go:30）时，组件扫描可见行重新定位并立即重建一帧；所选节点被折叠隐藏或删除时选择清除。
异步加载由调用方在后台完成并通过 Window.Update 回到界面线程。