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

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

משוב

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

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