in English

جاوا اسکریپت

بوت استرپ را با افزونه های اختیاری جاوا اسکریپت زنده کنید. درباره هر افزونه، گزینه‌های API داده‌ها و برنامه‌ای ما و موارد دیگر بیاموزید.

در این صفحه

فردی یا تالیفی

پلاگین‌ها را می‌توان به‌صورت جداگانه (با استفاده از Bootstrap's individual js/dist/*.js) یا به‌طور هم‌زمان با استفاده bootstrap.jsیا کوچک‌سازی bootstrap.min.js(هر دو را شامل نشود) گنجاند.

اگر از باندلر (Webpack، Parcel، Vite...) استفاده می‌کنید، می‌توانید از /js/dist/*.jsفایل‌هایی استفاده کنید که UMD آماده هستند.

استفاده با فریمورک های جاوا اسکریپت

در حالی که Bootstrap CSS را می توان با هر فریم ورکی استفاده کرد، جاوا اسکریپت بوت استرپ به طور کامل با چارچوب های جاوا اسکریپت مانند React، Vue و Angular که دانش کامل DOM را فرض می کنند سازگار نیست. هم Bootstrap و هم فریم ورک ممکن است سعی کنند همان عنصر DOM را جهش دهند و در نتیجه باگ هایی مانند کرکره ها در موقعیت "باز" گیر کرده باشند.

یک جایگزین بهتر برای کسانی که از این نوع فریم ورک ها استفاده می کنند، استفاده از بسته های فریمورک خاص به جای جاوا اسکریپت بوت استرپ است. در اینجا برخی از محبوب ترین گزینه ها آورده شده است:

React: React Bootstrap
Vue: BootstrapVue (در حال حاضر فقط Vue 2 و Bootstrap 4 را پشتیبانی می کند)
Angular: ng-bootstrap

استفاده از بوت استرپ به عنوان ماژول

خودت آن را امتحان کن! کد منبع و نسخه آزمایشی را برای استفاده از Bootstrap به عنوان یک ماژول ES از مخزن twbs/examples دانلود کنید . همچنین می توانید مثال را در 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 را به شکل زیر به جاوا اسکریپت وارد می کند:

import * as Popper from "@popperjs/core"

اگر این کار را همانطور که هست امتحان کنید، با خطای زیر در کنسول روبرو خواهید شد:

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

برای رفع این مشکل، می توانید از یک 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 بستگی دارد .

ویژگی های داده

تقریباً تمام پلاگین های بوت استرپ را می توان تنها از طریق HTML با ویژگی های داده (روش ترجیحی ما برای استفاده از عملکرد جاوا اسکریپت) فعال و پیکربندی کرد. مطمئن شوید که فقط از یک مجموعه از ویژگی‌های داده در یک عنصر استفاده می‌کنید (به عنوان مثال، نمی‌توانید یک tooltip و modal را از همان دکمه فعال کنید.)

از آنجایی که گزینه‌ها می‌توانند از طریق ویژگی‌های داده یا جاوا اسکریپت ارسال شوند، می‌توانید نام گزینه را 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"ویژگی باشد، مقدار نهایی titleخواهد بود 456و ویژگی های داده جداگانه مقادیر داده شده در را لغو می کنند data-bs-config. علاوه بر این، ویژگی های داده موجود می توانند مقادیر JSON مانند data-bs-delay='{"show":0,"hide":150}'.

انتخابگرها

ما از روش‌های اصلی querySelectorو querySelectorAllبرای پرس و جو از عناصر DOM به دلایل عملکرد استفاده می‌کنیم، بنابراین باید از انتخابگرهای معتبر استفاده کنید . اگر از انتخابگرهای خاصی مانند استفاده می کنید collapse:Example، حتما از آنها فرار کنید.

مناسبت ها

بوت استرپ رویدادهای سفارشی را برای اقدامات منحصر به فرد بیشتر افزونه ها فراهم می کند. به طور کلی، این ها به صورت مصدر و ماضی می آیند - که در آن مصدر (مثل show) در شروع یک رویداد تحریک می شود، و شکل ماضی آن (مصدر) shownپس از اتمام یک عمل فعال می شود.

همه رویدادهای نامتناهی preventDefault()عملکردی را ارائه می دهند. این امکان را فراهم می کند تا اجرای یک عمل قبل از شروع آن متوقف شود. بازگشت false از یک کنترل کننده رویداد نیز به طور خودکار تماس 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

روش ها و خواص

هر پلاگین بوت استرپ روش ها و ویژگی های ثابت زیر را نشان می دهد.

روش	شرح
`dispose`	مودال یک عنصر را از بین می برد. (داده های ذخیره شده در عنصر DOM را حذف می کند)
`getInstance`	روش ایستا که به شما امکان می دهد نمونه مدال مرتبط با یک عنصر DOM را دریافت کنید.
`getOrCreateInstance`	روش ایستا که به شما امکان می دهد نمونه مدال مرتبط با یک عنصر DOM را دریافت کنید، یا در صورتی که اولیه نشده بود، یک نمونه جدید ایجاد کنید.

خاصیت استاتیک	شرح
`NAME`	نام افزونه را برمی گرداند. (مثال `bootstrap.Tooltip.NAME`:)
`VERSION`	نسخه هر یک از افزونه های بوت استرپ از طریق `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

شما در Bootstrap 5 به jQuery نیاز ندارید ، اما همچنان می‌توانید از اجزای ما با jQuery استفاده کنید. اگر بوت استرپ jQueryدر windowشی شناسایی کند، تمام اجزای ما را به سیستم پلاگین جی کوئری اضافه می کند. این به شما امکان می دهد کارهای زیر را انجام دهید:

$('[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

در مورد سایر اجزای ما نیز همینطور است.

بدون درگیری

گاهی اوقات لازم است از پلاگین های بوت استرپ با سایر فریم ورک های UI استفاده شود. در این شرایط، گاهی اوقات ممکن است برخورد فضای نام رخ دهد. اگر این اتفاق افتاد، می‌توانید با .noConflictافزونه‌ای که می‌خواهید ارزش آن را برگردانید تماس بگیرید.

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

بوت استرپ به طور رسمی از کتابخانه های جاوا اسکریپت شخص ثالث مانند Prototype یا jQuery UI پشتیبانی نمی کند. با وجود .noConflictرویدادها و فضای نام، ممکن است مشکلات سازگاری وجود داشته باشد که باید به تنهایی آنها را برطرف کنید.

رویدادهای جی کوئری

jQueryبوت استرپ اگر در windowشی وجود داشته باشد و هیچ data-bs-no-jqueryویژگی تنظیم نشده باشد، جی کوئری را شناسایی می <body>کند. اگر جی کوئری پیدا شود، بوت استرپ به لطف سیستم رویداد جی کوئری رویدادها را منتشر می کند. بنابراین اگر می خواهید به رویدادهای بوت استرپ گوش دهید، باید به جای jQuery از متدهای جی کوئری ( .on, .one) استفاده کنید addEventListener.

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