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

تعيد هذه الدالة مجموعةً من العناصر المطابقة التي إمَّا وُجدَت في شجرة DOM بناءً على الوسائط المُمرَّرة، أو أنشئت بتمرير سلسلة نصية تحتوي على محتوى HTML.

‎jQuery( selector [, context ] )‎

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

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

الوصف

تقبل هذه الدالة سلسلة نصية تحتوي على محدِّد CSS يُستعمَل لمطابقة مجموعة من العناصر.

‎jQuery( selector [, context ] )‎

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

selector

سلسلة نصية تحتوي على تعبير محدِّد.

context

عنصر DOM، أو كائن Document، أو كائن jQuery والذي سيُستعمَل بوصفه سياقًا (context).

jQuery( element )‎

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

element

عنصر DOM يراد تغليفه في كائن jQuery.

‎jQuery( elementArray )‎

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

elementArray

مصفوفةٌ تحتوي على مجموعة من عناصر DOM يُراد تغليفها في كائن jQuery.

‎jQuery( object )‎

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

object

كائن مجرَّد (object) يراد تغليفه في كائن jQuery.

‎jQuery( selection )‎

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

selection

كائن jQuery موجود يراد نسخه.

‎jQuery()‎

أضيفت مع الإصدار: 1.0. ولا يقبل هذا الشكل من الدالة أية وسائط.

تبحث الدالة jQuery()‎ -ويمكن أن تكتب أيضًا بالشكل ‎$()‎- عند استعمالها في شكلها الأول عن العناصر التي تطابق المحدِّد المُعطى في DOM ثمَّ تنشئ كائنًا جديدًا من النوع jQuery يشير إلى تلك العناصر التي وجدها:

$( "div.foo" );

إن لم يتطابق أي عنصر مع المحدِّد المعطى، فسيُعاد كائن jQuery فارغ لا يحوي أيَّة عناصر.

سياق التحديد

تُجري المحدِّدات عمليَّة البحث ضمن DOM افتراضيًّا بدءًا من العنصر الجذر للمستند. رغم ذلك، يمكن تمرير سياق بديل للبحث فيه عن طريق استعمال الوسيط الثاني context للدالة ‎$()‎. إن أردنا مثلًا البحث ضمن معالج حدثٍ ما، فيمكن تقييد عمليَّة البحث ضمن مجاله فقط بالشكل التالي:

$( "div.foo" ).click(function() {
 $( "span", this ).addClass( "bar" );
});

عندما انحصرت عمليَّة البحث على العنصر <span> في السياق this فقط، فسيضاف التصنيف الجديد إلى العناصر <span> الموجودة ضمن نطاق العنصر المضغوط عليه فقط.

توجد طريقة أخرى لإجبار المحدِّد على البحث ضمن سياق معين وهي استعمال التابع ‎.find()‎، إذ يكافئ ‎$( "span", this )‎ الشكل ‎$( this ).find( "span" )‎.

استعمال عناصر DOM

تنشئ الدالة عند استعمالها بشكلها الثاني والثالث كائن jQuery مستعملةً عنصر DOM واحد أو أكثر سبق تحديدها بأي طريقة أخرى. تُرتَّب العناصر في الكائن jQuery المُنشأ من مصفوفة من العناصر مثلما كانت مرتبة في المصفوفة تمامًا خلافًا لأغلب عمليات jQuery المشابهة التي تُرتَّب فيها العناصر وفقًا لترتيب DOM. ستُنسخ العناصر من المصفوفة كما هي ولن يزال تغليفها إن كانت قد غُلِّفت بشكل مجموعات jQuery مسبقًا.

أرجو الانتباه إلى أنَّه بالرغم من إمكانيَّة تمرير عُقَد نصية (text nodes) وعُقَد تعليق (comment nodes) إلى مجموعة jQuery بهذه الطريقة إلا أنَّ أغلب العمليات لا تدعم ذلك. ستجد ملاحظةً واضحةً جليَّةً في صفحة توثيق العمليات التي تدعم هذا الأمر تشير إلى ذلك.

الاستعمال الشائع لبنية عنصر DOM واحد هو استدعاء توابع jQuery مع عنصرٍ مُرِّر إلى دالة رد نداء عبر الكلمة المحجوزة this مثل:

$( "div.foo" ).click(function() {
 $( this ).slideUp();
});

نتيجة هذا المثال هي إخفاء العناصر مع حركة انسحابيَّة عند الضغط عليها. بما أنَّ معالج الحدث يتلقى العنصر المضغوط عبر this كعنصر DOM مجرَّد، لذا يجب أن يمرَّر العنصر إلى الدالة ‎$()‎ قبل تطبيق توابع jQuery عليه. يمكن تمرير البيانات التي بصيغة XML والمعادة من استدعاء Ajax إلى الدالة ‎$()‎، لذا يمكن إعادة عناصر فرديَّة ذات البنية XML باستعمال التابع ‎.find()‎ وتوابع التنقل الأخرى (انظر التصنيف Traversing).

$.post( "url.xml", function( data ) {
 var $child = $( data ).find( "child" );
});

نسخ كائنات jQuery

عندما يمرَّر كائن jQuery إلى الدالة ‎$()‎، فسيُنشأ نسخة عنه، إذ يشير كائن jQuery الجديد هذا إلى عناصر DOM ذاتها التي يشير إليها الكائن الأول.

إعادة مجموعة فارغة

بدءًا من الإصدار jQuery 1.4، يعيد استدعاء التابع jQuery()‎ دون وسائط مجموعة jQuery فارغة. أمَّا في الإصدارات السابقة، فسيعيد هذا الاستدعاء مجموعةً تحتوي على العقدة document.

العمل مع كائنات مجرَّدة

العمليات المدعومة حاليًا على كائنات JavaScript المجرَّدة والمغلَّفة في jQuery هي: ‎.data()‎، و ‎.prop()‎، و ‎.on()‎، و ‎.off()‎، و ‎.trigger()‎، و ‎.triggerHandler()‎ فقط. سيؤدي استعمال التابع ‎.data()‎ (أو أي تابع يحتاج التابع ‎.data()‎) مع كائن مجرَّد إلى ظهور خاصِّيَّة جديدة في الكائن تدعى jQuery{randomNumber}‎ (مثل jQuery123456789).

// تعريف كائن مجرَّد
var foo = { foo: "bar", hello: "world" };
 
// jQuery تمرير هذا الكائن إلى دالة
var $foo = $( foo );
 
// التحقق من إمكانية الوصول إلى قيم الخاصِّيَّّات
var test1 = $foo.prop( "foo" ); // bar
 
// التحقق من إمكانية تغيير قيم الخاصِّيَّّات
$foo.prop( "foo", "foobar" );
var test2 = $foo.prop( "foo" ); // foobar
 
// كما شُرح آنفًا .data() التحقق من استخدام التابع
$foo.data( "keyName", "someValue" );
console.log( $foo ); // jQuery{randomNumber} سيحتوي الآن على الخاصية

// التحقق من إمكانية ربط حدث واستدعائه 
$foo.on( "eventName", function () {
  console.log( "eventName استُدعي الحدث" );
});
 
$foo.trigger( "eventName" ); // “eventName ستظهر الرسالة “استُدعي الحدث

يجب استعمال ‎.trigger( "eventName" )‎ من أجل البحث عن الخاصِّيَّة "eventName" في الكائن ثمَّ محاولة تنفيذها بعد تنفيذ أيَّة معالجات أحداث مرتبطة به. لن يُتحقَّق من كون الخاصِّيَّة دالةً أم لا. يمكن تجنب هذا السلوك باستعمال ‎.triggerHandler( "eventName" )‎ عوضًا عن ذلك.

$foo.triggerHandler( "eventName" ); // أيضًا "eventName ستظهر الرسالة "استُدعي الحدث

أمثلة

إيجاد جميع العناصر <p> التي تعد عناصر أبناء للعنصر <div> ثمَّ إضافة إطار لها:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery مثالٌ عن استعمال الدالة</title>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>واحد</p>
<div><p>اثنان</p></div>
<p>ثلاثة</p>
 
<script>
$( "div > p" ).css( "border", "1px solid gray" );
</script>
 
</body>
</html>

إيجاد جميع عناصر الإدخال <input> التي من النوع "radio" ضمن النموذج الأول في الصفحة:

$( "input:radio", document.forms[ 0 ] );

إيجاد جميع العناصر <div> الواقعة ضمن مستند XML من طلب Ajax:

$( "div", xml.responseXML );

تغيير لون خلفية الصفحة إلى الأسود:

$( document.body ).css( "background", "black" );

إخفاء جميع عناصر الإدخال <input> ضمن النموذج:

$( myForm.elements ).hide();

‎jQuery( html [, ownerDocument ] )‎

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

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

الوصف

تنشئ هذه الدالة عناصر DOM من السلسلة النصية المُعطاة التي تحتوي على HTML صرفة.

‎jQuery( html [, ownerDocument ] )‎

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

html

سلسلة نصية ذات محتوى HTML. انتبه إلى أنَّ الدالة تحلِّل محتوى HTML فقط ولا تحلِّل محتوى XML.

ownerDocument

المستند الذي سيُنشَأ العنصر الجديد ضمنه.

jQuery( html, attributes )‎

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

html

سلسلة نصية تحتوي على عنصر HTML وحيد مستقل مثل <div /‎> أو <div></div>.

attributes

كائنٌ يضم خاصِّيَّات (attributes)، وأحداث، وتوابع يراد استدعاؤها مع العنصر المنشأ حديثًا.

إنشاء عناصر جديدة

إن مُرَّرت سلسلة نصية إلى الدالة ‎$()‎ كوسيط، فستفحص jQuery محتوى هذه السلسلة لتتحقَّق إن كان شبيهًا بمحتوى HTML (مثل أن يبدأ بوسم <tag>). إن لم يكن شبيهًا بمحتوى HTML، فستُفسَّر السلسلة النصية على أنَّها تعبير محدِّد كما شرحنا ذلك منذ قليل. أمَّا إن عُثر على دليل يؤكِّد تشابه محتوى السلسلة مع أجزاءٍ من HTML، فستحاول jQuery أن تنشئ عناصر DOM جديدة بالشكل الذي أعطيت ووصفت فيه ثمَّ تنشئ كائن jQuery يشير إلى تلك العناصر. يمكن استعمال هذا الكائن المعاد مع توابع jQuery الاعتياديَّة مثل:

$( "<p id='test'>هذا <em>محتوى</em> جديد</p>" ).appendTo( "body" );

من أجل تفسير السلسلة النصية على أنَّها HTML بالتحديد، استعمل التابع ‎$.parseHTML()‎. تُنشأ العناصر افتراضيًّا حيث يتطابق ‎.ownerDocument مع المستند الذي حُمِّلت مكتبة jQuery إليه. يمكن إضافة العناصر إلى مستند آخر شرط أن تُنشَأ هذه العناصر باستعماله مثل:

$("<p>iframe مرحبًا أيها المستند</p>", $("#myiframe").prop("contentWindow").document);

عندما يزيد تعقيد محتوى HTML عن وسم واحد لا يملك أيَّة خاصِّيَّة -كما في المثال السابق-، فستُعالج عملية إنشاء العناصر بوساطة الآلية ‎.innerHTML في المتصفح. تنشئ jQuery في أغلب الحالات عنصرًا جديدًا من النوع <div> وتسند محتوى HTML المعطى إلى الخاصِّيَّة innerHTML لهذا العنصر. إن كان الوسيط المعطى يحتوي على وسمٍ واحدٍ (سواءً أضيف إليه وسم الإغلاق الاختياري أم لا مثل ‎ $( "<a></a>"‎ )‎ أو ‎$( "<a>"‎ )‎ أو استُعمِل الوسم المختصر بدلًا عنه مثل ‎$( "<img />"‎ )‎)، فستنشئ jQuery العنصر باستعمال الدالة ‎.createElement()‎ الأساسيَّة في JavaScript.

قد لا تولِّد بعض المتصفحات أحيانًا عناصر DOM تماثل تمامًا محتوى HTML المعطى عندما يكون هذا المحتوى الممرَّر معقدًا، إذ ذُكر قبل قليل أنَّ jQuery تستعمل الخاصِّيَّة ‎.innerHTML في المتصفح لتحلِّل محتوى HTML المعطى وتضيفه إلى المستند الحالي. ترشِّح بعض المتصفحات خلال هذه العمليَّة عناصر محدَّدة مثل العنصر <html>، والعنصر <title>، والعنصر <head>، وسيؤدي ذلك إلى أنَّ العناصر المضافة إلى المستند قد لا تماثل السلسلة النصية الأصليَّة الممرَّرة.

من جهة أخرى، ترشيح العناصر لا يقتصر على الوسوم الثلاثة تلك، فكان المتصفح IE قبل الإصدار 8 مثلًا يحوِّل جميع الخاصِّيَّات href في الروابط إلى عناوين URL مطلقة، وكان قبل الإصدار 9 لا يعالج عناصر HTML5 بشكل صحيح دون وجود طبقة إضافية منفصلة للتوافقية.

إن أردت التأكد من توافقية محتوى HTML مع جميع المنصات، فيجب أن يكون هذا المحتوى مكتوبًا ومنسقًا بأفضل شكل، إذ يجب على الوسوم التي يمكن أن تحتوي عناصر أخرى أن تقترن بوسم إغلاق مثل:

$( "<a href='https://jquery.com'></a>" );

أمَّا الوسوم التي لا يمكن أن تحتوي على أية عناصر أخرى، فيُقبل أن لا تقترن بوسم إغلاق:

$( "<img>" );
$( "<input>" );

عند تمرير محتوى HTML إلى jQuery()‎، لاحظ أنَّه لا تُعامَل العقد النصية بوصفها عناصر DOM. هنالك بعض الاستثناءات لقلة قليلة من التوابع مثل التابع ‎.content()‎ التي تتجاهل أو تحذف تلك العقد النصية. انظر إلى المثال التالي:

var el = $( "<br>2<br>3" ); // [<br>, "2", <br>]
el = $( "<br>2<br>3 >" ); // [<br>, "2", <br>, "3 &gt;"]

لذا، يجب أن يكون هذا السلوك متوقعًا. بدءًا من الإصدار jQuery 1.9.0 (وما لم تُستعمل الإضافة jQuery Migrate)، أصبحت jQuery تتطلب أن تبدأ السلسلة النصية بالمحرف >، لذا لم يعد بالإمكان ظهور عقد نصية في مقدمة محتوى HTML المعطى مثلًا.

بدءًا من الإصدار jQuery 1.4، أصبح الوسيط الثاني في jQuery()‎ يقبل كائن مجرَّد يحتوي على مجموعة تضم مجموعات فرعيَّة من الخاصِّيَّات التي يمكن تمريرها إلى التابع ‎.attr()‎.

ملاحظة مهمة: إن مُرِّر الوسيط الثاني، فينبغي على محتوى HTML المعطى في الوسيط الأول أن يمثل عنصرًا بسيطًا دون أية خاصِّيَّات. بدءًا من الإصدار jQuery 1.4، أصبح بالإمكان تمرير أي نوع من أنواع الأحداث بالإضافة إلى إمكانيَّة استدعاء توابع jQuery التالية: val، أو css، أو html، أو text، أو data، أو width، أو height، أو offset.

بدءًا من الإصدار jQuery 1.8، يمكن استعمال أي نسخة من توابع jQuery (تابعًا إلى jQuery.fn) كخاصِّيَّة للكائن الممرَّر إلى الوسيط الثاني:

$( "<div></div>", {
  "class": "my-div",
  on: {
    touchstart: function( event ) {
      // افعل شيئًا
    }
  }
}).appendTo( "body" );

يجب أن يكون الاسم "class" مقتبسًا ضمن الكائن بما أنَّه كلمة محجوزة في JavaScript، ولا يمكن استعمال "className" إذ يشير إلى خاصِّيَّة DOM (خاصية كائنية [property] وليس خاصِّيَّة ‎[attribute] HTML). لمَّا كان الوسيط الثاني سهل الاستعمال، فقد تؤدي مرونته الكبيرة إلى الحصول على نتائج غير متوقعة مثل أن يستدعي الشكل ‎$( "<input>", {size: "4"}‎ )‎ التابع size()‎. بدلًا من ضبط قيمة الخاصية size. بناءً على ذلك، يمكن أن يكتب المثال السابق بالشكل التالي:

$( "<div></div>" )
  .addClass( "my-div" )
  .on({
    touchstart: function( event ) {
      // Do something
    }
  })
    .appendTo( "body" );

أمثلة

إنشاء عنصر <div> مع جميع محتوياته بشكل ديناميكي وإضافته إلى العنصر <body>، إذ سينشأ العنصر داخليًا ثم ستُضبط قيمة الخاصِّيَّة innerHTML له إلى محتوى HTML المعطى:

$( "<div><p>مرحبًا</p></div>" ).appendTo( "body" );

إنشاء بعض عناصر DOM:

$( "<div/>", {
  "class": "test",
  text: "Click me!",
  click: function() {
    $( this ).toggleClass( "test" );
  }
})
  .appendTo( "body" );

‎jQuery( callback )‎

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

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

الوصف

تربط هذه الدالة دالةً معينة يراد تنفيذها بعد انتهاء تحميل DOM.

‎jQuery( callback )‎

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

callback

دالة من الشكل Function()‎ وتمثل الدالة المراد تنفيذها عندما تصبح DOM جاهزة.

تسلك هذه الدالة سلوكًا شبيهًا لسلوك التابع ‎$( document ).ready()‎، إذ تستعمل لتغليف عمليات أخرى للدالة ‎$()‎ في الصفحة التي تعتمد على جاهزية DOM.

أمثلة

تنفيذ دالة محدَّدة عندما تصبح DOM جاهزة للاستخدام:

$(function() {
 // أصبحت الصفحة جاهزة
});

استعمال اختصار للشكل ‎$(document).ready()‎ ووسيط لكتابة شيفرة الفشل الآمن (failsafe) في jQuery عبر الاسم البديل $ ودون الاعتماد على الاسم البديل العام:

jQuery(function( $ ) {
 // اكتب هنا الشيفرة التي ستُستعمل في حالة الفشل الآمن
});

مصادر

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