أدوات التحقق

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

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

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

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

أنواع أدوات التحقّق من الصحة

تنفذ أدوات التحقق من الصحة في أوقات مختلفة بناءً على نوع عملية التحقق التي تتم.

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

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

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

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

نموذج التعليمات البرمجية باستخدام الربط:

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