כלי אימות

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

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

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

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

סוגי מאמתים

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

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

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

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

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

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

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

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

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

• נוספו ישירות בבונה של השדה.

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

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.

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

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

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

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

Modified Return Value

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

דוגמה ל-Modifying Validator:

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

ערך החזרה אפס

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

דוגמה ל-Nulling Validator:

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

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

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

דוגמה ל-Listener Validator:

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

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

הערך של

בתוך כלי תיקוף, 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);
  }
};