Utility API

Uslužni API je alat baziran na Sass-u za generiranje uslužnih klasa.

Na ovoj stranici

Bootstrap uslužni programi se generiraju pomoću našeg uslužnog API-ja i mogu se koristiti za izmjenu ili proširenje našeg zadanog skupa uslužnih klasa putem Sass-a. Naš uslužni API je baziran na nizu Sass mapa i funkcija za generiranje porodica klasa sa različitim opcijama. Ako niste upoznati sa Sass mapama, pročitajte službene Sass dokumente da započnete.

Mapa sadrži sve naše uslužne programe i kasnije se $utilitiesspaja s vašom prilagođenom $utilitiesmapom, ako postoji. Mapa uslužnih programa sadrži ključnu listu grupa komunalnih usluga koje prihvataju sljedeće opcije:

Opcija	Tip	Zadana vrijednost	Opis
`property`	Obavezno	–	Ime svojstva, ovo može biti string ili niz stringova (npr. horizontalni dopuni ili margine).
`values`	Obavezno	–	Lista vrijednosti ili mapa ako ne želite da ime klase bude isto kao vrijednost. Ako `null`se koristi kao ključ mape, `class`ne stavlja se ispred imena klase.
`class`	Opciono	null	Ime generirane klase. Ako nije naveden i `property`predstavlja niz stringova, `class`podrazumevano će biti prvi element `property`niza. Ako nije naveden i `property`predstavlja niz, `values`ključevi se koriste za `class`imena.
`css-var`	Opciono	`false`	Boolean za generiranje CSS varijabli umjesto CSS pravila.
`css-variable-name`	Opciono	null	Prilagođeno ime bez prefiksa za CSS varijablu unutar skupa pravila.
`local-vars`	Opciono	null	Mapa lokalnih CSS varijabli za generiranje uz CSS pravila.
`state`	Opciono	null	Lista varijanti pseudoklasa (npr. `:hover`ili `:focus`) za generiranje.
`responsive`	Opciono	`false`	Boolean koji pokazuje da li treba generirati responzivne klase.
`rfs`	Opciono	`false`	Boolean za omogućavanje tečnosti ponovnog skaliranja sa RFS .
`print`	Opciono	`false`	Boolean označava da li je potrebno generirati klase ispisa.
`rtl`	Opciono	`true`	Boolean koji pokazuje da li uslužni program treba zadržati u RTL-u.

API objasnio

Sve uslužne varijable se dodaju $utilitiesvarijabli unutar našeg _utilities.scssstila. Svaka grupa uslužnih programa izgleda otprilike ovako:

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

Što daje sljedeće:

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

Nekretnina

Potrebni propertyključ mora biti postavljen za bilo koji uslužni program i mora sadržavati važeće CSS svojstvo. Ovo svojstvo se koristi u skupu pravila generiranog uslužnog programa. Kada je classključ izostavljen, on takođe služi kao podrazumevano ime klase. Razmotrite text-decorationuslužni program:

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

Izlaz:

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

Vrijednosti

Koristite valuesključ da odredite koje vrijednosti za navedene propertytreba koristiti u generiranim imenima klasa i pravilima. Može biti lista ili mapa (podešena u uslužnim programima ili u Sass varijabli).

Kao spisak, kao sa text-decorationuslužnim programima :

values: none underline line-through

Kao mapa, kao sa opacityuslužnim programima :

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

Kao Sass varijabla koja postavlja listu ili mapu, kao u našim positionuslužnim programima :

values: $position-values

Klasa

Koristite classopciju da promijenite prefiks klase koji se koristi u prevedenom CSS-u. Na primjer, da promijenite iz .opacity-*u .o-*:

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

Izlaz:

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

Ako class: null, generira klase za svaki od valuesključeva:

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

Izlaz:

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

CSS varijabilni uslužni programi

Postavite css-varbooleovu opciju na truei API će generirati lokalne CSS varijable za dati selektor umjesto uobičajenih property: valuepravila. Dodajte opcionalno css-variable-nameda postavite drugačije ime CSS varijable od naziva klase.

Uzmite u obzir naše .text-opacity-*komunalne usluge. Ako dodamo css-variable-nameopciju, dobićemo prilagođeni izlaz.

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

Izlaz:

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

Lokalne CSS varijable

Koristite local-varsopciju da navedete Sass mapu koja će generirati lokalne CSS varijable unutar skupa pravila uslužne klase. Imajte na umu da može biti potreban dodatni rad da se te lokalne CSS varijable koriste u generiranim CSS pravilima. Na primjer, razmotrite naše .bg-*komunalne usluge:

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

Izlaz:

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

države

Koristite stateopciju za generiranje varijacija pseudo-klase. Primjeri pseudoklasa su :hoveri :focus. Kada se pruži lista stanja, kreiraju se imena klasa za tu pseudo-klasu. Na primjer, da promijenite neprozirnost pri lebdenju, dodajte state: hoveri ući ćete .opacity-hover:hoveru svoj prevedeni CSS.

Trebate više pseudo-klasa? Koristite listu stanja razdvojenu razmakom: state: hover focus.

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

Izlaz:

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

Responsive

Dodajte responsiveboolean za generiranje odgovarajućih uslužnih programa (npr. .opacity-md-25) u svim tačkama prekida .

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

Izlaz:

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

Print

Omogućavanje printopcije će takođe generisati uslužne klase za štampanje, koje se primenjuju samo u okviru @media print { ... }upita za medije.

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

Izlaz:

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

Važnost

Svi uslužni programi koje generira API uključuju !importantkako bi se osiguralo da nadjačavaju komponente i klase modifikatora kako je predviđeno. Ovu postavku možete globalno promijeniti pomoću $enable-important-utilitiesvarijable (podrazumevano na true).

Korištenje API-ja

Sada kada ste upoznati s načinom na koji API uslužnih programa radi, naučite kako dodati vlastite prilagođene klase i modificirati naše zadane uslužne programe.

Nadjačajte uslužne programe

Zaobiđite postojeće uslužne programe koristeći isti ključ. Na primjer, ako želite dodatne responzivne uslužne klase za prelijevanje, možete učiniti ovo:

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

Dodajte uslužne programe

Novi uslužni programi se mogu dodati na zadanu $utilitieskartu sa map-merge. Provjerite _utilities.scssjesu li naše potrebne Sass datoteke i prvo uvezene, a zatim koristite map-mergeza dodavanje dodatnih uslužnih programa. Na primjer, evo kako dodati odgovarajući cursoruslužni program s tri vrijednosti.

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

Modificirajte uslužne programe

Izmijenite postojeće uslužne programe u zadanoj $utilitiesmapi sa map-geti map-mergefunkcijama. U donjem primjeru dodajemo dodatnu vrijednost widthuslužnim programima. Počnite s inicijalom map-merge, a zatim odredite koji uslužni program želite izmijeniti. Odatle dohvatite ugniježđenu "width"kartu pomoću map-getda biste pristupili i izmijenili opcije i vrijednosti uslužnog programa.

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

Omogući odgovor

Možete omogućiti responzivne klase za postojeći skup uslužnih programa koji trenutno ne reagiraju prema zadanim postavkama. Na primjer, da bi borderklase bile prilagodljive:

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

Ovo će sada generirati prilagodljive varijacije .borderi .border-0za svaku tačku prekida. Vaš generirani CSS će izgledati ovako:

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

Preimenujte uslužne programe

Nedostaju v4 uslužni programi ili ste navikli na drugu konvenciju imenovanja? API uslužnih programa može se koristiti za nadjačavanje rezultata classdatog uslužnog programa—na primjer, za preimenovanje .ms-*uslužnih programa u 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";

Uklonite uslužne programe

Uklonite bilo koji od zadanih uslužnih programa sa map-remove()funkcijom 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";

Također možete koristiti map-merge()Sass funkciju i postaviti grupni ključ na nullza uklanjanje uslužnog programa.

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

Dodajte, uklonite, izmijenite

Možete dodati, ukloniti i modificirati mnoge uslužne programe odjednom pomoću funkcije map-merge()Sass . Evo kako možete kombinirati prethodne primjere u jednu veću kartu.

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

Uklonite uslužni program u RTL-u

Neki rubni slučajevi otežavaju RTL stilizaciju , kao što su prijelomi linija na arapskom. Stoga se uslužni programi mogu izostaviti iz RTL izlaza postavljanjem rtlopcije na false:

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

Izlaz:

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

Ovo ne daje ništa u RTL-u, zahvaljujući RTLCSS removekontrolnoj direktivi .