输入类 · TreeSelect
树选择器
树选择器用于多层级树形数据的结构化展示 & 选取,例如显示文件夹与文件的列表、显示组织架构成员列表等等。

代码演示

如何引入

基本用法

最简单的用法,默认为单选模式,每一级菜单项均可选择。

多选

设置 multiple,可以进行多选。多选情况下所有子项都被选择时,自动勾选显示其父项。通过设置 maxTagCount 属性,可以设置显示的标签数量上限。通过设置 leafOnly (>= v0.32.0) 属性,可以设置只展示叶子节点,同时 onChange 的回调入参也会只有叶子节点的值。

可搜索的

通过设置 filterTreeNode 属性可支持搜索功能。默认对 label 值进行搜索,可通过 treeNodeFilterProp 更改。
如果只希望展示过滤后的结果,可以设置 showFilteredOnly

搜索框位置

可以使用 searchPosition 来设置搜索框的位置,可选: dropdown(默认)、trigger
当输入框位于 trigger 时:
  1. 搜索框占位符由 placeholder 控制;
  2. showClear=true 时,点击输入框的清空按钮,将同时清空 inputValue 和 value。

尺寸大小

可以通过 size 设置尺寸大小,可选: 'small'、'default'、'large'

默认展开

defaultExpandAllexpandAll 均可以设置 TreeSelect 的默认展开/收起状态。二者的区别是,defaultExpandAll 只在初始化时生效,而 expandAll 不仅会在初始化时生效,当数据(treeData)发生动态更新时,expandAll 也仍然生效。
其中,expandAll 是从 1.30.0 开始支持的。
在下面的 demo 中,TreeData 更新后,defaultExpandAll 失效,expandAll 仍然生效。

禁用

严格禁用

version: >= 1.30.0
可以使用 disableStrictly 来开启严格禁用。开启严格禁用后,当节点是 disabled 的时候,则不能通过子级或者父级的关系改变选中状态。
以下面的 demo 为例,节点"中国"开启了严格禁用,因此,当我们改变其父节点"亚洲"的选中状态时,也不会影响到节点"中国"的选中状态。

受控

传入 value 时即为受控组件,可以配合 onChange 使用。

节点选中关系

版本:>= 2.5.0
多选时,可以使用 checkRelation 来设置节点之间选中关系的类型,可选:'related'(默认)、'unRelated'。当选中关系为 'unRelated' 时,意味着节点之间的选中互不影响。

开启搜索的展开受控

传入 expandedKeys 时即为展开受控组件,可以配合 onExpand 使用。当展开受控时,如果开启 filterTreeNode 并进行搜索是不会再自动展开节点的,此时,节点的展开完全由 expandedKeys 来控制。你可以利用 onSearch 的入参 filteredExpandedKeys(version: >= 2.6.0) 来实现展开受控时的搜索展开效果。

虚拟化

列表虚拟化,用于大量树节点的情况。开启后,动画效果将被关闭。
virtualize 是一个包含下列值的对象:
  • height: 高度值,如果为 string 必须有计算高度才能被渲染出来,即其父节点有 offsetHeight。建议传入数组。
  • width: 宽度值,默认 100%
  • itemSize: 每行的treeNode的高度,必传
如果带搜索框,建议开启 showFilteredOnly 减少多余节点的渲染。

动态更新数据

异步加载数据

通过设置 loadData 可以动态加载数据,此时需要在数据中传入 isLeaf 标明叶子节点。

自定义 Trigger

如果默认的触发器样式满足不了你的需求,可以用 triggerRender 自定义选择框的展示。
triggerRender 入参如下:

自定义渲染已选项

你可以通过 renderSelectedItem 自定义选择框中已选项标签的渲染结构。
  • 单选时 renderSelectedItem(treeNode: TreeNode) => content:ReactNode
  • 多选时 renderSelectedItem(treeNode: TreeNode, { index:number, onClose:function }) => { isRenderInTag:bool, content:ReactNode }
    • isRenderInTag 为 true 时,会自动将 content 包裹在 Tag 中渲染(带有背景色以及关闭按钮)
    • isRenderInTag 为 false 时,将直接渲染返回的 content

API参考

TreeSelect

属性说明类型默认值版本
arrowIcon自定义右侧下拉箭头Icon,当showClear开关打开且当前有选中值时,hover会优先显示clear iconReactNode1.15.0
autoAdjustOverflow浮层被遮挡时是否自动调整方向(暂时仅支持竖直方向,且插入的父级为 body)booleantrue0.34.0
autoExpandParent是否自动展开父节点booleanfalse0.34.0
checkRelation多选时,节点之间选中状态的关系,可选:'related'、'unRelated'string'related'2.5.0
className选择框的 className 属性string--
clickToHide选择后是否自动关闭下拉弹层,仅单选模式有效booleantrue1.5.0
defaultExpandAll设置在初始化时是否展开所有节点。而如果后续数据(treeData)发生改变,这个 api 是无法影响节点的展开情况的,如果有这个需要可以使用 expandAllbooleanfalse0.32.0
defaultExpandedKeys默认展开的节点,显示其直接子级string[]-0.32.0
defaultOpen默认展开下拉菜单booleanfalse0.32.0
defaultValue指定默认选中的条目string | number | TreeNode | (string | number | TreeNode)[]--
disabled是否禁用booleanfalse-
disableStrictly是否严格禁用booleanfalse1.30.0
dropdownClassName下拉菜单的 className 属性string--
dropdownMatchSelectWidth下拉菜单最小宽度是否等于Selectbooleantrue-
dropdownStyle下拉菜单的样式CSSProperties--
emptyContent当搜索无结果时展示的内容ReactNode暂无数据-
expandAction展开逻辑,可选 false, 'click', 'doubleClick'。默认值为 false,即仅当点击展开按钮时才会展开boolean | stringfalse1.4.0
expandAll设置是否默认展开所有节点,若后续数据(treeData)发生改变,默认的展开情况也是会受到这个 api 影响的booleanfalse1.30.0
expandedKeys(受控)展开的节点,默认展开节点显示其直接子级string[]-0.32.0
filterTreeNode是否根据输入项进行筛选,默认用 treeNodeFilterProp 的值作为要筛选的 TreeNode 的属性值boolean|(inputValue: string, treeNodeString: string) => booleanfalse-
getPopupContainer指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 position: relativefunction():HTMLElement--
insetLabel前缀标签别名,主要用于 FormReactNode-0.28.0
labelEllipsis是否开启label的超出省略,默认虚拟化状态下开启booleanfalse|true(virtualized)1.8.0
leafOnly多选模式下是否开启 onChange 回调入参及展示标签只有叶子节点booleanfalse0.32.0
loadData异步加载数据,需要返回一个Promise(treeNode: TreeNode) => Promise-1.32.0
loadedKeys(受控)已经加载的节点,配合 loadData 使用Set< string >-1.32.0
maxTagCount最多显示多少个 tagnumber--
motionExpand是否开启选项树节点动画booleantrue-
multiple是否支持多选booleanfalse-
optionListStyleoptionList的样式CSSProperties-1.8.0
outerBottomSlot渲染在弹出层底部,与 optionList 平级的自定义 slotReactNode-1.1.0
outerTopSlot渲染在弹出层顶部,与 optionList 平级的自定义 slot,注意如果开启了 filterTreeNode 会取代搜索框,可以通过 search 方法来自行处理ReactNode-1.9.0
placeholder选择框默认文字string--
prefix前缀标签ReactNode-0.28.0
renderFullLabel完全自定义label的渲染函数,入参及用法详见(obj) => ReactNode-1.7.0
renderLabel自定义label的渲染函数,入参及用法详见(label:ReactNode, data:TreeNode) => ReactNode-1.6.0
renderSelectedItem自定义渲染已选项Function-1.26.0
searchAutoFocus搜索框自动聚焦booleanfalse1.27.0
searchPlaceholder搜索框默认文字string--
searchPosition设置搜索框的位置,可选: dropdowntriggerstringdropdown1.29.0
showClear当值不为空时,trigger 是否展示清除按钮booleanfalse
showFilteredOnly搜索状态下是否只展示过滤后的结果booleanfalse0.32.0
showSearchClear是否显示搜索框的清除按钮booleantrue0.35.0
size选择框大小,可选 largesmalldefaultstringdefault-
style选择框的样式CSSProperties--
suffix后缀标签ReactNode-0.28.0
treeDatatreeNodes 数据,如果设置则不需要手动构造 TreeNode 节点(key 值在整个树范围内唯一)TreeNode[][]-
treeNodeFilterProp搜索时输入项过滤对应的 treeNode 属性stringlabel-
treeNodeLabelProp作为显示的 prop 设置stringlabel-
triggerRender自定义触发器渲染方法({ placeholder: string }) => ReactNode-0.34.0
validateStatus校验结果,可选 warningerrordefault(只影响样式背景色)string-0.32.0
value当前选中的节点的value值,传入该值时将作为受控组件string | number | TreeNode | (string | number | TreeNode)[]--
virtualize列表虚拟化,用于大量树节点的情况,由 height, width, itemSize 组成,参考 Tree - Virtualize Object。开启后将关闭动画效果。object-0.32.0
zIndextreeSelect下拉菜单的zIndexnumber10300.30.0
onBlur失去焦点时的回调function(event)--
onChange选中树节点时调用此函数,默认返回值为当前所有选中项的value值及节点属性;如果是通过tag关闭,event参数为nullFunction--
onChangeWithObject是否将选中项 option 的其他属性作为回调。设为 true 时,onChange 的入参类型Function(node|node[], e) 此时如果是受控,也需要把 value 设置成 object,且必须含有 value 的键值;defaultValue同理。booleanfalse1.0.0
onExpand展示节点时调用function(expandedKeys:array, {expanded: bool, node})--
onFocus聚焦时的回调function(event)--
onLoad节点加载完毕时触发的回调(loadedKeys: Set<string>, treeNode: TreeNode) => void-1.32.0
onSearch文本框值变化时回调。 入参 filteredExpandedKeys 表示因为搜索或 value/defaultValue 而展开的节点的 key, 可以配合 expandedKeys 受控时使用function(sugInput: string, filteredExpandedKeys: string[])-filteredExpandedKeys 在 2.6.0 中新增
onSelect被选中时调用,返回值为当前事件选项的key值function(selectedKey:string, selected: bool, selectedNode: TreeNode)--
onVisibleChange弹出层展示/隐藏时触发的回调function(isVisible:boolean)1.4.0

TreeNode

不同 TreeNode 的 key 值要求必填且唯一。label 允许重复。v>=1.7.0 之前 value 值要求必须必填且唯一。 v>=1.7.0 之后 value 值非必填。此时 onChange, value, defaultValue 及 onChangeWithObject 中所取的 value 属性值将改为 key 值。 为了保证行为的符合预期,treeData 中的 value 值或者全部不填写,或者全部填写且唯一,不建议混写。
属性说明类型默认值
value属性值string|number-
label展示的文本string|ReactNode-
icon自定义图标ReactNode-
disabled是否禁用,多选状态下支持booleanfalse
keyrequired且要求唯一string-
isLeaf是否为叶子节点boolean-

Method

  • search(sugInput: string) 如果需要自定义搜索框可以使用该方法。

Accessibility

ARIA

  • TreeSelect 会自动设置 aria-label 为 'TreeSelect',也支持用户自行设置 aria-label 来表示该 TreeSelect 作用;
  • TreeSelect 允许用户设置 aria-describedbyaria-errormessagearia-invalidaria-labelledbyaria-required,另外,Form 会为 Form.TreeSelect 自动设置这些属性;
  • TreeSelect 会自动为每个子节点分别设置 aria-disabledaria-checkedaria-selectedaria-level 来表明节点状态及层级;
示例:

设计变量

© 2021 Semi Design. All rights reserved.

京ICP备19058139号-13浙公网安备 33011002016131号

Designed & Developed with love by Douyin FE & MED