التابع .ready() في jQuery
.ready( handler )
القيم المعادة
يعيد كائنًا من النوع jQuery.
الوصف
ينفِّذ هذا التابع دالةً عندما تكون شجرة DOM جاهزة.
.ready( handler )
أُضيف مع الإصدار: 1.0.
handler
الدالة المراد تنفيذها بعد أن تصبح DOM جاهزة.
يوفر التابع .ready() طريقة لتشغيل شيفرة JavaScript حالما يصبح بالإمكان تعديل DOM بشكل آمن. يُعدُّ هذا الوقت غالبًا أفضل الأوقات لإنجاز مهامٍ ضرورية قبل أن يشاهد المستخدم الصفحة أو يتفاعل معها مثل إضافة معالجات أحداث أو تهيئة إضافات معيَّنة. عندما تُضاف دوال متعدِّدة عبر الاستدعاء المتتالي إلى هذا التابع، فستُنفَّذ عندما تصبح DOM جاهزة بالترتيب نفسه الذي أضيفت به. بدءًا من إصدار jQuery 3.0، تتأكد jQuery من أنَّ حدوث استثناء في إحدى معالجات الحدث لا يؤثر على تنفيذ بقية المعالجات التي أضيفت بعده.
توفر أغلب المتصفحات طريقة لأداء الوظيفة نفسها وتكون على شكل حدثٍ وهو DOMContentLoaded. على أي حال، يختلف التابع .ready() في jQuery عنه، إذ هو أكثر أهميَّة وفائدة؛ فإن أصبحت شجرة DOM جاهزة وأطلق المتصفح الحدث DOMContentLoaded قبل أن استدعاء التابع .ready( handler )، فستُنفَّذ الدالة handler. على النقيص من ذلك، إذا ربطنا دالةً لتعالج الحدث DOMContentLoaded بعد إطلاق الحدث DOMContentLoaded، فلن تُنفَّذ الدالة حينئذٍ.
توفر المتصفحات أيضًا الحدث load في الكائن window. عندما يُطلق هذا الحدث، فهذا يشير إلى تحميل جميع محتويات الصفحة بما في ذلك الصور. يمكن مراقبة هذا الحدث في jQuery باستعمال $( window ).on( "load", handler ). في الحالات التي تعتمد فيها الشيفرة على المحتويات المحمَّلة (مثل أن تكون أبعاد الصورة مطلوبة)، فيجب آنذاك أن توضع هذه الشيفرة في معالج الحدث load.
لاحظ أنَّه الرغم أنَّ DOM تصبح جاهزة دومًا قبل أن يكتمل تحميل الصفحة تمامًا، فمن غير الآمن عادةً ربط مستمع الحدث load بالشيفرة المُنفَّذة في الدالة handler المُمرَّرة إلى التابع .ready(). على سبيل المثال، يمكن تحميل السكربتات ديناميكيًا بعد أن تُحمَّل الصفحة بفترة باستعمال توابع مثل $.getScript(). رغم أنَّ معالجات الحدث المضافة باستعمال .ready() ستُنفَّذ دومًا في السكربت المُحمَّل ديناميكيًا، إلا أنَّ الحدث load في الكائن window يكون قد حدث مسبقًا ولن تُنفَّذ تلك المستمعات مطلقًا.
توفر jQuery طرائق عدة لإرفاق دالة من أجل أن تُنفَّذ عندما تصبح DOM جاهزة وهي:
$( handler )$( document ).ready( handler )$( "document" ).ready( handler )$( "img" ).ready( handler )$().ready( handler )
جميع الصيغ السابقة متكافئة تمامًا. بدءًا من الإصدار jQuery 3.0، ينصح باستعمال الصيغة الأولى فقط؛ فرغم أنَّ بقية الصيغ لا تزال تعمل، إلا أنَّها أصبحت مهملة ويعود السبب إلى أنَّ التحديد لا يتبع سلوك التابع .ready() وهو غير فعَّال ويمكن أن يؤدي إلى افتراضات خطأ حول سلوك التابع. على سبيل المثال، تعمل الصياغة الثالثة مع document ولا تحدِّد أي شيء بينما تنتظر الصيغة الرابعة لتصبح الصفحة جاهزة ولكنَّها تدل حقيقةً (بشكل خطأ) على أنَّها تنتظر لتصبح الصور جاهزة وليس الصفحة.
هنالك أيضًا الصياغة $(document).on( "ready", handler ) ولكنَّها أهملت في الإصدار jQuery 1.8 وحذفت في الإصدار jQuery 3.0. الجدير بالملاحظة أنَّه إذا أصبحت DOM جاهزة قبل أن يُربَط هذا الحدث، فلن يُنفَّذ معالج الحدث حينها.
يستعمل التابع .ready() عادة مع دوال مجهولة مثل:
$( document ).ready(function() {
// .ready() يستدعى معالج الحدث من أجل
});
والتي تكافئ الطريقة المفضلة للاستدعاء وهي:
$(function() {
// .ready() يستدعى معالج الحدث من أجل
});
الاسم البديل للكائن jQuery
عندما يستعمل $.noConflict() لتجنب حصول تعارض في مجال الأسماء (namespace)، فلا يبقى الاختصار $ متاحًا حينذاك. مع ذلك، يُمرَّر الوسيط handler في التابع .ready() كمرجعٍ للكائن jQuery الذي يستدعي التابع. يسمح هذا للوسيط handler باستعمال الكائن jQuery، وكأنَّه $ مثلًا، دون معرفة اسمه البديل:
jq2 = jQuery.noConflict();
jq2(function( $ ) {
// jq2 الحقيقي هو jQuery تستعمل الشيفرة $ كالمعتاد هنا؛ الكائن
});
أمثلة
إظهار رسالة عن اكتمال تحميل DOM:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>ready مثالٌ عن استعمال التابع</title>
<style>
p {
color: red;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
<script>
$(function() {
$( "p" ).text( "حمِّلت DOM الآن ويمكن البدء بإجراء التعديلات عليها." );
});
</script>
</head>
<body>
<p>لم تكتمل عملية التحميل بعد</p>
</body>
</html>