عرض مصدر Bootstrap/javascript

<noinclude>{{DISPLAYTITLE:ملحقات JavaScript في إطار Bootstrap}}</noinclude>

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

== فردية أو مجمَّعة ==
يمكن تضمين ملحقات فرديَّا (باستخدام ملفات js مُفرَدة من مجلّد <code>Bootstrap</code>) أو تضمين جميع الملحقات دفعة واحدة بالملف <code>bootstrap.js</code> أو نسخته المصغَّرة <code>bootstrap.min.js</code> (لا تضمّن الاثنين معًا).
== الاعتماديّات ==
تعتمد بعض المحلقات وعناصر [[CSS]] على ملحقات أخرى. تأكّد عند تضمين الملحقات فرديًّا من التحقّق من الاعتماديّات في التوثيقات. انتبه كذلك إلى أنَّ '''الملحقات جميعها تعتمد على [[jQuery]]''' (يعني هذا أنه يجب تضمين [[jQuery]] قبل ملفات الملحقات). راجع الملف <code>package.json</code> لرؤية إصدارات [[jQuery]] المدعومة.

تعتمد [[Bootstrap/dropdowns|القوائم المنسدلة (Dropdowns)]]، [[Bootstrap/popovers|والعناصر المنبثقة (Popovers)]]، [[Bootstrap/tooltips|والتلميحات (Tooltips)]] جميعها على [https://popper.js.org/ Popper.js].

== خاصيّات البيانات ==
يمكن تفعيل ملحقات Bootstrap كلّها تقريبا وإعدادهًا بواسطة [[HTML]] وحده عن طريق خاصيّات البيانات (data attributes، وهي طريقة مطوّري Bootstrap التي يفضّلونها على استخدام [[JavaScript]]). تأكّد من '''استخدام مجموعة واحدة فقط من خاصيّات البيانات على عنصُر معيَّن''' (مثلاً؛ لا يمكن إظهار [[Bootstrap/tooltips|تلميح]] وفتح [[Bootstrap/modal|مربعات الحوار [Modal]]] بنفس الزّر).

يُرغَب أحيانًا في تعطيل الوظيفة المذكورة أعلاه. إن كنت ترغب في تعطيل واجهة التطبيقات البرمجية الخاصّة بخاصيّات البيانات فيمكنك ذلك بفصل جميع الأحداث في مجال الأسماء <code>data-api</code> من المستند؛ على النحو التالي:<syntaxhighlight lang="javascript">
$(document).off('.data-api')
</syntaxhighlight>كما يمكنك بدلًا من ذلك استهداف ملحق محدَّد بذكر اسمه ضمن فضاء الأسماء <code>data-api</code> على النحو التالي:<syntaxhighlight lang="javascript">
$(document).off('.alert.data-api')
</syntaxhighlight>'''تنبيه:''' تأكّد من تخليص المحدّدات المخصَّصة مثل <code>collapse:Example</code> إن كنت تستخدمها، إذ أنها ستمرّ عبر jQuery.

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

توفّر جميع الأحداث التي تحمل أسماء بأفعال مصدرية قدرةً على استعمال التابع <code>[[JavaScript/Event/preventDefault|preventDefault()‎]]</code> الذي يمنح إمكانية إيقاف الحدث قبل أن يبدأ. يؤدّي إرجاع القيمة <code>false</code> من مُعالج الأحداث (Event handler) إلى استدعاء التابع <code>preventDefault()‎</code> تلقائيًا.<syntaxhighlight lang="javascript">
$('#myModal').on('show.bs.modal', function (e) { 
   if (!data) return e.preventDefault() // يوقف إظهار نافذة شرطية 
})
</syntaxhighlight>

== واجهة تطبيقات برمجية ==
يرى فريق Bootstrap أنه يجب أن يكون المبرمج قادرًا على استخدام جميع ملحقات Bootstrap ببساطة عن طريق واجهة برمجية API باستخدام [[JavaScript]]. جميع الواجهات البرمجية في Bootstrap هي توابع منفردة يمكن استدعاؤها بالتتالي وتُرجِع المجموعة التي نُفِّذت عليها الإجراءات:<syntaxhighlight lang="javascript">
$('.btn.danger').button('toggle').addClass('fat')
</syntaxhighlight>يجب أن تتلقّى جميع التوابع إما كائنَ خيارات اختياري، أو سلسلة محارف تستهدف تابعًا مخصوصًا، أو لا شيء (وفي هذه الحالة يُلجَأ للسلوك المبدئي للملحَق):<syntaxhighlight lang="javascript">
$('#myModal').modal()                      // تُستهَل نافذة شرطية بالخيارات المبدئية 
$('#myModal').modal({ keyboard: false })   // تُستهَل نافذة شرطية بدون لوحة مفاتيح
$('#myModal').modal('show')                // تُستهَل نافذة شرطية بالتابع show وتُعرض مباشرة
</syntaxhighlight>يقدّم كلّ مُلحَق دالةً بانيةً (Constructor) في الخاصيّة <code>Constructor</code>، مثلا ‎<code>$.fn.popover.Constructor</code>. يمكنك الحصول على نسخة (Instance) مُلحَق مخصوصة من العنصُر مباشرة ‎<code>$('[rel="popover"]').data('popover')‎</code>.

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

يجب الإنصات إلى الحدث المُصاحب لاكتمال الانتقال إن كنت تريد تنفيذ إجراء بعد اكتمال الحدث.<syntaxhighlight lang="javascript">
$('#myCollapse').on('shown.bs.collapse', function (e) { // الإجراء المُراد تنفيذه بعد تمدّد المساحة القابلة للتقلّص })
</syntaxhighlight>علاوة على ذلك، '''يُتجاهل استدعاء تابع لا يزال في طور الانتقال'''.<syntaxhighlight lang="javascript">
$('#myCarousel').on('slid.bs.carousel', function (e) {
  $('#myCarousel').carousel('2') // ستنزلق الشريحة 2 فور اكتمال الانتقال إلى الشريحة 1
})

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

=== الإعدادات المبدئية ===
يمكن تعديل الإعدادات المبدئية لمُلحَق بتغيير كائن <code>Constructor.Default</code>  الخاصّ بالمُلحَق:<syntaxhighlight lang="javascript">
$.fn.modal.Constructor.Default.keyboard = false // يغيّر القيمة المبدئية للخيار `keyboard` في الملحق modal إلى false

</syntaxhighlight>

== مشكلة تداخل أسماء الدوال ==
يتوجّب أحيانًا استخدام ملحقات Bootstrap مع أطر عمل واجهة مستخدم أخرى. قد تتداخل في هذه الحالة مجالات الأسماء. إن حدث ذلك فيمكنك استدعاء التابع ‎<code>.noConflict</code> في المُلحَق الذي تريد استعادة قيمته السابقة.<syntaxhighlight lang="javascript">
var bootstrapButton = $.fn.button.noConflict() // يرجع $.fn.button إلى القيمة المُسنَدة إليه سابقا
$.fn.bootstrapBtn = bootstrapButton            // يسند وظيفة Bootstrap إلى $().bootstrapBtn
</syntaxhighlight>

== أعداد الإصدارات ==
يمكن الوصول إلى إصدار كل مُلحَق من ملحَقات Bootstrap عن طريق الخاصيّة <code>VERSION</code> في مشيّد المُلحَق. للحصول مثلًا على إصدار [[Bootstrap/tooltips|ملحَق التلميحات tooltip]]:<syntaxhighlight lang="javascript">
$.fn.tooltip.Constructor.VERSION // => "4.0.0"
</syntaxhighlight>

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

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

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

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

يتضمّن <code>util.js</code> دوال خدمية ومساعدات أساسية لأحداث <code>transitionEnd</code> علاوة على مُحاكٍ [[:تصنيف:CSS Transitions|لا]]<nowiki/>[[:تصنيف:CSS Transitions|نتقالات CSS]]. تستخدم بقية الملحقات هذا الملف للتحقّق من دعم انتقالات CSS والتقاط الانتقالات العالقة.

== مصادر ==
* [https://getbootstrap.com/docs/4.0/getting-started/javascript/ صفحة JavaScript في توثيق Bootstrap].
[[تصنيف:Bootstrap]]
[[تصنيف:Bootstrap Getting Started]]