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

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

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

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

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

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

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

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

لمزيد من المعلومات عن مدقّقي الصفوف، اطّلِع على القسم تنفيذ مدقّق صف في إنشاء حقل مخصّص.

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

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