API d'utilitat

L'API d'utilitat és una eina basada en Sass per generar classes d'utilitat.

En aquesta pàgina

Les utilitats d'arrencada es generen amb la nostra API d'utilitats i es poden utilitzar per modificar o ampliar el nostre conjunt predeterminat de classes d'utilitats mitjançant Sass. La nostra API d'utilitat es basa en una sèrie de mapes i funcions Sass per generar famílies de classes amb diverses opcions. Si no esteu familiaritzat amb els mapes de Sass, llegiu els documents oficials de Sass per començar.

El $utilitiesmapa conté totes les nostres utilitats i després es fusiona amb el vostre $utilitiesmapa personalitzat, si n'hi ha. El mapa d'utilitats conté una llista amb claus de grups d'utilitats que accepten les opcions següents:

Opció	Tipus	Valor per defecte	Descripció
`property`	Obligatori	–	Nom de la propietat, pot ser una cadena o una matriu de cadenes (p. ex., farciments horitzontals o marges).
`values`	Obligatori	–	Llista de valors o un mapa si no voleu que el nom de la classe sigui el mateix que el valor. Si `null`s'utilitza com a clau de mapa, `class`no s'afegeix al nom de la classe.
`class`	Opcional	nul	Nom de la classe generada. Si no es proporciona i `property`és una matriu de cadenes, `class`serà per defecte el primer element de la `property`matriu. Si no es proporciona i `property`és una cadena, les `values`claus s'utilitzen per als `class`noms.
`css-var`	Opcional	`false`	Booleà per generar variables CSS en lloc de regles CSS.
`css-variable-name`	Opcional	nul	Nom personalitzat sense prefix per a la variable CSS dins del conjunt de regles.
`local-vars`	Opcional	nul	Mapa de variables CSS locals per generar a més de les regles CSS.
`state`	Opcional	nul	Llista de variants de pseudo-classe (p. ex., `:hover`o `:focus`) per generar.
`responsive`	Opcional	`false`	Booleà que indica si s'han de generar classes responsives.
`rfs`	Opcional	`false`	Booleà per habilitar el reescala de fluids amb RFS .
`print`	Opcional	`false`	Booleà que indica si cal generar classes d'impressió.
`rtl`	Opcional	`true`	Booleà que indica si la utilitat s'ha de mantenir a RTL.

API explicada

Totes les variables d'utilitat s'afegeixen a la $utilitiesvariable dins del nostre _utilities.scssfull d'estil. Cada grup d'utilitats té un aspecte semblant a això:

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

Que produeix el següent:

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

Propietat

La propertyclau necessària s'ha d'establir per a qualsevol utilitat i ha de contenir una propietat CSS vàlida. Aquesta propietat s'utilitza al conjunt de regles de la utilitat generada. Quan classs'omet la clau, també serveix com a nom de classe per defecte. Considereu la text-decorationutilitat:

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

Sortida:

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

Valors

Utilitzeu la valuesclau per especificar quins valors de l'especificat propertys'han d'utilitzar als noms i regles de classe generats. Pot ser una llista o un mapa (establert a les utilitats o en una variable de Sass).

Com a llista, com amb text-decorationles utilitats :

values: none underline line-through

Com a mapa, com amb opacityles utilitats :

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

Com a variable Sass que estableix la llista o el mapa, com a les nostres positionutilitats :

values: $position-values

Classe

Utilitzeu l' classopció per canviar el prefix de classe utilitzat al CSS compilat. Per exemple, per canviar de .opacity-*a .o-*:

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

Sortida:

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

Si class: null, genera classes per a cadascuna de les valuesclaus:

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

Sortida:

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

Utilitats variables CSS

Estableix l' css-varopció booleana truei l'API generarà variables CSS locals per al selector donat en lloc de les property: valueregles habituals. Afegiu un opcional css-variable-nameper establir un nom de variable CSS diferent del nom de la classe.

Considereu les nostres .text-opacity-*utilitats. Si afegim l' css-variable-nameopció, obtindrem una sortida personalitzada.

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

Sortida:

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

Variables CSS locals

Utilitzeu l' local-varsopció per especificar un mapa Sass que generarà variables CSS locals dins del conjunt de regles de la classe d'utilitat. Tingueu en compte que pot requerir treball addicional consumir aquestes variables CSS locals a les regles CSS generades. Per exemple, considereu les nostres .bg-*utilitats:

$utilities: (
  "background-color": (
    property: background-color,
    class: bg,
    local-vars: (
      "bg-opacity": 1
    ),
    values: map-merge(
      $utilities-bg-colors,
      (
        "transparent": transparent
      )
    )
  )
);

Sortida:

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

Estats

Utilitzeu l' stateopció per generar variacions de pseudo-classe. Les pseudoclasses d'exemple són :hoveri :focus. Quan es proporciona una llista d'estats, es creen noms de classe per a aquesta pseudo-classe. Per exemple, per canviar l'opacitat al passar el cursor, afegiu state: hover-lo i obtindreu .opacity-hover:hoverel vostre CSS compilat.

Necessites diverses pseudoclasses? Utilitzeu una llista d'estats separats per espais: state: hover focus.

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

Sortida:

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

Responent

Afegiu el responsivebooleà per generar utilitats sensibles (per exemple, .opacity-md-25) a tots els punts d'interrupció .

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

Sortida:

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

Imprimir

Si activeu l' printopció també es generaran classes d'utilitat per a la impressió, que només s'apliquen a la @media print { ... }consulta de mitjans.

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

Sortida:

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

Importància

Totes les utilitats generades per l'API inclouen !importantper assegurar-se que anul·len components i classes modificadores tal com es pretén. Podeu canviar aquesta configuració globalment amb la $enable-important-utilitiesvariable (per defecte és true).

Utilitzant l'API

Ara que ja coneixeu com funciona l'API d'utilitats, apreneu a afegir les vostres classes personalitzades i a modificar les nostres utilitats predeterminades.

Anul·lar utilitats

Substituïu les utilitats existents utilitzant la mateixa clau. Per exemple, si voleu classes d'utilitat de desbordament responsives addicionals, podeu fer això:

$utilities: (
  "overflow": (
    responsive: true,
    property: overflow,
    values: visible hidden scroll auto,
  ),
);

Afegeix utilitats

Es poden afegir noves utilitats al $utilitiesmapa predeterminat amb un map-merge. Assegureu-vos que els nostres fitxers Sass necessaris _utilities.scsss'importin primer i, a continuació, utilitzeu map-mergeper afegir les vostres utilitats addicionals. Per exemple, aquí s'explica com afegir una cursorutilitat sensible amb tres valors.

@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";

Modificar les utilitats

Modifiqueu les utilitats existents al $utilitiesmapa predeterminat amb map-geti map-mergefuncions. A l'exemple següent, estem afegint un valor addicional a les widthutilitats. Comenceu amb una inicial map-mergei després especifiqueu quina utilitat voleu modificar. A partir d'aquí, obteniu el mapa imbricat "width"amb map-getper accedir i modificar les opcions i els valors de la utilitat.

@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";

Activa la resposta

Podeu habilitar les classes responsives per a un conjunt existent d'utilitats que actualment no responen de manera predeterminada. Per exemple, per fer que les borderclasses responguin:

@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";

Això ara generarà variacions sensibles de .borderi .border-0per a cada punt d'interrupció. El vostre CSS generat tindrà aquest aspecte:

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

Canviar el nom de les utilitats

Falten les utilitats v4 o s'utilitzen amb una altra convenció de nomenclatura? L'API d'utilitats es pot utilitzar per anul·lar el resultat classd'una utilitat determinada, per exemple, per canviar el nom .ms-*de les utilitats a oldish .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";

Elimina les utilitats

Elimineu qualsevol de les utilitats predeterminades amb la map-remove()funció Sass .

@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";

També podeu utilitzar la map-merge()funció Sass i establir la clau de grup nullper eliminar la utilitat.

@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";

Afegir, eliminar, modificar

Podeu afegir, eliminar i modificar moltes utilitats alhora amb la map-merge()funció Sass . A continuació s'explica com podeu combinar els exemples anteriors en un mapa més gran.

@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";

Elimina la utilitat a RTL

Alguns casos extrems dificulten l'estil RTL , com ara els salts de línia en àrab. Així, les utilitats es poden eliminar de la sortida RTL establint l' rtlopció a false:

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

Sortida:

/* rtl:begin:remove */
.text-break {
  word-wrap: break-word !important;
  word-break: break-word !important;
}
/* rtl:end:remove */

Això no genera res a RTL, gràcies a la directiva de control RTLCSSremove .