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

`‎.load( url [, data ] [, complete ] )‎`

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

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

الوصف

يحمِّل هذا التابع البيانات من الخادم ثمَّ يضع محتوى HTML المُعاد في العنصر المتطابق.

`‎.load( url [, data ] [, complete ] )‎`

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

`url`

سلسلة نصية تمثل الرابط URL الذي سيُرسل إليه الطلب.

`data`

كائن مجرد (Object) أو سلسلة نصية يُراد إرسالها إلى الخادم مع الطلب.

`complete`

دالة من الشكل Function( String responseText, String textStatus, jqXHR jqXHR )‎، وتمثِّل دالة ردِّ النداء التي ستُنفَّذ عند اكتمال إرسال الطلب.

ملاحظة: قبل الإصدار jQuery 3.0، كان لدى مجموعة معالجة الحدث تابع أيضًا يدعى ‎.load()‎. تحدِّد إصدارات jQuery القديمة أي دالة يجب اطلاقها اعتمادًا على مجموعة المعاملات الممرَّرة إليها.

هذه الدالة هي أبسطة طريقة لجلب البيانات من الخادم. تشبه إلى حد ما ‎$.get(url, data, success)‎ باستثناء أنَّه تابع وليس دالة عامة ولديه دالة رد نداء مضمَّنة. عندما يُكشتف رد ناجح (مثل أن يكون textStatus هو "success" أو "notmodified")، فإن التابع ‎.load()‎ يضع البيانات المعادة في محتوى HTML للعنصر المتطابق. هذا يعني أنه أغلب استخدامات هذا التابع يمكن تبسيطها بالشكل:

$( "#result" ).load( "ajax/test.html" );

إن لم يطابق المحدد أي عنصر (أي إن لم يكن هنالك عنصر في الصفحة ذي المعرف "result")، فلن يُرسل الطلب Ajax.

دالة رد النداء (Callback)

إن زُود رد النداء "complete"، فسينفذ بعد إنجاز عملية الإرسال باستعمال POST وادراج محتوى HTML. ستستدعى دالة رد النداء مرةً لكل عنصر في مجموعة jQuery، وسيشير this إلى كل عنصر DOM.

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

في كلا المثالين السابقين، إن لم تحتوي الصفحة الحالية على عنصر ذي المعرف "result"، فلن يُنفذ التابع ‎.load()‎.

تابع الطلب (request)

سيُستعمل التابع POST إن مُرِّرت البيانات إلى المعامل data على أنَّها كائن. خلا ذلك، سيُستعمل التابع GET.

تحميل أجزاء من الصفحة (Loading Page Fragments)

يسمح لنا التابع ‎.load()‎، خلافًا للتابع ‎$.get()‎، بتحديد جزء الصفحة البعيدة المطلوب إدراجه، وهذا يتحقق باستعمال صياغة مخصصة للمعامل url. إن أضيف محرف المسافة مرة واحدة أو أكثر في السلسلة النصية للمعامل url، فالجزء الذي يلي أول مسافة يُمثل محدد jQuery الذي يحدد المحتوى المطلوب تحميله.

سنعدِّل على المثال السابق لإعادة جزء من الصفحة فقط بدلًا من إعادتها كلها:

$( "#result" ).load( "ajax/test.html #container" );

سيجلب التابع عند تنفيذه كل محتوى الصفحة ajax/test.html، ولكن ستحلل jQuery هذا المحتوى للبحث عن العنصر ذي المعرِّف "container". بعد إيجاد هذا العنصر، سيضاف هو ومحتواه إلى العنصر الذي يملك المعرِّف "result" وسيُهمل بعدئذٍ بقية محتوى الصفحة.

تستعمل jQuery خاصية المتصفح ‎.innerHTML لتحلِّل محتوى الصفحة المُعاد وتدرجه إلى الصفحة الحالية. يرشِّح المتصفحات غالبًا خلال هذه العملية العناصر الموجودة في الصفحة مثل العنصر <html>، أو العنصر <title>، أو العنصر <head>. نتيجةً لذلك، قد لا تكون العناصر المعادة باستعمال ‎.load()‎ نفسها تمامًا فيما لو أُعيدت الصفحة مباشرةً باستعمال المتصفح.

تنفيذ السكربت

عند استدعاء التابع ‎.load()‎ مع استعمال رابط URL دون إلحاقه بتعبير محدِّد، فسيُمرر المحتوى إلى التابع ‎.html()‎ قبل إزالة السكربتات منه، وستُنفذ آنذاك هذه السكربتات قبل أن تُتجاهل. إن استُدعي التابع ‎.load()‎ مع إضافة تعبير محدد إلى العنوان URL، فستُزال السكريتات على أي حال قبل بدء تحديث شجرة DOM، ولن تُنفَّذ حينها. ستُشرح هاتان الحالتان في المثالين التاليين:

في هذا المثال، أي شيفرات JavaScript ستُحمل إلى العنصر ذي المعرف "a" الذي يمثل جزءًا من الصفحة الحالية فإنها ستنفَّذ بنجاح:

$( "#a" ).load( "article.html" );

من جهة أخرى، إنَّ كتل السكربتات في المثال التالي الموجودة في الصفحة التي حُمِّلت إلى ‎#b ستُزال ولن تُنفذ:

$( "#b" ).load( "article.html #target" );

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

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

أمثلة

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

<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>load مثالٌ عن استعمال التابع</title>
  <style>
  body {
    font-size: 12px;
    font-family: Arial;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<b>المشاريع:</b>
<ol id="new-projects"></ol>
 
<script>
$( "#new-projects" ).load( "/resources/load.html #projects li" );
</script>
 
</body>
</html>

إظهار تنبيه إذا واجه طلب "Ajax" خطأً ما:

<!doctype html>
<html lang="ar">
<head>
  <meta charset="utf-8">
  <title>load مثالٌ عن استعمال التابع</title>
  <style>
  body {
    font-size: 12px;
    font-family: Arial;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<b>ردٌ ناجح (يجب أن يكون فارغًا):</b>
<div id="success"></div>
<b>ردٌ خطأ:</b>
<div id="error"></div>
 
<script>
$( "#success" ).load( "/not-here.php", function( response, status, xhr ) {
  if ( status == "error" ) {
    var msg = "نتأسف جدًا، إذ يوجد خطأ: ";
    $( "#error" ).html( msg + xhr.status + " " + xhr.statusText );
  }
});
</script>
 
</body>
</html>

تحميل الملف feeds.html إلى العنصر <div> ذي المُعرِّف "feeds":

$( "#feeds" ).load( "feeds.html" );

النتيجة ستكون:

<div id="feeds"><b>45</b> تمت عملية التحميل بنجاح</div>

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

$( "#objectID" ).load( "test.php", { "choices[]": [ "أحمد", "ليلى" ] } );

مثال مشابه للمثال السابق ولكن المعاملات الإضافية ستُرسل باستعمال POST إلى الخادم وسيُنفذ رد النداء عندما ينتهي الخادم من استلام الطلب:

$( "#feeds" ).load( "feeds.php", { limit: 25 }, function() {
  alert( "اكتمل تحميل 25 من المدخلات الأخيرة" );
});

مصادر

صفحة التابع ‎‎.load()‎ في توثيق jQuery الرسمي.