پلاگین ها

افزونه یک قطعه کد مستقل است که قابلیتی را به Blockly اضافه می‌کند. برای مثال، ممکن است یک فیلد سفارشی اضافه کند، یک قالب جدید تعریف کند یا یک رندرکننده سفارشی ارائه دهد. افزونه‌ها معمولاً از طریق npm بسته‌بندی و توزیع می‌شوند.

برای آشنایی سریع با افزونه‌ها، به بحث مروری افزونه‌ها (۲۰۲۱) مراجعه کنید.

اگر می‌خواهید افزونه‌ی خودتان را بسازید، به افزودن افزونه مراجعه کنید.

افزونه‌های شخص ثالث و اول شخص

افزونه‌های شخص ثالث توسط تیم Blockly پشتیبانی می‌شوند و تحت دامنه @blockly در npm منتشر می‌شوند. آن‌ها به گونه‌ای طراحی شده‌اند که در طیف گسترده‌ای از برنامه‌های Blockly قابل استفاده باشند.

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

یک افزونه پیدا کنید

  • از Blockly Plugins & Demos دیدن کنید، که دموهای زنده‌ای از افزونه‌های شخص ثالث دارد.

  • در npm keyword:blockly-plugin جستجو کنید. افزونه‌هایی که دامنه @blockly دارند توسط تیم Blockly منتشر شده‌اند. برای نتایج گسترده‌تر، keyword:blockly یا blockly را جستجو کنید.

  • به دایرکتوری blockly-samples/plugins در گیت‌هاب مراجعه کنید، که مخزن افزونه‌های شخص ثالث است. هر افزونه دارای یک فایل README است که رفتار و کاربرد مورد نظر آن را شرح می‌دهد.

نصب یک افزونه

توصیه می‌کنیم افزونه‌ها را با یک مدیر بسته مانند npm یا yarn نصب کنید. این کار دریافت به‌روزرسانی‌ها را آسان می‌کند.

  • نصب افزونه با استفاده از مدیر بسته

    ان‌پی‌ام 

    npm install @blockly/field-angle

    نخ 

    yarn add @blockly/field-angle

  • نصب افزونه بدون مدیر بسته

    باز کردن 

    <script src="https://unpkg.com/@blockly/field-angle"></script>

    همچنین می‌توانید مخزن گیت‌هاب حاوی افزونه را کپی کنید. برای افزونه‌های شخص ثالث، این blockly-samples است.

برای دیدن اینکه آیا دستورالعمل نصب اضافی وجود دارد یا خیر، فایل README افزونه را بررسی کنید.

از یک افزونه استفاده کنید

هر افزونه متفاوت است، بنابراین برای اطلاعات بیشتر در مورد نحوه استفاده از آن افزونه، به فایل README افزونه مراجعه کنید. مثال زیر نحوه استفاده از افزونه @blockly/field-angle را نشان می‌دهد:

  1. کد را از افزونه وارد کنید. نحوه انجام این کار بستگی به نحوه نصب افزونه دارد.

    npm یا yarn 

    import Blockly from 'blockly';
import {registerFieldAngle} from '@blockly/field-angle';

    باز کردن

    نیازی به استفاده از دستور import نیست.

    مخزن کلون شده 

    import {registerFieldAngle} from 'path/to/plugin';

  2. افزونه را در صورت نیاز راه‌اندازی کنید. افزونه‌هایی که فیلدهای سفارشی ارائه می‌دهند، اغلب از شما می‌خواهند که فیلد را ثبت کنید:

    registerFieldAngle();

  3. از افزونه استفاده کنید.

    Blockly.common.defineBlocksWithJsonArray([
  {
    type: "my_angle_block",
    message0: "%1 degrees",
    args0: [
      {
        // Use @blockly/field-angle.
        type: "field_angle",
        name: "FIELDNAME",
        value: 45,
      },
    ],
    output: null,
    style: 'math_blocks'
  },
]);

    میدانی برای انتخاب زاویه از یک صفحه مدرج ۳۶۰ درجه.

نسخه‌های افزونه

افزونه‌های موجود در blockly-samples از نسخه‌بندی معنایی استفاده می‌کنند که برای استفاده از یک نسخه اصلی جدید، نیاز به شکستن تغییرات دارد. هر افزونه جدیدی که هسته را به‌روزرسانی می‌کند، نسخه اصلی 0 را خواهد داشت تا نشان دهنده توسعه اولیه باشد .

اکثر افزونه‌ها، بسته blockly را به عنوان یک peerDependency به جای یک dependency شامل می‌شوند. دلیل این امر این است که ما فرض می‌کنیم شما قبلاً Blockly را نصب کرده‌اید. (استفاده از یک افزونه بدون استفاده از Blockly منطقی نیست.) این به شما امکان می‌دهد نسخه Blockly را خودتان مدیریت کنید، اما همچنین شما را ملزم می‌کند که package.json افزونه را بررسی کنید تا حداقل نسخه Blockly مورد نیاز خود را تعیین کنید. اگر افزونه‌ای به‌روزرسانی شود و به نسخه جدیدتری از Blockly نیاز داشته باشد، این یک تغییر اساسی محسوب می‌شود و نسخه اصلی آن افزایش می‌یابد.

وقتی افزونه‌ای را به package.json برنامه‌تان اضافه می‌کنید، پیش‌فرض این است که قبل از نسخه، یک هشتک قرار دهید:

"dependencies": {
  "@blockly/field-angle": "^5.0.12"
}

این به npm اجازه می‌دهد هر نسخه فرعی (minor) را در سطح یا بالاتر از نسخه ذکر شده نصب کند، بنابراین نسخه 5.0.20 یا 5.1.0 کار می‌کند، اما نسخه اصلی جدید مانند 6.0.1 کار نمی‌کند. وقتی به نسخه جدیدی از Blockly به‌روزرسانی می‌کنید، ایده خوبی است که بررسی کنید آیا افزونه‌های شما نیز می‌توانند به نسخه اصلی جدید به‌روزرسانی شوند یا خیر.