Data: components 069-080

2026-10-05 12:27:55 -04:00
1 parent 2a232930dd
commit 16533b8f02
@@ -0,0 +1,57 @@
+# 072 Tree · 树
+
+## 用途
+
+展示层级数据：节点展开、选择、键盘导航、外部加载子项与空状态。只构建可见行，10 万节点同样流畅；折叠的子树不创建任何界面元素。
+
+## 最小示例
+
+```go
+kids := map[string][]string{"Nave": {"Pulpit", "Pews"}}
+var state mujica.TreeState[string]
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Tree(c, &state, mujica.TreeOptions[string]{
+		Roots:    []string{"Nave", "Sacristy"},
+		Children: func(n string) []string { return kids[n] },
+		Label:    func(n string) string { return n },
+	}).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` | 内置“暂无数据” | 无数据时的说明文字。 |
+
+## 状态
+
+默认、悬停、选中（Accent 填充 + 勾选标记）、聚焦、展开/折叠（箭头旋转）、子项加载中、子项加载失败、空、首次加载与失败。
+
+## 事件
+
+`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`），元素数受可见区域限制，但遍历成本随展开节点数增长。
+- 单选跟随节点的搜索范围为 1000 行（ui/list.go:30）。
+- 异步加载由调用方在后台完成并通过 `Window.Update` 回到界面线程。