146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
# xq-tree 树形控件
|
||
|
||
基于 uni-app 的高性能树形控件，支持**手风琴模式**、**多选/单选**、**父子联动**、**严格模式**、**自定义节点插槽**、**交错展开折叠动画**及**固定宽高滚动**，完美兼容微信小程序、H5 及 App。
|
||
|
||
---
|
||
|
||
## ✨ 核心特性
|
||
|
||
- ✅ **手风琴模式**：同级节点自动折叠，保持界面整洁
|
||
- ✅ **多选支持**：复选框半选/全选状态，父子联动或严格模式自由切换
|
||
- ✅ **单选模式**：`multiple` 为 false 时仅允许选中一个节点
|
||
- ✅ **自定义节点内容**：通过插槽完全控制节点渲染，包括展开图标
|
||
- ✅ **交错动画**：展开/折叠时子节点有平滑的下落/收起动画，无空白闪烁
|
||
- ✅ **固定宽高滚动**：通过 `height`/`width` 属性限制容器，溢出自动出现滚动条
|
||
- ✅ **灵活字段映射**：自定义 `nodeKey`、`labelKey`、`childrenKey` 等字段名
|
||
- ✅ **丰富的方法**：全选、清空、指定节点选中、获取选中节点等
|
||
- ✅ **深层递归操作**：`expandAll` 等方法支持递归展开整棵树
|
||
|
||
---
|
||
|
||
## 📦 安装与引入
|
||
|
||
将组件文件夹放入 `uni_modules/xq-tree/` 或 `components/` 目录，即可通过 easycom 自动引入，无需手动 import。
|
||
|
||
---
|
||
|
||
## 🚀 快速上手
|
||
|
||
```vue
|
||
<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
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| data | Array | `[]` | 树形数据源 |
|
||
| nodeKey | String | `'id'` | 节点唯一标识字段 |
|
||
| labelKey | String | `'label'` | 节点显示文本字段 |
|
||
| childrenKey | String | `'children'` | 子节点字段名 |
|
||
| indent | Number | `20` | 每级缩进像素 |
|
||
| showCheckbox | Boolean | `false` | 是否显示复选框 |
|
||
| defaultExpandAll | Boolean | `false` | 是否默认展开所有节点 |
|
||
| defaultExpandedKeys | Array | `[]` | 默认展开的节点 key 数组 |
|
||
| defaultCheckedKeys | Array | `[]` | 默认勾选的节点 key 数组 |
|
||
| checkStrictly | Boolean | `true` | 是否严格模式（父子互不关联） |
|
||
| accordion | Boolean | `false` | 是否开启手风琴模式 |
|
||
| multiple | Boolean | `false` | 是否开启多选（false 时为单选模式）本期并未实现 |
|
||
| isDeepExpand | Boolean | `true` | 调用 expandAll 时是否递归展开所有子节点 |
|
||
| emptyText | String | `'暂无数据'` | 空数据时显示的文本 |
|
||
| checkedKey | String | `'_checked'` | 节点数据中存储勾选状态的字段名 |
|
||
| height | Number | `500` | 容器最小高度（rpx），溢出时垂直滚动 |
|
||
| width | Number | `300` | 容器最小宽度（rpx），溢出时水平滚动 |
|
||
| labelSlot | Boolean | `false` | 微信小程序是否启用自定义节点插槽 |
|
||
|
||
---
|
||
|
||
## 📤 Events
|
||
|
||
| 事件名 | 参数 | 说明 |
|
||
|--------|------|------|
|
||
| node-click | `(node)` | 节点被点击时触发 |
|
||
| node-expand | `(node)` | 节点展开时触发 |
|
||
| node-collapse | `(node)` | 节点折叠时触发 |
|
||
| check-change | `(node, checked)` | 复选框状态改变时触发 |
|
||
| check | `(node, { checkedKeys })` | 点击复选框后触发，返回当前所有选中 keys |
|
||
|
||
---
|
||
|
||
## 🧩 Slots
|
||
|
||
| 插槽名 | 作用域 | 说明 |
|
||
|--------|--------|------|
|
||
| node | `{ node, level, expanded, checked, indeterminate, isLeaf }` | 自定义节点内容（需设置 `labelSlot` 为 true 在微信小程序中启用） |
|
||
| icon | `{ node }` | 自定义展开/折叠图标（微信小程序不支持） |
|
||
|
||
> ℹ️ 微信小程序中，由于性能问题，`node` 插槽需手动设置 `labelSlot` 为 `true` 才会启用，否则默认渲染纯文本。
|
||
|
||
---
|
||
|
||
## 🛠️ 方法 (通过 ref 调用)
|
||
|
||
| 方法名 | 参数 | 说明 |
|
||
|--------|------|------|
|
||
| getCheckedKeys() | - | 返回当前所有勾选的节点 key 数组 |
|
||
| getCheckedNodes() | - | 返回当前所有勾选的节点原始数据数组 |
|
||
| setCheckedKeys(keys) | `keys: Array` | 设置当前勾选的节点 key 数组 |
|
||
| expandAll() | - | 展开所有节点（根据 `isDeepExpand` 决定是否递归） |
|
||
| collapseAll() | - | 折叠所有节点 |
|
||
| clearChecked() | - | 清空所有勾选 |
|
||
| setNodeChecked(keyOrNode, checked) | `keyOrNode`：节点的 key 或节点对象<br>`checked`：布尔值 | 设置指定节点的勾选状态 |
|
||
| checkAll() | - | 全选所有节点 |
|
||
|
||
---
|
||
|
||
## 🎨 动画说明
|
||
|
||
组件内置了基于 CSS 关键帧的进入/离开动画，通过 `TransitionGroup` 实现：
|
||
|
||
- **展开动画**：子节点从上方逐渐撑开并淡入，同级子节点有 0.03s 的错开延迟
|
||
- **折叠动画**：节点向上收起并淡出，动画完成后自动移除
|
||
|
||
可通过覆盖 `.tree-node-enter-active`、`.tree-node-leave-active` 及 `@keyframes treeExpandIn`、`treeCollapseOut` 样式来调整动画时长或效果。
|
||
|
||
---
|
||
|
||
## 📄 License
|
||
|
||
MIT
|
||
|
||
---
|
||
|
||
**文档版本**：v1.0.0
|
||
**最后更新**：2026-04-26
|