Utility-API
Die Utility-API ist ein Sass-basiertes Tool zum Generieren von Utility-Klassen.
Bootstrap-Dienstprogramme werden mit unserer Dienstprogramm-API generiert und können verwendet werden, um unseren Standardsatz von Dienstprogrammklassen über Sass zu ändern oder zu erweitern. Unsere Utility-API basiert auf einer Reihe von Sass-Maps und -Funktionen zum Generieren von Klassenfamilien mit verschiedenen Optionen. Wenn Sie mit Sass-Karten nicht vertraut sind, lesen Sie die offiziellen Sass-Dokumente , um loszulegen.
Die $utilities
Karte enthält alle unsere Dienstprogramme und wird später mit Ihrer benutzerdefinierten $utilities
Karte zusammengeführt, falls vorhanden. Die Versorgungskarte enthält eine Schlüsselliste von Versorgungsgruppen, die die folgenden Optionen akzeptieren:
Möglichkeit | Typ | Standardwert | Beschreibung |
---|---|---|---|
property |
Erforderlich | – | Name der Eigenschaft, dies kann ein String oder ein Array von Strings sein (z. B. horizontale Paddings oder Ränder). |
values |
Erforderlich | – | Werteliste oder eine Zuordnung, wenn Sie nicht möchten, dass der Klassenname mit dem Wert identisch ist. Wenn null als Kartenschlüssel verwendet wird, wird er nicht kompiliert. |
class |
Optional | Null | Name der generierten Klasse. Wenn nicht angegeben und property es sich um ein Array von Zeichenfolgen handelt, class wird standardmäßig das erste Element des property Arrays verwendet. |
css-var |
Optional | false |
Boolean zum Generieren von CSS-Variablen anstelle von CSS-Regeln. |
local-vars |
Optional | Null | Karte lokaler CSS-Variablen, die zusätzlich zu den CSS-Regeln generiert werden sollen. |
state |
Optional | Null | Liste der zu generierenden Pseudo-Klassenvarianten (z. B. :hover oder ).:focus |
responsive |
Optional | false |
Boolescher Wert, der angibt, ob responsive Klassen generiert werden sollen. |
rfs |
Optional | false |
Boolean, um die Fluid-Neuskalierung mit RFS zu ermöglichen . |
print |
Optional | false |
Boolescher Wert, der angibt, ob Druckklassen generiert werden müssen. |
rtl |
Optional | true |
Boolescher Wert, der angibt, ob der Nutzen in RTL beibehalten werden soll. |
API erklärt
Alle Hilfsvariablen werden der $utilities
Variable in unserem _utilities.scss
Stylesheet hinzugefügt. Jede Gruppe von Dienstprogrammen sieht etwa so aus:
$utilities: (
"opacity": (
property: opacity,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Was folgendes ausgibt:
.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }
Eigentum
Der erforderliche property
Schlüssel muss für jedes Dienstprogramm festgelegt werden und eine gültige CSS-Eigenschaft enthalten. Diese Eigenschaft wird im Regelsatz des generierten Dienstprogramms verwendet. Wenn der class
Schlüssel weggelassen wird, dient er auch als Standardklassenname. Betrachten Sie den text-decoration
Nutzen:
$utilities: (
"text-decoration": (
property: text-decoration,
values: none underline line-through
)
);
Ausgabe:
.text-decoration-none { text-decoration: none !important; }
.text-decoration-underline { text-decoration: underline !important; }
.text-decoration-line-through { text-decoration: line-through !important; }
Werte
Verwenden Sie den values
Schlüssel, um anzugeben, welche Werte für die angegebenen property
in den generierten Klassennamen und Regeln verwendet werden sollen. Kann eine Liste oder Karte sein (in den Dienstprogrammen oder in einer Sass-Variablen festgelegt).
Als Liste, wie bei text-decoration
Dienstprogrammen :
values: none underline line-through
Als Karte, wie bei opacity
Versorgungsunternehmen :
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
Als Sass-Variable, die die Liste oder Karte festlegt, wie in unseren position
Dienstprogrammen :
values: $position-values
Klasse
Verwenden Sie die class
Option, um das im kompilierten CSS verwendete Klassenpräfix zu ändern. Zum Beispiel, um von .opacity-*
nach zu wechseln .o-*
:
$utilities: (
"opacity": (
property: opacity,
class: o,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Ausgabe:
.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; }
Dienstprogramme für CSS-Variablen
Setzen Sie die css-var
boolesche Option auf true
und die API generiert anstelle der üblichen property: value
Regeln lokale CSS-Variablen für den angegebenen Selektor. Betrachten Sie unsere .text-opacity-*
Dienstprogramme:
$utilities: (
"text-opacity": (
css-var: true,
class: text-opacity,
values: (
25: .25,
50: .5,
75: .75,
100: 1
)
),
);
Ausgabe:
.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; }
Lokale CSS-Variablen
Verwenden Sie die local-vars
Option, um eine Sass-Zuordnung anzugeben, die lokale CSS-Variablen innerhalb des Regelsatzes der Hilfsklasse generiert. Bitte beachten Sie, dass möglicherweise zusätzliche Arbeit erforderlich ist, um diese lokalen CSS-Variablen in den generierten CSS-Regeln zu verwenden. Betrachten Sie zum Beispiel unsere .bg-*
Dienstprogramme:
$utilities: (
"background-color": (
property: background-color,
class: bg,
local-vars: (
"bg-opacity": 1
),
values: map-merge(
$utilities-bg-colors,
(
"transparent": transparent
)
)
)
);
Ausgabe:
.bg-primary {
--bs-bg-opacity: 1;
background-color: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important;
}
Zustände
Verwenden Sie die state
Option zum Generieren von Pseudo-Klassenvariationen. Beispiele für Pseudoklassen sind:hover
und :focus
. Wenn eine Liste von Zuständen bereitgestellt wird, werden Klassennamen für diese Pseudoklasse erstellt. Um beispielsweise die Deckkraft beim Hover zu ändern, fügen Sie hinzu state: hover
und Sie erhalten .opacity-hover:hover
Ihr kompiliertes CSS.
Benötigen Sie mehrere Pseudoklassen? Verwenden Sie eine durch Leerzeichen getrennte Liste von Zuständen: state: hover focus
.
$utilities: (
"opacity": (
property: opacity,
class: opacity,
state: hover,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Ausgabe:
.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; }
Reaktionsschnell
Fügen Sie den responsive
booleschen Wert hinzu, um responsive Dienstprogramme (z. B. .opacity-md-25
) über alle Breakpoints hinweg zu generieren hinweg zu generieren .
$utilities: (
"opacity": (
property: opacity,
responsive: true,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Ausgabe:
.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; }
}
Durch Aktivieren der print
Option werden auch Utility-Klassen für den Druck generiert, die nur innerhalb von angewendet werden@media print { ... }
Medienabfrage angewendet werden.
$utilities: (
"opacity": (
property: opacity,
print: true,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Ausgabe:
.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; }
}
Bedeutung
Alle von der API generierten Dienstprogramme enthalten !important
, um sicherzustellen, dass sie Komponenten und Modifikatorklassen wie beabsichtigt überschreiben. Sie können diese Einstellung global mit der $enable-important-utilities
Variablen umschalten (standardmäßigtrue
).
Verwenden der API
Nachdem Sie nun mit der Funktionsweise der Utilities-API vertraut sind, erfahren Sie, wie Sie Ihre eigenen benutzerdefinierten Klassen hinzufügen und unsere Standard-Utilities ändern.
Dienstprogramme überschreiben
Überschreiben Sie vorhandene Dienstprogramme mit derselben Taste. Wenn Sie beispielsweise zusätzliche responsive Overflow-Hilfsklassen wünschen, können Sie Folgendes tun:
$utilities: (
"overflow": (
responsive: true,
property: overflow,
values: visible hidden scroll auto,
),
);
Dienstprogramme hinzufügen
Neue Dienstprogramme können $utilities
mit einer map-merge
. Stellen Sie sicher, dass unsere erforderlichen Sass-Dateien und _utilities.scss
zuerst importiert werden, und map-merge
fügen Sie dann Ihre zusätzlichen Dienstprogramme hinzu. Hier erfahren Sie beispielsweise, wie Sie ein responsives cursor
Dienstprogramm mit drei Werten hinzufügen.
@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,
)
)
);
Dienstprogramme ändern
Ändern Sie vorhandene Dienstprogramme in der Standardzuordnung $utilities
mit map-get
und map-merge
Funktionen. Im folgenden Beispiel fügen wir den width
Dienstprogrammen einen zusätzlichen Wert hinzu. Beginnen Sie mit einem Anfangsbuchstaben map-merge
und geben Sie dann an, welches Dienstprogramm Sie ändern möchten. Rufen Sie von dort aus die verschachtelte "width"
Karte mit ab map-get
, um auf die Optionen und Werte des Dienstprogramms zuzugreifen und diese zu ändern.
@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%),
),
),
),
)
);
Responsiv aktivieren
Sie können reaktionsschnelle Klassen für einen vorhandenen Satz von Dienstprogrammen aktivieren, die derzeit standardmäßig nicht reaktionsfähig sind. Um beispielsweise die border
Klassen reaktionsfähig zu machen:
@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 ),
),
)
);
Dadurch werden nun ansprechende Variationen von .border
und .border-0
für jeden Haltepunkt generiert. Ihr generiertes CSS sieht folgendermaßen aus:
.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 { ... }
}
Dienstprogramme umbenennen
Fehlende v4-Dienstprogramme oder an eine andere Namenskonvention gewöhnt? Die Hilfsprogramm-API kann verwendet werden, um das Ergebnis class
eines bestimmten Hilfsprogramms zu überschreiben – zum Beispiel, um .ms-*
Hilfsprogramme in altmodisch umzubenennen.ml-*
umzubenennen :
@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 ),
),
)
);
Dienstprogramme entfernen
Entfernen Sie alle Standarddienstprogramme, indem Sie den Gruppenschlüssel auf setzen null
. Um beispielsweise alle unsere width
Dienstprogramme zu entfernen, erstellen Sie eine $utilities
map-merge
und fügen Sie sie hinzu "width": null
.
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";
$utilities: map-merge(
$utilities,
(
"width": null
)
);
Dienstprogramm in RTL entfernen
Einige Grenzfälle erschweren das RTL-Styling , etwa Zeilenumbrüche auf Arabisch. Daher können Dienstprogramme aus der RTL-Ausgabe gelöscht werden, indem die rtl
Option auf gesetzt wird false
:
$utilities: (
"word-wrap": (
property: word-wrap word-break,
class: text,
values: (break: break-word),
rtl: false
),
);
Ausgabe:
/* rtl:begin:remove */
.text-break {
word-wrap: break-word !important;
word-break: break-word !important;
}
/* rtl:end:remove */
Dies gibt dank der RTLCSS remove
-Steuerungsanweisung nichts in RTL aus .