示例工程【免费下载链接】practical-aspnetcorePractical samples of ASP.NET Core 11, 10, 9, 8.0, 7.0, 6.0, 5.0, 3.1, 2.2, and 2.1,projects you can use. Readme contains explanations on all projects.项目地址https://gitcode.com/gh_mirrors/pr/practical-aspnetcore点击查看免费下载本文基于 practical-aspnetcore 仓库中的projects/htmx/hx-replace-url-2示例讲解如何在 ASP.NET Core Minimal API 中配合 HTMX 4使用hx-replace-url属性在 AJAX 请求完成后将浏览器地址栏替换为自定义 URL。读完本文你将掌握hx-replace-url的三种取值语义true/false/ 自定义 URL、它与hx-push-url及HX-Replace-Url响应头的区别以及如何在一个完整的 Minimal API 应用中含反伪造令牌校验落地这一能力。为什么需要替换浏览器地址栏在传统页面中每次交互都会触发整页刷新地址栏 URL 天然与服务端页面一一对应。而 HTMX 的 AJAX 请求只在局部交换 DOM地址栏不会自动变化。若某些业务场景要求局部刷新后地址依然指向正确资源——例如翻页、筛选、切换个人详情页——就需要手动同步地址栏。HTMX 提供了两条同步地址的通道hx-push-url使用history.pushState将新 URL追加进浏览器历史记录后退按钮可以回退到之前的地址hx-replace-url使用history.replaceState用新 URL替换当前历史记录条目后退按钮不会回到被替换掉的地址。两者的取舍在于是否需要保留上一步的可回退性。hx-replace-url适合地址只是当前状态的一种表达、不应产生历史噪声的场景例如列表筛选条件的同步。hx-replace-url 的三种取值取值行为不设置默认请求完成后不修改地址栏hx-replace-urltrue用本次请求的 URL 替换当前地址hx-replace-urlfalse显式禁止替换可用于覆盖继承来的设置hx-replace-url/some/path用给定的自定义 URL 替换当前地址projects/htmx/hx-replace-url-2这个示例的核心正是演示第三种自定义 URL用法——请求的真实端点与地址栏展示的 URL 可以完全解耦。核心示例五种 HTTP 动词 自定义 URLhx-replace-url-2/README.md给出的核心 HTML 片段如下它把五种 HTTP 动词的触发元素与各自的自定义替换 URL 一一对应ul li hx-get/htmx/get hx-replace-url/person/annaGET/li li hx-post/htmx/post hx-replace-url/person/johnPOST/li li hx-put/htmx/put hx-replace-url/person/ahmedPUT/li li hx-patch/htmx/patch hx-replace-url/person/gabyPATCH/li li hx-delete/htmx/delete hx-replace-url/person/danielaDELETE/li /ul观察这段代码可以提炼出两个关键点请求与地址解耦每个li发起的请求都指向/htmx/{verb}端点而地址栏被替换为/person/{name}这类语义化 URL。例如hx-get/htmx/get实际请求的是服务端数据处理端点但用户看到的地址是/person/anna。覆盖全部动词GET、POST、PUT、PATCH、DELETE 五种动词都支持该属性说明地址替换是 HTMX 请求生命周期中的通用能力与请求方法无关。实际页面在 hx-replace-url-2/Program.cs 中采用左右两栏布局左侧演示hx-replace-urltrue用请求 URL 替换右侧演示自定义 URL 替换方便读者在同一页面直接对比两种写法的地址栏差异。服务端实现Minimal API 端点组 统一过滤器该示例的服务端完全由 Minimal API 实现。首先是注册与启用反伪造服务var builder WebApplication.CreateBuilder(); builder.Services.AddAntiforgery(); var app builder.Build(); app.UseAntiforgery();随后将所有 HTMX 端点收敛到一个路由组并挂上统一过滤器见 Program.csvar htmx app.MapGroup(/htmx).AddEndpointFilter(async (context, next) { if (context.HttpContext.Request.Headers.ContainsKey(HX-Request) is false) return Results.Content(); if (context.HttpContext.Request.Method GET) return await next(context); await context.HttpContext.RequestServices.GetRequiredServiceIAntiforgery()!.ValidateRequestAsync(context.HttpContext); return await next(context); });这段过滤器做了两件值得注意的事HTMX 请求识别HTMX 发起的 AJAX 请求都会携带HX-Request: true请求头。过滤器用它判断请求是否来自 HTMX若不是则直接返回空内容防止外部直接调用这些端点拿到不完整的片段响应反伪造校验分流GET 请求直接放行读取类操作不改变状态其余 POST / PUT / PATCH / DELETE 则调用IAntiforgery.ValidateRequestAsync校验令牌不通过会抛出异常并拒绝请求。五个端点本身非常精简统一返回文本片段见 Program.cshtmx.MapGet(/get, (HttpRequest request) { return Results.Content($GET {DateTime.UtcNow}); }); htmx.MapPost(/post, (HttpRequest request) { return Results.Content($POST {DateTime.UtcNow}); }); // PUT、PATCH、DELETE 端点结构相同分别返回 PUT ... 等文本反伪造令牌如何送达前端由于示例的 HTML 是服务端动态生成的令牌可以在生成页面时直接注入。首页端点通过IAntiforgery.GetAndStoreTokens(context)取到令牌对再写入meta namehtmx-config见 Program.csmeta namehtmx-config content{ antiForgery: {headerName : {{ token.HeaderName}}, requestToken : {{token.RequestToken }} } }HTMX 4 支持通过htmx-configmeta 标签注入全局配置。前端脚本监听htmx:config:request事件在每次请求发出前把令牌写入请求头GET 除外见 Program.csdocument.addEventListener(htmx:config:request, (evt) { let httpVerb evt.detail.ctx.request.method.toUpperCase(); if (httpVerb GET) return; 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); } } });这样前端自动附加令牌、后端统一校验令牌形成一条完整的 CSRF 防护链而hx-replace-url的地址替换逻辑完全独立于这条链路运行。与仓库内同主题变体的对比practical-aspnetcore 的projects/htmx目录下围绕地址同步提供了多个互补示例总览见 Readme.md适合放在一起理解示例目录机制适用场景hx-replace-url属性hx-replace-urltrue用请求 URL 替换地址不产生历史记录hx-replace-url-2属性hx-replace-url/person/anna用自定义 URL 替换地址请求与地址解耦header-hx-replace-url响应头HX-Replace-Url由服务端决定替换地址前端无需写属性push-url属性hx-push-url把地址推入历史记录后退可回退其中header-hx-replace-url展示了另一种思路前端完全不加属性由服务端在响应中通过response.Headers.Append(HX-Replace-Url, /get)指定替换目标见 header-hx-replace-url/Program.cs。当替换成什么地址属于服务端业务逻辑时这种方式更合适而当地址是前端交互的固定产物时hx-replace-url属性更直观。运行与验证项目位于projects/htmx/hx-replace-url-2包含独立的解决方案文件 hx-replace-url-2.sln 与项目文件 hx-replace-url-2.csproj。其目标框架为net10.0启用了ImplicitUsings与预览版语言特性LangVersionpreview。运行方式cd projects/htmx/hx-replace-url-2 dotnet run浏览器打开首页后依次点击右侧栏自定义 URL 组的五个列表项观察两处现象地址栏变化每次点击后地址被替换为对应的/person/{name}且页面不刷新后退按钮地址是被替换而非追加因此连续点击后按浏览器后退不会逐个回退到之前的/person/xxx地址——这与push-url示例的行为形成鲜明对比。同时可打开开发者工具查看网络请求非 GET 请求会携带反伪造令牌头而 GET 请求不带若直接以非 HTMX 方式不带HX-Request头访问/htmx/post将收到空响应。小结hx-replace-url是 HTMX 提供的高频实用属性它让局部刷新 地址同步成为可能。hx-replace-url-2示例证明了它可以与全部五种 HTTP 动词配合并支持将地址替换为与请求 URL 完全不同的自定义值从而在保持真实端点路径私密性的同时对外呈现语义化地址。配合本仓库中的hx-replace-urltrue取值、header-hx-replace-url响应头方案与push-url历史记录方案三个兄弟示例你可以根据是否保留历史、由谁决定地址这两个维度为自己的应用挑选最合适的地址同步方案。赞分享示例工程【免费下载链接】practical-aspnetcorePractical samples of ASP.NET Core 11, 10, 9, 8.0, 7.0, 6.0, 5.0, 3.1, 2.2, and 2.1,projects you can use. Readme contains explanations on all projects.项目地址https://gitcode.com/gh_mirrors/pr/practical-aspnetcore点击查看免费下载相关推荐htmx 的 HX-Replace-Url 响应头无痕替换浏览器地址栏 URL 的完整指南htmx 的 HX Replace Url 响应头无痕替换浏览器地址栏 URL 的完整指南 HX Replace Url 是 htmx 提供的标准响应头之一前端Web框架ASP.NET Core Minimal API 中的 hx-indicator为 HTMX 4 的 AJAX 请求打造自定义加载指示器practical-aspnetcore 实战示例ASP.NET Core Minimal API 中的 hx indicator为 HTMX 4 的 AJAX 请求打造自定义加载指示器practical示例工程htmx hx-replace-url 属性完全指南URL 替换、HX-Replace-Url 响应头与 History API 实战htmx hx replace url 属性完全指南URL 替换、HX Replace Url 响应头与 History API 实战 hx replace前端Web框架上一篇Spring Data R2DBC与WebFlux整合构建高性能响应式API的完整指南下一篇Immich 地图视图完整指南三步开启地理位置让照片自己归位到地图创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考