📞 02166056460

متد ajaxSuccess

10 / 10
از 1 کاربر
بازگشت به لیست مقالات » | جمعه 1 آبان 1405 در ساعت 11 و 55 دقیقه | نظرات کاربران ( 0 )
آموزش jQuery

متد ajaxSuccess در jQuery؛ آموزش کاربرد و مثال

آشنایی با رویداد موفقیت درخواست Ajax، پارامترها، نمونه کد و نکته‌های مهم نسخه‌های جدید jQuery

در این راهنما، متد ajaxSuccess در jQuery را با مثال‌های کاربردی بررسی می‌کنیم تا بدانید چه زمانی اجرا می‌شود، چه اطلاعاتی در اختیار تابع قرار می‌دهد و چطور می‌توان آن را با روش پیشنهادی نسخه‌های جدید نوشت. این رویداد برای واکنش به پایان موفقیت‌آمیز درخواست‌های Ajax کاربرد دارد، اما با رویدادهای مربوط به خطا یا پایان هر درخواست یکسان نیست.

برای آشنایی بیشتر با مبانی کتابخانه، می‌توانید به آموزش JQuery مراجعه کنید. در ادامه، علاوه بر شکل کلی استفاده، محدودیت‌ها، روش عیب‌یابی و نمونه‌هایی برای رابط کاربری را می‌خوانید.

۵ نکته مهم درباره متد ajaxSuccess در jQuery

۰۱

۱. رویداد فقط پس از پاسخ موفق اجرا می‌شود

ajaxSuccess یک رویداد سراسری Ajax است که پس از موفقیت درخواست اجرا می‌شود. منظور از موفقیت این است که درخواست به پاسخ موفق برسد؛ بنابراین برای مدیریت خطای شبکه، خطای سرور یا پاسخ ناموفق نباید فقط به این رویداد تکیه کنید. برای آن وضعیت‌ها معمولاً از گزینه‌های error و رویدادهایی مانند ajaxError استفاده می‌شود.

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

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

۰۲

۲. برای همه درخواست‌ها قابل استفاده است

ویژگی سراسری بودن باعث می‌شود یک handler بتواند موفقیت درخواست‌های Ajax مختلف را مشاهده کند؛ لازم نیست برای هر درخواست یک شنونده جداگانه بسازید. این روش برای ثبت رخدادها، مخفی‌کردن نشانگر بارگذاری عمومی یا اجرای رفتاری مشترک در چند بخش سایت سودمند است.

بااین‌حال، رویداد تنها زمانی فعال می‌شود که درخواست با تنظیم global غیرفعال نشده باشد. مقدار پیش‌فرض این تنظیم فعال است. اگر درخواست خاصی نباید رویدادهای سراسری را فعال کند، می‌توان در تنظیمات همان درخواست global: false قرار داد.

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

۰۳

۳. در jQuery جدید، handler را به document متصل کنید

از jQuery نسخه ۱٫۹ به بعد، برای دریافت رویدادهای سراسری Ajax باید handler را به شیء document متصل کنید. اتصال به یک عنصر دلخواه صفحه، مانند div، برای دریافت این رویداد سراسری مناسب نیست. این نکته یکی از علت‌های رایج اجرا نشدن handler در کدهای قدیمی است.

در نسخه‌های تازه‌تر، روش پیشنهادی استفاده از .on() است. شکل قدیمی .ajaxSuccess() به‌عنوان روش کوتاه‌شده شناخته می‌شود و در jQuery 3.5 منسوخ اعلام شده است؛ بنابراین هنگام نوشتن کد جدید بهتر است از روش اتصال رویداد استفاده کنید.

مثال کاربردی: اگر رویدادی را به $("div") متصل کنید و انتظار داشته باشید تمام درخواست‌های صفحه را ببیند، احتمالاً نتیجه دلخواه نمی‌گیرید. اتصال به $(document) مطابق رفتار رویداد سراسری است.

۱٫۰
معرفی ajaxSuccess در jQuery
۱٫۹
الزام اتصال رویداد سراسری به document
۳٫۵
منسوخ‌شدن روش کوتاه‌شده ajaxSuccess
۰۴

۴. پارامترهای رویداد اطلاعات درخواست را فراهم می‌کنند

تابع handler می‌تواند اطلاعات رویداد، شیء درخواست و تنظیمات Ajax را دریافت کند. شکل متداول این پارامترها به‌صورت event، xhr و settings است. نام متغیرها را می‌توانید تغییر دهید، اما ترتیب پارامترها را باید مطابق امضای رویداد نگه دارید.

شیء xhr به پاسخ و وضعیت درخواست دسترسی می‌دهد و شیء تنظیمات اطلاعاتی مانند نشانی درخواست و نوع آن را در بر می‌گیرد. این داده‌ها برای بررسی رفتار برنامه مفیدند؛ بااین‌حال، اطلاعات حساس پاسخ را بدون بررسی امنیت و حریم خصوصی در گزارش‌ها ثبت نکنید.

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

📡

event

شیء رویداد را در اختیار handler می‌گذارد.

⚙️

xhr

به شیء درخواست و اطلاعات پاسخ دسترسی می‌دهد.

📊

settings

تنظیمات مربوط به درخواست Ajax را نگه می‌دارد.

۰۵

۵. رویداد سراسری را برای کارهای مشترک نگه دارید

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

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

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

شکل کلی استفاده و نمونه کد

۰۶

نحوه استفاده از متد ajaxSuccess

در نمونه قدیمی، تابع handler را با متد کوتاه‌شده به یک انتخابگر متصل می‌کردند. این نمونه برای شناخت کدهای موجود مفید است؛ اما برای پروژه‌های جدید و نسخه‌های تازه jQuery، اتصال رویداد به document با .on() انتخاب مناسب‌تری است. صفحه باید jQuery را پیش از اجرای این کد بارگذاری کرده باشد.

$(document).ajaxSuccess(function(event, xhr, settings) {
  console.log("AJAX request successfully completed");
});

در این شکل، تابع پس از موفقیت درخواست‌های سراسری اجرا می‌شود. پارامتر event اطلاعات رویداد را نگه می‌دارد، xhr شیء درخواست است و settings تنظیمات ارسال‌شده به Ajax را در اختیار می‌گذارد. کد ساده بالا فقط برای نمایش اجراشدن handler پیامی در کنسول ثبت می‌کند.

نمونه پیشنهادی با .on() چنین است:

$(document).on("ajaxSuccess", function(event, xhr, settings) {
  console.log("درخواست با موفقیت کامل شد:", settings.url);
});

برای اینکه پیام را فقط برای یک درخواست خاص نمایش دهید، شرطی بر اساس نشانی یا تنظیمات درخواست اضافه کنید. به این ترتیب، رویداد همچنان سراسری می‌ماند، اما واکنش برنامه به درخواست موردنظر محدود می‌شود.

$(document).on("ajaxSuccess", function(event, xhr, settings) {
  if (settings.url === "/api/products") {
    console.log("فهرست محصولات با موفقیت دریافت شد");
  }
});

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

✅

پیام موفقیت

نمایش اعلان عمومی پس از پاسخ موفق درخواست.

📊

ثبت رخداد

بررسی درخواست‌های موفق برای گزارش‌گیری مناسب.

🔄

به‌روزرسانی عمومی

اجرای یک رفتار مشترک پس از دریافت موفق پاسخ.

راهنمای استفاده درست از ajaxSuccess

۰۷

انتخاب محل اتصال رویداد

برای رویداد سراسری، محل اتصال را document در نظر بگیرید. اتصال handler به یک عنصر محتوایی ممکن است این تصور را ایجاد کند که رویداد به آن عنصر محدود است، درحالی‌که هدف رویداد مشاهده درخواست‌های Ajax در سطح صفحه است.

اگر قصد دارید تنها یک عملیات مشخص را مدیریت کنید، ممکن است گزینه success در فراخوانی $.ajax() واضح‌تر و ساده‌تر باشد. برای نمونه، دریافت پاسخ جست‌وجو و نمایش نتیجه آن معمولاً منطق اختصاصی همان درخواست است، نه رفتاری مشترک برای همه درخواست‌های سایت.

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

۰۸

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

پیش از استفاده از رویداد، بررسی کنید که درخواست واقعاً از طریق Ajax ارسال شده باشد و تنظیم global آن خاموش نشده باشد. همچنین مطمئن شوید handler پس از بارگذاری jQuery و پیش از ارسال درخواست ثبت شده است. اگر درخواست زودتر ارسال شود، رویدادی که بعداً به صفحه متصل شده آن را دریافت نمی‌کند.

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

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

۰۹

توجه به تفاوت موفقیت و پایان درخواست

ajaxSuccess فقط برای درخواست موفق است. رویداد ajaxComplete پس از پایان درخواست اجرا می‌شود، چه پاسخ موفق باشد و چه ناموفق. برای رسیدگی به خطا نیز می‌توانید از ajaxError یا گزینه error درخواست استفاده کنید. انتخاب درست به رفتاری بستگی دارد که می‌خواهید پیاده‌سازی کنید.

این تفاوت در مدیریت نشانگر بارگذاری اهمیت دارد. اگر نشانگر باید بعد از هر درخواست ناپدید شود، صرفاً استفاده از ajaxSuccess کافی نیست؛ چون در صورت خطا اجرا نمی‌شود. در مقابل، اگر پیام فقط پس از موفقیت نمایش داده می‌شود، این رویداد یا callback موفقیت می‌تواند گزینه مناسبی باشد.

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

۱۰

سازگاری با ساختار فعلی پروژه

در پروژه‌های قدیمی ممکن است کدهای متعددی از شکل .ajaxSuccess() استفاده کنند. پیش از تغییر، نسخه jQuery و محل‌های اتصال handler را بررسی کنید. سپس رویداد را به روش جدید منتقل و رفتار برنامه را در حالت موفقیت، خطا و ارسال هم‌زمان چند درخواست آزمایش کنید.

در برنامه‌های بزرگ، ثبت handler سراسری می‌تواند روی بخش‌هایی اثر بگذارد که در زمان نوشتن کد در نظر گرفته نشده‌اند. به همین دلیل، نام‌گذاری روشن، شرط‌گذاری بر اساس تنظیمات درخواست و مستندسازی رفتار handler به کاهش خطاهای ناخواسته کمک می‌کند.

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

اشتباهات رایج هنگام استفاده

۱۱

اتصال handler به انتخابگر نامناسب

یکی از خطاهای رایج این است که رویداد سراسری به یک عنصر دلخواه مانند $("div") متصل شود. اگر handler اجرا نمی‌شود، ابتدا اتصال به $(document) را بررسی کنید و مطمئن شوید کد پیش از ارسال درخواست اجرا شده است.

۱۲

انتظار اجرای رویداد برای پاسخ ناموفق

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

۱۳

نادیده‌گرفتن تنظیم global

درخواستی که با global: false ارسال شده باشد رویدادهای سراسری Ajax را فعال نمی‌کند. اگر تنها یک درخواست از handler عبور نمی‌کند، تنظیمات همان درخواست را با دقت بررسی کنید.

۱۴

استفاده از روش کوتاه‌شده در کد تازه

روش کوتاه‌شده ممکن است در کدهای قدیمی دیده شود، اما برای پیاده‌سازی تازه بهتر است از $(document).on("ajaxSuccess", handler) استفاده کنید. این شکل، نوع رویداد و محل اتصال را آشکارتر نشان می‌دهد و با راهنمای نسخه‌های جدید سازگارتر است.

مقایسه رویدادهای مرتبط Ajax

۱۵

هر رویداد برای چه کاری مناسب است؟

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

رویداد یا گزینه زمان اجرا کاربرد معمول
ajaxSuccess پس از موفقیت درخواست سراسری رفتار مشترک پس از دریافت موفق پاسخ
ajaxError پس از خطای درخواست سراسری ثبت یا مدیریت خطاهای عمومی
ajaxComplete پس از پایان درخواست، موفق یا ناموفق پاک‌سازی یا پایان وضعیت عمومی بارگذاری
success پس از موفقیت همان درخواست پردازش اختصاصی پاسخ یک درخواست
error در صورت خطای همان درخواست نمایش یا مدیریت خطای اختصاصی

نکات کلیدی برای پیاده‌سازی مطمئن

۱۶

چک‌لیست پیش از استفاده

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

  • محل اتصال: برای رویداد سراسری، handler را به document متصل کنید.
  • زمان اتصال: پیش از ارسال درخواست، کد ثبت رویداد را اجرا کنید.
  • روش پیشنهادی: در کد جدید از .on("ajaxSuccess", handler) استفاده کنید.
  • مدیریت خطا: برای پاسخ ناموفق، مسیر جداگانه‌ای در نظر بگیرید.
  • دامنه کاربرد: منطق اختصاصی هر درخواست را در callback مربوط به همان درخواست نگه دارید.
مزایای ajaxSuccess

رفتار مشترک و قابل پیگیری

کاربردهای مناسب رویداد سراسری
۰۱
عمومی

مشاهده درخواست‌ها

مدیریت رفتار مشترک پس از پاسخ موفق

۰۲
گزارش

ثبت رخداد موفق

بررسی درخواست‌های موفق در برنامه

۰۳
رابط کاربری

اعلان عمومی

نمایش پیام پس از پاسخ موفق

۰۴
یکپارچه

کاهش تکرار کد

اجرای منطق مشترک در چند بخش

۰۵
کنترل

دسترسی به تنظیمات

بررسی اطلاعات درخواست در handler

۱۷

جمع‌بندی: چه زمانی از ajaxSuccess استفاده کنیم؟

متد ajaxSuccess در jQuery برای اجرای یک رفتار مشترک پس از موفقیت درخواست‌های سراسری Ajax مناسب است. در نسخه‌های جدید، handler را به document متصل کنید و برای کد تازه روش .on() را ترجیح دهید. پارامترهای رویداد، شیء درخواست و تنظیمات Ajax می‌توانند برای تشخیص درخواست و تصمیم‌گیری استفاده شوند.

در عین حال، به خاطر داشته باشید که این رویداد برای خطا اجرا نمی‌شود و درخواست‌هایی با global: false را پوشش نمی‌دهد. اگر منطق تنها به یک درخواست مربوط است، callbackهای همان درخواست گزینه روشن‌تری هستند. انتخاب درست میان رویداد سراسری و callback اختصاصی، کد را قابل فهم‌تر و نگهداری آن را ساده‌تر می‌کند.

اگر برای پیاده‌سازی رابط کاربری یا ارتقای وب‌سایت خود به راهنمایی نیاز دارید، درباره طراحی سایت و نیازهای پروژه‌تان بیشتر بخوانید.

برای ساخت تجربه کاربری بهتر برنامه‌ریزی کنید

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

مشاهده خدمات طراحی سایت ←

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

متد ajaxSuccess در jQuery چه کاری انجام می‌دهد؟

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

در jQuery جدید، ajaxSuccess را به کجا متصل کنیم؟

برای دریافت رویداد سراسری، handler را به document متصل کنید. روش پیشنهادی برای کد جدید استفاده از $(document).on("ajaxSuccess", handler) است.

آیا ajaxSuccess هنگام بروز خطا هم اجرا می‌شود؟

خیر. این رویداد برای درخواست موفق است. برای مدیریت خطا از گزینه error در همان درخواست یا رویداد سراسری ajaxError استفاده کنید. رویداد ajaxComplete پس از پایان درخواست، چه موفق و چه ناموفق، اجرا می‌شود.

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

handler معمولاً پارامترهای event، xhr و settings را دریافت می‌کند. این پارامترها به‌ترتیب اطلاعات رویداد، شیء درخواست و تنظیمات Ajax را فراهم می‌کنند.

تفاوت ajaxSuccess با گزینه success چیست؟

ajaxSuccess رویدادی سراسری برای درخواست‌های موفق است، درحالی‌که گزینه success به یک درخواست مشخص تعلق دارد. برای پردازش اختصاصی پاسخ یک درخواست، معمولاً callback همان درخواست خواناتر است.

ارسال نظر و نظرات ثبت شده
سایر مقالات
متد 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 روشی ساده بر ...
دسته بندی
جستجو
⏳ در حال پردازش...
لطفا صبر کنید