API за помощни програми

API за помощни програми е базиран на Sass инструмент за генериране на класове за помощни програми.

На тази страница

Помощните програми Bootstrap се генерират с нашия API за помощни програми и могат да се използват за модифициране или разширяване на нашия набор от помощни класове по подразбиране чрез Sass. Нашият помощен API е базиран на серия от Sass карти и функции за генериране на семейства от класове с различни опции. Ако не сте запознати с картите на Sass, прочетете официалните документи на Sass , за да започнете.

Картата $utilitiesсъдържа всички наши помощни програми и по-късно се обединява с вашата персонализирана $utilitiesкарта, ако има такава. Картата на помощните програми съдържа списък с ключове от групи помощни програми, които приемат следните опции:

опция	Тип	Описание
`property`	Задължително	Име на свойството, това може да бъде низ или масив от низове (напр. хоризонтални подложки или полета).
`values`	Задължително	Списък със стойности или карта, ако не искате името на класа да е същото като стойността. Ако `null`се използва като ключ за карта, той не се компилира.
`class`	Не е задължително	Променлива за името на класа, ако не искате то да е същото като свойството. В случай, че не предоставите `class`ключа и `property`ключът е масив от низове, името на класа ще бъде първият елемент на `property`масива.
`state`	Не е задължително	Списък с варианти на псевдокласове като `:hover`или `:focus`за генериране за помощната програма. Няма стойност по подразбиране.
`responsive`	Не е задължително	Булева стойност, показваща дали трябва да се генерират адаптивни класове. `false`по подразбиране.
`rfs`	Не е задължително	Булева стойност за активиране на флуидно повторно мащабиране. Разгледайте страницата на RFS , за да разберете как работи това. `false`по подразбиране.
`print`	Не е задължително	Булева стойност, показваща дали трябва да се генерират класове за печат. `false`по подразбиране.
`rtl`	Не е задължително	Булева стойност, показваща дали помощната програма трябва да се съхранява в RTL. `true`по подразбиране.

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

Персонализиран префикс на клас

Използвайте classопцията за промяна на префикса на класа, използван в компилирания CSS:

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

Изход:

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

държави

Използвайте 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; }
}

Смяна на комунални услуги

Заменете съществуващите помощни програми, като използвате същия ключ. Например, ако искате допълнителни отзивчиви помощни класове за препълване, можете да направите това:

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

Помощни програми за печат

Активирането на 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картата по подразбиране с map-merge. Уверете се, че нашите необходими Sass файлове и _utilities.scssпърво са импортирани, след което използвайте, за map-mergeда добавите вашите допълнителни помощни програми. Например, ето как да добавите отзивчива cursorпомощна програма с три стойности.

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

Променете помощните програми

$utilitiesПроменете съществуващите помощни програми в картата по подразбиране с функции map-getи map-merge. В примера по-долу добавяме допълнителна стойност към widthпомощните програми. Започнете с инициал map-mergeи след това посочете коя помощна програма искате да промените. Оттам изтеглете вложената "width"карта, за map-getда получите достъп и да промените опциите и стойностите на помощната програма.

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

Активиране на отзивчивостта

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

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

Това вече ще генерира отзивчиви варианти на .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 помощни програми или се използва друга конвенция за именуване? API на помощните програми може да се използва за замяна на резултата classот дадена помощна програма – например, за преименуване .ms-*на помощни програми на oldish .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 ),
    ),
  )
);

Премахнете помощните програми

Премахнете някоя от помощните програми по подразбиране, като зададете груповия ключ на null. Например, за да премахнете всички наши widthпомощни програми, създайте $utilities map-mergeи добавете "width": nullв него.

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

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

Премахнете помощната програма в 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 .