פרסום ספריות בלוקים

יישומי פלאגין שמספקים ספריות של הגדרות חסימה הם דרך נהדרת לשתף בלוקים לשימוש חוזר עם הקהילה של 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 תציע כלים שיאפשרו לכם לרשום פריטים שכבר רשומים ללא שגיאות. עד אז, כדאי לבדוק מה כבר נרשם לפני שרושמים תוסף, מוט, מיקס או שדה בעצמכם.
  • חשוב להבהיר מהן הדרישות המוקדמות או של יחסי התלות הנדרשים על ידי הפלאגין או הגדרות החסימה.

• כדאי לספק פונקציות גנרטור לכל אחד מהבלוקים שתספקו.

  • השימוש בפונקציות גנרטור עצמאיות ומאפשר למשתמשים להשתמש בבלוקים בקלות בלי שיצטרכו להבין את המבנה והעיצוב שלהם. אם הם יצטרכו לכתוב פונקציות מחולל משלהם, הדבר עלול לגרום לכך שכל משתמש יבצע עבודה מיותרת.
  • JavaScript היא השפה הנפוצה ביותר ב-Blockly, כך שאם בוחרים לספק רק שפה אחת, מומלץ להשתמש ב-JavaScript, אלא אם הבלוקים שלכם מיועדים לשפה ספציפית, כמו הטמעה של ספריית Python.
  • כדאי לפרסם בעיות שמתייחסות לנושא 'עזרה' בשפות שאתם לא יכולים להטמיע בהן פונקציות של מחולל, ולקבל בקשות משיכה אם המשתמשים תורמים אותן.

  • אם כוללים פונקציית התקנה לבלוק, אפשר לאשר פרמטר 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});
    

משוב

אם יש לכם שאלות לגבי הדרך הטובה ביותר לפעול בהתאם להנחיות האלה בפלאגין, תוכלו לפנות אלינו בפורום! נשמח לראות את ספריות הבלוקים שלכם ולתת להן משוב.

שימו לב שלא כל יישומי הפלאגין מהדומיין הנוכחי שמספקים הגדרות חסימה כרגע פועלים לפי ההנחיות האלה, אבל יישומי פלאגין חדשים כן פועלים בהתאם להנחיות האלה ואנחנו מתכננים להעביר את יישומי הפלאגין הקיימים.