in English

JavaScript

Erwecken Sie Bootstrap mit unseren optionalen JavaScript-Plugins zum Leben. Erfahren Sie mehr über jedes Plugin, unsere Daten- und programmatischen API-Optionen und mehr.

Auf dieser Seite

Einzeln oder zusammengestellt

Plugins können einzeln (mit Bootstrap's individual js/dist/*.js) oder alle auf einmal mit bootstrap.jsoder the minified bootstrap.min.js(nicht beides enthalten) eingebunden werden.

Wenn Sie einen Bundler (Webpack, Parcel, Vite…) verwenden, können Sie /js/dist/*.jsDateien verwenden, die UMD-fähig sind.

Verwendung mit JavaScript-Frameworks

Während das Bootstrap-CSS mit jedem Framework verwendet werden kann, ist das Bootstrap-JavaScript nicht vollständig kompatibel mit JavaScript-Frameworks wie React, Vue und Angular , die eine vollständige Kenntnis des DOM voraussetzen. Sowohl Bootstrap als auch das Framework versuchen möglicherweise, dasselbe DOM-Element zu mutieren, was zu Fehlern wie Dropdowns führt, die in der „offenen“ Position hängen bleiben.

Eine bessere Alternative für diejenigen, die diese Art von Frameworks verwenden, ist die Verwendung eines Framework-spezifischen Pakets anstelle des Bootstrap-JavaScripts. Hier sind einige der beliebtesten Optionen:

Reagieren: Bootstrap reagieren
Vue: BootstrapVue (unterstützt derzeit nur Vue 2 und Bootstrap 4)
Eckig: ng-bootstrap

Bootstrap als Modul verwenden

Versuch es selber! Laden Sie den Quellcode und die funktionierende Demo zur Verwendung von Bootstrap als ES-Modul aus dem twbs/examples-Repository herunter . Sie können das Beispiel auch in StackBlitz öffnen .

Wir stellen eine Version von Bootstrap bereit, die als ESM( bootstrap.esm.jsund bootstrap.esm.min.js) erstellt wurde und es Ihnen ermöglicht, Bootstrap als Modul im Browser zu verwenden, wenn Ihre Zielbrowser dies unterstützen .

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

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

Im Vergleich zu JS-Bundlern müssen Sie bei der Verwendung von ESM im Browser den vollständigen Pfad und Dateinamen anstelle des Modulnamens verwenden. Lesen Sie mehr über JS-Module im Browser. Deshalb verwenden wir 'bootstrap.esm.min.js'statt 'bootstrap'oben. Dies wird jedoch durch unsere Popper-Abhängigkeit weiter erschwert, die Popper wie folgt in unser JavaScript importiert:

import * as Popper from "@popperjs/core"

Wenn Sie dies unverändert versuchen, wird in der Konsole ein Fehler wie der folgende angezeigt:

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

Um dies zu beheben, können Sie mit einem importmapdie beliebigen Modulnamen in vollständige Pfade auflösen. Wenn Ihre Zielbrowser , nicht unterstützen importmap, müssen Sie das es-module-shims- Projekt verwenden. So funktioniert es für Bootstrap und 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>

Abhängigkeiten

Einige Plugins und CSS-Komponenten sind von anderen Plugins abhängig. Wenn Sie Plugins einzeln einbinden, stellen Sie sicher, dass Sie in der Dokumentation nach diesen Abhängigkeiten suchen.

Unsere Dropdowns, Popovers und Tooltips hängen auch von Popper ab .

Datenattribute

Nahezu alle Bootstrap-Plug-ins können nur über HTML mit Datenattributen aktiviert und konfiguriert werden (unsere bevorzugte Methode zur Verwendung der JavaScript-Funktionalität). Stellen Sie sicher, dass Sie nur einen Satz von Datenattributen für ein einzelnes Element verwenden (z. B. können Sie einen Tooltip und ein Modal nicht über dieselbe Schaltfläche auslösen).

Da Optionen über Datenattribute oder JavaScript übergeben werden können, können Sie einen Optionsnamen data-bs-wie in anhängen data-bs-animation="{value}". Stellen Sie sicher, dass Sie den Falltyp des Optionsnamens von " camelCase " in " kebab -case " ändern, wenn Sie die Optionen über Datenattribute übergeben. Verwenden Sie beispielsweise data-bs-custom-class="beautifier"anstelle von data-bs-customClass="beautifier".

Ab Bootstrap 5.2.0 unterstützen alle Komponenten ein experimentelles reserviertes Datenattribut, das eine data-bs-configeinfache Komponentenkonfiguration als JSON-String enthalten kann. Wenn ein Element über data-bs-config='{"delay":0, "title":123}'und data-bs-title="456"-Attribute verfügt, ist der endgültige titleWert 456und die separaten Datenattribute überschreiben die auf angegebenen Werte data-bs-config. Darüber hinaus können vorhandene Datenattribute JSON-Werte wie data-bs-delay='{"show":0,"hide":150}'.

Selektoren

Wir verwenden aus Leistungsgründen die nativen querySelectorund querySelectorAllMethoden zum Abfragen von DOM-Elementen, daher müssen Sie gültige Selektoren verwenden . Wenn Sie spezielle Selektoren wie verwenden collapse:Example, achten Sie darauf, sie zu maskieren.

Veranstaltungen

Bootstrap bietet benutzerdefinierte Ereignisse für die einzigartigen Aktionen der meisten Plugins. Im Allgemeinen kommen diese in einer Infinitiv- und Partizipform vor – wobei der Infinitiv (z. B. show) zu Beginn eines Ereignisses ausgelöst wird und seine Partizipform (z. B. shown) beim Abschluss einer Aktion ausgelöst wird.

Alle Infinitivereignisse bieten preventDefault()Funktionalität. Dies bietet die Möglichkeit, die Ausführung einer Aktion zu stoppen, bevor sie beginnt. Die Rückgabe von false von einem Event-Handler ruft ebenfalls automatisch auf preventDefault().

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

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

Programmatische API

Alle Konstruktoren akzeptieren ein optionales Optionsobjekt oder nichts (was ein Plugin mit seinem Standardverhalten initiiert):

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

Wenn Sie eine bestimmte Plugin-Instanz erhalten möchten, stellt jedes Plugin eine getInstanceMethode bereit. Um beispielsweise eine Instanz direkt von einem Element abzurufen:

bootstrap.Popover.getInstance(myPopoverEl)

Diese Methode gibt zurück, nullwenn keine Instanz über das angeforderte Element initiiert wird.

Alternativ getOrCreateInstancekann verwendet werden, um die mit einem DOM-Element verknüpfte Instanz abzurufen oder eine neue zu erstellen, falls sie nicht initialisiert wurde.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Falls eine Instanz nicht initialisiert wurde, kann sie ein optionales Konfigurationsobjekt als zweites Argument akzeptieren und verwenden.

CSS-Selektoren in Konstruktoren

Zusätzlich zu den Methoden getInstanceund getOrCreateInstancekönnen alle Plugin-Konstruktoren ein DOM-Element oder einen gültigen CSS-Selektor als erstes Argument akzeptieren. Plugin-Elemente werden mit der querySelectorMethode gefunden, da unsere Plugins nur ein einzelnes Element unterstützen.

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

Asynchrone Funktionen und Übergänge

Alle programmgesteuerten API-Methoden sind asynchron und kehren zum Aufrufer zurück, sobald der Übergang gestartet wird, aber bevor er endet . Um eine Aktion auszuführen, nachdem der Übergang abgeschlossen ist, können Sie auf das entsprechende Ereignis lauschen.

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

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

Außerdem wird ein Methodenaufruf einer Übergangskomponente ignoriert .

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

Auch wenn es richtig erscheinen mag, die disposeMethode direkt nach anzuwenden hide(), führt dies zu falschen Ergebnissen. Hier ist ein Beispiel für die problematische Verwendung:

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

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

Standardeinstellungen

Sie können die Standardeinstellungen für ein Plugin ändern, indem Sie das Constructor.DefaultObjekt des Plugins ändern:

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

Methoden und Eigenschaften

Jedes Bootstrap-Plugin stellt die folgenden Methoden und statischen Eigenschaften bereit.

Methode	Beschreibung
`dispose`	Zerstört das Modal eines Elements. (Entfernt gespeicherte Daten auf dem DOM-Element)
`getInstance`	Statische Methode, mit der Sie die modale Instanz abrufen können, die einem DOM-Element zugeordnet ist.
`getOrCreateInstance`	Statische Methode, mit der Sie die mit einem DOM-Element verknüpfte modale Instanz abrufen oder eine neue erstellen können, falls sie nicht initialisiert wurde.

Statische Eigenschaft	Beschreibung
`NAME`	Gibt den Plugin-Namen zurück. (Beispiel: `bootstrap.Tooltip.NAME`)
`VERSION`	Auf die Version jedes Bootstrap-Plugins kann über die `VERSION`Eigenschaft des Konstruktors des Plugins zugegriffen werden (Beispiel: `bootstrap.Tooltip.VERSION`)

Desinfektionsmittel

Tooltips und Popovers verwenden unseren integrierten Bereinigungsdienst, um Optionen zu bereinigen, die HTML akzeptieren.

Der Standardwert allowListist der folgende:

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

Wenn Sie diesem Standardwert neue Werte hinzufügen möchten, allowListkönnen Sie Folgendes tun:

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)

Wenn Sie unseren Sanitizer umgehen möchten, weil Sie lieber eine dedizierte Bibliothek verwenden, z. B. DOMpurify , sollten Sie Folgendes tun:

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

Optional mit jQuery

Sie brauchen jQuery in Bootstrap 5 nicht , aber es ist trotzdem möglich, unsere Komponenten mit jQuery zu verwenden. Wenn Bootstrap jQuerydas windowObjekt erkennt, fügt es alle unsere Komponenten in das Plug-in-System von jQuery ein. Dadurch können Sie Folgendes tun:

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

Gleiches gilt für unsere anderen Komponenten.

Kein Konflikt

Manchmal ist es notwendig, Bootstrap-Plugins mit anderen UI-Frameworks zu verwenden. Unter diesen Umständen kann es gelegentlich zu Namespace-Kollisionen kommen. In diesem Fall können Sie .noConflictdas Plugin aufrufen, dessen Wert Sie zurücksetzen möchten.

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

Bootstrap unterstützt offiziell keine JavaScript-Bibliotheken von Drittanbietern wie Prototype oder jQuery UI. Trotz .noConflictund Namespace-Ereignissen kann es zu Kompatibilitätsproblemen kommen, die Sie selbst beheben müssen.

jQuery-Ereignisse

Bootstrap erkennt jQuery, wenn jQueryes im windowObjekt vorhanden ist und kein data-bs-no-jqueryAttribut auf gesetzt ist <body>. Wenn jQuery gefunden wird, gibt Bootstrap dank des Ereignissystems von jQuery Ereignisse aus. Wenn Sie also Bootstrap-Ereignisse abhören möchten, müssen Sie die jQuery-Methoden ( .on, .one) anstelle von verwenden addEventListener.

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

JavaScript deaktiviert

Bootstrap-Plugins haben keinen speziellen Fallback, wenn JavaScript deaktiviert ist. Wenn Ihnen in diesem Fall die Benutzererfahrung wichtig ist, verwenden Sie <noscript>, um Ihren Benutzern die Situation zu erklären (und wie JavaScript wieder aktiviert wird) und/oder fügen Sie Ihre eigenen benutzerdefinierten Fallbacks hinzu.