Апгрэйд да htmx 4: Fetch, явна спадчына і тое, што ламаецца

Htmx апоўязаны на простай, спецыяльна выбранай немоднай стратэгіи: сервер вяртае HTML, прыгледвач уводзі гэты HTML у сторанку, і такім чынам ствараецца функцыйная аплікацыя без неабходнасці дакладнага копіювання всей інтэрфейсной структуры як кліентскага стану. Версія 4 захоўвае гэтую стратэгію, адночаса перабудоўваючы падстаўную сістэму на адной заснове сучасных прыемаў прыгледвачаў. У гэтым кярыранте пояснюецца, што і чаму зменілася, якія змены можа таямна зламаць існуючую аплікацыю, і як запусціць апдэйт у вигляде структураванага аудыту, а не проста падняць версію. Дакладныя вядомасці аднасоўваюцца да htmx 4, задокументаванага на момент напісання; перад міграцыяй паказваццаўна пераканайцеся ў конкрэтных деталях за дапамогою нотатак па выданні.

Контракт, які htmx 4 захоўвае

Дапамагае прыгадаць, што заменяе htmx. Тыповая аплікацыя, якая выконваецца на кліентэ, запрашоўвае у API данні у формате JSON, зберагае іх у JavaScript, выконвае компаненты на ўсёй гэтай базе дадзеных і постаўляе стан на кліянцы. Htmx адключае большую частку гэтага проміжнага шару. Сервер адпавядае тым форматам, які насправды патрэбны корыстніку, тым самым — HTML.

Разглядзім кнопку, прадзеяную атрыбутамі на кшталт hx-post, цэлью, напрыклад #task-list, і стратэгіяй адмены, якая дадае данні ў канцы. Калі хтось нажме на яе, htmx скупляе контэкст запиту, адправляе яго на сервер, парсуе паданыя данні і дадае іх у канцы спісу задач. Перакананне, автарызацыя, зберагчыцтва і адображэнне застаюцца на сервере. Абмен, навігацыя, фокус і сам дакумент застаюцца ў браузеры.

Это большае, чым простае названне для fetch(). Атрыбуты описваюць кантроль гіпермедыі: якія дзеянні ўзможны, куды яны надаюцца і як рэзультаты ўжоўвешчанняя павінны быць уключаныя ў чырвоную сторунку. Фрагмент, які вяртаецца, сам можа мець лінкі і формы, якія адказваюць пра наступныя дзеянні, так сама як і цэлая сторунка. Іншымі словамі, HTML застаецца протакалом прыемлена; htmx толькі координуе цей процес.

Версія 4 залечвае гэты публічны аспект практычна незменным. Тое, што ёй перарганізуецца, — гэта жыцёвы цикл пад ёю. Рэзультатам не яўляецца новая фронт-енд парадыгма, а болей строгія правіла ўжоўвешчанняя таго, як HTML, HTTP, DOM і сервер, який керуе станам, взаімаюцца.

Ядро, перабудавана на базе Fetch API

У болейшых версіях выкорыстоўвалася XMLHttpRequest. Гэта было логічна, калі htmx павінен быў працаваць у старэйшых браузерах, а XHR апавяралае прыбуткі пра прагрэс завантажэння, ад каторых залежалі дзеянні дазейна. Аднак з часам гэта рашэння па сумяшнасці ператворылася на архітектурны дывэнт. Команда htmx перапісала механізм запытам на аднойчыну з API Fetch, якае базуецца на обявленнях, спытваючы гэта ў меншам проекте пад назвай Fixi і з відтворэнням HTML у ручым режыме.

Прогназаваная схема назвавання прыбуткаў

Чыстэйшая структура выражаецца ў модэлі прыбуткаў. Назвы прыбуткаў тепер выконваюць аднаковы шаблон htmx:phase:action, за неабходнасцю расшыроўваючыся дапамога пад-дзеяння (htmx:phase:action:sub-action). Паколькі фаза прадушае, можна за мгненне з’ясаваць, чы рэагуе адчувальнік да прыбутку до чы пасля таго крока, які ён называе.

Кожны ўзнёмак, які стосуецца запыту, таксама отрымае той самы об’ект контэксту. Расшырэнняя і аберанты больш не павінны збираць розныя деталі, спецыфічныя для кожнага ўзнёмка, каб знайсці вучальны элемент, настройкі запыту, адпаведную адпаведь і процес абмяну; усё це знаходзіцца ў адным месцы. Запыты таксама отрымаюць фазу finally, якая запускаецца незалежна ад рэзультата: успеху, неудачы чы развіцця. Гэта і є правильны момент для выканання завершальных дзеянь, такіх як схованне індыкатора загрузкі чы павтовыяклэчванне кнопак.

Якща ваш кодавая база слухае ўзнёмкі htmx па імену, кожны аберант трэба пераглянуць, таму што старыя імены не падходзяць да новай схемы.

Рэшэйверы зняты, на іх месцы прыйшла платформа

Htmx 4 таксама відмовляецца ад дапаможных функцый, якія дублювалі API, якія браузеры тепер надаюць надзеяйна:

• htmx.addClass() заменяецца на element.classList.add()

htmx.closest() заменіўся на element.closest()

htmx.remove() заменіўся на element.remove()

Это правільны падход. Невялікая бібліятэка не павинна вечна выкорыстоўваць спецыяльныя API, калі платформа ўжо ўсваяе іх, а їх заменітелі — цэлком стандартныя вызывы DOM, якія ведае кожны развівальнік.

Пэрадача атрыбутаў тепер є необав’язковай

Найзначнейшая змяна пад час міграцыі не стосуецца Fetch. Htmx 4 больш не перадае большасць атрыбутаў па змоўе з элементаў-прадкуў.

Раней атрыбут, які быў размешчаны на контейнере — напрыклад, цэль, паперкі з падтверджэнням чы аблака заголовкаў запиту — пасляўсідава прызначаліся кожнаму наследніку, які работаў за дапамогою htmx. У версіі 4 неабходна явна заявіць пра такое наследаванне, дадаўшы до назвы атрыбута наявнага элемента суфікс :inherited. Наследнік, які хочаць расширыць успадкованую значэнне чы селектар, а не заменіць яго, можа выкарыстоўваць суфікс :append.

Этот суфікс не ўжо декоратыўны элемент. Ён паведамляе тых, хто чытае шаблон, пра тое, што атрыбут наявнага элемента ўмышлена є часткай поведання яго наследнікаў. Гэта ўсё больш прыбліжае htmx да локальнасці поведання: чым ближэй заява знаходзіцца да элемента, які ёй керуе, тым менш непазрозумелага контекста трэба реканструюваць чытальніку. Спяльнае поведанне заўсёды можліва; яго дыямэт проста аанунцуецца там, дзе яно заявляецца.

Чаму гэта ўскладненая частка апгрэйда

Гэя змена таксама стварае моцна небяспечны спосаб абыекцыі. Падазроўваючы, што загаловак CSRF завжды быў заданы ў кампоненте-обгортку. Пасля апгрэйда старонік прадаёцца так сама, як і раней, але запыткі ад падэлементаў больш не несу гэтага загаловка і пачынаюць быць адхіленыя серверам. Нічога не выглядае некоректна, пакуль хтось не адправіць форму.

Htmx прысвячае афіцыйны калькюлятор апгрэйда, який скануе шаблоны і скрыпты на непрамае успадкуванне, застарэлыя назвы запускаў, адключаныя атрыбуты і застарэлыя API. Іспользуйце яго атлас як пачатковы список, а не гаранцію, а потым перагляньце рэальныя шляхі запыткаў, усабліваючы ўвагу на тыя, якія захаваны загаловкамі, падтверджэннямі чы раўнымі целямі.

Адпаведзі на абыекцыі стаюць заменнымі фрагментамі

У Htmx 2 адаптаванні ў выпадку адпаведных кодаў стану 4xx чы 5xx не выканаліся за значэнням. Htmx 4 зменшыў гэта правіла: ён адаптавае кожную HTTP-адпаведзь, за выключэнням 204 No Content і 304 Not Modified.

Калі адпаведныя групы кодаў стану павінны падаць у разныя месца чы выкорыстоўваць розныя правіла адаптавання, новы атрыбут hx-status дазволяе настаўіць гэта для кожнай класы стану, напрыклад, выклікаючы адправку памылак верыфікацыі ў рэгіон для адразування паведамленняў, а памылкі сервера — у банер на рэвюжнай сторонцы.

Рэальныя наследкіі падаюць на сервер. Кожна адпаведзь на адказку працоўкі павінна стаць валідным фрагментам для таго элемента, які яе прымае. Полны лог стэка або чысты тэла адказкі ў формате JSON буду вставленыя ў DOM такімі, якія яны є. Коды статусу застаюцца з своім значэнням HTTP для кешаў, логаў і кліентоў, тады калі тэла HTML несу інфармацыю пра адзіначэнне тэксту і, ў ідеале, наступныя дзеянні, якія можа выконаць корыстнік, напрыклад, пасправядліванне формы.

Аднавленне кальколькі рэгіонаў з адной адказкі

Адна операцыя з боку сервера часта вымагае змены не толькі элемента, які нажаў корыстнік. Апублікацыя паведамлення можа дадаць яго да часовай шкалы, падняць лічыльнік непрачытаных паведамленняў і заменіць элемент кнігівадзора. Htmx давно прыменяе метод замены элементаў паштою: элементы ў адказцы, пазначаныя як паштоўныя, заменяюць адпаведныя элементы ў іншых частках докумэнта.

Htmx 4 дадае болей ясны ўстатку — элемент <hx-partial>. Кожны такі элемент прызначае сабе выконвальную мету і стратэгію замены, тады адпаведны рэспонс выглядае як спіс чыста адзначаных актуалізацый.

Таксонамія элементаў таксама визначаная. Спачатку заменяецца галоўны рэспонс; пасля — частковы элементы і элементы, якія не ўключаны ў галоўны рэспонс, у порядку іх выкладкі ў дакумэнце. Гэта спрыяе таму, што кожная актуалізацыя будзе значымая сама па сабе, а не залежнаць ад пасляэфектаў паканальных змян у тым жа рэспонсе.

Гэта адпавядае лёгкай оркестрацыі рэспонсаў. Сервер можа описаць кожны візуабельны наследак адной операцыі ў аднам рэспонсе, не вяртаючы JSON і не заставляючы код кліента распадзеляць поля між разнымі компанентамі.

Змены, якія падтрымліваюць стан браузера

Замена innerHTML ўсё ж зрозумела, але яна пазбавляе браузер его внутрашняго стану. Поле для тэксту можа апынуцца без выбранага фрагмента, увага можа перайсці на іншы элемент, відэа можа пачацца зноў, а спецыяльны элемент можа быць знішчаны і створаны занова, нават калі большая частка яго маркапу застаецца незменным.

Htmx 4 прыносіць режымы innerMorph і outerMorph, пабудаваныя на удосконаванай версіі алгорытму Idiomorph. У працэзе замены не пазбавляюцца цяльныя паддрэвы, а алгорытм пораўнюе старыя і новыя вузлы і застаўляе самы мінімальны набор змян. Вузлы, якія падходзяць, застаюцца тымі ж, і ўсё, што залежыць ад яных — увага, выбраны фрагмент, пазіцыя відпаведнага кантэнту і внутрашні стан — таксама застаецца незменным.

Морфінг не завжды ўсё ж таки лепшы варыянт. Для простага фрагмента масовая замена часта є бяспечней і лёгча для дыбагавання. Морфінг стае корыстным, калі цэль выканання містіць жывыя элементы формы, спецыяльныя елементы, медыя-контэнт або віджеты трэціх сторон, ідентыфікатары якіх мае значэнне. Htmx таксама апранае селектары для прыхілу цэлых вузлаў або толькі ўсіх іх дзецяў пад час морфу, што ёсць практычны спосаб захаваць становыя элементы, такія як вбудоўаная карта або редактар багатага тэксту.

Загальны прынцып варта памярцац нават за межамі htmx: сервер выбірае, якім павінен быць HTML, а браузер захоўвае фізычныя об’екты DOM, якія павінны перазстаць пасля пераходу.

Стрімаванне існуе ў расширэннях, а не ў ядрзе

Fetch дае htmx набагато лепшую базу для стрімавых адказаў, але сама сэрца праграмы не нав’язвае аднаго протаколу стрімавання для всіх. У замен htmx 4 прыносіць околачныя, спецыялізаваныя расшырэння для Server-Sent Events, WebSockets і адказаў у формате multipart.

Rasшырэнне для multipart, hx-multipart, падтрымляе форматы multipart/mixed і multipart/parallel. Кожная частка можа мець HTML разам з сабойшымі заголовкамі HX-*. Гэта дазволяе серверу адразу выслаць тымчасовы адказ, а потым стрімаваць дадатковыя часткі праз адпрацоўку повольных заданняї, пры чым кожная з іх обрабоцваліцца окрема, без неабходнасці стварання власнага канектора паведамленняў на стороне кліента.

Выбар між гэтымі расшырэннямі залежыць ад формату потоку дадзенняў:

• SSE падходзіць для архіваваных, однакоўных апдэйтаў, якія надаюцца з сервера.
• WebSockets падходзіць для справжняя двухканальная пераказка паведамленняў.

Multipart падходзіць для адной HTTP-операцыі, якая з часам выдае калькіляванні.

Усе тры варыянты выкарыстоўваюцца ў той самы механізм адмены, таму рэшта вашага маркапа не залежыць ад таго, який спосаб прынёс фрагмент.

Простейшая модэль расширэння

Зберагчы стрімінг парадульна ад ядро, ўжо тады ядро застаецца маленькім, а граніцы расширэння стаюць болей функцыйнаснымі. Расширэнняя htmx 4 рэгіструюць ся безпосередна і можу прыўязвацца да фазы запита, адпаведзі і адмены. Яны актываюцца проста праз уключэнне ўсілявання; атрыбут hx-ext больш не існуе. Якщо вы хочаце чыстую граніцу, налаштаванні дазваляюць абмежыць, якія імены расширэння дазволены на сайце.

HCON: кампактная пазначэння для опцыяў атрыбутаў

Калі атрыбуты сталаўцяліся з большай колькасцю опцый, htmx патрабаваў сінтаксіса, які бы не быў настолькі «шумным», калі праіснаваў у значэнні атрыбута ў формате JSON. Адпаведзью стала HCON — пазначэнне канфігурацыйных об’ектаў htmx. Ён падтрымлівае пары ключ-значэнне, роздзеленыя прасланкамі, флагі як логічныя значэння, цыфры, строкі з кавычкамі і ключы з крапкамі для вярстывання.

JSON таксама залічваецца, што ўдобна, калі сервер вялікі час ужо генеруе канфігурацыю. HCON спрямованы на рукапісны маркап: дастаточна стислы, каб можна было яго швытаць, але настолькі структураваны, што htmx не патрабуе окалічнага парсера для кожнага атрыбута. Той самы пазначэння выкарыстоўваецца для тригераў, модыфікатораў замены, канфігурацыі запитоў, заголовкаў, значэнняў і заголовка адпаведзі HX-Location; таму яго вучыцца раз прыносіць практычныя наследкі ў всіх сферах.

hx-live для стану кліента, які застаецца

Гіпермедыя не усувае ўсю локальную інтэрактыўнасць. Перш чым будзе адправлена якое-небудзь запитанне, апыяецца спадны список. Калькулятор симваў апошні час зменяецца праз кожны натыканне на клавішу. Карточкі, элементы для адкрыць і тымчасовыя выбіранні зазвычай ёсць адпаведальнасцю браузера.

Новая расширэння hx-live падходзіць да такіх ситуацыяў за дапамой невялікага шару скрыптавання, адорыянтаванага на DOM. Яно праспектуе дапамогу для запытанняў, селектары для пошуку суседніх элементаў, інструменты DOM, дапамогу для асінхронных задач, доступ да атрыбутаў і значэнняў дадзеных з урахоўваннем іх типу, а таксама рэакtyвныя прыўязкі, такія як :text, :class і :hidden.

Яго фундаментальная правіла ў філасофскай паўназначэнні: DOM ёсць хранальнік стану. Рэакtyвны выраз чытае стан з суседніх элементаў і апошні час адкладзе прыказку суседніх элементаў. Усё тое, што є стойкім, застаецца у власнасці сервера і падае на сторанку ў формате HTML, як і ранейш.

Уважайце hx-live як клапан адпуску для дробных задач карточнага інтэрфейсу, а не як спосаб развіць другое прыемленьне ўнутрэй браузера. Ожывайце яго тады, калі інакш быяў бы неабходны пісьмо павтаральных шаблонав для адгуку на змяны інтэрфейсу, якія є тымчасовымі. Калі стан павінен застацца пасля переходу, быть выменным між пользователямі, контролюваць правыя адносы чы стаць часткай транзакцый, яго месца — на серверы.

Навігацыя па історыі: перзапрашанне замест вясвачэння кадроў

Htmx 2 храніў кадры історыі ў localStorage. Вясвачэнне такога кадра магло вернуць змяны DOM, якія былі адбыты незв’язанымі скрыптамі, але не стан JavaScript-рантайма, які іх стварыў. Старонка выглядала інтерактываю, але на самай працы была фасілізаваным DOM: віджэты былі атрыбутаваны, пры тым чым за іхнімі нічога не было налаштавана.

Htmx 4 усунэць той стандартны кеш. Пад час перавыходу назад і прагулу вперадзе ён зноў запрашоўвае стораніцу і размешчае яе рэзультат у <body> або ў спецыязаваны элемент історыі. Правильныя загаловкі кэшавання HTTP можа зробіць такі запрос практычна безкоштовным, пры тым як да скрыптаў будзе задаўцца чысты дакумент для ініцыялізацыі.

Програмы, якім сапраўды патрэбны локальныя копіі, могу завантажыць расширэнне hx-history-cache, якое выкарыстоўвае sessionStorage і чытра адзначае такую працэс. Гэты патэрн павтараецца ў усіх версіях: стандартнае рашэння — цэ это свежая версія, а локальная реканструкцыя — это дапаможны функцыянал, які можна выключыць.

Спрыяйце міграцыі як аудыту працэса

Найбезпечнейшы ўзраджэнне — это не слепая замена пакетаў, а кароткая пераглядка кожнага месца, дзе поведэнне перакрывае межы маркапаў. Большасць стораніцаў залишае своі маркапы незменнымі; робота сфокусаваная на неявнай спадчыне, абэрткі супарадзіння, обработцы адпаведзей, історыі та расширэннях.

Спачатку задаць точную версію htmx 4, а потым запрацаваць офіцыйны чыннік перагляду ўзраджэння, описаны ў дакументацыі перайшоўства. Раскідваць вынікі чынніка так, каб утрымацца ад суперасункі между перэименаванымі атрыбутамі:

1. Перэіменаваць стары атрыбут hx-disable, які означаў „ігнораваць гэты паддрэв“, у hx-ignore.
2. Толькі пасля чаго перэіменаваць hx-disabled-elt у новы hx-disable. Якшо выконваць гэтыя два крокі у зворачнай парады, атрыбуты можна будзе випадкова ператворыць аднам у другі.

Дадзіце :inherited там, дзе абяцейкавы элемент павінен і даляй вплываць на своіх наследнікаў, уважна старайцеся да загалоўных элементаў, падтверджэнняў, цэлей і элементаў includes.

Адкорэктавайце назвы слухачаў запускаючыхся змаганняў і заменіце выдаленыя дапаможныя элементы на вбудованыя API прыгледача.

Прабавайце адпаведзі 4xx і 5xx, адколькі яны тепер за замовчаннем мяняюцца між сабою, і пераканаўцеся, што кожна з іх вяртае значны фрагмент.

Прабавайце кожны элемент hx-delete, які больш не адправляе даныя знаходзячагся ў яго формулара, якщо толькі вы не прагаворыце пра цэе за дапамогою hx-include.

Прабавайце навігацыю наперад і назад, аранжаванне паказвання параграфаў, таймауты, чергі запускаючыхся змаганняў і кожную дадатковую функцыю, яку вы вжываеце, памятаючы, што hx-ext больш не існуе.

Калі htmx 4 — правы інструмент

Змена заголовка — це Fetch, але абсалютным прынцыпам являецца чыстая яснасць. Атрыбут доходзіць да наследнікаў толькі тады, калі яго прызначэнне гэта працюе. HTML апытку з невялікім успехам па значэнню дазволу паказваецца корыстніку, а вы налаштовваете выключэнняя варыянты. У адпаведзінах, якія затрагваюць калькі рэгіонаў, чытна паказана, куды кожны элемент прыходзіць і як ён заменяецца. Навігацыя назад і вперад завантажвае чыстую стороніцу, як толькі вы спецыяльна не актываўце кэш з фіксаваным іменем. Расширэнняя падключаюцца чераз адны спакульнаі жытнёвы цикл, а стандартныя методы DOM выконваюць сваю ролю там, дзе раней htmx выкарыстоўваў сваія дапаможнікі.

Усе гэта спакойвае скрытую дзейнасць, не перадаючы стан аплікацыі ў клаўентскую рамку. Гэта тае падзейсце, да якога прагне htmx: насычаная інтэрацыя, автарытет сервера і HTML, які ўсё ж такі описвае, што можа робіць стороніца.

Гэта не зробіць кожны інтэрфейс простым. Графічны редактор, рабочая суперфіса, яка працюе без падзейчання на сеть, або прыкладнэц, створаны на адміністрацыі глыбокаў спавяльнавальнага локальнага модэлю, можа правядзіць наявнасць болей сложанай архітэктуры кліента. Аднак большасць бізнес-прыкладнэцаў складаецца з навігацыі, форм, табелей, пераканання данных і рабочых прайсэптав, якія вже ўсё ж такі належаць серверу. Для такіх прыкладнэцаў часта простае вярнуць готовую рэпрэзентацыю, чым падтрымліваць сінхронізацыю двух машын стану.

Ключовыя выводы

• Модэль htmx застаецца незменным: элементы — гіпермедыйныя кантроллеры, адказы — HTML, а стан належыць серверу.
• Непрыямая спадчына атрыбутаў зникла; відсутнеча суфікса :inherited — гэта найбольш верагодны прычыні таямніх бягункоў, особліва для заголовкаў CSRF.
• Адказы на абяканні тепер за замовчаннем меняюцца, таму кожны тэла адказу 4xx і 5xx павінен быць валідным фрагментам для свайго цэльвыка.

<hx-partial> і механізмы замены элемента дазволяюць ясна і прагнозавальна адрабатаваць кантэкст у колька регіонаў і зберагаць стан элемента.

Стрімаванне, інтэрактыўнасць на боку кліента і кэшаванне історыі перашлі ў дапаможныя расширэння, якія можна ўвёсці за пажыраннем, таму сама сэрца функцыяналу застаецца маленькім.

Запусціце перакалькувальнік апдэйтаў, а пасля працаваце з рэальнымі шляхамі запытоў; перакалькувальнік выявляе можлівыя варыянты, а толькі тэставанне паказвае, чы прылада яшчэ працюе.

Спаднія статыкі

• Дзе напісана функцыя вядомае, што яна бачыць: лексычны дыялект JavaScript — З’ясавайце, як JavaScript разв’язвае імёна зменных через лексычныя среды, чаму месца вызыва ніколі не мае значэння для пошуку, і як гэта паўтарыцца ў обробніках React.
• JavaScript Currying Demystified: Closures, Partial Application, Reuse — Дазвольце дазнацься, як куррыяванне ператварае функцыі JavaScript з колькіма аргументамі на павторныя ланцюгі з адним аргументам, якое ў іх разлічнае з частым застосаваннем і калі можна яго працягнуць.
• Upgrading a React Codebase to TypeScript 6.0: What Breaks First — Як строгейшыя стандартныя настройкі, паследоўванне методаў, імпорты падшляхоў #/ і типы Temporal указваюць на адрасах TypeScript 6.0 на вплыв на прыкладніцу React, а таксама спіс пунктав для безпечнага апдэйта.