简介：TreeGrid树枝表控件及Demo源码面向需要在Web项目中实现树形表格展示的开发者，尤其适合使用ASP.NET技术栈、希望快速集成可展开折叠层级数据表的前端与后端人员。资源包共105个文件，约175KB，以gif界面截图、cs源码文件、dll与pdb程序集、aspx页面及css样式表为主，另含少量配置与项目文件，整体结构完整，可直接参考或二次开发。已有192人学习下载，说明该控件在实际项目中有一定参考价值。包内提供Default.aspx示例页面与Builder.cs等核心实现代码，配合Web.config配置和样式文件，读者可据此理解树枝表的节点渲染、层级展开与数据绑定思路，并借助截图对照运行效果，快速将控件移植到自己的管理后台或分类展示场景中。
1. 树形表格控件：为什么后台系统总绕不开它
做过管理后台的开发者大概都有过这种经历：需求文档上写着“菜单权限树”“组织架构表”“物料分类清单”，产品经理画的原型里，每一行前面带个三角箭头，点一下展开子级，再点一下收起，行与行之间还有缩进和连接线。第一次遇到这种需求，很多人的第一反应是找个现成的表格组件，结果发现普通表格只能平铺数据，树形结构得自己拼。TreeGrid 树枝表控件就是为这个场景准备的：它把“树”的层级关系和“表格”的列对齐能力揉在一起，既能像树一样展开折叠，又能像表格一样按列展示字段、排序、勾选。这份源码包里包含控件本体和可直接运行的 Demo，适合正在做后台系统、需要快速落地树形数据展示的前端开发者，也适合想研究表格控件内部渲染机制、准备二次封装的人。下面从项目定位、目录结构、核心实现一路讲到怎么跑、怎么改。
2. 项目定位与技术选型：一个控件该有的边界
2.1 它解决的是“层级数据 + 多列展示”的交叉需求
普通表格的数据是扁平的，一行就是一条记录；普通树控件能表达层级，但每个节点通常只有一个标题，没法按列对齐展示多个字段。TreeGrid 把两者合在一起，数据模型是树，渲染结果是表格。典型使用场景包括：组织架构里展示部门、负责人、人数、状态四列，部门下挂子部门；权限配置里展示菜单树，每行带菜单名、路由、权限标识、是否启用；物料分类里展示一级分类、二级分类、三级分类，每行带编码和库存数量。这些场景的共同点是：数据天然有父子关系，但每一层需要展示的字段不止一个。控件要做的就是递归遍历树，把每个节点渲染成一行，根据层级计算缩进，同时保证同一列的宽度对齐。
从源码包的结构看，这个项目的定位很明确：它不是一个完整的后台框架，而是一个可独立引入的控件加一套演示页面。控件负责数据解析、行渲染、展开折叠、选中状态维护；Demo 负责展示不同数据形态下的用法，比如静态数据、异步加载、带复选框、带连接线。这种“控件 + Demo”的组织方式对二次开发很友好，你可以先把 Demo 跑起来看效果，再对照源码改自己需要的部分，不用先理解一整个框架。
2.2 技术栈与依赖：轻量是刻意的选择
从源码包的文件构成判断，这个项目走的是轻量路线：核心是一个 JavaScript 控件文件，配套 CSS 样式文件，Demo 页面用原生 HTML 引入，没有绑定任何前端框架。这种选型的理由很实际——树形表格是基础展示组件，如果强依赖某个框架，换项目就得重写；做成原生实现，Vue、React、jQuery 项目都能通过适配层接入。常见做法是控件内部用构造函数或类来组织，对外暴露初始化方法、数据设置方法、展开折叠方法、选中获取方法，事件通过回调或自定义事件抛出。
依赖方面，这类控件通常不引入第三方库，DOM 操作、事件绑定、递归遍历都自己实现。好处是体积小、可控性强；代价是浏览器兼容和边界情况得自己兜。源码里如果出现对classList、querySelector、addEventListener的使用，说明它面向的是现代浏览器；如果用了attachEvent或innerHTML拼接，说明兼容策略偏保守。读源码时先确认这一点，能避免在旧环境里翻车。
2.3 目录结构：先认清每个文件干什么
拿到源码包，第一步不是急着打开 Demo，而是把目录扫一遍。这类项目的典型结构如下：
TreeGrid/ ├── src/ │ ├── treegrid.js # 控件核心：数据解析、渲染、事件 │ ├── treegrid.css # 控件样式：缩进、连接线、展开图标 │ └── utils.js # 工具函数：递归、DOM 操作、数据扁平化 ├── demo/ │ ├── index.html # 基础用法演示 │ ├── async.html # 异步加载子节点演示 │ └── checkbox.html # 复选框与半选状态演示 ├── data/ │ └── sample.json # 演示用树形数据 └── README.md # 引入方式与 API 说明实际文件名可能略有差异，但职责划分基本一致。treegrid.js是阅读重点，通常包含几个关键部分：配置默认值、数据规范化（把不同格式的树数据统一成内部结构）、行渲染（递归生成 DOM）、展开折叠（维护节点状态并更新 DOM）、选中逻辑（父子联动、半选计算）。treegrid.css里最关键的是缩进规则和连接线绘制，很多显示问题都出在这里。demo目录下的页面是最好的“可执行文档”，改一个参数刷新页面就能看到效果，比读 API 文档快。
提示：先跑
demo/index.html，确认控件在当前浏览器能正常渲染，再去看源码。如果 Demo 都跑不起来，优先检查文件路径和浏览器控制台报错，别急着改代码。
3. 核心模块拆解：从数据到 DOM 的完整链路
3.1 数据规范化：把“各种树”统一成一种树
树形数据的来源五花八门：有的用children字段挂子节点，有的用parentId平铺后自己组装，有的子节点字段叫items或nodes。控件如果只认一种格式，接入成本就高。合格的做法是在初始化时做一次规范化，把外部数据转成内部统一的节点结构。常见实现如下：
// 数据规范化：统一子节点字段，补全层级和父节点引用 function normalizeTree(data, options) { const childKey = options.childKey || 'children'; const idKey = options.idKey || 'id'; const parentKey = options.parentKey || 'parentId'; // 情况一：已经是嵌套结构，递归补全 level 和 parent function walk(nodes, level, parent) { return nodes.map(node => { const item = Object.assign({}, node); item._level = level; // 层级，用于计算缩进 item._parent = parent; // 父节点引用，用于向上联动 const children = node[childKey]; if (Array.isArray(children) && children.length) { item[childKey] = walk(children, level + 1, item); } else { item[childKey] = []; item._leaf = true; // 标记叶子节点，决定是否显示展开图标 } return item; }); } // 情况二：平铺数据，先按 parentId 建索引再组装 if (Array.isArray(data) && data.some(n => n[parentKey] !== undefined)) { const map = {}; data.forEach(n => { map[n[idKey]] = Object.assign({}, n, { [childKey]: [] }); }); const roots = []; data.forEach(n => { const node = map[n[idKey]]; if (n[parentKey] && map[n[parentKey]]) { map[n[parentKey]][childKey].push(node); } else { roots.push(node); } }); return walk(roots, 0, null); } return walk(data, 0, null); }这段代码做了三件事：第一，通过childKey、idKey、parentKey三个配置项适配不同数据格式；第二，给每个节点补上_level和_parent，前者用于渲染时计算缩进，后者用于复选框父子联动时向上查找；第三，叶子节点打上_leaf标记，渲染时据此决定是否输出展开图标。参数说明：options.childKey默认children，如果你的接口返回items，初始化时传进去即可；idKey和parentKey用于平铺数据组装，嵌套结构下不生效。这里容易踩的坑是平铺数据里父节点可能排在子节点后面，所以要先建索引再组装，不能边遍历边挂载。
3.2 行渲染：递归生成表格行与缩进
数据规范化之后，渲染的核心是递归遍历，每个节点输出一个<tr>，第一列根据_level计算左内边距，并放置展开折叠图标。简化后的实现如下：
// 行渲染：递归输出 tr，首列带缩进和展开图标 function renderRows(nodes, columns, container) { nodes.forEach(node => { const tr = document.createElement('tr'); tr.dataset.id = node.id; tr.dataset.level = node._level; columns.forEach((col, index) => { const td = document.createElement('td'); if (index === 0) { // 首列：缩进 + 图标 + 文本 td.style.paddingLeft = (node._level * 20 + 8) + 'px'; if (!node._leaf) { const icon = document.createElement('span'); icon.className = 'tg-icon tg-icon-collapsed'; icon.addEventListener('click', () => toggleNode(node, tr)); td.appendChild(icon); } td.appendChild(document.createTextNode(node[col.field] || '')); } else { td.textContent = node[col.field] !== undefined ? node[col.field] : ''; } tr.appendChild(td); }); container.appendChild(tr); // 子节点默认折叠，展开时再渲染或显示 if (node.children && node.children.length) { renderRows(node.children, columns, container); } }); }逻辑说明：columns是列配置数组，每项包含field和title，首列特殊处理，其余列直接取字段值。缩进用paddingLeft实现，_level * 20是每层 20 像素，这个值可以做成配置项。展开图标绑定点击事件，调用toggleNode切换状态。这里有一个性能取舍：上面的写法是一次性把所有层级都渲染出来，靠 CSS 控制子行显示隐藏；数据量大时更常见的做法是懒渲染，只渲染可见行，展开时再插入子节点。源码里如果用了display: none控制折叠，说明走的是前一种路线，优点是展开折叠快，缺点是初始 DOM 多；如果用了动态插入，初始加载快，但频繁展开折叠会有重排开销。读源码时留意这一点，改的时候才知道往哪个方向优化。
3.3 展开折叠与状态维护：别让 DOM 和状态各说各话
展开折叠看起来简单，实际最容易出问题：点了图标行没反应、展开了但图标没变、折叠后子节点的子节点还露着。根因通常是状态只存在 DOM 上，没有独立的节点状态。稳妥的做法是每个节点维护一个_expanded标记，DOM 的显示隐藏由状态驱动：
// 展开折叠：状态驱动 DOM，避免直接操作 display 导致状态不一致 function toggleNode(node, tr) { node._expanded = !node._expanded; const icon = tr.querySelector('.tg-icon'); icon.className = 'tg-icon ' + (node._expanded ? 'tg-icon-expanded' : 'tg-icon-collapsed'); // 找到该节点对应的所有后代行，统一控制显示 const rows = tr.parentNode.querySelectorAll('tr'); let started = false; rows.forEach(row => { if (row === tr) { started = true; return; } if (!started) return; const level = Number(row.dataset.level); if (level <= node._level) { started = false; return; } // 遇到同级或更高级，停止 if (level === node._level + 1) { row.style.display = node._expanded ? '' : 'none'; } // 更深层级：父节点折叠时一并隐藏，展开时保持自身状态 if (!node._expanded) row.style.display = 'none'; }); }这段代码的关键在“遇到同级或更高级就停止”这个判断，它依赖行在 DOM 中的顺序是深度优先的，这也是递归渲染天然保证的。参数上，_level决定缩进和折叠边界，_expanded决定图标状态。常见翻车点是：只隐藏直接子节点，孙节点没处理，折叠后还能看到孙节点；或者展开时把原本折叠的孙节点也强制显示了。上面的写法在折叠时统一隐藏所有后代，展开时只恢复直接子节点，更深层保持各自状态，逻辑上更稳。如果源码用的是给每行加>// 复选框联动：向下全选/全不选，向上计算全选与半选 function syncCheckbox(node, checked) { // 向下：递归设置所有后代 function setDown(n) { n._checked = checked; n._indeterminate = false; (n.children || []).forEach(setDown); } setDown(node); // 向上：从当前节点父级开始，逐级计算 let parent = node._parent; while (parent) { const children = parent.children || []; const allChecked = children.every(c => c._checked); const someChecked = children.some(c => c._checked || c._indeterminate); parent._checked = allChecked; parent._indeterminate = !allChecked && someChecked; parent = parent._parent; } refreshCheckboxDom(); }
逻辑说明：向下递归简单，直接覆盖；向上计算要区分“全选”和“半选”，every判断全选，some判断是否存在选中或半选的后代。refreshCheckboxDom负责把状态同步到 DOM，包括设置checked属性和indeterminate属性。参数上，_checked和_indeterminate是内部状态，对外通过getChecked()返回选中节点 id 数组。这里容易忽略的是初始化：如果数据里自带选中状态，渲染完成后要自底向上跑一遍计算，否则父节点的半选状态不对。另一个坑是异步加载子节点后，父节点的半选状态需要重新计算，不能只在点击时算。
4. 跑起来与改造：从 Demo 到自己的页面
4.1 本地运行：三步看到效果
这类纯前端控件不需要构建工具，最省事的跑法是用静态服务器打开 Demo，避免file://协议下部分浏览器对本地文件读取的限制。步骤：
# 进入项目目录 cd TreeGrid # 起一个静态服务器（任选其一） python3 -m http.server 8080 # 或 npx serve . # 浏览器访问 # http://localhost:8080/demo/index.html打开后应该能看到带展开图标的表格，点击三角箭头能展开子行。如果页面空白，先看控制台：常见报错是treegrid.js路径不对、数据文件 404、或者 CSS 没加载导致图标不显示但行还在。确认 Demo 正常后，再打开demo/async.html看异步加载的写法，打开demo/checkbox.html看复选框联动，这两个页面基本覆盖了实际项目里八成用法。
4.2 接入自己的页面：初始化参数怎么传
把控件接入现有页面，核心是准备好容器、列配置、数据源三样东西，然后调用初始化方法。典型写法：
// 初始化 TreeGrid const grid = new TreeGrid({ el: '#tree-grid', // 容器选择器或 DOM columns: [ { field: 'name', title: '名称', width: 240 }, { field: 'owner', title: '负责人', width: 120 }, { field: 'count', title: '人数', width: 80, align: 'right' }, { field: 'status', title: '状态', width: 100 } ], data: treeData, // 嵌套或平铺数据均可 idKey: 'id', parentKey: 'parentId', // 平铺数据时生效 childKey: 'children', indent: 20, // 每层缩进像素 showCheckbox: true, // 是否显示复选框 defaultExpandLevel: 1, // 默认展开到第几层，-1 全部折叠 onCheck: (checkedIds) => { // 选中变化回调 console.log('当前选中', checkedIds); } });参数说明：el支持选择器字符串和 DOM 元素；columns里align控制列对齐，数值列建议右对齐；defaultExpandLevel是初始化时展开层级的快捷配置，比逐个调用展开方法方便；onCheck在复选框变化时触发，返回当前所有选中节点的 id。接入时最常见的错误是列field和数据字段对不上，导致整列空白，排查时先console.log第一条数据看看字段名。另一个注意点是容器高度：树形表格行数多时需要外层容器设overflow: auto，否则展开后页面被撑得很长。
4.3 异步加载子节点：懒加载的接入点
数据量大或者子节点需要按需请求时，用异步加载。控件通常提供loadData回调或lazy配置，展开某个节点时才去请求子节点：
// 异步加载：展开时请求子节点，加载完成后插入 const grid = new TreeGrid({ el: '#tree-grid', columns: columns, data: rootNodes, // 初始只有根节点 lazy: true, loadData: (node, done) => { fetch('/api/children?parentId=' + node.id) .then(res => res.json()) .then(list => { done(list); // 把子节点交给控件渲染 }) .catch(() => done([])); // 失败也要回调，避免图标一直转 } });逻辑说明：lazy: true告诉控件不要假设节点有子节点，展开时先调loadData；done是回调函数，传入子节点数组后控件负责规范化、渲染、更新图标状态。参数上，node是当前展开的节点对象，done必须调用，哪怕请求失败也要传空数组，否则展开图标会卡在加载态。这里容易踩的坑是重复请求：用户快速点开又收起再点开，可能触发多次请求，常见做法是在节点上打一个_loaded标记，已加载过就直接用缓存。另一个坑是异步加载后父节点的复选框半选状态没重算，需要在done之后手动触发一次向上同步。
4.4 样式改造：缩进线和图标替换
控件默认样式通常比较朴素，接入项目时要改缩进线、图标、行高、选中背景色。缩进线一般用 CSS 伪元素画，或者用背景图平铺。常见做法是给首列单元格加一个左边框，配合paddingLeft形成层级感：
/* 缩进线：用伪元素在首列左侧画竖线 */ .treegrid td:first-child { position: relative; } .treegrid tr[data-level="1"] td:first-child::before, .treegrid tr[data-level="2"] td:first-child::before { content: ''; position: absolute; left: 10px; top: 0; bottom: 0; border-left: 1px dashed #d9d9d9; } /* 展开图标替换：用背景图或字体图标 */ .tg-icon-expanded::before { content: '▾'; } .tg-icon-collapsed::before { content: '▸'; }改样式时注意两点：缩进线的left值要和 JS 里的indent配合，否则线和文字对不齐；图标如果用字体图标，要确认字体文件已加载，否则显示成方块。行高和选中背景色直接覆盖tr和tr.selected即可。如果项目用了 CSS 变量，把主色、边框色抽成变量，换主题时只改变量值，比逐个改选择器省事。
5. 避坑与排查：五个真实场景的翻车记录
5.1 展开后子行错位，缩进对不齐
现象：点击展开，子行出现了，但缩进比预期少一层，或者和父行文字没对齐。原因通常是_level计算错误：平铺数据组装时根节点层级没从 0 开始，或者嵌套数据里某层children是空数组但被当成有子节点，层级多算了一级。解决：在规范化函数里打印每个节点的_level和id，对照数据源确认根节点是 0；空数组统一转成[]并标记_leaf，避免层级虚增。另外检查 CSS 里paddingLeft是否被其他样式覆盖，用开发者工具看计算后的值最直接。
5.2 复选框半选状态不更新
现象：勾选了一个子节点，父节点没有变成半选；或者全部子节点取消后，父节点还是勾选态。原因多半是向上计算只跑了一层，或者异步加载子节点后没有重新计算。解决：确认syncCheckbox里的while循环一直走到根节点；异步done回调之后手动调一次向上同步；初始化时如果数据自带选中状态，渲染完成后自底向上跑一遍全量计算，别只依赖点击事件。
5.3 数据量大时页面卡顿
现象：几千行数据一次性渲染，展开折叠明显延迟，滚动不流畅。原因是一次性生成全部 DOM，节点越多越慢。解决：优先用懒渲染，只渲染可见行，展开时再插入子节点；如果必须全量渲染，折叠时用display: none而不是移除 DOM，减少重排；列数多时避免每行都查 DOM，渲染前把列配置缓存好。另一个容易忽略的点是事件绑定：给每个图标单独绑事件，几千个节点就是几千个监听器，改成事件委托绑在容器上，性能差别很明显。
5.4 异步加载重复请求
现象：快速展开收起同一个节点，网络面板里出现多次相同请求。原因是没有记录加载状态，每次展开都触发loadData。解决：在节点上维护_loading和_loaded两个标记，_loading为真时直接忽略新的展开请求，_loaded为真时直接用已有子节点不再请求；请求失败时把_loading复位，允许重试。这个坑在弱网环境下特别明显，用户手快一点就能复现。
5.5 样式冲突导致图标不显示
现象：Demo 里图标正常，接入项目后三角箭头不见了，或者显示成方块。原因是项目全局样式重置了span::before的content，或者字体图标文件路径不对。解决：给控件样式加命名空间前缀，避免被全局样式命中；图标优先用内联 SVG 或纯 CSS 三角，减少字体文件依赖；用开发者工具检查图标的content计算值，如果是none，说明被覆盖了，提高选择器优先级或换 class 名。
6. 二次开发：把控件改成项目里顺手的样子
二次开发的第一步不是改代码，而是明确改哪一层。这个控件的分层很清楚：数据规范化层负责适配数据格式，渲染层负责 DOM 结构，交互层负责展开折叠和选中，样式层负责视觉。改需求时先对号入座，能少走很多弯路。比如接口返回的字段名和控件默认不一致，只改规范化层的配置项，别去动渲染逻辑；要加一列操作按钮，在列配置里加一个render函数，渲染时判断该列有render就调用它返回 HTML，没有就走默认文本，这样不用改核心渲染循环。
一个具体的改造技巧是给列配置加自定义渲染钩子。很多项目需要在行尾放“编辑”“删除”按钮，或者给状态列加颜色标签。做法是在渲染单元格时判断列配置：
// 列自定义渲染：有 render 用 render，没有走默认 if (typeof col.render === 'function') { td.innerHTML = col.render(node[col.field], node, index); } else { td.textContent = node[col.field] !== undefined ? node[col.field] : ''; }调用方这样写：
{ field: 'status', title: '状态', render: (val) => { const map = { 1: '启用', 0: '停用' }; return '<span class="tag tag-' + val + '">' + (map[val] || '-') + '</span>'; } }这个钩子成本很低，但把展示逻辑从控件里解耦出去了，后续加标签、加按钮、加进度条都不用碰核心文件。验证方法也简单：改完刷新 Demo，看目标列是否按预期渲染，再检查其他列有没有被影响。
第二个值得做的改造是暴露一个refresh方法，数据变更后不用销毁重建整个控件。实现上就是把规范化、渲染、状态恢复串成一个函数，初始化时调一次，外部数据更新后再调一次。注意刷新前要保存当前展开的节点 id 和选中 id，刷新后恢复，否则用户展开到第三层，一刷新全折叠了，体验很差。这个细节在真实项目里经常被忽略，但用户感知很强。
第三个方向是性能。如果项目数据量确实大，把全量渲染改成虚拟滚动是收益最大的改造，但工作量也最大。折中方案是分页加载根节点，子节点懒加载，配合defaultExpandLevel控制初始展开量。我一般会先量一下实际数据规模，几百行以内全量渲染完全够用，没必要提前上虚拟滚动，过度设计反而增加维护成本。
最后说一个我踩过的坑：改控件时直接在生产用的treegrid.js上动刀，改到一半发现影响了另一个页面，回滚又丢了自己的修改。从那以后我每次二次开发都先把控件文件复制一份到项目自己的目录，重命名成带项目前缀的文件，原文件保持不动，改坏了随时对照。另外每次改完渲染逻辑，我都会把三个 Demo 页面挨个点一遍，展开、折叠、勾选、异步加载各走一轮，确认没有回归再提交。这个习惯看着笨，但省下的排查时间远比多点的几下多。希望帮到你。
本文还有配套的精品资源，点击获取
