树选择 TreeSelect

基本用法

最简单的用法。

复选框多选

可以通过设置 treeCheckable 属性开启复选框勾选。

定制回填方式

可以通过treeCheckStrategy属性定制回填方式。

双向绑定

选中值支持双向绑定。

下拉框的页头和页脚

自定义树选择下拉框的页头和页脚

回退选项

使用 fallback-option 自定义找不到选项的值的显示效果，默认找不到选项就展示值本身。用户可以将其设定为 false 来隐藏那些没有匹配到节点数据的值。

自定义 TreeData 的字段名称

通过 fieldNames 字段可以自定义 TreeData 的字段名。

设置 value 格式

labelInValue 为 true 时，value 格式为： { label: string, value: string }。

动态加载

可以通过 loadMore 进行动态加载。此时可设置 isLeaf 来标示叶子节点。

多选

控制下拉框的展开收起

通过 popupVisible (支持 v-model) 控制下拉框的展开和收起。

远程搜索

监听 search 事件，在事件处理函数中获取数据并更新 treeData。自定义搜索逻辑时，建议关闭内部过滤逻辑（:disable-filter="true"），以免影响自定义结果。

搜索

设置 :allow-search="true" 启用搜索功能。动态加载时候只能在已加载数据中进行搜索。默认的关键字搜索是从value字段匹配。也可以传入 filterTreeNode自定义过滤方式。

不同尺寸

设置 size 可以使用四种尺寸（small, default, large, huge）的选择器。高度分别对应 24px、28px、32px、36px。

自定义触发元素

自定义触发元素。

虚拟列表

当前示例会同时展示三种常见写法：直接传空对象使用默认固定高度、显式传 itemSize 固定模式、显式传 minItemSize 动态模式。这样可以直接验证 TreeSelect 现在已经支持顶层 virtual-list-props，而不需要再通过旧的内部透传路径开启虚拟列表。

通过指定 virtual-list-props 来开启虚拟列表，在大量数据时获得高性能表现。TreeSelect 内部树节点默认按尺寸走固定高度模式：mini / small / medium / large 分别对应 24 / 28 / 32 / 36。如果你没有显式传 itemSize 或 minItemSize，组件会按内部 Tree size 自动补齐固定高度；如果你需要动态树节点高度或虚拟模式下的展开动画，请显式改传 minItemSize。完整参数与迁移映射见虚拟列表迁移指南。

从 Arco Design 迁移

TreeSelect 在命名和大部分基础交互上和 Arco Design Vue 更接近，但实际实现已经切换到当前组件库内部的 Tree、Trigger、SelectView、表单与主题链路。迁移时通常可以先平移 API，再按需适配当前组件库的树节点插槽和弹层行为。

对应关系

Arco Design Vue	SD Design Vue	说明
`a-tree-select`	`sd-tree-select`	树选择器主体
`data`	`data`	树数据主属性保持一致
`v-model` / `model-value`	`v-model` / `model-value`	受控写法保持一致
`field-names`	`field-names`	字段映射保持一致
`multiple`	`multiple`	多选模式写法保持一致
`tree-checkable`	`tree-checkable`	复选框模式写法保持一致
`tree-checked-strategy`	`tree-checked-strategy`	回填策略写法保持一致
`load-more`	`load-more`	动态加载写法保持一致
`popup-visible`	`popup-visible`	弹层显隐控制保持一致
`#label` / `#tag` / `#header` / `#footer`	同名插槽	选择框与下拉层插槽基本可直接迁移

主要差异

当前实现的树面板完全复用本地 Tree 组件，因此节点内容定制更偏向 Tree 子插槽写法，像标题和额外内容应优先使用 tree-slot-title、tree-slot-extra，不要继续依赖旧版内部节点 DOM 结构。
弹层容器、局部主题和表单联动都走当前组件库内部链路。历史上如果通过外层容器 hack 修过滚动定位或局部主题，迁移后应优先改成 popup-container、trigger-props 和 ConfigProvider。
复选框模式、多选模式和路径展示的组合行为以当前组件库实现为准，特别是 tree-checkable、show-path、separator 一起使用时，建议重新验收回填文本和删除标签行为。
树节点渲染的公开扩展方式统一收敛到插槽，没有额外对外暴露函数式 render API；自定义节点 UI 时优先走模板插槽。

迁移前后示例

基础替换

<template>
  <a-tree-select v-model="value" :data="treeData" placeholder="Please select ..." />
</template>

<template>
  <sd-tree-select v-model="value" :data="treeData" placeholder="Please select ..." />
</template>

复选框多选

<template>
  <a-tree-select v-model="value" :data="treeData" tree-checkable tree-checked-strategy="child" />
</template>

<template>
  <sd-tree-select v-model="value" :data="treeData" tree-checkable tree-checked-strategy="child" />
</template>

节点标题定制

<template>
  <sd-tree-select v-model="value" :data="treeData">
    <template #tree-slot-title="{ title }">
      <strong>{{ title }}</strong>
    </template>
  </sd-tree-select>
</template>

建议的迁移顺序

先直接替换组件标签并保留原有 data、field-names、multiple、tree-checkable 等写法，优先让页面恢复渲染。
再检查树节点定制：如果历史代码依赖旧版节点 DOM 或内部 class，改成 tree-slot-title、tree-slot-extra 这类公开插槽。
接着回归弹层与主题：重点检查滚动容器、局部主题、表单校验、动态加载和复选框勾选链路。
最后确认组合行为：特别是 tree-checkable、tree-check-strictly、show-path、load-more 和远程搜索一起出现的复杂场景。

从 Naive UI 迁移

TreeSelect 这次迁移以当前组件库的 Tree、Trigger、SelectView 和表单体系为基础，同时保留了 Naive UI 常用 props 的兼容别名，目标是让旧业务可以先平滑替换，再逐步回到本地优先的 API 命名。

对应关系

Naive UI	SD Design Vue	说明
`n-tree-select`	`sd-tree-select`	树选择器主体
`:options`	`:data` / `:options`	当前组件库主属性是 `data`，但保留 `options` 兼容别名
`v-model:value`	`v-model` / `v-model:value`	两种受控写法都支持
`filterable`	`allow-search` / `filterable`	本地推荐使用 `allow-search`
`clearable`	`allow-clear` / `clearable`	本地推荐使用 `allow-clear`
`checkable`	`tree-checkable` / `checkable`	本地推荐使用 `tree-checkable`
`check-strategy`	`tree-checked-strategy` / `checkStrategy`	本地推荐使用 `tree-checked-strategy`
`show` / `default-show`	`popup-visible` / `default-popup-visible`，同时兼容 `show` / `defaultShow`	显隐控制可逐步迁回本地命名
`render-tag`	`#tag`	对外渲染函数已移除，统一改用插槽
节点标题自定义	`tree-slot-title`	树节点内容通过 Tree 子插槽定制

主要差异

运行时行为以当前组件库为主，尤其是弹层挂载、局部主题、表单联动、树节点交互和滚动容器，已经统一接入本地 Trigger / Tree / ConfigProvider。迁移后不要继续依赖 Naive 的内部浮层层级或私有 DOM 结构。
当前版本保留了 options、value、show、filterable、clearable、checkable、checkStrategy 等兼容面，但新增代码建议直接使用本地命名：data、model-value、popup-visible、allow-search、allow-clear、tree-checkable、tree-checked-strategy。
对外 render function 已经全部移除。原来依赖 render-tag、自定义节点渲染函数的场景，要分别改成 tag、label、tree-slot-title、tree-slot-extra 等插槽。
tree-checkable 和多选展示已经接入当前组件库的本地勾选状态链路，勾选模式下的标签展示、回填策略和 show-path 都以当前实现为准。迁移含复选框的场景时，建议重点回归父子联动、严格模式和回填文本。

迁移前后示例

基础替换

<template>
  <n-tree-select
    v-model:value="value"
    :options="options"
    filterable
    clearable
    placeholder="Please select ..."
  />
</template>

<template>
  <sd-tree-select
    v-model="value"
    :data="options"
    allow-search
    allow-clear
    placeholder="Please select ..."
  />
</template>

复选框模式

<template>
  <n-tree-select v-model:value="value" :options="options" checkable :check-strategy="'child'" />
</template>

<template>
  <sd-tree-select v-model="value" :data="options" tree-checkable tree-checked-strategy="child" />
</template>

`render-tag` 迁移到插槽

<template>
  <n-tree-select v-model:value="value" :options="options" multiple :render-tag="renderTag" />
</template>

<template>
  <sd-tree-select v-model="value" :data="options" multiple>
    <template #tag="{ data }">
      <span>{{ data?.title ?? data?.label }}</span>
    </template>
  </sd-tree-select>
</template>

节点标题定制

<template>
  <sd-tree-select v-model="value" :data="options">
    <template #tree-slot-title="{ title }">
      <strong>{{ title }}</strong>
    </template>
  </sd-tree-select>
</template>

建议的迁移顺序

先替换组件本体并让页面跑起来：n-tree-select 改成 sd-tree-select，原有 options、value、filterable、clearable、checkable 可以先靠兼容别名维持行为。
再统一属性命名：把 options 迁到 data，把 filterable / clearable / checkable / check-strategy 逐步改成 allow-search / allow-clear / tree-checkable / tree-checked-strategy，避免新旧命名长期混用。
接着迁移自定义渲染：删除 render-tag 等函数式入口，改用 label、tag、tree-slot-title、tree-slot-extra 等模板插槽。
最后逐项验收交互：重点检查勾选模式、tree-check-strictly、show-path、远程搜索、虚拟列表、回退选项和弹层显隐控制，确认它们已经符合当前组件库的本地行为。

API

`<tree-select>` Props

参数名	描述	类型	默认值	版本
disabled	是否禁用	`boolean`	`false`
loading	是否为加载中状态	`boolean`	`false`
error	是否为错误状态	`boolean`	`false`
size	选择框的大小	`'mini' \| 'small' \| 'medium' \| 'large'`	`'medium'`
border	是否显示边框	`boolean`	`true`
allow-search	是否允许搜索，兼容 `filterable` 别名	`boolean \| { retainInputValue?: boolean }`	`false (single) \| true (multiple)`
filterable	`allow-search` 的兼容别名	`boolean`	`-`
allow-clear	是否允许清除，兼容 `clearable` 别名	`boolean`	`false`
clearable	`allow-clear` 的兼容别名	`boolean`	`-`
placeholder	提示文案	`string`	`-`
max-tag-count	最多显示的标签数量，仅在多选模式有效，支持响应式折叠	`number \| 'responsive'`	`-`
multiple	是否支持多选	`boolean`	`false`
default-value	默认值	`string \| number \| Array<string \| number> \| LabelValue \| LabelValue[]`	`-`
model-value (v-model)	绑定值	`string \| number \| Array<string \| number> \| LabelValue \| LabelValue[]`	`-`
value (v-model:value)	`model-value` 的兼容别名	`string \| number \| Array<string \| number> \| LabelValue \| LabelValue[]`	`-`
field-names	指定节点数据中的字段名	`TreeFieldNames`	`-`
data	数据，兼容 `options` 别名	`TreeNodeData[]`	`[]`
options	`data` 的兼容别名	`TreeNodeData[]`	`-`
label-in-value	设置value格式。默认是string，设置为true时候，value格式为： { label: string, value: string }	`boolean`	`false`
tree-checkable	是否展示复选框，兼容 `checkable` 别名	`boolean`	`false`
checkable	`tree-checkable` 的兼容别名	`boolean`	`-`
tree-check-strictly	父子节点是否关联	`boolean`	`false`
tree-checked-strategy	定制回显方式，兼容 `checkStrategy` 别名	`'all' \| 'parent' \| 'child'`	`'all'`
checkStrategy	`tree-checked-strategy` 的兼容别名	`'all' \| 'parent' \| 'child'`	`-`
show-path	单选时展示从根节点到当前节点的完整路径	`boolean`	`false`
separator	`show-path` 开启时的路径分隔符	`string`	`' / '`
tree-props	可以接受所有 Tree 组件的Props	`Partial<TreeProps>`	`-`
trigger-props	可以接受所有 Trigger 组件的Props	`Partial<TriggerProps>`	`-`
virtual-scroll	Naive 兼容开关。设为 `false` 时会关闭通过 `virtual-list-props` 或 `treeProps.virtualListProps` 注入的虚拟列表配置	`boolean`	`-`
popup-visible (v-model)	弹出框是否可见	`boolean`	`-`
default-popup-visible	默认弹出框是否可见	`boolean`	`false`
dropdown-style	下拉框样式	`CSSProperties`	`-`
dropdown-class-name	下拉框样式 class	`string \| string[]`	`-`
filter-tree-node	自定义节点过滤函数	`(searchKey: string, nodeData: TreeNodeData) => boolean`	`-`
load-more	动态加载数据	`(nodeData: TreeNodeData) => Promise<void>`	`-`
disable-filter	禁用内部过滤逻辑	`boolean`	`false`
popup-container	弹出框的挂载容器	`string \| HTMLElement`	`-`
fallback-option	为 value 中找不到匹配项的 key 定义节点数据	`boolean \| ((key: number \| string) => TreeNodeData \| boolean)`	`true`	2.22.0
selectable	设置可选择的节点，默认全部可选	`boolean\| 'leaf'\| (( node: TreeNodeData, info: { isLeaf: boolean; level: number } ) => boolean)`	`true`	2.27.0
scrollbar	是否开启虚拟滚动条	`boolean \| ScrollbarProps`	`true`	2.39.0
show-header-on-empty	空状态时是否显示header	`boolean`	`false`
show-footer-on-empty	空状态时是否显示footer	`boolean`	`false`
input-value (v-model)	输入框的值	`string`	`-`	2.55.0
default-input-value	输入框的默认值（非受控模式）	`string`	`''`	2.55.0

`<tree-select>` Events

事件名	描述	参数	版本
change	值改变时触发	value: `string \| number \| LabelValue \| Array<string \| number> \| LabelValue[] \| undefined`
popup-visible-change	下拉框显示状态改变时触发	visible: `boolean`
search	搜索值变化时触发	searchKey: `string`
clear	点击清除时触发	-
input-value-change	输入框的值发生改变时触发	inputValue: `string`	2.55.0

`<tree-select>` Slots

插槽名	描述	参数	版本
trigger	自定义触发元素	-
prefix	前缀	-
label	自定义选择框显示	data: `mixed`
tag	自定义多选标签显示	data: `TreeNodeData`
header	自定义下拉框页头	-
loader	定制加载中显示的内容	-
empty	定制空数据展示	-
footer	自定义下拉框页脚	-
tree-slot-extra	定制 tree 组件的渲染额外节点内容	-
tree-slot-title	定制 tree 组件的节点标题	title: `string`
tree-slot-icon	定制 tree 组件的节点图标	node: `TreeNodeData`	2.18.0
tree-slot-switcher-icon	定制 tree 组件的 switcher 图标	-

树选择 TreeSelect

基本用法

复选框多选

定制回填方式

双向绑定

下拉框的页头和页脚

回退选项

自定义 TreeData 的字段名称

设置 value 格式

动态加载

多选

控制下拉框的展开收起

远程搜索

搜索

不同尺寸

自定义触发元素

虚拟列表

从 Arco Design 迁移

对应关系

主要差异

迁移前后示例

基础替换

复选框多选

节点标题定制

建议的迁移顺序

从 Naive UI 迁移

对应关系

主要差异

迁移前后示例

基础替换

复选框模式

render-tag 迁移到插槽

节点标题定制

建议的迁移顺序

API

<tree-select> Props

<tree-select> Events

<tree-select> Slots

`render-tag` 迁移到插槽

`<tree-select>` Props

`<tree-select>` Events

`<tree-select>` Slots