Utility API

API pripomočkov je orodje, ki temelji na Sassu, za ustvarjanje razredov pripomočkov.

Na tej strani

Pripomočki Bootstrap so ustvarjeni z našim API-jem za pripomočke in jih je mogoče uporabiti za spreminjanje ali razširitev našega privzetega nabora razredov pripomočkov prek Sass. Naš uporabniški API temelji na seriji zemljevidov in funkcij Sass za generiranje družin razredov z različnimi možnostmi. Če niste seznanjeni z zemljevidi Sass, preberite uradne dokumente Sass , da začnete.

Zemljevid $utilitiesvsebuje vse naše pripomočke in se pozneje združi z vašim $utilitieszemljevidom po meri, če je na voljo. Zemljevid pripomočkov vsebuje označen seznam skupin pripomočkov, ki sprejemajo naslednje možnosti:

Možnost	Vrsta	Privzeta vrednost	Opis
`property`	Obvezno	–	Ime lastnosti, to je lahko niz ali niz nizov (npr. vodoravni oblazinjeni robovi).
`values`	Obvezno	–	Seznam vrednosti ali zemljevid, če ne želite, da je ime razreda enako vrednosti. Če `null`se uporablja kot ključ zemljevida, `class`ni pred imenom razreda.
`class`	Neobvezno	nič	Ime ustvarjenega razreda. Če ni naveden in `property`je matrika nizov, `class`bo privzeto uporabljen prvi element `property`matrike. Če ni naveden in `property`je niz, se za imena `values`uporabljajo ključi .`class`
`css-var`	Neobvezno	`false`	Logična vrednost za generiranje spremenljivk CSS namesto pravil CSS.
`css-variable-name`	Neobvezno	nič	Ime brez predpone po meri za spremenljivko CSS znotraj nabora pravil.
`local-vars`	Neobvezno	nič	Zemljevid lokalnih spremenljivk CSS za ustvarjanje poleg pravil CSS.
`state`	Neobvezno	nič	Seznam različic psevdorazreda (npr. `:hover`ali `:focus`), ki jih je treba ustvariti.
`responsive`	Neobvezno	`false`	Logična vrednost, ki označuje, ali je treba ustvariti odzivne razrede.
`rfs`	Neobvezno	`false`	Logična vrednost za omogočanje tekočega spreminjanja velikosti z RFS .
`print`	Neobvezno	`false`	Logična vrednost, ki označuje, ali je treba ustvariti tiskalne razrede.
`rtl`	Neobvezno	`true`	Logična vrednost, ki označuje, ali naj se pripomoček hrani v RTL.

Razložen API

Vse uporabne spremenljivke so dodane $utilitiesspremenljivki v naši _utilities.scsstabeli slogov. Vsaka skupina pripomočkov izgleda nekako takole:

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

Kar izpiše naslednje:

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

Lastnina

Zahtevani propertyključ mora biti nastavljen za kateri koli pripomoček in mora vsebovati veljavno lastnost CSS. Ta lastnost se uporablja v ustvarjenem naboru pravil pripomočka. Ko je classključ izpuščen, služi tudi kot privzeto ime razreda. Razmislite o text-decorationpripomočku:

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

Izhod:

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

Vrednote

S valuesključem določite, katere vrednosti za podano propertynaj bodo uporabljene v ustvarjenih imenih razredov in pravilih. Lahko je seznam ali zemljevid (nastavljen v pripomočkih ali v spremenljivki Sass).

Kot seznam, kot pri text-decorationpripomočkih :

values: none underline line-through

Kot zemljevid, kot pri opacitypripomočkih :

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

Kot spremenljivka Sass, ki nastavi seznam ali zemljevid, kot v naših positionpripomočkih :

values: $position-values

Razred

Uporabite classmožnost za spremembo predpone razreda, uporabljene v prevedenem CSS. Če želite na primer spremeniti iz .opacity-*v .o-*:

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

Izhod:

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

Če class: null, ustvari razrede za vsakega od valuesključev:

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

Izhod:

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

Pripomočki za spremenljivke CSS

Nastavite css-varlogično možnost na truein API bo ustvaril lokalne spremenljivke CSS za dani izbirnik namesto običajnih property: valuepravil. Dodajte izbirno css-variable-name, da nastavite ime spremenljivke CSS, ki se razlikuje od imena razreda.

Razmislite o naših .text-opacity-*pripomočkih. Če dodamo css-variable-namemožnost, bomo dobili izhod po meri.

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

Izhod:

.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 spremenljivke CSS

Uporabite local-varsmožnost, da določite zemljevid Sass, ki bo ustvaril lokalne spremenljivke CSS znotraj nabora pravil razreda pripomočkov. Upoštevajte, da bo morda potrebno dodatno delo za uporabo teh lokalnih spremenljivk CSS v ustvarjenih pravilih CSS. Na primer, upoštevajte naše .bg-*pripomočke:

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

Izhod:

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

države

Uporabite statemožnost za ustvarjanje različic psevdorazreda. Primeri psevdorazredov so :hoverin :focus. Ko je naveden seznam stanj, se za ta psevdorazred ustvarijo imena razredov. Na primer, če želite spremeniti motnost pri premikanju miške, dodajte state: hoverin dobili boste .opacity-hover:hoversvoj prevedeni CSS.

Potrebujete več psevdorazredov? Uporabite s presledki ločen seznam stanj: state: hover focus.

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

Izhod:

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

Odzivna

Dodajte responsivelogično vrednost za ustvarjanje odzivnih pripomočkov (npr. .opacity-md-25) v vseh prelomnih točkah .

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

Izhod:

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

Tiskanje

Če omogočite printmožnost, boste ustvarili tudi razrede pripomočkov za tiskanje, ki se uporabljajo samo znotraj @media print { ... }medijske poizvedbe.

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

Izhod:

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

Pomembnost

Vsi pripomočki, ki jih ustvari API, vključujejo !important, da zagotovijo, da preglasijo komponente in razrede modifikatorjev, kot je predvideno. To nastavitev lahko globalno preklopite s $enable-important-utilitiesspremenljivko (privzeto na true).

Uporaba API-ja

Zdaj, ko ste seznanjeni s tem, kako deluje API za pripomočke, se naučite, kako dodati lastne razrede po meri in spremeniti naše privzete pripomočke.

Preglasi pripomočke

Preglasite obstoječe pripomočke z uporabo istega ključa. Na primer, če želite dodatne odzivne razrede pripomočkov za prelivanje, lahko naredite to:

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

Dodajte pripomočke

Nove pripomočke je mogoče dodati privzetemu $utilitieszemljevidu z map-merge. Prepričajte se, da so naše zahtevane datoteke Sass in _utilities.scssnajprej uvožene, nato uporabite map-mergeza dodajanje dodatnih pripomočkov. Tukaj je na primer, kako dodati odziven cursorpripomoček s tremi vrednostmi.

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

Spremenite pripomočke

Spremenite obstoječe pripomočke v privzetem $utilitieszemljevidu s funkcijami map-getin map-merge. widthV spodnjem primeru pripomočkom dodajamo dodatno vrednost . Začnite z začetnico map-mergein nato določite, kateri pripomoček želite spremeniti. Od tam pridobite ugnezdeni "width"zemljevid z map-getza dostop in spreminjanje možnosti in vrednosti pripomočka.

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

Omogoči odzivnost

Odzivne razrede lahko omogočite za obstoječi nabor pripomočkov, ki trenutno privzeto niso odzivni. Na primer, da bodo borderrazredi odzivni:

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

To bo zdaj ustvarilo odzivne različice .borderin .border-0za vsako prelomno točko. Vaš ustvarjen CSS bo videti takole:

.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 pripomočke

Manjkajo pripomočki v4 ali ste navajeni na drugo konvencijo poimenovanja? API za pripomočke lahko uporabite za preglasitev rezultatov classdanega pripomočka – na primer za preimenovanje .ms-*pripomočkov v 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";

Odstranite pripomočke

Odstranite vse privzete pripomočke s map-remove()funkcijo 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";

Uporabite lahko tudi map-merge()funkcijo Sass in nastavite tipko skupine na , nullda odstranite pripomoček.

@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, odstrani, spremeni

map-merge()S funkcijo Sass lahko dodate, odstranite in spremenite številne pripomočke hkrati . Tukaj je opisano, kako lahko prejšnje primere združite v en večji zemljevid.

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

Odstrani pripomoček v RTL

Nekateri robovi otežujejo oblikovanje RTL , na primer prelomi vrstic v arabščini. Tako lahko pripomočke izpustite iz izhoda RTL, tako da nastavite rtlmožnost na false:

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

Izhod:

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

To ne izpiše ničesar v RTL, zahvaljujoč nadzorni direktivi RTLCSSremove .