更新记录

1.0.0（2026-10-12） 下载此版本

• 首个版本
• 弹出层内树形展示，支持多层级展开 / 收起
• 关键字模糊搜索，命中节点自动保留祖先链并展开
• 支持手风琴模式（同级只展开一个）
• 支持仅选择叶子节点
• 支持字段映射（label / children / disabled），适配任意数据结构
• 支持自定义回显文案（labelFormatter）与自定义校验（validator，支持 Promise）
• 支持一键清除、整体禁用、初始展开全部
• v-model 双向绑定，Vue2 / Vue3 双兼容

平台兼容性

uni-app(5.0)

uni-app x(5.0)

其他

Rui-selectSearchTree 可搜索树形选择器

通用的树形选择组件：输入框样式的选择框 + 底部弹出层内的树形列表，支持模糊搜索、展开收起，开箱即用。

组件不依赖任何业务接口或数据格式，通过 data 传入树形数据即可，用法与 element-plus 的 TreeSelect 类似。

功能特性

• 弹出层内树形展示，支持任意层级、展开 / 收起
• 关键字模糊搜索，命中节点的祖先链自动保留并展开
• 支持手风琴模式（同级节点每次只展开一个）
• 支持「仅选择叶子节点」模式
• 字段映射 props（label / children / disabled），适配任意数据结构
• 支持自定义回显文案 labelFormatter 与自定义校验 validator（支持 Promise）
• 支持一键清除、整体禁用、初始展开全部
• v-model 双向绑定，Vue2、Vue3 项目均可直接使用，无需适配
• 已选值在打开弹窗时自动展开祖先链并滚动定位

安装

在插件市场点击「使用 HBuilderX 导入插件」即可。依赖的 uni-easyinput、uni-popup、uni-icons 会由 HBuilderX 自动安装。

组件符合 easycom 规范，无需 import、无需注册，模板中直接使用。

数据格式

默认节点字段为 id / label / children / disabled：

const treeData = [
  {
    id: '1',
    label: '总部',
    children: [
      { id: '1-1', label: '研发中心' },
      { id: '1-2', label: '市场中心', children: [{ id: '1-2-1', label: '华东大区' }] }
    ]
  }
]

若你的字段名不同，通过 props 映射：

<Rui-selectSearchTree v-model="orgId" :data="treeData"
  nodeKey="orgId"
  :props="{ label: 'orgName', children: 'children', disabled: 'isDisabled' }" />

快速上手

<!-- 最简用法 -->
<Rui-selectSearchTree v-model="form.orgId" :data="treeData" />

<!-- 手风琴模式 + 初始展开全部 -->
<Rui-selectSearchTree v-model="form.orgId" :data="treeData" accordion expand-all />

<!-- 仅允许选择叶子节点 -->
<Rui-selectSearchTree v-model="form.orgId" :data="treeData" only-leaf />

<!-- 自定义标题、占位与搜索框占位 -->
<Rui-selectSearchTree v-model="form.orgId" :data="treeData"
  title="选择组织机构" placeholder="请选择组织机构" search-placeholder="输入机构名称筛选" />

<!-- 不可清除 + 禁用 -->
<Rui-selectSearchTree v-model="form.orgId" :data="treeData" :clearable="false" disabled />

<!-- 自定义回显：带上级路径 -->
<Rui-selectSearchTree v-model="form.orgId" :data="treeData" :label-formatter="formatLabel" />

自定义回显与校验

export default {
  methods: {
    // node：当前节点；path：祖先节点数组（从根到父级）
    formatLabel(node, path) {
      const prefix = path.map(n => n.label).join('/')
      return prefix ? `${prefix}/${node.label}` : node.label
    },
    // 返回 false 阻止确定；抛错也会阻止确定；支持返回 Promise
    async validate(node) {
      if (node.disabledFlag) {
        uni.showToast({ title: '该节点不可选', icon: 'none' })
        return false
      }
      return true
    }
  }
}

Props

Events

使用说明

• 选中值 v-model 存储的是节点的 nodeKey 字段值；change / confirm 事件会额外回传完整节点对象
• 搜索时会忽略手动展开状态，命中节点的祖先链自动展开；清空关键字后恢复手动展开状态
• 打开弹窗时会自动展开已选节点的祖先链并滚动定位到该节点
• onlyLeaf 为 true 时，父节点仅用于展开 / 收起，不可被选中
• 清除操作会触发 change，参数为 ('', null)

兼容性

• 支持：App（vue 页面）、H5、微信 / 支付宝 / 百度 / 字节跳动 / QQ 小程序
• 不支持：nvue 页面
• Vue2、Vue3 项目均支持