Utility API

Nástroj API je nástroj založený na Sass na generovanie tried nástrojov.

Na tejto stránke

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 `null`sa používa ako kľúč mapy, `class`nepridáva sa pred názov triedy.
`class`	Voliteľné	nulový	Názov vygenerovanej triedy. Ak nie je zadaný a `property`ide o pole reťazcov, `class`predvolene sa použije prvý prvok `property`poľa. Ak nie je zadaný a `property`ide o reťazec, pre názvy `values`sa používajú kľúče .`class`
`css-var`	Voliteľné	`false`	Boolean na generovanie premenných CSS namiesto pravidiel CSS.
`css-variable-name`	Voliteľné	nulový	Vlastný názov bez predpony pre premennú CSS v sade pravidiel.
`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. `:hover`alebo `: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; }

If class: null, generuje triedy pre každý z valueskľúčov:

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

Výkon:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !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. Pridajte voliteľnú položku css-variable-namena nastavenie iného názvu premennej CSS, ako je názov triedy.

Zvážte naše .text-opacity-*služby. Ak túto možnosť pridáme css-variable-name, dostaneme vlastný výstup.

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

Výkon:

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

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 sa .opacity-hover:hoverdo 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/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";

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

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

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

Odstráňte nástroje

Odstráňte všetky predvolené nástroje pomocou funkcie map-remove()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";

Môžete tiež použiť funkciu map-merge()Sass a nastaviť skupinový kľúč na nullna odstránenie pomôcky.

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

Pridať, odstrániť, upraviť

map-merge()Pomocou funkcie Sass môžete naraz pridať, odstrániť a upraviť mnoho nástrojov . Takto môžete spojiť predchádzajúce príklady do jednej väčšej mapy.

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

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 .