מאמתים

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

הערה: החתימה בשדה 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);
  }
};

כל אחת מהשיטות שלמעלה יכולה להיכלל בתוך extension, שיתמוך בפורמט JSON.

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

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

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

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

ערך החזרה שעבר שינוי

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

דוגמה לכלי התיקוף שמבצע שינוי:

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

ערך של החזרת ערך null

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

דוגמה לכלי לאימות נתוני ביטול:

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

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

הערך של זה

החלק הפנימי של כלי התיקוף מתייחס לשדה 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);
  }
};