أدوات التحقّق

أداة التحقّق هي دالة تتلقّى القيمة الجديدة للحقول، ثمّ تتخذ إجراءً بشأنها. وهي طريقة بسيطة لتخصيص حقل. تتيح لك هذه السمة تشغيل وظيفة عند تغيير قيمة حقل أو تعديل الإدخال أو حصر القيم المقبولة.

بعض الأمثلة الشائعة:

• حصر حقل نصي على قبول الأحرف فقط
• فرض عدم ترك حقل نصي فارغًا
• يجب أن يكون التاريخ في المستقبل.
• تعديل شكل أحد المربّعات استنادًا إلى قائمة منسدلة

ملاحظة: تعدّل أدوات التحقّق قيمة الحقل وليس نصه.

أنواع أدوات التحقّق

يتم تنفيذ أدوات التحقّق في أوقات مختلفة حسب نوعها.

أدوات التحقّق من صحة الفئة هي جزء من تعريف فئة نوع الحقل، ويتم استخدامها عادةً لتقييد نوع القيمة المسموح بها في الحقل (على سبيل المثال، لا تقبل حقول الأرقام سوى الأحرف الرقمية). يتم تنفيذ أدوات التحقّق من صحة الفئة على جميع القيم التي تم تمريرها إلى الحقل (بما في ذلك القيمة التي تم تمريرها إلى الدالة الإنشائية).

لمزيد من المعلومات حول أدوات التحقّق من صحة الفئات، راجِع قسم تنفيذ أداة التحقّق من صحة الفئات في مقالة إنشاء حقل مخصّص.

يتم تحديد أدوات التحقّق المحلية عند إنشاء الحقل. يتم تنفيذ أدوات التحقّق المحلية على جميع القيم التي يتم تمريرها إلى الحقل باستثناء القيمة التي يتم تمريرها إلى الدالة الإنشائية. وهذا يعني أنّها تعمل على:

• القيم الواردة في ملف 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.

قد تختلف قيمة الحقل بشكل كبير حسب نوع الحقل الذي يتم التحقّق من صحته (على سبيل المثال، سيخزّن حقل الأرقام رقمًا، بينما سيخزّن حقل إدخال النص سلسلة)، لذا من الأفضل قراءة المستندات الخاصة بحقلك المحدّد قبل إنشاء أداة التحقّق.

ملاحظة: لا تقبل الحقول القابلة للتعديل أدوات التحقّق من الصحة، لذا احرص على مراجعة مستندات الحقل المحدّد.

القيم المعروضة

تحدّد القيمة المعروضة من أداة التحقّق الإجراء التالي الذي سيتّخذه الحقل. هناك ثلاثة احتمالات:

القيمة المعروضة غير صحيحة

قيمة معدَّلة أو مختلفة تصبح بعد ذلك القيمة الجديدة للحقل يُستخدَم هذا الإجراء غالبًا لتنظيف قيمة، مثلاً عن طريق إزالة المسافات البيضاء الزائدة.

مثال على أداة التحقّق المعدِّلة:

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

قيمة الإرجاع الفارغة

قيمة فارغة، ما يعني أنّ القيمة المحدّدة غير صالحة في معظم الحالات، سيتجاهل الحقل قيمة الإدخال. يتم تحديد السلوك الدقيق من خلال 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);
};

لاحظ مرة أخرى كيف أنّ النص المعروض لا يعكس بالضرورة قيمة الحقل.

قيمة هذا الإجراء

داخل أداة التحقّق، يشير 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);
  }
};