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

API utilitaire

L'API utilitaire est un outil basé sur Sass pour générer des classes utilitaires.

Sur cette page

Les utilitaires Bootstrap sont générés avec notre API utilitaire et peuvent être utilisés pour modifier ou étendre notre ensemble par défaut de classes utilitaires via Sass. Notre API utilitaire est basée sur une série de cartes et de fonctions Sass pour générer des familles de classes avec diverses options. Si vous n'êtes pas familier avec les cartes Sass, lisez les documents officiels Sass pour commencer.

La $utilitiescarte contient tous nos utilitaires et est ensuite fusionnée avec votre $utilitiescarte personnalisée, si elle est présente. La carte des services publics contient une liste à clé de groupes de services publics qui acceptent les options suivantes :

Option Taper La description
property Obligatoire Nom de la propriété, il peut s'agir d'une chaîne ou d'un tableau de chaînes (par exemple, remplissages horizontaux ou marges).
values Obligatoire Liste de valeurs ou carte si vous ne voulez pas que le nom de la classe soit identique à la valeur. Si nullest utilisé comme clé de carte, il n'est pas compilé.
class Optionnel Variable pour le nom de la classe si vous ne voulez pas qu'il soit identique à la propriété. Si vous ne fournissez pas la classclé et que la propertyclé est un tableau de chaînes, le nom de la classe sera le premier élément du propertytableau.
state Optionnel Liste des variantes de pseudo-classe comme :hoverou :focusà générer pour l'utilitaire. Pas de valeur par défaut.
responsive Optionnel Booléen indiquant si des classes réactives doivent être générées. falsepar défaut.
rfs Optionnel Booléen pour activer la mise à l'échelle du fluide. Consultez la page RFS pour savoir comment cela fonctionne. falsepar défaut.
print Optionnel Booléen indiquant si des classes d'impression doivent être générées. falsepar défaut.
rtl Optionnel Booléen indiquant si l'utilité doit être conservée en RTL. truepar défaut.

L'API expliquée

Toutes les variables utilitaires sont ajoutées à la $utilitiesvariable dans notre _utilities.scssfeuille de style. Chaque groupe d'utilitaires ressemble à ceci :

$utilities: (
  "opacity": (
    property: opacity,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
 );

Qui sort ce qui suit :

.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

Préfixe de classe personnalisé

Utilisez l' classoption pour changer le préfixe de classe utilisé dans le CSS compilé :

$utilities: (
  "opacity": (
    property: opacity,
    class: o,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
 );

Production:

.o-0 { opacity: 0; }
.o-25 { opacity: .25; }
.o-50 { opacity: .5; }
.o-75 { opacity: .75; }
.o-100 { opacity: 1; }

États

Utilisez l' stateoption pour générer des variantes de pseudo-classe. Des exemples de pseudo-classes sont :hoveret :focus. Lorsqu'une liste d'états est fournie, des noms de classe sont créés pour cette pseudo-classe. Par exemple, pour changer l'opacité au survol, ajoutez state: hoveret vous obtiendrez .opacity-hover:hoverdans votre CSS compilé.

Besoin de plusieurs pseudo-classes ? Utilisez une liste d'états séparés par des espaces : state: hover focus.

$utilities: (
  "opacity": (
    property: opacity,
    class: opacity,
    state: hover,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Production:

.opacity-0-hover:hover { opacity: 0 !important; }
.opacity-25-hover:hover { opacity: .25 !important; }
.opacity-50-hover:hover { opacity: .5 !important; }
.opacity-75-hover:hover { opacity: .75 !important; }
.opacity-100-hover:hover { opacity: 1 !important; }

Utilitaires réactifs

Ajoutez le responsivebooléen pour générer des utilitaires réactifs (par exemple, .opacity-md-25) sur tous les points d'arrêt .

$utilities: (
  "opacity": (
    property: opacity,
    responsive: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
 );

Production:

.opacity-0 { opacity: 0 !important; }
.opacity-25 { opacity: .25 !important; }
.opacity-50 { opacity: .5 !important; }
.opacity-75 { opacity: .75 !important; }
.opacity-100 { opacity: 1 !important; }

@media (min-width: 576px) {
  .opacity-sm-0 { opacity: 0 !important; }
  .opacity-sm-25 { opacity: .25 !important; }
  .opacity-sm-50 { opacity: .5 !important; }
  .opacity-sm-75 { opacity: .75 !important; }
  .opacity-sm-100 { opacity: 1 !important; }
}

@media (min-width: 768px) {
  .opacity-md-0 { opacity: 0 !important; }
  .opacity-md-25 { opacity: .25 !important; }
  .opacity-md-50 { opacity: .5 !important; }
  .opacity-md-75 { opacity: .75 !important; }
  .opacity-md-100 { opacity: 1 !important; }
}

@media (min-width: 992px) {
  .opacity-lg-0 { opacity: 0 !important; }
  .opacity-lg-25 { opacity: .25 !important; }
  .opacity-lg-50 { opacity: .5 !important; }
  .opacity-lg-75 { opacity: .75 !important; }
  .opacity-lg-100 { opacity: 1 !important; }
}

@media (min-width: 1200px) {
  .opacity-xl-0 { opacity: 0 !important; }
  .opacity-xl-25 { opacity: .25 !important; }
  .opacity-xl-50 { opacity: .5 !important; }
  .opacity-xl-75 { opacity: .75 !important; }
  .opacity-xl-100 { opacity: 1 !important; }
}

@media (min-width: 1400px) {
  .opacity-xxl-0 { opacity: 0 !important; }
  .opacity-xxl-25 { opacity: .25 !important; }
  .opacity-xxl-50 { opacity: .5 !important; }
  .opacity-xxl-75 { opacity: .75 !important; }
  .opacity-xxl-100 { opacity: 1 !important; }
}

Modification des utilitaires

Remplacez les utilitaires existants en utilisant la même clé. Par exemple, si vous souhaitez des classes d'utilitaires de débordement réactifs supplémentaires, vous pouvez procéder comme suit :

$utilities: (
  "overflow": (
    responsive: true,
    property: overflow,
    values: visible hidden scroll auto,
  ),
);

L'activation de l' printoption générera également des classes utilitaires pour l'impression, qui ne sont appliquées que dans la @media print { ... }requête multimédia.

$utilities: (
  "opacity": (
    property: opacity,
    print: true,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
 );

Production:

.opacity-0 { opacity: 0 !important; }
.opacity-25 { opacity: .25 !important; }
.opacity-50 { opacity: .5 !important; }
.opacity-75 { opacity: .75 !important; }
.opacity-100 { opacity: 1 !important; }

@media print {
  .opacity-print-0 { opacity: 0 !important; }
  .opacity-print-25 { opacity: .25 !important; }
  .opacity-print-50 { opacity: .5 !important; }
  .opacity-print-75 { opacity: .75 !important; }
  .opacity-print-100 { opacity: 1 !important; }
}

Importance

Tous les utilitaires générés par l'API incluent !importantpour s'assurer qu'ils remplacent les composants et les classes de modificateurs comme prévu. Vous pouvez basculer ce paramètre globalement avec la $enable-important-utilitiesvariable (par défaut à true).

Utilisation de l'API

Maintenant que vous savez comment fonctionne l'API des utilitaires, découvrez comment ajouter vos propres classes personnalisées et modifier nos utilitaires par défaut.

Ajouter des utilitaires

De nouveaux utilitaires peuvent être ajoutés à la carte par défaut $utilitiesavec un fichier map-merge. Assurez-vous que nos fichiers Sass requis et _utilities.scsssont importés en premier, puis utilisez le map-mergepour ajouter vos utilitaires supplémentaires. Par exemple, voici comment ajouter un cursorutilitaire réactif avec trois valeurs.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

Modifier les utilitaires

Modifiez les utilitaires existants dans la $utilitiescarte par défaut avec les fonctions map-getet map-merge. Dans l'exemple ci-dessous, nous ajoutons une valeur supplémentaire aux widthutilitaires. Commencez par une initiale map-merge, puis spécifiez l'utilitaire que vous souhaitez modifier. À partir de là, récupérez la carte imbriquée "width"avec map-getpour accéder et modifier les options et les valeurs de l'utilitaire.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": map-merge(
      map-get($utilities, "width"),
      (
        values: map-merge(
          map-get(map-get($utilities, "width"), "values"),
          (10: 10%),
        ),
      ),
    ),
  )
);

Activer réactif

Vous pouvez activer les classes réactives pour un ensemble existant d'utilitaires qui ne sont pas actuellement réactifs par défaut. Par exemple, pour rendre les borderclasses réactives :

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

Cela va maintenant générer des variations réactives de .borderet .border-0pour chaque point d'arrêt. Votre CSS généré ressemblera à ceci :

.border { ... }
.border-0 { ... }

@media (min-width: 576px) {
  .border-sm { ... }
  .border-sm-0 { ... }
}

@media (min-width: 768px) {
  .border-md { ... }
  .border-md-0 { ... }
}

@media (min-width: 992px) {
  .border-lg { ... }
  .border-lg-0 { ... }
}

@media (min-width: 1200px) {
  .border-xl { ... }
  .border-xl-0 { ... }
}

@media (min-width: 1400px) {
  .border-xxl { ... }
  .border-xxl-0 { ... }
}

Renommer les utilitaires

Utilitaires v4 manquants ou habitués à une autre convention de nommage ? L'API des utilitaires peut être utilisée pour remplacer le résultat classd'un utilitaire donné, par exemple, pour renommer .ms-*les utilitaires en oldish.ml-* :

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

Supprimer les utilitaires

Supprimez tous les utilitaires par défaut en définissant la clé de groupe sur null. Par exemple, pour supprimer tous nos widthutilitaires, créez un $utilities map-mergeet ajoutez- le "width": nulldans.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

Supprimer l'utilitaire dans RTL

Certains cas extrêmes rendent le style RTL difficile , comme les sauts de ligne en arabe. Ainsi, les utilitaires peuvent être supprimés de la sortie RTL en définissant l' rtloption surfalse :

$utilities: (
  "word-wrap": (
    property: word-wrap word-break,
    class: text,
    values: (break: break-word),
    rtl: false
  ),
);

Production:

/* rtl:begin:remove */
.text-break {
  word-wrap: break-word !important;
  word-break: break-word !important;
}
/* rtl:end:remove */

Cela ne produit rien en RTL, grâce à la directive de contrôle RTLCSSremove .