Руководство по событиям htmx

Прослушивание событий

Событие htmx можно прослушивать тремя способами.

Используйте htmx.on(), который по умолчанию прослушивает document:

htmx.on('htmx:after:swap', function (evt) {
    console.log('swapped', evt.detail.ctx.target);
});

Используйте стандартный метод addEventListener:

document.body.addEventListener('htmx:after:init', function (evt) {
    setUpElement(evt.detail.elt);
});

Или добавьте атрибут hx-on:* непосредственно к элементу:

<button hx-post="/example"
        hx-on:htmx:config:request="ctx.request.body.set('source', 'button')">
    Post Me!
</button>

События htmx всплывают, поэтому обработчик на document или document.body видит события от всех элементов. Используйте атрибут hx-on:*, если нужно обрабатывать события только одного элемента.

Детали события

Большинство событий htmx содержат объект detail. Для событий запроса и подстановки detail.ctx — это контекст запроса. Он содержит исходный элемент, целевой элемент, стиль подстановки, запрос и, после получения ответа, сам ответ.

htmx.on('htmx:before:request', function (evt) {
    let ctx = evt.detail.ctx;
    console.log(ctx.request.method, ctx.request.action, ctx.target);
});

В атрибуте hx-on:* каждое свойство detail уже доступно в текущей области видимости, поэтому вместо event.detail.ctx можно написать ctx.

В событиях жизненного цикла элементов используется detail.elt — элемент, обработанный htmx.

Отмена события

События htmx можно отменить. Вызовите preventDefault(), чтобы остановить дальнейшую работу htmx:

htmx.on('htmx:before:request', function (evt) {
    if (!isLoggedIn()) {
        evt.preventDefault();
    }
});

Отмена по-разному влияет на каждое событие:

Жизненный цикл событий

События запроса

Эти события возникают в указанном порядке при каждом запросе.

События подстановки

События жизненного цикла элементов

События истории

Полный список, включая события-триггеры load, intersect и every, см. в справочнике событий.

Типовые решения

Инициализация сторонней библиотеки

Новый контент, добавленный htmx с помощью подстановки, неизвестен другим вашим библиотекам. Подпишитесь на htmx:after:init, чтобы настроить его:

htmx.on('htmx:after:init', function (evt) {
    setUpElement(evt.detail.elt);
});

Также можно использовать htmx.onLoad() — сокращённую запись для этого.

Добавление значения в каждый запрос

Событие htmx:config:request возникает до кодирования тела запроса, поэтому ctx.request.body пока ещё является объектом FormData:

htmx.on('htmx:config:request', function (evt) {
    evt.detail.ctx.request.body.set('csrf-token', getToken());
});

Чтобы вместо этого добавить заголовок, присвойте значение ctx.request.headers:

htmx.on('htmx:config:request', function (evt) {
    evt.detail.ctx.request.headers['X-CSRF-Token'] = getToken();
});

Изменение целевого элемента или стиля подстановки

Оба параметра находятся в контексте, поэтому их можно изменить вплоть до момента подстановки:

htmx.on('htmx:before:swap', function (evt) {
    if (evt.detail.ctx.response.status === 404) {
        evt.detail.ctx.target = document.querySelector('#errors');
    }
});

Декларативный вариант этого решения описан в разделе hx-status.

Запись событий в журнал

Установите для htmx.config.logAll значение true, чтобы записывать все события htmx в консоль:

htmx.config.logAll = true;

Также можно задать это из HTML:

<meta name="htmx-config" content="logAll:true">

htmx всегда записывает на уровне ошибок события, в деталях которых содержится error, а на уровне предупреждений — события, в деталях которых содержится warn. logAll добавляет все остальные события.

См. также

• Скрипты на стороне клиента
• Атрибуты hx-on:*
• Справочник событий
• Руководство по созданию расширений htmx, в котором показано, как перехватывать те же события из расширения