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, `class`tidak ditambahkan ke nama kelas.
`class`	Opsional	batal	Nama kelas yang dihasilkan. Jika tidak disediakan dan `property`merupakan array string, `class`akan default ke elemen pertama dari `property`array. Jika tidak disediakan dan `property`berupa string, `values`kunci digunakan untuk `class`nama.
`css-var`	Opsional	`false`	Boolean untuk menghasilkan variabel CSS alih-alih aturan CSS.
`css-variable-name`	Opsional	batal	Nama kustom tanpa awalan untuk variabel CSS di dalam kumpulan aturan.
`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; }

Jika class: null, menghasilkan kelas untuk masing-masing valueskunci:

$utilities: (
  "visibility": (
    property: visibility,
    class: null,
    values: (
      visible: visible,
      invisible: hidden,
    )
  )
);

Keluaran:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !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. Tambahkan opsional css-variable-nameuntuk menetapkan nama variabel CSS yang berbeda dari nama kelas.

Pertimbangkan .text-opacity-*utilitas kami. Jika kami menambahkan css-variable-nameopsi, kami akan mendapatkan output khusus.

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

Keluaran:

.text-opacity-25 { --bs-text-alpha: .25; }
.text-opacity-50 { --bs-text-alpha: .5; }
.text-opacity-75 { --bs-text-alpha: .75; }
.text-opacity-100 { --bs-text-alpha: 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

All utilities generated by the API include !important to ensure they override components and modifier classes as intended. You can toggle this setting globally with the $enable-important-utilities variable (defaults to true).

Using the API

Now that you’re familiar with how the utilities API works, learn how to add your own custom classes and modify our default utilities.

Override utilities

Override existing utilities by using the same key. For example, if you want additional responsive overflow utility classes, you can do this:

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

Add utilities

New utilities can be added to the default $utilities map with a map-merge. Make sure our required Sass files and _utilities.scss are imported first, then use the map-merge to add your additional utilities. For example, here’s how to add a responsive cursor utility with three values.

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

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

@import "bootstrap/scss/utilities/api";

Modify utilities

Modify existing utilities in the default $utilities map with map-get and map-merge functions. In the example below, we’re adding an additional value to the width utilities. Start with an initial map-merge and then specify which utility you want to modify. From there, fetch the nested "width" map with map-get to access and modify the utility’s options and values.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@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%),
        ),
      ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

Enable responsive

You can enable responsive classes for an existing set of utilities that are not currently responsive by default. For example, to make the border classes responsive:

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

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

This will now generate responsive variations of .border and .border-0 for each breakpoint. Your generated CSS will look like this:

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

Rename utilities

Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting class of a given utility—for example, to rename .ms-* utilities to oldish .ml-*:

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

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

@import "bootstrap/scss/utilities/api";

Remove utilities

Remove any of the default utilities with the map-remove() Sass function.

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

// Remove multiple utilities with a comma-separated list
$utilities: map-remove($utilities, "width", "float");

@import "bootstrap/scss/utilities/api";

You can also use the map-merge() Sass function and set the group key to null to remove the utility.

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

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

@import "bootstrap/scss/utilities/api";

Add, remove, modify

You can add, remove, and modify many utilities all at once with the map-merge() Sass function. Here’s how you can combine the previous examples into one larger map.

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

$utilities: map-merge(
  $utilities,
  (
    // Remove the `width` utility
    "width": null,

    // Make an existing utility responsive
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),

    // Add new utilities
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

@import "bootstrap/scss/utilities/api";

Remove utility in 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 .