jQuery ajax - طريقة ajax()

دليل jQuery Ajax

مثال

من خلال AJAX تحميل قطعة نصية:

كود jQuery:}

$(document).ready(function(){
  $("#b01").click(function(){
  htmlobj=$.ajax({url:"/jquery/test1.txt",async:false});
  $("#myDiv").html(htmlobj.responseText);
  });
});

كود HTML:

<div id="myDiv"><h2>تغيير هذا النص باستخدام AJAX</h2></div>
<button id="b01" type="button">تغيير المحتوى</button>

تجربة شخصية

التعريف والاستخدام

يتم تحميل البيانات البعيدة من خلال طلب HTTP باستخدام دالة ajax().

هذه هي عملية AJAX الأساسية في jQuery. يمكن استخدام إصدارات أعلى المستوى مثل $.get،$.post وما إلى ذلك. $.ajax() تعود XMLHttpRequest الذي أنشأته.

في الحالة الأبسط،يمكن استخدام $.ajax() بدون أي معاملات.

ملاحظة:جميع الخيارات يمكن ضبطها بشكل عامية من خلال دالة $.ajaxSetup().

النحو

jQuery.ajax([settings])
المواضيع الوصف
settings

اختياري. مجموعة من المفاتيح والقيم المستخدمة لتكوين طلب AJAX.

يمكن ضبط القيم الافتراضية لأي خيار من خلال $.ajaxSetup().

المواضيع

options

النوع: Object

اختياري. إعدادات الطلب AJAX. جميع الخيارات اختيارية.

async

نوع: Boolean

القيمة الافتراضية: true. إذا كانت الإعدادات الافتراضية،فجميع الطلبات تكون طلبات غير متزامنة. إذا كنت بحاجة إلى إرسال طلب متزامن،فأضف هذا الخيار على false.

ملاحظة،الطلبات المتزامنة ستجمد المتصفح،ويجب أن ينتظر المستخدم تنفيذ أي عملية أخرى حتى اكتمال الطلب.

beforeSend(XHR)

نوع: Function

يمكن تعديل معامل XMLHttpRequest قبل إرسال الطلب، مثل إضافة رؤوس HTTP مخصصة.

مفردة XMLHttpRequest هي المعامل الوحيد.

هذا هو حدث Ajax. إذا تم عودة false يمكن إلغاء هذه الطلب Ajax.

الذاكرة المؤقتة

نوع: Boolean

القيمة الافتراضية: true،إذا كان dataType هو script و jsonp فإن القيمة الافتراضية تكون false. عند ضبط هذا الخيار على false لن يتم توفير هذه الصفحة.

ميزات جديدة jQuery 1.2.

complete(XHR, TS)

نوع: Function

دالة تلقائية بعد إكمال الطلب (تُدعى بعد نجاح أو فشل الطلب).

المعلمات: Object XMLHttpRequest و string وصف نوع الطلب.

هذا هو حدث Ajax.

contentType

نوع: String

القيمة الافتراضية: "application/x-www-form-urlencoded". نوع الت编码 الذي يتم إرسال المعلومات إليه إلى الخادم.

القيمة الافتراضية تناسب معظم الحالات. إذا تم توفير content-type واضح لـ $.ajax()، فإنه سيتم إرساله إلى الخادم (حتى لو لم يكن هناك بيانات لإرسالها).

context

النوع: Object

يستخدم هذا العنصر لضبط سياق الدوال التلقائية المتعلقة ب Ajax. أي أن يتم توجيه this في الدالة التلقائية إلى هذا العنصر (إذا لم يتم تحديد هذا المعامل، فإن this سيشير إلى معامل options الذي تم توفيره عند استدعاء AJAX هذا). على سبيل المثال، إذا تم تحديد عنصر DOM كمعامل context، فإنه يتم ضبط سياق الدالة التلقائية success لهذا العنصر.

مثل هذا:

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

نوع: String

البيانات التي يتم إرسالها إلى الخادم. سيتم تحويلها تلقائيًا إلى تنسيق سلسلة الطلب. سيتم إضافة إلى URL في طلب GET. راجع وصف خيار processData لتجنب هذا التحويل التلقائي. يجب أن يكون في تنسيق Key/Value. إذا كان مجموعة، ستقوم jQuery بتحويل القيم المختلفة إلى نفس الاسم. مثل {foo:["bar1", "bar2"]} يتم تحويله إلى '&foo=bar1&foo=bar2'.

dataFilter

نوع: Function

وظيفة معالجة مسبقة للبيانات الأصلية التي تعود من Ajax. توفر المعلمات data و type: data هي البيانات الأصلية التي تعود من Ajax، و type هو المعامل dataType الذي تم توفيره عند استدعاء jQuery.ajax. سيتم معالجة القيمة التي تعود من الوظيفة من قبل jQuery.

dataType

نوع: String

نوع البيانات التي يتوقعها الخادم العودة. إذا لم يتم تحديد، ستقوم jQuery بتحديد الذكاء الفذاء بناءً على معلومات MIME HTTP في حزمة HTTP، مثل نوع MIME XML يتم التعرف عليه ك XML. في الإصدار 1.4، سيتم إنشاء JSON كعنصر JavaScript، وسيتم تنفيذ script. بعد ذلك، سيتم تحليل البيانات التي يعودها الخادم بناءً على هذا القيمة، وسيتم نقلها إلى الدالة التلقائية. القيم المتاحة:

  • "xml": عودة وثيقة XML، يمكن معالجتها بواسطة jQuery.
  • "html": عودة معلومات HTML غير منظم؛ يتم تنفيذ علامات script عند إدراجها في DOM.
  • "script": عودة رمز JavaScript غير منظم. لن يتم توفير النتائج تلقائيًا. إلا إذا تم تعيين "cache". ملاحظة: عند الطلب من مسافات بعيدة (ليس في نفس النطاق)، سيتم تحويل جميع الطلبات POST إلى GET. (باستخدام علامة script في DOM).
  • "json": عودة بيانات JSON.
  • "jsonp": صيغة JSONP. عند استدعاء الدالة باستخدام صيغة JSONP، مثل "myurl?callback=?"، سيقوم jQuery بتبديل ? إلى الاسم الصحيح للدالة لتنفيذ الدالة المراجعة.
  • "text": عودة نص غير منظم
error

نوع: Function

القيمة الافتراضية: التحقق تلقائيًا (xml أو html). يتم استدعاء هذه الدالة عند فشل الطلب.

توجد ثلاثة معلمات هنا: عميل XMLHttpRequest، معلومات الخطأ، (اختياري) كائن الاستثناء الم捕获.

إذا حدث خطأ، يمكن أن تكون معلومات الخطأ (الخطوة الثانية) غير null، مثل "timeout", "error", "notmodified" و "parsererror".

هذا هو حدث Ajax.

global

نوع: Boolean

هل يتم تنشيط الأحداث AJAX العالمية. القيمة الافتراضية: true. عند تعيينها إلى false، لن يتم تنشيط الأحداث AJAX العالمية مثل ajaxStart أو ajaxStop التي يمكن استخدامها للتحكم في أحداث Ajax المختلفة.

ifModified

نوع: Boolean

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

jsonp

نوع: String

في طلب jsonp، قم بتعديل اسم الدالة المراجعة. تستخدم هذه القيمة لتعويض جزء "callback" في URL الخاص بطلبات GET أو POST مثل "callback=?"، مثل {jsonp:'onJsonPLoad'} سيؤدي إلى إرسال "onJsonPLoad=?" إلى الخادم.

jsonpCallback

نوع: String

تحديد اسم الوظيفة المرجعية للمطالبة jsonp. هذه القيمة ستستخدم لاستبدال اسم الوظيفة العشوائي الذي يصنعه jQuery. هذا يستخدم أساسًا لإنشاء أسماء وظائف فريدة، مما يجعل إدارة الطلبات أسهل، ويجعل تقديم الوظائف المرجعية والمعالجة الإرشادية أسهل. يمكنك أيضًا تحديد اسم الوظيفة المرجعية هذا عند تريد تثبيت طلب GET لذا كان يمكن أن يُخزن من قبل المتصفح.

password

نوع: String

للإجابة على طلبات التحقق من هوية HTTP بكلمة المرور.

processData

نوع: Boolean

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

scriptCharset

نوع: String

يُستخدم فقط عندما يكون dataType "jsonp" أو "script"، ويكون type "GET" لاضطرار تغيير charset. عادةً ما يستخدم فقط عندما يكون ت编码 المحتوى المحلي والبعيد مختلفًا.

success

نوع: Function

الوظيفة المرجعية بعد إتمام الطلب.

المعلومات: البيانات التي تعود من الخادم، ومعالجتها بناءً على المعامل dataType؛ النصوص الوصفية للحالة.

هذا هو حدث Ajax.

traditional

نوع: Boolean

إذا كنت ترغب في استخدام طريقة تقديم البيانات التقليدية، فأضف الحالة "true". يرجى الرجوع إلى طريقة jQuery.param في فئة الأدوات.

timeout

نوع: Number

ضبط وقت انقضاء الطلب (بالميليسي ثانية). هذه الإعدادات ستعيد كتابة الإعدادات العالمية.

type

نوع: String

القيمة الافتراضية: "GET"). طريقة الطلب ("POST" أو "GET")، بشكل افتراضي "GET". ملاحظة: يمكن استخدام طلبات HTTP الأخرى مثل PUT و DELETE أيضًا، ولكن دعمها محدود في بعض المتصفحات.

url

نوع: String

القيمة الافتراضية: عنوان الصفحة الحالية. عنوان الطلب المرسل.

username

نوع: String

للإجابة على طلبات التحقق من هوية HTTP بالاسم المستخدم.

xhr

نوع: Function

يحتاج إلى العودة بجسم XMLHttpRequest. بشكل افتراضي في IE هو ActiveXObject في الحالات الأخرى هو XMLHttpRequest. يستخدم لإعادة كتابة أو تقديم XMLHttpRequest مكملة. هذا المعامل لم يكن متاحًا في jQuery 1.3.

دوال ال回调

إذا كان من المطلوب معالجة البيانات التي يتم الحصول عليها من $.ajax()، فيجب استخدام دوال ال回调: beforeSend، error، dataFilter، success، complete.

beforeSend

يتم استدعاء هذه الدالة قبل إرسال الطلب، ويتم إرسال XMLHttpRequest كمعامل.

error

يتم استدعاء هذه الدالة عند حدوث خطأ في الطلب. يتم إرسال XMLHttpRequest، وكذلك نص يصف نوع الخطأ، ومثال على الاستثناء (إذا كان موجودًا).

dataFilter

يتم استدعاء هذه الدالة بعد نجاح الطلب. يتم إرسال البيانات المقدمة وكذلك قيمة parameter dataType. ويجب أن يتم إرجاع البيانات الجديدة (قد تكون معالجة) التي يتم نقلها إلى دالة success.

success

يتم استدعاء هذه الدالة بعد الطلب. يتم إرسال البيانات بعد الرد، وكذلك نص يحتوي على رمز النجاح.

complete

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

نوع البيانات

يعتمد دالة $.ajax() على المعلومات التي يقدمها الخادم لمعالجة البيانات المقدمة. إذا كان الخادم يبلغ بأن البيانات المقدمة هي XML، فإن النتائج يمكن استخدامها من خلال طرق XML العادية أو اختيارات jQuery. إذا كان هناك نوع آخر، مثل HTML، يتم التعامل مع البيانات كنص.

من خلال خيار dataType يمكن تحديد طرق معالجة البيانات المختلفة. بالإضافة إلى XML البحت، يمكن تحديد html، json، jsonp، script أو text.

في ذلك، لا يتم معالجة البيانات المقدمة بنوع text و xml. يتم ببساطة نقل property responseText أو responseHTML الخاص ب XMLHttpRequest إلى دالة success.

ملاحظة:يجب علينا التأكد من أن نوع MIME الذي يتم إبلاغه من قبل خادم الويب يتطابق مع dataType الذي اخترناه. على سبيل المثال، إذا كان XML، يجب على الخادم إعلان text/xml أو application/xml للحصول على نتائج متسقة.

إذا تم تحديد نوع html، فإن أي JavaScript مدمج سيتم تنفيذه قبل أن يتم إرجاع HTML كنص. بنفس الطريقة، إذا تم تحديد نوع script، فإن JavaScript المولد على الجانب الخادم سيتم تنفيذه أولاً، ثم سيتم إرجاع النص كبيانات نصية.

إذا تم تحديد النوع على json، فإن البيانات المكتسبة سيتم تحليلها كـ Object JavaScript، وسيتم إرجاع العنصر المكون كنتيجة. من أجل تحقيق هذا الهدف، سيحاول أولاً استخدام JSON.parse(). إذا لم يدعم المتصفح ذلك، فإنه سيستخدم دالة لإنشاء.

بيانات JSON هي نوع من البيانات المقدمة بشكل تنظيمي يمكن تحليلها بسهولة باستخدام JavaScript. إذا كانت ملفات البيانات المكتسبة مخزنة على خادم بعيد (مثل اختلاف النطاقات، أي الحصول على بيانات عبر الحدود الزمنية)، فإنه يجب استخدام نوع jsonp . إذا تم استخدام هذا النوع، سيتم إنشاء معامل سلسلة الاستعلام callback=?، هذا المعامل سيتم إضافته إلى URL الطلب. يجب أن يضيف الجانب الخادم اسم الدالة قبل بيانات JSON لإنشاء طلب JSONP صالح. إذا كنت ترغب في تحديد اسم معامل الدالة البديل عن callback، يمكنك تعيين parameter jsonp في $.ajax().

ملاحظة:JSONP هو توسيع لـ JSON. يتطلب بعض الشيفرة على الجانب الخادم لمراقبة وتعامل مع معاملات سلسلة الاستعلام.

إذا تم تحديد نوع script أو jsonp، فإن البيانات التي يتم استقبالها من الخادم تكون باستخدام علامة <script> بدلاً من Object XMLHttpRequest . في هذه الحالة، لا يعود $.ajax() يعود بـ XMLHttpRequest Object، وسيتم أيضًا نقل الوظائف المعالجة للأحداث مثل beforeSend.

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

بالتشخيص، يستخدم طلب Ajax طريقة GET. إذا كنت ترغب في استخدام طريقة POST، يمكنك تعيين قيمة parameter type . سيفؤثر هذا الخيار أيضًا على كيفية إرسال محتوى خيار البيانات إلى الخادم.

خيار البيانات يمكن أن يحتوي على سلسلة استعلام، مثل key1=value1&key2=value2، أو يمكن أن يكون خريطة، مثل {key1: 'value1', key2: 'value2'} . إذا تم استخدام شكل الأخير، فإن البيانات يتم تحويلها إلى سلسلة استعلام عند إرسالها إلى المرسل. يمكن تجنب هذا التreatment من خلال تعيين خيار processData إلى false . إذا كنا نريد إرسال عنوان XML إلى الخادم، قد لا يكون هذا التreatment مناسبًا. وإذا كان ذلك الحال، يجب أيضًا تغيير قيمة خيار contentType إلى MIME نوع آخر مناسب بدلاً من application/x-www-form-urlencoded .

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

يُستخدم خيار global لمنع التسجيل من التفاعل مع إعدادات الرد، مثل .ajaxSend أو ajaxError أو طرق مشابهة. يكون ذلك مفيدًا في بعض الحالات، مثل إرسال طلبات متكررة ومختصرة، حيث يمكن تعطيل ذلك في ajaxSend.

إذا كان على الخادم إجراء تأكيد HTTP، يمكن استخدام اسم المستخدم وكلمة المرور من خلال خيارات username وpassword.

تكون الطلبات Ajax محددة المدة، لذا يمكن استخدام تحذيرات الأخطاء المكتسبة والمعالجة لتحسين تجربة المستخدم. عادةً، يتم الحفاظ على قيمة المعامل default لـ timeout، أو يمكن تعيينها بشكل عام من خلال jQuery.ajaxSetup، ويتم إعادة تعيين خيار timeout للاستخدام الخاص نادرًا.

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

يُمكن لتقنية scriptCharset تعيين مجموعة معينة من الحروف للطلبات التي تحتوي على علامة <script>، لاستخدامها في scripts أو بيانات jsonp. يكون ذلك مفيدًا بشكل خاص عندما تكون مجموعة الحروف للسكرابت والصفحة مختلفة.

أول حرف في Ajax هو الأول من asynchronous، مما يعني أن جميع العمليات تكون متوازية وليس لديها ترتيب زمني بينها. يتم تعيين معامل async لـ $.ajax() دائمًا على true، مما يشير إلى أن يمكن تنفيذ الكود الآخر بعد بدء الطلب. لا يُنصح بتغيير هذا الخيار إلى false، مما يعني أن جميع الطلبات لم تعد متوازية، مما قد يؤدي إلى تثبيط المتصفح.

يستعيد وظيفة $.ajax جسم XMLHttpRequest الذي أنشأته. عادةً، يقوم jQuery بمعالجة وإنتاج هذا الجسم داخليًا، ولكن يمكن للمستخدم أيضًا إرسال جسم xhr مسبقًا من خلال خيار xhr. يُعتبر الجسم عادةً مهملًا، ولكن يقدم واجهة أساسية لمراقبة وتعديل الطلبات. على سبيل المثال، يمكن استخدام .abort() على الجسم للإجراء وقف الطلبات قبل إكمالها.

دليل jQuery Ajax