TreeSelect 树选择器

用法

基础

示例加载中...

权限编排

TxTreeSelect 选择归属团队，与 TxTransfer、TxTimeline 组成授权流程。

示例加载中...

最佳实践

紧凑的归属、命名空间、分类与组织单元选择用 TxTreeSelect；需要常驻上下文、批量操作或自定义行控件时用 TxTree。
nodes 用稳定的 key 与 label，不要沿用旧选择器的 value 字段；key 不依赖本地化文案。
渲染前让值的形态匹配 multiple；运行时切换不会在标量与数组间自动转换。
默认展开保持浅层，例如根部门或产品域。
node 插槽只放徽标或副标题，不要加与行选择竞争的点击目标。

API 参考

属性

属性名	类型	默认值	说明
`modelValue`	`string \| number \| Array<string \| number> \| undefined`	-	单选时为选中 key；`multiple` 时为 key 数组。
`nodes`	`TreeSelectNode[]`	`[]`	下拉树节点，也用于解析触发器文本。
`multiple`	`boolean`	`false`	启用复选框多选，触发器以标签显示选中项。
`disabled`	`boolean`	`false`	禁用触发器、下拉交互、键盘切换与清空。
`placeholder`	`string`	`'请选择'`	没有可显示的选中 label 时的占位文本。
`searchable`	`boolean`	`true`	显示搜索框，文本作为 `filterText` 传给内部 `TxTree`。
`clearable`	`boolean`	`true`	有选中项且未禁用时显示清空按钮。
`placement`	`PopoverPlacement`	`'bottom-start'`	下拉层的位置。
`dropdownOffset`	`number`	`6`	下拉层与触发器的距离。
`dropdownWidth`	`number`	`0`	下拉层宽度；`0` 交给 `TxPopover` 决定。
`dropdownMaxWidth`	`number`	`480`	下拉层最大宽度。
`dropdownMaxHeight`	`number`	`320`	下拉树最大高度，超出后滚动。
`defaultExpandedKeys`	`Array<string \| number>`	`[]`	内部 `TxTree` 的初始展开 key。

事件

事件名	参数	说明
`update:modelValue`	`value: TreeSelectValue`	选择、清空或调用 `setValue()` 后触发。
`change`	`value: TreeSelectValue`	紧随 `update:modelValue`，值相同。
`open`	-	下拉层打开时触发。
`close`	-	下拉层关闭时触发。

插槽

插槽名	参数	说明
`node`	`{ node, level, expanded, selected }`	替换行内的节点标签区；箭头、复选框、缩进与点击仍由组件处理。

暴露方法

名称	类型	说明
`open()`	`() => void`	打开下拉层。
`close()`	`() => void`	关闭下拉层。
`toggle()`	`() => void`	切换下拉层。
`focus()`	`() => void`	聚焦 combobox 触发器。
`blur()`	`() => void`	使 combobox 触发器失焦。
`clear()`	`() => void`	未禁用时清空：单选派发 `undefined`，多选派发 `[]`。
`setValue(value)`	`(value: TreeSelectValue) => void`	经 `update:modelValue` 与 `change` 派发传入值，不校验它是否在 `nodes` 中。
`getValue()`	`() => TreeSelectValue`	返回当前的 `modelValue`。
`getCheckedKeys()`	`() => Array<string \| number>`	以数组返回选中 key，单选模式亦然。

类型

type TreeSelectValue = string | number | Array<string | number> | undefined

interface TreeSelectNode {
  key: string | number // 稳定唯一，用作选中值
  label: string // 节点文本、默认搜索目标与触发器文本
  disabled?: boolean // 禁止选择该节点
  children?: TreeSelectNode[]
}

概述

触发器是可聚焦的 role="combobox"（aria-haspopup="tree"，aria-controls 指向浮层），浮层内是 role="tree" 的 TxTree；Enter 与 Space 开合下拉层，Escape 关闭。
单选选中后关闭下拉层，清空为 undefined；多选保持打开，清空为 []。
禁用节点不可选，但有子节点时仍可展开。
搜索使用 TxTree 默认的 label 过滤，不支持自定义 filterMethod 或受控 expandedKeys；需要领域搜索时在外层组合，或直接用 TxTree。
触发器文本从当前 nodes 解析；未知的选中 key 仍留在选中集合中，但不显示文本。
setValue() 只派发事件，modelValue 仍由父级经 v-model 持有；常规代码优先用 v-model。

技术实现

下拉层由 TxPopover 承载，位置与宽度属性透传给它；树复用 TxTree，只传入 defaultExpandedKeys、filterText 与 multiple。
源码：packages/tuffex/packages/components/src/tree-select/。

查看源码

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