Utility API

Ang utility API ay isang tool na nakabatay sa Sass upang makabuo ng mga klase ng utility.

Sa pahinang ito

Ang mga utility ng Bootstrap ay nabuo gamit ang aming utility API at maaaring gamitin upang baguhin o palawigin ang aming default na hanay ng mga klase ng utility sa pamamagitan ng Sass. Ang aming utility API ay batay sa isang serye ng mga mapa at function ng Sass para sa pagbuo ng mga pamilya ng mga klase na may iba't ibang opsyon. Kung hindi ka pamilyar sa mga mapa ng Sass, magbasa sa opisyal na mga dokumento ng Sass upang makapagsimula.

Ang $utilitiesmapa ay naglalaman ng lahat ng aming mga kagamitan at sa kalaunan ay pinagsama sa iyong custom na $utilitiesmapa, kung mayroon. Ang mapa ng utility ay naglalaman ng isang naka-key na listahan ng mga pangkat ng utility na tumatanggap ng mga sumusunod na opsyon:

Pagpipilian	Uri	Default na halaga	Paglalarawan
`property`	Kailangan	–	Pangalan ng property, ito ay maaaring isang string o isang array ng mga string (hal., horizontal paddings o margins).
`values`	Kailangan	–	Listahan ng mga halaga, o isang mapa kung hindi mo nais na ang pangalan ng klase ay pareho sa halaga. Kung `null`ginamit bilang key ng mapa, hindi ito pinagsama-sama.
`class`	Opsyonal	wala	Pangalan ng nabuong klase. Kung hindi ibinigay at `property`isang array ng mga string, `class`ay magiging default sa unang elemento ng `property`array.
`css-var`	Opsyonal	`false`	Boolean upang bumuo ng mga variable ng CSS sa halip na mga panuntunan ng CSS.
`local-vars`	Opsyonal	wala	Mapa ng mga lokal na variable ng CSS upang mabuo bilang karagdagan sa mga panuntunan ng CSS.
`state`	Opsyonal	wala	Listahan ng mga pseudo-class na variant (hal, `:hover`o `:focus`) na bubuuin.
`responsive`	Opsyonal	`false`	Boolean na nagsasaad kung dapat mabuo ang mga tumutugong klase.
`rfs`	Opsyonal	`false`	Boolean upang paganahin ang fluid rescaling gamit ang RFS .
`print`	Opsyonal	`false`	Boolean na nagpapahiwatig kung ang mga klase sa pag-print ay kailangang mabuo.
`rtl`	Opsyonal	`true`	Boolean na nagpapahiwatig kung ang utility ay dapat panatilihin sa RTL.

Ipinaliwanag ng API

Ang lahat ng mga variable ng utility ay idinaragdag sa $utilitiesvariable sa loob ng aming _utilities.scssstylesheet. Ang bawat pangkat ng mga utility ay ganito ang hitsura:

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

Alin ang naglalabas ng sumusunod:

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

Ari-arian

Ang kinakailangang propertykey ay dapat itakda para sa anumang utility, at dapat itong maglaman ng wastong CSS property. Ang property na ito ay ginagamit sa nabuong ruleset ng utility. Kapag classtinanggal ang susi, nagsisilbi rin itong default na pangalan ng klase. Isaalang-alang ang text-decorationutility:

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

Output:

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

Mga halaga

Gamitin ang valueskey para tukuyin kung aling mga value para sa tinukoy propertyang dapat gamitin sa nabuong mga pangalan at panuntunan ng klase. Maaaring isang listahan o mapa (nakatakda sa mga utility o sa isang Sass variable).

Bilang isang listahan, tulad ng sa text-decorationmga utility :

values: none underline line-through

Bilang isang mapa, tulad ng sa opacitymga utility :

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

Bilang isang Sass variable na nagtatakda ng listahan o mapa, tulad ng sa aming mga positionutility :

values: $position-values

Klase

Gamitin ang classopsyon para baguhin ang class prefix na ginamit sa compiled CSS. Halimbawa, upang baguhin mula .opacity-*sa .o-*:

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

Output:

.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 variable utility

Itakda ang css-varboolean na opsyon sa trueat bubuo ang API ng mga lokal na variable ng CSS para sa ibinigay na selector sa halip na sa karaniwang mga property: valuepanuntunan. Isaalang-alang ang aming .text-opacity-*mga utility:

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

Output:

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

Mga lokal na variable ng CSS

Gamitin ang local-varsopsyon para tumukoy ng Sass map na bubuo ng mga lokal na variable ng CSS sa loob ng ruleset ng utility class. Pakitandaan na maaaring mangailangan ng karagdagang trabaho upang ubusin ang mga lokal na variable ng CSS sa nabuong mga panuntunan ng CSS. Halimbawa, isaalang-alang ang aming .bg-*mga utility:

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

Output:

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

Estado

Gamitin ang stateopsyon upang bumuo ng mga pseudo-class na variation. Ang mga halimbawang pseudo-class ay :hoverat :focus. Kapag ang isang listahan ng mga estado ay ibinigay, ang mga pangalan ng klase ay nilikha para sa pseudo-class na iyon. Halimbawa, upang baguhin ang opacity sa hover, magdagdag state: hoverat makukuha mo ang .opacity-hover:hoveriyong pinagsama-samang CSS.

Kailangan ng maramihang pseudo-class? Gumamit ng isang listahan ng mga estado na pinaghihiwalay ng espasyo: state: hover focus.

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

Output:

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

Tumutugon

Idagdag ang responsiveboolean upang makabuo ng mga tumutugon na kagamitan (hal., .opacity-md-25) sa lahat ng mga breakpoint .

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

Output:

.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

Ang pagpapagana sa printopsyon ay bubuo din ng mga utility class para sa pag-print, na inilalapat lamang sa loob ng @media print { ... }media query.

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

Output:

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

Kahalagahan

Kasama sa lahat ng mga utility na nabuo ng API !importantupang matiyak na na-override nila ang mga bahagi at mga klase ng modifier ayon sa nilalayon. Maaari mong i-toggle ang setting na ito sa buong mundo gamit ang $enable-important-utilitiesvariable (naka-default sa true).

Gamit ang API

Ngayong pamilyar ka na sa kung paano gumagana ang utility API, alamin kung paano magdagdag ng sarili mong mga custom na klase at baguhin ang aming mga default na utility.

I-override ang mga utility

I-override ang mga kasalukuyang utility sa pamamagitan ng paggamit ng parehong key. Halimbawa, kung gusto mo ng mga karagdagang responsive na overflow na mga klase ng utility, magagawa mo ito:

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

Magdagdag ng mga utility

Maaaring idagdag ang mga bagong utility sa default na $utilitiesmapa na may map-merge. Tiyaking _utilities.scssna-import muna ang aming mga kinakailangang Sass file, pagkatapos ay gamitin ang map-mergepara idagdag ang iyong mga karagdagang utility. Halimbawa, narito kung paano magdagdag ng tumutugon na cursorutility na may tatlong halaga.

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

Baguhin ang mga utility

Baguhin ang mga kasalukuyang utility sa default na $utilitiesmapa gamit ang map-getat mga map-mergefunction. Sa halimbawa sa ibaba, nagdaragdag kami ng karagdagang halaga sa mga widthutility. Magsimula sa isang inisyal map-mergeat pagkatapos ay tukuyin kung aling utility ang gusto mong baguhin. Mula doon, kunin ang nested na "width"mapa map-getpara ma-access at mabago ang mga opsyon at value ng utility.

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

Paganahin ang tumutugon

Maaari mong paganahin ang mga tumutugong klase para sa isang umiiral nang hanay ng mga utility na kasalukuyang hindi tumutugon bilang default. Halimbawa, upang gawing bordertumutugon ang mga klase:

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

Bubuo na ito ngayon ng mga tumutugong variation ng .borderat .border-0para sa bawat breakpoint. Ang iyong nabuong CSS ay magiging ganito:

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

Palitan ang pangalan ng mga utility

Nawawala ang mga utility ng v4, o ginamit sa isa pang kombensyon ng pagbibigay ng pangalan? Maaaring gamitin ang utility API upang i-override ang resulta classng isang ibinigay na utility—halimbawa, upang palitan ang pangalan ng mga .ms-*utility sa 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 ),
    ),
  )
);

Alisin ang mga utility

Alisin ang alinman sa mga default na utility sa pamamagitan ng pagtatakda ng group key sa null. Halimbawa, upang alisin ang lahat ng aming widthmga utility, gumawa ng $utilities map-mergeat magdagdag sa "width": nullloob.

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

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

Alisin ang utility sa RTL

Ang ilang edge case ay nagpapahirap sa pag-istilo ng RTL , gaya ng mga line break sa Arabic. Kaya ang mga utility ay maaaring i-drop mula sa RTL output sa pamamagitan ng pagtatakda ng rtlopsyon sa 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 */

Hindi ito naglalabas ng anuman sa RTL, salamat sa RTLCSS removecontrol directive .