Skip to main content Skip to docs navigation
مشاهدة على الـ GitHub

الـ (Sass)

استفد من ملفات الـ Sass المصدرية للاستفادة من الـ variables، والـ maps، والـ mixins، والدوال (functions) لمساعدتك في البناء بشكل أسرع وتخصيص مشروعك.

في هذه الصفحة

استفد من ملفات الـ Sass المصدرية للاستفادة من الـ variables، والـ maps، والـ mixins، والمزيد.

تظهر تحذيرات الاستبعاد (deprecation warnings) الخاصة بالـ Sass عند تجميع ملفات الـ Sass المصدرية باستخدام أحدث إصدارات Dart Sass. هذا لا يمنع التجميع أو استخدام الـ Bootstrap. نحن نعمل على إصلاح طويل الأمد، ولكن في هذه الأثناء يمكن تجاهل إشعارات الاستبعاد هذه.

هيكل الملفات (File structure)

كلما كان ذلك ممكناً، تجنب تعديل ملفات الـ Bootstrap الأساسية. بالنسبة لـ Sass، هذا يعني إنشاء ورقة أنماط (stylesheet) خاصة بك تقوم باستيراد Bootstrap حتى تتمكن من تعديله وتوسيعه. بافتراض أنك تستخدم مدير حزم مثل npm، سيكون لديك هيكل ملفات يبدو بهذا الشكل:

your-project/
├── scss/
│   └── custom.scss
└── node_modules/
│   └── bootstrap/
│       ├── js/
│       └── scss/
└── index.html

إذا كنت قد قمت بتنزيل ملفات المصدر الخاصة بنا ولا تستخدم مدير حزم، فستحتاج إلى إنشاء شيء مشابه لهذا الهيكل يدوياً، مع الحفاظ على ملفات المصدر الخاصة بـ Bootstrap منفصلة عن ملفاتك الخاصة.

your-project/
├── scss/
│   └── custom.scss
├── bootstrap/
│   ├── js/
│   └── scss/
└── index.html

الاستيراد (Importing)

في ملف custom.scss الخاص بك، ستقوم باستيراد ملفات الـ Sass المصدرية الخاصة بـ Bootstrap. لديك خياران: تضمين الـ Bootstrap بالكامل، أو اختيار الأجزاء التي تحتاجها. نحن نشجع على الخيار الأخير، ولكن كن على علم بأن هناك بعض المتطلبات والتبعيات عبر المكونات الخاصة بنا. ستحتاج أيضاً إلى تضمين بعض الـ JavaScript من أجل الإضافات (plugins) الخاصة بنا.

// Custom.scss
// Option A: Include all of Bootstrap

// Include any default variable overrides here (though functions won’t be available)

@import "../node_modules/bootstrap/scss/bootstrap";

// Then add additional custom code here

// Custom.scss
// Option B: Include parts of Bootstrap

// 1. Include functions first (so you can manipulate colors, SVGs, calc, etc)
@import "../node_modules/bootstrap/scss/functions";

// 2. Include any default variable overrides here

// 3. Include remainder of required Bootstrap stylesheets (including any separate color mode stylesheets)
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

// 4. Include any default map overrides here

// 5. Include remainder of required parts
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// 6. Include any other optional stylesheet partials as desired; list below is not inclusive of all available stylesheets
@import "../node_modules/bootstrap/scss/utilities";
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
@import "../node_modules/bootstrap/scss/images";
@import "../node_modules/bootstrap/scss/containers";
@import "../node_modules/bootstrap/scss/grid";
@import "../node_modules/bootstrap/scss/helpers";
// ...

// 7. Optionally include utilities API last to generate classes based on the Sass map in `_utilities.scss`
@import "../node_modules/bootstrap/scss/utilities/api";

// 8. Add additional custom code here

بمجرد إعداد هذا التكوين، يمكنك البدء في تعديل أي من الـ Sass variables والـ maps في ملف custom.scss الخاص بك. يمكنك أيضاً البدء في إضافة أجزاء من الـ Bootstrap تحت قسم // Optional حسب الحاجة. نقترح استخدام مجموعة الاستيراد الكاملة من ملف bootstrap.scss الخاص بنا كنقطة بداية.

التجميع (Compiling)

من أجل استخدام كود الـ Sass المخصص الخاص بك كـ CSS في المتصفح، فأنت بحاجة إلى Sass compiler. يأتي الـ Sass كحزمة CLI، ولكن يمكنك أيضاً تجميعه باستخدام أدوات بناء أخرى مثل Gulp أو Webpack أو باستخدام تطبيقات GUI. تحتوي بعض بيئات التطوير المتكاملة (IDEs) أيضاً على Sass compilers مدمجة أو كإضافات قابلة للتنزيل.

نحن نفضل استخدام الـ CLI لتجميع الـ Sass الخاص بنا، ولكن يمكنك استخدام الطريقة التي تفضلها. من سطر الأوامر، قم بتشغيل ما يلي:

# Install Sass globally
npm install -g sass

# Watch your custom Sass for changes and compile it to CSS
sass --watch ./scss/custom.scss ./css/custom.css

تعرف على المزيد من الخيارات في sass-lang.com/install و التجميع باستخدام VS Code.

هل تستخدم Bootstrap مع أداة بناء أخرى؟ فكر في قراءة أدلتنا للتجميع باستخدام Webpack أو Parcel أو Vite لدينا أيضاً عروض توضيحية جاهزة للإنتاج في مستودع الأمثلة الخاص بنا على GitHub.

التضمين (Including)

بمجرد تجميع الـ CSS الخاص بك، يمكنك تضمينه في ملفات الـ HTML الخاصة بك. داخل ملف index.html الخاص بك، سترغب في تضمين ملف الـ CSS المجمّع. تأكد من تحديث المسار إلى ملف الـ CSS المجمّع إذا قمت بتغييره.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Custom Bootstrap</title>
    <link href="/css/custom.css" rel="stylesheet">
  </head>
  <body>
    <h1>Hello, world!</h1>
  </body>
</html>

القيم الافتراضية للمتغيرات (Variable defaults)

تتضمن كل متغيرات الـ Sass في Bootstrap علامة !default مما يسمح لك بتجاوز القيمة الافتراضية للمتغير في الـ Sass الخاص بك دون تعديل الكود المصدري لـ Bootstrap. قم بنسخ ولصق المتغيرات حسب الحاجة، وقم بتعديل قيمها، وقم بإزالة علامة !default. إذا تم تعيين متغير بالفعل، فلن يتم إعادة تعيينه بواسطة القيم الافتراضية في Bootstrap.

ستجد القائمة الكاملة لمتغيرات Bootstrap في scss/_variables.scss. يتم تعيين بعض المتغيرات إلى null ، وهذه المتغيرات لا تخرج الخاصية ما لم يتم تجاوزها في التكوين الخاص بك.

يجب أن تأتي عمليات تجاوز المتغيرات بعد استيراد الدوال (functions) الخاصة بنا، ولكن قبل بقية عمليات الاستيراد.

إليك مثال يغير background-color و color لـ <body> عند استيراد وتجميع Bootstrap عبر npm:

// Required
@import "../node_modules/bootstrap/scss/functions";

// Default variable overrides
$body-bg: #000;
$body-color: #111;

// Required
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";
@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// Optional Bootstrap components here
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

كرر ذلك حسب الضرورة لأي متغير في الـ Bootstrap، بما في ذلك الخيارات العامة أدناه.

ابدأ مع الـ Bootstrap عبر npm باستخدام مشروعنا المبدئي! توجه إلى مستودع قالب Sass & JS example لترى كيفية بناء وتخصيص الـ Bootstrap في مشروع npm الخاص بك. يتضمن ذلك مترجم Sass و Autoprefixer و Stylelint و PurgeCSS و Bootstrap Icons.

الخرائط (Maps) والحلقات (loops)

تتضمن الـ Bootstrap عدداً من خرائط الـ Sass (Sass maps)، وهي عبارة عن أزواج من المفاتيح والقيم التي تسهل إنشاء عائلات من الـ CSS ذات الصلة. نحن نستخدم خرائط الـ Sass لألواننا، ونقاط توقف الشبكة (grid breakpoints)، وغيرها. ومثل متغيرات الـ Sass، تتضمن جميع خرائط الـ Sass علامة !default ويمكن تجاوزها وتوسيعها.

يتم دمج بعض خرائط الـ Sass الخاصة بنا في خرائط فارغة افتراضياً. يتم ذلك للسماح بتوسيع خريطة Sass معينة بسهولة، ولكن ذلك يأتي على حساب جعل إزالة العناصر من الخريطة أكثر صعوبة قليلاً.

تعديل الخريطة (Modify map)

يتم تعريف جميع المتغيرات في خريطة $theme-colors كمتغيرات مستقلة. لتعديل لون موجود في خريطة $theme-colors الخاصة بنا، أضف ما يلي إلى ملف الـ Sass المخصص الخاص بك:

$primary: #0074d9;
$danger: #ff4136;

لاحقاً، يتم تعيين هذه المتغيرات في خريطة $theme-colors الخاصة بالـ Bootstrap:

$theme-colors: (
  "primary": $primary,
  "danger": $danger
);

الإضافة إلى الخريطة (Add to map)

أضف ألواناً جديدة إلى $theme-colors، أو أي خريطة (map) أخرى، عن طريق إنشاء خريطة Sass جديدة بقيمك المخصصة ودمجها مع الخريطة الأصلية. في هذه الحالة، سنقوم بإنشاء خريطة $custom-colors جديدة ودمجها مع $theme-colors.

// Create your own map
$custom-colors: (
  "custom-color": #900
);

// Merge the maps
$theme-colors: map-merge($theme-colors, $custom-colors);

الإزالة من الخريطة (Remove from map)

لإزالة الألوان من $theme-colors، أو أي خريطة (map) أخرى، استخدم map-remove. كن على علم أنه يجب عليك إدراج $theme-colors بين متطلباتنا مباشرة بعد تعريفها في variables وقبل استخدامها في maps:

// Required
@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/variables-dark";

$theme-colors: map-remove($theme-colors, "info", "light", "dark");

@import "../node_modules/bootstrap/scss/maps";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/root";

// Optional
@import "../node_modules/bootstrap/scss/reboot";
@import "../node_modules/bootstrap/scss/type";
// etc

المفاتيح المطلوبة (Required keys)

تفترض الـ Bootstrap وجود بعض المفاتيح المحددة داخل خرائط الـ Sass (Sass maps) لأننا نستخدمها ونوسعها بأنفسنا. وبينما تقوم بتخصيص الخرائط المضمنة، قد تواجه أخطاء حيث يتم استخدام مفتاح خريطة Sass محدد.

على سبيل المثال، نستخدم المفاتيح primary و success و danger من $theme-colors للروابط والأزرار وحالات النماذج. لا ينبغي أن يسبب استبدال قيم هذه المفاتيح أي مشاكل، ولكن إزالتها قد تسبب مشاكل في تجميع الـ Sass. في هذه الحالات، ستحتاج إلى تعديل كود الـ Sass الذي يستخدم تلك القيم.

الدوال (Functions)

الألوان

إلى جانب خرائط الـ Sass التي لدينا، يمكن أيضاً استخدام ألوان السمة كمتغيرات مستقلة، مثل $primary.

.custom-element {
  color: $gray-100;
  background-color: $dark;
}

يمكنك تفتيح أو تغميق الألوان باستخدام دوال (functions) الـ Bootstrap tint-color() و shade-color(). ستقوم هذه الدوال بخلط الألوان مع الأسود أو الأبيض، على عكس دوال (functions) الـ Sass الأصلية lighten() و darken() التي تغير درجة السطوع بمقدار ثابت، وهو ما لا يؤدي غالباً إلى التأثير المطلوب.

تجمع الدالة shift-color() هاتين الدالتين من خلال تغميق اللون إذا كان الوزن موجباً وتفتيحه إذا كان الوزن سالباً.

scss/_functions.scss 
// Tint a color: mix a color with white
@function tint-color($color, $weight) {
  @return mix(white, $color, $weight);
}

// Shade a color: mix a color with black
@function shade-color($color, $weight) {
  @return mix(black, $color, $weight);
}

// Shade the color if the weight is positive, else tint it
@function shift-color($color, $weight) {
  @return if($weight > 0, shade-color($color, $weight), tint-color($color, -$weight));
}

من الناحية العملية، ستقوم باستدعاء الدالة (function) وتمرير معاملات اللون والوزن.

.custom-element {
  color: tint-color($primary, 10%);
}

.custom-element-2 {
  color: shade-color($danger, 30%);
}

.custom-element-3 {
  color: shift-color($success, 40%);
  background-color: shift-color($success, -60%);
}

تباين الألوان (Color contrast)

من أجل تلبية متطلبات التباين الخاصة بـ إرشادات الوصول إلى محتوى الويب (WCAG)، يجب على المؤلفين توفير حد أدنى من تباين ألوان النصوص بنسبة 4.5:1 وحد أدنى من تباين الألوان غير النصية بنسبة 3:1، مع وجود استثناءات قليلة جداً.

للمساعدة في ذلك، قمنا بتضمين الدالة (function) color-contrast في الـ Bootstrap. وهي تستخدم خوارزمية نسبة تباين WCAG لحساب عتبات التباين بناءً على السطوع النسبي في مساحة ألوان sRGB لإرجاع لون تباين فاتح (#fff)، أو داكن (#212529)، أو أسود (#000) تلقائياً بناءً على اللون الأساسي المحدد. هذه الدالة مفيدة بشكل خاص للمزجات (mixins) أو الحلقات (loops) حيث تقوم بإنشاء فئات (classes) متعددة.

على سبيل المثال، لإنشاء عينات ألوان من خريطة (map) $theme-colors الخاصة بنا:

@each $color, $value in $theme-colors {
  .swatch-#{$color} {
    color: color-contrast($value);
  }
}

ويمكن استخدامه أيضاً لاحتياجات التباين لمرة واحدة:

.custom-element {
  color: color-contrast(#000); // returns `color: #fff`
}

يمكنك أيضاً تحديد لون أساسي باستخدام وظائف خريطة الألوان لدينا:

.custom-element {
  color: color-contrast($dark); // returns `color: #fff`
}

هروب الـ (SVG)

نحن نستخدم الدالة (function) escape-svg لعمل هروب للمحارف < و > و # لصور خلفية الـ (SVG). عند استخدام الدالة (function) escape-svg ، يجب وضع الـ data URIs بين علامتي تنصيص.

دوال (functions) الجمع والطرح

نحن نستخدم الدوال (functions) add و subtract لتغليف دالة calc الخاصة بـ CSS. الغرض الأساسي من هذه الدوال (functions) هو تجنب الأخطاء عندما يتم تمرير قيمة 0 "بدون وحدة" إلى تعبير calc. تعبيرات مثل calc(10px - 0) ستؤدي إلى خطأ في جميع المتصفحات، على الرغم من أنها صحيحة رياضياً.

مثال حيث تكون عملية الـ calc صالحة:

$border-radius: .25rem;
$border-width: 1px;

.element {
  // Output calc(.25rem - 1px) is valid
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Output the same calc(.25rem - 1px) as above
  border-radius: subtract($border-radius, $border-width);
}

Example where the calc is invalid:

$border-radius: .25rem;
$border-width: 0;

.element {
  // Output calc(.25rem - 0) is invalid
  border-radius: calc($border-radius - $border-width);
}

.element {
  // Output .25rem
  border-radius: subtract($border-radius, $border-width);
}

المزجات/الدمج (Mixins)

يحتوي المجلد scss/mixins/ الخاص بنا على مجموعة كبيرة من المزجات/الدمج (mixins) التي تشغل أجزاءً من الـ Bootstrap ويمكن استخدامها أيضاً في مشروعك الخاص.

مخططات الألوان (Color schemes)

يتوفر مزيج/دمج (mixin) مختصر لاستعلام الوسائط prefers-color-scheme مع دعم مخططات الألوان light و dark. راجع مستندات أوضاع الألوان للحصول على معلومات حول مزيج/دمج (mixin) وضع الألوان الخاص بنا.

scss/mixins/_color-scheme.scss 
@mixin color-scheme($name) {
  @media (prefers-color-scheme: #{$name}) {
    @content;
  }
}

.custom-element {
  @include color-scheme(light) {
    // Insert light mode styles here
  }

  @include color-scheme(dark) {
    // Insert dark mode styles here
  }
}