Триггеры

По умолчанию AJAX-запросы инициируются «естественным» событием элемента:

• input, textarea и select инициируются при событии изменения (change)
• form инициируется при событии отправки (submit)
• все остальные элементы инициируются при событии клика (click)

Если вы хотите изменить это поведение, используйте атрибут hx-trigger, чтобы указать, какое событие вызовет запрос.

Вот div, который отправляет POST-запрос на /mouse_entered, когда указатель мыши попадает в область блока:

<div hx-post="/mouse_entered" hx-trigger="mouseenter">
  [Тут мышка, мышка!]
</div>

Модификаторы триггера

Триггер также может иметь несколько дополнительных модификаторов, которые изменяют его поведение. Например, если вы хотите, чтобы запрос выполнялся только один раз, вы можете использовать модификатор once для триггера:

<div hx-post="/mouse_entered" hx-trigger="mouseenter once">
  [Тут мышка, мышка!]
</div>

Другие модификаторы, которые вы можете использовать для триггеров:

• changed — отправлять запрос только в том случае, если значение элемента изменилось
• delay:<интервал времени> — подождать заданное количество времени (например, 1s) перед отправкой запроса. Если событие сработает снова, обратный отсчёт сбрасывается.
• throttle:<интервал времени> — подождать заданное количество времени (например, 1s) перед отправкой запроса. В отличие от delay, если новое событие произойдет до истечения временного лимита, событие будет отброшено, и запрос будет выполнен в конце временного периода.
• from:<CSS селектор> — слушать событие на другом элементе. Это можно использовать для таких вещей, как горячие клавиши. Обратите внимание, что этот CSS селектор не анализируется заново, если страница изменяется.

Вы можете использовать эти атрибуты для реализации многих распространённых UX-паттернов, таких как активный поиск:

<input type="text" name="q"
  hx-get="/trigger_delay"
  hx-trigger="keyup changed delay:500ms"
  hx-target="#search-results"
  placeholder="Поиск..."
>
<div id="search-results"></div>

Этот элемент ввода будет отправлять запрос через 500 миллисекунд после события отпускания клавиши, если ввод был изменён, и вставляет результаты в div с id search-results.

Можно указать несколько триггеров в атрибуте hx-trigger, разделяя их запятыми.

Фильтры триггеров

Вы также можете применять фильтры триггеров, используя квадратные скобки после имени события, заключая в них выражение JavaScript, которое будет анализироваться. Если выражение возвращает true, событие будет срабатывать, в противном случае — нет.

Вот пример, который срабатывает только при нажатии Control + Click на элементе:

<div hx-get="/clicked" hx-trigger="click[ctrlKey]">
  Нажми Control + Click
</div>

Свойства, такие как ctrlKey, будут сначала разрешены относительно триггерного события, а затем относительно глобальной области видимости. Символ this будет привязан к текущему элементу.

Специальные события

htmx предоставляет несколько специальных событий для использования в hx-trigger:

• load — срабатывает один раз, когда элемент загружается впервые
• revealed — срабатывает один раз, когда элемент впервые появляется в области видимости
• intersect — срабатывает один раз, когда элемент впервые пересекает область видимости. Это поддерживает две дополнительные опции:
  • root:<selector> — CSS-селектор корневого элемента для пересечения
  • threshold:<float> — число с плавающей запятой от 0.0 до 1.0, указывающее, на каком уровне пересечения должно срабатывать событие

Вы также можете использовать пользовательские события для триггера запросов, если у вас есть более сложный случай использования.

Опрашивание

Если вы хотите, чтобы элемент опрашивал указанный URL, а не ждал события, вы можете использовать синтаксис every с атрибутом hx-trigger:

<div hx-get="/news" hx-trigger="every 2s"></div>

Это говорит htmx:

Каждые 2 секунды отправляй GET-запрос на /news и загружай ответ в div.

Если вы хотите остановить опрос, можно ответить кодом HTTP 286, и элемент отменит опрос.

Опрашивание по триггеру

Ещё одна техника, которая может быть использована для достижения опроса в htmx, — это «опрашивание по триггеру», где элемент указывает триггер load вместе с задержкой и заменяет себя ответом:

<div hx-get="/messages"
  hx-trigger="load delay:1s"
  hx-swap="outerHTML">
</div>

Если конечная точка /messages продолжает возвращать div, настроенный таким образом, она будет продолжать «опрашивание» по URL каждую секунду.

Опрашивание по триггеру может быть полезна в ситуациях, когда опрос имеет конечную точку, после которой опрос прекращается, например, когда вы показываете пользователю индикатор прогресса.