TreeSelect 树型选择控件

开发指南

何时使用

类似 Select 的选择控件,可选择的数据结构是一个树形结构时,可以使用 TreeSelect,例如公司层级、学科系统、分类目录等等。

基本

最简单的单选用法。

使用数据直接生成

使用 dataSource 生成树结构,除设置 label, value, key, children 属性外,还可传入 TreeNode 的其他属性,包括 selectable, disabled, checkboxDisabled, isLeaf,推荐使用 dataSource 而不是手动生成 TreeNode 的方式生成树,这样使用更简单,性能更好。

复选框多选

展示复选框多选的功能。

受控

展示树选择受控的用法。

TreeSelect:

无障碍

通过aria-labelledby对组件进行描述。关于键盘操作请参考ARIA and KeyBoard

API

TreeSelect

参数说明类型默认值
children树节点ReactNode-
size选择框大小

可选值:
'small', 'medium', 'large'
Enum'medium'
placeholder选择框占位符String-
disabled是否禁用Booleanfalse
hasArrow是否有下拉箭头Booleantrue
hasBorder是否有边框Booleantrue
hasClear是否有清空按钮Booleanfalse
label自定义内联 labelReactNode-
readOnly是否只读,只读模式下可以展开弹层但不能选择Boolean-
autoWidth下拉框是否与选择器对齐Booleantrue
dataSource数据源,该属性优先级高于 childrenArray<Object>-
value(受控)当前值String/Array<String>-
defaultValue(非受控)默认值String/Array<String>null
valueRender自定义选中的值渲染方式Functionitem => item.labelitem.value
onChange选中值改变时触发的回调函数

签名:
Function(value: String/Array, data: Object/Array) => void
参数:
value: {String/Array} 选中的值,单选时返回单个值,多选时返回数组
data: {Object/Array} 选中的数据,包括 value, label, pos, key属性,单选时返回单个值,多选时返回数组,父子节点选中关联时,同时选中,只返回父节点
Function() => {}
showSearch是否显示搜索框Booleanfalse
onSearch在搜索框中输入时触发的回调函数

签名:
Function(keyword: String) => void
参数:
keyword: {String} 输入的关键字
Function() => {}
notFoundContent无数据时显示内容ReactNode'Not Found'
multiple是否支持多选Booleanfalse
treeCheckable下拉框中的树是否支持勾选节点的复选框Booleanfalse
treeCheckStrictly下拉框中的树勾选节点复选框是否完全受控(父子节点选中状态不再关联)Booleanfalse
treeCheckedStrategy定义选中时回填的方式

可选值:
'all'(返回所有选中的节点)
'parent'(父子节点都选中时只返回父节点)
'child'(父子节点都选中时只返回子节点)
Enum'parent'
treeDefaultExpandAll下拉框中的树是否默认展开所有节点Booleanfalse
treeDefaultExpandedKeys下拉框中的树默认展开节点key的数组Array<String>[]
treeLoadData下拉框中的树异步加载数据的函数,使用请参考Tree的异步加载数据Demo

签名:
Function(node: ReactElement) => void
参数:
node: {ReactElement} 被点击展开的节点
Function-
treeProps透传到 Tree 的属性对象Object{}
defaultVisible初始下拉框是否显示Booleanfalse
visible当前下拉框是否显示Boolean-
onVisibleChange下拉框显示或关闭时触发事件的回调函数

签名:
Function(visible: Boolean, type: String) => void
参数:
visible: {Boolean} 是否显示
type: {String} 触发显示关闭的操作类型
Function() => {}
popupStyle下拉框自定义样式对象Object-
popupClassName下拉框样式自定义类名String-
popupContainer下拉框挂载的容器节点String/Function-
popupProps透传到 Popup 的属性对象Object-
followTrigger是否跟随滚动Boolean-

TreeSelect.Node

参数说明类型默认值
children树节点ReactNode-
label节点文本内容ReactNode'---'
selectable单独设置是否支持选中,覆盖 Tree 的 selectableBoolean-
checkable单独设置是否出现复选框,覆盖 Tree 的 checkableBoolean-
editable单独设置是否支持编辑,覆盖 Tree 的 editableBoolean-
draggable单独设置是否支持拖拽,覆盖 Tree 的 draggableBoolean-
disabled是否禁止节点响应Booleanfalse
checkboxDisabled是否禁止勾选节点复选框Booleanfalse
isLeaf是否是叶子节点,设置loadData时生效Booleanfalse

dataSource 数据结构

const dataSource = [{
    label: '服装',
    value: '1',
    key: '1',
    selectable: false,
    children: [{
        label: '男装',
        value: '2',
        key: '2',
        children: [{
            label: '外套',
            value: '4',
            key: '4',
            disableCheckbox: true
        }, {
            label: '夹克',
            value: '5',
            key: '5',
            disabled: true
        }]
    }, {
        label: '女装',
        value: '3',
        key: '3',
        children: [{
            label: '裙子',
            value: '6',
            key: '6'
        }]
    }]
}];

如果不传入 key,TreeSelect 会使用内部计算出来的位置字符串作为 key 值,如果你想指定诸如 treeDefaultExpandedKeys 这样的属性,请传入自定义的 key 值,让它和 value 是一个值,是一个很好的办法。

ARIA and KeyBoard

按键说明
Enter打开选择树或选择某一项
Up Arrow获取同级当前项前一项焦点
Down Arrow获取同级当前项后一项焦点
Right Arrow打开当前元素的下一级子树并聚焦到第一项
Left Arrow返回到当前元素的父节点并关闭当前子树