htmx 速查清单完全指南用 hx-* 属性构建现代交互页面的请求、交换与扩展机制【免费下载链接】reference面向开发者的技术速查清单Cheat Sheets集合整理常见技术、工具与开发流程帮助快速查阅关键信息提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference本篇基于 Quick Reference 仓库中的 htmx 备忘清单系统讲解 htmx 这一面向浏览器、无运行时依赖的 JavaScript 库从hx-get/hx-post等 AJAX 属性、hx-trigger/hx-target/hx-swap三大请求-交换核心到带外交换、表单参数控制、常见交互模式点击编辑、删除行、轮询、上传进度以及完整的 CSS 类状态机、事件与 JavaScript API、请求/响应头协议和扩展体系。读完后可直接在项目 HTML 中复制示例落地并能依据事件与类名对请求生命周期做精准干预和动画处理。htmx 是什么以及如何引入htmx 是一个面向浏览器、无运行时依赖的 JavaScript 库。它的核心思路是不改变HTML 优先的架构而是通过hx-*HTML 属性让页面元素直接发起 AJAX 请求、局部替换 HTML、处理 CSS 过渡并通过扩展机制支持 WebSocket、SSE 等能力。这意味着服务端返回的仍是 HTML 片段前端无需编写数据绑定或状态管理代码。安装方式方式用法下载文件下载htmx.min.js后用普通script引入npmnpm install htmx.org2.0.10Webpack / bundlerimport htmx.org;全局变量window.htmx require(htmx.org);扩展先加载 htmx再加载扩展并使用hx-exthtmx 2.x 是当前主线1.x 仍支持 IE11。生产环境使用 CDN 时建议固定版本并按官方下载页更新integrity值script srchttps://cdn.jsdelivr.net/npm/htmx.org2.0.10/dist/htmx.min.js/script第一个请求最小可用示例只需两个属性——hx-post指定请求地址与方法hx-swap指定响应如何换入button hx-post/clicked hx-swapouterHTML 点击我 /button当按钮被点击时htmx 会向/clicked发出POST请求并用响应 HTML 替换整个按钮outerHTML。这就是 htmx 的基本闭环触发 → 请求 → 响应片段 → 交换进 DOM。五种 AJAX 方法属性作用hx-get/url发起GET请求hx-post/url发起POST请求hx-put/url发起PUT请求hx-patch/url发起PATCH请求hx-delete/url发起DELETE请求默认触发事件由元素类型决定input、textarea、select为changeform为submit其他元素为click。理解这一点可以避免输入框一变化就发请求之外的意外行为——若需要更精细的控制显式使用hx-trigger。请求与交换hx-trigger、hx-target、hx-swaphx-trigger控制何时发请求示例行为hx-triggerclick点击时触发hx-triggermouseenter鼠标进入时触发hx-triggerload元素加载后触发hx-triggerevery 2s每 2 秒轮询hx-triggerkeyup changed delay:500ms值变化且停止输入 500ms 后触发hx-triggerclick once只触发一次hx-triggerclick[ctrlKey]满足事件过滤表达式才触发hx-triggerload, click delay:1s多个触发器组合常用修饰符once只触发一次changed值变化时才触发delay:time延迟触发期间再次触发会重置计时即防抖throttle:time节流触发from:selector监听其他元素上的事件target:selector只处理来自匹配目标的事件。hx-target控制响应换到哪里示例目标解析规则hx-target#result将响应换入指定元素hx-targetthis目标为当前元素hx-targetclosest tr目标为最近的表格行hx-targetnext .panel目标为后续匹配元素hx-targetprevious .item目标为前一个匹配元素hx-targetfind .body目标为当前元素内的匹配子元素closest/next/previous/find让事件源与更新目标解耦例如表格里一个删除按钮可以只替换所在tr行而不需要按钮自己承担 DOM 更新职责。一个防抖搜索的完整示例同时用到了hx-get、hx-trigger修饰符与hx-targetinput nameq hx-get/search hx-triggerkeyup changed delay:500ms hx-target#search-results placeholder搜索 div idsearch-results/divhx-swap控制内容如何交换值行为innerHTML默认替换目标元素内部 HTMLouterHTML替换整个目标元素beforebegin插入到目标元素之前afterbegin插入到目标元素内部开头beforeend插入到目标元素内部结尾afterend插入到目标元素之后delete删除目标元素none不换入主体内容仍处理带外交换常用修饰符修饰符行为swap:1s收到响应后延迟 1 秒再交换settle:500ms交换后等待 500ms 再 settletransition:true使用 View Transitions APIignoreTitle:true忽略响应中的titlescroll:bottom交换后滚动到底部show:top交换后显示目标顶部选择与带外交换Out-of-Band属性行为hx-select#content从响应中选择局部内容换入hx-select-oob#alert从响应中挑选带外内容hx-swap-oobtrue响应片段按id直接更新页面其他位置hx-preserve在交换中保留元素带外交换解决的是一次响应要同时更新页面多个不相关区域的问题服务端只需在响应中为需要额外更新的片段加上hx-swap-oobtrue或用hx-select-oob指定htmx 会按id找到页面其他位置的同名元素并同步更新无需多次请求。一个实战细节表格中的tr、td等片段用于带外交换时建议用template包裹避免浏览器解析 HTML 时丢失结构HTML 解析器允许tr脱离table上下文存在直接出现在响应片段中会被自动归位而丢失目标结构。参数与表单参数提交规则场景规则普通输入元素如果元素有name和值会随请求提交form提交表单内所有输入值非GET请求会包含关联表单的输入值hx-include#extra额外包含其他元素的值hx-paramsnot csrf过滤请求参数hx-vals{page: 1}添加 JSON 格式的额外值htmx:configRequest发请求前用事件修改参数或请求头hx-params与hx-vals的组合可以精确控制出站数据前者负责删排除不想要的字段后者负责加注入分页号、令牌等 JSON 值htmx:configRequest事件则提供最后一道可编程的拦截点。文件上传form hx-post/upload hx-encodingmultipart/form-data hx-target#result input typefile namefile button上传/button /form progress idprogress value0 max100/progress div idresult/div注意hx-encodingmultipart/form-datahtmx 默认以 URL 编码提交参数文件上传必须显式声明 multipart 编码。上传过程中可监听htmx:xhr:progress事件根据 XHR 的progress回调驱动progress条显示上传进度。确认与提示机制说明hx-confirm确定删除请求前显示确认框hx-prompt请输入名称请求前显示提示框htmx:confirm自定义异步确认流程HX-Prompt请求头中包含用户对 prompt 的响应hx-prompt的用户输入会放入HX-Prompt请求头传给服务端若确认流程需要请求后端例如是否有未保存更改可监听htmx:confirm事件用 Promise 异步返回结果替代原生confirm()。常见模式点击编辑典型的展示态 ↔ 编辑态切换两态共用同一目标hx-targetthishx-swapouterHTML由服务端返回不同片段实现状态流转div hx-targetthis hx-swapouterHTML divlabel名字/label: Joe/div divlabel邮箱/label: joeexample.com/div button hx-get/contacts/1/edit编辑/button /div服务器返回表单form hx-put/contacts/1 hx-targetthis hx-swapouterHTML input namefirstName valueJoe input nameemail valuejoeexample.com button保存/button button hx-get/contacts/1取消/button /form表单内的保存按钮提交PUT请求取消按钮hx-get回展示态视图形成无需前端路由的状态机。删除行删除按钮放在tr内但目标声明为closest tr让整行被替换tbody hx-confirm确定删除 hx-targetclosest tr hx-swapouterHTML swap:1s tr tdJoe/td tdjoeexample.com/td tdbutton hx-delete/contacts/1删除/button/td /tr /tbodyhx-swapouterHTML swap:1s中的swap:1s延迟 1 秒执行交换为离场动画留出时间窗。配合 CSS 过渡htmx 在交换前给目标元素添加htmx-swapping类即可实现淡出tr.htmx-swapping td { opacity: 0; transition: opacity 1s ease-out; }延迟加载与轮询div hx-get/graph hx-triggerload img classhtmx-indicator src/spinner.svg alt加载中 /div div hx-get/news hx-triggerevery 2s/divhx-triggerload让图表在页面加载时异步拉取不阻塞首屏hx-triggerevery 2s启动固定间隔轮询服务端可返回 HTTP286状态码来通知客户端停止轮询286 是 htmx 约定的无内容需交换且停止轮询响应非常适合有新数据就推、没有就静默的场景。请求指示器button hx-get/save hx-indicator#indicator 保存 /button img idindicator classhtmx-indicator src/spinner.svg alt加载中请求期间 htmx 会添加htmx-request类默认会让.htmx-indicator显示出来。hx-indicator可指向任意元素包括this不指定时默认查找与触发元素同父级的.htmx-indicator。CSS 类理解交换生命周期htmx 通过一组 CSS 类暴露请求与交换的各个阶段这是编写进出场动画的关键依据Class出现时机htmx-added新内容换入前添加settle 后移除htmx-indicator请求指示器元素默认隐藏htmx-request请求期间添加到触发元素或指示器元素htmx-settling内容交换后、settle 前添加htmx-swappingswap 前添加可用于离场动画一次典型交换的类名流转为请求发出时目标获得htmx-request→ 响应到达、交换即将发生前旧目标获得htmx-swapping离场动画窗口→ 新节点插入时带htmx-added入场动画窗口→ 交换完成进入 settle 阶段时带htmx-settling→ settle 结束默认或settle:time指定后所有临时类移除。前文的删除行示例正是利用了htmx-swapping的离场窗口。API 速查核心属性属性说明hx-boost增强链接和表单使用 AJAX 替代整页跳转hx-get发起GET请求hx-post发起POST请求hx-put发起PUT请求hx-patch发起PATCH请求hx-delete发起DELETE请求hx-trigger指定触发请求的事件hx-target指定响应内容换入的目标hx-swap指定内容交换方式hx-select从响应中选择要换入的内容hx-push-url将 URL 推入浏览器历史hx-replace-url替换当前浏览器 URLhx-swap-oob处理响应中的带外交换hx-boost值得单独说明给普通a链接或form加上它即可把整页跳转升级为 AJAX 请求 内容交换是渐进式改造存量页面成本最低的手段——不需要逐元素改写为 htmx 属性。附加属性属性说明hx-confirm请求前显示确认对话框hx-disabled-elt请求期间禁用触发元素或指定元素hx-disable禁用当前节点及子节点的 htmx 处理hx-disinherit禁用属性继承hx-encoding设置请求编码如multipart/form-datahx-ext启用扩展hx-headers添加请求头hx-history-elt指定历史快照元素hx-include包含额外输入值hx-indicator指定请求期间显示状态的元素hx-params过滤请求参数hx-preserve交换时保留元素hx-prompt请求前显示提示框hx-request配置请求行为hx-select-oob从响应中选择带外交换内容hx-sync控制多个请求之间的同步hx-validate请求前触发表单验证hx-vals添加 JSON 格式参数注意 htmx 的属性继承机制部分属性如hx-target、hx-swap可从父元素继承给子元素hx-disinherit用于切断这种继承——这也是删除行示例能把hx-targetclosest tr写在tbody上的原因。常用事件事件说明htmx:beforeRequest发出请求前触发htmx:configRequest请求前配置参数和请求头htmx:beforeSendXHR 发送前触发htmx:afterRequest请求完成后触发htmx:beforeSwap交换前触发可改变目标或 swap 方式htmx:afterSwap内容换入后触发htmx:afterSettleDOM settle 后触发htmx:load新内容加入 DOM 后触发htmx:confirm请求确认阶段触发htmx:responseErrorHTTP 错误响应时触发htmx:sendError网络发送失败时触发htmx:timeout请求超时时触发htmx:xhr:progressXHR 进度事件常用于上传事件覆盖了完整生命周期configRequest改参数/请求头→beforeSend发送前→afterRequest收到响应→beforeSwap可重定向目标与换法→afterSwap→afterSettle→load对新 DOM 挂初始化逻辑如初始化图表。错误处理则分散在htmx:responseErrorHTTP 错误码、htmx:sendError网络层失败、htmx:timeout超时三个入口。JavaScript API方法说明htmx.ajax()发起 htmx 风格 AJAX 请求htmx.trigger()触发元素事件htmx.on()添加事件监听器htmx.off()移除事件监听器htmx.onLoad()监听 htmx 加载的新内容htmx.process()处理动态加入的 DOMhtmx.find()查找单个元素htmx.findAll()查找多个元素htmx.closest()查找最近祖先元素htmx.addClass()添加类htmx.removeClass()移除类htmx.toggleClass()切换类htmx.takeClass()从同级元素中取得唯一类htmx.logAll()打开所有 htmx 事件日志htmx.logger自定义日志函数两个高频方法htmx.process()用于对绕过 htmx 扫描直接插入 DOM的元素例如用innerHTML手工塞入的模板手动补挂 htmx 行为htmx.ajax()则允许在 JS 中发起与属性体系行为一致的请求自动带HX-Request头、走同样的交换流程适合表单验证失败后重新提交这类场景。请求头客户端 → 服务端标头说明HX-Boosted请求来自hx-boostHX-Current-URL当前浏览器 URLHX-History-Restore-Request历史恢复请求HX-Prompt用户对hx-prompt的响应HX-Requesthtmx 请求总是为trueHX-Target目标元素 idHX-Trigger-Name触发元素 nameHX-Trigger触发元素 id服务端只需判断HX-Request: true即可区分完整页面请求与htmx 片段请求从而决定返回整页还是局部片段——这是后端适配 htmx 的最小契约。HX-Target与HX-Trigger则让服务端知道内容该换到哪、由哪个元素发起便于在同一端点返回不同片段。响应头服务端 → 客户端标头说明HX-Location客户端跳转但不整页刷新HX-Push-Url推入新的浏览器历史 URLHX-Redirect浏览器重定向到新地址HX-Refresh值为true时刷新整页HX-Replace-Url替换当前浏览器 URLHX-Reswap覆盖客户端hx-swapHX-Retarget覆盖客户端目标元素HX-Reselect覆盖客户端hx-selectHX-Trigger响应收到后触发事件HX-Trigger-After-Swapswap 后触发事件HX-Trigger-After-Settlesettle 后触发事件响应头让服务端获得运行时控制权无需客户端预先声明即可动态改换目标HX-Retarget、覆盖交换方式HX-Reswap、在响应中顺带触发前端事件HX-Trigger系列可传 JSON 作为事件 detail或指令浏览器做软跳转/刷新。典型用法如保存成功后顺带刷新侧边栏计数服务端在响应头中返回HX-Trigger: {refreshCount: true}前端监听该事件即可。扩展与调试扩展扩展能力hx-extresponse-targets按 HTTP 状态码选择目标hx-extsseServer-Sent Events 支持hx-extwsWebSocket 支持hx-extpreload预加载内容hx-exthead-support合并响应中的 head 信息hx-exthtmx-1-compat恢复部分 htmx 1.x 行为扩展必须在核心 htmx 之后加载社区扩展可能有不同安装方式使用前应查看对应扩展仓库。实时通信ws/sse与一次响应按状态码分发到不同区域response-targets都是核心属性难以表达、由扩展补齐的能力。调试手段手段用途htmx.logAll()在控制台记录所有 htmx 事件htmx.logger fn自定义日志输出HX-Request: true服务端识别 htmx 请求Network 面板查看HX-*请求头和响应头htmx:beforeSwap调试目标、响应和交换行为htmx:responseError处理非 2xx/3xx 响应排障路径建议先用htmx.logAll()确认请求是否发出、事件是否到达 → 在 Network 面板核对HX-*头验证服务端契约 → 用htmx:beforeSwap打断点检查目标元素与实际响应 → 对错误响应挂htmx:responseError兜底。全局配置meta namehtmx-config content{defaultSwapStyle:outerHTML}也可以用meta标签声明 JSON 配置在加载 htmx 脚本之前生效或直接修改htmx.config对象。常见配置包括默认 swap 样式、请求超时、是否允许属性继承、是否携带跨站凭据等。本文来源Quick Reference 速查站与文档渲染机制本文内容整理自 Quick Reference 速查站仓库 README.md 描述的为中文开发者整理的技术栈速查清单中的 htmx 备忘清单。从仓库结构看该站采用纯 Markdown 文档 自动编译的管线docs/目录下的每个.md文件对应一个速查页package.json 中的refs-cli负责把 Markdown 编译为静态站点npm run build产出dist/npm run start开启 watch 模式本地预览netlify.toml 与 Dockerfile 则分别定义了静态部署与容器化发布方式。htmx 备忘清单 中大量出现的!--rehype:wrap-classcol-span-2--、!--rehype:classNameleft-align code-nowrap--注释并非 htmx 的内容而是站点排版指令按 CONTRIBUTING.md 的说明站点通过 rehype 插件rehype-attr解析这类注释为 HTML 元素附加布局类实现卡片网格、列宽、左对齐等速查站特有的视觉排版。阅读该文档源码时可直接忽略这些注释行它们不影响 htmx 技术内容本身。需要指出的是本仓库本身是一个文档站而非 htmx 的代码仓库文中所有 htmx 行为描述均以 docs/htmx.md 速查清单整理的内容为准对应 htmx 2.x 主线若你的项目锁定了 1.x部分属性行为如带外交换语法存在差异可用hx-exthtmx-1-compat扩展过渡。小结htmx 的价值在于把发请求—等响应—换片段这套交互逻辑前移到 HTML 属性层hx-trigger决定何时、hx-target与hx-swap决定换到哪和怎么换、hx-select/hx-swap-oob处理复合响应参数由hx-params/hx-vals/hx-include精确控制状态用htmx-*CSS 类驱动动画扩展补齐 WebSocket/SSE 等实时能力。配合HX-Request请求头契约与服务端响应头控制一个不写前端框架的 HTML 项目同样可以拥有完整的局部更新、轮询、上传与历史管理体验。完整清单可回看仓库中的 htmx 备忘清单属性级细节可查阅 htmx 官方文档站的 Attributes、Events 与 Headers 参考页。【免费下载链接】reference面向开发者的技术速查清单Cheat Sheets集合整理常见技术、工具与开发流程帮助快速查阅关键信息提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考