in English

جافا سكريبت

قم بإضفاء الحيوية على Bootstrap باستخدام مكونات JavaScript الإضافية الاختيارية. تعرف على كل مكون إضافي وبياناتنا وخيارات API البرمجية والمزيد.

على هذه الصفحة

فردي أو مجمعة

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

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

الاستخدام مع أطر عمل JavaScript

بينما يمكن استخدام Bootstrap CSS مع أي إطار عمل ، فإن Bootstrap JavaScript غير متوافق تمامًا مع أطر عمل JavaScript مثل React و Vue و Angular التي تفترض معرفة كاملة بـ DOM. قد يحاول كل من Bootstrap وإطار العمل تغيير عنصر DOM نفسه ، مما يؤدي إلى حدوث أخطاء مثل القوائم المنسدلة عالقة في الوضع "المفتوح".

البديل الأفضل لأولئك الذين يستخدمون هذا النوع من الأطر هو استخدام حزمة خاصة بإطار العمل بدلاً من Bootstrap JavaScript. فيما يلي بعض الخيارات الأكثر شيوعًا:

رد فعل: رد فعل Bootstrap
Vue: BootstrapVue (حاليًا يدعم Vue 2 و Bootstrap 4 فقط)
الزاوي: ng-bootstrap

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

جربها بنفسك! قم بتنزيل الكود المصدري والعرض التوضيحي العملي لاستخدام Bootstrap كوحدة ES من مستودع twbs / أمثلة . يمكنك أيضًا فتح المثال في StackBlitz .

نحن نقدم إصدارًا من 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>

مقارنةً بحزم JS ، يتطلب استخدام ESM في المستعرض استخدام المسار الكامل واسم الملف بدلاً من اسم الوحدة النمطية. اقرأ المزيد عن وحدات JS في المتصفح. لهذا السبب نستخدمها 'bootstrap.esm.min.js'بدلاً من 'bootstrap'أعلاه. ومع ذلك ، يزداد الأمر تعقيدًا بسبب اعتمادنا على Popper ، والذي يستورد Popper إلى JavaScript كما يلي:

import * as Popper from "@popperjs/core"

إذا جربت هذا كما هو ، فسترى خطأ في وحدة التحكم كما يلي:

Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../".

لإصلاح هذا الأمر ، يمكنك استخدام الأمر an importmapلحل أسماء الوحدات النمطية العشوائية لإكمال المسارات. إذا كانت المستعرضات المستهدفة لا تدعم importmap، فستحتاج إلى استخدام مشروع es-module-shims . إليك كيفية عملها مع Bootstrap و Popper:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-iYQeCzEYFbKjA/T2uDLTpkwGzCiq6soy8tYaI1GyVh/UjpbCx/TYkiZhlZB6+fzT" crossorigin="anonymous">
    <title>Hello, modularity!</title>
  </head>
  <body>
    <h1>Hello, modularity!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="ESM in Browser" data-bs-content="Bang!">Custom popover</button>

    <script async src="https://cdn.jsdelivr.net/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script>
    <script type="importmap">
    {
      "imports": {
        "@popperjs/core": "https://cdn.jsdelivr.net/npm/@popperjs/[email protected]/dist/umd/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.esm.min.js"
      }
    }
    </script>
    <script type="module">
      import * as bootstrap from 'bootstrap'

      new bootstrap.Popover(document.getElementById('popoverButton'))
    </script>
  </body>
</html>

التبعيات

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

تعتمد القوائم المنسدلة والقوائم المنبثقة وتلميحات الأدوات أيضًا على Popper .

سمات البيانات

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

نظرًا لأنه يمكن تمرير الخيارات عبر سمات البيانات أو JavaScript ، يمكنك إلحاق اسم خيار بـ data-bs-، كما في data-bs-animation="{value}". تأكد من تغيير نوع حالة اسم الخيار من " camelCase " إلى " kebab-case " عند تمرير الخيارات عبر سمات البيانات. على سبيل المثال ، استخدم data-bs-custom-class="beautifier"بدلاً من data-bs-customClass="beautifier".

اعتبارًا من Bootstrap 5.2.0 ، تدعم جميع المكونات سمة بيانات تجريبية محجوزة data-bs-configيمكن أن تحتوي على تكوين مكون بسيط كسلسلة JSON. عندما يكون للعنصر سمات data-bs-config='{"delay":0, "title":123}'وخصائص ، ستكون القيمة data-bs-title="456"النهائية وستتجاوز سمات البيانات المنفصلة القيم المعطاة . بالإضافة إلى ذلك ، يمكن لسمات البيانات الحالية استيعاب قيم JSON مثل .title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

المحددات

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

الأحداث

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

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

const myModal = document.querySelector('#myModal')

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

API برمجي

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

const myModalEl = document.querySelector('#myModal')

const modal = new bootstrap.Modal(myModalEl) // initialized with defaults

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // initialized with no keyboard

إذا كنت ترغب في الحصول على مثيل مكون إضافي معين ، فإن كل مكون إضافي يعرض getInstanceطريقة. على سبيل المثال ، لاسترداد مثيل مباشرة من عنصر:

bootstrap.Popover.getInstance(myPopoverEl)

سيعود nullهذا التابع إذا لم يتم بدء مثيل على العنصر المطلوب.

بدلاً من ذلك ، getOrCreateInstanceيمكن استخدامه لربط المثيل بعنصر DOM ، أو إنشاء مثيل جديد في حالة عدم تهيئته.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

في حالة عدم تهيئة مثيل ، فقد يقبل ويستخدم كائن تكوين اختياري كوسيطة ثانية.

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

بالإضافة إلى التوابع getInstanceو getOrCreateInstance، يمكن لجميع منشئي المكونات الإضافية قبول عنصر DOM أو محدد CSS صالح كأول وسيط. تم العثور على عناصر البرنامج المساعد مع querySelectorالطريقة لأن الإضافات لدينا تدعم عنصرًا واحدًا فقط.

const modal = new bootstrap.Modal('#myModal')
const dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
const offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas')
const alert = bootstrap.Alert.getOrCreateInstance('#myAlert')

وظائف وانتقالات غير متزامنة

جميع طرق API البرمجية غير متزامنة وتعود إلى المتصل بمجرد بدء النقل ، ولكن قبل أن ينتهي . من أجل تنفيذ إجراء بمجرد اكتمال الانتقال ، يمكنك الاستماع إلى الحدث المقابل.

const myCollapseEl = document.querySelector('#myCollapse')

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

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

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

myCarouselEl.addEventListener('slid.bs.carousel', 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 !!

`dispose`طريقة

في حين أنه قد يبدو من الصحيح استخدام disposeالطريقة بعد ذلك مباشرة hide()، إلا أنها ستؤدي إلى نتائج غير صحيحة. فيما يلي مثال على استخدام المشكلة:

const myModal = document.querySelector('#myModal')
myModal.hide() // it is asynchronous

myModal.addEventListener('shown.bs.hidden', event => {
  myModal.dispose()
})

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

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

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

الأساليب والخصائص

يعرض كل مكون إضافي من Bootstrap الأساليب والخصائص الثابتة التالية.

طريقة	وصف
`dispose`	يدمر شكل عنصر. (يزيل البيانات المخزنة على عنصر DOM)
`getInstance`	الأسلوب الثابت الذي يسمح لك بالحصول على المثيل الشرطي المرتبط بعنصر DOM.
`getOrCreateInstance`	طريقة ثابتة تسمح لك بالحصول على مثيل مشروط مرتبط بعنصر DOM ، أو إنشاء مثيل جديد في حالة عدم تهيئته.

خاصية ثابتة	وصف
`NAME`	يُرجع اسم البرنامج المساعد. (مثال `bootstrap.Tooltip.NAME`:)
`VERSION`	يمكن الوصول إلى إصدار كل من مكونات Bootstrap الإضافية عبر `VERSION`خاصية مُنشئ المكون الإضافي (مثال `bootstrap.Tooltip.VERSION`:)

مطهر

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

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

const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
const 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، يمكنك القيام بما يلي:

const 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
const myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

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

const yourTooltipEl = document.querySelector('#yourTooltip')
const tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn(content) {
    return DOMPurify.sanitize(content)
  }
})

اختياريا باستخدام jQuery

لا تحتاج إلى jQuery في Bootstrap 5 ، ولكن لا يزال من الممكن استخدام مكوناتنا مع jQuery. إذا اكتشف Bootstrap jQueryفي windowالكائن ، فسيضيف جميع مكوناتنا في نظام المكون الإضافي لـ jQuery. يتيح لك ذلك القيام بما يلي:

$('[data-bs-toggle="tooltip"]').tooltip() // to enable tooltips, with default configuration

$('[data-bs-toggle="tooltip"]').tooltip({ boundary: 'clippingParents', customClass: 'myClass' }) // to initialize tooltips with given configuration

$('#myTooltip').tooltip('show') // to trigger `show` method

الشيء نفسه ينطبق على مكوناتنا الأخرى.

لا تعارض

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

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

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

أحداث jQuery

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

$('#myTab a').on('shown.bs.tab', () => {
  // do something...
})