الدالة ‎‎jQuery.get()‎‎ في jQuery

jQuery.get( url [, data ] [, success ] [, dataType ] )‎

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

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

الوصف

يجلب هذا التابع بياناتٍ من الخادم باستعمال طلب HTTP عبر الطريقة GET.

jQuery.get( 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.get( [settings ] )‎

أُضيفت مع الإصدار: 1.12/2.2.

settings

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

هذه الدالة هي اختزال للدالة jQuery.ajax()‎ التي تكافئ:

$.ajax({
  url: url,
  data: data,
  success: success,
  dataType: dataType
});

يُمرَّر إلى دالة رد النداء success البيانات المُعادة من الخادم التي تكون من النوع XML، أو text، أو JavaScript، أو JSON بحسب النوع MIME للرد. يمرَّر إليها أيضًا محتوى حالة الرد.

بدءًا من الإصدار jQuery 1.5، أصبح بالإمكان أن يُمرَّر إلى دالة رد النداء success الكائن jqXHR أيضًا (في الإصدار jQuery 1.4 يكون هذا الكائن هو XMLHttpRequest). على أي حال، لمَّا كانت طلبات JSONP وطلبات GET العابرة للنطاقات (cross-domain) لا تستعمل XHR، ففي هذه الحالات يكون المعامل jqXHR والمعامل teatStatus المرَّرين إلى دالة رد النداء success غير مُعرَّفين (undefined).

أغلب حالات تنفيذ الدالة ‎$.get()‎ تستعمل معالج الحدث success:

$.get( "ajax/test.html", function( data ) {
  $( ".result" ).html( data );
  alert( "اكتملت عملية التحميل." );
});

يجلب هذا المثال جزءًا من شيفرة HTML ويضيفها إلى الصفحة.

الكائن jqXHR

بدءًا من الإصدار jQuery 1.5، تعيد جميع توابع Ajax في jQuery مجموعةً حاويةً (superset) للكائن XMLHttpRequest. تنفِّذ الكائنات jqXHR المعادة عن طريق ‎$.get()‎ الواجهة Promise بإعطائها جميع الخاصِّيَّات، والتوابع، وسلوك Promise (ارجع إلى الكائن Deferred للمزيد من المعلومات).

تأخذ التوابع jqXHR.done()‎ (للنجاح)، و jqXHR.fail()‎ (للفشل)، و jqXHR.always()‎ (للإكمال سواء كان الطلب ناجحًا أم فاشلًا، وأضيف في الإصدار jQuery 1.6) وسيط الدالة التي تُستدعَى عندما ينتهي الطلب. للمزيد من المعلومات حول الوسائط التي تمرَّر إلى هذه الدالة، اقرأ القسم "الكائن jqXHR" في توثيق الدالة ‎$.ajax()‎.

تسمح الواجهة Promise لتوابع Ajax في jQuery، من ضمنها التابع ‎$.get()‎، بريط ردود نداء متعدِّدة -‎.done()‎، و ‎.fail()‎، و ‎.always()‎- بطلب واحد أيضًا كما أنَّها تسمح بإسناد ردود النداء هذه بعد أن يكون الطلب قد اكتمل. إن كان الطلب مكتملًا مسبقًا، فستُطلق ردود النداء مباشرةً.

// إسناد معالجات حدث بعد إنشاء الطلب مباشرةً
// لهذا الطلب jqXHR وحفظ الكائن
var jqxhr = $.get( "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). لن يتمكن الطلب آنذاك من جلب البيانات بنجاح من نطاقات أو نطاقات فرعية أو منافذ أو بروتوكولات مختلفة.
• لا يخضع الطلب script والطلب JSONP إلى قيود سياسة المصدر الواحد.
• إن أعاد طلبٌ ما أنشئ باستعمال jQuery.get()‎ رمز خطأٍ، فسيفشل الطلب بصمت إلا إذا استدعى السكربت التابع ‎.ajaxError()‎ العام. بدءًا من الإصدار jQuery 1.5، أصبح بالإمكان إعادة التابع ‎.error()‎ للكائن jqXHR باستعمال jQuery.get()‎ لمعالجة الأخطاء.

أمثلة

طلب الصفحة test.php وتجاهل البيانات المعادة:

$.get( "test.php" );

طلب الصفحة test.php مع إرسال بعض البيانات مع الطلب وتجاهل البيانات المعادة:

$.get( "test.php", { name: "عاكف", time: "2pm" } );

تمرير مصفوفة من البيانات إلى الخادم وتجاهل البيانات المعادة:

$.get( "test.php", { "choices[]": ["سعد", "مارية"] } );

طلب الصفحة test.php وإظهار البيانات المعادة في تنبيه (سيكون نوع البيانات HTML أو XML بناءً على ما الذي أُعيد):

$.get( "test.php", function( data ) {
 alert( "البيانات المجلوبة: " + data );
});

طلب الصفحة test.cgi وإظهار البيانات المعادة في تنبيه مع إرسال بيانات إلى الخادم (سيكون نوع البيانات HTML أو XML بناءً على ما الذي أُعيد):

$.get( "test.cgi", { name: "عاكف", time: "2pm" } )
 .done(function( data ) {
   alert( "البيانات المجلوبة: " + data );
 });

جلب محتويات الصفحة test.php التي أُعيدت بتنسيق ‎ (<?php echo json_encode( array( "name"=>"jamil","time"=>"2pm" ) ); ?>) json‎وإضافتها إلى الصفحة:

$.get( "test.php", function( data ) {
  $( "body" )
    .append( "Name: " + data.name ) // عاكف
    .append( "Time: " + data.time ); //  2pm
}, "json" );

جلب نموذجٍ باستعمال طلب Ajax ووضع البيانات المعادة في عنصر <div>:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery.post مثالٌ عن استعمال التابع</title>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<form action="/" id="searchForm">
  <input type="text" name="s" placeholder="Search...">
  <input type="submit" value="Search">
</form>
<!-- the result of the search will be rendered inside this div -->
<div id="result"></div>
 
<script>
// بالنموذج submit ربط معالج الحدث
$( "#searchForm" ).submit(function( event ) {
 
  // إيقاف السلوك الطبيعي لإرسال النموذج
  event.preventDefault();
 
  // الحصول على بعض المعلومات من العناصر في الصفحة
  var $form = $( this ),
    term = $form.find( "input[name='s']" ).val(),
    url = $form.attr( "action" );
 
  // POST إرسال البيانات عبر الطريقة 
  var posting = $.post( url, { s: term } );
 
  // <div> وضع البيانات المعادة في عنصر 
  posting.done(function( data ) {
    var content = $( data ).find( "#content" );
    $( "#result" ).empty().append( content );
  });
});
</script>
 
</body>
</html>

مصادر

• صفحة الدالة ()jQuery.get في توثيق jQuery الرسمي.