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	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	Variable para sa pangalan ng klase kung ayaw mong maging pareho ito sa property. Kung sakaling hindi mo ibigay ang `class`susi at `property`ang susi ay isang hanay ng mga string, ang pangalan ng klase ang magiging unang elemento ng `property`array.
`state`	Opsyonal	Listahan ng mga pseudo-class na variant na gusto `:hover`o `:focus`gagawin para sa utility. Walang default na halaga.
`responsive`	Opsyonal	Boolean na nagpapahiwatig kung ang mga tumutugon na klase ay kailangang mabuo. `false`bilang default.
`rfs`	Opsyonal	Boolean upang paganahin ang fluid rescaling. Tingnan ang pahina ng RFS upang malaman kung paano ito gumagana. `false`bilang default.
`print`	Opsyonal	Boolean na nagpapahiwatig kung ang mga klase sa pag-print ay kailangang mabuo. `false`bilang default.
`rtl`	Opsyonal	Boolean na nagpapahiwatig kung ang utility ay dapat panatilihin sa RTL. `true`bilang default.

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

Custom na prefix ng klase

Gamitin ang classopsyon para baguhin ang class prefix na ginamit sa compiled CSS:

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

Output:

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

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

Mga tumutugon na kagamitan

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

Pagbabago ng 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,
  ),
);

Mga kagamitan sa pag-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.

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 kombensiyon ng pagbibigay ng pangalan? Ang mga utility API ay maaaring gamitin 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 .