验证器

验证器是一种函数，用于接受字段的新值，然后对其执行操作。它们是自定义字段的一种简单方法。借助这些事件，您可以在字段值发生变化时触发功能、修改输入或限制可接受的值。

一些常见示例：

  • 将文本字段限制为仅接受字母。
  • 要求文本字段非空。
  • 要求日期为未来的日期。
  • 根据下拉菜单修改块的形状。

验证器类型

验证器的执行时间因其类型而异。

类验证器是字段类型的类定义的一部分，通常用于限制字段允许的值的类型（例如，数字字段仅接受数字字符）。系统会对传递给字段的所有值（包括传递给构造函数的值）运行类验证器。

如需详细了解类验证器，请参阅“创建自定义字段”中的实现类验证器部分。

本地验证器是在构建字段时定义的。本地验证器会对传递给字段的所有值（除了传递给构造函数的值）进行运行。这意味着它们在以下平台上运行：

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

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 返回值

null，表示给定值无效。在大多数情况下，该字段会忽略输入值。确切行为由字段的 doValueInvalid_ 函数指定。

置 null 验证器示例：

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

包含 null 化验证器的文本输入字段

未定义的返回值

未定义（或没有返回语句）或输入值，这意味着输入值应成为字段的新值。这类验证器通常充当更改监听器。

监听器验证器示例：

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