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	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 đồ, `class`không được thêm vào trước tên lớp.
`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. Nếu không được cung cấp và `property`là một chuỗi, các `values`khóa được sử dụng cho các `class`tên.
`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.
`css-variable-name`	Không bắt buộc	vô giá trị	Tên tùy chỉnh không có tiền tố cho biến CSS bên trong bộ quy tắc.
`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 $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; }

Tài sản

Khóa bắt buộc propertyphả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 classkhóa bị bỏ qua, nó cũng đóng vai trò là tên lớp mặc định. Xem xét các text-decorationtiệ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 valueskhóa để chỉ định giá trị nào cho giá trị được chỉ định propertysẽ đượ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-decorationcác tiện ích :

values: none underline line-through

Dưới dạng bản đồ, giống như với opacitycá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 positiontiện ích của chúng tôi :

values: $position-values

Lớp

Sử dụng classtù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; }

Nếu class: null, tạo các lớp cho mỗi valueskhóa:

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

Đầu ra:

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

Tiện ích biến CSS

Đặt css-vartùy chọn boolean thành truevà API sẽ tạo các biến CSS cục bộ cho bộ chọn nhất định thay vì các property: valuequy tắc thông thường. Thêm tùy chọn css-variable-nameđể đặt tên biến CSS khác với tên lớp.

Hãy xem xét các .text-opacity-*tiện ích của chúng tôi. Nếu chúng tôi thêm css-variable-nametùy chọn, chúng tôi sẽ nhận được đầu ra tùy chỉnh.

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

Đầu ra:

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

Các biến CSS cục bộ

Sử dụng local-varstù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 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; }

Phản ứng nhanh nhẹn

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

In

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.

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

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

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

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

Xóa các tiện ích

Loại bỏ bất kỳ tiện ích mặc định nào bằng map-remove()chức năng 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";

Bạn cũng có thể sử dụng map-merge()chức năng Sass và đặt khóa nhóm nullđể xóa tiện ích.

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

Thêm, xóa, sửa đổi

Bạn có thể thêm, xóa và sửa đổi nhiều tiện ích cùng một lúc với map-merge()chức năng Sass . Đây là cách bạn có thể kết hợp các ví dụ trước đó thành một bản đồ lớn hơn.

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

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 .