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	Valeur par défaut	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 `null`est utilisé comme clé de carte, il n'est pas compilé.
`class`	Optionnel	nul	Nom de la classe générée. S'il n'est pas fourni et s'il `property`s'agit d'un tableau de chaînes, `class`la valeur par défaut sera le premier élément du `property`tableau.
`css-var`	Optionnel	`false`	Booléen pour générer des variables CSS au lieu de règles CSS.
`local-vars`	Optionnel	nul	Carte des variables CSS locales à générer en complément des règles CSS.
`state`	Optionnel	nul	Liste des variantes de pseudo-classe (par exemple, `:hover`ou `:focus`) à générer.
`responsive`	Optionnel	`false`	Booléen indiquant si des classes responsives doivent être générées.
`rfs`	Optionnel	`false`	Booléen pour activer le redimensionnement fluide avec RFS .
`print`	Optionnel	`false`	Booléen indiquant si des classes d'impression doivent être générées.
`rtl`	Optionnel	`true`	Booléen indiquant si l'utilité doit être conservée en RTL.

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; }

Propriété

La propertyclé requise doit être définie pour n'importe quel utilitaire et doit contenir une propriété CSS valide. Cette propriété est utilisée dans le jeu de règles de l'utilitaire généré. Lorsque la classclé est omise, elle sert également de nom de classe par défaut. Considérez l' text-decorationutilité:

$utilities: (
  "text-decoration": (
    property: text-decoration,
    values: none underline line-through
  )
);

Production:

.text-decoration-none { text-decoration: none !important; }
.text-decoration-underline { text-decoration: underline !important; }
.text-decoration-line-through { text-decoration: line-through !important; }

Valeurs

Utilisez la valuesclé pour spécifier quelles valeurs pour le spécifié propertydoivent être utilisées dans les noms de classe et les règles générés. Peut être une liste ou une carte (définie dans les utilitaires ou dans une variable Sass).

En liste, comme avec les text-decorationutilitaires :

values: none underline line-through

Sous forme de carte, comme avec les opacityutilitaires :

values: (
  0: 0,
  25: .25,
  50: .5,
  75: .75,
  100: 1,
)

En tant que variable Sass qui définit la liste ou la carte, comme dans nos positionutilitaires :

values: $position-values

Classer

Utilisez l' classoption pour changer le préfixe de classe utilisé dans le CSS compilé. Par exemple, pour passer de .opacity-*à .o-*:

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

Production:

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

Utilitaires de variables CSS

Définissez l' css-varoption booléenne sur trueet l'API générera des variables CSS locales pour le sélecteur donné au lieu des property: valuerègles habituelles. Considérez nos .text-opacity-*utilitaires :

$utilities: (
  "text-opacity": (
    css-var: true,
    class: text-opacity,
    values: (
      25: .25,
      50: .5,
      75: .75,
      100: 1
    )
  ),
);

Production:

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

Variables CSS locales

Utilisez l' local-varsoption pour spécifier une carte Sass qui générera des variables CSS locales dans l'ensemble de règles de la classe utilitaire. Veuillez noter que l'utilisation de ces variables CSS locales dans les règles CSS générées peut nécessiter un travail supplémentaire. Par exemple, considérons nos .bg-*utilitaires :

$utilities: (
  "background-color": (
    property: background-color,
    class: bg,
    local-vars: (
      "bg-opacity": 1
    ),
    values: map-merge(
      $utilities-bg-colors,
      (
        "transparent": transparent
      )
    )
  )
);

Production:

.bg-primary {
  --bs-bg-opacity: 1;
  background-color: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important;
}

É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; }

Sensible

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; }
}

Imprimer

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.

Remplacer les 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,
  ),
);

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 .