This is a viewer only at the moment see the article on how this works.
To update the preview hit Ctrl-Alt-R (or ⌘-Alt-R on Mac) or Enter to refresh. The Save icon lets you save the markdown file to disk
This is a preview from the server running through my markdig pipeline
Friday, 02 May 2025
HTMX 是一个强大的 JavaScript 图书馆, 它允许您创建动态的网络应用程序, 最小的 JavaScript 。 它允许您提出 AJAX 请求, 交换 HTML 内容, 并直接处理 HTML 属性中的事件 。 我使用 HTMX 已有两年左右的时间了, 并且每个项目我都越来越了解它的能力; 更重要的是它的局限性 。
但是,我仍然不声称对它有专家知识。我只是想分享一下我在旅途中学到的一些东西。
随行条款: 本篇文章的重点是HTMX的事件系统、扩展和高级定制。关于部分浏览的 ASP.NET 核心集成模式, HTMX.NET 和页码见我的随附文章: 带有ASP.net核心部分的HTMXHTMX:服务器-Side文艺复兴.
请求准备阶段是HTMX在发送到服务器之前配置请求的阶段。 这包括设置信头、添加参数和处理用户输入。 在此阶段触发以下事件:
flowchart LR
A[htmx:configRequest] --> B[htmx:confirm] --> C[htmx:prompt] --> D[htmx:abort]
请求的生命周期阶段是HTMX向服务器发送请求并处理回复的周期阶段。
flowchart LR E[htmx:beforeRequest] --> F[htmx:request] --> G[htmx:afterRequest]
反应处理阶段是HTMX处理服务器响应并更新DOM的处理阶段。
flowchart LR
H[htmx:beforeOnLoad] --> I[htmx:onLoad]
I --> J[htmx:beforeSwap] --> K[htmx:swap] --> L[htmx:afterSwap]
L --> M[htmx:afterSettle] --> N[htmx:afterOnLoad]
HTMX 在历史管理阶段更新浏览器历史和 URL 。 在此阶段触发以下事件 :
flowchart LR A[htmx:historyRestoreRequest] A --> B[htmx:historyPopped] B --> C[htmx:historyRestorePage]
正如您可以看到 HTMX 提供了一些事件, 您可以连接到这些事件来修改请求或回应, 甚至历史; HTMX 是一个如此紧凑的系统, 做一个LOT 。 您可以使用其中的每一个来修改 HTMX 如何以非常全面的方式与服务器/ 客户端进行互动 。
HTMX最强大的一个方面是: 创建扩展名 来扩展它的能力。 htmx:configRequest 以在请求中添加额外参数。当您想要将额外数据传送到服务器而不必修改 HTML 或 JavaScript 代码时,此选项非常有用。
其它分机可能会被勾勾勾 htmx:beforeRequest (b) 在收到请求之前修改请求;但 之后 勾勾勾 configRequest; 如 的 beforeRequest 类似的东西 HX-Vals 和 HX-Includes 已经附在背面(在有效载荷\查询字符串中)。
你连勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾勾 htmx:afterSwap 在内容被互换后执行动作。 阿尔卑山 或 文学 您可以在最小代码下创建强大的动态应用程序。
HTMX 提供一些内置扩展像 hx-boost 和 hx-swap-oob 允许您在不写任何自定义代码的情况下增强 HTMX 的功能。然而,有时您需要创建自己的扩展以达到特定要求。
例如,您可能需要在您的请求中添加自定义信头, 修改请求的有效载荷, 或者以独特的方式处理具体事件 。
实现HTMX为您提供一些方便的整合点:
{
/**
* init(api)
* Called once when the extension is initialized.
* Use it to set up internal state, store references, or access HTMX utility functions via the api parameter.
*/
init: function(api) {
return null;
},
/**
* getSelectors()
* Returns additional CSS selectors that HTMX should monitor.
* Useful if your extension needs to handle custom elements or dynamic behavior.
*/
getSelectors: function() {
return null;
},
/**
* onEvent(name, evt)
* Called on every HTMX event (e.g., htmx:beforeRequest, htmx:afterSwap).
* Return false to cancel the event or stop propagation.
*/
onEvent: function(name, evt) {
return true;
},
/**
* transformResponse(text, xhr, elt)
* Modify the raw response text before it is parsed and swapped into the DOM.
* Use this to sanitize or preprocess HTML.
*/
transformResponse: function(text, xhr, elt) {
return text;
},
/**
* isInlineSwap(swapStyle)
* Return true if your extension will handle this swap style manually.
* This tells HTMX to skip default behavior.
*/
isInlineSwap: function(swapStyle) {
return false;
},
/**
* handleSwap(swapStyle, target, fragment, settleInfo)
* Perform custom DOM manipulation if you implement a custom swap style.
* Return true to prevent HTMX's default swap.
*/
handleSwap: function(swapStyle, target, fragment, settleInfo) {
return false;
},
/**
* encodeParameters(xhr, parameters, elt)
* Modify or serialize request parameters before sending.
* Return null to use default URL/form encoding.
* Return a string to override with a custom payload (e.g., JSON).
*/
encodeParameters: function(xhr, parameters, elt) {
return null;
}
}
HTMX 提供一些预建扩展件 有关在这里读取.
举例说,便便 内嵌扩展 json-encode 允许您在请求的正文中发送 JSON 数据, 而不是 URL 编码的窗体数据。 如果您想要向服务器发送复杂的数据结构或阵列, 这会有用 。
你可以看到,这个钩子连成3个事件
init - 设置扩展范围并储存HTMX API的参考文献onEvent - 设置 Content-Type 标题到 application/json 当请求被配置时encodeParameters - 推翻默认 URL 编码格式编码,并将参数序列化为 JSON。它还返回一个字符串,以防止 HTMX 使用默认 URL 编码格式编码。(function() {
let api
htmx.defineExtension('json-enc', {
init: function(apiRef) {
api = apiRef
},
onEvent: function(name, evt) {
if (name === 'htmx:configRequest') {
evt.detail.headers['Content-Type'] = 'application/json'
}
},
encodeParameters: function(xhr, parameters, elt) {
xhr.overrideMimeType('text/json')
const object = {}
parameters.forEach(function(value, key) {
if (Object.hasOwn(object, key)) {
if (!Array.isArray(object[key])) {
object[key] = [object[key]]
}
object[key].push(value)
} else {
object[key] = value
}
})
const vals = api.getExpressionVars(elt)
Object.keys(object).forEach(function(key) {
// FormData encodes values as strings, restore hx-vals/hx-vars with their initial types
object[key] = Object.hasOwn(vals, key) ? vals[key] : object[key]
})
return (JSON.stringify(object))
}
})
})()
甚至更简单,但更简单 hx-debug 加上 HX-Debug 请求页头。 这可用于调试和记录目的, 因为它允许您在 Dev 控制台看到原始请求和响应数据 。
(function() {
htmx.defineExtension('debug', {
onEvent: function(name, evt) {
if (console.debug) {
console.debug(name, evt)
} else if (console) {
console.log('DEBUG:', name, evt)
} else {
throw new Error('NO CONSOLE SUPPORTED')
}
}
})
})()
还有更多,包括一个非常强大的 客户端侧推演扩展名 从而允许您使用客户端微博库将返回的 JSON 数据转换为 HTML 。 这对于创建动态 UI 有用, 不必依赖服务器端翻譯 。
例如,在最近的一个项目中,我利用HTMX OOB交换软件更新了表格中的若干行。 为了做到这一点,我想知道表格中目前显示的是哪些行,所以我只更新了可见的行。
export default {
encodeParameters: function (xhr, parameters, elt) {
const ext = elt.getAttribute('hx-ext') || '';
if (!ext.split(',').map(e => e.trim()).includes('dynamic-rowids')) {
return null; // Use default behavior
}
const id = elt.dataset.id;
const approve = elt.dataset.approve === 'true';
const minimal = elt.dataset.minimal === 'true';
const single = elt.dataset.single === 'true';
const target = elt.dataset.target;
const payload = { id, approve, minimal, single };
if (approve && target) {
const table = document.querySelector(target);
if (table) {
const rowIds = Array.from(table.querySelectorAll('tr[id^="row-"]'))
.map(row => row.id.replace('row-', ''));
payload.rowIds = rowIds;
}
}
// Merge payload into the parameters object
Object.assign(parameters, payload);
return null; // Return null to continue with default URL-encoded form encoding
}
}
要使用它,我们需要在我们的 HTMX 配置中添加扩展名 。 所以在您输入点 js 文件( 假设您使用模块; yoy should be) 中, 您可以做类似的事情 :
import dynamicRowIds from "./dynamicRowIds"; // Load the file
htmx.defineExtension("dynamic-rowids", dynamicRowIds); // Register the extension
然后,在任意元素上您想要使用它,您可以添加 hx-ext 值的属性 dynamic-rowids.
<button
hx-ext="dynamic-rowids"
data-target="#my-table"
data-id="@Model.Id"
data-param1="true"
data-param2="false"
data-param3="@Model.Whatever"
hx-post
hx-controller="Contoller"
hx-action="Action"
>
<i class='bx bx-check text-xl text-white'></i>
</button>
这是另一个简单的 HTMX 扩展名, 这次连接到 htmx:configRequest 请求发送前我们正在修改 URL 。 如果您使用基于查询字符串的过滤等, 您想要一些请求来保存已有的过滤器, 而其他请求则不保存( 例如“ name ” 和 “ startdate ” , 但不使用“ page ” 或“ sort ” ) , 此扩展是有用的 。
这是SMIILAR, 与现有的 HTMX 扩展号不完全相同 推进参数
你可以看到我们勾勾勾 onEvent 收听 htmx:configRequest 事件 。
然后我们:
preserve-params-exclude 从元素属性( 如果存在的话) 中从属性中分离出来, 并将其分成一系列要排除的密钥( 因此我们不把它们添加到请求中) 。export default {
onEvent: function (name, evt) {
if (name !== 'htmx:configRequest') return;
const el = evt.detail.elt;
const excludeStr = el.getAttribute('preserve-params-exclude') || '';
const exclude = excludeStr.split(',').map(s => s.trim());
const currentParams = new URLSearchParams(window.location.search);
const newParams = new URLSearchParams(evt.detail.path.split('?')[1] || '');
currentParams.forEach((value, key) => {
if (!exclude.includes(key) && !newParams.has(key)) {
newParams.set(key, value);
}
});
evt.detail.path = evt.detail.path.split('?')[0] + '?' + newParams.toString();
return true;
}
};
在这里,我用的是必需的 HTMX.Net 其标签助手的标签。 hx-controller 和 hx-action 是为您生成正确的 HTMX 属性的标签助手。以及 hx-route-<x> 用于在路径中传递值。这非常有用,因为它允许您使用 C# 代码生成属性的正确值, 而不是在 HTML 中硬编码 。
作为一个扩展,它非常容易使用:
首先,我们需要在我们的 HTMX 配置中添加扩展 。
import preserveParams from './preserveParams.js';
htmx.defineExtension('preserve-params', preserveParams);
注意: 您会注意到默认的 HTMX 扩展使用“ 自动装入” 方法装入扩展 。
// Autoloading the extension and registering it
(function() {
htmx.defineExtension('debug', {
}
如果您在非模块环境中使用 HTMX 。 但是, 如果您使用模块( 应该是模块) , 最好使用 import 将扩展的语句加载到扩展的语句,然后明确将其注册为与您的 htmx 复选框。这样,您就可以利用树的摇动,只装载所需的扩展。
然后,在你的元素上,你可以添加 hx-ext 值的属性 preserve-params 和 preserve-params-exclude 属性,带有逗号分隔的参数列表,从请求中排除。
<a class="btn-outline-icon"
hx-controller="MyController"
hx-action="MyAction"
hx-route-myparam="@MyParam"
hx-push-url="true"
hx-ext="preserve-params"
preserve-params-exclude="page,sort"
hx-target="#page-content"
hx-swap="innerHTML show:top"
hx-indicator>
<i class="bx bx-search"></i>
</a>
在本案中,由于 event.detail.path 新的 myparam 将替换为我们的新值, 但保留所有其他值( 除非 page 和 sort)这样,我们就可以不断将我们在 URL 中设置的任何过滤器传递到服务器上,而不必担心当我们提出新的请求时这些过滤器丢失。
HTMX的精美之处之一是,它与服务器的许多互动都通过 HTTP 信头发生。这些信头为服务器提供了内容丰富的关于触发请求的内容,允许您从 ASP.NET 核心端点或 Razor 视图中做出适当反应。
同样,这方面的一个关键组成部分是: HTMX.Net。在它提供的许多物品中,有些是整洁的。 Request 用于检测 HTMX 请求的延期。 这有助于确定 HTMX 是否提出请求, 并相应处理 。
它还有自己的机制来发送触发器
Response.Htmx(h => {
h.WithTrigger("yes")
.WithTrigger("cool", timing: HtmxTriggerTiming.AfterSettle)
.WithTrigger("neat", new { valueForFrontEnd= 42, status= "Done!" }, timing: HtmxTriggerTiming.AfterSwap);
});
推推器等... etc... Khalid做了一个伟大的工作 创建了一系列的扩展 方便与HTMX合作 在ASP.NET核心。
这是我用HTMX和ASP.NET核心 工作的工具箱里的关键工具 检查出来!
以下是最有用的信头 HTMX 发送的所有请求的细目 :
我在ASP.NET核心应用软件中广泛使用这些软件。 Request.IsHtmx() , Request.IsHtmxBoosted() 和 Request.IsHtmxNonBoosted() 您可以很容易地检测到HTMX要求并做出相应反应。
例如,我有一个非常简单的扩展名 请求,它让我可以检测 是否请求针对我的主 #page-content (div) 如果是这样的话,我知道我应该寄回一部分
注意: 许多人不知道你可以指定一个“ 全页”为部分, 然后跳过布局 。
if (Request.PageContentTarget())
{
Response.PushUrl(Request);
return PartialView("List", vm);
}
return View("List", vm);
public static class RequestExtensions
{
public static bool PageContentTarget(this HttpRequest request)
{
bool isPageContentTarget = request.Headers.TryGetValue("hx-target", out var pageContentHeader)
&& pageContentHeader == "page-content";
return isPageContentTarget;
}
}
除请求延期外,您还可以创建响应延期,将事件发回客户。这对启动客户附带活动有用。
例如 在我的SweetAlert2整合中 我允许使用服务器设定的触发器关闭对话框 。
document.body.addEventListener('sweetalert:close', closeSweetAlertLoader);
这是由服务器作为 HTMX 触发事件触发的 。
public static void CloseSweetAlert(this HttpResponse response)
{
response.Headers.Append("HX-Trigger" , JsonSerializer.Serialize(new
{
sweetalert = "close"
}));
}
这将触发 sweetalert:close 对话框。您也可以使用该对话框将数据传送给客户 HX-Trigger 头页。 它可用于将数据从服务器传送到客户端, 无需修改 HTML 或 JavaScript 代码 。
正如你所看到的那样,通过在身体上添加一个活动听众,听这些事件是很容易的。我主要使用JSON,因为它总是正确的编码。
以前我写过吐司方法 在这里,但在此也值得一提。非常简单地说,使服务器能够触发客户方的敬酒通知。我设置了此响应扩展的触发程序。
public static void ShowToast(this HttpResponse response, string message, bool success = true)
{
response.Headers.Append("HX-Trigger", JsonSerializer.Serialize(new
{
showToast = new
{
toast = message,
issuccess =success
}
}));
}
然后我就勾入事件客户的侧面 打电话给我 showToast 函数。
import { showToast, showHTMXToast } from './toast';
window.showHTMXToast = showHTMXToast;
document.body.addEventListener("showToast", showHTMXToast);
这又呼唤我, showToast 函数和 well, 显示一个举举; 再查看更多关于它的内容 条款内 .
export function showHTMXToast(event) {
const xhr = event?.detail?.xhr;
let type = 'success';
let message = xhr?.responseText || 'Done!';
try {
const data = xhr ? JSON.parse(xhr.responseText) : event.detail;
if (data.toast) message = data.toast;
if ('issuccess' in data) {
type = data.issuccess === false ? 'error' : 'success';
} else if (xhr?.status >= 400) {
type = 'error';
} else if (xhr?.status >= 300) {
type = 'warning';
}
} catch {
if (xhr?.status >= 400) type = 'error';
else if (xhr?.status >= 300) type = 'warning';
}
showToast(message, 3000, type);
}
HTMX 和 ASP.NET Core 的旋风之旅,我希望你觉得它有用和丰富。如果你有任何问题或评论,请在下面随意评论。
本篇文章是HTMX和ASP.NET Core的两部分系列的一部分:
HTMX官方文件:
图书馆和工具 :
社区资源:
© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.