Запросы и ответы

Htmx ожидает, что ответы на AJAX-запросы, которые он делает, будут в формате HTML. Обычно это фрагменты HTML (хотя полный HTML-документ, соответствующий тегу hx-select, также может быть полезен). Htmx затем заменит возвращённый HTML в документе в указанной цели и с указанной стратегией замены.

Иногда вы можете захотеть ничего не делать при замене, но всё же, возможно, вызвать событие на стороне клиента (см. ниже).

В этом случае по умолчанию вы можете вернуть код ответа 204 - No Content, и htmx проигнорирует содержимое ответа.

В случае ошибки ответа от сервера (например, 404 или 501) htmx вызовет событие htmx:responseError, которое вы можете обработать.

В случае ошибки соединения будет вызвано событие htmx:sendError.

Настройка обработки ответов

Вы можете настроить вышеописанное поведение htmx, изменяя или заменяя массив htmx.config.responseHandling. Этот объект представляет собой коллекцию объектов JavaScript, определённых следующим образом:

responseHandling: [
    {code:"204", swap: false},   // 204 - No Content по умолчанию ничего не делает, но не является ошибкой
    {code:"[23]..", swap: true}, // Ответы 200 и 300 не являются ошибками и заменяются
    {code:"[45]..", swap: false, error:true}, // Ответы 400 и 500 не заменяются и являются ошибками
    {code:"...", swap: false}    // захват всех других кодов ответа
]

Когда htmx получает ответ, он будет по порядку проходить по массиву htmx.config.responseHandling и проверять, соответствует ли свойство code данного объекта, рассматриваемое как регулярное выражение, текущему ответу. Если запись соответствует текущему коду ответа, она будет использована для определения того, как будет обрабатываться ответ.

Доступные поля для конфигурации обработки ответов в записях этого массива:

code - строка, представляющая регулярное выражение, которое будет проверяться на соответствие кодам ответа.
swap - true, если ответ должен быть заменен в DOM, false в противном случае.
error - true, если htmx должен рассматривать этот ответ как ошибку.
ignoreTitle - true, если htmx должен игнорировать теги заголовков в ответе.
select - CSS-селектор, который будет использоваться для выбора содержимого из ответа.
target - CSS-селектор, указывающий альтернативную цель для ответа.
swapOverride - альтернативный механизм замены для ответа.

Примеры настройки обработки ответов

В качестве примера того, как использовать эту конфигурацию, рассмотрим ситуацию, когда серверный фреймворк отвечает с кодом 422 - Unprocessable Entity при возникновении ошибок валидации. По умолчанию htmx проигнорирует ответ, так как он соответствует регулярному выражению [45]...

Используя механизм мета-конфигурации для настройки responseHandling, мы могли бы добавить следующую конфигурацию:

<!--
  * 204 No Content по умолчанию ничего не делает, но не является ошибкой.
  * Ответы 2xx, 3xx и 422 не являются ошибками и заменяются.
  * Ответы 4xx и 5xx не заменяются и являются ошибками.
  * Все остальные ответы заменяются с использованием "..." в качестве захвата всех.
-->
<meta
  name="htmx-config"
  content='{
        "responseHandling":[
            {"code":"204", "swap": false},
            {"code":"[23]..", "swap": true},
            {"code":"422", "swap": true},
            {"code":"[45]..", "swap": false, "error":true},
            {"code":"...", "swap": true}
        ]
    }'
/>

Если вы хотите заменить все ответы, независимо от кода HTTP, вы можете использовать следующую конфигурацию:

<!--все ответы заменяются-->
<meta name="htmx-config" content='{"responseHandling": [{"code":".*", "swap": true}]}' />

Наконец, стоит рассмотреть возможность использования расширения Response Targets, которое позволяет вам настраивать поведение кодов ответов декларативно через атрибуты.

CORS

При использовании htmx в контексте кросс-доменных запросов не забудьте настроить ваш веб-сервер для установки заголовков Access-Control, чтобы заголовки htmx были видимы на стороне клиента.

Посмотреть все заголовки запроса и ответа, которые реализует htmx

Заголовки запроса

htmx включает в себя ряд полезных заголовков в запросах:

Заголовок	Описание
`HX-Boosted`	указывает, что запрос выполнен через элемент с использованием hx-boost
`HX-Current-URL`	текущий URL браузера
`HX-History-Restore-Request`	”true”, если запрос предназначен для восстановления истории после пропуска в локальном кэше истории
`HX-Prompt`	ответ пользователя на hx-prompt
`HX-Request`	всегда “true”
`HX-Target`	`id` целевого элемента, если он существует
`HX-Trigger-Name`	`name` триггерного элемента, если он существует
`HX-Trigger`	`id` триггерного элемента, если он существует

Заголовки ответа

htmx поддерживает некоторые специфические для htmx заголовки ответа:

HX-Location - позволяет выполнить клиентский редирект без полной перезагрузки страницы.
HX-Push-Url - добавляет новый URL в стек истории.
HX-Redirect - может быть использован для выполнения клиентского редиректа на новое местоположение.
HX-Refresh - если установлено в true, клиентская сторона выполнит полное обновление страницы.
HX-Replace-Url - заменяет текущий URL в адресной строке.
HX-Reswap - позволяет указать, как будет выполнена замена ответа. См. hx-swap для возможных значений.
HX-Retarget - CSS-селектор, который обновляет цель обновления содержимого на другой элемент на странице.
HX-Reselect - CSS-селектор, который позволяет выбрать, какая часть ответа будет использована для замены. Переопределяет существующий hx-select на триггерном элементе.
HX-Trigger - позволяет вызывать клиентские события.
HX-Trigger-After-Settle - позволяет вызывать клиентские события после этапа завершения.
HX-Trigger-After-Swap - позволяет вызывать клиентские события после этапа замены.

Для получения дополнительной информации о заголовках HX-Trigger смотрите Заголовки ответа HX-Trigger.

Отправка формы через htmx имеет преимущество в том, что больше не требуется использовать шаблон Post/Redirect/Get. После успешной обработки POST-запроса на сервере вам не нужно возвращать HTTP 302 (Redirect). Вы можете напрямую вернуть новый HTML-фрагмент.

Также вышеуказанные заголовки ответа не передаются htmx для обработки с кодами ответа 3xx Redirect, такими как HTTP 302 (Redirect). Вместо этого браузер перехватит редирект внутренне и вернет заголовки и ответ с перенаправленного URL. Где это возможно, используйте альтернативные коды ответа, такие как 200, чтобы позволить возвращать эти заголовки ответа.

Порядок операций запроса

Порядок операций запроса htmx:

Элемент срабатывает и начинает запрос
- Значения собираются для запроса
- К соответствующим элементам применяется класс htmx-request
- Запрос затем отправляется асинхронно через AJAX
  - После получения ответа целевой элемент помечается классом htmx-swapping
  - Применяется необязательная задержка замены (см. атрибут hx-swap)
  - Выполняется фактическая замена содержимого
    - класс htmx-swapping удаляется с целевого элемента
    - класс htmx-added добавляется к каждому новому фрагменту содержимого
    - класс htmx-settling применяется к целевому элементу
    - Выполняется задержка settling (по умолчанию: 20 мс)
    - DOM стабилизируется
    - класс htmx-settling удаляется с целевого элемента
    - класс htmx-added удаляется с каждого нового фрагмента содержимого

Вы можете использовать классы htmx-swapping и htmx-settling для создания CSS-переходов между страницами.