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 izmantots kā kartes atslēga, `class`tas netiek pievienots klases nosaukumam.
`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. Ja tas nav norādīts un `property`ir virkne, nosaukumiem `values`tiek izmantoti taustiņi `class`.
`css-var`	Neobligāti	`false`	Būla, lai ģenerētu CSS mainīgos CSS kārtulu vietā.
`css-variable-name`	Neobligāti	null	Pielāgots nosaukums bez prefiksa CSS mainīgajam kārtulu kopā.
`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; }

Ja class: null, ģenerē klases katrai valuesatslēgai:

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

Izvade:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !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ā. Pievienojiet neobligātu css-variable-name, lai iestatītu CSS mainīgā nosaukumu, kas atšķiras no klases nosaukuma.

Apsveriet mūsu .text-opacity-*pakalpojumus. Ja pievienosim css-variable-nameopciju, mēs iegūsim pielāgotu izvadi.

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

Izvade:

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

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

Modify utilities

Modify existing utilities in the default $utilities map with map-get and map-merge functions. In the example below, we’re adding an additional value to the width utilities. Start with an initial map-merge and then specify which utility you want to modify. From there, fetch the nested "width" map with map-get to access and modify the utility’s options and values.

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

Enable responsive

You can enable responsive classes for an existing set of utilities that are not currently responsive by default. For example, to make the border classes responsive:

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

This will now generate responsive variations of .border and .border-0 for each breakpoint. Your generated CSS will look like this:

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

Rename utilities

Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting class of a given utility—for example, to rename .ms-* utilities to 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";

Remove utilities

Remove any of the default utilities with the map-remove() Sass function.

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

You can also use the map-merge() Sass function and set the group key to null to remove the utility.

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

Add, remove, modify

You can add, remove, and modify many utilities all at once with the map-merge() Sass function. Here’s how you can combine the previous examples into one larger map.

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

Remove utility in 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 .