API utilitaire
L'API utilitaire est un outil basé sur Sass pour générer des classes utilitaires.
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
.