更新记录

1.0.0（2026-04-25） 下载此版本

✅ 无限层级树形结构展示，子节点通过 children 字段配置

✅ 节点展开/折叠，支持递归展开/折叠指定节点及所有子节点

✅ 默认展开所有节点（defaultExpandAll）或指定节点（defaultExpandedKeys）

✅ 树形层级序号（自动生成 1、1.1、1.2 等）

✅ 最外层序号展示（可控仅顶级节点或所有行）

✅ 节点缩进可配置

平台兼容性

uni-app(3.7.10)

xq-tree-table 树形表格组件使用文档

xq-tree-table 是一个基于 uni-table 深度封装的树形数据表格组件，支持树形展开/折叠、自定义多选/全选/半选、层级序号、列显隐与本地存储、排序/筛选事件代理、插槽自定义等功能，适用于后台管理系统的部门、分类、组织架构等树形数据展示。

安装与引入

组件符合 easycom 规范，将 xq-tree-table 文件夹放入项目的 uni_modules 目录 中，即可在页面中直接使用，无需手动导入。

依赖 @dcloudio/uni-ui 中的 uni-table、uni-icons、uni-popup、uni-tooltip，请确保项目已安装这些组件。

快速开始

<template>
  <xq-tree-table
    v-model:columns="columns"
    :table-data="treeData"
    type="selection"
    row-key="id"
    default-expand-all
    :max-height="600"
    @selection-change=""
  />
</template>

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

const columns = ref([
  { prop: 'name', label: '部门名称', width: 200 },
  { prop: 'status', label: '状态', slot: 'status' },
  { prop: 'action', label: '操作', slot: 'action' }
])

const treeData = ref([
  {
    id: 1,
    name: '总公司',
    children: [
      { id: 2, name: '研发部' },
      { id: 3, name: '市场部' }
    ]
  }
])

const  = (rows) => console.log('选中行:', rows)
</script>

Props

数据与树形配置

表格样式

多选配置

序号列

树形序号列

列显隐与本地存储

行高亮与固定高度

Events

Slots

表头插槽 header

通过列配置的 thSlot 字段启用，可自定义表头内容。作用域参数：{ column, cIdx }

<template #header="{ column, cIdx }">
  <text>{{ column.label }} (自定义)</text>
</template>

单元格插槽 cell

用于自定义单元格内容，所有数据列统一使用静态插槽名 cell。作用域参数：{ row, column, rowIndex, isExpandedCell } 其中 column 为列原始配置对象，可通过 column.prop 区分不同列。

<template #cell="{ row, column }">
  <template v-if="column.prop === 'status'">
    <u-tag :text="row.status === '0' ? '启用' : '禁用'" />
  </template>
  <template v-else-if="column.prop === 'action'">
    <button @click="handleEdit(row)">
      编辑
    </button>
  </template>
</template>

如果没有提供 #cell 插槽，组件会自动根据 tooltip 配置显示默认文本或气泡提示。

列配置

每个列对象支持以下属性（除 prop 和 label 外均为可选）：

默认第一列为树形列，会额外显示展开/折叠图标及缩进。

events 示例：

{
  prop: 'postId',
  label: '岗位编号',
  sortable: true,
  events: {
    'sort-change': ({ column, event }) => {
      console.log('排序变化', event.order)
    }
  }
}

方法 (通过 ref 调用)

列显隐与本地存储

传入 local-column-keys="my_table"，用户勾选列后自动存入本地缓存，刷新页面后列配置会恢复。

<xq-tree-table local-column-keys="my_table_columns" ... />

在列配置弹窗中，被 disabled 的列将无法取消勾选（例如操作列常用）。

完整示例

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

const tableRef = ref(null)

// 可以直接将事件写在column得events中
const columns = ref([
  { prop: 'name', label: '部门名称', width: 200 },
 {
    prop: 'status',
    label: '状态',
    slot: 'status', // 使用插槽自定义内容
    visible: true,
    filterType: 'select', // 筛选类型为下拉
    filterData: [ // 下拉的内容
      { text: '全部', value: '' },
      { text: '启用', value: '0' },
      { text: '禁用', value: '1' }
    ],
    events: {
      'filter-change': ({ column, event }) => {
        console.log('筛选值', event.value)
      }
    }
  },
  { prop: 'action', label: '操作', slot: 'action', width: 150, disabled: true }
])

// 或者将columns放到配置文件中,这么写也可以
import { tableColumns } from './xxx.js'
// 定义事件处理器（只关注业务逻辑）
const eventHandlers = {
  postId: {
    'sort-change': (e) => {
      console.log('岗位编号排序', e)
      // 直接调用接口、更新 state
    },
  },
  status: {
    'filter-change': (e) => {
      console.log('岗位状态过滤', e)
      // 直接调用接口、更新 state
    },
  },
}

// 最好是做一个深拷贝, 确保不会影响其他页面的引用
const columns = ref(
  tableColumns.map(col => ({ ...col, events: eventHandlers[col.prop] || col.events || {} })),
)
---
const treeData = ref([
  {
    id: 1,
    name: '总公司',
    status: '0',
    children: [
      { id: 2, name: '研发部', status: '1' },
      { id: 3, name: '市场部', status: '0' }
    ]
  }
])

const  = rows => console.log('选中:', rows)
const onRowClick = row => console.log('点击行:', row)

function handleEdit(row) { /* 编辑逻辑 */ }
function handleDelete(row) { /* 删除逻辑 */ }

// 调用暴露方法
const selectAll = () => tableRef.value.selectionAll()
</script>

<template>
  <xq-tree-table
    ref="tableRef"
    v-model:columns="columns"
    :table-data="treeData"
    type="selection"
    row-key="id"
    :max-height="500"
    local-column-keys="demo_tree"
    @selection-change=""
    @row-click="onRowClick"
  >
    <template #cell="{ row, column }">
      <template v-if="column.prop === 'status'">
        <u-tag :text="row.status === '0' ? '启用' : '禁用'" />
      </template>
      <template v-else-if="column.prop === 'action'">
        <button @click="handleEdit(row)">
          编辑
        </button>
        <button @click="handleDelete(row)">
          删除
        </button>
      </template>
    </template>
  </xq-tree-table>
</template>

平台兼容性

依赖说明

• uni-table / uni-tr / uni-th / uni-td
• uni-icons
• uni-popup
• uni-tooltip

以上组件均包含在 @dcloudio/uni-ui 中，请确保项目已安装。

文档版本：v1.0.0 最后更新：2026-04-25