Атрибут hx-trigger

Атрибут hx-trigger позволяет вам указать, что вызывает AJAX-запрос. Значением триггера может быть:

Имя события (например, click или my-custom-event), за которым следуют фильтр события и набор модификаторов события.
Определение опроса в форме every <значение времени>.
Список таких событий, разделённых запятыми.

Стандартные события

Стандартные события относятся к событиям Web API (например, click, keydown, mouseup, load).

Стандартное событие, такое как click, можно указать в качестве триггера следующим образом:

<div hx-get="/clicked" hx-trigger="click">Нажми на меня</div>

События можно фильтровать, заключив булево JavaScript-выражение в квадратные скобки после имени события. Если это выражение оценивается как true, событие будет вызвано, в противном случае оно будет проигнорировано. Фильтры стандартных событий требуют eval.

<div hx-get="/clicked" hx-trigger="click[ctrlKey]">Control + клик</div>

Это событие будет срабатывать, если событие click будет вызвано с установленным свойством event.ctrlKey в true.

Условия также могут ссылаться на глобальные функции или состояние:

<div hx-get="/clicked" hx-trigger="click[checkGlobalState()]">Control + клик</div>

И также могут быть объединены с использованием стандартного синтаксиса JavaScript:

<div hx-get="/clicked" hx-trigger="click[ctrlKey&&shiftKey]">Control-Shift + клик</div>

Обратите внимание, что все символы, используемые в выражении, сначала будут разрешены относительно вызывающего события, а затем — относительно глобального пространства имён, поэтому myEvent[foo] сначала будет искать свойство с именем foo в событии, а затем — глобальный символ с именем foo.

Модификаторы стандартных событий

Стандартные события также могут иметь модификаторы, которые изменяют их поведение:

once — событие будет срабатывать только один раз (например, при первом клике).
changed — событие будет срабатывать только если значение элемента изменилось. Обратите внимание, что change — это имя события, а changed — имя модификатора.
delay:<значение времени> — перед тем, как событие вызовет запрос, произойдет задержка. Если событие будет зафиксировано снова, задержка сбросится.
throttle:<значение времени> — произойдет ограничение после того, как событие вызовет запрос. Если событие будет зафиксировано снова до завершения задержки, оно будет проигнорировано, элемент сработает в конце задержки.
from:<расширенный CSS-селектор> — позволяет событию, которое вызывает запрос, происходить от другого элемента в документе (например, прослушивание события клавиши на элементе body для поддержки горячих клавиш).
- Стандартный CSS-селектор разрешается для всех элементов, соответствующих этому селектору. Таким образом, from:input будет слушать каждое поле ввода на странице.
- CSS-селектор оценивается только один раз и не анализируется заново, когда страница изменяется. Если вам нужно обнаружить динамически добавленные элементы, используйте фильтр стандартных событий, например hx-trigger="click[event.target.matches('button')] from:body", который будет перехватывать события клика от каждой кнопки на странице.
- Расширенный CSS-селектор здесь позволяет использовать следующие нестандартные значения CSS:
  - document — слушать события на документе.
  - window — слушать события на окне.
  - closest <CSS селектор> — находит ближайший родительский элемент или сам элемент, соответствующий заданному CSS-селектору.
  - find <CSS селектор> — находит ближайший дочерний элемент, соответствующий заданному CSS-селектору.
  - next — ссылается на элемент element.nextElementSibling.
  - next <CSS селектор> — сканирует DOM вперед для первого элемента, соответствующего заданному CSS-селектору. (Например, next .error будет нацеливаться на ближайший следующий элемент-сосед с классом error).
  - previous — ссылается на элемент element.previousElementSibling.
  - previous <CSS селектор> — сканирует DOM назад для первого элемента, соответствующего заданному CSS-селектору. (Например, previous .error будет нацеливаться на ближайший предыдущий элемент-сосед с классом error).
target:<CSS селектор> — позволяет вам фильтровать через CSS-селектор на целевом элементе события. Это может быть полезно, когда вы хотите слушать триггеры от элементов, которые могут не находиться в DOM в момент инициализации, например, прослушивая на элементе body, но с фильтром target для дочернего элемента.
consume — если эта опция включена, событие не вызовет никаких других запросов htmx на родителях (или на элементах, слушающих на родителях).
queue:<вариант очереди> — определяет, как события ставятся в очередь, если событие происходит, пока запрос на другое событие выполняется. Варианты:
- first — ставить первое событие в очередь.
- last — ставить последнее событие в очередь (по умолчанию).
- all — ставить все события в очередь (выдавать запрос для каждого события).
- none — не ставить новые события в очередь.

Вот пример поля поиска, которое выполняет поиск при отпускании клавиши, но только если значение поиска изменилось и пользователь не вводил ничего нового в течение 1 секунды:

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

Ответ с URL /search будет добавлен в div с id search-results.

Нестандартные события

Существуют некоторые дополнительные нестандартные события, которые поддерживает htmx:

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

Срабатывание через заголовок `HX-Trigger`

Если вы пытаетесь вызвать событие из заголовка ответа HX-Trigger, вам, вероятно, потребуется использовать модификатор from:body. Например, если вы отправите заголовок, подобный этому HX-Trigger: my-custom-event с ответом, элемент, вероятно, должен выглядеть следующим образом:

<div hx-get="/example" hx-trigger="my-custom-event from:body">
  Запускается с помощью заголовка HX-Trigger...
</div>

Это происходит потому, что заголовок, скорее всего, вызовет событие в другой иерархии DOM, отличной от той, к которой принадлежит элемент, который вы хотите активировать. По той же причине вы часто будете отслеживать горячие клавиши на элементе body.

Опрос

Применяя синтаксис every <значение времени>, вы можете настроить периодический опрос элемента:

<div hx-get="/latest_updates" hx-trigger="every 1s">
  Пока ничего!
</div>

Этот пример будет отправлять GET-запрос к URL /latest_updates каждую секунду и заменять результаты в innerHTML этого div.

Если вы хотите добавить фильтр к опросу, его следует указать после объявления опроса:

<div hx-get="/latest_updates" hx-trigger="every 1s [someConditional]">
  Пока ничего!
</div>

Несколько триггеров

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

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

Этот пример загрузит /news сразу после загрузки страницы, а затем снова с задержкой в одну секунду после каждого клика.

С помощью JavaScript

AJAX-запрос также можно вызвать с помощью JavaScript через htmx.trigger().

Примечания

hx-trigger не наследуется.
hx-trigger можно использовать без AJAX-запроса, в этом случае он только вызовет событие htmx:trigger.
Чтобы передать CSS-селектор, содержащий пробелы (например, form input), в модификатор from- или target-, оберните селектор в круглые или фигурные скобки (например, from:(form input) или from:closest (form input)).
Событие сброса в hx-trigger (например, hx-trigger="change, reset") может не работать так, как задумано, поскольку HTMX формирует свои значения и отправляет запрос до того, как браузер сбросит значения формы. В качестве обходного пути добавьте задержку, чтобы дать браузеру возможность сбросить форму перед выполнением запроса (например, hx-trigger="change, reset delay:0.01s").