Back to "HTMX з ASP.NET Core Partials: ServerM SK2Side Renaissance"

This is a viewer only at the moment see the article on how this works.

To update the preview hit Ctrl-Alt-R (or ⌘-Alt-R on Mac) or Enter to refresh. The Save icon lets you save the markdown file to disk

This is a preview from the server running through my markdig pipeline

ASP.NET Core HTMX HTMX.NET Web Development

HTMX з ASP.NET Core Partials: ServerM SK2Side Renaissance

Friday, 28 November 2025

Введение

Якщо ви збудували традиційні ASP.NET Core MVC-приложения, ви знаєте проблемуM SK3 яка боїлась вас МSK4 клацання спалахом МSK5 коли użytkownicy переміщуються між сторінками . повна сторінка перезагрузується MSC7 хром blinking браузера M SK8 зміст стрибає навколо, так як нова сторінка відображає . Це працює MST10 але це не працюєMST11t відчувати сучасний.

Технологія повернення частинних фрагментів HTML з сервера і заміни їх на DOM вирішує це - і це не ' не нове МSK2 Я МSK3 користуюсь цим шаблоном з часів jQuery XMLHttpRequest. Що змінилося? Як вишуканим це' стало HTMX.

HTMX дає нам декларативний спосіб робити те, що ми завжди робили'МSK1 повертаємо серверM SK2 надсилаємо HTML і поміняємо його на сторінку . більше не пишемо за замовчанням JavaScript для кожного інтерактиву МSK4 більше немає вибору між MSC5правильним" сервером M SK7 сторонним розвитком та гладким пользователем . З HT MXMスク9 ми отримуємо обидваMسک10

Article: Ця стаття зфокусується на стороні ASP.NET Core integration side . Для глибокого занурення у події HTMX, життєвий циклM SK3 та налаштування rozszerzeńMSC4 читайте мою допомічну статтюMスク5 Успілковий тур по HTMX розширенням та використанню HT MX з ASP.NET Core.

В цьому artykule я покажу вам, як HTMX прекрасно інтегрується з ASP HTMX.NET бібліотека робить його ще кращим, і як моя mostlylucid.pagingtaghelper Pakiet NuGet використовує HTMX, що надає потужну папку з мінімальною конфігурацією.

Цей підхід є структурним, а також анонімним. - Джанґо додав фрагменти шаблонів у версії. | 6.0, | Rails має Turbo Frames | МSK3 | а більша мережевая екосистема поширюється на HTML |- | над МSK5 | мSK6 | патерни дроту |МSK7 | Це \ ' | хороший час для створення серверу \ МSK9 | переданих програм \МSK10 |

Що таке HTMX?

HTMX - це бібліотека, яка дає вам доступ до сучасних функцій браузера безпосередньо з HTML, замість того, щоб писати JavaScriptM SK1 Вона розширює HTML з атрибутами, які дають вам змогу робити AJAX-запити , обмінювати змістом M SK3 і створювати багато інтерактивів - все, не залишаючи свого маркупа

Найчастіше використовуєте ключові атрибути'

  • hx-get, hx-post, hx-put, hx-delete - Зробіть HTTP-запити
  • hx-target - Вказувати, де поставити відповідь
  • hx-swap - Контроль того, як контент змінюється innerHTMLM SK2 outerHTMLМSK3 і т.д.
  • hx-trigger - Визначати, що спричиняє виклик запиту
  • hx-push-url - Обновлюйте URL браузера без перезавантаження сторінки

Тут: МСК0 - краса цього: МSK1 - ви, МSK2 - ви все ще пишете сервер; МSK3 - сторонній код; , - повертаючий сервер. МSK5 - присвоєний HTML. МСК6 - Немає API для JSON; МСК7 - ні клієнта; МСК8 - сторонні шаблони; ММСК9 - немає конвеєрів для будування. ММСк10 - просто хороший старий.

Модель такою ж старою, як і сама AJAX

До HTMX, ми досягли такого ж результату з значно більшою церемоніей . ТутM SK2 ось як виглядали частинні оновлення в епоху jQuery:

// jQuery circa 2010
$('#load-more').click(function() {
    $.ajax({
        url: '/posts/page/' + currentPage,
        success: function(html) {
            $('#posts-container').append(html);
            currentPage++;
        }
    });
});

І навіть раніше, з ванильовим JavaScript:

// Vanilla JS circa 2005
var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
    if (xhr.readyState === 4 && xhr.status === 200) {
        document.getElementById('content').innerHTML = xhr.responseText;
    }
};
xhr.open('GET', '/partial-content', true);
xhr.send();

Сервер - сторонній шаблон був ідентичний - повертає HTML фрагменти МSK2 поміняє їх на DOM МSK3 HTMX просто переміщує цю логіку з JavaScript в HTML атрибути | , | роблячи її декларативною | МSK5 | відкриючою |, | і набагато меншою помилкою |

ASP. NET-розробники роблять це вже роками PartialView() з першого дня в МVC, Html.RenderAction() для складних фрагментів - можливості завжди були там . нам бракувало элегантного МSK2 стандартизованого способу підключення з боку клієнта МSK3 HTMX чудово заповнює цю прогалину

Поширена індустрія також знову відкриває ці шаблони. МСК0 Термини, такі як " SSR " МSK3Сервер.- Східне відображання. МSK5 " гібридне відтворювання. ", та |" архітектура островів. МСК9 по суті описують те, що сервери. | - | Східні фреймворки завжди робили.

Установлення HTMX в ASP.NET Корі

Перше, включити HTMX у свій макет. Ви можете використати CDN або застосувати його локально

<script src="https://unpkg.com/[email protected]"></script>

МSK0 - це воно. МSK1 - Ніхто не будує, МSK2 - ні установки, , - ні конфігурації веб-пакета. . - Просто вкиньте скриптовий значок і ви - МSK5 - підете на гонки.

Alpine.jsM SK1 Client-Side Component

Для клієнта-залежна реактивність M SK1об ’ єкті МSK2уховані елементи МSK3помикаючі стани , локальний стан інтерфейсу \ ), Alpine.js доповнює HTMX ідеально. На лише M SK1KB gzipped, це надає VueMSC3ReactMska4подібну декларативну реактивність без bloatMска5

<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"></script>

Ось як вони працюють разом.

<div x-data="{ open: false }">
    <button x-on:click="open = !open">Toggle</button>
    <div x-show="open" x-transition>
        <button hx-get="/api/data" hx-target="#results">Load Data</button>
    </div>
</div>

Альпіне управляє локальною інтерфейсом ( перемиканняM SK1 HTMX управляє серверними дзвінками | ( | залученням даних | МSK3 | Впродовж цього artykułу |МSK4 | ви |' | побачите цей шаблон | МSK6 | Альпіно для реактивності клієнта | мSK7 | HMX для взаємодії з серверами | .

Bibliotekа HTMX.NET

Халід Абуахме's HTMX.NET бібліотека надає перший-клас ASP.NET Коренная інтеграціяM SK2 Доступна як Htmx і Htmx.TagHelpers NuGet пакети, це відчувається природнім для .NET і робить роботу з HTMX абсолютним задоволенням . ВиMSC3 знайдете більше KhalidаM SK4 його прекрасного відкритогоMスク5забезпечної роботи на його GitHub.

Установлення

dotnet add package Htmx
dotnet add package Htmx.TagHelpers

У вашому _ViewImports.cshtml:

@addTagHelper *, Htmx.TagHelpers

Метод розширення IsHtmx()

Найпотрібнішою функцією є Request.IsHtmx() метод розширення,, який повідомляє вам, чи запрос прийшов з HTMX

[HttpGet]
public async Task<IActionResult> Index(int page = 1, int pageSize = 20)
{
    var posts = await blogViewService.GetPagedPosts(page, pageSize);

    if (Request.IsHtmx())
        return PartialView("_BlogSummaryList", posts);

    return View("Index", posts);
}

Ця модель абсолютно блискуча. Одна дія контроллера працює для обох

  • Полна сторінка завантажується (вчас, коли użytkownicy переміщуються напряму або обновляютьсяM SK1
  • Часткове оновлення (, коли HTMX робить прохання)

Жодних окремих API-кінців , без дублованої логіки, без надрахунків на серіалізацію JSON МSK2

Поширена помилка: Багато програмістів ASP.NET вважають, що вам потрібні _ як префікс ( _BlogSummaryList.cshtml) щоб отримати частину рендерингаM SK1 Ви не маєте PartialView() сам метод каже ASP.NET Core пропустити макет. - це МSK2 говорить: МСК3 забудьте макет, МСК4 просто відтворіть цей біт return PartialView("SearchResults", model) з звичайним файлом для перегляду і він працює чудово. Конвенція, яка базується на концепції ASPM SK1 Веб-сторінки NET (WebMatrix) де він запобігає передачі файлів безпосередньо через URL МSK4 але MVC завжди захищає всі перегляди від прямого доступу в будь-якому разіMSC5 ЦеMسک6 це лише конвенція по наименованню, щоб допомогти визначити перегляди запланований як частинки.

HTMX.NET Допоміжні до ярликів

HTMX.NET надає вказівники на тегні, які роблять роботу з контроллерами чистішою.

<button
    hx-controller="Comment"
    hx-action="GetCommentForm"
    hx-post
    hx-target="#commentform">
    Reply
</button>

Це генерує правильний маршрут, використовуючи ASP.NET Core

Ось справжній приклад цього блогу:

<button
    class="btn btn-outline btn-sm mb-4"
    hx-action="Comment"
    hx-controller="Comment"
    hx-post
    hx-vals
    x-on:click.prevent="window.mostlylucid.comments.setValues($event)"
    hx-on="htmx:afterSwap: window.scrollTo({top: 0, behavior: 'smooth'})"
    hx-swap="outerHTML"
    hx-target="#commentform">
    Comment
</button>

Зверніть увагу, як HTMX грає добре з Alpine.js M SK1x-on:click.prevent) для інколишніх бітів клієнта

Інші допоміжні HTMX.NET

Ця бібліотека також пропонує:

  • Request.IsHtmxNonBoosted() - перевірити, чи це HTMX-запрос, але не підштовхнутий
  • Request.IsHtmxRefresh() - Подивіться, чи це ' - запит про відновлення історії
  • Допоможники реагування для заголовків HTMX ( триггериM SK1 перенаправки, і т.д.

Справжня-World Example: Поиск із частинками

Тут – МСК0 – пошуковий контролер цього блогу. МСК1 – показує три послідовності зворотнього зв 'язку.

[HttpGet]
[OutputCache(Duration = 3600, VaryByHeaderNames = new[] { "hx-request", "pagerequest" })]
public async Task<IActionResult> Search(
    string? query,
    int page = 1,
    int pageSize = 10,
    [FromHeader] bool pagerequest = false)
{
    var searchModel = await BuildSearchModel(query, page, pageSize);

    if (pagerequest && Request.IsHtmx())
        return PartialView("_SearchResultsPartial", searchModel.SearchResults);

    if (Request.IsHtmx())
        return PartialView("SearchResults", searchModel);

    return View("SearchResults", searchModel);
}

Три зворотньі шляхи для трьох сценаріїв:

  1. Запити на веб-сторінку - мінімальний частинний МSK1просто список результатівM SK2
  2. Зміни в фільтрах - відрізок частково МSK1 результати з фильтрамиM SK2
  3. Пряма навігація - повна сторінка МSK1разгортання МSK2 все )

Частковий вид (_SearchResultsPartial.cshtml) використовує вказівник міток

@model Mostlylucid.Models.Blog.PostListViewModel
<div class="pt-2" id="content">
    @if (Model.Data?.Any() is true)
    {
        <div class="inline-flex w-full items-center justify-center pb-4">
            @if (Model.TotalItems > Model.PageSize)
            {
                <pager
                    x-ref="pager"
                    link-url="@Model.LinkUrl"
                    hx-boost="true"
                    hx-target="#content"
                    hx-swap="show:none"
                    page="@Model.Page"
                    page-size="@Model.PageSize"
                    total-items="@Model.TotalItems"
                    hx-headers='{"pagerequest": "true"}'>
                </pager>
            }
        </div>
        @foreach (var post in Model.Data)
        {
            <partial name="_ListPost" model="post"/>
        }
    }
</div>

Зламання помічника теги веб-мейкера:

  • hx-boost="true" - Перехоплює посилання , конвертує в AJAX
  • hx-target="#content" - Де ввести реакцію
  • hx-headers='{"pagerequest": "true"}' - За замовчанням заголовок каже контроллеру, що це
  • Контролер перевіряє Request.IsHtmx() && pagerequest щоб повернути лише мінімальну частину

Найяскравіший пакет .pagingtaghelper

Я написала mostlylucid.pagingtaghelper для того, щоб уникнути повторюваної сторінки коду. ItM SK1s HTMX-first but works without JavaScript too .

Установлення

dotnet add package mostlylucid.pagingtaghelper

Dodaj до _ViewImports.cshtml:

@addTagHelper *, mostlylucid.pagingtaghelper

Найголовніше

Втілити IPagingModel<T> і ви МСК0 , Готові ,

public class BasePagingModel<T> : IPagingModel<T> where T : class
{
    public int Page { get; set; }
    public int TotalItems { get; set; }
    public int PageSize { get; set; }
    public string LinkUrl { get; set; }
    public List<T> Data { get; set; }
}

Що ви отримуєте:

  • Нужна нульова конфігурація
  • Множество інтерфейсів інтерфейсу (TailwindCSS + DaisyUI, Bootstrap
  • Підтримка темного trybу
  • 8 збудовані мови
  • Вибірники розміру сторінки
  • Прогрессивне покращення ( працює без Java-скриптуM SK1
  • Поддержка символів продовження для баз даних NoSQL

Помощник теги генерує посилання, які зберігають строки запиту, підтримують налаштування заголовківM SK1 і безперешкодно інтегруються з HTMX

Діаграма потоку HMX

Ось як працює ціла система.

graph TB
    A[Browser] -->|"Initial page load"| B[Controller Action]
    B -->|"Request.IsHtmx() = false"| C[Return Full View]
    C --> D[Render Layout + Partial]

    A -->|"User clicks pagination/filter"| E[HTMX Request]
    E -->|"hx-get with headers"| F[Same Controller Action]
    F -->|"Request.IsHtmx() = true"| G{Check Headers}
    G -->|"pagerequest header"| H[Return Minimal Partial]
    G -->|"No special header"| I[Return Section Partial]

    H --> J[Swap Content in Target]
    I --> J

    J -->|"User clicks another link"| E

    style B stroke:#333,stroke-width:2px
    style F stroke:#333,stroke-width:2px
    style C stroke:#0066cc,stroke-width:2px
    style H stroke:#00cc66,stroke-width:2px
    style I stroke:#00cc66,stroke-width:2px

Порівняння з іншими системами

Фрагменти szablonу Django

Джанґо додав до версії певну частину шаблонного відтворювання 6.0 (Декембрь МSK2 з фрагментами шаблонів МSK3 До того МСК4 Развивачі Джанго зазвичай використовували вміщування таг або третє МСК5 пакети, такі як django М СК6render M СК7block MСК8 ASP М סК9 NET Core мав PartialView() від версії 1.0 в МSK1 МSK2 різні фреймворки , різні часові строки M SK4 але одна і та ж дестинація : фрагменти HTML для HTMX MSC6

Корабли з турбо ramaми

Ruby on Rails має Turbo Frames (частину Hotwire),, яка схожа на spiritM SK2

<%= turbo_frame_tag "posts" do %>
  <%= render @posts %>
<% end %>

Різниця в тому, що Turbo потребує конкретних маркерів для кадру, як для запиту, так і для відповіді. . HTMX є більш гнучким. hx-target.

Живевізор Феникса

Elixir's Phoenix LiveView використовує інший підхід з постійними підключеннями до WebSocket і сервераM SK1 сторонній стан:

def handle_event("load_more", _params, socket) do
  {:noreply, assign(socket, posts: load_more_posts())}
end

LiveView блискуче для реального-застосувань часу,, але для підключень потрібен веб-сокет і серверний пам ’ ятьM SK2 HTMX використовує стару HTTP - безстатовийMSC4 вміщований в кэшіМSK5 масштабованийMスク6 Для блогуMST7 щоM ST8 ідеальнийM st9

Рівень ефективності

Виходи Caching: OutputCache атрибут змінюється hx-request заголовок, відокремлення повних сторінок та частин

[OutputCache(Duration = 3600, VaryByHeaderNames = new[] { "hx-request", "pagerequest" })]

Мощність мережі: Сервер - HTML, що передавається, часто менший за JSON МSK2 клієнт МSK3 шаблони на стороні \ , потребує менше обертів \ МSK5 \ і правильного резервуарного копію . \

Розмір пакету: HTMX

Заawansовані візерунки

Оптимістичні aktualiзації інтерфейсу - Об 'єднати HTMX та Альпіний для миттєвого зворотнього зв' язку

<div x-data="{ count: @Model.CommentCount }">
    <button hx-post="/comment/like" x-on:click="count++" hx-on::after-request="count = $event.detail.xhr.response">
        Likes: <span x-text="count"></span>
    </button>
</div>

Перерахунки миттєво оновляються: ( оптимістичний ), а потім синхронізуються з відповіддю сервера

Ззовні - МСК0, з-за МСК1 - С Swaps - Обновляти декілька розділів сторінки з одного відгуку

<div id="main-content"><!-- Main response --></div>
<div id="notification-count" hx-swap-oob="true"><span>5 new</span></div>

Чудово для значків повідомлень, рахунки koszykа , і т.д.M SK2 Я розкриваю цю модель у глибині Показ Toast і Swapping з HTMX.

Client-Templates Side with WebAPI - Іноді ви хочете середній - шляховий досвід МSK2 сервер M SK3 надсилання HTML для більшості речей , але JSON з WebAPI для конкретного динамічного контенту Client-sideM SK1extension шаблонів дозволяє робити саме це:

<script src="https://unpkg.com/[email protected]/client-side-templates.js"></script>
<script src="https://unpkg.com/mustache@latest"></script>

<div hx-ext="client-side-templates">
    <template id="post-template" type="text/mustache">
        {{#posts}}
        <div class="post">
            <h3>{{title}}</h3>
            <p>{{excerpt}}</p>
        </div>
        {{/posts}}
    </template>

    <button hx-get="/api/posts"
            hx-target="#post-list"
            mustache-template="post-template">
        Load Posts
    </button>
    <div id="post-list"></div>
</div>

Цей підхід працює з Mustache, Рухівними панелями , або шаблонами NunjucksM SK2 Ваш веб-API повертає JSON,, але HTMX керує рендеруючим klientомMSC4замість МSK5 ЦеMST6 особливо корисний, коли ви маєте існуючий API чи вам потрібно ділитися інформацією з мобільними програмамиMSL7 Для більшої інформації про розширення HT MX, включно з klientом, см. companion article.

Найкращі поради &

Програмне забезпечення для розв 'язання проблем: Установити Поширення виправника HTMX - показує кожен запит, відповідьM SK2 і обмін в реальному часі - часі

Торки CSRF

ASP.NET Core' антифайзерні टोकони потребують спеціального обробки з AJAXM SK2 HTMXMスク3NET надає кілька чистих варіантівMSC4 Рекомендується спосіб використання HtmxAntiforgeryScriptEndpoint:

// In Program.cs
app.MapHtmxAntiforgeryScript();
<!-- In your layout head -->
<script src="@HtmxAntiforgeryScriptEndpoints.Path" defer></script>

Або використовуйте вказівник теги: <meta name="htmx-config" includeAspNetAntiforgeryToken="true" />. Подивіться Article on HTMX Anti-Forgery Tokens для повних деталей.

Альпіанський.js M SK1 Шортханд в розорі

Альпіанці's @click короткострокові конфлікти з Razor's @ синтаксис. Замість цього используйте конкретну формуM SK1

<button x-on:click="doSomething()">Click me</button>  <!-- Instead of @click -->
<div x-bind:class="isOpen ? 'block' : 'hidden'"></div>  <!-- Instead of :class -->

Або втекти з @@click, але чіткіша синтаксиса

Керування історією

Контроль записів історії: По замовчуванню, HTMX поштовхує кожен запит в історію

<paging model="@Model" hx-push-url="false">  <!-- Don't add history entries -->

Або використати hx-replace-url="true" щоб оновити URL без додавання записів.

Часткова проблема Фантома: Повернімося до браузера/наперед - лише частинний фрагмент без макетуM SK1 виправимо з hx-history-elt на вашому контейнері з контентом:

<div class="container mx-auto" id="contentcontainer" hx-history-elt>
    @RenderBody()
</div>

Це вказує HTMX, який елемент сфотографувати, зберігаючи навколишній макет під час відновлення історії.

Caching CDN (CloudflareM SK1 і т.д.

Симптомен: HTMX працює локально, але виходить за межі CDN

Причина коріння: ЦДН ігнорують HX-Request заголовок. Ваш сервер повертає інший контент на основі цього заголовкаM SK1 але CDN зберігає їх однаково

ASP.NET Core fix: Використовувати VaryByHeaderNames:

[OutputCache(Duration = 3600, VaryByHeaderNames = new[] { "hx-request" })]

Сигнальний зв 'язок Konfigurувати правила кэшу, щоб включити HX-Request в ключі кэшу . Для Cloudflare : Окно на панелі МSK2 Хранение в кэші | → | Правила кэша | МSK4 | Набір ключів кэшів |→ | Заголовки |МSK6 | Включити HX-Request.

Обговорення hx-

hx-boost перетворює звичайні посилання на AJAX запити. Страница фраз HTMX зауважує, що деякі керівники команди рекомендують уникати цього. (залишає <head> зміст, впливає на локальність поведінкиМSK1, тоді як інші вважають, що це добре для швидких перемогM SK2

<div hx-boost="true" hx-target="#contentcontainer">
    <a asp-action="Show" asp-route-slug="@post.Slug">Read More</a>
</div>

Цей блог використовує його по-різному. Коли ми націлюємося на конкретні контейнери hx-get є чіткішим,, але hx-boost працює, якщо ви hx-boost="false" на елементах дитини.

Завершення

HTMX з ASP.NET Коренные частинки представляють повернення до сервера-ручну простоту без пожертвування сучасним UXM SK2 Ви отримуєте

  • Динамічні, SPAM SK1подібні взаємодії
  • Сервер -залежне відтворення МSK1вигідно для SEO
  • Правильна HTTPキャッシュування
  • Найнижчий JavaScript
  • Прогресивне покращення
  • Тип-безпечний маршрут з HTMX.NET
  • Нуль-конфигурація веб-сторінки з більш зрозумілимM SK1pagingtaghelper

Сервер \ - \ переданий підхід підтримав випробування часу \ МSK1 \ і з HTMX , \ він нарешті має элегантного клієнта \МSK3 \ стороннє інструментарій, якого він заслуговує \ мSK4 \ Ви можете побудувати надійні \ , \ веб-приложения, які будуть продуктивними, використовуючи шаблони, що працювали десятиліттями. \

Подібні статті в цьому блогі

Article Companion

Ця стаття є частиною серії двох частин на HTMX з ASP

  1. Цей artykuł - зосереджена на ASPM SK1 NET Коренная інтеграція , частинні переглядиМSK3 HTMX.NETMSC5 та відображання
  2. Вистроєна павутина HTMX Extensions - Глубокий занурення в події HTMX , життєвий цикл МSK2 архітектура rozszerzenia

Більше статей про HTMX

Дальне читання

офіційна документація:

Бібліотеки & НаrzędziаM SK1

Community Resources:

logo

© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.