Walidatory

Walidator to funkcja, która pobiera w polach nową wartość, a potem wykonuje na niej działania. Jest to prosty sposób na dostosowanie pola. Pozwalają aktywować funkcje, gdy zmieni się wartość pola, zmodyfikować dane wejściowe lub ograniczyć dopuszczalne wartości.

Oto kilka typowych przykładówSome common examples:

  • Ograniczenie akceptowania tylko liter w polu tekstowym.
  • Wymóg, aby pole tekstowe nie było puste.
  • Wymaganie, aby data była w przyszłości.
  • Modyfikowanie kształtu bryły za pomocą menu.

Rodzaje walidatorów

Walidatory uruchamiają się w różnym czasie w zależności od jego rodzaju.

Walidatory klas wchodzą w skład definicji klasy typu pola i zwykle służą do ograniczania typu wartości dopuszczalnej w danym polu (np. w polach liczbowych akceptowane są tylko znaki liczbowe). Walidatory klas są uruchamiane w przypadku wszystkich wartości przekazywanych w polu (w tym wartości przekazanej do konstruktora).

Więcej informacji o walidatorach klas znajdziesz w sekcji Implementowanie walidatora klas artykułu Tworzenie pola niestandardowego.

Lokalne walidatory są definiowane w czasie tworzenia pola. Lokalne walidatory uruchamiają się na wszystkich wartościach przekazywanych do pola z wyjątkiem wartości przekazanej do konstruktora. Oznacza to, że wyświetlają się:

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

Walidatory klas są uruchamiane przed lokalnymi walidatorami, ponieważ działają jak weryfikatorzy. Przed przekazaniem wartości upewniają się, że wartość jest prawidłowego typu.

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

Rejestrowanie lokalnego walidatora

Lokalne walidatory mogą być rejestrowane na 2 sposoby:

  • Dodano 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 tych metod możesz dodać do rozszerzenia na potrzeby obsługi formatu JSON.

Wartość tego pola może się różnić w zależności od typu weryfikowanego pola (np.pole liczbowe będzie zawierać liczbę, a pole tekstowe będzie zawierać ciąg znaków). Dlatego przed utworzeniem walidatora zalecamy zapoznanie się z dokumentacją konkretnego pola.

Zwracane wartości

Wartość zwracana przez walidator określa dalsze działania pola. Są 3 możliwości:

Zmodyfikowana zwracana wartość

Zmodyfikowana lub inna wartość, która następnie staje się nową wartością pola. Jest to często używane do czyszczenia wartości, na przykład przez usunięcie końcowej spacji.

Przykład walidatora modyfikacji:

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

Pole do wprowadzania tekstu z walidatorem modyfikującym

Zwracana wartość bez wartości

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

Przykład walidatora wartości 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;
};

Pole do wprowadzania tekstu z walidatorem wartości null

Nieokreślona wartość zwracana

Niezdefiniowana (lub brak instrukcji zwracającej) lub wartość wejściowa, która oznacza, że wartość wejściowa powinna zostać nową wartością pola. Walidatory tego typu działają zwykle jak detektory zmian.

Przykład walidatora słuchaczy:

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

Zwróć uwagę ponownie, że wyświetlany tekst nie musi odzwierciedlać wartości pola.

Wartość tego

Wewnątrz walidatora this odnosi się do pola, a nie do bloku. Aby 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 przy użyciu dodatku 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 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);
  }
};