الأداة المساعدة API
الأداة المساعدة API هي أداة تستند إلى Sass لإنشاء فئات الأدوات المساعدة.
يتم إنشاء أدوات Bootstrap المساعدة من خلال واجهة برمجة التطبيقات الخاصة بنا ويمكن استخدامها لتعديل أو توسيع مجموعتنا الافتراضية من فئات الأدوات المساعدة عبر Sass. تعتمد واجهة برمجة التطبيقات (API) الخاصة بنا على سلسلة من خرائط ووظائف Sass لتوليد مجموعات من الفئات بخيارات متنوعة. إذا لم تكن معتادًا على خرائط Sass ، فاقرأ مستندات Sass الرسمية للبدء.
تحتوي $utilities
الخريطة على جميع أدواتنا المساعدة ويتم دمجها لاحقًا مع $utilities
خريطتك المخصصة ، إن وجدت. تحتوي خريطة الأداة المساعدة على قائمة بمفاتيح مجموعات الأدوات التي تقبل الخيارات التالية:
خيار | يكتب | القيمة الافتراضية | وصف |
---|---|---|---|
property |
مطلوب | - | اسم الخاصية ، يمكن أن تكون سلسلة أو مجموعة من السلاسل (على سبيل المثال ، الحشوات الأفقية أو الهوامش). |
values |
مطلوب | - | قائمة القيم ، أو خريطة إذا كنت لا تريد أن يكون اسم الفئة مطابقًا للقيمة. إذا null تم استخدامه كمفتاح خريطة ، فلن يتم تجميعه. |
class |
اختياري | لا شيء | اسم الفئة التي تم إنشاؤها. إذا لم يتم توفيره وكان property مصفوفة من السلاسل ، class فسيتم تعيينه افتراضيًا على العنصر الأول من property المصفوفة. |
css-var |
اختياري | false |
قيمة منطقية لإنشاء متغيرات CSS بدلاً من قواعد 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; }
المرافق المتغيرة CSS
اضبط css-var
الخيار المنطقي على true
وستقوم واجهة برمجة التطبيقات بإنشاء متغيرات CSS محلية للمحدد المحدد بدلاً من property: value
القواعد المعتادة. ضع في اعتبارك مرافقنا .text-opacity-*
:
$utilities: (
"text-opacity": (
css-var: true,
class: text-opacity,
values: (
25: .25,
50: .5,
75: .75,
100: 1
)
),
);
انتاج:
.text-opacity-25 { --bs-text-opacity: .25; }
.text-opacity-50 { --bs-text-opacity: .5; }
.text-opacity-75 { --bs-text-opacity: .75; }
.text-opacity-100 { --bs-text-opacity: 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; }
متجاوب
أضف القيمة 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/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 ، أو تستخدم اصطلاح تسمية آخر؟ يمكن استخدام واجهة برمجة تطبيقات الأدوات المساعدة لتجاوز الناتج الناتج 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
الخيار على 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
.