跳到主要内容

TreeSelect 树选择 ​

uni-appH5微信小程序App

uni-app 跨端树选择器。触发器 + 遮罩下拉面板(参考 Dropdown),面板内以拍平缩进列表渲染树(scroll-view 滚动),支持单选 / multiple 多选级联勾选、clearable 清空、collapseTags 标签折叠。相对 Web 版的适配:无 Teleport/hover,clearable 有值时常显清空按钮;复选框为自定义 view(✓/− 文本标记),保证小程序/App 端样式一致;单选仅可选中叶子节点,点击父级切换展开;展开态由组件记忆,关闭重开不丢失。

何时使用 ​

选项本身是层级结构且需要选中叶子节点时:组织汇报关系、费用归属部门、多级分类。

何时不使用 ​

扁平选项用 Select(picker 原生体验更好);需要选中一条完整的根到叶子路径(如省市区)时用 Cascader;只展示层级、不需要选择时用 Tree。

本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。

9:41
TreeSelect 树选择 · uni-app H5 实时运行 新窗口打开

Props ​

名称类型默认值说明
modelValuestring | number | Array<string | number> | nullnull绑定值(单选为叶子节点 value,multiple 多选为叶子 value 数组),配合 v-model 使用
optionsArray<TreeSelectOption>[]嵌套选项:{ label: string; value: string | number; children?: 同构; disabled?: boolean }
placeholderstring"请选择"未选中时的占位文本
disabledbooleanfalse禁用
clearablebooleanfalse可清空;移动端无 hover,有值时常显清空按钮
multiplebooleanfalse多选模式:复选框级联勾选,勾选父级勾选全部可用子孙(部分选中时父级半选);面板不关闭,触发器以标签展示选中叶子
collapseTagsbooleanfalse多选时折叠标签:只显示首个标签与 +N 计数
checkablebooleantrue多选时显示复选框;false 时点击叶子节点行切换选中。单选始终为纯点击选中
defaultExpandedKeysArray<string | number>[]首次挂载时展开的节点 key 列表;树的展开态由组件记忆,关闭重开不丢失

Events ​

名称载荷说明
update:modelValuestring | number | Array<string | number> | null选中节点/勾选变化/清空时触发,用于 v-model
changestring | number | Array<string | number> | null值变化时触发(选中节点、勾选变化或清空)
clearvoid点击清空按钮时触发

示例 ​

单选 ​

vue
<TreeSelect v-model="value1" :options="deptTree" placeholder="选择团队" />

多选勾选 ​

vue
<TreeSelect v-model="s" :options="deptTree" multiple placeholder="选择多个团队" />

默认展开 ​

vue
<TreeSelect v-model="value2" :options="deptTree" :default-expanded-keys="['rd']" placeholder="选择团队" />