כלי אימות

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

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

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

סוגי מאמתים

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

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

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

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

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

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

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

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

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

  • הוספה ישירה ב-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));
  }
};

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

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

דוגמה לאימות Nulling:

// 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;
};

שדה קלט טקסט עם מאמת לאפסה

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

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

דוגמה לאימות של מאזין:

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

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

הערך של this

בתוך כלי אימות, הערך 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);
  }
};