简介面向Delphi与RAD Studio开发者的中文技术文档聚焦借助HTMX与WebStencils进行快速Web开发适合希望用服务端模板和少量HTML属性增强页面交互、降低JavaScript与AJAX依赖的初中级开发者。文件为1个PDF约919KB单册紧凑便于离线查阅。内容先讲HTMX定位与GET、POST、PUT/PATCH/DELETE等请求方式对照传统JavaScript和AJAX说明hx-get、hx-post、hx-swap等属性如何指定响应目标并控制内容交换再介绍WebBroker的组件架构、应用创建与请求响应处理为HTMX落地提供后端基础。已有479人学习可作为理解Delphi 12 Web开发新模式、搭建页面原型与动态交互的参考。1. 先把三件事分清Delphi 12 里的 HTMX、WebStencils 和 WebBroker 到底是什么第一次翻这份《Delphi 12 控件之 htmx webstencils中文版》新手最容易卡在名字上——HTMX 和 WebStencils 看着像两个陌生的前端框架其实是一对搭档。拆开说Delphi 12 还是你熟悉的那个写程序的工具HTMX 是一组直接写在 HTML 标签上的属性让页面自己会发请求WebStencils 是随 Delphi 12 一起来的模板引擎负责把后台数据填进 HTML 里底下托着它们的叫 WebBroker专门接请求、发响应。四者合起来是一条完整的路界面用模板写交互用属性写逻辑全留在 Delphi 代码里。它最适合手上已经有一堆 Delphi 代码、想给这些程序加个网页入口又不想被前端工程化折腾的人。2. 为什么要学这套组合它把前端复杂度砍掉了一大半新手听到「网页开发」四个字脑子里浮现的往往是 Node、打包工具、一堆配置文件还没写第一行业务代码就先被环境劝退。这套组合的思路正好相反它假设你只会 Delphi也只需要会 Delphi剩下的部分用 HTML 属性加模板语法补上。这一章不讲怎么装环境先把「为什么值得学」讲透你后面动手时才知道每一步在解决什么问题。2.1 传统 JavaScript 加 AJAX累在「两边要对齐」先看一个再普通不过的需求一个待办清单勾选某一条就把它标记成完成。用传统写法前端要写这么一段// 传统做法勾选一条待办要自己发请求、自己解析 JSON、自己改 DOM document.querySelectorAll(.toggle).forEach(function (box) { box.addEventListener(change, async function () { const id box.dataset.id; // 从标签上抠出 id const resp await fetch(/api/tasks/ id /toggle, { method: POST }); const data await resp.json(); // 还要和后台约定返回结构 box.closest(li).classList.toggle(done, data.done); // 手动同步界面 }); });这段代码本身不算长真正让人头疼的是它背后的隐形成本。第一请求地址、参数名、返回字段名前后端必须一字不差地对齐改一个字段名要动两个地方忘了就是白屏。第二界面状态要靠 JS 手动同步勾选后如果请求失败你得自己写回滚逻辑否则界面和数据库就对不上了。第三这段逻辑写在哪个文件、什么时候加载、会不会和别的脚本打架都是新手容易翻车的点。我带过的新人里十个有八个第一次做异步刷新时卡的不是逻辑而是「为什么点完没反应」——控制台一打开一个拼错的字段名躺在那儿。2.2 HTMX 的核心就五个动作全写在标签上HTMX 的做法是把上面那段 JS 整个删掉改成在标签上写属性。它真正需要你记住的动作只有五个去哪儿要数据、要回来放哪儿、用什么方式要、要回来怎么换、什么时候要。属性作用最简写法hx-get/hx-post用 GET 或 POST 发起请求hx-get/tasks/listhx-target服务器返回的内容塞进哪个元素hx-target#tasklisthx-swap怎么替换整块换、内部换、追加hx-swapinnerHTMLhx-trigger什么事件触发默认是点击hx-triggerchangehx-select只从响应里挑一块用hx-select#tasklist同样的勾选需求HTMX 版本长这样!-- 勾选即提交服务器直接返回一段新的 li整条替换掉 -- li idtask-3 input typecheckbox hx-post/tasks/3/toggle hx-target#task-3 hx-swapouterHTML 写周报 /li区别在哪服务器不再返回一段 JSON而是直接返回渲染好的 HTML 片段。浏览器拿到什么就换什么不需要前端再翻译一遍。这意味着「界面长什么样」这件事只有一处定义——服务端的模板前端不再有第二套渲染逻辑也就没有对齐问题。新手最容易低估这一点当你只有一套渲染逻辑时改样式、改字段、改布局都只改一个文件。2.3 WebStencils 解决的是另一个痛点别再拼字符串了在 WebStencils 之前Delphi 写网页的常规姿势是拼字符串// 老写法拼字符串引号、转义、循环全靠人肉维护 Html : ul; for Task in Tasks do Html : Html li Task.Title /li; Html : Html /ul; Response.Content : Html;这段代码能跑但经不起真实数据。标题里带一个或者页面结构就崩了要加个 class、加个条件判断、嵌套两层循环字符串会迅速变成一团乱麻更麻烦的是改样式——设计师给你一份 HTML你得一个字一个字地翻译成字符串拼接语句改一次错一次。WebStencils 把这层翻译工作去掉了模板文件就是普通 HTML取值和判断用开头!-- templates/tasks.html这就是能直接被浏览器打开的 HTML -- ul idtasklist ForEach task in tasks li classtask if task.Done then done input typecheckbox hx-post/tasks/task.Id/toggle hx-targetclosest li hx-swapouterHTML task.Title /li End /ul几个要点task.Title是点表示法取值ForEach ... End是循环if ... then是条件* 这是注释 *写给人看、不会输出到页面上。完整语法里还有page、query、ifNOT、else这些够你覆盖日常九成场景。HTML 里的{ }花括号要用双写转义因为模板引擎会把它当成占位符——这条先记着第五章还会提。2.4 哪些项目适合这套写法哪些别硬上说清楚适合谁比夸它重要。适合的典型场景内部管理系统、表单密集的后台、需要快速出原型给业务方看的项目、团队里没有专职前端、已经有现成 Delphi 业务代码想加个网页壳子。这类项目的共同点是「页面多、交互浅、迭代快」用 HTMX 加 WebStencils一个人一天能推好几个页面。不太适合的场景也要讲明白。如果你的页面需要大量客户端交互比如拖拽排序、富文本编辑、复杂图表联动、离线可用那还是老老实实上成熟的前端框架HTMX 在这类场景会让你越写越别扭。如果你的团队已经有稳定的前端栈和组件库硬切过来反而是浪费。还有一个容易忽略的点HTMX 每次交互都往服务器发一次请求返回的是一段 HTML 而不是几十字节的 JSON流量会大一些。对内部系统完全无所谓对高并发公网应用就要算一算。判断标准很简单——如果你的页面主要是「展示数据、提交表单」这套组合是省力的如果主要是「在浏览器里做复杂运算和状态管理」那它不是为你准备的。3. 第一次动手从新建 WebBroker 工程到跑通 Hello World概念讲完了接下来是最容易让人放弃的一段把第一个页面跑起来。我的血泪经验是新手在这一步翻车九成不是代码写错而是目录、端口、路径这三件小事没对齐。这一章按顺序走一遍每一步都告诉你「怎么确认自己是对的」跑不通时也知道该看哪儿。3.1 新建 WebBroker 应用先让浏览器能打开一个页面打开 RAD Studio走这条路径菜单里选新建工程找到 Web 类目下的 Web Server Application类型先选独立运行的那种stand-alone它自带一个小型服务器不用配 IIS 或 Apache学习阶段最省事向导会让你填端口先用一个不常用的比如 8080工程建好后会看到一个 WebModule这就是整个应用的请求入口直接运行浏览器访问http://localhost:8080能出东西就算通了。如果浏览器提示无法连接先看两件事程序是否真的在运行有些环境会在控制台窗口里等你按回车才启动以及端口有没有被别的程序占掉。换个端口重来一遍比在那里猜半天快得多。第一段代码就写在 WebModule 的默认处理动作里目的是确认「请求能进来、响应能出去」// WebModule 的默认处理动作先返回一段最原始的 HTML procedure TWebModule1.WebModule1DefaultHandlerAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); begin // 字符集必须写全少了 charset 中文就会变问号 Response.ContentType : text/html; charsetutf-8; Response.Content : h1你好世界/h1; end;参数含义值得逐一看清Request是这次进来的请求表单字段、查询参数、请求头都从它身上取Response是你要发回去的东西ContentType告诉浏览器这是什么格式Content就是正文Handled是一个开关你把它设成 True表示这个请求我处理完了别再往下传。新手常犯的错是只改Content不管ContentType页面能显示但中文全是乱码然后怀疑是编码问题折腾半天。3.2 WebModule、WebStencilsEngine、WebStencilsProcessor 各管什么这三个名字长得很像功能完全不同混淆了就会写出「模板改了没生效」这类玄学问题。用一句话概括模块管分发引擎管数据处理器管一次渲染。组件类比具体职责WebModule前台接待按路径把请求分给对应的处理动作WebStencilsEngine公告栏存放所有页面共享的变量、全局配置WebStencilsProcessor印刷机拿一个模板文件加一份数据印出一段 HTML用法上的分界很清楚像站点名称、当前登录用户、版本号这种每个页面都要用的值挂在引擎上用AddVar加一次全局可用像某个列表页的具体数据就在处理这次请求时临时喂给处理器。理解了这个分工你就不会把「所有页面的标题」这种全局值塞进单个页面里复制粘贴十几遍。3.3 模板文件放在哪先把目录规矩定下来这一步看着无聊但它决定了你未来两周会不会天天遇到「文件找不到」。建议一开始就定成这个样子项目根目录/ ├── wwwroot/ │ ├── js/htmx.min.js # 前端脚本本地放一份别依赖外网 │ └── templates/ # 所有模板文件 │ ├── layout.html # 公共布局 │ └── index.html # 首页 └── 编译输出的可执行文件两个关键点。第一htmx 的脚本文件下载一份放到wwwroot/js下用script src/js/htmx.min.js/script本地引用。为什么强调本地因为部署到内网或者断网环境时外链会直接白屏而错误信息还特别不明显新手很容易在这里卡一整天。第二模板路径的写法要和程序运行时的工作目录对得上。调试阶段最省事的办法是用相对路径并且确保程序是从项目根目录启动的如果路径怎么改都不对就在代码里把当前工作目录打印出来看一眼比猜快。提示模板文件本身就是合法的 HTML可以直接双击用浏览器打开预览样式。改布局时先在浏览器里调好再往里加语法效率会高很多。3.4 Hello World模板加三行代码就跑起来了先写模板。注意这个文件不依赖任何后端就能打开!-- templates/index.html普通 HTML加了几处 取值 -- !DOCTYPE html html langzh-CN head meta charsetutf-8 titleTitle/title script src/js/htmx.min.js/script /head body h1Title/h1 p服务器时间Now/p /body /html再改处理动作把「拼字符串」换成「过一遍模板引擎」procedure TWebModule1.WebModule1DefaultHandlerAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); begin Response.ContentType : text/html; charsetutf-8; // AddVar 把值挂到引擎上模板里的 Title、Now 就取到了 WebStencilsEngine1.AddVar(Title, 我的第一个 Web 页面); WebStencilsEngine1.AddVar(Now, FormatDateTime(yyyy-mm-dd hh:nn, Now)); // 处理器指向模板文件Content 读出来就是渲染完成的 HTML WebStencilsProcessor1.InputFileName : wwwroot\templates\index.html; Response.Content : WebStencilsProcessor1.Content; end;代码只有三句有效逻辑告诉引擎有哪些变量、告诉处理器用哪个模板、把渲染结果塞进响应。InputFileName是模板路径Content是「渲染后的结果」这个属性——注意它和Response.Content名字一样但完全没关系前者是处理器算出来的字符串后者是要发给浏览器的正文。验证方式重新运行刷新浏览器。页面出现标题和时间说明整条链路通了如果显示的是原样的Title字符说明模板没经过处理器检查一下Content是不是从处理器取的如果报文件找不到回到 3.3 看路径。这一步通了之后后面所有玩法都是在这个骨架上加东西。4. 让页面动起来用 hx-get 和 hx-post 做出第一个能增能删的清单Hello World 只证明链路通了页面还是死的。这一章做一件真正有用的事一个能添加、能勾选、能删除的待办清单。做完这个例子HTMX 的常用属性你基本就都摸过一遍了剩下的都是查手册的事。4.1 hx-get 加 hx-target一次最小的异步刷新先做最简单的一半点按钮只刷新清单那一块其他部分不动。!-- 按钮只负责「要数据」要回来放哪儿由 hx-target 说了算 -- button hx-get/tasks/list hx-target#tasklist hx-swapinnerHTML 刷新清单 /button div idtasklist !-- 这里的内容会被服务器返回的片段整体替换掉 -- /div服务端这边给 WebModule 加一个处理动作路径设成/tasks/list逻辑是拿数据、渲染片段模板、返回procedure TWebModule1.WebModule1TaskListAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); begin Response.ContentType : text/html; charsetutf-8; // 真实项目里这里换成从数据库或内存列表取 WebStencilsEngine1.AddVar(tasks, GetTaskList); WebStencilsProcessor1.InputFileName : wwwroot\templates\tasks_list.html; Response.Content : WebStencilsProcessor1.Content; end;注意返回的不是整个页面而只是清单那一段 HTML。这是 HTMX 的核心习惯服务端返回的是「零件」不是「整车」。刚上手时很容易顺手返回整个页面结果一刷新导航栏和页脚全部重复嵌套进去页面越点越乱。判断标准很简单——模板文件里有没有html标签片段模板不应该有。调试时有个比盯浏览器快得多的办法# 直接看服务端到底吐了什么比在浏览器里猜快 curl -i http://localhost:8080/tasks/list看两样东西状态码是不是 200返回的 HTML 结构对不对。如果命令行里正常、浏览器里不对问题就在前端属性上如果命令行里就不对问题在服务端往下查的范围立刻缩小一半。4.2 hx-post把表单数据送回服务器添加任务的流程是「填表单 → 提交 → 服务器存下来 → 返回新的清单」。!-- 提交后不跳页直接把返回的清单塞回列表 -- form hx-post/tasks/add hx-target#tasklist hx-swapinnerHTML input typetext nametitle placeholder要做的事 button typesubmit添加/button /form服务端从请求里取字段procedure TWebModule1.WebModule1AddTaskAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); var Title: string; begin // POST 表单取值用 ContentFieldsGET 的查询参数用 QueryFields Title : Trim(Request.ContentFields.Values[title]); if Title then begin // 出错也要返回片段前端才知道该显示什么 Response.ContentType : text/html; charsetutf-8; Response.Content : p classerr内容不能为空/p; Exit; end; AddTask(Title); // 存进你的数据源 // 存完立刻返回最新清单前端负责替换不需要额外刷新 Response.ContentType : text/html; charsetutf-8; WebStencilsEngine1.AddVar(tasks, GetTaskList); WebStencilsProcessor1.InputFileName : wwwroot\templates\tasks_list.html; Response.Content : WebStencilsProcessor1.Content; end;两个细节值得单独说。第一ContentFields和QueryFields别用混POST 表单的数据在ContentFieldsURL 上?a1这种在QueryFields用错了取出来永远是空字符串且不报错非常难查。第二处理完之后不要返回空内容。HTMX 拿到空响应行为是「什么都不换」页面看起来像没反应——很多新手以为请求失败了其实请求成功了只是回了个空字符串。4.3 hx-swap 和 hx-trigger换法与时机的调节旋钮hx-swap控制「拿回来的 HTML 怎么放进去」常用的几种取值效果典型场景innerHTML替换目标元素的内部内容列表整体刷新outerHTML连目标元素本身一起替换单条记录的局部更新beforeend追加到目标元素末尾聊天消息、日志流afterbegin插到目标元素开头新消息置顶delete删掉目标元素删除一条记录hx-trigger控制「什么时候发请求」默认是点击可以改成change勾选框变化即提交、keyup changed delay:500ms输入停下半秒再查避免每敲一个字发一次、load元素加载完就请求、every 2s定时刷新。新手最该先掌握的是delay因为实时搜索如果不加延迟输入十个字就是十次请求服务器直接被你自己刷爆。还有一个好用的属性hx-select服务器返回一大段 HTML你只想要其中某一块。比如后端为了复用返回的还是完整清单但这次只想更新统计数字就可以用hx-select#stats把那一块挑出来剩下的丢掉。这招在多处复用同一个模板时特别省事。4.4 合起来做一个能加能删的待办清单最后把删除和勾选补上。这两处用outerHTML更合适因为服务器返回的就是完整的一条记录!-- 单条记录勾选后整条替换删除后整条消失 -- li idtask-task.Id classtask if task.Done then done input typecheckbox hx-post/tasks/task.Id/toggle hx-target#task-task.Id hx-swapouterHTML spantask.Title/span button hx-delete/tasks/task.Id hx-target#task-task.Id hx-swapouterHTML 删除 /button /lihx-delete是 HTMX 提供的另一种请求方式和hx-post、hx-put、hx-patch一样都只是换个 HTTP 方法而已写法完全一致。服务端处理删除时直接返回空内容加上hx-swapouterHTML元素就被移除了——这个组合是删除操作最省事的方式不用写任何前端删除逻辑。到这里你已经用到了 GET、POST、DELETE 三种请求用到了hx-target、hx-swap、hx-trigger、hx-select四个属性。剩下的什么分类筛选、状态过滤本质都是同一套把筛选条件挂在请求参数上服务端按条件返回过滤后的片段前端负责换上去。真正需要你动的脑筋在服务端而不在 HTML 上——这正是这套组合想让你接受的分工。注意模板里的{ }花括号记得双写转义否则会被模板引擎当成占位符吃掉而且报错信息往往指向别的地方是典型的玄学问题。5. 新手避坑五个最容易翻车的现场和对应的解法这一章的内容全部来自真实的踩坑现场每一条都按「现象 → 原因 → 解决」写。你不用背遇到问题时回来对着找就行。五个坑覆盖了新手期八成以上的卡点剩下的两成基本是拼写错误。5.1 现象点了按钮整个页面跳走了现象点按钮的一瞬间整个页面刷新或者跳转到一个空白页有时候地址栏还变了。原因最常见的是表单里的button默认类型是submit即使你写了hx-post浏览器仍然会执行原生提交另一种是用了a标签但没写href或者写了点击触发的是原生跳转而不是 HTMX 请求。解决把按钮显式声明成typebutton只有真正要提交表单的那一个才用typesubmit链接类操作用href#配合阻止默认行为或者干脆换成button元素。判断是不是这个原因很快看浏览器地址栏有没有变化变了就是原生提交在起作用。5.2 现象页面上原样显示 task.Title现象页面打开什么都对就是在该出现数据的地方直接显示了task.Title这串字符像模板没生效一样。原因模板文件确实没经过处理器。要么Response.Content是直接从文件读出来的原始字符串绕过了处理器要么InputFileName路径写错程序读到了另一个同名文件还有一种情况是模板里花括号没转义解析到一半就中断了。解决先确认Response.Content是从处理器的Content属性取的而不是自己用文件读取函数读的。再确认路径指向的是你正在编辑的那个文件——把修改一个明显字比如标题加个感叹号作为测试改完刷新能看到变化说明路径对了。最后检查 HTML 里的{ }有没有双写。5.3 现象请求发出去了浏览器控制台报 404现象按下按钮浏览器开发者工具的 Network 面板里能看到请求但状态码是 404响应体里是一段错误页。原因路径没对上。可能是处理动作的路径前缀和页面里写的请求地址不一致一个写/tasks/list一个写/api/tasks/list也可能是大小写、结尾斜杠的差异。还有人是在 WebModule 里加了动作但忘了启用程序根本没注册这条路由。解决先把页面里的请求地址复制出来用命令行curl -i 完整地址直接打看能不能通。命令行通、页面不通说明是相对路径的问题——页面本身的地址带了一段前缀相对路径会拼在前面。统一改成以/开头的绝对路径问题立刻消失。5.4 现象返回 200页面却纹丝不动现象Network 面板里状态码 200响应体也有内容但页面看上去什么都没变。原因三种可能。一是hx-target的选择器没匹配到元素比如写错了 id或者 id 在循环里重复了二是hx-swap的取值和目标元素不匹配比如对一个本身要被替换的元素用了innerHTML看起来就像没变化三是服务端返回了空内容。解决先看响应体是不是空的空的就查服务端分支逻辑八成是某个提前Exit没返回内容。再看选择器在浏览器控制台里用document.querySelector(你的选择器)执行一下返回null就是它的问题。最后检查 id 唯一性——在循环里用固定的 id 是很常见的错误改成一串带序号的task-1、task-2就好了。5.5 现象中文变成一堆问号现象页面能出来但所有中文都显示成问号或者一堆看不懂的字符。原因Response.ContentType只写了text/html没写字符集或者写的是utf-8但模板文件本身保存成了别的编码格式。解决把响应的ContentType固定写成text/html; charsetutf-8模板文件统一用 UTF-8 保存。还有一个隐蔽情况某些编辑器保存时会自动加 BOM 头这个头会被当成正文输出导致页面最前面出现一行空白或者奇怪的字符——用「无 BOM 的 UTF-8」保存或者用十六进制查看器看一眼文件开头就能确认。提示把这五条整理成一个自己的检查清单每次页面不对时从上往下走一遍。我见过的大部分「怎么也调不通」都是这五条里的某一条。6. 下一步学什么从跑通第一个例子到改得动别人的代码跑到待办清单这一步你其实已经把这套技术的主干走完了。接下来容易犯的错是「什么属性都学一遍」结果学了一堆冷门的反而不会用。更有效的顺序是先补三块按顺序来就行顺序学什么为什么排在这里第一块布局模板RenderBody、LayoutPage、Import页面一多公共导航和页脚必须抽出来否则改一次要动十个文件第二块会话与安全内存会话、CSRF、输入校验一旦有登录和写操作这些不是可选项第三块高级属性hx-trigger的复合写法、hx-push-url、hx-include需要「地址栏能分享」「把多个字段带给服务器」时才用得上第一块优先学的原因很实际你现在的三个页面可能各自都有一份导航栏改个菜单要改三遍改完还可能漏一处。布局模板的思路是把公共部分抽成骨架每个页面只保留自己那块内容占位符负责「把内容塞进来」。抽完之后改一次全站生效那种松一口气的感觉特别明显。第二块是绕不开的门槛。会话管理最省事的做法是放在内存里——一个会话表登录成功就写进去请求进来时按凭据查。但这里有个坑要提前知道内存会话在程序重启后就没了所有用户被迫重新登录。做演示无所谓上线前要么换成持久化存储要么确认这个行为在你的场景里可接受。同时别忽略输入校验和 CSRF 防护只要页面能提交数据这两件事就要一起考虑不能等出事再补。第三块等真的需要再说。hx-push-url让地址栏跟着变用户按后退键才是自然的hx-include可以把目标元素之外的输入框一起带过去做筛选栏时特别顺手。这些属性看一眼文档就能用没必要提前背。最后说个我自己交过学费的习惯。早期我总觉得「先跑起来再说」于是一个页面里既拼了两行字符串、又混着模板、还顺手写了几行内联脚本当时能跑两周后自己都看不懂了。从那以后我给自己定了一条死规矩只要某个 HTML 片段在第二个地方出现立刻抽成模板只要某个取值超过两处立刻挂到引擎上去。这条规矩救过我很多次尤其是在项目赶进度、所有人都想「先一把梭」的时候。希望帮到你。本文还有配套的精品资源点击获取
简介面向Delphi与RAD Studio开发者的中文技术文档聚焦借助HTMX与WebStencils进行快速Web开发适合希望用服务端模板和少量HTML属性增强页面交互、降低JavaScript与AJAX依赖的初中级开发者。文件为1个PDF约919KB单册紧凑便于离线查阅。内容先讲HTMX定位与GET、POST、PUT/PATCH/DELETE等请求方式对照传统JavaScript和AJAX说明hx-get、hx-post、hx-swap等属性如何指定响应目标并控制内容交换再介绍WebBroker的组件架构、应用创建与请求响应处理为HTMX落地提供后端基础。已有479人学习可作为理解Delphi 12 Web开发新模式、搭建页面原型与动态交互的参考。1. 先把三件事分清Delphi 12 里的 HTMX、WebStencils 和 WebBroker 到底是什么第一次翻这份《Delphi 12 控件之 htmx webstencils中文版》新手最容易卡在名字上——HTMX 和 WebStencils 看着像两个陌生的前端框架其实是一对搭档。拆开说Delphi 12 还是你熟悉的那个写程序的工具HTMX 是一组直接写在 HTML 标签上的属性让页面自己会发请求WebStencils 是随 Delphi 12 一起来的模板引擎负责把后台数据填进 HTML 里底下托着它们的叫 WebBroker专门接请求、发响应。四者合起来是一条完整的路界面用模板写交互用属性写逻辑全留在 Delphi 代码里。它最适合手上已经有一堆 Delphi 代码、想给这些程序加个网页入口又不想被前端工程化折腾的人。2. 为什么要学这套组合它把前端复杂度砍掉了一大半新手听到「网页开发」四个字脑子里浮现的往往是 Node、打包工具、一堆配置文件还没写第一行业务代码就先被环境劝退。这套组合的思路正好相反它假设你只会 Delphi也只需要会 Delphi剩下的部分用 HTML 属性加模板语法补上。这一章不讲怎么装环境先把「为什么值得学」讲透你后面动手时才知道每一步在解决什么问题。2.1 传统 JavaScript 加 AJAX累在「两边要对齐」先看一个再普通不过的需求一个待办清单勾选某一条就把它标记成完成。用传统写法前端要写这么一段// 传统做法勾选一条待办要自己发请求、自己解析 JSON、自己改 DOM document.querySelectorAll(.toggle).forEach(function (box) { box.addEventListener(change, async function () { const id box.dataset.id; // 从标签上抠出 id const resp await fetch(/api/tasks/ id /toggle, { method: POST }); const data await resp.json(); // 还要和后台约定返回结构 box.closest(li).classList.toggle(done, data.done); // 手动同步界面 }); });这段代码本身不算长真正让人头疼的是它背后的隐形成本。第一请求地址、参数名、返回字段名前后端必须一字不差地对齐改一个字段名要动两个地方忘了就是白屏。第二界面状态要靠 JS 手动同步勾选后如果请求失败你得自己写回滚逻辑否则界面和数据库就对不上了。第三这段逻辑写在哪个文件、什么时候加载、会不会和别的脚本打架都是新手容易翻车的点。我带过的新人里十个有八个第一次做异步刷新时卡的不是逻辑而是「为什么点完没反应」——控制台一打开一个拼错的字段名躺在那儿。2.2 HTMX 的核心就五个动作全写在标签上HTMX 的做法是把上面那段 JS 整个删掉改成在标签上写属性。它真正需要你记住的动作只有五个去哪儿要数据、要回来放哪儿、用什么方式要、要回来怎么换、什么时候要。属性作用最简写法hx-get/hx-post用 GET 或 POST 发起请求hx-get/tasks/listhx-target服务器返回的内容塞进哪个元素hx-target#tasklisthx-swap怎么替换整块换、内部换、追加hx-swapinnerHTMLhx-trigger什么事件触发默认是点击hx-triggerchangehx-select只从响应里挑一块用hx-select#tasklist同样的勾选需求HTMX 版本长这样!-- 勾选即提交服务器直接返回一段新的 li整条替换掉 -- li idtask-3 input typecheckbox hx-post/tasks/3/toggle hx-target#task-3 hx-swapouterHTML 写周报 /li区别在哪服务器不再返回一段 JSON而是直接返回渲染好的 HTML 片段。浏览器拿到什么就换什么不需要前端再翻译一遍。这意味着「界面长什么样」这件事只有一处定义——服务端的模板前端不再有第二套渲染逻辑也就没有对齐问题。新手最容易低估这一点当你只有一套渲染逻辑时改样式、改字段、改布局都只改一个文件。2.3 WebStencils 解决的是另一个痛点别再拼字符串了在 WebStencils 之前Delphi 写网页的常规姿势是拼字符串// 老写法拼字符串引号、转义、循环全靠人肉维护 Html : ul; for Task in Tasks do Html : Html li Task.Title /li; Html : Html /ul; Response.Content : Html;这段代码能跑但经不起真实数据。标题里带一个或者页面结构就崩了要加个 class、加个条件判断、嵌套两层循环字符串会迅速变成一团乱麻更麻烦的是改样式——设计师给你一份 HTML你得一个字一个字地翻译成字符串拼接语句改一次错一次。WebStencils 把这层翻译工作去掉了模板文件就是普通 HTML取值和判断用开头!-- templates/tasks.html这就是能直接被浏览器打开的 HTML -- ul idtasklist ForEach task in tasks li classtask if task.Done then done input typecheckbox hx-post/tasks/task.Id/toggle hx-targetclosest li hx-swapouterHTML task.Title /li End /ul几个要点task.Title是点表示法取值ForEach ... End是循环if ... then是条件* 这是注释 *写给人看、不会输出到页面上。完整语法里还有page、query、ifNOT、else这些够你覆盖日常九成场景。HTML 里的{ }花括号要用双写转义因为模板引擎会把它当成占位符——这条先记着第五章还会提。2.4 哪些项目适合这套写法哪些别硬上说清楚适合谁比夸它重要。适合的典型场景内部管理系统、表单密集的后台、需要快速出原型给业务方看的项目、团队里没有专职前端、已经有现成 Delphi 业务代码想加个网页壳子。这类项目的共同点是「页面多、交互浅、迭代快」用 HTMX 加 WebStencils一个人一天能推好几个页面。不太适合的场景也要讲明白。如果你的页面需要大量客户端交互比如拖拽排序、富文本编辑、复杂图表联动、离线可用那还是老老实实上成熟的前端框架HTMX 在这类场景会让你越写越别扭。如果你的团队已经有稳定的前端栈和组件库硬切过来反而是浪费。还有一个容易忽略的点HTMX 每次交互都往服务器发一次请求返回的是一段 HTML 而不是几十字节的 JSON流量会大一些。对内部系统完全无所谓对高并发公网应用就要算一算。判断标准很简单——如果你的页面主要是「展示数据、提交表单」这套组合是省力的如果主要是「在浏览器里做复杂运算和状态管理」那它不是为你准备的。3. 第一次动手从新建 WebBroker 工程到跑通 Hello World概念讲完了接下来是最容易让人放弃的一段把第一个页面跑起来。我的血泪经验是新手在这一步翻车九成不是代码写错而是目录、端口、路径这三件小事没对齐。这一章按顺序走一遍每一步都告诉你「怎么确认自己是对的」跑不通时也知道该看哪儿。3.1 新建 WebBroker 应用先让浏览器能打开一个页面打开 RAD Studio走这条路径菜单里选新建工程找到 Web 类目下的 Web Server Application类型先选独立运行的那种stand-alone它自带一个小型服务器不用配 IIS 或 Apache学习阶段最省事向导会让你填端口先用一个不常用的比如 8080工程建好后会看到一个 WebModule这就是整个应用的请求入口直接运行浏览器访问http://localhost:8080能出东西就算通了。如果浏览器提示无法连接先看两件事程序是否真的在运行有些环境会在控制台窗口里等你按回车才启动以及端口有没有被别的程序占掉。换个端口重来一遍比在那里猜半天快得多。第一段代码就写在 WebModule 的默认处理动作里目的是确认「请求能进来、响应能出去」// WebModule 的默认处理动作先返回一段最原始的 HTML procedure TWebModule1.WebModule1DefaultHandlerAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); begin // 字符集必须写全少了 charset 中文就会变问号 Response.ContentType : text/html; charsetutf-8; Response.Content : h1你好世界/h1; end;参数含义值得逐一看清Request是这次进来的请求表单字段、查询参数、请求头都从它身上取Response是你要发回去的东西ContentType告诉浏览器这是什么格式Content就是正文Handled是一个开关你把它设成 True表示这个请求我处理完了别再往下传。新手常犯的错是只改Content不管ContentType页面能显示但中文全是乱码然后怀疑是编码问题折腾半天。3.2 WebModule、WebStencilsEngine、WebStencilsProcessor 各管什么这三个名字长得很像功能完全不同混淆了就会写出「模板改了没生效」这类玄学问题。用一句话概括模块管分发引擎管数据处理器管一次渲染。组件类比具体职责WebModule前台接待按路径把请求分给对应的处理动作WebStencilsEngine公告栏存放所有页面共享的变量、全局配置WebStencilsProcessor印刷机拿一个模板文件加一份数据印出一段 HTML用法上的分界很清楚像站点名称、当前登录用户、版本号这种每个页面都要用的值挂在引擎上用AddVar加一次全局可用像某个列表页的具体数据就在处理这次请求时临时喂给处理器。理解了这个分工你就不会把「所有页面的标题」这种全局值塞进单个页面里复制粘贴十几遍。3.3 模板文件放在哪先把目录规矩定下来这一步看着无聊但它决定了你未来两周会不会天天遇到「文件找不到」。建议一开始就定成这个样子项目根目录/ ├── wwwroot/ │ ├── js/htmx.min.js # 前端脚本本地放一份别依赖外网 │ └── templates/ # 所有模板文件 │ ├── layout.html # 公共布局 │ └── index.html # 首页 └── 编译输出的可执行文件两个关键点。第一htmx 的脚本文件下载一份放到wwwroot/js下用script src/js/htmx.min.js/script本地引用。为什么强调本地因为部署到内网或者断网环境时外链会直接白屏而错误信息还特别不明显新手很容易在这里卡一整天。第二模板路径的写法要和程序运行时的工作目录对得上。调试阶段最省事的办法是用相对路径并且确保程序是从项目根目录启动的如果路径怎么改都不对就在代码里把当前工作目录打印出来看一眼比猜快。提示模板文件本身就是合法的 HTML可以直接双击用浏览器打开预览样式。改布局时先在浏览器里调好再往里加语法效率会高很多。3.4 Hello World模板加三行代码就跑起来了先写模板。注意这个文件不依赖任何后端就能打开!-- templates/index.html普通 HTML加了几处 取值 -- !DOCTYPE html html langzh-CN head meta charsetutf-8 titleTitle/title script src/js/htmx.min.js/script /head body h1Title/h1 p服务器时间Now/p /body /html再改处理动作把「拼字符串」换成「过一遍模板引擎」procedure TWebModule1.WebModule1DefaultHandlerAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); begin Response.ContentType : text/html; charsetutf-8; // AddVar 把值挂到引擎上模板里的 Title、Now 就取到了 WebStencilsEngine1.AddVar(Title, 我的第一个 Web 页面); WebStencilsEngine1.AddVar(Now, FormatDateTime(yyyy-mm-dd hh:nn, Now)); // 处理器指向模板文件Content 读出来就是渲染完成的 HTML WebStencilsProcessor1.InputFileName : wwwroot\templates\index.html; Response.Content : WebStencilsProcessor1.Content; end;代码只有三句有效逻辑告诉引擎有哪些变量、告诉处理器用哪个模板、把渲染结果塞进响应。InputFileName是模板路径Content是「渲染后的结果」这个属性——注意它和Response.Content名字一样但完全没关系前者是处理器算出来的字符串后者是要发给浏览器的正文。验证方式重新运行刷新浏览器。页面出现标题和时间说明整条链路通了如果显示的是原样的Title字符说明模板没经过处理器检查一下Content是不是从处理器取的如果报文件找不到回到 3.3 看路径。这一步通了之后后面所有玩法都是在这个骨架上加东西。4. 让页面动起来用 hx-get 和 hx-post 做出第一个能增能删的清单Hello World 只证明链路通了页面还是死的。这一章做一件真正有用的事一个能添加、能勾选、能删除的待办清单。做完这个例子HTMX 的常用属性你基本就都摸过一遍了剩下的都是查手册的事。4.1 hx-get 加 hx-target一次最小的异步刷新先做最简单的一半点按钮只刷新清单那一块其他部分不动。!-- 按钮只负责「要数据」要回来放哪儿由 hx-target 说了算 -- button hx-get/tasks/list hx-target#tasklist hx-swapinnerHTML 刷新清单 /button div idtasklist !-- 这里的内容会被服务器返回的片段整体替换掉 -- /div服务端这边给 WebModule 加一个处理动作路径设成/tasks/list逻辑是拿数据、渲染片段模板、返回procedure TWebModule1.WebModule1TaskListAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); begin Response.ContentType : text/html; charsetutf-8; // 真实项目里这里换成从数据库或内存列表取 WebStencilsEngine1.AddVar(tasks, GetTaskList); WebStencilsProcessor1.InputFileName : wwwroot\templates\tasks_list.html; Response.Content : WebStencilsProcessor1.Content; end;注意返回的不是整个页面而只是清单那一段 HTML。这是 HTMX 的核心习惯服务端返回的是「零件」不是「整车」。刚上手时很容易顺手返回整个页面结果一刷新导航栏和页脚全部重复嵌套进去页面越点越乱。判断标准很简单——模板文件里有没有html标签片段模板不应该有。调试时有个比盯浏览器快得多的办法# 直接看服务端到底吐了什么比在浏览器里猜快 curl -i http://localhost:8080/tasks/list看两样东西状态码是不是 200返回的 HTML 结构对不对。如果命令行里正常、浏览器里不对问题就在前端属性上如果命令行里就不对问题在服务端往下查的范围立刻缩小一半。4.2 hx-post把表单数据送回服务器添加任务的流程是「填表单 → 提交 → 服务器存下来 → 返回新的清单」。!-- 提交后不跳页直接把返回的清单塞回列表 -- form hx-post/tasks/add hx-target#tasklist hx-swapinnerHTML input typetext nametitle placeholder要做的事 button typesubmit添加/button /form服务端从请求里取字段procedure TWebModule1.WebModule1AddTaskAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); var Title: string; begin // POST 表单取值用 ContentFieldsGET 的查询参数用 QueryFields Title : Trim(Request.ContentFields.Values[title]); if Title then begin // 出错也要返回片段前端才知道该显示什么 Response.ContentType : text/html; charsetutf-8; Response.Content : p classerr内容不能为空/p; Exit; end; AddTask(Title); // 存进你的数据源 // 存完立刻返回最新清单前端负责替换不需要额外刷新 Response.ContentType : text/html; charsetutf-8; WebStencilsEngine1.AddVar(tasks, GetTaskList); WebStencilsProcessor1.InputFileName : wwwroot\templates\tasks_list.html; Response.Content : WebStencilsProcessor1.Content; end;两个细节值得单独说。第一ContentFields和QueryFields别用混POST 表单的数据在ContentFieldsURL 上?a1这种在QueryFields用错了取出来永远是空字符串且不报错非常难查。第二处理完之后不要返回空内容。HTMX 拿到空响应行为是「什么都不换」页面看起来像没反应——很多新手以为请求失败了其实请求成功了只是回了个空字符串。4.3 hx-swap 和 hx-trigger换法与时机的调节旋钮hx-swap控制「拿回来的 HTML 怎么放进去」常用的几种取值效果典型场景innerHTML替换目标元素的内部内容列表整体刷新outerHTML连目标元素本身一起替换单条记录的局部更新beforeend追加到目标元素末尾聊天消息、日志流afterbegin插到目标元素开头新消息置顶delete删掉目标元素删除一条记录hx-trigger控制「什么时候发请求」默认是点击可以改成change勾选框变化即提交、keyup changed delay:500ms输入停下半秒再查避免每敲一个字发一次、load元素加载完就请求、every 2s定时刷新。新手最该先掌握的是delay因为实时搜索如果不加延迟输入十个字就是十次请求服务器直接被你自己刷爆。还有一个好用的属性hx-select服务器返回一大段 HTML你只想要其中某一块。比如后端为了复用返回的还是完整清单但这次只想更新统计数字就可以用hx-select#stats把那一块挑出来剩下的丢掉。这招在多处复用同一个模板时特别省事。4.4 合起来做一个能加能删的待办清单最后把删除和勾选补上。这两处用outerHTML更合适因为服务器返回的就是完整的一条记录!-- 单条记录勾选后整条替换删除后整条消失 -- li idtask-task.Id classtask if task.Done then done input typecheckbox hx-post/tasks/task.Id/toggle hx-target#task-task.Id hx-swapouterHTML spantask.Title/span button hx-delete/tasks/task.Id hx-target#task-task.Id hx-swapouterHTML 删除 /button /lihx-delete是 HTMX 提供的另一种请求方式和hx-post、hx-put、hx-patch一样都只是换个 HTTP 方法而已写法完全一致。服务端处理删除时直接返回空内容加上hx-swapouterHTML元素就被移除了——这个组合是删除操作最省事的方式不用写任何前端删除逻辑。到这里你已经用到了 GET、POST、DELETE 三种请求用到了hx-target、hx-swap、hx-trigger、hx-select四个属性。剩下的什么分类筛选、状态过滤本质都是同一套把筛选条件挂在请求参数上服务端按条件返回过滤后的片段前端负责换上去。真正需要你动的脑筋在服务端而不在 HTML 上——这正是这套组合想让你接受的分工。注意模板里的{ }花括号记得双写转义否则会被模板引擎当成占位符吃掉而且报错信息往往指向别的地方是典型的玄学问题。5. 新手避坑五个最容易翻车的现场和对应的解法这一章的内容全部来自真实的踩坑现场每一条都按「现象 → 原因 → 解决」写。你不用背遇到问题时回来对着找就行。五个坑覆盖了新手期八成以上的卡点剩下的两成基本是拼写错误。5.1 现象点了按钮整个页面跳走了现象点按钮的一瞬间整个页面刷新或者跳转到一个空白页有时候地址栏还变了。原因最常见的是表单里的button默认类型是submit即使你写了hx-post浏览器仍然会执行原生提交另一种是用了a标签但没写href或者写了点击触发的是原生跳转而不是 HTMX 请求。解决把按钮显式声明成typebutton只有真正要提交表单的那一个才用typesubmit链接类操作用href#配合阻止默认行为或者干脆换成button元素。判断是不是这个原因很快看浏览器地址栏有没有变化变了就是原生提交在起作用。5.2 现象页面上原样显示 task.Title现象页面打开什么都对就是在该出现数据的地方直接显示了task.Title这串字符像模板没生效一样。原因模板文件确实没经过处理器。要么Response.Content是直接从文件读出来的原始字符串绕过了处理器要么InputFileName路径写错程序读到了另一个同名文件还有一种情况是模板里花括号没转义解析到一半就中断了。解决先确认Response.Content是从处理器的Content属性取的而不是自己用文件读取函数读的。再确认路径指向的是你正在编辑的那个文件——把修改一个明显字比如标题加个感叹号作为测试改完刷新能看到变化说明路径对了。最后检查 HTML 里的{ }有没有双写。5.3 现象请求发出去了浏览器控制台报 404现象按下按钮浏览器开发者工具的 Network 面板里能看到请求但状态码是 404响应体里是一段错误页。原因路径没对上。可能是处理动作的路径前缀和页面里写的请求地址不一致一个写/tasks/list一个写/api/tasks/list也可能是大小写、结尾斜杠的差异。还有人是在 WebModule 里加了动作但忘了启用程序根本没注册这条路由。解决先把页面里的请求地址复制出来用命令行curl -i 完整地址直接打看能不能通。命令行通、页面不通说明是相对路径的问题——页面本身的地址带了一段前缀相对路径会拼在前面。统一改成以/开头的绝对路径问题立刻消失。5.4 现象返回 200页面却纹丝不动现象Network 面板里状态码 200响应体也有内容但页面看上去什么都没变。原因三种可能。一是hx-target的选择器没匹配到元素比如写错了 id或者 id 在循环里重复了二是hx-swap的取值和目标元素不匹配比如对一个本身要被替换的元素用了innerHTML看起来就像没变化三是服务端返回了空内容。解决先看响应体是不是空的空的就查服务端分支逻辑八成是某个提前Exit没返回内容。再看选择器在浏览器控制台里用document.querySelector(你的选择器)执行一下返回null就是它的问题。最后检查 id 唯一性——在循环里用固定的 id 是很常见的错误改成一串带序号的task-1、task-2就好了。5.5 现象中文变成一堆问号现象页面能出来但所有中文都显示成问号或者一堆看不懂的字符。原因Response.ContentType只写了text/html没写字符集或者写的是utf-8但模板文件本身保存成了别的编码格式。解决把响应的ContentType固定写成text/html; charsetutf-8模板文件统一用 UTF-8 保存。还有一个隐蔽情况某些编辑器保存时会自动加 BOM 头这个头会被当成正文输出导致页面最前面出现一行空白或者奇怪的字符——用「无 BOM 的 UTF-8」保存或者用十六进制查看器看一眼文件开头就能确认。提示把这五条整理成一个自己的检查清单每次页面不对时从上往下走一遍。我见过的大部分「怎么也调不通」都是这五条里的某一条。6. 下一步学什么从跑通第一个例子到改得动别人的代码跑到待办清单这一步你其实已经把这套技术的主干走完了。接下来容易犯的错是「什么属性都学一遍」结果学了一堆冷门的反而不会用。更有效的顺序是先补三块按顺序来就行顺序学什么为什么排在这里第一块布局模板RenderBody、LayoutPage、Import页面一多公共导航和页脚必须抽出来否则改一次要动十个文件第二块会话与安全内存会话、CSRF、输入校验一旦有登录和写操作这些不是可选项第三块高级属性hx-trigger的复合写法、hx-push-url、hx-include需要「地址栏能分享」「把多个字段带给服务器」时才用得上第一块优先学的原因很实际你现在的三个页面可能各自都有一份导航栏改个菜单要改三遍改完还可能漏一处。布局模板的思路是把公共部分抽成骨架每个页面只保留自己那块内容占位符负责「把内容塞进来」。抽完之后改一次全站生效那种松一口气的感觉特别明显。第二块是绕不开的门槛。会话管理最省事的做法是放在内存里——一个会话表登录成功就写进去请求进来时按凭据查。但这里有个坑要提前知道内存会话在程序重启后就没了所有用户被迫重新登录。做演示无所谓上线前要么换成持久化存储要么确认这个行为在你的场景里可接受。同时别忽略输入校验和 CSRF 防护只要页面能提交数据这两件事就要一起考虑不能等出事再补。第三块等真的需要再说。hx-push-url让地址栏跟着变用户按后退键才是自然的hx-include可以把目标元素之外的输入框一起带过去做筛选栏时特别顺手。这些属性看一眼文档就能用没必要提前背。最后说个我自己交过学费的习惯。早期我总觉得「先跑起来再说」于是一个页面里既拼了两行字符串、又混着模板、还顺手写了几行内联脚本当时能跑两周后自己都看不懂了。从那以后我给自己定了一条死规矩只要某个 HTML 片段在第二个地方出现立刻抽成模板只要某个取值超过两处立刻挂到引擎上去。这条规矩救过我很多次尤其是在项目赶进度、所有人都想「先一把梭」的时候。希望帮到你。本文还有配套的精品资源点击获取
