API Utilitas

API utilitas adalah alat berbasis Sass untuk menghasilkan kelas utilitas.

Di halaman ini

Utilitas bootstrap dihasilkan dengan API utilitas kami dan dapat digunakan untuk memodifikasi atau memperluas kumpulan kelas utilitas default kami melalui Sass. API utilitas kami didasarkan pada serangkaian peta dan fungsi Sass untuk menghasilkan keluarga kelas dengan berbagai opsi. Jika Anda tidak terbiasa dengan peta Sass, bacalah dokumen resmi Sass untuk memulai.

Peta $utilitiesberisi semua utilitas kami dan kemudian digabungkan dengan $utilitiespeta khusus Anda, jika ada. Peta utilitas berisi daftar kunci grup utilitas yang menerima opsi berikut:

Pilihan	Jenis	Nilai default	Keterangan
`property`	Yg dibutuhkan	-	Nama properti, ini bisa berupa string atau array string (misalnya, padding atau margin horizontal).
`values`	Yg dibutuhkan	-	Daftar nilai, atau peta jika Anda tidak ingin nama kelas sama dengan nilainya. Jika `null`digunakan sebagai kunci peta, itu tidak dikompilasi.
`class`	Opsional	batal	Nama kelas yang dihasilkan. Jika tidak disediakan dan `property`merupakan array string, `class`akan default ke elemen pertama dari `property`array.
`css-var`	Opsional	`false`	Boolean untuk menghasilkan variabel CSS alih-alih aturan CSS.
`local-vars`	Opsional	batal	Peta variabel CSS lokal yang akan dihasilkan selain aturan CSS.
`state`	Opsional	batal	Daftar varian pseudo-class (misalnya, `:hover`atau `:focus`) yang akan dihasilkan.
`responsive`	Opsional	`false`	Boolean menunjukkan apakah kelas responsif harus dibuat.
`rfs`	Opsional	`false`	Boolean untuk mengaktifkan penskalaan ulang cairan dengan RFS .
`print`	Opsional	`false`	Boolean menunjukkan jika kelas cetak perlu dibuat.
`rtl`	Opsional	`true`	Boolean menunjukkan jika utilitas harus disimpan di RTL.

API dijelaskan

Semua variabel utilitas ditambahkan ke $utilitiesvariabel dalam _utilities.scssstylesheet kita. Setiap grup utilitas terlihat seperti ini:

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

Yang menghasilkan sebagai berikut:

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

Properti

Kunci yang diperlukan propertyharus disetel untuk utilitas apa pun, dan harus berisi properti CSS yang valid. Properti ini digunakan dalam kumpulan aturan utilitas yang dihasilkan. Ketika classkunci dihilangkan, itu juga berfungsi sebagai nama kelas default. Pertimbangkan text-decorationutilitasnya:

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

Keluaran:

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

Nilai

Gunakan valueskunci untuk menentukan nilai mana untuk yang ditentukan propertyharus digunakan dalam nama dan aturan kelas yang dihasilkan. Dapat berupa daftar atau peta (diatur dalam utilitas atau dalam variabel Sass).

Sebagai daftar, seperti dengan text-decorationutilitas :

values: none underline line-through

Sebagai peta, seperti dengan opacityutilitas :

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

Sebagai variabel Sass yang mengatur daftar atau peta, seperti dalam positionutilitas kami :

values: $position-values

Kelas

Gunakan classopsi untuk mengubah awalan kelas yang digunakan dalam CSS yang dikompilasi. Misalnya, untuk mengubah dari .opacity-*ke .o-*:

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

Keluaran:

.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-varopsi boolean ke truedan API akan menghasilkan variabel CSS lokal untuk pemilih yang diberikan alih-alih property: valueaturan biasa. Pertimbangkan .text-opacity-*utilitas kami:

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

Keluaran:

.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

Gunakan local-varsopsi untuk menentukan peta Sass yang akan menghasilkan variabel CSS lokal dalam set aturan kelas utilitas. Harap dicatat bahwa mungkin memerlukan pekerjaan tambahan untuk menggunakan variabel CSS lokal tersebut dalam aturan CSS yang dihasilkan. Misalnya, pertimbangkan .bg-*utilitas kami:

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

Keluaran:

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

negara bagian

Gunakan stateopsi untuk menghasilkan variasi kelas semu. Contoh pseudo-class adalah :hoverdan :focus. Ketika daftar status disediakan, nama kelas dibuat untuk kelas semu itu. Misalnya, untuk mengubah opacity saat mengarahkan kursor, tambahkan state: hoverdan Anda akan mendapatkan .opacity-hover:hoverCSS yang dikompilasi.

Perlu beberapa kelas semu? Gunakan daftar status yang dipisahkan oleh spasi: state: hover focus.

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

Keluaran:

.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

Tambahkan responsiveboolean untuk menghasilkan utilitas responsif (misalnya, .opacity-md-25) di semua breakpoints .

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

Keluaran:

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

Mencetak

Mengaktifkan printopsi juga akan menghasilkan kelas utilitas untuk pencetakan, yang hanya diterapkan dalam @media print { ... }kueri media.

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

Keluaran:

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

Pentingnya

Semua utilitas yang dihasilkan oleh API termasuk !importantuntuk memastikan mereka mengganti komponen dan kelas pengubah sebagaimana dimaksud. Anda dapat mengaktifkan pengaturan ini secara global dengan $enable-important-utilitiesvariabel (default ke true).

Menggunakan API

Sekarang setelah Anda terbiasa dengan cara kerja API utilitas, pelajari cara menambahkan kelas kustom Anda sendiri dan memodifikasi utilitas default kami.

Ganti utilitas

Ganti utilitas yang ada dengan menggunakan kunci yang sama. Misalnya, jika Anda menginginkan kelas utilitas overflow responsif tambahan, Anda dapat melakukan ini:

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

Tambahkan utilitas

Utilitas baru dapat ditambahkan ke $utilitiespeta default dengan ekstensi map-merge. Pastikan file Sass kami _utilities.scssyang diperlukan dan diimpor terlebih dahulu, lalu gunakan map-mergeuntuk menambahkan utilitas tambahan Anda. Misalnya, berikut ini cara menambahkan cursorutilitas responsif dengan tiga 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,
    )
  )
);

Ubah utilitas

Ubah utilitas yang ada di $utilitiespeta default dengan map-getdan map-mergefungsi. Pada contoh di bawah, kami menambahkan nilai tambahan ke widthutilitas. Mulailah dengan inisial map-mergedan kemudian tentukan utilitas mana yang ingin Anda ubah. "width"Dari sana, ambil peta bersarang map-getuntuk mengakses dan mengubah opsi dan nilai utilitas.

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

Aktifkan responsif

Anda dapat mengaktifkan kelas responsif untuk kumpulan utilitas yang ada yang saat ini tidak responsif secara default. Misalnya, untuk membuat 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 ),
    ),
  )
);

Ini sekarang akan menghasilkan variasi responsif dari .borderdan .border-0untuk setiap breakpoint. CSS yang Anda buat akan terlihat seperti ini:

.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 nama utilitas

Utilitas v4 tidak ada, atau terbiasa dengan konvensi penamaan lain? API utilitas dapat digunakan untuk mengganti hasil classdari utilitas tertentu—misalnya, untuk mengganti nama .ms-*utilitas menjadi 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 ),
    ),
  )
);

Hapus utilitas

Hapus semua utilitas default dengan mengatur kunci grup ke null. Misalnya, untuk menghapus semua widthutilitas kami, buat $utilities map-mergedan tambahkan "width": nulldi dalamnya.

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

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

Hapus utilitas di RTL

Beberapa kasus tepi membuat penataan RTL menjadi sulit , seperti jeda baris dalam bahasa Arab. Dengan demikian utilitas dapat dikeluarkan dari output RTL dengan mengatur rtlopsi ke false:

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

Keluaran:

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

Ini tidak menghasilkan apa pun di RTL, berkat arahan kontrol RTLCSSremove .