Utility-API

Die Utility-API ist ein Sass-basiertes Tool zum Generieren von Utility-Klassen.

Auf dieser Seite

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	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. Wird `null`als Zuordnungsschlüssel verwendet, `class`wird er nicht dem Klassennamen vorangestellt.
`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. Wenn nicht angegeben und `property`eine Zeichenfolge ist, werden die `values`Schlüssel für die `class`Namen verwendet.
`css-var`	Optional	`false`	Boolean zum Generieren von CSS-Variablen anstelle von CSS-Regeln.
`css-variable-name`	Optional	Null	Benutzerdefinierter Name ohne Präfix für die CSS-Variable innerhalb des Regelsatzes.
`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 aktivieren .
`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 $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; }

Eigentum

Der erforderliche propertySchlü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 classSchlüssel weggelassen wird, dient er auch als Standardklassenname. Betrachten Sie den text-decorationNutzen:

$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 valuesSchlüssel, um anzugeben, welche Werte für die angegebenen propertyin 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-decorationDienstprogrammen :

values: none underline line-through

Als Karte, wie bei opacityVersorgungsunternehmen :

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

Als Sass-Variable, die die Liste oder Karte festlegt, wie in unseren positionDienstprogrammen :

values: $position-values

Klasse

Verwenden Sie die classOption, 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; }

Wenn class: null, generiert Klassen für jeden der valuesSchlüssel:

$utilities: (
  "visibility": (
    property: visibility,
    class: null,
    values: (
      visible: visible,
      invisible: hidden,
    )
  )
);

Ausgabe:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !important; }

Dienstprogramme für CSS-Variablen

Setzen Sie die css-varboolesche Option auf trueund die API generiert anstelle der üblichen property: valueRegeln lokale CSS-Variablen für den angegebenen Selektor. Fügen Sie optional hinzu css-variable-name, um einen anderen CSS-Variablennamen als den Klassennamen festzulegen.

Betrachten Sie unsere .text-opacity-*Dienstprogramme. Wenn wir die Option hinzufügen css-variable-name, erhalten wir eine benutzerdefinierte Ausgabe.

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

Ausgabe:

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

Lokale CSS-Variablen

Verwenden Sie die local-varsOption, 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 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; }

Reaktionsschnell

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

Drucken

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 ü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 $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/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

@import "bootstrap/scss/utilities/api";

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/maps";
@import "bootstrap/scss/mixins";
@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%),
        ),
      ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

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/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

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/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

Dienstprogramme entfernen

Entfernen Sie alle Standard-Dienstprogramme mit der map-remove()Sass-Funktion .

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

// Remove multiple utilities with a comma-separated list
$utilities: map-remove($utilities, "width", "float");

@import "bootstrap/scss/utilities/api";

Sie können auch die map-merge()Sass-Funktion verwenden und die Gruppentaste auf stellen null, um das Dienstprogramm zu entfernen.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

@import "bootstrap/scss/utilities/api";

Hinzufügen, entfernen, ändern

map-merge()Mit der Sass-Funktion können Sie viele Dienstprogramme auf einmal hinzufügen, entfernen und ändern . So können Sie die vorherigen Beispiele zu einer größeren Karte kombinieren.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    // Remove the `width` utility
    "width": null,

    // Make an existing utility responsive
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),

    // Add new utilities
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

@import "bootstrap/scss/utilities/api";

Dienstprogramm in RTL entfernen

Manche 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 .