Passer au contenu principal Passer à la navigation dans les documents
Check
in English

Javascript

Donnez vie à Bootstrap avec nos plugins JavaScript optionnels. Découvrez chaque plug-in, nos options d'API de données et de programmation, et plus encore.

Sur cette page

Individuel ou compilé

Les plugins peuvent être inclus individuellement (à l'aide de Bootstrap's individual js/dist/*.js), ou tous à la fois à bootstrap.jsl'aide de ou minified bootstrap.min.js(n'incluez pas les deux).

Si vous utilisez un bundler (Webpack, Parcel, Vite…), vous pouvez utiliser des /js/dist/*.jsfichiers compatibles UMD.

Utilisation avec les frameworks JavaScript

Bien que le CSS Bootstrap puisse être utilisé avec n'importe quel framework, le JavaScript Bootstrap n'est pas entièrement compatible avec les frameworks JavaScript tels que React, Vue et Angular qui supposent une connaissance complète du DOM. Bootstrap et le framework peuvent tenter de muter le même élément DOM, ce qui entraîne des bogues tels que des listes déroulantes bloquées en position "ouverte".

Une meilleure alternative pour ceux qui utilisent ce type de frameworks est d'utiliser un package spécifique au framework au lieu du JavaScript Bootstrap. Voici quelques-unes des options les plus populaires :

Utiliser Bootstrap comme module

Essayez-le vous-même ! Téléchargez le code source et la démonstration de travail pour utiliser Bootstrap en tant que module ES à partir du référentiel twbs/examples . Vous pouvez également ouvrir l'exemple dans StackBlitz .

Nous fournissons une version de Bootstrap construite en tant que ESM( bootstrap.esm.jset bootstrap.esm.min.js) qui vous permet d'utiliser Bootstrap en tant que module dans le navigateur, si vos navigateurs ciblés le supportent .

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

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

Par rapport aux bundlers JS, l'utilisation d'ESM dans le navigateur nécessite que vous utilisiez le chemin complet et le nom de fichier au lieu du nom du module. En savoir plus sur les modules JS dans le navigateur. C'est pourquoi nous utilisons 'bootstrap.esm.min.js'au lieu de ci- 'bootstrap'dessus. Cependant, cela est encore compliqué par notre dépendance Popper, qui importe Popper dans notre JavaScript comme ceci :

import * as Popper from "@popperjs/core"

Si vous essayez ceci tel quel, vous verrez une erreur dans la console comme celle-ci :

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

Pour résoudre ce problème, vous pouvez utiliser un importmappour résoudre les noms de module arbitraires en chemins complets. Si vos navigateurs ciblés ne prennent pas en charge importmap, vous devrez utiliser le projet es-module-shims . Voici comment cela fonctionne pour Bootstrap et 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>

Dépendances

Certains plugins et composants CSS dépendent d'autres plugins. Si vous incluez des plugins individuellement, assurez-vous de vérifier ces dépendances dans la documentation.

Nos listes déroulantes, popovers et infobulles dépendent également de Popper .

Attributs de données

Presque tous les plugins Bootstrap peuvent être activés et configurés uniquement via HTML avec des attributs de données (notre manière préférée d'utiliser la fonctionnalité JavaScript). Assurez-vous de n'utiliser qu'un seul ensemble d'attributs de données sur un seul élément (par exemple, vous ne pouvez pas déclencher une info-bulle et un modal à partir du même bouton.)

Comme les options peuvent être transmises via des attributs de données ou JavaScript, vous pouvez ajouter un nom d'option à data-bs-, comme dans data-bs-animation="{value}". Assurez-vous de changer le type de casse du nom de l'option de " camelCase " à " kebab-case " lors du passage des options via les attributs de données. Par exemple, utilisez à la data-bs-custom-class="beautifier"place de data-bs-customClass="beautifier".

Depuis Bootstrap 5.2.0, tous les composants prennent en charge un attribut de données expérimentaldata-bs-config réservé pouvant héberger une configuration de composant simple sous forme de chaîne JSON. Lorsqu'un élément a des attributs data-bs-config='{"delay":0, "title":123}'et , la valeur finale sera et les attributs de données séparés remplaceront les valeurs données sur . De plus, les attributs de données existants peuvent héberger des valeurs JSON telles que .data-bs-title="456"title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

Sélecteurs

Nous utilisons les méthodes natives querySelectoret querySelectorAllpour interroger les éléments DOM pour des raisons de performances, vous devez donc utiliser des sélecteurs valides . Si vous utilisez des sélecteurs spéciaux comme collapse:Example, assurez-vous de les échapper.

Événements

Bootstrap fournit des événements personnalisés pour les actions uniques de la plupart des plugins. Généralement, ceux-ci se présentent sous une forme infinitive et participe passé - où l'infinitif (ex. show) est déclenché au début d'un événement, et sa forme de participe passé (ex. shown) est déclenchée à la fin d'une action.

Tous les événements infinitifs fournissent des preventDefault()fonctionnalités. Cela permet d'arrêter l'exécution d'une action avant qu'elle ne démarre. Retourner false à partir d'un gestionnaire d'événements appellera également automatiquement preventDefault().

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

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

API programmatique

Tous les constructeurs acceptent un objet d'options optionnel ou rien (qui lance un plugin avec son comportement par défaut) :

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

Si vous souhaitez obtenir une instance de plugin particulière, chaque plugin expose une getInstanceméthode. Par exemple, pour récupérer une instance directement depuis un élément :

bootstrap.Popover.getInstance(myPopoverEl)

Cette méthode retournera nullsi une instance n'est pas initiée sur l'élément demandé.

Alternativement, getOrCreateInstancepeut être utilisé pour obtenir l'instance associée à un élément DOM, ou en créer un nouveau au cas où il n'aurait pas été initialisé.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Si une instance n'a pas été initialisée, elle peut accepter et utiliser un objet de configuration facultatif comme deuxième argument.

Sélecteurs CSS dans les constructeurs

En plus des méthodes getInstanceet getOrCreateInstance, tous les constructeurs de plugins peuvent accepter un élément DOM ou un sélecteur CSS valide comme premier argument. Les éléments de plugin sont trouvés avec la querySelectorméthode puisque nos plugins ne supportent qu'un seul élément.

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

Fonctions et transitions asynchrones

Toutes les méthodes API programmatiques sont asynchrones et reviennent à l'appelant une fois la transition démarrée, mais avant qu'elle ne se termine . Afin d'exécuter une action une fois la transition terminée, vous pouvez écouter l'événement correspondant.

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

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

De plus, un appel de méthode sur un composant en transition sera ignoré .

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 !!

disposeméthode

Bien qu'il puisse sembler correct d'utiliser la disposeméthode immédiatement après hide(), cela conduira à des résultats incorrects. Voici un exemple d'utilisation du problème :

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

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

Paramètres par défaut

Vous pouvez modifier les paramètres par défaut d'un plugin en modifiant l' Constructor.Defaultobjet du plugin :

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

Méthodes et propriétés

Chaque plugin Bootstrap expose les méthodes et propriétés statiques suivantes.

Méthode La description
dispose Détruit le modal d'un élément. (Supprime les données stockées sur l'élément DOM)
getInstance Méthode statique qui permet d'obtenir l'instance modale associée à un élément DOM.
getOrCreateInstance Méthode statique qui permet d'obtenir l'instance modale associée à un élément DOM, ou d'en créer une nouvelle au cas où elle n'aurait pas été initialisée.
Propriété statique La description
NAME Renvoie le nom du plug-in. (Exemple : bootstrap.Tooltip.NAME)
VERSION La version de chacun des plugins de Bootstrap est accessible via la VERSIONpropriété du constructeur du plugin (Exemple : bootstrap.Tooltip.VERSION)

Désinfectant

Les info-bulles et les popovers utilisent notre assainisseur intégré pour assainir les options qui acceptent le HTML.

La valeur par défaut allowListest la suivante :

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

Si vous souhaitez ajouter de nouvelles valeurs à cette valeur par défaut allowList, vous pouvez procéder comme suit :

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)

Si vous souhaitez contourner notre désinfectant parce que vous préférez utiliser une bibliothèque dédiée, par exemple DOMPurify , vous devez procéder comme suit :

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

Utiliser éventuellement jQuery

Vous n'avez pas besoin de jQuery dans Bootstrap 5 , mais il est toujours possible d'utiliser nos composants avec jQuery. Si Bootstrap détecte jQuerydans l' windowobjet, il ajoutera tous nos composants dans le système de plug-in de jQuery. Cela vous permet de faire ce qui suit :

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

Il en va de même pour nos autres composants.

Pas de conflit

Parfois, il est nécessaire d'utiliser des plugins Bootstrap avec d'autres frameworks d'interface utilisateur. Dans ces circonstances, des collisions d'espaces de noms peuvent parfois se produire. Si cela se produit, vous pouvez appeler .noConflictle plugin dont vous souhaitez annuler la valeur.

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

Bootstrap ne prend pas officiellement en charge les bibliothèques JavaScript tierces telles que Prototype ou jQuery UI. Malgré .noConflictles événements et les espaces de noms, il peut y avoir des problèmes de compatibilité que vous devez résoudre vous-même.

Événements jQuery

Bootstrap détectera jQuery s'il jQueryest présent dans l' windowobjet et qu'aucun data-bs-no-jqueryattribut n'est défini sur <body>. Si jQuery est trouvé, Bootstrap émettra des événements grâce au système d'événements de jQuery. Donc, si vous voulez écouter les événements de Bootstrap, vous devrez utiliser les méthodes jQuery ( .on, .one) au lieu de addEventListener.

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

JavaScript désactivé

Les plugins de Bootstrap n'ont pas de repli spécial lorsque JavaScript est désactivé. Si vous vous souciez de l'expérience utilisateur dans ce cas, utilisez <noscript>pour expliquer la situation (et comment réactiver JavaScript) à vos utilisateurs, et/ou ajoutez vos propres solutions de repli personnalisées.