Utility API

Naudingumo API yra Sass pagrįstas įrankis, skirtas komunalinių paslaugų klasėms generuoti.

Šiame puslapyje

„Bootstrap“ paslaugos generuojamos naudojant mūsų paslaugų API ir gali būti naudojamos modifikuoti arba išplėsti numatytąjį paslaugų klasių rinkinį per „Sass“. Mūsų paslaugų API yra pagrįsta Sass žemėlapių ir funkcijų serija, skirta kurti klasių šeimas su įvairiomis parinktimis. Jei nesate susipažinę su Sass žemėlapiais, norėdami pradėti , perskaitykite oficialius Sass dokumentus .

Žemėlapyje yra visos $utilitiesmūsų paslaugos ir vėliau jis sujungiamas su tinkintu $utilitiesžemėlapiu, jei toks yra. Naudingumo žemėlapyje yra raktų sąrašas paslaugų grupių, kurios priima šias parinktis:

Variantas	Tipas	Numatytoji reikšmė	apibūdinimas
`property`	Reikalingas	–	Ypatybės pavadinimas, tai gali būti eilutė arba eilučių masyvas (pvz., horizontalūs užpildai arba paraštės).
`values`	Reikalingas	–	Vertybių sąrašas arba žemėlapis, jei nenorite, kad klasės pavadinimas būtų toks pat kaip reikšmė. Jei `null`naudojamas kaip žemėlapio raktas, jis nėra kompiliuojamas.
`class`	Neprivaloma	nulinis	Sukurtos klasės pavadinimas. Jei nepateikta ir `property`yra eilučių masyvas, `class`pagal nutylėjimą bus pirmasis `property`masyvo elementas.
`css-var`	Neprivaloma	`false`	Būlio reikšmė generuoti CSS kintamuosius vietoj CSS taisyklių.
`local-vars`	Neprivaloma	nulinis	Vietinių CSS kintamųjų žemėlapis, kurį reikia generuoti be CSS taisyklių.
`state`	Neprivaloma	nulinis	Pseudoklasių variantų sąrašas (pvz., `:hover`arba `:focus`), kurį reikia generuoti.
`responsive`	Neprivaloma	`false`	Būlio reikšmė, nurodanti, ar reikia sugeneruoti reaguojančias klases.
`rfs`	Neprivaloma	`false`	Būlio reikšmė, kad būtų galima keisti skysčio skalę naudojant RFS .
`print`	Neprivaloma	`false`	Būlio reikšmė, nurodanti, ar reikia sugeneruoti spausdinimo klases.
`rtl`	Neprivaloma	`true`	Būlio reikšmė, nurodanti, ar naudingumas turėtų būti saugomas RTL.

API paaiškino

Visi naudingumo kintamieji pridedami prie $utilitieskintamojo mūsų _utilities.scssstiliaus lape. Kiekviena paslaugų grupė atrodo maždaug taip:

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

Kuris išveda šiuos duomenis:

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

Nuosavybė

Reikiamas propertyraktas turi būti nustatytas bet kokiai programai ir jame turi būti tinkama CSS ypatybė. Ši savybė naudojama sugeneruotos programos taisyklių rinkinyje. Kai classraktas yra praleistas, jis taip pat naudojamas kaip numatytasis klasės pavadinimas. Apsvarstykite text-decorationnaudingumą:

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

Išvestis:

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

Vertybės

Naudokite valuesklavišą, kad nurodytumėte, kurios nurodytos reikšmės propertyturi būti naudojamos sugeneruotų klasių pavadinimuose ir taisyklėse. Gali būti sąrašas arba žemėlapis (nustatytas paslaugų programose arba Sass kintamajame).

Kaip sąrašas, kaip ir su text-decorationkomunalinėmis paslaugomis :

values: none underline line-through

Kaip žemėlapis, kaip su opacitykomunalinėmis paslaugomis :

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

Kaip Sass kintamasis, kuris nustato sąrašą arba žemėlapį, kaip mūsų positionpaslaugų programose :

values: $position-values

Klasė

Naudokite classparinktį, kad pakeistumėte klasės priešdėlį, naudojamą sudarytame CSS. Pavyzdžiui, pakeisti iš .opacity-*į .o-*:

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

Išvestis:

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

CSS kintamųjų paslaugų programos

Nustatykite css-varloginę parinktį trueir API sugeneruos vietinius CSS kintamuosius tam parinkikliui, o ne įprastoms property: valuetaisyklėms. Apsvarstykite mūsų .text-opacity-*komunalines paslaugas:

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

Išvestis:

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

Vietiniai CSS kintamieji

Naudokite local-varsparinktį, norėdami nurodyti Sass žemėlapį, kuris generuos vietinius CSS kintamuosius pagal naudingumo klasės taisyklių rinkinį. Atminkite, kad norint panaudoti tuos vietinius CSS kintamuosius sugeneruotose CSS taisyklėse, gali prireikti papildomo darbo. Pavyzdžiui, apsvarstykite mūsų .bg-*komunalines paslaugas:

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

Išvestis:

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

valstybėse

Naudokite stateparinktį, kad sukurtumėte pseudoklasių variantus. Pseudoklasių pavyzdžiai yra :hoverir :focus. Pateikus būsenų sąrašą, tai pseudoklasei sukuriami klasių pavadinimai. Pavyzdžiui, norėdami pakeisti neskaidrumą užvedę pelės žymeklį, pridėkite state: hoverir gausite .opacity-hover:hoversavo sukompiliuotą CSS.

Reikia kelių pseudoklasių? Naudokite tarpais atskirtą būsenų sąrašą: state: hover focus.

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

Išvestis:

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

Atsakingas

Pridėkite responsiveloginę reikšmę, kad generuotumėte reaguojančias priemones (pvz., .opacity-md-25) visuose lūžio taškuose .

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

Išvestis:

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

Spausdinti

Įjungus šią printparinktį taip pat bus sukurtos spausdinimo naudingumo klasės, kurios taikomos tik @media print { ... }medijos užklausoje.

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

Išvestis:

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

Svarba

Visos API sugeneruotos komunalinės paslaugos !importantužtikrina, kad jos nepaisytų komponentų ir modifikatorių klasių, kaip numatyta. Šį nustatymą galite perjungti visame pasaulyje naudodami $enable-important-utilitieskintamąjį (numatytasis nustatymas yra true).

Naudojant API

Dabar, kai žinote, kaip veikia paslaugų API, sužinokite, kaip pridėti savo pasirinktines klases ir modifikuoti numatytąsias paslaugų programas.

Nepaisyti komunalinių paslaugų

Nepaisykite esamų paslaugų naudodami tą patį raktą. Pavyzdžiui, jei norite papildomų interaktyvių perpildymo paslaugų klasių, galite tai padaryti:

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

Pridėti komunalines paslaugas

$utilitiesĮ numatytąjį žemėlapį galima pridėti naujų paslaugų su map-merge. Įsitikinkite, kad _utilities.scsspirmiausia yra importuoti reikalingi Sass failai ir, tada naudokite, map-mergekad pridėtumėte papildomų paslaugų. Pavyzdžiui, štai kaip pridėti reaguojančią cursorprogramą su trimis reikšmėmis.

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

Keisti komunalines paslaugas

Modifikuokite esamas komunalines paslaugas numatytame $utilitiesžemėlapyje su map-getir map-mergefunkcijomis. Toliau pateiktame pavyzdyje prie widthkomunalinių paslaugų pridedame papildomą reikšmę. Pradėkite nuo inicialo map-mergeir tada nurodykite, kurią programą norite keisti. Iš ten pateikite įdėtą "width"žemėlapį, map-getkad galėtumėte pasiekti ir modifikuoti paslaugų parinktis ir reikšmes.

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

Įgalinti reaguojantį

Galite įgalinti reaguojančias klases esamam paslaugų rinkiniui, kuris šiuo metu pagal numatytuosius nustatymus nereaguoja. Pavyzdžiui, kad borderklasės būtų jautrios:

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

Dabar bus sugeneruoti atsakingi kiekvieno pertraukos taško .borderir variantai. .border-0Jūsų sugeneruotas CSS atrodys taip:

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

Pervardyti komunalines paslaugas

Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting class of a given utility—for example, to rename .ms-* utilities to 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 ),
    ),
  )
);

Remove utilities

Remove any of the default utilities by setting the group key to null. For example, to remove all our width utilities, create a $utilities map-merge and add "width": null within.

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

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

Remove utility in RTL

Some edge cases make RTL styling difficult, such as line breaks in Arabic. Thus utilities can be dropped from RTL output by setting the rtl option to false:

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

Output:

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

This doesn’t output anything in RTL, thanks to the RTLCSS remove control directive.