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	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, ia tidak disusun.
`class`	Pilihan	Pembolehubah untuk nama kelas jika anda tidak mahu ia sama dengan harta. Sekiranya anda tidak memberikan `class`kunci dan `property`kunci ialah tatasusunan rentetan, nama kelas akan menjadi elemen pertama `property`tatasusunan.
`state`	Pilihan	Senarai varian kelas pseudo seperti `:hover`atau `:focus`untuk dijana untuk utiliti. Tiada nilai lalai.
`responsive`	Pilihan	Boolean menunjukkan jika kelas responsif perlu dijana. `false`secara lalai.
`rfs`	Pilihan	Boolean untuk membolehkan penskalaan semula bendalir. Sila lihat halaman RFS untuk mengetahui cara ini berfungsi. `false`secara lalai.
`print`	Pilihan	Boolean menunjukkan jika kelas cetakan perlu dijana. `false`secara lalai.
`rtl`	Pilihan	Boolean menunjukkan sama ada utiliti harus disimpan dalam RTL. `true`secara lalai.

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

Awalan kelas tersuai

Gunakan classpilihan untuk menukar awalan kelas yang digunakan dalam CSS yang disusun:

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

Pengeluaran:

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

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

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

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

Utiliti 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.

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/utilities";

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

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/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": map-merge(
      map-get($utilities, "width"),
      (
        values: map-merge(
          map-get(map-get($utilities, "width"), "values"),
          (10: 10%),
        ),
      ),
    ),
  )
);

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/utilities";

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

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/utilities";

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

Alih keluar utiliti

Alih keluar mana-mana utiliti lalai dengan menetapkan kunci kumpulan kepada null. Contohnya, untuk mengalih keluar semua widthutiliti kami, buat $utilities map-mergedan tambah "width": nulldalam.

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

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

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 .