使用 hx-on 监听 HTMX 事件:在 ASP.NET Core Minimal API 中处理 AJAX 请求前后的钩子

原创2026-10-14 13:01:482,329 阅读
文章标签:示例工程

使用 hx-on 监听 HTMX 事件:在 ASP.NET Core Minimal API 中处理 AJAX 请求前后的钩子

导读

hx-on 是 HTMX 提供的内联事件处理属性,允许开发者直接在 HTML 元素上以 JavaScript 响应 HTML 事件与 HTMX 生命周期事件。本文以 practical-aspnetcore 仓库中的 hx-on-2 示例 为骨架,完整讲解如何使用 hx-on::before:request 与 hx-on::after:request 在 AJAX 请求发出前、完成后执行自定义逻辑,并结合其背后的 ASP.NET Core Minimal API 源码(含反伪造令牌校验、HX-Request 头校验、五种 HTTP 动词端点)做源码级剖析。读完本文,你将掌握 hx-on 的双冒号命名空间事件语法、事件冒泡的父级统一监听技巧,以及如何在一个真实可运行的全栈示例中落地这套方案。

一、认识 hx-on:同时覆盖 HTML 事件与 HTMX 事件

hx-on 的核心价值在于:它把事件监听从 JavaScript 文件搬到了 HTML 属性上,形成一种"内联声明式"的事件处理方式。根据 hx-on 系列示例 的定位,它被拆成两个互补的例子:

  • hx-on:处理 HTML 事件,如 click、mouseover、dblclick;
  • hx-on-2:处理 HTMX 事件,如 htmx:before:request、htmx:after:request。

两者在语法上有一个关键区别:HTMX 事件是命名空间事件(以 htmx: 前缀命名),因此在 hx-on 中需要用双冒号 :: 来分隔:

事件类型 属性写法 示例
HTML 事件 hx-on:事件名 hx-on:click="alert('click')"
HTMX 命名空间事件 hx-on::事件名 hx-on::before:request="alert('before')"

这一点在 hx-on-2 的 README 中被明确使用:属性值写为 hx-on::before:request="alert('before')",双冒号表明后面跟的是一个带命名空间的 HTMX 事件,而非普通 HTML 事件。

另一个值得强调的机制是事件冒泡:HTMX 的 before:request / after:request 等事件从发起请求的元素(<li>)触发后会沿 DOM 向上冒泡。因此可以把 hx-on 写在父容器 <ul> 上,统一捕获所有子元素发起的请求事件,实现类似事件委托的效果,无需在每一个 <li> 上重复书写。

二、核心示例:在请求发出前与完成后各弹一次提示

hx-on-2 的核心 HTML 结构如下(原文完整保留):

<ul hx-on::before:request="alert('before')" hx-on::after:request="alert('after')">
    <li hx-get="/htmx">GET</li>
    <li hx-post="/htmx">POST</li>
    <li hx-put="/htmx">PUT</li>
    <li hx-patch="/htmx">PATCH</li>
    <li hx-delete="/htmx">DELETE</li>
</ul>

行为解读:

  1. 点击任意一个 <li>(例如 GET),HTMX 会基于 hx-get 属性向 /htmx 发起 AJAX 请求;
  2. 请求正式发出前,htmx:before:request 事件触发,<ul> 上的 hx-on::before:request 回调执行,浏览器弹出 before 提示;
  3. 请求完成、响应返回并处理完毕后,htmx:after:request 事件触发,弹出 after 提示。

由此,"请求前 → 请求后"两个时间点的钩子全部由一行属性完成声明,不需要任何额外的 addEventListener 代码。这正是 hx-on 相对传统事件监听的直观优势:逻辑就近放在 DOM 上,语义一目了然。

在 Program.cs 中,这段 <ul> 被嵌入由服务端生成的 HTML 字符串内,并对 <li> 施加了 cursor:pointer 样式提示可点击。

三、源码级剖析:一个完整可运行的 ASP.NET Core 实现

hx-on-2 并不是一个静态 HTML 页面,而是一个完整的 ASP.NET Core Minimal API 项目。其 Program.cs 与仓库中的 all-verbs 示例 高度同源——可以推断该示例是在 all-verbs 的基础上,仅在 <ul> 上追加了两行 hx-on 属性而得到的进阶版本,用于演示"全动词 + 事件钩子"的组合。整个实现可分为四个层次。

3.1 反伪造令牌的基础设施

var builder = WebApplication.CreateBuilder();
builder.Services.AddAntiforgery();
var app = builder.Build();

app.UseAntiforgery();

项目启用了 ASP.NET Core 内置的 Antiforgery(反伪造)服务,这在后面服务端对非 GET 请求的校验中扮演关键角色。

3.2 服务端生成的页面与令牌下发

GET / 端点通过 IAntiforgery.GetAndStoreTokens 获取并存储令牌,然后把它写入 <meta name="htmx-config"> 标签中,让 HTMX 4 能读取这份运行时配置:

<meta name="htmx-config" content='{ "antiForgery": {"headerName" : "{{ token.HeaderName}}", "requestToken" : "{{token.RequestToken }}" } }'>

接着通过一段内联脚本监听 htmx:config:request 事件,在每个请求即将发出时(发生在 before:request 之后的参数收集阶段)把反伪造令牌注入请求:

document.addEventListener("htmx:config:request", (evt) => {
    let httpVerb = evt.detail.ctx.request.method.toUpperCase();
    if (httpVerb === 'GET') return;   // GET 不需要令牌

    let antiForgery = htmx.config.antiForgery;
    if (antiForgery) {
        // 表单里已带令牌则短路
        if (evt.detail.ctx.request.body.has(antiForgery.formFieldName))
            return;

        if (antiForgery.headerName) {
            evt.detail.ctx.request.headers[antiForgery.headerName] = antiForgery.requestToken;
        } else {
            evt.detail.ctx.request.body.set(antiForgery.formFieldName, antiForgery.requestToken);
        }
    }
});

这段代码在仓库中是一个反复出现的模式(如 htmx-after-on-load/Program.cs、htmx-config-request 中都有),它保证了 POST/PUT/PATCH/DELETE 等改变状态的方法携带 CSRF 令牌。

3.3 /htmx 路由组与端点过滤器

服务端把 /htmx 下的五个动词端点组合进同一个路由组,并挂上一个端点过滤器做两道关卡:

var htmx = app.MapGroup("/htmx").AddEndpointFilter(async (context, next) =>
{
    // 关卡一:请求必须来自 HTMX,否则返回空内容
    if (context.HttpContext.Request.Headers.ContainsKey("HX-Request") is false)
        return Results.Content("");

    // 关卡二:非 GET 请求必须通过反伪造校验
    if (context.HttpContext.Request.Method == "GET")
        return await next(context);

    await context.HttpContext.RequestServices.GetRequiredService<IAntiforgery>()!.ValidateRequestAsync(context.HttpContext);
    return await next(context);
});
  • HX-Request 头是 HTMX 4 客户端在发起 AJAX 请求时自动附带的标记头,这里用它拒绝非 HTMX 的直接访问;
  • GET 视为只读请求直接放行;其余动词统一走 ValidateRequestAsync 校验令牌。

3.4 五个动词端点

路由组下为每种 HTTP 动词映射了同路径 / 的端点,统一返回带动词前缀的时间戳文本:

htmx.MapGet("/",    (HttpRequest request) => Results.Content($"GET => {DateTime.UtcNow}"));
htmx.MapPost("/",   (HttpRequest request) => Results.Content($"POST => {DateTime.UtcNow}"));
htmx.MapPut("/",    (HttpRequest request) => Results.Content($"PUT => {DateTime.UtcNow}"));
htmx.MapPatch("/",  (HttpRequest request) => Results.Content($"PATCH => {DateTime.UtcNow}"));
htmx.MapDelete("/", (HttpRequest request) => Results.Content($"DELETE => {DateTime.UtcNow}"));

因为 <ul> 上的 hx-on::before:request / hx-on::after:request 会捕获所有子 <li> 的事件,所以无论点击哪一个动词,浏览器端都会先弹出 before、请求返回后再弹出 after,而响应内容则被 HTMX 默认交换进发起请求的 <li> 中。

四、运行与验证

4.1 环境前提

  • 仓库根目录的 global.json 指定了 SDK 10.0.0(rollForward: major、allowPrerelease: true);
  • 项目文件 all-verbs.csproj 目标框架为 net10.0,启用了 ImplicitUsings 与 LangVersion=preview;
  • HTMX 4 浏览器库(htmx.org@4.0.0)通过 jsDelivr CDN 直接引入,不依赖任何 HTMX NuGet 包(这一点在 htmx 目录总览 中有明确说明)。

4.2 启动步骤

# 在项目目录下还原并运行
cd projects/htmx/hx-on-2
dotnet restore
dotnet run

浏览器打开 http://localhost:5000(或启动日志中打印的实际地址),页面会展示 "All verbs supported in HTMX" 标题与五个可点击的动词项。

4.3 预期行为与验证

  1. 点击 GET:先弹出 before,点击确定后请求发出,响应 GET => <UTC 时间> 被交换到页面;随后弹出 after。
  2. 依次点击 POST、PUT、PATCH、DELETE:均先 before 后 after,且响应文本前缀与动词一一对应。期间可通过浏览器 DevTools 的 Network 面板确认非 GET 请求都携带了反伪造请求头。
  3. 直接在浏览器地址栏访问 /htmx(不带 HX-Request 头):由于端点过滤器的第一道关卡,返回的是空内容——这是预期的防直连行为。

若想脱离浏览器用命令行验证各端点,可手动附带 HX-Request 头模拟 HTMX 客户端(此时非 GET 请求还需附带有效的反伪造令牌,否则会被第二道关卡拦截):

curl -H "HX-Request: true" http://localhost:5000/htmx

五、扩展:HTMX 事件生命周期中的其他钩子

before:request 与 after:request 只是 HTMX 事件体系的一部分,仓库中还提供了多个可相互对照的事件示例,帮助你构建完整的请求生命周期认知:

  • htmx-config-request:在 HTMX 收集完请求参数之后触发,可用来追加或修改将要发送的参数(本例的反伪造令牌注入正是利用了这一事件);
  • htmx-after-on-load:监听 htmx:after:init,在元素被 HTMX 初始化完成后执行逻辑;
  • htmx-response-error:监听 htmx:response:error,统一处理 HTTP 错误响应(网络错误、超时、swap 失败等则归入 htmx:error)。

把这些事件与 hx-on 结合,可以得到一个朴素的事件时序:元素初始化(after:init)→ 参数收集(config:request)→ 请求发出前(before:request)→ 响应处理后(after:request)→ 出错时(response:error)。

六、注意事项与实践建议

  1. alert() 只是演示,生产环境建议替换:弹窗会阻塞页面线程,干扰用户操作。实践中应改用 console.log、更新页面上的状态指示器(如结合 hx-indicator 的示例思路显示 loading 状态)或调用业务函数。
  2. 父级监听依赖事件冒泡:hx-on 写在 <ul> 上之所以能覆盖所有 <li>,前提是 htmx:before:request / htmx:after:request 会从发起元素冒泡到祖先节点。若业务上需要在某个请求上单独处理,也可以把 hx-on 直接写在该元素上,两者可以并存。
  3. 命名空间事件必须用双冒号:hx-on::before:request 与 HTML 事件的 hx-on:click 写法不同,写错分隔符会导致事件无法被捕获。
  4. CSRF 校验是安全底线:本示例中 POST/PUT/PATCH/DELETE 都被服务端强制要求反伪造令牌,浏览器端借助 htmx:config:request 自动注入。迁移到自己的项目时,务必保留这一层校验,而不是只做"能跑通"。
  5. 留意项目文件的命名:hx-on-2 目录中的解决方案与工程文件沿用了 all-verbs 的命名(all-verbs.sln 引用 all-verbs.csproj),这是仓库内示例复用工程模板留下的痕迹,不影响 dotnet run 直接运行。

综上,hx-on 提供了一种极简的"属性即监听器"方案,让请求前后钩子、甚至任意 HTMX 生命周期事件都能以声明式的方式就近写在 DOM 上;再配合 ASP.NET Core Minimal API 的反伪造校验与 HX-Request 关卡,即可构建出一个既有交互反馈、又具备基本安全防护的完整 HTMX 全栈示例。

登录后查看全文
practical-aspnetcore