in English

JavaScript

Cuir Bootstrap ar an saol lenár bhforlíontáin roghnacha JavaScript. Foghlaim faoi gach breiseán, ár sonraí agus ár roghanna API ríomhchláraithe, agus tuilleadh.

Ar an leathanach seo

Aonair nó tiomsaithe

Is féidir forlíontáin a áireamh ina n-aonar (ag baint úsáide as duine aonair Bootstrap js/dist/*.js), nó iad go léir ag baint úsáide as bootstrap.jsnó an mionghearrtha ag an am céanna bootstrap.min.js(ná cuir an dá cheann san áireamh).

Má úsáideann tú cuachta (Webpack, Beartán, Vite…), is féidir leat /js/dist/*.jscomhaid a úsáid atá réidh le UMD.

Úsáid le creataí JavaScript

Cé gur féidir an CSS Bootstrap a úsáid le haon chreat, níl an Bootstrap JavaScript comhoiriúnach go hiomlán le creataí JavaScript mar React, Vue, agus Angular a ghlacann eolas iomlán ar an DOM. D’fhéadfadh go ndéanfadh Bootstrap agus an creat araon iarracht an eilimint DOM céanna a athrú ó bhonn, rud a fhágann go mbeidh fabhtanna cosúil le anuas atá i bhfostú sa suíomh “oscailte”.

Rogha eile níos fearr dóibh siúd a bhaineann úsáid as creataí den chineál seo ná pacáiste sainchreat a úsáid in ionad an Bootstrap JavaScript. Seo cuid de na roghanna is coitianta:

Frithghníomh: React Bootstrap
Vue: BootstrapVue (ní thacaíonn ach Vue 2 agus Bootstrap 4 faoi láthair)
Uillinn: ng-bootstrap

Ag baint úsáide as Bootstrap mar mhodúl

Bain triail as tú féin! Íoslódáil an cód foinse agus an taispeántas oibre chun Bootstrap a úsáid mar mhodúl ES ón stór twbs/samplaí . Is féidir leat an sampla a oscailt i StackBlitz freisin .

Soláthraímid leagan de Bootstrap tógtha mar ESM( bootstrap.esm.jsagus bootstrap.esm.min.js) a ligeann duit Bootstrap a úsáid mar mhodúl sa bhrabhsálaí, má thacaíonn do bhrabhsálaithe spriocdhírithe leis .

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

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

I gcomparáid le cugóirí JS, má úsáidtear ESM sa bhrabhsálaí ní mór duit an cosán iomlán agus ainm an chomhaid a úsáid in ionad ainm an mhodúil. Léigh tuilleadh faoi mhodúil JS sa bhrabhsálaí. Sin an fáth a úsáidimid 'bootstrap.esm.min.js'in ionad 'bootstrap'thuas. Mar sin féin, tá sé seo casta níos mó ag ár spleáchas Popper, a iompórtálann Popper isteach inár JavaScript mar seo:

import * as Popper from "@popperjs/core"

Má dhéanann tú iarracht é seo mar atá, feicfidh tú earráid sa chonsól mar seo a leanas:

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

Chun é seo a shocrú, is féidir leat úsáid a bhaint as importmapchun ainmneacha na modúl treallach a réiteach chun cosáin a chríochnú. Mura dtacaíonn do bhrabhsálaithe spriocdhíritheimportmap le , beidh ort an tionscadal es-module-shims a úsáid . Seo mar a oibríonn sé do Bootstrap agus 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>

Spleáchais

Braitheann roinnt breiseán agus comhpháirteanna CSS ar fhorlíontáin eile. Má chuireann tú forlíontáin san áireamh ina n-aonar, déan cinnte seiceáil le haghaidh na spleáchais seo sna doiciméid.

Braitheann ár dropdowns, popovers, agus leideanna uirlisí ar Popper freisin .

Tréithe sonraí

Is féidir beagnach gach breiseán Bootstrap a chumasú agus a chumrú trí HTML amháin le tréithe sonraí (an bealach is fearr linn feidhmiúlacht JavaScript a úsáid). Bí cinnte nach n-úsáideann ach sraith amháin de shaintréithe sonraí ar eilimint amháin (m.sh., ní féidir leat leid uirlisí agus modha a spreagadh ón gcnaipe céanna).

Toisc gur féidir roghanna a chur ar aghaidh trí tréithe sonraí nó JavaScript, is féidir leat ainm rogha a chur i gceangal le data-bs-, mar atá i data-bs-animation="{value}". Bí cinnte cineál an cháis den ainm rogha a athrú ó “ camelCase ” go “ kebab-case ” agus tú ag dul thar na roghanna trí tréithe sonraí. Mar shampla, úsáid data-bs-custom-class="beautifier"in ionad data-bs-customClass="beautifier".

Amhail Bootstrap 5.2.0, tacaíonn na comhpháirteanna go léir le tréith sonraí forchoimeádta turgnamhachadata-bs-config ar féidir cumraíocht chomhpháirt shimplí a áireamh mar theaghrán JSON. data-bs-config='{"delay":0, "title":123}'Nuair a bhíonn agus tréithe ag eilimint , is é an luach data-bs-title="456"deiridh a bheidh ann agus sáróidh na tréithe sonraí ar leith na luachanna a thugtar ar . Ina theannta sin, tá tréithe sonraí atá ann cheana in ann luachanna JSON cosúil le .title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

Roghnóirí

Úsáidimid na modhanna dúchasacha querySelectoragus na querySelectorAllmodhanna chun gnéithe DOM a cheistiú ar chúiseanna feidhmíochta, mar sin ní mór duit roghnóir bailí a úsáid . Má úsáideann tú roghnóirí speisialta cosúil le collapse:Example, a bheith cinnte chun éalú leo.

Imeachtaí

Soláthraíonn Bootstrap imeachtaí saincheaptha le haghaidh gníomhartha uathúla fhormhór na mbreiseán. Go ginearálta, is i bhfoirm infinideach agus i bhfoirm rannpháirtí san am atá thart a thagann siad seo - áit a spreagtar an infinideach (ex. show) ag tús imeachta, agus ina shownspreagtar foirm an rannpháirtí san am atá thart (ex. ) ar chríochnú gníomhaíochta.

Soláthraíonn gach imeacht infinitive preventDefault()feidhmiúlacht. Soláthraíonn sé seo an cumas chun stop a chur le gníomh a chur i gcrích sula dtosaíonn sé. Má fhilleann tú bréagach ó láimhseálaí teagmhais, glaofar go huathoibríoch é preventDefault().

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

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

Clár API

Glacann gach tógálaí le réad roghanna roghnach nó rud ar bith (a chuireann tús le breiseán lena iompar réamhshocraithe):

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

Más mian leat sampla breiseán ar leith a fháil, nochtfaidh gach breiseán getInstancemodh. Mar shampla, chun sampla a fháil go díreach ó eilimint:

bootstrap.Popover.getInstance(myPopoverEl)

Fillfidh an modh seo nullmura gcuirtear tús le cás thar an eilimint iarrtha.

Mar mhalairt air sin, getOrCreateInstanceis féidir é a úsáid chun an t-úsc a bhaineann le heilimint DOM a fháil, nó ceann nua a chruthú ar eagla nár cuireadh tús leis.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Sa chás nár cuireadh tús le cás, féadfaidh sé glacadh le réad cumraíochta roghnach agus é a úsáid mar dhara argóint.

Roghnóirí CSS i dtógálaithe

Chomh maith leis na modhanna getInstanceagus na getOrCreateInstancemodhanna, is féidir le gach cruthaitheoir breiseán glacadh le eilimint DOM nó roghnóir CSS bailí mar an chéad argóint. Faightear eilimintí breiseán leis an querySelectormodh mar ní thacaíonn ár bhforlíontáin ach le heilimint amháin.

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

Feidhmeanna agus aistrithe asincrónacha

Tá na modhanna API ríomhchláraithe go léir asincrónach agus filleann siad chuig an nglaoiteoir nuair a bhíonn an t-aistriú tosaithe, ach sula dtiocfaidh deireadh leis . Chun gníomh a dhéanamh nuair a bheidh an t-aistriú críochnaithe, is féidir leat éisteacht leis an imeacht comhfhreagrach.

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

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

Ina theannta sin, ní thabharfar aird ar ghlao modha ar chomhpháirt trasdula .

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

Cé go bhféadfadh sé cosúil go bhfuil sé ceart an disposemodh a úsáid díreach tar éis hide(), beidh torthaí mícheart mar thoradh air. Seo sampla den fhadhbúsáid:

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

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

Socruithe réamhshocraithe

Is féidir leat na socruithe réamhshocraithe le haghaidh breiseán a athrú trí Constructor.Defaultréad an bhreiseáin a mhodhnú:

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

Modhanna agus airíonna

Nochtann gach breiseán Bootstrap na modhanna agus na hairíonna statacha seo a leanas.

Modh	Cur síos
`dispose`	Scriosann modhúil eilimint. (Baintear sonraí stóráilte ar an eilimint DOM)
`getInstance`	Modh statach a cheadaíonn duit an t-ásc módúil a bhaineann le heilimint DOM a fháil.
`getOrCreateInstance`	Modh statach a cheadaíonn duit an t-ásc módúil a bhaineann le heilimint DOM a fháil, nó ceann nua a chruthú ar eagla nár cuireadh tús leis.

Maoin statach	Cur síos
`NAME`	Seoltar ainm an bhreiseáin ar ais. (Sampla: `bootstrap.Tooltip.NAME`)
`VERSION`	Is féidir an leagan de gach breiseán de chuid Bootstrap a rochtain trí `VERSION`airí chruthaitheoir an bhreiseáin (Sampla: `bootstrap.Tooltip.VERSION`)

Sanitizer

Úsáideann Leideanna Uirlisí agus Popovers ár sláintitheoir ionsuite chun roghanna a ghlacann le HTML a shláintiú.

allowListSeo a leanas an luach réamhshocraithe :

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

Más mian leat luachanna nua a chur leis an réamhshocrú seo allowListis féidir leat na rudaí seo a leanas a dhéanamh:

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)

Más mian leat ár sláintitheoir a sheachbhóthar toisc gur fearr leat leabharlann thiomanta a úsáid, mar shampla DOMPurify , ba cheart duit na rudaí seo a leanas a dhéanamh:

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

Ag baint úsáide as jQuery go roghnach

Níl jQuery uait i Bootstrap 5 , ach is féidir ár gcomhpháirteanna a úsáid le jQuery fós. Má bhraitheann Bootstrap jQueryan windowréad, cuirfidh sé ár gcomhpháirteanna go léir i gcóras breiseán jQuery. Ligeann sé seo duit na rudaí seo a leanas a dhéanamh:

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

Tá an rud céanna i gceist lenár gcomhpháirteanna eile.

Gan choimhlint

Uaireanta is gá forlíontáin Bootstrap a úsáid le creataí Chomhéadain eile. Sna cúinsí seo, féadann imbhuailtí ainmspáis tarlú ó am go chéile. Má tharlaíonn sé seo, is féidir leat glaoch .noConflictar an mbreiseán is mian leat a luach a chur ar ais.

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

Ní thacaíonn Bootstrap go hoifigiúil le leabharlanna tríú páirtí JavaScript ar nós Fréamhshamhail nó Chomhéadain jQuery. In ainneoin .noConflictimeachtaí agus ainmspás orthu, d’fhéadfadh fadhbanna comhoiriúnachta a bheith ann nach mór duit a réiteach i d’aonar.

imeachtaí jQuery

Braithfidh Bootstrap jQuery má tá jQuerysé i láthair san windowoibiacht agus mura bhfuil aon data-bs-no-jqueryaitreabúid socraithe ar <body>. Má aimsítear jQuery, scaoilfidh Bootstrap imeachtaí a bhuíochas do chóras imeachtaí jQuery. Mar sin más mian leat éisteacht le himeachtaí Bootstrap, beidh ort na modhanna jQuery ( .on, .one) a úsáid in ionad addEventListener.

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

JavaScript díchumasaithe

Níl aon chúltaca speisialta ag forlíontáin Bootstrap nuair atá JavaScript díchumasaithe. Más spéis leat eispéireas an úsáideora sa chás seo, bain úsáid as <noscript>chun an cás a mhíniú (agus conas JavaScript a athchumasú) do d’úsáideoirí, agus/nó cuir do chuid fallbacks saincheaptha féin leis.