htmx 2.0 در ژوئن ۲۰۲۴ منتشر شد و تغییرهای آن را باید در قرارداد درخواست، تنظیم‌ها و extensionها خواند. این نسخه وابستگی فرضی به hyperscript را حذف نکرد؛ این دو پروژه مستقل‌اند. آمار رشد دانلود یا ستاره مخزن که در نسخه قبلی مطلب آمده بود هم بدون منبع و بازه روشن، توضیح مفیدی برای مهاجرت نمی‌داد. اعلام رسمی htmx 2 مبنای تاریخ و دامنه این راهنماست.
این مطلب برای پروژه‌ای نوشته شده که از خانواده 1 به خانواده 2 می‌رود یا هنوز نمونه‌های قدیمی آن را نگه می‌دارد. وضعیت نسخه‌های بعدی را از سایت رسمی بخوانید و رفتار آن‌ها را با نسخه 2 یکی نگیرید. htmx برای فرستادن درخواست و قرار دادن پاسخ HTML در صفحه استفاده می‌شود؛ تعویض شماره نسخه، قرارداد endpoint، اعتبارسنجی و مجوز برنامه را به‌طور خودکار اصلاح نمی‌کند.
ابتدا مصرف واقعی را پیدا کنید
قبل از تغییر، محل بارگذاری کتابخانه و نسخه واقعی را ثبت کنید. پروژه ممکن است یک script در Layout، یک بسته npm و یک کپی محلی قدیمی داشته باشد. اگر دو نسخه هم‌زمان در صفحه حاضرند، نتیجه با نمونه ساده مستندات فرق خواهد داشت. حذف سردرگمی نسخه، پیش از بررسی رفتار attributeها لازم است. فایل minified را از روی نام کوتاه آن تشخیص ندهید؛ منشأ و نسخه را ثبت کنید.
فهرست hx-get، hx-post و extensionهای فعال را تهیه کنید. برای هر مسیر، نوع پاسخ مورد انتظار را بنویسید: صفحه کامل، fragment، redirect یا پاسخ بدون بدنه. خطای مهاجرت اغلب در یک قرارداد خاص ظاهر می‌شود، نه تمام صفحه. اگر تیم بداند کدام قسمت به کدام endpoint وابسته است، اصلاح محدودتر و بازگشت قابل فهم‌تر خواهد بود.
کد اختصاصی روی eventهای htmx را نیز پیدا کنید. ممکن است تغییر نام یا شکل attribute روی بخشی اثر بگذارد که در ظاهر HTML اصلی دیده نمی‌شود. یک listener عمومی در Layout می‌تواند رفتار چندین صفحه را عوض کند. هنگام بازبینی، هم markup و هم کد event handler را کنار هم بخوانید تا وابستگی پنهان باقی نماند.
تغییرهای نسخه 2 را با راهنمای مهاجرت بخوانید
راهنمای رسمی مهاجرت از 1 به 2 تغییرهای ناسازگار و تنظیم‌های پیش‌فرض را ثبت می‌کند. از جمله پشتیبانی IE کنار گذاشته شده و extensionها مسیر جدا دارند. این تغییرها به همه پروژه‌ها اثر یکسانی ندارند. پروژه‌ای که به مرورگر قدیمی سازمانی متکی است، پیش از ارتقا باید نیاز مخاطب و گزینه قابل ادامه را مشخص کند.
بعضی تنظیم‌های درخواست نیز در نسخه 2 فرق می‌کنند. به جای اینکه هر رفتار تازه را bug بنامید، پیش‌فرض همان نسخه را بررسی کنید. اگر endpoint شما پارامتر را فقط در شکل خاصی می‌خواند، تفاوت body و URL می‌تواند مسئله ایجاد کند. در قرارداد API بنویسید کدام method، کدام پارامتر و کدام نوع پاسخ معتبر است؛ این سند باید مستقل از انتخاب کتابخانه رابط قابل فهم باشد.
تغییر نسخه را با تعویض هم‌زمان قالب‌ها و endpointها جمع نکنید. اگر نتیجه یک عملیات متفاوت شد، تیم باید بتواند اثر تغییر کتابخانه را از اثر تغییر منطق جدا کند. ابتدا یک مسیر محدود را با قرارداد روشن نگه دارید. اگر بازگشت لازم شد، فایل‌ها و تنظیم‌های همان مسیر باید با نسخه قبلی هماهنگ باشند؛ فقط برگرداندن script همیشه کافی نیست.
Extensionها وابستگی مستقل دارند
در خانواده 2، extensionها جدا از هسته مدیریت می‌شوند. فهرست رسمی extensionها نقطه شروع یافتن نسخه و راهنمای هر کدام است. وجود attribute hx-ext بدون بارگذاری کد مربوط، قابلیت را فراهم نمی‌کند. در نصب npm یا فایل محلی، مسیر script و ترتیب بارگذاری باید صریح باشد. نمونه‌ای که extension معرفی می‌کند ولی فایلش را ندارد کامل نیست.
WebSocket و Server-Sent Events دو الگوی ارتباط متفاوت‌اند. راهنمای WebSocket extension و راهنمای SSE extension قرارداد هر کدام را توضیح می‌دهند. انتخاب را از نیاز جریان داده شروع کنید: آیا داده فقط از سرور می‌آید یا رفت‌وبرگشت پیوسته لازم است؟ نام جدید extension دلیل کافی برای افزودن اتصال دائمی به یک فرم ساده نیست.
اتصال دائمی به مدیریت قطع و وصل نیاز دارد. اگر صفحه پیام تازه دریافت می‌کند، باید معلوم باشد پس از reconnect چه داده‌ای از دست رفته و چگونه وضعیت معتبر برمی‌گردد. نمایش یک اتصال باز در مرورگر، تضمین دریافت تمام رخدادها نیست. شناسه، ترتیب و تکرار پیام به طراحی سرویس هم مربوط‌اند و کتابخانه رابط آن‌ها را به جای شما تعریف نمی‌کند.
Event Handler را بدون حدس منتقل کنید
نسخه 2 برای استفاده از hx-on شکل‌های attribute مربوط به event را مطرح می‌کند و attribute قدیمی نباید بی‌بررسی حمل شود. مرجع hx-on syntax را توضیح می‌دهد. هنگام اصلاح، نام event و محل اجرای handler را دقیق نگه دارید. بزرگ‌نویسی یا شکل نام در HTML می‌تواند با انتظار JavaScript تفاوت داشته باشد.
اگر handler فقط وضعیت ظاهری را عوض می‌کند، بررسی کنید آیا attribute یا CSS ساده‌تر همان کار را انجام می‌دهد. اگر منطق مهم برنامه را دارد، آن را در یک رشته کوتاه و دشوارخوان در markup پنهان نکنید. هدف htmx حذف تمام JavaScript نیست. کد اختصاصی باید جایی قرار گیرد که مسئولیتش روشن و با lifetime عنصر هماهنگ باشد.
وقتی fragment جایگزین می‌شود، listenerهایی که دستی به عنصر قدیمی وصل شده‌اند ممکن است دیگر به عنصر تازه تعلق نداشته باشند. روش اتصال باید با این چرخه هماهنگ باشد. ثبت handler تازه بدون حذف قبلی نیز می‌تواند یک عمل را چند بار اجرا کند. پیش از افزودن event سفارشی، قرارداد عنصر تازه و عنصر حذف‌شده را بنویسید.
Fragment، status و cache را هماهنگ کنید
htmx معمولاً پاسخ HTML را در target مشخص قرار می‌دهد. هدف و نوع swap باید با پاسخ endpoint هماهنگ باشند. اگر innerHTML به کار می‌برید، ظرف باقی می‌ماند؛ در outerHTML ظرف هم جایگزین می‌شود. هیچ مهاجرت نسخه‌ای جای این تصمیم ساختاری را نمی‌گیرد. نام IDهای لازم درخواست بعدی باید در خروجی تازه حفظ شود.
پاسخ ناموفق هم به سیاست نمایش نیاز دارد. انتظار اینکه هر HTML برگشتی با هر status خودکار نمایش داده شود، قرارداد دقیقی نیست. قواعد response handling همان نسخه و رفتار سفارشی پروژه را بخوانید. یک endpoint اعتبارسنجی باید status و بدنه مشخص داشته باشد و UI بداند خطا در کدام قسمت نمایش داده می‌شود. پیام کلی «درخواست انجام نشد» همه علت‌ها را پوشش نمی‌دهد.
اگر یک URL در درخواست عادی صفحه کامل و در درخواست htmx fragment می‌دهد، cache باید این تفاوت را بشناسد. Header مربوط به HX-Request راه تشخیص قالب است و مجوز امنیتی نیست. سرور باید دسترسی را مستقل از آن بررسی کند. نتیجه اشتباه cache ممکن است fragment را به بازدید مستقیم یا سند کامل را به ظرف کوچک بدهد؛ این خطا به قرارداد پاسخ مربوط است.
نمونه پایه را قبل از توسعه نگه دارید
برای شروع عملی، مقاله htmx و نمونه کامل جست‌وجوی server-driven یک سرور Node.js و فرم GET با HTML و CSS کامل دارد. آن نمونه از بسته محلی خانواده 2 استفاده می‌کند و وابستگی پنهانی به CDN ندارد. قبل از اضافه کردن extension، همان چرخه درخواست و پاسخ را برای فرم مورد نظر خود روشن کنید.
در پروژه‌ای با backend موجود، endpoint آموزشی را با مسیر واقعی خود جایگزین کنید و قرارداد اعتبارسنجی را حفظ کنید. فرم بدون JavaScript باید راه ادامه تعریف‌شده داشته باشد، اگر هدف پروژه Progressive Enhancement است. به‌روزرسانی جزئی نباید تنها راه دسترسی به یک عمل ضروری باشد مگر محصول عمداً چنین نیاز و محدودیتی را پذیرفته باشد.
برای عملیات تغییردهنده، token و روش CSRF framework را مطابق قرارداد نگه دارید. htmx مجوز یا اعتبار ورودی را صادر نمی‌کند. داده‌ای که در پاسخ HTML قرار می‌گیرد هم باید با قواعد escape یا sanitize مناسب آماده شود. بخش امنیت مستندات htmx به این مسئولیت‌ها مربوط است. تغییر نسخه نباید کنترل‌های backend را حذف کند.
مهاجرت را با رفتار کاربر تحویل دهید
در فهرست کار، نتیجه قابل مشاهده بنویسید: فرم پس از موفقیت چه نشان می‌دهد، خطا کجا ظاهر می‌شود و Focus چه می‌شود. یک رسید تکنیکی «script عوض شد» برای ارزیابی محصول کافی نیست. اگر عنصر دارای Focus حذف می‌شود، ادامه کار کاربر را تعیین کنید. مقاله دسترسی‌پذیری از روز اول به این مرحله مربوط است.
راهنمای راه‌اندازی پروژه باید نسخه core، extensionهای لازم و علت تنظیم‌های غیرپیش‌فرض را ثبت کند. تنظیمی که برای رفتار قدیمی اضافه شده اگر بدون توضیح بماند، در ارتقای بعدی دوباره ابهام ایجاد می‌کند. آن را به مسئله مشخص و محدودیت نسخه وصل کنید. با اصلاح یک پیش‌فرض، باید معلوم باشد کدام انتظار محصول حفظ شده است.
قدم بعدی، انتخاب یک جریان کوچک و تهیه جدول درخواست و پاسخ آن است. سپس موارد راهنمای مهاجرت را روی همان جریان تطبیق دهید و extensionهای واقعاً مصرف‌شده را جدا مدیریت کنید. خبر انتشار htmx 2 آغاز این بررسی است؛ نتیجه مهاجرت باید رفتار قابل توضیح و فایل‌های وابسته روشن باشد، نه یک وعده کلی درباره «ساده‌ترین ابزار» یا رشد دانلود.
هنوز دیدگاهی ثبت نشده
اولین نفری باشید که نظر می‌دهد!