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

ביולי 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 לא נקראת יותר על ידי הליבה שלה, כך שאם הפונקציה setText מכילה לוגיקה, צריך להעביר אותה אל חבילת הפונקציות הטיפול בערכים, לפונקציה 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_;
}

התכונה 'חסימה' מטפלת באופן אוטומטי ב:

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

מה צריך לעשות?

• אימות ערכים (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_);
};

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

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

מה צריך לעשות?

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

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