更新记录

0.0.3（2026-04-01） 下载此版本

• 首次更新

平台兼容性

uni-app(3.7.3)

tdesign-uniapp-tree

基于 Vue 3 + uni-app 的树形选择器组件，API 对齐 TDesign Vue Next Tree，同时扩展了弹窗模式、拖拽排序等移动端特有能力。配合 @tdesign/uniapp 使用。

特性

• 🎯 单选 / 多选 — 默认单选，checkable 开启多选
• 🔍 节点过滤 — 通过 filter 函数实时过滤节点
• 🌳 父子级联 — checkStrictly 开启父子关联选中，支持 weak / strong 模式
• ✅ 受控模式 — 支持 v-model:value、v-model:expanded、v-model:actived 双向绑定
• 📦 异步加载 — lazy + load 按需加载子节点
• 🖱 拖拽排序 — draggable 节点拖拽重新排序
• 🎨 主题定制 — CSS Design Tokens 自定义主题
• 📄 弹窗 / 页面模式 — usePopup 切换 popup 弹窗 / page 整页展示
• 📐 辅助线 — line 开启节点连接线
• 💡 节点激活 — activable 节点高亮激活

安装

npm install tdesign-uniapp-tree @tdesign/uniapp

在 pages.json 中配置 easycom 自动注册：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^t-(.*)": "@tdesign/uniapp/$1/$1.vue",
      "tdesign-uniapp-tree": "tdesign-uniapp-tree/tdesign-uniapp-tree/tdesign-uniapp-tree.vue"
    }
  }
}

快速上手

基础单选

<template>
  <tdesign-uniapp-tree
    ref="treeRef"
    :data="treeData"
    @confirm="onConfirm"
  />
</template>

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

const treeRef = ref();
const treeData = ref([
  { id: '1', label: '北京' },
  {
    id: '2', label: '上海',
    children: [
      { id: '2-1', label: '浦东新区' },
      { id: '2-2', label: '黄浦区' },
    ],
  },
  {
    id: '3', label: '广州',
    children: [
      { id: '3-1', label: '海珠区' },
      { id: '3-2', label: '番禺区' },
    ],
  },
]);

function onConfirm(list) {
  console.log('选中项：', list);
}
</script>

多选 + 父子级联

<tdesign-uniapp-tree
  ref="treeRef"
  :data="treeData"
  checkable
  check-strictly
  value-mode="all"
  @confirm="onConfirm"
/>

搜索过滤

<tdesign-uniapp-tree
  ref="treeRef"
  :data="treeData"
  :filter="filterFn"
/>

<script setup>
const keyword = ref('');
function filterFn(node) {
  if (!keyword.value) return true;
  return node.label.includes(keyword.value);
}
</script>

异步加载

<tdesign-uniapp-tree
  ref="treeRef"
  :data="asyncTreeData"
  lazy
  :load="loadData"
  checkable
/>

<script setup>
const asyncTreeData = ref([
  { id: 'a1', label: '节点A', children: [] },
  { id: 'b1', label: '节点B', children: [] },
]);

function loadData(data) {
  const { $type: type, source } = data;
  if (type === 'nodeLoad') {
    return new Promise((resolve) => {
      setTimeout(() => {
        resolve([
          { id: `${source.id}-1`, label: `${source.label}-子项1` },
          { id: `${source.id}-2`, label: `${source.label}-子项2` },
        ]);
      }, 1000);
    });
  }
}
</script>

v-model 受控

<tdesign-uniapp-tree
  :data="treeData"
  checkable
  v-model:value="checkedIds"
  v-model:expanded="expandedIds"
  v-model:actived="activedIds"
  activable
/>

页面模式

<tdesign-uniapp-tree
  :use-popup="false"
  :data="treeData"
  checkable
  @confirm="onConfirm"
/>

API

Props

对齐 PC 端 TDesign Tree

valueMode 可选值：'onlyLeaf'（仅叶子节点）、'parentFirst'（父节点优先）、'all'（所有节点）

UniApp 扩展

Events

Slots

Methods

通过 ref 调用组件实例方法：

CSS Design Tokens

组件使用 CSS 变量实现主题定制，覆盖以下变量即可自定义样式：

.tdesign-uniapp-tree {
  --td-tree-bg-color: #fff;
  --td-tree-text-color: #757575;
  --td-tree-brand-color: #0052d9;
  --td-tree-border-color: #f5f5f5;
  --td-tree-line-color: rgba(204, 204, 204, 0.9);
  --td-tree-disabled-color: #ccc;
  --td-tree-input-border-color: #f0f0f0;
  --td-tree-item-height: 80rpx;
  --td-tree-font-size: 28rpx;
  --td-tree-bar-font-size: 32rpx;
  --td-tree-bar-height: 116rpx;
  --td-tree-bar-title-color: #000;
  --td-tree-drag-shadow: 6rpx 8rpx 12rpx rgba(0, 0, 0, 0.15);
  --td-tree-focus-shadow: 0 0 6px 4px rgba(169, 169, 169, 0.15);
  --td-tree-active-color: var(--td-tree-brand-color);
  --td-tree-delete-color: #e34d59;
  --td-tree-empty-color: var(--td-tree-text-color);
  --td-tree-radius: 24rpx;
}

Demo 项目结构

本仓库的 src/pages/ 即完整的示例项目，采用 @tdesign/uniapp 内置的 t-demo / t-demo-header 组件组织展示。

src/pages/
├── index/
│   ├── index.vue                      ← 主入口页（t-demo 模式）
│   └── _example/
│       ├── tree-data.js               ← 公共树数据
│       ├── base/index.vue             ← 基础用法（单选/多选）
│       ├── select-parent/index.vue    ← 父级可选配置
│       ├── echo-default/index.vue     ← 默认回显
│       ├── search-mode/index.vue      ← 搜索过滤
│       ├── expanded/index.vue         ← 展开模式配置
│       ├── draggable/index.vue        ← 拖拽排序
│       ├── async-load/index.vue       ← 异步加载
│       ├── theme/index.vue            ← 主题颜色
│       └── page-mode/index.vue        ← 页面模式入口
└── tree-page/
    └── index.vue                      ← 页面模式示例

运行示例：

# H5
pnpm dev:h5

# 微信小程序
pnpm dev:mp-weixin

# App
pnpm dev:app

兼容性

• ✅ uni-app / uni-app X
• ✅ Vue 3
• ✅ H5 / 微信小程序 / App

License

MIT