Choices: components 031-040 (wip)

2026-10-05 12:26:17 -04:00
1 parent cfc7ab023d
commit d67eb60bf9
@@ -0,0 +1,59 @@
+# 040 TreeSelect · 树选择
+
+## 用途
+
+在树形数据中选择一个或多个节点，支持搜索、展开折叠、半选显示，父子联动规则可配置。
+
+## 最小示例
+
+```go
+var roles []string
+nodes := []mujica.TreeSelectNode{
+	{ID: "court", Label: "Court", Children: []mujica.TreeSelectNode{
+		{ID: "king", Label: "King"},
+		{ID: "queen", Label: "Queen"},
+	}},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.TreeSelect(c, &roles, nodes, mujica.TreeSelectOptions{Multiple: true, Label: "Roles"})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func TreeSelect(c *ui.Context, selected *[]string, nodes []TreeSelectNode, opts TreeSelectOptions) ChoiceResult`。单选模式下 `*selected` 最多一个 ID，否则 panic。节点 ID 在整棵树中必须唯一。
+
+`TreeSelectNode`：`ID`、`Label`、`Children []TreeSelectNode`、`Disabled`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Multiple` | `bool` | false | 多选（复选框）；单选时点击节点即选择并关闭。 |
+| `Rule` | `TreeSelectRule` | `TreeSelectCascade` | 多选父子规则：`TreeSelectCascade` 勾选父节点即勾选其全部可用叶节点，值只含叶节点 ID，父节点按子节点显示全选/半选；`TreeSelectIndependent` 每个节点独立勾选，值可含任意 ID。 |
+| `Placeholder` | `string` | 内置“请选择…” | 无值时提示。 |
+| `MaxTags` | `int` | 0 → 3 | 多选时字段中显示的标签数，其余折叠为“+N”。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Label` | `string` | "" | 无障碍名称。 |
+
+## 状态
+
+字段：占位、单值文字、多值标签与折叠、展开、聚焦、禁用。弹层：搜索框、展开/折叠箭头、未选/选中/半选方框（单选为玫瑰底高亮）、禁用节点（联动时被跳过）、无结果。搜索时显示匹配节点及其祖先并自动展开。
+
+## 事件
+
+`Changed()` 在选择变化的那一帧返回 true。
+
+## 键盘操作
+
+- Enter / Space / ↓：打开弹层，焦点在搜索框；搜索框中 ↓ 进入树。
+- ↑/↓、Home、End：在可见节点间移动。
+- →：展开；已展开时进入第一个子节点。←：折叠；已折叠或叶节点时回到父节点。
+- Space：勾选（多选）；Enter / Space：选择（单选）。
+- Escape：关闭，焦点回到字段。
+
+## 限制
+
+- 树行基于 `ui.CheckboxBase` / `ui.ButtonBase` 自绘。MyGo 的 `TreeItem` 只能显示文字标签，无法放入复选框（ui/tree.go:44），故未复用。
+- 展开状态与半选状态只在画面上表示：MyGo 不对自定义元素公开 expanded 与 mixed 的设置（ui/base.go:297、ui/element.go:282 仅内部设置），屏幕阅读器读不到这两个状态；展开箭头带“展开/收起 + 节点名”的名称。
+- 列表未虚拟化，适合数千节点以内。