hx-trigger

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

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

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

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

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

Стандартные фильтры событий

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

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

Это событие будет выполнено, если событие клика выполнено с event.ctrlKey свойством, установленным в значение true.

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

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

И также может быть объединено, используя стандартный синтаксис JavaScript

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

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

Стандартные модификаторы событий

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

• once - событие будет выполнено только один раз (например, первый клик)
• changed - событие будет изменяться только в случае изменения значения элемента. Обратите внимание, что change — это имя события, а changed — имя модификатора.
• delay:<timing declaration> - перед тем, как событие вызовет запрос, произойдёт задержка. Если событие снова будет обнаружено, задержка сбросится.
• throttle:<timing declaration> - после того, как событие вызовет запрос, произойдёт ограничение скорости. Если событие будет снова обнаружено до завершения задержки, оно будет проигнорировано, элемент выполнит запрос в конце задержки.
• from:<Extended CSS selector> - позволяет событию, которое вызывает запрос, исходить от другого элемента в документе (например, прослушивание события нажатия клавиши на теле документа для поддержки горячих клавиш)
  • Стандартный CSS-селектор находит все элементы, соответствующие этому селектору. Таким образом, from:input прослушивает все поля ввода на странице.
  • Расширенный CSS-селектор здесь позволяет использовать следующие нестандартные CSS-значения:
    • document - прослушивать события в документе
    • window - прослушивать события в окне
    • closest <CSS selector> - находит ближайший предковый элемент или сам себя, соответствующий данному CSS-селектору
    • find <CSS selector> - находит ближайшего дочернего элемента, соответствующего данному CSS-селектору
    • next соответствует element.nextElementSibling
    • next <CSS selector> ищет в DOM вперёд первый элемент, соответствующий заданному CSS-селектору. (Например, next .error будет нацелен на ближайший следующий элемент-потомка с классом error)
    • previous соответствует element.previousElementSibling
    • previous <CSS selector> ищет в DOM назад первый элемент, соответствующий заданному CSS-селектору. (Например previous .error будет нацелен на ближайшего предыдущего элемента с классом error)
• target:<CSS selector> - позволяет фильтровать по CSS-селектору целевого элемента события. Это может быть полезно, когда вы хотите прослушивать триггеры от элементов, которые могут отсутствовать в DOM в момент инициализации, например, прослушивая на теле, но с фильтром целевого элемента для дочернего элемента
• consume - если этот параметр включён, событие не будет запускать другие запросы htmx на родительских элементах (или на элементах, прослушивающих события на родительских элементах)
• queue:<queue option> - определяет, как события помещаются в очередь, если событие возникает, когда запрос на другое событие находится в процессе выполнения. Параметры:
  • first - поместить первое событие в очередь
  • last - поместить последнее событие в очередь (по умолчанию)
  • all - поместить все события в очередь (выполнить запрос для каждого события)
  • none - не помещать новые события в очередь

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

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

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

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

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

• load - срабатывает при загрузке (полезно для ленивой загрузки чего-либо)
• revealed - срабатывает, когда элемент прокручивается в область просмотра (также полезно для ленивой загрузки). Если вы используете overflow в CSS, например, overflow-y: scroll, вы должны использовать intersect once вместо revealed.
• intersect - срабатывает один раз, когда элемент впервые пересекает область просмотра. Поддерживает два дополнительных параметра:
  • root:<selector> - CSS-селектор корневого элемента для пересечения
  • threshold:<float> - число с плавающей запятой от 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">
    Triggered by HX-Trigger header...
  </div>

для запуска.

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

Опрос

Используя синтаксис every <timing declaration> можно периодически проводить опрос элемента:

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

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

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

<div hx-get="/latest_updates" hx-trigger="every 1s [someConditional]">
  Nothing Yet!
</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:nearest (form input))