Utility API

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

در این صفحه

ابزارهای بوت استرپ با API ابزار ما تولید می شوند و می توان از آنها برای اصلاح یا گسترش مجموعه پیش فرض کلاس های ابزار از طریق Sass استفاده کرد. API ابزار ما بر اساس یک سری نقشه ها و توابع Sass برای تولید خانواده هایی از کلاس ها با گزینه های مختلف است. اگر با نقشه های Sass آشنا نیستید، برای شروع، اسناد رسمی Sass را بخوانید .

نقشه $utilitiesشامل همه ابزارهای ما است و در صورت وجود، بعداً با $utilitiesنقشه سفارشی شما ادغام می شود. نقشه ابزار شامل یک لیست کلیدی از گروه های ابزار است که گزینه های زیر را می پذیرد:

گزینه	تایپ کنید	شرح
`property`	ضروری	نام ویژگی، این می تواند یک رشته یا آرایه ای از رشته ها باشد (به عنوان مثال، لایه های افقی یا حاشیه).
`values`	ضروری	لیست مقادیر یا نقشه اگر نمی خواهید نام کلاس با مقدار یکسان باشد. اگر `null`به عنوان کلید نقشه استفاده می شود، کامپایل نمی شود.
`class`	اختیاری	متغیر برای نام کلاس اگر نمی خواهید با ویژگی یکسان باشد. در صورتی که کلید را ارائه نکنید `class`و `property`کلید آرایه ای از رشته ها باشد، نام کلاس اولین عنصر `property`آرایه خواهد بود.
`state`	اختیاری	فهرست انواع شبه کلاس مانند `:hover`یا `:focus`برای تولید برای ابزار. بدون مقدار پیش فرض
`responsive`	اختیاری	Boolean نشان می دهد که آیا کلاس های پاسخگو باید تولید شوند یا خیر. `false`به صورت پیش فرض.
`rfs`	اختیاری	Boolean برای فعال کردن مقیاس مجدد مایع. به صفحه RFS نگاهی بیندازید تا بدانید چگونه این کار می کند. `false`به صورت پیش فرض.
`print`	اختیاری	Boolean نشان می‌دهد که آیا کلاس‌های چاپی باید تولید شوند یا خیر. `false`به صورت پیش فرض.
`rtl`	اختیاری	Boolean نشان می دهد که آیا ابزار باید در RTL نگه داشته شود. `true`به صورت پیش فرض.

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

پیشوند کلاس سفارشی

از classگزینه تغییر پیشوند کلاس استفاده شده در CSS کامپایل شده استفاده کنید:

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

خروجی:

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

ایالت ها

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

تغییر آب و برق

با استفاده از همان کلید، برنامه های کاربردی موجود را لغو کنید. به عنوان مثال، اگر می‌خواهید کلاس‌های ابزار سرریز پاسخگوی اضافی را بخواهید، می‌توانید این کار را انجام دهید:

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

ابزارهای چاپ

با فعال کردن این 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با یک علامت به نقشه پیش فرض اضافه کرد map-merge. مطمئن شوید که فایل‌های Sass مورد نیاز ما _utilities.scssابتدا وارد شده‌اند، سپس از آن map-mergeبرای اضافه کردن ابزارهای کمکی اضافی خود استفاده کنید. به عنوان مثال، در اینجا نحوه اضافه کردن یک cursorابزار پاسخگو با سه مقدار آورده شده است.

@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,
    )
  )
);

برنامه های کاربردی را اصلاح کنید

ابزارهای موجود در $utilitiesنقشه پیش فرض با map-getو map-mergeتوابع را تغییر دهید. در مثال زیر، ما یک مقدار اضافی به برنامه های widthکاربردی اضافه می کنیم. با یک حرف اول شروع کنید map-mergeو سپس مشخص کنید که کدام ابزار را می خواهید تغییر دهید. "width"از آنجا، نقشه تودرتو را واکشی کنید map-getتا به گزینه‌ها و مقادیر ابزار دسترسی داشته باشید و آن‌ها را تغییر دهید.

@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%),
        ),
      ),
    ),
  )
);

پاسخگو را فعال کنید

می‌توانید کلاس‌های پاسخگو را برای مجموعه‌ای از ابزارهای موجود که در حال حاضر به‌طور پیش‌فرض پاسخگو نیستند، فعال کنید. به عنوان مثال، برای اینکه borderکلاس ها پاسخگو باشند:

@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 ),
    ),
  )
);

این اکنون تغییرات پاسخگوی .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/utilities";

$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

برنامه های کاربردی را حذف کنید

با تنظیم کلید گروه روی، هر یک از ابزارهای پیش فرض را حذف کنید null. به عنوان مثال، برای حذف همه widthابزارهای ما، یک را ایجاد کرده $utilities map-mergeو "width": nullدرون آن را اضافه کنید.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

برنامه کاربردی را در 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 خروجی نمی دهد .