バリデータ

バリデータは、フィールドの新しい値を受け取って処理する関数です。フィールドを簡単にカスタマイズできます。フィールドの値が変更されたときに機能をトリガーしたり、入力を変更したり、許容される値を制限したりできます。

一般的な例を以下に示します。

  • テキスト フィールドで文字のみを受け付けるように制限する。
  • テキスト フィールドに入力が必須であることを指定する。
  • 日付が将来の日付であることを必須にする。
  • プルダウンに基づいてブロックの形状を変更する。

バリデータの種類

バリデータは、バリデータの種類に応じて異なるタイミングで実行されます。

クラス バリデータはフィールド タイプのクラス定義の一部であり、通常はフィールドで許可される値の型を制限するために使用されます（数値フィールドでは数値のみが許可されます）。クラス バリデータは、フィールドに渡されるすべての値（コンストラクタに渡される値を含む）で実行されます。

クラス バリデータの詳細については、カスタム フィールドの作成のクラス バリデータの実装をご覧ください。

ローカル バリデータは、フィールドの作成時に定義されます。ローカル バリデータは、コンストラクタに渡された値を除く、フィールドに渡されたすべての値に対して実行されます。つまり、コンテナは次の環境で実行されます。

  • XML に含まれる値。
  • setValue に渡される値。
  • setFieldValue に渡される値。
  • ユーザーが変更した値。

クラス バリデータはゲートキーパーとして機能するため、ローカル バリデータの前に実行されます。値が正しい型であることを確認してから渡します。

値の検証の順序と一般的な値の詳細については、値をご覧ください。

ローカル検証ツールの登録

ローカル バリデータは次の 2 つの方法で登録できます。

  • フィールドのコンストラクタに直接追加されます。
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 形式をサポートできます。

フィールドの値は、検証対象のフィールドのタイプによって大きく異なる場合があります（たとえば、数値フィールドには数値が保存され、テキスト入力フィールドには文字列が保存されます）。そのため、バリデータの作成前に、特定のフィールドのドキュメントを確認することをおすすめします。

戻り値

バリデータの戻り値によって、フィールドの次の処理が決まります。次の 3 つの可能性があります。

変更された戻り値

変更された値または別の値。これは、フィールドの新しい値になります。これは、末尾の空白文字の削除など、値のクリーンアップによく使用されます。

変更検証ツールの例:

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

変更バリデータを含むテキスト入力フィールド

Null 戻り値

null: 指定された値が無効であることを意味します。ほとんどの場合、フィールドは入力値を無視します。正確な動作は、フィールドの doValueInvalid_ 関数で指定されます。

Nulling バリデータの例:

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

ヌル化検証ツールを使用したテキスト入力フィールド

未定義の戻り値

未定義（または return ステートメントなし）または入力値。つまり、入力値がフィールドの新しい値になります。通常、このようなタイプのバリデータは変更リスナーとして機能します。

リスナー バリデータの例:

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