Расширения

Htmx предоставляет механизм расширений для определения и использования расширений в приложениях, основанных на htmx.

Использование расширений

Использование расширения включает два шага:

включите определение расширения, которое добавит его в реестр расширений htmx
ссылка на расширение через атрибут hx-ext

Вот пример

  <script src="/path/to/ext/debug.js" defer></script>
  <button hx-post="/example" hx-ext="debug">This Button Uses The Debug Extension</button>

Это загружает расширение отладки с unpkg CDN и добавляет расширение отладки к данной кнопке. (Это выведет подробную запись в журнал для кнопки, для целей отладки.)

Обратите внимание, что тег hx-ext может быть размещен на родительских элементах, если вы хотите, чтобы плагин применялся к всей части DOM, и на теге body для его применения ко всем запросам htmx.

Подсказка: Чтобы использовать несколько расширений на одном элементе, разделяйте их запятыми:

  <button hx-post="/example" hx-ext="debug, json-enc">This Button Uses Two Extensions</button>

Игнорирование расширений

По умолчанию расширения применяются к узлу DOM, где они вызываются, вместе со всеми дочерними элементами внутри этого родительского узла. Если вам нужно отключить расширение где-либо в дереве DOM, вы можете использовать ключевое слово ignore:, чтобы остановить его использование.

<div hx-ext="debug">
  <button hx-post="/example">This button used the debug extension</button>
  <button hx-post="/example" hx-ext="ignore:debug">This button does not</button>
</div>

Включенные расширения

htmx включает набор расширений по умолчанию, которые удовлетворяют общим потребностям разработчиков. Эти расширения тестируются на htmx в каждом дистрибутиве.

Установка расширений

Исходный код включенных расширений можно найти по адресу https://unpkg.com/browse/htmx.org/dist/ext/. Вам нужно будет включить файл javascript для расширения, а затем установить его с помощью атрибутов hx-ext.

Дополнительные сведения см. в документации по соответствующему расширению.

Список включенных расширений

Расширение	Описание
`ajax-header`	включает широко используемый заголовок `X-Requested-With`, который идентифицирует запросы ajax во многих фреймворках бэкэнда
`alpine-morph`	расширение для использования плагина Alpine.js morph в качестве механизма подмены в htmx.
`class-tools`	расширение для управления временным добавлением и удалением классов на HTML-элементах
`client-side-templates`	поддержка обработки шаблонов на стороне клиента ответов JSON/XML
`debug`	расширение для отладки конкретного элемента с помощью htmx
`event-header`	включает сериализованную в формате JSON версию триггерного события, если таковое имеется
`head-support`	поддержка объединения тега `head` из ответов в существующие документы `head`
`include-vals`	позволяет включать дополнительные значения в запрос
`json-enc`	использовать кодирование JSON в теле запросов вместо стандартного `x-www-form-urlencoded`
`idiomorph`	расширение для использования алгоритма подмены idiomorph в качестве механизма подмены
`loading-states`	позволяет отключать элементы ввода, добавлять и удалять CSS-классы к любому элементу во время обработки запроса.
`method-override`	использовать заголовок `X-HTTP-Method-Override` для не-`GET` и `POST` запросов
`morphdom-swap`	расширение для использования библиотеки morphdom в качестве механизма подмены в htmx.
`multi-swap`	позволяет подменять несколько элементов с помощью различных методов подмены
`path-deps`	расширение для выражения зависимостей на основе путей, аналогично intercoolerjs
`preload`	предварительно загружает выбранные `href` и `hx-get` целевые элементы на основе правил, которые вы контролируете.
`remove-me`	позволяет удалять элемент после заданного времени
`response-targets`	позволяет задать разные целевые элементы для подмены при получении разных кодов HTTP-ответа
`restored`	позволяет вызывать события при нажатии кнопки «Назад»
`server-sent-events`	однонаправленная доставка сообщений с сервера через EventSource
`web-sockets`	двунаправленное подключение к серверам WebSocket
`path-params`	позволяет использовать параметры для переменных пути вместо отправки их в запросе или теле

Определение расширения

Для определения расширения вызывается функция htmx.defineExtension():

<script>
htmx.defineExtension('my-ext', {
onEvent : function(name, evt) {
        console.log("Fired event: " + name, evt);
    }
  })
</script>

Обычно это делается в отдельном файле javascript, а не в теге script в строке.

Расширения должны иметь имена, разделенные дефисами, которые достаточно короткие и описательные.

Расширения могут переопределять следующие стандартные точки расширения, чтобы добавить или изменить функциональность:

{
    onEvent : function(name, evt) {return true;},
    transformResponse : function(text, xhr, elt) {return text;},
    isInlineSwap : function(swapStyle) {return false;},
    handleSwap : function(swapStyle, target, fragment, settleInfo) {return false;},
    encodeParameters : function(xhr, parameters, elt) {return null;}
}

Licensed under the Zero-Clause BSD License.
https://htmx.org/extensions/