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

פלאגינים שמספקים ספריות של הגדרות של בלוקים הם דרך מצוינת לשתף את הבלוקים לשימוש חוזר עם קהילת Blockly. כדי שספריית הבלוקים שלכם תהיה רב-תכליתית ומועילה ככל האפשר, פיתחנו את ההנחיות הבאות.

הנחיות

• חשוב שיהיה למשתמשיםקל להתקין את כל הבלוקים שלך, ולוודא אפשרי של המשתמשים להתקין רק בלוקים מסוימים או חלקים מסוימים שהם בוחרים.
  • התקנה קלה של הכול: כדי לעשות זאת, אפשר לספק פונקציה שמתקינה כל חלק שנדרש להגדרת בלוק יחידה (כמו mutators, ‏ extensions, ‏ mixins, ‏ שדות וכו'). אפשר גם לספק פונקציה שתתקין בבת אחת את כל הבלוקים שמוצעים על ידי הפלאגין.
  • מאפשרים לבחור חלקים ספציפיים: כדאי לייצא בנפרד את כל החלקים של הגדרת הבלוק, כדי שהמשתמשים יוכלו לייבא רק את החלקים שהם צריכים כדי ליצור בלוק מותאם אישית דומה משלהם.
• הימנעו משימוש בתופעות לוואי בפלאגין.
  • אסור להתקין בלוקים, שדות, תוספים וחלקים אחרים כתוצאה מטעינת הפלאגין. המשתמשים צריכים לשמור על שליטה על הדברים שמותקנים ומתי הם מותקנים. כך המשתמשים יכולים לייבא את החלקים הנחוצים להם בלי לדאוג שחלקים שלא נחוצים להם יותקנו.

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

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

משוב

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

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