Bootstrap/javascript

أنعش Bootstrap بملحقات JavaScript الاختيارية المبنية على jQuery. احصُل على معلومات عن كل ملحق، خيارات البيانات وواجهة التطبيقات البرمجية API وأمور أخرى.

فردية أو مجمَّعة

يمكن تضمين ملحقات فرديَّا (باستخدام ملفات *.js مُفرَدة من مجلّد Bootstrap) أو تضمين جميع الملحقات دفعة واحدة بالملف bootstrap.js أو نسخته المصغَّرة bootstrap.min.js (لا تضمّن الاثنين معا).

الاعتماديّات

تعتمد بعض المحلقات وعناصر CSS على ملحقات أخرى. تأكّد عند تضمين الملحقات فرديًّا من التحقّق من الاعتماديّات في التوثيقات. انتبه كذلك إلى أن الملحقات جميعها تعتمد على jQuery (يعني هذا أنه يجب تضمين jQuery قبل ملفات الملحقات). راجع الملف package.json لرؤية إصدارات jQuery المدعومة.

تعتمد القوائم المنسدلة Dropdowns، التلميحات المنبثقة Popovers والتلميحات Tooltips جميعها على Popper.js.

خاصيّات البيانات

يمكن تفعيل ملحقات Bootstrap كلّها تقريبا وإعدادها بواسطة HTML وحده عن طريق خاصيّات البيانات (طريقة مطوّري Bootstrap التي يفضّلونها على استخدام JavaScript). تأكّد من استخدام مجموعة واحدة فقط من خاصيّات البيانات على عنصُر معيَّن (مثلا؛ لا يمكن إظهار تلميح وفتح نافذة شرطية Modal بنفس الزّر).

يُرغَب أحيانا في تعطيل الوظيفة المذكورة أعلاه. إن كنت ترغب في تعطيل واجهة التطبيقات البرمجية الخاصّة بخاصيّات البيانات فيمكنك ذلك بفصل جميع الأحداث في فضاء الأسماء data-api من المستند؛ على النحو التالي

$(document).off('.data-api')

كما يمكنك بدلا من ذلك استهداف ملحق محدَّد بذكر اسمه ضمن فضاء الأسماء data-api على النحو التالي:

$(document).off('.alert.data-api')

تنبيه: تأكّد من تخليص المحدّدات المخصَّصة مثل collapse:Example إن كنت تستخدمها، إذ أنها ستمرّ عبر jQuery.

الأحداث

يوفّر Bootstrap أحداثًا مخصَّصة لأغلب الإجراءات الفريدة للملحقات. تأتي هذه الأحداث عموما بصيغتيْن تُسمَّى الأولى بأفعال إنكليزية مصدرية (show) والثانية بأسماء مفعولة (shown). تُطلَق الصيغة الأولى عند بداية الحدث فيما تُطلَق الثانية بعد اكتمال الحدث.

توفّر جميع الأحداث التي تحمل أسماء بأفعال مصدرية التابع preventDefault() الذي يمنح إمكانية إيقاف الحدث قبل أن يبدأ. يؤدّي إرجاع القيمة false من مُعالج حدث Event handler إلى استدعاء preventDefault() تلقائيا.

$('#myModal').on('show.bs.modal', function (e) { 
   if (!data) return e.preventDefault() // يوقف إظهار نافذة شرطية 
})

واجهة تطبيقات برمجية

يرى فريق Bootstrap أنه يجب أن يكون المبرمج قادرا على استخدام جميع ملحقات Bootstrap ببساطة عن طريق واجهة JavaScript للتطبيقات. جميع واجهات التطبيقات البرمجية في Bootstrap هي توابع منفردة يمكن استدعاؤها بالتتالي وتُرجِع المجموعة التي نُفِّذت عليها الإجراءات:

$('.btn.danger').button('toggle').addClass('fat')

يجب أن تتلقّى جميع التوابع إما كائنَ خيارات اختياري، سلسلة محارف تستهدف تابعا مخصوصا أو لا شيء (وفي هذه الحالة يُلجَأ للسلوك المبدئي للملحَق):

$('#myModal').modal()                      // تُستهَل نافذة شرطية بالخيارات المبدئية 
$('#myModal').modal({ keyboard: false })   // تُستهَل نافذة شرطية بدون لوحة مفاتيح
$('#myModal').modal('show')                // تُستهَل نافذة شرطية بالتابع show وتُعرض مباشرة

يقدّم كلّ مُلحَق مشيّده Constructor الخام بالخاصيّة Constructor، مثلا $.fn.popover.Constructor. يمكنك الحصول على نسخة Instance مُلحَق مخصوصة من العنصُر مباشرة $('[rel="popover"]').data('popover').

الدوال غير المتزامنة والانتقالات

جميع توابع واجهة التطبيقات البرمجية غير متزامنة Asynchronous وتعود إلى المُستدعي مباشرة بعد بدء الانتقال ولكن قبل أن يكتمل.

يجب الإنصات إلى الحدث المُصاحب لاكتمال الانتقال إن كنت تريد تنفيذ إجراء بعد اكتمال الحدث.

$('#myCollapse').on('shown.bs.collapse', function (e) { // الإجراء المُراد تنفيذه بعد تمدّد المساحة القابلة للتقلّص })

علاوة على ذلك، يُتجاهل استدعاء تابع لا يزال في طور الانتقال.

$('#myCarousel').on('slid.bs.carousel', function (e) {
  $('#myCarousel').carousel('2') // ستنزلق الشريحة 2 فور اكتمال الانتقال إلى الشريحة 1
})

$('#myCarousel').carousel('1') // يبدأ الانزلاق إلى الشريحة 1 ويعود إلى المُستدعي
$('#myCarousel').carousel('2') // !! سيُتجاهل، إذ أن الانتقال إلى الشريحة 1 لم يكتمل بعد

الإعدادات المبدئية

يمكن تعديل الإعدادات المبدئية لمُلحَق بتغيير كائن Constructor.Default الخاصّ بالمُلحَق:

$.fn.modal.Constructor.Default.keyboard = false // يغيّر القيمة المبدئية للخيار `keyboard` في الملحق modal إلى false

بدون تداخل

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

var bootstrapButton = $.fn.button.noConflict() // يرجع $.fn.button إلى القيمة المُسنَدة إليه سابقا
$.fn.bootstrapBtn = bootstrapButton            // يسند وظيفة Bootstrap إلى $().bootstrapBtn

أعداد الإصدارات

يمكن الوصول إلى إصدار كل مُلحَق من ملحَقات Bootstrap عن طريق الخاصيّة VERSION في مشيّد المُلحَق. في ملحَق التلميحات tooltip على سبيل المثال:

$.fn.tooltip.Constructor.VERSION // => "4.0.0"

لا بدائل احتياطية في حال تعطيل JavaScript

لا تتوفّر ملحقات Bootstrap على بدائل احتياطية سلسلة للعمل عند تعطيل JavaScript. لتجربة مستخدم أفضل، استخدم <noscript> لتشرح للمستخدمين الوضعيّة وكيف يمكنكهم إعادة تفعيل JavaScript، أو استخدم بدائل احتياطية مخصَّصة.

تنبيه: مكتبات طرف ثالث

لا يدعم Bootstrap رسميا مكتبات JavaScript من طرف ثالث مثل Prototype أو jQuery UI. على الرغم من وجود التابع .noConflict والأحداث التابعة لفضاء أسماء؛ إلا أنه يمكن أن توجد مشاكل توافقية تتطلّب أن تجد لها حلا بنفسك.

Util

تعتمد جميع ملفات JavaScript في Bootstrap على الملف util.js ويجب أن يُضمَّن إلى جانب بقية ملفات JavaScript. إن كنت تستخدم النسخة المجمَّعة (أو المُصغَّرة) bootstrap.js فلا حاجة لتضمين الملف، إذ أنه موجود مسبقا.

يتضمّن util.js دوال خدمية ومساعدات أساسية لأحداث transitionEnd علاوة على مُحاكٍ لانتقالات CSS. تستخدم بقية الملحقات هذا الملف للتحقّق من دعم انتقالات CSS والتقاط الانتقالات العالقة.