Walidatory

Walidator to funkcja, która przyjmuje nowe wartości pól, a następnie wykonuje na nich działania. To prosty sposób na dostosowanie pola. Umożliwiają one wywoływanie funkcji, gdy zmienia się wartość pola, modyfikowanie danych wejściowych lub ograniczanie dopuszczalnych wartości.

Oto kilka typowych przykładówSome common examples:

  • Ograniczanie pola tekstowego do akceptowania tylko liter.
  • Wymaganie, aby pole tekstowe nie było puste.
  • wymaganie, aby data przypadała w przyszłości;
  • Modyfikowanie kształtu bloku na podstawie menu.

Rodzaje weryfikatorów

Walidatory są uruchamiane w różnych momentach w zależności od ich rodzaju.

Walidatory klas są częścią definicji klasy typu pola i są zwykle używane do ograniczania typu wartości dozwolonych w polu (np. pola liczbowe akceptują tylko znaki numeryczne). Walidatory klas są uruchamiane dla wszystkich wartości przekazywanych do pola (w tym wartości przekazywanej do konstruktora).

Więcej informacji o walidatorach klas znajdziesz w sekcji Implementowanie walidatora klasy w artykule Tworzenie pola niestandardowego.

Lokalne narzędzia sprawdzające są definiowane w momencie tworzenia pola. Lokalne walidatory są uruchamiane dla wszystkich wartości przekazywanych do pola z wyjątkiem wartości przekazywanej do konstruktora. Oznacza to, że działają one na:

  • wartości zawarte w XML,
  • Wartości przekazywane do setValue.
  • Wartości przekazywane do setFieldValue.
  • Wartości zmienione przez użytkownika.

Walidatory klas są uruchamiane przed walidatorami lokalnymi, ponieważ działają jak strażnicy. Sprawdzają, czy wartość jest odpowiedniego typu, zanim ją przekażą.

Więcej informacji o kolejności weryfikacji wartości i wartościach w ogóle znajdziesz w sekcji Wartości.

Rejestrowanie lokalnego weryfikatora

Lokalnych weryfikatorów można zarejestrować na 2 sposoby:

  • Dodawane bezpośrednio w konstruktorze pola.
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);
  }
};

Każdą z powyższych metod można umieścić w rozszerzeniu, aby obsługiwać format JSON.

Wartość pola może się znacznie różnić w zależności od typu sprawdzanego pola (np. pole liczbowe będzie przechowywać liczbę, a pole wprowadzania tekstu – ciąg znaków), dlatego przed utworzeniem narzędzia do sprawdzania poprawności warto zapoznać się z dokumentacją dotyczącą konkretnego pola.

Wartości zwracane

Wartość zwracana przez mechanizm weryfikacji określa, co dalej robi pole. Istnieją 3 możliwości:

Zmodyfikowana zwracana wartość

Zmodyfikowana lub inna wartość, która staje się nową wartością pola. Jest to często używane do oczyszczania wartości, np. przez usuwanie końcowych białych znaków.

Przykład walidatora modyfikującego:

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

Pole tekstowe ze sprawdzaniem modyfikującym

Wartość zwracana null

Wartość null, co oznacza, że podana wartość jest nieprawidłowa. W większości przypadków pole zignoruje wartość wejściową. Dokładne działanie jest określone przez doValueInvalid_ funkcję pola.

Przykład weryfikatora zerowania:

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

Pole tekstowe z walidatorem zerującym

Nieokreślona zwracana wartość

Niezdefiniowana (lub brak instrukcji return) lub wartość wejściowa, co oznacza, że wartość wejściowa powinna stać się nową wartością pola. Tego typu walidatory zwykle działają jako odbiorniki zmian.

Przykład weryfikatora odbiorcy:

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

Zwróć uwagę, że tekst wyświetlany niekoniecznie odzwierciedla wartość pola.

Wartość tego

W walidatorze this odnosi się do pola, a nie do bloku. Jeśli musisz uzyskać dostęp do bloku w walidatorze, użyj funkcji getSourceBlock. Możesz też użyć funkcji bind, aby ustawić kontekst, w którym wywoływany jest walidator.

Przykładowy kod z użyciem 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);
  }
};

Przykładowy kod z użyciem elementu 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);
  }
};