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	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, nie jest kompilowany.
`class`	Opcjonalny	Zmienna nazwy klasy, jeśli nie chcesz, aby była taka sama jak właściwość. W przypadku, gdy nie podasz `class`klucza, a `property`klucz jest tablicą ciągów, nazwa klasy będzie pierwszym elementem `property`tablicy.
`state`	Opcjonalny	Lista wariantów pseudoklas, takich jak `:hover`lub `:focus`do wygenerowania dla narzędzia. Brak wartości domyślnej.
`responsive`	Opcjonalny	Wartość logiczna wskazująca, czy należy wygenerować klasy responsywne. `false`domyślnie.
`rfs`	Opcjonalny	Wartość logiczna umożliwiająca ponowne skalowanie płynu. Zajrzyj na stronę RFS , aby dowiedzieć się, jak to działa. `false`domyślnie.
`print`	Opcjonalny	Wartość logiczna wskazująca, czy należy wygenerować klasy drukowania. `false`domyślnie.
`rtl`	Opcjonalny	Wartość logiczna wskazująca, czy narzędzie powinno być przechowywane w RTL. `true`domyślnie.

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

Niestandardowy prefiks klasy

Użyj classopcji zmiany prefiksu klasy używanego w skompilowanym CSS:

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

Wyjście:

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

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

Responsywne narzędzia

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

Zmiana narzędzi

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

Narzędzia do drukowania

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.

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

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

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

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

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

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

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

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

Usuń narzędzia

Usuń dowolne z domyślnych narzędzi, ustawiając klucz grupy na null. Na przykład, aby usunąć wszystkie nasze widthnarzędzia, utwórz $utilities map-mergei dodaj "width": nullwewnątrz.

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

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

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 .