Narzędzie API

Narzędzie API to narzędzie oparte na Sass do generowania klas narzędzi.

Na tej stronie

Narzędzia Bootstrap są generowane za pomocą naszego narzędzia API i mogą być używane do modyfikowania lub rozszerzania naszego domyślnego zestawu klas narzędzi poprzez Sass. Nasze narzędzie API oparte jest na szeregu map i funkcji Sass do generowania rodzin klas z różnymi opcjami. Jeśli nie znasz map Sassa, zapoznaj się z oficjalnymi dokumentami Sassa , aby rozpocząć.

Mapa $utilitieszawiera wszystkie nasze narzędzia i jest później łączona z Twoją niestandardową $utilitiesmapą, jeśli jest dostępna. Mapa mediów zawiera kluczową listę grup mediów, które akceptują następujące opcje:

Opcja	Rodzaj	Domyślna wartość	Opis
`property`	Wymagany	–	Nazwa właściwości, może to być ciąg lub tablica ciągów (np. poziome dopełnienia lub marginesy).
`values`	Wymagany	–	Lista wartości lub mapa, jeśli nie chcesz, aby nazwa klasy była taka sama jak wartość. Jeśli `null`jest używany jako klucz mapy, `class`nie jest dołączany do nazwy klasy.
`class`	Opcjonalny	zero	Nazwa wygenerowanej klasy. Jeśli nie podano i `property`jest tablicą ciągów, `class`domyślnie zostanie użyty pierwszy element `property`tablicy. Jeśli nie podano i `property`jest ciągiem, `values`klucze są używane do `class`nazw.
`css-var`	Opcjonalny	`false`	Boolean do generowania zmiennych CSS zamiast reguł CSS.
`css-variable-name`	Opcjonalny	zero	Niestandardowa nazwa zmiennej CSS bez prefiksu w zestawie reguł.
`local-vars`	Opcjonalny	zero	Mapa lokalnych zmiennych CSS do wygenerowania oprócz reguł CSS.
`state`	Opcjonalny	zero	Lista wariantów pseudoklasy (np. `:hover`lub `:focus`) do wygenerowania.
`responsive`	Opcjonalny	`false`	Wartość logiczna wskazująca, czy należy generować klasy responsywne.
`rfs`	Opcjonalny	`false`	Wartość logiczna umożliwiająca ponowne skalowanie płynów za pomocą RFS .
`print`	Opcjonalny	`false`	Wartość logiczna wskazująca, czy należy wygenerować klasy drukowania.
`rtl`	Opcjonalny	`true`	Wartość logiczna wskazująca, czy narzędzie powinno być przechowywane w RTL.

Wyjaśnienie API

Wszystkie zmienne narzędzia są dodawane do $utilitieszmiennej w naszym _utilities.scssarkuszu stylów. Każda grupa narzędzi wygląda mniej więcej tak:

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

Co daje następujące dane:

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

Nieruchomość

Wymagany propertyklucz musi być ustawiony dla każdego narzędzia i musi zawierać prawidłową właściwość CSS. Ta właściwość jest używana w zestawie reguł wygenerowanego narzędzia. Gdy classklucz zostanie pominięty, służy również jako domyślna nazwa klasy. Rozważ text-decorationnarzędzie:

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

Wyjście:

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

Wartości

Użyj valuesklucza, aby określić, które wartości dla określonego propertypowinny być używane w generowanych nazwach klas i regułach. Może być listą lub mapą (ustawioną w narzędziach lub w zmiennej Sass).

Jako lista, podobnie jak w przypadku text-decorationnarzędzi :

values: none underline line-through

Jako mapa, podobnie jak w przypadku opacitymediów :

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

Jako zmienną Sass, która ustawia listę lub mapę, tak jak w naszych positionnarzędziach :

values: $position-values

Klasa

Użyj classopcji, aby zmienić prefiks klasy używany w skompilowanym CSS. Na przykład, aby zmienić z .opacity-*na .o-*:

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

Wyjście:

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

Jeśli class: null, generuje klasy dla każdego z valueskluczy:

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

Wyjście:

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

Narzędzia zmiennych CSS

Ustaw css-varopcję logiczną na, truea interfejs API wygeneruje lokalne zmienne CSS dla danego selektora zamiast zwykłych property: valuereguł. Dodaj opcjonalną, css-variable-nameaby ustawić inną nazwę zmiennej CSS niż nazwa klasy.

Rozważ nasze .text-opacity-*narzędzia. Jeśli dodamy css-variable-nameopcję, otrzymamy niestandardowe wyjście.

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

Wyjście:

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

Użyj local-varsopcji, aby określić mapę Sass, która będzie generować lokalne zmienne CSS w ramach zestawu reguł klasy narzędziowej. Pamiętaj, że wykorzystanie tych lokalnych zmiennych CSS w wygenerowanych regułach CSS może wymagać dodatkowej pracy. Rozważmy na przykład nasze .bg-*narzędzia:

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

Wyjście:

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

Stany

Użyj stateopcji generowania odmian pseudoklas. Przykładowe pseudoklasy to :hoveri :focus. Po podaniu listy stanów tworzone są nazwy klas dla tej pseudoklasy. Na przykład, aby zmienić krycie po najechaniu kursorem, dodaj, state: hovera otrzymasz .opacity-hover:hoverskompilowany CSS.

Potrzebujesz wielu pseudoklas? Użyj rozdzielonej spacjami listy stanów: state: hover focus.

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

Wyjście:

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

Czuły

Dodaj wartość responsivelogiczną, aby wygenerować responsywne narzędzia (np. .opacity-md-25) we wszystkich punktach przerwania .

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

Wyjście:

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

Wydrukować

Włączenie tej printopcji spowoduje również wygenerowanie klas narzędzi do drukowania, które są stosowane tylko w @media print { ... }zapytaniu o media.

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

Wyjście:

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

Znaczenie

Wszystkie narzędzia generowane przez API !importantzapewniają, że zastępują one komponenty i klasy modyfikatorów zgodnie z przeznaczeniem. Możesz przełączać to ustawienie globalnie za pomocą $enable-important-utilitieszmiennej (domyślnie true).

Korzystanie z API

Teraz, gdy już wiesz, jak działa interfejs API narzędzi, dowiedz się, jak dodawać własne niestandardowe klasy i modyfikować nasze domyślne narzędzia.

Narzędzia zastępcze

Zastąp istniejące narzędzia za pomocą tego samego klucza. Na przykład, jeśli potrzebujesz dodatkowych klas narzędziowych responsywnych przepełnień, możesz to zrobić:

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

Dodaj narzędzia

Nowe narzędzia można dodać do domyślnej $utilitiesmapy za pomocą map-merge. Upewnij się, że nasze wymagane pliki Sass i _utilities.scsszostały zaimportowane jako pierwsze, a następnie użyj , map-mergeaby dodać dodatkowe narzędzia. Na przykład, oto jak dodać responsywne cursornarzędzie z trzema wartościami.

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

Modyfikuj narzędzia

Zmodyfikuj istniejące narzędzia na domyślnej $utilitiesmapie za pomocą funkcji map-geti map-merge. W poniższym przykładzie dodajemy dodatkową wartość do widthnarzędzi. Zacznij od inicjału, map-mergea następnie określ, które narzędzie chcesz zmodyfikować. Stamtąd pobierz zagnieżdżoną "width"mapę za pomocą map-get, aby uzyskać dostęp i zmodyfikować opcje i wartości narzędzia.

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

Włącz responsywność

Możesz włączyć responsywne klasy dla istniejącego zestawu narzędzi, które obecnie domyślnie nie reagują. Na przykład, aby borderklasy były responsywne:

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

Spowoduje to teraz generowanie responsywnych odmian .borderi .border-0dla każdego punktu przerwania. Twój wygenerowany CSS będzie wyglądał tak:

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

Zmień nazwy narzędzi

Brakujące narzędzia v4 lub przyzwyczajone do innej konwencji nazewnictwa? Interfejs API narzędzi może zostać użyty do zastąpienia wyniku classdziałania danego narzędzia — na przykład do zmiany nazwy .ms-*narzędzi 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";

Usuń narzędzia

Usuń wszystkie domyślne narzędzia za pomocą map-remove()funkcji 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";

Możesz także użyć map-merge()funkcji Sass i ustawić klawisz grupy na, nullaby usunąć narzędzie.

@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, usuń, zmodyfikuj

map-merge()Dzięki funkcji Sass możesz dodawać, usuwać i modyfikować wiele narzędzi jednocześnie . Oto jak możesz połączyć poprzednie przykłady w jedną większą mapę.

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

Usuń narzędzie w RTL

Niektóre skrajne przypadki utrudniają stylizację RTL , na przykład łamanie linii w języku arabskim. W ten sposób narzędzia można usunąć z wyjścia RTL, ustawiając rtlopcję na false:

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

Wyjście:

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

To nie wyświetla niczego w RTL, dzięki dyrektywie sterującej RTLCSSremove .