TreeSelect 树选择
何时使用
类似 Select 的选择控件，可选择的数据结构是一个树形结构时，可以使用 TreeSelect，例如公司层级、学科系统、分类目录等等。
代码演示
基本
loading
多选
loading
可勾选
loading
异步加载
loading
线性样式
loading
弹出位置
loading
形态变体
loading
自定义状态
loading
最大选中数量
loading
前后缀
loading
API
Tree props
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| allowClear | 自定义清除按钮 | boolean | { clearIcon?: ReactNode } | false | 5.8.0: 支持对象形式 |
| classNames | 语义化结构 class | Record<SemanticDOM, string> | - | 5.25.0 |
| disabled | 是否禁用 | boolean | false | |
| popupMatchSelectWidth | 下拉菜单和选择器同宽。默认将设置 min-width，当值小于选择框宽度时会被忽略。false 时会关闭虚拟滚动 | boolean | number | true | 5.5.0 |
| fieldNames | 自定义节点 label、value、children 的字段 | object | { label: label, value: value, children: children } | 4.17.0 |
| getPopupContainer | 菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。示例 | function(triggerNode) | () => document.body | |
| labelInValue | 是否把每个选项的 label 包装到 value 中，会把 value 类型从 string 变为 {value: string, label: ReactNode, halfChecked: boolean(选项列表是否为半选状态，并且不会展示到值中) } 的格式 | boolean | false | |
| listHeight | 设置弹窗滚动高度 | number | 256 | |
| 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） | boolean | false | |
| notFoundContent | 当下拉列表为空时显示的内容 | ReactNode | Not Found | |
| open | 是否展开下拉菜单 | boolean | - | |
| placeholder | 选择框默认文字 | string | - | |
| placement | 选择框弹出的位置 | bottomLeft bottomRight topLeft topRight | bottomLeft | |
| prefix | 自定义前缀 | ReactNode | - | 5.22.0 |
| showCheckedStrategy | 配置 treeCheckable 时，定义选中项回填的方式。TreeSelect.SHOW_ALL: 显示所有选中节点(包括父节点)。TreeSelect.SHOW_PARENT: 只显示父节点(当父节点下所有子节点都选中时)。 默认只显示子节点 | TreeSelect.SHOW_ALL | TreeSelect.SHOW_PARENT | TreeSelect.SHOW_CHILD | TreeSelect.SHOW_CHILD | |
| showSearch | 是否支持搜索框 | boolean | Object | 单选：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 | 语义化结构 style | Record<SemanticDOM, CSSProperties> | - | 5.25.0 |
| tagRender | 自定义 tag 内容，多选时生效 | (props) => ReactNode | - | |
| treeCheckable | 显示 Checkbox | boolean | false | |
| treeCheckStrictly | checkable 状态下节点选择完全受控（父子节点选中状态不再关联），会使得 labelInValue 强制为 true | boolean | false | |
| treeData | treeNodes 数据，如果设置则不需要手动构造 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 | 默认展开所有树节点 | boolean | false | |
| treeDefaultExpandedKeys | 默认展开的树节点 | string[] | - | |
| treeExpandAction | 点击节点 title 时的展开逻辑，可选：false | click | doubleClick | string | boolean | false | 4.21.0 |
| treeExpandedKeys | 设置展开的树节点 | string[] | - | |
| treeIcon | 是否展示 TreeNode title 前的图标，没有默认样式，如设置为 true，需要自行定义图标相关样式 | boolean | false | |
| treeLine | 是否展示线条样式，请参考 [Tree - showLine] | boolean | object | false | 4.17.0 |
| treeLoadedKeys | （受控）已经加载的节点，需要配合 loadData 使用 | string[] | [] | |
| treeNodeLabelProp | 作为显示的 prop 设置 | string | title | |
| value(v-model) | 指定当前选中的条目 | string | string[] | - | |
| variant | 形态变体 | outlined | borderless | filled | underlined | outlined | 5.13.0 | underlined: 5.24.0 |
| virtual | 设置 false 时关闭虚拟滚动 | boolean | true | 4.1.0 |
| onChange | 选中树节点时调用此函数 | function(value, label, extra) | - | |
| onOpenChange | 展开下拉菜单的回调 | (open: boolean) => void | - | |
| onSelect | 被选中时调用 | function(value, node, extra) | - | |
| onTreeExpand | 展示节点时调用 | function(expandedKeys) | - | |
| onPopupScroll | 下拉列表滚动时的回调 | (event: UIEvent) => void | - | 5.17.0 |
showSearch
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| autoClearSearchValue | 当多选模式下值被选择，自动清空搜索框 | boolean | true | |
| filterTreeNode | 是否根据输入项进行筛选，默认用 treeNodeFilterProp 的值作为要筛选的 TreeNode 的属性值 | boolean | function(inputValue: string, treeNode: TreeNode) (函数需要返回 bool 值) | function | |
| searchValue | 搜索框的值，可以通过 onSearch 获取用户输入 | string | - | |
| treeNodeFilterProp | 输入项过滤对应的 treeNode 属性 | string | value | |
| onSearch | 文本框值变化时的回调 | function(value: string) | - |
Tree 方法
| 名称 | 描述 | 版本 |
|---|---|---|
| blur() | 移除焦点 | |
| focus() | 获取焦点 |
TreeNode props
建议使用 treeData 来代替 TreeNode，免去手动构造的麻烦
| 参数 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| checkable | 当树为 Checkbox 时，设置独立节点是否展示 Checkbox | boolean | - | |
| disableCheckbox | 禁掉 Checkbox | boolean | false | |
| disabled | 是否禁用 | boolean | false | |
| isLeaf | 是否是叶子节点 | boolean | false | |
| key | 此项必须设置（其值在整个树范围内唯一） | string | - | |
| selectable | 是否可选 | boolean | true | |
| title | 树节点显示的内容 | ReactNode | --- | |
| value | 默认根据此属性值进行筛选（其值在整个树范围内唯一） | string | - |