Delphi 12整合HTMX与WebStencils：基于WebBroker快速开发Web页面

简介：面向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 整个删掉，改成在标签上写属性。它真正需要你记住的动作只有五个：去哪儿要数据、要回来放哪儿、用什么方式要、要回来怎么换、什么时候要。

同样的勾选需求，HTMX 版本长这样：

<!-- 勾选即提交，服务器直接返回一段新的 <li>，整条替换掉 --> <li id="task-3"> <input type="checkbox" hx-post="/tasks/3/toggle" hx-target="#task-3" hx-swap="outerHTML"> 写周报 </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 id="tasklist"> @ForEach task in tasks <li class="task @if task.Done then done"> <input type="checkbox" hx-post="/tasks/@task.Id/toggle" hx-target="closest li" hx-swap="outerHTML"> @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，走这条路径：

1. 菜单里选新建工程，找到 Web 类目下的 Web Server Application；
2. 类型先选独立运行的那种（stand-alone），它自带一个小型服务器，不用配 IIS 或 Apache，学习阶段最省事；
3. 向导会让你填端口，先用一个不常用的，比如 8080；
4. 工程建好后会看到一个 WebModule，这就是整个应用的请求入口；
5. 直接运行，浏览器访问http://localhost:8080，能出东西就算通了。

如果浏览器提示无法连接，先看两件事：程序是否真的在运行（有些环境会在控制台窗口里等你按回车才启动），以及端口有没有被别的程序占掉。换个端口重来一遍，比在那里猜半天快得多。

第一段代码就写在 WebModule 的默认处理动作里，目的是确认「请求能进来、响应能出去」：

// WebModule 的默认处理动作，先返回一段最原始的 HTML procedure TWebModule1.WebModule1DefaultHandlerAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); begin // 字符集必须写全，少了 charset 中文就会变问号 Response.ContentType := 'text/html; charset=utf-8'; Response.Content := '<h1>你好，世界</h1>'; end;

参数含义值得逐一看清：Request是这次进来的请求，表单字段、查询参数、请求头都从它身上取；Response是你要发回去的东西，ContentType告诉浏览器这是什么格式，Content就是正文；Handled是一个开关，你把它设成 True，表示这个请求我处理完了，别再往下传。新手常犯的错是只改Content不管ContentType，页面能显示，但中文全是乱码，然后怀疑是编码问题折腾半天。

3.2 WebModule、WebStencilsEngine、WebStencilsProcessor 各管什么

这三个名字长得很像，功能完全不同，混淆了就会写出「模板改了没生效」这类玄学问题。用一句话概括：模块管分发，引擎管数据，处理器管一次渲染。

用法上的分界很清楚：像站点名称、当前登录用户、版本号这种每个页面都要用的值，挂在引擎上，用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 lang="zh-CN"> <head> <meta charset="utf-8"> <title>@Title</title> <script src="/js/htmx.min.js"></script> </head> <body> <h1>@Title</h1> <p>服务器时间：@Now</p> </body> </html>

再改处理动作，把「拼字符串」换成「过一遍模板引擎」：

procedure TWebModule1.WebModule1DefaultHandlerAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); begin Response.ContentType := 'text/html; charset=utf-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-swap="innerHTML"> 刷新清单 </button> <div id="tasklist"> <!-- 这里的内容会被服务器返回的片段整体替换掉 --> </div>

服务端这边，给 WebModule 加一个处理动作，路径设成/tasks/list，逻辑是拿数据、渲染片段模板、返回：

procedure TWebModule1.WebModule1TaskListAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); begin Response.ContentType := 'text/html; charset=utf-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-swap="innerHTML"> <input type="text" name="title" placeholder="要做的事"> <button type="submit">添加</button> </form>

服务端从请求里取字段：

procedure TWebModule1.WebModule1AddTaskAction(Sender: TObject; Request: TWebRequest; Response: TWebResponse; var Handled: Boolean); var Title: string; begin // POST 表单取值用 ContentFields，GET 的查询参数用 QueryFields Title := Trim(Request.ContentFields.Values['title']); if Title = '' then begin // 出错也要返回片段，前端才知道该显示什么 Response.ContentType := 'text/html; charset=utf-8'; Response.Content := '<p class="err">内容不能为空</p>'; Exit; end; AddTask(Title); // 存进你的数据源 // 存完立刻返回最新清单，前端负责替换，不需要额外刷新 Response.ContentType := 'text/html; charset=utf-8'; WebStencilsEngine1.AddVar('tasks', GetTaskList); WebStencilsProcessor1.InputFileName := 'wwwroot\templates\tasks_list.html'; Response.Content := WebStencilsProcessor1.Content; end;

两个细节值得单独说。第一，ContentFields和QueryFields别用混：POST 表单的数据在ContentFields，URL 上?a=1这种在QueryFields，用错了取出来永远是空字符串，且不报错，非常难查。第二，处理完之后不要返回空内容。HTMX 拿到空响应，行为是「什么都不换」，页面看起来像没反应——很多新手以为请求失败了，其实请求成功了，只是回了个空字符串。

4.3 hx-swap 和 hx-trigger：换法与时机的调节旋钮

hx-swap控制「拿回来的 HTML 怎么放进去」，常用的几种：

hx-trigger控制「什么时候发请求」，默认是点击，可以改成change（勾选框变化即提交）、keyup changed delay:500ms（输入停下半秒再查，避免每敲一个字发一次）、load（元素加载完就请求）、every 2s（定时刷新）。新手最该先掌握的是delay，因为实时搜索如果不加延迟，输入十个字就是十次请求，服务器直接被你自己刷爆。

还有一个好用的属性hx-select：服务器返回一大段 HTML，你只想要其中某一块。比如后端为了复用，返回的还是完整清单，但这次只想更新统计数字，就可以用hx-select="#stats"把那一块挑出来，剩下的丢掉。这招在多处复用同一个模板时特别省事。

4.4 合起来做一个能加能删的待办清单

最后把删除和勾选补上。这两处用outerHTML更合适，因为服务器返回的就是完整的一条记录：

<!-- 单条记录：勾选后整条替换，删除后整条消失 --> <li id="task-@task.Id" class="task @if task.Done then done"> <input type="checkbox" hx-post="/tasks/@task.Id/toggle" hx-target="#task-@task.Id" hx-swap="outerHTML"> <span>@task.Title</span> <button hx-delete="/tasks/@task.Id" hx-target="#task-@task.Id" hx-swap="outerHTML"> 删除 </button> </li>

hx-delete是 HTMX 提供的另一种请求方式，和hx-post、hx-put、hx-patch一样，都只是换个 HTTP 方法而已，写法完全一致。服务端处理删除时，直接返回空内容加上hx-swap="outerHTML"，元素就被移除了——这个组合是删除操作最省事的方式，不用写任何前端删除逻辑。

到这里，你已经用到了 GET、POST、DELETE 三种请求，用到了hx-target、hx-swap、hx-trigger、hx-select四个属性。剩下的什么分类筛选、状态过滤，本质都是同一套：把筛选条件挂在请求参数上，服务端按条件返回过滤后的片段，前端负责换上去。真正需要你动的脑筋在服务端，而不在 HTML 上——这正是这套组合想让你接受的分工。

注意：模板里的{ }花括号记得双写转义，否则会被模板引擎当成占位符吃掉，而且报错信息往往指向别的地方，是典型的玄学问题。

5. 新手避坑：五个最容易翻车的现场和对应的解法

这一章的内容全部来自真实的踩坑现场，每一条都按「现象 → 原因 → 解决」写。你不用背，遇到问题时回来对着找就行。五个坑覆盖了新手期八成以上的卡点，剩下的两成基本是拼写错误。

5.1 现象：点了按钮整个页面跳走了

现象：点按钮的一瞬间，整个页面刷新或者跳转到一个空白页，有时候地址栏还变了。

原因：最常见的是表单里的button默认类型是submit，即使你写了hx-post，浏览器仍然会执行原生提交；另一种是用了<a>标签但没写href或者写了，点击触发的是原生跳转而不是 HTMX 请求。

解决：把按钮显式声明成type="button"，只有真正要提交表单的那一个才用type="submit"；链接类操作用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; charset=utf-8'，模板文件统一用 UTF-8 保存。还有一个隐蔽情况：某些编辑器保存时会自动加 BOM 头，这个头会被当成正文输出，导致页面最前面出现一行空白或者奇怪的字符——用「无 BOM 的 UTF-8」保存，或者用十六进制查看器看一眼文件开头就能确认。

提示：把这五条整理成一个自己的检查清单，每次页面不对时从上往下走一遍。我见过的大部分「怎么也调不通」，都是这五条里的某一条。

6. 下一步学什么：从跑通第一个例子到改得动别人的代码

跑到待办清单这一步，你其实已经把这套技术的主干走完了。接下来容易犯的错是「什么属性都学一遍」，结果学了一堆冷门的反而不会用。更有效的顺序是先补三块，按顺序来就行：

第一块优先学的原因很实际：你现在的三个页面可能各自都有一份导航栏，改个菜单要改三遍，改完还可能漏一处。布局模板的思路是把公共部分抽成骨架，每个页面只保留自己那块内容，占位符负责「把内容塞进来」。抽完之后，改一次全站生效，那种松一口气的感觉特别明显。

第二块是绕不开的门槛。会话管理最省事的做法是放在内存里——一个会话表，登录成功就写进去，请求进来时按凭据查。但这里有个坑要提前知道：内存会话在程序重启后就没了，所有用户被迫重新登录。做演示无所谓，上线前要么换成持久化存储，要么确认这个行为在你的场景里可接受。同时别忽略输入校验和 CSRF 防护，只要页面能提交数据，这两件事就要一起考虑，不能等出事再补。

第三块等真的需要再说。hx-push-url让地址栏跟着变，用户按后退键才是自然的；hx-include可以把目标元素之外的输入框一起带过去，做筛选栏时特别顺手。这些属性看一眼文档就能用，没必要提前背。

最后说个我自己交过学费的习惯。早期我总觉得「先跑起来再说」，于是一个页面里既拼了两行字符串、又混着模板、还顺手写了几行内联脚本，当时能跑，两周后自己都看不懂了。从那以后，我给自己定了一条死规矩：只要某个 HTML 片段在第二个地方出现，立刻抽成模板；只要某个取值超过两处，立刻挂到引擎上去。这条规矩救过我很多次，尤其是在项目赶进度、所有人都想「先一把梭」的时候。希望帮到你。

本文还有配套的精品资源，点击获取