Validadores

Um validador é uma função que recebe o novo valor dos campos e, em seguida, age nele. Elas são uma maneira simples de personalizar um campo. Com eles, é possível acionar a funcionalidade quando o valor de um campo é alterado, modificar a entrada ou limitar os valores aceitáveis.

Alguns exemplos comuns:

  • Restringir um campo de texto para aceitar apenas letras.
  • Exigir que um campo de texto não esteja vazio.
  • Exigir que uma data seja no futuro.
  • Modificar a forma de um bloco com base em uma lista suspensa.

Tipos de validadores

Os validadores são executados em momentos diferentes, dependendo do tipo de validador.

Os validadores de classe fazem parte da definição de classe de um tipo de campo e geralmente são usados para restringir o tipo de valor permitido pelo campo (por exemplo, os campos "number" aceitam apenas caracteres numéricos). Os validadores de classe são executados em todos os valores transmitidos ao campo (incluindo o valor transmitido ao construtor).

Para mais informações sobre validadores de classes, consulte a seção Como implementar um validador de classe em Como criar um campo personalizado.

Os validadores locais são definidos no momento da construção de um campo. Os validadores locais são executados em todos os valores transmitidos para o campo, exceto o valor transmitido ao construtor. Isso significa que eles são executados em:

  • Valores contidos em XML.
  • Valores passados para setValue.
  • Valores passados para setFieldValue.
  • Valores alterados pelo usuário.

Os validadores de classe são executados antes dos validadores locais porque agem como controladores. Eles garantem que o valor seja do tipo correto antes da transmissão.

Para mais informações sobre a sequência de validação de valor e valores em geral, consulte Valores.

Como registrar um validador local

Os validadores locais podem ser registrados de duas maneiras:

  • Adicionado diretamente ao construtor de um campo.
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);
  }
};

Qualquer um dos métodos acima pode ser unido a uma extensão para oferecer suporte ao formato JSON.

O valor do campo pode ser muito diferente dependendo do tipo de campo que está sendo validado (por exemplo, um campo numérico armazena um número, enquanto um campo de entrada de texto armazena uma string). Portanto, é melhor ler a documentação do seu campo específico antes de criar um validador.

Valores de retorno

O valor de retorno do validador determina o que o campo faz a seguir. Existem três possibilidades:

Valor de retorno modificado

Um valor modificado ou diferente, que então se torna o novo valor do campo. Isso é frequentemente usado para limpar um valor, por exemplo, removendo o espaço em branco à direita.

Exemplo de um validador de modificação:

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

Campo de entrada de texto com um validador de modificação

Valor de retorno nulo

Nulo, o que significa que o valor fornecido é inválido. Na maioria dos casos, o campo ignora o valor de entrada. O comportamento exato é especificado pela função doValueInvalid_ do campo.

Exemplo de um validador de nulidade:

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

Campo de entrada de texto com um validador de anulação

Valor de retorno indefinido

Indefinido (ou nenhuma instrução de retorno) ou o valor de entrada, o que significa que o valor de entrada deve se tornar o novo valor do campo. Esses tipos de validadores geralmente funcionam como listeners de mudanças.

Exemplo de um validador de listener:

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

Mais uma vez, observe como o text de exibição não reflete necessariamente o value do campo.

Valor deste

Dentro de um validador, this se refere ao campo, não ao bloco. Se você precisar acessar o bloco dentro de um validador, use a função getSourceBlock. Também é possível usar a função bind para definir o contexto em que o validador é chamado.

Exemplo de código usando 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);
  }
};

Exemplo de código usando 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);
  }
};