logoAnt Design

⌘ K
  • 设计
  • 研发
  • 组件
  • 博客
  • 资源
  • 国内镜像
5.25.2
  • 组件总览
  • 通用
    • Button按钮
    • FloatButton悬浮按钮
      5.0.0
    • Icon图标
    • Typography排版
  • 布局
    • Divider分割线
    • Flex弹性布局
      5.10.0
    • Grid栅格
    • Layout布局
    • Space间距
    • Splitter分隔面板
      5.21.0
  • 导航
    • Anchor锚点
    • Breadcrumb面包屑
    • Dropdown下拉菜单
    • Menu导航菜单
    • Pagination分页
    • Steps步骤条
    • Tabs标签页
  • 数据录入
    • AutoComplete自动完成
    • Cascader级联选择
    • Checkbox多选框
    • ColorPicker颜色选择器
      5.5.0
    • DatePicker日期选择框
    • Form表单
    • Input输入框
    • InputNumber数字输入框
    • Mentions提及
    • Radio单选框
    • Rate评分
    • Select选择器
    • Slider滑动输入条
    • Switch开关
    • TimePicker时间选择框
    • Transfer穿梭框
    • TreeSelect树选择
    • Upload上传
  • 数据展示
    • Avatar头像
    • Badge徽标数
    • Calendar日历
    • Card卡片
    • Carousel走马灯
    • Collapse折叠面板
    • Descriptions描述列表
    • Empty空状态
    • Image图片
    • List列表
    • Popover气泡卡片
    • QRCode二维码
      5.1.0
    • Segmented分段控制器
    • Statistic统计数值
    • Table表格
    • Tag标签
    • Timeline时间轴
    • Tooltip文字提示
    • Tour漫游式引导
      5.0.0
    • Tree树形控件
  • 反馈
    • Alert警告提示
    • Drawer抽屉
    • Message全局提示
    • Modal对话框
    • Notification通知提醒框
    • Popconfirm气泡确认框
    • Progress进度条
    • Result结果
    • Skeleton骨架屏
    • Spin加载中
    • Watermark水印
      5.1.0
  • 其他
    • Affix固钉
    • App包裹组件
      5.1.0
    • ConfigProvider全局化配置
    • Util工具类
      5.13.0

TreeSelect
树选择

树型选择控件。
使用import { TreeSelect } from "antd";
源码components/tree-select
文档
编辑此页更新日志

相关资源

Ant Design X
Ant Design Charts
Ant Design Pro
Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Web3
Ant Design Landing-首页模板集
Scaffolds-脚手架市场
Umi-React 应用开发框架
dumi-组件/文档研发工具
qiankun-微前端框架
Ant Motion-设计动效
国内镜像站点 🇨🇳

社区

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design 语雀专栏
Ant Design 知乎专栏
体验科技专栏
seeconf logoSEE Conf-蚂蚁体验科技大会
加入我们

帮助

GitHub
更新日志
常见问题
报告 Bug
议题
讨论区
StackOverflow
SegmentFault

Ant XTech logo更多产品

yuque logo语雀-构建你的数字花园
AntV logoAntV-数据可视化解决方案
Egg logoEgg-企业级 Node.js 框架
Kitchen logoKitchen-Sketch 工具集
Galacean logoGalacean-互动图形解决方案
xtech logo蚂蚁体验科技
主题编辑器
Made with ❤ by
蚂蚁集团和 Ant Design 开源社区

何时使用

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

代码演示

Please select
基本

最简单的用法。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Please select
从数据直接生成

使用 treeData 把 JSON 数据直接生成树结构。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Please select
异步加载

异步加载树节点。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code


Please select
弹出位置

可以通过 placement 手动指定弹出的位置。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Error
 
Warning multiple
自定义状态

使用 status 为 TreeSelect 添加状态,可选 error 或者 warning。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Please select


Prefix
Please select
前后缀

自定义前缀 prefix 和后缀图标 suffixIcon。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.22.0
 
Please select
多选

多选的树选择。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Node1
 
可勾选

使用勾选框实现多选功能。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
线性样式

通过 treeLine 配置线性样式。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Please select
Please select
Please select
Please select
形态变体

TreeSelect 形态变体,可选 outlined filled borderless underlined 四种形态。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.13.0
Child 1-1
 
1 / 3
最大选中数量

你可以通过设置 maxCount 约束最多可选中的数量,当超出限制时会变成禁止选中状态。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.23.0

API

通用属性参考:通用属性

Tree props

参数说明类型默认值版本
allowClear自定义清除按钮boolean | { clearIcon?: ReactNode }false5.8.0: 支持对象形式
autoClearSearchValue当多选模式下值被选择,自动清空搜索框booleantrue
classNames语义化结构 classRecord<SemanticDOM, string>-5.25.0
defaultOpen是否默认展开下拉菜单boolean-
defaultValue指定默认选中的条目string | string[]-
disabled是否禁用booleanfalse
popupClassName下拉菜单的 className 属性,使用 classNames.popup.root 替换string-4.23.0
popupMatchSelectWidth下拉菜单和选择器同宽。默认将设置 min-width,当值小于选择框宽度时会被忽略。false 时会关闭虚拟滚动boolean | numbertrue5.5.0
dropdownRender自定义下拉框内容,使用 popupRender 替换(originNode: ReactNode, props) => ReactNode-
popupRender自定义下拉框内容(originNode: ReactNode, props) => ReactNode-
dropdownStyle下拉菜单的样式,使用 styles.popup.root 替换object-
fieldNames自定义节点 label、value、children 的字段object{ label: label, value: value, children: children }4.17.0
filterTreeNode是否根据输入项进行筛选,默认用 treeNodeFilterProp 的值作为要筛选的 TreeNode 的属性值boolean | function(inputValue: string, treeNode: TreeNode) (函数需要返回 bool 值)function
getPopupContainer菜单渲染父节点。默认渲染到 body 上,如果你遇到菜单滚动定位问题,试试修改为滚动的区域,并相对其定位。示例function(triggerNode)() => document.body
labelInValue是否把每个选项的 label 包装到 value 中,会把 value 类型从 string 变为 {value: string, label: ReactNode, halfChecked(treeCheckStrictly 时有效): string[] } 的格式booleanfalse
listHeight设置弹窗滚动高度number256
loadData异步加载数据。在过滤时不会调用以防止网络堵塞,可参考 FAQ 获得更多内容function(node)-
maxCount指定可选中的最多 items 数量,仅在 multiple=true 时生效。如果此时 (showCheckedStrategy = 'SHOW_ALL' 且未开启 treeCheckStrictly),或使用 showCheckedStrategy = 'SHOW_PARENT',则maxCount无效。number-5.23.0
maxTagCount最多显示多少个 tag,响应式模式会对性能产生损耗number | responsive-responsive: 4.10
maxTagPlaceholder隐藏 tag 时显示的内容ReactNode | function(omittedValues)-
maxTagTextLength最大显示的 tag 文本长度number-
multiple支持多选(当设置 treeCheckable 时自动变为 true)booleanfalse
notFoundContent当下拉列表为空时显示的内容ReactNodeNot Found
open是否展开下拉菜单boolean-
placeholder选择框默认文字string-
placement选择框弹出的位置bottomLeft bottomRight topLeft topRightbottomLeft
prefix自定义前缀ReactNode-5.22.0
searchValue搜索框的值,可以通过 onSearch 获取用户输入string-
showCheckedStrategy配置 treeCheckable 时,定义选中项回填的方式。TreeSelect.SHOW_ALL: 显示所有选中节点(包括父节点)。TreeSelect.SHOW_PARENT: 只显示父节点(当父节点下所有子节点都选中时)。 默认只显示子节点TreeSelect.SHOW_ALL | TreeSelect.SHOW_PARENT | TreeSelect.SHOW_CHILDTreeSelect.SHOW_CHILD
showSearch是否支持搜索框boolean单选:false | 多选:true
size选择框大小large | middle | small-
status设置校验状态'error' | 'warning'-4.19.0
suffixIcon自定义的选择框后缀图标ReactNode<DownOutlined />
switcherIcon自定义树节点的展开/折叠图标ReactNode | ((props: AntTreeNodeProps) => ReactNode)-renderProps: 4.20.0
styles语义化结构 styleRecord<SemanticDOM, CSSProperties>-5.25.0
tagRender自定义 tag 内容,多选时生效(props) => ReactNode-
treeCheckable显示 Checkboxbooleanfalse
treeCheckStrictlycheckable 状态下节点选择完全受控(父子节点选中状态不再关联),会使得 labelInValue 强制为 truebooleanfalse
treeDatatreeNodes 数据,如果设置则不需要手动构造 TreeNode 节点(value 在整个树范围内唯一)array<{value, title, children, [disabled, disableCheckbox, selectable, checkable]}>[]
treeDataSimpleMode使用简单格式的 treeData,具体设置参考可设置的类型 (此时 treeData 应变为这样的数据结构: [{id:1, pId:0, value:'1', title:"test1",...},...], pId 是父节点的 id)boolean | object<{ id: string, pId: string, rootPId: string }>false
treeTitleRender自定义渲染节点(nodeData) => ReactNode-5.12.0
treeDefaultExpandAll默认展开所有树节点booleanfalse
treeDefaultExpandedKeys默认展开的树节点string[]-
treeExpandAction点击节点 title 时的展开逻辑,可选:false | click | doubleClickstring | booleanfalse4.21.0
treeExpandedKeys设置展开的树节点string[]-
treeIcon是否展示 TreeNode title 前的图标,没有默认样式,如设置为 true,需要自行定义图标相关样式booleanfalse
treeLine是否展示线条样式,请参考 Tree - showLineboolean | objectfalse4.17.0
treeLoadedKeys(受控)已经加载的节点,需要配合 loadData 使用string[][]
treeNodeFilterProp输入项过滤对应的 treeNode 属性stringvalue
treeNodeLabelProp作为显示的 prop 设置stringtitle
value指定当前选中的条目string | string[]-
variant形态变体outlined | borderless | filled | underlinedoutlined5.13.0 | underlined: 5.24.0
virtual设置 false 时关闭虚拟滚动booleantrue4.1.0
onChange选中树节点时调用此函数function(value, label, extra)-
onDropdownVisibleChange展开下拉菜单的回调,使用 onOpenChange 替换(open: boolean) => void-
onOpenChange展开下拉菜单的回调(open: boolean) => void-
onSearch文本框值变化时的回调function(value: string)-
onSelect被选中时调用function(value, node, extra)-
onTreeExpand展示节点时调用function(expandedKeys)-
onPopupScroll下拉列表滚动时的回调(event: UIEvent) => void-5.17.0

Tree 方法

名称描述版本
blur()移除焦点
focus()获取焦点

TreeNode props

建议使用 treeData 来代替 TreeNode,免去手动构造的麻烦

参数说明类型默认值版本
checkable当树为 Checkbox 时,设置独立节点是否展示 Checkboxboolean-
disableCheckbox禁掉 Checkboxbooleanfalse
disabled是否禁用booleanfalse
isLeaf是否是叶子节点booleanfalse
key此项必须设置(其值在整个树范围内唯一)string-
selectable是否可选booleantrue
title树节点显示的内容ReactNode---
value默认根据此属性值进行筛选(其值在整个树范围内唯一)string-

Semantic DOM

Please select
  • root
    5.25.0
    根元素
  • popup.root
    5.25.0
    弹出菜单元素

主题变量(Design Token)

组件 Token如何定制?
Token 名称描述类型默认值
indentSize缩进宽度number24
nodeHoverBg节点悬浮态背景色stringrgba(0,0,0,0.04)
nodeHoverColor节点悬浮态态文字颜色stringrgba(0,0,0,0.88)
nodeSelectedBg节点选中态背景色string#e6f4ff
nodeSelectedColor节点选中态文字颜色stringrgba(0,0,0,0.88)
titleHeight节点标题高度number24
全局 Token如何定制?

FAQ

onChange 时如何获得父节点信息?

从性能角度考虑,我们默认不透出父节点信息。你可以这样获得:https://codesandbox.io/s/get-parent-node-in-onchange-eb1608

自定义 Option 样式导致滚动异常怎么办?

请参考 Select 的 FAQ。

为何在搜索时 loadData 不会触发展开?

在 v4 alpha 版本中,默认在搜索时亦会进行搜索。但是经反馈,在输入时会快速阻塞网络。因而改为搜索不触发 loadData。但是你仍然可以通过 filterTreeNode 处理异步加载逻辑:

tsx
<TreeSelect
filterTreeNode={(input, treeNode) => {
const match = YOUR_LOGIC_HERE;
if (match && !treeNode.isLeaf && !treeNode.children) {
// Do some loading logic
}
return match;
}}
/>

为何弹出框不能横向滚动?

关闭虚拟滚动即可,因为开启虚拟滚动时无法准确的测量完整列表的 scrollWidth。