驗證工具

驗證器是一種函式，可接收欄位的新值，然後對其採取動作。這是一種簡單的自訂欄位方式。這些事件可讓您在欄位值變更、修改輸入內容或限制可接受的值時觸發功能。

以下是一些常見的例子：

  • 限制文字欄位只接受字母。
  • 要求文字欄位不得留空。
  • 要求日期必須是未來的日期。
  • 根據下拉式選單修改區塊形狀。

驗證器類型

驗證器的執行時間會因驗證器類型而異。

類別驗證器是欄位類型的類別定義的一部分，通常用於限制欄位允許的值類型 (例如數字欄位只接受數字字元)。系統會針對傳遞至欄位的所有值 (包括傳遞至建構函式的值) 執行類別驗證工具。

如要進一步瞭解類別驗證工具，請參閱「建立自訂欄位」中的「實作類別驗證工具」一節。

本機驗證器是在欄位建構時定義。當值傳遞至欄位時，系統會執行本機驗證工具，但傳遞至建構函式的值除外。也就是說，這些程式會在以下裝置上執行：

  • XML 中包含的值。
  • 傳遞至 setValue 的值。
  • 傳遞至 setFieldValue 的值。
  • 使用者變更的值。

類別驗證工具會在本機驗證工具之前執行，因為它們會扮演守門員的角色。在傳遞值之前，會先確認值的類型是否正確。

如要進一步瞭解值驗證的順序，以及一般值的相關資訊，請參閱「值」。

註冊本機驗證工具

您可以透過下列兩種方式註冊本機驗證器：

  • 直接在欄位的建構函式中新增。
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);
  }
};

上述任一方法都可以包裝在擴充功能中，以支援 JSON 格式。

欄位的值可能會因要驗證的欄位類型而有很大差異 (例如數值欄位會儲存數字，而文字輸入欄位會儲存字串)，因此建議您在建立驗證器之前，先閱讀特定欄位的說明文件。

傳回值

驗證工具的傳回值會決定欄位接下來要執行的動作。有三種可能：

修改的傳回值

經過修改或不同的值，這會成為欄位的新值。這項功能通常用於清理值，例如移除結尾的空白字元。

修改驗證器的範例：

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

含修改驗證器的文字輸入欄位

空值傳回值

空值，表示指定的值無效。在大多數情況下，欄位會忽略輸入值。欄位的 doValueInvalid_ 函式會指定確切的行為。

空值驗證器範例：

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

含有空值驗證工具的文字輸入欄位

未定義的傳回值

未定義 (或沒有傳回陳述式) 或輸入值，這表示輸入值應成為欄位的新值。這類驗證工具通常會充當變更事件監聽器。

事件監聽器驗證器範例：

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

請再次注意，顯示的文字不一定會反映欄位的值。

this 的值

在驗證器內部，this 是指欄位，而非區塊。如果您需要存取驗證器內的區塊，請使用 getSourceBlock 函式。您也可以使用 bind 函式，設定呼叫驗證工具的內容。

使用 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);
  }
};

使用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);
  }
};