hx-trigger

hx-trigger 属性允许你指定触发 AJAX 请求的内容。触发器值可以是以下值之一：

¥The hx-trigger attribute allows you to specify what triggers an AJAX request. A trigger value can be one of the following:

• 事件名称（例如 “click” 或 “my-custom-event”）后跟事件过滤器和一组事件修饰符

  ¥An event name (e.g. “click” or “my-custom-event”) followed by an event filter and a set of event modifiers

• 形式为 every <timing declaration> 的轮询定义

  ¥A polling definition of the form every <timing declaration>

• 此类事件的逗号分隔列表

  ¥A comma-separated list of such events

标准事件

¥Standard Events

标准事件引用 web API 事件（例如单击、键盘按下、鼠标松开、加载）。

¥Standard events refer to web API events (e.g. click, keydown, mouseup, load).

可以将标准事件（例如 click）指定为触发器，如下所示：

¥A standard event, such as click can be specified as the trigger like so:

<div hx-get="/clicked" hx-trigger="click">Click Me</div>

标准事件过滤器

¥Standard Event Filters

可以通过在事件名称后用方括号括起布尔 javascript 表达式来过滤事件。如果此表达式的计算结果为 true，则将触发该事件，否则将被忽略。标准事件过滤器 需要 eval。

¥Events can be filtered by enclosing a boolean javascript expression in square brackets after the event name. If this expression evaluates to true the event will be triggered, otherwise it will be ignored. Standard event filters require eval.

<div hx-get="/clicked" hx-trigger="click[ctrlKey]">Control Click Me</div>

如果在 event.ctrlKey 属性设置为 true 的情况下触发单击事件，将触发此事件。

¥This event will trigger if a click event is triggered with the event.ctrlKey property set to true.

条件也可以引用全局函数或状态

¥Conditions can also refer to global functions or state

<div hx-get="/clicked" hx-trigger="click[checkGlobalState()]">Control Click Me</div>

也可以使用标准 javascript 语法进行组合

¥And can also be combined using the standard javascript syntax

<div hx-get="/clicked" hx-trigger="click[ctrlKey&&shiftKey]">Control-Shift Click Me</div>

请注意，表达式中使用的所有符号将首先针对触发事件进行解析，然后针对全局命名空间进行解析，因此 myEvent[foo] 将首先在事件上查找名为 foo 的属性，然后查找名为 foo 的全局符号

¥Note that all symbols used in the expression will be resolved first against the triggering event, and then next against the global namespace, so myEvent[foo] will first look for a property named foo on the event, then look for a global symbol with the name foo

标准事件修饰符

¥Standard Event Modifiers

标准事件也可以具有改变其行为方式的修饰符。修饰符是：

¥Standard events can also have modifiers that change how they behave. The modifiers are:

• once - 事件只会触发一次（例如第一次点击）

  ¥once - the event will only trigger once (e.g. the first click)

• changed - 仅当元素的值发生变化时，事件才会发生变化。请注意 change 是事件的名称，changed 是修饰符的名称。

  ¥changed - the event will only change if the value of the element has changed. Please pay attention change is the name of the event and changed is the name of the modifier.

• delay:<timing declaration> - 事件触发请求之前将发生延迟。如果再次看到事件，它将重置延迟。

  ¥delay:<timing declaration> - a delay will occur before an event triggers a request. If the event is seen again it will reset the delay.

• throttle:<timing declaration> - 事件触发请求后将发生节流。如果在延迟完成之前再次看到事件，它将被忽略，元素将在延迟结束时触发。

  ¥throttle:<timing declaration> - a throttle will occur after an event triggers a request. If the event is seen again before the delay completes, it is ignored, the element will trigger at the end of the delay.

• from:<Extended CSS selector> - 允许触发请求的事件来自文档中的另一个元素（例如，监听正文上的键事件，以支持热键）

  ¥from:<Extended CSS selector> - allows the event that triggers a request to come from another element in the document (e.g. listening to a key event on the body, to support hot keys)

  • 标准 CSS 选择器解析为与该选择器匹配的所有元素。因此，from:input 将监听页面上的每个输入。

    ¥A standard CSS selector resolves to all elements matching that selector. Thus, from:input would listen on every input on the page.

  • CSS 选择器仅评估一次，页面更改时不会重新评估。如果你需要检测动态添加的元素，请使用 标准事件过滤器，例如 hx-trigger="click[event.target.matches('button')] from:body"，它将 catch 点击页面上每个按钮的事件。

    ¥The CSS selector is only evaluated once and is not re-evaluated when the page changes. If you need to detect dynamically added elements use a standard event filter, for example hx-trigger="click[event.target.matches('button')] from:body" which would catch click events from every button on the page.

  • 此处扩展的 CSS 选择器允许以下非标准 CSS 值：

    ¥The extended CSS selector here allows for the following non-standard CSS values:

    • document - 监听文档上的事件

      ¥document - listen for events on the document

    • window - 监听窗口上的事件

      ¥window - listen for events on the window

    • closest <CSS selector> - 查找与给定的 css 选择器匹配的 closest 祖级元素或其本身

      ¥closest <CSS selector> - finds the closest ancestor element or itself, matching the given css selector

    • find <CSS selector> - 查找与给定的 css 选择器匹配的最近子元素

      ¥find <CSS selector> - finds the closest child matching the given css selector

    • next 解析为 element.nextElementSibling

      ¥next resolves to element.nextElementSibling

    • next <CSS selector> 向前扫描 DOM 以查找与给定 CSS 选择器匹配的第一个元素。(例如 next .error 将定位到具有 error 类的最近的后续兄弟元素)

      ¥next <CSS selector> scans the DOM forward for the first element that matches the given CSS selector. (e.g. next .error will target the closest following sibling element with error class)

    • previous 解析为 element.previousElementSibling

      ¥previous resolves to element.previousElementSibling

    • previous <CSS selector> 向后扫描 DOM 以查找与给定 CSS 选择器匹配的第一个元素。(例如 previous .error 将定位到具有 error 类的最近的前一个兄弟元素)

      ¥previous <CSS selector> scans the DOM backwards for the first element that matches the given CSS selector. (e.g. previous .error will target the closest previous sibling with error class)

• target:<CSS selector> - 允许你通过 CSS 选择器对事件目标进行过滤。当你想要监听初始化时可能不在 DOM 中的元素的触发器时，此功能很有用，例如，通过监听主体，但使用子元素的目标过滤器

  ¥target:<CSS selector> - allows you to filter via a CSS selector on the target of the event. This can be useful when you want to listen for triggers from elements that might not be in the DOM at the point of initialization, by, for example, listening on the body, but with a target filter for a child element

• consume - 如果包含此选项，则事件将不会触发对父级（或在父级上监听的元素）的任何其他 htmx 请求

  ¥consume - if this option is included the event will not trigger any other htmx requests on parents (or on elements listening on parents)

• queue:<queue option> - 确定如果在请求另一个事件时发生事件，事件如何排队。选项包括：

  ¥queue:<queue option> - determines how events are queued if an event occurs while a request for another event is in flight. Options are:

  • first - 将第一个事件排队

    ¥first - queue the first event

  • last - 将最后一个事件排队（默认）

    ¥last - queue the last event (default)

  • all - 将所有事件排队（为每个事件发出一个请求）

    ¥all - queue all events (issue a request for each event)

  • none - 不排队新事件

    ¥none - do not queue new events

以下是搜索框的示例，该搜索框在 keyup 上进行搜索，但前提是搜索值已更改且用户 1 秒内未输入任何新内容：

¥Here is an example of a search box that searches on keyup, but only if the search value has changed and the user hasn’t typed anything new for 1 second:

<input name="q"
       hx-get="/search" hx-trigger="keyup changed delay:1s"
       hx-target="#search-results"/>

来自 /search URL 的响应将附加到 ID 为 search-results 的 div。

¥The response from the /search url will be appended to the div with the id search-results.

非标准事件

¥Non-standard Events

htmx 支持一些额外的非标准事件：

¥There are some additional non-standard events that htmx supports:

• load - 加载时触发（用于延迟加载）

  ¥load - triggered on load (useful for lazy-loading something)

• revealed - 当元素滚动到视口中时触发（对于延迟加载也很有用）。如果你在 css 中使用 overflow（如 overflow-y: scroll），则应使用 intersect once 而不是 revealed。

  ¥revealed - triggered when an element is scrolled into the viewport (also useful for lazy-loading). If you are using overflow in css like overflow-y: scroll you should use intersect once instead of revealed.

• intersect - 当元素首次与视口相交时触发一次。这支持两个附加选项：

  ¥intersect - fires once when an element first intersects the viewport. This supports two additional options:

  • root:<selector> - 用于交集的根元素的 CSS 选择器

    ¥root:<selector> - a CSS selector of the root element for intersection

  • threshold:<float> - 0.0 和 1.0 之间的浮点数，表示触发事件的交集量

    ¥threshold:<float> - a floating point number between 0.0 and 1.0, indicating what amount of intersection to fire the event on

通过 HX-Trigger 标头触发

¥Triggering via the HX-Trigger header

如果你尝试从 HX-Trigger 响应标头触发事件，则可能需要使用 from:body 修饰符。例如如果你发送带有响应的类似 HX-Trigger: my-custom-event 的标头，则元素可能需要如下所示：

¥If you’re trying to fire an event from HX-Trigger response header, you will likely want to use the from:body modifier. E.g. if you send a header like this HX-Trigger: my-custom-event with a response, an element would likely need to look like this:

  <div hx-get="/example" hx-trigger="my-custom-event from:body">
    Triggered by HX-Trigger header...
  </div>

以便触发。

¥in order to fire.

这是因为标题可能会在与你希望触发的元素不同的 DOM 层次结构中触发事件。出于类似的原因，你经常会监听来自正文的热键。

¥This is because the header will likely trigger the event in a different DOM hierarchy than the element that you wish to be triggered. For a similar reason, you will often listen for hot keys from the body.

轮询

¥Polling

通过使用语法 every <timing declaration>，你可以定期轮询元素：

¥By using the syntax every <timing declaration> you can have an element poll periodically:

<div hx-get="/latest_updates" hx-trigger="every 1s">
  Nothing Yet!
</div>

此示例将每秒向 /latest_updates URL 发出 GET 并将结果交换到此 div 的 innerHTML 中。

¥This example will issue a GET to the /latest_updates URL every second and swap the results into the innerHTML of this div.

如果你希望向轮询添加过滤器，则应将其添加到轮询声明之后：

¥If you want to add a filter to polling, it should be added after the poll declaration:

<div hx-get="/latest_updates" hx-trigger="every 1s [someConditional]">
  Nothing Yet!
</div>

多个触发器

¥Multiple Triggers

可以提供多个触发器，用逗号分隔。每个触发器都有自己的选项。

¥Multiple triggers can be provided, separated by commas. Each trigger gets its own options.

  <div hx-get="/news" hx-trigger="load, click delay:1s"></div>

此示例将在页面加载时立即加载 /news，然后在每次单击后延迟一秒再次加载。

¥This example will load /news immediately on page load, and then again with a delay of one second after each click.

通过 JavaScript

¥Via JavaScript

AJAX 请求也可以通过 JavaScript htmx.trigger() 触发。

¥The AJAX request can be triggered via JavaScript htmx.trigger(), too.

注释

¥Notes

• hx-trigger 不是继承的

  ¥hx-trigger is not inherited

• hx-trigger 可在没有 AJAX 请求的情况下使用，在这种情况下它只会触发 htmx:trigger 事件

  ¥hx-trigger can be used without an AJAX request, in which case it will only fire the htmx:trigger event

• 为了将包含空格的 CSS 选择器（例如 form input）传递给 from 或 target 修饰符，请将选择器括在括号或大括号中（例如 from:(form input) 或 from:closest (form input)）

  ¥In order to pass a CSS selector that contains whitespace (e.g. form input) to the from- or target-modifier, surround the selector in parentheses or curly brackets (e.g. from:(form input) or from:closest (form input))

• hx-trigger 中的重置事件（例如 hx-trigger=“更改，重置”）可能无法按预期工作，因为 HTMX 会在浏览器重置表单值之前构建其值并发送请求。作为一种解决方法，添加延迟以让浏览器在发出请求之前重置表单（例如 hx-trigger=“更改，重置延迟：0.01 秒”）。

  ¥A reset event in hx-trigger (e.g. hx-trigger=“change, reset”) might not work as intended, since HTMX builds its values and sends a request before the browser resets the form values. As a workaround, add a delay to let the browser reset the form before making the request (e.g. hx-trigger=“change, reset delay:0.01s”).