Utility API

Услужниот API е алатка заснована на Sass за генерирање на класи на алатки.

На оваа страница

Услужните програми за Bootstrap се генерираат со нашето API за услужни програми и може да се користат за менување или проширување на нашиот стандарден сет на класи на алатки преку Sass. Нашето корисно API се заснова на серија Sass мапи и функции за генерирање семејства на класи со различни опции. Ако не сте запознаени со мапите на Sass, прочитајте ги официјалните документи на Sass за да започнете.

Картата $utilitiesги содржи сите наши алатки и подоцна се спојува со вашата приспособена $utilitiesкарта, доколку е присутна. Мапата на комуналните услуги содржи клучена листа на групи на алатки кои ги прифаќаат следните опции:

Опција	Тип	Стандардна вредност	Опис
`property`	Задолжително	-	Име на имотот, ова може да биде низа или низа жици (на пр. хоризонтални облоги или маргини).
`values`	Задолжително	-	Список на вредности или мапа ако не сакате името на класата да биде исто со вредноста. Ако `null`се користи како клуч за мапа, `class`не е прикачен на името на класата.
`class`	Изборен	нула	Име на генерирана класа. Ако не е обезбедено и `property`е низа од низи, `class`стандардно ќе биде првиот елемент од `property`низата. Ако не е обезбедено и `property`е низа, `values`копчињата се користат за `class`имињата.
`css-var`	Изборен	`false`	Булова за генерирање на CSS променливи наместо CSS правила.
`css-variable-name`	Изборен	нула	Приспособено име без префикс за променливата CSS во множеството правила.
`local-vars`	Изборен	нула	Карта на локални CSS променливи за генерирање покрај правилата на CSS.
`state`	Изборен	нула	Список на варијанти на псевдо-класа (на пример, `:hover`или `:focus`) за генерирање.
`responsive`	Изборен	`false`	Булова покажува дали треба да се генерираат одговорни класи.
`rfs`	Изборен	`false`	Булова за да се овозможи рескалирање на течноста со RFS .
`print`	Изборен	`false`	Булова покажува дали треба да се генерираат класи за печатење.
`rtl`	Изборен	`true`	Булова покажува дали алатката треба да се чува во RTL.

Објаснето API

Сите корисни променливи се додаваат на $utilitiesпроменливата во нашиот лист со _utilities.scssстилови. Секоја група на комунални услуги изгледа вака:

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

Која го дава следново:

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

Имотот

Потребниот propertyклуч мора да биде поставен за која било алатка и мора да содржи валидно CSS својство. Ова својство се користи во множеството правила на генерираната алатка. Кога classклучот е испуштен, тој служи и како стандардно име на класата. Размислете за text-decorationалатката:

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

Излез:

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

Вредности

Користете го valuesклучот за да одредите кои вредности за наведеното propertyтреба да се користат во генерираните имиња и правила на класите. Може да биде листа или мапа (поставена во комуналните услуги или во променливата Sass).

Како листа, како со text-decorationкомуналните услуги :

values: none underline line-through

Како мапа, како кај opacityкомуналните услуги :

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

Како променлива Sass што ја поставува листата или мапата, како во нашите positionкомунални услуги :

values: $position-values

Класа

Користете ја classопцијата за промена на префиксот на класата што се користи во компајлираниот CSS. На пример, за промена од .opacity-*во .o-*:

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

Излез:

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

Ако class: null, генерира класи за секое од valuesклучевите:

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

Излез:

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

CSS променливи комунални услуги

Поставете ја css-varопцијата boolean на trueи API ќе генерира локални CSS променливи за дадениот избирач наместо вообичаените property: valueправила. Додадете опционално css-variable-nameза да поставите различно име на променлива CSS од името на класата.

Размислете за нашите .text-opacity-*комунални услуги. Ако ја додадеме css-variable-nameопцијата, ќе добиеме прилагоден излез.

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

Излез:

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

Локални CSS променливи

Користете ја local-varsопцијата за да наведете карта Sass која ќе генерира локални CSS променливи во рамките на множеството правила на класата за помошни услуги. Имајте предвид дека може да бара дополнителна работа за да се потрошат тие локални CSS променливи во генерираните правила на CSS. На пример, разгледајте ги нашите .bg-*комунални услуги:

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

Излез:

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

држави

Користете ја stateопцијата за генерирање варијации на псевдо-класа. Пример псевдо-класи се :hoverи :focus. Кога се обезбедува список на состојби, се креираат имиња на класи за таа псевдо-класа. На пример, за да ја промените непроѕирноста при лебдењето, додајте state: hoverи ќе влезете .opacity-hover:hoverво вашата компајлирана CSS.

Ви требаат повеќе псевдо-класи? Користете листа на состојби одвоена со простор: state: hover focus.

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

Излез:

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

Одговорен

Додајте го responsiveбулот за да генерирате одговорни алатки (на пример, .opacity-md-25) низ сите точки на прекин .

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

Излез:

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

Печати

Овозможувањето на printопцијата ќе генерира и корисни класи за печатење, кои се применуваат само во рамките на @media print { ... }барањето за медиуми.

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

Излез:

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

Важност

Сите алатки генерирани од API вклучуваат !importantза да се осигури дека ги надминуваат компонентите и класите на модификатори како што е наменето. Можете да ја префрлите оваа поставка глобално со $enable-important-utilitiesпроменливата (стандардно на true).

Користење на API

Сега кога сте запознаени со тоа како функционира API-то на услужните програми, научете како да додавате свои сопствени класи и да ги менувате нашите стандардни алатки.

Отфрли ги комуналните услуги

Отфрлете ги постоечките комунални услуги со користење на истиот клуч. На пример, ако сакате дополнителни респонзивни услужни класи за прелевање, можете да го направите ова:

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

Додадете комунални услуги

Новите алатки може да се додадат на стандардната $utilitiesмапа со map-merge. Проверете дали нашите потребни датотеки Sass _utilities.scssсе прво увезени, а потоа користете го за map-mergeда ги додадете вашите дополнителни алатки. На пример, еве како да додадете одговорна cursorалатка со три вредности.

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

Изменете ги комуналните услуги

Изменете ги постоечките алатки во стандардната $utilitiesмапа со map-getи map-mergeфункции. Во примерот подолу, додаваме дополнителна вредност на widthкомуналните услуги. Започнете со почетна map-mergeи потоа наведете која алатка сакате да ја измените. Оттаму, преземете ја вгнездената "width"карта со map-getза да пристапите и да ги измените опциите и вредностите на алатката.

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

Овозможи одговор

Можете да овозможите одговорни класи за постоечки сет на услужни програми кои во моментов не одговараат стандардно. На пример, за да ги направите borderкласите одговорни:

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

Ова сега ќе генерира одговорни варијации на .borderи .border-0за секоја точка на прекин. Вашиот генериран CSS ќе изгледа вака:

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

Преименувајте ги комуналните услуги

Недостасува v4 комунални услуги или се користи за друга конвенција за именување? Utilities API може да се користи за да се отфрли резултатот classод дадена алатка - на пример, да се преименуваат .ms-*услужните програми во стари .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";

Отстранете ги комуналните услуги

Отстранете која било од стандардните алатки со функцијата 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";

Можете исто така да ја користите функцијата map-merge()Sass и да го поставите копчето за групата за nullда ја отстраните алатката.

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

Додавање, отстранување, менување

Можете да додавате, отстранувате и менувате многу алатки одеднаш со функцијата map-merge()Sass . Еве како можете да ги комбинирате претходните примери во една поголема мапа.

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

Отстранете ја алатката во RTL

Некои рабови го отежнуваат стилот на RTL , како што се прекините на линиите на арапски. Така, комуналните услуги може да се исфрлат од излезот RTL со поставување на rtlопцијата на false:

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

Излез:

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

Ова не емитува ништо во RTL, благодарение на контролната директива RTLCSSremove .