Preskoči na glavno vsebino Preskoči na navigacijo po dokumentih
in English

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 nullse uporablja kot ključ zemljevida, se ne prevede.
class Neobvezno nič Ime ustvarjenega razreda. Če ni naveden in propertyje matrika nizov, classbo privzeto uporabljen prvi element propertymatrike.
css-var Neobvezno false Logična vrednost za generiranje spremenljivk CSS namesto pravil CSS.
local-vars Neobvezno nič Zemljevid lokalnih spremenljivk CSS za ustvarjanje poleg pravil CSS.
state Neobvezno nič Seznam različic psevdorazreda (npr. :hoverali :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; }

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. Razmislite o naših .text-opacity-*pripomočkih:

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

Izhod:

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

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

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

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

$utilities: map-merge(
  $utilities,
  (
    "width": map-merge(
      map-get($utilities, "width"),
      (
        values: map-merge(
          map-get(map-get($utilities, "width"), "values"),
          (10: 10%),
        ),
      ),
    ),
  )
);

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

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

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

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

Odstranite pripomočke

Odstranite katerega koli od privzetih pripomočkov tako, da nastavite ključ skupine na null. Na primer, če želite odstraniti vse naše widthpripomočke, ustvarite $utilities map-mergein dodajte "width": nullznotraj.

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

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

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 .