Delphi TMS WEB Core 框架第五讲：TMSWebForm单页结构调用JS与XData后端联调部署

TMS WEB Core 把 Delphi 的 Pascal 窗体代码经 pas2js 编译器译成 JavaScript，产出纯 HTML/JS/CSS 单页应用（SPA），浏览器直接跑，不依赖任何原生可执行文件。设计期在 Delphi IDE 里像画 VCL 一样拖 TWebButton、TWebEdit、TWebLabel，编译期由 TMS WEB Core 插件调用 pas2js 把 .pas/.dfm 编成 Project1.js，再由项目同目录的 Project1.html 作为容器加载 。下面按“建项目→TMSWebForm结构→事件与组件→调JS→REST/XData联调→编译部署→排错”顺序直拆。

一、新建项目与目录结构
Delphi IDE → File → New → Other → TMS WEB → TMS Web Application（或 TMS Web Browser Application）。生成结构：
- Project1.dpr：项目入口，形似 VCL 的 .dpr
• Unit1.pas：窗体逻辑，类继承 TWebForm（不是 TForm）

• Unit1.dfm：组件布局持久化

• Project1.html：SPA 容器，body 里默认仅引 <script src="Project1.js"></script>

- 编译输出：默认落项目目录 \tmsweb 子目录，含 .html/.js/.css/图片

设计期本质是借 VCL 设计器画 Web 客户端，运行时才是真浏览器 DOM。多 Form 共存时，所有 TWebForm 挂在同一个 HTML 页面 URL 下切换，不刷新整页 。

二、TMSWebForm 与 HTML 容器绑定机制
每个 TWebForm 配套一个同名单 .html（如 unit1.html），作为该窗体控件的挂载容器。运行时 TMS WEB Core 把 TWebButton 等控件动态建成对应 DOM 元素塞进 body 或指定 ElementID 节点 。
关键属性：
• ElementID：把 Delphi 控件绑到 HTML 里已存在的 <div id="xxx">，适合套 Bootstrap/AdminLTE 模板

• ElementFont / ElementClassName：直接挂 CSS class，接 Bootstrap 5、AdminLTE 4 无压力

- Body 合并规则：Form 创建时，unit.html 内容合并进主 Project.html 的 body，ElementID 对不上就渲染错位

三、基础组件与事件写法
拖 TWebEdit1、TWebButton1、TWebLabel1 到 Form，双击按钮写：
procedure TForm1.WebButton1Click(Sender: TObject);
begin
WebLabel1.Caption := '你好，' + WebEdit1.Text + '！';
end;

F9 运行 → IDE 起内置轻量 Web Server（默认 localhost:8000）→ 拉起默认浏览器加载 Project1.html → 点击按钮改标签。背后就是 pas2js 编出的 JS 在操纵 DOM 。

常用 TMS WEB Core 前端组件：
• TWebButton / TWebEdit / TWebLabel / TWebMemo

• TWebTableView / TWebTableControl（数据表格）

- TWebHttpRequest（AJAX 请求）
• TWebClientConnection + TWebClientDataSet + TWebDataSource（REST/JSON 数据集绑定）

四、从 Delphi 调 JavaScript
三种方式直接混写：
1. 全局对象：unit Web 里已声明 document: TJSDocument; window: TJSWindow; console: TJSConsole
document.title := '后台首页';
window.alert('保存成功');
console.log('debug info');

2. asm…end 内联 JS 块（pas2js 原生支持）：
procedure TForm1.WebButton1Click(Sender: TObject);
var s: string;
begin
s := WebEdit1.Text;
asm
alert('你输入了：' + s);
localStorage.setItem('uid', s);
end;
end;

3. 引入外部 JS 库：IDE → Project 右键 → JavaScript Library Manager 加 cdn 或本地 .js，运行时直接 window.xxx() 调

五、REST / XData 后端联调（管理后台标配）
前端纯 SPA 不落地数据，走 HTTP REST + JSON。后端用 TMS XData 最快，几分钟把数据库暴露成 REST API 。
前端连 XData 步骤：
1. 放 TXDataWebConnection 到 Form，设 URL：http://localhost:2001/tms/xdata
2. 设 XDataWebConnection1.Connected := True（注意：浏览器内全异步，不能紧接写依赖连接的同步代码，用 OnConnect 回调）
3. 用 TXDataWebClient 发查询/新增/修改，或挂 TWebClientDataSet 做 DB-Aware 绑定，写法接近传统 TClientDataSet
4. 登录鉴权：JWT 放 Authorization 头，TXDataWebConnection 的 RequestHeaders 里加；或用 TMS Sphinx 做统一认证

示例：拉角色列表渲染表格
procedure TForm1.LoadRoles;
begin
XDataWebClient1.RoleList(
procedure(Resp: TXDataClientResponse)
var json: TJSONArray;
begin
json := TJSONObject(Resp.Result).GetValue('value') as TJSONArray;
WebTableControl1.LoadFromJSON(json);
end);
end;


六、编译与部署
1. 开发期：F9 由 TMSWebRunner 拉起浏览器，内置 Server 占 8000 端口，改 Project → Options → TMS Web → Browser 可换 Chrome/Edge
2. 发布期：编译完把 \tmsweb 输出目录（Project1.html + Project1.js + .css + 资源）整目录拷到 IIS / Nginx / Apache 根目录即可，无 DLL、无 EXE
3. 生产配置：XData 后端地址写进同目录 td_configuration.json：{ "Server": "https://域名/tms/xdata" }，前端读取避免硬编码
4. HTTPS 混用坑：页面走 HTTPS 时，XData 也必须 HTTPS，否则浏览器拦 JS 发 HTTP 请求，Let's Encrypt 免费证书挂 XData 即可

七、常见排错
• 编译报 pas2js not found：Tools → Options → TMS Web → Web Compiler 路径未指到 pas2js.exe，重装 TMS WEB Core 或手动指路径

- 页面白屏控件不显：unit.html 的 ElementID 与 Delphi 控件 ElementID 不一致，或 Bootstrap 模板 DOM 结构覆盖掉了挂载点
• XData 连不上：URL 末尾是否带 /tms/xdata、CORS 未开（XData 端启 TCorsMiddleware）、JWT 头拼错

- asm 块里 Pascal 变量拿不到：asm 内是纯 JS 上下文，必须先在 Pascal 侧赋给局部变量再进 asm，或用 window.__uid = uid 桥接
• 多 Form 切换闪屏：用 Form.Show/ShowModal 而非新建浏览器页，SPA 内 Form 切换不刷新 URL

TMS WEB Core 的实战价值在“一套 Pascal 代码出桌面 VCL + Web 后台”，传奇类开服管理端（在线人数、爆率热改、GM 审计、行会查询）直接套 AdminLTE 模板 + XData 读 HeroDB/SQL，比另学 Vue/React 省一套语言栈。按上面建项目→拖组件→asm 调 JS→TXDataWebConnection 联后端→\tmsweb 目录丢 Nginx 的流程走，管理后台前端一次成型。