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:hoverאת ה-CSS המהודר שלך.

צריך מחלקות פסאודו מרובות? השתמש ברשימה מופרדת ברווחים של מצבים: 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; }

תגובה

הוסף את ה- responsiveboolean כדי ליצור כלי עזר מגיבים (למשל, .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, הודות להנחיית הבקרה של RTLCSSremove .