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	Valoare implicită	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ă, `class`nu este adăugat înaintea numelui clasei.
`class`	Opțional	nul	Numele clasei generate. Dacă nu este furnizat și `property`este o matrice de șiruri, `class`va fi implicit primul element al `property`matricei. Dacă nu este furnizat și `property`este un șir, `values`cheile sunt folosite pentru `class`nume.
`css-var`	Opțional	`false`	Boolean pentru a genera variabile CSS în loc de reguli CSS.
`css-variable-name`	Opțional	nul	Nume personalizat fără prefix pentru variabila CSS din setul de reguli.
`local-vars`	Opțional	nul	Hartă variabilelor CSS locale de generat în plus față de regulile CSS.
`state`	Opțional	nul	Lista de variante de pseudo-clasă (de exemplu, `:hover`sau `:focus`) de generat.
`responsive`	Opțional	`false`	Boolean care indică dacă ar trebui generate clase receptive.
`rfs`	Opțional	`false`	Boolean pentru a permite rescalarea fluidă cu RFS .
`print`	Opțional	`false`	Boolean care indică dacă trebuie generate clase de imprimare.
`rtl`	Opțional	`true`	Boolean care indică dacă utilitatea ar trebui să fie păstrată în RTL.

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

Proprietate

Cheia necesară propertytrebuie setată pentru orice utilitar și trebuie să conțină o proprietate CSS validă. Această proprietate este utilizată în setul de reguli al utilitarului generat. Când classcheia este omisă, servește și ca nume implicit de clasă. Luați în considerare text-decorationutilitatea:

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

Ieșire:

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

Valori

Utilizați valuescheia pentru a specifica ce valori pentru cele specificate propertyar trebui utilizate în numele și regulile de clasă generate. Poate fi o listă sau o hartă (setată în utilități sau într-o variabilă Sass).

Ca o listă, ca și cu text-decorationutilitățile :

values: none underline line-through

Ca o hartă, ca și cu opacityutilitățile :

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

Ca o variabilă Sass care setează lista sau harta, ca în positionutilitățile noastre :

values: $position-values

Clasă

Utilizați classopțiunea pentru a schimba prefixul de clasă folosit în CSS-ul compilat. De exemplu, pentru a schimba de la .opacity-*la .o-*:

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

Ieșire:

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

Dacă class: null, generează clase pentru fiecare dintre valueschei:

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

Ieșire:

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

Utilitare variabile CSS

Setați css-varopțiunea booleană la trueși API-ul va genera variabile CSS locale pentru selectorul dat în loc de property: valueregulile obișnuite. Adăugați o opțiune css-variable-namepentru a seta un alt nume de variabilă CSS decât numele clasei.

.text-opacity-*Luați în considerare utilitățile noastre . Dacă adăugăm css-variable-nameopțiunea, vom obține o ieșire personalizată.

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

Ieșire:

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

Variabile CSS locale

Utilizați local-varsopțiunea pentru a specifica o hartă Sass care va genera variabile CSS locale în setul de reguli al clasei de utilitate. Vă rugăm să rețineți că poate necesita muncă suplimentară pentru a consuma acele variabile CSS locale în regulile CSS generate. De exemplu, luați în considerare .bg-*utilitățile noastre:

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

Ieșire:

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

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

Receptiv

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

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.

Ignorați utilitățile

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

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

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

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/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ți utilitățile

Eliminați oricare dintre utilitarele implicite cu map-remove()funcția 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";

De asemenea, puteți utiliza map-merge()funcția Sass și puteți seta tasta de grup la nullpentru a elimina utilitarul.

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

Adăugați, eliminați, modificați

Puteți adăuga, elimina și modifica multe utilități simultan cu map-merge()funcția Sass . Iată cum puteți combina exemplele anterioare într-o hartă mai mare.

@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ț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 .