با CSS استایل کنید

برنامه‌های Blockly از عناصر HTML و SVG ساخته شده‌اند. این عناصر با کلاس‌های CSS برچسب‌گذاری شده‌اند که مشخص می‌کنند چه چیزی را نشان می‌دهند (مثلاً blocklyBlock ، blocklyField ) و همچنین حالت آنها (مثلاً blocklyEditing ، blocklySelected ) را نشان می‌دهند. Blockly همچنین مجموعه‌ای پیش‌فرض از قوانین CSS را ارائه می‌دهد.

شما می‌توانید از CSS برای استایل‌دهی به برنامه خود استفاده کنید:

• قوانین CSS Blockly را با قوانین خودتان لغو کنید.
• برای جزئیات بیشتر، کلاس‌های CSS خودتان را به کامپوننت‌های Blockly اضافه کنید.
• از کلاس‌ها و قوانین CSS برای استایل‌دهی به کامپوننت‌های سفارشی استفاده کنید.

نکته: ساده‌ترین راه برای استایل‌دهی به Blockly استفاده از قالب‌ها است. اگر به کنترل دقیق‌تری نیاز دارید، از CSS استفاده کنید.

کلاس‌های CSS

برنامه‌های Blockly از کلاس‌های CSS برای شناسایی عناصری که باید استایل‌بندی شوند استفاده می‌کنند. این کار کنترل دقیق‌تری نسبت به انتخابگرهای نوع (عنصر) ارائه می‌دهد.

کلاس‌های CSS بلاکلی

Blockly از کلاس‌های CSS برای ارائه انواع اطلاعات زیر در مورد عناصر HTML و SVG مورد استفاده خود استفاده می‌کند.

• نوع. اکثر کلاس‌های CSS بلوکی مشخص می‌کنند که یک عنصر چه چیزی را نشان می‌دهد. برای مثال، عنصر ریشه یک بلوک با برچسب blocklyBlock مشخص می‌شود. برخی از عناصر با چندین کلاس مشخص می‌شوند که هر کدام خاص‌تر از قبلی هستند. برای مثال، عنصر ریشه یک فیلد ورودی متن با برچسب‌های blocklyField ، blocklyInputField و blocklyTextInputField مشخص می‌شود. کلاس‌های نوع در طول عمر یک کامپوننت ثابت می‌مانند.

• حالت. Blockly همچنین از کلاس‌های CSS برای مشخص کردن حالت یک کامپوننت استفاده می‌کند. برای مثال، وقتی مکان‌نما روی یک فیلد ورودی متن است، عنصر ریشه آن با کلاس blocklyEditing برچسب‌گذاری می‌شود. وقتی مکان‌نما دور می‌شود، این کلاس حذف می‌شود.

• اطلاعات تکمیلی. Blockly از چند کلاس CSS برای ارائه اطلاعات تکمیلی استفاده می‌کند. برای مثال، <div> تزریقی دارای کلاس‌هایی است که نام رندرکننده و قالب فعلی فضای کاری را ارائه می‌دهند. این کلاس‌ها عموماً در طول عمر برنامه ثابت می‌مانند.

ساده‌ترین راه برای کشف اینکه Blockly از چه کلاس‌های CSS استفاده می‌کند، باز کردن ابزارهای توسعه‌دهنده مرورگر و بررسی عناصر مورد استفاده برنامه شماست.

کلاس‌های CSS سفارشی

شما می‌توانید از کلاس‌های CSS سفارشی برای ارائه ویژگی‌های خاص‌تر به کامپوننت‌های Blockly استفاده کنید.

فضاهای کاری

برای اضافه کردن یا حذف کردن یک کلاس CSS از تزریق <div> یک فضای کاری، WorkspaceSvg.addClass یا WorkspaceSvg.removeClass را فراخوانی کنید.

جعبه ابزارها

برای افزودن یک کلاس CSS به یک دکمه یا برچسب در جعبه ابزار، از کلید web-class در تعریف JSON جعبه ابزار خود استفاده کنید. برای اطلاعات بیشتر، به بخش دکمه‌ها و برچسب‌ها مراجعه کنید.

برای لغو کلاس‌های CSS مورد استفاده برای بخش‌های مختلف یک دسته‌بندی، از کلید cssConfig در تعریف JSON آن دسته‌بندی استفاده کنید. این به شما امکان می‌دهد تا دسته‌بندی‌های جداگانه را استایل‌دهی کنید. برای اطلاعات بیشتر، به بخش CSS دسته‌بندی مراجعه کنید.

بلوک‌ها

برای افزودن کلاس‌های 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,
}]);

همچنین می‌توانید با فراخوانی BlockSvg.addClass یا BlockSvg.removeClass ، یک کلاس CSS را از عنصر <g> یک بلوک اضافه یا حذف کنید.

فیلدهای برچسب

برای اضافه کردن یا حذف کردن یک کلاس CSS از عنصر <text> که توسط یک فیلد label یا فیلد label قابل سریال‌سازی استفاده می‌شود، FieldLabel.setClass را فراخوانی کنید. همچنین می‌توانید نام کلاس را به سازنده‌ی label ارسال کنید.

کلاس‌های 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');
  }
}

هشدار: dom.addClass یا dom.removeClass برای اضافه کردن کلاس‌ها به کامپوننت‌های نوشته شده توسط دیگران، از جمله Blockly، یا حذف کلاس‌ها از آنها استفاده نکنید. این کار ممکن است منجر به نتایج غیرقابل پیش‌بینی شود.

پس‌زمینه قوانین 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 از یکی از این‌ها استفاده می‌کند.
• قوانینی که توسط مرورگر یا کاربر تعیین می‌شوند.
• قوانین at-rules مربوط به @scope و @layer و ویژگی animation که توسط Blockly استفاده نمی‌شوند.

قوانین CSS

قوانین CSS نحوه‌ی استایل‌دهی به برنامه‌ی شما را مشخص می‌کنند. Blockly مجموعه‌ای از قوانین پیش‌فرض را ارائه می‌دهد که می‌توانید آن‌ها را با قوانین خودتان لغو کنید.

قوانین CSS به صورت مسدود

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، تابع Blockly.css.register را فراخوانی کنید. قوانین شما بعد از قوانین Blockly اضافه می‌شوند و اولویت بالاتری نسبت به قوانین Blockly با همان ویژگی دارند.
• یک تگ <style> یا پیوند به یک برگه سبک خارجی را به عنوان فرزند بعدی تگ <head> اضافه کنید. از آنجا که Blockly قوانین خود را به عنوان دو فرزند اول تگ <head> اضافه می‌کند، قوانین شما اولویت بالاتری نسبت به قوانین Blockly با همان ویژگی خواهند داشت.
• از استایل‌های درون‌خطی برای اضافه کردن استایل به عناصر در یک کامپوننت سفارشی استفاده کنید. این قوانین نسبت به هر قانونی که دارای انتخابگر است، از سطح اختصاصی بالاتری برخوردار خواهند بود.
• از ویژگی‌های ارائه روی عناصر SVG در یک کامپوننت سفارشی استفاده کنید. این قوانین نسبت به هر قانونی که دارای انتخابگر است، از سطح اختصاصی بودن کمتری برخوردار خواهند بود.

عیب‌یابی

اگر CSS شما کار نمی‌کند، دلایل احتمالی آن عبارتند از:

• شما از ویژگی‌های CSS روی یک عنصر SVG یا از ویژگی‌های استایل‌بندی SVG روی یک عنصر HTML استفاده می‌کنید. به مقایسه ویژگی‌های استایل‌بندی SVG و ویژگی‌های CSS مراجعه کنید.

• قانون شما اولویت کمتری نسبت به قانون دیگر دارد. این معمولاً به دلیل سطح ویژگی پایین‌تر است. راه‌های ممکن برای رفع این مشکل عبارتند از:

  • به جای انتخابگر نوع (عنصر)، از انتخابگر کلاس استفاده کنید.
  • از چندین انتخابگر استفاده کنید.
  • در صورت امکان، یک کلاس سفارشی به عنصر هدف خود اضافه کنید و از این کلاس در قانون خود استفاده کنید.
  • به عنوان آخرین راه حل، یک حاشیه‌نویسی !important به قانون خود اضافه کنید. اگر یک قانون رقیب با استفاده از یک سبک درون‌خطی (ویژگی style ) مشخص شده باشد، این تنها انتخاب شماست.

• قانون شما همان سطح اختصاصی بودن قانون دیگری را دارد، اما در صفحه زودتر اتفاق می‌افتد. اگر نمی‌توانید سطح اختصاصی بودن قانون خود را افزایش دهید، آن را به صفحه بعد منتقل کنید.

دو نوع قانون CSS وجود دارد که نمی‌توانید آنها را لغو کنید:

• ویژگی‌هایی که درون یک قانون transition تنظیم شده‌اند.
• !important مشخص شده توسط مرورگر.