JavaScript

Δώστε ζωή στο Bootstrap με τις προαιρετικές μας προσθήκες JavaScript. Μάθετε για κάθε προσθήκη, τις επιλογές δεδομένων και προγραμματιστικών API και πολλά άλλα.

Σε αυτήν την σελίδα

Ατομικό ή μεταγλωττισμένο

Τα πρόσθετα μπορούν να συμπεριληφθούν μεμονωμένα (χρησιμοποιώντας το μεμονωμένο του Bootstrap js/dist/*.js), ή όλα ταυτόχρονα χρησιμοποιώντας bootstrap.jsή ελαχιστοποιημένα bootstrap.min.js(μην συμπεριλαμβάνονται και τα δύο).

Εάν χρησιμοποιείτε bundler (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)
Γωνιακό: 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 εξαρτώνται από άλλα πρόσθετα. Εάν συμπεριλάβετε προσθήκες μεμονωμένα, φροντίστε να ελέγξετε για αυτές τις εξαρτήσεις στα έγγραφα.

Τα αναπτυσσόμενα, τα popover και οι συμβουλές εργαλείων μας εξαρτώνται επίσης από το Popper .

Χαρακτηριστικά δεδομένων

Σχεδόν όλα τα πρόσθετα Bootstrap μπορούν να ενεργοποιηθούν και να ρυθμιστούν μόνο μέσω HTML με χαρακτηριστικά δεδομένων (ο προτιμώμενος τρόπος χρήσης της λειτουργικότητας JavaScript). Βεβαιωθείτε ότι χρησιμοποιείτε μόνο ένα σύνολο χαρακτηριστικών δεδομένων σε ένα μόνο στοιχείο (π.χ., δεν μπορείτε να ενεργοποιήσετε μια επεξήγηση εργαλείου και ένα modal από το ίδιο κουμπί.)

Καθώς οι επιλογές μπορούν να μεταβιβαστούν μέσω χαρακτηριστικών δεδομένων ή 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`	Στατική μέθοδος που σας επιτρέπει να λαμβάνετε το modal instance που σχετίζεται με ένα στοιχείο DOM.
`getOrCreateInstance`	Στατική μέθοδος που σας επιτρέπει να λαμβάνετε το modal στιγμιότυπο που σχετίζεται με ένα στοιχείο DOM ή να δημιουργήσετε ένα νέο σε περίπτωση που δεν είχε αρχικοποιηθεί.

Στατική ιδιότητα	Περιγραφή
`NAME`	Επιστρέφει το όνομα της προσθήκης. (Παράδειγμα: `bootstrap.Tooltip.NAME`)
`VERSION`	Η έκδοση καθενός από τις προσθήκες του Bootstrap είναι προσβάσιμη μέσω της `VERSION`ιδιότητας του κατασκευαστή της προσθήκης (Παράδειγμα: `bootstrap.Tooltip.VERSION`)

Απολυμαντικό

Τα Tooltips και τα Popover χρησιμοποιούν το ενσωματωμένο μας απολυμαντικό για να απολυμάνουν επιλογές που δέχονται 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) στους χρήστες σας ή/και να προσθέσετε τις δικές σας προσαρμοσμένες εναλλακτικές.