hx-history-cache

Восстановление страниц при переходе назад/вперёд из sessionStorage

Расширение history-cache заменяет стандартную обработку истории в htmx клиентским кэшем, хранящимся в sessionStorage. Когда пользователь переходит назад или вперёд, расширение мгновенно восстанавливает страницу из кэша, а не загружает её с сервера.

Установка

<script src="/path/to/htmx.js"></script>
<script src="/path/to/ext/hx-history-cache.js"></script>

Если вы используете пакет htmax, hx-history-cache уже включено, но по умолчанию отключено. Включите его с помощью:

<meta name="htmx-config" content='{"historyCache": {"disable": false}}'>

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

Изменения разметки не требуются. После загрузки скрипта вся навигация, управляемая htmx, автоматически кэшируется.

Чтобы исключить страницу из кэша, добавьте hx-history="false" в любом месте документа:

<div hx-history="false">
  <!-- This page will not be saved to the history cache -->
</div>

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

Все параметры находятся в htmx.config.historyCache и могут быть заданы с помощью метатега:

<meta name="htmx-config" content='{"historyCache": {"size": 20, "refreshOnMiss": true}}'>

Чтобы использовать морфинг для более плавного восстановления:

<meta name="htmx-config" content='{"historyCache": {"swapStyle": "outerMorph"}}'>

Параметр	По умолчанию	Описание
`size`	`10`	Максимальное количество страниц, сохраняемых в кэше. Сначала удаляются самые старые записи. Установите значение `0`, чтобы полностью отключить кэширование.
`refreshOnMiss`	`false`	Если значение `true`, принудительно перезагружает страницу, когда запрошенной записи истории нет в кэше.
`disable`	`false` (`true` в htmax)	Отключает расширение, не выгружая его. При использовании пакета htmax кэширование истории по умолчанию отключено — включите его с помощью метатега конфигурации.
`swapStyle`	`"outerSync"`	Стиль подмены htmx, используемый при восстановлении содержимого из кэша. По умолчанию используется `outerSync`: целевой элемент сохраняется в DOM (вместе со слушателями и состоянием компонента), его атрибуты синхронизируются, а дочерние элементы заменяются. Используйте `innerHTML`, чтобы заменить только дочерние элементы, не синхронизируя атрибуты. Для плавного сравнения DOM можно задать значение `"innerMorph"` или `"outerMorph"`.

События

Расширение генерирует следующие события на document:

Событие	Данные	Описание
`htmx:history:cache:before:save`	`{ target, head }`	Генерируется перед сохранением текущей страницы. Отмените событие, чтобы пропустить сохранение. Перед сохранением снимка можно изменить целевой DOM и `detail.head`.
`htmx:history:cache:after:save`	`{ content, head, scroll, title }`	Генерируется после сохранения страницы.
`htmx:history:cache:miss`	`{ path, refreshOnMiss }`	Генерируется, если запрошенной записи истории нет в кэше. Задайте `detail.refreshOnMiss = true`, чтобы принудительно перезагрузить страницу.
`htmx:history:cache:hit`	`{ path, item }`	Генерируется, когда запись найдена в кэше. Отмените событие, чтобы обойти кэш и позволить htmx загрузить данные с сервера.
`htmx:history:cache:before:restore`	`{ head, ready }`	Генерируется перед восстановлением содержимого из кэша. Задайте для `detail.ready` промис, чтобы отложить восстановление body.
`htmx:history:cache:after:restore`	`{ item, head, ready }`	Генерируется после восстановления содержимого из кэша, заголовка, прокрутки и аннотированного состояния. Получает данные события `before:restore` с добавленным `item`.

Пример: исключение определённых путей из кэша

document.addEventListener('htmx:history:cache:before:save', (evt) => {
    if (location.pathname.startsWith('/admin')) {
        evt.preventDefault();
    }
});

Пример: обработка отсутствующей записи в кэше

document.addEventListener('htmx:history:cache:miss', (evt) => {
    console.log('Cache miss for', evt.detail.path);
    evt.detail.refreshOnMiss = true; // reload instead of fetching via htmx
});

Пример: проверка найденной записи в кэше перед восстановлением

document.addEventListener('htmx:history:cache:hit', (evt) => {
    if (isStale(evt.detail.item)) {
        return false; // bypass cache, let htmx fetch fresh content
    }
});

Восстановление head

По умолчанию расширение сохраняет снимок <head>, но не восстанавливает его. Подключение расширения hx-head включает полное восстановление <head> при попадании в кэш. Таблицы стилей и блокирующие скрипты готовы до восстановления body. Отложенные скрипты выполняются после подмены body, перед восстановлением заголовка, прокрутки и состояния форм из кэша.

<script src="/path/to/ext/hx-history-cache.js"></script>
<script src="/path/to/ext/hx-head.js"></script>

Принцип работы

Перед навигацией (htmx:before:history:update): HTML текущей страницы, <head>, заголовок и положение прокрутки сериализуются и записываются в sessionStorage.
При переходе назад/вперёд (htmx:before:history:restore): расширение ищет целевой путь в кэше.
- Запись найдена: генерируется htmx:history:cache:hit, отменяется сетевой запрос ядра, а содержимое восстанавливается с помощью htmx.swap(). Если загружено hx-head, оно координирует восстановление head через событие кэша перед восстановлением и обычный цикл подмены.
- Запись не найдена: генерируется htmx:history:cache:miss. Если задано refreshOnMiss, страница перезагружается; в противном случае ядро обрабатывает запрос обычным образом.
Вытеснение записей из кэша: когда количество записей в кэше превышает size, удаляется самая старая запись. Если sessionStorage заполнен, записи удаляются с начала, пока запись не завершится успешно.

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