Zum Hauptinhalt springen Zur Dokumentennavigation springen
in English

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 $utilitiesKarte enthält alle unsere Dienstprogramme und wird später mit Ihrer benutzerdefinierten $utilitiesKarte zusammengeführt, falls vorhanden. Die Versorgungskarte enthält eine Schlüsselliste von Versorgungsgruppen, die die folgenden Optionen akzeptieren:

Möglichkeit Typ 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 nullals Kartenschlüssel verwendet wird, wird er nicht kompiliert.
class Optional Variable für den Klassennamen, wenn Sie nicht möchten, dass er mit der Eigenschaft identisch ist. Falls Sie den Schlüssel nicht angeben classund der propertySchlüssel ein Array von Zeichenfolgen ist, ist der Klassenname das erste Element des propertyArrays.
state Optional Liste der Pseudoklassenvarianten wie :hoveroder :focus, die für das Dienstprogramm generiert werden sollen. Kein Standardwert.
responsive Optional Boolescher Wert, der angibt, ob responsive Klassen generiert werden müssen. falsestandardmäßig.
rfs Optional Boolean, um die Fluid-Neuskalierung zu aktivieren. Schauen Sie sich die RFS -Seite an, um herauszufinden, wie das funktioniert. falsestandardmäßig.
print Optional Boolescher Wert, der angibt, ob Druckklassen generiert werden müssen. falsestandardmäßig.
rtl Optional Boolescher Wert, der angibt, ob der Nutzen in RTL beibehalten werden soll. truestandardmäßig.

API erklärt

Alle Hilfsvariablen werden der $utilitiesVariable in unserem _utilities.scssStylesheet 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; }

Benutzerdefiniertes Klassenpräfix

Verwenden Sie die classOption, um das im kompilierten CSS verwendete Klassenpräfix zu ändern:

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

Ausgabe:

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

Zustände

Verwenden Sie die stateOption zum Generieren von Pseudo-Klassenvariationen. Beispiele für Pseudoklassen sind :hoverund :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: hoverund Sie erhalten .opacity-hover:hoverIhr 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; }

Reaktionsschnelle Dienstprogramme

Fügen Sie den responsivebooleschen Wert hinzu, um reaktionsschnelle Dienstprogramme (z. B. .opacity-md-25) über alle Haltepunkte 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; }
}

Dienstprogramme ändern

Ü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,
  ),
);

Durch Aktivieren der printOption werden auch Utility-Klassen für den Druck generiert, die nur innerhalb der @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-utilitiesVariablen umschalten (standardmäßig true).

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 hinzufügen

Neue Dienstprogramme können $utilitiesmit einer map-merge. Stellen Sie sicher, dass unsere erforderlichen Sass-Dateien und _utilities.scsszuerst importiert werden, und map-mergefügen Sie dann Ihre zusätzlichen Dienstprogramme hinzu. Hier erfahren Sie beispielsweise, wie Sie ein responsives cursorDienstprogramm 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 $utilitiesmit map-getund map-mergeFunktionen. Im folgenden Beispiel fügen wir den widthDienstprogrammen einen zusätzlichen Wert hinzu. Beginnen Sie mit einem Anfangsbuchstaben map-mergeund 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 borderKlassen 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 .borderund .border-0fü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 classeines bestimmten Hilfsprogramms zu überschreiben – zum Beispiel, um .ms-*Hilfsprogramme in oldish umzubenennen .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 ),
    ),
  )
);

Dienstprogramme entfernen

Entfernen Sie alle Standarddienstprogramme, indem Sie den Gruppenschlüssel auf setzen null. Um beispielsweise alle unsere widthDienstprogramme zu entfernen, erstellen Sie eine $utilities map-mergeund 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 rtlOption 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 .