الدالة jQuery.post() في jQuery
jQuery.post( url [, data ] [, success ] [, dataType ] )
القيم المعادة
تعيد كائنًا من النوع jqXHR.
الوصف
تجلب هذه الدالة بياناتٍ من الخادم باستعمال طلب HTTP عبر الطريقة POST.
jQuery.post( url [, data ] [, success ] [, dataType ] )
أُضيف مع الإصدار: 1.0.
url
سلسلة نصية تحتوي على الرابط URL الذي سيُرسل الطلب إليه.
data
كائنٌ مجرَّد أو سلسلة نصية ترسل إلى الخادم مع الطلب.
success
دالةٌ من الشكل Function( Object data, String textStatus, jqXHR jqXHR ) يراد تنفيذها إن نجح الطلب. يجب تمرير قيمة هذا الوسيط إن أعطي الوسيط dataType ولكن يمكن أن ينوب عنه استعمال القيمة العدميَّة (null) أو jQuery.noop.
dataType
سلسلة نصية تمثل نوع البيانات المتوقع إعادتها من الخادم. القيمة الافتراضيَّة هي Intelligent Guess (xml, json, script, text, html).
jQuery.post( [settings ] )
أُضيف مع الإصدار: 1.12/2.2.
settings
كائنٌ مجرَّد (object) يمثِّل مجموعةً من الأزواج مفتاح/قيمة التي تضبط طلب Ajax. جميع الإعدادات اختياريَّة باستثناء url، ويمكن تعيين إعدادات افتراضيَّة لأي ضبط باستعمال التابع $.ajaxSetup(). انظر إلى توثيق الدالة jQuery.ajax( settings ) للاطلاع على القائمة الكاملة لجميع الإعدادات. ستُعيَّن قيمة الضبط type إلى post تلقائيًّا.
هذه الدالة هي اختزال للدالة jQuery.ajax() التي تكافئ:
$.ajax({
type: "POST",
url: url,
data: data,
success: success,
dataType: dataType
});
يُمرَّر إلى دالة رد النداء success البيانات المُعادة من الخادم التي تكون من النوع XML، أو text بحسب النوع MIME للرد. يمرَّر إليها أيضًا محتوى حالة الرد.
بدءًا من الإصدار jQuery 1.5، أصبح بالإمكان أن يُمرَّر إلى دالة رد النداء success الكائن jqXHR أيضًا (في الإصدار jQuery 1.4 يكون هذا الكائن هو XMLHttpRequest).
أغلب حالات تنفيذ الدالة $.post() تستعمل معالج الحدث success:
$.post( "ajax/test.html", function( data ) {
$( ".result" ).html( data );
alert( "اكتملت عملية التحميل." );
});
يجلب هذا المثال جزءًا من شيفرة HTML ويضيفها إلى الصفحة.
الصفحات المجلوبة بوساطة POST لا تُخزَّن مطلقًا، لذا ليس للضبط cache والضبط ifModified في jQuery.ajaxSetup() أي تأثير.
الكائن jqXHR
بدءًا من الإصدار jQuery 1.5، تعيد جميع توابع Ajax في jQuery مجموعةً حاويةً (superset) للكائن XMLHttpRequest. تُنفِّذ الكائنات jqXHR المعادة عن طريق $.post() الواجهة Promise بإعطائها جميع الخاصِّيَّات، والتوابع، وسلوك Promise (ارجع إلى الكائن Deferred للمزيد من المعلومات).
تأخذ التوابع jqXHR.done() (عند النجاح)، و jqXHR.fail() (عند الفشل)، و jqXHR.always() (عند الإكمال سواء كان الطلب ناجحًا أم فاشلًا، وأضيف في الإصدار jQuery 1.6) وسيط الدالة التي تُستدعَى عندما ينتهي الطلب. للمزيد من المعلومات حول الوسائط التي تمرَّر إلى هذه الدالة، اقرأ القسم "الكائن jqXHR" في توثيق الدالة $.ajax().
تسمح الواجهة Promise لتوابع Ajax في jQuery، من ضمنها $.post()، بربط ردود نداء متعدِّدة -.done()، و .fail()، و .always()- بطلب واحد أيضًا كما أنَّها تسمح بإسناد ردود النداء هذه بعد أن يكون الطلب قد اكتمل. إن كان الطلب مكتملًا مسبقًا، فستُطلق ردود النداء مباشرةً.
// إسناد معالجات حدث بعد إنشاء الطلب مباشرةً
// لهذا الطلب jqXHR وحفظ الكائن
var jqxhr = $.post( "example.php", function() {
alert( "نجح الطلب" );
})
.done(function() {
alert( "نجح الطلب مرة أخرى" );
})
.fail(function() {
alert( "خطأ" );
})
.always(function() {
alert( "اكتمل الطلب" );
});
// أنجز أعمالًا أخرى هنا
// تعيين دالة أخرى عند اكتمال الطلب السابق
jqxhr.always(function() {
alert( "مرة ثانية، اكتمل الطلب" );
});
ملاحظة: بدءًا من الإصدار jQuery 3.0، حذفت توابع ردود النداء jqXHR.success()، و jqXHR.error()، و jqXHR.complete(). يمكنك استعمال التوابع jqXHR.done()، و jqXHR.fail()، و jqXHR.always() عوضًا عنها.
ملاحظات إضافية
- بسبب القيود الأمنية للمتصفحات، فإنَّ أغلب طلبات "Ajax" تخضع إلى سياسة المصدر الواحد (Same origin policy). لن يتمكن الطلب آنذاك من جلب البيانات بنجاح من نطاقات أو نطاقات فرعيَّة أو منافذ أو بروتوكولات مختلفة.
- إن أعاد طلبٌ ما أنشئ باستعمال
jQuery.post() رمز خطأٍ، فسيفشل الطلب بصمت إلا إذا استدعى السكربت التابع.ajaxError() العام. بدءًا من الإصدار jQuery 1.5، أصبح بالإمكان إعادة التابع .error() للكائن jqXHR باستعمالjQuery.post()لمعالجة الأخطاء.
أمثلة
طلب الصفحة test.php وتجاهل البيانات المعادة:
$.post( "test.php" );
طلب الصفحة test.php مع إرسال بعض البيانات مع الطلب وتجاهل البيانات المعادة:
$.post( "test.php", { name: "عاكف", time: "2pm" } );
تمرير مصفوفة من البيانات إلى الخادم وتجاهل البيانات المعادة:
$.post( "test.php", { "choices[]": ["سعد", "مارية"] } );
إرسال بيانات نموذجٍ إلى الخادم باستعمال طلب Ajax:
$.post( "test.php", $( "#testform" ).serialize() );
طلب الصفحة test.php وإظهار البيانات المعادة في تنبيه (سيكون نوع البيانات HTML أو XML بناءً على ما الذي أُعيد):
$.post( "test.php", function( data ) {
alert( "البيانات المجلوبة: " + data );
});
طلب الصفحة test.php وإظهار البيانات المعادة في تنبيه مع إرسال بيانات إلى الخادم (سيكون نوع البيانات HTML أو XML بناءً على ما الذي أُعيد):
$.post( "test.php", { name: "عاكف", time: "2pm" } )
.done(function( data ) {
alert( "البيانات المجلوبة: " + data );
});
جلب محتويات الصفحة test.php التي أُعيدت بتنسيق (<?php echo json_encode( array( "name"=>"jamil","time"=>"2pm" ) ); ?>) json وإضافتها إلى الصفحة:
$.post( "test.php", function( data ) {
$( "body" )
.append( "Name: " + data.name ) // عاكف
.append( "Time: " + data.time ); // 2pm
}, "json" );