Trình xác thực

Trình xác thực là một hàm nhận giá trị mới của các trường, sau đó hoạt động trên các trường nó. Đây là một cách đơn giản để tuỳ chỉnh một trường. Chúng cho phép bạn kích hoạt chức năng khi giá trị của trường thay đổi, sửa đổi giá trị đầu vào hoặc giới hạn các giá trị có thể chấp nhận được.

Một số ví dụ phổ biến:

  • Giới hạn trường văn bản để chỉ chấp nhận chữ cái.
  • Yêu cầu trường văn bản không được để trống.
  • Yêu cầu một ngày trong tương lai.
  • Sửa đổi hình dạng của khối dựa trên trình đơn thả xuống.

Các loại trình xác thực

Các trình xác thực sẽ thực thi vào các thời điểm khác nhau tuỳ thuộc vào loại trình xác thực là thế nào.

Trình xác thực lớp là một phần trong định nghĩa lớp của một loại trường và thường dùng để hạn chế loại giá trị mà trường cho phép (ví dụ: số chỉ chấp nhận ký tự số). Trình xác thực lớp chạy trên tất cả các giá trị được truyền đến trường này (bao gồm giá trị được truyền đến hàm khởi tạo).

Để biết thêm thông tin về trình xác thực lớp, hãy xem Triển khai trình xác thực lớp trong Tạo trường tùy chỉnh.

Trình xác thực cục bộ được xác định tại thời điểm xây dựng một trường. Chiến dịch Địa phương trình xác thực chạy trên tất cả các giá trị được chuyển đến trường ngoại trừ giá trị được chuyển đến hàm khởi tạo. Tức là các chiến dịch này chạy trên:

  • Các giá trị có trong XML.
  • Các giá trị được truyền vào setValue.
  • Các giá trị được chuyển vào setFieldValue.
  • Các giá trị do người dùng thay đổi.

Trình xác thực lớp sẽ chạy trước trình xác thực cục bộ vì các trình này hoạt động giống như "người gác cổng". Các phương thức này đảm bảo rằng giá trị thuộc đúng loại trước khi truyền tính năng đó trên thiết bị.

Để biết thêm thông tin về trình tự xác thực giá trị và các giá trị trong hãy xem phần Giá trị chung.

Đăng ký trình xác thực cục bộ

Bạn có thể đăng ký trình xác thực cục bộ theo hai cách:

  • Được thêm trực tiếp vào hàm khởi tạo của một trường.
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);
  }
};

Một trong hai phương pháp trên có thể được gói trong một tiện ích, để hỗ trợ định dạng JSON.

Giá trị của trường có thể rất khác nhau tuỳ thuộc vào loại trường đang đã được xác thực (ví dụ: trường số sẽ lưu trữ số, trong khi trường nhập dữ liệu văn bản sẽ lưu trữ một chuỗi), do đó tốt nhất bạn nên đọc tài liệu dành cho trước khi tạo trình xác thực.

Giá trị trả về

Giá trị trả về của trình xác thực xác định hoạt động tiếp theo của trường này. Có là ba khả năng:

Giá trị trả về đã sửa đổi

Giá trị được sửa đổi hoặc khác, sau đó trở thành giá trị mới của trường. Hàm này thường được dùng để dọn dẹp một giá trị, chẳng hạn như bằng cách xoá phần tử theo dõi khoảng trắng.

Ví dụ về trình xác thực việc sửa đổi:

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

Trường nhập văn bản có trình xác thực sửa đổi

Giá trị trả về giá trị rỗng

Null, nghĩa là giá trị đã cho không hợp lệ. Trong hầu hết các trường hợp, trường này sẽ bỏ qua giá trị nhập. Hành vi chính xác được chỉ định bởi doValueInvalid_ hàm.

Ví dụ về trình xác thực giá trị rỗng:

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

Trường nhập văn bản có trình xác thực giá trị rỗng

Giá trị trả về không xác định

Giá trị không được xác định (hoặc không có câu lệnh trả về) hoặc giá trị đầu vào, có nghĩa là giá trị đầu vào sẽ trở thành giá trị mới của trường. Các loại trình xác thực này thường đóng vai trò là trình nghe thay đổi.

Ví dụ về Trình xác thực trình nghe:

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

Hãy lưu ý một lần nữa rằng văn bản hiển thị không nhất thiết phải phản ánh giá trị.

Giá trị của chỉ số này

Bên trong trình xác thực this đề cập đến trường chứ không phải khối. Nếu bạn cần để truy cập vào khối bên trong trình xác thực, hãy dùng hàm getSourceBlock. Bạn có thể cũng sử dụng hàm liên kết để đặt ngữ cảnh trong đó trình xác thực được gọi.

Mã mẫu sử dụng 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);
  }
};

Mã mẫu sử dụng liên kết:

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