bootbox.js : Encapsulation des boîtes de dialogue Bootstrap pour une utilisation simplifiée

Site officiel en chinois : https://www.bootboxjs.cn/

Documentation officielle réorganisée pour référence personnelle

Inclusion dans HTML

Pour commencer, inclure les ressources nécessaires. Puisque Bootbox est une encapsulation de Bootstrap, l'ordre d'inclusion est important :

  1. jQuery (version minimale requise : 1.9.1)
  2. Popper.js (optionnel)
  3. Bootstrap (version actuelle 5, prend en charge Bootstrap 3 et 4)
  4. Bootbox
  5. Bootbox Locales (optionnel - à omettre si seul l'anglais est nécessaire)

Utilisation

Boîte de dialogue Alert

Une boîte de dialogue d'alerte simple avec un seul bouton. Appuyez sur ESC ou cliquez sur le bouton de fermeture pour fermer la boîte de dialogue.

Afficher un message qui peut contenir du texte HTML :

bootbox.alert("Votre message ici...");
bootbox.alert("Votre message <b>ici...</b>");

Ajouter un rappel (callback) :

bootbox.alert("Votre message ici...", function(){
    /* votre code de rappel */ 
});

Personnalisation détaillée via les options :

bootbox.alert({
    size: "small",
    title: "Votre Titre",
    message: "Votre message ici...",
    callback: function(){ /* fonction de rappel */ }
});

Boîte de dialogue Confirm

Une boîte de dialogue de confirmasion avec des boutons Annuler et Confirmer. Appuyez sur ESC ou cliquez sur Fermer() pour fermer la boîte de dialogue et appeler le rappel, comme si l'utilisateur avait cliqué sur "Annuler".

La boîte de dialogue de confirmation nécessite une fonction de rappel

Les modaux Bootstarp sont non-bloquants, contrairement aux boîtes de dialogue du BOM

Informations avec choix ok : le rappel reçoit true, fermeture : false

boiteConfirmation("Êtes-vous sûr?", function(resultat){
    /* votre code de rappel */ 
});

Autres options :

boiteConfirmation({ 
    size: "small",
    message: "Êtes-vous sûr?",
    callback: function(resultat){ /* resultat est un booléen; true = OK, false = Annuler */ }
});

Boîte de dialogue Prompt

Une boîte de dialogue demandant une saisie utilisateur. Appuyez sur ESC ou cliquez sur Fermer() pour fermer la boîte de dialogue et appeler le rappel, comme si l'utilisateur avait cliqué sur "Annuler".

Requiert Bootstrap 3.1.0 ou une version supérieure

La boîte de dialogue prompt nécessite une fonction de rappel

Informations avec champ de saisie : si annulé ou fermé, le rappel reçoit null, sinon le texte saisi

boiteInvite("Quel est votre nom?", function(resultat){
    /* votre code de rappel */ 
});

valeur : définit la valeur initiale du prompt. Pour présélectionner plusieurs valeurs (avec cases à cocher ou sélection multiple), utilisez un tableau comme option valeur. Par défaut null

typeSaisie : type de saisie. Options possibles : text, password, textarea, email, select, checkbox, radio, date, time, number, range

optionsSaisie : si select, checkbox, ou radio est spécifié comme type de saisie, un tableau de valeurs valide au format suivant doit être fourni

{
    texte: '',
    valeur: '',
    groupe: ''
}

Boîte de dialogue personnalisée Custom

Une méthode de boîte de dialogue entièrement personnalisable, prenant un seul paramètre : l'objet options.

Appuyer sur la touche ESC ne ferme pas automatiquement la boîte de dialogue personnalisée. Vous devez implémenter ce comportement vous-même avec l'option onEscape.

Le minimum requis pour créer une boîte de dialogue personnalisée est l'option message, qui crée une boîte de dialogue non fermable (comme une superposition "chargement").

boiteDialogue({ 
    message: '<div class="text-center"><i class="fa fa-spin fa-spinner"></i> Chargement...</div>', 
    boutonFermer: false 
});

Exemple d'utilisation complexe :

boiteDialogue({ 
    titre: 'Exemple de Dialogue Personnalisé',
    message: '<p>Cet dialogue démontre de nombreuses options disponibles lors de l\'utilisation de la bibliothèque Bootbox</p>',
    taille: 'large',
    onEscape: true,
    arrierePlan: true,
    boutons: {
        premier: {
            etiquette: 'Premier',
            classe: 'btn-primary',
            rappel: function(){
                              
            }
        },
        deuxieme: {
            etiquette: 'Deuxième',
            classe: 'btn-info',
            rappel: function(){
                              
            }
        },
        troisieme: {
            etiquette: 'Troisième',
            classe: 'btn-success',
            rappel: function(){
                              
            }
        },
        quatrieme: {
            etiquette: 'Quatrième',
            classe: 'btn-danger',
            rappel: function(){
                              
            }
        }
    }
});

Options de la boîte de dialogue

message

Type : String | Element

Détermine et personnalise le contenu obligatoire de la boîte de dialogue

Texte (ou balisage) affiché dans la boîte de dialogue.

titre

Type : String | Element

Ajoute un titre à la boîte de dialogue et place ce texte (ou balisage) dans un élément `

` ### rappel

Type : Function

Nécessaire pour les boîtes de dialogue de confirmation et de prompt

Le rappel d'alerte ne doit pas fournir d'arguments. Si c'est le cas, ils seront ignorés :

boiteAlerte({ 
    message: "Je suis une alerte!", 
    rappel: function() {
    } 
});

Les rappels de confirmation et de prompt doivent fournir un arguement pour le résultat. Pour une confirmation, ce sera une valeur true ou false, tandis que le résultat du prompt conservera la valeur saisie par l'utilisateur :

boiteConfirmation("Êtes-vous sûr?", function(resultat) {
    // resultat sera true ou false
}); 

boiteInvite("Quel est votre nom?", function(resultat) {
    if (resultat === null) {
        // Prompt annulé
    } else {
        // resultat a une valeur
    }
});

Pour tout rappel, si vous ne souhaitez pas que la boîte de dialogue se ferme lorsque le rappel est terminé, ajoutez return false; comme dernière ligne du rappel. Ensuite, vous devez utiliser modal() ou la fonction boiteMasquerTout() pour fermer manuellement la boîte de dialogue :

var dialogue = boiteInvite("Quel est votre nom?", function(resultat) {
    if (resultat === null) {
        // Prompt annulé
    } else {
        // resultat a une valeur
        dialogue.modal('masquer');
    } 

    return false;
});

onEscape

Type : Boolean | Function

Permet à l'utilisateur de fermer la boîte de dialogue en appuyant sur ESC, ce qui appellera cette fonction.

  • undefined, null : pas de fonction de rappel fournie
  • true : appuyer sur ESC ferme la boîte de dialogue
  • false : appuyer sur ESC ne ferme pas la boîte de dialogue

Valeur par défaut : true pour les alertes, confirmations et prompts ; null pour les boîtes de dialogue personnalisées.

afficher

Type : Boolean

La boîte de dialogue doit-elle être affichée immédiatement. Par défaut : true

arrierePlan

Type : Boolean

La boîte de dialogue doit-elle avoir un arrière-plan. Détermine également si un clic sur l'arrière-plan ferme le modal.

  • undefined, null : affiche l'arrière-plan, mais le clic est sans effet
  • true : affiche l'arrière-plan, clic ferme la boîte de dialogue
  • false : n'affiche pas l'arrière-plan

Par défaut : null

boutonFermer

Type : Boolean

La boîte de dialogue doit-elle avoir un bouton de fermeture

Par défaut : true

animer

Type : Boolean

Animer la boîte de dialogue (nécessite un navigateur prenant en charge les animations CSS).

Par défaut : true

classe

Type : String

Classes supplémentaires à appliquer au wrapper de la boîte de dialogue.

Par défaut : null

taille

Type : String

Ajoute les classes de taille de modal Bootstrap appropriées au wrapper de la boîte de dialogue.

Valeurs valides :

  • Petit : small, sm
  • Grand : large, lg
  • Très grand : extra-large, xl

Requiert Bootstrap 3.1.0 ou une version supérieure. Très grand nécessite Bootstrap 4.2.0 ou une version supérieure.

Par défaut : null

locale

Type : String

Définit la locale à utiliser pour chaque boîte de dialogue - cette option ne remplace pas la locale par défaut. Les autres boîtes de dialogue continueront à utiliser la locale par défaut.

La configuration de la locale est utilisée pour traduire les trois étiquettes de bouton standard : OK, CONFIRM, ANNULER

boutons

Type : Object

Les boutons sont définis comme un objet JavaScript. La définition minimale requise est :

"Votre texte de bouton": function() { }

Définition complète :

nomBouton : {
    etiquette: 'Votre texte de bouton',
    classe: 'une-classe',
    rappel: function() { }
}

Options :

  • alerte : ok
  • confirmation : annuler, confirmer
  • prompt : annuler, confirmer

Peut remplacer chaque option de bouton disponible pour utiliser un contenu et des styles CSS personnalisés :

boiteConfirmation({
    message: "Ceci est une confirmation avec du texte de bouton personnalisé et des couleurs ! Vous aimez ça ?",
    boutons: {
        confirmer: {
            etiquette: 'Oui',
            classe: 'btn-success'
        },
        annuler: {
            etiquette: 'Non',
            classe: 'btn-danger'
        }
    },
    rappel: function (resultat) {
        // ...
    }
});

Locales disponibles

Les locales sont utilisées pour fournir des traductions pour chaque bouton de commande intégré (OK, ANNULER et CONFIRMER).

Voici les locales disponibles (voir le tableau ci-dessous). Vous pouvez trouver chaque locale rendue sur la page "Exemples".

Clé Nom Clé Nom
ar Arabe az Azerbaïdjanais
bg\_BG Bulgare br Portugais-Brésil
cs Tchèque da Danois
de Allemand el Grec
en Anglais es Espagnol/Espagne
et Estonien eu Basque
fa Perse fi Finlandais
fr Français he Hébreu
hr Croate hu
id Indonésien it
ja ka Géorgien
ko Coréen lt Lituanien
lv nl Néerlandais
no Norvégien pl Polonais
pt Portugais ru Russe
sk Slovaque sl Slovène
sq Albanais sv Suédois
sw Souahéli ta Tamoul
th Thaï tr Turc
uk Ukrainien zh\_CN Chinois (République populaire de Chine)
zh\_TW Chinois (Taïwan)

Pour utiliser une locale autre que 'en', vous devez effectuer l'une des opérations suivantes :

  • Utiliser le fichier bootbox.all.js ou bootbox.all.min.js qui inclut toutes les locales
  • Ajouter une référence à bootbox.locales.js ou bootbox.locales.min.js après bootbox.js
  • Ajouter une référence au fichier de la locale cible (par exemple fr.js pour la locale française) dans le dossier src/locales
  • Utiliser la fonction ajouterLocale pour ajouter manuellement une locale

Utilisation des fonctions jQuery avec Bootbox

L'objet Bootbox retourné par chaque fonction de boîte de dialogue est un objet jQuery.

Ainsi, vous pouvez chaîner la plupart des fonctions jQuery au résultat d'une boîte de dialogue Bootbox.

Exemple de traitement de l'événement Bootstrap shown.bs.modal en utilisant .on() :

var dialogue = boiteDialogue({
    /* Vos options... */
});
              
dialogue.on('shown.bs.modal', function(e){
    // Faites quelque chose avec la boîte de dialogue juste après qu'elle ait été montrée à l'utilisateur...
});

Si vous définissez l'option afficher sur false, vous pouvez également utiliser la fonction Bootstrap modal() pour afficher et masquer manuellement la boîte de dialogue :

var dialogue = boiteDialogue({
    afficher: false,
    /* Vos options... */
});
              
dialogue.modal('afficher');
              
dialogue.modal('masquer');

Fonctions d'instance

boiteInit(function)

Permet de fournir une fonction à appeler lors de l'initialisation de la boîte de dialogue.

var dialogue = boiteDialogue({
    /* Vos options... */
});
              
dialogue.init(function(){
    // Faites quelque chose avec la boîte de dialogue...
});

init peut être appelé sur n'importe quelle fonction wrapper, car elles retournent toutes un objet Bootbox/jQuery

Fonctions globales

boiteDefauts(object **options**)

Cette méthode permet à l'utilisateur de définir de nombreuses options par défaut affichées dans les exemples de boîtes de dialogue.

Beaucoup de ces options s'appliquent également aux méthodes wrapper de base et peuvent être remplacées si la méthode wrapper est appelée avec un seul paramètre d'options :

boiteDefauts({
  /**
   * @optional String
   * @default: en
   * paramètres de locale à utiliser pour traduire les trois
   * étiquettes de bouton standard : OK, CONFIRMER, ANNULER
   */
  locale: "fr",
  
  /**
   * @optional Boolean
   * @default: true
   * si la boîte de dialogue doit être affichée immédiatement
   */
  afficher: true,
  
  /**
   * @optional Boolean
   * @default: true
   * si la boîte de dialogue doit avoir un arrière-plan ou non
   */
  arrierePlan: true,
  
  /**
   * @optional Boolean
   * @default: true
   * afficher un bouton de fermeture
   */
  boutonFermer: true,
  
  /**
   * @optional Boolean
   * @default: true
   * animer la boîte de dialogue en entrée et en sortie (non pris en charge dans < IE 10)
   */
  animer: true,
  
  /**
   * @optional String
   * @default: null
   * une classe supplémentaire à appliquer au wrapper de la boîte de dialogue
   */
  classe: "mon-modal"
  
});

boiteDefinirLocale(String nom)

Permet à l'utilisateur de sélectionner une locale au lieu d'utiliser boiteDefauts("locale", ...).

La configuration de la locale est utilisée pour traduire les trois étiquettes de bouton standard : OK, CONFIRMER, ANNULER

Par défaut : en

boiteAjouterLocale(String nom, object valeurs)

Permet à l'utilisateur d'ajouter des traductions personnalisées pour chaque bouton de commande intégré. L'objet valeurs doit être au format suivant :

{
    OK : '',
    ANNULER : '',
    CONFIRMER : ''
}

boiteSupprimerLocale(String nom)

Permet à l'utilisateur de supprimer une locale des paramètres de locale disponibles.

boiteLocales(String nom)

Permet à l'utilisateur d'obtenir un objet de locale à partir des paramètres de locale disponibles. Si nom est vide, toutes les locales seront retournées.

boiteMasquerTout()

Cache toutes les boîtes de dialogue Bootbox actuellement actives. Vous pouvez fermer individuellement les boîtes de dialogue Bootstrap normales comme suit :

dialogue.modal('masquer')

Limitations connues

Le code de la boîte de dialogue ne bloque pas l'exécution du code

Contrairement aux alertes, confirmations ou prompts natifs, tous les modals Bootstrap (et donc les modals Bootbox) sont asynchrones ; c'est-à-dire que les événements générés par Bootstrap sont des événements non bloquants. En raison de cette limitation, le code qui ne doit pas être évalué avant que l'utilisateur ne ferme la boîte de dialogue doit être appelé dans la fonction de rappel de la boîte de dialogue.

Pas de support pour plusieurs modals ouverts

Comme indiqué dans la documentation officielle de Bootstrap, il s'agit d'une limitation du plugin modal de Bootstrap. Bien qu'il soit fonctionnellement possible de déclencher plusieurs modals, un CSS et/ou un code JavaScript personnalisé sont nécessaires pour chaque couche de modal afin de les afficher correctement.

Valeur du prompt non nettoyée

La valeur retournée par le prompt Bootbox n'est pas nettoyée d'aucune manière.

Chaînes de contenu non nettoyées

Vous pouvez utiliser du texte brut ou du HTML pour toute option de Bootbox qui définit l'apparence d'affichage, telle que titre, message et étiquettes de bouton. Bootbox ne nettoie aucune de ces valeurs. Comme nous utilisons la fonction .html() de jQuery pour construire la boîte de dialogue, cela constitue un vecteur XSS potentiel. Le nettoyage du contenu est de votre responsabilité.

Étiquettes: bootbox.js Bootstrap modales dialogue jQuery

Publié le 24 juin à 02h21

Étiquettes Populaires

©2026 L'Atelier Monstre