إضافة نمط باستخدام CSS

يتم إنشاء تطبيقات Blockly من عناصر HTML وSVG. يتم تصنيف هذه العناصر باستخدام فئات CSS تحدّد ما تمثّله (مثل blocklyBlock وblocklyField) بالإضافة إلى حالتها (مثل blocklyEditing وblocklySelected). يوفّر Blockly أيضًا مجموعة تلقائية من قواعد CSS.

يمكنك استخدام CSS لتصميم تطبيقك:

  • تجاوز قواعد CSS في Blockly بقواعدك الخاصة.
  • أضِف فئات CSS الخاصة بك إلى مكوّنات Blockly للحصول على المزيد من التحديد.
  • استخدِم فئات وقواعد CSS لتحديد نمط المكوّنات المخصّصة.

فئات CSS

تستخدم تطبيقات Blockly فئات CSS لتحديد العناصر التي سيتم تصميمها. ويوفّر ذلك تحكّمًا أكثر دقة من أدوات اختيار النوع (العنصر).

فئات CSS في Blockly

تستخدم Blockly فئات CSS لتقديم الأنواع التالية من المعلومات حول عناصر HTML وSVG التي تستخدمها.

  • النوع: تحدّد معظم فئات CSS في Blockly ما يمثّله العنصر. على سبيل المثال، يتم تصنيف العنصر الجذر الخاص بكتلة على أنّه blocklyBlock. يتم تصنيف بعض العناصر باستخدام فئات متعددة، وكل فئة تكون أكثر تحديدًا من الفئة السابقة. على سبيل المثال، يتم تصنيف العنصر الجذر لحقل إدخال النص على أنّه blocklyField وblocklyInputField وblocklyTextInputField. تظل فئات الأنواع كما هي طوال مدة توفّر المكوّن.

  • الولاية: تستخدم Blockly أيضًا فئات CSS لتحديد حالة أحد المكوّنات. على سبيل المثال، عندما يكون المؤشر على حقل إدخال نص، يتم تصنيف العنصر الجذر الخاص به باستخدام الفئة blocklyEditing. عندما يتم نقل المؤشر بعيدًا، تتم إزالة هذه الفئة.

  • معلومات إضافية تستخدم Blockly بعض فئات CSS لتقديم معلومات إضافية. على سبيل المثال، يحتوي العنصر الذي تم إدراجه <div> على فئات توفّر اسم أداة العرض الحالية ومظهر مساحة العمل. تبقى هذه الفئات بشكل عام كما هي طوال فترة استخدام التطبيق.

أسهل طريقة لمعرفة فئات CSS التي يستخدمها Blockly هي فتح أدوات المطوّرين في المتصفّح وفحص العناصر التي يستخدمها تطبيقك.

فئات CSS المخصّصة

يمكنك استخدام فئات CSS مخصّصة لتوفير المزيد من الخصوصية لمكوّنات Blockly.

مساحات العمل

لإضافة فئة CSS أو إزالتها من عملية إدخال مساحة عمل <div>، استخدِم WorkspaceSvg.addClass أو WorkspaceSvg.removeClass.

مجموعات الأدوات

لإضافة فئة CSS إلى زر أو تصنيف في صندوق أدوات، استخدِم المفتاح web-class في تعريف JSON الخاص بصندوق الأدوات. لمزيد من المعلومات، يُرجى الاطّلاع على الأزرار والتصنيفات.

لتجاوز فئات CSS المستخدَمة في الأجزاء المختلفة من الفئة، استخدِم المفتاح cssConfig في تعريف JSON الخاص بالفئة. يتيح لك ذلك تنسيق فئات فردية. لمزيد من المعلومات، يُرجى الاطّلاع على فئة CSS.

Blocks

لإضافة فئات CSS إلى حظر مخصّص، مرِّر سلسلة أو مجموعة من السلاسل إلى المفتاح classes.

Blockly.common.defineBlocksWithJsonArray([{
  "type": "string_length",
  "message0": 'length of %1',
  "args0": [
    {
      "type": "input_value",
      "name": "VALUE",
      "check": "String",
    }
  ],
  "classes": "myStringLengthBlock",
  "output": "Number",
  "colour": 160,
}]);

يمكنك أيضًا إضافة فئة CSS أو إزالتها من عنصر <g> في أحد المربّعات من خلال استدعاء BlockSvg.addClass أو BlockSvg.removeClass.

حقول التصنيفات

لإضافة أو إزالة فئة CSS من العنصر <text> المستخدَم من قِبل حقل تصنيف أو حقل تصنيف قابل للتسلسل، استخدِم FieldLabel.setClass. يمكنك أيضًا تمرير اسم فئة إلى الدالة الإنشائية للتصنيف.

فئات CSS والمكوّنات المخصّصة

عند إنشاء مكوّن مخصّص، استخدِم إحدى الطرق التالية لإضافة فئات CSS مخصّصة:

  • إذا كان المكوّن فئة فرعية من Field أو Icon، عليك إلغاء طريقة initView. على سبيل المثال:

    class MyCustomField extends Blockly.FieldTextInput {
  ...

  initView() {
    super.initView();

    // Add custom CSS class so we can style the field.
    if (this.fieldGroup_) {
      Blockly.utils.dom.addClass(this.fieldGroup_, 'myCustomField');
    }
  }
}

    لمزيد من المعلومات، يُرجى الاطّلاع على تخصيص الحقول باستخدام CSS أو إنشاء طريقة عرض الرمز.

  • عند إنشاء عنصر SVG، مرِّر صفك إلى Blockly.utils.dom.createSvgElement:

    this.svgRoot = Blockly.utils.dom.createSvgElement(Svg.G, {'class': 'myCustomComponent'});

  • عند إنشاء عنصر HTML، استخدِم Blockly.utils.dom.addClass:

    const myDiv = document.createElement('div');
Blockly.utils.dom.addClass(myDiv, 'myInformation');

لإضافة صفوف أو إزالتها بعد الإنشاء، استخدِم Blockly.utils.dom.addClass أو Blockly.utils.dom.removeClass.

setMyHighlight(highlight) {
  if (highlight) {
    Blockly.utils.dom.addClass(this.svgRoot, 'myHighlight');
  } else {
    Blockly.utils.dom.removeClass(this.svgRoot, 'myHighlight');
  }
}

خلفية قواعد CSS

إذا كنت على دراية بسمات تصميم SVG وCSS، يمكنك تخطّي هذا القسم.

خصائص تصميم SVG مقارنةً بخصائص CSS

يتم تصميم عناصر SVG باستخدام خصائص تصميم SVG. ويمكن استخدامها كسمات في عناصر SVG (المعروفة أيضًا باسم سمات العرض) أو في قواعد CSS. وبالتالي، فإنّ جميع ما يلي يؤدي الغرض نفسه.

<!-- SVG file with presentation attributes. -->
<circle fill="red" ... />

<!-- SVG file with <style> tag. -->
<style>
  circle {fill:red;}
</style>
<circle ... />

/* External CSS file.*/
circle {fill:red;}

<!-- SVG file with inline style. -->
<circle style="fill:red;" ... />

تتعلّق قائمة خصائص تصميم SVG بقائمة خصائص CSS، ولكنّها تختلف عنها:

  • المفهوم نفسه، الاسم نفسه على سبيل المثال، تستخدم كل من SVG وCSS السمة direction لتحديد ما إذا كان النص مكتوبًا من اليمين إلى اليسار أو من اليسار إلى اليمين.
  • المفهوم نفسه، ولكن الاسم مختلف على سبيل المثال، تستخدم SVG fill لتحديد لون التعبئة، بينما تستخدم CSS background-color.
  • خدمة CSS فقط تتضمّن CSS العديد من الخصائص غير المتوفّرة في SVG، مثل margin وpadding.
  • ملفات SVG فقط: تحتوي SVG على بعض الخصائص غير المتوفّرة في CSS، مثل x وy.

لذلك، إذا كنت تريد تصميم عنصر SVG، استخدِم خصائص تصميم SVG. إذا كنت تريد تصميم عنصر HTML، استخدِم سمات CSS.

التتالي في CSS

يحدّد التتالي في CSS الأولويات لقواعد CSS، والتي تحدّد القاعدة التي سيتم استخدامها إذا كانت أكثر من قاعدة واحدة تنطبق على خاصية وعنصر معيّنين. يغطّي التتالي المبسّط التالي أجزاء التتالي الأكثر استخدامًا في Blockly، وقد يساعدك في الإجابة عن السؤال "لماذا لا يعمل CSS؟".

التسلسل الهرمي المبسّط

لتحديد القاعدة التي تنطبق على عنصر وسمة معيّنَين، اتّبِع الخطوات التالية وتوقّف عندما تبقى قاعدة واحدة فقط:

  1. اجمع كل القواعد التي تنطبق على الموقع والعنصر.
  2. إذا كانت أي قواعد تتضمّن التعليق التوضيحي !important، تجاهِل جميع القواعد التي لا تتضمّن التعليق التوضيحي !important.

  3. اختَر القواعد ذات الدقة الأعلى.

    • تكون سمات العرض في SVG ذات مستوى تحديد صفر.
    • يتم احتساب درجة التحديد للقواعد في علامة <style> أو ورقة أنماط خارجية بشكل طبيعي.
    • تكون لسمات الأنماط المضمّنة (الأنماط التي يتم ضبطها بواسطة سمة style) درجة تحديد أعلى من أي محدّد.

  4. اختَر القاعدة التي تظهر في آخر المستند.

  5. إذا لم تنطبق أي قاعدة، يتم اكتساب قيمة السمة من العنصر الرئيسي للعنصر.

لا تأخذ هذه الخوارزمية في الاعتبار الأجزاء التالية من التتالي:

  • السمة transition التي لها الأولوية القصوى يستخدم Blockly بعضًا من هذه الأنواع.
  • قاعدة @media at-rule يستخدم Blockly أحد هذه الأنواع.
  • القواعد التي يحدّدها المتصفّح أو المستخدم
  • قواعد @scope و@layer التي تبدأ بعلامة @ والسمة animation، وهي غير مستخدَمة في Blockly

قواعد CSS

تحدّد قواعد CSS طريقة تصميم تطبيقك. توفّر Blockly مجموعة تلقائية من القواعد يمكنك استبدالها بقواعدك الخاصة.

قواعد CSS في Blockly

توفّر Blockly مجموعة تلقائية من قواعد CSS. تؤثّر طريقة ومكان إضافة هذه القواعد في أولويتها.

علامات الأنماط

يتم تحديد معظم قواعد CSS في Blockly في علامتَي <style>. وبما أنّ هذه العلامات تظهر بالقرب من أعلى الصفحة، تكون لقواعدها أولوية أقل من القواعد التي تتضمّن التفاصيل نفسها وتظهر في وقت لاحق من الصفحة.

قواعد Blockly.css.register

عند إدخال Blockly، تتم إضافة العلامة <style> كعلامة فرعية للعلامة <head>. تأتي القواعد في هذه العلامة من:

  • مساحة الاسم Blockly.css للاطّلاع على هذه القواعد، افتح الملف core/css.ts وابحث عن let content.
  • المكوّنات الفردية التي تستدعي Blockly.css.register لإضافة قواعد CSS خاصة بالمكوّن بما أنّ css.register تضيف هذه القواعد إلى نهاية السلسلة content، فإنّ لها أولوية أعلى من القواعد التي لها نفس درجة التحديد والتي تمت إضافتها في وقت سابق. للاطّلاع على هذه القواعد، راجِع المكالمات إلى Blockly.css.register.

إذا كنت لا تريد استخدام هذه القواعد، اضبط خيار إعدادات css على false. في هذه الحالة، تكون أنت المسؤول عن توفير مجموعة بديلة من قواعد CSS.

قواعد العارض

عند إنشاء مثيل لأداة العرض، تتم إضافة علامة <style> تحتوي على قواعد CSS خاصة بأداة العرض كعنصر ثانوي للعلامة <head>. يُرجى العِلم أنّه تتم إضافة هذه القواعد دائمًا، ولا تتأثر بخيار الإعداد css. للاطّلاع على هذه القواعد، ابحث عن طريقة getCss_ في أداة العرض.

الأنماط المضمّنة

يتم تحديد الأنماط المضمّنة باستخدام السمة style، ويتم إنشاؤها بشكل عام عند إنشاء نموذج المستند (DOM) لأحد المكوّنات. للحصول على قائمة جزئية، يُرجى الاطّلاع على طلب البحث هذا على GitHub.

يتم تطبيق الأنماط المضمّنة مباشرةً على العنصر الذي تظهر فيه، وتكون درجة تحديدها أعلى من أي أداة اختيار. لهذا السبب، يتطلّب إلغاء هذه الإعدادات بشكل عام استخدام !important تعليق توضيحي.

سمات العرض التقديمي لملفات SVG

سمات العرض في SVG هي خصائص تنسيق SVG تُستخدَم كسمات لعناصر SVG. وتبلغ درجة تحديدها صفرًا، ولا يمكن أن تحتوي على تعليق توضيحي !important، لذا تكون لها الأولوية الأدنى بين جميع قواعد Blockly. تنشئ Blockly هذه السلاسل بشكل عام من خلال عمليات استدعاء إلى createSvgElement.

إضافة قواعد CSS الخاصة بك

يمكنك إضافة قواعد CSS الخاصة بك باستخدام الطرق نفسها التي تستخدمها Blockly:

  • اتّصِل بـ Blockly.css.register قبل إدخال Blockly. ستتم إضافة قواعدك بعد قواعد Blockly، وستكون لها أولوية أعلى من قواعد Blockly التي تتضمّن التفاصيل نفسها.
  • أضِف علامة <style> أو رابطًا إلى ورقة أنماط خارجية كعنصر فرعي لاحق للعلامة <head>. بما أنّ Blockly يضيف قواعده كأول عنصرَين ثانويَين للعلامة <head>، ستكون لقواعدك أولوية أعلى من قواعد Blockly التي تتضمّن التفاصيل نفسها.
  • استخدِم الأنماط المضمّنة لإضافة أنماط إلى العناصر في مكوّن مخصّص. وستكون هذه القواعد أكثر تحديدًا من أي قواعد تتضمّن محدّدًا.
  • استخدِم سمات العرض التقديمي على عناصر SVG في مكوّن مخصّص. وستكون هذه القواعد أقل تحديدًا من أي قواعد تتضمّن محدّدًا.

تحديد المشاكل وحلّها

إذا لم يكن CSS يعمل، إليك بعض الأسباب المحتملة:

  • أنت تستخدم خصائص CSS على عنصر SVG أو خصائص تصميم SVG على عنصر HTML. اطّلِع على خصائص تصميم SVG مقارنةً بخصائص CSS.

  • تتمتّع قاعدتك بأولوية أقل من قاعدة أخرى. ويحدث ذلك عادةً بسبب انخفاض مستوى الدقة. في ما يلي بعض الطرق المحتملة لحلّ هذه المشكلة:

    • استخدِم محدّد فئة بدلاً من محدّد نوع (عنصر).
    • استخدام أدوات اختيار متعددة
    • إذا أمكن، أضِف فئة مخصّصة إلى العنصر المستهدَف واستخدِم هذه الفئة في القاعدة.
    • كحلّ أخير، أضِف تعليقًا توضيحيًا !important إلى القاعدة. هذا هو خيارك الوحيد إذا تم تحديد قاعدة متضاربة باستخدام نمط مضمّن (السمة style).

  • تتضمّن قاعدتك مستوى التفصيل نفسه الذي تتضمّنه قاعدة أخرى، ولكنّها تظهر في موضع أبكر في الصفحة. إذا لم تتمكّن من زيادة دقة القاعدة، يمكنك نقلها إلى موضع لاحق في الصفحة.

هناك نوعان من قواعد CSS لا يمكنك تجاهلهما:

  • السمات التي يتم ضبطها داخل قاعدة transition
  • قواعد !important يحدّدها المتصفّح