Javascript

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

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, Rollup…), vous pouvez utiliser des /js/dist/*.jsfichiers compatibles UMD.

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. Notez également que tous les plugins dépendent de jQuery (cela signifie que jQuery doit être inclus avant les fichiers du plugin). Consultez notrepackage.json pour voir quelles versions de jQuery sont prises en charge.

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

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

Cependant, dans certaines situations, il peut être souhaitable de désactiver cette fonctionnalité. Pour désactiver l'API d'attribut de données, dissociez tous les événements sur l'espace de noms du document avec data-apicomme suit :

$(document).off('.data-api')

Alternativement, pour cibler un plugin spécifique, incluez simplement le nom du plugin en tant qu'espace de noms avec l'espace de noms data-api comme ceci :

$(document).off('.alert.data-api')

É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().

$('#myModal').on('show.bs.modal', function (event) {
  if (!data) {
    return event.preventDefault() // stops modal from being shown
  }
})

API programmatique

Nous pensons également que vous devriez pouvoir utiliser tous les plugins Bootstrap uniquement via l'API JavaScript. Toutes les API publiques sont des méthodes uniques et chaînées et renvoient la collection sur laquelle elles ont agi.

$('.btn.danger').button('toggle').addClass('fat')

Toutes les méthodes doivent accepter un objet d'options optionnel, une chaîne qui cible une méthode particulière, ou rien (qui lance un plugin avec un comportement par défaut) :

$('#myModal').modal() // initialized with defaults
$('#myModal').modal({ keyboard: false }) // initialized with no keyboard
$('#myModal').modal('show') // initializes and invokes show immediately

Chaque plugin expose également son constructeur brut sur une Constructorpropriété : $.fn.popover.Constructor. Si vous souhaitez obtenir une instance de plugin particulière, récupérez-la directement à partir d'un élément : $('[rel="popover"]').data('popover').

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.

$('#myCollapse').on('shown.bs.collapse', function (event) {
  // Action to execute once the collapsible area is expanded
})

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

$('#myCarousel').on('slid.bs.carousel', function (event) {
  $('#myCarousel').carousel('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})

$('#myCarousel').carousel('1') // Will start sliding to the slide 1 and returns to the caller
$('#myCarousel').carousel('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 plugin en modifiant l' Constructor.Defaultobjet du plugin :

// changes default for the modal plugin's `keyboard` option to false
$.fn.modal.Constructor.Default.keyboard = false

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.

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 jQuery de Bootstrap est accessible via la VERSIONpropriété du constructeur du plugin. Par exemple, pour le plugin tooltip :

$.fn.tooltip.Constructor.VERSION // => "4.6.2"

Pas de repli spécial lorsque JavaScript est désactivé

Les plugins de Bootstrap ne se replient pas particulièrement gracieusement 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.

Util

Tous les fichiers JavaScript de Bootstrap dépendent de util.jset doivent être inclus avec les autres fichiers JavaScript. Si vous utilisez le compiled (ou minified) bootstrap.js, il n'est pas nécessaire de l'inclure, il est déjà là.

util.jscomprend des fonctions utilitaires et une aide de base pour transitionEndles événements ainsi qu'un émulateur de transition CSS. Il est utilisé par les autres plugins pour vérifier la prise en charge des transitions CSS et pour détecter les transitions suspendues.

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 whiteListest la suivante :

var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var DefaultWhitelist = {
  // 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 whiteList, vous pouvez procéder comme suit :

var myDefaultWhiteList = $.fn.tooltip.Constructor.Default.whiteList

// To allow table elements
myDefaultWhiteList.table = []

// To allow td elements and data-option attributes on td elements
myDefaultWhiteList.td = ['data-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-]+/
myDefaultWhiteList['*'].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 :

$('#yourTooltip').tooltip({
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content)
  }
})