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 trường, sau đó tác động lên giá trị đó. Đây là 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 một trường thay đổi, sửa đổi dữ liệu đầu vào hoặc giới hạn những giá trị được chấp nhận.

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

• Hạn chế 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 ngày phải là ngày trong tương lai.
• Sửa đổi hình dạng của một khối dựa trên trình đơn thả xuống.

Lưu ý: Trình xác thực sửa đổi giá trị của một trường chứ không phải văn bản của trường đó.

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

Trình xác thực sẽ thực thi vào những thời điểm khác nhau, tuỳ thuộc vào loại trình xác thực.

Trình xác thực lớp là một phần trong định nghĩa lớp của kiểu trường và thường được dùng để hạn chế kiểu giá trị mà trường cho phép (ví dụ: các trường số chỉ chấp nhận ký tự số). Trình xác thực lớp được chạy trên tất cả các giá trị được truyền đến trường (bao gồm cả 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 phần Triển khai trình xác thực lớp trong bài viết Tạo trường tuỳ chỉnh.

Trình xác thực cục bộ được xác định tại thời điểm tạo một trường. Trình xác thực cục bộ chạy trên tất cả các giá trị được truyền đến trường ngoại trừ giá trị được truyền đến hàm khởi tạo. Điều này có nghĩa là các ứng dụng này chạy trên:

• Các giá trị có trong XML.
• Giá trị được truyền đến setValue.
• Giá trị được truyền đến setFieldValue.
• Giá trị do người dùng thay đổi.

Trình xác thực lớp được chạy trước trình xác thực cục bộ vì chúng hoạt động như người gác cổng. Chúng đảm bảo rằng giá trị thuộc đúng loại trước khi truyền giá trị đó.

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

Đă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.

Lưu ý: Chữ ký của hàm khởi tạo trường có thể khác nhau tuỳ thuộc vào loại 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));
  }
};

• Với setValidator.

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

Bạn có thể gói một trong hai phương thức trên 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ữ một số, trong khi trường nhập văn bản sẽ lưu trữ một chuỗi). Vì vậy, tốt nhất là bạn nên đọc tài liệu cho trường cụ thể của mình trước khi tạo trình xác thực.

Lưu ý: Chỉ những trường có thể chỉnh sửa mới chấp nhận trình xác thực, vì vậy, hãy nhớ kiểm tra tài liệu của trường cụ thể.

Giá trị trả về

Giá trị trả về của trình xác thực sẽ xác định hành động tiếp theo của trường. Có 3 trường hợp có thể xảy ra:

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

Một giá trị đã được sửa đổi hoặc khác, sau đó trở thành giá trị mới của trường. Thao tác này thường được dùng để làm sạch một giá trị, chẳng hạn như bằng cách xoá khoảng trắng ở cuối.

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

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

Giá trị trả về rỗng

Null, tức 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ị đầu vào. Hành vi chính xác được chỉ định bằng doValueInvalid_ function của trường.

Ví dụ về Trình xác thực vô hiệu hoá:

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

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

Không 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);
};

Xin 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ị của trường.

Giá trị của

Bên trong trình xác thực, this đề cập đến trường chứ không phải khối. Nếu cần truy cập vào khối bên trong một trình xác thực, hãy sử dụng hàm getSourceBlock. Bạn cũng có thể dùng hàm bind để đặt ngữ cảnh mà 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 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);
  }
};