Utility API

The utility API er Sass byggt tól til að búa til gagnsemi flokka.

Á þessari síðu

Bootstrap tól eru búin til með tólum API okkar og hægt er að nota til að breyta eða stækka sjálfgefið sett af tólaflokkum í gegnum Sass. Forritaskil gagnsemi okkar eru byggð á röð Sass korta og aðgerða til að búa til flokkafjölskyldur með ýmsum valkostum. Ef þú þekkir ekki Sass kort skaltu lesa upp opinberu Sass skjölin til að byrja.

Kortið $utilitiesinniheldur öll tólin okkar og er síðar sameinuð sérsniðnu $utilitieskortinu þínu, ef það er til staðar. Veitukortið inniheldur lykillista yfir veituhópa sem samþykkja eftirfarandi valkosti:

Valkostur	Tegund	Sjálfgefið gildi	Lýsing
`property`	Áskilið	–	Heiti eignarinnar, þetta getur verið strengur eða fylki strengja (td lárétt bólstrun eða spássíur).
`values`	Áskilið	–	Listi yfir gildi, eða kort ef þú vilt ekki að flokksnafnið sé það sama og gildið. If `null`er notaður sem `class`kortalykill, er ekki á undan bekkjarheitinu.
`class`	Valfrjálst	núll	Heiti myndaðs flokks. Ef það er ekki gefið upp og `property`er fylki af strengjum, `class`verður sjálfgefið fyrsta þátt `property`fylkisins. Ef það er ekki gefið upp og `property`er strengur eru `values`takkarnir notaðir fyrir `class`nöfnin.
`css-var`	Valfrjálst	`false`	Boolean til að búa til CSS breytur í stað CSS reglna.
`css-variable-name`	Valfrjálst	núll	Sérsniðið nafn án forskeyti fyrir CSS breytuna inni í reglusettinu.
`local-vars`	Valfrjálst	núll	Kort af staðbundnum CSS breytum til að búa til til viðbótar við CSS reglurnar.
`state`	Valfrjálst	núll	Listi yfir gerviflokkaafbrigði (td `:hover`eða `:focus`) til að búa til.
`responsive`	Valfrjálst	`false`	Boolean gefur til kynna hvort búa eigi til móttækilega flokka.
`rfs`	Valfrjálst	`false`	Boolean til að gera kleift að endurskala vökva með RFS .
`print`	Valfrjálst	`false`	Boolean gefur til kynna hvort búa þurfi til prentflokka.
`rtl`	Valfrjálst	`true`	Boolean sem gefur til kynna hvort nota ætti að vera í RTL.

API útskýrt

Öllum nytjabreytum er bætt við $utilitiesbreytuna í _utilities.scssstílblaðinu okkar. Hver hópur veitu lítur einhvern veginn svona út:

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

Sem gefur út eftirfarandi:

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

Eign

Nauðsynlegur propertylykill verður að vera stilltur fyrir hvaða tól sem er og hann verður að innihalda gilda CSS eign. Þessi eign er notuð í reglusetti tólsins. Þegar classlyklinum er sleppt virkar hann einnig sem sjálfgefið flokksheiti. Hugleiddu text-decorationgagnsemina:

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

Framleiðsla:

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

Gildi

Notaðu valueslykilinn til að tilgreina hvaða gildi fyrir tilgreinda propertyætti að nota í mynduðum flokksnöfnum og reglum. Getur verið listi eða kort (sett í tólum eða í Sass breytu).

Sem listi, eins og með text-decorationtólum :

values: none underline line-through

Sem kort, eins og með opacitytólum :

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

Sem Sass breyta sem setur listann eða kortið, eins og í positiontólum okkar :

values: $position-values

bekk

Notaðu classmöguleikann til að breyta flokksforskeyti sem notað er í samsettum CSS. Til dæmis, til að breyta úr .opacity-*í .o-*:

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

Framleiðsla:

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

Ef class: null, býr til flokka fyrir hvern valueslykla:

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

Framleiðsla:

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

CSS breytileg tól

Stilltu css-varBoolean valkostinn á trueog API mun búa til staðbundnar CSS breytur fyrir tiltekinn veljara í stað venjulegra property: valuereglna. Bættu við valfrjálsu css-variable-nametil að stilla annað CSS breytuheiti en flokksheitið.

Íhuga .text-opacity-*veitur okkar. Ef við bætum css-variable-namevalkostinum við fáum við sérsniðið úttak.

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

Framleiðsla:

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

Staðbundnar CSS breytur

Notaðu local-varsvalmöguleikann til að tilgreina Sass kort sem mun búa til staðbundnar CSS breytur innan reglusetts tólaflokksins. Vinsamlegast athugaðu að það gæti þurft viðbótarvinnu til að nota þessar staðbundnu CSS breytur í CSS reglum sem myndaðar eru. Skoðum til dæmis .bg-*tólin okkar:

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

Framleiðsla:

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

Ríki

Notaðu statemöguleikann til að búa til gerviflokkaafbrigði. Dæmi um gerviflokkar eru :hoverog :focus. Þegar listi yfir ríki er veittur eru flokksnöfn búin til fyrir þann gerviflokk. Til dæmis, til að breyta ógagnsæi á sveimi skaltu bæta við state: hoverog þú munt komast .opacity-hover:hoverinn í samansetta CSS.

Þarftu marga gerviflokka? Notaðu bilaðskilinn lista yfir ríki: state: hover focus.

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

Framleiðsla:

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

Móttækilegur

Bættu við responsiveboolean til að búa til móttækileg tól (td .opacity-md-25) yfir alla brotpunkta .

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

Framleiðsla:

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

Prenta

Ef printvalkosturinn er virkur mun einnig myndast gagnsemisflokkar fyrir prentun, sem eru aðeins notaðir innan @media print { ... }fjölmiðlafyrirspurnarinnar.

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

Framleiðsla:

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

Mikilvægi

Öll tól sem myndast af API innihalda !importanttil að tryggja að þau hnekkja íhlutum og breytingaflokkum eins og ætlað er. Þú getur skipt um þessa stillingu á heimsvísu með $enable-important-utilitiesbreytunni (sjálfgefið er true).

Með því að nota API

Nú þegar þú ert kunnugur hvernig forritaskil tóla virka skaltu læra hvernig á að bæta við eigin sérsniðnum flokkum og breyta sjálfgefnum tólum okkar.

Hneka tólum

Hneka núverandi tólum með því að nota sama lykil. Til dæmis, ef þú vilt fá fleiri móttækilega yfirflæðisveituflokka, geturðu gert þetta:

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

Bæta við tólum

Hægt er að bæta nýjum tólum við sjálfgefið $utilitieskort með map-merge. Gakktu úr skugga um að nauðsynlegar Sass skrár okkar og _utilities.scssséu fluttar inn fyrst, notaðu síðan map-mergetil að bæta við viðbótartólum þínum. Til dæmis, hér er hvernig á að bæta við móttækilegu cursortóli með þremur gildum.

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

Breyta tólum

Breyttu núverandi tólum á sjálfgefna $utilitieskortinu með map-getog map-mergeaðgerðum. Í dæminu hér að neðan erum við að bæta við viðbótarvirði við widthveiturnar. Byrjaðu á upphafsstaf map-mergeog tilgreindu síðan hvaða tól þú vilt breyta. Þaðan skaltu sækja hreiður "width"kortið með map-gettil að fá aðgang að og breyta valkostum og gildum tólsins.

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

Virkja móttækilegur

Þú getur virkjað móttækilega flokka fyrir núverandi sett af tólum sem eru ekki móttækileg sjálfgefið. Til dæmis, til að gera borderbekkina móttækilega:

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

Þetta mun nú búa til móttækileg afbrigði af .borderog .border-0fyrir hvern brotpunkt. Mynduð CSS mun líta svona út:

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

Endurnefna tól

Vantar v4 tól, eða vanur annarri nafnavenju? Hægt er að nota forritaskil tóla til að hnekkja niðurstöðu classtiltekins tóls - til dæmis til að endurnefna .ms-*tól í oldish .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";

Fjarlægðu tól

Fjarlægðu eitthvað af sjálfgefnum tólum með map-remove()Sass aðgerðinni .

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

Þú getur líka notað map-merge()Sass aðgerðina og stillt hóplykilinn á til nullað fjarlægja tólið.

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

Bæta við, fjarlægja, breyta

Þú getur bætt við, fjarlægt og breytt mörgum tólum í einu með map-merge()Sass aðgerðinni . Hér er hvernig þú getur sameinað fyrri dæmin í eitt stærra kort.

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

Fjarlægðu tól í RTL

Sum jaðarhylki gera RTL stíl erfitt , svo sem línuskil á arabísku. Þannig er hægt að sleppa tólum úr RTL framleiðslu með því að stilla rtlvalkostinn á false:

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

Framleiðsla:

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

Þetta gefur ekki út neitt í RTL, þökk sé RTLCSS removestjórnskipuninni .