التابع ‎‎jQuery.ajax()‎‎ في jQuery

من موسوعة حسوب
< jQuery‏ | jQuery
مراجعة 10:37، 1 يوليو 2018 بواسطة عبد اللطيف ايمش (نقاش | مساهمات) (←‏أنواع البيانات)
(فرق) → مراجعة أقدم | المراجعة الحالية (فرق) | مراجعة أحدث ← (فرق)

jQuery.ajax( url [, settings ] )‎

القيم المعادة

تعيد كائنًا من النوع jqXHR.

الوصف

ترسل هذه الدالة طلب ‎(Ajax) HTTP غير متزامن.

jQuery.ajax( url [, settings ] )‎

أُضيف مع الإصدار: 1.5.

url

سلسلة نصية تحتوي على العنوان URL المراد إرسال الطلب إليه.

settings

كائن مجرَّد (object) يمثِّل مجموعة من الأزواج مفتاح/قيمة التي تضبط طلب Ajax. جميع الإعدادات اختيارية ويمكن تعيين إعدادات افتراضية لأي ضبط باستعمال التابع ‎$.ajaxSetup()‎. انظر إلى القسم التالي للاطلاع على القائمة الكاملة لجميع الإعدادات.

jQuery.ajax( [ settings ] )‎

أُضيف مع الإصدار: 1.0.

settings

كائن مجرَّد (object) يمثِّل مجموعة من الأزواج مفتاح/قيمة التي تضبط طلب Ajax. جميع الإعدادات اختيارية ويمكن تعيين إعدادات افتراضية لأي ضبط باستعمال التابع ‎$.ajaxSetup()‎.

الإعدادات المتاحة هي:

accepts

كائن مجرَّد يمثل مجموعة من الأزواج مفتاح/قيمة التي تعيِّن dataType المعطى إلى النوع MIME المقابل لها والذي أرسل في ترويسة الطلب Accept، وقيمته الافتراضية تعتمد على dataType. تخبر هذه الترويسة الخادم عن نوع الاستجابة التي تقبلها هي بدورها. على سبيل المثال، تعرِّف الشيفرة التالية نوعًا خاصًا هو mycustomtype ليُرسَل مع الطلب:

$.ajax({
  accepts: {
    mycustomtype: 'application/x-some-custom-type'
  },
 
  // `mycustomtype` تعليمات من أجل إلغاء تسلسل النوع
  converters: {
    'text mycustomtype': function(result) {
      // افعل شيئًا
      return newresult;
    }
  },
 
  // `mycustomtype` يتوقع أن يعيد الخادم النوع
  dataType: 'mycustomtype'
});

ملاحظة: ستحتاج إلى تحديد مدخلة متممة لهذا النوع في converters في هذه الحالة من أجل أن يعمل بشكل صحيح.

async

ترسل جميع الطلبات بشكل غير متزامن افتراضيًّا، إذ إنَّ القيمة الافتراضيَّة لهذا الضبط هي true. إن أردت إرسال الطلبات بشكل متزامن، فغيِّر قيمة هذا الضبط إلى false. لا تدعم الطلبات العابرة للنطاق (cross-domain requests) والطلبات ذات النوع dataType: "jsonp"‎ العمليات المتزامنة. انتبه إلى أنَّ الطلبات المتزامنة قد تسبب توقف المتصفح مؤقتًا عن الاستجابة لأي حدث عندما يكون الطلب فعَّالًا.

بدءًا من الإصدار jQuery 1.8، أهمل استعمال async: false مع الكائن ‎(‎$.Deferred) jqXHR. يجب عليك استعمال الخيارات success/error/complete لدالة رد النداء (callback) بدلًا من التوابع المقابلة للكائن jqXHR مثل التابع jqXHR.done()‎.

beforeSend

دالة من الشكل Function( jqXHR jqXHR, Object settings )‎ تمثل دالة رد النداء التي ستُنفَّذ قبل إرسال الطلب لتعديل الكائن jqXHR (في الإصدار jQuery 1.4.x، يكون XMLHTTPRequest) قبل إرساله.

استعمل هذه الدالة من أجل ضبط ترويسات مخصَّصة. تقبل هذه الدالة أن يمرر إليها الكائن jqXHR والكائن settings كوسائط. تُعدُّ هذه الدالة حدثًا من أحداث Ajax، وسيلغى الطلب إن أعادت الدالة القيمة false.

بدءًا من الإصدار jQuery 1.5، سيستدعى الضبط beforeSend بغض النظر عن نوع الطلب.

cache

قيمة منطقيَّة (Boolean)، وقيمته الافتراضيَّة هي true في جميع أنواع الطلبات باستثناء النوع 'script' والنوع 'jsonp' التي تكون القيمة الافتراضيَّة فيها هي false. إن ضُبطت قيمته إلى false، فستجبر المتصفح حينها على عدم تخزين الصفحات المطلوبة.

ملاحظة: لن يعمل ضبط قيمة cache إلى false بشكل صحيح إلا في الطلب HEAD والطلب GET، إذ يعمل بإضافة ‎ _={timestamp}‎ إلى معاملات الطلب GET. ليس هنالك حاجة لهذا الضبط في أنواع الطلبات الأخرى، ويستثنى في هذه الحالة المتصفح IE8 عندما يرسل طلب POST لعنوان URL قد أرسل إليه طلب مسبقًا باستعمال GET.

complete

دالة من الشكل Function( jqXHR jqXHR, String textStatus )‎ تمثل الدالة التي ستُستدعى عند انتهاء الطلب (بعد تنفيذ رد النداء success ورد النداء error). تقبل هذه الدالة أن يمرَّر إليها وسيطين هما: الكائن jqXHR (في الإصدار jQuery 1.4.x، يكون XMLHTTPRequest)، وسلسلة نصية تصنِّف حالة الطلب ("success"، أو "notmodified"، أو "nocontent"، أو "error"، أو "timeout"، أو "abort"، أو "parsererror").

بدءًا من الإصدار jQuery 1.5، أصبح الضبط complete يقبل مصفوفة من الدوال، إذ ستستدعى حينئذٍ كل دالة على التوالي. تُعدُّ هذه الدالة أو الدوال حدثًا من أحداث Ajax.

contents

كائن مجرَّد يمثل مجموعة من الأزواج سلسلة نصية/تعبير نمطي (regular expression) التي ستحدِّد كيفية تحليل jQuery للرد عند إعطاء نوع محتواه. (أضيف مع الإصدار: 1.5).

contentType

قيمة منطقيَّة أو سلسلة نصية تحدِّد نوع محتوى البيانات المرسلة إلى الخادم، وقيمته الافتراضيَّة هي "application/x-www-form-urlencoded; charset=UTF-8" التي تناسب أغلب الحالات. إن مرَّرت نوع البيانات إلى ‎$.ajax()‎ بشكل صريح، فسيُرسل إلى الخادم حينئذٍ حتى لو لم يكن هنالك بيانات لإرسالها. بدءًا من الإصدار jQuery 1.6، يمكن تمرير القيمة false لإخبار jQuery بعدم ضبط أية ترويسة لنوع البيانات.

ملاحظة: أوصى المعيار W3C XMLHttpRequest باستعمال ترميز المحارف UTF-8 دومًا. لن يجبر تحديد ترميز آخر للمحارف المتصفح على تغيير الترميز.

ملاحظة: في الطلبات العابرة للنطاق، اضبط نوع المحتوى إلى أي نوع آخر باستثناء القيمة application/x-www-form-urlencoded أو القيمة multipart/form-data أو القيمة text/plain التي تجبر المتصفح على إرسال طلب preflight OPTIONS إلى الخادم.

context

كائن مجرد يمثل محتوى جميع ردود النداء المتعلقة بالنوع Ajax. المحتوى هو كائن يمثل إعدادات Ajax المستعملة في الاستدعاء افتراضيًّا (يُدمج ‎$.ajaxSettings مع الإعدادات الممرَّرة إلى ‎$.ajax). على سبيل المثال، سيؤدي تحديد عنصر DOM كمحتوى إلى إسناد هذا المحتوى إلى دالة رد النداء complete للطلب كما موضح في المثال التالي:

$.ajax({
  url: "test.html",
  context: document.body
}).done(function() {
  $( this ).addClass( "done" );
});
converters

كائن مجرَّد يحتوي على محولات أنواع البيانات (dataType-to-dataType)، إذ تمثِّل كلُّ قيمة محوِّل دالةً تعيد القيمة المحولة للرد. القيمة الافتراضيَّة هي ‎{"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML}‎. (أضيف مع الإصدار: 1.5).

crossDomain

قيمة منطقيَّة، وقيمته الافتراضيَّة هي false من أجل طلبات من نفس النطاق (same-domain) و true من أجل الطلبات اعلابرة للنطاقات (cross-domain).

إن أردت إجبار الطلب على عبور النطاق (crossDomain request) مثل JSONP في نفس النطاق، فغير قيمة هذا الضبط إلى true؛ هذا سيسمح للخادم بإعادة توجيه الطلب مثلًا إلى نطاق آخر. (أضيف مع الإصدار: 1.5).

data

كائن مجرَّد أو سلسلة نصية أو مصفوفة تمثل البيانات المراد إرسالها إلى الخادم. تحول البيانات إلى سلسلة إستعلامات نصية إن لم تعطَ بشكل سلسلة نصية، وتضاف إلى عنوان URL في طلبات GET. انظر الضبط processData إن أردت منع هذه العملية التلقائية.

إن أعطي هذا الضبط على شكل كائن، فيجب أن يكون أزواجًا من مفتاح/قيمة. أمَّا إن أعطي على شكل مصفوفة، فسترمِّز jQuery عدَّة قيم بنفس المفتاح بناءً على قيمة الضبط traditional (تجده في الأسفل).

dataFilter

دالة من الشكل Function( String data, String type )‎ تعيد أي شيء، وتُستعمَل لمعالجة بيانات الرد الصرفة للكائن XMLHttpRequest. تُجرِي هذه الدالة عمليَّة ترشيح مسبقة لبيانات الرد وكأنها تنظِّف وتعقِّم تلك البيانات قبل أن تعيدها إليك. تقبل الدالة وسيطين هما: البيانات الصرفة المعادة من الخادم، والمعامل dataType.

dataType

سلسلة نصية تمثل نوع البيانات التي تتوقع أن تُعاد من الخادم. إن لم يحدَّد أي نوع، فستحاول jQuery أن تخمِّن نوع البيانات بالاعتماد على نوع MIME للرد (سيعطي النوع XML في MIME مثلًا القيمة XML، وسينتج النوع JSON في الإصدار 1.4 كائن JavaScript، وسيؤدي النوع script إلى تنفيذ الشيفرة المعادة في الإصدار 1.4، وسيعاد أي شيء آخر كسلسلة نصية). القيمة الافتراضيَّة لهذا الضبط هي Intelligent Guess (xml, json, script, or html)‎. الأنواع المتاحة (مُرِّرت النتيجة التي ستُمرَّر كأوّل وسيط لدالة رد النداء) هي:

  • "XML": يعاد مستند XML يمكن أن تعالجه jQuery.
  • "html" يعاد محتوى HTML كنص عادي، وتنفَّذ الشيفرة الموجودة ضمن عناصر <script> عند إضافتها إلى DOM.
  • "script": يُعدُّ الرد على أنَّه شيفرة JavaScript، ويعاد كنص عادي. يفضل تعطيل التخزين (caching) بإضافة معامل سلسلة الاستعلام النصية ‎_=[TIMESTAMP]‎ إلى الرابط URL إلا إذا غُيِّرت قيمة الضبط cache إلى القيمة true. ملاحظة: سيحول هذا النوع الطلبات POST إلى GET من أجل الطلبات ذات النطاق البعيد (remote-domain requests).
  • "json": يُعدُّ الرد على أنَّه JSON، ويعاد ككائن JavaScript. تنفَّذ طلبات "json" العابرة للنطاقات (Cross-domain ) التي تملك دالة رد نداء نائبة (callback placeholder)، مثل ‎?callback=?‎، باستعمال JSONP ما لم يحتوي الطلب على القيمة jsonp: false المعطاة لضبط إعداداته. تحلَّل بيانات JSON بأسلوب دقيق وصارم، إذ يُرفَض أي جزء مشوه من JSON ويطلق خطأ عند التحليل. بدءًا من الإصدار jQuery 1.9، سيرفض الرد الفارغ أيضًا، إذ يجب على الخادم أن يعيد ردًا يحوي null أو {} على الأقل. (تصفح هذا القسم للمزيد من المعلومات حول تنسيق JSON الصحيح).
  • "jsonp": يحمَّل الرد المعاد في كتلة JSON باستعمال JSONP. أضف العبارة ?callback=? إلى نهاية العنوان URL لتحديد رد النداء. يفضل تعطيل التخزين (caching) بإضافة معامل سلسلة الاستعلام النصية ‎_=[TIMESTAMP]‎ إلى الرابط URL إلا إذا غُيِّرت قيمة الضبط cache إلى القيمة true.
  • "text": سلسلة نصية تحتوي على نص عادي (plain text).
  • بدءًا من الإصدار jQuery 1.5، أصبح بإمكان jQuery تحويل نوع البيانات dataType من النوع التي استقبلته والمحدد في ترويسة نوع المحتوى (Content-Type header) إلى أي نوع تحتاجه عبر تمرير قيم متعددة مفصولة بفراغ لهذا الضبط. إن أردت مثلًا أن يعامل رد نصي على أنَّه XML، فاستعمل القيمة "text xml" مع الضبط dataType ببساطة. يمكنك أيضًا أن تجعل رد JSONP يعاد كنص ويفسر من قبل jQuery على أنَّه XML من خلال استعمال "jsonp text xml". بطريقة مشابهة، يمكن اختزال السلسلة النصية إلى "jsonp xml" عوضًا عن ذلك، إذ ستجرى محاول حينئذٍ للتحويل من jsonp إلى xml. إن فشلت هذه العمليَّة، فسيحول من jsonp إلى text ثمَّ من text إلى xml.
error

دالة من الشكل Function( jqXHR jqXHR, String textStatus, String errorThrown )‎ تستدعى عند فشل الطلب. تقبل هذه الدالة ثلاثة وسائط هي: كائن jqXHR (في الإصدار jQuery 1.4.x، يكون XMLHttpRequest)، وسلسلة نصية تصف نوع الخطأ الذي حصل، سلسلة نصية اختيارية تحتوي تمثيلًا نصيًا لرسالة الخطأ. القيم المتاحة للوسيط الثاني (بجانب القيمة null) هي: "timeout"، و "error"، و "abort"، و "parsererror". عند حصول خطأ HTTP، يتلقى الوسيط errorThrown الجزء النصي المتعلق بحالة HTTP مثل الجزء "Not Found" أو "Internal Server Error".

بدءًا من الإصدار jQuery 1.5، أًصبح بإمكان الضبط error قبول مصفوفة من الدوال، إذ ستستدعى تلك الدوال على التوالي. تُعدُّ هذه الدالة أو الدوال حدثًا من أحداث Ajax.

ملاحظة: لا يستدعى معالج الحدث هذا مع السكربت العابر للنطاق والطلب JSONP العابر للنطاق أيضًا.

global

قيمة منطقيَّة (Boolean) تحدِّد إن كان يسمح باستدعاء معالجات الحدث Ajax العامة مع الطلب حينئذ. القيمة الافتراضية هي true وعند تغييرها إلى القيمة false، ستُمنَع معالجات الحدث العامة -مثل ajaxStart أو ajaxStop- من استدعائها. هذا الضبط مفيد، إذ يستعمل للتحكم بمختلف أحداث Ajax.

hearders

كائن يتكون من أزواج من مفتاح/قيمة تمثل ترويسات إضافيَّة يراد إرسالها مع الطلبات باستعمال XMLHttpRequest. تضاف الترويسة X-Requested-With: XMLHttpRequest دومًا ولكن يمكن تغيير قيمتها الافتراضيَّة XMLHttpRequest هنا. يمكن أن تستبدل القيم في الضبط headers عبر استعمال دالة الضبط beforeSend. القيمة الافتراضيَّة هي {}. (أضيف مع الإصدار: 1.5).

ifModified

قيمة منطقيَّة تسمح للطلب بأن يكون ناجحًا إن تغيَّر الرد عن الرد المعاد من آخر طلب، وهذا يتم عبر التحقُّق من ترويسة Last-Modified في HTTP. القيمة الافتراضيَّة هي false وتشير إلى تجاهل الترويسة. في الإصدار jQuery 1.4، يتحقَّق هذا الضبط أيضًا من 'etag' الذي يحدِّده الخادم لتتبع البيانات غير المعدلة.

isLocal

قيمة منطقيَّة (Boolean) تسمح للبيئة الحالية أن يُعترَف بها كبيئة عامة، مثل نظام الملفات (filesystem)، حتى ولو لم تعترف jQuery بها كذلك افتراضيًّا. البروتوكولات التي يعترف بأنَّها عامة حاليًا هي: file، و ‎*-extension، و widget. إن احتجت إلى تعديل هذا الضبط، فينصح بشدة القيام بذلك مرةً واحدةً عبر التابع ‎$.ajaxSetup()‎. القيمة الافتراضيَّة تعتمد على موقع البروتوكول الحالي. (أضيف مع الإصدار: 1.5.1).

jsonp

سلسلة نصية أو قيمة منطقيَّة تُستعمَل لتجاهل اسم دالة رد النداء في طلب JSONP. ستستخدم هذه القيمة عوضًا عن 'callback' في الجزء 'callback=?‎' من سلسلة الاستعلام النصية في العنوان URL. إن استعملنا القيمة {jsonp:'onJSONPLoad'‎} مثلًا، فستكون النتيجة 'onJSONPLoad=?‎' التي تمرَّر إلى الخادم.

بدءًا من الإصدار jQuery 1.5، يؤدي تعيين قيمة الضبط jsonp إلى القيمة false إلى منع jQuery من إضاف السلسلة النصية "‎?callback" إلى العنوان URL أو محاول استعمال "‎=?‎‎" للتحويل. في هذه الحالة، يجب عليك تعيين قيمة الضبط jsonpCallback بشكل صريح مثل { jsonp: false, jsonpCallback: "callbackName"‎ }. إن لم تكن واثقًا من الذي أرسل إليه طلبات Ajax، فغيِّر قيمة الضبط jsonp إلى false لزيادة الحماية.

jsonpCallback

سلسلة نصية أو دالة من الشكل Function()‎ تعيد سلسلة نصية تحدِّد اسم دالة رد النداء لطلب JSONP. ستسخدم هذه القيمة عوضًا عن الاسم العشوائي الذي تولِّده jQuery تلقائيًا. الأفضل أحيانًا أن ندع jQuery تولد اسمًا فريدًا، إذ ستسهِّل بذلك علينا إدارة الطلبات بتوفير دوال رد نداء ومعالجات للأخطاء. قد تحتاج إلى تحديد دالة رد النداء عندما تريد تفعيل تخزين الطلبات GET في المتصفح.

بدءًا من الإصدار jQuery 1.5، يمكنك أيضًا استعمال دالةً مع هذا الضبط والتي تضبط قيمته حينئذٍ إلى القيمة التي تعيدها.

method

سلسلة نصية تحدِّد طريقة الإرسال عبر HTTP (أي HTTP method) التي ستستعمل مع الطلب مثل "POST" أو "GET" أو "PUT". (أضيف مع الإصدار: 1.9.0).

mimeType

سلسلة نصية تمثل نوع MIME الذي سيحل محل النوع XHR. (أضيف مع الإصدار: 1.5.1).

password

سلسلة نصية تمثل كلمة المرور المراد استعمالها مع الكائن XMLHttpRequest عند الرد على طلب المصادقة HTTP للسماح بالوصول.

processData

قيمة منطقيَّة. ستعالج البيانات الممرَّرة إلى الضبط data ككائن (أي شيء خلاف سلسلة نصية) وتحوَّل إلى سلسلة استعلام نصية افتراضيًّا بما يتناسب مع نوع المحتوى الافتراضي "application/x-www-form-urlencoded". إن أردت إرسال DOMDocument أو أية بيانات دون معالجتها، فغيِّر قيمة هذا الضبط إلى false.

scriptCharset

سلسلة نصية. يطبق هذا الضبط عند نقل السكربتات (مثل الطلبات العابرة للنطاق مع تعيين القيمة "script" أو القيمة "jsonp" للضبط dataType والقيمة "GET" للضبط Method) بضبط قيمة الخاصِّيَّة charset في العنصر <script> إلى القيمة نفسها المعيَّنة في الطلب. هذا الضبط مفيد، إذ يستعمل عندما يختلف ترميز المحارف في الصفحة الحالية عن الترميز المحدَّد في السكربت البعيد.

statusCode

كائن يحتوي على رموز HTTP الرقمية والدوال التي يراد استدعاؤها عندما يعيد الرد رمزًا مقابلًا لها. على سبيل المثال، ستُظهِر الشيفرة التالية تنبيهًا عندما يكون رمز حالة الرد المعاد هي 404:

$.ajax({
  statusCode: {
    404: function() {
      alert( "لم يعثر على الصفحة" );
    }
  }
});

إن نجح الطلب، فستأخذ دوال رمز الحالة المعاملات نفسها التي تأخذها دالة رد النداء الناجحة. أما إن حصل خطأ وأعيدت نتيجة هذا الخطأ (من ضمنها إعادة التحويل 3xx)، فستأخذ تلك الدوال المعاملات نفسها الممررة إلى رد النداء error. (أضيف مع الإصدار: 1.5).

success

دالة من الشكل Function( Anything data, String textStatus, jqXHR jqXHR )‎ تستدعى إن نجح الطلب. تقبل هذه الدالة أن يمرر إليها ثلاثة وسائط هي: البيانات المعادة من الخادم منسقةً وفقًا لقيمة الضبط dataType أو دالة رد النداء dataFilter إن أعطيت، وسلسلة نصية تصف حالة الطلب، والكائن jqXHR (في الإصدار jQuery 1.4.x يكون XMLHttpRequest).

بدءًا من الإصدار jQuery 1.5، أصبح الضبط success يقبل مصفوفة من الدوال.

تُعدُّ هذه الدالة أو الدوال حدثًا من أحداث Ajax.

timeout

عددًا يمثل زمن انتهاء مهلة الطلب وواحدته ميلي ثانية. القيمة 0 تعني أنه لا يوجد مهلة لانتظار الطلب بعد إرساله. تعيين قيمة لهذا الضبط سيؤدي إلى إهمال أي مهلة زمنية عامة ضبطت باستعمال ‎$.ajaxSetup()‎. يبدأ حساب المهلة الزمنية لحظة استدعاء ‎$.ajax. إن كان هنالك طلبات أخرى قيد الإرسال ولم يكن هنالك اتصالٌ متوافر للمتصفح، فمن المحتمل أن تنفد المهلة الزمنية المحددة للطلب حتى قبل أن يرسل.

في الإصدار jQuery 1.4.x وما قبله، انتبه إلى أنه لن يعود الكائن XMLHttpRequest صالحًا إن نفدت المهلة الزمنية المحدَّد للطلب.

الوصول إلى أحد عناصر كائنٍ قد يؤدي إلى رمي استثناءٍ.

في المتصفح Firefox 3.0+‎ فقط، لا تُلغى طلبات السكربتات وطلبات JSONP عند نفاد المهلة الزمنية، إذ سيعمل السكربت آنذاك حتى لو وصل بعد نفاد الوقت.

traditional

قيمة منطقية (Boolean). هذا الضبط مفيد في حال أردت استعمال النمط التقليدي لترميز المعاملات (param serialization).

type

يعدُّ هذا الضبط اسمًا بديلًا للضبط method. يجب عليك استعماله إن كنت تستخدم إصدارًا ما قبل jQuery 1.9.0. القيمة الافتراضيَّة هي 'GET'.

url

سلسلة نصية تحتوي على العنوان URL الذي سيرسل إليه الطلب. القيمة الافتراضيَّة له هي عنوان الصفحة الحالية.

username

سلسلة نصية تمثل اسم المستخدم الذي سيستعمل مع الكائن XMLHttpRequest عند الرد على طلب المصادقة HTTP للسماح بالوصول.

xhr

دالة من الشكل Function()‎ تمثل دالة رد النداء (callback) المراد استعمالها لإنشاء الكائن  XMLHttpRequest. القيمة الافتراضيَّة هي الكائن ActiveXObject إن كان ذلك متاحًا (في المتصفح IE)، أو الكائن XMLHttpRequest خلاف ذلك. يمكنك استعمال هذا الضبط لاستعمال نسخة بديلة عن الكائن XMLHttpRequest بالشكل الذي تريده أو يمكن تجاهل هذه الميزة والاستفادة من الإعدادات الافتراضيَّة.

xhrFields

كائن يحتوي على أزواجٍ من «اسم المجال/قيمة المجال» التي تضبط خاصيات الكائن XHR الأساسي. على سبيل المثال، يمكنك استعمال هذا الضبط لتعيين القيمة true إلى withCredentials للطلبات العابرة للنطاق إن احتجت إلى ذلك.

$.ajax({
   url: a_cross_domain_url,
   xhrFields: {
      withCredentials: true
   }
});

في الإصدار jQuery 1.5، لم تنتشر (propagate) الخاصِّيَّة withCredentials إلى الكائن XHR الأساسي، لذا ستتجاهل الطلبات CORS التي تحتاج لها هذه الراية (flag)؛ ولهذا السبب، ينصح بشدة استعمال الإصدار jQuery 1.5.1 وما بعده التي توجب استعمال تلك الخاصِّيَّة. (أضيف مع الإصدار: 1.5.1).

ترتكز جميع طلبات Ajax المرسلة باستعمال jQuery على الدالة ‎$.ajax()‎. ليس هنالك داعٍ في أغلب الأحيان إلى استدعاء هذه الدالة مباشرةً، إذ تتوافر بدائل عديدة ذات مستوى أعلى (higher-level) من الأسهل استعمالها مثل الدالة ‎$.get()‎ والتابع ‎.‎load()‎ وغيرها. كلما قل استعمال الخيارات والإعدادات المطلوب ضبطها، كان استعمال الدالة ‎$.ajax()‎ أسهل وأكثر مرونة.

أبسط شكل لاستعمال الدالة ‎$.ajax()‎ هو استدعاؤها دون أية وسائط مثل:

$.ajax();

ملاحظة: يمكن ضبط الإعدادات وجعلها افتراضيَّة على الصعيد العام باستعمال الدالة ‎$.ajaxSetup()‎.

في هذا المثال، يؤدي استعمال الدالة دون أية وسائط إلى تحميل محتويات الصفحة الحالية ولكن لن يفعل أي شيء بالناتج الذي نحصل عليه. للاستفادة من الناتج، يمكنك تنفيذ إحدى دوال ردود النداء.

الكائن jqXHR

الكائن XMLHttpRequest (أو jqXHR) المعاد باستعمال ‎$.ajax()‎ بدءًا من الإصدار jQuery 1.5 هو مجموعةٌ حاويةٌ (superset) للكائن XMLHttpRequest الأساسي للمتصفح. يحتوي الكائن مثلًا على الخاصِّيَّة responseText والخاصِّيَّة responseXML بالإضافة إلى التابع getResponseHeader()‎. عند اختيار آلية للنقل غير XMLHttpRequest (مثل الوسم <script> للطلب JSONP)، فسيحاكي الكائن jqXHR الكائن XHR الأساسي وظيفيًّا حيث أمكنه ذلك.

بدءًا من الإصدار jQuery 1.5.1، يمكن أن يحتوي الكائن jqXHR على التابع overrideMimeType()‎ أيضًا (كان هذا متاحًا في الإصدار jQuery 1.4.x أيضًا ولكنه أزيل مؤقتًا في الإصدار jQuery 1.5). قد يستعمل التابع overrideMimeType()‎ في دالة رد النداء beforeSend()‎ لتعديل ترويسة نوع المحتوى (content-type header) للرد مثلًا:

$.ajax({
  url: "https://fiddle.jshell.net/favicon.png",
  beforeSend: function( xhr ) {
    xhr.overrideMimeType( "text/plain; charset=x-user-defined" );
  }
})
  .done(function( data ) {
    if ( console && console.log ) {
      console.log( "Sample of data:", data.slice( 0, 100 ) );
    }
  });

تنفِّذ (implement) الكائنات jqXHR المعادة عن طريق ‎$.ajax()‎ بدءًا من الإصدار jQuery 1.5 الواجهة Promise بإعطائها جميع الخاصيات، والتوابع، وسلوك Promise (ارجع إلى توثيق الكائن Deferred للمزيد من المعلومات). تأخذ هذه التوابع دالة واحدة أو أكثر كوسائط التي تستدعى عندما ينتهي طلب ‎$.ajax()‎. يسمح لك هذا بإسناد ردود نداء متعدِّدة في طلب وحيد وحتى إسناد ردود نداء بعد أن يكون الطلب قد اكتمل. (إن اكتمل الطلب مسبقًا، فسيُطلق رد النداء مباشرةً). هنالك عدة توابع Promise متاحة لاستعمالها مع الكائن jqXHR من ضمنها:

  • jqXHR.done(function( data, textStatus, jqXHR ) {});‎ شكلٌ آخرٌ لإنشاء دالة رد النداء للضبط success. ارجع إلى صفحة التابع deferred.done()‎ للاطلاع على مزيد من التفاصيل حول كيفية التنفيذ.
  • jqXHR.fail(function( jqXHR, textStatus, errorThrown ) {});‎ شكلٌ آخرٌ لإنشاء دالة رد النداء للضبط error، إذ حل التابع ‎.‎fail()‎ مكان التابع ‎.error()‎ المهمل. ارجع إلى صفحة التابع deferred.fail()‎ للاطلاع على المزيد من التفاصيل حول كيفية التنفيذ.
  • jqXHR.always(function( data|jqXHR, textStatus, jqXHR|errorThrown ) { });‎ (أضيف مع الإصدار: 1.6) شكلٌ آخرٌ لإنشاء دالة رد النداء للضبط complete، إذ حل التابع ‎.always()‎ مكان التابع ‎.complete()‎ المهمل. عند الرد على طلب ناجح، تكون وسائط الدالة مماثلة تمامًا لوسائط التابع ‎.done()‎ وهي: السلسلة النصية data، والسلسلة النصية textStatus، والكائن jqXHR. أمَّا في حالة فشل الطلب، ستكون الوسائط نفسها الوسائط الممررة إلى التابع ‎.fail()‎ وهي: الكائن jqXHR، والسلسلة النصية textStatus، والسلسلة النصية errorThrown. ارجع إلى صفحة التابع deferred.always()‎ للاطلاع على المزيد من التفاصيل حول كيفية التنفيذ.
  • jqXHR.then(function( data, textStatus, jqXHR ) {}, function( jqXHR, textStatus, errorThrown ) {});‎ مزيجٌ لوظيفة التابع ‎.done()‎ والتابع ‎.fail()‎، إذ يسمح (بدءًا من الإصدار jQuery 1.8) بتعديل الكائن Promise. ارجع إلى التابع deferred.then()‎ للاطلاع على المزيد من التفاصيل حول كيفية التنفيذ.

ملاحظة: حذفت دوال ردود النداء jqXHR.success()‎، و jqXHR.error()‎، و jqXHR.complete()‎ بدءًا من الإصدار 3.0. يمكنك استعمال jqXHR.done()‎، و jqXHR.fail()‎، و jqXHR.always()‎ عوضًا عنها.

// إسناد معالجات أحداثٍ بعد إنشاء الطلب مباشرةً ,
// لهذا الطلب jqXHR وحفظ الكائن
var jqxhr = $.ajax( "example.php" )
  .done(function() {
    alert( "تم بنجاح" );
  })
  .fail(function() {
    alert( "حصل خطأ" );
  })
  .always(function() {
    alert( "اكتمل بنجاح" );
  });
 
// أنجز أعمالًا أخرى هنا
 
//  أخرى للطلب complete تعيين دالة
jqxhr.always(function() {
  alert( "اكتمل مرة أخرى بنجاح" );
});

يشير this ضمن جميع دوال ردود النداء إلى الكائن المعطى في الوسيط context الممرَّر إلى ‎$.ajax()‎ مع الإعدادات settings المعطاة. إن لم يعطَ المعامل context، فسيشر this إلى الإعدادات settings نفسها.

لتحقيق التوافقيَّة الرجوعيَّة (backward compatibility) مع الكائن XMLHttpRequest، سيعرض الكائن jqXHR الخاصِّيَّات والتوابع التالية:

  • readyState
  • responseXML و/أو responseText عندما يُرَدُّ على الطلب الأساسي بإعادة مستند XML و/أو text على التوالي.
  • status
  • statusText
  • abort( [ statusText ] )‎
  • getAllResponseHeaders()‎ كسلسلة نصية.
  • getResponseHeader( name )‎
  • overrideMimeType( mimeType )‎
  • setRequestHeader( name, value )‎ التي اشتقت من المعيار القياسي مع تبديل القيمة الجديد مكان القيمة القديمة بدلًا من ربط القيمة الجديدة بالقيمة القديمة.
  • statusCode( callbacksByStatusCode )‎

لا تتوافر الآلية onreadystatechange، إذ تغطي التوابع done، و fail، و always، و statusCode كل ما يمكن أن تتخيله.

طوابير دوال ردود النداء

تقبل الإعدادات beforeSend، و error، و dataFilter، و success جميعها دوال ردود نداء والتي تُستدعَى في الأوقات الملائمة.

بدءًا من الإصدار jQuery 1.5، يمكن أن تدار خطافات (hooks) دوال النداء fail، و done، و always -بدءًا من الإصدار jQuery 1.6- باستعمال طوابير من النوع "أدخل أولًا وأخرج أولًا" (first-in first-out queues أو اختصارًا fifo queues)، إذ يسمح ذلك بربط أكثر من دالة رد نداء بخطاف. انظر إلى توابع الكائن Deferred التي تنفَّذ داخليًا لخطافات دوال ردود النداء ‎$.ajax()‎ هذه.

خطافات دوال ردود النداء التي تتيحها ‎$.ajax‎()‎ هي كما يلي:

  1. دالة رد النداء للضبط beforeSend. تقبل أن يمرَّر  إليها الكائن jqXHR والكائن settings كوسائط.
  2. دالة رد النداء للضبط error وتستدعى إن فشل الطلب. تقبل أن يمرَّر إليها الكائن jqXHR، وسلسلة نصية تشير إلى نوع الخطأ، وكائن استثنائي إن أمكن. ستوفِّر بعض الأخطاء المضمَّنة سلسلة نصية تمثل كائنًا استثنائيًّا مثل "abort" أو "timeout" أو "No Transport".
  3. دالة رد النداء للضبط dataFilter وتستدعى عند نجاح استلام بيانات الرد. تقبل أن يمرَّر إليها البيانات المعادة وقيمة dataType ويجب أن يعيد البيانات (المحتمل أنها تغيرت) لتمريرها إلى success.
  4. دالة رد النداء للضبط success وتستدعى إن نجح الطلب. تقبل أن يمرَّر إليها البيانات المعادة، وسلسلة نصية تحتوي على رمز نجاح العمليَّة، والكائن jqXHR.
  5. دوال ردود النداء Promise وهي: ‎.done()‎، و ‎.fail()‎، و ‎.always()‎، و ‎.then()‎ وتستدعى وفقًا للترتيب الذي سجلت فيه.
  6. دالة رد النداء للضبط complete وتستدعى عند انتهاء الطلب سواءً كان هذا الطلب ناجحًا أم فاشلًا. تقبل أن يمرَّر إليها الكائن jqXHR بالإضافة إلى سلسلة نصية تحتوي على رمز نجاح أو فشل الطلب.

أنواع البيانات

تتعلق أنواع الردود المختلفة لاستدعاء الدالة ‎$.ajax()‎ بمختلف أنواع العمليات التي أجريت مسبقًا قبل أن تمرَّر إلى معالج الحدث success. يعتمد نوع تلك العمليات افتراضيًّا على نوع محتوى الرد ولكن يمكن ضبط ذلك صراحةً باستعمال الضبط dataType. إن أعطيت قيمة الضبط dataType، فستُهمَل ترويسة نوع المحتوى (Content-Type header) للرد.

أنواع البيانات المتاحة هي: text، و html، و xml، و json، و jsonp، و script.

إن حُدِّد النوع text أو html، فلن تحدث أية عمليات معالجة مسبقة. تمرَّر البيانات ببساطة إلى المعالج success، ثمَّ تصبح متاحةً بعدئذٍ عبر الخاصِّيَّة responseText للكائن jqXHR.

إن حُدِّد النوع xml، فسيحلَّل الرد باستعمال jQuery.parseXML قبل أن يمرَّر ككائن مستند XMLDocument إلى معالج الحدث success. يصبح المستند XML متاحًا عبر الخاصِّيَّة responseXML للكائن jqXHR.

إن حُدِّد النوع json فسيحلَّل الرد باستعمال jQuery.parseJSON قبل أن يمرر ككائن إلى معالج الحدث success. يصبح الكائن JSON متاحًا عبر الخاصِّيَّة responseJSON للكائن jqXHR.

إن حُدِّد النوع script، فستنفِّذ الدالة ‎$.ajax()‎ السكربت الذي تستلمه من الخادم قبل أن تمرِّره إلى معالج الحدث success كسلسلة نصية.

أما إن حُدِّد النوع jsonp، فستضيف ‎$.ajax()‎ تلقائيًّا للمعامل سلسلة الاستعلام النصية callback=?‎ (الافتراضي) إلى العنوان URL. يمكن استعمال الخاصِّيَّة jsonp والخاصِّيَّة jsonpCallback للإعدادات settings الممررة إلى ‎$.ajax()‎ لتحديد اسم معامل سلسلة الاستعلام النصية واسم دالة رد النداء JSONP على التوالي. يجب أن يعيد الخادم سكربتًا صحيحًا يمرر الرد JSON إلى دالة رد النداء. ستنفِّذ الدالة ‎$.ajax()‎ ذلك السكربت المعاد باستدعاء دالة رد النداء JSONP قبل تمرير الكائن JSON الذي يحتوي على الرد إلى معالج الحدث success للدالة ‎$.ajax()‎.

للمزيد من المعلومات حول JSONP، يمكنك الرجوع إلى هذا المقال.

إرسال البيانات إلى الخادم

ترسل طلبات Ajax افتراضيًّا عبر HTTP باستعمال طريقة GET. إن دعت الحاجة إلى استعمال طريقة POST، فيمكن تغيير الطريقة المستعملة بضبط قيمة الوسيط type في الإعدادات settings إلى هذه الطريقة، إذ يحدِّد هذا الوسيط كيفية إرسال محتوى الوسيط data إلى الخادم. سينقل المحتوى إلى الخادم عند تحديد الطريقة POST باستعمال الترميز UTF-8، إذ ذلك ما نص عليه المعيار W3C XMLHTTPRequest.

يمكن أن يحوي الضبط data إمَّا سلسلة استعلام نصية من النموذج key1=value1&key2=value2، أو كائنًا من النموذج {key1: 'value1', key2: 'value2'‎}. إن استُعمل النموذج الأخير، فستُحول البيانات إلى سلسلة استعلام نصية باستعمال jQuery.param()‎ قبل أن تُرسل. يمكن التحايل على هذه العملية بتغيير قيمة الضبط processData إلى false، إذ قد تكون هذه العملية غير مرغوب فيها خصوصًا إن أردت إرسال كائن XML إلى الخادم. في هذه الحالة، غيِّر قيمة الضبط contentType من النوع application/x-www-form-urlencoded إلى نوع MIME أكثر ملائمةً.

خيارات متقدمة

يمنع الضبط global معالجات الأحداث المسجلة باستعمال التابع ‎.ajaxSend()‎، والتابع ‎.ajaxError()‎، وتوابع أخرى مشابهة من أن تُطلق عندما يستدعيها الطلب. يمكن أن يكون هذا مفيدًا لإخفاء مؤشر التحميل مثلًا الذي نُفِّذ مع ‎.ajaxSend()‎ إن كانت الطلبات متكررة وموجزة. تتغير قيمة الضبط global إلى false تلقائيًّا مع السكربت العابر للنطاق (cross-domain script) والطلبات JSONP. انظر إلى شرح هذه التوابع في الأسفل للمزيد من التفاصيل.

إن أراد الخادم أن يجري مصادقةً قبل أن يرسل ردًا، فيمكن حينذاك إرسال اسم المستخدم وكلمة المرور بوساطة الضبط username والضبط password.

إن طلبات Ajax محدودةٌ بزمنٍ، لذا يمكن التعرف على الأخطاء ومعالجتها لتحسين تجربة المستخدم (user experience). قيمة المهلة الزمنية للطلب هي غالبًا إمَّا القيمة الافتراضيَّة الأساسية أو القيمة المعيَّنة كقيمة افتراضيَّة باستعمال ‎$.ajaxSetup()‎، فقد تحتاج أحيانًا إلى تجاهل هاتين القيمتين لطلبات محددة باستعمال الضبط timeout.

يرسل الطلب دومًا افتراضيًّا ولكن المتصفح قد يخزِّن النتيجة المرتبطة به. إن أردت منع تخزين نتيجة الطلبات، فغيِّر قيمة الضبط cache إلى false. أمَّا إن أردت أن يُبلِّغ الطلب عن حالة الفشل عندما لا يتغير فحوى الرد عن الطلب السابق، فغيِّر قيمة الضبط ifModified إلى true.

يساعد الضبط scriptCharset بتحديد ترميز المحارف للطلبات التي تستعمل الوسم <script> ضمنها (مثل الطلبات ذات النوع script والنوع jsonp). هذا الضبط مفيدُ جدًا في حال اختلاف الترميز المستعمل في السكربت عن نظيره المستعمل في الصفحة المستضيفة.

ذُكر في بداية هذا التوثيق، في قسم الوصف تحديدًا، أنَّ هذه الدالة ترسل طلبًا بشكل غير متزامن، إذ تشير العبارة "غير متزامن" إلى أنَّ عمليَّة الإرسال تحدث على التوازي وليس هنالك أي ضمان لإكمال تنفيذ العملية وفقًا لترتيب ما. القيمة الافتراضيَّة للضبط async هي true وهذا يعني أن تنفيذ الشيفرة قد يستمر بعد اكتمال إرسال الطلب. ينصح بشدة عدم تعيين قيمة هذا الضبط إلى false، إذ تصبح حينئذٍ العملية متزامنة ويمكن أن تؤدي إلى خروج المتصفح عن الاستجابة.

تنشئ الدالة ‎$.ajax()‎ الكائن XMLHttpRequest ثمَّ تعيده. تسهم jQuery في عملية معالجة وإنشاء هذا الكائن داخليًا وبشكل طبيعي ولكن يمكن أيضًا تحديد دالة مخصَّصة لإنشاء هذا الكائن باستعمال الضبط xhr. يمكن التخلص هذا الكائن المعاد بسهولة إلا أنَّه يوفر واجهة منخفضة المستوى (lower-level interface) لمراقبة وتعديل الطلب. سيؤدي استدعاء التابع ‎.abort()‎ بالتحديد مع الكائن XMLHttpRequest إلى مقاطعة الطلب وإلغائه قبل أن يكتمل.

Ajax الموسّعة

بدءًا من الإصدار jQuery 1.5، أصبح تنفيذ Ajax في jQuery يتضمن المرشحات المسبقة (prefilters) والنواقل (transports)، والمحولات (converters) التي توسِّع Ajax بتوفير قدر كبير من المرونة.

استعمال المحولات

تدعم المحولات في ‎$.ajax()‎ تعيين (mapping) أنواع بيانات إلى أنواع بيانات أخرى. إن أردت تعيين نوع بيانات مخصَّص إلى نوع معروف (مثل json)، فيجب أن تضيف رابطًا يوافق بين نوع محتوى الرد ونوع البيانات الفعلي باستعمال الضبط contents:

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "mycustomtype json": function( result ) {
      // افعل شيئًا هنا
      return newresult;
    }
  }
});

هذا الكائن الإضافي ضروري جدًا لأنَّ نوع محتوى الرد وأنواع البيانات لا تتطابق مطلقًا (وبالتالي يُعتمد على التعابير النمطية). للتحويل من نوع مدعوم (مثل text أو json) إلى نوع بيانات مخصَّص والتحويل بالعكس أيضًا، استعمل المحولات الممرَّرة (pass-through converter) الأخرى:

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "text mycustomtype": true,
    "mycustomtype json": function( result ) {
      // افعل شيئًا هنا
      return newresult;
    }
  }
});

تسمح لنا هذه الشيفرة بالتحويل من text إلى mycustomtype ثمَّ من mycustomtype إلى json.

ملاحظات إضافية

  • بسبب القيود الأمنية للمتصفحات، فإنَّ أغلب طلبات "Ajax" تخضع إلى سياسة المصدر الواحد (Same origin policy). لن يتمكن الطلب آنذاك من جلب البيانات بنجاح من نطاقات أو نطاقات فرعية أو منافذ أو بروتوكولات مختلفة.
  • لا يخضع الطلب script والطلب JSONP إلى قيود سياسة المصدر الواحد.

أمثلة

حفظ بعض البيانات في الخادم وإبلاغ المستخدم عند الانتهاء من العمليَّة:

$.ajax({
  method: "POST",
  url: "some.php",
  data: { name: "محمد", location: "سوريا" }
})
  .done(function( msg ) {
    alert( "حُفظت البيانات: " + msg );
  });

إستعادة أحدث إصدار من صفحة HTML:

$.ajax({
  url: "test.html",
  cache: false
})
  .done(function( html ) {
    $( "#results" ).append( html );
  });

إرسال مستند xml كبيانات إلى الخادم. سيؤدي تعيين قيمة الضبط processData إلى false إلى منع تحويل البيانات إلى سلسلة نصية تلقائيًّا:

var xmlDocument = [create xml document];
var xmlRequest = $.ajax({
  url: "page.php",
  processData: false,
  data: xmlDocument
});
 
xmlRequest.done( handleResponse );

إرسال قيمة الخاصِّيَّة id كبيانات إلى الخادم لحفظها، وإبلاغ المستخدم حال اكتمال أو فشل العملية:

var menuId = $( "ul.nav" ).first().attr( "id" );
var request = $.ajax({
  url: "script.php",
  method: "POST",
  data: { id : menuId },
  dataType: "html"
});
 
request.done(function( msg ) {
  $( "#log" ).html( msg );
});
 
request.fail(function( jqXHR, textStatus ) {
  alert( "فشل الطلب: " + textStatus );

تحميل ملف JavaScript وتنفيذه:

$.ajax({
  method: "GET",
  url: "test.js",
  dataType: "script"
});

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=jQuery/jQuery/ajax&oldid=11611»