Přejít na hlavní obsah Přejít na navigaci v dokumentech
in English

Utility API

Utility API je nástroj založený na Sass pro generování tříd obslužných programů.

Obslužné programy Bootstrap jsou generovány pomocí našeho rozhraní API a lze je použít k úpravě nebo rozšíření naší výchozí sady tříd obslužných programů prostřednictvím Sass. Naše API nástroje je založeno na řadě map Sass a funkcích pro generování rodin tříd s různými možnostmi. Pokud nejste obeznámeni s mapami Sass, přečtěte si oficiální dokumenty Sass , abyste mohli začít.

Mapa $utilitiesobsahuje všechny naše nástroje a později se sloučí s vaší vlastní $utilitiesmapou, pokud existuje. Mapa nástrojů obsahuje klíčovaný seznam skupin nástrojů, které přijímají následující možnosti:

Volba Typ Výchozí hodnota Popis
property Požadované Název vlastnosti, může to být řetězec nebo pole řetězců (např. vodorovné odsazení nebo okraje).
values Požadované Seznam hodnot nebo mapa, pokud nechcete, aby byl název třídy stejný jako hodnota. Pokud nullje použit jako klíč mapy, není zkompilován.
class Volitelný nula Název generované třídy. Pokud není zadán a propertyjedná se o pole řetězců, classbude výchozí první prvek propertypole.
css-var Volitelný false Boolean pro generování proměnných CSS namísto pravidel CSS.
local-vars Volitelný nula Mapa místních proměnných CSS, které se mají generovat navíc k pravidlům CSS.
state Volitelný nula Seznam variant pseudotříd (např. :hovernebo :focus), které se mají vygenerovat.
responsive Volitelný false Boolean udávající, zda mají být generovány responzivní třídy.
rfs Volitelný false Boolean pro umožnění změny měřítka kapaliny pomocí RFS .
print Volitelný false Boolean označující, zda je třeba vygenerovat třídy tisku.
rtl Volitelný true Boolean označující, zda má být nástroj zachován v RTL.

Vysvětleno API

Všechny proměnné utility jsou přidány do $utilitiesproměnné v naší _utilities.scssšabloně stylů. Každá skupina nástrojů vypadá nějak takto:

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

Z čehož vychází následující:

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

Vlastnictví

Požadovaný propertyklíč musí být nastaven pro jakýkoli nástroj a musí obsahovat platnou vlastnost CSS. Tato vlastnost se používá v sadě pravidel generovaného nástroje. Když je classklíč vynechán, slouží také jako výchozí název třídy. Zvažte text-decorationužitečnost:

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

Výstup:

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

Hodnoty

Pomocí valuesklíče určete, které hodnoty pro zadanou hodnotu propertymají být použity ve vygenerovaných názvech tříd a pravidlech. Může to být seznam nebo mapa (nastavená v utilitách nebo v proměnné Sass).

Jako seznam, jako u text-decorationnástrojů :

values: none underline line-through

Jako mapa, jako u opacitynástrojů :

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

Jako proměnná Sass, která nastavuje seznam nebo mapu, jako v našich positionutilitách :

values: $position-values

Třída

Použijte classmožnost změnit předponu třídy použitou v kompilovaném CSS. Chcete-li například změnit z .opacity-*na .o-*:

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

Výstup:

.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 proměnné utility

Nastavte css-varmožnost boolean na a API místo obvyklých pravidel truevygeneruje místní proměnné CSS pro daný selektor . property: valueZvaž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ýstup:

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

Místní proměnné CSS

Použijte tuto local-varsmožnost k určení mapy Sass, která bude generovat místní proměnné CSS v rámci sady pravidel pomocné třídy. Vezměte prosím na vědomí, že využití těchto místních proměnných CSS ve vygenerovaných pravidlech CSS může vyžadovat další práci. Zvažte napří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ýstup:

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

států

Použijte statemožnost pro generování variací pseudotříd. Příkladem pseudotříd jsou :hovera :focus. Když je uveden seznam stavů, vytvoří se pro tuto pseudotřídu názvy tříd. Chcete-li například změnit neprůhlednost při najetí myší, přidejte state: hovera dostanete se .opacity-hover:hoverdo zkompilovaného CSS.

Potřebujete více pseudotříd? Použijte mezerami oddělený seznam stavů: state: hover focus.

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

Výstup:

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

Responzivní

Přidejte responsiveboolean a vygenerujte responzivní nástroje (např. .opacity-md-25) napříč všemi body přerušení .

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

Výstup:

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

Tisk

Povolením této printmožnosti se také vygenerují pomocné třídy pro tisk, které se použijí pouze v rámci @media print { ... }dotazu na média.

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

Výstup:

.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žitost

Všechny nástroje generované rozhraním API zahrnují !important, aby bylo zajištěno, že přepíší komponenty a třídy modifikátorů, jak bylo zamýšleno. Toto nastavení můžete globálně přepínat pomocí $enable-important-utilitiesproměnné (výchozí nastavení je true).

Pomocí API

Nyní, když jste obeznámeni s tím, jak funguje rozhraní API utilit, zjistěte, jak přidat své vlastní třídy a upravit naše výchozí nástroje.

Přepsat utility

Přepište stávající nástroje pomocí stejného klíče. Pokud například chcete další responzivní třídy obslužných programů přetečení, můžete to udělat takto:

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

Přidejte nástroje

Nové nástroje lze přidat do výchozí $utilitiesmapy pomocí přípony map-merge. Nejprve se ujistěte, že jsou naše požadované soubory Sass a _utilities.scssimportovány, a poté použijte map-mergek přidání dalších nástrojů. Zde je například uvedeno, jak přidat responzivní cursornástroj se třemi 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 nástroje

Upravte stávající nástroje ve výchozí $utilitiesmapě pomocí funkcí map-geta map-merge. V níže uvedeném příkladu přidáváme k widthutilitám další hodnotu. Začněte iniciálou map-mergea poté určete, který nástroj chcete upravit. Odtud načtěte vnořenou "width"mapu pomocí map-get, abyste získali přístup k možnostem a hodnotám nástroje a upravili je.

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

Povolit responzivní

Můžete povolit responzivní třídy pro existující sadu nástrojů, které aktuálně ve výchozím nastavení nereagují. Například, aby byly bordertřídy responzivní:

@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 nyní vygeneruje responzivní varianty .bordera .border-0pro každý bod přerušení. Váš vygenerovaný CSS bude vypadat 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 { ... }
}

Přejmenujte nástroje

Chybí vám nástroje v4 nebo jste zvyklí na jinou konvenci pojmenování? Rozhraní API utilit lze použít k přepsání výsledku classdaného obslužného programu – například k přejmenování .ms-*utilit 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 ),
    ),
  )
);

Odstraňte nástroje

Odeberte všechny výchozí nástroje nastavením skupinového klíče na null. Chcete-li například odebrat všechny naše widthnástroje, vytvořte $utilities map-mergea přidejte "width": nulldo.

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

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

Odebrat nástroj v RTL

Některé případy okrajů znesnadňují styling RTL , například zalomení řádků v arabštině. Nástroje lze tedy z výstupu RTL vypustit nastavením rtlmožnosti na false:

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

Výstup:

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

Díky řídicí direktivě RTLCSS seremove v RTL nic nevypisuje .