驗證工具

驗證工具是一種函式，可擷取欄位的新值，然後對其採取行動。這類欄位可讓您輕鬆自訂欄位。如此一來，您可以在欄位值變更、修改輸入，或限制系統接受的值時觸發功能。

以下是一些常見的例子：

  • 限製文字欄位僅接受字母。
  • 要求文字欄位不可空白。
  • 要求日期必須在未來。
  • 根據下拉式選單修改區塊的形狀。

驗證工具類型

驗證工具會在不同時間執行，視驗證工具的類型而定。

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

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

本機驗證工具是在欄位建構時定義。本機驗證工具會對傳送至欄位的所有值執行，但「傳遞給建構函式的值除外」。這表示廣告是在以下位置放送：

  • 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 內是指欄位，而非區塊。如需存取驗證工具中的區塊，請使用 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);
  }
};