in English

JavaScript

Қосымша JavaScript плагиндерімен Bootstrap-ті жандандырыңыз. Әрбір плагин, деректер және бағдарламалық API опциялары және т.б. туралы біліңіз.

Бұл бетте

Жеке немесе құрастырылған

Плагиндерді жеке қосуға болады (Bootstrap's individual js/dist/*.js) немесе барлығын бірден bootstrap.jsнемесе кішірейтілген bootstrap.min.js(екеуін де қамтымайды).

Топтаманы (Webpack, Parcel, Vite…) пайдалансаңыз /js/dist/*.js, UMD дайын файлдарды пайдалануға болады.

JavaScript фреймворктерімен пайдалану

Bootstrap CSS кез келген фреймворкпен пайдаланылуы мүмкін болғанымен, Bootstrap JavaScript DOM туралы толық білімі бар React, Vue және Angular сияқты JavaScript құрылымдарымен толық үйлесімді емес . Bootstrap және жақтау бірдей DOM элементін мутациялауға әрекет етуі мүмкін, нәтижесінде «ашық» күйде тұрып қалған ашылмалы тізімдер сияқты қателер пайда болады.

Фреймворктердің осы түрін пайдаланатындар үшін жақсы балама Bootstrap JavaScript орнына арнайы құрылымдық пакетті пайдалану болып табылады. Міне, ең танымал нұсқалардың кейбірі:

Реакция: React Bootstrap
Vue: BootstrapVue (қазіргі уақытта тек Vue 2 және Bootstrap 4 қолдайды)
Бұрыштық: ng-bootstrap

Bootstrap модулін модуль ретінде пайдалану

Өзіңіз көріңіз! Twbs/examples репозиторийінен ES модулі ретінде Bootstrap пайдалану үшін бастапқы кодты және жұмыс демонстрациясын жүктеп алыңыз . Сондай-ақ мысалды 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'Дегенмен, бұл біздің Попперге тәуелділігімізбен қиындатады, ол Попперді 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 функциясын пайдаланудың таңдаулы тәсілі). Бір элементте деректер атрибуттарының бір жинағын ғана пайдалануды ұмытпаңыз (мысалы, бір түймеден құралдар кеңесі мен модальды іске қоса алмайсыз.)

data-bs-Опцияларды деректер атрибуттары немесе JavaScript арқылы жіберуге болатындықтан , параметр атауын сияқты қосуға болады data-bs-animation="{value}". Опцияларды деректер атрибуттары арқылы беру кезінде опция атауының регистр түрін “ camelCase ” дан “ kebab-case ” күйіне өзгертуді ұмытпаңыз. Мысалы, data-bs-custom-class="beautifier"орнына пайдаланыңыз data-bs-customClass="beautifier".

Bootstrap 5.2.0 нұсқасы бойынша барлық компоненттер қарапайым құрамдас конфигурациясын JSON жолы ретінде орналастыра алатын эксперименттік сақталған деректер төлсипатын қолдайды. data-bs-configЭлементте 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()функционалдылықты қамтамасыз етеді. Бұл әрекет басталмай тұрып оның орындалуын тоқтату мүмкіндігін береді. Оқиға өңдегішінен 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және әдістеріне қосымша , барлық плагин конструкторлары бірінші аргумент ретінде getOrCreateInstanceDOM элементін немесе жарамды 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`)

Санитизатор

Кеңестер мен 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 арқылы пайдалану әлі де мүмкін. Егер 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

Бұл біздің басқа компоненттерге де қатысты.

Қақтығыс жоқ

Кейде басқа UI құрылымдарымен Bootstrap плагиндерін пайдалану қажет. Мұндай жағдайларда аттар кеңістігінің соқтығысуы кейде орын алуы мүмкін. Бұл орын алса, .noConflictмәнін қайтарғыңыз келетін плагинге қоңырау шалуыңызға болады.

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

Bootstrap Prototype немесе jQuery UI сияқты үшінші тарап JavaScript кітапханаларына ресми түрде қолдау көрсетпейді. Оқиғаларға және аттар кеңістігіне қарамастан .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

JavaScript өшірілген кезде Bootstrap плагиндерінде арнайы резерв болмайды. Бұл жағдайда пайдаланушы тәжірибесіне мән берсеңіз, пайдаланушыларыңызға <noscript>жағдайды (және JavaScript-ті қайта қосу жолын) түсіндіру үшін пайдаланыңыз және/немесе өзіңіздің теңшелетін резервтеріңізді қосыңыз.