hx-upsert

Обновление или вставка элементов с hx-swap='upsert'

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

Установка

<script src="https://cdn.jsdelivr.net/npm/htmx.org@4.0.0/dist/htmx.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/htmx.org@4.0.0/dist/ext/hx-upsert.js"></script>

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

Используйте hx-swap="upsert", чтобы применить поведение upsert:

<button hx-get="/items" hx-swap="upsert" hx-target="#item-list">
    Refresh Items
</button>

<div id="item-list">
    <div id="item-1">Original Item 1</div>
    <div id="item-2">Original Item 2</div>
</div>

Когда сервер возвращает:

<div id="item-2">Updated Item 2</div>
<div id="item-3">New Item 3</div>

Результат будет таким:

<div id="item-list">
    <div id="item-1">Original Item 1</div>
    <div id="item-2">Updated Item 2</div>
    <div id="item-3">New Item 3</div>
</div>

Как это работает

Стиль подмены upsert:

Обновляет элементы с совпадающими ID (заменяет их outerHTML)
Вставляет новые элементы, у которых нет совпадающих ID
Сохраняет существующие элементы, отсутствующие в ответе

Настройка

Сортировка

Добавьте sort, чтобы расположить элементы по возрастанию ID:

<div hx-get="/items" hx-swap="upsert sort">

Используйте sort:desc для сортировки по убыванию:

<div hx-get="/items" hx-swap="upsert sort:desc">

Пользовательский атрибут ключа

Используйте key:attr для сортировки по другому атрибуту:

<div hx-get="/items" hx-swap="upsert key:data-priority sort">
    <div id="task-2" data-priority="1">High Priority</div>
    <div id="task-1" data-priority="5">Low Priority</div>
</div>

Добавление элементов без ключа в начало

По умолчанию элементы без ID добавляются в конец. Используйте prepend, чтобы вставлять их в начало:

<div hx-get="/items" hx-swap="upsert prepend">

Комбинированные модификаторы

<div hx-get="/items" hx-swap="upsert sort:desc prepend">

Использование с `<hx-partial>`

Можно использовать <hx-partial> с hx-swap="upsert" для целевого выполнения upsert в одном ответе:

<hx-partial hx-target="#main" hx-swap="innerHTML">
    <div>Updated main content</div>
</hx-partial>
<hx-partial hx-target="#item-list" hx-swap="upsert sort">
    <div id="item-2">Updated Item 2</div>
    <div id="item-5">New Item 5</div>
</hx-partial>

Ограничения

Сопоставлять и обновлять можно только элементы с атрибутами id
ID должны быть уникальными во всём документе
При сортировке используется сравнение localeCompare с учётом числовых значений, что может сказаться на производительности при работе с очень большими списками

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