Что нового в htmx 4

Несовместимые изменения

fetch() заменяет XMLHttpRequest

Все запросы используют нативный API fetch(). Это нельзя отменить.

Явное наследование

Добавьте :inherited к любому атрибуту, который должен наследоваться вниз по дереву DOM.

<!-- htmx 2: implicit inheritance -->
<div hx-confirm="Are you sure?">
    <button hx-delete="/item/1">Delete</button>
</div>

<!-- htmx 4: explicit inheritance -->
<div hx-confirm:inherited="Are you sure?">
    <button hx-delete="/item/1">Delete</button>
</div>

Работает с любым атрибутом: hx-boost:inherited, hx-target:inherited, hx-confirm:inherited и т. д.

Используйте :append, чтобы добавить значение к наследуемому, а не заменить его:

<div hx-include:inherited="#global-fields">
    <!-- appends .extra to the inherited value -->
    <form hx-include:inherited:append=".extra">...</form>
</div>

Вернуть прежнее поведение: htmx.config.implicitInheritance = true

Подмена ответов с ошибками

htmx 4 подменяет содержимое при получении всех HTTP-ответов. Подмена не выполняется только для 204 и 304.

В htmx 2 ответы 4xx и 5xx не подменялись. В htmx 4, если сервер возвращает HTML с кодом 422 или 500, этот HTML подставляется в целевой элемент. Создавайте ответы с ошибками так, чтобы их HTML можно было использовать для подмены, или используйте hx-status, чтобы задать поведение для отдельных кодов.

Вернуть прежнее поведение: htmx.config.noSwap = [204, 304, '4xx', '5xx']

hx-delete не включает данные формы

Как и hx-get, hx-delete больше не включает поля родительской формы.

Исправление: при необходимости добавьте hx-include="closest form".

Без кэширования истории

История больше не кэширует страницы в localStorage. При переходе назад htmx повторно загружает страницу и подменяет содержимое в <body> или, если он присутствует, в элементе [hx-history-elt]. Поведение такое же, как в htmx 2.

Используйте htmx.config.history = "reload", чтобы вместо этого полностью перезагрузить страницу. Используйте htmx.config.history = false, чтобы отключить эту возможность.

Порядок внеполосной подмены

В htmx 2 элементы для внеполосной подмены (hx-swap-oob) подменялись до основного содержимого.

В htmx 4 сначала подменяется основное содержимое. Элементы для внеполосной подмены и <hx-partial> подменяются после него (в порядке следования в документе).

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

Модификатор hx-trigger queue удалён

Модификатор queue атрибута hx-trigger (например, hx-trigger="click queue:all") больше не работает. Постановка запросов в очередь теперь управляется исключительно атрибутом hx-sync.

<!-- htmx 2 -->
<div hx-trigger="click queue:all" hx-get="/test">...</div>

<!-- htmx 4: use hx-sync instead -->
<div hx-trigger="click" hx-get="/test" hx-sync="this:queue all">...</div>

Тайм-аут 60 секунд

В htmx 2 тайм-аута не было (0). В htmx 4 параметру defaultTimeout задано значение 60000.

Вернуть прежнее поведение: htmx.config.defaultTimeout = 0

Загрузка расширений

Подключайте скрипты расширений напрямую. Атрибут не нужен:

<script src="/path/to/htmx.js"></script>
<script src="/path/to/ext/sse.js"></script>

Ограничьте список расширений, которые могут загружаться:

<meta name="htmx-config" content='{"extensions": "sse, ws"}'>

Авторы расширений используют htmx.registerExtension(name, methodMap) для регистрации.

Подробнее см. в разделе Система расширений.

Переименования и удаления

Атрибуты

Выполните переименование hx-disable до обновления. В htmx 2 hx-disable означал «не обрабатывать этот элемент средствами htmx». В htmx 4 для этого используется hx-ignore, а hx-disable теперь выполняет функцию, которую раньше выполнял hx-disabled-elt.

События

Все события теперь следуют новому шаблону: htmx:phase:action[:sub-action]. Большинство событий ошибок объединены в htmx:error. Для HTTP-ответов с ошибками используется htmx:response:error.

Конфигурация

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

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

JavaScript API

По-прежнему доступны: htmx.ajax(), htmx.config, htmx.find(), htmx.findAll(), htmx.on(), htmx.onLoad(), htmx.parseInterval(), htmx.process(), htmx.swap(), htmx.trigger().

Что нового

Атрибуты

Модификаторы прокрутки hx-swap

Модификаторы show и scroll больше не поддерживают комбинированный синтаксис selector:position. Вместо этого используйте отдельные ключи:

<!-- htmx 2 (broken in 4) -->
<div hx-swap="innerHTML show:#other:top"></div>

<!-- htmx 4 -->
<div hx-swap="innerHTML show:top showTarget:#other"></div>
<div hx-swap="innerHTML scroll:bottom scrollTarget:#other"></div>

Стили hx-swap

<div hx-get="/data" hx-swap="innerMorph">...</div>
<div hx-get="/data" hx-swap="outerMorph">...</div>
<div hx-get="/text" hx-swap="textContent">...</div>
<div hx-get="/remove" hx-swap="delete">...</div>

• innerMorph / outerMorph: подмена с морфингом с использованием алгоритма idiomorph. Лучше подходит для сохранения состояния в сложных интерфейсах.
• textContent: установить текстовое содержимое целевого элемента (без разбора HTML).
• delete: полностью удалить целевой элемент.

Новые псевдонимы существующих стилей подмены (работают как старые, так и новые названия):

Подмены по коду состояния

Задайте разное поведение подмены для каждого кода состояния HTTP:

<form hx-post="/save"
      hx-status:422="swap:innerHTML target:#errors select:#validation-errors"
      hx-status:5xx="swap:none push:false">
    <!-- form fields -->
</form>

Доступные ключи конфигурации: swap:, target:, select:, push:, replace:, transition:.

Поддерживаются точные коды (404), подстановочные символы для одной цифры (50x) и подстановочные символы для диапазонов (5xx). Проверка выполняется в порядке убывания специфичности.

<hx-partial>

Нацеливайте ответ на несколько элементов. Альтернатива hx-swap-oob для случаев, когда требуется явно управлять выбором целевых элементов и стратегией подмены:

<hx-partial hx-target="#messages" hx-swap="beforeend">
    <div>New message</div>
</hx-partial>

<hx-partial hx-target="#count">
    <span>5</span>
</hx-partial>

Каждый <hx-partial> задаёт собственную стратегию hx-target и hx-swap. Полную документацию см. в разделе Обновления нескольких целевых элементов.

Переходы между представлениями

Поддержка API переходов между представлениями доступна, но по умолчанию отключена.

Включить: htmx.config.transitions = true

Совместимость с JSX

Во фреймворках, не поддерживающих : в именах атрибутов, можно использовать metaCharacter, чтобы заменить его:

htmx.config.metaCharacter = "-";
// hx-ws-connect instead of hx-ws:connect
// hx-confirm-inherited instead of hx-confirm:inherited

Методы JavaScript

• htmx.timeout(time): возвращает промис, который разрешается по истечении задержки (число миллисекунд или строка интервала '500ms'/'1s'/'5m')

htmx.takeClass удалён из ядра. Аналогичные возможности предоставляет расширение hx-live в пространстве имён htmx.live:

htmx.live.take(target, className, source)   // strip class from `source`, add to `target`
htmx.live.forEvent(...args)                 // race events/timeouts
htmx.live.nextFrame()                       // promise that resolves on next animation frame
htmx.live.q(selector)                       // jQuery-like proxy rooted at documentElement
htmx.live.debounce(ms[, fn])                // global debounce
htmx.live.refresh()                         // recompute every live expression

В области видимости выражений hx-live/hx-on они доступны без префикса (take, forEvent, nextFrame, q, debounce, toggle); в качестве неявного контекста используется текущий элемент. См. документацию расширения hx-live.

Автоматически регистрируемые события

События, инициированные внутри библиотеки, выводятся в консоль следующим образом:

• Если для события задано detail.error, вывод направляется в console.error (если применимо, экземпляр Error сначала выводится целиком, чтобы DevTools отобразил стек вызовов). Сюда относятся сбои запросов, исключения в обработчиках hx-on и другие случаи выбрасывания исключений. Приложения, подписанные на htmx:error, получают те же данные через событие.
• Если задано detail.warn, вывод направляется в console.warn.
• В противном случае событие записывается на уровне console.log (по умолчанию сообщения не отображаются; задайте htmx.config.logAll = true, чтобы показывать их).

Это восстанавливает соглашение htmx 2.x: чтобы внутренний сбой отображался в консоли, отправьте событие с detail.error (или detail.warn); настройка console.error для каждого сайта не требуется.

Контекст запроса в событиях

Все события предоставляют согласованный объект ctx с информацией о запросе и ответе.

События

Ключи конфигурации

Основные расширения

Теперь htmx 4 поставляется с множеством «основных» расширений. Расширения SSE и WebSocket были значительно переработаны, а hx-multipart, hx-live, hx-targets, hx-ptag, hx-csp, hx-download, hx-prompt и hx-history-cache — новые. Подробности см. в руководствах по обновлению для этих расширений.