رفتن به محتوای اصلی به پیمایش اسناد بروید
in English

جاوا اسکریپت

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

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

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

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

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

ما نسخه ای از 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>

پلاگین های ناسازگار

به دلیل محدودیت‌های مرورگر، برخی از افزونه‌های ما، یعنی افزونه‌های Dropdown، Tooltip و Popover، نمی‌توانند در یک <script>برچسب با moduleنوع استفاده شوند زیرا به Popper وابسته هستند. برای اطلاعات بیشتر در مورد موضوع اینجا را ببینید .

وابستگی ها

برخی از پلاگین ها و اجزای CSS به پلاگین های دیگر بستگی دارند. اگر افزونه‌ها را به صورت جداگانه اضافه می‌کنید، حتماً این وابستگی‌ها را در اسناد بررسی کنید.

بازشوها، پاپاورها و راهنمای ابزار ما نیز به Popper بستگی دارد .

هنوز می خواهید از jQuery استفاده کنید؟ ممکن است!

بوت استرپ 5 برای استفاده بدون جی کوئری طراحی شده است، اما هنوز هم می توان از اجزای ما با جی کوئری استفاده کرد. اگر بوت استرپ jQueryدر windowشی شناسایی کند، تمام اجزای ما را به سیستم پلاگین جی کوئری اضافه می کند. این بدان معنی است که شما قادر خواهید بود $('[data-bs-toggle="tooltip"]').tooltip()برای فعال کردن راهنمای ابزار انجام دهید. در مورد سایر اجزای ما نیز همینطور است.

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

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

انتخابگرها

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

مناسبت ها

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

همه رویدادهای نامتناهی preventDefault()عملکردی را ارائه می دهند. این امکان را فراهم می کند تا اجرای یک عمل قبل از شروع آن متوقف شود. بازگشت false از یک کنترل کننده رویداد نیز به طور خودکار تماس preventDefault()می گیرد.

var myModal = document.getElementById('myModal')

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

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

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

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

API برنامه‌ای

همه سازنده ها یک شی گزینه اختیاری یا هیچ چیز را می پذیرند (که یک پلاگین را با رفتار پیش فرض خود شروع می کند):

var myModalEl = document.getElementById('myModal')

var modal = new bootstrap.Modal(myModalEl) // initialized with defaults
var modal = new bootstrap.Modal(myModalEl, { keyboard: false }) // initialized with no keyboard

اگر می‌خواهید نمونه پلاگین خاصی را دریافت کنید، هر افزونه getInstanceروشی را نشان می‌دهد. برای بازیابی مستقیم آن از یک عنصر، این کار را انجام دهید bootstrap.Popover.getInstance(myPopoverEl):

انتخابگرهای CSS در سازنده ها

همچنین می توانید از یک انتخابگر CSS به عنوان اولین آرگومان به جای عنصر DOM برای مقداردهی اولیه افزونه استفاده کنید. در حال حاضر عنصر پلاگین با این querySelectorروش پیدا می شود زیرا افزونه های ما فقط از یک عنصر پشتیبانی می کنند.

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

توابع ناهمزمان و انتقال

همه متدهای API برنامه‌ریزی ناهمزمان هستند و پس از شروع انتقال، اما قبل از پایان آن ، به تماس‌گیرنده بازمی‌گردند .

به منظور اجرای یک عمل پس از اتمام انتقال، می توانید به رویداد مربوطه گوش دهید.

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)

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

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

شماره های نسخه

نسخه هر یک از افزونه های بوت استرپ از طریق VERSIONویژگی سازنده افزونه قابل دسترسی است. به عنوان مثال، برای افزونه tooltip:

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

وقتی جاوا اسکریپت غیرفعال است، هیچ بازگشتی خاصی وجود ندارد

وقتی جاوا اسکریپت غیرفعال است، پلاگین‌های بوت استرپ به‌خوبی کار نمی‌کنند. اگر در این مورد به تجربه کاربری اهمیت می دهید، <noscript>برای توضیح وضعیت (و نحوه فعال کردن مجدد جاوا اسکریپت) به کاربران خود و/یا اضافه کردن بک گراندهای سفارشی خود استفاده کنید.

کتابخانه های شخص ثالث

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

ضد عفونی کننده

Tooltips و 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)
  }
})