hx-sync

hx-sync 属性允许你在多个元素之间同步 AJAX 请求。

¥The hx-sync attribute allows you to synchronize AJAX requests between multiple elements.

hx-sync 属性由一个 CSS 选择器组成，用于指示要同步的元素，后面可选跟一个冒号，然后是可选的同步策略。可用的策略是：

¥The hx-sync attribute consists of a CSS selector to indicate the element to synchronize on, followed optionally by a colon and then by an optional syncing strategy. The available strategies are:

• drop - 如果现有请求正在运行，则丢弃（忽略）此请求（默认）

  ¥drop - drop (ignore) this request if an existing request is in flight (the default)

• abort - 如果现有请求正在运行，则丢弃（忽略）此请求，如果不是这种情况，则在仍在运行时发生另一个请求时中止此请求

  ¥abort - drop (ignore) this request if an existing request is in flight, and, if that is not the case, abort this request if another request occurs while it is still in flight

• replace - 中止当前请求（如果有），并将其替换为此请求

  ¥replace - abort the current request, if any, and replace it with this request

• queue - 将此请求放在与给定元素关联的请求队列中

  ¥queue - place this request in the request queue associated with the given element

queue 修饰符可以接受一个附加参数，该参数准确指示如何排队：

¥The queue modifier can take an additional argument indicating exactly how to queue:

• queue first - 将请求正在发送时显示的第一个请求排队

  ¥queue first - queue the first request to show up while a request is in flight

• queue last - 将请求正在发送时显示的最后一个请求排队

  ¥queue last - queue the last request to show up while a request is in flight

• queue all - 将请求正在发送时显示的所有请求排队

  ¥queue all - queue all requests that show up while a request is in flight

注释

¥Notes

• hx-sync 是继承的，可以放在父元素上

  ¥hx-sync is inherited and can be placed on a parent element

此示例解决了表单的提交请求和单个输入的验证请求之间的竞争条件。通常情况下，不使用 hx-sync，填写输入并立即提交表单会触发对 /validate 和 /store 的两个并行请求。在输入上使用 hx-sync="closest form:abort" 将监视表单上的请求，如果存在表单请求或在输入请求进行时启动，则中止输入的请求。

¥This example resolves a race condition between a form’s submit request and an individual input’s validation request. Normally, without using hx-sync, filling out the input and immediately submitting the form triggers two parallel requests to /validate and /store. Using hx-sync="closest form:abort" on the input will watch for requests on the form and abort the input’s request if a form request is present or starts while the input request is in flight.

<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>

如果你宁愿优先处理验证请求而不是提交请求，可以使用 drop 策略。此示例将使验证请求优先于提交请求，以便如果验证请求正在进行中，则无法提交表单。

¥If you’d rather prioritize the validation request over the submit request, you can use the drop strategy. This example will prioritize the validation request over the submit request so that if a validation request is in flight, the form cannot be submitted.

<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 replace 策略将提交请求优先于所有输入验证请求。这将取消任何正在进行的验证请求并仅发出 hx-post="/store" 请求。如果你宁愿中止提交请求并优先处理任何现有验证请求，你可以在表单标记上使用 hx-sync="this:abort" 策略。

¥When dealing with forms that contain many inputs, you can prioritize the submit request over all input validation requests using the hx-sync replace strategy on the form tag. This will cancel any in-flight validation requests and issue only the hx-post="/store" request. If you’d rather abort the submit request and prioritize any existing validation requests you can use the hx-sync="this:abort" strategy on the form tag.

<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-trigger 属性的 delay 修饰符可用于消除用户输入的抖动，并避免在用户键入时发出多个请求。但是，一旦请求完成后，如果用户再次开始输入，即使前一个请求尚未完成处理，也会开始新的请求。此示例将取消任何正在进行的请求并仅使用最后一个请求。如果搜索输入包含在目标中，那么像这样使用 hx-sync 也有助于减少用户仍在输入时输入被替换的机会。

¥When implementing active search functionality the hx-trigger attribute’s delay modifier can be used to debounce the user’s input and avoid making multiple requests while the user types. However, once a request is made, if the user begins typing again a new request will begin even if the previous one has not finished processing. This example will cancel any in-flight requests and use only the last request. In cases where the search input is contained within the target, then using hx-sync like this also helps reduce the chances that the input will be replaced while the user is still typing.

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