Uslužni API

Utility API je alat temeljen na Sass-u za generiranje klasa uslužnih programa.

Na ovoj stranici

Bootstrap uslužni programi generiraju se s našim API-jem uslužnih programa i mogu se koristiti za izmjenu ili proširenje našeg zadanog skupa klasa uslužnih programa putem Sass-a. Naš uslužni API temelji se na nizu Sass mapa i funkcija za generiranje obitelji klasa s različitim opcijama. Ako niste upoznati sa Sass mapama, pročitajte službene Sass dokumente da biste započeli.

Karta $utilitiessadrži sve naše pomoćne programe i kasnije se spaja s vašom prilagođenom $utilitieskartom, ako postoji. Karta komunalnih usluga sadrži označeni popis grupa komunalnih usluga koje prihvaćaju sljedeće opcije:

Opcija	Tip	Zadana vrijednost	Opis
`property`	Potreban	–	Naziv svojstva, ovo može biti niz znakova ili niz znakova (npr. horizontalna ispuna ili margine).
`values`	Potreban	–	Popis vrijednosti ili mapa ako ne želite da naziv klase bude isti kao vrijednost. Ako `null`se koristi kao ključ karte, `class`ne dodaje se ispred naziva klase.
`class`	Neobavezno	ništavan	Naziv generirane klase. Ako nije navedeno i `property`niz je nizova, `class`zadano će biti prvi element `property`niza. Ako nisu navedeni i `property`predstavljaju niz, `values`ključevi se koriste za `class`imena.
`css-var`	Neobavezno	`false`	Booleov za generiranje CSS varijabli umjesto CSS pravila.
`css-variable-name`	Neobavezno	ništavan	Prilagođeno ime bez prefiksa za CSS varijablu unutar skupa pravila.
`local-vars`	Neobavezno	ništavan	Karta lokalnih CSS varijabli za generiranje uz CSS pravila.
`state`	Neobavezno	ništavan	Popis varijanti pseudoklase (npr. `:hover`ili `:focus`) za generiranje.
`responsive`	Neobavezno	`false`	Booleov pokazatelj treba li generirati odgovarajuće klase.
`rfs`	Neobavezno	`false`	Booleov za omogućavanje promjene veličine fluida s RFS -om .
`print`	Neobavezno	`false`	Booleov pokazatelj treba li generirati klase ispisa.
`rtl`	Neobavezno	`true`	Booleov pokazatelj treba li uslužni program biti zadržan u RTL-u.

API objašnjen

Sve korisne varijable dodaju se $utilitiesvarijabli unutar naše _utilities.scsstablice stilova. 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; }

Vlasništvo

Potreban propertyključ mora biti postavljen za bilo koji pomoćni program i mora sadržavati važeće CSS svojstvo. Ovo se svojstvo koristi u skupu pravila generiranog pomoćnog programa. Kada je classključ izostavljen, on također služi kao zadani naziv 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

Upotrijebite valuesključ da odredite koje vrijednosti za navedeno propertytreba koristiti u generiranim imenima klasa i pravilima. Može biti popis ili mapa (postavljena u pomoćnim programima ili u Sass varijabli).

Kao popis, poput text-decorationuslužnih programa :

values: none underline line-through

Kao karta, kao s opacityuslužnim programima :

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

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

values: $position-values

Klasa

Koristite classopciju za promjenu prefiksa klase koji se koristi u kompajliranom CSS-u. Na primjer, za promjenu 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; }

Pomoćni programi CSS varijabli

Postavite css-varBooleovu opciju na truei API će generirati lokalne CSS varijable za dani birač umjesto uobičajenih property: valuepravila. Dodajte opciju css-variable-nameza postavljanje različitog naziva CSS varijable od naziva klase.

Uzmite u obzir naše .text-opacity-*komunalije. Ako dodamo css-variable-nameopciju, dobit ć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

Upotrijebite local-varsopciju da navedete Sass mapu koja će generirati lokalne CSS varijable unutar skupa pravila klase pomoćnih programa. Imajte na umu da može biti potreban dodatni rad za korištenje tih lokalnih CSS varijabli u generiranim CSS pravilima. Na primjer, razmotrite naše .bg-*pomoćne programe:

$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 pseudo-klasa su :hoveri :focus. Kada se pruži popis stanja, stvaraju se nazivi klasa za tu pseudo-klasu. Na primjer, da promijenite neprozirnost pri lebdenju, dodajte state: hoveri dobit ćete .opacity-hover:hoversvoj kompilirani CSS.

Trebate više pseudo-klasa? Koristite popis stanja odvojen 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; }

Uzvratni

Dodajte responsiveBooleovu vrijednost za generiranje odgovarajućih uslužnih programa (npr., .opacity-md-25) preko svih prijelomnih točaka .

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

Ispis

Omogućavanje printopcije također će generirati klase korisnih programa za ispis, koje se primjenjuju samo unutar @media print { ... }medijskog upita.

$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 pomoć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 mijenjati pomoću $enable-important-utilitiesvarijable (zadano je true).

Korištenje API-ja

Sada kada ste upoznati s načinom rada API-ja pomoćnih programa, naučite kako dodati vlastite prilagođene klase i izmijeniti naše zadane pomoćne programe.

Nadjačaj pomoćne programe

Nadjačajte postojeće pomoćne programe korištenjem istog ključa. Na primjer, ako želite dodatne responzivne pomoćne klase preljeva, možete učiniti sljedeće:

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

Dodajte pomoćne programe

Novi pomoćni programi mogu se dodati zadanoj $utilitieskarti pomoću map-merge. Prvo provjerite jesu li naše potrebne Sass datoteke i _utilities.scssuvezene, a zatim upotrijebite map-mergeza dodavanje dodatnih uslužnih programa. Na primjer, evo kako dodati responzivni 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";

Izmijenite pomoćne programe

Izmijenite postojeće pomoćne programe u zadanoj $utilitieskarti s funkcijama map-geti map-merge. U donjem primjeru dodajemo dodatnu vrijednost widthuslužnim programima. Počnite s inicijalom map-merge, a zatim navedite koji uslužni program želite izmijeniti. Odatle dohvatite ugniježđenu "width"kartu map-getza pristup i izmjenu opcija 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 responzivno

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

@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 odgovarajuće varijacije .borderi .border-0za svaku prijelomnu točku. Vaš generirani CSS izgledat će 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 pomoćne programe

Nedostaju v4 pomoćni programi ili ste navikli na drugu konvenciju imenovanja? API uslužnih programa može se koristiti za nadjačavanje rezultata classdanog 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";

Ukloni pomoćne programe

Uklonite sve zadane pomoćne programe s 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()funkciju Sass 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";

Dodaj, ukloni, izmijeni

Možete dodavati, uklanjati i mijenjati mnoge pomoć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";

Ukloni uslužni program u RTL-u

Neka rubna kućišta otežavaju oblikovanje RTL- a, poput prijeloma redaka na arapskom. Stoga se pomoćni programi mogu ispustiti 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 ispisuje ništa u RTL-u, zahvaljujući RTLCSS removekontrolnoj direktivi .