简介一份面向Web前端开发者的DHTMLX组件示例合集集中演示树形控件、数据网格、日历和分层面板等常用交互模块的用法适合需要在项目中快速搭建后台管理界面、数据看板或日程面板的初中级开发者参考。压缩包共274个文件包含js、css、html示例页面196个gif演示动图39个png界面截图17个db数据文件以及少量xml与bak备份整体仅334KB轻量便于本地运行和阅读。已有235人学习下载。通过这些实例可以了解组件的初始化流程、属性配置、事件响应以及与后端数据源通信的方式还能看到异步加载、编辑排序过滤、日历多视图切换与Grid联动等典型场景遇到相似需求时可直接借鉴参数写法和交互思路。1. Dhtmlx 不是又一个 jQuery 插件tree grid calendar 三个组件能解决什么很多内部管理系统里的复杂交互其实只需要三个组件左侧组织架构树tree中间数据表格grid右上角日期筛选calendar。Dhtmlx 跟 jQuery 时代那些只封装外观的插件不同它自带数据引擎、事件系统和渲染管线能把这三样东西直接接上后端数据。按这份「用Dhtmlx做的例子」里的写法复现一遍你会发现表格排序、树形懒加载、日期范围校验这些反复折腾人的需求都能在几百行内落地。适合负责后台管理系统的前端开发者也适合接了内部项目但不熟悉 dhtmlx 的团队拿来当骨架。2. 先把第一个页面跑起来初始化顺序、版本选型与 license 边界拿到例子第一件事是确认版本而不是改代码。dhtmlx 老版本和现代版本接口差异大到像两个产品这一步错了后面全是白屏。2.1 版本选型老 API 与现代 API 怎么区分dhtmlx 老版本5.x 之前的构造函数通常以 dhtmlX 开头比如 dhtmlXGridObject、dhtmlXTreeObject、dhtmlXCalendarObject。6.x 之后改为 dhx.Grid、dhx.Tree、dhx.Calendar。两种写法加载的文件不同不能混用。判断依据很简单打开例子的 JS 文件搜索 new dhtmlX 或 new dhx.。看到前者就用 GPL 源码包里的 dhtmlx.js 与 dhtmlx.css看到后者就去对应组件包里引入 dhx/tree、dhx/grid、dhx/calendar。如果例子里两种混合出现说明这份资源整合过多个来源按报错处的上下文单独替换对应组件文件即可。提示GPL 版本的免费使用边界以开源协议条款为准商业闭源项目要购买商业授权使用前先确认这一点避免开发到一半换库。2.2 最小页面模板先 DOM 后脚本初始化 dhtmlx 组件有一个硬性顺序问题容器 div 必须已经出现在 DOM 里才能在它内部渲染组件。把这个顺序写错是新手最常见的问题我一般把脚本放在容器 div 之后或者用 window.onload 包裹。!DOCTYPE html html head link relstylesheet hrefdhtmlx.css script srcdhtmlx.js/script /head body div idgridBox stylewidth:600px;height:300px;/div div idtreeBox stylewidth:200px;height:300px;/div script // DOM 渲染完成后再初始化 var grid new dhtmlXGridObject(gridBox); grid.setHeader(姓名,部门,入职日期); grid.setColTypes(ro,ro,date); grid.setInitWidths(120,100,120); grid.init(); var tree new dhtmlXTreeObject(treeBox, 100%, 100%, 0); tree.loadJSON(org.json); /script /body /html逻辑说明grid 的初始化由 setHeader 列名、setColTypes 列类型、setInitWidths 列宽三组配置加 init() 构成。tree 的第四个参数 0 表示不显示根节点直接把最上层数据当根渲染。参数说明setColTypes 里的 ro 是只读列ed 是文本可编辑date 是日期列ch 是复选框列。列类型决定组件的行为边界比如 date 列在排序时按时间排字符串列就按字典序排。这里也提醒一下资源检索时的拼写问题dhtmlx 的表格组件是 Grid很多人把 grid 记成 gird在搜索框里打出来的结果完全不同。如果你搜不到对应文档先检查是不是这个词拼错了。2.3 引入方式CSS 丢了是最高频的翻车现场老版本引入方式很简单一个 dhtmlx.js 加一个 dhtmlx.css 就覆盖全部组件。新版本改成按组件拆包每个包都要引入自己的 CSS 和 JS。这份例子如果是打包下载的一般目录里会有组件对应的 css 文件和 js 文件。实际排查时最常见问题是JS 引入成功CSS 漏引。现象是表格能渲染出数据行但表头样式丢了列宽也塌。检查顺序我先看 href 路径相对当前页面是否正确再看控制台的 404最后才怀疑业务代码。CSS 漏引还会造成日历弹层错位、树节点图标不显示遇到这类奇奇怪怪的样式问题第一反应应该是检查样式表而不是逻辑。排查时可以用浏览器开发者工具的网络面板刷新页面看 css 请求状态码。如果是 404优先检查路径大小写dhtmlx 的文件名通常是全小写多一个空格都不行。路径确认无误后再检查引入顺序先引 css后引 js样式表放后面会覆盖组件默认主题导致皮肤显示异常。3. Tree 与 Grid 联动实战树表数据绑定与事件转发树和表格的联动是这份例子的重头戏。拆开看每个组件本身不难难点在数据结构和事件转发。3.1 Tree 数据格式嵌套结构、parseJSON 与懒加载dhtmlxTree 老版本的数据源支持 XML 和 JSON。我最常用的方式是 parseJSON 直接传内存对象省去一次请求。var tree new dhtmlXTreeObject(treeBox, 100%, 100%, 0); tree.parseJSON([ { id: dept1, text: 研发部, child: [ { id: team11, text: 前端组 }, { id: team12, text: 后端组 } ]}, { id: dept2, text: 产品部, child: [] } ]);逻辑说明child 是子节点数组text 是节点显示名id 是节点唯一标识。parseJSON 执行后组件内部自动生成树形结构并渲染。id 唯一性是这份例子没过细说但很关键的约束。懒加载场景下子节点的 id 如果与父节点或其他兄弟节点重复展开后 DOM 会同时出现两个 id 相同的节点tree.getAllChildNodes 这类方法返回的数据就会错乱。懒加载的标准做法是通过 onOpenStart 事件判断父节点是否加载过。组件提供了 getUserData / setUserData 来挂自定义标记我用这个标记避免重复请求tree.attachEvent(onOpenStart, function(id) { if (tree.getUserData(id, loaded)) return; fetch(/api/children?pid id) .then(function(res) { return res.json(); }) .then(function(list) { list.forEach(function(item) { tree.insertNewItem(id, item.id, item.text); }); tree.setUserData(id, loaded, 1); }); });逻辑说明onOpenStart 在父节点展开动作开始时触发拿到节点 id如果还没加载过发请求拿子节点列表然后 insertNewItem 逐个插入。setUserData 打上 loaded 标记后下次展开同一节点就不会重复请求。参数说明insertNewItem 的参数顺序是父节点 id、新节点 id、显示文本如果漏了第二个参数组件会返回 undefined 并可能在渲染时把新节点挂到根上。踩过这个坑的人不少。3.2 Grid 列配置setColTypes 决定行为边界表格组件的列配置集中在 init() 之前的几行代码里。我把列类型这块单独讲因为它直接决定表格能不能编辑、排序是否按日期、复选框是否可点击。var grid new dhtmlXGridObject(gridBox); grid.setHeader(工号,姓名,入职日期,在职); grid.setColTypes(ed,ro,date,ch); grid.setInitWidths(70,100,120,60); grid.setSkin(modern); grid.init(); grid.parse([ [NO001, 张三, 2023-04-12, 1], [NO002, 李四, 2022-11-03, 0] ], array);逻辑说明setHeader 定义四列setColTypes 逐个指定行为setInitWidths 指定列初始宽度。setSkin 要在 init 之前设置否则皮肤不生效。parse 传入二维数组第二参数 array 告诉组件按数组格式解析。参数说明ed 是文本编辑列ch 是复选框列date 是日期列ro 是只读列。日期列如果用 ro那它不参与编辑但排序仍按时间。复选框列的值 1 表示选中、0 表示未选中取数据时也是这两个数字需要展示文本时再用 format 回调转换。init() 之后再修改列配置不会自动刷新这是 dhtmlx 表格又一个顺序约束。项目中如果遇到「列加了但不显示」可以先想想是不是在 init 之后调用了 setHeader。此时应该先销毁实例再重建或者调用 grid.setColumnsAutoSize(true) 这类重建类方法。3.3 树选节点驱动表格刷新事件转发的正确姿势两个组件的联动核心是事件转发树节点点击时拿节点 id 去查数据然后刷表格。tree.attachEvent(onClick, function(nodeId) { var rows queryRowsByDept(nodeId); // 返回二维数组 grid.clearAll(); grid.parse(rows, array); });逻辑说明onClick 事件携带被点击节点的 id。这里把 id 当作部门编码查出对应员工列表clearAll 清空旧数据后重新 parse。快速点击时会出现多次请求并发响应乱序的问题旧请求比新请求晚返回表格显示的数据和当前选中节点对不上。我在例子里加一个 loading 状态锁var gridLoading false; tree.attachEvent(onClick, function(nodeId) { if (gridLoading) return; gridLoading true; queryRowsByDept(nodeId).then(function(rows) { grid.clearAll(); grid.parse(rows, array); gridLoading false; }); });逻辑说明gridLoading 为 true 时忽略新的点击事件相当于把异步请求串行化。代价是快速切换节点时部分点击会被丢弃但对内部管理系统来说丢失中间态比数据错乱更可接受。更细的优化是记录最后点击的节点请求返回后再比对一次节点 id不一致就丢弃旧响应这样可以保证最终状态正确。4. Calendar 日期组件的正确打开方式格式化、范围约束与表单联动日历组件看似简单最容易出差错的却恰恰是日期格式和时区。这一章按初始化、范围约束、表单集成三个层次拆开。4.1 Calendar 初始化与日期格式占位符日历组件初始化的核心参数是日期格式。dhtmlx 旧版使用 %Y-%m-%d 这套 strftime 风格占位符初看很像但跟常见的 dayjs 格式约定完全不同。var startCal new dhtmlXCalendarObject(startCal); startCal.setDateFormat(%Y-%m-%d %H:%i); startCal.hideTime();逻辑说明dhtmlXCalendarObject 可以直接挂在 input 元素上点击后弹出日历。setDateFormat 控制选中后写入 input 的字符串格式。hideTime 表示不显示时间选择区只选日期。参数说明%Y 四位年、%m 两位月、%d 两位日、%H 小时、%i 分钟。注意分钟是 %i 不是 %M%M 在部分版本里是月份的另一种表示用错会出现「分钟永远显示 0」的怪问题。这一点最好在写例子时就把格式常量提取出来避免到处魔法字符串。4.2 日期范围限制setRanges 与 onChange 的配合日期范围限制最常见的需求是结束日期不能早于开始日期。通过两个日历组件联动实现核心方法是 setRangesvar startCal new dhtmlXCalendarObject(startInput); var endCal new dhtmlXCalendarObject(endInput); startCal.setDateFormat(%Y-%m-%d); endCal.setDateFormat(%Y-%m-%d); startCal.attachEvent(onChange, function(date) { var d new Date(date.getFullYear(), date.getMonth(), date.getDate()); endCal.setRanges(d, null); // 可选范围从 d 开始无上限 });逻辑说明start 日历变化时把 end 日历的最小可选日期设置为所选日期。这里重新构造了一个本地零点时间对象而不是直接把 date 传进去就是为了避开时区偏移导致结束日期差一天的问题。需要注意的一点setRanges 只影响图形界面上可点击的日期如果用户直接在输入框里手动输入一个早于开始日期的值组件默认是不拦截的。要做强校验还得在提交表单时再比较一次字符串。function validateRange(startStr, endStr) { if (!startStr || !endStr) return 日期不能为空; if (startStr endStr) return 结束日期不能早于开始日期; return ; }逻辑说明ISO 格式的日期字符串可以直接用字符串比较因为 %Y-%m-%d 从年、月、日逐位对齐字典序等价于时间先后顺序。这个小技巧能省掉三次 Date 解析也避免了时区再次介入。4.3 日历与表单提交联动日历最终要落到表单提交上。把日历与 input 关联后input 的 value 已经按统一格式写好了提交时只需要校验和拼参。function buildQuery() { var start document.getElementById(startInput).value; var end document.getElementById(endInput).value; var err validateRange(start, end); if (err) { alert(err); return; } var params new URLSearchParams({ start: start, end: end, source: grid-demo }); return /api/export? params.toString(); }逻辑说明URLSearchParams 负责转义特殊字符比手拼字符串安全。source 参数用来标识请求来源方便接口侧做统计或缓存。如果后端还有分页需求可以把页码和每页大小也拼进同一个 params 对象保持查询参数统一管理。5. 避坑记录版本混用、样式失效、日期差一天等五个高频事故这一章每一条都是从实际跑过的现象里提炼的按现象、原因、解决的顺序列清楚。5.1 老 API 混入新包直接白屏现象加载页面后树和表格区域一片空白控制台报 new dhtmlXGridObject is not a constructor。原因页面引入了 6.x 之后的组件包但示例代码还是 5.x 时期的 dhtmlX 写法。现代包里不存在这个构造函数执行直接中断所有组件都渲染不出来。解决先全局搜索代码里的 new dhtmlX 与 new dhx. 两个关键字grep -rn new dhtmlX\|new dhx\. src/统计哪个占多数再决定引入对应版本的 dhtmlx.js 或 dhx 组件包。如果页面需要混用多个来源的代码把旧代码整体迁移到新 API 的成本较高建议统一成新写法。5.2 表格列宽对不齐现象表格数据行和表头错位设置了 setInitWidths 也没有用。原因容器在初始化后尺寸发生变化或者皮肤切换导致列宽重新计算组件没有感知到。解决在页面布局稳定后调用 grid.setSizes() 强制重算列宽。如果换了皮肤先调用 grid.setSkin(modern) 再调用 grid.setSizes()。列宽参数注意单位是像素不要和百分比混用。如果表格所在容器使用了 flex 或流式布局最好监听容器的 resize 事件在尺寸变化后补一次 setSizes。5.3 日期回调差一天现象日历里选了 2023-04-12onChange 里打出来的对象转成字符串后变成 2023-04-11。原因Date 对象在转字符串时经历了统一标准时间的转换东八区环境下时间会被减去 8 小时再按页面时区显示就会跳到前一天。解决在回调里不要直接 toString 或 toISOString而是用 getFullYear、getMonth、getDate 重新组装本地日期。之前 4.2 小节里的零点构造方法就是为这个问题写的统一放到一个 toLocalDate 工具函数里复用。5.4 中文乱码现象表格和树里中文都显示成问号。原因页面或数据文件没有声明 utf-8老版 XML 数据尤其容易出现XML 头里缺 encoding 声明就会按平台默认编码解析。解决HTML 里加 meta charsetutf-8XML 第一行声明 encodingutf-8。用 fetch 加载数据时优先拿到文本再统一转fetch(data.xml) .then(function(res) { return res.text(); }) .then(function(xmlText) { grid.loadXMLString(xmlText); });先拿文本再由组件解析可以绕过浏览器自动探测编码带来的乱码问题。5.5 组件销毁不彻底越切越卡现象单页应用里切换页面再回来内存只增不减页面响应越来越慢。原因页面离开时只隐藏了容器 div没有调用组件销毁方法树和表格的事件监听还挂在旧节点上反复进出就堆积了多个实例。解决页面清理阶段先调 grid.destructor()、tree.destructor() 释放事件再移除 DOM 节点。统一封装一个 destroyAll 方法在所有带 dhtmlx 组件的页面里复用function destroyAll() { if (grid) { grid.destructor(); grid null; } if (tree) { tree.destructor(); tree null; } if (startCal) { startCal.destructor(); startCal null; } }逻辑说明destructor 是组件自带的内存释放入口调用后事件监听和 DOM 引用会一并清理。置空变量是为了防止后续代码在页面缓存里误用到旧实例。6. 把三个组件串成一条事件总线少写一半回调代码dhtmlx 每个组件都有一套 attachEvent 方法事件越多回调越散。我习惯用一个极简的事件总线把三个组件的事件统一收集起来状态变化都通过总线分发。6.1 迷你事件总线实现var bus { handlers: {}, on: function(evt, fn) { (this.handlers[evt] this.handlers[evt] || []).push(fn); }, emit: function(evt, payload) { (this.handlers[evt] || []).forEach(function(fn) { fn(payload); }); } };逻辑说明on 注册事件emit 触发事件。它不依赖 dhtmlx任何版本都能用。注册时把事件名和回调存进 handlers触发时遍历执行。这个小工具几十行比引入事件库省事得多。6.2 改造联动逻辑树和日历的事件不再各自直接操作 grid而是先 emit 到总线再由统一的地方去响应。tree.attachEvent(onClick, function(id) { bus.emit(dept:selected, id); }); startCal.attachEvent(onChange, function(date) { bus.emit(range:change, { start: date }); }); bus.on(dept:selected, function(deptId) { loadGridData(deptId); }); bus.on(range:change, function(range) { loadGridData(currentDeptId, range.start); });逻辑说明事件源只负责发事件消费方只负责接事件组件之间不再互相引用。以后要加「部门选中后同时联动面板标题、面包屑、统计数字」只需要在总线里多挂两个回调不用改动树组件的初始化代码。这套做法帮我把这个例子里三个组件之间互相引用的循环依赖拆干净了。有一次我直接在树的事件里调用 grid又在 grid 的事件里改树的状态调试到凌晨都没定位清楚后来把事件全部改成总线转发十分钟就理清了链路。从那以后我每次接 dhtmlx 组件都强制先把所有 attachEvent 列一张表统一挂到总线上再写业务逻辑。希望帮到你。本文还有配套的精品资源点击获取
