Preskočiť na hlavný obsah Preskočiť na navigáciu v dokumentoch
in English

Utility API

Pomocné API je nástroj založený na Sass na generovanie pomocných tried.

Pomôcky Bootstrap sa generujú pomocou nášho pomocného rozhrania API a možno ich použiť na úpravu alebo rozšírenie našej predvolenej sady pomocných tried cez Sass. Naše pomocné API je založené na sérii máp Sass a funkciách na generovanie rodín tried s rôznymi možnosťami. Ak nie ste oboznámení s mapami Sass, prečítajte si oficiálnu dokumentáciu Sass , aby ste mohli začať.

Mapa $utilitiesobsahuje všetky naše nástroje a neskôr sa zlúči s vašou vlastnou $utilitiesmapou, ak existuje. Mapa nástrojov obsahuje kľúčovaný zoznam skupín nástrojov, ktoré akceptujú nasledujúce možnosti:

Možnosť Typ Predvolená hodnota Popis
property Požadovaný Názov vlastnosti, môže to byť reťazec alebo pole reťazcov (napr. horizontálne vypchávky alebo okraje).
values Požadovaný Zoznam hodnôt alebo mapa, ak nechcete, aby bol názov triedy rovnaký ako hodnota. Ak nullsa používa ako kľúč mapy, nie je kompilovaný.
class Voliteľné nulový Názov vygenerovanej triedy. Ak nie je zadaný a propertyide o pole reťazcov, classpredvolene sa použije prvý prvok propertypoľa.
css-var Voliteľné false Boolean na generovanie premenných CSS namiesto pravidiel CSS.
local-vars Voliteľné nulový Mapa miestnych premenných CSS, ktoré sa majú generovať ako doplnok k pravidlám CSS.
state Voliteľné nulový Zoznam variantov pseudotried (napr. :hoveralebo :focus), ktoré sa majú vygenerovať.
responsive Voliteľné false Boolean označujúci, či sa majú generovať responzívne triedy.
rfs Voliteľné false Boolean na umožnenie zmeny mierky tekutiny pomocou RFS .
print Voliteľné false Boolean označujúci, či je potrebné vygenerovať triedy tlače.
rtl Voliteľné true Boolean označujúci, či by mal byť nástroj ponechaný v RTL.

API vysvetlené

Všetky premenné pomôcky sú pridané do $utilitiespremennej v rámci našej šablóny so _utilities.scssštýlmi. Každá skupina nástrojov vyzerá asi takto:

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

Z čoho vychádza nasledovné:

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

Nehnuteľnosť

Požadovaný propertykľúč musí byť nastavený pre akýkoľvek nástroj a musí obsahovať platnú vlastnosť CSS. Táto vlastnosť sa používa v sade pravidiel vygenerovanej pomôcky. Keď je classkľúč vynechaný, slúži aj ako predvolený názov triedy. Zvážte text-decorationužitočnosť:

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

Výkon:

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

hodnoty

Pomocou valueskľúča špecifikujte, ktoré hodnoty pre zadané propertyby sa mali použiť vo vygenerovaných názvoch tried a pravidlách. Môže to byť zoznam alebo mapa (nastavená v nástrojoch alebo v premennej Sass).

Ako zoznam, ako pri text-decorationpomôckach :

values: none underline line-through

Ako mapa, ako s opacitynástrojmi :

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

Ako premenná Sass, ktorá nastavuje zoznam alebo mapu, ako v našich positionnástrojoch :

values: $position-values

Trieda

Použite classmožnosť zmeniť predponu triedy použitú v kompilovanom CSS. Ak chcete napríklad zmeniť z .opacity-*na .o-*:

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

Výkon:

.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 premenné nástroje

Nastavte css-varboolovskú možnosť na truea API vygeneruje lokálne premenné CSS pre daný selektor namiesto zvyčajných property: valuepravidiel. Zvážte naše .text-opacity-*nástroje:

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

Výkon:

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

Lokálne premenné CSS

Použite túto local-varsmožnosť na zadanie mapy Sass, ktorá vygeneruje lokálne premenné CSS v rámci sady pravidiel pomocnej triedy. Upozorňujeme, že použitie týchto miestnych premenných CSS vo vygenerovaných pravidlách CSS môže vyžadovať ďalšiu prácu. Zvážte napríklad naše .bg-*nástroje:

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

Výkon:

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

štátov

Použite statemožnosť na generovanie variácií pseudotried. Príkladmi pseudotried sú :hovera :focus. Keď je poskytnutý zoznam stavov, vytvoria sa názvy tried pre danú pseudotriedu. Ak chcete napríklad zmeniť nepriehľadnosť pri umiestnení kurzora myši, pridajte state: hovera dostanete.opacity-hover:hover do kompilovaného CSS.

Potrebujete viacero pseudotried? Použite medzerami oddelený zoznam stavov: state: hover focus.

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

Výkon:

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

Responzívne

Pridajte responsiveboolean na generovanie responzívnych utilít (napr. .opacity-md-25) naprieč všetkými bodmi prerušenia .

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

Výkon:

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

Tlačiť

Povolenie tejto printmožnosti tiež vygeneruje pomocné triedy pre tlač, ktoré sa použijú iba v rámci @media print { ... }mediálneho dotazu.

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

Výkon:

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

Dôležitosť

Všetky pomocné programy generované rozhraním API zahŕňajú !important, aby sa zabezpečilo, že prepíšu komponenty a triedy modifikátorov, ako bolo zamýšľané. Toto nastavenie môžete globálne prepínať pomocou $enable-important-utilitiespremennej (predvolená hodnota je true).

Pomocou API

Teraz, keď ste oboznámení s tým, ako funguje rozhranie API nástrojov, zistite, ako pridať svoje vlastné triedy a upraviť naše predvolené nástroje.

Prepísať nástroje

Prepíšte existujúce pomocné programy použitím rovnakého kľúča. Napríklad, ak chcete ďalšie responzívne pomocné triedy pretečenia, môžete to urobiť takto:

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

Pridajte inžinierske siete

Nové nástroje možno pridať do predvolenej $utilitiesmapy pomocou súboru map-merge. Uistite sa, že naše požadované súbory Sass a _utilities.scsssú importované ako prvé, potom použite map-mergena pridanie ďalších nástrojov. Tu je napríklad postup, ako pridať responzívnu cursorpomôcku s tromi hodnotami.

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

Upravte pomôcky

Upravte existujúce nástroje v predvolenej $utilitiesmape pomocou funkcií map-geta map-merge. V nižšie uvedenom príklade pridávame widthpomocným programom ďalšiu hodnotu. Začnite s iniciálou map-mergea potom zadajte, ktorý nástroj chcete upraviť. Odtiaľ načítajte vnorenú "width"mapu pomocou , map-getaby ste získali prístup k možnostiam a hodnotám pomôcky a upravili ich.

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

Povoliť responzívne

Môžete povoliť responzívne triedy pre existujúcu množinu pomocných programov, ktoré momentálne predvolene nereagujú. Napríklad, aby boli bordertriedy responzívne:

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

Toto teraz vygeneruje responzívne variácie .bordera .border-0pre každý bod prerušenia. Váš vygenerovaný CSS bude vyzerať takto:

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

Premenujte nástroje

Chýbajú vám pomôcky verzie 4 alebo ste zvyknutí na inú konvenciu pomenovania? Rozhranie API pomocných programov možno použiť na prepísanie výsledku classdaného pomocného programu – napríklad na premenovanie .ms-*pomocných programov na staré .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 ),
    ),
  )
);

Odstráňte nástroje

Odstráňte všetky predvolené nástroje nastavením skupinového kľúča na null. Ak chcete napríklad odstrániť všetky naše widthnástroje, vytvorte a $utilities map-mergea pridajte "width": nulldo.

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

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

Odstrániť nástroj v RTL

Niektoré prípady okrajov sťažujú štýl RTL , napríklad zalomenie riadkov v arabčine. Pomôcky je teda možné vypustiť z výstupu RTL nastavením rtlmožnosti na false:

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

Výkon:

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

Toto nevypisuje nič v RTL vďaka riadiacej direktíve RTLCSSremove .