更新记录

1.0.1（2026-04-26） 下载此版本

预览图片

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

[1.0.0] - 2026-04-26

平台兼容性

uni-app(4.0)

uni-app x(4.44)

xq-tree 树形控件

基于 uni-app 的高性能树形控件，支持手风琴模式、多选/单选、父子联动、严格模式、自定义节点插槽、交错展开折叠动画及固定宽高滚动，完美兼容微信小程序、H5 及 App。

✨ 核心特性

• ✅ 手风琴模式：同级节点自动折叠，保持界面整洁
• ✅ 多选支持：复选框半选/全选状态，父子联动或严格模式自由切换
• ✅ 单选模式：multiple 为 false 时仅允许选中一个节点
• ✅ 自定义节点内容：通过插槽完全控制节点渲染，包括展开图标
• ✅ 交错动画：展开/折叠时子节点有平滑的下落/收起动画，无空白闪烁
• ✅ 固定宽高滚动：通过 height/width 属性限制容器，溢出自动出现滚动条
• ✅ 灵活字段映射：自定义 nodeKey、labelKey、childrenKey 等字段名
• ✅ 丰富的方法：全选、清空、指定节点选中、获取选中节点等
• ✅ 深层递归操作：expandAll 等方法支持递归展开整棵树

📦 安装与引入

将组件文件夹放入 uni_modules/xq-tree/ 或 components/ 目录，即可通过 easycom 自动引入，无需手动 import。

🚀 快速上手

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

const treeData = ref([
  {
    id: 1,
    name: '一级 1',
    children: [
      { id: 2, name: '二级 1-1' },
      { id: 3, name: '二级 1-2' }
    ]
  }
])

function handleCheck(node, checkedState) {
  console.log('当前节点：', node)
  console.log('选中状态：', checkedState)
}
</script>

<template>
  <xq-tree
    :data="treeData"
    node-key="id"
    label-key="name"
    show-checkbox
    default-expand-all
    @check="handleCheck"
  />
</template>

⚙️ Props

📤 Events

🧩 Slots

ℹ️ 微信小程序中，由于性能问题，node 插槽需手动设置 labelSlot 为 true 才会启用，否则默认渲染纯文本。

🛠️ 方法 (通过 ref 调用)

🎨 动画说明

组件内置了基于 CSS 关键帧的进入/离开动画，通过 TransitionGroup 实现：

• 展开动画：子节点从上方逐渐撑开并淡入，同级子节点有 0.03s 的错开延迟
• 折叠动画：节点向上收起并淡出，动画完成后自动移除

可通过覆盖 .tree-node-enter-active、.tree-node-leave-active 及 @keyframes treeExpandIn、treeCollapseOut 样式来调整动画时长或效果。

📄 License

MIT

文档版本：v1.0.0 最后更新：2026-04-26