API Utiliti

API utiliti ialah alat berasaskan Sass untuk menjana kelas utiliti.

Pada halaman ini

Utiliti Bootstrap dijana dengan API utiliti kami dan boleh digunakan untuk mengubah suai atau melanjutkan set lalai kelas utiliti kami melalui Sass. API utiliti kami adalah berdasarkan siri peta dan fungsi Sass untuk menjana keluarga kelas dengan pelbagai pilihan. Jika anda tidak biasa dengan peta Sass, baca dokumen rasmi Sass untuk bermula.

Peta $utilitiesmengandungi semua utiliti kami dan kemudian digabungkan dengan $utilitiespeta tersuai anda, jika ada. Peta utiliti mengandungi senarai berkunci kumpulan utiliti yang menerima pilihan berikut:

Pilihan	taip	Nilai asal	Penerangan
`property`	Diperlukan	–	Nama harta, ini boleh menjadi rentetan atau tatasusunan rentetan (cth, pelapik mendatar atau jidar).
`values`	Diperlukan	–	Senarai nilai, atau peta jika anda tidak mahu nama kelas sama dengan nilai. Jika `null`digunakan sebagai kunci peta, `class`ia tidak disertakan pada nama kelas.
`class`	Pilihan	null	Nama kelas yang dihasilkan. Jika tidak disediakan dan `property`merupakan tatasusunan rentetan, `class`akan lalai kepada elemen pertama `property`tatasusunan. Jika tidak disediakan dan `property`merupakan rentetan, `values`kekunci digunakan untuk `class`nama.
`css-var`	Pilihan	`false`	Boolean untuk menjana pembolehubah CSS dan bukannya peraturan CSS.
`css-variable-name`	Pilihan	null	Nama tersuai tanpa awalan untuk pembolehubah CSS dalam set peraturan.
`local-vars`	Pilihan	null	Peta pembolehubah CSS tempatan untuk dijana sebagai tambahan kepada peraturan CSS.
`state`	Pilihan	null	Senarai varian kelas pseudo (cth, `:hover`atau `:focus`) untuk dijana.
`responsive`	Pilihan	`false`	Boolean yang menunjukkan jika kelas responsif perlu dijana.
`rfs`	Pilihan	`false`	Boolean untuk mendayakan penskalaan semula bendalir dengan RFS .
`print`	Pilihan	`false`	Boolean menunjukkan jika kelas cetakan perlu dijana.
`rtl`	Pilihan	`true`	Boolean menunjukkan sama ada utiliti harus disimpan dalam RTL.

API menjelaskan

Semua pembolehubah utiliti ditambahkan pada $utilitiespembolehubah dalam _utilities.scsslembaran gaya kami. Setiap kumpulan utiliti kelihatan seperti ini:

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

Yang menghasilkan yang berikut:

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

Harta benda

Kunci yang diperlukan propertymesti ditetapkan untuk sebarang utiliti dan ia mesti mengandungi sifat CSS yang sah. Sifat ini digunakan dalam set peraturan utiliti yang dijana. Apabila classkunci ditinggalkan, ia juga berfungsi sebagai nama kelas lalai. Pertimbangkan text-decorationutiliti:

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

Pengeluaran:

.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 valueskekunci untuk menentukan nilai untuk yang ditentukan propertyharus digunakan dalam nama dan peraturan kelas yang dijana. Boleh menjadi senarai atau peta (ditetapkan dalam utiliti atau dalam pembolehubah Sass).

Sebagai senarai, seperti dengan text-decorationutiliti :

values: none underline line-through

Sebagai peta, seperti dengan opacityutiliti :

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

Sebagai pembolehubah Sass yang menetapkan senarai atau peta, seperti dalam positionutiliti kami :

values: $position-values

Kelas

Gunakan classpilihan untuk menukar awalan kelas yang digunakan dalam CSS yang disusun. Sebagai contoh, untuk menukar daripada .opacity-*kepada .o-*:

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

Pengeluaran:

.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, menjana kelas untuk setiap valueskunci:

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

Pengeluaran:

.visible { visibility: visible !important; }
.invisible { visibility: hidden !important; }

Utiliti pembolehubah CSS

Tetapkan css-varpilihan boolean kepada truedan API akan menjana pembolehubah CSS setempat untuk pemilih yang diberikan dan bukannya property: valueperaturan biasa. Tambah pilihan css-variable-nameuntuk menetapkan nama pembolehubah CSS yang berbeza daripada nama kelas.

Pertimbangkan .text-opacity-*utiliti kami. Jika kami menambah css-variable-namepilihan, kami akan mendapat output tersuai.

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

Pengeluaran:

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

Pembolehubah CSS tempatan

Gunakan local-varspilihan untuk menentukan peta Sass yang akan menjana pembolehubah CSS tempatan dalam set peraturan kelas utiliti. Sila ambil perhatian bahawa ia mungkin memerlukan kerja tambahan untuk menggunakan pembolehubah CSS tempatan tersebut dalam peraturan CSS yang dijana. Sebagai contoh, pertimbangkan .bg-*utiliti kami:

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

Pengeluaran:

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

negeri

Gunakan statepilihan untuk menjana variasi kelas pseudo. Contoh kelas pseudo ialah :hoverdan :focus. Apabila senarai keadaan disediakan, nama kelas dicipta untuk kelas pseudo itu. Contohnya, untuk menukar kelegapan pada tuding, tambah state: hoverdan anda akan mendapat .opacity-hover:hoverdalam CSS terkumpul anda.

Perlukan berbilang kelas pseudo? Gunakan senarai keadaan yang diasingkan ruang: state: hover focus.

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

Pengeluaran:

.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 menjana utiliti responsif (cth, .opacity-md-25) merentas semua titik putus .

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

Pengeluaran:

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

Cetak

Mendayakan printpilihan juga akan menjana kelas utiliti untuk cetakan, yang hanya digunakan dalam @media print { ... }pertanyaan media.

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

Pengeluaran:

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

Kepentingan

Semua utiliti yang dijana oleh API termasuk !importantuntuk memastikan ia mengatasi komponen dan kelas pengubah suai seperti yang dimaksudkan. Anda boleh menogol tetapan ini secara global dengan $enable-important-utilitiespembolehubah (lalai kepada true).

Menggunakan API

Memandangkan anda sudah biasa dengan cara API utiliti berfungsi, ketahui cara menambah kelas tersuai anda sendiri dan mengubah suai utiliti lalai kami.

Tolak utiliti

Gantikan utiliti sedia ada dengan menggunakan kekunci yang sama. Sebagai contoh, jika anda mahukan kelas utiliti limpahan responsif tambahan, anda boleh melakukan ini:

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

Tambah utiliti

Utiliti baharu boleh ditambah pada $utilitiespeta lalai dengan map-merge. Pastikan fail Sass kami yang diperlukan dan _utilities.scssdiimport terlebih dahulu, kemudian gunakan map-mergeuntuk menambah utiliti tambahan anda. Sebagai contoh, berikut ialah cara menambah cursorutiliti responsif dengan tiga nilai.

@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";

Ubah suai utiliti

Ubah suai utiliti sedia ada dalam $utilitiespeta lalai dengan map-getdan map-mergefungsi. Dalam contoh di bawah, kami menambah nilai tambahan pada widthutiliti. Mulakan dengan huruf awal map-mergedan kemudian nyatakan utiliti yang ingin anda ubah suai. Dari sana, ambil peta bersarang "width"dengan map-getuntuk mengakses dan mengubah suai pilihan dan nilai utiliti.

@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";

Dayakan responsif

Anda boleh mendayakan kelas responsif untuk set utiliti sedia ada yang tidak responsif secara lalai pada masa ini. Sebagai contoh, untuk menjadikan borderkelas responsif:

@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";

Ini kini akan menjana variasi responsif .borderdan .border-0untuk setiap titik putus. CSS yang anda hasilkan akan kelihatan 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 { ... }
}

Namakan semula utiliti

Tiada utiliti v4, atau digunakan dengan konvensyen penamaan lain? API utiliti boleh digunakan untuk mengatasi hasil classutiliti yang diberikan—contohnya, untuk menamakan semula .ms-*utiliti kepada lama .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";

Alih keluar utiliti

Alih keluar mana-mana utiliti lalai dengan map-remove()fungsi Sass .

@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";

Anda juga boleh menggunakan map-merge()fungsi Sass dan tetapkan kunci kumpulan nulluntuk mengalih keluar utiliti.

@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";

Tambah, alih keluar, ubah suai

Anda boleh menambah, mengalih keluar dan mengubah suai banyak utiliti serentak dengan map-merge()fungsi Sass . Begini cara anda boleh menggabungkan contoh sebelumnya menjadi satu peta yang lebih besar.

@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";

Alih keluar utiliti dalam RTL

Sesetengah kes tepi menyukarkan penggayaan RTL , seperti pemisah baris dalam bahasa Arab. Oleh itu utiliti boleh digugurkan daripada output RTL dengan menetapkan rtlpilihan untuk false:

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

Pengeluaran:

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

Ini tidak mengeluarkan apa-apa dalam RTL, terima kasih kepada arahan kawalan RTLCSSremove .