3个关键步骤掌握jQuery-TreeGrid树形表格实现与避坑指南

2026-03-14 04:43:59作者：裴麒琰

在开发数据管理系统时，你是否曾因层级数据展示而头疼？当面对部门结构、文件目录等具有父子关系的数据时，普通表格无法直观呈现层级关系，手动实现树形结构又耗时费力。本文将通过三个核心场景，带你从零基础掌握jQuery-TreeGrid插件的使用方法，解决层级数据展示难题，避开80%新手会踩的坑。

[环境搭建]：如何正确引入jQuery-TreeGrid插件？

场景还原

小王是刚入行的前端开发者，接到一个需求：将公司组织架构数据用树形表格展示。他下载了jQuery-TreeGrid插件后，直接在HTML中引入JS文件，却发现控制台报错"$ is not defined"，表格毫无反应。

错误分析

依赖缺失：未先引入jQuery库导致插件无法识别$符号
路径错误：插件文件路径引用不正确
加载顺序：JS文件加载顺序颠倒，插件在jQuery之前加载

解决方案

准备工作

🔧 确保已安装Node.js环境，通过命令行克隆项目代码：

git clone https://gitcode.com/gh_mirrors/jq/jquery-treegrid

核心操作

🔧 第一步：引入jQuery库在HTML文件的<head>标签中添加：

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
<!-- 注意：必须先引入jQuery再引入插件 -->

🔧 第二步：引入插件文件根据项目目录结构，添加插件的CSS和JS文件：

<!-- 引入样式文件 -->
<link rel="stylesheet" href="css/jquery.treegrid.css">
<!-- 引入核心脚本 -->
<script src="js/jquery.treegrid.min.js"></script>

验证方法

在浏览器中打开页面，按F12打开开发者工具，切换到Console面板，输入$.fn.treegrid，若返回函数定义则表示引入成功。

[!TIP] 生产环境建议使用minified版本（.min.js）以提高加载速度，开发环境可使用未压缩版本方便调试。

新手常见误区

⚠️ 直接下载单个JS文件使用，忽略了CSS样式的引入，导致表格布局错乱 ⚠️ 引入多个版本的jQuery，造成版本冲突 ⚠️ 未等待DOM加载完成就执行初始化代码，导致选择器无法找到表格元素

[基础使用]：如何将普通表格转换为树形表格？

场景还原

小李成功引入插件后，按照示例代码编写了HTML表格，但调用.treegrid()方法后，表格依然是普通表格样式，没有树形结构出现。检查HTML发现，他的表格行没有任何特殊属性。

错误分析

缺少数据属性：表格行未添加标识父子关系的data-tt-id和data-tt-parent-id属性
表格结构不规范：没有使用<thead>和<tbody>标签区分表头和数据
初始化时机错误：在DOM元素未加载完成时执行了初始化代码

解决方案

准备工作

🔧 创建基础表格结构，确保包含表头和数据体：

<table id="orgTree">
  <thead>
    <tr>
      <th>部门名称</th>
      <th>负责人</th>
      <th>人数</th>
    </tr>
  </thead>
  <tbody>
    <!-- 数据行将在这里动态生成或静态定义 -->
  </tbody>
</table>

核心操作

🔧 第一步：为表格行添加层级关系属性

<tbody>
  <!-- 根节点：parent-id为0或不设置 -->
  <tr data-tt-id="1" data-tt-parent-id="0">
    <td>技术部</td>
    <td>张经理</td>
    <td>20</td>
  </tr>
  <!-- 子节点：parent-id对应父节点的id -->
  <tr data-tt-id="1-1" data-tt-parent-id="1">
    <td>前端组</td>
    <td>李主管</td>
    <td>8</td>
  </tr>
  <tr data-tt-id="1-2" data-tt-parent-id="1">
    <td>后端组</td>
    <td>王主管</td>
    <td>12</td>
  </tr>
</tbody>

🔧 第二步：初始化树形表格

// 等待DOM加载完成
$(document).ready(function() {
  // 基本初始化
  $("#orgTree").treegrid({
    // 展开/折叠图标所在列，默认为第一列
    treeColumn: 0,
    // 初始展开级别，0表示全部折叠，-1表示全部展开
    expandLevel: 0,
    // 是否显示连接线
    lines: true
  });
});

验证方法

刷新页面后，表格第一列应出现展开/折叠图标，点击图标可显示或隐藏子节点，层次结构清晰可见。

[!TIP] data-tt-id必须是唯一的字符串或数字，data-tt-parent-id为0或不设置表示根节点

新手常见误区

⚠️ 所有行都使用相同的data-tt-id，导致节点关系混乱 ⚠️ 忘记设置treeColumn参数，图标出现在错误列 ⚠️ 对动态生成的表格数据，在数据加载完成前执行初始化

[功能进阶]：如何控制树形节点的展开与折叠？

场景还原

项目中需要实现"展开全部"和"折叠全部"按钮，小张尝试调用$('#orgTree').treegrid('expand')却没有反应，查阅文档后发现需要指定节点ID，但他不知道如何获取所有节点ID。

错误分析

方法使用错误：未正确传递参数给展开/折叠方法
节点ID管理混乱：没有维护节点ID的层次结构
事件绑定时机不当：在表格初始化前绑定按钮事件

解决方案

准备工作

🔧 添加控制按钮到页面：

<button id="expandAll">展开全部</button>
<button id="collapseAll">折叠全部</button>

核心操作

🔧 第一步：实现展开/折叠单个节点

// 展开指定节点
function expandNode(nodeId) {
  // 参数1: 方法名，参数2: 节点ID
  $("#orgTree").treegrid("expand", nodeId);
}

// 折叠指定节点
function collapseNode(nodeId) {
  $("#orgTree").treegrid("collapse", nodeId);
}

🔧 第二步：实现展开/折叠全部节点

// 展开全部节点
$("#expandAll").click(function() {
  // 获取所有根节点
  var rootNodes = $("tr[data-tt-parent-id='0']");
  
  // 递归展开所有节点
  rootNodes.each(function() {
    var nodeId = $(this).data("tt-id");
    expandAllChildren(nodeId);
  });
});

// 递归展开所有子节点
function expandAllChildren(nodeId) {
  // 展开当前节点
  $("#orgTree").treegrid("expand", nodeId);
  
  // 查找所有子节点
  var children = $("tr[data-tt-parent-id='" + nodeId + "']");
  
  // 递归展开子节点
  children.each(function() {
    expandAllChildren($(this).data("tt-id"));
  });
}

// 折叠全部节点
$("#collapseAll").click(function() {
  $("#orgTree").treegrid("collapseAll");
});

🔧 第三步：绑定节点展开/折叠事件

$("#orgTree").treegrid({
  // 其他配置...
  // 节点展开时触发
  onExpand: function(event, node) {
    console.log("节点展开:", node.id);
    // 可以在这里添加自定义逻辑，如加载子节点数据
  },
  // 节点折叠时触发
  onCollapse: function(event, node) {
    console.log("节点折叠:", node.id);
  }
});