Validadores

Um validador é uma função que recebe o novo valor dos campos e age sobre ele. Eles são uma maneira simples de personalizar um campo. Eles permitem acionar funcionalidades quando o valor de um campo muda, modificar a entrada ou limitar quais valores são 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 o formato de um bloco com base em um menu suspenso.

Tipos de validadores

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

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, campos de número só aceitam 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 classe, consulte a seção Implementar um validador de classe em "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 ao campo , exceto o valor transmitido ao construtor. Isso significa que eles são executados em:

  • Valores contidos em XML.
  • Valores transmitidos para setValue.
  • Valores transmitidos para setFieldValue.
  • Valores mudados pelo usuário.

Os validadores de classe são executados antes dos validadores locais porque agem como porteiros. Eles garantem que o valor seja do tipo correto antes de transmiti-lo.

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

Registrar um validador local

Os validadores locais podem ser registrados de duas maneiras:

  • Adicionado diretamente no 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 encapsulado em 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. Por isso, é melhor ler a documentação do campo específico antes de criar um validador.

Valores de retorno

O valor de retorno do validador determina o que o campo faz em seguida. Há três possibilidades:

Valor de retorno modificado

Um valor modificado ou diferente, que se torna o novo valor do campo. Isso geralmente é usado para limpar um valor, como remover espaços em branco no final.

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 informado é 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 NullingValidator:

// 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 sem 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 atuam como listeners de mudança.

Exemplo de um ListenerValidator:

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

Observe mais uma vez como o texto de exibição não reflete necessariamente o valor do campo.

Valor de "this"

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. Você também pode 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);
  }
};