简介Bootstrap TreeGrid 插件基于 Bootstrap 框架面向 Web 前端开发者主要解决表格内层级数据的展示与交互问题常用于权限管理、分类目录等需要嵌套结构的页面也适用于后台管理系统或内容组织场景。压缩包共 7 个文件包含 3 个 JavaScript 插件文件实现树形数据加载、展开折叠、事件处理等核心逻辑、2 个 CSS 样式文件用于控制节点缩进与外观风格以及 2 张 PNG 示例图片方便查看效果预览整体仅 33 KB非常轻量可直接集成到现有 Bootstrap 项目中。目前已有 380 人学习/下载适合具备基础 Bootstrap 使用经验的开发者快速上手。资源附带演示页面和使用说明可帮助读者掌握 TreeGrid 的初始化配置、数据源绑定、节点状态控制等关键步骤同时它支持自定义扩展列、排序搜索和 API 接口调用可以直接在项目中复用提升后台管理界面的信息组织效率与用户体验。1. 树形表格插件到底在解决什么问题从部门列表到文件目录的同一套痛点做后台管理系统时大概率会遇到一个需求左侧明明有一棵组织架构树右侧的表格却只能平铺展示所有部门上下级关系全靠上级部门这一列的文字硬撑。当产品经理提出部门列表要能按层级展开收起同时每一行还要有负责人、人数、操作按钮时普通表格拉不平树组件又丢了表头对齐。最后落地的方案基本都指向同一个方向基于 Bootstrap 的树形表格 js 插件在表格行上做层级缩进和展开收起同时保留列操作能力。这篇文章从选型原理、最小可运行代码讲到高频踩坑和进阶技巧照着做就能在项目里跑起来。2. 选型与渲染原理搞懂插件是怎么把树画进表格里的2.1 三种主流路线改造表格、树形组件拼接、现成插件先说我实际见过的三种做法。第一种是手写逻辑在普通表格里加一个层级列用字符串拼接缩进空格再用一个数组记录每个节点的展开状态。层级固定两层以内的时候很清爽一旦出现第三层缩进计算和状态联动开始失控遇到增删改节点时大量代码要重写。第二种是树组件加表格拼起来左边一棵树当导航右边表格显示当前节点数据视觉上没问题但用户会追问树里选中的节点为什么表格里没有高亮表格的筛选条件和树的状态为什么不同步。这种联动本质上是两套状态硬凑维护成本随需求增加线性膨胀。第三种是直接用现成的 treegrid 插件这也是大多数项目最终走的路。这类插件基于 jQuery 加 Bootstrap 的表格能力初始化时传入树形数据或平铺数据自动生成缩进和展开箭头。因为被大量项目跑过主要坑位都浮出来了反而是最好落地的选择。除非项目明确要求零 jQuery 依赖否则我一般会直接选这条路。三种路线做个对比路线优点缺点适合场景表格手写缩进零依赖、完全可控状态管理繁琐层级深了容易乱层级固定的两级小表树组件加表格树交互体验完整两套数据状态割裂联动代码工作量大树做导航、表格只读现成 treegrid 插件开箱即用、方案成熟依赖 jQuery深度定制受插件边界限制大多数后台管理端场景有一点容易被忽略现成插件不等于零成本。插件默认样式依赖 Bootstrap 的表格类名整体引入 jQuery 在老项目里没什么负担但如果项目已经迁到 Vue 或 React塞一个 jQuery 插件会显得很重。这种时候更要慎重新项目优先找组件库自带的树表格老项目维护才考虑插件。2.2 树形数据格式parentId 平铺与嵌套 children树形表格的输入数据有两种常见组织方式后端接口大多数返回平铺格式前端组件大多数偏爱嵌套格式。先把两者的区别看清后面所有转换逻辑都从这里出发。// 方式一平铺加 parentId 关联后端返回最常见 const flatData [ { id: 1, parentId: 0, name: 总部, leader: 张明 }, { id: 2, parentId: 1, name: 研发部, leader: 李华 }, { id: 3, parentId: 1, name: 市场部, leader: 王芳 }, { id: 4, parentId: 2, name: 前端组, leader: 赵磊 }, { id: 5, parentId: 4, name: 基础架构组, leader: 钱进 } ]; // 方式二嵌套 children前端组件更常用 const nestedData [ { id: 1, parentId: 0, name: 总部, leader: 张明, children: [ { id: 2, parentId: 1, name: 研发部, leader: 李华, children: [ { id: 4, parentId: 2, name: 前端组, leader: 赵磊 } ] }, { id: 3, parentId: 1, name: 市场部, leader: 王芳 } ] } ];平铺格式的优点是构造简单数据库里也好存直接按 parentId 分组就能组装关系缺点是层级关系藏在一串 id 里肉眼不容易看出结构。嵌套格式正好相反层级一目了然但要递归读取后端拼装也麻烦一些。大部分 treegrid 插件内部最终都要把数据展平成带层级标记的行数组所以两种格式可以互换。平铺转嵌套的常见做法是先按 parentId 建索引再递归组装嵌套转平铺用深度优先遍历每层记录深度。不需要把每种写法都背下来但必须知道插件初始化的参数里会说明它接收哪种格式传错格式是新手最容易翻车的地方。2.3 渲染原理一次展平加状态标记理解了数据格式再看插件怎么把树画出来。几乎所有 treegrid 插件的主线逻辑都一样把嵌套结构展平成一维行数组给每行标注层级和可见性。渲染时表格只渲染可见行为 true 的行折叠一个节点时把它所有后代行标记为不可见。展开状态一般用集合维护比如 expandedIds。每次点击箭头插件在这个集合里增删节点 id重新计算全部行的可见性再局部更新表格。这个机制决定了两件事展开、折叠操作本质上是整表重算数据量大时会卡排序、分页这类扩展如果挂在表格原有逻辑上容易打破可见性的一致性第 4 章会展开讲。层级缩进也不是靠加空格实现而是通过给每行插入带 padding-left 的占位单元格或动态设置第一格的内边距。这解释了为什么自定义列宽时第一列的缩进表现有时候会显得奇怪。3. 跑通第一个树形表格依赖、HTML 与初始化配置3.1 最小依赖清单和引入顺序先确认项目里是否已有 jQuery 和 Bootstrap大多数老项目都自带缺的话要补上。依赖按顺序引入顺序错乱会出现各种插件没生效的玄学问题先给最小组合link relstylesheet hrefbootstrap.min.css link relstylesheet hreftreegrid.css script srcjquery.min.js/script script srcbootstrap.min.js/script script srctreegrid.js/script样式部分先加载 Bootstrap 的 bootstrap.min.css再加载 treegrid 的 css后者的展开箭头和缩进样式要在 Bootstrap 之后生效。脚本部分必须 jQuery 在前Bootstrap 的 js 其次最后才是 treegrid 插件脚本因为插件初始化时依赖前两者的全局对象。注意不要图省事把 treegrid 的 css 和 js 合并到一个自定义文件里插件内部可能依赖 Bootstrap 的类名比如 .table、.collapse合并压缩时顺序一乱排查起来非常难受。3.2 最小可运行页面HTML 结构加数据源下面这个页面是验证插件能不能用的最小骨架。它不涉及业务逻辑只验证数据进来、树形渲染、展开收起正常!DOCTYPE html html langzh-CN head meta charsetUTF-8 link relstylesheet hrefbootstrap.min.css link relstylesheet hreftreegrid.css script srcjquery.min.js/script script srcbootstrap.min.js/script script srctreegrid.js/script /head body div classcontainer table iddeptTable classtable table-bordered thead tr th部门名称/th th负责人/th th人数/th /tr /thead tbody/tbody /table /div script const flatData [ { id: 1, parentId: 0, name: 总部, leader: 张明, count: 12 }, { id: 2, parentId: 1, name: 研发部, leader: 李华, count: 80 }, { id: 3, parentId: 1, name: 市场部, leader: 王芳, count: 30 }, { id: 4, parentId: 2, name: 前端组, leader: 赵磊, count: 15 }, { id: 5, parentId: 4, name: 基础架构组, leader: 钱进, count: 6 } ]; $(#deptTable).treegrid({ data: flatData, idField: id, parentField: parentId, treeColumn: name, expandAll: false }); /script /body /html这段代码的逻辑插件收到平铺数据后根据 idField 和 parentField 找出父子关联由 treeColumn 指定的字段所在的列渲染树形缩进和箭头。expandAll 传 false让根层级初始展开、下层默认收起页面加载后只看到总部及研发部、市场部三个根节点。几个参数值得单独说。treeColumn 必须对应表头里真实存在的列名传错的话缩进和箭头会跑到别的列上。expandAll 在数据量几十行时随便用换成几千行它就是卡顿的第一嫌疑。idField 不要省略即使数据里没有 id 字段也建议在接口层做一次映射因为插件的展开状态集合依赖它做 key。3.3 初始化配置与必调参数从 treeColumn 到 onClickRow跑通最小示例后最常改的配置集中在这几个参数上。做项目前先抄一遍这个表心里有底参数名作用推荐值idField节点唯一标识字段数据里的主键名parentField父节点标识字段平铺数据必须指定treeColumn树形列决定缩进渲染到哪一列选层级信息所在列expandAll是否初始化全部展开数据少于 200 行才建议 trueonChange展开收起后的回调用于同步其他组件状态onClickRow点击行回调用于行选中或详情跳转再给一段带事件的初始化代码对后面做联动很有用$(#deptTable).treegrid({ data: flatData, idField: id, parentField: parentId, treeColumn: name, expandAll: false, onChange: function (row, expanded) { // 当节点被展开或收起时触发row 是当前行数据 refreshChildCount(row.id, expanded); }, onClickRow: function (rowEle, rowData) { // 用户点击任意行时触发常用于加载详情 loadDeptDetail(rowData.id); } });onChange 的回调签名在不同实现里略有差异常见是传入当前行数据和展开状态布尔值。onClickRow 要注意它是点击任何一行都触发如果想让点击箭头和点击行本身的行为区分开我一般会把箭头区域的点击单独绑定避免误触发。4. 树形表格 5 个高频踩坑现场现象、原因、解决这一章是血泪经验每条都来自实际项目。提前看完比测试报告丢过来再查高效得多。4.1 展开图标不显示点击也没有反应现象表格正常渲染层级缩进也有唯独每行前面的箭头是空白点击也没反应。原因treegrid 样式文件用了一种字体图标引入 treegrid.css 后如果页面里没有对应字体文件或者字体路径被构建工具改写错图标就渲染成空白。更隐蔽的是部分插件把图标写在伪元素 content 里浏览器控制台不报错表现为一切正常但就是没图标。解决打开网络面板看字体请求是否 404。如果 404把字体文件放到正确路径或者用 CSS 覆盖图标为文本符号我常用的方案是覆盖成和-.treegrid-expander { font-family: Arial, sans-serif; } .treegrid-collapse::before { content: -; } .treegrid-expand::before { content: ; }这个方案不依赖字体文件任何构建环境下都不会再出现图标消失的问题缺点是样式朴素但对后台系统完全够用。4.2 排序功能把树形层级打乱现象给表格开启排序点击表头按人数排序父子关系乱了子级跑到父级上面或者根节点和子节点混在一起。原因树形表格的排序扩展直接对渲染用的展平数组排序它不知道哪一行是谁的子节点。只要排序逻辑没约束父节点必须先于子节点结果必然错乱。解决如果业务必须要排序我一般会禁止全表排序改为列内排序。在排序回调里先按根节点分组组内再排子节点层级就不会被打乱$(#deptTable).treegrid({ // 禁用插件自带的全表排序 sortable: false }); // 自己实现列内排序取出当前展开的所有行 // 按 parentId 分组组内排序后重新写入表格 function sortVisibleRows(groupKey) { const rows getAllVisibleRows(); const groups groupByParentId(rows); Object.keys(groups).forEach(pid { groups[pid].sort((a, b) a[groupKey] - b[groupKey]); }); renderSortedRows(groups); }更省事的做法如果排序需求不强烈直接关闭排序功能成本最低。排序和树形结构天然有冲突接需求时先确认是不是又要做一个互相矛盾的交互。4.3 分页后展开状态丢失现象展开某个根节点的三级子级翻到下一页再翻回来发现所有节点都收起了。原因分页扩展重新渲染时只把当前页数据交给表格展开状态的集合没有和页面绑定翻页等于重新初始化。解决加一个全局展开状态缓存在翻页前保存当前展开节点集合表格渲染完成后恢复let expandedCache new Set(); // 在每次翻页前调用收集当前展开行 function beforePageChange() { expandedCache.clear(); $(#deptTable).find(tr.treegrid-expanded).each(function () { expandedCache.add($(this).data(id)); }); } // 在表格重新渲染完成后调用 function afterPageRender() { expandedCache.forEach(function (rowId) { $(#deptTable).treegrid(expandRow, rowId); }); }这个方案只对展开状态有效折叠状态不需要缓存因为新增行默认都是收起。还有一个边界要留意如果分页接口本身是懒加载子节点翻页回来子节点数据可能还没到需要在数据加载完成后再做一次恢复展开的判断。4.4 懒加载子节点后表格行高跳动现象点击一个根节点展开子节点数据从接口返回后表格行高突然变化滚动条位置跳动体验很突兀。原因懒加载是先渲染一个占位行数据回来后把占位行替换成真正内容。占位行高度和真实行不一致替换时表格触发重排。解决让占位行高度与正常行保持一致给占位行设置固定最小高度。更简单的方案是展开时不立刻渲染占位行而是先显示一个加载中文本行数据回来后替换有加载过程的视觉过渡跳动感会明显减弱。4.5 一次性展开几千行导致页面卡死现象接口一次返回三千行数据初始化配置里 expandAll 为 true页面白屏几秒甚至弹出无响应提示。原因插件把几千行所有单元格的 DOM 一次性创建还要做一次性可见性计算数据量大时性能急剧下探。解决业务层做三层策略。第一接口分页每页最多五百行注意和分页共存时用 4.3 节的缓存方案且只在单页内有效跨页缓存会冲突。第二默认只展开第一层用 expandLevel 之类的参数代替 expandAll。第三如果数据是组织架构这种层级结构让接口先返回根节点框架子节点懒加载页面永远只渲染当前展开的节点这是最可靠的做法。5. 进阶让树形表格能落地生产的四个技巧5.1 自定义缩进、图标和初始展开层级默认样式往往和项目 UI 风格不搭最常见的需求是改箭头图标、缩进宽度和初始展开层级。缩进宽度直接改 CSS 的 padding-left.treegrid-indent { width: 20px; /* 每层缩进宽度默认16px层级多时调小 */ } .treegrid-expander { width: 20px; /* 箭头区域宽度 */ cursor: pointer; color: #2f6fed; /* 箭头颜色 */ }初始展开层级这个需求大多数插件没有现成参数。我的做法是初始化后手动展开需要的行而不是依赖配置$(#deptTable).treegrid({ expandAll: false }); // 数据加载完成后手动展开指定节点 $(#deptTable).treegrid(expandRow, 1);这里的逻辑是 expandRow 接收节点 id插件会展开它下方的子级。用这个方式可以不改数据源实现默认展开前两层或默认展开某个部门这类业务诉求。5.2 选中父节点联动子节点这是权限管理里最常见的需求勾选一个父节点它所有子节点也被选中取消父节点子节点全部取消。插件一般只提供单行选择联动逻辑要在点击回调里自己实现function toggleChildren(rowData, checked, rows) { rows.forEach(function (row) { if (row.parentId rowData.id) { setRowChecked(row.id, checked); // 递归处理下级这里用 parentId 判断 if (row.children row.children.length 0) { toggleChildren(row, checked, rows); } } }); }注意这里拿到的 rows 是插件内部的展平数据不是原始嵌套数据所以递归判断用 parentId 而不是 children。这个细节不对联动就只生效一层排查时还看不出来。实际项目中子节点选中还受半选状态影响即父节点的部分子节点被选中时父节点应显示半选图标。插件不一定支持半选我会在父节点回调里统计子节点选中数手动切换父节点的样式类。5.3 懒加载与服务器端数据获取接口返回整棵树在层级深时不可接受懒加载是必选项。做法是初始化只传根节点列表展开节点时在 onChange 里判断该行是否还有未加载的子节点有则发请求返回后调用插件的追加子节点方法$(#deptTable).treegrid({ data: rootList, idField: id, parentField: parentId, treeColumn: name, onChange: function (row, expanded) { if (expanded row.hasChildren !row.childrenLoaded) { $.ajax({ url: /api/dept/children, method: GET, data: { id: row.id }, success: function (children) { // 把返回的子节点插入当前行下面 $(#deptTable).treegrid(appendChild, { parentId: row.id, children: children }); } }); } } });这个方案的边界要特别注意用户快速连续点开、收起、再点开同一个节点会触发多次请求后一次返回会把前一次的数据重复追加。我在项目里用一个请求去重 Mapkey 是节点 id请求在途时直接忽略新触发这是典型的低概率但必现的坑。5.4 增删改后的局部刷新与状态恢复增删改节点后最忌讳的是整个表格重新初始化那会把用户展开状态全丢还带来一次全量渲染。正确做法是局部操作再保存展开状态// 删除节点先保存展开状态再移除当前行及其后代 function removeDept(rowId) { const expanded collectExpandedIds(); $(#deptTable).treegrid(removeRow, rowId); restoreExpanded(expanded); } // 新增节点直接追加到指定父节点下 $(#deptTable).treegrid(appendChild, { parentId: parentId, children: [newRow] });新增时要注意appendChild 如果父节点当前是收起状态新节点在视觉上不可见但数据已在内部数组里。用户下次展开时会看到数据如果后端同步返回时又做了一次全量刷新就可能出现新增了一次却出现两条的问题。处理办法是新增后立即把父节点展开或者调用刷新节点方法重读该父节点下的数据。6. 收尾验证树形表格健壮性的一个笨办法项目后期最常翻车的不是功能跑不起来而是各种操作组合之后的状态错乱。分享一个我一直在用的笨办法状态矩阵验证法。手工构造一个包含 3 层、每层 3 个节点的测试数据按「先展开某层 → 收起 → 翻页 → 再展开 → 刷新 → 排序」的顺序操作一遍每做一步就打印当前所有可见行的 id 顺序和期望结果对比。打印逻辑很简单遍历表格当前可见行把每行 id 和层级输出到控制台人工核对是否符合展开收起预期。这个方法不依赖测试框架5 分钟能完成一轮但能把插件内部状态有没有错乱看得清清楚楚。我第一次用这个办法是在某权限管理项目上线前夜当时只测了加载后默认展开叶子节点的流程没测先展开再刷新的路径。结果线上用户按「展开部门 → 搜索成员 → 清空搜索」操作了一遍树全部收起用户以为系统坏了。后来用状态矩阵跑了一遍才发现刷新操作把展开状态集合清了但没重新加载修复方案就是在刷新后调一次恢复展开的接口问题当场消失。现在每接一个树形表格需求我都会先花 10 分钟把这个验证流程跑一遍再交测试。行顺序、展开层级、翻页状态这三个点是树形表格最脆弱的地方先确认它们稳了再上业务功能。希望帮到你。本文还有配套的精品资源点击获取