הוספת שדה של פלאגין כדי לחסום את היצרן

בעזרת Blockly Developer Tools אפשר ליצור בלוקים בהתאמה אישית באמצעות בלוקים! יש בו תמיכה בשדות שמפורסמים כיישומי פלאגין בנוסף לשדות שכוללים את הליבה של Blockly. אם יצרתם שדה בהתאמה אישית, תוכלו להוסיף בו תמיכה ל-block Fact באמצעות המדריך הזה. כדי להוסיף תמיכה בשדה המותאם אישית, צריך לפרסם אותו ב-npm. תצטרכו גם להתחייב לעדכן את השדה שלכם בהתאם לשינויים ב-Blockly, אחרת ייתכן שנצטרך להסיר אותו מ-block Fact

פיתוח במפעל בלוקים

קוד המקור של ה-Block בקמפיין נמצא במאגר הבלוקים (blockly Samples) בספרייה examples/developer-tools.

כדי לשלוח שינוי בכלים למפתחים בדוגמאות של חסימה, צריך לבצע את השלבים הטיפוסיים לפיתוח בדוגמאות של חסימה. עם זאת, בניגוד לעבודה עם יישומי פלאגין, צריך להריץ את הפקודה npm install ישירות מהספרייה examples/developer-tools, ולא ברמת הרמה הבסיסית (root) של דוגמאות חסימה.

התקנת הפלאגין

כדי שה-Block פקטורי יוכל להציג את השדה המותאם אישית בתצוגה המקדימה, הוא צריך להתקין את השדה המותאם אישית. מוסיפים את השדה כתלות ב-NPM של כלים למפתחים. לאחר מכן צריך לרשום אותו או לבצע פעולות הגדרה אחרות שנדרשות ב-developer-tools/src/blocks/index.ts.

יצירת חסימה לשדה

מכיוון שהבלוק פקטור משתמש בבלוקים כדי ליצור בלוקים בהתאמה אישית, יש צורך בבלוק שמייצג את השדה המותאם אישית.

יצירה של הגדרת החסימה

אתם צריכים לעצב את הבלוק לשדה שלכם. אם אתם רוצים לקבל מטא, אפשר אפילו לעצב אותו באמצעות Block פקטורי! הבלוק צריך לאפשר למשתמש לקבוע את ההגדרה שנדרשת על ידי השדה, כמו ערכי ברירת מחדל ושם. מוסיפים את הגדרת החסימה הזו ל-developer-tools/src/blocks/fields.ts ומייבאים אותה ב-developer-tools/src/blocks/index.ts.

הוספת בלוק לארגז הכלים

בשלב הבא צריך להוסיף את הבלוק הזה להגדרת ארגז הכלים כדי שהוא יהיה נגיש למשתמשים. ההגדרה של ארגז הכלים נמצאת ב-developer-tools/src/toolbox.ts. צריך להוסיף את הבלוק לקטגוריה "Fields".

מחוללי קוד

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

יוצרים קובץ לבלוק השדות בספרייה output-generators/fields. תצטרכו להוסיף לקובץ הזה את מחוללי הבלוקים של כל אחד מהגנרטורים הבאים. מייבאים את הקובץ הזה מהקובץ blocks/index.ts כדי שהפונקציות של מחולל קוד הבלוק ייטענו לאפליקציה.

הגדרת JavaScript

השדה javascriptDefinitionGenerator יוצר את הקוד שייכלל בהגדרת ה-JavaScript של בלוק שכולל את השדה המותאם אישית. בדרך כלל, המשמעות היא שהמחולל של קודי הבלוקים צריך להחזיר שורת קוד שנראית כמו .appendField(new YourFieldConstructor(arg1, arg2), 'userSpecifiedName'). שימו לב ששורת הקוד הזו לא כוללת נקודה ופסיק, כי קלט שמכיל מספר שדות יכלול מספר קריאות ל-appendField בשרשרת. הארגומנטים ב-constructor נשלפים מהערכים שהמשתמש הגדיר בבלוק השדות. דוגמה למחולל קוד הבלוקים הזה של FieldAngle:

javascriptDefinitionGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: JavascriptDefinitionGenerator,
): string {
  const name = generator.quote_(block.getFieldValue('FIELDNAME'));
  const angle = block.getFieldValue('ANGLE');
  return `.appendField(new FieldAngle(${angle}), ${name})`;
};

יש שני שדות על בלוק הזווית שהמשתמש גרר מהקטגוריה 'שדות' של ארגז הכלים של 'בלוק יצרן':

  • FIELDNAME: המשתמש יכול להגדיר את שם השדה בבלוק המותאם אישית שלו
  • ANGLE: המשתמש יכול להגדיר את ערך ברירת המחדל של הזווית

במחולל הבלוקים הזה, אנחנו מקבלים את ערך ברירת המחדל של הזווית ומעבירים אותו כארגומנט היחיד ל-constructor של FieldAngle. שם השדה תמיד מועבר כארגומנט השני אל appendField.

הגדרת JSON

השדה jsonDefinitionGenerator דומה, אבל זה פלט של החלק מהגדרת הבלוק של JSON שתואם לשדה. בדרך כלל, הקוד הזה הוא אובייקט JSON שכולל:

  • type: תואם לשם השדה שלך במרשם השדות של Blockly
  • name: המשתמש יכול להגדיר את שם השדה בבלוק המותאם אישית שלו
  • כל מאפיין מותאם אישית אחר שנדרש בשיטת האתחול של JSON בשדה שלכם.

הנה דוגמה שוב מ-FieldAngle:

jsonDefinitionGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: JsonDefinitionGenerator,
): string {
  const code = {
    type: 'field_angle',
    name: block.getFieldValue('FIELDNAME'),
    angle: block.getFieldValue('ANGLE'),
  };
  return JSON.stringify(code);
};

כותרות קוד

הכלי Code Header Generator יוצר את הפלט של כותרות הקוד שמוצג ב-Block פקטורי. אפשר להחליף את הפלט בין ייבוא esModule לבין תגי סקריפט, בהתאם לאופן שבו המשתמש רוצה לטעון את הקוד, כך שבעצם יהיו שתי מכונות מחולל שונות: אחת לכל פנייה. צריך להוסיף מחולל קוד בלוקים לכל אחד מהם. הנה דוגמה עבור FieldAngle:

importHeaderGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: CodeHeaderGenerator,
): string {
  generator.addHeaderLine(
    `import {registerFieldAngle, FieldAngle} from '@blockly/field-angle';`,
  );
  generator.addHeaderLine(`registerFieldAngle();`);
  return '';
};

scriptHeaderGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: CodeHeaderGenerator,
): string {
  generator.addHeaderLine(
    `<script src="https://unpkg.com/@blockly/field-angle"></script>`,
  );
  generator.addHeaderLine(`registerFieldAngle();`);
  return '';
};

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

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

לשונית גנרטור

לבסוף, יש לנו את המחולל שיוצר את הפתח להדמיה בשדה. במחולל הבלוקים הזה כותבים קוד שיוצר קוד שעוזר למשתמשים לכתוב קוד שיוצר את הקוד. עדיין מבולבל? זה קל יותר ממה שזה נשמע!

קטע המחולל של בלוק מותאם אישית כולל משתנה מוגדר מראש שמייצג כל שדה בבלוק. בנוסף, יש שדה TODO שהמשתמש צריך לסיים כדי להרכיב את כל המשתנים האלה במחרוזת הקוד הסופית שהבלוק המותאם אישית שלו יחזיר. כלומר, בדרך כלל כל מה שאתם צריכים על מחולל קוד הבלוקים שלכם הוא להחזיר את השורה שיוצרת את המשתנה המותאם אישית הזה. נניח שהמשתמש יוצר בלוק בהתאמה אישית שיוסיף קרני אור שמש לקנבס שלו. מוסיפים לבלוק שדה זווית שנקרא "SUN_DIRECTION". ה-stub של המחולל של הבלוק הזה יכלול את השורה const angle_sun_direction = block.getFieldValue("SUN_DIRECTION");. זו שורת הקוד שמחולל הבלוקים שלנו לשדה הזווית צריך להחזיר:

generatorStubGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: GeneratorStubGenerator,
): string {
  const name = block.getFieldValue('FIELDNAME');
  const fieldVar = generator.createVariableName('angle', name);
  return `const ${fieldVar} = block.getFieldValue(${generator.quote_(
    name,
  )});\n`;
};

כדי לקבל שם סטנדרטי למשתנה, תוכלו לקרוא ל-generator.createVariableName ולהעביר את סוג השדה שלכם (למשל angle, number וכו') ואת השם של המשתמש בשדה.

לבדיקה

אחרי שתכתבו את כל החלקים האלה, תוכלו להפעיל את ה-Block Proxy על ידי הרצת npm start בספרייה blockly-samples/examples/developer-tools. אמורה להיות אפשרות לגרור את הבלוק מקטגוריית השדות, להוסיף אותו לקלט בבלוק ולעקוב אחרי השינוי בפלט. חשוב לוודא שהתצוגה המקדימה של הבלוק נראית תקינה, ושהקוד של כל אחד מקטעי הפלט נכון.