TreeSelect
从层级候选项中选择。中文惯用名：树选择器。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.tree-select |
| 名称 | TreeSelect |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 从层级候选项中选择 |
| 描述 | 中文惯用名：树选择器。 |
预览
静态结构：TreeSelect 为 input 风格触发器（data-slot="treeselect-trigger"，显示选中节点 label，缺省「请选择」）+ 受控 Popover 弹层；searchable 时弹层顶部为过滤输入（按 label 过滤，命中节点的祖先保留展开），下方为 data-slot="treeselect-tree" 内联树（自实现）：每个节点 data-slot="treeselect-node"，含子节点的节点前置 ChevronRight 展开 / 收起按钮（展开时旋转 90°），按深度缩进，选中节点高亮；打开弹层时自动展开到当前选中节点。单选，选中即关闭弹层。Form 内声明 name 时外层包 FieldShell（label + 校验错误）。
DSL 结构
{
"type": "TreeSelect",
"props": {
"name": "department",
"placeholder": "请选择部门",
"options": [
{
"label": "华东大区",
"value": "east",
"children": [
{
"label": "杭州分公司",
"value": "hz"
},
{
"label": "上海分公司",
"value": "sh"
}
]
},
{
"label": "华南大区",
"value": "south"
}
]
}
}何时用
何时使用
- 从层级候选项中选择单个节点：组织架构、分类树、目录归属。
- 树节点均可选（父节点也是合法值），且需要展开 / 收起浏览或按 label 搜索。
何时不用
- 只有叶子才是合法值、强调逐级下钻：使用 Cascader（值是路径数组）。
- 扁平候选列表：使用 Select，不必引入树结构。
- 需要多选：当前实现为单选，多选用 Checkbox 组或其他多选组件。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 基础树选择 | 弹层内联树，可展开 / 收起逐级浏览 | 层级不深、节点可浏览的场景 |
| searchable 搜索 | 弹层顶部过滤输入，按 label 过滤并保留祖先展开 | 树较大、需要快速定位节点 |
| placeholder 空态 | 未选时触发器显示弱提示（缺省「请选择」） | 非必填层级字段 |
| disabled 禁用 | 触发器半透明不可点开 | 联动未就绪或只读场景 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（FieldShell 呈现） |
rules | FieldRule[] | — | 校验规则 |
options | TreeSelectOption[] | [] | 嵌套选项树（{ label, value, children? }） |
value | `string | number` | — |
placeholder | string | '请选择' | 空态提示文案 |
searchable | boolean | false | 弹层顶部显示过滤输入（按 label 过滤，命中节点的祖先保留展开） |
disabled | boolean | false | 禁用触发器 |
onChange | `(value: string | number) => void` | — |
className | string | — | 根节点 class（Form 内为 form-item 容器，独立渲染时为触发器） |
style | CSSProperties | — | 根节点内联样式（同 className 的挂载规则） |
使用规范
- 与 Cascader 的边界：TreeSelect 值是单个节点 value（父节点可选），Cascader 值是路径数组且叶子才完成选择；按数据语义选型。
- 树超过两级或节点较多时开 searchable，让用户按 label 过滤而非逐级翻找。
- options 的 value 在整棵树内必须唯一，否则选中回显会命中第一个匹配节点。
- 父节点是否可选取决于业务：实现上任意节点点击即选中并关闭弹层，不要假设父节点仅用于展开。
- 打开弹层自动展开到当前选中节点；value 必须能在 options 中找到，否则触发器回退空态。
正例
- ✓ 部门归属：options 为组织架构树，选中任意层级部门，Form 内 name + 必填 rules。
- ✓ 分类选择：searchable 开启，输入关键字过滤命中节点及其祖先。
- ✓ 回显编辑：value 传入已存节点 value，打开弹层自动展开到该节点。
反例
- ✕ 用 TreeSelect 做省市区选择且只存叶子（应使用 Cascader，保留完整路径）。
- ✕ 树内 value 重复，回显命中错误节点。
- ✕ 扁平十几个选项也套树结构（应使用 Select，减少层级负担）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。