Strumenti di convalida

Uno strumento di convalida è una funzione che acquisisce il nuovo valore nei campi e poi vi agisce. Rappresentano un modo semplice per personalizzare un campo. Ti consentono di attivare la funzionalità quando il valore di un campo cambia, modifica l'input o limita i valori accettabili.

Alcuni esempi comuni:

  • Limitare un campo di testo all'accettazione solo di lettere.
  • Richiedono che un campo di testo non sia vuoto.
  • Richiedere una data futura.
  • Modifica della forma di un blocco in base a un menu a discesa.

Tipi di convalidatori

Gli strumenti di convalida vengono eseguiti in momenti diversi a seconda del tipo di convalidatore.

Gli strumenti di convalida dei corsi fanno parte della definizione della classe di un tipo di campo e sono solitamente utilizzati per limitare il tipo di valore consentito dal campo (ad esempio, i campi numerici accettano solo caratteri numerici). Gli strumenti di convalida delle classi vengono eseguiti su tutti i valori passati al campo (incluso il valore trasmesso al costruttore).

Per ulteriori informazioni sugli strumenti di convalida delle classi, consulta la sezione Implementazione di uno strumento di convalida delle classi in Creazione di un campo personalizzato.

Gli strumenti di convalida locali vengono definiti al momento della creazione di un campo. Gli strumenti di convalida locali vengono eseguiti su tutti i valori trasferiti al campo, ad eccezione di quello trasmesso al costruttore. Ciò significa che vengono eseguiti su:

  • Valori contenuti nel file XML.
  • Valori passati a setValue.
  • Valori passati a setFieldValue.
  • Valori modificati dall'utente.

Gli strumenti di convalida delle classi vengono eseguiti prima degli strumenti di convalida locali perché fungono da gatekeeper. Si assicurano che il valore sia del tipo corretto prima di trasmetterlo.

Per ulteriori informazioni sulla sequenza di convalida dei valori e sui valori in generale, consulta Valori.

Registrazione di uno strumento di convalida locale

Gli strumenti di convalida locali possono essere registrati in due modi:

  • Aggiunta direttamente nel costruttore di un 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);
  }
};

Entrambi i metodi precedenti possono essere aggregati in un'estensione per supportare il formato JSON.

Il valore del campo può essere molto diverso a seconda del tipo di campo convalidato (ad esempio, un campo numerico memorizza un numero, mentre un campo di immissione di testo memorizza una stringa), quindi è meglio leggere la documentazione relativa al campo specifico prima di creare uno strumento di convalida.

Valori restituiti

Il valore restituito dallo strumento di convalida determina l'azione successiva del campo. Ci sono tre possibilità:

Valore restituito modificato

Un valore modificato o diverso, che diventa il nuovo valore del campo. Questo viene spesso utilizzato per ripulire un valore, ad esempio rimuovendo lo spazio vuoto finale.

Esempio di strumento di convalida della modifica:

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

Campo di immissione testo con strumento di convalida modificabile

Valore restituito null

Null, significa che il valore specificato non è valido. Nella maggior parte dei casi il campo ignora il valore di input. Il comportamento esatto è specificato dalla doValueInvalid_ funzione del campo.

Esempio di strumento di convalida del 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;
};

Campo di immissione testo con strumento di convalida dell'annullamento

Valore restituito non definito

Non definito (o nessuna istruzione restituita) o il valore di input, il che significa che il valore di input deve diventare il nuovo valore del campo. Questi tipi di convalidatori agiscono generalmente come listener di modifiche.

Esempio di strumento di convalida dei listener:

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

Nota ancora una volta che il testo visualizzato non riflette necessariamente il valore del campo.

Valore di questo

All'interno di uno strumento di convalida, il this si riferisce al campo, non al blocco. Se hai bisogno di accedere al blocco all'interno di uno strumento di convalida, utilizza la funzione getSourceBlock. Puoi anche utilizzare la funzione bind per impostare il contesto all'interno del quale viene chiamato lo strumento di convalida.

Codice di esempio che utilizza 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);
  }
};

Codice di esempio utilizzando 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);
  }
};