أدوات التحقق

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

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

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

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

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

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

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

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

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

• القيم المضمّنة في 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, '');
};

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

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

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

قيمة هذا

يشير العنصر داخل أداة التحقّق this إلى الحقل، وليس إلى المجموعة. إذا كنت بحاجة إلى الوصول إلى المجموعة داخل أداة التحقّق، استخدِم الدالة getSourceBlock. يمكنك أيضًا استخدام دالة الربط لتعيين السياق الذي يتم من خلاله استدعاء أداة التحقق.

رمز نموذجي باستخدام 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);
  }
};