# 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