Validatoren

Ein Validator ist eine Funktion, die den neuen Wert des Felds entgegennimmt und dann darauf reagiert. Sie sind eine einfache Möglichkeit, ein Feld anzupassen. Damit können Sie Funktionen auslösen, wenn sich der Wert eines Felds ändert, Eingaben ändern oder einschränken, welche Werte zulässig sind.

Hier einige Beispiele:

• Ein Textfeld so einschränken, dass nur Buchstaben akzeptiert werden.
• Ein Textfeld darf nicht leer sein.
• Ein Datum muss in der Zukunft liegen.
• Form eines Blocks basierend auf einem Drop-down-Menü ändern

Hinweis :Mit Validatoren wird der Wert eines Felds geändert, nicht der Text.

Arten von Validatoren

Validierungen werden je nach Art des Validators zu unterschiedlichen Zeiten ausgeführt.

Klassenvalidatoren sind Teil der Klassendefinition eines Feldtyps und werden in der Regel verwendet, um den Typ des vom Feld zulässigen Werts einzuschränken (z.B. akzeptieren Zahlenfelder nur numerische Zeichen). Klassenvalidatoren werden für alle Werte ausgeführt, die an das Feld übergeben werden (einschließlich des Werts, der an den Konstruktor übergeben wird).

Weitere Informationen zu Klassenvalidatoren finden Sie im Abschnitt Klassenvalidator implementieren unter „Benutzerdefiniertes Feld erstellen“.

Lokale Validatoren werden zum Zeitpunkt der Erstellung eines Felds definiert. Lokale Validatoren werden für alle Werte ausgeführt, die an das Feld übergeben werden, mit Ausnahme des Werts, der an den Konstruktor übergeben wird. Das bedeutet, dass sie auf folgenden Plattformen ausgeführt werden:

• Werte in XML.
• An setValue übergebene Werte.
• An setFieldValue übergebene Werte.
• Vom Nutzer geänderte Werte.

Klassenvalidierungen werden vor lokalen Validierungen ausgeführt, da sie wie Gatekeeper fungieren. Sie sorgen dafür, dass der Wert den richtigen Typ hat, bevor er weitergegeben wird.

Weitere Informationen zur Reihenfolge der Wertvalidierung und zu Werten im Allgemeinen finden Sie unter „Werte“.

Lokalen Validator registrieren

Lokale Validatoren können auf zwei Arten registriert werden:

• Direkt im Konstruktor eines Felds hinzugefügt.

Hinweis :Die Signatur des Feldkonstruktors kann je nach Feldtyp unterschiedlich sein.

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

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

Beide oben genannten Methoden können in eine Erweiterung eingebunden werden, um das JSON-Format zu unterstützen.

Der Wert des Felds kann je nach Art des zu validierenden Felds sehr unterschiedlich sein.In einem Zahlenfeld wird beispielsweise eine Zahl gespeichert, während in einem Texteingabefeld ein String gespeichert wird. Daher ist es am besten, die Dokumentation für Ihr spezifisches Feld zu lesen, bevor Sie eine Validierung erstellen.

Hinweis: Validatoren werden nur für bearbeitbare Felder akzeptiert. Sehen Sie sich daher die Dokumentation des jeweiligen Felds an.

Rückgabewerte

Der Rückgabewert des Validators bestimmt, was mit dem Feld als Nächstes passiert. Dafür gibt es drei Möglichkeiten:

Geänderter Rückgabewert

Ein geänderter oder anderer Wert, der dann zum neuen Wert des Felds wird. Diese Funktion wird häufig verwendet, um einen Wert zu bereinigen, z. B. um nachfolgende Leerzeichen zu entfernen.

Beispiel für einen Änderungsvalidator:

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

Null-Rückgabewert

Null, was bedeutet, dass der angegebene Wert ungültig ist. In den meisten Fällen wird der eingegebene Wert im Feld ignoriert. Das genaue Verhalten wird durch die doValueInvalid_-Funktion des Felds angegeben.

Beispiel für einen Nulling Validator:

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

Undefinierter Rückgabewert

„Undefined“ (oder keine Return-Anweisung) oder der Eingabewert, was bedeutet, dass der Eingabewert der neue Wert des Felds sein soll. Diese Arten von Validatoren fungieren in der Regel als Änderungs-Listener.

Beispiel für einen Listener-Validator:

// Log the new value to console.
var validator = function(newValue) {
  console.log(newValue);
};

Der Text, der angezeigt wird, entspricht nicht unbedingt dem Wert des Felds.

Wert von

Innerhalb eines Validators bezieht sich this auf das Feld, nicht auf den Block. Wenn Sie innerhalb eines Validators auf den Block zugreifen müssen, verwenden Sie die Funktion getSourceBlock. Sie können auch die Funktion bind verwenden, um den Kontext festzulegen, in dem der Validator aufgerufen wird.

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

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