انتقل إلى المحتوى الرئيسي انتقل إلى التنقل في المستندات
View on GitHub

JavaScript

إضفاء الحيوية على Bootstrap باستخدام مكونات JavaScript الإضافية الاختيارية الخاصة بنا. تعلم حول كل إضافة، بيانات الخاصة بنا وخيارات واجهة برمجة التطبيقات البرمجية، واكثر.

فردي أو مجمع

يمكن شمل المكونات الإضافية بشكل فردي (باستخدام Bootstrap فردي js/dist/*.js)، أو كلها مرة واحدة باستخدام bootstrap.js أو bootstrap.min.js المصغر (لا تقم بشمل كليهما).

إذا كنت تستخدم حزمة (Webpack ،Rollup…)، يمكنك استخدام ملفات /js/dist/*.js الجاهزة UMD.

استخدام Bootstrap كوحدة نمطية

نحن نقدم نسخة من Bootstrap مبنية على أنها ESM (bootstrap.esm.js وbootstrap.esm.min.js) والتي تتيح لك استخدام Bootstrap كوحدة نمطية في متصفح الخاص بك، إذا كنت تدعم المستعرضات المستهدفة.

<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'

  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

إضافات الغير متوافقة

بسبب قيود المتصفح، بعض إضافات الخاصة بنا، وهي هبوط قطرة، إضافات تلميح اداة وPopover، لا يمكن استخدامها في علامة <script> مع نوع module لأنها تعتمد على Popper. لمزيد من المعلومات حول هذه القضية انظر هنا.

تبعيات

تعتمد بعض إضافات ومكونات CSS على إضافات الأخرى. إذا قمت بشمل إضافات بشكل فردي، تأكد من التحقق من هذه التبعيات في المستندات.

هبوط قطرة الخاص بنا، تعتمد العناصر المنبثقة وتلميحات الأدوات أيضًا على Popper.

ما زلت تريد استخدام jQuery؟ انه ممكن!

تم تصميم Bootstrap 5 ليتم استخدامه بدون jQuery، ولكن لا يزال من الممكن استخدام مكونات الخاصة بنا مع jQuery. إذا اكتشف Bootstrap وجود jQuery في كائن window سيضيف جميع مكونات الخاصة بنا في نظام الإضافة لـ jQuery؛ هذا يعني أنك ستتمكن من تنفيذ $('[data-bs-toggle="tooltip"]').tooltip() لتمكين تلميحات الأدوات. الشيء نفسه ينطبق على مكونات الخاصة بنا الأخرى.

سمات بيانات

يمكن تمكين جميع إضافات Bootstrap وتهيئتها تقريبًا من خلال HTML وحده مع سمات البيانات (طريقتنا المفضلة لاستخدام وظائف JavaScript). تأكد من استخدام مجموعة واحدة فقط من سمات البيانات على عنصر واحد (على سبيل المثال ، لا يمكنك تشغيل تلميح أداة ومشروط من نفس الزر).

محددات

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

الأحداث

يوفر Bootstrap أحداثًا مخصصة لمعظم الإجراءات الفريدة للإضافات. عموما، تأتي هذه في صيغة المصدر وشكل النعت الماضي - حيث يتم تشغيل المصدر (على سبيل المثال show) في بداية الحدث، ويتم تشغيل شكل النعت الماضي (على سبيل المثال shown) عند الانتهاء من إجراء ما.

تزود كافة أحداث المصدر وظيفة preventDefault(). تزودات هذا القدرة على إيقاف تنفيذ إجراء الإعدام قبل أن يبدأ. سيؤدي إرجاع خطأ من معالج الأحداث إلى استدعاء preventDefault() تلقائيًا أيضًا.

var myModal = document.getElementById('myModal')

myModal.addEventListener('show.bs.modal', function (event) {
  if (!data) {
    return event.preventDefault() // stops modal from being shown
  }
})

أحداث jQuery

سيكتشف Bootstrap jQuery إذا كان jQuery موجودًا في كائن window ولا توجد سمة data-bs-no-jquery مُعيَّنة على <body>. إذا تم العثور على jQuery، سوف ينبعث Bootstrap الأحداث بفضل نظام أحداث jQuery’s. لذا إذا كنت تريد الاستماع إلى أحداث Bootstrap’s، سيتعين عليك استخدام طرق jQuery (.on، .one) بدلاً من addEventListener.

$('#myTab a').on('shown.bs.tab', function () {
  // قم بعمل ما...
})

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

تقبل جميع المنشئات كائن خيارات اختيارية أو لا شيء (الذي يبدأ إضافة بسلوكه الافتراضي):

var myModalEl = document.getElementById('myModal')

var modal = new bootstrap.Modal(myModalEl) // تمت تهيئته مع الافتراضيات
var modal = new bootstrap.Modal(myModalEl, { keyboard: false }) // تهيئته بدون لوحة مفاتيح

إذا كنت تحب في الحصول على مثيل إضافة معينة، كل إضافة تكشف طريقة getInstance. من أجل استعادته مباشرة من اجزاء، افعل هذا: bootstrap.Popover.getInstance(myPopoverEl).

محددات CSS في مُنشئين

يمكنك أيضًا استخدام محدد CSS كأول وسيطة بدلاً من اجراء DOM لتهيئة الإضافة. حاليًا تم العثور على اجراء الإضافة بواسطة طريقة querySelector نظرًا لأن الإضافات الخاصة بنا تدعم اجراء واحد فقط.

var modal = new bootstrap.Modal('#myModal')
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')

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

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

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

var myCollapseEl = document.getElementById('#myCollapse')

myCollapseEl.addEventListener('shown.bs.collapse', function (event) {
  // Action to execute once the collapsible area is expanded
})

بالإضافة إلى ذلك سيتم تجاهل استدعاء طريقة على مكون انتقالي.

var myCarouselEl = document.getElementById('myCarousel')
var carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

myCarouselEl.addEventListener('slid.bs.carousel', function (event) {
  carousel.to('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})

carousel.to('1') // Will start sliding to the slide 1 and returns to the caller
carousel.to('2') // !! Will be ignored, as the transition to the slide 1 is not finished !!

الإعدادات الافتراضية

يمكنك تغيير الإعدادات الافتراضية للإضافة بواسطة تعديل الكائن Constructor.Default الخاص بالإضافة:

// changes default for the modal plugin's `keyboard` option to false
bootstrap.Modal.Default.keyboard = false

لا يوجد تعارض (فقط إذا كنت تستخدم jQuery)

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

var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality

أرقام الإصدارات

يمكن الوصول إلى إصدار كل إضافة من إضافات Bootstrap عبر خاصية VERSION لمنشئ الإضافة. لإضافة تلميح الأدوات:

bootstrap.Tooltip.VERSION // => "5.0.1"

لا احتياطات خاصة عند تعطيل JavaScript

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

مكتبات الطرف الثالث

لا يدعم Bootstrap رسميًا مكتبات JavaScript التابعة لجهات خارجية مثل Prototype أو jQuery UI. على الرغم من .noConflict وأحداث تباعد اسم، قد يكون هناك مشاكل توافق تحتاج إلى إصلاحها بنفسك.

المطهر

ادوات تلميح وPopovers تستخدم مدمج الخاص بنا المدمج لتعقيم الخيارات التي تقبل HTML.

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

var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var DefaultAllowlist = {
  // 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: []
}

إذا كنت ترغب في إضافة قيم جديدة إلى هذه allowList الافتراضي يمكنك القيام بما يلي:

var myDefaultAllowList = bootstrap.Tooltip.Default.allowList

// To allow table elements
myDefaultAllowList.table = []

// To allow td elements and data-bs-option attributes on td elements
myDefaultAllowList.td = ['data-bs-option']

// You can push your custom regex to validate your attributes.
// Be careful about your regular expressions being too lax
var myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

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

var yourTooltipEl = document.getElementById('yourTooltip')
var tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content)
  }
})