الدالة jQuery.getJSON() في jQuery
jQuery.getJSON( url [, data ] [, success ] )
القيم المعادة
تعيد كائنًا من النوع jqXHR.
الوصف
تجلب هذه الدالة بياناتٍ مرمَّزة بصيغة JSON من الخادم باستعمال طلب HTTP عبر الطريقة GET.
jQuery.get( url [, data ] [, success ] )
أُضيفت مع الإصدار: 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.ajax()، إذ تكافئ:
$.ajax({
dataType: "json",
url: url,
data: data,
success: success
});
البيانات المراد إرسالها إلى الخادم تضاف إلى العنوان URL كسلسلة استعلام نصية. إن كان الوسيط data كائنًا مجرَّدًا، فسيحوَّل إلى سلسلة نصية ورموز URL المُشفَّرة (url-encoded) قبل إضافته إلى العنوان URL.
أغلب حالات تنفيذ الدالة $.getJSON() تستعمل معالج الحدث success:
$.getJSON( "ajax/test.json", function( data ) {
var items = [];
$.each( data, function( key, val ) {
items.push( "<li id='" + key + "'>" + val + "</li>" );
});
$( "<ul/>", {
"class": "my-new-list",
html: items.join( "" )
}).appendTo( "body" );
});
يعتمد هذا المثال بالتأكيد على بنية ملف JSON:
{
"واحد": "هو ربي",
"اثنان": "هما أمي وأبي",
"ثلاثة": "هم إخوتي"
}
سيؤدي استعمال هذه البنية إلى إنشاء قائمة غير مرتَّبة وإضافتها إلى <body>، إذ يُستعمَل في المثال حلقة تكرار تطبَّق على البيانات المطلوبة.
يمرَّر إلى دالة رد النداء success البيانات المعادة من الخادم، التي تكون كائن JavaScript، أو مصفوفة عادةً بحسب ما عُرِّفت عبر بنية JSON وحلُّلت باستعمال التابع $.parseJSON(). يُمرَّر إليها أيضًا محتوى حالة الرد.
بدءًا من الإصدار jQuery 1.5، أصبح بالإمكان أن يمرَّر إلى دالة رد النداء success الكائن jqXHR أيضًا (في الإصدار jQuery 1.4 يكون هذا الكائن هو XMLHttpRequest). على أي حال، لمَّا كانت طلبات JSONP وطلبات GET العابرة للنطاقات (cross-domain) لا تستعمل XHR، ففي هذه الحالات يكون المعامل jqXHR والمعامل teatStatus المرَّرين إلى دالة رد النداء success غير مُعرَّفين (undefined).
ملاحظة مهمة: بدءًا من الإصدار jQuery 1.4، إن احتوى ملف JSON على خطأ في الصياغة، فسيفشل الطلب بشكل صامت، لذا تجنب التعديل اليدوي للبيانات ذات الصيغة JSON. إنَّ JSON هي صيغة تبادل بيانات مع قواعد صارمة للصياغة أكثر من تلك الموجودة في رموز محارف الكائنات (objects literal notation) في JavaScript. على سبيل المثال، يجب على جميع السلاسل النصية في JSON سواءً كانت خاصِّيَّات أو قيم أن تكون مقتبسة. للمزيد من التفاصيل حول JSON، يمكن الاطلاع على الموقع الرسمي لها.
JSONP
إن احتوى العنوان URL على السلسلة النصية "callbaxk=?" (أو ما شابهها كأن تكون مُعرَّفة من طرف الواجهات البرمجية للخادم)، فسيُعامَل الطلب على أنَّه JOSNP. راجع فقرة النوع "jsonp" في القسم dataType في توثيق الدالة $.ajax() للمزيد من المعلومات.
الكائن jqXHR
بدءًا من الإصدار jQuery 1.5، تعيد جميع توابع Ajax في jQuery مجموعةً حاويةً (superset) للكائن XMLHttpRequest. تنفِّذ الكائنات jqXHR المعادة عن طريق $.getJSON() الواجهة Promise بإعطائها جميع الخاصِّيَّات، والتوابع، وسلوك Promise (ارجع إلى الكائن Deferred للمزيد من المعلومات).
تأخذ التوابع jqXHR.done() (للنجاح)، و jqXHR.fail() (للفشل)، و jqXHR.always() (للإكمال سواء كان الطلب ناجحًا أم فاشلًا، وأضيف في الإصدار jQuery 1.6) وسيط الدالة التي تُستدعَى عندما ينتهي الطلب. للمزيد من المعلومات حول الوسائط التي تمرَّر إلى هذه الدالة، اقرأ القسم "الكائن jqXHR" في توثيق الدالة $.ajax().
تسمح الواجهة Promise لتوابع Ajax في الإصدار jQuery 1.5، من ضمنها الدالة $.getJSON()، بريط ردود نداء متعدِّدة -.done()، و .fail()، و .always()، بطلب واحد أيضًا كما أنَّها تسمح بإسناد ردود النداء هذه بعد أن يكون الطلب قد اكتمل. إن كان الطلب مكتملًا مسبقًا، فستُطلق ردود النداء مباشرةً.
// إسناد معالجات حدث بعد إنشاء الطلب مباشرةً
// لهذا الطلب jqXHR وحفظ الكائن
var jqxhr = $.getJSON( "example.json", function() {
console.log( "success" );
})
.done(function() {
console.log( "second success" );
})
.fail(function() {
console.log( "error" );
})
.always(function() {
console.log( "complete" );
});
// أنجز أعمالًا أخرى هنا
// تعيين دالة أخرى عند اكتمال الطلب السابق
jqxhr.complete(function() {
console.log( "second complete" );
});
ملاحظة: بدءًا من الإصدار jQuery 3.0، حُذفت توابع ردود النداء jqXHR.success()، و jqXHR.error()، و jqXHR.complete(). يمكنك استعمال التوابع jqXHR.done()، و jqXHR.fail()، و jqXHR.always() عوضًا عنها.
ملاحظات إضافية
- بسبب القيود الأمنية للمتصفحات، فإنَّ أغلب طلبات "Ajax" تخضع إلى سياسة المصدر الواحد (Same origin policy). لن يتمكن الطلب آنذاك من جلب البيانات بنجاح من نطاقات أو نطاقات فرعية أو منافذ أو بروتوكولات مختلفة.
- لا يخضع الطلب script والطلب JSONP إلى قيود سياسة المصدر الواحد.
أمثلة
جلب أحدث أربع صور للجبل رينييه (Mount Rainier) من الواجهة البرمجيَّة Flicker:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>jQuery.getJSON demo</title>
<style>
img {
height: 100px;
float: left;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div id="images"></div>
<script>
(function() {
var flickerAPI = "https://api.flickr.com/services/feeds/photos_public.gne?jsoncallback=?";
$.getJSON( flickerAPI, {
tags: "mount rainier",
tagmode: "any",
format: "json"
})
.done(function( data ) {
$.each( data.items, function( i, item ) {
$( "<img>" ).attr( "src", item.media.m ).appendTo( "#images" );
if ( i === 3 ) {
return false;
}
});
});
})();
</script>
</body>
</html>
جلب بيانات JSON من الصفحة text.js والوصول إلى الأسماء في بيانات JSON المعادة:
$.getJSON( "test.js", function( json ) {
console.log( "JSON Data: " + json.users[ 3 ].name );
});
جلب بيانات JSON من الصفحة test.js مع إرسال بيانات إضافيَّة إلى الخادم والوصول إلى الأسماء في البيانات المعادة. إن حصل أي خطأ، فستظهر رسالة بهذا الخط:
$.getJSON( "test.js", { name: "عاكف", time: "2pm" } )
.done(function( json ) {
console.log( "JSON Data: " + json.users[ 3 ].name );
})
.fail(function( jqxhr, textStatus, error ) {
var err = textStatus + ", " + error;
console.log( "فشل الطلب: " + err );
});