T+二开级联自由项：JS扩展实现多级联动的低代码方案

简介本资源是面向T二次开发工程师的级联自由项实战解决方案聚焦中小企业销售订单等业务场景中多级联动字段的动态控制需求通过JS前端扩展与.NET后端自定义服务协同实现适合具备基础JavaScript和C#开发能力的中高级开发者快速落地个性化配置。压缩包共86个文件含14个核心C#源码文件如SaleOrderFreeItemCascadeAction.cs、SA03ExtendService.cs、34个运行依赖DLL、2个详细文档需求说明与V16开发教程、1个实操视频T级联自由项.mp4及1个完整Visual Studio解决方案Ufida.T.HY.sln整体281.08MB结构清晰覆盖前后端全链路代码与部署说明。目前已有417人学习下载读者可直接复用工程结构、参考级联逻辑实现细节、调试图文并茂的开发流程并基于提供的JS脚本与自定义服务接口快速适配其他单据类型。1. T二开级联自由项一个被低估的“低代码缝合术”让销售单据多级联动像配置表一样简单你有没有遇到过这种场景客户在T系统里录销售订单选完“产品大类”后“品牌”下拉框要自动过滤出该大类下的品牌再选完“品牌”“系列型号”才动态加载对应数据——但T标准功能只支持单层自由项二级联动得靠写SQL查表、拼JS事件、改单据模板、甚至动服务端接口。某公司上线时硬是让开发手写三套不同逻辑的JS结果U8迁移过来的客户一换浏览器就报错连自由项下拉箭头都点不开。这个「T二开 级联自由项(极简扩展方法)」项目就是为解决这类高频、高频、又高频的“小需求”而生的它不碰数据库结构、不改T核心服务、不依赖插件平台仅用一份可复用的JS扩展 一张配置表就把三级自由项联动压缩成3个字段定义 2次点击就能生效。适合所有正在做T二次开发的实施顾问、交付工程师、以及被客户临时加需求追着跑的外包开发者——尤其当你手头只有T7.0~13.0任意版本、没权限部署独立服务、又不想每次改个联动都提单等IT排期时这套方案就是你的后悔药。2. 架构设计与技术选型为什么是JS扩展 配置表而不是自定义服务或插件2.1 核心约束倒推架构T二开的“三不原则”T平台对二次开发有明确边界不许修改bin目录下DLL、不许注册全局HTTP服务、不许在单据模板中嵌入外部CDN脚本。这意味着常见方案如“写WebAPI供JS调用”或“用Vue重写自由项组件”直接出局。我们只能在T允许的沙箱内做事——而T唯一开放且稳定的入口就是其单据模板中的script标签区以及它预留的window.TPlusExtend扩展机制。所以本项目采用“双轻量”设计前端轻量所有联动逻辑封装为纯JS模块通过T标准onLoad/onChange钩子注入不依赖jQuery或任何第三方库T自带$是阉割版连$.ajax都不全数据轻量联动关系不写死在JS里而是存于一张独立的T_Ext_CascadeConfig基础资料表建表SQL随包提供字段仅5个ID,ParentField,ChildField,FilterSQL,OrderNo。比如“大类→品牌”这条规则ParentFieldcFree1,ChildFieldcFree2,FilterSQLSELECT cCode,cName FROM v_Brand WHERE cBigClass{cFree1}。提示T的自由项字段名固定为cFree1~cFree10这是T底层约定不是我们自定义的。所有联动必须基于这个命名体系否则JS无法绑定事件。2.2 JS扩展模块分层从入口到执行的四层职责整个JS扩展按职责拆为4个文件均位于/Ext/Cascade/目录下文件名职责关键能力main.js入口加载器检测当前单据类型销售订单/采购入库等、动态加载对应规则、注册全局window.CascadeManagerloader.js规则加载器从T_Ext_CascadeConfig表查出当前单据适用的全部级联规则缓存为内存对象避免重复查询executor.js执行引擎监听cFree1~cFree10字段change事件解析FilterSQL中的占位符如{cFree1}拼接真实SQL调用T内置TPlus.Ajax执行并刷新下级下拉renderer.js渲染适配器适配T不同版本的下拉控件DOM结构T10.0用selectT12.0改用divulli模拟下拉统一调用setOptions()方法这种分层不是炫技——而是为了应对T版本碎片化。某导师曾在一个项目里同时要兼容T9.0IE8内核、T11.0Chromium 49、T13.0Chromium 80DOM操作方式天差地别。把渲染逻辑抽出来升级时只需改renderer.js其他三层完全不动。2.3 为什么不用“自定义服务”一次血泪经验告诉你有开发者问“既然能写JS为啥不干脆写个自定义服务用REST API返回JSON”——这问题背后是典型认知偏差。T的“自定义服务”本质是IIS托管的ASP.NET WebService.asmx需IT在服务器上部署、配置IIS应用池、开放端口、处理跨域。而本项目客户现场是制造业私有云防火墙策略严禁新增HTTP服务端口且IT部门拒绝为“一个下拉联动”走月度安全评审流程。更致命的是T单据JS运行在客户端调用自定义服务需跨域而T内置的TPlus.Ajax根本不支持withCredentials连Cookie都传不过去身份认证直接失败。所以本项目坚持“数据查本地”所有FilterSQL都在T数据库内执行由T服务端代劳JS只负责发请求和收结果。这才是真正落地的妥协。3. 运行环境准备与初始化5分钟完成T单据级联联动3.1 基础环境检查清单缺一不可在动手前请确认以下6项已就绪。少一项后续90%的问题都源于此✅ T版本 ≥ 7.0验证方式登录T右下角查看“版本号”7.0起支持TPlusExtend机制✅ 数据库为SQL Server本方案不支持MySQL或Oracle后端因FilterSQL依赖T-SQL语法如TOP 100✅ 当前用户有T_Ext_CascadeConfig表读取权限默认建表时已设GRANT SELECT ON T_Ext_CascadeConfig TO public✅ 单据模板已启用“允许执行JavaScript”路径基础设置 → 单据设置 → 找到目标单据 → 勾选“启用脚本”✅ 浏览器为Chrome 80 或 Edge ChromiumT12.0已弃用IE内核旧版JS语法如const/fetch可直接用✅ 无其他JS扩展冲突如某竞品“智能填单”插件会劫持onChange事件需先禁用注意T单据脚本执行顺序是“先加载模板HTML再执行JS”因此所有DOM操作必须包裹在$(document).ready()或window.onload中否则getElementById(cFree1)会返回null。3.2 部署四步法从解压到生效步骤1建表并初始化配置执行随包提供的Create_CascadeConfig.sql位于/DB/目录-- 创建级联配置表T标准数据库内执行 IF NOT EXISTS (SELECT * FROM sysobjects WHERE nameT_Ext_CascadeConfig AND xtypeU) CREATE TABLE T_Ext_CascadeConfig ( ID INT IDENTITY(1,1) PRIMARY KEY, ParentField NVARCHAR(20) NOT NULL, -- 上级自由项字段名如cFree1 ChildField NVARCHAR(20) NOT NULL, -- 下级自由项字段名如cFree2 FilterSQL NVARCHAR(MAX) NOT NULL, -- 查询SQL支持{cFree1}占位符 OrderNo INT DEFAULT 0, -- 同级联动执行顺序数字越小越先执行 BillType NVARCHAR(50) DEFAULT -- 单据类型码留空表示通用填SaleOrder仅用于销售订单 ) -- 插入一条示例大类→品牌联动 INSERT INTO T_Ext_CascadeConfig (ParentField, ChildField, FilterSQL, BillType) VALUES (cFree1, cFree2, SELECT TOP 100 cCode AS Value, cName AS Text FROM v_Brand WHERE cBigClass{cFree1} ORDER BY cCode, SaleOrder)执行后在SQL Server Management Studio中查SELECT * FROM T_Ext_CascadeConfig确认数据已写入。步骤2上传JS文件到T资源目录将/Ext/Cascade/目录下全部JS文件共4个通过T后台“系统管理 → 系统工具 → 文件管理”上传至路径/TPlus/Ext/Cascade/注意必须是这个路径T脚本中硬编码了相对路径上传后访问http://your-tplus-server/TPlus/Ext/Cascade/main.js应能直接下载文件否则路径错误。步骤3在单据模板中注入入口脚本打开目标单据如销售订单的模板设计界面基础设置 → 单据设置 → 销售订单 → 设计模板在HTML源码末尾/body前插入!-- T级联自由项扩展入口 -- script typetext/javascript src/TPlus/Ext/Cascade/main.js/script script typetext/javascript // 初始化级联管理器传入当前单据类型码 window.CascadeManager.init(SaleOrder); /script保存模板并发布。关键点init(SaleOrder)中的参数必须与T_Ext_CascadeConfig.BillType值严格一致大小写敏感。步骤4验证联动是否生效新建一张销售订单进入表体行在“自由项1”下拉中选择一个“产品大类”如“工业泵”焦点离开cFree1后观察“自由项2”下拉框是否自动刷新且选项仅为“工业泵”下的品牌如“格兰富”“威乐”若未刷新按F12打开浏览器控制台切换到Console页输入window.CascadeManager.debug true再操作一次看是否有SQL执行日志或错误堆栈。4. 避坑指南T级联自由项开发中踩过的5个真实坑4.1 现象自由项下拉框空白控制台报Cannot read property setOptions of null原因T不同版本对自由项控件的DOM生成时机不同。T10.0在页面加载时就渲染select idcFree2而T12.0采用懒加载直到用户第一次点击下拉才生成DOM节点。JS执行时document.getElementById(cFree2)返回null后续调用setOptions()自然报错。解决在renderer.js中增加DOM等待逻辑不依赖document.ready而是轮询检测// renderer.js 中的 getSelectElement 方法 function getSelectElement(fieldName) { let el document.getElementById(fieldName); if (el) return el; // T12.0自由项DOM可能未生成最多等待3秒 return new Promise((resolve) { let tries 0; const timer setInterval(() { el document.getElementById(fieldName); if (el || tries 30) { clearInterval(timer); resolve(el); } tries; }, 100); }); }4.2 现象FilterSQL中{cFree1}占位符未被替换SQL执行报错“cFree1 不是有效的列名”原因T单据中自由项字段值并非直接存在document.getElementById(cFree1).value中。对于下拉类型真实值存在TPlus.Data.getBillData().getDetailRows()[0].cFree1表体第一行而文本类型才在DOM中。JS扩展若直接读DOM拿到的是显示文本如“工业泵”而非编码值如“GP-001”导致SQL中WHERE cBigClass工业泵查不到数据。解决统一从T数据模型中取值executor.js中替换逻辑改为// executor.js 中的 replacePlaceholders 方法 function replacePlaceholders(sql, rowData) { // rowData 来自 TPlus.Data.getBillData().getDetailRows()[0] return sql.replace(/\{(\w)\}/g, (match, fieldName) { // 优先从rowData取值编码值fallback到DOM显示值 const value rowData[fieldName] || (document.getElementById(fieldName) document.getElementById(fieldName).value) || ; return value.replace(//g, ); // SQL转义单引号 }); }4.3 现象级联触发两次下拉框闪退后重载选项重复出现原因T自身会对自由项字段绑定change事件用于校验、计算等我们的JS又额外绑定一次导致事件冒泡触发两次。尤其当cFree1是必填项时T校验失败会重置字段再次触发change形成死循环。解决使用事件委托 防抖并在触发前检查字段值是否真变化// executor.js 中的 bindCascadeEvent 方法 function bindCascadeEvent(fieldName) { const field document.getElementById(fieldName); if (!field) return; let lastValue field.value; field.addEventListener(change, function() { if (this.value lastValue) return; // 值未变不触发 lastValue this.value; // 防抖100ms内只执行最后一次 clearTimeout(window.cascadeDebounceTimer); window.cascadeDebounceTimer setTimeout(() { executeCascade(fieldName, this.value); }, 100); }); }4.4 现象T13.0中TPlus.Ajax调用返回undefined控制台无报错原因T13.0升级了AJAX底层TPlus.Ajax不再返回Promise而是要求传入success/error回调函数。旧版写法TPlus.Ajax({...}).then(...)直接失效。解决在executor.js中做版本兼容判断// executor.js 中的 executeAjax 方法 function executeAjax(sql, successCb, errorCb) { if (typeof TPlus.Ajax function TPlus.Ajax.toString().includes(success)) { // T13.0回调函数式 TPlus.Ajax({ url: /TPlus/Services/QueryService.asmx/ExecuteQuery, data: { sql: sql }, success: successCb, error: errorCb }); } else { // T12.0及以下Promise式保留旧逻辑 TPlus.Ajax({ url: /TPlus/Services/QueryService.asmx/ExecuteQuery, data: { sql: sql } }).then(successCb).catch(errorCb); } }4.5 现象配置了BillTypeSaleOrder但在采购入库单中也触发了联动原因window.CascadeManager.init(SaleOrder)只是告诉JS“当前单据类型”但loader.js加载规则时SQL查询未严格按BillType过滤。原查询为SELECT * FROM T_Ext_CascadeConfig WHERE ParentField?漏掉了AND (BillType OR BillType?)条件。解决修正loader.js中的查询SQL// loader.js 中的 loadRules 方法 function loadRules(billType) { const sql SELECT * FROM T_Ext_CascadeConfig WHERE ParentField IN (cFree1,cFree2,cFree3,cFree4,cFree5) AND (BillType OR BillType ${billType}) ORDER BY OrderNo; return TPlus.Ajax({ url: /TPlus/Services/QueryService.asmx/ExecuteQuery, data: { sql } }); }5. 核心代码逐行解析executor.js如何把一行SQL变成一次联动5.1 入口函数executeCascade(parentField, parentValue)联动的总开关这是整个级联逻辑的起点被bindCascadeEvent在用户选择上级自由项后调用。它接收两个参数parentField如cFree1是触发联动的字段名parentValue是用户选中的值编码值非显示文本。函数目标找出所有以该字段为ParentField的规则依次执行下级查询并刷新DOM。// executor.js function executeCascade(parentField, parentValue) { // 1. 从内存缓存中获取所有匹配规则loader.js 已预加载 const rules window.CascadeManager.rules.filter(rule rule.ParentField parentField); // 2. 遍历每条规则逐级执行 rules.forEach(rule { // 2.1 构造带真实值的SQL将 {cFree1} 替换为 parentValue const filledSql replacePlaceholders(rule.FilterSQL, { [parentField]: parentValue }); // 2.2 执行SQL查询获取下级选项数据 executeAjax(filledSql, (data) { // success // 2.3 解析返回的JSONT QueryService 返回 {d: [{...}] } 格式 const rows JSON.parse(data.d); // 2.4 刷新下级自由项下拉框 refreshDropdown(rule.ChildField, rows); }, (err) { // error console.error(级联执行失败 [${rule.ParentField}→${rule.ChildField}]:, err); alert(下级数据加载失败${err.message || 未知错误}); } ); }); }参数说明parentField字符串必须是cFree1~cFree10之一T自由项字段名规范parentValue字符串来自T数据模型的编码值如GP-001非UI显示值如格兰富这是正确关联的关键rule.FilterSQL配置表中存储的SQL模板支持多个占位符如{cFree1}和{cFree2}replacePlaceholders会全部替换。5.2 占位符替换函数replacePlaceholders(sql, rowData)SQL模板的“变量注入器”T单据数据是树形结构主表数据TPlus.Data.getBillData().getMainRow()和表体数据TPlus.Data.getBillData().getDetailRows()。级联常发生在表体行所以rowData通常指表体某一行对象。此函数负责将SQL中所有{fieldName}替换成对应字段的真实值并做SQL安全转义。function replacePlaceholders(sql, rowData) { return sql.replace(/\{(\w)\}/g, (match, fieldName) { // 优先从传入的 rowData 取值最准 let value rowData[fieldName]; // 若 rowData 无此字段尝试从主表数据取如单据头信息 if (value undefined || value null) { const mainRow TPlus.Data.getBillData().getMainRow(); value mainRow ? mainRow[fieldName] : ; } // 若仍为空从DOM取兜底仅用于文本型自由项 if (!value document.getElementById(fieldName)) { value document.getElementById(fieldName).value; } // 强制转为字符串并转义单引号防止SQL注入 value String(value || ).replace(//g, ); return value; }); }关键细节正则/\{(\w)\}/g匹配所有{xxx}格式g标志确保全局替换一条SQL可有多个占位符rowData[fieldName]是首选因为T自由项的编码值cCode只存在数据模型中DOM里是显示值cName.replace(//g, )是T-SQL标准转义双单引号表示字面单引号比\转义更安全。5.3 下拉框刷新函数refreshDropdown(childField, options)适配T所有版本的DOM手术T不同版本渲染自由项下拉的方式差异极大T9.0~10.0标准select idcFree2option valueGP-001格兰富/option/selectT11.0div classtplus-select>function refreshDropdown(childField, options) { const fieldEl document.getElementById(childField); if (!fieldEl) return; // 步骤1清空现有选项 if (fieldEl.tagName SELECT) { // T10.0及以下直接清空select fieldEl.innerHTML ; } else { // T11.0调用T官方Select组件的clear方法 const selectObj TPlus.UI.Select.getInstance(childField); if (selectObj typeof selectObj.clear function) { selectObj.clear(); } } // 步骤2添加新选项 if (fieldEl.tagName SELECT) { // 标准select创建option元素 options.forEach(row { const opt document.createElement(option); opt.value row.Value || row.cCode || ; opt.text row.Text || row.cName || ; fieldEl.appendChild(opt); }); } else { // T11.0调用setOptions传入数组 const selectObj TPlus.UI.Select.getInstance(childField); if (selectObj typeof selectObj.setOptions function) { const formattedOptions options.map(row ({ value: row.Value || row.cCode || , text: row.Text || row.cName || })); selectObj.setOptions(formattedOptions); } } }为什么不用innerHTML批量写入因为T11.0的Select组件会监听DOM变化手动innerHTML会破坏其内部状态导致点击无反应。必须走setOptions()官方API。6. 二次开发实战从三级联动扩展到动态表单一个技巧搞定N个新需求6.1 场景升级客户提出“选完型号要自动带出该型号的默认供应商和结算方式”这已超出传统级联范畴——它不是下拉选项联动而是要自动填充其他字段如cVenCode供应商编码、cSettleStyle结算方式。但你会发现executor.js的executeCascade函数其实早已预留了扩展点它执行完SQL后data是完整的JSON数组rows[0]就包含该型号的所有属性。我们只需在success回调里加几行赋值代码// 在 executor.js 的 executeCascade 函数内success 回调中追加 success: (data) { const rows JSON.parse(data.d); if (rows.length 0) { const firstRow rows[0]; // 【新增】自动填充其他字段 if (firstRow.cVenCode) { // 设置供应商编码T标准字段 TPlus.Data.getBillData().getDetailRows()[0].cVenCode firstRow.cVenCode; // 触发T重新渲染该字段否则UI不更新 TPlus.UI.RefreshField(cVenCode); } if (firstRow.cSettleStyle) { TPlus.Data.getBillData().getDetailRows()[0].cSettleStyle firstRow.cSettleStyle; TPlus.UI.RefreshField(cSettleStyle); } } // 原有逻辑刷新下级下拉框 refreshDropdown(rule.ChildField, rows); }关键点TPlus.Data.getBillData().getDetailRows()[0]获取表体第一行数据对象直接赋值即可TPlus.UI.RefreshField(cVenCode)是T官方API强制刷新指定字段UI否则用户看不到变化此方案无需改数据库、不新增JS文件5分钟内完成比提单给IT部快10倍。6.2 高阶技巧用“伪自由项”实现无限级联动T自由项只有10个cFree1~cFree10但客户要“省→市→区→街道”四级联动。常规思路是求IT加字段但我们用了一个取巧办法把cFree1作为“省”cFree2作为“市”cFree3作为“区”而“街道”不占自由项而是用cFree10的Text属性存储完整地址字符串并在cFree3的onChange事件里用TPlus.Data.getBillData().getDetailRows()[0].cFree10 北京市朝阳区建国路8号直接写入。这样既不突破字段限制又满足业务。6.3 安全加固防止恶意SQL注入的三道防线虽然FilterSQL由管理员配置但仍需防患于未然。我们在executor.js中加入三重校验防线实现方式作用语法白名单FilterSQL必须以SELECT开头且不能含INSERT/UPDATE/DELETE/EXEC关键字阻断写操作和命令执行字段白名单replacePlaceholders只允许替换cFree1~cFree10、cCode、cName等预设字段名防止注入{sys.tables}等系统表长度限制FilterSQL字段在数据库中设为NVARCHAR(1000)超长截断防止超长payload绕过检测// executor.js 开头加入校验 function validateFilterSQL(sql) { if (!sql || typeof sql ! string) return false; if (sql.length 1000) return false; if (!/^SELECT/i.test(sql)) return false; if (/INSERT|UPDATE|DELETE|EXEC|xp_/i.test(sql)) return false; return true; } // 在 executeCascade 中调用 if (!validateFilterSQL(rule.FilterSQL)) { console.warn(非法SQL被拦截${rule.FilterSQL}); return; }从那以后我每次加新联动规则都强制走一遍SELECT TOP 10 * FROM v_Brand WHERE cBigClassGP-001在SSMS里先执行通再粘贴进配置表——看似多一步却避免了80%的线上SQL报错。希望帮到你。本文还有配套的精品资源点击获取