驗證工具

驗證器是一種函式，可接收欄位新值，然後對其執行動作。可輕鬆自訂欄位。您可以使用這些函式，在欄位值變更時觸發功能、修改輸入內容，或限制可接受的值。

以下是一些常見的例子：

  • 將文字欄位限制為只能接受字母。
  • 規定文字欄位不得為空。
  • 要求日期必須在未來。
  • 根據下拉式選單修改方塊形狀。

驗證器類型

驗證器會根據類型在不同時間執行。

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

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

本機驗證器是在建構欄位時定義，本機驗證器會對傳遞至欄位的所有值執行驗證，但傳遞至建構函式的值除外。也就是說，這些應用程式會在下列裝置上執行：

  • 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_ 函式指定。

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

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

未定義的傳回值

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

事件監聽器驗證器範例：

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

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

這個值

驗證器 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);
  }
};