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));
}
};
- Com 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);
}
};
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, '');
};
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;
};
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);
}
};