Utility API

API-ul utilitar este un instrument bazat pe Sass pentru a genera clase de utilitate.

Pe aceasta pagina

Utilitarele Bootstrap sunt generate cu API-ul nostru de utilitate și pot fi folosite pentru a modifica sau extinde setul implicit de clase de utilitate prin Sass. API-ul nostru utilitar se bazează pe o serie de hărți și funcții Sass pentru generarea de familii de clase cu diferite opțiuni. Dacă nu sunteți familiarizat cu hărțile Sass, citiți documentele oficiale Sass pentru a începe.

Harta $utilitiesconține toate utilitățile noastre și este ulterior îmbinată cu $utilitiesharta dvs. personalizată, dacă este prezentă. Harta de utilități conține o listă cu chei de grupuri de utilități care acceptă următoarele opțiuni:

Opțiune	Tip	Descriere
`property`	Necesar	Numele proprietății, acesta poate fi un șir sau o matrice de șiruri (de exemplu, umplutură orizontală sau margini).
`values`	Necesar	Listă de valori sau o hartă dacă nu doriți ca numele clasei să fie același cu valoarea. Dacă `null`este folosit ca cheie de hartă, nu este compilat.
`class`	Opțional	Variabilă pentru numele clasei dacă nu doriți să fie același cu proprietatea. În cazul în care nu furnizați `class`cheia și `property`cheia este o matrice de șiruri de caractere, numele clasei va fi primul element al `property`matricei.
`state`	Opțional	Lista de variante de pseudo-clasă precum `:hover`sau `:focus`de generat pentru utilitar. Nicio valoare implicită.
`responsive`	Opțional	Boolean care indică dacă trebuie generate clase receptive. `false`în mod implicit.
`rfs`	Opțional	Boolean pentru a permite redimensionarea fluidului. Aruncă o privire la pagina RFS pentru a afla cum funcționează. `false`în mod implicit.
`print`	Opțional	Boolean care indică dacă trebuie generate clase de imprimare. `false`în mod implicit.
`rtl`	Opțional	Boolean care indică dacă utilitatea ar trebui să fie păstrată în RTL. `true`în mod implicit.

API explicat

Toate variabilele utilitare sunt adăugate $utilitiesvariabilei din foaia noastră de _utilities.scssstil. Fiecare grup de utilități arată cam așa:

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

Care scoate următoarele:

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

Prefix de clasă personalizat

Utilizați classopțiunea pentru a schimba prefixul de clasă folosit în CSS-ul compilat:

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

Ieșire:

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

state

Utilizați stateopțiunea pentru a genera variații de pseudo-clasă. Exemple de pseudoclase sunt :hoverși :focus. Când este furnizată o listă de stări, sunt create nume de clasă pentru acea pseudo-clasă. De exemplu, pentru a schimba opacitatea la trecerea cursorului, adăugați state: hoverși veți intra .opacity-hover:hoverîn CSS-ul dvs. compilat.

Aveți nevoie de mai multe pseudo-clase? Utilizați o listă de stări separate prin spațiu: state: hover focus.

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

Ieșire:

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

Utilități receptive

Adăugați valoarea responsivebooleană pentru a genera utilitare receptive (de exemplu, .opacity-md-25) în toate punctele de întrerupere .

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

Ieșire:

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

Schimbarea utilitatilor

Ignorați utilitățile existente utilizând aceeași cheie. De exemplu, dacă doriți clase suplimentare de utilitare responsive overflow, puteți face acest lucru:

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

Utilitare de imprimare

Activarea printopțiunii va genera, de asemenea , clase de utilitate pentru tipărire, care sunt aplicate numai în @media print { ... }interogarea media.

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

Ieșire:

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

Importanţă

Toate utilitarele generate de API includ !importantpentru a se asigura că suprascrie componentele și clasele modificatoare așa cum este prevăzut. Puteți comuta această setare la nivel global cu $enable-important-utilitiesvariabila (implicit la true).

Folosind API-ul

Acum că sunteți familiarizat cu modul în care funcționează API-ul utilitare, aflați cum să adăugați propriile clase personalizate și să modificați utilitățile noastre implicite.

Adăugați utilități

Noi utilitare pot fi adăugate la $utilitiesharta implicită cu un map-merge. Asigurați-vă că fișierele noastre Sass necesare și _utilities.scsssunt importate mai întâi, apoi utilizați map-mergepentru a adăuga utilitățile suplimentare. De exemplu, iată cum să adăugați un cursorutilitar receptiv cu trei valori.

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

Modificați utilitățile

Modificați utilitățile existente în $utilitiesharta implicită cu map-getși map-mergefuncții. În exemplul de mai jos, adăugăm o valoare suplimentară widthutilităților. Începeți cu o inițială map-mergeși apoi specificați utilitarul pe care doriți să îl modificați. De acolo, preluați "width"harta imbricată cu map-getpentru a accesa și modifica opțiunile și valorile utilitarului.

@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ți responsive

Puteți activa clasele receptive pentru un set existent de utilitare care nu sunt receptive în mod implicit. De exemplu, pentru a face borderclasele receptive:

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

Acest lucru va genera acum variații receptive ale .borderși .border-0pentru fiecare punct de întrerupere. CSS-ul dvs. generat va arăta astfel:

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

Redenumiți utilitățile

Lipsesc utilitare v4 sau sunt folosite cu o altă convenție de denumire? API-ul utilitare poate fi folosit pentru a suprascrie rezultatul classunui utilitar dat - de exemplu, pentru a redenumi .ms-*utilitățile în vechi .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ți utilitățile

Eliminați oricare dintre utilitarele implicite setând cheia de grup la null. De exemplu, pentru a elimina toate widthutilitățile noastre, creați un $utilities map-mergeși adăugați "width": nullîn interior.

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

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

Eliminați utilitarul din RTL

Unele cazuri de margine fac stilul RTL dificil , cum ar fi rupturile de linie în arabă. Astfel, utilitățile pot fi eliminate din ieșirea RTL setând rtlopțiunea la false:

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

Ieșire:

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

Acest lucru nu scoate nimic în RTL, datorită directivei de control RTLCSSremove .