الأداة المساعدة API

الأداة المساعدة API هي أداة تستند إلى Sass لإنشاء فئات الأدوات المساعدة.

على هذه الصفحة

يتم إنشاء أدوات Bootstrap المساعدة من خلال واجهة برمجة التطبيقات الخاصة بنا ويمكن استخدامها لتعديل أو توسيع مجموعتنا الافتراضية من فئات الأدوات المساعدة عبر 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وستقوم واجهة برمجة التطبيقات بإنشاء متغيرات 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

الآن بعد أن أصبحت على دراية بكيفية عمل واجهة برمجة تطبيقات الأدوات المساعدة ، تعرف على كيفية إضافة الفئات المخصصة الخاصة بك وتعديل الأدوات المساعدة الافتراضية الخاصة بنا.

تجاوز المرافق

تجاوز المرافق الموجودة باستخدام نفس المفتاح. على سبيل المثال ، إذا كنت تريد فئات أدوات مساعدة إضافية سريعة الاستجابة ، فيمكنك القيام بذلك:

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

أضف المرافق

يمكن إضافة أدوات مساعدة جديدة إلى $utilitiesالخريطة الافتراضية بملحق map-merge. تأكد _utilities.scssمن استيراد ملفات Sass المطلوبة أولاً ، ثم استخدمها 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 ، أو تستخدم اصطلاح تسمية آخر؟ يمكن استخدام واجهة برمجة تطبيقات الأدوات المساعدة لتجاوز الناتج الناتج 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الخيار على 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 .