TreeSelect 树形选择
含有下拉菜单的树形选择器，结合了 el-tree 和 el-select 两个组件的功能。
基础用法
export function TreeSelectBasic() { const [value, setValue] = useState<TreeSelectValue | undefined>(); return ( <> <ElTreeSelect value={value} onChange={setValue} data={DATA} renderAfterExpand={false} style={width} /> <ElDivider /> show checkbox:{" "} <ElTreeSelect value={value} onChange={setValue} data={DATA} renderAfterExpand={false} showCheckbox style={width} /> </> );}
选择任意级别
当属性 check-strictly=true 时，任何节点都可以被选择，否则只有子节点可被选择。
当使用 show-checkbox时，由于 check-on-click-node 默认值是 false，这时候只能通过 checkbox 来选中，当然您也可以将其设置成 true，这样点击整个 node 都可以用来完成选择
在使用 show-checkbox 时，因为 check-on-click-leaf 默认值为 true， 最后一个树节点可以通过点击节点进行勾选。
show checkbox:
show checkbox with `check-on-click-node`:
export function TreeSelectCheckStrictly() { const [value, setValue] = useState<TreeSelectValue | undefined>(); return ( <> <ElTreeSelect value={value} onChange={setValue} data={DATA} checkStrictly renderAfterExpand={false} style={width} /> <ElDivider /> show checkbox:{" "} <ElTreeSelect value={value} onChange={setValue} data={DATA} checkStrictly renderAfterExpand={false} showCheckbox style={width} /> <ElDivider /> show checkbox with `check-on-click-node`:{" "} <ElTreeSelect value={value} onChange={setValue} data={DATA} checkStrictly renderAfterExpand={false} showCheckbox checkOnClickNode style={width} /> </> );}
多选
show checkbox:
show checkbox with `check-strictly`:
export function TreeSelectMultiple() { const [value, setValue] = useState<TreeSelectValue | undefined>([]); const [valueStrictly, setValueStrictly] = useState<TreeSelectValue | undefined>( [], ); return ( <> <ElTreeSelect value={value} onChange={setValue} data={DATA} multiple renderAfterExpand={false} style={width} /> <ElDivider /> show checkbox:{" "} <ElTreeSelect value={value} onChange={setValue} data={DATA} multiple renderAfterExpand={false} showCheckbox style={width} /> <ElDivider /> show checkbox with `check-strictly`:{" "} <ElTreeSelect value={valueStrictly} onChange={setValueStrictly} data={DATA} multiple renderAfterExpand={false} showCheckbox checkStrictly checkOnClickNode style={width} /> </> );}
禁用选项
export function TreeSelectDisabled() { const [value, setValue] = useState<TreeSelectValue | undefined>(); return ( <ElTreeSelect value={value} onChange={setValue} data={[ { value: "1", label: "Level one 1", disabled: true, children: [ { value: "1-1", label: "Level two 1-1", disabled: true, children: [ { value: "1-1-1", label: "Level three 1-1-1", disabled: true }, ], }, ], }, ...DATA.slice(1), ]} style={width} /> );}
可筛选
使用关键字筛选或自定义筛选方法。 filterMethod可以自定义数据筛选的方法， filterNodeMethod可以自定义节点数据筛选的方法。
filter method:
filter node method:
export function TreeSelectFilterable() { const [value, setValue] = useState<TreeSelectValue | undefined>(); const [data, setData] = useState<TreeData>(SOURCE_DATA); const filterMethod = (keyword: string) => { setData( keyword ? (SOURCE_DATA.filter((item) => String(item.label).includes(keyword), ) as TreeData) : SOURCE_DATA, ); }; const filterNodeMethod = (keyword: unknown, item: Record<string, unknown>) => String(item.label).includes(String(keyword)); return ( <> <ElTreeSelect value={value} onChange={setValue} data={SOURCE_DATA} filterable style={width} /> <ElDivider /> filter method:{" "} <ElTreeSelect value={value} onChange={setValue} data={data} filterMethod={filterMethod} filterable style={width} /> <ElDivider /> filter node method:{" "} <ElTreeSelect value={value} onChange={setValue} data={SOURCE_DATA} filterNodeMethod={filterNodeMethod} filterable style={width} /> </> );}
自定义内容
export function TreeSelectSlots() { const [value, setValue] = useState<TreeSelectValue | undefined>(); const renderContent = ({ data }: { data: Record<string, unknown> }) => ( <span style={{ color: "#626AEF" }}>{String(data.label)}</span> ); return ( <> <ElTreeSelect value={value} onChange={setValue} data={DATA} style={width}> {({ data }) => ( <> {String(data.label)} <span style={{ color: "gray" }}>(suffix)</span> </> )} </ElTreeSelect> <ElDivider /> use render content:{" "} <ElTreeSelect value={value} onChange={setValue} data={DATA} renderContent={renderContent} style={width} /> </> );}
懒加载
export function TreeSelectLazy() { const [value, setValue] = useState<TreeSelectValue | undefined>(); const [value2, setValue2] = useState<TreeSelectValue | undefined>(5); const treeProps = { label: "label", children: "children", isLeaf: "isLeaf" }; return ( <> <ElTreeSelect value={value} onChange={setValue} lazy load={loadLazyNode} props={treeProps} style={width} /> <ElDivider /> show lazy load label:{" "} <ElTreeSelect value={value2} onChange={setValue2} lazy load={loadLazyNode} props={treeProps} cacheData={[{ value: 5, label: "lazy load node5" }]} style={width} /> </> );}
使用 node-key 属性
默认情况下，modelValue 会查找 value 键。对于其他数据结构，必须提供 node-key 才能正常工作。
export function TreeSelectNodeKey() { const [value, setValue] = useState<TreeSelectValue | undefined>([2]); return ( <ElTreeSelect value={value} onChange={setValue} style={width} data={[ { id: 1, label: "Level one 1", children: [ { id: 2, label: "Level two 1-1" }, { id: 3, label: "Level two 1-2" }, ], }, ]} nodeKey="id" showCheckbox multiple defaultExpandAll /> );}
node-key 在整个树中应该是唯一的。value-key 与 node-key 具有相同的目标。- 与 select 组件相反，tree-select 不能检索对象值。
TreeSelect API
树形选择器组合了 ElTree 与 ElSelect 的能力，官方文档说明「原有属性未做改动，请查阅原组件文档」。
React 版沿用这一约定：树相关属性见 Tree、下拉相关属性见下表。
TreeSelect Attributes
| 属性名 | 说明 | 类型 | 默认值 |
|---|
| value | 选中值，单选为单值、多选为数组（对应官方 v-model） | string / number / array | — |
| data | 树数据 | array | [] |
| multiple | 是否多选 | boolean | false |
| clearable | 是否可清空 | boolean | false |
| filterable | 是否可筛选 | boolean | false |
| disabled | 是否禁用整个组件（对应官方 ElSelect 的 disabled） | boolean | false |
| placeholder | 占位文本 | string | 请选择 |
| size | 尺寸 | enum | — |
| value-key | 取值的字段名，对应官方 value-key | string | — |
| cache-data | 懒加载节点的缓存数据，结构同 data，用于取未加载节点的 label | array | [] |
| filter-method | 自定义筛选方法，由调用方重建 data | Function | — |
| filter-node-method | 自定义节点筛选方法 | Function | — |
| remote-method | 远程筛选方法 | Function | — |
| empty-values | 空值集合，缺省取全局配置 | array | — |
| value-on-clear | 清空时返回的值，缺省取全局配置 | string / number / boolean / Function | — |
| popper-class | 下拉浮层的额外类名 | string | — |
| visible | 下拉是否展开，传入即为受控 | boolean | — |
| class-name / style | 根元素类名与样式 | string / object | — |
Tree 属性透传
TreeProps 上的属性原样透传给内部的 ElTree：nodeKey、props、render-after-expand、
show-checkbox、check-strictly、check-on-click-node、check-on-click-leaf、
expand-on-click-node、default-expand-all、default-expanded-keys、default-checked-keys、
lazy、load、accordion、indent、highlight-current、auto-expand-parent、
render-content、allow-drag / allow-drop / draggable 等。
官方同样把 node-key || value-key || 'value' 作为内部树的 node-key，因此只传
value-key 也能正确寻址与勾选。
TreeSelect Events
| 事件名 | 说明 | 参数 |
|---|
| onChange | 选中值变化（对应官方 v-model 的 update:modelValue） | Function |
| onClear | 点击清空图标 | — |
| onRemoveTag | 多选模式下点击标签的关闭按钮 | Function |
| onVisibleChange | 下拉展开态变化，配合受控的 visible 使用 | Function |
| onFocus | 输入框聚焦 | Function |
| onBlur | 输入框失焦 | Function |
| onCheck | 勾选变化，转发自 ElTree 的 check | Function |
| onNodeClick | 节点被点击，转发自 ElTree 的 node-click | Function |
| onNodeExpand | 节点展开，转发自 ElTree 的 node-expand | Function |
| onReady | 拿到内部 ElTree 的实例句柄（替代官方 treeRef） | Function |
TreeSelect Slots
| 名称 | 说明 | 参数 |
|---|
| default | 自定义树节点内容（React 侧通过 children 函数 prop 传入） | ({ node, data, store }) => ReactNode |
Exposes
| 名称 | 说明 | 类型 |
|---|
| onReady 下发的实例 | 与 ElTree 的实例同构，含 getCheckedKeys / setCheckedKeys / filter / getNode 等 | TreeInstance |
