Tree 树形

可筛选、可选择的层级树

已验证自 0.3.4

用法

基础

filterText 接收搜索文本，匹配分支临时展开。

示例加载中...

后台权限域

选中的 key 驱动右侧详情、穿梭框或审计流。

示例加载中...

最佳实践

把 key 当作持久标识，不要从会翻译或重命名的文案派生。
只有其它界面需要掌握展开状态时才用 expandedKeys，否则用 defaultExpandedKeys。
权限域树保持单选，资源授权交给 TxTransfer、DataTable 或详情面板。
用 leaf=false 表示懒加载占位时，外围 UI 要提供加载或空子级状态；TxTree 不会自行拉取子节点。
用 item 插槽替换行时，调用 toggleExpand() 与 toggleSelect()，不要复制内部状态逻辑。

API 参考

属性

属性名	类型	默认值	说明
`nodes`	`TreeNode[]`	`[]`	树形数据源。
`modelValue`	`string \| number \| Array<string \| number>`	-	选中 key（`multiple` 时为数组）；不绑定时由树自行维护。
`multiple`	`boolean`	`false`	以数组形式切换多个选中 key。
`selectable`	`boolean`	`true`	允许行与 checkbox 选择；关闭后仍可展开。
`checkable`	`boolean`	`false`	为每个可见节点显示 checkbox，不向子孙级联。
`disabled`	`boolean`	`false`	禁用整棵树的选择；展开仍可用。
`defaultExpandedKeys`	`Array<string \| number>`	`[]`	非受控的初始展开 key；未传 `expandedKeys` 时，其变化会重置展开状态。
`defaultSelectedKeys`	`Array<string \| number>`	-	非受控的初始选中态；绑定 `modelValue` 时忽略。
`expandedKeys`	`Array<string \| number>`	-	受控展开 key；父级需在 `update:expandedKeys` 后回传。
`indent`	`number`	`16`	每级缩进（px）。
`filterText`	`string`	`''`	过滤文本；非空时匹配分支临时展开。
`filterMethod`	`(node: TreeNode, query: string) => boolean`	-	自定义匹配，收到 trim 后的原始查询；默认按小写 label 包含匹配。

事件

事件名	参数	说明
`update:modelValue`	`value: TreeValue`	点击可选节点或 checkbox 变化后触发。
`select`	`{ key: TreeKey, node: TreeNode }`	紧随 `update:modelValue` 触发，带选中节点。
`toggle`	`{ key: TreeKey, expanded: boolean }`	节点展开或折叠后触发。
`update:expandedKeys`	`keys: TreeKey[]`	受控与非受控时都返回下一组展开 key。

插槽

插槽名	参数	说明
`item`	`{ node, level, expanded, hasChildren, selected, toggleExpand, toggleSelect, indent }`	替换整行渲染；调用插槽 helper 保留选择与展开行为。
`empty`	-	过滤后无可见行时的空状态，默认为 `No results`。

TreeNode

字段	类型	说明
`key`	`string \| number`	稳定唯一的 key，用于选择与展开。
`label`	`string`	行文本，也是默认过滤目标。
`children`	`TreeNode[]`	子节点。
`leaf`	`boolean`	设为 `false` 时，没有子节点也显示展开箭头。
`disabled`	`boolean`	禁用该节点的选择；有子节点时仍可展开。
`icon`	`TxIconSource \| string`	节点图标；字符串按 class 图标处理。

概述

展开与选中都分受控与非受控：传入 expandedKeys 或绑定 modelValue 后，组件只派发事件，父级回传后视图才更新。
过滤不改写展开状态，只临时展开匹配节点的祖先。
选择模型是扁平的：checkable 只改变控件形态，没有半选或级联。
disabled 与 node.disabled 阻止选择，但仍可展开。
根节点为 role="tree"（multiple 时带 aria-multiselectable）；每行为 role="treeitem"，带 aria-level、aria-setsize、aria-posinset 及按需的 aria-expanded / aria-selected / aria-disabled。item 插槽只替换行内视觉，这些语义保留。

技术实现

节点按展开状态与过滤结果展平成可见行。
源码：packages/tuffex/packages/components/src/tree/。

packages/tuffex/packages/components/src/tree/index.ts

自定义

主题变量	用途
`--tx-text-color-primary`	行标签颜色。
`--tx-text-color-secondary`	展开箭头与空状态。
`--tx-color-primary`	选中行底色。
`--tx-fill-color`	悬停行底色。