API tiện ích
API tiện ích là một công cụ dựa trên Sass để tạo các lớp tiện ích.
Các tiện ích Bootstrap được tạo bằng API tiện ích của chúng tôi và có thể được sử dụng để sửa đổi hoặc mở rộng tập hợp các lớp tiện ích mặc định của chúng tôi thông qua Sass. API tiện ích của chúng tôi dựa trên một loạt các bản đồ và hàm Sass để tạo các họ lớp với nhiều tùy chọn khác nhau. Nếu bạn không quen với bản đồ Sass, hãy đọc các tài liệu chính thức của Sass để bắt đầu.
Bản $utilities
đồ chứa tất cả các tiện ích của chúng tôi và sau đó được hợp nhất với $utilities
bản đồ tùy chỉnh của bạn, nếu có. Bản đồ tiện ích chứa một danh sách có khóa các nhóm tiện ích chấp nhận các tùy chọn sau:
Quyền mua | Loại hình | Giá trị mặc định | Sự mô tả |
---|---|---|---|
property |
Yêu cầu | - | Tên của thuộc tính, đây có thể là một chuỗi hoặc một mảng các chuỗi (ví dụ: khoảng đệm ngang hoặc lề). |
values |
Yêu cầu | - | Danh sách các giá trị hoặc một bản đồ nếu bạn không muốn tên lớp giống với giá trị. Nếu null được sử dụng làm khóa bản đồ, nó không được biên dịch. |
class |
Không bắt buộc | vô giá trị | Tên của lớp được tạo. Nếu không được cung cấp và property là một mảng chuỗi, class sẽ mặc định là phần tử đầu tiên của property mảng. |
css-var |
Không bắt buộc | false |
Boolean để tạo các biến CSS thay vì các quy tắc CSS. |
local-vars |
Không bắt buộc | vô giá trị | Bản đồ các biến CSS cục bộ để tạo ngoài các quy tắc CSS. |
state |
Không bắt buộc | vô giá trị | Danh sách các biến thể lớp giả (ví dụ: :hover hoặc :focus ) để tạo. |
responsive |
Không bắt buộc | false |
Boolean cho biết có nên tạo các lớp đáp ứng hay không. |
rfs |
Không bắt buộc | false |
Boolean để cho phép thay đổi tỷ lệ chất lỏng với RFS . |
print |
Không bắt buộc | false |
Boolean cho biết có cần tạo các lớp in hay không. |
rtl |
Không bắt buộc | true |
Boolean cho biết nếu tiện ích nên được giữ trong RTL. |
API giải thích
Tất cả các biến tiện ích được thêm vào $utilities
biến trong biểu _utilities.scss
định kiểu của chúng tôi. Mỗi nhóm tiện ích trông giống như sau:
$utilities: (
"opacity": (
property: opacity,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Kết quả nào sau đây:
.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }
Tài sản
Khóa bắt buộc property
phải được đặt cho bất kỳ tiện ích nào và nó phải chứa thuộc tính CSS hợp lệ. Thuộc tính này được sử dụng trong bộ quy tắc của tiện ích đã tạo. Khi class
khóa bị bỏ qua, nó cũng đóng vai trò là tên lớp mặc định. Xem xét các text-decoration
tiện ích:
$utilities: (
"text-decoration": (
property: text-decoration,
values: none underline line-through
)
);
Đầu ra:
.text-decoration-none { text-decoration: none !important; }
.text-decoration-underline { text-decoration: underline !important; }
.text-decoration-line-through { text-decoration: line-through !important; }
Giá trị
Sử dụng values
khóa để chỉ định giá trị nào cho giá trị được chỉ định property
sẽ được sử dụng trong các quy tắc và tên lớp đã tạo. Có thể là một danh sách hoặc bản đồ (đặt trong các tiện ích hoặc trong một biến Sass).
Dưới dạng một danh sách, giống như với text-decoration
các tiện ích :
values: none underline line-through
Dưới dạng bản đồ, giống như với opacity
các tiện ích :
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
Là một biến Sass đặt danh sách hoặc bản đồ, như trong các position
tiện ích của chúng tôi :
values: $position-values
Lớp
Sử dụng class
tùy chọn để thay đổi tiền tố lớp được sử dụng trong CSS đã biên dịch. Ví dụ, để thay đổi từ .opacity-*
thành .o-*
:
$utilities: (
"opacity": (
property: opacity,
class: o,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Đầu ra:
.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; }
Tiện ích biến CSS
Đặt css-var
tùy chọn boolean thành true
và API sẽ tạo các biến CSS cục bộ cho bộ chọn nhất định thay vì các property: value
quy tắc thông thường. Xem xét các .text-opacity-*
tiện ích của chúng tôi:
$utilities: (
"text-opacity": (
css-var: true,
class: text-opacity,
values: (
25: .25,
50: .5,
75: .75,
100: 1
)
),
);
Đầu ra:
.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; }
Các biến CSS cục bộ
Sử dụng local-vars
tùy chọn để chỉ định một bản đồ Sass sẽ tạo ra các biến CSS cục bộ trong bộ quy tắc của lớp tiện ích. Xin lưu ý rằng nó có thể yêu cầu công việc bổ sung để sử dụng các biến CSS cục bộ đó trong các quy tắc CSS đã tạo. Ví dụ: hãy xem xét các .bg-*
tiện ích của chúng tôi:
$utilities: (
"background-color": (
property: background-color,
class: bg,
local-vars: (
"bg-opacity": 1
),
values: map-merge(
$utilities-bg-colors,
(
"transparent": transparent
)
)
)
);
Đầu ra:
.bg-primary {
--bs-bg-opacity: 1;
background-color: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important;
}
Những trạng thái
Sử dụng state
tùy chọn để tạo các biến thể giả lớp. Các lớp giả ví dụ là :hover
và :focus
. Khi danh sách các trạng thái được cung cấp, các tên lớp sẽ được tạo cho lớp giả đó. Ví dụ: để thay đổi độ mờ khi di chuột, hãy thêm state: hover
và bạn sẽ nhận được .opacity-hover:hover
CSS đã biên dịch của mình.
Cần nhiều lớp giả? state: hover focus
Sử dụng danh sách các trạng thái được phân tách bằng dấu cách :.
$utilities: (
"opacity": (
property: opacity,
class: opacity,
state: hover,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Đầu ra:
.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; }
Phản ứng nhanh nhẹn
Thêm responsive
boolean để tạo các tiện ích đáp ứng (ví dụ .opacity-md-25
:) trên tất cả các điểm ngắt .
$utilities: (
"opacity": (
property: opacity,
responsive: true,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Đầu ra:
.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; }
}
In
Bật print
tùy chọn này cũng sẽ tạo ra các lớp tiện ích cho in, các lớp này chỉ được áp dụng trong @media print { ... }
truy vấn phương tiện.
$utilities: (
"opacity": (
property: opacity,
print: true,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
Đầu ra:
.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; }
}
Tầm quan trọng
Tất cả các tiện ích được tạo bởi API bao gồm !important
để đảm bảo chúng ghi đè các thành phần và lớp bổ trợ như dự định. Bạn có thể chuyển đổi cài đặt này trên toàn cầu bằng $enable-important-utilities
biến (mặc định là true
).
Sử dụng API
Bây giờ bạn đã quen với cách hoạt động của API tiện ích, hãy tìm hiểu cách thêm các lớp tùy chỉnh của riêng bạn và sửa đổi các tiện ích mặc định của chúng tôi.
Ghi đè các tiện ích
Ghi đè các tiện ích hiện có bằng cách sử dụng cùng một khóa. Ví dụ: nếu bạn muốn các lớp tiện ích tràn đáp ứng bổ sung, bạn có thể thực hiện điều này:
$utilities: (
"overflow": (
responsive: true,
property: overflow,
values: visible hidden scroll auto,
),
);
Thêm tiện ích
Các tiện ích mới có thể được thêm vào bản đồ mặc định $utilities
với một map-merge
. Đảm bảo các tệp Sass bắt buộc của chúng tôi và _utilities.scss
được nhập trước, sau đó sử dụng tệp map-merge
để thêm các tiện ích bổ sung của bạn. Ví dụ: đây là cách thêm cursor
tiện ích đáp ứng với ba giá trị.
@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,
)
)
);
Sửa đổi các tiện ích
Sửa đổi các tiện ích hiện có trong $utilities
bản đồ mặc định với map-get
và map-merge
các chức năng. Trong ví dụ dưới đây, chúng tôi đang thêm một giá trị bổ sung cho các width
tiện ích. Bắt đầu với một chữ cái đầu map-merge
và sau đó chỉ định tiện ích nào bạn muốn sửa đổi. "width"
Từ đó, tìm nạp bản đồ lồng nhau map-get
để truy cập và sửa đổi các tùy chọn và giá trị của tiện ích.
@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%),
),
),
),
)
);
Bật phản hồi
Bạn có thể kích hoạt các lớp đáp ứng cho một tập hợp các tiện ích hiện có hiện không đáp ứng theo mặc định. Ví dụ, để làm cho các border
lớp đáp ứng:
@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 ),
),
)
);
Điều này bây giờ sẽ tạo ra các biến thể đáp ứng của .border
và .border-0
cho từng điểm ngắt. CSS được tạo của bạn sẽ trông giống như sau:
.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 { ... }
}
Đổi tên các tiện ích
Thiếu tiện ích v4 hoặc được sử dụng với quy ước đặt tên khác? API tiện ích có thể được sử dụng để ghi đè kết quả class
của một tiện ích nhất định — ví dụ: để đổi tên .ms-*
các tiện ích thành cũ .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 ),
),
)
);
Xóa các tiện ích
Loại bỏ bất kỳ tiện ích mặc định nào bằng cách đặt khóa nhóm thành null
. Ví dụ: để xóa tất cả các width
tiện ích của chúng tôi, hãy tạo $utilities
map-merge
và thêm "width": null
vào bên trong.
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";
$utilities: map-merge(
$utilities,
(
"width": null
)
);
Xóa tiện ích trong RTL
Một số trường hợp cạnh gây khó khăn cho việc tạo kiểu RTL , chẳng hạn như ngắt dòng trong tiếng Ả Rập. Do đó, các tiện ích có thể bị loại bỏ khỏi đầu ra RTL bằng cách đặt rtl
tùy chọn thành false
:
$utilities: (
"word-wrap": (
property: word-wrap word-break,
class: text,
values: (break: break-word),
rtl: false
),
);
Đầu ra:
/* rtl:begin:remove */
.text-break {
word-wrap: break-word !important;
word-break: break-word !important;
}
/* rtl:end:remove */
Điều này không xuất ra bất kỳ thứ gì trong RTL, nhờ chỉ thị điều khiển RTLCSSremove
.