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.
- Individuel ou compilé
- Utiliser Bootstrap comme module
- Dépendances
- Vous voulez toujours utiliser jQuery ? C'est possible!
- Attributs de données
- Événements
- API programmatique
- Pas de conflit (uniquement si vous utilisez jQuery)
- Numéros de version
- Pas de repli spécial lorsque JavaScript est désactivé
- Désinfectant
Individuel ou compilé
Les plugins peuvent être inclus individuellement (en utilisant le js/dist/*.js
individuel de Bootstrap), ou tous à la fois en utilisant bootstrap.js
ou le bootstrap.min.js
(ne pas inclure les deux).
Si vous utilisez un bundler (Webpack, Rollup…), vous pouvez utiliser des fichiers /js/dist/*.js
qui sont prêts pour UMD.
Utiliser Bootstrap comme module
Nous fournissons une version de Bootstrap construite comme ESM
(bootstrap.esm.js
et bootstrap.esm.min.js
) qui permet vous permet d'utiliser Bootstrap en tant que module dans votre 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>
Plugins incompatibles
En raison des limitations du navigateur, certains de nos plugins, à savoir les plugins Dropdown, Tooltip et Popover, ne peuvent pas être utilisés dans une balise <script>
de type module
car ils dépendent de Popper. Pour plus d'informations sur le problème, consultez ici.
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.
Vous voulez toujours utiliser jQuery ? C'est possible !
Bootstrap 5 est conçu pour être utilisé sans jQuery, mais il est toujours possible d'utiliser nos composants avec jQuery. Si Bootstrap détecte jQuery
dans l'objet window
, il ajoutera tous nos composants dans le système de plug-in de jQuery ; cela signifie que vous pourrez faire $('[data-bs-toggle="tooltip"]').tooltip()
pour activer les info-bulles. Il en va de même pour nos autres composants.
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 une fenêtre modale à partir du même bouton.)
Sélecteurs
Actuellement, pour interroger les éléments DOM, nous utilisons les méthodes natives querySelector
et querySelectorAll
pour des raisons de performances, vous devez donc utiliser sélecteurs valides.
Si vous utilisez des sélecteurs spéciaux, par exemple : 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 la forme d'un infinitif et d'un 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é à la fin d'une action.
Tous les événements infinitifs fournissent preventDefault()
fonctionnalité. 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()
.
var monModal = document.getElementById('myModal')
myModal.addEventListener('show.bs.modal', function (event) {
if (!data) {
return event.preventDefault() // stops modal from being shown
}
})
Événements jQuery
Bootstrap détectera jQuery si jQuery
est présent dans l'objet window
et qu'il n'y a pas d'attribut data-bs-no-jquery
défini sur <corps>
. 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', function () {
// do something...
})
API programmatique
Tous les constructeurs acceptent un objet d'options optionnel ou rien (qui lance un plugin avec son comportement par défaut) :
var myModalEl = document.getElementById('myModal')
var modal = new bootstrap.Modal(myModalEl) // initialized with defaults
var modal = new bootstrap.Modal(myModalEl, { keyboard: false }) // initialized with no keyboard
Si vous souhaitez obtenir une instance de plugin particulière, chaque plugin expose une méthode getInstance
. Pour le récupérer directement depuis un élément, faites ceci : bootstrap.Popover.getInstance(myPopoverEl)
.
Sélecteurs CSS dans les constructeurs
Vous pouvez également utiliser un sélecteur CSS comme premier argument au lieu d'un élément DOM pour initialiser le plugin. Actuellement, l'élément du plug-in est trouvé par la méthode querySelector
puisque nos plug-ins ne prennent en charge qu'un seul élément.
var modal = new bootstrap.Modal('#myModal')
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
Fonctions et transitions asynchrones
Toutes les méthodes API programmatiques sont asynchrones et reviennent à l'appelant une fois la transition commencé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.
var myCollapseEl = document.getElementById('myCollapse')
myCollapseEl.addEventListener('shown.bs.collapse', function (event) {
// Action to execute once the collapsible area is expanded
})
De plus, un appel de méthode sur un composant de transition sera ignoré.
var myCarouselEl = document.getElementById('myCarousel')
var carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance
myCarouselEl.addEventListener('slid.bs.carousel', function (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 !!
Paramètres par défaut
Vous pouvez modifier les paramètres par défaut d'un plug-in en modifiant l'objet Constructor.Default
du plug-in :
// changes default for the modal plugin's `keyboard` option to false
bootstrap.Modal.Default.keyboard = false
Pas de conflit (uniquement si vous utilisez jQuery)
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 .noConflict
sur le plugin dont vous souhaitez annuler la valeur.
var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality
Numéros de version
La version de chacun des plugins Bootstrap est accessible via la propriété VERSION
du constructeur du plugin. Par exemple, pour le plugin tooltip :
bootstrap.Tooltip.VERSION // => "5.0.2"
Pas de repli spécial lorsque JavaScript est désactivé
Les plugins de Bootstrap ne se replient pas particulièrement bien 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 ajouter vos propres solutions de repli personnalisées.
Bibliothèques tierces
Bootstrap ne prend pas officiellement en charge les bibliothèques JavaScript tierces telles que Prototype ou jQuery UI. Malgré .noConflict
et les événements d'espace de noms, il peut y avoir des problèmes de compatibilité que vous devez résoudre vous-même.
Désinfectant
Les info-bulles et les popovers utilisent notre nettoyeur intégré pour nettoyer les options qui acceptent le HTML.
La valeur par défaut allowList
est la suivante :
var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var 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: []
}
If you want to add new values to this default allowList
you can do the following:
var 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
var 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 le faire ce qui suit :
var yourTooltipEl = document.getElementById('yourTooltip')
var tooltip = new bootstrap.Tooltip(yourTooltipEl, {
sanitizeFn: function (content) {
return DOMPurify.sanitize(content)
}
})