انتشار کتابخانه های بلوکی

افزونه‌هایی که کتابخانه‌هایی از تعاریف بلوک را ارائه می‌دهند، راه بسیار خوبی برای به اشتراک گذاشتن بلوک‌های قابل استفاده مجدد شما با انجمن Blockly هستند. برای اینکه کتابخانه بلوک شما تا حد امکان همه کاره و مفید باشد، این دستورالعمل ها را توسعه داده ایم.

رهنمودها

• نصب تمام بلوک‌های خود را برای کاربران آسان کنید و این امکان را برای کاربران فراهم کنید که فقط بلوک‌ها یا قطعاتی از بلوک‌هایی را که انتخاب می‌کنند نصب کنند.
  • نصب همه چیز را آسان کنید: می توانید این کار را با ارائه تابعی انجام دهید که هر قطعه ای را که تعریف یک بلوک نیاز دارد نصب می کند (مانند جهش دهنده ها، افزونه ها، میکسین ها، فیلدها و غیره). همچنین می توانید عملکردی را ارائه دهید که تمام بلوک های ارائه شده توسط افزونه شما را به یکباره نصب می کند.
  • امکان انتخاب قطعات خاص را فراهم کنید: شما باید تمام قطعات یک تعریف بلوک را به طور جداگانه صادر کنید، به طوری که کاربر بتواند تنها قطعات مورد نیاز خود را وارد کند تا بلاک سفارشی مشابه خود را ایجاد کند.
• از استفاده از عوارض جانبی در افزونه خود اجتناب کنید.
  • بلوک‌ها، فیلدها، برنامه‌های افزودنی و سایر قطعات نباید به عنوان یک عارضه جانبی بارگذاری افزونه شما نصب شوند. کاربران باید کنترل داشته باشند که کدام چیزها و چه زمانی نصب می شوند. این به کاربران اجازه می دهد تا قطعات مورد نیاز خود را بدون نگرانی از نصب نشدن قطعات وارد کنند.

• به جای نمونه سازی مستقیم فیلدهای جدید از رجیستری فیلد JSON استفاده کنید.

  • توصیه نمی شود - نمونه سازی مستقیم یک فیلد جدید:

      const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(new Blockly.FieldNumber(123), 'NAME');
        }
      }
    

  • توصیه می شود - رجیستری فیلد JSON:

      export const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(Blockly.fieldRegistry.fromJson({
                  name: 'field_number',
                  value: 123,
                }), 'NAME');
        }
      }
    

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

• در مورد مواردی که کاربر قبلاً نصب کرده است، فرضیات را در نظر نگیرید.

  • اگر افزونه شما به یک فیلد سفارشی یا افزونه دیگری نیاز دارد، خودتان آن فیلدها را در تابع install ارائه شده ثبت کنید.
  • به زودی، Blockly ابزارهایی را ارائه می دهد که به شما امکان می دهد موارد ثبت شده قبلی را بدون خطا ثبت کنید. تا آن زمان، ممکن است بخواهید قبل از ثبت افزونه، جهش‌دهنده، میکسین یا فیلد، آنچه قبلاً ثبت شده است را بررسی کنید.
  • در مورد هر گونه پیش نیاز یا وابستگی که توسط تعاریف پلاگین یا بلوک شما لازم است، شفاف باشید.

• ارائه توابع مولد برای هر یک از بلوک هایی که ارائه می کنید را در نظر بگیرید.

  • ارائه توابع ژنراتور که خارج از جعبه کار می کنند، استفاده از بلوک های شما را بدون نیاز به درک ساختار و طراحی آنها برای کاربران آسان تر می کند. اگر آنها مجبور باشند توابع مولد خود را بنویسند، این ممکن است منجر به انجام کارهای اضافی توسط هر کاربر شود.
  • جاوا اسکریپت رایج ترین زبان مورد استفاده در Blockly است، بنابراین اگر فقط یک زبان را برای ارائه انتخاب می کنید، ما جاوا اسکریپت را توصیه می کنیم، مگر اینکه بلاک های شما برای یک زبان خاص مانند اجرای کتابخانه پایتون ساخته شده باشند.
  • برای زبان هایی که نمی توانید توابع مولد را برای آن ها پیاده سازی کنید، مسائل مربوط به "کمک مورد نیاز" را در نظر بگیرید، و اگر کاربر آنها را ارائه کرد، درخواست های کششی را برای آنها بپذیرید.

  • اگر یک تابع نصب برای بلوک خود ارائه دهید، می توانید یک پارامتر generators اختیاری را بپذیرید. اگر کاربر یک نمونه مولد را که شما از آن پشتیبانی می کنید عبور دهد، می توانید به طور خودکار عملکرد تولید کننده کد بلوک را نصب کنید و کارهای مرتبط مانند افزودن کلمات رزرو شده را انجام دهید:

      // Your plugin's install function
      export const installMyCustomBlock(generators = {}) {
        Blockly.defineBlocks({my_custom_block: myCustomBlock});
        if (generators.javascript) {
          generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
          generators.javascript.addReservedWords('specialReservedWord');
        }
      }
    
      // How a user may install your block
      import {javascriptGenerator} from 'blockly/javascript';
      import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
      // installs the block definition and the javascript block-code generator
      installMyCustomBlock({javascript: javascriptGenerator});
    

بازخورد

اگر سؤالی در مورد چگونگی پیروی از این دستورالعمل ها در افزونه خود دارید، در انجمن به ما اطلاع دهید! ما دوست داریم کتابخانه های بلوک شما را ببینیم و در مورد آنها بازخورد ارائه کنیم.

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