מאמתים

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

כמה דוגמאות נפוצות:

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

הערה: המאמתים משנים את הערך של השדה ולא את הטקסט שלו.

סוגים של מאמתים

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

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

למידע נוסף על כלים לאימות כיתות, ראו הטמעה של מאמת כיתות במאמר 'יצירת שדה מותאם אישית'.

מאמתים מקומיים מוגדרים בזמן היצירה של השדה. תיקוף מקומי פועל בכל הערכים שמועברים לשדה מלבד הערך שהועבר ל-constructor. פירוש הדבר הוא שהמודעות מוצגות ב:

• ערכים הכלולים ב-XML.
• הערכים הועברו אל setValue.
• הערכים הועברו אל setFieldValue.
• הערכים השתנו על ידי המשתמש.

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

למידע נוסף על רצף של אימות ערכים ועל ערכים באופן כללי, אפשר לעיין ב-Values (ערכים).

רישום מאמת מקומי

אפשר לרשום את המאמתים המקומיים בשתי דרכים:

• נוסף ישירות ב-constructor של שדה.

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

Blockly.Blocks['validator_example'] = {
  init: function() {
    // Remove all 'a' characters from the text input's value.
    var validator = function(newValue) {
      return newValue.replace(/\a/g, '');
    };

    this.appendDummyInput()
        .appendField(new Blockly.FieldTextInput('default', validator));
  }
};

• באמצעות setValidator.

Blockly.Blocks['validator_example'] = {
  init: function() {
    // Remove all 'a' characters from the text input's value.
    var validator = function(newValue) {
      return newValue.replace(/\a/g, '');
    };

    var field = new Blockly.FieldTextInput('default');
    field.setValidator(validator);

    this.appendDummyInput().appendField(field);
  }
};

אפשר לכלול כל אחת מהשיטות שלמעלה בתוסף כדי לתמוך בפורמט JSON.

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

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

הערכים המוחזרים

הערך המוחזר של המאמת קובע מה יהיה השדה הבא. יש שלוש אפשרויות:

ערך החזרה שהשתנה

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

דוגמה למאמת שינויים:

// Remove all 'a' characters from the text input's value.
var validator = function(newValue) {
  return newValue.replace(/\a/g, '');
};

ערך החזרה אפס

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

דוגמה למאמת null:

// Any value containing a 'b' character is invalid.  Other values are valid.
var validator = function(newValue) {
  if (newValue.indexOf('b') != -1) {
    return null;
  }
  return newValue;
};

ערך החזרה לא מוגדר

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

דוגמה למאמת האזנה:

// Log the new value to console.
var validator = function(newValue) {
  console.log(newValue);
};

חשוב לזכור שוב שהטקסט לתצוגה לא בהכרח משקף את הערך של השדה.

הערך של זה

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

קוד לדוגמה באמצעות getSourceBlock:

Blockly.Blocks['colour_match'] = {
  init: function() {
    this.appendDummyInput()
        .appendField(new Blockly.FieldColour(
            null, this.validate
        ), 'COLOUR');
    this.setColour(this.getFieldValue('COLOUR'));
  },

  validate: function(colourHex) {
    this.getSourceBlock().setColour(colourHex);
  }
};

קוד לדוגמה באמצעות bind:

Blockly.Blocks['colour_match'] = {
  init: function() {
    this.appendDummyInput()
      .appendField(new Blockly.FieldColour(
          null, this.validate.bind(this)
      ), 'COLOUR');
    this.validate(this.getFieldValue('COLOUR'));
  },

  validate: function(colourHex) {
    this.setColour(colourHex);
  }
};