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 $utilities carte contient tous nos utilitaires et est ensuite fusionnée avec votre $utilities carte 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	Type	DValeur par défaut	Description
`property`	Required	–	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`	Required	–	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`	Optional	null	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`	Optional	`false`	Booléen pour générer des variables CSS au lieu de règles CSS.
`local-vars`	Optional	null	Carte des variables CSS locales à générer en complément des règles CSS.
`state`	Optional	null	Liste des variantes de pseudo-classe (par exemple, `:hover` ou `:focus`) à générer.
`responsive`	Optional	`false`	Booléen indiquant si des classes responsives doivent être générées.
`rfs`	Optional	`false`	Booléen pour activer le redimensionnement fluide avec RFS.
`print`	Optional	`false`	Booléen indiquant si des classes d'impression doivent être générées.
`rtl`	Optional	`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 $utilities variable dans notre _utilities.scss feuille 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és

La property clé 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 class clé est omise, elle sert également de nom de classe par défaut. Considérez l' text-decoration utilité:

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

Sortir:

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

Valeurs

Utiliser la values clé pour spécifier quelles valeurs pour le spécifié property doivent ê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-decoration utilitaires:

values: none underline line-through

Sous forme de carte, comme avec les opacity utilitaires:

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 position utilitaires:

values: $position-values

Classer

Utiliser l' class option 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,
    )
  )
);

Sortir:

.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-var option booléenne sur true et l'API générera des variables CSS locales pour le sélecteur donné au lieu des property: value rè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
    )
  ),
);

Sortir:

.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-vars option 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
      )
    )
  )
);

Sortir:

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

Etats

Utiliser l' state option pour générer des variantes de pseudo-classe. Des exemples de pseudo-classes sont :hover et :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: hover et vous obtiendrez .opacity-hover:hover dans 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,
    )
  )
);

Sortir:

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

Responsive

Ajoutez le responsive boolé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,
    )
  )
);

Sortir:

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

Impression

L'activation de l' print option 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,
    )
  )
);

Sortir:

.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 !important pour 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-utilities variable (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 $utilities avec un fichier map-merge.Assurez-vous que nos fichiers Sass requis et _utilities.scss sont importés en premier, puis utilisez le map-merge pour ajouter vos utilitaires supplémentaires. Par exemple, voici comment ajouter un cursor utilitaire 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 $utilities carte par défaut avec les fonctions map-get et map-merge Dans l'exemple ci-dessous, nous ajoutons une valeur supplémentaire aux width utilitaires. 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-get pour 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 responsive

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 border classes 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 .border et .border-0 pour 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 class d'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 width utilitaires, créez un $utilities map-merge et ajoutez- le "width": null dedans.

@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' rtl option sur false:

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

Sortir:

/* 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 RTLCSS remove.

QZY.codes by quazerty

Bootstrap 5.2 | Utilitaires

API

API utilitaire

L'API expliquée

Propriétés

Valeurs

Classer

Utilitaires de variables CSS

Variables CSS locales

Etats

Responsive

Impression

Importance

Utilisation de l'API

Remplacer les utilitaires

Ajouter des utilitaires

Modifier les utilitaires

Activer responsive

Renommer les utilitaires

Supprimer les utilitaires

Supprimer l'utilitaire dans RTL