שדרוג של שדה מותאם אישית

ביולי 2019 (גרסה 2.20190722) נוסף API של שדות עם קידוד מפורט יותר. היא נועדה להיות תואמת לדורות קודמים ככל האפשר. המשמעות היא שאם יצרתם שדה מותאם אישית לפני יולי 2019, סביר להניח שהוא ימשיך לפעול. לפני שמחליטים אם צריך לשדרג את השדה המותאם אישית, כדאי לקרוא את הקטע אזורים מסוכנים ולבצע בדיקה יסודית של השדה.

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

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

אזורים מסוכנים

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

Blockly.Field.register

השדות לא רשומים יותר דרך Blockly.Field.register();. יש עכשיו מרחב שמות fieldRegistry שמטפל ברישום.

Blockly.Field.register('my_field_name', myFieldClass);

הופך ל:

Blockly.fieldRegistry.register('my_field_name', myFieldClass);

setText

הפונקציה setText לא מופעלת יותר על ידי ליבת Blockly, ולכן אם הפונקציה setText מכילה לוגיקה, צריך להעביר אותה לחבילת הפונקציות של value handling, לפונקציה getText ולפונקציות הרינדור (בהתאם לפעולה המדויקת של הפונקציה setText).

CustomFields.UpgradeField.prototype.setText = function(newText) {
  // Do validation.
  if (typeof newText != 'string' || newText === this.text_) {
    return;
  }

  // Fire event.
  if (this.sourceBlock_ && Blockly.Events.isEnabled()) {
    Blockly.events.fire(new Blockly.Events.BlockChange(
        this.sourceBlock_, 'field', this.name, this.text_, newText
    ));
  }

  // Update text value.
  this.text_ = 'prefix' + newText;

  // Rerender.
  this.size_.width = 0;
};

הופך ל:

CustomFields.UpgradeField.prototype.doClassValidation_ = function(newValue) {
  if (typeof newValue != 'string') {
    return null;
  }
  return newValue;
};

CustomFields.UpgradeField.prototype.getText = function() {
  return  'prefix' + this.value_;
}

‫Blockly מטפל אוטומטית ב:

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

תצטרכו לטפל ב:

• אימות ערך (doClassValidation_).
• טקסט השדה (getText).
• ממשק משתמש של שדה

הערה: מומלץ לשנות את כל הקריאות ל-setText לקריאות ל-setValue, כי setValue תומך באימות ו-setText לא.

שדרוגים מומלצים

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

ניתן לסריאליזציה

מידע נוסף על המאפיינים EDITABLE ו-SERIALIZABLE זמין במאמר מאפיינים שאפשר לערוך וליצור מהם סדרות.

CustomFields.UpgradeField.prototype.SERIALIZABLE = true;

אפשר להתעלם מהאזהרה שבהמשך, אבל אפשר לפתור אותה על ידי הגדרת המאפיין SERIALIZABLE:

Detected an editable field that was not serializable. Please define
SERIALIZABLE property as true on all editable custom fields. Proceeding
with serialization.

האזהרה שלמעלה מציינת שמערכת Blockly מניחה שרוצים לבצע סריאליזציה של השדה (כי המאפיין EDITABLE הוא true), אבל היא לא יכולה להיות בטוחה עד שמגדירים את המאפיין SERIALIZABLE. אם לא תעשו כלום, הכול יפעל כמו שצריך והשדה יסודר, אבל תקבלו אזהרות במסוף.

size_.width

this.size_.width = 0;

הופך ל:

this.isDirty_ = true;

אפשר להתעלם מהאזהרה שבהמשך, אבל אפשר לפתור אותה על ידי הגדרת המאפיין isDirty_ במקום המאפיין size_.width:

Deprecated use of setting size_.width to 0 to rerender a field. Set
field.isDirty_ to true instead.

האזהרה שלמעלה מציינת ש-Blockly זיהה שאתם משתמשים בשיטה ישנה לעיבוד מחדש של שדה, ומומלץ להשתמש בשיטה החדשה.

מידע נוסף על המאפיין isDirty_ זמין במאמר isDirty_.

init

הפונקציה init הפכה לפונקציית תבנית כדי לצמצם את כמות הקוד הכפול בתת-מחלקות.

CustomFields.UpgradeField.prototype.init = function() {
  if (this.fieldGroup_) {
    // Already initialized once.
    return;
  }

  // Call superclass.
  CustomFields.UpgradeField.superClass_.init.call(this);

  // Create DOM elements.
  this.extraDom_ = Blockly.utils.dom.createSvgElement('image',
      {
        'height': '10px',
        'width': '10px'
      });
  this.extraDom_.setAttributeNS('http://www.w3.org/1999/xlink',
      'xlink:href', 'image.svg');
  this.extraDom_.style.cursor = 'pointer';
  this.fieldGroup_.appendChild(this.extraDom_);

  // Bind events.
  this.mouseOverWrapper_ =
    Blockly.browserEvents.bind(
        this.getClickTarget_(), 'mouseover', this, this.onMouseOver_);
  this.mouseOutWrapper_ =
    Blockly.browserEvents.bind(
        this.getClickTarget_(), 'mouseout', this, this.onMouseOut_);

  // Render.
  this.setValue(this.getValue());
};

הופך ל:

CustomFields.UpgradeField.prototype.initView = function() {
  CustomFields.UpgradeField.superClass_.initView.call(this);

  this.extraDom_ = Blockly.utils.dom.createSvgElement('image',
      {
        'height': '10px',
        'width': '10px'
      });
  this.extraDom_.setAttributeNS('http://www.w3.org/1999/xlink',
      'xlink:href', 'image.svg');
  this.extraDom_.style.cursor = 'pointer';
  this.fieldGroup_.appendChild(this.extraDom_);
};

CustomFields.UpgradeField.prototype.bindEvents_ = function() {
  CustomFields.UpgradeField.superClass_.bindEvents_.call(this);

  this.mouseOverWrapper_ =
    Blockly.bindEvent_(
        this.getClickTarget_(), 'mouseover', this, this.onMouseOver_);
  this.mouseOutWrapper_ =
    Blockly.bindEvent_(
        this.getClickTarget_(), 'mouseout', this, this.onMouseOut_);
};

כלומר, מעכשיו Blockly מטפל אוטומטית בפעולות הבאות:

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

תצטרכו לטפל ב:

• הוספת רכיבי DOM נוספים (initView).
• הוספה של קשרי אירועים נוספים (bindEvents_).
• הסרת קישורי אירועים (dispose).

חשוב: מומלץ לבצע את כל יצירת ה-DOM בתוך initView כי זה הכי יעיל. מומלץ לבצע רפקטורינג אם יצירת ה-DOM מתבצעת בתוך הקונסטרקטור, setText, setValue או render_.

onMouseDown_

CustomFields.UpgradeField.prototype.onMouseDown_ = function(e) {
  // ...
};

הופך ל:

CustomFields.UpgradeField.prototype.showEditor_ = function() {
  // ...
}

מומלץ להגדיר את הפונקציה showEditor_ לטיפול בלחיצות עכבר ולא את הפונקציה onMouseDown_, כי היא מאפשרת להעביר קלט דרך מערכת התנועות.

מידע נוסף על עורכים זמין במאמר עורכים.

setValue

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

text_

מומלץ אף פעם לא לגשת ישירות למאפיין text_ של השדה או לעדכן אותו. במקום זאת, משתמשים בפונקציה getText כדי לגשת לטקסט הקריא למשתמש של השדה, ובפונקציה setValue כדי לעדכן את הערך המאוחסן של השדה.

מידע נוסף על הערך של שדה לעומת הטקסט שלו זמין במאמר מבנה השדה.

קבלת עזרה בשדרוג

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

מה צריך לספק

כדי לקבל עזרה, מומלץ לשאול שאלות ספציפיות:

לא מומלץ: "מה הבעיה בשדה הזה?"

לא מומלץ גם להשתמש בהנחיה: "עזור לי לשדרג את השדה הזה".

מומלץ: 'טקסט השדה לא מתעדכן כמו שצריך'.

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

לא מומלץ:

• תמונות של קוד.
• הקוד לא שלם.

המלצה:

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

איפה לפרסם

אפשר לפרסם שאלות לגבי השדרוג בפורום המפתחים של Blockly.

אם אתם בטוחים שהבעיה היא ב-blockly core, אתם יכולים גם לפרסם בעיה ב-GitHub של blockly. אם תחליטו לפרסם בעיה, תצטרכו למלא את כל הפרטים הנדרשים.