in English

JavaScript

Bootstrap-ны безнең өстәмә JavaScript плагиннарыбыз белән тормышка ашырыгыз. Eachәр плагин, безнең мәгълүматлар һәм программалы API параметрлары һәм башкалар турында белү.

Бу биттә

Индивидуаль яки тупланган

Плагиннар индивидуаль кертелергә мөмкин (Bootstrap индивидуаль кулланып js/dist/*.js), яисә берьюлы куллану bootstrap.jsяки минимальләштерү bootstrap.min.js(икесен дә кертмәгез).

Әгәр дә сез бәйләүче куллансагыз (Веб-пакет, Посылка, Vite…), сез /js/dist/*.jsUMD әзер файлларны куллана аласыз.

JavaScript рамкалары белән куллану

Bootstrap CSS теләсә нинди рамка белән кулланылса да , Bootstrap JavaScript DOM турында тулы белем алган React, Vue, Angular кебек JavaScript рамкалары белән тулысынча туры килми . Bootstrap да, рамка да бер үк DOM элементын мутацияләргә тырышырга мөмкин, нәтиҗәдә "ачык" позициядә калган тамчылар кебек хаталар барлыкка килергә мөмкин.

Бу төр рамканы кулланучылар өчен яхшырак альтернатива - Bootstrap JavaScript урынына махсус пакет куллану. Менә иң популяр вариантлар:

Реакция: Bootstrap реакциясен
Vue: BootstrapVue (хәзерге вакытта Vue 2 һәм Bootstrap 4 ярдәм итә)
Почмак: ng-bootstrap

Bootstrap модулын куллану

Yourselfзегез сынап карагыз! Bootstrap-ны ES модуле итеп куллану өчен чыганак кодын һәм эш демо-ны йөкләгез . Сез шулай ук мисалны 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 "../".

Моны төзәтер өчен, сез 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 компонентлары бүтән плагиннарга бәйле. Әгәр дә сез плагиннарны аерым кертәсез икән, документларда бу бәйләнешләрне тикшерегез.

Безнең тамчылар, поповерлар, кораллар шулай ук Попперга бәйле .

Мәгълүмат атрибутлары

Барлык 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"атрибутлар булганда, соңгы titleкыйммәт булачак 456һәм аерым мәгълүмат атрибутлары бирелгән кыйммәтләрне юкка чыгарачак data-bs-config. Моннан тыш, булган мәгълүмат атрибутлары JSON кебек кыйммәтләрне урнаштыра ала data-bs-delay='{"show":0,"hide":150}'.

Сайлаучылар

Эшчәнлек сәбәпләре аркасында DOM элементларын сорау өчен без туган querySelectorһәм ысулларны кулланабыз, шуңа күрә сез дөрес селекторларны кулланырга тиеш . Әгәр дә сез махсус селекторларны куллансагыз , алардан качыгыз.querySelectorAllcollapse: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Әгәр дә соралган элемент өстендә инстанция башланмаса, бу ысул кире кайтачак .

Альтернатив рәвештә, getOrCreateInstanceDOM элементы белән бәйләнгән инстанцияне алу өчен, яисә ул башланмаган очракта яңасын булдыру өчен кулланылырга мөмкин.

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

Методлар һәм үзлекләр

Everyәрбер Bootstrap плагины түбәндәге ысулларны һәм статик үзлекләрне фаш итә.

Метод	Тасвирлау
`dispose`	Элемент модалын җимерә. (DOM элементында сакланган мәгълүматны бетерә)
`getInstance`	DOM элементы белән бәйләнгән модаль инстанцияне алырга мөмкинлек бирүче статик ысул.
`getOrCreateInstance`	Статик ысул, ул DOM элементы белән бәйләнгән модаль инстанцияне алырга, яисә ул башланмаган очракта яңасын булдырырга мөмкинлек бирә.

Статик милек	Тасвирлау
`NAME`	Плагин исемен кайтара. (Мисал `bootstrap.Tooltip.NAME`:)
`VERSION`	Bootstrap плагиннарының һәрберсенең версиясенә `VERSION`плагин конструкторы милеге аша кереп була (Мисал `bootstrap.Tooltip.VERSION`:)

Санитизатор

Кораллар һәм поповерлар 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 белән куллану мөмкин. Әгәр 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 плагиннарын башка UI рамкалары белән кулланырга кирәк. Бу шартларда вакыт-вакыт исем киңлеге бәрелешләре булырга мөмкин. .noConflictБу очрак булса, сез кыйммәтен кире кайтарырга теләгән плагинга шалтырата аласыз.

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

Bootstrap рәсми рәвештә Прототип яки jQuery UI кебек өченче як JavaScript китапханәләрен хупламый. Вакыйгаларга һәм исемнәргә карамастан .noConflict, яраклашу проблемалары булырга мөмкин, аларны үзегез төзәтергә кирәк.

jQuery вакыйгалары

Bootstrap jQuery-ны табачак, әгәр объектта булса һәм jQueryатрибут куелмаган булса . JQuery табылса, Bootstrap jQuery вакыйгалар системасы ярдәмендә вакыйгалар чыгарачак. Шулай итеп, Bootstrap вакыйгаларын тыңларга теләсәгез, сезгә jQuery ысулларын ( , ) кулланырга туры киләчәк .windowdata-bs-no-jquery<body>.on.oneaddEventListener

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

JavaScript инвалид

JavaScript сүндерелгәндә Bootstrap плагиннарының махсус кире кайтуы юк. Әгәр дә сез бу очракта кулланучының тәҗрибәсе турында кайгыртасыз икән, кулланучыларга <noscript>ситуацияне (һәм JavaScriptны ничек яңадан эшләтеп җибәрергә) аңлату өчен кулланыгыз, һәм / яки үзегезнең кимчелекләрегезне өстәгез.