UviewUltra 4.0

Appearance

Tree 树形组件 4.4.0 ​

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

平台差异说明 ​

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

微信小程序插槽说明 ​

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

基本使用 ​

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

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

自定义节点内容 ​

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

vue
<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 后父子节点互不影响。

vue
<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>
js
<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>

手风琴模式 ​

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

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

API ​

Props 参数说明 ​

参数说明类型默认值可选值
data树的数据源Array[]-
props节点字段映射，支持 label、children、nodeKey、disabledObject{ label: 'label', children: 'children', nodeKey: 'id', disabled: 'disabled' }-
node-key每个节点的唯一标识字段名，优先级高于 props.nodeKeyString''-
show-checkbox是否显示复选框Booleanfalsetrue / false
default-expand-all是否默认展开所有节点Booleanfalsetrue / false
default-expanded-keys默认展开的节点 key 列表Array[]-
default-checked-keys默认选中的节点 key 列表Array[]-
expand-on-click-node是否在点击节点内容时展开或折叠Booleantruetrue / false
check-on-click-node是否点击节点内容时切换选中状态Booleanfalsetrue / false
check-strictly是否启用父子节点不关联选择Booleanfalsetrue / false
accordion是否开启手风琴模式Booleanfalsetrue / false
highlight-current是否高亮当前节点Booleanfalsetrue / false
current-node-key当前高亮节点 keyString / Number''-
indent相邻层级缩进距离String / Number32-
icon-size展开图标大小String / Number14-
checkbox-size复选框大小String / Number16-
expand-icon折叠状态图标名Stringplay-right-fill-
collapse-icon展开状态图标名Stringarrow-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 时只返回叶子节点 keykeys[]
getHalfCheckedNodes()获取半选节点列表nodes[]
getHalfCheckedKeys()获取半选节点 key 列表keys[]
setCheckedKeys(keys, leafOnly)设置选中的节点 key 列表-
setChecked(key, checked, deep)设置某个节点选中状态，deep 控制是否联动子节点-
setCurrentKey(key)设置当前高亮节点-
getCurrentKey()获取当前高亮节点 keykey
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
自定义渲染非微信小程序平台可通过默认插槽自定义节点内容
实例方法提供读取和设置选中节点、半选节点、当前节点的方法