API Utilitas

API utilitas minangka alat basis Sass kanggo ngasilake kelas sarana.

Ing kaca iki

Utilitas Bootstrap digawe nganggo API utilitas kita lan bisa digunakake kanggo ngowahi utawa ngluwihi set standar kelas utilitas liwat Sass. API utilitas kita adhedhasar seri peta lan fungsi Sass kanggo ngasilake kulawarga kelas kanthi macem-macem pilihan. Yen sampeyan ora ngerti peta Sass, waca dokumen Sass resmi kanggo miwiti.

Peta $utilitieskasebut ngemot kabeh keperluan kita lan banjur digabung karo $utilitiespeta khusus sampeyan, yen ana. Peta sarana ngemot dhaptar klompok utilitas sing dikunci sing nampa pilihan ing ngisor iki:

Pilihan	Jinis	Nilai standar	Katrangan
`property`	dibutuhake	–	Jeneng properti, iki bisa dadi senar utawa array saka strings (contone, paddings horisontal utawa pinggiran).
`values`	dibutuhake	–	Dhaptar nilai, utawa peta yen sampeyan ora pengin jeneng kelas padha karo nilai. Yen `null`digunakake minangka kunci peta, ora dikompilasi.
`class`	Opsional	null	Jeneng kelas sing digawe. Yen ora kasedhiya lan `property`Uploaded saka strings, `class`bakal gawan kanggo unsur pisanan `property`Uploaded.
`css-var`	Opsional	`false`	Boolean kanggo ngasilake variabel CSS tinimbang aturan CSS.
`local-vars`	Opsional	null	Peta variabel CSS lokal kanggo ngasilake saliyane aturan CSS.
`state`	Opsional	null	Dhaptar varian kelas pseudo (contone, `:hover`utawa `:focus`) kanggo ngasilake.
`responsive`	Opsional	`false`	Boolean sing nuduhake yen kelas responsif kudu digawe.
`rfs`	Opsional	`false`	Boolean kanggo ngaktifake rescaling cairan karo RFS .
`print`	Opsional	`false`	Boolean sing nuduhake yen kelas print kudu digawe.
`rtl`	Opsional	`true`	Boolean sing nuduhake yen sarana kudu disimpen ing RTL.

API diterangno

Kabeh variabel utilitas ditambahake menyang $utilitiesvariabel ing _utilities.scssstylesheet kita. Saben klompok utilitas katon kaya iki:

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

Kang output ing ngisor iki:

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

Properti

Tombol sing dibutuhake propertykudu disetel kanggo sarana apa wae, lan kudu ngemot properti CSS sing bener. Properti iki digunakake ing ruleset sarana sing digawe. Nalika classtombol diilangi, uga dadi jeneng kelas standar. Coba text-decorationgunakake:

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

Nilai

Gunakake valuestombol kanggo nemtokake nilai sing ditemtokake propertykudu digunakake ing jeneng kelas lan aturan sing digawe. Bisa dadi dhaptar utawa peta (diset ing utilitas utawa ing variabel Sass).

Minangka dhaptar, kaya karo text-decorationutilitas :

values: none underline line-through

Minangka peta, kaya karo opacityutilitas :

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

Minangka variabel Sass sing nyetel dhaptar utawa peta, kaya ing positionutilitas kita :

values: $position-values

kelas

Gunakake classpilihan kanggo ngganti awalan kelas sing digunakake ing CSS kompilasi. Contone, kanggo ngganti saka .opacity-*menyang .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; }

Utilitas variabel CSS

Setel css-varpilihan boolean truelan API bakal ngasilake variabel CSS lokal kanggo pamilih sing diwenehake tinimbang property: valueaturan sing biasa. Coba .text-opacity-*utilitas kita:

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

Variabel CSS lokal

Gunakake local-varspilihan kanggo nemtokake peta Sass sing bakal ngasilake variabel CSS lokal ing aturan kelas sarana. Wigati dimangerteni manawa mbutuhake karya tambahan kanggo nggunakake variabel CSS lokal kasebut ing aturan CSS sing digawe. Contone, nimbang .bg-*utilitas kita:

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

negara

Gunakake statepilihan kanggo ngasilake variasi kelas pseudo. Conto kelas pseudo yaiku :hoverlan :focus. Nalika dhaptar negara diwenehake, jeneng kelas digawe kanggo kelas pseudo kasebut. Contone, kanggo ngganti opacity ing hover, nambah state: hoverlan sampeyan bakal entuk .opacity-hover:hoverCSS kompilasi.

Perlu sawetara pseudo-kelas? Gunakake dhaptar negara sing dipisahake spasi: 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; }

Responsif

Tambah responsiveboolean kanggo ngasilake utilitas responsif (contone, .opacity-md-25) ing kabeh breakpoints .

$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

Ngaktifake printpilihan uga bakal ngasilake kelas sarana kanggo dicithak, sing mung ditrapake ing @media print { ... }query media.

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

wigati

Kabeh keperluan sing digawe dening API kalebu !importantkanggo mesthekake yen ngganti komponen lan kelas modifier kaya sing dikarepake. Sampeyan bisa ngalih setelan iki sacara global nganggo $enable-important-utilitiesvariabel (standar kanggo true).

Nggunakake API

Saiki sampeyan wis ngerti cara kerja API utilitas, sinau carane nambah kelas khusus sampeyan dhewe lan ngowahi utilitas standar.

Ngganti utilitas

Ganti utilitas sing ana kanthi nggunakake tombol sing padha. Contone, yen sampeyan pengin kelas utilitas overflow responsif tambahan, sampeyan bisa nindakake iki:

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

Tambah utilitas

Utilitas anyar bisa ditambahake menyang $utilitiespeta standar kanthi map-merge. Priksa manawa file Sass sing dibutuhake lan _utilities.scssdiimpor dhisik, banjur gunakake map-mergekanggo nambah keperluan tambahan sampeyan. Contone, iki carane nambah cursorsarana responsif kanthi telung nilai.

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

Ngowahi utilitas

$utilitiesNgowahi keperluan ana ing peta standar karo map-getlan map-mergefungsi. Ing conto ing ngisor iki, kita nambahake nilai tambahan kanggo widthutilitas. Miwiti karo dhisikan map-mergebanjur nemtokake sarana sing pengin diowahi. "width"Saka ing kono, jupuk peta nested map-getkanggo ngakses lan ngowahi pilihan lan nilai sarana.

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

Aktifake responsif

Sampeyan bisa ngaktifake kelas responsif kanggo pesawat ana saka keperluan sing saiki ora responsif minangka standar. Contone, kanggo nggawe borderkelas responsif:

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

Iki saiki bakal ngasilake variasi responsif .borderlan .border-0kanggo saben breakpoint. CSS sing digawe bakal katon kaya iki:

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

Ganti jeneng utilitas

Ilang keperluan v4, utawa digunakake kanggo konvènsi jeneng liyane? API utilitas bisa digunakake kanggo ngganti asil classsaka utilitas sing diwenehake-contone, kanggo ngganti jeneng .ms-*utilitas dadi lawas .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 ),
    ),
  )
);

Mbusak keperluan

Mbusak utilitas standar kanthi nyetel tombol grup menyang null. Contone, kanggo mbusak kabeh widthkeperluan kita, nggawe $utilities map-mergelan nambah "width": nulling.

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

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

Mbusak sarana ing RTL

Sawetara kasus pinggir nggawe gaya RTL angel , kayata jeda baris ing basa Arab. Dadi utilitas bisa dicopot saka output RTL kanthi nyetel rtlpilihan kanggo 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 */

Iki ora ngasilake apa-apa ing RTL, amarga arahan kontrol RTLCSSremove .