ยูทิลิตี้ API

API ยูทิลิตี้เป็นเครื่องมือที่ใช้ Sass เพื่อสร้างคลาสยูทิลิตี้

ในหน้านี้

ยูทิลิตี้ Bootstrap ถูกสร้างขึ้นด้วยยูทิลิตี้ API ของเรา และสามารถใช้เพื่อแก้ไขหรือขยายชุดคลาสยูทิลิตี้เริ่มต้นของเราผ่าน Sass ยูทิลิตี API ของเราอิงตามชุดของแผนที่ Sass และฟังก์ชันสำหรับสร้างกลุ่มคลาสที่มีตัวเลือกต่างๆ หากคุณไม่คุ้นเคยกับแผนที่ Sass โปรดอ่านเอกสาร Sass อย่างเป็นทางการเพื่อเริ่มต้น

แผนที่ประกอบด้วย ระบบ$utilitiesสาธารณูปโภคทั้งหมดของเราและจะรวมเข้ากับ$utilitiesแผนที่ที่กำหนดเองของคุณในภายหลัง หากมี แผนผังยูทิลิตี้ประกอบด้วยรายการคีย์ของกลุ่มยูทิลิตี้ซึ่งยอมรับตัวเลือกต่อไปนี้:

ตัวเลือก	พิมพ์	ค่าเริ่มต้น	คำอธิบาย
`property`	ที่จำเป็น	–	ชื่อของคุณสมบัติ อาจเป็นสตริงหรืออาร์เรย์ของสตริง (เช่น ช่องว่างภายในแนวนอนหรือระยะขอบ)
`values`	ที่จำเป็น	–	รายการค่า หรือแผนที่ หากคุณไม่ต้องการให้ชื่อคลาสเหมือนกับค่า ถ้า`null`ใช้เป็นคีย์แผนที่`class`จะไม่ถูกเติมหน้าชื่อคลาส
`class`	ไม่จำเป็น	โมฆะ	ชื่อของคลาสที่สร้างขึ้น หากไม่ระบุและ`property`เป็นอาร์เรย์ของสตริง`class`จะมีค่าเริ่มต้นเป็นองค์ประกอบแรกของ`property`อาร์เรย์ หากไม่ระบุและ`property`เป็นสตริง`values`คีย์จะใช้สำหรับ`class`ชื่อ
`css-var`	ไม่จำเป็น	`false`	บูลีนเพื่อสร้างตัวแปร CSS แทนกฎ CSS
`css-variable-name`	ไม่จำเป็น	โมฆะ	ชื่อที่ไม่มีคำนำหน้าที่กำหนดเองสำหรับตัวแปร CSS ภายในชุดกฎ
`local-vars`	ไม่จำเป็น	โมฆะ	แมปของตัวแปร CSS ในเครื่องเพื่อสร้างเพิ่มเติมจากกฎ CSS
`state`	ไม่จำเป็น	โมฆะ	รายการตัวแปรคลาสหลอก (เช่น`:hover`หรือ`:focus`) ที่จะสร้าง
`responsive`	ไม่จำเป็น	`false`	บูลีนที่ระบุว่าควรสร้างคลาสที่ตอบสนองหรือไม่
`rfs`	ไม่จำเป็น	`false`	บูลีนเพื่อเปิดใช้ งานการปรับขนาดของเหลว ด้วยRFS
`print`	ไม่จำเป็น	`false`	บูลีนระบุว่าจำเป็นต้องสร้างคลาสการพิมพ์หรือไม่
`rtl`	ไม่จำเป็น	`true`	บูลีนระบุว่าควรเก็บยูทิลิตี้ไว้ใน RTL หรือไม่

API อธิบาย

ตัวแปรยูทิลิตี้ทั้งหมดจะถูกเพิ่มลงใน$utilitiesตัวแปรภายใน_utilities.scssสไตล์ชีต ของเรา ยูทิลิตี้แต่ละกลุ่มมีลักษณะดังนี้:

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

ซึ่งให้ผลลัพธ์ดังต่อไปนี้:

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

คุณสมบัติ

ต้องpropertyตั้งค่าคีย์ที่จำเป็นสำหรับยูทิลิตี้ใดๆ และต้องมีคุณสมบัติ CSS ที่ถูกต้อง คุณสมบัตินี้ถูกใช้ในชุดกฎของยูทิลิตี้ที่สร้างขึ้น เมื่อclassคีย์ถูกละเว้น มันจะทำหน้าที่เป็นชื่อคลาสดีฟอลต์ พิจารณาtext-decorationยูทิลิตี้:

$utilities: (
  "text-decoration": (
    property: text-decoration,
    values: none underline line-through
  )
);

เอาท์พุท:

.text-decoration-none { text-decoration: none !important; }
.text-decoration-underline { text-decoration: underline !important; }
.text-decoration-line-through { text-decoration: line-through !important; }

ค่านิยม

ใช้valuesคีย์เพื่อระบุว่าpropertyควรใช้ค่าใดในชื่อคลาสและกฎที่สร้างขึ้น สามารถเป็นรายการหรือแผนที่ (ตั้งค่าในยูทิลิตี้หรือในตัวแปร Sass)

เป็นรายการ เช่นเดียวกับtext-decorationยูทิลิตี้ :

values: none underline line-through

เป็นแผนที่ เช่นเดียวกับopacityสาธารณูปโภค :

values: (
  0: 0,
  25: .25,
  50: .5,
  75: .75,
  100: 1,
)

เป็นตัวแปร Sass ที่ตั้งค่ารายการหรือแผนที่ เช่นเดียวกับในpositionยูทิลิตี้ ของเรา :

values: $position-values

ระดับ

ใช้classตัวเลือกเพื่อเปลี่ยนคำนำหน้าคลาสที่ใช้ใน CSS ที่คอมไพล์แล้ว ตัวอย่างเช่น หากต้องการเปลี่ยนจาก.opacity-*เป็น.o-*:

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

เอาท์พุท:

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

ถ้าclass: null, สร้างคลาสสำหรับแต่ละvaluesคีย์:

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

เอาท์พุท:

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

ยูทิลิตี้ตัวแปร CSS

ตั้งค่าcss-varตัวเลือกบูลีนเป็นtrueและ API จะสร้างตัวแปร CSS ในเครื่องสำหรับตัวเลือกที่กำหนดแทนproperty: valueกฎ ปกติ เพิ่มตัวเลือกcss-variable-nameเพื่อตั้งชื่อตัวแปร CSS ที่แตกต่างจากชื่อคลาส

พิจารณา.text-opacity-*สาธารณูปโภค ของเรา หากเราเพิ่มcss-variable-nameตัวเลือก เราจะได้ผลลัพธ์ที่กำหนดเอง

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

เอาท์พุท:

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

ตัวแปร CSS ในเครื่อง

ใช้local-varsตัวเลือกเพื่อระบุแมป Sass ที่จะสร้างตัวแปร CSS ภายในชุดกฎของคลาสยูทิลิตี้ โปรดทราบว่าอาจต้องมีการทำงานเพิ่มเติมเพื่อใช้ตัวแปร CSS ในเครื่องเหล่านั้นในกฎ CSS ที่สร้างขึ้น ตัวอย่างเช่น พิจารณา.bg-*ยูทิลิตี้ของเรา:

$utilities: (
  "background-color": (
    property: background-color,
    class: bg,
    local-vars: (
      "bg-opacity": 1
    ),
    values: map-merge(
      $utilities-bg-colors,
      (
        "transparent": transparent
      )
    )
  )
);

เอาท์พุท:

.bg-primary {
  --bs-bg-opacity: 1;
  background-color: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity)) !important;
}

รัฐ

ใช้stateตัวเลือกเพื่อสร้างรูปแบบคลาสหลอก ตัวอย่างคลาสหลอกคือ:hoverและ:focus. เมื่อมีการระบุรายการสถานะ ชื่อคลาสจะถูกสร้างขึ้นสำหรับคลาสหลอกนั้น ตัวอย่างเช่น หากต้องการเปลี่ยนความทึบเมื่อวางเมาส์เหนือ ให้เพิ่มstate: hoverแล้วคุณจะได้.opacity-hover:hoverCSS ที่คอมไพล์แล้ว

ต้องการคลาสหลอกหลายคลาส? ใช้รายการสถานะที่คั่นด้วยช่องว่าง: state: hover focus.

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

เอาท์พุท:

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

ตอบสนอง

เพิ่มresponsiveบูลีนเพื่อสร้างยูทิลิตี้ตอบสนอง (เช่น.opacity-md-25) ในทุกจุดสั่งหยุด

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

เอาท์พุท:

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

พิมพ์

การเปิดใช้งานprintตัวเลือกนี้ จะ สร้างคลาสยูทิลิตี้สำหรับการพิมพ์ด้วย ซึ่งจะใช้เฉพาะใน@media print { ... }แบบสอบถามสื่อเท่านั้น

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

เอาท์พุท:

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

ความสำคัญ

ยูทิลิตีทั้งหมดที่สร้างโดย API รวมถึง!importantเพื่อให้แน่ใจว่าจะแทนที่ส่วนประกอบและคลาสตัวปรับแต่งตามที่ตั้งใจไว้ คุณสามารถสลับการตั้งค่านี้ทั่วโลกด้วย$enable-important-utilitiesตัวแปร (ค่าเริ่มต้นเป็นtrue)

การใช้ API

เมื่อคุณคุ้นเคยกับวิธีการทำงานของยูทิลิตี้ API แล้ว ให้เรียนรู้วิธีเพิ่มคลาสที่กำหนดเองและแก้ไขยูทิลิตี้เริ่มต้นของเรา

แทนที่ยูทิลิตี้

แทนที่ยูทิลิตี้ที่มีอยู่โดยใช้คีย์เดียวกัน ตัวอย่างเช่น หากคุณต้องการคลาสยูทิลิตีโอเวอร์โฟลว์แบบตอบสนองเพิ่มเติม คุณสามารถทำได้:

$utilities: (
  "overflow": (
    responsive: true,
    property: overflow,
    values: visible hidden scroll auto,
  ),
);

เพิ่มสาธารณูปโภค

สามารถเพิ่มยูทิลิตี้ใหม่ลงใน$utilitiesแผนที่เริ่มต้นด้วยนามสกุลmap-merge. ตรวจสอบให้แน่ใจว่าไฟล์ Sass ที่จำเป็นของเราและ_utilities.scssนำเข้าก่อน จากนั้นใช้map-mergeเพื่อเพิ่มยูทิลิตี้เพิ่มเติมของคุณ ตัวอย่างเช่น ต่อไปนี้คือวิธีเพิ่มcursorยูทิลิตีแบบตอบสนองด้วยค่าสามค่า

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

แก้ไขยูทิลิตี้

แก้ไขยูทิลิตี้ที่มีอยู่ใน$utilitiesแผนที่เริ่มต้นด้วยmap-getและmap-mergeฟังก์ชั่น ในตัวอย่างด้านล่าง เรากำลังเพิ่มมูลค่าเพิ่มเติมให้กับwidthยูทิลิตี้ เริ่มต้นด้วยชื่อย่อmap-mergeแล้วระบุยูทิลิตี้ที่คุณต้องการแก้ไข จากนั้นดึง"width"แผนที่ ที่ซ้อนกัน map-getเพื่อเข้าถึงและแก้ไขตัวเลือกและค่าของยูทิลิตี้

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

เปิดใช้งานการตอบสนอง

คุณสามารถเปิดใช้งานคลาสที่ตอบสนองสำหรับชุดยูทิลิตี้ที่มีอยู่ซึ่งปัจจุบันไม่ตอบสนองตามค่าเริ่มต้น ตัวอย่างเช่น เพื่อให้borderคลาสตอบสนอง:

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

ซึ่งตอนนี้จะสร้างรูปแบบที่ตอบสนองต่อ.borderและ.border-0สำหรับแต่ละเบรกพอยต์ CSS ที่คุณสร้างขึ้นจะมีลักษณะดังนี้:

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

เปลี่ยนชื่อยูทิลิตี้

ไม่มียูทิลิตี้ v4 หรือใช้กับการตั้งชื่อแบบอื่น? ยูทิลิตี API สามารถใช้เพื่อแทนที่ผลลัพธ์classของยูทิลิตีที่กำหนด ตัวอย่างเช่น เพื่อเปลี่ยนชื่อ.ms-*ยูทิลิตีเป็น oldish .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";

ลบยูทิลิตี้

ลบยูทิลิตี้เริ่มต้นด้วยฟังก์ชันmap-remove()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";

คุณยังสามารถใช้map-merge()ฟังก์ชัน Sassและตั้งค่าคีย์กลุ่มnullเพื่อนำยูทิลิตี้ออก

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

เพิ่ม ลบ แก้ไข

คุณสามารถเพิ่ม ลบ และแก้ไขยูทิลิตี้ต่างๆ ได้พร้อมกันด้วยฟังก์ชันmap-merge()Sass ต่อไปนี้คือวิธีที่คุณสามารถรวมตัวอย่างก่อนหน้านี้เป็นแผนที่ที่ใหญ่กว่าแผนที่เดียว

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

ลบยูทิลิตี้ใน RTL

เคสขอบบางอันทำให้การจัดรูปแบบ RTL ทำได้ยากเช่น การขึ้นบรรทัดใหม่เป็นภาษาอาหรับ ดังนั้นยูทิลิตี้สามารถหลุดจากเอาต์พุต RTL ได้โดยการตั้งค่าrtlตัวเลือกเป็นfalse:

$utilities: (
  "word-wrap": (
    property: word-wrap word-break,
    class: text,
    values: (break: break-word),
    rtl: false
  ),
);

เอาท์พุท:

/* rtl:begin:remove */
.text-break {
  word-wrap: break-word !important;
  word-break: break-word !important;
}
/* rtl:end:remove */

สิ่งนี้ไม่ได้ส่งออกสิ่งใดใน RTL ต้องขอบคุณRTLCSS control removedirective