JavaScript

Dewch â Bootstrap yn fyw gyda'n ategion JavaScript dewisol. Dysgwch am bob ategyn, ein data a'n hopsiynau API rhaglennol, a mwy.

Ar y dudalen hon

Unigol neu wedi'i lunio

Gellir cynnwys ategion yn unigol (gan ddefnyddio unigolyn Bootstrap js/dist/*.js), neu i gyd ar unwaith gan ddefnyddio bootstrap.jsneu'r miniified bootstrap.min.js(peidiwch â chynnwys y ddau).

Os ydych chi'n defnyddio bwndelwr (Webpack, Parcel, Vite…), gallwch ddefnyddio /js/dist/*.jsffeiliau sy'n barod ar gyfer UMD.

Defnydd gyda fframweithiau JavaScript

Er y gellir defnyddio'r Bootstrap CSS gydag unrhyw fframwaith, nid yw'r Bootstrap JavaScript yn gwbl gydnaws â fframweithiau JavaScript fel React, Vue, ac Angular sy'n rhagdybio gwybodaeth lawn o'r DOM. Efallai y bydd Bootstrap a'r fframwaith yn ceisio treiglo'r un elfen DOM, gan arwain at fygiau fel cwymplenni sy'n sownd yn y sefyllfa “agored”.

Dewis arall gwell i'r rhai sy'n defnyddio'r math hwn o fframweithiau yw defnyddio pecyn fframwaith-benodol yn lle'r Bootstrap JavaScript. Dyma rai o'r opsiynau mwyaf poblogaidd:

Ymateb: React Bootstrap
Vue: BootstrapVue (dim ond yn cefnogi Vue 2 a Bootstrap 4 ar hyn o bryd)
onglog: ng-bootstrap

Defnyddio Bootstrap fel modiwl

Rhowch gynnig arni eich hun! Lawrlwythwch y cod ffynhonnell a'r demo gweithredol ar gyfer defnyddio Bootstrap fel modiwl ES o'r ystorfa twbs/enghreifftiau . Gallwch hefyd agor yr enghraifft yn StackBlitz .

Rydym yn darparu fersiwn o Bootstrap a adeiladwyd fel ESM( bootstrap.esm.jsa bootstrap.esm.min.js) sy'n eich galluogi i ddefnyddio Bootstrap fel modiwl yn y porwr, os yw'ch porwyr targed yn ei gefnogi .

<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'

  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

O'i gymharu â bwndeli JS, mae defnyddio ESM yn y porwr yn gofyn ichi ddefnyddio'r llwybr llawn ac enw'r ffeil yn lle enw'r modiwl. Darllenwch fwy am fodiwlau JS yn y porwr. Dyna pam rydyn ni'n defnyddio 'bootstrap.esm.min.js'yn lle'r 'bootstrap'uchod. Fodd bynnag, mae hyn yn cael ei gymhlethu ymhellach gan ein dibyniaeth ar Popper, sy'n mewnforio Popper i'n JavaScript fel hyn:

import * as Popper from "@popperjs/core"

Os ceisiwch hyn fel y mae, fe welwch wall yn y consol fel y canlynol:

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

I drwsio hyn, gallwch ddefnyddio importmapi ddatrys enwau modiwlau mympwyol i gwblhau llwybrau. Os nad yw eich porwyr targed yn cefnogi importmap, bydd angen i chi ddefnyddio'r prosiect es-module-shims . Dyma sut mae'n gweithio i Bootstrap a 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>

Dibyniaethau

Mae rhai ategion a chydrannau CSS yn dibynnu ar ategion eraill. Os ydych chi'n cynnwys ategion yn unigol, gwnewch yn siŵr eich bod chi'n gwirio am y dibyniaethau hyn yn y dogfennau.

Mae ein cwymplenni, popovers, a chynghorion offer hefyd yn dibynnu ar Popper .

Priodoleddau data

Gellir galluogi a ffurfweddu bron pob ategyn Bootstrap trwy HTML yn unig gyda phriodoleddau data (ein hoff ffordd o ddefnyddio ymarferoldeb JavaScript). Gwnewch yn siŵr eich bod chi'n defnyddio un set o briodoleddau data ar un elfen yn unig (ee, ni allwch sbarduno cyngor a moddol o'r un botwm.)

Gan y gellir trosglwyddo opsiynau trwy briodoleddau data neu JavaScript, gallwch atodi enw opsiwn i data-bs-, fel yn data-bs-animation="{value}". Gwnewch yn siŵr eich bod yn newid math achos yr enw opsiwn o “ camelCase ” i “ kebab-case ” wrth basio'r opsiynau trwy briodoleddau data. Er enghraifft, defnyddiwch data-bs-custom-class="beautifier"yn lle data-bs-customClass="beautifier".

O Bootstrap 5.2.0, mae'r holl gydrannau'n cefnogi priodoledd data neilltuedig arbrofoldata-bs-config a all gynnwys cyfluniad cydran syml fel llinyn JSON. Pan fydd gan elfen data-bs-config='{"delay":0, "title":123}'a data-bs-title="456"phriodoleddau, y gwerth terfynol titlefydd 456a bydd y priodoleddau data ar wahân yn diystyru'r gwerthoedd a roddir ar data-bs-config. Yn ogystal, mae priodoleddau data presennol yn gallu cynnwys gwerthoedd JSON fel data-bs-delay='{"show":0,"hide":150}'.

Detholwyr

Rydym yn defnyddio'r brodorol querySelectora'r querySelectorAlldulliau i ymholi am elfennau DOM am resymau perfformiad, felly mae'n rhaid i chi ddefnyddio dewiswyr dilys . Os ydych chi'n defnyddio dewiswyr arbennig fel collapse:Example, gwnewch yn siŵr eich bod chi'n dianc rhagddynt.

Digwyddiadau

Mae Bootstrap yn darparu digwyddiadau wedi'u teilwra ar gyfer gweithredoedd unigryw'r mwyafrif o ategion. Yn gyffredinol, daw’r rhain ar ffurf berfenw a chyfranogiad y gorffennol – lle mae’r berfenw (ex. show) yn cael ei sbarduno ar ddechrau digwyddiad, a’i ffurf cyfranogwr yn y gorffennol (ex. shown) yn cael ei sbarduno wrth gwblhau gweithred.

Mae pob digwyddiad berfenw yn darparu preventDefault()ymarferoldeb. Mae hyn yn rhoi'r gallu i atal cyflawni gweithred cyn iddo ddechrau. Bydd dychwelyd ffug gan drafodwr digwyddiad hefyd yn galw'n awtomatig preventDefault().

const myModal = document.querySelector('#myModal')

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

API rhaglennol

Mae pob adeiladwr yn derbyn gwrthrych opsiynau dewisol neu ddim (sy'n cychwyn ategyn gyda'i ymddygiad diofyn):

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

Os hoffech chi gael enghraifft ategyn penodol, mae pob ategyn yn datgelu getInstancedull. Er enghraifft, i adfer enghraifft yn uniongyrchol o elfen:

bootstrap.Popover.getInstance(myPopoverEl)

Bydd y dull hwn yn dychwelyd nullos na chychwynnir enghraifft dros yr elfen y gofynnwyd amdani.

Fel arall, getOrCreateInstancegellir ei ddefnyddio i gael yr enghraifft yn gysylltiedig ag elfen DOM, neu greu un newydd rhag ofn na chafodd ei gychwyn.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Rhag ofn na chychwynnwyd enghraifft, gall dderbyn a defnyddio gwrthrych cyfluniad dewisol fel ail ddadl.

Dewiswyr CSS mewn adeiladwyr

Yn ogystal â'r dulliau getInstancea'r getOrCreateInstancedulliau, gall pob lluniwr ategyn dderbyn elfen DOM neu ddewisydd CSS dilys fel y ddadl gyntaf. Mae elfennau ategyn i'w cael gyda'r querySelectordull gan mai dim ond un elfen y mae ein ategion yn ei chynnal.

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')

Swyddogaethau a thrawsnewidiadau anghydamserol

Mae'r holl ddulliau API rhaglennol yn asyncronig ac yn dychwelyd at y galwr unwaith y bydd y trawsnewid wedi dechrau, ond cyn iddo ddod i ben . Er mwyn cyflawni gweithred unwaith y bydd y trawsnewid wedi'i gwblhau, gallwch wrando ar y digwyddiad cyfatebol.

const myCollapseEl = document.querySelector('#myCollapse')

myCollapseEl.addEventListener('shown.bs.collapse', event => {
  // Action to execute once the collapsible area is expanded
})

Yn ogystal, bydd galwad dull ar gydran trawsnewid yn cael ei anwybyddu .

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`dull

Er y gall ymddangos yn gywir i ddefnyddio'r disposedull yn syth ar ôl hide(), bydd yn arwain at ganlyniadau anghywir. Dyma enghraifft o'r defnydd problemus:

const myModal = document.querySelector('#myModal')
myModal.hide() // it is asynchronous

myModal.addEventListener('shown.bs.hidden', event => {
  myModal.dispose()
})

Gosodiadau diofyn

Gallwch newid y gosodiadau diofyn ar gyfer ategyn trwy addasu Constructor.Defaultgwrthrych yr ategyn:

// changes default for the modal plugin's `keyboard` option to false
bootstrap.Modal.Default.keyboard = false

Dulliau a phriodweddau

Mae pob ategyn Bootstrap yn datgelu'r dulliau a'r priodweddau statig canlynol.

Dull	Disgrifiad
`dispose`	Yn dinistrio moddol elfen. (Yn dileu data sydd wedi'i storio ar yr elfen DOM)
`getInstance`	Dull statig sy'n eich galluogi i gael yr enghraifft foddol sy'n gysylltiedig ag elfen DOM.
`getOrCreateInstance`	Dull statig sy'n eich galluogi i gael yr enghraifft foddol yn gysylltiedig ag elfen DOM, neu greu un newydd rhag ofn na chafodd ei gychwyn.

Eiddo statig	Disgrifiad
`NAME`	Yn dychwelyd enw'r ategyn. (Enghraifft `bootstrap.Tooltip.NAME`:)
`VERSION`	Gellir cyrchu fersiwn pob un o ategion Bootstrap trwy `VERSION`eiddo lluniwr yr ategyn (Enghraifft : `bootstrap.Tooltip.VERSION`)

Glanweithydd

Mae Tooltips a Popovers yn defnyddio ein glanweithydd adeiledig i lanweithio opsiynau sy'n derbyn HTML.

Y gwerth diofyn allowListyw'r canlynol:

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: []
}

Os ydych am ychwanegu gwerthoedd newydd at y rhagosodiad hwn allowListgallwch wneud y canlynol:

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)

Os ydych chi am osgoi ein glanweithydd oherwydd bod yn well gennych chi ddefnyddio llyfrgell bwrpasol, er enghraifft DOMPurify , dylech chi wneud y canlynol:

const yourTooltipEl = document.querySelector('#yourTooltip')
const tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn(content) {
    return DOMPurify.sanitize(content)
  }
})

Gan ddefnyddio jQuery yn ddewisol

Nid oes angen jQuery yn Bootstrap 5 , ond mae'n dal yn bosibl defnyddio ein cydrannau gyda jQuery. Os bydd Bootstrap jQueryyn canfod y windowgwrthrych, bydd yn ychwanegu ein holl gydrannau yn system ategyn jQuery. Mae hyn yn caniatáu ichi wneud y canlynol:

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

Mae'r un peth yn wir am ein cydrannau eraill.

Dim gwrthdaro

Weithiau mae angen defnyddio ategion Bootstrap gyda fframweithiau UI eraill. O dan yr amgylchiadau hyn, gall gwrthdrawiadau gofod enwau ddigwydd o bryd i'w gilydd. Os bydd hyn yn digwydd, gallwch chi alw .noConflictar yr ategyn yr ydych am ddychwelyd ei werth.

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

Nid yw Bootstrap yn cefnogi llyfrgelloedd JavaScript trydydd parti yn swyddogol fel Prototeip neu jQuery UI. Er gwaethaf .noConflictdigwyddiadau a bylchau enwau, efallai y bydd problemau cydnawsedd y bydd angen i chi eu trwsio ar eich pen eich hun.

digwyddiadau jQuery

Bydd Bootstrap yn canfod jQuery os jQueryyw'n bresennol yn y windowgwrthrych ac nid oes data-bs-no-jquerypriodoledd wedi'i osod ar <body>. Os canfyddir jQuery, bydd Bootstrap yn allyrru digwyddiadau diolch i system digwyddiadau jQuery. Felly os ydych chi eisiau gwrando ar ddigwyddiadau Bootstrap, bydd yn rhaid i chi ddefnyddio'r dulliau jQuery ( .on, .one) yn lle addEventListener.

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

JavaScript anabl

Nid oes gan ategion Bootstrap unrhyw wrth gefn arbennig pan fydd JavaScript wedi'i analluogi. Os ydych chi'n poeni am brofiad y defnyddiwr yn yr achos hwn, defnyddiwch <noscript>i egluro'r sefyllfa (a sut i ail-alluogi JavaScript) i'ch defnyddwyr, a / neu ychwanegu eich wrth gefn personol eich hun.