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	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	Variabel untuk nama kelas jika Anda tidak ingin sama dengan properti. Jika Anda tidak memberikan `class`kunci dan `property`kunci adalah array string, nama kelas akan menjadi elemen pertama dari `property`array.
`state`	Opsional	Daftar varian pseudo-class yang disukai `:hover`atau `:focus`dihasilkan untuk utilitas. Tidak ada nilai default.
`responsive`	Opsional	Boolean menunjukkan jika kelas responsif perlu dibuat. `false`secara default.
`rfs`	Opsional	Boolean untuk mengaktifkan penskalaan ulang cairan. Lihat halaman RFS untuk mengetahui cara kerjanya. `false`secara default.
`print`	Opsional	Boolean menunjukkan jika kelas cetak perlu dibuat. `false`secara default.
`rtl`	Opsional	Boolean menunjukkan jika utilitas harus disimpan di RTL. `true`secara default.

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

Awalan kelas khusus

Gunakan classopsi untuk mengubah awalan kelas yang digunakan dalam CSS yang dikompilasi:

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

Keluaran:

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

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

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

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

Utilitas cetak

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.

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 yang diberikan—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 .