• 前端

hx-sync是 htmx 提供的高阶请求协调属性，它允许开发者在多个元素之间同步 AJAX 请求，通过drop、abort、replace、queue四种策略解决表单提交与字段校验、活动搜索等场景下的请求竞态问题。读完本文，你将掌握 hx-sync 的完整语法、四种同步策略及三种队列模式的区别，并理解其底层请求锁与队列实现原理，能够直接在项目中落地消除并发请求冲突的实战方案。

hx-sync 是什么：为 HTML 元素建立请求同步关系

htmx 默认允许页面中任意多个元素各自独立地发起 AJAX 请求。这在大多数场景下没有问题，但当多个请求之间存在因果关系或竞争关系时（例如表单提交请求与字段校验请求同时进行、用户连续键入触发的搜索请求互相覆盖），就会出现响应乱序、数据过期等竞态条件。

hx-sync属性正是为此设计：它允许你将一个元素的请求与另一个元素的请求状态关联起来，由 htmx 统一仲裁谁可以发、谁应该等、谁应该被丢弃。其官方定义位于 hx-sync 属性文档，在 属性参考表 中，它的职责被概括为"控制不同元素发起的请求之间如何进行同步"。

hx-sync 语法与完整取值

hx-sync的值由三部分构成：

hx-sync="<selector>:<strategy> [queue modifier]"

• selector：一个 CSS 选择器，用于指明要与之同步的目标元素。特殊值this表示"当前元素自身"（即承载该 hx-sync 属性的元素）。
• strategy：冒号后的同步策略，可选值如下表；省略时默认是drop。
• queue modifier：仅当策略为queue时使用，进一步指定入队方式。

queue策略可附加队列模式：

hx-sync是可继承属性，可以放在父元素上，让整个子树共享同一套同步规则（详见下文"继承行为"一节）。

四种同步策略详解

drop：静默丢弃冲突请求（默认）

当同步目标上已有请求在飞行时，新请求被直接忽略，不会发出网络请求，也不产生任何提示。这是最保守的策略，适合"校验请求优先、冗余请求直接放弃"的场景。

abort：双向防冲突

abort策略较为特殊，它有两种表现：

• 若目标元素已有请求在飞行，本次请求被丢弃；
• 若目标元素没有请求在飞行，则本次请求会被标记为abortable（可被中止），此后一旦有其他请求到达，会通过触发htmx:abort事件把这次请求中止。

从源码看，这一标记被保存在元素内部数据eltData.abortable中（见 src/htmx.js），后续任意请求发起时都会检查该标记并决定是否中止它（见 src/htmx.js）。

replace：新请求取代旧请求

replace会先对同步目标触发htmx:abort事件取消其正在进行的请求，然后立即发出本次请求。它适用于"总是以最新状态为准"的场景，例如活动搜索框中用户持续键入时，始终只保留最后一次搜索请求。

queue：按队列顺序执行

queue策略不丢弃任何请求，而是把请求挂到目标元素的队列中，等当前请求结束再依次发出。队列配合first/last/all三种模式，可以精细控制排队范围：

• queue first：飞行期间只保留第一个新请求；
• queue last（默认）：飞行期间清空旧队列、只保留最后一个新请求；
• queue all：飞行期间到达的请求全部入队、按序执行。

继承行为：hx-sync 是继承属性

hx-sync与hx-target、hx-trigger等属性一样具有继承性，可以写在父元素上统一管理子树内所有请求的同步关系。源码中通过getClosestAttributeValue(elt, 'hx-sync')获取属性值（见 src/htmx.js），该函数会沿 DOM 向上遍历查找最近的、未被屏蔽的属性（见 src/htmx.js）。

继承还受hx-disinherit/hx-inherit的控制：若某祖先声明hx-disinherit="hx-sync"，则其子树将屏蔽从更上层继承来的同步规则。当目标选择器写为this时，源码使用findThisElement(elt, 'hx-sync')定位到最近的、实际声明了 hx-sync 属性的祖先元素（见 src/htmx.js），这也正是"表单上写hx-sync="this:replace"会作用于表单自身"的原因。

实战场景一：消除表单提交与字段校验的竞态条件

这是 hx-sync 最典型的应用。一个表单中，输入框在change事件时向/validate发起校验请求，同时用户可能立即点击提交按钮向/store发起提交请求。不使用 hx-sync 时，这两个请求会并行发出，校验结果可能与提交数据不同步。

方案 A：让校验请求让位于提交请求（abort）

在输入框上使用hx-sync="closest form:abort"：表单的提交请求一旦出现（或已在飞行中），输入框的校验请求要么被丢弃、要么被标记为可中止，从而保证提交优先：

<form hx-post="/store"> <input id="title" name="title" type="text" hx-post="/validate" hx-trigger="change" hx-sync="closest form:abort"> <button type="submit">Submit</button> </form>

方案 B：让校验请求优先于提交请求（drop）

如果你希望"校验请求优先、校验期间禁止提交"，改用drop策略：只要校验请求在飞行，提交请求就会被静默丢弃，表单无法提交：

<form hx-post="/store"> <input id="title" name="title" type="text" hx-post="/validate" hx-trigger="change" hx-sync="closest form:drop" > <button type="submit">Submit</button> </form>

实战场景二：多输入表单的整体优先级控制

当一个表单包含大量带校验请求的输入框时，与其在每个输入框上逐个配置，不如把同步规则统一放到表单上：

• 使用hx-sync="this:replace"：提交请求优先。任何在飞行中的校验请求都会被中止，只发出hx-post="/store"提交请求：

<form hx-post="/store" hx-sync="this:replace"> <input id="title" name="title" type="text" hx-post="/validate" hx-trigger="change" /> <button type="submit">Submit</button> </form>

• 使用hx-sync="this:abort"：校验请求优先。提交请求会被中止，优先完成已有的校验请求。

两种写法分别对应"提交为主"与"校验为主"两种产品语义，取舍取决于业务上哪一方更关键。

实战场景三：活动搜索请求去重（this:replace + delay）

实现搜索即输入（search-as-you-type）时，通常先用hx-trigger的delay修饰符做防抖，避免击键过程中发出大量请求。但防抖只能推迟请求的发起时机，一旦请求发出，用户继续键入又会触发新请求，即使上一个请求尚未完成。此时用hx-sync="this:replace"让新请求中止并取代旧请求，保证始终只有最后一次搜索生效：

<input type="search" hx-get="/search" hx-trigger="keyup changed delay:500ms, search" hx-target="#search-results" hx-sync="this:replace">

这个方案还有一个附带收益：当搜索输入框本身位于#search-results目标区域内部时，replace会在新请求发出前中止旧请求，降低"用户在键入过程中输入框被旧响应替换"的概率。

源码级原理：请求同步的完整执行流程

hx-sync 的同步逻辑在issueAjaxRequest内部执行，核心代码位于 src/htmx.js，流程如下：

1. 解析属性：通过getClosestAttributeValue(elt, 'hx-sync')取到继承后的属性值，按冒号拆分为选择器与策略（见 src/htmx.js）；选择器为this时用findThisElement定位声明该属性的元素，否则用querySelectorExt解析 CSS 选择器；策略缺省时回退为drop。
2. 策略裁决：
   • drop：目标元素已有飞行请求且不可中止时，直接resolve并返回，请求被放弃（见 src/htmx.js）；
   • abort：有飞行请求则放弃本次请求，否则把本次请求标记为abortable（见 src/htmx.js）；
   • replace：对目标元素触发htmx:abort事件，中止其当前请求（见 src/htmx.js）；
   • queue：解析出队列模式（缺省last），进入第 3 步（见 src/htmx.js）。
3. 入队或放行：若目标元素仍有飞行请求（见 src/htmx.js），abortable的请求被中止；否则按队列模式入队——first只在队列为空时入队一次，all总是入队，last先清空旧队列再入队。
4. 请求结束释放锁：请求真正发出后，htmx 在endRequestLock中把eltData.xhr置空并弹出队列中的下一个请求继续执行（见 src/htmx.js），从而形成"同一同步目标上同一时刻至多一个在飞行请求"的串行化约束。

关于中止动作本身：htmx 在文档初始化时于<body>上注册了htmx:abort事件监听器，收到事件后调用对应元素内部数据中保存的xhr.abort()真正取消网络请求（见 src/htmx.js）。这意味着任何元素都可以通过htmx.trigger(elt, 'htmx:abort')编程式中止目标请求，这与 hx-sync 的replace/abort策略底层是同一套机制。

测试验证：策略行为均有自动化用例覆盖

仓库的 hx-sync 测试文件 对上述所有策略都提供了可复现的验证用例，可作为你理解各策略行为差异的权威参考：

• drop 与默认值：两个按钮同时请求，第一个响应、第二个保持初始内容（it('can use drop strategy')、it('defaults to the drop strategy')）；
• replace：后点击的按钮的请求取代先点击的请求，先点击者不更新（it('can use replace strategy')）；
• queue all / last / first：三个按钮连续触发，观察三个响应周期内各按钮的更新顺序——all三者依次更新，last只保留最后一个排队者，first只保留第一个排队者（对应三个独立测试用例）；
• abort 两种形态：分别在"已有请求在飞行"与"无请求在飞行"两种初始状态下验证丢弃与可中止标记行为（it('can use abort strategy to end existing abortable request')与it('can use abort strategy to drop abortable request when one is in flight')）；
• 编程式中止：通过htmx.trigger(b1, 'htmx:abort')手动中止按钮请求（it('can abort a request programmatically')）。

小结

hx-sync把原本各自为政的 AJAX 请求纳入统一仲裁，是 htmx 处理请求并发问题的核心工具。选用策略时可遵循简单的经验法则：宁可丢失也不冲突用drop，让新请求接管用replace，既要防冲突又要可恢复用abort，所有请求都不可丢则用queue。配合hx-trigger的delay防抖与继承属性机制，它足以覆盖表单校验、活动搜索、批量操作等绝大多数多请求协调场景。该属性自 htmx 1.7.0 引入（见 版本发布说明），更完整的组合示例还可参考 docs.md 中的请求同步章节。

• 前端