Utility API

Utility API یک ابزار مبتنی بر Sass برای تولید کلاس های ابزار است.

در این صفحه

ابزارهای بوت استرپ با 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`	Boolean نشان می دهد که آیا کلاس های پاسخگو باید تولید شوند یا خیر.
`rfs`	اختیاری	`false`	Boolean برای فعال کردن مقیاس مجدد مایع با RFS .
`print`	اختیاری	`false`	Boolean نشان می‌دهد که آیا کلاس‌های چاپی باید تولید شوند یا خیر.
`rtl`	اختیاری	`true`	Boolean نشان می دهد که آیا ابزار باید در 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; }

If ، برای هر یک از کلیدها 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گزینه boolean را روی آن تنظیم کنید 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. هنگامی که لیستی از حالت ها ارائه می شود، نام کلاس ها برای آن شبه کلاس ایجاد می شود. به عنوان مثال، برای تغییر opacity در شناور، اضافه کنید 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; }

پاسخگو

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

اکنون که با نحوه کار Utilities 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 را از دست داده‌اید یا از نام‌گذاری دیگری استفاده کرده‌اید؟ از Utilities API می‌توان برای نادیده گرفتن نتایج حاصل classاز یک ابزار معین استفاده کرد - برای مثال، برای تغییر نام ابزار .ms-*به قدیمی .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 */

به لطف دستورالعمل کنترل RTLCSSremove ، این چیزی در RTL خروجی نمی‌دهد .