📞 02166056460

متد ajaxComplete

8 / 10
از 4 کاربر
بازگشت به لیست مقالات » | شنبه 2 آبان 1405 در ساعت 17 و 2 دقیقه | نظرات کاربران ( 0 )
آموزش jQuery

متد ajaxComplete در jQuery

بررسی کاربرد، پارامترها، مثال عملی و نکات مهم رویداد تکمیل درخواست Ajax

در این راهنما با متد ajaxComplete در jQuery آشنا می شوید؛ رویدادی که پس از پایان درخواست Ajax اجرا می شود و برای مدیریت کارهایی مانند پنهان کردن نشانگر بارگذاری کاربرد دارد. در ادامه، تفاوت آن با رویدادهای موفقیت و خطا، شیوه استفاده، محدودیت ها و چند نمونه کد را بررسی می کنیم.

اگر در حال یادگیری jQuery هستید، مطالب آموزش JQuery می تواند برای آشنایی با مفاهیم مرتبط مفید باشد. همچنین، اگر در پروژه خود به پیاده سازی رابط کاربری یا طراحی سایت نیاز دارید، رفتار درخواست های ناهمگام را از همان ابتدا در نظر بگیرید تا تجربه کاربری روان تری بسازید.

۰۱

متد ajaxComplete چیست و چه زمانی اجرا می شود؟

ajaxComplete یک رویداد سراسری در jQuery است. این رویداد زمانی اجرا می شود که یک درخواست Ajax به پایان برسد؛ چه درخواست با موفقیت پاسخ گرفته باشد و چه با خطا یا وضعیت دیگری تمام شده باشد. بنابراین، برای کارهایی مناسب است که باید بعد از پایان درخواست انجام شوند و به موفق یا ناموفق بودن آن وابسته نیستند.

برای نمونه، فرض کنید هنگام دریافت اطلاعات، یک پیام «در حال بارگذاری» نمایش می دهید. پس از تمام شدن درخواست، این پیام باید ناپدید شود؛ حتی اگر سرور پاسخ خطا برگرداند. استفاده از رویداد تکمیل در چنین موقعیتی کمک می کند پیام بارگذاری در هر دو حالت بسته شود. برای نمایش پیام موفقیت یا خطای مشخص، باید از رویدادهای مناسب همان وضعیت نیز کمک بگیرید.

در نسخه های جدیدتر jQuery، رویدادهای سراسری Ajax باید روی شیء document ثبت شوند. به همین دلیل شکل پیشنهادی استفاده از این رویداد، اتصال آن به سند صفحه است. این نکته به ویژه هنگام انتقال کدهای قدیمی اهمیت دارد؛ چون ثبت رویداد روی یک عنصر دلخواه ممکن است مطابق انتظار عمل نکند.

۵ نکته مهم درباره متد ajaxComplete

۰۲

۱. این رویداد پایان درخواست را نشان می دهد، نه موفقیت آن را

نکته اصلی در استفاده از ajaxComplete این است که «پایان یافتن» را گزارش می کند، نه «موفق شدن» را. اگر سرور خطا بدهد یا درخواست با وضعیت ناموفق خاتمه پیدا کند، رویداد تکمیل همچنان می تواند اجرا شود. بنابراین بهتر است برای پاک سازی وضعیت عمومی صفحه از آن استفاده کنید، نه برای اعلام قطعی موفقیت عملیات.

برای مثال، پنهان کردن لایه بارگذاری پس از پایان هر درخواست، وظیفه ای عمومی است و می تواند در این رویداد انجام شود. اما نمایش پیام «اطلاعات با موفقیت ذخیره شد» باید به نتیجه واقعی درخواست وابسته باشد و در رویداد موفقیت قرار بگیرد. این جداسازی از نمایش پیام گمراه کننده به کاربر جلوگیری می کند.

در یک فرم ثبت نام، اگر درخواست پایان پیدا کند، می توان دکمه ارسال را دوباره فعال کرد؛ اما تنها در صورت پاسخ موفق باید پیام تایید ثبت اطلاعات نشان داده شود. این مثال ساده تفاوت میان پایان درخواست و نتیجه درخواست را روشن می کند.

۰۳

۲. رویداد را روی document ثبت کنید

برای شنیدن رویدادهای سراسری Ajax، آن را روی document ثبت کنید. روش ثبت روی یک عنصر صفحه در نسخه های قدیمی ممکن است در کدهای موجود دیده شود، اما برای سازگاری با نسخه های جدید، اتصال به سند انتخاب مطمئن تری است.

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

برای نمونه، صفحه ای را تصور کنید که هم فهرست محصولات را بارگذاری می کند و هم اطلاعات حساب کاربر را. شنونده عمومی می تواند یک شاخص کلی را پس از پایان درخواست پنهان کند، اما به روزرسانی محتوای هر بخش بهتر است با منطق مختص همان درخواست انجام شود.

۰۴

۳. پارامترهای تابع را بشناسید

تابعی که به رویداد تکمیل می دهید، اطلاعاتی درباره رویداد و درخواست تمام شده دریافت می کند. در امضای رایج، این اطلاعات شامل شیء رویداد، شیء درخواست و تنظیمات Ajax است. شناخت آن ها کمک می کند درخواست مربوط را بررسی کنید یا بر اساس پاسخ دریافتی، رفتار دقیق تری بنویسید.

در نام گذاری پارامترها، مستندات جدید jQuery معمولاً از event، jqXHR و ajaxSettings استفاده می کنند. در مثال های قدیمی تر ممکن است نام هایی مانند xhr و options ببینید. نام متغیرها را می توان تغییر داد؛ مهم این است که ترتیب آرگومان ها را درست درک کنید.

📡

event

اطلاعات مربوط به رویدادی را در بر می گیرد که تابع را اجرا کرده است.

🔄

jqXHR

به شیء درخواست دسترسی می دهد تا وضعیت و پاسخ آن بررسی شود.

⚙️

ajaxSettings

تنظیماتی را ارائه می کند که برای ارسال درخواست Ajax استفاده شده اند.

وجود این پارامترها به این معنا نیست که باید همیشه از همه آن ها استفاده کنید. اگر هدف فقط بستن یک نشانگر بارگذاری باشد، بدنه تابع می تواند ساده بماند. هنگامی که لازم است درخواست ها را از هم تشخیص دهید، بررسی تنظیمات یا نشانی درخواست می تواند مفید باشد؛ اما این کار باید با توجه به ساختار واقعی پروژه انجام شود.

۰۵

۴. ترتیب رویدادها را با هدف خود هماهنگ کنید

رویدادهای سراسری Ajax برای کارهای متفاوتی در نظر گرفته شده اند. رویداد آغاز درخواست برای شروع نمایش وضعیت بارگذاری، رویداد موفقیت برای رسیدگی به پاسخ موفق، رویداد خطا برای مدیریت شکست و رویداد تکمیل برای کارهای مشترک پس از پایان درخواست به کار می رود.

اگر همه منطق را در ajaxComplete قرار دهید، تشخیص دلیل اجرای هر بخش دشوار می شود. برای مثال، ممکن است پیام خطا و پیام موفقیت هر دو پس از هر درخواست اجرا شوند، چون تابع تکمیل از وضعیت نهایی به تنهایی نتیجه گیری نمی کند. بهتر است هر رویداد فقط مسئولیت مرتبط با نام و هدف خود را داشته باشد.

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

۰۶

۵. همه درخواست ها الزاماً این رویداد را فعال نمی کنند

رویدادهای سراسری فقط برای درخواست هایی اجرا می شوند که در سازوکار Ajax سراسری مشارکت دارند. برای نمونه، اگر در تنظیمات یک درخواست مقدار global: false تعیین شده باشد، رویدادهای عمومی Ajax برای آن درخواست اجرا نمی شوند. این موضوع می تواند علت اجرا نشدن تابع ثبت شده باشد.

همچنین برخی درخواست های خاص، مانند درخواست های بین دامنه ای مبتنی بر JSONP یا بارگذاری اسکریپت، ممکن است با رویدادهای سراسری متداول رفتار متفاوتی داشته باشند. هنگام عیب یابی، نوع درخواست، تنظیمات آن و نسخه jQuery را بررسی کنید و به فرض های کلی اکتفا نکنید.

برای مثال، اگر نشانگر بارگذاری پس از یک درخواست خاص خاموش نمی شود، ابتدا بررسی کنید که درخواست واقعاً از مسیر Ajax مورد انتظار ارسال شده باشد و تنظیمات آن رویدادهای سراسری را غیرفعال نکرده باشد. این بررسی معمولاً سریع تر از بازنویسی بی دلیل تابع رویداد نتیجه می دهد.

شکل کلی استفاده از ajaxComplete

۰۷

ثبت رویداد و آرگومان های تابع

در شکل کلی زیر، تابع پس از پایان درخواست Ajax اجرا می شود. آرگومان های تابع برای دسترسی به اطلاعات رویداد، درخواست و تنظیمات آن هستند. در کد جدید، ثبت رویداد روی سند صفحه انتخاب مناسبی است:

$(document).ajaxComplete(function(event, jqXHR, ajaxSettings) {
  // کد مورد نظر پس از پایان درخواست
});

اگر تابع شما از اطلاعات درخواست استفاده نمی کند، لازم نیست برای آرگومان ها نامی تعیین کنید. اما اگر می خواهید وضعیت پاسخ یا نشانی درخواست را بررسی کنید، پارامترهای مناسب را دریافت کنید و در صورت نیاز مستندات نسخه مورد استفاده را نیز مرور کنید.

۰۸

مثال کاربردی: پنهان کردن نشانگر بارگذاری

در مثال زیر، هنگام آغاز درخواست یک نشانگر ساده نمایش داده می شود و پس از پایان درخواست، پنهان می شود. رویداد تکمیل، مستقل از موفق یا ناموفق بودن نتیجه، مرحله پاک سازی را انجام می دهد. برای مشاهده نتیجه بهتر است عنصری با شناسه wait در صفحه داشته باشید.

$(document).ajaxStart(function() {
  $("#wait").show();
});

$(document).ajaxComplete(function() {
  $("#wait").hide();
});

این نمونه برای وضعیت بارگذاری عمومی مناسب است. اگر صفحه چند درخواست هم زمان دارد، رفتار رویدادهای آغاز و پایان سراسری را در کنار تعداد درخواست های فعال در نظر بگیرید. هدف این است که نشانگر زودتر از پایان کارهای در جریان پنهان نشود و کاربر تصور نکند صفحه آماده شده است، در حالی که هنوز اطلاعات دیگری دریافت می شود.

برای یک درخواست مشخص، می توانید از تنظیمات همان فراخوانی هم استفاده کنید. این روش زمانی مناسب است که نشانگر فقط به یک بخش مربوط باشد یا نخواهید رویداد سراسری بر تمام درخواست های صفحه اثر بگذارد.

توسعه وب

رفتار درخواست ها را از ابتدا طراحی کنید

مدیریت روشن وضعیت بارگذاری، خطا و پاسخ سرور بخشی از تجربه کاربری مناسب در طراحی سایت است.

اطلاعات بیشتر درباره طراحی سایت ←

تحلیل کاربرد ajaxComplete در پروژه های واقعی

۰۹

چرا پایان درخواست باید جدا از نتیجه آن مدیریت شود؟

هر درخواست Ajax یک چرخه دارد: ارسال می شود، در حال انتظار می ماند و در نهایت پایان می یابد. نتیجه نهایی ممکن است موفقیت آمیز باشد یا نیازمند رسیدگی به خطا باشد. رابط کاربری هم معمولاً در هر دو حالت باید از وضعیت انتظار خارج شود؛ برای مثال، دکمه ارسال دوباره فعال شود یا نشانگر بارگذاری بسته شود.

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

در مقابل، اگر عملیات پاک سازی فقط در مسیر موفقیت نوشته شود، هنگام شکست درخواست ممکن است دکمه غیرفعال بماند یا پیام انتظار همچنان روی صفحه دیده شود. قرار دادن پاک سازی در رویدادی که با پایان درخواست مرتبط است، راهی برای پوشش دادن هر دو مسیر فراهم می کند.

۱۰

محدودیت های رویدادهای سراسری را در نظر بگیرید

رویداد سراسری برای رفتار مشترک صفحه مفید است، اما همیشه بهترین جا برای منطق وابسته به یک دکمه یا یک بخش خاص نیست. اگر هر درخواست را بدون توجه به منبع آن یکسان مدیریت کنید، ممکن است پاسخ یک بخش باعث تغییر وضعیت بخش دیگری شود. در صفحه های پیچیده، بهتر است میان رفتار عمومی و منطق اختصاصی تعادل برقرار کنید.

راه دیگر این است که درخواست های یک بخش را با شناسه یا تنظیمات مشخص مدیریت کنید و فقط رفتارهای عمومی را به شنونده سراسری بسپارید. برای نمونه، خاموش کردن یک نشانگر کلی می تواند عمومی باشد، اما پاک کردن پیام خطای یک فرم بهتر است در همان منطق فرم انجام شود. این تفکیک نگهداری و توسعه کد را آسان تر می کند.

همچنین، در پروژه هایی که از کتابخانه ها یا افزونه های مختلف استفاده می کنند، ممکن است چند درخواست هم زمان و چند شنونده رویداد وجود داشته باشد. ثبت بی رویه handlerها می تواند باعث شود یک تابع چند بار اجرا شود. برای جلوگیری از آن، محل ثبت رویداد را کنترل کنید و از ثبت دوباره در هر بار باز شدن یک بخش صفحه پرهیز کنید.

✅

پاک سازی عمومی

کارهایی را انجام می دهد که پس از پایان درخواست، به نتیجه وابسته نیستند.

📊

بررسی پاسخ

با دسترسی به شیء درخواست، امکان بررسی اطلاعات پاسخ را فراهم می کند.

🔒

مدیریت وضعیت

به پایان دادن به حالت انتظار در مسیرهای موفق و ناموفق کمک می کند.

مزایا و ملاحظات استفاده از ajaxComplete

مزایای ajaxComplete

مدیریت روشن تر درخواست ها

برای رابط کاربری قابل پیش بینی
۰۱
پایان درخواست

اجرای پس از تکمیل

برای انجام کارهای پایانی مشترک.

۰۲
نتیجه مستقل

پوشش دو وضعیت

پایان کار، چه موفق و چه ناموفق.

۰۳
اطلاعات درخواست

دسترسی به پارامترها

بررسی رویداد و تنظیمات درخواست.

۰۴
کاهش تکرار

پاک سازی متمرکز

قرار دادن منطق مشترک در یک محل.

۰۵
رابط کاربری

کنترل بارگذاری

پنهان کردن نشانگر پس از پایان کار.

۱۱

جدول خلاصه رویدادها و پارامترها

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

مورد کاربرد نکته مهم
ajaxComplete اجرای کارهای مشترک پس از پایان درخواست به تنهایی نشانه موفقیت نیست
event دسترسی به اطلاعات رویداد آرگومان نخست تابع است
jqXHR بررسی شیء درخواست و پاسخ در نمونه های قدیمی ممکن است xhr نامیده شود
ajaxSettings دسترسی به تنظیمات درخواست در نمونه های قدیمی ممکن است options نامیده شود
global: false غیرفعال کردن رویدادهای سراسری برای یک درخواست می تواند مانع اجرای handler عمومی شود
۱۲

نتیجه گیری: چه زمانی از ajaxComplete استفاده کنیم؟

متد ajaxComplete در jQuery برای اجرای کارهایی مناسب است که باید پس از پایان درخواست Ajax انجام شوند، بدون آنکه موفقیت یا شکست درخواست شرط اجرای آن ها باشد. بستن نشانگر بارگذاری، بازگرداندن وضعیت عمومی رابط کاربری و انجام پاک سازی های مشترک از نمونه های کاربردی آن هستند.

برای استفاده درست، رویداد را روی document ثبت کنید، پارامترهای تابع را در صورت نیاز بررسی کنید و محدودیت درخواست هایی را که رویدادهای سراسری را غیرفعال می کنند در نظر بگیرید. پیام موفقیت و رسیدگی به خطا را نیز به رویدادهای متناسب بسپارید تا کد خوانا و رفتار صفحه قابل پیش بینی باقی بماند.

سوالات متداول متد ajaxComplete در jQuery

آیا ajaxComplete فقط پس از درخواست موفق اجرا می شود؟

خیر. این رویداد پس از پایان درخواست اجرا می شود و موفقیت شرط اجرای آن نیست. برای نمایش پیام موفقیت یا مدیریت خطا، از رویدادهای متناسب با نتیجه درخواست استفاده کنید.

رویداد ajaxComplete را روی کدام عنصر ثبت کنیم؟

برای دریافت رویدادهای سراسری Ajax در نسخه های جدید jQuery، آن را روی document ثبت کنید. ثبت رویداد روی عنصر دلخواه ممکن است در همه نسخه ها رفتار مورد انتظار را نداشته باشد.

پارامترهای تابع ajaxComplete چه اطلاعاتی دارند؟

تابع می تواند شیء رویداد، شیء درخواست و تنظیمات Ajax را دریافت کند. در نام گذاری رایج جدید این پارامترها event، jqXHR و ajaxSettings هستند؛ نام متغیرها قابل تغییر است.

چرا تابع ajaxComplete من اجرا نمی شود؟

ثبت رویداد روی عنصری غیر از document، غیرفعال بودن رویدادهای سراسری با تنظیم global: false یا استفاده از نوع خاصی از درخواست می تواند علت باشد. نسخه jQuery و تنظیمات درخواست را بررسی کنید.

تفاوت ajaxComplete با ajaxSuccess چیست؟

ajaxComplete پس از پایان درخواست اجرا می شود، در حالی که ajaxSuccess برای درخواست موفق است. بنابراین، کارهای عمومی پس از پایان را در رویداد تکمیل و رسیدگی به پاسخ موفق را در رویداد موفقیت قرار دهید.

مدیریت درخواست های Ajax را دقیق تر انجام دهید

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

ادامه آموزش JQuery ←
ارسال نظر و نظرات ثبت شده
سایر مقالات
متد serializeArray ۵ نکته مهم درباره متد serializeArray در jQuery 💡آشنایی با متد در این بخش از آموزش JQuery، ب ...
متد serialize متد serialize در jQuery چیست و چگونه از آن استفاده کنیم؟ ⭐ آشنایی با serialize در این بخش از ...
متد $.post متد post در jQuery چیست و چگونه از آن استفاده کنیم؟ ⭐ آشنایی با درخواست POST در این راهنما، ...
متد load متد load در jQuery چیست و چگونه استفاده می‌شود؟ ⭐ متد load در jQuery متد load در jQuery ...
متد $.getScript آموزش jQuery متد getScript در jQuery؛ دریافت و اجرای فایل جاوااسکریپت نحوه استفاده، پارامت ...
متد $.getJSON آموزش جی کوئری متد $.getJSON در جی کوئری؛ آموزش دریافت داده های JSON نحوه استفاده، مدیریت ...
متد $.get آموزش jQuery آموزش متد $.get در jQuery؛ دریافت اطلاعات از سرور نحوه ارسال درخواست GET، دری ...
متد ajaxSuccess آموزش jQuery متد ajaxSuccess در jQuery؛ آموزش کاربرد و مثال آشنایی با رویداد موفقیت درخواس ...
متد ajaxStop آموزش jQuery متد ajaxStop در jQuery تشخیص پایان همه درخواست های هم زمان Ajax و اجرای کد من ...
متد ajaxStart آموزش jQuery متد ajaxStart در jQuery؛ آموزش کاربرد و مثال اجرای تابع هنگام آغاز درخواست&zw ...
متد $.ajaxSetup آموزش jQuery و Ajax متد ajaxSetup در jQuery: تنظیم پیش فرض درخواست های Ajax نحوه کار، نمون ...
متد ajaxSend آموزش jQuery متد ajaxSend در jQuery چیست و چگونه از آن استفاده کنیم؟ آشنایی با رویداد ارسا ...
متد ajaxError آموزش jQuery متد ajaxError در jQuery؛ مدیریت خطای درخواست Ajax نحوه کار، آرگومان‌ها، ...
متد ajaxComplete آموزش jQuery متد ajaxComplete در jQuery بررسی کاربرد، پارامترها، مثال عملی و نکات مهم روید ...
متد ajax آموزش jQuery متد Ajax در jQuery؛ راهنمای ارسال درخواست به سرور آشنایی با ساختار درخواست Aj ...
متد Get و Post ای جکس در جی کوئری آموزش jQuery Ajax متدهای GET و POST در jQuery Ajax انتخاب متد مناسب، ارسال داده و مدیریت پ ...
Ajax در Jquery چگونه است ؟ Ajax در jQuery چیست و چگونه کار می‌کند؟ 💡آشنایی با ایجکس Ajax در jQuery روشی ساده بر ...
دسته بندی
جستجو
⏳ در حال پردازش...
لطفا صبر کنید