# Tree 树形组件 3.4.47

树形组件用于展示具有层级结构的数据，支持展开/折叠、复选框、节点点击、手风琴模式、默认展开/默认选中和实例方法读取选中状态。

# 平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	头条小程序	QQ小程序
√	√	√	√	√	√	√

# 微信小程序插槽说明

为规避微信小程序端动态 scoped slot 在树形递归场景下可能不显示或运行时报错的问题，组件在微信小程序端会使用内置文本渲染作为稳定兜底。H5、App 等平台仍支持默认插槽自定义节点内容。

# 基本使用

通过 data 传入树数据，通过 props 指定节点字段映射。

<template>
  <up-tree
    :data="treeData"
    :props="defaultProps"
    :default-expanded-keys="['1']"
    highlight-current
    current-node-key="1"
    @node-click="handleNodeClick"
  />
</template>

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

const defaultProps = ref({
  label: 'label',
  children: 'children',
  nodeKey: 'id',
  disabled: 'disabled'
});

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

const handleNodeClick = (node) => {
  console.log('节点被点击:', node);
};
</script>

<script>
export default {
  data() {
    return {
      defaultProps: {
        label: 'label',
        children: 'children',
        nodeKey: 'id',
        disabled: 'disabled'
      },
      treeData: [
        {
          id: '1',
          label: '一级 1',
          children: [
            {
              id: '1-1',
              label: '二级 1-1',
              children: [
                { id: '1-1-1', label: '三级 1-1-1' },
                { id: '1-1-2', label: '三级 1-1-2' }
              ]
            }
          ]
        }
      ]
    };
  },
  methods: {
    handleNodeClick(node) {
      console.log('节点被点击:', node);
    }
  }
};
</script>

# 自定义节点内容

H5、App 等平台可以通过默认插槽自定义节点内容。插槽参数包含 node、data、level、expanded、checked、indeterminate、disabled。

<template>
  <up-tree :data="treeData" :props="defaultProps" default-expand-all>
    <template #default="{ node, level, expanded }">
      <view class="custom-tree-node">
        <text>{{ node.label }}</text>
        <text v-if="node.children && node.children.length">
          {{ expanded ? '已展开' : '已收起' }} · {{ level }}级
        </text>
      </view>
    </template>
  </up-tree>
</template>

# 复选框

设置 show-checkbox 后展示复选框。默认情况下父子节点会联动；设置 check-strictly 后父子节点互不影响。

<template>
  <up-tree
    ref="treeRef"
    :data="treeData"
    :props="defaultProps"
    show-checkbox
    default-expand-all
    check-on-click-node
    :default-checked-keys="['2-1-1']"
    @check-change="handleCheckChange"
    @check="handleCheck"
  />
</template>

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

const treeRef = ref(null);
const defaultProps = ref({
  label: 'label',
  children: 'children',
  nodeKey: 'id',
  disabled: 'disabled'
});
const treeData = ref([
  {
    id: '2',
    label: '表单组件',
    children: [
      {
        id: '2-1',
        label: '输入组件',
        children: [
          { id: '2-1-1', label: 'Input 输入框' },
          { id: '2-1-2', label: 'Textarea 文本域' }
        ]
      }
    ]
  }
]);

const handleCheckChange = (node, checked) => {
  console.log('勾选状态变化:', node, checked);
};

const handleCheck = (node, state) => {
  console.log('当前选中 keys:', state.checkedKeys);
};

const setChecked = () => {
  treeRef.value.setCheckedKeys(['2-1-2']);
};
</script>

<script>
export default {
  methods: {
    handleCheckChange(node, checked) {
      console.log('勾选状态变化:', node, checked);
    },
    handleCheck(node, state) {
      console.log('当前选中 keys:', state.checkedKeys);
    },
    setChecked() {
      this.$refs.treeRef.setCheckedKeys(['2-1-2']);
    }
  }
};
</script>

# 手风琴模式

设置 accordion 后，同一级节点每次只展开一个。

<template>
  <up-tree
    :data="treeData"
    :props="defaultProps"
    accordion
    expand-on-click-node
  />
</template>

# API

# Props 参数说明

参数	说明	类型	默认值	可选值
data	树的数据源	`Array`	`[]`	-
props	节点字段映射，支持 `label`、`children`、`nodeKey`、`disabled`	`Object`	`{ label: 'label', children: 'children', nodeKey: 'id', disabled: 'disabled' }`	-
node-key	每个节点的唯一标识字段名，优先级高于 `props.nodeKey`	`String`	`''`	-
show-checkbox	是否显示复选框	`Boolean`	`false`	`true / false`
default-expand-all	是否默认展开所有节点	`Boolean`	`false`	`true / false`
default-expanded-keys	默认展开的节点 key 列表	`Array`	`[]`	-
default-checked-keys	默认选中的节点 key 列表	`Array`	`[]`	-
expand-on-click-node	是否在点击节点内容时展开或折叠	`Boolean`	`true`	`true / false`
check-on-click-node	是否点击节点内容时切换选中状态	`Boolean`	`false`	`true / false`
check-strictly	是否启用父子节点不关联选择	`Boolean`	`false`	`true / false`
accordion	是否开启手风琴模式	`Boolean`	`false`	`true / false`
highlight-current	是否高亮当前节点	`Boolean`	`false`	`true / false`
current-node-key	当前高亮节点 key	`String / Number`	`''`	-
indent	相邻层级缩进距离	`String / Number`	`32`	-
icon-size	展开图标大小	`String / Number`	`14`	-
checkbox-size	复选框大小	`String / Number`	`16`	-
expand-icon	折叠状态图标名	`String`	`play-right-fill`	-
collapse-icon	展开状态图标名	`String`	`arrow-down-fill`	-

# Events 事件说明

事件名	说明	参数
@node-click	点击节点时触发	`node`
@check-change	节点勾选状态变化时触发	`node, checked`
@check	复选框状态变化后触发	`node, { checkedNodes, checkedKeys, halfCheckedNodes, halfCheckedKeys }`
@node-expand	节点展开时触发	`node`
@node-collapse	节点折叠时触发	`node`
@current-change	当前节点变化时触发	`currentNode, oldCurrentNode`

# Ref 方法说明

方法名	说明	返回值
getCheckedNodes(leafOnly)	获取当前选中的节点列表，`leafOnly` 为 `true` 时只返回叶子节点	`nodes[]`
getCheckedKeys(leafOnly)	获取当前选中的节点 key 列表，`leafOnly` 为 `true` 时只返回叶子节点 key	`keys[]`
getHalfCheckedNodes()	获取半选节点列表	`nodes[]`
getHalfCheckedKeys()	获取半选节点 key 列表	`keys[]`
setCheckedKeys(keys, leafOnly)	设置选中的节点 key 列表	-
setChecked(key, checked, deep)	设置某个节点选中状态，`deep` 控制是否联动子节点	-
setCurrentKey(key)	设置当前高亮节点	-
getCurrentKey()	获取当前高亮节点 key	`key`
getCurrentNode()	获取当前高亮节点	`node`

# 插槽说明（Slot）

插槽名	说明	参数
default	自定义节点内容插槽，微信小程序端使用内置文本兜底	`{ node, data, level, expanded, checked, indeterminate, disabled }`

# 支持的功能特性

功能	说明
展开/折叠	支持点击箭头或配置 `expand-on-click-node` 控制展开逻辑
单节点展开	通过 `accordion` 开启同级手风琴展开
复选框联动	父子节点自动同步勾选状态，除非开启 `check-strictly`
默认状态	支持 `default-expanded-keys`、`default-checked-keys` 初始化展开和选中
当前节点	支持 `highlight-current`、`current-node-key` 和 `setCurrentKey`
自定义渲染	非微信小程序平台可通过默认插槽自定义节点内容
实例方法	提供读取和设置选中节点、半选节点、当前节点的方法

← Pagination 分页器 CityLocate 城市定位选择 →