hx-ptag

Пропускайте опросы без изменений с помощью HX-PTag: "v42"

Расширение ptag добавляет теги опроса (метаданные) для отдельных элементов, позволяя серверу пропускать замену содержимого, если оно не изменилось. Оно работает как ETag в HTTP, но на уровне приложения и элементов, а не протокола и URL.

Полезно в сценариях опроса, когда ответы зависят от того, какое содержимое уже было отправлено клиенту.

Установка

<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-ptag.js"></script>

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

Когда ответ содержит заголовок HX-PTag, расширение сохраняет его значение в исходном элементе. При последующих запросах от этого элемента сохранённое значение отправляется в заголовке запроса HX-PTag.

Сервер может использовать полученное значение HX-PTag, чтобы определить подходящий ответ. Если ничего не изменилось, сервер отвечает 304 Not Modified, и htmx пропускает замену содержимого.

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

Базовый опрос

<div hx-get="/news" hx-trigger="every 3s">
    Latest News...
</div>

Сервер возвращает содержимое вместе с заголовком ptag:

HTTP/1.1 200 OK
HX-PTag: "v42"

<div>Breaking: htmx 4 released!</div>

При следующем опросе htmx отправляет:

GET /news HTTP/1.1
HX-PTag: "v42"

Если ничего не изменилось, сервер отвечает 304 без тела ответа.

Пример на стороне сервера

@app.get("/news")
def news(request):
    current_tag = compute_news_hash()
    client_tag = request.headers.get("HX-PTag")

    if client_tag == current_tag:
        return Response(status_code=304)

    return Response(
        content=render_news(),
        headers={"HX-PTag": current_tag}
    )

Задание начального PTag

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

<div hx-get="/news" hx-trigger="every 3s" hx-ptag="v42">
    Latest News...
</div>

Полезно, когда сервер формирует исходную страницу и знает текущую версию.

Использование временной метки в PTag

Если ptag — это временная метка, сервер может использовать её, чтобы определить, какое новое содержимое отправить, а не только нужно ли его отправлять.

Конечная точка чата может использовать ptag, чтобы возвращать только сообщения, появившиеся после последнего опроса:

<div hx-get="/messages" hx-trigger="every 2s" hx-ptag="2026-03-13T00:00:00Z">
</div>

@app.get("/messages")
def messages(request):
    since = request.headers.get("HX-PTag")
    now = datetime.utcnow().isoformat() + "Z"
    new_messages = get_messages_between(since, now)
    if not new_messages:
        return Response(status_code=304)

    return Response(
        content=render_messages(new_messages),
        headers={"HX-PTag": now}
    )

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