Przejdź do głównej zawartości Przejdź do nawigacji w dokumentach
in English

Narzędzie API

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

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 nulljest używany jako klucz mapy, nie jest kompilowany.
class Opcjonalny zero Nazwa wygenerowanej klasy. Jeśli nie podano i propertyjest tablicą ciągów, classdomyślnie zostanie użyty pierwszy element propertytablicy.
css-var Opcjonalny false Boolean do generowania zmiennych CSS zamiast reguł CSS.
local-vars Opcjonalny zero Mapa lokalnych zmiennych CSS do wygenerowania oprócz reguł CSS.
state Opcjonalny zero Lista wariantów pseudoklasy (np. :hoverlub :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; }

Narzędzia zmiennych CSS

Ustaw css-varopcję logiczną na, truea interfejs API wygeneruje lokalne zmienne CSS dla danego selektora zamiast zwykłych property: valuereguł. Rozważ nasze .text-opacity-*narzędzia:

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

Wyjście:

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

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/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 .