API Utiliti
API utiliti ialah alat berasaskan Sass untuk menjana kelas utiliti.
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 $utilities
mengandungi semua utiliti kami dan kemudian digabungkan dengan $utilities
peta 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, ia tidak disusun. |
class |
Pilihan | null | Nama kelas yang dihasilkan. Jika tidak disediakan dan property merupakan tatasusunan rentetan, class akan lalai kepada elemen pertama property tatasusunan. |
css-var |
Pilihan | false |
Boolean untuk menjana pembolehubah CSS dan bukannya peraturan CSS. |
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 $utilities
pembolehubah dalam _utilities.scss
lembaran 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 property
mesti ditetapkan untuk sebarang utiliti dan ia mesti mengandungi sifat CSS yang sah. Sifat ini digunakan dalam set peraturan utiliti yang dijana. Apabila class
kunci ditinggalkan, ia juga berfungsi sebagai nama kelas lalai. Pertimbangkan text-decoration
utiliti:
$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 values
kekunci untuk menentukan nilai untuk yang ditentukan property
harus 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-decoration
utiliti :
values: none underline line-through
Sebagai peta, seperti dengan opacity
utiliti :
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
Sebagai pembolehubah Sass yang menetapkan senarai atau peta, seperti dalam position
utiliti kami :
values: $position-values
Kelas
Gunakan class
pilihan 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; }
Utiliti pembolehubah CSS
Tetapkan css-var
pilihan boolean kepada true
dan API akan menjana pembolehubah CSS setempat untuk pemilih yang diberikan dan bukannya property: value
peraturan biasa. Pertimbangkan .text-opacity-*
utiliti kami:
$utilities: (
"text-opacity": (
css-var: true,
class: text-opacity,
values: (
25: .25,
50: .5,
75: .75,
100: 1
)
),
);
Pengeluaran:
.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; }
Pembolehubah CSS tempatan
Gunakan local-vars
pilihan 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 state
pilihan untuk menjana variasi kelas pseudo. Contoh kelas pseudo ialah :hover
dan :focus
. Apabila senarai keadaan disediakan, nama kelas dicipta untuk kelas pseudo itu. Contohnya, untuk menukar kelegapan pada tuding, tambah state: hover
dan anda akan mendapat .opacity-hover:hover
dalam 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 responsive
boolean 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 print
pilihan 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 !important
untuk memastikan ia mengatasi komponen dan kelas pengubah suai seperti yang dimaksudkan. Anda boleh menogol tetapan ini secara global dengan $enable-important-utilities
pembolehubah (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 $utilities
peta lalai dengan map-merge
. Pastikan fail Sass kami yang diperlukan dan _utilities.scss
diimport terlebih dahulu, kemudian gunakan map-merge
untuk menambah utiliti tambahan anda. Sebagai contoh, berikut ialah cara menambah cursor
utiliti 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 $utilities
peta lalai dengan map-get
dan map-merge
fungsi. Dalam contoh di bawah, kami menambah nilai tambahan pada width
utiliti. Mulakan dengan huruf awal map-merge
dan kemudian nyatakan utiliti yang ingin anda ubah suai. Dari sana, ambil peta bersarang "width"
dengan map-get
untuk 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 border
kelas 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 .border
dan .border-0
untuk 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 class
utiliti 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 width
utiliti kami, buat $utilities
map-merge
dan tambah "width": null
dalam.
@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 rtl
pilihan 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
.