in English

JavaScript

Ажывіце Bootstrap з дапамогай нашых дадатковых плагінаў JavaScript. Даведайцеся аб кожным плагіне, нашых параметрах даных і праграмнага API і многае іншае.

На гэтай старонцы

Індывідуальныя або складзеныя

Убудовы могуць быць уключаны паасобку (з выкарыстаннем Bootstrap's individual 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. Вось некалькі найбольш папулярных варыянтаў:

React: React Bootstrap
Vue: BootstrapVue (у цяперашні час падтрымлівае толькі Vue 2 і Bootstrap 4)
Angular: ng-bootstrap

Выкарыстанне 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 у наш 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 залежаць ад іншых убудоў. Калі вы ўключаеце плагіны паасобку, пераканайцеся, што праверылі гэтыя залежнасці ў дакументах.

Нашы выпадаючыя спісы, усплывальныя вобразы і падказкі таксама залежаць ад 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", канчатковае titleзначэнне будзе , 456а асобныя атрыбуты даных будуць перавызначаць значэнні, зададзеныя ў data-bs-config. Акрамя таго, існуючыя атрыбуты даных могуць змяшчаць такія значэнні JSON, як data-bs-delay='{"show":0,"hide":150}'.

Селектары

Мы выкарыстоўваем уласныя метады querySelectorі querySelectorAllдля запыту элементаў DOM з меркаванняў прадукцыйнасці, таму вы павінны выкарыстоўваць сапраўдныя селектары . Калі вы выкарыстоўваеце спецыяльныя селектары, такія як collapse:Example, не забудзьцеся экранаваць іх.

Падзеі

Bootstrap забяспечвае карыстальніцкія падзеі для большасці унікальных дзеянняў плагінаў. Як правіла, яны бываюць у форме інфінітыва і дзеепрыметніка прошлага часу - дзе інфінітыў (напр. 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

Метады і ўласцівасці

Кожны плагін 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

Вам не патрэбны 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...
})

Адключаны JavaScript

Плагіны Bootstrap не маюць спецыяльнага запасу, калі JavaScript адключаны. Калі вы клапоціцеся аб узаемадзеянні з карыстальнікам у гэтым выпадку, выкарыстоўвайце <noscript>для тлумачэння сітуацыі (і таго, як паўторна ўключыць JavaScript) вашым карыстальнікам, і/або дадайце свае ўласныя запасныя варыянты.