Chuyển đến nội dung chính Chuyển đến điều hướng tài liệu
in English

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.

Trên trang này

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 $utilitiesbả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 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 Biến cho tên lớp nếu bạn không muốn nó giống với thuộc tính. Trong trường hợp bạn không cung cấp classkhóa và propertykhóa là một mảng chuỗi, tên lớp sẽ là phần tử đầu tiên của propertymảng.
state Không bắt buộc Danh sách các biến thể lớp giả thích :hoverhoặc :focusđể tạo cho tiện ích. Không có giá trị mặc định.
responsive Không bắt buộc Boolean cho biết nếu các lớp đáp ứng cần được tạo. falsetheo mặc định.
rfs Không bắt buộc Boolean để cho phép thay đổi tỷ lệ chất lỏng. Hãy xem trang RFS để tìm hiểu cách thức hoạt động của nó. falsetheo mặc định.
print Không bắt buộc Boolean cho biết có cần tạo các lớp in hay không. falsetheo mặc định.
rtl Không bắt buộc Boolean cho biết nếu tiện ích nên được giữ trong RTL. truetheo mặc định.

API giải thích

Tất cả các biến tiện ích được thêm vào $utilitiesbiế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ả đầu ra sau đây:

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

Tiền tố lớp tùy chỉnh

Sử dụng classtùy chọn để thay đổi tiền tố lớp được sử dụng trong CSS đã biên dịch:

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

Đầu ra:

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

Những trạng thái

Sử dụng statetùy chọn để tạo các biến thể giả lớp. Các lớp giả ví dụ là :hovervà :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: hovervà bạn sẽ nhận được .opacity-hover:hoverCSS đã biên dịch của mình.

Cần nhiều lớp giả? state: hover focusSử 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; }

Các tiện ích đáp ứng

Thêm responsiveboolean để 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; }
}

Thay đổi 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,
  ),
);

Bật printtù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-utilitiesbiế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.

Thêm tiện ích

Các tiện ích mới có thể được thêm vào bản đồ mặc định $utilitiesvớ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 cursortiệ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 $utilitiesbản đồ mặc định với map-getvà map-mergecá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 widthtiện ích. Bắt đầu với một chữ cái đầu map-mergevà 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 borderlớ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 .bordervà .border-0cho 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ả classcủ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 widthtiện ích của chúng tôi, hãy tạo $utilities map-mergevà thêm "width": nullvà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 rtltù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 .