jQuery/Topics

أساس jQuery

تشكل التوابع والدوال الموجودة في هذا القسم أساس مكتبة jQuery.

المحددات

توفر مكتبة jQuery مجموعة قوية من الأدوات لمطابقة العناصر وتحديدها في الصفحة، إذ استفادت المكتبة من CSS بجميع إصداراتها.

من أجل استعمال المحارف الخاصة (مثل !"#$%&'()*+,./:;<=>?@[\]^`{|}~) كجزء صرف من الاسم المراد تحديده، يجب أن تهرب تلك المحارف عبر \\. على سبيل المثال، إن كان اسم العنصر المراد تحديده هو id="foo.bar"، يمكنك تحديده عبر المُحدِّد $("#foo\\.bar"). تحوي مواصفات CSS القياسية (أي W3C CSS specification) مجموعة كاملة من القواعد المتعلقة بالمحددات الصالحة. هنالك أيضًا مقالة مفيدة لصاحبها Mathias Bynens تتحدث عن تهريب سلسلة من الحارف في CSS.

التنقل بين العناصر

تتيح التوابع في هذا القسم بتحديد عناصر موجودة في موضع محدد والتنقل بينها.

تعديل العناصر

جميع التوابع في هذا القسم تعدل وتتلاعب بشجرة DOM عبر تعديل عنصر (أو مجموعة من العناصر) بأكمله وبذاته مثل الإضافة، أو النسخ، أو الحذف، أو الإزالة ...إلخ. (إن كنت تبحث عن توابع تعدل خاصية عنصر، فانتقل إلى قسم «تعديل الخاصيات»).

تعديل الخاصيات

جميع التوابع في هذا القسم تعدل وتتلاعب بشجرة DOM عبر تعديل خاصية محددة لعنصر (أو مجموعة من العناصر). توصف أغلبية هذه التوابع على أنها «توابع ضابطة» (setters)، إذ تضبط وتغير قيمة خاصية محددة. هنالك قلة من هذه التوابع توصف على أنها «توابع جالبة» (getters) مثل ‎.attr()‎ و ‎.html()‎ و ‎.val()‎ لأنها تجلب معلومات من عناصر DOM لاستخدامها لاحقًا. (إن كنت تود إجراء تعديل على العنصر نفسه، فارجع إلى قسم «تعديل العناصر»).

التأثيرات والحركات

توفر مكتبة jQuery عدة تقنيات من أجل إضافة حركات إلى صفحة الويب. المحركات المشمولة هي الحركات البسيطة (simple animations) والحركات القياسية (standard animations) المستخدمة بكثرة بالإضافة إلى توفير إمكانية لإنشاء وإضافة حركات مخصصة.

الأحداث

تُستخدَم التوابع الموجودة في هذا القسم لتسجيل سلوكيات محدَّدة تحدث عندما وقع حدث معين ناتج عن تفاعل المستخدم مع المتصفح. أضف إلى ذلك وجود توابع تساعد على التعديل والتلاعب بتلك السلوكيات المسجلة مسبقًا.

التعامل مع البيانات

يوفر هذا القسم مجموعة من التوابع التي تستعمل من أجل ربط بيانات محدَّدة مع عنصر محدَّد (أو مجموعة عناصر محدَّدة) وقراءة تلك البيانات لاحقًا.

`‎.data()‎`

يخزِّن التابع ‎.data()‎ بيانات عشوائية مرتبطة بالعناصر المتطابقة أو تُعيد القيمة في مخزن البيانات المحدد للعنصر الأول في مجموعة العناصر المتطابقة.

`‎jQuery.data()‎`

يخزِّن هذا التابع بيانات اعتباطيَّة ويقرنها بعنصر محدَّد، ويعيد القيمة التي ضُبِطَت.

`‎jQuery.hasData()‎`

يتحقَّق هذا التابع إن كان يملك عنصرٌ محدَّدٌ أيَّةَ بياناتٍ مرتبطةٍ به.

`jQuery‎.proxy()‎`

يأخذ هذا التابع دالةً ويعيد أخرى جديدة تحوي محتوًى محددًّا.

`‎jQuery.removeData()‎`

يحذف هذا التابع جزءًا من البيانات المُخزَّنة مسبقًا والمرفقة بعنصر محدَّد.

`‎.removeData()‎`

يحذف هذا التابع جزءًا من البيانات المخزَّنة مسبقًا.

خدمات jQuery

توفر التوابع الموجودة في هذا القسم بعض عدة خدمات ووظائف متنوعة. يصعب حصرها في تصنيف أو قسم واحد.

`‎jQuery.dequeue()‎`

ينفَّذ هذا التابع الدالة التالية الموجودة في طابور الانتظار للعناصر المتطابقة.

`‎jQuery.each()‎`

هذه الدالة هي دالة تكرار عامة تستعمل لتكرار تنفيذ دالة بسلاسة تامة عبر الكائنات والمصفوفات. عدد مرات تكرار تنفيذ الدالة على المصفوفات والكائنات الشبيهة بالمصفوفات التي لها الخاصِّيَّة length (مثل الكائن الذي يحوي وسائط دالةٍ) تنحصر بالمجال من 0 إلى length-1، إذ length هو عدد العناصر. أمَّا عدد مرات تكرار الكائنات الأخرى تتعلق بالخصائص المسماة للكائن.

`‎jQuery.fn.extend()‎`

يدمج هذا التابع محتويات كائنٍ مع الكائن prototype في jQuery لتوفير نسخةٍ جديدةٍ من توابع jQuery.

`‎jQuery.globalEval()‎`

يُنفِّذ هذا التابع جزءًا من شيفرة JavaScript على الصعيد العام.

`‎jQuery.grep()‎`

يبحث هذا التابع عن عناصر مصفوفة تتطابق مع الدالة المرشِّحة المعطاة ثمَّ يعيد هذه العناصر بطريقة لا تتأثر فيها المصفوفة الأصليَّة.

`‎jQuery.inArray()‎`

يبحث هذا التابع عن قيمة محدَّدة ضمن مصفوفةٍ ثمَّ يعيد قيمة فهرس موضعها (أو القيمة ‎-1 إن لم يجدها).

`‎jQuery.isArray()‎`

يتحقَّق هذا التابع إن كان الوسيط الممرَّر إليه مصفوفةً أم لا.

`‎jQuery.isEmptyObject()‎`

يتحقَّق هذا التابع إن كان الكائن المُمرَّر إليه فارغًا (لا يحوي أيَّة خاصِّيَّة قابلة للإحصاء) أم لا.

`‎jQuery.isFunction()‎`

يتحقَّق هذا التابع إن كان الكائن الممرَّر إليه دالةَ ردِّ نداءٍ أم لا.

`‎jQuery.isNumeric()‎`

يتحقَّق هذا التابع إن كان الكائن الممرَّر إليه عددًا (Number) أم لا.

`‎jQuery.isPlainObject()‎`

يتحقَّق هذا التابع إن كان الكائن الممرَّر إليه كائنًا مجرَّدًا (أُنشئ باستعمال "{}" أو "new Object") أم لا.

`‎jQuery.isWindow()‎`

يتحقَّق هذا التابع إن كان الوسيط الممرَّر إليه هو الكائن window أم لا.

`‎jQuery.isXMLDoc()‎`

يتحقَّق هذا التابع إن كانت عقدة DOM المُمرَّر إليه ضمن مستند XML (أو هل هو مستند XML) أم لا.

`‎jQuery.makeArray()‎`

يحوِّل هذا التابع كائنًا شبيهًا بمصفوفة إلى مصفوفة JavaScript حقيقية.

`‎jQuery.map()‎`

يُمرِّر هذا التابع كلَّ عنصر من عناصر مصفوفة أو كائن إلى دالةٍ، ثمَّ ينشئ مصفوفةً جديدةً تحتوي على القيم المعادة.

`‎jQuery.merge()‎`

تدمج هذه الدالة محتوى مصفوفتين مع بعضهما بعضًا وتضع الناتج في المصفوفة الأولى.

`‎jQuery.noop()‎`

هذه الدالة هي دالةٌ فارغةٌ.

`‎jQuery.now()‎`

يعيد هذا التابع عددًا يمثِّل الوقت الحالي.

`‎jQuery.parseHTML()‎`

يفسِّر هذا التابع سلسلة نصية تحتوي على شيفرة HTML ثمَّ يعيد مصفوفة من عقد DOM.

`‎jQuery.parseJSON()‎`

يعيد مصفوفةً (Array) أو سلسلةً نصيةً (String) أو عددًا (Number) أو كائنًا (Object) أو قيمة منطقيَّة (Boolean).

`jQuery‎.parseXML()‎`

يفسِّر هذا التابع سلسلة نصية بصيغة XML إلى مستند XML.

`‎jQuery.trim()‎`

يزيل هذا التابع جميع المسافات البيضاء (whitespace) من بداية ونهاية السلسلة النصية المُمرَّرة إليه.

`‎jQuery.type()‎`

يعيد هذا التابع نوع JavaScript الداخلي للكائن المُمرَّر إليه.

`‎jQuery.unique()‎`

يرتِّب هذا التابع مصفوفةً من عناصر DOM، في مكانها، مع حذف العناصر المتكرِّرة. انتبه إلى أنَّ هذا التابع لا يصلح للعمل إلا مع المصفوفات التي تحوي عناصر DOM فقط.

`‎jQuery.uniqueSort()‎`

يرتِّب هذا التابع مصفوفةً من عناصر DOM، في مكانها، مع حذف العناصر المتكرِّرة. انتبه إلى أنَّ هذا التابع لا يصلح للعمل إلا مع المصفوفات التي تحوي عناصر DOM فقط.

التعامل مع CSS

تعمل التوابع الموجودة في هذا القسم على جلب وضبط قيم خاصيات CSS لعنصر محدَّد (أو مجموعة عناصر محدَّدة).

`‎.height()‎`

يجلب هذا التابع الطول الحالي لأول عنصر في مجموعة العناصر المتطابقة أو يغير الطول لكل العناصر المتطابقة.

`‎.innerHeight()‎`

يعيد هذا التابع قيمة الطول الحالي (تتضمن قيمة الحواشي فقط دون الإطار) لأول عنصر في مجموعة العناصر المطابقة أو يغير الطول الداخلي لكل العناصر المطابقة.

`‎.innerWidth()‎`

يعيد هذا التابع قيمة العرض الحالي (تدخل قيمة الحواشي ضمنها فقط) لأول عنصر من مجموعة العناصر المطابقة أو يغير العرض الداخلي لكل العناصر المطابقة.

`‎jQuery.cssHooks()‎`

يتعلَّق هذا التابع بـ jQuery مباشرةً للتحكم بكيفيَّة استعادة أو ضبط قيم خاصِّيَّات CSS محدَّدة، أو توحيد أسماء خاصِّيَّات CSS، أو إنشاء خاصِّيَّات CSS مخصَّصة.

`‎jQuery.cssNumber()‎`

يعيد هذا التابع كائنًا يحتوي على جميع خاصِّيَّات CSS التي يمكن استعمالها دون واحدة. يستعمل التابع ‎.css()‎ هذا الكائن ليتحقَّق إن كان بإمكانه إضافة الواحدة px إلى القيم المعطاة دون واحدة.

`‎jQuery.escapeSelector()‎`

يهرِّب هذا التابع مجموعةً من المحارف التي تشبه اسم محدِّد في CSS.

`‎.offset()‎`

يجلب هذا التابع الإحداثيات الحاليَّة للعنصر الأول في مجموعة العناصر المطابقة نسبةً إلى الصفحة.

`‎.outerHeight()‎`

يجلب هذا التابع قيمة الارتفاع الخارجي (outer height، تتضمن الحواشي [padding]، والإطار [border]، والهامش [margin] اختياريًّا) الحاليَّة لأول عنصر في مجموعة العناصر المطابقة، أو يغير قيمة الارتفاع الخارجي لكل العناصر المطابقة.

`‎.outerWidth()‎`

يجلب هذا التابع قيمة العرض الخارجي (outer width، تتضمن الحواشي [padding]، وحدَّ الإطار [border]، والهامش [margin] اختياريًّا) الحاليَّة لأول عنصر في مجموعة العناصر المطابقة، أو يغير قيمة العرض الخارجي لكل العناصر المطابقة.

`‎.position()‎`

يجلب هذا التابع الإحداثيات الحالية للعنصر الأول في المجموعة المطابقة نسبةً إلى أقرب عنصر أب متموضع (offset parent) لذلك العنصر.

`‎.scrollLeft()‎`

يجلب هذا التابع موضع شريط التمرير الأفقي الحالي للعنصر الأول من مجموعة العناصر المطابقة.

`‎.scrollTop()‎`

يجلب هذا التابع موضع شريط التمرير الشاقولي الحالي للعنصر الأول من مجموعة العناصر المطابقة.

`‎.width()‎`

إعادة العرض الحالي المحسوب للعنصر الأول من مجموعة العناصر المُطابقة، أو ضبط عرض CSS لكل عنصر في مجموعة العناصر المُطابقة.

التعامل مع Ajax

تحوي مكتبة jQuery على مجموعة كاملة من الأدوات المخصصة للتعامل مع Ajax. التوابع والدوال الموجودة في هذا القسم تسمح لك مثلًا بتحميل بيانات من الخادم دون تحديث المتصفح صفحة الويب.

`‎.ajaxComplete()‎`

يُسجِّل هذا التّابع مُعالِج الأحداث (Event handler) لاستدعائه عند اكتمال طلبات Ajax.

`‎.ajaxError()‎`

يُسجِّل هذا التّابع مُعالِج الأحداث (Event handler) لاستدعائه عند اكتمال تنفيذ طلب Ajax مع حدوث خطأ.

`‎.ajaxSend()‎`

يُرفِق هذا التّابع دالة لتنفيذها قبل إرسال طلب Ajax.

`‎.ajaxStart()‎`

يُسجِّل هذا التّابع مُعالِج الأحداث (Event handler) لاستدعائه عند بدء أول طلب Ajax.

`‎.ajaxStop()‎`

يُسجِّل هذا التّابع مُعالِج الأحداث (Event handler) لاستدعائه عند اكتمال تنفيذ جميع طلبات Ajax.

`‎.ajaxSuccess()‎`

يُرفِق هذا التّابع دالة لتنفيذها عند اكتمال تنفيذ طلب Ajax.

`‎jQuery.ajax()‎`

ترسل هذه الدالة طلب ‎(Ajax) HTTP غير متزامن.

`‎jQuery.ajaxPrefilter()‎`

يعالج هذا التابع إعدادات Ajax المخصَّصة أو يعدِّل إعدادات موجودة قبل أن يرسل كل طلب وقبل أن يعالج باستعمال الدالة ‎$.ajax()‎.

`‎jQuery.ajaxSetup()‎`

يعيِّن هذا التابع قيمًا افتراضيَّة لطلبات Ajax المستقبليَّة، ولا ينصح باستعماله.

`‎jQuery.ajaxTransport()‎`

ينشئ هذا التابع كائنًا يعالج عملية الإرسال الفعلي لبيانات Ajax.

`‎jQuery.get()‎`

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

`‎jQuery.getJSON()‎`

تجلب هذه الدالة بياناتٍ مرمَّزة بصيغة من الخادم باستعمال طلب عبر الطريقة .

`‎jQuery.getScript()‎`

يجلب هذا التابع ملف JavaScript من الخادم باستعمال طلب HTTP عبر الطريقة GET ثمَّ يُنفِّذه.

`‎jQuery.param()‎`

يرمِّز (serialize) هذا التابع محتويات مصفوفة، أو كائن مجرَّد، أو كائن jQuery ويضعها في سلسلة نصيَّة لتصبح ملائمة لاستعمالها في سلسلة الاستعلام النصية لعنوان URL أو لإرسالها في طلبات Ajax. في حال تمرير كائن jQuery، فيجب أن يحوي هذا الكائن عناصر إدخال <input> لها خاصِّيَّات بالشكل اسم/قيمة.

`‎jQuery.post()‎`

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

`‎.load()‎`

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

`‎.serialize()‎`

يُرمِّز هذا التابع مجموعة من عناصر النماذج ويضعها في سلسلة نصيِّة من أجل إرسالها.

`‎.serializeArray()‎`

يُرمِّز هذا التابع مجموعة من عناصر النماذج ويضعها في مصفوفة على شكل أسماء وقيم من أجل إرسالها.

الكائن Callbacks

تعيد الدالة jQuery.Callbacks()‎، التي عُرِّفت في الإصدار 1.7، كائنًا متعدد الأغراض يوفر وسيلةً قوية لإدارة قائمة ردود النداء. تدعم هذه الدالة إضافة، وحذف، وإطلاق، وتعطيل ردود النداء.

`callbacks.add()‎`

يُضيف رد نداء أو مجموعة من ردود النداء إلى قائمة ردود النداء.

`‎callbacks.disable()‎`

يُعطِّل قائمة ردود النداء ويمنعها من فعل أي شيء آخر.

`‎callbacks.disabled()‎`

يُحدِّد ما إذا كانت قائمة ردود النداء مُعطَّلة.

`‎callbacks.empty()‎`

يُزيل كافّة ردود النداء من القائمة.

`‎callbacks.fire()‎`

يستدعي كافّة ردود النداء عن طريق الوسائط المُعطاة.

`‎callbacks.fired()‎`

يُحدِّد ما إذا كانت ردود النداء قد استُدعيَت على الأقل مرّة واحدة.

`‎callbacks.fireWith()‎`

يستدعي كافّة ردود النداء في القائمة عن طريق السّياق (context) والوسائط المُعطاة.

`‎callbacks.has()‎`

يُحدِّد ما إذا كانت قائمة ردود النداء تملك أي رد نداء مُرفَق إليها. وإن زوّدناه باسم رد نداء كوسيط فسيُحدِّد ما إذا كان موجودًا في القائمة.

`callbacks.lock()‎`

يقفل قائمة ردود النداء بحالتها الحاليّة.

`‎callbacks.locked()‎`

يُحدِّد ما إذا كانت قائمة ردود النداء مُقفلة.

`‎callbacks.remove()‎`

يُزيل رد نداء أو مجموعة ردود نداء من قائمة ردود النداء.

`‎jQuery.Callbacks()‎`

تعيد هذه الدالة كائنًا مُتعدِّد الأغراض يُزوِّدنا بطريقة فعَّالة لإدارة قائمة ردود النداء.

الكائن `Deferred`

الكائن المؤجل Deferred، الذي عُرِّف في الإصدار 1.5، هو كائن أداةٍ قابل للتسلسل (chainable utility object) يُنشَأ عبر استدعاء التابع jQuery.Deferred(). يستطيع هذا الكائن تسجيل عدة ردود نداء إلى طابور ردود النداء (callback queues)، واستدعاء ردود النداء الموجودة في هذا الطابور، والاعتماد على حالة النجاح (success state) أو الفشل (failure state) لأي دالة متزامنة (synchronous) أو غير متزامنة (asynchronous).

الكائن المؤجل Deferred قابل للتسلسل بشكل مشابه لقابلية تسلسل الكائن jQuery باستثناء أنه يملك توابعًا خاصة به. بعد إنشاء كائن من النوع Deferred، يمكنك استعمال أي من التوابع المذكورة في هذا القسم إمَّا باستدعائها مباشرةً على الكائن المنشَأ أو بحفظ الكائن في متغير واستدعاء تابع أو أكثر على ذلك المتغير.

`deferred.always()‎`

يُضيف هذا التابع معالجات تُستدعَى عند حل الكائن المؤجل Deferred أو رفضه.

`‎deferred.catch()‎`

يُضيف هذا التابع معالجات تُستدعى عند رفض الكائن المؤجل Deferred.

`‎deferred.done()‎`

يُضيف هذا التابع معالجات تستدعى عند حل الكائن المؤجل Deferred.

`deferred‎.fail()‎`

يُضيف هذا التابع معالجات تُستدعى عند رفض الكائن المؤجل Deferred.

`‎deferred.notify()‎`

يستدعي هذا التابع progressCallbacks لكائن مؤجل Deferred بواسطة الوسائط args المعطاة.

`‎deferred.notifyWith()‎`

يستدعي هذا التابع progressCallbacks لكائن مؤجل Deferred بواسطة الوسائط args والسياق context المعطاة.

`deferred‎.pipe()‎`

تابع أداة يُستخدم لترشيح و/أو تقييد الكائنات المؤجلة Deferreds.

`‎deferred.progress()‎`

يُضيف هذا التابع معالجات تستدعى عندما ينتج الكائن المؤجل Deferred إشعارات التقدُّم.

`‎deferred.promise()‎`

يُعيد هذا التابع كائن Promise للكائن المؤجل Deferred.

`‎deferred.reject()‎`

يرفُض هذا التابع كائنًا مؤجلًا ويستدعي أي failCallbacks مع الوسيط args المُعطى.

`deferred‎.rejectWith()‎`

يرفض هذا التابع كائنًا مؤجلًا Deferred ويستدعي أي failCallbacks مع سياق context ووسائط args محددة.

`‎deferred.resolve()‎`

قبول كائن مؤجل واستدعاء أي doneCallbacks مع الوسائط args المُحدَدة.

`‎deferred.resolveWith()‎`

يقبل كائن مؤجل ويستدعي أي doneCallbacks مع السياق context والوسائط args المُحدَدة.

`‎deferred.state()‎`

يُحدد هذا التابع الحالة الحالية لكائن مؤجل.

`‎deferred.then()‎`

يُضيف هذا التابع معالجات تُستدعَى عند قبول الكائن المؤجل أو رفضه أو ما زال قيد التقدم.

`‎jQuery.Deferred()‎`

هذه الدالة هي دالةٌ منتجة (factory function) تعيد كائن أداةٍ قابل للتسلسل (chainable utility object) يمكن استعمال مجموعة من التوابع مع هذا الكائن لتسجيل عدَّة دوال رد نداءٍ في طوابير ردود النداء (callback queues)، واستدعاء هذه الطوابير فيما بعد، ونقل حالة النجاح (success state) أو الفشل (failure state) لأي دالة متزامنة (synchronous) أو غير متزامنة (asynchronous).