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 وحده عن طريق خاصيّات البيانات (data attributes، وهي طريقة مطوّري Bootstrap التي يفضّلونها على استخدام JavaScript). تأكّد من استخدام مجموعة واحدة فقط من خاصيّات البيانات على عنصُر معيَّن (مثلاً؛ لا يمكن إظهار تلميح وفتح مربعات الحوار [Modal] بنفس الزّر).

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

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

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

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

تنبيه: المُحددات

نستخدم للبحث في شجرة DOM حاليًا التوابع الأصلية querySelector و querySelectorAll لأنّ أداءها أحسن. لذا عليك استخدام محدّدات صالحة. إن أردت استخدام محددات خاصة، مثل collapse:Example، احرص على تهريبها.

الأحداث

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

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

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

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

يرى فريق Bootstrap أنه يجب أن يكون المبرمج قادرًا على استخدام جميع ملحقات Bootstrap ببساطة عن طريق واجهة برمجية API باستخدام 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 دوال خدمية ومساعدات أساسية لأحداث transitionPopovers End علاوة على مُحاكٍ لانتقالات CSS. تستخدم بقية الملحقات هذا الملف للتحقّق من دعم انتقالات CSS والتقاط الانتقالات العالقة.

المصححات Sanitizers

تستخدم تعتمد والعناصر المنبثقة (Popovers)، والتلميحات (Tooltips) مصححات مٌضمّنة للتحقق من صحة الخيارات التي تقبل قيم مكتوبة بترميز HTML.

هذه هي قيمة whiteList الافتراضية:

var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var DefaultWhitelist = {
  // Global attributes allowed on any supplied element below.
  '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  div: [],
  em: [],
  hr: [],
  h1: [],
  h2: [],
  h3: [],
  h4: [],
  h5: [],
  h6: [],
  i: [],
  img: ['src', 'srcset', 'alt', 'title', 'width', 'height'],
  li: [],
  ol: [],
  p: [],
  pre: [],
  s: [],
  small: [],
  span: [],
  sub: [],
  sup: [],
  strong: [],
  u: [],
  ul: []
}

يمكنك إضافة قيم جديدة للائحة البيضاء الافتراضية عبر ما يلي:

var myDefaultWhiteList = $.fn.tooltip.Constructor.Default.whiteList

// لإتاحة عناصر الجدول
myDefaultWhiteList.table = []

// data-option وسمات td للسماح بعناصر 
myDefaultWhiteList.td = ['data-option']

// يمكنك إضافة تعبير نمطي مخصص لتصحيح السمات
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultWhiteList['*'].push(myCustomRegex)

يمكنك تجاوز المصحح عبر كتابة مايلي:

$('#yourTooltip').tooltip({
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content)
  }
})

مصادر

• صفحة JavaScript في توثيق Bootstrap.