الـ Utility API

الـ Utility API هي أداة تعتمد على الـ Sass لتوليد الفئات (classes) المساعدة.

في هذه الصفحة

يتم توليد الـ Bootstrap utilities باستخدام الـ utility API الخاصة بنا، ويمكن استخدامها لتعديل أو توسيع مجموعة الفئات (classes) المساعدة الافتراضية عبر الـ Sass. تعتمد الـ utility API الخاصة بنا على سلسلة من الـ Sass maps والدوال (functions) لتوليد عائلات من الفئات (classes) بخيارات متنوعة. إذا لم تكن على دراية بـ Sass maps، فاقرأ مستندات Sass الرسمية للبدء.

تحتوي الخريطة (map) $utilities على جميع الـ utilities الخاصة بنا ويتم دمجها لاحقاً مع الخريطة (map) utilities$ المخصصة الخاصة بك، في حال وجودها. تحتوي الخريطة (map) الخاصة بالـ utility على قائمة مفهرسة من مجموعات الـ utility التي تقبل الخيارات التالية:

الإختيار	النوع	القيمة الافتراضية	الوصف
`property`	Required	–	اسم الخاصية، ويمكن أن تكون سلسلة نصية أو مصفوفة من السلاسل النصية (على سبيل المثال، الهوامش الداخلية أو الخارجية الأفقية).
`values`	Required	–	قائمة من القيم، أو خريطة (map) إذا كنت لا تريد أن يكون اسم الفئة (class) هو نفس القيمة. إذا تم استخدام `null` كمفتاح للخريطة (map)، فلن يتم إضافة `class` كبادئة لاسم الفئة.
`class`	Optional	null	اسم الفئة (class) التي سيتم توليدها. إذا لم يتم توفيرها وكانت `property` مصفوفة من السلاسل النصية، فستكون `class` افتراضياً هي العنصر الأول في مصفوفة `property`. إذا لم يتم توفيرها وكانت `property` سلسلة نصية، فسيتم استخدام مفاتيح `values` كأسماء للفئات (classes).
`css-var`	Optional	`false`	قيمة منطقية (Boolean) لتوليد متغيرات CSS بدلاً من قواعد CSS.
`css-variable-name`	Optional	null	اسم مخصص غير مسبوق لمتغير CSS داخل مجموعة القواعد.
`local-vars`	Optional	null	خريطة (map) من متغيرات CSS المحلية التي سيتم توليدها بالإضافة إلى قواعد CSS.
`state`	Optional	null	قائمة من متغيرات الفئات الزائفة (pseudo-class) (مثل `:hover` أو `:focus`) التي سيتم توليدها.
`responsive`	Optional	`false`	قيمة منطقية (Boolean) تشير إلى ما إذا كان يجب توليد فئات متوافقة مع الشاشات (Responsive).
`rfs`	Optional	`false`	قيمة منطقية (Boolean) لتمكين إعادة التحجيم المرن باستخدام RFS.
`print`	Optional	`false`	قيمة منطقية (Boolean) تشير إلى ما إذا كان يجب توليد فئات للطباعة.
`rtl`	Optional	`true`	قيمة منطقية (Boolean) تشير إلى ما إذا كان يجب الإبقاء على الـ utility في وضع RTL.

شرح الـ API

تتم إضافة جميع متغيرات الـ utility إلى المتغير $utilities ضمن ورقة أنماط (stylesheet) _utilities.scss الخاصة بنا. تبدو كل مجموعة من الـ utilities بهذا الشكل:

$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)

يجب تعيين مفتاح property المطلوب لأي utility، ويجب أن يحتوي على خاصية CSS صالحة. تُستخدم هذه الخاصية في مجموعة قواعد الـ utility المُولدة. عندما يتم حذف مفتاح class ، فإنه يعمل أيضاً كاسم فئة (class) افتراضي. تأمل في الـ utility الخاصة بـ 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)

استخدم مفتاح values لتحديد القيم التي يجب استخدامها للـ property المحددة في أسماء الفئات (classes) والقواعد المُولدة. يمكن أن تكون قائمة أو خريطة (map) (يتم تعيينها في الـ utilities أو في متغير Sass).

كقائمة، كما هو الحال مع فئات text-decoration المساعدة:

values: none underline line-through

كخريطة (map)، كما هو الحال مع فئات (opacity) أدوات الشفافية:

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

كمتغير Sass يحدد القائمة أو الخريطة (map)، كما هو الحال في أدوات position المساعدة:

values: $position-values

الفئة (Class)

استخدم خيار 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 ، فسيتم توليد فئات (classes) لكل مفتاح من مفاتيح values :

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

المخرجات:

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

أدوات متغيرات الـ (CSS)

قم بتعيين الخيار المنطقي (Boolean) css-var إلى true وسيقوم الـ API بتوليد متغيرات CSS محلية للمحدد المعطى بدلاً من قواعد property: value المعتادة. أضف خيار css-variable-name الاختياري لتعيين اسم متغير CSS مختلف عن اسم الفئة (class).

تأمل في أدوات .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 محلية ضمن مجموعة قواعد الـ utility class. يرجى الملاحظة أنه قد يتطلب الأمر عملاً إضافياً لاستهلاك متغيرات الـ 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;
}

الحالات (States)

استخدم خيار state لتوليد تنويعات من الفئات الزائفة (pseudo-class). أمثلة على الفئات الزائفة هي :hover و :focus. عند توفير قائمة من الحالات، يتم إنشاء أسماء فئات (classnames) لتلك الفئة الزائفة. على سبيل المثال، لتغيير الشفافية عند التمرير (hover)، أضف 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)

أضف القيمة المنطقية (Boolean) responsive لتوليد أدوات متوافقة مع الشاشات (على سبيل المثال، .opacity-md-25) عبر جميع نقاط التوقف (breakpoints).

$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 سيقوم أيضاً بتوليد فئات (classes) مساعدة للطباعة، والتي يتم تطبيقها فقط ضمن استعلام الوسائط @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; }
}

الأهمية

تتضمن جميع الـ utilities التي يتم توليدها بواسطة الـ API عبارة !important لضمان تجاوز المكونات وفئات التعديل (modifier classes) كما هو مقصود. يمكنك تبديل هذا الإعداد عالمياً باستخدام المتغير $enable-important-utilities (القيمة الافتراضية هي true).

استخدام الـ API

الآن بعد أن أصبحت على دراية بكيفية عمل الـ utilities API، تعرف على كيفية إضافة الفئات (classes) المخصصة الخاصة بك وتعديل الـ utilities الافتراضية لدينا.

تجاوز الأدوات المساعدة (utilities)

قم بتجاوز الـ utilities الموجودة باستخدام نفس المفتاح. على سبيل المثال، إذا كنت تريد فئات utility إضافية متوافقة مع الشاشات (responsive) لخاصية overflow، يمكنك القيام بذلك:

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

إضافة أدوات مساعدة (utilities)

يمكن إضافة utilities جديدة إلى خريطة (map) $utilities الافتراضية باستخدام map-merge. تأكد من استيراد ملفات Sass المطلوبة وملف _utilities.scss أولاً، ثم استخدم map-merge لإضافة الـ utilities الإضافية الخاصة بك. على سبيل المثال، إليك كيفية إضافة utility متوافقة مع الشاشات (responsive) لخاصية cursor بثلاث قيم.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@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)

قم بتعديل الـ utilities الموجودة في الخريطة (map) $utilities الافتراضية باستخدام الدوال (functions) map-get و map-merge. في المثال أدناه، نقوم بإضافة قيمة إضافية إلى الـ utilities الخاصة بـ width. ابدأ بـ map-merge أولية ثم حدد الـ utility التي تريد تعديلها. من هناك، قم بجلب الخريطة (map) المتداخلة "width" باستخدام map-get للوصول إلى خيارات وقيم الـ utility وتعديلها.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@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";

تفعيل التوافق مع الشاشات (Responsive)

يمكنك تفعيل الفئات (classes) المتوافقة مع الشاشات لمجموعة موجودة من الـ utilities التي ليست متوافقة مع الشاشات افتراضياً. على سبيل المثال، لجعل فئات border متوافقة مع الشاشات:

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@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";

سيؤدي هذا الآن إلى توليد تنويعات متوافقة مع الشاشات (responsive) للفئات .border و .border-0 لكل نقطة توقف (breakpoint). سيبدو ملف 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 { ... }
}

إعادة تسمية الأدوات المساعدة

هل تفتقد إلى الـ utilities الخاصة بالإصدار v4، أو تستخدم اتفاقية تسمية أخرى؟ يمكن استخدام الـ utilities API لتجاوز الـ class الناتج لـ utility معينة—على سبيل المثال، لإعادة تسمية الـ utilities من .ms-* إلى .ml-* القديمة:

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@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/variables-dark";
@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 لإزالة الأدوات المساعد (utility).

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

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

@import "bootstrap/scss/utilities/api";

إضافة، إزالة، تعديل

يمكنك إضافة العديد من الـ utilities وإزالتها وتعديلها جميعاً في وقت واحد باستخدام map-merge() الدالة الخاصة بـ Sass من هنا. إليك كيف يمكنك دمج الأمثلة السابقة في خريطة (map) واحدة أكبر.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@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، وذلك بفضل توجيه التحكم remove الخاص بـ RTLCSS.