Utilīta API

Lietderības API ir uz Sass balstīts rīks utilītu klašu ģenerēšanai.

Šajā lapā

Bootstrap utilītas tiek ģenerētas, izmantojot mūsu utilīta API, un tās var izmantot, lai modificētu vai paplašinātu mūsu noklusējuma utilītu klašu kopu, izmantojot Sass. Mūsu utilīta API ir balstīta uz Sass karšu un funkciju sēriju, lai ģenerētu klašu saimes ar dažādām iespējām. Ja neesat pazīstams ar Sass kartēm, izlasiet oficiālos Sass dokumentus , lai sāktu darbu.

Kartē ir $utilitiesvisas mūsu utilītas, un tā vēlāk tiek apvienota ar jūsu pielāgoto $utilitieskarti, ja tāda ir. Lietderību karte satur atslēgtu utilītu grupu sarakstu, kas pieņem šādas opcijas:

Opcija	Tips	Noklusējuma vērtība	Apraksts
`property`	Obligāti	–	Rekvizīta nosaukums, tas var būt virkne vai virkņu masīvs (piemēram, horizontāli polsterējumi vai piemales).
`values`	Obligāti	–	Vērtību saraksts vai karte, ja nevēlaties, lai klases nosaukums būtu tāds pats kā vērtība. Ja `null`tiek izmantota kā kartes atslēga, tā netiek kompilēta.
`class`	Neobligāti	null	Ģenerētās klases nosaukums. Ja tas nav norādīts un `property`ir virkņu masīvs, `class`pēc noklusējuma tiks izmantots pirmais `property`masīva elements.
`css-var`	Neobligāti	`false`	Būla, lai ģenerētu CSS mainīgos CSS kārtulu vietā.
`local-vars`	Neobligāti	null	Vietējo CSS mainīgo karte, kas jāģenerē papildus CSS kārtulām.
`state`	Neobligāti	null	Ģenerējamo pseidoklases variantu saraksts (piemēram, `:hover`vai `:focus`).
`responsive`	Neobligāti	`false`	Būla vērtība, kas norāda, vai ir jāģenerē adaptīvās klases.
`rfs`	Neobligāti	`false`	Būla vērtība, lai iespējotu šķidruma mērogošanu ar RFS .
`print`	Neobligāti	`false`	Būla vērtība, kas norāda, vai ir jāģenerē drukas klases.
`rtl`	Neobligāti	`true`	Būla vērtība, kas norāda, vai lietderība ir jāsaglabā RTL.

API paskaidroja

Visi lietderības mainīgie tiek pievienoti $utilitiesmainīgajam mūsu _utilities.scssstila lapā. Katra utilītu grupa izskatās apmēram šādi:

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

Kas izvada sekojošo:

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

Īpašums

Nepieciešamā propertyatslēga ir jāiestata jebkurai utilītai, un tai ir jābūt derīgam CSS rekvizītam. Šis rekvizīts tiek izmantots ģenerētās utilītas kārtulu kopā. Ja classatslēga tiek izlaista, tā kalpo arī kā noklusējuma klases nosaukums. Apsveriet text-decorationlietderību:

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

Izvade:

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

Vērtības

Izmantojiet valuestaustiņu, lai norādītu, kuras norādītās vērtības propertyjāizmanto ģenerēto klašu nosaukumos un noteikumos. Var būt saraksts vai karte (iestatīts utilītprogrammās vai Sass mainīgajā).

Kā saraksts, tāpat kā ar text-decorationkomunālajiem pakalpojumiem :

values: none underline line-through

Kā karte, tāpat kā ar opacitykomunālajiem pakalpojumiem :

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

Kā Sass mainīgais, kas nosaka sarakstu vai karti, kā mūsu positionutilītprogrammās :

values: $position-values

Klase

Izmantojiet classopciju, lai mainītu apkopotajā CSS izmantoto klases prefiksu. Piemēram, lai mainītu no .opacity-*uz .o-*:

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

Izvade:

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

CSS mainīgo utilītas

Iestatiet css-varBūla opciju uz trueun API ģenerēs vietējos CSS mainīgos attiecīgajam atlasītājam parasto property: valuekārtulu vietā. Apsveriet mūsu .text-opacity-*pakalpojumus:

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

Izvade:

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

Vietējie CSS mainīgie

Izmantojiet local-varsopciju, lai norādītu Sass karti, kas ģenerēs vietējos CSS mainīgos lietderības klases kārtulu kopā. Lūdzu, ņemiet vērā, ka var būt nepieciešams papildu darbs, lai izmantotu šos vietējos CSS mainīgos ģenerētajos CSS kārtulos. Piemēram, apsveriet mūsu .bg-*pakalpojumus:

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

Izvade:

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

valstis

Izmantojiet stateopciju, lai ģenerētu pseidoklases variācijas. Pseidoklases ir :hoverun :focus. Kad tiek nodrošināts stāvokļu saraksts, šai pseidoklasei tiek izveidoti klašu nosaukumi. Piemēram, lai mainītu necaurredzamību, virzot kursoru, pievienojiet, state: hoverun jūs iegūsit .opacity-hover:hoversavā kompilētajā CSS.

Nepieciešamas vairākas pseidoklases? Izmantojiet ar atstarpi atdalītu stāvokļu sarakstu: state: hover focus.

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

Izvade:

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

Atsaucīgs

Pievienojiet responsiveBūla vērtību, lai ģenerētu adaptīvas utilītas (piemēram, .opacity-md-25) visos pārtraukuma punktos .

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

Izvade:

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

Drukāt

Iespējojot šo printopciju, drukāšanai tiks ģenerētas arī lietderības klases, kas tiek lietotas tikai @media print { ... }multivides vaicājumā.

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

Izvade:

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

Svarīgums

Visas API ģenerētās utilītprogrammas ietver !important, lai nodrošinātu, ka tās ignorē komponentus un modifikatoru klases, kā paredzēts. Varat pārslēgt šo iestatījumu globāli, izmantojot $enable-important-utilitiesmainīgo (pēc noklusējuma true).

Izmantojot API

Tagad, kad esat iepazinies ar utilītu API darbību, uzziniet, kā pievienot savas pielāgotās klases un modificēt mūsu noklusējuma utilītas.

Ignorēt utilītas

Ignorēt esošās utilītas, izmantojot to pašu taustiņu. Piemēram, ja vēlaties izmantot papildu adaptīvās pārpildes utilītas klases, varat rīkoties šādi:

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

Pievienojiet komunālos pakalpojumus

Jaunas utilītas var pievienot noklusējuma $utilitieskartei, izmantojot map-merge. Vispirms pārliecinieties, vai mūsu nepieciešamie Sass faili un _utilities.scssir importēti, pēc tam izmantojiet , map-mergelai pievienotu papildu utilītas. Piemēram, šeit ir norādīts, kā pievienot adaptīvu cursorutilītu ar trim vērtībām.

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

Modificēt utilītas

Mainiet esošās utilītas noklusējuma $utilitieskartē ar map-getun map-mergefunkcijām. Tālāk esošajā piemērā mēs pievienojam widthutilītprogrammām papildu vērtību. Sāciet ar iniciāli map-mergeun pēc tam norādiet, kuru utilītu vēlaties modificēt. No turienes paņemiet ligzdoto "width"karti, map-getlai piekļūtu un mainītu utilīta opcijas un vērtības.

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

Iespējot atsaucīgo

Varat iespējot adaptīvās klases esošai utilītu kopai, kas pašlaik pēc noklusējuma nereaģē. Piemēram, lai padarītu bordernodarbības atsaucīgas:

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

Tas tagad ģenerēs katra pārtraukuma punkta .borderun .border-0katra pārtraukuma punkta adaptīvas variācijas. Jūsu ģenerētais CSS izskatīsies šādi:

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

Pārdēvējiet utilītas

Vai trūkst v4 utilītu vai esat pieradis pie cita nosaukšanas principa? Utilītas API var izmantot, lai ignorētu classnoteiktas utilītas rezultātus, piemēram, lai pārdēvētu .ms-*utilītas uz 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 ),
    ),
  )
);

Noņemiet utilītas

Noņemiet jebkuru no noklusējuma utilītprogrammām, iestatot grupas taustiņu uz null. Piemēram, lai noņemtu visas mūsu widthutilītas, izveidojiet $utilities map-mergeun pievienojiet "width": null.

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

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

Noņemiet utilītu RTL

Daži malas korpusi apgrūtina RTL stilu , piemēram, līniju pārtraukumi arābu valodā. Tādējādi utilītas var izslēgt no RTL izejas, iestatot rtlopciju uz false:

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

Izvade:

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

Pateicoties RTLCSS removevadības direktīvai , tas RTL formātā neko neizvada .