更新记录

1.0.0（2026-04-28） 下载此版本

更新日志

[1.0.0] - 2026-04-28

平台兼容性

uni-app(4.11)

xq-tree-select 树形选择器组件文档

组件概述

xq-tree-select 是一个基于 uni-app 的树形下拉选择器，内部封装了树组件，支持单选与多选、可搜索过滤、自定义节点渲染、底部确认/取消按钮以及多选标签展示等功能。已适配 H5、微信小程序、App 等多种平台。

引入方式

在页面或组件中通过 import 引入并注册即可使用。

<script setup>
import XqTreeSelect from '@/uni_modules/xq-tree-select/components/xq-tree-select/xq-tree-select.vue'
</script>

<template>
  <XqTreeSelect v-model="selectedValue" :data="treeData" />
</template>

基础用法

单选模式

<script setup>
import { ref } from 'vue'

const selectedId = ref('')
const treeData = ref([
  {
    id: '1',
    name: '一级节点',
    children: [
      { id: '1-1', name: '二级节点' }
    ]
  }
])
</script>

<template>
  <xq-tree-select
    v-model="selectedId"
    :data="treeData"
    node-key="id"
    label-key="name"
    placeholder="请选择部门"
  />
</template>

多选模式（带底部确认按钮）

<template>
  <xq-tree-select
    v-model="checkedKeys"
    :data="treeData"
    multiple
    show-footer
    confirm-text="确认选择"
    cancel-text="取消"
    :tag-limit="3"
  />
</template>

<script setup>
import { ref } from 'vue'
const checkedKeys = ref([])
const treeData = ref([...])
</script>

可搜索模式

<template>
  <xq-tree-select
    v-model="selectedId"
    :data="treeData"
    filterable
    filter-placeholder="输入关键字搜索"
  />
</template>

自定义节点内容

通过 show-custom-node 开启自定义节点插槽，使用具名插槽 #node 接收节点数据。

<template>
  <xq-tree-select
    v-model="selectedId"
    :data="treeData"
    show-custom-node
  >
    <template #node="{ node, level, expanded }">
      <view style="display: flex; align-items: center;">
        <text>{{ node.label }}</text>
        <text style="color: #999;">
          (层级：{{ level }})
        </text>
      </view>
    </template>
  </xq-tree-select>
</template>

Props

Events

Slots

注意事项

1. 数据格式：data 中的每一项必须包含 nodeKey 和 labelKey 指定的字段，子节点通过 childrenKey 指定。
2. 多选绑定：多选模式下 modelValue 必须是数组类型，否则无法正常显示标签。
3. 搜索过滤：filterMethod 为自定义过滤函数，若不传则使用组件内置的标签匹配过滤（递归匹配 label）。
4. 底部按钮逻辑：当 showFooter 为 true 时，只有点击“确定”按钮才会更新绑定值；点击“取消”或蒙层会恢复到弹窗打开前的选中状态。若为 false，则选中操作立即生效。
5. 自适应弹出方向：placement="auto" 时，组件会根据触发元素距离屏幕底部和顶部的距离自动选择向上或向下弹出。
6. 严格模式：checkStrictly 为 true 时，父节点与子节点的选中状态互不影响；否则勾选父节点会同时勾选全部后代。
7. 自定义节点：使用 showCustomNode 时，必须显式设置该属性为 true，插槽内容才会渲染。插槽作用域中 node.label 已被映射为对应 labelKey 字段的值。
8. 小程序样式：请勿在组件内添加小程序不支持的 CSS 选择器或属性；若需全局设置盒模型，请在 App.vue 中按上述条件编译方式处理。

完整示例

<script setup>
import { ref } from 'vue'
import XqTreeSelect from '@/uni_modules/xq-tree-select/components/xq-tree-select/xq-tree-select.vue'

const selected = ref([])
const treeData = ref([
  {
    menuId: '1',
    menuName: '系统管理',
    children: [
      { menuId: '1-1', menuName: '用户管理' },
      { menuId: '1-2', menuName: '角色管理' }
    ]
  }
])

function handleChange(val) {
  console.log('选中值变化：', val)
}
</script>

<template>
  <view class="page">
    <xq-tree-select
      v-model="selected"
      :data="treeData"
      node-key="menuId"
      label-key="menuName"
      multiple
      filterable
      show-footer
      show-custom-node
      @change="handleChange"
    >
      <template #node="{ node }">
        <view style="display: flex; align-items: center;">
          <text>{{ node.label }}</text>
        </view>
      </template>
    </xq-tree-select>
  </view>
</template>