الفرق بين المراجعتين لصفحة: «Sass/usage»
ط إضافة عنوان |
ط استبدال النص - '\[\[تصنيف:(.*)\]\]' ب'{{SUBPAGENAME}}' |
||
| (5 مراجعات متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة) | |||
| سطر 1: | سطر 1: | ||
يمكن استخدام Sass بثلاث طرائق: كأداة سطر أوامر، أو كوحدةٍ مستقلة لروبي، أو كمُلحقة في أيّ بيئة عمل تدعم Rack، بما في ذلك Ruby on Rails و Merb. | <noinclude>{{DISPLAYTITLE:تثبيت وضبط واستخدام Sass}}</noinclude> | ||
يمكن استخدام Sass بثلاث طرائق هي: كأداة سطر أوامر، أو كوحدةٍ مستقلة لروبي، أو كمُلحقة في أيّ بيئة عمل تدعم Rack، بما في ذلك Ruby on Rails و Merb. | |||
== تثبيت Sass == | == تثبيت Sass == | ||
الخطوة الأولى لاستخدام Sass | الخطوة الأولى لاستخدام Sass هي تثبيت الجوهرة (gem) Sass:<syntaxhighlight lang="shell"> | ||
gem install sass | gem install sass | ||
</syntaxhighlight>إن كنت تستخدم نظام ويندوز، فقد تحتاج إلى تثبيت روبي أولاً. | </syntaxhighlight>إن كنت تستخدم نظام ويندوز، فقد تحتاج إلى تثبيت روبي أولاً. | ||
| سطر 8: | سطر 9: | ||
لتشغيل Sass من سطر الأوامر، يكفي أن تكتب الأمر الآتي:<syntaxhighlight lang="shell"> | لتشغيل Sass من سطر الأوامر، يكفي أن تكتب الأمر الآتي:<syntaxhighlight lang="shell"> | ||
sass input.scss output.css | sass input.scss output.css | ||
</syntaxhighlight>يمكنك أيضًا إخبار Sass بمراقبة الملف وتحديث ملف CSS الناتج عند | </syntaxhighlight>يمكنك أيضًا إخبار Sass بمراقبة الملف وتحديث ملف CSS الناتج عند كلِّ تغيُّرٍ في ملف Sass:<syntaxhighlight lang="shell"> | ||
sass --watch input.scss:output.css | sass --watch input.scss:output.css | ||
</syntaxhighlight>إن كان لديك | </syntaxhighlight>إن كان لديك مجلَّد يحتوي على عدِّة ملفات Sass، فيمكنك أيضًا إخبار Sass بمراقبة ذلك المجلَّد بأكمله:<syntaxhighlight lang="shell"> | ||
sass --watch app/sass:public/stylesheets | sass --watch app/sass:public/stylesheets | ||
</syntaxhighlight> | </syntaxhighlight>للإطلاع على التوثيقٍ الشامل لجميع خيارات الأمر <code>sass</code>، استعمل الأمر <code>sass --help</code>. | ||
إنّ استخدام Sass في الكود البرمجي لروبي بسيطٌ | إنّ استخدام Sass في الكود البرمجي لروبي بسيطٌ جدًّا، إذ يمكنك بعد تثبيت الجوهرة Sass استخدامها بتشغيل <code>require "sass"</code> واستخدام <code>Sass::Engine</code> كالآتي:<syntaxhighlight lang="ruby"> | ||
engine = Sass::Engine.new("#main {background-color: #0000ff}", :syntax => :scss) | engine = Sass::Engine.new("#main {background-color: #0000ff}", :syntax => :scss) | ||
engine.render #=> "#main { background-color: #0000ff; }\n" | engine.render #=> "#main { background-color: #0000ff; }\n" | ||
| سطر 23: | سطر 24: | ||
لإتاحة Sass في الإصدارات السابقة لإصدار Rails 3، أضف السطر التالي إلى <code>environment.rb</code>:<syntaxhighlight lang="ruby"> | لإتاحة Sass في الإصدارات السابقة لإصدار Rails 3، أضف السطر التالي إلى <code>environment.rb</code>:<syntaxhighlight lang="ruby"> | ||
config.gem "sass" | config.gem "sass" | ||
</syntaxhighlight>أمّا في Rails 3، فأضف | </syntaxhighlight>أمّا في Rails 3، فأضف السطر التالي إلى Gemfile بدلًا من ذلك:<syntaxhighlight lang="ruby"> | ||
gem "sass" | gem "sass" | ||
</syntaxhighlight>لإتاحة Sass في Merb، أضف السطر التالي إلى الملف <code>config/dependencies.rb</code>:<syntaxhighlight lang="ruby"> | </syntaxhighlight>لإتاحة Sass في Merb، أضف السطر التالي إلى الملف <code>config/dependencies.rb</code>:<syntaxhighlight lang="ruby"> | ||
| سطر 30: | سطر 31: | ||
require 'sass/plugin/rack' | require 'sass/plugin/rack' | ||
use Sass::Plugin::Rack | use Sass::Plugin::Rack | ||
</syntaxhighlight>لا تعمل أنماط Sass | </syntaxhighlight>لا تعمل أنماط Sass بطريقة عمل العروض (views) نفسها فهي لا تتضمّن محتوًى ديناميكيًا، لذا ليس من الضروري توليد [[CSS]] سوى عند تحديث ملف Sass. توضع الملفات <code>.sass</code> و <code>.scss</code> افتراضيًا في المجلَّد <code>public/stylesheets/sass</code> (يمكن تخصيص ذلك باستخدام الخيار <code>:template_location</code>) ثمّ يتم تصريفها (compiled)، عند الحاجة، إلى ملفات CSS مقابلة لتلك الموجودة ووضعها في المجلَّد <code>public/stylesheets</code>. على سبيل المثال، سيُصرَّف الملف <code>public/stylesheets/sass/main.scss</code> إلى <code>public/stylesheets/main.css</code>. | ||
== التخزين المؤقت == | == التخزين المؤقت == | ||
افتراضيًّا، تخزِّن Sass مؤقتًا القوالب المُصرّفة (compiled templates) [[Sass/@ rules|والمجزوءات]] (partials). يسرِّع هذا عمليّة إعادة تصريف المجموعات الكبيرة من ملفات Sass بشكلٍ كبيرٍ، ويعمل بشكل أفضل إذا قُسِّمَت قوالب Sass إلى ملفاتٍ منفصلة لأجل استيرادها -عبر <code>[[Sass/@ rules|@import]]</code>- في ملف واحدٍ كبير. | |||
في غياب إطار عمل، تضع Sass القوالب المخزّنة مؤقتًا في | في غياب إطار عمل، تضع Sass القوالب المخزّنة مؤقتًا في مجلَّد <code>sass-cache.</code>. أمَّا في روبي و Merb، فستُخزَّن في <code>tmp/sass-cache</code>. يمكن تخصيص المجلَّد عبر الخيار <code>:cache_location</code>. إن لم ترغب في أن تستخدم تقنيةُ Sass التخزينَ المؤقَّت، فاضبط الخيار <code>:cache</code> إلى القيمة <code>false</code>. | ||
== الخيارات == | == الخيارات == | ||
يمكن تعيين الخيارات عن طريق تحديد التلبيد ((Hash <code>Sass::Plugin#options</code> في <code>environment.rb</code> في روبي أو <code>config.ru</code> في Rack | يمكن تعيين الخيارات عن طريق تحديد التلبيد ((Hash <code>Sass::Plugin#options</code> في <code>environment.rb</code> في روبي أو <code>config.ru</code> في Rack.<syntaxhighlight lang="ruby"> | ||
Sass::Plugin.options[:style] = :compact | Sass::Plugin.options[:style] = :compact | ||
</syntaxhighlight> | </syntaxhighlight>أو عن طريق تعيين التلبيد <code>[Merb::Plugin.config[:sass</code> في <code>init.rb</code> في Merb.<syntaxhighlight lang="ruby"> | ||
Merb::Plugin.config[:sass][:style] = :compact | Merb::Plugin.config[:sass][:style] = :compact | ||
</syntaxhighlight> | </syntaxhighlight>أو عن طريق تمرير خيارات تلبيد إلى <code>Sass::Engine#initialize</code>. جميع الخيارات ذات الصّلة متاحةٌ أيضًا من خلال الرايات (flags) في سطري أوامر Sass و SCSS وهي: | ||
=== <code>:style</code> === | |||
ضبط تنسيق مُخرجات CSS. انظر [[Sass/output style|تنسيق المخرجات]]. | |||
=== <code>:syntax</code> === | |||
تحديد صياغة ملف الإدخال، اختر <code>:sass</code> لأجل الصياغة الإزاحيَّة و <code>:scss</code> لأجل الصياغة SCSS. هذا مفيد فقط عندما ترغب في إنشاء نسخة من <code>Sass::Engine</code> بنفسك. تُضبط تلقائيًا بالشكل المناسب عند استخدام <code>Sass::Plugin</code>. القيمة الافتراضيَّة لهذه الخاصيّة هي <code>sass:</code>. | |||
=== <code>:property_syntax</code> === | |||
إجبار الملفات المكتوبة بالصياغة الإزاحيّة على استخدام صياغة واحدة لأجل الخاصِّيَّات. إذا لم تُستخدَم الصياغة الصحيحة فسيُطلَق خطأ. تفرض <code>new:</code> استخدام النقطتين بعد اسم الخاصيَّة. على سبيل المثال: <code>color: #0f3</code> أو <code>width: $main_width</code>. أمّا <code>old:</code> فتفرض استخدام النقطتين قبل اسم الخاصِّيَّة. على سبيل المثال: <code>color #0f3:</code> أو <code>width $main_width:</code>. افتراضيًا، كلا الصياغتين صالحتان وهذا ليس له أيّ تأثيرٍ على ملفات SCSS. | |||
=== <code>cache:</code> === | |||
تحديد ما إذا كان ينبغي تخزين ملفات Sass المُحلّلة (parsed) مؤقتًّا للحصول على سرعة أكبر. القيمة الافتراضيَّة هي <code>true</code>. | |||
=== <code>read_cache:</code> === | |||
إن ضُبِطَ هذا الخيار دون ضبط الخيار <code>cache:</code>، فستُقرأ النّسخ المخزّنة مؤقتًا لتقنية Sass إن كانت موجودة، ولن يُكتب عليها إن لم تكن موجودة. | |||
=== <code>cache_store:</code> === | |||
إن أُسنِد لهذه الخاصِّيَّة نسخةٌ من صنف فرعي من <code>Sass::CacheStores::Base</code>، فسيستخدم مكانُ التخزين المؤقَّت هذا لتخزين واسترجاع النتائج المصرّفة والمخزَّنة. القيمة الافتراضيَّة هي <code>Sass::CacheStores::Filesystem</code> والتي ستُهيئ باستخدام الخيار <code>:cache_location</code>. | |||
=== <code>never_update:</code> === | |||
تحديد ما إذا كان ينبغي تحديث ملفات [[CSS]]، حتى لو تغيّر ملف القالب. إعطاء هذا الخيار القيمة <code>true</code> قد يحسِّن الأداء قليلًا. قيمته الافتراضيّة هي <code>false</code>. ولا معنى لها إلا في Rack، أو Ruby on Rails، أو Merb. | |||
=== <code>always_update:</code> === | |||
تحديد ما إذا كان ينبغي تحديث ملفات [[CSS]] عند الدخول إلى وحدة تحكم (controller) في كلِّ مرَّة، في مقابل إيقاف التحديث في حالة تعديل القالب. القيمة الافتراضيَّة هي <code>false</code>. ولا معنى لها إلّا في Rack، أو Ruby on Rails، أو Merb. | |||
=== <code>:always_check</code> === | |||
تحديد ما إذا كان ينبغي التحقّق من إمكانيَّة تحديث قالب Sass عند الدّخول إلى وحدة تحكم، في مقابل إيقاف عمليّة التحديث عند بدء تشغيل الخادم. إذا حُدِّث قالب Sass، فسيُعاد تصريفه، وسيُكتب على ملف [[CSS]] المقابل. القيمة الافتراضيَّة لهذه الخاصِّيَّة هي <code>false</code> في وضع الإنتاج (production mode)، أو <code>true</code> خلافًا لذلك، ولا معنى لها إلا في Rack، أو Ruby on Rails، أو Merb. | |||
=== <code>:poll</code> === | |||
عندما تكون قيمتها <code>true</code>، سيستخدم دومًا الاستطلاع الخلفي (polling backend) لأجل <code>Sass::Plugin::Compiler#watch</code> بدلًا من نظام الملفات الخلفي الأصلي. | |||
=== <code>:full_exception</code> === | |||
تحديد ما إذا كان الخطأ في الكود البرمجي للّغة Sass سيجعل Sass توفّر وصفًا مفصلًا داخل ملف [[CSS]] المُولّد. إذا أُعطِيتْ لهذه الخاصية القيمة <code>true</code>، فسيُعرَض الخطأ جنبًا إلى جنب مع رقم السطر ومقتطف من الكود المصدري على شكل تعليقٍ في ملف [[CSS]] وفي الجزء العلوي أيضًا من الصفحة (في المتصفحات المدعومة). خلاف ذلك، سيُطلَق استثناء في الكود البرمجي في [[Ruby|روبي]]. القيمة الافتراضيَّة لهذه الخاصيَّة هي <code>false</code> في وضع الإنتاج، أو <code>true</code> خلاف ذلك. | |||
=== <code>:template_location</code> === | |||
تحديد مسار المجلَّد الجذري لقالب Sass الخاصّ بتطبيقك. في حال كانت تلبيدًا (hash)، فسيُتجاهل <code>:css_location</code> وسيُعيّن هذا الخيار رابطًا (mapping) بين مجلّدي المدخلات والمخرجات. يمكن أيضًا إعطاء هذه الخاصيًة قائمة مكوّنة من قوائم ثنائيَّة (2-element lists) بدلًا من التلبيد. القيمة الافتراضيَّة هي css_location + <code>"/sass"</code>، ولا معنى لها إلا في Rack، أو Ruby on Rails، أو Merb. لاحظ أنّه في حال حُدِّدَت عدَّة مواقع للقالب، فستُوضَع جميعًا في مسار الاستيراد، ممّا يسمح لك بالاستيراد منها. تذكر أنّه نظرًا لتعدد الصيغ المحتملة التي يمكن أن يكون عليها، فيجب تعيين هذا الخيار بشكل مباشرٍ، وليس الدخول إليه أو تعديله. استخدم بدلًا من ذلك التابع <code>Sass::Plugin#template_location_array</code>، والتابع <code>Sass::Plugin#add_template_location</code> والتابع <code>Sass::Plugin#remove_template_location</code>. | |||
=== <code>:css_location</code> === | |||
تحديد المسار حيث يجب أن تُكتب مُخرجات CSS. يتم تجاهل هذا الخيار في حالة كان <code>:template_location</code> تلبيدًا. القيمة الافتراضيَّة هي "<code>./public/stylesheets</code>"، ولا معنى لها إلا في Rack، أو Ruby on Rails، أو Merb. | |||
=== <code>:cache_location</code> === | |||
تحديد المسار حيث يجب أن تُكتب ملفات sassc المُخزّنة مؤقتًا. القيمة الافتراضيَّة هي "<code>./tmp/sass-cache</code>" في Rails و Merb، أو "<code>./.sass-cache</code>" خلاف ذلك. في حال ضُبِطَ الخيار <code>:cache_store</code>، فسيتم تجاهلها. | |||
=== <code>:unix_newlines</code> === | |||
إن كانت قيمتها <code>true</code>، فسيُستخدم نمط السطر الجديد المٌعتمد في أنظمة يونكس عند كتابة الملفات. لا معنى لها إلا في نظام ويندوز، وعندما تتولى Sass كتابة الملفات فقط (في Rack، أو Rails، أو Merb، وذلك عند استخدام <code>Sass::Plugin</code> مباشرةً، أو عند استخدام سطر الأوامر). | |||
=== <code>:filename</code> === | |||
تحديد اسم الملف الذي يتم تقديمه. ويُستخدم فقط لأجل التبليغ عن الأخطاء، ويُعيّن تلقائيًّا عند استخدام Rack، أو Rails أو Merb. | |||
=== <code>:line</code> === | |||
رقم السطر الأول من قالب Sass. يُستخدم للإبلاغ عن أرقام الأسطر في الأخطاء. استعمال هذه الراية مفيد في حال ضُمِّن قالب Sass في ملف روبي. | |||
=== <code>:load_paths</code> === | |||
تحديد مسار المصفوفة التي تحتوي على مسارات الملفات أو المستورِدات التي ينبغي البحث فيها عن قوالب Sass المستوردة بالمُوجّه <code>[[Sass/@ rules|@import]]</code>. قد يكون ذلك سلسلة نصيّة، أو كائنات لأسماء المسارات، أو أصنافًا فرعية من <code>Sass::Importers::Base</code>. قيمة هذه الخاصيّة الافتراضيَّة هي مجلّد العمل الحالي. أمّا في Rack، أو Rails، أو Merb فقيمتها هي قيمة <code>:template_location</code>. مسار التحميل معلومٌ أيضًا من <code>Sass.load_paths</code> ومن متغيّر البيئة <code>SASS_PATH</code>. | |||
=== <code>:filesystem_importer</code> === | |||
صنفٌ فرعيٌّ مُشتقٌّ من الصنف <code>Sass::Importers::Base</code> يُستخدم لمعالجة السلاسل النصيّة الكاملة لمسارات التحميل. يُفترض أن يُؤدي هذا الخيار إلى استيراد الملفات من نظام الملفات (filesystem). ينبغي أن يكون هذا الصنف صنفًا كائنيًا (Class object) يرث من <code>Sass::Importers::Base</code> بحيث تقبل الدالة البانية (constructor) معاملًا واحدًا على شكل سلسلة نصّية (وقيمة ذاك المعامل هي مسار التحميل). قيمة هذه الخاصيّة الافتراضية هي <code>Sass::Importers::Filesystem</code>. | |||
=== <code>:sourcemap</code> === | |||
تتحكّم في كيفيَّة إنشاء الخرائط المصدريّة (sourcemaps) التي تُبيّن للمتصفح كيفيَّة العثور على أنماط Sass المسؤولة عن توليد كل نمط CSS على حدة. هناك ثلاث قيم صالحة لها. القيمة الأولى هي <code>:auto</code> التي تُستعمل لاستخدام روابط URI نسبية (relative URI) حيث أمكن ذلك على افتراض أنّ ملف الأنماط المصدري سيكون متاحًا على أيّ خادم تستخدمه، وأنّ موقعه النسبي سيكون كما هو في الملفات المحليَّة. إن لم تكن روابط URI النسبيَّة متوافرةً، فسيُستخدم بدلًا من ذلك الروابط التي تبدأ بالبروتوكول "file:". القيمة الثانية هي <code>:file</code> التي ستستخدم البروتوكول "file:" دومًا وستعمل محليًا أي لا يمكن نشرها إلى خادم بعيد. القيمة الثالثة هي <code>:inline</code> التي ستُضمِّن النصّ المصدري الكامل الموجود في الخريطة المصدريَّة. وهي محمولة إلى أقصى حد ولكن يمكن أن تنشئ ملفات خرائط مصدريَّة كبيرةً جدًّا. القيمة الأخيرة التي يمكن استخدامها هي، <code>:none</code> التي تؤدي إلى عدم توليد أيّ خريطة مصدريّة بالمُطلق. | |||
=== <code>:line_numbers</code> === | |||
عند إعطائها القيمة <code>true</code>، تؤدِّي إلى إظهار رقم السطر والملف حيث عُرّف المُحدِّد (selector) في ملف [[CSS]] المُصرَّف على شكل تعليق. هذا مفيدٌ لأجل التنقيح، خاصةً عند استخدام [[Sass/@ rules|الاستيرادات]] [[Sass/mixins|والمخاليط]] (mixins). يمكن أيضًا أن يسمى هذا الخيار <code>:line_comments</code>. تُعطَّل هذه الراية تلقائيًا عند استخدام نمط المُخرجات <code>:compressed</code> أو الخيارين <code>:debug_info/:trace_selectors</code>. | |||
=== <code>:trace_selectors</code> === | |||
عند إعطائها القيمة <code>true</code>، فسيظهَر دليل كامل يحتوي [[Sass/@ rules|الاستيرادات]] [[Sass/mixins|والمخاليط]] قبل كل محدّد. قد يكون هذا مفيدًا لأجل تنقيح الأخطاء داخل المتصفّح في ملفات الأنماط المستوردة وعند تضمين [[Sass/mixins|المخاليط]] (mixins). هذا الخيار يستبدِل الخيار <code>:line_comments</code> ويُستبدَل بالخيار <code>:debug_info</code>. تُعطَّل تلقائيًا عند استخدام نمط المُخرجات <code>:compressed</code>. | |||
=== <code>:debug_info</code> === | |||
عند إعطائها القيمة <code>true</code>، فسيظهر رقم السطر والملف حيث عُرّف المُحدد في ملف [[CSS]] المُصرّف في شكلٍ يمكن أن يفهمه المتصفح. وهي مفيدة عند اقترانها بالإضافة [https://addons.mozilla.org/en-US/firefox/addon/103988 FireSass Firebug] لأجل عرض اسم ملف Sass ورقم السطر. ستُعطَّل تلقائيًا عند استخدام نمط المُخرجات <code>:compressed</code>. | |||
=== <code>:custom</code> === | |||
هي خيار متاح للتطبيقات الفرديَّة لإتاحة البيانات لدوال Sass المخصّصة. | |||
=== <code>:quiet</code> === | |||
عند إعطائها القيمة <code>true</code>، فستعطّل التحذيرات (warnings). | |||
== اختيار الصياغة == | == اختيار الصياغة == | ||
ستستخدمُ أداة سطر الأوامر الخاصة | ستستخدمُ أداة سطر الأوامر الخاصة بلغة Sass امتدادَ الملف لتحديد الصياغة المُستخدمة، ولكنّ قد لا يتوافر اسم الملف دائمًا. الصياغة الافتراضيَّة في سطر الأوامر للغة Sass هي الصياغة الإزاحيَّة ولكن يمكنك أن تمرّر إليه الخيار <code>--scss</code> إن كنت تريد أن تؤوّل المدخلات على أنَّها مكتوبة بالصياغة SCSS. بدلًا من ذلك، يمكنك استخدام برنامج سطر الأوامر الخاص باللغة SCSS والذي يشبه بالضبط برنامج Sass لكنّ الصياغة الافتراضيَّة فيه هي الصياغة SCSS. | ||
== الترميزات == | == الترميزات == | ||
عند | عند تشغيل Sass على [[Ruby|روبي]] 1.9 وما بعدها، فإنّها تُدرك ترميز الأحرف المستخدم في الملفات. تتّبع Sass [http://www.w3.org/TR/2013/WD-css-syntax-3-20130919/#determine-the-fallback-encoding مواصفة CSS] لتحديد ترميز ملف الأنماط، وتَرجع إلى ترميز السلاسل النصيَّة للغة [[Ruby|روبي]]. هذا يعني أنّها ستتحقَّق من علامة ترتيب البايتات (byte order mark)، ثمّ التصريح <code>[[CSS/@charset|@charset]]</code>، ثمّ ترميز سلاسل روبي النصّية (أي Ruby string encoding). وإذا لم يُضبَط أيٌّ من تلك فستفترض أنّ الوثيقة مكتوبة بترميز UTF-8. | ||
استخدم التصريح <code>[[CSS/@charset|@charset]]</code> صراحةً لتحديد ترميز ملفات الأنماط مثلما هو الحال في [[CSS]]. أضف السطر <code>@charset "encoding-name"</code> في بداية ملف الأنماط (قبل أي مسافة بيضاء أو تعليق) وستُفسِّره Sass على أنّه الترميز المُعيَّن. لاحظ أنّه مهما كان الترميز الذي تستخدمه، فيجب أن يكون قابلًا للتحويل إلى الترميز Unicode. | |||
ستكتب Sass دائمًا بالترميز UTF-8. وستشمل التصريح <code>[[CSS/@charset|@charset]]</code> إذا وفقط إذا كان الملف يحتوي محارف من غير محارف ASCII. أما في الوضع المضغوط (compressed mode)، | ستكتب Sass دائمًا بالترميز UTF-8. وستشمل التصريح <code>[[CSS/@charset|@charset]]</code> إذا وفقط إذا كان الملف يحتوي محارف من غير محارف ASCII. أما في الوضع المضغوط (compressed mode)، فستُستخدَم علامة ترتيب البايتات الخاصَّة بالترميز UTF-8 (أي UTF-8 byte order mark) بدلًا من التصريح <code>[[CSS/@charset|@charset]]</code>. | ||
== مصادر == | == مصادر == | ||
* [https://sass-lang.com/documentation/file.SASS_REFERENCE.html#using_sass قسم Using Sass من توثيق Sass الرسمي]. | * [https://sass-lang.com/documentation/file.SASS_REFERENCE.html#using_sass قسم Using Sass من توثيق Sass الرسمي]. | ||
[[تصنيف:Sass|{{SUBPAGENAME}}]] | |||
المراجعة الحالية بتاريخ 06:56، 20 مايو 2018
يمكن استخدام Sass بثلاث طرائق هي: كأداة سطر أوامر، أو كوحدةٍ مستقلة لروبي، أو كمُلحقة في أيّ بيئة عمل تدعم Rack، بما في ذلك Ruby on Rails و Merb.
تثبيت Sass
الخطوة الأولى لاستخدام Sass هي تثبيت الجوهرة (gem) Sass:
gem install sass
إن كنت تستخدم نظام ويندوز، فقد تحتاج إلى تثبيت روبي أولاً. لتشغيل Sass من سطر الأوامر، يكفي أن تكتب الأمر الآتي:
sass input.scss output.css
يمكنك أيضًا إخبار Sass بمراقبة الملف وتحديث ملف CSS الناتج عند كلِّ تغيُّرٍ في ملف Sass:
sass --watch input.scss:output.css
إن كان لديك مجلَّد يحتوي على عدِّة ملفات Sass، فيمكنك أيضًا إخبار Sass بمراقبة ذلك المجلَّد بأكمله:
sass --watch app/sass:public/stylesheets
للإطلاع على التوثيقٍ الشامل لجميع خيارات الأمر sass، استعمل الأمر sass --help.
إنّ استخدام Sass في الكود البرمجي لروبي بسيطٌ جدًّا، إذ يمكنك بعد تثبيت الجوهرة Sass استخدامها بتشغيل require "sass" واستخدام Sass::Engine كالآتي:
engine = Sass::Engine.new("#main {background-color: #0000ff}", :syntax => :scss)
engine.render #=> "#main { background-color: #0000ff; }\n"
مُلحقات Rack/Rails/Merb
لإتاحة Sass في الإصدارات السابقة لإصدار Rails 3، أضف السطر التالي إلى environment.rb:
config.gem "sass"
أمّا في Rails 3، فأضف السطر التالي إلى Gemfile بدلًا من ذلك:
gem "sass"
لإتاحة Sass في Merb، أضف السطر التالي إلى الملف config/dependencies.rb:
dependency "merb-haml"
أمّا لإتاحة Sass في تطبيقات Rack، فأضف السّطرين التاليين إلى config.ru:
require 'sass/plugin/rack'
use Sass::Plugin::Rack
لا تعمل أنماط Sass بطريقة عمل العروض (views) نفسها فهي لا تتضمّن محتوًى ديناميكيًا، لذا ليس من الضروري توليد CSS سوى عند تحديث ملف Sass. توضع الملفات .sass و .scss افتراضيًا في المجلَّد public/stylesheets/sass (يمكن تخصيص ذلك باستخدام الخيار :template_location) ثمّ يتم تصريفها (compiled)، عند الحاجة، إلى ملفات CSS مقابلة لتلك الموجودة ووضعها في المجلَّد public/stylesheets. على سبيل المثال، سيُصرَّف الملف public/stylesheets/sass/main.scss إلى public/stylesheets/main.css.
التخزين المؤقت
افتراضيًّا، تخزِّن Sass مؤقتًا القوالب المُصرّفة (compiled templates) والمجزوءات (partials). يسرِّع هذا عمليّة إعادة تصريف المجموعات الكبيرة من ملفات Sass بشكلٍ كبيرٍ، ويعمل بشكل أفضل إذا قُسِّمَت قوالب Sass إلى ملفاتٍ منفصلة لأجل استيرادها -عبر @import- في ملف واحدٍ كبير.
في غياب إطار عمل، تضع Sass القوالب المخزّنة مؤقتًا في مجلَّد sass-cache.. أمَّا في روبي و Merb، فستُخزَّن في tmp/sass-cache. يمكن تخصيص المجلَّد عبر الخيار :cache_location. إن لم ترغب في أن تستخدم تقنيةُ Sass التخزينَ المؤقَّت، فاضبط الخيار :cache إلى القيمة false.
الخيارات
يمكن تعيين الخيارات عن طريق تحديد التلبيد ((Hash Sass::Plugin#options في environment.rb في روبي أو config.ru في Rack.
Sass::Plugin.options[:style] = :compact
أو عن طريق تعيين التلبيد [Merb::Plugin.config[:sass في init.rb في Merb.
Merb::Plugin.config[:sass][:style] = :compact
أو عن طريق تمرير خيارات تلبيد إلى Sass::Engine#initialize. جميع الخيارات ذات الصّلة متاحةٌ أيضًا من خلال الرايات (flags) في سطري أوامر Sass و SCSS وهي:
:style
ضبط تنسيق مُخرجات CSS. انظر تنسيق المخرجات.
:syntax
تحديد صياغة ملف الإدخال، اختر :sass لأجل الصياغة الإزاحيَّة و :scss لأجل الصياغة SCSS. هذا مفيد فقط عندما ترغب في إنشاء نسخة من Sass::Engine بنفسك. تُضبط تلقائيًا بالشكل المناسب عند استخدام Sass::Plugin. القيمة الافتراضيَّة لهذه الخاصيّة هي sass:.
:property_syntax
إجبار الملفات المكتوبة بالصياغة الإزاحيّة على استخدام صياغة واحدة لأجل الخاصِّيَّات. إذا لم تُستخدَم الصياغة الصحيحة فسيُطلَق خطأ. تفرض new: استخدام النقطتين بعد اسم الخاصيَّة. على سبيل المثال: color: #0f3 أو width: $main_width. أمّا old: فتفرض استخدام النقطتين قبل اسم الخاصِّيَّة. على سبيل المثال: color #0f3: أو width $main_width:. افتراضيًا، كلا الصياغتين صالحتان وهذا ليس له أيّ تأثيرٍ على ملفات SCSS.
cache:
تحديد ما إذا كان ينبغي تخزين ملفات Sass المُحلّلة (parsed) مؤقتًّا للحصول على سرعة أكبر. القيمة الافتراضيَّة هي true.
read_cache:
إن ضُبِطَ هذا الخيار دون ضبط الخيار cache:، فستُقرأ النّسخ المخزّنة مؤقتًا لتقنية Sass إن كانت موجودة، ولن يُكتب عليها إن لم تكن موجودة.
cache_store:
إن أُسنِد لهذه الخاصِّيَّة نسخةٌ من صنف فرعي من Sass::CacheStores::Base، فسيستخدم مكانُ التخزين المؤقَّت هذا لتخزين واسترجاع النتائج المصرّفة والمخزَّنة. القيمة الافتراضيَّة هي Sass::CacheStores::Filesystem والتي ستُهيئ باستخدام الخيار :cache_location.
never_update:
تحديد ما إذا كان ينبغي تحديث ملفات CSS، حتى لو تغيّر ملف القالب. إعطاء هذا الخيار القيمة true قد يحسِّن الأداء قليلًا. قيمته الافتراضيّة هي false. ولا معنى لها إلا في Rack، أو Ruby on Rails، أو Merb.
always_update:
تحديد ما إذا كان ينبغي تحديث ملفات CSS عند الدخول إلى وحدة تحكم (controller) في كلِّ مرَّة، في مقابل إيقاف التحديث في حالة تعديل القالب. القيمة الافتراضيَّة هي false. ولا معنى لها إلّا في Rack، أو Ruby on Rails، أو Merb.
:always_check
تحديد ما إذا كان ينبغي التحقّق من إمكانيَّة تحديث قالب Sass عند الدّخول إلى وحدة تحكم، في مقابل إيقاف عمليّة التحديث عند بدء تشغيل الخادم. إذا حُدِّث قالب Sass، فسيُعاد تصريفه، وسيُكتب على ملف CSS المقابل. القيمة الافتراضيَّة لهذه الخاصِّيَّة هي false في وضع الإنتاج (production mode)، أو true خلافًا لذلك، ولا معنى لها إلا في Rack، أو Ruby on Rails، أو Merb.
:poll
عندما تكون قيمتها true، سيستخدم دومًا الاستطلاع الخلفي (polling backend) لأجل Sass::Plugin::Compiler#watch بدلًا من نظام الملفات الخلفي الأصلي.
:full_exception
تحديد ما إذا كان الخطأ في الكود البرمجي للّغة Sass سيجعل Sass توفّر وصفًا مفصلًا داخل ملف CSS المُولّد. إذا أُعطِيتْ لهذه الخاصية القيمة true، فسيُعرَض الخطأ جنبًا إلى جنب مع رقم السطر ومقتطف من الكود المصدري على شكل تعليقٍ في ملف CSS وفي الجزء العلوي أيضًا من الصفحة (في المتصفحات المدعومة). خلاف ذلك، سيُطلَق استثناء في الكود البرمجي في روبي. القيمة الافتراضيَّة لهذه الخاصيَّة هي false في وضع الإنتاج، أو true خلاف ذلك.
:template_location
تحديد مسار المجلَّد الجذري لقالب Sass الخاصّ بتطبيقك. في حال كانت تلبيدًا (hash)، فسيُتجاهل :css_location وسيُعيّن هذا الخيار رابطًا (mapping) بين مجلّدي المدخلات والمخرجات. يمكن أيضًا إعطاء هذه الخاصيًة قائمة مكوّنة من قوائم ثنائيَّة (2-element lists) بدلًا من التلبيد. القيمة الافتراضيَّة هي css_location + "/sass"، ولا معنى لها إلا في Rack، أو Ruby on Rails، أو Merb. لاحظ أنّه في حال حُدِّدَت عدَّة مواقع للقالب، فستُوضَع جميعًا في مسار الاستيراد، ممّا يسمح لك بالاستيراد منها. تذكر أنّه نظرًا لتعدد الصيغ المحتملة التي يمكن أن يكون عليها، فيجب تعيين هذا الخيار بشكل مباشرٍ، وليس الدخول إليه أو تعديله. استخدم بدلًا من ذلك التابع Sass::Plugin#template_location_array، والتابع Sass::Plugin#add_template_location والتابع Sass::Plugin#remove_template_location.
:css_location
تحديد المسار حيث يجب أن تُكتب مُخرجات CSS. يتم تجاهل هذا الخيار في حالة كان :template_location تلبيدًا. القيمة الافتراضيَّة هي "./public/stylesheets"، ولا معنى لها إلا في Rack، أو Ruby on Rails، أو Merb.
:cache_location
تحديد المسار حيث يجب أن تُكتب ملفات sassc المُخزّنة مؤقتًا. القيمة الافتراضيَّة هي "./tmp/sass-cache" في Rails و Merb، أو "./.sass-cache" خلاف ذلك. في حال ضُبِطَ الخيار :cache_store، فسيتم تجاهلها.
:unix_newlines
إن كانت قيمتها true، فسيُستخدم نمط السطر الجديد المٌعتمد في أنظمة يونكس عند كتابة الملفات. لا معنى لها إلا في نظام ويندوز، وعندما تتولى Sass كتابة الملفات فقط (في Rack، أو Rails، أو Merb، وذلك عند استخدام Sass::Plugin مباشرةً، أو عند استخدام سطر الأوامر).
:filename
تحديد اسم الملف الذي يتم تقديمه. ويُستخدم فقط لأجل التبليغ عن الأخطاء، ويُعيّن تلقائيًّا عند استخدام Rack، أو Rails أو Merb.
:line
رقم السطر الأول من قالب Sass. يُستخدم للإبلاغ عن أرقام الأسطر في الأخطاء. استعمال هذه الراية مفيد في حال ضُمِّن قالب Sass في ملف روبي.
:load_paths
تحديد مسار المصفوفة التي تحتوي على مسارات الملفات أو المستورِدات التي ينبغي البحث فيها عن قوالب Sass المستوردة بالمُوجّه @import. قد يكون ذلك سلسلة نصيّة، أو كائنات لأسماء المسارات، أو أصنافًا فرعية من Sass::Importers::Base. قيمة هذه الخاصيّة الافتراضيَّة هي مجلّد العمل الحالي. أمّا في Rack، أو Rails، أو Merb فقيمتها هي قيمة :template_location. مسار التحميل معلومٌ أيضًا من Sass.load_paths ومن متغيّر البيئة SASS_PATH.
:filesystem_importer
صنفٌ فرعيٌّ مُشتقٌّ من الصنف Sass::Importers::Base يُستخدم لمعالجة السلاسل النصيّة الكاملة لمسارات التحميل. يُفترض أن يُؤدي هذا الخيار إلى استيراد الملفات من نظام الملفات (filesystem). ينبغي أن يكون هذا الصنف صنفًا كائنيًا (Class object) يرث من Sass::Importers::Base بحيث تقبل الدالة البانية (constructor) معاملًا واحدًا على شكل سلسلة نصّية (وقيمة ذاك المعامل هي مسار التحميل). قيمة هذه الخاصيّة الافتراضية هي Sass::Importers::Filesystem.
:sourcemap
تتحكّم في كيفيَّة إنشاء الخرائط المصدريّة (sourcemaps) التي تُبيّن للمتصفح كيفيَّة العثور على أنماط Sass المسؤولة عن توليد كل نمط CSS على حدة. هناك ثلاث قيم صالحة لها. القيمة الأولى هي :auto التي تُستعمل لاستخدام روابط URI نسبية (relative URI) حيث أمكن ذلك على افتراض أنّ ملف الأنماط المصدري سيكون متاحًا على أيّ خادم تستخدمه، وأنّ موقعه النسبي سيكون كما هو في الملفات المحليَّة. إن لم تكن روابط URI النسبيَّة متوافرةً، فسيُستخدم بدلًا من ذلك الروابط التي تبدأ بالبروتوكول "file:". القيمة الثانية هي :file التي ستستخدم البروتوكول "file:" دومًا وستعمل محليًا أي لا يمكن نشرها إلى خادم بعيد. القيمة الثالثة هي :inline التي ستُضمِّن النصّ المصدري الكامل الموجود في الخريطة المصدريَّة. وهي محمولة إلى أقصى حد ولكن يمكن أن تنشئ ملفات خرائط مصدريَّة كبيرةً جدًّا. القيمة الأخيرة التي يمكن استخدامها هي، :none التي تؤدي إلى عدم توليد أيّ خريطة مصدريّة بالمُطلق.
:line_numbers
عند إعطائها القيمة true، تؤدِّي إلى إظهار رقم السطر والملف حيث عُرّف المُحدِّد (selector) في ملف CSS المُصرَّف على شكل تعليق. هذا مفيدٌ لأجل التنقيح، خاصةً عند استخدام الاستيرادات والمخاليط (mixins). يمكن أيضًا أن يسمى هذا الخيار :line_comments. تُعطَّل هذه الراية تلقائيًا عند استخدام نمط المُخرجات :compressed أو الخيارين :debug_info/:trace_selectors.
:trace_selectors
عند إعطائها القيمة true، فسيظهَر دليل كامل يحتوي الاستيرادات والمخاليط قبل كل محدّد. قد يكون هذا مفيدًا لأجل تنقيح الأخطاء داخل المتصفّح في ملفات الأنماط المستوردة وعند تضمين المخاليط (mixins). هذا الخيار يستبدِل الخيار :line_comments ويُستبدَل بالخيار :debug_info. تُعطَّل تلقائيًا عند استخدام نمط المُخرجات :compressed.
:debug_info
عند إعطائها القيمة true، فسيظهر رقم السطر والملف حيث عُرّف المُحدد في ملف CSS المُصرّف في شكلٍ يمكن أن يفهمه المتصفح. وهي مفيدة عند اقترانها بالإضافة FireSass Firebug لأجل عرض اسم ملف Sass ورقم السطر. ستُعطَّل تلقائيًا عند استخدام نمط المُخرجات :compressed.
:custom
هي خيار متاح للتطبيقات الفرديَّة لإتاحة البيانات لدوال Sass المخصّصة.
:quiet
عند إعطائها القيمة true، فستعطّل التحذيرات (warnings).
اختيار الصياغة
ستستخدمُ أداة سطر الأوامر الخاصة بلغة Sass امتدادَ الملف لتحديد الصياغة المُستخدمة، ولكنّ قد لا يتوافر اسم الملف دائمًا. الصياغة الافتراضيَّة في سطر الأوامر للغة Sass هي الصياغة الإزاحيَّة ولكن يمكنك أن تمرّر إليه الخيار --scss إن كنت تريد أن تؤوّل المدخلات على أنَّها مكتوبة بالصياغة SCSS. بدلًا من ذلك، يمكنك استخدام برنامج سطر الأوامر الخاص باللغة SCSS والذي يشبه بالضبط برنامج Sass لكنّ الصياغة الافتراضيَّة فيه هي الصياغة SCSS.
الترميزات
عند تشغيل Sass على روبي 1.9 وما بعدها، فإنّها تُدرك ترميز الأحرف المستخدم في الملفات. تتّبع Sass مواصفة CSS لتحديد ترميز ملف الأنماط، وتَرجع إلى ترميز السلاسل النصيَّة للغة روبي. هذا يعني أنّها ستتحقَّق من علامة ترتيب البايتات (byte order mark)، ثمّ التصريح @charset، ثمّ ترميز سلاسل روبي النصّية (أي Ruby string encoding). وإذا لم يُضبَط أيٌّ من تلك فستفترض أنّ الوثيقة مكتوبة بترميز UTF-8.
استخدم التصريح @charset صراحةً لتحديد ترميز ملفات الأنماط مثلما هو الحال في CSS. أضف السطر @charset "encoding-name" في بداية ملف الأنماط (قبل أي مسافة بيضاء أو تعليق) وستُفسِّره Sass على أنّه الترميز المُعيَّن. لاحظ أنّه مهما كان الترميز الذي تستخدمه، فيجب أن يكون قابلًا للتحويل إلى الترميز Unicode.
ستكتب Sass دائمًا بالترميز UTF-8. وستشمل التصريح @charset إذا وفقط إذا كان الملف يحتوي محارف من غير محارف ASCII. أما في الوضع المضغوط (compressed mode)، فستُستخدَم علامة ترتيب البايتات الخاصَّة بالترميز UTF-8 (أي UTF-8 byte order mark) بدلًا من التصريح @charset.