HCON

Синтаксис

Пары «ключ — значение»

Пары разделяются пробелами или запятыми. Оба варианта равнозначны.

key:value key2:value2
key:value, key2:value2

Типы значений

<!-- booleans -->
<button hx-get="/api" hx-config="validate">          <!-- validate: true -->
<button hx-get="/api" hx-config="validate:false">    <!-- validate: false -->

<!-- numbers -->
<button hx-get="/api" hx-config="timeout:5000">

<!-- strings, quotes needed when value contains spaces or special chars -->
<button hx-get="/api" hx-config='credentials:"include"'>
<button hx-get="/api" hx-config="cache:'no-cache'">

Точечная нотация для вложенных ключей

Используйте ., чтобы задать свойства вложенного объекта:

<meta name="htmx-config" content="sse.reconnect:true sse.reconnectDelay:1000">

В результате получается { sse: { reconnect: true, reconnectDelay: 1000 } }.

Резервный вариант с JSON

Любое значение, начинающееся с {, разбирается как JSON, а не как HCON. Это позволяет составлять конфигурацию на сервере и напрямую подставлять её:

<!-- server renders this -->
<meta name="htmx-config" content='{"defaultSwap":"outerHTML","transitions":true}'>

<!-- or on an element -->
<button hx-get="/api" hx-config='{"credentials":"include","timeout":5000}'>

JSON и HCON нельзя смешивать: вся строка должна быть записана в одном из этих форматов.

Экранирование запятых и специальных символов

Заключайте значения в кавычки, если они содержат запятые, пробелы или разделители HCON.

<!-- comma ends the trigger spec -->
<input hx-trigger="keyup from:.a, .b">

<!-- quoted, comma is part of the value -->
<input hx-trigger='keyup from:".a, .b"'>

<!-- space ends the bare value -->
<button hx-vals="message:hello world">

<!-- quoted, the whole phrase is the value -->
<button hx-vals='message:"hello world"'>

Используйте тот тип кавычек, который не используется в HTML-атрибуте:

<input hx-trigger="keyup from:'.a, .b'">
<input hx-trigger='keyup from:".a, .b"'>

Где используется HCON

hx-swap модификаторы

Сначала указывается стиль замены (не HCON), затем модификаторы разбираются как HCON:

<div hx-get="/update" hx-swap="innerHTML swap:200ms settle:100ms scroll:top">
<div hx-get="/update" hx-swap="outerHTML transition:true ignoreTitle:true">

Также поддерживается полная форма JSON. При использовании JSON, если "style" не указан, как и ожидалось, используется значение по умолчанию config.defaultSwap; если он указан, то переопределяет стиль:

<!-- modifiers only, style = config.defaultSwap -->
<div hx-swap='{"swap":"200ms","settle":"100ms"}'>

<!-- explicit style -->
<div hx-swap='{"style":"outerHTML","swap":"200ms"}'>

Доступные модификаторы замены: swap, settle, scroll, show, scrollTarget, showTarget, transition, strip, ignoreTitle, focusScroll, target.

hx-trigger модификаторы

Сначала указывается имя события, затем модификаторы:

<input hx-get="/search" hx-trigger="keyup delay:300ms">
<button hx-post="/save" hx-trigger="click throttle:1s">
<div hx-get="/poll" hx-trigger="every 2s">
<form hx-post="/submit" hx-trigger="submit once">

Доступные модификаторы триггера: delay, throttle, from, target, consume, changed, once.

hx-config

Объединяется с контекстом запроса до его отправки. Полезно для задания параметров fetch для отдельных элементов:

<button hx-get="/slow" hx-config="timeout:30000">
<button hx-get="/api/data" hx-config='credentials:"include" cache:"no-cache"'>

<meta name="htmx-config">

Задаёт глобальные значения htmx.config. Поддерживаются HCON и JSON:

<!-- HCON -->
<meta name="htmx-config" content="defaultSwap:outerHTML transitions:true">

<!-- JSON -->
<meta name="htmx-config" content='{"defaultSwap":"outerHTML","transitions":true}'>

<!-- nested via dot notation -->
<meta name="htmx-config" content="sse.reconnect:true sse.reconnectMaxAttempts:5">

HX-Location заголовок ответа

Сервер может вернуть в этом заголовке HCON или JSON:

HX-Location: /new-page
HX-Location: path:"/new-page" push:"true"
HX-Location: {"path":"/new-page","push":"true"}

Наследование атрибутов и :append

HCON — это формат разбора данных. Функция объединения :append находится на уровень выше — в системе наследования атрибутов htmx. Если использовать :append в имени атрибута, htmx объединяет значение дочернего элемента с унаследованным значением родительского, соединяя их (удаляя {}):

<div hx-headers:inherited='{"X-Tenant": "acme"}'>
  <button hx-get="/api"
          hx-headers:append='{"X-Request-ID": "123"}'>
    <!-- sends both headers -->
  </button>
</div>

Это работает с любым атрибутом, принимающим HCON/JSON, включая hx-vals и hx-headers.

Примечания и ограничения

• Для примитивных типов используйте литералы JSON. count:42 становится числом, enabled:true — логическим значением, а name:bob остаётся строкой.
• Используйте кавычки для группировки, а не для управления типом. Кавычки сохраняют пробелы, запятые и разделители. Значения в кавычках, представляющие числа и логические значения, всё равно разбираются как числа и логические значения.
• Записывайте длительности в естественном виде. 200ms, 2s и 1m остаются строками в HCON; htmx преобразует их там, где ожидаются длительности.
• Заключайте ключи с точками в кавычки, чтобы сохранить их в исходном виде. "a.b":1 создаёт {"a.b": 1}. Запись a.b:1 без кавычек создаёт {a: {b: 1}}.
• Заключайте пробелы и запятые в кавычки. Разделение по запятым с учётом HCON сохраняет запятые внутри [...], (...), <.../> и кавычек.
• Для массивов используйте JSON. В HCON нет синтаксиса литералов массивов, поэтому используйте резервный вариант с JSON, например {"items":[1,2,3]}.
• Для вложенных объектов используйте точечную нотацию. a.b.c:value работает; a:{b:{c:value}} — нет.
• Для выражений используйте js:. Значения HCON — это литералы, поэтому для динамических значений указывайте hx-vals="js:{token: getToken()}".
• Избегайте ключей прототипа. __proto__, constructor и prototype игнорируются.
• Выберите JSON или HCON. Строка, начинающаяся с {, считается JSON; смешивать эти два синтаксиса нельзя.

См. также

• hx-swap
• hx-trigger
• hx-vals
• hx-config