شروع با HTMX: راهنمای مبتدیان

Summarize this content to 400 words in Persian Lang
HTMX یک کتابخانه جاوا اسکریپت است که به شما امکان می دهد قابلیت های AJAX را مستقیماً با استفاده از ویژگی های HTML به HTML اضافه کنید. کتابخانه بر دو ایده اساسی استوار است:

یک مثال اساسی ممکن است این باشد:

hx-get=”/data” hx-trigger=”click” hx-swap=”outerHTML”>
Get

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

این دکمه:

اما چرا باید HTMX را در نظر گرفت در حالی که چندین فریمورک فرانت اند امروزه در دسترس هستند؟ در اینجا چند نکته کلیدی وجود دارد که باید مورد توجه قرار گیرد:

سادگی: HTMX به توسعه دهندگان اجازه می دهد تا برنامه های وب تعاملی را با استفاده از ویژگی های ساده HTML به جای کد جاوا اسکریپت بسازند.
کارایی: از آنجایی که HTMX عمدتاً به HTML (و حداقل جاوا اسکریپت) متکی است، صفحات اغلب سریع‌تر بارگیری می‌شوند و از حافظه کمتری استفاده می‌کنند.
منحنی یادگیری: از آنجایی که HTMX مستقیماً با HTML کار می کند، منحنی یادگیری کمتری برای توسعه دهندگانی دارد که با HTML/CSS راحت تر هستند.
رندر سمت سرور: HTMX با هر فناوری سمت سرور کار می کند. این به توسعه دهندگان اجازه می دهد تا به زبان های باطن مربوطه خود کار کنند.

سلام دنیا

هر فناوری جدید همیشه با مثال کلاسیک “سلام جهان” شروع می شود. دستورات زیر را برای تنظیم راه حل اجرا کنید:

dotnet new web -o TodoApi
dotnet new sln -n Htmx
dotnet sln add –in-root TodoApi

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

در TodoApi پروژه، و اضافه کنید HtmlResult.cs فایل با محتوای زیر:

using System.Net.Mime;
using System.Text;

namespace TodoApi;

public class HtmlResult : IResult
{
private readonly string _html;

public HtmlResult(string html)
{
_html = html;
}

public Task ExecuteAsync(HttpContext httpContext)
{
httpContext.Response.ContentType = MediaTypeNames.Text.Html;
httpContext.Response.ContentLength = Encoding.UTF8.GetByteCount(_html);
return httpContext.Response.WriteAsync(_html);
}
}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

این کلاس برای برگرداندن HTML از نقاط انتهایی API حداقل ما استفاده خواهد شد. برو به Program.cs فایل و به روز رسانی محتوا به شرح زیر است:

using Microsoft.AspNetCore.Html;
using TodoApi;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet(“/hello-world”, () => new HtmlResult(@”

Get time

“));
app.MapPost(“/hello-world”, () => new HtmlResult($@”Hello World {DateTimeOffset.UtcNow}”));
app.Run();

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

دو نقطه پایانی در API ما وجود دارد. اولی سند HTML اولیه را برمی گرداند که شامل ارجاع به کتابخانه HTMX از طریق CDN است. در داخل بدنه، دکمه‌ای با ویژگی‌های HTMX وجود دارد (که بعدا توضیح داده خواهد شد) که به مرورگر دستور می‌دهد تا درخواست HTTP POST را انجام دهد. /hello-world هنگامی که دکمه کلیک می شود و سپس دکمه را با پاسخ جایگزین می کند. نقطه پایانی دوم فقط یک تگ div حاوی پیام را برمی گرداند. برای مشاهده این در عمل، برنامه را اجرا کنید و به http://localhost:5179/hello-world بروید.

ویژگی های

ویژگی های اولیه مورد استفاده در HTMX برای درخواست های AJAX طراحی شده اند:

hx-get: درخواست GET را به URL داده شده صادر می کند.
hx-post: درخواست POST را به URL داده شده صادر می کند.
hx-put: درخواست PUT را به URL داده شده صادر می کند.
hx-patch: یک درخواست PATCH به URL داده شده صادر می کند.
hx-delete: درخواست DELETE را به URL داده شده صادر می کند.

ویژگی های زیر بیشتر مورد استفاده قرار می گیرند. برای اطلاعات بیشتر، لطفا به وب سایت رسمی اینجا مراجعه کنید.

hx-trigger

ویژگی hx-trigger ما را قادر می سازد تا تعریف کنیم که چه چیزی درخواست AJAX را آغاز می کند. به‌طور پیش‌فرض، وقتی از محرک‌های زیر استفاده می‌شود، نیازی به تعیین ویژگی نیست:

input، textarea & select بر روی ایجاد می شوند change رویداد.
form بر روی راه اندازی می شود submit رویداد.
همه چیز دیگر توسط click رویداد.

مقدار ماشه می تواند یکی از موارد زیر باشد:

hx-target

را hx-target ویژگی ما را قادر می سازد به جای عنصری که درخواست AJAX را آغاز می کند، عنصر دیگری را برای تعویض هدف قرار دهیم. مقدار این ویژگی می تواند باشد:

یک انتخابگر پرس و جو CSS از عنصر مورد نظر.
this نشان می دهد که عنصر با hx-target ویژگی خود هدف است.
closest نزدیکترین عنصر جد یا خودش را پیدا می کند که با انتخابگر CSS داده شده مطابقت دارد.
find اولین عنصر فرزند اول را پیدا می کند که با انتخابگر CSS داده شده مطابقت دارد.
next DOM را برای اولین عنصری که با انتخابگر CSS داده شده مطابقت دارد اسکن می کند.
previous DOM را برای اولین عنصری که با انتخابگر CSS داده شده مطابقت دارد به عقب اسکن می کند.

hx-swap

را hx-swap ویژگی به شما این امکان را می دهد که نحوه تعویض پاسخ نسبت به هدف درخواست AJAX را مشخص کنید. مقادیر ممکن این ویژگی عبارتند از:

innerHTML: محتوا را داخل عنصر هدف قرار می دهد. گزینه پیش فرض
outerHTML: کل عنصر هدف را با پاسخ جایگزین کنید.
beforebegin: محتوا را قبل از هدف در عنصر والد درج کنید.
afterbegin: پاسخ را قبل از فرزند اول عنصر هدف درج کنید.
beforeend: پاسخ را بعد از آخرین فرزند عنصر هدف درج کنید.
afterend: پاسخ را بعد از هدف در عنصر والد درج کنید.
delete: عنصر هدف را بدون توجه به پاسخ حذف می کند.
none: محتوایی را از پاسخ اضافه نمی کند.

همه برنامه

بیایید یک اپلیکیشن بسازیم تا همه این مفاهیم را در عمل ببینیم. برای ساخت HTML در دات نت می توانیم از HtmlContentBuilder کلاس به جای استفاده از یک رشته ساده. این چندین مزیت دارد:

قابل پارامترسازی: از آنجا که HtmlContentBuilder از فراخوانی های متد استفاده می کند، می توانید پارامترهایی را به آن متدها ارسال کنید تا به صورت پویا HTML بسازید.
پشتیبانی از رمزگذاری: HtmlContentBuilder HTML به طور خودکار هر رشته رمزگذاری نشده ای را که اضافه می کنید رمزگذاری می کند.
ترکیب پذیر: می توانیم چندتایی بنویسیم HtmlContentBuilder نمونه هایی برای ساخت HTML پیچیده تر.
نگهداری آسان تر: با پیچیده‌تر شدن HTML، نگهداری HTML به‌عنوان یک رشته ممکن است دشوار شود. HtmlContentBuilder به شما اجازه می دهد تا با استفاده از فراخوانی متد، HTML را به صورت تدریجی ایجاد کنید.

بیایید یک جدید ایجاد کنیم IResult اجرا بر اساس IHtmlContent رابط:

using Microsoft.AspNetCore.Html;
using System.Net.Mime;
using System.Text.Encodings.Web;
using System.Text;
namespace TodoApi;
public class HtmlContentResult : IResult
{
private readonly IHtmlContent _htmlContent;

public HtmlContentResult(IHtmlContent htmlContent)
{
_htmlContent = htmlContent;
}

public Task ExecuteAsync(HttpContext httpContext)
{
httpContext.Response.ContentType = MediaTypeNames.Text.Html;
using (var writer = new StringWriter())
{
_htmlContent.WriteTo(writer, HtmlEncoder.Default);
var html = writer.ToString();
httpContext.Response.ContentLength = Encoding.UTF8.GetByteCount(html);
return httpContext.Response.WriteAsync(html);
}
}
}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

ایجاد یک TodoItem.cs فایل برای ذخیره مدل ما:

namespace TodoApi;
public class TodoItem
{
public Guid Id { get; set; }
public bool IsCompleted { get; set; }
public string? Name { get; set; }
};

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

ایجاد یک Components.cs کلاسی که شامل تمام سازهای HTML ما باشد:

using Microsoft.AspNetCore.Html;
namespace TodoApi;
public static class Components
{
public static IHtmlContent Document(IHtmlContentContainer children)
{
var builder = new HtmlContentBuilder();
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(children);
builder.AppendHtml(“”);
return builder;
}

public static IHtmlContent TodoList(IEnumerableTodoItem> todoItems)
{
var builder = new HtmlContentBuilder();
builder.AppendHtml(“”);
foreach (var todoItem in todoItems)
{
builder.AppendHtml(TodoItem(todoItem));
}
builder.AppendHtml(“”);
return builder;
}

public static IHtmlContent TodoItem(TodoItem todoItem)
{
var builder = new HtmlContentBuilder();
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendFormat(“{0}”, todoItem.Name);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
return builder;
}
}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

حرکت به Program.cs فایل و کد زیر را اضافه کنید:

var db = new ListTodoItem>()
{
new TodoItem() { Id = Guid.NewGuid(), Name = “abc”, IsCompleted = true },
new TodoItem() { Id = Guid.NewGuid(), Name = “123”, IsCompleted = false },
};

app.MapGet(“https://dev.to/”, () =>
{
var builder = new HtmlContentBuilder();
builder.AppendHtml(“”);
builder.AppendHtml(“”);
return new HtmlContentResult(Components.Document(builder));
});

app.MapGet(“/todos”, () => new HtmlContentResult(Components.TodoList(db)));

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

نقطه پایانی اول سند HTML اولیه را ارائه می دهد، در حالی که دومی لیستی از موارد را برمی گرداند. در طول رویداد بارگذاری برچسب بدن (hx-trigger=”load”، HTMX یک درخواست می کند (hx-get=”/todos”) و پاسخ را در داخل عنصر (hx-swap=”innerHTML”). بیایید ویژگی ها را برای تغییر و حذف موارد اضافه کنیم. را به روز کنید TodoItem جزء به شرح زیر است:

public static IHtmlContent TodoItem(TodoItem todoItem)
{
var isCompleted = string.Empty;
if (todoItem.IsCompleted)
{
isCompleted = “checked”;
}
var builder = new HtmlContentBuilder();
builder.AppendHtml(“”);
return builder;
}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

در طول رویداد تغییر ورودی چک باکس، HTMX یک درخواست را آغاز می کند (hx-post=”/todos/{todoItem.Id}/toggle”) و جایگزین عنصر (hx-target=”closest div”) با پاسخ (hx-swap=”outerHTML”) به روز رسانی لیست. در همان خط، رویداد کلیک یک عمل مشابه را انجام می دهد. با این حال، از آنجایی که پاسخ خالی است، مورد از لیست حذف می شود. در Program.cs فایل، این دو نقطه پایانی را اضافه کنید:

app.MapPost(“/todos/{id}/toggle”, (string id) =>
{
var todo = db.First(t => t.Id.ToString() == id);
todo.IsCompleted = !todo.IsCompleted;
return new HtmlContentResult(Components.TodoItem(todo));
});

app.MapDelete(“/todos/{id}”, (string id) =>
{
var todo = db.First(t => t.Id.ToString() == id);
db.Remove(todo);
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

ویژگی نهایی افزودن موارد جدید به لیست را امکان پذیر می کند. حرکت به TodoItem.cs فایل و کد زیر را اضافه کنید:

record AddTodoItem(string? Name);

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

بعد، در Program.cs فایل، نقطه پایانی زیر را اضافه کنید:

app.MapPost(“/todos”, (AddTodoItem command) =>
{
var todo = new TodoItem {Id = Guid.NewGuid(),Name = command.Name, IsCompleted = false };
db.Add(todo);
return new HtmlContentResult(Components.TodoItem(todo));
});

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

حرکت به Components.cs فایل و اصلاح کنید Document جزء برای نصب json-enc پسوند برای رمزگذاری پارامترها در قالب JSON به جای فرمت URL:

public static IHtmlContent Document(IHtmlContentContainer children)
{
var builder = new HtmlContentBuilder();
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(“”);
builder.AppendHtml(children);
builder.AppendHtml(“”);
return builder;
}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

در همین فایل a را اضافه کنید TodoForm جزء:

در طول رویداد ارسال، HTMX یک درخواست (hx-post=”/todos”) با فرمت JSON (hx-ext=”json-enc”) و پاسخ را در عنصر والد قبل از فرم (hx-swap=”beforebegin”). در نهایت، را اصلاح کنید TodoList جزء شامل TodoForm جزء:

public static IHtmlContent TodoList(IEnumerableTodoItem> todoItems)
{
var builder = new HtmlContentBuilder();
builder.AppendHtml(“”);
foreach (var todoItem in todoItems)
{
builder.AppendHtml(TodoItem(todoItem));
}
builder.AppendHtml(TodoForm());
builder.AppendHtml(“”);
return builder;
}

وارد حالت تمام صفحه شوید

از حالت تمام صفحه خارج شوید

در نتیجه، HTMX یک کتابخانه جاوا اسکریپت قدرتمند و سبک است که فرآیند ساخت برنامه های کاربردی وب تعاملی را ساده می کند. با استفاده از ویژگی‌های HTML برای درخواست‌های AJAX، HTMX منحنی یادگیری آسان، عملکرد بهبود یافته و یکپارچه‌سازی یکپارچه با فناوری‌های سمت سرور را ارائه می‌دهد. این راهنمای مبتدی پایه محکمی برای شروع کار با HTMX فراهم می کند و قابلیت های آن را از طریق یک مثال ساده Todo App به نمایش می گذارد. همه کدها در اینجا موجود است. با تشکر، و کد نویسی مبارک.

 hx-get="/data" hx-trigger="click" hx-swap="outerHTML">
    Get

dotnet new web -o TodoApi
dotnet new sln -n Htmx
dotnet sln add --in-root TodoApi

using System.Net.Mime;
using System.Text;

namespace TodoApi;

public class HtmlResult : IResult
{
    private readonly string _html;

    public HtmlResult(string html)
    {
        _html = html;
    }

    public Task ExecuteAsync(HttpContext httpContext)
    {
        httpContext.Response.ContentType = MediaTypeNames.Text.Html;
        httpContext.Response.ContentLength = Encoding.UTF8.GetByteCount(_html);
        return httpContext.Response.WriteAsync(_html);
    }
}

using Microsoft.AspNetCore.Html;
using TodoApi;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/hello-world", () => new HtmlResult(@"

    
        
        
        

		

			

										

							
							 هم‌رسانی
						
						
				
					 فیس بوک
				
				
					 توییتر (X)
				
				
					 لینکدین
				
				
					 ‫تامبلر
				
				
					 ‫پین‌ترست
				
				
					 ‫رددیت
				
				
					 ‫VKontakte
				
				
					 ‫Odnoklassniki
				
				
					 پاکت
				
				
					 رایانامه
				
				
					 چاپ