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	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, no es compila.
`class`	Opcional	Variable per al nom de la classe si no voleu que sigui el mateix que la propietat. En cas que no proporcioneu la `class`clau i la `property`clau és una matriu de cadenes, el nom de la classe serà el primer element de la `property`matriu.
`state`	Opcional	Llista de variants de pseudo-classes com `:hover`o `:focus`per generar per a la utilitat. Cap valor predeterminat.
`responsive`	Opcional	Booleà que indica si cal generar classes responsives. `false`per defecte.
`rfs`	Opcional	Booleà per permetre el reescala de fluids. Fes una ullada a la pàgina RFS per saber com funciona això. `false`per defecte.
`print`	Opcional	Booleà que indica si cal generar classes d'impressió. `false`per defecte.
`rtl`	Opcional	Booleà que indica si la utilitat s'ha de mantenir a RTL. `true`per defecte.

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

Prefix de classe personalitzat

Utilitzeu l' classopció per canviar el prefix de classe utilitzat al CSS compilat:

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

Sortida:

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

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

Utilitats sensibles

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

Canvi d'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,
  ),
);

Utilitats d'impressió

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.

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/utilities";

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

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/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": map-merge(
      map-get($utilities, "width"),
      (
        values: map-merge(
          map-get(map-get($utilities, "width"), "values"),
          (10: 10%),
        ),
      ),
    ),
  )
);

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/utilities";

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

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/utilities";

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

Elimina les utilitats

Elimineu qualsevol de les utilitats predeterminades configurant la clau de grup a null. Per exemple, per eliminar totes les nostres widthutilitats, creeu un $utilities map-mergei afegiu-hi "width": null.

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

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

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 .